@downcity/agent 1.1.74 → 1.1.81

package/src/types/agent/RemoteAgentOptions.ts

@@ -0,0 +1,29 @@
+/**
+ * RemoteAgent 构造类型。
+ *
+ * 关键点（中文）
+ * - RemoteAgent 只关心远程访问地址与可选鉴权 token。
+ * - HTTP 鉴权与 RPC 本机直连语义在 transport 层实现。
+ */
+
+/**
+ * 远程 Agent 构造参数。
+ */
+export interface RemoteAgentOptions {
+  /**
+   * 远程 agent 访问地址。
+   *
+   * 例如：`https://city.example.com/agents/lucas`、`http://127.0.0.1:5314/agents/lucas`
+   * 或 `rpc://127.0.0.1:15314`
+   */
+  url: string;
+
+  /**
+   * 访问远程 HTTP Agent 时使用的 Bearer token。
+   *
+   * 关键点（中文）
+   * - 仅 `http://` / `https://` transport 会携带该 token。
+   * - `rpc://` 是本机内部直连通道，不读取也不发送 token。
+   */
+  token?: string;
+}

package/src/types/agent/SessionActor.ts

@@ -0,0 +1,88 @@
+/**
+ * Agent session actor 接口类型。
+ *
+ * 关键点（中文）
+ * - 这里只描述 session 的可调用能力。
+ * - session 的数据结构、history/system payload 放在 `SessionTypes.ts`。
+ */
+
+import type {
+  AgentCreateSessionInput,
+  AgentListSessionsInput,
+  AgentSessionConfigSnapshot,
+  AgentSessionForkInput,
+  AgentSessionHistoryInput,
+  AgentSessionHistoryPage,
+  AgentSessionInfo,
+  AgentSessionSetInput,
+  AgentSessionSummaryPage,
+  AgentSessionSystemSnapshot,
+} from "@/types/agent/SessionTypes.js";
+import type {
+  AgentSessionSubscriber,
+  AgentSessionUnsubscribe,
+} from "@/types/sdk/AgentSessionEvent.js";
+import type { AgentSessionPromptInput } from "@/types/sdk/AgentSessionPrompt.js";
+import type { AgentSessionTurnHandle } from "@/types/sdk/AgentSessionTurn.js";
+
+/**
+ * SDK Session 集合绑定。
+ */
+export interface AgentSessionCollection {
+  /** 新建一个 session。 */
+  createSession(input?: AgentCreateSessionInput): Promise<AgentSession>;
+
+  /** 获取一个已存在的 session。 */
+  getSession(sessionId: string): Promise<AgentSession>;
+
+  /** 列出当前 agent 的 session 摘要页。 */
+  listSessions(input?: AgentListSessionsInput): Promise<AgentSessionSummaryPage>;
+}
+
+/**
+ * Session actor 公共能力。
+ */
+export interface AgentSessionActor {
+  /** 当前 session 稳定标识。 */
+  readonly id: string;
+
+  /** 读取当前 session 详情。 */
+  getInfo(): Promise<AgentSessionInfo>;
+
+  /** 追加一条新的 prompt。 */
+  prompt(input: AgentSessionPromptInput): Promise<AgentSessionTurnHandle>;
+
+  /** 订阅当前 session 的未来事件。 */
+  subscribe(subscriber: AgentSessionSubscriber): AgentSessionUnsubscribe;
+
+  /** 读取当前 session 历史分页。 */
+  history(input?: AgentSessionHistoryInput): Promise<AgentSessionHistoryPage>;
+
+  /** 读取当前 session 生效的 system 快照。 */
+  system(): Promise<AgentSessionSystemSnapshot>;
+}
+
+/**
+ * 本地 Agent 返回的公开 session 接口。
+ */
+export interface AgentSession extends AgentSessionActor {
+  /** 当前 session 所属 agentId。 */
+  readonly agentId: string;
+
+  /** 当前 session 配置快照。 */
+  readonly config: AgentSessionConfigSnapshot;
+
+  /** 写入当前 session 默认配置。 */
+  set(input: AgentSessionSetInput): Promise<void>;
+
+  /** 从当前 session 创建一个分叉会话。 */
+  fork(input?: AgentSessionForkInput | string): Promise<AgentSession>;
+}
+
+/**
+ * 远程 Agent 返回的公开 session 接口。
+ */
+export interface RemoteAgentSession extends AgentSessionActor {
+  /** 从当前远程 session 创建一个分叉会话。 */
+  fork(input?: AgentSessionForkInput | string): Promise<RemoteAgentSession>;
+}

package/src/types/agent/SessionTypes.ts

@@ -0,0 +1,335 @@
+/**
+ * Agent session 数据类型。
+ *
+ * 关键点（中文）
+ * - 只描述 session 的输入、摘要、历史、system snapshot 与配置快照。
+ * - session actor 方法接口拆到 `SessionActor.ts`。
+ */
+
+import type { LanguageModel } from "ai";
+import type { AgentModel } from "@/model/CityModelAdapter.js";
+import type { SessionMessageV1 } from "@/executor/types/SessionMessages.js";
+
+/**
+ * 新建 session 的输入参数。
+ */
+export interface AgentCreateSessionInput {
+  /**
+   * 可选显式 sessionId。
+   *
+   * 关键点（中文）
+   * - 传入时表达“创建意图”。
+   * - 若该 session 已存在，SDK 应直接报错，而不是静默复用。
+   * - 省略时由 SDK 自动生成稳定且不可推导的 sessionId。
+   */
+  sessionId?: string;
+
+}
+
+/**
+ * Session 列表查询输入。
+ */
+export interface AgentListSessionsInput {
+  /**
+   * 当前页返回上限。
+   *
+   * 说明（中文）
+   * - 省略时由 SDK 使用默认值。
+   * - 建议宿主 UI 明确传入，避免在大量 session 下拉取过多数据。
+   */
+  limit?: number;
+
+  /**
+   * 分页游标。
+   *
+   * 说明（中文）
+   * - 当前使用 SDK 自身生成的透明字符串游标。
+   * - 调用方只负责透传，不应自行解析其内部格式。
+   */
+  cursor?: string;
+
+  /**
+   * 关键词过滤。
+   *
+   * 说明（中文）
+   * - 推荐用于匹配 `sessionId`、标题与预览文本。
+   * - 属于轻量包含匹配，不承诺复杂搜索语义。
+   */
+  query?: string;
+}
+
+/**
+ * Session 可变配置。
+ */
+export interface AgentSessionSetInput {
+  /**
+   * 当前 session 默认模型实例。
+   *
+   * 关键点（中文）
+   * - 这里接受运行中的模型实例，而不是模型 ID。
+   * - 由于模型实例通常不可序列化，落盘只保留轻量可读标签用于展示。
+   */
+  model?: AgentModel;
+}
+
+/**
+ * Session 当前配置快照。
+ */
+export interface AgentSessionConfigSnapshot {
+  /** 当前 session 绑定的默认模型实例。 */
+  model?: LanguageModel;
+  /** 当前模型的轻量可读标签。 */
+  modelLabel?: string;
+}
+
+/**
+ * Session 历史视图类型。
+ */
+export type AgentSessionHistoryView = "message" | "timeline";
+
+/**
+ * Session 时间线事件。
+ */
+export interface AgentSessionTimelineEvent {
+  /** 当前事件唯一标识。 */
+  id: string;
+  /**
+   * 当前事件角色。
+   *
+   * 说明（中文）
+   * - `tool-call` / `tool-result` 用于把 assistant 内部工具过程平铺给 UI。
+   */
+  role: "user" | "assistant" | "tool-call" | "tool-result";
+  /** 事件时间戳（毫秒）。 */
+  ts?: number;
+  /** 事件所属消息种类。 */
+  kind?: string;
+  /** 事件来源。 */
+  source?: string;
+  /** 当前事件展示文本。 */
+  text: string;
+  /**
+   * 当前事件对应工具名称。
+   *
+   * 说明（中文）
+   * - 仅 `tool-call` / `tool-result` 这类事件通常会携带该字段。
+   */
+  toolName?: string;
+}
+
+/**
+ * Session system block 来源类型。
+ */
+export type AgentSessionSystemBlockSource =
+  | "core"
+  | "instruction"
+  | "plugin"
+  | "session";
+
+/**
+ * Session system prompt 的单个组成块。
+ */
+export interface AgentSessionSystemBlock {
+  /** 当前 block 的来源层级。 */
+  source: AgentSessionSystemBlockSource;
+  /**
+   * 当前 block 在来源层级内的名称。
+   *
+   * 说明（中文）
+   * - `instruction` 通常使用 `agent`。
+   * - `plugin` 使用对应 plugin 名称。
+   * - `core` 使用 `default`。
+   * - `session` 使用当前 session 上下文名称。
+   */
+  name: string;
+  /**
+   * 已归一化后的 system 文本内容。
+   *
+   * 关键点（中文）
+   * - SDK 不对 instruction 做动态变量替换。
+   * - 动态上下文应由调用方放入 user message。
+   */
+  content: string;
+}
+
+/**
+ * 当前 session 的稳定上下文信息。
+ */
+export interface AgentSessionSystemSessionInfo {
+  /** 当前 session 所属 agentId。 */
+  agentId: string;
+  /** 当前 session 唯一标识。 */
+  sessionId: string;
+  /** 当前 agent 绑定的项目根目录。 */
+  projectRoot: string;
+  /**
+   * 当前 session 首次创建时间。
+   *
+   * 关键点（中文）
+   * - 这是 session 初始化时落盘的稳定参考时间，按 Date/ISO 字符串对外展示。
+   * - 它不是每轮运行的当前时间，不会随着后续 turn 执行而改变。
+   */
+  createdAt: string;
+  /**
+   * 当前 session 初始化时解析到的系统时区。
+   *
+   * 关键点（中文）
+   * - 这是 session 级参考时区，随创建信息一起固定。
+   * - 它不是每轮运行重新解析的动态时区。
+   */
+  timezone: string;
+}
+
+/**
+ * 当前 session 生效的完整 system prompt 快照。
+ */
+export interface AgentSessionSystemSnapshot {
+  /** 当前 sessionId。 */
+  sessionId: string;
+  /**
+   * 当前 session 的稳定上下文信息。
+   *
+   * 关键点（中文）
+   * - 这里包含 session 创建时间这类稳定参考信息。
+   * - 这里不包含当前时间、轮次、用户输入等每轮变化的数据。
+   * - 每轮动态信息应由调用方放入 user message，避免破坏 instruction 缓存命中。
+   */
+  session: AgentSessionSystemSessionInfo;
+  /** 当前生效的 system blocks，按进入模型的顺序排列。 */
+  blocks: AgentSessionSystemBlock[];
+}
+
+/**
+ * Session 摘要。
+ */
+export interface AgentSessionSummary {
+  /** 当前 session 所属 agentId。 */
+  agentId: string;
+  /** 当前 session 唯一标识。 */
+  sessionId: string;
+  /**
+   * 当前 session 可读标题。
+   *
+   * 说明（中文）
+   * - 标题持久化在 session `meta.json` 顶层。
+   * - 首条用户消息出现后，SDK 会优先生成标题，失败时回退到首条用户消息截断。
+   * - 空 session 可能暂时没有标题，调用方可回退到 `sessionId`。
+   */
+  title?: string;
+  /**
+   * 当前 session 的最近预览文本。
+   *
+   * 说明（中文）
+   * - 通常来自最后一条用户可见消息的裁剪文本。
+   * - 适合用于侧边栏、列表卡片或 session picker。
+   */
+  previewText?: string;
+  /** 当前 session 首次创建时间（ms）。 */
+  createdAt?: number;
+  /** 当前 session 最近一次更新时间（ms）。 */
+  updatedAt?: number;
+  /** 当前 session 已落盘消息数。 */
+  messageCount: number;
+  /** 当前 session 绑定模型的可读标签。 */
+  modelLabel?: string;
+  /** 当前 session 是否处于执行中。 */
+  executing?: boolean;
+}
+
+/**
+ * Session 详情。
+ */
+export interface AgentSessionInfo extends AgentSessionSummary {
+  /** 当前 session 初始化时记录的时区。 */
+  timezone?: string;
+}
+
+/**
+ * Session 摘要分页结果。
+ */
+export interface AgentSessionSummaryPage {
+  /** 当前页 session 摘要列表。 */
+  items: AgentSessionSummary[];
+  /**
+   * 当前页所对应的总条数。
+   *
+   * 说明（中文）
+   * - 这里表示过滤后的总数，不是仅当前页数量。
+   * - 对分页 UI、结果统计和空态判断更友好。
+   */
+  total: number;
+  /** 下一页游标。 */
+  nextCursor?: string;
+  /** 是否仍有更多结果。 */
+  hasMore: boolean;
+}
+
+/**
+ * Session 历史读取输入。
+ */
+export interface AgentSessionHistoryInput {
+  /** 当前页返回上限。 */
+  limit?: number;
+  /** 分页游标。 */
+  cursor?: string;
+  /**
+   * 返回顺序。
+   *
+   * 说明（中文）
+   * - `asc`：从旧到新
+   * - `desc`：从新到旧
+   */
+  order?: "asc" | "desc";
+  /**
+   * 返回视图类型。
+   *
+   * 说明（中文）
+   * - `message`：原始 session 消息
+   * - `timeline`：适合直接渲染 UI 的平铺事件
+   */
+  view?: AgentSessionHistoryView;
+}
+
+/**
+ * Session 历史分页结果。
+ */
+export interface AgentSessionHistoryPage {
+  /** 当前读取所对应的 session 信息。 */
+  session: AgentSessionInfo;
+  /** 当前页实际返回视图。 */
+  view: AgentSessionHistoryView;
+  /**
+   * 当前页数据列表。
+   *
+   * 说明（中文）
+   * - `view=message` 时返回 `SessionMessageV1[]`
+   * - `view=timeline` 时返回 `AgentSessionTimelineEvent[]`
+   */
+  items: SessionMessageV1[] | AgentSessionTimelineEvent[];
+  /**
+   * 过滤前后的总条数。
+   *
+   * 说明（中文）
+   * - 对 `view=message` 表示消息条数。
+   * - 对 `view=timeline` 表示时间线事件条数。
+   */
+  total: number;
+  /** 下一页游标。 */
+  nextCursor?: string;
+  /** 是否仍有更多数据。 */
+  hasMore: boolean;
+}
+
+/**
+ * Session fork 输入。
+ */
+export interface AgentSessionForkInput {
+  /**
+   * 可选分叉锚点消息 ID。
+   *
+   * 关键点（中文）
+   * - 省略时复制当前 session 的完整消息历史。
+   * - 传入时复制到该消息为止（包含该消息）。
+   */
+  messageId?: string;
+}

package/src/types/config/DowncityConfig.ts

@@ -8,7 +8,7 @@
 import type { LlmConfig } from "@/types/config/LlmConfig.js";
 import type { ExecutionBindingConfig } from "@/types/config/ExecutionBinding.js";
 import type { JsonObject } from "@/types/common/Json.js";
-import type { SandboxProjectConfig } from "@/runtime/sandbox/types/Sandbox.js";
+import type { SandboxProjectConfig } from "@/sandbox/types/Sandbox.js";
 
 /**
  * 单个聊天渠道配置。

package/src/types/executor/SessionRunContext.ts

@@ -0,0 +1,76 @@
+/**
+ * SessionRunContext：单次 session run 的显式运行上下文。
+ *
+ * 关键点（中文）
+ * - 这里承载本轮执行过程中需要在多个组件间透传的运行期数据。
+ * - 业务侧上下文优先通过该对象显式传递，避免分散读取隐式全局状态。
+ * - tool 深层回调等无法直接传参的场景，才通过 run scope 间接读取这个对象。
+ */
+
+import type {
+  SessionAssistantStepCallback,
+  SessionUiMessageChunkCallback,
+} from "@/executor/types/SessionRun.js";
+import type { SessionUserMessageV1 } from "@/executor/types/SessionMessages.js";
+import type { FileUIPart } from "ai";
+
+/**
+ * 单次 session run 的运行上下文。
+ */
+export interface SessionRunContext {
+  /**
+   * 当前执行所属的 session 标识。
+   */
+  sessionId: string;
+
+  /**
+   * step 边界合并回调。
+   *
+   * 关键点（中文）
+   * - 由 Session actor 在 turn 运行期间注入。
+   * - 用于把运行中追加的 user 消息并入下一 step。
+   */
+  onStepCallback?: () => Promise<SessionUserMessageV1[]>;
+
+  /**
+   * assistant step 完成回调。
+   *
+   * 关键点（中文）
+   * - 用于把中间 step 文本或 reasoning 事件回传给 Session 事件流。
+   */
+  onAssistantStepCallback?: SessionAssistantStepCallback;
+
+  /**
+   * UI stream chunk 回调。
+   *
+   * 关键点（中文）
+   * - 用于把底层模型 UI chunk 旁路输出到订阅流或 transport。
+   */
+  onUiMessageChunkCallback?: SessionUiMessageChunkCallback;
+
+  /**
+   * 本轮运行中待并入下一 step 的 user 消息。
+   *
+   * 关键点（中文）
+   * - 主要由 tool runtime 在当前 turn 内动态注入。
+   * - 这些消息只影响当前执行，不会自动持久化。
+   */
+  injectedUserMessages: SessionUserMessageV1[];
+
+  /**
+   * 本轮运行结束后待写入长期历史的 user 消息。
+   *
+   * 关键点（中文）
+   * - 为保证时间线顺序稳定，这些消息会在 assistant 结果落盘之后统一持久化。
+   */
+  deferredPersistedUserMessages: SessionUserMessageV1[];
+
+  /**
+   * 本轮运行结束前待并入最终 assistant 消息的 file parts。
+   *
+   * 关键点（中文）
+   * - 用于 tool/plugin 在执行期产生图片、文件等最终输出。
+   * - 这些 part 不依赖模型把 tool result 再复述一遍，直接落入 assistant UIMessage。
+   */
+  pendingAssistantFileParts: FileUIPart[];
+}

package/src/types/{runtime/host → platform}/Store.ts

@@ -1,5 +1,5 @@
 /**
- * 平台宿主存储类型定义。
+ * 平台存储类型定义。
  *
  * 关键点（中文）
  * - Town 只保存平台级 env、channel account 与安全配置。

package/src/types/plugin/ImagePlugin.ts

@@ -0,0 +1,103 @@
+/**
+ * ImagePlugin 类型定义。
+ *
+ * 关键点（中文）
+ * - 这里仅定义 agent 对图片能力的最低层协议，不绑定 city 或任意上游 provider。
+ * - 图片生成结果使用 AI SDK UIMessage，保证 session 落盘格式与现有消息系统一致。
+ * - 字段保持 JSON 可序列化，便于通过 plugin action 与 tool bridge 传递。
+ */
+
+import type { UIMessage } from "ai";
+import type { JsonObject, JsonValue } from "@/types/common/Json.js";
+
+/**
+ * 图片生成文本内容片段。
+ */
+export interface ImagePluginTextContent {
+  /** 内容类型，固定为文本。 */
+  type: "text";
+  /** 生图提示词或上下文文本。 */
+  text: string;
+}
+
+/**
+ * 图片生成参考图片内容片段。
+ */
+export interface ImagePluginFileContent {
+  /** 内容类型，固定为图片。 */
+  type: "image";
+  /** 远程图片 URL。 */
+  url?: string;
+  /** data URL 图片内容。 */
+  data_url?: string;
+  /** 图片 MIME 类型，例如 `image/png`。 */
+  media_type?: string;
+}
+
+/**
+ * 图片生成多模态内容片段。
+ */
+export type ImagePluginContent =
+  | ImagePluginTextContent
+  | ImagePluginFileContent;
+
+/**
+ * 图片生成上下文消息。
+ */
+export interface ImagePluginMessage {
+  /** 消息角色。 */
+  role: "system" | "user" | "assistant";
+  /** 该消息内的文本与图片内容。 */
+  content: ImagePluginContent[];
+}
+
+/**
+ * ImagePlugin 调用输入。
+ */
+export interface ImagePluginInput {
+  /** 图片模型引用。 */
+  model?: string;
+  /** 单句快捷提示词。 */
+  prompt?: string;
+  /** 多轮或多模态图片生成上下文。 */
+  messages?: ImagePluginMessage[];
+  /** 生成图片数量。 */
+  n?: number;
+  /** 生成图片数量，兼容部分上游使用的 count 命名。 */
+  count?: number;
+  /** 图片尺寸，例如 `1024x1024`。 */
+  size?: string;
+  /** 图片宽高比，例如 `1:1`。 */
+  aspect_ratio?: string;
+  /** 图片宽高比，兼容部分上游使用的 ratio 命名。 */
+  ratio?: string;
+  /** 图片质量，例如 `standard`、`hd`、`ultra`、`4k`。 */
+  quality?: string;
+  /** 随机种子。 */
+  seed?: number;
+  /** 业务侧任务 ID，用于异步图片任务幂等、追踪和恢复。 */
+  client_job_id?: string;
+  /** Provider 私有参数，例如 `{ openai: {...}, gemini: {...}, luchi: {...} }`。 */
+  provider_options?: JsonObject;
+  /** 允许外部 image 函数接收其他 JSON 可序列化参数。 */
+  [key: string]: JsonValue | ImagePluginMessage[] | undefined;
+}
+
+/**
+ * ImagePlugin 生成结果。
+ */
+export type ImagePluginResult = UIMessage;
+
+/**
+ * ImagePlugin 构造参数。
+ */
+export interface ImagePluginOptions {
+  /** Plugin 稳定名称，默认 `image`。 */
+  name?: string;
+  /** Plugin 展示标题，默认 `Image`。 */
+  title?: string;
+  /** Plugin 用途说明。 */
+  description?: string;
+  /** 图片生成函数，通常传入 `(input) => city.ai.image(input)`。 */
+  image: (input: ImagePluginInput) => Promise<ImagePluginResult> | ImagePluginResult;
+}