企业官网建设流程全解析

• 前端
• 桌面应用
• AI 应用
• MCP 服务

OpenPencil 是一个 AI 原生的开源设计编辑器（Figma 的替代品），其官方 CLI（@open-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.fig），CLI 直接读取磁盘上的设计文档并本地执行查询，无需打开编辑器；
• 应用模式（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 info

openpencil 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 tree

openpencil tree design.fig

以树形结构打印文档的节点层级。实现位于 packages/cli/src/commands/tree.ts，它额外支持两个参数：

# 只查看第一页的树 openpencil tree design.fig --page "Desktop" # 限制深度为 2 层，避免超大文档刷屏 openpencil tree design.fig --depth 2

树形输出使用agentfmt渲染，每个节点显示“类型 名称 (id)”，例如FRAME Header (1:2)。

按名称或类型搜索：openpencil find

openpencil find design.fig --type TEXT openpencil find design.fig --name "Button"

find命令（见 packages/cli/src/commands/find.ts）提供以下选项：

两个条件可组合使用，例如找出所有名为 Button 的文本节点：

openpencil find design.fig --type TEXT --name "Button"

XPath 查询：openpencil query

query命令用 XPath 选择器对文档做更灵活的结构化查询，定位能力远超find：

openpencil query design.fig "//FRAME" openpencil query design.fig "//TEXT[@fontSize >= 24]" openpencil query design.fig "//*[@visible = false]"

实现位于 packages/cli/src/commands/query.ts，selector 为必填位置参数。源码示例还展示了数值比较与函数用法：

# 宽度小于 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 node

openpencil node design.fig --id 1:23

node命令（packages/cli/src/commands/node.ts）的--id为必填项，打印指定节点的详细属性。它输出的字段相当丰富，包括：

• 基础属性：type、name、id、width、height、x、y；
• 父节点：parent (name (id))；
• 文本内容（text）、字体（font，格式为<fontSize>px <fontFamily>）；
• 填充色：SOLID 可见填充会通过colorToHex转换为十六进制色值，若透明度小于 1 还会追加百分比，如#1F6FEB 80%；
• 圆角半径（radius）、旋转角度（rotate）、整体透明度（opacity）；
• 隐藏（visible: false）、锁定（locked: true）、子节点数量（children）；
• 布局模式（layout，NONE时省略，其余转小写）；
• 变量绑定：boundVariables中以var:<field>形式列出绑定到设计变量的属性及对应变量名。

加--json可拿到包含上述全部字段的原始数据对象。

列出页面：openpencil pages

openpencil pages design.fig

输出文档中所有页面，每页显示名称、ID 与节点数（见 packages/cli/src/commands/pages.ts）。--json返回PageItem[]，包含name、id、nodes字段。

查看变量与集合：openpencil variables

openpencil variables design.fig

设计变量（Variables）是 OpenPencil 中跨对象复用设计令牌的机制。variables命令（packages/cli/src/commands/variables.ts）按**集合（collection）**分组打印，每个集合显示其模式（modes）与内部变量名、取值、类型。支持两个过滤参数：

# 只查看颜色类变量 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-contrast

lint（packages/cli/src/commands/lint.ts）用于扫描设计文档的一致性、结构性与可访问性问题，参数如下：

三个预设由 packages/core/src/lint/presets.ts 定义并导出：recommended、strict、accessibility。从源码看，color-contrast（颜色对比度）在recommended中即为 error 级别，strict会把 recommended 中非color-contrast的规则全部升级为warning并保持对比度规则为 error，accessibility则面向可访问性场景。预设的合并逻辑位于 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 完成了三件事：

1. 用IORegistry(BUILTIN_IO_FORMATS)读取文档字节并还原为SceneGraph（.fig、.pen等内置格式均由 packages/core/src/io 的BUILTIN_IO_FORMATS注册）；
2. 读取后调用computeAllLayouts(graph)计算全部布局（packages/core/src/layout），保证查询时拿到的宽高、位置等布局属性是最终值；
3. 按命令类型决定懒加载填充范围（prepareDocumentForRPC）：

这个设计对.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参数，两套模式对外命令完全一致，脚本可以无缝切换。

小结：检查命令一览

所有命令都支持--json，且均可在“文件模式”与“连接运行中应用”两种形态下使用，配合documents --json定位具体文档、lint的非零退出码门禁，足以支撑从日常巡检到 CI 自动化的完整设计文档检查流程。完整命令注册可查阅 packages/cli/src/index.ts，CLI 参考总览见 packages/docs/reference/cli.md。

• 前端
• 桌面应用
• AI 应用
• MCP 服务