@downcity/agent 1.1.8 → 1.1.11

package/src/host/sdk/Agent.ts

@@ -1,419 +0,0 @@
-/**
- * Agent SDK 本地入口。
- *
- * 关键点（中文）
- * - `new Agent({ id, path, tools, services, plugins })` 只做同步装配，不在构造阶段启动任何 I/O。
- * - session、HTTP、RPC、service lifecycle 都按需异步初始化。
- * - SDK Agent 通过最小 `AgentContext` 适配层复用现有 service/plugin/chat 运行协议，而不是重复实现一套执行链。
- */
-
-import fs from "fs-extra";
-import { nanoid } from "nanoid";
-import type { Tool } from "ai";
-import { Logger } from "@shared/utils/logger/Logger.js";
-import type { BaseService } from "@/service/builtins/BaseService.js";
-import type { AgentContext } from "@/agent/AgentContextTypes.js";
-import type { AgentRuntime } from "@/agent/AgentRuntimeTypes.js";
-import type { DowncityConfig } from "@/shared/types/DowncityConfig.js";
-import type { JsonValue } from "@/shared/types/Json.js";
-import type { AgentPlatformRuntime } from "@/shared/types/AgentHost.js";
-import type {
-  Plugin,
-  PluginAvailability,
-  PluginPort,
-  PluginView,
-} from "@/shared/types/Plugin.js";
-import type {
-  AgentOptions,
-  AgentSessionMetadata,
-} from "@/host/sdk/AgentSdkTypes.js";
-import { SdkSession } from "@/host/sdk/Session.js";
-import { loadStaticSystemPrompts } from "@session/composer/system/default/StaticPromptCatalog.js";
-import { getSdkAgentSessionsRootDirPath } from "@/host/sdk/Paths.js";
-import { SdkAgentHttpServer } from "@/host/sdk/HttpServer.js";
-import { SdkAgentRpcServer } from "@/host/sdk/RpcServer.js";
-import {
-  createAgentPathRuntime,
-  createAgentPluginConfigRuntime,
-} from "@/host/runtime/AgentHostRuntime.js";
-import { loadDowncityConfig } from "@/config/Config.js";
-import { appendExecSessionMessage } from "@/service/builtins/chat/runtime/ChatIngressStore.js";
-import { readChatMetaBySessionId } from "@/service/builtins/chat/runtime/ChatMetaStore.js";
-import { resolveChatQueueStore } from "@/service/builtins/chat/runtime/ChatQueueStore.js";
-import { HookRegistry } from "@/plugin/HookRegistry.js";
-import { PluginRegistry } from "@/plugin/PluginRegistry.js";
-import { isPluginEnabled } from "@/plugin/Activation.js";
-
-const EMPTY_SDK_PLATFORM: AgentPlatformRuntime = {
-  getGlobalEnv: () => ({}),
-  getAgentEnv: () => ({}),
-  listModels: () => [],
-  listProviders: async () => [],
-  getModel: () => null,
-  getChannelAccount: () => null,
-  readChatAuthorizationConfig: () => ({
-    roles: {},
-    channels: {},
-  }),
-  writeChatAuthorizationConfig: async (_projectRoot, nextConfig) => nextConfig,
-  setChatAuthorizationUserRole: async () => ({
-    roles: {},
-    channels: {},
-  }),
-  isPluginEnabled: (pluginName) => pluginName === "auth",
-};
-
-function createFallbackSdkConfig(agentId: string): DowncityConfig {
-  return {
-    name: agentId,
-    version: "0.0.0",
-  } as DowncityConfig;
-}
-
-/**
- * SDK 本地 Agent。
- */
-export class Agent {
-  readonly id: string;
-  readonly path: string;
-  readonly tools: Record<string, Tool>;
-  readonly http: SdkAgentHttpServer;
-  readonly rpc: SdkAgentRpcServer;
-  readonly services: Map<string, BaseService>;
-  readonly plugins: PluginPort;
-
-  private readonly logger: Logger;
-  private readonly sessionsById = new Map<string, SdkSession>();
-  private readonly runtime: AgentRuntime;
-  private readonly serviceContext: AgentContext;
-  private readonly pluginRegistry: PluginRegistry;
-  private readonly pluginSystemProviders: Plugin[];
-  private readonly config: DowncityConfig;
-  private readonly platform: AgentPlatformRuntime;
-  private systems: string[];
-  private servicesStartPromise: Promise<void> | null = null;
-
-  constructor(options: AgentOptions) {
-    this.id = String(options.id || "").trim();
-    this.path = String(options.path || "").trim();
-    this.tools = options.tools && typeof options.tools === "object"
-      ? { ...options.tools }
-      : {};
-    if (!this.id) {
-      throw new Error("Agent requires a non-empty id");
-    }
-    if (!this.path) {
-      throw new Error("Agent requires a non-empty path");
-    }
-
-    this.logger = new Logger();
-    this.logger.bindProjectRoot(this.path);
-    this.platform = options.platform || EMPTY_SDK_PLATFORM;
-    this.systems = loadStaticSystemPrompts(this.path);
-    this.config = this.loadConfig();
-    this.services = this.createServiceMap(options.services || []);
-    this.runtime = this.createRuntime();
-    for (const service of this.services.values()) {
-      service.bindAgent(this.runtime);
-    }
-    this.pluginSystemProviders = Array.isArray(options.plugins)
-      ? [...options.plugins]
-      : [];
-    this.pluginRegistry = this.createPluginRegistry(this.pluginSystemProviders);
-    this.plugins = this.createPluginPort();
-    this.serviceContext = this.createServiceContext();
-    this.http = new SdkAgentHttpServer(this);
-    this.rpc = new SdkAgentRpcServer(this);
-  }
-
-  /**
-   * 获取或创建一个 session。
-   */
-  async session(sessionId?: string): Promise<SdkSession> {
-    const session = this.getOrCreateSession(sessionId);
-    await session.initialize();
-    return session;
-  }
-
-  /**
-   * 列出当前 agent 的全部 session 元数据。
-   */
-  async sessions(): Promise<AgentSessionMetadata[]> {
-    const rootDir = getSdkAgentSessionsRootDirPath(this.path, this.id);
-    if (!(await fs.pathExists(rootDir))) return [];
-    const entries = await fs.readdir(rootDir, { withFileTypes: true });
-    const items: AgentSessionMetadata[] = [];
-    for (const entry of entries) {
-      if (!entry.isDirectory()) continue;
-      let sessionId = "";
-      try {
-        sessionId = decodeURIComponent(entry.name);
-      } catch {
-        sessionId = entry.name;
-      }
-      if (!sessionId) continue;
-      const session = await this.session(sessionId);
-      items.push(await session.toMetadata());
-    }
-    items.sort((a, b) => (b.updatedAt || 0) - (a.updatedAt || 0));
-    return items;
-  }
-
-  /**
-   * 确保显式注入的 services 已启动。
-   */
-  async ensureServicesStarted(): Promise<void> {
-    if (this.servicesStartPromise) {
-      await this.servicesStartPromise;
-      return;
-    }
-    this.servicesStartPromise = (async () => {
-      for (const service of this.services.values()) {
-        await service.lifecycle?.start?.(this.serviceContext);
-      }
-    })();
-    await this.servicesStartPromise;
-  }
-
-  /**
-   * 刷新静态 system 文本集合。
-   */
-  reloadStaticPrompts(): void {
-    this.systems = loadStaticSystemPrompts(this.path);
-  }
-
-  private loadConfig(): DowncityConfig {
-    try {
-      return loadDowncityConfig(this.path, {
-        projectEnv: {},
-        agentEnv: {},
-        globalEnv: {},
-      });
-    } catch {
-      return createFallbackSdkConfig(this.id);
-    }
-  }
-
-  private createServiceMap(input: BaseService[]): Map<string, BaseService> {
-    const services = new Map<string, BaseService>();
-    for (const service of input) {
-      const name = String(service?.name || "").trim();
-      if (!name) {
-        throw new Error("Agent received a service without a valid name");
-      }
-      if (services.has(name)) {
-        throw new Error(`Duplicate service registration: ${name}`);
-      }
-      services.set(name, service);
-    }
-    return services;
-  }
-
-  private createPluginRegistry(input: Plugin[]): PluginRegistry {
-    let pluginRegistryRef: PluginRegistry | null = null;
-    const hookRegistry = new HookRegistry({
-      contextResolver: () => this.serviceContext,
-      pluginEnabledChecker: (pluginName) => {
-        const plugin = pluginRegistryRef?.get(pluginName);
-        return plugin ? isPluginEnabled({ plugin, context: this.serviceContext }) : false;
-      },
-    });
-    const registry = new PluginRegistry({
-      contextResolver: () => this.serviceContext,
-      hookRegistry,
-    });
-    pluginRegistryRef = registry;
-
-    for (const plugin of input) {
-      registry.register(plugin);
-    }
-    return registry;
-  }
-
-  private createPluginPort(): PluginPort {
-    return {
-      list: (): PluginView[] => this.pluginRegistry.list(),
-      availability: async (pluginName: string): Promise<PluginAvailability> =>
-        await this.pluginRegistry.availability(pluginName),
-      runAction: async (params) => await this.pluginRegistry.runAction(params),
-      pipeline: async <T>(pointName: string, value: T): Promise<T> =>
-        await this.pluginRegistry.pipeline(pointName, value),
-      guard: async <T>(pointName: string, value: T): Promise<void> => {
-        await this.pluginRegistry.guard(pointName, value);
-      },
-      effect: async <T>(pointName: string, value: T): Promise<void> => {
-        await this.pluginRegistry.effect(pointName, value);
-      },
-      resolve: async <TInput, TOutput>(
-        pointName: string,
-        value: TInput,
-      ): Promise<TOutput> =>
-        await this.pluginRegistry.resolve<TInput, TOutput>(pointName, value),
-    };
-  }
-
-  private async loadPluginSystemPrompts(): Promise<string[]> {
-    const out: string[] = [];
-    for (const plugin of this.pluginSystemProviders) {
-      if (typeof plugin.system !== "function") continue;
-      try {
-        if (!isPluginEnabled({ plugin, context: this.serviceContext })) continue;
-        if (typeof plugin.availability === "function") {
-          const availability = await plugin.availability(this.serviceContext);
-          if (!availability.available) continue;
-        }
-        const text = String(await plugin.system(this.serviceContext)).trim();
-        if (!text) continue;
-        out.push(text);
-      } catch {
-        // 单个 plugin system 失败不应阻断 SDK session 主链路。
-      }
-    }
-    return out;
-  }
-
-  private async loadServiceSystemPrompts(): Promise<string[]> {
-    const out: string[] = [];
-    for (const service of this.services.values()) {
-      if (typeof service.system !== "function") continue;
-      try {
-        const text = String(await service.system(this.serviceContext)).trim();
-        if (!text) continue;
-        out.push(text);
-      } catch {
-        // 单个 service system 失败不应阻断 SDK session 主链路。
-      }
-    }
-    return out;
-  }
-
-  private createRuntime(): AgentRuntime {
-    const runtime = {
-      cwd: this.path,
-      rootPath: this.path,
-      logger: this.logger,
-      config: this.config,
-      env: {},
-      globalEnv: {},
-      systems: this.systems,
-      paths: createAgentPathRuntime(this.path),
-      pluginConfig: createAgentPluginConfigRuntime(this.path),
-      platform: this.platform,
-      model: undefined,
-      getSession: (sessionId: string) => {
-        return this.getOrCreateSession(sessionId).getServicePort() as never;
-      },
-      listExecutingSessionIds: () =>
-        [...this.sessionsById.values()]
-          .filter((session) => session.isExecuting())
-          .map((session) => session.id),
-      getExecutingSessionCount: () =>
-        [...this.sessionsById.values()].filter((session) => session.isExecuting()).length,
-      services: this.services,
-    } satisfies Omit<AgentRuntime, "getSession"> & {
-      getSession(sessionId: string): never;
-    };
-    return runtime as unknown as AgentRuntime;
-  }
-
-  private createServiceContext(): AgentContext {
-    let context!: AgentContext;
-    context = {
-      agent: this.runtime,
-      cwd: this.path,
-      rootPath: this.path,
-      logger: this.logger,
-      config: this.config,
-      env: {},
-      globalEnv: {},
-      systems: this.systems,
-      paths: this.runtime.paths,
-      pluginConfig: this.runtime.pluginConfig,
-      platform: this.platform,
-      session: {
-        get: (sessionId) => this.getOrCreateSession(sessionId).getServicePort(),
-        listExecutingSessionIds: () => this.runtime.listExecutingSessionIds(),
-        getExecutingSessionCount: () => this.runtime.getExecutingSessionCount(),
-      },
-      invoke: {
-        invoke: async (params: {
-          service: string;
-          action: string;
-          payload?: JsonValue;
-        }) => {
-          const serviceName = String(params.service || "").trim();
-          const actionName = String(params.action || "").trim();
-          const service = this.services.get(serviceName);
-          if (!service) {
-            return {
-              success: false,
-              error: `Unknown service: ${serviceName}`,
-            };
-          }
-          const action = service.actions[actionName];
-          if (!action) {
-            return {
-              success: false,
-              error: `Unknown action: ${serviceName}.${actionName}`,
-            };
-          }
-          const result = await action.execute({
-            context,
-            payload: params.payload ?? null,
-            serviceName,
-            actionName,
-          });
-          if (!result.success) {
-            return {
-              success: false,
-              ...(result.error ? { error: result.error } : {}),
-            };
-          }
-          return {
-            success: true,
-            ...(result.data !== undefined ? { data: result.data } : {}),
-          };
-        },
-      },
-      chat: {
-        readMetaBySessionId: async (sessionId: string) => {
-          return await readChatMetaBySessionId({
-            context,
-            sessionId,
-          });
-        },
-        appendExecSessionMessage: async (params) => {
-          await appendExecSessionMessage({
-            context,
-            sessionId: params.sessionId,
-            text: params.text,
-            extra: params.extra,
-          });
-        },
-        enqueue: (params) => resolveChatQueueStore(context).enqueue(params),
-      },
-      plugins: this.plugins,
-    };
-    return context;
-  }
-
-  private getOrCreateSession(sessionId?: string): SdkSession {
-    const resolvedSessionId =
-      String(sessionId || "").trim() || `session-${Date.now()}-${nanoid(8)}`;
-    const cached = this.sessionsById.get(resolvedSessionId);
-    if (cached) return cached;
-
-    const created = new SdkSession({
-      agentId: this.id,
-      projectRoot: this.path,
-      sessionId: resolvedSessionId,
-      tools: this.tools,
-      logger: this.logger,
-      getStaticSystemPrompts: () => this.systems,
-      getServiceSystemPrompts: () => this.loadServiceSystemPrompts(),
-      getPluginSystemPrompts: () => this.loadPluginSystemPrompts(),
-    });
-    this.sessionsById.set(resolvedSessionId, created);
-    return created;
-  }
-}

package/src/host/sdk/AgentSdkTypes.ts

@@ -1,296 +0,0 @@
-/**
- * Agent SDK 对外类型定义。
- *
- * 关键点（中文）
- * - 这里集中声明 `Agent` / `RemoteAgent` / `Session` 面向外部调用方的稳定接口。
- * - SDK 用户通过显式 `tools` / `services` / `plugins` 装配能力，不直接依赖内部 runtime 单例。
- * - 本地/远程 session 运行与基础落盘能力仍是 SDK 主路径。
- */
-
-import type { LanguageModel, Tool } from "ai";
-import type { BaseService } from "@/service/builtins/BaseService.js";
-import type { JsonValue } from "@/shared/types/Json.js";
-import type { Plugin } from "@/shared/types/Plugin.js";
-import type { SessionMessageV1 } from "@/types/session/SessionMessages.js";
-import type { AgentPlatformRuntime } from "@/shared/types/AgentHost.js";
-
-/**
- * 本地 Agent 构造参数。
- */
-export interface AgentOptions {
-  /**
-   * 当前 agent 的稳定标识。
-   *
-   * 关键点（中文）
-   * - 用于 `.downcity/agents/<agentId>/...` 目录分区。
-   * - 应保持稳定、可 URL 编码、尽量不要依赖展示名称。
-   */
-  id: string;
-
-  /**
-   * 当前 agent 绑定的项目根目录。
-   */
-  path: string;
-
-  /**
-   * 当前 agent 默认可用的工具集合。
-   *
-   * 关键点（中文）
-   * - tools 归属于 agent 级，而不是 session 级。
-   * - session 运行时会直接复用这份工具集合。
-   */
-  tools?: Record<string, Tool>;
-
-  /**
-   * 当前 agent 显式持有的 service 实例集合。
-   *
-   * 关键点（中文）
-   * - 这里接收已经实例化好的 service，而不是 service class。
-   * - `Agent` 会在构造阶段按名称注册这些实例，并在启动时自动绑定 runtime。
-   * - v1 推荐显式传入 `new ChatService(...)` 这类实例，而不是依赖包内隐式注册表。
-   */
-  services?: BaseService[];
-
-  /**
-   * 当前 agent 显式注册的 plugin 定义集合。
-   *
-   * 关键点（中文）
-   * - 这里接收完整 plugin 定义对象，而不是 plugin 名称。
-   * - `Agent` 会为当前 SDK 实例创建独立 plugin registry，避免污染全局 runtime。
-   * - 同名 plugin 会直接报错，避免 action / hook / resolve 行为被静默覆盖。
-   */
-  plugins?: Plugin[];
-
-  /**
-   * 当前 agent 显式注入的平台能力集合。
-   *
-   * 关键点（中文）
-   * - SDK 侧若不提供，则使用最小空实现。
-   * - 推荐由宿主产品显式传入，避免 SDK 本地实例隐式依赖 city。
-   */
-  platform?: AgentPlatformRuntime;
-}
-
-/**
- * 远程 Agent 构造参数。
- */
-export interface RemoteAgentOptions {
-  /**
-   * 远程 SDK HTTP 基础地址。
-   *
-   * 例如：`http://127.0.0.1:15314`
-   */
-  baseUrl: string;
-}
-
-/**
- * Session 可变配置。
- */
-export interface AgentSessionSetInput {
-  /**
-   * 当前 session 默认模型实例。
-   *
-   * 关键点（中文）
-   * - 这里接受运行中的模型实例，而不是模型 ID。
-   * - 由于模型实例通常不可序列化，落盘只保留轻量可读标签用于展示。
-   */
-  model?: LanguageModel;
-}
-
-/**
- * Session 当前配置快照。
- */
-export interface AgentSessionConfigSnapshot {
-  /**
-   * 当前 session 绑定的默认模型实例。
-   */
-  model?: LanguageModel;
-
-  /**
-   * 当前模型的轻量可读标签。
-   */
-  modelLabel?: string;
-}
-
-/**
- * Session 运行输入。
- */
-export interface AgentSessionRunInput {
-  /**
-   * 当前轮用户查询文本。
-   */
-  query: string;
-}
-
-/**
- * Session 运行结果。
- */
-export interface AgentSessionRunResult {
-  /**
-   * 本轮执行是否成功。
-   */
-  success: boolean;
-
-  /**
-   * 失败时的错误文本。
-   */
-  error?: string;
-
-  /**
-   * 最终 assistant 文本。
-   */
-  text: string;
-
-  /**
-   * 最终 assistant 原始 UIMessage。
-   */
-  assistantMessage: SessionMessageV1;
-}
-
-/**
- * SDK 对外的流式事件。
- */
-export type AgentSessionStreamEvent =
-  | {
-      /**
-       * 文本增量事件。
-       */
-      type: "text-delta";
-      /**
-       * 当前追加的文本片段。
-       */
-      text: string;
-    }
-  | {
-      /**
-       * reasoning 增量事件。
-       */
-      type: "reasoning-delta";
-      /**
-       * 当前追加的 reasoning 文本片段。
-       */
-      text: string;
-    }
-  | {
-      /**
-       * 工具调用可用事件。
-       */
-      type: "tool-call";
-      /**
-       * 当前工具调用唯一标识。
-       */
-      toolCallId: string;
-      /**
-       * 工具名称。
-       */
-      toolName: string;
-      /**
-       * 工具输入参数。
-       */
-      args: JsonValue;
-    }
-  | {
-      /**
-       * 工具调用结果事件。
-       */
-      type: "tool-result";
-      /**
-       * 当前工具调用唯一标识。
-       */
-      toolCallId: string;
-      /**
-       * 工具名称。
-       */
-      toolName: string;
-      /**
-       * 工具输出结果。
-       */
-      result: JsonValue;
-    }
-  | {
-      /**
-       * 工具调用失败事件。
-       */
-      type: "tool-error";
-      /**
-       * 当前工具调用唯一标识。
-       */
-      toolCallId: string;
-      /**
-       * 工具名称。
-       */
-      toolName: string;
-      /**
-       * 错误文本。
-       */
-      error: string;
-    }
-  | {
-      /**
-       * 运行结束事件。
-       */
-      type: "finish";
-      /**
-       * 最终完成原因（若底层可提供）。
-       */
-      finishReason?: string;
-    }
-  | {
-      /**
-       * 运行错误事件。
-       */
-      type: "error";
-      /**
-       * 错误文本。
-       */
-      error: string;
-    };
-
-/**
- * Session 元数据列表项。
- */
-export interface AgentSessionMetadata {
-  /**
-   * 当前 session 所属 agentId。
-   */
-  agentId: string;
-
-  /**
-   * 当前 session 唯一标识。
-   */
-  sessionId: string;
-
-  /**
-   * 当前 session 首次创建时间（ms）。
-   */
-  createdAt?: number;
-
-  /**
-   * 当前 session 最近一次更新时间（ms）。
-   */
-  updatedAt?: number;
-
-  /**
-   * 当前 session 已落盘消息数。
-   */
-  messageCount: number;
-
-  /**
-   * 当前 session 绑定模型的可读标签。
-   */
-  modelLabel?: string;
-}
-
-/**
- * Session fork 输入。
- */
-export interface AgentSessionForkInput {
-  /**
-   * 可选分叉锚点消息 ID。
-   *
-   * 关键点（中文）
-   * - 省略时复制当前 session 的完整消息历史。
-   * - 传入时复制到该消息为止（包含该消息）。
-   */
-  messageId?: string;
-}