cgraphx 1.4.1 → 2.0.0

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

@@ -0,0 +1,221 @@
+---
+name: write-unit-test-code
+description: 基于 write-unit-test-spec 产出的测试规格文档 + 已有实现代码,填实单元测试代码 + 跑测试 + 出报告。读测试规格派生场景 → 读实现代码定位被测目标(函数/类/模块)→ 产出 .test.ts(断言填实,能真跑)→ 跑测试 → 出 <前缀>-单元测试报告.md。被测代码缺失的场景用 it.skip + TODO 占位。依赖测试规格文档存在 —— 找不到时报错退出,要求先跑 /write-unit-test-spec。Use when 想填实测试代码 / 写单元测试 / 跑单元测试 / write-unit-test-code. 不写业务实现代码、不修实现 bug、不假装通过.
+---
+
+# Write Unit Test Code
+
+## 定位
+
+**测试填实 + 验证 skill**:消费 `write-unit-test-spec` 产出的测试规格文档,基于已有实现代码填实测试代码,跑测试验证,出测试报告。
+
+**和 write-unit-test-spec 的分工**:
+- write-unit-test-spec:产**测试规格文档**(该测哪些场景,基于 spec,零代码依赖)
+- 本 skill(write-unit-test-code):基于测试规格 + 已有实现,填实测试代码 + 跑 + 出报告
+
+两个 skill 顺序依赖:本 skill 找不到测试规格文档时报错退出。
+
+**和 implementation 的关系**:平行线路。implementation 写业务实现代码,本 skill 写测试代码。本 skill 假设被测代码已存在(典型场景:用户跑完 implementation 后回来补测试);代码缺失的场景用 `it.skip` + TODO 占位。
+
+## HARD-GATE
+
+- **不写业务实现代码** —— 本 skill 只写测试代码 + 测试报告,业务实现是 implementation 的事
+- **依赖测试规格文档** —— 当前 feature 没有 `<前缀>-单元测试-spec.md` 时,报错退出:"找不到测试规格,请先跑 /write-unit-test-spec"。不自己现场派生测试场景(那是 write-unit-test-spec 的职责)
+- **不编造被测目标** —— 测试里 import 的函数/类/模块必须**已存在**。不存在 → 对应场景用 `it.skip` + `// TODO: 实现提供后填实` 占位,不自己造签名
+- **不修实现代码** —— 测试失败时如实报告,不替用户改业务代码
+- **不假装通过** —— 测试断言不调到"假绿"。失败就是失败,如实标在报告里
+
+## Trigger
+
+**使用此 skill 当**:
+- 用户跑完 `/write-unit-test-spec`,想填实测试代码
+- 用户跑完 implementation,想基于测试规格补测试
+- 用户明确说"填实测试 / 写单元测试代码 / 跑单元测试 / write-unit-test-code"
+
+**不要使用此 skill 当**:
+- 没有测试规格文档 —— 先跑 `/write-unit-test-spec`
+- 想写业务实现 —— 用 `/implementation`
+- 想产测试规格(不填实)—— 用 `/write-unit-test-spec`
+- 纯文档 / 配置 / 无行为变更的需求 —— 无可测代码
+
+## 流程
+
+### 1. 前置检查
+
+- 确认 `docs/features/<feature-id>/<前缀>-单元测试-spec.md` 存在。**不存在 → 报错退出**:"找不到测试规格,请先跑 /write-unit-test-spec"。不现场派生场景。
+- 复用测试规格的 feature-id 和文件前缀,推导出测试文件路径和报告文件名。
+
+### 2. 读测试规格文档
+
+读 `<前缀>-单元测试-spec.md`,拿到:
+- 必测场景清单(主路径 / 边界 / 异常,每条标 spec 依据)
+- 测试骨架映射(测试文件该放哪、框架、命名)
+
+### 3. 读已有实现代码
+
+根据测试规格描述的被测目标,在代码库定位已有实现(用 grep / Read):
+- 读函数签名、参数、返回值、抛错行为、依赖关系
+- 如果测试规格里的某个场景**代码里还没实现**:
+  - 对应测试用 `it.skip` + `// TODO: 实现提供后填实` 占位
+  - 记入"实现缺失场景清单",汇报时告诉用户"有 N 个场景因实现缺失跳过"
+  - **不自己造签名**
+- 如果实现和 spec 不一致(测试规格基于 spec,但代码偏离了 spec):
+  - 在测试报告里标注"实现与 spec 偏差:X(spec 说 A,代码实际 B)"
+  - 测试按**代码实际行为**写(要能跑过)
+  - 偏差记录留给用户决定(改代码 / 改 spec / 接受现状)
+
+### 4. 产出测试文件(断言填实)
+
+写到 `<项目测试目录>/<feature-id>.test.ts`(或项目约定的命名/后缀,从测试规格的"骨架映射"节读取)。形态:
+
+- 实现已就绪的场景 → `describe` + `it`(含真实断言,基于读到的签名写,能真跑)
+- 实现缺失的场景 → `it.skip` + `// TODO: 实现提供后填实` 占位
+- import 被目标(已存在的模块直接 import;不存在的标 TODO 注释,不强行 import)
+- 框架(vitest/jest/...)和文件后缀按项目约定
+- 已有同模块测试文件 → 文件名加后缀避免覆盖(如 `<feature-id>.补充.test.ts`),在报告里提示"已有 X,是否合并由用户判断"
+
+**AI 自己发挥的空间**:fixture / mock 怎么组织、describe 嵌套多深、断言写多细,agent 按既有测试风格判断,不强加模板。
+
+### 5. 跑测试验证 + 产出测试报告
+
+跑一次项目的测试命令(如 `npm test`),确认新写的测试能跑(通过或失败都行,失败说明实现有 bug 或测试断言写错)。
+
+**产出单元测试报告**,写到 `docs/features/<feature-id>/<前缀>-单元测试报告.md`。结构轻量,至少包含:
+
+- 测试概况:总数 / 通过 / 失败 / 跳过(it.skip 占位)/ 时长
+- 逐场景详细结果:每个 `it` 的通过/失败/跳过 + 入参 + 执行过程 + 断言判定 + 失败原因(如有)
+- 实现与 spec 偏差小结
+- 待确认项汇总(实现缺失 / spec 不够细等)
+- 下一步建议(失败 → 建议改实现 / 改测试 / 改 spec;跳过多 → 建议先补实现再回来跑)
+
+**报告原则**:
+- 通过 → 报告"测试已就绪,N 个场景覆盖"
+- 失败 → 报告如实标失败 + 原因分类(测试写错 / 实现有 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. 汇报 + 不自动继续
+
+告诉用户:
+- 测试文件路径
+- **单元测试报告路径** + 报告里的关键数字(通过/失败/跳过数)
+- 实现与 spec 的偏差(如有)
+- 待确认项(如有)
+
+**不调用 implementation / write-unit-test-spec / run-api-test**,由用户决定下一步。
+
+## 产物
+
+| 产物 | 路径 | 形态 |
+|---|---|---|
+| 测试文件 | `<项目测试目录>/<feature-id>.test.ts` | describe + `it`(断言填实) / `it.skip`(实现待补) |
+| 单元测试报告 | `docs/features/<feature-id>/<前缀>-单元测试报告.md` | 测试概况 + 逐场景结果 + 偏差小结 + 下一步建议 |
+
+## 边界场景
+
+- **找不到测试规格文档** → 报错退出,要求先跑 `/write-unit-test-spec`。不现场派生场景。
+- **实现代码缺失** → 对应场景 `it.skip` + TODO 占位,汇报时告诉用户。不造签名。
+- **已有同模块测试文件** → 文件名加后缀避免覆盖,报告里提示用户。不主动改既有测试。
+- **跨语言项目** → 按测试规格文档里标注的语言约定产出。一次调用不产多语言测试。
+- **实现与 spec 偏差** → 测试按代码实际行为写(要能跑过),偏差记录在报告里,汇报时提示用户。
+- **纯文档/配置需求** → 检测到测试规格无可测场景 → 提示"规格里无可测场景,不建议继续"并退出。
+
+## 不做的事
+
+- 不写业务实现代码(那是 implementation 的事)
+- 不现场派生测试场景(那是 write-unit-test-spec 的事,本 skill 找不到规格就退出)
+- 不修实现代码(失败如实报告)
+- 不假装通过(断言不调到假绿)
+- 不引入硬 gate(precommit hook / 提交拦截)
+- 不假设测试框架(从测试规格的骨架映射读,或运行时探测)
+- 不改 write-unit-test-spec / implementation / write-plan(它们对本 skill 零依赖)
+
+## 和其他 skill 的关系
+
+- **write-unit-test-spec**:上游,提供测试规格文档。本 skill 找不到它就退出。
+- **implementation**:平行线路,写业务实现。本 skill 读它的产物(代码),但不调它。
+- **run-api-test**:不同类型的测试(接口测试 vs 单元测试),互不干涉。