@xgent-ai/skills 0.1.0 → 0.4.0

package/skills/dev-plan/references/architecture-quality.md

@@ -0,0 +1,141 @@
+# 架构质量检查（复杂计划按需读取）
+
+本参考用于新增共享模块/跨系统契约、结构性重构、远程或外部依赖、数据生命周期变化、不停机迁移，以及显著可靠性或运维风险。简单局部改动不要为了填满本文件而扩大设计。
+
+## 1. 区分事实、决策、假设
+
+- **事实**：本次从用户、代码、配置、运行结果或项目规则确认的现状，带来源。
+- **决策**：在约束下选择的未来做法；不能伪装成“代码已经支持”。
+- **假设**：暂缺证据但方案依赖的前提，必须带验证办法、影响、责任人和最晚确认点。
+- **目标**：用户或项目承诺的结果；数值必须有来源。行业常见值只能用来提出问题，不能直接写进计划。
+
+计划头记录调查日期、commit SHA 与 dirty 状态，避免事实脱离代码快照。
+
+## 2. 模块、接口与接缝
+
+- **模块**：拥有一组行为与实现的单元，可小到函数、大到跨层业务切片。
+- **接口**：调用者正确使用模块必须知道的全部内容，包括入口、参数、不变量、调用顺序、错误模式、配置和性能特征。
+- **接缝**：无需修改调用点即可替换行为的位置。
+- **适配器**：在接缝处满足接口的具体实现。
+- **深度**：调用者学习较小接口即可获得较多行为；深模块把复杂度藏在内部。
+- **局部性**：规则、修改和验证集中在拥有它的模块，而不是散落到多个调用者。
+
+对关键模块填写：
+
+| 模块 | 调用者 | 接口与不变量 | 接缝 | 隐藏的复杂度 | 依赖 | 测试面 |
+| --- | --- | --- | --- | --- | --- | --- |
+| <名称/路径> | <谁调用> | <入口、顺序、错误、配置、性能> | <替换点或“无”> | <集中拥有的策略> | <分类> | <通过接口观察什么> |
+
+检查：
+
+1. **删除测试**：删除该模块后，复杂度会消失还是散回多个调用者？消失说明它可能只是转发层。
+2. 能否减少入口或参数，并把排序、重试、权限、状态转换等规则藏到模块内？
+3. 接口是否泄漏数据库结构、传输细节或只为测试存在的内部控制？
+4. 测试是否通过同一接口观察结果？内部重构不应迫使行为测试整体重写。
+5. 新抽象是否至少集中一项真实复杂策略或服务多个调用者？“以后可能有第二个实现”不是充分理由。
+
+## 3. 依赖分类与测试替身
+
+| 类别 | 例子 | 设计与测试策略 |
+| --- | --- | --- |
+| 进程内 | 纯计算、内存状态 | 直接合并进深模块，通过外部接口测试，无需适配器 |
+| 本地可替代 | 本地数据库、文件系统、嵌入式实现 | 使用真实的轻量本地替身；接缝可留在模块内部 |
+| 远程但自有 | 自己维护的 HTTP/gRPC/消息服务 | 在网络接缝定义 port；生产适配器走真实传输，测试用内存适配器 |
+| 真正外部 | 支付、短信、第三方 SaaS | 注入最小 port；生产适配器封装供应商语义，测试使用 mock/fake |
+
+只有一个真实实现且测试可直接使用它时，接缝通常是假想的。生产实现与测试替身确实不同，或同一策略需要服务多个调用者时，接缝才开始产生价值。内部测试接缝不要暴露成公共接口。
+
+## 4. Design It Twice
+
+下列决策至少设计两个有实质差异的候选：新模块接口、接缝位置、系统形态、跨服务协议、数据归属、可靠性等级、迁移/兼容策略。简单、局部、可逆选择跳过。
+
+先写共同约束，再比较：
+
+| 维度 | 候选 A | 候选 B |
+| --- | --- | --- |
+| R/NFR/C 适配 |  |  |
+| 接口深度与调用成本 |  |  |
+| 规则局部性 |  |  |
+| 兼容与迁移成本 |  |  |
+| 失败与恢复 |  |  |
+| 运维与可观测性 |  |  |
+| 测试面 |  |  |
+| 引入成本与未来触发点 |  |  |
+
+候选必须都可行，不能把明显错误方案当陪衬。若协作代理已获授权且问题足够复杂，可让不同代理独立设计候选；普通计划不强制使用代理。
+
+## 5. ADR-lite
+
+只用于高影响、难回退或跨团队决策：
+
+    ### ADR-<n>：<标题>
+    - 状态：Proposed / Accepted / Blocked
+    - 背景与驱动：<要解决什么；关联 R/NFR/C>
+    - 备选：<至少两个真实方案及淘汰理由>
+    - 决策：<选择及证据>
+    - 正面后果：<获得什么>
+    - 负面/中性后果：<成本、运维、锁定、兼容影响>
+    - 重新评估触发：<达到何种规模、故障、成本或需求变化时重审>
+
+普通可逆选择留在决策表，不另造 ADR。
+
+## 6. NFR 与约束账本
+
+只评估被本次改动影响的类别：
+
+| ID | 类别 | 当前基线/来源 | 本期目标 | 超限或失败行为 | 设计机制 | 验证 | 状态 |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| NFR-1 | 性能/容量/可用性/可靠性/安全/隐私/可观测性/运维/成本/可维护性 |  |  |  |  |  | 已知/未知/阻塞 |
+
+- 未提供数值时写“未知”，并说明它影响同步/异步、单库/分片、缓存、队列、批大小等哪个选择。
+- 不为假想规模预埋基础设施。记录当前方案的瓶颈和触发下一阶段架构的可观察条件。
+- 安全与可靠性目标必须可验证；“高性能”“高可用”“可扩展”不是目标。
+
+## 7. 数据生命周期与迁移
+
+逐张受影响表/对象检查创建、更新、删除、转移、失效、归档和恢复：
+
+- FK、NOT NULL、UNIQUE、软引用与声明的回退语义一致。
+- 快照字段的每条写路径从服务端权威来源生成，不信前端传入的派生值。
+- 热查询的过滤/排序/关联列有现有索引或迁移增量，索引名称与查询形状写清。
+- 涉及滚动发布时使用兼容阶段：**expand → migrate/backfill → 切读写 → contract**。
+- 写清新旧版本兼容窗口、双写/回读策略、批次与断点、幂等重放、失败恢复、回滚条件和不可逆点。
+- 回滚不是一句“回滚版本”：明确代码、schema、数据和外部契约分别能否回退。
+
+## 8. 失败模式与运行闭环
+
+高影响运行路径填写：
+
+| 失败/触发 | 爆炸半径 | 数据后果 | 用户表现/降级 | 检测 | 恢复/补偿 | 验证 |
+| --- | --- | --- | --- | --- | --- | --- |
+
+至少走查：依赖不可达/超时、部分成功、重复投递、乱序、进程崩溃、并发写、配额耗尽、凭证失效、迁移中断和回滚。按实际改动裁剪。
+
+后台任务/队列明确原子认领、租约或截止时间、僵尸恢复、幂等键、重试退避、终态与人工补偿。普通请求中的 check-then-write 明确条件写、唯一约束或事务锁。
+
+检测必须落到现有日志、指标、追踪、审计、健康检查或告警入口；若仓库没有能力，列精确增量或把运行承诺降到可证明的水平。
+
+## 9. 行为级核实
+
+对计划真正依赖的行为逐项核到代码：
+
+- **分页/批量**：offset/cursor 是否推进；重复调用是否永远返回同一批；边界与稳定排序是什么。
+- **限流/配额**：数值、作用域、计数窗口、超限是排队、拒绝还是降级。
+- **鉴权**：claims 的真实形状、scope/role/permission/bypass 的传播路径和失效时延。
+- **密钥域**：使用哪个密钥/env、轮换与灾备、数据是否绑死在其他模块的密钥上。
+- **框架错误面**：schema/中间件/业务闸的执行顺序，最终 HTTP 与业务错误语义。
+- **事务与投递**：发射点在事务内外、崩溃时是否丢失、实际是 at-most-once、at-least-once 还是 best effort。
+- **删除与失效**：引用目标删除、转移或失权后，现有数据如何显示和授权。
+
+## 10. 交叉一致性
+
+发出前逐项反查：
+
+- 机制使用的 scope、凭证、角色、开关和 env 在配置/种子/部署路径中确实存在，并从 UI/载荷逐跳到服务端真闸。
+- 每个调用者使用的接口字段、错误和顺序与接口定义一致；适配器没有偷偷扩大能力。
+- 数据约束、删除语义、快照来源、迁移顺序和回滚承诺互不冲突。
+- 验证断言在设计中有依据；设计的 R/NFR/C 在验证或显式人工验收中有落点。
+- 新错误码、共享导出、配置键、指标、事件类型和部署字段都有登记点。
+- 同一格式、上限、通知语义或可靠性承诺在所有章节保持一致。
+- 失败模式中的检测与恢复能力在改动面和里程碑中有实现项。
+- Ready 计划不存在会改变范围、安全、数据、外部契约或关键 NFR 的未决假设。

package/skills/dev-plan/references/execution-workflow.md

@@ -0,0 +1,25 @@
+# 依赖与并行调度：写计划与评审时用
+
+写计划时细化里程碑的依赖与并行边界、评审时核对编排能否安全执行，读本文件。实施者不读它：实施需要的并行、回写与记录约定已原样写进计划的「实施者定位」「实施进度」两节（见 `plan-skeleton.md`），改这里的规则时同步改那两节。
+
+## 并行执行
+
+每次调度前检查依赖与当前工作树。有独立任务、工具可用且并行收益超过委派与集成成本时，使用 subagents；主 agent 处理不冲突的任务或集成准备。小任务直接完成，不为凑数量拆任务。
+
+### 哪些任务可同时启动
+
+- 前置成果已通过所需检查，输入/接口契约已稳定；依赖落到实际成果与检查 ID，不默认等待上游里程碑全部终验。数据/安全/发布风险门及用户约定的分期门不能绕过。
+- 区分开发、集成和终验前置：稳定契约下可先用 fixture 开发；真实接口可用后再联调，同环境的 API/UI 主路径集中走查。局部检查通过不代替阶段终验，集成与评测放明确的收口里程碑负责。
+- 写入的文件集合互不重叠，不会在另一个任务仍依赖的文件中改接口/导出/行为。共享类型、公共入口、锁文件、生成产物和迁移序号指定一个负责人，先确定契约或串行集成。
+- 测试和运行资源互不影响：共享数据库、种子/迁移、端口、开发栈重启、同一浏览器会话或外部环境写入需隔离或串行。独立 worktree 只能隔离文件，不能自动隔离这些资源。
+- 无法证明独立就先串行完成前置或重新划界。用户要求串行、工具不可用或资源受限时如实说明，按可用并发数调度，其余串行，不虚构已启动的 subagents。
+
+### 委派、交付与集成
+
+主 agent 给每个 subagent 一份精简任务说明：目标及章节/需求/检查 ID、已稳定契约、可写与禁改路径、运行资源、需回报的阻塞。不复制整段聊天或无关历史；工具支持时选择最小上下文，让 subagent 按需读取规则和相关文件。
+
+**模型默认继承**：如无特别要求，subagent 使用与主 agent 相同的模型。启动工具支持继承时省略模型覆盖参数；必须显式指定时填写主 agent 的模型。只有用户或适用指令明确要求其他模型时才覆盖，不自行因任务难度、成本或速度降级/换模型。
+
+每个文件同一时间只有一个写入者。**计划与里程碑记录由主 agent 单写**；subagent 返回结果、改动路径、验证命令/环境/基线/结果与缺口，主 agent 归入对应记录，默认不另建任务文件。复杂交接或证据确需独立保存时才指定任务记录路径并链接。任务结束、阻塞或暂停时及时交付；不得替其他 agent 修改文件或回滚他人改动。边界变化先回报，主 agent 调整分工后再继续。
+
+主 agent 审查交付与 diff，完成里程碑规定的检查；已通过且相关代码、配置、依赖、输入与环境未变的证据可引用，受影响检查重跑，收口仍做必要集成回归。有任务失败则保留成果，只阻塞依赖任务。里程碑完成立即回写，下游只需部分成果时保存其前置检查证据即可推进。结束对话前收集或停止尚在运行的任务，记录可接续状态。

package/skills/dev-plan/references/plan-skeleton.md

@@ -1,101 +1,276 @@
-# 通用开发计划骨架(项目无自带模板时的兜底)
+# 通用开发计划骨架（dev-plan 默认模板）
 
-> 使用方式:照抄章节结构;`<尖括号>` 为占位;写作指引(引用块)写完删掉。
-> 目标读者是**实现者**(人或 Agent),他们只执行、不重开设计讨论——所以决策、边界、验收必须在这份文档里一次说死。
+> 除非用户显式指定其他模板，dev-plan 一律使用本骨架，不依赖目标仓库存在模板文件。
+> 按改动面与风险裁剪章节；删除不适用的占位和写作指引，不为满足形式填充内容。
+> 目标读者是后续实现者，因此事实、决策、接口、迁移、失败和验收必须闭环。
+> 同一信息只展开一次：已有 PRD 用 ID 与来源引用，账本已含完整设计/验收落点时删 §13；其余章节与里程碑引用定义和检查 ID。模块内测试就近完成，昂贵集成验收按可行性集中到阶段收口，独立风险门保留。
+> 同理，写作过程不进计划：用了哪份 skill、骨架或参考资料，读过哪些规则文件、哪些确认无约束，调查、复核与评审改稿的经过，以及“本次只写计划、未实施”这类写作当时的状态，实现者都不需要知道；计划只陈述当前结论。
+> 仓库规则里真正约束实现的条目落成 §0.1 的 `C-*` 或 §12 的一行一坑，带规则路径与被约束的具体行为。
+> 开头的「实施须知」与「实施者定位」「实施进度」两节是实施期的完整合同：实施者只读计划、不加载本 skill，所以实施需要的规则只能写在这两节里。「实施须知」与两节的协议文字原样带入，其中唯一的填空是 `<进度校验命令>`；恢复快照与完成记录按真实状态初始化。
 
 ```markdown
-# <代号> · <项目名> · <功能名>(<形态> · <4-8 个关键架构特征,用 " · " 串起>)
+# <代号> · <项目名> · <功能名>（<形态 · 关键架构特征>）
 
-> 站在 <本计划依赖的既有模块/文档,带路径链接> 之上。
-> 本期交付:**<一段话说清交付物形态与核心能力>**。
-> 本期的独特职责:<一句话定位;与最相近既有物的差异对照>。
-> **<顶层排除:最容易被误解为在范围内的东西,第一屏就排除>**。
+> **实施须知：实施或续做本计划时不要加载 `dev-plan` skill。** 它只用于撰写和评审计划；实施所需约定已全部写在下方「实施者定位」「实施进度」两节，加载它只会白占上下文。
+>
+> **计划状态：<Ready / Proposed / Blocked>**
+>
+> 调查基线：<YYYY-MM-DD> · <commit/version> · <clean/dirty；dirty 时说明事实基于当前工作树>。
+>
+> 本期交付：**<交付物形态与核心能力>**。
+> 本期独特职责：<与最接近现有能力的差异>。
+> **顶层排除：<最容易被误解为在范围内的内容>**。
 
-## 0. 本期范围与决策
+## 实施者定位
 
-<一句话定性:难点不在 <别人以为难的>,而在 ①… ②… ③…>
+执行本计划的 agent 是**资深软件工程师**，依据本计划、仓库规则和当前代码实施。
 
-| # | 决策点 | 选择 | 含义 |
+- **表达与源码**：报告用路径、需求/检查/里程碑 ID 定位，不复述计划。源码不放需求编号、agent 标记或规划元数据，注释解释必要原因；追溯放记录或提交说明。
+- **完成的定义**：本里程碑退出检查全部通过才能记完成；未运行、失败、环境缺失分别记缺口，不冒充通过。集中到阶段收口的终验由收口里程碑负责，通过前不宣称整期或跨期需求已验收。
+- **工作顺序**：需要行为测试的改动先红、再绿、再重构。按实际前置成果及检查推进，不等无关终验，数据、安全、发布及用户分期门不得绕过；稳定契约下可用 fixture 开发，不能替代真实集成。按 §9 执行局部检查与集中验收，同环境走查可合并；相关代码、配置、依赖、输入与环境未变可引用已通过证据，否则重跑受影响检查，收口仍跑必要集成回归。
+- **并行交付**：独立任务在收益超过委派/集成成本且工具可用时使用 subagents，模型默认继承。任务说明只给目标/ID、稳定契约、可写与禁改路径、运行资源和检查；共享文件单人负责，数据库、端口、浏览器等隔离或串行。子 agent 返回结果、路径、验证证据与缺口，默认不另写任务文档；主 agent 审查并集成验收。边界变化先回报，失败只阻塞依赖任务；结束对话前收集或停止仍在运行的任务。
+
+## 实施进度（实施期持续更新）
+
+本节是跨对话恢复的**唯一汇总入口**，协议文字不随实施改写，实施期只更新「恢复快照」和「完成记录」。续做时先读仓库规则、本节、当前任务相关正文与依赖，再核对 `git status` 和相关 diff；记录与工作树不符时先查明原因，不凭记录覆盖用户改动，也不凭代码存在推断验收已通过。只有继续未完任务、核验前置验收、排错或审查时，才按链接读取对应记录的相关部分；不要默认加载全部记录或原始日志。
+
+**回写时机**：里程碑完成后立即回写，再报告完成或提交；下游只需部分成果时，所需前置检查通过并在记录保存证据即可推进。实质进展后受阻、暂停、交接、发现偏差或结束对话时也保存成果与缺口；普通子任务切换不单独回写。
+
+**一次回写**：主 agent 更新对应记录，再同步快照变化字段和完成记录一行，不重写无变化内容或追加流水。快照写当前任务、进展与下一步，命令及证据只进记录。首次回写删占位行，每个已记进展的里程碑恰好一行，状态仅「进行中 / 阻塞 / 已完成」；完成时移至已完成行末，最近完成取该行。更新时间带时区，摘要 1–2 句，记录填相对计划的链接（如 `[M1 记录](FEATURE.records/M1.md)`）。范围、决策、接口、数据、风险或退出条件有偏差时，就地修订对应正文，不追加勘误历史。
+
+**独立记录**：按需建 `<计划名>.records/M<n>.md`，头部写计划链接、更新时区、状态及验证基线（commit SHA；未提交写 dirty@起始SHA 与关键改动路径）。正文只写交付行为/路径、必要偏差、未完项与继续动作；验收按 `检查 ID/覆盖范围 | 命令或步骤 | 结果/必要证据` 记录，共同环境和基线在头部写一次，有差异再单列。同一测试组可覆盖多条退出条件，须逐条可追溯；引用原证据与复用依据，不复制断言全文、成功日志或调试流水。未运行、失败、环境缺失明确区分；只有复杂交接、排错或证据需独立保存时才另建任务记录/日志/截图并链接。
+
+**回写后自查**：「当前进度 n/N」的 N 等于里程碑总数，n 只计状态为「已完成」的行；「最近完成」对应最后一条已完成记录，不按编号推算；链接指向已落盘文件。每次回写后运行 `<进度校验命令>`：它只查上述结构、计数与链接存在性，不证明验收真实通过。
+
+### 恢复快照
+
+- 最近更新：<尚未开始；实施后写 YYYY-MM-DD HH:mm + 时区>
+- 当前进度：0/<里程碑总数> 个里程碑完成
+- 当前状态：<尚未开始 / 进行中 M<n>（可并列多个）及一句实质进展 / 阻塞 / 已完成>
+- 最近完成：无
+- 下一步：M1 · <第一个可执行动作与退出条件>
+- 当前阻塞：<无；或阻塞事实、影响与解除条件>
+- 代码基线：<当前核对的 commit SHA；未提交写 dirty@起始SHA；具体路径与各次验证基线只写独立记录>
+
+### 完成记录
+
+| Milestone | 状态 | 更新时间 | 简要记录 | 实现与验收记录 |
+| --- | --- | --- | --- | --- |
+| — | — | — | 尚未开始任何里程碑 | — |
+
+<初稿保留上面的占位行，不预建空记录、不填写虚假完成事实；本条写作指引不带入计划。>
+
+## 0. 需求、范围与决策
+
+### 0.1 需求与约束账本
+
+| ID | 类型 | 来源 | 内容 | 设计/验收落点 | 状态 |
+| --- | --- | --- | --- | --- | --- |
+| R-1 | 功能 | <用户原话> | <可观察的业务能力> | <章节 + 验收> | 已确认 |
+| NFR-1 | <性能/可靠性/安全/...> | <用户/规则/代码；未知则写未知> | <目标或待确认问题> | <机制 + 验证> | 已知/未知/阻塞 |
+| C-1 | 约束 | <规则/代码路径> | <技术栈/兼容/交付约束> | <影响章节> | 已确认 |
+| A-1 | 假设 | <为何暂时依赖> | <假设内容> | <验证办法 + 责任人 + 最晚确认点> | 开放/阻塞 |
+
+<已有 PRD 沿用其 ID，内容仅写能力摘要或本期差异，不重抄需求/验收原文；设计/验收落点引用正文和 §9 检查 ID，不能只有里程碑编号。只列相关 NFR，不编造数字。本表已完整覆盖映射时删除 §13。>
+
+### 0.2 决策表
+
+| # | 决策点 | 选择 | 含义/影响 | 依据 |
+| --- | --- | --- | --- | --- |
+| D1 | 形态 | <选择> | <部署、既有代码、边界和零改动声明> | <R/NFR/C + 代码路径> |
+| D2 | <接口/协议/权限/数据归属/...> | <选择> | <正负后果> | <证据> |
+
+### 0.3 ADR-lite（仅高影响、难回退决策）
+
+#### ADR-1：<标题>
+
+- 状态：<Proposed / Accepted / Blocked>
+- 背景与驱动：<关联 R/NFR/C>
+- 备选：<至少两个真实可行方案及淘汰理由>
+- 决策：<选择及证据>
+- 正面后果：<收益>
+- 负面/中性后果：<成本、运维、锁定、兼容影响>
+- 重新评估触发：<规模、故障、成本或需求变化>
+
+### 0.4 职责与事实所有权
+
+|  | <系统 A> | <本模块/本期> | <系统 B> |
 | --- | --- | --- | --- |
-| 1 | 形态 | … | <对部署/既有代码/边界的影响;能"零改动"的明说> |
-| 2 | <协议/凭证/权限/数据归属/复用策略…> | … | … |
+| 拥有 | <事实/策略/恢复责任> | <事实/策略/恢复责任> | <事实/策略/恢复责任> |
+| 不拥有 | <红线> | **<绝不顺手承担的职责>** | <红线> |
+
+一句话：<把职责与失败恢复责任切死>。
+
+### 0.5 明确不在本期
+
+- **<相邻功能>**——<去向：二期 / 另立项 / 依赖某能力 / 明确放弃>。
+
+## 1. 当前事实与改动面
+
+### 1.1 现状与缺口
+
+- **已核实**：<现有行为>（<路径/符号>）。
+- **缺口**：<现状不能满足什么> → <最小增量> → <漏做后果>（<路径/符号>）。
+- **未核实阻塞**：<缺失证据> → <影响的决策> → <解除办法>。
+
+### 1.2 拓扑与文件清单
+
+<列出受影响的 workspace/包/模块/配置/脚本；★ 标新增。增量型同时写清无需修改的邻接面及依据。>
+
+<仅当三个以上节点、异步时序、所有权或状态迁移难以用文字看清时加入最小图。>
+
+## 2. 模块、接口与依赖（结构性设计时使用）
+
+| 模块 | 调用者 | 接口与不变量 | 接缝 | 隐藏复杂度 | 依赖分类/适配器 | 测试面 |
+| --- | --- | --- | --- | --- | --- | --- |
+| <名称/路径> | <调用方> | <入口、顺序、错误、配置、性能> | <替换点或无> | <集中拥有的规则> | <进程内/本地可替代/远程自有/外部> | <通过接口观察的结果> |
+
+<说明候选接口比较、删除测试，以及为什么需要或不需要新接缝。>
 
-### 0.1 职责边界:<X> 拥有什么,本模块拥有什么
-|  | <系统A> | <本模块(本期)> | <系统B> |
+## 3. 数据模型与迁移（涉及持久化时使用）
+
+| 表/对象 | 关键字段与约束 | 生命周期/权威来源 | 查询与索引 |
 | --- | --- | --- | --- |
-| 拥有 | … | … | … |
-| 红线 | — | **<本模块绝不做的事>** | … |
+| <名称> ★ | <类型、FK/软引用、NOT NULL、UNIQUE> | <创建/更新/删除/失效/快照来源> | <查询形状 + 已有/新增索引> |
+
+### 3.1 兼容与迁移
+
+1. **Expand**：<向前/向后兼容的 schema/接口增量>。
+2. **Migrate/Backfill**：<批次、断点、幂等、双写/回读、失败恢复>。
+3. **切换读写**：<门、指标、灰度或版本窗口>。
+4. **Contract**：<何时删除旧列/旧接口，前置证据>。
+5. **回滚**：<代码/schema/数据/外部契约分别如何回退；不可逆点>。
+
+## 4. 集成与契约
+
+| 依赖/调用方 | 当前状态 | 行为级证据 | 本期处理 | 失败语义 |
+| --- | --- | --- | --- | --- |
+| <名称> | 已核实足够 / 已核实缺口 / 未核实阻塞 | <路径/符号 + 分页/鉴权/事务等语义> | 零改动 / 精确增量 / 阻塞解除 | <超时、重试、降级、错误> |
+
+<需要的配置、种子、权限、scope、事件、错误码和共享导出逐项列出登记位置。>
+
+## 5. 核心机制与服务端
+
+- **主流程**：<编号写透状态变化、幂等短路、并发控制、失败回退和每步凭证>。
+- **接口/路由**：<入口、参数、不变量、闸门顺序、业务与传输错误语义>。
+- **权限链**：<UI 可见性 → token/bootstrap/载荷 → 服务端真闸>。
+- **并发**：<条件写/唯一约束/事务锁；后台任务的认领、租约、僵尸恢复和计数原子性>。
+- **数据权威**：<派生/快照值的服务端来源；删除、转移、失权后的行为>。
+
+## 6. 前端与交互（涉及 UI 时使用）
 
-一句话:<把职责切分说死;实现期所有"要不要顺手做"回来看这句>。
+- 信息架构与角色视图：<入口、主路径、权限差异>。
+- 状态：<loading / empty / error / partial / disabled / success>。
+- 可访问性、响应式、主题、i18n：<项目规则 + 验证>。
+- 前端隐藏只改善体验，不能代替服务端授权。
+- 真实浏览器走查：<项目可用工具、主路径和关键边界；环境不可用时明确未验证>。
 
-### 0.2 关键取舍(显式记录而非默默处理)
-- **a. <标题>。** <选了什么、为什么>。代价:<显式承认>。缓解:<手段/兜底>。
-- <重点覆盖:降级路径、幂等/重试、安全收口、显式截断、最大回归风险及其门>
+## 7. NFR、安全与运行保障
 
-### 0.3 明确不在本期
-- **<最容易蔓延的相邻功能>**——<去向:二期/另立项/依赖某底座>。
+| ID | 基线/来源 | 目标或未知项 | 超限/失败行为 | 机制 | 验证 |
+| --- | --- | --- | --- | --- | --- |
+| NFR-1 | <路径/用户> | <可量化目标；未知则说明影响> | <拒绝/排队/降级/告警> | <设计> | <断言/观测> |
 
-## 1. 拓扑与改动面
-<涉及的模块/目录逐个列,★ 标新增;每条一两行写清承载什么;增量型写"增量清单 + 零改动声明">
-<端口/环境变量/脚本等新增项逐个列名 + 默认值 + 语义;与现状核对过不冲突>
+安全项逐条对应验证：鉴权、越权矩阵、租户/用户隔离、敏感数据、注入/SSRF/XSS、限流、审计与密钥轮换。只列与本期风险相关的项。
 
-## 2. 数据模型
-| 表 | 关键列 | 说明(语义 + 唯一键/索引) |
-| --- | --- | --- |
-<声明项目的数据约定:软引用/外键策略、排序字段规范、分页契约、迁移工具及其退路>
+可观测性逐条落到现有日志、指标、追踪、审计、健康检查和告警入口；不存在的能力列精确增量，不凭空承诺。
 
-## 3. 集成与契约
-<逐个上游:「已核实(`路径`):零改动」或精确增量(现状缺口 → 最小改法 → 漏掉的后果);没有第三种状态>
-<需要的种子数据/配置逐条编号,实现期照单执行>
+## 8. 失败模式、发布与回滚
 
-## 4. 服务端机制(核心业务)
-<鉴权链以哪个文件为模板;路由清单按分组列全 + 每组的闸;
- 本期最核心的 1-2 条管线用编号步骤写透(幂等短路、失败回退、每步用谁的凭证);
- 消费/写入的门逐道列出并注明"服务端强制,前端隐藏只是体验">
+| 失败/触发 | 爆炸半径 | 数据后果 | 用户表现/降级 | 检测 | 恢复/补偿 | 验证 |
+| --- | --- | --- | --- | --- | --- | --- |
+| <失败> | <租户/模块/全局> | <丢失/重复/延迟/无> | <可观察表现> | <日志/指标/告警> | <自动/人工步骤> | <故障注入/断言> |
 
-## 5. 前端
-<视图与信息架构按角色列;重头戏页面标出;空态/错误态/进行中态把关点;i18n 要求>
+- 发布顺序：<代码、配置、迁移、开关、依赖的顺序>。
+- 放量/切换门：<必须为绿的指标与断言>。
+- 回滚门：<何时回滚、由谁执行、数据如何处理>。
+- 简单局部任务若无新增运行期失败模式，写明依据后可省略表格。
 
-## 6. 安全清单(验收断言的来源)
-<每条都要能翻译成 §7 的一条验证断言——写不出断言的不算安全项;
- 覆盖:凭证存储、越权矩阵、租户/用户隔离、限流、敏感值不进 URL 与日志>
+## 9. 验证
 
-## 7. 验证
-### 7.1 自动化断言脚本 <每支一行写清覆盖面;标出核心;隔离/越权/招牌能力必有专门脚本>
-### 7.2 跨模块回归 <复用/扩展哪些既有验证>
-### 7.3 真实环境走查 <用"→"串出步骤级走查脚本,含故障注入与越权入口>
-### 7.4 静态校验 <类型检查/i18n 完整性等>
+### 9.1 行为与接口验证
 
-## 8. 里程碑(每步可验证)
-| # | 里程碑 | 内容 | 验证 |
+<按下表定义检查，后续里程碑与验收记录引用 ID。已有 PRD/测试定义用链接 + 本期增量断言，不重复展开；通过公开接口验证行为，避免绑定内部实现。>
+
+| 检查 ID | 需求/验收行与可观察结果 | 命令/入口与环境 | 执行时点 |
 | --- | --- | --- | --- |
-| M1 | <骨架+契约接入> | <重构先行的独立 commit + 回归门> | <断言点;"既有套件全绿"> |
-| Mn | <收尾> | <文档 + 挂总验证> | <全量回归 + 真实环境全链路> |
-
-## 9. 风险与开放问题
-- **<最大风险>**:<门/缓解>。
-- **开放问题(实现前确认)**:① <决策留白>;② <发现的全局缺口——不临时补也不放大,单列>。
-
-## 10. 已知坑(沿用既有教训)
-<一行一坑 + 出处;P0 加粗>
-
-## 11. 需求 → 设计映射(自检)
-| # | 需求 | 本期落点 |
-| --- | --- | --- |
-| R1 | <原始需求逐条> | <§号 + 机制名 + 验证脚本名> |
-| — | <项目硬约束> | … |
-| — | **不在本期**:<排除项汇总> | §0.3 |
+| V-1 | <需求 ID/验收行 + 新增行为/边界> | <实际测试入口与 fixture/环境> | <所需能力/环境就绪后；是下游前置则写清> |
+| V-2 | <跨模块主路径/API + UI> | <同一部署与用户/角色> | <阶段收口；可合并的走查范围> |
+
+<以下 §9.2–§9.5 只补本表未表达的回归、故障、真实环境与静态检查；已在表中定义则引用 ID 或省略对应小节。>
+
+### 9.2 集成与回归
+
+<复用/扩展哪些既有测试和脚本；跨模块契约、旧行为基线与兼容窗口如何验证。>
+
+### 9.3 NFR 与故障注入
+
+<容量/延迟/可靠性/恢复目标如何测；依赖超时、重复、部分失败、迁移中断如何注入。>
+
+### 9.4 真实环境与 UI
+
+<从登录/配置到核心结果的走查；角色、语言、主题、错误、另一租户/账户边界。同环境的 API/UI 走查合并执行，前期已核实的未变部分引用证据，收口验证受影响范围与完整主路径。>
+
+### 9.5 静态校验
+
+<项目实际提供的 typecheck/lint/build/schema/i18n/依赖检查命令。>
+
+## 10. 里程碑与验收安排
+
+<围绕可验证的能力/交付切片分组，不按模块或工种拆里程碑。同能力、同环境且无独立风险门可合并，内部任务保留局部检查；阶段收口集中昂贵集成、走查、故障演练和评测。发布、迁移、不可逆操作、安全边界和用户约定的分期门保留必要检查。>
+
+| # | 里程碑 | 前置依赖 | 内容与并行边界 | 验证/退出条件 |
+| --- | --- | --- | --- | --- |
+| M1 | <行为基线/骨架> | <实际需要的成果 + 前置检查 ID，不默认等整个里程碑> | <最小改动；独立任务与共享文件/资源归属> | <§9 局部检查 ID + 必要风险门>；回写「实施进度」 |
+| Mn | <阶段收口/终验> | <本阶段交付物齐备 + 所需前置检查> | <统一部署、集成、走查、评测；负责人> | <§9 集成/终验检查 ID，覆盖本阶段全部验收>；回写「实施进度」 |
+
+<每行退出条件以「回写『实施进度』」结尾；只引用检查 ID 和本里程碑独有条件，不再抄需求验收清单。局部完成不等于阶段终验通过。>
+
+<依赖区分开发/集成/终验；已验证的子任务可解除对应开发前置，无关走查或发布排练不阻塞代码开发，除非用户分期或风险门要求。并行说明到可写路径与资源，按收益决定委派；共享契约先定、共享文件单人修改，统一集成，不为并行硬拆。>
+
+## 11. 风险、开放问题与就绪状态
+
+| 项目 | 影响 | 责任人/解除办法 | 最晚确认点 | 是否阻塞 |
+| --- | --- | --- | --- | --- |
+| <风险/问题/A-* / NFR 未知> | <范围/安全/数据/契约/排期> | <动作> | <里程碑前> | 是/否 |
+
+- 最终状态：**<Ready / Proposed / Blocked>**。
+- 定级理由：<为什么可以实施，或哪些项阻塞>。
+
+## 12. 已知坑与历史教训
+
+- <一行一坑 + 规则/事故/进度文档路径；说明本计划如何规避>。
+
+## 13. 需求 → 设计 → 验证映射（§0.1 未完整映射时使用）
+
+<与 §0.1 二选一作为完整映射入口；使用本节时 §0.1 不重复设计/验收落点，不重抄需求内容。>
+
+| ID | 需求/约束/假设 | 设计落点 | 验证/解除办法 | 结果 |
+| --- | --- | --- | --- | --- |
+| R-1 | <内容> | <章节 + 机制> | <断言/走查> | 覆盖 |
+| NFR-1 | <内容> | <章节 + 机制> | <测试/观测> | 覆盖/阻塞 |
+| C-1 | <内容> | <章节> | <静态/运行检查> | 覆盖 |
+| A-1 | <内容> | <依赖的决策> | <验证办法> | 已解除/阻塞 |
+| — | **不在本期：<汇总>** | §0.5 | <去向> | 排除 |
 ```
 
-## 写作自检(发出前过一遍)
-
-- [ ] 决策表每行都有「含义」——只写选择不写影响的决策等于没做。
-- [ ] 每条取舍都有**代价**字样;每个排除项都有去向。
-- [ ] 每个上游契约要么「已核实(路径)」要么列了精确增量——没有第三种状态。
-- [ ] 里程碑表每行「验证」列非空,最后一行落到全量回归 + 真实环境走查。
-- [ ] §6 安全清单每条能对应 §7 的一条断言。
-- [ ] §11 映射覆盖全部原始需求 + 项目硬约束 + 排除项。
-- [ ] 已知坑节搬运了相关历史教训。
-- [ ] 交叉一致性:机制用到的凭证/scope 在配置清单中存在;验收断言与设计相符;承诺的不变量互不冲突;新增标识符(错误码/导出/env/部署值)都有登记点;同一口径的多处提及逐处对齐。
-- [ ] 上游行为级核实:分页推进/限流数值/claims 形状/密钥域/事务语义——计划依赖的行为与代码实际一致,不止"文件存在"。
-- [ ] 闸门顺序与错误面:多道闸写明顺序,承诺的错误码 = 第一道会失败的闸抛出的;权限位从 UI 可见性到服务端真闸逐跳追通。
+## 发出前自检
+
+- [ ] 默认使用本文件；未探测或依赖目标仓库中的模板。
+- [ ] 计划记录调查日期、commit/version 和 dirty 状态。
+- [ ] 除开头「实施须知」外，全文没有写作过程元信息：用了哪份 skill/骨架/参考、读过哪些规则文件的清单、调查步骤、评审处置与改稿经过、“本次只写计划”类状态；相关约束已落成 `C-*` 或 §12。
+- [ ] 顶部实施进度已按真实状态初始化，0/N、M1、里程碑总数和代码基线互相一致；没有预填虚假完成记录。
+- [ ] 「实施进度」的回写协议为骨架原文在位，`<进度校验命令>` 已替换；每个里程碑的退出条件都以「回写『实施进度』」结尾。
+- [ ] 计划只留简要进度与链接；记录按检查组保留可追溯证据，不默认建子任务文档，进行中/阻塞不计完成。
+- [ ] 依赖落到实际成果和前置检查；合并验收有覆盖范围与收口负责人，独立风险/分期门保留，局部通过不冒充终验。
+- [ ] 并行收益与边界明确，共享文件/资源单人负责或隔离，主 agent 集成验收并单写计划。
+- [ ] 开头“实施须知”与“实施者定位”为骨架原文，未改写、未删减。
+- [ ] R/NFR/C/A 在账本或 §13 全部映射，未重复展开需求/断言；未知数字未被伪造成目标。
+- [ ] 关键决策有真实备选、正负后果和重新评估触发；普通选择未被 ADR 化。
+- [ ] 复杂设计写清模块、接口、接缝、依赖分类与测试面；没有假想抽象。
+- [ ] 契约均为“已核实足够 / 已核实缺口 / 未核实阻塞”之一。
+- [ ] 数据约束与生命周期、迁移、兼容和回滚互相一致。
+- [ ] 失败模式的检测、恢复和验证在改动面与里程碑中有落点。
+- [ ] 验证通过接口观察行为；安全/NFR 条目均可断言或观测。
+- [ ] 复用/已核实路径真实存在，新增路径已明确标注。
+- [ ] Ready 计划没有影响范围、安全、数据、外部契约或关键 NFR 的未决项。