@roarpeng/graphflow 1.15.5 → 1.16.0

package/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 All notable changes to this project are documented in this file.
 
+## [1.16.0] - 2026-09-08
+
+### Added
+
+- **R4 集成层模块化收口（HostAdapter 全宿主）**：新增通用 profile 驱动切片 `src/integrations/profile-host-installer.ts`。`installViaHostAdapter` / `uninstallViaHostAdapter` / `getHostAdapterInstallStatus` 现覆盖全部 19 个注册宿主——4 个手写切片（DeepSeek Harness / Cursor / Claude Code / Kimi Code）+ 15 个 profile 宿主（Trae、VS Code、Windsurf、Cline、Roo Code、Kilo Code、PearAI、Gemini、Codex、Antigravity、Amazon Q、Zed、Continue、Qoder、Opencode）。
+- **`skill-installer` 精确目标原语**：`installSkillToTargets` / `removeSkillFromTargets` / `installInstructionsToTargets` / `removeInstructionsFromTargets`——单宿主 install slice 只写自己的 `skills/graphflow/SKILL.md` 与受管指令块，不再顺带写其它已检测宿主。
+
+### Changed
+
+- **CLI 三处宿主硬编码改为注册表遍历**：`install` / `uninstall` / `doctor` 统一走 `HOST_ADAPTER_MIGRATED_IDS`；`uninstall` 先按宿主切片清理，再跑遗留清扫（工作区 MCP 条目、Trae 用户 Skill、项目级规则）。新增宿主不再需要改 `init.ts`。
+- **`agent-profiles` 注册表并入 `buildAgentProfiles()`**：`opencode` 等仅在新注册表登记的宿主获得 MCP 安装/状态支持；遗留条目在同 id 时优先，已写入的 marker / target 路径不变。
+- **`runOrchestration` 拆分**：新增 `src/core/orchestrator-phases.ts`，把 ~360 行大函数拆为 `runSimplePhase` / `resolvePlanPhase` / `runBridgePhase` / `runLlmDagPhase` + `makeDagNodeRunner`；`orchestrator.ts` 只保留模式解析、上下文装配与 triage。日志、图/技能同步顺序、`triageId` 传播（含 LLM 失败路径有意不带 `triageId`）逐字保持。
+
+### Fixed
+
+- **mcp-http 请求超时可配置**：新增 `GRAPHFLOW_MCP_TIMEOUT_MS`，`createGraphClient()` 据此设置 `GraphifyMcpClient.timeoutMs`（默认仍 15s）。当端点连接挂起（而非被拒绝）时，15s × 多次图操作会拖长单次运行；该开关让 CI / 测试可以快速失败。
+- **临时目录残留图谱劫持工作区发现**：MCP 服务以 cwd 位于 `%TEMP%` 启动时会在那里写 `graphflow-out/graphflow-graph.json`，而 `hasProjectWorkspaceMarkers()` 把该文件当作项目标记，于是 `discoverWorkspaceRoot()` 对**所有**位于临时目录之下的项目都返回临时目录根，m49 工作区隔离用例随之失败。新增 `isSystemTempDirectory()` 作为向上遍历边界（不改动 `isUsableWorkspaceFallback`，保留显式 cwd 回退语义），并给 `discoverWorkspaceRoot()` 增加 `extraBoundaries` 测试钩子。
+- **README.md / README.zh.md UTF-8 损坏**：v1.15.4 的版本号提交（`a8ae51d`）在改写两个 README 时把约 100 个多字节序列的第三字节替换成 `?`——中文、破折号、箭头、勾选全部变成乱码并随 npm 包发布。已按 `e7e429d`（v1.15.3 文档提交）逐行核对后重建，仅保留有意的版本号与 HostAdapter 文案改动；同时补齐 README.zh.md 落后一版的版本徽章（1.15.4 → 1.15.5）。
+
+### Tests
+
+- `tests/host-adapter-install.test.ts`：注册表完整性、通用切片 install / uninstall / status、未安装宿主零写入（+4 用例）。
+- `tests/m-install-hooks-wiring.test.ts`：doctor hooks 检查改为按 agent 名匹配（DeepSeek Harness glue 与 Claude Code hooks 同属 `hooks` 类别，注册表顺序不是契约）。
+- `tests/m48-doc-code-consistency.test.ts`：新增「文档必须是合法 UTF-8」与「README.zh.md 徽章与 package.json 一致」两个守卫（+2 用例）。
+- `tests/m49-workspace-root-isolation.test.ts`：新增临时目录边界与「残留图谱不得捕获嵌套项目」回归用例（+2 用例）。
+
 ## [1.15.5] - 2026-09-08
 
 ### Added

package/README.md

@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-[![npm version](https://img.shields.io/badge/npm-1.15.5-blue)](https://www.npmjs.com/package/@roarpeng/graphflow)
+[![npm version](https://img.shields.io/badge/npm-1.16.0-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.
 
@@ -10,9 +10,9 @@ The community is converging on an "agent harness" vocabulary: **memory + hooks +
 
 | Harness primitive | GraphFlow implementation |
 | --- | --- |
-| **Memory** | 12-language AST code graph + Episodic / Skill / Decision nodes �?project knowledge *and* project experience persist across sessions |
-| **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 |
-| **Skills** | A four-class flywheel (`proven` / `correctable` / `anti-pattern` / `noise`) with canary validation �?skills are promoted by evidence, not by assertion |
+| **Memory** | 12-language AST code graph + Episodic / Skill / Decision nodes — project knowledge *and* project experience persist across sessions |
+| **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 |
+| **Skills** | A four-class flywheel (`proven` / `correctable` / `anti-pattern` / `noise`) with canary validation — skills are promoted by evidence, not by assertion |
 
 Pure TypeScript/Node. CLI + MCP + VS Code extension. Fully offline, no API key required.
 
@@ -21,20 +21,20 @@ Pure TypeScript/Node. CLI + MCP + VS Code extension. Fully offline, no API key r
 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:
 
 - Static injection pays the same token cost every session regardless of the task, and grows until it is truncated or ignored.
-- Plain RAG retrieves text but never accumulates *experience* �?the thousandth task pays the same cost as the first.
+- Plain RAG retrieves text but never accumulates *experience* — the thousandth task pays the same cost as the first.
 
-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.
+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.
 
 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.
 
 ## Proof, not promises
 
-**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>`.
+**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`
+- **~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)
 
@@ -56,7 +56,7 @@ npx @roarpeng/graphflow graph index .
 npx @roarpeng/graphflow context preview "orchestrator" --json
 ```
 
-Connect via MCP (Cursor / Claude Code / �?:
+Connect via MCP (Cursor / Claude Code / …):
 
 ```json
 {
@@ -69,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). For symbol-precise edits, compose Serena as a second MCP server �?[GraphFlow + Serena](docs/graphflow-serena.md) (`examples/graphflow-serena.mcp.json`).
+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
 
@@ -77,14 +77,14 @@ Single-purpose tools each do one thing well; GraphFlow combines graph + compress
 
 | Capability | **GraphFlow** | CodeGraph | Serena | Repomix |
 | --- | --- | --- | --- | --- |
-| Code graph | 12-language AST index | more mature | LSP symbols | �?|
+| Code graph | 12-language AST index | more mature | LSP symbols | — |
 | Context compression | layered + graph compression + vector recall | partial | partial | whole-repo dump |
-| Planning protocol | ATP IR + DAG + agent bridge | �?| �?| �?|
-| **Learning memory** | Episodic / Skill / Decision flywheel | �?| �?| �?|
-| Local-first | �?| �?| �?| �?|
-| Open protocol | [ATP/IR public spec](docs/atp-ir-spec-v1.md) | �?| �?| �?|
+| Planning protocol | ATP IR + DAG + agent bridge | — | — | — |
+| **Learning memory** | Episodic / Skill / Decision flywheel | — | — | — |
+| 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/graphflow-serena.md) ([中文](docs/graphflow-serena.zh.md); [comparison](docs/comparison.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/graphflow-serena.md) ([中文](docs/graphflow-serena.zh.md); [comparison](docs/comparison.md)).
 
 ## Core capabilities (v1.15+)
 
@@ -92,8 +92,8 @@ Single-purpose tools each do one thing well; GraphFlow combines graph + compress
 | --- | --- |
 | **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) |
 | **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 |
-| **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. |
-| **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 |
+| **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. |
+| **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 |
 | **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 |
 | **Vector index** | In-process memoization + disk persistence (fingerprint-checked, seconds to restore after MCP restart) |
 | **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
 | **Model routing** | Smart / Economy tiers; multi-provider health probes and fallback (DeepSeek, OpenAI, Anthropic, Bailian, Doubao) |
 | **Workbench** | Plan DAG seeds function-topic containers; collapsed outline; click `topicId` to resume; drift forks a side branch; original Q/A stored via `assistantReply` |
 | **Observability** | `graphflow_diagnose` / `route diagnose`: provider health + graph stats + token savings + **flywheel health** (auto-capture, episodes, skills by class, session journal) + workbench outline |
-| **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 / Kimi Code install · uninstall · doctor; other hosts still use the legacy installers |
+| **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 install · uninstall · doctor for **every** registered host: 4 hand-written slices (Cursor / Claude Code / DeepSeek Harness / Kimi Code) + a generic profile-backed slice for the rest |
 | **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 |
 | **Engineering quality** | TypeScript strict; vitest suite; `npm run ci` includes extension packaging and smoke tests |
 
 ### Positioning
 
-> 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.
+> 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.
 
 ## MCP tools (10)
 
 | Tool | Function |
 | --- | --- |
-| `graphflow_context` | Compressed context package (query �?anchors + summaries; `topicId` / `assistantReply` to resume a workbench node or fill the pending answer; anchorId �?expand) |
+| `graphflow_context` | Compressed context package (query → anchors + summaries; `topicId` / `assistantReply` to resume a workbench node or fill the pending answer; anchorId → expand) |
 | `graphflow_plan` | Task planning (mode='simple' or 'insight'; seeds `workbench.topics` + `workbench.outline`; agent-delegated without an LLM) |
 | `graphflow_run` | Orchestration + bridge execution descriptor |
 | `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
 
 ## Workbench navigation (v1.9.14)
 
-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.
+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.
 
 Wake the collapsed outline when you need it (still 10 MCP tools):
 
 ```bash
 graphflow workbench tree --json            # CLI
 # VS Code / Cursor: GraphFlow: Workbench Tree (Activity Bar, default collapsed) or chat /tree
-# MCP: graphflow_diagnose �?graph.workbenchOutline
+# MCP: graphflow_diagnose → graph.workbenchOutline
 graphflow context preview --topic-id "<topic:...>" "continue from this node"
 graphflow context preview --reply "original assistant answer"
 ```
@@ -165,7 +165,7 @@ graphflow doctor                           # install self-check
 
 ## Configuration
 
-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.
+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.
 
 Key options:
 
@@ -186,16 +186,16 @@ Set `graphPolicy.transport` to `mcp-http` to host the graph on a remote Graphify
 { "graphPolicy": { "transport": "mcp-http", "mcpEndpoint": "http://graphify.team.internal:8080" } }
 ```
 
-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).
+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).
 
 ## Benchmarks
 
-- **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%)
-- **Independent-style**: [INDEPENDENT-RESULTS.md](benchmarks/INDEPENDENT-RESULTS.md) �?CodeGraph-style 5-domain evaluation, Hit@5 **96%**, token savings **96.6%**, overall **96.2%**
-- **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%)
-- **Token savings**: [RESULTS.md](benchmarks/RESULTS.md) �?8 representative queries, **98.2%** savings, re-counted with independent gpt-tokenizer
-- **Retrieval quality**: [RETRIEVAL-EVAL-RESULTS.md](benchmarks/RETRIEVAL-EVAL-RESULTS.md) �?132 queries, Hit@5=100%, MRR=0.836, NDCG@5=0.601
-- **Skill flywheel A/B**: [SKILL-AB-RESULTS.md](benchmarks/SKILL-AB-RESULTS.md) �?injection rate 100%, recall 100%, overhead 25.6 tok/task
+- **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%)
+- **Independent-style**: [INDEPENDENT-RESULTS.md](benchmarks/INDEPENDENT-RESULTS.md) — CodeGraph-style 5-domain evaluation, Hit@5 **96%**, token savings **96.6%**, overall **96.2%**
+- **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%)
+- **Token savings**: [RESULTS.md](benchmarks/RESULTS.md) — 8 representative queries, **98.2%** savings, re-counted with independent gpt-tokenizer
+- **Retrieval quality**: [RETRIEVAL-EVAL-RESULTS.md](benchmarks/RETRIEVAL-EVAL-RESULTS.md) — 132 queries, Hit@5=100%, MRR=0.836, NDCG@5=0.601
+- **Skill flywheel A/B**: [SKILL-AB-RESULTS.md](benchmarks/SKILL-AB-RESULTS.md) — injection rate 100%, recall 100%, overhead 25.6 tok/task
 
 ## VS Code / Cursor extension
 
@@ -225,7 +225,7 @@ ln -s /absolute/path/to/GraphFlow ~/.cursor/plugins/local/graphflow
 
 Docs: [Context Engineering contract](docs/context-contract.md) · [Experience memory](docs/experience-memory.md)
 
-**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:
+**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:
 
 ```bash
 npx @roarpeng/graphflow uninstall
@@ -233,39 +233,39 @@ npx @roarpeng/graphflow uninstall
 
 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.
 
-## DeepSeek Harness 插件（用法与能力�?
+## DeepSeek Harness 插件（用法与能力）
 
-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)�?
+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)。
 
-**�?dsh 上能工作 vs 不能工作�?*
+**在 dsh 上能工作 vs 不能工作：**
 
 | 能力 | dsh |
 | --- | --- |
-| 10 �?MCP 工具（`mcp__graphflow__graphflow_*`），stdio `cwd` = 会话工作�?| �?|
-| Skill（on-demand `skill({name:"graphflow"})`；bundle glue 注册，不必先 `graphflow install`�?| �?|
-| 会话结束飞轮：仅 `agent/disposed` 关闭 pending episode（不�?live `session/flush`；`GRAPHFLOW_AUTO_CAPTURE=0` 可关�?| �?|
-| 首轮�?hint：先�?`graphflow_context`（`rootDir` = cwd�?| �?|
-| Workbench 数据（`topicId` / outline）经 MCP `graphflow_context` / `graphflow_diagnose` | �?|
-| VS Code/Cursor 图谱面板、Settings webview、Workbench Tree、`@graphflow` chat | **�?*（宿�?UI，不移植�?|
-| Cursor Agent Plugins 1.0 发现 | **�?*（dsh �?`dsh.bundle`�?|
-| Claude Code `SessionStart/End/Stop` **文件** hooks | **�?*（dsh analog 是上面的 glue�?|
+| 10 个 MCP 工具（`mcp__graphflow__graphflow_*`），stdio `cwd` = 会话工作区 | 是 |
+| Skill（on-demand `skill({name:"graphflow"})`；bundle glue 注册，不必先 `graphflow install`） | 是 |
+| 会话结束飞轮：仅 `agent/disposed` 关闭 pending episode（不是 live `session/flush`；`GRAPHFLOW_AUTO_CAPTURE=0` 可关） | 是 |
+| 首轮短 hint：先调 `graphflow_context`（`rootDir` = cwd） | 是 |
+| Workbench 数据（`topicId` / outline）经 MCP `graphflow_context` / `graphflow_diagnose` | 是 |
+| VS Code/Cursor 图谱面板、Settings webview、Workbench Tree、`@graphflow` chat | **否**（宿主 UI，不移植） |
+| Cursor Agent Plugins 1.0 发现 | **否**（dsh 用 `dsh.bundle`） |
+| Claude Code `SessionStart/End/Stop` **文件** hooks | **否**（dsh analog 是上面的 glue） |
 
-**装进某个 profile（推荐）�?*
+**装进某个 profile（推荐）：**
 
 ```bash
 dsh plugin --profile web add @roarpeng/graphflow
 npx @deepseek-ai/dsh web
 ```
 
-**或在已有 `~/.dsh` 时写 home �?overlay（对所�?profile 生效）：**
+**或在已有 `~/.dsh` 时写 home 级 overlay（对所有 profile 生效）：**
 
 ```bash
 npx @roarpeng/graphflow install
 ```
 
-会写�?`$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�?
+会写入 `$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。
 
-**用法�?* 第一轮先 `mcp__graphflow__graphflow_context`（传�?`rootDir` = 仓库绝对路径），复杂任务�?`graphflow_plan`；改完代码后 `graphflow_index`；若走了 `graphflow_run`，结束后必须 `graphflow_report_outcome`。不要在 patch 里写�?`GRAPHFLOW_WORKSPACE_ROOT`�?
+**用法：** 第一轮先 `mcp__graphflow__graphflow_context`（传入 `rootDir` = 仓库绝对路径），复杂任务再 `graphflow_plan`；改完代码后 `graphflow_index`；若走了 `graphflow_run`，结束后必须 `graphflow_report_outcome`。不要在 patch 里写死 `GRAPHFLOW_WORKSPACE_ROOT`。
 
 ## Agent integrations
 
@@ -278,17 +278,17 @@ npx @roarpeng/graphflow uninstall  # remove MCP + Skill + Rules + hooks
 npx @roarpeng/graphflow init       # write a minimal project config
 ```
 
-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`), Kimi Code CLI, and more (15+). Cursor, Claude Code, DeepSeek Harness, and Kimi Code go through the HostAdapter registry (`installViaHostAdapter`); remaining hosts still use the legacy installers.
+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`), Kimi Code CLI, and more (15+). **Every** registered host goes through the HostAdapter registry (`installViaHostAdapter`); the legacy installers now only cover host-scoped extras (Trae user Skills, project-level rules).
 
 | Path | When to use |
 | --- | --- |
 | **Agent Plugins** | Preferred single-host Skill + MCP discovery |
 | **`graphflow install`** | Rules / multi-agent / non-plugin hosts |
-| **`graphflow uninstall`** | After removing a plugin (or anytime) �?clears leftover Skill/MCP/Rules |
+| **`graphflow uninstall`** | After removing a plugin (or anytime) — clears leftover Skill/MCP/Rules |
 
 ## 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/). Dual-MCP compose snippet (GraphFlow + Serena, config only): [`examples/graphflow-serena.mcp.json`](examples/graphflow-serena.mcp.json).
+[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
 
@@ -306,7 +306,7 @@ npm install
 npm run ci        # lint + build + tests + extension packaging + smoke
 ```
 
-Requires Node.js �?20, npm �?10. Expected: lint clean, build succeeds, 961 tests pass.
+Requires Node.js ≥ 20, npm ≥ 10. Expected: lint clean, build succeeds, 961 tests pass.
 
 ## Project structure
 
@@ -318,14 +318,14 @@ GraphFlow/
 ├── dsh/plugin.mjs      # dsh ESM glue: skill register + session-end capture
 ├── skills/graphflow/   # portable Agent Skill (canonical SKILL.md)
 ├── src/
-�?  ├── core/           # orchestration core: orchestrator, triage, dag-engine, agent-delegation
-�?  ├── graph/          # indexing, context slicing, graph compression, sqlite/auto storage, snapshot
-�?  ├── routing/        # model routing and health probes (5 providers)
-�?  ├── learning/       # embeddings, episodic, skill-flywheel, hnsw, nightly
-�?  ├── agents/         # ATP schema, planner, insight, brainstormer
-�?  └── surfaces/
-�?      ├── cli/        # CLI + runtime
-�?      └── mcp/        # MCP server (10 tools)
+│   ├── core/           # orchestration core: orchestrator, triage, dag-engine, agent-delegation
+│   ├── graph/          # indexing, context slicing, graph compression, sqlite/auto storage, snapshot
+│   ├── routing/        # model routing and health probes (5 providers)
+│   ├── learning/       # embeddings, episodic, skill-flywheel, hnsw, nightly
+│   ├── agents/         # ATP schema, planner, insight, brainstormer
+│   └── surfaces/
+│       ├── cli/        # CLI + runtime
+│       └── 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 + flywheel reproduction + GraphFlow/Serena

package/README.zh.md

@@ -2,24 +2,24 @@
 
 [English](README.md) | 中文
 
-[![npm version](https://img.shields.io/badge/npm-1.15.4-blue)](https://www.npmjs.com/package/@roarpeng/graphflow)
+[![npm version](https://img.shields.io/badge/npm-1.16.0-blue)](https://www.npmjs.com/package/@roarpeng/graphflow)
 
-> **给编�?Agent 用的记忆与上下文 harness�?* 本地优先的代码知识图�?· 有界上下文压缩（�?98% token 节省�?· 跨会话学习飞轮�?
+> **给编程 Agent 用的记忆与上下文 harness。** 本地优先的代码知识图谱 · 有界上下文压缩（约 98% token 节省） · 跨会话学习飞轮。
 
-GraphFlow �?**记忆 + hooks + skills** 做成可移植的 MCP 表面（Cursor、Claude Code、DeepSeek Harness�?5+ Agent），让无状态模型变成可长期工作的编码助手。它**不是编排执行�?*：先压缩上下文、再规划，执行交给宿�?Agent。纯 TypeScript/Node，CLI + MCP + VS Code 扩展，完全离线，无需 API Key�?
+GraphFlow 把 **记忆 + hooks + skills** 做成可移植的 MCP 表面（Cursor、Claude Code、DeepSeek Harness、15+ Agent），让无状态模型变成可长期工作的编码助手。它**不是编排执行器**：先压缩上下文、再规划，执行交给宿主 Agent。纯 TypeScript/Node，CLI + MCP + VS Code 扩展，完全离线，无需 API Key。
 
-**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 / 治理平面仍在�?
+**v1.16.0** 已发：团队共享记忆 MVP（`graphflow team serve` + RBAC）、**全部 19 个宿主的 install / uninstall / doctor 统一走 HostAdapter**（4 个手写切片 + 通用 profile 切片）、飞轮公开复现（`npm run proof:flywheel`）、Serena 双 MCP 指南，以及 R4 `context-package-core` 与 `runOrchestration` 拆分。v1.14 把对话图做成一等资产（时间边、召回、fork/回放）。v1.12–v1.13 的 fidelity / 治理平面仍在。
 
-## 快速开�?
+## 快速开始
 
 ```bash
 npx @roarpeng/graphflow graph index .
 npx @roarpeng/graphflow context preview "orchestrator" --json
-graphflow mcp serve --http         # MCP Streamable HTTP（默�?stateless�?-stateful 开�?SSE session�?
-npx @roarpeng/graphflow install    # 自动接入已检测到�?Agent（含 dsh�?
+graphflow mcp serve --http         # MCP Streamable HTTP（默认 stateless；--stateful 开启 SSE session）
+npx @roarpeng/graphflow install    # 自动接入已检测到的 Agent（含 dsh）
 ```
 
-MCP 入口�?
+MCP 入口：
 
 ```json
 {
@@ -32,75 +32,75 @@ MCP 入口
 }
 ```
 
-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)）�?
+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.15�?
+## 本版要点（v1.15）
 
 | 能力 | 说明 |
 | --- | --- |
-| **Harness** | 记忆动态、按任务召回（图锚点 + 压缩摘要 + 历史 episode + skill），有明�?L0–L3 token 预算 |
-| **飞轮复现** | `npm run proof:flywheel` 离线串检�?/ skill A/B / memory A/B；见 [docs/flywheel-reproduction.md](docs/flywheel-reproduction.md) |
+| **Harness** | 记忆动态、按任务召回（图锚点 + 压缩摘要 + 历史 episode + skill），有明确 L0–L3 token 预算 |
+| **飞轮复现** | `npm run proof:flywheel` 离线串检索 / skill A/B / memory A/B；见 [docs/flywheel-reproduction.md](docs/flywheel-reproduction.md) |
 | **团队记忆** | `graphflow team serve`：tenant 隔离 + viewer/contributor/admin；非 loopback 默认强制认证；`diagnose` 报告连通与 RBAC。见 [docs/team-memory-security.md](docs/team-memory-security.md) |
-| **HostAdapter** | Cursor / Claude Code / DeepSeek Harness �?install / uninstall / doctor 走注册表；其余宿主仍走遗留安装器 |
-| **Serena** | 并列第二�?MCP：context/plan �?Serena 编辑 �?`report_outcome` |
+| **HostAdapter** | **全部 19 个宿主**的 install / uninstall / doctor 统一走注册表：4 个手写切片（Cursor / Claude Code / DeepSeek Harness / Kimi Code）+ 通用 profile 切片（Trae、VS Code、Windsurf、Cline、Roo、Kilo、PearAI、Gemini、Codex、Antigravity、Amazon Q、Zed、Continue、Qoder、Opencode） |
+| **Serena** | 并列第二个 MCP：context/plan → Serena 编辑 → `report_outcome` |
 
-完整英文对照与基准数字：[README.md](README.md)�?
+完整英文对照与基准数字：[README.md](README.md)。
 
-## 工作台脉络（v1.9.14�?
+## 工作台脉络（v1.9.14）
 
-日常 Chat 仍是单线。复杂任务用 `graphflow_plan` 播种**功能主题容器**（画布上是计划步骤，不是一轮一节点）。点击节点，�?`topicId` 传给 `graphflow_context` 即可在该功能上继续或回到主线。问法跑偏会 Fork 孤立旁支，主线不被刷脏。答完再�?`graphflow_context({ assistantReply })` 回填原文。树上的标题只用于显示；下一轮必读是 Goal + 祖先标题 + 该节点原�?Q/A�?
+日常 Chat 仍是单线。复杂任务用 `graphflow_plan` 播种**功能主题容器**（画布上是计划步骤，不是一轮一节点）。点击节点，把 `topicId` 传给 `graphflow_context` 即可在该功能上继续或回到主线。问法跑偏会 Fork 孤立旁支，主线不被刷脏。答完再调 `graphflow_context({ assistantReply })` 回填原文。树上的标题只用于显示；下一轮必读是 Goal + 祖先标题 + 该节点原文 Q/A。
 
-按需唤醒（仍�?10 �?MCP 工具，不新增）：
+按需唤醒（仍是 10 个 MCP 工具，不新增）：
 
 ```bash
 graphflow workbench tree --json
 # VS Code / Cursor：GraphFlow: Workbench Tree（活动栏默认收起）或 Chat /tree
-# MCP：graphflow_diagnose �?graph.workbenchOutline
+# MCP：graphflow_diagnose → graph.workbenchOutline
 graphflow context preview --topic-id "<topic:...>" "在此节点继续"
 graphflow context preview --reply "助手原文回答"
 ```
 
 ## DeepSeek Harness 插件
 
-GraphFlow 本身就是一�?**dsh 插件�?*（topic：`dsh-plugin`）。`package.json` 声明 `dsh.bundle`，根目录 `cordis.patch.yml` �?GraphFlow MCP �?ESM glue 插入 Harness 的插件树�?
+GraphFlow 本身就是一个 **dsh 插件包**（topic：`dsh-plugin`）。`package.json` 声明 `dsh.bundle`，根目录 `cordis.patch.yml` 把 GraphFlow MCP 与 ESM glue 插入 Harness 的插件树。
 
 ### 能力
 
-| 能力 | 说明 | dsh 工具�?|
+| 能力 | 说明 | dsh 工具名 |
 | --- | --- | --- |
-| 压缩上下�?| 查询 �?锚点 + 摘要；按 `anchorId` 展开 | `mcp__graphflow__graphflow_context` |
-| 任务规划 | simple / insight；无 LLM 时桥接宿�?| `mcp__graphflow__graphflow_plan` |
-| 桥接执行�?| 规划 + 压缩上下文，不代跑代�?| `mcp__graphflow__graphflow_run` |
-| 结果回填 | 关闭技能飞�?| `mcp__graphflow__graphflow_report_outcome` |
+| 压缩上下文 | 查询 → 锚点 + 摘要；按 `anchorId` 展开 | `mcp__graphflow__graphflow_context` |
+| 任务规划 | simple / insight；无 LLM 时桥接宿主 | `mcp__graphflow__graphflow_plan` |
+| 桥接执行包 | 规划 + 压缩上下文，不代跑代码 | `mcp__graphflow__graphflow_run` |
+| 结果回填 | 关闭技能飞轮 | `mcp__graphflow__graphflow_report_outcome` |
 | ATP Insight | submit / merge | `mcp__graphflow__graphflow_insight` |
-| 建图 | 增量 / 单文�?/ 全量重建 | `mcp__graphflow__graphflow_index` |
-| 技能洞�?| 历史任务沉淀�?skill | `mcp__graphflow__graphflow_skill_insights` |
-| 诊断 | 图谱、路由、token 节省、飞轮健�?| `mcp__graphflow__graphflow_diagnose` |
+| 建图 | 增量 / 单文件 / 全量重建 | `mcp__graphflow__graphflow_index` |
+| 技能洞察 | 历史任务沉淀的 skill | `mcp__graphflow__graphflow_skill_insights` |
+| 诊断 | 图谱、路由、token 节省、飞轮健康 | `mcp__graphflow__graphflow_diagnose` |
 | 产物 | 图谱 import / export | `mcp__graphflow__graphflow_artifact` |
-| 技能指�?| 给已连接 Agent 的用法说�?| `mcp__graphflow__graphflow_skill_guide` |
+| 技能指南 | 给已连接 Agent 的用法说明 | `mcp__graphflow__graphflow_skill_guide` |
 
-| �?dsh �?| 状�?|
+| 在 dsh 上 | 状态 |
 | --- | --- |
-| 上述 10 �?MCP 工具（stdio `cwd` = 会话工作区） | 支持 |
-| Skill（bundle glue 注册；`dsh plugin add` 即可�?| 支持 |
-| 会话结束飞轮（仅 `agent/disposed` �?`outcome report`；不�?live `session/flush`�?| 支持 |
-| VS Code/Cursor 图谱面板、Settings、Workbench Tree、`@graphflow` chat | **不移�?* |
-| Cursor Agent Plugins 发现 / Claude Code Session* **文件** hooks | **不移�?*（dsh �?bundle + glue�?|
+| 上述 10 个 MCP 工具（stdio `cwd` = 会话工作区） | 支持 |
+| Skill（bundle glue 注册；`dsh plugin add` 即可） | 支持 |
+| 会话结束飞轮（仅 `agent/disposed` → `outcome report`；不是 live `session/flush`） | 支持 |
+| VS Code/Cursor 图谱面板、Settings、Workbench Tree、`@graphflow` chat | **不移植** |
+| Cursor Agent Plugins 发现 / Claude Code Session* **文件** hooks | **不移植**（dsh 用 bundle + glue） |
 
-核心价值：本地 AST 知识图谱、L1–L3 分层压缩（实测约 98% token 节省）、跨会话 Episodic / Skill 飞轮。GraphFlow **不执行代�?*，只给宿�?Agent 压缩上下文和计划。Workbench 数据�?MCP `graphflow_context` / `graphflow_diagnose` 即可�?
+核心价值：本地 AST 知识图谱、L1–L3 分层压缩（实测约 98% token 节省）、跨会话 Episodic / Skill 飞轮。GraphFlow **不执行代码**，只给宿主 Agent 压缩上下文和计划。Workbench 数据走 MCP `graphflow_context` / `graphflow_diagnose` 即可。
 
 ### 安装
 
-**方式 A：装进某�?profile（推荐）**
+**方式 A：装进某个 profile（推荐）**
 
 ```bash
 dsh plugin --profile web add @roarpeng/graphflow
 npx @deepseek-ai/dsh web
 ```
 
-**方式 B：home �?overlay（所�?profile 生效�?*
+**方式 B：home 级 overlay（所有 profile 生效）**
 
-先有 `$DSH_HOME`（默�?`~/.dsh`），再执行：
+先有 `$DSH_HOME`（默认 `~/.dsh`），再执行：
 
 ```bash
 npx @roarpeng/graphflow install
@@ -121,21 +121,21 @@ dsh plugin --profile web add /absolute/path/to/GraphFlow
 
 ### 用法
 
-1. 任何读代码、改代码、排错之前，先调 `mcp__graphflow__graphflow_context`，并传入当前仓库绝对路径 `rootDir`�?
-2. 用返回的 `summary` / `anchors` / `tokenBudget` 当第一上下文；不够再按 `anchorId` 展开�?
-3. 跨多文件或范围不清时，再�?`graphflow_plan`；结果里�?`workbench.topics` 是功能节点。之后可�?`topicId` 细化，或 `graphflow_diagnose.graph.workbenchOutline` / `graphflow workbench tree` 唤醒脉络树�?
-4. 改完文件后调 `graphflow_index`（单文件可传 `filePath`）�?
-5. 若走�?`graphflow_run`，结束后必须 `graphflow_report_outcome`（`episodeId` + `success`）�?
-6. 回答用户后应再调 `graphflow_context({ assistantReply })` 回填原文�?
-7. 中文问题请同时传 `englishQuery`（英文文件名 / 符号名），不要只用泛化中文词检索�?
+1. 任何读代码、改代码、排错之前，先调 `mcp__graphflow__graphflow_context`，并传入当前仓库绝对路径 `rootDir`。
+2. 用返回的 `summary` / `anchors` / `tokenBudget` 当第一上下文；不够再按 `anchorId` 展开。
+3. 跨多文件或范围不清时，再调 `graphflow_plan`；结果里的 `workbench.topics` 是功能节点。之后可用 `topicId` 细化，或 `graphflow_diagnose.graph.workbenchOutline` / `graphflow workbench tree` 唤醒脉络树。
+4. 改完文件后调 `graphflow_index`（单文件可传 `filePath`）。
+5. 若走了 `graphflow_run`，结束后必须 `graphflow_report_outcome`（`episodeId` + `success`）。
+6. 回答用户后应再调 `graphflow_context({ assistantReply })` 回填原文。
+7. 中文问题请同时传 `englishQuery`（英文文件名 / 符号名），不要只用泛化中文词检索。
 
-不要�?`cordis.patch.yml` 里写�?`GRAPHFLOW_WORKSPACE_ROOT`�?
+不要在 `cordis.patch.yml` 里写死 `GRAPHFLOW_WORKSPACE_ROOT`。
 
 ### 卸载
 
 ```bash
 npx @roarpeng/graphflow uninstall
-# 若只从某�?profile 移除 bundle�?
+# 若只从某个 profile 移除 bundle：
 dsh plugin --profile web remove @roarpeng/graphflow
 ```
 
@@ -143,12 +143,12 @@ dsh plugin --profile web remove @roarpeng/graphflow
 
 | 路径 | 适用 |
 | --- | --- |
-| [Agent Plugins 1.0](https://agent-plugins.org)（`plugin.json` + `mcp.json` + `skills/`�?| Cursor 等支持插件清单的宿主 |
-| `npx @roarpeng/graphflow install` | Rules / �?Agent / 非插件宿主（�?dsh overlay�?|
+| [Agent Plugins 1.0](https://agent-plugins.org)（`plugin.json` + `mcp.json` + `skills/`） | Cursor 等支持插件清单的宿主 |
+| `npx @roarpeng/graphflow install` | Rules / 多 Agent / 非插件宿主（含 dsh overlay） |
 | VS Code / Cursor 扩展 | Open VSX：`roarpeng.graphflow` |
 
 ## 更多
 
 完整英文文档、基准与协议：[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)）�?
+第三方复现飞轮 / 记忆 A/B / 检索自测：`npm run proof:flywheel`（说明见 [docs/flywheel-reproduction.md](docs/flywheel-reproduction.md)）。

package/dist/config/discover-workspace.d.ts

@@ -13,15 +13,32 @@ export declare function hasDevProjectMarkers(dir: string): boolean;
  */
 export declare function isUnsafeWorkspaceFallback(dir: string): boolean;
 export declare function isUsableWorkspaceFallback(dir: string): boolean;
+/**
+ * True when `dir` is an OS temp root (e.g. `%TEMP%` / `/tmp`).
+ *
+ * A temp root must never be an implicit workspace: an MCP server started with
+ * cwd inside the temp directory writes `graphflow-out/graphflow-graph.json`
+ * there, and `hasProjectWorkspaceMarkers()` would then treat the temp root as a
+ * project — capturing upward discovery for every project created beneath it
+ * (observed as the m49 workspace-isolation failure).
+ */
+export declare function isSystemTempDirectory(dir: string): boolean;
 /**
  * Walk upward from `fromDir` to find the nearest user project root.
  * Skips GraphFlow runtime directories (extension vendor, global npm package).
  *
+ * The walk stops at unsafe boundaries (home / AppData) and at OS temp roots,
+ * so a stray graph store in `%TEMP%` cannot capture unrelated projects.
+ * `extraBoundaries` is a test hook for exercising the same rule without writing
+ * to the real temp directory.
+ *
  * IDE env hints (CURSOR_PROJECT_DIR, etc.) are only used when `fromDir` is a
  * GraphFlow runtime directory — e.g. extension vendor — where upward walk cannot
  * reach the user's opened workspace.
  */
-export declare function discoverWorkspaceRoot(fromDir?: string): string | undefined;
+export declare function discoverWorkspaceRoot(fromDir?: string, options?: {
+    extraBoundaries?: readonly string[];
+}): string | undefined;
 /** Apply discovered workspace to process.env when MCP starts without an explicit root. */
 export declare function ensureMcpWorkspaceEnv(fromDir?: string): string | undefined;
 /** IDE-provided workspace when process cwd is unsafe or a GraphFlow runtime directory. */

package/dist/config/discover-workspace.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"discover-workspace.d.ts","sourceRoot":"","sources":["../../src/config/discover-workspace.ts"],"names":[],"mappings":"AAyBA,6EAA6E;AAC7E,wBAAgB,gCAAgC,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAMvE;AAuBD,iBAAS,KAAK,IAAI,OAAO,CAuBxB;AAED,8GAA8G;AAC9G,wBAAgB,2BAA2B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAGhE;AAED,+EAA+E;AAC/E,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAoB/D;AAYD,6EAA6E;AAC7E,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAGzD;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CA6B9D;AAED,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAM9D;AAiDD;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,GAAE,MAAsB,GAAG,MAAM,GAAG,SAAS,CA8BzF;AAED,0FAA0F;AAC1F,wBAAgB,qBAAqB,CAAC,OAAO,GAAE,MAAsB,GAAG,MAAM,GAAG,SAAS,CAyCzF;AAED,0FAA0F;AAC1F,wBAAgB,0BAA0B,IAAI,MAAM,GAAG,SAAS,CAM/D;AAED,OAAO,EAAE,KAAK,EAAE,CAAC"}
+{"version":3,"file":"discover-workspace.d.ts","sourceRoot":"","sources":["../../src/config/discover-workspace.ts"],"names":[],"mappings":"AAyBA,6EAA6E;AAC7E,wBAAgB,gCAAgC,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAMvE;AAuBD,iBAAS,KAAK,IAAI,OAAO,CAuBxB;AAED,8GAA8G;AAC9G,wBAAgB,2BAA2B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAGhE;AAED,+EAA+E;AAC/E,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAoB/D;AAYD,6EAA6E;AAC7E,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAGzD;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CA6B9D;AAED,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAM9D;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAO1D;AAiDD;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,GAAE,MAAsB,EAC/B,OAAO,GAAE;IAAE,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAAO,GACpD,MAAM,GAAG,SAAS,CAmCpB;AAED,0FAA0F;AAC1F,wBAAgB,qBAAqB,CAAC,OAAO,GAAE,MAAsB,GAAG,MAAM,GAAG,SAAS,CAyCzF;AAED,0FAA0F;AAC1F,wBAAgB,0BAA0B,IAAI,MAAM,GAAG,SAAS,CAM/D;AAED,OAAO,EAAE,KAAK,EAAE,CAAC"}