@roarpeng/graphflow 1.7.7 → 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.7+�?
+## ???????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 导入/导出 |
-| **上下文压�?* | 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 等） |
-| **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 |
+| **模型路由** | Smart / Economy 双 tier；多 provider 健康探测与 fallback（**DeepSeek**、OpenAI、Anthropic、百炼、豆包） |
+| **知识图谱** | 工作区 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 / Opencode 等） |
+| **VS Code 扩展** | Settings、建图、路由测试、Context Preview、**知识图谱可视化**、Skill Insights、Chat Agent、一键安装 MCP |
+| **存储后端** | `file`（JSON）/ `memory` / `sqlite`（FTS5）/ `mcp-http`（Graphify） |
+| **多项目隔离** | 全局配置共享 LLM/路由；**图谱路径按当前工作区解析**，不再串读其它项目的 `graphflow-out` |
+| **工程质量** | 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 核心�?026-07�?
+### v1.7.0 ????026-07??
 
-**P0 向量召回修正**：废�?FNV-1a hash embedding，引�?`@xenova/transformers` + `all-MiniLM-L6-v2`�?84 维，�?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 工具精简**�?8 个工具合并为 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 核心�?026-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 核心�?026-07�?
+### v1.4.0 ????026-07??
 
-**奥卡姆剃刀精简**：移�?OpenBMB 本地部署、语义压缩模型、语义增强器、技能进化、金丝雀门控、本地嵌入模型、向量存储等未产生真实价值的模块。留下的是三条经过验证的闭环链路�?
+**???????**????OpenBMB ?????????????????????????????????????????????????????????????????????
 
-**三大核心功能验证修复**�?
+**??????????**??
 
-1. **HNSW 向量召回完全打�?*（P0 修复�?
-   - `file-indexer` 现在为所�?File/Symbol/Module 节点附加真正的语�?embedding（`@xenova/transformers` + `all-MiniLM-L6-v2`�?84 维）
-   - `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.7**（root + vscode-extension）；npm：`@roarpeng/graphflow@1.7.7`
-- **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.7.vsix
-cursor --install-extension graphflow-tool-1.7.7.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,76 +483,76 @@ 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/
 ├── src/
-�?  ├── core/           # 编排核心：orchestrator, triage, dag-engine, types
-�?  ├── graph/          # 索引、上下文切片、图压缩、snapshot
-�?  ├── routing/        # 模型路由与健康探测（deepseek/openai/anthropic/bailian/doubao�?
-�?  ├── learning/       # embeddings, episode, skill-flywheel, reflector, hnsw
-�?  └── surfaces/
-�?      ├── cli/        # CLI + runtime 子模�?
-�?      └── mcp/        # MCP server (10 tools)
-├── tests/              # 59 文件 / 280+ tests
-├── vscode-extension/   # VS Code 面板与命�?
+│   ├── core/           # 编排核心：orchestrator, triage, dag-engine, types
+│   ├── graph/          # 索引、上下文切片、图压缩、snapshot
+│   ├── routing/        # 模型路由与健康探测（deepseek/openai/anthropic/bailian/doubao）
+│   ├── learning/       # embeddings, episode, skill-flywheel, reflector, hnsw
+│   └── surfaces/
+│       ├── cli/        # CLI + runtime 子模块
+│       └── mcp/        # MCP server (10 tools)
+├── tests/              # 72 文件 / 357+ tests
+├── vscode-extension/   # VS Code 面板与命令
 ├── docs/
 └── CHANGELOG.md
 ```
 
-## 版本与变�?
+## ??????
 
-- 变更日志：`CHANGELOG.md`
-- License：Apache-2.0
+- ?????`CHANGELOG.md`
+- License?Apache-2.0