dsh-subagent-control 1.0.7 → 1.0.8

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 1.0.8
+
+Documentation only, no behaviour change.
+
+- The README explains what a subagent is before the word is used, drops internal terms (host,
+  profile patch layer, wall-clock budget) and describes the companion bundles by what they do
+  instead of justifying why they ship separately.
+
 ## 1.0.7
 
 - Rewrote the README for users instead of maintainers: what the three tools are for, how to install

package/README.en.md

@@ -6,6 +6,8 @@
 
 > English | [中文](README.md)
 
+In DSH an agent can hand part of the work to another agent; the one that takes it is called a subagent. This plugin lets the agent that handed the work out see those subagents, send them another line, and stop them.
+
 ## When you need it
 
 - You started a few subagents to work in parallel and want to know who is still running
@@ -21,24 +23,16 @@
 | `send_subagent_message` | Send one more message to a direct child | `subagent_id`, `message` |
 | `interrupt_subagent` | Stop a subagent's current turn | `subagent_id` |
 
-It looks like this:
+Once it is installed, one `list_subagents` call returns a line per subagent:
 
 ```
-list_subagents
-→ 3b0f9c1e  running  "review the patch"  depth=1
-
-list_subagents scope=descendants
-→ 3b0f9c1e  running  "review the patch"  depth=1
-  7d2a44b0  inactive "check the tests"    depth=2
-
-send_subagent_message subagent_id=3b0f9c1e message="also look at locale/zh.json"
-→ messageId=...
-
-interrupt_subagent subagent_id=3b0f9c1e
-→ accepted=true
+3b0f9c1e  running   "review the patch"  depth=1
+7d2a44b0  inactive  "check the tests"   depth=2
 ```
 
-Each line is `id  status  "label"  depth=`. `running` means a turn is executing; `inactive` only means no turn is running right now — **the subagent is still there**, and a message wakes it.
+Left to right: the id, the current status, the task in quotes, and the depth. `depth=1` is one you started, `depth=2` is one it started. `running` means a turn is executing; `inactive` only means no turn is running at this moment, not that the subagent is gone, and a message wakes it.
+
+Messaging and stopping are simpler still: `send_subagent_message` takes an id and one sentence, `interrupt_subagent` takes just the id, and they return a message id and whether the request was accepted.
 
 Team members are continuable subagents too, so they show up in the list marked `team=teammate`. Pass `include_teammates: false` when you only want the plain subagents you started.
 
@@ -67,7 +61,7 @@ Turn them on one by one under **Settings → Plugins → Installed → `dsh-suba
 - [dsh-human-wait](https://github.com/SpaceRelay/dsh-subagent-control/tree/main/human-wait) — keep PTC mode from burning its budget while you answer
 - [dsh-find-session](https://github.com/SpaceRelay/dsh-subagent-control/tree/main/dsh-find-session) — find text in the conversation or across every session
 
-All three install separately: they override a shipped row or another plugin's behaviour, and that should never happen implicitly.
+They each do one thing, so they are three separate packages: install the one you want. None of them come with this package.
 
 ## FAQ
 

package/README.md

@@ -6,12 +6,14 @@
 
 > [English](README.en.md) | 中文
 
+DSH 里，智能体可以把一部分活交给另一个智能体去做，被派出去的那个叫「子代理」。这个插件让派活的那一方能看见它们、给它们补话、把它们叫停。
+
 ## 什么时候用得上
 
 - 派了几个子代理分头干活，想知道还有谁在跑、跑到哪一步
-- 想给某个正在跑的子代理补一句话
-- 想叫停跑偏的那个，把回合收回来
-- 团队里，组长派出去的孙代子代理也要从上往下管得住
+- 想给某个正在干活的子代理补一句话
+- 想叫停跑偏的那个，让它停下来
+- 团队成员派出去的下一层子代理，也要能从上面管得住
 
 ## 三个工具
 
@@ -21,24 +23,16 @@
 | `send_subagent_message` | 给一个直接子代理补一句话 | `subagent_id`、`message` |
 | `interrupt_subagent` | 叫停某个子代理当前这一轮 | `subagent_id` |
 
-长这样：
+装好之后，智能体调一次 `list_subagents`，拿到的是每个子代理一行：
 
 ```
-list_subagents
-→ 3b0f9c1e  running  "review the patch"  depth=1
-
-list_subagents scope=descendants
-→ 3b0f9c1e  running  "review the patch"  depth=1
-  7d2a44b0  inactive "check the tests"    depth=2
-
-send_subagent_message subagent_id=3b0f9c1e message="顺手看一下 locale/zh.json"
-→ messageId=...
-
-interrupt_subagent subagent_id=3b0f9c1e
-→ accepted=true
+3b0f9c1e  running   "review the patch"  depth=1
+7d2a44b0  inactive  "check the tests"   depth=2
 ```
 
-每行是 `id  状态  "标签"  depth=`。`running` 表示正在跑；`inactive` 只表示当前没有回合在执行——**不是子代理没了**，发条消息就能唤醒。
+从左往右是：id、当前状态、引号里它正在做的任务、深度。`depth=1` 是你直接派出去的，`depth=2` 是它再派出去的。`running` 表示正在跑；`inactive` 只表示这一刻没有回合在执行，不是子代理没了，发条消息就能唤醒。
+
+补话和打断更简单：`send_subagent_message` 给一个 id 和一句话，`interrupt_subagent` 只给一个 id，分别返回一条消息 id 和这次请求是否被接受。
 
 团队里的队友本身也是可续子代理，所以也会出现在列表里，标着 `team=teammate`。只想要自己派的普通子代理，传 `include_teammates: false`。
 
@@ -54,10 +48,10 @@ interrupt_subagent subagent_id=3b0f9c1e
 
 | 面板里显示的名字 | 工具 | 作用 |
 | --- | --- | --- |
-| 跨层补话 | `relay_subagent_message` | 给够不着的深层后代发消息：投给第一跳并请它继续往下转 |
+| 跨层补话 | `relay_subagent_message` | 给够不着的深层子代理发消息：先发给直接子代理，由它继续往下转 |
 | 等待子代理 | `wait_subagents` | 在当前回合等子代理跑完，而不是先结束回合 |
 | 释放子代理 | `drain_subagents` | 停掉并释放直接子代理，真正把实例腾出来 |
-| 委派预算 | `subagent_budget` | 只读报告：深度上限、各层人数、运行 / 已停数量 |
+| 委派预算 | `subagent_budget` | 只读报告：深度上限、每层的人数、在跑和已停的数量 |
 
 在 设置 → 插件 → 已安装 → `dsh-subagent-control` 下面逐个打开，打开一个只注册一个工具。
 
@@ -67,7 +61,7 @@ interrupt_subagent subagent_id=3b0f9c1e
 - [dsh-human-wait](https://github.com/SpaceRelay/dsh-subagent-control/tree/main/human-wait) —— PTC 模式下等你回答问题时不烧掉执行预算
 - [dsh-find-session](https://github.com/SpaceRelay/dsh-subagent-control/tree/main/dsh-find-session) —— 会话内 / 跨会话关键词查找
 
-三个都是单独安装的：它们改的是宿主自带的行或别的插件的行为，不该跟着这个包一起悄悄生效。
+它们各有各的用途，所以是三个独立的包，要单独安装，不会跟着本包装上。
 
 ## 常见问题
 
@@ -75,13 +69,13 @@ interrupt_subagent subagent_id=3b0f9c1e
 
 **为什么只列出一两个？** 默认只列直接子代理。要看整棵树，`scope=descendants`。
 
-**inactive 的还能用吗？** 能。它只是当前没有回合在跑，发消息会唤醒。
+**inactive 的还能用吗？** 能。它只是这一刻没在干活，发条消息就醒。
 
 **和 `dsh-subagent-library` 冲突吗？** 两者都注册 `list_subagents`，同时装只有一个生效，选一个。
 
 ## 隐私与开销
 
-- 只读子代理注册表，不写文件、不联网、没有配置项
+- 只读子代理列表，不写文件、不联网、没有配置项
 - 零依赖，不引入任何运行时包
 
 ## 卸载

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-subagent-control",
-  "version": "1.0.7",
+  "version": "1.0.8",
   "description": "Three tools — list_subagents, send_subagent_message, interrupt_subagent — that let any agent, including a team member, list, steer and stop the subagents it started.",
   "license": "MIT",
   "author": {