@peterxiaoyang/superspec 0.1.0 → 0.1.2

package/dist/src/init_cli.d.ts

@@ -1,2 +1,27 @@
+import { runCommand, type OpenspecCliProbe } from "./core.ts";
+import { type InstallScope } from "./install_engine.ts";
+type InitArgs = {
+    path: string;
+    codexHome: string;
+    mode: "install" | "update" | "uninstall";
+    scope: InstallScope | null;
+    dryRun: boolean;
+    force: boolean;
+};
+export declare function maybe_install_missing_openspec(opts: {
+    cwd: string;
+    scope: InstallScope;
+    mode: InitArgs["mode"];
+    interactive?: boolean;
+    commandExistsFn?: (cmd: string, meta?: {
+        cwd?: string;
+    }) => boolean;
+    probeOpenspecFn?: (meta?: {
+        cwd?: string;
+    }) => OpenspecCliProbe;
+    run?: typeof runCommand;
+    writeStderr?: (text: string) => void;
+}): "not-needed" | "installed" | "skipped" | "failed";
 export declare function main_init(argv?: string[]): number;
 export declare function main_init_async(argv?: string[]): Promise<number>;
+export {};

package/dist/src/init_cli.js

@@ -1,14 +1,15 @@
-import { block, GuardError, printDecision, reason } from "./core.js";
-import { project_init } from "./project_init.js";
+import { block, commandExists, GuardError, printDecision, reason, runCommand, openspec_cli_probe, REQUIRED_OPENSPEC_MIN_VERSION, } from "./core.js";
+import { forced_openspec_install_plan, project_init, recommended_openspec_install_plan } from "./project_init.js";
 import { install_workflow, uninstall_workflow, update_workflow } from "./install_engine.js";
 import { homedir } from "node:os";
 import { resolve } from "node:path";
 import { createInterface } from "node:readline/promises";
+import { system_failure_zh } from "./i18n.js";
 function usage() {
     return "usage: superspec init [-h] [--scope {project,user}] [--path PATH] [--codex-home PATH] [--create] [--update] [--uninstall] [--dry-run] [--force]\n";
 }
 function help() {
-    return `${usage()}\noptional arguments:\n  -h, --help             show this help message and exit\n  --scope {project,user} install into this project's .codex directory or into the Codex user home (default: project)\n  --project              shortcut for --scope project\n  --user                 shortcut for --scope user\n  --global               compatibility alias for --user\n  --path PATH            project root for --scope project (default: current directory)\n  --codex-home PATH      Codex user home for --scope user (default: $CODEX_HOME or ~/.codex)\n  --create               accepted for compatibility; init creates missing surfaces by default\n  --update               manifest-driven update of managed SuperSpec surfaces (user-modified files kept, new version written to *.new)\n  --uninstall            manifest-driven removal of managed SuperSpec surfaces (.superspec data and preexisting/user-modified files are kept)\n  --dry-run              with --uninstall: print what would be removed without touching files\n  --force                with install: overwrite pre-existing different files (backs up *.bak)\n`;
+    return `${usage()}\n可选参数：\n  -h, --help             显示帮助并退出\n  --scope {project,user} 安装到当前项目的 .codex 目录，或安装到用户级 Codex 目录（默认：project）\n  --project              等价于 --scope project\n  --user                 等价于 --scope user\n  --global               兼容别名，等价于 --user\n  --path PATH            --scope project 时使用的项目根目录（默认：当前目录）\n  --codex-home PATH      --scope user 时使用的 Codex 用户目录（默认：$CODEX_HOME 或 ~/.codex）\n  --create               兼容参数；init 默认就会创建缺失内容\n  --update               按 manifest 更新 SuperSpec 管理的文件；用户改动文件保留，新的版本写入 *.new\n  --uninstall            按 manifest 卸载 SuperSpec 管理的文件；.superspec 数据与既有/用户改动文件会保留\n  --dry-run              配合 --uninstall 时只预览将删除的文件，不实际修改\n  --force                安装时覆盖已有且内容不同的文件，并保留 *.bak 备份\n`;
 }
 function parse_init_argv(argv) {
     const getValue = (flag) => {
@@ -17,19 +18,19 @@ function parse_init_argv(argv) {
             return undefined;
         const value = argv[idx + 1];
         if (value === undefined || value.startsWith("--"))
-            throw new GuardError(`${flag} requires a value`);
+            throw new GuardError(`${flag} 缺少取值`);
         return value;
     };
     const update = argv.includes("--update");
     const uninstall = argv.includes("--uninstall");
     if (update && uninstall)
-        throw new GuardError("--update and --uninstall are mutually exclusive");
+        throw new GuardError("--update 与 --uninstall 不能同时使用");
     const scopeFlag = getValue("--scope");
     if (scopeFlag !== undefined && !["project", "user", "global"].includes(scopeFlag))
-        throw new GuardError("--scope must be project or user");
+        throw new GuardError("--scope 只能是 project 或 user");
     const userShortcut = argv.includes("--user") || argv.includes("--global");
     if (userShortcut && argv.includes("--project"))
-        throw new GuardError("--user/--global and --project are mutually exclusive");
+        throw new GuardError("--user/--global 与 --project 不能同时使用");
     let scope = scopeFlag === "global" ? "user" : scopeFlag ?? null;
     if (userShortcut)
         scope = "user";
@@ -47,6 +48,20 @@ function parse_init_argv(argv) {
 function joinHomeCodex() {
     return `${homedir()}/.codex`;
 }
+function commandFailure(proc) {
+    const output = (proc.error?.message ?? (proc.stderr || proc.stdout)).trim();
+    if (output)
+        return system_failure_zh(output, `安装命令执行失败（退出状态码 ${proc.status ?? "未知"}）。`);
+    if (proc.status !== null)
+        return `安装命令执行失败（退出状态码 ${proc.status}）。`;
+    return "安装命令执行失败，请查看终端日志后重试。";
+}
+function shouldRetryOpenSpecInstallWithForce(proc) {
+    const output = `${proc.error?.message ?? ""}\n${proc.stderr}\n${proc.stdout}`;
+    const binConflict = /\bEEXIST\b|already exists|file exists|Refusing to delete|will not overwrite|would overwrite/iu.test(output);
+    const openspecBin = /\bopenspec(?:\.(?:cmd|ps1))?\b/iu.test(output);
+    return binConflict && openspecBin;
+}
 function engineDecision(gate, projectRoot, result, nextActions) {
     if (result.problems.length > 0) {
         const decision = block("project", gate, result.problems.map((item) => reason(`${gate}_failed`, item)));
@@ -68,12 +83,12 @@ async function promptInstallScope() {
     const rl = createInterface({ input: process.stdin, output: process.stderr });
     try {
         for (;;) {
-            const answer = (await rl.question("Install SuperSpec Codex surfaces to project or user? [project] ")).trim().toLowerCase();
-            if (answer === "" || answer === "project" || answer === "p" || answer === "1")
+            const answer = (await rl.question("请选择安装范围：project 还是 user？[project] ")).trim().toLowerCase();
+            if (answer === "" || answer === "project" || answer === "p" || answer === "1" || answer === "项目")
                 return "project";
-            if (answer === "user" || answer === "u" || answer === "2" || answer === "global" || answer === "g")
+            if (answer === "user" || answer === "u" || answer === "2" || answer === "global" || answer === "g" || answer === "用户")
                 return "user";
-            process.stderr.write("Please answer project or user.\n");
+            process.stderr.write("请输入 project 或 user。\n");
         }
     }
     finally {
@@ -83,6 +98,60 @@ async function promptInstallScope() {
 function canPrompt() {
     return Boolean(process.stdin.isTTY && process.stderr.isTTY);
 }
+export function maybe_install_missing_openspec(opts) {
+    const commandExistsFn = opts.commandExistsFn ?? ((cmd, meta) => commandExists(cmd, { cwd: meta?.cwd }));
+    if (opts.mode !== "install")
+        return "not-needed";
+    const run = opts.run ?? runCommand;
+    const probeOpenspecFn = opts.probeOpenspecFn ?? ((meta) => openspec_cli_probe({ cwd: meta?.cwd, commandExistsFn, run }));
+    const before = probeOpenspecFn({ cwd: opts.cwd });
+    if (before.ok)
+        return "not-needed";
+    const writeStderr = opts.writeStderr ?? ((text) => {
+        process.stderr.write(text);
+    });
+    const plan = recommended_openspec_install_plan({ cwd: opts.cwd, commandExistsFn });
+    if (plan === null) {
+        writeStderr(`${before.message}。SuperSpec 需要 @fission-ai/openspec >= ${REQUIRED_OPENSPEC_MIN_VERSION}，但未找到 npm、pnpm、yarn 或 bun，无法自动安装。\n`);
+        return "skipped";
+    }
+    writeStderr(`${before.message}。SuperSpec 需要 @fission-ai/openspec >= ${REQUIRED_OPENSPEC_MIN_VERSION}，将自动安装或升级。\n`);
+    writeStderr(`正在安装 OpenSpec CLI：${plan.rendered}\n`);
+    let proc = run(plan.cmd, plan.args, { cwd: opts.cwd, timeout: 300_000 });
+    if ((proc.error || proc.status !== 0) && shouldRetryOpenSpecInstallWithForce(proc)) {
+        const forcedPlan = forced_openspec_install_plan(plan);
+        writeStderr(`OpenSpec CLI 安装遇到全局 bin 冲突，正在覆盖重试：${forcedPlan.rendered}\n`);
+        proc = run(forcedPlan.cmd, forcedPlan.args, { cwd: opts.cwd, timeout: 300_000 });
+    }
+    if (proc.error || proc.status !== 0) {
+        writeStderr(`自动安装 OpenSpec CLI 失败：${commandFailure(proc)}\n`);
+        return "failed";
+    }
+    const after = probeOpenspecFn({ cwd: opts.cwd });
+    if (!after.ok) {
+        writeStderr(`安装命令已完成，但当前 PATH 里的 openspec 仍不可用：${after.message}。请重新打开终端或确认全局 bin 已在 PATH 中，然后重新运行 superspec init；Windows PowerShell 请运行 superspec.cmd init。\n`);
+        return "failed";
+    }
+    writeStderr("OpenSpec CLI 安装或升级完成，继续执行 superspec init。\n");
+    return "installed";
+}
+function openspecPreflightBlocked(args, scope, installResult) {
+    const targetRoot = scope === "user" ? args.codexHome : args.path;
+    const code = installResult === "skipped" ? "openspec_auto_install_unavailable" : "openspec_auto_install_failed";
+    const message = installResult === "skipped"
+        ? `OpenSpec CLI 不满足 SuperSpec 要求，且未找到可用包管理器自动安装 @fission-ai/openspec >= ${REQUIRED_OPENSPEC_MIN_VERSION}。`
+        : `OpenSpec CLI 自动安装或升级 @fission-ai/openspec >= ${REQUIRED_OPENSPEC_MIN_VERSION} 未完成。`;
+    const decision = block("project", "openspec_preflight", [reason(code, message)], {
+        next_actions: [`install or upgrade @fission-ai/openspec >= ${REQUIRED_OPENSPEC_MIN_VERSION}, then rerun \`superspec init --scope ${scope}\``],
+    });
+    printDecision({
+        ...decision,
+        project_root: args.path,
+        install_scope: scope,
+        install_root: targetRoot,
+    }, { command: "init" });
+    return 1;
+}
 function run_init(args, scope) {
     const targetRoot = scope === "user" ? args.codexHome : args.path;
     const gatePrefix = scope === "user" ? "user" : "project";
@@ -107,7 +176,7 @@ function run_init(args, scope) {
     }
     summary.install_scope = scope;
     summary.install_root = targetRoot;
-    printDecision(summary);
+    printDecision(summary, { command: "init" });
     return summary.allowed ? 0 : 1;
 }
 export function main_init(argv = process.argv.slice(2)) {
@@ -117,12 +186,16 @@ export function main_init(argv = process.argv.slice(2)) {
             return 0;
         }
         const args = parse_init_argv(argv);
-        return run_init(args, args.scope ?? "project");
+        const scope = args.scope ?? "project";
+        const openspecInstall = maybe_install_missing_openspec({ cwd: args.path, scope, mode: args.mode });
+        if (openspecInstall === "failed" || openspecInstall === "skipped")
+            return openspecPreflightBlocked(args, scope, openspecInstall);
+        return run_init(args, scope);
     }
     catch (err) {
         const change = "project";
         const errReason = err instanceof GuardError ? reason("guard_error", err.message) : reason("guard_internal_error", `${err.name}: ${err.message}`);
-        printDecision(block(change, "guard_error", [errReason]));
+        printDecision(block(change, "guard_error", [errReason]), { command: "init" });
         return 2;
     }
 }
@@ -134,12 +207,15 @@ export async function main_init_async(argv = process.argv.slice(2)) {
         }
         const args = parse_init_argv(argv);
         const scope = args.scope ?? (canPrompt() ? await promptInstallScope() : "project");
+        const openspecInstall = maybe_install_missing_openspec({ cwd: args.path, scope, mode: args.mode });
+        if (openspecInstall === "failed" || openspecInstall === "skipped")
+            return openspecPreflightBlocked(args, scope, openspecInstall);
         return run_init(args, scope);
     }
     catch (err) {
         const change = "project";
         const errReason = err instanceof GuardError ? reason("guard_error", err.message) : reason("guard_internal_error", `${err.name}: ${err.message}`);
-        printDecision(block(change, "guard_error", [errReason]));
+        printDecision(block(change, "guard_error", [errReason]), { command: "init" });
         return 2;
     }
 }

package/dist/src/openspec.d.ts

@@ -1,4 +1,21 @@
 import type { JsonMap, Reason } from "./util.ts";
+import { runCommand } from "./util.ts";
+export declare const REQUIRED_OPENSPEC_MIN_VERSION = "1.4.1";
+export type OpenspecCliProbe = {
+    ok: boolean;
+    state: "ok" | "missing" | "invalid" | "too_old";
+    version: string | null;
+    message: string;
+};
+export declare function parse_openspec_version(raw: string): string | null;
+export declare function compare_versions(actual: string, required: string): number;
+export declare function openspec_cli_probe(opts?: {
+    cwd?: string;
+    commandExistsFn?: (cmd: string, meta?: {
+        cwd?: string;
+    }) => boolean;
+    run?: typeof runCommand;
+}): OpenspecCliProbe;
 export declare function openspec_status(change: string): JsonMap;
 export declare function openspec_validate(change: string): [boolean, string];
 export declare function openspec_version(): string;

package/dist/src/openspec.js

@@ -1,6 +1,93 @@
 import { dirname, join, resolve, sep } from "node:path";
 import { existsSync } from "node:fs";
-import { GATE_ALIASES, GATE_ROUTE, GuardError, ROUTE_ALIASES, ROUTE_ORDER, fingerprint_obj, isObject, reason, repr, runCommand, } from "./util.js";
+import { REQUIRED_OPENSPEC_CLI_SURFACES, GATE_ALIASES, GATE_ROUTE, GuardError, ROUTE_ALIASES, ROUTE_ORDER, commandExists, fingerprint_obj, isObject, reason, repr, runCommand, } from "./util.js";
+export const REQUIRED_OPENSPEC_MIN_VERSION = "1.4.1";
+export function parse_openspec_version(raw) {
+    const match = raw.match(/\b(\d+)\.(\d+)\.(\d+)(?:[-+][0-9A-Za-z.-]+)?\b/);
+    return match ? `${match[1]}.${match[2]}.${match[3]}` : null;
+}
+export function compare_versions(actual, required) {
+    const actualParts = actual.split(".").map((part) => Number.parseInt(part, 10));
+    const requiredParts = required.split(".").map((part) => Number.parseInt(part, 10));
+    for (let index = 0; index < Math.max(actualParts.length, requiredParts.length); index += 1) {
+        const actualPart = actualParts[index] ?? 0;
+        const requiredPart = requiredParts[index] ?? 0;
+        if (!Number.isFinite(actualPart))
+            return -1;
+        if (!Number.isFinite(requiredPart))
+            return 1;
+        if (actualPart > requiredPart)
+            return 1;
+        if (actualPart < requiredPart)
+            return -1;
+    }
+    return 0;
+}
+export function openspec_cli_probe(opts = {}) {
+    const commandExistsFn = opts.commandExistsFn ?? ((cmd, meta) => commandExists(cmd, { cwd: meta?.cwd }));
+    const run = opts.run ?? runCommand;
+    if (!commandExistsFn("openspec", { cwd: opts.cwd })) {
+        return {
+            ok: false,
+            state: "missing",
+            version: null,
+            message: "PATH 中缺少 OpenSpec CLI（openspec）",
+        };
+    }
+    const versionProc = run("openspec", ["--version"], { cwd: opts.cwd, timeout: 15_000 });
+    if (versionProc.error || versionProc.status !== 0) {
+        const output = (versionProc.error?.message ?? (versionProc.stderr || versionProc.stdout)).trim();
+        return {
+            ok: false,
+            state: "invalid",
+            version: null,
+            message: `\`openspec --version\` 执行失败：${output}`,
+        };
+    }
+    const rawVersion = `${versionProc.stdout}${versionProc.stderr}`.trim();
+    if (/openspec[-_\s]*chinese/iu.test(rawVersion)) {
+        return {
+            ok: false,
+            state: "invalid",
+            version: null,
+            message: "PATH 上的 openspec 来自 openspec-chinese，不是受支持的 @fission-ai/openspec CLI",
+        };
+    }
+    const version = parse_openspec_version(rawVersion);
+    if (version === null) {
+        return {
+            ok: false,
+            state: "invalid",
+            version: null,
+            message: "PATH 上的 OpenSpec CLI（openspec）无法报告语义版本，可能不是受支持的 @fission-ai/openspec",
+        };
+    }
+    if (compare_versions(version, REQUIRED_OPENSPEC_MIN_VERSION) < 0) {
+        return {
+            ok: false,
+            state: "too_old",
+            version,
+            message: `openspec ${version} 低于 SuperSpec 要求的最低版本 ${REQUIRED_OPENSPEC_MIN_VERSION}`,
+        };
+    }
+    for (const args of REQUIRED_OPENSPEC_CLI_SURFACES) {
+        const proc = run("openspec", [...args], { cwd: opts.cwd, timeout: 15_000 });
+        if (proc.error || proc.status !== 0) {
+            return {
+                ok: false,
+                state: "invalid",
+                version,
+                message: `openspec ${version} 缺少必需的原生能力：\`openspec ${args.join(" ")}\` 执行失败`,
+            };
+        }
+    }
+    return {
+        ok: true,
+        state: "ok",
+        version,
+        message: `openspec ${version} satisfies SuperSpec requirements`,
+    };
+}
 export function openspec_status(change) {
     const proc = runCommand("openspec", ["status", "--change", change, "--json"], { timeout: 30_000 });
     if (proc.error) {
@@ -28,8 +115,7 @@ export function openspec_version() {
     if (proc.error || proc.status !== 0)
         return "unknown";
     const raw = (proc.stdout || proc.stderr).trim();
-    const match = raw.match(/\d+\.\d+\.\d+/);
-    return match ? match[0] : raw || "unknown";
+    return (parse_openspec_version(raw) ?? raw) || "unknown";
 }
 export function openspec_status_shape_reasons(status) {
     const problems = [];

package/dist/src/project_init.d.ts

@@ -1,4 +1,31 @@
-import { type JsonMap } from "./core.ts";
+import { type JsonMap, type OpenspecCliProbe } from "./core.ts";
+export declare const OPENSPEC_NPM_PACKAGE = "@fission-ai/openspec";
+export declare const OPENSPEC_INSTALL_DOC_URL = "https://github.com/Fission-AI/OpenSpec#readme";
+export type OpenspecInstallPlan = {
+    manager: "npm" | "pnpm" | "yarn" | "bun";
+    cmd: string;
+    args: string[];
+    rendered: string;
+};
+export declare function recommended_openspec_install_plan(opts?: {
+    cwd?: string;
+    commandExistsFn?: (cmd: string, meta?: {
+        cwd?: string;
+    }) => boolean;
+}): OpenspecInstallPlan | null;
+export declare function forced_openspec_install_plan(plan: OpenspecInstallPlan): OpenspecInstallPlan;
+export declare function missing_openspec_cli_message(opts?: {
+    cwd?: string;
+    commandExistsFn?: (cmd: string, meta?: {
+        cwd?: string;
+    }) => boolean;
+}): string;
+export declare function openspec_cli_requirement_message(probe: OpenspecCliProbe, opts?: {
+    cwd?: string;
+    commandExistsFn?: (cmd: string, meta?: {
+        cwd?: string;
+    }) => boolean;
+}): string;
 export declare function project_init(repoRootRaw?: string, opts?: {
     force?: boolean;
 }): JsonMap;

package/dist/src/project_init.js

@@ -1,16 +1,63 @@
 import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { join, resolve } from "node:path";
-import { REQUIRED_SUPERSPEC_AGENT_ROLES, REQUIRED_OPENSPEC_CODEX_SKILLS, block, reason, read_agent_toml_name, read_skill_frontmatter_name, commandExists, runCommand, } from "./core.js";
+import { REQUIRED_SUPERSPEC_AGENT_ROLES, REQUIRED_OPENSPEC_CODEX_SKILLS, REQUIRED_OPENSPEC_MIN_VERSION, block, commandExists, openspec_cli_probe, reason, read_agent_toml_name, read_skill_frontmatter_name, runCommand, } from "./core.js";
 import { install_workflow } from "./install_engine.js";
+import { system_failure_zh } from "./i18n.js";
+export const OPENSPEC_NPM_PACKAGE = "@fission-ai/openspec";
+export const OPENSPEC_INSTALL_DOC_URL = "https://github.com/Fission-AI/OpenSpec#readme";
 const ROLE_DESCRIPTIONS = {
-    architect: "System design, boundaries, interfaces, and long-horizon tradeoffs",
-    critic: "Critical review of plans, evidence, assumptions, and scope drift",
-    "test-engineer": "Test strategy, coverage, and RED/GREEN evidence review",
-    "code-reviewer": "Code/spec/security review lane for the code-review workflow",
-    verifier: "Final completion evidence and verification review",
+    architect: "系统设计、边界、接口与长期取舍",
+    critic: "严格审查计划、证据、假设与范围漂移",
+    "test-engineer": "测试策略、覆盖率与 RED/GREEN 证据审查",
+    "code-reviewer": "代码 / 规格 / 安全审查",
+    verifier: "最终完成证据与验证审查",
 };
 function commandFailure(proc) {
-    return (proc.error?.message ?? (proc.stderr || proc.stdout)).trim();
+    return system_failure_zh((proc.error?.message ?? (proc.stderr || proc.stdout)).trim(), proc.status !== null && proc.status !== undefined ? `命令执行失败（退出状态码 ${proc.status}）。` : "命令执行失败，请查看终端日志后重试。");
+}
+function renderCommand(cmd, args) {
+    return [cmd, ...args].join(" ");
+}
+export function recommended_openspec_install_plan(opts = {}) {
+    const commandExistsFn = opts.commandExistsFn ?? ((cmd, meta) => commandExists(cmd, { cwd: meta?.cwd }));
+    const versionedPackage = `${OPENSPEC_NPM_PACKAGE}@latest`;
+    const candidates = [
+        { manager: "npm", cmd: "npm", args: ["install", "-g", versionedPackage] },
+        { manager: "pnpm", cmd: "pnpm", args: ["add", "-g", versionedPackage] },
+        { manager: "yarn", cmd: "yarn", args: ["global", "add", versionedPackage] },
+        { manager: "bun", cmd: "bun", args: ["add", "-g", versionedPackage] },
+    ];
+    for (const candidate of candidates) {
+        if (!commandExistsFn(candidate.cmd, { cwd: opts.cwd }))
+            continue;
+        return { ...candidate, rendered: renderCommand(candidate.cmd, candidate.args) };
+    }
+    return null;
+}
+export function forced_openspec_install_plan(plan) {
+    const versionedPackage = `${OPENSPEC_NPM_PACKAGE}@latest`;
+    const forced = {
+        npm: ["install", "-g", "--force", versionedPackage],
+        pnpm: ["add", "-g", "--force", versionedPackage],
+        yarn: ["global", "add", versionedPackage, "--force"],
+        bun: ["add", "-g", "--force", versionedPackage],
+    };
+    return { ...plan, args: forced[plan.manager], rendered: renderCommand(plan.cmd, forced[plan.manager]) };
+}
+export function missing_openspec_cli_message(opts = {}) {
+    return openspec_cli_requirement_message({
+        ok: false,
+        state: "missing",
+        version: null,
+        message: "PATH 中缺少 OpenSpec CLI（openspec）",
+    }, opts);
+}
+export function openspec_cli_requirement_message(probe, opts = {}) {
+    const plan = recommended_openspec_install_plan(opts);
+    if (plan) {
+        return `${probe.message}。需要 @fission-ai/openspec >= ${REQUIRED_OPENSPEC_MIN_VERSION}。可先运行 \`${plan.rendered}\` 安装或升级，然后重新运行 \`superspec init --scope project\`。`;
+    }
+    return `${probe.message}。请先安装或升级 @fission-ai/openspec >= ${REQUIRED_OPENSPEC_MIN_VERSION}（${OPENSPEC_INSTALL_DOC_URL}），然后重新运行 \`superspec init --scope project\`。`;
 }
 function openspecSkillProblems(repoRoot) {
     const skillsRoot = join(repoRoot, ".codex", "skills");
@@ -34,9 +81,9 @@ function writeSuperSpecAgent(repoRoot, name) {
         `description = "${ROLE_DESCRIPTIONS[name] ?? `superspec ${name} role`}"`,
         'model_reasoning_effort = "high"',
         'developer_instructions = """',
-        `You are the repo-local superspec ${name} native subagent.`,
-        "Follow the assigned superspec gate evidence task, cite concrete files, and report blockers upward.",
-        "Do not substitute main-thread self-review for required role evidence.",
+        `你是仓库本地的 superspec ${name} native subagent。`,
+        "遵循分配给你的 superspec gate 证据任务，引用具体文件，并把未通过的问题上报主流程。",
+        "不要用主流程自审替代必须的角色证据。",
         '"""',
         "",
     ].join("\n"), "utf8");
@@ -51,16 +98,17 @@ function writeSuperSpecPrompt(repoRoot, name) {
         'argument-hint: "superspec gate evidence task"',
         "---",
         "",
-        `You are the repo-local superspec ${name} role.`,
+        `你是仓库本地的 superspec ${name} 角色。`,
         "",
-        "Review the provided superspec gate context with concrete file-backed evidence. Produce a concise pass/block report, cite source anchors and target refs, and do not replace required native-subagent evidence with main-thread self-review.",
+        "请基于具体文件证据审查提供的 superspec gate 上下文，输出简洁的通过 / 未通过报告，引用 source anchors 与 target refs，并且不要用主流程自审替代必须的 native-subagent 证据。",
         "",
     ].join("\n"), "utf8");
     return filePath;
 }
 function ensureOpenSpecCodex(repoRoot, actions) {
-    if (!commandExists("openspec", { cwd: repoRoot }))
-        return ["openspec CLI is not available in PATH"];
+    const probe = openspec_cli_probe({ cwd: repoRoot });
+    if (!probe.ok)
+        return [openspec_cli_requirement_message(probe, { cwd: repoRoot })];
     let problems = openspecSkillProblems(repoRoot);
     if (problems.length === 0) {
         actions.push({ action: "openspec_codex_skills", status: "ok" });
@@ -71,10 +119,10 @@ function ensureOpenSpecCodex(repoRoot, actions) {
         action: "openspec init --tools codex .",
         status: init.status === 0 ? "updated" : "failed",
         refs: problems,
-        detail: init.status === 0 ? undefined : (init.stderr || init.stdout).trim(),
+        detail: init.status === 0 ? undefined : commandFailure(init),
     });
     if (init.error || init.status !== 0)
-        return [`openspec init failed: ${commandFailure(init)}`];
+        return [`openspec init 执行失败：${commandFailure(init)}`];
     problems = openspecSkillProblems(repoRoot);
     if (problems.length === 0)
         return [];
@@ -83,12 +131,12 @@ function ensureOpenSpecCodex(repoRoot, actions) {
         action: "openspec update --force .",
         status: update.status === 0 ? "updated" : "failed",
         refs: problems,
-        detail: update.status === 0 ? undefined : (update.stderr || update.stdout).trim(),
+        detail: update.status === 0 ? undefined : commandFailure(update),
     });
     if (update.error || update.status !== 0)
-        return [`openspec update failed: ${commandFailure(update)}`];
+        return [`openspec update 执行失败：${commandFailure(update)}`];
     problems = openspecSkillProblems(repoRoot);
-    return problems.length === 0 ? [] : [`OpenSpec Codex skills remain missing/invalid: ${problems.join(", ")}`];
+    return problems.length === 0 ? [] : [`OpenSpec 配套技能文件仍然缺失或无效：${problems.join(", ")}`];
 }
 function ensureSuperSpecRoles(repoRoot, actions) {
     const problems = [];
@@ -99,14 +147,14 @@ function ensureSuperSpecRoles(repoRoot, actions) {
             created.push(writeSuperSpecAgent(repoRoot, name));
         }
         else if (read_agent_toml_name(agentPath) !== name) {
-            problems.push(`invalid agent ${agentPath}`);
+            problems.push(`agent 文件无效：${agentPath}`);
         }
         const promptPath = join(repoRoot, ".codex", "prompts", `${name}.md`);
         if (!existsSync(promptPath) || !statSync(promptPath).isFile()) {
             created.push(writeSuperSpecPrompt(repoRoot, name));
         }
         else if (!readFileSync(promptPath, "utf8").trim()) {
-            problems.push(`empty prompt ${promptPath}`);
+            problems.push(`prompt 文件为空：${promptPath}`);
         }
     }
     actions.push({

package/dist/src/util.d.ts

@@ -1,3 +1,4 @@
+import { type WorkflowTermHint } from "./i18n.ts";
 export declare const SCHEMA_VERSION = 1;
 export declare const GUARD_VERSION = "superspec-guard@1";
 export declare const CONFIG_FILENAME = "config.yaml";
@@ -12,6 +13,9 @@ export type Reason = {
     code: string;
     message: string;
     refs: string[];
+    label_zh?: string;
+    hint_zh?: string;
+    message_zh?: string;
 };
 export type Decision = {
     allowed: boolean;
@@ -24,6 +28,16 @@ export type Decision = {
     block_reasons: Reason[];
     next_allowed_actions: string[];
     trust_warnings: string[];
+    actions?: JsonMap[];
+    decision_zh?: string;
+    gate_label_zh?: string;
+    gate_hint_zh?: string;
+    command?: string;
+    command_label_zh?: string;
+    command_hint_zh?: string;
+    next_allowed_actions_zh?: string[];
+    trust_warnings_zh?: string[];
+    workflow_terms_zh?: WorkflowTermHint[];
 };
 export type TaskInfo = {
     task_id: string;
@@ -82,7 +96,12 @@ export declare function block(change: string, gate: string, reasons: Reason[], o
     gate_summary?: Record<string, any>;
     next_actions?: string[];
 }): Decision;
-export declare function printDecision(decision: JsonMap): void;
+export declare function decorateDecision(decision: JsonMap, opts?: {
+    command?: string;
+}): JsonMap;
+export declare function printDecision(decision: JsonMap, opts?: {
+    command?: string;
+}): void;
 export declare function runCommand(cmd: string, args: string[], opts?: {
     cwd?: string;
     timeout?: number;
@@ -108,6 +127,7 @@ export declare function commandLookupInvocation(cmd: string, platform?: NodeJS.P
     args: string[];
     shell: boolean;
 };
+export declare function selectWindowsCommandCandidate(cmd: string, whereStdout: string): string;
 export declare function windowsShellEscapeArg(arg: string): string;
 export declare function windowsCmdShimInvocation(cmdPath: string, args: string[], comspec?: string): {
     cmd: string;