记忆图谱与省流编排 123caiji/dsh-memory-toolkit

dsh-memory-toolkit

DeepSeek Harness 记忆与 Token 优化插件工具包：跨会话知识图谱记忆 + 五层省 Token 编排。

DeepSeek Harness 的记忆与 Token 优化插件工具包。两个插件彼此独立，可组合使用，也可单独使用：

| 插件 | 包名 | 用途 |
| graph-memory | @123caiji/dsh-graph-memory | 跨会话知识图谱记忆：带类型的节点、因果关系、PageRank、社区、双路召回（向量 + FTS5） |
| lean-context | @123caiji/dsh-lean-context | 省 Token 编排：五层正交能力（纪律、收敛、路由、审计、重建） |

实测数据

以下数据来自实际运行（2026-08-18，Node v24.15.0，Windows 11）：

代码规模

| 指标 | graph-memory | lean-context | 合计 |
| TypeScript 源码行数 | 5,813 | 448 | 6,261 |
| 测试文件数 | 11 | — | 11 |
| 测试用例数 | 107 | — | 107 |

测试结果

Test Files 1 failed | 10 passed (11)
Tests 1 failed | 106 passed (107)
Duration 8.52s

- 106/107 测试通过（99.1% 通过率）
- 唯一失败：migration.test.ts 的临时目录清理（Windows EPERM 权限问题，非代码缺陷）

graph-memory Benchmark

插入 15 个渗透测试知识节点后的实际运行数据：

数据库大小: 4 KB 节点总数: 15 (TASK: 8, SKILL: 6, EVENT: 1) 关系总数: 14 (USED_SKILL: 3, SOLVED_BY: 3, REQUIRES: 3, PATCHES: 3, CONFLICTS_WITH: 2) 向量索引: 15 条 (128 维)

FTS5 搜索 "nmap 扫描" → 返回 3 条:
- [TASK] nmap-端口扫描: 对 192.168.1.0/24 执行 nmap -sS -sV 全端口扫描
- [TASK] wpscan-wordpress-扫描: 对 WordPress 站点执行 wpscan
- [TASK] nikto-web-扫描: 执行 nikto 对 Web 服务进行漏洞扫描

向量搜索 → 返回 5 条:
- [TASK] nmap-端口扫描
- [TASK] hydra-smb-暴力破解
- [SKILL] nuclei-漏洞扫描模板
- [TASK] sqlmap-注入检测
- [SKILL] burp-suite-代理抓包

lean-context Token 节约实测

纪律层注入成本（一次性）：

Discipline prompt: 2,914 bytes ≈ 911 tokens

对 DSH 仓库的 context_audit 实测（指令链 token 成本）：

./AGENTS.md 15,997 bytes ≈ 4,999 tokens
./docs/AGENTS.md 10,635 bytes ≈ 3,323 tokens
./.agents/skills/dsh-find-simplifications/ 14,680 bytes ≈ 4,588 tokens
./.agents/skills/dsh-prose-standard/ 9,139 bytes ≈ 2,856 tokens
./.agents/skills/dsh-translate-docs/ 10,316 bytes ≈ 3,224 tokens
./.agents/skills/record-browser-gif/ 12,195 bytes ≈ 3,811 tokens
./.agents/skills/dsh-code-review/ 8,278 bytes ≈ 2,587 tokens
...（共 14 个文件） TOTAL: 123,784 bytes ≈ 38,684 tokens

ZeroToken 模式下的输出节约（实测对比）：

| 场景 | 冗长输出 | 精简输出 | 节约 | 降幅 |
| A: "帮我看看这个函数做什么" | 213 tokens | 27 tokens | 186 tokens | 88% |
| B: 代码修复任务 | 214 tokens | 65 tokens | 149 tokens | 70% |

综合估算（100 轮会话）：

平均每轮节约: 168 tokens 纪律层成本: 911 tokens（一次性注入） 100 轮净节约: 15,889 tokens ROI: 17x（投入 1 倍 token 换回 17 倍节约）纪律层占比: 2.4%（相对于 38,684 tokens 指令链）

结论：纪律层仅占指令链 2.4% 的 token 成本，但通过 ZeroToken 模式可在每个会话中节约 70%-88% 的输出 token，100 轮会话 ROI 达 17 倍。

目录

- 快速安装
- 插件一：graph-memory（跨会话记忆）
- 插件二：lean-context（省 Token 编排）
- 配置参考
- 开发指南
- 验证与排查
- 许可证与致谢

快速安装

方式 A：从 GitHub 安装（推荐）

dsh 0.1.x 起，plugin 子命令必须带 --profile。下面示例用 web；桌面版通常是 desktop，可用 dsh profile list 确认。

安装整个工具包
dsh plugin --profile web add github:123caiji/dsh-memory-toolkit

或只安装单个插件（子包用 #path: 指定，没有 --subdir 这个参数）
dsh plugin --profile web add 'github:123caiji/dsh-memory-toolkit#path:/packages/graph-memory'
dsh plugin --profile web add 'github:123caiji/dsh-memory-toolkit#path:/packages/lean-context'

方式 B：从本地路径安装（开发模式） bash
git clone https://github.com/123caiji/dsh-memory-toolkit.git
cd dsh-memory-toolkit
pnpm install
pnpm build # 生成 dist/ 与 lib/；仓库已带编译产物，可跳过

从本地路径加载到 DSH

dsh plugin --profile web add ./packages/graph-memory
dsh plugin --profile web add ./packages/lean-context

方式 C：网页端安装

1. 启动 DSH Web：dsh web
2. 访问 http://127.0.0.1:3080
3. 进入 设置 → 插件 → 添加
4. 填入 github:123caiji/dsh-memory-toolkit
5. 选择要加载的子包

验证安装

dsh plugin --profile web list # 确认 graph-memory 和 lean-context 处于 active 状态

graph-memory 的数据库默认放在 $DSH_HOME/graph-memory/graph-memory.db；没有设置 DSH_HOME 时是 ~/.dsh/graph-memory/graph-memory.db。需要换位置时在 cordis.patch.yml 里填 dbPath。
dsh doctor # 诊断插件加载错误

插件一：graph-memory（跨会话记忆）

是什么

为 DeepSeek Harness 提供跨会话的长期记忆能力。基于 SQLite 知识图谱，把任务（TASK）、技能（SKILL）、事件（EVENT）存成节点，用五种因果关系连接，再用 PageRank 和社区检测做相关性排序。

核心特性：
- 三类节点：TASK（任务）/ SKILL（技能）/ EVENT（事件）
- 五种因果关系：USED_SKILL / SOLVED_BY / REQUIRES / PATCHES / CONFLICTS_WITH
- 双路召回：向量检索（可选）→ 社区扩展 → PageRank 排序；未配置向量时回退 SQLite FTS5 全文检索
- 自动注入：相关记忆在 Prompt Assembly 阶段自动注入上下文

使用方法

自动模式（无需操作）：插件加载后，相关记忆会自动注入到新会话的系统提示中。

工具调用：

| 工具 | 说明 | 示例 |
| gm_status | 查看数据库状态、节点数、关系数 | gm_status() |
| gm_search | 检索相关记忆 | gm_search(query="nmap 扫描", limit=5) |
| gm_record | 记录新节点 | gm_record(type="TASK", title="端口扫描", content="对 192.168.1.0/24 执行 nmap") |
| gm_stats | 查看图谱统计 | gm_stats() |

向量检索配置（可选）

不配置时自动回退 FTS5 全文检索。配置后启用语义向量召回，召回精度更高： bash

设置环境变量（DeepSeek Embedding API 示例）

setx GRAPH_MEMORY_EMBEDDING_API_KEY "your-api-key"
setx GRAPH_MEMORY_EMBEDDING_BASE_URL "https://api.deepseek.com/v1"
setx GRAPH_MEMORY_EMBEDDING_MODEL "text-embedding-v1"
setx GRAPH_MEMORY_EMBEDDING_DIMENSIONS "1024"

重启 DSH 后生效。验证：调用 gm_status，vectorEnabled 应为 true。

数据库位置

默认：~/.dsh/graph-memory/graph-memory.db

覆盖：在 profile 的 cordis.patch.yml 中修改 dbPath： yaml
- insert:
- id: graph-memory
name: '@123caiji/dsh-graph-memory'
config:
dbPath: /your/custom/path/graph-memory.db

完整文档见 packages/graph-memory/README_CN.md。

插件二：lean-context（省 Token 编排）

是什么

五层正交的 Token 优化能力，每层独立开关。内置纪律层和审计层，开箱即用；收敛、路由、重建层委托上游社区插件。

五层架构

| 层 | 作用机制 | 实现来源 | 默认 | 风险 |
| discipline（纪律） | systemPrompt 注入六模式决策表 | 内置 | 开 | 低 |
| convergence（收敛） | MCP 工具 schema 压缩 | 委托 dsh-mcp-lens | 关 | 低 |
| routing（路由） | 简单问题 flash 直答 | 委托 dsh-model-router | 关 | 中 |
| audit（审计） | 只读上下文成本审计 | 内置（context_audit 工具） | 开 | 低 |
| rebuild（重建） | Agent Loop 切片重建 | 委托 dsh-slice-agent-loop | 关 | 高 |

使用方法

纪律层（自动）：
- 插件加载后自动注入六模式决策表到系统提示
- 对 Agent 说「省 token」强化 ZeroToken 模式
- 说「详细解释」退出省 token 模式

审计层：bash

调用 context_audit 工具审计上下文 token 成本

context_audit(cwd=".")
输出：AGENTS.md / CLAUDE.md / .agents/skills//SKILL.md 的 token 成本 + 重复检测。

收敛 / 路由 / 重建层：安装上游插件后在配置中开启： bash
dsh plugin --profile web add github:labmimors/dsh-mcp-lens # 收敛层
dsh plugin --profile web add github:tianji-qingtian/dsh-model-router # 路由层
dsh plugin --profile web add github:TT-Wang/dsh-slice-agent-loop # 重建层（高风险，单独验证）

完整文档见 packages/lean-context/README.md。

配置参考

两个插件的配置都在各自的 cordis.patch.yml 中。可在 profile 层覆盖： yaml

~/.dsh/profiles/web/cordis.patch.yml

- insert:
- id: graph-memory
name: '@123caiji/dsh-graph-memory'
config:
recallMaxNodes: 10 # 召回最大节点数（默认 6） recallMaxDepth: 3 # 召回深度（默认 2） maintenanceInterval: 12 # 维护周期（小时，默认 6）

- id: lean-context
name: '@123caiji/dsh-lean-context'
config:
discipline:
enabled: true
audit:
enabled: true
cacheSeconds: 120
convergence:
enabled: true # 需先安装 dsh-mcp-lens routing: enabled: false rebuild: enabled: false # 高风险，默认关

开发指南

环境要求

- Node.js >= 20（推荐 22.19+ 或 24+）
- pnpm >= 9
- DSH 源码仓库（用于本地集成测试）

本地开发 bash
git clone https://github.com/123caiji/dsh-memory-toolkit.git
cd dsh-memory-toolkit
pnpm install

构建

pnpm run build

测试

pnpm run test

单个包

pnpm --filter @123caiji/dsh-graph-memory run build
pnpm --filter @123caiji/dsh-lean-context run test

目录结构

dsh-memory-toolkit/
├── package.json # workspace 根 ├── pnpm-workspace.yaml ├── LICENSE # MIT ├── README.md # 本文件 ├── .gitignore └── packages/ ├── graph-memory/ # 跨会话知识图谱记忆 (5,813 行 TS) │ ├── package.json │ ├── cordis.patch.yml # DSH 插件注册 │ ├── dsh.ts # DSH 工具注册入口 (428 行) │ ├── index.ts # 导出入口 (872 行) │ ├── src/ │ │ ├── engine/ # LLM/Embedding 引擎 │ │ ├── extractor/ # 节点提取器 │ │ ├── format/ # 格式化与组装 │ │ ├── graph/ # 图算法（PageRank/社区/去重/维护） │ │ ├── recaller/ # 召回逻辑 │ │ ├── store/ # SQLite 存储层 (643+ 行) │ │ └── types.ts # 类型定义 │ ├── test/ # Vitest 测试 (107 用例) │ ├── docs/ # 文档与图片 │ ├── README.md # 英文文档 │ ├── README_CN.md # 中文文档 │ └── LICENSE # MIT（双版权：adoresever + 123caiji） └── lean-context/ # 省 Token 编排 (448 行 TS) ├── package.json ├── cordis.patch.yml ├── src/ │ ├── index.ts # 统一入口 (126 行) │ ├── discipline.ts # 纪律层：六模式决策表 (65 行) │ └── audit.ts # 审计层：context_audit 工具 (257 行) ├── README.md # 完整文档 └── LICENSE # MIT

验证与排查

安装验证 bash
dsh plugin --profile web list

graph-memory active

lean-context active

graph-memory 验证
bash

在 DSH 会话中调用

gm_status()

期望输出：dbPath, nodeCount, relationCount, vectorEnabled

lean-context 验证 bash

纪律层：新会话的系统提示应包含 "Lean Context — Six-Mode Discipline"

审计层：context_audit 工具应可用

context_audit(cwd=".")

常见问题

| 问题 | 原因 | 解决 |
| Cannot find module '@photostructure/sqlite' | native binding 未编译 | pnpm install 时确认 allowBuilds 包含该包 |
| ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING | 入口是 .ts，而 Node 24 不会在 node_modules 里剥离类型 | 拉取最新提交（入口已改为 dist/dsh.js / lib/src/index.js）后重新安装 |
| JsonSchemaError: unsupported JSON schema: ... | 工具 schema 用了 DSH 强制子集不支持的写法（如把 required: true 写在数组/字符串节点的属性上） | 已在 1.6.0-beta.2 / 0.1.0-rc.6 修复：parameters 与 output.schema 都改成原生 JSON Schema，required 只挂在对象节点上 |
| YAMLException: bad indentation of a mapping entry | 旧版 cordis.patch.yml 的 !!js 值引号未闭合 | 已修复，拉取最新提交（!!js 已移除） |
| error: required option '--profile <name>' not specified | dsh 0.1.x 的 plugin 子命令必须带 profile | 命令里加 --profile web（或 desktop） |
| ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING | 入口是 .ts，而 Node 24 不会在 node_modules 里剥离类型 | 拉取最新提交（入口已改为 dist/dsh.js / lib/src/index.js）后重新安装 |
| YAMLException: bad indentation of a mapping entry | 旧版 cordis.patch.yml 的 !!js 值引号未闭合 | 已修复，拉取最新提交（!!js 已移除） |
| error: required option '--profile <name>' not specified | dsh 0.1.x 的 plugin 子命令必须带 profile | 命令里加 --profile web（或 desktop） |
| gm_status 返回 vectorEnabled: false | 未配置 embedding 环境变量 | 设置 GRAPH_MEMORY_EMBEDDING_ 后重启 DSH |
| 纪律层未生效 | systemPrompt section 未注入 | 检查 cordis.patch.yml 的 discipline.enabled: true |
| 委托层报 not wired yet | 上游插件未安装 | 按上文安装 dsh-mcp-lens / dsh-model-router / dsh-slice-agent-loop |

排查命令 bash
dsh doctor # 诊断插件加载错误
dsh plugin --profile web list # 列出全部插件
dsh plugin --profile web reload # 重载插件
dsh plugin --profile web remove <name> # 卸载

许可证与致谢

许可证

MIT。详见 LICENSE。

致谢

- graph-memory 衍生自 adoresever/graph-memory（MIT），感谢原作者的知识图谱记忆设计
- lean-context 的纪律层参考了 phoenixlucky/zerotoken-skill 的 ZeroToken 六模式决策表
- 感谢 DeepSeek 团队的 DeepSeek Harness 提供的插件化 Agent 框架

上游插件（可选依赖）

| 插件 | 用途 | 仓库 |
| dsh-mcp-lens | MCP 工具 schema 收敛 | labmimors/dsh-mcp-lens |
| dsh-model-router | 模型路由 | tianji-qingtian/dsh-model-router |
| dsh-slice-agent-loop | 智能体循环切片重建 | TT-Wang/dsh-slice-agent-loop |

贡献

欢迎提交 Issue 和 PR：

- Issue：https://github.com/123caiji/dsh-memory-toolkit/issues
- PR：https://github.com/123caiji/dsh-memory-toolkit/pulls

提交前请确保 pnpm run build 和 pnpm run test 通过。