DSH HUB
HomePlugin StorePlugin PacksCommunityRankingsResourcesPublish Guide
Plugin source
Back to catalog

ventisyn /

ventisyn/dsh-agent-control

Verified

DSH 整合插件,包含功能:删除会话,删除单独一轮对话,重启及关闭实例

★ 1 Stars0 Forks0 IssuesN/A Community rating0 Confirmed installs
View on GitHub
READMESource: 0.2.2-rc.1-v1.6.1@4f1bc4a9

dsh-agent-control

DeepSeek Harness(DSH)插件:把三件会改变实例现状的破坏性操作——删除会话、删除一轮对话、重启或关闭进程——收进一个插件,用同一套确认与失败语义管理;另附两项只读的浏览器端功能(任务完成提醒——铃声与可选的系统通知——与每轮花费,两个独立开关,见下方「任务完成提醒」与「每轮花费」)。

  • 删除会话:把一个会话不留残留地移除——磁盘目录(两种 id 拼写)、工作区记账(含归档/置顶)、投影缓存记录,以及它派生的子代理会话(递归,同样清目录与缓存)。fork 出来的会话是独立对话,不受影响。子代理里只要有一个还驻留在内存里,整次删除都会拒绝、什么都不动
    • 插件不碰的:别的插件自己存的数据(例如审批类插件的事件记录里可能提到这个会话 id)、按内容寻址共享的附件($DSH_HOME/attachments,可能被别的会话引用)
  • 删除一轮对话:从模型可见的上下文里移除一轮已结束的对话(问题、回复与该轮的工具记录),会话本身、之后的轮次与日志都保留
    • 做法与 DSH 自己的手动压缩同形:一笔独立压缩事务把那一轮的可见区间换成一句「这里原有一轮对话,已被用户删除」的提示,模型从此看不到原内容。只能在会话空闲时删(有一轮正在进行或正在压缩时会拒绝)。
    • ⚠️ v1.0.0 的旧写法(空的 system/message 墓碑)会让会话重启后打不开,已不再使用。
  • 热重启:把「DSH 进程重启」这件事也收进同一个插件——模型可以调用 restart_harness(必须说明原因)让需要重启才生效的改动(例如宿主插件代码)落地,重启后这个会话自动继续;用户也可以在设置页点按钮重启。见下方「热重启」一节。
  • 任务完成提醒(可选,只读):任务完成时响一声提示音,音效与音量可调,也可以限定为只提醒当前会话;还可选弹一条系统通知(同一行里的子开关,默认关,需要浏览器授权,权限只从设置页的用户手势申请)。在浏览器里跑,host 端只有一条只读探针。见下方「任务完成提醒」一节。
  • 每轮花费(可选,只读):在每轮回复下方显示这一轮大概花了多少钱。同样在浏览器里跑,host 端只有一条只读探针;金额是估算(token 用量 × 价目表),不是账单。见下方「每轮花费」一节。
  • 上述两项是两个独立的组件行(notify 与 cost),可以只开其中一个。

插件列表里六行、可以逐个开关(core + 会话 / 轮次 / 热重启 / 任务完成提醒 / 每轮花费五个组件):关掉哪一行,那一个组件 就真的下线——路由消失、界面入口随之消失。见下方「组件开关」。

本插件只使用 DSH 的公开 API:不依赖内核的私有结构,也不照抄任何第三方插件的实现。这一点是刻意的——依赖私有结构的写法换一个 harness 版本就会静默失效(详见 AGENTS.md 第 4 节)。

两者的区别(最要紧的一条)

删除会话 删除一轮
磁盘日志 永久删除 保留(日志是 append-only,不改写、不截断)
模型上下文 会话整个消失 那一轮不再进入上下文
附件 随会话目录一起删 不会清理(见下方「已知限制」)
可恢复 ❌ 不可恢复 ❌ 但内容仍在日志里

⚠️ 删除一轮不是安全删除。 它通过在日志末尾追加一笔压缩事务、把那一轮从模型可见面上替换掉来实现。被删内容仍然完整留在会话日志与附件存储里,只是不再进入模型上下文。任何「删了就没人能看到」的理解都是错的。

界面

  • 会话行「…」菜单 → 「删除会话…」(侧栏)
  • 每条已结束的回复旁 → 垃圾桶按钮(会话运行中时禁用)
  • 两者都会弹出同一个确认框,必须勾选确认才能点「删除」
  • 删掉的那一轮会在界面上被隐藏,让界面与模型看到的保持一致
  • 设置 → Agent 控制 → 运行状态、阻塞提示、「重启 DSH」按钮与「最近一次重启」卡片,外加一个「关闭实例」按钮(见下);同一页另有「任务完成提醒」一节(铃声开关、音效、音量、提醒范围,以及「系统通知」复选框、权限状态与「测试通知」按钮)与「每轮花费」一节(花费开关与自定义价目表),两节分别跟着 notify / cost 行出现

组件开关

本插件在插件列表里是六行(一行 core + 五个组件行),每一行都可以单独关掉。关掉之后那个组件 在本进程里根本不存在:路由消失、界面上的入口也跟着消失——不是「按钮还在、点了报错」。

行 负责什么
dsh-agent-control(core) 客户端 bundle 的交付、启动时清理孤儿归档标记,以及「按行构建各功能」的接线。它本身不含删除或重启能力
dsh-agent-control/session(会话) 会话列表、删除会话(含只剩记账的「幽灵会话」清理),以及客户端判断这个组件在不在的只读探针
dsh-agent-control/turn(轮次) 某个会话里已删轮次的列表、删除一轮,以及只读探针
dsh-agent-control/restart(热重启) 重启状态 / 重启 / 关闭实例三条路由、模型工具 restart_harness、重启后的「续作投递」
dsh-agent-control/notify(任务完成提醒) 只在浏览器里跑:任务完成铃声、可选的系统通知(Notification API,权限需用户手势授予)与设置页「任务完成提醒」一节。host 端只有一条只读探针,没有 POST 路由、没有模型工具
dsh-agent-control/cost(每轮花费) 只在浏览器里跑:每轮回复下方的花费徽章与设置页「每轮花费」一节。host 端只有一条只读探针,没有 POST 路由、没有模型工具

怎么关:插件列表里本插件那一组「包含的组件」右侧的开关。关掉是一次 profile 写入 (宿主把那一行标成 disabled),重启实例后生效——host 端的接线只在进程启动时装配。

开关分两级:第一行是总闸(插件本体)。关掉它,另外五个组件拿不到本体提供的服务, 会停在未运行状态,一个接口都不会注册——界面也会跟着消失(客户端界面也由本体交付)。 本体开着时,五个组件可以各自独立开关。

关掉之后的实际影响:

  • 路由真的不见了:被关掉的组件那几条路由(含只读探针)在进程里根本不存在,请求会落到 404 或宿主的鉴权 fallback。GET /api/agent-control/sessions 这类探针可以直接用来确认。
  • 界面入口跟着消失:客户端在挂载时先探测这几个组件(GET /api/agent-control/session/status、 .../turn/status、.../restart/status、.../notify/status、.../cost/status,都是只读、不带参数、不改变状态的接口),探不到就不注册 对应的槽位——会话行菜单里的删除项、回复旁的垃圾桶、已删轮次的隐藏标记、每轮花费徽章、重启/关闭横幅与确认框、设置页的「热重启」「任务完成提醒」「每轮花费」三节。 判据是「先探测、后注册」(已经注册的槽位无法在运行中卸载),探测失败或超时的方向是少显示 (模型侧本来也有 host 闸门,少显示只是界面滞后)。
  • 旧配置不受影响:如果某个组件行从来不存在(例如只有一行 agent-control 的老配置),core 会把 五个组件全装上,行为与从前完全一致。
  • 关掉不删数据、也不改变已知残留:插件自己不落任何数据文件(提醒与花费的设置存在浏览器 localStorage,两行共用一份,见下);会话删除在内存 store 里那条记录 (已知残留,见「已知限制」)仍然要等进程退出才消失——关掉组件既不会撤销已经发生的删除,也不会顺手清残留。
  • 关掉「热重启」= 重启与关闭都下线:restart_harness 工具、设置页那一节、界面上的重启按钮与 关闭实例按钮属于同一个组件,要留着它们就别关这一行。
  • 关掉一个组件不会让实例起不来(刻意的:配置写错一个词的代价不该是打不开)。

热重启与关闭实例

模型可以在需要的时候重启宿主进程(例如它刚改了本插件的 host 端代码,而 host 模块不会热加载),重启在本轮结束后执行,这个会话随后自动继续——模型会收到一条「DSH 已热重启」的通知,里面带着它自己写下的原因与续作说明。

  • 两个入口,同一套护栏:模型工具 restart_harness({ reason, resume_note? }) 与设置页的「重启 DSH」按钮走的是同一条路径(requestRestart)。
  • 模型发起时默认要过审批:审批卡片里显示模型给的原因;被拒就什么都不做。可以在插件行配置里把 approval 设成 auto 免审批(仍受限频与阻塞项约束)。
  • 有别的会话在跑、或有后台任务在跑时会拒绝,并告诉模型「等哪个会话结束」。这是刻意的:重启会中断那些任务。
    • ⚠️ 已知限制:宿主的作业列表按所有者隔离,插件看不到别的会话启动的后台任务,只能统计无主作业与调用者自己的作业。
  • 限频:10 分钟内最多 3 次;同一个会话在 60 秒内再次请求会被拒绝(防模型死循环)。
  • 停机时间约 6–10 秒,其中大部分是新进程启动的时间;重启期间页面会短暂不可用(不需要手动刷新,DSH 客户端会自己恢复)。
  • 不做配置回滚:如果新进程因为配置或插件错误起不来,插件不会替你改回任何东西——它会如实报告失败,并在设置页给出新进程日志的文件名,剩下的要你自己处理。
  • ⚠️ 如果你的实例是由桌面启动器(DSHL)拉起的:实测(v1.1.0)重启本身能成功,辅助进程也不会被杀,但启动器认不出重启后的新进程——它会从启动器的列表里消失,变成一个它管不到的孤儿进程(还活着、还在服务)。
    • 原因:启动器按它自己 spawn 的那个子进程 PID 认实例(就绪判定读的是子进程 stdout 里的登录横幅),进程一退出它就记「已退出」;它只在自己启动时做一次「核验并恢复监控」,判据仍是那个进程的身份,所以新 PID 不会被认领。
    • 后果与处置:启动器里看不到、也停不掉它(要从任务管理器结束进程);也别对同一个 profile 再点一次「启动」,那会变成两个实例争同一个端口。要恢复管理,只能先手动结束那个进程,再从启动器启动。
    • 这条本插件修不了:需要启动器提供重启接口,而本插件按设计不依赖、也不改写启动器的私有状态(那套记录是它的私有格式,靠它等于把插件绑死在一个第三方实现上)。
  • ⚠️ 端口暴露的风险同样适用:POST /api/agent-control/restart 走的是插件自建路由(没有 harness 鉴权),所以它额外做了 Origin/自定义头校验,避免被网页 CSRF。但如果你的 webServer 绑在 0.0.0.0 上,等于把「重启我的实例」暴露给整个网络——不要这么部署。

关闭实例

设置页同一页里还有一个「关闭 DSH」按钮:干净地停掉整个实例(ctx.appExit(0),与直接关窗口等价)。

  • 它存在的理由:实例被启动器失去跟踪之后(见上面那条),启动器里既看不到也停不掉它——这个按钮就是那种情况下唯一的收尾入口。当然,任何时候都能用它停实例。
  • 只有界面能触发:插件不提供对应的模型工具。关掉实例会让所有会话与后台任务一起中断,而且不会自动重启(不像热重启会续作),所以这个决定只能由人来做。
  • 必须勾选确认,弹窗里会列出当前有几个会话 / 后台任务会被中断,并写明「不会自动重启」。
  • 行为:接口先回 202(已接受这次关闭请求),然后进程退出;界面显示「DSH 正在关闭…」,随后是「实例已关闭,可以关掉这个页面」。要再用它,得从启动器或终端重新启动。
  • 不会写坏日志:退出前会尽力把每个会话已经记录的事件刷到盘上(每个会话最多等 500 毫秒,刷不动也照常退出)。如果关的时候正好有一轮在跑,那一轮在日志里会是「未闭合」,打开会话时由 DSH 内核按「被中断」补齐——这正是关窗口/崩溃时的同一套恢复路径,不是损坏。
  • 与热重启互斥:任一流程进行中时另一个按钮是禁用的。关闭不等正在跑的任务结束(它就是要立刻停),这一点与热重启刻意不同。

任务完成提醒

只有 notify 那一行(dsh-agent-control/notify)可用时才出现。这一行在 host 端只有一条只读探针 GET /api/agent-control/notify/status:没有 POST 路由、没有模型工具、不改变任何状态,功能全在浏览器里。

这一行里有两个互相独立的子开关:铃声与系统通知。只开一个就只做一半,两个都关就安静完成。

  • 会话从「运行中」变成空闲时响一声。 判据是 running 的 true → false 边沿——页面刚打开时的第一份快照不会误响,重复快照也不会重复响;子代理会话不响;提醒范围可以限定为「仅当前会话」。
  • 音效(三音 / 单音 / 钟声 / 不响)与音量在设置页「任务完成提醒」一节调(settings.section,order 510),全部用 Web Audio 现场合成,不下载音频文件。
  • 浏览器要求页面先被点过一次才允许出声;没点过时铃声静默降级,不报错、不影响其它功能。
  • 系统通知(默认关):勾选同一节里的「系统通知」后,一轮结束时会弹一条系统通知——标题「任务完成」、正文是会话标题(拿不到标题时是「一轮回复已经结束」);它不出声(声音归铃声,同一次完成不会响两下),同一个会话的连续完成是替换而不是在通知中心堆一串;点通知会聚焦窗口并回到那个会话。用的是浏览器标准的 Notification API,网页版与桌面版走同一份代码(桌面版里通知以承载页面的宿主身份发出)。
  • 权限只从用户手势申请:勾选复选框或点「测试通知」时才会弹浏览器的授权提示;完成时只读权限、绝不主动弹框。没授权就不弹、也不报错,设置页会如实显示「已授权 / 尚未授权 / 已被浏览器阻止 / 这个环境不支持系统通知」。
  • 两个提醒都只在这个页面里生效:页面关掉之后既不会响、也不会弹通知(通知由这个页面发出)。需要页面关闭后仍然到达的通知,请另配通知工具。
  • 关掉这一行 = 不订阅完成事件、不响铃、不弹通知、也不注册设置页那一节;花费徽章与「每轮花费」一节照常。

每轮花费

只有 cost 那一行(dsh-agent-control/cost)可用时才出现,同样只有一条只读探针 GET /api/agent-control/cost/status(没有 POST 路由、没有模型工具)。

  • 读取 Chat 已经算好的精确 token 用量(未命中缓存的输入 / 缓存命中 / 缓存写入 / 输出),乘一份价目表,把金额显示在每轮回复下方(小于 1 元保留四位,例如 ¥0.0061)。金额是估算,不是账单:
    • 价目表分两套:DeepSeek 官方价(人民币,区分高峰与空闲两档)与常见模型的公开美元价(OpenAI / Anthropic / Google / xAI / DeepSeek,按模型名匹配——自动去掉 provider 前缀、版本点号与日期后缀,所以 OpenRouter 的 anthropic/claude-opus-5.5 这类路由也能算)。可在设置页「每轮花费」一节(settings.section,order 520)用 JSON 按 provider/model 或模型名覆盖或补充;未知模型显示「—」,悬停给出 token 用量,绝不猜价格。
    • 峰谷按北京时间判定:工作日 09:00–12:00、14:00–18:00 为高峰,其余时段(含周末)按空闲价。⚠️ 节假日没有公开的机器可读日历,按工作日算,因此节假日会高估一倍;宁可高估也不低估。
    • 一轮跨多个模型时按第一个路由估算;官方价格调整后内置表可能滞后,请以账单为准。
  • 每轮花费徽章挂在 conversation.chat.turnTail 槽位(order 100,紧跟「已删轮次」隐藏标记),同样只在探到这一行可用之后才注册。
  • 关掉这一行 = 不注册徽章与设置页那一节;铃声、系统通知与「任务完成提醒」一节照常。

两行的设置都只存在这个浏览器里(localStorage,键 dsh-agent-control:observe;notify 与 cost 共用同一份设置对象,插件仍然不落任何数据文件):不进 profile、不写任何文件;换浏览器或清掉站点数据就回到默认值。notify 那一份里含铃声、音效、音量、提醒范围与是否弹系统通知(systemNotify,缺字段按关处理)。observe 只是这两件事的内部统称,插件列表里没有叫它的行。

已知限制

  • 打开过的会话也能删(0.2.1-alpha.2-v1.2.0 起)。DSH 仍然没有把会话从内存 store 摘除的公开接口,但实测(0.2.1-alpha.2)活会话的磁盘目录删得掉、也不会被写回来,于是插件改成:先停掉 agent,再照常删目录、工作区记账与投影缓存;如果删的正是界面上正在看的那个会话,界面会切到同一工作区里的另一个会话。
    • 残留只有一处、并且说清楚:内存里那条 store 记录会留到进程退出(它不再对应任何磁盘数据,也不会再被界面打开);接口响应里用 wasLive: true 如实标注。
  • 删除一轮不清理附件:内核当前没有公开的附件清理接口。被删轮次里的图片/文件仍留在 $DSH_HOME/attachments。
  • 已压缩的轮次可能无法单独删除:如果那一轮与其它内容共用了一个压缩后的可见节点,或它的可见节点不再连续,插件会拒绝并说明原因,而不是删掉一半。
  • HTTP 接口没有 harness 鉴权:插件自建的路由不走 harness 的鉴权链路。会改变状态的 POST 路由(删除会话、删除轮次、重启、关闭)自己做了可信校验(优先用宿主的 requestRejection,不可用时靠同源 Origin / 自定义头兜底)并要求 content-type: application/json,别的网页不能跨站触发;但能访问到这个端口的非浏览器调用者带上自定义头仍可能调用。默认只监听回环地址;如果你的 webServer 配置成 0.0.0.0,请自行评估。

安装

# 装最新发布版:不写 ref 时取仓库默认分支,本仓库的默认分支始终指向最新发布版本
dsh plugin --profile <profile 名> add github:ventisyn/dsh-agent-control

# 需要钉到某个版本时,把 <完整版本号> 换成版本分支名(也是 Release 标题)
dsh plugin --profile <profile 名> add github:ventisyn/dsh-agent-control#<完整版本号>

# 本地开发(改完重启即生效)
dsh plugin --profile <profile 名> add link:<本地 clone 路径>

⚠️ 如果 profile 里已经装了别的删除类插件,请先移除,否则界面上会出现两套删除按钮——同一批槽位只能有一个主人:

dsh plugin --profile <profile 名> remove <占用了同名槽位的插件>

安装或改动 host 端代码后需要重启 dsh web:已加载的 host 模块不会因为文件改动而重新导入(新增的路由会一直返回 401)。

排障

装好之后:

# 会话列表(同时也是「路由是否注册成功」的探针)
curl http://127.0.0.1:<端口>/api/agent-control/sessions

# 热重启的状态(也是辅助进程判断「新进程起来了没有」的探针)
curl http://127.0.0.1:<端口>/api/agent-control/restart/status

浏览器控制台里:

window.__dshAgentControl.usingNativePrimitives()  // 用的是原生原语还是自带兜底
window.__dshAgentControl.id                       // 注册 id
window.__dshAgentControl.features()               // 这次挂载探测到的组件开关:{ session, turn, restart, notify, cost }
                                                  // true / false / null(null = 还没探到,按不可用处理)
window.__dshAgentControl.observe.systemNotify     // 系统通知:{ supported, permission, request, show }
window.__dshAgentControl.observe.stats()          // { chimes, notifications }:完成边沿各触发过几次

接口一览:

GET  /api/agent-control/session/status    { ok: true, enabled: true } ←「会话」组件的只读探针(界面靠它决定注册不注册入口)
GET  /api/agent-control/sessions          会话列表
GET  /api/agent-control/turns?sessionId=  某个会话里已被删除的轮次
POST /api/agent-control/session/delete    { sessionId }
POST /api/agent-control/turn/delete       { sessionId, assistantMessageId }
GET  /api/agent-control/turn/status       「轮次」组件的只读探针(同上)
GET  /api/agent-control/notify/status     「任务完成提醒」组件的只读探针(同上)
GET  /api/agent-control/cost/status       「每轮花费」组件的只读探针(同上)
GET  /api/agent-control/restart/status    热重启的状态(也是新进程的就绪探针,同时是「重启」组件的只读探针)
POST /api/agent-control/restart           { reason?, force? } → 202 { ok, restartId }
POST /api/agent-control/shutdown          { }(可空体)→ 202 { ok } ← 停掉整个实例,只从界面触发

组件被关掉时,属于它的那几条路由根本不存在(请求落到 404 或宿主的鉴权 fallback), 所以「这个组件在不在」用上面那几条 /status 探针一拉就知道。

失败一律返回 { ok: false, error: { code, message } }。错误码含义:

码 含义
REQUEST_DENIED 删除请求没通过可信校验(Origin / 自定义头 / 浏览器鉴权),403;宿主鉴权给 401 时照抄 401
TARGET_NOT_FOUND 目标已经不存在
TURN_NOT_CLOSED 那一轮还没结束
TURN_COMPACTED 那一轮已被压缩或不再连续,无法单独删除
AGENT_BUSY 会话的任务没有停下来,已放弃删除
DELETE_FAILED 宿主拒绝了这次删除(消息里带原始原因)
RESTART_BLOCKED 别的会话或后台任务在忙(消息里列出是哪些)
RESTART_IN_PROGRESS 已经有一次重启在进行中
RESTART_RATE_LIMITED 太频繁(10 分钟 3 次 / 同会话 60 秒冷却)
RESTART_UNSUPPORTED 这个部署做不到(取不到启动规格、没有 appExit、辅助脚本缺失…)——不会假装成功
RESTART_DENIED 审批被拒,或这次请求没通过可信校验(Origin / 自定义头)
RESTART_FORBIDDEN 子代理发起重启:只有主会话可以重启宿主
SHUTDOWN_DENIED 关闭请求没通过可信校验(Origin / 自定义头 / 浏览器鉴权)
SHUTDOWN_UNSUPPORTED 这个部署没有 appExit,插件无法请求退出(请从启动器或终端停止)
SHUTDOWN_FAILED 请求宿主退出时抛错(消息里带原始原因)——不会假装已经关掉

开发

npm test    # 语法检查 + 337 项离线测试,不需要 DSH 进程,也不碰真实 profile

设计与取舍、与 DSH 版本的耦合点、改完的自检清单都在 AGENTS.md; 路由与事件细则在 docs/CONTRACT.md,已经踩过的坑在 docs/PITFALLS.md。

说明

  • 非官方:这是第三方插件,与 DeepSeek 官方没有隶属或背书关系;文中出现的 DeepSeek、DeepSeek Harness、DSH 等名称仅用于说明它在什么环境里运行。
  • 主要由 AI 编码代理编写:代码、测试与文档都是在与 AI 代理协作下产出的,提交历史里能直接看到。仓库里所有结论都尽量附上可复核的证据(日志、接口响应、诊断脚本输出),请按证据判断,不要按措辞判断。
  • 本插件的实测记录(包括未验证项)都写在仓库内 docs/VERIFY-*.md 里,请按那里的结论判断它的成熟度,不要只看本页的概览。
  • 细则与坑在 docs/ 下:CONTRACT.md(路由与事件)、PITFALLS.md、RELEASING.md。

许可

MIT

—/ 5

No ratings yet

Verified DSH bundle

Commit 4f1bc4a9f492

Community comments

No comments yet. Be the first to write one.

DSH HUB

A community index for DSH plugins. Not an official GitHub or DeepSeek AI product.

CommunityResourcesAPIAbout