概览

shared-handoff-dsh

Shared handoff kit for DeepSeek Harness: evidence-driven handoff and repo-local task-id state skills, cross-platform (macOS/Linux/Windows).

README / ZH

插件文档

shared-handoff-dsh

English | 中文

把 shared-handoff-kit 的 handoff 工作流带入 DeepSeek Harness（dsh）的技能插件：打包 handoff 与 task-id-bootstrap 两个技能，零依赖、零构建，适配 macOS、Linux 与 Windows（区分 Win10 / Win11 的 Python 环境差异）。

技能

技能	说明	需要什么
`handoff`	证据驱动的会话交接：导出/恢复，跨 Codex、Claude、dsh 通用	无（纯指令）
`task-id-bootstrap`	仓库本地任务状态 `.agents/state/tasks/<task-id>/`，并把当前 dsh 会话（`DSH_SESSION_JSONL`）绑定到任务	Python 3.9+

安装

dsh plugin --profile web add shared-handoff-dsh

重启 dsh web 后，两个技能进入技能目录，模型经 skill 工具加载。

使用

装好后不需要任何命令——技能由对话触发，模型自动加载对应 SKILL.md。

task-id-bootstrap：开一个任务

在 dsh 对话里直接说（中英文标点都行）：

新开task-id=init-kmp，然后开个 init-kmp 分支

模型会运行打包的 bootstrap 脚本，你要的产出是三行证明：

Task state: .../.agents/state/tasks/init-kmp
Current task: init-kmp
Session binding: /Users/you/.dsh/sessions/.../session.jsonl.zstd

之后这个任务的进展记录在 .agents/state/tasks/init-kmp/process.md，下次说 继续，task-id=init-kmp 即可恢复。注意：只有目录没有绑定 = 部分成功，模型应如实报告。

首次使用时若机器缺 Python（3.9+），模型会先报告缺失并给出你平台对应的安装命令，征得你同意后才会代装，不会静默安装。

handoff：交接 / 续接会话

对话变长、想换新会话继续时，说：

帮我做个 handoff

得到一份可直接粘贴进新会话的交接提示词（工作区/分支/已完成/验证状态/ 下一步）。反过来，新会话开头说：

继续上次 handoff

模型会从状态文件（而非聊天记录）重建上下文。交接、新开线程继续、 继续上次、resume 等说法同样触发。

两个技能配合

同一仓库里 task-id 激活后，handoff 导出/恢复会自动认 .agents/state/tasks/<task-id>/process.md 为准，不会另起一套状态。

跨 agent 交接

状态布局与 Codex / Claude 版完全一致：在 dsh 里导出的交接，可以贴到 Codex 或 Claude 里恢复，反之亦然（session-tasks.json 三方共用）。

自动化（原 hook 的等价实现）

原 kit 在 Codex/Claude 里靠 hooks 实现的三件事，本插件用 dsh 事件系统在 host 侧自动完成，装好即生效，无需任何配置：

原 hook	dsh 等价	行为
`SessionStart`	首个 `agent/pre-step`（step 1）	自动把当前任务的 `process.md` / `process.auto.md` 作为基线用户消息注入会话——开新会话说一句"继续"即可，状态自动就位；基线末尾附带提醒：阶段性工作完成后主动运行 `handoff` 技能更新语义状态
`UserPromptSubmit`（task 路由）	`agent/pre-step` 消息扫描	用户消息中的 `task=<id>` 标记自动重绑会话并切换 `current-task`（新任务自动建目录），随后注入切换通知
续接	`agent/pre-step` 消息扫描	短续接指令（继续 / 接着 / resume / 交接…）在会话中途重新注入持久化状态，注入带"重新注入"标记
`Stop`	`session/event` 的 `turn/end`	每轮结束自动刷新 `process.auto.md`（截取该轮最后的模型输出），并镜像到已存在的 `process.recent.md`；同一时机还会向 `process.md` 末尾的 `## Auto Log` 段追加一行本轮摘要（新的在最后，上限 `maxLogEntries` 条，手写段落不受影响）
`PreCompact` / `PostCompact`	`compaction/start` / `compaction/summary`	压缩前后自动写快照 + 更新 `context_guard.json` 守卫；每完成一次压缩 `auto_compact_count` +1，达到 `compactThreshold`（默认 3）后 `clear_required` 置位，下一次基线注入附带 controlled clear 提示（先 handoff 保存进度，再开新会话）

任务归属的解析也与原版一致：先按当前会话 transcript 在 session-tasks.json 里查绑定（dsh 会话按 $DSH_HOME/sessions 下的 transcript 路径对齐），查不到再回退 current-task 指针。所有写入都落在与 Codex/Claude 同一份 .agents/state/ 里，三方互通。

与 Codex / pi 版互通：context_guard.json 采用读-合并-写，字段契约与 Codex 原版对齐（auto_compact_count、clear_required、threshold、 last_*），其他 runtime 的专有键（pi_compact_count、 last_pi_session_id 等）原样透传。清除阈值判定把 pi 与 dsh 的计数加总 ——同一个仓库在多个 runtime 之间交替使用，守护依然正确。

不想用某项自动化时，在 profile 的 patch 里关掉：

- id: shared-handoff
  name: 'shared-handoff-dsh'
  config:
    injectBaseline: false   # 关掉会话开始注入
    autoSnapshot: false     # 关掉每轮自动快照
    autoLog: false          # 关掉 process.md 的每轮 Auto Log 追加
    compactionGuard: false  # 关掉压缩守卫
    handoffReminder: false  # 关掉基线里的主动 handoff 提醒
    maxLogChars: 300        # Auto Log 单条截断长度
    maxLogEntries: 100      # Auto Log 段条数上限
    compactThreshold: 3     # 压缩多少次后建议 controlled clear

process.auto.md 与 context_guard.json 是 host 托管文件，模型不会手写它们（SKILL.md 已注明）；process.md 仍由模型按技能指引维护——例外是文件末尾由 host 追加的 ## Auto Log 段。

设计要点

archify-dsh 模式：cordis.patch.yml 挂载一个隔离的 @deepseek-ai/dsh-skill-filesystem 实例（includeDefaultRoots: false + 唯一 providerName + bundledSkillDir 指向包内 skills/），不影响原生 filesystem 提供方。
host 半（hook 等价）：插件本体零外部依赖（仅 Node 内置模块），监听 agent/pre-step 与 session/event 实现注入/快照/守卫，见上文「自动化」；监听器自吞错误，快照失败绝不会打断 agent 循环。
子代理只读（单写者规则）：委派子代理与 fork 分身（origin: "subagent" / delegationDepth > 0）只接收基线注入，绝不写状态——不写快照、不进 Auto Log、不写绑定、不更新压缩守卫、也不响应 task=<id> 路由（委派 prompt 里提到的任务标记不会劫持仓库的当前任务）。否则并行子代理会互相覆盖快照、交错污染 Auto Log；父会话是唯一写者，子代理的发现通过最终报告回流并由父会话记录。
会话绑定：dsh 在受管 bash/PowerShell 环境注入 DSH_SESSION_JSONL （当前会话 transcript 路径），bootstrap 脚本以 --transcript-path 绑定，脚本本体零改动，与 Codex/Claude 版写入同一份 session-tasks.json。
跨平台：SKILL.md 内置 bash 与 PowerShell 双命令、Win10/Win11 Python 检测差异表（py 启动器、Store 别名 stub、winget 可用性）；锁模块在 POSIX 用 fcntl、Windows 用 msvcrt，与原版语义一致。
缺 Python 时：不静默安装——报告缺失、给出平台对应命令、征得同意后才代装；handoff 技能与 host 半自动化不受影响（它们不依赖 Python）。

已知限制

只迁移了两个平台无关技能；claude-handoff（Claude Code 专属）与 Codex/Claude 的 hook 运行时不属于本插件，仍由原 kit 安装。
host 半的自动快照只记录该轮最后的模型输出（事实性内容），不做摘要改写——语义性进展仍由模型维护在 process.md 里；## Auto Log 段提供逐轮带时间戳的轨迹，但不替代那份人工整理。
本地路径安装（dsh plugin add <路径>）为 link 形态，发 npm 后与他人共享更稳妥。

License

MIT（沿用 shared-handoff-kit）。

LIMITATIONS

已知限制

- 只迁移了两个平台无关技能；`claude-handoff`（Claude Code 专属）与 Codex/Claude 的 hook 运行时不属于本插件，仍由原 kit 安装。 - host 半的自动快照只记录该轮最后的模型输出（事实性内容），不做摘要改写——语义性进展仍由模型维护在 `process.md` 里；`## Auto Log` 段提供逐轮带时间戳的轨迹，但不替代那份人工整理。 - 本地路径安装（`dsh plugin add <路径>`）为 link 形态，发 npm 后与他人共享更稳妥。

shared-handoff-dsh