@xgent-ai/skills 0.1.0 → 0.3.0

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

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

package/skills/dev-plan/scripts/check_progress.sh

@@ -0,0 +1,158 @@
+#!/usr/bin/env bash
+# 用法: check_progress.sh <计划.md> [仓库根,默认 .]
+# 检查计划顶部「实施进度」的内部一致性 —— 实施期每回写一次跑一次,写计划时也跑一次(应报 0/N)。
+# 只检查摘要、状态、ID 与引用文件存在性,不读取独立记录正文,也不证明验收已通过。
+# 兼容旧版内联证据表并提示迁移;「压根没回写」仍需结合陈旧提示与实际工作判断。
+set -euo pipefail
+plan="${1:?用法: check_progress.sh <计划.md> [仓库根]}"; root="${2:-.}"
+[ -f "$plan" ] || { echo "ERROR: 计划文件不存在: $plan" >&2; exit 1; }
+
+errs=0; warns=0
+err()  { echo "ERROR: $*"; errs=$((errs + 1)); }
+warn() { echo "WARN:  $*"; warns=$((warns + 1)); }
+trim() { printf '%s' "$1" | sed -e 's/^[[:space:]]*//' -e 's/[[:space:]]*$//'; }
+plain() { trim "$(printf '%s' "$1" | tr -d '*`')"; }
+field() { trim "$(grep -m1 "^- $1[：:]" <<<"$snap" | sed "s/^- $1[：:]//" || true)"; }
+required() {
+  local value
+  value="$(plain "$2")"
+  case "$value" in ""|—|-|待补|TBD|N/A) err "$1 为空或待补" ;; esac
+  # 摘要可合法提到 <select> 等标签;只对基线检查被反引号包裹的占位。
+  if [[ "$1" = *代码基线 ]] && [[ "$value" =~ \<[^\<\>]+\> ]]; then
+    err "$1 残留模板占位"
+  fi
+  return 0
+}
+
+# 取出一节:从标题行的下一行起,到下一个同级或更高级标题为止。
+section() {
+  awk -v re="$1" '
+    /^#+[ \t]/ {
+      lvl = length($1)
+      if (inseg && lvl <= start) exit
+      if (!inseg && $0 ~ re) { inseg = 1; start = lvl; next }
+    }
+    inseg { print }
+  ' "$2"
+}
+# 表中以 M<数字> 开头的行(「评审整改」这类非里程碑行不计入)
+mrows() { grep -E '^\|[[:space:]]*\**M[0-9]+\**[[:space:]]*\|' <<<"$1" || true; }
+ids() { mrows "$1" | cut -d '|' -f2 | tr -d '*`[:space:]' | sed 's/M/\nM/g' | sed '/^$/d'; }
+
+prog="$(section '^#+[ \t].*实施进度' "$plan")"
+snap="$(section '^#+[ \t].*恢复快照' "$plan")"
+recs="$(section '^#+[ \t].*完成记录' "$plan")"
+mile="$(section '^#+[ \t].*里程碑' "$plan")"
+
+[ -n "$prog" ] || err "找不到「实施进度」节 —— 跨对话恢复的唯一入口缺失"
+[ -n "$snap" ] || err "找不到「恢复快照」"
+[ -n "$recs" ] || err "找不到「完成记录」"
+[ -n "$mile" ] || err "找不到里程碑表"
+
+# ① 快照七个字段齐全
+for f in 最近更新 当前进度 当前状态 最近完成 下一步 当前阻塞 代码基线; do
+  required "恢复快照:$f" "$(field "$f")"
+done
+
+# ② 快照里的模板占位没填(骨架的 <...> 应当被真实内容替换)。
+#    只查快照:完成记录的证据正文里出现 <img> / <select> 这类尖括号是正常的。先剥掉行内代码。
+while IFS= read -r l; do
+  [ -n "$l" ] && err "恢复快照残留模板占位:$(trim "$l")"
+done < <(sed 's/`[^`]*`//g' <<<"$snap" | grep -E '<[^<>]+>' || true)
+
+# ③ 识别新摘要索引与旧内联证据表,核对 ID 和记录字段。
+mcount="$(mrows "$mile" | grep -c . || true)"
+rcount="$(mrows "$recs" | grep -c . || true)"
+legacy=0
+if grep -qE '^\|[[:space:]]*Milestone[[:space:]]*\|[[:space:]]*状态[[:space:]]*\|' <<<"$recs"; then :
+elif grep -qE '^\|[[:space:]]*Milestone[[:space:]]*\|[[:space:]]*完成时间[[:space:]]*\|' <<<"$recs"; then
+  legacy=1
+  warn "旧版内联证据表:本次续做时将详情迁入独立记录,计划保留状态、摘要与链接"
+else
+  err "完成记录表头不受支持,请使用 Milestone / 状态 / 更新时间 / 简要记录 / 实现与验收记录"
+fi
+mids="$(ids "$mile")"
+for id in $(printf '%s\n' "$mids" | sort | uniq -d); do err "里程碑表 ID 重复:$id"; done
+seen=""; completed=0; latest_completed=""
+plan_dir="$(cd "$(dirname "$plan")" && pwd)"
+link_re='^\[[^]]+\]\(([^)]+)\)$'
+while IFS= read -r row; do
+  [ -n "$row" ] || continue
+  IFS='|' read -r _ c_m c_2 c_3 c_4 c_5 _rest <<<"$row"
+  m="$(plain "$c_m")"
+  grep -qxF "$m" <<<"$mids" || err "完成记录出现未知里程碑:$m"
+  if grep -qxF "$m" <<<"$seen"; then err "完成记录里程碑重复:$m"; fi
+  seen="${seen}"$'\n'"$m"
+  if [ "$legacy" -eq 1 ]; then
+    state="已完成"
+    required "$m 完成时间" "$c_2"
+    required "$m 完成摘要" "$c_3"
+    required "$m 验证证据" "$c_4"
+    required "$m 代码基线" "$c_5"
+  else
+    state="$(plain "$c_2")"
+    case "$state" in 进行中|阻塞|已完成) ;; *) err "$m 状态无效:$state" ;; esac
+    required "$m 更新时间" "$c_3"
+    required "$m 简要记录" "$c_4"
+    link="$(trim "$c_5")"
+    if [[ "$link" =~ $link_re ]]; then
+      target="${BASH_REMATCH[1]}"
+      target="${target#<}"; target="${target%>}"; target="${target%%#*}"
+      case "$target" in
+        ""|/*|*://*) err "$m 记录须为相对计划文件的本地链接:$target" ;;
+        *) [ -f "$plan_dir/$target" ] || err "$m 记录文件不存在:$target"
+           [ ! "$plan_dir/$target" -ef "$plan" ] || err "$m 记录必须独立于计划文件" ;;
+      esac
+    else
+      err "$m 缺少实现与验收记录的 Markdown 链接"
+    fi
+  fi
+  if [ "$state" = "已完成" ]; then
+    completed=$((completed + 1)); latest_completed="$m"
+  fi
+done < <(mrows "$recs")
+if [ "$rcount" -gt 0 ] && grep -qE '尚未(完成|开始)任何里程碑' <<<"$recs"; then
+  err "完成记录已有实施事实,却仍保留初始占位行"
+fi
+
+# ④ n/N 只统计已完成状态,进行中/阻塞不计入。
+cur="$(field 当前进度)"
+done_n=""; total_n=""
+if [[ "$cur" =~ ([0-9]+)[[:space:]]*/[[:space:]]*([0-9]+) ]]; then
+  done_n="${BASH_REMATCH[1]}"; total_n="${BASH_REMATCH[2]}"
+else
+  err "「当前进度」不是 n/N 形状,新对话读不出进度:$(trim "$cur")"
+fi
+if [ -n "$total_n" ]; then
+  [ "$mcount" -gt 0 ] || err "里程碑表里没有 M<数字> 行,无法核对 N"
+  [ "$mcount" -eq 0 ] || [ "$total_n" -eq "$mcount" ] \
+    || err "「当前进度」的 N=$total_n,里程碑表却有 $mcount 行 —— 计划改过里程碑但没同步快照"
+  [ "$done_n" -eq "$completed" ] \
+    || err "「当前进度」说完成 $done_n 个,完成记录实际完成 $completed 个(共 $rcount 行)"
+fi
+
+# ⑤ 最近完成取记录中最后一条已完成行,允许 M3 先于 M2 完成。
+lastdone="$(plain "$(field 最近完成)")"
+if [ "$completed" -eq 0 ]; then
+  [ "$lastdone" = "无" ] || err "0 个里程碑完成,但「最近完成」写着:$lastdone"
+else
+  latest_re="^${latest_completed}([^0-9]|$)"
+  [[ "$lastdone" =~ $latest_re ]] || err "最近完成应为 $latest_completed,实际为:$lastdone"
+fi
+
+# ⑥ 陈旧提示:代码改了、计划没动
+if command -v git >/dev/null 2>&1 && git -C "$root" rev-parse --git-dir >/dev/null 2>&1; then
+  planrel="$(git -C "$root" ls-files --full-name --error-unmatch "$plan" 2>/dev/null || true)"
+  dirty="$(git -C "$root" status --porcelain 2>/dev/null | cut -c4- | sed 's/.* -> //' || true)"
+  if [ -n "$dirty" ]; then
+    n="$(grep -c . <<<"$dirty" || true)"
+    if [ -n "$planrel" ] && grep -qxF "$planrel" <<<"$dirty"; then :
+    elif [ -n "$done_n" ] && [ -n "$total_n" ] && [ "$done_n" -lt "$total_n" ]; then
+      warn "还剩 $((total_n - done_n)) 个里程碑未完成,工作树有 $n 个未提交改动,而本计划文件没被改过 —— 若其中已完成某个里程碑,先回写「实施进度」再继续"
+    fi
+  fi
+fi
+
+echo "---"
+echo "进度:${done_n:-?}/${total_n:-?} · 里程碑表 $mcount 行 · 记录 $rcount 行(已完成 $completed) · ERROR $errs · WARN $warns"
+[ "$errs" -eq 0 ] || exit 1

package/skills/elintp/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: elintp
+description: 把一个技术主题、或一份技术文档（PRD、开发计划、技术方案、评审纪要）讲成任何背景的读者都能看懂并复述出来的 HTML 文档——大图示、显眼的关键数字、带图例的图表、表头带释义的表格、尽量少的术语。凡用户输入 /elintp <主题或文档>，或要求「讲得通俗一点 / 把这份 PRD 讲成人话 / 写给业务同事看的说明 / 给不做研发的同事解释这个系统」时使用。Use when the user types /elintp <topic-or-document>, or asks for a plain-language explainer or restatement of a technical document aimed at readers outside the engineering team.
+---
+
+# elintp · 把事情讲清楚，而不是把读者讲低
+
+输入：$ARGUMENTS
+
+目标：读者看完能用自己的话把这件事讲给别人听。
+
+## 两种输入
+
+**输入是主题**（一个系统、一个概念、一次故障）：自己组织内容，按下面的准则写。
+
+**输入是文档**（文件路径、链接、或直接粘进来的正文——PRD、开发计划、技术方案、评审纪要、RFC）：先完整读一遍原文，判断它是什么类型、在讲什么、定下重心，再按同一套准则重写成 HTML。产出形态、红线、写作准则全都一样，只多两层约束——**先判型再定重心**，以及**你在转述，不在创作**。
+
+分不清用户给的是主题还是文档，就问一句，不要猜。
+
+## 语言选择
+
+用户没指定语言就用简体中文；用户用哪种语言提问就用哪种，文档模式下也可以从原文判断。代码、文件名、标识符保持英文。
+
+## 红线：文档里不出现关于读者的话
+
+只写主题本身，不写读者是谁、懂不懂、需不需要懂。下面这类句子**一句都不能出现**——正文、开场白、副标题、图注、脚注，一律算：
+
+- 「这份说明写给不写代码的人。」
+- 「面向非技术人员 / 业务同事 / 小白 / 外行 / 门外汉」
+- 「你不需要懂技术也能看明白」
+- 「用大白话讲 / 通俗版 / 简化版 / 人话版」
+- 「简单来说，你只要记住一句话就够了」
+
+**为什么**：这类句子对理解主题零贡献，却把整篇的定位从「解释一件事」降成「照顾一群人」，读的人会觉得被冒犯。读者的背景决定的是**你怎么写**，不是**你写什么**——它应该体现在措辞里，而不是被声明出来。
+
+**替代做法**：开篇第一句直接给主题本身的事实或结论。
+
+- ✗ 「这份文档写给不写代码的同事，介绍我们的消息队列。」
+- ✓ 「订单提交后不会立刻扣库存，中间隔着一个排队环节，平均等待 200 毫秒。」
+
+## 写作准则
+
+- **先给结论，再给机制。** 每一节的第一句就是这一节的答案，后面才是它为什么成立。开篇不要铺垫，第一行就是答案。
+- **一句话一个意思**；写操作步骤时，一句话一个动作。
+- **主动语态，写清是谁做了什么。** 「校验拦下了这次发布」，不写「这次发布被拦下了」。
+- **句子要短。** 读到一半得换口气的句子，本来就是两句。
+- **一个词一个意思，一个意思一个词。** 同一个东西不要换着叫——读者会以为你在指不同的东西。
+- **用现在时**，除非时间本身就是要讲的事实。
+- **宁可用列表，也不要密不透风的段落**——但列表不等于可以丢掉条目之间的关系，该写清先后、因果、依赖就写清。
+- **术语该用就用，但首次出现时用一句话给出含义**，紧跟在术语后面，不要道歉、不要加引号强调「这个词很专业」。实在没有通俗说法的术语，就写读者会看到什么、要做什么，术语本身在括号里出现一次。
+- **代码、命令、配置项是精确字符串。** 用户要敲、要跑的东西一个字都不改，解释写在它周围。
+- **类比服务于精确，不服务于亲切。** 一个类比只有在它能让读者对下一段做出正确推断时才留下；不要为了显得亲切而把事情说成儿童故事。
+- **不省略读者会用到的量级。** 多快、多少、多贵、失败率多高——数字比形容词管用。
+- **不确定的地方直说不确定**，不要用模糊表述糊过去。
+- **篇幅目标是原文的一半以内**，除非「转述硬规则 1」或用户点名的条数不允许。
+
+## 文档模式第一步：判型，定重心
+
+拿到文档，动笔前先做两件事：
+
+1. **判型。** 这是 PRD、开发计划、技术方案、评审纪要，还是故障复盘？
+2. **定重心。** 读者读完要能回答哪几个问题？重心决定什么放前面、展开写，什么退到后面、一句带过。
+
+**重写不是把原文逐段换个说法再过一遍。** 原文的目录是按写作者的思路排的（背景、目标、方案、排期、风险……），新文档按读者的问题排。两者的顺序本来就不该一样。
+
+### PRD
+
+读者要能回答：
+
+- **会多出什么？** 用用户能看到的行为写，不写模块名。
+- **做完之后系统变成什么样？** 和现在的差别在哪。
+- **建议怎么实施？** 分几步、先后顺序、每一步做完能看到什么。
+
+### 开发计划
+
+先看计划里的记录，判断它做完了没有——勾选框、状态字段、进度回写小节、修订记录都是信号。
+
+- **还没做完**：重心是**要开发什么**，以及**技术路线是什么**——选了哪条路，为什么是它，代价是什么。
+- **已经做完**：重心是**做出了什么**、**读者怎么自己验证**（具体到点哪里、跑什么命令、看哪个数），以及**还有什么遗漏和要接着跟的**。
+- **做了一半**：两段都写。先讲已完成的和怎么验证，再讲剩下的和技术路线。哪部分算完，以原文的记录为准。
+
+计划里写着「已完成」而这次会话没有实际验证过，就写「计划记录为已完成」，不写「已经完成」——转述硬规则 3。
+
+### 其他类型
+
+同样先问一句「读者读完要能回答什么问题」，再定重心。判不准类型，或者判不准计划做完没有，就问用户，不要猜。
+
+### 重心不是丢东西的借口
+
+重心决定的是**顺序和详略**，不决定去留。转述硬规则 1 照旧：原文的每条警告、风险、数字、前提，重心之外的也要在文档里出现——可以放到后面、压成一行，但不能没有。
+
+## 转述硬规则（输入是文档时）
+
+1. **只做减法，不做粉饰。** 原文里的每一条警告、风险、数字、前提条件，重写后都还在。丢掉 ⚠ 那行的「摘要」是一种谎。涉及安全、数据丢失、以及任何难以撤销的操作，展开写全，不缩写。
+2. **数字原样。** 金额、数量、日期不四舍五入。指明某个动作的工单号、PR 号照抄。
+3. **和原文一样真，不比原文更真。** 原文的说法仍然是说法：写「计划里说测试会全部通过」，不写「测试会全部通过」——除非这次会话里你自己验证过。
+4. **不清楚的地方保持不清楚。** 原文含糊的地方就写「原文没有说」，不要靠猜把它补圆。
+
+## 产出形态：一个本地 HTML 文件
+
+**默认写到本地，不发布。** 单文件、样式与脚本内联、不依赖外网资源，双击就能打开、也能直接当附件发出去。路径听用户的；用户没指定就放当前目录（仓库里已有 `docs/` 就放 `docs/`），文件名用主题命名，文档模式下跟着原文档的名字走。写完把路径告诉用户。
+
+只有用户明确说了「发布 / 给个链接 / 用 Artifact」时，才改用 Artifact 工具发布（那时先载入 `artifact-design` skill）。
+
+这份文档要靠看，不靠读：
+
+- **大图示**：核心流程/结构用一张占满宽度的图讲完，图能独立看懂（自带标注，不依赖正文）。
+- **关键数字做成指标块**：数值大字号，旁边一行说明它意味着什么（`200ms` 下面写「用户几乎察觉不到」）。
+- **图表必须带图例和轴标签**，颜色不是唯一区分手段。
+- **表格的表头带释义**：每个可能不自明的列名挂 tooltip（`title` 或自绘 tooltip），把这一列到底在说什么讲清楚。
+- 移动端可读；宽内容自己横向滚动，页面本身不横向滚动。
+- 文档模式下，正文**末尾**注明原文出处（路径或链接）和你读到的版本，方便读者回去核对。开头不写，开头留给主题本身。
+
+## 交付前自检
+
+1. 通读全文，搜一遍有没有描述读者身份/水平的句子——有就删掉，不要改写成委婉版本，直接删。
+2. 第一句话是不是主题本身的事实？如果它在介绍这份文档，重写。
+3. 每张图、每个数字：去掉它，读者会不会漏掉一个结论？不会就说明它是装饰，删。
+4. 找一个具体问题（「出故障时会怎样？」「这东西一天处理多少？」），看文档能不能答上来。答不上来就补。
+5. 文档模式：重心里的那几个问题，文档能逐个答上来吗？答不上来的补。
+6. 文档模式：把新文档的小标题和原文目录并排看——如果一节对一节、顺序基本一致，说明你只是在逐段换说法，按重心重组。
+7. 文档模式再加一遍对照：原文的每条警告、风险、数字、前提，在新文档里都能找到吗？找不到的补回去。
+
+## 常见坑
+
+- **用户说「没看懂」是反馈，不是质疑。** 重讲一遍就好，不要辩解、不要用同样的高度再讲一次、也不要在重讲里夹带「我当时是这么想的」。
+- **重讲不是偷偷改错。** 如果重讲时发现原来写的是错的，那是一处更正，明说；不要在「更简单的版本」里悄悄换掉。
+- **任务做到一半被问「等等，这是什么意思？」**：先重讲那一处，再回到原来的任务，别把线索丢了。
+- **原文本来就已经写得很清楚**：说一句「原文已经够清楚了」，然后停手。为了显得有用而造一个不同的版本，是灌水。