dsh-workplan 1.5.0 → 1.5.2

package/lib/plan.js

@@ -1039,8 +1039,18 @@ export function applyStatus(statuses, subtaskId, patch) {
         if (patch.error === undefined)
             next.error = null;
     }
-    if (patch.status === 'in_progress' && next.startedAt === null) {
-        next.startedAt = Date.now();
+    if (patch.status === 'in_progress') {
+        if (next.startedAt === null)
+            next.startedAt = Date.now();
+        /*
+         * [1.5.2] 「正在做」不允许自称 100%。
+         *
+         * 工具允许 `{status:'in_progress', progress:100}`，界面于是出现
+         * 「正在做 + 进度 100%」，计划层再叠一个环 0% / 加权 100%（T5 C8）。
+         * 完成只能由 status='done' 表达，progress 到 99 就是这一步的上限。
+         */
+        if (Number(next.progress) >= 100)
+            next.progress = 99;
     }
     if (patch.status === 'blocked' && next.finishedAt === null) {
         next.finishedAt = Date.now();
@@ -1169,6 +1179,16 @@ export function deriveAggregates(statuses) {
         departments.set(item.department, department);
     }
     const total = statuses.length;
+    const allDone = total > 0 && done === total;
+    /*
+     * [1.5.2] 加权进度在「未全部完成」时不得四舍五入成 100。
+     *
+     * 旧算法直接 `round(progressSum / total)`：11 个 done + 1 个 blocked@95 得到
+     * 100，卡片上就出现「总体进度 100%」旁边还有「1 卡住了 / 11/12 做好了」——
+     * 与截图同类的自相矛盾（T4 实测 A.5）。这里的封顶只作用于展示口径，不影响
+     * 任何计数；全部完成时仍严格为 100，从而与 `done === total` 一一对应。
+     */
+    const raw = total === 0 ? 0 : Math.round(progressSum / total);
     return {
         stats: {
             total,
@@ -1176,7 +1196,7 @@ export function deriveAggregates(statuses) {
             blocked,
             inProgress,
             pending,
-            progress: total === 0 ? 0 : Math.round(progressSum / total),
+            progress: allDone ? 100 : Math.min(99, raw),
         },
         departments: [...departments.values()],
     };
@@ -1203,13 +1223,18 @@ export function computeStats(statuses) {
     return derivePlanSnapshot(statuses).stats;
 }
 /**
- * Invariant checker for tests and CI; production paths never call it because
- * pure derivation is already self-consistent.
+ * Invariant checker for tests and CI.
  *
  * Returns an empty array when every invariant holds. Each message names the
  * field and the observed value so it can be pasted straight into a report.
+ *
+ * [1.5.2] `phase` 是新增的可选入参：1.4.3 的 I1–I7 只校验计数内部自洽，
+ * 完全不看 `phase` 与 `stats` 的关系，因此「14/14 且 progress=100 却写着
+ * 正在收尾」这种**跨字段**矛盾一路畅通到界面。I8/I9 专门封住这一类：
+ * 只要调用方把本次真正要下发的 phase 传进来，任何「进度与状态文案打架」
+ * 的载荷都会在这里被判为违规，而不是等到用户看截图。
  */
-export function aggregateInvariantViolations(snapshot) {
+export function aggregateInvariantViolations(snapshot, phase) {
     const violations = [];
     const { statuses, stats, departments } = snapshot;
     if (stats.total !== statuses.length) {
@@ -1271,19 +1296,98 @@ export function aggregateInvariantViolations(snapshot) {
     if (sums.inProgress !== stats.inProgress) {
         violations.push(`I7 各部门 inProgress 之和=${sums.inProgress} 与 stats.inProgress=${stats.inProgress} 不一致`);
     }
+    /*
+     * [1.5.2] I8/I9 —— 完成语义跨字段不变量（用户截图那条「100% + 正在收尾」）。
+     *
+     * I8：工作项全部 done ⇔ phase 必须是 done。这是一条双向断言：
+     *     - 全 done 却是 pending/planning/executing/integrating/paused/blocked/degraded
+     *       ⇒ 卡片会同时出现 100% 与进行中文案（本次事故）；
+     *     - phase=done 却还有未完成项 ⇒ 反向矛盾（「已完成」下面挂着没做完的活）。
+     * I9：加权进度与计数同口径：全 done ⇒ 100；未全 done ⇒ 不得为 100。
+     *     旧算法 round(progressSum/total) 让 11 done + 1 blocked@95 算出 100。
+     */
+    if (stats.total > 0) {
+        const allDone = stats.done === stats.total;
+        if (allDone && phase !== undefined && phase !== null && phase !== 'done') {
+            violations.push(`I8 stats.done=${stats.done}/${stats.total} 已全部完成，但 phase=${String(phase)} 仍表示未完成`);
+        }
+        if (!allDone && phase === 'done') {
+            violations.push(`I8 phase=done 但 stats.done=${stats.done}/${stats.total} 尚未全部完成`);
+        }
+        if (allDone && stats.progress !== 100) {
+            violations.push(`I9 全部完成但 stats.progress=${stats.progress}`);
+        }
+        if (!allDone && stats.progress >= 100) {
+            violations.push(`I9 未全部完成（${stats.done}/${stats.total}）却显示 stats.progress=${stats.progress}`);
+        }
+    }
+    /*
+     * I10：单个工作项也不能自相矛盾——`in_progress` 意味着「还没做完」，
+     * 它的进度必须 < 100（旧载荷里出现过「正在做 + 100%」，T5 C8）。
+     */
+    for (const item of statuses) {
+        if (item?.status === 'in_progress' && Number(item?.progress) >= 100) {
+            violations.push(`I10 子任务 ${String(item?.subtaskId)} 状态为 in_progress 但 progress=${item?.progress}`);
+        }
+    }
     return violations;
 }
-export function planPhase(statuses, resultSeen = false) {
+/**
+ * 计划级阶段，由状态列表唯一决定。
+ *
+ * [1.5.2] 修复「一边 100%、一边正在收尾」的根因。
+ *
+ * 旧实现的最后一步是 `return resultSeen ? 'done' : 'integrating'`：工作项全部
+ * done 时仍要等「结果消息落盘」才晋升终态。问题在于 `resultSeen` 只是**持久化
+ * 回放**才知道的副作用，内存路径（`updateStatus` / `serialisePlan`）拿不到它：
+ *
+ *  - 主 Agent 用 `dsh_workplan_update` 补完最后几项时，phase 永远停在 integrating；
+ *  - 该路径不会再派发，也就永远不会写结果消息，于是 integrating 永久留存；
+ *  - 同期 `stats.done/total` 已是 14/14、百分比 100%，卡片就同时显示
+ *    「100% · 都做完了」和「正在收尾」，并留在「进行中」组（用户截图）。
+ *
+ * 结论：完成语义只能有一个事实源——状态列表。工作项全部完成即计划完成，
+ * 不需要也不允许等另一个副作用来「确认」。`resultSeen` 参数仅为兼容旧调用点保留，
+ * 不再参与判定（旧的 integrating 窗口已由 dispatch 内的 `executing` 覆盖）。
+ */
+export function planPhase(statuses, _resultSeen = false) {
     if (statuses.length === 0)
         return 'pending';
     if (statuses.every((item) => item.status === 'done'))
-        return resultSeen ? 'done' : 'integrating';
+        return 'done';
     if (statuses.some((item) => item.status === 'blocked'))
         return 'blocked';
     if (statuses.some((item) => item.status === 'in_progress' || item.status === 'done'))
         return 'executing';
     return 'pending';
 }
+/**
+ * 把「缓存的 phase」与「由状态列表派生的 phase」对账成唯一结果。
+ *
+ * phase 是缓存（dispatch/预算/取消会写它），statuses 是事实源。只要两者可能
+ * 分叉，就必须在出口处对账，否则同一个会话会因读取路径不同而翻转（实时
+ * integrating / 刷新后 done，T2 场景 B）。
+ *
+ * 规则只有四条，全部可由 `aggregateInvariantViolations` 断言：
+ *  1. 工作项全部 done ⇒ 一定是 done（缓存不得把它拖回任何进行中状态）；
+ *  2. 缓存是 done/integrating 但工作项没全 done ⇒ 缓存过期，回退到派生值；
+ *  3. pending/planning/executing 是「状态列表能直接回答」的轮次状态：一旦
+ *     有工作项开始（派生值不再是 pending），缓存里的旧 pending/planning 必须
+ *     让位；而派生值仍是 pending 时保留缓存（dispatch 刚开始、状态尚未落盘）。
+ *  4. 其余情况保留缓存的轮次状态（paused/cancelled/blocked/degraded）——
+ *     它们携带状态列表里没有的信息（预算暂停、用户取消）。
+ */
+export function reconcilePhase(phase, statuses) {
+    const derived = planPhase(statuses);
+    if (derived === 'done')
+        return 'done';
+    if (phase === 'done' || phase === 'integrating')
+        return derived;
+    if (phase === 'pending' || phase === 'planning' || phase === 'executing') {
+        return derived === 'pending' ? phase : derived;
+    }
+    return phase ?? derived;
+}
 export function nextReadyInStage(plan, statuses, stageId) {
     const byId = new Map(statuses.map((item) => [item.subtaskId, item]));
     const stage = plan.stages.find((item) => item.id === stageId);

package/lib/runtime.js

@@ -12,7 +12,7 @@
  * in this file is allowed to escape as an unhandled rejection from a listener.
  */
 import { randomUUID } from 'node:crypto';
-import { MAX_CONCURRENT, PlanError, applyStatus, attachPlanMeta, buildChildPrompt, buildCancelMessage, buildDegradedMessage, buildPlanMessage, buildPlannerPrompt, buildResultMessage, createStatuses, derivePlanSnapshot, extractJson, flattenSubtasks, isRecord, isSocialMessage, isStatusQuestion, isVagueContinuation, markDependentsBlocked, messageText, readySubtasks, MAX_PLAN_RESUMES, canResumePlan, resetBlockedStatuses, parseCancelMessage, parseResultMessage, parseWorkplanMessage, planPhase, truncate, validatePlan, applyResultStatuses, } from './plan.js';
+import { MAX_CONCURRENT, PlanError, aggregateInvariantViolations, applyStatus, attachPlanMeta, buildChildPrompt, buildCancelMessage, buildDegradedMessage, buildPlanMessage, buildPlannerPrompt, buildResultMessage, createStatuses, derivePlanSnapshot, extractJson, flattenSubtasks, isRecord, isSocialMessage, isStatusQuestion, isVagueContinuation, markDependentsBlocked, messageText, readySubtasks, MAX_PLAN_RESUMES, canResumePlan, resetBlockedStatuses, parseCancelMessage, parseResultMessage, parseWorkplanMessage, planPhase, reconcilePhase, truncate, validatePlan, applyResultStatuses, } from './plan.js';
 import { createProgressWatchdog, describeError } from './watchdog.js';
 export const PLANNER_TIMEOUT_MS = 120000;
 /**
@@ -785,21 +785,31 @@ export async function dispatchPlan(ctx, record, options) {
                 });
             }
             record.statuses = reset;
-            record.phase = 'paused';
             const total = record.statuses.length;
             const done = record.statuses.filter((item) => item.status === 'done').length;
+            /*
+             * [1.5.2] 预算到点 ≠ 一定是「暂停」。
+             *
+             * 旧代码在这里无条件 `record.phase = 'paused'`：如果最后一个子任务恰好在
+             * 截止时刻之后完成（done === total），计划会以 14/14、progress=100 的载荷
+             * 带着 paused 返回，界面就是「100% + 预算用完，可续跑」（T5 C4）。
+             * 全部完成时直接进终态，并且不再写「其余 0 项保留为未完成」这种自相矛盾的说明。
+             */
+            const allDoneNow = total > 0 && done === total;
+            record.phase = allDoneNow ? 'done' : 'paused';
             const minutes = Math.max(1, Math.round((options.totalTimeoutMs ?? TOTAL_TIMEOUT_MS) / 60000));
-            record.error = `本轮执行预算（${minutes} 分钟）已到：已完成 ${done}/${total}，其余 ${total - done} 项保留为未完成，再次派发本计划即可续跑（已完成的不重跑）`;
+            record.error = allDoneNow
+                ? null
+                : `本轮执行预算（${minutes} 分钟）已到：已完成 ${done}/${total}，其余 ${total - done} 项保留为未完成，再次派发本计划即可续跑（已完成的不重跑）`;
             /*
              * Drop the failure lines the aborted children wrote on their way out.
              * They used to survive into the result payload as
              * `["T4: 总执行超时", "总执行超时", …]`, so the model read a failure
              * report for subtasks that were explicitly *not* failures.
              */
-            record.errors = [
-                ...(record.errors ?? []).filter((line) => !/总执行超时/.test(String(line))),
-                record.error,
-            ].slice(-20);
+            record.errors = (record.errors ?? []).filter((line) => !/总执行超时/.test(String(line)));
+            if (!allDoneNow)
+                record.errors = [...record.errors, record.error].slice(-20);
         }
         else {
             /*
@@ -850,15 +860,30 @@ function serialisePlan(record, session) {
             : []);
     const statuses = snapshot.statuses;
     const stats = snapshot.stats;
-    let phase = record.phase ?? (plan ? planPhase(statuses) : 'degraded');
+    /*
+     * [1.5.2] 出口对账，而不是无条件相信内存缓存。
+     *
+     * 旧写法 `record.phase ?? planPhase(statuses)` 让缓存一旦存在就完全绕过
+     * statuses：一次 `updateStatus` 把计划写成 integrating 之后，即使 14/14 全部
+     * 完成，下发的 phase 仍是 integrating，界面于是「100% + 正在收尾」。这里改成
+     * `reconcilePhase`：全部完成一律 done，缓存过期的 done/integrating 回退到派生值。
+     */
+    let phase = reconcilePhase(record.phase ?? (plan ? planPhase(statuses) : 'degraded'), statuses);
     if (phase === 'pending' && !record.dispatchedAt && plan?.createdAt && Date.now() - plan.createdAt > STALE_PENDING_MS) {
         phase = 'cancelled';
     }
+    /*
+     * 每次真正下发前跑一遍跨字段不变量（I1–I10）。正常情况下恒为空；一旦某个
+     * 未来改动重新引入「进度与状态打架」，这里会把它连同具体字段值一起带出去，
+     * 而不是等用户截图发现。附在 payload 上而不是抛错：展示层不应因自检而白屏。
+     */
+    const violations = aggregateInvariantViolations(snapshot, phase);
     return {
         sessionId: session.id,
         planId: record.planId ?? plan?.planId ?? null,
         title: plan?.title ?? record.title ?? '任务进度',
         phase,
+        ...(violations.length ? { violations } : {}),
         degraded: record.degraded === true,
         error: record.error ? truncate(record.error, 2000) : null,
         errors: (record.errors ?? []).slice(-20),
@@ -1024,6 +1049,15 @@ export function reconstructFromSession(session, targetPlanId) {
         phase = 'paused';
     if (cancelled)
         phase = 'cancelled';
+    /*
+     * [1.5.2] 回放也必须走同一套对账。
+     *
+     * 回放曾经因为 `resultSeen=true`（结果消息在会话里）得到 done，而同一时刻的
+     * 实时缓存因为没有这个副作用得到 integrating —— 同一个会话刷新前后翻转。
+     * `reconcilePhase` 让两条链路都以 statuses 为准：全部完成即 done（包括历史上
+     * 「先完成、后收到取消消息」的会话，不再出现「100% + 已取消」）。
+     */
+    phase = reconcilePhase(phase, statuses);
     /*
      * An old plan that was never dispatched used to be relabelled `cancelled`,
      * which also made it permanently unresumable — the card said "已取消" and no
@@ -1195,7 +1229,16 @@ export function createWorkplanRuntime(ctx, options = {}) {
         if (status === 'blocked') {
             record.statuses = markDependentsBlocked(record.plan, record.statuses, subtaskId);
         }
-        record.phase = planPhase(record.statuses);
+        /*
+         * [1.5.2] 这里曾是「100% + 正在收尾」的直接入口。
+         *
+         * 旧代码 `record.phase = planPhase(record.statuses)` 用不到 `resultSeen`，
+         * 所以主 Agent 用 update 工具补完最后一项时得到的 phase 永远是 integrating；
+         * 而这条路径之后不会再派发，也就永远不会写结果消息把它晋升为 done。
+         * 走 `reconcilePhase` 后，全部完成即 done，且已 done 的计划不会被一次
+         * 空更新打回 integrating（T4 实测 A.2 的回退路径）。
+         */
+        record.phase = reconcilePhase(record.phase, record.statuses);
         record.updatedAt = Date.now();
         const snapshot = derivePlanSnapshot(record.statuses);
         return {
@@ -1223,6 +1266,29 @@ export function createWorkplanRuntime(ctx, options = {}) {
         const reason = typeof args?.reason === 'string' && args.reason.trim()
             ? args.reason.trim()
             : '用户取消';
+        /*
+         * [1.5.2] 已完成即终态：取消不再把 100% 的计划改写成「已取消」。
+         *
+         * T4 实测 A.4：2/2 全部 done 的计划被取消后会得到 `phase=cancelled` +
+         * `done=2/2` + `percent=100` —— 又一个「一边说全好了、一边说被取消」的
+         * 自相矛盾组合，且会让本可续跑/查看的完成记录永远退出「已完成」组。
+         * 这里直接把取消变成 no-op 并如实返回 done。
+         */
+        const before = derivePlanSnapshot(record.statuses);
+        if (before.stats.total > 0 && before.stats.done === before.stats.total) {
+            record.phase = 'done';
+            record.updatedAt = Date.now();
+            state.records.set(session.id, record);
+            return {
+                ok: true,
+                planId: record.plan.planId,
+                phase: 'done',
+                reason,
+                alreadyDone: true,
+                abortedRunning: false,
+                stats: before.stats,
+            };
+        }
         if (record.dispatchPromise) {
             /*
              * Cancel must always work.
@@ -1409,9 +1475,14 @@ export function createWorkplanRuntime(ctx, options = {}) {
                 ctx.logger?.warn?.(`dsh-workplan: 写入结果消息失败：${error instanceof Error ? error.message : String(error)}`);
             }
         }
-        if (record.resultWritten && record.statuses.length > 0 && record.statuses.every((item) => item.status === 'done')) {
-            record.phase = 'done';
-        }
+        /*
+         * [1.5.2] 终态不再依赖「结果消息写成功」这个副作用。
+         *
+         * 旧代码只有 `record.resultWritten === true` 时才把 phase 升成 done，
+         * 于是 session.append 抛错（或该轮根本没有派发）就会永久停在 integrating。
+         * 完成语义由 statuses 决定；结果消息只负责持久化，不负责定义完成。
+         */
+        record.phase = reconcilePhase(record.phase, record.statuses);
         /*
          * The model's dispatch result reports the same snapshot the dashboard will
          * show. It used to send `record.stats` while the status list below was read

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-workplan",
-  "version": "1.5.0",
+  "version": "1.5.2",
   "description": "Automatic task decomposition, real department subagents, and a responsive workplan dashboard for DeepSeek Harness.",
   "type": "module",
   "license": "MIT",