@downcity/city 1.1.4 → 1.1.5

package/src/cli/agent/Stop.ts

@@ -0,0 +1,45 @@
+/**
+ * `city agent stop`：停止后台常驻的 Agent 进程（daemon）。
+ *
+ * 关键点（中文）
+ * - 这是单个 agent 的生命周期命令，只停止目标项目的 daemon。
+ * - 底层 stop 会同步清理 pid/meta，并把 city registry 中对应 agent 标记为 stopped。
+ * - 若目标 agent 未运行，命令保持幂等，只输出 not running。
+ */
+
+import path from "path";
+import { stopDaemonProcess } from "@/process/daemon/Manager.js";
+import { emitCliBlock } from "../shared/CliReporter.js";
+import { resolveAgentName } from "../shared/IndexSupport.js";
+
+/**
+ * stop 命令执行流程。
+ *
+ * 关键点（中文）
+ * 1) 将输入路径解析为绝对项目路径
+ * 2) 调用 daemon manager 停止进程组
+ * 3) 用人类可读 block 输出 stopped / not running
+ */
+export async function stopCommand(cwd: string = "."): Promise<void> {
+  const projectRoot = path.resolve(cwd);
+  const result = await stopDaemonProcess({ projectRoot });
+  emitCliBlock({
+    tone: result.stopped ? "success" : "info",
+    title: result.stopped ? "Agent daemon stopped" : "Agent daemon not running",
+    summary: resolveAgentName(projectRoot),
+    facts: [
+      {
+        label: "Project",
+        value: projectRoot,
+      },
+      ...(result.pid
+        ? [
+            {
+              label: "PID",
+              value: String(result.pid),
+            },
+          ]
+        : []),
+    ],
+  });
+}

package/src/cli/control-plane/ControlPlaneAuthBootstrap.ts

@@ -0,0 +1,72 @@
+/**
+ * control plane 启动阶段的本机 token 初始化辅助。
+ *
+ * 关键点（中文）
+ * - `city start` 首次启动时，如果还没有本机 CLI access token，这里负责初始化首个 token。
+ * - 新模型不再要求用户名密码登录，也不再做交互式密码提示。
+ * - 一旦本机 token 已存在，本模块直接跳过，不会重复打断启动流程。
+ * - 启动流程不再写入任何本机默认 token 状态，只显示一次明文 token。
+ */
+
+import { AuthService } from "@/http/auth/AuthService.js";
+import { emitCliBlock } from "../shared/CliReporter.js";
+
+const DEFAULT_CONTROL_PLANE_BOOTSTRAP_TOKEN_NAME = "control-plane-bootstrap";
+
+/**
+ * control plane 启动期统一账户初始化参数。
+ */
+export interface EnsureControlPlaneAuthBootstrapOptions {
+  /**
+   * 可选注入外部 AuthService，便于测试。
+   */
+  authService?: AuthService;
+
+  readPassword?: () => Promise<string>;
+}
+
+/**
+ * 确保平台级至少存在一个本机 access token。
+ */
+export async function ensureControlPlaneAuthBootstrap(
+  options: EnsureControlPlaneAuthBootstrapOptions = {},
+): Promise<void> {
+  const authService = options.authService || new AuthService();
+  const ownsAuthService = !options.authService;
+  try {
+    if (authService.hasLocalCliAccess()) {
+      return;
+    }
+
+    const payload = authService.ensureLocalCliAccess({
+      tokenName: DEFAULT_CONTROL_PLANE_BOOTSTRAP_TOKEN_NAME,
+    });
+
+    emitCliBlock({
+      tone: "success",
+      title: "Control plane token initialized",
+      summary: payload.user.username,
+      facts: [
+        {
+          label: "Subject",
+          value: payload.user.username,
+        },
+        {
+          label: "Name",
+          value: payload.token.name,
+        },
+        {
+          label: "Token",
+          value: payload.token.token,
+        },
+        {
+          label: "Next",
+          value: "把上面的 Bearer Token 粘贴到控制面 UI / Extension",
+        },
+      ],
+      note: "明文 token 只会在本次初始化时显示一次。",
+    });
+  } finally {
+    if (ownsAuthService) authService.close();
+  }
+}

package/src/cli/control-plane/ControlPlaneCommand.ts

@@ -0,0 +1,216 @@
+/**
+ * CLI city/control-plane 命令装配。
+ *
+ * 关键点（中文）
+ * - 这里的 `console` 更接近 city gateway / control plane 的运维入口，而不是单 agent API。
+ * - 统一管理 top-level city 生命周期命令与 control plane 模块命令。
+ * - 本文件只保留命令树装配；runtime 与状态细节已拆到辅助模块。
+ */
+
+import { Command, Option } from "commander";
+import {
+  getControlPlaneRuntimeStatus,
+  restartControlPlaneCommand,
+  runControlPlaneRuntimeCommand,
+  startControlPlaneCommand,
+  stopControlPlaneCommand,
+} from "./ControlPlaneRuntime.js";
+import { registerConfigCommand } from "../shared/Config.js";
+import { registerModelCommand } from "../model/Model.js";
+import { controlPlaneInitCommand } from "./ControlPlaneInit.js";
+import { parseBoolean, parsePort, createVersionBanner } from "../shared/IndexSupport.js";
+import { CliError } from "../shared/CliError.js";
+import { updateCommand } from "../shared/Update.js";
+import {
+  controlPlaneStatusCommand,
+  printControlPlaneStatusPanel,
+} from "./ControlPlaneStatus.js";
+import {
+  prepareForegroundAgent,
+  ensureRegisteredAgentProjectRoot,
+  restartCityRuntimeCommand,
+  runCityRuntimeCommand,
+  startCityRuntimeCommand,
+  stopCityRuntimeCommand,
+} from "./ControlPlaneProcess.js";
+
+/**
+ * top-level city/control-plane 命令注册参数。
+ */
+export interface ControlPlaneCommandRegistrationContext {
+  /** 当前 CLI 版本号。 */
+  version: string;
+  /** 当前 CLI 入口文件绝对路径。 */
+  cliPath: string;
+}
+
+/**
+ * 注册 top-level city 生命周期命令与 `console` 模块命令。
+ *
+ * 语义说明（中文）
+ * - `city ...` / `city console ...` 管的是平台控制面进程。
+ * - 单 agent 控制能力统一留在 `@downcity/agent` 暴露的 runtime / HTTP control API。
+ */
+export function registerControlPlaneCommands(
+  program: Command,
+  context: ControlPlaneCommandRegistrationContext,
+): void {
+  program
+    .command("init")
+    .description("初始化 city 全局配置（模型/插件等，写入 ~/.downcity/downcity.db）")
+    .helpOption("--help", "display help for command")
+    .action(createVersionBanner(context.version, async () => {
+      await controlPlaneInitCommand();
+    }));
+
+  program
+    .command("start")
+    .description("启动 city runtime；使用 -a/--all、--console 或 -p/--public 可同时启动 Console")
+    .option("-a, --all", "同时启动 Console")
+    .option("--console", "同时启动 Console")
+    .option("-p, --public [enabled]", "以公网模式启动 Console（绑定 0.0.0.0）", parseBoolean)
+    .option("-h, --host <host>", "Console 主机；传入后默认同时启动 Console")
+    .helpOption("--help", "display help for command")
+    .action(createVersionBanner(context.version, async (
+      _options: { all?: boolean; console?: boolean; public?: boolean; host?: string },
+      command: Command,
+    ) => {
+      const options = command.opts<{
+        all?: boolean;
+        console?: boolean;
+        public?: boolean;
+        host?: string;
+      }>();
+      const shouldStartConsole =
+        options?.all === true ||
+        options?.console === true ||
+        options?.public === true ||
+        Boolean(String(options?.host || "").trim());
+      await startCityRuntimeCommand(context.cliPath);
+      if (shouldStartConsole) {
+        await startControlPlaneCommand({
+          options: {
+            public: options?.public,
+            host: options?.host,
+          },
+          cliPath: context.cliPath,
+        });
+      }
+    }));
+
+  program
+    .command("stop")
+    .description("停止 CITY（先停 Console，再停 city 后台与受管 agent）")
+    .helpOption("--help", "display help for command")
+    .action(createVersionBanner(context.version, async () => {
+      await stopCityRuntimeCommand();
+    }));
+
+  program
+    .command("restart")
+    .description("重启 CITY（重启 city 后台并恢复已运行 agent，再拉起 Console）")
+    .helpOption("--help", "display help for command")
+    .action(createVersionBanner(context.version, async () => {
+      await restartCityRuntimeCommand(context.cliPath);
+      await startControlPlaneCommand({
+        cliPath: context.cliPath,
+      });
+    }));
+
+  program
+    .command("status")
+    .description("查看 city 后台、Console 与已托管 agent 运行状态")
+    .helpOption("--help", "display help for command")
+    .action(createVersionBanner(context.version, async () => {
+      await controlPlaneStatusCommand();
+    }));
+
+  program
+    .command("update")
+    .description("更新全局 downcity CLI 到最新版本")
+    .option("--manager <manager>", "指定包管理器（npm|pnpm|auto）", "auto")
+    .helpOption("--help", "display help for command")
+    .action(createVersionBanner(context.version, async (
+      _options: { manager?: string },
+      command: Command,
+    ) => {
+      const options = command.opts<{ manager?: string }>();
+      const manager = String(options.manager || "auto").trim().toLowerCase();
+      if (manager !== "auto" && manager !== "npm" && manager !== "pnpm") {
+        throw new CliError({
+          title: `Invalid manager: ${manager}`,
+          fix: "Use npm|pnpm|auto.",
+        });
+      }
+      await updateCommand({
+        manager: manager as "auto" | "npm" | "pnpm",
+      });
+    }));
+
+  program
+    .command("run", { hidden: true })
+    .description("city 内部运行时（不直接使用）")
+    .action(runCityRuntimeCommand);
+
+  const consoleCommand = program
+    .command("console [action]")
+    .description("管理控制面模块（命令名保留为 console；start/stop/restart/status，默认 start）")
+    .option("-p, --public [enabled]", "以公网模式启动控制面（绑定 0.0.0.0）", parseBoolean)
+    .option("-h, --host <host>", "控制面主机（默认 127.0.0.1）")
+    .addOption(new Option("--port <port>").argParser(parsePort).hideHelp())
+    .helpOption("--help", "display help for command");
+
+  consoleCommand
+    .action(
+      createVersionBanner(
+        context.version,
+        async (
+          action: string | undefined,
+          _options: { public?: boolean; host?: string; port?: number },
+          command: Command,
+        ) => {
+          const options = command.opts<{ public?: boolean; host?: string; port?: number }>();
+          const resolvedAction = String(action || "start").trim().toLowerCase();
+          if (resolvedAction === "start") {
+            await startControlPlaneCommand({
+              options,
+              cliPath: context.cliPath,
+            });
+            return;
+          }
+          if (resolvedAction === "run") {
+            await runControlPlaneRuntimeCommand(options);
+            return;
+          }
+          if (resolvedAction === "stop") {
+            await stopControlPlaneCommand();
+            return;
+          }
+          if (resolvedAction === "restart") {
+            await restartControlPlaneCommand({
+              options,
+              cliPath: context.cliPath,
+            });
+            return;
+          }
+          if (resolvedAction === "status") {
+            const status = await getControlPlaneRuntimeStatus();
+            printControlPlaneStatusPanel(status);
+            return;
+          }
+          throw new CliError({
+            title: `Unknown action: ${resolvedAction}`,
+            fix: "Use start|stop|restart|status.",
+          });
+        },
+      ),
+    );
+
+  registerConfigCommand(program);
+  registerModelCommand(program);
+}
+
+export {
+  ensureRegisteredAgentProjectRoot,
+  prepareForegroundAgent,
+};

package/src/cli/control-plane/ControlPlaneInit.ts

@@ -0,0 +1,83 @@
+/**
+ * `city init`：初始化平台级默认配置（`~/.downcity/`）。
+ *
+ * 生成内容
+ * - `~/.downcity/downcity.db`：平台级全局配置存储（敏感字段加密）
+ * - `~/.downcity/schema/downcity.schema.json`：给项目 downcity.json 的 schema（可选）
+ *
+ * 关键点（中文）
+ * - city 运行时是强依赖：`city start` + `city agent start` 都会使用这里的默认配置。
+ * - 平台级配置不再使用 `~/.downcity/downcity.json` 和 `~/.downcity/.env`。
+ * - agent 项目内 `downcity.json/.env` 仍保持项目级配置职责。
+ */
+
+import path from "node:path";
+import fs from "fs-extra";
+import { DOWNCITY_JSON_SCHEMA } from "@/config/DowncitySchema.js";
+import { saveJson } from "@/utils/storage.js";
+import {
+  getPlatformRootDirPath,
+} from "@/process/registry/CityPaths.js";
+import { PlatformStore } from "@downcity/agent";
+import { emitCliBlock, emitCliList } from "../shared/CliReporter.js";
+
+/**
+ * 平台初始化入口。
+ */
+export async function controlPlaneInitCommand(): Promise<void> {
+  const operationRoot = getPlatformRootDirPath();
+  const schemaDir = path.join(operationRoot, "schema");
+  const schemaPath = path.join(schemaDir, "downcity.schema.json");
+
+  await fs.ensureDir(operationRoot);
+
+  // 写入 schema（给编辑器使用）
+  await fs.ensureDir(schemaDir);
+  await saveJson(schemaPath, DOWNCITY_JSON_SCHEMA);
+
+  const modelStore = new PlatformStore();
+  let existingModelsCount = 0;
+  try {
+    existingModelsCount = modelStore.listModels().length;
+    emitCliBlock({
+      tone: "success",
+      title: "Platform base initialized",
+      facts: [
+        {
+          label: "Root",
+          value: operationRoot,
+        },
+        {
+          label: "Schema",
+          value: schemaPath,
+        },
+        {
+          label: "Existing models",
+          value: String(existingModelsCount),
+        },
+      ],
+      note:
+        existingModelsCount > 0
+          ? "检测到已有模型池。`city init` 不会修改模型配置。"
+          : "当前还没有模型池。你可以稍后执行 `city model create` 配置模型。",
+    });
+  } finally {
+    modelStore.close();
+  }
+  emitCliBlock({
+    tone: "success",
+    title: "Platform initialized",
+    summary: "base-only",
+    note: "基础设施已初始化。下一步可执行 `city model create` 配置模型。",
+  });
+  emitCliList({
+    tone: "accent",
+    title: "Created",
+    items: [
+      { title: "encrypted platform settings" },
+      { title: "downcity schema" },
+    ],
+  });
+
+  // 关键点（中文）：skills 仅使用 `~/.agents/skills`，不做 built-in / claude 自动同步。
+}