DSH 专家工坊 · dsh-expert-suite

面向 DSH（DeepSeek Harness）的专家与专家团插件：给 AI 加"角色与团队"两个协作维度——用一个领域专家的身份干活，或拉起一支多 Agent 团队按流程交付。

• 专家（Expert）：单角色切换——「人设 + 方法论 + 工具白名单」，让 AI 以特定领域专家身份执行任务，且白名单是进程内强约束；
• 专家团（Expert Team）：多 Agent 协作——团长把任务拆解、按需派工给成员子代理、整合交付，支持会话式（和团长对话）与批量（一次跑完）两种工作方式；
• 三种创建方式：手动创建（工具 / 面板表单）、文件导入（JSON / Markdown）、AI 生成（一句话描述 → 自动成稿入库）。

随包内置 8 位专家与 1 个「全栈交付团」，开箱即用。

特性

• 🧑‍💻 召唤专家：注入 persona + 工具白名单门禁，/expert data_analyst 即用；
• 👥 会话式专家团：进入团队和团长对话，打招呼就只是打招呼，有任务才按需派工；
• ⚙️ 批量交付：team_run 一次跑完整条流水线（serial / parallel / auto 三种执行模式 + step 干预）；
• 📥 多种创建方式：手动表单 / 文件导入（JSON、Markdown）/ AI 生成，均校验后入库；
• 🔒 进程内权限隔离：工具白名单由宿主 tools.guard() 单调拒绝，不是提示词提醒；
• 🎛️ 图形面板：设置页分栏 + 悬浮入口，浏览 / 创建 / 导入 / 详情 / 一键召唤与进入；
• 🧩 运行时 skill：每位专家 / 每个团队 / 使用说明都注册为 skill，AI 可随时加载；
• 🔌 零侵入降级：所有宿主接缝集中在适配层，服务缺席只降级、不影响宿主。

安装

从 npm 安装（推荐）：在 DSH 的「插件」页（设置 / 侧边栏）搜索安装 dsh-expert-suite；或用命令行：

dsh plugin add dsh-expert-suite

装完重启一次：插件加载时会把「专家模式」「专家团模式」两个预设铺到 $DSH_HOME/.agent-presets/，重启后出现在预设选择器里。

从源码开发安装：构建产物后引入（见下文「开发」）。

兼容性：对齐 DSH 0.2.0-rc.2 运行时与 @deepseek-ai/* rc peer；更早版本请按宿主安装时的 peer 提示处理（dsh plugin --profile <profile> allow-version 授权）。

快速上手

# 单专家
/expert-list                          # 浏览名册
/expert data_analyst                  # 召唤数据分析师（注入 persona + 工具白名单）
/expert data_analyst 帮我解读这份报表   # 召唤 + 立即发送第一句话
/expert-dismiss                       # 退出专家模式

# 专家团（会话式：进入团队，和团长对话）
/team-list                            # 浏览团队
/team fullstack_delivery              # 进入团队（打招呼、问能力、下任务都行）
/team fullstack_delivery 你好          # 进入团队并发送第一句话
# 之后正常对话：团长确认任务后才按需派工，打招呼就只是打招呼

# AI 创建（在会话里直接说）
请调用 expert_generate：我需要一个专门写技术文档的专家
请调用 team_generate：帮我组建一个能完成产品从设计到上线的团队

也可以全程用工具驱动：expert_list → expert_summon → expert_dismiss；团队侧 team_dispatch（团长按需派工）/ team_status / team_end，或 team_run（批量一次跑完）。

图形界面：设置 →「DSH 专家工坊」（或右下角悬浮按钮）打开浏览面板，可视化浏览 / 创建 / 导入专家与专家团。

核心概念

专家（Expert）

一个专家 = 一份「人设 + 方法论（persona）」+ 一个工具白名单（toolFilter）。召唤后，模型以该专家身份执行任务；白名单外的工具调用被当场拒绝（进程内强约束）。字段：

id / name / category / description / capabilities / expertise[] / exampleTasks[] / persona / model? / toolFilter[] / source

专家团（Expert Team）

一个团队 = 团长（lead）+ 若干成员（members），成员按 order 排序、各带 responsibility。字段：

id / name / description / executionMode(serial|parallel|auto) / interventionMode(auto|step) / members[{expertId, order, responsibility}] / leadPersona? / source

三种创建方式

方式	入口	说明
手动创建	面板「创建专家 / 创建专家团」、工具 expert_create / team_create	逐字段填写；团队成员可选现有专家或「自定义角色」现场定义
文件导入	面板「导入」、工具 expert_import / team_import	专家支持 JSON / Markdown；团队只支持 JSON
AI 生成	面板「AI 生成」、工具 expert_generate / team_generate	自然语言描述 → 生成器子代理成稿 → 校验后入库

使用指南

召唤与退出专家

• 召唤：/expert <id>，或面板点「召唤专家」；可带一句话 /expert <id> 消息 立即开工。
• 退出：/expert-dismiss，或状态条上的 ✕。
• 召唤成功后面板自动收起，右上角状态条显示当前专家 / 团队，可一键退出。

团队协作：会话式（默认）与批量（显式）

会话式（默认）——/team <团队id> 或面板「进入专家团」：注入团长契约，你和团长对话。打招呼、问团队能力就只是对话；有实际任务时团长先澄清目标、再用 team_dispatch 按需派工给成员（每次派工 = 一次 one-shot 子代理，等待交付后整合回复你），不会一上来跑全队。随时 team_status 看派工记录，team_end 结束并把各成员交付留档供总结。

批量（显式）——team_run 工具：给定自包含总目标，团长一次拆解、按执行模式跑完所有相关成员并整合总结。适合"现在就把整件事跑完"。

批量模式的执行模式（团队定义里的 executionMode）：

• serial：按 order 串行，后续成员能看到前序交付物；
• parallel：全部成员同一波次并行（受 maxParallelMembers 限制，默认 4），团长最后整合；
• auto：团长先做结构化规划（outputSchema 校验的波次计划），按波次执行；规划失败自动回退为按 order 串行并记入日志；
• interventionMode: step：每位成员（或每个并行波次）交付后暂停，用 team_message(action=continue) 放行。

成员的「连续性」由提示词承载（后续派工带上前序交付物全文），子代理会话不做跨派工驻留——这是 v1 的刻意取舍，换取只依赖宿主最稳定的 API 面。

权限与工具白名单

• 专家召唤：toolFilter 通过宿主 tools.guard()（单调拒绝，不可撤销）按 agent 生效；白名单外的工具调用被当场拒绝并说明原因。空白名单 = 不限制。
• 团队成员：每次派工都是一次 one-shot 子代理（ctx.subagents.start('spawn')），其 persona / toolFilter / maxDepth=1 在子代理创建窗口内落地，且不能继续向下委派。
• 团长：默认 leadToolFace: 'coordinator'——只协调不执行（拒绝 bash/pwsh/write/edit）；可在 Config 改为 full。
• 指定模型：专家定义里的 model 映射到子代理 agentOptions.model，需要宿主开启「子代理模型选择」opt-in，否则派工会报错——内置专家默认不指定模型（继承会话路由）。
• 跨平台工具名：toolFilter 里的工具名会按当前部署可见工具自动清洗（例如 Windows 上没有 bash、提供 pwsh），避免未知名导致 spawn 失败。

工具清单（19 个）

工具	说明
expert_list / expert_get	列出（支持 category 筛选）/ 获取专家完整定义
expert_create / expert_import / expert_delete	创建（zod 校验）/ 导入 / 删除（内置不可删）
expert_summon / expert_dismiss	召唤（注入 persona + 启用门禁）/ 退出
team_list / team_get / team_create / team_import / team_delete	团队同名管理操作
team_dispatch	（团长模式）按需派工一项子任务给成员，等待交付并返回
team_run	批量模式：teamId + 自包含 objective 一次跑完全队并整合，返回 runId
team_status	查看运行状态（成员进度、日志、总结）；缺省返回当前会话的活跃团队
team_message	action=send 与成员对话；action=continue 放行 step 模式暂停点
team_end	结束团队（缺省结束当前会话的活跃团队），返回各成员交付供总结
expert_generate / team_generate	自然语言 → AI 生成专家 / 从现有名册组团并入库（save=false 可只预览）

数据与存储

$DSH_HOME/expert-suite/
├── experts/<id>.json     用户创建 / 导入 / AI 生成的专家
└── teams/<id>.json       用户创建 / 导入 / AI 生成的专家团

内置资产随包提供；同 id 时用户目录版本优先。内置定义不可删除（返回 BUILTIN_READONLY）。

导入格式

专家

JSON：直接是完整定义对象；Markdown：YAML frontmatter + 正文（正文即 persona）：

---
id: tech_doc_writer
name: 技术文档专家
category: 写作
description: 面向开发者的技术文档写作
expertise: [技术写作, Vue, Vite]
exampleTasks:
  - 把这份源码注释整理成教程
toolFilter: [read, write, grep, glob]
capabilities: |-
  多行能力介绍……
---

你是资深技术文档工程师……（persona 正文）

专家团

只支持 JSON。成员通过 expertId 引用已存在的专家，所以先确保这些专家在名册里：

{
  "id": "launch_team",
  "name": "上线筹备组",
  "description": "把新产品从定义推到上线",
  "executionMode": "auto",
  "interventionMode": "auto",
  "members": [
    { "expertId": "product_manager", "order": 0,
      "responsibility": "产出需求定义与验收标准，交给设计师" },
    { "expertId": "ui_designer", "order": 1,
      "responsibility": "基于需求产出界面方案" },
    { "expertId": "code_reviewer", "order": 2,
      "responsibility": "评审可实现性与风险" }
  ],
  "leadPersona": "可选：自定义团长人设，留空用内置模板"
}

• executionMode：auto（推荐）/ serial / parallel；
• interventionMode：auto 全自动 / step 每位成员交付后暂停等你放行；
• members[].order：数字，决定默认执行顺序；members[].responsibility：该成员负责什么、产出交给谁；
• 名册里没有的角色，可在「创建专家团」表单用「+ 自定义角色」现场建，或先创建 / 导入专家；导入后自动注册运行时 skill，同 id 覆盖已有版本。

插件配置

在 cordis.yml 的插件行里配置：

- insert:
    - id: expert-suite
      name: 'dsh-expert-suite'
      config:
        dataDir: ''              # 缺省 $DSH_HOME/expert-suite
        layPresets: true         # 自动铺设两个预设
        maxParallelMembers: 4    # 波次内最大并行子代理数
        leadToolFace: 'coordinator'  # coordinator | full

架构与平台集成

宿主半边按官方契约实现：ctx.tools.register / ctx.tools.guard、ctx.subagents.start('spawn', …)、ctx.skills.register（运行时 skill）、ctx.commands.register、ctx.webServer.register（0.2.0 起为 webServer，0.1.5 线为 httpServer，两个名字都挂 inject 回调、谁先就绪注册谁）、agent.inject / agent.followup、ctx.agents.get / list。所有宿主接缝集中在 src/ports.ts（host）与 src/client/slots.ts（client），改宿主版本适配只动这两处。

Client 半边按官方模块加载契约实现（window.__ModuleLoader__.load({ id, factory }) 自注册、require('react') 取平台 React、导出 { apply, inject }），面板是 Vue 3 SFC 通过 React 宿主组件以「孤岛」挂载。入口为两个已核实的官方 slot：settings.section（设置页分栏）与 shell.overlay（右下角悬浮按钮）。面板数据与动作走 /expert-suite/* 路由（在 webserver 上注册；无 webserver 的 profile 自动降级为只读空态）。

两个值得知道的平台行为：

• 链接安装的包（link: / file:）内部 import 的 @deepseek-ai/* peer 会被宿主重定向到安装副本——本包 peerDependencies 必须与运行时真实 import 一一对应；
• 插件展示元数据：locale/{en,zh}.json 的 meta.title/description + package.json 的 icon（宿主 readPluginMeta 经 ESM 解析读取，exports 必须放出 ./locale/*.json）。

开发

pnpm install
pnpm run typecheck   # TypeScript 严格模式（零错误为合并门禁）
pnpm run build       # host（tsc → dist/）+ client（vite → dist/client.js）
pnpm publish         # 发布前会先跑 build

本地装进 DSH 调试：把本包以 link: / file: 引入 profile，或 pnpm dsh web --patch ./cordis.patch.yml。

项目结构

dsh-expert-suite/
├── package.json            # dsh.bundle / dsh.client 声明、exports、依赖
├── cordis.patch.yml        # bundle patch（宿主入口行）
├── tsconfig.json           # strict + NodeNext
├── vite.client.config.ts   # client 打包（CSS 注入 JS）
├── presets/                # 随包预设（专家模式 / 专家团模式）
│   ├── expert-mode/{preset.yml, agent.cordis.yml}
│   └── team-mode/{preset.yml, agent.cordis.yml}
└── src/
    ├── index.ts            # 宿主入口（apply：装配全部能力）
    ├── config.ts           # 插件 Config（Schemastery）
    ├── types.ts            # 数据模型（zod）+ 运行状态类型
    ├── deps.ts             # 工具层共享依赖与工具函数
    ├── ports.ts            # 平台适配层（spawn / 门禁 / persona 注入 / skill 注册）
    ├── builtin/            # 内置专家（8）与内置团队（1），构建期静态导入
    ├── storage/            # expert-store / team-store / markdown frontmatter 解析
    ├── tools/              # expert-tools / team-tools / ai-tools
    ├── orchestrator/       # team-runner（波次执行引擎）/ prompts（团长与生成器提示词）
    ├── skills.ts           # 运行时 skill 内容生成与全量注册
    ├── presets.ts          # 预设铺设（版本戳）
    ├── commands.ts         # 斜杠命令
    ├── routes.ts           # 面板数据路由（webserver 渐进增强）
    ├── help.ts             # 使用说明（面板弹窗与运行时 skill 同源）
    └── client/             # DSH 专家工坊面板（Vue 3 SFC 孤岛 + 官方模块加载契约 + slot 注册）

反馈与贡献

发现问题或有想法，欢迎提 issue / PR。贡献前请保证 pnpm run typecheck 零错误。

License

MIT