@roarpeng/graphflow 1.4.0 → 1.4.1

package/CHANGELOG.md

@@ -4,6 +4,18 @@ All notable changes to this project are documented in this file.
 
 ## [Unreleased]
 
+## [1.4.1] - 2026-07-05
+
+### Fixed
+
+- **CI Windows 构建**：`package-windows` 固定 `windows-2022`，修复 `windows-latest`（VS 2026）上 node-gyp 无法识别 VS 18 导致 `hnswlib-node` 编译失败
+- **validate**：Linux CI 增加 `npm rebuild hnswlib-node`，确保 HNSW 原生模块在测试前就绪
+- **文档一致性**：同步 MCP 工具列表（移除 v1.4 已删除的 `enrich_graph` / `model_download` / `metrics`；补充 `submit_insight` / `merge_insight` / `skill_guide`）
+
+### Changed
+
+- **README / 扩展 README**：补充 VSIX 安装步骤（VS Code / Cursor）、MCP `install` 命令、`hnswlib-node` 原生编译环境说明
+
 ## [1.4.0] - 2026-07-04
 
 ### Changed

package/README.md

@@ -97,9 +97,9 @@ npx @roarpeng/graphflow context preview "orchestrator" --json
 
 ### 发布信息
 
-- 最新版本：**v1.4.0**（root + vscode-extension）；npm：`@roarpeng/graphflow@1.4.0`
-- **GitHub Release**：push 到 `main` 后 CI 自动构建 VSIX 并发布到 GitHub Releases
-- **npm 发布**：push tag `v*` 触发 npm publish
+- 最新版本：**v1.4.1**（root + vscode-extension）；npm：`@roarpeng/graphflow@1.4.1`
+- **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,6 +107,9 @@ 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 环境安装
 
 ## 5 分钟本地试跑
 
@@ -303,13 +306,18 @@ const run = await orchestrate(
 GraphFlow CLI 可自动检测并安装 MCP 配置到 15+ 编码 Agent：
 
 ```bash
-# 检测已安装的 Agent
+# 检测已安装的 Agent 与 MCP 配置状态
 npx @roarpeng/graphflow doctor
 
-# 自动安装 MCP 配置到所有检测到的 Agent
+# 一键安装 MCP + Skill + Cursor Rules（推荐）
+npx @roarpeng/graphflow install
+
+# 或仅初始化项目级配置（.graphflow/config.json 等）
 npx @roarpeng/graphflow init
 ```
 
+**本地 `npm install` 后**：若项目已有 `.cursor/mcp.json` 或 `.vscode/mcp.json`，postinstall 会自动注入 workspace 级 GraphFlow MCP 与 Skill；完整用户级安装请运行 `npx @roarpeng/graphflow install`。
+
 支持的 Agent：Cursor、VS Code、Trae、Claude Code、Windsurf、Cline、Roo Code、Kilo Code、PearAI、Gemini、Codex、Antigravity、Amazon Q、Zed、Continue。
 
 ## 配置文件
@@ -350,7 +358,25 @@ cp graphflow.config.example.json graphflow.config.json
 | `skillPolicy.enableSkillFlywheel` | 技能飞轮 |
 | `embeddingPolicy.provider` | embedding 提供者（`hash` 零成本 / `openai`） |
 
-## VS Code 扩展
+## VS Code / Cursor 扩展
+
+扩展内置 GraphFlow runtime，**安装 VSIX 后无需再 clone 本仓库或配置 `npm run start`**。
+
+### 安装 VSIX（推荐）
+
+1. 打开 [GitHub Releases](https://github.com/Roarpeng/GraphFlow/releases)，下载最新 `graphflow-vscode-<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-vscode-1.4.1.vsix
+# 或
+cursor --install-extension graphflow-vscode-1.4.1.vsix
+```
 
 ### 命令面板
 
@@ -374,7 +400,7 @@ Chat Agent（`@graphflow`）：`/run`、`/plan`、`/graph`、`/skills`、`/diagn
 
 其它建图入口：`graph index` CLI、MCP `graphflow_index`、`autoIndexOnPreview` / `autoIndexOnRun` / `autoIndexOnSave`
 
-### 开发模式
+### 开发模式（贡献者）
 
 ```bash
 cd vscode-extension
@@ -384,13 +410,11 @@ npm run build
 
 在 VS Code 中 `F5` 启动 Extension Development Host。
 
-### 安装 VSIX
-
-从 [GitHub Releases](https://github.com/Roarpeng/GraphFlow/releases) 下载最新 VSIX，或本地：
+### 本地打包 VSIX
 
 ```bash
-cd vscode-extension && npm run package
-code --install-extension artifacts/graphflow-vscode-*.vsix
+npm run package:extension
+# 输出：artifacts/graphflow-vscode-<version>.vsix
 ```
 
 ## 本地验收清单

package/dist/surfaces/cursor-rules/graphflow.mdc

@@ -44,6 +44,8 @@ Do not scan the whole repository, recursively inspect many files, or read large
 | `graphflow_plan_insight` | Six Thinking Hats + 5-Why deep analysis | Medium - ambiguous/high-stakes tasks |
 | `graphflow_run` | Plan + context package (bridge mode) | Medium - full task packaging |
 | `graphflow_report_outcome` | Report bridge-mode execution outcome back | Medium - close the learning loop |
+| `graphflow_submit_insight` | Submit agent answers to Six Hats / plan prompts | Medium - no external LLM API |
+| `graphflow_merge_insight` | Merge submitted insights into unified plan | Medium - after submit_insight |
 
 ### Graph Management Tools (Medium Frequency)
 
@@ -53,8 +55,6 @@ Do not scan the whole repository, recursively inspect many files, or read large
 | `graphflow_index_file` | Single file incremental index | Medium-High - after saving a file |
 | `graphflow_rebuild` | Clear cache + full re-index | Low - when graph is stale/corrupted |
 | `graphflow_inspect_graph` | Graph stats & sample nodes/edges | Low - check graph health |
-| `graphflow_enrich_graph` | Semantic enrichment of symbols | Rare - LLM-powered enrichment |
-| `graphflow_model_download` | Download local compression model | Rare - offline setup |
 
 ### Collaboration & Insights Tools (Low Frequency)
 
@@ -63,8 +63,8 @@ Do not scan the whole repository, recursively inspect many files, or read large
 | `graphflow_export_artifact` | Export graph to portable artifact | Low - team sharing |
 | `graphflow_import_artifact` | Import graph artifact | Low - skip full index on new machine |
 | `graphflow_skill_insights` | Learned skill patterns | Low - leverage prior learning |
+| `graphflow_skill_guide` | Skill usage guide for connected agents | Low - onboarding |
 | `graphflow_stats` | Cumulative token savings stats | Low - ROI tracking |
-| `graphflow_metrics` | Prometheus-compatible metrics | Low - observability |
 | `graphflow_diagnose` | Provider health & model routing | Rare - config issues |
 
 ## Standard Workflows

package/dist/surfaces/trae-skill/graphflow/SKILL.md

@@ -21,10 +21,10 @@ GraphFlow is a graph-based context and planning service backed by a persistent M
 ┌─────────────────────────────────────────────────┐
 │  GraphFlow MCP Server (persistent backend)      │
 │  18 tools: preview, expand, plan, plan_insight,  │
-│  run, report_outcome, index, index_file, rebuild,│
-│  enrich, model_download, inspect, skill_insights,│
-│  diagnose, export_artifact, import_artifact,     │
-│  stats, metrics                                  │
+│  run, report_outcome, submit_insight, merge_insight,│
+│  index, index_file, rebuild, inspect, skill_insights,│
+│  skill_guide, diagnose, export_artifact, import_artifact,│
+│  stats                                              │
 └──────────────────┬──────────────────────────────┘
                    │
                    ▼
@@ -72,6 +72,8 @@ GraphFlow is a graph-based context and planning service backed by a persistent M
 | `graphflow_plan_insight` | Six Thinking Hats + 5-Why deep analysis | Medium - ambiguous/high-stakes tasks |
 | `graphflow_run` | Plan + context package (bridge mode) | Medium - full task packaging |
 | `graphflow_report_outcome` | Report bridge-mode execution outcome back | Medium - close the learning loop |
+| `graphflow_submit_insight` | Submit agent answers to Six Hats / plan prompts | Medium - no external LLM API |
+| `graphflow_merge_insight` | Merge submitted insights into unified plan | Medium - after submit_insight |
 
 ### Graph Management Tools (Medium Frequency)
 
@@ -81,8 +83,6 @@ GraphFlow is a graph-based context and planning service backed by a persistent M
 | `graphflow_index_file` | Single file incremental index | Medium-High - after saving a file |
 | `graphflow_rebuild` | Clear cache + full re-index | Low - when graph is stale/corrupted |
 | `graphflow_inspect_graph` | Graph stats & sample nodes/edges | Low - check graph health |
-| `graphflow_enrich_graph` | Semantic enrichment of symbols | Rare - LLM-powered enrichment |
-| `graphflow_model_download` | Download local compression model | Rare - offline setup |
 
 ### Collaboration & Insights Tools (Low Frequency)
 
@@ -91,8 +91,8 @@ GraphFlow is a graph-based context and planning service backed by a persistent M
 | `graphflow_export_artifact` | Export graph to portable artifact | Low - team sharing |
 | `graphflow_import_artifact` | Import graph artifact | Low - skip full index on new machine |
 | `graphflow_skill_insights` | Learned skill patterns | Low - leverage prior learning |
+| `graphflow_skill_guide` | Skill usage guide for connected agents | Low - onboarding |
 | `graphflow_stats` | Cumulative token savings stats | Low - ROI tracking |
-| `graphflow_metrics` | Prometheus-compatible metrics | Low - observability |
 | `graphflow_diagnose` | Provider health & model routing | Rare - config issues |
 
 ---
@@ -300,14 +300,6 @@ graphflow_import_artifact(inputPath?)
 
 ### Workflow 7: Advanced Capabilities
 
-#### Semantic Enrichment (LLM required)
-```
-graphflow_enrich_graph(batchSize?, sleepMs?, timeoutMs?)
-```
-- Adds semantic descriptions to symbol nodes
-- Improves context quality for complex queries
-- Requires configured LLM provider
-
 #### Skill Insights (learning flywheel)
 ```
 graphflow_skill_insights(limit?, rootDir?)
@@ -324,14 +316,6 @@ graphflow_stats(configPath?, rootDir?)
 - ROI tracking
 - See how much GraphFlow has saved
 
-#### Prometheus Metrics
-```
-graphflow_metrics(configPath?, rootDir?)
-```
-- Prometheus text exposition format
-- Token savings, graph size, compression ratio
-- For observability dashboards
-
 #### Diagnostics
 ```
 graphflow_diagnose(configPath?)
@@ -377,9 +361,8 @@ Start
   ├─ Do you want to leverage prior learning?
   │   └─ YES → graphflow_skill_insights
   │
-  ├─ Tracking ROI / observability?
-  │   ├─ Quick stats → graphflow_stats
-  │   └─ Prometheus → graphflow_metrics
+  ├─ Tracking ROI?
+  │   └─ graphflow_stats
   │
   └─ Is routing/models misbehaving?
       └─ YES → graphflow_diagnose
@@ -467,7 +450,7 @@ Always pay attention to `tokenBudget`:
 ### Context quality is poor
 1. Try more specific query terms
 2. Check if symbols are indexed (inspect graph)
-3. Run `graphflow_enrich_graph` for semantic enhancement (LLM required)
+3. Run `graphflow_rebuild` if the graph may be stale
 
 ### Tool errors / configuration issues
 1. Run `graphflow_diagnose` to check provider health
@@ -527,9 +510,6 @@ await graphflow_skill_insights({ limit: 5 });
 // Token savings stats
 await graphflow_stats();
 
-// Prometheus metrics
-await graphflow_metrics();
-
 // Diagnose issues
 await graphflow_diagnose();
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@roarpeng/graphflow",
-  "version": "1.4.0",
+  "version": "1.4.1",
   "publishConfig": {
     "access": "public"
   },

package/src/surfaces/cursor-rules/graphflow.mdc

@@ -44,6 +44,8 @@ Do not scan the whole repository, recursively inspect many files, or read large
 | `graphflow_plan_insight` | Six Thinking Hats + 5-Why deep analysis | Medium - ambiguous/high-stakes tasks |
 | `graphflow_run` | Plan + context package (bridge mode) | Medium - full task packaging |
 | `graphflow_report_outcome` | Report bridge-mode execution outcome back | Medium - close the learning loop |
+| `graphflow_submit_insight` | Submit agent answers to Six Hats / plan prompts | Medium - no external LLM API |
+| `graphflow_merge_insight` | Merge submitted insights into unified plan | Medium - after submit_insight |
 
 ### Graph Management Tools (Medium Frequency)
 
@@ -53,8 +55,6 @@ Do not scan the whole repository, recursively inspect many files, or read large
 | `graphflow_index_file` | Single file incremental index | Medium-High - after saving a file |
 | `graphflow_rebuild` | Clear cache + full re-index | Low - when graph is stale/corrupted |
 | `graphflow_inspect_graph` | Graph stats & sample nodes/edges | Low - check graph health |
-| `graphflow_enrich_graph` | Semantic enrichment of symbols | Rare - LLM-powered enrichment |
-| `graphflow_model_download` | Download local compression model | Rare - offline setup |
 
 ### Collaboration & Insights Tools (Low Frequency)
 
@@ -63,8 +63,8 @@ Do not scan the whole repository, recursively inspect many files, or read large
 | `graphflow_export_artifact` | Export graph to portable artifact | Low - team sharing |
 | `graphflow_import_artifact` | Import graph artifact | Low - skip full index on new machine |
 | `graphflow_skill_insights` | Learned skill patterns | Low - leverage prior learning |
+| `graphflow_skill_guide` | Skill usage guide for connected agents | Low - onboarding |
 | `graphflow_stats` | Cumulative token savings stats | Low - ROI tracking |
-| `graphflow_metrics` | Prometheus-compatible metrics | Low - observability |
 | `graphflow_diagnose` | Provider health & model routing | Rare - config issues |
 
 ## Standard Workflows

package/src/surfaces/trae-skill/graphflow/SKILL.md

@@ -21,10 +21,10 @@ GraphFlow is a graph-based context and planning service backed by a persistent M
 ┌─────────────────────────────────────────────────┐
 │  GraphFlow MCP Server (persistent backend)      │
 │  18 tools: preview, expand, plan, plan_insight,  │
-│  run, report_outcome, index, index_file, rebuild,│
-│  enrich, model_download, inspect, skill_insights,│
-│  diagnose, export_artifact, import_artifact,     │
-│  stats, metrics                                  │
+│  run, report_outcome, submit_insight, merge_insight,│
+│  index, index_file, rebuild, inspect, skill_insights,│
+│  skill_guide, diagnose, export_artifact, import_artifact,│
+│  stats                                              │
 └──────────────────┬──────────────────────────────┘
                    │
                    ▼
@@ -72,6 +72,8 @@ GraphFlow is a graph-based context and planning service backed by a persistent M
 | `graphflow_plan_insight` | Six Thinking Hats + 5-Why deep analysis | Medium - ambiguous/high-stakes tasks |
 | `graphflow_run` | Plan + context package (bridge mode) | Medium - full task packaging |
 | `graphflow_report_outcome` | Report bridge-mode execution outcome back | Medium - close the learning loop |
+| `graphflow_submit_insight` | Submit agent answers to Six Hats / plan prompts | Medium - no external LLM API |
+| `graphflow_merge_insight` | Merge submitted insights into unified plan | Medium - after submit_insight |
 
 ### Graph Management Tools (Medium Frequency)
 
@@ -81,8 +83,6 @@ GraphFlow is a graph-based context and planning service backed by a persistent M
 | `graphflow_index_file` | Single file incremental index | Medium-High - after saving a file |
 | `graphflow_rebuild` | Clear cache + full re-index | Low - when graph is stale/corrupted |
 | `graphflow_inspect_graph` | Graph stats & sample nodes/edges | Low - check graph health |
-| `graphflow_enrich_graph` | Semantic enrichment of symbols | Rare - LLM-powered enrichment |
-| `graphflow_model_download` | Download local compression model | Rare - offline setup |
 
 ### Collaboration & Insights Tools (Low Frequency)
 
@@ -91,8 +91,8 @@ GraphFlow is a graph-based context and planning service backed by a persistent M
 | `graphflow_export_artifact` | Export graph to portable artifact | Low - team sharing |
 | `graphflow_import_artifact` | Import graph artifact | Low - skip full index on new machine |
 | `graphflow_skill_insights` | Learned skill patterns | Low - leverage prior learning |
+| `graphflow_skill_guide` | Skill usage guide for connected agents | Low - onboarding |
 | `graphflow_stats` | Cumulative token savings stats | Low - ROI tracking |
-| `graphflow_metrics` | Prometheus-compatible metrics | Low - observability |
 | `graphflow_diagnose` | Provider health & model routing | Rare - config issues |
 
 ---
@@ -300,14 +300,6 @@ graphflow_import_artifact(inputPath?)
 
 ### Workflow 7: Advanced Capabilities
 
-#### Semantic Enrichment (LLM required)
-```
-graphflow_enrich_graph(batchSize?, sleepMs?, timeoutMs?)
-```
-- Adds semantic descriptions to symbol nodes
-- Improves context quality for complex queries
-- Requires configured LLM provider
-
 #### Skill Insights (learning flywheel)
 ```
 graphflow_skill_insights(limit?, rootDir?)
@@ -324,14 +316,6 @@ graphflow_stats(configPath?, rootDir?)
 - ROI tracking
 - See how much GraphFlow has saved
 
-#### Prometheus Metrics
-```
-graphflow_metrics(configPath?, rootDir?)
-```
-- Prometheus text exposition format
-- Token savings, graph size, compression ratio
-- For observability dashboards
-
 #### Diagnostics
 ```
 graphflow_diagnose(configPath?)
@@ -377,9 +361,8 @@ Start
   ├─ Do you want to leverage prior learning?
   │   └─ YES → graphflow_skill_insights
   │
-  ├─ Tracking ROI / observability?
-  │   ├─ Quick stats → graphflow_stats
-  │   └─ Prometheus → graphflow_metrics
+  ├─ Tracking ROI?
+  │   └─ graphflow_stats
   │
   └─ Is routing/models misbehaving?
       └─ YES → graphflow_diagnose
@@ -467,7 +450,7 @@ Always pay attention to `tokenBudget`:
 ### Context quality is poor
 1. Try more specific query terms
 2. Check if symbols are indexed (inspect graph)
-3. Run `graphflow_enrich_graph` for semantic enhancement (LLM required)
+3. Run `graphflow_rebuild` if the graph may be stale
 
 ### Tool errors / configuration issues
 1. Run `graphflow_diagnose` to check provider health
@@ -527,9 +510,6 @@ await graphflow_skill_insights({ limit: 5 });
 // Token savings stats
 await graphflow_stats();
 
-// Prometheus metrics
-await graphflow_metrics();
-
 // Diagnose issues
 await graphflow_diagnose();
 ```