@ppdocs/mcp 3.2.26 → 3.2.28

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 (10) hide show
  1. package/dist/cli.js +77 -43
  2. package/dist/tools/flowchart.js +5 -2
  3. package/package.json +1 -1
  4. package/templates/commands/pp/diagnose.md +174 -82
  5. package/templates/commands/pp/discuss.md +4 -4
  6. package/templates/commands/pp/execute.md +151 -84
  7. package/templates/commands/pp/init.md +200 -123
  8. package/templates/commands/pp/protocol.md +181 -0
  9. package/templates/commands/pp/review.md +158 -55
  10. package/templates/commands/pp/sync.md +229 -178
package/templates/commands/pp/sync.md CHANGED
@@ -1,178 +1,229 @@
1
- **角色**: Knowledge Graph Synchronization Architect (KGSA) - 维护代码与知识图谱的绝对一致性
2
-
3
- ## 同步宪法
4
- | 原则 | 要求 |
5
- |:---|:---|
6
- | **代码即真理** | 代码与图谱冲突时以 Git 状态为准，强制覆写；禁止保留幽灵节点 |
7
- | **拓扑优先** | Types → Utils → Services → UI，底层未建不创建上层 |
8
- | **引用强约束** | relatedFiles 精确锚定物理路径；signature 为代码唯一标识符 |
9
- | **版本追踪** | 版本号以 0.1 起始，每次同步有变动必须更新版本号 (AI控制递增) |
10
- | **版本一致性** | 同步完成后更新 lastSyncAt，用于检测代码↔图谱是否同步 |
11
- | **标签完整性** | 每节点 ≥3 个分类标签，标签由AI管理 |
12
-
13
- ---
14
-
15
- ## 同步模式
16
- | 参数 | 行为 |
17
- |:---|:---|
18
- | `all` | 全量扫描 `src/**/*.{ts,tsx,py,go,rs}` |
19
- | `recent` | `git diff --name-only HEAD~N` 增量检测 |
20
- | `check` | 仅对比不执行 |
21
-
22
- ---
23
-
24
- ## 标准流程 (5步)
25
-
26
- ### Step 1: 变更检测
27
- ```
28
- task_create({ title:"KG同步", goals:["检测变更","更新节点","验证覆盖"], related_nodes:["root"] })
29
-
30
- recent模式: git diff --name-only HEAD~3
31
- all模式: Glob src/**/*.{ts,tsx}
32
-
33
- ⭐ kg_search([""]) 一次获取全部现有节点 (替代逐个search)
34
- ```
35
-
36
- **版本一致性检测** ⭐新增:
37
- ```
38
- 对每个有 relatedFiles 的节点:
39
- 1. 获取文件 mtime (通过 Bash stat 或 fs.statSync)
40
- 2. 对比节点的 lastSyncAt
41
- 3. mtime > lastSyncAt → 标记为 [OUTDATED] 需同步
42
- 4. lastSyncAt 不存在 → 标记为 [UNTRACKED] 从未同步
43
- ```
44
-
45
- **输出变更清单**:
46
- ```
47
- ├─ 🟢 [NEW] src/services/Payment.ts (待创建)
48
- ├─ 🟡 [MOD] src/utils/format.ts (待更新)
49
- ├─ 🟠 [OUTDATED] src/hooks/useAuth.ts (代码已改，图谱未同步)
50
- └─ 🔴 [DEL] src/legacy/old.ts (待废弃)
51
- ```
52
- 等待用户确认 `OK`
53
-
54
- ### Step 2: 依赖解析 + 拓扑排序
55
- 解析 import 语句 → 构建依赖树 → 拓扑排序确保底层先处理
56
-
57
- ### Step 2.5: 标签完整性预检 ⭐新增
58
- ```
59
- kg_list_tags() → 获取现有标签词库 (91个标签)
60
- 检查待处理节点:
61
- - 标签 < 3 → 自动补全建议
62
- - 使用现有标签词库保持一致性
63
- ```
64
-
65
- ### Step 3: 原子化执行
66
- 对每个文件:
67
- ```
68
- 1. 读取源码 → 提取 signature/imports/comments
69
- 2. 从 Step1 缓存查找现有节点 (无需再次kg_search)
70
- 3. 执行写入:
71
- - NEW: kg_create_node (全字段 + relatedFiles + ⚠️tags≥3)
72
- - MOD: kg_update_node (变动字段 + 追加 versions)
73
- - DEL: kg_update_node(status:"deprecated") 或 kg_delete_node
74
- 4. 每5个文件: task_add_log(progress, "已处理 N/M")
75
- 5. 遇到问题: task_add_log(issue, "xxx解析失败")
76
- 6. 找到方案: task_add_log(solution, "改用yyy方式")
77
- ```
78
-
79
- **版本追加规则** (MOD时自动执行):
80
- ```
81
- kg_update_node({
82
- nodeId: "xxx",
83
- description: "新描述",
84
- lastSyncAt: new Date().toISOString(), // ⭐ 更新同步时间戳
85
- versions: [...现有versions, {
86
- version: 上一版本 + 0.1, // ⭐ 0.1起始，AI控制递增
87
- date: "ISO时间",
88
- changes: "本次变更摘要"
89
- }]
90
- })
91
- ```
92
-
93
- **代码版本注释** (源码文件头部):
94
- ```typescript
95
- // @version 0.1
96
- // 或 JSDoc 格式
97
- /**
98
- * @version 0.1
99
- */
100
- ```
101
-
102
- **同步时间戳规则** ⭐新增:
103
- ```
104
- NEW: kg_create_node 后自动设置 lastSyncAt = now
105
- MOD: kg_update_node 时必须传 lastSyncAt = now
106
- OUTDATED: 仅更新 lastSyncAt (无需改 description/versions)
107
- ```
108
-
109
- ### Step 4: 关系校验 ⭐优化
110
- ```
111
- 1. kg_read_node(nodeId, depth=1) 批量校验上下游关系
112
- 2. kg_list_nodes({maxEdges:0}) 检查孤立节点
113
- 3. 检查断链 (dependencies 指向不存在的 signature)
114
- ```
115
-
116
- ### Step 5: 交付报告 ⭐增强
117
- ```
118
- 1. 统计覆盖率
119
- 2. kg_list_tags() 输出标签分布
120
- 3. task_complete({
121
- summary: "同步完成...",
122
- difficulties: ["遇到的困难"],
123
- solutions: ["采用的方案"],
124
- references: [{title:"参考", url:"..."}]
125
- })
126
- ```
127
-
128
- **交付报告**:
129
- ```markdown
130
- | 维度 | 数量 | 状态 |
131
- |:---|:---|:---|
132
- | 新增节点 | 3 | ✅ |
133
- | 更新节点 | 12 | ✅ |
134
- | 废弃节点 | 1 | ⚠️ |
135
- | 版本追加 | 8 | ✅ |
136
- | 标签补全 | 5 | ✅ |
137
- | 同步时间戳更新 | 15 | ✅ |
138
- | 版本一致率 | 100% | 🟢 |
139
- | 覆盖率 | 98.5% | 🟢 |
140
- | 标签总数 | 91 | 📊 |
141
-
142
- 建议: git add . && git commit -m "chore: sync kg"
143
- ```
144
-
145
- ---
146
-
147
- ## MCP 工具速查 ⭐新增
148
-
149
- | 工具 | 用途 | 示例 |
150
- |:---|:---|:---|
151
- | `kg_search([""])` | 获取全部节点 | 变更检测时一次拉取 |
152
- | `kg_list_tags` | 标签词库 | 保持标签一致性 |
153
- | `kg_read_node(id, depth=1)` | 含关系的详情 | 校验上下游 |
154
- | `kg_list_nodes({maxEdges:0})` | 孤立节点 | 发现断链 |
155
- | `kg_list_nodes` | 含summary列表 | 覆盖率报告 |
156
-
157
- ---
158
-
159
- ## 异常处理
160
- | 场景 | 反应 |
161
- |:---|:---|
162
- | git status 不干净 | 警告 + 询问是否强制继续 |
163
- | kg_search 返回多个同名节点 | 暂停，列出候选请求人工绑定 |
164
- | 文件解析失败 | task_add_log(issue) + 标记 Skipped，不中断队列 |
165
- | 标签不足3个 | 自动从词库补全，记录日志 |
166
-
167
- ---
168
-
169
- ## 字段映射
170
- | 代码实体 | 图谱字段 | 提取规则 |
171
- |:---|:---|:---|
172
- | import 语句 | dependencies | 解析AST，匹配现有 signature |
173
- | 文件路径 | relatedFiles | 相对项目根 (如 `src/utils/auth.ts`) |
174
- | export 函数/类 | signature | 标识符名 (如 `AuthService`) |
175
- | JSDoc/Comments | description | 优先注释，无则代码生成摘要 |
176
- | 功能分类 | tags | ≥3个，使用 kg_list_tags 词库 |
177
- | 同步时间 | lastSyncAt | 每次同步完成时设为当前 ISO 时间戳 |
178
- | `// @version 0.1` | versions[].version | 代码文件头注释，0.1起始 |
1
+ **角色**: Knowledge Graph Synchronization Architect — 维护代码与知识图谱的绝对一致性
2
+
3
+ ## 同步宪法
4
+
5
+ | 原则 | 要求 |
6
+ |:---|:---|
7
+ | **代码即真理** | 代码与图谱冲突时以 Git 状态为准, 强制覆写 |
8
+ | **层级感知** | 变更定位到具体子图层级, 逐层向上验证影响链 |
9
+ | **最小变更** | 只更新有差异的节点/文档, 不做无意义的全量覆写 |
10
+ | **创建即关联** | 新增节点必须 bind 源码 + 创建/关联文档, 无孤立资产 |
11
+
12
+ ---
13
+
14
+ ## 同步模式
15
+
16
+ 用户触发时选择模式 (或由 AI 根据上下文判断):
17
+
18
+ | 模式 | 触发 | 扫描范围 |
19
+ |:---|:---|:---|
20
+ | `recent` (默认) | `/pp:sync` 或 `/pp:sync recent` | `git diff --name-only HEAD~3` 近期变更文件 |
21
+ | `all` | `/pp:sync all` | `code_scan(force:true)` 全量重扫 |
22
+ | `check` | `/pp:sync check` | 仅对比, 输出差异报告, 不执行写入 |
23
+
24
+ ---
25
+
26
+ ## 标准流程
27
+
28
+ ### Phase 1: 变更检测
29
+
30
+ **1.1 获取图谱现状**
31
+ ```
32
+ kg_init() → 确保项目连接
33
+ kg_tree() → 文档全景
34
+ kg_flowchart(action:"list") → 所有流程图
35
+ kg_flowchart(action:"get") → 主图节点+连线
36
+ ```
37
+
38
+ **1.2 获取代码变更**
39
+ ```
40
+ recent 模式:
41
+ Bash: git diff --name-only HEAD~3 → 变更文件列表
42
+ Bash: git log --oneline -5 → 近期提交摘要
43
+ code_scan() → 增量更新索引
44
+
45
+ all 模式:
46
+ code_scan(force:true) → 全量重建索引
47
+ Glob: src/**/*.{ts,tsx,rs} → 全部源文件
48
+ ```
49
+
50
+ **1.3 逐文件交叉比对**
51
+ ```
52
+ 对每个变更文件 (或全量文件):
53
+ 1. code_context(filePath) → 该文件的符号/依赖/被引用
54
+ 2. kg_flowchart(action:"get", chartId:对应子图) → 图谱中该区域的节点
55
+ 3. 对比:
56
+ - 文件中有导出, 图谱无节点 → [NEW]
57
+ - 文件已修改, 图谱节点描述/连线过时 → [MOD]
58
+ - 图谱节点绑定的文件已删除/移动 → [DEL/DRIFT]
59
+ - 图谱与代码一致 → [OK]
60
+ ```
61
+
62
+ **输出变更清单** (等待用户确认):
63
+ ```
64
+ ├─ 🟢 [NEW] src/hooks/useTheme.ts → 需创建节点+文档
65
+ ├─ 🟡 [MOD] src-tauri/src/storage/graph_store.rs → 节点描述需更新
66
+ ├─ 🔴 [DEL] src/legacy/oldHelper.ts → 节点需废弃/删除
67
+ ├─ 🟠 [DRIFT] src/utils/format.ts → moved to src/utils/formatter.ts → 需 unbind+rebind
68
+ └─ ✅ [OK] src/hooks/useProjectData.ts → 无变化
69
+
70
+ 统计: NEW 2 | MOD 5 | DEL 1 | DRIFT 1 | OK 15
71
+ ```
72
+ → 用户确认 `OK` 后进入 Phase 2
73
+
74
+ ### Phase 2: 影响链分析
75
+
76
+ **2.1 定位子图层级**
77
+ ```
78
+ 对每个 [NEW]/[MOD] 文件:
79
+ 1. 确定它属于哪张子图 (通过目录映射或 bind 记录)
80
+ 2. code_impact(symbolName) → 该符号的爆炸半径
81
+ - L1 直接引用 = 必须检查
82
+ - L2 间接引用 = 建议检查
83
+ 3. 影响是否跨子图? → 标记需要检查的父图连线
84
+ ```
85
+
86
+ **2.2 拓扑排序**
87
+ ```
88
+ 按依赖关系排序变更:
89
+ 底层变更先处理 (types/store) → 上层后处理 (hooks/components)
90
+ 避免更新上层节点时底层依赖还未就绪
91
+ ```
92
+
93
+ ### Phase 3: 原子化执行
94
+
95
+ **3.1 处理 [NEW] — 新增节点**
96
+ ```
97
+ 1. 判断深度: 该文件是否需要独立子图?
98
+ - 导出 ≥5 个符号 → create_chart + batch_add
99
+ - 导出 <5 个符号 → 在父子图中添加节点
100
+
101
+ 2. 创建节点:
102
+ kg_flowchart(action:"batch_add", chartId:目标子图,
103
+ nodes:[{id:"n_xxx", label:"xxx", nodeType:"process", domain:"...", description:"..."}],
104
+ edges:[{from:"n_xxx", to:"n_依赖", edgeType:"call"}])
105
+
106
+ 3. 绑定源码:
107
+ kg_flowchart(action:"bind", nodeId:"n_xxx", files:["src/..."])
108
+
109
+ 4. 创建文档 (遵循5分类):
110
+ kg_doc(action:"create",
111
+ path:"/模块/前端/xxx",
112
+ summary:"一句话职责",
113
+ content:"## 职责\n...\n## 公开API\n...\n## 文件路径\n...",
114
+ bindTo:"n_xxx")
115
+ ```
116
+
117
+ **3.2 处理 [MOD] — 更新节点**
118
+ ```
119
+ 1. 读取现有节点:
120
+ kg_flowchart(action:"get_node", nodeId:"n_xxx", includeDoc:true)
121
+
122
+ 2. 对比差异, 更新变动部分:
123
+ kg_flowchart(action:"update_node", nodeId:"n_xxx",
124
+ description:"新的一句话描述",
125
+ docContent:"更新后的文档内容",
126
+ docSummary:"更新后的摘要")
127
+
128
+ 3. 追加版本记录:
129
+ kg_doc(action:"update", path:"/模块/.../xxx",
130
+ versions:[{version:当前+0.1, date:"ISO日期", changes:"变更摘要"}])
131
+
132
+ 4. 检查连线是否需要更新:
133
+ code_context(filePath) → 新的import列表
134
+ 对比图谱中现有连线 → 增删连线
135
+ ```
136
+
137
+ **3.3 处理 [DEL] — 废弃/删除**
138
+ ```
139
+ 选项A - 标记废弃 (推荐):
140
+ kg_flowchart(action:"update_node", nodeId:"n_xxx", description:"[DEPRECATED] 原描述")
141
+ kg_flowchart(action:"unbind", nodeId:"n_xxx", files:["已删文件"])
142
+
143
+ 选项B - 彻底删除:
144
+ kg_flowchart(action:"delete_node", nodeId:"n_xxx")
145
+ kg_doc(action:"delete", path:"/模块/.../xxx")
146
+ ```
147
+
148
+ **3.4 处理 [DRIFT] — 路径漂移**
149
+ ```
150
+ kg_flowchart(action:"unbind", nodeId:"n_xxx", files:["旧路径"])
151
+ kg_flowchart(action:"bind", nodeId:"n_xxx", files:["新路径"])
152
+ ```
153
+
154
+ **进度记录** (每处理5个文件):
155
+ ```
156
+ kg_task(action:"update", taskId:"当前任务", log_type:"progress",
157
+ content:"已处理 N/M | NEW:a MOD:b DEL:c")
158
+ ```
159
+
160
+ ### Phase 4: 层级验证
161
+
162
+ **4.1 子图内部验证**
163
+ ```
164
+ 对每个受影响的子图:
165
+ kg_flowchart(action:"orphans", chartId:"sub_xxx") → 该子图内孤立节点
166
+ kg_flowchart(action:"get", chartId:"sub_xxx") → 检查连线完整性
167
+ ```
168
+
169
+ **4.2 跨层验证**
170
+ ```
171
+ 如果变更影响了跨子图的连线:
172
+ kg_flowchart(action:"get_node", nodeId:父节点, expand:2)
173
+ → 验证父子图之间的连线是否仍然正确
174
+ ```
175
+
176
+ **4.3 全局健康检查**
177
+ ```
178
+ kg_flowchart(action:"orphans") → 全局孤立节点 (应为0)
179
+ kg_flowchart(action:"health") → 冷热分布
180
+ kg_tree() → 文档覆盖确认
181
+ ```
182
+
183
+ ### Phase 5: 交付报告
184
+
185
+ ```
186
+ | 维度 | 数量 | 状态 |
187
+ |:---|:---|:---|
188
+ | 新增节点 | N | ✅ |
189
+ | 更新节点 | M | ✅ |
190
+ | 废弃/删除 | K | ⚠️/✅ |
191
+ | 路径修复 | P | ✅ |
192
+ | 新增文档 | D | ✅ |
193
+ | 更新文档 | U | ✅ |
194
+ | 新增连线 | E | ✅ |
195
+ | 孤立节点 | 0 | 🟢 |
196
+ | 受影响子图 | S 张 | 🟢 |
197
+ ```
198
+
199
+ 如有任务:
200
+ ```
201
+ kg_task(action:"archive", taskId:"当前任务",
202
+ summary:"同步完成...",
203
+ difficulties:["遇到的问题"],
204
+ solutions:["解决方案"])
205
+ ```
206
+
207
+ ---
208
+
209
+ ## 目录→子图映射规则
210
+
211
+ | 源码目录 | 子图 | 父节点 |
212
+ |:---|:---|:---|
213
+ | src-tauri/src/storage/ | sub_storage | n_storage |
214
+ | src-tauri/src/models/ | sub_kg (内) | n_kg |
215
+ | src-tauri/src/server/ | sub_entry | n_entry |
216
+ | src-tauri/src/commands/ | sub_entry (内) | n_entry |
217
+ | mcp-server/src/tools/ | sub_mcp | n_mcp |
218
+ | src/components/ | sub_frontend | n_frontend |
219
+ | src/hooks/ | sub_frontend (内) | n_frontend |
220
+
221
+ ## 异常处理
222
+
223
+ | 场景 | 处理 |
224
+ |:---|:---|
225
+ | git 有未提交变更 | 警告 + 展示 diff, 询问是否继续 |
226
+ | 节点绑定的文件不存在 | 标记 [DRIFT], 搜索新位置, 建议 rebind |
227
+ | 同一符号映射多个节点 | 暂停, 列出候选, 请求用户选择 |
228
+ | code_scan 索引过旧 | 自动 code_scan() 增量更新后重试 |
229
+ | 子图嵌套变更 (新文件导出≥5) | 建议 create_chart 升级为子图 |