@downcity/agent 1.1.10 → 1.1.11

package/src/host/daemon/Manager.ts

@@ -1,344 +0,0 @@
-/**
- * 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 "@/host/daemon/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/runtime/CityPaths.ts

@@ -1,84 +0,0 @@
-/**
- * CityPaths：city 全局运行态与 control plane 共享的路径规则。
- *
- * 关键点（中文）
- * - Downcity 的全局根目录固定在用户目录 `~/.downcity/`。
- * - `~/.downcity/downcity.db`：全局 SQLite 数据库，保存模型池与平台级配置。
- * - `~/.downcity/main/*`：city 后台与 control plane 共享的运行文件目录。
- * - 这里定义的是“全局路径约定”，不是单个 agent 项目的 `.downcity/` 路径。
- */
-
-import os from "node:os";
-import path from "node:path";
-
-/**
- * 全局根目录（用户级）。
- */
-export function getPlatformRootDirPath(): string {
-  const explicitRoot = String(process.env.DC_PLATFORM_ROOT || "").trim();
-  if (explicitRoot) return path.resolve(explicitRoot);
-  return path.join(os.homedir(), ".downcity");
-}
-
-/**
- * 全局 SQLite 数据库路径（用户级）。
- */
-export function getPlatformStoreDbPath(): string {
-  return path.join(getPlatformRootDirPath(), "downcity.db");
-}
-
-/**
- * city 全局运行目录（pid/log/registry）。
- */
-export function getCityRuntimeDirPath(): string {
-  return path.join(getPlatformRootDirPath(), "main");
-}
-
-/**
- * 全局模型存储密钥文件路径。
- */
-export function getPlatformStoreKeyPath(): string {
-  return path.join(getCityRuntimeDirPath(), "model-db.key");
-}
-
-/**
- * city 后台 pid 文件路径。
- */
-export function getCityPidPath(): string {
-  return path.join(getCityRuntimeDirPath(), "city.pid");
-}
-
-/**
- * city 后台日志路径（stdout/stderr 合并）。
- */
-export function getCityLogPath(): string {
-  return path.join(getCityRuntimeDirPath(), "city.log");
-}
-
-/**
- * control plane pid 文件路径。
- */
-export function getControlPlanePidPath(): string {
-  return path.join(getCityRuntimeDirPath(), "control-plane.pid");
-}
-
-/**
- * control plane 日志路径（stdout/stderr 合并）。
- */
-export function getControlPlaneLogPath(): string {
-  return path.join(getCityRuntimeDirPath(), "control-plane.log");
-}
-
-/**
- * control plane 元数据路径。
- */
-export function getControlPlaneMetaPath(): string {
-  return path.join(getCityRuntimeDirPath(), "control-plane.json");
-}
-
-/**
- * 受管 agent registry 文件路径（city 维护的 agent 清单）。
- */
-export function getManagedAgentRegistryPath(): string {
-  return path.join(getCityRuntimeDirPath(), "agents.json");
-}

package/src/host/runtime/CityRegistry.ts

@@ -1,256 +0,0 @@
-/**
- * CityRegistry：city 后台维护的 agent registry（`~/.downcity/main/agents.json`）。
- *
- * 关键点（中文）
- * - registry 只维护“city 认知到的 agent 项目列表”，用于统一观测与批量管理。
- * - registry 不承载实时健康检查：status/list 会读取每个项目的 daemon pid 并判活。
- * - agent daemon 启动成功后必须登记到 city 后台（强约束）。
- */
-
-import fs from "fs-extra";
-import path from "node:path";
-import type {
-  ManagedAgentRegistryEntry,
-  ManagedAgentRegistryV1,
-} from "@/host/runtime/types/Platform.js";
-import { getManagedAgentRegistryPath, getCityRuntimeDirPath } from "./CityPaths.js";
-import { isCityRunning } from "./CityRuntime.js";
-
-const CONSOLE_DIR = getCityRuntimeDirPath();
-const MANAGED_AGENTS_FILE = getManagedAgentRegistryPath();
-
-function buildEmptyRegistry(): ManagedAgentRegistryV1 {
-  return {
-    v: 1,
-    updatedAt: new Date().toISOString(),
-    agents: [],
-  };
-}
-
-function normalizeProjectRoot(projectRoot: string): string {
-  const resolved = path.resolve(String(projectRoot || "").trim());
-  if (!resolved) throw new Error("projectRoot is required");
-  return resolved;
-}
-
-function normalizePid(pid: number): number {
-  if (!Number.isFinite(pid) || Number.isNaN(pid) || !Number.isInteger(pid) || pid < 1) {
-    throw new Error(`Invalid pid: ${pid}`);
-  }
-  return pid;
-}
-
-function normalizeIsoTime(input: string | undefined): string {
-  const value = String(input || "").trim();
-  if (!value) return new Date().toISOString();
-  const ms = Date.parse(value);
-  if (!Number.isFinite(ms)) return new Date().toISOString();
-  return new Date(ms).toISOString();
-}
-
-function normalizeRegistryEntry(
-  entry: Partial<ManagedAgentRegistryEntry>,
-): ManagedAgentRegistryEntry | null {
-  try {
-    const projectRoot = normalizeProjectRoot(String(entry.projectRoot || ""));
-    const pid = normalizePid(Number(entry.pid));
-    const startedAt = normalizeIsoTime(
-      typeof entry.startedAt === "string" ? entry.startedAt : undefined,
-    );
-    const updatedAt = normalizeIsoTime(
-      typeof entry.updatedAt === "string" ? entry.updatedAt : undefined,
-    );
-    return {
-      projectRoot,
-      pid,
-      startedAt,
-      updatedAt,
-      status:
-        entry.status === "stopped"
-          ? "stopped"
-          : "running",
-      stoppedAt:
-        entry.status === "stopped"
-          ? normalizeIsoTime(
-              typeof entry.stoppedAt === "string"
-                ? entry.stoppedAt
-                : undefined,
-            )
-          : undefined,
-    };
-  } catch {
-    return null;
-  }
-}
-
-function normalizeRegistry(
-  value: Partial<ManagedAgentRegistryV1> | null | undefined,
-): ManagedAgentRegistryV1 {
-  if (!value || typeof value !== "object") return buildEmptyRegistry();
-  const source = Array.isArray(value.agents) ? value.agents : [];
-  const normalizedAgents: ManagedAgentRegistryEntry[] = [];
-  for (const item of source) {
-    if (!item || typeof item !== "object") continue;
-    const normalized = normalizeRegistryEntry(item as ManagedAgentRegistryEntry);
-    if (!normalized) continue;
-    const existingIndex = normalizedAgents.findIndex(
-      (entry) => entry.projectRoot === normalized.projectRoot,
-    );
-    if (existingIndex >= 0) {
-      normalizedAgents[existingIndex] = normalized;
-      continue;
-    }
-    normalizedAgents.push(normalized);
-  }
-  return {
-    v: 1,
-    updatedAt: normalizeIsoTime(
-      typeof value.updatedAt === "string" ? value.updatedAt : undefined,
-    ),
-    agents: normalizedAgents.sort((a, b) =>
-      a.projectRoot.localeCompare(b.projectRoot),
-    ),
-  };
-}
-
-async function writeManagedAgentRegistry(
-  registry: ManagedAgentRegistryV1,
-): Promise<void> {
-  await fs.ensureDir(CONSOLE_DIR);
-  await fs.writeJson(MANAGED_AGENTS_FILE, normalizeRegistry(registry), {
-    spaces: 2,
-  });
-}
-
-/**
- * 确保 city agent registry 文件存在。
- *
- * 关键点（中文）
- * - 空 city 运行态也应拥有显式的空 registry，避免 Console 将“尚未启动任何 agent”误判为异常。
- * - 若文件已存在则不覆盖，保持历史记录不丢失。
- */
-export async function ensureManagedAgentRegistry(): Promise<void> {
-  await fs.ensureDir(CONSOLE_DIR);
-  if (await fs.pathExists(MANAGED_AGENTS_FILE)) {
-    return;
-  }
-  await writeManagedAgentRegistry(buildEmptyRegistry());
-}
-
-/**
- * 获取 city agent registry 文件路径。
- */
-export function getManagedAgentsRegistryPath(): string {
-  return MANAGED_AGENTS_FILE;
-}
-
-/**
- * 读取 city agent registry（容错）。
- *
- * 关键点（中文）
- * - 文件不存在或损坏时返回空 registry，避免影响主流程。
- */
-export async function readManagedAgentRegistry(): Promise<ManagedAgentRegistryV1> {
-  try {
-    if (!(await fs.pathExists(MANAGED_AGENTS_FILE))) {
-      return buildEmptyRegistry();
-    }
-    const raw = (await fs.readJson(MANAGED_AGENTS_FILE)) as Partial<ManagedAgentRegistryV1>;
-    return normalizeRegistry(raw);
-  } catch {
-    return buildEmptyRegistry();
-  }
-}
-
-/**
- * 列出 city registry 中记录的 agent（按 projectRoot 排序）。
- */
-export async function listManagedAgentEntries(): Promise<ManagedAgentRegistryEntry[]> {
-  const registry = await readManagedAgentRegistry();
-  return [...registry.agents].sort((a, b) => a.projectRoot.localeCompare(b.projectRoot));
-}
-
-/**
- * 新增或更新一条 city agent 记录。
- */
-export async function upsertManagedAgentEntry(input: {
-  projectRoot: string;
-  pid: number;
-  startedAt?: string;
-  status?: "running" | "stopped";
-  stoppedAt?: string;
-}): Promise<void> {
-  // 关键点（中文）：agent 必须登记到 city 后台才“有效”，因此 city 未启动时拒绝写入 registry。
-  if (!(await isCityRunning())) {
-    throw new Error("city runtime is not running");
-  }
-
-  const projectRoot = normalizeProjectRoot(input.projectRoot);
-  const pid = normalizePid(input.pid);
-  const nowIso = new Date().toISOString();
-
-  const registry = await readManagedAgentRegistry();
-  const index = registry.agents.findIndex((entry) => entry.projectRoot === projectRoot);
-  if (index >= 0) {
-    const existing = registry.agents[index];
-    registry.agents[index] = {
-      projectRoot,
-      pid,
-      startedAt: normalizeIsoTime(existing.startedAt || input.startedAt),
-      updatedAt: nowIso,
-      status: input.status === "stopped" ? "stopped" : "running",
-      stoppedAt:
-        input.status === "stopped"
-          ? normalizeIsoTime(input.stoppedAt || nowIso)
-          : undefined,
-    };
-  } else {
-    registry.agents.push({
-      projectRoot,
-      pid,
-      startedAt: normalizeIsoTime(input.startedAt),
-      updatedAt: nowIso,
-      status: input.status === "stopped" ? "stopped" : "running",
-      stoppedAt:
-        input.status === "stopped"
-          ? normalizeIsoTime(input.stoppedAt || nowIso)
-          : undefined,
-    });
-  }
-
-  registry.updatedAt = nowIso;
-  await writeManagedAgentRegistry(registry);
-}
-
-/**
- * 标记 agent 为 stopped（保留历史记录，不删除）。
- */
-export async function markManagedAgentStopped(projectRoot: string): Promise<void> {
-  const key = normalizeProjectRoot(projectRoot);
-  const registry = await readManagedAgentRegistry();
-  const index = registry.agents.findIndex((entry) => entry.projectRoot === key);
-  if (index < 0) return;
-  const nowIso = new Date().toISOString();
-  const current = registry.agents[index];
-  registry.agents[index] = {
-    ...current,
-    status: "stopped",
-    stoppedAt: nowIso,
-    updatedAt: nowIso,
-  };
-  registry.updatedAt = nowIso;
-  await writeManagedAgentRegistry(registry);
-}
-
-/**
- * 按 projectRoot 移除一条 agent 记录。
- */
-export async function removeManagedAgentEntry(projectRoot: string): Promise<void> {
-  const key = normalizeProjectRoot(projectRoot);
-  const registry = await readManagedAgentRegistry();
-  const nextAgents = registry.agents.filter((entry) => entry.projectRoot !== key);
-  if (nextAgents.length === registry.agents.length) return;
-  registry.agents = nextAgents;
-  registry.updatedAt = new Date().toISOString();
-  await writeManagedAgentRegistry(registry);
-}