dsh-expert-suite

Readme

# DSH 专家工坊 · dsh-expert-suite

<p align="center">
  <a href="https://www.npmjs.com/package/dsh-expert-suite"><img alt="npm" src="https://img.shields.io/npm/v/dsh-expert-suite"></a>
  <a href="https://www.npmjs.com/package/dsh-expert-suite"><img alt="license" src="https://img.shields.io/npm/l/dsh-expert-suite"></a>
  <img alt="host" src="https://img.shields.io/badge/DSH-0.2.0--rc.2-blue">
</p>

面向 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`；或用命令行：

```sh
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` 授权）。

## 快速上手

```text
# 单专家
/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）：

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

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

### 专家团

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

```json
{
  "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` 的插件行里配置：

```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](./LICENSE)