dsh-tree-task-flow 0.3.3 → 0.3.5

package/README.md

@@ -22,46 +22,73 @@
 | 过程 | 读文件、试错、命令输出 | 节点完成时**整段折叠掉** |
 | 结果 | 模型在 `tree_task_done` 里提交的 `result` | 留下来，供后续节点引用 |
 
-## 上下文怎么长
+## 折叠按什么切
+
+规则只有一条，**只看表层，与计划树无关**：
 
 ```
-[节点 0]  系统提示词（身份 / 工具 schema / 工具说明）   ← 不随计划变化
-[用户消息]
-[目标级汇总]                          ← 换目标时逐条累积
-  [任务级汇总]                        ← 换任务时逐条累积
-    [子任务汇总] [子任务汇总] …       ← 同级逐条累积，互不卷走
-    [当前子任务的执行过程]            ← 下一次折叠的对象
+从上一个边界调用之后  →  到下一个 tree_task_done 之前，这一段收走
 ```
 
-每一层有一个**游标**，记着"这一层总结到哪儿了"。节点完成时，插件把
-**游标之后到末尾**这一整段替换成一条汇总消息：
+边界调用是 `tree_task_create` / `tree_task_plan` / `tree_task_done` 这三个工具，
+它们的调用**与返回**都留在上下文里——模型靠它们看"计划是什么、下一步干什么"。
+折叠只收它们**之间**的过程，换成一条计数通告：
 
 ```
-子任务完成 → 替换 [上个游标之后, 末尾] → 本子任务的汇总
-任务完成   → 替换 [进任务时的边界之后, 末尾] → 本任务的汇总
-目标完成   → 替换 [进目标时的边界之后, 末尾] → 目标的汇总
+[tree_task_plan 调用] [返回：已添加 2 个子任务 + 整棵树]
+[tree_task消息：隐藏了 12 条过程上下文。读取：… 写入：…]
+[tree_task_done 调用] [返回：接下来需要进行步骤：「二」(s-4)。]
 ```
 
-游标自己留在替换范围**之外**，所以同级上一条汇总消息不会被这一次折叠卷走。
-这就是"同级完成不互相屏蔽"的来由。
+两条硬约束：
+
+- 两次边界调用之间**夹着你的消息就不折**——往前折丢了需求，往后折丢了回应，
+  这一段整段跳过，一个节点都不动；
+- 两次调用**挨着**（中间没有过程）也什么都不注入，不追加、不留空消息。
 
-游标失效时（被压缩遮掉、或它之后本来就什么都没有）折叠**降级为纯追加**：
-过程收不起来，但提交的结果照样进上下文。**收不起来可以，丢掉结果不行。**
+每一次 `tree_task_done` 的调用与它的返回都**留在上下文里**，一轮轮累积；
+模型下一轮还看得到"我刚做完了什么、接下来干什么"。
 
 折叠发生在 `agent/pre-step`——上一轮已结束、下一个请求还没构造的那一刻。
 工具执行中途不能折叠，那时 surface 还在增长，替换会把自己卷进去。
 
-## 检查点
+## 注入消息与 tree_task_done 的返回
+
+一次折叠在上下文里留下**两样**东西：
 
-**子任务全部结束，不会让父节点自动完成。** 那一刻树进入**检查点**：
+**一、折叠通告——哪一段被收走了**
 
 ```
-检查点：任务「重构解析器」(t-3) 的子节点已全部结束。
-此刻轮到你的判断：用 tree_task_plan 继续给 t-3 拆子节点，
-或者用 tree_task_done 提交这个任务的结果并完成它。
+tree_task消息：隐藏了12条过程上下文。
+读取：C:\apps\x\a.js、C:\apps\x\b.js
+写入：C:\apps\x\c.js
 ```
 
-**检查点只是提示，不是闸门。** 它出现在 `tree_task_done` 的回执、树上和汇总消息里，
+只报条数与**读写了哪些文件**：过程收走了，但"这活碰过哪些文件"得留下，
+否则模型要从头再找一遍。路径取自工具调用的 `file_path` / `path` 参数——
+界面列出文件变更用的是同一个来源；`pwsh` / `bash` 里碰过什么文件看不出来，不计入。
+
+**二、`tree_task_done` 的返回——下一步干什么**
+
+```
+tree_task消息：接下来需要进行步骤：「步骤二」(s-4)。
+```
+
+按情形是三种之一：
+
+| 情形 | 返回的是 |
+|---|---|
+| 同层还有下一个 | `tree_task消息：接下来需要进行步骤/任务：「标题」(id)。` |
+| 同层到头、上一层还没交 | `tree_task消息：检查点：任务/目标<id> 的步骤/任务已全部结束，请确认<id> 是否完成，如果完成请调用tree_task_done，如果还需继续，可使用 tree_task_plan 新增步骤/任务继续。` |
+| 整棵树都完了 | `tree_task消息：请汇报最终结果。` |
+
+两样都**不重复提交内容**（`result` 就在这次调用的参数里）。折叠时，**这次
+`tree_task_done` 的调用连同它的返回原样留在上下文里**，被收走的只是它**前面**那段过程。
+
+**子任务全部结束，不会让父节点自动完成。** 那一刻树进入**检查点**，
+也就是上表第二种返回。
+
+**检查点只是提示，不是闸门。** 它出现在树上，也出现在 `tree_task_done` 的返回里，
 但插件**不会拦住任何工具**——"这一层到底做完了没有"由模型判断，插件既不替它定死，
 也不靠拒绝别的工具把它逼到墙角。
 
@@ -70,14 +97,28 @@
 | 工具 | 用途 |
 |---|---|
 | `tree_task_status` | 查看整棵树、各节点状态与已提交的结果，以及现在该推进哪个节点 |
-| `tree_task_create` | 建立计划：一个目标 + 若干任务 |
+| `tree_task_create` | 新增一个目标：这个目标 + 它下面的若干任务。可多次调用，多个目标并存，不替换已有计划 |
 | `tree_task_plan` | 给一个节点追加子节点：给目标追加任务，给任务追加子任务 |
-| `tree_task_done` | 完成一个节点并提交它的结果，**`result` 必填** |
+| `tree_task_done` | 完成一个节点并提交它的结果，**`result` 必填**；返回的就是"下一步干什么"，这次调用连同返回留在上下文里，被收走的只是它前面的执行过程 |
 | `tree_task_update` | 修改一个节点的标题或说明 |
-| `tree_task_drop` | 丢弃一个节点；丢弃任务会连同它的子任务一起丢弃 |
+| `tree_task_drop` | 丢弃一个节点；丢弃目标会连同它下面的任务与子任务一起走，丢弃任务带上它的子任务 |
 
 层级固定三级，子任务是最低一级，不能再往下拆。
 
+### 三层怎么分
+
+| 层 | 是什么 | 怎么算分对了 |
+|---|---|---|
+| **L1 目标** | 最终要交付的东西 | 一个会话可以有多个，按创建顺序排；每个都写清要交付什么 |
+| **L2 任务** | **交付节点** | 一件能独立验收的交付物（一个文件、一条能跑的命令、一份结论）；下面覆盖多个步骤，别拆到只剩一两个 |
+| **L3 子任务** | **步骤** | 任务内部一两次工具调用能做完的事 |
+
+**折叠次数跟着 `tree_task_done` 的次数走**：每完成一个节点就折一次，界面也会因此多一张
+系统提示词卡片。所以任务别拆得太碎——够厚，done 的次数少，上下文前缀变动的次数也少。
+
+`result` 分两层写：任务的 result 写**交付物 + 怎么验收**（文件在哪、怎么跑、验出什么、
+已知限制），子任务的 result 一句话说清这步做了什么就够。
+
 ## 安装
 
 需要 Node.js 22.19 以上，以及能运行 `dsh`。
@@ -219,7 +260,7 @@ dsh --profile web --dump-config          # 输出里应出现 task-tree 这一
 | 文件 | 内容 |
 |---|---|
 | `plans/<sessionId>.json` | 计划树（每个会话一棵） |
-| `surfaces/<sessionId>.json` | 三层的折叠游标 `{ key, cursor }` |
+| `surfaces/<sessionId>.json` | 三层的进度游标 `{ key, cursor }`（只给界面看，不参与折叠） |
 
 > 目录名沿用插件改名前的标识，为的是不让既有的计划文件失联；插件名与它无关。
 
@@ -235,21 +276,21 @@ dsh --profile web --dump-config          # 输出里应出现 task-tree 这一
    空 `result` 会被拒绝。所以要写清"产出了什么"，写成能独立看懂的样子——
    过程会丢，别把过程写进去。
 
-2. **折叠是尽力而为的。** 游标被压缩遮掉时收不起来，但结果一定进上下文。
-   面板上看到某段过程还在，通常是这个原因。
+2. **折叠只看表层。** 两次边界调用之间没有过程时，什么都不注入；中间夹着你的消息时
+   整段不折——那一段原样留着（往前折丢需求、往后折丢回应），代价是上下文不收缩。
 
 3. **模型看到的工具说明不随计划变化，也不复述工具清单。** 那一段只讲什么时候用
    这组工具、完成时守什么规矩；每个工具的用法由它自己的 `description` 承担。
    要了解计划就让模型调 `tree_task_status`。
 
-4. **每次折叠，界面上的"系统提示词"卡片会重新渲染一次，但提示词一个字都没变。**
-   DSH 把"上下文被替换过"记成一次请求序列的边界，界面在 `reason` 不是 `change`
-   的请求上都会渲染这张卡片，而复用的是同一个锚点，所以卡片不会变多，位置也不动。
-   这是 DSH 的固有语义，插件只能把替换次数压到最低——**一次折叠只替换真正变化的
-   那一层**，典型的完成一个节点只产生一次替换。
+4. **折叠几次，界面就多几张「系统提示词」卡片，但上下文里的系统提示词始终只有一条。**
+   DSH 把"上下文被替换过"记成一次请求序列的边界（下一次请求带 `reason=series`），
+   界面在 `reason` 不是 `change` 的请求上都会画一张系统提示词卡片；锚点跟着那一轮 step 走，
+   卡片于是一张张堆起来。**上下文里 `system/message` 自始至终只有一条**，折叠没有伪造
+   任何系统消息。已实测：3 次折叠 → 3 次 `series` → 界面 3 张卡片。
 
 5. **改需求用「丢弃 + 追加」，不要重建整棵树。** 丢掉的节点留在树里可查，
-   它和完成的节点会合进同一条汇总。
+   它和完成的节点会一起被那一段折叠收走（通告只报条数，不区分完成还是丢弃）。
 
 6. **暂停不留痕迹。** 暂停后模型看到的是"没有下一条请求"，看不到任何"你被暂停了"
    之类的提示；继续之后也不会有"继续"消息进上下文。想让模型知道中间发生过什么，
@@ -261,7 +302,7 @@ dsh --profile web --dump-config          # 输出里应出现 task-tree 这一
 |---|---|
 | 资料 / 文件快照 / 记忆 | 上下文里值得留下的只有结果，其余靠模型自己重读 |
 | 文件回退 / 撤销 | 改需求用「丢弃 + 追加」 |
-| 多目标并行（多个根） | 单活动计划，数据结构已预留扩展 |
+| 并行推进多个目标 | 结构上支持一个会话有多个目标（目标层就是兄弟列表），但同一时刻只沿一条活动路径走 |
 | 把计划内容注入提示词 | 计划状态由 `tree_task_status` 现取，提示词里只放不随计划变化的说明 |
 
 ## 自检

package/client.js

@@ -166,11 +166,29 @@ window.__ModuleLoader__.load({
 			return { total, done };
 		}
 
+		/** 计划里的全部目标。一个会话可以有多个目标，它们是最外层的兄弟。 */
+		function goalsOf(data) {
+			return data?.plan?.goals || [];
+		}
+
+		/** 当前该盯着哪个目标：活动路径上的那个；没有就取第一个还没结束的，再退到最后一个。 */
+		function focusGoal(data) {
+			const goals = goalsOf(data);
+			if (goals.length === 0) return null;
+			const here = goals.find((each) => each.id === data?.active?.goalId);
+			if (here) return here;
+			return (
+				goals.find((each) => each.status !== "done" && each.status !== "dropped") ||
+				goals[goals.length - 1]
+			);
+		}
+
 		/** 当前活动节点的标题：子任务优先，其次任务，最后目标。 */
 		function currentLabel(data) {
 			const active = data.active;
 			if (!active) return "";
-			const goal = data.plan.goal;
+			const goal = focusGoal(data);
+			if (!goal) return "";
 			const task = (goal.tasks || []).find((each) => each.id === active.taskId);
 			if (!task) return goal.title;
 			const step = (task.steps || []).find((each) => each.id === active.stepId);
@@ -198,7 +216,7 @@ window.__ModuleLoader__.load({
 			const checkpoint = data.checkpoint;
 			if (checkpoint !== null && checkpoint !== undefined && typeof checkpoint.id === "string") {
 				ids.add(checkpoint.id);
-				const goalId = data.plan?.goal?.id;
+				const goalId = focusGoal(data)?.id;
 				if (checkpoint.level !== "goal" && typeof goalId === "string") ids.add(goalId);
 			}
 			return ids;
@@ -229,6 +247,7 @@ window.__ModuleLoader__.load({
 			"label.noResult": "（还没提交结果）",
 			"label.current": "当前",
 			"label.checkpointHere": "检查点",
+			"label.goals": "{count} 个目标",
 			"placeholder.result":
 				"写清这个节点产出了什么。它整段执行过程会被这条结果顶替，所以要能独立看懂。",
 			"hint.noChildren": "（还没有子节点 → 让模型调用 tree_task_plan）",
@@ -261,6 +280,7 @@ window.__ModuleLoader__.load({
 			"label.noResult": "(no result submitted yet)",
 			"label.current": "current",
 			"label.checkpointHere": "checkpoint",
+			"label.goals": "{count} goals",
 			"placeholder.result":
 				"State what this node produced. Its whole execution range is replaced by this result, so it must stand on its own.",
 			"hint.noChildren": "(no children yet → ask the model to call tree_task_plan)",
@@ -457,8 +477,8 @@ window.__ModuleLoader__.load({
 		/**
 		 * 一个节点：一行标题 + 可展开的详情。
 		 *
-		 * 三层共用同一个组件——它们的字段与动作本来就一样，差别只有缩进和
-		 * 「能不能丢弃」（整个目标不能丢，plan.js 会拒绝）。
+		 * 三层共用同一个组件——它们的字段与动作本来就一样，差别只有缩进，
+		 * 以及"这一层要不要给丢弃按钮"（目标、任务、子任务都能丢）。
 		 */
 		function NodeRow({ node, depth, activeIds, openIds, checkpointId, canDrop, sessionId, reload, t }) {
 			const children = node.tasks || node.steps || [];
@@ -662,8 +682,18 @@ window.__ModuleLoader__.load({
 			if (state.loading || state.empty || !state.data) return null;
 
 			const data = state.data;
-			const goal = data.plan.goal;
-			const stats = countNodes(goal);
+			const goals = goalsOf(data);
+			if (goals.length === 0) return null;
+			// 一个会话可能有多个目标：条上给总数与合计进度，正文里把它们都列出来，
+			// 展开状态仍旧只摊开正在走的那条路径。
+			const stats = goals.reduce(
+				(acc, each) => {
+					const one = countNodes(each);
+					return { total: acc.total + one.total, done: acc.done + one.done };
+				},
+				{ total: 0, done: 0 },
+			);
+			const heading = goals.length === 1 ? goals[0].title : t("label.goals", { count: goals.length });
 			const current = currentLabel(data);
 			// 「被按住」有两条来源：插件闸门（paused）与人按过界面停止（stopped）。
 			// 对用户来说都是"停着呢，点继续就能接着跑"，所以合成一个状态展示。
@@ -687,7 +717,7 @@ window.__ModuleLoader__.load({
 						{ className: "dsh-ttf-bar" },
 						h("span", { className: "dsh-ttf-glyph", "aria-hidden": true }, icon("IconChecklistOutline14", 14)),
 						h("span", { className: "dsh-ttf-label" + (held ? " dsh-ttf-labelHeld" : "") }, stateLabel),
-						h("span", { className: "dsh-ttf-title", title: goal.title }, goal.title),
+						h("span", { className: "dsh-ttf-title", title: heading }, heading),
 						h(
 							"span",
 							{ className: "dsh-ttf-progress" },
@@ -735,18 +765,21 @@ window.__ModuleLoader__.load({
 										)
 									: null,
 								held ? h("div", { className: "dsh-ttf-note" }, t("note.paused")) : null,
-								h(NodeRow, {
-									node: goal,
-									depth: 0,
-									activeIds: currentIds(data),
-									openIds: defaultOpenIds(data),
-									checkpointId: data.checkpoint ? data.checkpoint.id : null,
-									// 整个目标不能丢弃：plan.js 会拒绝，这里也不给按钮。
-									canDrop: false,
-									sessionId,
-									reload,
-									t,
-								}),
+								goals.map((each) =>
+									h(NodeRow, {
+										key: each.id,
+										node: each,
+										depth: 0,
+										activeIds: currentIds(data),
+										openIds: defaultOpenIds(data),
+										checkpointId: data.checkpoint ? data.checkpoint.id : null,
+										// 目标也能丢：丢弃会连同它下面的任务与子任务一起走。
+										canDrop: true,
+										sessionId,
+										reload,
+										t,
+									}),
+								),
 							)
 						: null,
 				),

package/lib/commands.js

@@ -26,17 +26,19 @@ const DISABLED_NOTE =
   "也不会折叠任何上下文。要打开请在 profile 的 cordis.patch.yml 里把 enabled 设为 true。";
 
 /**
- * 把检查点那句话拼出来。措辞与 `plan.js` 的检查点提示一致。
+ * 把检查点那句话拼出来。措辞与 `plan.js` 的 `renderContinue` 一致。
  *
  * @param checkpoint - `checkpointOf(plan)` 的结果。
  * @returns 两行文本。
  */
 function checkpointLines(checkpoint) {
   const label = levelLabel(checkpoint.level);
+  const id = checkpoint.node.id;
+  const title = checkpoint.node.title;
   return [
-    `检查点：${label}「${checkpoint.node.title}」(${checkpoint.node.id}) 的子节点已全部结束。`,
-    `此刻轮到你的判断：用 tree_task_plan 继续给 ${checkpoint.node.id} 拆子节点，` +
-      `或者用 tree_task_done(id="${checkpoint.node.id}", result="…") 提交这个${label}的结果并完成它。`,
+    `检查点：${label}「${title}」(${id}) 的子节点已全部结束。`,
+    `结果已经满足「${title}」，就用 tree_task_done(id="${id}", result="…") 提交这个${label}的结果并完成它；` +
+      `还缺哪一步，再用 tree_task_plan 补上。`,
   ];
 }
 

package/lib/http.js

@@ -10,7 +10,7 @@
  *   - **每层的结果**：节点完成时提交的文本。条目不自己去挖计划树的深层结构，
  *     接口直接把三层各自的结果摆出来。
  *   - **检查点状态**：一个节点自己的子节点全部结束、而它自己还开着的那一刻。
- *     此刻只有两条路——继续拆子节点，或者提交结果并完成它。
+ *     折叠出来的汇总消息会直接写明这一层够不够收尾。
  *   - **暂停状态**：条目上的暂停/继续按钮写的就是这个。暂停挂的是
  *     `agent/pre-step`（见 `pause.js`），不插消息、不改计划，所以它不属于计划树，
  *     单独回传。