@downcity/agent 1.1.408 → 1.1.437

package/src/types/executor/SessionTurnContext.ts

@@ -7,18 +7,25 @@
  * - 可变状态只能通过行为方法更新，消费者不能直接操作内部数组、lease 或 callback。
  */
 
-import type { ShellApprovalGateway } from "@downcity/workspace";
-import type { SessionUserMessage } from "@/types/session/SessionMessage.js";
-import type { SessionAssistantResultPart } from "@/types/session/SessionContent.js";
+import type { RuntimeToolEffect } from "@downcity/type";
+import type { ShellApprovalGateway } from "@downcity/type";
+import type {
+  SessionModelUserContent,
+  SessionUserMessage,
+} from "@downcity/type";
+import type { SessionAgentContent } from "@downcity/type";
 import type { SessionAssistantOutput } from "@/types/executor/SessionAssistantOutput.js";
-import type { AgentPluginExecutionLease } from "@/types/plugin/PluginRuntime.js";
-import type { PluginExecutionContext } from "@/types/plugin/PluginExecutionContext.js";
+import type { SessionHookContext } from "@downcity/type";
+import type { SessionHookScopeRuntime } from "@downcity/type";
 import type {
   AgentSessionActionCallback,
   AgentSessionActionEvent,
   AgentSessionActionRecord,
 } from "@/types/sdk/AgentSessionAction.js";
-import type { SessionInteractionPort } from "@/types/session/SessionInteraction.js";
+import type { SessionInteractionPort } from "@downcity/type";
+import type { SessionOrigin } from "@downcity/type";
+import type { SessionHookContextBlock } from "@downcity/type";
+import type { ModelRequestFailureNotice } from "@downcity/type";
 
 /**
  * 创建一个 Session Turn 上下文所需的稳定输入。
@@ -29,6 +36,9 @@ export interface SessionTurnContextInit {
   /** 当前执行所属的 Session 标识。 */
   session_id: string;
 
+  /** 当前执行所属 Session 的完整来源元数据。 */
+  session_origin: SessionOrigin;
+
   /** 当前执行所属的非空 Turn 标识。 */
   turn_id: string;
 
@@ -38,26 +48,34 @@ export interface SessionTurnContextInit {
   /** 上游取消信号；上下文会把它转发到自身拥有的运行生命周期。 */
   abort_signal?: AbortSignal;
 
-  /** 在 Step 检查点消费 Session 队列，并返回应并入模型上下文的 User 消息。 */
-  merge_step_input?: () => Promise<SessionUserMessage[]>;
+  /** 在 Step 检查点提交 Session 输入队列；持久化消息由 Composer 重新读取。 */
+  commit_step_input?: () => Promise<void>;
+
+  /** 将 Executor 产生的内部模型输入持久化为当前 Turn 的 canonical User Message。 */
+  append_internal_user_message?: (
+    parts: readonly SessionModelUserContent[],
+  ) => Promise<SessionUserMessage>;
 
   /** 判断是否仍有等待下一个 Step 消费的 User prompt。 */
   has_pending_step_input?: () => boolean;
 
-  /** 消费一次 canonical history 重载请求。 */
-  consume_history_reload?: () => boolean;
-
   /** Executor 写入 canonical Assistant Message 使用的唯一输出端口。 */
   assistant_output?: SessionAssistantOutput;
 
   /** 当前 Session 执行面创建用户异步交互的端口。 */
   interactions?: SessionInteractionPort;
 
-  /** 当前 Session 拥有的 unrestricted Shell 审批网关。 */
+  /** 当前 Session 提供的 host Shell 审批网关。 */
   shell_approval_gateway?: ShellApprovalGateway;
 
+  /** 当前 Turn effects 追加后触发的实时观测回调，宿主可据此广播文件改动摘要。 */
+  on_effects_changed?: (effects: readonly RuntimeToolEffect[]) => void;
+
   /** 把辅助 Action 持久化并发布为 Session 事件的回调。 */
   publish_action?: AgentSessionActionCallback;
+
+  /** 把内部模型请求失败交给 Session 边界投影。 */
+  report_model_request_failure?: (notice: ModelRequestFailureNotice) => void;
 }
 
 /**
@@ -69,6 +87,9 @@ export interface SessionTurnContext {
     /** 当前执行所属的 Session 标识。 */
     readonly session_id: string;
 
+    /** 当前执行所属 Session 的完整来源元数据。 */
+    readonly origin: SessionOrigin;
+
     /** 当前执行所属的 Turn 标识。 */
     readonly turn_id: string;
 
@@ -96,8 +117,11 @@ export interface SessionTurnContext {
     /** 当前 Step 已提交生效的 Agent instruction 快照。 */
     readonly agent_systems: readonly string[];
 
-    /** 当前 Step 持有的 Plugin execution lease；仅供内核执行边界使用。 */
-    readonly plugins?: AgentPluginExecutionLease;
+    /** 当前 Step 持有的稳定 Hook 作用域。 */
+    readonly hooks?: SessionHookScopeRuntime;
+
+    /** 当前 Turn 首次解析后冻结的 Plugin 动态上下文。 */
+    readonly plugin_context_blocks: readonly SessionHookContextBlock[];
 
     /** 原子提交当前 Step 使用的 env 与 instruction 快照。 */
     commit(input: {
@@ -108,35 +132,38 @@ export interface SessionTurnContext {
       agent_systems: readonly string[];
     }): void;
 
-    /** 切换当前 Step 的 Plugin lease，并先释放前一个 lease。 */
-    replace_plugins(plugins?: AgentPluginExecutionLease): Promise<void>;
+    /** 切换当前 Step 的 Hook 作用域，并先关闭前一个作用域。 */
+    replace_hooks(hooks?: SessionHookScopeRuntime): Promise<void>;
+
+    /** 首次调用时解析并冻结动态上下文，后续 Step 与重试复用同一快照。 */
+    resolve_plugin_context_blocks(
+      resolver: () => Promise<readonly SessionHookContextBlock[]>,
+    ): Promise<readonly SessionHookContextBlock[]>;
 
-    /** 释放当前 Step 持有的 Plugin lease。 */
+    /** 释放当前 Step 持有的 Plugin Hook 作用域。 */
     release(): Promise<void>;
 
-    /** 为 Plugin 生成只包含稳定、只读运行快照的新对象。 */
-    plugin_execution_context(call_id?: string): PluginExecutionContext;
+    /** 为 City Plugin 生成只包含稳定、只读运行快照的新对象。 */
+    hook_context(call_id?: string): SessionHookContext;
   };
 
-  /** 当前运行的动态 User 输入及延迟持久化输入。 */
+  /** 当前运行的动态 User 输入。 */
   readonly input: {
-    /** 在 Step 边界消费运行期注入消息与 Session 队列消息。 */
-    checkpoint(): Promise<SessionUserMessage[]>;
+    /** 登记已经持久化、属于本 Turn 的 canonical User Message。 */
+    observe_user_message(message: SessionUserMessage): void;
 
-    /** 判断是否有等待下一个 Step 消费的 Session prompt。 */
-    has_pending(): boolean;
+    /** 返回本 Turn 已登记 User Message 的不可变快照。 */
+    user_messages(): readonly SessionUserMessage[];
 
-    /** 注入一条只影响当前运行、在下一 Step 生效的 User 消息。 */
-    inject_user_message(message: SessionUserMessage): void;
+    /** 提交输入队列；下一 Step 由 Composer 重新读取 canonical history。 */
+    checkpoint(): Promise<void>;
 
-    /** 延迟到 Assistant 结果落盘后再持久化一条 User 消息。 */
-    defer_user_message(message: SessionUserMessage): void;
+    /** 判断是否有等待下一个 Step 消费的 Session prompt。 */
+    has_pending(): boolean;
 
-    /** 返回延迟持久化 User 消息的不可变快照。 */
-    deferred_user_messages(): readonly SessionUserMessage[];
+    /** 持久化一条只供模型消费的内部 canonical User Message。 */
+    append_internal(parts: readonly SessionModelUserContent[]): Promise<SessionUserMessage>;
 
-    /** 消费一次 canonical history 重载请求。 */
-    consume_history_reload(): boolean;
   };
 
   /** 当前运行的 Assistant Message 与辅助 Action 输出能力。 */
@@ -145,13 +172,27 @@ export interface SessionTurnContext {
     readonly assistant?: SessionAssistantOutput;
 
     /** 把 Action 产生的 Assistant Parts 加入当前 Step 收口队列。 */
-    enqueue_assistant_parts(parts: readonly SessionAssistantResultPart[]): void;
+    enqueue_assistant_parts(parts: readonly SessionAgentContent[]): void;
 
     /** 消费当前 Step 中等待写入 canonical Assistant Message 的 Parts。 */
-    take_assistant_parts(): SessionAssistantResultPart[];
+    take_assistant_parts(): SessionAgentContent[];
 
     /** 发布一条不进入 LLM 输入的 Session Action。 */
     publish_action(event: AgentSessionActionEvent): Promise<void>;
+
+    /** 把当前 Turn 的内部模型请求失败交给 Session 边界。 */
+    report_model_request_failure(
+      notice: ModelRequestFailureNotice,
+    ): void;
+  };
+
+  /** 当前 Turn 已经发生、等待在收口检查点投影的 Tool 副作用。 */
+  readonly effects: {
+    /** 按实际发生顺序追加 Tool 副作用。 */
+    append(effects: readonly RuntimeToolEffect[]): void;
+
+    /** 返回当前 Turn 已收集副作用的不可变快照。 */
+    snapshot(): readonly RuntimeToolEffect[];
   };
 
   /** 当前 Session 执行面创建用户异步交互的端口。 */
@@ -159,7 +200,7 @@ export interface SessionTurnContext {
 
   /** 当前运行可使用的 Shell 协作能力。 */
   readonly shell: {
-    /** 当前 Session 拥有的 unrestricted 审批网关。 */
+    /** 当前 Session 提供的 host 执行审批网关。 */
     readonly approval_gateway?: ShellApprovalGateway;
   };
 }

package/src/types/group/DispatchStrategy.ts

@@ -1,8 +1,11 @@
-/** Group 调度策略：为当前消息上下文生成一组有依赖关系的成员投递节点。 */
+/**
+ * Group 调度策略：根据群聊语义与成员画像生成有限的阶段计划。
+ *
+ * 调度器只负责决定谁在什么阶段完成哪项工作，不接触 Agent 的执行能力、完整指令或
+ * Session 生命周期。GroupSession 负责执行计划，并在需要时用真实结果发起下一轮判断。
+ */
 
 import type { GroupMessage } from "@/types/group/Group.js";
-import type { Agent } from "@/agent/Agent.js";
-import type { AgentModel } from "@/agent/AgentModel.js";
 import type {
   ModelClient,
   ModelContent,
@@ -12,69 +15,115 @@ import type {
 import { generate_model } from "@executor/model/ModelGenerate.js";
 import { z } from "zod";
 
-/** 一个投递节点内成员的发言方式。 */
-export type DispatchResponseMode = "single" | "parallel";
-
 /** 本次调度的触发来源。 */
 export type DispatchTrigger = "user" | "auto";
 
-/** 调度图中的一个成员投递节点。 */
-export interface DispatchNode {
-  /** 当前调度图内的稳定节点标识。 */
-  readonly node_id: string;
-  /** 当前节点允许接收消息的成员标识。 */
-  readonly member_ids: readonly string[];
-  /** 当前节点只运行首个成员，还是允许全部成员并行运行。 */
-  readonly response_mode: DispatchResponseMode;
-  /** 当前节点依赖的前置节点标识；依赖完成后才能投递。 */
-  readonly depends_on_node_ids: readonly string[];
-  /** 注入成员 AgentSession 的发言约束。 */
+/** 调度器理解当前 Group 所需的最小身份信息。 */
+export interface DispatchGroupProfile {
+  /** 当前 Group 的稳定标识。 */
+  readonly group_id: string;
+  /** 当前 Group 的用户可见名称。 */
+  readonly name: string;
+  /** 当前 Group 的可选协作目标，用于判断任务是否已经完成。 */
+  readonly instruction?: string;
+}
+
+/** 调度器选择成员所需的最小 Agent 画像。 */
+export interface DispatchMemberProfile {
+  /** 当前成员 Agent 的稳定标识，也是调度协议引用该成员的键。 */
+  readonly agent_id: string;
+  /** 当前成员 Agent 的用户可见名称。 */
+  readonly name: string;
+  /** 当前成员 Agent 的能力描述，用于判断任务与成员是否匹配。 */
+  readonly description: string;
+}
+
+/** 一个阶段中交给单个成员的独立任务。 */
+export interface DispatchAssignment {
+  /** 接收当前任务的成员 Agent 标识。 */
+  readonly member_id: string;
+  /** 当前成员在本阶段需要直接完成的具体任务。 */
   readonly instruction: string;
 }
 
-/** 一次调度生成的当前最佳响应图。 */
+/** 调度计划中的一个顺序阶段；阶段内部的任务并行执行。 */
+export interface DispatchStage {
+  /** 当前计划内稳定、可持久化的阶段标识。 */
+  readonly stage_id: string;
+  /** 当前阶段需要并行执行的成员专属任务。 */
+  readonly assignments: readonly DispatchAssignment[];
+}
+
+/** 一次调度生成的有限阶段计划。 */
 export interface DispatchDecision {
-  /** 当前调度图中的投递节点。 */
-  readonly nodes: readonly DispatchNode[];
-  /** 当前图完成后是否允许唯一的 GroupSession auto dispatch 继续判断。 */
+  /** 调度器对成员选择、阶段安排和停止判断的简要说明。 */
+  readonly reason: string;
+  /** 按顺序执行的阶段；同一阶段内的任务并行执行。 */
+  readonly stages: readonly DispatchStage[];
+  /** 当前计划执行后是否已经可以结束，不再基于结果自动调度。 */
   readonly terminal: boolean;
 }
 
 /** Group 调度策略协议。 */
 export interface DispatchStrategy {
-  /** 根据触发来源、当前消息、历史和成员关系生成当前最佳响应图。 */
+  /** 根据触发来源、当前消息、历史、新增批次和成员画像生成当前最佳阶段计划。 */
   decide_dispatch(input: {
+    /** 当前 Group 的只读语义画像。 */
+    readonly group: DispatchGroupProfile;
     /** 本次调度由用户消息触发，还是由 GroupSession 自动收口触发。 */
     readonly trigger: DispatchTrigger;
-    /** 当前待调度的 Group 消息；auto dispatch 时为本批新增消息中的最后一条。 */
-    readonly message: GroupMessage;
-    /** 当前 auto dispatch 尚未消费的新增消息。 */
+    /** 当前待判断的 Group 消息；它在新增批次中以当前标记出现。 */
+    readonly current_message: GroupMessage;
+    /** 本批新增消息之前的最近 Group 对话，不包含 pending_messages。 */
+    readonly history: readonly GroupMessage[];
+    /** 当前调度尚未消费的新增 Group 消息批次。 */
     readonly pending_messages: readonly GroupMessage[];
-    /** 当前 Group 已存在的消息历史。 */
-    readonly messages: readonly GroupMessage[];
-    /** 当前 Group 成员快照。 */
-    readonly members: readonly Agent[];
-    /** 当前 Dispatch Session Turn 的取消信号。 */
+    /** 当前 Group 成员的只读语义画像。 */
+    readonly members: readonly DispatchMemberProfile[];
+    /** 当前 GroupSession 调度 Turn 的取消信号。 */
     readonly abort_signal: AbortSignal;
   }): Promise<DispatchDecision> | DispatchDecision;
 }
 
 /** AI 调度策略的构造参数。 */
 export interface AiDispatchStrategyOptions {
-  /** Group 用于理解群聊意图并生成调度图的模型。 */
-  readonly model?: AgentModel;
+  /** Group 用于理解群聊意图并生成阶段计划的模型。 */
+  readonly model?: ModelClient;
 }
 
-/** AI 调度工具的最小输入协议；外层阶段串行，阶段内成员并行。 */
+/** AI 调度工具的最小输入协议；阶段串行，阶段内 assignment 并行。 */
 const dispatch_group_input_schema = z.object({
-  steps: z.array(z.array(z.string().trim().min(1)).min(1).max(16)).max(16),
-  /** 当前响应图完成后是否交给唯一的 auto dispatch 继续判断。 */
+  /** 解释成员选择、阶段安排以及停止或继续的语义依据。 */
+  reason: z.string().trim().min(1).max(2_000),
+  /** 当前已经可以确定的有限工作阶段。 */
+  stages: z.array(z.object({
+    /** 当前阶段内可以独立并行的成员任务。 */
+    assignments: z.array(z.object({
+      /** 接收任务的真实成员 Agent 标识。 */
+      member_id: z.string().trim().min(1),
+      /** 该成员需要直接完成的具体任务。 */
+      instruction: z.string().trim().min(1).max(4_000),
+    })).min(1).max(16),
+  })).max(16),
+  /** 当前阶段执行完即可结束，还是必须依据实际结果再判断一次。 */
   next: z.enum(["stop", "continue"]),
 });
 
 const max_dispatch_model_steps = 3;
 
-/** 使用 Group.model 理解群聊意图并通过内部 tool call 生成成员投递决定。 */
+const dispatch_system_prompt = [
+  "你是 Group 的语义调度器，只能调用一次 dispatch_group，不得直接回答用户问题。",
+  "你的职责是用最少的必要成员和阶段满足用户意图，并在语义上已经完成时立即停止。",
+  "请根据 Group 目标、成员名称和能力描述选择成员；只能选择给出的真实 member_id。",
+  "普通任务默认只交给一个最匹配的成员。只有任务可独立并行，或用户明确要求多人分别回答时，才在同一阶段安排多个 assignment。",
+  "每个 assignment 必须写成员专属、可以直接执行的具体任务，不能只写‘回复用户’或重复成员身份。",
+  "stages 按顺序执行，同一 stage 内的 assignments 并行执行。已知的连续步骤应一次规划进多个 stages。",
+  "next=continue 仅用于下一步选择必须依赖本轮成员的实际输出；它不是邀请更多成员继续讨论。",
+  "若当前对话已经满足用户意图，返回 stages=[]、next=stop。若所列 stages 执行后即可满足意图，也使用 next=stop。",
+  "不得因为尚有其他成员、礼貌附和、重复总结、非必要 review 或维持对话而继续。",
+].join("\n");
+
+/** 使用 Group.model 理解群聊意图并通过内部 tool call 生成阶段计划。 */
 export class AiDispatchStrategy implements DispatchStrategy {
   private readonly model?: ModelClient;
 
@@ -83,11 +132,12 @@ export class AiDispatchStrategy implements DispatchStrategy {
   }
 
   async decide_dispatch(input: {
+    readonly group: DispatchGroupProfile;
     readonly trigger: DispatchTrigger;
-    readonly message: GroupMessage;
+    readonly current_message: GroupMessage;
+    readonly history: readonly GroupMessage[];
     readonly pending_messages: readonly GroupMessage[];
-    readonly messages: readonly GroupMessage[];
-    readonly members: readonly Agent[];
+    readonly members: readonly DispatchMemberProfile[];
     readonly abort_signal: AbortSignal;
   }): Promise<DispatchDecision> {
     if (!this.model) {
@@ -95,7 +145,7 @@ export class AiDispatchStrategy implements DispatchStrategy {
     }
     try {
       const messages: ModelMessage[] = [
-        { role: "system", content: [{ type: "text", text: "你是群聊消息调度器。你只能调用 dispatch_group，不回答用户问题。普通任务默认只选择一个最合适的成员；只有用户明确要求多人分别回答，或确实存在并行的独立工作时，才把多个成员放在同一阶段。外层 steps 阶段按顺序执行，后一个阶段等待前一个阶段完成。只有真实存在的成员才能被选择。" }] },
+        { role: "system", content: [{ type: "text", text: dispatch_system_prompt }] },
         { role: "user", content: [{ type: "text", text: build_dispatch_prompt(input) }] },
       ];
       let protocol_error = "Group dispatch model did not call dispatch_group";
@@ -104,13 +154,16 @@ export class AiDispatchStrategy implements DispatchStrategy {
           messages,
           tools: [{
             name: "dispatch_group",
-            description: "提交当前 Group 的成员投递路径。只调用一次；不要输出普通文本。没有成员需要回复时使用空 steps 和 next=stop。",
+            description: "提交当前 Group 的有限阶段计划。已经完成时使用空 stages 和 next=stop；只有后续选择依赖实际结果时才使用 next=continue。",
             input_schema: z.toJSONSchema(dispatch_group_input_schema) as Record<string, ModelJsonValue>,
           }],
           tool_choice: { type: "tool", tool_name: "dispatch_group" },
-          max_output_tokens: 600,
+          max_output_tokens: 1_200,
           reasoning: { enabled: false },
-        }, input.abort_signal);
+        }, {
+          request_kind: "group_dispatch",
+          signal: input.abort_signal,
+        });
         const dispatch_call = result.tool_calls.length === 1 && result.tool_calls[0]?.tool_name === "dispatch_group"
           ? result.tool_calls[0]
           : undefined;
@@ -169,57 +222,78 @@ function append_dispatch_retry_messages(
   });
 }
 
-/** 为 AI 调度器构造稳定、有限长度的群聊上下文。 */
+/** 为 AI 调度器构造稳定、有限且不重复当前消息的群聊上下文。 */
 function build_dispatch_prompt(input: {
+  readonly group: DispatchGroupProfile;
   readonly trigger: DispatchTrigger;
-  readonly message: GroupMessage;
+  readonly current_message: GroupMessage;
+  readonly history: readonly GroupMessage[];
   readonly pending_messages: readonly GroupMessage[];
-  readonly messages: readonly GroupMessage[];
-  readonly members: readonly Agent[];
+  readonly members: readonly DispatchMemberProfile[];
 }): string {
-  const members = input.members.map((member) => `- ${member.id}`).join("\n");
-  const history = input.messages.slice(-20).map((message) => `${message.sender_type}:${message.sender_id}: ${message.text}`).join("\n");
+  const members = input.members.map((member) => [
+    `- ID: ${member.agent_id}`,
+    `  名称: ${member.name}`,
+    `  能力描述: ${member.description || "（未提供）"}`,
+  ].join("\n")).join("\n");
+  const history = input.history.slice(-20).map(format_group_message).join("\n");
+  const pending_messages = input.pending_messages.map((message) => (
+    `${message.id === input.current_message.id ? "[当前] " : ""}${format_group_message(message)}`
+  )).join("\n");
   return [
-    "成员：",
+    "Group:",
+    `- ID: ${input.group.group_id}`,
+    `- 名称: ${input.group.name}`,
+    `- 目标: ${input.group.instruction || "（未提供）"}`,
+    "成员:",
     members,
-    "最近群聊：",
+    "此前对话:",
     history || "（无）",
-    "本次新增消息：",
-    input.pending_messages.map((message) => `${message.sender_type}:${message.sender_id}: ${message.text}`).join("\n") || "（无）",
-    `调度触发来源：${input.trigger}`,
-    "当前消息：",
-    `${input.message.sender_type}:${input.message.sender_id}: ${input.message.text}`,
-    "请调用 dispatch_group，输入 steps 和 next。steps 是二维数组：外层阶段按顺序执行，同一阶段数组内的成员并行执行；没有成员需要回复时使用空 steps 和 next=stop。不要输出普通文本。",
+    "本批新增消息:",
+    pending_messages || "（无）",
+    `触发方式: ${input.trigger}`,
+    "请调用 dispatch_group，提交 reason、stages 和 next，不要输出普通文本。",
   ].join("\n");
 }
 
-/** 将 AI tool call 编译为内部执行图，并确保只引用真实成员。 */
-function normalize_dispatch_tool_input(value: unknown, members: readonly Agent[]): DispatchDecision {
+/** 将 GroupMessage 格式化为调度器可读、稳定的单行文本。 */
+function format_group_message(message: GroupMessage): string {
+  return `${message.sender_type}:${message.sender_id}: ${message.text}`;
+}
+
+/** 将 AI tool call 校验并编译为内部阶段计划。 */
+function normalize_dispatch_tool_input(
+  value: unknown,
+  members: readonly DispatchMemberProfile[],
+): DispatchDecision {
   const parsed = dispatch_group_input_schema.parse(value);
-  const valid_ids = new Set(members.map((member) => member.id));
-  const nodes = parsed.steps.map((member_ids, index) => {
-    const unique_member_ids = [...new Set(member_ids)];
-    if (unique_member_ids.length !== member_ids.length) {
-      throw new Error(`Group dispatch selected member more than once in step ${index}`);
-    }
-    for (const member_id of unique_member_ids) {
-      if (!valid_ids.has(member_id)) {
-        throw new Error(`Group dispatch selected unknown member: ${member_id}`);
+  const valid_ids = new Set(members.map((member) => member.agent_id));
+  const stages = parsed.stages.map((stage, stage_index) => {
+    const selected_member_ids = new Set<string>();
+    const assignments = stage.assignments.map((assignment) => {
+      if (!valid_ids.has(assignment.member_id)) {
+        throw new Error(`Group dispatch selected unknown member: ${assignment.member_id}`);
       }
-    }
+      if (selected_member_ids.has(assignment.member_id)) {
+        throw new Error(`Group dispatch selected member more than once in stage ${stage_index}`);
+      }
+      selected_member_ids.add(assignment.member_id);
+      return {
+        member_id: assignment.member_id,
+        instruction: assignment.instruction,
+      };
+    });
     return {
-      node_id: `step-${index}`,
-      member_ids: unique_member_ids,
-      response_mode: unique_member_ids.length > 1 ? "parallel" as const : "single" as const,
-      depends_on_node_ids: index === 0 ? [] : [`step-${index - 1}`],
-      instruction: "你已被 Group 调度选中，请直接针对当前消息给出回复，并且只代表自己发言。",
+      stage_id: `stage-${stage_index}`,
+      assignments,
     };
   });
-  if (nodes.length === 0 && parsed.next === "continue") {
-    throw new Error("Group dispatch cannot continue without any member step");
+  if (stages.length === 0 && parsed.next === "continue") {
+    throw new Error("Group dispatch cannot continue without any stage");
   }
   return {
-    nodes,
+    reason: parsed.reason,
+    stages,
     terminal: parsed.next === "stop",
   };
 }

package/src/types/group/Group.ts

@@ -1,7 +1,7 @@
 /** Group 的公开领域类型：Group 是持续存在的群聊主体。 */
 
 import type { Agent } from "@/agent/Agent.js";
-import type { AgentModel } from "@/agent/AgentModel.js";
+import type { ModelClient } from "@downcity/type";
 import type { DispatchStrategy } from "@/types/group/DispatchStrategy.js";
 import type { GroupSessions } from "@/types/group/GroupSession.js";
 
@@ -14,7 +14,7 @@ export interface GroupOptions {
   /** Group 的可选协作说明。 */
   readonly instruction?: string;
   /** Group 用于理解群聊意图并选择投递成员的模型。 */
-  readonly model?: AgentModel;
+  readonly model?: ModelClient;
   /** Group 成员列表。 */
   readonly members: readonly Agent[];
   /** Group 的消息调度策略；省略时使用 Group.model 驱动的 AI 调度。 */
@@ -39,8 +39,8 @@ export interface GroupMessage {
   readonly turn_id?: string;
   /** 可选的自动调度运行标识；自动调度产生的消息使用此标识。 */
   readonly dispatch_id?: string;
-  /** 可选的响应图节点标识。 */
-  readonly dispatch_node_id?: string;
+  /** 可选的调度计划阶段标识。 */
+  readonly dispatch_stage_id?: string;
   /** 创建时间的 Unix 毫秒时间戳。 */
   readonly created_at: number;
 }
@@ -53,8 +53,8 @@ export interface GroupContract {
   readonly name: string;
   /** Group 的协作说明。 */
   readonly instruction?: string;
-  /** Group 用于理解群聊意图并生成成员投递图的模型；未提供时首次调度会失败。 */
-  readonly model?: AgentModel;
+  /** Group 用于理解群聊意图并生成成员阶段计划的模型；未提供时首次调度会失败。 */
+  readonly model?: ModelClient;
   /** Group 成员快照。 */
   readonly members: readonly Agent[];
   /** Group 使用的消息调度策略。 */

package/src/types/group/{GroupDispatchSession.ts → GroupDispatch.ts}

@@ -1,19 +1,20 @@
 /**
- * Group Dispatch Session 领域类型。
+ * GroupSession 内部调度协议。
  *
- * Dispatch Session 只记录群聊调度 Turn，不复制 GroupMessage 正文；消息正文仍由
- * GroupSession 的消息日志作为唯一事实源，调度记录通过消息 ID 建立稳定引用。
+ * 调度不是独立 Session，只是 GroupSession 根据共享消息和成员画像计算下一步阶段计划的
+ * 内部运行过程。本模块描述该过程的输入、结果与持久化记录。
  */
 
-import type { Agent } from "@/agent/Agent.js";
 import type { GroupMessage } from "@/types/group/Group.js";
 import type {
+  DispatchGroupProfile,
+  DispatchMemberProfile,
   DispatchDecision,
   DispatchStrategy,
   DispatchTrigger,
 } from "@/types/group/DispatchStrategy.js";
 
-/** Dispatch Session 中一次调度 Turn 的持久化状态。 */
+/** GroupSession 中一次调度 Turn 的持久化状态。 */
 export type GroupDispatchTurnStatus =
   | "queued"
   | "running"
@@ -21,7 +22,7 @@ export type GroupDispatchTurnStatus =
   | "failed"
   | "stopped";
 
-/** Dispatch Session 中一次调度 Turn 的完整持久化快照。 */
+/** GroupSession 中一次调度 Turn 的完整持久化快照。 */
 export interface GroupDispatchTurnRecord {
   /** 当前调度 Turn 的稳定标识。 */
   readonly dispatch_id: string;
@@ -43,38 +44,32 @@ export interface GroupDispatchTurnRecord {
   readonly updated_at: number;
 }
 
-/** Dispatch Session 持久化所需的最小数据能力。 */
-export interface GroupDispatchSessionDataStore {
-  /** 读取每个 dispatch_id 的最新调度 Turn 快照。 */
-  list_turns(): Promise<GroupDispatchTurnRecord[]>;
-  /** 以追加日志方式提交一个调度 Turn 的最新完整快照。 */
-  append_turn(turn: GroupDispatchTurnRecord): Promise<void>;
-}
-
-/** Dispatch Session 成功完成一次调度后的运行结果。 */
-export interface GroupDispatchSessionResult {
+/** GroupSession 完成一次调度后的内部运行结果。 */
+export interface GroupDispatchResult {
   /** 当前调度 Turn 的稳定标识。 */
   readonly dispatch_id: string;
   /** 已经校验并持久化的成员投递决定。 */
   readonly decision: DispatchDecision;
 }
 
-/** 创建 Group Dispatch Session 的运行依赖。 */
-export interface GroupDispatchSessionOptions {
+/** 创建 Group 调度运行器的内部依赖。 */
+export interface GroupDispatchRuntimeOptions {
   /** 当前 GroupSession 使用的消息调度策略。 */
   readonly dispatch_strategy: DispatchStrategy;
 }
 
-/** 向 Group Dispatch Session 提交一次调度判断的输入快照。 */
-export interface GroupDispatchSessionInput {
+/** GroupSession 提交给调度策略的一次不可变输入快照。 */
+export interface GroupDispatchInput {
+  /** 当前 Group 的只读语义画像。 */
+  readonly group: DispatchGroupProfile;
   /** 本次调度由用户消息还是自动传播触发。 */
   readonly trigger: DispatchTrigger;
   /** 当前调度所围绕的 GroupMessage。 */
-  readonly message: GroupMessage;
+  readonly current_message: GroupMessage;
   /** 当前调度需要一起判断的新增 GroupMessage。 */
   readonly pending_messages: readonly GroupMessage[];
-  /** 当前 GroupSession 的完整共享消息快照。 */
-  readonly messages: readonly GroupMessage[];
-  /** 当前 Group 的成员快照。 */
-  readonly members: readonly Agent[];
+  /** 本批新增消息之前的最近 Group 对话。 */
+  readonly history: readonly GroupMessage[];
+  /** 当前 Group 成员的只读语义画像。 */
+  readonly members: readonly DispatchMemberProfile[];
 }