分支交接记忆 FleetingEcho/dsh-handoff

dsh-handoff

为 DeepSeek Harness (dsh) 提供持久化工作记忆：每个 git 分支自动维护一个 handoff.md，外加在每个分支上都可用的共享项目知识。

这是 pi-handoff 的 Cordis 插件移植版。磁盘上的存储与 pi-handoff 逐字节完全相同，因此两个 agent 共享位于 ~/.agent/agent-handoff/ 的同一个存储，并能互相读取对方的 handoff.md、project.md 和 events.jsonl。如果你已经在 pi 上使用 pi-handoff，切换到 dsh（或同时运行两者）会复用你现有的 handoff 文件，无需迁移。

该扩展会记录最近的对话轮次，定期将它们归纳为简洁的 Markdown，并通过 dsh 运行时上下文快照将结果注入未来的会话。不会向你的仓库写入任何内容。

这是一个树外社区插件，不属于官方 @deepseek-ai/ 包。@deepseek-ai/ 运行时包是可选的 peer 依赖，由 dsh 在加载时解析。

快速开始

你不需要克隆或构建任何东西——已发布的仓库自带预构建的 lib/index.js，dsh plugin add 会自动激活它（该包声明了 dsh.bundle.patch，因此会自动协调进 profile 的 bundle 列表）。一条命令：

Install into a profile (e.g. "web", the default GUI profile). The short
github: shorthand and the full HTTPS URL are equivalent:
dsh plugin --profile web add github:FleetingEcho/dsh-handoff
dsh plugin --profile web add https://github.com/FleetingEcho/dsh-handoff.git

然后重启该 profile（正在运行的 profile 在重启之前不会加载新层），打开一个会话，并确认：

/handoff status

你应该会看到存储路径（~/.agent/agent-handoff/...）、检测到的 git 分支，以及 recording: yes。完成——本 README 的其余部分均为参考内容。

第一次使用 dsh？$DSH_HOME 默认为 ~/.dsh，profile 位于 $DSH_HOME/profiles// 下。运行 dsh --help 列出命令，运行 dsh plugin --profile --help 查看插件管理标志。

安装到 profile

dsh profile 是 $DSH_HOME/profiles// 下按顺序排列的插件 bundle 栈。本插件是一个自激活 bundle（它在 package.json 中声明了 dsh.bundle.patch），因此 dsh plugin add 会完成全部工作：它在 profile 目录中运行 pnpm，将包复制进去，并将其协调进 dsh.profile.bundles。

从 GitHub 安装（推荐）

dsh plugin 是一个轻量的 pnpm 转发器，因此它接受任何 pnpm 包说明符。对本插件而言，下面两种形式是等价的——github:owner/repo 是 GitHub 仓库的 pnpm 简写，而完整的 HTTPS URL 则最为明确：

dsh plugin --profile add github:FleetingEcho/dsh-handoff
equivalent explicit form:
dsh plugin --profile add https://github.com/FleetingEcho/dsh-handoff.git
两种形式都会记录依赖（作为 github:FleetingEcho/dsh-handoff）并激活插件。同样的简写形式适用于任何托管在 git 上的 dsh 插件，例如 github:omdsh-dev/DSH-better-sidebar；你也可以用 github:owner/repo# 固定某个 ref。验证它已进入 bundle 列表并组合进配置树：

dsh --profile --dump-config | grep -A8 fleetingecho/dsh-handoff

你应该会看到一个带有其默认配置的 id: handoff 条目。然后重启该 profile 并运行 /handoff status。

从本地克隆安装

如果你想编辑源码，请改为安装本地目录（它是链接而非复制，因此在重新构建后，对 lib/index.js 的编辑会在下次 profile 启动时被拾取）：

cd /home/zteng/work/Tools/dsh-handoff
npm install && npm run build # only needed if you change src/*
dsh plugin --profile add /home/zteng/work/Tools/dsh-handoff

更新现有安装

dsh plugin --profile web update @fleetingecho/dsh-handoff

这会从 GitHub 拉取最新提交并协调该 profile 的插件树。更新后重启该 profile，然后在会话中运行 /handoff status 以验证新版本已加载。

移除

dsh plugin --profile web remove @fleetingecho/dsh-handoff

验证它已加载

在该 profile 下的会话中：

/handoff status

- 存储路径 + 检测到的分支 + recording: yes → 它已加载。
- handoff: not initialized for this session → 插件未加载。检查 dsh --profile --dump-config | grep -A8 fleetingecho 中是否有 id: handoff 行；如果不存在，说明 bundle 未激活（重新运行 add 命令）。如果该行存在但会话报告错误，请检查 profile 启动日志——最常见的加载失败是 Cannot find package '@deepseek-ai/...'，这源于以裸 link: 形式安装到 profile 之外的目录（请使用 GitHub/tarball 形式，或确保 @deepseek-ai/ 对等依赖能从该 profile 共享的 node_modules 中解析）。

记忆是如何组织的

dsh-handoff 保留三种具有不同生命周期的记忆：

| 记忆 | 作用域 | 用途 |
| handoff.md | 当前分支 | 目标、进度、决策、活跃文件以及后续步骤 |
| 项目知识 | 每个分支 | 经过审阅的架构、约定、工作流、可复用的决策以及陷阱 |
| 固定规则 | 每个分支 | 自动化摘要绝不能改写的硬性规则和明确偏好 |

每个 git 分支都有独立的 handoff.md。切换分支会自动切换 handoff（每轮都会重新检测）。项目知识和固定规则存放在 project.md 中，并在每个分支上注入。在 git 仓库之外，该目录使用单个 default 分支。

日常使用场景你通常只需正常工作。后台刷新大约每 thresholdTurns 轮运行一次，当大量材料累积时会更快触发，并且在每一轮稳定后也会运行。缓冲的事件是持久化的，因此退出无需等待模型调用。

you: "Add a login page to the app"
…agent works, writes files, runs tests…
[handoff silently records each turn and folds them into handoff.md]

you: /handoff status # peek at the store, pending events, pins, suggestions
you: /handoff flush # refresh the branch handoff right now

恢复下一个会话

用“keep going”或“what's left?”开始下一个会话。上一个分支交接已经作为上下文注入——你无需重新总结。dsh-handoff 的运行时上下文快照是变更门控的，因此稳定的交接每一步都不产生开销，而变更后的交接会恰好一次取代先前的快照。

开始一个新任务

/handoff clear # archive the current branch handoff and start a fresh skeleton

项目知识和固定规则不会被清除——它们能在清除和分支切换后保留，因为它们存放在 project.md 中。

暂停记录

/handoff pause # stop recording this session; the gap is never written
/handoff resume # start recording again

暂停期间，不会收集任何内容，也不会运行刷新，因此暂停的这段时间不会留下任何痕迹供日后过滤。在暂停之前缓冲的工作会被保留，并在 resume 之后合并进来。注入在暂停期间仍然有效，因此 agent 仍会读取现有文档。固定项、project add 和显式的 /handoff flush 仍然有效——暂停抑制的是自动记录，而不是有意执行的命令。暂停仅对当前会话有效；开始新会话时总会恢复记录。

子代理

只有顶层代理会采用存储、收集和注入。子代理（委托深度 > 0）是隔离的短生命周期工作器：它们既不写入共享的 events.jsonl（这只会与父代理在其锁上产生争用），也不接收交接注入。当从子代理调用时，handoff 工具会报告“not initialized for this session”。

命令和工具

用户命令（/handoff …）

| 命令 | 用途 |
| /handoff [status] | 显示存储、分支、队列、用量、固定项和项目建议 |
| /handoff flush | 立即刷新当前分支交接 |
| /handoff clear | 开始一个新的任务交接；项目知识和固定项保留 |
| /handoff project status | 显示共享知识和待处理建议 |
| /handoff project refresh [all] | 从活动分支中提取持久知识；all 包括已归档/已删除的存储 |
| /handoff project / project review | 应用排队的建议 |
| /handoff project add [Section:] | 直接添加共享知识 |
| /handoff project forget | 移除一条共享事实；匹配不明确时不移除任何内容 |
| /handoff pin | 添加一条受保护的项目级规则 |
| /handoff unpin | 移除一条固定规则；匹配不明确时不移除任何内容 |
| /handoff pause / resume | 停止并重新开始当前会话的记录；注入保持活跃 |

Agent 工具（handoff）

模型可以调用 handoff 工具并执行以下操作：

- status — 检查存储
- flush — 立即刷新分支交接
- project_propose — 将持久项目知识加入队列以供用户审阅（需要 note，可选 section）
- pin — 记录一条硬性常驻规则（适用于每个分支）
- unpin — 按子字符串移除一条固定规则

破坏性控制（clear、pause、resume）仍然仅限用户使用。暂停期间，该工具的 flush 会报告暂停状态，而不是执行写入。

write-handoff 技能

注册了一个 write-handoff 技能，以便模型（或你，通过技能命令）可以手动将当前对话压缩为一份交接文档。它会先读取自动维护的 handoff.md，只有在自动版本缺失或过期时才会写入手动版本。

共享项目知识

当多个分支已积累有用经验时，运行项目刷新：

/handoff project refresh
/handoff project # review/apply queued suggestions

refresh 仅在分支交接发生变化后调用模型。变更的分支会以有界批次进行扫描；每个成功的批次都会被检查点记录，因此后续失败绝不会将未处理的分支标记为已扫描。已删除/已归档的 git 分支存储默认会被跳过；使用 /handoff project refresh all 也会挖掘它们。

/handoff project review 会应用所有排队的建议（此配置文件没有来自插件命令的交互式确认界面；请先用 /handoff project status 检查它们，如果你想手动控制，可以用 /handoff project add / /handoff project forget 逐条应用/移除）。

你也可以直接管理知识：

/handoff project status
/handoff project add Prefer small atomic store mutations
/handoff project add Architecture: Events are the durable source of pending work
/handoff project forget atomic store

直接添加的内容默认归入 Conventions。可用部分包括：Project Overview、Architecture、Conventions、Workflows、Decisions and Rationale、Known Pitfalls。

面向 agent 的 handoff 工具可以通过 project_propose 将普通项目知识加入队列。

固定规则

固定规则是受保护的层级。将它们用于绝不应被自动改写或移除的硬性约束：

/handoff pin Deploys go through ops/deploy.sh, never make release
/handoff pin The staging database is read-only
/handoff unpin staging database

不要固定当前任务进度、分支特定状态、已在 AGENTS.md/README 中重复的文档或机密信息。固定规则是永久的，适用于每个分支，并且绝不会被摘要器改写。

存储布局所有文件都存放在项目之外（目录结构与 pi-handoff 相同）：

~/.agent/agent-handoff//
├── project.md 共享知识与固定规则 ├── project-candidates.json 建议与审核状态 ├── project-meta.json 各分支的项目扫描修订版本 └── / ├── handoff.md 当前分支交接文档 ├── events.jsonl 持久化事件与文档快照 └── meta.json 游标与会话元数据

项目键使用 git 仓库根目录，因此从不同子目录启动该工具链会访问同一个存储。在仓库之外，工作目录本身即为键。设置 HANDOFF_DIR（或配置项 dir）可使用其他存储根目录。

分支文档包含七个固定章节：Current Goal、Progress、Decisions、Constraints、Open Questions、Active Files、Next Steps。其长度上限约为 16,000 个字符，同时保留所有章节标题。共享项目知识的长度上限约为 16,000 个字符；受保护的固定规则使用单独的章节。

存储限制

| 文件/内容 | 限制 | 清理行为 |
| handoff.md | 24k 字符 / 96 KB | 超大的模型输出按章节压缩；超大的写入会被拒绝 |
| 项目知识 | 16k 字符 | 已有的超大章节会被压缩；达到限制时新事实会被拒绝 |
| 固定规则 | 200 条规则，每条 500 字符，总计 16k | 新固定规则会被拒绝；遗留的重复/溢出固定规则会被移除并留下标记 |
| project.md | 128 KB | 每次原子写入时强制执行 |
| events.jsonl | 1,000 行 / 4 MB | 裁剪至约 900 行 / 2 MB；待处理的溢出会留下对摘要器可见的标记 |
| project-candidates.json | 200 条待处理 + 500 条已审核，每字段 240 字符，1 MB | 最旧的超额候选会被自动移除 |
| project-meta.json | 2,000 个分支哈希 / 2 MB | 最旧的扫描哈希会被自动移除 |
| 分支 meta.json | 32 KB | 启动时会丢弃未知字段并对已知值进行规范化 |

配置

所有选项都可以从配置文件的 cordis.patch.yml（顶层 YAML 补丁条目数组；通过 id: handoff 定位此插件）或通过环境变量覆盖。环境变量（带有 PI_HANDOFF_ 别名以保持一致）会覆盖配置。默认值随此插件自带的 cordis.patch.yml 一起提供，因此你只需在配置文件中打补丁即可更改某些设置。

| 字段 | 默认值 | 环境变量 | 用途 |
| dir | ~/.agent/agent-handoff | HANDOFF_DIR / PI_HANDOFF_DIR | 存储根目录覆盖 |
| model | 当前会话模型 | HANDOFF_MODEL / PI_HANDOFF_MODEL | 摘要器模型，格式为 provider/model-id |
| thresholdChars | 24000 | HANDOFF_THRESHOLD_CHARS | 累积达到这么多新字符后自动刷新 |
| thresholdTurns | 20 | HANDOFF_THRESHOLD_TURNS | 每经过这么多轮次自动刷新（0 = 仅按字符数） |
| maxTokens | 16384 | HANDOFF_MAX_TOKENS | 单次摘要器调用的最大输出 token 数 |
| debug | false | HANDOFF_DEBUG / PI_HANDOFF_DEBUG | 将刷新/提取诊断信息记录到 stderr |

在 profile 中覆盖配置

编辑 $DSH_HOME/profiles//cordis.patch.yml（初始内容为 []）。带有 id: handoff 的补丁条目会将其 config 合并到 bundle 的默认值之上（每个字段以最后写入为准）：

$DSH_HOME/profiles//cordis.patch.yml
- id: handoff
config:
model: "glm/GLM 5.2" # 使用你配置的 glm provider 进行后台折叠 thresholdTurns: 15 dir: "~/.agent/agent-handoff" # 可选：覆盖存储根目录 debug: true

使用 dsh --profile --dump-config | grep -A10 'id: handoff' 确认合成后的值，然后重启该 profile。

选择摘要器模型

默认情况下，摘要器复用会话当前活跃的模型（从会话的请求头中读取，回退到 agent 的 provider/model 选项）。要为后台折叠固定一个更便宜/更快的模型，请在补丁层（见上文）中设置 model，或设置 HANDOFF_MODEL。

该值的格式为 provider/model-id，与 dsh 路由时完全一致（例如 glm/GLM 5.2、deepseek/deepseek-chat）。未配置凭据的模型会被跳过，转而使用会话当前活跃的模型。

与 pi-handoff 的对应关系

如果你来自 pi-handoff，以下是各部分的对应转换方式。存储格式未变，因此无需迁移——两个 agent 读写相同的文件。

| pi-handoff | dsh-handoff |
| session_start 事件 | agent/session-start（仅顶层 agent） |
| before_agent_start 分支重新检测 | session/event turn/start |
| message_end / tool_execution_ / turn_end 收集 | session/event（user/message、assistant/message、tool/call、tool/result、turn/end） |
| agent_settled 排空 | agent/status → idle（以及 turn/end） |
| session_before_compact / session_compact | session/event compaction/（使快照失效） |
| session_shutdown | agent/disposed |
| context 事件注入 | ctx.systemPrompt.context()（变更门控的运行时上下文快照） |
| complete() 摘要器调用 | 通过解析后的 provider/model 路由调用 ctx.llm.stream() |
| /pi-handoff 命令 | /handoff 命令 |
| handoff 工具 | handoff 工具（相同操作） |
| /skill:write-handoff | 通过 ctx.skills.register() 注册 |

有意为之的差异

- 子 agent（委派深度 > 0）不会采用存储或接受注入——它们只会争用父级的 events.jsonl 锁。
- 无目标变更确认提示（pi 的 before_agent_start UI 提示）：dsh 没有轻量级的插件侧确认界面。请手动使用 /handoff clear。
- 环境变量别名：HANDOFF_ 带有 PI_HANDOFF_ 回退以保持对等。

开发最终用户永远不需要构建——lib/index.js 已提交，因此 dsh plugin add 可以直接从仓库使用。构建仅适用于修改 src/ 的贡献者。

cd /home/zteng/work/Tools/dsh-handoff
npm install # devDependencies for the build toolchain
npm run build # bun build → lib/index.js (externals @deepseek-ai/)
npm run typecheck # tsc --noEmit (needs the @deepseek-ai/* type packages resolvable)

对于本地类型检查，请使 @deepseek-ai/ 类型包可解析（例如从已安装的 dsh 中符号链接它们，或临时 npm install 它们而不保存）：

mkdir -p node_modules/@deepseek-ai
for p in cordis dsh-agent dsh-commands dsh-llm dsh-session dsh-skill dsh-system-prompt dsh-tools schemastery; do
ln -s /node_modules/@deepseek-ai/$p node_modules/@deepseek-ai/$p
done
npm run typecheck

主要文件：

| 文件 | 作用 |
| src/index.ts | Cordis 插件：生命周期、刷新队列、命令、工具、技能、注入 |
| src/store.ts | 路径、迁移、项目知识、事件、原子持久化（共享格式） |
| src/collector.ts | 从 dsh 会话事件中进行确定性的脱敏轮次收集 |
| src/summarizer.ts | 分支刷新和项目知识提取 |
| src/injector.ts | 分支和项目上下文注入（运行时上下文快照） |
| src/redact.ts | 机密拒绝列表 |
| lib/index.js | 预构建包（已提交；外部依赖 @deepseek-ai/） |
| package.json | 声明 dsh.bundle.patch → 使 dsh plugin add 自动激活此包 |
| cordis.patch.yml | 自插入插件的包补丁（id: handoff），带默认配置 |