cgraphx 1.1.0 → 1.2.0

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.
Files changed (81) hide show
  1. package/README.md +0 -1
  2. package/dist/.claude-template/skills/cgraphx/SKILL.md +3 -3
  3. package/dist/.claude-template/skills/cgraphx/agent-prompt.md +1 -1
  4. package/dist/.claude-template/skills/cgraphx-guide/SKILL.md +94 -0
  5. package/dist/.claude-template/skills/cgraphx-guide/how-to-use.html +403 -0
  6. package/dist/.claude-template/skills/clarify-requirements/SKILL.md +19 -8
  7. package/dist/.claude-template/skills/code-impact-docgen/SKILL.md +186 -176
  8. package/dist/.claude-template/skills/code-impact-docgen/template-design-html.md +357 -0
  9. package/dist/.claude-template/skills/code-impact-docgen/template-design-md.md +164 -0
  10. package/dist/.claude-template/skills/code-impact-init/SKILL.md +47 -47
  11. package/dist/.claude-template/skills/developer-timeline/SKILL.md +9 -0
  12. package/dist/.claude-template/skills/write-api-doc/SKILL.md +317 -0
  13. package/dist/.claude-template/skills/write-api-doc/template-api-html.md +422 -0
  14. package/dist/.claude-template/skills/write-plan/SKILL.md +38 -16
  15. package/dist/.claude-template/skills/write-prd/SKILL.md +32 -8
  16. package/dist/.claude-template/skills/write-spec/SKILL.md +34 -9
  17. package/dist/bin/codegraph.js +0 -100
  18. package/dist/bin/codegraph.js.map +1 -1
  19. package/dist/resolution/index.d.ts.map +1 -1
  20. package/dist/resolution/index.js +13 -0
  21. package/dist/resolution/index.js.map +1 -1
  22. package/dist/resolution/scope-index.d.ts +86 -0
  23. package/dist/resolution/scope-index.d.ts.map +1 -0
  24. package/dist/resolution/scope-index.js +143 -0
  25. package/dist/resolution/scope-index.js.map +1 -0
  26. package/dist/resolution/stdlib-blocklist.d.ts +53 -0
  27. package/dist/resolution/stdlib-blocklist.d.ts.map +1 -0
  28. package/dist/resolution/stdlib-blocklist.js +143 -0
  29. package/dist/resolution/stdlib-blocklist.js.map +1 -0
  30. package/dist/search/ast-helpers.d.ts +42 -0
  31. package/dist/search/ast-helpers.d.ts.map +1 -0
  32. package/dist/search/ast-helpers.js +106 -0
  33. package/dist/search/ast-helpers.js.map +1 -0
  34. package/dist/search/call-sites.d.ts +398 -0
  35. package/dist/search/call-sites.d.ts.map +1 -0
  36. package/dist/search/call-sites.js +1433 -0
  37. package/dist/search/call-sites.js.map +1 -0
  38. package/dist/search/context.d.ts +134 -0
  39. package/dist/search/context.d.ts.map +1 -0
  40. package/dist/search/context.js +575 -0
  41. package/dist/search/context.js.map +1 -0
  42. package/dist/search/impact.d.ts +139 -0
  43. package/dist/search/impact.d.ts.map +1 -0
  44. package/dist/search/impact.js +646 -0
  45. package/dist/search/impact.js.map +1 -0
  46. package/dist/search/related.d.ts +178 -0
  47. package/dist/search/related.d.ts.map +1 -0
  48. package/dist/search/related.js +667 -0
  49. package/dist/search/related.js.map +1 -0
  50. package/dist/search/slice.d.ts +148 -0
  51. package/dist/search/slice.d.ts.map +1 -0
  52. package/dist/search/slice.js +460 -0
  53. package/dist/search/slice.js.map +1 -0
  54. package/dist/search/snr-constants.d.ts +41 -0
  55. package/dist/search/snr-constants.d.ts.map +1 -0
  56. package/dist/search/snr-constants.js +44 -0
  57. package/dist/search/snr-constants.js.map +1 -0
  58. package/dist/search/types.d.ts +28 -0
  59. package/dist/search/types.d.ts.map +1 -0
  60. package/dist/search/types.js +12 -0
  61. package/dist/search/types.js.map +1 -0
  62. package/dist/timeline/cli.d.ts.map +1 -1
  63. package/dist/timeline/cli.js +22 -3
  64. package/dist/timeline/cli.js.map +1 -1
  65. package/dist/timeline/store.d.ts +5 -0
  66. package/dist/timeline/store.d.ts.map +1 -1
  67. package/dist/timeline/store.js +23 -3
  68. package/dist/timeline/store.js.map +1 -1
  69. package/package.json +1 -1
  70. package/scripts/agent-eval/block-cgraphx-and-gitnexus-cli-hook.sh +43 -0
  71. package/scripts/agent-eval/block-cgraphx-cli-hook.sh +32 -0
  72. package/scripts/agent-eval/block-cgraphx-cli-settings.json +16 -0
  73. package/scripts/agent-eval/cli-vs-mcp-3arm.sh +121 -0
  74. package/scripts/agent-eval/multi-tool-eval.sh +171 -0
  75. package/scripts/agent-eval/parse-cli-vs-mcp.mjs +232 -0
  76. package/scripts/agent-eval/parse-multi-tool.mjs +242 -0
  77. package/scripts/agent-eval/subagent-token-cost.py +188 -0
  78. package/dist/.claude-template/skills/code-impact-docgen/template-business-html.md +0 -242
  79. package/dist/.claude-template/skills/code-impact-docgen/template-business-md.md +0 -107
  80. package/dist/.claude-template/skills/code-impact-docgen/template-technical-html.md +0 -205
  81. package/dist/.claude-template/skills/code-impact-docgen/template-technical-md.md +0 -155
package/dist/.claude-template/skills/write-api-doc/template-api-html.md ADDED
@@ -0,0 +1,422 @@
1
+ # 接口文档 HTML 模板
2
+
3
+ 适用于 feature 接口开发完毕后,由 `write-api-doc` skill 从 spec + 代码反向提取生成。默认输出到 `docs/features/<feature-id>/<文件前缀>-接口文档.html`。
4
+
5
+ 复用 `template-design-html.md` 的 CSS 变量(`:root` 里的颜色 / 字体 / 间距变量)以保持视觉一致;额外增加 `.api-method`、`.endpoint`、`.endpoint-list`、`.error-table` 等接口文档专用样式。
6
+
7
+ ## 完整 HTML 结构
8
+
9
+ ```html
10
+ <!DOCTYPE html>
11
+ <html lang="zh-CN">
12
+ <head>
13
+ <meta charset="UTF-8">
14
+ <meta name="viewport" content="width=device-width, initial-scale=1.0">
15
+ <title>{feature 标题} — 接口文档</title>
16
+ <style>
17
+ :root {
18
+ --bg: #ffffff;
19
+ --surface: #f8f9fa;
20
+ --text: #1d1d1f;
21
+ --text-secondary: #6e6e73;
22
+ --accent: #0071e3;
23
+ --accent-light: #e8f0fe;
24
+ --border: #d2d2d7;
25
+ --code-bg: #f5f5f7;
26
+ --font-sans: -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif;
27
+ --font-mono: "SF Mono", "Fira Code", "Cascadia Code", "Source Code Pro", monospace;
28
+ --max-width: 900px;
29
+
30
+ /* HTTP 方法色 */
31
+ --method-get: #2ea44f;
32
+ --method-get-bg: #e6f4ea;
33
+ --method-post: #0071e3;
34
+ --method-post-bg: #e8f0fe;
35
+ --method-put: #b08800;
36
+ --method-put-bg: #fff8e1;
37
+ --method-patch: #8b41c9;
38
+ --method-patch-bg: #f5eafa;
39
+ --method-delete: #c0392b;
40
+ --method-delete-bg: #fdedec;
41
+ }
42
+
43
+ *, *::before, *::after { margin: 0; padding: 0; box-sizing: border-box; }
44
+
45
+ body {
46
+ font-family: var(--font-sans);
47
+ font-size: 15px;
48
+ line-height: 1.7;
49
+ color: var(--text);
50
+ background: var(--bg);
51
+ }
52
+
53
+ .container {
54
+ max-width: var(--max-width);
55
+ margin: 0 auto;
56
+ padding: 2rem 1.5rem;
57
+ }
58
+
59
+ h1 {
60
+ font-size: 1.8rem;
61
+ font-weight: 700;
62
+ letter-spacing: -0.02em;
63
+ margin-bottom: 0.5em;
64
+ padding-bottom: 0.5em;
65
+ border-bottom: 2px solid var(--border);
66
+ }
67
+
68
+ .meta {
69
+ color: var(--text-secondary);
70
+ font-size: 0.875rem;
71
+ margin-bottom: 2em;
72
+ }
73
+
74
+ h2 {
75
+ font-size: 1.4rem;
76
+ font-weight: 600;
77
+ margin-top: 2.5em;
78
+ margin-bottom: 0.75em;
79
+ padding-bottom: 0.3em;
80
+ border-bottom: 1px solid var(--border);
81
+ }
82
+
83
+ h3 {
84
+ font-size: 1.15rem;
85
+ font-weight: 600;
86
+ margin-top: 1.5em;
87
+ margin-bottom: 0.5em;
88
+ }
89
+
90
+ h4 {
91
+ font-size: 0.95rem;
92
+ font-weight: 600;
93
+ color: var(--text-secondary);
94
+ text-transform: uppercase;
95
+ letter-spacing: 0.05em;
96
+ margin-top: 1.5em;
97
+ margin-bottom: 0.5em;
98
+ }
99
+
100
+ p { margin-bottom: 1em; }
101
+
102
+ ul, ol {
103
+ margin-bottom: 1em;
104
+ padding-left: 1.5em;
105
+ }
106
+
107
+ li { margin-bottom: 0.3em; }
108
+
109
+ strong { font-weight: 600; }
110
+
111
+ code {
112
+ font-family: var(--font-mono);
113
+ background: var(--code-bg);
114
+ padding: 0.15em 0.4em;
115
+ border-radius: 4px;
116
+ font-size: 0.9em;
117
+ }
118
+
119
+ pre {
120
+ background: var(--code-bg);
121
+ border: 1px solid var(--border);
122
+ border-radius: 8px;
123
+ padding: 1em;
124
+ margin-bottom: 1em;
125
+ overflow-x: auto;
126
+ }
127
+
128
+ pre code {
129
+ background: none;
130
+ padding: 0;
131
+ font-size: 0.85em;
132
+ }
133
+
134
+ table {
135
+ width: 100%;
136
+ border-collapse: collapse;
137
+ margin-bottom: 1em;
138
+ font-size: 0.92em;
139
+ }
140
+
141
+ th, td {
142
+ padding: 0.55em 0.9em;
143
+ text-align: left;
144
+ border-bottom: 1px solid var(--border);
145
+ vertical-align: top;
146
+ }
147
+
148
+ thead th {
149
+ font-weight: 600;
150
+ color: var(--accent);
151
+ background: var(--surface);
152
+ }
153
+
154
+ tbody tr:nth-child(even) { background: var(--surface); }
155
+
156
+ .toc {
157
+ background: var(--surface);
158
+ border: 1px solid var(--border);
159
+ border-radius: 8px;
160
+ padding: 1em 1.5em;
161
+ margin-bottom: 2em;
162
+ }
163
+
164
+ .toc h3 {
165
+ margin-top: 0;
166
+ margin-bottom: 0.5em;
167
+ font-size: 1rem;
168
+ }
169
+
170
+ .toc ul { list-style: none; padding-left: 0; }
171
+ .toc li { margin-bottom: 0.25em; }
172
+ .toc a { color: var(--accent); text-decoration: none; }
173
+ .toc a:hover { text-decoration: underline; }
174
+ .toc ul ul { padding-left: 1.5em; margin-top: 0.25em; }
175
+
176
+ /* HTTP 方法标签 */
177
+ .api-method {
178
+ display: inline-block;
179
+ font-family: var(--font-mono);
180
+ font-weight: 700;
181
+ font-size: 0.75em;
182
+ letter-spacing: 0.05em;
183
+ padding: 0.2em 0.6em;
184
+ border-radius: 4px;
185
+ text-transform: uppercase;
186
+ vertical-align: middle;
187
+ }
188
+ .api-method.get { color: var(--method-get); background: var(--method-get-bg); }
189
+ .api-method.post { color: var(--method-post); background: var(--method-post-bg); }
190
+ .api-method.put { color: var(--method-put); background: var(--method-put-bg); }
191
+ .api-method.patch { color: var(--method-patch); background: var(--method-patch-bg); }
192
+ .api-method.delete { color: var(--method-delete); background: var(--method-delete-bg); }
193
+
194
+ /* 接口详情容器 */
195
+ .endpoint {
196
+ background: var(--surface);
197
+ border: 1px solid var(--border);
198
+ border-radius: 8px;
199
+ padding: 1.5em;
200
+ margin-bottom: 1.5em;
201
+ }
202
+
203
+ .endpoint h3 {
204
+ margin-top: 0;
205
+ display: flex;
206
+ align-items: center;
207
+ gap: 0.6em;
208
+ flex-wrap: wrap;
209
+ }
210
+
211
+ .endpoint h3 code {
212
+ font-size: 0.95em;
213
+ background: var(--code-bg);
214
+ padding: 0.2em 0.5em;
215
+ }
216
+
217
+ .endpoint-desc {
218
+ color: var(--text-secondary);
219
+ font-style: italic;
220
+ margin-bottom: 1em;
221
+ }
222
+
223
+ /* 接口清单表专用 */
224
+ .endpoint-list td:nth-child(1) { white-space: nowrap; width: 1%; }
225
+ .endpoint-list td:nth-child(2) { font-family: var(--font-mono); font-size: 0.9em; }
226
+
227
+ /* 错误码表专用 */
228
+ .error-table td:nth-child(1) {
229
+ font-family: var(--font-mono);
230
+ font-weight: 600;
231
+ color: var(--method-delete);
232
+ white-space: nowrap;
233
+ }
234
+
235
+ /* 待补充/待确认标记 */
236
+ .placeholder {
237
+ display: inline-block;
238
+ background: #fff3cd;
239
+ color: #856404;
240
+ padding: 0.1em 0.5em;
241
+ border-radius: 4px;
242
+ font-size: 0.85em;
243
+ font-style: italic;
244
+ }
245
+ .pending-review {
246
+ display: inline-block;
247
+ background: #f8d7da;
248
+ color: #721c24;
249
+ padding: 0.1em 0.5em;
250
+ border-radius: 4px;
251
+ font-size: 0.85em;
252
+ font-style: italic;
253
+ }
254
+
255
+ @media print {
256
+ body { font-size: 11pt; }
257
+ .container { max-width: 100%; padding: 0; }
258
+ .toc { break-after: page; }
259
+ h2, .endpoint { break-inside: avoid; }
260
+ }
261
+ </style>
262
+ </head>
263
+ <body>
264
+ <div class="container">
265
+ <h1>{feature 标题} — 接口文档</h1>
266
+ <p class="meta">feature-id: {feature-id} | 生成日期: YYYY-MM-DD | 接口总数: N | 范围: 本次 feature 新增</p>
267
+
268
+ <nav class="toc">
269
+ <h3>目录</h3>
270
+ <ul>
271
+ <li><a href="#概览">概览</a></li>
272
+ <li><a href="#接口清单">接口清单</a></li>
273
+ <li><a href="#接口详情">接口详情</a>
274
+ <ul>
275
+ <li><a href="#endpoint-1">GET /api/users/:id</a></li>
276
+ <li><a href="#endpoint-2">POST /api/users</a></li>
277
+ </ul>
278
+ </li>
279
+ </ul>
280
+ </nav>
281
+
282
+ <section id="概览">
283
+ <h2>概览</h2>
284
+ <p>本 feature 新增接口的业务背景,从 spec 摘录的一段简述。</p>
285
+ <table>
286
+ <tr><th>Base URL</th><td>/api/v1 <span class="placeholder">若不可推断填"待补充"</span></td></tr>
287
+ <tr><th>鉴权方式</th><td>Bearer Token <span class="placeholder">若不可推断填"待补充"</span></td></tr>
288
+ <tr><th>主要变化</th><td>新增了用户查询和创建接口</td></tr>
289
+ <tr><th>spec 来源</th><td>docs/features/&lt;feature-id&gt;/&lt;文件前缀&gt;-spec.md</td></tr>
290
+ </table>
291
+ </section>
292
+
293
+ <section id="接口清单">
294
+ <h2>接口清单</h2>
295
+ <table class="endpoint-list">
296
+ <thead>
297
+ <tr><th>方法</th><th>路径</th><th>简述</th></tr>
298
+ </thead>
299
+ <tbody>
300
+ <tr>
301
+ <td><span class="api-method get">GET</span></td>
302
+ <td>/api/users/:id</td>
303
+ <td>查询用户详情</td>
304
+ </tr>
305
+ <tr>
306
+ <td><span class="api-method post">POST</span></td>
307
+ <td>/api/users</td>
308
+ <td>创建新用户</td>
309
+ </tr>
310
+ </tbody>
311
+ </table>
312
+ </section>
313
+
314
+ <section id="接口详情">
315
+ <h2>接口详情</h2>
316
+
317
+ <section id="endpoint-1" class="endpoint">
318
+ <h3>
319
+ <span class="api-method get">GET</span>
320
+ <code>/api/users/:id</code>
321
+ </h3>
322
+ <p class="endpoint-desc">查询用户详情。返回指定 ID 的用户基础信息和关联角色。</p>
323
+
324
+ <h4>请求参数</h4>
325
+ <table>
326
+ <thead>
327
+ <tr><th>位置</th><th>参数</th><th>类型</th><th>必填</th><th>说明</th></tr>
328
+ </thead>
329
+ <tbody>
330
+ <tr><td>path</td><td>id</td><td>string</td><td>是</td><td>用户 ID</td></tr>
331
+ <tr><td>query</td><td>expand</td><td>string</td><td>否</td><td>展开关联字段,如 <code>expand=role,dept</code></td></tr>
332
+ <tr><td>header</td><td>Authorization</td><td>string</td><td>是</td><td>Bearer Token</td></tr>
333
+ </tbody>
334
+ </table>
335
+
336
+ <h4>响应示例</h4>
337
+ <pre><code>{
338
+ "id": "u_001",
339
+ "name": "张三",
340
+ "role": "admin",
341
+ "createdAt": "2026-07-04T10:00:00Z"
342
+ }</code></pre>
343
+
344
+ <h4>错误码</h4>
345
+ <table class="error-table">
346
+ <thead>
347
+ <tr><th>状态码</th><th>含义</th><th>触发场景</th></tr>
348
+ </thead>
349
+ <tbody>
350
+ <tr><td>401</td><td>未授权</td><td>token 无效或过期</td></tr>
351
+ <tr><td>404</td><td>用户不存在</td><td>id 无效或已删除</td></tr>
352
+ </tbody>
353
+ </table>
354
+ </section>
355
+
356
+ <section id="endpoint-2" class="endpoint">
357
+ <h3>
358
+ <span class="api-method post">POST</span>
359
+ <code>/api/users</code>
360
+ </h3>
361
+ <p class="endpoint-desc">创建新用户。需要管理员权限。</p>
362
+
363
+ <h4>请求参数</h4>
364
+ <table>
365
+ <thead>
366
+ <tr><th>位置</th><th>参数</th><th>类型</th><th>必填</th><th>说明</th></tr>
367
+ </thead>
368
+ <tbody>
369
+ <tr><td>body</td><td>name</td><td>string</td><td>是</td><td>用户名,1-32 字符</td></tr>
370
+ <tr><td>body</td><td>role</td><td>string</td><td>是</td><td>角色,<code>admin</code> / <code>member</code></td></tr>
371
+ <tr><td>header</td><td>Authorization</td><td>string</td><td>是</td><td>Bearer Token,需 admin 角色</td></tr>
372
+ </tbody>
373
+ </table>
374
+
375
+ <h4>响应示例</h4>
376
+ <pre><code>{
377
+ "id": "u_002",
378
+ "name": "李四",
379
+ "role": "member",
380
+ "createdAt": "2026-07-04T11:00:00Z"
381
+ }</code></pre>
382
+
383
+ <h4>错误码</h4>
384
+ <table class="error-table">
385
+ <thead>
386
+ <tr><th>状态码</th><th>含义</th><th>触发场景</th></tr>
387
+ </thead>
388
+ <tbody>
389
+ <tr><td>400</td><td>参数错误</td><td>name 为空 / role 不在枚举内</td></tr>
390
+ <tr><td>403</td><td>无权限</td><td>非 admin 角色调用</td></tr>
391
+ <tr><td>409</td><td>用户名冲突</td><td>name 已存在</td></tr>
392
+ </tbody>
393
+ </table>
394
+ </section>
395
+ </section>
396
+ </div>
397
+ </body>
398
+ </html>
399
+ ```
400
+
401
+ ## 章节内容指南
402
+
403
+ | 章节 | 主来源 | 改写方向 |
404
+ |------|--------|----------|
405
+ | 文档头 | feature-id 推断 | 自动填,接口总数在文档生成后写入 |
406
+ | 概览 | spec 目标与范围 + 接口边界 | 一段话写业务背景;Base URL / 鉴权从代码或 spec 推断,推断不出标"待补充" |
407
+ | 接口清单 | grep + Read 命中的新增路由 | 一行一个接口,方法标签着色 |
408
+ | 接口详情 — 业务说明 | spec 接口章节 + handler 代码 | 一句话写接口做什么,关联 spec 哪条业务规则 |
409
+ | 请求参数 | handler 签名 + DTO / 类型注解 + 路由模板 | 表格化:位置 / 参数 / 类型 / 必填 / 说明;提取不到标"待补充" |
410
+ | 响应示例 | handler return + 序列化 + 类型注解 | 写出典型成功响应 JSON 示例;复杂对象给 1-2 个字段即可,不堆全表 |
411
+ | 错误码 | handler 异常处理 + spec 异常章节 | 表格化:状态码 / 含义 / 触发场景;spec 声明优先,代码补充 |
412
+
413
+ ## 格式要点
414
+
415
+ - HTTP 方法用 `<span class="api-method {method-lowercase}">` 标签着色(GET 绿 / POST 蓝 / PUT 黄 / PATCH 紫 / DELETE 红)
416
+ - 接口详情用 `<section class="endpoint">` 容器,有底色和圆角边框,视觉上和清单表区分
417
+ - 路径用 `<code>` 包裹,字体等宽
418
+ - 待补充字段用 `<span class="placeholder">` 标黄;与 spec 冲突用 `<span class="pending-review">` 标红
419
+ - 错误码列用 `.error-table` 着色,状态码列等宽红色
420
+ - 响应示例代码块不标语言类型(JSON 视觉清爽即可)
421
+ - 表格行支持自动斑马纹,无需手写
422
+ - 移动端友好:`flex-wrap` 让方法标签 + 路径在窄屏自动换行
package/dist/.claude-template/skills/write-plan/SKILL.md CHANGED
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: write-plan
3
- description: 用户要求基于已确认的 spec、规格说明、技术边界、业务规则、代码上下文或当前上下文编写 plan/实现计划/开发计划/Agent 执行计划时使用。用于把规格契约拆成 coding agent 可执行且应忠实执行的任务清单、依赖图、风险控制、文件归档和验收步骤,默认产出 docs/features/{feature-id}/plan/ 下的 index.md、01-schema.md、02-backend.md、03-frontend.md、04-test.md 等按需文件。不写 PRD/spec、不直接改代码;信息不足时只补问影响计划正确性的关键问题,或将不确定内容标记为【待确认】。
3
+ description: 用户要求基于已确认的 spec、规格说明、技术边界、业务规则、代码上下文或当前上下文编写 plan/实现计划/开发计划/Agent 执行计划时使用。用于把规格契约拆成 coding agent 可执行且应忠实执行的任务清单、依赖图、风险控制、文件归档和验收步骤,默认产出 docs/features/{feature-id}/plan/ 下的 <文件前缀>-index.md、<文件前缀>-01-schema.md、<文件前缀>-02-backend.md、<文件前缀>-03-frontend.md、<文件前缀>-04-test.md 等按需文件(文件前缀算法见 SKILL 正文)。不写 PRD/spec、不直接改代码;信息不足时只补问影响计划正确性的关键问题,或将不确定内容标记为【待确认】。
4
4
  ---
5
5
 
6
6
  # 编写 Plan (Write Plan)
@@ -53,33 +53,55 @@ Plan 可以包含具体文件、模块、接口、表、测试命令和任务依
53
53
 
54
54
  `docs/features/<feature-id>/plan/`
55
55
 
56
- 目录下文件固定为以下候选,按需创建:
56
+ 目录下文件都加 `<文件前缀>-` 前缀(前缀算法见下一节),按需创建:
57
57
 
58
- - `index.md` — 总任务清单 + 全局依赖图,必须创建
59
- - `01-schema.md` — 建表/数据迁移任务,按需创建
60
- - `02-backend.md` — 业务逻辑/接口任务,按需创建
61
- - `03-frontend.md` — 前端任务,按需创建
62
- - `04-test.md` — 测试与验收任务,按需创建
58
+ - `<文件前缀>-index.md` — 总任务清单 + 全局依赖图,必须创建
59
+ - `<文件前缀>-01-schema.md` — 建表/数据迁移任务,按需创建
60
+ - `<文件前缀>-02-backend.md` — 业务逻辑/接口任务,按需创建
61
+ - `<文件前缀>-03-frontend.md` — 前端任务,按需创建
62
+ - `<文件前缀>-04-test.md` — 测试与验收任务,按需创建
63
63
 
64
64
  如果没有可写项目上下文,或用户明确只需要正文,则直接在回复中输出同等结构的 plan 内容。
65
65
 
66
- 不要创建空的按需文件。某类工作不存在时,在 `index.md` 中标记“不涉及”。
66
+ 不要创建空的按需文件。某类工作不存在时,在 `<文件前缀>-index.md` 中标记”不涉及”。
67
67
 
68
- ## feature-id 规则
68
+ ## feature-id 与文件前缀规则
69
69
 
70
- 格式:`YYYY-MM-DD-<short-slug>`。
70
+ **feature-id 格式**:`YYYY-MM-DD-[业务ID-]<标题>`
71
71
 
72
72
  1. 日期使用当前日期。
73
- 2. slug 从需求名称或业务目标中提炼,优先短、清晰、可识别。
74
- 3. slug 可使用中文业务短语或英文短语,用连字符分隔,不强行翻译。
75
- 4. 若当前上下文或用户已提供 feature-id,则复用。
76
- 5. 如果同一目录下已有 PRD、spec 或其他需求文档,优先复用同一个 feature-id。
77
- 6. 写入前检查 `docs/features/` 下是否重名;重名时追加简短后缀。
78
- 7. 默认创建 `docs/features/<feature-id>/plan/`。
73
+ 2. 业务ID 是**可选**段落(字母数字 + 连字符,如 `CRM-req19230`)。skill 启动时提示用户填写,允许留空。
74
+ 3. 标题段允许中文、英文或混合(例:`号百商品详情查询接口`、`features目录结构调整`)。**不得**对中文做英文 slug 转换。
75
+ 4. 业务ID 段与标题段用连字符连接,组成 `<业务ID>-<标题>`。
76
+ 5. 写入前检查 `docs/features/` 下是否重名;重名时追加简短后缀。
77
+ 6. 若当前上下文或用户已提供 feature-id,则复用。
78
+ 7. 如果同一目录下已有 PRD、spec 或其他需求文档,优先复用同一个 feature-id。
79
+
80
+ **文件前缀算法**:
81
+ - 有业务ID:文件前缀 = `<业务ID>-<标题>`(如 `CRM-req19230-号百商品详情查询接口`)
82
+ - 无业务ID:文件前缀 = `<标题>`(如 `features目录结构调整`)
83
+
84
+ **默认产物路径**:`docs/features/<feature-id>/plan/<文件前缀>-index.md` 等
85
+
86
+ 例:
87
+ - 有业务ID:`docs/features/2026-06-10-CRM-req19230-号百商品详情查询接口/plan/CRM-req19230-号百商品详情查询接口-index.md`
88
+ - 无业务ID:`docs/features/2026-07-03-features目录结构调整/plan/features目录结构调整-index.md`
89
+
90
+ **敏感字符拒绝**:文件名不得包含 `/`、`:`、`*`、`?`、`”`、`<`、`>`、`|`。用户提供时若含敏感字符,skill 必须要求用户重命名,不得自动替换字符。
91
+
92
+ **与旧目录共存**:skill 始终用新命名,不主动探测旧目录的 `index.md` / `01-schema.md` 等。旧 feature 目录里继续更新会出现旧命名和新命名并存,由用户自行处理。
79
93
 
80
94
  ## 工作流程
81
95
 
82
96
  通常按以下顺序处理,但允许根据项目上下文合并或跳过不必要步骤。不要把流程完整性置于计划可执行性之上。
97
+ 在写任何 plan 内容前,**必须**先与用户确认两件事:
98
+
99
+ 1. **业务 ID**:本次需求是否有对应的工单号 / 需求单号 / 项目代号?允许留空,但**留空也必须显式确认**(用户明确说"没有/留空"),不得默认跳过。
100
+ 2. **标题语言**:用中文 / 英文 / 中英混合?由用户选定,**禁止** Agent 因为"目录看起来更整齐"/"和现有 feature 命名一致"/"避免中文路径问题"等原因,擅自把中文需求转成英文 slug。
101
+
102
+ - 用户主动给过完整 feature-id 或文件名 → 直接复用,跳过本步。
103
+ - 用户用 `/write-plan` 触发但未给命名决策 → **第一步就问这两个问题**,问完再写。
104
+ - 不得"先写 plan 内容,命名最后再说"。命名决策必须在内容产出之前落定,否则会在文件名上反复返工。
83
105
 
84
106
  1. **读取输入和项目上下文**
85
107
  - 找到当前 feature-id、spec、PRD、现有 plan 或相关文档。
package/dist/.claude-template/skills/write-prd/SKILL.md CHANGED
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: write-prd
3
- description: 用户要求基于已确认的需求、业务边界、业务规则、流程说明、客户材料或当前上下文编写 PRD/业务需求文档时使用。用于产出给领导、客户、业务方审阅的业务需求文档,帮助能拍板的人确认业务决策、业务流程、范围、规则、权限、异常和验收口径是否符合预期。不写技术 spec、实现计划或代码;信息不足时只补问影响业务决策确认的关键问题,或将不确定内容标记为【待确认】。
3
+ description: 用户要求基于已确认的需求、业务边界、业务规则、流程说明、客户材料或当前上下文编写 PRD/业务需求文档/需求文档时使用。用于产出给领导、客户、业务方审阅的业务需求文档,帮助能拍板的人确认业务决策、业务流程、范围、规则、权限、异常和验收口径是否符合预期。不写技术 spec、实现计划或代码;信息不足时只补问影响业务决策确认的关键问题,或将不确定内容标记为【待确认】。
4
4
  ---
5
5
 
6
6
  # 编写 PRD (Write PRD)
@@ -62,6 +62,14 @@ description: 用户要求基于已确认的需求、业务边界、业务规则
62
62
  - 测试用例明细,除非作为客户可读验收口径
63
63
 
64
64
  ## 工作流程
65
+ 在写任何 prd 内容前,**必须**先与用户确认两件事:
66
+
67
+ 1. **业务 ID**:本次需求是否有对应的工单号 / 需求单号 / 项目代号?允许留空,但**留空也必须显式确认**(用户明确说"没有/留空"),不得默认跳过。
68
+ 2. **标题语言**:用中文 / 英文 / 中英混合?由用户选定,**禁止** Agent 因为"目录看起来更整齐"/"和现有 feature 命名一致"/"避免中文路径问题"等原因,擅自把中文需求转成英文 slug。
69
+
70
+ - 用户主动给过完整 feature-id 或文件名 → 直接复用,跳过本步。
71
+ - 用户用 `/write-prd` 触发但未给命名决策 → **第一步就问这两个问题**,问完再写。
72
+ - 不得"先写 prd 内容,命名最后再说"。命名决策必须在内容产出之前落定,否则会在文件名上反复返工。
65
73
 
66
74
  1. **检查上下文完整性**
67
75
  - 确认当前上下文是否已有明确需求范围。
@@ -132,20 +140,36 @@ description: 用户要求基于已确认的需求、业务边界、业务规则
132
140
 
133
141
  在可写项目上下文中,默认创建或更新:
134
142
 
135
- `docs/features/<feature-id>/prd.md`
143
+ `docs/features/<feature-id>/<文件前缀>-需求文档.md`
144
+
145
+ 文件前缀规则见下一节。
136
146
 
137
147
  如果没有可写项目上下文,或用户明确只需要正文,则直接在回复中输出 PRD 内容。
138
148
 
139
- ## feature-id 规则
149
+ ## feature-id 与文件前缀规则
140
150
 
141
- 格式:`YYYY-MM-DD-<short-slug>`。
151
+ **feature-id 格式**:`YYYY-MM-DD-[业务ID-]<标题>`
142
152
 
143
153
  1. 日期使用当前日期。
144
- 2. slug 从需求名称或业务目标中提炼,优先短、清晰、可识别。
145
- 3. slug 可使用中文业务短语或英文短语,用连字符分隔,不强行翻译。
146
- 4. 若当前上下文或用户已提供 feature-id,则复用。
154
+ 2. 业务ID 是**可选**段落(字母数字 + 连字符,如 `CRM-req19230`)。skill 启动时提示用户填写,允许留空。
155
+ 3. 标题段允许中文、英文或混合(例:`号百商品详情查询接口`、`features目录结构调整`)。**不得**对中文做英文 slug 转换。
156
+ 4. 业务ID 段与标题段用连字符连接,组成 `<业务ID>-<标题>`。
147
157
  5. 写入前检查 `docs/features/` 下是否重名;重名时追加简短后缀。
148
- 6. 默认创建 `docs/features/<feature-id>/prd.md`。
158
+ 6. 若当前上下文或用户已提供 feature-id,则复用。
159
+
160
+ **文件前缀算法**:
161
+ - 有业务ID:文件前缀 = `<业务ID>-<标题>`(如 `CRM-req19230-号百商品详情查询接口`)
162
+ - 无业务ID:文件前缀 = `<标题>`(如 `features目录结构调整`)
163
+
164
+ **默认产物路径**:`docs/features/<feature-id>/<文件前缀>-需求文档.md`
165
+
166
+ 例:
167
+ - 有业务ID:`docs/features/2026-06-10-CRM-req19230-号百商品详情查询接口/CRM-req19230-号百商品详情查询接口-需求文档.md`
168
+ - 无业务ID:`docs/features/2026-07-03-features目录结构调整/features目录结构调整-需求文档.md`
169
+
170
+ **敏感字符拒绝**:文件名不得包含 `/`、`:`、`*`、`?`、`"`、`<`、`>`、`|`。用户提供时若含敏感字符,skill 必须要求用户重命名,不得自动替换字符。
171
+
172
+ **与旧目录共存**:skill 始终用新命名,不主动探测旧目录的 `prd.md`。旧 feature 目录里继续更新会出现 `prd.md`(旧)和 `<文件前缀>-需求文档.md`(新)并存,由用户自行处理。
149
173
 
150
174
  ## 章节写法
151
175
 
package/dist/.claude-template/skills/write-spec/SKILL.md CHANGED
@@ -65,6 +65,15 @@ Spec 可以包含必要的技术边界和系统影响,但不要展开成任务
65
65
 
66
66
  ## 工作流程
67
67
 
68
+ 在写任何 spec 内容前,**必须**先与用户确认两件事:
69
+
70
+ 1. **业务 ID**:本次需求是否有对应的工单号 / 需求单号 / 项目代号?允许留空,但**留空也必须显式确认**(用户明确说"没有/留空"),不得默认跳过。
71
+ 2. **标题语言**:用中文 / 英文 / 中英混合?由用户选定,**禁止** Agent 因为"目录看起来更整齐"/"和现有 feature 命名一致"/"避免中文路径问题"等原因,擅自把中文需求转成英文 slug。
72
+
73
+ - 用户主动给过完整 feature-id 或文件名 → 直接复用,跳过本步。
74
+ - 用户用 `/write-spec` 触发但未给命名决策 → **第一步就问这两个问题**,问完再写。
75
+ - 不得"先写 spec 内容,命名最后再说"。命名决策必须在内容产出之前落定,否则会在文件名上反复返工。
76
+
68
77
  1. **检查上下文完整性**
69
78
  - 确认当前上下文是否已有明确需求、业务边界和技术边界。
70
79
  - 识别缺失的行为、规则、数据、接口、权限、异常、兼容性或验收信息。
@@ -232,21 +241,37 @@ Spec 可以包含必要的技术边界和系统影响,但不要展开成任务
232
241
 
233
242
  在可写项目上下文中,默认创建或更新:
234
243
 
235
- `docs/features/<feature-id>/spec.md`
244
+ `docs/features/<feature-id>/<文件前缀>-spec.md`
245
+
246
+ 文件前缀规则见下一节。
236
247
 
237
248
  如果没有可写项目上下文,或用户明确只需要正文,则直接在回复中输出 spec 内容。
238
249
 
239
- ## feature-id 规则
250
+ ## feature-id 与文件前缀规则
240
251
 
241
- 格式:`YYYY-MM-DD-<short-slug>`。
252
+ **feature-id 格式**:`YYYY-MM-DD-[业务ID-]<标题>`
242
253
 
243
254
  1. 日期使用当前日期。
244
- 2. slug 从需求名称或业务目标中提炼,优先短、清晰、可识别。
245
- 3. slug 可使用中文业务短语或英文短语,用连字符分隔,不强行翻译。
246
- 4. 若当前上下文或用户已提供 feature-id,则复用。
247
- 5. 如果同一目录下已有 PRD 或其他需求文档,优先复用同一个 feature-id。
248
- 6. 写入前检查 `docs/features/` 下是否重名;重名时追加简短后缀。
249
- 7. 默认创建 `docs/features/<feature-id>/spec.md`。
255
+ 2. 业务ID 是**可选**段落(字母数字 + 连字符,如 `CRM-req19230`)。skill 启动时提示用户填写,允许留空。
256
+ 3. 标题段允许中文、英文或混合(例:`号百商品详情查询接口`、`features目录结构调整`)。**不得**对中文做英文 slug 转换。
257
+ 4. 业务ID 段与标题段用连字符连接,组成 `<业务ID>-<标题>`。
258
+ 5. 写入前检查 `docs/features/` 下是否重名;重名时追加简短后缀。
259
+ 6. 若当前上下文或用户已提供 feature-id,则复用。
260
+ 7. 如果同一目录下已有 PRD 或其他需求文档,优先复用同一个 feature-id。
261
+
262
+ **文件前缀算法**:
263
+ - 有业务ID:文件前缀 = `<业务ID>-<标题>`(如 `CRM-req19230-号百商品详情查询接口`)
264
+ - 无业务ID:文件前缀 = `<标题>`(如 `features目录结构调整`)
265
+
266
+ **默认产物路径**:`docs/features/<feature-id>/<文件前缀>-spec.md`
267
+
268
+ 例:
269
+ - 有业务ID:`docs/features/2026-06-10-CRM-req19230-号百商品详情查询接口/CRM-req19230-号百商品详情查询接口-spec.md`
270
+ - 无业务ID:`docs/features/2026-07-03-features目录结构调整/features目录结构调整-spec.md`
271
+
272
+ **敏感字符拒绝**:文件名不得包含 `/`、`:`、`*`、`?`、`"`、`<`、`>`、`|`。用户提供时若含敏感字符,skill 必须要求用户重命名,不得自动替换字符。
273
+
274
+ **与旧目录共存**:skill 始终用新命名,不主动探测旧目录的 `spec.md`。旧 feature 目录里继续更新会出现 `spec.md`(旧)和 `<文件前缀>-spec.md`(新)并存,由用户自行处理。
250
275
 
251
276
  ## 写作原则
252
277