# Codex Prompt: T4-Spike Path B — Figma Connect Publish + 同步价值验证

> ## ⚠️ DEFERRED — 不要 fire（2026-04-30 起）
>
> Tooltip rule #6 验证发现 `figma connect publish` 需要 **Organization / Enterprise** plan seat，用户当前 Pro plan 不可达。Path B pre-flight 必失败。本 prompt 保留作未来 Org 升级时的执行模板。
>
> **当前替代方案**：现有 `pnpm sync:figma-library` audit 在 Pro tier 已能报告 Figma drift；项目目标"AI 拿 URL → 1:1"已通过 AGENTS.md 硬规则 #6 + canonical SoT + divergences.md 拿到（[Badge spike commit b9e5ac3](../retrospection/2026-04-30-t4-spike-validated.md)）。
>
> **未来恢复条件**：用户 Figma 升 Organization / Enterprise plan，`get_code_connect_map` 不再返回 401。届时 fire 本 prompt 跑 Path B 验证 publish 链路。
>
> ---

> **Spike 目标**：验证 Code Connect 的"主价值"——`figma connect publish` 把 Badge.figma.ts 提交到 Figma 后，DevMode 面板能看到 code snippet，且 Figma 改组件后能机械识别影响代码。
>
> **估时 2-3h。不要 commit。**
>
> **前置约定（用户已拍板）**：`figma connect publish` 写 Figma metadata 不算违反 AGENTS.md 硬规则 #1（"不修改 Figma 设计"）——metadata 是设计师授权的连接信息，不修改设计本身。

---

## 背景（必读）

[2026-04-30 复盘](../retrospection/2026-04-30-t4-spike-validated.md) 已验证 T4-spike Path A：AI 拿 Figma URL → 生成 1:1 Vue 代码端到端跑通。但用户主张 Code Connect 的核心理由是**Figma 同步价值**：

> "一旦 Figma 组件有更新，执行 Figma 组件同步就很快能找到，无需大量搜索、差异对比等工作"

Path A 没验证这条。Path B 必须先证：如果 publish 链路 + DevMode 双向可见 + 同步识别**真能跑通**，T4 batch 全 21 组件批量才有真增量价值；否则 .figma.ts 只是 AI 生成 bonus。

---

## 必读前置

1. **`AGENTS.md`** — 项目级 AI 协作规则（含 "同步 Figma 库" 安全模式 + 硬规则 #1）
2. **`docs/meta-rules.md`** — 反模式清单 + 触发器 G/I
3. **[`docs/internal/retrospection/2026-04-30-t4-spike-validated.md`](../retrospection/2026-04-30-t4-spike-validated.md)** — Path A 完整背景
4. **[`src/components/Badge/Badge.figma.ts`](../../src/components/Badge/Badge.figma.ts)** — 已 commit 的 Code Connect 模板，本 spike 直接用它
5. **[`figma-sync/api.mjs`](../../figma-sync/api.mjs)** — 已有 Figma API 接入，看现有 token / file_key 用法
6. **`@figma/code-connect` 包**（已装）—— 跑 `pnpm exec figma --help` 看 CLI 命令真实形态，**不要凭印象写命令**

---

## Pre-flight 检查（先做，任一失败 STOP）

### 检查 1：Figma 账号能力

`figma connect publish` 需要 Figma DevMode 权限。检查方式：

```bash
# 看 user 的 Figma plan 是否含 Dev Mode（Pro / Organization / Enterprise 都有）
# Plan owner 已确认用户有 Figma Pro 权限
```

如果用户 Figma 是 Free plan → **STOP**，报 "Figma DevMode 不可用，Path B 不能执行"。

### 检查 2：环境变量

- `FIGMA_FILE_KEY`（[api.mjs:33](../../figma-sync/api.mjs#L33) 已用）→ Path B 也需要
- `FIGMA_PERSONAL_ACCESS_TOKEN`（或 `FIGMA_TOKEN`，看 `@figma/code-connect` 实际期望哪个名字）→ 需 **code_connect:write** scope

```bash
# 检查 .env 文件存在且含两个变量（不要打印 token 值）
test -f .env && grep -E '^(FIGMA_FILE_KEY|FIGMA_PERSONAL_ACCESS_TOKEN|FIGMA_TOKEN)=' .env | sed 's/=.*/=***/'
```

如果缺 `code_connect:write` scope → STOP 报告，让用户回 Figma 加 scope 后再跑。

### 检查 3：CLI 形态

```bash
pnpm exec figma --help 2>&1 | head -40
pnpm exec figma connect --help 2>&1 | head -40
```

读 help，列出可用子命令（应含 `create` / `publish` / `unpublish` / `parse` 等）。**不要 hardcode 命令**——按真实 help 输出走。

---

## 任务（按顺序，每步都有 STOP 条件）

### 任务 1：跑 `figma connect create`（如需要）

按 CLI help 形态，初始化 Code Connect 配置。预期产物：

- `figma.config.json`（或类似名）—— 项目级配置文件
- 可能需要回答几个问题（framework / paths 等），用 Vue + TypeScript

**注意**：`figma connect create` 默认可能扫全库自动生成所有组件的 `.figma.ts` stub。**禁止**——本 spike 只测 Badge。如果 create 命令强制扫全库，停下来确认能不能限制只对 Badge.figma.ts 操作。

如果 create 把 Badge.figma.ts 覆盖了 → STOP，git checkout 恢复，找参数限制范围。

### 任务 2：跑 `figma connect publish` 上传 Badge

按 CLI help 形态，找到限定单文件的 flag（如 `--node` / `--include` / 直接传文件路径）：

```bash
# 示例形态（实际命令查 help）
pnpm exec figma connect publish --node src/components/Badge/Badge.figma.ts
# 或
pnpm exec figma connect publish src/components/Badge/Badge.figma.ts
```

**预期输出**：CLI 报告 publish 成功 + 显示 Figma 中 Badge 组件 (`4821:1665`) 的 connection 已建立。

**STOP 条件**：
- 任何 401 / 403 (token scope 问题) → 报告，让用户加 scope
- 任何 publish 全库行为 → STOP，找参数限制
- 任何 publish 失败但报错不清晰 → 抓完整 stderr 给主 session 复审

### 任务 3：DevMode 验证（用户操作步骤文档）

写一份步骤说明 `docs/internal/_spikes/figma-connect-publish-devmode-test.md`，让用户手动在 Figma 里验证：

```markdown
# DevMode 验证步骤

1. 在 Figma 打开 TVU Design System 文件
2. 切到 Dev Mode（右上角切换）
3. 选中 Badge 组件（任一 variant，如 node-id=4821:1660 = Type=Circle, Color=Red, Tag=Filled）
4. 看右侧 Code 面板：
   - **预期**：显示 `<Badge color="Red" tag="Filled" type="Circle">99+</Badge>`
   - **如显示**：path B 主价值已落地——Figma 现在跟代码硬绑
   - **如不显示**：publish 没生效，看 DevMode 是否有错误提示

请回传 DevMode 截图给主 session。
```

### 任务 4：同步价值验证设计（不实跑改 Figma）

按 AGENTS.md 硬规则 #1（不改 Figma 设计），spike 不能让 executor 自己改 Figma。**改的动作必须用户做**。

设计**用户操作 + executor 验证**两步流程，写到上面那份 `figma-connect-publish-devmode-test.md` 后续段：

```markdown
# 同步价值验证（用户 + executor 协作）

## 用户步骤
1. 在 Figma 改 Badge 一个细节（如 Type=Circle / Color=Red / Tag=Filled 这个 variant 的 border-radius 从 16px 改成 20px）
2. **不要** publish 改动——保留为草稿状态即可（如果改不动可以创建一个新 variant 或临时调整）
3. 回到代码侧，告诉主 session "Figma 已改 Badge"

## Executor / 主 session 验证步骤
1. 跑 `figma connect parse src/components/Badge/Badge.figma.ts`（或 CLI 等价命令），看是否报告 Badge 跟 Figma 状态不一致
2. 跑 `pnpm sync:figma-library`（已有命令）拉 Figma 最新数据，跑 audit
3. 对照报告——是否能机械找到 "Badge 受 Figma 改动影响"

## 判定矩阵
| 工具 | 报 Badge 受影响 | 不报 Badge 受影响 |
|---|---|---|
| `figma connect parse` | ✅ Code Connect 主价值落地 | ❌ Code Connect 没起作用 |
| `pnpm sync:figma-library` audit | ✅ 现有 audit 已 cover | （存量 audit 也行） |

## 决策
- 两个都报：Code Connect 是真增量（更精确粒度）
- 只 audit 报，CC 不报：Code Connect 没主价值，T4 batch 重估必要性
- 都不报：spike 失败，重新设计验证方式
```

### 任务 5：清理（spike 不留 publish 副作用）

如果 publish 成功，spike 完成后必须**清理**：

```bash
pnpm exec figma connect unpublish --node src/components/Badge/Badge.figma.ts
# 或等价命令
```

理由：本 spike 是**验证**，不是**生产部署**。T4 batch 真做时再正式 publish 全 21 组件。Spike 留 publish 状态会污染 Figma DevMode 后续测试。

如果 unpublish 失败 → 报告主 session，由 plan owner 决定是否手动清理。

---

## 不要做的事

- ❌ **不 commit / 不 push**
- ❌ **不修改 Figma 设计**（只 publish metadata）
- ❌ **不让 `figma connect create` 扫全库生成 stubs**——只针对 Badge.figma.ts 操作
- ❌ 不安装多余依赖（`@figma/code-connect` 已装够）
- ❌ 不改 `Badge.figma.ts` / `Badge.vue` / 任何 src/ 文件
- ❌ 不让 spike 留 publish 副作用——任务 5 必须 unpublish
- ❌ 不打印 `FIGMA_PERSONAL_ACCESS_TOKEN` / `FIGMA_TOKEN` 真值（只检查存在性）

允许的：

- ✅ 读项目内任何文件
- ✅ 跑 `pnpm exec figma --help` / `figma connect --help` / `figma connect <cmd> --help`
- ✅ 跑 `figma connect publish` / `parse` / `unpublish`（限定 Badge.figma.ts）
- ✅ 新增最多 2 个文件：
  - `figma.config.json`（或类似名，由 `figma connect create` 生成）
  - `docs/internal/_spikes/figma-connect-publish-devmode-test.md`（用户操作步骤）

---

## 自验

```bash
ls -la docs/internal/_spikes/figma-connect-publish-devmode-test.md
ls -la figma.config.json 2>/dev/null   # 如 create 跑了

# 工作区状态
git status --short | grep '^??' | wc -l    # 应 ≤ 2 新文件
git status --short | grep -E '^.M' | wc -l  # 应 = 0（不改任何已 tracked 文件）
git log --oneline -1   # HEAD 仍 b9e5ac3

# Badge.figma.ts 没被改
git diff HEAD -- src/components/Badge/Badge.figma.ts | wc -l   # 应 = 0
```

---

## 完成后 STOP

报告格式：

```
=== Pre-flight ===
Figma plan: Pro / Org / Enterprise / Free
FIGMA_FILE_KEY: present / missing
FIGMA_PERSONAL_ACCESS_TOKEN (or _TOKEN): present / missing
Token scope code_connect:write: confirmed / unknown / missing

=== CLI 形态 ===
figma connect 子命令真实清单：[create, publish, parse, ...]

=== 任务执行 ===
任务 1 (create): SKIPPED / SUCCESS / FAILED （理由）
任务 2 (publish): SUCCESS / FAILED （CLI 输出片段）
任务 3 (DevMode 验证文档): WRITTEN at <path>
任务 4 (同步验证设计文档): WRITTEN at <path>
任务 5 (unpublish): SUCCESS / FAILED / SKIPPED

=== 阻碍 / 困惑 ===
（如有）

=== 工作区状态 ===
N untracked，0 modified，0 commits，HEAD = b9e5ac3
```

主 session 复审 publish 结果 + 验证文档可执行性，然后用户跑 DevMode 验证 + 同步价值验证，回传截图 / 验证结果。

**STOP。不要进 T4 batch。**