dsh-agents-md
English | 中文
一个给 dsh 用的插件，把 opencode 式的自定义 agent 带进你的会话。用 markdown 文件定义 agent——每个文件有自己的 system prompt 和模型——然后在对话里用 @名字 呼叫它：该 mention 会派发一个 subagent，按这个 agent 的指令和模型运行，agent 的回复作为上下文回到对话里。
工作原理
在 agents 目录（默认 ~/.dsh/agents/）里每个 agent 放一个文件。文件名就是 mention 名字；YAML frontmatter 放 description（显示在 @ 菜单和模型视角里）、可选的 provider 和可选的 model；正文就是这个 agent 的 system prompt。
---
description: 检查代码 bug 和边界情况
provider: google
model: gemini-3-flash-preview
---
你是一位资深代码评审员。检查正确性、边界情况和安全问题，逐条说明问题并给出修改建议。provider 和 model 就是 dsh 自己的模型路由用的名字——即 Models 页面（或 settings.yaml 里的 llm-* 配置）里配置的那套。两个都省略则继承父代理的路由。路由缺失或不存在会导致子代理第一次请求失败，所以请用你配置的 provider 实际支持的 id。
然后在任意会话里输入 @reviewer <你的请求>：
@菜单（和内置 subagent 引用共用一个触发键）列出你的 agent 和描述——选中后以@名字落进输入框。- 主模型从系统提示词里读到 roster，当请求提到某个 agent 时，由主模型自己调用
call_agent工具（传 agent 名和任务）。工具把该 agent 作为子代理跑在 subagent provider 上（默认spawn）：agent 正文作为子代理的 system prompt，frontmatter 里的provider/model作为子代理的路由，子代理继承父代理的工具集——agent 自己调工具干活。运行期间可以在 subagent 目录里看到它。 - 工具把 agent 的回复返回给主模型，主模型据此继续。
# 对话中输入
@reviewer 检查这段代码有没有 bug
# 主模型调用 call_agent(agent: "reviewer", prompt: "检查这段代码有没有 bug")
# 并从工具结果收到 agent 的回复。安装
# 从 npm 安装（需要 dsh >= 0.1.0-rc.6）
dsh plugin --profile web add @dingyi222666/dsh-agents-md
# 重启 dsh web，'@' agent 引用源会自动挂载
dsh web注意：
dsh plugin相当于给 web profile 加一个依赖。bundle 插件只有在完整包名出现在 profile 的dsh.profile.bundles列表后才会被加载（新版 dsh 会自动添加；旧版需手动加）；bundle patch 在下次启动时生效。- 用仓库源码启动的 CLI 时，参数要直接走 bin（
node --import tsx/esm apps/cli/src/bin.ts ...）。
配置
插件行接受常规的 cordis 配置键（在 profile 的 cordis.patch.yml 里 dsh-agents-md 行的 config 下设置，需要表达式时用 !!js）：
| 键 | 默认值 | 含义 |
|---|---|---|
agentsDir | ~/.dsh/agents | 存放 agent 定义（每个文件一个 *.md）的目录 |
provider | spawn | subagent provider 名；必须支持 persona 能力 |
maxDepth | 3 | 派发的 agent 的绝对委派深度上限（0 禁止派发） |
rosterPath | /dsh-agents-md/agents.json | 浏览器 roster 端点的 HTTP 路径 |
模型体验
- 新增 prompt 内容：一条 system-prompt section（顺序 95），列出已加载的 agent（
@name — description (路由)），提示模型在请求提到某个 agent 时调用call_agent。roster 为空时该 section 不渲染任何内容。 - 新增工具：
call_agent（仅在至少加载了一个 agent 时注册）——agent（roster 枚举）+prompt。是否派发由模型决定。 - Token 开销：roster section 与 agent 数量成正比；每次派发消耗子代理自己的一轮。
已知限制
- 派发与否由模型决定。 没有任何机制强制模型调用
call_agent；强模型可能直接回答@name请求而不派发。请把 roster 的 description 写清楚，帮助模型正确路由。 - 严格的
{{…}}persona 规则。 agent 正文会用作子代理的 persona，其中{{name}}是严格的 prompt 变量引用。正文含完整{{...}}组的文件会在加载时被跳过并记录原因（只有{{没有后续}}的字面文本没问题）。这与 dsh 自身的部署 persona 语义一致。 - frontmatter 只支持
description、provider和model。 opencode 的temperature、mode、tools字段不生效（dsh 的 subagent 请求没有 temperature 通道，工具限定是另一个独立能力）。 - 支持热重载。 agents 目录会被监听：增删改
*.md文件会自动重新注册call_agent工具的枚举并刷新 roster（约 200ms 防抖）——无需重启。修改已有 agent 的正文或路由，工具派发时立即用新定义。 - mention 边界只看名字字符。 字面名为
types的 agent 会被@types/react匹配到——请起有区分度的名字。
开发
yarn run build— 构建浏览器 bundle（lib/client.js）和 Node 半边（lib/index.js+lib/invariant.js）。yarn test— vitest 套件：agent 解析、mention 检测、派发编排、真实 apply 路径、浏览器@源。yarn typecheck— 对src和tests做严格 TypeScript 检查。