Figma SIR Compiler

把 Figma 设计稿编译成中立的 SIR / DSL / style-spec 产物，再交给 Agent 按 dsl-gen delivery skill 交付 UniApp 工程。

这个包本身负责：

• 拉取 Figma 文件或节点
• 编译 SIR / DSL
• 生成 tokens、style-spec、增量 diff
• 提供 critical style presence 检查
• 随 output/ 拷贝 dsl-gen delivery skill

这个包本身不负责：

• 直接生成 Vue / UniApp 页面
• 直接运行 /dsl-gen 子命令
• 证明视觉高保真
• 替 Agent 写页面、组件、样式或 .dsl-gen 交付账本

UniApp 出码由 Agent 执行 output/dsl-gen/SKILL.md。当前契约版本跟 npm 包版本一致，权威源是 package.json，对应 skill 内的 contractVersion。

Figma
  -> figma-sir compile
  -> output/code + tokens + style-spec + dsl-gen skill
  -> Agent 按 dsl-gen/SKILL.md 交付 output/uniapp
  -> gates / delivery manifest / HBuilderX 打开

快速开始

npm install figma-sir-compiler

npx figma-sir init
export FIGMA_TOKEN=figd_xxx
# 编辑 figma.config.json，填入 fileKey

npx figma-sir compile

compile 完成后，把下面这句话发给 Agent：

请按 output/dsl-gen/SKILL.md，交付 UniApp 工程到 output/uniapp。

这句话刻意不重复 SKILL.md 里的 L0 规则，避免 README 变成第二份契约。默认情况下，Agent 会按 SKILL.md 的 DSL 发现顺序决定处理范围。

安装与配置

npm install figma-sir-compiler
npx figma-sir init

init 会生成 figma.config.json。推荐把 token 放在环境变量，不要写进配置文件。

配置优先级：

CLI 参数 > 环境变量 > figma.config.json

| 配置 | 环境变量 / CLI | 说明 | | :--- | :--- | :--- | | Figma token | FIGMA_TOKEN / --token | 推荐只用环境变量 | | file key | FIGMA_FILE_KEY / --file-key | Figma URL 中 /design/<fileKey>/ | | node id | FIGMA_NODE_ID / --node-id | 可选；支持 12:34 或 12-34 | | 输出目录 | FIGMA_OUTPUT_DIR / -o | 默认 output |

CLI 命令

figma-sir init [--force]
figma-sir compile [options]
figma-sir fetch [-o raw.json] [--refresh]
figma-sir diff <prev.json> <next.json> [--json]
figma-sir style-spec -i output/code -o output/style-spec.json
figma-sir critical-style-presence --code output/uniapp --spec output/style-spec.json

常用：

npx figma-sir compile
npx figma-sir compile --refresh
npx figma-sir compile --strict
npx figma-sir compile -o output --node-id 12:34
npx figma-sir compile --quiet --json

| 命令 | 作用 | | :--- | :--- | | init | 创建 figma.config.json | | compile | 拉取 Figma，输出 SIR / DSL / tokens / style-spec / delta / dsl-gen skill | | fetch | 只拉取 Figma 原始 JSON | | diff | 比较两个 SIR JSON | | style-spec | 无 token 场景下从 DSL 重建 style-spec | | critical-style-presence | 诊断 critical 样式值是否可在生成工程中检出 |

critical-style-presence 是诊断，不是交付硬门禁；它只证明 critical 样式值可检出，不证明样式值属于正确节点，也不证明视觉还原质量。

标准流程

1. 编译设计稿

npx figma-sir compile

首次编译会产出完整 output/code。后续编译会根据上一次基准写出 dsl-manifest.json 和 delta/。

2. 让 Agent 交付 UniApp

默认只需要一句话：

请按 output/dsl-gen/SKILL.md，交付 UniApp 工程到 output/uniapp。

/dsl-gen 不是 npm CLI 子命令，而是给 Agent 的触发话术。Agent 应以 output/dsl-gen/SKILL.md 为唯一交付契约，并按其中的 DSL 发现顺序读取输入：

用户显式路径
-> output/dsl-manifest.json 中的 added + changed / output/delta
-> output/code

输出目录是 output/uniapp/。需要强制指定范围时，再在这句话后补充具体 DSL 路径即可。

3. 检查交付

Agent 应按 SKILL.md 跑 L0 gate；诊断命令只记录结果，不作为生成目标。常见命令包括：

python3 output/dsl-gen/scripts/check-generation-plan.py --phase=plan output/uniapp
bash output/dsl-gen/scripts/check-scaffold.sh output/uniapp
bash output/dsl-gen/scripts/check-flex-display.sh output/uniapp
python3 output/dsl-gen/scripts/check-generation-plan.py --phase=delivery output/uniapp
python3 output/dsl-gen/scripts/check-source-locked-generation.py output/uniapp
python3 output/dsl-gen/scripts/check-page-chain-events.py output/uniapp
python3 output/dsl-gen/scripts/check-delivery-manifest.py output/uniapp
python3 output/dsl-gen/scripts/check-semantic-coverage.py output/uniapp
npx figma-sir critical-style-presence --code output/uniapp --spec output/style-spec.json

如果你在仓库根开发本包，也可以用 dsl-gen/scripts/... 路径；如果是在 output/ 产物里使用，脚本路径通常是 output/dsl-gen/scripts/...。

4. 打开 UniApp

用 HBuilderX 打开：

output/uniapp

如果工程使用了 uni-popup 或 mescroll，生成工程 README 会提醒你从 HBuilderX 插件市场导入对应 uni_modules。不要用 npm 安装这些 UniApp 插件。

output 产物说明

output/
├── sir.prev.json
├── diff.json
├── dsl-manifest.json
├── tokens.json
├── style-spec.json
├── style-spec.agent.json
├── style-spec.critical.json
├── style-spec/pages/*.json
├── style-spec.context.json
├── style-spec.hints.scss
├── dsl-gen/
├── code/
└── delta/
    ├── added/
    └── changed/

| 产物 | 含义 | 谁使用 | | :--- | :--- | :--- | | sir.prev.json | 上次编译基准，便于 diff | CLI / 机器 | | diff.json | 节点级变化摘要 | 人 / CLI；不作为 delivery source | | dsl-manifest.json | page DSL 状态：added / changed / unchanged / removed | Agent 做增量范围判断 | | tokens.json | 编译出的颜色、圆角等 token | Agent 写 uni.scss | | style-spec.json | 全量样式 IR | 机器 / critical-style-presence；Agent 默认不读 | | style-spec.agent.json | style-spec pageFile 索引 | Agent 只用来找本页 pageFile | | style-spec.critical.json | critical 样式侧车 | critical-style-presence 诊断；不用于出码 | | style-spec/pages/*.json | 每页 full nodes 样式上下文 | Agent 写本页 CSS 必读 | | style-spec.context.json | 旧单文件 style-spec 的恢复产物 | 缺 pages/ 时使用；只含 pages[].nodes 与统计 | | style-spec.hints.scss | critical 字面量速览 | 人类 debug；不用于出码 | | dsl-gen/ | Delivery skill、references、gate scripts、placeholder asset | Agent | | code/ | 当前全量 DSL | Agent 全量交付 | | delta/added / delta/changed | 本轮新增/变化 DSL | Agent 增量交付 |

重要约束：

• Agent 默认不要读取全量 style-spec.json。
• 写某页 CSS 前必须读取本页 DSL 和对应 style-spec/pages/<pageFile>。
• summary、style-spec.hints.scss、style-spec.critical.json 不属于 delivery source，不能作为页面结构、组件、CSS 或 coverage 来源。

output/uniapp 产物说明

Agent 交付后，output/uniapp 通常包含：

output/uniapp/
├── App.vue
├── main.js
├── index.html
├── manifest.json
├── pages.json
├── uni.scss
├── components/
├── pages/
├── static/placeholder.png
├── README.md
└── .dsl-gen/
    ├── run-state.json
    ├── page-plan.json
    ├── component-plan.json
    ├── component-inventory.json
    ├── delivery-manifest.json
    ├── events.ndjson
    ├── page-chains/*.lock.json
    ├── page-chains/*.json
    ├── coverage/pages/*.semantic.json
    └── assets/media-manifest.json

| 产物 | 代表什么 | | :--- | :--- | | components/ | 仅放 shared 组件 | | pages/<pageDir>/components/ | 页面或业务域内 page-scope 组件 | | static/placeholder.png | 图片占位资源；无真实图时统一使用 | | .dsl-gen/run-state.json | Plan Barrier 状态与 baseline | | .dsl-gen/page-plan.json | 每页输入、style pageFile、Page Chain 计划 | | .dsl-gen/component-plan.json | H0-H5 组件抽取决策 | | .dsl-gen/component-inventory.json | 实际组件清单、归属、使用页、显式 import | | .dsl-gen/events.ndjson | Page Chain 事件账本 | | .dsl-gen/page-chains/*.json | 每页 Source-Locked 生成结果 | | .dsl-gen/coverage/pages/*.semantic.json | 可选诊断；高价值语义节点覆盖证据 | | .dsl-gen/assets/media-manifest.json | Icon/Image 占位与替换追踪 | | .dsl-gen/delivery-manifest.json | 交付总账本和 gate 结果 |

这些账本是过程与契约证据，不是视觉质量证明。

Agent 交付契约

dsl-gen 是随包分发的 delivery skill，不是 npm CLI 子命令。它的最高权威是 output/dsl-gen/SKILL.md。

README 只负责告诉用户如何启动交付；具体 L0、Source-Locked Page Chain、style-spec 主路径、组件归属、Script Boundary、gate taxonomy 都以 SKILL.md 为准。不要把 README 或用户提示词当成第二份规则源。

增量生成

compile 会维护：

output/dsl-manifest.json
output/delta/added
output/delta/changed

默认仍然使用同一句话：

请按 output/dsl-gen/SKILL.md，交付 UniApp 工程到 output/uniapp。

Agent 会按 SKILL.md 的发现顺序优先处理本轮 added + changed。首次编译时，delta/added 等价于当前全部新增页面；后续编译时，delta/added 只代表本轮新增，delta/changed 代表本轮变化，output/code 始终代表当前全量 DSL。

按当前契约，Agent 可以先完成 Plan Barrier 与 Foundation；但在写任何页面或 page-scope 组件前，会先输出本批 Page Chain Re-Read Checkpoint 等你确认。这个检查点是提醒 Agent 重新读取本页 DSL + full style-spec pageFile 后再出码；你应能看到每个页面对应的 DSL、pageFile、page components、shared deps、允许写入范围和执行顺序。

如果需要强制只处理某些文件，可以追加一句：

本轮只处理 output/delta/added 和 output/delta/changed。

unchanged 通常不需要整批重扫；removed 需要结合产品意图决定是否移除页面或保留兼容入口。

页多 / 分批

dsl-gen 契约内置分批策略：

| page 数 | 默认行为 | | :--- | :--- | | <= 6 | 可一次交付 | | 7-12 | 建议分批 | | >= 13 | 默认先计划再分批 |

分批不改变 L0。每批仍要：

• 按声明范围生成
• 保留未声明路径
• 遵守 Page Chain
• 更新账本
• 跑对应 gate

接接口

UI 交付和接口绑定是两件事。默认只交付 UI，不编造后端 path。

绑定流程：

UI + slots
-> OpenAPI
-> bind draft
-> 人审 review.a
-> confirmed binding
-> wire

推荐话术：

请按 output/dsl-gen/SKILL.md 在 output/uniapp 上执行 bind draft。
OpenAPI 路径是 docs/openapi/xxx.yaml。
只生成 binding draft 和检查台，不要 wire，不要编造接口。

检查台：

python3 output/dsl-gen/scripts/write-binding-review.py output/uniapp

本地 mock 可选：

npx --yes @stoplight/prism-cli@latest mock docs/openapi/your.yaml -p 4010 -h 127.0.0.1

绑定文档：

| 文档 | 何时读 | | :--- | :--- | | data-binding.md | 总览 | | binding-slots.md | UI 阶段写 slots | | binding-wire.md | bind / review / wire |

常见问题

figma-sir compile 会直接生成 UniApp 吗？

不会。它生成 DSL、style-spec 和 dsl-gen delivery skill。UniApp 工程由 Agent 按 skill 交付。

/dsl-gen 是 CLI 命令吗？

不是 npm CLI 子命令。它是给 Agent 的触发话术。真正的包命令是 figma-sir compile、figma-sir style-spec、figma-sir critical-style-presence 等。

为什么不让 Agent 直接读全量 style-spec.json？

全量文件可能很大，容易超上下文或导致 Agent 只看摘要写近似页面。正确路径是 style-spec.agent.json 找 pageFile，再读取本页 style-spec/pages/*.json；summary / hints / critical 不参与出码。

critical-style-presence 通过代表高保真吗？

不代表。它是诊断项，只证明 critical 样式值可检出，不证明值绑定到正确节点，也不证明整体视觉质量。

为什么生成工程里有 .dsl-gen/？

它是交付账本，不是运行时业务代码。里面记录 plan、Page Chain、component inventory、delivery manifest、gate 结果和可选诊断结果。

可以用临时脚本批量写页面吗？

不可以。脚本不进交付目录也不合规。helper 只能做 hash、校验、格式化或上下文恢复。

HBuilderX 打开前要做什么？

打开 output/uniapp。若 README 提示 uni-popup 或 mescroll，先从 HBuilderX 插件市场导入对应插件。

设计稿建议

• 页面 FRAME 放在 SECTION 下，避免游离页面。
• 页面名稳定，减少路由和 binding id 变化。
• 尽量使用 Auto Layout。
• Button、Input、Card、List、Sheet、Modal 命名清晰。
• 列表容器命名包含 List / Cards / Feed 等信号。
• Prototype 导航用 navigate；打开弹层用 overlay。

维护命令

维护 skill、references 或 scripts 后运行：

npm run version:check-skill
python3 dsl-gen/scripts/check-skill-consistency.py
node --test tests/**/*.test.js

发包或完整验证：

npm test

License

MIT