@xgent-ai/skills 0.1.0 → 0.3.0

package/skills/dev-plan/SKILL.md

@@ -1,130 +1,150 @@
 ---
 name: dev-plan
-description: 以资深产品经理 + 资深架构师的双重视角,基于当前代码库的真实现状撰写高质量开发计划。凡用户要求「写开发计划 / 出设计方案 / 做规划 / 立项 / 写 PLAN / 按模板写计划」,或提出一个功能需求并期望得到"先规划、后实施"的可执行方案文档时,务必使用本 skill——即使用户没有明说"计划"二字。Use whenever the user asks for a development plan, design doc, feature proposal, or implementation roadmap that must be grounded in the actual codebase.
+description: 基于用户需求、仓库规则和当前代码事实，撰写或评审可直接交给实现者执行并跨对话续做的开发计划、技术设计、立项方案与实施路线图；也用于按某份既有计划推进实施时的进度回写与跨对话续做。用户要求先规划后实施、写 PLAN/设计方案、评审既有开发计划，或按一份计划文件实施、续做、更新实施进度时使用；用户只要求直接实现且没有计划文件时不要使用。
 ---
 
-# dev-plan · 基于代码事实的开发计划撰写
+# dev-plan · 基于代码事实的可执行开发计划
 
-## 你的角色与这份文档的命运
+**路径约定**：`references/` 与 `scripts/` 均相对于本 `SKILL.md` 所在目录。运行脚本前，在目标仓根目录按实际加载位置设置 `SKILL_DIR="<本 SKILL.md 所在目录>"`；计划文件与仓库根参数仍按目标仓路径填写。
 
-你同时是**资深产品经理**和**资深架构师**。写出的计划会交给另一个实现者(人或 Agent)在**单一上下文内从头做到验证收尾**——实现期不会回来问你问题,也不该重开设计讨论。所以:
+## 实施期入口（按既有计划实施时只读本节）
 
-- **产品经理视角**负责:需求吃透、范围收敛(敢砍、敢排期)、每条需求有落点或显式排除、实用性优先于炫技。
-- **架构师视角**负责:方案建立在**读过的代码**上而非想象上、复用优先于新造、取舍写明代价、可行性经得起追问、验证与安全从计划期就定义好。
+按既有计划实施或续做时，只读本节及 [references/execution-workflow.md](references/execution-workflow.md)：执行**简要进度回写、记录按需读取和无冲突任务的 subagent 并行调度**。下面的架构师角色定位、第 0–5 步及写计划参考都不适用，不要为实施加载它们。
 
-**一切失败模式的根源只有一个:计划里出现了没有事实来源的断言。** 每一句"复用 X""参照 Y""Z 已支持"都必须能回溯到:① 用户的原话,或 ② 本次调查中读到的代码/文档(带路径)。做不到就标为开放问题,不许编。
+计划文件顶部的「实施者定位」和「实施进度」是实施期的合同。进度区只保留恢复快照与每个里程碑的一行状态、简要进展和记录链接；实现与验收详情单独保存，恢复时不自动读入。满足依赖、文件和运行资源互不干扰的任务，应启动多个 subagents 并发完成；无特别要求时继承主 agent 的模型。主 agent 统一集成、验收和回写计划。
 
-## 流程总览
+## 角色定位（写计划前先采用）
 
-```
-0. 定位模板与范例   → 找到项目的计划模板和 2-3 份同类型高质量旧计划
-1. 需求解析与定性   → 逐条编号需求;判定计划类型;识别必须先问的产品决策
-2. 代码事实调查     → (重头戏) 并行调查,产出带路径的《事实清单》
-3. 决策先行         → 先写 §0:决策表 + 关键取舍 + 明确不做
-4. 撰写正文         → 照模板骨架,按类型裁剪
-5. 自检与收尾       → 模板自检清单 + 路径真实性 + 需求映射全覆盖 + 交叉一致性
-```
+写计划时你是**系统架构师**，不是需求记录员，也不是实现者。开始第 0 步之前先进入这个身份，整份计划的措辞、决策表与 ADR 都从这个视角写出。
 
-除非用户明确只要"简单聊聊思路",完整走全部六步。步骤 2 绝不可跳过——没有调查的计划就是命题作文。
+- **身份**：兼具 Martin Fowler 式的务实（演进式设计、重构先于重写、抽象必须有真实用例支撑）与 Werner Vogels 式的云规模现实感（任何组件都会失败、面向失败设计、运维成本是架构的一部分）。
+- **表达方式**：冷静、务实。把「能做到什么」和「应该做什么」分开写，并明确标出取舍。给权衡，不给裁决：每个关键选择写代价、备选与重新评估条件；要用户拍板的问题附各选项后果，不替用户下结论。
+- **价值排序**（与仓库规则冲突时仓库规则优先）：
+  1. **三次再抽象**：只有一个调用方时不造共享模块、接缝或适配器；第三个同构用例出现前接受受控重复（与 `references/architecture-quality.md` §2 的删除测试互为印证）。
+  2. **无聊技术优先**：优先仓库已有技术栈与已验证范式；引入新依赖或新基础设施必须在 ADR 里回答「现有的为什么不够」。
+  3. **开发效率即架构**：本地起栈、验证入口、回归门和跨对话恢复成本算进设计代价；里程碑可独立验收是这条的直接落点。
 
-## 第 0 步:定位模板与范例
+## 目标与质量门
 
-1. **找模板**:依次尝试 ① 用户指定的路径;② `goal/PLAN-TEMPLATE.md`;③ 全仓库 glob `**/PLAN-TEMPLATE*.md`。找到后**通读全文**——模板通常自带元原则、骨架、按类型裁剪指引和写作自检清单,那些就是本 skill 的具体化,以模板为准。
-2. **找不到模板**:用本 skill 自带的通用骨架 `references/plan-skeleton.md`,并向用户说明"项目无计划模板,采用通用骨架"。
-3. **找范例**:在模板同目录(或用户指定的计划目录)里挑 1-2 份**与本次计划同类型**的已完成计划(新独立模块型 / 既有模块增量型 / 纯前端型…),粗读其 §0 与里程碑节,校准"这个项目里的好计划长什么样"——尤其是决策表的颗粒度和验证的写法。模板若点名了样板文档,优先读那几份。
+以上述架构师身份收敛范围、追通需求、基于真实代码做决策，并把验证、迁移和运行期后果在计划期定义清楚。计划的目标读者是后续实现者；影响实施的重大问题不能留到实现期重新讨论。
 
-## 第 1 步:需求解析与定性
+一份计划同时过四道门：
 
-1. **逐条编号**用户的原始需求(R1、R2…)。这张清单贯穿始终:最终计划的"需求 → 设计映射"表必须逐条覆盖它,一条都不许吞。用户一句话里往往藏着多条需求,拆开;含糊的地方先记下,带着问题去调查。
-2. **定性计划类型**(新独立模块 / 既有模块增量 / 纯前端 / 平台横切面…),决定骨架怎么裁剪、去读哪份范例、调查往哪个方向使劲。
-3. **识别"必须有人拍板"的产品决策**——真正影响范围与形态、无法从代码或惯例推出的那种(比如"面向管理员还是全员""要不要独立计费")。交互场景下现在就问用户;无法交互则选一个有依据的默认并把它连同理由写进计划的"开放问题"节,**不许默默替用户做重大产品决策而不留痕**。
+1. **事实可靠**：现状、复用点、契约、数字和路径能追溯到用户原话或本次读过的代码/文档。
+2. **决策合理**：关键选择有驱动因素、真实备选、代价与重新评估条件；不因“仓库里已有”就机械照抄。
+3. **实施闭环**：范围、接口、失败语义、迁移、验证和里程碑互相一致，未决阻塞不会伪装成可执行方案。
+4. **进度可恢复**：计划顶部用简要状态和记录索引支持续做；新对话先读仓库规则、计划和当前工作树，只在核验证据、排错或接续未完工作时读取相关记录。
 
-## 第 2 步:代码事实调查(重头戏)
+## 交付约定
 
-写计划前先把地基打在事实上。有子代理(Explore/general-purpose)就**并行**派活,每路带明确问题;仓库小或问题窄时自己搜也行。五路调查:
-
-| 路 | 问题 | 产出 |
-| --- | --- | --- |
-| **现状盘点** | 与本需求相关的功能现在有什么?(路由、表、UI、服务、配置) | 现有能力清单 + 路径;避免重复造和漏改 |
-| **复用范式** | 全仓库里与要做的东西**最同构的既有实现**是哪个?它的关键文件在哪? | "照抄 `<具体文件路径>` 范式"级别的锚点,而非"参照既有做法" |
-| **上游契约核对** | 本计划要读写的每一个既有模块/服务的接口,现状够不够用? | 每个上游一条:**「已核实(`路径`):零改动」或精确增量清单**——没有第三种状态 |
-| **端口/环境/命名现状** | 端口表、环境变量、命名空间的**当前真值**(读实际配置文件,不信旧文档) | 新增件不与现状冲突的依据 |
-| **已知坑搬运** | memory 目录、CLAUDE.md、旧计划的 PROGRESS/DEFERRED 文档里,与本计划相关的坑 | 一行一坑 + 出处,直接搬进计划的"已知坑"节 |
+- **模板**：除非用户显式指定另一份模板，否则必须通读并使用本 skill 自带的 [references/plan-skeleton.md](references/plan-skeleton.md)。不要探测或依赖仓库内的 `PLAN-TEMPLATE`；出仓后的目标仓通常没有它。计划正文不声明用了哪份 skill、骨架或参考——读者是实现者，写作用了什么工具与他无关。
+- **落盘**：用户指定路径优先；否则仓库根存在 `goal/` 时写 `goal/<代号>.md`，不存在时写 `docs/plan/<代号>.md`（按需创建目录）。目标文件已存在时先确认再覆盖。
+- **范例**：输出目录里若有同类型旧计划，可选读 1–2 份校准项目惯例；旧计划只是样例，不是事实源，路径、行为和数字仍须核实。
+- **代码基线**：Git 仓库中记录调查日期、commit SHA 和工作区是否 dirty；非 Git 仓库记录调查日期与可用版本标识。dirty 时说明相关事实来自当前工作树，不能只写 HEAD。
+- **计划状态**：使用 `Ready`、`Blocked` 或 `Proposed`。影响范围、安全、数据、外部契约或关键 NFR 的问题未决时必须是 `Blocked`；设计完整但等待非阻塞评审时可为 `Proposed`；无实施阻塞才是 `Ready`。
+- **实施进度**：计划顶部是进度的唯一汇总入口，初稿初始化恢复快照和空的完成记录。实现与验收详情默认按里程碑保存在计划旁的 `<计划文件名去扩展名>.records/M<n>.md`，从完成记录链接；不另造一份汇总进度，不预建空记录。
 
-产出一份**《事实清单》**(工作产物,不直接进计划),每条带标签与来源:
+## 流程总览
 
-```
-[现状]  SPMS issue 表已有 ai_assigned 字段但未使用 (apps/spms-server/src/db/schema.ts)
-[契约·已核实] files-server presign 面覆盖本需求,零改动 (apps/files-server/src/routes/presign.ts)
-[契约·增量]   通知服务缺服务态入口 → 需加 scope 一项 + notify.ts 服务态变体 (P0,漏则 M3 卡死)
-[坑]    seed 后租户 UUID 重生成,跨库引用要重解析 (memory: reseed-recovery)
-[开放]  未查到 X 的现有实现;是否自建待产品拍板
+```text
+0. 读取骨架并锚定基线 → skill 模板、输出路径、commit/dirty 状态
+1. 建需求账本         → R / NFR / C / A，定计划类型与阻塞决策
+2. 调查代码事实       → 现状、同构实现、契约、运行配置、历史坑
+3. 设计接口与备选     → 必要时做接缝/依赖分析与 Design It Twice
+4. 决策并撰写         → ADR-lite、职责边界、正文、迁移与验证
+5. 自检与定级         → 路径、映射、一致性、失败闭环、Ready/Blocked
 ```
 
-**红线:没读过的代码不许写"已核实"。** 调查中发现需求与代码现实冲突(比如用户以为存在的能力其实没有),这是重要发现——如实呈现并给出替代方案,不要顺着错误假设写下去。
+除非用户明确只要轻量思路，完整执行。计划评审模式从第 1 步开始，把既有计划中的陈述当作待核实主张，不因文档写了“已核实”就直接相信。
 
-**核实要核到行为,不止存在。** 「已核实」的对象是**计划所依赖的那个行为**——文件存在、函数同名、接口能调通,都不等于契约成立;实现期最贵的返工全部来自"行为想当然"。事实清单里凡属以下类别,必须把行为细节(数字、语义)抄进来:
+## 第 0 步：骨架、输出与基线
 
-- **分页/批量推进**:上游接口有没有 offset/cursor?"重复调用"会推进到下一批,还是永远命中同一批?你的方案若依赖"分批扇出",这一条不核实等于整个机制不成立。
-- **限流/配额/上限**的具体数值与作用域(每租户?每调用方?每分钟?),超限行为是排队还是失败。
-- **鉴权模板的 claims 形状**:要照抄的 gate 里到底有没有 `permissions`/`bypass`?抄了一个没有权限位的 gate,再叠"按权限下放"的设计就是空中楼阁。
-- **密钥/加密的密钥域**:复用的加密函数绑的是哪个 env/密钥?轮换/灾备是否与你的数据绑死在别人的密钥上?
-- **框架层行为**:如框架校验失败先于业务闸返 4xx——"业务错误一律 200"的承诺需要宽 schema/手动解析才能兑现,计划里要写明。
-- **事务/失败语义**:被复用的"钩子/发射点"在事务内还是事务外?进程崩溃时丢不丢?你承诺的可靠性等级(at-least-once 等)必须与之相容。
+1. 通读 `references/plan-skeleton.md`；用户显式给了模板时，通读用户模板并以其章节结构为准，但仍保留本 skill 的事实、决策和就绪门。
+2. 按“用户指定 → 已有 `goal/` → `docs/plan/`”确定目标路径。不要在仓库里搜索其他模板。
+3. 记录代码调查基线。先读仓库根及相关子目录的 `AGENTS.md`、`CLAUDE.md` 或等价规则文件；项目规则高于通用骨架。读规则是为了约束设计，**规则清单本身不进计划**：有约束的条目落成 `C-*` 或第 12 节的一行一坑（带规则路径与被约束的具体行为），读过但无约束的文件一个字都不写。
 
-## 第 3 步:决策先行
+## 第 1 步：需求账本与计划定性
 
-正文之前先把 §0 钉死——所有实现期会引发争论的点(形态/协议/凭证/权限/边界/复用策略)在这里一次拍完:
+把输入拆成四类，并在最终映射表逐条覆盖：
 
-- **决策表**:每行 = 决策点 + 选择 + **含义**(对部署件/既有代码/边界的影响;能"零改动"的明说)。只写选择不写影响的决策等于没做。
-- **职责边界**:一张"谁拥有什么"的表 + 一句话把职责切死,实现期所有"要不要顺手做"回来看这句。
-- **关键取舍**:每条 = 选择 → **代价**(显式承认) → 缓解/兜底(实在缓解不了就写"风险显式承认")。重点覆盖:降级路径、幂等/重试、**并发与竞态**(两个层面都要:① 后台 worker/队列写清原子认领、基于截止时间的僵尸判定、计数器原子更新——读后写的熔断计数、按旧时间戳清扫 running 这类竞态在计划期就要堵死;② 普通请求路径上**任何跨请求的 check-then-write**——先查状态再写入的流程(如"检查问卷开放→插入答卷"对上"管理员并发关闭")必须写明事务内锁或条件写)、**数据生命周期**(每张新表对其引用的实体逐个走查"被删/被转移/被失效"场景:FK/NOT NULL/UNIQUE 约束必须与声明的回退语义相容——写着 NOT NULL 外键又承诺"删除后回退占位"是自相矛盾;快照列注明每条写路径的**服务端权威来源**,绝不信前端传值)、安全收口、显式截断、回归风险及其门。
-- **明确不做**:所有容易蔓延的相邻功能逐条出表,**每条给去向**(二期 / 另立项 / 依赖某底座就绪)。产品经理的价值一半在这张表上——评审时会被问"那 X 呢"的都要提前出现在这。
+| 类型 | 内容 | 规则 |
+| --- | --- | --- |
+| `R-*` | 用户可见功能与业务规则 | 每条有设计落点、验收或显式排除 |
+| `NFR-*` | 性能、容量、可用性、可靠性、安全、隐私、可观测性、运维、成本、可维护性 | 只保留受本需求影响的类别 |
+| `C-*` | 技术栈、兼容性、交付、时间、法规和仓库硬约束 | 标明来源，不把惯例误写成用户需求 |
+| `A-*` | 暂未证实但设计暂时依赖的假设 | 写验证办法、影响和责任人；重大假设未决则 Blocked |
 
-## 第 4 步:撰写正文
+- 未给出的吞吐、p95、可用性、RPO/RTO、预算等数字不得套用行业示例。能从现有 SLO/配置继承就带路径引用；否则写“未知”，说明它会改变哪个决策以及何时必须确认。
+- 定性计划类型：新模块、既有模块增量、纯前端、重构/深模块化、数据迁移、平台横切面或跨系统集成。类型决定需要加载哪些按需参考与裁剪哪些章节。
+- 真正改变产品形态、权限、数据归属或外部承诺且无法从证据推出的选择，应尽早请用户拍板；不能交互时不得默默代决。
 
-照模板骨架 + 类型裁剪写。通用写作规矩(与模板自身指引冲突时以模板为准):
+## 第 2 步：代码事实调查
 
-1. **复用具名到文件路径**——"照抄 `apps/xx/src/lib/gate.ts` 范式",禁止"参照既有做法"。
-2. **数字来自调查**——端口、表名、scope 名、上限值,全部来自第 2 步的事实清单,不来自记忆或旧文档。
-3. **热查询点名索引**——汇总/列表/统计查询的过滤列,要么指出已有索引(带名字),要么写进迁移新增;别让聚合裸扫大表。
-4. **闸门有顺序,错误面要对齐**——同一端点叠多道闸(存在性/scope/角色/成员资格)时写明顺序;计划承诺的错误码必须是**第一道会失败的闸**真正抛出的(先查成员再查存在性,非成员对不存在的资源拿到的就是 403 而非 NOT_FOUND——想承诺 NOT_FOUND 就得先查存在性);每类拒绝写明传输层 status(4xx)还是业务错误(200+错误体),验证章节按此断言。
-5. **每个里程碑自带验收**——里程碑表每行的"验证"列非空(脚本断言 + 真实环境走查);上一步不绿不进下一步;重构类步骤以"既有验证全绿"为回归门。
-6. **安全项 = 可断言项**——安全清单每条都要能翻译成一条验证断言,写不出断言的不算安全项。
-7. **需求 → 设计映射兜底**——结尾一张表,R1…Rn 逐条指到具体章节 + 机制 + 验证脚本;项目硬约束(多租户/i18n/设计规范等)也入表;排除项汇总指到"明确不做"。
-8. **规模感**:参考模板给的行数区间(无模板时 200-500 行);范围决策约 1/3、验证约 1/4——这两块薄了计划就不可执行。调查过程的原始材料**不要**倾倒进计划,计划只留结论 + 路径。
+调查至少覆盖与需求相关的五个方向，窄任务可合并，但不能跳过关键方向：
 
-## 第 5 步:自检与收尾
+| 方向 | 要回答的问题 | 产出 |
+| --- | --- | --- |
+| 现状盘点 | 已有哪些路由、表、UI、服务、脚本与配置？ | 能力与缺口，带路径 |
+| 复用范式 | 最同构的实现是什么，其行为真的适配吗？ | 具名到文件/符号的复用锚点与差异 |
+| 契约核对 | 每个上游/下游行为是否满足计划？ | 已核实足够 / 已核实缺口 / 未核实阻塞 |
+| 运行真值 | 端口、env、命名、部署、迁移和验证入口是什么？ | 从实际配置读出的不冲突依据 |
+| 历史约束 | 规则文件、进度/延期文档、事故或迁移记录有哪些相关教训？ | 一行一坑 + 出处 |
+
+事实清单使用三态，不再强行二选一：
+
+```text
+[已核实·足够] <行为与语义> (<路径/符号>)
+[已核实·缺口] <现状> → <最小增量> → <漏做后果> (<路径/符号>)
+[未核实·阻塞] <缺什么证据> → <影响的决策> → <如何解除>
+```
 
-1. **过模板自检清单**(模板通常自带;没有就用 `references/plan-skeleton.md` 末尾的通用版),逐项打勾,不过的回去改。
-2. **路径真实性**:跑 `scripts/check_paths.sh <计划文件> <仓库根>`,列出计划中引用但不存在的路径;逐条人工判断——★新增文件与占位符本来就不存在(正常),**"复用/已核实"类路径出现在 MISSING 里就是虚构,必须修**。
-3. **需求映射全覆盖**:对照第 1 步的 R1…Rn 逐条核对映射表,有空格说明设计有洞。
-4. **交叉一致性自检(抓自相矛盾)**:换上实现者的眼睛把全篇重读一遍——计划是分章节写出来的,各章节各自合理但互相打架是最常见的深层缺陷。专抓四类:
-   - 机制章节用到的每个 scope/服务态调用/凭证,反查 seed/SA/清单章节确实配了——设计用了 `directory.read` 而服务账号只给了 `notification.send`,实现期必卡死;
-   - 验证章节的每条断言在设计章节有依据——不许"验收要求了设计里不存在的东西"(如断言 CSV 含备注列,而设计定义的 CSV 没有该列);
-   - 承诺的不变量互不冲突——"信封 id 恒定"与"重投递克隆新行"不能同时成立,发现即回去改设计;
-   - 新增的每个标识符(错误码/共享包导出/env/部署 values 字段)都有对应的登记文件项——漏一处 typecheck/部署就断;
-   - 每个权限/角色/开关位**逐跳追通**:UI 入口可见性 → token/bootstrap 载荷 → 服务端真闸——任何一跳不携带该位就是断链(后端支持 bypass 删除但 bootstrap 不返 bypass、发了角色模板但服务端只认租户 role,都是这类);
-   - 同一口径(导出格式、通知语义、上限值)在全篇多处出现的,逐处对齐——在一处修正的决定必须同步到其余所有提及处,只修一处等于没修。
-5. **落盘**:默认写到项目的计划目录(与模板/范例同目录),命名循既有惯例(如 `goal/<代号>.md`);目标文件已存在时先确认再覆盖。
-6. **汇报**:向用户交付时,除了计划路径,单独列出:① 留给用户拍板的开放问题;② 调查中发现的、与用户假设冲突的事实;③ 你替用户砍掉/推迟的范围(让用户有机会否决)。
+“已核实”必须核到计划依赖的行为，而非只确认文件或函数存在。涉及分页推进、配额、claims、密钥域、事务、失败语义或框架错误面时，读取 [references/architecture-quality.md](references/architecture-quality.md) 的“行为级核实”节。
 
-## 红线(任何情况下不违反)
+## 第 3 步：接口、接缝与备选设计
 
-- **只写计划,不动手实现。** 交付物是计划文档;用户要实施会另说。
-- **不虚构核实。** "已核实"三个字后面必须是本次真读过的路径。
-- **不缩水验证。** 验证章节 + 里程碑验收占计划近一半篇幅是特征不是浪费——砍这里等于交付一份不可执行的愿望清单。
-- **不吞需求。** 用户的每条原始需求,要么有设计落点,要么被显式排除并给出去向,没有第三种下场。
+出现以下任一情况时，必须完整读取 [references/architecture-quality.md](references/architecture-quality.md)：新增共享模块或跨系统契约、重构既有模块、引入远程/外部依赖、改变数据生命周期、要求不停机迁移，或存在显著可靠性/运维风险。局部文案、样式或简单单模块增量不为填表而造架构。
 
----
+复杂计划至少完成：
+
+- 找出承载复杂行为的模块、调用者、接口与接缝；接口包括不变量、调用顺序、错误、配置和性能语义，不只是类型签名。
+- 按进程内、本地可替代、远程但自有、真正外部依赖分类，选择真实实现和测试替身；没有变化需求时不凭空增加 adapter。
+- 对形态、接缝、跨服务协议、数据归属、可靠性等级或迁移策略等高影响决策，提出至少两个真正可行且有实质差异的候选，按需求适配、局部性、迁移、失败、运维、测试和成本比较。简单可逆选择无需形式化比较。
+- 画图只在三个以上节点、异步时序、所有权或状态迁移用文字难以看清时使用；图必须表达关系，不能只是装饰。
+
+## 第 4 步：决策与正文
+
+按骨架裁剪撰写：
+
+- 普通决策表写“决策点、选择、含义、依据”；关键且难回退的决策再写 ADR-lite：背景/驱动因素、备选、选择、正负后果、重新评估触发条件。
+- 职责边界写清谁拥有事实、策略和失败恢复；“复用”必须具名到本次读过的路径与行为差异。
+- 数字只能来自用户、代码/配置、项目规则或明确决策。热查询说明已有索引或迁移增量；未知规模不靠猜测决定新基础设施。
+- 多道闸写执行顺序，错误码与第一道实际失败的闸一致；安全、可靠性和 NFR 条目都要能转成可观察的验证。
+- 涉及持久化、对外契约或滚动部署时，写清兼容窗口、expand/migrate/contract、回填/重放、发布与回滚门。
+- 每个里程碑有独立验收；重构先保留行为基线，再通过模块接口验证结果，避免测试内部实现细节。
+- 写清里程碑及任务的前置依赖、可并行范围与共享文件/资源的单一负责人。只有前置已满足、契约已稳定且互不干扰的任务才可并行；收尾设集成验收，不保留“一律按编号串行”的限制。复杂调度按需读 [references/execution-workflow.md](references/execution-workflow.md) 的“并行执行”。
+- 每个里程碑的退出条件**逐行**以「回写『实施进度』」结尾。实施者是按行核对退出条件的：把这条只写在表外的总说明里，它就会被跳过，进度也就攒到本期收尾才补。
+- 在计划顶部初始化实施进度：总里程碑数、当前状态、最近完成、下一步、阻塞和代码基线必须与里程碑表一致；计划尚未实施时如实写“0/N、尚未开始、下一步 M1”，不得预填完成记录。
+- 骨架顶部的“实施者定位”原样带入计划，不改写、不删减：它是给执行计划的 agent 的定位，与写计划的架构师定位是两回事。
+- 计划按风险和改动面裁剪，不用固定行数或章节占比衡量质量；调查原始材料不倾倒进正文，只保留结论与来源。
+
+## 第 5 步：自检、就绪与交付
+
+1. 跑 `"$SKILL_DIR/scripts/check_paths.sh" <计划文件> <仓库根>`，人工区分新增路径与虚构的“复用/已核实”路径。
+2. 对照 `R-* / NFR-* / C-* / A-*` 检查映射：每条有设计、验证、排除去向或阻塞说明。
+3. 按 `references/architecture-quality.md` 的一致性清单检查凭证/scope、接口/调用方、数据约束/生命周期、设计/验证、发布/回滚和多处重复口径。
+4. 建失败模式表：高影响失败至少写触发、爆炸半径、数据后果、用户表现、检测、恢复与验证；简单局部任务可说明“不引入新的运行期失败模式”及依据。
+5. 检查“实施者定位”与“实施进度”的回写协议为骨架原文在位；每个里程碑的退出条件都以「回写『实施进度』」结尾，依赖与可并行边界明确；跑 `"$SKILL_DIR/scripts/check_progress.sh" <计划文件> <仓库根>` 确认进度与里程碑一致，记录链接有效；初稿不预填完成事实，不把实现与验收详情写回计划。
+6. 最终定级：存在影响范围、安全、数据、外部契约或关键 NFR 的未决项即 `Blocked`；只等非阻塞评审为 `Proposed`；所有实施前置已解决才是 `Ready`。
+7. 汇报计划路径与状态，并单列：待拍板问题、与用户假设冲突的事实、被砍/推迟的范围、未在真实环境完成的调查或验证。
 
-## 本仓库(xgent-ai-portal)默认值
+评审既有计划时，默认只输出问题、证据、严重度和修订建议；用户明确要求改稿时才覆盖原计划。
 
-在本仓库使用时,以下路径与惯例直接采用,不必重新探测:
+## 红线
 
-- **模板**:`goal/PLAN-TEMPLATE.md`(自带元原则 §A、骨架 §B、类型裁剪 §C、写作自检 §D——以它为准)。计划落盘到 `goal/<大写代号>.md`。
-- **样板计划**:新独立 App 型读 `goal/GIT.md` 或 `goal/LMS-RESOURCE.md`;既有 App 增量型读 `goal/PMS-MCP.md`。
-- **端口真值**:`apps/web/vite.config.ts` + 根 `package.json` 的 `dev:all`——别信旧文档端口图。
-- **已知坑来源**:`~/.claude/projects/-Users-rockie-Documents-GitHub-xgent-xgent-ai-portal/memory/`(先看 `MEMORY.md` 索引)、根 `CLAUDE.md`、`goal/*-PROGRESS.md` / `*-DEFERRED.md`。
-- **平台硬约束**(必进需求映射表):多租户隔离(全表 `tenantId`);业务状态一律 200 + `{ok,data}`(HTTP status 只表传输层);字典表 `sort` 规范;三语 i18n;前端两步法(`impeccable` 设计 + Chrome 真浏览器验证);列表接口 `Page<T>` 服务端分页。
-- **新独立 App 的同构基线**:独立后端(Elysia + Drizzle + 独立 Postgres 库 `xgent-<key>`)+ TDT 自省 gate + 前端经 host `sdk.callService` + 应用市场 listing seed + `verify-*.ts` 脚本挂 `verify:all`——决策表第一行"形态"从这里出发。
+- 写作/评审模式不实施功能；用户已要求按计划实施时，直接进入实施期入口，无需重复请求授权。
+- 未读过的代码不写“已核实”，没有来源的数字不写成目标或现状。
+- 不吞需求，不把重大假设藏进正文，不把阻塞计划标为 `Ready`。
+- 不把未通过退出条件的里程碑写成已完成，不用聊天记录代替计划内的简要进度与独立的实现/验收记录；不在续做时批量加载历史记录。
+- 不为假想扩展造接缝、基础设施或抽象，也不照搬通用架构示例覆盖仓库现实。
+- 计划里不写写作过程：用了哪份 skill / 模板 / 参考资料、读过哪些规则文件的清单、调查做了几轮，既不是实施事实也不是里程碑进展，还会诱导实施者去加载只有写计划才需要的上下文。
+- 不在出仓 skill 中硬编码某个仓库的模板、技术栈、端口、样板计划、本机路径或业务约定；这些必须在运行时从目标仓规则和代码读取。

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,78 @@
+# 按计划实施：进度、记录与并行
+
+实施或续做时读取本文件；写计划时仅在需要细化调度边界时读“并行执行”。不加载写作骨架或架构参考作为实施上下文。
+
+## 先恢复最小上下文
+
+先读仓库规则、计划的恢复快照/完成记录索引、当前任务对应的正文与依赖，再核对 `git status` / 相关 diff。记录与工作树不符时查明原因，不凭历史记录覆盖用户改动，不凭代码存在就推断验收已通过。
+
+**独立记录按需读取**：只有继续某个未完任务、核实其前置验收、排查失败/偏差或审查交付时，才打开该里程碑记录的相关章节。无需例行复读最近完成的详细记录，更不要 `cat` 全部记录或把历史日志传给每个 subagent。只查结构一致性时运行校验脚本，看简短结果即可。
+
+## 计划只存摘要，详情独立落盘
+
+- 计划顶部保留七行恢复快照。当前状态列出在做的里程碑及最近实质进展，下一步给可执行动作；不写命令、断言列表、调试过程或完整改动清单。
+- “完成记录”是一张里程碑索引：`Milestone / 状态 / 更新时间 / 简要记录 / 实现与验收记录`。每个已开始的里程碑最多一行，状态仅用 `进行中`、`阻塞`、`已完成`；摘要一到两句，写交付结果或“已做到哪里、还差什么”。进行中/阻塞不计入完成数。
+- 默认每个里程碑一份 `<计划名>.records/M<n>.md`，在其中分开写“实现记录”和“验收记录”；链接相对计划文件解析，例如 `[M1 记录](FEATURE.records/M1.md)`。用户已有记录目录时沿用。详情只从完成记录链接，不在正文/快照重复嵌入。
+- 记录首次有实施事实时再建；原始日志、截图、完整 diff 仅在有复核价值时单独保存并从记录链接。记录本身也要提炼证据，不复制终端流水、聊天或阅读清单。
+
+### 独立记录的最小内容
+
+按下面结构写真实内容，不预填通过；它不是另一份总进度表。
+
+```markdown
+# M1 · 实现与验收记录
+
+- 对应计划：相对链接
+- 最近更新：日期、时间与时区
+- 状态：进行中 / 阻塞 / 已完成
+- 代码基线：commit SHA；未提交写 dirty@起始SHA，非 Git 写可用版本标识
+
+## 实现记录
+
+- 已交付行为、关键改动路径、必要决策及计划偏差。
+- 尚未完成项、阻塞事实及继续动作；完成后写无。
+- 并行任务如有独立交付记录，在这里链接，不复制全部内容。
+
+## 验收记录
+
+| 退出条件 | 命令或走查步骤 | 环境/代码基线 | 结果与必要证据 |
+| --- | --- | --- | --- |
+
+逐条记录实际结果；未运行、失败、环境缺失明确区分。人工/UI 验证写环境、主路径与关键边界结论。必要的日志/截图用链接。
+```
+
+代码基线必须对应验证时的实现；dirty 时在实现记录列关键改动路径，不能用 HEAD 冒充已提交成果。主 agent 的集成修正若影响既有结果，应更新验收证据。subagent 完成自己的任务不等于里程碑通过验收。
+
+## 每个里程碑及时回写
+
+每次完成里程碑，或发生实质进展后准备暂停、受阻、切换任务、结束对话时，按顺序完成以下动作；并行任务逐个收敛，不等整个批次结束才补记：
+
+1. **先保存独立记录**：及时记下实现与实际验收结果。全部功能/验收条件通过才标 `已完成`；未通过则保存已有成果和缺口，保持 `进行中` 或 `阻塞`。
+2. **再刷新计划摘要**：同步七行快照和该里程碑的一行索引，链接到已存在的记录文件。由未完成转为已完成时，将该行移至已完成记录末尾，不增加重复行；已完成行按实际完成先后排列，“最近完成”取最后一条已完成记录，不按编号大小推算。并行时允许 M3 比 M2 先完成。
+3. **有偏差就修正文**：范围、决策、接口、数据、风险或退出条件变化，修订对应章节，快照只点明变化及影响。不要把偏差藏在独立记录里。
+4. **校验后再交接**：运行 `"$SKILL_DIR/scripts/check_progress.sh" <计划文件> [仓库根]`。先完成记录落盘与计划回写，再报告完成、提交代码或启动依赖该成果的任务；已经独立运行的任务可继续。
+
+脚本检查数量、状态、里程碑 ID、最近完成和引用文件存在性，不默认读取所有记录内容，也不证明验收真实通过。主 agent 在记完成时核验该里程碑的证据；后续恢复只按需要复核。
+
+旧计划首次按此流程续做时，将已有完成详情迁到独立记录，保留原时间、结果和基线；计划改成摘要索引。没有证据就保留缺口，不能补造通过记录。只迁移正在执行的这份计划，不批量改其他历史计划；旧规则中的串行限制若只是旧模板默认值，可按依赖核实后更新，项目确有顺序约束则保留。
+
+## 并行执行
+
+每次调度前检查依赖与当前工作树。**有两个以上可独立推进、不会互相干扰的任务且环境提供 subagent 能力时，启动多个 subagents 并发完成**；主 agent 同时处理不与它们冲突的任务或集成准备。不要只写“可以并行”却仍全部串行，也不要为了凑数量拆出无意义任务。
+
+### 哪些任务可同时启动
+
+- 前置成果已通过所需验收，输入/接口契约已稳定；同一里程碑内或不同里程碑之间都可并行，编号本身不是依赖。
+- 写入的文件集合互不重叠，不会在另一个任务仍依赖的文件中改接口/导出/行为。共享类型、公共入口、锁文件、生成产物和迁移序号指定一个负责人，先确定契约或串行集成。
+- 测试和运行资源互不影响：共享数据库、种子/迁移、端口、开发栈重启、同一浏览器会话或外部环境写入需隔离或串行。独立 worktree 只能隔离文件，不能自动隔离这些资源。
+- 无法证明独立就先串行完成前置或重新划界。用户要求串行、工具不可用或资源受限时如实说明，按可用并发数调度，其余串行，不虚构已启动的 subagents。
+
+### 委派、交付与集成
+
+主 agent 给每个 subagent 一份精简任务说明：目标及计划章节/需求 ID、已稳定契约、允许写入与禁止修改的路径、可用运行资源、验收条件、独立记录路径、需回报的阻塞。不复制整段聊天或无关历史；工具支持时选择最小上下文，让 subagent 按需读取规则和相关文件。
+
+**模型默认继承**：如无特别要求，subagent 使用与主 agent 相同的模型。启动工具支持继承时省略模型覆盖参数；必须显式指定时填写主 agent 的模型。只有用户或适用指令明确要求其他模型时才覆盖，不自行因任务难度、成本或速度降级/换模型。
+
+每个文件同一时间只有一个写入者。**计划与里程碑汇总记录由主 agent 单写**；subagent 将详情写入各自的 `<计划名>.records/M<n>-<任务名>.md`，返回简要结果、改动路径、验证结论、缺口与记录链接。任务结束、阻塞或暂停时及时交付；不得替其他 agent 修改文件或回滚他人改动。边界变化先回报，主 agent 调整分工后再继续。
+
+主 agent 逐项审查交付与当前 diff，按需读取相关任务记录，整合成果并完成里程碑所需的集成/回归验证；局部测试全绿不能替代集成验收。有任务失败就保留已交付成果，阻塞依赖它的任务，无关任务可继续。每个里程碑验收完成后立即独立回写，不能等所有 subagents 都结束。结束对话前收集或停止尚在运行的任务，记录可接续状态，不留下无人管理的写入任务。