dsh-supervisor

Supervision for DSH agents: a per-agent switch, a queued instruction inbox, and a supervisor-authored brief that carries the context only the orchestrator has.

It works with Agent Teams members and with plain continuable subagents, because it reads both sources the harness already maintains instead of inventing its own registry.

右侧栏「监督」
  ● builder   teammate  continuable           [监督 开]
    实现层：负责渲染层改动
    ┌────────────────────────────────────────────────┐
    │ 已读完 render/ 下 4 个模块，改动集中在 props 传递。  │
    │ 下一步应给它具体文件路径，不要给模糊目标。           │
    └────────────────────────────────────────────────┘
    排队 1 条
    15:32  顺手把 X 也改了                ✕
    [ 给 builder 排一个任务…        ] [发送]
    已投递 2 条 · 最近 15:41

它解决什么

DSH 本身能派活、能收结果，但缺三样：

缺口	本插件的做法
没有逐个 agent 的监督开关	每人一个开关。关掉 → 保留全部记录、队列暂存不投递；打开 → 按原顺序补发
没有排队收件箱	一个输入框。开关开着立即投递，关着就攒着
没人写"这个 agent 到底在干嘛"	intro 字段，只能由监督方（模型）通过 supervise 工具写入

安装

三种方式任选：

# 1. git（推荐：换机器也能装）
dsh plugin --profile web add "github:<owner>/dsh-supervisor"

# 2. 本地目录（开发调试）
dsh plugin --profile web add /path/to/dsh-supervisor

# 3. 打包后分发
npm pack                                  # 得到 dsh-supervisor-0.2.0.tgz
dsh plugin --profile web add ./dsh-supervisor-0.2.0.tgz

装完重启 dsh web。

为什么 git 安装不会被 pnpm 拦下：本包没有 prepare / build / postinstall 脚本， 产物就是仓库里的 JS。所以不会触发 ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED。

依赖

运行时零依赖。

宿主侧不 import 任何 @deepseek-ai/*（全部通过 ctx.get(...) 取服务）； 客户端只用 require('react') 和宿主已经提供的模块加载器。

唯一的软依赖是 dsh-better-sidebar： 它提供 ctx.betterSidebar.registerTab。没装它时插件照常加载、路由和工具照常工作， 只是不会出现侧边栏页签（启动时会打一条 warn）。也就是说：

• 有 better-sidebar → 面板 + 路由 + 工具
• 没有 → 路由 + 工具（可以用 HTTP 或让模型全权代劳）

配置

写在 profile 的 cordis.patch.yml 里覆盖即可：

- id: supervisor
  config:
    enabled: true
    defaultSupervise: false
    pollIntervalMs: 4000
    historyLimit: 20
    delivery: queue        # queue | steer
    statePath: null        # null => $DSH_HOME/supervisor/state.json

键	默认	说明
enabled	true	关掉后不注册任何东西
defaultSupervise	false	新发现的 agent 初始开关；默认关 = 只有显式 toggle 或面板才开监听
pollIntervalMs	4000	面板可见时的轮询间隔（1000–60000）
historyLimit	20	每个 agent 保留多少条已投递记录（0–200）
delivery	queue	子代理投递方式：queue 排到下一轮，steer 插到最近一步
statePath	null	状态文件绝对路径

非法值一律回落默认，不会让 profile 起不来。

模型侧接口：supervise 工具

监督方（通常是主 agent）用它读写监督状态：

action	参数	说明
list	—	列出 agent、开关、队列深度、是否已有介绍
toggle	agent, supervise	开关；打开时自动补发队列
queue	agent, text	排一条任务；开关开着立即投递
intro	agent, text	写入介绍
request_intro	agent	标记"等介绍"，面板显示待办
forget	agent	清除本插件的记录（agent 本身不动）

agent 可以传 id，也可以传名字/标签（大小写不敏感）。

HTTP 接口

POST /supervisor/api，sessionId 可以是当前看到的任意会话——宿主会自己上溯到根会话。

{ "op": "list",          "sessionId": "..." }
{ "op": "toggle",        "sessionId": "...", "agentId": "...", "supervise": true }
{ "op": "queue",         "sessionId": "...", "agentId": "...", "text": "..." }
{ "op": "drop",          "sessionId": "...", "agentId": "...", "index": 0 }
{ "op": "intro",         "sessionId": "...", "agentId": "...", "text": "..." }
{ "op": "request_intro", "sessionId": "...", "agentId": "..." }
{ "op": "forget",        "sessionId": "...", "agentId": "..." }

除 list 外都返回完整快照。业务失败是 {"ok": false, "message": ...}，HTTP 状态仍为 200； 只有请求本身不合法（非 POST、JSON 解析失败）才用 4xx/405。

数据从哪来

数据	来源	是否本插件所有
团队成员、状态、模型	ctx.agentTeams.listMembers	❌
任意深度子代理、投递模式	ctx.subagents.listDescendants	❌
团队投递	ctx.agentTeams.sendMessage	❌
子代理投递	ctx.subagents.prompt	❌
监督开关、队列、介绍、历史	$DSH_HOME/supervisor/state.json	✅

因为前四项每次都现读，面板永远不可能和任务板/工具看到的不一致。

谁能被监督

类型	可投递	说明
Team teammate	✅	走 sendMessage
continuable 子代理	✅	走 prompt，和你手动切进子会话打字是同一条通道
one-shot / external	❌	终态记录，面板标「只读」，输入框不出现
Lead 自己	—	不出现在列表里（它是监督方）

状态文件

{
  "version": 2,
  "roots": {
    "<根会话 id>": {
      "agents": {
        "<agent 会话 id>": {
          "name": "builder",
          "supervise": true,
          "intro": "…",
          "introRequestedAt": null,
          "queue": [{ "at": 0, "text": "…" }],
          "history": [{ "at": 0, "text": "…", "queuedAt": 0 }],
          "lastError": null
        }
      }
    }
  }
}

按 agent id 而不是名字索引——名字会变、会在不同团队里重名，id 不会。 删掉这个文件即全部重置。

兼容性

DSH	状态
0.2.x	目标版本，已验证
0.1.x	未验证；subagents.prompt 与 agentTeams 的契约可能不同

用到的服务：webServer（必需）、agents、subagents、agentTeams、tools（可选）。 缺任何一个都只降级对应功能，不会让插件加载失败。

测试

npm test

54 项离线检查：配置归一化、状态修复与版本、名单与目录合并、根会话解析、 三条投递分支、开关暂停/补发、介绍读写、工具契约、客户端 bundle 加载与降级。 不连网、不起 DSH、不需要浏览器。

限制

• 不是推送：面板按 pollIntervalMs 轮询。团队投影本身是推送的，但复用需要读客户端 内部 state，稳定性不如走宿主路由。
• 不显示对话内容：只看状态与介绍，要看内容用 DSH 自带的子会话转录。
• 路由无鉴权：只监听回环地址，且 sessionId 必须能解析到在线会话；但同机任何进程都能调。 需要更强隔离请在前面加代理或改用 unix socket。
• steer 模式的语义由 DSH 决定（插到最近一步，不保证被采纳）；默认 queue 更可预测。

许可

MIT