会话交接导出 ZhijiangTang/dsh-handoff

dsh-handoff

DSH 插件：会话交接一键导出。把当前会话的目标、已完成/未完成、关键文件与统计，导出为一份确定性的 Markdown 交接文档。纯 ESM、零依赖、无构建。

简介

handoff 工具从 exec.agent.session 的会话事件流中收集事实，不调用任何 LLM，直接生成确定性的 HANDOFF.md（或你指定的路径），适合在会话结束 / 切换上下文 / 交给接手者时，快速产出一份可读的交接材料。

- 确定性导出，不调模型，零成本：所有内容来自会话事件流（用户消息、工具调用、工具结果、todo、goal/change、token 统计），不做模型推断、不读时钟、不用随机数，同样输入必然得到同样输出。
- 与记忆插件的区别：这是一次性交接文档，而不是持久记忆库——它把「此刻」的会话状态冻结成一份文件，供人（或下一会话）阅读；记忆插件则是持续累积、随会话演进的状态。

安装

dsh plugin --profile add file:./plugins/dsh-handoff
或发布到 npm 后：
dsh plugin --profile add dsh-handoff

参数

| 参数 | 类型 | 必填 | 默认 | 说明 |
| dest | string | 否 | HANDOFF.md | 导出文件路径（相对工作区根） |
| overwrite | boolean | 否 | false | dest 已存在时是否覆盖；false 且已存在则返回规范错误值 |

输出（规范值）

- 成功：{ ok: true, path, sections, eventCount, chars, skipped, note }
- sections：生成的章节标题列表（会话交接 / 目标 / 已完成 / 未完成 / 下一步建议 / 关键文件 / 会话统计）
- eventCount：遍历的会话事件数；chars：写入字符数
- skipped：事件流不可用 / 无法适配时为 true，note 说明降级原因
- 失败：{ ok: false, error }，error 为字符串（越界 / 已存在 / 写入失败）。所有失败都走规范值，不抛异常。

生成内容

- # 会话交接：会话 id + 首末事件时间范围
- ## 目标：最近 3 条直接用户消息（各截 200 字）+ 最新 goal/change 目标状态
- ## 已完成：文件写入/编辑清单、git 提交、成功工具结果计数
- ## 未完成：isError 的工具、todo 中 pending/in_progress 项
- ## 下一步建议：留空模板
- ## 关键文件：出现过的路径去重前 15
- ## 会话统计：事件/消息/工具/token/goal 计数

降级行为

事件结构存在不确定性，handoff 先做 typeof 探测（session.events 是否为数组、事件是否带 type 字段）：

- 探测失败（如自检 / 无会话环境下 exec.agent 为空，或 events 非数组、事件缺 type）→ 返回 ok: true 且 skipped: true，只写出模板骨架 + 降级说明，绝不抛错。
- 探测通过但个别事件结构异常 → 跳过该条事件，其余照常收集。

安全

- 路径围栏：resolve(dest) 必须位于工作区根（exec.agent.session.header.cwd ?? process.cwd()）之内，否则返回 { ok: false, error: 'dest 越出工作区' }。
- 挂载时自检：走真实执行管道调用 handoff（唯一临时名）→ 断言 ok: true、文件存在、含 # 会话交接 标题 → 打印证据 → 删除临时文件。

License

MIT