前言¶
在 DeepSeek Harness（DSH）里用内置的 subagent 工具做任务拆分，常见结果是：子代理带着父代理的人设去干窄任务、输出形态随模型心情变化；你只想读文件，子代理却握着 shell；要的是评审，它却改了代码。批量抽取和设计决策也往往挤在同一档、通常也是最贵的模型上。这些不是「提示词写得不够严」就能根治的——父身份、全量工具集和统一模型路由是结构自带的。
dsh-plugin-subagent-roster（维护者 121212165，分类：工作流）把系统提示、能力范围和模型档位从「请模型自觉」改成插件侧的结构约束，并按任务形态区分批量线与团队协作线。下面介绍它解决什么问题、如何安装，以及两种典型入口。
这是什么¶
一句话：面向 DSH 的受约束子代理名册——每个角色固定 persona（子系统提示）、toolFilter.allow 能力白名单、agentOptions 模型档位；父代理只多一个 delegate 工具，其 role 枚举覆盖整份名册，避免为二十个角色付二十套 schema。
仓库：121212165/dsh-plugin-subagent-roster（MIT，当前包版本 0.2.2）。社区目录页：SkillHub 插件条目。DSH 生态主张「一切皆插件」；SkillHub 等目录为社区站点，与 DeepSeek / 幻方无官方从属关系。
内置 subagent 的三类泄漏与对应机制¶
README 把失败模式归纳为三列约束，效果如下（机制均来自插件实现，非口头约定）：
| 约束 | 机制 | 效果 |
|---|---|---|
| 身份 | 委派时带上角色 persona，成为子代理的 persona-prefix |
身份由角色定义，不由父代理带入 |
| 能力 | 请求上的 toolFilter.allow |
例如评审角色没有写工具，无法改代码 |
| 模型 | 请求上的 agentOptions |
批量用便宜档，评审用够用档，协作用最强调档 |
| 深度 | maxDepth: 1，且过滤器不授予 subagent* |
角色子代理为叶子，避免递归扇出 |
两条任务线¶
名册按「工具形态」区分两类工作方式：
- 批量线（Bulk） — 每次调用处理一项，可并行；子代理完全没有工具。适合逐条字段抽取、逐条校验、逐条改写等。
- 团队线（Team） — 规划、构建、评审、检索、组装等岗位；各角色能力范围不同，且不能互相顶替。
内置二十个角色的说明见仓库文档 roles.en.md 与 roles.zh.md。
安装与启用¶
安装命令以 README 原文为准（<your-profile> 换成你的 profile 名，<owner> 为 GitHub 用户名 121212165）：
# 从 GitHub 安装（源码即产物，无需构建授权）
dsh plugin --profile <your-profile> add github:121212165/dsh-plugin-subagent-roster
# 或从本地目录安装
dsh plugin --profile <your-profile> add /path/to/dsh-plugin-subagent-roster
bundle 会写入一行插件配置；父代理获得上述单个 delegate 工具。可用下面命令确认是否出现 subagent-roster 行：
dsh --profile <name> --dump-config
环境要求（package.json / README）：DSH >=0.2.0-rc.2 <0.3.0，Node >=22.18；纯 ESM，无构建步骤。
插件市场索引（可选）：仓库提供 format: 1 官方索引格式，订阅地址：
https://121212165.github.io/dsh-plugin-subagent-roster/market/index.json
在 DSH 中先开启 Experimental plugins 下的「Custom plugin market」，再在 Plugins → Discover → Add index source 粘贴该 URL。索引中的版本来自 commit 固定 的 git 源（README 记载为 24f55f2），确认对话框里看到的源与安装内容一致。
安装前请自行阅读仓库源码与 MIT 许可证；插件随当前 dsh 进程权限运行，与本地 shell 对文件的访问能力同级。
插件配置与模型档位¶
插件 settings（cordis 中配置，字段以 README 为准）：
| 字段 | 默认 | 含义 |
|---|---|---|
mode |
advisory |
advisory 仅警告；strict 拒绝加载自相矛盾的名册 |
provider |
deepseek-official |
各 tier 解析所用的 provider |
allowedModels |
[] |
非空时，任一 tier 解析到列表外模型即违规 |
routingGuidance |
true |
是否把 bulk / team 路由说明注册进父代理提示 |
各 tier 的模型 id 从环境变量解析，同一包可服务多套部署：
| 变量 | 用途 |
|---|---|
ROSTER_PROVIDER |
四个 tier 共用的 provider 路由 |
ROSTER_BATCH_MODEL / ROSTER_BUILD_MODEL / ROSTER_REVIEW_MODEL / ROSTER_TEAM_MODEL |
各档模型 id |
ROSTER_BATCH_MAX_TOKENS 等 |
各档输出 token 上限 |
也可在 profile 的 cordis.patch.yml 里按 id 覆盖单行配置。
运维页与 roles.json¶
profile 运行期间，插件在本机提供运维页（默认端口由 pagePort 决定，0 表示关闭）：
http://127.0.0.1:4317/
可在页面上增删角色、调整顺序、气质、tier、能力范围，并直接编辑 persona（子代理系统提示）。保存后立即生效，无需重启；若新名册挂载失败会回滚到上一版。
角色数据位于 $DSH_HOME/subagent-roster/roles.json，首次启动从内置二十角色种子生成，也支持手改。保存时整表校验：id 为 kebab-case、tier / capability / line 取值合法、角色不变量（例如评审不能带写能力）等；校验失败不会覆盖文件。
安全注意：页面无认证，仅绑定 127.0.0.1；不要暴露到其他网卡。它具备与本地 shell 相当的文件权限。
典型用法¶
1. 在对话里用 delegate¶
父代理通过唯一的 delegate 工具选择 role 枚举中的角色委派。具体角色能力以 roles.json 与文档为准；routingGuidance 为 true 时，父提示中会包含 bulk / team 路由说明。
2. 确定性批量入口（roster-fanout）¶
README 记载：让父模型自行决定「要不要委派」在免费模型上不可靠（见仓库 test-report.md §3）。批量场景可把决策移到入口脚本，按条目数量驱动：
node bin/roster-fanout.mjs \
--profile <your-profile> \
--role batch-exact \
--items-file items.json \
--contract 'one JSON object {"text": <the item>}' \
--expect-json \
--concurrency 3 \
--out results.jsonl
要点：
- N 条输入对应 N 次子角色调用，形状由调用方式决定，不依赖父模型临场判断。
- 每条结果从子代理的
tool_result事件读取，不用父代理转述。 --expect-json校验契约；子代理报错、无返回或 JSON 非法则该条失败。- 任一条失败则进程非零退出，便于脚本或 CI 门禁。
契约由 --expect-json 强制执行，契约文案在子任务内部下发（子代理在任务外看不到）。README 称在最便宜 bulk tier 上测得 8/8 合规；失败即失败项，不会用散文冒充成功。
（若已全局安装插件，也可使用包内 bin 名 roster-fanout，见 package.json。）
验证与延伸阅读¶
仓库自带无模型调用的单元测试与可选 bench：
npm test # README：18 个单元测试
node bench/run.mjs --repeat 1 # 需本地 OpenAI 兼容网关
bench 结论来自网关请求日志（实际 persona、模型是否等于 tier、工具数量是否等于角色授权、负例是否未动工作区等），而非仅看回答文本。
设计说明、测试报告与评审文档：docs/design.md、docs/test-report.md、docs/review.md。
适用场景与注意¶
更适合：需要把「评审只读」「批量无工具」「岗位用不同模型」写进结构而非提示词的团队；有 CI / 脚本门禁的批量 JSON 抽取或校验；希望通过运维页或 roles.json 自定义名册的 DSH 用户。
务必注意：
- 插件以当前 DSH 进程权限运行；安装前检查源码与 MIT 许可证。
- 运维页等同本机高权限配置入口，勿对公网暴露。
- 版本与 DSH 处于
0.2.xRC 区间，升级 DSH 时需对照 README 的 compatibility 范围。
结尾¶
dsh-plugin-subagent-roster 把子代理委派里的身份、能力与模型三件事钉在角色名册与 delegate / roster-fanout 入口上，用 bulk 与 team 两种工具形态区分批量项工作与多角色协作。若要进一步了解参数与角色表，可从 GitHub 仓库 与 SkillHub 目录页 入手。
