@roarpeng/graphflow 1.7.14 → 1.8.0

package/README.md

@@ -1,24 +1,26 @@
 # GraphFlow
 
-> **Local-first ?????? + ????????* ?????????????????????????
+[![npm version](https://img.shields.io/badge/npm-1.8.0-blue)](https://www.npmjs.com/package/@roarpeng/graphflow)
 
-GraphFlow ??????????*????????**?? agent ??????????????????????*?? + 90%+ token ??**????????? **Episodic / Skill / Decision ??**???????????????????????**????**?????????
+> **编码 Agent 的上下文与记忆层** — Local-first 代码知识图谱 + 上下文压缩 + 跨会话学习飞轮
 
-??TypeScript/Node ??????? CLI?MCP?VS Code ????????*?? API key?????**??????????+ ??????????
+GraphFlow 为 Cursor / Claude Code 等编码 Agent 提供项目级的"感知与记忆"：把仓库索引成知识图谱，将 Agent 需要的上下文压缩 **90%+ token**（基准实测 98.7%），并通过 Episodic / Skill / Decision 三类节点让 Agent **跨会话复用项目经验**。规划与执行通过 Bridge 模式委托给宿主 Agent 完成——GraphFlow 不持有 LLM 也能完整闭环。
 
-## 30 ????
+纯 TypeScript/Node 实现，CLI + MCP + VS Code 扩展三种形态，无 API key 即可离线运行。
 
-?? API key??????????????????????
+## 30 秒上手
+
+无需 API key（离线 AST 建图 + 图压缩）：
 
 ```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,529 +33,149 @@ npx @roarpeng/graphflow context preview "orchestrator" --json
 }
 ```
 
-???? agent ???? `graphflow_context` ???????????? `graphflow_plan`????provider API key ??*???*????????LLM ?????????
+Agent 先调 `graphflow_context` 拿压缩上下文，再用 `graphflow_plan` 规划；无 provider API key 时 GraphFlow 自动把 ATP 思考协议桥接给宿主 Agent 作答（agent-delegated 模式）。
 
-## ?????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 | ?????|
+| 代码图谱 | 12 语言 AST 索引 | 更成熟 | LSP 符号级 | 无 |
+| 上下文压缩 | 分层 + 图压缩 + 向量召回 | 部分 | 部分 | 整库打包 |
+| 规划协议 | ATP IR + DAG + Agent 桥接 | 无 | 无 | 无 |
+| **学习记忆** | Episodic / Skill / Decision 飞轮 | 无 | 无 | 无 |
+| Local-first | ✅ | ✅ | ✅ | ✅ |
+| 协议开放 | [ATP/IR 公开规范](docs/atp-ir-spec-v1.md) | — | — | — |
 
-> ???????????????????CodeGraph ??????LSP ???????Serena ??????????Repomix ????GraphFlow ??????"?? + ?? + ?? + ????"???????agent ????token??????????????
+> 差异化核心是**学习飞轮**：图谱索引和 token 压缩都可复制，跨会话积累的项目私有经验（技能、教训、决策）不可复制——它随使用时长增值。
 
-## ???????v1.7.14+??
+## 核心能力（v1.7.15+）
 
-| ????| ?? |
+| 模块 | 能力 |
 | --- | --- |
-| **????????* | ???????? 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/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??*??????????
-
-### v1.7.0 ????026-07??
-
-**P0 ??????**????FNV-1a hash embedding????`@xenova/transformers` + `all-MiniLM-L6-v2`??84 ????22MB?? JS ?????????????????
-
-**P1 ?? hnswlib-node**??????C++ ??????????????????????? <10K ???????????
-
-**P2 MCP ????**??8 ?????? 10 ??????context?plan?index?insight?diagnose?artifact ????????LLM ??????????
-
-**P2 ATP ?????**??????????????????????short-circuit????First Principles / Decision Matrix / Reflection????4-6 ??LLM ????
-
----
-
-### v1.5.0 ????026-07??
-
-**ATP v1.0 Agent Thinking Protocol**????????????????????????
-
-**?? 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** ???????????????????????????
-
-**ATP ?? IR**?`atp-schema.ts` ?? `AgentThinkingProtocol` ????????Multi-Agent ????????
-
-**TaskNode ??**????`priority`?`complexity`?`verification`?`inputs`?`outputs`?`risks` 6 ???????
-
-**Agent ????**?work items ????intent +requirement +first-principles +decision-matrix +reflection??submit/merge ??????
-
-**????**?`planInsight(task, options)` ????????????`runFullAtp=true` ???? ATP 8 ????
-
-**P0 ????**????VS Code ????????runtime ??????`enrichGraph`/`downloadModel`/`showSetupGuide` ?? + `/enrich` ???????? 87 ??OpenBMB/enrichment ????????`canaryAllowed`/`canaryReason` ??5 ??enrichment ??????
-
-### v1.4.0 ????026-07??
-
-**???????**????OpenBMB ?????????????????????????????????????????????????????????????????????
-
-**??????????**??
-
-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` ??????????????
-
-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.7.14**?root + vscode-extension??npm?`@roarpeng/graphflow@1.7.14`
-- **GitHub Release**?push ??`main` ??CI ??`windows-2022` ??????VSIX ???? [GitHub Releases](https://github.com/Roarpeng/GraphFlow/releases)
-- **Open VSX**：`main` / `v*` Build 成功后自动幂等发布到 [Open VSX](https://open-vsx.org/extension/roarpeng/graphflow-tool)（密钥 `open_vsx_token`，namespace `roarpeng`，与 `package.json` publisher 一致；版本已存在则跳过）
-- **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 ??????????
-
-## 5 ??????
-
-```bash
-npm install
-npm run ci
-```
-
-预期：`lint` 无错误、`build` 成功、**357+ tests** 通过、扩展 bundle 与 runtime smoke 通过。
-
-## Agent ????
-
-GraphFlow ????????????
-
-1. **CLI ????**???????? `--json`
-2. **MCP stdio server**?Cursor?Claude Code ??????
-
-??????MCP??
-
-```bash
-npm run start:mcp
-```
-
-### MCP ?????10 ??
-
-| ?? | ???|
+| **规划协议** | ATP v1.1（Intent / Requirement / Six Hats / 5-Why / First Principles / Decision Matrix / Planning / Reflection）；simple / complex / insight 三种模式；无 LLM 时 agent-delegated 桥接；[ATP/IR 公开规范 v1.1](docs/atp-ir-spec-v1.md) |
+| **目标对齐** | **Goal 锚点节点化**（intent 五元组固化为一等公民，每次打包自动注入原始需求）；**低置信度澄清门**（confidence < 0.6 不出 plan）；**alignment-check 执行期回检**；**deviation 偏离分类**（misread-requirement / scope-creep / tech-drift）；**Goal 版本链 + 变更 diff** |
+| **知识图谱** | 12 语言 AST 索引（TS/JS/Python/Rust/Go/C/C++/Java/Ruby/Kotlin/Swift/Dart）；File / Module / Symbol 节点 + 依赖/引用/定义/调用/继承边 |
+| **上下文压缩** | L1/L2/L3 分层锚点；图结构压缩（边权重 + PageRank，**LRU 缓存**）；**词干匹配召回**（orchestrate ↔ orchestration）；向量召回 + RRF；RepoMap 概览；自适应预算 |
+| **检索质量** | **Golden-set 回归门禁**（26 查询，CI 强制 ≥80% 召回，实测 100%） |
+| **向量索引** | 进程内记忆化 + **磁盘持久化**（指纹校验，MCP 重启秒级恢复） |
+| **存储后端** | `file` / `memory` / `sqlite`（FTS5，**searchtext 分词增强**，camelCase 可检索）/ **`auto`（sqlite 优先自动切换）** / `mcp-http` |
+| **学习飞轮** | Episodic Memory、Reflection、Skill 节点（score ±1，bounded [-20,20]）、nightly 学习、技能衰减/剪枝、**飞轮贡献报告**（`skill report` / `graphflow_diagnose`，含偏离聚合与 Goal 统计） |
+| **团队共享** | **`skill sync`**：技能包导出/导入到可提交的 `.graphflow/skills/team-skills.json` |
+| **效果基准** | [token 节省 98.7%](benchmarks/RESULTS.md)（独立复核）；[Skill A/B 基准](benchmarks/SKILL-AB-RESULTS.md)（注入率/召回率/开销，`npm run benchmark:skills`） |
+| **模型路由** | Smart / Economy 双 tier；多 provider 健康探测与 fallback（DeepSeek、OpenAI、Anthropic、百炼、豆包） |
+| **可观测性** | `graphflow_diagnose`：provider 健康 + 图统计 + token 节省 + **飞轮报告** |
+| **Agent 接入** | CLI `--json`；MCP stdio（10 工具）；自动安装 MCP 到 15+ Agent |
+| **工程质量** | TypeScript strict；**92 测试文件 / 455 tests**；`npm run ci` 含扩展打包与 smoke |
+
+### 定位说明
+
+> GraphFlow **不是编排执行器**——它是编码 Agent 的**上下文与记忆层**。任务执行通过 Bridge 模式交给宿主 coding agent（诚实语义，不伪造 COMPLETED）；GraphFlow 负责让它"看得准、记得住"。
+
+## 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 ???? |
-
-**MCP ????**???? MCP ????`cwd` ????????????????
-
-- ?? `graphflow_index` ????`rootDir`????????
-- ??MCP ??????`GRAPHFLOW_WORKSPACE_ROOT` ????
-- ?? VS Code ?????????????`.cursor/mcp.json`
-
-CLI ????
-
-```bash
-npm run start -- plan "refactor planner and add tests" --json
-npm run start -- context preview "orchestrator" --json
-npm run start -- graph inspect --json
-```
-
-?? agent ?????`AGENTS.md`?`CLAUDE.md`?`.cursor/rules/graphflow.mdc`
-
-## ???????CLI??
-
-### ????
-
-```bash
-npm run start -- graph index .
-```
-
-???`indexedFiles=?? indexedSymbols=?`
-
-### ????????
+| `graphflow_context` | 压缩上下文包（query → 锚点 + 摘要；anchorId → 展开） |
+| `graphflow_plan` | 任务规划（mode='simple' 或 'insight'；无 LLM 时 agent-delegated） |
+| `graphflow_run` | 编排 + Bridge 执行描述符 |
+| `graphflow_report_outcome` | 结果回填（含 deviation 偏离分类），闭环学习飞轮 |
+| `graphflow_insight` | ATP 洞察 submit / merge（Agent 桥接协议） |
+| `graphflow_index` | 增量 / 全量索引 |
+| `graphflow_skill_insights` | 技能洞察 |
+| `graphflow_diagnose` | 诊断（provider + 图 + token 节省 + 飞轮） |
+| `graphflow_artifact` | 图谱 artifact 导入 / 导出 |
+| `graphflow_skill_guide` | GraphFlow Skill 使用指南 |
 
-```bash
-npm run start -- context preview "orchestrator"
-```
-
-???`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"
-```
+**MCP 工作区解析**：自动从 MCP 客户端 `cwd` 发现工作区；也可用 `GRAPHFLOW_WORKSPACE_ROOT` 显式指定。
 
-### ???? / ?? / ??
+## CLI 速查
 
 ```bash
-npm run start -- route diagnose
-npm run start -- learn nightly
-npm run start -- graph inspect
-npm run start -- skill insights
+graphflow graph index .                    # 建图
+graphflow context preview "orchestrator"   # 上下文预览
+graphflow plan "refactor planner" --json   # 规划
+graphflow run "update readme"              # 编排（Bridge）
+graphflow skill insights                   # 技能洞察
+graphflow skill report                     # 飞轮贡献报告
+graphflow skill sync export                # 导出团队技能包（git 共享）
+graphflow skill sync import                # 导入团队技能包
+graphflow route diagnose                   # 路由诊断
+graphflow learn nightly                    # 夜间学习
+graphflow doctor                           # 安装自检
 ```
 
-## ????
-
-### ??????
-
-GraphFlow ??????????????????????????????????????????????
-
-| ??| ?? | ?? | ?? |
-| --- | --- | --- | --- |
-| ??????| ????????+ 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????
-
-??????
-
-```json
-{
-  "graphPolicy": {
-    "compression": {
-      "enableGraphCompression": true,
-      "enableAdaptiveBudget": true
-    }
-  },
-  "embeddingPolicy": {
-    "enabled": true,
-    "provider": "transformers",
-    "modelCacheDir": "/path/to/preseeded/transformers-cache",
-    "topK": 8,
-    "minSimilarity": 0.05
-  }
-}
-```
+## 配置
 
-?????????? `@xenova/transformers` ???????? `embeddingPolicy.modelCacheDir` ??????`GRAPHFLOW_EMBEDDING_CACHE_DIR` ???????
+三层合并：全局 `~/.graphflow.config.json` → 项目 `graphflow.config.json` → 项目 `.graphflow/config.json`。复制 [graphflow.config.example.json](graphflow.config.example.json) 起步。
 
-????????????
+关键项：
 
-```bash
-npm run start -- route diagnose
-```
-
-### SQLite / FTS5 ??
-
-```json
-{
-  "graphPolicy": {
-    "transport": "sqlite",
-    "graphStorePath": "tmp/graphflow-graph.sqlite",
-    "maxContextTokens": 1500
-  }
-}
-```
-
-WAL + FTS5 ?????? `file` / `memory` ??????
-
-### Episodic Memory + Reflection
-
-```ts
-const run = await orchestrate(
-  { task: "refactor planner module and add tests" },
-  { graphClient, enableEpisodicMemory: true, enableGraphContextInPrompt: true }
-);
-```
-
-?? 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 ??
-
-### ??? AST ??
-
-| ?? | ?? |
+| 配置 | 说明 |
 | --- | --- |
-| TypeScript / JavaScript | `.ts .tsx .js .jsx` |
-| Python | `.py` |
-| Rust | `.rs` |
-| Go | `.go` |
-| C / C++ | `.c .h .cc .cpp .cxx .hpp .hxx` |
-| Java | `.java` |
-| Ruby | `.rb` |
-| Kotlin | `.kt` |
-| Swift | `.swift` |
-| Dart | `.dart` |
-
-?? `graphPolicy.includeExtensions` ???????tree-sitter WASM ???? `npm run build` ????`wasm/` ?? npm ???????????????
-
-### Agent MCP ????
+| `graphPolicy.transport` | `file` / `memory` / `sqlite` / **`auto`（推荐：sqlite 优先，不可用自动降级 file）** / `mcp-http` |
+| `graphPolicy.maxContextTokens` | 上下文预算（默认 1500） |
+| `graphPolicy.autoIndexOnSave` | 保存时自动增量索引（默认 true） |
+| `embeddingPolicy.provider` | `transformers`（本地默认）/ `openai` / `hash` |
+| `embeddingPolicy.vectorStorePath` | 向量索引持久化路径（自动派生 `.hnsw`） |
+| `skillPolicy.enableSkillFlywheel` | 学习飞轮开关 |
 
-GraphFlow CLI ???????? MCP ????15+ ?? Agent??
+## 基准
 
-```bash
-# ???????Agent ??MCP ?????
-npx @roarpeng/graphflow doctor
-
-# ?????MCP + Skill + Cursor Rules????
-npx @roarpeng/graphflow install
+- **Token 节省**：[benchmarks/RESULTS.md](benchmarks/RESULTS.md) — 8 个代表性查询，230,069 → 2,893 tokens（**98.7%**），独立 gpt-tokenizer 复核，`npm run benchmark` 可复现。
+- **Skill 飞轮 A/B**：[benchmarks/SKILL-AB-RESULTS.md](benchmarks/SKILL-AB-RESULTS.md) — 注入率 100%、episode 召回 100%、平均开销 25.6 tokens/任务，`npm run benchmark:skills` 可复现。
+- **检索召回**：golden set（26 查询）纳入 CI 回归门禁，防止压缩/排序改动悄悄劣化召回。
 
-# ????????????graphflow/config.json ??
-npx @roarpeng/graphflow init
-```
+## VS Code / Cursor 扩展
 
-**?? `npm install` ??*?????? `.cursor/mcp.json` ??`.vscode/mcp.json`?postinstall ??????workspace ??GraphFlow MCP ??Skill????????????`npx @roarpeng/graphflow install`??
+从 [GitHub Releases](https://github.com/Roarpeng/GraphFlow/releases) 下载 `graphflow-tool-<version>.vsix` 安装（或 Open VSX：`roarpeng.graphflow-tool`）。
 
-### Trae / Trae CN ????
+命令：Settings / Show Graph（图谱可视化）/ Preview Context / Plan & Brainstorm / Run Task / Skill Insights / Install MCP；Chat Agent `@graphflow`（`/run` `/plan` `/graph` `/skills` `/diagnose` `/learn` `/history`）。
 
-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 ????|
+## Agent 集成
 
 ```bash
-# ?????????fat-battle/web?GraphFlow ??
-npx @roarpeng/graphflow install
-npx @roarpeng/graphflow doctor   # ???Trae CN rules/skill/MCP ????
+npx @roarpeng/graphflow doctor     # 检测已安装的 Agent
+npx @roarpeng/graphflow install    # 自动安装 MCP + Skill + Rules
+npx @roarpeng/graphflow init       # 写入最小项目配置
 ```
 
-**??**?MCP ???????? `GRAPHFLOW_WORKSPACE_ROOT` ????????Trae ??????????Agent ??`graphflow_context` ?????? `rootDir`??
-
-### 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 CLI ????
-
-| ?? | ?? |
-|------|------|
-| `~/.gemini/settings.json` | MCP ????|
-| `~/.gemini/GEMINI.md` | ????????|
-
-### VS Code / GitHub Copilot ????
-
-| ?? | ?? |
-|------|------|
-| `~/.config/Code/User/mcp.json` | ????MCP?`servers` ?? |
-| `.github/copilot-instructions.md` | ????Copilot ???token-first??|
-| `.vscode/mcp.json` | ????? MCP |
+支持：Cursor、VS Code、Trae（含 CN）、Claude Code、Windsurf、Cline、Roo Code、Kilo Code、Gemini CLI、Codex、Antigravity、Opencode、Qoder、Amazon Q、Zed、Continue 等 15+。
 
-```bash
-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??
+## 协议
 
-## ????
+[ATP/IR — Agent Thinking Protocol 公开规范 v1.0](docs/atp-ir-spec-v1.md)：work-item 注册表、submit/merge 契约、兼容性规则。第三方工具可实现兼容的 producer / consumer。
 
-???`graphflow.config.json`??????`~/.graphflow.config.json` ???????
+## 开发
 
 ```bash
-cp graphflow.config.example.json graphflow.config.json
-```
-
-### ?? vs ????
-
-| ?? | ?? | ???? |
-| --- | --- | --- |
-| ?? | `~/.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`
-
-????
-
-| ?? | ?? |
-| --- | --- |
-| `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.layerQuota` | L1/L2/L3 ???? |
-| `routingPolicy.enableDynamicRouting` | provider ???? |
-| `skillPolicy.enableSkillFlywheel` | ?????|
-| `embeddingPolicy.provider` | embedding ????`transformers` ?? / `openai`??|
-
-## VS Code / Cursor ??
-
-???? GraphFlow runtime??*?? VSIX ?????clone ?????? `npm run start`**?VSIX ???? `@xenova/transformers` ????????????????????? `GRAPHFLOW_EMBEDDING_CACHE_DIR`?Installer ??????????????????IDE ??????
-
-### ?? 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 / ????
-
-CLI ????????`code` / `cursor` ????
-
-```bash
-code --install-extension graphflow-tool-1.7.14.vsix
-cursor --install-extension graphflow-tool-1.7.14.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 ?? |
-
-Chat Agent?`@graphflow`??`/run`?`/plan`?`/graph`?`/skills`?`/diagnose`?`/learn`?`/history`
-
-### Settings ????
-
-1. ?? Graph Store Path ??**Save Settings**
-2. **??????? LLM??* ????????
-3. ?????? Provider ??**??????????*
-
-???????`graph index` CLI?MCP `graphflow_index`?`autoIndexOnPreview` / `autoIndexOnRun` / `autoIndexOnSave`
-
-### ?????????
-
-```bash
-cd vscode-extension
 npm install
-npm run build
+npm run ci        # lint + build + 测试 + 扩展打包 + smoke
 ```
 
-??VS Code ??`F5` ?? Extension Development Host??
-
-### ???? VSIX
-
-```bash
-npm run package:extension
-# ???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 ?????
-
-## ????
-
-**??????Snapshot ??????????*
-
-- ???`~/.graphflow.config.json` ?????? `workspaceRoot`??*??????*??????
-- ?????????????????? `store` ???????? `graphflow-out/`
-
-**MCP ????????????**
-
-- `graphflow_index` ?? `rootDir: "/????????"`
-- ?? MCP ???? `"env": { "GRAPHFLOW_WORKSPACE_ROOT": "/????????" }`
-- ?????????????WASM ??????`@roarpeng/graphflow` ????????????
-
-**`context preview` ?? 0 anchors**
-
-- ????`graph index` ??Settings ??
-- ??????????????? `orchestrator`?`planner`??
-
-**??????????????*
-
-- ????????**?????*
-- ??????????*????**?? 120 ??????????????
-
-**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/)??
-
-**??LLM ????**
-
-- ??????????????context preview????????+ transformers.js ????????MCP `graphflow_diagnose` ???? LLM
-- ?? Six Hats ??????LLM ?????????provider
+要求 Node.js ≥ 20、npm ≥ 10。预期：lint 无错误、构建成功、455 测试通过。
 
-## ????
+## 项目结构
 
 ```text
 GraphFlow/
 ├── src/
-│   ├── core/           # 编排核心：orchestrator, triage, dag-engine, types
-│   ├── graph/          # 索引、上下文切片、图压缩、snapshot
-│   ├── routing/        # 模型路由与健康探测（deepseek/openai/anthropic/bailian/doubao）
-│   ├── learning/       # embeddings, episode, skill-flywheel, reflector, hnsw
+│   ├── core/           # 编排核心：orchestrator, triage, dag-engine, agent-delegation
+│   ├── graph/          # 索引、上下文切片、图压缩、sqlite/auto 存储、snapshot
+│   ├── routing/        # 模型路由与健康探测（5 provider）
+│   ├── learning/       # embeddings, episodic, skill-flywheel, hnsw, nightly
+│   ├── agents/         # ATP schema, planner, insight, brainstormer
 │   └── surfaces/
-│       ├── cli/        # CLI + runtime 子模块
-│       └── mcp/        # MCP server (10 tools)
-├── tests/              # 72 文件 / 357+ tests
+│       ├── cli/        # CLI + runtime
+│       └── mcp/        # MCP server（10 工具）
+├── tests/              # 92 文件 / 455 tests（含检索 golden set、goal anchor）
+├── benchmarks/         # token 节省 + skill A/B 基准（可复现）
+├── docs/               # ATP v1.0 设计 + ATP/IR 公开规范
 ├── vscode-extension/   # VS Code 面板与命令
-├── docs/
 └── CHANGELOG.md
 ```
 
-## ??????
+## 历史变更
 
-- ?????`CHANGELOG.md`
-- License?Apache-2.0
+详细记录见 [CHANGELOG.md](CHANGELOG.md)。License：Apache-2.0。