@super-coding/cli 0.2.1 → 0.2.3

package/dist/pingcode/remote-config.js

@@ -0,0 +1,69 @@
+// 平台下发的 PingCode 凭据落地：remote 经 webhook 取回 manifest environment 配置，
+// 在 hello 之后推给 daemon，这里决定「写不写本机文件」。
+//
+// 核心策略：**只在本机完全没有配置时写入**（missing → 写；ok/invalid → 不碰）。
+// 理由：本机文件可能承载用户手动配的个人令牌或私有部署地址，静默覆盖等于销毁用户配置；
+// 而「平台配置统一凭据」的场景只需要覆盖新机器。轮换 secret 时的逃生路径是
+// `scode pingcode disconnect`（删文件）后重连，而不是让握手路径隐式覆盖。
+//
+// 安全：base_url 在本通道单独做 https 强制（localhost 例外）。config.ts 的 normalize 允许
+// http（本地 pc 调试合理），但 WS 下发的值来自网络，必须更严——被篡改成 http 就等于把令牌
+// 明文送出去。
+import { inspectPingcodeConfig, pingcodeConfigPath, writePingcodeConfig, } from "./config.js";
+const clean = (value) => (typeof value === "string" ? value.trim() : "");
+/**
+ * 只接受 https；http 仅放行本机回环（私有部署的本地调试、e2e stub）。
+ * 与 config.ts 的宽松校验分开是刻意的：用户手输可以 http，网络下发不行。
+ */
+export function isAcceptableRemoteBaseUrl(raw) {
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        return false;
+    }
+    if (url.protocol === "https:")
+        return true;
+    if (url.protocol !== "http:")
+        return false;
+    return url.hostname === "localhost" || url.hostname === "127.0.0.1" || url.hostname === "[::1]";
+}
+/**
+ * 应用平台下发的凭据。绝不抛错：daemon 的握手路径不能因为一个坏字段崩掉。
+ * 返回值供调用方决定日志级别（written 打一次、exists 静默）。
+ */
+export function applyRemotePingcodeConfig(input, env = process.env) {
+    // 总开关：SC_PINGCODE=off 关掉整条集成；SC_PINGCODE_REMOTE_CONFIG=off 只关远端写入
+    if (env["SC_PINGCODE"] === "off" || env["SC_PINGCODE_REMOTE_CONFIG"] === "off") {
+        return { applied: "skipped_disabled" };
+    }
+    const baseUrl = clean(input?.base_url);
+    const clientId = clean(input?.client_id);
+    const clientSecret = clean(input?.client_secret);
+    if (!clientId || !clientSecret) {
+        if (!clientId && !clientSecret)
+            return { applied: "skipped_empty" };
+        return { applied: "skipped_incomplete", missing: clientId ? "client_secret" : "client_id" };
+    }
+    if (baseUrl && !isAcceptableRemoteBaseUrl(baseUrl)) {
+        return { applied: "skipped_bad_base_url", base_url: baseUrl };
+    }
+    const state = inspectPingcodeConfig();
+    if (state.state === "ok")
+        return { applied: "exists", path: state.path };
+    // 坏文件不覆盖：可能只是手写少了个逗号，覆盖会让用户失去自己配置的线索
+    if (state.state === "invalid") {
+        return { applied: "skipped_invalid", path: state.path, error: state.error };
+    }
+    try {
+        // base_url 缺省时交给 normalize 回落 DEFAULT_BASE_URL，不在调用方硬编码
+        writePingcodeConfig(baseUrl
+            ? { base_url: baseUrl, client_id: clientId, client_secret: clientSecret }
+            : { client_id: clientId, client_secret: clientSecret });
+        return { applied: "written", path: pingcodeConfigPath() };
+    }
+    catch (err) {
+        return { applied: "failed", error: err.message };
+    }
+}

package/dist/pingcode/skill.js

@@ -3,10 +3,25 @@
 import { readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 /** dist 与 src 同构：builtin/ 与 skill.js 同目录（构建期由 copy-assets 拷贝） */
-const SKILL_PATH = fileURLToPath(new URL("./builtin/SKILL.md", import.meta.url));
-const REFERENCE_PATH = fileURLToPath(new URL("./builtin/reference.md", import.meta.url));
+const BUILTIN_DIR = "./builtin/";
+const SKILL_PATH = fileURLToPath(new URL(`${BUILTIN_DIR}SKILL.md`, import.meta.url));
+/**
+ * 附属参考文件。`pc` 有 18 个模块、约 400 条命令，全部塞进 SKILL.md 会把每次加载的
+ * 上下文撑爆，因此按模块拆开：SKILL.md 只留入口与铁律，细节按需读取。
+ * 顺序即写入会话目录的顺序，第一项为主参考。
+ */
+export const REFERENCE_FILES = [
+    "reference.md",
+    "reference-ship.md",
+    "reference-testhub.md",
+    "reference-org-wiki.md",
+    "reference-cross.md",
+];
+const REFERENCE_PATHS = REFERENCE_FILES.map((name) => fileURLToPath(new URL(`${BUILTIN_DIR}${name}`, import.meta.url)));
 /** 正文过短视为打包缺失/截断，宁可不注入 */
 const MIN_SKILL_CHARS = 200;
+/** 单个参考文件的下限：最薄的一份也有 40+ 条命令，低于这个值基本是拷贝失败 */
+const MIN_REFERENCE_CHARS = 1_500;
 export const PINGCODE_SKILL_NAME = "use-pingcode-cli";
 const SKILL_ID = "builtin:use-pingcode-cli";
 let cached;
@@ -23,19 +38,23 @@ export function loadPingcodeSkill() {
         return cached;
     try {
         const content = stripBom(readFileSync(SKILL_PATH, "utf8"));
-        const reference = stripBom(readFileSync(REFERENCE_PATH, "utf8"));
         if (!/^---\r?\n/.test(content))
             throw new Error("SKILL.md 缺少 frontmatter");
         if (content.trim().length < MIN_SKILL_CHARS)
             throw new Error(`SKILL.md 正文过短（<${MIN_SKILL_CHARS} 字符），疑似打包缺失`);
-        if (reference.trim().length < MIN_SKILL_CHARS)
-            throw new Error("reference.md 内容过短，疑似打包缺失");
+        const files = REFERENCE_FILES.map((name, i) => {
+            const reference = stripBom(readFileSync(REFERENCE_PATHS[i], "utf8"));
+            if (reference.trim().length < MIN_REFERENCE_CHARS) {
+                throw new Error(`${name} 内容过短（<${MIN_REFERENCE_CHARS} 字符），疑似打包缺失`);
+            }
+            return { path: name, content: reference };
+        });
         cached = {
             id: SKILL_ID,
             name: PINGCODE_SKILL_NAME,
             ...(frontmatterDescription(content) ? { description: frontmatterDescription(content) } : {}),
             content,
-            files: [{ path: "reference.md", content: reference }],
+            files,
         };
     }
     catch (err) {
@@ -48,4 +67,8 @@ export function loadPingcodeSkill() {
 export function resetPingcodeSkillCache() {
     cached = undefined;
 }
-export const pingcodeSkillPaths = { SKILL_PATH, REFERENCE_PATH };
+export const pingcodeSkillPaths = {
+    SKILL_PATH,
+    REFERENCE_PATH: REFERENCE_PATHS[0],
+    REFERENCE_PATHS,
+};

package/dist/setup/index.js

@@ -0,0 +1,329 @@
+// `scode setup`：一条命令把本机初始化到「能被平台派活」的状态。
+//
+// 交互形态是向导：先给总览（会做几件事），再一步一步来；每一步先说明「这步干什么」，
+// 需要用户输入时把问题、说明、默认值分行摆开，输入位置用 `›` 指出来；最后给结果汇总。
+// 非交互（--yes 或无 TTY）只用参数/环境变量，缺什么跳过什么。
+//
+// 三个步骤：
+//   1. 设备绑定：未绑定时先在前台配对，配对码直接打在用户眼前。
+//   2. 守护进程：绑定后再启动 daemon —— 未绑定就启动，daemon 会自己发一份配对码，
+//      与这里的配对流程抢同一个设备，所以顺序是「先绑定、后启动」。
+//   3. PingCode 凭据：依次询问 PC_OPEN_API_BASE_URL / PC_CLIENT_ID / PC_CLIENT_SECRET，
+//      落盘与校验复用 `scode pingcode connect`（~/.super-coding/pingcode.json，0600）。
+import { loadDevice, restoreDeviceBackup } from "../daemon/device-store.js";
+import { startDaemon, stopDaemon } from "../daemon/manage.js";
+import { isAlive, readPid } from "../daemon/paths.js";
+import { runPairing } from "../daemon/pairing.js";
+import { serviceUrls } from "../daemon/urls.js";
+import { connectPingcode, DEFAULT_BASE_URL, inspectPingcodeConfig, } from "../pingcode/index.js";
+import { askConfirm, createPrompter, noPrompt } from "./prompt.js";
+import { GUTTER, INDENT, paint, pad, symbol } from "./ui.js";
+/** 与 PingCode 应用里「Open API」三项一一对应，同时也是可用的环境变量名 */
+export const ENV_BASE_URL = "PC_OPEN_API_BASE_URL";
+export const ENV_CLIENT_ID = "PC_CLIENT_ID";
+export const ENV_CLIENT_SECRET = "PC_CLIENT_SECRET";
+const TOTAL_STEPS = 3;
+/** 汇总里的标签宽度（「守护进程」= 8 列，留一点余量） */
+const LABEL_WIDTH = 12;
+/** 复核区的标签宽度：要放下最长的 `Client Secret`（13 列） */
+const REVIEW_LABEL_WIDTH = 16;
+/** 分隔线宽度：固定值，避免窄终端折行折出难看的样子 */
+const RULE_WIDTH = 72;
+// ---------- 输出 ----------
+function stepLine(index, title) {
+    console.log("");
+    console.log(`${paint.cyan(symbol.step)} ${paint.bold(`${index}/${TOTAL_STEPS}`)}  ${paint.bold(title)}`);
+}
+/** 步骤内的一行（挂在竖线上）；不传内容就是一条竖线，用来分隔块 */
+function row(text = "") {
+    console.log(text ? `${GUTTER}${text}` : GUTTER.trimEnd());
+}
+function note(text) {
+    row(paint.dim(text));
+}
+function ok(text, detail) {
+    row(`${paint.green(symbol.done)} ${text}${detail ? `${INDENT}${paint.dim(detail)}` : ""}`);
+}
+function skip(text) {
+    row(paint.dim(`${symbol.skip} ${text}`));
+}
+function fail(text) {
+    row(paint.red(`${symbol.fail} ${text}`));
+}
+/** 汇总里的「标签 + 值」行，按显示宽度对齐（中文占 2 列，不能用 length） */
+function field(label, value) {
+    console.log(`    ${paint.dim(pad(label, LABEL_WIDTH))}${value}`);
+}
+/** 步骤内的「标签 + 值」行：跟着竖线导轨走，标签列更宽（要放下 Client Secret） */
+function rowField(label, value) {
+    row(`${INDENT}${paint.dim(pad(label, REVIEW_LABEL_WIDTH))}${value}`);
+}
+/** 密钥只显示固定 8 个点：既不暴露长度，也不像 `***cret` 那样露出尾部 */
+const DOT_MASK = "••••••••";
+// ---------- 小工具 ----------
+/** 环境变量 → 去空串，避免把「配了个空值」当成已配置 */
+function fromEnv(env, name) {
+    const raw = env[name];
+    return raw && raw.trim() ? raw.trim() : undefined;
+}
+function defaultRunningPid() {
+    const state = readPid();
+    return state && isAlive(state.pid) ? state.pid : null;
+}
+function currentPingcode() {
+    const inspected = inspectPingcodeConfig();
+    return inspected.state === "ok" ? inspected.config : null;
+}
+function shortId(id) {
+    return id.length > 8 ? `${id.slice(0, 8)}…` : id;
+}
+/** Open API 地址必须能当 base URL 用；写错要等校验时才报错就太晚了 */
+function validateBaseUrl(value) {
+    if (!/^https?:\/\//i.test(value)) {
+        return "要以 http:// 或 https:// 开头，例如 https://open.pingcode.com";
+    }
+    if (/\s/.test(value))
+        return "地址里不能有空格";
+    return undefined;
+}
+// ---------- PingCode：非交互 ----------
+/** 参数 > 环境变量 > 已有配置 > 默认地址；缺凭据就跳过 */
+async function pingcodeNonInteractive(opts, env, existing, connect) {
+    if (existing && !opts.force && !(opts.clientId || opts.clientSecret)) {
+        ok("沿用现有配置", `Client ID ${existing.client_id ?? "无"}`);
+        return false;
+    }
+    const baseUrl = (opts.baseUrl ??
+        fromEnv(env, ENV_BASE_URL) ??
+        existing?.base_url ??
+        DEFAULT_BASE_URL).trim();
+    const clientId = opts.clientId ?? fromEnv(env, ENV_CLIENT_ID) ?? existing?.client_id;
+    const clientSecret = opts.clientSecret ?? fromEnv(env, ENV_CLIENT_SECRET) ?? existing?.client_secret;
+    if (!clientId || !clientSecret) {
+        skip("未提供凭据（非交互模式不提问）");
+        note("补齐：scode setup --client-id <ID> --client-secret <SECRET> [--base-url <URL>]");
+        note(`或设置环境变量 ${ENV_CLIENT_ID} / ${ENV_CLIENT_SECRET}`);
+        return false;
+    }
+    await connect({ baseUrl, clientId, clientSecret });
+    return true;
+}
+// ---------- PingCode：交互 ----------
+async function pingcodeInteractive(opts, env, existing, ask, connect) {
+    const explicit = !!(opts.clientId || opts.clientSecret);
+    if (existing && !opts.force && !explicit) {
+        ok("当前已配置", `${existing.base_url} · Client ID ${existing.client_id ?? "（无）"}`);
+        const again = await askConfirm(ask, "要修改这些配置吗？", false, "不修改就直接回车");
+        if (!again) {
+            skip("保留现有配置");
+            return false;
+        }
+    }
+    else if (!explicit) {
+        const wanted = await askConfirm(ask, "现在配置 PingCode 凭据吗？", true, "稍后也可以用 scode pingcode connect 单独配置");
+        if (!wanted) {
+            skip("已跳过 PingCode 配置");
+            return false;
+        }
+    }
+    return await collectPingcode(opts, env, existing, ask, connect);
+}
+/** 逐项问 → 复核 → 保存 */
+async function collectPingcode(opts, env, existing, ask, connect) {
+    const baseUrlDefault = (opts.baseUrl ??
+        fromEnv(env, ENV_BASE_URL) ??
+        existing?.base_url ??
+        DEFAULT_BASE_URL).trim();
+    const clientIdDefault = opts.clientId ?? fromEnv(env, ENV_CLIENT_ID) ?? existing?.client_id;
+    const clientSecretDefault = opts.clientSecret ?? fromEnv(env, ENV_CLIENT_SECRET) ?? existing?.client_secret;
+    row();
+    note("三项都在 PingCode「应用 → Open API」页面里，可以直接复制");
+    row();
+    const baseUrl = await ask("Open API 地址", {
+        defaultValue: baseUrlDefault,
+        hint: ["公有云 https://open.pingcode.com", "私有部署 https://<你的域名>/open"],
+        validate: validateBaseUrl,
+    });
+    row();
+    const clientId = await ask("Client ID", {
+        defaultValue: clientIdDefault,
+        allowEmpty: !clientIdDefault,
+        hint: "在应用凭据里，不是应用 ID，也不是工作项编号；留空则跳过",
+    });
+    row();
+    const clientSecret = await ask("Client Secret", {
+        defaultValue: clientSecretDefault,
+        defaultLabel: "回车沿用已保存的值",
+        allowEmpty: !clientSecretDefault,
+        hidden: true,
+        hint: clientSecretDefault
+            ? "输入时不回显；直接回车则沿用已保存的值"
+            : "输入时不回显；粘贴后直接回车（留空则跳过）",
+    });
+    if (!clientId || !clientSecret) {
+        skip("Client ID / Client Secret 为空，已跳过（稍后可用 scode pingcode connect 补）");
+        return false;
+    }
+    row();
+    row(paint.bold("即将保存"));
+    rowField("地址", baseUrl);
+    rowField("Client ID", clientId);
+    rowField("Client Secret", paint.dim(DOT_MASK));
+    const confirmed = await askConfirm(ask, "确认保存并校验吗？", true, "校验会真的向 PingCode 换一次令牌");
+    if (!confirmed) {
+        skip("已取消，未写入任何内容");
+        return false;
+    }
+    row(paint.dim("… 正在校验"));
+    await connect({ baseUrl, clientId, clientSecret });
+    ok("凭据已保存并通过校验");
+    return true;
+}
+// ---------- 主流程 ----------
+export async function runSetup(opts = {}, deps = {}) {
+    const env = deps.env ?? process.env;
+    const interactive = deps.interactive ?? (!!process.stdin.isTTY && !opts.yes);
+    // Ctrl+C：默认行为要么打一堆栈，要么被 readline 吃掉继续跑；统一成一句人话 + 明确的退出码
+    const onSigint = () => {
+        console.log(`\n${GUTTER}${paint.yellow(`${symbol.warn} 已中断（已完成的步骤不会回滚）`)}`);
+        process.exit(130);
+    };
+    // 注入了 ask（测试）时不再创建真实 readline，避免测试进程挂上 stdin 监听
+    const ownPrompter = interactive && !deps.ask ? createPrompter(process.stdin, process.stdout, { onInterrupt: onSigint }) : null;
+    const ask = deps.ask ?? ownPrompter?.ask ?? noPrompt;
+    const pairing = deps.pairing ?? ((httpUrl, log) => runPairing(httpUrl, { log }));
+    const start = deps.startDaemon ?? startDaemon;
+    const stop = deps.stopDaemon ?? stopDaemon;
+    const connect = deps.connectPingcode ?? connectPingcode;
+    const load = deps.loadDevice ?? (() => loadDevice() ?? restoreDeviceBackup());
+    const runningPid = deps.runningPid ?? defaultRunningPid;
+    const { http } = serviceUrls(env);
+    let pingcodeError = null;
+    let changed = 0;
+    if (interactive)
+        process.once("SIGINT", onSigint);
+    try {
+        console.log("");
+        console.log(paint.bold("Super Coding 初始化"));
+        console.log(`${INDENT}${paint.dim("依次完成 3 件事：绑定设备 → 启动守护进程 → 配置 PingCode 凭据")}`);
+        console.log(`${INDENT}${paint.dim(interactive
+            ? "回车采用方括号里的默认值，Ctrl+C 随时中断"
+            : "非交互模式：只用命令行参数与环境变量，缺什么跳过什么")}`);
+        console.log(paint.dim("─".repeat(RULE_WIDTH)));
+        // ---------- 1/3 设备绑定 ----------
+        stepLine(1, "设备绑定");
+        note("绑定后，平台才能把任务派到这台机器执行。");
+        let device = load();
+        if (device) {
+            ok("已绑定", `${device.machine_name} · ${shortId(device.id)}`);
+        }
+        else if (!interactive) {
+            // 配对要等你看到终端里的码、再去应用里输入，--yes 场景下没人能做这件事；
+            // 直接进配对会静默轮询 10 分钟然后超时退出，比跳过更糟
+            skip("未绑定设备（非交互模式不配对）");
+            note("请在终端里运行 scode setup 完成配对");
+        }
+        else if (!(await askConfirm(ask, "设备尚未绑定，现在开始配对吗？", true))) {
+            skip("未绑定（之后可再运行 scode setup）");
+        }
+        else {
+            if (runningPid()) {
+                row();
+                note("先停掉正在运行的守护进程，否则它会自己发一份配对码，和这里抢同一个设备");
+                await stop();
+                ok("已停止守护进程");
+            }
+            row();
+            note("请在 Super Coding 应用「设备」页添加设备，把终端里的配对码填进去");
+            device = await pairing(http, (msg) => row(paint.dim(msg)));
+            row();
+            ok("配对完成", `${device.machine_name} · ${shortId(device.id)}`);
+            changed += 1;
+        }
+        // ---------- 2/3 守护进程 ----------
+        stepLine(2, "守护进程");
+        note("守护进程常驻本机，负责连接平台并执行任务。");
+        const pid = runningPid();
+        if (pid) {
+            ok("已在运行", `pid ${pid}`);
+        }
+        else if (!device) {
+            skip("设备未绑定，暂不启动；绑定后运行 scode daemon start");
+        }
+        else if (interactive && !(await askConfirm(ask, "现在启动守护进程吗？", true))) {
+            skip("已跳过；稍后运行 scode daemon start");
+        }
+        else {
+            await start();
+            ok("已启动", "后台常驻，关掉终端也不影响");
+            changed += 1;
+        }
+        // ---------- 3/3 PingCode 凭据 ----------
+        stepLine(3, "PingCode 凭据");
+        note("配好之后，agent 才能在会话里读取工作项上下文。");
+        if (opts.skipPingcode) {
+            skip("已跳过（--skip-pingcode）");
+        }
+        else {
+            const existing = currentPingcode();
+            try {
+                const done = interactive
+                    ? await pingcodeInteractive(opts, env, existing, ask, connect)
+                    : await pingcodeNonInteractive(opts, env, existing, connect);
+                if (done)
+                    changed += 1;
+            }
+            catch (err) {
+                pingcodeError = err instanceof Error ? err : new Error(String(err));
+                fail(`配置失败：${pingcodeError.message}`);
+                note("修好后重试：scode pingcode connect");
+            }
+        }
+        // ---------- 汇总 ----------
+        console.log(paint.dim("─".repeat(RULE_WIDTH)));
+        const finalDevice = load();
+        const finalPid = runningPid();
+        const finalPingcode = currentPingcode();
+        const allReady = !!finalDevice && !!finalPid && (!!finalPingcode || !!opts.skipPingcode);
+        if (pingcodeError) {
+            console.log(`${paint.red(symbol.fail)} ${paint.bold("初始化未全部完成")}`);
+        }
+        else if (!allReady) {
+            // 有步骤被跳过或取消：不能说「已就绪」，那会让人以为配完了
+            console.log(`${paint.yellow(symbol.warn)} ${paint.bold("初始化尚未完成")}`);
+        }
+        else if (changed === 0) {
+            console.log(`${paint.green(symbol.done)} ${paint.bold("已就绪，本次没有改动")}`);
+        }
+        else {
+            console.log(`${paint.green(symbol.done)} ${paint.bold("初始化完成")}`);
+        }
+        console.log("");
+        field("设备", finalDevice
+            ? `${finalDevice.machine_name}${paint.dim(` · ${shortId(finalDevice.id)}`)}`
+            : paint.yellow("未绑定"));
+        field("守护进程", finalPid ? paint.green(`运行中 · pid ${finalPid}`) : paint.yellow("未运行"));
+        field("PingCode", finalPingcode
+            ? paint.green(`已配置 ${paint.dim(`· ${finalPingcode.base_url}`)}`)
+            : paint.dim("未配置"));
+        console.log("");
+        console.log(`${INDENT}${paint.dim("下一步")}`);
+        const next = [
+            ["scode daemon logs -f", "查看实时日志"],
+            ["scode daemon status", "查看运行状态"],
+        ];
+        if (!finalPingcode)
+            next.push(["scode setup", "补配 PingCode 凭据"]);
+        for (const [cmd, desc] of next) {
+            console.log(`${INDENT}  ${paint.cyan(pad(cmd, 22))}${paint.dim(desc)}`);
+        }
+        console.log("");
+        if (pingcodeError)
+            process.exitCode = 1;
+    }
+    finally {
+        if (interactive)
+            process.removeListener("SIGINT", onSigint);
+        ownPrompter?.close();
+    }
+}

package/dist/setup/prompt.js

@@ -0,0 +1,129 @@
+// 交互式问答：只做 setup 需要的最小能力——带默认值的单行输入 + 密钥不回显 + 输入校验循环。
+//
+// 不引入第三方依赖（仓库只依赖 commander/ws）。密钥遮蔽用 readline 的 _writeToOutput
+// 钩子：它在写提示符与回显输入时被调用，静音期间一律吞掉，提示符由我们自己先打印。
+//
+// 排版目标：每个问题都「先说清楚是什么、默认值是什么」，输入位置用 `› ` 明确指出来，
+// 而不是把所有信息揉在一行里。
+import { createInterface } from "node:readline";
+import { GUTTER, INDENT, paint, symbol } from "./ui.js";
+export function createPrompter(input = process.stdin, output = process.stdout, opts = {}) {
+    const rl = createInterface({ input, output });
+    let muted = false;
+    // readline 关闭后 question() 会直接抛 "readline was closed"；记下来，后续提问降级为默认值
+    let closed = false;
+    rl.once("close", () => {
+        closed = true;
+    });
+    if (opts.onInterrupt)
+        rl.on("SIGINT", () => opts.onInterrupt?.());
+    // 只接管「输出」，不接管行编辑；静音时连同回显一起吞掉
+    rl._writeToOutput = (text) => {
+        if (!muted)
+            output.write(text);
+    };
+    const resolveEmpty = (question, defaultValue, allowEmpty) => {
+        if (defaultValue !== undefined)
+            return defaultValue;
+        if (allowEmpty)
+            return "";
+        throw new Error(`${question} 不能为空`);
+    };
+    const read = async (defaultValue) => {
+        let eof = false;
+        try {
+            return await new Promise((resolve) => {
+                const onClose = () => {
+                    eof = true;
+                    resolve(defaultValue ?? "");
+                };
+                rl.once("close", onClose);
+                rl.question("", (value) => {
+                    rl.removeListener("close", onClose);
+                    resolve(value);
+                });
+            });
+        }
+        finally {
+            if (eof)
+                output.write("\n");
+        }
+    };
+    const ask = async (question, opts = {}) => {
+        const { defaultValue, defaultLabel, hidden = false, allowEmpty = false, hint, suffix, validate, gutter = GUTTER, } = opts;
+        const tail = suffix ??
+            (defaultValue !== undefined
+                ? ` [${(defaultLabel ?? defaultValue) || "空"}]`
+                : allowEmpty
+                    ? ""
+                    : " [必填]");
+        const hints = hint === undefined ? [] : Array.isArray(hint) ? hint : [hint];
+        for (let attempt = 0;; attempt += 1) {
+            output.write(`${gutter}${paint.cyan("?")} ${paint.bold(question)}${paint.dim(tail)}\n`);
+            // 说明只在第一次展示：校验失败重问时再重复一遍会让终端刷屏
+            if (attempt === 0) {
+                for (const line of hints)
+                    output.write(`${gutter}${INDENT}${paint.dim(line)}\n`);
+            }
+            output.write(`${gutter}${INDENT}${paint.dim(`${symbol.arrow} `)}`);
+            // 输入流已结束（Ctrl+D 或管道提前 EOF）：不再提问，直接按默认值/空值收场
+            if (closed) {
+                output.write("\n");
+                return resolveEmpty(question, defaultValue, allowEmpty);
+            }
+            muted = hidden;
+            let answer;
+            try {
+                answer = await read(defaultValue);
+            }
+            finally {
+                muted = false;
+                if (hidden)
+                    output.write("\n");
+            }
+            // 不回显的输入完全没有视觉反馈，容易让人以为没读到；这里只报位数，不泄露内容
+            if (hidden && answer.trim()) {
+                output.write(`${gutter}${INDENT}${paint.dim(`${symbol.skip} 已记录 ${answer.trim().length} 个字符（不回显）`)}\n`);
+            }
+            const trimmed = answer.trim();
+            const value = trimmed ? trimmed : defaultValue !== undefined ? defaultValue : allowEmpty ? "" : null;
+            if (value === null) {
+                output.write(`${gutter}${INDENT}${paint.yellow(`${symbol.warn} ${question} 不能为空`)}\n`);
+                continue;
+            }
+            const error = validate?.(value);
+            if (error) {
+                output.write(`${gutter}${INDENT}${paint.yellow(`${symbol.warn} ${error}`)}\n`);
+                continue;
+            }
+            return value;
+        }
+    };
+    return { ask, close: () => rl.close() };
+}
+/**
+ * 是非题：回车走默认值，只有明确的 y/n 才改判；看不懂的输入重问一次，
+ * 而不是默默当成默认值（那会让人以为自己答了别的意思）。
+ */
+export async function askConfirm(ask, question, defaultYes = true, hint) {
+    for (;;) {
+        const answer = (await ask(question, {
+            allowEmpty: true,
+            defaultValue: "",
+            suffix: defaultYes ? " (Y/n)" : " (y/N)",
+            hint,
+        }))
+            .trim()
+            .toLowerCase();
+        if (!answer)
+            return defaultYes;
+        if (/^(y|yes|是|确认|好)$/.test(answer))
+            return true;
+        if (/^(n|no|否|不|取消)$/.test(answer))
+            return false;
+    }
+}
+/** 非交互模式：参数/环境变量已经决定一切，问题不应被提出 */
+export const noPrompt = (question) => {
+    throw new Error(`需要交互输入（${question}），但当前不是可交互终端；请用命令行参数或环境变量提供`);
+};

package/dist/setup/ui.js

@@ -0,0 +1,78 @@
+// setup 的输出层：颜色、图标、对齐。
+//
+// 只解决「看不出这一步在干什么 / 输出像流水账」的问题，不掺业务判断。
+//
+// 颜色规则：FORCE_COLOR 强制开；NO_COLOR、TERM=dumb、非 TTY 一律关 —— 重定向到文件或
+// CI 里不应该出现一堆 ESC 序列。ANSI 用自写的包装函数，不引第三方依赖（仓库只有 commander/ws）。
+const env = process.env;
+const forceColor = env.FORCE_COLOR !== undefined && env.FORCE_COLOR !== "0";
+const colorEnabled = forceColor || (!!process.stdout.isTTY && env.NO_COLOR === undefined && env.TERM !== "dumb");
+function style(open, close) {
+    return colorEnabled ? (text) => `\x1b[${open}m${text}\x1b[${close}m` : (text) => text;
+}
+export const paint = {
+    bold: style("1", "22"),
+    dim: style("2", "22"),
+    red: style("31", "39"),
+    green: style("32", "39"),
+    yellow: style("33", "39"),
+    cyan: style("36", "39"),
+};
+export const symbol = {
+    step: "◆",
+    done: "✓",
+    skip: "·",
+    warn: "!",
+    fail: "✗",
+    arrow: "›",
+    bullet: "•",
+};
+/** 左侧导轨：把每一步的内容都挂在一条竖线上，视觉上归拢到当前步骤 */
+export const GUTTER = "  │  ";
+/** 步骤内容里的二级缩进（提示、输入游标用） */
+export const INDENT = "  ";
+const WIDE_RANGES = [
+    [0x1100, 0x115f], // 谚文字母
+    [0x2e80, 0x303e], // 部首、康熙部首、CJK 标点
+    [0x3041, 0x33ff], // 假名、注音、CJK 兼容
+    [0x3400, 0x4dbf], // CJK 扩展 A
+    [0x4e00, 0x9fff], // CJK 基本区
+    [0xa000, 0xa4cf], // 彝文
+    [0xac00, 0xd7a3], // 谚文音节
+    [0xf900, 0xfaff], // CJK 兼容表意
+    [0xfe30, 0xfe6f], // CJK 兼容形式
+    [0xff00, 0xff60], // 全角 ASCII
+    [0xffe0, 0xffe6], // 全角符号
+    [0x1f300, 0x1f64f], // emoji
+    [0x20000, 0x3fffd], // CJK 扩展 B 及以上
+];
+function isWide(code) {
+    return WIDE_RANGES.some(([lo, hi]) => code >= lo && code <= hi);
+}
+/**
+ * 显示宽度：中文/全角占 2 列。
+ * 直接用 `String.length` 对齐会让中英混排的列歪掉（「设备」是 2 个字符但占 4 列）。
+ */
+export function displayWidth(text) {
+    let width = 0;
+    for (const ch of text) {
+        const code = ch.codePointAt(0) ?? 0;
+        width += isWide(code) ? 2 : 1;
+    }
+    return width;
+}
+/** 按显示宽度右补空格，把 `text` 撑到 `width` 列 */
+export function pad(text, width) {
+    const gap = width - displayWidth(text);
+    return gap > 0 ? text + " ".repeat(gap) : text;
+}
+/** 终端宽度（取不到或不合理时退回 72），用于画分隔线 */
+export function terminalWidth() {
+    const columns = process.stdout.columns;
+    if (!columns || columns < 40)
+        return 72;
+    return Math.min(columns, 100) - 2;
+}
+export function rule() {
+    return paint.dim("─".repeat(terminalWidth()));
+}