@downcity/city 1.1.4 → 1.1.5

package/bin/process/daemon/Manager.js

@@ -0,0 +1,287 @@
+/**
+ * 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, } from "@downcity/agent";
+import { markManagedAgentStopped, upsertManagedAgentEntry, } from "../../process/registry/CityRegistry.js";
+import { signalDetachedProcess } from "../../process/registry/ProcessSweep.js";
+/**
+ * 异步睡眠工具。
+ */
+const sleep = async (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+ * 计算 daemon pid 文件路径。
+ */
+export const getDaemonPidPath = (projectRoot) => path.join(getDowncityDebugDirPath(projectRoot), DAEMON_PID_FILENAME);
+/**
+ * 计算 daemon 日志文件路径。
+ */
+export const getDaemonLogPath = (projectRoot) => path.join(getDowncityDebugDirPath(projectRoot), DAEMON_LOG_FILENAME);
+/**
+ * 计算 daemon 元数据文件路径。
+ */
+export const getDaemonMetaPath = (projectRoot) => path.join(getDowncityDebugDirPath(projectRoot), DAEMON_META_FILENAME);
+/**
+ * 读取 daemon pid。
+ *
+ * 关键点（中文）
+ * - 读取失败或内容非法统一返回 `null`，调用方走无进程分支。
+ */
+export const readDaemonPid = async (projectRoot) => {
+    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) => {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+/**
+ * 读取 daemon meta（宽松模式）。
+ *
+ * 关键点（中文）
+ * - 返回 null 表示文件缺失、解析失败或结构非法。
+ * - 该函数用于状态展示，不抛异常。
+ */
+export const readDaemonMeta = async (projectRoot) => {
+    try {
+        const value = await fs.readJson(getDaemonMetaPath(projectRoot));
+        const pid = Number(value?.pid);
+        if (!Number.isFinite(pid) || pid <= 0)
+            return null;
+        const startedAt = String(value?.startedAt || "").trim();
+        if (!startedAt)
+            return null;
+        const command = String(value?.command || "").trim();
+        const project = String(value?.projectRoot || "").trim();
+        if (!command || !project)
+            return null;
+        return value;
+    }
+    catch {
+        return null;
+    }
+};
+/**
+ * 诊断 stale 原因。
+ */
+export const diagnoseDaemonStaleReasons = async (projectRoot, pid) => {
+    const reasons = [];
+    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) => {
+    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, meta) => {
+    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) => {
+    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 = {
+        ...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) => {
+    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 };
+};
+//# sourceMappingURL=Manager.js.map

package/bin/process/daemon/Manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Manager.js","sourceRoot":"","sources":["../../../src/process/daemon/Manager.ts"],"names":[],"mappings":"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"}

package/bin/process/daemon/PortAllocator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PortAllocator.d.ts","sourceRoot":"","sources":["../../../src/process/daemon/PortAllocator.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAQH,KAAK,kBAAkB,GAAG;IACxB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAyBF;;GAEG;AACH,wBAAsB,qBAAqB,CACzC,MAAM,GAAE,kBAAuB,GAC9B,OAAO,CAAC,MAAM,CAAC,CAejB"}

package/bin/process/daemon/PortAllocator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PortAllocator.js","sourceRoot":"","sources":["../../../src/process/daemon/PortAllocator.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,GAAG,MAAM,UAAU,CAAC;AAE3B,MAAM,wBAAwB,GAAG,IAAI,CAAC;AACtC,MAAM,sBAAsB,GAAG,IAAI,CAAC;AACpC,MAAM,cAAc,GAAG,IAAI,GAAG,CAAS,CAAC,IAAI,CAAC,CAAC,CAAC;AAQ/C,SAAS,WAAW,CAAC,IAAY;IAC/B,OAAO,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,IAAI,IAAI,IAAI,KAAK,CAAC;AAC9D,CAAC;AAED;;;;;GAKG;AACH,KAAK,UAAU,aAAa,CAAC,IAAY,EAAE,IAAY;IACrD,OAAO,MAAM,IAAI,OAAO,CAAU,CAAC,OAAO,EAAE,EAAE;QAC5C,MAAM,MAAM,GAAG,GAAG,CAAC,YAAY,EAAE,CAAC;QAClC,MAAM,CAAC,KAAK,EAAE,CAAC;QACf,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,EAAE;YACxB,OAAO,CAAC,KAAK,CAAC,CAAC;QACjB,CAAC,CAAC,CAAC;QACH,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE;YAC7B,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;QACpC,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,SAA6B,EAAE;IAE/B,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,IAAI,wBAAwB,CAAC;IACvD,MAAM,GAAG,GAAG,MAAM,CAAC,GAAG,IAAI,sBAAsB,CAAC;IACjD,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,IAAI,SAAS,CAAC,CAAC,IAAI,EAAE,IAAI,SAAS,CAAC;IAClE,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,IAAI,KAAK,GAAG,GAAG,EAAE,CAAC;QAC5D,MAAM,IAAI,KAAK,CAAC,uBAAuB,KAAK,IAAI,GAAG,EAAE,CAAC,CAAC;IACzD,CAAC;IAED,KAAK,IAAI,IAAI,GAAG,KAAK,EAAE,IAAI,IAAI,GAAG,EAAE,IAAI,IAAI,CAAC,EAAE,CAAC;QAC9C,IAAI,cAAc,CAAC,GAAG,CAAC,IAAI,CAAC;YAAE,SAAS;QACvC,sCAAsC;QACtC,IAAI,MAAM,aAAa,CAAC,IAAI,EAAE,IAAI,CAAC;YAAE,OAAO,IAAI,CAAC;IACnD,CAAC;IAED,MAAM,IAAI,KAAK,CAAC,8BAA8B,KAAK,IAAI,GAAG,aAAa,IAAI,EAAE,CAAC,CAAC;AACjF,CAAC"}

package/bin/process/registry/AgentHostRuntime.d.ts

@@ -0,0 +1,10 @@
+import type { AgentPathRuntime, AgentPluginConfigRuntime } from "@downcity/agent";
+/**
+ * 创建当前项目的路径能力集合。
+ */
+export declare function createAgentPathRuntime(projectRoot: string): AgentPathRuntime;
+/**
+ * 创建 plugin 配置持久化能力集合。
+ */
+export declare function createAgentPluginConfigRuntime(projectRoot: string): AgentPluginConfigRuntime;
+//# sourceMappingURL=AgentHostRuntime.d.ts.map

package/bin/process/registry/AgentHostRuntime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentHostRuntime.d.ts","sourceRoot":"","sources":["../../../src/process/registry/AgentHostRuntime.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EACV,gBAAgB,EAChB,wBAAwB,EACzB,MAAM,iBAAiB,CAAC;AAGzB;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,WAAW,EAAE,MAAM,GAAG,gBAAgB,CAgB5E;AAED;;GAEG;AACH,wBAAgB,8BAA8B,CAAC,WAAW,EAAE,MAAM,GAAG,wBAAwB,CAY5F"}

package/bin/process/registry/AgentHostRuntime.js

@@ -0,0 +1,47 @@
+/**
+ * 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";
+/**
+ * 创建当前项目的路径能力集合。
+ */
+export function createAgentPathRuntime(projectRoot) {
+    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) {
+    const rootPath = String(projectRoot || "").trim();
+    return {
+        async persistProjectPlugins(plugins) {
+            return persistProjectPluginConfig({
+                projectRoot: rootPath,
+                sections: {
+                    ...(plugins !== undefined ? { plugins } : {}),
+                },
+            });
+        },
+    };
+}
+//# sourceMappingURL=AgentHostRuntime.js.map

package/bin/process/registry/AgentHostRuntime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentHostRuntime.js","sourceRoot":"","sources":["../../../src/process/registry/AgentHostRuntime.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EACL,eAAe,EACf,yBAAyB,EACzB,0BAA0B,EAC1B,0BAA0B,EAC1B,kBAAkB,EAClB,6BAA6B,EAC7B,0BAA0B,EAC1B,0BAA0B,EAC1B,6BAA6B,EAC7B,yBAAyB,EACzB,6BAA6B,GAC9B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,0BAA0B,EAAE,MAAM,iBAAiB,CAAC;AAO7D;;GAEG;AACH,MAAM,UAAU,sBAAsB,CAAC,WAAmB;IACxD,MAAM,QAAQ,GAAG,MAAM,CAAC,WAAW,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IAClD,OAAO;QACL,WAAW,EAAE,QAAQ;QACrB,kBAAkB,EAAE,GAAG,EAAE,CAAC,kBAAkB,CAAC,QAAQ,CAAC;QACtD,eAAe,EAAE,GAAG,EAAE,CAAC,eAAe,CAAC,QAAQ,CAAC;QAChD,yBAAyB,EAAE,GAAG,EAAE,CAAC,yBAAyB,CAAC,QAAQ,CAAC;QACpE,0BAA0B,EAAE,GAAG,EAAE,CAAC,0BAA0B,CAAC,QAAQ,CAAC;QACtE,0BAA0B,EAAE,CAAC,SAAS,EAAE,EAAE,CAAC,0BAA0B,CAAC,QAAQ,EAAE,SAAS,CAAC;QAC1F,0BAA0B,EAAE,GAAG,EAAE,CAAC,0BAA0B,CAAC,QAAQ,CAAC;QACtE,6BAA6B,EAAE,GAAG,EAAE,CAAC,6BAA6B,CAAC,QAAQ,CAAC;QAC5E,6BAA6B,EAAE,GAAG,EAAE,CAAC,6BAA6B,CAAC,QAAQ,CAAC;QAC5E,0BAA0B,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,0BAA0B,CAAC,QAAQ,EAAE,IAAI,CAAC;QAChF,6BAA6B,EAAE,GAAG,EAAE,CAAC,6BAA6B,CAAC,QAAQ,CAAC;QAC5E,yBAAyB,EAAE,CAAC,SAAS,EAAE,EAAE,CAAC,yBAAyB,CAAC,QAAQ,EAAE,SAAS,CAAC;KACzF,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,8BAA8B,CAAC,WAAmB;IAChE,MAAM,QAAQ,GAAG,MAAM,CAAC,WAAW,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IAClD,OAAO;QACL,KAAK,CAAC,qBAAqB,CAAC,OAA8C;YACxE,OAAO,0BAA0B,CAAC;gBAChC,WAAW,EAAE,QAAQ;gBACrB,QAAQ,EAAE;oBACR,GAAG,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;iBAC9C;aACF,CAAC,CAAC;QACL,CAAC;KACF,CAAC;AACJ,CAAC"}

package/bin/process/registry/CityPaths.d.ts

@@ -0,0 +1,53 @@
+/**
+ * CityPaths：city 全局运行态与 control plane 共享的路径规则。
+ *
+ * 关键点（中文）
+ * - Downcity 的全局根目录固定在用户目录 `~/.downcity/`。
+ * - `~/.downcity/downcity.db`：全局 SQLite 数据库，保存模型池与平台级配置。
+ * - `~/.downcity/main/*`：city 后台与 control plane 共享的运行文件目录。
+ * - 这里定义的是“全局路径约定”，不是单个 agent 项目的 `.downcity/` 路径。
+ */
+/**
+ * 全局根目录（用户级）。
+ *
+ * 关键点（中文）
+ * - 测试或多实例隔离场景可通过 `DC_PLATFORM_ROOT` 显式覆盖。
+ */
+export declare function getPlatformRootDirPath(): string;
+/**
+ * 全局 SQLite 数据库路径（用户级）。
+ */
+export declare function getPlatformStoreDbPath(): string;
+/**
+ * city 全局运行目录（pid/log/registry）。
+ */
+export declare function getCityRuntimeDirPath(): string;
+/**
+ * 全局模型存储密钥文件路径。
+ */
+export declare function getPlatformStoreKeyPath(): string;
+/**
+ * city 后台 pid 文件路径。
+ */
+export declare function getCityPidPath(): string;
+/**
+ * city 后台日志路径（stdout/stderr 合并）。
+ */
+export declare function getCityLogPath(): string;
+/**
+ * control plane pid 文件路径。
+ */
+export declare function getControlPlanePidPath(): string;
+/**
+ * control plane 日志路径（stdout/stderr 合并）。
+ */
+export declare function getControlPlaneLogPath(): string;
+/**
+ * control plane 元数据路径。
+ */
+export declare function getControlPlaneMetaPath(): string;
+/**
+ * 受管 agent registry 文件路径（city 维护的 agent 清单）。
+ */
+export declare function getManagedAgentRegistryPath(): string;
+//# sourceMappingURL=CityPaths.d.ts.map

package/bin/process/registry/CityPaths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CityPaths.d.ts","sourceRoot":"","sources":["../../../src/process/registry/CityPaths.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH;;;;;GAKG;AACH,wBAAgB,sBAAsB,IAAI,MAAM,CAI/C;AAED;;GAEG;AACH,wBAAgB,sBAAsB,IAAI,MAAM,CAE/C;AAED;;GAEG;AACH,wBAAgB,qBAAqB,IAAI,MAAM,CAE9C;AAED;;GAEG;AACH,wBAAgB,uBAAuB,IAAI,MAAM,CAEhD;AAED;;GAEG;AACH,wBAAgB,cAAc,IAAI,MAAM,CAEvC;AAED;;GAEG;AACH,wBAAgB,cAAc,IAAI,MAAM,CAEvC;AAED;;GAEG;AACH,wBAAgB,sBAAsB,IAAI,MAAM,CAE/C;AAED;;GAEG;AACH,wBAAgB,sBAAsB,IAAI,MAAM,CAE/C;AAED;;GAEG;AACH,wBAAgB,uBAAuB,IAAI,MAAM,CAEhD;AAED;;GAEG;AACH,wBAAgB,2BAA2B,IAAI,MAAM,CAEpD"}

package/bin/process/registry/CityPaths.js

@@ -0,0 +1,78 @@
+/**
+ * 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";
+/**
+ * 全局根目录（用户级）。
+ *
+ * 关键点（中文）
+ * - 测试或多实例隔离场景可通过 `DC_PLATFORM_ROOT` 显式覆盖。
+ */
+export function getPlatformRootDirPath() {
+    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() {
+    return path.join(getPlatformRootDirPath(), "downcity.db");
+}
+/**
+ * city 全局运行目录（pid/log/registry）。
+ */
+export function getCityRuntimeDirPath() {
+    return path.join(getPlatformRootDirPath(), "main");
+}
+/**
+ * 全局模型存储密钥文件路径。
+ */
+export function getPlatformStoreKeyPath() {
+    return path.join(getCityRuntimeDirPath(), "model-db.key");
+}
+/**
+ * city 后台 pid 文件路径。
+ */
+export function getCityPidPath() {
+    return path.join(getCityRuntimeDirPath(), "city.pid");
+}
+/**
+ * city 后台日志路径（stdout/stderr 合并）。
+ */
+export function getCityLogPath() {
+    return path.join(getCityRuntimeDirPath(), "city.log");
+}
+/**
+ * control plane pid 文件路径。
+ */
+export function getControlPlanePidPath() {
+    return path.join(getCityRuntimeDirPath(), "control-plane.pid");
+}
+/**
+ * control plane 日志路径（stdout/stderr 合并）。
+ */
+export function getControlPlaneLogPath() {
+    return path.join(getCityRuntimeDirPath(), "control-plane.log");
+}
+/**
+ * control plane 元数据路径。
+ */
+export function getControlPlaneMetaPath() {
+    return path.join(getCityRuntimeDirPath(), "control-plane.json");
+}
+/**
+ * 受管 agent registry 文件路径（city 维护的 agent 清单）。
+ */
+export function getManagedAgentRegistryPath() {
+    return path.join(getCityRuntimeDirPath(), "agents.json");
+}
+//# sourceMappingURL=CityPaths.js.map

package/bin/process/registry/CityPaths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CityPaths.js","sourceRoot":"","sources":["../../../src/process/registry/CityPaths.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B;;;;;GAKG;AACH,MAAM,UAAU,sBAAsB;IACpC,MAAM,YAAY,GAAG,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,gBAAgB,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IACvE,IAAI,YAAY;QAAE,OAAO,IAAI,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC;IACpD,OAAO,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,WAAW,CAAC,CAAC;AAC9C,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,sBAAsB;IACpC,OAAO,IAAI,CAAC,IAAI,CAAC,sBAAsB,EAAE,EAAE,aAAa,CAAC,CAAC;AAC5D,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,qBAAqB;IACnC,OAAO,IAAI,CAAC,IAAI,CAAC,sBAAsB,EAAE,EAAE,MAAM,CAAC,CAAC;AACrD,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,uBAAuB;IACrC,OAAO,IAAI,CAAC,IAAI,CAAC,qBAAqB,EAAE,EAAE,cAAc,CAAC,CAAC;AAC5D,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,cAAc;IAC5B,OAAO,IAAI,CAAC,IAAI,CAAC,qBAAqB,EAAE,EAAE,UAAU,CAAC,CAAC;AACxD,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,cAAc;IAC5B,OAAO,IAAI,CAAC,IAAI,CAAC,qBAAqB,EAAE,EAAE,UAAU,CAAC,CAAC;AACxD,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,sBAAsB;IACpC,OAAO,IAAI,CAAC,IAAI,CAAC,qBAAqB,EAAE,EAAE,mBAAmB,CAAC,CAAC;AACjE,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,sBAAsB;IACpC,OAAO,IAAI,CAAC,IAAI,CAAC,qBAAqB,EAAE,EAAE,mBAAmB,CAAC,CAAC;AACjE,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,uBAAuB;IACrC,OAAO,IAAI,CAAC,IAAI,CAAC,qBAAqB,EAAE,EAAE,oBAAoB,CAAC,CAAC;AAClE,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,2BAA2B;IACzC,OAAO,IAAI,CAAC,IAAI,CAAC,qBAAqB,EAAE,EAAE,aAAa,CAAC,CAAC;AAC3D,CAAC"}

package/bin/process/registry/CityRegistry.d.ts

@@ -0,0 +1,51 @@
+/**
+ * CityRegistry：city 后台维护的 agent registry（`~/.downcity/main/agents.json`）。
+ *
+ * 关键点（中文）
+ * - registry 只维护“city 认知到的 agent 项目列表”，用于统一观测与批量管理。
+ * - registry 不承载实时健康检查：status/list 会读取每个项目的 daemon pid 并判活。
+ * - agent daemon 启动成功后必须登记到 city 后台（强约束）。
+ */
+import type { ManagedAgentRegistryEntry, ManagedAgentRegistryV1 } from "@downcity/agent";
+/**
+ * 确保 city agent registry 文件存在。
+ *
+ * 关键点（中文）
+ * - 空 city 运行态也应拥有显式的空 registry，避免 Console 将“尚未启动任何 agent”误判为异常。
+ * - 若文件已存在则不覆盖，保持历史记录不丢失。
+ */
+export declare function ensureManagedAgentRegistry(): Promise<void>;
+/**
+ * 获取 city agent registry 文件路径。
+ */
+export declare function getManagedAgentsRegistryPath(): string;
+/**
+ * 读取 city agent registry（容错）。
+ *
+ * 关键点（中文）
+ * - 文件不存在或损坏时返回空 registry，避免影响主流程。
+ */
+export declare function readManagedAgentRegistry(): Promise<ManagedAgentRegistryV1>;
+/**
+ * 列出 city registry 中记录的 agent（按 projectRoot 排序）。
+ */
+export declare function listManagedAgentEntries(): Promise<ManagedAgentRegistryEntry[]>;
+/**
+ * 新增或更新一条 city agent 记录。
+ */
+export declare function upsertManagedAgentEntry(input: {
+    projectRoot: string;
+    pid: number;
+    startedAt?: string;
+    status?: "running" | "stopped";
+    stoppedAt?: string;
+}): Promise<void>;
+/**
+ * 标记 agent 为 stopped（保留历史记录，不删除）。
+ */
+export declare function markManagedAgentStopped(projectRoot: string): Promise<void>;
+/**
+ * 按 projectRoot 移除一条 agent 记录。
+ */
+export declare function removeManagedAgentEntry(projectRoot: string): Promise<void>;
+//# sourceMappingURL=CityRegistry.d.ts.map

package/bin/process/registry/CityRegistry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CityRegistry.d.ts","sourceRoot":"","sources":["../../../src/process/registry/CityRegistry.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EACV,yBAAyB,EACzB,sBAAsB,EACvB,MAAM,iBAAiB,CAAC;AA8GzB;;;;;;GAMG;AACH,wBAAsB,0BAA0B,IAAI,OAAO,CAAC,IAAI,CAAC,CAMhE;AAED;;GAEG;AACH,wBAAgB,4BAA4B,IAAI,MAAM,CAErD;AAED;;;;;GAKG;AACH,wBAAsB,wBAAwB,IAAI,OAAO,CAAC,sBAAsB,CAAC,CAUhF;AAED;;GAEG;AACH,wBAAsB,uBAAuB,IAAI,OAAO,CAAC,yBAAyB,EAAE,CAAC,CAGpF;AAED;;GAEG;AACH,wBAAsB,uBAAuB,CAAC,KAAK,EAAE;IACnD,WAAW,EAAE,MAAM,CAAC;IACpB,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,SAAS,GAAG,SAAS,CAAC;IAC/B,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,GAAG,OAAO,CAAC,IAAI,CAAC,CAyChB;AAED;;GAEG;AACH,wBAAsB,uBAAuB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAehF;AAED;;GAEG;AACH,wBAAsB,uBAAuB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAQhF"}