@downcity/agent 1.1.338 → 1.1.400

package/src/types/group/DispatchStrategy.ts

@@ -0,0 +1,165 @@
+/** Group 调度策略：为当前消息上下文生成一组有依赖关系的成员投递节点。 */
+
+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, ModelJsonValue } from "@downcity/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 的发言约束。 */
+  readonly instruction: string;
+}
+
+/** 一次调度生成的当前最佳响应图。 */
+export interface DispatchDecision {
+  /** 当前调度图中的投递节点。 */
+  readonly nodes: readonly DispatchNode[];
+  /** 当前图完成后是否允许唯一的 GroupSession auto dispatch 继续判断。 */
+  readonly terminal: boolean;
+}
+
+/** Group 调度策略协议。 */
+export interface DispatchStrategy {
+  /** 根据触发来源、当前消息、历史和成员关系生成当前最佳响应图。 */
+  decide_dispatch(input: {
+    /** 本次调度由用户消息触发，还是由 GroupSession 自动收口触发。 */
+    readonly trigger: DispatchTrigger;
+    /** 当前待调度的 Group 消息；auto dispatch 时为本批新增消息中的最后一条。 */
+    readonly message: GroupMessage;
+    /** 当前 auto dispatch 尚未消费的新增消息。 */
+    readonly pending_messages: readonly GroupMessage[];
+    /** 当前 Group 已存在的消息历史。 */
+    readonly messages: readonly GroupMessage[];
+    /** 当前 Group 成员快照。 */
+    readonly members: readonly Agent[];
+  }): Promise<DispatchDecision> | DispatchDecision;
+}
+
+/** AI 调度策略的构造参数。 */
+export interface AiDispatchStrategyOptions {
+  /** Group 用于理解群聊意图并生成调度图的模型。 */
+  readonly model?: AgentModel;
+}
+
+/** AI 调度工具的最小输入协议；外层阶段串行，阶段内成员并行。 */
+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 继续判断。 */
+  next: z.enum(["stop", "continue"]),
+});
+
+/** 使用 Group.model 理解群聊意图并通过内部 tool call 生成成员投递决定。 */
+export class AiDispatchStrategy implements DispatchStrategy {
+  private readonly model?: ModelClient;
+
+  constructor(options: AiDispatchStrategyOptions = {}) {
+    this.model = options.model;
+  }
+
+  async decide_dispatch(input: {
+    readonly trigger: DispatchTrigger;
+    readonly message: GroupMessage;
+    readonly pending_messages: readonly GroupMessage[];
+    readonly messages: readonly GroupMessage[];
+    readonly members: readonly Agent[];
+  }): Promise<DispatchDecision> {
+    if (!this.model) {
+      throw new Error("Group requires a configured model for dispatch");
+    }
+    try {
+      const result = await generate_model(this.model, {
+        messages: [
+          { role: "system", content: [{ type: "text", text: "你是群聊消息调度器。你只能调用 dispatch_group，不回答用户问题。普通任务默认只选择一个最合适的成员；只有用户明确要求多人分别回答，或确实存在并行的独立工作时，才把多个成员放在同一阶段。外层 steps 阶段按顺序执行，后一个阶段等待前一个阶段完成。只有真实存在的成员才能被选择。" }] },
+          { role: "user", content: [{ type: "text", text: build_dispatch_prompt(input) }] },
+        ],
+        tools: [{
+          name: "dispatch_group",
+          description: "提交当前 Group 的成员投递路径。只调用一次；不要输出普通文本。没有成员需要回复时使用空 steps 和 next=stop。",
+          input_schema: z.toJSONSchema(dispatch_group_input_schema) as Record<string, ModelJsonValue>,
+        }],
+        tool_choice: { type: "tool", tool_name: "dispatch_group" },
+        max_output_tokens: 600,
+        reasoning: { enabled: false },
+      });
+      if (result.tool_calls.length !== 1 || result.tool_calls[0]?.tool_name !== "dispatch_group") {
+        throw new Error("Group dispatch model did not call dispatch_group");
+      }
+      return normalize_dispatch_tool_input(result.tool_calls[0].input, input.members);
+    } catch (error) {
+      const detail = error instanceof Error ? error.message : String(error);
+      throw new Error(`Group dispatch model failed: ${detail}`, { cause: error });
+    }
+  }
+}
+
+/** 为 AI 调度器构造稳定、有限长度的群聊上下文。 */
+function build_dispatch_prompt(input: {
+  readonly trigger: DispatchTrigger;
+  readonly message: GroupMessage;
+  readonly pending_messages: readonly GroupMessage[];
+  readonly messages: readonly GroupMessage[];
+  readonly members: readonly Agent[];
+}): 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");
+  return [
+    "成员：",
+    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。不要输出普通文本。",
+  ].join("\n");
+}
+
+/** 将 AI tool call 编译为内部执行图，并确保只引用真实成员。 */
+function normalize_dispatch_tool_input(value: unknown, members: readonly Agent[]): 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}`);
+      }
+    }
+    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 上下文判断是否需要回复，只代表自己发言；不需要时返回空内容。",
+    };
+  });
+  if (nodes.length === 0 && parsed.next === "continue") {
+    throw new Error("Group dispatch cannot continue without any member step");
+  }
+  return {
+    nodes,
+    terminal: parsed.next === "stop",
+  };
+}

package/src/types/group/Group.ts

@@ -0,0 +1,64 @@
+/** Group 的公开领域类型：Group 是持续存在的群聊主体。 */
+
+import type { Agent } from "@/agent/Agent.js";
+import type { AgentModel } from "@/agent/AgentModel.js";
+import type { DispatchStrategy } from "@/types/group/DispatchStrategy.js";
+import type { GroupSessions } from "@/types/group/GroupSession.js";
+
+/** 创建 Group 的参数。 */
+export interface GroupOptions {
+  /** Group 的稳定标识。 */
+  readonly id: string;
+  /** Group 的展示名称；省略时使用 id。 */
+  readonly name?: string;
+  /** Group 的可选协作说明。 */
+  readonly instruction?: string;
+  /** Group 用于理解群聊意图并选择投递成员的模型。 */
+  readonly model?: AgentModel;
+  /** Group 成员列表。 */
+  readonly members: readonly Agent[];
+  /** Group 的消息调度策略；省略时使用 Group.model 驱动的 AI 调度。 */
+  readonly dispatch_strategy?: DispatchStrategy;
+}
+
+/** Group 中的一条共享消息。 */
+export interface GroupMessage {
+  /** 消息稳定标识。 */
+  readonly id: string;
+  /** 所属 Group 标识。 */
+  readonly group_id: string;
+  /** 消息发送者标识；用户消息使用 user，系统消息使用 system。 */
+  readonly sender_id: string;
+  /** 消息发送者类型。 */
+  readonly sender_type: "user" | "agent" | "system";
+  /** 消息正文。 */
+  readonly text: string;
+  /** 可选的被回复消息标识。 */
+  readonly reply_to?: string;
+  /** 可选的用户 GroupTurn 标识；同一用户请求产生的消息共享此标识。 */
+  readonly turn_id?: string;
+  /** 可选的自动调度运行标识；自动调度产生的消息使用此标识。 */
+  readonly dispatch_id?: string;
+  /** 可选的响应图节点标识。 */
+  readonly dispatch_node_id?: string;
+  /** 创建时间的 Unix 毫秒时间戳。 */
+  readonly created_at: number;
+}
+
+/** Group 公开能力。 */
+export interface GroupContract {
+  /** Group 的稳定标识。 */
+  readonly id: string;
+  /** Group 的展示名称。 */
+  readonly name: string;
+  /** Group 的协作说明。 */
+  readonly instruction?: string;
+  /** Group 用于理解群聊意图并生成成员投递图的模型；未提供时首次调度会失败。 */
+  readonly model?: AgentModel;
+  /** Group 成员快照。 */
+  readonly members: readonly Agent[];
+  /** Group 使用的消息调度策略。 */
+  readonly dispatch_strategy: DispatchStrategy;
+  /** 当前 Group 创建的独立群聊上下文集合。 */
+  readonly sessions: GroupSessions;
+}

package/src/types/group/GroupSession.ts

@@ -0,0 +1,154 @@
+/** GroupSession 的公开领域类型：一次 Group 的独立群聊上下文。 */
+
+import type { AgentSession } from "@/types/agent/SessionActor.js";
+import type { GroupMessage } from "@/types/group/Group.js";
+import type { Agent } from "@/agent/Agent.js";
+import type { WorkspaceBase } from "@downcity/workspace";
+import type { RespondSessionInteractionInput, SessionInteractionRequest } from "@/types/session/SessionInteraction.js";
+
+/** Group 成员运行态。 */
+export interface GroupMemberRuntime {
+  /** 成员 Agent 标识。 */
+  readonly agent_id: string;
+  /** 当前是否正在执行。 */
+  readonly running: boolean;
+}
+
+/** Group 运行阶段。 */
+export type GroupStatusPhase = "idle" | "dispatching" | "dispatched" | "executing" | "stopped" | "failed";
+
+/** GroupSession 的统一实时事件。 */
+export type GroupEvent =
+  | { /** 事件类型。 */ readonly type: "message"; /** 新增的共享消息。 */ readonly message: GroupMessage }
+  | { /** 事件类型。 */ readonly type: "interaction"; /** 发起交互的成员 Agent。 */ readonly agent_id: string; /** 成员 Session 的交互请求。 */ readonly request: SessionInteractionRequest }
+  | { /** 事件类型。 */ readonly type: "status"; /** 当前群聊轮次。 */ readonly turn_id?: string; /** 当前轮次对应的消息标识。 */ readonly message_id?: string; /** 当前运行阶段。 */ readonly phase: GroupStatusPhase; /** Dispatch 完成后实际接受消息的成员标识。 */ readonly dispatched_member_ids?: readonly string[]; /** 成员运行态快照。 */ readonly members: readonly GroupMemberRuntime[] };
+
+/** Group 事件订阅回调。 */
+export type GroupEventSubscriber = (event: GroupEvent) => void | Promise<void>;
+
+/** 取消 Group 消息订阅。 */
+export type GroupEventUnsubscribe = () => void;
+
+/** GroupSession 接收一条用户消息后的异步调度回执。 */
+export interface GroupPromptResult {
+  /** 当前用户消息对应的 GroupTurn 标识。 */
+  readonly turn_id: string;
+  /** 用户消息是否已经成功写入并开始调度；不代表成员已经完成回复。 */
+  readonly success: boolean;
+  /** 回执生成时共享消息总数。 */
+  readonly message_count: number;
+}
+
+/** 向 GroupSession 发言的输入。 */
+export interface GroupPromptInput {
+  /** 用户消息正文。 */
+  readonly query: string;
+}
+
+/** GroupSession 列表使用的轻量摘要，不加载消息历史。 */
+export interface GroupSessionSummary {
+  /** GroupSession 稳定标识。 */
+  readonly id: string;
+  /** 所属 Group 稳定标识。 */
+  readonly group_id: string;
+  /** 首次创建时间戳。 */
+  readonly created_at: number;
+  /** 最近更新时间戳。 */
+  readonly updated_at: number;
+  /** 已持久化消息数量。 */
+  readonly message_count: number;
+  /** 当前 GroupSession 绑定的 Workspace 标识。 */
+  readonly workspace_id?: string;
+  /** 最后一条消息的用户可见预览。 */
+  readonly preview_text?: string;
+}
+
+/** GroupSession 的创建输入；第一阶段不允许调用方指定 session_id。 */
+export interface GroupSessionCreateInput {
+  /** 当前群聊使用的 Workspace；省略时使用内存执行上下文。 */
+  readonly workspace?: WorkspaceBase;
+}
+
+/** 恢复 GroupSession 时的上下文输入。 */
+export interface GroupSessionGetInput {
+  /** 当前群聊使用的 Workspace；必须与持久化 metadata 一致。 */
+  readonly workspace?: WorkspaceBase;
+}
+
+/** GroupSession 列表过滤条件。 */
+export interface GroupSessionListInput {
+  /** 只返回绑定到指定 Workspace 的群聊上下文。 */
+  readonly workspace_id?: string;
+}
+
+/** GroupSession 公开能力。 */
+export interface GroupSessionContract {
+  /** 当前群聊上下文的稳定标识。 */
+  readonly id: string;
+  /** 所属 Group 的稳定标识。 */
+  readonly group_id: string;
+  /** 当前 GroupSession 绑定的 Workspace ID；未绑定时为空。 */
+  readonly workspace_id?: string;
+  /** 立即追加用户消息并开始异步群聊调度。 */
+  prompt(input: GroupPromptInput): Promise<GroupPromptResult>;
+  /** 读取共享消息事实快照。 */
+  messages(): Promise<readonly GroupMessage[]>;
+  /** 订阅共享消息。 */
+  subscribe(subscriber: GroupEventSubscriber): GroupEventUnsubscribe;
+  /** 响应成员 Agent Session 当前等待的 Interaction。 */
+  respond_interaction(input: RespondSessionInteractionInput): Promise<void>;
+  /** 停止当前传播和成员执行；停止完成后可再次 prompt。 */
+  stop(): Promise<void>;
+  /** 释放当前上下文，不再接受新的 prompt。 */
+  dispose(): Promise<void>;
+}
+
+/** GroupSession 的公开实例类型。 */
+export interface GroupSession extends GroupSessionContract {}
+
+/** GroupSession 集合公开能力。 */
+export interface GroupSessions {
+  /** 创建一个新的群聊上下文，标识由集合内部生成。 */
+  create(input?: GroupSessionCreateInput): Promise<GroupSession>;
+  /** 从 Storage 恢复当前 Group 的一个群聊上下文。 */
+  get(session_id: string, input?: GroupSessionGetInput): Promise<GroupSession | null>;
+  /** 从 Storage 恢复当前 Group 的全部群聊上下文。 */
+  list(input?: GroupSessionListInput): Promise<readonly GroupSessionSummary[]>;
+  /** 释放并移除指定群聊上下文。 */
+  remove(session_id: string, input?: GroupSessionGetInput): Promise<GroupSession | null>;
+}
+
+/** GroupSession 的内部依赖快照。 */
+export interface GroupSessionRuntimeContext {
+  /** 当前 Group 的成员。 */
+  readonly members: readonly Agent[];
+  /** 当前 Group 的协作说明。 */
+  readonly instruction?: string;
+  /** 当前 Group 的消息调度策略。 */
+  readonly dispatch_strategy: import("@/types/group/DispatchStrategy.js").DispatchStrategy;
+  /** 当前 Group 的稳定标识。 */
+  readonly group_id: string;
+  /** 当前 Group 的展示名称。 */
+  readonly group_name: string;
+}
+
+/** 当前群聊上下文中由 Agent 持有的成员 Session。 */
+export type GroupMemberSession = AgentSession;
+
+/** GroupSession 内部维护的一次用户请求运行记录。 */
+export interface GroupTurnRuntime {
+  /** 用户请求对应的 GroupTurn 标识。 */
+  readonly turn_id: string;
+  /** 用户根消息标识。 */
+  readonly root_message_id: string;
+  /** 用户消息写入时冻结的上下文消息标识。 */
+  readonly context_message_ids: readonly string[];
+  /** 当前 GroupTurn 的异步 user dispatch。 */
+  user_dispatch?: Promise<void>;
+  /** 当前 GroupTurn 是否等待 GroupSession 的 auto dispatch。 */
+  auto_pending: boolean;
+  /** 当前 GroupTurn 是否已经停止或失败。 */
+  stopped: boolean;
+  /** 当前 GroupTurn 是否由持久化检查点恢复，只等待统一 auto dispatch 收口。 */
+  readonly recovered?: boolean;
+}

package/src/types/group/GroupSessionStore.ts

@@ -0,0 +1,82 @@
+/** GroupSession 持久化协议：只描述 GroupSession 所需的底层数据能力。 */
+
+import type { GroupMessage } from "@/types/group/Group.js";
+import type { FileSystem } from "@downcity/workspace";
+
+/** GroupSession 的持久化元数据。 */
+export interface GroupSessionHistoryMeta {
+  /** metadata schema 版本。 */
+  readonly v: 1;
+  /** 当前 GroupSession 标识。 */
+  readonly session_id: string;
+  /** 所属 Group 标识。 */
+  readonly group_id: string;
+  /** 当前 GroupSession 绑定的 Workspace 标识；未绑定时为空。 */
+  readonly workspace_id?: string;
+  /** 首次创建时间戳。 */
+  readonly created_at: number;
+  /** 最近更新时间戳。 */
+  readonly updated_at: number;
+  /** 已持久化消息数量。 */
+  readonly message_count: number;
+  /** 最后一条消息的用户可见预览。 */
+  readonly preview_text?: string;
+  /** GroupSession 为每个成员 Agent 复用的 AgentSession 标识。 */
+  readonly member_session_ids?: Readonly<Record<string, string>>;
+  /** 尚未完成收口的 GroupTurn 检查点；进程重启后仅据此恢复 auto dispatch。 */
+  readonly pending_turns?: readonly GroupSessionTurnCheckpoint[];
+  /** 进程中断前尚未消费的 auto dispatch frontier 消息标识。 */
+  readonly auto_frontier_message_ids?: readonly string[];
+}
+
+/** GroupSession 可恢复的最小运行检查点。 */
+export interface GroupSessionTurnCheckpoint {
+  /** 用户请求对应的 GroupTurn 标识。 */
+  readonly turn_id: string;
+  /** 用户根消息标识。 */
+  readonly root_message_id: string;
+  /** 用户消息写入时冻结的上下文消息标识。 */
+  readonly context_message_ids: readonly string[];
+}
+
+/** 单个 GroupSession 的持久化数据视图。 */
+export interface GroupSessionDataStore {
+  /** 当前 GroupSession 标识。 */
+  readonly session_id: string;
+  /** 初始化当前 GroupSession 的存储布局。 */
+  initialize(): Promise<void>;
+  /** 读取完整共享消息历史。 */
+  list_messages(): Promise<GroupMessage[]>;
+  /** 追加一条消息并同步更新 metadata。 */
+  append_message(message: GroupMessage): Promise<void>;
+  /** 读取当前 GroupSession metadata。 */
+  read_metadata(): Promise<GroupSessionHistoryMeta>;
+  /** 写入当前 GroupSession metadata。 */
+  write_metadata(metadata: GroupSessionHistoryMeta): Promise<void>;
+  /** 在文件锁内合并更新当前 GroupSession metadata。 */
+  update_metadata(patch: Partial<GroupSessionHistoryMeta>): Promise<GroupSessionHistoryMeta>;
+}
+
+/** Group 所拥有的全部 GroupSession 持久化入口。 */
+export interface GroupSessionStore {
+  /** 返回指定 GroupSession 的持久化视图。 */
+  session(session_id: string): GroupSessionDataStore;
+  /** 判断指定 GroupSession 是否存在。 */
+  has_session(session_id: string): Promise<boolean>;
+  /** 列出当前 Group 的持久化 Session metadata。 */
+  list_session_metadata(): Promise<GroupSessionHistoryMeta[]>;
+  /** 删除指定 GroupSession 的全部数据。 */
+  remove_session(session_id: string): Promise<boolean>;
+  /** 释放当前 Store 持有的资源。 */
+  dispose(): Promise<void>;
+}
+
+/** 创建基于 City StorageScope 的 GroupSession Store。 */
+export interface GroupSessionStoreOptions {
+  /** City StorageScope 提供的受控文件能力。 */
+  readonly files: FileSystem;
+  /** 当前 Group 的存储作用域根目录。 */
+  readonly storage_root_path: string;
+  /** 当前 Group 稳定标识。 */
+  readonly group_id: string;
+}

package/src/types/plugin/AgentPluginContext.ts

@@ -0,0 +1,30 @@
+/**
+ * AgentPluginContext：Plugin 在 Agent 级生命周期中可访问的最小能力。
+ *
+ * 边界说明（中文）
+ * - 该上下文不包含 Workspace，避免 Agent 级资源意外绑定第一个项目。
+ * - 该上下文不暴露完整 City，只暴露宿主明确注入的 Embassy 能力。
+ * - Plugin 是否需要 Agent 级生命周期，由 Plugin 自己是否实现 start/stop 决定。
+ */
+
+import type { Logger } from "@/utils/logger/Logger.js";
+import type { PluginWebServices } from "@/types/plugin/PluginServices.js";
+import type { Embassy } from "@downcity/federation";
+
+/** Plugin 的 Agent 级生命周期上下文。 */
+export interface AgentPluginContext {
+  /** 当前 Agent 的稳定标识。 */
+  readonly agent_id: string;
+
+  /** 当前 Agent 的全局日志器，不绑定任何 Workspace 文件系统。 */
+  readonly logger: Logger;
+
+  /** 当前 Agent 持有的 Web 搜索与文档能力。 */
+  readonly web?: PluginWebServices;
+
+  /** City 注入的 Embassy 能力；Agent 未加入 City 时为空。 */
+  readonly embassy?: Embassy;
+
+  /** 动态读取当前 Agent 静态指令的只读快照。 */
+  readonly instructions: readonly string[];
+}

package/src/types/plugin/PluginAction.ts

@@ -10,7 +10,7 @@ import type { Command } from "commander";
 import type { Context as HonoContext } from "hono";
 import type { z } from "zod";
 import type { PluginContext } from "@/types/plugin/PluginContext.js";
-import type { PluginExecutionContext } from "@/types/plugin/PluginExecutionContext.js";
+import type { PluginActionExecutionContext } from "@/types/plugin/PluginActionExecution.js";
 import type { JsonObject, JsonValue } from "@/types/common/Json.js";
 import type { ActionResultMessage } from "@/types/action/ActionResult.js";
 
@@ -134,6 +134,8 @@ export interface PluginActionMetadata<P extends JsonValue = JsonValue> {
   input_schema?: PluginActionInputSchema<P>;
   /** Action 调用示例。 */
   examples?: PluginActionExample<P>[];
+  /** Action 的协作式超时上限（毫秒）；Action 必须监听 execution.abort_signal。 */
+  timeout_ms?: number;
 }
 
 /**
@@ -149,16 +151,16 @@ export interface PluginAction<
   api?: PluginActionApi<P>;
   /** Action 执行器。 */
   execute: (params: {
-    /** 当前执行上下文。 */
+    /** WorkspaceEntry 创建的稳定 Plugin 能力视图。 */
     context: PluginContext;
     /**
      * 当前 action 所属 Session Turn 的只读 Plugin 执行快照。
      *
      * 关键点（中文）
-     * - 模型 tool 调用时必定提供。
-     * - CLI、HTTP 或定时任务等非 Session 入口可能不提供。
+     * - 模型 tool 调用复用对应 tool call ID 和 Turn 取消信号。
+     * - CLI、HTTP 与定时任务等非 Session 入口由 Registry 补齐调用身份和取消信号。
      */
-    execution_context?: PluginExecutionContext;
+    execution: PluginActionExecutionContext;
     /** 已通过 schema 校验后的输入。 */
     input: P;
     /** 当前插件名称。 */

package/src/types/plugin/PluginActionExecution.ts

@@ -0,0 +1,36 @@
+/**
+ * Plugin Action 单次执行上下文。
+ *
+ * 关键点（中文）
+ * - 每次 Action 调用都获得独立、只读的身份与取消快照。
+ * - Agent 与 Workspace 的稳定身份只保留在 PluginContext，不复制到单次执行对象。
+ * - Session 字段来自可选的 PluginExecutionContext；HTTP、CLI 与 Schedule 调用可以没有 Session。
+ */
+
+import type { PluginExecutionContext } from "@/types/plugin/PluginExecutionContext.js";
+import type { SessionInteractionPort } from "@/types/session/SessionInteraction.js";
+
+/** 当前 Action 所属 Session 的执行范围。 */
+export interface PluginSessionExecutionScope {
+  /** 当前 Session 标识。 */
+  readonly session_id: string;
+  /** 当前 Turn 标识。 */
+  readonly turn_id: string;
+  /** 当前 Session 的用户交互端口；当前入口未开放交互能力时为空。 */
+  readonly interactions?: SessionInteractionPort;
+}
+
+/** Plugin Action 执行器传给业务 Action 的完整只读上下文。 */
+export interface PluginActionExecutionContext {
+  /** 当前 Action 调用的稳定标识；模型 Tool 调用时等于对应 tool call ID。 */
+  readonly call_id: string;
+
+  /** 当前 Action 必须监听的取消信号；可同时承载 Turn 取消和 Action 超时。 */
+  readonly abort_signal: AbortSignal;
+
+  /** 当前调用所属的 Session；非 Session 入口时为空。 */
+  readonly session?: PluginSessionExecutionScope;
+
+  /** 当前调用开始时捕获的只读 Step 快照。 */
+  readonly snapshot: PluginExecutionContext;
+}

package/src/types/plugin/PluginCommand.ts

@@ -4,12 +4,12 @@
  * 关键点（中文）：生命周期只负责启动和停止；所有显式能力调用统一使用 Action。
  */
 
-import type { PluginContext } from "@/types/plugin/PluginContext.js";
+import type { AgentPluginContext } from "@/types/plugin/AgentPluginContext.js";
 
 /** Plugin 生命周期定义。 */
 export interface PluginLifecycle {
-  /** Plugin 启动钩子。 */
-  start?(context: PluginContext): Promise<void> | void;
-  /** Plugin 停止钩子。 */
-  stop?(context: PluginContext): Promise<void> | void;
+  /** Plugin 随 Agent 启动的钩子；不得假设存在 Workspace。 */
+  start?(context: AgentPluginContext): Promise<void> | void;
+  /** Plugin 随 Agent 停止的钩子。 */
+  stop?(context: AgentPluginContext): Promise<void> | void;
 }

package/src/types/plugin/PluginContext.ts

@@ -2,35 +2,51 @@
  * PluginContext：Agent 向 Plugin 投影的稳定能力视图。
  *
  * 边界说明（中文）
- * - Plugin 只依赖本接口，不持有 Agent 实例，也不参与 Session 内核编排。
+ * - Plugin 只依赖本接口，不持有 Agent、City 实例，也不参与 Session 内核编排。
  * - 动态状态通过只读 getter 暴露，保证 Workspace env 与 instruction 始终来自唯一状态源。
  */
 
-import type { AgentSessions } from "@/agent/AgentSessions.js";
+import type { AgentSessionCollection } from "@/types/agent/AgentSessionCollection.js";
 import type { AgentPlugins } from "@/types/plugin/PluginRuntime.js";
-import type { FileSystem } from "@/types/workspace/FileSystem.js";
+import type { FileSystem, WorkspaceShell } from "@downcity/workspace";
 import type { Logger } from "@/utils/logger/Logger.js";
-import type { Shell } from "@downcity/shell";
+import type { PluginWebServices } from "@/types/plugin/PluginServices.js";
+import type { Embassy } from "@downcity/federation";
 
 /** Agent 向 Plugin 开放的最小、稳定运行时能力。 */
 export interface PluginContext {
   /** 当前 Agent 的稳定标识。 */
   readonly agent_id: string;
 
+  /** 当前 Workspace 的稳定标识。 */
+  readonly workspace_id: string;
+
   /** 当前 Workspace 的绝对根目录。 */
   readonly workspace_path: string;
 
+  /** 当前 Plugin 在 Agent 内的运行时私有数据根路径。 */
+  readonly data_path: string;
+
   /** 当前 Workspace 的统一文件能力。 */
   readonly files: FileSystem;
 
+  /** 当前 Plugin 运行时私有数据目录的统一文件能力。 */
+  readonly data_files: FileSystem;
+
   /** 当前 Workspace 显式挂载的 Shell；未启用时为空。 */
-  readonly shell?: Shell;
+  readonly shell?: WorkspaceShell;
 
-  /** 当前 Agent 独享的统一日志器。 */
+  /** 当前 Agent 在当前 Workspace 执行上下文中使用的统一日志器。 */
   readonly logger: Logger;
 
+  /** 当前 Agent 持有的 Web 搜索与文档能力。 */
+  readonly web?: PluginWebServices;
+
+  /** City 注入的 Embassy 能力；Agent 未加入 City 时为空。 */
+  readonly embassy?: Embassy;
+
   /** 当前 Agent 的 Session 集合入口。 */
-  readonly sessions: AgentSessions;
+  readonly sessions: AgentSessionCollection;
 
   /** 当前 Agent 唯一的 Plugin 调用与注册入口。 */
   readonly plugins: AgentPlugins;