@hoplogic/hopjit 0.1.0

package/dist/prompt.js

@@ -0,0 +1,1014 @@
+import { hasChildren, getChildren, DEFLATE_THRESHOLD, HUMAN_PREVIEW_THRESHOLD, getParentStepId } from './ast-helpers.js';
+import { serializeActBody } from './act-body-parser.js';
+import { getWriteScope } from './ast-runtime.js';
+import * as nodeFs from 'node:fs';
+import * as nodePath from 'node:path';
+const CHARS_PER_TOKEN = 4;
+const TRUNCATE_MARKER = ' [TRUNCATED]';
+const OUTPUT_VAL_MAX = 60; // 执行链里输出值预览的最大字符数
+const OUTPUT_VAL_ELLIPSIS = '...'; // 超长时的省略号（截断长度 = MAX - 其长度，不再手算 57）
+const AGGRESSIVE_INPUT_MAX = 400; // 预算裁尽仍超时，input 字符串激进截断的上限
+const BUDGET_STANDARD = {
+    l1a: 800, l1b: 0, l2a: 600, l2b: 400, l3: 1200, l4: 600, l5: 400, total: 4000,
+};
+// L2c 重试反馈预算（带反馈重跑时才出现，单条最近失败说明）。见 prompt-assembler ^anc-exec-l2c-retry-feedback
+const L2C_RETRY_FEEDBACK_BUDGET = 300;
+const BUDGET_WITH_KNOWLEDGE = {
+    l1a: 600, l1b: 400, l2a: 600, l2b: 400, l3: 1200, l4: 600, l5: 400, total: 4400,
+};
+/** 上下文组装组件：按步骤类型把引擎运行时状态组成 6 层 AssembledContext（L1-L6）并做 token 预算裁剪，自身不发 API。见 [[prompt-assembler#^anc-exec-prompt-assembly]] */
+export class PromptAssembler {
+    engine;
+    budget;
+    constructor(engine, hasKnowledgeProvider = false) {
+        this.engine = engine;
+        this.budget = hasKnowledgeProvider ? BUDGET_WITH_KNOWLEDGE : BUDGET_STANDARD;
+    }
+    assembleReasonContext(step) {
+        return this.assembleContext(step);
+    }
+    assembleCheckContext(step) {
+        return this.assembleContext(step);
+    }
+    assembleActContext(step) {
+        return this.assembleContext(step);
+    }
+    assembleAdaptiveContext(subtaskId) {
+        const spec = this.engine.getSpec();
+        const subtask = this.findStepById(subtaskId, spec);
+        if (!subtask) {
+            return {
+                task_context: '',
+                progress_summary: '',
+                inputs: {},
+                instruction: 'Replan required.',
+                output_schema: [],
+            };
+        }
+        const taskCtx = this.buildAdaptiveTaskContext(subtask);
+        const progress = this.buildSubtaskProgress(subtask);
+        const inputs = this.resolveInputs(subtask);
+        const instruction = `Replan required. The subtask "${subtask.summary}" failed. Provide new children steps that achieve the same outputs.`;
+        const outputSchema = subtask.outputs ?? [];
+        return {
+            task_context: truncateToChars(taskCtx, this.budget.l1a * CHARS_PER_TOKEN),
+            progress_summary: truncateToChars(progress, this.budget.l2a * CHARS_PER_TOKEN),
+            inputs,
+            instruction,
+            output_schema: outputSchema,
+        };
+    }
+    reassembleAggressive(step) {
+        const spec = this.engine.getSpec();
+        const header = spec.header;
+        // L1a: Goal + direct parent only (1 level)
+        let taskCtx = `Goal: ${header.goal ?? ''}\n`;
+        const parentId = getParentStepId(step.step_id);
+        if (parentId) {
+            const parent = this.findStepById(parentId, spec);
+            if (parent) {
+                const outputs = parent.outputs?.map(o => o.name).join(', ') ?? '';
+                taskCtx += `  ${parent.step_id} [${parent.step_type}] ${parent.summary}${outputs ? ` | + → ${outputs}` : ''}\n`;
+            }
+        }
+        // L2a: dependency-driven progress (aggressive mode still uses same logic)
+        const progress = this.buildProgressSummary(step);
+        // L3: all values truncated to 400 chars (~100 tokens)
+        const inputs = this.resolveInputs(step, 400);
+        return {
+            task_context: taskCtx,
+            progress_summary: progress,
+            inputs,
+            instruction: step.instruction ?? step.summary,
+            output_schema: step.outputs ?? [],
+        };
+    }
+    assembleContext(step) {
+        const budget = this.budget;
+        const taskCtx = this.buildTaskContext(step);
+        const progress = this.buildProgressSummary(step);
+        const iterHistory = this.buildIterationHistory(step);
+        const retryFeedback = this.buildRetryFeedback(step);
+        const inputs = this.resolveInputs(step);
+        const instruction = this.buildInstruction(step);
+        const outputSchema = step.outputs ?? [];
+        let ctx = {
+            task_context: truncateToChars(taskCtx, budget.l1a * CHARS_PER_TOKEN),
+            progress_summary: truncateToChars(progress, budget.l2a * CHARS_PER_TOKEN),
+            inputs,
+            instruction,
+            output_schema: outputSchema,
+        };
+        if (iterHistory) {
+            ctx.iteration_history = truncateToChars(iterHistory, budget.l2b * CHARS_PER_TOKEN);
+        }
+        if (retryFeedback) {
+            ctx.retry_feedback = truncateToChars(retryFeedback, L2C_RETRY_FEEDBACK_BUDGET * CHARS_PER_TOKEN);
+        }
+        ctx = this.applyBudgetTrimming(ctx);
+        return ctx;
+    }
+    // L2c 重试反馈：subtask 带反馈重跑时，注入上次失败说明（check 的 text 槽 / 失败原因），
+    // 让重跑执行者知道"上次错在哪"。首跑（无重试历史）返回 undefined 不渲染。
+    // 见 [[../../HopSpec V3核心规范#^anc-exec-retry-adaptive]] / prompt-assembler ^anc-exec-l2c-retry-feedback
+    // @a: anc-exec-l2c-retry-feedback
+    buildRetryFeedback(step) {
+        const fb = this.engine.getActiveRetryFeedback(step.step_id);
+        if (!fb)
+            return undefined;
+        return `⚠️ 上次尝试失败（第 ${fb.attempt} 次）：${fb.reason}\n→ 本次重跑请针对此修正。`;
+    }
+    // L1 骨架：静态步骤树——step_id+[type]+summary+树结构+容器关键属性，
+    // 不含状态/数据/节点体（←/+→/>）。给 LLM 全局计划地图，与 L3 动态执行链互补。
+    // worker 子实例(subtreeRoot!=null)时裁到子树视图+父 parallel 身份头。
+    // 见 [[../../HopSpec V3核心规范#^anc-exec-l1-skeleton]]
+    /** 渲染骨架单节点（含容器 attr：loop max / subtask retry+adaptive / case condition）+ 递归 children。
+     * buildSpecSkeleton 与 buildSubtreeSkeleton 共用（原两处 render 逐字复制）。 */
+    renderSkeletonNode(node, depth, lines) {
+        const indent = '  '.repeat(depth);
+        let attr = '';
+        if (node.step_type === 'loop') {
+            const m = node.max_iterations;
+            if (m != null)
+                attr = ` max=${m}`;
+        }
+        else if (node.step_type === 'subtask') {
+            const st = node;
+            if (st.retry != null)
+                attr += ` retry=${st.retry}`;
+            if (st.adaptive)
+                attr += ` adaptive`;
+        }
+        else if (node.step_type === 'case') {
+            const c = node.condition;
+            if (c)
+                attr = `: ${c}`;
+        }
+        lines.push(`${indent}${node.step_id}. [${node.step_type}${attr}] ${node.summary}`);
+        if (hasChildren(node)) {
+            for (const child of getChildren(node))
+                this.renderSkeletonNode(child, depth + 1, lines);
+        }
+    }
+    buildSpecSkeleton(spec) {
+        const subtreeRoot = this.engine.getSubtreeRoot();
+        if (subtreeRoot)
+            return this.buildSubtreeSkeleton(spec, subtreeRoot);
+        const lines = [];
+        for (const s of spec.steps ?? [])
+            this.renderSkeletonNode(s, 0, lines);
+        return lines.join('\n');
+    }
+    // worker 子树视图骨架：只渲染目标 child 子树 + 父 parallel 一行身份标注
+    // @a: anc-exec-parallel-worker-prompt, anc-exec-l1-skeleton
+    buildSubtreeSkeleton(spec, subtreeRootId) {
+        const lines = [];
+        const rootNode = this.findStepById(subtreeRootId, spec);
+        if (!rootNode)
+            return '';
+        // 父 parallel 身份标注
+        const parentId = getParentStepId(subtreeRootId);
+        if (parentId) {
+            const parent = this.findStepById(parentId, spec);
+            if (parent) {
+                lines.push(`${parent.step_id}. [${parent.step_type}] ${parent.summary}  ← 你负责 ${subtreeRootId} 分支（与其它分支并行执行，无需关心兄弟）`);
+            }
+        }
+        // 子树骨架
+        this.renderSkeletonNode(rootNode, 1, lines);
+        return lines.join('\n');
+    }
+    buildTaskContext(step) {
+        const spec = this.engine.getSpec();
+        const header = spec.header;
+        // minimal 模式非首步：砍跨步不变的定向段（Goal/Types/Outputs/骨架），保 Constraints（安全底线）+
+        // 祖先位置链（动态锚点）。首步（!hasAnyDone）或 full 模式 → 全量自包含。见 ^anc-exec-context-mode。
+        // @a: anc-exec-context-mode
+        const hasAnyDone = [...this.engine.getStepStates().values()].some(s => s === 'done' || s === 'failed');
+        const lean = this.engine.getContextMode() === 'minimal' && hasAnyDone;
+        let ctx = lean ? '' : `Goal: ${header.goal ?? ''}\n`;
+        if (header.constraints?.length) {
+            ctx += `Constraints: ${header.constraints.join('; ')}\n`; // 安全约束：minimal 也保
+        }
+        if (!lean && header.types?.length) {
+            ctx += `Types: ${header.types.map(t => t.name).join(', ')}\n`;
+        }
+        if (!lean && header.outputs?.length) {
+            ctx += `Outputs: ${header.outputs.map(o => `${o.name}: ${o.type}`).join(', ')}\n`;
+        }
+        // worker 子实例：显式承载子任务目标契约(让 worker 明白自己要交付什么)
+        // @a: anc-exec-parallel-worker-prompt
+        const subtreeRoot = this.engine.getSubtreeRoot();
+        if (subtreeRoot) {
+            const rootNode = this.findStepById(subtreeRoot, spec);
+            if (rootNode) {
+                const deliverables = rootNode.outputs?.map(o => `${o.name}: ${o.type}`).join(', ') ?? '';
+                ctx += `\n[你的子任务] ${rootNode.summary}\n`;
+                if (deliverables)
+                    ctx += `交付输出: ${deliverables}\n`;
+            }
+        }
+        // L1 骨架：静态步骤树，给 LLM 全局计划与自身位置（见 ^anc-exec-l1-skeleton）。minimal 非首步跳过。
+        if (!lean) {
+            const skeleton = this.buildSpecSkeleton(spec);
+            if (skeleton)
+                ctx += `Steps 骨架:\n${skeleton}\n`;
+        }
+        // 祖先链：worker 子实例跳过（子树骨架已含父 parallel 头，祖先链是冗余重复）
+        if (!subtreeRoot) {
+            const ancestors = this.getAncestorChain(step.step_id, spec);
+            const loopCounters = this.engine.getLoopCounters();
+            for (let i = 0; i < ancestors.length; i++) {
+                const a = ancestors[i];
+                const depth = i + 1;
+                const indent = '  '.repeat(depth);
+                const outputs = a.outputs?.map(o => o.name).join(', ') ?? '';
+                let loopTag = '';
+                if (a.step_type === 'loop') {
+                    const iter = loopCounters.get(a.step_id);
+                    const max = a.max_iterations;
+                    if (iter != null)
+                        loopTag = ` (iter ${iter}${max ? '/' + max : ''})`;
+                }
+                if (depth <= 3) {
+                    ctx += `${indent}${a.step_id} [${a.step_type}]${loopTag} ${a.summary}${outputs ? ` | + → ${outputs}` : ''}\n`;
+                }
+                else {
+                    ctx += `${indent}${a.step_id}: ${a.summary}${outputs ? ` → ${outputs}` : ''}\n`;
+                }
+            }
+        }
+        return ctx;
+    }
+    buildProgressSummary(currentStep) {
+        const spec = this.engine.getSpec();
+        const states = this.engine.getStepStates();
+        const hasAnyDone = [...states.values()].some(s => s === 'done' || s === 'failed');
+        if (!hasAnyDone)
+            return 'No steps completed yet.';
+        const fullDisplaySet = this.buildFullDisplaySet(currentStep, spec);
+        const lines = [];
+        for (const step of spec.steps ?? []) {
+            this.renderStepProgress(step, fullDisplaySet, 0, lines);
+        }
+        return lines.join('\n');
+    }
+    buildFullDisplaySet(currentStep, spec) {
+        const depVarNames = currentStep.inputs?.map(i => i.source) ?? [];
+        const depStepIds = this.findProducerSteps(depVarNames, spec);
+        const siblings = this.getSiblingStepIds(currentStep.step_id, spec);
+        const states = this.engine.getStepStates();
+        const doneSiblings = siblings.filter(id => states.get(id) === 'done' || states.get(id) === 'failed');
+        const recentSiblings = doneSiblings.slice(-5);
+        return new Set([...depStepIds, ...recentSiblings]);
+    }
+    renderStepProgress(step, fullDisplaySet, indent, lines) {
+        const states = this.engine.getStepStates();
+        const state = states.get(step.step_id);
+        if (!state || state === 'pending')
+            return;
+        const prefix = '  '.repeat(indent);
+        const isContainer = hasChildren(step);
+        // skipped：L3 是给后继提供可引用产出，未走路径无产出、对后继无价值 → 不显示
+        if (state === 'skipped')
+            return;
+        // branch：折叠为单行——标命中 case + 展开 branch 聚合输出，不展开 case 内部、不显示 skipped case。
+        // @a: anc-exec-l3-branch
+        if (step.step_type === 'branch') {
+            const taken = getChildren(step).find(c => {
+                const cs = states.get(c.step_id);
+                return cs === 'done' || cs === 'running' || cs === 'failed';
+            });
+            const outputVals = this.formatContainerOutputs(step);
+            const hitLabel = taken ? ` ◀ 命中 ${taken.step_id}` : '（无 case 命中，输出 None）';
+            lines.push(`${prefix}✓ ${step.step_id} [branch]: ${step.summary}${hitLabel}${outputVals}`);
+            return;
+        }
+        if (fullDisplaySet.has(step.step_id)) {
+            lines.push(`${prefix}${this.formatStepFull(step)}`);
+        }
+        else if (isContainer && state === 'done') {
+            const outputNames = step.outputs?.map(o => o.name).join(', ') ?? '';
+            lines.push(`${prefix}✓ ${step.step_id} [${step.step_type}]: ${step.summary}${outputNames ? ` → ${outputNames}` : ''}`);
+            return;
+        }
+        else if (state === 'done' || state === 'failed') {
+            const outputNames = step.outputs?.map(o => o.name).join(', ') ?? '';
+            const marker = state === 'done' ? '✓' : '✗';
+            lines.push(`${prefix}${marker} ${step.step_id}${outputNames ? `: ${outputNames}` : ''}`);
+        }
+        else if (state === 'running') {
+            lines.push(`${prefix}▶ ${step.step_id} [${step.step_type}]: ${step.summary}`);
+        }
+        if (isContainer) {
+            for (const child of getChildren(step)) {
+                this.renderStepProgress(child, fullDisplaySet, indent + 1, lines);
+            }
+        }
+    }
+    formatStepFull(step) {
+        const state = this.engine.getStepStates().get(step.step_id);
+        const marker = state === 'done' ? '✓' : state === 'failed' ? '✗' : '▶';
+        const outputVals = (step.outputs && state === 'done') ? this.formatOutputVals(step) : [];
+        return `${marker} ${step.step_id} [${step.step_type}]: ${step.summary}${outputVals.length ? ` → ${outputVals.join(', ')}` : ''}`;
+    }
+    /** 把步骤输出格式化为 `name=值(截断) # desc` 列表——读 scope 变量、JSON.stringify、超长截断。
+     * formatStepFull / formatContainerOutputs 共用（原两处逐字复制）。 */
+    formatOutputVals(step) {
+        const spec = this.engine.getSpec();
+        const vars = this.engine.getVariableStore();
+        const scopeId = getWriteScope(step.step_id, spec);
+        return (step.outputs ?? []).map(o => {
+            const val = vars.read(o.name, scopeId);
+            const str = val != null ? JSON.stringify(val) : 'null';
+            const preview = str.length > OUTPUT_VAL_MAX
+                ? str.slice(0, OUTPUT_VAL_MAX - OUTPUT_VAL_ELLIPSIS.length) + OUTPUT_VAL_ELLIPSIS
+                : str;
+            const desc = o.description ? `  # ${o.description}` : '';
+            return `${o.name}=${preview}${desc}`;
+        });
+    }
+    // 展开容器聚合输出值（branch 折叠展示用）——读容器透传到父 scope 的输出
+    formatContainerOutputs(step) {
+        if (!step.outputs || step.outputs.length === 0)
+            return '';
+        const parts = this.formatOutputVals(step);
+        return parts.length ? ` → ${parts.join(', ')}` : '';
+    }
+    findProducerSteps(varNames, spec) {
+        if (varNames.length === 0)
+            return [];
+        const nameSet = new Set(varNames);
+        const producers = [];
+        const walk = (steps) => {
+            for (const s of steps) {
+                if (s.outputs?.some(o => nameSet.has(o.name)))
+                    producers.push(s.step_id);
+                if (hasChildren(s))
+                    walk(getChildren(s));
+            }
+        };
+        walk(spec.steps ?? []);
+        return producers;
+    }
+    getSiblingStepIds(stepId, spec) {
+        const parentId = getParentStepId(stepId);
+        if (!parentId)
+            return (spec.steps ?? []).map(s => s.step_id);
+        const parent = this.findStepById(parentId, spec);
+        if (!parent || !hasChildren(parent))
+            return [];
+        return getChildren(parent).map(s => s.step_id);
+    }
+    buildIterationHistory(step) {
+        const spec = this.engine.getSpec();
+        const loopAncestor = this.findNearestLoopAncestor(step.step_id, spec);
+        if (!loopAncestor)
+            return undefined;
+        const loopCounters = this.engine.getLoopCounters();
+        const currentIter = loopCounters.get(loopAncestor.step_id) ?? 1;
+        if (currentIter <= 1)
+            return undefined;
+        const log = this.engine.getExecEvents();
+        const loopPrefix = loopAncestor.step_id + '.';
+        // Group log entries by iteration
+        const iterations = [];
+        let iterEntries = [];
+        let lastIter = 0;
+        for (const entry of log) {
+            if (!entry.step_id.startsWith(loopPrefix))
+                continue;
+            if (entry.event === 'step_start' && entry.step_id === loopAncestor.children[0]?.step_id) {
+                if (iterEntries.length > 0)
+                    iterations.push(iterEntries);
+                iterEntries = [];
+                lastIter++;
+            }
+            iterEntries.push(entry);
+        }
+        if (iterEntries.length > 0)
+            iterations.push(iterEntries);
+        if (iterations.length <= 1)
+            return undefined;
+        const lines = [`Loop ${loopAncestor.step_id} — iteration ${currentIter}:`];
+        const recentStart = Math.max(0, iterations.length - 3);
+        for (let i = 0; i < iterations.length - 1; i++) {
+            const iter = iterations[i];
+            const iterNum = i + 1;
+            if (i < recentStart) {
+                const completed = iter.filter(e => e.event === 'step_done').length;
+                const failed = iter.filter(e => e.event === 'step_failed').length;
+                lines.push(`  iter ${iterNum}: ${completed} done, ${failed} failed`);
+            }
+            else {
+                lines.push(`  iter ${iterNum}:`);
+                for (const e of iter) {
+                    if (e.event === 'step_done' || e.event === 'step_failed') {
+                        lines.push(`    ${e.event === 'step_done' ? '✓' : '✗'} ${e.step_id}${e.detail ? ': ' + e.detail : ''}`);
+                    }
+                }
+            }
+        }
+        return lines.join('\n');
+    }
+    // 解析 step 的 ← inputs 取值。两种模式:
+    // - 默认(forceTruncate=undefined):走 agent 通道 deflate——小值原样;大值(>DEFLATE_THRESHOLD=4096)写
+    //   work_zone/vars/<name>.json,返 {$file:abs_path} 指针。LLM 看到指针决定要不要 Read 拿真值。
+    //   见 design/prompt-assembler.md 决策5 ^anc-exec-inputs-deflate / shared-types ^anc-exec-deflate。
+    // - forceTruncate=N(reassembleAggressive 救命模式):用 [TRUNCATED] 强截断到 N 字符,接受信息损失。
+    // 独立模式 workZone 空串 → fallback 原值(无截断无 deflate)。// @a: anc-exec-inputs-deflate
+    resolveInputs(step, forceTruncate) {
+        const spec = this.engine.getSpec();
+        const vars = this.engine.getVariableStore();
+        const scopeId = getWriteScope(step.step_id, spec);
+        const workZone = this.engine.getWorkZone();
+        const inputs = {};
+        if (!step.inputs)
+            return inputs;
+        for (const binding of step.inputs) {
+            const val = vars.read(binding.source, scopeId);
+            if (val === null) {
+                inputs[binding.name] = null;
+                continue;
+            }
+            if (val === undefined) {
+                inputs[binding.name] = undefined;
+                continue;
+            }
+            // 激进救命模式:强截断
+            if (forceTruncate !== undefined) {
+                const str = typeof val === 'string' ? val : (JSON.stringify(val) ?? '');
+                if (str.length > forceTruncate) {
+                    inputs[binding.name] = str.slice(0, forceTruncate - TRUNCATE_MARKER.length) + TRUNCATE_MARKER;
+                }
+                else {
+                    inputs[binding.name] = val;
+                }
+                continue;
+            }
+            // 默认 agent 通道:小值原样,大值 deflate 到 $file
+            const serialized = JSON.stringify(val);
+            if (workZone && serialized && serialized.length > DEFLATE_THRESHOLD) {
+                const filePath = nodePath.join(workZone, 'vars', `${binding.name}.json`);
+                nodeFs.writeFileSync(filePath, serialized, { mode: 0o600 });
+                inputs[binding.name] = { $file: filePath };
+            }
+            else {
+                inputs[binding.name] = val;
+            }
+        }
+        return inputs;
+    }
+    buildInstruction(step) {
+        let base = step.instruction ? `${step.summary}\n${step.instruction}` : step.summary;
+        // call 步骤：附加 callee + 双向映射信息，供 CC 驱动子 spec 调用 // @a: anc-step-call
+        if (step.step_type === 'call') {
+            const call = step;
+            const lines = [`[CALL] callee_spec_id: ${call.callee_spec_id ?? '(unspecified)'}`];
+            if (call.param_mapping?.length) {
+                lines.push('inputs (子参数 ← 父变量): ' + call.param_mapping.map(m => `${m.to} ← ${m.from}`).join(', '));
+            }
+            if (call.output_mapping?.length) {
+                lines.push('outputs (父变量 ← 子输出): ' + call.output_mapping.map(m => `${m.to} ← ${m.from}`).join(', '));
+            }
+            base += '\n' + lines.join('\n');
+        }
+        // act/commit 有结构化 body：复用模式交付 body 文本给 caller（CC）严格按此执行。
+        // body 含工具调用（caller 按 ToolProvider 清单注册的同名工具执行）。// @a: anc-exec-act-body-interp
+        if ((step.step_type === 'act' || step.step_type === 'commit') && step.body) {
+            const bodyText = serializeActBody(step.body);
+            base += '\n\n[ACT BODY — 严格按此 hop_python 逻辑执行，不要重新规划；工具调用对应你按 ToolProvider 清单注册的同名工具]\n```hop_python\n'
+                + bodyText + '\n```';
+        }
+        return base;
+    }
+    buildAdaptiveTaskContext(subtask) {
+        const spec = this.engine.getSpec();
+        const header = spec.header;
+        let ctx = `Goal: ${header.goal ?? ''}\n`;
+        ctx += `Subtask: ${subtask.summary}\n`;
+        if (subtask.outputs?.length) {
+            ctx += `Required outputs: ${subtask.outputs.map(o => `${o.name}: ${o.type}`).join(', ')}\n`;
+        }
+        return ctx;
+    }
+    buildSubtaskProgress(subtask) {
+        const states = this.engine.getStepStates();
+        const log = this.engine.getExecEvents();
+        const lines = [];
+        for (const child of subtask.children) {
+            const state = states.get(child.step_id);
+            if (state === 'done') {
+                lines.push(`✓ ${child.step_id} [${child.step_type}]: ${child.summary}`);
+            }
+            else if (state === 'failed') {
+                const failEntry = [...log].reverse().find(e => e.step_id === child.step_id && e.event === 'step_failed');
+                lines.push(`✗ ${child.step_id} [${child.step_type}]: ${child.summary} — FAILED: ${failEntry?.detail ?? 'unknown'}`);
+            }
+        }
+        return lines.length > 0 ? lines.join('\n') : 'No steps executed in this subtask yet.';
+    }
+    applyBudgetTrimming(ctx) {
+        const total = this.estimateContextTokens(ctx);
+        if (total <= this.budget.total)
+            return ctx;
+        // 按价值从低到高裁剪：L3b iteration_history → L3 progress_summary → L2 knowledge
+        // → L2d doc_ref → L1 task_context → L2c retry_feedback → L4 inputs（L5/L6 不裁）
+        let excess = total - this.budget.total;
+        if (ctx.iteration_history && excess > 0) {
+            const saved = this.estimateTokens(ctx.iteration_history);
+            ctx.iteration_history = undefined;
+            excess -= saved;
+        }
+        if (excess > 0) {
+            const current = this.estimateTokens(ctx.progress_summary);
+            const target = Math.max(100, current - excess);
+            ctx.progress_summary = truncateToChars(ctx.progress_summary, target * CHARS_PER_TOKEN);
+            excess -= (current - target);
+        }
+        if (ctx.knowledge_context && excess > 0) {
+            const saved = this.estimateTokens(ctx.knowledge_context);
+            ctx.knowledge_context = undefined;
+            excess -= saved;
+        }
+        // L2d doc-ref：作者显式引用，优先级高于 knowledge（故在其后裁剪），仅在 knowledge 裁尽仍超才砍
+        // @a: anc-exec-doc-ref-injection
+        if (ctx.doc_ref_context && excess > 0) {
+            const saved = this.estimateTokens(ctx.doc_ref_context);
+            ctx.doc_ref_context = undefined;
+            excess -= saved;
+        }
+        if (excess > 0) {
+            const current = this.estimateTokens(ctx.task_context);
+            const target = Math.max(100, current - excess);
+            ctx.task_context = truncateToChars(ctx.task_context, target * CHARS_PER_TOKEN);
+            excess -= (current - target);
+        }
+        // L2c 重试反馈靠后裁剪（价值高，直接指导重跑修正），仅 L1/L2/L3 裁尽仍超才裁
+        if (ctx.retry_feedback && excess > 0) {
+            const saved = this.estimateTokens(ctx.retry_feedback);
+            ctx.retry_feedback = undefined;
+            excess -= saved;
+        }
+        if (excess > 0) {
+            // Aggressive input truncation
+            for (const key of Object.keys(ctx.inputs)) {
+                const val = ctx.inputs[key];
+                if (typeof val === 'string' && val.length > AGGRESSIVE_INPUT_MAX) {
+                    ctx.inputs[key] = val.slice(0, AGGRESSIVE_INPUT_MAX - TRUNCATE_MARKER.length) + TRUNCATE_MARKER;
+                }
+            }
+        }
+        return ctx;
+    }
+    estimateContextTokens(ctx) {
+        let total = this.estimateTokens(ctx.task_context);
+        total += this.estimateTokens(ctx.progress_summary);
+        total += this.estimateTokens(ctx.instruction);
+        total += this.estimateTokens(JSON.stringify(ctx.output_schema));
+        total += this.estimateTokens(JSON.stringify(ctx.inputs));
+        if (ctx.knowledge_context)
+            total += this.estimateTokens(ctx.knowledge_context);
+        if (ctx.doc_ref_context)
+            total += this.estimateTokens(ctx.doc_ref_context);
+        if (ctx.iteration_history)
+            total += this.estimateTokens(ctx.iteration_history);
+        if (ctx.retry_feedback)
+            total += this.estimateTokens(ctx.retry_feedback);
+        return total;
+    }
+    estimateTokens(text) {
+        return Math.ceil(text.length / CHARS_PER_TOKEN);
+    }
+    getAncestorChain(stepId, spec) {
+        const ancestors = [];
+        let currentId = getParentStepId(stepId);
+        while (currentId) {
+            const step = this.findStepById(currentId, spec);
+            if (step)
+                ancestors.unshift(step);
+            currentId = getParentStepId(currentId);
+        }
+        return ancestors;
+    }
+    findNearestLoopAncestor(stepId, spec) {
+        let currentId = getParentStepId(stepId);
+        while (currentId) {
+            const step = this.findStepById(currentId, spec);
+            if (step && step.step_type === 'loop')
+                return step;
+            currentId = getParentStepId(currentId);
+        }
+        return null;
+    }
+    findStepById(stepId, spec) {
+        const search = (steps) => {
+            for (const step of steps) {
+                if (step.step_id === stepId)
+                    return step;
+                if (hasChildren(step)) {
+                    const found = search(getChildren(step));
+                    if (found)
+                        return found;
+                }
+            }
+            return null;
+        };
+        return search(spec.steps ?? []);
+    }
+}
+function truncateToChars(text, maxChars) {
+    if (text.length <= maxChars)
+        return text;
+    return text.slice(0, maxChars - TRUNCATE_MARKER.length) + TRUNCATE_MARKER;
+}
+// ============================================================
+// L2 Knowledge Retrieval // @a: anc-exec-knowledge-retrieval
+// ============================================================
+const RE_KNOWLEDGE_HINT = /@knowledge\s+([^\n@]+)/g;
+const L2_BUDGET_CHARS = 8000 * CHARS_PER_TOKEN; // 8000 tokens
+/**
+ * Extract @knowledge hints from text (constraints, instruction, etc.)
+ * Returns unique keywords/phrases declared via `@knowledge <term>`.
+ */
+export function extractKnowledgeHints(text) {
+    if (!text)
+        return [];
+    const hints = [];
+    let match;
+    const re = new RegExp(RE_KNOWLEDGE_HINT.source, 'g');
+    while ((match = re.exec(text)) !== null) {
+        const hint = match[1].trim();
+        if (hint && !hints.includes(hint)) {
+            hints.push(hint);
+        }
+    }
+    return hints;
+}
+/**
+ * Collects all @knowledge hints from spec constraints and a step's instruction.
+ */
+export function collectKnowledgeHints(spec, step) {
+    // Spec-level: scan constraints
+    const constraintsText = (spec.header.constraints ?? []).join('\n');
+    const specHints = extractKnowledgeHints(constraintsText);
+    // Step-level: scan instruction
+    const stepHints = extractKnowledgeHints(step.instruction ?? '');
+    return { specHints, stepHints };
+}
+/**
+ * Retrieve knowledge from a KnowledgeProvider based on @knowledge hints.
+ * This is an async operation — call from the dispatcher after assembling context.
+ *
+ * @param provider - The KnowledgeProvider to query
+ * @param specHints - Global @knowledge hints from spec constraints
+ * @param stepHints - Step-scoped @knowledge hints from instruction
+ * @param supplementaryQuery - Optional query from lack_of_info (passive path)
+ * @returns KnowledgeRetrievalResult with fragments from each source
+ */
+/** 对一组 query 逐个检索并追加到 target，provider 抛错则静默降级（跳过该 query）。
+ * 四个知识来源共用（原各写一份 try/catch）。 */
+async function retrieveInto(provider, target, queries, topK) {
+    for (const q of queries) {
+        if (!q || !q.trim())
+            continue;
+        try {
+            target.push(...await provider.retrieve(q.trim(), topK));
+        }
+        catch {
+            // Degrade gracefully: skip this query
+        }
+    }
+}
+export async function retrieveKnowledge(provider, specHints, stepHints, supplementaryQuery, dynamicQuery) {
+    const result = {
+        specKnowledge: [],
+        stepKnowledge: [],
+        supplementary: [],
+        dynamic: [],
+    };
+    await retrieveInto(provider, result.specKnowledge, specHints, 3); // 来源1: Spec @knowledge
+    await retrieveInto(provider, result.stepKnowledge, stepHints, 3); // 来源3: Step @knowledge
+    await retrieveInto(provider, result.supplementary, supplementaryQuery ? [supplementaryQuery] : [], 3); // 来源2: lack_of_info 被动路径
+    await retrieveInto(provider, result.dynamic, dynamicQuery ? [dynamicQuery] : [], 5); // 来源4: summary+instruction 整段 query
+    return result;
+}
+/**
+ * Format knowledge retrieval results into the L2 knowledge_context string.
+ * Deduplicates by source_id and applies budget trimming.
+ */
+export function formatKnowledgeContext(result, triggerStepId, budgetChars = L2_BUDGET_CHARS) {
+    // Deduplicate across all sources by source_id
+    const seen = new Set();
+    const dedup = (fragments) => {
+        const unique = [];
+        for (const f of fragments) {
+            if (!seen.has(f.source_id)) {
+                seen.add(f.source_id);
+                unique.push(f);
+            }
+        }
+        return unique;
+    };
+    // Sort each source by relevance (high > medium > low)
+    const relevanceOrder = { high: 0, medium: 1, low: 2 };
+    const sortByRelevance = (a, b) => (relevanceOrder[a.relevance] ?? 2) - (relevanceOrder[b.relevance] ?? 2);
+    const specFragments = dedup(result.specKnowledge).sort(sortByRelevance);
+    const stepFragments = dedup(result.stepKnowledge).sort(sortByRelevance);
+    const suppFragments = dedup(result.supplementary).sort(sortByRelevance);
+    const dynamicFragments = dedup(result.dynamic ?? []).sort(sortByRelevance); // 来源4，优先级最低，最后 dedup
+    if (specFragments.length === 0 && stepFragments.length === 0 && suppFragments.length === 0 && dynamicFragments.length === 0) {
+        return '';
+    }
+    const sections = [];
+    if (specFragments.length > 0) {
+        const lines = specFragments.map(f => `${f.source_id}: ${f.content}`);
+        sections.push(`### Spec @knowledge（全程可用）\n${lines.join('\n')}`);
+    }
+    if (suppFragments.length > 0) {
+        const triggerNote = triggerStepId
+            ? `（由步骤 ${triggerStepId} 的 lack_of_info 触发，前序步骤未参考此知识）`
+            : '';
+        const lines = suppFragments.map(f => `${f.source_id}: ${f.content}`);
+        sections.push(`### 补充检索${triggerNote}\n${lines.join('\n')}`);
+    }
+    if (stepFragments.length > 0) {
+        const lines = stepFragments.map(f => `${f.source_id}: ${f.content}`);
+        sections.push(`### 步骤 @knowledge\n${lines.join('\n')}`);
+    }
+    if (dynamicFragments.length > 0) {
+        const lines = dynamicFragments.map(f => `${f.source_id}: ${f.content}`);
+        sections.push(`### 动态检索\n${lines.join('\n')}`);
+    }
+    let formatted = `[知识上下文]\n${sections.join('\n---\n')}`;
+    // Budget trimming: remove from lowest priority source first (step > supplementary > spec)
+    if (formatted.length > budgetChars) {
+        formatted = truncateToChars(formatted, budgetChars);
+    }
+    return formatted;
+}
+/**
+ * Inject L2 knowledge context into an assembled context.
+ * This is the main async entry point for the dispatcher to enrich context with knowledge.
+ *
+ * @param ctx - The assembled context (modified in place and returned)
+ * @param provider - KnowledgeProvider from HostConfig
+ * @param spec - The spec AST (for extracting constraints)
+ * @param step - The current step node (for extracting step-level hints)
+ * @param supplementaryQuery - Optional query from lack_of_info (passive path)
+ * @param triggerStepId - Step ID that triggered supplementary retrieval
+ * @returns The enriched AssembledContext
+ */
+export async function injectKnowledgeContext(ctx, provider, spec, step, supplementaryQuery, triggerStepId) {
+    // 返回检索到的 source_id 列表（供 HopLog knowledge 流控字段记录），空 = 无检索
+    const { specHints, stepHints } = collectKnowledgeHints(spec, step);
+    // 来源4 动态检索：整段 summary + instruction 作 query（v1 无 NLP，靠 Provider 语义匹配）
+    const dynamicQuery = [step.summary, step.instruction].filter(Boolean).join(' ');
+    // If no hints, no supplementary, no dynamic query, nothing to retrieve
+    if (specHints.length === 0 && stepHints.length === 0 && !supplementaryQuery && !dynamicQuery.trim()) {
+        return [];
+    }
+    try {
+        const result = await retrieveKnowledge(provider, specHints, stepHints, supplementaryQuery, dynamicQuery);
+        const knowledgeText = formatKnowledgeContext(result, triggerStepId);
+        if (knowledgeText) {
+            ctx.knowledge_context = knowledgeText;
+        }
+        const sources = [...result.specKnowledge, ...result.stepKnowledge, ...result.supplementary, ...result.dynamic]
+            .map(f => f.source_id);
+        return [...new Set(sources)];
+    }
+    catch {
+        // Knowledge injection degradation: if provider throws, L2 is empty
+        // Record warning would happen at dispatcher level
+        return [];
+    }
+}
+/**
+ * 把 AssembledContext 格式化为完整自包含 prompt 文本。
+ * 包含：角色说明（让任何 LLM 拿到就能正确执行）+ 6 层结构化内容。
+ * 复用模式下记录到 hoplog llm.prompt（引擎交给 CC 推理的完整 context 渲染——CC 即 llm，
+ * 见 [[spec-observability#^anc-obs-mode-boundary]]）。独立模式的真实 API prompt 由 dispatcher
+ * 的 buildSystemPrompt+buildMessages 另行组装（结构不同：system + 多条 user message），
+ * 本函数不代表独立模式实际发送内容（独立模式 llm.prompt 记录属 v2）。
+ * 覆盖守护见 tests/prompt.test.ts（@v: anc-obs-debug-context）——新增 AssembledContext 字段须同步本函数。
+ */
+export function formatPromptText(ctx, stepType) {
+    const sections = [];
+    // 角色前缀：自包含执行指引，按步骤类型给出行为要求
+    const rolePrefix = buildRolePrefix(stepType);
+    sections.push(rolePrefix);
+    sections.push('═══ L1. Spec 契约 ═══');
+    sections.push(ctx.task_context);
+    if (ctx.knowledge_context) {
+        sections.push('═══ L2. 知识上下文 ═══');
+        sections.push(ctx.knowledge_context);
+    }
+    if (ctx.doc_ref_context) { // L2d doc-ref // @a: anc-exec-doc-ref-injection
+        sections.push('═══ L2d. 引用文档 ═══');
+        sections.push(ctx.doc_ref_context);
+    }
+    if (ctx.retry_feedback) {
+        sections.push('═══ L2c. 重试反馈 ═══');
+        sections.push(ctx.retry_feedback);
+    }
+    sections.push('═══ L3. 执行链上下文 ═══');
+    sections.push(ctx.progress_summary);
+    if (ctx.iteration_history) {
+        sections.push('═══ L3b. 迭代历史 ═══');
+        sections.push(ctx.iteration_history);
+    }
+    sections.push('═══ L4. 步骤输入 ═══');
+    const inputLines = Object.entries(ctx.inputs)
+        .map(([k, v]) => `${k}: ${typeof v === 'string' ? v : JSON.stringify(v)}`)
+        .join('\n');
+    sections.push(inputLines || '(无输入)');
+    sections.push('═══ L5. 步骤指令 ═══');
+    sections.push(ctx.instruction);
+    sections.push('═══ L6. 输出约束 ═══');
+    const schemaLines = ctx.output_schema
+        .map((o) => `+ → ${o.name}: ${o.type}${o.description ? `  # ${o.description}` : ''}`)
+        .join('\n');
+    sections.push(schemaLines || '(无输出)');
+    return sections.join('\n\n');
+}
+function buildRolePrefix(stepType) {
+    const common = `你正在执行一个 HopSpec 规约中的步骤。严格按以下规则操作。
+
+⚠️ 硬约束（违反即错误）：
+- 输出字段名、类型、数量必须与 L6 输出约束完全一致——不得多也不得少
+- L1 Constraints 不可违反
+- 不得编造数据——信息不足时必须输出 lack_of_info
+- 每条 Bash 命令只做一件事，禁止管道（|）、链式（&&）
+
+下面是按 6 层组织的结构化上下文：
+- L1 Spec 契约+骨架：任务目标、约束、全局步骤计划——不可违反
+- L3 执行链：已完成步骤的产出（你可以引用）、当前位置（◀ 标记）
+- L4 步骤输入：你的输入数据
+- L5 步骤指令：你具体要做什么
+- L6 输出约束：你的输出必须严格符合此结构`;
+    const typeGuide = {
+        reason: `你的角色：推理分析。
+【必须】基于 L5 指令和 L4 输入数据进行推理，产出 JSON 对象。
+【必须】JSON 的 key 严格使用 L6 output_schema 中每个变量的 name，数量完全一致。
+【必须】信息不足时输出 {"lack_of_info":"说明缺少什么信息"}，绝不编造。
+【禁止】输出 L6 未声明的额外字段。`,
+        check: `你的角色：验证判定。
+【必须】固定产出恰好两个值：一个 bool（判定槽：通过=true / 失败=false）+ 一个 text（说明槽：失败原因）。
+【必须】看 L6 output_schema 哪个是 bool 哪个是 text，按各自的 name 填入。
+【禁止】自行决定重试或修改之前步骤的产出——你只负责如实判定，引擎自动处理后续。`,
+        act: `你的角色：确定性执行（禁止推理）。
+【如果】L5 包含 \`\`\`hop_python 代码块 → 严格逐行执行（赋值、内置函数、工具调用），不得改动逻辑、不得跳行、不得添加额外操作。
+【如果】没有代码块 → 按 L5 自然语言指令使用 Bash/Read/Write 工具执行。
+【必须】产出 JSON，key 严格对应 L6 output_schema 的变量名。
+【禁止】在执行期自由发挥或加入推理。`,
+        commit: `你的角色：不可逆执行（与 act 同源）。
+执行方式与 act 完全相同，唯一区别是操作不可逆（如写入生产数据库、发送邮件、git push）。
+【必须】确认操作内容无误后再执行。产出 JSON 格式同 act。
+【禁止】在执行期自由发挥。`,
+        confirm: `你的角色：纯审批闸门。
+【必须】展示待审批动作（presented_data.question + context），等 caller 答 approve/reject。
+【禁止】自行替人做决策。approve→bool true / reject→全局中止。不收集业务数据值（那是 ask）。`,
+        ask: `你的角色：数据收集——向 caller 请求业务数据值。
+【必须】展示 question（要 caller 提供什么）+ output_schema（要填的变量/类型）+ default_value（前序推断默认值）+ options（候选，如有）。
+【必须】caller 答"值是什么"（具体数据值，或采用 default 快捷，或选 option），值落到 +→ 声明的变量名。
+【禁止】把 approve/reject 当数据值——ask 不是审批闸门，要中止用 confirm。`,
+    };
+    const guide = (stepType && typeGuide[stepType]) || `【必须】输出 JSON 格式，key 严格对应 L6 output_schema 的变量名。`;
+    return `${common}\n\n${guide}`;
+}
+/**
+ * 组装 parallel 容器的完整自包含 fan-out 指令文本。
+ * driver agent 拿到这段文本就能完成 fan-out→驱动→join 全流程。
+ */
+export function formatParallelPromptText(p) {
+    const childList = p.children
+        .map(c => `- ${c.child_step_id} ${c.summary}  params: ${JSON.stringify(c.params_for_child)}`)
+        .join('\n');
+    const cli = p.cliPath;
+    const sd = p.stateDir;
+    const workerPrompts = p.children
+        .map(c => {
+        const paramsJson = JSON.stringify(c.params_for_child);
+        return `--- child ${c.child_step_id}（${c.summary}）---
+你是 HopSpec parallel worker，负责驱动 child ${c.child_step_id}（${c.summary}）到终态。
+严格按以下步骤操作，不得跳步、不得自由发挥。
+
+⚠️ 硬约束（违反即错误）：
+- 输出的 JSON 字段名、类型、数量必须与 output_schema 完全一致——不得多、不得少、不得改名
+- 不得编造数据——如果基于输入数据和指令无法完成任务，必须输出 {"lack_of_info":"说明缺少什么信息"}
+- check 步骤只做判定（true/false），不得自行决定重试或修改之前步骤的产出——引擎自动处理重试
+- act/commit 步骤如果有 hop_python body 代码块，必须逐行严格执行代码逻辑，不得改动、不得跳行、不得添加额外操作
+- 每条 Bash 命令必须独立完整——禁止管道（|）、禁止链式（&&）、禁止 shell 变量赋值
+- 所有命令直接写完整路径执行，不需要 cd
+
+第 1 步：执行启动命令（直接复制执行，不要修改）
+node ${cli} run ${p.specPath} --parallel-parent ${p.instanceId} --parallel-child ${c.child_step_id} --state-dir ${sd} --log-dir ${p.parentLogDir}/parallel/${c.child_step_id} --log-level debug --params '${paramsJson}'
+
+这条命令返回一个 JSON 对象。
+
+第 2 步：读返回 JSON 的 "status" 字段，严格按值分派
+- "completed" → child 执行完毕。报告终态和产出的变量值摘要，然后结束。
+- "failed" → 执行失败。报告失败原因，然后结束。
+- "step_ready" → 引擎给你一个步骤要执行，继续第 3 步。
+- 其他值 → 报告异常状态，然后结束。
+
+第 3 步：从返回的 JSON 中提取以下字段（后续步骤都会用到）
+- step_id：当前步骤 ID（如 "${c.child_step_id}.1"），提交结果时必须填入这个确切的值
+- step_type：步骤类型，决定你怎么执行（reason / check / act / commit）
+- context.instruction：你的任务指令——告诉你具体做什么
+- context.inputs：你的输入数据——变量名到值的映射
+- context.output_schema：你必须产出的变量列表，每个有 name（变量名）和 type（类型）。这是你输出 JSON 的 key 的唯一来源
+
+第 4 步：按 step_type 严格执行
+
+(a) reason 步骤——推理分析：
+   根据 context.instruction 的指示，基于 context.inputs 的数据进行推理分析。
+   【必须】产出 JSON 对象，key 严格使用 output_schema 中每个变量的 name，value 是你的推理结果。
+   【必须】字段数量与 output_schema 完全一致——不多不少。
+   【必须】信息不足时输出 {"lack_of_info":"说明缺少什么信息"}，绝不编造。
+   示例：output_schema = [{name:"points_a", type:"text"}]
+   → 你必须产出恰好一个字段：{"points_a":"你的分析结果文本"}
+
+(b) check 步骤——验证判定：
+   【必须】固定产出恰好两个值：一个 bool（判定槽：通过=true / 失败=false）+ 一个 text（说明槽）。
+   【必须】看 output_schema 哪个是 bool 类型、哪个是 text 类型，按各自的 name 填入。
+   【禁止】自行决定重试或修改之前步骤的产出——你只负责如实判定，引擎自动处理后续。
+   示例：output_schema = [{name:"a_ok", type:"bool"}, {name:"a_note", type:"text"}]
+   → 你必须产出恰好两个字段：{"a_ok":true,"a_note":"校验通过，摘要包含所有要点"}
+
+(c) act 步骤——确定性执行（禁止推理）：
+   【如果】context.instruction 包含 \`\`\`hop_python 代码块 → 严格按代码逐行执行（赋值、内置函数、工具调用），不得改动逻辑、不得跳行、不得添加额外操作。
+   【如果】没有代码块 → 按 instruction 的自然语言描述，使用 Bash/Read/Write 工具执行操作。
+   【必须】产出 JSON，key 严格对应 output_schema 的变量名。
+
+(d) commit 步骤——不可逆执行：
+   执行方式与 act 完全相同，唯一区别是操作不可逆（如写入生产数据库、发送邮件）。
+   【必须】确认操作内容无误后再执行。产出 JSON 格式同 act。
+
+第 5 步：提交结果（直接复制模板，替换两个占位符）
+node ${cli} submit_and_fetch_next <STEP_ID> --output '<OUTPUT_JSON>' --state-dir ${sd}
+
+【必须】替换规则：
+- <STEP_ID> → 第 3 步提取的 step_id 值（如 ${c.child_step_id}.1），不要留尖括号
+- <OUTPUT_JSON> → 你在第 4 步产出的完整 JSON 字符串，用单引号包裹
+
+完整示例：
+node ${cli} submit_and_fetch_next ${c.child_step_id}.1 --output '{"points_a":"分析结果..."}' --state-dir ${sd}
+
+第 6 步：回到第 2 步
+submit_and_fetch_next 返回新的 JSON。回到第 2 步读 status 继续分派。
+循环直到 status 为 "completed" 或 "failed"，然后报告终态并结束。`;
+    })
+        .join('\n\n');
+    return `你是 HopSpec parallel driver，负责并行调度以下 child 容器到终态后 join 合并。
+
+═══ 任务概览 ═══
+Goal: ${p.goal}
+Outputs: ${p.outputs}
+Parallel step ${p.parallelStepId} 分发 ${p.children.length} 个 child（max_concurrent=${p.maxConcurrent}）：
+${childList}
+
+═══ Fan-out：对每个 child 起一个 subagent ═══
+用你所在 runtime 的子 agent 机制（如 CC 的 Agent 工具 / Codex 的 subagent）起一个 subagent 驱动一个 child 子实例。
+并发数 ≤ ${p.maxConcurrent}；child 数超出则分批，前批全部返回后起下批。
+
+每个 subagent prompt（已填入实际参数）：
+
+${workerPrompts}
+
+═══ Join：全部 subagent 返回后 ═══
+node ${p.cliPath} join_parallel ${p.parallelStepId} --state-dir ${p.stateDir} --instance ${p.instanceId}
+引擎 merge 后返回下一步 JSON，继续主循环。
+
+═══ 错误处理 ═══
+- 某 subagent 返回 failed → 不阻塞其余，join 时该 child 输出写 None
+- 某 subagent 异常退出 → 视为 failed
+- 含 confirm 的 child 不进并行，主 driver 串行驱动`;
+}
+// 人通道格式化:把 record 中每个值按 HUMAN_PREVIEW_THRESHOLD(5K) 处理——
+// 小值原样;大值写 work_zone/vars/<name>.json,返 {$file, preview} 复合格式,
+// preview = 头 5K 字符 + "...[完整内容见文件]"。driver 完整 dump preview 给 user 看 +
+// 提示完整在哪。见 design/shared-types.md ^anc-exec-deflate / 概念 ^anc-exec-audience-routing。
+// workZone 空串(独立模式)时跳过 deflate,原值返回(信息不丢,只是没文件链接)。
+// @a: anc-exec-deflate, anc-exec-audience-routing
+export function formatHumanContext(record, workZone) {
+    const result = {};
+    for (const [key, value] of Object.entries(record)) {
+        if (value === null || value === undefined) {
+            result[key] = value;
+            continue;
+        }
+        const str = typeof value === 'string' ? value : (JSON.stringify(value) ?? '');
+        if (!workZone || str.length <= HUMAN_PREVIEW_THRESHOLD) {
+            result[key] = value;
+            continue;
+        }
+        // 大值卸到文件 + 返 preview
+        const filePath = nodePath.join(workZone, 'vars', `${key}.json`);
+        nodeFs.writeFileSync(filePath, JSON.stringify(value), { mode: 0o600 });
+        const preview = str.slice(0, HUMAN_PREVIEW_THRESHOLD) + '\n...[完整内容见文件]';
+        result[key] = { $file: filePath, preview };
+    }
+    return result;
+}