dsh-agents-tool

目录驱动的全局专家 Agent 插件 —— DeepSeek Harness (dsh) 插件

npm 包名：@mikasomaka/dsh-custom-agents

目录驱动的全局专家 Agent 插件（DeepSeek Harness）：像 oh-my-pi 一样，用一个文件夹管理你的 AI 专家。

把 agent 定义写成 ~/.dsh/agents/*.md（markdown + YAML frontmatter），插件自动把每个文件注册成一个可调用的子代理工具 subagent_<name>。增删/修改文件即增删/修改工具，无需改配置、无需重启。

特性

| 需求 | 实现 | |---|---| | 永久存在 | 定义在 ~/.dsh/agents/*.md，装一次永久生效 | | 任何会话可用 | 工具注册在 host 全局层，所有 preset 的会话都可见 | | 工具式 | one-shot 每次调用生成全新子代理实例前台返回；continuable: true 可续聊多轮 | | 会话间隔离 | 每次调用独立实例，互不影响 | | 自由增删 | fs.watch 监听目录，加文件=加工具，删文件=删工具 | | 何时调用有指导 | 自动生成 agents-tool:usage 系统提示段 + 每工具的 description | | 不依赖 tool-subagent | 直接调用 ctx.subagents 服务（@deepseek-ai/dsh-subagent） |

安装

从 npm 安装（推荐）

dsh plugin --profile web add @mikasomaka/dsh-custom-agents

重启 DSH，新会话即可使用（说「让 shifu 排查这个报错」）。

本地源码开发安装

pnpm install
pnpm build
dsh plugin --profile web add .

# 播种示例 agents（可选）
mkdir -p ~/.dsh/agents
cp examples/agents/*.md ~/.dsh/agents/

Agent 文件格式

每个 *.md = YAML frontmatter + persona 正文（与 omp 的 task agent 同构）：

---
name: shifu                 # 必需；工具名 = subagent_shifu
description: 升级排查专家   # 必需；进工具描述与指导段
model: openai-codex/gpt-5.6-sol   # 可选；provider/model 或裸 model；省略=继承当前会话
thinking-level: high             # 可选；off/minimal/low/medium/high/xhigh/max；省略=模型/路由默认
continuable: true                # 可选；true=可续聊（多轮）；省略=one-shot（每次全新实例）
maxDepth: 1                # 可选；子代理再委派深度上限，默认 1
tools:                     # 可选；省略=全部工具；语义见下方表格
  deny: [edit, write]      #   扁平列表 = allow；对象 = allow/deny
---
（persona 正文，即子代理人设）

tools 语义：

| 写法 | 效果 | |---|---| | （不写 tools） | 子代理可用全部工具 | | tools: [read, grep] | 只允许列出的工具 | | tools: [] | 拒绝全部工具（空 allow 白名单） | | tools: {allow: [read]} | 只允许列出的工具 | | tools: {deny: [edit, write]} | 除列出的外全部可用 | | tools: {allow: []} | 拒绝全部工具（空 allow 白名单） |

工具名必须是当前 preset 里已注册的全局工具名，未知名会在子代理创建时报错。

one-shot vs continuable：

| | one-shot（默认） | continuable: true | |---|---|---| | 每次调用 | 全新子代理实例，前台返回结果 | 启动持久子代理，返回 subagentId | | 后续轮次 | 不可复用（只读记录） | send_message(subagent_id=...) 续聊，记住此前对话 | | 适合 | 一次性求助/快速审查 | 多轮审查/迭代（如 PR 多轮 review） | | 结果获取 | 直接返回 | 每轮完成收到结算通知（含最终消息） |

已忽略但保留兼容的 omp 字段：spawns（v1 不生效，见 Roadmap）。

配置（profile patch 覆盖）

- id: agents-tool
  config:
    agentsDir: ~/.dsh/agents     # agents 目录（~ 展开）
    provider: spawn              # 子代理提供方
    toolPrefix: subagent_        # 工具名前缀
    defaultMaxDepth: 1           # 文件未指定时的深度上限
    promptSectionOrder: 118      # 指导段顺序
    watchDebounceMs: 200         # 目录变更防抖

开发

pnpm typecheck
pnpm build

技术栈与 dsh-web-search 一致（tsdown + TypeScript，纯 host 插件）。

回退 / 卸载

dsh plugin --profile web remove @mikasomaka/dsh-custom-agents

Roadmap

• spawns 支持（agent 可再委派给指定 agent 工具，配合 maxDepth）
• 项目级 agents 目录（按工作区可见性，需 scope-aware 工具注册）
• run_in_background 可选