@roarpeng/graphflow 1.9.4 → 1.9.12

package/CHANGELOG.md

@@ -2,6 +2,139 @@
 
 All notable changes to this project are documented in this file.
 
+## [Unreleased]
+
+## [1.9.12] - 2026-08-12
+
+### Added
+
+- **Episode ↔ Engineering KG on outcome path**: `graphflow_report_outcome` / CLI `outcome report` accept optional `requirementIds` / `conceptIds` / `codeHints` and write episode → `derived_from` → eng nodes via `linkEpisodeToEngineeringNodes`
+- **Document-semantic insight ↔ episode provenance**: when `episodeId` is passed with a document-semantic submit, the same eng links are written for experience↔eng consistency
+- **ATP minimal producer atp-ir/1.2**: optional `memory-recall` / `memory-backfill` markers (host-managed); fixture + README updated; still runnable without GraphFlow MCP
+- **P0 skill consolidate apply**：`graphflow skill consolidate` 默认 dry-run；`--apply` / `--execute` 安全调用 `applySkillConsolidation`（未知 id skip）
+- **代码域检索评测公开数据集**：`benchmarks/datasets/retrieval-golden-v1.json`（+ `.jsonl`），含 schema / license / domainCounts / Hit@5·MRR·NDCG 映射说明；`npm run dataset:retrieval` 从 `benchmarks/retrieval-golden-data.ts` 再生，避免漂移
+- **Agent Plugins 1.0** packaging at repo root: `plugin.json`, `mcp.json` (`type: stdio`), and canonical `skills/graphflow/SKILL.md`
+- README section for local plugin install (`~/.cursor/plugins/local`) and Team Marketplace / Git discovery
+- `npm run sync:surfaces` keeps `src/surfaces/trae-skill/graphflow/SKILL.md` aligned with the Agent Plugins skill source
+- Conformance test `tests/agent-plugins-1.0.test.ts`
+- **P1 Context Engineering contract**: [docs/context-contract.md](docs/context-contract.md) — budget fields, L0–L3 anchors/refill, positioning vs platform indexing / RL; links MCP `graphflow_context` and Agent Plugins
+- **P1 Experience memory guide**: [docs/experience-memory.md](docs/experience-memory.md) — Storage → Reflection → Experience; artifact / memory-pack / skill-sync; Agent Plugin vs `install` matrix
+- **Experience memory pack**: `exportExperienceMemoryPack` + CLI `graphflow artifact export-memory` → `graphflow-out/memory-pack/{README,skills,episodes}.md`
+- README: Agent Plugins as **primary** install; `graphflow install` as Rules / multi-agent fallback; links to the two new docs
+- **install/doctor 接入 Claude Code 飞轮 hooks**：`graphflow install` 在检测到 Claude Code home 时自动调用 `installClaudeCodeHooks`（SessionStart / SessionEnd / Stop）；`doctor --json` 新增 `hooks` 类别自检；InstallReport 增加 `claudeCodeHooks`；`GRAPHFLOW_CLAUDE_HOME` 便于测试覆盖
+
+### Fixed
+
+- **扩展升级后 MCP launcher 路径失效**：`repairStaleGraphFlowMcpLaunchers` 在扩展激活时扫描用户级与工作区 MCP 配置；若 `graphflow` 仍指向已删除的旧版 `mcp-launcher.cjs/.cmd`（如 `roarpeng.graphflow-1.9.6`），自动改写为当前扩展启动器。修复 Cursor Agents 依赖项目级 `.cursor/mcp.json` 而 IDE 仍可用的不一致。
+
+### Changed
+
+- ATP/IR spec status line marks **`atp-ir/1.2` Stable**; §5 / §8 document optional Engineering KG link fields on `report_outcome`
+- ROADMAP P2 rows (ATP producer + Engineering KG episode chain; ATP/IR v1.2 protocol) → ✅
+- **P0 Experience 飞轮可观测**：`getFlywheelReport` / `skill report` / `route diagnose` / `graphflow_diagnose` 的 `experience` 增加 dry-run `consolidation` 动作计数（UPDATE/DELETE/ADD）与建议 hint；ROADMAP P0 ✅
+- Skill resolution (`resolveSkillSourcePath` / MCP `graphflow_skill_guide`) prefers `skills/graphflow` before legacy `trae-skill` paths
+- `package.json` `files` publishes `plugin.json`, `mcp.json`, and `skills/`
+- ROADMAP (2026-08-12): Experience-layer P0–P2 ✅ (skill consolidate --apply; retrieval golden dataset; ATP/IR v1.2 + episode↔eng KG)
+- **`graphflow uninstall`** now removes **MCP + Skills + Rules + hooks** (user + workspace MCP). After removing an Agent Plugin in Cursor, run `uninstall` so leftover `~/.cursor/skills/graphflow` cannot keep steering the agent.
+
+### Tests
+
+- `tests/m-install-hooks-wiring.test.ts`：hooks status + install/doctor 接线
+- `tests/m-stale-mcp-launcher-repair.test.ts`：失效 mcp-launcher 路径检测与改写
+- `tests/atp-ir-v1.2-conformance.test.ts`：ATP/IR v1.2 memory markers + producer protocol
+- `tests/report-outcome-engineering-links.test.ts`：outcome / insight eng-link wiring
+- `tests/retrieval-dataset.test.ts`：公开检索数据集与 TS 真源条目数/内容一致
+
+## [1.9.11] - 2026-08-08
+
+### Added
+
+- **VSIX 激活时按需下载 anydoc**：设置 `graphflow.downloadAnydoc`（默认 true）→ `npm install @firecrawl/anydoc` 到 `~/.graphflow/optional-deps`；MCP launcher / `document-convert` 经 `GRAPHFLOW_ANYDOC_NODE_MODULES` 加载。失败则跳过 Office/PDF，源码索引照常
+- README / 扩展 README 说明 VSIX 不内置、可自动下载、可关闭
+- **emilkowalski/skills**：项目安装 design-eng 等 skill；扩展 webview 面板统一 soft elevation、`:active` scale(0.97)、`--ease-out`、reduced-motion
+
+## [1.9.10] - 2026-08-08
+
+### Added
+
+- **Engineering KG 跨层边**：`documents`（文档 File→Concept/Requirement）、`implements`（代码→Requirement）、`derived_from`（语义节点→来源 File/insight）
+- **文档域一等节点**：`Concept` / `Requirement`；`document-semantic` insight submit 自动写入并尝试用 `relatedCodeHints` 链接已有 File/Symbol
+- **说明**：VS Code/Cursor **VSIX 不打包** `@firecrawl/anydoc`；自 v1.9.11 起扩展激活时可自动下载到 `~/.graphflow/optional-deps`（`graphflow.downloadAnydoc`）。CLI/`npm i` 仍可通过 optionalDependency 安装。无 anydoc 时跳过 Office/PDF，源码索引不受影响
+
+### Changed
+
+- 逻辑三分（code / doc / experience）落在**单图 + type/domain + 跨层边**，不拆物理三库
+
+## [1.9.9] - 2026-08-08
+
+### Fixed
+
+- **CI macOS ENAMETOOLONG**：`walkFiles` 深度目录测试从 400 段降至 80 段，保留迭代遍历断言，避免 APFS 路径过长导致 Action 失败
+
+### Added
+
+- **Office/PDF 文档建图**：可选依赖 `@firecrawl/anydoc`，将 PDF/DOCX/PPTX/XLSX 等转为 Markdown 后走既有 markdown 章节/链接图谱；缺省扩展名已包含办公文档；单文件上限约 5MB
+- **Document semantic bridge**：索引成功后返回 optional `document-semantic-*` `agentWorkItems`，由宿主 Agent 抽取关键实体/主张并经 `graphflow_insight(mode=submit)` 回写
+
+### Research note
+
+文档→MD 选型：优先 Firecrawl **anydoc**（Node、多格式、本地）；备选 Microsoft MarkItDown（Python）、Pandoc（系统依赖）。npm 上无关的旧包 `anydoc` 勿用。
+
+## [1.9.8] - 2026-08-08
+
+### Added
+
+- **P0 飞轮可观测性**：`getFlywheelReport` / `skill report` / `graphflow_diagnose` / `route diagnose` 暴露 `autoCaptureEnabled`、`sessionJournal`、`skills.byOutcomeKind`；`npm run backfill:episodes` 包装历史回填脚本
+- **Skill-conditioned DAG**：plan 节点可选 `skillRefs` / `avoidPatterns`；bridge 指令要求执行前审阅 skills / 避开 anti-patterns
+- **SkillOpt-lite**：无 LLM 的有界 skill guidance 编辑（最多 3 次，严格提升才接受）；接入 `applySkillLearning` lessons 路径
+- **团队记忆 canary 门控**：`canary-gate.ts`——sync/import 技能须本地成功 N 次（或显式 validate）才可晋升 `proven`；anti-pattern 仅隔离
+- **Codex Windows MCP**：安装写入 `NODE` / `NPX_CLI` 8.3 短路径，修复 Codex 注册失败
+
+### Changed
+
+- **图噪声**：引用边前缀 Trie 预过滤；子图 PageRank LRU 缓存键按节点集排序哈希
+- **planAndBrainstorm** 异步化以在 flywheel 开启时注入 skill 条件
+
+### Tests
+
+- 新增 `tests/m81-skill-conditioned-dag.test.ts`、`tests/canary-gate.test.ts`；扩展 flywheel-report / graph-noise / mcp-resources / Codex MCP install
+
+## [1.9.7] - 2026-08-03
+
+### Added
+
+- **综合能力 Benchmark（P1-P6 六维度）**：`benchmarks/run-comprehensive-bench.ts`，覆盖图谱索引、上下文压缩、规划与分诊、学习飞轮、Bridge 模式、端到端性能，总体得分 **92.9%**
+- **CodeGraph 风格独立 Benchmark**：`benchmarks/run-independent-bench.ts`，5 域（core/graph/learning/config/integrations）评测，Hit@5 96%、Token 节省 96.6%、总体 **96.2%**
+- **SWE-bench 风格上下文就绪评测**：`benchmarks/run-swe-bench-eval.ts`，12 实例（easy/medium/hard × bug-fix/feature/refactor/test），多查询策略下上下文就绪率 100%（非真实 SWE-bench，仅测量压缩上下文是否包含任务所需文件/符号）
+- **检索质量 IR 指标评测**：`benchmarks/run-retrieval-eval.ts`，132 条 golden 查询，Hit@5=100%、MRR=0.836、NDCG@5=0.601
+- **符号提取模块**：`src/graph/symbol-extract.ts`，从任务描述提取 camelCase/PascalCase 符号名，补充图查询提升召回
+- **同文件符号提升 + 导入图扩展**：`buildEnhancedContextPackage` 新增 Step 5，自动从已锚定文件提取同文件 Symbol 节点，并通过 import 关系扩展跨文件召回
+- **Bridge+DAG 混合执行模式**：`enableBridgeDagExecution` 选项，bridge 模式下可选择同时本地执行 DAG（`tests/m81-bridge-dag-execution.test.ts`，5 个用例）
+
+### Changed
+
+- **上下文压缩优化**：anchor 上限 15（`maxAnchors`）、L2 module 注入、L3 always-on 层；压缩得分 38.4% → 64.9%
+- **DAG 并行度提升**：单 clause 任务拆分 4 节点（实现∥测试设计），并行度 1.2x → 1.40x
+- **Skill hints 修复**：传入 evidence 通过 P0-2 质量门控，skill hints 从 0 恢复到正常生成
+
+### Tests
+
+- 99 测试文件 / 692 tests（+1 m81 bridge+DAG、m79 plan clause split 更新）
+
+## [1.9.6] - 2026-08-03
+
+### Fixed
+
+- **Cursor/VS Code MCP 启动失败**：扩展 vendor 打包漏掉 `@modelcontextprotocol/sdk`，MCP launcher 加载 `vendor/graphflow/dist/surfaces/mcp/server.js` 时抛出 `Cannot find module '@modelcontextprotocol/sdk/server/index.js'`（Connection closed / -32000）。`sync-runtime.mjs` 已将 MCP SDK 纳入 `runtimeRoots`，并在同步后校验必选包存在；新增 `test:mcp` 烟雾测试防止回归
+
+## [1.9.5] - 2026-08-01
+
+### Fixed
+
+- **图谱索引排除 Agent 工具目录（P1）**：`IGNORED_DIRS` 新增 `.agent` / `.claude` / `.cursor` / `.gemini` / `.joycode` / `.trae` / `Cursor`——`.claude/worktrees` 为每个 worktree 保存完整仓库副本，此前被当作源码索引进图（本地实测 1421 个 File 节点中 1076 个来自 worktrees，占 76%），污染检索锚点、PageRank 与存储；修复后 `graph rebuild` 扫描文件数从 ~1500+ 降至 326，旧图可在下次增量/全量索引时自动清理
+- **增量索引剪枝批量删除（P1，读写放大修复的伴生问题）**：排除目录后首次增量索引需从缓存差集剪除大量过期节点，而 `pruneFileFromGraph` 逐节点 `deleteNode`（file 后端每次全量读写 JSON，实测 62MB 图 × 1000+ 节点 → 305s 挂起）；新增可选能力 `GraphClient.deleteNodes(ids)`（file 单次读+写、sqlite 单事务分块 IN、memory 批处理，均级联清理悬空边），剪枝改为单次快照读取 + 单次批量删除，mcp-http 试点保留逐节点回退路径
+- **测试 95 文件 / 656**（+2 walker 排除、+1 剪枝批量删除、+1 file 批量删除用例）
+
 ## [1.9.4] - 2026-08-01
 
 ### Changed

package/README.md

@@ -1,26 +1,58 @@
 # GraphFlow
 
-[![npm version](https://img.shields.io/badge/npm-1.9.4-blue)](https://www.npmjs.com/package/@roarpeng/graphflow)
+[![npm version](https://img.shields.io/badge/npm-1.9.12-blue)](https://www.npmjs.com/package/@roarpeng/graphflow)
 
-> **编码 Agent 的上下文与记忆层** — Local-first 代码知识图谱 + 上下文压缩 + 跨会话学习飞轮
+> **The memory & context harness for coding agents.** Local-first code knowledge graph · bounded context compression (~98% token savings) · cross-session learning flywheel.
 
-GraphFlow 为 Cursor / Claude Code 等编码 Agent 提供项目级的"感知与记忆"：把仓库索引成知识图谱，将 Agent 需要的上下文压缩 **90%+ token**（基准实测 98.7%），并通过 Episodic / Skill / Decision 三类节点让 Agent **跨会话复用项目经验**。规划与执行通过 Bridge 模式委托给宿主 Agent 完成——GraphFlow 不持有 LLM 也能完整闭环。
+The community is converging on an "agent harness" vocabulary: **memory + hooks + skills** are the harness primitives that turn a stateless model into a reliable long-running agent. GraphFlow implements all three for coding agents and ships them through a portable MCP surface (Cursor, Claude Code, 15+ agents):
 
-纯 TypeScript/Node 实现，CLI + MCP + VS Code 扩展三种形态，无 API key 即可离线运行。
+| 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` hooks 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.
+
+## Why a harness, not another RAG
+
+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.
+
+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
+
+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:
 
-## 30 秒上手
+- **~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)
 
-无需 API key（离线 AST 建图 + 图压缩）：
+Results are commit-anchored so any number above can be checked out and re-run. Third-party reproduction is actively welcomed — see [ROADMAP.md](ROADMAP.md) for the open invitation.
+
+## Memory poisoning protection
+
+Shared and synced memory is only useful if it cannot be silently corrupted. Skills merged from external sources (e.g. `skill sync` imports) are **treated as unproven until validated locally**: imported skills carry provenance markers, never enter the `proven` class directly, must pass canary validation on real tasks before promotion, and `anti-pattern` skills are isolated rather than deleted so they can be audited. Promotion is gated by the four-class lifecycle, not by trust in the source. See [docs/team-memory-security.md](docs/team-memory-security.md).
+
+## Quick start
+
+No API key needed (offline AST indexing + graph compression):
 
 ```bash
-# 1. 离线建图（AST 索引，无需 LLM）
+# 1. Build the graph offline (AST indexing, no LLM)
 npx @roarpeng/graphflow graph index .
 
-# 2. 预览压缩上下文（锚点 + 摘要，节省 90%+ token）
+# 2. Preview compressed context (anchors + summaries, 90%+ token savings)
 npx @roarpeng/graphflow context preview "orchestrator" --json
 ```
 
-接入 MCP（Cursor / Claude Code 等）：
+Connect via MCP (Cursor / Claude Code / …):
 
 ```json
 {
@@ -33,159 +65,213 @@ npx @roarpeng/graphflow context preview "orchestrator" --json
 }
 ```
 
-Agent 先调 `graphflow_context` 拿压缩上下文，再用 `graphflow_plan` 规划；无 provider API key 时 GraphFlow 自动把 ATP 思考协议桥接给宿主 Agent 作答（agent-delegated 模式）。
+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).
 
-## 为什么是 GraphFlow
+## Why GraphFlow
 
-单点工具各有长项，GraphFlow 把"图谱 + 压缩 + 规划协议 + 学习记忆"合到一处：
+Single-purpose tools each do one thing well; GraphFlow combines graph + compression + planning protocol + learning memory in one place:
 
-| 能力 | **GraphFlow** | CodeGraph | Serena | Repomix |
+| Capability | **GraphFlow** | CodeGraph | Serena | Repomix |
 | --- | --- | --- | --- | --- |
-| 代码图谱 | 12 语言 AST 索引 | 更成熟 | LSP 符号级 | 无 |
-| 上下文压缩 | 分层 + 图压缩 + 向量召回 | 部分 | 部分 | 整库打包 |
-| 规划协议 | ATP IR + DAG + Agent 桥接 | 无 | 无 | 无 |
-| **学习记忆** | Episodic / Skill / Decision 飞轮 | 无 | 无 | 无 |
+| 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 | ✅ | ✅ | ✅ | ✅ |
-| 协议开放 | [ATP/IR 公开规范](docs/atp-ir-spec-v1.md) | — | — | — |
+| Open protocol | [ATP/IR public spec](docs/atp-ir-spec-v1.md) | — | — | — |
 
-> 差异化核心是**学习飞轮**：图谱索引和 token 压缩都可复制，跨会话积累的项目私有经验（技能、教训、决策）不可复制——它随使用时长增值。
+> The differentiator is the **learning flywheel**: graph indexing and token compression are replicable; project-private experience (skills, lessons, decisions) accumulated across sessions is not — it compounds with use. Serena is a complement, not a competitor — see [GraphFlow + Serena: better together](docs/comparison.md#graphflow--serena-better-together联合方案).
 
-## 核心能力（v1.7.15+）
+## Core capabilities (v1.7.15+)
 
-| 模块 | 能力 |
+| Module | Capability |
 | --- | --- |
-| **规划协议** | ATP v1.1（Intent / Requirement / Six Hats / 5-Why / First Principles / Decision Matrix / Planning / Reflection）；simple / complex / insight 三种模式；无 LLM 时 agent-delegated 桥接；[ATP/IR 公开规范 v1.1](docs/atp-ir-spec-v1.md) |
-| **目标对齐** | **Goal 锚点节点化**（intent 五元组固化为一等公民，每次打包自动注入原始需求）；**低置信度澄清门**（confidence < 0.6 不出 plan）；**alignment-check 执行期回检**；**deviation 偏离分类**（misread-requirement / scope-creep / tech-drift）；**Goal 版本链 + 变更 diff** |
-| **知识图谱** | 12 语言 AST 索引（TS/JS/Python/Rust/Go/C/C++/Java/Ruby/Kotlin/Swift/Dart）；File / Module / Symbol 节点 + 依赖/引用/定义/调用/继承边 |
-| **上下文压缩** | L1/L2/L3 分层锚点；图结构压缩（边权重 + PageRank，**LRU 缓存**）；**词干匹配召回**（orchestrate ↔ orchestration）；向量召回 + RRF；RepoMap 概览；自适应预算 |
-| **检索质量** | **Golden-set 回归门禁**（26 查询，CI 强制 ≥80% 召回，实测 100%） |
-| **向量索引** | 进程内记忆化 + **磁盘持久化**（指纹校验，MCP 重启秒级恢复） |
-| **存储后端** | `file` / `memory` / `sqlite`（FTS5，**searchtext 分词增强**，camelCase 可检索）/ **`auto`（sqlite 优先自动切换）** / `mcp-http` |
-| **学习飞轮** | Episodic Memory、Reflection、Skill 节点（score ±1，bounded [-20,20]）、nightly 学习、技能衰减/剪枝、**飞轮贡献报告**（`skill report` / `graphflow_diagnose`，含偏离聚合与 Goal 统计） |
-| **团队共享** | **`skill sync`**：技能包导出/导入到可提交的 `.graphflow/skills/team-skills.json`；导入为**双向 MERGE**（per-skill-id 并集，updatedAt 较新者胜、并列保留本地、本地独有技能保留；`--force` 覆盖）；golden 检索基准随包往返 → `.graphflow/team-golden.json` |
-| **效果基准** | [token 节省 98.7%](benchmarks/RESULTS.md)（独立复核）；[Skill A/B 基准](benchmarks/SKILL-AB-RESULTS.md)（注入率/召回率/开销，`npm run benchmark:skills`） |
-| **模型路由** | Smart / Economy 双 tier；多 provider 健康探测与 fallback（DeepSeek、OpenAI、Anthropic、百炼、豆包） |
-| **可观测性** | `graphflow_diagnose`：provider 健康 + 图统计 + token 节省 + **飞轮报告** |
-| **Agent 接入** | CLI `--json`；MCP stdio（10 工具）；自动安装 MCP 到 15+ Agent |
-| **工程质量** | TypeScript strict；**92 测试文件 / 455 tests**；`npm run ci` 含扩展打包与 smoke |
-
-### 定位说明
-
-> GraphFlow **不是编排执行器**——它是编码 Agent 的**上下文与记忆层**。任务执行通过 Bridge 模式交给宿主 coding agent（诚实语义，不伪造 COMPLETED）；GraphFlow 负责让它"看得准、记得住"。
-
-## MCP 工具（10 个）
-
-| 工具 | 功能 |
+| **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 |
+| **Retrieval quality** | Golden-set regression gate (132 queries, Hit@5=100%, MRR=0.836, NDCG@5=0.601) |
+| **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` |
+| **Learning flywheel** | Episodic memory, reflection, skill nodes (score ±1, bounded [-20,20]), nightly training, skill decay/pruning, **auto-capture + Claude Code hooks (on by default)**, **SkillOpt-lite** bounded guidance edits, four-class lifecycle + **canary gate for synced skills**, `npm run backfill:episodes`, contribution reports (`skill report` / `graphflow_diagnose` / `route diagnose`) |
+| **Team sharing** | `skill sync`: export/import skill packs to a committable `.graphflow/skills/team-skills.json`; imports are a **bidirectional MERGE** (per-skill-id union, newer `updatedAt` wins, ties keep local, local-only skills preserved; `--force` to overwrite); golden retrieval queries round-trip via `.graphflow/team-golden.json`; [security model](docs/team-memory-security.md) |
+| **Benchmarks** | [Comprehensive 92.9%](benchmarks/COMPREHENSIVE-RESULTS.md) · [Independent-style 96.2%](benchmarks/INDEPENDENT-RESULTS.md) · [context-readiness eval](benchmarks/SWE-BENCH-RESULTS.md) · [98.2% token savings](benchmarks/RESULTS.md) |
+| **Model routing** | Smart / Economy tiers; multi-provider health probes and fallback (DeepSeek, OpenAI, Anthropic, Bailian, Doubao) |
+| **Observability** | `graphflow_diagnose` / `route diagnose`: provider health + graph stats + token savings + **flywheel health** (auto-capture, episodes, skills by class, session journal) |
+| **Agent surfaces** | CLI `--json`; MCP stdio (10 tools); auto-install into 15+ agents (incl. **Codex Windows NODE/NPX_CLI short-path MCP**) |
+| **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.
+
+## MCP tools (10)
+
+| Tool | Function |
 | --- | --- |
-| `graphflow_context` | 压缩上下文包（query → 锚点 + 摘要；anchorId → 展开） |
-| `graphflow_plan` | 任务规划（mode='simple' 或 'insight'；无 LLM 时 agent-delegated） |
-| `graphflow_run` | 编排 + Bridge 执行描述符 |
-| `graphflow_report_outcome` | 结果回填（含 deviation 偏离分类），闭环学习飞轮 |
-| `graphflow_insight` | ATP 洞察 submit / merge（Agent 桥接协议） |
-| `graphflow_index` | 增量 / 全量索引 |
-| `graphflow_skill_insights` | 技能洞察 |
-| `graphflow_diagnose` | 诊断（provider + 图 + token 节省 + 飞轮） |
-| `graphflow_artifact` | 图谱 artifact 导入 / 导出 |
-| `graphflow_skill_guide` | GraphFlow Skill 使用指南 |
+| `graphflow_context` | Compressed context package (query → anchors + summaries; anchorId → expand) |
+| `graphflow_plan` | Task planning (mode='simple' or 'insight'; agent-delegated without an LLM) |
+| `graphflow_run` | Orchestration + bridge execution descriptor |
+| `graphflow_report_outcome` | Outcome backfill (incl. deviation classification), closes the learning flywheel |
+| `graphflow_insight` | ATP insight submit / merge (agent bridge protocol) |
+| `graphflow_index` | Incremental / full indexing |
+| `graphflow_skill_insights` | Skill insights |
+| `graphflow_diagnose` | Diagnostics (provider + graph + token savings + flywheel) |
+| `graphflow_artifact` | Graph artifact import / export |
+| `graphflow_skill_guide` | GraphFlow skill usage guide |
 
-**MCP 工作区解析**：自动从 MCP 客户端 `cwd` 发现工作区；也可用 `GRAPHFLOW_WORKSPACE_ROOT` 显式指定。
+**MCP workspace resolution**: the workspace is discovered automatically from the MCP client `cwd`; override with `GRAPHFLOW_WORKSPACE_ROOT`.
 
-## CLI 速查
+## CLI quick reference
 
 ```bash
-graphflow graph index .                    # 建图
-graphflow context preview "orchestrator"   # 上下文预览
-graphflow plan "refactor planner" --json   # 规划
-graphflow run "update readme"              # 编排（Bridge）
-graphflow skill insights                   # 技能洞察
-graphflow skill report                     # 飞轮贡献报告
-graphflow skill sync export                # 导出团队技能包 + golden 查询集（git 共享）
-graphflow skill sync import                # 导入团队技能包（MERGE；--force 覆盖）＋ golden 合并到 .graphflow/team-golden.json
-graphflow route diagnose                   # 路由诊断
-graphflow learn nightly                    # 夜间学习
-graphflow doctor                           # 安装自检
+graphflow graph index .                    # build the graph
+graphflow context preview "orchestrator"   # preview compressed context
+graphflow plan "refactor planner" --json   # plan
+graphflow run "update readme"              # orchestrate (bridge)
+graphflow skill insights                   # skill insights
+graphflow skill report                     # flywheel contribution report
+graphflow skill sync export                # export team skill pack + golden queries (share via git)
+graphflow skill sync import                # import team skill pack (MERGE; --force to overwrite) + golden merge into .graphflow/team-golden.json
+graphflow route diagnose                   # routing diagnostics
+graphflow learn nightly                    # nightly learning
+graphflow doctor                           # install self-check
 ```
 
-## 配置
+## Configuration
 
-三层合并：全局 `~/.graphflow.config.json` → 项目 `graphflow.config.json` → 项目 `.graphflow/config.json`。复制 [graphflow.config.example.json](graphflow.config.example.json) 起步。
+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:
 
-| 配置 | 说明 |
+| Option | Description |
 | --- | --- |
-| `graphPolicy.transport` | `file` / `memory` / `sqlite` / **`auto`（推荐：sqlite 优先，不可用自动降级 file）** / `mcp-http` |
-| `graphPolicy.maxContextTokens` | 上下文预算（默认 1500） |
-| `graphPolicy.autoIndexOnSave` | 保存时自动增量索引（默认 true） |
-| `embeddingPolicy.provider` | `transformers`（本地默认）/ `openai` / `hash` |
-| `embeddingPolicy.vectorStorePath` | 向量索引持久化路径（自动派生 `.hnsw`） |
-| `skillPolicy.enableSkillFlywheel` | 学习飞轮开关 |
+| `graphPolicy.transport` | `file` / `memory` / `sqlite` / **`auto` (recommended: sqlite-first, falls back to file)** / `mcp-http` |
+| `graphPolicy.maxContextTokens` | Context budget (default 1500) |
+| `graphPolicy.autoIndexOnSave` | Auto incremental index on save (default true) |
+| `embeddingPolicy.provider` | `transformers` (local default) / `openai` / `hash` |
+| `embeddingPolicy.vectorStorePath` | Vector index persistence path (`.hnsw` derived automatically) |
+| `skillPolicy.enableSkillFlywheel` | Learning flywheel switch |
 
-## Team backend pilot（团队后端试点）
+## Team backend pilot
 
-将 `graphPolicy.transport` 设为 `mcp-http` 即可把图谱托管到远程 Graphify 服务（团队共享），需配置 `graphPolicy.mcpEndpoint`（http(s) URL，可选 `mcpApiKey` bearer token）：
+Set `graphPolicy.transport` to `mcp-http` to host the graph on a remote Graphify service (shared by the team); requires `graphPolicy.mcpEndpoint` (http(s) URL, optional `mcpApiKey` bearer token):
 
 ```json
 { "graphPolicy": { "transport": "mcp-http", "mcpEndpoint": "http://graphify.team.internal:8080" } }
 ```
 
-Endpoint 缺失/格式非法会在配置校验时直接报错；连接失败或运行期请求失败则透明降级到本地 JSON 文件存储（`graphPolicy.graphStorePath`，默认 `graphflow-out/graphflow-graph.json`）并记录 `logger.warn`，与 sqlite→file 降级一致，不会中断 Agent 流程。试点协议暂不支持全量快照：`readSnapshot` 返回本地镜像文件（可能滞后）。
+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. The pilot protocol does not yet support full snapshots: `readSnapshot` returns the local mirror file (possibly stale). For the team-sharing security model, 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
 
-- **Token 节省**：[benchmarks/RESULTS.md](benchmarks/RESULTS.md) — 8 个代表性查询，230,069 → 2,893 tokens（**98.7%**），独立 gpt-tokenizer 复核，`npm run benchmark` 可复现。
-- **Skill 飞轮 A/B**：[benchmarks/SKILL-AB-RESULTS.md](benchmarks/SKILL-AB-RESULTS.md) — 注入率 100%、episode 召回 100%、平均开销 25.6 tokens/任务，`npm run benchmark:skills` 可复现。
-- **检索召回**：golden set（26 查询）纳入 CI 回归门禁，防止压缩/排序改动悄悄劣化召回。
+## VS Code / Cursor extension
 
-## VS Code / Cursor 扩展
+Download `graphflow-<version>.vsix` from [GitHub Releases](https://github.com/Roarpeng/GraphFlow/releases) (or Open VSX: `roarpeng.graphflow`).
 
-从 [GitHub Releases](https://github.com/Roarpeng/GraphFlow/releases) 下载 `graphflow-<version>.vsix` 安装（或 Open VSX：`roarpeng.graphflow`）。
+Commands: Settings / Show Graph (graph visualization) / Preview Context / Plan & Brainstorm / Run Task / Skill Insights / Install MCP; chat agent `@graphflow` (`/run` `/plan` `/graph` `/skills` `/diagnose` `/learn` `/history`).
 
-命令：Settings / Show Graph（图谱可视化）/ Preview Context / Plan & Brainstorm / Run Task / Skill Insights / Install MCP；Chat Agent `@graphflow`（`/run` `/plan` `/graph` `/skills` `/diagnose` `/learn` `/history`）。
+## Agent Plugins 1.0
+
+**Primary install path** for hosts that support [Agent Plugins](https://agent-plugins.org). GraphFlow ships as a portable package at the repository root:
+
+```text
+plugin.json              # Agent Plugins 1.0 manifest
+mcp.json                 # stdio MCP (type required by the spec)
+skills/graphflow/SKILL.md
+```
 
-## Agent 集成
+**Install in Cursor (local):**
 
 ```bash
-npx @roarpeng/graphflow doctor     # 检测已安装的 Agent
-npx @roarpeng/graphflow install    # 自动安装 MCP + Skill + Rules
-npx @roarpeng/graphflow init       # 写入最小项目配置
+mkdir -p ~/.cursor/plugins/local
+ln -s /absolute/path/to/GraphFlow ~/.cursor/plugins/local/graphflow
+# then Restart Cursor / Developer: Reload Window
 ```
 
-支持：Cursor、VS Code、Trae（含 CN）、Claude Code、Windsurf、Cline、Roo Code、Kilo Code、Gemini CLI、Codex、Antigravity、Opencode、Qoder、Amazon Q、Zed、Continue 等 15+。
+**Install via Team Marketplace / Git:** import this repository; clients discover `plugin.json`, then load `skills/` and `mcp.json`.
+
+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:
+
+```bash
+npx @roarpeng/graphflow uninstall
+```
+
+That removes user + workspace MCP entries, `skills/graphflow` folders, GraphFlow rules/instruction blocks, and Claude Code hooks. Also delete any local symlink under `~/.cursor/plugins/local/graphflow` if you used one.
+
+## Agent integrations
+
+Use **`npx @roarpeng/graphflow install` as the fallback** when you need Rules, multi-agent wiring, or a host that does not load Agent Plugins:
+
+```bash
+npx @roarpeng/graphflow doctor     # detect installed agents
+npx @roarpeng/graphflow install    # auto-install MCP + Skill + Rules
+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, and more (15+).
+
+| 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 |
+
+## 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/).
+
+## Community
 
-## 协议
+GraphFlow is a single-maintainer project (bus factor = 1); community collaboration is the key to reducing single-point risk. Contributions welcome:
 
-[ATP/IR — Agent Thinking Protocol 公开规范 v1.0](docs/atp-ir-spec-v1.md)：work-item 注册表、submit/merge 契约、兼容性规则。第三方工具可实现兼容的 producer / consumer。
+- [Contributing guide](CONTRIBUTING.md): dev environment, code style, test requirements and PR checklist
+- [Roadmap](ROADMAP.md): completed milestones and next steps (P0–P2)
+- [Issues](https://github.com/Roarpeng/GraphFlow/issues): bug reports and feature requests (please use the built-in templates)
+- [Discussions](https://github.com/Roarpeng/GraphFlow/discussions): questions and ideas
 
-## 开发
+## Development
 
 ```bash
 npm install
-npm run ci        # lint + build + 测试 + 扩展打包 + smoke
+npm run ci        # lint + build + tests + extension packaging + smoke
 ```
 
-要求 Node.js ≥ 20、npm ≥ 10。预期：lint 无错误、构建成功、455 测试通过。
+Requires Node.js ≥ 20, npm ≥ 10. Expected: lint clean, build succeeds, 692 tests pass.
 
-## 项目结构
+## Project structure
 
 ```text
 GraphFlow/
+├── plugin.json         # Agent Plugins 1.0 manifest
+├── mcp.json            # Agent Plugins MCP (stdio)
+├── skills/graphflow/   # portable Agent Skill (canonical SKILL.md)
 ├── src/
-│   ├── core/           # 编排核心：orchestrator, triage, dag-engine, agent-delegation
-│   ├── graph/          # 索引、上下文切片、图压缩、sqlite/auto 存储、snapshot
-│   ├── routing/        # 模型路由与健康探测（5 provider）
+│   ├── 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 工具）
-├── tests/              # 92 文件 / 455 tests（含检索 golden set、goal anchor）
-├── benchmarks/         # token 节省 + skill A/B 基准（可复现）
-├── docs/               # ATP v1.0 设计 + ATP/IR 公开规范
-├── vscode-extension/   # VS Code 面板与命令
+│       └── mcp/        # MCP server (10 tools)
+├── tests/              # 99 files / 692 tests (incl. retrieval golden set, bridge+DAG)
+├── benchmarks/         # comprehensive + independent + SWE-bench + token savings + skill A/B (reproducible)
+├── docs/               # ATP spec + context contract + experience memory + comparisons
+├── vscode-extension/   # VS Code panel and commands
 └── CHANGELOG.md
 ```
 
-## 历史变更
+## Changelog
 
-详细记录见 [CHANGELOG.md](CHANGELOG.md)。License：Apache-2.0。
+Full history in [CHANGELOG.md](CHANGELOG.md). License: Apache-2.0.

package/dist/agents/atp-example-producer.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Minimal ATP/IR producer helpers for third-party–compatible simple-plan work items.
+ * Pure builders (no network / no GraphFlow LLM). See examples/atp-minimal-producer/.
+ *
+ * Emits atp-ir/1.1 required simple-plan items plus optional alignment-check and
+ * atp-ir/1.2 optional memory markers (memory-recall / memory-backfill). v1.1
+ * consumers ignore unknown optional items per spec §7.
+ */
+import { SIMPLE_PLAN_BRIDGE_REQUIRED_IDS, type AgentWorkItem } from "../core/agent-delegation.js";
+export { SIMPLE_PLAN_BRIDGE_REQUIRED_IDS };
+/** Protocol version emitted by the reference minimal producer. */
+export declare const ATP_MINIMAL_PRODUCER_PROTOCOL: "atp-ir/1.2";
+export type MinimalProducerOptions = {
+    /**
+     * Include atp-ir/1.2 optional memory-recall / memory-backfill markers.
+     * Default true. Set false for a pure v1.1 work-item set.
+     */
+    includeMemoryItems?: boolean;
+};
+/**
+ * Optional host-managed memory markers (atp-ir/1.2 §8). Agents MUST NOT treat
+ * these as required or answerable; consumers targeting v1.1 ignore them.
+ */
+export declare function buildOptionalMemoryWorkItems(): AgentWorkItem[];
+/**
+ * Build the documented simple-plan bridge work-item set (intent + decomposition
+ * required; optional alignment-check; optional v1.2 memory markers).
+ * Stable machine IDs match docs/atp-ir-spec-v1.md §4.2 / §8.
+ */
+export declare function buildMinimalSimplePlanWorkItems(task: string, options?: MinimalProducerOptions): AgentWorkItem[];
+/** Required simple-plan IDs only (no optional alignment-check or memory markers). */
+export declare function buildRequiredSimplePlanWorkItems(task: string): AgentWorkItem[];
+//# sourceMappingURL=atp-example-producer.d.ts.map

package/dist/agents/atp-example-producer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"atp-example-producer.d.ts","sourceRoot":"","sources":["../../src/agents/atp-example-producer.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EACL,+BAA+B,EAC/B,KAAK,aAAa,EACnB,MAAM,6BAA6B,CAAC;AAErC,OAAO,EAAE,+BAA+B,EAAE,CAAC;AAE3C,kEAAkE;AAClE,eAAO,MAAM,6BAA6B,EAAG,YAAqB,CAAC;AAwCnE,MAAM,MAAM,sBAAsB,GAAG;IACnC;;;OAGG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B,CAAC;AAEF;;;GAGG;AACH,wBAAgB,4BAA4B,IAAI,aAAa,EAAE,CAqB9D;AAED;;;;GAIG;AACH,wBAAgB,+BAA+B,CAC7C,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,sBAAsB,GAC/B,aAAa,EAAE,CAoEjB;AAED,qFAAqF;AACrF,wBAAgB,gCAAgC,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,EAAE,CAK9E"}