@roarpeng/graphflow 1.4.3 → 1.7.0

package/AGENTS.md

@@ -1,15 +1,10 @@
-# GraphFlow Agent Playbook
+# GraphFlow for Claude Code
 
-GraphFlow exposes both a CLI and an MCP server so external coding agents can call planning, orchestration, graph inspection, and context compression directly.
+Use GraphFlow as a local orchestration and context service.
 
-## Preferred entrypoints
+## Recommended setup
 
-1. Use MCP when your client supports it.
-2. Fall back to CLI with `--json` when MCP is unavailable.
-
-## MCP startup
-
-Installed package:
+Add a local MCP server entry that launches GraphFlow over stdio:
 
 ```json
 {
@@ -22,7 +17,7 @@ Installed package:
 }
 ```
 
-From this repository:
+During repository development you can also point Claude Code at this checkout:
 
 ```json
 {
@@ -36,31 +31,10 @@ From this repository:
 }
 ```
 
-## Tool selection
-
-- Use `graphflow_plan` before multi-step edits.
-- Use `graphflow_preview_context` before large refactors or codebase-wide questions.
-- Use `graphflow_run` when you want GraphFlow to plan and package a task with compressed context, returning a structured execution descriptor (executionDescriptor) for you to execute. GraphFlow delegates execution to external coding agents by default (bridge mode).
-- **Mandatory:** after executing work from a `graphflow_run` `executionDescriptor`, call `graphflow_report_outcome` with the `episodeId` from the run result, a `success` boolean, and optional `lessons`. This closes the skill flywheel loop.
-- Use `graphflow_index` after workspace changes if graph freshness matters.
-- Use `graphflow_inspect_graph` and `graphflow_skill_insights` for observability.
-- Use `graphflow_diagnose` when model/provider routing looks wrong.
-
-### No API key? Use agent-delegated LLM
-
-When no GraphFlow provider API is configured, `graphflow_plan_insight` and complex `graphflow_run` return **`agentWorkItems`**: Six Hats + plan prompts for **you** (the connected coding agent) to answer with your own model. GraphFlow still supplies heuristic plans, compressed graph context, and DAG structure — no external GraphFlow API required.
-
-After answering `agentWorkItems` prompts, call `graphflow_submit_insight` with `task`, `workItemId`, and your JSON `response` to persist each answer as a Decision node in the graph (optionally pass `episodeId` from `graphflow_run` for traceability). When all items are submitted, call `graphflow_merge_insight` to merge into a full Six Hats insight and refined DAG plan before execution.
-
-## CLI fallback
-
-Examples:
-
-```bash
-npx @roarpeng/graphflow plan "refactor planner and add tests" --json
-npx @roarpeng/graphflow context preview "orchestrator" --json
-npx @roarpeng/graphflow route diagnose --json
-npx @roarpeng/graphflow outcome report <episodeId> <success> --json
-```
+## Usage guidance
 
-Always pass `--json` when another agent or script is parsing the output.
+- Ask GraphFlow to plan before broad changes: `graphflow_plan`.
+- Ask GraphFlow to compress and anchor code context: `graphflow_context`.
+- Ask GraphFlow to inspect graph state or skill learnings when the repo history matters.
+- After executing work from a `graphflow_run` `executionDescriptor`, **must** call `graphflow_report_outcome` with the `episodeId` from the run result, a `success` boolean, and optional `lessons` to close the skill flywheel loop.
+- Fall back to `graphflow ... --json` only if MCP is not available (including `graphflow --json outcome report <episodeId> <success>`).

package/CHANGELOG.md

@@ -4,6 +4,46 @@ All notable changes to this project are documented in this file.
 
 ## [Unreleased]
 
+## [1.7.0] - 2026-07-11
+
+### Added
+
+- **P0 向量召回修正**：引入 `@xenova/transformers` + `all-MiniLM-L6-v2`（384 维，约 22MB），实现真正的本地语义 embedding 召回
+- **P2 ATP 自适应截断**：简单任务（低优先级、无约束、短描述）自动 short-circuit，跳过 First Principles / Decision Matrix / Reflection，节省 4-6 次 LLM 调用
+- **P2 MCP 工具精简**：18 个工具合并为 10 个核心工具，降低 LLM 工具调用认知负荷
+
+### Changed
+
+- **embedding provider 默认改为 `transformers`**：替代原有的 FNV-1a hash embedding（伪语义）
+- **MCP 工具合并**：
+  - `graphflow_context` = `preview_context` + `expand_anchor`
+  - `graphflow_plan` = `plan` + `plan_insight`（mode 参数区分）
+  - `graphflow_index` = `index` + `index_file` + `rebuild`
+  - `graphflow_insight` = `submit_insight` + `merge_insight`
+  - `graphflow_diagnose` = `diagnose` + `inspect_graph` + `stats`
+  - `graphflow_artifact` = `export_artifact` + `import_artifact`
+
+### Removed
+
+- **P1 移除 `hnswlib-node`**：彻底移除 C++ 编译依赖，向量召回统一使用纯线性扫描
+- 移除 `graphPolicy.enableHnsw` 配置项及相关代码
+- 移除 `hash` embedding provider 及相关函数
+
+## [1.4.4] - 2026-07-05
+
+### Added
+
+- **Antigravity IDE 安装**：MCP 写入 `~/.gemini/antigravity/mcp_config.json`；全局 Skill、项目 `.agent/rules` / `.agent/skills`；项目 `GEMINI.md` 受管块
+- **Gemini CLI**：共享 MCP 路径 `~/.gemini/config/mcp_config.json`
+- **GitHub Copilot**：专用 `.github/copilot-instructions.md` 源文件（token-first，非 CLAUDE.md 副本）
+- **Trae CN 项目安装**：`.trae/rules/graphflow.md`（alwaysApply）与项目 Skill；doctor 自检
+- **测试**：`m62-trae-cn-install`、`m63-agents-install`
+
+### Fixed
+
+- **Antigravity MCP 路径错误**：不再写入 VS Code `Code/User/mcp.json`
+- **用户级 MCP 污染**：`install` 不再向用户配置注入 `GRAPHFLOW_WORKSPACE_ROOT`；切换策略时自动清除 stale env
+
 ## [1.4.3] - 2026-07-05
 
 ### Added

package/CLAUDE.md

@@ -34,7 +34,7 @@ During repository development you can also point Claude Code at this checkout:
 ## Usage guidance
 
 - Ask GraphFlow to plan before broad changes: `graphflow_plan`.
-- Ask GraphFlow to compress and anchor code context: `graphflow_preview_context`.
+- Ask GraphFlow to compress and anchor code context: `graphflow_context`.
 - Ask GraphFlow to inspect graph state or skill learnings when the repo history matters.
 - After executing work from a `graphflow_run` `executionDescriptor`, **must** call `graphflow_report_outcome` with the `episodeId` from the run result, a `success` boolean, and optional `lessons` to close the skill flywheel loop.
 - Fall back to `graphflow ... --json` only if MCP is not available (including `graphflow --json outcome report <episodeId> <success>`).

package/README.md

@@ -31,7 +31,7 @@ npx @roarpeng/graphflow context preview "orchestrator" --json
 }
 ```
 
-接好后让 agent 优先调用 `graphflow_preview_context` 取压缩上下文；多步任务用 `graphflow_plan`。配置 provider API key 是**可选**的——只在需要 LLM 规划增强时才用。
+接好后让 agent 优先调用 `graphflow_context` 取压缩上下文；多步任务用 `graphflow_plan`。配置 provider API key 是**可选**的——只在需要 LLM 规划增强时才用。
 
 ## 为什么选 GraphFlow（与同类对比）
 
@@ -48,27 +48,62 @@ npx @roarpeng/graphflow context preview "orchestrator" --json
 
 > 实话实说：论纯图谱的成熟度与社区规模，CodeGraph 更领先；论 LSP 符号编辑标准，Serena 更专精；论整库打包，Repomix 更简单。GraphFlow 的价值在于把"图谱 + 压缩 + 规划 + 学习记忆"合到一处，让 agent 不仅省 token，还能跨会话复用项目经验。
 
-## 当前能力总览（v1.4.0+）
+## 当前能力总览（v1.7.0+）
 
 | 能力域 | 说明 |
 | --- | --- |
-| **任务规划与移交** | 按任务复杂度分流 simple / complex / insight；DAG 规划；`graphflow_plan_insight` 六顶思考帽 + 5-Why 深度分析；默认 **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（OpenAI、Anthropic、百炼、豆包） |
 | **知识图谱** | 工作区 AST 索引（TS/JS/Python/Rust/Go/C/C++/Java/Ruby/Kotlin/Swift）；File / Module / Symbol 节点 + 依赖/引用/定义/调用/继承边；图谱 artifact 导入/导出 |
-| **上下文压缩** | L1/L2/L3 分层锚点；近无损打包；图结构压缩（边权重+PageRank，零成本默认开启）；向量召回 + RRF + HNSW ANN；RepoMap 概览；自适应预算 |
-| **持续建图** | 默认 `autoIndexOnSave`；MCP 启动时自动启动 FileWatcher；preview / run 前按需增量索引；MCP `graphflow_index_file` 单文件增量 |
+| **上下文压缩** | 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_stats` 累计 token 节省；VS Code 知识图谱 Snapshot |
-| **Agent 接入** | CLI `--json`；MCP stdio（**18 工具**）；自动安装 MCP 到 15+ Agent（Cursor / Claude Code / Windsurf / Cline / Codex / Gemini 等） |
+| **可观测性** | `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；**56 测试文件 / 249+ tests**；`npm run ci` 含扩展 esbuild 打包与 bundled runtime smoke |
+| **工程质量** | TypeScript strict；**59 测试文件 / 280+ tests**；`npm run ci` 含扩展 esbuild 打包与 bundled runtime smoke |
 
 ### 一句话总结
 
 > 从 task 描述出发，自动规划 → 路由模型 → 压缩图谱上下文（含向量召回）→ **输出结构化执行描述符交给外部 coding agent**，并把经验沉淀回知识图谱；定位为 **上下文与规划服务（context service）**，而非独立执行器。
 
+### v1.7.0 核心（2026-07）
+
+**P0 向量召回修正**：废弃 FNV-1a hash embedding，引入 `@xenova/transformers` + `all-MiniLM-L6-v2`（384 维，约 22MB，纯 JS 推理），实现真正的本地语义召回。
+
+**P1 移除 hnswlib-node**：彻底移除 C++ 编译依赖，向量召回统一使用纯线性扫描（典型仓库 <10K 节点性能完全够用）。
+
+**P2 MCP 工具精简**：18 个工具合并为 10 个核心工具（context、plan、index、insight、diagnose、artifact 等合并），降低 LLM 工具调用认知负荷。
+
+**P2 ATP 自适应截断**：简单任务（低优先级、无约束、短描述）自动 short-circuit，跳过 First Principles / Decision Matrix / Reflection，节省 4-6 次 LLM 调用。
+
+---
+
+### v1.5.0 核心（2026-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 核心（2026-07）
 
 **奥卡姆剃刀精简**：移除 OpenBMB 本地部署、语义压缩模型、语义增强器、技能进化、金丝雀门控、本地嵌入模型、向量存储等未产生真实价值的模块。留下的是三条经过验证的闭环链路。
@@ -76,10 +111,9 @@ npx @roarpeng/graphflow context preview "orchestrator" --json
 **三大核心功能验证修复**：
 
 1. **HNSW 向量召回完全打通**（P0 修复）
-   - `file-indexer` 现在为所有 File/Symbol/Module 节点附加 hash embedding（零成本 FNV-1a，256 维）
+   - `file-indexer` 现在为所有 File/Symbol/Module 节点附加真正的语义 embedding（`@xenova/transformers` + `all-MiniLM-L6-v2`，384 维）
    - `orchestrator-context` 现在传递 `embeddingProvider` + `enableVectorRecall` 到压缩管道
-   - HNSW 索引持久化路径接通（`vectorStorePath` → `.hnsw` 文件）
-   - 大仓库（≥200 节点）自动使用 HNSW ANN（10-100x 提速），小仓库线性扫描
+   - 向量召回统一使用纯线性扫描，无需 C++ 编译依赖
 
 2. **FileWatcher 接入 MCP 启动**（P0 修复）
    - `startFileWatcherIfEnabled` 此前是死代码，现已接入 MCP 服务器启动路径
@@ -97,7 +131,7 @@ npx @roarpeng/graphflow context preview "orchestrator" --json
 
 ### 发布信息
 
-- 最新版本：**v1.4.3**（root + vscode-extension）；npm：`@roarpeng/graphflow@1.4.3`
+- 最新版本：**v1.7.0**（root + vscode-extension）；npm：`@roarpeng/graphflow@1.7.0`
 - **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`
@@ -107,9 +141,7 @@ npx @roarpeng/graphflow context preview "orchestrator" --json
 1. Node.js >= 20
 2. npm >= 10
 3. Windows / macOS / Linux 均可
-4. **npm 安装 `@roarpeng/graphflow` 时**：`hnswlib-node` 为**强制依赖**（HNSW 向量召回），首次安装会编译原生模块
-   - **Linux / macOS**：通常自带 C++ 工具链即可
-   - **Windows**：需安装 [Visual Studio Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/) 并勾选 **「使用 C++ 的桌面开发」**；或使用 WSL / Linux 环境安装
+4. **npm 安装 `@roarpeng/graphflow` 时**：纯 JS/TS 依赖，无原生模块编译
 
 ## 5 分钟本地试跑
 
@@ -118,7 +150,7 @@ npm install
 npm run ci
 ```
 
-预期：`lint` 无错误、`build` 成功、**249+ tests** 通过、扩展 bundle 与 runtime smoke 通过。
+预期：`lint` 无错误、`build` 成功、**280+ tests** 通过、扩展 bundle 与 runtime smoke 通过。
 
 ## Agent 工具接入
 
@@ -133,27 +165,19 @@ GraphFlow 支持两种对外接入方式：
 npm run start:mcp
 ```
 
-### MCP 工具一览（18 个）
+### MCP 工具一览（10 个）
 
 | 工具 | 用途 |
 | --- | --- |
-| `graphflow_preview_context` | 压缩任务相关上下文（**优先调用**） |
-| `graphflow_plan` | 多步任务分解与 DAG 规划 |
-| `graphflow_plan_insight` | 六顶思考帽 + 5-Why 深度分析后规划（复杂任务） |
+| `graphflow_context` | 预览压缩上下文（query）或扩展锚点（anchorId）（**优先调用**） |
+| `graphflow_plan` | 多步任务分解与 DAG 规划（mode='simple' 或 'insight'） |
 | `graphflow_run` | 规划 + 压缩上下文，输出 bridge 执行描述符 |
 | `graphflow_report_outcome` | 向 GraphFlow 汇报任务执行结果，用于学习飞轮 |
-| `graphflow_submit_insight` | 回传 `agentWorkItems` 中每条 prompt 的外部 agent 分析结果 |
-| `graphflow_merge_insight` | 合并已提交的 agent 分析为完整 Six Hats insight + DAG plan |
-| `graphflow_expand_anchor` | 扩展指定锚点的上下文详情 |
-| `graphflow_index` | 全工作区增量建图 |
-| `graphflow_index_file` | 单文件增量建图（适合 onSave / watcher） |
-| `graphflow_rebuild` | 清空缓存后全量重建 |
-| `graphflow_inspect_graph` | 图谱快照统计与样本节点 |
+| `graphflow_insight` | 提交或合并 agent 分析结果（Six Hats / plan prompts） |
+| `graphflow_index` | 全工作区增量建图、单文件建图或全量重建 |
 | `graphflow_skill_insights` | 技能学习洞察 |
-| `graphflow_diagnose` | 路由与模型健康诊断 |
-| `graphflow_export_artifact` | 导出压缩图谱 artifact |
-| `graphflow_import_artifact` | 导入图谱 artifact |
-| `graphflow_stats` | 累计 token 节省 ROI 统计 |
+| `graphflow_diagnose` | 路由健康、图谱统计与 token 节省 |
+| `graphflow_artifact` | 导出或导入压缩图谱 artifact |
 | `graphflow_skill_guide` | 获取 GraphFlow Skill 使用指南 |
 
 **MCP 建图提示**：用户级 MCP 进程的 `cwd` 不一定是当前项目。请任选其一：
@@ -215,16 +239,15 @@ GraphFlow 的压缩采用「两层渐进」策略，先用零成本图结构压
 | 层 | 机制 | 成本 | 默认 |
 | --- | --- | --- | --- |
 | 图结构压缩 | 边权重连通子图 + PageRank 中心性重排 | 零 LLM | **开启** |
-| 向量召回 | hash embedding + RRF 融合；候选 ≥200 自动用 HNSW ANN | 零 LLM | **开启** |
+| 向量召回 | transformers.js embedding + 线性扫描 + RRF 融合 | 本地模型 | **开启** |
 | RepoMap 概览 | 预算紧张时返回模块级地图 | 零 LLM | opt-in |
 | 自适应预算 | 按任务复杂度动态调整 token 预算 | 零 LLM | opt-in |
 
 **向量召回设计**：
 
-- 索引时：`file-indexer` 为每个节点生成 256 维 hash embedding（FNV-1a，零成本，无模型推理）
+- 索引时：`file-indexer` 为每个节点生成 384 维语义 embedding（`@xenova/transformers` + `all-MiniLM-L6-v2`，约 22MB，纯 JS 推理）
 - 查询时：对 query 生成同样维度的 embedding，与图中节点做 cosine similarity
-- 大仓库（≥200 候选节点）自动启用 HNSW ANN（hnswlib-node），10-100x 提速
-- 小仓库使用线性扫描，避免 HNSW 构建开销
+- 统一使用线性扫描（典型仓库 <10K 节点性能完全够用，无需 HNSW ANN）
 - 关键词检索 + 向量召回结果通过 RRF（Reciprocal Rank Fusion, k=60）融合
 
 配置示例：
@@ -232,7 +255,6 @@ GraphFlow 的压缩采用「两层渐进」策略，先用零成本图结构压
 ```json
 {
   "graphPolicy": {
-    "enableHnsw": true,
     "compression": {
       "enableGraphCompression": true,
       "enableAdaptiveBudget": true
@@ -240,7 +262,7 @@ GraphFlow 的压缩采用「两层渐进」策略，先用零成本图结构压
   },
   "embeddingPolicy": {
     "enabled": true,
-    "provider": "hash",
+    "provider": "transformers",
     "topK": 8,
     "minSimilarity": 0.05
   }
@@ -318,6 +340,56 @@ npx @roarpeng/graphflow init
 
 **本地 `npm install` 后**：若项目已有 `.cursor/mcp.json` 或 `.vscode/mcp.json`，postinstall 会自动注入 workspace 级 GraphFlow MCP 与 Skill；完整用户级安装请运行 `npx @roarpeng/graphflow install`。
 
+### Trae / Trae CN 推荐配置
+
+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 服务器 |
+
+```bash
+# 在项目根目录执行（fat-battle/web、GraphFlow 等）
+npx @roarpeng/graphflow install
+npx @roarpeng/graphflow doctor   # 检查 Trae CN rules/skill/MCP 是否就绪
+```
+
+**注意**：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 |
+
+```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。
 
 ## 配置文件
@@ -352,11 +424,11 @@ cp graphflow.config.example.json graphflow.config.json
 | `graphPolicy.autoIndexOnSave` | 保存后增量索引（默认 **true**） |
 | `graphPolicy.autoIndexOnPreview` / `autoIndexOnRun` | preview / run 前自动索引 |
 | `graphPolicy.enableNearLosslessMode` | 近无损上下文打包 |
-| `graphPolicy.enableHnsw` | HNSW ANN 加速（默认 **true**） |
+
 | `graphPolicy.layerQuota` | L1/L2/L3 锚点配额 |
 | `routingPolicy.enableDynamicRouting` | provider 健康路由 |
 | `skillPolicy.enableSkillFlywheel` | 技能飞轮 |
-| `embeddingPolicy.provider` | embedding 提供者（`hash` 零成本 / `openai`） |
+| `embeddingPolicy.provider` | embedding 提供者（`transformers` 本地 / `openai`） |
 
 ## VS Code / Cursor 扩展
 
@@ -373,9 +445,9 @@ cp graphflow.config.example.json graphflow.config.json
 CLI 安装（若已安装 `code` / `cursor` 命令）：
 
 ```bash
-code --install-extension graphflow-vscode-1.4.3.vsix
+code --install-extension graphflow-vscode-1.7.0.vsix
 # 或
-cursor --install-extension graphflow-vscode-1.4.3.vsix
+cursor --install-extension graphflow-vscode-1.7.0.vsix
 ```
 
 ### 命令面板
@@ -455,7 +527,7 @@ npm run package:extension
 
 **无 LLM 时能用吗**
 
-- 可以：结构索引、图谱可视化、context preview（基于结构图谱 + hash embedding 向量召回）、MCP `graphflow_inspect_graph` 均不强制 LLM
+- 可以：结构索引、图谱可视化、context preview（基于结构图谱 + transformers.js 语义向量召回）、MCP `graphflow_diagnose` 均不强制 LLM
 - 只有 Six Hats 深度规划和 LLM 语义压缩需要配置 provider
 
 ## 项目结构
@@ -469,8 +541,8 @@ GraphFlow/
 │   ├── learning/       # embeddings, episode, skill-flywheel, reflector, hnsw
 │   └── surfaces/
 │       ├── cli/        # CLI + runtime 子模块
-│       └── mcp/        # MCP server (18 tools)
-├── tests/              # 56 文件 / 249+ tests
+│       └── mcp/        # MCP server (10 tools)
+├── tests/              # 59 文件 / 280+ tests
 ├── vscode-extension/   # VS Code 面板与命令
 ├── docs/
 └── CHANGELOG.md

package/dist/agents/atp-schema.d.ts

@@ -0,0 +1,59 @@
+export interface IntentAnalysis {
+    explicitIntent: string;
+    implicitIntent: string;
+    coreProblem: string;
+    nonGoals: string[];
+    successDefinition: string;
+    complexity?: "simple" | "moderate" | "complex";
+}
+export interface RequirementAnalysis {
+    functional: string[];
+    nonFunctional: string[];
+    constraints: string[];
+    priority: "Low" | "Medium" | "High" | "Critical";
+    scope: {
+        included: string[];
+        excluded: string[];
+    };
+}
+export interface FirstPrinciplesAnalysis {
+    assumptions: string[];
+    facts: string[];
+    deconstructedTo: string[];
+    challenges: string[];
+}
+export interface DecisionMatrixOption {
+    name: string;
+    description: string;
+    scores: {
+        complexity: number;
+        cost: number;
+        risk: number;
+        maintainability: number;
+        impact: number;
+    };
+    pros: string[];
+    cons: string[];
+}
+export interface DecisionMatrixResult {
+    options: DecisionMatrixOption[];
+    recommendedOption: string;
+    rationale: string;
+}
+export interface PlanReflection {
+    confidence: number;
+    uncertainties: string[];
+    missingInformation: string[];
+    improvementDirections: string[];
+}
+export interface AgentThinkingProtocol {
+    task: string;
+    intent: IntentAnalysis;
+    requirements: RequirementAnalysis;
+    sixHatsInsight: import("./insight").SixHatsInsight;
+    firstPrinciples: FirstPrinciplesAnalysis;
+    decisionMatrix: DecisionMatrixResult;
+    plan: import("../core/types").TaskNode[];
+    reflection: PlanReflection;
+}
+//# sourceMappingURL=atp-schema.d.ts.map

package/dist/agents/atp-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"atp-schema.d.ts","sourceRoot":"","sources":["../../src/agents/atp-schema.ts"],"names":[],"mappings":"AACA,MAAM,WAAW,cAAc;IAC7B,cAAc,EAAE,MAAM,CAAC;IACvB,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,UAAU,CAAC,EAAE,QAAQ,GAAG,UAAU,GAAG,SAAS,CAAC;CAChD;AAGD,MAAM,WAAW,mBAAmB;IAClC,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,QAAQ,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,UAAU,CAAC;IACjD,KAAK,EAAE;QACL,QAAQ,EAAE,MAAM,EAAE,CAAC;QACnB,QAAQ,EAAE,MAAM,EAAE,CAAC;KACpB,CAAC;CACH;AAGD,MAAM,WAAW,uBAAuB;IACtC,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAGD,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE;QACN,UAAU,EAAE,MAAM,CAAC;QACnB,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;QACb,eAAe,EAAE,MAAM,CAAC;QACxB,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC;IACF,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB;AAED,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,oBAAoB,EAAE,CAAC;IAChC,iBAAiB,EAAE,MAAM,CAAC;IAC1B,SAAS,EAAE,MAAM,CAAC;CACnB;AAGD,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,kBAAkB,EAAE,MAAM,EAAE,CAAC;IAC7B,qBAAqB,EAAE,MAAM,EAAE,CAAC;CACjC;AAGD,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,cAAc,CAAC;IACvB,YAAY,EAAE,mBAAmB,CAAC;IAClC,cAAc,EAAE,OAAO,WAAW,EAAE,cAAc,CAAC;IACnD,eAAe,EAAE,uBAAuB,CAAC;IACzC,cAAc,EAAE,oBAAoB,CAAC;IACrC,IAAI,EAAE,OAAO,eAAe,EAAE,QAAQ,EAAE,CAAC;IACzC,UAAU,EAAE,cAAc,CAAC;CAC5B"}

package/dist/agents/atp-schema.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=atp-schema.js.map

package/dist/agents/atp-schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"atp-schema.js","sourceRoot":"","sources":["../../src/agents/atp-schema.ts"],"names":[],"mappings":""}

package/dist/agents/decision-engine.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Decision Engine — First Principles Analysis + Decision Matrix.
+ *
+ * These two modules form the core of ATP v1.0's analytical depth:
+ * - First Principles: strip away assumptions, decompose to fundamental
+ *   truths, and challenge every belief about the problem.
+ * - Decision Matrix: generate viable options, score them across
+ *   multiple dimensions, and recommend the best path forward.
+ *
+ * Each module has an LLM-powered version (calls executeRolePrompt) and
+ * a heuristic fallback (rule-based, no LLM dependency). The LLM version
+ * always falls back to the heuristic when the call fails or the JSON
+ * response is unparseable.
+ */
+import type { SixHatsInsight, PlanInsightOptions } from "./insight";
+import type { FirstPrinciplesAnalysis, DecisionMatrixResult } from "./atp-schema";
+/** === First Principles Analysis === */
+/**
+ * Apply first principles thinking to the task using LLM.
+ *
+ * Asks the LLM to:
+ * 1. List current assumptions (assumptions)
+ * 2. Decompose to irreducible facts (facts)
+ * 3. Identify fundamental elements (deconstructedTo)
+ * 4. Challenge each assumption (challenges)
+ *
+ * Falls back to heuristic on LLM failure or unparseable response.
+ */
+export declare function applyFirstPrinciples(task: string, insight: SixHatsInsight, options: PlanInsightOptions): Promise<FirstPrinciplesAnalysis>;
+/**
+ * Heuristic first principles analysis — no LLM calls.
+ * Derives assumptions, facts, decomposition, and challenges from
+ * the Six Hats insight using rule-based logic.
+ */
+export declare function applyFirstPrinciplesHeuristic(task: string, insight: SixHatsInsight): FirstPrinciplesAnalysis;
+/** === Decision Matrix Evaluation === */
+/**
+ * Evaluate solution options using a decision matrix with LLM.
+ *
+ * Asks the LLM to:
+ * 1. Generate 2-3 viable options based on first principles analysis
+ * 2. Score each option on complexity, cost, risk, maintainability, impact (1-10)
+ * 3. List pros and cons for each option
+ * 4. Recommend one option with rationale
+ *
+ * Falls back to heuristic on LLM failure or unparseable response.
+ */
+export declare function evaluateOptions(task: string, insight: SixHatsInsight, firstPrinciples: FirstPrinciplesAnalysis, options: PlanInsightOptions): Promise<DecisionMatrixResult>;
+/**
+ * Heuristic decision matrix evaluation — no LLM calls.
+ * Generates two standard options (Incremental vs Comprehensive)
+ * and recommends based on risk count.
+ */
+export declare function evaluateOptionsHeuristic(_task: string, insight: SixHatsInsight): DecisionMatrixResult;
+//# sourceMappingURL=decision-engine.d.ts.map

package/dist/agents/decision-engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decision-engine.d.ts","sourceRoot":"","sources":["../../src/agents/decision-engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AACpE,OAAO,KAAK,EACV,uBAAuB,EACvB,oBAAoB,EAErB,MAAM,cAAc,CAAC;AAItB,wCAAwC;AAExC;;;;;;;;;;GAUG;AACH,wBAAsB,oBAAoB,CACxC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,cAAc,EACvB,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,uBAAuB,CAAC,CA4ClC;AAED;;;;GAIG;AACH,wBAAgB,6BAA6B,CAC3C,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,cAAc,GACtB,uBAAuB,CAoBzB;AAED,yCAAyC;AAEzC;;;;;;;;;;GAUG;AACH,wBAAsB,eAAe,CACnC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,cAAc,EACvB,eAAe,EAAE,uBAAuB,EACxC,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,oBAAoB,CAAC,CAiE/B;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,cAAc,GACtB,oBAAoB,CAwBtB"}