dsh-workplan 0.0.0-stage → 1.4.3

package/lib/plan.js

@@ -0,0 +1,1495 @@
+/**
+ * Pure planning helpers for dsh-workplan.
+ *
+ * This module deliberately has no dependency on DeepSeek Harness services. It
+ * owns the plan contract, JSON extraction/validation, the planner prompt, the
+ * durable message format, and the pure status/graph helpers used by the host
+ * runtime and by unit tests.
+ */
+import { randomUUID } from 'node:crypto';
+export const PLAN_VERSION = 1;
+export const MAX_STAGES = 6;
+export const MAX_SUBTASKS = 15;
+export const MAX_CONCURRENT = 5;
+export const MAX_PLAN_JSON_CHARS = 60000;
+export const PLAN_MARKER_BEGIN = '<!-- DSH-WORKPLAN:BEGIN -->';
+export const PLAN_MARKER_END = '<!-- DSH-WORKPLAN:END -->';
+export const RESULT_MARKER_BEGIN = '<!-- DSH-WORKPLAN-RESULT:BEGIN -->';
+export const RESULT_MARKER_END = '<!-- DSH-WORKPLAN-RESULT:END -->';
+export const CANCEL_MARKER_BEGIN = '<!-- DSH-WORKPLAN-CANCEL:BEGIN -->';
+export const CANCEL_MARKER_END = '<!-- DSH-WORKPLAN-CANCEL:END -->';
+export const STATUSES = Object.freeze(['pending', 'in_progress', 'done', 'blocked']);
+export const LIKELIHOODS = Object.freeze(['low', 'medium', 'high']);
+export const DEPARTMENTS = Object.freeze({
+    engineering: { zh: '工程研发', en: 'Engineering' },
+    research: { zh: '研究分析', en: 'Research' },
+    design: { zh: '设计', en: 'Design' },
+    product: { zh: '产品', en: 'Product' },
+    data: { zh: '数据', en: 'Data' },
+    qa: { zh: '质量验证', en: 'QA' },
+    security: { zh: '安全', en: 'Security' },
+    devops: { zh: '运维', en: 'DevOps' },
+    writing: { zh: '文档写作', en: 'Writing' },
+    operations: { zh: '运营', en: 'Operations' },
+    legal: { zh: '法务合规', en: 'Legal' },
+    finance: { zh: '财务', en: 'Finance' },
+});
+export const DEPARTMENT_IDS = Object.freeze(Object.keys(DEPARTMENTS));
+export class PlanError extends Error {
+    code;
+    details;
+    constructor(message, code = 'PLAN_ERROR', details = undefined) {
+        super(message);
+        this.name = 'PlanError';
+        this.code = code;
+        this.details = details;
+    }
+}
+export function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+export function truncate(value, max) {
+    if (typeof value !== 'string')
+        return '';
+    return value.length <= max ? value : `${value.slice(0, Math.max(0, max - 1))}…`;
+}
+export function messageText(message) {
+    if (!message || !Array.isArray(message.content))
+        return '';
+    return message.content
+        .filter((block) => block && block.type === 'text' && typeof block.text === 'string')
+        .map((block) => block.text)
+        .join('\n');
+}
+/*
+ * Lightweight conversational inputs must not start the planning pipeline.
+ *
+ * This is deliberately a conservative, deterministic token list rather than a
+ * model call: a greeting should never pay for a planner request or spawn
+ * department agents. The check only returns true when EVERY meaningful token is
+ * a known greeting/thanks/acknowledgement/farewell. "你好，帮我写代码" keeps
+ * the task text and therefore still gets a plan.
+ */
+const SOCIAL_PHRASES = Object.freeze([
+    'thank you very much',
+    'nice to meet you',
+    'how are you doing',
+    'have a nice day',
+    'see you later',
+    'good afternoon',
+    'good morning',
+    'good evening',
+    "how's it going",
+    'hello there',
+    'hi there',
+    'hey there',
+    'thank you',
+    'see you',
+    'good night',
+    'what\'s up',
+    'thanks a lot',
+    'goodbye',
+    'bye bye',
+    '谢谢你',
+    '谢谢你了',
+    '辛苦了',
+    '麻烦你了',
+    '好久不见',
+    '最近怎么样',
+    '最近好吗',
+    '很高兴认识你',
+    '早上好',
+    '上午好',
+    '中午好',
+    '下午好',
+    '晚上好',
+    '晚安',
+    '早安',
+    '午安',
+    '早点休息',
+    '亲爱的',
+    '大家好',
+    '你好',
+    '您好',
+    '哈喽',
+    '请问',
+    '在吗',
+    '在么',
+    '谢谢',
+    '多谢',
+    '再见',
+    '拜拜',
+    '好的',
+    '收到',
+    '明白了',
+    '没问题',
+    '不客气',
+    '没关系',
+    'hello',
+    'thanks',
+    'thank you',
+    'good morning',
+    'good night',
+    'see you',
+    'okay',
+    'ok',
+    'yes',
+    'yep',
+    'sure',
+    'cool',
+    'great',
+    'nice',
+    'lol',
+    'hey',
+    'hi',
+    'yo',
+    'sup',
+    'thx',
+    'bye',
+    '嗯嗯',
+    '哈哈',
+    '嘿嘿',
+    '呵呵',
+    '老师',
+    '同学',
+    '朋友',
+    '大佬',
+    '老板',
+    '先生',
+    '女士',
+    '好',
+    '行',
+    '可以',
+    '嗯',
+    '哦',
+    '噢',
+    '嗨',
+    '嘿',
+]);
+const SOCIAL_TRAILING_PARTICLES = /[呀啊呢吧啦哦噢嗯哈嘛喽咯哒滴了喔唔嘿呵吗]+$/u;
+export function isSocialMessage(value) {
+    if (typeof value !== 'string')
+        return false;
+    const original = value.trim();
+    if (original.length === 0 || original.length > 60)
+        return false;
+    let rest = original.toLowerCase();
+    for (const phrase of SOCIAL_PHRASES) {
+        if (!rest.includes(phrase))
+            continue;
+        rest = rest.split(phrase).join(' ');
+    }
+    rest = rest.replace(/[\s\p{P}\p{S}]+/gu, '');
+    rest = rest.replace(SOCIAL_TRAILING_PARTICLES, '');
+    return rest.length === 0;
+}
+/*
+ * A bare "continue" carries no new task content. The planner only sees the
+ * current message, so it cannot know what to continue; planning it produces a
+ * huge plan for an unknown object. The main Agent has the conversation history
+ * and should continue directly (or ask which thread), so this gate bypasses the
+ * planner exactly like a social message.
+ */
+const VAGUE_CONTINUATIONS = Object.freeze([
+    'continue',
+    'keep going',
+    'carry on',
+    'go on',
+    'proceed',
+    '继续推进',
+    '继续做',
+    '继续吧',
+    '接着来',
+    '接着做',
+    '往下推进',
+    '往下做',
+    '然后呢',
+    '接下来',
+    '下一步',
+    '继续',
+    '接着',
+    '往下',
+    '再来',
+    '开始吧',
+    '干吧',
+    'next',
+]);
+export function isVagueContinuation(value) {
+    if (typeof value !== 'string')
+        return false;
+    const original = value.trim();
+    if (original.length === 0 || original.length > 24)
+        return false;
+    let rest = original.toLowerCase();
+    for (const phrase of VAGUE_CONTINUATIONS) {
+        if (!rest.includes(phrase))
+            continue;
+        rest = rest.split(phrase).join(' ');
+    }
+    rest = rest.replace(/[\s\p{P}\p{S}]+/gu, '');
+    if (rest.length === 0)
+        return true;
+    /*
+     * "B继续" / "按B继续" / "方案B继续" continue a decision already made in the
+     * conversation. The main Agent can see that decision; the planner only sees
+     * this short message, so planning it invents a huge new task. Require a short
+     * tail so "继续修复这个 bug" is still planned.
+     */
+    const compact = original.toLowerCase().replace(/[\s\p{P}\p{S}]+/gu, '');
+    if (/继续|接着|往下|下一步/.test(compact)) {
+        const tail = compact.replace(/继续|接着|往下|下一步|方案|按照|按|就|吧|呀|啊|呢/g, '');
+        if (tail.length <= 2)
+            return true;
+    }
+    return false;
+}
+/*
+ * A status question asks about work already recorded; planning and dispatching
+ * it creates a second plan about the first plan and is guaranteed to feed back
+ * on itself. The main Agent can answer it from the session log/dashboard, so
+ * this gate bypasses the planner. It deliberately requires a question/status
+ * form so a real repair task such as "修复卡住的任务" still gets planned.
+ */
+const STATUS_PATTERNS = Object.freeze([
+    /完成(了)?(吗|么|没有|没|嘛)/,
+    /(全部|全都|都|已经).{0,6}完成/,
+    /(做|写|改|修)(完|好)(了)?(吗|么|没有|没|嘛)/,
+    /进度(如何|怎么样|多少|到哪|呢|吗)?/,
+    /卡住(了)?(吗|么|没有|没|嘛)?/,
+    /(还|剩)(有|下|余)?.{0,6}(多少|几|什么|哪些)/,
+    /是否.{0,8}(完成|做完|卡住|进行|通过)/,
+    /正确(吗|么|不)/,
+    /(显示|数字|统计|具体工作).{0,12}(正确|对不上|不一致|不对)/,
+    /(对不上|不一致)(吗|么|？|\?)/,
+    /(status|progress|done yet|completed|how many.*(left|remain)|what.*(left|remain))/i,
+]);
+export function isStatusQuestion(value) {
+    if (typeof value !== 'string')
+        return false;
+    const original = value.trim();
+    if (original.length === 0 || original.length > 120)
+        return false;
+    const looksLikeQuestion = /[?？]/.test(original)
+        || /(吗|呢|没有|是否|多少|几|如何|怎么样|到哪)/.test(original)
+        || /^(查|看|告诉我|确认|核对).{0,8}(进度|状态|完成|卡住)/.test(original);
+    if (!looksLikeQuestion)
+        return false;
+    // A request to change/repair the progress UI is a real task, not a status
+    // question, even though it contains the word 进度.
+    if (/(改进|优化|设计|修复|实现|增加|调整|开发|重构|排查|诊断|改造|排版)/.test(original))
+        return false;
+    return STATUS_PATTERNS.some((pattern) => pattern.test(original));
+}
+function push(errors, path, message) {
+    errors.push(`${path}: ${message}`);
+}
+function readString(value, path, min, max, errors) {
+    if (typeof value !== 'string') {
+        push(errors, path, '必须是字符串');
+        return '';
+    }
+    const text = value.trim();
+    if (text.length < min) {
+        push(errors, path, `长度不能小于 ${min}`);
+        return text;
+    }
+    if (text.length > max) {
+        push(errors, path, `长度不能超过 ${max}`);
+        return text.slice(0, max);
+    }
+    return text;
+}
+function readStringArray(value, path, options, errors) {
+    const opts = { min: 0, max: 20, itemMax: 2000, ...options };
+    if (!Array.isArray(value)) {
+        push(errors, path, '必须是字符串数组');
+        return [];
+    }
+    if (value.length < opts.min)
+        push(errors, path, `至少需要 ${opts.min} 项`);
+    if (value.length > opts.max)
+        push(errors, path, `最多允许 ${opts.max} 项`);
+    const out = [];
+    value.slice(0, opts.max).forEach((item, index) => {
+        if (typeof item !== 'string') {
+            push(errors, `${path}[${index}]`, '必须是字符串');
+            return;
+        }
+        const text = item.trim();
+        if (text.length === 0) {
+            push(errors, `${path}[${index}]`, '不能为空');
+            return;
+        }
+        if (text.length > opts.itemMax) {
+            push(errors, `${path}[${index}]`, `长度不能超过 ${opts.itemMax}`);
+            out.push(text.slice(0, opts.itemMax));
+            return;
+        }
+        out.push(text);
+    });
+    return out;
+}
+function readEnum(value, path, allowed, errors) {
+    if (!allowed.includes(value)) {
+        push(errors, path, `必须是 ${allowed.join(' / ')} 之一`);
+        return allowed[0];
+    }
+    return value;
+}
+function readTaskUnderstanding(value, errors) {
+    const source = isRecord(value) ? value : {};
+    if (!isRecord(value))
+        push(errors, 'taskUnderstanding', '必须是对象');
+    return {
+        originalRequest: readString(source.originalRequest, 'taskUnderstanding.originalRequest', 1, 8000, errors),
+        deliverable: readString(source.deliverable, 'taskUnderstanding.deliverable', 1, 2000, errors),
+        successCriteria: readStringArray(source.successCriteria, 'taskUnderstanding.successCriteria', { min: 1, max: 20, itemMax: 600 }, errors),
+        constraints: readStringArray(source.constraints, 'taskUnderstanding.constraints', { min: 0, max: 20, itemMax: 600 }, errors),
+        knownFacts: readStringArray(source.knownFacts, 'taskUnderstanding.knownFacts', { min: 0, max: 20, itemMax: 600 }, errors),
+        unknowns: readStringArray(source.unknowns, 'taskUnderstanding.unknowns', { min: 0, max: 20, itemMax: 600 }, errors),
+        assumptions: readStringArray(source.assumptions, 'taskUnderstanding.assumptions', { min: 0, max: 20, itemMax: 600 }, errors),
+    };
+}
+function readContradictions(value, errors) {
+    const source = isRecord(value) ? value : {};
+    if (!isRecord(value))
+        push(errors, 'contradictions', '必须是对象');
+    const primary = isRecord(source.primary) ? source.primary : {};
+    if (!isRecord(source.primary))
+        push(errors, 'contradictions.primary', '必须是对象');
+    return {
+        primary: {
+            statement: readString(primary.statement, 'contradictions.primary.statement', 1, 1200, errors),
+            evidence: readStringArray(primary.evidence, 'contradictions.primary.evidence', { min: 1, max: 10, itemMax: 800 }, errors),
+            whyPrimary: readString(primary.whyPrimary, 'contradictions.primary.whyPrimary', 1, 1200, errors),
+        },
+        secondary: readStringArray(source.secondary, 'contradictions.secondary', { min: 0, max: 10, itemMax: 800 }, errors),
+        transformationConditions: readStringArray(source.transformationConditions, 'contradictions.transformationConditions', { min: 0, max: 10, itemMax: 800 }, errors),
+    };
+}
+function readSubtasks(value, stageIndex, errors) {
+    const path = `stages[${stageIndex}].subtasks`;
+    if (!Array.isArray(value)) {
+        push(errors, path, '必须是数组');
+        return [];
+    }
+    if (value.length < 1)
+        push(errors, path, '每个阶段至少需要 1 个子任务');
+    if (value.length > MAX_SUBTASKS)
+        push(errors, path, `最多允许 ${MAX_SUBTASKS} 个子任务`);
+    return value.slice(0, MAX_SUBTASKS).map((item, index) => {
+        const source = isRecord(item) ? item : {};
+        const base = `${path}[${index}]`;
+        if (!isRecord(item))
+            push(errors, base, '必须是对象');
+        const department = typeof source.department === 'string'
+            ? source.department
+            : '';
+        if (!DEPARTMENTS[department]) {
+            push(errors, `${base}.department`, `必须是 ${DEPARTMENT_IDS.join(' / ')} 之一`);
+        }
+        return {
+            id: readString(source.id, `${base}.id`, 1, 16, errors),
+            title: readString(source.title, `${base}.title`, 1, 200, errors),
+            department,
+            role: readString(source.role, `${base}.role`, 1, 200, errors),
+            objective: readString(source.objective, `${base}.objective`, 1, 2000, errors),
+            method: readStringArray(source.method, `${base}.method`, { min: 1, max: 8, itemMax: 800 }, errors),
+            inputs: readStringArray(source.inputs, `${base}.inputs`, { min: 0, max: 12, itemMax: 800 }, errors),
+            outputs: readStringArray(source.outputs, `${base}.outputs`, { min: 1, max: 12, itemMax: 800 }, errors),
+            dependsOn: readStringArray(source.dependsOn, `${base}.dependsOn`, { min: 0, max: 12, itemMax: 16 }, errors),
+            acceptance: readStringArray(source.acceptance, `${base}.acceptance`, { min: 1, max: 8, itemMax: 800 }, errors),
+            risk: readString(source.risk, `${base}.risk`, 1, 1000, errors),
+        };
+    });
+}
+function readStages(value, errors) {
+    if (!Array.isArray(value)) {
+        push(errors, 'stages', '必须是数组');
+        return [];
+    }
+    if (value.length < 1 || value.length > MAX_STAGES) {
+        push(errors, 'stages', `数量必须为 1-${MAX_STAGES}`);
+    }
+    return value.slice(0, MAX_STAGES).map((item, index) => {
+        const source = isRecord(item) ? item : {};
+        const base = `stages[${index}]`;
+        if (!isRecord(item))
+            push(errors, base, '必须是对象');
+        return {
+            id: readString(source.id, `${base}.id`, 1, 16, errors),
+            name: readString(source.name, `${base}.name`, 1, 200, errors),
+            goal: readString(source.goal, `${base}.goal`, 1, 1200, errors),
+            rationale: readString(source.rationale, `${base}.rationale`, 1, 1200, errors),
+            checkpoint: readString(source.checkpoint, `${base}.checkpoint`, 1, 1200, errors),
+            subtasks: readSubtasks(source.subtasks, index, errors),
+        };
+    });
+}
+function readRisks(value, errors) {
+    if (!Array.isArray(value)) {
+        push(errors, 'risks', '必须是数组');
+        return [];
+    }
+    if (value.length > 8)
+        push(errors, 'risks', '最多允许 8 项');
+    return value.slice(0, 8).map((item, index) => {
+        const source = isRecord(item) ? item : {};
+        const base = `risks[${index}]`;
+        if (!isRecord(item))
+            push(errors, base, '必须是对象');
+        return {
+            risk: readString(source.risk, `${base}.risk`, 1, 800, errors),
+            likelihood: readEnum(source.likelihood, `${base}.likelihood`, LIKELIHOODS, errors),
+            impact: readString(source.impact, `${base}.impact`, 1, 800, errors),
+            mitigation: readString(source.mitigation, `${base}.mitigation`, 1, 800, errors),
+            trigger: readString(source.trigger, `${base}.trigger`, 1, 800, errors),
+        };
+    });
+}
+function readVerification(value, errors) {
+    if (!Array.isArray(value)) {
+        push(errors, 'verification', '必须是数组');
+        return [];
+    }
+    if (value.length < 1)
+        push(errors, 'verification', '至少需要 1 项');
+    if (value.length > 12)
+        push(errors, 'verification', '最多允许 12 项');
+    return value.slice(0, 12).map((item, index) => {
+        const source = isRecord(item) ? item : {};
+        const base = `verification[${index}]`;
+        if (!isRecord(item))
+            push(errors, base, '必须是对象');
+        return {
+            item: readString(source.item, `${base}.item`, 1, 600, errors),
+            method: readString(source.method, `${base}.method`, 1, 800, errors),
+            evidence: readString(source.evidence, `${base}.evidence`, 1, 800, errors),
+        };
+    });
+}
+function readPracticeLoop(value, errors) {
+    const source = isRecord(value) ? value : {};
+    if (!isRecord(value))
+        push(errors, 'practiceLoop', '必须是对象');
+    return {
+        plan: readString(source.plan, 'practiceLoop.plan', 1, 800, errors),
+        do: readString(source.do, 'practiceLoop.do', 1, 800, errors),
+        check: readString(source.check, 'practiceLoop.check', 1, 800, errors),
+        act: readString(source.act, 'practiceLoop.act', 1, 800, errors),
+    };
+}
+function checkPlanGraph(plan, errors) {
+    const stageIds = new Set();
+    const subtaskIds = new Set();
+    const order = new Map();
+    const dependencies = new Map();
+    let nextOrder = 0;
+    let total = 0;
+    for (const [stageIndex, stage] of plan.stages.entries()) {
+        if (!stage.id) {
+            push(errors, `stages[${stageIndex}].id`, '不能为空');
+            continue;
+        }
+        if (stageIds.has(stage.id)) {
+            push(errors, `stages[${stageIndex}].id`, `阶段 ID 重复：${stage.id}`);
+        }
+        stageIds.add(stage.id);
+        for (const [subtaskIndex, subtask] of stage.subtasks.entries()) {
+            const base = `stages[${stageIndex}].subtasks[${subtaskIndex}]`;
+            total += 1;
+            if (!subtask.id) {
+                push(errors, `${base}.id`, '不能为空');
+                continue;
+            }
+            if (subtaskIds.has(subtask.id)) {
+                push(errors, `${base}.id`, `子任务 ID 重复：${subtask.id}`);
+            }
+            subtaskIds.add(subtask.id);
+            order.set(subtask.id, nextOrder);
+            dependencies.set(subtask.id, subtask.dependsOn);
+            nextOrder += 1;
+        }
+    }
+    if (total < 1)
+        push(errors, 'stages', '至少需要 1 个子任务');
+    if (total > MAX_SUBTASKS)
+        push(errors, 'stages', `子任务总数不能超过 ${MAX_SUBTASKS}`);
+    for (const [stageIndex, stage] of plan.stages.entries()) {
+        for (const [subtaskIndex, subtask] of stage.subtasks.entries()) {
+            const base = `stages[${stageIndex}].subtasks[${subtaskIndex}]`;
+            for (const dependency of subtask.dependsOn) {
+                if (!order.has(dependency)) {
+                    push(errors, `${base}.dependsOn`, `未知子任务依赖：${dependency}`);
+                    continue;
+                }
+                if (order.get(dependency) >= order.get(subtask.id)) {
+                    push(errors, `${base}.dependsOn`, `依赖必须位于更早阶段或更早位置：${dependency}`);
+                }
+            }
+        }
+    }
+    const visiting = new Set();
+    const visited = new Set();
+    function visit(id) {
+        if (visited.has(id))
+            return;
+        if (visiting.has(id)) {
+            push(errors, 'stages', `依赖存在环：${id}`);
+            return;
+        }
+        visiting.add(id);
+        for (const dependency of dependencies.get(id) ?? [])
+            visit(dependency);
+        visiting.delete(id);
+        visited.add(id);
+    }
+    for (const id of dependencies.keys())
+        visit(id);
+    let serialized = '';
+    try {
+        serialized = JSON.stringify(plan);
+    }
+    catch {
+        push(errors, 'plan', '无法序列化为 JSON');
+    }
+    if (serialized.length > MAX_PLAN_JSON_CHARS) {
+        push(errors, 'plan', `计划 JSON 超过 ${MAX_PLAN_JSON_CHARS} 字符，请精简`);
+    }
+}
+/**
+ * Validate an untrusted planner object. Never throws for malformed input.
+ *
+ * @param {unknown} raw
+ * @returns {{ok: true, plan: object} | {ok: false, errors: string[]}}
+ */
+export function validatePlan(raw) {
+    if (!isRecord(raw)) {
+        return { ok: false, errors: ['计划必须是 JSON 对象'] };
+    }
+    const errors = [];
+    if (raw.version !== PLAN_VERSION)
+        errors.push(`version: 必须为 ${PLAN_VERSION}`);
+    const plan = {
+        version: PLAN_VERSION,
+        title: readString(raw.title, 'title', 1, 200, errors),
+        taskUnderstanding: readTaskUnderstanding(raw.taskUnderstanding, errors),
+        contradictions: readContradictions(raw.contradictions, errors),
+        stages: readStages(raw.stages, errors),
+        risks: readRisks(raw.risks, errors),
+        verification: readVerification(raw.verification, errors),
+        practiceLoop: readPracticeLoop(raw.practiceLoop, errors),
+    };
+    checkPlanGraph(plan, errors);
+    if (errors.length > 0)
+        return { ok: false, errors };
+    return { ok: true, plan };
+}
+export function attachPlanMeta(plan, meta) {
+    return {
+        ...plan,
+        planId: meta.planId,
+        sessionId: meta.sessionId,
+        createdTurn: meta.createdTurn,
+        createdAt: meta.createdAt,
+        sourceMessageIds: [...meta.sourceMessageIds],
+    };
+}
+export function flattenSubtasks(plan) {
+    const out = [];
+    for (const stage of plan.stages) {
+        for (const subtask of stage.subtasks) {
+            out.push({ stage, subtask });
+        }
+    }
+    return out;
+}
+export function extractJson(text) {
+    if (typeof text !== 'string' || text.trim() === '') {
+        throw new PlanError('规划器没有返回内容', 'EMPTY_OUTPUT');
+    }
+    let value = text.trim();
+    const fenced = value.match(/```(?:json)?\s*([\s\S]*?)```/i);
+    if (fenced)
+        value = fenced[1].trim();
+    const first = value.indexOf('{');
+    const last = value.lastIndexOf('}');
+    if (first < 0 || last <= first) {
+        throw new PlanError('规划器返回内容中没有 JSON 对象', 'NO_JSON');
+    }
+    const candidate = value.slice(first, last + 1);
+    try {
+        return JSON.parse(candidate);
+    }
+    catch (error) {
+        throw new PlanError(`规划器返回的 JSON 无法解析：${error instanceof Error ? error.message : String(error)}`, 'INVALID_JSON');
+    }
+}
+export function departmentLabel(id, language = 'zh') {
+    const entry = DEPARTMENTS[id];
+    if (!entry)
+        return id;
+    return language === 'en' ? entry.en : entry.zh;
+}
+export function buildPlannerPrompt(taskText, cwd, conversationContext = '') {
+    const departments = DEPARTMENT_IDS
+        .map((id) => { const d = DEPARTMENTS[id]; return `- ${id}（${d.zh} / ${d.en}）`; })
+        .join('\n');
+    const task = truncate(taskText, 16000);
+    const directory = typeof cwd === 'string' && cwd ? cwd : '（未知）';
+    const context = truncate(conversationContext, 7000);
+    return [
+        '你是一个任务分解规划器。请用马克思主义哲学的科学方法分析下面的任务，并只输出一个 JSON 对象。',
+        '',
+        '必须遵守：',
+        '1. 实事求是：knownFacts 只能来自用户输入或可验证事实；不得编造文件、接口、数据或结论。',
+        '2. 抓主要矛盾：找出决定任务成败的核心矛盾，写清证据和“为什么它是主要矛盾”。',
+        '3. 具体问题具体分析：根据任务类型选择部门和方法，不要机械套模板。',
+        '4. 实践—认识—再实践：每个阶段设置检查点，用结果修正后续行动。',
+        '5. 质量互变：把大目标拆成可验收的量变阶段，设置阶段门槛。',
+        '6. 矛盾转化：说明什么条件下次要矛盾会上升为主要矛盾，以及如何应对。',
+        '',
+        '硬性约束：',
+        `- 阶段 1-${MAX_STAGES} 个；子任务总数 1-${MAX_SUBTASKS} 个；每个阶段至少 1 个子任务。`,
+        '- 按任务实际复杂度决定规模：简单任务 1-3 个子任务，复杂任务才展开；不得为了显得细致而堆叠子任务。',
+        '- 子任务 ID 使用 T1、T2…；阶段 ID 使用 S1、S2…；所有 ID 唯一。',
+        '- dependsOn 只能引用更早阶段或更早位置的子任务；不得形成环。',
+        '- dependsOn 只在真正需要前序产出时填写；能独立并行的子任务必须留空，不要为了形式制造依赖链。',
+        '- department 必须从下面的部门中选择一个。',
+        '- method、outputs、acceptance 必须是非空数组；inputs 可以为空，未知写“待确认”。',
+        '- unknowns 和 assumptions 必须如实列出；没有就写空数组，不能把假设写成事实。',
+        '- 子任务必须可独立执行、可验收；不要为了凑数拆无意义任务。',
+        '- 子任务由子 Agent 独立执行：它们没有派发权限、不能重启服务、不能安装或升级依赖。禁止把「调用 dsh_workplan_dispatch」「重启/停止 dsh web」「安装或升级插件」这类只有主 Agent 才能执行的动作写进子任务；确实需要时，写成“给出结论或建议，由主 Agent 执行”。',
+        '- 单个子任务应能在 10 分钟内完成；动手重的任务要拆成多个小步，避免整条计划被一个慢子任务拖住。',
+        '- 不要输出 Markdown 代码围栏、解释或前后缀；只输出一个 JSON 对象。',
+        '',
+        '可用部门：',
+        departments,
+        '',
+        `工作目录：${directory}`,
+        '',
+        '最近对话（只用于理解“它 / 这个 / B / 上一项”等指代，不是新的任务；不要把它当成额外需求）：',
+        context || '（无可用对话背景）',
+        '',
+        '任务：',
+        task,
+        '',
+        '输出 JSON 结构（字段必须齐全，值要具体）：',
+        '{',
+        '  "version": 1,',
+        '  "title": "短标题",',
+        '  "taskUnderstanding": {',
+        '    "originalRequest": "用户原任务复述",',
+        '    "deliverable": "最终交付物",',
+        '    "successCriteria": ["可验收标准"],',
+        '    "constraints": ["约束"],',
+        '    "knownFacts": ["仅来自用户输入或可验证事实"],',
+        '    "unknowns": ["未验证项：如何验证"],',
+        '    "assumptions": ["明确标注的假设"]',
+        '  },',
+        '  "contradictions": {',
+        '    "primary": {',
+        '      "statement": "主要矛盾",',
+        '      "evidence": ["证据"],',
+        '      "whyPrimary": "为什么它决定成败"',
+        '    },',
+        '    "secondary": ["次要矛盾"],',
+        '    "transformationConditions": ["矛盾转化条件"]',
+        '  },',
+        '  "stages": [',
+        '    {',
+        '      "id": "S1",',
+        '      "name": "阶段名",',
+        '      "goal": "阶段目标",',
+        '      "rationale": "为什么需要该阶段",',
+        '      "checkpoint": "阶段检查点",',
+        '      "subtasks": [',
+        '        {',
+        '          "id": "T1",',
+        '          "title": "子任务",',
+        '          "department": "engineering",',
+        '          "role": "部门内角色",',
+        '          "objective": "目标",',
+        '          "method": ["具体方法/步骤"],',
+        '          "inputs": ["输入；未知写待确认"],',
+        '          "outputs": ["输出/交付物"],',
+        '          "dependsOn": [],',
+        '          "acceptance": ["可测试的验收标准"],',
+        '          "risk": "主要风险"',
+        '        }',
+        '      ]',
+        '    }',
+        '  ],',
+        '  "risks": [',
+        '    {',
+        '      "risk": "风险",',
+        '      "likelihood": "low",',
+        '      "impact": "影响",',
+        '      "mitigation": "缓解",',
+        '      "trigger": "触发信号"',
+        '    }',
+        '  ],',
+        '  "verification": [',
+        '    { "item": "验证项", "method": "方法", "evidence": "证据形式" }',
+        '  ],',
+        '  "practiceLoop": {',
+        '    "plan": "计划",',
+        '    "do": "执行",',
+        '    "check": "检查",',
+        '    "act": "修正"',
+        '  }',
+        '}',
+    ].join('\n');
+}
+export function makeUserMessage(text, source) {
+    return {
+        id: randomUUID(),
+        role: 'user',
+        content: [{ type: 'text', text }],
+        source,
+    };
+}
+export function buildPlanSummary(plan) {
+    const total = flattenSubtasks(plan).length;
+    const primary = plan.contradictions.primary.statement;
+    return truncate(`【任务分解】${plan.title}｜${plan.stages.length} 个阶段 / ${total} 个子任务｜主要矛盾：${primary}`, 300);
+}
+export function buildPlanMessage(plan) {
+    const summary = buildPlanSummary(plan);
+    const payload = {
+        kind: 'workplan',
+        version: PLAN_VERSION,
+        planId: plan.planId,
+        sessionId: plan.sessionId,
+        createdTurn: plan.createdTurn,
+        createdAt: plan.createdAt,
+        plan,
+    };
+    const text = `${summary}\n\n${PLAN_MARKER_BEGIN}\n${JSON.stringify(payload)}\n${PLAN_MARKER_END}`;
+    return makeUserMessage(text, { kind: 'workplan', form: 'notice', summary });
+}
+export function buildDegradedMessage(options) {
+    const error = truncate(options.error ?? '未知错误', 600);
+    const summary = truncate(`【自动分解降级】${error}`, 300);
+    const payload = {
+        kind: 'workplan',
+        version: PLAN_VERSION,
+        planId: options.planId,
+        sessionId: options.sessionId,
+        createdTurn: options.createdTurn,
+        createdAt: options.createdAt,
+        degraded: true,
+        error,
+        title: '自动分解降级',
+        taskUnderstanding: {
+            originalRequest: truncate(options.taskText ?? '', 2000),
+            deliverable: '未能自动生成计划',
+            successCriteria: [],
+            constraints: [],
+            knownFacts: [],
+            unknowns: ['任务分解失败，需要用户确认是否重试'],
+            assumptions: [],
+        },
+    };
+    const text = [
+        summary,
+        '',
+        '自动任务分解失败，部门 Agent 未启动。',
+        '请先向用户说明失败原因，并询问是否重试；在用户确认前不要开始执行任务。',
+        '',
+        PLAN_MARKER_BEGIN,
+        JSON.stringify(payload),
+        PLAN_MARKER_END,
+    ].join('\n');
+    return makeUserMessage(text, { kind: 'workplan', form: 'notice', summary });
+}
+export function buildResultSummary(result) {
+    const stats = result.stats ?? { done: 0, total: 0, blocked: 0 };
+    return truncate(`【部门执行结果】完成 ${stats.done}/${stats.total}，受阻 ${stats.blocked}，请主 Agent 核对并整合`, 300);
+}
+export function buildResultMessage(result) {
+    const summary = buildResultSummary(result);
+    const payload = {
+        kind: 'workplan-result',
+        version: PLAN_VERSION,
+        planId: result.planId,
+        sessionId: result.sessionId,
+        dispatchedAt: result.dispatchedAt,
+        statuses: result.statuses,
+        errors: result.errors ?? [],
+        stats: result.stats,
+        /*
+         * The round's final phase has to travel with the payload. Without it a
+         * budget pause could not be replayed after a page refresh: `@rebuild`
+         * guessed `executing` from the statuses, the card said "正在做" while
+         * nothing was running, and the pause looked like a stall again.
+         */
+        phase: typeof result.phase === 'string' ? result.phase : undefined,
+        // Carried so a page refresh can still tell "resume budget exhausted" from
+        // "never resumed", instead of promising a retry that will be refused.
+        resumeCount: Number(result.resumeCount ?? 0),
+        resumeAvailable: result.resumeAvailable === true,
+    };
+    const blocked = Number(result.stats?.blocked ?? 0);
+    const paused = Number(result.stats?.pending ?? 0) > 0 && result.phase === 'paused';
+    const lines = [
+        summary,
+        '',
+        '各部门子任务结果如下，请主 Agent：',
+        '1. 核对每个完成项的证据与验收标准；',
+        '2. 处理受阻项，必要时向用户确认；',
+        '3. 给出最终答复，不要声称未验证的完成。',
+        // A blocked plan used to look identical to a finished one. State the exact
+        // recovery move so the model retries the failed work instead of rebuilding
+        // the whole plan or stopping to ask the user for a repeated request.
+        ...(blocked > 0
+            ? [result.resumeAvailable === false
+                    ? `4. 本计划已用尽自动续跑额度（${Number(result.resumeCount ?? 0)}/${MAX_PLAN_RESUMES}），受阻项不会再自动重跑：请主 Agent 直接接手完成，不要重复派发。`
+                    : `4. 受阻项可再次调用 dsh_workplan_dispatch 从受阻处续跑（已完成的不会重跑，本计划剩余续跑额度 ${MAX_PLAN_RESUMES - Number(result.resumeCount ?? 0)} 次）。`]
+            : paused
+                ? [`4. 本轮执行预算用尽，剩余 ${Number(result.stats?.pending ?? 0)} 项未完成（不是失败、未计入续跑额度）：再次调用 dsh_workplan_dispatch 即可从剩下的步骤继续，已完成的不重跑。`]
+                : []),
+        '',
+        RESULT_MARKER_BEGIN,
+        JSON.stringify(payload),
+        RESULT_MARKER_END,
+    ];
+    return makeUserMessage(lines.join('\n'), {
+        kind: 'workplan-result',
+        form: 'notice',
+        summary,
+    });
+}
+function extractBetween(text, begin, end) {
+    if (typeof text !== 'string')
+        return null;
+    const start = text.indexOf(begin);
+    if (start < 0)
+        return null;
+    const finish = text.indexOf(end, start + begin.length);
+    if (finish < 0)
+        return null;
+    return text.slice(start + begin.length, finish).trim();
+}
+export function parseWorkplanMessage(message) {
+    const body = extractBetween(messageText(message), PLAN_MARKER_BEGIN, PLAN_MARKER_END);
+    if (!body)
+        return null;
+    try {
+        const payload = JSON.parse(body);
+        if (!isRecord(payload) || payload.kind !== 'workplan')
+            return null;
+        return payload;
+    }
+    catch {
+        return null;
+    }
+}
+export function parseResultMessage(message) {
+    const body = extractBetween(messageText(message), RESULT_MARKER_BEGIN, RESULT_MARKER_END);
+    if (!body)
+        return null;
+    try {
+        const payload = JSON.parse(body);
+        if (!isRecord(payload) || payload.kind !== 'workplan-result')
+            return null;
+        return payload;
+    }
+    catch {
+        return null;
+    }
+}
+export function buildCancelMessage(planId, reason = '用户取消') {
+    const summary = `【任务已取消】${truncate(String(reason || '用户取消'), 120)}`;
+    const payload = {
+        kind: 'workplan-cancel',
+        version: PLAN_VERSION,
+        planId,
+        reason: String(reason || '用户取消'),
+        cancelledAt: Date.now(),
+    };
+    const lines = [
+        summary,
+        '',
+        '这次任务分解已取消。取消只停止后续执行，不会把未完成项标成完成；已完成项保留原记录。',
+        '',
+        CANCEL_MARKER_BEGIN,
+        JSON.stringify(payload),
+        CANCEL_MARKER_END,
+    ];
+    return makeUserMessage(lines.join('\n'), {
+        kind: 'workplan-cancel',
+        form: 'notice',
+        summary,
+    });
+}
+export function parseCancelMessage(message) {
+    const body = extractBetween(messageText(message), CANCEL_MARKER_BEGIN, CANCEL_MARKER_END);
+    if (!body)
+        return null;
+    try {
+        const payload = JSON.parse(body);
+        if (!isRecord(payload) || payload.kind !== 'workplan-cancel')
+            return null;
+        return payload;
+    }
+    catch {
+        return null;
+    }
+}
+/*
+ * Replay a durable result message into statuses. Dashboard reconstruction used
+ * to read only the plan message, so after a page refresh every finished child
+ * looked pending again (0 done / 0 blocked / 12 pending). The result message is
+ * the only durable record of child outcomes, so it must be folded back too.
+ */
+export function applyResultStatuses(statuses, result) {
+    if (!Array.isArray(statuses) || !result || !Array.isArray(result.statuses))
+        return statuses;
+    let next = statuses;
+    for (const entry of result.statuses) {
+        if (!isRecord(entry) || typeof entry.subtaskId !== 'string')
+            continue;
+        if (!STATUSES.includes(entry.status))
+            continue;
+        if (!next.some((item) => item.subtaskId === entry.subtaskId))
+            continue;
+        try {
+            next = applyStatus(next, entry.subtaskId, {
+                status: entry.status,
+                progress: typeof entry.progress === 'number' ? entry.progress : undefined,
+                childId: entry.childId ?? null,
+                startedAt: entry.startedAt ?? null,
+                finishedAt: entry.finishedAt ?? null,
+                summary: typeof entry.summary === 'string' ? entry.summary : undefined,
+                error: entry.error ?? null,
+            });
+        }
+        catch {
+            // Ignore a single corrupt historical status; the rest still replay.
+        }
+    }
+    return next;
+}
+export function createStatuses(plan) {
+    return flattenSubtasks(plan).map(({ stage, subtask }) => ({
+        subtaskId: subtask.id,
+        stageId: stage.id,
+        title: subtask.title,
+        department: subtask.department,
+        role: subtask.role,
+        status: 'pending',
+        progress: 0,
+        childId: null,
+        startedAt: null,
+        finishedAt: null,
+        summary: '',
+        error: null,
+    }));
+}
+export function applyStatus(statuses, subtaskId, patch) {
+    const index = statuses.findIndex((item) => item.subtaskId === subtaskId);
+    if (index < 0)
+        throw new PlanError(`未知子任务：${subtaskId}`, 'UNKNOWN_SUBTASK');
+    const current = statuses[index];
+    const next = { ...current };
+    if (patch.status !== undefined) {
+        if (!STATUSES.includes(patch.status)) {
+            throw new PlanError(`非法状态：${String(patch.status)}`, 'INVALID_STATUS');
+        }
+        next.status = patch.status;
+    }
+    if (patch.progress !== undefined) {
+        if (!Number.isInteger(patch.progress) || patch.progress < 0 || patch.progress > 100) {
+            throw new PlanError('progress 必须是 0-100 的整数', 'INVALID_PROGRESS');
+        }
+        next.progress = patch.progress;
+    }
+    if (patch.childId !== undefined)
+        next.childId = patch.childId;
+    if (patch.startedAt !== undefined)
+        next.startedAt = patch.startedAt;
+    if (patch.finishedAt !== undefined)
+        next.finishedAt = patch.finishedAt;
+    if (patch.summary !== undefined)
+        next.summary = truncate(String(patch.summary), 3000);
+    if (patch.error !== undefined)
+        next.error = patch.error === null ? null : truncate(String(patch.error), 2000);
+    if (patch.status === 'done') {
+        next.progress = 100;
+        if (next.finishedAt === null)
+            next.finishedAt = Date.now();
+    }
+    if (patch.status === 'pending') {
+        /*
+         * A reset means "back to the initial state", so every companion field of
+         * the previous attempt goes too.
+         *
+         * Leaving `summary` (and, unless the caller asked for one, `error`) behind
+         * made a re-queued subtask read as `pending` while still carrying the
+         * verdict of the attempt that just failed. Explicit values in the same
+         * patch still win, so a caller can attach a reason such as “预算用尽”.
+         */
+        next.progress = 0;
+        next.startedAt = null;
+        next.finishedAt = null;
+        next.childId = null;
+        if (patch.summary === undefined)
+            next.summary = '';
+        if (patch.error === undefined)
+            next.error = null;
+    }
+    if (patch.status === 'in_progress' && next.startedAt === null) {
+        next.startedAt = Date.now();
+    }
+    if (patch.status === 'blocked' && next.finishedAt === null) {
+        next.finishedAt = Date.now();
+    }
+    const copy = statuses.slice();
+    copy[index] = next;
+    return copy;
+}
+export function isSubtaskStatus(value) {
+    return typeof value === 'string' && STATUSES.includes(value);
+}
+/** Clamp anything to an integer in `[0, 100]`; non-finite input counts as 0. */
+export function clampProgress(value) {
+    const numeric = Number(value);
+    if (!Number.isFinite(numeric))
+        return 0;
+    return Math.min(100, Math.max(0, Math.round(numeric)));
+}
+function numberOrNull(value) {
+    if (value === null || value === undefined)
+        return null;
+    const numeric = Number(value);
+    return Number.isFinite(numeric) ? numeric : null;
+}
+function stringOr(value, fallback) {
+    return typeof value === 'string' ? value : fallback;
+}
+/**
+ * Structurally normalise one entry without touching the clock.
+ *
+ * Rules mirror the write path in `applyStatus`:
+ * - an unknown status becomes `pending` (otherwise the four counters sum to
+ *   less than `total`, which is how a corrupt entry used to hide itself);
+ * - `pending` carries no progress and no run bookkeeping;
+ * - `done` is progress 100 even if a stale entry stored something else.
+ *
+ * Timestamps are only type-coerced, never filled in: filling them here would
+ * change the payload on every poll just because time passed.
+ */
+export function normaliseStatusEntry(entry) {
+    const source = entry ?? {};
+    const status = isSubtaskStatus(source.status) ? source.status : 'pending';
+    const progress = status === 'done' ? 100 : status === 'pending' ? 0 : clampProgress(source.progress);
+    return {
+        ...source,
+        subtaskId: stringOr(source.subtaskId, ''),
+        stageId: stringOr(source.stageId, ''),
+        title: stringOr(source.title, ''),
+        department: stringOr(source.department, ''),
+        role: stringOr(source.role, ''),
+        status,
+        progress,
+        childId: status === 'pending' ? null : (source.childId ?? null),
+        startedAt: status === 'pending' ? null : numberOrNull(source.startedAt),
+        finishedAt: status === 'pending' ? null : numberOrNull(source.finishedAt),
+        summary: stringOr(source.summary, ''),
+        error: typeof source.error === 'string' ? source.error : null,
+    };
+}
+/**
+ * Normalise a whole list.
+ *
+ * Entries without an identity (`subtaskId`) are dropped rather than counted: an
+ * entry that cannot be attributed to a subtask would inflate `total` and make
+ * every ratio on the dashboard lie.
+ */
+export function normaliseStatuses(statuses) {
+    const list = Array.isArray(statuses) ? statuses : [];
+    const result = [];
+    for (const entry of list) {
+        if (entry === null || entry === undefined || typeof entry !== 'object')
+            continue;
+        const normalised = normaliseStatusEntry(entry);
+        if (normalised.subtaskId.trim() === '')
+            continue;
+        result.push(normalised);
+    }
+    return result;
+}
+/**
+ * Count in one pass.
+ *
+ * Overall progress weights by status instead of trusting the stored number:
+ * `done` counts as 100, `in_progress` / `blocked` as their own (clamped)
+ * progress, `pending` as 0. A subtask that was rewound to `pending` can
+ * therefore never drag the plan's percentage up to where the cards say it is
+ * finished — that was the “100% 但 11/12” contradiction users saw.
+ */
+export function deriveAggregates(statuses) {
+    const departments = new Map();
+    let done = 0;
+    let blocked = 0;
+    let inProgress = 0;
+    let pending = 0;
+    let progressSum = 0;
+    for (const item of statuses) {
+        if (item.status === 'done') {
+            done += 1;
+            progressSum += 100;
+        }
+        else if (item.status === 'blocked') {
+            blocked += 1;
+            progressSum += clampProgress(item.progress);
+        }
+        else if (item.status === 'in_progress') {
+            inProgress += 1;
+            progressSum += clampProgress(item.progress);
+        }
+        else {
+            pending += 1;
+        }
+        const department = departments.get(item.department) ?? {
+            id: item.department,
+            total: 0,
+            done: 0,
+            blocked: 0,
+            inProgress: 0,
+        };
+        department.total += 1;
+        if (item.status === 'done')
+            department.done += 1;
+        else if (item.status === 'blocked')
+            department.blocked += 1;
+        else if (item.status === 'in_progress')
+            department.inProgress += 1;
+        departments.set(item.department, department);
+    }
+    const total = statuses.length;
+    return {
+        stats: {
+            total,
+            done,
+            blocked,
+            inProgress,
+            pending,
+            progress: total === 0 ? 0 : Math.round(progressSum / total),
+        },
+        departments: [...departments.values()],
+    };
+}
+/**
+ * The one entry point used when a plan is serialised.
+ *
+ * Input is read once, normalised once and aggregated once; the three returned
+ * values share one array instance, so `stats`, `departments` and `statuses` in
+ * a single payload cannot disagree.
+ */
+export function derivePlanSnapshot(raw) {
+    const statuses = normaliseStatuses(raw);
+    const { stats, departments } = deriveAggregates(statuses);
+    return { statuses, stats, departments };
+}
+/**
+ * Compatibility alias for callers that only need the counts.
+ *
+ * @deprecated Prefer `derivePlanSnapshot(statuses).stats` so the caller counts
+ * the exact array it is about to ship.
+ */
+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.
+ *
+ * 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.
+ */
+export function aggregateInvariantViolations(snapshot) {
+    const violations = [];
+    const { statuses, stats, departments } = snapshot;
+    if (stats.total !== statuses.length) {
+        violations.push(`I1 stats.total=${stats.total} 与 statuses.length=${statuses.length} 不一致`);
+    }
+    const counted = stats.done + stats.blocked + stats.inProgress + stats.pending;
+    if (counted !== stats.total) {
+        violations.push(`I2 四个状态计数之和=${counted} 与 total=${stats.total} 不一致`);
+    }
+    for (const key of ['total', 'done', 'blocked', 'inProgress', 'pending']) {
+        const value = stats[key];
+        if (!Number.isInteger(value) || value < 0)
+            violations.push(`I3 stats.${key}=${String(value)} 不是非负整数`);
+    }
+    if (!Number.isInteger(stats.progress) || stats.progress < 0 || stats.progress > 100) {
+        violations.push(`I4 stats.progress=${String(stats.progress)} 不在 0..100`);
+    }
+    const seen = new Set();
+    for (const item of statuses) {
+        if (item.subtaskId === '')
+            violations.push('I5 存在 subtaskId 为空的条目');
+        if (seen.has(item.subtaskId))
+            violations.push(`I5 subtaskId 重复：${item.subtaskId}`);
+        seen.add(item.subtaskId);
+        if (!Number.isInteger(item.progress) || item.progress < 0 || item.progress > 100) {
+            violations.push(`I4 ${item.subtaskId}.progress=${String(item.progress)} 不在 0..100`);
+        }
+        if (item.status === 'pending') {
+            if (item.progress !== 0)
+                violations.push(`I6 ${item.subtaskId} 是 pending 但 progress=${item.progress}`);
+            if (item.childId !== null)
+                violations.push(`I6 ${item.subtaskId} 是 pending 但仍有 childId`);
+            if (item.startedAt !== null)
+                violations.push(`I6 ${item.subtaskId} 是 pending 但仍有 startedAt`);
+            if (item.finishedAt !== null)
+                violations.push(`I6 ${item.subtaskId} 是 pending 但仍有 finishedAt`);
+        }
+        if (item.status === 'done' && item.progress !== 100) {
+            violations.push(`I6 ${item.subtaskId} 是 done 但 progress=${item.progress}`);
+        }
+    }
+    const sums = { total: 0, done: 0, blocked: 0, inProgress: 0 };
+    for (const department of departments) {
+        sums.total += department.total;
+        sums.done += department.done;
+        sums.blocked += department.blocked;
+        sums.inProgress += department.inProgress;
+        const pendingHere = statuses.filter((item) => item.department === department.id && item.status === 'pending').length;
+        if (department.total !== department.done + department.blocked + department.inProgress + pendingHere) {
+            violations.push(`I7 部门 ${department.id} 的计数之和与 total 不一致`);
+        }
+    }
+    if (sums.total !== stats.total)
+        violations.push(`I7 各部门 total 之和=${sums.total} 与 stats.total=${stats.total} 不一致`);
+    if (sums.done !== stats.done)
+        violations.push(`I7 各部门 done 之和=${sums.done} 与 stats.done=${stats.done} 不一致`);
+    if (sums.blocked !== stats.blocked)
+        violations.push(`I7 各部门 blocked 之和=${sums.blocked} 与 stats.blocked=${stats.blocked} 不一致`);
+    if (sums.inProgress !== stats.inProgress) {
+        violations.push(`I7 各部门 inProgress 之和=${sums.inProgress} 与 stats.inProgress=${stats.inProgress} 不一致`);
+    }
+    return violations;
+}
+export function planPhase(statuses, resultSeen = false) {
+    if (statuses.length === 0)
+        return 'pending';
+    if (statuses.every((item) => item.status === 'done'))
+        return resultSeen ? 'done' : 'integrating';
+    if (statuses.some((item) => item.status === 'blocked'))
+        return 'blocked';
+    if (statuses.some((item) => item.status === 'in_progress' || item.status === 'done'))
+        return 'executing';
+    return 'pending';
+}
+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);
+    if (!stage)
+        return [];
+    return stage.subtasks.filter((subtask) => {
+        const status = byId.get(subtask.id);
+        if (!status || status.status !== 'pending')
+            return false;
+        return subtask.dependsOn.every((dependency) => byId.get(dependency)?.status === 'done');
+    });
+}
+/*
+ * Readiness across the whole plan, not per stage. A stage is only a grouping
+ * label; making every later stage wait for every earlier stage lets one slow
+ * child turn an entire plan red. Only real dependsOn edges gate a subtask.
+ */
+export function readySubtasks(plan, statuses) {
+    const byId = new Map(statuses.map((item) => [item.subtaskId, item]));
+    return flattenSubtasks(plan)
+        .map((entry) => entry.subtask)
+        .filter((subtask) => {
+        const status = byId.get(subtask.id);
+        if (!status || status.status !== 'pending')
+            return false;
+        return subtask.dependsOn.every((dependency) => byId.get(dependency)?.status === 'done');
+    });
+}
+export function markDependentsBlocked(plan, statuses, blockedId) {
+    let next = statuses.slice();
+    let changed = true;
+    const blocked = new Set([blockedId]);
+    while (changed) {
+        changed = false;
+        for (const { subtask } of flattenSubtasks(plan)) {
+            if (blocked.has(subtask.id))
+                continue;
+            const status = next.find((item) => item.subtaskId === subtask.id);
+            if (!status || status.status !== 'pending')
+                continue;
+            if (subtask.dependsOn.some((dependency) => blocked.has(dependency))) {
+                next = applyStatus(next, subtask.id, {
+                    status: 'blocked',
+                    error: `上游子任务受阻：${subtask.dependsOn.filter((id) => blocked.has(id)).join('、')}`,
+                });
+                blocked.add(subtask.id);
+                changed = true;
+            }
+        }
+    }
+    return next;
+}
+/**
+ * How many times one plan may be re-dispatched after it went blocked.
+ *
+ * Re-dispatch used to be a silent no-op: every subtask was already `blocked`,
+ * `readySubtasks()` returned nothing, and the dispatcher returned
+ * `{ ok: true, phase: 'blocked' }` without running a single child. A model that
+ * followed the prompt ("核对结果后再继续") could not tell "nothing ran" apart
+ * from "everything already ran", so the plan stayed dead and the only recovery
+ * was asking the user to repeat the request — which built a fresh plan and hit
+ * the same wall.
+ */
+export const MAX_PLAN_RESUMES = 4;
+/**
+ * Reset every failed or half-run subtask to `pending` so it can run again.
+ *
+ * `done` results are preserved: the retry is a resume, not a restart. That
+ * matters because a child may take minutes of real work, and re-running it
+ * would also re-run its side effects.
+ *
+ * @param statuses - the current status list.
+ * @returns a new status list with blocked/in_progress entries cleared.
+ */
+export function resetBlockedStatuses(statuses) {
+    if (!Array.isArray(statuses))
+        return [];
+    let next = statuses.slice();
+    for (const item of statuses) {
+        if (item?.status !== 'blocked' && item?.status !== 'in_progress')
+            continue;
+        next = applyStatus(next, item.subtaskId, {
+            status: 'pending',
+            progress: 0,
+            error: null,
+            summary: '',
+            startedAt: null,
+            finishedAt: null,
+            childId: null,
+        });
+    }
+    return next;
+}
+/**
+ * Decide whether re-dispatching this plan should resume the failed subtasks.
+ *
+ * Cancellation is never resumed automatically: a user cancel and a turn abort
+ * both end in `cancelled`, and silently restarting work the user stopped is
+ * worse than asking again. Both `blocked` and `paused` plans resume.
+ *
+ * @param record - the live plan record.
+ * @param maxResumes - resume budget, defaults to {@link MAX_PLAN_RESUMES}.
+ * @returns the decision plus a model-readable reason when refused.
+ */
+export function canResumePlan(record, maxResumes = MAX_PLAN_RESUMES) {
+    const statuses = Array.isArray(record?.statuses) ? record.statuses : [];
+    /*
+     * A `paused` plan is resumable too.
+     *
+     * Running out of the round budget leaves the unfinished subtasks `pending` on
+     * purpose, so before this they were invisible here: the payload said
+     * `resumeAvailable: false` and the card told the user the automatic resume
+     * budget was spent, even though re-dispatching simply continues the work.
+     * Pending work after a pause counts as resumable, and a pause is not charged
+     * against the resume budget (it is a time slice, not a repair).
+     */
+    const paused = record?.phase === 'paused';
+    const failed = statuses.filter((item) => {
+        if (item?.status === 'blocked' || item?.status === 'in_progress')
+            return true;
+        return paused && item?.status === 'pending';
+    });
+    const used = Number(record?.resumeCount ?? 0);
+    if (failed.length === 0) {
+        return { resume: false, reason: '没有需要续跑的子任务', failed: 0, used, remaining: maxResumes - used };
+    }
+    if (record?.phase !== 'blocked' && !paused) {
+        return {
+            resume: false,
+            reason: `计划当前阶段是 ${String(record?.phase ?? 'unknown')}，不能续跑`,
+            failed: failed.length,
+            used,
+            remaining: maxResumes - used,
+        };
+    }
+    if (!paused && used >= maxResumes) {
+        return {
+            resume: false,
+            reason: `续跑次数已用尽（${used}/${maxResumes}），受阻子任务需要主 Agent 直接接手完成`,
+            failed: failed.length,
+            used,
+            remaining: 0,
+        };
+    }
+    return { resume: true, reason: '', failed: failed.length, used, remaining: maxResumes - used };
+}
+export function findSubtask(plan, subtaskId) {
+    for (const { stage, subtask } of flattenSubtasks(plan)) {
+        if (subtask.id === subtaskId)
+            return { stage, subtask };
+    }
+    return null;
+}
+export function buildChildPrompt({ plan, subtask, stage, dependencyResults, cwd, conversationContext = '' }) {
+    /*
+     * Every field below is read defensively.
+     *
+     * A plan that was reconstructed, resumed, or written by an older version can
+     * legitimately lack `taskUnderstanding` / `contradictions`. Dereferencing them
+     * directly threw inside prompt building, so each child failed instantly and
+     * the whole plan was blocked — a stuck plan caused by missing metadata rather
+     * than by the work being impossible.
+     */
+    const results = Array.isArray(dependencyResults) ? dependencyResults : [];
+    const dependencies = results.length === 0
+        ? '无'
+        : results
+            .map((item) => `- ${item.id} ${item.title}：${item.status}${item.summary ? `｜${item.summary}` : ''}`)
+            .join('\n');
+    const background = truncate(conversationContext, 5000);
+    const understanding = plan?.taskUnderstanding ?? {};
+    const contradiction = plan?.contradictions?.primary?.statement ?? '（未记录）';
+    const stageName = stage?.name ?? '（未命名阶段）';
+    const stageGoal = stage?.goal ?? '（未记录目标）';
+    return [
+        `你是「${departmentLabel(subtask.department)}」部门的执行 Agent，只负责下面这一个子任务。`,
+        '',
+        `全局任务：${understanding.originalRequest ?? '（未记录）'}`,
+        `最终交付物：${understanding.deliverable ?? '（未记录）'}`,
+        `主要矛盾：${contradiction}`,
+        `当前阶段：${stageName}（${stageGoal}）`,
+        `工作目录：${cwd || '（未知）'}`,
+        '',
+        '最近对话背景（用于理解“它 / 这个 / B / 上一项”等指代；不是新的任务）：',
+        background || '（无可用对话背景）',
+        '',
+        `你的子任务：${subtask.id} ${subtask.title}`,
+        `角色：${subtask.role}`,
+        `目标：${subtask.objective}`,
+        `方法：${(subtask.method ?? []).join('；') || '（未指定）'}`,
+        `输入：${Array.isArray(subtask.inputs) && subtask.inputs.length ? subtask.inputs.join('；') : '无明确输入'}`,
+        `输出：${(subtask.outputs ?? []).join('；') || '（未指定）'}`,
+        `验收标准：${(subtask.acceptance ?? []).join('；') || '（未指定）'}`,
+        `风险：${subtask.risk}`,
+        '',
+        '依赖子任务的已知结果：',
+        dependencies,
+        '',
+        '执行要求：',
+        '- 只完成本子任务，不擅自扩大范围；不要派生新的 Agent。',
+        '- 你没有派发权限，也不能重启或安装任何服务；遇到这类步骤，直接写清“需要主 Agent 执行什么”，不要等待或空转。',
+        '- 不得编造事实、文件、命令结果或证据；无法确认时明确写“未验证”。',
+        '- 可以读取工作目录、运行必要命令、修改与任务相关的文件。',
+        '- 优先使用给定上下文和本地工具；只有任务明确需要最新外部信息时才联网搜索。',
+        '- 控制工具调用次数，证据足够就立即汇报；不要反复搜索或等待长时间任务。',
+        '- 如果确实无法完成，第一行输出 `BLOCKED: 原因`，然后简要说明。',
+        '- 完成后用简洁中文汇报：做了什么、证据/文件、验收结果、遗留问题。',
+    ].join('\n');
+}