本地 Superagent（Local Superagent）

中文 | English

DSH 插件：一个本地版 Superagent 任务看板。你在自己的 DSH 工作区里布置任务，插件自动把任务派发给独立执行会话（worker），由"主管"会话按验收条件审查结果并决定下一步；只在真正需要你决定时才把任务放到「待你决定」。入口在左侧导航栏 Superagent。

本项目是独立的社区插件，不是 DeepSeek 官方产品，也不是上游仓库的 fork 或官方代码改版。架构参考 DeepSeek 的 dsh-superagent-prototype（注意力经济学、主从双 Session、结构化汇报、审查与恢复）；不提供 GitHub/Gitee 自动接单，任务直接来自本地看板，工作区就是本机目录。

安装（首选 GitHub）

需要 Node.js >= 22 和 DSH。当前实机验证范围仅为 Windows / DSH 0.2.1-rc.5；其他平台和 DSH 版本尚未实机验证。

• DSH Desktop：在插件页选择「添加插件」，在「包名或地址」填写 github:superchao5717/dsh-local-superagent#v0.4.0 固定版本；也可从 v0.4.0 发布页核对安装包。Desktop profile 由 Electron 专属管理，不要使用 Web CLI 命令管理 Desktop。

• DSH Web：在运行 DSH Web 的环境执行以下命令（--profile 位于 add 之前）：

  dsh plugin --profile web add github:superchao5717/dsh-local-superagent#v0.4.0
  

安装后在左侧导航栏打开 Superagent。不要手工编辑 profile 的 bundles 或依赖列表。包名保留 @local/dsh-local-superagent，以兼容已有 profile；@local 不代表只能本地安装。

项目不发布 npm（private: true），分发方式是 GitHub 源码及 GitHub Release 的 .tgz。运行代码本身是 JavaScript，无需 build 步骤；Release 是否已提供可用资产以发布页为准。

0.4.0：统一全局设置与任务入口

以下使用说明描述 0.4.0 的正式行为。旧 0.3.0 仍采用每主管独立配置，其历史验收记录保留在下方；升级需安装新版本，现有实例不会因文档更新而自动改变。

• 右上角「设置」统一管理一份全局配置，模型、自动审查、暂停和超时自主续办对所有主管及 worker 生效；不再提供单主管配置。工作区/主管筛选只改变查看范围，不改变配置作用范围。
• maxWorkers（1–4）是统一配置的每位主管并发上限，不是全看板共享的总 worker 池。修改配置不强行中断当前请求或执行轮；后续派发、审查与续办使用新值。
• 一个工作区可以创建多个 Superagent；它们保留各自的任务队列、工作区归属与审查上下文，每个任务绑定明确的主管，但不再分别保存生效的模型或调度设置。
• 执行模型范围全部不选时，继承统一的 Superagent 模型；统一主管模型也未选时才跟随 DSH 默认。

0.4.0 / schema 3 升级迁移

升级前先备份账本，等待正在执行的任务结束。迁移以原 board.settings 作为全局配置，不从某个已选主管推断配置；旧主管原设置保留在各记录的 legacySettings 中供审计，settingsMigration 记录 fromSchema、toSchema: 3、at、settingsSource: 'board.settings' 与说明信息，任务、报告与待回答问题保留。schema 3 的主管存储记录不再保存生效的 settings；看板返回的 superagents[].settings 只是全局设置的只读投影。旧单主管账本仍保留按工作区建立默认主管的迁移路径。

schema 3 不建议直接用旧版 0.3.0 覆盖运行，也不承诺自动兼容降级。 如需回退，应先停止相关运行并使用升级前备份，避免旧版误读新账本。加载插件会轮换运行会话。

多主管与人工决策

• 待用户决策的任务始终保留在“进行中”，以等待样式显示问题、主管归属和回答入口，不再从三列看板消失。
• “超时自主续办”默认关闭，开启后可设置等待时间（1–1440 分钟，默认 30）。到期由任务所属主管审慎决定是否在原授权范围内推进，记录决策，而不是伪造用户回答。暂停时不自动续办；必须由人完成的登录、认证、权限、付款或新增授权等步骤不能因此绕过。每个任务在人回答或手动重试之前最多尝试一次超时自主续办；新问题不会无限触发模型调用，后续仍可转人工。
• 删除主管不删除历史任务；有未结束任务的主管不能删除。
• 多主管不等于文件隔离：同一个工作区内的主管访问同一磁盘目录。并行修改同一仓库前请划分文件范围或使用项目自己的独立 worktree，不自动提供文件锁。

快速开始

1. 左侧导航栏点击 Superagent；
2. 选一个工作区，在主管 rail 点击 ＋ 创建或选中一个 Superagent；选中主管旁的 ⋯ 菜单可改名或删除；
3. 使用主管区域下方唯一的 布置任务 入口，填写标题、目标/要求、验收条件（可选）、优先级，确认主管归属后 加入队列；顶部工具栏不再提供重复入口；
4. 插件自动派发、执行、审查；需要你决定时任务仍在“进行中”并显示等待标记，可在顶部问答区或任务详情直接回答，回答后自动继续。

建议安装/升级后重启一次 DSH：插件在启动时轮换自己的主管会话来获得干净的提示词与工具注册。

看板怎么读

区域	含义
顶部计数	运行中 / 排队 / 待你决定 / 已完成 / 并发上限；暂停停止派发新任务（运行中的继续）
工作区	来自 DSH 的工作区注册表；也可「添加工作区」注册本机目录
待你决定	顶部可展开问答区，直接显示问题并提交回答；任务同时保留在“进行中”，详情也可回答
待接单	已接单、等待所属主管的空闲执行位
进行中	执行中、主管审查中、等待用户决策；等待任务用专门样式标识，并显示自动续办状态
已结束	已完成 / 失败 / 已停止，可按类型筛选
详情	目标、验收条件、执行报告、交付物、主管结论、执行会话 id（可复制）、进度日志；可重试/停止/删除

右上角「设置」统一修改全局配置：每位主管并发上限（1–4）、自动审查、暂停/恢复、Superagent 模型、工作代理模型范围及超时自主续办。对所有主管/worker 生效，与当前工作区或主管筛选无关；并发值不是全看板总池。系统会显示主管会话 id 与状态目录。

模型配置

全局设置面板的「模型」区有两项配置，统一用于所有主管及 worker；选项来自 DSH 当前的模型目录（与聊天窗口的模型选择器同源）：

配置	作用	空值语义
Superagent 模型	主管会话（审查执行结果、决定下一步的 supervisor）使用的模型	跟随 DSH 部署默认模型
工作代理模型范围	执行会话（worker）允许使用的模型范围，可多选；第一个是默认执行模型	继承统一 Superagent 模型（统一主管模型也未选时才跟随 DSH 默认）

• 派发新任务或重试时，执行会话默认使用范围内的第一个模型；在设置里可把任意已选模型「设为默认」。
• 主管审查时会在 payload 里看到 worker_models 范围；判 continue 时可以附带 worker_model，指定下一轮执行会话换用范围内另一个模型（例如小模型没做出来时升级模型）。不在范围内的模型会被 Host 拒绝并给出可选范围。
• 保存时 Host 会对照模型目录校验，模型当前不可用返回 invalid_model；模型目录暂时读不到时按原样保存，避免网络波动卡住设置。
• 模型按会话注入：worker/supervisor 会话创建后，Host 用它自己的 agent/request、system-prompt/assemble 路由把请求固定到配置的 provider/model，并写入 model/selection 会话事件；不会改动 DSH 的全局默认模型。统一配置不会改写 DSH 的全局默认，也不强行中断当前请求或执行轮；新值用于所有主管后续审查及 worker 后续派发/续办。

界面与交互

• 紧凑的主管 rail 用于切换单个主管或聚合视图，显示状态与计数；＋ 创建主管，选中主管的 ⋯ 菜单提供改名和删除，不再另设独立管理面板。
• 布置任务 只有一个入口，位于主管区域下方；任务表单也在这里展开，关闭再打开保留当前页面内草稿。顶部工具栏只保留暂停、刷新、全局设置等操作，不重复放置任务 CTA。
• 工作区以胶囊标签切换（全部 + 每个工作区 + 添加工作区弹层）；右侧常驻搜索框，可按标题/目标/工作区实时过滤。
• 看板三列：待接单、进行中（含「主管审查中」徽标）、已结束（按完成/失败/已停止筛选）；卡片按优先级与更新时间排序，显示优先级、耗时、最新进展、待回答的问题或主管结论。
• 「待你决定」在顶部展开显示问题和回答框，可直接提交，不必打开详情；可收起以节省空间。任务仍以等待卡片留在进行中，详情也保留回答入口；轮询和折叠不会清空当前问题的页面内回答草稿，更换问题则清除旧草稿；Enter 提交、Shift+Enter 换行。开启超时续办时显示适用条件和计时，不把必须由人处理的问题显示成必然会自动继续。
• 详情抽屉：概览、目标/验收、执行报告（状态徽标 + 交付物）、主管审查、执行会话 id（一键复制）、垂直进度时间轴；底部重试/停止/删除（删除有二次确认）。
• 设置与添加工作区使用锚定弹层，点击外部或 Esc 关闭；操作结果以右下角轻量提示条反馈，不打断操作。
• 键盘：Esc 逐层关闭弹层/详情；表单内 Ctrl / ⌘ + Enter 提交任务；n 在页面空白处聚焦「布置新任务」。
• 响应式：宽屏为看板 + 右侧详情栏；窄于约 1180px 时详情变为右侧抽屉 + 遮罩，窄屏看板收成单列。

工作原理

用户在看板布置任务（工作区 + 标题 + 目标 + 验收）
        │  确定性调度（Host 代码，不需要模型参与）
        ▼
每轮一个全新的 worker Session（工作区目录、工具集受限、系统提示注入）
        │  工作完成后调用 superagent_report 恰好一次：
        │  ready | needs_decision | blocked | failed
        ▼
任务所属 Superagent 的持久 supervisor Session 审查（主管之间上下文隔离，只判断、不执行）
        │  superagent_review：done | continue | needs_you | fail
        ├─ done      → 已完成
        ├─ continue  → 进入所属主管队列，按容量派发下一轮 worker（携带上一轮摘要，最多连续 2 轮）
        ├─ needs_you → 进入「待你决定」，只带一个问题
        └─ fail      → 失败

关键设计：

• 主从分离：worker 读代码、改文件、验证；supervisor 不读代码、不动手，只对照验收条件给结论。两者的上下文互不污染。
• 确定性派发：用户任务本身就是明确授权，所以接单/排队/并发控制由 Host 代码完成，省掉一次模型往返，也避免模型"漏接单"。
• 模型可配：主管会话与执行会话的模型都可在设置里配置；执行会话使用一个有序模型范围，主管在 continue 时可为下一轮选择范围内的模型。模型按会话注入，不动 DSH 全局默认模型。
• 结构化汇报：worker 只能通过 superagent_report 交结果（状态 + 摘要 + 交付物 + 单个问题）；汇报内容越界会被 Host 校验/截断。
• 低打扰：正常推进不弹窗、不往聊天里发消息；只有 needs_you 才占用你的注意力，一次一个问题。
• 预算与止损：worker 被要求"验证点到为止、同命令失败两次即停、单轮尽量 10 分钟"；Host 另有 45 分钟超时兜底，超时转人工决定。
• 可恢复：账本是 Host 端 JSON（原子写）；插件/DSH 重启后，运行中的任务重新排队，审查中的任务重新入队；每轮派发使用新的 worker Session，避免旧插件的工具注册残留。
• 会话可见：worker 会话会出现在所属工作区的会话列表里（标题 ⚡ 任务名），可以直接点开看执行过程；主管会话标题为 Superagent 主管（自动调度，勿手动删除）。

文件与状态

• 插件入口：index.js（Host 装配与同源 API 路由 /api/local-superagent/invoke）
  • lib/store.js 任务账本（原子写 JSON）、lib/engine.js 调度/审查/恢复、lib/sessions.js 会话创建与装饰、lib/models.js 模型选择归一化与目录裁剪、lib/prompts.js 提示词、lib/tools.js 模型工具、lib/api.js 操作分发
  • client.js 浏览器端看板（React，经 DSH Client Slot 注册左侧入口与主面板）
  • docs/CONTRACT.md Host/Client 接口契约
• 运行账本：~/.dsh/state/local-superagent/board.json
• 模型可用的 agent 工具：local_superagent（board / add_task / task），可从任意会话读取看板；建任务需明确主管归属。模型不能伪造用户回答：人工回答从 UI 提交；只有用户显式在全局设置开启超时自主续办时，主管才可在安全门允许的普通方案决策上自主继续，并留下“非用户回答”的日志。

边界与注意

• 不是安全沙箱：worker 以当前 OS 用户、danger-full-access 运行，能读写你能读写的路径；任务目标要写清楚范围。
• 默认本地交付：提示词要求不 commit / 不 push / 不部署 / 不装软件，除非任务明确要求。
• 删除「Superagent 主管」会话会让下次审查重新创建它；不要手动删，以免丢失审查上下文（任务本身不受影响）。
• 卸载：在插件页按名称停用/移除插件；账本文件保留在 ~/.dsh/state/local-superagent/，删除前确认不再需要并做好备份。
• 与上游原型的差异：没有 Source/Trigger/Thread/Mandate/远程任务准入层，没有 GitHub/飞书投递；任务由用户在本地明确布置，但任务内容仍需审慎检查。保留了主从 Session、报告协议、审查、恢复、注意力最小化这些核心机制。

开发与测试

npm test
npm run check
npm pack --dry-run

需要 Node.js >= 22；测试没有 npm 依赖，也不需要安装插件、启动 DSH 或访问真实账本。

开发修改 Host/Client 后，可在插件页按名称停用再启用插件，并刷新页面验证；若 DSH 缓存了旧的 Client 模块元数据，可能需要重启 Host。仅文件修改成功不代表运行实例已更新。

0.4.0 验证范围（2026-11-04）

• 本地离线回归 78/78 通过；真实账本副本的 schema 2→3 迁移验证了任务/问题保留、旧设置归档及重复迁移幂等。
• 已在现有 Windows / DSH 0.2.1-rc.5 实例验证全局配置作用于多主管、主管 rail 创建及改名/删除保护、唯一任务入口。未宣称干净 Host 重装或跨平台 CI 已通过；安装与 Release 资产应单独核验。

已发布 0.3.0 历史验收范围（2026-11-04）

以下记录仅属于每主管独立配置的已发布 0.3.0；0.4.0 的全局设置/schema 3 验证范围单独列于上方，不改写历史结果。

• 当时 Windows 离线回归 71/71 通过，Host/Client JavaScript 语法检查通过；包含多工作区/同工作区多主管隔离、迁移幂等、模型继承、自治预算与容量、人类安全门、停止/停用/人工回答竞态，以及紧凑 rail、折叠管理、顶部回答与草稿的 Client VM 测试。
• 已在现有 DSH 0.2.1-rc.5 实例实测：创建多主管、独立设置、跨工作区暂停排队、等待卡保留在进行中、普通问题超时自主选择并第二轮完成。空 worker 范围的两轮执行请求路由与主管模型一致。
• 审查使用每轮 review_token + 持久 reviewEpoch，旧轮次判决和兜底结算不能覆盖人工回答后的新轮次；停止后的任务不能被迟到回答或停用设置复活。删除主管后历史任务的重试会明确拒绝，而不是永久排队。
• 离线测试不安装插件、不启动 DSH、不调用真实模型/GPU/账号，也不读取真实运行账本。提供 Linux/Windows、Node.js 22/24 的可选 CI 示例；本次未启用或验证远程 CI，也不代表这些组合已实机通过。GitHub 安装与 Release 资产仍应在正式发布后独立验收。

许可证

MIT，保留原版权署名。架构参考与上游许可信息见 THIRD_PARTY_NOTICES.md。贡献约定见 CONTRIBUTING.md，风险与漏洞报告见 SECURITY.md。