前言¶

在 DeepSeek Harness (DSH) 生态中，管理子智能体通常需要编写额外的配置或脚本。该插件解决了这个问题：它允许你直接使用本地 Markdown 文件定义智能体，并将它们注册为官方 DSH subagents。这提供了一个轻量级的方式来扩展 DSH 的能力，支持后台任务派发与双向追问。

核心功能¶

1. Markdown 文件即 Agent 定义
   在 ~/.dsh/agents/ 目录下创建一个 .md 文件，文件名即 Agent 名称。Frontmatter 定义元数据（如模型、思考强度），正文即 system prompt，修改后立即生效。

2. 断点续跑
   长任务在运行过程中若发生中断（报错、取消、限额或崩溃），再次调用时会自动从已保存的进度继续，无需从头开始。

3. 后台派发与双向追问
   支持将代理置于后台运行，主对话继续进行。通过 ask_agent 接口可以向后台代理发送追问并等待回复。

4. 开箱即用的预置 Agent
   插件内置 workhorse、oldfox 和 rubber-duck 三个预置 Agent。它们仅在首次启动且目录为空时植入，后续修改不会覆盖。

5. 基于官方 Spawn Provider
   所有自定义 Agent 均通过 DSH 官方的 spawn provider 启动，属于货真价实的 dsh subagent，继承官方原生的会话、持久化和双向通信能力。

6. 并发与深度控制
   支持通过配置项 maxActiveSubagents（同时活跃子代理上限，默认 8）和 maxDepth（委托嵌套深度上限，默认 1）来限制并发行为。

安装与启用¶

本插件依赖 DSH 版本 >= 0.1.7-rc.1（RC/稳定线；Alpha 线不再支持）。

1. 本地安装
   将仓库克隆到本地并在 Profile 中挂载：

    dsh plugin --profile tui add ~/github/dsh-subagent-registry

重启 DSH 后插件生效。

2. NPM 安装

    npm i @aiwayds/dsh-subagent-registry

在 Profile 配置中通过稳定 ID `dsh-subagent-registry` 加载，或使用 bundle patch 挂载。

典型用法¶

1. 主对话点名调用
   在对话中直接使用 Agent 名称：

    用 workhorse 把今天的发布清单整理成表格

底层调用 `use_agent(agent: "workhorse", prompt: "…")`。

2. 后台代理追问
   使用 ask_agent 对后台代理发送消息并等待回复：

    ask_agent(agent: "worker", message: "…")

3. 定义自定义 Agent
   在 ~/.dsh/agents/ 创建文件，配置 frontmatter：

    ---
    name: my-agent
    description: "一行简介"
    model: opencode-go/deepseek-flash
    thinking: high
    ---
    You are my-agent. 这段正文作为 system prompt。

4. 配置并发上限
   在 profile patch 中写入配置：

    subagent: {
      maxActiveSubagents: N,
      maxDepth: M
    }

适用场景与注意¶

• 适用人群：需要管理多个角色分工（如开发、审查、测试）的开发者，或希望用纯文本管理 AI 行为逻辑的用户。
• 卸载方式：dsh plugin --profile <name> remove @aiwayds/dsh-subagent-registry。卸载后 Agent 文件保留，但 use_agent / ask_agent 工具会消失。
• 降级处理：如果没有本插件，dsh-tui-pi 会优雅降级，只是失去自定义 Agent 派发能力。
• 依赖检查：使用前请确认当前 DSH 版本满足 >= 0.1.7-rc.1。

结尾¶

该插件通过引入本地 Markdown 文件机制，降低了 DSH 子代理的使用门槛，同时保持了与官方机制的兼容性。更多配置细节可参考文档。