dsh-mini-superagentPLUGIN
v0.10.1 · MIT GitHub
npm 已发布 · v0.10.1 · MIT

dsh-mini-superagent
主会话派活,报告自己回来

把活派给独立的后台子会话,报告会自己作为插件来源的消息回流主会话;侧边栏「派发工作台」看并发、排队、批次进度与失败原因。

10 个 dispatch_* 工具 + 一块常驻工作台,纯 ESM、零运行时依赖;npm 已发布 0.10.1,按包名一行装进 DSH。

派发工作台 · dispatch console全部进行中分析
认识 dsh-mini-superagent worker Session × 3
把 auth 从单文件拆成独立模块,不改公开 API
dispatch_launch_many group g-m0abc
t-m0abc-1 拆分 auth/types.jsrunning
t-m0abc-2 拆分 auth/index.jsqueued
t-m0abc-3 补 auth 回归测试queued
t-m0abc-4 更新调用点queued
dispatch_report · done

auth 已拆成 4 个模块,公开 API 未变;补了 3 个回归测试,npm test 全绿。

把 4 个模块分别重构,最后跑一次全量测试
+ 工作区内修改DeepSeek-V4-Flash High

面板字段与状态取自 tools.js / dispatch.js 的实际返回

01 / CAPABILITIES

派发出去,主会话不再等结果

能力模型沿用 DSH 官方 dsh-superagent 原型的「主会话 + 执行器 Session」,但只保留派发这一件事:没有数据库,没有构建步骤,也没有跨进程调度。

10 个工具,一条闭环

派发、查询、干预、汇报四组工具注册在插件根 context,对所有会话可见;能不能调用由 execute 里的角色判断决定。

dispatch_* · TOOL_NAMES10 registered
dispatch_launchlaunch
dispatch_launch_manylaunch
dispatch_listquery
dispatch_messagesteer
dispatch_reportreport

一次派一批,并发可控

dispatch_launch_many 一次派 1–16 条互相独立的任务;全局最多 6 个同时 running,超出的进 queued,每个结算点自动补位。

batch g-m0abc2 / 5
t-1 改接口done
t-2 补实现running
t-3 跑测试depends_on_index [1]
t-4 补文档queued
t-5 汇总queued

过程看得见,进度按步走

worker 在 dispatch_report 里带 plan(最多 12 步 × 120 字,整版替换),看板任务行显示 2/5,抽屉显示当前步骤。会话里直接出卡:派发卡带批次与实时状态,报告卡按【任务】【结果】【备注】【需要】四段渲染。

dispatch_report · plan2 / 5
01 读接口定义done
02 拆分类型文件done
03 改调用点
04 跑回归测试doing

出事查得到,账本可审计

tasks.json v4 是派发事实的唯一权威;重启恢复、未结算标 interrupted、退休留痕,dispatch_inspect 能翻到最后一次输出。

GET /dsh-mini-superagent/boardtrace
launcht-m0abc-1
startdispatch-t-m0abc-1
reportdone
relaydirect
settletasks.json v4
02 / DEVELOPER EXPERIENCE

开发者体验

图形界面安装(最省事)

打开 DeepSeek Harness 的插件页面,点右上角「添加插件」,输入 dsh-mini-superagent 即可安装;装完刷新一次 GUI 页面。不需要命令行,也不需要写 target。

01打开 DeepSeek Harness 的插件页面
02点右上角「添加插件」
03输入包名,确认安装
$dsh-mini-superagent

一行安装(npm)

dsh-mini-superagent@0.10.1 已发布到 npm(latest)。在 DSH 里按包名安装即可,不用 clone、不用构建、也不用 npm install。装完确认 10 个 dispatch_* 工具已注册。

$plugin_manager(action="install_bundle", target="dsh-mini-superagent@0.10.1")

从源码 / 本地目录安装

想改代码或用本地目录装,先 clone 再把 target 换成本地路径。装完刷新一次 GUI,侧边栏图标与输入框控件才会加载。

$git clone https://github.com/wychmod/dsh-mini-superagent.git
$plugin_manager(action="install_bundle", target="<仓库路径>/dsh-mini-superagent")

验证版本与并发上限

version 与 src/constants.js 的 VERSION 一致;max_workers 等于配置里的 maxWorkers(默认 6)。

$dispatch_list() → {"version":"0.10.1","total":0,"running":0,"max_workers":6}

环境与安装注意

不要和旧插件 dsh-dispatch 同时安装:两者有 8 个同名工具,同一全局层重复注册会直接抛错。

$DSH >= 0.2.1-rc.2 · Node ^22.19.0 || >=24.0.0 · 0 运行时依赖
03 / GET STARTED

从安装到派出第一条任务

子会话看不到主会话历史,brief 必须自包含:目标、约束、验收、已知事实。派发返回之后,该任务的执行环节都归子会话。

基本使用

01
写一份自包含的 brief

目标 / 约束 / 验收 / 已知事实四项齐全;注入上限 maxBriefChars 12000。

02
派发即移交,结束本轮

dispatch_launch 登记 + 投递后立即返回;默认不要用 dispatch_wait,报告会自己作为消息回流并唤醒空闲会话。

03
需要先后关系就声明依赖

depends_on_index: [0] / depends_on(最多 8 个前置)。依赖在任务开始前判定,前置未结算就一直 queued 且不占并发位。

04
接着上一条继续干

dispatch_message 追问纠偏;continue_task_id 同一任务追加要求;handoff_from 新建任务并沿用来源子会话。

必要配置 · 全部可选

写在 bundle 的 cordis.patch.yml 的 config 里;整段删掉也能工作,默认值见 src/constants.js 的 DEFAULTS。

maxWorkers6
maxTasksPerSession64
workerWorkspaceday
archiveAfterHours168
retryTransienttrue
noticeMergeWindowMs1500
restrictRoutertrue
ledgerMaxTasks / Days1000 / 90
autoHandofffalse

另有 stateDir、reportOnTurnEnd、maxReportSummaryChars 6000、memoryWindowDays 7 / memoryWindowTasks 200、taskDirRoot 与 prepareCommand 等;完整清单见包内 README。

04 / USE CASES

四种真实用法

场景 01 / 并行

把多个模块分别重构

一次派 1–16 条互相独立的任务,每条各自一个子会话、立即入队;整批结算后收到一条批次汇总,而不是 N 条流水。

dispatch_launch_many / group 汇总

场景 02 / 先后

先改接口,再补实现,最后跑测试

批内用 depends_on_index,跨批用 depends_on。前置失败或取消会连带取消并写 cancel_reason 与 error_code,不会自动改派。

depends_on / depends_on_index

场景 03 / 接续

追问、纠偏与上下文续用

worker 报 blocked 就追问;handoff_from 新建任务、沿用来源子会话,保留独立记录、报告链与看板行。dispatch_candidates 只给候选与素材,不打分。

dispatch_message / handoff_from / dispatch_candidates

场景 04 / 可观测

长任务的过程与结果都能查

plan 让看板显示 2/5;派发工作台四视图 + 独立「已退休」视图 + 分析看板;tasks.json v4 重启恢复,dispatch_inspect 翻到最后一次输出。

plan / GET /dsh-mini-superagent/board / dispatch_inspect

05 / ARCHITECTURE

一次派发,经过哪些模块

主会话只接触 tools.js;派发逻辑在 dispatch.js,纯状态与队列在 tasks.js,落盘在 store.js,所有宿主 API 收在 sessions.js。看板走同源 HTTP,浏览器侧不打包、不编译。

主会话 Agent派发者 tools.js10 个 dispatch_* dispatch.jslaunch / pump / settle sessions.js建会话 / 投递消息 worker Session × N独立 cwd · 有历史 dispatch_launch / dispatch_launch_many → 登记后立即返回 纯逻辑 / I/O / 适配层 tasks.js状态跃迁 / 队列 store.jstasks.json v4 workspaces.js工作区 / 归档 prepare.js每任务目录 prompt.js / voice.js给模型 / 给用户 dispatch_report → 插件来源消息 → 唤醒主会话 stats.js / analytics.js全量聚合 board.js同源 HTTP 快照 client/index.js派发工作台 / 分析看板
一句话读图:dispatch_launch 进来,dispatch.js 登记任务(tasks.js)并落盘(store.js),由 sessions.js 建会话、投简报;worker 用 dispatch_report 回到 tools.js,报告再投回主会话。看板从任务表与聚合模块取数。
01 src/index.js入口 · 建 Dispatch、restore + provision、注册 10 个工具、接宿主事件、注册看板路由、启动归档巡检。
02 src/tools.js工具层 · 10 个 dispatch_* 定义、参数 schema、结果卡片拼装与归属校验;不直接操作会话。
03 src/dispatch.js编排层 · launch / pump / settle / start / report / admissionOf / relay / cancel / retry / 归档 / targets / 记忆治理。
04 tasks.js + store.js纯状态与 I/O · TaskTable.transition() 是状态唯一写入口;tasks.json v4 原子替换写 + .bak 回退,800ms 防抖。
05 sessions / workspaces / prepare宿主适配 · 建会话、构造插件来源消息、双通道投递、切工作目录;工作区四级解析与每任务目录。
06 worker Session × N执行 · 独立 Session、独立 cwd、有历史;用 dispatch_report 汇报,报告回流主会话。
07 board.js + client/index.js看板 · GET /board(2s 轮询)、/board/retired、/board/stats、/board/analytics;POST cancel / retry / archive / target。

依赖方向:单向、无环

index → dispatch → sessions → prompt → tasks → constants
dispatch → store / prepare / workspaces / board
client/index.js  ──同源 HTTP──▶  board.js

board.js 接收 dispatch 实例但不 import 它;client 与 Host 没有 import 关系,只通过路由前缀与快照字段对齐(由 test/contract-consistency.test.js 钉住)。tasks.js / store.js / workspaces.js 不 import 任何 @deepseek-ai/*,因此能脱离 DSH 单测。硬依赖是 tools / agents / sessionController 三个服务;webServer 缺失时看板路由安静跳过,派发与工具照常。

06 / DESIGN DECISIONS

六个关键取舍

这些不是偏好,是 docs/architecture.md 里逐条记下依据与代价的实现事实。

01 / 执行单元

worker 是 Session,不是一次性子任务

用 sessionController.create 建真正的 Session:建完就能投递,有历史可追问,人在侧边栏能直接接手。代价是会话列表会持续增长,任务取消不会删会话。

02 / 权威源

账本才是事实,会话只是投影

tasks.json 存状态归属、报告正文、投递结果与续跑信息;会话里的报告都是从账本读出再渲染的投影。投影可以更短、可以丢、可以重放,但不得反过来成为事实。

03 / 并发

靠队列,不靠拒绝

takeRunnable() 在返回任务前先置 running 占位,避免多个 pump 交错超发;派发、加载与所有结算点都会触发 pump。dispatch_message 唤醒已结算 worker 是软上限的有意例外。

04 / 状态机

状态只有一个写入口

TaskTable.transition() 依跃迁表校验每次变化;SETTLED(占不占并发位)、COMPLETION_BASE(能不能给完成率投票)、STATUS_ORDER(展示顺序)分开定义,改图的顺序不会动指标口径。

05 / 报告

至多一次投递,事实与投影分离

三次重试共用一个 message id,重试前查收件箱与会话事件判重。入库上限 6000 字管账本体积,投影预算 800 字管回流长度;压缩只作用于投影,dispatch_inspect 读回的仍是全文。

06 / 治理与交付

给记忆设预算,客户端不打包

1.5 秒合并窗口只收 progress,结论类永不参与;账本 1000 条 / 90 天封顶,退休只留 13 字段薄记录。client/index.js 用 plain ModuleLoader,不引打包器,保住「clone 下来就能装」。

为什么「派发即移交」只写进提示,不做成守卫

主会话「重做同一个任务」在工具层面与「做另一件相关的活」无法区分,加守卫只会误伤;硬边界只有路由模式那一种:把目标设成工作区或「自动」时,用 tools.restrict({ deny: ['write','edit'] }) 结构性收走改文件工具。这一层靠 test/handoff.test.js 的文本断言防回归。

07 / BOUNDARIES

已知限制与真实缺口

对外展示一个项目,把没做到的部分也写清楚,比只写能力更有用。以下全部来自仓库 README 的「已知限制」与 Roadmap「未做」。

已知限制

  • 看板只支持 Web 形态:headless 没有 webServer 时不注册路由,派发与工具照常工作。
  • 排队只在内存:重启后未启动的排队任务重新入队,已经在跑的标 interrupted。
  • 状态文件是单写的:多个 Harness 实例共用同一个 DSH_HOME 时可能互相覆盖,用 stateDir 隔离。
  • 看板快照最多 200 条,没有分页与历史归档;/board/stats 与 /board/analytics 读全量账本。
  • maxWorkers 是软上限;worker 能看到全部全局工具,要更严的工具面用 agent_preset。
  • 读回执依赖宿主 session/event;收不到时「已投递未读」会一直显示,只影响展示不影响投递。
  • 界面未做真机视觉验收:控件对齐、弹层翻转、深浅色对比度仍以离线断言与人工目视为准。
  • 指标有窗口:成功率 / 中位耗时只算最近 7 天 / 200 条内的已结算任务。

未做(真实缺口)

  • 真机视觉验收:控件对齐、弹层翻转与边缘夹取、深浅色对比度未逐项验证。
  • token / 成本计量:需要宿主提供 usage 事件;当前账本没有费用字段,不做估算。
  • 队列持久化:排队顺序只在内存,没有落盘队列。
  • 多机调度:本地单写 JSON,不做跨进程协调。
  • 看板分页 / 历史归档:快照列表上限 200 条。

参与贡献

欢迎 issue 和 PR。改动前先读 docs/architecture.md 与对应 PRD;提交前在包目录跑 npm run check:dev(语法检查 + 648 单测 + 817 客户端离线渲染检查,GitHub Actions 跑同一条链)。约束:不引入运行时依赖、不加构建步骤、不跳过失败断言;文档里的数字必须与代码 / CHANGELOG.md 同源。

一行命令装好,派第一条任务

dsh-mini-superagent@0.10.1 已发布到 npm,在 DSH 里按包名一行安装即可。10 个工具、两张会话卡片、一份可读的 tasks.json v4 和一块常驻看板,在开源、可组合的基础上把派发这件事做透。

↑