@downcity/agent 1.1.1 → 1.1.5

package/src/host/daemon/Client.ts

@@ -0,0 +1,182 @@
+/**
+ * Daemon API 客户端（process 子模块）。
+ *
+ * 关键点（中文）
+ * - 业务模块统一通过 daemon API 与运行时通信。
+ * - 地址解析优先级：CLI 参数 > 环境变量 > daemon meta > 默认值。
+ */
+
+import fs from "fs-extra";
+import {
+  type DaemonEndpoint,
+  type DaemonJsonApiCallParams,
+  type DaemonJsonApiCallResult,
+} from "./Api.js";
+import {
+  formatCliBearerHeaderValue,
+  resolveCliAuthToken,
+} from "@/http/auth/CliAuthStateStore.js";
+import { getDaemonMetaPath } from "@/host/daemon/Manager.js";
+import type { JsonObject, JsonValue } from "@/shared/types/Json.js";
+
+/**
+ * 解析端口值。
+ *
+ * 关键点（中文）
+ * - 仅接受 1~65535 的整数；非法值返回 undefined。
+ */
+function parsePortLike(input: string | number | undefined): number | undefined {
+  if (input === undefined || input === null || input === "") return undefined;
+  const raw =
+    typeof input === "number" ? input : Number.parseInt(String(input), 10);
+  if (!Number.isFinite(raw) || Number.isNaN(raw)) return undefined;
+  if (!Number.isInteger(raw) || raw <= 0 || raw > 65535) return undefined;
+  return raw;
+}
+
+/**
+ * 归一化 host。
+ *
+ * 关键点（中文）
+ * - `0.0.0.0`/`::` 会转换为 `127.0.0.1`，避免客户端直连通配地址失败。
+ */
+function normalizeHost(input: string | undefined): string | undefined {
+  const host = typeof input === "string" ? input.trim() : "";
+  if (!host) return undefined;
+  if (host === "0.0.0.0" || host === "::") return "127.0.0.1";
+  return host;
+}
+
+function parseErrorMessageFromPayload(data: JsonValue | null): string | null {
+  if (!data || typeof data !== "object" || Array.isArray(data)) return null;
+  const payload = data as JsonObject;
+  if (typeof payload.error === "string") return payload.error;
+  if (typeof payload.message === "string") return payload.message;
+  return null;
+}
+
+function pickArgValue(args: string[], key: string): string | undefined {
+  const idx = args.findIndex((item) => String(item).trim() === key);
+  if (idx < 0) return undefined;
+  const next = String(args[idx + 1] || "").trim();
+  return next || undefined;
+}
+
+/**
+ * 解析 daemon endpoint。
+ *
+ * 优先级（中文）
+ * 1) 显式入参 `host/port`
+ * 2) 环境变量 `DC_SERVER_*` / `DC_CTX_SERVER_*`
+ * 3) daemon meta args（`downcity.daemon.json`）
+ * 4) 默认 `127.0.0.1:5314`
+ */
+function resolveDaemonEndpoint(params: {
+  projectRoot: string;
+  host?: string;
+  port?: number;
+}): DaemonEndpoint {
+  const explicitHost = normalizeHost(params.host);
+  const explicitPort = parsePortLike(params.port);
+
+  const envHost =
+    normalizeHost(process.env.DC_SERVER_HOST) ||
+    normalizeHost(process.env.DC_CTX_SERVER_HOST);
+  const envPort =
+    parsePortLike(process.env.DC_SERVER_PORT) ||
+    parsePortLike(process.env.DC_CTX_SERVER_PORT);
+
+  let daemonArgHost: string | undefined;
+  let daemonArgPort: number | undefined;
+  try {
+    const metaPath = getDaemonMetaPath(params.projectRoot);
+    if (fs.existsSync(metaPath)) {
+      const raw = fs.readJsonSync(metaPath) as { args?: unknown };
+      const args = Array.isArray(raw?.args)
+        ? raw.args.map((item) => String(item))
+        : [];
+      daemonArgHost = normalizeHost(pickArgValue(args, "--host"));
+      daemonArgPort = parsePortLike(pickArgValue(args, "--port"));
+    }
+  } catch {
+    // ignore daemon meta errors, fallback to other sources
+  }
+
+  const host = explicitHost || envHost || daemonArgHost || "127.0.0.1";
+  const port = explicitPort || envPort || daemonArgPort || 5314;
+
+  return {
+    host,
+    port,
+    baseUrl: `http://${host}:${port}`,
+  };
+}
+
+/**
+ * 调用 daemon JSON API。
+ *
+ * 错误语义（中文）
+ * - 网络异常：`success=false` + `error`（无 status）。
+ * - HTTP 非 2xx：`success=false` + `status` + `error`。
+ */
+export async function callServer<T>(
+  params: DaemonJsonApiCallParams,
+): Promise<DaemonJsonApiCallResult<T>> {
+  const endpoint = resolveDaemonEndpoint({
+    projectRoot: params.projectRoot,
+    host: params.host,
+    port: params.port,
+  });
+
+  const url = new URL(params.path, endpoint.baseUrl).toString();
+  const method = params.method || "GET";
+  const hasBody = params.body !== undefined && method !== "GET";
+  const headers: Record<string, string> = {};
+  const authHeaderValue = formatCliBearerHeaderValue(
+    resolveCliAuthToken({
+      explicitToken: params.authToken,
+    }),
+  );
+  if (hasBody) {
+    headers["Content-Type"] = "application/json";
+  }
+  if (authHeaderValue) {
+    headers.Authorization = authHeaderValue;
+  }
+
+  try {
+    const response = await fetch(url, {
+      method,
+      headers: Object.keys(headers).length > 0 ? headers : undefined,
+      body: hasBody ? JSON.stringify(params.body) : undefined,
+    });
+
+    let data: JsonValue | null = null;
+    try {
+      data = (await response.json()) as JsonValue;
+    } catch {
+      data = null;
+    }
+
+    if (!response.ok) {
+      const messageFromData =
+        parseErrorMessageFromPayload(data) || `HTTP ${response.status}`;
+      return {
+        success: false,
+        status: response.status,
+        error: messageFromData,
+      };
+    }
+
+    return {
+      success: true,
+      status: response.status,
+      data: data as T,
+    };
+  } catch (error) {
+    return {
+      success: false,
+      error: `Failed to call ${url}: ${String(error)}`,
+    };
+  }
+}

package/src/host/daemon/Manager.ts

@@ -0,0 +1,344 @@
+/**
+ * Downcity daemon 管理（PID / 日志 / 启停）。
+ *
+ * 目标
+ * - `downcity agent start`：后台启动（终端退出后仍运行）
+ * - `downcity agent restart`：重启后台进程
+ *
+ * 约定
+ * - 所有 daemon 相关文件都写入 `.downcity/debug/`，便于排查：
+ *   - `downcity.pid`：进程 pid
+ *   - `downcity.daemon.log`：stdout/stderr 合并日志
+ *   - `downcity.daemon.json`：元数据（启动时间、参数等）
+ */
+
+import fs from "fs-extra";
+import path from "path";
+import { spawn } from "child_process";
+import { getDowncityDebugDirPath } from "@/config/Paths.js";
+import {
+  DAEMON_LOG_FILENAME,
+  DAEMON_META_FILENAME,
+  DAEMON_PID_FILENAME,
+  type DaemonMeta,
+  type DaemonStaleReason,
+} from "@/shared/types/Daemon.js";
+import {
+  markManagedAgentStopped,
+  upsertManagedAgentEntry,
+} from "@/host/runtime/CityRegistry.js";
+import { signalDetachedProcess } from "@/host/runtime/ProcessSweep.js";
+
+/**
+ * 异步睡眠工具。
+ */
+const sleep = async (ms: number): Promise<void> =>
+  new Promise((resolve) => setTimeout(resolve, ms));
+
+/**
+ * 计算 daemon pid 文件路径。
+ */
+export const getDaemonPidPath = (projectRoot: string): string =>
+  path.join(getDowncityDebugDirPath(projectRoot), DAEMON_PID_FILENAME);
+
+/**
+ * 计算 daemon 日志文件路径。
+ */
+export const getDaemonLogPath = (projectRoot: string): string =>
+  path.join(getDowncityDebugDirPath(projectRoot), DAEMON_LOG_FILENAME);
+
+/**
+ * 计算 daemon 元数据文件路径。
+ */
+export const getDaemonMetaPath = (projectRoot: string): string =>
+  path.join(getDowncityDebugDirPath(projectRoot), DAEMON_META_FILENAME);
+
+/**
+ * 读取 daemon pid。
+ *
+ * 关键点（中文）
+ * - 读取失败或内容非法统一返回 `null`，调用方走无进程分支。
+ */
+export const readDaemonPid = async (
+  projectRoot: string,
+): Promise<number | null> => {
+  try {
+    const raw = await fs.readFile(getDaemonPidPath(projectRoot), "utf-8");
+    const pid = Number.parseInt(String(raw).trim(), 10);
+    return Number.isFinite(pid) && pid > 0 ? pid : null;
+  } catch {
+    return null;
+  }
+};
+
+/**
+ * 检查进程是否存活。
+ */
+export const isProcessAlive = (pid: number): boolean => {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+/**
+ * 读取 daemon meta（宽松模式）。
+ *
+ * 关键点（中文）
+ * - 返回 null 表示文件缺失、解析失败或结构非法。
+ * - 该函数用于状态展示，不抛异常。
+ */
+export const readDaemonMeta = async (
+  projectRoot: string,
+): Promise<DaemonMeta | null> => {
+  try {
+    const value = await fs.readJson(getDaemonMetaPath(projectRoot));
+    const pid = Number((value as { pid?: unknown })?.pid);
+    if (!Number.isFinite(pid) || pid <= 0) return null;
+    const startedAt = String(
+      (value as { startedAt?: unknown })?.startedAt || "",
+    ).trim();
+    if (!startedAt) return null;
+    const command = String(
+      (value as { command?: unknown })?.command || "",
+    ).trim();
+    const project = String(
+      (value as { projectRoot?: unknown })?.projectRoot || "",
+    ).trim();
+    if (!command || !project) return null;
+    return value as DaemonMeta;
+  } catch {
+    return null;
+  }
+};
+
+/**
+ * 诊断 stale 原因。
+ */
+export const diagnoseDaemonStaleReasons = async (
+  projectRoot: string,
+  pid: number,
+): Promise<DaemonStaleReason[]> => {
+  const reasons: DaemonStaleReason[] = [];
+  reasons.push({
+    code: "process_not_alive",
+    message: "pid file exists but process is not alive",
+  });
+
+  const metaPath = getDaemonMetaPath(projectRoot);
+  const metaExists = await fs.pathExists(metaPath);
+  if (!metaExists) {
+    reasons.push({
+      code: "meta_missing",
+      message: "daemon meta file is missing",
+    });
+    return reasons;
+  }
+
+  try {
+    await fs.readJson(metaPath);
+  } catch {
+    reasons.push({
+      code: "meta_invalid",
+      message: "daemon meta file is invalid JSON",
+    });
+    return reasons;
+  }
+
+  const parsedMeta = await readDaemonMeta(projectRoot);
+  if (!parsedMeta) {
+    reasons.push({
+      code: "meta_invalid",
+      message: "daemon meta file has invalid structure",
+    });
+    return reasons;
+  }
+
+  if (parsedMeta.pid !== pid) {
+    reasons.push({
+      code: "meta_pid_mismatch",
+      message: `meta pid (${parsedMeta.pid}) does not match pid file (${pid})`,
+    });
+  }
+
+  const metaProjectRoot = path.resolve(String(parsedMeta.projectRoot || ""));
+  const expectedProjectRoot = path.resolve(projectRoot);
+  if (metaProjectRoot !== expectedProjectRoot) {
+    reasons.push({
+      code: "meta_project_mismatch",
+      message: `meta project root mismatch (${metaProjectRoot})`,
+    });
+  }
+
+  return reasons;
+};
+
+/**
+ * 清理僵尸 daemon 标记文件。
+ *
+ * 算法（中文）
+ * - 若 pid 文件存在但进程不存在，移除 pid/meta，恢复可重启状态。
+ */
+export const cleanupStaleDaemonFiles = async (
+  projectRoot: string,
+): Promise<void> => {
+  const pid = await readDaemonPid(projectRoot);
+  if (!pid) return;
+  if (isProcessAlive(pid)) return;
+
+  // 关键注释：pid 文件存在但进程已退出，属于“脏状态”，这里直接清理。
+  await fs.remove(getDaemonPidPath(projectRoot));
+  await fs.remove(getDaemonMetaPath(projectRoot));
+  // 关键点（中文）：僵尸 daemon 清理时标记 stopped，保留历史记录。
+  try {
+    await markManagedAgentStopped(projectRoot);
+  } catch {
+    // ignore registry sync errors
+  }
+};
+
+/**
+ * 写入 daemon pid 与元数据文件。
+ */
+export const writeDaemonFiles = async (
+  projectRoot: string,
+  meta: DaemonMeta,
+): Promise<void> => {
+  await fs.ensureDir(getDowncityDebugDirPath(projectRoot));
+  await fs.writeFile(getDaemonPidPath(projectRoot), String(meta.pid), "utf-8");
+  await fs.writeJson(getDaemonMetaPath(projectRoot), meta, { spaces: 2 });
+};
+
+/**
+ * 启动 daemon 子进程。
+ *
+ * 流程（中文）
+ * 1) 清理脏 pid/meta
+ * 2) 检查是否已有存活 daemon
+ * 3) detached + unref 拉起 `node cli.js run ...`
+ * 4) 写入 pid/meta 供 stop/restart 使用
+ */
+export const startDaemonProcess = async (params: {
+  projectRoot: string;
+  cliPath: string;
+  args: string[];
+}): Promise<{ pid: number; logPath: string }> => {
+  const { projectRoot, cliPath, args } = params;
+
+  await fs.ensureDir(getDowncityDebugDirPath(projectRoot));
+  await cleanupStaleDaemonFiles(projectRoot);
+
+  const existingPid = await readDaemonPid(projectRoot);
+  if (existingPid && isProcessAlive(existingPid)) {
+    throw new Error(`Daemon already running (pid: ${existingPid})`);
+  }
+
+  const logPath = getDaemonLogPath(projectRoot);
+  const logFd = fs.openSync(logPath, "a");
+
+  const childEnv: NodeJS.ProcessEnv = {
+    ...process.env,
+    DOWNCITY_DAEMON: "1",
+  };
+
+  // 关键注释：daemon 进程必须 detached + unref 才能在父进程退出后继续运行。
+  const child = spawn(process.execPath, [cliPath, ...args], {
+    cwd: projectRoot,
+    detached: true,
+    stdio: ["ignore", logFd, logFd],
+    env: childEnv,
+  });
+
+  child.unref();
+
+  if (!child.pid) {
+    throw new Error("Failed to start daemon process (missing pid)");
+  }
+
+  await writeDaemonFiles(projectRoot, {
+    pid: child.pid,
+    projectRoot,
+    startedAt: new Date().toISOString(),
+    command: process.execPath,
+    args: [cliPath, ...args],
+    node: process.version,
+    platform: process.platform,
+  });
+
+  // 关键点（中文）：启动成功后必须登记到 managed agent registry，否则该 daemon 视为“无效启动”。
+  try {
+    await upsertManagedAgentEntry({
+      projectRoot,
+      pid: child.pid,
+      status: "running",
+    });
+  } catch (error) {
+    // 回滚：无法登记时立即停止 daemon 并清理状态文件。
+    signalDetachedProcess(child.pid, "SIGTERM");
+    await sleep(300);
+    try {
+      if (isProcessAlive(child.pid)) signalDetachedProcess(child.pid, "SIGKILL");
+    } catch {
+      // ignore
+    }
+    await fs.remove(getDaemonPidPath(projectRoot));
+    await fs.remove(getDaemonMetaPath(projectRoot));
+    throw error;
+  }
+
+  return { pid: child.pid, logPath };
+};
+
+/**
+ * 停止 daemon 子进程。
+ *
+ * 策略（中文）
+ * - 先发 `SIGTERM` 做优雅退出；超时后回退 `SIGKILL`。
+ * - 无论 stop 结果如何，最终清理 pid/meta，避免状态残留。
+ */
+export const stopDaemonProcess = async (params: {
+  projectRoot: string;
+  timeoutMs?: number;
+}): Promise<{ stopped: boolean; pid?: number }> => {
+  const { projectRoot, timeoutMs = 10_000 } = params;
+
+  await cleanupStaleDaemonFiles(projectRoot);
+  const pid = await readDaemonPid(projectRoot);
+  if (!pid) return { stopped: false };
+
+  if (!isProcessAlive(pid)) {
+    await fs.remove(getDaemonPidPath(projectRoot));
+    await fs.remove(getDaemonMetaPath(projectRoot));
+    return { stopped: false, pid };
+  }
+
+  signalDetachedProcess(pid, "SIGTERM");
+
+  const startedAt = Date.now();
+  while (Date.now() - startedAt < timeoutMs) {
+    if (!isProcessAlive(pid)) break;
+    await sleep(200);
+  }
+
+  if (isProcessAlive(pid)) {
+    // 关键注释：尽量优雅停止，超时后再强杀，避免后台进程“卡死”。
+    try {
+      signalDetachedProcess(pid, "SIGKILL");
+    } catch {
+      // ignore
+    }
+  }
+
+  await fs.remove(getDaemonPidPath(projectRoot));
+  await fs.remove(getDaemonMetaPath(projectRoot));
+  // 关键点（中文）：停止后标记为 stopped，保留历史记录。
+  try {
+    await markManagedAgentStopped(projectRoot);
+  } catch {
+    // ignore registry sync errors
+  }
+
+  return { stopped: true, pid };
+};

package/src/host/daemon/ProjectSetup.ts

@@ -0,0 +1,126 @@
+/**
+ * ProjectSetup：runtime 启动前项目结构准备模块。
+ *
+ * 关键点（中文）
+ * - 统一校验初始化必要文件（PROFILE.md / downcity.json）。
+ * - 统一确保 `.downcity/*` 目录结构存在，避免调用方重复拼装目录逻辑。
+ */
+
+import fs from "fs-extra";
+import path from "node:path";
+import { loadDowncityConfig } from "@/config/Config.js";
+import { PlatformStore } from "@/shared/utils/store/index.js";
+import {
+  readProjectExecutionBinding,
+  readProjectPrimaryModelId,
+} from "@/agent/project/ProjectExecutionBinding.js";
+import {
+  getCacheDirPath,
+  getLogsDirPath,
+  getProfileMdPath,
+  getDowncityConfigDirPath,
+  getDowncityDataDirPath,
+  getDowncityDebugDirPath,
+  getDowncityDirPath,
+  getDowncityJsonPath,
+  getDowncityProfileDirPath,
+  getDowncityPublicDirPath,
+  getDowncitySessionRootDirPath,
+  getDowncityTasksDirPath,
+} from "@/config/Paths.js";
+
+/**
+ * 校验项目初始化关键文件。
+ */
+function ensureContextFiles(projectRoot: string): void {
+  // Check if initialized（启动入口一次性确认工程根目录与关键文件）
+  if (!fs.existsSync(getProfileMdPath(projectRoot))) {
+    console.error(
+      '❌ Project not initialized. Please run "city agent create" first',
+    );
+    process.exit(1);
+  }
+
+  if (!fs.existsSync(getDowncityJsonPath(projectRoot))) {
+    console.error(
+      '❌ downcity.json does not exist. Please run "city agent create" first',
+    );
+    process.exit(1);
+  }
+}
+
+/**
+ * 确保 `.downcity` 运行目录结构完整。
+ */
+function ensureShipDirectories(projectRoot: string): void {
+  // 关键点（中文）：尽量只在启动时确保目录结构存在，避免在 Agent/Tool 执行过程中反复 ensure。
+  fs.ensureDirSync(getDowncityDirPath(projectRoot));
+  fs.ensureDirSync(getDowncityTasksDirPath(projectRoot));
+  fs.ensureDirSync(getLogsDirPath(projectRoot));
+  fs.ensureDirSync(getCacheDirPath(projectRoot));
+  fs.ensureDirSync(getDowncityProfileDirPath(projectRoot));
+  fs.ensureDirSync(getDowncityDataDirPath(projectRoot));
+  fs.ensureDirSync(getDowncitySessionRootDirPath(projectRoot));
+  fs.ensureDirSync(getDowncityPublicDirPath(projectRoot));
+  fs.ensureDirSync(getDowncityConfigDirPath(projectRoot));
+  fs.ensureDirSync(path.join(getDowncityDirPath(projectRoot), "schema"));
+  fs.ensureDirSync(getDowncityDebugDirPath(projectRoot));
+}
+
+/**
+ * runtime 启动前准备项目结构。
+ */
+export function ensureRuntimeProjectReady(projectRoot: string): void {
+  ensureContextFiles(projectRoot);
+  ensureShipDirectories(projectRoot);
+}
+
+/**
+ * 校验项目执行绑定是否可用于启动。
+ *
+ * 关键点（中文）
+ * - `downcity.json.execution` 必须存在且合法。
+ * - 若走 API 模式，则 `execution.modelId` 必须在 console 模型池中可解析。
+ * - 若走 local 模式，则 `lmp` plugin 必须启用且本地模型文件必须存在。
+ * - 若模型被 pause，也要在启动前直接拒绝，避免进程拉起后秒退。
+ */
+export function ensureRuntimeExecutionBindingReady(projectRoot: string): void {
+  let primaryModelId = "";
+  try {
+    const config = loadDowncityConfig(projectRoot);
+    primaryModelId = readProjectPrimaryModelId(config);
+  } catch (error) {
+    console.error("❌ Invalid downcity.json execution binding");
+    console.error(`   project: ${projectRoot}`);
+    console.error(`   error: ${error instanceof Error ? error.message : String(error)}`);
+    process.exit(1);
+  }
+
+  if (!primaryModelId) {
+    console.error("❌ Invalid downcity.json execution binding");
+    console.error(`   project: ${projectRoot}`);
+    console.error('   error: "execution" must be { "type": "api", "modelId": "..." }');
+    process.exit(1);
+  }
+
+  const store = new PlatformStore();
+  try {
+    const model = store.getModel(primaryModelId);
+    if (!model) {
+      console.error("❌ Model not found in platform model pool");
+      console.error(`   project: ${projectRoot}`);
+      console.error(`   execution.modelId: ${primaryModelId}`);
+      console.error("   fix: run `city model create` or `city model list`");
+      process.exit(1);
+    }
+    if (model.isPaused === true) {
+      console.error("❌ Model is paused");
+      console.error(`   project: ${projectRoot}`);
+      console.error(`   execution.modelId: ${primaryModelId}`);
+      console.error(`   fix: run \`city model pause ${primaryModelId} --enabled false\``);
+      process.exit(1);
+    }
+  } finally {
+    store.close();
+  }
+}