@peterxiaoyang/superspec 0.1.8 → 0.1.10

package/README.md

@@ -82,6 +82,8 @@ superspec init --scope project
 
 这条命令的意思是：把 SuperSpec 当前可用的工作流入口安装到项目里。
 
+初始化还会安装托管的 `.codex/hooks.json`。它会让 Codex 在写文件前、工具执行后、子智能体启动和停止时调用 SuperSpec，做检查和记录。
+
 Windows PowerShell 如果拦截 npm 的 `.ps1` 脚本，请改用：
 
 ```powershell
@@ -157,6 +159,18 @@ openspec/changes/<变更ID>/.superspec/
 `.superspec/` 要不要提交到 git，由你的团队决定。
 如果不提交，删掉后就没有 git 历史可以恢复。
 
+## Hook 会做什么
+
+SuperSpec 安装的 hook 会在几个关键时机运行：
+
+- 写文件前：检查是否会改到 SuperSpec 的过程记录、提前归档、绕过任务检查，或写到当前任务不该写的地方
+- 工具执行后：如果刚跑的是测试或验证命令，就记录这次结果
+- 子智能体启动和停止时：记录这次子智能体运行的基本信息
+
+这些 hook 的默认超时时间是 `120` 秒。这个时间限制的是 hook 自己的检查过程，不限制 `npm test`、构建命令或子智能体本身能运行多久。
+
+hook 不是安全沙箱。它能减少误操作、拦住一部分明显会破坏流程记录的写入，并留下审计线索；但不能保证阻止所有绕过，也不能把记录变成不可伪造的安全证明。
+
 ## 重要边界
 
 SuperSpec 能让流程更规范，但它不是安全锁。
@@ -175,7 +189,7 @@ SuperSpec 能让流程更规范，但它不是安全锁。
 - 阻止恶意伪造记录
 - 替代正式的安全审计、合规审计或法律证明
 
-也就是说，SuperSpec v1 是“流程纪律工具”，不是“强制安全系统”。
+也就是说，SuperSpec 目前是“流程纪律 + 审计辅助工具”，不是“强制安全系统”。hook 会增强可见性和一部分写入检查，但它仍然不能替代正式的安全控制。
 
 ## 常用命令
 
@@ -223,6 +237,7 @@ superspec doctor
 
 ```text
 .codex/
+  hooks.json
   skills/superspec-explore/
   skills/superspec-propose/
   skills/superspec-apply/

package/dist/src/hooks/health.js

@@ -7,26 +7,26 @@ const EXPECTED_HOOK_MATRIX = [
     {
         eventName: "PreToolUse",
         matcher: "Bash|apply_patch|Edit|Write|mcp__.*",
-        timeout: 10,
-        statusMessage: "SuperSpec hook write policy",
+        timeout: 120,
+        statusMessage: "SuperSpec 写入策略检查",
     },
     {
         eventName: "PostToolUse",
         matcher: "Bash",
-        timeout: 30,
-        statusMessage: "SuperSpec hook runtime evidence",
+        timeout: 120,
+        statusMessage: "SuperSpec 运行证据记录",
     },
     {
         eventName: "SubagentStart",
         matcher: ".*",
-        timeout: 30,
-        statusMessage: "SuperSpec hook subagent start",
+        timeout: 120,
+        statusMessage: "SuperSpec 子智能体启动记录",
     },
     {
         eventName: "SubagentStop",
         matcher: ".*",
-        timeout: 30,
-        statusMessage: "SuperSpec hook subagent stop",
+        timeout: 120,
+        statusMessage: "SuperSpec 子智能体停止记录",
     },
 ];
 function isRecord(value) {

package/dist/src/init_cli.js

@@ -4,12 +4,36 @@ import { install_workflow, uninstall_workflow, update_workflow } from "./install
 import { homedir } from "node:os";
 import { resolve } from "node:path";
 import { createInterface } from "node:readline/promises";
-import { system_failure_zh } from "./i18n.js";
+import { action_detail_zh, action_status_zh, reason_message_zh, system_failure_zh } from "./i18n.js";
 function usage() {
     return "usage: superspec init [-h] [--scope {project,user}] [--path PATH] [--codex-home PATH] [--format {json,agent,user}] [--create] [--update] [--uninstall] [--dry-run] [--force]\n";
 }
 function help() {
-    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  --format {json,agent,user} 输出格式；json 用于诊断，agent/user 用于安全展示\n  --user-facing          等价于 --format user\n  --create               兼容参数；init 默认就会创建缺失内容\n  --update               按 manifest 更新 SuperSpec 管理的文件；用户改动文件保留，新的版本写入 *.new\n  --uninstall            按 manifest 卸载 SuperSpec 管理的文件；.superspec 数据与既有/用户改动文件会保留\n  --dry-run              配合 --uninstall 时只预览将删除的文件，不实际修改\n  --force                安装时覆盖已有且内容不同的文件，并保留 *.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  --format {json,agent,user} 输出格式（默认：user）；json 用于诊断或自动化，agent 用于工作流消费\n  --user-facing          等价于 --format user\n  --create               兼容参数；init 默认就会创建缺失内容\n  --update               按 manifest 更新 SuperSpec 管理的文件；用户改动文件保留，新的版本写入 *.new\n  --uninstall            按 manifest 卸载 SuperSpec 管理的文件；.superspec 数据与既有/用户改动文件会保留\n  --dry-run              配合 --uninstall 时只预览将删除的文件，不实际修改\n  --force                安装时覆盖已有且内容不同的文件，并保留 *.bak 备份\n`;
+}
+function requestedOutputFormat(argv) {
+    if (argv.includes("--user-facing"))
+        return "user";
+    let selected = null;
+    for (let idx = 0; idx < argv.length; idx += 1) {
+        if (argv[idx] !== "--format")
+            continue;
+        const value = argv[idx + 1];
+        if (value === undefined || value.startsWith("--"))
+            return null;
+        selected = value;
+    }
+    if (selected === null)
+        return null;
+    try {
+        return parseDecisionOutputFormat(selected);
+    }
+    catch {
+        return null;
+    }
+}
+function fallbackOutputFormat(argv) {
+    return requestedOutputFormat(argv) ?? "user";
 }
 function parse_init_argv(argv) {
     const getValues = (flag) => {
@@ -45,7 +69,7 @@ function parse_init_argv(argv) {
         parseDecisionOutputFormat(value);
     const selectedFormat = argv.includes("--user-facing")
         ? "user"
-        : (formatValues.length > 0 ? formatValues[formatValues.length - 1] : "json");
+        : (formatValues.length > 0 ? formatValues[formatValues.length - 1] : "user");
     const format = parseDecisionOutputFormat(selectedFormat);
     return {
         path: resolve(getValue("--path") ?? process.cwd()),
@@ -60,6 +84,118 @@ function parse_init_argv(argv) {
 function joinHomeCodex() {
     return `${homedir()}/.codex`;
 }
+function scopeLabel(scope) {
+    return scope === "user" ? "用户级" : "项目级";
+}
+function modeLabel(mode, dryRun) {
+    if (mode === "update")
+        return "更新";
+    if (mode === "uninstall")
+        return dryRun ? "卸载预览" : "卸载";
+    return "初始化";
+}
+function actionSummary(actions) {
+    if (!Array.isArray(actions) || actions.length === 0)
+        return "";
+    const counts = new Map();
+    for (const item of actions) {
+        if (!item || typeof item !== "object")
+            continue;
+        const status = String(item.status ?? "");
+        if (!status)
+            continue;
+        counts.set(status, (counts.get(status) ?? 0) + 1);
+    }
+    const changedOrder = ["created", "updated", "removed", "would_remove", "skipped", "failed"];
+    const parts = changedOrder
+        .map((status) => [status, counts.get(status) ?? 0])
+        .filter(([, count]) => count > 0)
+        .map(([status, count]) => `${action_status_zh(status)} ${count} 项`);
+    if (parts.length > 0)
+        return parts.join("，");
+    const okCount = counts.get("ok") ?? 0;
+    return okCount > 0 ? `已检查 ${okCount} 项，无需改动` : "";
+}
+function actionTarget(action) {
+    const match = action.match(/^(?:install|update|uninstall(?: rmdir)?)\s+(.+)$/u);
+    return match?.[1] ?? "";
+}
+function skippedActionNotes(actions) {
+    if (!Array.isArray(actions))
+        return [];
+    const groups = new Map();
+    for (const item of actions) {
+        if (!item || typeof item !== "object")
+            continue;
+        const action = String(item.action ?? "");
+        const status = String(item.status ?? "");
+        if (status !== "skipped")
+            continue;
+        const detail = String(item.detail ?? "");
+        const note = detail ? action_detail_zh(detail) : "有文件被保留未改动；需要完整列表时添加 --format json。";
+        const target = actionTarget(action);
+        const group = groups.get(note) ?? { count: 0, targets: [] };
+        group.count += 1;
+        if (target && group.targets.length < 3)
+            group.targets.push(target);
+        groups.set(note, group);
+    }
+    return [...groups.entries()].map(([note, group]) => {
+        const hiddenCount = group.count - group.targets.length;
+        if (group.targets.length === 0)
+            return `${note}（${group.count} 项）`;
+        const suffix = hiddenCount > 0 ? ` 等 ${group.count} 项` : "";
+        return `${note}（${group.targets.join("，")}${suffix}）`;
+    });
+}
+function knownInitProblemMessageZh(message) {
+    if (/install manifest missing; run superspec init before --update/iu.test(message)) {
+        return "缺少安装清单；请先运行 superspec init，再执行 update。";
+    }
+    if (/install manifest missing; nothing to uninstall/iu.test(message)) {
+        return "缺少安装清单；当前没有可卸载的 SuperSpec 管理文件。";
+    }
+    return null;
+}
+function reasonTextZh(item) {
+    const code = String(item.code ?? "");
+    const message = String(item.message ?? "");
+    const refs = Array.isArray(item.refs) ? item.refs.map((ref) => String(ref)) : [];
+    return knownInitProblemMessageZh(message) ?? reason_message_zh(code, message, refs);
+}
+function renderInitUserDecision(decision, opts = {}) {
+    const lines = [];
+    const op = modeLabel(opts.mode, opts.dryRun);
+    lines.push(`SuperSpec ${op}${decision.allowed ? "完成" : "未完成"}。`);
+    lines.push(`范围：${scopeLabel(opts.scope)}。`);
+    const root = opts.targetRoot ?? String(decision.install_root ?? decision.project_root ?? "");
+    if (root)
+        lines.push(`位置：${root}`);
+    const summary = actionSummary(decision.actions);
+    if (decision.allowed && summary)
+        lines.push(`处理：${summary}。`);
+    const skippedNotes = skippedActionNotes(decision.actions);
+    if (decision.allowed && skippedNotes.length > 0) {
+        lines.push("跳过项：");
+        for (const note of skippedNotes)
+            lines.push(`- ${note}`);
+    }
+    const reasons = Array.isArray(decision.block_reasons) ? decision.block_reasons : [];
+    if (!decision.allowed && reasons.length > 0) {
+        lines.push("原因：");
+        for (const item of reasons)
+            lines.push(`- ${reasonTextZh(item)}`);
+        lines.push("修正后重新运行同一命令；需要完整诊断时添加 --format json。");
+    }
+    return `${lines.join("\n")}\n`;
+}
+function printInitDecision(decision, opts) {
+    if (opts.format === "user") {
+        process.stdout.write(renderInitUserDecision(decision, opts));
+        return;
+    }
+    printDecision(decision, { command: opts.command ?? "init", format: opts.format });
+}
 function commandFailure(proc) {
     const output = (proc.error?.message ?? (proc.stderr || proc.stdout)).trim();
     if (output)
@@ -156,12 +292,19 @@ function openspecPreflightBlocked(args, scope, installResult) {
     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({
+    printInitDecision({
         ...decision,
         project_root: args.path,
         install_scope: scope,
         install_root: targetRoot,
-    }, { command: "init", format: args.format });
+    }, {
+        command: "init",
+        format: args.format,
+        mode: args.mode,
+        scope,
+        targetRoot,
+        dryRun: args.dryRun,
+    });
     return 1;
 }
 function run_init(args, scope) {
@@ -188,7 +331,14 @@ function run_init(args, scope) {
     }
     summary.install_scope = scope;
     summary.install_root = targetRoot;
-    printDecision(summary, { command: "init", format: args.format });
+    printInitDecision(summary, {
+        command: "init",
+        format: args.format,
+        mode: args.mode,
+        scope,
+        targetRoot,
+        dryRun: args.dryRun,
+    });
     return summary.allowed ? 0 : 1;
 }
 export function main_init(argv = process.argv.slice(2)) {
@@ -208,7 +358,14 @@ export function main_init(argv = process.argv.slice(2)) {
     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]), { command: "init", format: args?.format });
+        printInitDecision(block(change, "guard_error", [errReason]), {
+            command: "init",
+            format: args?.format ?? fallbackOutputFormat(argv),
+            mode: args?.mode,
+            scope: args?.scope ?? "project",
+            targetRoot: args?.path,
+            dryRun: args?.dryRun,
+        });
         return 2;
     }
 }
@@ -229,7 +386,14 @@ export async function main_init_async(argv = process.argv.slice(2)) {
     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]), { command: "init", format: args?.format });
+        printInitDecision(block(change, "guard_error", [errReason]), {
+            command: "init",
+            format: args?.format ?? fallbackOutputFormat(argv),
+            mode: args?.mode,
+            scope: args?.scope ?? "project",
+            targetRoot: args?.path,
+            dryRun: args?.dryRun,
+        });
         return 2;
     }
 }

package/dist/superspec.js

@@ -30,7 +30,7 @@ function help() {
         "  version     print SuperSpec CLI version",
         "",
         "examples:",
-        "  superspec init --scope project --format agent",
+        "  superspec init --scope project",
         "  superspec init --scope user",
         "  superspec guard check-init --change <change> --format agent",
         "  superspec doctor",
@@ -49,7 +49,7 @@ function updateHelp() {
         "  --user, --global        equivalent to --scope user",
         "  --path PATH             project root for project scope (default: current directory)",
         "  --codex-home PATH       Codex user home for user scope (default: $CODEX_HOME or ~/.codex)",
-        "  --format {json,agent,user} output format; use agent for workflow consumption",
+        "  --format {json,agent,user} output format (default: user); use json for diagnostics/automation",
         "  --local-only            skip npm self-update and use the currently installed package",
         "  -h, --help              show this help",
         "",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peterxiaoyang/superspec",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "description": "SuperSpec workflow package: guard runtime, generic workflow templates, and Codex adapter payload.",
   "repository": {
     "type": "git",

package/templates/hooks/codex-hooks.json

@@ -12,8 +12,8 @@
           {
             "type": "command",
             "command": "superspec-hook --change \"$SUPERSPEC_CHANGE\"",
-            "timeout": 10,
-            "statusMessage": "SuperSpec hook write policy"
+            "timeout": 120,
+            "statusMessage": "SuperSpec 写入策略检查"
           }
         ]
       }
@@ -25,8 +25,8 @@
           {
             "type": "command",
             "command": "superspec-hook --change \"$SUPERSPEC_CHANGE\"",
-            "timeout": 30,
-            "statusMessage": "SuperSpec hook runtime evidence"
+            "timeout": 120,
+            "statusMessage": "SuperSpec 运行证据记录"
           }
         ]
       }
@@ -38,8 +38,8 @@
           {
             "type": "command",
             "command": "superspec-hook --change \"$SUPERSPEC_CHANGE\"",
-            "timeout": 30,
-            "statusMessage": "SuperSpec hook subagent start"
+            "timeout": 120,
+            "statusMessage": "SuperSpec 子智能体启动记录"
           }
         ]
       }
@@ -51,8 +51,8 @@
           {
             "type": "command",
             "command": "superspec-hook --change \"$SUPERSPEC_CHANGE\"",
-            "timeout": 30,
-            "statusMessage": "SuperSpec hook subagent stop"
+            "timeout": 120,
+            "statusMessage": "SuperSpec 子智能体停止记录"
           }
         ]
       }