@ats-cx/cx-cli 0.1.0

package/dist/cli.js

@@ -0,0 +1,596 @@
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { createRequire } from "node:module";
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { ApmRequestError, appendTrace, loadRun, machineConfigDir } from "@ats-cx/cx-core";
+import { Command, CommanderError } from "commander";
+import { ZodError } from "zod";
+import { createToolContext } from "./context.js";
+import { APM_FLUSH_HELP, APM_PROJECT_HELP, APM_QUERY_HELP, APM_RESOLVE_HELP } from "./apm-help.js";
+import { UserFacingError } from "./errors.js";
+import { runInit } from "./init.js";
+import { formatOut, jsonOut } from "./output.js";
+import { runProjectPull } from "./project-pull.js";
+import { runSkillsInstall, runSkillsStatus, runSkillsUninstall, SKILLS_INSTALL_HELP, SKILLS_STATUS_HELP, SKILLS_UNINSTALL_HELP, } from "./skills.js";
+import { finalizeDiagnosisTool, recordHypothesisTool } from "./tools/conclusion-tools.js";
+import { createRunTool } from "./tools/create-run.js";
+import { getCaseBriefTool, getTimelineTool, listSessionsTool, searchLogsTool } from "./tools/log-tools.js";
+import { diffProjectVersionsTool, getProjectSnapshotTool } from "./tools/project-tools.js";
+import { apmFlushTool, apmProjectTool, apmQueryTool, apmResolveTool } from "./tools/apm-tools.js";
+import { discoverWorkspace, workspaceLogSourceWarning } from "./workspace.js";
+export const TOOLKIT_ROOT = resolve(fileURLToPath(new URL("..", import.meta.url)));
+const VERSION = createRequire(import.meta.url)("../package.json").version;
+/** 命令面契约：`.scratch/cx-cli-convergence/assets/02-cx-cli-help-mock.md`。改命令时同步改这里。 */
+const TOP_LEVEL_HELP = `Usage: cx-cli [选项] <命令>
+
+编辑器诊断与项目数据工具箱
+
+全局选项:
+  --config <目录>        配置目录（默认: cwd 向上发现 .cx-cli 工作区 > $CX_CLI_CONFIG_DIR > 工具箱 config/）
+  --json                 输出 JSON（默认与人类可读格式相同，均为缩进 JSON）
+  -V, --version          显示版本号
+  -h, --help             显示帮助
+
+机器级命令（一台机器一次）:
+  skills install         把包内 skills 软链进本机 Agent（Claude Code / Codex），并建机器级覆盖目录（幂等）
+  skills status          检查 skills 链接与机器级覆盖目录（未就绪 exit 1）
+  skills uninstall       解除本包的 skills 链接（不动机器级覆盖目录）
+
+工作区命令:
+  init                   在当前仓库根创建 .cx-cli 诊断工作区（幂等）
+
+项目数据命令（直连 DB，需 .env）:
+  project pull <projectId...>   拉取每个项目最新一条快照到本地快照库
+  project pull --history        改为拉取全量历史快照
+
+APM 查询命令（网页端接口，只读）:
+  apm query              查询埋点日志（9 张表）
+  apm resolve            邮箱/手机 → userId（经网页端 portal 路由）
+  apm project <projectId>  现网 project JSON（portal 当前线上版本，非失败快照）
+  apm flush              让网页端把攒批未写入的事件落库（= 网页「同步」）
+
+诊断命令（只读本地快照库 + 日志源）:
+  run new                创建诊断 run
+  brief                  读取 case 摘要
+  sessions               列出 session
+  timeline               读取 session 时间线
+  search-logs            跨 session 检索日志
+  snapshot               读取 project 快照
+  diff-project           对比两个 project 版本
+  hypothesis             记录诊断假设
+  finalize               提交诊断结论
+  report                 生成诊断报告
+`;
+/** 同上契约（`project pull --help` 一节）。commander 默认排版对不上，这里固定文案。 */
+const PROJECT_PULL_HELP = `Usage: cx-cli project pull [选项] <projectId...>
+
+拉取项目快照到本地快照库（工作区 data/，无工作区时为 toolkit.json 的 projectHistoryDir）。
+落盘: <projectHistoryDir>/<projectId>/<projectId>_<时间>.json（时间取记录 CREATE_TIME）。
+同一秒有多条记录时，第 2 条起追加 _02、_03 序号后缀，各自独立成文件。
+XML 数据自动转换为 JSON。
+
+参数:
+  projectId...           一个或多个项目 ID
+
+选项:
+  --history              拉取全量历史（默认只拉每个项目最新一条）
+  --env <文件>           指定 .env 文件路径（默认: 工作区 .env，无工作区时 ~/.config/cx-cli/.env）
+  --json                 输出 JSON（默认与人类可读格式相同，均为缩进 JSON）
+  -h, --help
+
+示例:
+  cx-cli project pull 6345434              # 场景 1: 下载 project（最新一条）
+  cx-cli project pull 6345434 --history    # 场景 2: 拉取全量历史
+  cx-cli project pull 6345434 6351428      # 多项目，各拉最新一条
+`;
+/** commander 以异常返回控制流；这三种是「正常输出后退出」，其余一律参数错误（exit 2）。 */
+const NORMAL_EXIT_CODES = new Set(["commander.help", "commander.helpDisplayed", "commander.version"]);
+export function assertConfigDirExists(path, label) {
+    if (!existsSync(path) || !statSync(path).isDirectory()) {
+        throw new UserFacingError(`${label}: ${path}`);
+    }
+}
+/** 配置解析优先级（map 决策 8）：显式 --config > cwd 向上发现工作区 > $CX_CLI_CONFIG_DIR > 工具箱 config/。 */
+export function resolveExecution(explicit, cwd = process.cwd()) {
+    if (typeof explicit === "string" && explicit.length > 0) {
+        const configDir = resolve(explicit);
+        assertConfigDirExists(configDir, "错误: --config 指定的配置目录不存在");
+        return { configDir, configSource: "explicit", workspace: null };
+    }
+    const workspace = discoverWorkspace(cwd);
+    if (workspace) {
+        if (!workspace.toolkitConfigDir) {
+            return { configDir: join(TOOLKIT_ROOT, "config"), configSource: "toolkit", workspace };
+        }
+        try {
+            assertConfigDirExists(workspace.toolkitConfigDir, `错误: ${join(workspace.workspaceDir, "config.json")} 的 toolkitConfigDir 指向不存在的目录`);
+        }
+        catch (error) {
+            if (!(error instanceof UserFacingError)) {
+                throw error;
+            }
+            throw new UserFacingError(`${error.message}\n` +
+                `删掉这一键即改用当前 cx-cli 自带的共享配置（${join(TOOLKIT_ROOT, "config")}）；在 ${workspace.hostRoot} 重新运行 cx-cli init 会自动处理。\n` +
+                "要钉住别的配置目录，请改成存在的路径。");
+        }
+        return { configDir: workspace.toolkitConfigDir, configSource: "workspace", workspace };
+    }
+    const fromEnv = process.env.CX_CLI_CONFIG_DIR;
+    if (fromEnv) {
+        const configDir = resolve(fromEnv);
+        assertConfigDirExists(configDir, "错误: $CX_CLI_CONFIG_DIR 指定的配置目录不存在");
+        return { configDir, configSource: "env", workspace: null };
+    }
+    return { configDir: join(TOOLKIT_ROOT, "config"), configSource: "toolkit", workspace: null };
+}
+/** 合并命令自身与各级父命令的选项（`--config` 可写在子命令前后，就近者优先）。 */
+function collectOptions(command) {
+    const chain = [];
+    for (let current = command; current; current = current.parent) {
+        chain.unshift(current);
+    }
+    return Object.assign({}, ...chain.map(item => item.opts()));
+}
+function optString(value) {
+    return typeof value === "string" ? value : undefined;
+}
+function optNumber(value) {
+    return typeof value === "string" ? Number(value) : undefined;
+}
+function optStrings(value) {
+    return Array.isArray(value) && value.every(item => typeof item === "string") ? value : undefined;
+}
+function collectOption(value, previous) {
+    return [...previous, value];
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function sanitizeArgs(args) {
+    const sanitized = {};
+    for (const [key, value] of Object.entries(args)) {
+        if (typeof value === "string" && value.length > 500) {
+            continue;
+        }
+        sanitized[key] = value;
+    }
+    return sanitized;
+}
+function recordTrace(runDir, command, opts, configDir, data) {
+    appendTrace(runDir, {
+        actor: "cli",
+        command,
+        args: sanitizeArgs({ ...opts, config: configDir }),
+        outputSummary: JSON.stringify(data).slice(0, 200),
+    });
+}
+function readJsonFile(filePath) {
+    const parsed = JSON.parse(readFileSync(filePath, "utf8"));
+    return typeof parsed === "object" && parsed !== null ? parsed : {};
+}
+/**
+ * 诊断命令统一执行路径：解析配置目录 → 建 context → zod 校验 → 调 handler → 记 trace。
+ * 退出码：0 成功 / 1 业务失败（Error）/ 2 参数错误（ZodError）。
+ */
+async function executeTool(command, name, tool, buildInput, extras = {}) {
+    const opts = collectOptions(command);
+    let context;
+    let data;
+    let configDir;
+    try {
+        const execution = resolveExecution(opts.config);
+        configDir = execution.configDir;
+        context = createToolContext(execution.configDir, execution.workspace, execution.configSource);
+        // 走 stderr：不污染 --json 的 stdout，Agent 与人都看得见。
+        if (!extras.skipLogSourceWarning?.(opts)) {
+            const logSourceWarning = workspaceLogSourceWarning(context.config, execution.workspace, execution.configSource);
+            if (logSourceWarning) {
+                console.error(logSourceWarning);
+            }
+        }
+        const input = tool.inputSchema.parse(buildInput(opts));
+        data = await tool.handler(input, context);
+    }
+    catch (error) {
+        if (error instanceof ZodError) {
+            return jsonOut({ error: "参数校验失败", issues: error.issues }, 2);
+        }
+        if (error instanceof ApmRequestError) {
+            const file = "file" in error && typeof error.file === "string" ? error.file : undefined;
+            const errorData = {
+                error: error.message,
+                kind: error.kind,
+                ...(error.hint !== undefined ? { hint: error.hint } : {}),
+                ...(error.status !== undefined ? { status: error.status } : {}),
+                ...(file !== undefined ? { file } : {}),
+                ...(error.fetched !== undefined ? { fetched: error.fetched } : {}),
+                ...(error.total !== undefined ? { total: error.total } : {}),
+            };
+            const runId = optString(opts.run);
+            if (file !== undefined && runId !== undefined && context !== undefined && configDir !== undefined) {
+                const run = loadRun(context.config.runsDir, runId);
+                recordTrace(run.runDir, name, opts, configDir, errorData);
+            }
+            return jsonOut(errorData, 1);
+        }
+        if (error instanceof UserFacingError) {
+            return { exitCode: 1, stdout: error.message };
+        }
+        if (error instanceof Error) {
+            return jsonOut({ error: error.message }, 1);
+        }
+        throw error;
+    }
+    const failed = extras.check?.(data);
+    if (failed) {
+        return failed;
+    }
+    // run new 的 runId 只在返回值里（其余命令由 --run 给出）。
+    const producedRunId = typeof data === "object" && data !== null ? data.runId : undefined;
+    const runId = optString(opts.run) ?? optString(producedRunId);
+    if (runId) {
+        if (context === undefined || configDir === undefined) {
+            throw new Error("工具执行上下文未初始化");
+        }
+        const run = loadRun(context.config.runsDir, runId);
+        recordTrace(run.runDir, name, opts, configDir, data);
+    }
+    return formatOut(data);
+}
+/** `--config` / `--json` 挂到每个子命令，使其既能写在命令前也能写在命令后。 */
+function withGlobalOptions(command) {
+    return command
+        .option("--config <目录>", "配置目录（默认: cwd 向上发现 .cx-cli 工作区 > $CX_CLI_CONFIG_DIR > 工具箱 config/）")
+        .option("--json", "输出 JSON（默认与人类可读格式相同，均为缩进 JSON）");
+}
+export function createProgram(sink) {
+    const program = new Command();
+    // exitOverride / configureOutput / enablePositionalOptions 必须早于子命令创建：commander 在建子命令时复制这三项。
+    program.exitOverride();
+    // 按位置解析：命令前的选项归 program，命令后的选项归该命令。
+    // 否则 program 会抢走任意位置的同名选项（例如 `snapshot --version v1` 被顶层 -V 截胡）。
+    program.enablePositionalOptions();
+    program.configureOutput({
+        writeOut: chunk => sink.write(chunk),
+        writeErr: chunk => sink.write(chunk),
+    });
+    program
+        .name("cx-cli")
+        .description("编辑器诊断与项目数据工具箱")
+        .usage("[选项] <命令>")
+        .version(VERSION, "-V, --version", "显示版本号")
+        .helpOption("-h, --help", "显示帮助");
+    withGlobalOptions(program);
+    const emit = (result) => sink.emit(result);
+    // ---- 机器级命令 ----
+    // `--config` 只为兼容全局选项的任意位置写法，skills 组不读取配置目录，也不碰工作区。
+    const withSkillsOptions = (command) => command.option("--config <目录>", "忽略；skills 命令固定检查当前包与机器级目录").option("--json", "输出 JSON");
+    const skills = program
+        .command("skills")
+        .description("管理包内 skills 的机器级软链")
+        .option("--config <目录>", "忽略；skills 命令固定检查当前包与机器级目录")
+        .option("--json", "输出 JSON");
+    withSkillsOptions(skills.command("install"))
+        .description("把包内 skills 软链进本机 Agent，并建机器级覆盖目录")
+        .configureHelp({ formatHelp: () => SKILLS_INSTALL_HELP })
+        .action(() => {
+        emit(runSkillsInstall({ packageRoot: TOOLKIT_ROOT, packageVersion: VERSION }));
+    });
+    withSkillsOptions(skills.command("status"))
+        .description("检查 skills 链接与机器级覆盖目录")
+        .configureHelp({ formatHelp: () => SKILLS_STATUS_HELP })
+        .action(() => {
+        emit(runSkillsStatus({ packageRoot: TOOLKIT_ROOT, packageVersion: VERSION }));
+    });
+    withSkillsOptions(skills.command("uninstall"))
+        .description("解除本包的 skills 链接")
+        .configureHelp({ formatHelp: () => SKILLS_UNINSTALL_HELP })
+        .action(() => {
+        emit(runSkillsUninstall({ packageRoot: TOOLKIT_ROOT, packageVersion: VERSION }));
+    });
+    // ---- 工作区命令 ----
+    program
+        .command("init")
+        .description("在当前仓库根创建 .cx-cli 诊断工作区（幂等）")
+        .option("--json", "输出 JSON（默认与人类可读格式相同，均为缩进 JSON）")
+        .action(() => {
+        emit(runInit({ cwd: process.cwd(), toolkitRoot: TOOLKIT_ROOT }));
+    });
+    // ---- 项目数据命令 ----
+    // 按契约不挂全局选项：`--config` 只能写在命令名之前（或用 $CX_CLI_CONFIG_DIR）。
+    const project = program.command("project").description("项目数据命令（直连 DB，需 .env）");
+    project
+        .command("pull")
+        .description("拉取项目快照到本地快照库")
+        .argument("<projectId...>", "一个或多个项目 ID")
+        .option("--history", "拉取全量历史（默认只拉每个项目最新一条）")
+        .option("--env <文件>", "指定 .env 文件路径（默认: 工作区 .env，无工作区时 ~/.config/cx-cli/.env）")
+        // 输出本就是缩进 JSON；挂上 --json 只为与其余命令一致，Agent 照 skill 里「所有命令支持 --json」写不会被 exit 2 打断。
+        .option("--json", "输出 JSON（默认与人类可读格式相同，均为缩进 JSON）")
+        .configureHelp({ formatHelp: () => PROJECT_PULL_HELP })
+        .action(async (projectIds, _options, command) => {
+        const opts = collectOptions(command);
+        try {
+            const { configDir, configSource, workspace } = resolveExecution(opts.config);
+            const envPath = optString(opts.env) ??
+                (workspace && existsSync(workspace.envPath) ? workspace.envPath : join(machineConfigDir(), ".env"));
+            emit(await runProjectPull(projectIds, {
+                history: opts.history === true,
+                envPath,
+                envExamplePath: join(TOOLKIT_ROOT, ".env.example"),
+                configDir,
+                configSource,
+                workspace,
+            }));
+        }
+        catch (error) {
+            // runProjectPull 内部自带错误处理，这里只兜工作区解析（resolveExecution）的错。
+            emit(error instanceof UserFacingError
+                ? { exitCode: 1, stdout: error.message }
+                : jsonOut({ error: errorMessage(error) }, 1));
+        }
+    });
+    // ---- APM 查询命令 ----
+    const apm = program.command("apm").description("APM 查询命令（网页端接口，只读）");
+    withGlobalOptions(apm.command("query"))
+        .description("查询埋点日志（9 张表）")
+        .option("--type <表>", "日志类型")
+        .option("--project <id>", "project_id")
+        .option("--user <id>", "user_id")
+        .option("--collection <id>", "collection_id")
+        .option("--session <id>", "session_id")
+        .option("--event <名>", "事件名 data_name")
+        .option("--sub-type <值>", "sub_type")
+        .option("--where <列=值>", "按列等值，可重复（type / page / pageSize / order 除外）", collectOption, [])
+        .option("--app <id>", "app_id")
+        .option("--bizline <id>", "bizline_id")
+        .option("--from <时间>", "log_time 下界，必填")
+        .option("--to <时间>", "log_time 上界")
+        .option("--item <值>", "网页同款 ID 过滤")
+        .option("--search <文本>", "网页同款搜索过滤")
+        .option("--order <ASC|DESC>", "按 log_time 排序")
+        .option("--limit <n>", "最多从服务端取 n 行")
+        .option("--count", "只回总数，不落盘")
+        .option("--preview <n>", "stdout 内联的预览行数")
+        .option("--full", "预览不瘦身")
+        .option("--out <文件>", "查询落盘路径")
+        .option("--run <runId>", "把查询落盘写进 run")
+        .option("--no-flush", "不在查询前同步")
+        .configureHelp({ formatHelp: () => APM_QUERY_HELP })
+        .action(async (_options, command) => {
+        emit(await executeTool(command, "apm query", apmQueryTool, opts => ({
+            type: optString(opts.type),
+            project: optString(opts.project),
+            user: optString(opts.user),
+            collection: optString(opts.collection),
+            session: optString(opts.session),
+            event: optString(opts.event),
+            subType: optString(opts.subType),
+            where: optStrings(opts.where),
+            app: optString(opts.app),
+            bizline: optString(opts.bizline),
+            from: optString(opts.from),
+            to: optString(opts.to),
+            item: optString(opts.item),
+            search: optString(opts.search),
+            order: optString(opts.order),
+            limit: optNumber(opts.limit),
+            count: opts.count === true ? true : undefined,
+            preview: optNumber(opts.preview),
+            full: opts.full === true ? true : undefined,
+            out: optString(opts.out),
+            run: optString(opts.run),
+            noFlush: opts.flush === false ? true : undefined,
+        }), { skipLogSourceWarning: () => true }));
+    });
+    withGlobalOptions(apm.command("resolve"))
+        .description("邮箱/手机 → userId（经网页端 portal 路由）")
+        .option("--email <邮箱>", "邮箱 → userId")
+        .option("--phone <手机号>", "手机号 → userId")
+        .option("--host <站点 host>", "日志 host 列的完整域名")
+        .configureHelp({ formatHelp: () => APM_RESOLVE_HELP })
+        .action(async (_options, command) => {
+        emit(await executeTool(command, "apm resolve", apmResolveTool, opts => ({
+            email: optString(opts.email),
+            phone: optString(opts.phone),
+            host: optString(opts.host),
+        }), { skipLogSourceWarning: () => true }));
+    });
+    withGlobalOptions(apm.command("project"))
+        .description("现网 project JSON（portal 当前线上版本，非失败快照）")
+        .argument("<projectId>", "项目 ID")
+        .option("--host <站点 host>", "日志 host 列的完整域名")
+        .option("--out <文件>", "落盘路径")
+        .option("--run <runId>", "落进 run 的 artifacts/apm/")
+        .configureHelp({ formatHelp: () => APM_PROJECT_HELP })
+        .action(async (projectId, _options, command) => {
+        emit(await executeTool(command, "apm project", apmProjectTool, opts => ({
+            projectId,
+            host: optString(opts.host),
+            out: optString(opts.out),
+            run: optString(opts.run),
+        }), { skipLogSourceWarning: () => true }));
+    });
+    withGlobalOptions(apm.command("flush"))
+        .description("让网页端把攒批未写入的事件落库")
+        .configureHelp({ formatHelp: () => APM_FLUSH_HELP })
+        .action(async (_options, command) => {
+        emit(await executeTool(command, "apm flush", apmFlushTool, () => ({}), {
+            skipLogSourceWarning: () => true,
+        }));
+    });
+    // ---- 诊断命令 ----
+    const run = program.command("run").description("诊断 run 相关命令");
+    withGlobalOptions(run.command("new"))
+        .description("创建诊断 run")
+        .requiredOption("--projectId <id>", "项目 ID")
+        .option("--complaint <文本>", "用户投诉描述", "")
+        .option("--logs <文件>", "用查询落盘或任一 {result:[…]} 形状的文件作日志源（不读配置 logSource）")
+        .action(async (_options, command) => {
+        emit(await executeTool(command, "run new", createRunTool, opts => {
+            const logsFile = optString(opts.logs);
+            return {
+                projectId: optString(opts.projectId),
+                complaint: optString(opts.complaint) ?? "",
+                logsFile: logsFile === undefined || logsFile.length === 0 ? logsFile : resolve(logsFile),
+            };
+        }, { skipLogSourceWarning: opts => optString(opts.logs) !== undefined }));
+    });
+    withGlobalOptions(program.command("brief"))
+        .description("读取 case 摘要")
+        .requiredOption("--run <runId>", "run ID")
+        .action(async (_options, command) => {
+        emit(await executeTool(command, "brief", getCaseBriefTool, opts => ({ runId: optString(opts.run) })));
+    });
+    withGlobalOptions(program.command("sessions"))
+        .description("列出 session")
+        .requiredOption("--run <runId>", "run ID")
+        .action(async (_options, command) => {
+        emit(await executeTool(command, "sessions", listSessionsTool, opts => ({ runId: optString(opts.run) })));
+    });
+    withGlobalOptions(program.command("timeline"))
+        .description("读取 session 时间线")
+        .requiredOption("--run <runId>", "run ID")
+        .requiredOption("--session <sessionId>", "session ID")
+        .option("--category <类别>", "按语义类别过滤")
+        .option("--payload", "附带每条事件的 payload 原文（默认只列 payloadKeys）")
+        .option("--cursor <n>", "分页游标")
+        .option("--page-size <n>", "分页大小")
+        .action(async (_options, command) => {
+        emit(await executeTool(command, "timeline", getTimelineTool, opts => ({
+            runId: optString(opts.run),
+            sessionId: optString(opts.session),
+            category: optString(opts.category),
+            payload: opts.payload === true ? true : undefined,
+            cursor: optNumber(opts.cursor),
+            pageSize: optNumber(opts.pageSize),
+        })));
+    });
+    withGlobalOptions(program.command("search-logs"))
+        .description("跨 session 检索日志")
+        .requiredOption("--run <runId>", "run ID")
+        .option("--event <事件名>", "按事件名过滤")
+        .option("--payload-key <key>", "按 payload 字段过滤")
+        .option("--from <ISO>", "起始时间")
+        .option("--to <ISO>", "结束时间")
+        .option("--payload", "附带每条事件的 payload 原文（默认只列 payloadKeys）")
+        .option("--cursor <n>", "分页游标")
+        .option("--page-size <n>", "分页大小")
+        .action(async (_options, command) => {
+        emit(await executeTool(command, "search-logs", searchLogsTool, opts => ({
+            runId: optString(opts.run),
+            eventName: optString(opts.event),
+            payloadKey: optString(opts.payloadKey),
+            from: optString(opts.from),
+            to: optString(opts.to),
+            payload: opts.payload === true ? true : undefined,
+            cursor: optNumber(opts.cursor),
+            pageSize: optNumber(opts.pageSize),
+        })));
+    });
+    withGlobalOptions(program.command("snapshot"))
+        .description("读取 project 快照")
+        .requiredOption("--run <runId>", "run ID")
+        .requiredOption("--version <版本>", "快照版本")
+        .option("--detail <粒度>", "summary | pages | elements")
+        .option("--cursor <n>", "分页游标")
+        .option("--page-size <n>", "分页大小")
+        .action(async (_options, command) => {
+        emit(await executeTool(command, "snapshot", getProjectSnapshotTool, opts => ({
+            runId: optString(opts.run),
+            version: optString(opts.version),
+            detail: optString(opts.detail),
+            cursor: optNumber(opts.cursor),
+            pageSize: optNumber(opts.pageSize),
+        })));
+    });
+    withGlobalOptions(program.command("diff-project"))
+        .description("对比两个 project 版本")
+        .requiredOption("--run <runId>", "run ID")
+        .requiredOption("--before <版本>", "较早版本")
+        .requiredOption("--after <版本>", "较晚版本")
+        .option("--cursor <n>", "分页游标")
+        .option("--page-size <n>", "分页大小")
+        .action(async (_options, command) => {
+        emit(await executeTool(command, "diff-project", diffProjectVersionsTool, opts => ({
+            runId: optString(opts.run),
+            before: optString(opts.before),
+            after: optString(opts.after),
+            cursor: optNumber(opts.cursor),
+            pageSize: optNumber(opts.pageSize),
+        })));
+    });
+    withGlobalOptions(program.command("hypothesis"))
+        .description("记录诊断假设")
+        .requiredOption("--run <runId>", "run ID")
+        .requiredOption("--file <json 文件>", "假设 JSON 文件")
+        .action(async (_options, command) => {
+        emit(await executeTool(command, "hypothesis", recordHypothesisTool, opts => ({
+            runId: optString(opts.run),
+            ...readJsonFile(optString(opts.file) ?? ""),
+        })));
+    });
+    withGlobalOptions(program.command("finalize"))
+        .description("提交诊断结论")
+        .requiredOption("--run <runId>", "run ID")
+        .requiredOption("--file <json 文件>", "结论 JSON 文件")
+        .action(async (_options, command) => {
+        emit(await executeTool(command, "finalize", finalizeDiagnosisTool, opts => ({ runId: optString(opts.run), result: readJsonFile(optString(opts.file) ?? "") }), {
+            // 校验未通过：输出 errors 并按业务失败退出，不记 trace。
+            check: data => (data.ok ? undefined : jsonOut(data, 1)),
+        }));
+    });
+    // report 无对应 tool 定义（spec §3.12），直读 run 目录下的 report.md。
+    withGlobalOptions(program.command("report"))
+        .description("生成诊断报告")
+        .requiredOption("--run <runId>", "run ID")
+        .action((_options, command) => {
+        const opts = collectOptions(command);
+        const runId = optString(opts.run) ?? "";
+        try {
+            const { configDir, configSource, workspace } = resolveExecution(opts.config);
+            const context = createToolContext(configDir, workspace, configSource);
+            const run = loadRun(context.config.runsDir, runId);
+            const reportPath = join(run.runDir, "report.md");
+            if (!existsSync(reportPath)) {
+                emit(jsonOut({ error: `report.md 不存在于 run ${runId}` }, 1));
+                return;
+            }
+            const data = { report: readFileSync(reportPath, "utf8") };
+            recordTrace(run.runDir, "report", opts, configDir, data);
+            emit(formatOut(data));
+        }
+        catch (error) {
+            emit(error instanceof UserFacingError
+                ? { exitCode: 1, stdout: error.message }
+                : jsonOut({ error: errorMessage(error) }, 1));
+        }
+    });
+    // 顶层 help 按契约固定排版；放在子命令注册之后，避免子命令继承该配置。
+    program.configureHelp({ formatHelp: () => TOP_LEVEL_HELP });
+    return program;
+}
+export async function runCli(argv) {
+    const chunks = [];
+    const captured = {};
+    const program = createProgram({
+        write: chunk => {
+            chunks.push(chunk);
+        },
+        emit: result => {
+            captured.result = result;
+        },
+    });
+    try {
+        await program.parseAsync(argv, { from: "user" });
+    }
+    catch (error) {
+        if (error instanceof CommanderError) {
+            const exitCode = error.exitCode === 0 && NORMAL_EXIT_CODES.has(error.code) ? 0 : 2;
+            return { exitCode, stdout: chunks.join("").trimEnd() };
+        }
+        throw error;
+    }
+    return captured.result ?? { exitCode: 0, stdout: chunks.join("").trimEnd() };
+}
+//# sourceMappingURL=cli.js.map

package/dist/context.d.ts

@@ -0,0 +1,12 @@
+import type { ConfigSource, LogProvider, ProjectProvider, ResolvedConfig, SourceProvider, SourceRepoBinding } from "@ats-cx/cx-core";
+import type { Workspace } from "./workspace.js";
+export interface ToolContext {
+    config: ResolvedConfig;
+    configSource: ConfigSource;
+    logProvider: LogProvider;
+    projectProvider: ProjectProvider;
+    sourceProvider: SourceProvider;
+    /** 三仓绑定；无工作区时为空数组，此时诊断不带源码版本信息。 */
+    sourceRepos: SourceRepoBinding[];
+}
+export declare function createToolContext(configDir: string, workspace?: Workspace | null, configSource?: ConfigSource): ToolContext;

package/dist/context.js

@@ -0,0 +1,20 @@
+import { createLogProvider, createProjectProvider, createSourceProvider, loadConfig, } from "@ats-cx/cx-core";
+import { applyWorkspace } from "./workspace.js";
+export function createToolContext(configDir, workspace = null, configSource = "explicit") {
+    // 工作区模式下语义表只认工作区那份（spec 组件 D）；其余共享配置读自身 config/，或钉死的配置组。
+    const shared = loadConfig(configDir, {
+        source: configSource,
+        ...(workspace ? { eventSemanticsPath: workspace.semanticsPath } : {}),
+    });
+    const config = workspace ? applyWorkspace(shared, workspace) : shared;
+    const sourceRepos = workspace?.sourceRepos ?? [];
+    return {
+        config,
+        configSource,
+        logProvider: createLogProvider(config.logSource, config.apmProvider, {}, config.apmProviderState),
+        projectProvider: createProjectProvider(config.projectHistoryDir),
+        sourceProvider: createSourceProvider(sourceRepos),
+        sourceRepos,
+    };
+}
+//# sourceMappingURL=context.js.map

package/dist/contract.d.ts

@@ -0,0 +1,11 @@
+import type { z } from "zod";
+import type { ToolContext } from "./context.js";
+/** 工具契约：一份定义，两个传输层（进程内 runtime / CLI）共享。 */
+export interface ToolDefinition<Input, Output> {
+    name: string;
+    description: string;
+    /** 允许 schema 先从 CLI 原始形状 transform 成 handler 输入。 */
+    inputSchema: z.ZodType<Input, z.ZodTypeDef, unknown>;
+    handler: (input: Input, context: ToolContext) => Promise<Output>;
+}
+export declare function defineTool<Input, Output>(tool: ToolDefinition<Input, Output>): ToolDefinition<Input, Output>;

package/dist/contract.js

@@ -0,0 +1,4 @@
+export function defineTool(tool) {
+    return tool;
+}
+//# sourceMappingURL=contract.js.map

package/dist/errors.d.ts

@@ -0,0 +1,4 @@
+/** 面向用户的错误：message 已是可直接打印的中文文案，CLI 原样输出（exit 1），不再包成 JSON。 */
+export declare class UserFacingError extends Error {
+    constructor(message: string);
+}

package/dist/errors.js

@@ -0,0 +1,8 @@
+/** 面向用户的错误：message 已是可直接打印的中文文案，CLI 原样输出（exit 1），不再包成 JSON。 */
+export class UserFacingError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "UserFacingError";
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/index.d.ts

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