@ai-zen/agents-host 0.0.0-stage → 0.1.0-alpha.1

package/dist/cli.d.ts

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+/**
+ * 命令行入口（`bin.agents-host` → `dist/cli.js`）。
+ *
+ * 三组动作：
+ *   - `agents-host [serve]`：前台起服务。缺省是本地实例（只监听回环，凭证自动生成并写在
+ *     `<数据根>/run/token`）；`--public` 起对外实例，`--host` 指定监听地址；
+ *   - `agents-host token create|list|revoke`：**不开服务**，直接开库操作凭证（PRD L11 / F-E4）。
+ *     明文只在 `create` 的那一次输出里出现，此后库里只有摘要；
+ *   - `agents-host version`：版本与协议版本（升级判定要比这两个，PRD D4 / F-E3）。
+ *
+ * 参数解析是手写的：这个包不新增依赖，而命令形状就这么几种。解析失败给一句人话 + 退出码 2
+ * （「参数用法不对」与「运行失败」分开，脚本才好分支）；运行失败走 1，成功走 0。
+ *
+ * 错误一律走 i18n 渲染出的人话，不甩栈：命令行是给人看的，栈只在日志里有意义。
+ */
+/**
+ * 入口：返回退出码。
+ *
+ * 用法错误走 2、运行失败走 1、成功走 0 —— 脚本据此分支，不去解析句子。
+ */
+export declare function main(argv: readonly string[]): Promise<number>;

package/dist/cli.js

@@ -0,0 +1,354 @@
+#!/usr/bin/env node
+/**
+ * 命令行入口（`bin.agents-host` → `dist/cli.js`）。
+ *
+ * 三组动作：
+ *   - `agents-host [serve]`：前台起服务。缺省是本地实例（只监听回环，凭证自动生成并写在
+ *     `<数据根>/run/token`）；`--public` 起对外实例，`--host` 指定监听地址；
+ *   - `agents-host token create|list|revoke`：**不开服务**，直接开库操作凭证（PRD L11 / F-E4）。
+ *     明文只在 `create` 的那一次输出里出现，此后库里只有摘要；
+ *   - `agents-host version`：版本与协议版本（升级判定要比这两个，PRD D4 / F-E3）。
+ *
+ * 参数解析是手写的：这个包不新增依赖，而命令形状就这么几种。解析失败给一句人话 + 退出码 2
+ * （「参数用法不对」与「运行失败」分开，脚本才好分支）；运行失败走 1，成功走 0。
+ *
+ * 错误一律走 i18n 渲染出的人话，不甩栈：命令行是给人看的，栈只在日志里有意义。
+ */
+import { mkdir } from "node:fs/promises";
+import { createHost, resolveHostVersion } from "./app.js";
+import { readHostSettings, resolvePaths } from "./config.js";
+import { CredentialService } from "./services/index.js";
+import { CredentialRepository, Database, migrate } from "./storage/index.js";
+import { PROTOCOL_VERSION, HostError, toErrorData } from "./wire/index.js";
+/** 用法不对时的退出码（与「跑起来但失败了」区分开） */
+const EXIT_USAGE = 2;
+/** 运行期失败的退出码 */
+const EXIT_FAILURE = 1;
+/**
+ * 命令行的语言。
+ *
+ * 宿主的产品文案是「按连接的语言」渲染的（PRD D8），而命令行没有连接、也就没有协商入口，
+ * 所以它与自己的说明文字用同一种语言。这一点已在 `docs/plan-questions.md` 记过。
+ */
+const CLI_LANGUAGE = "zh";
+const USAGE = `用法：
+  agents-host [serve] [--port <端口>] [--host <地址>] [--local | --public] [--ai-zen-dir <目录>]
+      前台启动服务。缺省是本地实例（只监听 127.0.0.1，凭证自动生成并写在 <数据根>/run/token）。
+      端口的三档来源：--port > <数据根>/host.json 的 port > 默认 8790。
+      --port 0  让系统分配一个空闲端口（端口被占用时的退路，也是测试与冒烟用的写法）。
+      日志写在 <数据根>/logs/host.log（按大小轮转）。
+
+  agents-host token create [--note <备注>] [--ai-zen-dir <目录>]
+      新建一串凭证。明文只显示这一次。
+  agents-host token list [--ai-zen-dir <目录>]
+      列出全部凭证（含已吊销的）。
+  agents-host token revoke <凭证 id> [--ai-zen-dir <目录>]
+      单独吊销一串凭证。
+
+  agents-host version
+      打印宿主版本与协议版本。
+
+  --help / -h   打印这段说明。`;
+/** 参数用法错误：带着一句给人看的话，由入口翻成退出码 2 */
+class UsageError extends Error {
+}
+/**
+ * 解析命令行。
+ *
+ * 顺序不敏感（`--port` 可以写在子命令前后）：脚本里两种写法都有人用，为此出错不值当。
+ */
+function parseArgs(argv) {
+    const parsed = { command: "serve", local: true };
+    const words = [];
+    /** `--local` / `--public` 有没有被人明确写出来（用来发现与 `--host` 的矛盾） */
+    let localGiven = false;
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index] ?? "";
+        switch (arg) {
+            case "-h":
+            case "--help":
+                parsed.command = "help";
+                return parsed;
+            case "--local":
+                parsed.local = true;
+                localGiven = true;
+                break;
+            case "--public":
+                parsed.local = false;
+                localGiven = true;
+                break;
+            case "--port": {
+                const value = argv[index + 1];
+                if (value === undefined)
+                    throw new UsageError("--port 后面要跟一个端口号");
+                parsed.port = parsePort(value);
+                index += 1;
+                break;
+            }
+            case "--host": {
+                const value = argv[index + 1];
+                if (value === undefined || value.trim() === "") {
+                    throw new UsageError("--host 后面要跟一个监听地址");
+                }
+                parsed.host = value.trim();
+                index += 1;
+                break;
+            }
+            case "--note": {
+                const value = argv[index + 1];
+                if (value === undefined)
+                    throw new UsageError("--note 后面要跟一句备注");
+                parsed.note = value;
+                index += 1;
+                break;
+            }
+            case "--ai-zen-dir": {
+                const value = argv[index + 1];
+                if (value === undefined || value.trim() === "") {
+                    throw new UsageError("--ai-zen-dir 后面要跟一个目录");
+                }
+                parsed.aiZenDir = value;
+                index += 1;
+                break;
+            }
+            default:
+                if (arg.startsWith("-"))
+                    throw new UsageError(`不认识的参数：${arg}`);
+                words.push(arg);
+        }
+    }
+    const [head, ...rest] = words;
+    if (head !== undefined) {
+        if (head === "serve") {
+            if (rest.length > 0)
+                throw new UsageError(`serve 不接受多余的位置参数：${rest.join(" ")}`);
+            parsed.command = "serve";
+        }
+        else if (head === "version") {
+            if (rest.length > 0)
+                throw new UsageError(`version 不接受位置参数：${rest.join(" ")}`);
+            parsed.command = "version";
+        }
+        else if (head === "token") {
+            applyTokenArgs(parsed, rest);
+        }
+        else {
+            throw new UsageError(`不认识的命令：${head}`);
+        }
+    }
+    // 监听地址决定了这是哪种实例（PRD A6：本地实例只监听回环）
+    if (parsed.host !== undefined) {
+        if (isLoopbackHost(parsed.host)) {
+            parsed.local = true;
+        }
+        else if (localGiven && parsed.local) {
+            throw new UsageError(`--local 与对外地址 ${parsed.host} 互相矛盾：本地实例只监听回环`);
+        }
+        else {
+            parsed.local = false;
+        }
+    }
+    return parsed;
+}
+function applyTokenArgs(parsed, rest) {
+    const [action, ...tail] = rest;
+    if (action === "create" || action === "list") {
+        if (tail.length > 0)
+            throw new UsageError(`token ${action} 不接受位置参数：${tail.join(" ")}`);
+        parsed.command = "token";
+        parsed.action = action;
+        return;
+    }
+    if (action === "revoke") {
+        const id = tail[0];
+        if (id === undefined)
+            throw new UsageError("token revoke 后面要跟一个凭证 id");
+        if (tail.length > 1)
+            throw new UsageError(`token revoke 只接受一个 id：${tail.join(" ")}`);
+        parsed.command = "token";
+        parsed.action = "revoke";
+        parsed.credentialId = id;
+        return;
+    }
+    throw new UsageError(`不认识的 token 动作：${action ?? "(空)"}（可用：create / list / revoke）`);
+}
+/**
+ * 端口：0..65535 的整数，`0` 表示让系统分配。
+ *
+ * 写错就当场说，不静默回落到默认端口（R12 的口径：静默回落会造成「我配了 9000 却在 8790 上」）。
+ */
+function parsePort(value) {
+    const port = Number(value);
+    if (!Number.isInteger(port) || port < 0 || port > 65535) {
+        throw new UsageError(`端口要写成 0..65535 的整数（0 表示让系统分配），收到的是：${value}`);
+    }
+    return port;
+}
+/** 这个地址是不是回环（本地实例只监听回环，PRD A6） */
+function isLoopbackHost(host) {
+    return host === "localhost" || host === "::1" || host.startsWith("127.");
+}
+/**
+ * 开库做一件凭证相关的事（不启服务）。
+ *
+ * 与 `HostApp` 用同一个库文件与同一套迁移：命令行建出来的凭证，起服务后立刻能用。
+ */
+async function withCredentials(paths, work) {
+    await mkdir(paths.dataRoot, { recursive: true });
+    const db = new Database(paths.dbFile);
+    try {
+        await migrate(db);
+        return await work(new CredentialService({ credentials: new CredentialRepository(db) }));
+    }
+    finally {
+        await db.close();
+    }
+}
+/** `token create`：明文只在这里出现一次 */
+async function runTokenCreate(paths, note) {
+    const result = await withCredentials(paths, (credentials) => credentials.create({ note: note ?? "" }));
+    process.stdout.write(`凭证已创建（id: ${result.credential.id}）\n`);
+    if (result.credential.note !== "")
+        process.stdout.write(`备注：${result.credential.note}\n`);
+    process.stdout.write(`\n${result.token}\n\n`);
+    process.stdout.write("上面这串凭证只显示这一次：宿主此后只保存它的摘要，丢了只能重新创建。\n");
+    process.stdout.write("把它分发给要连接这台宿主的设备，对方在握手时带上它即可。\n");
+}
+/** `token list`：连已吊销的一起列，吊销状态看中间那列 */
+async function runTokenList(paths) {
+    const result = await withCredentials(paths, (credentials) => credentials.list());
+    if (result.credentials.length === 0) {
+        process.stdout.write("还没有任何凭证。用 `agents-host token create --note <备注>` 创建一串。\n");
+        return;
+    }
+    for (const credential of result.credentials) {
+        const state = credential.revokedAt === null ? "有效" : `已吊销（${credential.revokedAt}）`;
+        process.stdout.write(`${credential.id}  ${state}  创建于 ${credential.createdAt}  ${credential.note}\n`);
+    }
+}
+/** `token revoke`：`revoked: false` 表示这串本来就已经吊销了（不是失败，R42） */
+async function runTokenRevoke(paths, credentialId) {
+    const result = await withCredentials(paths, (credentials) => credentials.revoke({ credentialId }));
+    process.stdout.write(result.revoked ? `已吊销：${credentialId}\n` : `这串凭证本来就已吊销：${credentialId}\n`);
+}
+/**
+ * `serve`：前台起服务。
+ *
+ * 启动后打印四样东西：实际监听地址（端口可能是系统分配的）、版本、发现文件、本地凭证交付文件
+ * —— 客户端要连的就是前两个，本机免输凭证靠的是第三个（PRD A5 / architecture §2）。
+ * 日志落在哪儿也报一行（PRD F-J2：界面被占满时那是唯一的去处）。
+ *
+ * 端口的三档来源（D25 / 裁定 R67）：`--port` > `<数据根>/host.json` 的 `port` > 默认 8790。
+ * 配置文件那一档在这里读：读坏了（不是 JSON、端口不合法）就当场失败，不静默回落。
+ *
+ * 同一个数据根上已经有人在服务时（单实例），本进程只是把那个地址报出来就退出：
+ * 两个进程各写一份 `host.json` 会让客户端连谁都不对。
+ */
+async function runServe(parsed) {
+    const paths = resolvePaths(parsed.aiZenDir);
+    // 参数给了端口就不读配置文件：那一档这时轮不到它说话
+    const configPort = parsed.port === undefined ? (await readHostSettings(paths)).port : undefined;
+    const app = await createHost({
+        aiZenDir: parsed.aiZenDir,
+        port: parsed.port,
+        configPort,
+        host: parsed.host,
+        local: parsed.local,
+    });
+    const target = await app.start();
+    if (app.attached) {
+        process.stdout.write(`已有宿主在运行：ws://${target.host}:${target.port}\n`);
+        process.stdout.write(`发现文件：${app.paths.hostFile}\n`);
+        process.stdout.write("本进程不重复监听，直接退出。\n");
+        await app.stop("requested");
+        return;
+    }
+    process.stdout.write(`宿主已启动：ws://${target.host}:${target.port}\n`);
+    process.stdout.write(`版本：${app.version}（协议 ${PROTOCOL_VERSION}）\n`);
+    process.stdout.write(`发现文件：${app.paths.hostFile}\n`);
+    process.stdout.write(`日志：${app.paths.logsDir}\n`);
+    if (app.local) {
+        process.stdout.write(`本地凭证交付文件：${app.paths.tokenFile}\n`);
+    }
+    else {
+        process.stdout.write("对外实例：用 `agents-host token create --note <备注>` 创建凭证，再分发给要连接的设备。\n");
+    }
+    // 优雅退出：等收尾做完（摘发现文件、断连接、回收 Scope、关库）再让进程走
+    const stop = () => {
+        void app.shutdown("requested");
+    };
+    process.once("SIGINT", stop);
+    process.once("SIGTERM", stop);
+}
+/** 版本：脚本里比对升级（PRD D4 / F-E3） */
+function runVersion() {
+    process.stdout.write(`@ai-zen/agents-host ${resolveHostVersion()}（协议 ${PROTOCOL_VERSION}）\n`);
+}
+/**
+ * 失败原因（人话）。
+ *
+ * `HostError` 带文案键与参数，按命令行的语言渲染一句；其余错误只说它说了什么 —— 栈不进
+ * 终端，它只对改代码的人有用。
+ */
+function describeFailure(error) {
+    if (HostError.is(error)) {
+        const data = toErrorData(error, CLI_LANGUAGE);
+        const detail = error.detail;
+        const hint = typeof detail === "object" && detail !== null && typeof detail.path === "string"
+            ? `（${detail.path}）`
+            : "";
+        return `${data.message}${hint}`;
+    }
+    return error instanceof Error ? error.message : String(error);
+}
+/**
+ * 入口：返回退出码。
+ *
+ * 用法错误走 2、运行失败走 1、成功走 0 —— 脚本据此分支，不去解析句子。
+ */
+export async function main(argv) {
+    let parsed;
+    try {
+        parsed = parseArgs(argv);
+    }
+    catch (error) {
+        if (error instanceof UsageError) {
+            process.stderr.write(`${error.message}\n\n${USAGE}\n`);
+            return EXIT_USAGE;
+        }
+        throw error;
+    }
+    if (parsed.command === "help") {
+        process.stdout.write(`${USAGE}\n`);
+        return 0;
+    }
+    try {
+        if (parsed.command === "version") {
+            runVersion();
+            return 0;
+        }
+        const paths = resolvePaths(parsed.aiZenDir);
+        if (parsed.command === "token") {
+            if (parsed.action === "create")
+                await runTokenCreate(paths, parsed.note);
+            else if (parsed.action === "list")
+                await runTokenList(paths);
+            else
+                await runTokenRevoke(paths, parsed.credentialId ?? "");
+            return 0;
+        }
+        await runServe(parsed);
+        // 服务在后台跑（监听、推送），主流程不阻塞在某个 Promise 上
+        return 0;
+    }
+    catch (error) {
+        process.stderr.write(`${describeFailure(error)}\n`);
+        return EXIT_FAILURE;
+    }
+}
+// 本文件就是进程入口（`bin.agents-host` → `dist/cli.js`），不做「被 import 时不执行」的分支：
+// 库里没有任何地方 import 它，带了那个分支只会在符号链接安装（`node_modules/.bin`）时静默失效。
+void main(process.argv.slice(2)).then((code) => {
+    if (code !== 0)
+        process.exitCode = code;
+});

package/dist/config.d.ts

@@ -0,0 +1,97 @@
+/**
+ * 路径与监听的来源（plan §1 的 `config.ts` 契约）。
+ *
+ * 这一层只回答两个问题：**文件放哪**、**听哪个地址**。它不建目录、不读配置文件内容、
+ * 不认识业务对象 —— 目录的创建归启动流程，配置内容归 SDK 的 `ConfigManager`。
+ *
+ * `resolvePaths` 不从进程的工作目录推导任何东西：宿主是常驻后台进程，它的工作目录
+ * 由启动方式决定（可能是个空目录、可能是用户后来删掉的目录），拿它当数据根会让「同一台机器上的
+ * 数据在哪」随启动方式漂移。数据根只有一个来源：显式参数 → `AI_ZEN_DIR` → 用户目录下的 `~/.ai-zen`。
+ */
+/** 数据根下的路径（`architecture.md` §2 的目录图） */
+export interface HostPaths {
+    /** 数据根（`AI_ZEN_DIR`，缺省 `~/.ai-zen`） */
+    dataRoot: string;
+    /** 库文件：`<dataRoot>/ai-zen.db` */
+    dbFile: string;
+    /** 附件目录：`<dataRoot>/assets` */
+    assetsDir: string;
+    /** 运行期目录：`<dataRoot>/run` */
+    runDir: string;
+    /** 发现文件：`<dataRoot>/run/host.json`（这台机器上谁在服务的唯一真相） */
+    hostFile: string;
+    /** 本地凭证交付文件：`<dataRoot>/run/token` */
+    tokenFile: string;
+    /** SDK 的配置文件：`<dataRoot>/config.json`（配置唯一真相，裁定 R13） */
+    configFile: string;
+    /** 宿主自己的设置文件：`<dataRoot>/host.json`（D25 的「配置文件」那一档，裁定 R67） */
+    hostConfigFile: string;
+    /** 日志目录：`<dataRoot>/logs`（PRD F-J2：界面被占用时日志另有去处） */
+    logsDir: string;
+}
+/** 数据根环境变量（PRD F-J4：数据根可由它改，测试与多实例都靠它） */
+export declare const AI_ZEN_DIR_ENV = "AI_ZEN_DIR";
+/** 默认端口（PRD D25） */
+export declare const DEFAULT_PORT = 8790;
+/** 本地实例监听的地址（PRD A6：本地实例只监听回环） */
+export declare const LOOPBACK_HOST = "127.0.0.1";
+/** 对外实例监听的地址（创建者自己起、自己配凭证，PRD A6） */
+export declare const PUBLIC_HOST = "0.0.0.0";
+/**
+ * 数据根：显式参数 → 环境变量 → `~/.ai-zen`。
+ *
+ * 空字符串按「没给」处理：`AI_ZEN_DIR=` 这种写法在脚本里很常见，让它变成「当前目录」会
+ * 把数据散落到不可预期的位置。
+ */
+export declare function resolveDataRoot(aiZenDir?: string): string;
+/** 按数据根推出全部路径（库、附件、运行期目录、发现文件、凭证文件、两份配置文件、日志目录） */
+export declare function resolvePaths(aiZenDir?: string): HostPaths;
+/** 监听目标：地址 + 端口 */
+export interface ListenTarget {
+    host: string;
+    port: number;
+}
+/** `resolveListenTarget` 的入参 */
+export interface ListenTargetInput {
+    /** 启动参数给的端口（优先级最高，PRD D25） */
+    port?: number;
+    /** 配置文件里的端口（第二优先） */
+    configPort?: number;
+    /** 是不是本地实例：`true` 只监听回环，`false` 监听对外地址（PRD A6） */
+    local: boolean;
+}
+/**
+ * 决定监听哪个地址、哪个端口。
+ *
+ * 端口优先级：参数 > 配置文件 > 默认（PRD D25）。**显式给出的值不合法就报错**（裁定 R67）：
+ * 静默回落会造成「我配了 9000 却在 8790 上」这种查不出来的偏差，所以只有「完全没给」才落到
+ * 下一顺位。
+ *
+ * 两个来源的合法范围不同：启动参数允许 `0`（让系统分配，用例与冒烟都用它），配置文件里的
+ * 端口必须是真端口 —— 写 `0` 的意图只能是「每次启动换一个」，而这件事在配置文件里说不清。
+ */
+export declare function resolveListenTarget(input: ListenTargetInput): ListenTarget;
+/** 端口的三档优先级与两套取值范围（分出来是为了让调用方与用例都能单独验这一跳） */
+export declare function resolvePort(port: number | undefined, configPort: number | undefined): number;
+/** 端口是否是 1..65535 的整数 */
+export declare function isValidPort(value: unknown): value is number;
+/** 启动参数里的端口：`0` 也认（交给系统分配），其余同 {@link isValidPort} */
+export declare function isPortOrAuto(value: unknown): value is number;
+/**
+ * 宿主设置文件的形状。
+ *
+ * 只放「宿主自己的启动参数」这类东西，`config.json` 那一份归 SDK 管（R13）。眼下只有一个
+ * `port`：D25 的中间那一档需要一个真实来源，而不是让 `configPort` 只能由宿主程序注入。
+ */
+export interface HostSettings {
+    /** 端口；缺省表示「这一档没说话」，落到默认端口 */
+    port?: number;
+}
+/**
+ * 读 `<dataRoot>/host.json`。
+ *
+ * 三种情况分开：文件不在 → 空设置（这一档没说话）；读不出来 / 不是 JSON 对象 → `config_invalid`
+ * （写坏了要让人看见，不能当没有，否则用户改完没有任何反馈）；`port` 在但不是可用端口 →
+ * `config_invalid`（裁定 R67：显式给出的非法值报错，不静默回落）。
+ */
+export declare function readHostSettings(paths: HostPaths): Promise<HostSettings>;

package/dist/config.js

@@ -0,0 +1,171 @@
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { HostError } from "./wire/errors.js";
+/** 数据根目录名（缺省落在用户目录下） */
+const DEFAULT_DIR_NAME = ".ai-zen";
+/** 库文件名 */
+const DB_FILE_NAME = "ai-zen.db";
+/** 运行期子目录名 */
+const RUN_DIR_NAME = "run";
+/** 发现文件名 */
+const HOST_FILE_NAME = "host.json";
+/** 本地凭证交付文件名 */
+const TOKEN_FILE_NAME = "token";
+/** 附件子目录名 */
+const ASSETS_DIR_NAME = "assets";
+/** SDK 配置文件名（`<dataRoot>/config.json`，裁定 R13） */
+const CONFIG_FILE_NAME = "config.json";
+/** 宿主设置文件名（`<dataRoot>/host.json`，裁定 R67） */
+const HOST_CONFIG_FILE_NAME = "host.json";
+/** 日志子目录名（PRD F-J2） */
+const LOGS_DIR_NAME = "logs";
+/** 数据根环境变量（PRD F-J4：数据根可由它改，测试与多实例都靠它） */
+export const AI_ZEN_DIR_ENV = "AI_ZEN_DIR";
+/** 默认端口（PRD D25） */
+export const DEFAULT_PORT = 8790;
+/** 本地实例监听的地址（PRD A6：本地实例只监听回环） */
+export const LOOPBACK_HOST = "127.0.0.1";
+/** 对外实例监听的地址（创建者自己起、自己配凭证，PRD A6） */
+export const PUBLIC_HOST = "0.0.0.0";
+/**
+ * 数据根：显式参数 → 环境变量 → `~/.ai-zen`。
+ *
+ * 空字符串按「没给」处理：`AI_ZEN_DIR=` 这种写法在脚本里很常见，让它变成「当前目录」会
+ * 把数据散落到不可预期的位置。
+ */
+export function resolveDataRoot(aiZenDir) {
+    const explicit = normalizeDir(aiZenDir);
+    if (explicit)
+        return explicit;
+    const fromEnv = normalizeDir(process.env[AI_ZEN_DIR_ENV]);
+    if (fromEnv)
+        return fromEnv;
+    return join(homedir(), DEFAULT_DIR_NAME);
+}
+/** 按数据根推出全部路径（库、附件、运行期目录、发现文件、凭证文件、两份配置文件、日志目录） */
+export function resolvePaths(aiZenDir) {
+    const dataRoot = resolveDataRoot(aiZenDir);
+    const runDir = join(dataRoot, RUN_DIR_NAME);
+    return {
+        dataRoot,
+        dbFile: join(dataRoot, DB_FILE_NAME),
+        assetsDir: join(dataRoot, ASSETS_DIR_NAME),
+        runDir,
+        hostFile: join(runDir, HOST_FILE_NAME),
+        tokenFile: join(runDir, TOKEN_FILE_NAME),
+        configFile: join(dataRoot, CONFIG_FILE_NAME),
+        hostConfigFile: join(dataRoot, HOST_CONFIG_FILE_NAME),
+        logsDir: join(dataRoot, LOGS_DIR_NAME),
+    };
+}
+function normalizeDir(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed === "" ? undefined : trimmed;
+}
+/**
+ * 决定监听哪个地址、哪个端口。
+ *
+ * 端口优先级：参数 > 配置文件 > 默认（PRD D25）。**显式给出的值不合法就报错**（裁定 R67）：
+ * 静默回落会造成「我配了 9000 却在 8790 上」这种查不出来的偏差，所以只有「完全没给」才落到
+ * 下一顺位。
+ *
+ * 两个来源的合法范围不同：启动参数允许 `0`（让系统分配，用例与冒烟都用它），配置文件里的
+ * 端口必须是真端口 —— 写 `0` 的意图只能是「每次启动换一个」，而这件事在配置文件里说不清。
+ */
+export function resolveListenTarget(input) {
+    return {
+        host: input.local ? LOOPBACK_HOST : PUBLIC_HOST,
+        port: resolvePort(input.port, input.configPort),
+    };
+}
+/** 端口的三档优先级与两套取值范围（分出来是为了让调用方与用例都能单独验这一跳） */
+export function resolvePort(port, configPort) {
+    if (port !== undefined) {
+        if (!isPortOrAuto(port))
+            throw invalidPort("port", port, "launch_argument");
+        return port;
+    }
+    if (configPort !== undefined) {
+        if (!isValidPort(configPort))
+            throw invalidPort("configPort", configPort, "host.json");
+        return configPort;
+    }
+    return DEFAULT_PORT;
+}
+/** 端口是否是 1..65535 的整数 */
+export function isValidPort(value) {
+    return typeof value === "number" && Number.isInteger(value) && value > 0 && value <= 65535;
+}
+/** 启动参数里的端口：`0` 也认（交给系统分配），其余同 {@link isValidPort} */
+export function isPortOrAuto(value) {
+    return value === 0 || isValidPort(value);
+}
+/**
+ * 端口写得不对。
+ *
+ * 码是 `config_invalid`（PRD F-A8：配置类问题要能当场修），`detail` 说明哪个来源给的什么值，
+ * 界面据此把光标放到那一栏（`host.json` 的 `port`，或启动参数）。
+ */
+function invalidPort(field, value, source) {
+    return new HostError("config_invalid", {
+        messageKey: "error.portInvalid",
+        params: { value: String(value), source },
+        detail: { field, value, source, reason: "not_a_usable_port", allowed: "1..65535, 0 (launch argument only)" },
+    });
+}
+/**
+ * 读 `<dataRoot>/host.json`。
+ *
+ * 三种情况分开：文件不在 → 空设置（这一档没说话）；读不出来 / 不是 JSON 对象 → `config_invalid`
+ * （写坏了要让人看见，不能当没有，否则用户改完没有任何反馈）；`port` 在但不是可用端口 →
+ * `config_invalid`（裁定 R67：显式给出的非法值报错，不静默回落）。
+ */
+export async function readHostSettings(paths) {
+    let raw;
+    try {
+        raw = await readFile(paths.hostConfigFile, "utf8");
+    }
+    catch (error) {
+        // 文件不在是正常情况（绝大多数据根上就没有这份文件）
+        if (isMissingFile(error))
+            return {};
+        throw new HostError("config_invalid", {
+            messageKey: "config.fileBroken",
+            params: { path: paths.hostConfigFile, reason: "unreadable" },
+            detail: { path: paths.hostConfigFile, reason: "unreadable" },
+        });
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new HostError("config_invalid", {
+            messageKey: "config.fileBroken",
+            params: { path: paths.hostConfigFile, reason: "not_json" },
+            detail: { path: paths.hostConfigFile, reason: "not_json" },
+        });
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw new HostError("config_invalid", {
+            messageKey: "config.fileBroken",
+            params: { path: paths.hostConfigFile, reason: "not_an_object" },
+            detail: { path: paths.hostConfigFile, reason: "not_an_object" },
+        });
+    }
+    const record = parsed;
+    if (!Object.prototype.hasOwnProperty.call(record, "port") || record.port === null)
+        return {};
+    const port = record.port;
+    if (!isValidPort(port))
+        throw invalidPort("port", port, "host.json");
+    return { port };
+}
+function isMissingFile(error) {
+    return (typeof error === "object" &&
+        error !== null &&
+        error.code === "ENOENT");
+}

package/dist/handlers/agentHandlers.d.ts

@@ -0,0 +1,18 @@
+/**
+ * `agent.*` 的接线壳（F-B1…F-B7 / F-F5 / F-G3）。
+ *
+ * 与 `config.*` 同一套口径：入参直接交给服务，出参里的句子按这条连接的语言重渲染
+ * （D8）。业务判断在 `services/AgentService.ts`。
+ */
+import type { HandlerTable } from "../net/WsHub.js";
+import type { AgentService } from "../services/AgentService.js";
+/** 本文件负责的方法名 */
+export type AgentHandlerName = "agent.list" | "agent.get" | "agent.create" | "agent.update" | "agent.delete" | "agent.setModel" | "agent.setThinking" | "agent.restoreFactory";
+/** 本文件产出的 handler 表片段 */
+export type AgentHandlers = Pick<HandlerTable, AgentHandlerName>;
+/** 接线壳的依赖 */
+export interface AgentHandlerDeps {
+    agents: AgentService;
+}
+/** 造出 `agent.*` 的 handler 表 */
+export declare function createAgentHandlers(deps: AgentHandlerDeps): AgentHandlers;