| name | hermes-dsh-collab |
| description | 当你在 Hermes×dsh 多 agent 协作管线中担任 dsh 执行者（或为主控 Hermes 写派单任务书、判模型档位、定质量门）时使用——给出模型分层路由（Flash 常规/Pro 复杂/qwen 视觉）、spec 三铁律（Plan 先行/测试先行/范围声明）、git 唯一写者约定、质量门与写回机制的判断指引和踩坑规避。 |
| whenToUse | 收到任务书式派单要开工；写派单任务书；判断模型档位或视觉 patch；执行质量门验证、回炉或升级降级 |
Hermes×dsh 多 Agent 协作规范
本 skill 是判断指引，不是清单。 它把 style-museum 管线 14 天 30 commits 的实战规范提炼为可移植规则：Hermes 是唯一主控（写任务书 → 派单 → 独立验证质量门 → 统一 commit），dsh 是执行者（读任务书 → 按三铁律实现 → 报告，不 commit）。用它判断"这个阶段怎么派、怎么执行、怎么验收"，而不是机械过列表。
真源（Sources of truth）
以下文件是规范的活体，会持续更新——涉及对应主题时读它们，不要凭本 skill 复述：
- 实战观测卡（行为模式 + 踩坑，每阶段追加）：
/mnt/d/WorkSpace/Projects/style-museum/output/dsh-pipeline/observations.md
- spec 模板定稿：
/mnt/d/WorkSpace/Projects/style-museum/specs/template-v2.md；本 skill 的 references/spec-template.md 是它的通用化可复制件，两者冲突以项目模板为准
- 模型 patch 文件：
~/.dsh/profiles/headless/pro-model.patch.yml、~/.dsh/profiles/headless/vision-model.patch.yml（按路径引用，别把内容抄进任务书）
- 目标项目
AGENTS.md（硬约束，每次动手前必读）
何时使用
- 收到「任务书」形式的派单，要作为 dsh 执行者开工
- 要替 Hermes 主控写一份新派单任务书
- 要判断某阶段选哪档模型、要不要视觉 patch
- 要执行质量门验证、判定回炉、或决定升级降级
阻断项（违反 = 返工）
- git 唯一写者 = Hermes 主控。 dsh 执行者不做任何 git 写操作（commit/add/push/amend 全禁）。历史观测：任务书不写禁止条款时 dsh 会自行 commit——派单必须显式声明「不 commit」。
- 写回靠启动目录。 dsh 沙箱写权限 = 启动工作目录 + 平台临时根。派单命令必须是
cd <项目根> && dsh --profile headless "任务"；不在项目根启动，产物写不回项目。
- 三铁律缺一不派单：Plan 先行、测试先行、范围声明（file scoping）。
spec 三铁律（写任务书与执行都要守）
| 铁律 | 执行侧要求 | 判断要点 |
|---|
| Plan 先行 | 动手前读「必读」+ 目标文件，先输出改动清单（文件 × 改动点），再实现 | 清单是范围第一次自查：清单里出现范围外文件 = 立刻暴露 |
| 测试先行（TDD） | 先写/更新测试并确认失败（红），再实现到绿 | 没先红过的绿不可信——它可能什么都没测 |
| 范围声明 | 只允许改任务书列出的文件；禁止清单（数据真源/索引/未列文件）同等重要 | 主控 diff 审查按此对账；越界改动即使「顺手修好」也算违规 |
外加 不 commit（git 唯一写者条款，见阻断项）。完整可复制模板见 references/spec-template.md。
模型分层路由（按阶段复杂度选，不是按心情）
| 档位 | 适用 | 派单方式 |
|---|
| Flash（max 档） | 常规：单文件修改/参数/测试/简单 UI | 默认，无需 patch |
| Pro | 复杂：多文件重构/长内容提炼/复杂调试/视觉密集实现 | --patch ~/.dsh/profiles/headless/pro-model.patch.yml |
| qwen 视觉 | 看设计稿/截图对照/截图自检 | --patch ~/.dsh/profiles/headless/vision-model.patch.yml |
判断问句：改动横跨多文件且互相牵连？要读大量材料做长提炼？调试涉及跨层推理？——任一为是 → Pro；单文件局部改动 → Flash。拿不准就 Flash 试跑一轮：质量门全绿 + 零返工 = 组合成立；返工 = 升级 Pro 重派（实战已验证 Flash-max 处理常规阶段 3/3 通过，Pro 长提炼 1/1 通过并抓出跨文件系统性错误）。
patch 机制与三个坑（整段替换语义 / qwen 不配 reasoning 档 / vision patch 不改主模型）、验证姿势见 references/model-routing.md。
质量门（主控执行，不是 dsh 自报）
dsh 报告「完成」只是线索。主控必须独立验证四步：
- 测试全绿（后端 pytest / 前端 node --test）
- build 成功
git diff 审查：改动面与范围声明一致- 浏览器走查（涉及 UI）
原则：不信自报——用 curl 200 / 真浏览器点击 / 色值 diff 实测；数字声明必须可验证或带标签。命令细则与回炉流程见 references/quality-gates.md。
写回机制（一句话记住）
cd 项目根启动即写回，镜像/patch 交接全免。 dsh 的 workspace-write 沙箱以启动工作目录为写权限白名单，所以派单命令自带 cd。任何「产物在 /tmp、需 cp 回项目」的交接方式都是历史包袱。
常见踩坑（速览）
细节与对策在 references/pitfalls.md（唯一清单家），高频三条：
- patch 是整段替换语义——providers 必须写完整定义，只写局部字段 →
Provider is not configured
- qwen3.7-plus 不支持 reasoning: max——视觉 patch 不带推理档；vision patch 也不改主模型，只声明
input: [text, image] 让 read_image 自动路由
- 旧后端进程残留——主控用 terminal(background=true) 管理进程，不用 nohup；残留进程会让「测试全绿」验到旧代码
What NOT to do（专门节：挡住最容易犯的错）
- 不要 git commit / add / push / amend——你是执行者；主控验证全绿后统一提交（中文、单逻辑）
- 不要在任务书外自造范围——「顺手修一下」相邻文件 = 范围外偏差；发现需要修的，写进报告让主控决定
- 不要照抄 patch 文件内容进任务书——引用路径即可；抄错一份废一份，且 patch 语义本就易错
- 不要 resume 回炉——headless 无 resume（每次调用随机新 session）；失败由主控把原因写进新任务书重派
- 不要 nohup 起进程——用主控的 terminal(background=true) 管理
- 不要用 bundle 形态安装这个纯提示词 skill——
dsh plugin add 走 pnpm 依赖解析，对零代码资产纯增风险；复制目录到 skills root 即可（安装命令见项目 README.md）
- 不要复述真源——observations.md / spec 模板 / patch 文件是活的，用路径引用
- 不要相信 dsh 的「全绿」自报——质量门是主控的独立验证动作
自测（装完验证三件事）
- 出现在目录里：新开会话问「列出你的技能」应见
hermes-dsh-collab（没出现 = frontmatter 问题，查 kebab-case 与目录名一致）
- description 能触发：用真实场景提问（如「帮我写一份 dsh 派单任务书」）应触发加载
- 正文真的改变行为：对比加载前后——加载后应能复述三铁律与唯一写者约定，并拒绝 git commit
