@roarpeng/graphflow 1.15.1 → 1.15.3

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 All notable changes to this project are documented in this file.
 
+## [1.15.3] - 2026-09-05
+
+### Changed
+
+- **R4 context packaging 去重**：`buildLayeredContextPackage` / `buildEnhancedContextPackage` 抽出共享 `context-package-core`（keyword/vector 召回、L1–L3 配额打包、dialogue 与 neighbor expansion）。两条公开函数的签名与 MCP/CLI context preview 行为保持不变；enhanced 仍独占 adaptive budget、RepoMap、symbol boost、graph compression 与 same-file/import 扩展。
+
+### Tests
+
+- **m74/m75 测试隔离**：不再 `process.chdir()`，也不再向真实 `$HOME/.npm/_npx` 写文件。fake home 与项目根均落在 `os.tmpdir()`，通过 `fromDir` 注入与 `process.cwd` mock 覆盖 unsafe-cwd 路径。
+
+## [1.15.2] - 2026-09-05
+
+### Added
+
+- **飞轮公开复现包（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。
+- **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`）。无运行时代码改动。
+
 ## [1.15.1] - 2026-09-05
 
 ### Changed

package/README.md

@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-[![npm version](https://img.shields.io/badge/npm-1.15.1-blue)](https://www.npmjs.com/package/@roarpeng/graphflow)
+[![npm version](https://img.shields.io/badge/npm-1.15.3-blue)](https://www.npmjs.com/package/@roarpeng/graphflow)
 
 > **The memory & context harness for coding agents.** Local-first code knowledge graph · bounded context compression (~98% token savings) · cross-session learning flywheel.
 
@@ -29,14 +29,16 @@ It is also **local-first and portable**: everything runs offline with no API key
 
 ## Proof, not promises
 
-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:
+**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>`.
+
+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.
 
 - **~98% token savings** (8-query suite, 262,926 → 2,843 tokens; independently re-counted with `gpt-tokenizer`)
 - **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`
 - **Skill A/B: 100% vs 61.5%** task success with the flywheel on vs off (26 tasks)
 - **Memory ROI: 100% vs 56.5%** with episodic memory on vs off (62 tasks, with attribution chains)
 
-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.
+Results are commit-anchored so any number above can be checked out and re-run. See [ROADMAP.md](ROADMAP.md) for the open invitation.
 
 ## Memory poisoning protection
 
@@ -67,7 +69,7 @@ Connect via MCP (Cursor / Claude Code / …):
 }
 ```
 
-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).
+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`).
 
 ## Why GraphFlow
 
@@ -82,7 +84,7 @@ Single-purpose tools each do one thing well; GraphFlow combines graph + compress
 | Local-first | ✅ | ✅ | ✅ | ✅ |
 | Open protocol | [ATP/IR public spec](docs/atp-ir-spec-v1.md) | — | — | — |
 
-> 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联合方案).
+> 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)).
 
 ## Core capabilities (v1.13+)
 
@@ -285,7 +287,7 @@ Supported: Cursor, VS Code, Trae (incl. CN), Claude Code, Windsurf, Cline, Roo C
 
 ## Protocol
 
-[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/).
+[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).
 
 ## Community
 
@@ -325,7 +327,8 @@ GraphFlow/
 │       └── mcp/        # MCP server (10 tools)
 ├── tests/              # 142 files / 961 tests (incl. governance foundation and MCP HTTP/stdio matrix)
 ├── benchmarks/         # comprehensive + independent + SWE-bench + token savings + skill A/B (reproducible)
-├── docs/               # ATP spec + context contract + experience memory + comparisons
+├── docs/               # ATP spec + context contract + experience memory + flywheel reproduction + GraphFlow/Serena
+├── examples/           # ATP producer + team-memory config + GraphFlow/Serena dual-MCP snippet
 ├── vscode-extension/   # VS Code panel and commands
 └── CHANGELOG.md
 ```

package/README.zh.md

@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-[![npm version](https://img.shields.io/badge/npm-1.15.1-blue)](https://www.npmjs.com/package/@roarpeng/graphflow)
+[![npm version](https://img.shields.io/badge/npm-1.15.3-blue)](https://www.npmjs.com/package/@roarpeng/graphflow)
 
 > **给编程 Agent 用的记忆与上下文 harness。** 本地优先的代码知识图谱 · 有界上下文压缩（约 98% token 节省） · 跨会话学习飞轮。
 
@@ -31,7 +31,7 @@ MCP 入口：
 }
 ```
 
-Agent 应先调 `graphflow_context` 拿压缩上下文，再视需要调用 `graphflow_plan`。没有 LLM API Key 时会桥接到宿主 Agent（agent-delegated）。
+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)）。
 
 ## 工作台脉络（v1.9.14）
 
@@ -136,4 +136,6 @@ dsh plugin --profile web remove @roarpeng/graphflow
 
 ## 更多
 
-完整英文文档、基准与协议：[README.md](README.md) · [ATP/IR](docs/atp-ir-spec-v1.md) · [上下文合同](docs/context-contract.md) · [经验记忆](docs/experience-memory.md)
+完整英文文档、基准与协议：[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)
+
+第三方复现飞轮 / 记忆 A/B / 检索自测：`npm run proof:flywheel`（说明见 [docs/flywheel-reproduction.md](docs/flywheel-reproduction.md)）。

package/dist/graph/context-package-core.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Shared context-packaging core.
+ *
+ * `buildLayeredContextPackage` and `buildEnhancedContextPackage` used to
+ * duplicate retrieval + L1/L2/L3 quota packing (~60% overlap). Both public
+ * functions keep their signatures and extras; this module owns the common
+ * recall/pack steps so behavior stays identical.
+ */
+import type { GraphNode } from "../core/types.js";
+import type { GraphClient } from "./client-factory.js";
+import type { ContextAnchorItem, LayeredContextPackage, LayeredPackageOptions, SubgraphExpansionOptions } from "./context-slicer-types.js";
+export type DuplicateModulePolicy = "continue" | "break";
+export interface PackState {
+    summaryChannel: string[];
+    anchorChannel: ContextAnchorItem[];
+    added: Set<string>;
+    quota: {
+        l1: number;
+        l2: number;
+        l3: number;
+    };
+    used: {
+        l1: number;
+        l2: number;
+        l3: number;
+    };
+    maxTokens: number;
+    maxAnchors?: number;
+}
+export interface PackBudget {
+    tokens: number;
+    truncated: boolean;
+}
+/**
+ * Governance pins for L3: Decision/goal nodes that packing must prefer so
+ * budget truncation cannot drop alignment / deviation / goal constraints.
+ */
+export declare function isPinnedL3Node(node: GraphNode): boolean;
+export declare function createPackState(maxTokens: number, options?: LayeredPackageOptions, maxAnchors?: number): PackState;
+export declare function toLayeredPackage(state: PackState, budget: PackBudget): LayeredContextPackage;
+export declare function expandSubgraph(client: GraphClient, seedIds: string[], options?: SubgraphExpansionOptions): Promise<GraphNode[]>;
+export declare function vectorRecall(nodes: GraphNode[], queryEmbedding: number[], topK: number, minSimilarity: number): GraphNode[];
+export declare function collectKeywordHits(client: GraphClient, query: string, options?: LayeredPackageOptions): Promise<GraphNode[]>;
+/**
+ * Fuse keyword hits with vector recall when enabled.
+ * Returns `null` when vector recall is off so callers keep their current hit list
+ * (enhanced may have already applied symbol boosting).
+ * On failure, returns the original keyword hits (same reset both builders used).
+ */
+export declare function fuseVectorRecallIfEnabled(client: GraphClient, query: string, keywordHits: GraphNode[], options: LayeredPackageOptions | undefined, logLabel: string): Promise<GraphNode[] | null>;
+export declare function preparePackageHits(hits: GraphNode[], query: string, options: LayeredPackageOptions | undefined, snapshotNodes: GraphNode[] | undefined): GraphNode[];
+export declare function tryAppendL3Node(node: GraphNode, state: PackState, budget: PackBudget): "packed" | "budget" | "skip";
+export declare function packPrimaryHits(hits: GraphNode[], state: PackState, budget: PackBudget): void;
+export declare function injectL2Modules(client: GraphClient, hits: GraphNode[], state: PackState, budget: PackBudget, duplicatePolicy: DuplicateModulePolicy): Promise<void>;
+export declare function injectL3SkillsAndPins(client: GraphClient, query: string, options: LayeredPackageOptions | undefined, snapshotNodes: GraphNode[] | undefined, state: PackState, budget: PackBudget): Promise<void>;
+export declare function injectDialogueTurns(client: GraphClient, query: string, options: LayeredPackageOptions | undefined, state: PackState, budget: PackBudget): Promise<void>;
+export declare function injectSameFileAndImportExpansion(client: GraphClient, snapshotNodes: GraphNode[] | undefined, state: PackState, budget: PackBudget): Promise<void>;
+export declare function injectNeighborExpansion(client: GraphClient, options: LayeredPackageOptions | undefined, state: PackState, budget: PackBudget): Promise<void>;
+//# sourceMappingURL=context-package-core.d.ts.map

package/dist/graph/context-package-core.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-package-core.d.ts","sourceRoot":"","sources":["../../src/graph/context-package-core.ts"],"names":[],"mappings":"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"}