dsh-task-control

一句话定位

为 DSH Web 增加对话任务的暂停、恢复和取消三种控制能力。当 AI 正在执行一个长任务时，你可以中途暂停它（保留全部执行进度），稍后从暂停点继续，也可以立即取消当前回合。

核心能力

• 暂停任务：支持安全暂停（等待推理/工具自然完成后落地）和强制暂停（立即中断在途工具与模型输出）
• 恢复任务：从暂停点继续，不会重复执行已经完成的工作
• 取消任务：立即终止当前回合，并提示被打断的工具预期目的与潜在副作用
• 暂停粒度设置：在 Web 设置页可配置默认暂停模式与安全暂停下推理粒度（wait/stop），保存后立即生效
• 状态持久化：每个会话的暂停状态写入本地文件，重启 dsh web 也不会丢失
• 供其他插件调用：通过 taskControl 服务按会话 ID 提供程序化接口
• 三种入口：输入框旁的常驻按钮、斜杠命令（/pause /resume /cancel）、其他插件通过服务调用

技术实现

• 语言: TypeScript / JavaScript（编译产物）
• 关键依赖: @deepseek-ai/cordis、@deepseek-ai/dsh-llm、@deepseek-ai/dsh-client-ui-primitives、react
• 架构模式: Host/Client 双面插件。Host 端通过 cordis bundle.patch 注册斜杠命令、session 事件监听、taskControl 服务和两个 HTTP 路由；Client 端通过 package.json#dsh.client.inject 注入宿主提供的 runtime/locale/ui-settings/conversation 服务，在 composer 工具栏渲染按钮、在设置页渲染粒度配置面板
• 入口文件: lib/index.js（host）+ lib/client.js（browser）+ cordis.patch.yml

适用场景

适合需要在 DSH Web 中管理长时任务的场景：当 AI 正在跑一次大迁移、批量测试或多步工具调用时，你可能想暂停一下切换上下文，或者立刻取消一个方向跑偏的任务。安装后无需复杂配置，输入框旁就会出现三个常驻按钮，斜杠命令也可直接调用。

前置依赖与兼容性

安装方式

dsh plugin --profile web add github:p2coder/dsh-task-control

安装后请完整重启 dsh web 并刷新浏览器。

配置项

配置入口在 Web 设置页「设置 → 任务控制」，也可直接调用 /task-control/settings JSON 接口修改。

常见问题

Q: 安装后是否需要重启？

A: 需要。按 README 与 patch 描述，必须完整重启 dsh web 并刷新浏览器，cordis bundle patch 和客户端注入才会生效；只刷新页面会拿到旧的 UI。

Q: 暂停和官方自带的"停止"按钮有什么区别？

A: 官方"停止"按钮直接终止当前回合，状态丢失；本插件的"暂停"会保留全部执行进度并写入本地存档，恢复时从暂停点继续，不会重做已完成的工作。

Q: 强制暂停会破坏正在执行的工具吗？

A: 会。任何在途的工具都会被立刻中断，可能产生部分副作用。恢复时插件会弹出选择菜单，让你决定重新执行、跳过该工具还是继续保持暂停。

Q: 暂停状态保存在哪里？重启会丢吗？

A: 保存在用户目录下的 ~/.dsh/task-control/，每个会话一个 JSON 文件，采用 tmp+rename 原子写，重启 dsh web 不会丢失。测试时可用环境变量 DSH_TASK_CONTROL_STATE_DIR 改路径。

Q: 其他插件可以调用任务控制吗？

A: 可以。Host 端注册了 taskControl 服务，其他插件通过 ctx.get("taskControl") 拿到后，按会话 ID 调用 pause / resume / cancel / state 四个方法。

Q: 暂停期间定时提醒会触发吗？

A: 会。dsh-schedule 到期时仍会唤醒当前会话，暂停只控制当前回合，不会拦截定时事件。

Q: 子代理会被一起暂停吗？

A: 不会。已经派发的子代理独立运行，不会随父任务一起暂停。

Q: 修改插件代码后需要做什么？

A: 需要重新加载插件并重启 dsh web。客户端每 2 秒轮询一次状态，不重启的话浏览器拿到的仍是旧版本。

上手难度

入门 — 只需一条安装命令，无强制配置；输入框旁的按钮和斜杠命令开箱可用，进阶用户再调暂停粒度。

已知问题与限制

• 强制暂停会立即中断在途工具，工具的副作用状态未知，恢复时需用户手动选择重新执行或跳过（lib/index.js:303-310, 545-572）
• 暂停状态以独立 JSON 文件存于本地而非会话日志：源码明确说明 harness 的持久化读取器只接受已知事件类型，把 task-control/* 事件写入会话会导致会话重启后无法加载，因此采用外挂存储（lib/index.js:42-50）
• 暂停只控制当前回合，暂停期间发送新消息会开启新回合（README.md:81）
• safe wait 模式下暂停发生在推理完成后、工具派发前，会记录 deferredTools，恢复时需用户确认重新执行还是跳过（lib/index.js:484-526, 640-641）
• 已派发的子代理不会被父任务暂停，行为独立（README.md:83）
• 浏览器端每 2 秒轮询一次 /task-control/state，状态同步有最多 2 秒延迟（lib/client.js:195-198）
• 插件热卸载必须通过 ctx.effect 注销 /task-control 路由，否则 webserver 会抛"duplicate prefix route"（lib/index.js:828-834）

English | 中文

为 DSH Web 增加任务暂停、恢复和取消能力。支持安全暂停与强制暂停，恢复时从暂停点继续，不重复已完成的工作。

安装

dsh plugin --profile web add github:p2coder/dsh-task-control

安装后请完整重启 dsh web，然后刷新浏览器页面。

快速使用

任务运行时，输入框旁会显示三个常驻按钮：

灰色按钮表示当前不可用，黑色按钮表示可点击。

暂停模式

在「设置 → 任务控制」中修改默认模式，保存后立即生效：

命令

供其他插件调用

通过 ctx.get("taskControl") 获取服务：

暂停状态保存在 ~/.dsh/task-control/，重启后不会丢失。测试时可用 DSH_TASK_CONTROL_STATE_DIR 修改存储目录。

注意事项

测试

node test/host-smoke.mjs