会话管家 wangxing-git/dsh-tool-session

dsh-tool-session

DeepSeek Harness 会话管理工具插件：为模型（智能体）提供会话创建 / 重命名 / 归档 / 切换 / 列表 / 查询 / 当前会话信息工具，支持沙箱提权审批、UI 层面的会话切换、会话工具在对话流中的专属视图（各自图标 + 中文标题 + 摘要，替换默认的 generic 卡片），并为人提供 /clear、/new 两个斜杠命令（在输入框直接创建新会话并切换，不经模型）。

功能

| 工具 | 作用 |
| create_session | 创建新会话（可指定 cwd/workspace_id/title/agent_preset/switch/initial_message；workspace_id 会将新会话归属到该工作区，switch:true 创建后切换 UI，initial_message 可带首轮消息发起对话） |
| rename_session | 重命名会话（显式标题，钉住自动标题生成） |
| archive_session | 归档会话（隐藏但保留持久化日志，可恢复——本插件不提供真删除） |
| switch_session | 切换当前会话（UI 跟随打开目标会话） |
| list_sessions | 列出会话（id/title/cwd/running/archived/workspace 归属；可选 workspace_id 只返回指定工作区的会话，可选 include_archived 含归档，可选 query 按关键字对标题 / 会话 id / 工作目录 / 工作区标题做大小写不敏感的子串模糊搜索） |
| get_session | 按 id 查看单个会话详情（含 running/archived/workspace 归属） |
| get_current_session | 获取当前会话信息（id/cwd/title/workspace 归属） |

7 个工具的结果统一以格式化 JSON 文本返回（缩进 2 空格），模型直接读取结构化结果，而非人类可读的文本摘要。

斜杠命令（人类直接触发，不经 LLM）

| 命令 | 作用 |
| /clear | 在会话输入框直接创建新会话并切换过去（清空上下文），不经过模型——命令在 UI 命令平面执行，斜杠输入与结果文本都不进入会话历史 |
| /new | 与 /clear 同义：创建新会话并切换过去，不经过模型 |

两个命令都只接受无参数形式；带参数会返回 Usage: /clear (no arguments)。新会话继承当前会话的工作目录（cwd）与 agent preset，创建后归属 cwd 本身或 cwd 祖先目录对应的工作区并切换 UI。命令依赖 commands 服务（@deepseek-ai/dsh-commands，随 dsh base 提供）；UI-less 部署不提供该服务时命令静默不注册，7 个会话工具照常可用。

权限

- 沙箱后端挂载时，7 个工具统一声明 sandbox_permissions + justification 提权参数（与 bash/fs 同款词汇）。
- 提权经 approveEscalation 走 fail-closed 用户审批：非严格更宽、无审批服务、无 agent、拒绝/取消均不执行任何会话变更。
- archive_session 归档属破坏性操作，除沙箱提权外另经 approval.request 独立用户审批：无审批服务、无 agent、被拒/取消均不归档（fail-closed）。
- 会话操作本身经 host 服务（ctx.agents / ctx.sessionTitle / ctx.workspaceRegistry / ctx.agentDefaultModel）完成，不直接碰会话持久化文件。
- create_session 通过 agentOptions 声明默认模型的 seed 路由（provider/model/reasoningEffort）；model selection 的后续切换由 host-apiproxy 的 session.selectModel / session.models 端点惰性安装的动态 ref 接管，故会话中途切换模型可即时生效。推理强度必须在 agentOptions 里给出：agent-loop 的 step preparation 会固定请求配置，之后再在 agent/request 里补 reasoningEffort 会抛 "after step preparation fixed" 错误，首轮消息直接失败。缺省模型服务时 fail-closed 拒绝创建。
- create_session 创建后调用 workspace.attachSession() 将新会话归属到工作区，并对 cwd 做 fail-closed 校验：cwd 经 realpath 归一后必须精确等于一个已注册工作区路径（DSH 的 attachSession 只接受 cwd === 工作区 path，子目录一律拒绝）；显式 workspace_id 时还要求 cwd 与该工作区路径一致。不满足时直接报错、不创建会话，错误信息给出最接近的工作区路径，提示调用方改用已注册路径或先 create_workspace 注册该目录。

自动归档扫描（可选，默认关闭）

插件内置一个后台「自动归档扫描」：任何会话创建（UI 手动新建、create_session 工具、/clear、/new、fork 等）都会触发一次扫描，按规则静默归档历史会话。归档与手动 archive_session 同语义——隐藏但保留持久化日志、可恢复，但不弹审批（由配置显式开启的自动行为）。

规则（每组独立；组 = 每个工作区 + 未分组）：

- 组内未归档会话数 ≤ 上限时不归档任何会话（即使有超过阈值天数的会话）。
- 组内未归档会话数 > 上限时，归档到恰好 ≤ 上限；优先归档过期会话（最后活跃时间超过阈值天数），过期不足则继续归档最旧的未过期会话。
- 「过期」按最后活跃时间判定：max(创建时间, 最后一条人类消息时间)，与侧边栏会话排序语义一致。
- 只归档非运行中（cold）的历史会话；正在运行的会话与新建会话永不归档。

配置优先级：settings.yaml > cordis.patch.yml（composition base）> schema 默认。
方式一：settings.yaml（推荐） —— 编辑 ~/.dsh/settings.yaml，追加 tool-session 段后重启 dsh 生效（手改文件不会热加载；UI 设置面板的改动则即时生效）：

tool-session:
autoArchive:
enabled: true # 总开关，默认 false（关闭） maxAgeDays: 30 # 过期阈值天数，默认 30 maxSessionsPerWorkspace: 30 # 每组最多保留的未归档会话数，默认 30

方式二：cordis.patch.yml（composition base，需重启） —— 编辑 ~/.dsh/profiles/web/cordis.patch.yml：

- id: tool-session
config:
autoArchive:
enabled: true
maxAgeDays: 30
maxSessionsPerWorkspace: 30

| 字段 | 默认 | 说明 |
| autoArchive.enabled | false | 总开关 |
| autoArchive.maxAgeDays | 30 | 过期阈值（天） |
| autoArchive.maxSessionsPerWorkspace | 30 | 每组最多保留的未归档会话数 |

架构

- host 端（src/index.ts 等）：cordis 插件，注册 7 个工具 + 切换意图 SSE 事件端点（src/switch.ts，经 connection.fetch 注册 /api/tool-session/switch-events 精确路由，以 text/event-stream 推送）+ /clear、/new 两个斜杠命令（src/commands.ts，经 ctx.commands 注册，复用 src/create-session.ts 的创建核心）。切换意图按「投递水位」投递（SwitchIntent）：request 实时广播给活跃连接，任一连接写入成功即标记已送达（携带自增 revision）；新连接建立时只补投从未送达的意图（客户端断线期间产生的不丢），已送达的陈旧意图不重放——否则网络抖动重连、页面刷新、新开标签都会把用户硬拽回上一次 /clear 或 switch_session 的会话。
- client 端（src/client.ts）：订阅 SSE 事件流完成 UI 切换（连接存活期间零轮询，断线按 500ms 起指数退避重连，connection generation 变化时立即重订），并把 7 个会话工具的专属折叠行注册进 tool.call.toolview keyed slot（替换未注册时的 generic 卡片）。切换意图交给 src/client/switch-consumer.ts 落地：导航入口 ctx.uiWorkspace.openSession()（DSH 0.1.6 起会话选中与展示是 view owner 的职责，ctx.sessions 只承载目录与引用计数）对未知 id 直接抛错（fail loud），而意图经 SSE 到达时常早于会话列表的 RPC 事件帧（命令路径 /clear、/new 尤为明显），故由它在该窗口内重试（列表变化即时触发 + 定时兜底，默认 4s 窗口 / 120ms 间隔），只有窗口耗尽才 console.warn 告警——不静默丢弃。意图帧先经 src/client/switch-frame-gate.ts 按 revision 去重（重复/陈旧帧丢弃，缺失序号的旧版帧兼容放行），重连瞬间的重复投递不会造成无谓回跳。
- client 组件（src/client/presentations.ts + src/client/session-tool-row.tsx）：呈现注册表（每工具标题/图标/摘要提取）+ 折叠行组件（图标 + 标题 + 摘要，可展开参数/结果，状态用 StateDot 表达）。

安装到配置档

方式一：命令行安装（推荐）

执行：

dsh plugin --profile web add github:wangxing-git/dsh-tool-session

dsh plugin add 会在 ~/.dsh/profiles/web 内调用 pnpm 安装依赖，并在成功后自动把声明了 dsh.bundle 的插件追加进 dsh.profile.bundles，无需手动编辑。然后重启 dsh --profile web。

方式二：手动编辑 package.json

在 ~/.dsh/profiles/web/package.json 中：

{
"dsh": { "profile": { "bundles": ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-web-app", "dsh-tool-session"] } },
"dependencies": { "dsh-tool-session": "github:wangxing-git/dsh-tool-session" }
}

然后在配置档目录执行 pnpm install，重启 dsh --profile web。

本地开发调试时，可用 dsh plugin --profile web add link:/绝对路径/dsh-tool-session，或手写 "dsh-tool-session": "link:/绝对路径/dsh-tool-session" 后执行 pnpm install（link: 建议用绝对路径，相对路径会相对配置档目录解析）。

构建与测试

npm install # 安装依赖
npm run build # tsc(host) + tsc(client) + esbuild(client bundle)
npm test # vitest 单元测试

验证

1. 重启 dsh --profile web 后，模型工具目录中出现 create_session / rename_session / archive_session / switch_session / list_sessions / get_session / get_current_session。
2. 沙箱环境下调用任一工具带 sandbox_permissions 会触发审批弹窗。
3. switch_session（或 create_session + switch:true）执行后，UI 侧边栏当前会话切换为目标会话。
4. archive_session 归档后 ~/.dsh/sessions 下文件仍在（archivedSessionIds 更新）。
5. create_session 带 initial_message 参数创建后，新会话立即以该消息作为首轮用户消息开始对话（followup 注入并唤醒 driver）。
6. create_session 仅在 cwd（realpath 归一后）等于已注册工作区路径时创建并归属；cwd 为工作区子目录或未注册目录时直接报错、不产生会话，错误信息给出最接近的工作区路径。显式 workspace_id 时 cwd 必须与该项路径一致。
7. get_current_session 返回当前会话的 id/cwd/title/workspace 归属。
8. get_session 按 session_id 返回单个会话详情（含 running/archived/workspace 归属）。
9. 会话工具调用在对话流中显示专属视图：各自图标 + 中文标题 + 摘要，可点击展开参数/结果（不再统一显示 generic "Tool call"）。
10. 在会话输入框输入 / 后，命令菜单出现 /clear 与 /new；输入 /clear（或 /new）回车后，不经模型直接创建新会话并切换过去（旧会话保留、含一条 command 生命周期记录）。
11. 新会话继承当前会话的工作目录与 agent preset，归属相同工作区，UI 侧边栏出现并切换到新会话；当前会话 cwd 不是已注册工作区时命令返回错误文本、不创建会话。
12. list_sessions 传 query 关键字后仅返回标题 / 会话 id / 工作目录 / 工作区标题命中该关键字的会话（大小写不敏感，query 与 workspace_id / include_archived 可叠加过滤）。
13. 目标会话尚未进入客户端列表时切换不会丢：/clear（或 switch_session）后 UI 仍会切过去（client 端在 4s 窗口内等会话进列表后重试落地）；若会话始终未出现，浏览器 Console 出现 tool-session: switch intent dropped, session never listed: ... 告警，而不是静默无反应。
14. 网络抖动导致 SSE 断开重连（以及页面刷新、新开标签）后，UI 停留在用户当前所在的会话，不会被拽回上一次 /clear 或 switch_session 的会话；而客户端断线期间产生的切换意图仍会在重连后补投落地。
15. create_session 带 initial_message 且默认模型配置了 reasoningEffort 时，首轮不再因 "agent/request proposed reasoning effort ... after step preparation fixed ..." 失败：推理强度随 agentOptions 一并种入，会话首轮正常开始。