DeepSeek Harness 插件：dsh-agent-control

前言¶

DeepSeek Harness（DSH）采用插件化架构。在开发与调试过程中，删除会话、删除一轮对话，以及重启或关闭实例，是三件典型的“破坏性操作”。这些操作通常分散在不同的模块中，且缺乏统一的确认与失败语义管理，容易在操作时产生误判。

ventisyn/dsh-agent-control 插件将这三类操作整合在一起，提供了一套统一的确认机制和错误处理逻辑。它不依赖内核私有结构，仅使用公开 API，旨在为开发者提供更可控的会话管理与进程控制能力。

核心功能¶

该插件主要包含以下能力：

删除会话：将一个会话不留残留地移除。它会递归清理该会话派生的所有子代理会话（包括目录、工作区记账、投影缓存）。如果子代理中仍有会话驻留在内存中，删除操作会被拒绝。插件不会触碰其他插件的数据（如审批类插件的事件记录）或内容寻址共享的附件。
删除一轮对话：从模型的可见上下文中移除一轮已结束的对话（问题、回复及工具记录）。这一过程类似 DSH 的手动压缩，通过追加一笔独立的事务来替换可见内容，让模型无法再看到原内容。被删除的轮次在日志与附件中仍保留，不属于安全删除。
热重启：允许模型或用户重启 DSH 进程。重启会在当前任务结束后执行，重启后的会话会自动继续。这主要用于宿主插件代码修改后的生效。
关闭实例：干净地停掉整个 DSH 实例，与直接关闭窗口等价。这通常由用户在设置页触发。
组件开关：插件列表中包含四行配置（core + session/turn/restart），每一行都可以单独关闭。关闭后，对应的路由消失，界面入口也随之消失。
状态探针：提供 GET /api/agent-control/sessions 等只读接口，用于查询会话状态或确认组件是否注册成功。

安装与启用¶

使用 dsh 命令行工具安装，指定 profile 名称：

# 安装最新版本
dsh plugin --profile <profile 名> add github:ventisyn/dsh-agent-control

# 锁定到特定版本
dsh plugin --profile <profile 名> add github:ventisyn/dsh-agent-control#<完整版本号>

# 本地开发模式
dsh plugin --profile <profile 名> add link:<本地 clone 路径>

注意事项：
* 如果 profile 中已安装其他删除类插件，请先移除，否则界面会出现重复的删除按钮。
* 安装或修改 host 端代码后，需要重启 dsh web 才能加载新路由。

典型用法¶

界面操作¶

删除会话：在会话列表的“…”菜单中选择“删除会话”，或在设置页操作。
删除一轮：在每条已结束的回复旁点击垃圾桶按钮。
重启/关闭：在设置页的“Agent 控制”区域，点击“重启 DSH”或“关闭实例”。操作前需勾选确认框。

API 接口¶

插件提供 HTTP 接口，但没有 harness 鉴权。建议仅绑定回环地址或进行 Origin 校验。

# 查询会话列表
curl http://127.0.0.1:<端口>/api/agent-control/sessions

# 热重启
POST http://127.0.0.1:<端口>/api/agent-control/restart
Content-Type: application/json

{"reason": "修改了宿主插件代码"}

# 关闭实例
POST http://127.0.0.1:<端口>/api/agent-control/shutdown

组件开关¶

在插件列表中，每一行右侧都有一个开关。
* dsh-agent-control（core）：负责交付与初始化。
* dsh-agent-control/session：负责会话管理。
* dsh-agent-control/turn：负责轮次管理。
* dsh-agent-control/restart：负责热重启与关闭实例。

关闭某一行后，重启实例即可生效。关闭“热重启”行会同时移除重启和关闭按钮。

注意事项¶

删除一轮不是安全删除：被删除的轮次内容仍保留在会话日志与附件存储中，仅对模型不可见。
附件清理限制：删除一轮不会清理附件，因为内核没有公开的清理接口。
HTTP 接口鉴权：接口没有 harness 鉴权，仅依赖 Origin/自定义头校验。请勿将 webServer 绑定在 0.0.0.0 上，以免暴露重启或关闭接口。
启动器孤儿进程：如果实例是由桌面启动器（DSHL）拉起的，重启后进程会变成孤儿。启动器无法识别新进程，需手动结束旧进程后重新启动。
重启与关闭：
- 重启期间页面会短暂不可用。
- 关闭实例会中断所有会话与后台任务，且不会自动重启。
- 已压缩的轮次可能无法单独删除。

总结¶

dsh-agent-control 通过将破坏性操作统一管理，简化了 DSH 插件的开发与调试流程。它提供了灵活的组件开关，并在界面和 API 层面提供了统一的确认机制。开发者在使用时，需特别注意其非安全删除的特性以及与启动器的兼容性问题。