lightclawbot 1.2.6-beta.0 → 1.2.7

package/dist/src/group/orchestrator/planning/planning-parser.js

@@ -0,0 +1,207 @@
+/**
+ * @fileoverview PlanningParser —— Planning 阶段 JSON 决策解析器
+ *
+ * 本模块负责解析主 Agent（Leader）在 Planning 阶段输出的 JSON 决策文本，
+ * 将其转换为结构化的 TypeScript 对象，供后续流程使用。
+ *
+ * 核心职责：
+ *  1. 解析 LLM 输出的 JSON 文本（支持纯 JSON 和 markdown 代码块两种格式）；
+ *  2. 区分 "self_answer"（主 Agent 自己回答）和 "dispatch"（拆分派活）两种决策；
+ *  3. dispatch 决策时提取 transition（过渡话）和 tasks（子任务列表）；
+ *  4. 容错处理：JSON 解析失败时返回结构化的错误信息。
+ *
+ * 设计要点：
+ *  - 纯函数实现，不做任何 IO 操作，便于单元测试；
+ *  - 与 PlanValidator 配合使用：本模块只做 JSON 解析 + 结构提取，
+ *    字段合法性校验（如 id 唯一性、成员归属、循环依赖等）由 PlanValidator 负责。
+ *
+ * @module planning-parser
+ */
+/**
+ * 解析 LLM 输出的 Planning JSON 决策
+ *
+ * 这是本模块的主入口函数，负责将 LLM 的文本输出转换为结构化决策对象。
+ *
+ * 容错策略（按优先级依次尝试）：
+ *  1. 直接对整段文本执行 JSON.parse；
+ *  2. 若失败，尝试从文本中提取 ```json ... ``` markdown 代码块后再解析；
+ *  3. 若仍失败，返回 ok=false 并附带错误描述。
+ *
+ * @param text - LLM 输出的 finalText（可能是纯 JSON 或包含 markdown 代码块）
+ * @returns 解析结果，包含决策对象或错误信息
+ *
+ * @example
+ * ```ts
+ * const result = parsePlanningDecision('{"action":"self_answer"}');
+ * if (result.ok) {
+ *   console.log(result.decision); // { action: 'self_answer' }
+ * }
+ * ```
+ */
+export function parsePlanningDecision(text) {
+    const trimmed = text.trim();
+    // 空内容直接返回失败
+    if (!trimmed) {
+        return { ok: false, error: '响应内容为空', rawText: text };
+    }
+    // 第一步：尝试解析 JSON（含 markdown 代码块容错）
+    const parseResult = tryParseJson(trimmed);
+    if (!parseResult.ok) {
+        return { ok: false, error: parseResult.error, rawText: text };
+    }
+    const parsed = parseResult.data;
+    // 第二步：校验顶层结构必须是对象
+    if (!parsed || typeof parsed !== 'object') {
+        return { ok: false, error: '解析结果不是一个对象', rawText: text };
+    }
+    const obj = parsed;
+    const action = obj.action;
+    // 第三步：根据 action 字段分发处理
+    if (action === 'self_answer') {
+        return { ok: true, decision: { action: 'self_answer' }, rawText: text };
+    }
+    if (action === 'dispatch') {
+        return buildDispatchResult(obj, text);
+    }
+    // action 字段不是已知值
+    return {
+        ok: false,
+        error: `未知的 action 类型: "${String(action)}"`,
+        rawText: text,
+    };
+}
+/**
+ * 从 DispatchDecision 中提取 Plan 对象
+ *
+ * 将解析器产出的 DispatchDecision 转换为 PlanValidator 所需的 Plan 结构。
+ * 主要处理：将空的 dependsOn 数组转为 undefined，避免下游产生无意义的空依赖。
+ *
+ * @param decision - 已解析的 dispatch 决策
+ * @returns 标准化的 Plan 对象，可直接传入 PlanValidator 进行校验
+ *
+ * @example
+ * ```ts
+ * const plan = extractPlanFromDecision(dispatchDecision);
+ * const validationResult = validatePlan(plan, context);
+ * ```
+ */
+export function extractPlanFromDecision(decision) {
+    return {
+        tasks: decision.tasks.map((t) => ({
+            id: t.id,
+            to: t.to,
+            task: t.task,
+            // 空数组视为无依赖，设为 undefined 以简化下游判断
+            dependsOn: t.dependsOn?.length ? t.dependsOn : undefined,
+        })),
+    };
+}
+/**
+ * 尝试解析 JSON 文本
+ *
+ * 支持两种格式：
+ *  1. 纯 JSON 文本（直接 parse）
+ *  2. 包含 markdown 代码块的文本（提取 ```json ... ``` 内容后 parse）
+ *
+ * @param text - 待解析的文本（已 trim）
+ * @returns 解析结果，成功时包含 data，失败时包含 error 描述
+ * @internal
+ */
+function tryParseJson(text) {
+    // 策略一：直接解析整段文本
+    try {
+        return { ok: true, data: JSON.parse(text) };
+    }
+    catch {
+        // 直接解析失败，继续尝试代码块提取
+    }
+    // 策略二：尝试匹配 markdown 代码块（支持 ```json 和 ``` 两种写法）
+    const codeBlockMatch = /```(?:json)?\s*\n?([\s\S]*?)\n?\s*```/.exec(text);
+    if (codeBlockMatch?.[1]) {
+        try {
+            return { ok: true, data: JSON.parse(codeBlockMatch[1].trim()) };
+        }
+        catch {
+            // 代码块内容也无法解析
+            return {
+                ok: false,
+                error: `JSON 解析失败（已尝试代码块提取）: ${text.slice(0, 200)}`,
+            };
+        }
+    }
+    // 两种策略均失败，返回错误（附带前 200 字符用于调试）
+    return {
+        ok: false,
+        error: `JSON 解析失败: ${text.slice(0, 200)}`,
+    };
+}
+/**
+ * 构建 dispatch 类型的解析结果
+ *
+ * 从已解析的 JSON 对象中提取 dispatch 决策所需的字段：
+ *  - thinking: 可选的拆分思路
+ *  - transition: 过渡话（缺失时默认为空字符串）
+ *  - tasks: 子任务数组（逐项标准化）
+ *
+ * @param obj - 已解析的 JSON 对象（action 已确认为 'dispatch'）
+ * @param rawText - 原始文本（透传到结果中用于日志）
+ * @returns 解析结果
+ * @internal
+ */
+function buildDispatchResult(obj, rawText) {
+    // 提取可选的拆分思路（仅 string 类型有效）
+    const thinking = typeof obj.thinking === 'string' ? obj.thinking : undefined;
+    // 提取过渡话（缺失或非 string 时默认为空）
+    const transition = typeof obj.transition === 'string' ? obj.transition : '';
+    // 提取任务数组（非数组时降级为空数组）
+    const tasks = Array.isArray(obj.tasks) ? obj.tasks : [];
+    // tasks 为空时视为无效的 dispatch 决策
+    if (tasks.length === 0) {
+        return {
+            ok: false,
+            error: 'dispatch 决策的 tasks 数组为空',
+            rawText,
+        };
+    }
+    // 逐项标准化任务结构
+    const extractedTasks = tasks.map(normalizeTaskItem);
+    return {
+        ok: true,
+        decision: {
+            action: 'dispatch',
+            thinking,
+            transition,
+            tasks: extractedTasks,
+        },
+        rawText,
+    };
+}
+/**
+ * 标准化单个 task 项
+ *
+ * 仅做结构提取和类型安全转换，不做业务合法性校验。
+ * 对于缺失或类型不匹配的字段，使用空字符串作为默认值，
+ * 后续由 PlanValidator 统一报告校验错误。
+ *
+ * @param t - 原始 task 数据（类型未知）
+ * @returns 标准化后的 task 对象
+ * @internal
+ */
+function normalizeTaskItem(t) {
+    // 非对象类型直接返回空壳（由 PlanValidator 报错）
+    if (!t || typeof t !== 'object') {
+        return { id: '', to: '', task: '' };
+    }
+    const item = t;
+    // 过滤 dependsOn 中的非 string 元素，确保类型安全
+    const dependsOn = Array.isArray(item.dependsOn)
+        ? item.dependsOn.filter((d) => typeof d === 'string')
+        : undefined;
+    return {
+        id: typeof item.id === 'string' ? item.id : '',
+        to: typeof item.to === 'string' ? item.to : '',
+        task: typeof item.task === 'string' ? item.task : '',
+        // 仅在有有效依赖时才设置 dependsOn 字段
+        ...(dependsOn?.length ? { dependsOn } : {}),
+    };
+}

package/dist/src/group/orchestrator/planning/subtask-executor.js

@@ -0,0 +1,345 @@
+/**
+ * SubtaskExecutor —— 子任务 DAG 执行器
+ *
+ * 职责（场景 C 拆活路径的"运行儿子"那一段）：
+ *  1. 将主 Agent 产出的 Plan，按 dependsOn 做拓扑分层；
+ *  2. 层间串行、层内并发地驱动每个子 Agent 的 run（同层无依赖可安全并发）；
+ *  3. 把上游产出的文本作为「## 前置任务结果」注入到下游 child 的 message 前缀；
+ *  4. 收集 SubtaskResult[]，供后续 SummarizerRunner 汇总；
+ *  5. 失败容忍：单个 child 失败不阻断同层其他任务，下游依赖标记为 upstream_failed；
+ *  6. 级联 abort：任一 abort 立即跳过尚未启动的 child，已启动的由自身 abortSignal 终止。
+ *
+ * 设计要点：
+ *  - 不写状态机：状态 PLANNING / RUNNING_CHILDREN 由调用方（路由）转移；
+ *  - 不直接发出站事件：每个 child 的 sink 由本类内部构造，路径层不感知；
+ *  - 成功的 child 写 assistant 账本（parentRunId=leaderRunId）；
+ *    失败 / 中止写 system 账本（run_failed / user_aborted）；
+ *  - MVP 阶段简单实现：依赖 PlanValidator 已校验过环路 / 自引用 / 成员合法性。
+ */
+import { createStreamReplyConfig } from '../../../streaming/stream-reply-sink.js';
+import { errorToString, normalizeRunStatus } from '../../utils/run-helpers.js';
+import { getModuleLogger } from '../../../utils/logger.js';
+import { generateMsgId } from '../../../dedup.js';
+/**
+ * SubtaskExecutor 主体（无状态，可作为单例长期持有）
+ */
+export class SubtaskExecutor {
+    deps;
+    log = getModuleLogger('group.subtask-executor');
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /**
+     * 执行整张 Plan，按拓扑分层：层间串行、层内并发跑子任务
+     *
+     * @returns 与 plan.tasks 一一对应的 SubtaskResult 列表（顺序与 plan.tasks 一致）
+     */
+    async run(input) {
+        const { plan, ctx } = input;
+        const tag = `[SubtaskExecutor conv=${ctx.conversationId}]`;
+        const log = this.log;
+        // ── 1. 拓扑分层（Kahn） ──
+        const layers = this.topoLayers(plan.tasks);
+        log.info(`${tag} plan accepted tasks=${plan.tasks.length} layers=${layers.length}`);
+        // ── 2. 层间串行、层内并发执行 ──
+        // 同一层的任务无依赖关系，可安全并发；层间有依赖，必须串行等待上一层完成
+        const resultsById = new Map();
+        for (let i = 0; i < layers.length; i++) {
+            // 已被外部 abort：剩余层全部跳过
+            if (ctx.abortSignal.aborted) {
+                for (const remaining of layers.slice(i).flat()) {
+                    resultsById.set(remaining.id, this.makeAbortedResult(remaining));
+                }
+                break;
+            }
+            const layer = layers[i];
+            // 并发执行同层任务（无依赖关系，前端按 agentId 分区展示）
+            const layerResults = await Promise.all(layer.map((task) => {
+                if (ctx.abortSignal.aborted) {
+                    return Promise.resolve(this.makeAbortedResult(task));
+                }
+                return this.runSingleTask(task, resultsById, input);
+            }));
+            for (const r of layerResults) {
+                resultsById.set(r.taskId, r);
+            }
+        }
+        // ── 3. 按 plan.tasks 原顺序输出结果 ──
+        return plan.tasks.map((t) => resultsById.get(t.id) ?? this.makeUpstreamFailedResult(t));
+    }
+    // ────────────────────────────────────────────────
+    // 内部：单任务执行
+    // ────────────────────────────────────────────────
+    /**
+     * 跑一个 child run；上游失败时直接产出 upstream_failed 结果不启动 SDK
+     */
+    async runSingleTask(task, upstreamResults, input) {
+        const { ctx, leaderAgentId, leaderRunId, originalMsgId } = input;
+        const { runner, runRegistry, ledger, emitter, promptBuilder } = this.deps;
+        const log = this.log;
+        const tag = `[SubtaskExecutor conv=${ctx.conversationId} task=${task.id}]`;
+        // 1) 上游失败 → 直接短路
+        const blocking = this.collectBlockingUpstream(task, upstreamResults);
+        if (blocking.length > 0) {
+            const reason = `上游任务未完成: ${blocking.map((b) => `${b.taskId}(${b.status})`).join(', ')}`;
+            log.warn(`${tag} skipped due to upstream: ${reason}`);
+            try {
+                await ledger.appendSystem({
+                    groupId: ctx.groupId,
+                    event: 'run_failed',
+                    agentId: task.to,
+                    runId: `child:${task.id}:skipped`,
+                    content: reason,
+                });
+            }
+            catch (err) {
+                log.warn(`${tag} appendSystem(skipped) failed: ${err}`);
+            }
+            return {
+                taskId: task.id,
+                agentId: task.to,
+                runId: `child:${task.id}:skipped`,
+                status: 'failed',
+                errorMessage: reason,
+            };
+        }
+        // 2) 注册 abort（使用稳定 runId 便于前端聚合）
+        const childRunId = `child:${ctx.conversationId}:${task.id}`;
+        const abortSignal = runRegistry.registerRun(ctx.conversationId, childRunId, task.to);
+        // 3) 构造 sinkContext
+        const replyMsgId = generateMsgId();
+        const signalCtx = {
+            emitter,
+            targetId: ctx.userId,
+            replyMsgId,
+            originalMsgId,
+            agentId: task.to,
+        };
+        const sinkContext = createStreamReplyConfig({
+            emitter,
+            targetId: ctx.userId,
+            replyMsgId,
+            originalMsgId,
+            effectiveApiKey: ctx.effectiveApiKey ?? '',
+            agentId: task.to,
+            groupId: ctx.groupId,
+            runId: childRunId,
+            parentRunId: leaderRunId,
+            conversationId: ctx.conversationId,
+            isSubtask: true,
+        }, { suppressTyping: true, runId: childRunId }, signalCtx);
+        sinkContext.emitStart();
+        // 4) 拼 system prompt + message（注入上游结果）
+        const systemPrompt = promptBuilder.buildChild({
+            childAgentId: task.to,
+            leaderAgentId,
+            taskDescription: task.task,
+            userMessage: ctx.userMessage,
+        });
+        const childMessage = this.buildChildMessage(task, upstreamResults);
+        // 5) 拉起 child run
+        let runOutput;
+        try {
+            runOutput = await runner.run({
+                groupId: ctx.groupId,
+                agentId: task.to,
+                userId: ctx.userId,
+                role: 'child',
+                parentRunId: leaderRunId,
+                message: childMessage,
+                systemPrompt,
+                abortSignal,
+                sinkContext,
+                preassignedRunId: childRunId,
+                // 子任务执行也需要跨 Agent 通信权限
+                enableAgentToAgent: true,
+            });
+        }
+        catch (err) {
+            const e = err instanceof Error ? err : new Error(String(err));
+            log.error(`${tag} runner exception: ${e.message}`);
+            runRegistry.unregisterRun(ctx.conversationId, childRunId);
+            try {
+                await ledger.appendSystem({
+                    groupId: ctx.groupId,
+                    event: 'run_failed',
+                    agentId: task.to,
+                    runId: childRunId,
+                    content: e.message,
+                });
+            }
+            catch (logErr) {
+                log.warn(`${tag} appendSystem(exception) failed: ${logErr}`);
+            }
+            return {
+                taskId: task.id,
+                agentId: task.to,
+                runId: childRunId,
+                status: 'failed',
+                errorMessage: errorToString(e),
+            };
+        }
+        // 6) 落账本
+        const status = normalizeRunStatus(runOutput.status);
+        const result = {
+            taskId: task.id,
+            agentId: task.to,
+            runId: runOutput.runId || childRunId,
+            status,
+        };
+        if (runOutput.status === 'ok') {
+            result.output = runOutput.finalText;
+            try {
+                await ledger.appendAssistant({
+                    groupId: ctx.groupId,
+                    agentId: task.to,
+                    content: runOutput.finalText,
+                    runId: result.runId,
+                    parentRunId: leaderRunId,
+                });
+            }
+            catch (err) {
+                log.warn(`${tag} appendAssistant failed: ${err}`);
+            }
+            log.info(`${tag} done bytes=${runOutput.finalText.length}`);
+        }
+        else if (runOutput.status === 'aborted') {
+            // 被中止：如果已有部分输出内容，将其作为 assistant 条目持久化，
+            // 刷新页面后用户仍能看到中断前的内容。
+            // 不再写 user_aborted 系统事件——由上层路由（leader-dispatch）统一写一条即可。
+            result.errorMessage = 'aborted';
+            if (runOutput.finalText) {
+                result.output = runOutput.finalText;
+                try {
+                    await ledger.appendAssistant({
+                        groupId: ctx.groupId,
+                        agentId: task.to,
+                        content: runOutput.finalText,
+                        runId: result.runId,
+                        parentRunId: leaderRunId,
+                    });
+                }
+                catch (err) {
+                    log.warn(`${tag} appendAssistant(aborted partial) failed: ${err}`);
+                }
+                log.info(`${tag} aborted but has partial content, persisted bytes=${runOutput.finalText.length}`);
+            }
+        }
+        else {
+            result.errorMessage = errorToString(runOutput.error);
+            try {
+                await ledger.appendSystem({
+                    groupId: ctx.groupId,
+                    event: 'run_failed',
+                    agentId: task.to,
+                    runId: result.runId,
+                    content: result.errorMessage,
+                });
+            }
+            catch (err) {
+                log.warn(`${tag} appendSystem failed: ${err}`);
+            }
+            log.warn(`${tag} ${runOutput.status} reason=${result.errorMessage}`);
+        }
+        runRegistry.unregisterRun(ctx.conversationId, childRunId);
+        return result;
+    }
+    // ────────────────────────────────────────────────
+    // 内部：辅助方法
+    // ────────────────────────────────────────────────
+    /**
+     * 拓扑分层：返回 PlanItem[][]，第 i 层在第 i-1 层全部完成后再执行
+     */
+    topoLayers(tasks) {
+        const indeg = new Map();
+        const byId = new Map();
+        for (const t of tasks) {
+            indeg.set(t.id, (t.dependsOn ?? []).length);
+            byId.set(t.id, t);
+        }
+        const layers = [];
+        let remaining = tasks.length;
+        while (remaining > 0) {
+            const layer = [];
+            for (const [id, deg] of indeg) {
+                if (deg === 0)
+                    layer.push(byId.get(id));
+            }
+            if (layer.length === 0) {
+                // PlanValidator 应该已经挡掉环路，这里仅作兜底；把剩余任务塞最后一层抛失败
+                const stuck = Array.from(indeg.keys()).map((id) => byId.get(id));
+                layers.push(stuck);
+                break;
+            }
+            // 从入度表中移除本层
+            for (const t of layer)
+                indeg.delete(t.id);
+            // 后续任务的入度 -1
+            for (const id of indeg.keys()) {
+                const t = byId.get(id);
+                const deps = (t.dependsOn ?? []).filter((d) => indeg.has(d));
+                indeg.set(id, deps.length);
+            }
+            layers.push(layer);
+            remaining -= layer.length;
+        }
+        return layers;
+    }
+    /**
+     * 收集"阻塞下游执行"的上游：状态非 done 的依赖
+     */
+    collectBlockingUpstream(task, upstream) {
+        const blocking = [];
+        for (const dep of task.dependsOn ?? []) {
+            const r = upstream.get(dep);
+            if (!r || r.status !== 'done')
+                blocking.push(r ?? this.makeMissingResult(dep, task.to));
+        }
+        return blocking;
+    }
+    /**
+     * 把上游 done 结果拼接进 child 的 message，让子 Agent 能拿到上下文
+     */
+    buildChildMessage(task, upstream) {
+        const deps = (task.dependsOn ?? [])
+            .map((d) => upstream.get(d))
+            .filter((r) => !!r && r.status === 'done' && !!r.output);
+        if (deps.length === 0)
+            return task.task;
+        const blocks = deps.map((d) => `- [${d.taskId} by ${d.agentId}]\n${(d.output ?? '').trim()}`);
+        return [
+            '## 前置任务结果',
+            blocks.join('\n\n'),
+            '',
+            '## 你的任务',
+            task.task,
+        ].join('\n');
+    }
+    makeAbortedResult(task) {
+        return {
+            taskId: task.id,
+            agentId: task.to,
+            runId: `child:${task.id}:aborted`,
+            status: 'aborted',
+            errorMessage: '已停止',
+        };
+    }
+    makeUpstreamFailedResult(task) {
+        return {
+            taskId: task.id,
+            agentId: task.to,
+            runId: `child:${task.id}:upstream_failed`,
+            status: 'failed',
+            errorMessage: 'upstream_failed',
+        };
+    }
+    makeMissingResult(taskId, agentId) {
+        return {
+            taskId,
+            agentId,
+            runId: `child:${taskId}:missing`,
+            status: 'failed',
+            errorMessage: 'missing upstream result',
+        };
+    }
+}