@ppdocs/mcp 2.6.8 → 2.6.10

package/README.md

@@ -109,10 +109,9 @@ npx @ppdocs/mcp init -p <projectId> -k <key> --codex
 | `kg_update_node` | 更新节点内容 |
 | `kg_delete_node` | 删除节点 |
 | `kg_lock_node` | 锁定节点 (AI 只能锁定，解锁需前端手动) |
-| `kg_list_nodes` | 列出所有节点 |
+| `kg_list_nodes` | 列出节点 (支持 status/edges 过滤，maxEdges=0 查孤立节点) |
 | `kg_search` | 关键词搜索 |
 | `kg_find_path` | 查找依赖路径 |
-| `kg_find_orphans` | 查找孤立节点 |
 | `kg_get_relations` | 获取节点关系 |
 
 ### 任务管理工具
@@ -175,6 +174,10 @@ npx @ppdocs/mcp init -p <projectId> -k <key> --codex
 
 ## 更新日志
 
+### v2.6.9
+- ✨ `kg_list_nodes` 支持 status/minEdges/maxEdges 过滤
+- 🗑️ 移除 `kg_find_orphans` (用 `kg_list_nodes(maxEdges: 0)` 替代)
+
 ### v2.5.0
 - ✨ 新增 CLI init 命令，自动安装工作流模板
 - ✨ 支持 Codex 模式 (--codex)

package/dist/storage/httpClient.d.ts

@@ -5,11 +5,16 @@
  * API URL 格式: http://localhost:20001/api/:projectId/:password/...
  */
 import type { NodeData, SearchResult, PathResult, BugfixRecord, Task, TaskSummary, TaskLogType, TaskExperience } from './types.js';
+export interface ListNodesFilter {
+    status?: 'incomplete' | 'complete' | 'fixing' | 'refactoring' | 'deprecated';
+    minEdges?: number;
+    maxEdges?: number;
+}
 export declare class PpdocsApiClient {
     private baseUrl;
     constructor(apiUrl: string);
     private request;
-    listNodes(): Promise<NodeData[]>;
+    listNodes(filter?: ListNodesFilter): Promise<NodeData[]>;
     getNode(nodeId: string): Promise<NodeData | null>;
     createNode(node: Partial<NodeData>): Promise<NodeData>;
     updateNode(nodeId: string, updates: Partial<NodeData>): Promise<NodeData | null>;
@@ -22,12 +27,6 @@ export declare class PpdocsApiClient {
     lockNode(nodeId: string, locked: boolean): Promise<NodeData | null>;
     searchNodes(keywords: string[], limit?: number): Promise<SearchResult[]>;
     findPath(startId: string, endId: string): Promise<PathResult | null>;
-    findOrphans(): Promise<Array<{
-        id: string;
-        title: string;
-        type: string;
-        status: string;
-    }>>;
     getRelations(nodeId: string): Promise<Array<{
         nodeId: string;
         title: string;
@@ -52,7 +51,7 @@ export declare class PpdocsApiClient {
     completeTask(taskId: string, experience: TaskExperience): Promise<Task | null>;
 }
 export declare function initClient(apiUrl: string): void;
-export declare function listNodes(_projectId: string): Promise<NodeData[]>;
+export declare function listNodes(_projectId: string, filter?: ListNodesFilter): Promise<NodeData[]>;
 export declare function getNode(_projectId: string, nodeId: string): Promise<NodeData | null>;
 export declare function createNode(_projectId: string, node: Partial<NodeData>): Promise<NodeData>;
 export declare function updateNode(_projectId: string, nodeId: string, updates: Partial<NodeData>): Promise<NodeData | null>;
@@ -65,12 +64,6 @@ export declare function deleteNode(_projectId: string, nodeId: string): Promise<
 export declare function lockNode(_projectId: string, nodeId: string, locked: boolean): Promise<NodeData | null>;
 export declare function searchNodes(_projectId: string, keywords: string[], limit?: number): Promise<SearchResult[]>;
 export declare function findPath(_projectId: string, startId: string, endId: string): Promise<PathResult | null>;
-export declare function findOrphans(_projectId: string): Promise<Array<{
-    id: string;
-    title: string;
-    type: string;
-    status: string;
-}>>;
 export declare function getRelations(_projectId: string, nodeId: string): Promise<Array<{
     nodeId: string;
     title: string;

package/dist/storage/httpClient.js

@@ -99,8 +99,34 @@ export class PpdocsApiClient {
         }
     }
     // ============ 节点操作 ============
-    async listNodes() {
-        return this.request('/nodes');
+    async listNodes(filter) {
+        const nodes = await this.request('/nodes');
+        if (!filter)
+            return nodes;
+        // 计算每个节点的连接数 (入边+出边)
+        const edgeCounts = new Map();
+        nodes.forEach(n => edgeCounts.set(n.id, 0));
+        nodes.forEach(n => {
+            (n.dependencies || []).forEach(dep => {
+                // 出边: 当前节点依赖别人
+                edgeCounts.set(n.id, (edgeCounts.get(n.id) || 0) + 1);
+                // 入边: 被依赖的节点 (按 signature 匹配)
+                const target = nodes.find(t => t.signature?.toLowerCase() === dep.name.toLowerCase());
+                if (target)
+                    edgeCounts.set(target.id, (edgeCounts.get(target.id) || 0) + 1);
+            });
+        });
+        // 过滤
+        return nodes.filter(n => {
+            if (filter.status && n.status !== filter.status)
+                return false;
+            const edges = edgeCounts.get(n.id) || 0;
+            if (filter.minEdges !== undefined && edges < filter.minEdges)
+                return false;
+            if (filter.maxEdges !== undefined && edges > filter.maxEdges)
+                return false;
+            return true;
+        });
     }
     async getNode(nodeId) {
         try {
@@ -228,9 +254,6 @@ export class PpdocsApiClient {
             return null;
         }
     }
-    async findOrphans() {
-        return this.request('/orphans');
-    }
     async getRelations(nodeId) {
         const result = await this.request(`/relations/${nodeId}`);
         // 转换字段名 (API 返回 type，前端期望 edgeType)
@@ -323,8 +346,8 @@ function getClient() {
     return client;
 }
 // 导出与 fileStorage 相同的函数签名
-export async function listNodes(_projectId) {
-    return getClient().listNodes();
+export async function listNodes(_projectId, filter) {
+    return getClient().listNodes(filter);
 }
 export async function getNode(_projectId, nodeId) {
     return getClient().getNode(nodeId);
@@ -350,9 +373,6 @@ export async function searchNodes(_projectId, keywords, limit) {
 export async function findPath(_projectId, startId, endId) {
     return getClient().findPath(startId, endId);
 }
-export async function findOrphans(_projectId) {
-    return getClient().findOrphans();
-}
 export async function getRelations(_projectId, nodeId) {
     return getClient().getRelations(nodeId);
 }

package/dist/tools/index.js

@@ -120,21 +120,20 @@ export function registerTools(server, projectId, _user) {
         };
         return wrap(projectId, JSON.stringify(output, null, 2));
     });
-    // 7. 列出所有节点
-    server.tool('kg_list_nodes', '列出项目全部节点概览', {}, async () => {
-        const nodes = await storage.listNodes(projectId);
+    // 7. 列出节点 (支持过滤)
+    server.tool('kg_list_nodes', '列出节点，支持按状态/连接数过滤。maxEdges=0 可查孤立节点', {
+        status: z.enum(['incomplete', 'complete', 'fixing', 'refactoring', 'deprecated']).optional().describe('状态过滤'),
+        minEdges: z.number().optional().describe('最小连接数(含)'),
+        maxEdges: z.number().optional().describe('最大连接数(含)，0=孤立节点')
+    }, async (args) => {
+        const filter = (args.status || args.minEdges !== undefined || args.maxEdges !== undefined)
+            ? { status: args.status, minEdges: args.minEdges, maxEdges: args.maxEdges }
+            : undefined;
+        const nodes = await storage.listNodes(projectId, filter);
         const output = nodes.map(n => ({ id: n.id, title: n.title, type: n.type, status: n.status, locked: n.locked }));
         return wrap(projectId, JSON.stringify(output, null, 2));
     });
-    // 8. 查找孤立节点
-    server.tool('kg_find_orphans', '查找无连线的孤立节点(用于清理)', {}, async () => {
-        const orphans = await storage.findOrphans(projectId);
-        if (orphans.length === 0) {
-            return wrap(projectId, '没有孤立节点');
-        }
-        return wrap(projectId, JSON.stringify(orphans, null, 2));
-    });
-    // 9. 查询节点关系网 (支持多层)
+    // 8. 查询节点关系网 (支持多层)
     server.tool('kg_get_relations', '获取节点的上下游关系(谁依赖它/它依赖谁)，支持多层查询', {
         nodeId: z.string().describe('节点ID'),
         depth: z.number().min(1).max(3).optional().describe('查询层数(默认1，最大3)')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ppdocs/mcp",
-  "version": "2.6.8",
+  "version": "2.6.10",
   "description": "ppdocs MCP Server - Knowledge Graph for Claude",
   "type": "module",
   "main": "dist/index.js",

package/templates/commands/pp/init.md

@@ -4,103 +4,148 @@ description: 初始化知识图谱：100%扫描代码库，为每个模块创建
 
 # /init 项目初始化
 
-执行 `task_create("项目初始化: [项目名]")` → 递归扫描全部代码文件 → 逐文件审查创建节点 → 每处理5个文件调用 `task_add_log(progress)` 同步进度 → 全部完成后 `task_complete` 输出统计报告
+执行 `task_create("项目初始化")` → 分阶段扫描 → 逐文件创建节点 → 完成后 `task_complete`
 
-## 扫描规则
+## Phase 1: 项目探测
 
-**100%覆盖**: 递归遍历项目所有目录，不遗漏任何代码文件
+**技术栈识别**: package.json→Node/React | Cargo.toml→Rust | go.mod→Go | requirements.txt→Python
+**架构分析**: 读取入口配置 → Glob扫描源码目录 → 按目录聚类 → 输出架构树
 
-**忽略目录**: node_modules, dist, build, .git, .next, .nuxt, target, __pycache__
-
-**忽略文件**: .env*, *.lock, *.log, *.min.js, *.map, 图片(png/jpg/svg/ico), 字体(ttf/woff)
-
-**扫描顺序**: ①入口(main/index/App/lib.rs) → ②配置(package.json/tsconfig/Cargo.toml) → ③核心目录按字母序
+```
+┌─ 推断架构 ────────────────────┐
+│ [intro] 项目根: {名称}        │
+│ ├─ [intro] {模块A}: {路径}    │
+│ ├─ [logic] {模块B}: {路径}    │
+│ └─ [data]  共享类型           │
+└───────────────────────────────┘
+回复 OK 继续
+```
 
-## 节点字段规范
+**忽略**: node_modules, dist, build, .git, .next, target, __pycache__, .env*, *.lock, *.log, *.min.js
 
-每个节点必须填写以下字段，不可遗漏：
+## Phase 2: 签名规则表
 
-| 字段 | 必填 | 说明 |
+| 识别模式 | type | signature | categories |
+|:---|:---|:---|:---|
+| pages/views/routes | logic | `Page:{名称}` | `[ui, page]` |
+| components | logic | `Comp:{名称}` | `[ui, component]` |
+| use*.ts (Hook) | logic | `{名称}()` | `[hook]` |
+| services/api | logic | `Svc:{名称}` | `[service, api]` |
+| store/storage | logic | `Store:{名称}` | `[storage]` |
+| utils/helpers | logic | `{函数名}()` | `[util, reusable]` |
+| types/interfaces | data | `Type:{名称}` | `[type]` |
+| config/*.json | intro | `Config:{名称}` | `[config]` |
+| *.rs (Rust) | logic | `{mod}::{fn}` | `[rust]` |
+| *.go (Go) | logic | `{pkg}.{Func}` | `[go]` |
+
+### categories 分类 (17种)
+`ui` `function` `class` `library` `reusable` `snippet` `data` `logic` `api` `config` `util` `service` `model` `constant` `type` `hook` `middleware`
+
+## Phase 3: 字段规范 (MUST 全部填写)
+
+| 字段 | 规则 | 示例 |
 |:---|:---|:---|
-| title | ✅ | 格式 `[模块]:[文件名] 中文描述`，如 `Auth:login 用户登录处理` |
-| type | ✅ | `logic`(函数/组件/流程) `data`(类型/接口/结构) `intro`(架构/概念/说明) |
-| status | ✅ | 初始化统一设为 `incomplete`，待用户确认后改 `complete` |
-| signature | ✅ | 用于依赖匹配的唯一标识：函数名/类名/组件名/模块路径 |
-| categories | ✅ | 从17种分类中选择: ui/function/class/library/reusable/snippet/data/logic/api/config/util/service/model/constant/type/hook/middleware |
-| description | ✅ | **必须包含Mermaid流程图+表格**，禁止纯文字，详见下方模板 |
-| dataInput | 函数必填 | `{type: "类型定义", description: "参数说明"}` |
-| dataOutput | 函数必填 | `{type: "返回类型", description: "返回值说明"}` |
-| dependencies | ✅ | 依赖的其他模块 `[{name: "目标signature", description: "依赖原因"}]`，无依赖填空数组 |
-| relatedFiles | ✅ | 关联的源文件路径数组，如 `["src/services/auth.ts"]` |
-
-## description 模板
-
-### logic节点 (函数/组件/Hook)
-```markdown
-```mermaid
-flowchart LR
-    A[入口/触发] --> B{条件判断}
-    B -->|成功| C[核心处理]
-    B -->|失败| D[错误处理]
-    C --> E[返回结果]
+| title | 中文描述 | `用户认证服务` |
+| type | logic/data/intro | `logic` |
+| status | 统一 `incomplete` | 待确认后改 complete |
+| signature | 按上方规则生成 | `useAuth()` |
+| categories | 分类数组 | `["hook", "auth"]` |
+| **relatedFiles** | **MUST: 源文件路径** | `["src/hooks/useAuth.ts"]` |
+| **dependencies** | **MUST: 解析 import** | `[{name: "xxx", description: "用途"}]` |
+| description | 见下方模板 | |
+
+### relatedFiles 提取规则 (MUST)
+```
+1. 当前文件路径 → relatedFiles[0]
+2. 该文件 import 的本地文件 → relatedFiles[1..n]
+3. NEVER 留空，至少包含当前文件
 ```
 
-| 接口 | 类型 | 说明 |
-|:---|:---|:---|
-| Input | `ParamType` | 参数描述 |
-| Output | `ReturnType` | 返回值描述 |
-
-**核心逻辑**: 一句话描述函数职责
+### dependencies 推断规则 (MUST)
 ```
+依赖 = "谁调用了谁"
+
+处理每个文件时:
+1. 解析 import/require 语句 → 提取本地模块
+2. 对每个 import:
+   │
+   ├─ 匹配方式1: 签名匹配
+   │   import { useAuth } → 匹配 signature="useAuth()"
+   │
+   ├─ 匹配方式2: 路径匹配
+   │   遍历已创建节点的 relatedFiles
+   │   若 import 路径 ∈ 某节点的 relatedFiles → 匹配
+   │
+   └─ 匹配成功 → dependencies.push({
+        name: 目标节点的 signature,
+        description: "用途"
+      })
+```
+
+### description 模板
 
-### data节点 (类型/接口/枚举)
+**logic 节点**:
 ```markdown
-```mermaid
-classDiagram
-    class TypeName {
-        +fieldType field1
-        +fieldType field2
-    }
-```
+## 职责
+一句话描述
 
-| 字段 | 类型 | 必填 | 说明 |
-|:---|:---|:---|:---|
-| field1 | string | ✅ | 字段用途 |
-| field2 | number | ❌ | 字段用途 |
+## 流程
+| 步骤 | 说明 |
+|:---|:---|
+| 1. 入口 | 接收参数 |
+| 2. 处理 | 核心逻辑 |
+| 3. 返回 | 输出结果 |
 ```
 
-### intro节点 (架构/模块说明)
+**data 节点**:
 ```markdown
-```mermaid
-flowchart TB
-    subgraph 模块名[模块职责]
-        A --> B --> C
-    end
+## 结构
+| 字段 | 类型 | 说明 |
+|:---|:---|:---|
+| id | string | 唯一标识 |
 ```
 
-**职责**: 模块核心功能描述
-**关键依赖**: 列出核心依赖模块
-```
+**intro 节点**:
+```markdown
+## 职责
+模块功能
 
-## 进度同步
+## 包含
+| 子模块 | 说明 |
+|:---|:---|
+| xxx | 功能 |
+```
 
-每处理5个文件或完成1个目录后，调用 `task_add_log("progress", "已处理: [文件列表], 创建节点: N个")`
+> 注: 输入输出类型通过 dependencies 关联到 data 节点表达
 
-## 完成输出
+## Phase 4: 执行扫描
 
-`task_complete` 时输出完整统计：
+**顺序** (底层优先): types → utils → services → hooks → components → pages
 
-```markdown
-| 统计项 | 数量 |
-|:---|:---|
-| 扫描文件 | N |
-| 创建节点 | N |
-| 依赖关系 | N |
+```
+扫描文件 → 按签名规则生成节点 → kg_create_node
+                                    │
+进度: 每5文件 task_add_log("progress", "已处理: [文件列表]")
+```
 
-| 目录 | 文件数 | 节点数 | 覆盖率 |
-|:---|:---|:---|:---|
-| src/components | 12 | 12 | 100% |
-| src/services | 8 | 8 | 100% |
+## Phase 5: 完成报告
 
-**待人工补充**: [列出复杂度高需要人工完善description的节点]
 ```
+┌─────────────────────────────────┐
+│ 初始化完成                       │
+│ 扫描文件: XX | 创建节点: XX      │
+│ 覆盖率: 100%                    │
+│ 待人工完善: [复杂节点列表]        │
+└─────────────────────────────────┘
+```
+
+执行 `task_complete` 归档任务
+
+## 约束
+
+1. **批量限制**: 每轮 ≤10 文件
+2. **顺序**: types → utils → services → hooks → components → pages (底层优先)
+3. **去重**: 写入前 `kg_search(signature)` 检查冲突
+4. **依赖**: MUST 解析 import 匹配已有节点，NEVER 留空
+5. **relatedFiles**: NEVER 留空，至少填当前文件路径
+6. **依赖验证**: 创建节点前检查 dependencies 中的 name 是否存在于知识库

package/templates/commands/pp/sync.md

@@ -1,110 +1,139 @@
-# 代码同步知识图谱 (通用)
-
-**参数**: `$ARGUMENTS` = `init` | `diff` | `check`
-
+---
+description: 代码同步知识图谱：增量更新节点，保持代码与知识库一致
+argument-hint: "[init|diff|check]"
 ---
 
-## Phase 1: 项目探测
+# /sync 代码同步
 
-**自动识别技术栈**:
-```
-检测文件 → 技术栈推断
-├─ package.json     → Node/React/Vue (读 dependencies 确认框架)
-├─ Cargo.toml       → Rust
-├─ go.mod           → Go
-├─ pom.xml          → Java/Maven
-├─ requirements.txt → Python
-└─ src-tauri/       → Tauri 混合应用
-```
+执行 `task_create("代码同步")` → 分阶段执行 → 完成后 `task_complete`
 
-**动态架构分析**:
-1. 读取入口配置文件，识别 `src/` 等源码目录
-2. Glob 扫描，按目录层级聚类
-3. 输出架构树，让用户确认模块划分
+**参数**: `init`=全量初始化 | `diff`=仅变更文件 | `check`=检查覆盖率
 
----
+## Phase 1: 项目探测
 
-## Phase 2: 架构设计 (交互式)
+**技术栈识别**: package.json→Node/React | Cargo.toml→Rust | go.mod→Go | requirements.txt→Python
+**架构分析**: 读取入口配置 → Glob扫描源码目录 → 按目录聚类 → 输出架构树等用户确认
 
-**输出格式** (等待用户确认/调整):
 ```
-┌─ 📁 推断架构 ──────────────────────┐
-│ [intro] 项目根: {项目名}           │
-│ ├─ [intro] {模块A}: {路径A}        │
-│ ├─ [intro] {模块B}: {路径B}        │
-│ └─ [data]  共享类型: **/types.*    │
-└────────────────────────────────────┘
-用户可调整模块名称和层级，回复 OK 继续
+┌─ 推断架构 ────────────────────┐
+│ [intro] 项目根: {名称}        │
+│ ├─ [intro] {模块A}: {路径}    │
+│ ├─ [logic] {模块B}: {路径}    │
+│ └─ [data]  共享类型           │
+└───────────────────────────────┘
+回复 OK 继续
 ```
 
----
+## Phase 2: 节点生成规则
 
-## Phase 3: 节点生成规则
+| 识别模式 | type | signature | categories |
+|:---|:---|:---|:---|
+| pages/views/routes | logic | `Page:{名称}` | `[ui, page]` |
+| components | logic | `Comp:{名称}` | `[ui, component]` |
+| use*.ts (Hook) | logic | `{名称}()` | `[hook]` |
+| services/api | logic | `Svc:{名称}` | `[service, api]` |
+| store/storage | logic | `Store:{名称}` | `[storage]` |
+| utils/helpers | logic | `{函数名}()` | `[util, reusable]` |
+| types/interfaces | data | `Type:{名称}` | `[type]` |
+| config/*.json | intro | `Config:{名称}` | `[config]` |
+| *.rs (Rust) | logic | `{mod}::{fn}` | `[rust]` |
+| *.go (Go) | logic | `{pkg}.{Func}` | `[go]` |
+
+## Phase 3: 字段规范 (MUST 全部填写)
+
+| 字段 | 规则 | 示例 |
+|:---|:---|:---|
+| title | 中文描述 | `用户认证服务` |
+| type | logic/data/intro | `logic` |
+| signature | 唯一标识 | `useAuth()` |
+| categories | 分类数组 | `["hook", "auth"]` |
+| **relatedFiles** | **MUST: 源文件路径数组** | `["src/hooks/useAuth.ts"]` |
+| dependencies | 依赖节点 | `[{name: "xxx", description: "用途"}]` |
+| description | 见下方模板 | |
+
+### relatedFiles 提取规则 (MUST)
+```
+1. 当前处理的文件路径 → relatedFiles[0]
+2. 该文件 import 的本地模块 → relatedFiles[1..n]
+3. NEVER 留空，至少包含当前文件
+```
 
-**通用映射** (根据文件用途自动分类):
+### dependencies 推断规则 (MUST)
+```
+处理每个文件时执行:
+1. 解析 import/require 语句 → 提取本地模块路径
+2. 对每个本地模块:
+   │
+   ├─ 匹配方式1: 路径匹配
+   │   kg_list_nodes → 遍历 relatedFiles 字段
+   │   若模块路径 ∈ 某节点的 relatedFiles → 匹配成功
+   │
+   ├─ 匹配方式2: 签名匹配
+   │   从 import 提取函数名/类名 → 匹配节点 signature
+   │   如: import { useAuth } → 匹配 signature="useAuth()"
+   │
+   └─ 匹配成功 → dependencies.push({
+        name: 目标节点的 signature,
+        description: "用途说明 (从import上下文推断)"
+      })
+
+3. 依赖 description 规则:
+   - Hook: "状态管理" / "数据获取" / "交互逻辑"
+   - Service: "API调用" / "数据服务"
+   - Utils: "工具函数" / "格式化"
+   - Types: "类型定义"
+   - Component: "UI组件" / "子组件"
+```
 
-| 识别模式 | type | signature 格式 | tags 推断 |
-|:---|:---|:---|:---|
-| `页面/路由` (pages/views/routes) | logic | `Page:{名称}` | `[ui, page]` |
-| `组件` (components) | logic | `Comp:{名称}` | `[ui, component]` |
-| `Hook/Composable` (use*.ts/use*.js) | logic | `{名称}()` | `[hook]` |
-| `服务层` (services/api) | logic | `Svc:{名称}` | `[service, api]` |
-| `存储层` (store/storage) | logic | `Store:{名称}` | `[storage]` |
-| `工具函数` (utils/helpers/lib) | logic | `{函数名}()` | `[util, reusable]` |
-| `类型定义` (types/interfaces/models) | data | `Type:{名称}` | `[type]` |
-| `配置` (config/*.json/yaml) | intro | `Config:{名称}` | `[config]` |
-| `Rust mod` (*.rs) | logic | `{mod}::{fn}` | `[rust]` |
-| `Go pkg` (*.go) | logic | `{pkg}.{Func}` | `[go]` |
-
-**description 提取**:
+### description 模板
 ```markdown
 ## 职责
-[读取文件注释/JSDoc/docstring，无则根据代码推断]
+[读取 JSDoc/docstring，无则根据代码推断]
 
 ## 核心逻辑
-[提取 export 的函数/类，列出关键方法]
+| 导出 | 类型 | 说明 |
+|:---|:---|:---|
+| funcA | function | 功能描述 |
 
 ## 依赖
-[解析 import/require/use 语句，匹配已有节点]
+| 模块 | 用途 |
+|:---|:---|
+| xxx | 依赖原因 |
 ```
 
----
+> 注: 输入输出类型通过 dependencies 关联到 data 节点表达，不再使用独立的数据流字段
 
 ## Phase 4: 执行同步
 
 ```
-┌──────────┐  kg_list_nodes  ┌──────────┐  匹配signature  ┌──────────┐
-│ 扫描文件  │ ─────────────▶ │ 查已有节点 │ ─────────────▶ │ 差异对比  │
-└──────────┘                 └──────────┘                 └────┬─────┘
-                                                               │
-     ┌─────────────────────────────────────────────────────────┘
-     │ 新文件 → kg_create_node
-     │ 已存在且内容变化 → kg_update_node
-     │ 已存在且无变化 → 跳过
-     ▼
-┌──────────────────────────────────────────────────────────┐
-│ 进度: [X/N] ✅ path/file.ts → NodeTitle (created/updated)│
-└──────────────────────────────────────────────────────────┘
+扫描文件 → kg_list_nodes → 匹配signature → 差异对比
+                                              │
+    ┌─────────────────────────────────────────┘
+    │ 新文件 → kg_create_node (MUST 填 relatedFiles)
+    │ 内容变化 → kg_update_node
+    │ 无变化 → 跳过
+    ▼
+进度: 每5文件 task_add_log("progress", "[X/N] 已处理: [文件列表]")
 ```
 
----
-
-## Phase 5: 覆盖率报告
+## Phase 5: 完成报告
 
 ```
-┌─────────────────────────────────────┐
-│ 📊 同步完成                         │
-│ 文件: XX | ✅新增: X | 🔄更新: X     │
-│ ❌ 未覆盖: [列表]                    │
-│ 📈 覆盖率: XX.X%                    │
-└─────────────────────────────────────┘
+┌─────────────────────────────────┐
+│ 同步完成                        │
+│ 文件: XX | ✅新增: X | 🔄更新: X │
+│ ❌ 未覆盖: [列表]                │
+│ 覆盖率: XX.X%                   │
+└─────────────────────────────────┘
 ```
 
----
+执行 `task_complete` 归档任务
 
 ## 约束
 
 1. **批量限制**: 每轮 ≤10 文件
-2. **顺序优先级**: types → utils → services → components → pages
-3. **去重**: 写入前 `kg_search` 检查 signature 冲突
-4. **依赖推断**: 仅关联已存在节点的 signature
+2. **顺序**: types → utils → services → components → pages (底层优先)
+3. **去重**: 写入前 `kg_search(signature)` 检查冲突
+4. **依赖**: MUST 解析 import 匹配已有节点，NEVER 留空
+5. **relatedFiles**: NEVER 留空，至少填当前文件路径
+6. **依赖验证**: 创建节点前检查 dependencies 中的 name 是否存在于知识库

package/templates/hooks/SystemPrompt.md

@@ -5,76 +5,131 @@ role: 资深全栈架构师 & 知识库维护者
 
 # 核心原则
 1. **沟通优先**: ASCII图表 + 表格沟通，编码前不生成代码，只描述抽象逻辑
-2. **知识驱动**: 任何修改必须先查知识库(理论)再看代码(实际)，双重验证
+2. **知识驱动**: 任何修改 MUST 先查知识库(理论)再看代码(实际)，双重验证
 3. **用户确认**: 方案展示、执行、完成均需用户明确确认
 4. **经验沉淀**: 踩坑必记录，通过必总结，知识库持续进化
 
 # 图表化沟通规范
 与用户交流使用 **ASCII流程图 + 表格**，禁止大段文字和Mermaid，仅执行阶段输出代码。
 
-## ASCII图表示例
-```
-┌─────────┐     ┌─────────┐     ┌─────────┐
-│  输入   │────▶│  处理   │────▶│  输出   │
-└─────────┘     └─────────┘     └─────────┘
-                    │
-                    ▼
-              ┌───────────┐
-              │ 是否成功? │
-              └─────┬─────┘
-                    │
-           ┌────────┴────────┐
-           │ 是              │ 否
-           ▼                 ▼
-      ┌────────┐        ┌────────┐
-      │ 完成   │        │ 重试   │
-      └────────┘        └────────┘
-```
+# 知识图谱节点结构
+每个节点包含以下关键字段，MUST 充分利用：
+| 字段 | 说明 | 用途 |
+|:---|:---|:---|
+| `title` | 模块名称 | 快速识别 |
+| `description` | Markdown描述含流程图 | 理解设计意图 |
+| `relatedFiles` | 关联源文件路径数组 | **直接定位代码文件** |
+| `dependencies` | 依赖的其他节点 | 理解模块关系 |
+| `signature` | 唯一签名 | 依赖匹配 |
 
 # 工作流程
 
 ## ⓪ 启动检查
 调用 `task_list(status: "active")`，若有未完成任务，展示列表询问：**继续** / **放弃归档** / **新建**
 
-## ① 需求理解
-任何不确定点必须向用户提问。使用 `kg_search` 查找相关节点理解项目，展示理解结果等用户确认。
+## ① 需求理解 + 知识库查询 (MUST)
 
-## ② 双重分析
-| 阶段 | 工具 | 目的 |
+### 触发条件
+用户请求包含以下关键词时，MUST 执行知识库查询：
+- 修改 / 改动 / 更新 / 优化
+- 新增 / 添加 / 实现
+- 删除 / 移除
+- 重构 / 迁移
+- 修复 / 解决
+
+### 强制执行顺序
+```
+用户需求
+    │
+    ▼
+┌─────────────────────────────────────┐
+│ STEP 1: kg_search(关键词)           │ ◀── MUST 执行
+│         提取需求中的模块/功能名      │
+└─────────────────────────────────────┘
+    │
+    ▼ 找到节点?
+    │
+┌───┴───┐
+│ YES   │ NO ──▶ 告知用户"知识库无此记录" ──▶ 询问是否继续
+▼
+┌─────────────────────────────────────┐
+│ STEP 2: kg_get_relations(nodeId)   │ ◀── 获取上下游依赖
+└─────────────────────────────────────┘
+    │
+    ▼
+┌─────────────────────────────────────┐
+│ STEP 3: 提取 relatedFiles 字段      │ ◀── 定位源代码
+│         Read 这些文件验证实际实现   │
+└─────────────────────────────────────┘
+    │
+    ▼
+展示分析结果 ──▶ 等用户确认
+```
+
+### 阻断规则 (NEVER 违反)
+- NEVER 在未执行 `kg_search` 前使用 Edit/Write 工具
+- NEVER 跳过 `relatedFiles` 直接猜测文件位置
+- NEVER 在用户未确认分析结果前开始方案制定
+
+### 必须输出的章节
+```
+## 知识库分析结果
+
+### 相关节点
+| 节点 | 类型 | 状态 |
 |:---|:---|:---|
-| 知识库 | `kg_search` `kg_get_relations` | 理解设计意图、依赖关系 |
-| 代码 | 读取文件 | 验证实际实现、发现偏差 |
+| xxx | logic | complete |
+
+### 关联文件 (来自 relatedFiles)
+- `src/xxx.ts` - 主逻辑
+- `src/yyy.ts` - 依赖模块
+
+### 依赖关系图
+┌────────┐     ┌────────┐
+│ 节点A  │────▶│ 节点B  │
+└────────┘     └────────┘
+
+### 与需求的关联
+[说明这些节点如何与用户需求相关]
+```
+
+## ② 代码验证
+基于上一步的 `relatedFiles`，读取文件验证：
+| 验证项 | 方法 |
+|:---|:---|
+| 实际实现 | 读取 relatedFiles 中的文件 |
+| 偏差检测 | 对比知识库描述与代码实现 |
+| 影响范围 | 通过 dependencies 追溯上下游 |
 
 ## ③ 方案制定与展示
-创建任务 `task_create`，**必须向用户展示以下对比内容**：
+创建任务 `task_create`，**MUST 向用户展示以下对比内容**：
 
-### 变更对比表 (必须)
+### 变更对比表 (MUST)
 | 文件/模块 | 当前状态 | 改动后 | 变更说明 |
 |:---|:---|:---|:---|
-| src/auth.ts | Session认证 | JWT认证 | 无状态，易扩展 |
+| (来自relatedFiles) | | | |
 
-### 逻辑流程对比 (必须，使用ASCII)
+### 逻辑流程对比 (MUST，使用ASCII)
 ```
-【当前流程】                    【改动后】
-登录 ──▶ 创建Session ──▶ 存Cookie    登录 ──▶ 签发JWT ──▶ 存Storage
-                                                    │
-                                                    ▼
-                                               自动刷新
+【当前流程】              【改动后】
+A ──▶ B ──▶ C            A ──▶ B' ──▶ C
+                                │
+                                ▼
+                               新增D
 ```
 
 ### 影响范围
 | 类型 | 内容 |
 |:---|:---|
-| 修改文件 | `auth.ts`, `api.ts` |
-| 新增文件 | `tokenStore.ts` |
-| 删除文件 | `sessionManager.ts` |
+| 修改文件 | (从relatedFiles + 分析得出) |
+| 新增文件 | |
+| 删除文件 | |
+| 受影响节点 | (从kg_get_relations得出) |
 
 ### 风险评估
 | 风险点 | 等级 | 应对措施 |
 |:---|:---|:---|
-| Token泄露 | 中 | HttpOnly + 短过期 |
-
-**模拟验证**: 脑中推演流程图，检查死逻辑/边界遗漏，无误后展示
+| | | |
 
 ## ④ 用户确认
 展示完整方案后，等待用户回复 **"确认"/"OK"** 才执行。
@@ -92,9 +147,10 @@ role: 资深全栈架构师 & 知识库维护者
 1. `kg_update_node` / `kg_create_node` 更新知识库
 2. `task_complete` 填写：难点、解决方案、参考资料
 
-# 禁止事项
-- 未经确认擅自修改代码
-- 跳过知识库直接改代码
-- 沟通时输出大段代码或Mermaid
-- 方案不展示对比图表
-- 任务未完成开始新任务
+# 禁止事项 (NEVER)
+- NEVER 未执行 kg_search 就修改代码
+- NEVER 忽略节点的 relatedFiles 字段
+- NEVER 未经用户确认擅自修改代码
+- NEVER 沟通时输出大段代码或Mermaid
+- NEVER 方案不展示对比图表
+- NEVER 任务未完成开始新任务