cx-figma-analyzer

Imported from iamyxy/prd-to-code (assets/skills/cx-figma-analyzer/SKILL.md). Install upstream with npx skills add iamyxy/prd-to-code --skill cx-figma-analyzer. Copyright stays with the author.

Provider 配置约定

本 Skill 的服务名称与调用指导来自配置。进入原外部调用步骤时，先读取当前 session 的 provider-context.json，或执行 cx providers guide <capability> --context <pipeline-context.json>。快照优先于此文件安装时显示的名称；不得用新仓库配置覆盖进行中的 session。只替换工具实现，不增删或调整以下步骤、叶子 Skill、Hook 和 Gate。

Cx Figma Analyzer

职责

从当前 Cx session 的 LIST、澄清材料与引用的 PRD/Figma 中，发现能唯一映射到 LIST 模块的精确 Figma node 链接，覆盖写入固定产物供 cx-tech-design-design-inputs 自动填写。

这是只读拓展分析器，不是 Pipeline stage，也不是完整设计审计/报告系统。

开始前读取

• 输入包含 session_ref 时，读取 references/cx-session-inputs.md。
• PRD 使用 prd_source Provider 读取，按 cx providers guide prd_source --context <pipeline-context.json> 获取当前会话指导。
• Figma 分析使用 design_evidence Provider；按 cx providers guide design_evidence --context <pipeline-context.json> 获取布局/元数据工具，不固定某个 MCP。

硬边界

• 对 pipeline-context.json、pipeline-events.jsonl 和全部既有阶段产物只读。只额外覆盖写 .internal/tech-design/figma-node-links.json；不得写 design-inputs.json 或技术方案正文。
• 不调用 cx pipeline init、advance、block、rollback、rerun、finalize，不创建或恢复 session。
• 不打印 token、cookie、JWT 或其他凭据。Figma 与{{ providers.document_publisher.displayName }}鉴权由已有 MCP/CLI 管理。
• 外部读取只做有限重试。权限、认证、not-found 和多候选不是无限重试理由。
• You currently have nothing selected / selection-only 是根节点粒度不受支持的工具信号，不是权限失败；应继续用 get_metadata 发现可映射的业务子节点。
• 不调用 AskUserQuestion。无法唯一映射的节点直接省略，交给 collector 原有提问流程。

输入

至少提供一类：

Cx tech_design/pre Hook 调用时，session 已由 Pipeline 注入；优先读当前 session 的 LIST.md、CLARIFICATION.md 及其中引用的 PRD/Figma。

执行流程

1. 定位 session（见 session 输入契约）；优先只读 cx pipeline status --context <context> --json，CLI 不可用才直接读 JSON。
2. 读取 LIST.md 模块清单；从澄清材料、PRD、显式 Figma 链接汇聚候选节点。
3. 对候选根节点取 metadata / design context；根为 CANVAS 或返回 selection-only / 稀疏目录时，降为目录并用 get_metadata 发现业务子 Frame/Component，不要把根失败当终点。
4. 粒度下探：识别出的节点层级过大时，必须发现更细致的业务节点，容器级节点不能作为映射目标。
   • SECTION / CANVAS / DOCUMENT 只是组织容器，不能视为组件节点，不得写入产物；
   • 一个节点同时覆盖多个 LIST 模块，或明显是整页、整组稿而非单个模块对应的 UI 单元时，用 get_metadata 逐层发现其子级业务 Frame/Component/Instance，直到节点与模块唯一对应；
   • 下探后仍无法与单一模块唯一对应时省略该映射，不要回退到容器节点凑数。
5. 只保留同时满足下列条件的映射，写入产物后返回：
   • module_id 在当前 LIST.md 中存在，且节点与该模块能唯一对应；
   • url 含精确 node-id，node_id 与 URL 一致；
   • 节点不是 SECTION / CANVAS / DOCUMENT 等容器级节点；
   • 节点不是 PRD 的整页 page_reference；
   • 同一 node 不映射到多个模块；同一模块/状态不写多个互相冲突的 node。

不要生成 report.md、截图、coverage、动线表或{{ providers.document_publisher.displayName }}分析报告。不引入 confidence、候选 sidecar、D2C cache 或截图 handoff。

输出契约

覆盖写：

<session_dir>/.internal/tech-design/figma-node-links.json

父目录不存在时先创建 <session_dir>/.internal/tech-design。

{
  "status": "ready",
  "figma_node_links": [
    {
      "module_id": "M1",
      "state_hint": "正常态",
      "node_id": "100:220",
      "url": "https://www.figma.com/design/FileKey/analysis?node-id=100-220"
    }
  ]
}

顶层只写 status 和 figma_node_links，不要写 schema_version、session_id 或其它元数据。

• status 只使用 ready | partial | not_applicable；存在可用链接但分析仍有缺口时写 partial。
• 没有可用节点时也必须覆盖写 status: "not_applicable" 和空数组，防止复用旧结果。

Hook 调用最多返回十行，不内联报告正文：

status: OK | PARTIAL | BLOCKED
figma_node_links_path: .cx/sessions/2026-07-17-example/.internal/tech-design/figma-node-links.json
figma_node_links_count: 1

Hook 结果只是 stage evidence。不得修改 pipeline-context.json、pipeline-events.jsonl，不得新增 stage output 或 runner gate。