figma-ios-codegen: Instructions file for Codex

Project Agent Rules

本文件是跨客户端的 Agent 入口（Cursor / Claude Code / Codex / 其他读 AGENTS.md 的工具）。
Cursor 细则：.cursor/rules/figma-ios-codegen-workflow.mdc（按描述触发，alwaysApply: false；命中 Figma→代码意图时加载）。
新增 / 删除 / 重命名 .cursor/rules/*.mdc 时，必须同步更新本文件。
给人读的对外文档（安装 / 架构 / 设计约定 / FAQ）：docs/ — Agent 生成代码时仍以本文件 + skills 为准，不必整份加载 docs/。

必读规则文件

文件	适用场景
.cursor/rules/figma-ios-codegen-workflow.mdc	用户给出 Figma 链接并要求转/生成 iOS 代码时：强制按该 workflow 执行

详细 skill：.cursor/skills/（总入口 figma-ios-playbook）。
宿主定制：.cursor/bindings/（bindings/README.md）。
当前示例前缀 MK；换宿主只改 JSON，不改 skill。

---

何时启用本流程

同时满足才启用：

1. 提到 figma 或给出 figma.com/... 链接
2. 表达「转/生成代码」意图

不触发：只问 Figma 用法、或未提 Figma 的「写个登录页」。

当前只支持 iOS Swift（UIKit）。

---

铁律（最高优先级）

1. 先数据包，后写码 — 无成功的 {data_dir}/manifest.json → 禁止阶段 2。已有 data_dir 可跳过重拉，仍须校验 schema_version。
2. 阶段 2 唯一数据源 — 只读数据包 + .cursor/bindings/；禁止再调 Figma REST / MCP。
3. 全量还原 — 应实现节点全部生成；未完成须按 mdc「未完成处置模板」开头声明。
4. TODO — 仅 // TODO(阶段3): / // TODO(阶段2):。
5. 不要改 preload 源码「自愈」 — 先 python3 -m src.cli --self-check-only；禁止 LLM 重写 src/**。

---

架构（1 → 2 → 4；阶段 3 仓外）

阶段	做什么	谁做
1	Figma URL → 规范化数据包（零 LLM）	本地 CLI（或可选自建 MCP）
2	数据包 + bindings → 基础 UI Swift	Agent + .cursor/skills
4	节点覆盖率 + 截图视觉验收	Agent（阶段 2 之后强制）
3	PRD + 接口 → 商用业务代码	不在本仓库流程内

---

阶段 1：生成数据包

路径探测

WORKSPACE_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
PRELOAD_DIR_ENV="${FIGMA_PRELOAD_DIR:-$FIGMA_DATA_MCP_DIR}"   # 新名优先；旧名兼容

if [ -n "$PRELOAD_DIR_ENV" ] && [ -f "$PRELOAD_DIR_ENV/src/cli.py" ]; then
    DATA_PRELOAD_DIR="$PRELOAD_DIR_ENV"
elif [ -f "$WORKSPACE_ROOT/.cursor/figma-ios-preload-data/src/cli.py" ]; then
    DATA_PRELOAD_DIR="$WORKSPACE_ROOT/.cursor/figma-ios-preload-data"
elif [ -f "$WORKSPACE_ROOT/figma-ios-preload-data/src/cli.py" ]; then
    DATA_PRELOAD_DIR="$WORKSPACE_ROOT/figma-ios-preload-data"
fi
# 有 DATA_PRELOAD_DIR → MODE=local；否则需已配置 fetch_figma_design（MODE=mcp）