GraphFlow

English | 中文

给编程 Agent 用的记忆与上下文 harness。 本地优先的代码知识图谱 · 有界上下文压缩（约 98% token 节省） · 跨会话学习飞轮。

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。

快速开始

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）

MCP 入口：

{
  "mcpServers": {
    "graphflow": {
      "command": "npx",
      "args": ["-y", "--package=@roarpeng/graphflow", "graphflow-mcp"]
    }
  }
}

Agent 应先调 graphflow_context 拿压缩上下文，再视需要调用 graphflow_plan。没有 LLM API Key 时会桥接到宿主 Agent（agent-delegated）。

工作台脉络（v1.9.14）

日常 Chat 仍是单线。复杂任务用 graphflow_plan 播种功能主题容器（画布上是计划步骤，不是一轮一节点）。点击节点，把 topicId 传给 graphflow_context 即可在该功能上继续或回到主线。问法跑偏会 Fork 孤立旁支，主线不被刷脏。答完再调 graphflow_context({ assistantReply }) 回填原文。树上的标题只用于显示；下一轮必读是 Goal + 祖先标题 + 该节点原文 Q/A。

按需唤醒（仍是 10 个 MCP 工具，不新增）：

graphflow workbench tree --json
# VS Code / Cursor：GraphFlow: Workbench Tree（活动栏默认收起）或 Chat /tree
# 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 的插件树。

能力

| 能力 | 说明 | dsh 工具名 | | --- | --- | --- | | 压缩上下文 | 查询 → 锚点 + 摘要；按 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 | | 产物 | 图谱 import / export | mcp__graphflow__graphflow_artifact | | 技能指南 | 给已连接 Agent 的用法说明 | mcp__graphflow__graphflow_skill_guide |

| 在 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） |

核心价值：本地 AST 知识图谱、L1–L3 分层压缩（实测约 98% token 节省）、跨会话 Episodic / Skill 飞轮。GraphFlow 不执行代码，只给宿主 Agent 压缩上下文和计划。Workbench 数据走 MCP graphflow_context / graphflow_diagnose 即可。

安装

方式 A：装进某个 profile（推荐）

dsh plugin --profile web add @roarpeng/graphflow
npx @deepseek-ai/dsh web

方式 B：home 级 overlay（所有 profile 生效）

先有 $DSH_HOME（默认 ~/.dsh），再执行：

npx @roarpeng/graphflow install

会写入：

| 路径 | 作用 | | --- | --- | | $DSH_HOME/cordis.patch.yml | 插入 mcp-graphflow（cwd: process.cwd()）与 graphflow-dsh glue | | $DSH_HOME/skills/graphflow/SKILL.md | Skill 目录（graphflow install）；bundle glue 也会在运行时 ctx.skills.register |

开发态也可：

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（英文文件名 / 符号名），不要只用泛化中文词检索。

不要在 cordis.patch.yml 里写死 GRAPHFLOW_WORKSPACE_ROOT。

卸载

npx @roarpeng/graphflow uninstall
# 若只从某个 profile 移除 bundle：
dsh plugin --profile web remove @roarpeng/graphflow

其它安装路径

| 路径 | 适用 | | --- | --- | | Agent Plugins 1.0（plugin.json + mcp.json + skills/） | Cursor 等支持插件清单的宿主 | | npx @roarpeng/graphflow install | Rules / 多 Agent / 非插件宿主（含 dsh overlay） | | VS Code / Cursor 扩展 | Open VSX：roarpeng.graphflow |

更多

完整英文文档、基准与协议：README.md · ATP/IR · 上下文合同 · 经验记忆