@downcity/agent 1.1.73 → 1.1.79

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,334 @@
+/**
+ * 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/{runtime/host → platform}/Store.ts

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

package/src/types/plugin/PluginAction.ts

@@ -0,0 +1,133 @@
+/**
+ * Plugin action 类型。
+ *
+ * 关键点（中文）
+ * - action 是 plugin 对外暴露的显式能力。
+ * - CLI / HTTP 只是 action 的输入适配层，真正执行器统一走 `execute`。
+ */
+
+import type { Command } from "commander";
+import type { Context as HonoContext } from "hono";
+import type { AgentContext } from "@/types/runtime/agent/AgentContext.js";
+import type { JsonValue } from "@/types/common/Json.js";
+
+/**
+ * Plugin action 调用参数。
+ */
+export interface PluginActionInvokeParams {
+  /** 目标 plugin 名称。 */
+  plugin: string;
+  /** 目标 action 名称。 */
+  action: string;
+  /** 调用 payload（可选）。 */
+  payload?: JsonValue;
+}
+
+/**
+ * Plugin action 调用结果。
+ */
+export interface PluginActionInvokeResult {
+  /** 调用是否成功。 */
+  success: boolean;
+  /** 结构化返回数据（可选）。 */
+  data?: JsonValue;
+  /** 错误信息（可选）。 */
+  error?: string;
+}
+
+/**
+ * Plugin action 调用端口。
+ */
+export interface PluginActionInvokePort {
+  /** 调用指定 plugin action。 */
+  invoke(
+    params: PluginActionInvokeParams,
+  ): Promise<PluginActionInvokeResult>;
+}
+
+/**
+ * Plugin Action 执行结果。
+ */
+export interface PluginActionResult<R extends JsonValue = JsonValue> {
+  /** Action 是否成功。 */
+  success: boolean;
+  /** 返回数据（可选）。 */
+  data?: R;
+  /** 错误信息（可选）。 */
+  error?: string;
+  /** 人类可读消息（可选）。 */
+  message?: string;
+}
+
+/**
+ * Plugin Action 命令输入。
+ */
+export interface PluginActionCommandInput {
+  /** 位置参数列表。 */
+  args: string[];
+  /** 选项参数对象。 */
+  opts: Record<string, JsonValue>;
+}
+
+/**
+ * Plugin Action CLI 定义。
+ */
+export interface PluginActionCommand<P extends JsonValue = JsonValue> {
+  /** 命令说明。 */
+  description: string;
+  /** 额外 commander 配置（可选）。 */
+  configure?: (command: Command) => void;
+  /** 将 CLI 输入映射为 payload。 */
+  mapInput: (input: PluginActionCommandInput) => P | Promise<P>;
+}
+
+/**
+ * Plugin Action HTTP 定义。
+ */
+export interface PluginActionApi<P extends JsonValue = JsonValue> {
+  /** HTTP 方法。 */
+  method?: "GET" | "POST" | "PUT" | "DELETE";
+  /** HTTP 路径。 */
+  path?: string;
+  /** 将 HTTP 输入映射为 payload（可选）。 */
+  mapInput?: (ctx: HonoContext) => P | Promise<P>;
+}
+
+/**
+ * Plugin Action 定义。
+ */
+export interface PluginAction<
+  P extends JsonValue = JsonValue,
+  R extends JsonValue = JsonValue,
+> {
+  /**
+   * disabled 状态下是否仍允许执行。
+   *
+   * 说明（中文）
+   * - 用于 `on` / `status` / `models` / `configure` / `install` 这类 setup 相关 action。
+   * - 默认 false，避免 disabled plugin 绕过 registry 保护执行普通业务 action。
+   */
+  allowWhenDisabled?: boolean;
+  /** CLI 定义（可选）。 */
+  command?: PluginActionCommand<P>;
+  /** HTTP 定义（可选）。 */
+  api?: PluginActionApi<P>;
+  /** Action 执行器。 */
+  execute: (params: {
+    /** 当前执行上下文。 */
+    context: AgentContext;
+    /** 输入 payload。 */
+    payload: P;
+    /** 当前插件名称。 */
+    pluginName: string;
+    /** 当前 Action 名称。 */
+    actionName: string;
+  }) => Promise<PluginActionResult<R>> | PluginActionResult<R>;
+}
+
+/**
+ * Plugin Action 集合。
+ */
+export type PluginActions = {
+  [actionName: string]: PluginAction<JsonValue, JsonValue>;
+};

package/src/types/plugin/PluginCommand.ts

@@ -0,0 +1,89 @@
+/**
+ * Plugin command 与 lifecycle 类型。
+ *
+ * 关键点（中文）
+ * - command 面向显式 CLI/control 调用。
+ * - lifecycle 面向 runtime 主动 start/stop 钩子。
+ */
+
+import type {
+  AgentPathRuntime,
+  AgentPluginConfigRuntime,
+} from "@/types/agent/AgentRuntimeAssembly.js";
+import type { AgentContext } from "@/types/runtime/agent/AgentContext.js";
+import type { Logger } from "@/utils/logger/Logger.js";
+import type { DowncityConfig } from "@/types/config/DowncityConfig.js";
+import type { JsonValue } from "@/types/common/Json.js";
+
+/**
+ * Plugin 命令执行上下文。
+ *
+ * 关键点（中文）
+ * - 这里表达的是“CLI 命令执行 plugin 时真正需要的最小上下文”。
+ * - plugin 命令不应依赖 session、plugin invoke、agent runtime 等长期宿主对象。
+ * - agent runtime 在需要复用 action 时，直接传入自身更完整的 AgentContext 即可。
+ */
+export interface PluginCommandContext {
+  /** 当前命令工作目录。 */
+  cwd: string;
+  /** 当前项目根目录。 */
+  rootPath: string;
+  /** 当前统一日志器。 */
+  logger: Logger;
+  /** 当前解析后的项目配置。 */
+  config: DowncityConfig;
+  /**
+   * 当前项目环境变量快照。
+   *
+   * 关键点（中文）
+   * - 这里约定为宿主已经整理好的最终可见 env 视图。
+   * - plugin 不再区分 global env 与 agent env，避免上下文语义膨胀。
+   */
+  env: Record<string, string>;
+  /** 当前可见的路径能力集合。 */
+  paths: AgentPathRuntime;
+  /** 当前可见的 plugin 配置持久化能力集合。 */
+  pluginConfig: AgentPluginConfigRuntime;
+}
+
+/**
+ * Plugin 非 action 命令执行参数。
+ */
+export interface PluginCommandParams {
+  /** 当前统一执行上下文。 */
+  context: AgentContext;
+  /** 当前命令名称。 */
+  command: string;
+  /** 命令附带 payload（可选）。 */
+  payload?: JsonValue;
+}
+
+/**
+ * Plugin 非 action 命令执行结果。
+ */
+export interface PluginCommandResult {
+  /** 本次命令是否成功。 */
+  success: boolean;
+  /** 人类可读消息。 */
+  message?: string;
+  /** 结构化返回数据。 */
+  data?: JsonValue;
+}
+
+/**
+ * Plugin 生命周期兼容定义。
+ *
+ * 关键点（中文）
+ * - 这是从旧运行生命周期过渡过来的兼容层。
+ * - 新代码优先直接实现 `start/stop/command`。
+ */
+export interface PluginLifecycle {
+  /** plugin 启动钩子。 */
+  start?(context: AgentContext): Promise<void> | void;
+  /** plugin 停止钩子。 */
+  stop?(context: AgentContext): Promise<void> | void;
+  /** plugin 非 action 命令钩子。 */
+  command?(
+    params: PluginCommandParams,
+  ): Promise<PluginCommandResult> | PluginCommandResult;
+}