@downcity/city 1.1.24 → 1.1.32

package/src/cli/model/ModelManagerTypes.ts

@@ -3,35 +3,117 @@
  */
 
 export type ModelManagerRootAction =
+  /**
+   * 进入 provider 管理列表。
+   */
   | "providers"
+  /**
+   * 进入 model 管理列表。
+   */
   | "models"
+  /**
+   * 跳转到创建流程。
+   */
   | "create"
+  /**
+   * 退出 manager。
+   */
   | "exit";
 
 export type ModelManagerProviderAction =
+  /**
+   * 查看 provider 详情。
+   */
   | "details"
+  /**
+   * 编辑 provider 配置。
+   */
+  | "edit"
+  /**
+   * 测试 provider 并导入发现到的模型。
+   */
   | "discover"
+  /**
+   * 删除 provider。
+   */
+  | "remove"
+  /**
+   * 返回上一层。
+   */
   | "back";
 
 export type ModelManagerModelAction =
+  /**
+   * 查看 model 详情。
+   */
   | "details"
+  /**
+   * 编辑 model 配置。
+   */
+  | "edit"
+  /**
+   * 切换暂停状态。
+   */
   | "togglePause"
+  /**
+   * 测试 model 可调用性。
+   */
   | "test"
+  /**
+   * 绑定到项目。
+   */
   | "use"
+  /**
+   * 删除 model。
+   */
+  | "remove"
+  /**
+   * 返回上一层。
+   */
   | "back";
 
 export interface ModelManagerProviderSummary {
+  /**
+   * provider 在全局模型池中的唯一 ID。
+   */
   id: string;
+  /**
+   * provider 类型，例如 `openai`、`anthropic`。
+   */
   type: string;
+  /**
+   * provider 自定义 base URL；为空表示使用 SDK 默认地址。
+   */
   baseUrl?: string;
+  /**
+   * 当前引用该 provider 的模型数量。
+   */
   modelCount: number;
 }
 
 export interface ModelManagerModelSummary {
+  /**
+   * model 在全局模型池中的唯一 ID。
+   */
   id: string;
+  /**
+   * 当前 model 绑定的 provider ID。
+   */
   providerId: string;
+  /**
+   * 上游真实模型名。
+   */
   name: string;
+  /**
+   * 当前 model 是否已暂停。
+   */
   isPaused: boolean;
+  /**
+   * 可选的 temperature 覆写；为空表示使用上游默认值。
+   */
   temperature?: number;
+  /**
+   * 可选的 maxTokens 覆写；为空表示使用上游默认值。
+   */
   maxTokens?: number;
 }

package/src/cli/model/ModelSupport.ts

@@ -181,7 +181,7 @@ export async function discoverProviderModels(params: {
   }
 }
 
-export { resolveProjectRoot } from "../service/ServiceCommandSupport.js";
+export { resolveProjectRoot } from "../shared/PluginTargetSupport.js";
 
 /**
  * 设置项目 `downcity.json.execution.modelId`。

package/src/cli/shared/Chat.ts

@@ -3,7 +3,7 @@
  *
  * 关键点（中文）
  * - 这里先注册裸 `city chat` 的交互式入口。
- * - 具体 service actions/lifecycle 命令仍由 service 注册器补充到同一个命令组。
+ * - 具体 plugin runtime actions/lifecycle 命令仍由 plugin runtime 注册器补充到同一个命令组。
  */
 
 import type { Command } from "commander";
@@ -16,7 +16,7 @@ import { runInteractiveChatManager } from "./ChatManager.js";
 export function registerChatCommand(program: Command): void {
   const chat = program
     .command("chat")
-    .description("管理 chat service（无参数时启动交互式管理器）")
+    .description("管理 chat plugin（无参数时启动交互式管理器）")
     .helpOption("--help", "display help for command")
     .action(async () => {
       if (process.stdin.isTTY === true && process.stdout.isTTY === true) {

package/src/cli/shared/ChatManager.ts

@@ -2,7 +2,7 @@
  * `city chat` 交互式管理器。
  *
  * 关键点（中文）
- * - 裸 `city chat` 进入 chat service 管理，而不是只输出静态 help。
+ * - 裸 `city chat` 进入 chat plugin 管理，而不是只输出静态 help。
  * - chat channel account 属于 city 级配置，在这里通过“配置 channel”管理。
  * - agent 只绑定 channel account，不在 agent 流程中维护密钥。
  */
@@ -10,11 +10,11 @@
 import prompts from "prompts";
 import type { PromptObject } from "prompts";
 import {
-  ChatChannelAccountService,
+  ChatChannelAccountManager,
   type ChatChannelAccountListItem,
 } from "@downcity/agent";
 import { emitCliBlock, emitCliList } from "./CliReporter.js";
-import { runServiceControlCommand } from "../service/ServiceCommandRemote.js";
+import { runManagedPluginControlCommand } from "./ManagedPluginRemote.js";
 import type { StoredChannelAccountChannel } from "@downcity/agent";
 import type {
   ChatChannelAccountAction,
@@ -25,8 +25,8 @@ import { createAgentPlatformRuntime } from "@/process/registry/AgentHostRuntime.
 
 const CHAT_CHANNELS: StoredChannelAccountChannel[] = ["telegram", "feishu", "qq"];
 
-function createChannelAccountService(): ChatChannelAccountService {
-  return new ChatChannelAccountService(createAgentPlatformRuntime());
+function createChannelAccountManager(): ChatChannelAccountManager {
+  return new ChatChannelAccountManager(createAgentPlatformRuntime());
 }
 
 function isInteractiveTerminal(): boolean {
@@ -49,31 +49,31 @@ function formatCredentialSummary(account: ChatChannelAccountListItem): string {
 }
 
 async function promptRootAction(): Promise<ChatManagerRootAction | null> {
-  const service = createChannelAccountService();
-  const accounts = await service.list();
+  const manager = createChannelAccountManager();
+  const accounts = await manager.list();
   const response = (await prompts({
     type: "select",
     name: "action",
-    message: "管理 chat service",
+    message: "管理 chat plugin",
     choices: [
       {
         title: "查看状态",
-        description: "查看当前项目 chat service 运行状态",
+        description: "查看当前项目 chat plugin 运行状态",
         value: "status",
       },
       {
         title: "启动",
-        description: "启动当前项目 chat service",
+        description: "启动当前项目 chat plugin",
         value: "start",
       },
       {
         title: "停止",
-        description: "停止当前项目 chat service",
+        description: "停止当前项目 chat plugin",
         value: "stop",
       },
       {
         title: "重启",
-        description: "重启当前项目 chat service",
+        description: "重启当前项目 chat plugin",
         value: "restart",
       },
       {
@@ -94,8 +94,8 @@ async function promptRootAction(): Promise<ChatManagerRootAction | null> {
 }
 
 async function promptChannelAccountAction(): Promise<ChatChannelAccountAction | null> {
-  const service = createChannelAccountService();
-  const accounts = await service.list();
+  const manager = createChannelAccountManager();
+  const accounts = await manager.list();
   const response = (await prompts({
     type: "select",
     name: "action",
@@ -128,7 +128,7 @@ async function promptChannelAccountAction(): Promise<ChatChannelAccountAction |
       },
       {
         title: "返回",
-        description: "回到 chat service 菜单",
+        description: "回到 chat plugin 菜单",
         value: "back",
       },
     ],
@@ -139,8 +139,8 @@ async function promptChannelAccountAction(): Promise<ChatChannelAccountAction |
 }
 
 async function emitChannelAccountList(): Promise<void> {
-  const service = createChannelAccountService();
-  const { items } = await service.list();
+  const manager = createChannelAccountManager();
+  const { items } = await manager.list();
   if (items.length === 0) {
     emitCliBlock({
       tone: "info",
@@ -182,8 +182,8 @@ async function chooseChannel(): Promise<StoredChannelAccountChannel | null> {
 }
 
 async function chooseAccount(): Promise<ChatChannelAccountListItem | null> {
-  const service = createChannelAccountService();
-  const { items } = await service.list();
+  const manager = createChannelAccountManager();
+  const { items } = await manager.list();
   if (items.length === 0) {
     emitCliBlock({
       tone: "info",
@@ -296,8 +296,8 @@ async function addChannelAccount(): Promise<void> {
     initial: true,
   })) as { probe?: boolean };
 
-  const service = createChannelAccountService();
-  const result = await service.create({
+  const manager = createChannelAccountManager();
+  const result = await manager.create({
     channel,
     name,
     botToken: input.botToken,
@@ -324,8 +324,8 @@ async function editChannelAccount(): Promise<void> {
     channel: account.channel,
     current: account,
   });
-  const service = createChannelAccountService();
-  await service.upsert({
+  const manager = createChannelAccountManager();
+  await manager.upsert({
     id: account.id,
     channel: account.channel,
     name: String(input.name || account.name).trim(),
@@ -356,8 +356,8 @@ async function removeChannelAccount(): Promise<void> {
 
   if (response.remove !== true) return;
 
-  const service = createChannelAccountService();
-  service.remove(account.id);
+  const manager = createChannelAccountManager();
+  await manager.remove(account.id);
   emitCliBlock({
     tone: "success",
     title: "Channel account removed",
@@ -403,8 +403,8 @@ async function runChannelAccountManager(): Promise<void> {
 async function runChatLifecycleAction(
   action: "start" | "stop" | "restart" | "status",
 ): Promise<void> {
-  await runServiceControlCommand({
-    serviceName: "chat",
+  await runManagedPluginControlCommand({
+    pluginName: "chat",
     action,
     options: {
       path: ".",

package/src/cli/shared/Config.ts

@@ -14,7 +14,7 @@ import { getDowncityJsonPath } from "@/config/Paths.js";
 import { printResult } from "@/utils/cli/CliOutput.js";
 import { aliasCommand } from "./Alias.js";
 import { parseBoolean } from "./IndexSupport.js";
-import { resolveProjectRoot } from "../service/ServiceCommandSupport.js";
+import { resolveProjectRoot } from "./PluginTargetSupport.js";
 import type { DowncityConfig } from "@downcity/agent";
 
 function isPlainObject(value: unknown): value is Record<string, unknown> {

package/src/cli/{service/ServiceActionCommands.ts → shared/ManagedPluginActionCommands.ts}

@@ -1,29 +1,29 @@
 /**
- * Service action CLI 注册器。
+ * 受 agent 托管的 plugin action CLI 注册器。
  *
  * 关键点（中文）
- * - 负责把 service actions 挂到 commander（`city <service> <action>`）。
- * - 仅处理 CLI 参数映射与远程调用，不承载 service 状态机逻辑。
- * - service 注册表与调度时间解析统一复用 agent 包实现，避免 city 维护第二套事实源。
+ * - 负责把需要运行中 agent 承载的 plugin actions 挂到 commander（`city <plugin> <action>`）。
+ * - 仅处理 CLI 参数映射与远程调用，不承载 plugin 状态机逻辑。
+ * - 命令注册表与调度时间解析统一复用 agent 包实现，避免 city 维护第二套事实源。
  */
 
 import path from "node:path";
 import type { Command } from "commander";
 import {
   callAgentTransport,
-  listRegisteredServices,
+  listManagedPlugins,
   parseScheduledRunAtMsOrThrow,
 } from "@downcity/agent";
-import type { Service, ServiceAction } from "@downcity/agent";
+import type { BasePlugin, PluginAction } from "@downcity/agent";
 import type { JsonObject, JsonValue } from "@downcity/agent";
-import type { ServiceCommandScheduleInput } from "@downcity/agent";
-import type { ServiceCommandResponse } from "@downcity/agent";
-import type { ServiceCliBaseOptions } from "@downcity/agent";
+import type { PluginCommandScheduleInput } from "@downcity/agent";
+import type { PluginCommandResponse } from "@downcity/agent";
+import type { PluginCliBaseOptions } from "@downcity/agent";
 import { printResult } from "@/utils/cli/CliOutput.js";
-import { parseBoolean, parsePort } from "../shared/IndexSupport.js";
-import { runServiceControlCommand } from "./ServiceCommandRemote.js";
+import { parseBoolean, parsePort } from "./IndexSupport.js";
+import { runManagedPluginControlCommand } from "./ManagedPluginRemote.js";
 
-const CHAT_SERVICE_HELP_TEXT = [
+const CHAT_PLUGIN_HELP_TEXT = [
   "",
   "Chat quick guide:",
   "  直接输出 assistant 文本会发送到当前 chat channel。",
@@ -40,7 +40,7 @@ const CHAT_SERVICE_HELP_TEXT = [
 
 const CHAT_HELP_HOOK_ATTACHED = Symbol("chat-help-hook-attached");
 
-type ServiceCliBridgeOptions = {
+type PluginCliBridgeOptions = {
   path?: string;
   host?: string;
   port?: number;
@@ -85,7 +85,7 @@ function toJsonValue(input: unknown): JsonValue | undefined {
   return undefined;
 }
 
-function toServiceActionCommandOpts(
+function toPluginActionCommandOpts(
   options: Record<string, unknown>,
 ): Record<string, JsonValue> {
   const reservedKeys = new Set(["path", "host", "port", "token", "json", "delay", "time"]);
@@ -99,9 +99,9 @@ function toServiceActionCommandOpts(
   return normalized;
 }
 
-function toServiceCliBridgeOptions(
+function toPluginCliBridgeOptions(
   options: Record<string, unknown>,
-): ServiceCliBridgeOptions {
+): PluginCliBridgeOptions {
   return {
     path: typeof options.path === "string" ? options.path : ".",
     host: typeof options.host === "string" ? options.host : undefined,
@@ -111,7 +111,7 @@ function toServiceCliBridgeOptions(
   };
 }
 
-function flattenServiceActionCommandArgs(values: unknown[]): string[] {
+function flattenPluginActionCommandArgs(values: unknown[]): string[] {
   const out: string[] = [];
   const pushValue = (value: unknown): void => {
     if (value === undefined || value === null) return;
@@ -160,7 +160,7 @@ function hasLongOption(command: Command, longFlag: string): boolean {
  */
 function extractCommandScheduleInput(
   options: Record<string, unknown>,
-): ServiceCommandScheduleInput | undefined {
+): PluginCommandScheduleInput | undefined {
   const runAtMs = parseScheduledRunAtMsOrThrow({
     delay: options.delay as string | number | undefined,
     time: options.time as string | number | undefined,
@@ -169,38 +169,38 @@ function extractCommandScheduleInput(
   return { runAtMs };
 }
 
-function registerServiceActionCommand(params: {
+function registerPluginActionCommand(params: {
   program: Command;
-  service: Service;
+  plugin: BasePlugin;
   actionName: string;
-  action: ServiceAction<JsonValue, JsonValue>;
+  action: PluginAction<JsonValue, JsonValue>;
 }): void {
   const commandSpec = params.action.command;
   if (!commandSpec) return;
 
-  const serviceCommand =
-    params.program.commands.find((item) => item.name() === params.service.name) ||
+  const pluginCommand =
+    params.program.commands.find((item) => item.name() === params.plugin.name) ||
     params.program
-      .command(params.service.name)
-      .description(`${params.service.name} service actions`)
+      .command(params.plugin.name)
+      .description(`${params.plugin.name} plugin actions`)
       .helpOption("--help", "display help for command");
 
   if (
-    params.service.name === "chat" &&
-    !(serviceCommand as Command & { [CHAT_HELP_HOOK_ATTACHED]?: boolean })[
+    params.plugin.name === "chat" &&
+    !(pluginCommand as Command & { [CHAT_HELP_HOOK_ATTACHED]?: boolean })[
       CHAT_HELP_HOOK_ATTACHED
     ]
   ) {
-    const chatCommand = serviceCommand as Command & {
+    const chatCommand = pluginCommand as Command & {
       [CHAT_HELP_HOOK_ATTACHED]?: boolean;
     };
     chatCommand.on("--help", () => {
-      console.log(CHAT_SERVICE_HELP_TEXT);
+      console.log(CHAT_PLUGIN_HELP_TEXT);
     });
     chatCommand[CHAT_HELP_HOOK_ATTACHED] = true;
   }
 
-  const actionCommand = serviceCommand
+  const actionCommand = pluginCommand
     .command(params.actionName)
     .description(commandSpec.description)
     .helpOption("--help", "display help for command")
@@ -212,12 +212,12 @@ function registerServiceActionCommand(params: {
 
   commandSpec.configure?.(actionCommand);
   if (!hasLongOption(actionCommand, "--delay")) {
-    actionCommand.option("--delay <ms>", "延迟执行毫秒数（所有 service action 通用）");
+    actionCommand.option("--delay <ms>", "延迟执行毫秒数（所有 plugin action 通用）");
   }
   if (!hasLongOption(actionCommand, "--time")) {
     actionCommand.option(
       "--time <time>",
-      "定时执行时间（Unix 时间戳秒/毫秒或 ISO 时间，所有 service action 通用）",
+      "定时执行时间（Unix 时间戳秒/毫秒或 ISO 时间，所有 plugin action 通用）",
     );
   }
 
@@ -225,7 +225,7 @@ function registerServiceActionCommand(params: {
     const last = rawArgs.at(-1);
     const commandLike = isCommanderCommandLike(last) ? last : null;
     const positionalArgs = commandLike
-      ? flattenServiceActionCommandArgs(
+      ? flattenPluginActionCommandArgs(
           Array.isArray(commandLike.processedArgs)
             ? (commandLike.processedArgs as unknown[])
             : [],
@@ -235,7 +235,7 @@ function registerServiceActionCommand(params: {
           const fallbackPositional = isPlainOptionsObject(fallbackLast)
             ? rawArgs.slice(0, -1)
             : rawArgs;
-          return flattenServiceActionCommandArgs(fallbackPositional);
+          return flattenPluginActionCommandArgs(fallbackPositional);
         })();
     const allOptions = commandLike
       ? ((commandLike.opts() as Record<string, unknown>) || {})
@@ -243,16 +243,16 @@ function registerServiceActionCommand(params: {
           const fallbackLast = rawArgs.at(-1);
           return isPlainOptionsObject(fallbackLast) ? fallbackLast : {};
         })();
-    const actionOptions = toServiceActionCommandOpts(allOptions);
-    const bridgeOptions = toServiceCliBridgeOptions(allOptions);
-    let schedule: ServiceCommandScheduleInput | undefined;
+    const actionOptions = toPluginActionCommandOpts(allOptions);
+    const bridgeOptions = toPluginCliBridgeOptions(allOptions);
+    let schedule: PluginCommandScheduleInput | undefined;
     try {
       schedule = extractCommandScheduleInput(allOptions);
     } catch (error) {
       printResult({
         asJson: bridgeOptions.json,
         success: false,
-        title: `${params.service.name}.${params.actionName} failed`,
+        title: `${params.plugin.name}.${params.actionName} failed`,
         payload: {
           error: `Failed to parse schedule input: ${String(error)}`,
         },
@@ -270,7 +270,7 @@ function registerServiceActionCommand(params: {
       printResult({
         asJson: bridgeOptions.json,
         success: false,
-        title: `${params.service.name}.${params.actionName} failed`,
+        title: `${params.plugin.name}.${params.actionName} failed`,
         payload: {
           error: `Failed to parse command input: ${String(error)}`,
         },
@@ -278,15 +278,15 @@ function registerServiceActionCommand(params: {
       return;
     }
 
-    const remote = await callAgentTransport<ServiceCommandResponse>({
+    const remote = await callAgentTransport<PluginCommandResponse>({
       projectRoot: resolveProjectRoot(bridgeOptions.path),
-      path: "/api/services/command",
+      path: "/api/plugins/command",
       method: "POST",
       host: bridgeOptions.host,
       port: bridgeOptions.port,
       authToken: bridgeOptions.token,
       body: {
-        serviceName: params.service.name,
+        pluginName: params.plugin.name,
         command: params.actionName,
         payload,
         ...(schedule ? { schedule } : {}),
@@ -299,8 +299,8 @@ function registerServiceActionCommand(params: {
         asJson: bridgeOptions.json,
         success: Boolean(data.success),
         title: data.success
-          ? `${params.service.name}.${params.actionName} ok`
-          : `${params.service.name}.${params.actionName} failed`,
+          ? `${params.plugin.name}.${params.actionName} ok`
+          : `${params.plugin.name}.${params.actionName} failed`,
         payload: {
           ...(data.data !== undefined ? { data: data.data } : {}),
           ...(data.message ? { message: data.message } : {}),
@@ -313,7 +313,7 @@ function registerServiceActionCommand(params: {
     printResult({
       asJson: bridgeOptions.json,
       success: false,
-      title: `${params.service.name}.${params.actionName} failed`,
+      title: `${params.plugin.name}.${params.actionName} failed`,
       payload: {
         error: remote.error || "Unknown error",
       },
@@ -321,11 +321,11 @@ function registerServiceActionCommand(params: {
   });
 }
 
-function hasServiceSubcommand(command: Command, name: string): boolean {
+function hasPluginSubcommand(command: Command, name: string): boolean {
   return command.commands.some((item) => item.name() === name);
 }
 
-function attachServiceLifecycleOptions(command: Command): Command {
+function attachPluginLifecycleOptions(command: Command): Command {
   return command
     .option("--path <path>", "项目根目录（默认当前目录）", ".")
     .option("--host <host>", "Server host（覆盖自动解析）")
@@ -334,57 +334,57 @@ function attachServiceLifecycleOptions(command: Command): Command {
     .option("--json [enabled]", "以 JSON 输出", parseBoolean, true);
 }
 
-function registerServiceLifecycleCommands(params: {
+function registerPluginLifecycleCommands(params: {
   program: Command;
-  service: Service;
+  plugin: BasePlugin;
 }): void {
-  if (!params.service.lifecycle?.start && !params.service.lifecycle?.stop) {
+  if (!params.plugin.lifecycle?.start && !params.plugin.lifecycle?.stop) {
     return;
   }
 
-  const serviceCommand =
-    params.program.commands.find((item) => item.name() === params.service.name) ||
+  const pluginCommand =
+    params.program.commands.find((item) => item.name() === params.plugin.name) ||
     params.program
-      .command(params.service.name)
-      .description(`${params.service.name} service actions`)
+      .command(params.plugin.name)
+      .description(`${params.plugin.name} plugin actions`)
       .helpOption("--help", "display help for command");
 
   const lifecycleCommands = [
     {
       name: "start",
-      description: `启动 ${params.service.name} service`,
+      description: `启动 ${params.plugin.name} plugin`,
       action: "start" as const,
     },
     {
       name: "stop",
-      description: `停止 ${params.service.name} service`,
+      description: `停止 ${params.plugin.name} plugin`,
       action: "stop" as const,
     },
     {
       name: "restart",
-      description: `重启 ${params.service.name} service`,
+      description: `重启 ${params.plugin.name} plugin`,
       action: "restart" as const,
     },
     {
       name: "status",
-      description: `查看 ${params.service.name} service 运行状态`,
+      description: `查看 ${params.plugin.name} plugin 运行状态`,
       action: "status" as const,
     },
   ];
 
   for (const item of lifecycleCommands) {
-    if (hasServiceSubcommand(serviceCommand, item.name)) {
+    if (hasPluginSubcommand(pluginCommand, item.name)) {
       continue;
     }
 
-    attachServiceLifecycleOptions(
-      serviceCommand
+    attachPluginLifecycleOptions(
+      pluginCommand
         .command(item.name)
         .description(item.description)
         .helpOption("--help", "display help for command"),
-    ).action(async (options: ServiceCliBaseOptions) => {
-      await runServiceControlCommand({
-        serviceName: params.service.name,
+    ).action(async (options: PluginCliBaseOptions) => {
+      await runManagedPluginControlCommand({
+        pluginName: params.plugin.name,
         action: item.action,
         options,
       });
@@ -393,24 +393,24 @@ function registerServiceLifecycleCommands(params: {
 }
 
 /**
- * 注册所有 service actions 的 CLI 命令。
+ * 注册所有受 agent 托管的 plugin actions CLI 命令。
  */
-export function registerAllServicesForCli(program: Command): void {
-  const services = listRegisteredServices();
-  for (const service of services) {
-    for (const [actionName, action] of Object.entries(service.actions)) {
-      registerServiceActionCommand({
+export function registerManagedPluginCommandsForCli(program: Command): void {
+  const plugins = listManagedPlugins();
+  for (const plugin of plugins) {
+    for (const [actionName, action] of Object.entries(plugin.actions)) {
+      registerPluginActionCommand({
         program,
-        service,
+        plugin,
         actionName,
-        action,
+        action: action as PluginAction<JsonValue, JsonValue>,
       });
     }
   }
-  for (const service of services) {
-    registerServiceLifecycleCommands({
+  for (const plugin of plugins) {
+    registerPluginLifecycleCommands({
       program,
-      service,
+      plugin,
     });
   }
 }