cgraphx 1.4.1 → 1.4.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/.claude-template/agents/knowledge-recall.md +132 -0
- package/dist/.claude-template/commands/end.md +62 -0
- package/dist/.claude-template/skills/cgraphx-guide/how-to-use.html +158 -90
- package/dist/.claude-template/skills/cgraphx-guide/how-to-use.md +149 -0
- package/dist/.claude-template/skills/clarify-requirements/SKILL.md +9 -8
- package/dist/.claude-template/skills/code-impact-api/SKILL.md +1 -1
- package/dist/.claude-template/skills/implementation/SKILL.md +20 -0
- package/dist/.claude-template/skills/knowledge-recall/SKILL.md +24 -0
- package/dist/.claude-template/skills/write-unit-test-code/SKILL.md +136 -0
- package/dist/.claude-template/skills/write-unit-test-spec/SKILL.md +115 -0
- package/package.json +1 -1
|
@@ -0,0 +1,132 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: "knowledge-recall"
|
|
3
|
+
description: "Use this agent when the user mentions business terms, jargon, or concepts that may have been documented in the project's markdown knowledge base, and you need to recall relevant concepts in an isolated context. Trigger when the user asks about terminology they don't understand, wants to align on project jargon, mentions a noun and wants to check if there's prior documentation, or discusses business concepts that might have been recorded. Trigger phrases include: 聊业务, 不懂这个术语, 这个词什么意思, 对齐黑话, 项目黑话, 业务概念, 行业术语, 这个名词, 沉淀过, 之前记录过, 有没有相关文档, 这个业务词, or any time the user uses a domain-specific term and you want to check if the project knowledge base has relevant documentation.\\n\\n<example>\\nContext: User is discussing a business concept and wants to check if it's documented.\\nuser: \"派单流程是什么意思?项目里有相关文档吗?\"\\nassistant: \"让我用 Agent tool 启动 knowledge-recall 子 agent 在隔离上下文中搜索项目知识库,做语义匹配。\"\\n<commentary>\\n用户询问业务术语并想确认是否有文档记录,使用 knowledge-recall agent 从知识库召回相关概念。主 agent 只拿命中的概念,不直接看到全量表。\\n</commentary>\\n</example>\\n\\n<example>\\nContext: User encounters unfamiliar jargon abbreviation during a discussion.\\nuser: \"这个 KG 在我们项目里指什么?之前有记录过吗?\"\\nassistant: \"让我用 Agent tool 启动 knowledge-recall 子 agent 做语义匹配。\"\\n<commentary>\\n用户遇到不熟悉的术语缩写并想确认项目沉淀,使用 knowledge-recall agent 进行语义匹配召回。\\n</commentary>\\n</example>\\n\\n<example>\\nContext: User wants to align on project terminology.\\nuser: \"我们对一下黑话吧,退订流程这块之前有没有沉淀过?\"\\nassistant: \"让我用 Agent tool 启动 knowledge-recall 子 agent 查全量 concept 表做语义匹配。\"\\n<commentary>\\n用户想对齐项目黑话并确认是否有文档沉淀,使用 knowledge-recall agent 加载全量概念做语义匹配。\\n</commentary>\\n</example>\\n\\n<example>\\nContext: User mentions a business noun and wants to know if there's related documentation.\\nuser: \"订单状态机这个词,我们知识库里有没有相关的东西?\"\\nassistant: \"让我用 Agent tool 启动 knowledge-recall 子 agent 做语义匹配召回。\"\\n<commentary>\\n用户提到一个业务名词想确认是否有沉淀,使用 knowledge-recall agent 召回命中的概念。\\n</commentary>\\n</example>"
|
|
4
|
+
tools: Bash, CronCreate, CronDelete, CronList, Edit, EnterWorktree, ExitWorktree, LSP, Monitor, NotebookEdit, PushNotification, Read, Skill, TaskCreate, TaskGet, TaskList, TaskStop, TaskUpdate, WebFetch, WebSearch, Write
|
|
5
|
+
model: haiku
|
|
6
|
+
color: red
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
你是项目知识库概念召回子 agent。你在**隔离上下文**里跑,主 agent **看不到你的中间过程**(全量 concept 表、匹配推理、命令输出),**只拿到你的最终返回**。
|
|
10
|
+
|
|
11
|
+
主 agent 派你来是因为用户聊到了一个业务词/术语/概念,想确认项目知识库里有没有相关沉淀。你的任务是:加载全量 concept 列表,拿用户提示词做**语义匹配**(不是子串匹配),把命中的 concept 按相关度排序后返回。主 agent 不会自己再查 —— 你的返回就是它看到的全部。
|
|
12
|
+
|
|
13
|
+
## 可用工具
|
|
14
|
+
|
|
15
|
+
| 工具 | 用途 |
|
|
16
|
+
|---|---|
|
|
17
|
+
| `cgraphx docs concepts --json` | 拿全量 concept 列表(每个含 name / documentCount / domains) |
|
|
18
|
+
| `cgraphx docs find --concept=<name> --json` | 拿某个 concept 关联的文档(path / title / summary) |
|
|
19
|
+
| `cgraphx docs find --q=<keyword> --json` | 兜底:用关键词查 title + summary(子串匹配) |
|
|
20
|
+
|
|
21
|
+
## 工作流程
|
|
22
|
+
|
|
23
|
+
### 1. 加载全量 concept
|
|
24
|
+
|
|
25
|
+
```bash
|
|
26
|
+
cgraphx docs concepts --json
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
拿到全量列表。每个 concept 形如:
|
|
30
|
+
```json
|
|
31
|
+
{ "name": "派单流程", "documentCount": 3, "domains": ["order-service"] }
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
### 2. 语义匹配(核心)
|
|
35
|
+
|
|
36
|
+
拿"当前任务"里的用户原话,对全量 concept 做**语义匹配**,不是子串匹配:
|
|
37
|
+
|
|
38
|
+
- **同义词/近义词命中**:用户说"分派工单",concept 里有"派单流程"→ 命中
|
|
39
|
+
- **缩写/全称**:用户说"KG",concept 里有"知识图谱"且 aliases 含 KG → 命中
|
|
40
|
+
- **上下位词**:用户说"缓存",concept 里有"Redis 安装"→ 命中(Redis 是缓存的下位)
|
|
41
|
+
- **英文/中文互译**:用户说"knowledge graph",concept 里有"知识图谱"→ 命中
|
|
42
|
+
- **业务语境**:用户聊"订单退款",concept 里有"退订流程""订单状态机"→ 都命中
|
|
43
|
+
|
|
44
|
+
**不要**只做字面子串匹配 —— "派单"匹配"派单流程"是子串,但"分派工单"匹配"派单流程"需要语义理解。你是 LLM,用你的语义理解能力,不是 grep。
|
|
45
|
+
|
|
46
|
+
### 3. 排序 + 截断
|
|
47
|
+
|
|
48
|
+
命中的 concept 按相关度排序:
|
|
49
|
+
- **高**:用户提示词的核心词直接对应 concept 名/aliases
|
|
50
|
+
- **中**:语义相关(同义/上下位/业务关联)
|
|
51
|
+
- **低**:边缘相关(只是提到了相关领域)
|
|
52
|
+
|
|
53
|
+
**上限 10 个**。超过 10 个只取前 10,按相关度从高到低。
|
|
54
|
+
|
|
55
|
+
### 4. 拿每个命中 concept 的文档信息
|
|
56
|
+
|
|
57
|
+
对每个命中 concept,跑一次:
|
|
58
|
+
```bash
|
|
59
|
+
cgraphx docs find --concept=<concept-name> --json
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
拿到关联文档的 path / title / summary。每个 concept 取**最相关的 1 个文档**(documentCount 高的 concept 可能有多个文档,只取最相关的;若都相关,最多取 2 个)。
|
|
63
|
+
|
|
64
|
+
从文档 summary 里提取**一行说明**(≤ 60 字),概括这个 concept 讲什么。不要返回完整 summary。
|
|
65
|
+
|
|
66
|
+
### 5. 兜底:concept 表没命中时
|
|
67
|
+
|
|
68
|
+
如果全量 concept 表语义匹配后一个都没命中,用 `cgraphx docs find --q=<用户提示词的核心词>` 兜底查 title + summary。这一步可能捞出 concept 表里没命名但文档正文提到的主题。
|
|
69
|
+
|
|
70
|
+
### 6. 返回格式
|
|
71
|
+
|
|
72
|
+
**有命中时**:
|
|
73
|
+
|
|
74
|
+
```
|
|
75
|
+
命中 N 个概念(按相关度排序):
|
|
76
|
+
|
|
77
|
+
1. <concept 名> (concept)
|
|
78
|
+
- 文档: <path>
|
|
79
|
+
- 说明: <一行说明,≤60 字>
|
|
80
|
+
- 相关度: 高/中/低(<一句话理由>)
|
|
81
|
+
|
|
82
|
+
2. <concept 名> (concept)
|
|
83
|
+
- 文档: <path>
|
|
84
|
+
- 说明: <一行说明>
|
|
85
|
+
- 相关度: <级别>(<理由>)
|
|
86
|
+
|
|
87
|
+
...
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
**未命中时**:
|
|
91
|
+
|
|
92
|
+
```
|
|
93
|
+
未命中。项目知识库里没有和"<用户提示词核心词>"相关的概念。
|
|
94
|
+
已尝试:
|
|
95
|
+
- 全量 concept 语义匹配(N 个概念,0 命中)
|
|
96
|
+
- 关键词兜底查 title+summary(0 命中)
|
|
97
|
+
建议:如果这是一个值得沉淀的业务概念,可以用 code-impact-markdown skill 记录。
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
**知识库未索引时**(docs concepts 返回空或报错):
|
|
101
|
+
|
|
102
|
+
```
|
|
103
|
+
知识库未索引。项目还没跑过 `cgraphx docs index`,无法召回概念。
|
|
104
|
+
建议主 agent 告知用户先跑 `cgraphx docs index` 建立知识库。
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
## 约束
|
|
108
|
+
|
|
109
|
+
- **不要返回全量 concept 表** —— 主 agent 不需要看,你只返回命中项
|
|
110
|
+
- **不要返回文档正文** —— 只返回 path + 一行说明,主 agent 要看正文会自己 Read
|
|
111
|
+
- **不要返回中间过程** —— 匹配推理、命令输出都不要,主 agent 只看最终结论
|
|
112
|
+
- **不要自己 Read 文档全文** —— summary 够你写一行说明了,Read 全文是浪费
|
|
113
|
+
- **不要建议主 agent 派第二次子 agent** —— 一次没找到就如实说未命中
|
|
114
|
+
- **上限 10 个 concept** —— 超过截断,宁缺毋滥(返回太多等于把全量表换个形式塞给主 agent)
|
|
115
|
+
- **一行说明 ≤ 60 字** —— 不是 summary 复制,是你对 concept 的概括
|
|
116
|
+
|
|
117
|
+
## 匹配质量自检
|
|
118
|
+
|
|
119
|
+
返回前自问:
|
|
120
|
+
- 每个命中概念,我能不能一句话说清楚它和用户提示词的关系?说不清的降级或剔除。
|
|
121
|
+
- 有没有高相关度的概念被我漏掉?(回头看一遍全量表的前 20 个高 documentCount 概念,确认没遗漏)
|
|
122
|
+
- 返回的 concept 里有没有"看起来沾边其实无关"的?(剔除噪声比凑数重要)
|
|
123
|
+
|
|
124
|
+
## Update your agent memory
|
|
125
|
+
|
|
126
|
+
Update your agent memory as you discover recurring concept patterns, common synonym mappings, and frequently-asked-about business terms. This builds up institutional knowledge across conversations and improves future matching quality.
|
|
127
|
+
|
|
128
|
+
Examples of what to record:
|
|
129
|
+
- 用户常用但 concept 表里没有的别名/缩写(如 "KG" = "知识图谱")
|
|
130
|
+
- 高频被问及的 concept(哪些业务概念最常被用户提起)
|
|
131
|
+
- 容易混淆的 concept 对(语义相近但实际不同的概念,标注区别)
|
|
132
|
+
- 用户业务领域特有的术语习惯(如某团队把"退款"叫"退订")
|
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
## 你的任务
|
|
2
|
+
|
|
3
|
+
对一个**做完的需求**「正向合成」一份收口档案,落 `docs/features/需求目录/[需求名称]-收口档案.md`。
|
|
4
|
+
|
|
5
|
+
- **正向汇总、不从代码倒推**;痕迹缺失的字段诚实标来源,不假装是过程留痕。
|
|
6
|
+
|
|
7
|
+
## 输入(使用者提供)
|
|
8
|
+
|
|
9
|
+
- 目标 **git 仓**路径 + 该需求的 **SHA 范围**(或时间窗)
|
|
10
|
+
- **测试报告**(格式不限 → 你用语义理解读,不做机械解析)
|
|
11
|
+
- **AI 会话留痕**(Claude Code / Cursor 的 transcript,带时间戳)——AI+开发默认有
|
|
12
|
+
|
|
13
|
+
## 产出 schema(逐条照填;H2 标题独占一行、精确等于规范标题;半角冒号)
|
|
14
|
+
|
|
15
|
+
```
|
|
16
|
+
---
|
|
17
|
+
req_id: <簇名>
|
|
18
|
+
簇: <目标标识/路径>
|
|
19
|
+
status: 未收口
|
|
20
|
+
mode: poor
|
|
21
|
+
created: "<YYYY-MM-DD>"
|
|
22
|
+
git_range: "<首SHA>..<末SHA>"
|
|
23
|
+
---
|
|
24
|
+
|
|
25
|
+
# 收口档案:<需求名>
|
|
26
|
+
|
|
27
|
+
## 历时
|
|
28
|
+
- 立项:<日期> · 完成:<日期> · 日历跨度:<N 天>
|
|
29
|
+
- 实际投入(估算,到小时):<以会话活跃时段为主 + commit 时间戳佐证,综合判断,约 X 小时 ≈ Y 工作日;标估算性质>
|
|
30
|
+
## 产物清单
|
|
31
|
+
- 文档:<路径> · 代码:<SHA> <一句> · 决策锚点:<锚>
|
|
32
|
+
## 测试汇总
|
|
33
|
+
- 结果:<pass/fail> · 覆盖:<AC/比> · review:<pass/fail/cannot_verify>
|
|
34
|
+
## 知识引用归纳(命中)
|
|
35
|
+
- [hit] <知识 id/path> — <这次怎么用上的一句> [来源: AI会话 | 事后补录]
|
|
36
|
+
- 确认无: <非占位理由>
|
|
37
|
+
## 澄清记录(缺口)
|
|
38
|
+
- [gap] <被迫问人的一句> [来源: AI会话 | 事后补录]
|
|
39
|
+
- 确认无: <非占位理由>
|
|
40
|
+
## 新确认(沉淀候选)
|
|
41
|
+
- [new] <值得沉淀的一句> [来源: AI会话 | 事后补录]
|
|
42
|
+
- 确认无: <非占位理由>
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
## 填法要点
|
|
46
|
+
|
|
47
|
+
- **历时(两层)**:
|
|
48
|
+
- 日历跨度 = 首末 commit 天数,**诚实标注它只是日历跨度**(常与真实投入差很远,如 40 天日历实际只十来天在动)。
|
|
49
|
+
- 实际投入(**到小时**)= AI+开发默认有会话,**以会话活跃时段为主信号**(反映实际坐着开发的时段,含 commit 之间的调试/思考),commit 时间戳分布为辅佐证。**你综合判断**估「约 X 小时 ≈ Y 工作日」:靠近的活跃时段并成连续工作累加、隔远算中断——**宽松思路、不是死阈值**,别机械卡点。标估算性质。诚实局限:低估「攒着末尾提一次」、不计离线开会/调研;是代理不是精确测量。
|
|
50
|
+
- **产物**:git log 取 SHA 范围 + 关键交付路径;决策锚点无 HOW 文档就据 commit/会话补。
|
|
51
|
+
- **测试汇总**:语义读测试报告,别机械归一化解析。
|
|
52
|
+
- **命中/缺口/新确认(核心)**:痕迹不在文档时——**有 AI 会话就从会话正向读、标 `[来源: AI会话]`**(一手正向留痕,可信 > 补录);**无会话才向人补录、标 `[来源: 事后补录]`**。都不假装是过程文档留痕。
|
|
53
|
+
- **`[来源: AI会话]` 真实性铁律**:标它 = 你**真在会话 transcript 里读到** AI 召回/引用了那条知识、或被迫问了那个问题。**能读到真实会话就必须真读**,别拿 git 仓/handoff/中间文档**反推冒充**——「决策恰好和某文档吻合」是**内容吻合、非真召回**(倒推),只能标 `[来源: 事后补录]` 并注明推断。命中尤其别只找「显式引用」:遍历关键决策逆向问「做这步必须先知道什么」得到**候选**,但**必须回会话确证**才标 `[来源: AI会话]`,否则标事后补录。带**可抽审锚点** `[来源: AI会话 · <会话id/行号>]` 更佳。
|
|
54
|
+
- **三格别拔高凑数**:命中 = 库里已有知识这次被召回用上(✗ 复用自己写的函数 / 跑某流程 ≠ 命中);缺口 = 知识库缺了某条被迫问人(✗ 正常方向决策 ≠ 缺口);新确认 = 值得沉淀的新知识/规则。**纯机制需求三格全「确认无」是正常诚实收口**,别找复用/决策/经验来凑。
|
|
55
|
+
- **知识格内只放** `- [hit]/[gap]/[new]` 条目 **或** `- 确认无: <理由>` 行,别塞注释/散文。理由**不可**是占位符(空 / 无 / N/A / TODO / TBD / 待定 / 待补…)。
|
|
56
|
+
|
|
57
|
+
## 产出后自检
|
|
58
|
+
1. 六节齐全(历时 / 产物清单 / 测试汇总 / 命中 / 缺口 / 新确认),H2 标题精确等于规范标题。
|
|
59
|
+
2. 三个知识格每格 ≥1 条 `[hit]/[gap]/[new]` **或**一条非占位「确认无」。
|
|
60
|
+
3. poor 的每条 `[hit]/[gap]/[new]` 带 `[来源: AI会话]` 或 `[来源: 事后补录]`(任一)。
|
|
61
|
+
4. frontmatter 五键齐(req_id / 簇 / mode / created / git_range),created / git_range 带引号包成字符串。
|
|
62
|
+
- **内容质量**(命中准不准 / 澄清真不真 / 历时估得合不合理):**非机械可验**,交人工 review 或 LLM-judge。**禁止往档案塞关键字假装验证过内容**——校验查的是结构与非占位,不是内容对。
|
|
@@ -167,6 +167,55 @@ code {
|
|
|
167
167
|
}
|
|
168
168
|
.highlight p:last-child { margin-bottom: 0; }
|
|
169
169
|
|
|
170
|
+
/* Tabs */
|
|
171
|
+
.tabs-bar {
|
|
172
|
+
display: flex;
|
|
173
|
+
gap: 0;
|
|
174
|
+
border-bottom: 2px solid var(--color-border);
|
|
175
|
+
margin-bottom: 20px;
|
|
176
|
+
flex-wrap: wrap;
|
|
177
|
+
}
|
|
178
|
+
.tab-btn {
|
|
179
|
+
padding: 10px 18px;
|
|
180
|
+
font-size: 14px;
|
|
181
|
+
font-weight: 500;
|
|
182
|
+
color: var(--color-text-tertiary);
|
|
183
|
+
background: none;
|
|
184
|
+
border: none;
|
|
185
|
+
border-bottom: 2px solid transparent;
|
|
186
|
+
margin-bottom: -2px;
|
|
187
|
+
cursor: pointer;
|
|
188
|
+
transition: color 0.15s, border-color 0.15s;
|
|
189
|
+
font-family: inherit;
|
|
190
|
+
}
|
|
191
|
+
.tab-btn:hover { color: var(--color-primary); }
|
|
192
|
+
.tab-btn.active {
|
|
193
|
+
color: var(--color-primary);
|
|
194
|
+
border-bottom-color: var(--color-primary);
|
|
195
|
+
font-weight: 600;
|
|
196
|
+
}
|
|
197
|
+
.tab-panel { display: none; }
|
|
198
|
+
.tab-panel.active { display: block; }
|
|
199
|
+
.tab-panel .phase-list code { font-size: 12.5px; }
|
|
200
|
+
.tab-panel .phase-list em {
|
|
201
|
+
color: var(--color-text-tertiary);
|
|
202
|
+
font-size: 13px;
|
|
203
|
+
font-style: normal;
|
|
204
|
+
}
|
|
205
|
+
.tab-panel .flow-diagram {
|
|
206
|
+
background: var(--color-bg-code);
|
|
207
|
+
border: 1px solid var(--color-border);
|
|
208
|
+
border-radius: var(--radius);
|
|
209
|
+
padding: 16px 20px;
|
|
210
|
+
font-family: "SF Mono", "Menlo", monospace;
|
|
211
|
+
font-size: 12.5px;
|
|
212
|
+
line-height: 1.7;
|
|
213
|
+
overflow-x: auto;
|
|
214
|
+
margin: 12px 0 0;
|
|
215
|
+
white-space: pre;
|
|
216
|
+
color: var(--color-text-secondary);
|
|
217
|
+
}
|
|
218
|
+
|
|
170
219
|
/* Lists */
|
|
171
220
|
ul, ol {
|
|
172
221
|
padding-left: 24px;
|
|
@@ -269,102 +318,113 @@ footer p { margin: 0; }
|
|
|
269
318
|
<h2>安装流程</h2>
|
|
270
319
|
|
|
271
320
|
<div class="pipeline">
|
|
272
|
-
<
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
<div class="phase-label">机器级 · 每机器一次</div>
|
|
276
|
-
<ul class="phase-list">
|
|
277
|
-
<li><code>npm install -g cgraphx</code> 装 CLI<em>（Node ≥ 20 且 < 25）</em></li>
|
|
278
|
-
</ul>
|
|
279
|
-
</div>
|
|
321
|
+
<ul class="phase-list">
|
|
322
|
+
<li><code>npm install -g cgraphx</code> 装 CLI<em>（Node ≥ 20 且 < 25）</em></li>
|
|
323
|
+
</ul>
|
|
280
324
|
|
|
281
325
|
<div class="phase">
|
|
282
326
|
<div class="phase-label">项目级 · 每项目一次</div>
|
|
283
327
|
<ul class="phase-list">
|
|
284
|
-
<li
|
|
285
|
-
<li
|
|
286
|
-
<li
|
|
328
|
+
<li>项目目录内执行 <code>cgraphx init</code> 建 <code>.cgraphx/</code> 代码图谱索引和配置文件</li>
|
|
329
|
+
<li>项目目录内执行 <code>cgraphx install</code> 写 MCP 配置 + 部署 skills 模板到项目 <code>.claude/</code></li>
|
|
330
|
+
<li>一定要先 <code>cgraphx init</code>,<code>cgraphx init</code> 执行的同时可以执行 <code>cgraphx install</code></li>
|
|
287
331
|
</ul>
|
|
288
332
|
</div>
|
|
289
333
|
|
|
290
334
|
<div class="phase">
|
|
291
335
|
<div class="phase-label">卸载 · 可选</div>
|
|
292
336
|
<ul class="phase-list">
|
|
293
|
-
<li><code>npm uninstall -g cgraphx</code
|
|
337
|
+
<li><code>npm uninstall -g cgraphx</code></li>
|
|
294
338
|
<li>删项目目录下 <code>.cgraphx/</code> 清索引数据</li>
|
|
295
339
|
</ul>
|
|
296
340
|
</div>
|
|
297
341
|
</div>
|
|
298
|
-
|
|
299
|
-
<div class="highlight">
|
|
300
|
-
<p><strong>装一次,自动维护</strong>——全局装 CLI,每个项目跑 <code>init</code> + <code>install</code> 就接入完成;之后 watcher 自动同步代码图谱、MCP 配置自动注入,你不需要主动跑命令。卸载也是一条命令。</p>
|
|
301
|
-
</div>
|
|
302
342
|
</section>
|
|
303
343
|
|
|
304
344
|
<section>
|
|
305
345
|
<h2>使用流程</h2>
|
|
306
346
|
|
|
307
|
-
<div class="
|
|
308
|
-
<
|
|
347
|
+
<div class="tabs-bar">
|
|
348
|
+
<button class="tab-btn active" onclick="switchTab(this, 'tab-dev')">开发流程</button>
|
|
349
|
+
<button class="tab-btn" onclick="switchTab(this, 'tab-api-test')">接口测试流程</button>
|
|
350
|
+
<button class="tab-btn" onclick="switchTab(this, 'tab-unit-test')">单元测试流程</button>
|
|
351
|
+
<button class="tab-btn" onclick="switchTab(this, 'tab-knowledge')">知识库管理</button>
|
|
352
|
+
<button class="tab-btn" onclick="switchTab(this, 'tab-schema')">模型知识库管理</button>
|
|
353
|
+
</div>
|
|
309
354
|
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
</
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
<
|
|
321
|
-
<li><code>/write-prd</code> 写业务文档<em>（给业务方 / 领导确认）</em></li>
|
|
322
|
-
<li><code>/write-spec</code> 写技术规格<em>（归档业务行为 / 规则 / 接口 / 数据,作为 plan 的稳定输入）</em></li>
|
|
323
|
-
<li><code>/write-plan</code> 拆执行计划<em>（给 agent 执行）</em></li>
|
|
324
|
-
<li><code>/code-impact-markdown</code> 沉淀业务决策 / 概念到 <code>docs/knowledge/</code></li>
|
|
325
|
-
</ul>
|
|
355
|
+
<div id="tab-dev" class="tab-panel active">
|
|
356
|
+
<p style="color:var(--color-text-secondary);font-size:14px;margin:0 0 16px;">做需求的主线。</p>
|
|
357
|
+
<ul class="phase-list">
|
|
358
|
+
<li><strong style="color:var(--color-primary);">必经</strong> <code>/clarify-requirements</code> 澄清意图、业务边界、技术边界</li>
|
|
359
|
+
<li><span class="opt">可选</span> <code>/write-prd</code> 写业务文档<em>（给业务方 / 领导确认）</em></li>
|
|
360
|
+
<li><strong style="color:var(--color-primary);">核心</strong> <code>/write-spec</code> 写技术规格<em>（归档业务行为 / 规则 / 接口 / 数据）</em></li>
|
|
361
|
+
<li><span class="opt">可选</span> <code>/write-plan</code> 拆执行计划<em>（给 agent 执行）</em></li>
|
|
362
|
+
<li><strong style="color:var(--color-primary);">必经</strong> <code>/implementation</code> 实现<em>（简单任务）</em>或 <code>/subagent-implement</code><em>（复杂多任务）</em></li>
|
|
363
|
+
</ul>
|
|
364
|
+
<div class="highlight">
|
|
365
|
+
<p>日常默认 2 步:澄清 + 实现。复杂需求按需补 prd / spec / plan。cgraphx 在背后自动同步代码图谱,你不需要主动跑命令。</p>
|
|
326
366
|
</div>
|
|
367
|
+
</div>
|
|
327
368
|
|
|
328
|
-
|
|
329
|
-
|
|
330
|
-
|
|
331
|
-
|
|
332
|
-
|
|
333
|
-
|
|
334
|
-
|
|
335
|
-
|
|
369
|
+
<div id="tab-api-test" class="tab-panel">
|
|
370
|
+
<p style="color:var(--color-text-secondary);font-size:14px;margin:0 0 16px;"><strong>需求开发完成后</strong></p>
|
|
371
|
+
<ul class="phase-list">
|
|
372
|
+
<li><code>/write-api</code> 基于 spec 或已有代码生成 bruno 测试接口<em>（.bru + 测试规格 + 多环境配置）</em></li>
|
|
373
|
+
<li><code>/run-api-test</code> 跑接口测试 + 核实写接口 DB 副作用 + 出报告 <em>—— write-api 后执行;写接口必须查 DB 验数据</em></li>
|
|
374
|
+
</ul>
|
|
375
|
+
<div class="highlight">
|
|
376
|
+
<p>产物落在 <code>docs/bruno/</code>（接口定义）+ <code>docs/features/<前缀>/</code>（测试规格 + 报告）。两个 skill 顺序依赖,但 run-api-test 也可独立跑（针对已有 .bru）。</p>
|
|
336
377
|
</div>
|
|
378
|
+
</div>
|
|
337
379
|
|
|
338
|
-
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
|
|
342
|
-
|
|
343
|
-
|
|
344
|
-
|
|
380
|
+
<div id="tab-unit-test" class="tab-panel">
|
|
381
|
+
<p style="color:var(--color-text-secondary);font-size:14px;margin:0 0 16px;">和开发流程平行,共享 spec 作为输入,时序任意<em>（典型是代码先行、测试补充）</em>。</p>
|
|
382
|
+
<ul class="phase-list">
|
|
383
|
+
<li><code>/write-unit-test-spec</code> 基于 spec 产出单元测试规格文档<em>（零代码依赖,该测哪些路径/边界/异常）</em> <span class="opt">可选</span> <em>write-spec 后任意时机</em></li>
|
|
384
|
+
<li><code>/write-unit-test-code</code> 基于测试规格 + 已有实现,填实测试代码 + 跑测试 + 出报告 <em>—— 找不到测试规格则退出要求先跑 write-unit-test-spec</em></li>
|
|
385
|
+
</ul>
|
|
386
|
+
<div class="flow-diagram"> ┌──→ /write-plan → /implementation 开发流程 · 写代码
|
|
387
|
+
│
|
|
388
|
+
/clarify-requirements → /write-spec ──┤
|
|
389
|
+
│
|
|
390
|
+
└──→ /write-unit-test-spec → /write-unit-test-code 单元测试 · 写测试</div>
|
|
391
|
+
<div class="highlight">
|
|
392
|
+
<p>两条独立线路:开发流程写代码,单元测试流程写测试。产物落在 <code>docs/features/<前缀>/</code>（测试规格 + 报告）+ 项目测试目录（.test.ts）。</p>
|
|
345
393
|
</div>
|
|
394
|
+
</div>
|
|
346
395
|
|
|
347
|
-
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
|
|
351
|
-
|
|
352
|
-
|
|
353
|
-
</
|
|
396
|
+
<div id="tab-knowledge" class="tab-panel">
|
|
397
|
+
<p style="color:var(--color-text-secondary);font-size:14px;margin:0 0 16px;">沉淀业务决策、概念定义、历史教训到跨需求共享的知识库。</p>
|
|
398
|
+
<ul class="phase-list">
|
|
399
|
+
<li><code>/code-impact-markdown</code> 任何有价值的会话都可以触发沉淀 <em>—— 你只需要关注这一个指令</em></li>
|
|
400
|
+
<li><code>/code-impact-init</code> 新项目起步时批量探索 + 写知识库 <span class="opt">可选</span> <em>接手陌生项目时跑</em></li>
|
|
401
|
+
<li><code>knowledge-recall</code> 聊业务 / 不懂术语 / 对齐黑话时,派子 agent 召回相关概念 <em>—— agent 自动触发</em></li>
|
|
402
|
+
<li><code>code-impact-api</code> 已知概念名,精确查知识库 <em>—— agent 自动触发</em></li>
|
|
403
|
+
</ul>
|
|
404
|
+
<div class="highlight">
|
|
405
|
+
<p>产物落在 <code>docs/knowledge/*.md</code>。写文件前必须过 <code>cgraphx docs validate</code> 校验,非法文件会被索引跳过。</p>
|
|
354
406
|
</div>
|
|
407
|
+
</div>
|
|
355
408
|
|
|
356
|
-
|
|
357
|
-
|
|
358
|
-
|
|
359
|
-
|
|
360
|
-
|
|
361
|
-
|
|
409
|
+
<div id="tab-schema" class="tab-panel">
|
|
410
|
+
<p style="color:var(--color-text-secondary);font-size:14px;margin:0 0 16px;">数据库 schema 的 DDL 快照 + 探索补充,让 AI 理解表结构和业务语义。</p>
|
|
411
|
+
<ul class="phase-list">
|
|
412
|
+
<li><code>/export-table-ddl</code> 按 profile 批量导出项目用到的表的 CREATE TABLE DDL,按工程分目录 <em>—— 项目接入时跑一次,schema 变了重跑</em></li>
|
|
413
|
+
<li><code>db-query</code> 查数据时读本地 DDL 文件<em>（首选）</em>,文件不存在才连 DB 兜底;探索发现的隐式关系/含义/陷阱 append 到对应表的 DISCOVERED 块 <em>—— agent 自动触发</em></li>
|
|
414
|
+
</ul>
|
|
415
|
+
<div class="highlight">
|
|
416
|
+
<p>产物落在 <code>docs/schema-knowledge/<工程>/</code>（INDEX.md + ddl/<table>.sql + pending-comments.sql）。重 dump 时 DISCOVERED 块自动保留,积累不丢。</p>
|
|
362
417
|
</div>
|
|
363
418
|
</div>
|
|
364
419
|
|
|
365
|
-
<
|
|
366
|
-
|
|
367
|
-
|
|
420
|
+
<script>
|
|
421
|
+
function switchTab(btn, panelId) {
|
|
422
|
+
document.querySelectorAll('.tab-btn').forEach(b => b.classList.remove('active'));
|
|
423
|
+
document.querySelectorAll('.tab-panel').forEach(p => p.classList.remove('active'));
|
|
424
|
+
btn.classList.add('active');
|
|
425
|
+
document.getElementById(panelId).classList.add('active');
|
|
426
|
+
}
|
|
427
|
+
</script>
|
|
368
428
|
</section>
|
|
369
429
|
|
|
370
430
|
<section>
|
|
@@ -377,37 +437,45 @@ footer p { margin: 0; }
|
|
|
377
437
|
<span><span class="dot local"></span>本地测试相关</span>
|
|
378
438
|
</div>
|
|
379
439
|
|
|
380
|
-
<pre class="docs-tree"><b>docs/</b>
|
|
381
|
-
├── <b>bruno/</b>
|
|
382
|
-
│ ├── bruno.json
|
|
440
|
+
<pre class="docs-tree"><b>docs/</b> 文档工程 <span class="ann"># 必有</span>
|
|
441
|
+
├── <b>bruno/</b> API接口目录 <span class="ann"># write-api + run-api-test 维护; bruno app 可以直接打开这个目录识别为接口列表</span>
|
|
442
|
+
│ ├── bruno.json
|
|
383
443
|
│ ├── <b>environments/</b>
|
|
384
|
-
│ │ ├── local.bru
|
|
444
|
+
│ │ ├── local.bru
|
|
385
445
|
│ │ ├── staging.bru
|
|
386
446
|
│ │ └── production.bru
|
|
387
|
-
│ ├── <b>common/</b>
|
|
447
|
+
│ ├── <b>common/</b>
|
|
388
448
|
│ │ └── <接口名>/<场景>.bru
|
|
389
|
-
│ └── <b><服务名>/</b>
|
|
390
|
-
│ └── <b><需求前缀>/</b>
|
|
391
|
-
│ └── <b><接口名>/</b>
|
|
392
|
-
│ ├── <场景1>.bru
|
|
393
|
-
│ └── <场景2>.bru
|
|
449
|
+
│ └── <b><服务名>/</b>
|
|
450
|
+
│ └── <b><需求前缀>/</b>
|
|
451
|
+
│ └── <b><接口名>/</b>
|
|
452
|
+
│ ├── <场景1>.bru
|
|
453
|
+
│ └── <场景2>.bru
|
|
394
454
|
│
|
|
395
|
-
├── <b>features/</b>
|
|
396
|
-
│ └── <b><前缀>/</b>
|
|
397
|
-
│ ├── <前缀>
|
|
398
|
-
│ ├── <前缀>
|
|
399
|
-
│ ├── <b>plan/</b>
|
|
400
|
-
│ ├── <前缀>
|
|
401
|
-
│ ├── <前缀>
|
|
402
|
-
│ ├── <前缀>
|
|
403
|
-
│
|
|
455
|
+
├── <b>features/</b> 需求目录
|
|
456
|
+
│ └── <b><日期>-<编号>-<前缀>/</b> <span class="ann"># 如 2026-07-03-CRM-req19230-号百商品详情查询接口</span>
|
|
457
|
+
│ ├── <前缀>-spec.md <span class="skill">/write-spec</span> <span class="must">必选</span> <span class="ann">clarify 后执行</span>
|
|
458
|
+
│ ├── <前缀>-需求文档.md <span class="skill">/write-prd</span> <span class="opt">可选</span> <span class="ann">需要需求文档时,spec 之后</span>
|
|
459
|
+
│ ├── <b>plan/</b> <span class="skill">/write-plan</span> <span class="opt">可选</span> <span class="ann">大需求,spec/prd 后</span>
|
|
460
|
+
│ ├── <前缀>-单元测试-spec.md <span class="skill">/write-unit-test-spec</span> <span class="opt">可选</span> <span class="ann">spec 后任意时机</span>
|
|
461
|
+
│ ├── <前缀>-单元测试报告.md <span class="skill">/write-unit-test-code</span> <span class="opt">可选</span> <span class="ann">spec+开发完成后</span>
|
|
462
|
+
│ ├── <前缀>-api-spec.md <span class="skill">/write-api</span> <span class="opt">可选</span> <span class="ann">接口测试,开发完成后</span>
|
|
463
|
+
│ ├── <前缀>-测试报告.md <span class="skill">/run-api-test</span> <span class="opt">可选</span> <span class="ann">write-api 后自动产出</span>
|
|
464
|
+
│ ├── <前缀>-测试验证.jsonl <span class="skill">/run-api-test</span> <span class="opt">可选</span> <span class="ann">自动产出</span>
|
|
465
|
+
│ └── <前缀>-设计文档.md <span class="skill">/code-impact-docgen</span> <span class="opt">可选</span> <span class="ann">功能稳定后执行</span>
|
|
404
466
|
│
|
|
405
|
-
├── <b>knowledge/</b>
|
|
406
|
-
│
|
|
407
|
-
│ <span class="skill">/code-impact-markdown</span> <span class="ann">按需写</span>
|
|
467
|
+
├── <b>knowledge/</b> 知识库目录 <span class="skill">/code-impact-markdown</span> <span class="ann">任何有价值的会话都可以触发沉淀;</span>
|
|
468
|
+
│ <span class="skill">/code-impact-init</span> <span class="ann">新项目起步可以批量写 [可选]</span>
|
|
408
469
|
│
|
|
409
|
-
|
|
410
|
-
|
|
470
|
+
├── <b>schema-knowledge/</b> 模型知识库目录 <span class="skill">/export-table-ddl</span> <span class="ann">批量初始化工程模型, 按工程分目录</span>
|
|
471
|
+
│ ├── xw-inst <span class="skill">/db-query</span> <span class="ann">自动读文件内的模型, 兜底连接数据库获取数据, 经验回写到对应的 ddl文件</span>
|
|
472
|
+
│ │ ├── INDEX.md <span class="ann"># 表名 + 表注释,agent 进目录第一件事读</span>
|
|
473
|
+
│ │ ├── pending-comments.sql <span class="ann"># DBA 待执行 COMMENT SQL(action 队列,执行一条删一条)</span>
|
|
474
|
+
│ │ └── ddl/
|
|
475
|
+
│ │ ├── <table>.sql <span class="ann"># 完整 DDL + 末尾 DISCOVERED 块(db-query 探索补充的隐式关系/含义/陷阱)</span>
|
|
476
|
+
│ │ └── <table>.sql
|
|
477
|
+
│ ├── xw-order <span class="ann"># 结构同 xw-inst</span>
|
|
478
|
+
│ └── xw-so <span class="ann"># 结构同 xw-inst</span>
|
|
411
479
|
</pre>
|
|
412
480
|
|
|
413
481
|
<div class="highlight">
|
|
@@ -416,7 +484,7 @@ footer p { margin: 0; }
|
|
|
416
484
|
</section>
|
|
417
485
|
|
|
418
486
|
<footer>
|
|
419
|
-
<p>cgraphx 使用说明 · 2026-07-
|
|
487
|
+
<p>cgraphx 使用说明 · 2026-07-16</p>
|
|
420
488
|
</footer>
|
|
421
489
|
|
|
422
490
|
</div>
|
|
@@ -0,0 +1,149 @@
|
|
|
1
|
+
# cgraphx 怎么用
|
|
2
|
+
|
|
3
|
+
本地优先的代码智能 · 给 AI agent 用的代码图谱
|
|
4
|
+
|
|
5
|
+
最后更新:2026-07-16
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## 安装流程
|
|
10
|
+
|
|
11
|
+
- `npm install -g cgraphx` 装 CLI(Node ≥ 20 且 < 25)
|
|
12
|
+
|
|
13
|
+
### 项目级 · 每项目一次
|
|
14
|
+
|
|
15
|
+
- 项目目录内执行 `cgraphx init` 建 `.cgraphx/` 代码图谱索引和配置文件
|
|
16
|
+
- 项目目录内执行 `cgraphx install` 写 MCP 配置 + 部署 skills 模板到项目 `.claude/`
|
|
17
|
+
- 一定要先 `cgraphx init`, `cgraphx init` 执行的同时可以执行 `cgraphx install`
|
|
18
|
+
|
|
19
|
+
### 卸载 · 可选
|
|
20
|
+
|
|
21
|
+
- `npm uninstall -g cgraphx`
|
|
22
|
+
- 删项目目录下 `.cgraphx/` 清索引数据
|
|
23
|
+
|
|
24
|
+
---
|
|
25
|
+
|
|
26
|
+
## 使用流程
|
|
27
|
+
|
|
28
|
+
### 开发流程
|
|
29
|
+
|
|
30
|
+
做需求的主线。
|
|
31
|
+
|
|
32
|
+
- 必经 `/clarify-requirements` 澄清意图、业务边界、技术边界
|
|
33
|
+
- 可选 `/write-prd` 写业务文档(给业务方 / 领导确认)
|
|
34
|
+
- 核心 `/write-spec` 写技术规格(归档业务行为 / 规则 / 接口 / 数据)
|
|
35
|
+
- 可选 `/write-plan` 拆执行计划(给 agent 执行)
|
|
36
|
+
- 必经 `/implementation` 实现(简单任务)或 `/subagent-implement`(复杂多任务)
|
|
37
|
+
|
|
38
|
+
> 日常默认 2 步:澄清 + 实现。复杂需求按需补 prd / spec / plan。cgraphx 在背后自动同步代码图谱,你不需要主动跑命令。
|
|
39
|
+
|
|
40
|
+
---
|
|
41
|
+
|
|
42
|
+
### 接口测试流程
|
|
43
|
+
|
|
44
|
+
**需求开发完成后**
|
|
45
|
+
|
|
46
|
+
- `/write-api` 基于 spec 或已有代码生成 bruno 测试接口(.bru + 测试规格 + 多环境配置)
|
|
47
|
+
- `/run-api-test` 跑接口测试 + 核实写接口 DB 副作用 + 出报告 —— write-api 后执行;写接口必须查 DB 验数据
|
|
48
|
+
|
|
49
|
+
> 产物落在 `docs/bruno/`(接口定义)+ `docs/features/<前缀>/`(测试规格 + 报告)。两个 skill 顺序依赖,但 run-api-test 也可独立跑(针对已有 .bru)。
|
|
50
|
+
|
|
51
|
+
---
|
|
52
|
+
|
|
53
|
+
### 单元测试流程
|
|
54
|
+
|
|
55
|
+
和开发流程平行,共享 spec 作为输入,时序任意(典型是代码先行、测试补充)。
|
|
56
|
+
|
|
57
|
+
- `/write-unit-test-spec` 基于 spec 产出单元测试规格文档(零代码依赖,该测哪些路径/边界/异常)—— 可选,write-spec 后任意时机
|
|
58
|
+
- `/write-unit-test-code` 基于测试规格 + 已有实现,填实测试代码 + 跑测试 + 出报告 —— 找不到测试规格则退出要求先跑 write-unit-test-spec
|
|
59
|
+
|
|
60
|
+
```
|
|
61
|
+
┌──→ /write-plan → /implementation 开发流程 · 写代码
|
|
62
|
+
│
|
|
63
|
+
/clarify-requirements → /write-spec ──┤
|
|
64
|
+
│
|
|
65
|
+
└──→ /write-unit-test-spec → /write-unit-test-code 单元测试 · 写测试
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
> 两条独立线路:开发流程写代码,单元测试流程写测试。产物落在 `docs/features/<前缀>/`(测试规格 + 报告)+ 项目测试目录(.test.ts)。
|
|
69
|
+
|
|
70
|
+
---
|
|
71
|
+
|
|
72
|
+
### 知识库管理
|
|
73
|
+
|
|
74
|
+
沉淀业务决策、概念定义、历史教训到跨需求共享的知识库。
|
|
75
|
+
|
|
76
|
+
- `/code-impact-markdown` 任何有价值的会话都可以触发沉淀 —— 你只需要关注这一个指令
|
|
77
|
+
- `/code-impact-init` 新项目起步时批量探索 + 写知识库 —— 可选,接手陌生项目时跑
|
|
78
|
+
- `knowledge-recall` 聊业务 / 不懂术语 / 对齐黑话时,派子 agent 召回相关概念 —— agent 自动触发
|
|
79
|
+
- `code-impact-api` 已知概念名,精确查知识库 —— agent 自动触发
|
|
80
|
+
|
|
81
|
+
> 产物落在 `docs/knowledge/*.md`。写文件前必须过 `cgraphx docs validate` 校验,非法文件会被索引跳过。
|
|
82
|
+
|
|
83
|
+
---
|
|
84
|
+
|
|
85
|
+
### 模型知识库管理
|
|
86
|
+
|
|
87
|
+
数据库 schema 的 DDL 快照 + 探索补充,让 AI 理解表结构和业务语义。
|
|
88
|
+
|
|
89
|
+
- `/export-table-ddl` 按 profile 批量导出项目用到的表的 CREATE TABLE DDL,按工程分目录 —— 项目接入时跑一次,schema 变了重跑
|
|
90
|
+
- `db-query` 查数据时读本地 DDL 文件(首选),文件不存在才连 DB 兜底;探索发现的隐式关系/含义/陷阱 append 到对应表的 DISCOVERED 块 —— agent 自动触发
|
|
91
|
+
|
|
92
|
+
> 产物落在 `docs/schema-knowledge/<工程>/`(INDEX.md + ddl/<table>.sql + pending-comments.sql)。重 dump 时 DISCOVERED 块自动保留,积累不丢。
|
|
93
|
+
|
|
94
|
+
---
|
|
95
|
+
|
|
96
|
+
## docs/ 目录速查
|
|
97
|
+
|
|
98
|
+
翻文档时知道去哪儿找 —— 哪个目录由哪个 skill 自动维护。
|
|
99
|
+
|
|
100
|
+
**图例**:`必有` = 必有 | `可选` = 可选(按需) | `本地测试相关`
|
|
101
|
+
|
|
102
|
+
```
|
|
103
|
+
docs/ 文档工程 # 必有
|
|
104
|
+
├── bruno/ API接口目录 # write-api + run-api-test 维护; bruno app 可以直接打开这个目录识别为接口列表
|
|
105
|
+
│ ├── bruno.json
|
|
106
|
+
│ ├── environments/
|
|
107
|
+
│ │ ├── local.bru
|
|
108
|
+
│ │ ├── staging.bru
|
|
109
|
+
│ │ └── production.bru
|
|
110
|
+
│ ├── common/
|
|
111
|
+
│ │ └── <接口名>/<场景>.bru
|
|
112
|
+
│ └── <服务名>/
|
|
113
|
+
│ └── <需求前缀>/
|
|
114
|
+
│ └── <接口名>/
|
|
115
|
+
│ ├── <场景1>.bru
|
|
116
|
+
│ └── <场景2>.bru
|
|
117
|
+
│
|
|
118
|
+
├── features/ 需求目录
|
|
119
|
+
│ └── <日期>-<编号>-<前缀>/ # 如 2026-07-03-CRM-req19230-号百商品详情查询接口
|
|
120
|
+
│ ├── <前缀>-spec.md /write-spec 必选 clarify 后执行
|
|
121
|
+
│ ├── <前缀>-需求文档.md /write-prd 可选 需要需求文档时,spec 之后
|
|
122
|
+
│ ├── plan/ /write-plan 可选 大需求,spec/prd 后
|
|
123
|
+
│ ├── <前缀>-单元测试-spec.md /write-unit-test-spec 可选 spec 后任意时机
|
|
124
|
+
│ ├── <前缀>-单元测试报告.md /write-unit-test-code 可选 spec+开发完成后
|
|
125
|
+
│ ├── <前缀>-api-spec.md /write-api 可选 接口测试,开发完成后
|
|
126
|
+
│ ├── <前缀>-测试报告.md /run-api-test 可选 write-api 后自动产出
|
|
127
|
+
│ ├── <前缀>-测试验证.jsonl /run-api-test 可选 自动产出
|
|
128
|
+
│ └── <前缀>-设计文档.md /code-impact-docgen 可选 功能稳定后执行
|
|
129
|
+
│
|
|
130
|
+
├── knowledge/ 知识库目录 /code-impact-markdown 任何有价值的会话都可以触发沉淀;
|
|
131
|
+
│ /code-impact-init 新项目起步可以批量写 [可选]
|
|
132
|
+
│
|
|
133
|
+
|
|
134
|
+
├── schema-knowledge/ 模型知识库目录 /export-table-ddl 批量初始化工程模型, 按工程分目录
|
|
135
|
+
│ ├── xw-inst /db-query 自动读文件内的模型, 兜底连接数据库获取数据, 经验回写到对应的 ddl文件
|
|
136
|
+
│ │ ├── INDEX.md # 表名 + 表注释,agent 进目录第一件事读
|
|
137
|
+
│ │ ├── pending-comments.sql # DBA 待执行 COMMENT SQL(action 队列,执行一条删一条)
|
|
138
|
+
│ │ └── ddl/
|
|
139
|
+
│ │ ├── <table>.sql # 完整 DDL + 末尾 DISCOVERED 块(db-query 探索补充的隐式关系/含义/陷阱)
|
|
140
|
+
│ │ └── <table>.sql
|
|
141
|
+
│ ├── xw-order # 结构同 xw-inst
|
|
142
|
+
│ └── xw-so # 结构同 xw-inst
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
> **两个核心目录** —— `docs/features/` 是单次需求工作目录(必须有 spec.md),`docs/knowledge/` 是跨需求共享的业务知识库。**bruno/ 和 schema-knowledge/ 按需出现**,只在跑接口测试 / 查 DB 时产生。
|
|
146
|
+
|
|
147
|
+
---
|
|
148
|
+
|
|
149
|
+
cgraphx 使用说明 · 2026-07-16
|
|
@@ -31,38 +31,39 @@ description: 用户给一段话描述(模糊想法/领导式指令/产品想法/
|
|
|
31
31
|
|
|
32
32
|
## 流程
|
|
33
33
|
你必须为下列每一项创建一个任务,并按顺序完成:
|
|
34
|
-
1.
|
|
34
|
+
1. **知识库召回**
|
|
35
|
+
- 必须问用户是否需要 `knowledge-recall skill`, 用户确认后按 `knowledge-recall skill`流程,派出subagent探索知识库. 用于理解项目内行业俗语和黑话
|
|
36
|
+
|
|
37
|
+
2. **探索上下文**
|
|
35
38
|
- 按需读项目结构、文档、代码、测试、schema、路由、模型、API、UI、既有约定
|
|
36
39
|
- 项目里有这些工具可作为上下文补充, 对于符合的场景,必须使用:
|
|
37
|
-
- `code-impact-api skill` — 查 历史决策、业务概念、项目经验时必须使用
|
|
38
40
|
- `db-query skill` — 查数据库、查 DDL 时必须使用
|
|
39
41
|
- `codegraph_explore` MCP 工具 / `cgraphx query` / `cgraphx affected` CLI — 查代码调用关系、影响半径时必须使用
|
|
40
|
-
- `developer-timeline skill` — 查用户最近做了什么(回顾开发历史) 时必须使用
|
|
41
42
|
- 调用前明确告诉用户"我需要先查 X 来理解背景"。收集完简要陈述发现,不要大段贴原文
|
|
42
43
|
- 在假设任务形态之前,先识别当前行为和既有约束
|
|
43
44
|
|
|
44
|
-
|
|
45
|
+
3. **分类任务**
|
|
45
46
|
- 选一个主任务类型
|
|
46
47
|
- 只在严重影响澄清时加次任务类型
|
|
47
48
|
- 任务类型不清楚时,先问一个简短的分类问题再继续
|
|
48
49
|
|
|
49
|
-
|
|
50
|
+
4. **确认初步理解** ← 循环式复述的核心
|
|
50
51
|
- 复述你理解的意图
|
|
51
52
|
- 点出怀疑的目标、受影响的区域、初步范围
|
|
52
53
|
- 用结构化清单复述,然后明确问:"**这是你的意思吗?有什么要补充或纠正的?**"
|
|
53
54
|
- **铁律:用户明确说"没补充/没纠正/理解对了"之前,不进第 4 步。** 这一步的循环是整个 skill 的核心价值——agent 不知道用户脑中还有哪些观点没抛出来;理解偏差是后续所有返工的最大来源
|
|
54
55
|
|
|
55
|
-
|
|
56
|
+
5. **澄清业务边界**
|
|
56
57
|
- 确认业务目标、参与者、场景、包含范围、排除范围、数据归属、权限、异常、成功标准
|
|
57
58
|
- 对需要领导/业务方拍板的规则、口径、优先级、例外、验收标准明确标记为"业务决策"
|
|
58
59
|
|
|
59
|
-
|
|
60
|
+
6. **澄清技术方案边界**
|
|
60
61
|
- 确认受影响的层和主要技术选择,**不展开成完整设计 spec**
|
|
61
62
|
- **技术方案涉及既有代码改动时,做影响分析**——把 blast radius、直接调用方、受影响流程、风险等级(LOW/MEDIUM/HIGH/CRITICAL)报告给用户。HIGH/CRITICAL 风险必须先警告用户,再决定是否继续
|
|
62
63
|
- 当目标清楚但方案未定时,给 2-3 个可行方案 + 权衡 + 推荐方案;用户确认前不得把推荐方案写成已锁定技术方向
|
|
63
64
|
- 判断哪些技术决策必须在 spec/plan 前锁定,哪些可以留给后续实现做局部工程适配
|
|
64
65
|
|
|
65
|
-
|
|
66
|
+
7. **总结并停止**
|
|
66
67
|
- 输出简洁的澄清总结(见「最终输出」)
|
|
67
68
|
- 提一句可能的下一步(写 PRD/spec/plan/实现),作为用户控制的选择,不自动继续
|
|
68
69
|
- 总结指向"实现"时,**根据任务规模推荐 `/implementation` 或 `/subagent-implement`**(见「下游实现 skill 选择」)
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: code-impact-api
|
|
3
|
-
description: 项目文档知识库查询入口
|
|
3
|
+
description: 项目文档知识库查询入口 — 通过 cgraphx docs CLI 查询 docs/knowledge/ 下的业务决策、概念定义、历史教训。Use when 任务开始时 / 查业务概念 / 查历史决策 / 对齐术语 / 找相关文档 / 探索既有知识。
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
## 这个 skill 解决什么问题
|
|
@@ -123,6 +123,26 @@ description: 用户要求根据已确认的 plan、spec、任务清单、实现
|
|
|
123
123
|
- 如果存在 plan,最终能说明 `PLAN_FOLLOWED` / `PLAN_ADAPTED` / `PLAN_CONFLICT` 的状态。
|
|
124
124
|
- 最终回复清楚列出变更和验证结果。
|
|
125
125
|
|
|
126
|
+
## 知识沉淀提示(实现结束后)
|
|
127
|
+
|
|
128
|
+
汇报完变更和验证结果后,**主动评估本次会话是否产生了值得沉淀的知识**。不是每次都问 —— 只在本次实现中确实出现了下面任一情况时,提示用户:
|
|
129
|
+
|
|
130
|
+
- 踩了一个非显而易见的坑 / 陷阱(读代码看不出来,下次还会踩)
|
|
131
|
+
- 发现一个隐式约束或业务规则(代码里没写明,但影响实现)
|
|
132
|
+
- 做了一个有取舍的技术决策(存在替代方案,为什么选这个)
|
|
133
|
+
- 跨系统 / 跨文件的依赖关系,单看代码看不出来
|
|
134
|
+
- 历史背景 / 遗留约束解释了代码为什么是现在这样
|
|
135
|
+
|
|
136
|
+
满足时,在汇报末尾加一句:
|
|
137
|
+
|
|
138
|
+
```text
|
|
139
|
+
本次实现中 [简述发现],是否需要用 code-impact-markdown skill 沉淀到 docs/knowledge/?
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
用户同意 → 调 `code-impact-markdown` skill 走它的完整流程(查已有概念 → 写文件 → `docs validate` 校验 → 合并检查 → 询问扫描)。用户拒绝或没有值得沉淀的内容 → 不提,正常结束。
|
|
143
|
+
|
|
144
|
+
**不要自己造沉淀流程** —— 必须走 `code-impact-markdown` skill,它有 frontmatter 规范、校验、合并检查、命名规则。直接 Write 一个 .md 不校验不查重,等于往知识库灌坏文件。
|
|
145
|
+
|
|
126
146
|
## 遇到阻塞
|
|
127
147
|
|
|
128
148
|
遇到以下情况时暂停并向用户说明:
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: knowledge-recall
|
|
3
|
+
description: 从项目 markdown 知识库召回业务概念 — 当用户聊业务/遇到不懂的术语/需要对齐项目黑话/提到一个名词想确认项目里有没有沉淀过时,强制派子 agent 在隔离上下文里加载全量 concept 列表做语义匹配,主 agent 只拿命中的概念(名+文档路径+一行说明),不直接看到全量表。Use when 聊业务/不懂这个术语/这个词什么意思/对齐黑话/项目黑话/业务概念/行业术语/这个名词/沉淀过/之前记录过/有没有相关文档/这个业务词.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
## 这个 skill 解决什么
|
|
7
|
+
|
|
8
|
+
用户和 AI 聊业务时,AI 往往不会主动查项目已沉淀的概念,导致:用错行业黑话、重复问已记录过的问题、不知道有相关决策文档。本 skill 强制把"加载全量 concept + 匹配"这件事放进子 agent 的隔离上下文,主 agent 只收命中结果 —— 全量表(几十到几百个概念)不进主上下文,避免挤占决策空间。
|
|
9
|
+
|
|
10
|
+
## 流程
|
|
11
|
+
|
|
12
|
+
1. **Agent tool 调用**(专用子 agent,指令已内置在 agent 定义里):
|
|
13
|
+
```
|
|
14
|
+
Agent({
|
|
15
|
+
subagent_type: "knowledge-recall",
|
|
16
|
+
prompt: "当前任务: " + <用户原话或你的转述>
|
|
17
|
+
})
|
|
18
|
+
```
|
|
19
|
+
2. **直接采纳** 子 agent 返回的命中概念列表 —— 不要再自己调 `cgraphx docs concepts/find` 重新查(那是浪费,且会把全量表拉进主上下文)
|
|
20
|
+
3. 拿到命中概念后,主 agent 决定下一步:
|
|
21
|
+
- 概念够清晰,直接回答用户
|
|
22
|
+
- 需要细节 → `Read` 子 agent 返回的文档 path
|
|
23
|
+
- 需要精确查某个概念的其他文档 → 调 `code-impact-api` skill
|
|
24
|
+
- 子 agent 说"没有命中"→ 告诉用户项目里没沉淀这个概念,问要不要记录
|
|
@@ -0,0 +1,136 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: write-unit-test-code
|
|
3
|
+
description: 基于 write-unit-test-spec 产出的测试规格文档 + 已有实现代码,填实单元测试代码 + 跑测试 + 出报告。读测试规格派生场景 → 读实现代码定位被测目标(函数/类/模块)→ 产出 .test.ts(断言填实,能真跑)→ 跑测试 → 出 <前缀>-单元测试报告.md。被测代码缺失的场景用 it.skip + TODO 占位。依赖测试规格文档存在 —— 找不到时报错退出,要求先跑 /write-unit-test-spec。Use when 想填实测试代码 / 写单元测试 / 跑单元测试 / write-unit-test-code. 不写业务实现代码、不修实现 bug、不假装通过.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Write Unit Test Code
|
|
7
|
+
|
|
8
|
+
## 定位
|
|
9
|
+
|
|
10
|
+
**测试填实 + 验证 skill**:消费 `write-unit-test-spec` 产出的测试规格文档,基于已有实现代码填实测试代码,跑测试验证,出测试报告。
|
|
11
|
+
|
|
12
|
+
**和 write-unit-test-spec 的分工**:
|
|
13
|
+
- write-unit-test-spec:产**测试规格文档**(该测哪些场景,基于 spec,零代码依赖)
|
|
14
|
+
- 本 skill(write-unit-test-code):基于测试规格 + 已有实现,填实测试代码 + 跑 + 出报告
|
|
15
|
+
|
|
16
|
+
两个 skill 顺序依赖:本 skill 找不到测试规格文档时报错退出。
|
|
17
|
+
|
|
18
|
+
**和 implementation 的关系**:平行线路。implementation 写业务实现代码,本 skill 写测试代码。本 skill 假设被测代码已存在(典型场景:用户跑完 implementation 后回来补测试);代码缺失的场景用 `it.skip` + TODO 占位。
|
|
19
|
+
|
|
20
|
+
## HARD-GATE
|
|
21
|
+
|
|
22
|
+
- **不写业务实现代码** —— 本 skill 只写测试代码 + 测试报告,业务实现是 implementation 的事
|
|
23
|
+
- **依赖测试规格文档** —— 当前 feature 没有 `<前缀>-单元测试-spec.md` 时,报错退出:"找不到测试规格,请先跑 /write-unit-test-spec"。不自己现场派生测试场景(那是 write-unit-test-spec 的职责)
|
|
24
|
+
- **不编造被测目标** —— 测试里 import 的函数/类/模块必须**已存在**。不存在 → 对应场景用 `it.skip` + `// TODO: 实现提供后填实` 占位,不自己造签名
|
|
25
|
+
- **不修实现代码** —— 测试失败时如实报告,不替用户改业务代码
|
|
26
|
+
- **不假装通过** —— 测试断言不调到"假绿"。失败就是失败,如实标在报告里
|
|
27
|
+
|
|
28
|
+
## Trigger
|
|
29
|
+
|
|
30
|
+
**使用此 skill 当**:
|
|
31
|
+
- 用户跑完 `/write-unit-test-spec`,想填实测试代码
|
|
32
|
+
- 用户跑完 implementation,想基于测试规格补测试
|
|
33
|
+
- 用户明确说"填实测试 / 写单元测试代码 / 跑单元测试 / write-unit-test-code"
|
|
34
|
+
|
|
35
|
+
**不要使用此 skill 当**:
|
|
36
|
+
- 没有测试规格文档 —— 先跑 `/write-unit-test-spec`
|
|
37
|
+
- 想写业务实现 —— 用 `/implementation`
|
|
38
|
+
- 想产测试规格(不填实)—— 用 `/write-unit-test-spec`
|
|
39
|
+
- 纯文档 / 配置 / 无行为变更的需求 —— 无可测代码
|
|
40
|
+
|
|
41
|
+
## 流程
|
|
42
|
+
|
|
43
|
+
### 1. 前置检查
|
|
44
|
+
|
|
45
|
+
- 确认 `docs/features/<feature-id>/<前缀>-单元测试-spec.md` 存在。**不存在 → 报错退出**:"找不到测试规格,请先跑 /write-unit-test-spec"。不现场派生场景。
|
|
46
|
+
- 复用测试规格的 feature-id 和文件前缀,推导出测试文件路径和报告文件名。
|
|
47
|
+
|
|
48
|
+
### 2. 读测试规格文档
|
|
49
|
+
|
|
50
|
+
读 `<前缀>-单元测试-spec.md`,拿到:
|
|
51
|
+
- 必测场景清单(主路径 / 边界 / 异常,每条标 spec 依据)
|
|
52
|
+
- 测试骨架映射(测试文件该放哪、框架、命名)
|
|
53
|
+
|
|
54
|
+
### 3. 读已有实现代码
|
|
55
|
+
|
|
56
|
+
根据测试规格描述的被测目标,在代码库定位已有实现(用 `codegraph_explore` MCP / `cgraphx query` CLI / grep / Read):
|
|
57
|
+
- 读函数签名、参数、返回值、抛错行为、依赖关系
|
|
58
|
+
- 如果测试规格里的某个场景**代码里还没实现**:
|
|
59
|
+
- 对应测试用 `it.skip` + `// TODO: 实现提供后填实` 占位
|
|
60
|
+
- 记入"实现缺失场景清单",汇报时告诉用户"有 N 个场景因实现缺失跳过"
|
|
61
|
+
- **不自己造签名**
|
|
62
|
+
- 如果实现和 spec 不一致(测试规格基于 spec,但代码偏离了 spec):
|
|
63
|
+
- 在测试报告里标注"实现与 spec 偏差:X(spec 说 A,代码实际 B)"
|
|
64
|
+
- 测试按**代码实际行为**写(要能跑过)
|
|
65
|
+
- 偏差记录留给用户决定(改代码 / 改 spec / 接受现状)
|
|
66
|
+
|
|
67
|
+
### 4. 产出测试文件(断言填实)
|
|
68
|
+
|
|
69
|
+
写到 `<项目测试目录>/<feature-id>.test.ts`(或项目约定的命名/后缀,从测试规格的"骨架映射"节读取)。形态:
|
|
70
|
+
|
|
71
|
+
- 实现已就绪的场景 → `describe` + `it`(含真实断言,基于读到的签名写,能真跑)
|
|
72
|
+
- 实现缺失的场景 → `it.skip` + `// TODO: 实现提供后填实` 占位
|
|
73
|
+
- import 被目标(已存在的模块直接 import;不存在的标 TODO 注释,不强行 import)
|
|
74
|
+
- 框架(vitest/jest/...)和文件后缀按项目约定
|
|
75
|
+
- 已有同模块测试文件 → 文件名加后缀避免覆盖(如 `<feature-id>.补充.test.ts`),在报告里提示"已有 X,是否合并由用户判断"
|
|
76
|
+
|
|
77
|
+
**AI 自己发挥的空间**:fixture / mock 怎么组织、describe 嵌套多深、断言写多细,agent 按既有测试风格判断,不强加模板。
|
|
78
|
+
|
|
79
|
+
### 5. 跑测试验证 + 产出测试报告
|
|
80
|
+
|
|
81
|
+
跑一次项目的测试命令(如 `npm test`),确认新写的测试能跑(通过或失败都行,失败说明实现有 bug 或测试断言写错)。
|
|
82
|
+
|
|
83
|
+
**产出单元测试报告**,写到 `docs/features/<feature-id>/<前缀>-单元测试报告.md`。结构轻量,至少包含:
|
|
84
|
+
|
|
85
|
+
- 测试概况:总数 / 通过 / 失败 / 跳过(it.skip 占位)/ 时长
|
|
86
|
+
- 逐场景结果:每个 `it` 的通过/失败/跳过 + 失败原因(如有)
|
|
87
|
+
- 实现与 spec 偏差小结
|
|
88
|
+
- 待确认项汇总(实现缺失 / spec 不够细等)
|
|
89
|
+
- 下一步建议(失败 → 建议改实现 / 改测试 / 改 spec;跳过多 → 建议先补实现再回来跑)
|
|
90
|
+
|
|
91
|
+
**报告原则**:
|
|
92
|
+
- 通过 → 报告"测试已就绪,N 个场景覆盖"
|
|
93
|
+
- 失败 → 报告如实标失败 + 原因分类(测试写错 / 实现有 bug / spec 和实现偏差),**不修实现,不假装通过**
|
|
94
|
+
- 全部跳过(实现都没写)→ 报告标"无可跑测试,所有场景待实现",建议用户先跑 implementation
|
|
95
|
+
|
|
96
|
+
### 6. 汇报 + 不自动继续
|
|
97
|
+
|
|
98
|
+
告诉用户:
|
|
99
|
+
- 测试文件路径
|
|
100
|
+
- **单元测试报告路径** + 报告里的关键数字(通过/失败/跳过数)
|
|
101
|
+
- 实现与 spec 的偏差(如有)
|
|
102
|
+
- 待确认项(如有)
|
|
103
|
+
|
|
104
|
+
**不调用 implementation / write-unit-test-spec / run-api-test**,由用户决定下一步。
|
|
105
|
+
|
|
106
|
+
## 产物
|
|
107
|
+
|
|
108
|
+
| 产物 | 路径 | 形态 |
|
|
109
|
+
|---|---|---|
|
|
110
|
+
| 测试文件 | `<项目测试目录>/<feature-id>.test.ts` | describe + `it`(断言填实) / `it.skip`(实现待补) |
|
|
111
|
+
| 单元测试报告 | `docs/features/<feature-id>/<前缀>-单元测试报告.md` | 测试概况 + 逐场景结果 + 偏差小结 + 下一步建议 |
|
|
112
|
+
|
|
113
|
+
## 边界场景
|
|
114
|
+
|
|
115
|
+
- **找不到测试规格文档** → 报错退出,要求先跑 `/write-unit-test-spec`。不现场派生场景。
|
|
116
|
+
- **实现代码缺失** → 对应场景 `it.skip` + TODO 占位,汇报时告诉用户。不造签名。
|
|
117
|
+
- **已有同模块测试文件** → 文件名加后缀避免覆盖,报告里提示用户。不主动改既有测试。
|
|
118
|
+
- **跨语言项目** → 按测试规格文档里标注的语言约定产出。一次调用不产多语言测试。
|
|
119
|
+
- **实现与 spec 偏差** → 测试按代码实际行为写(要能跑过),偏差记录在报告里,汇报时提示用户。
|
|
120
|
+
- **纯文档/配置需求** → 检测到测试规格无可测场景 → 提示"规格里无可测场景,不建议继续"并退出。
|
|
121
|
+
|
|
122
|
+
## 不做的事
|
|
123
|
+
|
|
124
|
+
- 不写业务实现代码(那是 implementation 的事)
|
|
125
|
+
- 不现场派生测试场景(那是 write-unit-test-spec 的事,本 skill 找不到规格就退出)
|
|
126
|
+
- 不修实现代码(失败如实报告)
|
|
127
|
+
- 不假装通过(断言不调到假绿)
|
|
128
|
+
- 不引入硬 gate(precommit hook / 提交拦截)
|
|
129
|
+
- 不假设测试框架(从测试规格的骨架映射读,或运行时探测)
|
|
130
|
+
- 不改 write-unit-test-spec / implementation / write-plan(它们对本 skill 零依赖)
|
|
131
|
+
|
|
132
|
+
## 和其他 skill 的关系
|
|
133
|
+
|
|
134
|
+
- **write-unit-test-spec**:上游,提供测试规格文档。本 skill 找不到它就退出。
|
|
135
|
+
- **implementation**:平行线路,写业务实现。本 skill 读它的产物(代码),但不调它。
|
|
136
|
+
- **run-api-test**:不同类型的测试(接口测试 vs 单元测试),互不干涉。
|
|
@@ -0,0 +1,115 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: write-unit-test-spec
|
|
3
|
+
description: 基于 spec 产出单元测试规格文档(零代码依赖)。读 spec 派生必测路径/边界/异常/期望,产出 <前缀>-单元测试-spec.md,每条场景标 spec 依据。完全不碰业务实现代码 —— 只看测试基建(测试目录/框架/既有测试风格)。产物是独立的测试规格契约,供后续 write-unit-test-code 填实测试代码消费。即使代码一行没写也能产出。Use when 写完 spec 想要单元测试规格 / 测试设计 / 测试范围清单 / 测试场景 / write-unit-test-spec. 不写测试代码、不读实现代码、不跑测试.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Write Unit Test Spec
|
|
7
|
+
|
|
8
|
+
## 定位
|
|
9
|
+
|
|
10
|
+
**测试规格产出 skill**:基于 spec 派生"该测什么",产出独立的测试规格文档。完全不碰业务实现代码,只看项目的测试基建(测试目录、框架、既有测试风格)。
|
|
11
|
+
|
|
12
|
+
**和 write-unit-test-code 的分工**:
|
|
13
|
+
- 本 skill(write-unit-test-spec):产**测试规格文档**(该测哪些场景,基于 spec)
|
|
14
|
+
- write-unit-test-code:基于测试规格 + 已有实现代码,填实测试代码 + 跑测试 + 出报告
|
|
15
|
+
|
|
16
|
+
两个 skill 顺序依赖:先跑本 skill 拿规格,审完后跑 write-unit-test-code 填实。用户可以在中间叫停(只产规格,不填实)。
|
|
17
|
+
|
|
18
|
+
## HARD-GATE
|
|
19
|
+
|
|
20
|
+
- **不读业务实现代码** —— 本 skill 只读 spec 和测试基建(测试目录/框架/既有测试风格),不碰业务实现。测试规格是"该测什么",和代码怎么实现无关
|
|
21
|
+
- **不写测试代码** —— 本 skill 只产 markdown 规格文档,测试代码是 write-unit-test-code 的事
|
|
22
|
+
- **不编造测试场景** —— 每条必测场景必须能追溯到 spec 的某条验收口径,标 `依据: spec §X.Y`
|
|
23
|
+
- **不强制使用** —— 纯增量可选环节,不跑不影响原流程
|
|
24
|
+
- **依赖 spec** —— 当前 feature 没有 `<前缀>-spec.md` 时,提示"本 skill 依赖 spec,请先跑 write-spec"并退出
|
|
25
|
+
|
|
26
|
+
## Trigger
|
|
27
|
+
|
|
28
|
+
**使用此 skill 当**:
|
|
29
|
+
- 用户做完 spec,想要测试规格 / 测试设计 / 测试范围清单
|
|
30
|
+
- 用户想基于 spec 派生必测场景,审阅后再决定是否填实测试代码
|
|
31
|
+
- 用户明确说"写测试规格 / 测试场景 / 测试设计 / write-unit-test-spec"
|
|
32
|
+
|
|
33
|
+
**不要使用此 skill 当**:
|
|
34
|
+
- 没有 spec —— 先跑 `/write-spec`
|
|
35
|
+
- 想直接写测试代码 —— 用 `/write-unit-test-code`(但前提是已有测试规格)
|
|
36
|
+
- 想跑测试 —— 用 `/write-unit-test-code`(它收尾会跑)
|
|
37
|
+
- 纯文档 / 配置 / 无行为变更的需求 —— 无可测代码
|
|
38
|
+
|
|
39
|
+
## 流程
|
|
40
|
+
|
|
41
|
+
### 1. 前置检查
|
|
42
|
+
|
|
43
|
+
- 确认 `docs/features/<feature-id>/<前缀>-spec.md` 存在。不存在 → 提示并退出。
|
|
44
|
+
- 复用 spec 的 feature-id 和文件前缀,推导出本 skill 的产物文件名 `<前缀>-单元测试-spec.md`。
|
|
45
|
+
|
|
46
|
+
### 2. 识别项目测试基建(不读业务实现)
|
|
47
|
+
|
|
48
|
+
读项目的测试**基建**约定,决定测试代码未来放哪、用什么框架、什么命名。识别路径(按顺序尝试,任意一步识别到就停):
|
|
49
|
+
|
|
50
|
+
- 读 `package.json` 的 `test` script → 推断框架(vitest/jest/mocha)和测试命令
|
|
51
|
+
- 找既有测试目录:`__tests__/` / `test/` / `tests/` / `spec/`
|
|
52
|
+
- 读 1-2 个既有测试文件 → 推断命名风格、describe/it 用法、文件后缀(只看测试代码风格,不看被测代码)
|
|
53
|
+
- 非 JS 项目(python/go/rust)按该语言约定探测(pytest / go test / cargo test)
|
|
54
|
+
- 探测不到 → 问用户"测试文件放哪?用什么命名?"
|
|
55
|
+
|
|
56
|
+
识别结果作为测试规格文档里"测试骨架映射"节的依据(告诉 write-unit-test-code 未来测试文件该放哪)。
|
|
57
|
+
|
|
58
|
+
### 3. 读 spec 提取测试关注点(只读 spec)
|
|
59
|
+
|
|
60
|
+
从 `<前缀>-spec.md` 的以下章节派生必测路径:
|
|
61
|
+
- 验收标准与测试关注点
|
|
62
|
+
- 异常与边界场景
|
|
63
|
+
- 业务规则(每条规则通常对应至少一个测试)
|
|
64
|
+
- 系统行为(前置条件、触发、输出、失败行为)
|
|
65
|
+
|
|
66
|
+
把派生出的测试场景按"主路径 / 边界 / 异常"分组,每个场景标 spec 依据。
|
|
67
|
+
|
|
68
|
+
### 4. 产出测试规格文档
|
|
69
|
+
|
|
70
|
+
写到 `docs/features/<feature-id>/<前缀>-单元测试-spec.md`。结构轻量,至少包含:
|
|
71
|
+
|
|
72
|
+
- 测试范围(测什么、不测什么)
|
|
73
|
+
- 必测场景清单(按 主路径/边界/异常 分组,每条标 spec 依据)
|
|
74
|
+
- 测试骨架映射(未来测试文件路径 `<项目测试目录>/<feature-id>.test.ts` + 每个场景在骨架里的位置)
|
|
75
|
+
- 待确认项(spec 不够细时标【待确认】,提示用户回 write-spec 补)
|
|
76
|
+
|
|
77
|
+
**AI 自己发挥的空间**:具体章节怎么组织、必测场景写多细,agent 按 feature 复杂度判断。简单需求轻量写,复杂需求完整写。
|
|
78
|
+
|
|
79
|
+
### 5. 汇报 + 不自动继续
|
|
80
|
+
|
|
81
|
+
告诉用户:
|
|
82
|
+
- 测试规格文档路径
|
|
83
|
+
- 必测场景数(主路径 / 边界 / 异常 各几个)
|
|
84
|
+
- 待确认项(如有)
|
|
85
|
+
- 下一步建议:"审阅规格后,可跑 `/write-unit-test-code` 填实测试代码"
|
|
86
|
+
|
|
87
|
+
**不调用 write-unit-test-code / implementation / write-plan**,由用户决定。
|
|
88
|
+
|
|
89
|
+
## 产物
|
|
90
|
+
|
|
91
|
+
| 产物 | 路径 | 形态 |
|
|
92
|
+
|---|---|---|
|
|
93
|
+
| 测试规格文档 | `docs/features/<feature-id>/<前缀>-单元测试-spec.md` | 人读 markdown,每条必测场景标 spec 依据 + 测试骨架映射 |
|
|
94
|
+
|
|
95
|
+
## 边界场景
|
|
96
|
+
|
|
97
|
+
- **spec 不够细** → 测试规格里标【待确认】,提示用户回 write-spec 补,或本 skill 内问 3-5 个关键问题。不硬编造测试场景。
|
|
98
|
+
- **已有同模块测试规格文档** → 覆盖前提示用户"已有 <X>-单元测试-spec.md,是否覆盖",不静默覆盖。
|
|
99
|
+
- **跨语言项目** → 在规格里标注"本次规格按 <语言> 测试约定写",如果 spec 跨多语言,问用户主语言。
|
|
100
|
+
- **纯文档/配置需求** → 检测到 spec 无可测行为 → 提示"本需求无可测代码,不建议用本 skill"并退出。
|
|
101
|
+
|
|
102
|
+
## 不做的事
|
|
103
|
+
|
|
104
|
+
- 不读业务实现代码(只看测试基建)
|
|
105
|
+
- 不写测试代码(只产规格 markdown)
|
|
106
|
+
- 不跑测试
|
|
107
|
+
- 不填实断言
|
|
108
|
+
- 不改 spec / implementation / write-plan
|
|
109
|
+
- 不假设测试框架(运行时探测)
|
|
110
|
+
|
|
111
|
+
## 和其他 skill 的关系
|
|
112
|
+
|
|
113
|
+
- **write-spec**:上游,提供输入。
|
|
114
|
+
- **write-unit-test-code**:下游,消费本 skill 的测试规格文档,填实测试代码 + 跑测试 + 出报告。
|
|
115
|
+
- **implementation**:平行线路,写业务实现代码。本 skill 不依赖它(规格可早于实现产出)。
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "cgraphx",
|
|
3
|
-
"version": "1.4.
|
|
3
|
+
"version": "1.4.3",
|
|
4
4
|
"description": "Supercharge AI coding agents with semantic code intelligence — surgical context, fewer tool calls, faster answers. 100% local.",
|
|
5
5
|
"main": "dist/index.js",
|
|
6
6
|
"types": "dist/index.d.ts",
|