dsh-lead-mode 0.1.2 → 0.1.4

package/README.md

@@ -34,7 +34,18 @@ It is not tied to the preset. Any session can load it, two ways:
 - The model loads it when it judges the task needs it (the skill is marked model-invocable)
 - You run `/skill lead-mode` yourself
 
-It covers: agreeing on the goal before starting, making a delegation self-contained, keeping write scopes disjoint, the list/get/claim/complete flow for shared tasks, the rules for waiting on teammates, and doing the final verification yourself.
+It covers: agreeing on the goal before starting, making a delegation self-contained, keeping write scopes disjoint, the list/get/claim/complete flow for shared tasks, how to wait on teammates, where a teammate's model comes from, and doing the final verification yourself.
+
+Two of those facts only show up when you read the runtime source:
+
+| Fact | Why it matters |
+|---|---|
+| A teammate settling notifies you automatically, carrying its closing message | Finish your turn after delegating; you do not need to sit and watch |
+| A task change does not wake an idle Lead | Do not count on "it marked the task complete, so I know"; that path only wakes a caller currently inside `wait_agent` |
+
+So the skill's default is: finish your turn after delegating and let the notification wake you (the user sees progress immediately), and use one `wait_agent` only when the current turn cannot continue without the result. Never loop `wait_agent`, and never poll with repeated `list_agents`.
+
+Tell the teammate to put the **deliverable in its closing message** — that message is what comes back to you with the notification.
 
 ### 3. The dependency self-check command
 

package/README.zh-CN.md

@@ -34,7 +34,18 @@
 - 模型判断需要时自己加载（skill 标记为模型可调用）
 - 你直接敲 `/skill lead-mode`
 
-覆盖这些内容：开工前对齐目标、派活必须自包含、写作用域不重叠、共享任务的 list/get/claim/complete 流程、等 teammate 的规矩、最终验证自己做。
+覆盖这些内容：开工前对齐目标、派活必须自包含、写作用域不重叠、共享任务的 list/get/claim/complete 流程、怎么等 teammate、teammate 的模型从哪来、最终验证自己做。
+
+其中两条是读源码才确认的，容易踩：
+
+| 事实 | 为什么重要 |
+|---|---|
+| teammate 收工会自动通知你，通知里带它收尾那条消息 | 派完活结束回合就够，不用盯着等 |
+| task 变更不会唤醒空闲的 Lead | 别指望「它把 task 标 complete 了我就知道了」，那条路只唤醒正在 `wait_agent` 的调用方 |
+
+所以 skill 的默认建议是：派完活就结束回合等通知（用户立刻看到进展），只有本回合内就必须拿到结果时才用一次 `wait_agent`。不要 `wait_agent` 套循环，也不要反复 `list_agents` 轮询。
+
+派活 prompt 里要要求 teammate **把交付物写进收尾那条消息**——那条消息会随通知回到你手上。
 
 ### 三、依赖自检命令
 

package/cordis.patch.yml

@@ -50,9 +50,13 @@
                 有这些工具，就按 Lead 工作法干活：
 
                 - 派活自包含。teammate 看不到你的上下文，把目标、约束、验收标准、已知失败、绝对路径都写进 prompt。
+                - 要求它收尾那条消息写清交付物。它收工时那条消息会随通知回到你手上。
                 - 写作用域不重叠。一人一块文件。分不开的活排成依赖。
-                - 共享任务走 list、get、claim（带 revision）、干、complete。
-                - 等齐必需的 teammate 再给最终答复。等之前先 list_agents 确认有人 running。
+                - 共享任务走 list、get、claim（带 revision）、干、complete。task 只是账本，不是唤醒通道。
+                - 等活就结束回合等通知：teammate 收工、或给你发消息，都会唤醒你。task 变更只唤醒正在 wait_agent 的调用方，不会唤醒空闲的你。
+                - 不要用 wait_agent 套循环，也不要反复 list_agents 轮询。只有本回合内就必须拿到结果时才等一次。
+                - 等齐必需的 teammate 再给最终答复。
+                - teammate 继承你的模型，spawn_teammate 没法单独指定模型。
                 - 最终验证自己做：跑测试、看 diff、核数字。不要只信回报。
           - id: agent-instructions
             name: '@deepseek-ai/dsh-agent-instructions'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-lead-mode",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Lead mode for DSH: an agent preset, a working-method skill, a dependency self-check, and two reminders that tell you to enable the official Agent Teams. | 给 DSH 加 Lead 模式：预设、skill、依赖自检、两条前置提醒。",
   "type": "module",
   "main": "lib/index.js",

package/skills/lead-mode/SKILL.md

@@ -31,18 +31,79 @@ dsh plugin --profile <你的 profile 名> add @deepseek-ai/dsh-experimental-agen
 
 目标或指令有疑问先问用户。别自己挑一个解释就开始干。
 
-## 派活必须自包含
+## 等通知，别轮询
 
-teammate 看不到你的上下文。它能看到的只有你写的那段 prompt。
+teammate 干完你**会被唤醒**，不用自己盯着。
 
-派活时把这些写全：
+| 事件 | 唤醒空闲的你吗 | 带回什么 |
+|---|---|---|
+| teammate 一轮干完、没有新消息 | 会 | 它收尾那条消息 |
+| teammate 主动 `send_message` 给你 | 会 | 那条消息 |
+| task 被 claim 或 complete | **不会** | 只唤醒正在 `wait_agent` 的调用方 |
+
+所以默认这么做：**派完活就结束回合。** 把「派了谁、等什么」写清楚，然后收工。用户立刻看到进展，你不空转。teammate 收工时你被唤醒，接着干。
+
+`wait_agent` 只在「本回合内就必须拿到结果才能继续」时用一次。它的好处是 task 变更也能唤醒它。默认等 30 秒，上限 1 小时。
+
+禁止这两件事：
+
+- 用 `wait_agent` 套循环
+- 反复 `list_agents` 轮询
+
+`list_agents` 只用来回答「谁在跑、谁卡住了」，不用来等。
+
+`wait_agent` 返回 `noProgress` 不是错误，是告诉你没人在跑，该换手段。
+
+## 派活的四个参数
+
+`spawn_teammate` 只有 `name`、`description`、`prompt`、`context` 四个参数。
+
+| 参数 | 要点 |
+|---|---|
+| `name` | 小写连字符。**永久，不可复用**，创建失败的名字也占着 |
+| `description` | 一行职责，给用户看，也给你后面对账 |
+| `prompt` | 全部指令。teammate 只看到这一段 |
+| `context` | `fresh`（默认）看不到你的历史；`fork` 继承你已完成的回合 |
+
+`context` 怎么挑：
+
+- **绝大多数用 `fresh`。** 活是自包含的，把上下文写进 prompt 就够。
+- 只有当活依赖你已经掌握、又写不进 prompt 的东西时，才用 `fork`。
+
+取名字前先 `list_agents` 看一眼，别撞已占用的名字。
+
+## prompt 怎么写
+
+teammate 看不到你的上下文。它能看到的只有 `prompt`。
+
+把这些写全：
 
 - 目标、约束、验收标准
 - 已知的失败现象和报错原文
 - 相关文件路径，用绝对路径
 - 环境坑，比如本机 `diff` 是坏的要用 `/usr/bin/diff`
 
-派活 prompt 里写「按刚才说的做」等于没派。它不知道「刚才」。
+写「按刚才说的做」等于没派。它不知道「刚才」。
+
+### 收尾那条消息就是交付物
+
+teammate 收工时，它**最后那条消息**会随通知回到你手上，格式是「Its closing message:」加正文。
+
+所以派活时直接要求它收尾写清：
+
+```
+收尾那条消息写四块：结论 / 文件清单 / 验收输出 / 偏离规格的地方。
+```
+
+这比你额外要求一次 `send_message` 省事，而且是你默认拿得到的东西。
+
+需要**中途**进度（干到一半问一句、或者要它先确认再继续）时，才另外要求它 `send_message` 给你。
+
+### 收尾消息可能被省掉
+
+如果 teammate 在收工前刚给你发过 `send_message`，通知里不会重复它的收尾正文，而是写「It sent you a message just before finishing, so its closing message is omitted.」。
+
+也就是说：你要么拿到收尾消息，要么拿到它发的那条，不会两个都没。
 
 ## 写作用域不重叠
 
@@ -52,6 +113,8 @@ teammate 看不到你的上下文。它能看到的只有你写的那段 prompt
 
 写作用域有重叠时，在 task 描述里写明重叠在哪、谁先谁后。别指望 teammate 自己协调。
 
+作用域只是提示，不是锁。bash、格式化工具、代码生成器都绕开文件版本检查，所以派完活要自己看最终 diff。
+
 ## 共享任务流程
 
 每个活都是一个共享任务。流程固定：
@@ -66,13 +129,35 @@ teammate 看不到你的上下文。它能看到的只有你写的那段 prompt
 
 task 描述就是完整规格。规格写细一点，teammate 少问一轮。
 
-## 等 teammate 的规矩
+task 是给人看的账本，不是唤醒通道。别指望「它把 task 标 complete 了我就知道了」。
+
+## teammate 用什么模型
+
+**不能单独指定。** `spawn_teammate` 没有 model 或 provider 参数。
+
+teammate 继承你（Lead）在 spawn 那一刻的 provider 和 model。想换只有两条路：
+
+| 想要什么 | 怎么做 |
+|---|---|
+| 整队换模型 | 切 Lead 自己的模型。之后新 spawn 的 teammate 跟着变 |
+| 按任务挑模型 | 用不了 team，改用经典 `subagent` 工具 |
+
+经典 `subagent` 支持 `provider`、`model`、`reasoning_effort`、`agent_preset` 四个参数（本插件预设已开 `modelSelectionSettings`）。
+
+代价说清楚：经典 `subagent` 是一次性子代理，没有共享任务板，没有持久身份。要用团队就得接受统一模型。
+
+## 状态怎么看
 
-`wait_agent` 前先 `list_agents`，确认有人正在 running。没人在跑，`wait_agent` 立刻返回 noProgress，白等。
+| 状态 | 含义 |
+|---|---|
+| `running` | 正在跑一个回合 |
+| `inactive` | 没有回合在执行。**不代表活干完、也不代表失败** |
+| `provisioning` | 正在创建 |
+| `failed` | 创建失败 |
 
-没人在跑就先 `send_message` 唤醒，再等。
+`inactive` 有两种情况：teammate 已经收工（你收到过它的通知），或者它被存档了、等你再给它发消息才醒来。
 
-`inactive` 只说明当前没有 turn 在执行，不代表活干完了、也不代表失败。看 task 状态判断。
+只有 Lead 能创建和打断 teammate（`interrupt_agent`）。打断不清空它排队的消息。
 
 ## 给最终答复前
 
@@ -85,4 +170,4 @@ task 描述就是完整规格。规格写细一点，teammate 少问一轮。
 
 结论在前。文件清单、验收输出、偏离规格三块分开。
 
-没实测的数字不写精确值。不知道就写「未验证」。
+没实测的数字不写精确值。不知道就写「未验证」。