@downcity/agent 1.1.35 → 1.1.51

package/src/types/config/AgentProject.ts

@@ -0,0 +1,93 @@
+/**
+ * Agent 项目初始化相关类型定义。
+ *
+ * 关键点（中文）
+ * - 统一承载 CLI 与 control plane 共用的初始化输入/输出结构。
+ * - 所有字段都面向"项目骨架创建"语义，不掺杂 runtime 状态。
+ */
+
+import type { ExecutionBindingConfig } from "@/types/config/ExecutionBinding.js";
+import type { DowncityConfig } from "@/types/config/DowncityConfig.js";
+
+/**
+ * 可选的 chat channel 标识。
+ */
+export type AgentProjectChannel = "telegram" | "feishu" | "qq";
+
+/**
+ * 初始化 agent 项目的输入参数。
+ */
+export interface AgentProjectInitializationInput {
+  /**
+   * agent 项目根目录（绝对路径或可解析相对路径）。
+   */
+  projectRoot: string;
+
+  /**
+   * agent 唯一标识。
+   *
+   * 关键点（中文）
+   * - 为空时会自动回退到目录名推导出的默认 id。
+   * - 该字段会直接写入 `downcity.json.id`。
+   */
+  id?: string;
+
+  /**
+   * 项目执行绑定配置。
+   *
+   * 说明（中文）
+   * - 绑定平台全局模型池中的模型 ID。
+   */
+  execution: ExecutionBindingConfig;
+
+  /**
+   * 需要一并写入项目的 plugin 配置补丁。
+   *
+   * 说明（中文）
+   * - 这里只承载初始化时的最小配置，不负责 city 级 plugin lifecycle。
+   */
+  plugins?: DowncityConfig["plugins"];
+
+  /**
+   * 需要启用的 chat channels。
+   *
+   * 关键点（中文）
+   * - 仅写入用户选择的渠道，未选择的渠道不会写入 `downcity.json`。
+   */
+  channels?: AgentProjectChannel[];
+
+  /**
+   * 是否允许覆盖已存在的 `downcity.json`。
+   */
+  forceOverwriteShipJson?: boolean;
+}
+
+/**
+ * 初始化完成后的摘要结果。
+ */
+export interface AgentProjectInitializationResult {
+  /**
+   * 已解析后的 agent 项目根目录（绝对路径）。
+   */
+  projectRoot: string;
+
+  /**
+   * 最终写入的 agent id。
+   */
+  id: string;
+
+  /**
+   * 最终启用的 chat channels。
+   */
+  channels: AgentProjectChannel[];
+
+  /**
+   * 本次实际创建/写入的文件列表。
+   */
+  createdFiles: string[];
+
+  /**
+   * 因已存在而跳过的文件列表。
+   */
+  skippedFiles: string[];
+}

package/src/types/config/DowncityConfig.ts

@@ -149,9 +149,15 @@ export interface DowncityPluginConfigMap {
 
 export interface DowncityConfig {
   $schema?: string;
-  name: string;
+  /**
+   * agent 唯一标识。
+   *
+   * 关键点（中文）
+   * - `@downcity/agent` 只关心稳定标识，不承担展示名语义。
+   * - 该字段同时用于 session/runtime/storage 目录归属。
+   */
+  id: string;
   version: string;
-  description?: string;
   /**
    * Runtime startup configuration used by `downcity agent start`.
    * CLI flags (if provided) take precedence over this config.
@@ -195,69 +201,4 @@ export interface DowncityConfig {
    * - 对于项目内 `downcity.json`，通常不需要显式写 provider/model 明细。
    */
   llm?: LlmConfig;
-  /**
-   * 上下文管理（工程向配置）。
-   *
-   * 说明
-   * - 对话消息以 UIMessage[] 为唯一事实源（`.downcity/agents/<agentId>/sessions/<sessionId>/messages/messages.jsonl`）。
-   * - Agent 每次执行直接把 UIMessage[] 转成 ModelMessage[] 作为 messages 输入。
-   * - 超出上下文窗口时会自动 compact（更早段压缩为摘要 + 保留最近窗口）。
-   */
-  context?: {
-    /**
-     * messages（唯一上下文消息来源）的 compact 策略。
-     */
-    messages?: {
-      /**
-       * 历史兼容字段（保留）。
-       *
-       * 说明（中文）
-       * - 当前默认策略按 `compactRatio` 压缩前段消息。
-       * - 该字段仍会写入 compact 元信息，便于观测与旧配置兼容。
-       *
-       * 默认：30
-       */
-      keepLastMessages?: number;
-      /**
-       * 输入预算（近似 token 数）。
-       *
-       * 说明（中文）
-       * - 这里是近似值，用于在调用 provider 前提前触发 compact
-       * - 实际超窗仍会被 provider 拒绝并进入 retry（更激进 compact）
-       *
-       * 默认：128000
-       */
-      maxInputTokensApprox?: number;
-      /**
-       * compact 时是否归档被折叠的原始消息段（写入 messages/archive/）。
-       * 默认：true
-       */
-      archiveOnCompact?: boolean;
-
-      /**
-       * 前段压缩比例（0-1）。
-       *
-       * 说明（中文）
-       * - 触发 compact 后，优先压缩最早一段消息。
-       * - `0.5` 代表优先压缩“最早 50% 的 UIMessage”。
-       * - 实际切分会做边界保护（至少保留 1 条最近消息）。
-       *
-       * 默认：0.5
-       */
-      compactRatio?: number;
-    };
-    /**
-     * 记忆管理配置。
-     *
-     * 设计目标
-     * - 默认开启，开箱即用（零配置）
-     * - 仅保留总开关，避免复杂配置负担
-     */
-    memory?: {
-      /**
-       * 是否启用 memory plugin。
-       */
-      enabled?: boolean;
-    };
-  };
 }

package/src/types/config/LlmConfig.ts

@@ -47,7 +47,7 @@ export interface LlmProviderConfig {
   baseUrl?: string;
   /**
    * Provider API 密钥。
-   * 建议使用 `${ENV_VAR}` 形式，启动时会自动解析环境变量。
+   * 建议由 Console 模型池直接保存，或由宿主在运行时显式注入 env 后再回退读取。
    */
   apiKey?: string;
 }

package/src/types/config/Start.ts

@@ -4,6 +4,8 @@
  * 字段说明（中文）
  * - `port`/`host`：主 API 服务监听地址。
  *   - `agent start/restart` 中的 `port` 由 console 自动分配（CLI 不再暴露 `--port`）。
+ * - `rpcPort`：Agent 本机 RPC 监听端口。
+ *   - 属于内部启动参数，通常由 city 自动分配，不面向普通用户。
  * - `daemon`：兼容旧参数（显式声明后台/前台）。
  * - `foreground`：显式前台启动。
  */
@@ -11,6 +13,7 @@
 export interface StartOptions {
   port?: number | string;
   host?: string;
+  rpcPort?: number | string;
   daemon?: boolean | string;
   foreground?: boolean | string;
 }

package/src/types/runtime/agent/AgentContext.ts

@@ -0,0 +1,272 @@
+/**
+ * Agent 执行上下文类型定义。
+ *
+ * 职责说明（中文）
+ * - 这里定义 plugin runtime、plugin、prompt system 共用的统一执行上下文。
+ * - `AgentContext` 表达的是“当前一次执行可见的能力面”，不是宿主状态本体。
+ *
+ * 边界说明（中文）
+ * - `AgentRuntime` 负责保存长期状态；`AgentContext` 负责把这些状态暴露成执行接口。
+ * - 这里只定义协议，不负责任何上下文装配逻辑。
+ */
+
+import type { LanguageModel } from "ai";
+import type { Logger } from "@/utils/logger/Logger.js";
+import type { AgentRuntime } from "@/types/runtime/agent/AgentRuntime.js";
+import type {
+  AgentPathRuntime,
+  AgentPluginConfigRuntime,
+} from "@/types/runtime/host/AgentHost.js";
+import type { DowncityConfig } from "@/types/config/DowncityConfig.js";
+import type { JsonObject, JsonValue } from "@/types/common/Json.js";
+import type { PluginPort } from "@/plugin/types/Plugin.js";
+import type {
+  SessionMetadataV1,
+  SessionMessageV1,
+} from "@/executor/types/SessionMessages.js";
+import type {
+  SessionRunInput,
+  SessionRunResult,
+} from "@/executor/types/SessionRun.js";
+import type { SessionHistoryStore } from "@/executor/store/history/SessionHistoryStore.js";
+import type { AgentSessionPromptInput } from "@/types/sdk/AgentSessionPrompt.js";
+import type {
+  AgentSessionSubscriber,
+  AgentSessionUnsubscribe,
+} from "@/types/sdk/AgentSessionEvent.js";
+import type { AgentSessionTurnHandle } from "@/types/sdk/AgentSessionTurn.js";
+
+/**
+ * 跨 plugin runtime 调用参数。
+ */
+export interface InvokePluginParams {
+  /**
+   * 目标 plugin 名称。
+   */
+  plugin: string;
+  /**
+   * 目标 action 名称。
+   */
+  action: string;
+  /**
+   * 调用时附带的结构化 payload。
+   */
+  payload?: JsonValue;
+}
+
+/**
+ * 跨 plugin runtime 调用结果。
+ */
+export interface InvokePluginResult {
+  /**
+   * 调用是否成功。
+   */
+  success: boolean;
+  /**
+   * 成功时返回的数据载荷。
+   */
+  data?: JsonValue;
+  /**
+   * 失败时的错误信息。
+   */
+  error?: string;
+}
+
+/**
+ * 跨 plugin runtime 调用端口。
+ */
+export interface InvokePluginPort {
+  /**
+   * 调用指定 plugin action。
+   */
+  invoke(params: InvokePluginParams): Promise<InvokePluginResult>;
+}
+
+/**
+ * 单个 Session 执行端口。
+ */
+export interface SessionExecutorPort {
+  /**
+   * 执行一次 session run。
+   */
+  run(params: SessionRunInput): Promise<SessionRunResult>;
+
+  /**
+   * 请求取消当前正在执行的 turn。
+   *
+   * 关键点（中文）
+   * - 对普通本地 runtime 可不实现。
+   * - ACP runtime 可借此向远端发送 `session/cancel`。
+   */
+}
+
+/**
+ * 单个 Session 实例端口。
+ */
+export interface SessionPort {
+  /**
+   * 当前 session 标识。
+   */
+  readonly sessionId: string;
+  /**
+   * 获取当前 session 的执行端口。
+   */
+  getExecutor(): SessionExecutorPort;
+  /**
+   * 获取当前 session 的持久化端口。
+   */
+  getHistoryStore(): SessionHistoryStore;
+  /**
+   * 向当前 session actor 追加一条新的 prompt。
+   *
+   * 关键点（中文）
+   * - 这是面向 SDK / transport 的统一交互输入入口。
+   * - 返回值只有在当前输入被绑定到某个 turn 后才会兑现。
+   */
+  prompt(input: AgentSessionPromptInput): Promise<AgentSessionTurnHandle>;
+  /**
+   * 订阅当前 session 后续产生的 future 事件。
+   *
+   * 关键点（中文）
+   * - 只广播订阅之后产生的事件。
+   * - 历史消息仍通过 `getHistoryStore()` / SDK `history()` 读取。
+   */
+  subscribe(subscriber: AgentSessionSubscriber): AgentSessionUnsubscribe;
+  /**
+   * 清理当前 session 的 executor 缓存。
+   */
+  clearExecutor(): void;
+  /**
+   * 当前 session 更新后的异步通知钩子。
+   */
+  afterSessionUpdatedAsync(): Promise<void>;
+  /**
+   * 追加一条 user 消息。
+   */
+  appendUserMessage(params: {
+    /**
+     * 已构造好的完整消息。
+     */
+    message?: SessionMessageV1 | null;
+    /**
+     * 兜底文本内容。
+     */
+    text?: string;
+    /**
+     * 附加元数据。
+     */
+    extra?: SessionMetadataV1["extra"];
+  }): Promise<void>;
+  /**
+   * 追加一条 assistant 消息。
+   */
+  appendAssistantMessage(params: {
+    /**
+     * 已构造好的完整消息。
+     */
+    message?: SessionMessageV1 | null;
+    /**
+     * 兜底文本内容。
+     */
+    fallbackText?: string;
+    /**
+     * 附加元数据。
+     */
+    extra?: SessionMetadataV1["extra"];
+  }): Promise<void>;
+  /**
+   * 返回当前 session 是否正在执行。
+   */
+  isExecuting(): boolean;
+}
+
+/**
+ * Session 集合入口。
+ */
+export interface SessionCollectionPort {
+  /**
+   * 获取指定 sessionId 对应的 Session 实例。
+   */
+  get(sessionId: string): SessionPort;
+  /**
+   * 返回当前所有执行中的 sessionId。
+   */
+  listExecutingSessionIds(): string[];
+  /**
+   * 返回当前执行中的 session 数量。
+   */
+  getExecutingSessionCount(): number;
+  /**
+   * 解析指定 session 当前绑定的模型实例。
+   *
+   * 关键点（中文）
+   * - 模型归属于 session，而不是 agent 全局运行时。
+   * - 这里会触发 session 初始化/宿主配置，适合 task 等后台链路按 session 读取模型。
+   */
+  resolveModel(sessionId: string): Promise<LanguageModel | undefined>;
+}
+
+/**
+ * 统一执行上下文。
+ */
+export interface AgentContext {
+  /**
+   * 当前执行上下文对应的 agent 状态。
+   */
+  agent: AgentRuntime;
+  /**
+   * 当前命令工作目录。
+   */
+  cwd: string;
+  /**
+   * 当前项目根目录。
+   */
+  rootPath: string;
+  /**
+   * 统一日志器。
+   */
+  logger: Logger;
+  /**
+   * 当前运行时已解析配置。
+   */
+  config: DowncityConfig;
+  /**
+   * 当前项目环境变量快照。
+   */
+  env: Record<string, string>;
+  /**
+   * 当前生效的 system 文本集合。
+   */
+  systems: string[];
+  /**
+   * 当前可见的路径能力集合。
+   */
+  paths: AgentPathRuntime;
+  /**
+   * 当前可见的 plugin 配置持久化能力集合。
+   */
+  pluginConfig: AgentPluginConfigRuntime;
+  /**
+   * Session 能力入口。
+   *
+   * 关键点（中文）
+   * - plugin runtime 与 plugin 都通过这里访问 session 执行与持久化能力。
+   * - 内外统一使用 `sessionId` 语义。
+   */
+  session: SessionCollectionPort;
+  /**
+   * 跨 plugin runtime 调用主入口。
+   */
+  invoke: InvokePluginPort;
+  /**
+   * Plugin 调用入口。
+   */
+  plugins: PluginPort;
+}
+
+/**
+ * 允许 optional 字段的结构化配置对象。
+ */
+export type StructuredConfig = {
+  [key: string]: JsonValue | undefined;
+};

package/src/types/runtime/agent/AgentRuntime.ts

@@ -0,0 +1,84 @@
+/**
+ * Agent 实例运行时类型定义。
+ *
+ * 职责说明（中文）
+ * - 这里定义单个 `Agent` 实例持有的长期运行状态视图。
+ * - Session、plugin、server 等长期对象都通过这组类型共享统一状态结构。
+ *
+ * 边界说明（中文）
+ * - 这些类型描述的是“实例级长期状态”，不是某一次执行的上下文视图。
+ * - 运行时实现细节仍分散在各模块中，这里只保留稳定的共享结构定义。
+ */
+
+import type { Logger } from "@/utils/logger/Logger.js";
+import type { DowncityConfig } from "@/types/config/DowncityConfig.js";
+import type {
+  AgentPathRuntime,
+  AgentPluginConfigRuntime,
+} from "@/types/runtime/host/AgentHost.js";
+import type { BasePlugin } from "@/plugin/core/BasePlugin.js";
+import type { SessionPort } from "@/types/runtime/agent/AgentContext.js";
+
+/**
+ * Agent 实例启动早期的基础状态。
+ */
+export interface AgentRuntimeBase {
+  /**
+   * 当前命令工作目录。
+   */
+  cwd: string;
+  /**
+   * 当前 agent 项目根目录。
+   */
+  rootPath: string;
+  /**
+   * 当前统一日志器。
+   */
+  logger: Logger;
+  /**
+   * 当前解析后的项目配置。
+   */
+  config: DowncityConfig;
+  /**
+   * 当前 agent 局部环境变量快照。
+   */
+  env: Record<string, string>;
+  /**
+   * 当前生效的静态 system 文本集合。
+   */
+  systems: string[];
+  /**
+   * 当前 agent 可见的路径能力集合。
+   */
+  paths: AgentPathRuntime;
+  /**
+   * 当前 agent 可见的 plugin 配置持久化能力集合。
+   */
+  pluginConfig: AgentPluginConfigRuntime;
+}
+
+/**
+ * Agent 实例完整运行状态。
+ */
+export interface AgentRuntime extends AgentRuntimeBase {
+  /**
+   * 读取指定 sessionId 对应的 session 端口。
+   *
+   * 关键点（中文）
+   * - 返回值是统一的 `SessionPort`，而不是裸 `Executor`。
+   * - 这样 HTTP / plugin runtime / chat queue / contact 等入口都能复用同一层会话装配与执行兜底。
+   */
+  getSession(sessionId: string): SessionPort;
+  /**
+   * 返回当前执行中的 sessionId 列表。
+   */
+  listExecutingSessionIds(): string[];
+  /**
+   * 返回当前执行中的 session 数量。
+   */
+  getExecutingSessionCount(): number;
+  /**
+   * 当前 agent 持有的插件实例集合。
+   */
+  pluginInstances: Map<string, BasePlugin>;
+}