@roarpeng/graphflow 1.7.6 → 1.7.9

package/README.md

@@ -1,24 +1,24 @@
 # GraphFlow
 
-> **Local-first 代码知识图谱 + 跨会话学习记忆** —— 不只是压缩上下文，还记住项目的决策与教训。
+> **Local-first ?????? + ????????* ?????????????????????????
 
-GraphFlow 把你的仓库变成一张**可查询的代码图谱**，在 agent 读全文之前先返回压缩摘要与锚点（入门钩子：**图谱 + 90%+ token 压缩**）；更进一步，它用 **Episodic / Skill / Decision 节点**把每次任务的决策与教训沉淀回图谱，形成跨会话的**学习飞轮**（差异化纵深）。
+GraphFlow ??????????*????????**?? agent ??????????????????????*?? + 90%+ token ??**????????? **Episodic / Skill / Decision ??**???????????????????????**????**?????????
 
-纯 TypeScript/Node 本地运行，通过 CLI、MCP、VS Code 扩展对外暴露。**无需 API key、无需配置**即可起步：结构索引 + 离线压缩开箱即用。
+??TypeScript/Node ??????? CLI?MCP?VS Code ????????*?? API key?????**??????????+ ??????????
 
-## 30 秒上手
+## 30 ????
 
-无需 API key、无需注册——结构图谱与离线压缩本地直接跑：
+?? API key??????????????????????
 
 ```bash
-# 1. 建立结构图谱（纯 AST，零 LLM、零网络）
+# 1. ???????? AST?? LLM??????
 npx @roarpeng/graphflow graph index .
 
-# 2. 压缩预览：读全文前先拿摘要 + 锚点（通常省 90%+ token）
+# 2. ??????????????+ ???????90%+ token??
 npx @roarpeng/graphflow context preview "orchestrator" --json
 ```
 
-接入 MCP（Cursor / Claude Code 等），最小配置：
+?? MCP?Cursor / Claude Code ????????
 
 ```json
 {
@@ -31,162 +31,162 @@ npx @roarpeng/graphflow context preview "orchestrator" --json
 }
 ```
 
-接好后让 agent 优先调用 `graphflow_context` 取压缩上下文；多步任务用 `graphflow_plan`。配置 provider API key 是**可选**的——只在需要 LLM 规划增强时才用。
+???? agent ???? `graphflow_context` ???????????? `graphflow_plan`????provider API key ??*???*????????LLM ?????????
 
-## 为什么选 GraphFlow（与同类对比）
+## ?????GraphFlow????????
 
-这个赛道里有许多优秀的单点工具，GraphFlow 的定位不是"某一项最强"，而是**在代码图谱之上叠加了上下文压缩、规划编排与跨会话学习记忆**——尤其是"记忆型代码图谱"这一块目前少有人占据。诚实对比如下：
+????????????????GraphFlow ???????????????**?????????????????????????????*?????"??????????????????????????
 
-| 维度 | **GraphFlow** | CodeGraph | Serena | Repomix |
+| ?? | **GraphFlow** | CodeGraph | Serena | Repomix |
 | --- | --- | --- | --- | --- |
-| 结构代码图谱 | ✅ 多语言 AST 图谱 | ✅ 更成熟（★ 更高） | ⚠️ LSP 符号（非全图谱） | ❌ |
-| 上下文压缩 | ✅ 两层渐进（结构+向量） | ⚠️ 图查询为主 | ⚠️ 符号级精修 | ✅ 整库打包（无压缩） |
-| 规划编排 | ✅ DAG / 六顶思考帽 | ❌ | ❌ | ❌ |
-| **跨会话学习记忆** | ✅ Episodic / Skill / Decision 节点 | ❌ | ❌ | ❌ |
-| Local-first | ✅ | ✅ | ✅ | ✅ |
-| 许可 | Apache-2.0 | MIT | MIT | 宽松开源 |
+| ?????? | ????? AST ?? | ????????????| ?? LSP ???????? | ??|
+| ??????| ??????????????| ?? ??????| ?? ??????| ????????????|
+| ???? | ??DAG / ????? | ??| ??| ??|
+| **????????* | ??Episodic / Skill / Decision ?? | ??| ??| ??|
+| Local-first | ??| ??| ??| ??|
+| ?? | Apache-2.0 | MIT | MIT | ?????|
 
-> 实话实说：论纯图谱的成熟度与社区规模，CodeGraph 更领先；论 LSP 符号编辑标准，Serena 更专精；论整库打包，Repomix 更简单。GraphFlow 的价值在于把"图谱 + 压缩 + 规划 + 学习记忆"合到一处，让 agent 不仅省 token，还能跨会话复用项目经验。
+> ???????????????????CodeGraph ??????LSP ???????Serena ??????????Repomix ????GraphFlow ??????"?? + ?? + ?? + ????"???????agent ????token??????????????
 
-## 当前能力总览（v1.7.6+）
+## ???????v1.7.9+??
 
-| 能力域 | 说明 |
+| ????| ?? |
 | --- | --- |
-| **任务规划与移交** | 按任务复杂度分流 simple / complex / insight；DAG 规划；**ATP v1.0 Agent Thinking Protocol**：Intent → Requirement → Six Hats → 5-Why → First Principles → Decision Matrix → Planning → Reflection（`planInsight(task, opts, true)` 开启完整 8 阶段分析，简单任务自动 short-circuit）；Agent 委托模式生成 work items；默认 **bridge 模式**输出结构化任务描述符交给外部 coding agent 执行 |
+| **????????* | ???????? simple / complex / insight?DAG ????*ATP v1.0 Agent Thinking Protocol**?Intent ??Requirement ??Six Hats ??5-Why ??First Principles ??Decision Matrix ??Planning ??Reflection?`planInsight(task, opts, true)` ?????8 ????????????short-circuit??Agent ?????? work items????**bridge ??**?????????????? coding agent ?? |
 
 | **模型路由** | Smart / Economy 双 tier；多 provider 健康探测与 fallback（**DeepSeek**、OpenAI、Anthropic、百炼、豆包） |
-| **知识图谱** | 工作区 AST 索引（TS/JS/Python/Rust/Go/C/C++/Java/Ruby/Kotlin/Swift）；File / Module / Symbol 节点 + 依赖/引用/定义/调用/继承边；图谱 artifact 导入/导出 |
+| **知识图谱** | 工作区 AST 索引（TS/JS/Python/Rust/Go/C/C++/Java/Ruby/Kotlin/Swift/Dart）；File / Module / Symbol 节点 + 依赖/引用/定义/调用/继承边；图谱 artifact 导入/导出 |
 | **上下文压缩** | L1/L2/L3 分层锚点；近无损打包；图结构压缩（边权重+PageRank，零成本默认开启）；向量召回 + RRF 融合；RepoMap 概览；自适应预算 |
 | **持续建图** | 默认 `autoIndexOnSave`；MCP 启动时自动启动 FileWatcher；preview / run 前按需增量索引；MCP `graphflow_index` 单文件增量 |
 | **学习飞轮** | Episodic Memory（Jaccard + embedding RRF 语义检索）、Reflection（聚类 + Lesson 提取）、Skill 节点（score ±1，bounded [-20,20]）、nightly 学习、技能提示注入规划 |
 | **可观测性** | `graphflow_diagnose` 累计 token 节省；VS Code 知识图谱 Snapshot |
-| **Agent 接入** | CLI `--json`；MCP stdio（**10 工具**）；自动安装 MCP 到 15+ Agent（Cursor / Claude Code / Windsurf / Cline / Codex / Gemini 等） |
+| **Agent 接入** | CLI `--json`；MCP stdio（**10 工具**）；自动安装 MCP 到 15+ Agent（Cursor / Claude Code / Windsurf / Cline / Codex / Gemini / Opencode 等） |
 | **VS Code 扩展** | Settings、建图、路由测试、Context Preview、**知识图谱可视化**、Skill Insights、Chat Agent、一键安装 MCP |
 | **存储后端** | `file`（JSON）/ `memory` / `sqlite`（FTS5）/ `mcp-http`（Graphify） |
 | **多项目隔离** | 全局配置共享 LLM/路由；**图谱路径按当前工作区解析**，不再串读其它项目的 `graphflow-out` |
-| **工程质量** | TypeScript strict；**59 测试文件 / 280+ tests**；`npm run ci` 含扩展 esbuild 打包与 bundled runtime smoke |
+| **工程质量** | TypeScript strict；**72 测试文件 / 357+ tests**；`npm run ci` 含扩展 esbuild 打包与 bundled runtime smoke |
 
-### 一句话总结
+### ?????
 
-> 从 task 描述出发，自动规划 → 路由模型 → 压缩图谱上下文（含向量召回）→ **输出结构化执行描述符交给外部 coding agent**，并把经验沉淀回知识图谱；定位为 **上下文与规划服务（context service）**，而非独立执行器。
+> ??task ???????????????? ??????????????????**?????????????? coding agent**?????????????????**?????????context service??*??????????
 
-### v1.7.0 核心（2026-07）
+### v1.7.0 ????026-07??
 
-**P0 向量召回修正**：废弃 FNV-1a hash embedding，引入 `@xenova/transformers` + `all-MiniLM-L6-v2`（384 维，约 22MB，纯 JS 推理），实现真正的本地语义召回。
+**P0 ??????**????FNV-1a hash embedding????`@xenova/transformers` + `all-MiniLM-L6-v2`??84 ????22MB?? JS ?????????????????
 
-**P1 移除 hnswlib-node**：彻底移除 C++ 编译依赖，向量召回统一使用纯线性扫描（典型仓库 <10K 节点性能完全够用）。
+**P1 ?? hnswlib-node**??????C++ ??????????????????????? <10K ???????????
 
-**P2 MCP 工具精简**：18 个工具合并为 10 个核心工具（context、plan、index、insight、diagnose、artifact 等合并），降低 LLM 工具调用认知负荷。
+**P2 MCP ????**??8 ?????? 10 ??????context?plan?index?insight?diagnose?artifact ????????LLM ??????????
 
-**P2 ATP 自适应截断**：简单任务（低优先级、无约束、短描述）自动 short-circuit，跳过 First Principles / Decision Matrix / Reflection，节省 4-6 次 LLM 调用。
+**P2 ATP ?????**??????????????????????short-circuit????First Principles / Decision Matrix / Reflection????4-6 ??LLM ????
 
 ---
 
-### v1.5.0 核心（2026-07）
+### v1.5.0 ????026-07??
 
-**ATP v1.0 Agent Thinking Protocol**：以文档驱动的全链路思考协议增强深度分析流程。
+**ATP v1.0 Agent Thinking Protocol**????????????????????????
 
-**新增 5 个分析阶段**（在 Six Hats + 5-Why 基础上补齐）：
+**?? 5 ??????*?? Six Hats + 5-Why ????????
 
-1. **Intent Analysis** — 区分显式/隐式意图、核心问题、非目标、成功标准
-2. **Requirement Analysis** — 结构化功能/非功能需求、优先级、范围（included/excluded）
-3. **First Principles** — 拆解到不可再分事实、挑战假设
-4. **Decision Matrix** — 多方案按 5 维度打分（complexity/cost/risk/maintainability/impact）比较后推荐
-5. **Plan Reflection** — 规划阶段自评置信度、不确定性、缺失信息、改进方向
+1. **Intent Analysis** ??????/???????????????????
+2. **Requirement Analysis** ?????????????????????included/excluded??
+3. **First Principles** ?????????????????
+4. **Decision Matrix** ?????? 5 ?????complexity/cost/risk/maintainability/impact??????
+5. **Plan Reflection** ???????????????????????????
 
-**ATP 类型 IR**：`atp-schema.ts` 导出 `AgentThinkingProtocol` 完整接口，作为 Multi-Agent 共享中间表示。
+**ATP ?? IR**?`atp-schema.ts` ?? `AgentThinkingProtocol` ????????Multi-Agent ????????
 
-**TaskNode 丰富**：新增 `priority`、`complexity`、`verification`、`inputs`、`outputs`、`risks` 6 个可选字段。
+**TaskNode ??**????`priority`?`complexity`?`verification`?`inputs`?`outputs`?`risks` 6 ???????
 
-**Agent 委托扩展**：work items 扩展（+intent +requirement +first-principles +decision-matrix +reflection），submit/merge 闭环不变。
+**Agent ????**?work items ????intent +requirement +first-principles +decision-matrix +reflection??submit/merge ??????
 
-**向后兼容**：`planInsight(task, options)` 不传第三参数时行为不变；`runFullAtp=true` 启用完整 ATP 8 阶段。
+**????**?`planInsight(task, options)` ????????????`runFullAtp=true` ???? ATP 8 ????
 
-**P0 残留清理**：移除 VS Code 扩展中对已删除 runtime 方法的调用（`enrichGraph`/`downloadModel`/`showSetupGuide` 命令 + `/enrich` 聊天命令）；清理 87 处 OpenBMB/enrichment 残留代码；移除 `canaryAllowed`/`canaryReason` 和 5 个 enrichment 类型字段。
+**P0 ????**????VS Code ????????runtime ??????`enrichGraph`/`downloadModel`/`showSetupGuide` ?? + `/enrich` ???????? 87 ??OpenBMB/enrichment ????????`canaryAllowed`/`canaryReason` ??5 ??enrichment ??????
 
-### v1.4.0 核心（2026-07）
+### v1.4.0 ????026-07??
 
-**奥卡姆剃刀精简**：移除 OpenBMB 本地部署、语义压缩模型、语义增强器、技能进化、金丝雀门控、本地嵌入模型、向量存储等未产生真实价值的模块。留下的是三条经过验证的闭环链路。
+**???????**????OpenBMB ?????????????????????????????????????????????????????????????????????
 
-**三大核心功能验证修复**：
+**??????????**??
 
-1. **HNSW 向量召回完全打通**（P0 修复）
-   - `file-indexer` 现在为所有 File/Symbol/Module 节点附加真正的语义 embedding（`@xenova/transformers` + `all-MiniLM-L6-v2`，384 维）
-   - `orchestrator-context` 现在传递 `embeddingProvider` + `enableVectorRecall` 到压缩管道
-   - 向量召回统一使用纯线性扫描，无需 C++ 编译依赖
+1. **HNSW ?????????*?P0 ????
+   - `file-indexer` ??????File/Symbol/Module ??????????embedding?`@xenova/transformers` + `all-MiniLM-L6-v2`??84 ??
+   - `orchestrator-context` ?????`embeddingProvider` + `enableVectorRecall` ??????
+   - ???????????????? C++ ????
 
-2. **FileWatcher 接入 MCP 启动**（P0 修复）
-   - `startFileWatcherIfEnabled` 此前是死代码，现已接入 MCP 服务器启动路径
-   - 当 `autoIndexOnSave: true` 时自动监听文件变化并增量索引
+2. **FileWatcher ?? MCP ??**?P0 ????
+   - `startFileWatcherIfEnabled` ????????????MCP ????????
+   - ??`autoIndexOnSave: true` ??????????????
 
-3. **技能飞轮闭环修复**（P1 修复）
-   - `skillHints` 解耦：不再依赖 `enableGraphContextInPrompt`，独立注入 worker prompt
-   - Dangling edges 修复：`applySkillLearning` 现在先创建 Decision 节点再连 `improves` 边
+3. **?????????*?P1 ????
+   - `skillHints` ??????? `enableGraphContextInPrompt`??????worker prompt
+   - Dangling edges ???`applySkillLearning` ??????Decision ???? `improves` ??
 
-### 历史演进
+### ????
 
-- **v1.3.x**：多项目图谱隔离、Java/Ruby 索引器、MCP 工具扩展、知识图谱可视化
-- **v1.0.x**：诚实执行语义（bridge 模式）、三层渐进压缩、混合压缩模型
-- **v0.6.x**：全局配置脚手架、autoIndexOnSave、runtime 模块化、VS Code esbuild bundle
+- **v1.3.x**?????????Java/Ruby ????MCP ????????????
+- **v1.0.x**????????bridge ??????????????????
+- **v0.6.x**?????????autoIndexOnSave?runtime ????VS Code esbuild bundle
 
-### 发布信息
+### ????
 
-- 最新版本：**v1.7.6**（root + vscode-extension）；npm：`@roarpeng/graphflow@1.7.6`
-- **GitHub Release**：push 到 `main` 后 CI 在 `windows-2022` 上自动构建 VSIX 并发布到 [GitHub Releases](https://github.com/Roarpeng/GraphFlow/releases)
-- **npm 发布**：push tag `v*`（如 `v1.4.1`）触发 [Publish npm](https://github.com/Roarpeng/GraphFlow/actions/workflows/publish-npm.yml) 工作流
-- 变更日志：`CHANGELOG.md`
+- ?????**v1.7.9**?root + vscode-extension??npm?`@roarpeng/graphflow@1.7.9`
+- **GitHub Release**?push ??`main` ??CI ??`windows-2022` ??????VSIX ???? [GitHub Releases](https://github.com/Roarpeng/GraphFlow/releases)
+- **npm ??**?push tag `v*`?? `v1.4.1`????[Publish npm](https://github.com/Roarpeng/GraphFlow/actions/workflows/publish-npm.yml) ????
+- ?????`CHANGELOG.md`
 
-## 环境要求
+## ????
 
 1. Node.js >= 20
 2. npm >= 10
-3. Windows / macOS / Linux 均可
-4. **npm 安装 `@roarpeng/graphflow` 时**：纯 JS/TS 依赖，无原生模块编译
+3. Windows / macOS / Linux ??
+4. **npm ?? `@roarpeng/graphflow` ??*?? JS/TS ??????????
 
-## 5 分钟本地试跑
+## 5 ??????
 
 ```bash
 npm install
 npm run ci
 ```
 
-预期：`lint` 无错误、`build` 成功、**280+ tests** 通过、扩展 bundle 与 runtime smoke 通过。
+预期：`lint` 无错误、`build` 成功、**357+ tests** 通过、扩展 bundle 与 runtime smoke 通过。
 
-## Agent 工具接入
+## Agent ????
 
-GraphFlow 支持两种对外接入方式：
+GraphFlow ????????????
 
-1. **CLI 机器输出**：核心命令均支持 `--json`
-2. **MCP stdio server**：Cursor、Claude Code 等可直接调用
+1. **CLI ????**???????? `--json`
+2. **MCP stdio server**?Cursor?Claude Code ??????
 
-本仓库启动 MCP：
+??????MCP??
 
 ```bash
 npm run start:mcp
 ```
 
-### MCP 工具一览（10 个）
+### MCP ?????10 ??
 
-| 工具 | 用途 |
+| ?? | ???|
 | --- | --- |
-| `graphflow_context` | 预览压缩上下文（query）或扩展锚点（anchorId）（**优先调用**） |
-| `graphflow_plan` | 多步任务分解与 DAG 规划（mode='simple' 或 'insight'） |
-| `graphflow_run` | 规划 + 压缩上下文，输出 bridge 执行描述符 |
-| `graphflow_report_outcome` | 向 GraphFlow 汇报任务执行结果，用于学习飞轮 |
-| `graphflow_insight` | 提交或合并 agent 分析结果（Six Hats / plan prompts） |
-| `graphflow_index` | 全工作区增量建图、单文件建图或全量重建 |
-| `graphflow_skill_insights` | 技能学习洞察 |
-| `graphflow_diagnose` | 路由健康、图谱统计与 token 节省 |
-| `graphflow_artifact` | 导出或导入压缩图谱 artifact |
-| `graphflow_skill_guide` | 获取 GraphFlow Skill 使用指南 |
+| `graphflow_context` | ????????query???????anchorId??**????**??|
+| `graphflow_plan` | ????????DAG ???mode='simple' ??'insight'??|
+| `graphflow_run` | ?? + ???????? bridge ??????|
+| `graphflow_report_outcome` | ??GraphFlow ????????????????|
+| `graphflow_insight` | ??????agent ?????Six Hats / plan prompts??|
+| `graphflow_index` | ????????????????????|
+| `graphflow_skill_insights` | ???????|
+| `graphflow_diagnose` | ?????????? token ?? |
+| `graphflow_artifact` | ??????????artifact |
+| `graphflow_skill_guide` | ?? GraphFlow Skill ???? |
 
-**MCP 建图提示**：用户级 MCP 进程的 `cwd` 不一定是当前项目。请任选其一：
+**MCP ????**???? MCP ????`cwd` ????????????????
 
-- 调用 `graphflow_index` 时传入 `rootDir`（项目绝对路径）
-- 在 MCP 配置中设置 `GRAPHFLOW_WORKSPACE_ROOT` 环境变量
-- 使用 VS Code 扩展「建立图谱」或项目级 `.cursor/mcp.json`
+- ?? `graphflow_index` ????`rootDir`????????
+- ??MCP ??????`GRAPHFLOW_WORKSPACE_ROOT` ????
+- ?? VS Code ?????????????`.cursor/mcp.json`
 
-CLI 示例：
+CLI ????
 
 ```bash
 npm run start -- plan "refactor planner and add tests" --json
@@ -194,34 +194,34 @@ npm run start -- context preview "orchestrator" --json
 npm run start -- graph inspect --json
 ```
 
-外部 agent 约定文件：`AGENTS.md`、`CLAUDE.md`、`.cursor/rules/graphflow.mdc`
+?? agent ?????`AGENTS.md`?`CLAUDE.md`?`.cursor/rules/graphflow.mdc`
 
-## 本地功能验证（CLI）
+## ???????CLI??
 
-### 图谱索引
+### ????
 
 ```bash
 npm run start -- graph index .
 ```
 
-预期：`indexedFiles=…; indexedSymbols=…`
+???`indexedFiles=?? indexedSymbols=?`
 
-### 上下文压缩预览
+### ????????
 
 ```bash
 npm run start -- context preview "orchestrator"
 ```
 
-预期：`summary=…; anchors=…; tokens=…`（相对原始上下文通常可节省 **90%+ token**）
+???`summary=?? anchors=?? tokens=?`??????????????**90%+ token**??
 
-### 执行任务 / 规划
+### ???? / ??
 
 ```bash
 npm run start -- run "update readme and add tests"
 npm run start -- plan "update readme and add tests and refactor architecture module"
 ```
 
-### 路由诊断 / 学习 / 洞察
+### ???? / ?? / ??
 
 ```bash
 npm run start -- route diagnose
@@ -230,27 +230,27 @@ npm run start -- graph inspect
 npm run start -- skill insights
 ```
 
-## 进阶能力
+## ????
 
-### 上下文压缩
+### ??????
 
-GraphFlow 的压缩采用「两层渐进」策略，先用零成本图结构压缩砍掉冗余节点，再用向量召回补充语义相关节点：
+GraphFlow ??????????????????????????????????????????????
 
-| 层 | 机制 | 成本 | 默认 |
+| ??| ?? | ?? | ?? |
 | --- | --- | --- | --- |
-| 图结构压缩 | 边权重连通子图 + PageRank 中心性重排 | 零 LLM | **开启** |
-| 向量召回 | transformers.js embedding + 线性扫描 + RRF 融合 | 本地模型 | **开启** |
-| RepoMap 概览 | 预算紧张时返回模块级地图 | 零 LLM | opt-in |
-| 自适应预算 | 按任务复杂度动态调整 token 预算 | 零 LLM | opt-in |
+| ??????| ????????+ PageRank ??????| ??LLM | **???* |
+| ???? | transformers.js embedding + ?????+ RRF ?? | ???? | **???* |
+| RepoMap ?? | ???????????? | ??LLM | opt-in |
+| ????? | ???????????token ?? | ??LLM | opt-in |
 
-**向量召回设计**：
+**??????**??
 
-- 索引时：`file-indexer` 为每个节点生成 384 维语义 embedding（`@xenova/transformers` + `all-MiniLM-L6-v2`，约 22MB，纯 JS 推理）
-- 查询时：对 query 生成同样维度的 embedding，与图中节点做 cosine similarity
-- 统一使用线性扫描（典型仓库 <10K 节点性能完全够用，无需 HNSW ANN）
-- 关键词检索 + 向量召回结果通过 RRF（Reciprocal Rank Fusion, k=60）融合
+- ????`file-indexer` ????????384 ????embedding?`@xenova/transformers` + `all-MiniLM-L6-v2`?? 22MB?? JS ????
+- ??????query ????????embedding????????cosine similarity
+- ????????????? <10K ??????????? HNSW ANN??
+- ??????+ ???????? RRF?Reciprocal Rank Fusion, k=60????
 
-配置示例：
+??????
 
 ```json
 {
@@ -270,15 +270,15 @@ GraphFlow 的压缩采用「两层渐进」策略，先用零成本图结构压
 }
 ```
 
-离线环境可提前预下载 `@xenova/transformers` 模型缓存，并通过 `embeddingPolicy.modelCacheDir` 或环境变量 `GRAPHFLOW_EMBEDDING_CACHE_DIR` 指向该目录。
+?????????? `@xenova/transformers` ???????? `embeddingPolicy.modelCacheDir` ??????`GRAPHFLOW_EMBEDDING_CACHE_DIR` ???????
 
-查看当前压缩与路由状态：
+????????????
 
 ```bash
 npm run start -- route diagnose
 ```
 
-### SQLite / FTS5 后端
+### SQLite / FTS5 ??
 
 ```json
 {
@@ -290,7 +290,7 @@ npm run start -- route diagnose
 }
 ```
 
-WAL + FTS5 全文索引；与 `file` / `memory` 接口一致。
+WAL + FTS5 ?????? `file` / `memory` ??????
 
 ### Episodic Memory + Reflection
 
@@ -301,18 +301,18 @@ const run = await orchestrate(
 );
 ```
 
-每次 task 写入 Episode（附带 embedding）；相似 task 注入历史决策（Jaccard + embedding RRF 融合检索）；`learn nightly` 合成 Lesson 节点；Lesson 自动注入后续任务的 planner prompt。
+?? task ?? Episode????embedding???? task ???????Jaccard + embedding RRF ??????`learn nightly` ?? Lesson ???Lesson ??????????planner prompt??
 
-### 技能学习飞轮
+### ???????
 
-- `applySkillLearning`：每次任务结束后提取技能原子，更新 Skill 节点 score（pass +1 / fail -1，bounded [-20,20]）
-- `suggestSkillHints`：查询 Skill 节点，按 score/uses 排序，返回 top-N 技能提示
-- 技能提示独立注入 worker prompt，不依赖图谱上下文是否启用
-- 复合技能：技能对共现次数达阈值后自动创建 composite skill 节点
+- `applySkillLearning`????????????????? Skill ?? score?pass +1 / fail -1?bounded [-20,20]??
+- `suggestSkillHints`????Skill ???? score/uses ??????top-N ?????
+- ?????????worker prompt??????????????
+- ???????????????????? composite skill ??
 
-### 跨语言 AST 索引
+### ??? AST ??
 
-| 语言 | 扩展 |
+| ?? | ?? |
 | --- | --- |
 | TypeScript / JavaScript | `.ts .tsx .js .jsx` |
 | Python | `.py` |
@@ -323,158 +323,159 @@ const run = await orchestrate(
 | Ruby | `.rb` |
 | Kotlin | `.kt` |
 | Swift | `.swift` |
+| Dart | `.dart` |
 
-通过 `graphPolicy.includeExtensions` 限制扫描范围。tree-sitter WASM 语法包在 `npm run build` 时打入 `wasm/` 并随 npm 包分发，安装后无需联网下载。
+?? `graphPolicy.includeExtensions` ???????tree-sitter WASM ???? `npm run build` ????`wasm/` ?? npm ???????????????
 
-### Agent MCP 自动安装
+### Agent MCP ????
 
-GraphFlow CLI 可自动检测并安装 MCP 配置到 15+ 编码 Agent：
+GraphFlow CLI ???????? MCP ????15+ ?? Agent??
 
 ```bash
-# 检测已安装的 Agent 与 MCP 配置状态
+# ???????Agent ??MCP ?????
 npx @roarpeng/graphflow doctor
 
-# 一键安装 MCP + Skill + Cursor Rules（推荐）
+# ?????MCP + Skill + Cursor Rules????
 npx @roarpeng/graphflow install
 
-# 或仅初始化项目级配置（.graphflow/config.json 等）
+# ????????????graphflow/config.json ??
 npx @roarpeng/graphflow init
 ```
 
-**本地 `npm install` 后**：若项目已有 `.cursor/mcp.json` 或 `.vscode/mcp.json`，postinstall 会自动注入 workspace 级 GraphFlow MCP 与 Skill；完整用户级安装请运行 `npx @roarpeng/graphflow install`。
+**?? `npm install` ??*?????? `.cursor/mcp.json` ??`.vscode/mcp.json`?postinstall ??????workspace ??GraphFlow MCP ??Skill????????????`npx @roarpeng/graphflow install`??
 
-### Trae / Trae CN 推荐配置
+### Trae / Trae CN ????
 
-Trae 区分 **Rules**（每轮自动加载）与 **Skill**（按需匹配）。仅装 Skill 时 GraphFlow 触发频率偏低；`install` / `init` 会在项目内写入：
+Trae ?? **Rules**??????????**Skill**??????????Skill ??GraphFlow ???????`install` / `init` ????????
 
-| 路径 | 作用 |
+| ?? | ?? |
 |------|------|
-| `.trae/rules/graphflow.md` | `alwaysApply: true` — 每轮强制先调 `graphflow_context` |
-| `.trae/skills/graphflow/SKILL.md` | 详细 10 工具工作流；可用 `#graphflow` 手动触发 |
-| `~/.config/Trae CN/User/skills/graphflow/SKILL.md` | 用户级 Skill（跨项目） |
-| `User/mcp.json` | GraphFlow MCP 服务器 |
+| `.trae/rules/graphflow.md` | `alwaysApply: true` ???????? `graphflow_context` |
+| `.trae/skills/graphflow/SKILL.md` | ?? 10 ???????? `#graphflow` ???? |
+| `~/.config/Trae CN/User/skills/graphflow/SKILL.md` | ????Skill??????|
+| `User/mcp.json` | GraphFlow MCP ????|
 
 ```bash
-# 在项目根目录执行（fat-battle/web、GraphFlow 等）
+# ?????????fat-battle/web?GraphFlow ??
 npx @roarpeng/graphflow install
-npx @roarpeng/graphflow doctor   # 检查 Trae CN rules/skill/MCP 是否就绪
+npx @roarpeng/graphflow doctor   # ???Trae CN rules/skill/MCP ????
 ```
 
-**注意**：MCP 配置中不要硬编码 `GRAPHFLOW_WORKSPACE_ROOT` 到其他项目；在 Trae 打开哪个仓库，就让 Agent 在 `graphflow_context` 里传该仓库的 `rootDir`。
+**??**?MCP ???????? `GRAPHFLOW_WORKSPACE_ROOT` ????????Trae ??????????Agent ??`graphflow_context` ?????? `rootDir`??
 
-### Antigravity IDE 推荐配置
+### Antigravity IDE ????
 
-| 路径 | 作用 |
+| ?? | ?? |
 |------|------|
-| `~/.gemini/antigravity/mcp_config.json` | 全局 MCP（`mcpServers` 键） |
-| `~/.gemini/antigravity/skills/graphflow/SKILL.md` | 全局 Skill |
-| `.agent/rules/graphflow.md` | 项目级 Rules |
-| `.agent/skills/graphflow/SKILL.md` | 项目级 Skill |
-| `GEMINI.md` | 项目级受管指令块 |
+| `~/.gemini/antigravity/mcp_config.json` | ?? MCP?`mcpServers` ?? |
+| `~/.gemini/antigravity/skills/graphflow/SKILL.md` | ?? Skill |
+| `.agent/rules/graphflow.md` | ????Rules |
+| `.agent/skills/graphflow/SKILL.md` | ????Skill |
+| `GEMINI.md` | ???????? |
 
-### Gemini CLI 推荐配置
+### Gemini CLI ????
 
-| 路径 | 作用 |
+| ?? | ?? |
 |------|------|
-| `~/.gemini/settings.json` | MCP 服务器 |
-| `~/.gemini/GEMINI.md` | 全局受管指令块 |
+| `~/.gemini/settings.json` | MCP ????|
+| `~/.gemini/GEMINI.md` | ????????|
 
-### VS Code / GitHub Copilot 推荐配置
+### VS Code / GitHub Copilot ????
 
-| 路径 | 作用 |
+| ?? | ?? |
 |------|------|
-| `~/.config/Code/User/mcp.json` | 用户级 MCP（`servers` 键） |
-| `.github/copilot-instructions.md` | 仓库级 Copilot 指令（token-first） |
-| `.vscode/mcp.json` | 可选项目级 MCP |
+| `~/.config/Code/User/mcp.json` | ????MCP?`servers` ?? |
+| `.github/copilot-instructions.md` | ????Copilot ???token-first??|
+| `.vscode/mcp.json` | ????? MCP |
 
 ```bash
-npx @roarpeng/graphflow install          # 用户级 MCP + Skills
-npx @roarpeng/graphflow install --scope all   # 含项目级 Rules / Copilot 指令
+npx @roarpeng/graphflow install          # ????MCP + Skills
+npx @roarpeng/graphflow install --scope all   # ???? Rules / Copilot ??
 npx @roarpeng/graphflow doctor
 ```
 
-支持的 Agent：Cursor、VS Code、Trae、Claude Code、Windsurf、Cline、Roo Code、Kilo Code、PearAI、Gemini、Codex、Antigravity、Amazon Q、Zed、Continue。
+????Agent?Cursor?VS Code?Trae?Claude Code?Windsurf?Cline?Roo Code?Kilo Code?PearAI?Gemini?Codex?Antigravity?Amazon Q?Zed?Continue??
 
-## 配置文件
+## ????
 
-默认：`graphflow.config.json`（也可使用 `~/.graphflow.config.json` 全局配置）。
+???`graphflow.config.json`??????`~/.graphflow.config.json` ???????
 
 ```bash
 cp graphflow.config.example.json graphflow.config.json
 ```
 
-### 全局 vs 项目配置
+### ?? vs ????
 
-| 层级 | 路径 | 适合存放 |
+| ?? | ?? | ???? |
 | --- | --- | --- |
-| 全局 | `~/.graphflow.config.json` | Provider、API Key、Smart/Economy 模型、路由策略 |
-| 项目根 | `graphflow.config.json` | 项目专属覆盖（可选） |
-| 项目覆盖 | `.graphflow/config.json` | 工作区局部覆盖（`graphflow init` 生成） |
+| ?? | `~/.graphflow.config.json` | Provider?API Key?Smart/Economy ????????|
+| ????| `graphflow.config.json` | ?????????? |
+| ???? | `.graphflow/config.json` | ????????`graphflow init` ????|
 
-**多项目重要约定**：
+**????????*??
 
-- 图谱文件默认写在**当前工作区**下的 `graphflow-out/graphflow-graph.json`
-- 全局配置**不应**包含固定的 `workspaceRoot`（旧版本若已写入，请删除该字段）
-- MCP / 脚本可通过环境变量指定工作区：`GRAPHFLOW_WORKSPACE_ROOT=/path/to/project`
+- ????????**??????*?? `graphflow-out/graphflow-graph.json`
+- ????**??**??????`workspaceRoot`????????????????
+- MCP / ???????????????`GRAPHFLOW_WORKSPACE_ROOT=/path/to/project`
 
-关键项：
+????
 
-| 配置 | 说明 |
+| ?? | ?? |
 | --- | --- |
 | `graphPolicy.transport` | `file` / `memory` / `sqlite` / `mcp-http` |
-| `graphPolicy.graphStorePath` | 相对当前工作区的 JSON 或 `.sqlite` 路径 |
-| `graphPolicy.maxContextTokens` | 压缩上下文预算（默认 **1500**） |
-| `graphPolicy.autoIndexOnSave` | 保存后增量索引（默认 **true**） |
-| `graphPolicy.autoIndexOnPreview` / `autoIndexOnRun` | preview / run 前自动索引 |
-| `graphPolicy.enableNearLosslessMode` | 近无损上下文打包 |
+| `graphPolicy.graphStorePath` | ???????? JSON ??`.sqlite` ?? |
+| `graphPolicy.maxContextTokens` | ?????????? **1500**??|
+| `graphPolicy.autoIndexOnSave` | ?????????? **true**??|
+| `graphPolicy.autoIndexOnPreview` / `autoIndexOnRun` | preview / run ??????|
+| `graphPolicy.enableNearLosslessMode` | ???????? |
 
-| `graphPolicy.layerQuota` | L1/L2/L3 锚点配额 |
-| `routingPolicy.enableDynamicRouting` | provider 健康路由 |
-| `skillPolicy.enableSkillFlywheel` | 技能飞轮 |
-| `embeddingPolicy.provider` | embedding 提供者（`transformers` 本地 / `openai`） |
+| `graphPolicy.layerQuota` | L1/L2/L3 ???? |
+| `routingPolicy.enableDynamicRouting` | provider ???? |
+| `skillPolicy.enableSkillFlywheel` | ?????|
+| `embeddingPolicy.provider` | embedding ????`transformers` ?? / `openai`??|
 
-## VS Code / Cursor 扩展
+## VS Code / Cursor ??
 
-扩展内置 GraphFlow runtime，**安装 VSIX 后无需再 clone 本仓库或配置 `npm run start`**。VSIX 仍不捆绑 `@xenova/transformers` 模型包；需要本地语义向量时可预置缓存并设置 `GRAPHFLOW_EMBEDDING_CACHE_DIR`。Installer 支持面已冻结，后续不再继续扩展新的 IDE 安装目标。
+???? GraphFlow runtime??*?? VSIX ?????clone ?????? `npm run start`**?VSIX ???? `@xenova/transformers` ????????????????????? `GRAPHFLOW_EMBEDDING_CACHE_DIR`?Installer ??????????????????IDE ??????
 
-### 安装 VSIX（推荐）
+### ?? VSIX????
 
-1. 打开 [GitHub Releases](https://github.com/Roarpeng/GraphFlow/releases)，下载最新 `graphflow-tool-<version>.vsix`（CI 在每次 push `main` / tag 后自动构建）
-2. **VS Code**：扩展视图 → `…` → **从 VSIX 安装…** → 选择下载的文件
-3. **Cursor**：扩展视图 → 右上角 `…` → **Install from VSIX** → 选择下载的文件
-4. 重启编辑器；首次激活会自动尝试安装 GraphFlow MCP 到本机 Agent 配置
-5. 命令面板运行 **GraphFlow: Show Settings** → **建立图谱（无需 LLM）** → 即可使用 Context Preview / 知识图谱
+1. ?? [GitHub Releases](https://github.com/Roarpeng/GraphFlow/releases)??????`graphflow-tool-<version>.vsix`?CI ????push `main` / tag ??????
+2. **VS Code**????????`?` ??**??VSIX ????* ??????????
+3. **Cursor**????????????`?` ??**Install from VSIX** ??????????
+4. ????????????????? GraphFlow MCP ????Agent ??
+5. ?????? **GraphFlow: Show Settings** ??**??????? LLM??* ?????? Context Preview / ????
 
-CLI 安装（若已安装 `code` / `cursor` 命令）：
+CLI ????????`code` / `cursor` ????
 
 ```bash
-code --install-extension graphflow-tool-1.7.6.vsix
-cursor --install-extension graphflow-tool-1.7.6.vsix
+code --install-extension graphflow-tool-1.7.9.vsix
+cursor --install-extension graphflow-tool-1.7.9.vsix
 ```
 
-### 命令面板
+### ????
 
-| 命令 | 说明 |
+| ?? | ?? |
 | --- | --- |
-| GraphFlow: Show Settings | 配置、建图、路由测试 |
-| GraphFlow: Show Graph | **知识图谱可视化**（分层、搜索、跳转源码） |
-| GraphFlow: Preview Context | 上下文压缩与 Token Budget |
-| GraphFlow: Plan & Brainstorm | 任务规划 |
-| GraphFlow: Run Task | 执行任务 |
-| GraphFlow: Skill Insights | 技能学习面板 |
-| GraphFlow: Install MCP | 注入 MCP 配置 |
+| GraphFlow: Show Settings | ???????????|
+| GraphFlow: Show Graph | **????????*???????????? |
+| GraphFlow: Preview Context | ?????? Token Budget |
+| GraphFlow: Plan & Brainstorm | ???? |
+| GraphFlow: Run Task | ???? |
+| GraphFlow: Skill Insights | ???????|
+| GraphFlow: Install MCP | ?? MCP ?? |
 
-Chat Agent（`@graphflow`）：`/run`、`/plan`、`/graph`、`/skills`、`/diagnose`、`/learn`、`/history`
+Chat Agent?`@graphflow`??`/run`?`/plan`?`/graph`?`/skills`?`/diagnose`?`/learn`?`/history`
 
-### Settings 推荐流程
+### Settings ????
 
-1. 填写 Graph Store Path → **Save Settings**
-2. **建立图谱（无需 LLM）** → 生成结构图谱
-3. （可选）配置 Provider → **测试路由并建立图谱**
+1. ?? Graph Store Path ??**Save Settings**
+2. **??????? LLM??* ????????
+3. ?????? Provider ??**??????????*
 
-其它建图入口：`graph index` CLI、MCP `graphflow_index`、`autoIndexOnPreview` / `autoIndexOnRun` / `autoIndexOnSave`
+???????`graph index` CLI?MCP `graphflow_index`?`autoIndexOnPreview` / `autoIndexOnRun` / `autoIndexOnSave`
 
-### 开发模式（贡献者）
+### ?????????
 
 ```bash
 cd vscode-extension
@@ -482,58 +483,58 @@ npm install
 npm run build
 ```
 
-在 VS Code 中 `F5` 启动 Extension Development Host。
+??VS Code ??`F5` ?? Extension Development Host??
 
-### 本地打包 VSIX
+### ???? VSIX
 
 ```bash
 npm run package:extension
-# 输出：artifacts/graphflow-tool-<version>.vsix
+# ???artifacts/graphflow-tool-<version>.vsix
 ```
 
-## 本地验收清单
+## ??????
 
-1. `npm run ci` 全绿
-2. `graph index` → `indexedFiles > 0`
-3. `context preview` → `summary > 0` 且 `anchors > 0`
-4. VS Code **Show Graph** → 画布正常显示节点聚类（非角落小点）
-5. `plan` / `run` 返回正常输出
-6. `route diagnose` → 显示 provider 路由状态
+1. `npm run ci` ??
+2. `graph index` ??`indexedFiles > 0`
+3. `context preview` ??`summary > 0` ??`anchors > 0`
+4. VS Code **Show Graph** ????????????????????
+5. `plan` / `run` ??????
+6. `route diagnose` ???? provider ?????
 
-## 常见问题
+## ????
 
-**切换项目后 Snapshot 显示别的仓库的图谱**
+**??????Snapshot ??????????*
 
-- 检查 `~/.graphflow.config.json` 是否含有旧的 `workspaceRoot`，**删除该字段**后重载窗口
-- 在当前项目重新「建立图谱」，确认顶栏 `store` 路径指向本项目的 `graphflow-out/`
+- ???`~/.graphflow.config.json` ?????? `workspaceRoot`??*??????*??????
+- ?????????????????? `store` ???????? `graphflow-out/`
 
-**MCP 建图失败或索引到错误目录**
+**MCP ????????????**
 
-- `graphflow_index` 传入 `rootDir: "/你的项目绝对路径"`
-- 或在 MCP 配置中加 `"env": { "GRAPHFLOW_WORKSPACE_ROOT": "/你的项目绝对路径" }`
-- 离线环境索引多语言项目时，WASM 语法包已随 `@roarpeng/graphflow` 安装包内置，无需联网下载
+- `graphflow_index` ?? `rootDir: "/????????"`
+- ?? MCP ???? `"env": { "GRAPHFLOW_WORKSPACE_ROOT": "/????????" }`
+- ?????????????WASM ??????`@roarpeng/graphflow` ????????????
 
-**`context preview` 返回 0 anchors**
+**`context preview` ?? 0 anchors**
 
-- 先执行 `graph index` 或 Settings 建图
-- 检查查询词是否命中代码符号（如 `orchestrator`、`planner`）
+- ????`graph index` ??Settings ??
+- ??????????????? `orchestrator`?`planner`??
 
-**知识图谱面板空白或只有小点**
+**??????????????*
 
-- 点击画布工具栏 **「适应」**
-- 注意：画布展示的是**采样子图**（约 120 节点），全库规模请看顶栏统计
+- ????????**?????*
+- ??????????*????**?? 120 ??????????????
 
-**API Key 未配置**
+**API Key ????*
 
-- 在 `graphflow.config.json` 配置 provider `apiKey`，支持 `${ENV_VAR}` 占位
-- **DeepSeek（推荐）**：`providers.deepseek` + `tiers.*.provider: "deepseek"`，Base URL 默认 `https://api.deepseek.com`，模型用 `deepseek-v4-pro` / `deepseek-v4-flash`（见 [DeepSeek API 文档](https://api-docs.deepseek.com/zh-cn/)）
+- ??`graphflow.config.json` ?? provider `apiKey`????`${ENV_VAR}` ??
+- **DeepSeek????**?`providers.deepseek` + `tiers.*.provider: "deepseek"`?Base URL ?? `https://api.deepseek.com`???? `deepseek-v4-pro` / `deepseek-v4-flash`?? [DeepSeek API ??](https://api-docs.deepseek.com/zh-cn/)??
 
-**无 LLM 时能用吗**
+**??LLM ????**
 
-- 可以：结构索引、图谱可视化、context preview（基于结构图谱 + transformers.js 语义向量召回）、MCP `graphflow_diagnose` 均不强制 LLM
-- 只有 Six Hats 深度规划和 LLM 语义压缩需要配置 provider
+- ??????????????context preview????????+ transformers.js ????????MCP `graphflow_diagnose` ???? LLM
+- ?? Six Hats ??????LLM ?????????provider
 
-## 项目结构
+## ????
 
 ```text
 GraphFlow/
@@ -545,13 +546,13 @@ GraphFlow/
 │   └── surfaces/
 │       ├── cli/        # CLI + runtime 子模块
 │       └── mcp/        # MCP server (10 tools)
-├── tests/              # 59 文件 / 280+ tests
+├── tests/              # 72 文件 / 357+ tests
 ├── vscode-extension/   # VS Code 面板与命令
 ├── docs/
 └── CHANGELOG.md
 ```
 
-## 版本与变更
+## ??????
 
-- 变更日志：`CHANGELOG.md`
-- License：Apache-2.0
+- ?????`CHANGELOG.md`
+- License?Apache-2.0