cgraphx 1.4.0 → 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-init/SKILL.md +3 -0
- package/dist/.claude-template/skills/code-impact-markdown/SKILL.md +13 -5
- package/dist/.claude-template/skills/db-query/SKILL.md +38 -11
- package/dist/.claude-template/skills/export-table-ddl/closed-loop.html +14 -4
- 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/dist/markdown/cli.d.ts.map +1 -1
- package/dist/markdown/cli.js +42 -0
- package/dist/markdown/cli.js.map +1 -1
- 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>
|