@downcity/city 1.1.1 → 1.1.5

package/src/cli/agent/Init.ts

@@ -0,0 +1,291 @@
+/**
+ * `city agent create`：在目标目录生成最小可用的 Downcity 工程骨架与配置文件。
+ *
+ * 目标
+ * - 生成 `PROFILE.md` / `SOUL.md` / `downcity.json` / `.downcity/` 目录结构与 schema 文件
+ * - 通过交互式问题收集必要配置（模型、channels 等）
+ *
+ * 设计要点
+ * - Chat channels 支持多选：仅写入用户选择的 channels（未选择的不出现在 `downcity.json`）
+ * - 避免写入无意义的默认值：能省则省，保持配置简洁
+ */
+
+import path from "path";
+import os from "os";
+import prompts from "prompts";
+import fs from "fs-extra";
+import fg from "fast-glob";
+import { getProfileMdPath, getDowncityJsonPath, getSoulMdPath } from "@/config/Paths.js";
+import {
+  initializeAgentProject,
+  listPlatformModelChoices,
+  normalizeDefaultAgentName,
+} from "@downcity/agent";
+import type { AgentProjectChannel } from "@downcity/agent";
+import type { ExecutionBindingConfig } from "@downcity/agent";
+import { emitCliBlock, emitCliList } from "../shared/CliReporter.js";
+import { CliError } from "../shared/CliError.js";
+
+type InitPromptResponse = {
+  name?: string;
+  primaryModelId?: string;
+  channels?: string[];
+};
+
+
+/**
+ * init 命令入口。
+ *
+ * 流程（中文）
+ * 1) 校验项目目录与覆盖策略
+ * 2) 交互收集配置
+ * 3) 生成配置与目录
+ * 4) 生成最小可运行结构（skills 目录仅创建，不做自动同步/安装）
+ */
+export async function initCommand(
+  cwd: string = ".",
+  options: { force?: boolean } = {},
+): Promise<void> {
+  const projectRoot = path.resolve(cwd);
+  const projectBaseName = path.basename(projectRoot);
+  const defaultAgentName =
+    normalizeDefaultAgentName(projectBaseName) || projectBaseName;
+  let allowOverwrite = Boolean(options.force);
+
+  emitCliBlock({
+    tone: "accent",
+    title: "Initializing agent project",
+    facts: [
+      {
+        label: "Project",
+        value: projectRoot,
+      },
+    ],
+  });
+
+  // Check if core initialization files already exist
+  const existingProfileMd = fs.existsSync(getProfileMdPath(projectRoot));
+  const existingSoulMd = fs.existsSync(getSoulMdPath(projectRoot));
+  const existingShipJson = fs.existsSync(getDowncityJsonPath(projectRoot));
+  const platformModelChoices = await listPlatformModelChoices();
+  const platformModelIds = platformModelChoices.map((item) => item.value);
+
+  // 关键点（中文）：已存在的 PROFILE.md 永远不覆盖，只在 downcity.json 已存在时询问覆盖。
+  if (existingShipJson) {
+    if (!allowOverwrite) {
+      const confirmResponse = (await prompts({
+        type: "confirm",
+        name: "overwrite",
+        message:
+          "downcity.json already exists. Overwrite existing downcity.json and continue?",
+        initial: false,
+      })) as { overwrite?: boolean };
+
+      if (!confirmResponse.overwrite) {
+        emitCliBlock({
+          tone: "info",
+          title: "Initialization cancelled",
+        });
+        return;
+      }
+      allowOverwrite = true;
+    }
+  }
+
+  // Collect configuration information
+  // 交互采集（中文）：agent name + model + channels。
+  const response = (await prompts([
+    {
+      type: "text",
+      name: "name",
+      message: "Agent name",
+      initial: defaultAgentName,
+    },
+    {
+      type: "select",
+      name: "primaryModelId",
+      message: "Select primary model (from platform model pool)",
+      choices: platformModelChoices,
+      initial: 0,
+    },
+    {
+      // 关键交互: Chat channels 允许多选，未选择的就不写入 downcity.json
+      type: "multiselect",
+      name: "channels",
+      message: "Select chat channels (multi-select)",
+      choices: [
+        { title: "Telegram", value: "telegram" },
+        { title: "Feishu", value: "feishu" },
+        { title: "QQ", value: "qq" },
+      ],
+    },
+  ])) as InitPromptResponse;
+
+  // 关键点（中文）：agent_name 同时用于 `downcity.json.name` 与 init 模板变量渲染，避免两处来源不一致。
+  const agentName =
+    String(response.name || "").trim() || defaultAgentName;
+  const primaryModelId =
+    String(response.primaryModelId || "").trim() || "default";
+  if (platformModelIds.length === 0) {
+    throw new CliError({
+      title: "Platform model pool is empty",
+      note: "Please configure at least one model first.",
+      fix: "city model create",
+    });
+  }
+  const execution: ExecutionBindingConfig = {
+    type: "api",
+    modelId: primaryModelId,
+  };
+  const selectedChannels = Array.isArray(response.channels)
+    ? (response.channels as AgentProjectChannel[])
+    : [];
+  const initResult = await initializeAgentProject({
+    projectRoot,
+    agentName,
+    execution,
+    channels: selectedChannels,
+    forceOverwriteShipJson: allowOverwrite,
+  });
+
+  const createdItems: string[] = [];
+  const skippedItems: string[] = [];
+  if (!existingProfileMd && initResult.createdFiles.includes("PROFILE.md")) {
+    createdItems.push("PROFILE.md");
+  } else if (existingProfileMd) {
+    skippedItems.push("PROFILE.md");
+  }
+  if (!existingSoulMd && initResult.createdFiles.includes("SOUL.md")) {
+    createdItems.push("SOUL.md");
+  } else if (existingSoulMd) {
+    skippedItems.push("SOUL.md");
+  }
+  createdItems.push("downcity.json", ".downcity/", "downcity.schema.json");
+  skippedItems.push(".env", ".env.example");
+
+  emitCliBlock({
+    tone: "success",
+    title: "Initialization complete",
+    summary: agentName,
+  });
+  emitCliList({
+    tone: "accent",
+    title: "Created",
+    items: createdItems.map((item) => ({ title: item })),
+  });
+  emitCliList({
+    tone: "info",
+    title: "Skipped",
+    items: skippedItems.map((item) => ({ title: item })),
+  });
+  if (primaryModelId) {
+    emitCliBlock({
+      tone: "info",
+      title: "Execution",
+      summary: "api",
+      facts: [
+        {
+          label: "Model ID",
+          value: primaryModelId,
+        },
+        {
+          label: "Source",
+          value: "~/.downcity/downcity.db",
+        },
+      ],
+    });
+  }
+
+  const channelItems: Array<{ title: string; facts: Array<{ label: string; value: string }> }> = [];
+  if (selectedChannels.includes("feishu")) {
+    channelItems.push({
+      title: "feishu",
+      facts: [
+        {
+          label: "Bind",
+          value: "services.chat.channels.feishu.channelAccountId",
+        },
+        {
+          label: "Manage",
+          value: "Console > Global / Channel Accounts",
+        },
+      ],
+    });
+  }
+  if (selectedChannels.includes("telegram")) {
+    channelItems.push({
+      title: "telegram",
+      facts: [
+        {
+          label: "Bind",
+          value: "services.chat.channels.telegram.channelAccountId",
+        },
+        {
+          label: "Manage",
+          value: "Console > Global / Channel Accounts",
+        },
+      ],
+    });
+  }
+  if (selectedChannels.includes("qq")) {
+    channelItems.push({
+      title: "qq",
+      facts: [
+        {
+          label: "Bind",
+          value: "services.chat.channels.qq.channelAccountId",
+        },
+        {
+          label: "Manage",
+          value: "Console > Global / Channel Accounts",
+        },
+      ],
+    });
+  }
+  if (channelItems.length > 0) {
+    emitCliList({
+      tone: "accent",
+      title: "Channels",
+      items: channelItems,
+    });
+  }
+
+  const nextSteps: string[] = [
+    "Edit PROFILE.md to customize agent behavior",
+    "Edit SOUL.md to customize your core operating principles",
+    "Edit downcity.json.execution to adjust execution target",
+  ];
+  if (primaryModelId) {
+    nextSteps.push("Edit downcity.json.execution.modelId (bind to console API model id)");
+    nextSteps.push('Use "city model ..." to manage global model pool');
+  }
+
+  if (selectedChannels.includes("telegram")) {
+    nextSteps.push(
+      "Bind services.chat.channels.telegram.channelAccountId to an existing channel account",
+    );
+  }
+  if (selectedChannels.includes("feishu")) {
+    nextSteps.push(
+      "Bind services.chat.channels.feishu.channelAccountId to an existing channel account",
+    );
+  }
+  if (selectedChannels.includes("qq")) {
+    nextSteps.push(
+      "Bind services.chat.channels.qq.channelAccountId to an existing channel account",
+    );
+  }
+  nextSteps.push('Run "city agent start" to start the agent');
+
+  emitCliList({
+    tone: "accent",
+    title: "Next steps",
+    items: nextSteps.map((line, idx) => ({
+      title: `${idx + 1}. ${line}`,
+    })),
+  });
+  emitCliBlock({
+    tone: "info",
+    title: "Tip",
+  });
+}

package/src/cli/agent/Restart.ts

@@ -0,0 +1,68 @@
+/**
+ * `city agent restart`：重启后台常驻的 Agent 进程（daemon）。
+ *
+ * 关键点（中文）
+ * - 这是 `start` / `stop` 之间的组合命令，不直接复用 shell 层面的进程替换。
+ * - 重启前必须重新校验项目初始化状态与 execution binding，避免先停后起失败。
+ * - 成功后会重新生成 daemon 元信息与日志路径，确保运行态与当前配置一致。
+ */
+
+import path from "path";
+import { fileURLToPath } from "url";
+import { buildRunArgsFromOptions } from "@/process/daemon/CliArgs.js";
+import { startDaemonProcess, stopDaemonProcess } from "@/process/daemon/Manager.js";
+import type { StartOptions } from "@downcity/agent";
+import { emitCliBlock } from "../shared/CliReporter.js";
+import { resolveAgentName } from "../shared/IndexSupport.js";
+import { checkAgentPreflight } from "../service/ServiceCommandSupport.js";
+import { CliError } from "../shared/CliError.js";
+
+/**
+ * restart 命令执行流程。
+ *
+ * 关键点（中文）
+ * 1) 统一预检（项目初始化 + binding）
+ * 2) 停止旧 daemon
+ * 3) 按当前参数重建启动参数并拉起新 daemon
+ */
+export async function restartCommand(
+  cwd: string = ".",
+  options: StartOptions,
+): Promise<void> {
+  const projectRoot = path.resolve(cwd);
+
+  // 关键点（中文）：统一预检（restart 不强制要求 city runtime running，因为 stop 后可能已停）。
+  await checkAgentPreflight(projectRoot, { requireCityRunning: false });
+
+  // 计算当前 CLI 的入口路径（编译后是 `bin/main/modules/cli/Index.js`）。
+  const __filename = fileURLToPath(import.meta.url);
+  const __dirname = path.dirname(__filename);
+  const cliPath = path.resolve(__dirname, "../Index.js");
+
+  try {
+    await stopDaemonProcess({ projectRoot });
+    const args = await buildRunArgsFromOptions(projectRoot, options || {});
+    await startDaemonProcess({
+      projectRoot,
+      cliPath,
+      args,
+    });
+
+    emitCliBlock({
+      tone: "success",
+      title: "Agent daemon restarted",
+      summary: resolveAgentName(projectRoot),
+      facts: [
+        {
+          label: "Project",
+          value: projectRoot,
+        },
+      ],
+    });
+  } catch (error) {
+    throw new CliError({
+      title: "Failed to restart daemon",
+      note: error instanceof Error ? error.message : String(error),
+    });
+  }
+}

package/src/cli/agent/Run.ts

@@ -0,0 +1,148 @@
+/**
+ * 前台启动 Agent 进程（当前终端进程内运行）。
+ *
+ * 场景
+ * - `city agent start --foreground` 走这里（当前终端前台运行）
+ * - daemon 子进程也复用这里作为真正运行入口
+ *
+ * 说明
+ * - 后台常驻启动请使用 `downcity agent start`，并用
+ *   `downcity agent restart` 管理。
+ */
+
+import {
+  getAgentContext,
+  getAgentRuntime,
+  initAgentRuntime,
+  startAllServices,
+  startLocalRpcServer,
+  startServer,
+  startServiceScheduleRuntime,
+  stopAgentHotReload,
+  stopAllServices,
+  stopServiceScheduleRuntime,
+} from "@downcity/agent";
+import type { StartOptions } from "@downcity/agent";
+import { logger } from "@downcity/agent";
+import { CliError } from "../shared/CliError.js";
+
+/**
+ * 前台启动入口（由 `agent start` 前台模式与内部 daemon 子进程复用）。
+ *
+ * 职责（中文）
+ * - 初始化 agent 状态（配置、日志、services 依赖）
+ * - 解析并合并启动参数（CLI > downcity.json > 默认值）
+ * - 启动主 HTTP 服务
+ * - 启动 services（例如 task cron）
+ * - 统一处理进程信号并优雅停机
+ */
+export async function runCommand(
+  cwd: string = ".",
+  options: StartOptions,
+): Promise<void> {
+  // 初始化加载（进程级单例状态：root / config / logger / chat / agents 等）
+  await initAgentRuntime(cwd);
+  // 端口解析（中文）：允许 number / string；空值返回 undefined 以便走配置回退链。
+  const parsePort = (
+    value: string | number | undefined,
+    label: string,
+  ): number | undefined => {
+    if (value === undefined || value === null || value === "") return undefined;
+    const num =
+      typeof value === "number" ? value : Number.parseInt(String(value), 10);
+    if (!Number.isFinite(num) || Number.isNaN(num)) {
+      throw new Error(`${label} must be a number`);
+    }
+    if (!Number.isInteger(num) || num <= 0 || num > 65535) {
+      throw new Error(`${label} must be an integer between 1 and 65535`);
+    }
+    return num;
+  };
+  // Resolve startup options: CLI flags override built-in defaults.
+  let port: number;
+  try {
+    port = parsePort(options.port, "port") ?? 5314;
+  } catch (error) {
+    throw new CliError({
+      title: "Invalid start options",
+      note: error instanceof Error ? error.message : String(error),
+    });
+  }
+
+  const host = (options.host ?? "0.0.0.0").trim();
+
+  process.env.DC_SERVER_PORT = String(port);
+  process.env.DC_SERVER_HOST = host;
+
+  // Create and start server
+  const server = await startServer({
+    port,
+    host,
+  });
+  const localRpc = await startLocalRpcServer({
+    context: getAgentContext(),
+    runtime: getAgentRuntime(),
+  });
+
+  // 处理进程信号
+  // 停机顺序（中文）：services -> API server -> flush logs。
+  let isShuttingDown = false;
+  const shutdown = async (signal: string) => {
+    if (isShuttingDown) return;
+    isShuttingDown = true;
+
+    logger.info(`Received ${signal} signal, shutting down...`);
+
+    // 先停掉文件监听，避免关停阶段触发额外重载。
+    stopAgentHotReload();
+
+    // 先停持久化调度器，避免关停过程中继续触发新的 service action。
+    try {
+      await stopServiceScheduleRuntime();
+    } catch {
+      // ignore
+    }
+
+    // 停止全部 service
+    try {
+      await stopAllServices(getAgentContext());
+    } catch {
+      // ignore
+    }
+
+    // 停止服务器
+    await localRpc.stop();
+    await server.stop();
+
+    // Save logs
+    await logger.saveAllLogs();
+
+    logger.info("👋 Downcity stopped");
+    process.exit(0);
+  };
+
+  process.on("SIGINT", () => shutdown("SIGINT"));
+  process.on("SIGTERM", () => shutdown("SIGTERM"));
+
+  // 启动全部 service（含 task cron 等模块内生命周期逻辑）
+  // 调度策略（中文）：单服务失败不阻断主服务启动，仅记录日志。
+  try {
+    const lifecycle = await startAllServices(getAgentContext());
+    for (const item of lifecycle.results) {
+      if (item.success) continue;
+      logger.error(
+        `Service start failed: ${item.service?.name || "unknown"} - ${item.error || "unknown error"}`,
+      );
+    }
+  } catch (e) {
+    logger.error(`Service bootstrap failed: ${String(e)}`);
+  }
+
+  try {
+    await startServiceScheduleRuntime(getAgentContext());
+  } catch (e) {
+    logger.error(`Service schedule runtime bootstrap failed: ${String(e)}`);
+  }
+
+  logger.info("=== Downcity Started ===");
+}

package/src/cli/agent/Start.ts

@@ -0,0 +1,72 @@
+/**
+ * 后台常驻启动（daemon）。
+ *
+ * 对应用户命令：`city agent start`
+ *
+ * 行为
+ * - 在 `.downcity/debug/` 写入 pid/log/meta 文件
+ * - 通过 `node <commands/index.js> agent start ...` 启动真正的前台逻辑，但以 detached 方式在后台运行
+ *
+ * 注意
+ * - 前台启动请显式使用 `city agent start --foreground`。
+ */
+
+import path from "path";
+import { fileURLToPath } from "url";
+import { startDaemonProcess } from "@/process/daemon/Manager.js";
+import { buildRunArgsFromOptions } from "@/process/daemon/CliArgs.js";
+import type { StartOptions } from "@downcity/agent";
+import { emitCliBlock } from "../shared/CliReporter.js";
+import { resolveAgentName } from "../shared/IndexSupport.js";
+import { checkAgentPreflight } from "../service/ServiceCommandSupport.js";
+import { CliError } from "../shared/CliError.js";
+
+/**
+ * daemon 启动入口。
+ *
+ * 流程（中文）
+ * 1) 统一预检（city runtime + 项目初始化 + binding）
+ * 2) 组装 `agent start` 子进程参数
+ * 3) 通过 daemon manager 后台拉起并打印 pid/log
+ */
+export async function startCommand(
+  cwd: string = ".",
+  options: StartOptions,
+): Promise<void> {
+  const projectRoot = path.resolve(cwd);
+
+  // 关键点（中文）：统一预检，替代分散的内联校验。
+  await checkAgentPreflight(projectRoot);
+
+  // 计算当前 CLI 的入口路径（编译后是 `bin/main/modules/cli/Index.js`）。
+  const __filename = fileURLToPath(import.meta.url);
+  const __dirname = path.dirname(__filename);
+  const cliPath = path.resolve(__dirname, "../Index.js");
+
+  const args = await buildRunArgsFromOptions(projectRoot, options || {});
+
+  try {
+    const { logPath: _logPath } = await startDaemonProcess({
+      projectRoot,
+      cliPath,
+      args,
+    });
+
+    emitCliBlock({
+      tone: "success",
+      title: "Agent daemon started",
+      summary: resolveAgentName(projectRoot),
+      facts: [
+        {
+          label: "Project",
+          value: projectRoot,
+        },
+      ],
+    });
+  } catch (error) {
+    throw new CliError({
+      title: "Failed to start daemon",
+      note: error instanceof Error ? error.message : String(error),
+    });
+  }
+}

package/src/cli/agent/Status.ts

@@ -0,0 +1,116 @@
+/**
+ * 查询后台 Agent 进程（daemon）状态。
+ *
+ * 对应命令：
+ * - `city agent status [path]`
+ */
+
+import path from "path";
+import fs from "fs-extra";
+import {
+  diagnoseDaemonStaleReasons,
+  isProcessAlive,
+  readDaemonMeta,
+  readDaemonPid,
+} from "@/process/daemon/Manager.js";
+import { getProfileMdPath, getDowncityJsonPath } from "@/config/Paths.js";
+import { emitCliBlock } from "../shared/CliReporter.js";
+
+/**
+ * daemon 状态查询入口。
+ *
+ * 状态规则（中文）
+ * - 运行中：输出 pid / log / startedAt
+ * - 已初始化但未运行：输出 not running
+ * - 未初始化：提示执行 `city agent create`
+ */
+export async function statusCommand(cwd: string = "."): Promise<void> {
+  const projectRoot = path.resolve(cwd);
+  const missingInitFiles: string[] = [];
+
+  if (!fs.existsSync(getProfileMdPath(projectRoot))) {
+    missingInitFiles.push("PROFILE.md");
+  }
+  if (!fs.existsSync(getDowncityJsonPath(projectRoot))) {
+    missingInitFiles.push("downcity.json");
+  }
+
+  const pid = await readDaemonPid(projectRoot);
+
+  if (pid && isProcessAlive(pid)) {
+    const meta = await readDaemonMeta(projectRoot);
+
+    emitCliBlock({
+      tone: "success",
+      title: "Agent status",
+      summary: "running",
+      facts: [
+        ["project", projectRoot],
+        ...(meta?.startedAt ? [["started at", meta.startedAt]] : []),
+        ...(missingInitFiles.length > 0
+          ? [["warning", `missing init files: ${missingInitFiles.join(", ")}`]]
+          : []),
+      ].map(([label, value]) => ({ label, value })),
+    });
+    return;
+  }
+
+  if (pid) {
+    const reasons = await diagnoseDaemonStaleReasons(projectRoot, pid);
+    emitCliBlock({
+      tone: "warning",
+      title: "Agent status",
+      summary: "stale",
+      facts: [
+        {
+          label: "project",
+          value: projectRoot,
+        },
+        {
+          label: "reason",
+          value: reasons.map((item) => item.message).join("; "),
+        },
+        {
+          label: "fix",
+          value: `city agent doctor ${projectRoot} --fix`,
+        },
+      ],
+    });
+    return;
+  }
+
+  if (missingInitFiles.length > 0) {
+    emitCliBlock({
+      tone: "error",
+      title: "Agent status",
+      summary: "not initialized",
+      facts: [
+        {
+          label: "project",
+          value: projectRoot,
+        },
+        {
+          label: "missing",
+          value: missingInitFiles.join(", "),
+        },
+        {
+          label: "fix",
+          value: 'run "city agent create" first',
+        },
+      ],
+    });
+    return;
+  }
+
+  emitCliBlock({
+    tone: "info",
+    title: "Agent status",
+    summary: "stopped",
+    facts: [
+      {
+        label: "project",
+        value: projectRoot,
+      },
+    ],
+  });
+}