PerryLink/dsh-background-agents

👥 dsh-background-agents
- 1024 商店渠道：先执行一次 npm i -g dsh1024，然后执行 dsh1024 plugin --profile web add dsh-background-agents（计入 deepseek1024.com 安装排名）。
Gitee

面向 DeepSeek Harness 的交互式长会话后台代理，以及持久化的多代理团队房间——启动一个持久的子代理，让它在你持续对话的同时继续工作。

实时引导对话，并跨会话协调团队；借助 harness 自有的存储，一切都可在重启后存活。

License
DSH plugin
dsh-doctor
Node
CI
Version
npm version
npm downloads

English · 简体中文 · Español · Português · हिन्दी

兼容性

宿主 0.1.2-alpha.2 及更高版本会对会话事件词汇表执行 fail-closed，因此本插件不再向其写入仅用于日志的事实事件（background-agents/fact、team-room/fact）：事实改走 logger/panel 通道，投影则退化为空折叠。较旧的 rc 系列（直至 0.1.1-rc.2）仍保持可忽略标记的纪律。客户端部分现在依托当前的客户端包（dsh-api-session-controller、dsh-client-web）以及当前的 subagent 远程接口（interruptByParent、带客户端生成的 requestId 的 prompt；旧的 history RPC 已移除——结果窥视改为读取子会话的 conversation 投影）。
0.1.2-rc.1（适配于 2026-09-04）：会话信封保留其可忽略字段，仅用于已存储日志的读取兼容性——Session.append 仍无法为其打上该标记（第三个参数是仅用于 surface 事件类型的 SurfaceIntent，绝不是 options 包），因此 fact-gate 行为保持不变。
0.1.3-alpha.1（适配于 2026-09-06）：CI 测试装置固定点移至 master 检出（d347e7039）——会话持久化服务的句柄接缝（open → read → close）。已发布的 0.1.2-rc.1 运行时早于 open()，因此冷启动的 bg_result 读取会对此接缝进行特性检测，并回退到 load()——两条线上的行为相同。已于 2026-09-06 针对 dsh-v0.1.3-alpha.1 master 检出进行验证（完整门禁链 + profile 安装冒烟测试）。
0.1.5-alpha.1（适配于 2026-09-09）：SessionHandleReadResult 现在返回 { eventState, events }，因此冷启动的 bg_result 读取会从句柄接缝中解构 .events（已发布的 load() 回退保持不变）。CI 测试装置固定点移至公共标签提交 5dda764ed3aa（本地检出领先 13 个基础设施提交，且从 CI 不可达），兼容性探针安装 alpha 线。对等依赖范围扩大为 >=0.1.2-rc.1 =0.1.5-alpha.1 =0.1.2-rc.1 =0.1.5-alpha.1 =24.0.0 |
| 平台 | 全部（宿主工具；可选的 Web 侧边栏面板和团队房间，通过存储域能力提供） |
| 模型 | 任意（子级继承父级的路由；childProvider/childModel 可覆盖） |

你将获得

dsh-background-agents 将 DSH 的即发即忘后台作业升级为两个协同层面：

1. 五个操控工具 —— background_agent 在官方子代理接缝上启动一个持久、可继续的子级（可选 tool_filter —— 仅移除工具，绝不授予新工具；persona；max_depth；childProvider/childModel 路由）。bg_message 投递后续轮次；bg_list 报告状态（或使用 parentId/depth 报告后代树）；bg_result 读取最新结果文本（推理回退标记为 textSource: 'reasoning'）；bg_stop 请求中断。
2. 进度与归档 —— autoReport 在每个子级轮次后注入一行节流的进度信息；reportDelivery: wakeup 在空闲时启动父级轮次。空闲清扫会归档安静的子级，bg_message 会将它们唤醒（autoArchive: false 则改为停放安静的观察者）。
3. 仪表盘投影 + Web 面板 — backgroundAgents 会话投影将父日志折叠为行；侧边栏面板显示实时状态、跳转、消息、停止和结果预览。一切都可以从持久日志中重建——无需单独的数据库。
4. 团队房间（v0.5.0+） — /room 命令族加上八个 room_ 工具构建持久的多智能体房间：成员（每个都是一个独立会话）、消息总线（定向/广播）、共享任务板和共享时间线——存储在 team_rooms 存储域中（SQLite 或 JSONL），并可在 DSH 重启后恢复。跨成员任务交接通过官方审批接缝进行路由。

快速开始

1. install the bundle into your profile
dsh plugin --profile web add "github:PerryLink/dsh-background-agents#main"

or from npm (published releases)
dsh plugin --profile web add dsh-background-agents

2. restart and verify the row
dsh --profile web --dump-config | grep -A4 'id: background-agents'

bundle 补丁携带插件行；provider 是必需的。该仓库提交了其构建输出（lib/），因此 git 安装无需构建步骤。该插件需要已挂载 subagent 主干（任何基于 @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  "also check the snapshot tests now"
bg_stop

安装与卸载

- 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-.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 | （继承） | 子模型请求的提供方路由 |
| childModel | （继承） | 子模型请求的模型 id |
| maxChildDepth | （无） | 对 start 的 max_depth 参数的配置上限 |
| allowedChildTools | （无） | tool_filter 名称的允许列表；为空/不存在 = 无限制 |
| maxRooms | 16 | 整个配置文件中团队房间的硬性上限 |
| maxMembersPerRoom | 8 | 每个房间成员的硬性上限 |
| maxRoomsPerMember | 4 | 一个成员会话可加入房间数的硬性上限 |
| busRetention | 200 | 每个房间保留的总线消息数 |
| timelineRetention | 500 | 每个房间保留的时间线事件数 |
| taskRetention | 50 | 每个房间保留的已完成任务数 |
| maxMessageChars | 4000 | 单条房间消息文本的硬性上限（超出即拒绝，绝不截断） |
| injectRoomBrief | true | 将简短房间简报注入成员会话（加入 + 恢复时） |
| roomOpenTimeoutMs | 15000 | team_rooms 存储域打开可花费的时间，超过后每个房间操作都会显式失败（store-unavailable）而不是挂起 |
| allowUnmarkedFacts | false | 在丢弃 ignorable 标记的主机上强制仅记录事实事件（危险：未标记的事实会使会话在其他地方无法恢复）；默认是检测并跳过 |
| observability | true | 每代理成本/状态可观测性开关：为每个子代理轮次捕获一条 metrics 事实（token、轮次墙钟时间、错误标志），并将其聚合到每一行的 metrics 总计中，供成本面板使用；false 禁用捕获（面板将指标渲染为不可用） |
| inbound.enabled | false | 为外部代理运行时（OpenAI Agents SDK / CrewAI）启用 stdio JSON-RPC 入站桥接。默认禁用（故障关闭）。 |
| inbound.command | （无） | 外部运行时启动命令；当启用且存在时，插件会启动它并监听以换行分隔的 JSON-RPC 通知。不存在/无法启动 = 桥接保持休眠（记录日志）。 |

工具与界面

| 界面 | 类型 | 说明 |
|---|---|---|
| background_agent | 工具 | 启动一个持久、可继续的子代理（label、tool_filter、persona、max_depth） |
| bg_message | 工具 | 通过代理 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 投影 | 会话投影 | 从父日志折叠出的仪表盘行，包括每个 agent 的 metrics 总计（token、回合墙钟时间、错误计数） |
| teamRoom 投影 | 会话投影 | 从 team-room/fact 事件折叠出的共享时间线 |
| Web 侧边栏面板 | 客户端 | 实时状态、跳转、消息、停止、结果速览、每个 agent 的成本/状态总计、JSON 导出/复制 |

工作原理——以及它为何能在重启后存活

一切都依托官方 subagent 接缝：startContinuable、followup、interrupt、listChildren——插件自身不执行任何生命周期路由，从不触碰另一个会话的 Agent，也从不杀死进程树（停止 = 请求中断，拆除工作属于 continuation manager）。

插件通过一个结构化通道和一个模型可见通道写入每一条事实：

- background-agents/fact 结构化事实事件——已注册 / 消息 / 停止 / 进度 / 已归档事实，以及每回合的 metrics 采样（token、回合墙钟时间、错误标志），作为仅日志记录追加到父日志，并带有信封的 ignorable: true 标记；不认识该类型的读取方会跳过这些记录，而不是拒绝整个日志。若宿主的 Session.append 早于该标记（所有已发布的 rc 系列直至 0.1.0-rc.8 和 0.1.1-rc.2，以及 0.1.2-rc 系列（该系列仅为存储日志读取兼容性保留信封字段，仍无法打上该标记），会静默丢弃它——该标记修复仅存在于 harness master 上——从而使未标记的会话在更严格的构建上无法恢复），则在首次追加前进行检测（先做对等版本预检，再探测返回的信封），并跳过事实追加，同时给出一次性警告——持久化存储、通知和工具继续工作，投影降级为空的事实折叠。
- tool/result 重放元数据——在结构化通道之前写入的日志中携带相同事实（仅当某行没有结构化来源时才折叠）。
- 注入的 user/message 通知（模型可见），来源为 { kind: 'plugin', plugin: 'dsh-background-agents' }——节流后的进度行和归档通知（规范前缀 [background-agent ] …）。
- 官方 subagent-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 标记（会检测不支持该标记的旧主机并跳过 fact 追加——参见 allowUnmarkedFacts）；模型可见的进度行和房间投递是真实的 user/message 记录。

安全边界

- 仅限官方接缝。 Start、message 和 stop 是 startContinuable / followup / interrupt 之上的轻量适配器；stop 请求中断，绝不杀死进程。
- tool_filter 仅做限制。 它从子会话的视图中移除工具——绝不授予新工具；名称会依据 allowedChildTools 进行校验。
- 审批门控的交接。 room_transfer_task 通过官方审批接缝路由，当没有应答者授予时按失败关闭处理。
- 模型可见 ⟺ 已记录。 每条投递的房间消息都是成员自身日志中持久的 user/message；共享时间线以仅记录形式的 team-room/fact 事件进行镜像。
- 无调度，无跨机器代理。 子会话是部署中进程本地的可继续会话。

跨生态入站（P2）

外部代理运行时——OpenAI Agents SDK、CrewAI 及类似框架——可以通过基于 stdio 的最小换行分隔 JSON-RPC 2.0 桥接发布到团队房间。这是一个 JSON-RPC 直连最小集，而非官方 ACP 线路协议：完整的 ACP 兼容性有待上游接缝。

通过两个 Config 字段启用它，并将 inbound.command 指向一个启动器，该启动器在 stdout 上每行发出一个 JSON 通知：

cordis.yml (plugin row)
inbound:
enabled: true
command: "python external_runtime.py --room "

该运行时会发出三种通知类型；method 是事件名称，params.name 是外部代理的显示名称：

{"jsonrpc":"2.0","method":"agent_started","params":{"name":"researcher","room":"","traceId":"t-1"}}
{"jsonrpc":"2.0","method":"agent_message","params":{"name":"researcher","room":"","traceId":"t-1","message":"found the failing test"}}
{"jsonrpc":"2.0","method":"agent_finished","params":{"name":"researcher","room":"","traceId":"t-1","status":"ok","usage":{"inputTokens":100,"outputTokens":40}}}

每种类型都映射到房间已有的界面：agent_started 打开任务板卡片，agent_message 发布到消息总线，agent_finished 完成卡片并发布结果。无效消息按失败关闭处理——它们会被丢弃，并写回一个 JSON-RPC 错误。外部运行时不是 DSH 会话，因此房间所有者的成员会话充当发送者；没有所有者成员的房间会丢弃该事件。Start 和 stop 由插件 fiber 通过 disposer 拥有；无法启动的 inbound.command 会降级为一条记录警告（桥接保持休眠，其他一切不受影响）。

已知限制
- 团队房间要求存储域已组合；没有 @deepseek-ai/dsh-storage-domain 时，/room 命令和 room_ 工具会被禁用（五个 bg_* 工具仍会加载）。
- provider 必须指定一个支持可延续（continuable）的提供者（prepareContinuable）；缺少提供者会导致 background_agent 失败，直到它出现。
- maxBackgroundAgents 是会话的每一个可延续直接子级共享的预算，包括由内置 subagent 工具启动的那些。
- 一次性子级永远不会被列出或发送消息——bg_list 只保留可延续的行。
- 子级是进程本地的：调度接缝负责“何时”，本插件负责引导一个实时对话。
- 成本指标是原始的 token/时长总计，而非货币：harness 不向插件或浏览器暴露任何按模型的定价表，因此成本面板和导出永远不会将 token 转换为金额（当适配器未报告 token 核算时，它们显示 —）。

开发

pnpm install        # 仅工具链；harness 包针对同级检出进行解析
pnpm run typecheck  # 严格 TS，node + client 程序
pnpm test           # vitest：单元 + 端到端测试（真实 subagent 接缝、脚本化 LLM、jsdom 面板）
pnpm run build      # lib/index.js（node 部分）+ lib/client.js（web 客户端打包）
pnpm run gen-aliases  # 检出移动后重新映射 harness 包路径

一个无需密钥的端到端演示通过确定性的脚本化 LLM 驱动真实的父会话和一个后台子级（无需 API 密钥；dev/ 已被 gitignore——请根据你的检出调整路径）：

$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 — 创建者与维护者：基于官方 subagent 接缝的后台 agent 运行时、团队房间中枢、Web UI 侧边栏面板、会话投影、文档、CI/CD 与发布。

PerryLink DSH 插件家族

本项目是由 PerryLink 维护的 40 个 DeepSeek Harness 插件之一。如果这个对你有帮助，其他的很可能也会：

| 插件 | 一句话简介 |
|---|---|
| dsh-auto-review | 审批链上的第二模型自动审查，默认故障关闭 | |
| dsh-budget | DeepSeek Harness 的成本治理：预算、碳排和延迟集于一个面板。 | |
| dsh-checkpoint-rewind | 等同于 Claude Code /rewind：快照、会话分叉、一次性恢复 | |
| dsh-claude-move | 将 Claude Code 会话、记忆、技能和 CLAUDE.md 迁移到 DSH | |
| dsh-click | 面向 DeepSeek Harness 的跨平台原生桌面控制——优先支持 Windows。 | |
| dsh-composer-history | 为 Web 输入框提供终端风格的输入历史：方向键、Ctrl+R 搜索 | |
| dsh-data-quality | 数据集质量检查与引用交叉核对（此处消费的可选数值桥接） | |
| dsh-defend | 面向 DeepSeek Harness 的提示注入、越狱和密钥泄露防御。 | |
| dsh-doublecheck | 工程纪律守卫：需求拷问、测试门禁、对抗性审查 | |
| dsh-draw | 面向 DeepSeek Harness 的统一静态图像生成路由。 | |
| dsh-fast | 面向 DeepSeek Harness 的只读性能诊断。 | |
| dsh-fund-research | 面向中国公募基金的确定性研究报告 | |
| dsh-github | 面向 DSH 的 GitHub PR/issue 集成，每次写入均需审批 | |
| dsh-industry-research | 行业研究编排，通过本插件的 ctx.researchReport.assemble 封存其交付物 | |
| dsh-library | 面向 DeepSeek Harness 的本地文档知识库。 | |
| dsh-local-ai | 面向 DeepSeek Harness 的本地模型（Ollama）集成。 | |
| dsh-lsp-actions | 通过语言服务器提供 LSP 诊断、格式化、补全、代码操作和重命名 | |
| dsh-mask | PII 脱敏中间件：在模型边界匿名化，在展示层还原 | |
| dsh-mcp-panel | 只读 MCP 运行时面板：/mcp 命令 + 设置标签页，含状态、工具和错误 | |
| dsh-memento | 需审批的跨会话记忆：ctx.memory 接缝 + SQLite + memory 工具 | |
| dsh-observe | 面向 DeepSeek Harness 的 OpenTelemetry 和 Langfuse 可观测性导出器。 | |
| dsh-output-styles | 等效于 Claude Code outputStyles 的运行时样式切换 | |
| dsh-permission-rules | Claude Code 风格的声明式允许/拒绝/询问权限规则，带审计 | |
| dsh-personal-directive | 带顶栏开关的个人指令注入器（框架版） |
| dsh-plugin-guide | 作为按需智能体技能提供的插件开发知识库 | |
| dsh-plugin-doctor | 面向 DSH 插件的零依赖静态 + 沙箱冒烟检测器 | |
| dsh-reach | 多渠道审批/提问桥接：微信/Telegram/飞书，会话控制台 |
| dsh-research-report | 可验证的研究报告引擎：内容寻址的证据账本与密封版本 | |
| dsh-score | 面向 DeepSeek Harness 插件的多维度质量评分。 | |
| dsh-session-pin | 在 Web 侧边栏中固定会话，并保持持久排序 | |
| dsh-session-sync | DeepSeek Harness 的跨设备会话同步——你的会话存储的专用 git 镜像。 | |
| dsh-skill-pack-security | 安全审计技能包：密钥扫描、依赖与供应链审查 | |
| dsh-talk | DeepSeek Harness 的语音优先会话循环：对它说话，听它回答。 | |
| dsh-test-drive | 面向 DeepSeek Harness 插件的隔离安装与冒烟测试试驾。 | |
| dsh-ticktick | TickTick/滴答清单任务桥接：会话头部面板 + 11 个工具 | |
| dsh-translate | 面向 DeepSeek Harness 的供应商参数转换与确定性 JSON 修复。 | |
| dsh-wechat | 微信 ↔ DSH 桥接（腾讯 iLink 机器人）：文本/图片/文件/语音，聊天内审批 | |
| dsh-autotier | 自动强/廉价模型层级路由，带确定性风险防护和 /tier 命令 | |
| dsh-catalog | PerryLink 系列的 DSH Desktop Market 标准目录源 | |
| dsh-cert-mcp | 暴露认证注册表的只读 MCP 服务器：等级、快照和五维证据 | |
| dsh-kit | 一键安装核心系列插件的入门包 | |
| dsh-plugin-certification | 带可复现检查等级和徽章的社区认证注册表 | |
| dsh-plugin-kit | PerryLink DSH 插件共享的零运行时依赖工具包 | |
| dsh-plugin-portal | 零依赖静态门户，将整个插件家族渲染为单个页面 | |
| dsh-plugin-upgrade-015 | 合并了 0.1.3-alpha.1 → 0.1.5-rc.1 升级走廊卡片以及一个零依赖接缝扫描器 | |
| dsh-team-rooms | 跨会话团队房间：共享消息总线、任务板和时线 | |

从 DSH Desktop Market 安装

所有 PerryLink 插件均可在内置的 DSH Desktop Market 中浏览：Market → Sources → add source → paste https://perrylink-dsh-catalog.perrylink.workers.dev/catalog-source.json → select it。安装仍需通过 Market 的 npm 身份验证以及你的确认。

许可证

Apache License 2.0 © 2026 dsh-background-agents contributors