dsh-tree-task-flow 0.1.0

package/cordis.patch.yml

@@ -0,0 +1,20 @@
+# 本插件的 bundle 配置层：把 task-tree 这一行插入 profile 的插件行列表。
+#
+# package.json 的 dsh.bundle.patch 指向本文件，因此安装成 bundle 后，
+# 这一层会自动挂进 `dsh.profile.bundles` 配置栈（优先级低于 profile 自身的
+# cordis.patch.yml）。
+#
+# 这里刻意不写 config，全部走 lib/index.js 里的 DEFAULT_CONFIG。
+# 要临时关掉或改默认值，请在 profile 自己的 cordis.patch.yml 里覆盖这一行。
+#
+# ⚠️ 同 id 的 config 是**整体替换**，不是逐字段深合并——覆盖时要把需要的
+#    字段一次写全。可覆盖的字段见 DEFAULT_CONFIG：
+#
+#   enabled            总开关                          默认 false（装上 ≠ 启用）
+#   autoContinue       是否允许自动续行                默认 false（开着会让人停不下来）
+#   maxAutoRounds      连续自动续行轮次上限            默认 5
+#   promptOrder        静态说明段顺序                  默认 2000
+#   rootDir            插件状态目录                    默认 $DSH_HOME/dsh-task-tree
+- insert:
+    - id: task-tree
+      name: 'dsh-tree-task-flow'

package/enable.example.yml

@@ -0,0 +1,4 @@
+# 显式启用插件用。默认 enabled 是 false——装上不等于启用。
+- id: task-tree
+  config:
+    enabled: true

package/lib/auto-continue.js

@@ -0,0 +1,132 @@
+/**
+ * 自动续行兜底。
+ *
+ * 主路径其实**不需要这里**：`tree_task_done` 的返回文本里已经带了"请继续执行下一个步骤"，
+ * 模型通常会在同一轮里接着往下做。
+ *
+ * 这里兜的是"模型仍然停下来"的情况：本轮结束、agent 回到 `idle` 时，
+ * 如果计划还在进行中，就推一条续行消息把下一轮唤醒。
+ *
+ * 三条安全阀缺一不可（方案 §7.1）：
+ *
+ * 1. **有活跃的内置 goal 时完全不插手**——不只是"别抢方向盘"。
+ *    `dsh-goal-round-driver` 每推进一轮都设 `startsRequestSeries: true`，
+ *    那会让系统提示词走归一化分支；节点 0 一旦被判定需要重写，
+ *    整个上下文从第一个 token 起失去缓存。
+ * 2. **队列里还有人在等的时候绝不抢**：`inbox.nextTurn` / `nextStep` 非空就退出。
+ * 3. **连续续行轮次有上限**，达到就停，避免把 token 烧在一个卡住的任务上。
+ *
+ * @module dsh-tree-task-flow/auto-continue
+ */
+
+import { activePath, renderContinue } from "./plan.js";
+
+/**
+ * 注册续行兜底。
+ *
+ * @param ctx - 挂载本行的 Cordis 上下文。
+ * @param options - `{ store, cfg }`。
+ */
+export function registerAutoContinue(ctx, { store, cfg }) {
+  /** 每个会话连续续行了多少次。 */
+  const rounds = new Map();
+
+  /**
+   * 被用户强行打断过的会话——**不再自动续行**。
+   *
+   * 这是"会话停不下来"的解法。用户按下停止 → 本轮中止 → agent 回到 idle；
+   * 没有这道闸，下面的 `agent/status` 监听器会立刻把它再拉起来，用户就永远停不下来。
+   * `agent/turn-stopping` 的 payload 带 `signal`，`signal.aborted` 正是
+   * "这一轮是被中止的"这个事实。
+   */
+  const stopped = new Set();
+
+  ctx.on("agent/turn-stopping", (payload) => {
+    const sessionId = payload?.agent?.session?.id;
+    if (sessionId === undefined) return;
+    if (payload?.signal?.aborted === true) stopped.add(sessionId);
+  });
+
+  // 只有**真人**发的消息才重置配额。
+  //
+  // 必须按来源区分，不能按"这一步有没有消息"：`agent.followup()` 推的消息同样会
+  // 从 inbox 进入下一步的 `payload.messages`，那样每一轮都会把自己刚用掉的配额
+  // 重置回去，`maxAutoRounds` 也就失去了意义。
+  // `source.kind === 'user'` 才是真人，插件推的是 `'plugin'`。
+  //
+  // 注意这是 waterfall：必须 await next() 并把它返回，否则会截断监听器链。
+  ctx.on("agent/pre-step", async (payload, next) => {
+    const decision = await next();
+    const sessionId = payload?.agent?.session?.id;
+    if (sessionId === undefined) return decision;
+    const fromHuman = (payload?.messages ?? []).some(
+      (message) => message?.source?.kind === "user",
+    );
+    if (fromHuman) {
+      rounds.set(sessionId, 0);
+      // 人回来了，解除中断闸门，允许新一轮的续行。
+      stopped.delete(sessionId);
+    }
+    return decision;
+  });
+
+  ctx.on("agent/status", (payload) => {
+    if (cfg.autoContinue !== true) return;
+    if (payload?.status !== "idle") return;
+
+    const agent = payload.agent;
+    const sessionId = agent?.session?.id;
+    if (agent === undefined || sessionId === undefined) return;
+
+    // ★ 安全阀 0：这一轮是被用户**中止**的 → 绝不能把它拉起来。
+    if (stopped.has(sessionId)) return;
+
+    // 安全阀 1：内置 goal 活跃时完全不插手。
+    const goal = ctx.get?.("goals")?.get?.(agent);
+    if (goal !== undefined && goal !== null && goal.phase === "active") return;
+
+    // 安全阀 2：已经有排队输入，别抢在用户前面。
+    const inbox = agent.inbox;
+    if ((inbox?.nextTurn?.length ?? 0) > 0 || (inbox?.nextStep?.length ?? 0) > 0) return;
+
+    // 安全阀 3：轮次上限。
+    const used = rounds.get(sessionId) ?? 0;
+    if (used >= cfg.maxAutoRounds) return;
+
+    // 只有"**本会话的**计划还在进行中"才值得续。
+    const plan = store.readPlan(sessionId);
+    const active = activePath(plan);
+    if (active === null || active.step === null) return;
+
+    rounds.set(sessionId, used + 1);
+    try {
+      agent.followup({
+        id: `tt-continue-${sessionId}-${Date.now().toString(36)}`,
+        role: "user",
+        content: [{ type: "text", text: renderContinue(plan) }],
+        source: { kind: "plugin", plugin: "dsh-tree-task-flow", form: "notice", summary: "计划续行" },
+      });
+      ctx.logger?.info?.(
+        `dsh-tree-task-flow: 自动续行 ${used + 1}/${cfg.maxAutoRounds}（步骤 ${active.step.id}）`,
+      );
+    } catch (error) {
+      ctx.logger?.warn?.(`dsh-tree-task-flow: 自动续行失败：${String(error?.message ?? error)}`);
+    }
+  });
+
+  // 交给 /task-tree 命令用的控制接口：人得有一句话就能接管的手段。
+  return {
+    /** 停止某个会话的自动续行（用户中断时自动调用，也可由 /task-tree stop 显式调用）。 */
+    stop(sessionId) {
+      if (sessionId !== undefined) stopped.add(sessionId);
+    },
+    /** 重新允许某个会话自动续行。 */
+    resume(sessionId) {
+      if (sessionId !== undefined) stopped.delete(sessionId);
+    },
+    /** 这个会话当前是不是被停止状态。 */
+    isStopped(sessionId) {
+      return stopped.has(sessionId);
+    },
+  };
+}

package/lib/commands.js

@@ -0,0 +1,189 @@
+/**
+ * `/task-tree` 斜杠命令：给人用的入口。
+ *
+ * 命令**不经过模型**——`handler` 直接执行、直接返回文本。所以它是查看和管理
+ * 任务树最直接的方式，也是"把自动执行停下来"的那个开关：
+ * 任务自动执行必须是**受控**的，人得有一句话就能接管的手段。
+ *
+ * 命令同时是**检查点的旁路**：检查点闸门只拦模型（`tools/pre-execute`），
+ * 拦不住人。人在检查点里照样能提交结果、丢弃节点、或者把自动续行停掉。
+ *
+ * @module dsh-tree-task-flow/commands
+ */
+
+import { activePath, checkpointOf, complete, dropNode, levelLabel, renderTree } from "./plan.js";
+
+/** 用法说明，status 和 help 都会带上。 */
+const USAGE = [
+  "/task-tree                     查看本会话的任务树与检查点状态",
+  "/task-tree done <id> <结果>     提交某个节点的结果并完成它",
+  "/task-tree drop <id>           丢弃某个节点",
+  "/task-tree stop                停止本会话的自动续行",
+  "/task-tree resume              重新允许自动续行（需 config 里 autoContinue 为 true）",
+  "/task-tree reset               清掉本会话的计划树",
+].join("\n");
+
+/** 未启用时唯一要说的话：装了，但没开，以及怎么开。 */
+const DISABLED_NOTE =
+  "dsh-tree-task-flow 已装载但**未启用**（config 里 enabled 不是 true）：它没有注册工具，" +
+  "也不会折叠任何上下文。要启用请在 profile 的 cordis.patch.yml 里把 enabled 设为 true。";
+
+/**
+ * 把检查点那句话拼出来。措辞与 `plan.js` 的检查点提示、`tools.js` 的闸门拒绝文案一致。
+ *
+ * @param checkpoint - `checkpointOf(plan)` 的结果。
+ * @returns 两行文本。
+ */
+function checkpointLines(checkpoint) {
+  const label = levelLabel(checkpoint.level);
+  return [
+    `检查点：${label}「${checkpoint.node.title}」(${checkpoint.node.id}) 的子节点已全部结束。`,
+    `此刻只有两条路：tree_task_plan 继续给 ${checkpoint.node.id} 拆子节点，` +
+      `或者 tree_task_done(id="${checkpoint.node.id}", result="…") 提交这个${label}的结果并完成它。`,
+  ];
+}
+
+/**
+ * 注册命令。
+ *
+ * @param ctx - 挂载本行的 Cordis 上下文。
+ * @param options - `{ store, cfg, autoContinue, enabled }`；`autoContinue` 是
+ *   `registerAutoContinue` 返回的控制接口，未启用时为 null。
+ */
+export function registerCommands(ctx, { store, cfg, autoContinue, enabled = false }) {
+  // 和 tools 一样，命令服务不是每个部署都有；用 get 探测而不是写进 inject。
+  const commands = ctx.get?.("commands");
+  if (commands === undefined || commands === null) {
+    ctx.logger?.debug?.("dsh-tree-task-flow: 没有 commands 服务，/task-tree 未注册");
+    return;
+  }
+
+  commands.register({
+    name: "task-tree",
+    description: "查看与管理任务树：status / done <id> <结果> / drop <id> / stop / resume / reset",
+    input: { hint: "status | done <id> <结果> | drop <id> | stop | resume | reset" },
+    handler: (invocation) => {
+      const sessionId = invocation?.agent?.session?.id;
+      if (sessionId === undefined) {
+        return { kind: "error", text: "拿不到当前会话。" };
+      }
+
+      const raw = String(invocation?.rawInput ?? "").trim();
+      const [verb = "status", ...rest] = raw === "" ? [] : raw.split(/\s+/u);
+
+      if (verb === "help") {
+        return { kind: "success", text: enabled === true ? USAGE : `${DISABLED_NOTE}\n\n${USAGE}` };
+      }
+
+      // 未启用时插件没有注册工具，也就不会有计划树；除了查看"装了但没开"，
+      // 其余动词一概不执行——启用的插件一个字节都不该碰会话。
+      if (enabled !== true && verb !== "status") {
+        return {
+          kind: "error",
+          text: `${DISABLED_NOTE}\n\n未启用时只有 /task-tree status 与 /task-tree help 可用。`,
+        };
+      }
+
+      if (verb === "stop") {
+        autoContinue?.stop?.(sessionId);
+        return {
+          kind: "success",
+          text: "已停止本会话的自动续行。任务树的进度没有变，随时可以继续。",
+        };
+      }
+
+      if (verb === "resume") {
+        autoContinue?.resume?.(sessionId);
+        return {
+          kind: "success",
+          text:
+            cfg.autoContinue === true
+              ? "已重新允许本会话自动续行。"
+              : "已解除中断标记，但配置里 autoContinue 是 false，所以仍然不会自动续行。",
+        };
+      }
+
+      if (verb === "reset") {
+        store.writePlan(sessionId, null);
+        return { kind: "success", text: "已清掉本会话的计划树。" };
+      }
+
+      if (verb === "done") {
+        const id = rest[0];
+        const result = rest.slice(1).join(" ").trim();
+        if (id === undefined) {
+          return { kind: "error", text: `用法：/task-tree done <节点 id> <结果>\n\n${USAGE}` };
+        }
+        if (result === "") {
+          return {
+            kind: "error",
+            text:
+              "完成必须提交结果：请写清这个节点产出了什么。" +
+              "插件会用它顶替这个节点从开始到现在的整段执行过程，所以要写成能独立看懂的样子。",
+          };
+        }
+        const plan = store.readPlan(sessionId);
+        if (plan === null) return { kind: "error", text: "本会话还没有计划。" };
+        const outcome = complete(plan, id, result);
+        if (!outcome.ok) return { kind: "error", text: `没有完成：${outcome.reason}` };
+        store.writePlan(sessionId, plan);
+        // `complete` 已经把检查点提示放进 events 了，这里只补上折叠后的树。
+        return { kind: "success", text: [...outcome.events, "", renderTree(plan)].join("\n") };
+      }
+
+      if (verb === "drop") {
+        const id = rest[0];
+        if (id === undefined) {
+          return { kind: "error", text: `用法：/task-tree drop <节点 id>\n\n${USAGE}` };
+        }
+        const plan = store.readPlan(sessionId);
+        if (plan === null) return { kind: "error", text: "本会话还没有计划。" };
+        const result = dropNode(plan, id);
+        if (!result.ok) return { kind: "error", text: `没有丢弃：${result.reason}` };
+        store.writePlan(sessionId, plan);
+        return {
+          kind: "success",
+          text: [`已丢弃：${result.dropped.join("、")}`, "", renderTree(plan)].join("\n"),
+        };
+      }
+
+      if (verb !== "status") {
+        return { kind: "error", text: `不认识的子命令：${verb}\n\n${USAGE}` };
+      }
+
+      const plan = store.readPlan(sessionId);
+      const lines = [renderTree(plan)];
+
+      if (enabled !== true) {
+        lines.push("", DISABLED_NOTE);
+      } else if (plan === null) {
+        lines.push("", "本会话还没有计划。用 tree_task_create 建立目标与任务。");
+      } else {
+        // 检查点优先于"当前节点"：那一刻要推进的不是某个子任务，
+        // 而是"这一层到底做完了没有"这个判断。
+        const checkpoint = checkpointOf(plan);
+        const active = activePath(plan);
+        if (checkpoint !== null) {
+          lines.push("", ...checkpointLines(checkpoint));
+        } else if (active === null) {
+          lines.push("", "计划树上的所有节点都已结束。请向用户汇报最终结果。");
+        } else if (active.step !== null) {
+          lines.push("", `当前子任务：${active.step.id}「${active.step.title}」`);
+        } else if (active.task !== null) {
+          lines.push(
+            "",
+            `当前任务：${active.task.id}「${active.task.title}」（还没有子任务 → tree_task_plan）`,
+          );
+        } else {
+          lines.push(
+            "",
+            `当前目标：${active.goal.id}「${active.goal.title}」（还没有任务 → tree_task_plan）`,
+          );
+        }
+      }
+
+      lines.push("", USAGE);
+      return { kind: "success", text: lines.join("\n") };
+    },
+  });
+}

package/lib/http.js

@@ -0,0 +1,243 @@
+/**
+ * 设置面板用的 HTTP 接口。
+ *
+ * 面板跑在浏览器里，拿不到宿主内存中的 store，所以数据要经由这里出去。
+ * 全部挂在 `/dsh-tree-task-flow/` 前缀下；只读写插件**自己的**状态目录，
+ * 不碰会话日志（那是后端内部格式）。
+ *
+ * 面板要显示两样东西，都在这里算好给它：
+ *
+ *   - **每层的结果**：节点完成时提交的文本。面板不自己去挖计划树的深层结构，
+ *     接口直接把三层各自的结果摆出来。
+ *   - **检查点状态**：一个节点自己的子节点全部结束、而它自己还开着的那一刻。
+ *     此刻只有两条路——继续拆子节点，或者提交结果并完成它。
+ *
+ * 面板上的按钮都写计划树，所以写完要把**新的**活动路径、结果与检查点一并回传，
+ * 免得面板还要再发一次请求才知道自己按出了什么效果。
+ *
+ * @module dsh-tree-task-flow/http
+ */
+
+import { readdirSync } from "node:fs";
+import { join } from "node:path";
+
+import { activePath, checkpointOf, complete, dropNode, levelLabel } from "./plan.js";
+
+/** 统一的 JSON 响应。 */
+function sendJson(response, status, body) {
+  response.writeHead(status, {
+    "content-type": "application/json; charset=utf-8",
+    "cache-control": "no-store",
+  });
+  response.end(JSON.stringify(body));
+}
+
+/** 读请求体并解析 JSON；读不动就当空对象，别让面板拿到 500。 */
+async function readJsonBody(request) {
+  const chunks = [];
+  for await (const chunk of request) chunks.push(chunk);
+  if (chunks.length === 0) return {};
+  try {
+    return JSON.parse(Buffer.concat(chunks).toString("utf8"));
+  } catch {
+    return {};
+  }
+}
+
+/** 活动路径压成面板要的形状：三层各自的 id，没到那层就是 null。 */
+function activeInfo(plan) {
+  const active = activePath(plan);
+  if (active === null) return null;
+  return {
+    goalId: active.goal.id,
+    taskId: active.task?.id ?? null,
+    stepId: active.step?.id ?? null,
+  };
+}
+
+/** 检查点压成面板要的形状；没有检查点就是 null。 */
+function checkpointInfo(plan) {
+  const found = checkpointOf(plan);
+  if (found === null) return null;
+  return {
+    id: found.node.id,
+    level: found.level,
+    label: levelLabel(found.level),
+    title: found.node.title,
+  };
+}
+
+/** 一个节点提交过的结果；还没提交就是 null。 */
+function resultOf(node) {
+  if (!node?.result) return null;
+  return {
+    id: node.id,
+    title: node.title,
+    text: node.result.text,
+    at: node.result.at,
+  };
+}
+
+/** 活动路径上每一层各自提交的结果。 */
+function levelResults(plan) {
+  const active = activePath(plan);
+  return {
+    goal: resultOf(active?.goal),
+    task: resultOf(active?.task),
+    step: resultOf(active?.step),
+  };
+}
+
+/** 一次写操作之后，面板需要的全部新状态。 */
+function afterWrite(plan) {
+  return {
+    active: activeInfo(plan),
+    checkpoint: checkpointInfo(plan),
+    results: levelResults(plan),
+  };
+}
+
+/** 列出状态目录里所有**有计划的会话**。 */
+function listSessions(store) {
+  let names = [];
+  try {
+    names = readdirSync(join(store.root, "plans"));
+  } catch {
+    return [];
+  }
+
+  const out = [];
+  for (const name of names) {
+    if (!name.endsWith(".json")) continue;
+    const sessionId = name.slice(0, -".json".length);
+    const plan = store.readPlan(sessionId);
+    if (plan === null) continue;
+    const steps = (plan.goal?.tasks ?? []).flatMap((task) => task.steps ?? []);
+    out.push({
+      sessionId,
+      goal: plan.goal?.title ?? "(未命名目标)",
+      status: plan.goal?.status ?? "pending",
+      updatedAt: plan.updatedAt ?? 0,
+      steps: steps.length,
+      done: steps.filter((step) => step.status === "done").length,
+      result: plan.goal?.result?.text ?? null,
+      checkpoint: checkpointInfo(plan),
+    });
+  }
+  out.sort((a, b) => b.updatedAt - a.updatedAt);
+  return out;
+}
+
+/**
+ * 注册全部面板接口。
+ *
+ * @param ctx - 挂载本行的 Cordis 上下文。
+ * @param options - `{ store, cfg, autoContinue }`。
+ */
+export function registerHttp(ctx, { store, cfg, autoContinue }) {
+  ctx.inject(["webServer"], (host) => {
+    host.effect(() => {
+      // 会话列表：面板顶部的下拉框。
+      host.webServer.register(
+        {
+          kind: "exact",
+          path: "/dsh-tree-task-flow/sessions",
+          handler: async (request, response) => {
+            if (request.method !== "GET") return sendJson(response, 405, { ok: false, error: "只支持 GET" });
+            sendJson(response, 200, {
+              ok: true,
+              enabled: cfg.enabled === true,
+              sessions: listSessions(store),
+            });
+          },
+        },
+        "dsh-tree-task-flow: sessions",
+      );
+
+      // 一棵树的全部信息：结构 + 每层结果 + 检查点 + 当前路径 + 三层折叠游标。
+      host.webServer.register(
+        {
+          kind: "exact",
+          path: "/dsh-tree-task-flow/tree",
+          handler: async (request, response) => {
+            if (request.method !== "GET") return sendJson(response, 405, { ok: false, error: "只支持 GET" });
+            const url = new URL(request.url ?? "/", "http://localhost");
+            const sessionId = url.searchParams.get("sessionId") ?? "";
+            const plan = store.readPlan(sessionId);
+            if (plan === null) return sendJson(response, 404, { ok: false, error: "这个会话没有计划" });
+
+            const cursors = store.readSurfaces(sessionId);
+            sendJson(response, 200, {
+              ok: true,
+              plan,
+              ...afterWrite(plan),
+              cursors: {
+                goal: cursors.goal ?? null,
+                task: cursors.task ?? null,
+                step: cursors.step ?? null,
+              },
+              stopped: autoContinue?.isStopped?.(sessionId) === true,
+            });
+          },
+        },
+        "dsh-tree-task-flow: tree",
+      );
+
+      // 面板上的按钮都走这一个端点。
+      host.webServer.register(
+        {
+          kind: "exact",
+          path: "/dsh-tree-task-flow/action",
+          handler: async (request, response) => {
+            if (request.method !== "POST") return sendJson(response, 405, { ok: false, error: "只支持 POST" });
+            const body = await readJsonBody(request);
+            const sessionId = String(body.sessionId ?? "");
+            const action = String(body.action ?? "");
+
+            if (action === "stop" || action === "resume") {
+              autoContinue?.[action]?.(sessionId);
+              return sendJson(response, 200, {
+                ok: true,
+                stopped: autoContinue?.isStopped?.(sessionId) === true,
+              });
+            }
+
+            if (action === "reset") {
+              store.writePlan(sessionId, null);
+              // 计划没了，游标也必须跟着清：游标里记的是"这一层总结到哪儿了"，
+              // 留着旧节点 id，下一次建树的第一层就会被误判成"没换节点"。
+              store.writeSurfaces(sessionId, {
+                sessionId,
+                goal: null,
+                task: null,
+                step: null,
+                updatedAt: Date.now(),
+              });
+              return sendJson(response, 200, { ok: true, active: null, checkpoint: null, results: null });
+            }
+
+            if (action === "done" || action === "drop") {
+              const plan = store.readPlan(sessionId);
+              if (plan === null) return sendJson(response, 404, { ok: false, error: "这个会话没有计划" });
+              const id = String(body.id ?? "");
+              // 完成必须带结果：插件要用它替换掉这个节点的执行过程。
+              const outcome = action === "done" ? complete(plan, id, body.result) : dropNode(plan, id);
+              if (!outcome.ok) return sendJson(response, 200, { ok: false, error: outcome.reason });
+              store.writePlan(sessionId, plan);
+              return sendJson(response, 200, {
+                ok: true,
+                events: outcome.events ?? outcome.dropped ?? [],
+                ...afterWrite(plan),
+              });
+            }
+
+            return sendJson(response, 400, { ok: false, error: `不认识的动作：${action}` });
+          },
+        },
+        "dsh-tree-task-flow: action",
+      );
+
+      ctx.logger?.info?.("dsh-tree-task-flow: 设置面板接口已挂载");
+    }, "dsh-tree-task-flow: http");
+  });
+}