⚠️ 注意：本模板沉淀自特定项目，加载后请首先评估当前项目是否适用，切勿无脑套用。

⚠️ 使用前必读（给后来的智能体）

这份文件是"某个项目里跑出来的一套工作流模板"，不是通用标准。 它来自一个真实项目连续数十轮任务的复盘（含失败的返工），因此带有那个项目的形状： 一次一条命令的授权方式、特定的门禁命令、特定的留档目录。

请先做三件事，再决定要不要采纳：

1. 判断适配性：本项目的"完成"怎么定义？门禁是什么？谁能批准？留档放哪？ 若与模板不符 —— 改模板，不要改事实。
2. 只取能对上的部分：8 个节点里通常 5~7 个能直接对上；对不上的（例如没有独立验收人）就删掉该节点， 并在你自己的流程文档里写明"为什么删"。
3. 返工环必须保留：只画直线（侦察→实现→验证→提交）的流程会骗人。真实项目一定有返工。

另：文中的"卡片 / 改动编号 / commit hash"是该项目的原始记录，仅作实证注解，不要照搬其命名。

工作流模板 1：从症状到验收（8 节点 + 5 条返工边）

适用

• 需求 / 故障驱动的单次任务（有明确的"要修什么 / 要做什么"）
• 跨会话接手（配一份"项目状态文档"一起用：流程看这份，状态看那份）

不适用

• 纯探索性调研（只为搞清一件事、不打算改代码）—— 只走节点 1~2
• 事故应急（源码损坏 / 环境变量损坏等）—— 直接进对应的事故恢复技能，不走完 8 个节点

流程形状（★ 带返工环，不是流水线）

                     ┌──────────────── 返工环（真实发生过，必须画出来）────────────────┐
                     │                                                                  │
  ┌──────┐   ┌──────┐│  ┌──────┐   ┌──────┐   ┌──────┐   ┌──────┐   ┌──────┐   ┌──────┐
  │ 侦察 │──▶│ 报告 │┴─▶│ 拍板 │──▶│ 实现 │──▶│ 验证 │──▶│ 门禁 │──▶│commit│──▶│ 验收 │
  └──────┘   └──────┘   └──────┘   └──────┘   └──────┘   └──────┘   └──────┘   └──────┘
      ▲                                │          │          │                     │
      │      ┌──── 退回收侦察 ◀────────┘          │          │                     │
      │      │                                     │          │                     │
      │      └──── 验证红 ⇒ 改实现 ◀───────────────┘          │                     │
      │                                                       │                     │
      │   门禁红 ⇒ 回滚 / 改架构（判据见「何时该回滚不改」）┘                     │
      │                                                                             │
      └──────────── 验收打回 ⇒ 回到"侦察"（不是回到"实现"）◀───────────────────────┘

五条返工边（为什么必须有）

节点详表

⚠️ 只有人能验收 —— "完成"是决策者的动作，不是执行者的自评。

横切关注点（不占节点，但每步都适用）

① 授权与范围

• 高危动作（删文件、改配置、动用户数据、放宽权限）逐条说明理由并取得同意； 授权粒度按项目风险定（高风险项目 = 一次一条）。
• 权限被拒时按提示重试一次并附理由，不要反复试；被拒本身是信息，写进报告。

② 留档分层（过程产物 vs 结论）

③ 新教训（本模板第二轮补充）

• 编译通过 ≠ 可运行：改完必须真跑（NameError / UnboundLocalError 都发生在"编译绿"之后）。
• 验收指标只对目标敏感：别把无关信号算进阈值（例：中文全角括号因折行单独成行 vs 英文括号）。
• 门禁输出为空 = 失败：重定向到不存在目录会得到空文件，必须显式判空。

可移植规律（跨项目）

项目状态文档骨架（与流程配套，11 节）

两条元规则（骨架里必须固化）

1. 每条遗留必须带"触发条件" —— 否则接手者不知道什么时候该动它；
2. 每条"不改"决策必须带"理由 + 当时数字" —— 否则下一个人会重新提一遍。

移植到新项目（清单）

1. 复制本文件当骨架，保留第 1~8 节点与 5 条返工边（这是骨架主体）。
2. 替换三处项目特化：门禁命令、留档目录、授权方式。
3. 删掉对不上的节点（并在你的文档里写明"为什么删"）。
4. 新建你的"项目状态文档"（用上面的 11 节骨架），先把第 8 节写起来。
5. 把"挂哪些技能"换成你实际拥有的技能名（本模板末尾有索引示例）。
6. 第一次跑完后回来改模板：把你踩到的返工边补进"五条返工边"表。

维护

这份文件自己也要遵守的原则

• 只写"什么时候用哪份"，不重复技能正文（否则两处会打架）
• 每条结论尽量带实证（commit hash / 数字），不要写成"最佳实践"式空话
• 返工环不能删 —— 它是这份文件存在的理由（只画直线会骗人）

技能索引（迁移后口径：技能目录名，而非旧 .md 文件名）

实战案例与复盘

以下为该项目当时的一手记录，保留原始术语（卡片编号 / commit hash / 具体命令），仅作方法论的实证注解。

• 返工边 · 实现 → 侦察：卡片 H 的片级放宽第一次作用层错（在 region 级判"无中文"必然为假）⇒ 回侦察改在 region 内部再切一层（bbe6a00）；卡片 L 先出架构报告、用户确认"写代码"才动手（acefa66）。
• 返工边 · 验证 → 实现：卡片 M 的第一版修复按 493.23 钳制后仍越界 6.00pt ⇒ 改实现为 481.23（081ab05）。
• 返工边 · 门禁 → 回滚：集题本切片器重写架构错误 ⇒ 回滚到 23b6a5e； "重做"现场试做更差 ⇒ os.replace 放回备份（276baa7）。
• 返工边 · 验收 → 侦察：笔记 PDF "乱码"报回来 ⇒ 先侦察（是否 H2b 回归？）才动手， 结论是"新 tex 触发了预存在路径"（acefa66）。
• 节点内自环：乱码 → 越界 → 6pt 内边距 → …（一次侦察给不出结论是常态）。
• 规律 1 实证：卡片 L 先出架构报告（含 5 组反例、函数位置、边界），用户确认后才写代码（acefa66）。
• 规律 5 实证：卡片 L：实现一张（acefa66）、测试+截图一张（5d12857）； 卡片 O：实现一张（e2d3838）、文档一张（98e3a9f）。
• 规律 6 实证：卡片 L/M：--selftest 绿了，仍要用用户那条真实数据重跑（verify_L：文字层 62 → 141 字）。
• 本项目形态（节点详表末列）：门禁 = python -m src.main --selftest / --smoke； 跑时输出先落文件再读（控制台会把中文转 GBK）；探针写 data/tmp/（gitignore）； A/B 截图 → docs/screenshots/<卡片名>/；commit 消息写文件 + git commit -F（绝不用 -m）。
• 两份历史遗留教训（本模板第 3 条横切由此而来）：NameError: name 'logging' is not defined （编译绿、运行炸，自检 44/1）；UnboundLocalError: cannot access local variable 'hit' （从相邻函数复制代码带进孤儿变量，四份 PDF 全部 build 失败）。