dsh-tree-task-flow 0.2.0 → 0.3.1

package/README.md

@@ -4,13 +4,14 @@
 **目标 → 任务 → 子任务**三级树，每个节点完成时由模型提交结果，插件随即把这个节点的
 **执行过程**从上下文里折叠掉，只留下那条结果。
 
-装上不等于启用。插件默认关闭，不会在没人点头的时候改动任何会话。
+**安装即启用**：`dsh plugin add` 之后就生效，不需要再改任何配置。
+不想用的时候，在 profile 里写一句 `enabled: false` 就能关掉，关掉后一个字节都不碰会话。
 
 ## 它解决什么
 
 长任务跑到后半程，上下文里绝大多数内容是**过程**：读过哪些文件、试过哪些错、
 执行过哪些命令。这些内容对后面没有用，但会一直占着位置——每多一轮，
-模型要被喂的就越长，缓存也越容易被顶掉。
+喂给模型的上下文就更长一分，而其中真正需要留住的只有寥寥几句。
 
 真正需要留给后面的只有一句话：**这一步做完了，它产出了什么。**
 
@@ -24,7 +25,7 @@
 ## 上下文怎么长
 
 ```
-[节点 0]  系统提示词（身份 / 工具 schema / 静态说明）   ← 会话内逐字节不变
+[节点 0]  系统提示词（身份 / 工具 schema / 工具说明）   ← 不随计划变化
 [用户消息]
 [目标级汇总]                          ← 换目标时逐条累积
   [任务级汇总]                        ← 换任务时逐条累积
@@ -56,13 +57,13 @@
 
 ```
 检查点：任务「重构解析器」(t-3) 的子节点已全部结束。
-此刻只放行两个工具：tree_task_plan 与 tree_task_done。
+此刻轮到你的判断：用 tree_task_plan 继续给 t-3 拆子节点，
+或者用 tree_task_done 提交这个任务的结果并完成它。
 ```
 
-检查点只放行 `tree_task_plan`（继续拆子节点）和 `tree_task_done`（提交结果并完成），
-其余工具**一律被拒**。"这一层到底做完了没有"要由模型判断，不能被计数规则替它定死。
-
-检查点只拦模型（`tools/pre-execute`），拦不住人：`/task-tree` 命令随时能接管。
+**检查点只是提示，不是闸门。** 它出现在 `tree_task_done` 的回执、树上和汇总消息里，
+但插件**不会拦住任何工具**——"这一层到底做完了没有"由模型判断，插件既不替它定死，
+也不靠拒绝别的工具把它逼到墙角。
 
 ## 六个工具
 
@@ -81,55 +82,69 @@
 
 需要 Node.js 22.19 以上，以及能运行 `dsh`。
 
+**从 npm 安装**：
+
+```powershell
+dsh plugin --profile web add dsh-tree-task-flow
+```
+
 **从源码目录安装**（装成 `link:`，改完源码重启即生效）。把仓库克隆到任意目录，
 然后指向那个目录：
 
 ```powershell
 dsh plugin --profile web add <插件目录>
-dsh --profile web --dump-config          # 输出里应出现 task-tree 这一行
 ```
 
-**从 npm 安装**：
+`dsh plugin add` 会把包加进 profile 的 `dsh.profile.bundles`，而本包自带的
+`cordis.patch.yml`（由 `package.json` 的 `dsh.bundle.patch` 指定）会顺势把
+`task-tree` 这一行插进插件列表——**装上即启用，不需要再改任何配置**。装完可以核对：
 
 ```powershell
-dsh plugin --profile web add dsh-tree-task-flow
+dsh --profile web --dump-config          # 输出里应出现 task-tree 这一行，且不带 config
 ```
 
-**装完必须重启 `dsh web`**——运行中的会话不追溯。
-
-## 启用
+**必须重启 `dsh web` 才生效**——运行中的会话不追溯，新工具要在新会话里才会出现。
 
-**装上 ≠ 启用，插件默认是关的**（`enabled: false`）。
+## 关闭
 
-在 `$DSH_HOME/profiles/web/cordis.patch.yml` 里加：
+不想要了，除了 `dsh plugin remove` 卸掉，也可以只把它关掉。在
+`$DSH_HOME/profiles/<名字>/cordis.patch.yml` 里写：
 
 ```yaml
 - id: task-tree
   config:
-    enabled: true
+    enabled: false
 ```
 
-然后重启 `dsh web`。仓库里的 `enable.example.yml` 可以直接抄。
+然后重启 `dsh web`。仓库里的 `config.example.yml` 有可以直接抄的完整版本。
 
 > ⚠️ profile 这一层按行覆盖时 `config` 是**整体替换**，不是逐字段深合并——
 > 覆盖时要把想保留的字段一起写全，没写的会走插件默认值（见下面的配置表）。
 
-没启用时插件**一个字节都不碰会话**：不注册工具、不加提示词段落、不折叠、不续行。
-只留一条 `/task-tree` 命令让你确认"装了但没开"以及怎么开。
+关掉之后插件**一个字节都不碰会话**：不注册工具、不加提示词段落、不折叠、不续行、
+不挂暂停闸门。只留一条 `/task-tree` 命令，让你确认它是被关掉的以及怎么打开。
 
 ## 界面
 
-**输入框上方的「树形任务流」条目**（和内置的待办、目标条目并排，宽度与消息正文对齐）：
-
-- 折叠时一行：标题 + `已完成/总数 · 当前节点`
-- 展开后是三级树，当前节点高亮，已完成节点直接显示已提交的结果
-- 节点上可以直接完成、丢弃，不用敲命令
-- 顶部状态条：「停止自动续行」「清空计划」「刷新」
+**输入框上方的「树形任务流」条目**（和内置的待办、目标条目并排，宽度与消息正文对齐）。
+外观照内置条目做——用的是同一套 UI 基座（`@deepseek-ai/dsh-client-ui-primitives`
+的图标、Tooltip 与 CSS 变量），所以它看起来就是内置的一部分：
+
+- **折叠时**是目标条那样的 36px 单行条：左边清单图标，中间「阶段标签 + 目标标题 + 进度」，
+  右边一排圆形图标按钮——**暂停/继续**、清空计划、展开。
+  阶段标签四种：进行中 / 已暂停 / 检查点 / 已全部完成。
+- **展开后**是待办清单那样的卡片：三级树之间有竖线与拐角连线，层级一眼看得出来；
+  同一层的节点之间、节点内部的各个内容块之间，各有一条分界线。
+  当前节点用虚线圈标出，已完成打勾、丢弃的划掉。
+- 节点标题**不缩略**：有多长写多长，多了自动换行。
+- 提交的结果**默认只占一行**，点一下摊开看全文。
+- 节点上可以直接完成、丢弃，不用敲命令。
+- 数据每 4 秒自动拉一次，模型在后台改计划时界面会自己跟上。
 
 **没有计划的会话一个像素都不占**——读不到计划就返回 `null`，不会平白挤掉内置的
 待办与目标条目。
 
-开关不在界面上，在 profile 的 `cordis.patch.yml` 里（见下面的「启用」一节）。
+开关不在界面上，在 profile 的 `cordis.patch.yml` 里（见上面的「关闭」一节）。
 
 ## 命令
 
@@ -140,8 +155,8 @@ dsh plugin --profile web add dsh-tree-task-flow
 | `/task-tree` | 查看本会话的任务树与检查点状态 |
 | `/task-tree done <id> <结果>` | 提交某个节点的结果并完成它 |
 | `/task-tree drop <id>` | 丢弃某个节点 |
-| `/task-tree stop` | 停止本会话的自动续行 |
-| `/task-tree resume` | 重新允许自动续行（需 config 里 `autoContinue` 为 true） |
+| `/task-tree pause` | 暂停：正在跑的工具跑完就停住，不再往下推进 |
+| `/task-tree resume` | 继续：从停住的地方接着跑，不往会话里插消息 |
 | `/task-tree reset` | 清掉本会话的计划树 |
 
 ## 配置
@@ -150,12 +165,33 @@ dsh plugin --profile web add dsh-tree-task-flow
 
 | 字段 | 默认 | 说明 |
 |---|---|---|
-| `enabled` | `false` | 总开关 |
+| `enabled` | `true` | 总开关；**装上即启用**，写 `false` 关掉 |
 | `autoContinue` | `false` | 模型停下时是否自动续行 |
 | `maxAutoRounds` | `5` | 连续自动续行的轮次上限 |
-| `promptOrder` | `2000` | 静态说明段落的排序 |
+| `promptOrder` | `1800` | 工具说明段落的排序 |
 | `rootDir` | `null` | 状态目录，默认 `$DSH_HOME/dsh-task-tree` |
 
+## 暂停与继续
+
+界面上的暂停按钮（或 `/task-tree pause`）是**真暂停**，不是"关掉自动续行"：
+
+- **正在执行的那个工具会正常跑完**，不会被中途掐断；
+- 它跑完之后，会话就静静停在原地——不再发起模型请求，也不再往下走一步；
+- **全程不往会话里插任何消息**，上下文干干净净。
+
+继续（界面按钮或 `/task-tree resume`）就是从这个岔口放行：模型从它原本要请求的地方
+接着请求，同样**零新增消息**。任务树的进度停在哪儿，就从哪儿接着跑。
+
+闸门开在 agent 的 `agent/pre-step` 上——一个 step 走完、工具结果都已落盘、模型还没
+发起下一次请求的那一刻。这是唯一同时满足"不打断工具"和"不留痕迹"的位置：再晚一点
+的 `agent/turn-stopping` 一旦放行，就得靠 `steer()` 推一条消息才能续上，那就留下痕迹了。
+
+**闸门只拦自动推进，不拦真人发言。** 暂停期间你自己发一条消息，说明你要它跑，
+插件会直接放行并解除暂停，不会把你堵在门外。
+
+暂停期间人按界面上的停止（中断本轮）也不会卡住：闸门盯着本轮的取消信号，
+信号一 abort 就立刻放行。
+
 ## 自动续行的四道闸门
 
 `autoContinue` 默认关闭，开着也只是**兜底**：`tree_task_done` 的返回文本里已经带了
@@ -171,6 +207,9 @@ dsh plugin --profile web add dsh-tree-task-flow
 
 队列里还有排队输入时也不抢，让用户先说话。
 
+另外，**暂停会一并压住它**：`/task-tree pause` 之后，即使模型自己停了下来，
+兜底也不会把它重新拉起来；`/task-tree resume` 再放开。
+
 ## 状态文件
 
 全部在 `$DSH_HOME/dsh-task-tree/` 下，**以 `sessionId` 为键**：
@@ -197,8 +236,9 @@ dsh plugin --profile web add dsh-tree-task-flow
 2. **折叠是尽力而为的。** 游标被压缩遮掉时收不起来，但结果一定进上下文。
    面板上看到某段过程还在，通常是这个原因。
 
-3. **模型看到的是静态的工具组说明，不随计划变化。** 提示词一变，整个上下文
-   从第一个 token 起失去缓存。要了解计划就让模型调 `tree_task_status`。
+3. **模型看到的工具说明不随计划变化，也不复述工具清单。** 那一段只讲什么时候用
+   这组工具、完成时守什么规矩；每个工具的用法由它自己的 `description` 承担。
+   要了解计划就让模型调 `tree_task_status`。
 
 4. **每次折叠，界面上的"系统提示词"卡片会重新渲染一次，但提示词一个字都没变。**
    DSH 把"上下文被替换过"记成一次请求序列的边界，界面在 `reason` 不是 `change`
@@ -209,6 +249,10 @@ dsh plugin --profile web add dsh-tree-task-flow
 5. **改需求用「丢弃 + 追加」，不要重建整棵树。** 丢掉的节点留在树里可查，
    它和完成的节点会合进同一条汇总。
 
+6. **暂停不留痕迹。** 暂停后模型看到的是"没有下一条请求"，看不到任何"你被暂停了"
+   之类的提示；继续之后也不会有"继续"消息进上下文。想让模型知道中间发生过什么，
+   得自己发消息说。
+
 ## 不做的事
 
 | 不做 | 原因 |
@@ -216,18 +260,22 @@ dsh plugin --profile web add dsh-tree-task-flow
 | 资料 / 文件快照 / 记忆 | 上下文里值得留下的只有结果，其余靠模型自己重读 |
 | 文件回退 / 撤销 | 改需求用「丢弃 + 追加」 |
 | 多目标并行（多个根） | 单活动计划，数据结构已预留扩展 |
-| 把计划内容注入提示词 | 提示词必须逐字节不变，否则整个上下文失去缓存 |
+| 把计划内容注入提示词 | 计划状态由 `tree_task_status` 现取，提示词里只放不随计划变化的说明 |
 
 ## 自检
 
-三个自检脚本都不 import 任何 `@deepseek-ai/*` 运行时包——插件以 `link:` 方式安装时，
+六个自检脚本都不 import 任何 `@deepseek-ai/*` 运行时包——插件以 `link:` 方式安装时，
 从插件目录往上找不到宿主作用域的包，一旦 import 就根本跑不起来。
+`verify-client.mjs` 因此自带一套最小的 `window` / `document` / React 替身，
+真去物化 `client.js`、真调一次 `apply`、真渲染一遍条目。
 
 ```powershell
-node verify-entry.mjs     # 入口装配：启用/未启用两条路径各注册了什么
-node verify-tools.mjs     # 工具层：schema、result 必填、检查点闸门、三级约束
+node verify-entry.mjs     # 入口装配：默认（安装即启用）/ 显式关闭两条路径各注册了什么
+node verify-tools.mjs     # 工具层：schema、result 必填、三级约束
 node verify-region.mjs    # 折叠行为：游标推进、降级追加、检查点提示
 node verify-plan.mjs      # 计划树纯逻辑：状态流转、自动完成、丢弃级联
+node verify-pause.mjs     # 暂停闸门：挂起、放行、取消信号、真人发言、会话隔离
+node verify-client.mjs    # 客户端条目：挂载点、样式注入、文案键集、四种渲染态
 ```
 
 `verify-region.mjs` 用假 session 忠实复刻了 DSH surface 的三条硬规则
@@ -244,7 +292,7 @@ dsh plugin --profile web remove dsh-tree-task-flow
 
 ## 设计文档
 
-- `docs/02-DSH插件开发方案.md` —— 完整设计：上下文组成、游标、折叠、检查点、缓存推理
+- `docs/02-DSH插件开发方案.md` —— 完整设计：上下文组成、游标、折叠、检查点
 - `docs/01-AIDesktop联动设计整理.md` —— 本插件最初的设计来源
 
 ## 许可