@downcity/city 1.1.4 → 1.1.6

package/src/process/daemon/Api.ts

@@ -0,0 +1,64 @@
+/**
+ * Daemon API 协议类型模块。
+ *
+ * 关键点（中文）
+ * - 这里描述的是 CLI 与 agent daemon 之间的远程访问契约，不包含具体 HTTP 实现。
+ * - service 等上层模块只依赖这些协议类型，不需要感知 city/daemon 的内部实现细节。
+ * - 该文件属于 `main/city/daemon/*` 的协议边界，而不是通用 HTTP 类型目录。
+ */
+
+import type { JsonValue } from "@downcity/agent";
+
+/**
+ * Daemon 服务端点。
+ */
+export type DaemonEndpoint = {
+  host: string;
+  port: number;
+  baseUrl: string;
+};
+
+/**
+ * Daemon HTTP 方法白名单。
+ */
+export type DaemonHttpMethod = "GET" | "POST" | "PUT" | "DELETE";
+
+/**
+ * JSON API 调用参数。
+ *
+ * 关键点（中文）
+ * - `projectRoot` 用于解析 downcity.json 与默认 endpoint。
+ * - `host/port` 可显式覆盖自动解析结果。
+ */
+export type DaemonJsonApiCallParams = {
+  projectRoot: string;
+  path: string;
+  method?: DaemonHttpMethod;
+  body?: JsonValue;
+  /**
+   * 单次调用超时（毫秒）。
+   *
+   * 说明（中文）
+   * - 仅本地 IPC transport 当前会消费该参数。
+   * - 用于 `session execute`、`service command` 这类可能持续几十秒的请求，
+   *   避免被默认短超时误判成“Agent server 未启动”。
+   */
+  timeoutMs?: number;
+  host?: string;
+  port?: number;
+  authToken?: string;
+};
+
+/**
+ * JSON API 通用返回结构。
+ *
+ * 语义（中文）
+ * - `success=true` 时读取 `data`。
+ * - `success=false` 时读取 `error`（可选 `status`）。
+ */
+export type DaemonJsonApiCallResult<T> = {
+  success: boolean;
+  status?: number;
+  data?: T;
+  error?: string;
+};

package/src/process/daemon/CliArgs.ts

@@ -0,0 +1,39 @@
+/**
+ * 负责把 commander 解析到的 options 转换成子进程 CLI 参数。
+ *
+ * 关键点
+ * - daemon（来自 `agent start` / `agent restart`）会拉起一个前台 `agent start`
+ *   进程（显式 `--foreground true`），这里负责拼装其 argv。
+ */
+
+import type { StartOptions } from "@downcity/agent";
+import { allocateAvailablePort } from "@/process/daemon/PortAllocator.js";
+
+/**
+ * 将 daemon 选项转换为 `agent start` 子进程 argv。
+ *
+ * 关键点（中文）
+ * - daemon 始终启动 `agent start` 前台流程，因此参数统一映射到 `agent start` CLI 形态。
+ * - 只透传用户显式传入的字段，避免污染默认值决策。
+ */
+export const buildRunArgsFromOptions = async (
+  projectRoot: string,
+  options: StartOptions,
+): Promise<string[]> => {
+  // 关键点（中文）：daemon 子进程必须强制前台模式，避免再次进入 startCommand 形成递归拉起。
+  const args: string[] = ["agent", "start", projectRoot, "--foreground", "true"];
+
+  // 关键点（中文）：host 未指定时统一落到 0.0.0.0，保持历史监听行为。
+  const host = String(options.host || "0.0.0.0").trim() || "0.0.0.0";
+
+  // 关键点（中文）：agent 端口统一由 console 分配，不接受命令行显式覆盖。
+  const port = await allocateAvailablePort({ host });
+  if (!Number.isFinite(port) || Number.isNaN(port) || port <= 0 || port > 65535) {
+    throw new Error(`Invalid allocated port: ${String(port)}`);
+  }
+
+  args.push("--port", String(port));
+  args.push("--host", host);
+
+  return args;
+};

package/src/process/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 "@/process/daemon/Manager.js";
+import type { JsonObject, JsonValue } from "@downcity/agent";
+
+/**
+ * 解析端口值。
+ *
+ * 关键点（中文）
+ * - 仅接受 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/process/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 "@downcity/agent";
+import {
+  markManagedAgentStopped,
+  upsertManagedAgentEntry,
+} from "@/process/registry/CityRegistry.js";
+import { signalDetachedProcess } from "@/process/registry/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/process/registry/AgentHostRuntime.ts

@@ -0,0 +1,65 @@
+/**
+ * AgentHostRuntime：装配 AgentRuntime 宿主能力。
+ *
+ * 关键点（中文）
+ * - `main/agent/*` 负责创建这些宿主能力对象，再注入到 AgentRuntime。
+ * - services / session / plugins 只消费这些对象，不再直接 import `main/*`。
+ * - 当前先收敛路径与 plugin 配置持久化两类宿主能力。
+ */
+import {
+  getCacheDirPath,
+  getDowncityChannelDirPath,
+  getDowncityChannelMetaPath,
+  getDowncityChatHistoryPath,
+  getDowncityDirPath,
+  getDowncityMemoryDailyDirPath,
+  getDowncityMemoryDailyPath,
+  getDowncityMemoryIndexPath,
+  getDowncityMemoryLongTermPath,
+  getDowncitySessionDirPath,
+  getDowncitySessionRootDirPath,
+} from "@/config/Paths.js";
+import { persistProjectPluginConfig } from "@downcity/agent";
+import type {
+  AgentPathRuntime,
+  AgentPluginConfigRuntime,
+} from "@downcity/agent";
+import type { DowncityConfig } from "@downcity/agent";
+
+/**
+ * 创建当前项目的路径能力集合。
+ */
+export function createAgentPathRuntime(projectRoot: string): AgentPathRuntime {
+  const rootPath = String(projectRoot || "").trim();
+  return {
+    projectRoot: rootPath,
+    getDowncityDirPath: () => getDowncityDirPath(rootPath),
+    getCacheDirPath: () => getCacheDirPath(rootPath),
+    getDowncityChannelDirPath: () => getDowncityChannelDirPath(rootPath),
+    getDowncityChannelMetaPath: () => getDowncityChannelMetaPath(rootPath),
+    getDowncityChatHistoryPath: (sessionId) => getDowncityChatHistoryPath(rootPath, sessionId),
+    getDowncityMemoryIndexPath: () => getDowncityMemoryIndexPath(rootPath),
+    getDowncityMemoryLongTermPath: () => getDowncityMemoryLongTermPath(rootPath),
+    getDowncityMemoryDailyDirPath: () => getDowncityMemoryDailyDirPath(rootPath),
+    getDowncityMemoryDailyPath: (date) => getDowncityMemoryDailyPath(rootPath, date),
+    getDowncitySessionRootDirPath: () => getDowncitySessionRootDirPath(rootPath),
+    getDowncitySessionDirPath: (sessionId) => getDowncitySessionDirPath(rootPath, sessionId),
+  };
+}
+
+/**
+ * 创建 plugin 配置持久化能力集合。
+ */
+export function createAgentPluginConfigRuntime(projectRoot: string): AgentPluginConfigRuntime {
+  const rootPath = String(projectRoot || "").trim();
+  return {
+    async persistProjectPlugins(plugins: DowncityConfig["plugins"] | undefined): Promise<string> {
+      return persistProjectPluginConfig({
+        projectRoot: rootPath,
+        sections: {
+          ...(plugins !== undefined ? { plugins } : {}),
+        },
+      });
+    },
+  };
+}