@downcity/agent 1.1.35 → 1.1.43

package/src/types/common/EnvFile.ts

@@ -0,0 +1,31 @@
+/**
+ * Env 文件工具相关类型定义。
+ *
+ * 职责说明（中文）
+ * - 统一描述 `.env` / `.env.example` 写入工具使用的最小数据结构。
+ * - 避免工具模块直接内联匿名对象，便于后续在其他初始化流程中复用。
+ * - 这里只描述“文件写入条目”，不承载运行时环境变量快照语义。
+ */
+
+/**
+ * Env 文件中的单条键值项。
+ */
+export interface EnvFileEntry {
+  /**
+   * 环境变量键名。
+   *
+   * 关键点（中文）
+   * - 调用方应传入已规范化的变量名。
+   * - 工具层不会自动把任意字符串修正成合法变量名。
+   */
+  key: string;
+
+  /**
+   * 环境变量值。
+   *
+   * 关键点（中文）
+   * - 会按字面量写入目标文件。
+   * - 当前工具不额外做引号包裹或 shell 转义。
+   */
+  value: string;
+}

package/src/types/common/ResolvedConfigValue.ts

@@ -0,0 +1,16 @@
+/**
+ * 配置值递归结构类型。
+ *
+ * 职责说明（中文）
+ * - 描述 `downcity.json` 在“读取原始 JSON -> 解析环境变量占位符”阶段可接受的值结构。
+ * - 允许对象、数组、JSON 标量与 `undefined` 递归嵌套，供配置解析工具复用。
+ * - 该类型只服务配置装配阶段，不承诺运行时最终配置的严格业务语义。
+ */
+export type ResolvedConfigValue =
+  | string
+  | number
+  | boolean
+  | null
+  | undefined
+  | { [key: string]: ResolvedConfigValue }
+  | ResolvedConfigValue[];

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>;
+}

package/src/types/runtime/host/AgentHost.ts

@@ -4,28 +4,10 @@
  * 关键点（中文）
  * - 这里统一描述由 agent runtime 装配、再挂入 AgentRuntime 的宿主能力。
  * - plugin runtime / session / plugin 作者 API 只能消费这些稳定能力，不应直接依赖具体宿主实现。
- * - 当前先收敛路径、认证、plugin 配置持久化三类高频能力。
+ * - 当前先收敛路径与 plugin 配置持久化两类高频能力。
  */
 
 import type { DowncityConfig } from "@/types/config/DowncityConfig.js";
-import type {
-  ChatAuthorizationChannel,
-  ChatAuthorizationConfig,
-} from "@/plugin/builtins/auth/types/AuthPlugin.js";
-import type {
-  ChatChannelAccountCreateInput,
-  ChatChannelAccountListItem,
-  ChatChannelAccountProbeResult,
-  ChatChannelAccountUpsertInput,
-} from "@/plugin/builtins/chat/types/ChannelAccount.js";
-import type {
-  StoredChannelAccount,
-  StoredModel,
-  StoredModelProvider,
-} from "@/types/runtime/host/Store.js";
-import type { ChatChannelName } from "@/plugin/builtins/chat/types/ChannelStatus.js";
-import type { AgentProjectInitializationInput } from "@/config/project/types/AgentProject.js";
-import type { PlatformModelChoice } from "@/config/project/AgentInitializer.js";
 
 /**
  * Agent 路径能力集合。
@@ -90,123 +72,3 @@ export interface AgentPluginConfigRuntime {
    */
   persistProjectPlugins(plugins: DowncityConfig["plugins"] | undefined): Promise<string>;
 }
-
-/**
- * Agent 可见的平台能力集合。
- *
- * 关键点（中文）
- * - agent 只消费这些平台能力，不直接管理平台级持久化实现。
- * - 具体数据存储与管理应由 city / control plane 提供。
- */
-export interface AgentPlatformRuntime {
-  /**
-   * 读取当前平台级全局环境变量快照。
-   */
-  getGlobalEnv(): Record<string, string>;
-  /**
-   * 读取指定 agent 项目的私有环境变量快照。
-   */
-  getAgentEnv(projectRoot: string): Record<string, string>;
-  /**
-   * 读取当前平台模型池中的全部模型。
-   */
-  listModels(): StoredModel[];
-  /**
-   * 读取当前平台模型池中的全部 provider。
-   */
-  listProviders(): Promise<StoredModelProvider[]>;
-  /**
-   * 按模型 ID 读取单个模型。
-   */
-  getModel(modelId: string): StoredModel | null;
-  /**
-   * 按账户 ID 读取单个渠道账户。
-   */
-  getChannelAccount(channelAccountId: string): StoredChannelAccount | null;
-  /**
-   * 列出当前平台保存的全部渠道账户安全视图。
-   */
-  listChannelAccounts?(): Promise<ChatChannelAccountListItem[]>;
-  /**
-   * 探测渠道凭据并返回建议账户信息。
-   */
-  probeChannelAccount?(input: {
-    channel: string;
-    botToken?: string;
-    appId?: string;
-    appSecret?: string;
-    domain?: string;
-    sandbox?: boolean;
-  }): Promise<ChatChannelAccountProbeResult>;
-  /**
-   * 创建新的渠道账户。
-   */
-  createChannelAccount?(input: ChatChannelAccountCreateInput): Promise<{
-    id: string;
-    probed: boolean;
-    message?: string;
-  }>;
-  /**
-   * 更新现有渠道账户。
-   */
-  updateChannelAccount?(input: ChatChannelAccountUpsertInput): Promise<void>;
-  /**
-   * 删除渠道账户。
-   */
-  removeChannelAccount?(channelAccountId: string): Promise<void>;
-  /**
-   * 解析某个渠道当前应使用的账户。
-   */
-  resolveChannelAccount?(params: {
-    projectRoot: string;
-    channel: ChatChannelName;
-    channelAccountId?: string;
-  }): StoredChannelAccount | null;
-  /**
-   * 读取当前 agent 的 chat 授权配置。
-   */
-  readChatAuthorizationConfig(projectRoot: string): ChatAuthorizationConfig;
-  /**
-   * 覆盖写入当前 agent 的 chat 授权配置。
-   */
-  writeChatAuthorizationConfig(
-    projectRoot: string,
-    nextConfig: ChatAuthorizationConfig,
-  ): Promise<ChatAuthorizationConfig>;
-  /**
-   * 设置当前 agent 某个渠道用户的授权角色。
-   */
-  setChatAuthorizationUserRole(params: {
-    projectRoot: string;
-    channel: ChatAuthorizationChannel;
-    userId: string;
-    roleId: string;
-  }): Promise<ChatAuthorizationConfig>;
-  /**
-   * 判断指定 plugin 当前是否启用。
-   */
-  isPluginEnabled(pluginName: string): boolean;
-  /**
-   * 设置指定 plugin 的全局启用态。
-   */
-  setPluginEnabled?(pluginName: string, enabled: boolean): void;
-  /**
-   * 列出平台模型选项。
-   */
-  listPlatformModelChoices?(): Promise<PlatformModelChoice[]>;
-  /**
-   * 初始化 agent 项目。
-   */
-  initializeAgentProject?(
-    input: AgentProjectInitializationInput,
-  ): Promise<{
-    projectRoot: string;
-    agentName: string;
-    createdFiles: string[];
-    skippedFiles: string[];
-  }>;
-  /**
-   * 校验项目执行绑定是否已就绪。
-   */
-  ensureRuntimeExecutionBindingReady?(projectRoot: string): void;
-}

package/src/utils/object/DeepMerge.ts

@@ -0,0 +1,40 @@
+/**
+ * 通用深合并工具模块。
+ *
+ * 职责说明（中文）
+ * - 提供对象递归合并能力，供配置装配等“层层覆盖”场景复用。
+ * - 统一约束数组与标量的覆盖语义，避免不同模块出现不一致行为。
+ * - 这里只负责结构合并，不负责字段合法性校验。
+ */
+
+import { isPlainObject } from "@/utils/object/ObjectGuards.js";
+
+/**
+ * 深合并两个未知值。
+ *
+ * 关键点（中文）
+ * - 只有“对象 + 对象”会递归合并。
+ * - 数组始终以 `override` 为准，不做拼接。
+ * - 当 `override === undefined` 时保留 `base`，便于做配置层覆盖。
+ */
+export function deepMerge(base: unknown, override: unknown): unknown {
+  if (!isPlainObject(base) || !isPlainObject(override)) {
+    return override === undefined ? base : override;
+  }
+
+  const out: Record<string, unknown> = { ...base };
+  for (const [key, overrideValue] of Object.entries(override)) {
+    const baseValue = base[key];
+    if (Array.isArray(overrideValue)) {
+      out[key] = overrideValue;
+      continue;
+    }
+    if (isPlainObject(overrideValue) && isPlainObject(baseValue)) {
+      out[key] = deepMerge(baseValue, overrideValue);
+      continue;
+    }
+    out[key] = overrideValue === undefined ? baseValue : overrideValue;
+  }
+
+  return out;
+}

package/src/utils/object/ObjectGuards.ts

@@ -0,0 +1,19 @@
+/**
+ * 对象类型守卫工具模块。
+ *
+ * 职责说明（中文）
+ * - 提供与“普通对象”判断相关的基础守卫函数。
+ * - 供配置解析、CLI 输出、深合并等多个领域复用，避免每个模块各写一份。
+ * - 这里只处理通用对象判断，不携带任何业务字段语义。
+ */
+
+/**
+ * 判断一个值是否为普通对象记录。
+ *
+ * 关键点（中文）
+ * - 数组、`null`、函数都不会被视为普通对象。
+ * - 当前只要求“可按键遍历的普通对象”，不强制校验原型链来源。
+ */
+export function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}

package/src/utils/path/AncestorFiles.ts

@@ -0,0 +1,40 @@
+/**
+ * 祖先目录文件收集工具模块。
+ *
+ * 职责说明（中文）
+ * - 负责沿着目录树自下而上查找固定文件名，并按“根到叶子”顺序返回。
+ * - 供配置继承、工作区约定查找等场景复用，避免把目录遍历逻辑散落到业务模块。
+ * - 这里只处理文件路径收集，不解析文件内容。
+ */
+
+import fs from "fs-extra";
+import path from "node:path";
+
+/**
+ * 收集当前目录及其所有祖先目录中的指定文件。
+ *
+ * 关键点（中文）
+ * - 返回结果按“最上层目录 -> 当前项目目录”排序，适合做逐层覆盖合并。
+ * - 若文件名为空，则直接返回空数组，避免调用方拼接出异常路径。
+ */
+export function collectAncestorNamedFilePaths(
+  projectRoot: string,
+  filename: string,
+): string[] {
+  const normalizedFilename = String(filename || "").trim();
+  if (!normalizedFilename) return [];
+
+  const paths: string[] = [];
+  let dir = path.resolve(String(projectRoot || "").trim() || ".");
+  while (true) {
+    const candidate = path.join(dir, normalizedFilename);
+    if (fs.existsSync(candidate)) {
+      paths.push(candidate);
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+
+  return paths.reverse();
+}

package/src/utils/string/EscapeRegExp.ts

@@ -0,0 +1,19 @@
+/**
+ * 正则转义工具模块。
+ *
+ * 职责说明（中文）
+ * - 提供把普通字符串安全嵌入 `RegExp` 模式中的基础能力。
+ * - 避免各业务模块手写重复实现，并降低正则特殊字符导致的误匹配风险。
+ * - 这里只做字面量转义，不负责拼装完整正则表达式。
+ */
+
+/**
+ * 转义字符串中的正则特殊字符。
+ *
+ * 关键点（中文）
+ * - 返回值适合直接插入 `new RegExp(...)` 的模式字符串。
+ * - 不会自动添加边界、分组或 flags。
+ */
+export function escapeRegExp(input: string): string {
+  return String(input || "").replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}