lightclawbot 1.2.6-beta.0 → 1.2.7

package/dist/src/group/orchestrator/execution/agent-runner.js

@@ -0,0 +1,299 @@
+/**
+ * AgentRunner —— Agent 执行器（基于 dispatchReplyFromConfig 的实现）
+ *
+ * 历史背景：
+ *   早期实现直接调用 `runtime.subagent.run + waitForRun + events.onAgentEvent`，
+ *   该路径仅在「Gateway request 范围」内可用；当 channel plugin 在后台 socket
+ *   循环中（非 inbound 请求 scope）调用时，SDK 会抛
+ *   "Plugin runtime subagent methods are only available during a gateway request"。
+ *
+ * 现行实现：
+ *   与私聊 inbound.ts 一致，统一走
+ *     `runtime.channel.reply.dispatchReplyFromConfig` + `withReplyDispatcher`
+ *   该路径由 SDK 自行管理 agent run 生命周期，无需手动操作 subagent。
+ *
+ * 职责：
+ *  1. 拼装 sessionKey：`agent:<agentId>:<channel>:group:<groupId>`
+ *  2. 通过 `finalizeInboundContext` 构造群聊 InboundContext（ChatType: 'group'）
+ *  3. 自定义 lightweight ReplyDispatcher：
+ *     - sendBlockReply / sendFinalReply 用于聚合 finalText（也作为兜底来源）
+ *     - sendToolResult 用于产 tool kind 的 StreamChunk
+ *  4. 自定义 replyOptions：
+ *     - onPartialReply / onAssistantMessageStart / onToolStart 转 StreamChunk
+ *     - onAgentRunStart 捕获真实 runId
+ *     - abortSignal 透传给 SDK，原生级联中止
+ *  5. 用 `withReplyDispatcher(dispatcher, run)` 包裹 dispatchReplyFromConfig，
+ *     自动处理 markComplete / 异常兜底
+ *  6. 错误兜底：SDK 抛错 / 超时 / abort 都转换成结构化 status 返回，不再外抛
+ *
+ * 设计要点：
+ *  - 不写群账本：调用方拿到 finalText 后由路径层决定是否写
+ *  - 不感知出站协议：完全交给注入的 StreamSink
+ *  - 不依赖 runtime.subagent / runtime.events，规避 gateway-request scope 限制
+ */
+import { CHANNEL_KEY } from '../../../config.js';
+import { getLightclawRuntime } from '../../../runtime.js';
+import { getModuleLogger } from '../../../utils/logger.js';
+/**
+ * Agent 执行器
+ */
+export class AgentRunner {
+    accountId;
+    log;
+    constructor(options) {
+        this.accountId = options.accountId;
+        this.log = getModuleLogger('group.agent-runner');
+    }
+    /** 获取 PluginRuntime 实例（延迟获取，确保运行时已初始化） */
+    get runtime() {
+        return getLightclawRuntime();
+    }
+    /**
+     * 拼装群聊场景下的 sessionKey
+     *
+     * 与 `src/inbound.ts` 中私聊形态保持一致的命名风格：
+     *   私聊：agent:<agentId>:<channel>:direct:<userId>
+     *   群聊：agent:<agentId>:<channel>:group:<groupId>
+     *
+     * @param agentId - Agent ID
+     * @param groupId - 群 ID
+     */
+    static buildGroupSessionKey(agentId, groupId) {
+        return `agent:${agentId}:${CHANNEL_KEY}:group:${groupId}`;
+    }
+    /**
+     * 执行一次 Agent run
+     *
+     * @param input - 执行入参
+     * @returns run 终态聚合结果
+     */
+    async run(input) {
+        const sessionKey = AgentRunner.buildGroupSessionKey(input.agentId, input.groupId);
+        const tag = `[${CHANNEL_KEY}: AgentRunner ${input.role} ${input.agentId}@${input.groupId}]`;
+        const preRunId = input.preassignedRunId ?? '';
+        // ── 1. 已 abort 直接短路 ──
+        if (input.abortSignal.aborted) {
+            this.log.info(`${tag} abort before start`);
+            const empty = {
+                runId: preRunId,
+                agentId: input.agentId,
+                status: 'aborted',
+                finalText: '',
+            };
+            // 群聊场景：通过 sinkContext 发出 abort 终态帧
+            if (input.sinkContext) {
+                input.sinkContext.dispatcher.markComplete({ aborted: true });
+            }
+            return empty;
+        }
+        // ── 2. 装配 dispatcher 与 replyOptions ──
+        // 优先使用外部注入的 sinkContext（由路径层通过 createStreamReplyConfig 构造）
+        // 若未注入则内部构造（兼容旧调用方式，但群聊场景下应始终注入）
+        const sinkContext = input.sinkContext ?? this.createInternalSinkContext(input, tag);
+        const { dispatcher, replyOptions } = sinkContext;
+        // ── 3. 构造 InboundContext（群聊形态） ──
+        const fromAddress = `user:${input.userId}`;
+        // 构造媒体字段：SDK 的媒体理解管线依赖 MediaPaths/MediaUrls/MediaTypes 来处理文件
+        // （与私聊 inbound.ts 保持一致，确保 vision 模型能"看到"图片等媒体文件）
+        const mediaFields = {};
+        if (input.attachments && input.attachments.length > 0) {
+            const mediaUrls = input.attachments.map((a) => a.url);
+            const mediaTypes = input.attachments.map((a) => a.mimeType);
+            // 本地路径：SDK vision 模型优先通过 MediaPaths 读取本地文件内容
+            const mediaPaths = input.attachments.map((a) => a.localPath).filter((p) => !!p);
+            if (mediaPaths.length > 0) {
+                mediaFields.MediaPaths = mediaPaths;
+                mediaFields.MediaPath = mediaPaths[0];
+            }
+            mediaFields.MediaUrls = mediaUrls;
+            mediaFields.MediaUrl = mediaUrls[0];
+            mediaFields.MediaTypes = mediaTypes;
+            mediaFields.MediaType = mediaTypes[0];
+        }
+        const ctxPayload = this.runtime.channel.reply.finalizeInboundContext({
+            Body: input.message,
+            BodyForAgent: input.message,
+            RawBody: input.message,
+            CommandBody: input.message,
+            From: fromAddress,
+            To: `${CHANNEL_KEY}:${this.accountId}`,
+            Channel: CHANNEL_KEY,
+            ChatType: 'group',
+            SessionKey: sessionKey,
+            AccountId: this.accountId,
+            SenderId: input.userId,
+            SenderName: input.userId,
+            Provider: CHANNEL_KEY,
+            Surface: CHANNEL_KEY,
+            Timestamp: Date.now(),
+            OriginatingChannel: CHANNEL_KEY,
+            OriginatingTo: fromAddress,
+            AgentId: input.agentId,
+            // 群聊上下文额外标识：便于工具层按 groupId 还原会话
+            GroupId: input.groupId,
+            ConversationKind: 'group',
+            // 文件附件元数据：传递给 AI 上下文
+            Attachments: input.attachments && input.attachments.length > 0 ? input.attachments : undefined,
+            // 媒体字段：SDK 媒体理解管线所需（MediaUrls/MediaTypes），使 AI 能真正"看到"文件内容
+            ...mediaFields,
+            // 群协作指令 + 群成员能力卡作为 GroupSystemPrompt 注入，
+            // SDK 会将其作为 extraSystemPromptParts 的一部分追加到 agent 的 system prompt 中，
+            // 确保 LLM 将派活指令视为系统级指令而非用户消息。
+            GroupSystemPrompt: input.systemPrompt || undefined,
+        });
+        // ── 4. 加载最新配置并执行 dispatch ──
+        const cfg = this.runtime.config.loadConfig();
+        let timedOut = false;
+        let timer;
+        // 构造 configOverride：
+        //  - tools.deny: 禁用指定的内置工具（如 sessions_spawn）
+        //  - tools.agentToAgent: 启用跨 Agent 通信权限（群聊派活场景必需）
+        //  - responseFormat: 强制 JSON 输出（Planning 阶段使用）
+        const hasDeny = input.denyTools && input.denyTools.length > 0;
+        const hasA2A = input.enableAgentToAgent;
+        const hasJson = input.jsonMode;
+        const configOverride = hasDeny || hasA2A || hasJson
+            ? {
+                tools: {
+                    ...(hasDeny ? { deny: input.denyTools } : {}),
+                    ...(hasA2A ? { agentToAgent: { enabled: true } } : {}),
+                },
+                ...(hasJson ? { responseFormat: { type: 'json_object' } } : {}),
+            }
+            : undefined;
+        try {
+            await this.runtime.channel.reply.withReplyDispatcher({
+                dispatcher,
+                run: () => {
+                    const dispatchPromise = this.runtime.channel.reply.dispatchReplyFromConfig({
+                        ctx: ctxPayload,
+                        cfg,
+                        dispatcher,
+                        replyOptions,
+                        configOverride,
+                    });
+                    if (input.timeoutMs && input.timeoutMs > 0) {
+                        return Promise.race([
+                            dispatchPromise,
+                            new Promise((_, reject) => {
+                                timer = setTimeout(() => {
+                                    timedOut = true;
+                                    reject(new Error(`dispatchReplyFromConfig timeout after ${input.timeoutMs}ms`));
+                                }, input.timeoutMs);
+                            }),
+                        ]);
+                    }
+                    return dispatchPromise;
+                },
+            });
+        }
+        catch (err) {
+            const e = err instanceof Error ? err : new Error(String(err));
+            this.log.error(`${tag} dispatch failed: ${e.message}`);
+            // dispatch 异常时通过 markComplete 通知 sink 终态
+            dispatcher.markComplete({ aborted: timedOut || input.abortSignal.aborted });
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+        }
+        // ── 5. 归一化 status ──
+        // 从 sinkContext 获取最终文本（通过 hasEmittedContent 判断是否有输出）
+        const realRunId = sinkContext.getRunId() || preRunId;
+        const aborted = input.abortSignal.aborted;
+        const normalizedStatus = aborted ? 'aborted' : timedOut ? 'timeout' : 'ok';
+        // 获取最终文本：从 sinkContext 获取聚合后的完整文本
+        // markComplete 已经在 withReplyDispatcher 内部被 SDK 调用过了（正常路径）
+        const finalText = sinkContext.getFinalText();
+        const result = {
+            runId: realRunId,
+            agentId: input.agentId,
+            status: normalizedStatus,
+            finalText,
+            error: timedOut ? new Error(`timeout after ${input.timeoutMs}ms`) : undefined,
+        };
+        this.log.info(`${tag} finished runId=${realRunId} status=${normalizedStatus} bytes=${finalText.length}`);
+        return result;
+    }
+    /**
+     * 内部构造 SinkContext（兼容旧调用方式，不推荐）
+     *
+     * 当调用方未注入 sinkContext 时使用此方法构造一个最小化的 context。
+     * 群聊场景下应始终由路径层注入外部构造的 sinkContext。
+     */
+    createInternalSinkContext(input, tag) {
+        const log = this.log;
+        // 内部状态
+        let streamedText = '';
+        let finalText = '';
+        let lastFinalReplyText = '';
+        let abortDetected = false;
+        let completed = false;
+        const dispatcher = {
+            sendToolResult: (_payload) => {
+                return true;
+            },
+            sendBlockReply: (payload) => {
+                if (payload.text && payload.text.length > streamedText.length) {
+                    streamedText = payload.text;
+                }
+                return true;
+            },
+            sendFinalReply: (payload) => {
+                const text = payload.text ?? '';
+                if (/^⚙️ Agent was aborted\./.test(text.trim())) {
+                    abortDetected = true;
+                    return true;
+                }
+                if (/Previous run is still shutting down/i.test(text)) {
+                    log.warn(`${tag} SDK session lock conflict detected, suppressing: ${text.slice(0, 100)}`);
+                    abortDetected = true;
+                    return true;
+                }
+                if (text.length > 0) {
+                    lastFinalReplyText = text;
+                }
+                return true;
+            },
+            waitForIdle: async () => {
+                /* no-op */
+            },
+            getQueuedCounts: () => ({ tool: 0, block: 0, final: 0 }),
+            getFailedCounts: () => ({ tool: 0, block: 0, final: 0 }),
+            markComplete: () => {
+                completed = true;
+            },
+        };
+        const replyOptions = {
+            runId: input.preassignedRunId,
+            abortSignal: input.abortSignal,
+            onPartialReply: (payload) => {
+                if (!payload.text)
+                    return;
+                const delta = payload.text.startsWith(streamedText) ? payload.text.slice(streamedText.length) : payload.text;
+                streamedText = payload.text.startsWith(streamedText) ? payload.text : streamedText + delta;
+            },
+            onAssistantMessageStart: () => {
+                if (streamedText) {
+                    finalText += (finalText ? '\n' : '') + streamedText;
+                    streamedText = '';
+                }
+            },
+            suppressTyping: true,
+            disableBlockStreaming: true,
+        };
+        return {
+            dispatcher,
+            replyOptions,
+            hasEmittedContent: () => streamedText.length > 0 || finalText.length > 0,
+            emitStart: () => {
+                /* no-op for internal sink */
+            },
+            getRunId: () => input.preassignedRunId,
+            getFinalText: () => {
+                const aggregated = finalText && streamedText ? `${finalText}\n${streamedText}` : finalText || streamedText;
+                return aggregated || lastFinalReplyText;
+            },
+        };
+    }
+}

package/dist/src/group/orchestrator/execution/index.js

@@ -0,0 +1,7 @@
+/**
+ * @file execution 子模块出口
+ * @description 统一导出 AgentRunner / SoulResolver / PromptBuilder 及其类型
+ */
+export { AgentRunner } from './agent-runner.js';
+export { SoulResolver } from './soul-resolver.js';
+export { PromptBuilder } from './prompt-builder.js';

package/dist/src/group/orchestrator/execution/prompt-builder.js

@@ -0,0 +1,288 @@
+/**
+ * PromptBuilder —— 三段式 system prompt 构造器
+ *
+ * 主 Agent 在群聊场景下扮演两种形态、子 Agent 一种形态，对应三个构造方法：
+ *
+ *  1. buildLeader       自答阶段：本体 SOUL（由 SDK 注入）+ 群协作扩展指令 + 群成员能力卡
+ *
+ *  2. buildSummarizer   汇总阶段：本体 SOUL（由 SDK 注入）+ 子任务结果列表
+ *
+ *  3. buildChild        子 Agent：本体 SOUL（由 SDK 注入）+ 任务上下文
+ *
+ * 设计要点：
+ *  1. 本体 SOUL 由 OpenClaw SDK 自动加载（`~/.openclaw/agents/<agentId>/SOUL.md`），
+ *     这里只产出 *     这里只产出"额外注入"的部分，通过 SubagentRunParams.extraSystemPrompt 传给 SDK；
+ *  2. 群成员能力卡来自群账本 meta.json 中的 GroupMember 数据；
+ *  3. 模板与"主Agent设计.md §2.2 / §2.3"中文案保持一致；
+ *  4. 纯函数：不做 IO，便于单测。
+ */
+/**
+ * PromptBuilder 主体（无状态，方法纯函数）
+ */
+export class PromptBuilder {
+    /**
+     * 构造主 Agent 自答阶段的额外 system prompt（提供群成员信息上下文）
+     */
+    buildLeader(input) {
+        const members = this.buildMemberCards(input.memberCards, input.leaderAgentId);
+        return `---
+**场景设定**  
+在团队协作类群聊环境中，作为群内沟通协调的核心角色，负责引导和管理群内成员的交流流程、整合多方意见并推动问题解决，适用于团队项目讨论、工作事务沟通等多成员参与的实时互动场景。  
+
+**AI角色**  
+群聊协作管理专家（领航员），具备沟通引导、信息整合、问题分析与解决方案输出的专业能力，以协助团队成员高效完成协作任务。  
+
+**核心任务**  
+1. 接收并准确理解群内成员提出的问题、需求或请求；  
+2. 调用group_chat_history工具查询群内历史对话内容及其他成员的回复信息；  
+3. 基于历史对话和当前需求，提供针对性协作方案、沟通技巧或决策建议；  
+4. 以流式输出形式持续回应，保持对话连贯性与指导性。  
+
+**输出要求**  
+- 格式：自然语言文本  
+- 风格：专业、友好、指导性强，符合商务/团队协作沟通语境  
+- 长度：无严格字数限制，根据问题复杂度灵活调整，确保信息完整且不过于冗长  
+- 关键要素：包含问题回应、历史参考信息（如适用）、协作方案建议  
+
+**约束条件**  
+⚠️ 排除事项：不提供与群聊协作无关的内容；不泄露群成员隐私信息；不发表具有争议性或违法导向的观点；仅基于群内合理场景提供指导。敏感词过滤：不涉及政治敏感、人身攻击、负面情绪宣泄等内容。数据来源限制：仅依托群内历史对话记录和合理逻辑推导提供信息，不虚构群外未发生的事件或信息。
+
+**群成员信息**
+${members}`;
+    }
+    /**
+     * 构造 Planning 阶段的 system prompt（新方案：强制 JSON 输出决策）
+     *
+     * 该 prompt 要求 LLM 输出结构化 JSON，二选一：
+     *  - { action: "self_answer" }  → 自己直接回答
+     *  - { action: "dispatch", ... } → 拆分派活
+     */
+    buildPlanner(input) {
+        const members = this.buildMemberCards(input.memberCards, input.leaderAgentId);
+        return `---
+## 场景设定  
+在一个多Agent协作的群聊环境中，你作为特定群组的领航员（对应 ${input.leaderAgentId} 角色），需要接收用户发送的消息并判断是否由自身直接回应或协调群内其他Agent协作完成任务，属于团队协作流程中的任务分配与决策环节。  
+
+## AI角色
+团队协作流程中的群组领航型智能助手（任务决策与分配角色），具备分析任务复杂度、判断协作需求的专业能力。  
+
+## 核心任务  
+以群组领航员的身份，分析用户发送的消息内容，依据任务复杂度与群成员能力匹配度，从“自己直接回答”和“拆分派活”两种方案中选择其一，若选择拆分派活，需明确拆分逻辑、过渡话表述与子任务分配，确保符合协作约束规则。
+
+## 输出要求
+- 格式：JSON  
+- 风格：专业、简洁、指令性  
+- 长度：单条JSON对象，不超过200字符（含必要字段）  
+- 关键要素：包含action、thinking、transition、tasks等必要字段（若选拆分派活），或仅包含action字段（若选自己回答）。 
+- 你必须且只能输出一个 JSON 对象，不要输出任何其他文字、markdown 标记或代码块包裹。
+
+## 输出格式
+### 决策一：自己回答
+
+{"action":"self_answer"}
+
+### 决策二：拆分派活
+
+{
+  "action": "dispatch",
+  "thinking": "简要说明你的拆分思路（1-2句话），需说明任务间是否有先后依赖",
+  "transition": "给用户看的过渡话，需要用 @agentName 提及对应的 Agent，例如：好的，我让 @设计师 负责logo，@程序员 负责页面开发。
+  "tasks": [
+    {
+      "id": "t1",
+      "to": "agentId_A",
+      "task": "第一个任务描述（无依赖，最先执行）",
+      "dependsOn": []
+    },
+    {
+      "id": "t2",
+      "to": "agentId_B",
+      "task": "第二个任务描述（需要t1的产出物才能完成）",
+      "dependsOn": ["t1"]
+    }
+  ]
+}
+
+## 拆活约束
+
+- \`to\` 必须是下方「群成员」列表中的 agentId，不能是你自己（${input.leaderAgentId}）
+- 最多拆 5 个子任务，能合并的合并
+- 不可循环依赖
+- \`task\` 描述要完整自洽，子 Agent 不会看到用户原始消息的全部上下文
+- \`transition\` 过渡话中必须用 @name 格式提及每个被派活的 Agent（使用群成员的 name 而非 agentId），让用户清楚谁在做什么
+
+## dependsOn 依赖判断规则
+
+判断任务之间是否存在依赖关系，核心原则：**如果任务 B 需要使用任务 A 的产出物（如文件、设计稿、数据、代码等）才能正确完成，则 B 必须依赖 A**。
+
+### 必须设置 dependsOn 的场景：
+- 设计/创作类任务产出素材 → 开发/集成类任务使用该素材（如：设计logo → 把logo写到页面）
+- 数据生成任务 → 数据消费任务（如：爬取数据 → 分析数据）
+- 基础架构搭建 → 基于该架构的功能开发（如：搭建项目框架 → 开发具体功能模块）
+
+### 可以并行（dependsOn 留空 []）的场景：
+- 各任务之间相互独立，不需要对方的产出物（如：写文案 + 设计图标，两者互不依赖）
+- 任务虽然属于同一项目，但各自可以独立完成（如：开发登录页 + 开发注册页）
+
+### 示例：
+用户说"设计一个logo并写到网页中"：
+- t1: 设计师设计logo → dependsOn: []
+- t2: 程序员把logo写到网页 → dependsOn: ["t1"]（因为程序员需要设计师产出的logo文件）
+
+## 决策要点
+
+- 若群内无成员具备匹配该任务的能力，则执行self_answer；  
+- 若任务仅需单一领域知识且自身能够胜任，则执行self_answer；  
+- 若任务涉及多个领域或明确需要特定专业Agent的能力支持，则执行dispatch；  
+- 若明确要求"大家"、"所有人"、"每个人"各自完成某事（如自我介绍、各自发表意见），则执行dispatch，让每个成员独立回答； 
+- 若任务可拆分成更小子任务，则尝试将任务拆分为合理子任务后再分配； 
+
+## 群成员信息
+${members}
+
+---
+[用户消息]
+
+${input.userMessage.trim()}`;
+    }
+    /**
+     * 构造主 Agent 汇总阶段的额外 system prompt
+     */
+    buildSummarizer(input) {
+        return `---
+## 场景设定  
+在多群体聊协作项目完成后，各群成员已独立完成子任务，现处于汇总答复阶段，需要将各成员任务成果整合为统一最终答复提供给用户的场景。  
+
+## AI角色 
+团队协作汇总型专业助手，具备信息整合、内容提炼与自然语言沟通能力的协作支持角色，专注于完成从分散成果到完整答复的专业转化工作。  
+
+## 核心任务
+接收各群成员提交的所有子任务成果，执行信息整合与提炼操作，以自然语言生成完整最终答复；确保涵盖所有关键信息、核心结论与要点，同时处理可能存在的失败子任务情况（诚实告知并提供建议）；严格遵守汇总答复要求，仅输出整合后的最终答复，不涉及任务分配或决策类表述。  
+
+## 输出要求
+- 格式：Markdown  
+- 风格：正式自然，逻辑连贯  
+- 长度：约50-200字  
+- 关键要素：各任务成果总结、核心结论、关键要点、后续建议（若有失败任务）、自然语言表达  
+
+## 约束条件  
+- 严格遵守禁止项：不输出JSON格式；
+- 不逐字复述群员输出，需做信息整合；确保紧扣用户原始诉求，不凭空发挥；
+- 若存在失败的子任务，需诚实告知用户并提出可行后续建议。
+
+## 用户原始诉求
+
+${input.userMessage.trim()}
+
+## 群成员任务执行结果
+${this.formatSubtaskResults(input.subtaskResults)}`;
+    }
+    /**
+     * 构造创建群后主Agent欢迎消息的额外 system prompt
+     *
+     * @remarks
+     * 创建群成功后，主Agent需要根据群目标和成员能力，生成一条欢迎消息，
+     * 包含：欢迎词 + 群目标总结 + 开始方向建议。
+     */
+    buildWelcome(input) {
+        const members = this.buildMemberCards(input.memberCards, input.leaderAgentId);
+        return `---
+## 场景设定
+你是一个多 Agent 协作群的领航员（主 Agent），群刚刚被创建成功。你需要发送一条欢迎消息，向创建者介绍这个群的目标和如何开始。
+
+## AI角色
+群聊协作领航员，负责引导团队开展工作、明确目标方向、提供建议。
+
+## 核心任务
+根据群的名称和目标描述，生成一条热情、专业的欢迎消息，内容包括：
+1. 欢迎来到「群名称」
+2. 简要总结群的终极目标是什么
+3. 询问创建者当前的想法或方向（如风格、技术栈、优先级等）
+4. 提供 2-3 个建议的开始方向，让创建者可以快速上手
+5. 提及群规则（如可以随时 @ 成员）
+
+## 输出要求
+- 格式：Markdown
+- 风格：热情、友好、专业，像一个经验丰富的团队协作者
+- 长度：100-200字
+- 语气：自然随和，不要过于正式
+
+## 约束条件
+- 不要输出 JSON 格式
+- 不要派活或分配任务
+- 不要编造群成员的能力，仅基于下方提供的成员信息
+- **提及成员时必须使用名称（如 @程序员、@设计师），绝不要使用 agentId（如 @agent-xxx）**
+
+## 群信息
+- 群名称：${input.groupName}
+- 群目标：${input.groupDesc}
+
+${members}`;
+    }
+    /**
+     * 构造子 Agent 任务阶段的额外 system prompt
+     */
+    buildChild(input) {
+        const userContext = input.userMessage?.trim()
+            ? `\n## 用户原始诉求（仅供参考）\n\n${input.userMessage.trim()}\n`
+            : '';
+        return `---
+[群聊协作 - 子任务模式]
+
+你正在群聊中作为群成员协作。领航员（${input.leaderAgentId}）把以下子任务派给了你：
+
+## 你的任务
+
+${input.taskDescription.trim()}
+
+## 必须遵守
+
+- ✅ 专注完成上述任务，输出可被领航员直接整合的结果。
+- ✅ 输出要简洁、结构化，避免大段寒暄。
+- ❌ **你不能再次派活给其他 Agent**（最多 1 层嵌套）。
+- ❌ 不要替领航员给用户做最终答复，那是领航员的职责。
+${userContext}
+## 可用工具提示
+
+- 如果你需要了解群聊中之前的对话内容或其他成员的回复，可以调用 \`group_chat_history\` 工具查询历史记录。`;
+    }
+    /**
+     * 群成员能力卡片块
+     */
+    buildMemberCards(cards, leaderAgentId) {
+        const others = cards.filter((c) => c.agentId !== leaderAgentId);
+        if (others.length === 0) {
+            return `---
+[群成员（不含你自己）]
+
+（当前群里没有其他可派活成员，请直接独立完成任务。）`;
+        }
+        const memberList = others
+            .map((c) => {
+            const summary = c.summary.replace(/\n+/g, ' ').trim();
+            return `- **${c.name}** (agentId: ${c.agentId})\n  ${summary}`;
+        })
+            .join('\n\n');
+        return `---
+[群成员（不含你自己）]
+
+${memberList}
+
+> 注意：提及成员时请使用 @名称（如 @${others[0].name}），不要使用 @agentId`;
+    }
+    /**
+     * 子任务结果列表序列化
+     */
+    formatSubtaskResults(results) {
+        if (results.length === 0) {
+            return '（无子任务结果）';
+        }
+        const blocks = results.map((r, idx) => {
+            const ok = r.status === 'done';
+            const head = `### 子任务 ${idx + 1} - ${r.taskId} (${r.agentId}) - ${ok ? '✅ 成功' : `❌ ${r.status}`}`;
+            const body = ok ? (r.output ?? '（无输出）').trim() : `失败原因：${(r.errorMessage ?? '未知错误').trim()}`;
+            return [head, '', body].join('\n');
+        });
+        return blocks.join('\n\n');
+    }
+}

package/dist/src/group/orchestrator/execution/soul-resolver.js

@@ -0,0 +1,38 @@
+/**
+ * @file SoulResolver —— 群成员能力解析器
+ *
+ * 职责：
+ *  - 从群账本 meta.json 中的 GroupMember 数据直接构建 AgentCapabilityCard
+ *  - 不涉及任何文件 IO，能力信息完全来源于群元数据
+ *  - 输出 AgentCapabilityCard，供 PromptBuilder 拼接能力卡片块
+ */
+/**
+ * 群成员能力解析器
+ *
+ * 将 GroupMember（群账本元数据）映射为 AgentCapabilityCard（能力卡片），
+ * 供 PromptBuilder 在构建 Leader 编排 prompt 时使用。
+ */
+export class SoulResolver {
+    /**
+     * 解析单个群成员为能力卡片
+     *
+     * @param member - 群成员信息（来自 meta.json 的 GroupMember）
+     * @returns 对应的 AgentCapabilityCard
+     */
+    resolve(member) {
+        return {
+            agentId: member.agentId,
+            name: member.agentName || member.agentId,
+            summary: member.agentDesc || '',
+        };
+    }
+    /**
+     * 批量解析群成员列表为能力卡片数组（保证顺序与输入一致）
+     *
+     * @param members - GroupMember 列表（来自 meta.json）
+     * @returns AgentCapabilityCard 数组
+     */
+    resolveMany(members) {
+        return members.map((m) => this.resolve(m));
+    }
+}

package/dist/src/group/orchestrator/execution/types.js

@@ -0,0 +1,7 @@
+/**
+ * 执行层（execution）公共类型
+ *
+ * 收敛 AgentRunner / SoulResolver / PromptBuilder
+ * 之间共享的接口形状，避免循环依赖。
+ */
+export {};

package/dist/src/group/orchestrator/index.js

@@ -0,0 +1,14 @@
+/**
+ * @file Orchestrator 模块出口
+ * @description 统一导出调度器相关的类型、基础设施层、执行层、路径层和门面
+ */
+// ── 公共工具函数（从统一工具层转发） ──
+export { generatePreRunId, normalizeRunStatus, errorToString, } from '../utils/index.js';
+// ── 基础设施层（lifecycle） ──
+export { ConversationStateMachine, RunRegistry, LedgerWriter, } from './lifecycle/index.js';
+// ── 执行层（execution） ──
+export { AgentRunner, SoulResolver, PromptBuilder, } from './execution/index.js';
+// ── 路径层（routes） ──
+export { LeaderOrchestrationRoute, } from './routes/index.js';
+// ── 调度器门面 ──
+export { Orchestrator } from './orchestrator.js';