📄 本页由源文件 skills/dev-flow/steps/step-5.5-post-coding.md 自动投影生成（单一权威源）。请勿直接编辑本页。

步骤 5.5：编码后置钩子（POST-CODING，强制）

本文件仅在执行步骤 5.5 时加载。每轮编码完成后必须按顺序执行 4 个子钩子。

目标

编码完成后的强制质量检查：代码规范审查 → 文档同步 → 快速自检 → i18n 翻译检查。

执行规范（按顺序执行，不可跳过）

步骤 5 编码完成
→ 5.5a 代码规范审查（强制）
→ 5.5b 文档同步
→ 5.5c 快速自检（Build + Lint）
→ 5.5d i18n 翻译词条检查（条件触发）
→ 用户下一步指令

5.5a 代码规范审查 — L1 基础审查（强制，不可跳过，审核者分离）

触发条件：步骤 5 产生了任何代码文件改动即触发。无代码文件改动则跳过。

执行方式（审核者分离）

设计原则：编码者与审查者分离。通过独立的子 agent 审查改动，消除"自写自审"盲区。

主 agent 准备审查素材：

1. 生成本轮改动摘要：git diff --stat（改动文件清单 + 行数统计）
2. 获取完整 diff：git diff（作为 Task prompt 的内容）
3. 为每个改动文件写 1 句话用途说明

🔀 Fan-out 并行子 agent 审查：

🔀 Fan-out（步骤 5.5a L1 审查，2 子 Agent）：
├─ Task(2号): 代码审查 — CRITICAL/HIGH/MEDIUM/LOW 分级
│   审查要点：
│   - 功能正确性：逻辑是否按方案执行、是否有明显逻辑错误
│   - 边界条件：空值/undefined/空数组/异常输入是否处理
│   - 可选链：所有链式属性访问是否使用 ?.
│   - 代码风格：const优先、===全等、模板字面量、无 var
│   - React 规范：useEffect cleanup、函数式 setState、无 class 组件
│   - 调试残留：console.log/debugger/临时注释/硬编码测试值
│   - 对每个发现标注严重度（🔴CRITICAL/🟡MEDIUM/🟢LOW）
│
└─ Task(5号): 安全快速扫描
审查要点：

- XSS/注入风险（dangerouslySetInnerHTML、innerHTML、eval）
- 硬编码密钥/token/敏感凭证
- 用户输入未校验/未转义

⚠️ 每个 Task prompt 必须包含：① 本轮 diff 全文 ② 每个文件的用途说明 ③ 期望输出格式（严重度分级 + 文件位置 + 问题描述 + 修复建议）。

Fan-in → 主 agent 汇总：

1. 合并两份报告，去重（同一问题被两个 agent 同时发现时合并为一条）
2. 标注每条问题的来源（[2号] / [5号] / [2号+5号]）
3. 输出统一 L1 审查报告

严重度处理：

• 🔴 立即修复 → 修复后调用 read_lints 确认 → 若修复涉及 ≥3 行逻辑变更，重新走一轮 2号审查（最多 2 轮，防止无限循环）
• 🟢 仅提示（无需用户决策）
• 🟡 建议修复项需用户决策，必须使用 ask_followup_question 弹出交互式选项：

选项	说明
🔧 全部修复	修复所有 🟡 建议项
⏭️ 全部跳过	跳过所有 🟡 建议项
✏️ 部分修复	告诉我要修复哪几项（如 "修 1,3"）

模式差异

模式	子 agent 审查	🟡 交互
标准模式 / 完整模式	✅ 启用（2号+5号）	弹选项
精简模式（streamlined）	✅ 启用（同上）	弹选项（质量决策不豁免）
迭代修复	✅ 启用（2号+5号）	🟡 自动跳过
步骤 5 内部多轮修复	✅ 启用（2号+5号）；首轮与后续轮次一致	🟡 自动跳过（非首轮）
micro-fix	⚡ 极简版 L1（主 agent 自审，仅改动行 + 红线 §5/6/7/9）	不弹（🔴 自动修复，🟡 静默跳过）

设计说明：

• 迭代修复启用子 agent：因为这是已完成代码上的增量修复（提测反馈/上线 bugfix），回归风险最高，token 投入值得。🟡 仍自动跳过以减少用户打断。
• 内部多轮修复启用子 agent：每次增量 diff 虽小，但 🔴 问题（如可选链遗漏、边界条件）仍可能被主 agent 遗漏。子 agent 在后台并行运行，不增加用户等待时间；🔴 自动修复不增加交互次数。仅 token 成本（~5k），在代码质量面前是合理投入。
• micro-fix 极简版 L1：主 agent 自审，不走子 agent（token 开销 ~5k 远超微改动量）。v2 改造为"极简版 L1"而非完全跳过——仅扫描改动行 + 红线 §5/6/7/9 四项，成本可控（≤1 次 use_skill）。详见 references/micro-fix-light.md §二。

迭代修复/步骤 5 内部多轮修复的差异（详见 references/iteration-fix.md §「步骤 5.5 统一 L1 审查」）：

• 🟡 建议项自动跳过（不弹交互选项），减少打断
• 不输出完成标记 JSON、不弹推进选项——静默执行后直接汇报结果
• commit/收尾前的最终 5.5 仍按本文件的完整规范执行（弹选项 + 输出完成标记）

🏷️ 完成后输出锚点：[STEP-5.5-A-COMPLETE] L1 审查完成 | 2子agent spawned | 🔴{N} fixed | 🟡{M} pending

成本与性能

• 子 agent 调用：2 次并行 Task（~4-6k tokens，可并行执行无额外时间）
• 审查范围：仅本轮改动文件（git diff 范围）
• 最多 2 轮修复-重审循环（防止无限循环）

5.5b 文档同步

🏷️ 完成后输出锚点：[STEP-5.5-B-COMPLETE] 文档同步完成 | working-context 已更新

当前时机为 ① 编码后（四个时机中最轻量的）：

• 工作上下文：更新 ## 进度（当前状态 3~5 行）+ ## 备注（如有新增协议/交互细节）
• devlog / 文档平台：此时机不更新
• 跳过条件：本轮无代码改动

5.5c 快速自检（预检模式，2026-05-29 调整）

🏷️ 完成后输出锚点：[STEP-5.5-C-COMPLETE] 快速自检完成 | lint_pre_check={pass\|has_issues} | {N} pending issues

设计变更：原"必须 lint_clean=true"已调整为预检不阻塞，最终 lint 裁决统一在步骤 6.V3 执行（避免连续两次 lint 同样的文件）。

• read_lints 检查改动文件
• 预检结果记录到完成标记 JSON 的 lint_pre_check 字段（pass / has_issues），不阻塞 5.5 推进
• 发现明显错误（如类型错误、语法错误等编译级问题）→ 立即修复后回 5.5a 重新审查
• 仅 lint warning / 风格问题 → 写入 pending_lint_issues 列表传递到步骤 6.V3 统一裁决

5.5d i18n 翻译词条检查（条件触发，2026-07 新增）

定位：第一道拦截。编码完成后立即检查本次改动是否需要补充 i18n 翻译词条。 兜底：步骤 6A V8 会基于本钩子的输出做二次确认（详见 step-6-verify.md §V8）。

触发条件

满足以下全部条件时触发，否则静默跳过：

✅ 步骤 5 产生了代码改动（与 5.5a 一致）
✅ git diff 中包含 TSX/TS/JSX/JS 文件
✅ 文件路径在 src/ 目录下

不触发场景（静默跳过）：

• 纯样式文件改动（.less/.scss/.css）
• 纯配置文件/类型定义改动
• micro-fix 模式（保持轻量快速）
• 改动文件中无中文文案

执行流程（3 步）

5.5d i18n 翻译词条检查
│
├─ ① 获取改动文件 + 逐文件判定氛围
│     git diff --name-only | grep -E '\.(tsx|ts|jsx|js)$' | grep '^src/'
│     对每个文件并行执行两条命令：
│     A) grep -c "import.*{.*t.*}.*from.*i18n" <file>   # 是否有 import t
│     B) node my-project/src/i18n/utils/find-untranslated-chinese.js <file>  # 是否有未包裹中文
│
├─ ② 判定（仅两种结果）
│     ┌─────────────┬──────────────────┬──────────────────────────────┐
│     │ import t    │ 扫描结果         │ 判定                         │
│     ├─────────────┼──────────────────┼──────────────────────────────┤
│     │ ✅ 有       │ 有未包裹中文     │ 🔴 已启用 i18n，需补 t()     │
│     │ ✅ 有       │ 无未包裹中文     │ 🟢 已完整适配（不显示）      │
│     │ ❌ 无       │ 有未包裹中文     │ 🟡 未启用 i18n，建议决策     │
│     │ ❌ 无       │ 无中文           │ ⏭️ 跳过                      │
│     └─────────────┴──────────────────┴──────────────────────────────┘
│
└─ ③ 输出统一报告 + 弹出交互式决策

判定原则：文件 import t 了 = 开发者已选择 i18n → 🔴 新增中文必须补 t()。不引入包裹率等量化阈值。

namespace 自动推断

对需要补充翻译 JSON 的 key，根据文件路径自动推断目标 namespace：

文件路径 → 路由匹配（namespace-map.ts 的 ROUTE_NS_MAP 最长前缀匹配）→ namespace
├─ 匹配到 → 写入对应 JSON（如 webinar.json）
├─ 公共组件多页面引用 → 写入 common.json（兜底）
└─ 匹配失败 → 写入 common.json

报告格式

🌐 i18n 翻译词条检查（5.5d）

📊 扫描 {N} 个改动文件，{M} 个含中文文案
📊 发现：🔴 {A} 个已启用 i18n 文件需补 t() / 🟡 {B} 个未启用 i18n 文件需决策

### 🔴 已启用 i18n 的文件（需补 t()）

| 文件 | 行号 | 中文文案 | 推荐 namespace |
| --- | :---: | --- | --- |
| `views/webinar/.../index.tsx` | L42 | "报名人数上限" | `webinar` |
| `views/webinar/.../index.tsx` | L58 | "确定删除" | `webinar` |

### 🟡 未启用 i18n 的文件（需决策是否适配）

| 文件 | 中文文案数 | 示例 |
| --- | :---: | --- |
| `views/xxx/index.tsx` | 5 处 | "操作成功"、"请输入名称"、... |

> 📌 以上 🟡 文件当前未 import t，同模块其他文件均完整适配 i18n。

交互式决策（标准模式必须弹出）

#	选项	说明
1	🔧 修复 🔴 清单	给已适配文件的新增中文补 t()，末尾追加翻译 key 到对应 namespace JSON（翻译值用 TODO: 占位）
2	📋 连同 🟡 一并适配	将未启用 i18n 的文件也纳入改造（补 import { t } + 包裹所有中文 + 补 JSON）；仅存在 🟡 时显示
3	✍️ 仅补 t()，JSON 我手动补	只包裹 t()，不同步写翻译 JSON
4	⏭️ 全部跳过	记录到工作上下文 ## 待办，继续步骤 6

⚠️ 不自动补 t() 包裹：自动包裹有损坏代码风险（项目已有 fix-i18n-script-damage skill 佐证）。t() 包裹由 AI 在用户确认后手动完成。 ✅ 自动追加 JSON 条目：翻译 JSON 末尾追加 "中文 key": "TODO: <简要英译>"，风险可控。

模式差异（2）

模式	5.5d 行为
标准/完整	完整 3 步 + 交互式决策
精简（streamlined）	扫描 → 报告摘要 → 🔴 自动修复不弹选项；🟡 仅记录
迭代修复	扫描 → 仅输出摘要，不弹选项（i18n_5_5d = skipped）
步骤 5 内部多轮修复（非首轮）	扫描 → 仅输出摘要，不弹选项（i18n_5_5d = skipped）
micro-fix	跳过（i18n_5_5d = not_executed）

🏷️ 完成后输出锚点：[STEP-5.5-D-COMPLETE] i18n 扫描完成 | 结果={fixed_all\|skipped\|deferred\|no_issues\|not_executed}

与步骤 6A V8 的联动约定

5.5d 完成标记中的 i18n_5_5d 字段是 6A V8 的行为输入：

i18n_5_5d	含义	6A V8 行为
fixed_all	本次已全部修复	快速重扫确认 → 静默通过
skipped	用户选择跳过	再次提醒（不弹选项）
deferred	已记录待办	标注状态，不重复催促
no_issues	无 i18n 问题	静默通过
not_executed	未执行（如 micro-fix）	降级补执行完整扫描 + 弹出决策

⛔ 退出自检清单（逐项口播确认后才能输出完成 JSON）

在输出完成标记 JSON 之前，逐项确认并口播：

• [ ] 5.5a L1 审查：2 个子 agent（2号+5号）已 spawn 并汇总？
• [ ] 5.5a 🔴 问题：已修复且 read_lints 通过？
• [ ] 5.5a 🟡 问题：已弹出 ask_followup_question 让用户决策？
• [ ] 5.5b 文档同步：工作上下文 ## 进度 已更新？
• [ ] 5.5c 快速自检：read_lints 已执行？编译级错误已修复？
• [ ] 5.5d i18n：触发条件满足时已完成完整 3 步 + 交互式决策？
• [ ] 四个子环节锚点标记 [STEP-5.5-A/B/C/D-COMPLETE] 均已输出？
• [ ] 上述全部完成 → 才可输出完成标记 JSON

---

必须输出

步骤推进选项（标准模式必须）

按 steps/step-router.md §「步骤流转交互规则」，完成标记 JSON 输出并状态同步后， 若 interaction_mode 为 streamlined 则静默自动进入步骤 6（references/interaction-mode.md §🟢）； 标准模式下必须调用 ask_followup_question 弹出推进选项：

选项	说明
▶️ 继续步骤 6（质量验证）	编码后置钩子通过，进入 Build/Lint/Test 等验证
⏸️ 暂停，我有补充/疑问	暂停等待用户输入
🔁 回退步骤 5 补充修改	L1 审查或自检发现需要回到编码阶段

精简模式豁免：步骤 5.5→6 属于 step-router.md §「步骤流转交互规则」豁免范围，精简模式下自动推进。

结构化完成标记（必须输出，缺字段视为未完成）

{
"step": 5.5,
"name": "编码后置钩子",
"status": "completed",
"outputs": {
"l1_review_result": "passed | fixed_N_issues | skipped_no_changes",
"red_issues_fixed": 0,
"yellow_issues_decision": "all_fixed | all_skipped | partial_fixed | none",
"doc_synced": true,
"lint_pre_check": "pass | has_issues | skipped_no_changes",
"pending_lint_issues": "0 | N（待 6.V3 裁决的 warning 数）",
"i18n_5_5d": "fixed_all | skipped | deferred | no_issues | not_executed"
},
"working_context_updated": true,
"next_step": 6
}

完成标记校验规则：

• lint_pre_check 不能为空（必须做过预检）
• lint_pre_check=has_issues 时 pending_lint_issues 必须为非零数字
• 编译级错误（语法/类型）必须在 5.5c 当场修复，禁止传递到 6.V3
• l1_review_result 不能为空
• i18n_5_5d 不能为空（5.5d 即使跳过也需填写 no_issues 或 not_executed）
• 四个子钩子（5.5a/5.5b/5.5c/5.5d）全部完成后才能输出此标记
• status 为 completed 时才能进入步骤 6
• 📌 2026-05-29 字段调整：原 lint_clean: true 已替换为 lint_pre_check + pending_lint_issues，最终 lint 裁决在步骤 6.V3 完成（消除 5.5c / 6.V3 重复 lint）
• 📌 2026-07 新增：i18n_5_5d 字段为步骤 6A V8 兜底检测的行为输入（详见 step-6-verify.md §V8）