OpenPencil CLI 文档检查实战：info、tree、find、query、node、lint 等全部读取命令详解

前端桌面应用AI 应用MCP 服务【免费下载链接】open-pencilAI-native design editor. Open-source Figma alternative.项目地址https://gitcode.com/gh_mirrors/op/open-pencil点击查看免费下载OpenPencil 是一个 AI 原生的开源设计编辑器Figma 的替代品其官方 CLIopen-pencil/cli允许开发者在不打开编辑器的情况下直接读取、检查.fig与.pen设计文档。本文以官方文档 packages/docs/de/programmable/cli/inspecting.md 为主线结合 packages/cli/src 的真实源码实现完整讲解文档信息、文档树、对象查找、XPath 查询、页面与变量、运行中文档定位以及 lint 质量检查等全部检查类命令并附带每个命令的参数细节、默认值与底层原理让你读完即可把这些命令接入脚本与 CI 流水线。CLI 安装与两种运行模式CLI 包名为open-pencil/cli可通过 npm 或 bun 全局安装npm install -g open-pencil/cli # 或 bun add -g open-pencil/cli安装后可执行openpencil命令。从 packages/cli/src/index.ts 可以看到命令入口基于citty框架注册了 17 个子命令analyze、convert、documents、eval、export、find、formats、fonts、import、info、lint、libraries、query、node、pages、selection、tree、variables。本文聚焦其中的读取与检查类命令。所有检查命令都支持两种运行模式这一点由 packages/cli/src/rpc-data.ts 中的loadRPCData统一调度文件模式无头模式传入文件路径如design.figCLI 直接读取磁盘上的设计文档并本地执行查询无需打开编辑器应用模式RPC 模式省略文件参数CLI 通过 RPC 连接正在运行的桌面应用对当前打开或指定的文档执行同样的查询。# 文件模式直接读取 design.fig openpencil info design.fig # 应用模式对当前打开的文档执行 openpencil info应用模式底层通过 MCP discovery 文件定位运行中的应用优先走 Unix socket必要时回退到127.0.0.1的 HTTP 端口并携带 Bearer 令牌鉴权单次 RPC 请求超时 30 秒见 packages/cli/src/app-client.ts。若应用未运行会提示“Could not read MCP discovery file / Is the app running?”。文档信息openpencil infoopenpencil info design.fig该命令输出文档的页面数、对象数量、使用的字体以及文件大小等概览信息。其实现位于 packages/cli/src/commands/info.ts核心输出结构为首行概览pages pages, totalNodes nodes每页节点数直方图pageCounts字段单位 nodes节点类型汇总如 FRAME、TEXT、RECTANGLE 等各类对象数量分布字体列表Fonts: font1, font2, ...。配合--json可拿到结构化结果openpencil info design.fig --json输出包含pages、totalNodes、pageCounts、types、fonts等字段方便脚本二次加工。文档树与对象搜索打印文档树openpencil treeopenpencil tree design.fig以树形结构打印文档的节点层级。实现位于 packages/cli/src/commands/tree.ts它额外支持两个参数参数说明默认值--page 名称只打印指定页面按页面名称匹配第一页--depth 数字限制树的最大深度不限制Infinity# 只查看第一页的树 openpencil tree design.fig --page Desktop # 限制深度为 2 层避免超大文档刷屏 openpencil tree design.fig --depth 2树形输出使用agentfmt渲染每个节点显示“类型 名称 (id)”例如FRAME Header (1:2)。按名称或类型搜索openpencil findopenpencil find design.fig --type TEXT openpencil find design.fig --name Buttonfind命令见 packages/cli/src/commands/find.ts提供以下选项参数说明默认值--name 字符串按节点名称搜索部分匹配、不区分大小写无全部--type 类型按节点类型过滤如FRAME、TEXT、RECTANGLE、INSTANCE等无全部--page 名称限定搜索页面按名称所有页面--limit 数字最大返回条数100两个条件可组合使用例如找出所有名为 Button 的文本节点openpencil find design.fig --type TEXT --name ButtonXPath 查询openpencil queryquery命令用 XPath 选择器对文档做更灵活的结构化查询定位能力远超findopenpencil query design.fig //FRAME openpencil query design.fig //TEXT[fontSize 24] openpencil query design.fig //*[visible false]实现位于 packages/cli/src/commands/query.tsselector 为必填位置参数。源码示例还展示了数值比较与函数用法# 宽度小于 300 的 FRAME openpencil query design.fig //FRAME[width 300] # 名称包含 Label 的文本节点 openpencil query design.fig //TEXT[contains(name, \Label\)]XPath 属性名与 API 保持一致fontSize、layoutMode、strokeWeight等属性在 XPath 中书写时不加前缀、不改名与 OpenPencil 文档对象模型DOM的 API 字段一一对应学习成本低。query同样支持--page默认所有页面与--limit默认 1000比find更宽松适合批量抓取。文本模式下结果会显示每个节点的名称与尺寸宽×高加--json则输出完整匹配节点数组。对象详情、页面与变量按 ID 查看对象openpencil nodeopenpencil node design.fig --id 1:23node命令packages/cli/src/commands/node.ts的--id为必填项打印指定节点的详细属性。它输出的字段相当丰富包括基础属性type、name、id、width、height、x、y父节点parent (name (id))文本内容text、字体font格式为fontSizepx fontFamily填充色SOLID 可见填充会通过colorToHex转换为十六进制色值若透明度小于 1 还会追加百分比如#1F6FEB 80%圆角半径radius、旋转角度rotate、整体透明度opacity隐藏visible: false、锁定locked: true、子节点数量children布局模式layoutNONE时省略其余转小写变量绑定boundVariables中以var:field形式列出绑定到设计变量的属性及对应变量名。加--json可拿到包含上述全部字段的原始数据对象。列出页面openpencil pagesopenpencil pages design.fig输出文档中所有页面每页显示名称、ID 与节点数见 packages/cli/src/commands/pages.ts。--json返回PageItem[]包含name、id、nodes字段。查看变量与集合openpencil variablesopenpencil variables design.fig设计变量Variables是 OpenPencil 中跨对象复用设计令牌的机制。variables命令packages/cli/src/commands/variables.ts按**集合collection**分组打印每个集合显示其模式modes与内部变量名、取值、类型。支持两个过滤参数参数说明--collection 名称只显示指定集合--type 类型按变量类型过滤COLOR、FLOAT、STRING、BOOLEAN# 只查看颜色类变量 openpencil variables design.fig --type COLOR # 只看某个集合 openpencil variables design.fig --collection Brand末尾会汇总variables与collections总数若文档无变量则输出No variables found.。检查运行中的文档openpencil documents当桌面应用正在运行时可以不传文件路径直接与打开的文档交互。首先列出应用当前打开的所有文档openpencil documents该命令packages/cli/src/commands/documents.ts通过 RPC 调用list_documents输出每个文档的名称、ID、是否激活[active]标记、文件路径如有、当前页面名称与 ID、以及全部页面列表末尾还会提示可用的定位参数--document-id id --page-id id。对某个打开的文档执行查询时用--document-id与--page-id显式定位openpencil tree --document-id tab-123 --page-id 0:1这两个参数在 packages/cli/src/app-target.ts 中统一定义tree、find、query、node、pages、variables等命令均可接受。自动化流程的最佳实践官方文档明确建议先调用openpencil documents --json获取文档 ID 列表再显式传入--document-id与--page-id避免依赖“当前激活文档”这类隐式状态保证脚本可重复、可预期# 第一步拿到所有打开文档的 JSON openpencil documents --json # 第二步针对具体文档与页面执行查询 openpencil tree --document-id tab-123 --page-id 0:1 --json质量检查openpencil lint检查命令的最后一项是设计质量与可访问性检查openpencil lint design.fig openpencil lint design.pen --preset strict openpencil lint design.fig --rule color-contrastlintpackages/cli/src/commands/lint.ts用于扫描设计文档的一致性、结构性与可访问性问题参数如下参数说明默认值--preset 名称规则预设recommended--rule 规则ID只运行指定规则可重复指定无全部--list-rules列出全部可用规则与预设并退出—--json输出结构化结果false三个预设由 packages/core/src/lint/presets.ts 定义并导出recommended、strict、accessibility。从源码看color-contrast颜色对比度在recommended中即为 error 级别strict会把 recommended 中非color-contrast的规则全部升级为warning并保持对比度规则为 erroraccessibility则面向可访问性场景。预设的合并逻辑位于 packages/core/src/lint/linter.ts先按预设取规则集再叠加--rule指定的规则。规则的完整清单可以运行时查看openpencil lint design.fig --list-rules会列出每个规则 ID、所属类别与描述以及可用预设名。规则注册表见 packages/core/src/lint/rules/index.ts例如color-contrast的实现位于 packages/core/src/lint/rules/color-contrast.ts。lint 输出按error/warn/info三种严重级别分组每条消息包含规则 ID、节点路径nodePath、节点名称与 ID、具体描述以及可选的修复建议suggest。最终汇总形如Lint issues: 3 errors, 5 warnings, 2 info值得注意的 CI 语义当存在任何 error 级别问题时lint命令会以退出码 1 结束见 lint.ts 的process.exit(1)因此可以直接作为 CI 门禁使用# CI 中失败即中断 openpencil lint design.fig --preset strict --json底层实现无头加载与按需填充了解 CLI 背后的执行链路有助于判断命令在不同文档规模下的行为。以文件模式为例packages/cli/src/headless.ts 完成了三件事用IORegistry(BUILTIN_IO_FORMATS)读取文档字节并还原为SceneGraph.fig、.pen等内置格式均由 packages/core/src/io 的BUILTIN_IO_FORMATS注册读取后调用computeAllLayouts(graph)计算全部布局packages/core/src/layout保证查询时拿到的宽高、位置等布局属性是最终值按命令类型决定懒加载填充范围prepareDocumentForRPC命令填充策略pages/variables不填充直接读取元数据tree仅填充请求的页面默认第一页populateLazyFigImportRootsfind/query指定--page时只填充该页否则填充整个文档其余命令填充整个文档populateAllLazyFigImportRoots这个设计对.fig这类可能带懒加载导入节点的格式很重要树、搜索、查询默认只物化必要页面避免在大文档上做无谓的全量展开而node这类需要任意对象精确属性的命令则全量物化以保证正确性。填充发生变化后会重新计算布局computeAllLayouts(graph, pageId)。RPC 应用模式则复用同一套命令分发loadRPCData在未传文件时改为调用rpc(command, args)packages/cli/src/app-client.ts并把--document-id/--page-id映射为 RPC 的document_id/page_id参数两套模式对外命令完全一致脚本可以无缝切换。小结检查命令一览命令作用关键参数info文档概览页面、节点数、类型、字体、文件大小--jsontree打印节点树--page、--depth、--jsonfind按名称/类型搜索节点--name、--type、--page、--limit(100)、--jsonqueryXPath 结构化查询必填 selector、--page、--limit(1000)、--jsonnode按 ID 查看对象详情必填--id、--jsonpages列出页面--jsonvariables列出变量与集合--collection、--type、--jsondocuments列出应用打开的文档--jsonlint质量与可访问性检查--preset、--rule、--list-rules、--json所有命令都支持--json且均可在“文件模式”与“连接运行中应用”两种形态下使用配合documents --json定位具体文档、lint的非零退出码门禁足以支撑从日常巡检到 CI 自动化的完整设计文档检查流程。完整命令注册可查阅 packages/cli/src/index.tsCLI 参考总览见 packages/docs/reference/cli.md。赞分享前端桌面应用AI 应用MCP 服务【免费下载链接】open-pencilAI-native design editor. Open-source Figma alternative.项目地址https://gitcode.com/gh_mirrors/op/open-pencil点击查看免费下载相关推荐终极Node-Redis监控命令完整指南掌握INFO与MONITOR工具轻松优化Redis性能终极Node Redis监控命令完整指南掌握INFO与MONITOR工具轻松优化Redis性能 Node Redis作为Redis官方推荐的Node.js客户后端数据库客户端缓存Hydra 命令行标志完全指南掌握 --cfg、--multirun、--info 等全部 CLI 参数Hydra 命令行标志完全指南掌握 cfg、 multirun、 info 等全部 CLI 参数 本指南围绕 Hydra 框架中用命令行控制 Hydra 本开发工具后端CLIRye lint 命令详解基于 Ruff 的 Python 项目代码检查实战Rye lint 命令详解基于 Ruff 的 Python 项目代码检查实战 rye lint 是 Rye 提供的统一代码检查入口它屏蔽了底层工具差异直接开发工具CLI上一篇网络安全实战使用DedSec Project的10个网络工具进行渗透测试下一篇gh_mirrors/er/errors性能分析报告优化建议与实施步骤创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考