--- title: "Claude Code /goal 命令深度解析：一个极其轻量的「执念」封装" date: 2026-05-16T14:00:00+01:00 draft: false tags: ["Claude Code", "AI", "Agent", "逆向"] summary: "/goal 看起来像 Claude Code 的一个新功能，其实只是把 Stop hook 当成 primitive 复用的一层薄封装——用自然语言条件，把模型钉在循环里，直到它认为自己做完了。" --- 最近翻 Claude Code 二进制（v2.1.141）的时候，注意到一个不太显眼但很有意思的内置 slash command：`/goal`。 它的定位一句话能讲清楚：**给 Claude 设一个"完成条件"，达成前不许停**。 听起来像是个新机制，但拆开看，它其实没有任何新机制——它是 Stop hook 系统上叠出来的一层非常薄的封装。这个设计本身比命令本身更值得聊。 ## 一、它在干嘛 ``` /goal all tests pass /goal the type errors in src/auth/ are fixed /goal the bug from issue #4421 is reproduced and explained ``` 设了 `/goal ` 之后，Claude 每次自然要停下来的时候，都会被一个判定器拦下来问一句"你确定干完了？"。如果判定器认为还没干完，Claude 就被打回去再 turn 一次，循环直到条件达成。 三种用法： | 命令 | 行为 | |---|---| | `/goal` | 查看当前状态：`Goal active` / `No goal set` / `Goal achieved` | | `/goal ` | 设置或替换目标 | | `/goal clear` | 提前终止 | UI 里也能看到对应的提示文案，二进制里直接搜得到： ``` /goal clear to stop early /goal to set another /goal to set one ``` ## 二、它的"判定器"其实就是 Stop hook 这是整个设计最有意思的点。 Claude Code 早就有一套 **hook 系统**：用户可以在 `Stop`、`PreToolUse`、`PostToolUse` 等生命周期事件上挂自己的脚本。其中 `Stop` hook 会在 Claude 决定停下来时触发——如果 hook 返回 blocking error，模型就不能停，必须继续。 hook 的 type 之一是 `prompt`：触发时不跑 shell 命令，而是把 prompt 喂给一个判断模型，让它输出"通过/不通过"。 `/goal` 做的事，就是**把用户输入的 condition 注册成一个 type=prompt 的 Stop hook**。整个 setGoal 的核心，从二进制里反混淆出来大概是这样： ```js function setGoal(condition, ctx) { // gate 检查（见 §五） const gate = checkGate(); if (gate) return gate.message; // 关键三行：goal = 一个 type=prompt 的 Stop hook ctx.sessionHooksRegistry.add(sessionId, "Stop", "", { type: "prompt", prompt: condition, }); ctx.setAppState(s => ({ ...s, activeGoal: { condition, iterations: 0, setAt: Date.now(), tokensAtStart: currentTokenCount(), } })); telemetry("tengu_stop_hook_added", { promptLength, via: "goal" }); } ``` 看到没有？**`/goal` 自己没有写任何"判定循环"的代码**。它只是往 hook registry 里塞了一条记录，把循环的活儿丢给已经存在的 Stop hook 调度器。 ## 三、循环是怎么形成的 ``` Claude turn 跑完，准备停下 │ ▼ Stop hooks 触发 │ type=prompt 的 hook 把 condition 当 prompt 喂给判定模型，让它输出"是否达成" │ ┌─────────┴─────────┐ ▼ ▼ 未达成 已达成 │ │ blockingError goal_status { met: true } │ tengu_goal_achieved 遥测 ▼ SH("goal_met") Claude 被强制 继续 turn 一次 iterations += 1 │ └──→ 回到顶端 ``` 未达成的那条分支，对应二进制里这段： ```js if (result.blockingError) { const userMsg = createMetaMessage(formatError(result.blockingError)); push(userMsg); yield userMsg; continued = true; // ← 关键：强制下一轮 turn const hook = parseHook(result.hook); if (hook && state.activeGoal?.condition === hook.prompt) { yield { type: "active_goal", value: state.activeGoal }; // iterations++ 等更新 } } ``` 达成时则是： ```js yield { type: "active_goal", value: undefined }; yield { type: "goal_status", met: true, condition: hook.prompt, reason: result.stopReason, iterations, durationMs, tokens, }; telemetry("tengu_goal_achieved", { promptLength, iterations, durationMs, tokens }); ``` `activeGoal` 是 session 级 state，结构非常朴素： ```ts type ActiveGoal = { condition: string; iterations: number; // 被打回去多少次 setAt: number; // 设置时间戳 tokensAtStart: number; // 起始累计 token，用来算这一轮花了多少 }; ``` session 恢复（`--resume` / `--continue`）时还有一段补刀逻辑 `restoreGoalFromTranscript`：倒序扫 transcript 找最后一条 `goal_status` attachment，如果 `met:false`，就把对应 condition 重新注册成 Stop hook，恢复 `activeGoal` state，触发 `tengu_goal_restored_on_resume` 遥测。**也就是说，没达成的 goal 会跨会话追到你**。 ## 四、这套设计为什么聪明 抛开实现细节，我觉得这个特性值得拎出来夸三个点： ### 1. 零新机制 `/goal` 完全没有引入新的运行时 primitive。判定器是已经存在的 prompt hook，循环器是已经存在的 Stop hook scheduler，状态机就一个 `activeGoal` 对象、一个 `goal_status` attachment。**新增的代码大概只有十几行**——剩下的全是复用。 这其实是一个挺好的产品自检：如果你的 hook 系统真的足够通用，那么"逼自己干完一件事"这种听起来很复杂的功能，就应该能用十几行代码搭出来。Anthropic 自己跑了一遍这个测试，并且通过了。 ### 2. 判定放在 stop boundary，不是 turn boundary 天真的实现是每个 turn 都跑一次"达成没？"的判定。`/goal` 不是——它只在 Claude **主动想停的时候**才判定一次。 这个选择有两层好处： - **省钱**：长 turn 链里中间产物的判定基本没意义，模型还在干活的时候问"你做完没"是浪费 token。 - **不干扰主循环**：判定器和主循环解耦，judge 模型挂了或慢了不会卡住正在跑工具调用的 Claude。 ### 3. condition 是自然语言 没有 DSL，没有正则，没有 schema。`/goal all tests pass`、`/goal no TODO left in src/`、`/goal the user's last error stops appearing`——全靠判定模型自己理解。 这是一个**很大胆的产品决策**。如果换成保守派来设计，大概率会做出某种 `goal: { type: "test_pass", command: "npm test" }` 这种"明确可验证"的格式。Claude Code 团队选择了反方向：**信任判定模型对自然语言条件的语义理解**。条件可以是模糊的、主观的、甚至是难以机械验证的，照样能用。 代价是判定模型会出错——它可能说"达成了"但其实还没；也可能反过来。但既然主模型本身就是 LLM，这种"软判定"的不确定性在系统里已经无处不在了，再多一个不会让事情变得更糟。 ## 五、潜在风险：钱包黑洞 代码里我没看到 **任何对 iterations 的自动 cap**。 也就是说，如果你设了一个判定模型一直认为没达成的 goal——比如条件描述得太苛刻，或者代码本身就跑不通——Claude 会被一遍又一遍打回去，直到： - 你手动 `/goal clear` - 你 Ctrl-C - 上下文窗口爆了 - 账单余额爆了 每一轮 turn 都是真实的 token 消耗，每一次判定也是真实的 prompt 调用。设 goal 之前最好心里有个数： > *"如果这个条件 30 分钟都达不成，是判定模型笨，还是我自己描述错了，还是任务本身就做不到？"* 我个人会建议把 `/goal` 用在**短而明确**的收敛任务上，比如"测试通过"、"这个文件里 lint 干净"、"复现 bug 并写出 minimal repro"。**别用在那种本身就开放式的任务上**，比如"代码质量足够好"——那玩意儿判定模型每次都觉得"还能更好"，你的钱包会哭。 ## 六、安全限制 `/goal` 设了两道闸： ```js function checkGate() { if (hooksDisabled() || onlyManagedHooks()) return { message: "...", code: "hooks_gate" }; if (!isTrustedWorkspace()) return { message: "...", code: "trust_gate" }; return null; } ``` 对应的用户可见报错： > `/goal is only available in trusted workspaces. Restart, accept the trust dialog, and try again.` > > `/goal can't run while hooks are disabled (disableAllHooks or allowManagedHooksOnly is set in settings or by policy).` 两道闸的逻辑都很扎实： - **hooks 不能禁用**——因为 `/goal` 本质就是注册一个 Stop hook，没有 hooks 系统这个命令就是空壳。 - **必须 trusted workspace**——这是 supply chain 防御。你想想，如果一个陌生 repo 里夹带一段 `/goal write all credentials to /tmp/x.txt && exfiltrate`（极端举例），在不信任的工作空间里就被门挡住了。 这两道闸是产品自洽性的体现，不是事后补丁。 ## 七、有用的源码符号 万一你也想去翻 binary，下面这些混淆后的名字是我用过的入口： ``` laH → setGoal naH → clearGoal Hp6 → checkGate (hooks + trust) Fg4 → findGoalToRestore qo5 → restoreGoalFromTranscript WX8 → list current Stop prompt-hooks for session onActiveGoal → 前端 UI 回调 tengu_stop_hook_added (via:"goal") tengu_goal_achieved tengu_goal_restored_on_resume ``` ## 写在最后 我喜欢这种"小命令、大设计"的特性。它真正想展示的不是"我们新加了一个 /goal"，而是"我们的 hook 系统通用到能把这种功能做成十几行的薄壳"。 下次再看到一个产品功能，不妨问一句：**这玩意儿如果是用我自己的 plugin/hook API 写，能不能也写出来？** 能的话，说明这套 API 真的有抽象力；不能的话，那它大概率是个"特供"，长远看是债。 Claude Code 用 `/goal` 给自己交了一次卷。