专家工坊 LanYun417/dsh-expert-suite

DSH 专家工坊 · dsh-expert-suite

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

- 专家（Expert）：单角色切换——「人设 + 方法论 + 工具白名单」，让 AI 以特定领域专家身份执行任务，且白名单是进程内强约束；
- 专家团（Expert Team）：多智能体协作——团长把任务拆解、按需派工给成员子代理、整合交付，支持会话式（和团长对话）与批量（一次跑完）两种工作方式；
- 三种创建方式：手动创建（工具 / 面板表单）、文件导入（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": "把新产品从定义推到上线",json "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 的插件行里配置： yaml
- 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）。

开发 sh
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