@downcity/agent 1.1.174 → 1.1.178

package/src/plugin/core/PluginStateController.ts

@@ -1,144 +1,29 @@
 /**
- * PluginStateController：主动型 plugin 状态控制与状态记录模块。
+ * Plugin 注册状态兼容控制模块。
+ *
+ * 关键点（中文）
+ * - 新模型中 plugin 只有注册 / 卸载，不再暴露 start / stop / restart。
+ * - 该模块保留旧内部函数名，方便 RPC、CLI 与内建 plugin 渐进迁移。
  */
 
 import type { AgentContext } from "@/types/runtime/agent/AgentContext.js";
 import type {
-  PluginLifecycle,
-  PluginState,
   PluginStateControlAction,
   PluginStateControlResult,
-  PluginStateRecord,
   PluginStateSnapshot,
 } from "@/plugin/types/Plugin.js";
-import type { BasePlugin } from "@/plugin/core/BasePlugin.js";
-
-function nowMs(): number {
-  return Date.now();
-}
-
-function resolveLifecycle(plugin: BasePlugin): PluginLifecycle | undefined {
-  return plugin.lifecycle;
-}
-
-/**
- * 列出当前进程内可见的主动型 plugin 实例。
- */
-export function listPluginInstances(input?: {
-  context?: AgentContext;
-}): BasePlugin[] {
-  const contextPlugins = input?.context?.pluginInstances;
-  if (contextPlugins instanceof Map && contextPlugins.size > 0) {
-    return [...contextPlugins.values()];
-  }
-  return [];
-}
-
-/**
- * 按名称解析主动型 plugin 实例。
- */
-export function resolvePluginByName(
-  name: string,
-  input?: {
-    context?: AgentContext;
-  },
-): BasePlugin | null {
-  const key = String(name || "").trim();
-  if (!key) return null;
-  return listPluginInstances(input).find((plugin) => plugin.name === key) || null;
-}
-
-/**
- * 确保 plugin 对应的状态记录存在。
- */
-export function ensurePluginStateRecord(
-  plugin: BasePlugin,
-): PluginStateRecord {
-  return plugin.pluginStateRecord;
-}
-
-function hasCommandActions(plugin: BasePlugin): boolean {
-  return Object.values(plugin.actions).some((action) => Boolean(action.command));
-}
-
-/**
- * 把内部 record 映射为对外快照。
- */
-export function toPluginStateSnapshot(
-  record: PluginStateRecord,
-  plugin: BasePlugin,
-): PluginStateSnapshot {
-  const lifecycle = resolveLifecycle(plugin);
-  return {
-    name: plugin.name,
-    state: record.state,
-    updatedAt: record.updatedAt,
-    ...(record.lastError ? { lastError: record.lastError } : {}),
-    ...(record.lastCommand ? { lastCommand: record.lastCommand } : {}),
-    ...(typeof record.lastCommandAt === "number"
-      ? { lastCommandAt: record.lastCommandAt }
-      : {}),
-    supportsLifecycle: Boolean(lifecycle?.start || lifecycle?.stop),
-    supportsCommand: Boolean(lifecycle?.command) || hasCommandActions(plugin),
-  };
-}
-
-async function runSerialByPlugin(
-  record: PluginStateRecord,
-  step: () => Promise<void> | void,
-): Promise<void> {
-  const next = record.chain.then(() => Promise.resolve(step()));
-  record.chain = next.then(
-    () => undefined,
-    () => undefined,
-  );
-  await next;
-}
-
-/**
- * 标记 plugin 当前状态。
- */
-export function markPluginState(
-  record: PluginStateRecord,
-  state: PluginState,
-  error?: string,
-): void {
-  record.state = state;
-  record.updatedAt = nowMs();
-  if (error) {
-    record.lastError = error;
-    return;
-  }
-  delete record.lastError;
-}
 
 /**
- * 标记最近一次 plugin command。
- */
-export function markPluginCommand(
-  record: PluginStateRecord,
-  command: string,
-): void {
-  record.lastCommand = command;
-  record.lastCommandAt = nowMs();
-  record.updatedAt = nowMs();
-}
-
-/**
- * 列出全部主动型 plugin 状态快照。
+ * 列出当前 Agent 已注册 plugin 快照。
  */
 export function listPluginStates(input?: {
   context?: AgentContext;
 }): PluginStateSnapshot[] {
-  return listPluginInstances(input)
-    .map((plugin) =>
-      toPluginStateSnapshot(ensurePluginStateRecord(plugin), plugin),
-    )
-    .sort((a, b) => a.name.localeCompare(b.name));
+  return input?.context?.plugins.snapshots() || [];
 }
 
 /**
- * 判断指定主动型 plugin 是否处于运行中。
+ * 判断指定 plugin 是否已注册且 ready。
  */
 export function isPluginRunning(
   pluginName: string,
@@ -146,154 +31,79 @@ export function isPluginRunning(
     context?: AgentContext;
   },
 ): boolean {
-  const plugin = resolvePluginByName(pluginName, input);
-  if (!plugin) return false;
-  return ensurePluginStateRecord(plugin).state === "running";
-}
-
-async function startPluginInternal(
-  plugin: BasePlugin,
-  context: AgentContext,
-): Promise<PluginStateControlResult> {
-  const record = ensurePluginStateRecord(plugin);
-  const lifecycle = resolveLifecycle(plugin);
-  try {
-    await runSerialByPlugin(record, async () => {
-      if (record.state === "running") return;
-      markPluginState(record, "starting");
-      try {
-        await lifecycle?.start?.(context);
-        markPluginState(record, "running");
-      } catch (error) {
-        markPluginState(record, "error", String(error));
-        throw error;
-      }
-    });
-    return {
-      success: true,
-      plugin: toPluginStateSnapshot(record, plugin),
-    };
-  } catch (error) {
-    return {
-      success: false,
-      plugin: toPluginStateSnapshot(record, plugin),
-      error: String(error),
-    };
-  }
-}
-
-async function stopPluginInternal(
-  plugin: BasePlugin,
-  context: AgentContext,
-): Promise<PluginStateControlResult> {
-  const record = ensurePluginStateRecord(plugin);
-  const lifecycle = resolveLifecycle(plugin);
-  try {
-    await runSerialByPlugin(record, async () => {
-      if (record.state === "stopped") return;
-      markPluginState(record, "stopping");
-      try {
-        await lifecycle?.stop?.(context);
-        markPluginState(record, "stopped");
-      } catch (error) {
-        markPluginState(record, "error", String(error));
-        throw error;
-      }
-    });
-    return {
-      success: true,
-      plugin: toPluginStateSnapshot(record, plugin),
-    };
-  } catch (error) {
-    return {
-      success: false,
-      plugin: toPluginStateSnapshot(record, plugin),
-      error: String(error),
-    };
-  }
+  return input?.context?.plugins.status(pluginName)?.status === "ready";
 }
 
 /**
- * 执行单个主动型 plugin 状态控制动作。
+ * 执行兼容 plugin 控制动作。
  */
 export async function controlPluginState(params: {
   pluginName: string;
   action: PluginStateControlAction;
   context: AgentContext;
 }): Promise<PluginStateControlResult> {
-  const plugin = resolvePluginByName(params.pluginName, {
-    context: params.context,
-  });
-  if (!plugin) {
+  const pluginName = String(params.pluginName || "").trim();
+  if (!pluginName) {
     return {
       success: false,
-      error: `Unknown plugin: ${params.pluginName}`,
+      error: "pluginName is required",
     };
   }
 
-  if (params.action === "status") {
-    const record = ensurePluginStateRecord(plugin);
-    return {
-      success: true,
-      plugin: toPluginStateSnapshot(record, plugin),
-    };
-  }
-
-  if (params.action === "start") {
-    return await startPluginInternal(plugin, params.context);
+  const action = String(params.action || "").trim().toLowerCase();
+  if (action === "status" || action === "start" || action === "restart") {
+    const plugin = params.context.plugins.status(pluginName);
+    return plugin
+      ? { success: true, plugin }
+      : { success: false, error: `Unknown plugin: ${pluginName}` };
   }
 
-  if (params.action === "stop") {
-    return await stopPluginInternal(plugin, params.context);
+  if (action === "unregister" || action === "stop") {
+    const plugin = params.context.plugins.status(pluginName) || undefined;
+    const success = await params.context.plugins.unregister(pluginName);
+    return success
+      ? { success: true, ...(plugin ? { plugin } : {}) }
+      : { success: false, error: `Unknown plugin: ${pluginName}` };
   }
 
-  const stopResult = await stopPluginInternal(plugin, params.context);
-  if (!stopResult.success) return stopResult;
-  return await startPluginInternal(plugin, params.context);
+  return {
+    success: false,
+    error: `Unsupported plugin control action: ${params.action}`,
+  };
 }
 
 /**
- * 启动当前上下文中全部主动型 plugin。
+ * 启动当前上下文中全部已挂载 plugin。
  */
 export async function startAllPlugins(context: AgentContext): Promise<{
   success: boolean;
   results: PluginStateControlResult[];
 }> {
-  const results: PluginStateControlResult[] = [];
-  for (const plugin of listPluginInstances({ context })) {
-    results.push(
-      await controlPluginState({
-        pluginName: plugin.name,
-        action: "start",
-        context,
-      }),
-    );
-  }
+  const snapshots = await context.plugins.startAll();
   return {
-    success: results.every((item) => item.success),
-    results,
+    success: snapshots.every((item) => item.status === "ready"),
+    results: snapshots.map((plugin) => ({
+      success: plugin.status === "ready",
+      plugin,
+      ...(plugin.last_error ? { error: plugin.last_error } : {}),
+    })),
   };
 }
 
 /**
- * 停止当前上下文中全部主动型 plugin。
+ * 卸载当前上下文中全部 plugin。
  */
 export async function stopAllPlugins(context: AgentContext): Promise<{
   success: boolean;
   results: PluginStateControlResult[];
 }> {
-  const results: PluginStateControlResult[] = [];
-  for (const plugin of listPluginInstances({ context })) {
-    results.push(
-      await controlPluginState({
-        pluginName: plugin.name,
-        action: "stop",
-        context,
-      }),
-    );
-  }
+  const snapshots = context.plugins.snapshots();
+  await context.plugins.unregisterAll();
   return {
-    success: results.every((item) => item.success),
-    results,
+    success: true,
+    results: snapshots.map((plugin) => ({
+      success: true,
+      plugin,
+    })),
   };
 }

package/src/plugin/types/Plugin.ts

@@ -10,7 +10,8 @@ export type {
   PluginState,
   PluginStateControlAction,
   PluginStateControlResult,
-  PluginStateRecord,
+  PluginRuntimeRecord,
+  PluginSnapshot,
   PluginStateSnapshot,
 } from "@/types/plugin/PluginState.js";
 export type {

package/src/plugin/types/PluginState.ts

@@ -6,6 +6,7 @@ export type {
   PluginState,
   PluginStateControlAction,
   PluginStateControlResult,
-  PluginStateRecord,
+  PluginRuntimeRecord,
+  PluginSnapshot,
   PluginStateSnapshot,
 } from "@/types/plugin/PluginState.js";

package/src/plugin/types/Plugins.ts

@@ -4,7 +4,7 @@
 
 import type { JsonValue } from "@/types/common/Json.js";
 
-export type PluginControlAction = "start" | "stop" | "restart" | "status";
+export type PluginControlAction = "status" | "unregister";
 
 /**
  * 单个 plugin 的对外状态视图。
@@ -12,20 +12,20 @@ export type PluginControlAction = "start" | "stop" | "restart" | "status";
 export type PluginStateView = {
   /** plugin 稳定名称。 */
   name: string;
-  /** 当前运行状态。 */
-  state: "running" | "stopped" | "starting" | "stopping" | "error";
-  /** 最近一次状态更新时间（毫秒时间戳）。 */
+  /** 当前注册状态。 */
+  state: "ready" | "error";
+  /** 当前注册状态。 */
+  status: "ready" | "error";
+  /** 注册时间（毫秒时间戳）。 */
+  registered_at: number;
+  /** 最近更新时间（毫秒时间戳）。 */
+  updated_at: number;
+  /** 兼容旧字段的最近一次状态更新时间。 */
   updatedAt: number;
   /** 最近一次错误信息。 */
   lastError?: string;
-  /** 最近一次执行的命令名称。 */
-  lastCommand?: string;
-  /** 最近一次执行命令的时间（毫秒时间戳）。 */
-  lastCommandAt?: number;
-  /** 当前 plugin 是否支持显式 start/stop 生命周期控制。 */
-  supportsLifecycle: boolean;
-  /** 当前 plugin 是否支持 command/action 调用。 */
-  supportsCommand: boolean;
+  /** 最近一次错误信息。 */
+  last_error?: string;
 };
 
 /**

package/src/session/services/SessionStateService.ts

@@ -196,9 +196,7 @@ export class SessionStateService {
   async ensure_runnable(): Promise<void> {
     await this.ensure_ready_for_execution();
     if (!this.state.sessionConfig.model) {
-      throw new Error(
-        `Session "${this.session_id}" requires a configured model. Pass model to new Agent({ model }) or call session.set({ model }) first.`,
-      );
+      throw new Error("requires a configured model.");
     }
   }
 

package/src/types/agent/AgentOptions.ts

@@ -8,8 +8,9 @@
 
 import type { Tool } from "ai";
 import type { Shell } from "@downcity/shell";
-import type { BasePlugin } from "@/plugin/core/BasePlugin.js";
+import type { Plugin } from "@/types/plugin/PluginDefinition.js";
 import type { AgentModel } from "@/model/CityModelAdapter.js";
+import type { DowncityConfig } from "@/types/config/DowncityConfig.js";
 import type {
   AgentManagedSession,
   SessionOptions,
@@ -84,12 +85,12 @@ export interface AgentOptions {
    * 当前 agent 显式持有的插件实例集合。
    *
    * 关键点（中文）
-   * - 这里接收已经实例化好的 `BasePlugin` 对象，而不是 plugin class。
+   * - 这里接收已经创建好的 `Plugin` 对象，而不是 plugin class。
    * - `Agent` 会在构造阶段按名称注册这些实例，并自动绑定到当前 runtime。
    * - 同名 plugin 会直接报错，避免 action / hook / resolve 行为被静默覆盖。
    * - SDK 不再自动注入任何 built-in plugin；需要的能力都应由宿主显式传入。
    */
-  plugins?: BasePlugin[];
+  plugins?: Plugin[];
 
   /**
    * 当前 agent 使用的本地 Session 类。
@@ -110,4 +111,13 @@ export interface AgentOptions {
    * - 覆盖后的最终 env 会参与配置解析与运行时上下文装配，但不会回写到宿主环境。
    */
   env?: Record<string, string>;
+
+  /**
+   * 宿主显式传入的运行时配置。
+   *
+   * 关键点（中文）
+   * - SDK 不要求项目目录存在 `downcity.json`。
+   * - CLI / Console 可从自己的配置存储读取后传入这里。
+   */
+  config?: DowncityConfig;
 }

package/src/types/agent/AgentRuntimeAssembly.ts

@@ -68,7 +68,7 @@ export interface AgentPathRuntime {
  */
 export interface AgentPluginConfigRuntime {
   /**
-   * 将当前 `plugins` 配置块写回项目 `downcity.json`。
+   * 将当前 `plugins` 配置块写回宿主配置存储。
    */
   persistProjectPlugins(plugins: DowncityConfig["plugins"] | undefined): Promise<string>;
 }

package/src/types/config/AgentProject.ts

@@ -7,7 +7,6 @@
  */
 
 import type { ExecutionBindingConfig } from "@/types/config/ExecutionBinding.js";
-import type { DowncityConfig } from "@/types/config/DowncityConfig.js";
 
 /**
  * 可选的 chat channel 标识。
@@ -28,7 +27,7 @@ export interface AgentProjectInitializationInput {
    *
    * 关键点（中文）
    * - 为空时会自动回退到目录名推导出的默认 id。
-   * - 该字段会直接写入 `downcity.json.id`。
+   * - CLI 可把该字段写入自己的全局配置存储。
    */
   id?: string;
 
@@ -40,26 +39,14 @@ export interface AgentProjectInitializationInput {
    */
   execution: ExecutionBindingConfig;
 
-  /**
-   * 需要一并写入项目的 plugin 配置补丁。
-   *
-   * 说明（中文）
-   * - 这里只承载初始化时的最小配置，不负责 city 级 plugin lifecycle。
-   */
-  plugins?: DowncityConfig["plugins"];
-
   /**
    * 需要启用的 chat channels。
    *
    * 关键点（中文）
-   * - 仅写入用户选择的渠道，未选择的渠道不会写入 `downcity.json`。
+   * - SDK 初始化器只返回选择结果，不负责配置持久化。
    */
   channels?: AgentProjectChannel[];
 
-  /**
-   * 是否允许覆盖已存在的 `downcity.json`。
-   */
-  forceOverwriteShipJson?: boolean;
 }
 
 /**
@@ -81,6 +68,11 @@ export interface AgentProjectInitializationResult {
    */
   channels: AgentProjectChannel[];
 
+  /**
+   * 最终选择的 City AIService 模型 ID。
+   */
+  modelId?: string;
+
   /**
    * 本次实际创建/写入的文件列表。
    */

package/src/types/plugin/PluginRuntime.ts

@@ -13,6 +13,9 @@ import type {
 import type { JsonValue } from "@/types/common/Json.js";
 import type { PluginActionResult } from "@/types/plugin/PluginAction.js";
 import type { PluginActionExample } from "@/types/plugin/PluginAction.js";
+import type { Plugin } from "@/types/plugin/PluginDefinition.js";
+import type { AgentSessionSystemBlock } from "@/types/agent/AgentTypes.js";
+import type { PluginSnapshot } from "@/types/plugin/PluginState.js";
 
 /**
  * Plugin 概览视图。
@@ -80,9 +83,9 @@ export interface PluginReadView {
  * Plugin 可用性结果。
  */
 export interface PluginAvailability {
-  /** Plugin 是否启用。 */
+  /** Plugin 是否已注册。 */
   enabled: boolean;
-  /** Plugin 当前是否可用。 */
+  /** Plugin 当前环境是否可用。 */
   available: boolean;
   /** 不可用原因列表。 */
   reasons: string[];
@@ -92,6 +95,22 @@ export interface PluginAvailability {
  * 当前 Agent 可用的 plugin 调用面。
  */
 export interface AgentPlugins {
+  /** 注册或替换一个 plugin。 */
+  register(plugin: Plugin): Promise<PluginSnapshot>;
+  /** 卸载一个 plugin。 */
+  unregister(pluginName: string): Promise<boolean>;
+  /** 启动全部已挂载 plugin lifecycle。 */
+  startAll(): Promise<PluginSnapshot[]>;
+  /** 卸载全部 plugin。 */
+  unregisterAll(): Promise<void>;
+  /** 判断 plugin 是否已注册。 */
+  has(pluginName: string): boolean;
+  /** 读取单个 plugin 定义。 */
+  get(pluginName: string): Plugin | null;
+  /** 读取单个 plugin 注册快照。 */
+  status(pluginName: string): PluginSnapshot | null;
+  /** 列出全部已注册 plugin 快照。 */
+  snapshots(): PluginSnapshot[];
   /** 列出全部已注册 plugin。 */
   list(): PluginView[];
   /** 读取 plugin / action metadata。 */
@@ -112,6 +131,8 @@ export interface AgentPlugins {
     /** Action Payload（可选）。 */
     payload?: JsonValue;
   }): Promise<PluginActionResult<JsonValue>>;
+  /** 读取当前生效的 plugin system blocks。 */
+  systemBlocks(): Promise<AgentSessionSystemBlock[]>;
   /** 运行 pipeline 点，按顺序链式变换值。 */
   pipeline<T = JsonValue>(pointName: string, value: T): Promise<T>;
   /** 运行 guard 点；任一插件抛错即终止。 */