napbox 0.0.0-stage → 0.1.0

package/dist/agent/shell-command.js

@@ -0,0 +1,208 @@
+const OPERATOR_CHARACTERS = new Set([";", "&", "|", "\n", "(", ")", "`"]);
+function tokenize(command) {
+    const tokens = [];
+    let word;
+    const flush = () => {
+        if (word !== undefined)
+            tokens.push({ word });
+        word = undefined;
+    };
+    for (let i = 0; i < command.length; i++) {
+        const c = command[i];
+        if (c === "\\") {
+            i++;
+            if (command[i] !== "\n")
+                word = (word ?? "") + (command[i] ?? "");
+        }
+        else if (c === "'") {
+            const end = command.indexOf("'", i + 1);
+            const stop = end < 0 ? command.length : end;
+            word = (word ?? "") + command.slice(i + 1, stop);
+            i = stop;
+        }
+        else if (c === '"') {
+            word ??= "";
+            for (i++; i < command.length && command[i] !== '"'; i++) {
+                if (command[i] === "\\" && i + 1 < command.length)
+                    i++;
+                word += command[i];
+            }
+        }
+        else if (c === "$" && command[i + 1] === "(") {
+            flush();
+            tokens.push({ operator: true });
+            i++;
+        }
+        else if (OPERATOR_CHARACTERS.has(c)) {
+            flush();
+            tokens.push({ operator: true });
+        }
+        else if (c === " " || c === "\t") {
+            flush();
+        }
+        else if (c === "#" && word === undefined) {
+            while (i + 1 < command.length && command[i + 1] !== "\n")
+                i++;
+        }
+        else {
+            word = (word ?? "") + c;
+        }
+    }
+    flush();
+    return tokens;
+}
+/** 这些命令后面跟的才是真正运行的命令；值是它们自己带参数的选项 */
+const WRAPPERS = new Map([
+    ["sudo", new Set(["-u", "-g", "-h", "-p", "-C", "-T", "-U"])],
+    ["env", new Set(["-u", "-C", "-S"])],
+    ["command", new Set()],
+    ["exec", new Set(["-a"])],
+    ["nohup", new Set()],
+    ["time", new Set()],
+    ["nice", new Set(["-n"])],
+]);
+const SHELLS = new Set(["sh", "bash", "zsh", "dash"]);
+const baseName = (word) => word.slice(word.lastIndexOf("/") + 1);
+const isAssignment = (word) => /^[A-Za-z_][A-Za-z0-9_]*=/.test(word);
+/** 去掉变量赋值和 sudo、env 这类前缀，剩下真正运行的命令 */
+function unwrap(argv) {
+    let rest = argv;
+    for (;;) {
+        while (rest[0] !== undefined && isAssignment(rest[0]))
+            rest = rest.slice(1);
+        const name = rest[0] === undefined ? undefined : baseName(rest[0]);
+        if (name === "timeout") {
+            let i = 1;
+            while (rest[i]?.startsWith("-"))
+                i++;
+            rest = rest.slice(i + 1); // 跳过时长
+            continue;
+        }
+        const options = name === undefined ? undefined : WRAPPERS.get(name);
+        if (!options)
+            return rest;
+        let i = 1;
+        while (rest[i]?.startsWith("-"))
+            i += options.has(rest[i]) ? 2 : 1;
+        rest = rest.slice(i);
+    }
+}
+/** 拆成简单命令。sh -c '...' 里的内容也拆开看 */
+export function simpleCommands(command, depth = 0) {
+    const commands = [];
+    const cds = [];
+    let argv = [];
+    const finish = () => {
+        const words = unwrap(argv);
+        argv = [];
+        const name = words[0] === undefined ? undefined : baseName(words[0]);
+        if (name === undefined)
+            return;
+        if (name === "cd") {
+            const target = words[1];
+            if (target && target !== "-" && !target.includes("$"))
+                cds.push(target);
+            return;
+        }
+        const script = SHELLS.has(name) ? shellScript(words) : undefined;
+        if (script !== undefined && depth < 3) {
+            for (const inner of simpleCommands(script, depth + 1))
+                commands.push({ argv: inner.argv, cds: [...cds, ...inner.cds] });
+            return;
+        }
+        commands.push({ argv: words, cds: [...cds] });
+    };
+    for (const token of tokenize(command)) {
+        if ("word" in token)
+            argv.push(token.word);
+        else
+            finish();
+    }
+    finish();
+    return commands;
+}
+/** sh -c、bash -lc 这类写法里 -c 后面的脚本 */
+function shellScript(words) {
+    for (let i = 1; i < words.length; i++) {
+        const word = words[i];
+        if (!word.startsWith("-"))
+            return undefined;
+        if (!word.startsWith("--") && word.includes("c"))
+            return words[i + 1];
+    }
+    return undefined;
+}
+/** docker 和 docker compose 自己带值的选项，子命令在它们后面 */
+const DOCKER_OPTIONS = new Set(["--config", "-c", "--context", "-H", "--host", "-l", "--log-level"]);
+const COMPOSE_OPTIONS = new Set([
+    "--ansi",
+    "--env-file",
+    "-f",
+    "--file",
+    "--parallel",
+    "--profile",
+    "--progress",
+    "--project-directory",
+    "-p",
+    "--project-name",
+]);
+function firstWordAfterOptions(words, options) {
+    let i = 0;
+    while (words[i]?.startsWith("-"))
+        i += options.has(words[i]) ? 2 : 1;
+    return i;
+}
+/** docker 自己的选项之后的词，第一个是子命令；不是 docker 命令时是 undefined */
+function dockerWords(argv) {
+    if (argv[0] === undefined || baseName(argv[0]) !== "docker")
+        return undefined;
+    const rest = argv.slice(1);
+    return rest.slice(firstWordAfterOptions(rest, DOCKER_OPTIONS));
+}
+/** docker compose 的子命令，不是 docker compose 时是 undefined */
+export function composeSubcommand(argv) {
+    let rest;
+    if (argv[0] !== undefined && baseName(argv[0]) === "docker-compose") {
+        rest = argv.slice(1);
+    }
+    else {
+        const words = dockerWords(argv);
+        if (words?.[0] !== "compose")
+            return undefined;
+        rest = words.slice(1);
+    }
+    const i = firstWordAfterOptions(rest, COMPOSE_OPTIONS);
+    if (rest.includes("--help") || rest.includes("-h"))
+        return undefined;
+    return rest[i];
+}
+/** 是不是 docker run（或者同一件事的另一种写法 docker container run）：不靠 compose 直接起一个容器 */
+export function isDockerRun(argv) {
+    const words = dockerWords(argv);
+    if (words === undefined || words.includes("--help"))
+        return false;
+    return words[0] === "run" || (words[0] === "container" && words[1] === "run");
+}
+/** 自己在宿主机上起数据库这类服务的命令，返回一句话描述；不是时返回 undefined */
+export function startsOwnService(argv) {
+    const name = argv[0] === undefined ? undefined : baseName(argv[0]);
+    switch (name) {
+        case "postgres":
+        case "mysqld":
+        case "mysqld_safe":
+        case "mongod":
+        case "redis-server":
+            return argv.includes("--version") || argv.includes("--help") ? undefined : name;
+        case "pg_ctl":
+        case "mysql.server":
+            return argv.includes("start") || argv.includes("restart") ? name : undefined;
+        case "minio":
+            return argv[1] === "server" ? "minio server" : undefined;
+        case "brew":
+            return argv[1] === "services" && (argv[2] === "start" || argv[2] === "run" || argv[2] === "restart")
+                ? "brew services"
+                : undefined;
+        default:
+            return undefined;
+    }
+}

package/dist/agent/tools.d.ts

@@ -0,0 +1,43 @@
+import { z } from "zod";
+import type { NapboxClient } from "../client.ts";
+export interface ToolContext {
+    client: NapboxClient;
+    /** 没传 directory 时用的目录：会话工作的地方 */
+    sessionDirectory(): Promise<string>;
+    signal: AbortSignal;
+}
+export interface ToolResult {
+    value: unknown;
+    isError: boolean;
+}
+interface Tool<S extends z.ZodObject = z.ZodObject> {
+    name: string;
+    title: string;
+    description: string;
+    input: S;
+    annotations: {
+        readOnlyHint: boolean;
+        destructiveHint: boolean;
+        idempotentHint: boolean;
+    };
+    run(args: z.output<S>, context: ToolContext): Promise<unknown>;
+}
+export declare const tools: readonly Tool[];
+export declare function listTools(): {
+    name: string;
+    title: string;
+    description: string;
+    inputSchema: {
+        [x: string]: unknown;
+    };
+    annotations: {
+        readOnlyHint: boolean;
+        destructiveHint: boolean;
+        idempotentHint: boolean;
+        title: string;
+        openWorldHint: boolean;
+    };
+}[];
+/** 工具的错误都放进结果（isError），不当 JSON-RPC 错误：agent 能看到原因 */
+export declare function callTool(name: string, rawArguments: unknown, context: ToolContext): Promise<ToolResult>;
+export {};

package/dist/agent/tools.js

@@ -0,0 +1,295 @@
+// MCP 工具，和命令行一一对应（DESIGN.md 第 4 节）。出错时的内容和命令行一样是 {"error": {"code", "message"}}。
+import path from "node:path";
+import { z } from "zod";
+import { NapboxError } from "../client.js";
+import { EgressMode } from "../protocol.js";
+import { setup } from "./setup.js";
+/** 一次结果里每种输出最多留这么多字节（留最后的部分）：太长的结果 agent 也读不了，要全部内容就重定向到文件 */
+const OUTPUT_LIMIT = 48 * 1024;
+const DEFAULT_EXEC_SECONDS = 120;
+/** run 的时间从起环境算起，第一次还要拉镜像、构建 */
+const DEFAULT_RUN_SECONDS = 600;
+const directory = z
+    .string()
+    .optional()
+    .describe("在哪个目录操作（环境按所在 worktree 识别）。不写就是会话工作的目录；会话换了 worktree 时要写。");
+/** 操作临时环境的工具共用；up 的说明另写（它是起，不是找） */
+const temp = z
+    .string()
+    .optional()
+    .describe("操作这个 worktree 里叫这个名字的临时环境（up 传 temp 起的）。不写是开发环境。");
+const READ = { readOnlyHint: true, destructiveHint: false, idempotentHint: true };
+const WRITE = { readOnlyHint: false, destructiveHint: false, idempotentHint: true };
+const DESTROY = { readOnlyHint: false, destructiveHint: true, idempotentHint: false };
+const define = (tool) => tool;
+async function target(args, context) {
+    const base = await context.sessionDirectory();
+    return { cwd: args.directory ? path.resolve(base, args.directory) : base, temp: args.temp };
+}
+/** compose 变量替换用 MCP 服务自己的环境变量，和命令行用它自己的一样 */
+const processEnvironment = () => Object.fromEntries(Object.entries(process.env).filter((entry) => entry[1] !== undefined));
+const timeoutSeconds = (fallback, from) => z.int().min(1).max(3600).optional().describe(`超时后结束命令，默认 ${fallback} 秒${from}`);
+/** 只留最后 OUTPUT_LIMIT 字节 */
+class TailBuffer {
+    kept = Buffer.alloc(0);
+    total = 0;
+    add(data) {
+        this.total += data.length;
+        this.kept = Buffer.concat([this.kept, data]).subarray(-OUTPUT_LIMIT);
+    }
+    get text() {
+        return this.kept.toString("utf8");
+    }
+    get droppedBytes() {
+        return this.total - this.kept.length;
+    }
+}
+/** exec、run 共用：收下输出，到时间就取消。超时不抛，返回 timedOut 和已经收到的输出 */
+async function capture(seconds, context, start) {
+    const stdout = new TailBuffer();
+    const stderr = new TailBuffer();
+    const timeout = AbortSignal.timeout(seconds * 1000);
+    const captured = () => ({
+        stdout: stdout.text,
+        stderr: stderr.text,
+        droppedBytes: { stdout: stdout.droppedBytes, stderr: stderr.droppedBytes },
+    });
+    try {
+        const { exitCode } = await start(({ stream, data }) => (stream === "stdout" ? stdout : stderr).add(data), AbortSignal.any([context.signal, timeout]));
+        return { exitCode, ...captured() };
+    }
+    catch (error) {
+        if (!timeout.aborted)
+            throw error;
+        return { timedOut: true, ...captured() };
+    }
+}
+export const tools = [
+    define({
+        name: "up",
+        title: "启动环境",
+        description: "用项目的 compose 文件启动当前 worktree 的开发环境（数据库、对象存储、后端等），不用 Docker，每个 worktree 一套，端口不冲突。等服务都就绪后返回端口和变量。同一个环境的端口固定不变（休眠、唤醒、再次 up、换 profile 都一样），down 之后才释放。已在运行时马上返回。第一次可能要拉镜像、构建镜像，比较慢。测试要一套用完就扔的服务（比如空的数据库）时传 temp，代替 docker run。",
+        input: z.strictObject({
+            directory,
+            files: z.array(z.string()).optional().describe("compose 文件，按顺序合并。不写就自动查找。"),
+            profiles: z.array(z.string()).optional().describe("启用的 profile"),
+            build: z
+                .boolean()
+                .optional()
+                .describe("写了 build 的服务都重新构建。不传时只在镜像还没有时构建；改了 Dockerfile 或打进镜像的文件后要传 true。"),
+            temp: z
+                .string()
+                .optional()
+                .describe("起一个叫这个名字的临时环境，不动开发环境：有自己的端口和数据，可以同时起好几个。名字小写字母或数字开头，只用小写字母、数字和 . _ -，不超过 40 个字符。用完调 down 传同一个名字，数据直接删掉；它不休眠，闲置了自己销毁。"),
+        }),
+        annotations: WRITE,
+        async run(args, context) {
+            return context.client.up({
+                ...(await target(args, context)),
+                files: args.files,
+                profiles: args.profiles,
+                environment: processEnvironment(),
+                build: args.build,
+            });
+        },
+    }),
+    define({
+        name: "run",
+        title: "单独跑一次某个服务",
+        description: `临时起一个环境，在前台跑 compose 里的一个服务（测试、检查、一次性脚本），跑完整个销毁，代替 docker compose run 和 docker run --rm。它依赖的服务先起好；和开发环境互不影响，数据不保留。stdout、stderr 各留最后 ${OUTPUT_LIMIT / 1024}KB；不支持交互。服务失败看 exitCode。`,
+        input: z.strictObject({
+            directory,
+            service: z.string().describe("服务名"),
+            command: z
+                .array(z.string())
+                .min(1)
+                .optional()
+                .describe('命令和参数，换掉服务的 command，比如 ["npm", "test"]；不写就用 compose 里写的'),
+            files: z.array(z.string()).optional().describe("compose 文件，按顺序合并。不写就自动查找。"),
+            profiles: z.array(z.string()).optional().describe("启用的 profile。要跑的服务自己的 profile 不用写。"),
+            build: z.boolean().optional().describe("写了 build 的服务都重新构建。不传时只在镜像还没有时构建。"),
+            noDeps: z.boolean().optional().describe("不起它 depends_on 的服务"),
+            egress: EgressMode.optional().describe("出网模式，默认 open；none 是一起来就只能访问这个环境自己的服务"),
+            stdin: z.string().optional().describe("给服务的标准输入"),
+            timeoutSeconds: timeoutSeconds(DEFAULT_RUN_SECONDS, "，从起环境算起"),
+        }),
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
+        async run(args, context) {
+            const { cwd } = await target(args, context);
+            return capture(args.timeoutSeconds ?? DEFAULT_RUN_SECONDS, context, (onOutput, signal) => context.client.run({
+                cwd,
+                files: args.files,
+                profiles: args.profiles,
+                environment: processEnvironment(),
+                build: args.build,
+                egress: args.egress,
+                service: args.service,
+                command: args.command,
+                noDeps: args.noDeps,
+                stdin: args.stdin,
+                onOutput,
+                signal,
+            }));
+        },
+    }),
+    define({
+        name: "env",
+        title: "查看环境",
+        description: "当前 worktree 环境的状态、端口和变量（比如 NAPBOX_API_3100=127.0.0.1:41217）。不唤醒环境。代码连服务时用这里的地址。",
+        input: z.strictObject({ directory, temp }),
+        annotations: READ,
+        async run(args, context) {
+            return context.client.environment(await target(args, context));
+        },
+    }),
+    define({
+        name: "status",
+        title: "所有环境",
+        description: "napboxd 的版本和这台机器上所有环境的状态、端口。",
+        input: z.strictObject({}),
+        annotations: READ,
+        run: (_args, context) => context.client.status(),
+    }),
+    define({
+        name: "logs",
+        title: "查看日志",
+        description: "服务的日志，默认最后 200 行。不唤醒环境。每次启动前有一行分隔。",
+        input: z.strictObject({
+            directory,
+            temp,
+            service: z.string().describe("服务名"),
+            tail: z.int().min(0).optional().describe("最后几行，默认 200"),
+        }),
+        annotations: READ,
+        async run(args, context) {
+            const output = new TailBuffer();
+            await context.client.logs({
+                target: await target(args, context),
+                service: args.service,
+                tail: args.tail ?? 200,
+                onOutput: ({ data }) => output.add(data),
+                signal: context.signal,
+            });
+            return { logs: output.text, droppedBytes: output.droppedBytes };
+        },
+    }),
+    define({
+        name: "exec",
+        title: "在服务里执行命令",
+        description: `在服务的容器里执行命令，比如跑数据库迁移或 psql。休眠时先唤醒。沿用容器的环境变量、工作目录和用户。stdout、stderr 各留最后 ${OUTPUT_LIMIT / 1024}KB；不支持交互。命令失败看 exitCode。`,
+        input: z.strictObject({
+            directory,
+            temp,
+            service: z.string().describe("服务名"),
+            command: z.array(z.string()).min(1).describe('命令和参数，比如 ["sh", "-c", "ls /app | wc -l"]'),
+            stdin: z.string().optional().describe("给命令的标准输入"),
+            timeoutSeconds: timeoutSeconds(DEFAULT_EXEC_SECONDS, ""),
+        }),
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false },
+        async run(args, context) {
+            const environmentTarget = await target(args, context);
+            return capture(args.timeoutSeconds ?? DEFAULT_EXEC_SECONDS, context, (onOutput, signal) => context.client.exec({
+                target: environmentTarget,
+                service: args.service,
+                command: args.command,
+                stdin: args.stdin,
+                onOutput,
+                signal,
+            }));
+        },
+    }),
+    define({
+        name: "reset",
+        title: "清空数据卷",
+        description: "把一个数据卷恢复成空的，再重新起环境（一次性服务会重跑）。其他数据卷不动。旧数据保留 7 天。",
+        input: z.strictObject({ directory, volume: z.string().describe("数据卷名") }),
+        annotations: DESTROY,
+        async run(args, context) {
+            return context.client.reset(await target(args, context), args.volume);
+        },
+    }),
+    define({
+        name: "sleep",
+        title: "休眠环境",
+        description: "让当前 worktree 的环境休眠，释放内存，断开现有连接。一连接就会自动唤醒。闲置 30 分钟也会自动休眠。",
+        input: z.strictObject({ directory }),
+        annotations: WRITE,
+        async run(args, context) {
+            return context.client.sleep(await target(args, context));
+        },
+    }),
+    define({
+        name: "down",
+        title: "回收环境",
+        description: "回收当前 worktree 的环境：停掉服务、释放端口，数据保留 7 天后删除。只是不用了不需要回收，它会自己休眠。传 temp 是销毁那个临时环境，它的数据直接删掉。",
+        input: z.strictObject({ directory, temp }),
+        annotations: DESTROY,
+        async run(args, context) {
+            return context.client.down(await target(args, context));
+        },
+    }),
+    define({
+        name: "egress",
+        title: "切换出网模式",
+        description: "open：服务能上外网；none：只能访问环境自己的服务。都访问不到宿主机和局域网。在运行的马上生效。",
+        input: z.strictObject({ directory, temp, mode: EgressMode }),
+        annotations: WRITE,
+        async run(args, context) {
+            return context.client.egress(await target(args, context), args.mode);
+        },
+    }),
+    define({
+        name: "image_import",
+        title: "从 Docker 导入镜像",
+        description: "把本机 Docker 里的镜像导入 napbox，给 Docker Hub 上已经拉不到的旧版本用。只执行 docker save，不碰 Docker 的容器和数据。",
+        input: z.strictObject({ reference: z.string().describe("镜像名") }),
+        annotations: WRITE,
+        run: (args, context) => context.client.importImage(args.reference),
+    }),
+    define({
+        name: "setup",
+        title: "首次准备",
+        description: "第一次使用前的准备，或工具报 daemon_unavailable 时调用：下载约 700MB 的内核包，把后台程序 napboxd 注册成登录项并启动。已经准备好的不重做。有环境在运行时不会换版本，除非 restart 为 true。",
+        input: z.strictObject({
+            restart: z.boolean().optional().describe("有环境在运行时也更新后台程序，运行中的环境会停止，连接会断开"),
+        }),
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
+        run: (args) => setup({ restart: args.restart ?? false, log: () => { } }),
+    }),
+];
+export function listTools() {
+    return tools.map(({ name, title, description, input, annotations }) => {
+        const { $schema: _, ...inputSchema } = z.toJSONSchema(input);
+        return {
+            name,
+            title,
+            description,
+            inputSchema,
+            annotations: { title, ...annotations, openWorldHint: false },
+        };
+    });
+}
+/** 工具的错误都放进结果（isError），不当 JSON-RPC 错误：agent 能看到原因 */
+export async function callTool(name, rawArguments, context) {
+    const tool = tools.find((candidate) => candidate.name === name);
+    if (!tool)
+        return failure("usage_error", `没有工具 ${name}`);
+    const args = tool.input.safeParse(rawArguments ?? {});
+    if (!args.success)
+        return failure("usage_error", z.prettifyError(args.error));
+    try {
+        const value = await tool.run(args.data, context);
+        const timedOut = value.timedOut === true;
+        return { value, isError: timedOut };
+    }
+    catch (error) {
+        if (!(error instanceof NapboxError))
+            throw error;
+        return failure(error.code, error.code === "daemon_unavailable"
+            ? `${error.message} 调用 setup 工具准备（要用户同意：下载约 700MB、注册登录项）。`
+            : error.message);
+    }
+}
+function failure(code, message) {
+    return { value: { error: { code, message } }, isError: true };
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+// npm 包的 napbox 命令。setup、mcp、hook 是 TypeScript 写的；其余都交给 Swift 写的命令行，
+// 用 execve 直接换成它：标准输入输出、信号和退出码都不用转发。
+import path from "node:path";
+import { NapboxError } from "./client.js";
+import { runHook } from "./agent/hooks.js";
+import { nativeDirectory } from "./agent/locations.js";
+import { serveMcp } from "./agent/mcp.js";
+import { sweepCachedVersions } from "./agent/cache.js";
+import { registerMcp, setup } from "./agent/setup.js";
+const [command, ...rest] = process.argv.slice(2);
+async function runSetup(args) {
+    const restart = args.includes("--restart");
+    const others = args.filter((arg) => arg !== "--restart");
+    const [agent, extra] = others;
+    if (extra !== undefined || (agent !== undefined && agent !== "claude" && agent !== "codex")) {
+        throw new NapboxError("usage_error", "用法：napbox setup [claude|codex] [--restart]");
+    }
+    const result = await setup({ restart, log: (line) => process.stderr.write(`${line}\n`) });
+    const mcp = agent ? await registerMcp(agent) : undefined;
+    process.stdout.write(`${JSON.stringify({ ...result, mcp })}\n`);
+}
+async function readStdin() {
+    let text = "";
+    process.stdin.setEncoding("utf8");
+    for await (const chunk of process.stdin)
+        text += chunk;
+    return text;
+}
+try {
+    switch (command) {
+        case "setup":
+            await runSetup(rest);
+            break;
+        case "mcp":
+            // 只是清理，失败了下次再清，不影响服务
+            void sweepCachedVersions().catch(() => { });
+            await serveMcp();
+            process.exit(0);
+            break;
+        case "hook": {
+            const output = await runHook(JSON.parse(await readStdin()));
+            if (output)
+                process.stdout.write(`${JSON.stringify(output)}\n`);
+            break;
+        }
+        default: {
+            const native = path.join(nativeDirectory(), "napbox");
+            // engines 要求的 Node 都有它，类型里写成可选是因为 Windows 没有
+            process.execve(native, [native, ...process.argv.slice(2)]);
+        }
+    }
+}
+catch (error) {
+    // 和命令行一样的错误格式（DESIGN.md 第 9 节）
+    const { code, message } = error instanceof NapboxError ? error : { code: "internal_error", message: String(error) };
+    process.stdout.write(`${JSON.stringify({ error: { code, message } })}\n`);
+    process.exit(1);
+}