@roarpeng/graphflow 1.0.0 → 1.0.4

package/CHANGELOG.md

@@ -4,6 +4,32 @@ All notable changes to this project are documented in this file.
 
 ## [Unreleased]
 
+## [1.0.3] - 2026-06-24
+
+### Fixed
+
+- **CI**：`m17` 测试不再硬编码 `/usr/bin/node`，兼容 GitHub Actions hosted Node 路径。
+- **图谱存储**：`graphify-file-client` 原子写入（temp + rename）；损坏 JSON 时优雅降级为空 store 并提示 rebuild。
+- **上下文检索**：`rankNodesForContextQuery` 降低 `.cursor/mcp.json`、`docs/integrations` 等配置噪声，优先 `src/` 与 Symbol 节点。
+- **MCP metrics**：`graphflow_metrics` 支持 `rootDir` 并绑定工作区。
+
+## [1.0.2] - 2026-06-24
+
+### Fixed
+
+- **MCP ENOENT（fnm 临时路径）**：安装 MCP 时不再写入 fnm multishell 临时 `node` 绝对路径；优先使用 IDE 自带 Electron（`ELECTRON_RUN_AS_NODE`），否则回退稳定 `node`。
+- **Trae CN 支持**：安装器识别 `~/.trae-cn` 并写入 `~/.config/Trae CN/User/mcp.json`。
+
+## [1.0.1] - 2026-06-24
+
+### Fixed
+
+- **多项目工作区隔离**：MCP / 扩展 / npm 包不再把图谱绑定到 vendor 目录或全局配置里的陈旧 `workspaceRoot`。
+- **自动发现工作区**：新增 `discover-workspace`，从 cwd 向上查找项目根；仅在 runtime 目录（vendor、extensions）时回退到 IDE 环境变量。
+- **MCP launcher**：子进程 `cwd` 与 `GRAPHFLOW_WORKSPACE_ROOT` 指向用户打开的项目，不再固定在扩展 vendor。
+- **MCP 安装器**：默认写入 `GRAPHFLOW_WORKSPACE_ROOT: "${workspaceFolder}"`，merge 已有 env，扩展有工作区时同时写用户级与项目级配置。
+- **MCP 工具**：`preview_context`、`inspect_graph`、`skill_insights`、`stats` 支持可选 `rootDir` 覆盖。
+
 ## [1.0.0] - 2026-06-19
 
 首个正式版本。在 0.6.x 基础上完成「诚实执行语义」收敛与「上下文压缩」体系，所有新增能力均端到端接线到 CLI / MCP / orchestrator。

package/README.md

@@ -4,54 +4,70 @@ A Context-Aware Multi-Agent Orchestration Engine.
 
 GraphFlow 是一个基于 TypeScript/Node.js 的多智能体编排引擎，将 **Graphify 式知识图谱** 与 **Superpowers 式任务编排** 整合为可本地运行的上下文层：自动建图、压缩检索、规划执行、经验沉淀，并通过 CLI、MCP 与 VS Code 扩展对外暴露。
 
-## 当前能力总览（v1.0.0）
+## 当前能力总览（v1.0.0+）
 
 | 能力域 | 说明 |
 | --- | --- |
-| **任务规划与移交** | 按任务复杂度分流 simple / complex；DAG 规划；默认 **bridge 模式**输出结构化任务描述符交给外部 coding agent 执行 |
+| **任务规划与移交** | 按任务复杂度分流 simple / complex；DAG 规划；`graphflow_plan_insight` 六顶思考帽 + 5-Why 深度分析；默认 **bridge 模式**输出结构化任务描述符交给外部 coding agent 执行 |
 | **模型路由** | Smart / Economy 双 tier；多 provider 健康探测与 fallback（OpenAI、Anthropic、百炼、豆包、OpenBMB） |
-| **知识图谱** | 工作区 AST 索引（TS/JS/Python/Rust/Go/C/C++）；File / Module / Symbol 节点 + 依赖/引用/定义边 |
+| **知识图谱** | 工作区 AST 索引（TS/JS/Python/Rust/Go/C/C++/Java/Ruby）；File / Module / Symbol 节点 + 依赖/引用/定义边；图谱 artifact 导入/导出 |
 | **上下文压缩** | L1/L2/L3 分层锚点；近无损打包；图结构压缩（边权重+PageRank，零成本默认开启）；可选语义压缩（minicpm/economy LLM 聚类合并）；向量召回 + RRF + HNSW；RepoMap 概览；自适应预算 |
-| **持续建图** | 默认 `autoIndexOnSave`；preview / run 前按需增量索引（`hasPendingGraphIndexWork`） |
+| **持续建图** | 默认 `autoIndexOnSave`；preview / run 前按需增量索引（`hasPendingGraphIndexWork`）；MCP `graphflow_index_file` 单文件增量 |
 | **语义增强** | 可选 post-index LLM 语义 enrich；OpenBMB 本地 embedded 模式 |
 | **学习飞轮** | Episodic Memory、Reflection、Skill 节点、nightly 学习、技能提示注入规划 |
-| **Agent 接入** | CLI `--json`；MCP stdio（9 工具）；Cursor / Claude Code 规则与示例配置 |
-| **VS Code 扩展** | Settings、建图、路由测试、Context Preview、**知识图谱可视化**、Skill Insights、Chat Agent |
+| **可观测性** | `graphflow_stats` 累计 token 节省；`graphflow_metrics` Prometheus 指标；VS Code 知识图谱 Snapshot |
+| **Agent 接入** | CLI `--json`；MCP stdio（**16 工具**）；Cursor / Claude Code 规则与示例配置 |
+| **VS Code 扩展** | Settings、建图、路由测试、Context Preview、**知识图谱可视化**、Skill Insights、Chat Agent、一键安装 MCP |
 | **存储后端** | `file`（JSON）/ `memory` / `sqlite`（FTS5）/ `mcp-http`（Graphify） |
-| **工程质量** | TypeScript strict；**45 测试文件 / 200+ tests**；`npm run ci` 含扩展 esbuild 打包与 bundled runtime smoke |
+| **多项目隔离** | 全局配置共享 LLM/路由；**图谱路径按当前工作区解析**，不再串读其它项目的 `graphflow-out` |
+| **工程质量** | TypeScript strict；**49 测试文件 / 200+ tests**；`npm run ci` 含扩展 esbuild 打包与 bundled runtime smoke |
 
 ### 一句话总结
 
 > 从 task 描述出发，自动规划 → 路由模型 → 压缩图谱上下文（含向量召回）→ **输出结构化执行描述符交给外部 coding agent**，并把经验沉淀回知识图谱；定位为 **上下文与规划服务（context service）**，而非独立执行器。
 
-### v0.6.7 – v0.6.13 近期演进
+### v1.0.0 核心（2026-06）
 
-1. **知识图谱可视化（v0.6.12–0.6.13）**
-   - 可读标签（文件名、符号名、目录组）、代码层 / 学习层 Tab
-   - 暗色面板、目录聚类着色、关系线型、缩放/平移
-   - 双击节点或「打开源文件」跳转源码行
-   - 布局归一化修复大图谱「只剩角落小点」问题
+- **诚实执行语义（bridge 模式）**：`graphflow_run` 规划 + 压缩上下文后输出 `executionDescriptor`，交给 Cursor / Claude Code 等外部 agent 执行，不再伪造 `COMPLETED`。
+- **三层渐进压缩**：图结构压缩（默认零成本）→ 向量召回 + HNSW → 可选语义压缩（economy / minicpm）。
+- **混合压缩模型**：`compressor` 角色默认继承 economy tier；纯离线时首次按需下载 minicpm GGUF。
 
-2. **持续静默建图（v0.6.11）**
-   - `autoIndexOnSave` 默认开启；保存文件后 debounce 增量索引
-   - 旧配置 `maxContextTokens: 400` 自动升级到 1500
+### 最新更新（v1.0.x / main）
 
-3. **Runtime 模块化与扩展打包（v0.6.10）**
-   - `runtime/` 子模块 + `GraphFlowRuntimeModule` 类型校验
-   - VS Code 扩展 esbuild 单文件 bundle
+1. **多项目图谱隔离**
+   - 全局配置（`~/.graphflow.config.json`）只保存 LLM、路由等**机器级**设置，**不再持久化 `workspaceRoot`**
+   - 运行时按 `process.cwd()` 或 `GRAPHFLOW_WORKSPACE_ROOT` 解析 `graphflow-out/graphflow-graph.json`
+   - 修复：切换项目后 Snapshot / MCP 仍显示旧项目图谱的问题
 
-4. **配置与健壮性（v0.6.7–0.6.9）**
-   - 全局配置优先（`~/.graphflow.config.json`）
-   - 损坏 JSON 容错；postinstall 需显式 `GRAPHFLOW_ENABLE_POSTINSTALL=1`
-   - 无工作区也可打开 Settings；CI 可复现 `npm ci`
+2. **索引与语言扩展**
+   - 新增 **Java**（`.java`）、**Ruby**（`.rb`）tree-sitter 索引器
+   - C/C++、Rust 索引器增强；WASM 语法包可随 npm 包离线分发（`npm run wasm:download`）
+   - MCP 新增 `graphflow_index_file` 单文件增量索引
 
-5. **无 LLM 也能建图（v0.6.6 起）**
+3. **MCP 工具扩展（9 → 16）**
+   - `graphflow_plan_insight`：六顶思考帽 + 5-Why 深度规划
+   - `graphflow_export_artifact` / `graphflow_import_artifact`：图谱压缩包导入导出
+   - `graphflow_stats`：累计 token 节省统计
+   - `graphflow_metrics`：Prometheus 格式可观测性指标
+
+4. **知识图谱可视化（延续 v0.6.12+）**
+   - 可读标签、代码层/学习层 Tab、目录聚类、缩放平移、跳转源码
+   - Snapshot 为**采样视图**（默认约 120 节点 / 200 边），顶栏显示全库真实规模
+
+5. **配置与工程**
+   - 全局配置优先；损坏 JSON 容错；CI 全链路 validate + VSIX 打包
    - Settings「建立图谱（无需 LLM）」或 `graph index` 即可生成结构图谱
-   - 可选「测试路由并建立图谱」在 LLM 连通后触发语义 enrich
+
+### 历史演进（v0.6.7 – v0.6.13 摘要）
+
+- v0.6.12–0.6.13：知识图谱面板、布局归一化、Snapshot 可读标签
+- v0.6.11：`autoIndexOnSave` 默认开启；`maxContextTokens` 400 → 1500 自动升级
+- v0.6.10：runtime 模块化、VS Code esbuild bundle
+- v0.6.7–0.6.9：全局配置脚手架、无工作区也可打开 Settings
 
 ### 发布信息
 
-- 最新版本：**v1.0.0**（root + vscode-extension）；npm：`@roarpeng/graphflow@1.0.0`
+- 最新版本：**v1.0.4**（root + vscode-extension）；npm：`@roarpeng/graphflow@1.0.4`
 - **GitHub Release**：push 到 `main` 且 CI 通过后自动发布 VSIX（见 [Actions](https://github.com/Roarpeng/GraphFlow/actions)）
 - 变更日志：`CHANGELOG.md`
 
@@ -83,19 +99,32 @@ GraphFlow 支持两种对外接入方式：
 npm run start:mcp
 ```
 
-### MCP 工具一览
+### MCP 工具一览（16 个）
 
 | 工具 | 用途 |
 | --- | --- |
-| `graphflow_preview_context` | 压缩任务相关上下文（优先调用） |
-| `graphflow_plan` | 多步任务分解 |
-| `graphflow_run` | 执行编排循环 |
-| `graphflow_index` / `graphflow_rebuild` | 增量 / 全量建图 |
-| `graphflow_inspect_graph` | 图谱快照与统计 |
-| `graphflow_enrich_graph` | 语义增强 |
+| `graphflow_preview_context` | 压缩任务相关上下文（**优先调用**） |
+| `graphflow_plan` | 多步任务分解与 DAG 规划 |
+| `graphflow_plan_insight` | 六顶思考帽 + 5-Why 深度分析后规划（复杂任务） |
+| `graphflow_run` | 规划 + 压缩上下文，输出 bridge 执行描述符 |
+| `graphflow_index` | 全工作区增量建图 |
+| `graphflow_index_file` | 单文件增量建图（适合 onSave / watcher） |
+| `graphflow_rebuild` | 清空缓存后全量重建 |
+| `graphflow_inspect_graph` | 图谱快照统计与样本节点 |
+| `graphflow_enrich_graph` | 符号节点语义增强 |
 | `graphflow_skill_insights` | 技能学习洞察 |
-| `graphflow_diagnose` | 路由健康诊断 |
-| `graphflow_model_download` | OpenBMB 模型下载 |
+| `graphflow_diagnose` | 路由与压缩模型健康诊断 |
+| `graphflow_model_download` | OpenBMB / minicpm 模型下载 |
+| `graphflow_export_artifact` | 导出压缩图谱 artifact |
+| `graphflow_import_artifact` | 导入图谱 artifact |
+| `graphflow_stats` | 累计 token 节省 ROI 统计 |
+| `graphflow_metrics` | Prometheus 格式运行指标 |
+
+**MCP 建图提示**：用户级 MCP 进程的 `cwd` 不一定是当前项目。请任选其一：
+
+- 调用 `graphflow_index` 时传入 `rootDir`（项目绝对路径）
+- 在 MCP 配置中设置 `GRAPHFLOW_WORKSPACE_ROOT` 环境变量
+- 使用 VS Code 扩展「建立图谱」或项目级 `.cursor/mcp.json`
 
 CLI 示例：
 
@@ -237,8 +266,10 @@ const run = await orchestrate(
 | Rust | `.rs` |
 | Go | `.go` |
 | C / C++ | `.c .h .cc .cpp .cxx .hpp .hxx` |
+| Java | `.java` |
+| Ruby | `.rb` |
 
-通过 `graphPolicy.includeExtensions` 限制扫描范围。
+通过 `graphPolicy.includeExtensions` 限制扫描范围。tree-sitter WASM 语法包随 npm 包分发；开发/发布前可执行 `npm run wasm:download` 预下载到 `wasm/`。
 
 ## 配置文件
 
@@ -248,12 +279,26 @@ const run = await orchestrate(
 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.graphStorePath` | 相对当前工作区的 JSON 或 `.sqlite` 路径 |
 | `graphPolicy.maxContextTokens` | 压缩上下文预算（默认 **1500**） |
 | `graphPolicy.autoIndexOnSave` | 保存后增量索引（默认 **true**） |
 | `graphPolicy.autoIndexOnPreview` / `autoIndexOnRun` | preview / run 前自动索引 |
@@ -317,6 +362,18 @@ code --install-extension artifacts/graphflow-vscode-*.vsix
 
 ## 常见问题
 
+**切换项目后 Snapshot 显示别的仓库的图谱**
+
+- 检查 `~/.graphflow.config.json` 是否含有旧的 `workspaceRoot`，**删除该字段**后重载窗口
+- 在当前项目重新「建立图谱」，确认顶栏 `store` 路径指向本项目的 `graphflow-out/`
+- 使用 v1.0.x 最新版（已修复全局 `workspaceRoot` 串项目问题）
+
+**MCP 建图失败或索引到错误目录**
+
+- `graphflow_index` 传入 `rootDir: "/你的项目绝对路径"`
+- 或在 MCP 配置中加 `"env": { "GRAPHFLOW_WORKSPACE_ROOT": "/你的项目绝对路径" }`
+- 离线环境首次索引多语言项目时，确保 `wasm/` 语法包存在或网络可访问 unpkg
+
 **`context preview` 返回 0 anchors**
 
 - 先执行 `graph index` 或 Settings 建图
@@ -326,6 +383,7 @@ code --install-extension artifacts/graphflow-vscode-*.vsix
 
 - 升级到 **v1.0.0+** 并重载窗口
 - 点击画布工具栏 **「适应」**
+- 注意：画布展示的是**采样子图**（约 120 节点），全库规模请看顶栏统计
 
 **API Key 未配置**
 
@@ -347,7 +405,7 @@ GraphFlow/
 │   └── surfaces/
 │       ├── cli/        # CLI + runtime 子模块
 │       └── mcp/        # MCP server
-├── tests/              # 45 文件 / 200+ tests
+├── tests/              # 49 文件 / 200+ tests
 ├── vscode-extension/   # VS Code 面板与命令
 ├── docs/
 └── CHANGELOG.md

package/dist/agents/insight.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Six Thinking Hats + Five Whys Insight Engine.
+ *
+ * Borrowed from Edward de Bono's "Six Thinking Hats" framework —
+ * before planning a task, analyze it through 6 distinct perspectives,
+ * and auto-apply 5-level Why chains to key observations that fall
+ * below a confidence threshold.
+ *
+ * The 5 Why triggers are automatic: whenever a hat produces an
+ * observation with low certainty (< 0.6), the chain is applied to
+ * drill toward root cause.
+ */
+import type { TaskNode } from "../core/types";
+import type { ModelSelection } from "../routing/model-router";
+import { type PromptContext } from "../routing/provider-executor";
+/** === Hat Definitions === */
+export interface HatDefinition {
+    name: string;
+    color: "white" | "red" | "black" | "yellow" | "green" | "blue";
+    role: string;
+    focus: string;
+    question: string;
+    whyFocus: string;
+    whyRootFocus: string;
+}
+export declare const SIX_HATS: HatDefinition[];
+/** === Five Whys Chain === */
+export interface WhyStep {
+    level: 1 | 2 | 3 | 4 | 5;
+    question: string;
+    answer: string;
+    certainty: number;
+}
+export interface FiveWhyResult {
+    initialObservation: string;
+    certainty: number;
+    steps: WhyStep[];
+    rootCause: string;
+}
+export interface WhyChainSection {
+    hat: HatDefinition;
+    /** Key observation produced by this hat */
+    observation: string;
+    certainty: number;
+    /** 5-level why chain (only non-trivial ones are expanded) */
+    whyChain: FiveWhyResult | null;
+    /** Critical findings that should influence the plan */
+    criticalInsight: string;
+}
+/** === Six Hats Analysis Result === */
+export interface SixHatsInsight {
+    task: string;
+    hats: WhyChainSection[];
+    blueHatSynthesis: string;
+    rootCauses: string[];
+    criticalRisks: string[];
+    coreValue: string;
+    refinedTaskStatement: string;
+}
+/** === Main Entry Points === */
+export interface PlanInsightOptions {
+    selection: ModelSelection;
+    context?: PromptContext;
+}
+/**
+ * Run the full Six Thinking Hats + Five Whys analysis on a task,
+ * then generate a DAG-style plan that incorporates the insights.
+ *
+ * @param task The task to analyze
+ * @param options Model selection and context options
+ */
+export declare function planInsight(task: string, options: PlanInsightOptions): Promise<{
+    insight: SixHatsInsight;
+    plan: TaskNode[];
+}>;
+/**
+ * Run the Six Thinking Hats analysis with automatic 5 Why triggers.
+ *
+ * Each hat produces an observation. If the observation's certainty
+ * is below THRESHOLD (0.6), a 5 Why chain is automatically applied.
+ */
+export declare function analyzeWithSixHats(task: string, options: PlanInsightOptions): Promise<SixHatsInsight>;
+//# sourceMappingURL=insight.d.ts.map

package/dist/agents/insight.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"insight.d.ts","sourceRoot":"","sources":["../../src/agents/insight.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,EAAqB,KAAK,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAGrF,8BAA8B;AAE9B,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,OAAO,GAAG,KAAK,GAAG,OAAO,GAAG,QAAQ,GAAG,OAAO,GAAG,MAAM,CAAC;IAC/D,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,eAAO,MAAM,QAAQ,EAAE,aAAa,EAuDnC,CAAC;AAEF,8BAA8B;AAE9B,MAAM,WAAW,OAAO;IACtB,KAAK,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,aAAa;IAC5B,kBAAkB,EAAE,MAAM,CAAC;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,OAAO,EAAE,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,aAAa,CAAC;IACnB,2CAA2C;IAC3C,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,6DAA6D;IAC7D,QAAQ,EAAE,aAAa,GAAG,IAAI,CAAC;IAC/B,uDAAuD;IACvD,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,uCAAuC;AAEvC,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,eAAe,EAAE,CAAC;IACxB,gBAAgB,EAAE,MAAM,CAAC;IACzB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,oBAAoB,EAAE,MAAM,CAAC;CAC9B;AAED,gCAAgC;AAEhC,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE,cAAc,CAAC;IAC1B,OAAO,CAAC,EAAE,aAAa,CAAC;CACzB;AAED;;;;;;GAMG;AACH,wBAAsB,WAAW,CAC/B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC;IACT,OAAO,EAAE,cAAc,CAAC;IACxB,IAAI,EAAE,QAAQ,EAAE,CAAC;CAClB,CAAC,CAID;AAED;;;;;GAKG;AACH,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,cAAc,CAAC,CAkCzB"}