@roarpeng/graphflow 1.15.1 → 1.15.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/CHANGELOG.md +7 -0
  2. package/README.md +10 -7
  3. package/README.zh.md +5 -3
  4. package/package.json +2 -1
  5. package/plugin.json +1 -1
package/CHANGELOG.md CHANGED
@@ -2,6 +2,13 @@
2
2
 
3
3
  All notable changes to this project are documented in this file.
4
4
 
5
+ ## [1.15.2] - 2026-09-05
6
+
7
+ ### Added
8
+
9
+ - **飞轮公开复现包（path A）**：`npm run proof:flywheel` 串起已有的检索 / skill A/B / memory A/B 离线基准，打印机器可读摘要 + 人类 checklist；`--dry-run` / `--help` 不重跑基准。冻结数字目录 [`benchmarks/flywheel-proof-claims.json`](benchmarks/flywheel-proof-claims.json)；第三方入口 [`docs/flywheel-reproduction.md`](docs/flywheel-reproduction.md)。不发明新数字，只接线仓库里已提交的自测 RESULTS。
10
+ - **GraphFlow + Serena 联合方案独立指南**：把 `docs/comparison.md` 里的 "better together" 提升为一等文档 [`docs/graphflow-serena.md`](docs/graphflow-serena.md) / [中文](docs/graphflow-serena.zh.md)——并列安装两个 MCP、谁做什么（context/plan → Serena 编辑 → `report_outcome`）、常见坑。README（EN/中文）与 comparison 互链；配置示例 [`examples/graphflow-serena.mcp.json`](examples/graphflow-serena.mcp.json)（仅 MCP 片段，不把 Serena 写入 `package.json`）。无运行时代码改动。
11
+
5
12
  ## [1.15.1] - 2026-09-05
6
13
 
7
14
  ### Changed
package/README.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  English | [中文](README.zh.md)
4
4
 
5
- [![npm version](https://img.shields.io/badge/npm-1.15.1-blue)](https://www.npmjs.com/package/@roarpeng/graphflow)
5
+ [![npm version](https://img.shields.io/badge/npm-1.15.2-blue)](https://www.npmjs.com/package/@roarpeng/graphflow)
6
6
 
7
7
  > **The memory & context harness for coding agents.** Local-first code knowledge graph · bounded context compression (~98% token savings) · cross-session learning flywheel.
8
8
 
@@ -29,14 +29,16 @@ It is also **local-first and portable**: everything runs offline with no API key
29
29
 
30
30
  ## Proof, not promises
31
31
 
32
- All headline numbers come from a **public, reproducible benchmark suite** ([benchmarks/README.md](benchmarks/README.md)) with published methodology ([docs/benchmark-standards.md](docs/benchmark-standards.md)) and machine-readable JSON dumps pinned to commits:
32
+ **Third-party reproduction entry:** `npm run proof:flywheel` — one command, offline, no API key. Guide: [docs/flywheel-reproduction.md](docs/flywheel-reproduction.md). Independent runs are welcome; open a GitHub issue titled `[benchmark] Independent reproduction — <commit>`.
33
+
34
+ All headline numbers come from a **public, reproducible benchmark suite** ([benchmarks/README.md](benchmarks/README.md)) with published methodology ([docs/benchmark-standards.md](docs/benchmark-standards.md)) and machine-readable JSON dumps pinned to commits. Authoritative percentages live in the tracked RESULTS markdown; this package does not invent new scores.
33
35
 
34
36
  - **~98% token savings** (8-query suite, 262,926 → 2,843 tokens; independently re-counted with `gpt-tokenizer`)
35
37
  - **132-query golden retrieval set** in CI (Hit@5 = 100%, MRR = 0.836, NDCG@5 = 0.601); downloadable open dataset: [`benchmarks/datasets/retrieval-golden-v1.json`](benchmarks/datasets/retrieval-golden-v1.json) — run `npm run bench:retrieval`
36
38
  - **Skill A/B: 100% vs 61.5%** task success with the flywheel on vs off (26 tasks)
37
39
  - **Memory ROI: 100% vs 56.5%** with episodic memory on vs off (62 tasks, with attribution chains)
38
40
 
39
- Results are commit-anchored so any number above can be checked out and re-run. Third-party reproduction is actively welcomed — see [ROADMAP.md](ROADMAP.md) for the open invitation.
41
+ Results are commit-anchored so any number above can be checked out and re-run. See [ROADMAP.md](ROADMAP.md) for the open invitation.
40
42
 
41
43
  ## Memory poisoning protection
42
44
 
@@ -67,7 +69,7 @@ Connect via MCP (Cursor / Claude Code / …):
67
69
  }
68
70
  ```
69
71
 
70
- The agent calls `graphflow_context` for compressed context, then `graphflow_plan` to plan; without a provider API key GraphFlow automatically bridges the ATP thinking protocol to the host agent (agent-delegated mode).
72
+ The agent calls `graphflow_context` for compressed context, then `graphflow_plan` to plan; without a provider API key GraphFlow automatically bridges the ATP thinking protocol to the host agent (agent-delegated mode). For symbol-precise edits, compose Serena as a second MCP server — [GraphFlow + Serena](docs/graphflow-serena.md) (`examples/graphflow-serena.mcp.json`).
71
73
 
72
74
  ## Why GraphFlow
73
75
 
@@ -82,7 +84,7 @@ Single-purpose tools each do one thing well; GraphFlow combines graph + compress
82
84
  | Local-first | ✅ | ✅ | ✅ | ✅ |
83
85
  | Open protocol | [ATP/IR public spec](docs/atp-ir-spec-v1.md) | — | — | — |
84
86
 
85
- > The differentiator is the **learning flywheel**: graph indexing and token compression are replicable; project-private experience (skills, lessons, decisions) accumulated across sessions is not — it compounds with use. Serena is a complement, not a competitor — see [GraphFlow + Serena: better together](docs/comparison.md#graphflow--serena-better-together联合方案).
87
+ > The differentiator is the **learning flywheel**: graph indexing and token compression are replicable; project-private experience (skills, lessons, decisions) accumulated across sessions is not — it compounds with use. Serena is a complement, not a competitor — see [GraphFlow + Serena: better together](docs/graphflow-serena.md) ([中文](docs/graphflow-serena.zh.md); [comparison](docs/comparison.md)).
86
88
 
87
89
  ## Core capabilities (v1.13+)
88
90
 
@@ -285,7 +287,7 @@ Supported: Cursor, VS Code, Trae (incl. CN), Claude Code, Windsurf, Cline, Roo C
285
287
 
286
288
  ## Protocol
287
289
 
288
- [ATP/IR — Agent Thinking Protocol public specification v1.0](docs/atp-ir-spec-v1.md): work-item registry, submit/merge contract, compatibility rules. Third-party tools can implement compatible producers / consumers. Minimal Producer example: [`examples/atp-minimal-producer/`](examples/atp-minimal-producer/).
290
+ [ATP/IR — Agent Thinking Protocol public specification v1.0](docs/atp-ir-spec-v1.md): work-item registry, submit/merge contract, compatibility rules. Third-party tools can implement compatible producers / consumers. Minimal Producer example: [`examples/atp-minimal-producer/`](examples/atp-minimal-producer/). Dual-MCP compose snippet (GraphFlow + Serena, config only): [`examples/graphflow-serena.mcp.json`](examples/graphflow-serena.mcp.json).
289
291
 
290
292
  ## Community
291
293
 
@@ -325,7 +327,8 @@ GraphFlow/
325
327
  │ └── mcp/ # MCP server (10 tools)
326
328
  ├── tests/ # 142 files / 961 tests (incl. governance foundation and MCP HTTP/stdio matrix)
327
329
  ├── benchmarks/ # comprehensive + independent + SWE-bench + token savings + skill A/B (reproducible)
328
- ├── docs/ # ATP spec + context contract + experience memory + comparisons
330
+ ├── docs/ # ATP spec + context contract + experience memory + flywheel reproduction + GraphFlow/Serena
331
+ ├── examples/ # ATP producer + team-memory config + GraphFlow/Serena dual-MCP snippet
329
332
  ├── vscode-extension/ # VS Code panel and commands
330
333
  └── CHANGELOG.md
331
334
  ```
package/README.zh.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  [English](README.md) | 中文
4
4
 
5
- [![npm version](https://img.shields.io/badge/npm-1.15.1-blue)](https://www.npmjs.com/package/@roarpeng/graphflow)
5
+ [![npm version](https://img.shields.io/badge/npm-1.15.2-blue)](https://www.npmjs.com/package/@roarpeng/graphflow)
6
6
 
7
7
  > **给编程 Agent 用的记忆与上下文 harness。** 本地优先的代码知识图谱 · 有界上下文压缩（约 98% token 节省） · 跨会话学习飞轮。
8
8
 
@@ -31,7 +31,7 @@ MCP 入口：
31
31
  }
32
32
  ```
33
33
 
34
- Agent 应先调 `graphflow_context` 拿压缩上下文，再视需要调用 `graphflow_plan`。没有 LLM API Key 时会桥接到宿主 Agent（agent-delegated）。
34
+ Agent 应先调 `graphflow_context` 拿压缩上下文，再视需要调用 `graphflow_plan`。没有 LLM API Key 时会桥接到宿主 Agent（agent-delegated）。需要符号级精确编辑时，把 Serena 作为第二个 MCP server 并列挂载——见 [GraphFlow + Serena 联合方案](docs/graphflow-serena.zh.md)（配置示例：[`examples/graphflow-serena.mcp.json`](examples/graphflow-serena.mcp.json)）。
35
35
 
36
36
  ## 工作台脉络（v1.9.14）
37
37
 
@@ -136,4 +136,6 @@ dsh plugin --profile web remove @roarpeng/graphflow
136
136
 
137
137
  ## 更多
138
138
 
139
- 完整英文文档、基准与协议：[README.md](README.md) · [ATP/IR](docs/atp-ir-spec-v1.md) · [上下文合同](docs/context-contract.md) · [经验记忆](docs/experience-memory.md)
139
+ 完整英文文档、基准与协议：[README.md](README.md) · [ATP/IR](docs/atp-ir-spec-v1.md) · [上下文合同](docs/context-contract.md) · [经验记忆](docs/experience-memory.md) · [GraphFlow + Serena](docs/graphflow-serena.zh.md) · [竞品对比](docs/comparison.md)
140
+
141
+ 第三方复现飞轮 / 记忆 A/B / 检索自测：`npm run proof:flywheel`（说明见 [docs/flywheel-reproduction.md](docs/flywheel-reproduction.md)）。
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@roarpeng/graphflow",
3
- "version": "1.15.1",
3
+ "version": "1.15.2",
4
4
  "publishConfig": {
5
5
  "access": "public"
6
6
  },
@@ -77,6 +77,7 @@
77
77
  "bench:skill-ab": "tsx benchmarks/run-skill-ab-benchmark.ts && tsx benchmarks/run-skill-ab.ts",
78
78
  "bench:memory": "tsx benchmarks/run-memory-ab.ts",
79
79
  "bench:all": "npm run bench:retrieval && npm run bench:token && npm run bench:skill-ab && npm run bench:memory",
80
+ "proof:flywheel": "tsx benchmarks/run-flywheel-proof.ts",
80
81
  "dataset:retrieval": "tsx benchmarks/export-retrieval-dataset.ts",
81
82
  "backfill:episodes": "node scripts/backfill-episodes.cjs",
82
83
  "lint": "eslint .",
package/plugin.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
3
3
  "name": "graphflow",
4
- "version": "1.15.1",
4
+ "version": "1.15.2",
5
5
  "description": "图谱上下文压缩与任务规划插件（10 个 MCP 工具）。能力：压缩上下文、DAG 规划、增量建图、技能飞轮、诊断与产物导入导出。DeepSeek Harness：dsh plugin --profile web add @roarpeng/graphflow；工具名为 mcp__graphflow__graphflow_*。先调 graphflow_context（传 rootDir），复杂任务再 plan，改完代码后 index。",
6
6
  "author": {
7
7
  "name": "Roarpeng",