狼图索引 hawk2048/dsh-openwolf

dsh-openwolf

DeepSeek Harness 的第二大脑。

更好的上下文管理、预索引项目地图、更聪明的 token 利用，通过 harness 隐形钩子交付。工作流零改动。

快速开始 · 它会创建什么 · 初始化 · 工作原理 · Token 智能 · 仪表盘 · 命令 · 变更日志

| 不用 dsh-openwolf | 用 dsh-openwolf |
| 模型反复整文件重读（每次 ~2,000 tokens） | 先读一行摘要，或干脆跳过读取 |
| 为找一个函数整文件读取 | 符号级提示给出精确行号，offset/limit 定向读 |
| 上下文压缩抹掉已做的工作 | PreCompact 快照 + 恢复摘要，工作留在上下文里 |
| 每个会话从冷提示开始 | 预算封顶的会话摘要预载目标、已知错误、最近修复与项目地图 |
| 不知道 token 花在哪 | harness token meter 实测 + 实时本地仪表盘 |

为什么用 dsh-openwolf？

编码智能体很强大，但它们是「盲」的。在打开文件之前，智能体不知道文件里有什么；它分不清 50-token 的配置和 2,000-token 的模块；同一会话里重读同一文件而不自知；跨会话忘记你的纠正；上下文窗口压缩时丢失一切。

dsh-openwolf 给 harness 一个修复这一切的第二大脑——灵感来自 Claude Code 版 OpenWolf，作为 DeepSeek Harness 原生插件从零实现（MIT，不含 AGPL 参考项目的任何代码）：

- 上下文管理。 每个会话开始注入一份预算封顶的摘要（当前目标、已知错误、已修复 bug、项目地图）。压缩快照 + 压缩感知恢复意味着上下文压缩不再抹掉会话已完成的工作。
- 架构脚手架。 一份持久、自愈的项目索引为每个文件标注描述、token 估算，大文件还索引函数与类及其精确行号。智能体导航你的代码库，而不是重新发现它。
- Token 利用。 重复读被拦下，整文件读变成定向切片读，真实用量从 harness token meter 实测——你可以验证节省，而不是相信估算。

快速开始

两种安装方式，二选一——最终都能获得完整体验。

方式 1 —— 装进 harness（推荐）

最直接的方式。 一条命令，每个会话获得完整体验（会话摘要、读/写拦截、工具、技能）：

dsh plugin --profile web add dsh-openwolf # 装进你的 profile
dsh web # 重启（或重启 GUI）

就这么简单。无需初始化、无需配置：第一个会话里插件扫描一次工作区，此后保持地图新鲜，在底层默默工作——harness 照常用，没有任何流程改动。

不想敲命令？让智能体帮你装。 把下面这句复制进任意会话（Web GUI 或 headless 都行），智能体会替你安装并重启：

帮我把 dsh-openwolf 装进当前 profile，然后重启让它生效。

智能体会执行 dsh plugin --profile web add dsh-openwolf、重启，然后确认装好了。（用自己的话表达也可以——智能体理解意图，不挑措辞。）

方式 2 —— 独立安装 CLI，再接进 harness

本包也是普通 npm 包：装在任何地方，dshwolf CLI 即可独立使用（init / （scan / status / report / dashboard / cron / backups）：

npm install -g dsh-openwolf # 或项目内：npm install --save-dev dsh-openwolf
dshwolf init . && dshwolf scan . # 初始化 + 索引当前目录

要在 harness 里也使能（会话获得工具、会话摘要、读/写拦截——而不只是 CLI），把已装的包接进某个 profile——一条命令同时完成初始化 + 接线 + 安装依赖：

dshwolf init . --agent deepseek-harness # 初始化 + 接进默认 profile（web）
dsh web # 重启 harness（或重启 GUI）

也可以指定某个 profile 或全部，OpenWolf 风格：

dshwolf init . --agent headless # 接进 'headless' profile dshwolf init . --agent all # 接进所有 profile dshwolf harness status # 看看哪些 profile 已接线 dshwolf harness add web # 显式接线 + 安装到某个 profile

为什么需要这一步。 CLI 和 harness 插件是同一个 .dshwolf/ 大脑的两个前端——CLI 初始化的内容（地图、STATUS、memory、buglog、账本）正是 harness 读取的内容。但全局 npm install 对 harness 不可见：harness 只解析你 profile dependencies 里声明的包（已实测：profile node_modules 解析不到全局副本）。dshwolf init --agent（与 harness add）替你注册依赖 + bundle 行并自动运行 pnpm install——对应 OpenWolf openwolf init --agent claude 的一步到位（只想改 package.json 时用 --no-install，如 CI）。两个前端并存——CLI 给人和 cron 用、插件给会话用，共享同一个大脑。DSH 本身就是 agent 平台，所以"接线"= profile 里注册一行，而不是 OpenWolf 的 hook 文件安装。

从 git URL 或本地 checkout 安装需要额外的构建授权——见从源码安装。

装完你能得到什么（全部开箱即用，无需额外配置）：

| 领域 | 内容 |
| 会话内工具 | wolf_map · wolf_file · wolf_refresh · wolf_scan · wolf_init · wolf_status · wolf_learn · wolf_bug · wolf_report · wolf_schedule |
| 自动行为 | 会话开始摘要、重复读警告、符号行号提示、写动作日志、压缩幸存 |
| CLI 命令 | init · scan · scan --check · status · report · bug search · cron · register · update · backups · restore · dashboard · daemon |
| 仪表盘 | 实时本地面板：token、上下文健康、anatomy、活动、cron |

每个命令的用途场景见命令；自我维护机制（什么自动初始化、什么保持新鲜、什么时候才需要手动命令）见初始化与保持新鲜。

它会创建什么

首次扫描会在工作区创建 .dshwolf/ 目录：

| 文件 | 用途 |
| anatomy-index.json | 持久项目索引：描述、token 估算、内容哈希、符号 |
| anatomy.md | 索引的人类可读渲染，自动保持同步 |
| cerebrum.md | 学习到的偏好、纠正、Do-Not-Repeat 列表 |
| memory.md | 时序动作日志（含 token 估算） |
| STATUS.md | 会话交接：一次小读取即可恢复任何会话 |
| buglog.json | bug 修复记忆，可搜索，防止重新排查 |
| token-ledger.json | 实测 token 用量，按会话与 agent 统计 |
| hooks/ | 会话状态、扫描状态（git HEAD 钉住）、压缩前快照 |
| config.json | 配置，包括会话摘要预算 |
| OPENWOLF.md | agent 遵循的操作协议 |

为什么用 .dshwolf/ 而不是 .wolf/？ 原版 OpenWolf（面向 Claude Code / Codex / OpenCode / Gemini / Cursor）也使用 .wolf/ 大脑。我们把大脑放在独立的 .dshwolf/ 目录，意味着两个工具可以管理同一个工作区而互不覆盖彼此的配置、账本或记忆——未来的 OpenWolf 更新也永远不会逼着这里跟着改。
从本插件旧位置（0.9 之前）迁移：mv .wolf .dshwolf。从原版 OpenWolf 迁移：dshwolf import-openwolf——把 .wolf/ 的 cerebrum、memory、buglog、 STATUS 增量合并进 .dshwolf/（内容级去重、先备份、幂等），详见命令。（文件格式遵循 OpenWolf 行为规范——cerebrum、STATUS、 buglog、memory——所以一个项目可以选择任一大脑或两者并用。）

初始化与保持新鲜

无需任何手动初始化——插件在工作区的首次使用时惰性初始化大脑，之后自动重扫：

- 首次接触：第一次调用 wolf_ 工具（或第一个带 injectAgentsMd 的会话）即创建 .dshwolf/、扫描一次工作区、把地图注入 AGENTS.md。不需要单独执行 init。
- 自动刷新：防抖 watcher 在文件变更时重扫；write/edit 结果立即重分析被改文件，地图和 anatomy.md 随你的工作保持新鲜。
- 会话开始摘要：每个新会话注入预算封顶的摘要（STATUS 🚀 / Do-Not-Repeat / 最近 bugs / anatomy 指针），扫描过旧或 git HEAD 移动时给出陈旧警告。

想要显式控制时，一切都是一条命令（会话内也有对应工具）：

| 你想… | 命令（CLI） | 工具（会话内） |
| 立刻从磁盘重建整个索引 | dshwolf scan | wolf_refresh |
| 校验索引与文件系统一致（CI 友好） | dshwolf scan --check | wolf_scan |
| 手动初始化 .dshwolf/（幂等，很少需要） | dshwolf init | wolf_init |
| 读写会话交接文档 | dshwolf status | wolf_status |
| 更新所有已注册项目（先备份） | dshwolf update | — |
| 从时间戳备份回滚 .dshwolf/ | dshwolf restore | — |
| 定时无人值守重扫（零 token） | dshwolf cron add … scan | wolf_schedule |

提示：这些基本都不需要——插件的职责就是让大脑自我维护。只有当你在 harness 之外改了大量文件（例如一次大 git pull）想立刻重建地图时，才需要跑 dshwolf scan。

工作原理

会话开始插件注入预算封顶的摘要：当前目标、已知错误、最近 bug 修复、项目地图指针 agent 决定读一个大文件
插件："auth.ts (~2,900 tok)。符号: validateToken L82-140 ~450 tok。
用 offset/limit 只取你要的部分。"
agent 编辑文件插件在跨进程锁下更新索引、记录动作、刷新被改文件的条目会话中途上下文压缩插件在压缩前快照状态，压缩后重新注入"本会话已改文件"摘要， agent 不会重做已完成的工作会话结束插件从 harness token meter 读取真实用量写入账本

代码地图通过 harness 内置的 agent-instructions 插件预载：插件在工作区 AGENTS.md 内维护一个标记围栏块（你自己的内容从不被改动，相同内容绝不重写），所以每个会话开始时地图已经在上下文里。

上下文管理

- 会话摘要。 会话开始时把最高价值状态推进模型上下文，按可配置的 token 预算封顶（各段成本优先用 harness token meter 的启发式计价）。模型不需要读六个文件就能拿到所需。
- 压缩幸存。 compaction/start 快照；压缩后摘要列出已修改文件并指向动作日志。恢复与压缩不再重置跟踪。
- 陈旧检测。 扫描钉住 git HEAD。HEAD 移动或扫描超龄时，agent 会被提示先重扫再信任地图——错误索引绝不会被静默信任。
- STATUS.md 交接。 阶段末状态放在一份小文档里，新会话一次读取即达生产性上下文。
- 维护提醒。 cerebrum 过少 → 用 wolf_learn；buglog 为空 → 用 wolf_bug。插件提醒，模型喂大脑。

项目解剖

索引是持久存储（anatomy-index.json）加人类可读渲染（anatomy.md）。写入方通过跨进程锁协调，并发 hook 触发不丢条目。手改 markdown 会被内容哈希检测并 加性吸收（绝不覆盖）。

超过 500 估算 token 的文件还索引顶层符号：

- shared.ts (~3,200 tok)
- fn parseAnatomy L82-104 (~180 tok)
- fn serializeAnatomy L106-129 (~200 tok)

在大文件被读取前，提示列出最大的符号及其行号，agent 用 offset/limit 取一个函数而不是整个文件。文件在索引后变过则自动抑制提示——过期行号绝不会误导读取。
当前符号支持：TypeScript、JavaScript、Python、Go、Rust、Java（lezer CST 解析，可选依赖——其余语言回退正则启发式）。

Token 智能

估算有用，实测可信。插件从 harness token meter（ctx.tokenMeter， provider 上报）读取真实用量，按会话写入账本：

dshwolf report

token ledger: 12 sessions
measured (harness token meter): ~1,549,658 tokens
estimated (heuristic): ~1,420,011 tokens
current session: ~57,489 tokens

DeepSeek Harness 实测 A/B（同一"1 读 1 编辑"任务、同一份 3 文件工作区、 provider 上报合计）：

| 运行 | 读取 | 编辑 | 计费 tokens |
| 带 dsh-openwolf | 1 | 1 | 39,164 |
| 不带 | 1 | 1 | 35,488 |
| 差值 | | | +3,676（+10%） |

诚实解读：在"单次读取"的最小任务上，插件是净开销——固定成本占优。
省 token 的机制（避免重复读、offset/limit 定向读、地图优先导航）要等会话读多个文件或重复读同一文件时才兑现。原版项目字段数据（启发式估算）平均 ~65.8% token 下降、拦下 71% 的重复读。预期：会话触及多个文件或足够长时回本。

插件每个会话新增什么：

| 组件 | 频次 | 大小 |
| 会话摘要（+维护提醒） | 会话开始 | ≤ 1,500 tokens（可配） |
| AGENTS.md 地图块（injectAgentsMd 开启时） | 会话基线 | ≤ maxMapBytes（16 KiB ≈ 4k tokens） |
| 10 个 wolf_ 工具 schema | 每个请求 | ≈ 1–2k tokens（KV-cache 前缀稳定） |
| 2 条技能目录条目 | 会话基线 | ≈ 100 tokens |

一次性小任务可考虑 digestEnabled: false / injectAgentsMd: false / 调小 maxMapBytes。

安全

- 仪表盘只绑定 127.0.0.1，所有 API 访问需要逐项目 token（timing-safe 比较）；token 可放 --token-file（chmod 600），不出现在命令行参数里。
- 所有动态进程调用使用参数数组，任何地方都不做 shell 插值。
- 所有文件访问都有路径穿越防护。
- 密钥类文件（keys、keystores、凭据文件、.npmrc、.env 等）绝不进入索引、提示或日志；模板（.env.example）保持可索引。
- 安全回归套件随 pnpm test 运行。

内置技能

两个技能注册进 harness 技能目录：

- wolf-security-audit —— 分层审计（依赖 → 秘密 → 注入面 → 授权），产出严重度排序报告并写入 .dshwolf/buglog.json。
- wolf-reframe —— 设计大脑。从 13 框架知识库挑选或迁移 UI 框架，或按反"AI 味"设计准则审计/修复现有 UI：独特性是验收标准，一眼可辨的 AI 生成外观是失败态。

仪表盘

dshwolf daemon start
dshwolf dashboard

本地、token 认证的仪表盘：实测 vs 估算 token、上下文健康（扫描新鲜度、钉住的
git HEAD、摘要预算）、会话交接、实时活动、cron 控制、带逐文件符号的 anatomy
浏览器。面板可深链（/#tokens）。页面是实时的——SSE 流在 brain 文件一变就重渲染当前面板，流断开时回退 30s 轮询。

命令

所有命令都接受可选目录参数（默认当前工作目录）。按使用场景分组：

大脑生命周期

| 命令 | 作用 | 什么时候用 |
| dshwolf init [dir] | 创建 .dshwolf/（幂等）；--agent <profile\|all\|deepseek-harness> 同时接线 + 安装进 harness | 通常不需要——大脑首次使用时自动初始化；--agent 是方式 2 的一条命令初始化 |
| dshwolf scan [dir] | 重建项目索引、渲染 anatomy.md、注入 AGENTS.md | 在 harness 之外做了大改动（如 git pull）想立刻重建地图 |
| dshwolf scan --check [dir] | 校验索引与文件系统一致（size/mtime + git HEAD） | CI 或会话前校验；漂移退出码 1 |
| dshwolf status [dir] | 大脑健康：配置、扫描状态、账本、memory/buglog 计数 | "我的大脑健康吗？" |
| dshwolf report [dir] | token 账本摘要：各会话实测 vs 估算 | 弄清楚 token 花在哪 |
| dshwolf import-openwolf [dir] | 把已有 OpenWolf .wolf/ 大脑合并进 .dshwolf/（cerebrum/memory/buglog/STATUS，内容级去重，--dry-run/--from=<dir>/--status=…） | 从 Claude Code 等带 OpenWolf 大脑的项目迁移到 dsh-openwolf |

harness 接线（方式 2 独立安装后）

| 命令 | 作用 | 什么时候用 |
| dshwolf harness status | 列出 DSH profiles，标出哪些已接 dsh-openwolf | "我哪些 profile 已经装了插件？" |
| dshwolf harness add [name] | 把插件写进某 profile 的 package.json（dependencies + bundles）并自动运行 pnpm install（默认 profile web；--no-install 只改文件） | 方式 2 独立安装后，一条命令获得会话内体验（然后重启） |

记忆与 bug

| 命令 | 作用 | 什么时候用 |
| dshwolf bug search <term> | 搜索 .dshwolf/buglog.json | 重新排查可能已修复的问题之前 |
| dshwolf register [dir] | 把工作区加进全局项目注册表 | 让 dshwolf update 覆盖你所有项目 |
| dshwolf unregister [dir] | 从注册表移除 | 清理 |
| dshwolf update | 备份 + 重扫所有已注册工作区 | 一次性刷新所有已索引项目 |

备份

| 命令 | 作用 | 什么时候用 |
| dshwolf backups [dir] | 列出时间戳 .dshwolf/ 备份 | 看有哪些可回滚 |
| dshwolf restore [dir] [tag] | 从备份恢复 .dshwolf/（默认最新） | 实验搞砸之后 |

调度与服务

| 命令 | 作用 | 什么时候用 |
| dshwolf cron add <name> '<expr>' <scan\|check> [dir] | 定时零 token 任务（cron 语法、@daily 等） | 无人值守刷新：如每晚 scan |
| dshwolf cron list [dir] / dshwolf cron run <id> / dshwolf cron remove <id> | 管理定时任务 | 查看或手动触发任务 |
| dshwolf dashboard [dir] | 前台运行 Web 仪表盘（--port / --token / --token-file） | 实时查看 token / 上下文 / anatomy |
| dshwolf daemon start [dir] / dshwolf daemon stop | 后台守护：仪表盘 + cron 调度 | 不占用终端地常驻仪表盘与定时任务 |

所有命令也以工具形式出现在会话里（wolf_map、wolf_file、wolf_refresh、 wolf_scan、wolf_init、wolf_status、wolf_learn、wolf_bug、 wolf_report、wolf_schedule）——模型自己能做这一切，命令行只是给人、脚本和 cron 用的。

全局选项：dshwolf --help（分组帮助）与 dshwolf --version 随处可用；裸 dshwolf 也打印帮助。子命令组也有自己的帮助——dshwolf cron --help、dshwolf daemon --help、 dshwolf bug --help、dshwolf harness --help（或只敲组名）。旧名 wolf 仍可作为别名使用。

环境要求

- Node.js >= 20.19.0（engines.node）
- DeepSeek Harness >= 0.1.0-rc.6 < 0.3.0（engines.dsh）
- 运行时用到的宿主包（peerDependencies）： @deepseek-ai/dsh-tools、@deepseek-ai/dsh-skill、@deepseek-ai/dsh-llm、 @deepseek-ai/dsh-session 均 >= 0.1.0-rc.6，@deepseek-ai/cordis ^4.0.1
- 任意 DeepSeek Harness 配置档（web、headless、…）
- Windows、macOS 或 Linux

已在 DSH 0.2.0-rc.2（dsh-desktop 0.11.0）+ cordis 4.0.4 上验证。

宿主版本以 package.json 的 engines.dsh 与 peerDependencies 为准 —— 插件市场按它们判定兼容性。@deepseek-ai/dsh-session 列为 peer，是因为会话格式代际（SESSION_FORMAT_VERSION）由它持有：宿主换格式这类破坏必须能在声明层面被发现。

配置

所有选项经 schema 校验、默认值合理；无需配置任何东西。在配置档的 cordis.patch.yml 中按行 id（openwolf）覆盖：

- id: openwolf
config:
maxMapBytes: 16384 # 注入/返回地图文本的上限（字节） maxFileBytes: 65536 # 超过此大小的文件只列不读 maxFiles: 4000 # 每个工作区扫描文件数上限 watch: true # 防抖 watcher，文件变更自动重扫 injectAgentsMd: true # 维护 AGENTS.md 受管块 useGitignore: true # 遵循根目录 .gitignore symbols: true # 提取顶层符号 symbolBackend: auto # auto | regex | lezer（CST 解析） sessionDigestBudgetTokens: 1500 # 注入的会话摘要 token 上限 rescanIntervalHours: 6 # 重扫警告前的陈旧窗口 symbolThresholdTokens: 500 # 超过此 token 数的文件给符号行号提示 digestEnabled: true # 会话开始时注入会话摘要 interceptReads: true # 重复读警告 + anatomy 提示 interceptWrites: true # 动作日志 + 单文件索引刷新 compactionSurvival: true # 压缩快照 + 恢复摘要 skillsEnabled: true # 注册 wolf-security-audit + wolf-reframe autoRescanMinutes: 0 # 每 N 分钟自动重扫缓存根（0 = 关）

后层可按 id 整体覆盖该行，部署方保留自己的默认值。

限制

- 实测 vs 估算 —— 实测数字来自 harness token meter，精确；启发式估算是字符比近似。
- 多智能体接线 N/A —— 原版钩 5 个外部智能体（Claude Code/Codex/ OpenCode/Gemini/Cursor）；DSH 本身是智能体平台，一个大脑服务所有 DSH 会话与子代理。
- cron 引擎自研 —— 每次运行 0 token，有意不接 harness 的模型面向调度器（后者每次触发烧一次 LLM 轮次）。
- dashboard 是零依赖服务器渲染单页（面板子集），非 React SPA。
- 仅根级 .gitignore —— 暂不支持嵌套 .gitignore 与 git check-ignore 的精确语义。
- 读提示随结果到达 —— tools/post-execute 把提示附加在结果上下文上（DSH 目前没有读前拦截缝）。
- 摘要注入依赖智能体生命周期 —— 从持久日志恢复的会话跳过摘要（历史完整，与原版 resume 行为一致）。
- 发现问题？提交 issue。

开发

pnpm install
pnpm build # tsc → lib/
pnpm test # node --test，进程内执行

本包是可擦除 TypeScript + rewriteRelativeImportExtensions：node 可直接运行 src/ 做测试，tsc 产出发布用的 ESM lib/。prepare 脚本从源码构建，这正是 git 安装能工作的原因。想在真实 harness profile 里跑本地 checkout，见从源码安装。

License

MIT —— 对代码地图/上下文大脑思路的独立实现，不含任何 AGPL 项目的代码。
为 DeepSeek Harness 构建。