cgraphx 1.4.3 → 2.0.1

package/dist/.claude-template/skills/write-spec/SKILL.md

@@ -7,297 +7,90 @@ description: 用户要求基于已确认的需求、业务边界、技术方案
 
 ## 定位
 
-把当前上下文中已经确认或给定的需求、业务要求和技术边界,整理成**研发或 Agent 可引用的系统规格契约**。
-
-Spec 的目标是归档系统应该满足什么行为和约束,为后续 plan 文件和实际编码提供稳定输入。Spec 之后,后续 agent 不应重新解释业务规则、数据口径、接口契约、权限边界或异常行为。
+- **Spec = 任务的唯一契约**:归档系统必须满足的行为、规则、数据、接口、权限、异常、兼容性、约束和验收口径——plan 的稳定输入。Spec 之后,后续 agent 不重新解释业务规则、数据口径、接口契约、权限边界或异常行为。
+- **没有任何业务义务存在于 spec 之外**:澄清总结、PRD、聊天记录都是输入和证据,不是契约——决策只有写进 spec 才成为义务;在 clarify 里谈过但没进 spec 的,不具约束力。
+- **Spec 写业务可观察的要求与后果,不写实现手段选型**(同步/异步、缓存、定时任务归 plan);不展开成任务列表、文件级修改步骤、代码实现细节。
 
 <HARD-GATE>
-如果缺少会影响规格正确性或后续 plan 正确性的关键信息,先补问 3-5 个关键问题;如果不阻塞成文,在 spec 中标记为【待确认】。
-不要编造未确认的业务规则、接口行为、数据结构或技术约束。如果必须依赖未确认规则,先向用户确认。
-会影响 plan 写死或实现正确性的【待确认】不能伪装成已确认规格。
+缺少影响规格正确性或 plan 正确性的关键信息 → 先补问 3-5 个;不阻塞成文的标【待确认】。
+不编造未确认的业务规则、接口行为、数据结构或技术约束;必须依赖未确认规则时,先向用户确认。
+会影响 plan 写死或实现正确性的【待确认】,不能伪装成已确认规格。
 </HARD-GATE>
 
-## 与其他产物的边界
+## 边界
 
-- PRD 说明客户或业务方要确认的业务逻辑。
-- Spec 说明系统必须满足的行为、规则、接口、数据、权限、异常和约束,是后续 plan 的契约来源。
-- Plan 说明如何分步骤修改代码来满足 spec,不得重新定义 spec。
+- 澄清总结 = spec 的输入,**无损接收**:已锁定的入正文,未解决的入【待确认】,不悄悄丢,不伪装成已确认。
+- Plan 说明如何改代码满足 spec,不得重新定义 spec;实现手段选型在 plan 阶段结合代码规划——纯工程手段(无业务可观察后果)plan 自主,有业务可观察后果的回跳 spec 业务拍板。
 - Implementation 按 plan 编码,不得重新设计 spec 已锁定的契约。
 
-Spec 可以包含必要的技术边界和系统影响,但不要展开成任务列表、文件级修改步骤或代码实现细节。
-
 ## 输入理解
 
-优先基于当前上下文中的以下信息写 spec:
-
-- 用户已确认的需求描述
-- clarify 阶段产出的已锁定业务决策、已锁定技术方向、已排除方案和下游就绪判断
-- 已确认的业务目标、业务边界和非目标
-- 已确认的技术方案边界
-- 已确认的角色、权限、流程、状态、规则、异常和验收口径
-- 已有 PRD、接口说明、业务文档、代码上下文、数据口径或影响分析
-- 项目里已有的模块、页面、接口、模型、任务、队列、权限系统或外部系统约束
-
-如果当前上下文已经足够,直接写 spec。不要重新澄清已经确认过的内容。
-
-如果只有一句模糊想法,不要硬写完整 spec。先用 3-5 个问题补齐最影响规格正确性的内容。
-
-## 受众和边界
-
-面向研发、技术负责人、Code Agent、测试和后续 plan 编写者。文档应当清楚、可引用、可验证。
-
-可以写:
-
-- 需求目标和范围
-- 非目标
-- 术语和业务对象
-- 业务规则和状态流转
-- 功能行为规格
-- 输入输出和数据口径
-- 权限、安全、审计和可见性要求
-- 接口、页面、任务、队列、缓存、外部系统的影响边界
-- 同步/异步、幂等、重试、超时、一致性和兼容性要求
-- 数据迁移、回填、存量数据处理要求
-- 错误、异常和边界场景
-- 验收标准和测试关注点
-- 后续 plan 必须遵守的约束
-- 待确认项
+- 优先基于当前上下文:用户已确认的需求 · clarify 产出(已锁定业务决策/已排除方案/下游就绪判断)· 业务目标/边界/非目标 · 角色/权限/流程/状态/规则/异常/验收口径 · 已有 PRD/接口说明/业务文档/代码上下文/数据口径/影响分析 · 项目已有的模块/页面/接口/模型/任务/队列/权限系统约束。
+- 上下文足够 → 直接写,不重新澄清已确认内容。
+- **只有一句模糊想法 → 不硬写完整 spec,提醒用户走 clarify 流程。**
 
 ## 工作流程
 
-在写任何 spec 内容前,**必须**先与用户确认两件事:
-
-1. **业务 ID**:本次需求是否有对应的工单号 / 需求单号 / 项目代号?允许留空,但**留空也必须显式确认**(用户明确说"没有/留空"),不得默认跳过。
-2. **标题语言**:用中文 / 英文 / 中英混合?由用户选定,**禁止** Agent 因为"目录看起来更整齐"/"和现有 feature 命名一致"/"避免中文路径问题"等原因,擅自把中文需求转成英文 slug。
-
-- 用户主动给过完整 feature-id 或文件名 → 直接复用,跳过本步。
-- 用户用 `/write-spec` 触发但未给命名决策 → **第一步就问这两个问题**,问完再写。
-- 不得"先写 spec 内容,命名最后再说"。命名决策必须在内容产出之前落定,否则会在文件名上反复返工。
-
-1. **检查上下文完整性**
-  - 确认当前上下文是否已有明确需求、业务边界和技术边界。
-  - 识别缺失的行为、规则、数据、接口、权限、异常、兼容性或验收信息。
-  - 只补问会影响规格正确性或后续 plan 正确性的问题。
-  - 如果 clarify/PRD 中存在需要领导或业务方拍板但未确认的规则,不得把它写成已确认规格。
-
-2. **确定 spec 粒度**
-  - 简单需求写轻量 spec。
-  - 跨模块、跨系统、涉及数据/权限/异步/兼容性的需求写完整 spec。
-  - 不为了显得完整而展开无关技术细节。
-
-3. **归档系统规格**
-  - 把业务描述转换成系统应满足的行为和约束。
-  - 明确输入、输出、状态、规则、数据、权限、异常和验收。
-  - 对后续 plan 必须遵守的内容使用明确措辞。
-  - 明确哪些契约不允许 implementation 阶段自行调整。
-
-4. **标记不确定项**
-  - 未确认但不阻塞成文的内容标记为【待确认】。
-  - 不把推测写成已确认规格。
-  - 如果待确认项会影响 plan 任务拆分、数据结构、接口契约、权限或验收,标明"不解决前不可写死 plan"。
-
-5. **自检**
-  - 检查 spec 是否足以指导后续 plan。
-  - 检查是否混入实现步骤或代码方案。
-  - 检查业务规则、数据影响、权限、异常、兼容性和验收是否清楚。
-
-## 结构选择
-
-不要把下面内容当成固定模板。Spec 的结构必须根据项目既有规范、需求复杂度、上下文信息和后续 plan 的需要动态组织。
-
-优先级:
-
-1. 如果项目已有 `docs/features/`、历史 spec、团队模板或命名习惯,优先沿用项目格式。
-2. 如果需求简单,使用轻量结构,只保留能指导 plan 的内容。
-3. 如果需求复杂,按业务流程、模块、接口、数据、权限、异步、迁移等实际风险组织章节。
-4. 如果某类内容与当前需求无关,不要为了模板完整而保留空章节。
-5. 如果某类内容对后续 plan 很关键,即使默认模板没有,也要新增项目特定章节。
-
-最小结构建议:
-
-```markdown
-# 规格说明: <需求名称>
-> feature-id: <feature-id>
-> 状态: 草稿
-> 日期: YYYY-MM-DD
-
-## 1. 目标与范围
-
-## 2. 已确认规格
-
-## 3. 关键约束
-
-## 4. 不可留到实现期的决策
-
-## 5. 验收与验证关注点
-
-## 6. 待确认项
-```
-
-复杂需求可按需扩展为:
-
-```markdown
-# 规格说明: <需求名称>
-> feature-id: <feature-id>
-> 状态: 草稿
-> 日期: YYYY-MM-DD
-
-## 1. 目标与范围
-## 2. 术语与业务对象
-## 3. 业务规则
-## 4. 系统行为
-## 5. 数据、状态与口径
-## 6. 权限、安全与审计
-## 7. 接口、页面与系统边界
-## 8. 异步、幂等、重试与一致性
-## 9. 兼容性、迁移与存量数据
-## 10. 异常与边界场景
-## 11. 验收标准与测试关注点
-## 12. 不可留到实现期的决策
-## 13. Plan 编写约束
-## 14. 待确认项
-```
-
-这些只是候选结构。最终输出应选择最能表达当前需求的章节名称、顺序和粒度。
-
-## 内容模块池
-
-按需取用以下内容模块。不要逐项填表,不要保留无内容的章节。
-
-### 目标与范围
-
-说明系统要满足的目标、包含范围和明确不包含范围。范围应能约束后续 plan,防止计划扩张。
-
-### 术语与业务对象
-
-当项目概念会影响理解或实现时,列出后续实现和测试必须理解的概念,例如角色、单据、状态、产品、订单、账户、套餐、任务等。
-
-### 业务规则
-
-归档经过确认的业务判断、限制、计算、状态变化、优先级、冲突处理和例外规则。每条规则应可验证。
-
-### 系统行为
-
-描述系统在不同触发条件下必须表现出的行为。可按业务场景、用户动作、系统事件、接口调用或状态流转组织。
-
-常用表达维度:
-
-- 前置条件
-- 触发动作
-- 系统行为
-- 输出结果
-- 失败或不满足条件时的行为
-
-### 数据、状态与口径
-
-说明需要读取、创建、更新、删除、导入、导出、迁移或回填的数据及其业务含义。可以描述模型/字段/状态的预期,但不要展开成完整数据库设计。
-
-### 权限、安全与审计
-
-当相关时,说明角色权限、数据可见性、租户/组织/区域隔离、安全约束、审计日志、敏感数据处理等要求。
-
-### 接口、页面与系统边界
-
-当相关时,说明受影响的页面、接口、外部系统、后台任务、队列、缓存或模块边界。可以写业务级输入输出和系统边界,不要写代码级实现步骤。
-
-### 异步、幂等、重试与一致性
-
-当相关时,说明同步/异步要求、幂等要求、失败重试、超时处理、最终一致性、进度查询、通知和可观测性要求。
-
-### 兼容性、迁移与存量数据
-
-当相关时,说明是否要兼容已有用户、旧接口、历史数据、旧流程;是否涉及迁移、回填、默认值或灰度。
-
-### 异常与边界场景
-
-说明无权限、数据不存在、重复请求、并发、部分成功、回滚、空数据、外部系统失败等场景的预期行为。
-
-### 验收标准与测试关注点
-
-写可验证的系统行为和业务结果。可以给测试关注点,但不要写详细测试用例脚本。
-
-### Plan 编写约束
-
-列出后续 plan 必须遵守的约束,例如不能改动的旧行为、必须复用的机制、不能引入的依赖、必须兼容的接口、必须覆盖的风险点。
-
-### 不可留到实现期的决策
-
-列出后续 implementation/subagent-implement 不得自行决定或重新设计的内容,例如:
-
-- 业务规则、统计口径、过滤维度、时间范围、去重规则
-- 状态含义、状态流转、异常处理
-- API 输入输出、错误语义、兼容性
-- 权限、安全、审计、数据可见性
-- 数据迁移、回填、默认值、灰度策略
-- 同步/异步、幂等、重试、一致性要求
-
-如果这些内容尚未确认,不要把它们藏在正文中;写入待确认项并说明不解决前不能进入严格 plan。
-
-### 待确认项
-
-列出仍需用户、业务方或技术负责人确认的内容。不要把待确认项藏在正文里。
-
-## 产物位置
-
-在可写项目上下文中,默认创建或更新:
-
-`docs/features/<feature-id>/<文件前缀>-spec.md`
-
-文件前缀规则见下一节。
-
-如果没有可写项目上下文,或用户明确只需要正文,则直接在回复中输出 spec 内容。
-
-## feature-id 与文件前缀规则
-
-**feature-id 格式**:`YYYY-MM-DD-[业务ID-]<标题>`
-
-1. 日期使用当前日期。
-2. 业务ID 是**可选**段落(字母数字 + 连字符,如 `CRM-req19230`)。skill 启动时提示用户填写,允许留空。
-3. 标题段允许中文、英文或混合(例:`号百商品详情查询接口`、`features目录结构调整`)。**不得**对中文做英文 slug 转换。
-4. 业务ID 段与标题段用连字符连接,组成 `<业务ID>-<标题>`。
-5. 写入前检查 `docs/features/` 下是否重名;重名时追加简短后缀。
-6. 若当前上下文或用户已提供 feature-id,则复用。
-7. 如果同一目录下已有 PRD 或其他需求文档,优先复用同一个 feature-id。
-
-**文件前缀算法**:
-- 有业务ID:文件前缀 = `<业务ID>-<标题>`(如 `CRM-req19230-号百商品详情查询接口`)
-- 无业务ID:文件前缀 = `<标题>`(如 `features目录结构调整`)
-
-**默认产物路径**:`docs/features/<feature-id>/<文件前缀>-spec.md`
-
-例:
-- 有业务ID:`docs/features/2026-06-10-CRM-req19230-号百商品详情查询接口/CRM-req19230-号百商品详情查询接口-spec.md`
-- 无业务ID:`docs/features/2026-07-03-features目录结构调整/features目录结构调整-spec.md`
-
-**敏感字符拒绝**:文件名不得包含 `/`、`:`、`*`、`?`、`"`、`<`、`>`、`|`。用户提供时若含敏感字符,skill 必须要求用户重命名,不得自动替换字符。
-
-**与旧目录共存**:skill 始终用新命名,不主动探测旧目录的 `spec.md`。旧 feature 目录里继续更新会出现 `spec.md`(旧)和 `<文件前缀>-spec.md`(新)并存,由用户自行处理。
-
-## 写作原则
-
-- 面向研发和 Agent,不是面向客户展示。
-- 写系统必须满足的规格,不是写实施步骤。
-- 把业务要求转成可实现、可验证、可计划的约束。
-- 必要时保留项目术语、接口名、状态码、模块名或数据对象名。
-- 不确定就标【待确认】。
-- 已确认的非目标要明确写出。
-- 简单需求轻量写,复杂需求完整写。
-- 不要把未确认的方案选项写成正式规格。
-- 不要把需要业务拍板或技术确认的关键决策留给 plan/implementation 阶段临场决定。
-- 不要自动进入 plan 或 implementation。
-
-## 质量检查
-
-输出前确认:
-
-- 后续 plan 编写者能据此拆解实现工作。
-- 业务规则、系统行为和技术边界没有混在一起变得含糊。
-- 数据、状态、权限、异常、兼容性和验收口径足够明确。
-- 文档没有滑向客户 PRD、任务计划或代码方案。
-- 所有未确认内容都标为【待确认】。
-- 不可留到实现期的决策已经列出。
-- Plan 编写约束足以防止后续实现跑偏。
-
-## 收尾方式
-
-输出 spec 后,只提示用户可以审阅规格并指出需要调整的地方。不要主动继续写 plan 或代码。
+0. **命名先行**(写内容前必须落定):① 业务 ID——有无工单号/需求单号?允许留空但**必须显式确认**;② 标题语言——中/英/混合,用户选定,**禁止擅自中文转英文 slug**;③ 负责人——默认 `git config user.name`,向用户展示确认,写入头部 `> 负责人:`(「我的需求」检索以此为准)。用户已给 feature-id → 直接复用。
+1. **检查完整性**:识别缺失的行为/规则/数据/接口/权限/异常/兼容性/验收;只补问影响正确性的;clarify/PRD 中未拍板的规则不得写成已确认;无损接收 clarify 锁定决策。
+2. **定粒度**:简单需求轻量;跨模块/跨系统/涉数据/权限/兼容性 → 完整;不为显得完整展开无关技术细节。
+3. **归档规格**:业务描述 → 系统应满足的行为和约束;明确输入/输出/状态/规则/数据/权限/异常/验收;plan 必须遵守的用明确措辞;写清哪些契约不允许 implementation 自行调整。
+4. **标记不确定**:不阻塞的标【待确认】;推测 ≠ 已确认;影响 plan 拆分/契约/权限/验收的,标明"不解决前不可写死 plan"。
+5. **自检**:能否指导 plan;是否混入实现步骤/代码方案;规则/数据/权限/异常/兼容性/验收是否清楚。
+
+## 结构(动态组织,不是固定模板)
+
+面向研发/技术负责人/Code Agent/测试/plan 编写者:清楚、可引用、可验证。
+
+优先级:项目既有格式(`docs/features/`、历史 spec、团队模板)> 轻量结构(简单需求)> 按业务流程/模块/接口/数据/权限/迁移等实际风险组织(复杂需求)。无关内容不留空章节;plan 需要而模板没有的,新增项目特定章节。
+
+- **头部**:`# 规格说明: <需求名称>` + feature-id / 负责人 / 日期(每行 `> 字段: 值`)。需求阶段由 `cgraphx features` 从产物自动派生(已规格/已规划/已验证),不手填状态。
+- **最小结构**:目标与范围 / 已确认规格 / 关键约束 / 不可留到实现期的决策 / 验收与验证关注点 / 待确认项。
+- **复杂需求按需扩展**:术语与业务对象 / 业务规则 / 系统行为 / 数据、状态与口径 / 权限、安全与审计 / 接口、页面与系统边界 / 时效、幂等与一致性预期 / 兼容性、迁移与存量数据 / 异常与边界场景 / 验收标准与测试关注点 / Plan 编写约束。
+
+## 内容模块池(按需取用,不逐项填表,不留空章节)
+
+| 模块 | 写什么 |
+|---|---|
+| 目标与范围 | 目标、包含范围、明确非目标;范围应约束后续 plan |
+| 术语与业务对象 | 实现/测试必须理解的概念(角色/单据/状态/产品/订单/账户/套餐/任务等),含易混同名辨析 |
+| 业务规则 | 经确认的判断/限制/计算/状态变化/优先级/冲突处理/例外,每条可验证 |
+| 系统行为 | 各触发条件下的行为;按场景/用户动作/事件/接口/状态组织;维度:前置条件/触发/行为/输出/失败行为 |
+| 数据、状态与口径 | 读写/迁移/回填的数据及业务含义;可描述模型/字段/状态预期,**不展开完整数据库设计** |
+| 权限、安全与审计 | 角色权限/可见性/租户・组织・区域隔离/审计/脱敏 |
+| 接口、页面与系统边界 | 受影响的页面/接口/外部系统/任务/队列/模块;写业务级 IO 与边界,**不写代码级步骤** |
+| 时效、幂等与一致性预期(业务可观察) | 结果时效/数据新鲜度/重复请求预期(幂等)/失败・重试・超时预期/用户是否需感知中间状态/进度/通知/可观测性。**写预期与可观察后果,不写手段**——同步/异步・MQ・缓存选型由 plan 定;手段产生信封外可观察后果 → 先补 spec |
+| 兼容性、迁移与存量数据 | 旧用户/旧接口/历史数据/旧流程兼容;迁移/回填/默认值/灰度 |
+| 异常与边界场景 | 无权限/数据不存在/重复/并发/部分成功/回滚/空数据/外部失败 |
+| 验收标准与测试关注点 | 可验证的行为与业务结果;可给测试关注点,**不写详细测试脚本** |
+| Plan 编写约束 | 不能改的旧行为/必须复用的机制/不能引入的依赖/必须兼容的接口/必须覆盖的风险 |
+| 不可留到实现期的决策 | 业务规则/口径/维度/时间范围/去重 · 状态含义/流转/异常 · API IO/错误语义/兼容性 · 权限/安全/审计/可见性 · 迁移/回填/默认值/灰度 · 时效/新鲜度/一致性预期/幂等(**实现手段不入此列,由 plan 定**)。未确认 → 待确认项 + 注明"不解决前不能进严格 plan" |
+| 待确认项 | 仍需用户/业务方/技术负责人确认的内容,不藏在正文里 |
+
+## 质量检查(输出前)
+
+- plan 编写者能据此拆解;规则/行为/边界没有混在一起含糊。
+- 数据/状态/权限/异常/兼容性/验收口径明确。
+- 没滑向客户 PRD / 任务计划 / 代码方案;未确认全标【待确认】;"不可留到实现期"已列出;Plan 约束足以防跑偏。
+
+## 产物位置与命名
+
+- 路径:`docs/features/<feature-id>/<文件前缀>-spec.md`。无可写项目上下文 → 回复中直接输出正文。
+- **feature-id**:`YYYY-MM-DD-[业务ID-]<标题>`。业务ID 可选(字母数字 + 连字符);标题允许中/英/混合,**不得**中文转英文 slug;重名追加短后缀;同目录已有 PRD 优先复用同一 feature-id。
+- **文件前缀**:有业务ID = `<业务ID>-<标题>`,无 = `<标题>`。
+- 敏感字符(`/ \ : * ? " < > |`)拒绝,要求用户重命名,不自动替换。
+- 与旧目录共存:始终新命名,不探测旧 `spec.md`。
+
+## 收尾
+
+产物落盘后自动跑 `cgraphx features sync`(更新 `.cgraphx/my-features.md` 本人需求索引——本地文件、幂等、不问用户)。然后只提示用户审阅并指出需要调整的地方。**不主动继续写 plan 或代码。** 用户日后找需求目录:`cgraphx features list --mine`。
+
+## 红线(绝对不能做)
+
+1. ❌ **不编造**未确认的业务规则/接口行为/数据结构/技术约束——标【待确认】或先确认。
+2. ❌ **不把【待确认】伪装成已确认规格**(尤其影响 plan 写死的)。
+3. ❌ **不把实现手段选型写进 spec**(同步/异步、缓存、定时任务归 plan)——写可观察后果与预期。
+4. ❌ **不展开成任务列表/文件级修改步骤/代码实现细节**。
+5. ❌ **不重新澄清已确认内容**;模糊想法 → 提醒 clarify 流程,不硬写。
+6. ❌ **不自动进入 plan/implementation**——输出后提示即停。
+7. ❌ **不擅自中文转英文 slug**——命名归用户。

package/dist/.claude-template/skills/write-unit-test-code/SKILL.md

@@ -53,7 +53,7 @@ description: 基于 write-unit-test-spec 产出的测试规格文档 + 已有实
 
 ### 3. 读已有实现代码
 
-根据测试规格描述的被测目标,在代码库定位已有实现(用 `codegraph_explore` MCP / `cgraphx query` CLI / grep / Read):
+根据测试规格描述的被测目标,在代码库定位已有实现(用 grep / Read):
 - 读函数签名、参数、返回值、抛错行为、依赖关系
 - 如果测试规格里的某个场景**代码里还没实现**:
   - 对应测试用 `it.skip` + `// TODO: 实现提供后填实` 占位
@@ -83,7 +83,7 @@ description: 基于 write-unit-test-spec 产出的测试规格文档 + 已有实
 **产出单元测试报告**,写到 `docs/features/<feature-id>/<前缀>-单元测试报告.md`。结构轻量,至少包含:
 
 - 测试概况:总数 / 通过 / 失败 / 跳过(it.skip 占位)/ 时长
-- 逐场景结果:每个 `it` 的通过/失败/跳过 + 失败原因(如有)
+- 逐场景详细结果:每个 `it` 的通过/失败/跳过 + 入参 + 执行过程 + 断言判定 + 失败原因(如有)
 - 实现与 spec 偏差小结
 - 待确认项汇总(实现缺失 / spec 不够细等)
 - 下一步建议(失败 → 建议改实现 / 改测试 / 改 spec;跳过多 → 建议先补实现再回来跑)
@@ -93,6 +93,91 @@ description: 基于 write-unit-test-spec 产出的测试规格文档 + 已有实
 - 失败 → 报告如实标失败 + 原因分类(测试写错 / 实现有 bug / spec 和实现偏差),**不修实现,不假装通过**
 - 全部跳过(实现都没写)→ 报告标"无可跑测试,所有场景待实现",建议用户先跑 implementation
 
+**逐场景详细结果格式**:
+
+```markdown
+### 2.1 ✅ 通过 — 主路径 · 正常输入应返回期望结果
+
+| 维度 | 内容 |
+|---|---|
+| **场景** | 主路径 |
+| **用例** | 正常输入应返回期望结果 |
+| **状态** | ✅ 通过 |
+| **耗时** | 12 ms |
+
+#### 入参
+| 参数 | 值 | 类型 | 来源 |
+|---|---|---|---|
+| input | `{ name: "张三", age: 25 }` | object | 测试规格 §2.1 |
+
+#### 执行过程
+```typescript
+// 被测函数调用
+const result = processUser({ name: "张三", age: 25 });
+```
+
+#### 断言判定
+| # | 断言项 | 期望值 | 实际值 | 结果 |
+|---|---|---|---|---|
+| 1 | result.name | "张三" | "张三" | ✅ |
+| 2 | result.age | 25 | 25 | ✅ |
+| 3 | result.id | 存在 | 12345 | ✅ |
+```
+
+---
+
+```markdown
+### 2.2 ❌ 失败 — 边界 · 空值输入应抛错
+
+| 维度 | 内容 |
+|---|---|
+| **场景** | 边界 |
+| **用例** | 空值输入应抛错 |
+| **状态** | ❌ 失败 |
+| **耗时** | 8 ms |
+
+#### 入参
+| 参数 | 值 | 类型 | 来源 |
+|---|---|---|---|
+| input | `null` | null | 测试规格 §2.2 |
+
+#### 执行过程
+```typescript
+// 被测函数调用
+const result = processUser(null);
+```
+
+#### 断言判定 — 失败原因
+| # | 断言项 | 期望值 | 实际值 | 结果 |
+|---|---|---|---|---|
+| 1 | 抛出 ValidationError | `throw ValidationError` | `TypeError: Cannot read property 'name' of null` | ❌ **失败** |
+
+#### 失败分析
+- **可能原因**: 代码未做空值校验，直接访问了 input.name
+- **建议下一步**: 走 `/implementation` 在函数开头加空值校验
+```
+
+---
+
+```markdown
+### 2.3 ⏭️ 跳过 — 异常 · 权限不足应返回 403
+
+| 维度 | 内容 |
+|---|---|
+| **场景** | 异常 |
+| **用例** | 权限不足应返回 403 |
+| **状态** | ⏭️ 跳过 |
+| **原因** | 实现缺失 |
+
+#### 跳过原因
+被测代码中 `checkPermission` 函数尚未实现，对应测试用 `it.skip` 占位。
+
+```typescript
+it.skip('权限不足应返回 403', () => {
+  // TODO: 实现提供后填实
+});
+```
+
 ### 6. 汇报 + 不自动继续
 
 告诉用户:

package/dist/.claude-template/skills/write-workload/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: write-workload
+disable-model-invocation: true
+description: 产出「需求工作量汇报」文档,用于内部对账 / 甲方结款依据。当用户交付完一个需求、需要向甲方或内部汇报工作量、出结款依据、算工时、对账,或说「汇报工作量 / 需求工作量 / 工时汇报 / 工时统计 / 结款 / 对账 / 向甲方汇报 / 工作量评估 / 做了多少东西 / 值多少钱 / effort report / workload report / billing」时使用。即使没有明说「结款」,只要意图是量化已交付工作并对外汇报,就用本 skill。流程核心:先摸清汇报口径定维度(不直接开写),查代码核实交付物防虚报,补工时每项配理由+对应交付物,输出工作量汇报文档(含工时拆解+合理性佐证+可核验交付物,章节按需求复杂度组装,不套固定模板)到需求目录。对账场景必须有工时合理性佐证以应对「几个文件要这么多天」的质疑,工时数字不得凭空编造。
+---
+
+# write-workload — 需求工作量汇报(对账 / 结款)
+
+把一个**已交付的需求**量化成一份经得起甲方/财务追问的工作量汇报,作为内部对账、结款依据。
+
+## 这个 skill 的灵魂(先读这段)
+
+用户说「汇报工作量」时,最自然的反应是直接开写一份工时表。**别这样**。这个 skill 的全部价值在于五条心法,它们是从实战里踩出来的,每一条都对应一个真实翻车点:
+
+1. **维度先于内容** — 受众和口径不同,骨架完全不同(给业务方讲进度 / 给财务对账 / 给技术评审是三套东西)。直接写必返工。所以第一步永远是**问清口径再动笔**,哪怕只问两三个问题。
+2. **对账必配佐证** — 结款场景最致命的反问是「就改了这几个文件,要 X 人天?」。**代码量小但工时不少是常态**,因为联调、契约核实、外部对接都不体现在代码行数。工时拆解骨架如果不配一层「影响范围佐证」,工时数字就站不住。
+3. **隐性工时显性化** — 把代码里看不见的工作逐项列成工时项:需求待确认项的逐一核实、外部接口联调、跨服务契约逆向确认、配置映射纠正、返回键核对、多场景自测。**这是「工时比代码看着多」的合法性来源**,也是佐证层的主干。
+4. **工时数字不编** — 结款是钱。**你(Claude)不能凭空给工时数字。** 要么用户给真实记录,要么用户明确授权「你来估」并给区间,你才能填且标注是估算。被发现编数字是对账场景的信任灾难。
+5. **查代码核实交付物** — 需求文档 / plan 和实际代码经常有出入(方法名、URL、响应结构、映射表、查询方式都可能被改过)。不核实就按文档报,会虚报或错报,对账时穿帮。**汇报前必须回代码核实每一项交付物真实存在。**
+
+把这五条内化后,下面的流程就是它们的展开。
+
+## 何时触发
+
+- 用户交付完一个需求,要向甲方 / 内部出工作量汇报、结款依据、工时统计。
+- 关键词:工作量汇报 / 需求工作量 / 工时(汇报|统计) / 结款 / 对账 / 向甲方汇报 / 工作量评估 / 做了多少东西 / effort / workload / billing。
+- 即使没明说「结款」,只要意图是**量化已交付工作并对外汇报**,就走本 skill。
+
+> 不触发:纯进度同步(轻量,几句话即可)、未交付的纯技术方案评估(走 write-spec/plan)、代码质量评审(走 code-review)。
+
+## 输入
+
+一个需求,通常在 `docs/features/<feature-id>/` 下,含:需求文档 / spec / plan / 已落地代码。用户也可能只给一个需求编号或一句话描述,需要你先定位需求目录。
+
+## 流程
+
+### Step 0 · 摸清汇报口径(先问,不先写)
+
+这是最关键的一步,跳过它后面全错。用 `AskUserQuestion` 一次性问清(2~3 个问题):
+
+- **受众是谁?** — 内部对账/财务(要量化、可核验)/ 甲方项目经理(要进度+数字)/ 甲方技术负责人(要方案合理性)/ 内部领导。受众决定深度和口径。
+- **代码处于什么阶段?** — 已联调自测通过 / 代码写完未联调 / 还没写只是预估。决定汇报是「已交付」还是「预估」。
+- **结款按什么口径?** — 任务工时拆解(T&M,按人天)/ 交付物计价(按交付的文件接口)/ 功能点法。决定主维度骨架。
+
+> 问问题的目的不是走流程,是让骨架选对。问完你心里要有数:这份报告主维度是什么、要不要加固层、工时数字从哪来。
+
+### Step 1 · 读需求 + 查代码核实交付物
+
+1. 读需求文档 / spec / plan,理清这个需求做了什么。
+2. **用 grep / read 核实代码**:
+   - 核实每一项交付物**真实存在**:接口、实现类、新建文件、MDA 常量、配置、外部对接。
+   - **识别 plan / 需求文档与实际代码的出入**(方法名变没变?URL 对不对?响应结构是平铺还是嵌套?映射表准不准?批量查询方式?)。这些出入既是核实,也是隐性工时的来源(纠正它们花了时间)。
+3. 核实跨服务契约:依赖的下游服务方法是否真按预期返回(返回键、分支逻辑)。
+
+> 这一步的产出是一份「真实的交付物清单 + plan 与代码的 diff」。后面工时和佐证都基于它,不是基于需求文档的描述。
+
+### Step 2 · 定维度与骨架
+
+基于 Step 0 的口径选主维度骨架。**用 `AskUserQuestion` 带 preview 让用户对比骨架**(preview 里放每种骨架的报告结构 ASCII 图,用户一眼能选):
+
+- **任务工时拆解 + 影响范围佐证**(结款/对账默认推荐):工时拆解为主,叠加跨服务/外部对接佐证层,人天作汇总。
+- **交付物 + 影响范围**:以客观交付物(文件/接口/外部对接/测试)为主轴,影响范围作定价加权。适合交付物计价/验收结款。
+- **功能点法**:EI/EO/EQ/EIF/ILF 估算 UFP → 复杂度加权 → 折算人天。适合大型正式验收,单接口偏重。
+
+> 为什么用 preview:骨架的差别用文字讲不清,但用结构图对比用户一秒就能选。别省这一步。
+
+### Step 3 · 定内容策略
+
+两个决策(可并入 Step 2 的提问):
+
+- **工时口径**:按真实报(代码看着少但实际多,差额靠佐证解释)/ 按预估(还没做,给区间)。
+- **要不要加固层**:对账场景**默认要加**影响范围佐证层,这是对冲「几个文件要这么多天」的唯一手段。
+
+### Step 4 · 补工时
+
+参见下方「工时补全规则」。**数字不编,每项配理由 + 对应交付物。**
+
+### Step 5 · 出文档
+
+按「文档结构:必含要素 + 按需组装」组织章节(不套固定模板),保存到需求目录(见「hx 项目约定」的命名规则)。
+
+## 工时补全规则
+
+- **每项工时落在 0.5~2 天**(用户给的范围默认值,可按项目调整),超出要拆分或说明。
+- **每项必须配三件套**:工时数字 + 一句话理由(为什么是这个天数)+ 对应交付物(可核验,指向具体文件/接口/外部对接)。三件套缺一不可,这是对账时逐项核对的依据。
+- **数字来源优先级**:
+  1. 用户给真实人天记录 → 直接填。
+  2. 用户授权「你来估」+ 给区间 → 你按代码复杂度和隐性成本估,每项标注理由,**合计处可注明「估算」**。
+  3. **都没有 → 不填数字,留 `[__]` 占位并明确告诉用户「这是核心数字,我不编,你填」。** 绝不凭空写一个看似合理的数。
+- **隐性工时必须显性化成独立工时项**:需求待确认项核实、外部接口对接联调、跨服务契约逆向确认、配置/映射纠正、返回键核对、多场景自测 —— 这些代码行数小但耗时大,是工时主要构成,**必须单列**,不能藏在「开发」一项里。
+- **总量自检**:合计 ÷ 交付物数量 是否合理?隐性工时占比是否说得通?如果总数看起来「虚」,要么补佐证,要么调数字,别硬交。
+
+## 文档结构:必含要素 + 按需组装(不要套固定章节)
+
+不同需求的章节不一样——单服务小改动和跨服务外部对接的汇报,章节数、标题、侧重都不同。**别强行套固定模板。** 但结款汇报有几个必含的逻辑要素,缺了就不合格;其余按需求伸缩。
+
+### 必含要素(逻辑闭环,缺一不可)
+1. **工时拆解**(主维度)—— 结款的核心数字。用工时三件套(任务项 / 工时 / 理由 / 对应交付物)。
+2. **工时合理性佐证** —— 对冲「几个文件要这么多天」。形式自由:可独立成节,也可融进工时表「理由」列(每项配了为什么,本身就是佐证)。跨服务 / 外部对接 / 隐性工时多时,建议独立成节把隐性工时摊开。
+3. **可核验交付物清单** —— 文件 / 接口 / 外部对接 / 测试,让每条工时能对照到实物。
+4. **工时数字来源声明** —— 心法 #4。一句话注明:真实记录 还是 估算。
+
+### 按需要素(看情况取舍)
+- **需求背景**:给非技术读者(财务)或需求复杂时写;简单需求 / 技术读者一句带过或省略。
+- **影响范围**(跨服务 / 外部对接):跨度大单独成节;单服务改动并入工时理由即可。
+- **遗留 / 风险**:有就写,没有不硬凑。
+
+### 组织原则
+- 章节数量、标题、合并 / 拆分**按需求定,没有固定形态**。唯一不能省的是上面四个必含要素的**逻辑**(形式可变)。
+- 简单需求(单服务、小改动):工时表(理由列即佐证)+ 交付物清单,两节足矣。
+- 复杂需求(跨服务 / 外部对接):工时拆解 + 独立佐证节 + 交付物 + 遗留,四到五节。
+
+> 复杂需求四到五节的范例见下方「真实样例」(req74442)。那是「一种」组织方式,不是「唯一」模板。
+
+## 项目约定
+
+- **需求目录**:`docs/features/<feature-id>/`。先定位用户给的 feature 目录。
+- **文件命名**:`<前缀>-需求工作量.md`。**前缀沿用该需求目录里已有文件的命名前缀**(如 `CRM-req74442-电渠批量违约金试算接口`),保持族内一致。保存到该需求目录根下(不进 plan/ 子目录)。
+- **查代码**:用 grep / Read;跨服务契约定要分别核实每个服务。
+- **元信息表日期**:用当天日期(会话上下文里的 currentDate)。
+- **术语对齐**:用 CLAUDE.md 和 docs/knowledge/ 里的项目术语(prodInst / offer / bizCode / atom / @Center 等),别自造。
+
+## 收尾自检(交文档前)
+
+- [ ] 主维度和受众口径匹配(Step 0 确认过)
+- [ ] 每项工时有三件套,数字有来源(没编)
+- [ ] 工时合理性佐证在(独立成节 或 融进工时表理由列),能回答「几个文件要这么多天」
+- [ ] 交付物清单每一项都核实过真实存在
+- [ ] 文件名前缀和需求目录族内一致,存对位置
+- [ ] 遗留/风险如实写(测试地址待切生产、入参口径出入等),不藏

package/dist/cli/fatal-handler.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Render an uncaught value for the last-resort log WITHOUT triggering
+ * stack formatting. Pure and total — never throws, never touches `.stack`.
+ */
+export declare function describeFatal(value: unknown): string;
+/** Injectable seams so the wiring is testable without registering real handlers. */
+export interface FatalHandlerDeps {
+    /** Event target to attach to. Defaults to `process`. */
+    target?: NodeJS.EventEmitter;
+    /** How to terminate. Defaults to `process.exit`. */
+    exit?: (code: number) => void;
+    /** How to emit the bounded line. Defaults to a synchronous fd-2 write. */
+    write?: (line: string) => void;
+}
+/**
+ * Install the uncaught-exception / unhandled-rejection handlers. Both
+ * log a bounded line and then exit non-zero (Node's default fatal
+ * semantics).
+ */
+export declare function installFatalHandlers(deps?: FatalHandlerDeps): void;
+//# sourceMappingURL=fatal-handler.d.ts.map

package/dist/cli/fatal-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fatal-handler.d.ts","sourceRoot":"","sources":["../../src/cli/fatal-handler.ts"],"names":[],"mappings":"AAyBA;;;GAGG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAcpD;AAWD,oFAAoF;AACpF,MAAM,WAAW,gBAAgB;IAC/B,wDAAwD;IACxD,MAAM,CAAC,EAAE,MAAM,CAAC,YAAY,CAAC;IAC7B,oDAAoD;IACpD,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC9B,0EAA0E;IAC1E,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAChC;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,GAAE,gBAAqB,GAAG,IAAI,CActE"}