@roarpeng/graphflow 1.15.2 → 1.15.4

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 (21) hide show
  1. package/CHANGELOG.md +16 -0
  2. package/README.md +62 -61
  3. package/README.zh.md +58 -45
  4. package/cordis.patch.yml +4 -1
  5. package/dist/graph/context-package-core.d.ts +59 -0
  6. package/dist/graph/context-package-core.d.ts.map +1 -0
  7. package/dist/graph/context-package-core.js +512 -0
  8. package/dist/graph/context-package-core.js.map +1 -0
  9. package/dist/graph/context-slicer.d.ts +7 -11
  10. package/dist/graph/context-slicer.d.ts.map +1 -1
  11. package/dist/graph/context-slicer.js +54 -636
  12. package/dist/graph/context-slicer.js.map +1 -1
  13. package/dist/integrations/dsh-harness-installer.d.ts +41 -5
  14. package/dist/integrations/dsh-harness-installer.d.ts.map +1 -1
  15. package/dist/integrations/dsh-harness-installer.js +204 -15
  16. package/dist/integrations/dsh-harness-installer.js.map +1 -1
  17. package/dist/integrations/host-adapter-install.d.ts.map +1 -1
  18. package/dist/integrations/host-adapter-install.js +1 -0
  19. package/dist/integrations/host-adapter-install.js.map +1 -1
  20. package/package.json +1 -1
  21. package/plugin.json +1 -1
package/CHANGELOG.md CHANGED
@@ -2,6 +2,22 @@
2
2
 
3
3
  All notable changes to this project are documented in this file.
4
4
 
5
+ ## [1.15.4] - 2026-09-06
6
+
7
+ ### Fixed
8
+
9
+ - **DeepSeek Harness 安装不再弄挂 `dsh web`**：`graphflow install` 在 profile 未安装 `@roarpeng/graphflow` 时只写 MCP home overlay（不写 glue）；profile 已有包时清空 home overlay，由 bundle 独占 MCP+glue，避免 `ERR_MODULE_NOT_FOUND` 与 `duplicate loader entry id: mcp-graphflow`。空 `cordis.patch.yml` 改为删除文件（dsh 拒绝空 YAML）。FAQ 补充对应排障。
10
+
11
+ ## [1.15.3] - 2026-09-05
12
+
13
+ ### Changed
14
+
15
+ - **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 扩展。
16
+
17
+ ### Tests
18
+
19
+ - **m74/m75 测试隔离**：不再 `process.chdir()`，也不再向真实 `$HOME/.npm/_npx` 写文件。fake home 与项目根均落在 `os.tmpdir()`，通过 `fromDir` 注入与 `process.cwd` mock 覆盖 unsafe-cwd 路径。
20
+
5
21
  ## [1.15.2] - 2026-09-05
6
22
 
7
23
  ### Added
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.2-blue)](https://www.npmjs.com/package/@roarpeng/graphflow)
5
+ [![npm version](https://img.shields.io/badge/npm-1.15.4-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
 
@@ -10,9 +10,9 @@ The community is converging on an "agent harness" vocabulary: **memory + hooks +
10
10
 
11
11
  | Harness primitive | GraphFlow implementation |
12
12
  | --- | --- |
13
- | **Memory** | 12-language AST code graph + Episodic / Skill / Decision nodes — project knowledge *and* project experience persist across sessions |
14
- | **Hooks** | Outcome auto-capture (on by default) + Claude Code `SessionEnd` / `Stop` and DeepSeek Harness `agent/disposed` glue close the learning loop automatically — no manual outcome reporting required |
15
- | **Skills** | A four-class flywheel (`proven` / `correctable` / `anti-pattern` / `noise`) with canary validation — skills are promoted by evidence, not by assertion |
13
+ | **Memory** | 12-language AST code graph + Episodic / Skill / Decision nodes �?project knowledge *and* project experience persist across sessions |
14
+ | **Hooks** | Outcome auto-capture (on by default) + Claude Code `SessionEnd` / `Stop` and DeepSeek Harness `agent/disposed` glue close the learning loop automatically �?no manual outcome reporting required |
15
+ | **Skills** | A four-class flywheel (`proven` / `correctable` / `anti-pattern` / `noise`) with canary validation �?skills are promoted by evidence, not by assertion |
16
16
 
17
17
  Pure TypeScript/Node. CLI + MCP + VS Code extension. Fully offline, no API key required.
18
18
 
@@ -21,20 +21,20 @@ Pure TypeScript/Node. CLI + MCP + VS Code extension. Fully offline, no API key r
21
21
  Most "memory" products are either **static injection** (load `CLAUDE.md` / rules files in full on every session) or **plain RAG** (retrieve chunks, no learning). Both fail in long-lived projects:
22
22
 
23
23
  - Static injection pays the same token cost every session regardless of the task, and grows until it is truncated or ignored.
24
- - Plain RAG retrieves text but never accumulates *experience* — the thousandth task pays the same cost as the first.
24
+ - Plain RAG retrieves text but never accumulates *experience* �?the thousandth task pays the same cost as the first.
25
25
 
26
- GraphFlow is a harness: **memory is dynamic and typed**. Each request retrieves only what the current decision needs — graph anchors, compressed summaries, similar past episodes, applicable skills — under an explicit token budget (L0–L3 layered compression, ~98% savings measured). What the agent learns (outcomes, lessons, skills) is written back through hooks, so the harness gets better with use.
26
+ GraphFlow is a harness: **memory is dynamic and typed**. Each request retrieves only what the current decision needs �?graph anchors, compressed summaries, similar past episodes, applicable skills �?under an explicit token budget (L0–L3 layered compression, ~98% savings measured). What the agent learns (outcomes, lessons, skills) is written back through hooks, so the harness gets better with use.
27
27
 
28
28
  It is also **local-first and portable**: everything runs offline with no API key, and the whole surface is exposed over MCP, so the same memory travels across agents instead of being locked into one vendor's format.
29
29
 
30
30
  ## Proof, not promises
31
31
 
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>`.
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
33
 
34
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.
35
35
 
36
- - **~98% token savings** (8-query suite, 262,926 → 2,843 tokens; independently re-counted with `gpt-tokenizer`)
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
+ - **~98% token savings** (8-query suite, 262,926 �?2,843 tokens; independently re-counted with `gpt-tokenizer`)
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`
38
38
  - **Skill A/B: 100% vs 61.5%** task success with the flywheel on vs off (26 tasks)
39
39
  - **Memory ROI: 100% vs 56.5%** with episodic memory on vs off (62 tasks, with attribution chains)
40
40
 
@@ -56,7 +56,7 @@ npx @roarpeng/graphflow graph index .
56
56
  npx @roarpeng/graphflow context preview "orchestrator" --json
57
57
  ```
58
58
 
59
- Connect via MCP (Cursor / Claude Code / …):
59
+ Connect via MCP (Cursor / Claude Code / �?:
60
60
 
61
61
  ```json
62
62
  {
@@ -69,7 +69,7 @@ Connect via MCP (Cursor / Claude Code / …):
69
69
  }
70
70
  ```
71
71
 
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`).
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`).
73
73
 
74
74
  ## Why GraphFlow
75
75
 
@@ -77,23 +77,23 @@ Single-purpose tools each do one thing well; GraphFlow combines graph + compress
77
77
 
78
78
  | Capability | **GraphFlow** | CodeGraph | Serena | Repomix |
79
79
  | --- | --- | --- | --- | --- |
80
- | Code graph | 12-language AST index | more mature | LSP symbols | — |
80
+ | Code graph | 12-language AST index | more mature | LSP symbols | �?|
81
81
  | Context compression | layered + graph compression + vector recall | partial | partial | whole-repo dump |
82
- | Planning protocol | ATP IR + DAG + agent bridge | — | — | — |
83
- | **Learning memory** | Episodic / Skill / Decision flywheel | — | — | — |
84
- | Local-first | ✅ | ✅ | ✅ | ✅ |
85
- | Open protocol | [ATP/IR public spec](docs/atp-ir-spec-v1.md) | — | — | — |
82
+ | Planning protocol | ATP IR + DAG + agent bridge | �?| �?| �?|
83
+ | **Learning memory** | Episodic / Skill / Decision flywheel | �?| �?| �?|
84
+ | Local-first | �?| �?| �?| �?|
85
+ | Open protocol | [ATP/IR public spec](docs/atp-ir-spec-v1.md) | �?| �?| �?|
86
86
 
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)).
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)).
88
88
 
89
- ## Core capabilities (v1.13+)
89
+ ## Core capabilities (v1.15+)
90
90
 
91
91
  | Module | Capability |
92
92
  | --- | --- |
93
93
  | **Planning protocol** | ATP v1.1 (Intent / Requirement / Six Hats / 5-Why / First Principles / Decision Matrix / Planning / Reflection); simple / complex / insight modes; agent-delegated bridge without an LLM; **skill-conditioned DAG** (`skillRefs` / `avoidPatterns` on plan nodes); [ATP/IR public spec v1.1](docs/atp-ir-spec-v1.md) |
94
94
  | **Goal alignment** | Goal anchor nodes (intent five-tuple as first-class citizen, original requirement auto-injected); low-confidence clarification gate (no plan below 0.6); runtime alignment-check; deviation classification (misread-requirement / scope-creep / tech-drift); goal version chain + diffs |
95
- | **Knowledge graph** | 12-language AST indexing; File / Module / Symbol + **Concept / Requirement**; cross-layer edges `documents` / `implements` / `derived_from`; Office/PDF → Markdown via optional **`@firecrawl/anydoc`** (MIT). **CLI/npm**: optionalDependency. **VSIX**: not bundled; on activate the extension **auto-downloads the current-OS binary** into `~/.graphflow/optional-deps` when `graphflow.downloadAnydoc` is true (default). Disable the setting to skip network; source indexing still works. |
96
- | **Context compression** | L1/L2/L3 layered anchors; graph compression (edge weights + PageRank, LRU cache); stem-matching recall (orchestrate ↔ orchestration); vector recall + RRF; RepoMap overview; adaptive budget |
95
+ | **Knowledge graph** | 12-language AST indexing; File / Module / Symbol + **Concept / Requirement**; cross-layer edges `documents` / `implements` / `derived_from`; Office/PDF �?Markdown via optional **`@firecrawl/anydoc`** (MIT). **CLI/npm**: optionalDependency. **VSIX**: not bundled; on activate the extension **auto-downloads the current-OS binary** into `~/.graphflow/optional-deps` when `graphflow.downloadAnydoc` is true (default). Disable the setting to skip network; source indexing still works. |
96
+ | **Context compression** | L1/L2/L3 layered anchors; graph compression (edge weights + PageRank, LRU cache); stem-matching recall (orchestrate �?orchestration); vector recall + RRF; RepoMap overview; adaptive budget |
97
97
  | **Retrieval & fidelity** | Golden-set regression gate (132 queries, Hit@5=100%, MRR=0.836, NDCG@5=0.601); separate anchor-recall and normalized body-coverage metrics persisted beside token savings |
98
98
  | **Vector index** | In-process memoization + disk persistence (fingerprint-checked, seconds to restore after MCP restart) |
99
99
  | **Storage backends** | `file` / `memory` / `sqlite` (FTS5, tokenizer-enhanced `searchtext`, camelCase searchable) / **`auto` (sqlite-first with fallback)** / `mcp-http` |
@@ -103,19 +103,19 @@ Single-purpose tools each do one thing well; GraphFlow combines graph + compress
103
103
  | **Model routing** | Smart / Economy tiers; multi-provider health probes and fallback (DeepSeek, OpenAI, Anthropic, Bailian, Doubao) |
104
104
  | **Workbench** | Plan DAG seeds function-topic containers; collapsed outline; click `topicId` to resume; drift forks a side branch; original Q/A stored via `assistantReply` |
105
105
  | **Observability** | `graphflow_diagnose` / `route diagnose`: provider health + graph stats + token savings + **flywheel health** (auto-capture, episodes, skills by class, session journal) + workbench outline |
106
- | **Agent surfaces** | CLI `--json`; MCP stdio and Streamable HTTP (stateless JSON or stateful SSE, 10 tools); auto-install into 15+ agents (incl. **Codex Windows NODE/NPX_CLI short-path MCP**) |
106
+ | **Agent surfaces** | CLI `--json`; MCP stdio and Streamable HTTP (stateless JSON or stateful SSE, 10 tools); auto-install into 15+ agents (incl. **Codex Windows NODE/NPX_CLI short-path MCP**). **HostAdapter** registry owns Cursor / Claude Code / DeepSeek Harness install · uninstall · doctor; other hosts still use the legacy installers |
107
107
  | **Evidence & governance** | Outcome evidence packages (commit/diff/tests), evidence backfill, tamper-evident audit chains, ADR/Invariant/APIContract/Test review states, artifact three-way merge/signing/encryption, retention/quarantine, release gates |
108
108
  | **Engineering quality** | TypeScript strict; vitest suite; `npm run ci` includes extension packaging and smoke tests |
109
109
 
110
110
  ### Positioning
111
111
 
112
- > GraphFlow is **not an orchestrating executor** — it is the **memory & context harness** for coding agents. Task execution is delegated to the host coding agent via bridge mode (honest semantics, no faked COMPLETED); GraphFlow's job is to make the agent see clearly and remember.
112
+ > GraphFlow is **not an orchestrating executor** �?it is the **memory & context harness** for coding agents. Task execution is delegated to the host coding agent via bridge mode (honest semantics, no faked COMPLETED); GraphFlow's job is to make the agent see clearly and remember.
113
113
 
114
114
  ## MCP tools (10)
115
115
 
116
116
  | Tool | Function |
117
117
  | --- | --- |
118
- | `graphflow_context` | Compressed context package (query → anchors + summaries; `topicId` / `assistantReply` to resume a workbench node or fill the pending answer; anchorId → expand) |
118
+ | `graphflow_context` | Compressed context package (query �?anchors + summaries; `topicId` / `assistantReply` to resume a workbench node or fill the pending answer; anchorId �?expand) |
119
119
  | `graphflow_plan` | Task planning (mode='simple' or 'insight'; seeds `workbench.topics` + `workbench.outline`; agent-delegated without an LLM) |
120
120
  | `graphflow_run` | Orchestration + bridge execution descriptor |
121
121
  | `graphflow_report_outcome` | Outcome backfill (incl. deviation classification), closes the learning flywheel |
@@ -130,14 +130,14 @@ Single-purpose tools each do one thing well; GraphFlow combines graph + compress
130
130
 
131
131
  ## Workbench navigation (v1.9.14)
132
132
 
133
- Everyday chat stays a single thread. Complex work seeds a **workbench of function-topic containers** from `graphflow_plan` — one canvas node per plan step, not one node per turn. Click a node and pass `topicId` to `graphflow_context` to refine that function or return to the mainline. Drift auto-forks an isolated side branch (`co_occurs`); the trunk is not overwritten. After answering, call `graphflow_context({ assistantReply })` so the original reply is stored. Outline titles are display labels only; next-turn context is Goal + ancestor titles + the node's original Q/A.
133
+ Everyday chat stays a single thread. Complex work seeds a **workbench of function-topic containers** from `graphflow_plan` �?one canvas node per plan step, not one node per turn. Click a node and pass `topicId` to `graphflow_context` to refine that function or return to the mainline. Drift auto-forks an isolated side branch (`co_occurs`); the trunk is not overwritten. After answering, call `graphflow_context({ assistantReply })` so the original reply is stored. Outline titles are display labels only; next-turn context is Goal + ancestor titles + the node's original Q/A.
134
134
 
135
135
  Wake the collapsed outline when you need it (still 10 MCP tools):
136
136
 
137
137
  ```bash
138
138
  graphflow workbench tree --json # CLI
139
139
  # VS Code / Cursor: GraphFlow: Workbench Tree (Activity Bar, default collapsed) or chat /tree
140
- # MCP: graphflow_diagnose → graph.workbenchOutline
140
+ # MCP: graphflow_diagnose �?graph.workbenchOutline
141
141
  graphflow context preview --topic-id "<topic:...>" "continue from this node"
142
142
  graphflow context preview --reply "original assistant answer"
143
143
  ```
@@ -153,6 +153,7 @@ graphflow run "update readme" # orchestrate (bridge)
153
153
  graphflow skill insights # skill insights
154
154
  graphflow skill report # flywheel contribution report
155
155
  graphflow mcp serve --http # stateless MCP Streamable HTTP (add --stateful for SSE sessions)
156
+ graphflow team serve # team graph JSON-RPC (tenant + RBAC; non-loopback requires auth)
156
157
  graphflow outcome backfill --evidence evidence.jsonl # close pending episodes with evidence packages
157
158
  graphflow governance release-gate # enforce proven-skill/fidelity/pending gates
158
159
  graphflow skill sync export # export team skill pack + golden queries (share via git)
@@ -164,7 +165,7 @@ graphflow doctor # install self-check
164
165
 
165
166
  ## Configuration
166
167
 
167
- Three-layer merge: global `~/.graphflow.config.json` → project `graphflow.config.json` → project `.graphflow/config.json`. Copy [graphflow.config.example.json](graphflow.config.example.json) to get started.
168
+ Three-layer merge: global `~/.graphflow.config.json` �?project `graphflow.config.json` �?project `.graphflow/config.json`. Copy [graphflow.config.example.json](graphflow.config.example.json) to get started.
168
169
 
169
170
  Key options:
170
171
 
@@ -185,16 +186,16 @@ Set `graphPolicy.transport` to `mcp-http` to host the graph on a remote Graphify
185
186
  { "graphPolicy": { "transport": "mcp-http", "mcpEndpoint": "http://graphify.team.internal:8080" } }
186
187
  ```
187
188
 
188
- A missing/malformed endpoint fails at config validation; connection or runtime request failures degrade transparently to local JSON storage (`graphPolicy.graphStorePath`, default `graphflow-out/graphflow-graph.json`) with a `logger.warn`, consistent with the sqlite→file fallback, never interrupting the agent. HTTP 401/403 (auth / RBAC deny) do **not** degrade — they throw. `graphflow team serve` implements `graph.read_snapshot` and `team.health`; third-party Graphify servers without those methods still fall back to the local mirror. See [docs/team-memory-security.md](docs/team-memory-security.md).
189
+ A missing/malformed endpoint fails at config validation; connection or runtime request failures degrade transparently to local JSON storage (`graphPolicy.graphStorePath`, default `graphflow-out/graphflow-graph.json`) with a `logger.warn`, consistent with the sqlite→file fallback, never interrupting the agent. HTTP 401/403 (auth / RBAC deny) do **not** degrade �?they throw. `graphflow team serve` implements `graph.read_snapshot` and `team.health`; third-party Graphify servers without those methods still fall back to the local mirror. See [docs/team-memory-security.md](docs/team-memory-security.md).
189
190
 
190
191
  ## Benchmarks
191
192
 
192
- - **Comprehensive**: [COMPREHENSIVE-RESULTS.md](benchmarks/COMPREHENSIVE-RESULTS.md) — P1–P6 six-dimension evaluation, overall **92.9%** (indexing 100% / compression 64.9% / planning 100% / learning 100% / bridge 100% / performance 99.7%)
193
- - **Independent-style**: [INDEPENDENT-RESULTS.md](benchmarks/INDEPENDENT-RESULTS.md) — CodeGraph-style 5-domain evaluation, Hit@5 **96%**, token savings **96.6%**, overall **96.2%**
194
- - **SWE-bench-style**: [SWE-BENCH-RESULTS.md](benchmarks/SWE-BENCH-RESULTS.md) — self-built 12-instance context-readiness eval; [SWE-BENCH-REAL-RESULTS.md](benchmarks/SWE-BENCH-REAL-RESULTS.md) — Flask real-project 10-instance file-recall eval (48.3%)
195
- - **Token savings**: [RESULTS.md](benchmarks/RESULTS.md) — 8 representative queries, **98.2%** savings, re-counted with independent gpt-tokenizer
196
- - **Retrieval quality**: [RETRIEVAL-EVAL-RESULTS.md](benchmarks/RETRIEVAL-EVAL-RESULTS.md) — 132 queries, Hit@5=100%, MRR=0.836, NDCG@5=0.601
197
- - **Skill flywheel A/B**: [SKILL-AB-RESULTS.md](benchmarks/SKILL-AB-RESULTS.md) — injection rate 100%, recall 100%, overhead 25.6 tok/task
193
+ - **Comprehensive**: [COMPREHENSIVE-RESULTS.md](benchmarks/COMPREHENSIVE-RESULTS.md) �?P1–P6 six-dimension evaluation, overall **92.9%** (indexing 100% / compression 64.9% / planning 100% / learning 100% / bridge 100% / performance 99.7%)
194
+ - **Independent-style**: [INDEPENDENT-RESULTS.md](benchmarks/INDEPENDENT-RESULTS.md) �?CodeGraph-style 5-domain evaluation, Hit@5 **96%**, token savings **96.6%**, overall **96.2%**
195
+ - **SWE-bench-style**: [SWE-BENCH-RESULTS.md](benchmarks/SWE-BENCH-RESULTS.md) �?self-built 12-instance context-readiness eval; [SWE-BENCH-REAL-RESULTS.md](benchmarks/SWE-BENCH-REAL-RESULTS.md) �?Flask real-project 10-instance file-recall eval (48.3%)
196
+ - **Token savings**: [RESULTS.md](benchmarks/RESULTS.md) �?8 representative queries, **98.2%** savings, re-counted with independent gpt-tokenizer
197
+ - **Retrieval quality**: [RETRIEVAL-EVAL-RESULTS.md](benchmarks/RETRIEVAL-EVAL-RESULTS.md) �?132 queries, Hit@5=100%, MRR=0.836, NDCG@5=0.601
198
+ - **Skill flywheel A/B**: [SKILL-AB-RESULTS.md](benchmarks/SKILL-AB-RESULTS.md) �?injection rate 100%, recall 100%, overhead 25.6 tok/task
198
199
 
199
200
  ## VS Code / Cursor extension
200
201
 
@@ -224,7 +225,7 @@ ln -s /absolute/path/to/GraphFlow ~/.cursor/plugins/local/graphflow
224
225
 
225
226
  Docs: [Context Engineering contract](docs/context-contract.md) · [Experience memory](docs/experience-memory.md)
226
227
 
227
- **Uninstall:** Removing the Agent Plugin in Cursor only drops the plugin package. Skills/Rules/MCP written by `graphflow install` remain and will keep steering the agent — run:
228
+ **Uninstall:** Removing the Agent Plugin in Cursor only drops the plugin package. Skills/Rules/MCP written by `graphflow install` remain and will keep steering the agent �?run:
228
229
 
229
230
  ```bash
230
231
  npx @roarpeng/graphflow uninstall
@@ -232,39 +233,39 @@ npx @roarpeng/graphflow uninstall
232
233
 
233
234
  That removes user + workspace MCP entries, `skills/graphflow` folders, GraphFlow rules/instruction blocks, Claude Code hooks, and the DeepSeek Harness `cordis.patch.yml` overlay. Also delete any local symlink under `~/.cursor/plugins/local/graphflow` if you used one.
234
235
 
235
- ## DeepSeek Harness 插件（用法与能力）
236
+ ## DeepSeek Harness 插件（用法与能力�?
236
237
 
237
- GraphFlow 是 [DeepSeek Harness](https://www.deepseek.com/harness/en/) 的 [`dsh-plugin`](https://github.com/topics/dsh-plugin)。包内 `dsh.bundle` + `cordis.patch.yml` 会把 GraphFlow MCP 挂到内置 `@deepseek-ai/dsh-mcp-client`，并把 `@roarpeng/graphflow/dsh` glue 插入插件树。模型看到的工具名是 `mcp__graphflow__graphflow_*`。中文说明见 [README.zh.md](README.zh.md)。
238
+ GraphFlow �?[DeepSeek Harness](https://www.deepseek.com/harness/en/) �?[`dsh-plugin`](https://github.com/topics/dsh-plugin)。包�?`dsh.bundle` + `cordis.patch.yml` 会把 GraphFlow MCP 挂到内置 `@deepseek-ai/dsh-mcp-client`，并�?`@roarpeng/graphflow/dsh` glue 插入插件树。模型看到的工具名是 `mcp__graphflow__graphflow_*`。中文说明见 [README.zh.md](README.zh.md)�?
238
239
 
239
- **在 dsh 上能工作 vs 不能工作：**
240
+ **�?dsh 上能工作 vs 不能工作�?*
240
241
 
241
242
  | 能力 | dsh |
242
243
  | --- | --- |
243
- | 10 个 MCP 工具（`mcp__graphflow__graphflow_*`），stdio `cwd` = 会话工作区 | 是 |
244
- | Skill（on-demand `skill({name:"graphflow"})`；bundle glue 注册，不必先 `graphflow install`） | 是 |
245
- | 会话结束飞轮：仅 `agent/disposed` 关闭 pending episode（不是 live `session/flush`；`GRAPHFLOW_AUTO_CAPTURE=0` 可关） | 是 |
246
- | 首轮短 hint：先调 `graphflow_context`（`rootDir` = cwd） | 是 |
247
- | Workbench 数据（`topicId` / outline）经 MCP `graphflow_context` / `graphflow_diagnose` | 是 |
248
- | VS Code/Cursor 图谱面板、Settings webview、Workbench Tree、`@graphflow` chat | **否**（宿主 UI，不移植） |
249
- | Cursor Agent Plugins 1.0 发现 | **否**（dsh 用 `dsh.bundle`） |
250
- | Claude Code `SessionStart/End/Stop` **文件** hooks | **否**（dsh analog 是上面的 glue） |
244
+ | 10 �?MCP 工具（`mcp__graphflow__graphflow_*`），stdio `cwd` = 会话工作�?| �?|
245
+ | Skill（on-demand `skill({name:"graphflow"})`；bundle glue 注册，不必先 `graphflow install`�?| �?|
246
+ | 会话结束飞轮：仅 `agent/disposed` 关闭 pending episode（不�?live `session/flush`；`GRAPHFLOW_AUTO_CAPTURE=0` 可关�?| �?|
247
+ | 首轮�?hint：先�?`graphflow_context`（`rootDir` = cwd�?| �?|
248
+ | Workbench 数据（`topicId` / outline）经 MCP `graphflow_context` / `graphflow_diagnose` | �?|
249
+ | VS Code/Cursor 图谱面板、Settings webview、Workbench Tree、`@graphflow` chat | **�?*（宿�?UI，不移植�?|
250
+ | Cursor Agent Plugins 1.0 发现 | **�?*（dsh �?`dsh.bundle`�?|
251
+ | Claude Code `SessionStart/End/Stop` **文件** hooks | **�?*（dsh analog 是上面的 glue�?|
251
252
 
252
- **装进某个 profile（推荐）：**
253
+ **装进某个 profile（推荐）�?*
253
254
 
254
255
  ```bash
255
256
  dsh plugin --profile web add @roarpeng/graphflow
256
257
  npx @deepseek-ai/dsh web
257
258
  ```
258
259
 
259
- **或在已有 `~/.dsh` 时写 home 级 overlay（对所有 profile 生效）：**
260
+ **或在已有 `~/.dsh` 时写 home �?overlay（对所�?profile 生效）：**
260
261
 
261
262
  ```bash
262
263
  npx @roarpeng/graphflow install
263
264
  ```
264
265
 
265
- 会写入 `$DSH_HOME/cordis.patch.yml`（MCP + glue）与 `$DSH_HOME/skills/graphflow/SKILL.md`。卸载：`npx @roarpeng/graphflow uninstall`，或 `dsh plugin --profile web remove @roarpeng/graphflow`。`graphflow doctor` 会检查 overlay、glue、skill。
266
+ 会写�?`$DSH_HOME/cordis.patch.yml`（MCP + glue）与 `$DSH_HOME/skills/graphflow/SKILL.md`。卸载：`npx @roarpeng/graphflow uninstall`，或 `dsh plugin --profile web remove @roarpeng/graphflow`。`graphflow doctor` 会检�?overlay、glue、skill�?
266
267
 
267
- **用法：** 第一轮先 `mcp__graphflow__graphflow_context`（传入 `rootDir` = 仓库绝对路径），复杂任务再 `graphflow_plan`；改完代码后 `graphflow_index`；若走了 `graphflow_run`，结束后必须 `graphflow_report_outcome`。不要在 patch 里写死 `GRAPHFLOW_WORKSPACE_ROOT`。
268
+ **用法�?* 第一轮先 `mcp__graphflow__graphflow_context`（传�?`rootDir` = 仓库绝对路径），复杂任务�?`graphflow_plan`；改完代码后 `graphflow_index`；若走了 `graphflow_run`，结束后必须 `graphflow_report_outcome`。不要在 patch 里写�?`GRAPHFLOW_WORKSPACE_ROOT`�?
268
269
 
269
270
  ## Agent integrations
270
271
 
@@ -277,17 +278,17 @@ npx @roarpeng/graphflow uninstall # remove MCP + Skill + Rules + hooks
277
278
  npx @roarpeng/graphflow init # write a minimal project config
278
279
  ```
279
280
 
280
- Supported: Cursor, VS Code, Trae (incl. CN), Claude Code, Windsurf, Cline, Roo Code, Kilo Code, Gemini CLI, Codex, Antigravity, Opencode, Qoder, Amazon Q, Zed, Continue, DeepSeek Harness (`dsh`), and more (15+).
281
+ Supported: Cursor, VS Code, Trae (incl. CN), Claude Code, Windsurf, Cline, Roo Code, Kilo Code, Gemini CLI, Codex, Antigravity, Opencode, Qoder, Amazon Q, Zed, Continue, DeepSeek Harness (`dsh`), and more (15+). Cursor, Claude Code, and DeepSeek Harness go through the HostAdapter registry (`installViaHostAdapter`); remaining hosts still use the legacy installers.
281
282
 
282
283
  | Path | When to use |
283
284
  | --- | --- |
284
285
  | **Agent Plugins** | Preferred single-host Skill + MCP discovery |
285
286
  | **`graphflow install`** | Rules / multi-agent / non-plugin hosts |
286
- | **`graphflow uninstall`** | After removing a plugin (or anytime) — clears leftover Skill/MCP/Rules |
287
+ | **`graphflow uninstall`** | After removing a plugin (or anytime) �?clears leftover Skill/MCP/Rules |
287
288
 
288
289
  ## Protocol
289
290
 
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).
291
+ [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).
291
292
 
292
293
  ## Community
293
294
 
@@ -305,7 +306,7 @@ npm install
305
306
  npm run ci # lint + build + tests + extension packaging + smoke
306
307
  ```
307
308
 
308
- Requires Node.js ≥ 20, npm ≥ 10. Expected: lint clean, build succeeds, 961 tests pass.
309
+ Requires Node.js �?20, npm �?10. Expected: lint clean, build succeeds, 961 tests pass.
309
310
 
310
311
  ## Project structure
311
312
 
@@ -317,14 +318,14 @@ GraphFlow/
317
318
  ├── dsh/plugin.mjs # dsh ESM glue: skill register + session-end capture
318
319
  ├── skills/graphflow/ # portable Agent Skill (canonical SKILL.md)
319
320
  ├── src/
320
- │ ├── core/ # orchestration core: orchestrator, triage, dag-engine, agent-delegation
321
- │ ├── graph/ # indexing, context slicing, graph compression, sqlite/auto storage, snapshot
322
- │ ├── routing/ # model routing and health probes (5 providers)
323
- │ ├── learning/ # embeddings, episodic, skill-flywheel, hnsw, nightly
324
- │ ├── agents/ # ATP schema, planner, insight, brainstormer
325
- │ └── surfaces/
326
- │ ├── cli/ # CLI + runtime
327
- │ └── mcp/ # MCP server (10 tools)
321
+ �? ├── core/ # orchestration core: orchestrator, triage, dag-engine, agent-delegation
322
+ �? ├── graph/ # indexing, context slicing, graph compression, sqlite/auto storage, snapshot
323
+ �? ├── routing/ # model routing and health probes (5 providers)
324
+ �? ├── learning/ # embeddings, episodic, skill-flywheel, hnsw, nightly
325
+ �? ├── agents/ # ATP schema, planner, insight, brainstormer
326
+ �? └── surfaces/
327
+ �? ├── cli/ # CLI + runtime
328
+ �? └── mcp/ # MCP server (10 tools)
328
329
  ├── tests/ # 142 files / 961 tests (incl. governance foundation and MCP HTTP/stdio matrix)
329
330
  ├── benchmarks/ # comprehensive + independent + SWE-bench + token savings + skill A/B (reproducible)
330
331
  ├── docs/ # ATP spec + context contract + experience memory + flywheel reproduction + GraphFlow/Serena
package/README.zh.md CHANGED
@@ -2,23 +2,24 @@
2
2
 
3
3
  [English](README.md) | 中文
4
4
 
5
- [![npm version](https://img.shields.io/badge/npm-1.15.2-blue)](https://www.npmjs.com/package/@roarpeng/graphflow)
5
+ [![npm version](https://img.shields.io/badge/npm-1.15.4-blue)](https://www.npmjs.com/package/@roarpeng/graphflow)
6
6
 
7
- > **给编程 Agent 用的记忆与上下文 harness。** 本地优先的代码知识图谱 · 有界上下文压缩（约 98% token 节省） · 跨会话学习飞轮。
7
+ > **给编�?Agent 用的记忆与上下文 harness�?* 本地优先的代码知识图�?· 有界上下文压缩（�?98% token 节省�?· 跨会话学习飞轮�?
8
8
 
9
- GraphFlow 把 **记忆 + hooks + skills** 做成可移植的 MCP 表面（Cursor、Claude Code、DeepSeek Harness、15+ Agent），让无状态模型变成可长期工作的编码助手。v1.12 增加 fidelity 指标、SKILL.md 互操作和 Concept / Requirement 工程知识层。纯 TypeScript/Node，CLI + MCP + VS Code 扩展，完全离线，无需 API Key。
10
- v1.13 增加 evidence package、治理审查、签名/加密 artifact、release gate 和 MCP HTTP 认证。
9
+ GraphFlow �?**记忆 + hooks + skills** 做成可移植的 MCP 表面（Cursor、Claude Code、DeepSeek Harness�?5+ Agent），让无状态模型变成可长期工作的编码助手。它**不是编排执行�?*：先压缩上下文、再规划，执行交给宿�?Agent。纯 TypeScript/Node，CLI + MCP + VS Code 扩展，完全离线，无需 API Key�?
11
10
 
12
- ## 快速开始
11
+ **v1.15.3** 已发：团队共享记�?MVP（`graphflow team serve` + RBAC）、Cursor / Claude Code �?HostAdapter 安装路径、飞轮公开复现（`npm run proof:flywheel`）、Serena �?MCP 指南，以�?R4 上下文打包去重。v1.14 把对话图做成一等资产（时间边、召回、fork/回放）。v1.12–v1.13 �?fidelity / 治理平面仍在�?
12
+
13
+ ## 快速开�?
13
14
 
14
15
  ```bash
15
16
  npx @roarpeng/graphflow graph index .
16
17
  npx @roarpeng/graphflow context preview "orchestrator" --json
17
- graphflow mcp serve --http # MCP Streamable HTTP（默认 stateless；--stateful 开启 SSE session）
18
- npx @roarpeng/graphflow install # 自动接入已检测到的 Agent（含 dsh）
18
+ graphflow mcp serve --http # MCP Streamable HTTP（默�?stateless�?-stateful 开�?SSE session�?
19
+ npx @roarpeng/graphflow install # 自动接入已检测到�?Agent（含 dsh�?
19
20
  ```
20
21
 
21
- MCP 入口：
22
+ MCP 入口�?
22
23
 
23
24
  ```json
24
25
  {
@@ -31,63 +32,75 @@ MCP 入口：
31
32
  }
32
33
  ```
33
34
 
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
+ 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)）�?
36
+
37
+ ## 本版要点（v1.15�?
38
+
39
+ | 能力 | 说明 |
40
+ | --- | --- |
41
+ | **Harness** | 记忆动态、按任务召回（图锚点 + 压缩摘要 + 历史 episode + skill），有明�?L0–L3 token 预算 |
42
+ | **飞轮复现** | `npm run proof:flywheel` 离线串检�?/ skill A/B / memory A/B；见 [docs/flywheel-reproduction.md](docs/flywheel-reproduction.md) |
43
+ | **团队记忆** | `graphflow team serve`：tenant 隔离 + viewer/contributor/admin；非 loopback 默认强制认证；`diagnose` 报告连通与 RBAC。见 [docs/team-memory-security.md](docs/team-memory-security.md) |
44
+ | **HostAdapter** | Cursor / Claude Code / DeepSeek Harness �?install / uninstall / doctor 走注册表；其余宿主仍走遗留安装器 |
45
+ | **Serena** | 并列第二�?MCP：context/plan �?Serena 编辑 �?`report_outcome` |
46
+
47
+ 完整英文对照与基准数字：[README.md](README.md)�?
35
48
 
36
- ## 工作台脉络（v1.9.14）
49
+ ## 工作台脉络（v1.9.14�?
37
50
 
38
- 日常 Chat 仍是单线。复杂任务用 `graphflow_plan` 播种**功能主题容器**（画布上是计划步骤，不是一轮一节点）。点击节点，把 `topicId` 传给 `graphflow_context` 即可在该功能上继续或回到主线。问法跑偏会 Fork 孤立旁支，主线不被刷脏。答完再调 `graphflow_context({ assistantReply })` 回填原文。树上的标题只用于显示；下一轮必读是 Goal + 祖先标题 + 该节点原文 Q/A。
51
+ 日常 Chat 仍是单线。复杂任务用 `graphflow_plan` 播种**功能主题容器**（画布上是计划步骤，不是一轮一节点）。点击节点，�?`topicId` 传给 `graphflow_context` 即可在该功能上继续或回到主线。问法跑偏会 Fork 孤立旁支，主线不被刷脏。答完再�?`graphflow_context({ assistantReply })` 回填原文。树上的标题只用于显示；下一轮必读是 Goal + 祖先标题 + 该节点原�?Q/A�?
39
52
 
40
- 按需唤醒（仍是 10 个 MCP 工具，不新增）：
53
+ 按需唤醒（仍�?10 �?MCP 工具，不新增）：
41
54
 
42
55
  ```bash
43
56
  graphflow workbench tree --json
44
57
  # VS Code / Cursor：GraphFlow: Workbench Tree（活动栏默认收起）或 Chat /tree
45
- # MCP：graphflow_diagnose → graph.workbenchOutline
58
+ # MCP：graphflow_diagnose �?graph.workbenchOutline
46
59
  graphflow context preview --topic-id "<topic:...>" "在此节点继续"
47
60
  graphflow context preview --reply "助手原文回答"
48
61
  ```
49
62
 
50
63
  ## DeepSeek Harness 插件
51
64
 
52
- GraphFlow 本身就是一个 **dsh 插件包**（topic：`dsh-plugin`）。`package.json` 声明 `dsh.bundle`，根目录 `cordis.patch.yml` 把 GraphFlow MCP 与 ESM glue 插入 Harness 的插件树。
65
+ GraphFlow 本身就是一�?**dsh 插件�?*（topic：`dsh-plugin`）。`package.json` 声明 `dsh.bundle`，根目录 `cordis.patch.yml` �?GraphFlow MCP �?ESM glue 插入 Harness 的插件树�?
53
66
 
54
67
  ### 能力
55
68
 
56
- | 能力 | 说明 | dsh 工具名 |
69
+ | 能力 | 说明 | dsh 工具�?|
57
70
  | --- | --- | --- |
58
- | 压缩上下文 | 查询 → 锚点 + 摘要；按 `anchorId` 展开 | `mcp__graphflow__graphflow_context` |
59
- | 任务规划 | simple / insight；无 LLM 时桥接宿主 | `mcp__graphflow__graphflow_plan` |
60
- | 桥接执行包 | 规划 + 压缩上下文，不代跑代码 | `mcp__graphflow__graphflow_run` |
61
- | 结果回填 | 关闭技能飞轮 | `mcp__graphflow__graphflow_report_outcome` |
71
+ | 压缩上下�?| 查询 �?锚点 + 摘要；按 `anchorId` 展开 | `mcp__graphflow__graphflow_context` |
72
+ | 任务规划 | simple / insight；无 LLM 时桥接宿�?| `mcp__graphflow__graphflow_plan` |
73
+ | 桥接执行�?| 规划 + 压缩上下文，不代跑代�?| `mcp__graphflow__graphflow_run` |
74
+ | 结果回填 | 关闭技能飞�?| `mcp__graphflow__graphflow_report_outcome` |
62
75
  | ATP Insight | submit / merge | `mcp__graphflow__graphflow_insight` |
63
- | 建图 | 增量 / 单文件 / 全量重建 | `mcp__graphflow__graphflow_index` |
64
- | 技能洞察 | 历史任务沉淀的 skill | `mcp__graphflow__graphflow_skill_insights` |
65
- | 诊断 | 图谱、路由、token 节省、飞轮健康 | `mcp__graphflow__graphflow_diagnose` |
76
+ | 建图 | 增量 / 单文�?/ 全量重建 | `mcp__graphflow__graphflow_index` |
77
+ | 技能洞�?| 历史任务沉淀�?skill | `mcp__graphflow__graphflow_skill_insights` |
78
+ | 诊断 | 图谱、路由、token 节省、飞轮健�?| `mcp__graphflow__graphflow_diagnose` |
66
79
  | 产物 | 图谱 import / export | `mcp__graphflow__graphflow_artifact` |
67
- | 技能指南 | 给已连接 Agent 的用法说明 | `mcp__graphflow__graphflow_skill_guide` |
80
+ | 技能指�?| 给已连接 Agent 的用法说�?| `mcp__graphflow__graphflow_skill_guide` |
68
81
 
69
- | 在 dsh 上 | 状态 |
82
+ | �?dsh �?| 状�?|
70
83
  | --- | --- |
71
- | 上述 10 个 MCP 工具（stdio `cwd` = 会话工作区） | 支持 |
72
- | Skill（bundle glue 注册；`dsh plugin add` 即可） | 支持 |
73
- | 会话结束飞轮（仅 `agent/disposed` → `outcome report`；不是 live `session/flush`） | 支持 |
74
- | VS Code/Cursor 图谱面板、Settings、Workbench Tree、`@graphflow` chat | **不移植** |
75
- | Cursor Agent Plugins 发现 / Claude Code Session* **文件** hooks | **不移植**（dsh 用 bundle + glue） |
84
+ | 上述 10 �?MCP 工具（stdio `cwd` = 会话工作区） | 支持 |
85
+ | Skill（bundle glue 注册；`dsh plugin add` 即可�?| 支持 |
86
+ | 会话结束飞轮（仅 `agent/disposed` �?`outcome report`；不�?live `session/flush`�?| 支持 |
87
+ | VS Code/Cursor 图谱面板、Settings、Workbench Tree、`@graphflow` chat | **不移�?* |
88
+ | Cursor Agent Plugins 发现 / Claude Code Session* **文件** hooks | **不移�?*（dsh �?bundle + glue�?|
76
89
 
77
- 核心价值：本地 AST 知识图谱、L1–L3 分层压缩（实测约 98% token 节省）、跨会话 Episodic / Skill 飞轮。GraphFlow **不执行代码**，只给宿主 Agent 压缩上下文和计划。Workbench 数据走 MCP `graphflow_context` / `graphflow_diagnose` 即可。
90
+ 核心价值：本地 AST 知识图谱、L1–L3 分层压缩（实测约 98% token 节省）、跨会话 Episodic / Skill 飞轮。GraphFlow **不执行代�?*，只给宿�?Agent 压缩上下文和计划。Workbench 数据�?MCP `graphflow_context` / `graphflow_diagnose` 即可�?
78
91
 
79
92
  ### 安装
80
93
 
81
- **方式 A：装进某个 profile（推荐）**
94
+ **方式 A：装进某�?profile（推荐）**
82
95
 
83
96
  ```bash
84
97
  dsh plugin --profile web add @roarpeng/graphflow
85
98
  npx @deepseek-ai/dsh web
86
99
  ```
87
100
 
88
- **方式 B：home 级 overlay（所有 profile 生效）**
101
+ **方式 B：home �?overlay（所�?profile 生效�?*
89
102
 
90
- 先有 `$DSH_HOME`（默认 `~/.dsh`），再执行：
103
+ 先有 `$DSH_HOME`（默�?`~/.dsh`），再执行：
91
104
 
92
105
  ```bash
93
106
  npx @roarpeng/graphflow install
@@ -108,21 +121,21 @@ dsh plugin --profile web add /absolute/path/to/GraphFlow
108
121
 
109
122
  ### 用法
110
123
 
111
- 1. 任何读代码、改代码、排错之前，先调 `mcp__graphflow__graphflow_context`，并传入当前仓库绝对路径 `rootDir`。
112
- 2. 用返回的 `summary` / `anchors` / `tokenBudget` 当第一上下文；不够再按 `anchorId` 展开。
113
- 3. 跨多文件或范围不清时，再调 `graphflow_plan`；结果里的 `workbench.topics` 是功能节点。之后可用 `topicId` 细化，或 `graphflow_diagnose.graph.workbenchOutline` / `graphflow workbench tree` 唤醒脉络树。
114
- 4. 改完文件后调 `graphflow_index`（单文件可传 `filePath`）。
115
- 5. 若走了 `graphflow_run`，结束后必须 `graphflow_report_outcome`（`episodeId` + `success`）。
116
- 6. 回答用户后应再调 `graphflow_context({ assistantReply })` 回填原文。
117
- 7. 中文问题请同时传 `englishQuery`（英文文件名 / 符号名），不要只用泛化中文词检索。
124
+ 1. 任何读代码、改代码、排错之前，先调 `mcp__graphflow__graphflow_context`，并传入当前仓库绝对路径 `rootDir`�?
125
+ 2. 用返回的 `summary` / `anchors` / `tokenBudget` 当第一上下文；不够再按 `anchorId` 展开�?
126
+ 3. 跨多文件或范围不清时，再�?`graphflow_plan`；结果里�?`workbench.topics` 是功能节点。之后可�?`topicId` 细化，或 `graphflow_diagnose.graph.workbenchOutline` / `graphflow workbench tree` 唤醒脉络树�?
127
+ 4. 改完文件后调 `graphflow_index`（单文件可传 `filePath`）�?
128
+ 5. 若走�?`graphflow_run`，结束后必须 `graphflow_report_outcome`（`episodeId` + `success`）�?
129
+ 6. 回答用户后应再调 `graphflow_context({ assistantReply })` 回填原文�?
130
+ 7. 中文问题请同时传 `englishQuery`（英文文件名 / 符号名），不要只用泛化中文词检索�?
118
131
 
119
- 不要在 `cordis.patch.yml` 里写死 `GRAPHFLOW_WORKSPACE_ROOT`。
132
+ 不要�?`cordis.patch.yml` 里写�?`GRAPHFLOW_WORKSPACE_ROOT`�?
120
133
 
121
134
  ### 卸载
122
135
 
123
136
  ```bash
124
137
  npx @roarpeng/graphflow uninstall
125
- # 若只从某个 profile 移除 bundle：
138
+ # 若只从某�?profile 移除 bundle�?
126
139
  dsh plugin --profile web remove @roarpeng/graphflow
127
140
  ```
128
141
 
@@ -130,12 +143,12 @@ dsh plugin --profile web remove @roarpeng/graphflow
130
143
 
131
144
  | 路径 | 适用 |
132
145
  | --- | --- |
133
- | [Agent Plugins 1.0](https://agent-plugins.org)（`plugin.json` + `mcp.json` + `skills/`） | Cursor 等支持插件清单的宿主 |
134
- | `npx @roarpeng/graphflow install` | Rules / 多 Agent / 非插件宿主（含 dsh overlay） |
146
+ | [Agent Plugins 1.0](https://agent-plugins.org)（`plugin.json` + `mcp.json` + `skills/`�?| Cursor 等支持插件清单的宿主 |
147
+ | `npx @roarpeng/graphflow install` | Rules / �?Agent / 非插件宿主（�?dsh overlay�?|
135
148
  | VS Code / Cursor 扩展 | Open VSX：`roarpeng.graphflow` |
136
149
 
137
150
  ## 更多
138
151
 
139
152
  完整英文文档、基准与协议：[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
153
 
141
- 第三方复现飞轮 / 记忆 A/B / 检索自测：`npm run proof:flywheel`（说明见 [docs/flywheel-reproduction.md](docs/flywheel-reproduction.md)）。
154
+ 第三方复现飞�?/ 记忆 A/B / 检索自测：`npm run proof:flywheel`（说明见 [docs/flywheel-reproduction.md](docs/flywheel-reproduction.md)）�?
package/cordis.patch.yml CHANGED
@@ -20,7 +20,10 @@
20
20
  # 调用约定: 先 context（传 rootDir），复杂任务再 plan；改完代码后 index；
21
21
  # 若走了 run，结束后必须 report_outcome。不要写死 GRAPHFLOW_WORKSPACE_ROOT。
22
22
  #
23
- # graphflow install 也会把同一段 insert 写入 $DSH_HOME/cordis.patch.yml。
23
+ # graphflow install（无 profile 包时）只写 MCP 行到 $DSH_HOME/cordis.patch.yml；
24
+ # 已 `dsh plugin add` / profile 有包时会清空 home overlay，由 bundle 独占 MCP+glue
25
+ # （避免 duplicate loader entry id / ERR_MODULE_NOT_FOUND）。
26
+ # 完整安装请优先: dsh plugin --profile web add @roarpeng/graphflow
24
27
 
25
28
  - insert:
26
29
  - id: mcp-graphflow
package/dist/graph/context-package-core.d.ts ADDED
@@ -0,0 +1,59 @@
1
+ /**
2
+ * Shared context-packaging core.
3
+ *
4
+ * `buildLayeredContextPackage` and `buildEnhancedContextPackage` used to
5
+ * duplicate retrieval + L1/L2/L3 quota packing (~60% overlap). Both public
6
+ * functions keep their signatures and extras; this module owns the common
7
+ * recall/pack steps so behavior stays identical.
8
+ */
9
+ import type { GraphNode } from "../core/types.js";
10
+ import type { GraphClient } from "./client-factory.js";
11
+ import type { ContextAnchorItem, LayeredContextPackage, LayeredPackageOptions, SubgraphExpansionOptions } from "./context-slicer-types.js";
12
+ export type DuplicateModulePolicy = "continue" | "break";
13
+ export interface PackState {
14
+ summaryChannel: string[];
15
+ anchorChannel: ContextAnchorItem[];
16
+ added: Set<string>;
17
+ quota: {
18
+ l1: number;
19
+ l2: number;
20
+ l3: number;
21
+ };
22
+ used: {
23
+ l1: number;
24
+ l2: number;
25
+ l3: number;
26
+ };
27
+ maxTokens: number;
28
+ maxAnchors?: number;
29
+ }
30
+ export interface PackBudget {
31
+ tokens: number;
32
+ truncated: boolean;
33
+ }
34
+ /**
35
+ * Governance pins for L3: Decision/goal nodes that packing must prefer so
36
+ * budget truncation cannot drop alignment / deviation / goal constraints.
37
+ */
38
+ export declare function isPinnedL3Node(node: GraphNode): boolean;
39
+ export declare function createPackState(maxTokens: number, options?: LayeredPackageOptions, maxAnchors?: number): PackState;
40
+ export declare function toLayeredPackage(state: PackState, budget: PackBudget): LayeredContextPackage;
41
+ export declare function expandSubgraph(client: GraphClient, seedIds: string[], options?: SubgraphExpansionOptions): Promise<GraphNode[]>;
42
+ export declare function vectorRecall(nodes: GraphNode[], queryEmbedding: number[], topK: number, minSimilarity: number): GraphNode[];
43
+ export declare function collectKeywordHits(client: GraphClient, query: string, options?: LayeredPackageOptions): Promise<GraphNode[]>;
44
+ /**
45
+ * Fuse keyword hits with vector recall when enabled.
46
+ * Returns `null` when vector recall is off so callers keep their current hit list
47
+ * (enhanced may have already applied symbol boosting).
48
+ * On failure, returns the original keyword hits (same reset both builders used).
49
+ */
50
+ export declare function fuseVectorRecallIfEnabled(client: GraphClient, query: string, keywordHits: GraphNode[], options: LayeredPackageOptions | undefined, logLabel: string): Promise<GraphNode[] | null>;
51
+ export declare function preparePackageHits(hits: GraphNode[], query: string, options: LayeredPackageOptions | undefined, snapshotNodes: GraphNode[] | undefined): GraphNode[];
52
+ export declare function tryAppendL3Node(node: GraphNode, state: PackState, budget: PackBudget): "packed" | "budget" | "skip";
53
+ export declare function packPrimaryHits(hits: GraphNode[], state: PackState, budget: PackBudget): void;
54
+ export declare function injectL2Modules(client: GraphClient, hits: GraphNode[], state: PackState, budget: PackBudget, duplicatePolicy: DuplicateModulePolicy): Promise<void>;
55
+ export declare function injectL3SkillsAndPins(client: GraphClient, query: string, options: LayeredPackageOptions | undefined, snapshotNodes: GraphNode[] | undefined, state: PackState, budget: PackBudget): Promise<void>;
56
+ export declare function injectDialogueTurns(client: GraphClient, query: string, options: LayeredPackageOptions | undefined, state: PackState, budget: PackBudget): Promise<void>;
57
+ export declare function injectSameFileAndImportExpansion(client: GraphClient, snapshotNodes: GraphNode[] | undefined, state: PackState, budget: PackBudget): Promise<void>;
58
+ export declare function injectNeighborExpansion(client: GraphClient, options: LayeredPackageOptions | undefined, state: PackState, budget: PackBudget): Promise<void>;
59
+ //# sourceMappingURL=context-package-core.d.ts.map
package/dist/graph/context-package-core.d.ts.map ADDED
@@ -0,0 +1 @@
1
+ {"version":3,"file":"context-package-core.d.ts","sourceRoot":"","sources":["../../src/graph/context-package-core.ts"],"names":[],"mappings":"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"}