@downcity/agent 1.1.25 → 1.1.35

package/src/plugin/types/Plugin.ts

@@ -23,12 +23,121 @@ import type { DowncityConfig } from "@/types/config/DowncityConfig.js";
 import type { JsonObject, JsonValue } from "@/types/common/Json.js";
 import type { AuthRoutePolicy } from "@/types/runtime/auth/AuthRoute.js";
 
+/**
+ * Plugin 运行状态。
+ *
+ * 说明（中文）
+ * - `starting` / `stopping` 仅用于生命周期过渡态。
+ * - `error` 表示最近一次 lifecycle / command / action 执行失败后留下的状态标记。
+ */
+export type PluginState =
+  | "running"
+  | "stopped"
+  | "starting"
+  | "stopping"
+  | "error";
+
+/**
+ * 单个 plugin 实例内部持有的状态记录。
+ */
+export interface PluginStateRecord {
+  /**
+   * 当前运行状态。
+   */
+  state: PluginState;
+  /**
+   * 最近一次状态更新时间（毫秒时间戳）。
+   */
+  updatedAt: number;
+  /**
+   * 最近一次错误信息。
+   */
+  lastError?: string;
+  /**
+   * 最近一次执行的命令名。
+   */
+  lastCommand?: string;
+  /**
+   * 最近一次执行命令的时间（毫秒时间戳）。
+   */
+  lastCommandAt?: number;
+  /**
+   * 当前串行控制链。
+   */
+  chain: Promise<void>;
+}
+
+/**
+ * 单个 plugin 状态的对外快照。
+ */
+export interface PluginStateSnapshot {
+  /**
+   * plugin 名称。
+   */
+  name: string;
+  /**
+   * 当前运行状态。
+   */
+  state: PluginState;
+  /**
+   * 最近一次状态更新时间（毫秒时间戳）。
+   */
+  updatedAt: number;
+  /**
+   * 最近一次错误信息。
+   */
+  lastError?: string;
+  /**
+   * 最近一次执行的命令名。
+   */
+  lastCommand?: string;
+  /**
+   * 最近一次执行命令的时间（毫秒时间戳）。
+   */
+  lastCommandAt?: number;
+  /**
+   * 是否支持主动生命周期。
+   */
+  supportsLifecycle: boolean;
+  /**
+   * 是否支持 command/action。
+   */
+  supportsCommand: boolean;
+}
+
+/**
+ * plugin 状态控制动作。
+ */
+export type PluginStateControlAction =
+  | "start"
+  | "stop"
+  | "restart"
+  | "status";
+
+/**
+ * plugin 状态控制结果。
+ */
+export interface PluginStateControlResult {
+  /**
+   * 控制动作是否成功。
+   */
+  success: boolean;
+  /**
+   * 成功或失败后返回的最新 plugin 快照。
+   */
+  plugin?: PluginStateSnapshot;
+  /**
+   * 失败时的错误信息。
+   */
+  error?: string;
+}
+
 /**
  * Plugin 命令执行上下文。
  *
  * 关键点（中文）
  * - 这里表达的是“CLI 命令执行 plugin 时真正需要的最小上下文”。
- * - plugin 命令不应依赖 session、service invoke、agent runtime 等长期宿主对象。
+ * - plugin 命令不应依赖 session、plugin invoke、agent runtime 等长期宿主对象。
  * - agent runtime 在需要复用 action 时，直接传入自身更完整的 AgentContext 即可。
  */
 export interface PluginCommandContext {
@@ -71,13 +180,13 @@ export interface PluginCommandContext {
 }
 
 /**
- * Service 调用参数。
+ * Plugin action 调用参数。
  */
-export interface PluginServiceInvokeParams {
+export interface PluginActionInvokeParams {
   /**
-   * 目标 service 名称。
+   * 目标 plugin 名称。
    */
-  service: string;
+  plugin: string;
   /**
    * 目标 action 名称。
    */
@@ -89,9 +198,9 @@ export interface PluginServiceInvokeParams {
 }
 
 /**
- * Service 调用结果。
+ * Plugin action 调用结果。
  */
-export interface PluginServiceInvokeResult {
+export interface PluginActionInvokeResult {
   /**
    * 调用是否成功。
    */
@@ -107,15 +216,75 @@ export interface PluginServiceInvokeResult {
 }
 
 /**
- * Service 调用端口。
+ * Plugin action 调用端口。
  */
-export interface PluginServiceInvokePort {
+export interface PluginActionInvokePort {
   /**
-   * 调用指定 service action。
+   * 调用指定 plugin action。
    */
   invoke(
-    params: PluginServiceInvokeParams,
-  ): Promise<PluginServiceInvokeResult>;
+    params: PluginActionInvokeParams,
+  ): Promise<PluginActionInvokeResult>;
+}
+
+/**
+ * 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;
 }
 
 /**
@@ -430,7 +599,7 @@ export interface PluginAction<
     /**
      * 当前执行上下文。
      */
-    context: PluginCommandContext;
+    context: AgentContext;
     /**
      * 输入 payload。
      */
@@ -643,13 +812,13 @@ export interface PluginUsageDefinition {
 }
 
 /**
- * Plugin runtime HTTP 注入参数。
+ * Plugin HTTP 注入参数。
  *
  * 关键点（中文）
  * - plugin 只声明自己的路由与鉴权策略，不感知 server 装配细节。
  * - console 会复用相同路径策略保护代理请求，但不会重复注册路由本身。
  */
-export interface PluginRuntimeHttpRegistration {
+export interface PluginHttpRegistration {
   /**
    * 该组路由对应的鉴权策略列表。
    */
@@ -678,9 +847,9 @@ export interface PluginRuntimeHttpRegistration {
  */
 export interface PluginHttpDefinition {
   /**
-   * runtime HTTP 路由注入（可选）。
+   * server HTTP 路由注入（可选）。
    */
-  runtime?: PluginRuntimeHttpRegistration;
+  server?: PluginHttpRegistration;
 }
 
 /**
@@ -735,11 +904,15 @@ export interface Plugin {
    * Plugin system 文本构建器（可选）。
    */
   system?: (context: AgentContext) => string | Promise<string>;
+  /**
+   * 旧生命周期兼容定义（可选）。
+   */
+  lifecycle?: PluginLifecycle;
   /**
    * Plugin 可用性检查器（可选）。
    */
   availability?: (
-    context: PluginCommandContext,
+    context: PluginCommandContext | AgentContext,
   ) => Promise<PluginAvailability> | PluginAvailability;
   /**
    * Plugin HTTP 注入定义（可选）。

package/src/plugin/types/PluginApi.ts

@@ -1,5 +1,5 @@
 /**
- * plugin 管理命令与 API 类型。
+ * plugin catalog / availability / action API 类型。
  *
  * 关键点（中文）
  * - 统一描述 CLI -> daemon 的 plugin 管理协议。
@@ -73,9 +73,9 @@ export interface PluginAvailabilityView {
 }
 
 /**
- * plugin list 响应。
+ * plugin catalog 响应。
  */
-export interface PluginListResponse {
+export interface PluginCatalogResponse {
   /**
    * 请求是否成功。
    */

package/src/plugin/types/PluginSchedule.ts

@@ -0,0 +1,89 @@
+/**
+ * PluginSchedule：plugin action 调度相关共享类型。
+ */
+
+import type { JsonValue } from "@/types/common/Json.js";
+
+/**
+ * 调度任务状态。
+ */
+export type ScheduledJobStatus =
+  | "pending"
+  | "running"
+  | "succeeded"
+  | "failed"
+  | "cancelled";
+
+/**
+ * 调度任务完整记录。
+ */
+export interface ScheduledJobRecord {
+  /**
+   * 调度任务唯一 ID。
+   */
+  id: string;
+  /**
+   * 目标 plugin 名称。
+   */
+  pluginName: string;
+  /**
+   * 目标 action 名称。
+   */
+  actionName: string;
+  /**
+   * 原始 action payload。
+   */
+  payload: JsonValue;
+  /**
+   * 计划执行时间（毫秒时间戳）。
+   */
+  runAtMs: number;
+  /**
+   * 当前调度状态。
+   */
+  status: ScheduledJobStatus;
+  /**
+   * 最近一次错误文本。
+   */
+  error?: string;
+  /**
+   * 创建时间（毫秒时间戳）。
+   */
+  createdAt: number;
+  /**
+   * 最近更新时间（毫秒时间戳）。
+   */
+  updatedAt: number;
+}
+
+/**
+ * 创建调度任务所需输入。
+ */
+export interface CreateScheduledJobInput {
+  /**
+   * 目标 plugin 名称。
+   */
+  pluginName: string;
+  /**
+   * 目标 action 名称。
+   */
+  actionName: string;
+  /**
+   * 目标 action payload。
+   */
+  payload: JsonValue;
+  /**
+   * 计划执行时间（毫秒时间戳）。
+   */
+  runAtMs: number;
+}
+
+/**
+ * 统一 plugin command 调度输入。
+ */
+export interface PluginCommandScheduleInput {
+  /**
+   * 计划执行时间（毫秒时间戳）。
+   */
+  runAtMs: number;
+}

package/src/plugin/types/PluginState.ts

@@ -0,0 +1,11 @@
+/**
+ * PluginState：plugin 运行状态相关共享类型导出。
+ */
+
+export type {
+  PluginState,
+  PluginStateControlAction,
+  PluginStateControlResult,
+  PluginStateRecord,
+  PluginStateSnapshot,
+} from "@/plugin/types/Plugin.js";

package/src/plugin/types/Plugins.ts

@@ -0,0 +1,67 @@
+/**
+ * plugin 管理命令类型。
+ */
+
+import type { JsonValue } from "@/types/common/Json.js";
+
+export type PluginControlAction = "start" | "stop" | "restart" | "status";
+
+/**
+ * 单个 plugin 的对外状态视图。
+ */
+export type PluginStateView = {
+  /** plugin 稳定名称。 */
+  name: string;
+  /** 当前运行状态。 */
+  state: "running" | "stopped" | "starting" | "stopping" | "error";
+  /** 最近一次状态更新时间（毫秒时间戳）。 */
+  updatedAt: number;
+  /** 最近一次错误信息。 */
+  lastError?: string;
+  /** 最近一次执行的命令名称。 */
+  lastCommand?: string;
+  /** 最近一次执行命令的时间（毫秒时间戳）。 */
+  lastCommandAt?: number;
+  /** 当前 plugin 是否支持显式 start/stop 生命周期控制。 */
+  supportsLifecycle: boolean;
+  /** 当前 plugin 是否支持 command/action 调用。 */
+  supportsCommand: boolean;
+};
+
+/**
+ * plugin 状态列表响应。
+ */
+export type PluginStateListResponse = {
+  success: boolean;
+  plugins?: PluginStateView[];
+  error?: string;
+};
+
+/**
+ * plugin 生命周期控制响应。
+ */
+export type PluginControlResponse = {
+  success: boolean;
+  plugin?: PluginStateView;
+  error?: string;
+};
+
+/**
+ * plugin command/action 执行响应。
+ */
+export type PluginCommandResponse = {
+  success: boolean;
+  plugin?: PluginStateView;
+  message?: string;
+  data?: JsonValue;
+  error?: string;
+};
+
+export type PluginCliBaseOptions = {
+  path?: string;
+  agent?: string;
+  host?: string;
+  port?: number;
+  token?: string;
+  json?: boolean;
+};

package/src/runtime/host/AgentHostRuntime.ts

@@ -3,7 +3,7 @@
  *
  * 关键点（中文）
  * - agent runtime 负责创建这些宿主能力对象，再注入到 AgentRuntime。
- * - service / session / plugin 只消费这些对象，不直接依赖具体宿主实现。
+ * - plugin runtime / session / plugin 作者 API 只消费这些对象，不直接依赖具体宿主实现。
  * - 当前先收敛路径与 plugin 配置持久化两类宿主能力。
  */
 import {
@@ -28,10 +28,15 @@ import type { DowncityConfig } from "@/types/config/DowncityConfig.js";
 /**
  * 创建当前项目的路径能力集合。
  */
-export function createAgentPathRuntime(projectRoot: string): AgentPathRuntime {
+export function createAgentPathRuntime(
+  projectRoot: string,
+  agentIdInput: string,
+): AgentPathRuntime {
   const rootPath = String(projectRoot || "").trim();
+  const agentId = String(agentIdInput || "").trim();
   return {
     projectRoot: rootPath,
+    agentId,
     getDowncityDirPath: () => getDowncityDirPath(rootPath),
     getCacheDirPath: () => getCacheDirPath(rootPath),
     getDowncityChannelDirPath: () => getDowncityChannelDirPath(rootPath),
@@ -40,8 +45,9 @@ export function createAgentPathRuntime(projectRoot: string): AgentPathRuntime {
     getDowncityMemoryLongTermPath: () => getDowncityMemoryLongTermPath(rootPath),
     getDowncityMemoryDailyDirPath: () => getDowncityMemoryDailyDirPath(rootPath),
     getDowncityMemoryDailyPath: (date) => getDowncityMemoryDailyPath(rootPath, date),
-    getDowncitySessionRootDirPath: () => getDowncitySessionRootDirPath(rootPath),
-    getDowncitySessionDirPath: (sessionId) => getDowncitySessionDirPath(rootPath, sessionId),
+    getDowncitySessionRootDirPath: () => getDowncitySessionRootDirPath(rootPath, agentId),
+    getDowncitySessionDirPath: (sessionId) =>
+      getDowncitySessionDirPath(rootPath, agentId, sessionId),
   };
 }
 

package/src/runtime/host/daemon/Api.ts

@@ -3,7 +3,7 @@
  *
  * 关键点（中文）
  * - 这里描述的是 CLI 与 agent daemon 之间的远程访问契约，不包含具体 HTTP 实现。
- * - service 等上层模块只依赖这些协议类型，不需要感知 city/daemon 的内部实现细节。
+ * - plugin runtime 等上层模块只依赖这些协议类型，不需要感知 city/daemon 的内部实现细节。
  * - 该文件属于 agent daemon 访问协议边界，而不是通用 HTTP 类型目录。
  */
 
@@ -40,7 +40,7 @@ export type DaemonJsonApiCallParams = {
    *
    * 说明（中文）
    * - 仅本地 IPC transport 当前会消费该参数。
-   * - 用于 `session execute`、`service command` 这类可能持续几十秒的请求，
+   * - 用于 `session execute`、`plugin command` 这类可能持续几十秒的请求，
    *   避免被默认短超时误判成“Agent server 未启动”。
    */
   timeoutMs?: number;

package/src/runtime/host/daemon/ProjectSetup.ts

@@ -15,6 +15,7 @@ import {
 import type { AgentPlatformRuntime } from "@/types/runtime/host/AgentHost.js";
 import {
   getCacheDirPath,
+  getDowncityAgentsRootDirPath,
   getLogsDirPath,
   getProfileMdPath,
   getDowncityConfigDirPath,
@@ -24,7 +25,6 @@ import {
   getDowncityJsonPath,
   getDowncityProfileDirPath,
   getDowncityPublicDirPath,
-  getDowncitySessionRootDirPath,
   getDowncityTasksDirPath,
 } from "@/config/Paths.js";
 
@@ -59,7 +59,7 @@ function ensureShipDirectories(projectRoot: string): void {
   fs.ensureDirSync(getCacheDirPath(projectRoot));
   fs.ensureDirSync(getDowncityProfileDirPath(projectRoot));
   fs.ensureDirSync(getDowncityDataDirPath(projectRoot));
-  fs.ensureDirSync(getDowncitySessionRootDirPath(projectRoot));
+  fs.ensureDirSync(getDowncityAgentsRootDirPath(projectRoot));
   fs.ensureDirSync(getDowncityPublicDirPath(projectRoot));
   fs.ensureDirSync(getDowncityConfigDirPath(projectRoot));
   fs.ensureDirSync(path.join(getDowncityDirPath(projectRoot), "schema"));

package/src/runtime/sandbox/types/SandboxRuntime.ts

@@ -4,7 +4,7 @@
  * 关键点（中文）
  * - 这里放的是 agent 执行层内部使用的最小 sandbox 运行时类型。
  * - 当前只围绕 `SandboxRunner` 设计，不引入复杂 provider / policy / binding 对象。
- * - 目标是让 `ShellService` 可以直接把命令交给 `SandboxRunner` 执行。
+ * - 目标是让 shell plugin runtime 可以直接把命令交给 `SandboxRunner` 执行。
  */
 
 import type { ChildProcessWithoutNullStreams } from "node:child_process";

package/src/runtime/server/http/Server.ts

@@ -16,9 +16,6 @@ import { finished } from "node:stream/promises";
 import { logger as serverLogger } from "@/utils/logger/Logger.js";
 import { createExecuteRouter } from "@/runtime/server/http/execute/execute.js";
 import { healthRouter } from "@/runtime/server/http/health/health.js";
-import {
-  createServicesRouter,
-} from "@/runtime/server/http/services/services.js";
 import { createPluginsRouter } from "@/runtime/server/http/plugins/plugins.js";
 import { createStaticRouter } from "@/runtime/server/http/static/static.js";
 import { createControlRouter } from "@/runtime/server/http/control/ControlRouter.js";
@@ -28,7 +25,7 @@ import {
 } from "@/plugin/core/HttpRoutes.js";
 import type { AgentRuntime } from "@/core/AgentCoreTypes.js";
 import type { AgentContext } from "@/core/AgentContextTypes.js";
-import type { AgentCore } from "@/core/AgentCore.js";
+import type { AgentSessionCollection } from "@/sdk/AgentSdkTypes.js";
 
 /**
  * Server 启动参数。
@@ -38,12 +35,12 @@ export interface ServerStartOptions {
   port: number;
   /** HTTP 服务监听主机。 */
   host: string;
-  /** 可选实例级 agent core。 */
-  core?: Pick<AgentCore, "getContext" | "getRuntime" | "session" | "sessions">;
-  /** 可选实例级 runtime 读取函数。 */
-  getAgentRuntime?: () => AgentRuntime;
-  /** 可选实例级 context 读取函数。 */
-  getAgentContext?: () => AgentContext;
+  /** 当前 agent runtime 读取函数。 */
+  getAgentRuntime: () => AgentRuntime;
+  /** 当前 agent context 读取函数。 */
+  getAgentContext: () => AgentContext;
+  /** 可选 SDK Session 集合绑定。 */
+  sessionCollection?: AgentSessionCollection;
 }
 
 /**
@@ -58,41 +55,16 @@ export interface ServerInstance {
   stop(): Promise<void>;
 }
 
-type AgentServerBindings = {
-  getAgentRuntime: () => AgentRuntime;
-  getAgentContext: () => AgentContext;
-};
-
-function resolveServerBindings(options: Pick<
-  ServerStartOptions,
-  "core" | "getAgentRuntime" | "getAgentContext"
->): AgentServerBindings {
-  const core = options.core;
-  if (core) {
-    return {
-      getAgentRuntime: () => core.getRuntime(),
-      getAgentContext: () => core.getContext(),
-    };
-  }
-  if (options.getAgentRuntime && options.getAgentContext) {
-    return {
-      getAgentRuntime: options.getAgentRuntime,
-      getAgentContext: options.getAgentContext,
-    };
-  }
-  throw new Error(
-    "createServerApp/startServer requires either core or both getAgentRuntime/getAgentContext",
-  );
-}
-
 /**
  * 创建主 Hono 应用。
  */
 export function createServerApp(
-  options: Pick<ServerStartOptions, "core" | "getAgentRuntime" | "getAgentContext">,
+  options: Pick<
+    ServerStartOptions,
+    "getAgentRuntime" | "getAgentContext" | "sessionCollection"
+  >,
 ): Hono {
   const app = new Hono();
-  const bindings = resolveServerBindings(options);
 
   app.use("*", logger());
   app.use(
@@ -106,29 +78,25 @@ export function createServerApp(
 
   // 关键点（中文）：按路由域挂载，server 模块只保留装配职责。
   app.route("/", createStaticRouter({
-    getAgentRuntime: bindings.getAgentRuntime,
+    getAgentRuntime: options.getAgentRuntime,
   }));
   app.route("/", healthRouter);
-  const servicesRouter = createServicesRouter({
-    getAgentContext: bindings.getAgentContext,
-  });
-  app.route("/", servicesRouter);
   app.route("/", createPluginsRouter({
-    getAgentContext: bindings.getAgentContext,
+    getAgentContext: options.getAgentContext,
   }));
   app.route("/", createExecuteRouter({
-    getAgentRuntime: bindings.getAgentRuntime,
+    getAgentRuntime: options.getAgentRuntime,
   }));
   app.route("/", createControlRouter({
-    getAgentRuntime: bindings.getAgentRuntime,
-    getAgentContext: bindings.getAgentContext,
+    getAgentRuntime: options.getAgentRuntime,
+    getAgentContext: options.getAgentContext,
   }));
-  if (options.core) {
-    app.route("/", createSdkRouter(options.core));
+  if (options.sessionCollection) {
+    app.route("/", createSdkRouter(options.sessionCollection));
   }
   registerBuiltinPluginHttpRoutes({
     app,
-    getContext: bindings.getAgentContext,
+    getContext: options.getAgentContext,
   });
 
   return app;