@downcity/agent 1.1.13 → 1.1.15

package/src/sdk/Agent.ts

@@ -2,470 +2,242 @@
  * Agent SDK 本地入口。
  *
  * 关键点（中文）
- * - `new Agent({ id, path, instruction, tools, services, plugins })` 只做同步装配，不在构造阶段启动任何 I/O。
+ * - `Agent` 现在是实例外观层，长期运行状态下沉到 `AgentCore`。
  * - session、HTTP、RPC、service lifecycle 都按需异步初始化。
- * - SDK Agent 通过最小 `AgentContext` 适配层复用现有 service/plugin/chat 运行协议，而不是重复实现一套执行链。
+ * - `start/stop` 是唯一公开的长期运行生命周期入口。
  */
 
-import fs from "fs-extra";
-import { nanoid } from "nanoid";
 import type { Tool } from "ai";
-import { Logger } from "@/utils/logger/Logger.js";
 import type { BaseService } from "@/service/builtins/BaseService.js";
-import type { AgentContext } from "@/runtime/AgentContextTypes.js";
-import type { AgentRuntime } from "@/runtime/AgentRuntimeTypes.js";
-import type { DowncityConfig } from "@/types/config/DowncityConfig.js";
-import type { JsonValue } from "@/types/common/Json.js";
-import type { AgentPlatformRuntime } from "@/types/host/AgentHost.js";
+import type { AgentContext } from "@/core/AgentContextTypes.js";
+import type { AgentRuntime } from "@/core/AgentCoreTypes.js";
 import type {
-  Plugin,
-  PluginAvailability,
   PluginPort,
-  PluginView,
 } from "@/plugin/types/Plugin.js";
 import type {
   AgentOptions,
+  AgentStartOptions,
+  AgentStartResult,
+  AgentStopResult,
+  AgentHttpBinding,
+  AgentHttpStartOptions,
+  AgentRpcBinding,
   AgentSessionMetadata,
-  AgentSessionSystemBlock,
 } from "@/sdk/AgentSdkTypes.js";
 import { Session } from "@/sdk/Session.js";
-import { DEFAULT_SHIP_PROMPTS } from "@session/composer/system/default/SystemDomain.js";
-import { getSdkAgentSessionsRootDirPath } from "@/sdk/Paths.js";
-import { SdkAgentHttpServer } from "@/sdk/HttpServer.js";
-import { SdkAgentRpcServer } from "@/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/core/HookRegistry.js";
-import { PluginRegistry } from "@/plugin/core/PluginRegistry.js";
-import { isPluginEnabled } from "@/plugin/core/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;
-}
-
-function normalizeInstructionInput(input: string | string[] | undefined): string[] {
-  const items = Array.isArray(input) ? input : typeof input === "string" ? [input] : [];
-  return items
-    .map((item) => String(item || "").trim())
-    .filter((item) => item.length > 0);
-}
-
-function createCoreInstructionContent(projectRoot: string): string {
-  const currentYear = String(new Date().getFullYear());
-  return DEFAULT_SHIP_PROMPTS
-    .replaceAll("{{project_path}}", projectRoot)
-    .replaceAll("{{project_root}}", projectRoot)
-    .replaceAll("{{current_year}}", currentYear);
-}
-
-function createInstructionSystemBlocks(
-  instruction: string[],
-  projectRoot: string,
-): AgentSessionSystemBlock[] {
-  if (instruction.length === 0) {
-    return [
-      {
-        source: "core",
-        name: "default",
-        content: createCoreInstructionContent(projectRoot),
-      },
-    ];
-  }
-  return instruction.map((content, index) => ({
-    source: "instruction" as const,
-    name: instruction.length === 1 ? "agent" : `agent:${index + 1}`,
-    content,
-  }));
-}
+import { AgentCore } from "@/core/AgentCore.js";
+import { startAllServices, stopAllServices } from "@/service/core/Manager.js";
+import { startServer } from "@/server/http/Server.js";
+import { startLocalRpcServer } from "@/server/rpc/Server.js";
 
 /**
  * SDK 本地 Agent。
  */
 export class Agent {
+  readonly core: AgentCore;
   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, Session>();
-  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 instruction: string[];
-  private servicesStartPromise: Promise<void> | null = null;
+  private servicesStarted = false;
+  private startPromise: Promise<AgentStartResult> | null = null;
+  private httpBinding: AgentHttpBinding | null = null;
+  private rpcBinding: AgentRpcBinding | 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.instruction = normalizeInstructionInput(options.instruction);
-    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);
+    this.core = new AgentCore(options);
+    this.id = this.core.id;
+    this.path = this.core.path;
+    this.tools = this.core.tools;
+    this.services = this.core.services;
+    this.plugins = this.core.plugins;
   }
 
   /**
    * 获取或创建一个 session。
    */
   async session(sessionId?: string): Promise<Session> {
-    const session = this.getOrCreateSession(sessionId);
-    await session.initialize();
-    return session;
+    return await this.core.session(sessionId);
   }
 
   /**
    * 列出当前 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;
+    return await this.core.sessions();
   }
 
   /**
    * 确保显式注入的 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);
+    if (this.servicesStarted) return;
+    const lifecycle = await startAllServices(this.getContext());
+    this.servicesStarted = true;
+    for (const item of lifecycle.results) {
+      if (!item.success) {
+        this.getRuntime().logger.error(
+          `Service start failed: ${item.service?.name || "unknown"} - ${item.error || "unknown error"}`,
+        );
       }
-    })();
-    await this.servicesStartPromise;
+    }
   }
 
   /**
-   * 更新当前 SDK Agent 的静态基础指令。
-   *
-   * 关键点（中文）
-   * - instruction 不做动态变量替换。
-   * - 已创建的 session 后续 run 会读取最新 instruction blocks。
+   * 启动当前 agent 实例的长期运行能力。
    */
-  setInstruction(input: string | string[]): void {
-    this.instruction = normalizeInstructionInput(input);
-  }
+  async start(options?: AgentStartOptions): Promise<AgentStartResult> {
+    if (this.startPromise) {
+      return await this.startPromise;
+    }
+    this.startPromise = (async () => {
+      const shouldStartServices = options?.services !== false;
 
-  private loadConfig(): DowncityConfig {
+      if (shouldStartServices) {
+        await this.ensureServicesStarted();
+      }
+
+      const httpBinding =
+        options?.http === false || options?.http === undefined
+          ? undefined
+          : await this.startHttp(options.http);
+      const rpcBinding =
+        options?.rpc === true
+          ? await this.startRpc()
+          : undefined;
+
+      return {
+        ...(httpBinding ? { http: httpBinding } : {}),
+        ...(rpcBinding ? { rpc: rpcBinding } : {}),
+        servicesStarted: this.servicesStarted,
+      };
+    })();
     try {
-      return loadDowncityConfig(this.path, {
-        projectEnv: {},
-        agentEnv: {},
-        globalEnv: {},
-      });
-    } catch {
-      return createFallbackSdkConfig(this.id);
+      return await this.startPromise;
+    } catch (error) {
+      this.startPromise = null;
+      throw error;
     }
   }
 
-  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);
+  /**
+   * 停止当前 agent 实例的长期运行能力。
+   */
+  async stop(): Promise<AgentStopResult> {
+    const servicesStarted = this.servicesStarted;
+    const rpcStarted = this.rpcBinding !== null;
+    const httpStarted = this.httpBinding !== null;
+
+    if (servicesStarted) {
+      await stopAllServices(this.getContext());
+      this.servicesStarted = false;
     }
-    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;
+    if (rpcStarted) {
+      await this.stopRpc();
+    }
 
-    for (const plugin of input) {
-      registry.register(plugin);
+    if (httpStarted) {
+      await this.stopHttp();
     }
-    return registry;
-  }
 
-  private createPluginPort(): PluginPort {
+    this.startPromise = null;
+
     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),
+      httpStopped: httpStarted,
+      rpcStopped: rpcStarted,
+      servicesStopped: servicesStarted,
     };
   }
 
-  private loadInstructionSystemBlocks(): AgentSessionSystemBlock[] {
-    return createInstructionSystemBlocks(this.instruction, this.path);
+  /**
+   * 更新当前 SDK Agent 的静态基础指令。
+   *
+   * 关键点（中文）
+   * - instruction 不做动态变量替换。
+   * - 已创建的 session 后续 run 会读取最新 instruction blocks。
+   */
+  setInstruction(input: string | string[]): void {
+    this.core.setInstruction(input);
   }
 
-  private async loadPluginSystemBlocks(): Promise<AgentSessionSystemBlock[]> {
-    const out: AgentSessionSystemBlock[] = [];
-    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({
-          source: "plugin",
-          name: plugin.name,
-          content: text,
-        });
-      } catch {
-        // 单个 plugin system 失败不应阻断 SDK session 主链路。
-      }
-    }
-    return out;
+  /**
+   * 返回实例级 runtime 视图。
+   */
+  getRuntime(): AgentRuntime {
+    return this.core.getRuntime();
   }
 
-  private async loadServiceSystemBlocks(): Promise<AgentSessionSystemBlock[]> {
-    const out: AgentSessionSystemBlock[] = [];
-    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({
-          source: "service",
-          name: service.name,
-          content: text,
-        });
-      } catch {
-        // 单个 service system 失败不应阻断 SDK session 主链路。
-      }
-    }
-    return out;
+  /**
+   * 返回实例级执行上下文。
+   */
+  getContext(): AgentContext {
+    return this.core.getContext();
   }
 
-  private createRuntime(): AgentRuntime {
-    const runtime = {
-      cwd: this.path,
-      rootPath: this.path,
-      logger: this.logger,
-      config: this.config,
-      env: {},
-      globalEnv: {},
-      systems: this.instruction,
-      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;
+  /**
+   * 启动当前 agent 的 HTTP server。
+   */
+  private async startHttp(
+    options?: AgentHttpStartOptions,
+  ): Promise<AgentHttpBinding> {
+    if (this.httpBinding) {
+      return this.httpBinding;
+    }
+    const host = String(options?.host || "127.0.0.1").trim() || "127.0.0.1";
+    const port =
+      typeof options?.port === "number" && Number.isInteger(options.port)
+        ? options.port
+        : 15314;
+    const server = await startServer({
+      host,
+      port,
+      core: this.core,
+    });
+    this.httpBinding = {
+      baseUrl: `http://${host}:${port}`,
+      host,
+      port,
+      server,
     };
-    return runtime as unknown as AgentRuntime;
+    return this.httpBinding;
   }
 
-  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.instruction,
-      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;
+  /**
+   * 停止当前 agent 的 HTTP server。
+   */
+  private async stopHttp(): Promise<void> {
+    if (!this.httpBinding) return;
+    const current = this.httpBinding;
+    this.httpBinding = null;
+    await current.server.stop();
   }
 
-  private getOrCreateSession(sessionId?: string): Session {
-    const resolvedSessionId =
-      String(sessionId || "").trim() || `session-${Date.now()}-${nanoid(8)}`;
-    const cached = this.sessionsById.get(resolvedSessionId);
-    if (cached) return cached;
-
-    const created = new Session({
-      agentId: this.id,
-      projectRoot: this.path,
-      sessionId: resolvedSessionId,
-      tools: this.tools,
-      logger: this.logger,
-      getInstructionSystemBlocks: () => this.loadInstructionSystemBlocks(),
-      getServiceSystemBlocks: () => this.loadServiceSystemBlocks(),
-      getPluginSystemBlocks: () => this.loadPluginSystemBlocks(),
+  /**
+   * 启动当前 agent 的本地 RPC server。
+   */
+  private async startRpc(): Promise<AgentRpcBinding> {
+    if (this.rpcBinding) {
+      return this.rpcBinding;
+    }
+    const server = await startLocalRpcServer({
+      core: this.core,
     });
-    this.sessionsById.set(resolvedSessionId, created);
-    return created;
+    this.rpcBinding = {
+      endpoint: server.endpoint,
+      server,
+    };
+    return this.rpcBinding;
+  }
+
+  /**
+   * 停止当前 agent 的本地 RPC server。
+   */
+  private async stopRpc(): Promise<void> {
+    if (!this.rpcBinding) return;
+    const current = this.rpcBinding;
+    this.rpcBinding = null;
+    await current.server.stop();
   }
 }