@downcity/agent 1.1.1

package/src/runtime/CityRegistry.ts

@@ -0,0 +1,256 @@
+/**
+ * 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 {
+  ConsoleAgentRegistryEntry,
+  ConsoleAgentRegistryV1,
+} from "@/shared/types/Console.js";
+import { getConsoleAgentRegistryPath, getCityRuntimeDirPath } from "./CityPaths.js";
+import { isCityRunning } from "./CityRuntime.js";
+
+const CONSOLE_DIR = getCityRuntimeDirPath();
+const CONSOLE_AGENTS_FILE = getConsoleAgentRegistryPath();
+
+function buildEmptyRegistry(): ConsoleAgentRegistryV1 {
+  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<ConsoleAgentRegistryEntry>,
+): ConsoleAgentRegistryEntry | 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<ConsoleAgentRegistryV1> | null | undefined,
+): ConsoleAgentRegistryV1 {
+  if (!value || typeof value !== "object") return buildEmptyRegistry();
+  const source = Array.isArray(value.agents) ? value.agents : [];
+  const normalizedAgents: ConsoleAgentRegistryEntry[] = [];
+  for (const item of source) {
+    if (!item || typeof item !== "object") continue;
+    const normalized = normalizeRegistryEntry(item as ConsoleAgentRegistryEntry);
+    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 writeConsoleAgentRegistry(
+  registry: ConsoleAgentRegistryV1,
+): Promise<void> {
+  await fs.ensureDir(CONSOLE_DIR);
+  await fs.writeJson(CONSOLE_AGENTS_FILE, normalizeRegistry(registry), {
+    spaces: 2,
+  });
+}
+
+/**
+ * 确保 city agent registry 文件存在。
+ *
+ * 关键点（中文）
+ * - 空 city 运行态也应拥有显式的空 registry，避免 Console 将“尚未启动任何 agent”误判为异常。
+ * - 若文件已存在则不覆盖，保持历史记录不丢失。
+ */
+export async function ensureConsoleAgentRegistry(): Promise<void> {
+  await fs.ensureDir(CONSOLE_DIR);
+  if (await fs.pathExists(CONSOLE_AGENTS_FILE)) {
+    return;
+  }
+  await writeConsoleAgentRegistry(buildEmptyRegistry());
+}
+
+/**
+ * 获取 city agent registry 文件路径。
+ */
+export function getConsoleAgentsRegistryPath(): string {
+  return CONSOLE_AGENTS_FILE;
+}
+
+/**
+ * 读取 city agent registry（容错）。
+ *
+ * 关键点（中文）
+ * - 文件不存在或损坏时返回空 registry，避免影响主流程。
+ */
+export async function readConsoleAgentRegistry(): Promise<ConsoleAgentRegistryV1> {
+  try {
+    if (!(await fs.pathExists(CONSOLE_AGENTS_FILE))) {
+      return buildEmptyRegistry();
+    }
+    const raw = (await fs.readJson(CONSOLE_AGENTS_FILE)) as Partial<ConsoleAgentRegistryV1>;
+    return normalizeRegistry(raw);
+  } catch {
+    return buildEmptyRegistry();
+  }
+}
+
+/**
+ * 列出 city registry 中记录的 agent（按 projectRoot 排序）。
+ */
+export async function listConsoleAgents(): Promise<ConsoleAgentRegistryEntry[]> {
+  const registry = await readConsoleAgentRegistry();
+  return [...registry.agents].sort((a, b) => a.projectRoot.localeCompare(b.projectRoot));
+}
+
+/**
+ * 新增或更新一条 city agent 记录。
+ */
+export async function upsertConsoleAgentEntry(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 readConsoleAgentRegistry();
+  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 writeConsoleAgentRegistry(registry);
+}
+
+/**
+ * 标记 agent 为 stopped（保留历史记录，不删除）。
+ */
+export async function markConsoleAgentStopped(projectRoot: string): Promise<void> {
+  const key = normalizeProjectRoot(projectRoot);
+  const registry = await readConsoleAgentRegistry();
+  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 writeConsoleAgentRegistry(registry);
+}
+
+/**
+ * 按 projectRoot 移除一条 agent 记录。
+ */
+export async function removeConsoleAgentEntry(projectRoot: string): Promise<void> {
+  const key = normalizeProjectRoot(projectRoot);
+  const registry = await readConsoleAgentRegistry();
+  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 writeConsoleAgentRegistry(registry);
+}

package/src/runtime/CityRuntime.ts

@@ -0,0 +1,45 @@
+/**
+ * CityRuntime：city 后台进程状态工具。
+ *
+ * 关键点（中文）
+ * - city 后台负责统一管理/观测多个 agent daemon。
+ * - 这里处理的是 city 后台自身的 pid 与判活，不涉及 Console 模块的 UI 进程。
+ * - agent daemon 启动前必须确保 city 后台已启动（强约束）。
+ */
+
+import fs from "fs-extra";
+import { getCityPidPath } from "./CityPaths.js";
+
+/**
+ * 读取 city 后台 pid（读取失败或内容非法返回 null）。
+ */
+export async function readCityPid(): Promise<number | null> {
+  try {
+    const raw = await fs.readFile(getCityPidPath(), "utf-8");
+    const pid = Number.parseInt(String(raw).trim(), 10);
+    return Number.isFinite(pid) && pid > 0 ? pid : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 判断 city 后台进程是否存活。
+ */
+export function isCityProcessAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * 判断 city 后台是否在运行（基于 pid file + 判活）。
+ */
+export async function isCityRunning(): Promise<boolean> {
+  const pid = await readCityPid();
+  if (!pid) return false;
+  return isCityProcessAlive(pid);
+}

package/src/runtime/PluginRuntime.ts

@@ -0,0 +1,42 @@
+/**
+ * PluginRuntime：city 级 plugin 运行时注入模块。
+ *
+ * 关键点（中文）
+ * - PluginRegistry / PluginManager 属于 city runtime，不应直接反向 import agent AgentContext 单例。
+ * - 当前模块只负责保存“当前执行上下文 resolver”的注入入口。
+ * - agent runtime 仅作为 context provider 注册方，不再成为 plugin manager 的宿主。
+ */
+
+import type { AgentContext } from "@/types/agent/AgentContext.js";
+
+type AgentContextResolver = () => AgentContext;
+
+let executionContextResolver: AgentContextResolver | null = null;
+
+/**
+ * 设置当前 city plugin runtime 的执行上下文 resolver。
+ */
+export function setPluginRuntimeContextResolver(
+  resolver: AgentContextResolver,
+): void {
+  executionContextResolver = resolver;
+}
+
+/**
+ * 清理当前 city plugin runtime 的执行上下文 resolver。
+ */
+export function clearPluginRuntimeContextResolver(): void {
+  executionContextResolver = null;
+}
+
+/**
+ * 读取当前 city plugin runtime 的执行上下文 resolver。
+ */
+export function getPluginRuntimeContextResolver(): AgentContextResolver {
+  if (!executionContextResolver) {
+    throw new Error(
+      "Plugin runtime context resolver is not configured. Configure city plugin runtime before using PluginManager.",
+    );
+  }
+  return executionContextResolver;
+}

package/src/runtime/ProcessSweep.ts

@@ -0,0 +1,239 @@
+/**
+ * 孤儿进程清扫工具。
+ *
+ * 关键点（中文）
+ * - 处理“pid 文件不存在，但旧的 detached 进程还活着”的场景。
+ * - 仅匹配 Downcity CLI 自己拉起的 `run` / `console run` / `agent start --foreground true`。
+ * - 作为 stop/start 的兜底清理层，避免旧版本进程占住端口却无法被当前 pid 文件追踪。
+ * - `run` 指 city 后台，`console run` 指 Console 模块，二者需要明确区分。
+ */
+
+import { execFile as execFileCb } from "node:child_process";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFileCb);
+
+function isProcessAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function normalizeCommand(command: string): string {
+  return String(command || "").replace(/\s+/g, " ").trim();
+}
+
+/**
+ * 构建 detached 进程停机时的信号目标。
+ *
+ * 关键点（中文）
+ * - POSIX 下 `detached: true` 会让子进程成为新的进程组 leader。
+ * - `-pid` 表示向整个进程组发信号，可覆盖 ACP、shell、watcher 等孙进程。
+ * - Windows 不支持负 pid 进程组语义，只能回退到单 pid。
+ */
+export function buildDetachedProcessSignalTargets(pid: number): number[] {
+  if (!Number.isInteger(pid) || pid <= 0) return [];
+  if (process.platform === "win32") return [pid];
+  return [-pid, pid];
+}
+
+/**
+ * 向 detached 进程发送信号。
+ *
+ * 关键点（中文）
+ * - 优先发送到进程组；失败后再尝试单 pid。
+ * - 返回值只表示至少有一个目标接收到了信号，不代表进程已经退出。
+ */
+export function signalDetachedProcess(
+  pid: number,
+  signal: NodeJS.Signals,
+): boolean {
+  for (const target of buildDetachedProcessSignalTargets(pid)) {
+    try {
+      process.kill(target, signal);
+      return true;
+    } catch {
+      // 尝试下一个目标。
+    }
+  }
+  return false;
+}
+
+export function isDowncityCliCommand(command: string): boolean {
+  return /\/bin\/main\/modules\/cli\/Index\.js(?:\s|$)/.test(command);
+}
+
+/**
+ * 判断命令行是否属于本次清扫目标。
+ *
+ * 关键点（中文）
+ * - `Index.js run` 是 city runtime。
+ * - `Index.js console run` 是 Console UI runtime。
+ * - 两者都包含 `run`，因此必须按完整子命令匹配，不能只查 `run` 词元。
+ */
+export function shouldSweepDetachedCityCommand(
+  command: string,
+  params: {
+    includeConsole?: boolean;
+    includeUi?: boolean;
+    includeAgent?: boolean;
+  },
+): boolean {
+  if (!isDowncityCliCommand(command)) return false;
+  if (
+    params.includeConsole &&
+    /\/bin\/main\/modules\/cli\/Index\.js\s+run(?:\s|$)/.test(command)
+  ) {
+    return true;
+  }
+  if (
+    params.includeUi &&
+    /\/bin\/main\/modules\/cli\/Index\.js\s+console\s+run(?:\s|$)/.test(command)
+  ) {
+    return true;
+  }
+  if (
+    params.includeAgent &&
+    /\/bin\/main\/modules\/cli\/Index\.js\s+agent\s+start(?:\s|$)/.test(command) &&
+    /--foreground\s+true\b/.test(command)
+  ) {
+    return true;
+  }
+  return false;
+}
+
+async function listDetachedCityProcesses(params: {
+  includeConsole?: boolean;
+  includeUi?: boolean;
+  includeAgent?: boolean;
+  excludePids: Set<number>;
+}): Promise<Array<{ pid: number; command: string }>> {
+  if (process.platform === "win32") {
+    return [];
+  }
+
+  try {
+    const { stdout } = await execFileAsync(
+      "ps",
+      ["-axo", "pid=,command="],
+      {
+        maxBuffer: 1024 * 1024,
+      },
+    );
+
+    return String(stdout || "")
+      .split("\n")
+      .map((line) => line.match(/^\s*(\d+)\s+(.*)$/))
+      .filter((item): item is RegExpMatchArray => Boolean(item))
+      .map((item) => ({
+        pid: Number.parseInt(item[1] || "", 10),
+        command: normalizeCommand(item[2] || ""),
+      }))
+      .filter((item) => Number.isInteger(item.pid) && item.pid > 0)
+      .filter((item) => !params.excludePids.has(item.pid))
+      .filter((item) => shouldSweepDetachedCityCommand(item.command, params));
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * 只探测失联的 Downcity detached 进程，不执行停止动作。
+ */
+export async function findDetachedCityProcesses(params?: {
+  includeConsole?: boolean;
+  includeUi?: boolean;
+  includeAgent?: boolean;
+  excludePids?: number[];
+}): Promise<Array<{ pid: number; command: string }>> {
+  const excludePids = new Set<number>([
+    process.pid,
+    ...(Array.isArray(params?.excludePids) ? params.excludePids : []),
+  ]);
+
+  return listDetachedCityProcesses({
+    includeConsole: params?.includeConsole,
+    includeUi: params?.includeUi,
+    includeAgent: params?.includeAgent,
+    excludePids,
+  });
+}
+
+async function stopPid(pid: number, timeoutMs: number): Promise<boolean> {
+  if (!isProcessAlive(pid)) return true;
+
+  if (!signalDetachedProcess(pid, "SIGTERM")) {
+    return !isProcessAlive(pid);
+  }
+
+  const termStart = Date.now();
+  while (Date.now() - termStart < timeoutMs) {
+    if (!isProcessAlive(pid)) return true;
+    await new Promise((resolve) => setTimeout(resolve, 200));
+  }
+
+  try {
+    if (isProcessAlive(pid)) {
+      signalDetachedProcess(pid, "SIGKILL");
+    }
+  } catch {
+    return !isProcessAlive(pid);
+  }
+
+  const killStart = Date.now();
+  while (Date.now() - killStart < 2_000) {
+    if (!isProcessAlive(pid)) return true;
+    await new Promise((resolve) => setTimeout(resolve, 100));
+  }
+
+  return !isProcessAlive(pid);
+}
+
+/**
+ * 清扫失联的 Downcity detached 进程。
+ */
+export async function sweepDetachedCityProcesses(params?: {
+  includeConsole?: boolean;
+  includeUi?: boolean;
+  includeAgent?: boolean;
+  timeoutMs?: number;
+  excludePids?: number[];
+}): Promise<{
+  matched: Array<{ pid: number; command: string }>;
+  stopped: Array<{ pid: number; command: string }>;
+  alive: Array<{ pid: number; command: string }>;
+}> {
+  const timeoutMs = params?.timeoutMs ?? 8_000;
+  const excludePids = new Set<number>([
+    process.pid,
+    ...(Array.isArray(params?.excludePids) ? params.excludePids : []),
+  ]);
+  const matched = await listDetachedCityProcesses({
+    includeConsole: params?.includeConsole,
+    includeUi: params?.includeUi,
+    includeAgent: params?.includeAgent,
+    excludePids,
+  });
+
+  const stopped: Array<{ pid: number; command: string }> = [];
+  const alive: Array<{ pid: number; command: string }> = [];
+
+  for (const item of matched) {
+    // 关键点（中文）：逐个停止，避免并发 kill 时输出与状态难以对应。
+    const ok = await stopPid(item.pid, timeoutMs);
+    if (ok) {
+      stopped.push(item);
+    } else {
+      alive.push(item);
+    }
+  }
+
+  return {
+    matched,
+    stopped,
+    alive,
+  };
+}