专家团 · dsh-expert-team

English | 中文

一句话组队交付：/team 做一个带登录的支付模块 —— 自动组建 12 角色专家团，走 澄清 → 调研 → 设计 → 规格评审 → 方案确认 → 实现 → 审查 → 测试 → 交付 的门控流水线， 实现者直接改你工作区的代码，全程留痕成可复核的工件。

装在 DeepSeek Harness 上的 dsh 插件：零运行时依赖、无构建步骤、无安装钩子。

12 角色	9 阶段	89 个测试文件	0 运行时依赖	0 构建步骤
各带人设 / toolFilter / maxDepth: 1	含 1 道硬门 + 1 道确认门	含 140 条变异目录与多组棘轮	dependencies: {}	无 bundler、无 prepare 钩子

零运行时依赖。推荐同时装 Hindsight（跨项目记忆）—— 见依赖与推荐插件。

为谁而做

给中小团队与个人接单者的一支「完整技术部」 —— 不用招人、不用攒团队：一句话拉起产品、架构、调研、 UI/UX、前后端、数据、安全、评审、测试、运维、文档这 12 个岗位，按 9 阶段门控流程交付， 实现者直接改你的代码库，全程留痕成可复核的工件。

_{图 1：为谁而做。三类对象（中小公司内部工具与产品迭代 · 个人接单 / 外包交付 · 独立开发者做完整项目）共用同一套做法：把 12 个技术部岗位编织进一条 9 阶段门控流水线。注意底部那条橙色带 —— 你（lead）与 12 个岗位不在同一层：你把关产品级与范围级决策，其余由团队推进。}

技术部岗位	角色	在这个流程里做什么
产品经理	pm	澄清需求、写 SPEC.md，把边界与禁止项前置
架构师	architect	方案与模块划分、依赖 DAG、AUTHORITY.md 单源
技术调研	researcher	取舍与出处，给结论不给流水账
UI/UX	ui	界面结构与交互
后端 / 前端	backend / frontend	只有实现者动代码，各改自己那份文件
数据	dba	schema / 迁移 / 查询
安全审计	sec	越权、注入、密钥与依赖风险
代码评审	reviewer	独立评审，不能自批自过
测试	qa	覆盖缺口、边界用例、验收判据
运维	devops	构建、发布、环境与配置
技术文档	docs	README / 手册 / 变更记录
你	lead	只拍板产品级与范围级决策，其余由团队推进

典型场景：中小公司内部工具与产品迭代 · 个人接单 / 外包交付 · 独立开发者做完整项目 · 任何"需要有人独立验证"的长任务。

_{一句诚实边界：它不是人类团队 —— 产品级与范围级决策仍由你拍板。}

_{图 2：9 阶段门控流水线。「规格评审」是硬门 —— SPEC.md 的「边界与禁止项」没填就不放行（lib/interception.js）；「方案确认」是默认开启的确认门（identity.keepPlanGate，可在设置里关掉）；「实现」阶段按依赖 DAG 并行扇出，多个实现者同时开工、各自只改自己那份文件。}

---

速览 / At a glance

项目	值
包名	@yangdcm/dsh-expert-team（npm 公开包）
仓库	https://github.com/yangdcm/dsh-expert-team
宿主	DeepSeek Harness ≥ 0.1.5-rc.1（web profile）
运行时依赖	无（dependencies: {}；lib/ 只 import 同目录文件与 Node 内建）
Node.js	≥ 20
License	MIT
安装（一行）	dsh plugin --profile web add @yangdcm/dsh-expert-team
上手（一行）	会话切到「专家团模式」→ /team 做一个带登录的支付模块
过程产物	<你的工作区>/team/<run-id>/（SPEC.md · PLAN.md · TASKS.json · REVIEW.md · TEST.md · SUMMARY.md …）
本机数据	$DSH_HOME/expert-team/（settings.json · LEARNINGS.md · session-runs.json）

dsh 插件 · DeepSeek Harness 多智能体（multi-agent）编排器：角色化 subagent 团队 · 依赖 DAG 并行 · 阶段门控 · 质量门禁 · 工件留痕。

给 LLM / 检索用的索引：llms.txt

30 秒看懂

$ /team 做一个带登录的支付模块
  │
  ├─ 澄清       pm           问清边界与验收口径        → SPEC.md（含「边界与禁止项」）
  ├─ 调研       researcher   证据与选型                → RESEARCH.md
  ├─ 设计       architect    模块拆分与依赖 DAG        → PLAN.md
  ├─ 规格评审   reviewer     ▣ 硬门：边界没填不放行     ← 不过不进下一步
  ├─ 方案确认   你           ▣ 确认门（默认开，可关）
  ├─ 实现       backend …    按依赖 DAG 并行扇出        → 直接改你工作区的代码
  ├─ 审查       sec·reviewer 独立评审（换模型交叉验证） → REVIEW.md
  ├─ 测试       qa           复现、覆盖、回归           → TEST.md
  └─ 交付       docs         收尾结论               → SUMMARY.md

  全程留痕：TASKS.json · ROSTER.json · STATE.json · AUTHORITY.md · RUN.log.md
  聚合快照：`METRICS.md` 在 **`team/` 根**（`/team learn` 产出；不是 run 目录模板）
  落盘位置：<你的工作区>/team/<run-id>/

_{上表是「阶段 → 谁在做 → 落哪个工件」的对应关系（阶段名出自 lib/vocab.js 的唯一真源，工件名取自包内模板与代码）。想连它正在做什么一起看，用 dsh web 里的浮层，或 /team canvas 打开全屏画布。}

为什么不是「一个 agent 硬做」

单个 agent 干大活有三个固定失败模式：上下文漂移（长任务越做越偏）、自己批自己（没人独立验证）、 返工不收敛（同一个问题来回改）。专家团用四件事对付它们：

机制	做法
角色分工	12 个角色各带独立人设、工具边界（toolFilter）、委派深度（maxDepth: 1）；产品/架构只读写计划工件，审查/安全只读，实现者才动代码
阶段门控	9 个阶段，每次交接走「结构化返回值 + 工件文件」双通道 —— 状态不靠聊天记录传递
质量门禁	状态机一致性由插件代码强制（不是提示词请求）：任务未完成不能标 completed、质量问题必须由 qa/reviewer 裁决、覆盖率缺口、超轮次返工 —— 违规实时显示在浮层并计入 /team status；写侧归属门禁：非负责人覆写他人工件在 write/edit 通道当场拒绝（挂在 tools/pre-execute，创建放行；持 bash 的角色仍可能绕过，见 lib/artifact-ownership.js 的诚实边界）
收敛与记账	每 run 记 token/耗时/首产物时间/收尾预算；/team learn 跨 run 蒸馏经验，并在下次开工前回注

看一眼它在干什么

_{图 3：全屏画布。看阶段条与进度、团队编制（谁在跑、用哪个模型）、以及 人 / 事 / 料 / 盘 四个视角 —— 比浮层更完整的一层视图。}

_{图 4：任务依赖图 —— 11 个任务按依赖 DAG 并行推进；7 个完成、4 个失败。失败会触发 repair 与独立复验（repair-1 → review-2 → repair-2 → review-3），直到通过或被如实判为需修订 —— 这就是「返工不收敛」的硬门禁在真实运行里的样子。}

_{图 5：门禁违规。看顶部那条横幅 —— 违规项与拒绝理由（例如"SPEC.md 的边界章节已进入 implement 但仍无任何一行填写"）由 lib/interception.js 挂在宿主 tools/post-execute 上当场判出后推出，不是提示词提醒。}

_{图 6：角色编制。看成员列表 —— 谁在跑、用哪个模型、当前在做什么；展开任一成员可看它的任务与产物。模型可按角色分别配置，异构模型用于交叉验证。}

_{图 7：阶段与工件。看阶段条与预览区 —— 当前阶段、已过阶段、以及该阶段真正写下的工件正文（工件是唯一真源，浮层只是它的视图）。}

_{图 8：设置。看官方 设置 →「专家团」 这一页 —— 18 个设置项、中文标签、改动即保存并即时生效（上限/轮次/档位门/振荡检测在进程内重算）；值存在宿主命名空间 expert-team，随插件市场的备份/恢复一起走。}

输入框正上方还有一条常驻状态条（client 槽 conversation.input.dock，id expert-team-subagents，order 200）—— 有子代理在跑时是琥珀色横幅「N 个子代理运行中」+ 最多 3 个角色名 + 一个跳动圆点，点击它直接打开团队面板；没有在跑时只剩一行暗灰字「无子代理在运行」，会话或状态尚未就绪时则完全不渲染（判据与页头徽章同一条：/state 的 agents[].activity === 'running'）。

它为什么可靠

• 状态机由插件代码强制，不由提示词请求。 lib/interception.js 把「台账契约」与「规格边界」两条规则搬到宿主的 tools/post-execute 瀑布上：重复 id / 环 / 自依赖当场顶回（HARD_GRAPH_CODES），SPEC 边界未填不许进实现 （SPEC_COMPLETE_PHASES）。规格沉默等于允许，那正是头号返工源。
• 零运行时依赖、零 devDependencies、无构建步骤、无 prepare/postinstall 钩子。 装完就是能跑的那份代码， 没有"安装时执行未知脚本"这一层。
• 89 个测试文件 + 140 条变异目录。 npm run test:all 无需 install 即可跑（CI 跑的就是它）。 ⚠️ 变异目录的实际保障范围（如实说）：mutation-catalog.test.mjs 在 CI 里校验的是目录形状 —— id 唯一、每个变异体的 find 串在目标文件里恰好命中一次、目标测试文件存在、条数与常量一致；变异体本身需要手动注入（把 find 换成 replace 再跑对应测试，看它是否变红），CI 目前不执行变异体。所以它是"防呆 + 防漂移"，不是"自动证明测试能抓错" —— 别把它读成后者。
• 多组棘轮（ratchet）测试，把"已经想清楚的规矩"钉住，防止悄悄退化： vocab-consistency（术语与角色标签单一真源）、scan-single-source（同一事实不许有两个家）、 write-bypass-ratchet（写侧不许绕过拦截）、settings-consumers（每个设置项都必须有消费者，白名单集合相等 ⇒ 只减不增）、 state-perf-guard（子会话计时零次读日志，性能回归即红）。
• 两种零要分得清。 "我不知道有什么"与"确实没有"不长成同一个样子：工具面收窄失败时区分 no-known-names / nothing-to-deny；/state 取不到时间戳时给 hasTimestamp: false，而不是用 0 冒充。
• 失败必须出声。 写侧越界、工件分叉、超轮次返工一律显式报错，不做静默截断 —— 静默失败是本仓最贵的 bug 类型。
• 性能有实测、也有护栏。 曾经 /state 会逐条全量读子会话日志：实测热态 7.1–9.8 s、冷态 283.6 s（75 个子会话）， 还会堵住整个 dsh web 的事件循环。1.3.5 改成只查表（实测 0.0026 ms/次、零次 readSession）， 修复后的端到端数字待实机复测；state-perf-guard.test.mjs 守着它不许回退。

安装 / Installation

要求

• dsh web（本包在 0.1.5-rc.1 上开发与验证；更早版本未经测试）
• Node.js ≥ 20
• 会话使用 「专家团模式」 preset 时，12 个角色工具（subagent_pm / subagent_architect / …）才可用； 否则自动退回通用 subagent（角色人设写进 prompt），功能不丢、只是少了配置层的边界保证

方式一：命令行（推荐）

dsh plugin --profile web add @yangdcm/dsh-expert-team
# 然后重启 dsh web，使新 bundle 进入组合

方式二：插件市场（收录尚未提交 ⇒ 目前可能搜不到）

若已被收录：dsh web → 设置 → 插件市场 → 搜索「专家团」→ 一键安装 → 刷新页面。

方式三：从源码（开发/未发布时）

cd ~/.dsh/profiles/web
# package.json：dependencies 加 "@yangdcm/dsh-expert-team": "file:<本包绝对路径>"
# package.json：dsh.profile.bundles 加 "@yangdcm/dsh-expert-team"
pnpm install && dsh web

skill 不落地：插件加载时就把 expert-team skill 作为运行时条目注册进宿主的 skill 注册表 （相对资源用 resourceBase 指回包内目录），所以 $DSH_HOME/skills/ 下不会出现副本 —— 卸载即干净。宿主没有 skill 注册表时才会回退为复制到 $DSH_HOME/skills/。

「专家团模式」preset 会复制到 $DSH_HOME/.agent-presets/（宿主没有"运行时加扫描根"的 API）， 但带版本戳：升级后整目录重铺，不会静默停在旧版本。插件加载时就会把它铺到位 —— 所以 /team uninstall 回收之后，重启 dsh web 即会自愈重铺，不需要手工救。

设置在哪改：设置 →「专家团」 —— 官方设置菜单里的一整页（settings.section 槽， id: expert-team、order: 50），与其它插件的设置同一入口、同一套面板 chrome。数据层是宿主命名空间 expert-team（宿主持有、随插件市场的备份与恢复一起走；改值后上限/轮次/档位门在进程内即时重算， 不必重启）。浮层里原来的「设」页签已移除 —— 同一份表单只在一处渲染。 诚实边界：默认班底（角色 id 数组）刻意不上宿主 schema（类型表达不可靠），由该页里的对应控件与 $DSH_HOME/expert-team/settings.json 负责；宿主没有 settings 服务时，全部设置退回该文件。

A 线开关：设置里的「门禁 → 收窄 lead 工具面」（gates.leadToolFace，默认 on）决定 是否把执行类工具（bash/write/edit/grep/glob）从 lead 手上拿走、交给角色子代理。 也可用 config.leadToolFace 或环境变量 DSH_EXPERT_TEAM_LEAD_TOOLFACE=off 关闭。

装上之后怎么用

1. 装完重启一次 dsh web：插件加载时会把「专家团模式」预设自动铺到 $DSH_HOME/.agent-presets/expert-team （带版本戳，升级会整目录重铺）—— 不需要手工创建预设。重启后预设选择器里就有「专家团模式」， 12 个角色化专家 subagent 工具也全部就位（可在 设置 → 插件 → 插件列表 → 会话插件 看到它们）。
2. 会话切到「专家团模式」，再 /team <一句话目标>。
3. 改设置走 设置 →「专家团」（值存在宿主命名空间 expert-team，随插件市场的备份/恢复一起走）。

排障：预设丢了、或被同名预设占住 —— 重启一次 dsh web 即自愈（插件加载会重铺），也可跑一次 /team <任务>。 细节见下面「排障」一节，其中包含那条最容易踩的坑：不要用 expert-team 这个 id 去「创建 preset」。

依赖与推荐插件 / Dependencies and recommended plugins

必需：无。本插件零运行时依赖（package.json 无 dependencies 字段；lib/ 只 import 同目录文件与 Node 内建， client.js 只 require('react')，由宿主提供），只要求宿主 DeepSeek Harness ≥ 0.1.5-rc.1（web profile）。 下面这些不装也能跑完整个团队流程，装上是为了让「跨项目记忆」「费用显示」这类事真正兑现。

推荐：Hindsight 长期记忆（跨项目 / 跨会话）

dsh plugin --profile web add @vectorize-io/hindsight-coding-agents

• 为什么：专家团的 skill 会在 clarify 前用 hindsight_search_knowledge_pages 召回其它项目落库的知识、 在 deliver 时用 hindsight_ingest_document 把本次经验落库（标题「专家团经验 · <runId>」/「项目知识 · <cwd 名>」）。
• 不装会怎样：不报错、团队照常交付 —— 只是这些工具不存在、模型调不到，跨项目记忆这一环不生效。 团队自身的跨 run 学习走本地文件（$DSH_HOME/expert-team/LEARNINGS.md、<工作区>/team/LEARNINGS.md），与 Hindsight 无关。
• 注意：Hindsight 的记忆配置在 dsh 之外（服务地址/令牌/库命名），装完还要配它自己。

可选：会话费用显示

dsh plugin --profile web add dsh-cost-meter

浮层「在用模型」那一行尾部写着「会话费用见 dsh-cost-meter」。不装只是少了费用视图，不影响任何团队功能。

只在你要用「插件市场」安装 / 备份恢复时

dsh plugin --profile web add dshmarket

dshmarket 不随宿主 dsh 发布；README 的「方式二：插件市场」需要先装它。

另外，活动流里的工具名有中文兜底：browser_* → 已操作浏览器、mcp_connector_* → 已操作连接器、 dsh_im_* → 已发文件，认不出的显示「已执行操作」（见 lib/command.js 的 TOOL_LABEL / TOOL_LABEL_FAMILIES）。 装了 dsh-browser / dsh-mcp-connector / @xmanrui/dsh-im 之后，活动流里出现的就是它们真实的工具名与参数： 纯显示，装了更清楚，不装不影响团队功能。

快速上手 / Quick start

命令	作用
/team <一句话目标>	一句话组队（一次性，自动组队并交付）
/team --persist <任务>	持久化活团队：成员可反复指挥、跨会话恢复
/team --one-shot <任务>	反向覆盖：即使默认设了持久化，这次也只跑一次
/team --no-code <任务>	只产出计划/评审/测试工件，不改代码
/team --code <任务>	反向覆盖：即使默认"只出工件"，这次也动代码
/team --confirm <任务>	先建 run、不自动派工，浮层点「执行」才开工
/team --tier <档位> <任务>	指定流程档位（快速档 / 标准档 / 严格档）
/team status	所有 run 的阶段、成员、模型计划、实时违规
/team models [<run>]	每个角色的成本 / 模型计划
/team canvas [<run>]	生成可视化团队画布（HTML）；--watch 实时刷新
/team learn	聚合日志 → METRICS.md + 蒸馏经验到 LEARNINGS.md
/team wait [<run>]	查看在飞任务进展（不阻塞）
/team resume <run-id>	跨会话恢复
/team uninstall	回收本插件铺到 $DSH_HOME 的副本（skill 走运行时注册，本就不落地）

完整命令（/team codeindex 代码索引、/team limit 配额、/team settle 冷启动清算……）见 /team help。

产物落在哪

• <你的工作区>/team/<run-id>/ —— SPEC / PLAN / TASKS / ROSTER / STATE / REVIEW / TEST / SUMMARY / RUN.log.md 等工件
• $DSH_HOME/expert-team/ —— 本机偏好与跨项目经验：settings.json、session-runs.json、LEARNINGS.md

常见问题 / FAQ

它到底是什么？ 一个装在本机 dsh 上的插件：/team <一句话目标> 会拉起一支 12 角色的 subagent 团队（产品 / 架构 / 调研 / UI / 前后端 / 数据 / 安全 / 评审 / 测试 / 运维 / 文档），按 9 阶段门控流程在你的工作区里交付，并把过程写成可复核的工件。

和"直接让一个 agent 硬做"有什么区别？ 针对三个固定失败模式：上下文漂移（阶段与工件双通道交接）、自己批自己（评审/测试是独立角色，qa/reviewer 裁决才算过）、返工不收敛（超轮次与未闭环被硬门禁拦下并如实报错）。详见为什么不是「一个 agent 硬做」。

必须再装别的插件吗？ 不必。本插件零运行时依赖；Hindsight（跨项目记忆）是推荐、dsh-cost-meter（费用视图）是可选，不装也能跑完整个流程 —— 见依赖与推荐插件。

支持哪些 dsh 版本？ engines.dsh: >=0.1.5-rc.1（开发与验证基线 0.1.5-rc.1）；更早版本未经测试。Node.js ≥ 20。

数据放在哪？ 工件在你的工作区 <workspace>/team/<run-id>/；本机偏好与跨项目经验在 $DSH_HOME/expert-team/（settings.json / LEARNINGS.md / session-runs.json）。

怎么卸载？ /team uninstall 回收它铺到 $DSH_HOME 的副本（skill 走运行时注册、本就不落地），再从命令行或插件市场移除插件。注意：$DSH_HOME/expert-team/ 下的 LEARNINGS.md 等是你的数据，卸载不会删。

会自己联网吗？ 不会主动联网：它只调用宿主提供的工具（文件、shell、子代理）；能不能联网取决于你给会话的工具面。

支持哪些模型？ 由宿主决定；本插件支持按角色分别配置模型（浮层里能看到每个成员用哪个模型），异构模型可用于交叉验证。

不切「专家团模式」preset 也能用吗？ 能。/team 是 host 平面命令，任何预设下都能跑；此时退回通用 subagent（角色人设写进 prompt），少的是配置层的边界保证（toolFilter / maxDepth: 1）。

浮层/画布打开很慢？ 见排障。1.3.5 起 /state 不再逐条全量读子会话日志；升级到 ≥ 1.3.5 后重启 dsh web 即可（1.3.13 起首屏走 ?section=summary，1.3.17 起重活也有界）。

角色子代理起不来、报 does not support reasoning effort？ 这是会话路由的模型没声明 reasoningEfforts 造成的，不是本插件的问题 —— 宿主在任何网络 I/O 之前就把"请求的 effort"与"该模型公布的 efforts"比对，不匹配即拒。修法：在 ~/.dsh/settings.yaml 的 agent-default-model 条目里给该模型补 reasoningEfforts（off/low/high/max），或把会话切到官方路由。注意：本 preset 里 8 个角色声明 high、4 个声明 low ⇒ 漏声明时任何带 effort 的角色都会被拒（"只有 low 失败"是假象：先派谁先报谁）。插件加载时会预检并告警一行（只告警、不阻断）。

记忆没生效：报 could not resize shared memory 或返回一张 HTML 防火墙页？ 这两类错误都发生在记忆后端（Hindsight）的服务端，不是本插件，也不要把它们混成一件事：

• … -> 500 {"detail":"could not resize shared memory segment … No space left on device"} ⇒ 服务端 PostgreSQL 分配共享内存失败：自托管最常见成因是容器 /dev/shm 只有 64 MB（用 --shm-size=1g 重启容器），也可能是磁盘/inode 满（df -h）或并行度太高；
• … -> 403 <!doctype html>…网站防火墙… ⇒ 服务端 WAF 拦下了 POST（返回的是HTML 防火墙页，不是 API 的 JSON 错误）⇒ 检查 WAF 是否拦了 /v1/ 的请求，或把该客户端 IP/UA 加入白名单。这不是 token 问题。

怎么看：设置 →「专家团」→「记忆后端（Hindsight）· 只读诊断」 会显示配置文件路径、部署形态（cloud/self-hosted/daemon）、服务地址、token 是否已配置（值不显示）、以及最近一条失败的分类与处理建议，并可按需探测一次连通性（连通 ≠ 鉴权成功：401/403 也算"可达"）。重启语义：改 serverMode/apiUrl 需重启 dsh web；只改 apiToken 免重启（401 时会重读）。本页只读，没有任何写入控件。

术语 / Glossary

角色（12）

中文	English	代码标识
产品	Product	pm
架构	Architect	architect
调研	Researcher	researcher
界面设计	UI/UX	ui
后端	Backend	backend
前端	Frontend	frontend
数据	DBA	dba
安全审计	Security	sec
评审	Reviewer	reviewer
测试	QA	qa
运维	DevOps	devops
文档	Docs	docs

阶段（9）：clarify 澄清 → research 调研 → design 设计 → spec-review 规格评审（硬门）→ 方案确认 方案确认（确认门，默认开、可关）→ implement 实现 → review 审查 → test 测试 → deliver 交付。（id 与中文名的唯一真源是 lib/vocab.js。）

主要工件：SPEC.md（规格与边界）· RESEARCH.md（调研）· PLAN.md（方案）· TASKS.json（任务台账）· ROSTER.json（编制）· STATE.json（状态）· AUTHORITY.md（写入权限单源）· REVIEW.md（评审）· TEST.md（测试）· SUMMARY.md（交付总结）· METRICS.md（成本与耗时：team/ 根的聚合快照，/team learn 产出）· RUN.log.md（运行日志）

谁写：每个工件由产出它的角色自己 write 进 <run-dir>/；lead 只读工件做门控与裁决（它没有 write 工具）。STATE.json 与 RUN.log.md 由运行时维护。

插件结构

cordis.patch.yml       唯一的组合贡献：一个 host 面的 /team 命令行
lib/command.js         /team 命令：解析 + 建工作区 + 装 skill + 触发团队 + 11 条浮层路由
lib/validate.js        状态机/质量门禁/容量上限的纯函数校验器
lib/interception.js    把「台账契约」「规格边界」搬到宿主 tools/post-execute 瀑布上（硬门在代码里）
lib/tier.js            流程档位词表的唯一真源
lib/vocab.js           阶段/角色/档位词表的唯一真源（host 与 client 两侧都从这里派生）
lib/metrics/           token 记账、首产物耗时、收尾预算、METRICS 渲染
lib/routes/            路由层共享件（统一 405/500/JSON 处理、本机来源守卫）
client.js              客户端浮层（模块加载器 bundle，仅 require('react')）
skills/expert-team/    编排「大脑」：SKILL.md + references/ + assets/templates/
presets/expert-team/   「专家团模式」preset：12 个角色 subagent 工具实例

编排协议几乎全在 skill 里而非代码里 —— 这样团队协议可以随 skill 更新，不必改包。

开发

npm run test:all        # 89 个测试文件，零依赖、无需 install（CI 跑的就是它）
npm run rename <新包名>  # fork 后改名：自动同步 13 个文件里 4 种包名写法
npm run check:name      # 检查占位包名残留

npm run gate（gate:preset / gate:sync / gate:evidence / gate:bypass / gate:mutation） 是开发机专用门禁：gate:sync 比对本机 $DSH_HOME 下的自举副本，gate:preset 借用本机 dsh 安装里插件自带的 Config schema（dsh 路径自动探测，可用 DSH_INSTALL 覆盖），因此不在 CI 里跑。

排障

设置菜单里找不到「专家团」那一页？ 确认版本 ≥ 1.3.0（dsh plugin --profile web add @yangdcm/dsh-expert-team 升级，或 npm view @yangdcm/dsh-expert-team version 看线上版本），然后重启 dsh web —— 1.3.0 之前没有这一页。

「专家团模式」显示成裸 id（expert-team）、会话里没有 12 个角色工具？ 说明 $DSH_HOME/.agent-presets/expert-team/ 里不是我们那份（被删过，或被一份同名预设占了）。按优先级修：

1. 跑一次 /team <任意小任务> —— 插件会用包内资产重铺一份带版本戳的（最省事；1.3.0 起插件加载时也会自动铺）；
2. 或从包内覆盖：cp -f <包路径>/presets/expert-team/{agent.cordis.yml,preset.yml} ~/.dsh/.agent-presets/expert-team/；
3. 不要用同一个 id 在「设置 → Agent 预设」里「创建 preset」——那只会得到你选的源的组合（例如标准模式）， 不是我们这份。

改完重启 dsh web（预设名册在启动时固化，刷新页面不够），再开新会话（预设只在会话创建时固定）。

浮层打开很慢 / 整个 dsh web 发卡？ 1.3.5 之前 /state 会逐条全量读子会话日志（实测热态 7–10 s、 冷态 283 s），并堵住事件循环。升级到 ≥ 1.3.5 后重启 dsh web 即可。

自定义预设 / Custom presets（想改专家团默认行为时）

• 创建：设置 → Agent 预设 → 用「创造模式」创作自定义预设（其机制是"复制一份既有预设"，产出落在 $DSH_HOME/.agent-presets/<id>/）。
• 要定制专家团，请以「专家团模式」为源、换一个你自己的 id（例如 my-team）：复制出来的目录天然带上 12 个角色工具与它的 skill 目录， 你的改动只写在 my-team/ 里。永远不要改 expert-team/ 里的文件 —— 那份是插件所有的，加载/升级会整目录重铺覆盖。
• 新建的预设可能要重启 dsh web 后才出现在选择器里（宿主名册在启动时读取）。

诚实边界

• 本机来源守卫已就位，但不是鉴权：11 条浮层路由统一校验 Host（挡 DNS rebinding）、 写方法的 Origin（挡跨站写入）、客户端地址（挡局域网），写方法还要求 application/json （挡 form / text-plain 这类不触发预检的"简单请求"）；/file 改走宿主 ctx.fs 策略， 读被策略拒绝时如实报 403 而不退回裸读。 残余风险如实说明：本地非浏览器进程本来就能自造任意请求头，而 dsh 插件没有鉴权模型 —— 所以别把 dsh web 暴露到不可信网络（宿主配置 host: 0.0.0.0 时，守卫只挡住"没有回环地址"的客户端）。
• 仅 web profile：浮层与路由依赖 webServer；无浮层时命令与工件仍然可用。
• preset 漂移：随包的「专家团模式」是官方 standard preset 的拷贝 + 角色工具， 宿主若调整内置 preset 结构，需要同步更新。升级插件时会按版本戳整目录重铺； /team uninstall 可回收它（用户自己写的同名 preset 不会被碰）。
• 会有意调用 git status --porcelain（只读） 用于工件新鲜度判断。
• 未接线项不装作可用：设置页的项要么真的生效，要么被标为「暂未生效」（由 INERT_SETTINGS 单一真源驱动）， 并由 settings-consumers.test.mjs 盯着 —— 目前该表为空。

兼容性

• engines.dsh: >=0.1.5-rc.1，声明在 package.json 的 dsh.compatibility（dshReleases 逐版本标注）； 插件市场按它判断"这个插件跟你的宿主兼不兼容"。
• Node.js ≥ 20。
• profile：web（见上「诚实边界」）。

License

MIT © yangdcm