dat-lequoc/dsh-supervisor

dsh-supervisor — 一个用于 DeepSeek Harness 的常驻监督智能体

一个 24/7 全天候运行的主智能体（Main Agent），它记录一个可审查的目标，然后无人值守地循环执行：启动一个开发子智能体 → 休眠 → 在结算 / 报告 / 定时器 / 你的消息时唤醒 → 检查 → 引导、终止或继续。基于 DeepSeek Harness（dsh）原生优先构建：核心只是一个智能体预设、一个角色设定和一行调度服务配置——零自定义循环机制。本仓库是一个可安装的 dsh 插件包：一条命令即可将整套配置部署到任何运行 dsh 的机器上。

已在 glm-5.3（Z.AI）上完成端到端测试：目标设置、有依据的委派、飞行中引导、回合中途终止 + 更紧凑的重新启动、静默提问 → 记录假设流程、交付物验证（它发现了自己那个有缺陷的链接检查器并重新运行了它），以及完整的进程重启恢复。评分器得分：m0–m5 和 m7 均为 100%。

在新 PC 上运行本地课程

安装 Git 和 Python 3，克隆本仓库，然后运行其课程启动器：

mkdir -p "$HOME/src"
git clone https://github.com/dat-lequoc/dsh-supervisor.git "$HOME/src/dsh-supervisor"
cd "$HOME/src/dsh-supervisor"
./tutorial/setup.sh

启动器将其环境保存在 tutorial/.venv 下，安装仅评分器需要的 Python 依赖，选择一个未使用的 127.0.0.1 端口，并打印教程 URL。其本地服务器为每个里程碑中嵌入的评分按钮提供支持。它有意不安装 dsh、不克隆 DeepSeek Harness、不配置模型，也不创建工作区；这些步骤由设置章节明确讲解。

安装 supervisor（第 6 章）

前置条件：Node.js 22.19+（22.x 系列）或 Node.js 24+，以及 dsh
（npm i -g @deepseek-ai/dsh），并配置好模型（Web UI → Settings → Models；
已在 Z.AI glm-5.3 上测试）。

When chapter 6 tells you to install the already-cloned package:
cd "$HOME/src/dsh-supervisor"
dsh plugin --profile web add "file:$PWD"

restart dsh once (bundle layers compose at boot):
dsh web

这就是全部安装过程。这一条命令将该包注册为一个配置文件包（profile bundle）
（依赖项 + dsh.profile.bundles 条目），在启动时该包会：

1. 挂载 supervisor 的定时器所需的调度服务（dsh-schedule）
（不挂载 dsh-time-context——它会向每个请求注入一个时间戳块，
而 Schedule 并不依赖它），并且
2. 运行本包的设置插件（lib/index.js），它会将捆绑的
main-agent 预设安装到 ${DSH_HOME:-~/.dsh}/.agent-presets/——仅在不存在时安装，
绝不覆盖你的修改（行配置 syncPreset: always | if-absent | never）。

然后为 supervisor 的状态创建一个工作区：

mkdir -p "$HOME/agi-lab/.agi/subagents"
cp "$HOME/src/dsh-supervisor/agi-template/config.json" "$HOME/agi-lab/.agi/config.json"

替代方案：不使用插件管理器的手动安装

./scripts/install-manual.sh ~/agi-lab 会将预设复制到用户预设根目录
并将调度行写入你配置文件的 cordis.patch.yml。只使用一个路径，不要同时使用两者——调度服务每个进程只注册一次，因此 bundle 行和手动 patch 行不能共存。如果你的配置文件已经从其他地方挂载了 dsh-schedule，请通过针对 agi-schedule 的 id 定向 disabled: true patch 禁用此 bundle 的副本。

运行

打开 http://127.0.0.1:3080 → 新建会话 → 工作区 ~/agi-lab → 预设
Main Agent (Supervisor) → 给它一个任务，例如：

目标：生成 SUMMARY.md，描述  的布局——委派
工作、监督、交付。

你应该按顺序看到：它通过读取持久任务状态
和相关工作区 runbook/脚本来奠定基础，调用 start_goal 写入 .agi/GOAL.md
并立即武装原生目标，然后在同一轮中继续。不需要生成的
确认短语或第二次人工回复。然后它调用受保护的
subagent 工具，传入完整的结构化任务和显式 Settings 批准的模型路由，
设置一个循环签到提醒，然后休眠。它在 worker 的 settle
通知时唤醒，通过自己的读取验证交付物，将所有内容记录到
.agi/CHANGELOG.jsonl，然后继续或完成。你可以随时通过聊天进行引导；
worker 是侧边栏中的普通会话——点击一个即可实时观看。

可审查、非阻塞的目标前端

该预设有意禁用 Harness 原生的面向模型的
@deepseek-ai/dsh-tool-goal 行。该前端允许 create_goal 推断
长时间运行的意图，而无需先检查持久任务状态或工作区
runbook。dsh-supervisor/goal 仅替换该
前端；原生 ctx.goals 服务、会话投影和竞态防护的
目标轮次驱动程序仍安装在主机上。

替代方案暴露 get_goal、start_goal 和 update_goal。start_goal
仅对直接人工轮次中的根 agent 可用，并且仅在该
轮次调用 get_goal 之后可用。它捕获目标、约束、里程碑、
范围外内容和自主轮次上限到规范的 GOAL.md，立即调用原生
目标服务，并返回到同一模型轮次，以便工作继续。
生成的文档用于可见性和引导，而不是审批门：人工可以检查它并通过普通聊天重定向、暂停或停止。
update_goal 有意省略 edit；暂停、恢复、完成、阻塞
阈值、原生修订、投影和自动继续保留其
Harness 行为。

Worker 失败仅在原生可继续子项实际
settle 时报告。supervisor 保留那一次唤醒，并从子项的
持久最终 turn/end 中丰富它，例如 Terminal failure [QUOTA]: …。中间
RATE_LIMIT、SERVER、TIMEOUT、TRANSPORT 和空响应的小问题保持静默，
而 Harness 的重试策略负责处理它们；成功的重试会产生普通的
完成通知，而耗尽的重试只暴露其最终原因。停止的子代理仍可通过 send_message 恢复。

被阻塞的工作者同样无法将问题困在自己的会话中。受保护的 spawn 前端应用了原生的每子代理工具限制，从工作者的通告 schema 和执行路径中移除 ask_user_question。子代理作用域的 report 工具刻意在该限制下保留，因此问题会以 subagent-report 消息到达父代理，唤醒监督者，并可通过 send_message 回答。因此，周期性提醒仍是一种恢复检查，而不是监督者发现工作者一直在等待输入的第一现场。实时提示词还禁止将 list_agents: running 视为进展的证据。每次检查都必须将具体的报告、产物/日志变更或已完成的步骤与其先前的 NOTES.md 检查点进行比较。第一次未变化的检查触发状态探测；下一次未变化的检查则中断并恢复或重新生成工作者。此策略被渲染到每个请求中，因此监督者在规则上无法在“仍在运行”上循环。

/.agi/config.json 中用户拥有的旋钮（代理可以提议更改，但绝不编辑它）：wakeMinutes（检查节奏，≥ 5——调度下限）和 questionWaitMinutes（在记录假设并继续之前的耐心时间）。

该预设将恢复和连续性视为显式不变量。在升级阻塞之前，监督者必须检查仓库本地的 runbook 和脚本，并尝试一组有界的、不同的安全恢复；禁止反复猛击以及绕过安全或审批边界。仅人类依赖只阻塞其分支：独立的准备和验证继续进行。每个未完成的长时运行回合都必须留下持久的唤醒路径（运行中的工作者、活动的原生目标轮次或提醒），因此单纯的聊天承诺等待无法悄无声息地搁浅任务。遗留的 GOAL.md 仍是有用的上下文，但不冒充已武装的原生目标：每个启动、恢复或继续长时运行工作的直接请求都必须先检查 get_goal；当不存在活动的原生目标时，监督者必须检查工作区相关的 runbook/脚本并调用 start_goal。提醒是恢复辅助手段，不能替代目标驱动器。
此边界由插件拥有的预执行守卫强制执行，而不仅靠人格文本：显式的长时运行延续可以检查持久状态，但在当前回合检查原生目标状态并武装一个可审查的目标之前，操作工具保持关闭。一旦 start_goal 成功，同一回合可以立即使用工作区现有的自动化。如果工作区包含 runbook、自动化脚本或源入口，start_goal 还会被额外拒绝，直到当前回合成功打开 .agi 之外的一个；宽泛的列表或仅阅读 GOAL.md/NOTES.md 不满足接地要求。
元配置（设置 → 插件 → Supervisor）

Supervisor 的用户自有调节项位于一个设置命名空间 dsh-supervisor 中，可通过两种方式编辑，效果相同：

- Web UI： 设置 → 插件 → Supervisor —— 该卡片有一个从目录添加的下拉菜单。一个合成的 Current runtime model 选项默认启用；固定模型会标注其原生输入模态以及模型所声明的推理强度。每个允许的模型行都有自己的强度选择器，添加流程会同时询问路由和强度。
- 文件： ~/.dsh/settings.yaml 中的 dsh-supervisor: 块。

| 键 | 含义 | 生效时机 |
|---|---|---|
| workerModels | 必需的 subagent.model 的完整允许列表：runtime/current 和/或精确的 provider/model-id 路由；全新安装 = runtime/current；为空 = 禁用生成 | 下一次工具调用和下一次工具 schema（实时） |
| workerEfforts | 从每个允许的路由到其用户所选强度的映射；provider/default 不发送显式强度（全新安装和缺失条目的默认值），而诸如 high 之类的固定 id 来自该路由的原生目录 | 下一次生成和下一次工具描述（实时） |
| maxParallelWorkers | 同时打开的最大 worker 数，在生成时强制执行；0 = 无限制 | 下一次工具调用（实时） |
| wakeMinutes | supervisor 唤醒以检查 worker 的频率（分钟；循环计划，≥ 5） | 下一轮（实时） |
| questionWaitMinutes | 在记录假设并继续之前，等待问题答案的时长 | 下一轮（实时） |

更改是实时的——无需重启，无需新会话：插件会重新解析允许列表并重新挂载 subagent，使其 model 枚举和能力标签仅显示当前批准的选项。执行时也会重新读取设置，从而消除在请求收到其工具 schema 后模型被移除的竞态。一个 SUPERVISOR META-CONFIG 系统提示词部分会将同一策略连同强制上限和计时默认值重新渲染到每个请求中。

强度是每个设置所拥有的模型行的属性，而不是工具调用的选择。主 agent 会收到必需的模型枚举，但没有强度参数。它也无法从自己的请求继承强度：缺失的旧版映射条目会变为 provider/default。如果精确解析出的 worker 路由未声明某个固定强度，该强度会在 provider I/O 之前被拒绝；它绝不会被钳制或静默降级。对于动态的 runtime/current，只有 provider/model 路由跟随调用轮次；其强度仍来自 workerEfforts.runtime/current。插件会保留可继续子项的精确 id（或捕获前台子项的创建边缘），并在其首次模型调用之前应用一次性的、按 id 过滤的请求覆盖，使该选择成为子项持久 request/header 的一部分。后续热步骤和冷恢复都会恢复所记录的显式强度。无需 Harness 补丁或自定义续接描述符。
这里刻意不提供预设模型列表，也不存在隐式的父级/默认继承。全新安装明确允许 runtime/current：选择它会读取调用轮次持久化请求头中捕获的 provider/model，解析其能力，并将该确切路由转发给子级。它从不读取父级创建时的选项，因此在某一轮次前切换主模型也会同时切换 runtime/current 的含义，而不会重新引发陈旧路由的 bug。如果每个子级都必须使用固定路由，请在设置中移除此条目；移除所有条目即可禁用生成。

随附的原生 spawn 和 fork 前端不在预设中，因为它们没有受设置保护的 model 参数，并且可能继承主会话的路由/effort。插件拥有的 subagent 是唯一的委派前端。每个成功的工具结果都会标明所选路由、原生模态和有效 effort 策略，例如
antigravity/gemini-3.7-flash [text,image] effort=high，因此层级结构使设置所拥有的选择可见。视觉路由：给一个 [text,image] 模型，监督者就会把图像工作（截图、UI 检查、图表）发送到那里；worker 使用 read_image 读取文件，而 harness 仅允许在具备图像能力的路由上使用该工具。

Feed 标签页

每个会话的视图环（包含 Chat 和 Trajectory 的标签页）都会新增一个 Feed 条目：对于带有 .agi/ 状态的工作区，它会一览整个运行情况——实时目标卡片、worker（含 outcome.md）、进度时间线、问题栈、操作变更日志、笔记和任务报告，每约 5 秒刷新一次。它作为持久客户端插件（lib/client.js，通过 harness 的客户端模块扫描提供服务）随本捆绑包发布，外加一个读取 .agi/ 树的主机路由（GET /supervisor/feed?ws=…）。无需重建前端，无需动态插件审批。

完全停止（Feed 标题栏中的按钮）

原生停止方块只会中止当前轮次——监督者的周期性签到提醒（wakeMinutes，下限 5 分钟）是一个持久调度事件，因此 agent 会在几分钟后自行重新运行。Feed 标题栏中的 ■ Full stop 按钮会真正结束这一切。从 worker 的 Feed 中，它会将谱系解析回根 main-agent；如果该监督者处于冷状态，浏览器会先通过 Harness 的 existing-id session.create 路径恢复它，而不启动轮次。随后 POST /supervisor/stop?session=… 会中止活动轮次，等待空闲，递归释放每个常驻的可继续 worker 分支，在折叠前刷新，并在 agent 的独占维护窗口内删除所有活动调度提醒，随后进行第二次持久化刷新。对同一路由执行 GET 会验证轮次、提醒和 worker，因此即使页面刷新后，成功停止也会将按钮替换为其已停止状态。之后的手动提示会明确恢复监督者；已停止的 worker 会话仍保留在历史记录中，但不会继续运行或唤醒它。
你在找 Shots 标签页（浏览器守护进程 /shots/ 信息流之上的截图播放器）吗？那是它自己的独立插件，dsh-shots —— 通用的浏览器守护进程工具，刻意不属于 supervisor 的一部分。

这个仓库里有什么

| 路径 | 内容 |
|---|---|
| package.json + cordis.patch.yml + lib/ | dsh 打包：清单（dsh.bundle.patch + dsh.client）、插入的行、setup/routes、非阻塞原生目标前端、最终结算诊断，以及浏览器部分（lib/client.js：Feed 标签页、Full stop、设置卡片） |
| agent-presets/main-agent/ | supervisor 预设：persona（grounding、非阻塞目标设置、循环、问题）、插件拥有的目标前端，以及唯一受设置保护的 subagent worker 行 |
| agi-template/ | 新工作区的 .agi/config.json 模板 |
| tutorial/ | 自包含的 15 步课程应用：HTML/CSS/JS、setup/server、私有需求、评分 UI/CLI、里程碑评分器，以及可选的无头驱动 |
| scripts/install-manual.sh | 非打包回退安装器 |
| DESIGN.md / IMPLEMENTATION_PLAN.md | 设计记录（Q1–Q23、A1–A6、S1–S4、N1–N7、G1）和 v2 计划 |

给它评分

./tutorial/grade.sh all --ws ~/agi-lab    # m0–m6 report with bar chart
./tutorial/grade.sh m7 --ws ~/agi-acceptance  # acceptance + restart evidence
./tutorial/grade.sh doctor                # what the grader can see

评分器只读取持久化产物（预设文件、patch/bundle 行、.agi/、会话事件日志）—— 不会在你的 agent 中执行任何内容。tutorial/GRADING.md 记录了每一项检查。

无头驱动它（可选）

S=$(python3 tutorial/drive.py create --cwd ~/agi-lab)       # new supervisor session
python3 tutorial/drive.py send "$S" "your mission here"     # prompt + wait + tail
python3 tutorial/drive.py tail "$S"                          # readable event tail

从零开始学习

运行 ./tutorial/setup.sh 并打开它打印出的 URL。第一部分从零开始教授 Cordis 和 harness（不假设你懂 TypeScript）；第二部分逐个里程碑地构建本仓库中的所有内容，每个里程碑都配有实时测试和评分器；第三部分涵盖打包插件扩展 —— 正是本仓库使用的模式 —— 以及故障排除。

发布与插件生态

这个包如何触达其他人，按投入程度从低到高排列：

1. GitHub + dsh-plugin 话题。 给仓库打上 dsh-plugin 话题标签（harness README 的官方可发现性渠道），并写一句简洁的仓库描述 —— 社区索引抓取的正是这一行。然后用户可以直接从 git 安装：dsh plugin --profile web add "github:you/dsh-supervisor"。
2. 聚合器会自动收录它：awesome 列表（例如 vvlife/awesome-deepseek-harness-plugins 每天从该话题重新生成其 PLUGINS.md）和话题驱动的市场（例如 WhaleHub，一个可视化市场，带有
一键安装命令）。向精选列表提交 PR 可增加人工收录。
3. npm publish（可选）：dsh plugin 会转发到 pnpm，因此已发布的包可按名称安装。package.json 中的 files 列表已经限定了发布内容（lib、cordis.patch.yml、agent-presets、agi-template）。

关于随插件分发预设的打包说明，来自生态系统的经验
（dsh-minimal-msys2 使用同样的启动时复制模式分发预设；
dsh-preset-qa-mode 仅分发脚本；dsh-preset-scaffold 还通过
dsh-skill-filesystem 将其打包的 skills/ 注册为技能根目录）：

- 启动时复制到 ${DSH_HOME}/.agent-presets/ 是既定模式——预设
发现机制会在每次调用时重新读取根目录，因此复制后无需重启，而且
有意移除插件不会删除已安装的预设。
- 名册还支持部署配置的额外预设 roots（参见
dsh-agent-presets Config），但 bundle 无法在不整体重述的情况下追加到
已发布行的配置中——这就是复制模式在实践中胜出的原因。

安全说明

- 大部分 supervisor 协议仍然是文字说明加审计，但目标创建和 worker 模型
路由由插件自带的前端强制执行。阅读 .agi/CHANGELOG.jsonl——
它是每次 spawn/steer/kill/assumption 的日记。
- 在使用真实凭据进行无人值守任务之前，请有意识地决定沙箱/审批姿态
（本实验环境运行 danger-full-access）。
- 每个 $DSH_HOME 永远只能有一个 dsh。切勿编辑已发布的预设或 harness 检出。