# Codex Prompt: Sync Pipeline Safety 修复

修复 Claude 之前引入的不安全默认值。本任务只做安全性修复 + 文档说明：把 cleanup 改成默认 dry-run，把已写入的乐观值降级为待审，并在 `AGENTS.md` 给"同步 Figma 库"唤醒词补安全约束。

**不改 token、不改组件、不改 figma-data/、不运行 pipeline。**

---

## 必读前置（按顺序）

1. `AGENTS.md`（本仓库 AI 协作入口）
2. `docs/PROJECT_GOAL.md`
3. `figma-sync/sync-figma-library.mjs`（当前 pipeline 协调脚本）
4. `figma-sync/cleanup-unpublished.mjs`（当前 cleanup 脚本）
5. `figma-sync/ensure-docs-site-manifest.mjs`(当前 manifest 补齐脚本)
6. `docs/site-review-manifest.json`（含本次需要降级的 5 条）
7. `package.json`（scripts 段）

---

## 任务 1：修 `figma-sync/sync-figma-library.mjs`（最高优先级）

### 现状（不安全）
- pipeline 默认 Step 1 调用 `cleanup-unpublished.mjs --apply`
- 后果：每次 `pnpm sync:figma-library` 都会基于当时的 published manifest 删除 raw/normalized 中"非发布"内容
- 风险：manifest 临时不完整 / sync:extract 还没跑 / Figma 端 published list 临时变化时，会误删生产数据

### 目标（安全默认）

- pipeline **默认不调用任何 --apply 删除**
- cleanup 步骤默认只跑 dry-run，输出报告，**不删任何文件**
- 引入命令行标志 `--apply-cleanup`：只有显式传这个 flag 时，pipeline 才会让 cleanup 真删
- 已有的 `--with-extract` 标志保留不变

### 实现细节

- 在脚本顶部解析新标志：`const APPLY_CLEANUP = process.argv.includes('--apply-cleanup')`
- Step 1 调用 cleanup 时，根据 APPLY_CLEANUP 决定是否传 `--apply` 参数：
  - `APPLY_CLEANUP === true`  →  `node figma-sync/cleanup-unpublished.mjs --apply`
  - `APPLY_CLEANUP === false` →  `node figma-sync/cleanup-unpublished.mjs`（dry-run）
- Step 1 显示的步骤标题随模式变：
  - dry-run: `Step 1: cleanup:unpublished (dry-run, 不删文件)`
  - apply:   `Step 1: cleanup:unpublished --apply`
- SUMMARY 末尾的"全绿"提示也要根据模式区分：
  - dry-run 时提示："cleanup 仅 dry-run，未删任何 figma-data。如确认要删，请加 `--apply-cleanup` 重跑。"
  - apply 时维持现有提示

### 注意

- 不要在 cleanup 步骤之外引入新的删除 / 写入操作
- 不要改 cleanup 脚本本身的默认行为（cleanup-unpublished.mjs 已经是 dry-run-by-default）
- pipeline 里其它步骤的默认行为保持不变：
  - Step 2 audit:published-vs-code 仍然带 `--auto-suggest-unmapped`（写 mapping JSON 是非破坏性的）
  - Step 3 ensure-docs-site-manifest 仍然 `--apply`（改 manifest 是受控的，且 pixelReviewStage 已降级为 in-review，见任务 2）
  - Step 4/5 audit 是只读

---

## 任务 2：修 `figma-sync/ensure-docs-site-manifest.mjs`

### 改动点

把脚本里 `buildEntry()` 函数中 `pixelReviewStage` 的默认值从 `'approved'` 改成 `'in-review'`。

### 理由

`approved` 是"已人工审过像素一致"的强声明。新自动添加的条目从未被人工审，不应该带这个声明。降级为 `in-review` 是诚实状态。

### 注意

- 其它默认字段（`baselineStatus: 'captured'`、`expectedSourceType: 'canonical-only'`、`currentRenderingMode: 'figma-frame'`）不动
- 函数注释 / 顶部 comment 适当更新一下，提示 `pixelReviewStage` 是保守默认，需要人工后续核对升级

---

## 任务 3：把已写入的 5 条 manifest 条目从 `approved` 改回 `in-review`

### 范围

`docs/site-review-manifest.json` 里这 5 个 `pageId` 的 `pixelReviewStage` 字段，从 `"approved"` 改成 `"in-review"`：

- `breadcrumb`
- `form-item`
- `prompt-message`
- `steps`
- `tabs`

### 严格要求

- **只改这 5 个条目的 `pixelReviewStage` 字段**
- 不动同条目的其它字段（`figmaPage` / `figmaComponentSet` / `figmaNodeId` / `baselineStatus` / `expectedSourceType` / `currentRenderingMode` / `pageId` / `pageFile` / `kind` 都保留）
- 不动 manifest 里其它原有的 18 条条目（包括 overview / 5 个 foundation / 17 个老 component pages）
- 不调整顺序、不重新格式化全文，只精确改这 5 条的一个字段

---

## 任务 4：AGENTS.md 加唤醒词 "同步 Figma 库"

### 加在哪

在 AGENTS.md 现有"工作流（约定）"段落之后、"当前阶段定位"之前，新增一节 `### 唤醒词："同步 Figma 库"`。

不动 AGENTS.md 其它内容。

### 节内容（按下文写）

```markdown
### 唤醒词："同步 Figma 库"

任何 AI session 收到这句话时，按下面顺序执行，**禁止跳步、禁止默认走破坏性路径**：

1. 跑 `pnpm sync:figma-library`（默认**安全模式**：cleanup 只 dry-run，不删任何 figma-data/）
2. 看 cleanup dry-run 报告：
   - 如果有候选删除项，**只输出报告**，绝不直接删除
   - 把候选清单列给用户，并明确说明"会删除 N 个文件，需要授权"
3. 等用户回 `--apply-cleanup` 或显式确认后，才能跑 `pnpm sync:figma-library --apply-cleanup` 真删
4. `audit:figma-conformance` / `audit:docs-site` / `audit:published-vs-code` 输出必须能解释；如有未通过项，STOP 并报告，不要继续后续阶段
5. 任何 `figma-data/` 写操作（删除、改 index、改 manifest）必须经过 dry-run + 用户授权
6. 任何 `audit:published-vs-code --auto-suggest-unmapped` 新写入 mapping JSON 的条目，状态必须是 `needs-review`，禁止自动 `approved`

### 默认安全 vs 显式破坏性

| 场景 | 命令 | 默认行为 |
|---|---|---|
| 同步 Figma 库（推荐入口） | `pnpm sync:figma-library` | 安全：cleanup dry-run，不删 figma-data |
| 真要删（用户已审过 dry-run 报告） | `pnpm sync:figma-library --apply-cleanup` | 破坏性：cleanup 实际删除 |
| 含 Figma extract | 加 `--with-extract` | 需要 .env 中的 `FIGMA_TOKEN` |
```

---

## 禁止（必须严格遵守）

- ❌ 不修改 `figma-data/raw/` 任何文件
- ❌ 不修改 `figma-data/normalized/` 任何文件
- ❌ 不修改 `figma-data/published/` 任何文件
- ❌ 不运行 `cleanup:unpublished --apply`
- ❌ 不运行 `pnpm sync:figma-library`（任何形式）
- ❌ 不运行 `pnpm test` / `pnpm build`（验证留给用户）
- ❌ 不动 token 文件、组件代码、视觉硬错误——这些是后续阶段
- ❌ 不动 `working-principles.md`、`docs/PROJECT_GOAL.md`、`docs/PROJECT_MAP.md`
- ❌ 不替用户决策那 5 条 manifest 条目的最终 pixelReviewStage（`in-review` 是降级到诚实默认，最终是否升级到 `approved` 由用户后续逐条审）
- ❌ 不修我（Claude）写的 audit 脚本的逻辑——任务 1 只改 sync-figma-library.mjs

---

## 验证（不动手，仅自检）

完成 4 个任务后 **不要运行任何 pipeline / cleanup / audit / test / build**。只输出：

1. **改动文件清单**：每个文件改了哪几行
2. **diff 摘要**：每处改动的 before / after（关键字段对比）
3. **未验证项**：明确列出哪些行为只能在用户批准跑时验证（例如 `pnpm sync:figma-library` 的实际默认行为、Step 1 是否真的 dry-run）

---

## 完成后 STOP

不要进入下一阶段、不要追加修复、不要替用户决策。

报告格式：

```
== 改动文件 ==
- figma-sync/sync-figma-library.mjs: ...
- figma-sync/ensure-docs-site-manifest.mjs: ...
- docs/site-review-manifest.json: 改了 N 条条目的 pixelReviewStage
- AGENTS.md: 新增 "同步 Figma 库" 唤醒词节

== 未验证项 ==
- pipeline --apply-cleanup 实际删除路径（需用户授权后跑）
- pipeline 默认 dry-run 时是否完整跑通后续步骤（需用户跑一次验证）
- 其它...
```

完成报告后 STOP。等用户决定下一步。