@downcity/agent 1.1.25 → 1.1.35

package/src/sdk/AgentSdkTypes.ts

@@ -3,17 +3,27 @@
  *
  * 关键点（中文）
  * - 这里集中声明 `Agent` / `RemoteAgent` / `Session` 面向外部调用方的稳定接口。
- * - SDK 用户通过显式 `tools` / `services` / `plugins` 装配能力，不直接依赖内部 runtime 单例。
+ * - SDK 用户通过显式 `tools` / `plugins` 装配能力，不直接依赖内部 runtime 单例。
  * - 本地/远程 session 运行与基础落盘能力仍是 SDK 主路径。
  */
 
 import type { LanguageModel, Tool } from "ai";
-import type { BaseService } from "@/service/builtins/BaseService.js";
-import type { Plugin } from "@/plugin/types/Plugin.js";
+import type { BasePlugin } from "@/plugin/core/BasePlugin.js";
 import type { AgentPlatformRuntime } from "@/types/runtime/host/AgentHost.js";
 import type { LocalRpcServerHandle } from "@/types/runtime/rpc/LocalRpc.js";
 import type { ServerInstance } from "@/runtime/server/http/Server.js";
-import type { Session } from "@/sdk/Session.js";
+import type { SessionMessageV1 } from "@/executor/types/SessionMessages.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 Agent 插件装配模式。
+ */
+export type AgentMode = "preset" | "custom";
 
 /**
  * 本地 Agent 构造参数。
@@ -63,42 +73,24 @@ export interface AgentOptions {
   model?: LanguageModel;
 
   /**
-   * 当前 agent 显式持有的 service 实例集合。
+   * 当前 agent 的插件装配模式。
    *
    * 关键点（中文）
-   * - 这里接收已经实例化好的 service，而不是 service class。
-   * - `Agent` 会在构造阶段按名称注册这些实例，并在启动时自动绑定 runtime。
-   * - v1 推荐显式传入 `new ChatService(...)` 这类实例，而不是依赖包内隐式注册表。
+   * - `preset` 会自动装配内建插件集合。
+   * - `custom` 只使用显式传入的 `plugins`。
+   * - 默认值为 `custom`，避免本地嵌入场景隐式打开额外能力。
    */
-  services?: BaseService[];
+  mode?: AgentMode;
 
   /**
-   * 是否自动装配全部内建 service。
+   * 当前 agent 显式持有的插件实例集合。
    *
    * 关键点（中文）
-   * - 适合 city 这类宿主进程直接 `new Agent(...)` 的场景。
-   * - 未开启时，默认只使用显式传入的 `services`。
-   */
-  useBuiltinServices?: boolean;
-
-  /**
-   * 当前 agent 显式注册的 plugin 定义集合。
-   *
-   * 关键点（中文）
-   * - 这里接收完整 plugin 定义对象，而不是 plugin 名称。
-   * - `Agent` 会为当前 SDK 实例创建独立 plugin registry，避免污染全局 runtime。
+   * - 这里接收已经实例化好的 `BasePlugin` 对象，而不是 plugin class。
+   * - `Agent` 会在构造阶段按名称注册这些实例，并自动绑定到当前 runtime。
    * - 同名 plugin 会直接报错，避免 action / hook / resolve 行为被静默覆盖。
    */
-  plugins?: Plugin[];
-
-  /**
-   * 是否自动装配全部内建 plugin。
-   *
-   * 关键点（中文）
-   * - 适合 city 这类宿主进程直接 `new Agent(...)` 的场景。
-   * - 未开启时，默认只使用显式传入的 `plugins`。
-   */
-  useBuiltinPlugins?: boolean;
+  plugins?: BasePlugin[];
 
   /**
    * 当前 agent 显式注入的平台能力集合。
@@ -116,9 +108,9 @@ export interface AgentOptions {
    * - SDK 不负责默认模型策略，宿主可在这里统一为 session 注入 model 等运行配置。
    * - 若同时传入 `model`，则会先写入默认模型，再执行这里的宿主覆写逻辑。
    * - 该钩子对每个 session 只触发一次，适合做实例级默认装配。
-   * - 触发时机可能来自显式 `agent.session()`，也可能来自该 session 的首次执行入口。
+   * - 触发时机可能来自显式 `agent.createSession()` / `agent.getSession()`，也可能来自该 session 的首次执行入口。
    */
-  configureSession?: (session: Session) => Promise<void> | void;
+  configureSession?: (session: AgentSession) => Promise<void> | void;
 }
 
 /**
@@ -145,13 +137,13 @@ export interface AgentStartOptions {
   rpc?: boolean;
 
   /**
-   * 是否启动当前 agent 的 services。
+   * 是否启动当前 agent 的 plugins。
    *
    * 关键点（中文）
    * - 默认 `true`。
    * - `false` 适合只需要 session 能力、不希望启动后台能力的嵌入场景。
    */
-  services?: boolean;
+  plugins?: boolean;
 }
 
 /**
@@ -169,9 +161,9 @@ export interface AgentStopResult {
   rpcStopped: boolean;
 
   /**
-   * 本次是否实际停止了 services。
+   * 本次是否实际停止了 plugins。
    */
-  servicesStopped: boolean;
+  pluginsStopped: boolean;
 }
 
 /**
@@ -189,9 +181,9 @@ export interface AgentStartResult {
   rpc?: AgentRpcBinding;
 
   /**
-   * 当前 agent 是否已启动 services。
+   * 当前 agent 是否已启动 plugins。
    */
-  servicesStarted: boolean;
+  pluginsStarted: boolean;
 }
 
 /**
@@ -261,6 +253,53 @@ export interface RemoteAgentOptions {
   baseUrl: string;
 }
 
+/**
+ * 新建 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 可变配置。
  */
@@ -290,13 +329,63 @@ export interface AgentSessionConfigSnapshot {
   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"
-  | "service"
   | "plugin"
   | "session";
 
@@ -314,7 +403,7 @@ export interface AgentSessionSystemBlock {
    *
    * 说明（中文）
    * - `instruction` 通常使用 `agent`。
-   * - `service` / `plugin` 使用对应 service/plugin 名称。
+   * - `plugin` 使用对应 plugin 名称。
    * - `core` 使用 `default`。
    * - `session` 使用当前 session 上下文名称。
    */
@@ -394,9 +483,9 @@ export interface AgentSessionSystemSnapshot {
 }
 
 /**
- * Session 元数据列表项。
+ * Session 摘要。
  */
-export interface AgentSessionMetadata {
+export interface AgentSessionSummary {
   /**
    * 当前 session 所属 agentId。
    */
@@ -407,6 +496,24 @@ export interface AgentSessionMetadata {
    */
   sessionId: string;
 
+  /**
+   * 当前 session 可读标题。
+   *
+   * 说明（中文）
+   * - 当前 SDK 不要求标题一定存在。
+   * - 若调用方需要展示列表标题，可优先使用这里；为空时再回退到 `sessionId`。
+   */
+  title?: string;
+
+  /**
+   * 当前 session 的最近预览文本。
+   *
+   * 说明（中文）
+   * - 通常来自最后一条用户可见消息的裁剪文本。
+   * - 适合用于侧边栏、列表卡片或 session picker。
+   */
+  previewText?: string;
+
   /**
    * 当前 session 首次创建时间（ms）。
    */
@@ -426,6 +533,126 @@ export interface AgentSessionMetadata {
    * 当前 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;
 }
 
 /**
@@ -441,3 +668,93 @@ export interface AgentSessionForkInput {
    */
   messageId?: string;
 }
+
+/**
+ * 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>;
+}