diff --git a/content/posts/claude-code-goal.md b/content/posts/claude-code-goal.md index e69de29..677a58a 100644 --- a/content/posts/claude-code-goal.md +++ b/content/posts/claude-code-goal.md @@ -0,0 +1,245 @@ +--- +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` 给自己交了一次卷。