前言¶

在 DeepSeek Harness（DSH）里做复杂任务时，主智能体经常需要把一段工作交给子智能体：换模型、换人设、收窄工具面，再把结果接回当前会话。内置的 subagent、subagent_fork 工具可以在每次调用时选路由，但「固定岗位」——例如专职审查、探索代码库、拆日志——更适合写成可版本化、可覆盖的配置，而不是每次在提示里重复说明。

dsh-roles-zeta 走另一条路：给主智能体挂载一个 delegate 工具，角色定义放在 $DSH_HOME/agents（默认 ~/.dsh/agents）下的 Markdown 文件里。调用时指定角色 id，子智能体的人格、模型路由、推理力度和工具白名单由该文件决定，底层仍走与内置 subagent 相同的 ctx.subagents 服务，因此 provider、委派深度、续跑与后台结算等行为与 Harness 原有机制一致。

这是什么¶

维护者 zeta987 在 GitHub 开源的 DSH 插件，社区目录分类为「工作流」。一句话定位：基于角色文件的子智能体委派——一个 delegate 工具覆盖整份角色清单。插件依赖 dsh 0.2.1-rc.2 或更高（委派需携带「无自带 persona / 工具过滤」的 Agent Preset 语义）；运行环境要求 Node >= 22.19.0（见 package.json）。当前 npm 包版本为 0.5.0，许可证 MIT。

内置 subagent 与 subagent_fork 不会被卸掉：模型仍可按次选路由；角色则在写文件时固定。每个角色以 Agent Preset 形式下发给子智能体——复制调用方 preset，再叠加上角色的 persona，并只保留其工具所需的插件。

核心功能¶

delegate 与内置子智能体的关系¶

主智能体可见的工具名默认为 delegate（可在配置里改成其他 toolName）。一次调用传入角色 id 与任务文本；插件解析对应 .md 中的 frontmatter 与正文，经 ctx.subagents 拉起子智能体。与手写 subagent 相比，差异在于路由与人设来自磁盘上的角色文件，且目录变更可在短 quiet period 后自动重载（watchRolesDir 默认为 true）。

随包自带的八个角色¶

首次加载时，插件会把包内角色种子写入 ~/.dsh/agents，并生成 .seeded.json 记录种子状态。默认文件名包括：

~/.dsh/agents
├── code-mapper-lite.md   explorer.md            log-distiller.md   triage.md
├── deep-coordinator.md   hypothesis-debate.md   reviewer.md        worker.md
└── .seeded.json

新会话里 delegate 的工具描述会列出当前 roster 中的角色。

Web 斜杠命令¶

每个已加载角色在 Web 输入框中对应一条斜杠命令（与 /plan、/goal 等并列）。输入 / 可浏览；例如 /reviewer look at lib/index.js 会排队一轮对话，要求主智能体以 reviewer 角色、前台方式调用 delegate，并把该句作为 task——委派过程仍表现为普通 tool call，留在 transcript 里。

增删改角色文件会重新注册命令；若 id 与其他插件命令冲突，该角色跳过斜杠注册（会打日志），仍可通过 delegate 使用。配置 commands: false 可关闭全部；commandPrefix: "r-" 则命令形如 /r-reviewer。

设置页 Role agents¶

路径：Settings → Role agents。列表展示各角色及 shipped / yours / edited 等标记；编辑器可改 id、when 行、route、effort、工具勾选（或「继承全部」加委派开关）、persona 正文。保存即写入 $DSH_HOME/agents/<id>.md，与手工编辑同一文件。

删除自建角色会删文件；删除随包角色会留下 disabled: true 的 stub，随包副本不再加载，并在「Disabled shipped roles」中列出，直到恢复。恢复单个或全部随包角色会把包内文件拷回（不会动你新增的角色）。

页面通过 /__dsh/roles-zeta/ 下的 JSON 路由提供，鉴权与 Web API 其余部分相同。settingsPage: false 时不挂载该页与相关 API。

角色文件格式¶

每个角色一个 Markdown 文件：YAML frontmatter 供机器读取，正文作为子智能体 persona 前缀。示例（摘自 README）：

---
id: reviewer
when: Deep read-only reviewer for correctness, regressions, edge cases, and missing tests.
route: deepseek-official/deepseek-flash
effort: high
allow: [read, glob, grep, web_search, web_fetch, skill]
---

Review like an owner.
Prioritize correctness, regressions, edge cases, and missing tests.

有 allow 列表时，只有列表里包含委派工具名才能继续委派；无列表时需 delegation: true 才能委派。

加载顺序与覆盖规则¶

两个根目录，后者覆盖前者：包内 roles/*.md，然后 $DSH_HOME/agents。你不改动的随包文件会随插件版本更新；改过一次则视为「你的」，不再被覆盖。删掉某个文件不会再次 seed，但包内副本仍会加载——要彻底去掉需 disabled stub 或设置页删除。自行新增的文件与随包角色并存。seedRolesDir: false 停止向你的目录写入种子；watchRolesDir: false 则仅在 compose 时读一次目录。

安装与启用¶

DSH 按 profile 隔离插件安装根，需要在每个要用该插件的 profile 里分别安装。官方 README 给出的命令如下：

dsh plugin --profile web add dsh-roles-zeta
# restart the host

亦支持 github:zeta987/dsh-roles-zeta 或 file:<path> 等形式。安装后需重启 host 才会加载。

插件不会自动升级。要锁定某一发行版，需显式指定版本（README 示例）：

dsh plugin --profile web add dsh-roles-zeta@0.4.0
# restart the host

update 仅在安装时 pnpm 写下的 ^0.x 范围内浮动；pnpm 11+ 对发布不足 24 小时的版本有 minimumReleaseAge 限制，显式 @版本 可立即安装。你改过的角色文件不会被覆盖；从未动过的随包文件会在下次加载时随包刷新。

宿主配置通过 Cordis patch 插入一行（节选）：

- insert:
    - id: roles-zeta
      name: dsh-roles-zeta
      config:
        provider: spawn
        toolName: delegate
        backgroundMode: continuable
        maxDepth: 2

此处不出现模型或路径：路由由角色文件里的 route 决定。该配置在 host 平面，因此每个 preset 下的智能体都能看到 delegate。

常用配置项默认值与含义（摘自 README）：

典型用法¶

1. 按上文命令在 web profile 安装并重启 host。
2. 打开新会话，确认工具列表中有 delegate，描述里列出八个默认角色（或你自定义后的 roster）。
3. 命令行式：在 Web 输入框输入 /reviewer <任务说明>，让主智能体前台委派 reviewer。
4. 工具调用式：在对话中让模型调用 delegate，参数指定 role 与 task（与斜杠命令最终效果一致，均进入 transcript）。
5. 定制角色：在 Settings → Role agents 编辑，或直接在 ~/.dsh/agents 新增 / 修改 .md；保存后等待目录 watcher 生效，无需重 compose profile（除非关闭了 watchRolesDir）。
6. 收窄工具面：为只读审查角色设置 allow: [read, glob, grep, ...]，避免子智能体挂载不必要的写操作或 shell 类工具。

适用场景与注意¶

适合谁：需要在 DSH Web 工作流里固定「岗位」——代码审查、仓库探索、日志提炼、分诊协调等——并希望 roster 可 Git 管理、可随包升级、可在 UI 或文件两种方式维护的团队或个人开发者。

与内置 subagent 如何选：临时换模型、一次性 fork 仍用内置工具；重复使用的 persona + route + 工具策略写成角色文件，用 delegate 或 /角色id 更省事。

安全与权限：插件与当前 dsh 进程同权运行；allow 只.mask 工具名，不能替代你对宿主环境与插件源码的审查。安装前请阅读 GitHub 仓库 源码与 MIT 许可证，确认 rolesDir 中的 Markdown 不会被不可信方写入（任意文件可定义子智能体行为）。

生态说明：DSH 采用「一切皆插件」的扩展方式；SkillHub 目录页 为社区收录，与 DeepSeek / 幻方无官方从属关系。

结尾¶

dsh-roles-zeta 把子智能体委派收成「一个工具 + 一文件夹角色」：与 Harness 内置 subagent 服务同轨，又通过 Markdown 与 Web 设置页让岗位可维护、可覆盖。若你已在用 DSH Web profile，可按 README 安装、从默认八个角色试起，再按项目需要增删 ~/.dsh/agents 下的角色文件。

• 社区目录：https://www.skillhub.cn/plugins/zeta987/dsh-roles-zeta
• 源码与文档：https://github.com/zeta987/dsh-roles-zeta