安装
在 DeepSeek Harness 里通过 dsh-market 安装
dsh plugin --profile web add dshmarket
或使用命令行
dsh plugin --profile web add dsh-background-agents
装任何插件都等于在你的机器上跑第三方代码，权限和你本人一样大——能读你的文件、用你的凭据、访问网络。请先审阅源码，并尽量锁定 commit（github:owner/repo#sha）。
README
👥 dsh-background-agents
为 DeepSeek Harness 提供可交互的长会话后台代理，以及持久化的多代理团队房间 —— 启动一个持久的子代理，它一边持续工作，你一边继续对话。
跨会话操控实时对话并协调一个团队；一切都通过 harness 自身的存储跨重启存活。
English · 简体中文 · Español · Português · हिन्दी
兼容性
| 方面 | 状态 |
|---|---|
| Harness | DeepSeek Harness 0.1.0-rc.6（peer 依赖 >=0.1.0-rc.5 <0.2.0） |
| Node | ^22.19.0 || >=24.0.0 |
| 平台 | 全部（宿主工具；可选 Web 侧栏面板与团队房间，依赖存储域能力） |
| 模型 | 任意（子代理继承父代理的路由；childProvider/childModel 可覆盖） |
你能获得什么
dsh-background-agents 把 DSH 即发即弃的后台 作业 升级为两个协同的界面：
- 五个操控工具 ——
background_agent在官方子代理接缝上启动一个持久的、可续聊的子代理（可选tool_filter—— 只移除工具、绝不授予新工具；persona；max_depth；childProvider/childModel路由）。bg_message投递后续轮次；bg_list报告状态（或用parentId/depth报告后代树）；bg_result读取最新的结果文本（回退到推理内容时标记textSource: 'reasoning'）；bg_stop请求中断。 - 进度与归档 ——
autoReport在每个子代理轮次之后注入一条节流的进度行；reportDelivery: wakeup会在父会话空闲时启动一个父轮次。空闲清扫会把安静的代理归档，bg_message再把它们唤醒（autoArchive: false则改为让安静的监视者暂停驻留）。 - 仪表盘投影 + Web 面板 ——
backgroundAgents会话投影把父日志折叠成行；侧栏面板显示实时状态、跳转、消息、停止与结果预览。一切都从持久日志重建 —— 无需独立数据库。 - 团队房间（v0.5.0+） ——
/room命令族加上八个room_*工具构建持久化的多代理房间：成员（各自是一个独立会话）、消息总线（定向/广播）、共享任务板与共享时间线 —— 存储在team_rooms存储域（SQLite 或 JSONL），并在 DSH 重启后恢复。跨成员的任务交接通过官方审批接缝进行路由。
快速开始
# 1. 将 bundle 安装到你的 profile
dsh plugin --profile web add "github:PerryLink/dsh-background-agents#main"
# 或从 npm 安装（已发布版本）
dsh plugin --profile web add dsh-background-agents
# 2. 重启并验证该行
dsh --profile web --dump-config | grep -A4 'id: background-agents'
bundle 补丁携带插件行；provider 为必填。该仓库提交了它的构建产物（lib/），因此 git 安装无需构建步骤。该插件需要子代理脊柱已挂载（任何基于 @deepseek-ai/dsh-base 构建的 profile 都具备）。团队房间在存储域被组合的地方挂载（@deepseek-ai/dsh-storage-domain）；五个 bg_* 工具没有它也能工作。
然后，在任意会话中，直接让模型去做 —— 或者直接调用这些工具：
background_agent "watch the repo for test failures and keep me posted" (label: test-watch)
bg_list
bg_message <agentId> "also check the snapshot tests now"
bg_stop <agentId>
安装与卸载
- git 渠道（最新
main）：dsh plugin --profile web add "github:PerryLink/dsh-background-agents#main"—— 已提交lib/，无需prepare或allowBuilds步骤。 - npm 渠道（已发布版本）：
dsh plugin --profile web add dsh-background-agents。 - tarball 渠道：在本仓库执行
pnpm pack，然后dsh plugin --profile web add ./dsh-background-agents-<version>.tgz。 - 卸载：
dsh plugin --profile web remove dsh-background-agents（或从 profile 补丁中删除该行）。
配置
每个可调项都是经过校验的 Schemastery Config 字段 —— 在 cordis.yml 中修改，绝不在代码中修改。仅 provider 为必填。
| 键 | 默认值 | 含义 |
|---|---|---|
provider |
(必填) | 用于可续聊启动（spawn）的 ctx.subagents provider 名称 |
autoReport |
true |
每个子代理轮次后在父会话中注入一条进度行 |
reportDelivery |
quiet |
quiet 将该行追加到下一次模型请求；wakeup 在父会话空闲时启动一个父轮次 |
reportThrottleMs |
15000 |
同一子代理两次进度注入之间的最小间隔 |
reportSummaryMaxChars |
300 |
注入进度行文本的硬上限（以省略号截断） |
resultMaxChars |
4000 |
bg_result 文本的硬上限（以省略号截断，标记 truncated） |
maxBackgroundAgents |
4 |
每个父会话未归档后台代理的硬上限 |
autoArchive |
true |
空闲归档开关；为 false 时清扫器绝不归档安静的代理 |
idleTimeoutMinutes |
120 |
安静的代理被归档前的空闲窗口（>= 1） |
idleSweepIntervalMs |
60000 |
归档清扫周期 |
maxLabelChars |
120 |
显示标签上限（以省略号截断） |
childProvider |
(继承) | 子代理模型请求的 provider 路由 |
childModel |
(继承) | 子代理模型请求的模型 id |
maxChildDepth |
(无) | 某次启动的 max_depth 参数的配置上限 |
allowedChildTools |
(无) | tool_filter 名称的允许列表；为空/缺失 = 无限制 |
maxRooms |
16 |
整个 profile 内团队房间的硬上限 |
maxMembersPerRoom |
8 |
每个房间成员的硬上限 |
maxRoomsPerMember |
4 |
一个成员会话可加入的房间数上限 |
busRetention |
200 |
每个房间保留的总线消息数 |
timelineRetention |
500 |
每个房间保留的时间线事件数 |
taskRetention |
50 |
每个房间保留的已完成任务数 |
maxMessageChars |
4000 |
单条房间消息文本的硬上限（超限直接拒绝，绝不截断） |
injectRoomBrief |
true |
向成员会话注入简短房间简介（加入 + 恢复时） |
roomOpenTimeoutMs |
15000 |
team_rooms 存储域打开的最长等待时间；超时后所有房间操作以 store-unavailable 明确失败，而不是永久挂起 |
allowUnmarkedFacts |
false |
强制在丢弃 ignorable 标记的宿主上写入事实事件（危险：未标记事件会让会话在其他宿主上无法恢复）；默认自动探测并跳过 |
工具与界面
| 界面 | 类型 | 说明 |
|---|---|---|
background_agent |
工具 | 启动一个持久的、可续聊的子代理（label、tool_filter、persona、max_depth） |
bg_message |
工具 | 按 agent id 向子代理投递后续轮次 |
bg_list |
工具 | 你的代理的状态（或用 recursive: true 查看后代树） |
bg_result |
工具 | 读取子代理最新的助手输出文本 |
bg_stop |
工具 | 请求中断当前轮次 |
/room |
命令 | create|join|leave|list|send|tasks|task add|assign|claim|done|delete |
room_list_rooms / room_post / room_read |
工具 | 消息总线：名册、发帖（广播/定向）、读取历史 |
room_list_tasks / room_create_task / room_claim_task |
工具 | 共享任务板 |
room_transfer_task / room_complete_task |
工具 | 交接（审批门控）与完成 |
backgroundAgents 投影 |
会话投影 | 由父日志折叠出的仪表盘行 |
teamRoom 投影 |
会话投影 | 由 team-room/fact 事件折叠出的共享时间线 |
| Web 侧栏面板 | 客户端 | 实时状态、跳转、消息、停止、结果预览 |
工作原理 —— 以及它为何能在重启后存活
一切都运行在官方子代理接缝之上：startContinuable、followup、interrupt、listChildren —— 该插件不执行任何自己的生命周期路由，从不接触另一个会话的 Agent，也从不杀死进程树（停止 = 请求中断，清理工作属于延续管理器）。
该插件通过一个结构化通道和一个模型可见通道写入每一个事实：
background-agents/fact结构化事实事件 —— 即注册 / 消息 / 停止 / 进度 / 已归档等事实，以仅日志记录的形式追加到父日志，并带上信封的ignorable: true标记；不认识该类型的读取器会跳过这些记录，而不是拒绝读取日志。Session.append早于该标记的宿主（迄今发布的所有 rc 版本，至0.1.0-rc.7—— 任何发布版都还未盖标记，未标记会话在更严格的构建上无法恢复）会在首次追加前被探测出来（peer 版本预检 + 返回信封探测），事实追加被跳过并发出一次性警告 —— 持久存储、通知与工具照常工作，投影降级为空事实折叠。tool/result回放元数据 —— 在结构化通道出现之前写入日志的相同事实（仅当某行没有结构化来源时才折叠）。- 注入的
user/message通知（模型可见），来源为{ kind: 'plugin', plugin: 'dsh-background-agents' }—— 即节流的进度行与归档通知（规范前缀[background-agent <id>] …）。 - 官方的
subagent-settled通知 —— 子代理持久化的 "settled"（已结束）事实。 - 团队房间遵循同样的纪律：每一条投递的房间消息都是成员自身日志中持久化的
user/message，共享时间线则以仅日志的team-room/fact事件镜像到team_rooms存储域。
backgroundAgents 投影折叠结构化通道并保留旧有的折叠结果；仪表盘值与 bg_list 事实在每次重新打开时重建，无需解析人类可读的通知文本。当目录本身不可用时，bg_list 会返回一个明确的 unrecoverable 标记 —— 它绝不凭空捏造一个空列表。
与内置子代理工具的关系
harness 核心自带它自己的子代理工具（subagent、send_message、interrupt_agent，以及子端的 report 工具）。本插件的 bg_* 工具是它们的会话级同伴；两者可以一起挂载：
| 内置工具 | 本插件 | 差异 |
|---|---|---|
subagent (backgroundMode: 'continuable') |
background_agent |
相同的 startContinuable 接缝；本插件额外提供每个子代理的 tool_filter/persona/max_depth 校验以及每会话上限 |
send_message |
bg_message |
相同的投递语义；bg_message 面向本会话的后台代理，并维护投影事实 |
interrupt_agent |
bg_stop |
相同的中断语义；bg_stop 还会记录一条结构化的停止事实 |
子端 report 工具 |
autoReport | 内置工具由子模型自己调用；本插件在每个子代理轮次之后自动注入节流的进度 |
核心工具缺少的是：bg_list、bg_result、空闲归档，以及按父会话折叠的面板投影。
不在范围内：定时触发（调度接缝已存在）、跨机器/远程代理，以及对官方子代理激活契约的任何改动。
这不是本插件
| 项目 | 它的作用 | 边界 |
|---|---|---|
| titanwings/dsh-automation | 在新代理会话中定时执行编码任务 | 它负责任务何时运行（调度）。本插件负责对单个长会话的交互式操控 —— 没有调度接缝，没有 cron。 |
| vlln/dsh-task-status | 后台 作业 的状态栏（进度 + 输出尾部） | 它显示工具级的作业。本插件创建并操控代理会话；它的仪表盘只是其中的一个面板，而非产品本身。 |
| YYTbit/dsh-plugin-agent-dashboard | 多代理仪表盘技能 | 面向展示。本插件的行是可操作的：跳转进子会话、发送消息、停止 —— 全都通过官方控制平面。 |
权限与数据
- 权限：workshop 清单声明
session:append、subagent:spawn与tools:register。 - 数据：团队房间位于
team_rooms存储域（SQLite 或 JSONL —— 零额外服务）；后台代理事实随父会话日志。无独立数据库，无网络。 - 会话日志：
background-agents/fact与team-room/fact事件在支持标记的宿主上以信封的ignorable: true标记追加（早于该标记的宿主会被探测出来，事实追加被跳过 —— 见allowUnmarkedFacts）；模型可见的进度行与房间投递是真实的user/message记录。
安全边界
- 仅使用官方接缝。 启动、消息与停止都是对
startContinuable/followup/interrupt的薄封装；停止是请求中断，绝不杀死进程。 tool_filter只会限制。 它从子代理的视野中移除工具 —— 绝不授予新工具；名称会按allowedChildTools进行校验。- 审批门控的交接。
room_transfer_task通过官方审批接缝路由，当没有 answerer 授权时以失败关闭。 - 模型可见 ⟺ 已落盘。 每一条投递的房间消息都是成员自身日志中持久化的
user/message；共享时间线以仅日志的team-room/fact事件镜像。 - 无调度，无跨机器代理。 子代理是该部署的进程内可续聊会话。
已知限制
- 团队房间需要存储域被组合；没有
@deepseek-ai/dsh-storage-domain时，/room命令与room_*工具会被禁用（五个bg_*工具仍可加载）。 provider必须指定一个具备可续聊能力的 provider（prepareContinuable）；缺失的 provider 会让background_agent一直失败，直到它出现。maxBackgroundAgents是会话每一个可续聊直接子代理共享的预算，包括由内置subagent工具启动的那些。- 一次性子代理绝不会被列出或接收消息 ——
bg_list只保留可续聊的行。 - 子代理是进程内的：调度接缝负责「何时」，本插件负责操控一场活跃的对话。
开发
pnpm install # 仅工具链；harness 包针对同级 checkout 解析
pnpm run typecheck # 严格 TS，node + client 程序
pnpm test # vitest：单元 + 端到端测试（真实子代理接缝、脚本化 LLM、jsdom 面板）
pnpm run build # lib/index.js（node 半侧）+ lib/client.js（web 客户端 bundle）
pnpm run gen-aliases # checkout 移动后重新映射 harness 包路径
一个无需密钥的端到端演示通过确定性的脚本化 LLM 驱动一个真实的父会话和一个后台子代理（无需 API key；dev/ 已被 gitignore —— 请根据你的 checkout 调整路径）：
$env:DSH_HOME = 'D:/deepseek-harness/Project/Plugins/dsh-background-agents/dev/dsh-home'
pnpm dsh --profile headless --patch dev/cordis.yml "【父会话】驱动后台 agent 演示"
主题
dsh, dsh-plugin, deepseek-harness, subagent, background-agent, background-agents, agent-dashboard, conversation-steering, team-rooms, multi-agent, message-bus, task-board, collaboration
贡献者
- @PerryLink —— 创建者与维护者：官方子代理接缝上的后台代理运行时、团队房间枢纽、Web UI 侧栏面板、会话投影、文档、CI/CD 与发布。
PerryLink DSH 插件家族
本项目是由 PerryLink 维护的 DeepSeek Harness 插件之一。如果这个对你有帮助，其他的很可能也会：
| 插件 | 一句话简介 |
|---|---|
| dsh-mcp-panel | 只读 MCP 运行时面板：/mcp 命令 + 带状态、工具与错误的设置标签页 |
| dsh-doublecheck | 工程纪律守卫：需求盘问、测试关卡、对抗性审查 |
| dsh-background-agents | 持久的后台子代理，带 Web UI 侧栏、消息传递与中断 |
| dsh-lsp-actions | 通过语言服务器提供 LSP 诊断、格式化、补全、代码操作与重命名 |
| dsh-output-styles | Claude Code outputStyles 等价的运行时样式切换 |
| dsh-checkpoint-rewind | Claude Code /rewind 等价功能：快照、会话分叉、一次性恢复 |
| dsh-permission-rules | Claude Code 风格的声明式 allow/deny/ask 权限规则，带审计 |
| dsh-auto-review | 在审批链上的第二模型自动审查，默认失败关闭 |
| dsh-memento | 审批门控的跨会话记忆：ctx.memory 接缝 + SQLite + memory 工具 |
| dsh-skill-pack-security | 安全审计技能包：密钥扫描、依赖与供应链审查 |
| dsh-session-pin | 在 Web 侧栏中固定会话，带持久化排序 |
| dsh-composer-history | Web 编写器的终端风格输入历史：方向键、Ctrl+R 搜索 |
| dsh-github | DSH 的 GitHub PR/issue 集成，每次写入都由审批门控 |
| dsh-plugin-guide | 作为按需代理技能的插件开发知识库 |
| dsh-claude-move | 将 Claude Code 会话、记忆、技能与 CLAUDE.md 迁移到 DSH |
许可证
Apache License 2.0 © 2026 dsh-background-agents contributors