用 Claude Code Hook 和 Codex Wrapper 为 Prompt 自动打标签

建议点击 查看原文 查看最新内容。

原文链接: https://typonotes.com/posts/2026/11/20/claude-auto-tagged-prompt-for-magpie/

为什么要给 Prompt 打标签?

我用 Magpie 作为模型代理,希望它根据任务类型选择合适的模型。目前主要有三类任务:

  • [TASK: CODE_DEV]:编写、修改或重构代码。
  • [TASK: LOCAL_TEST]:只运行 lint、单元测试、构建或静态检查,不修改代码。
  • [TASK: VISUAL_TEST]:查看截图、检查页面布局,或进行浏览器视觉验收。

Magpie 可以通过语义理解判断任务,但明确的标签能让路由规则更稳定。关键是要在请求到达 Magpie、执行路由判断之前添加标签;仅在 Agent 收到请求后再补充,未必能影响代理层已经做出的选择。

本文用同一个 Python 脚本维护分类规则,再通过 Claude Code 的 UserPromptSubmit Hook 和 Codex CLI 的 shell wrapper 分别接入。

先定义分类规则

标签只是路由提示,不是模型名称。模型和标签的对应关系应集中配置在 Magpie 中,例如:

标签Magpie 路由目标适用任务
[TASK: CODE_DEV]代码开发主力模型编写、修改或重构代码
[TASK: LOCAL_TEST]轻量、快速的模型运行检查,不改代码
[TASK: VISUAL_TEST]支持视觉输入的模型截图、页面和视觉验收

建议在 Magpie 中让精确标签规则优先于语义兜底规则。还要确认 Magpie 实际检查请求中的哪个字段:用户消息、系统上下文,还是完整请求体。客户端加上标签,不代表代理一定能在它的匹配字段中看到标签。

分类时可以采用以下优先级:

  1. 视觉任务优先;如果请求包含截图,或明确要求检查页面视觉效果,标记为 VISUAL_TEST。
  2. 只有“运行测试或检查、且不修改代码”的任务才标记为 LOCAL_TEST。
  3. 包含代码编写、修改或修复的任务标记为 CODE_DEV。例如“修复代码并运行测试”仍属于代码开发,避免把需要改代码的任务路由给只适合快速检查的模型。
  4. 无法确定时不打标签,交给 Magpie 的语义规则兜底。

本地规则分类不需要再调用一个 LLM,但新增的标签仍会占用少量请求上下文 Token。分类规则是启发式的,应该从简单开始,再根据真实请求日志调整。

一个脚本,两种接入方式

将以下脚本保存为 ~/.local/bin/auto_tagger.py:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
#!/usr/bin/env python3
import json
import os
import re
import sys

VISUAL_RE = re.compile(
    r"(截图|视觉|页面布局|样式|对齐|UI|frontend|browser|screenshot|render)",
    re.I,
)
CODE_EDIT_RE = re.compile(
    r"(编写|写|实现|新增|修改|重构|修复|开发|implement|write|modify|refactor|fix)",
    re.I,
)
TEST_RE = re.compile(
    r"(lint|eslint|prettier|pytest|go\s+test|npm\s+test|单测|测试|typecheck|静态检查|编译|build)",
    re.I,
)
TEST_ACTION_RE = re.compile(
    r"(运行|跑|执行|检查|验证|一下|run|execute|check|verify|lint|pytest|go\s+test|npm\s+test|typecheck|编译|build)",
    re.I,
)


def classify(prompt: str, has_image: bool = False):
    if has_image or VISUAL_RE.search(prompt):
        return "[TASK: VISUAL_TEST]"
    # 改代码并运行测试仍归为代码开发,不拆散到另一个模型。
    if CODE_EDIT_RE.search(prompt):
        return "[TASK: CODE_DEV]"
    if TEST_RE.search(prompt) and TEST_ACTION_RE.search(prompt):
        return "[TASK: LOCAL_TEST]"
    return None


def add_tag(prompt: str, tag: str):
    if re.match(r"^\[TASK: [A-Z_]+\]", prompt):
        return prompt
    return f"{tag} {prompt}"


def handle_codex(real_codex: str, args: list[str]):
    # 只处理非交互的 `codex exec`;交互式 TUI 中的后续输入不会经过 shell wrapper。
    if args and args[0] == "exec" and len(args) > 1:
        prompt = args[-1]
        has_image = any(
            arg in ("-i", "--image") or arg.startswith("--image=")
            for arg in args
        )
        # 假设 Prompt 是最后一个位置参数,且 CLI 选项放在 Prompt 前面。
        if prompt and not prompt.startswith("-"):
            tag = classify(prompt, has_image)
            if tag:
                args[-1] = add_tag(prompt, tag)

    # 用 exec 保留 Codex 的退出码、信号行为和参数边界。
    os.execv(real_codex, [real_codex, *args])


def handle_claude_code():
    data = json.load(sys.stdin)
    prompt = data.get("prompt", "")
    tag = classify(prompt)
    if not tag:
        return

    # Hook 通过 additionalContext 提供提示;它不是对原始 prompt 的原地改写。
    print(json.dumps({
        "hookSpecificOutput": {
            "hookEventName": "UserPromptSubmit",
            "additionalContext": f"Magpie route hint: {tag}",
        }
    }, ensure_ascii=False))


def main():
    if len(sys.argv) > 1 and sys.argv[1] == "--codex":
        if len(sys.argv) < 3:
            raise SystemExit("usage: auto_tagger.py --codex /path/to/codex [args...]")
        handle_codex(sys.argv[2], sys.argv[3:])
    else:
        handle_claude_code()


if __name__ == "__main__":
    main()

这个分类器刻意保持简单:含糊的请求不贴标签;“修改代码并运行测试”优先按代码开发处理;视觉关键词优先级最高。上线前应按自己的表达习惯调整关键词,并用实际请求验证结果。

Claude Code:用 UserPromptSubmit Hook 注入路由提示

在 ~/.claude/settings.json 中添加 Hook 配置:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python3 ~/.local/bin/auto_tagger.py"
          }
        ]
      }
    ]
  }
}

Hook 收到 Claude Code 传来的 JSON,从 prompt 字段进行分类,并按 Hook 协议在标准输出中返回 JSON。这里使用 additionalContext 告诉 Claude 当前任务的路由标签;它不会像 Codex wrapper 那样直接重写原始 Prompt 字符串。

因此,接入后要特别验证 Magpie 是否能从实际请求中读到这段 additionalContext。如果 Magpie 只匹配用户消息文本,或在 Hook 执行之前已经完成路由,这种接法就不能保证命中标签规则。此时应改用 Magpie 前面的请求预处理层,或使用能在请求发送前修改用户消息的客户端 wrapper。

另外,Claude Code Hook 输入里的 prompt 不一定包含图片文件本身。视觉路由最好由 Magpie 根据真实图像输入判断;如需客户端识别附件,应先确认当前 Hook 版本实际提供的字段,不要假设存在 images 或 attachments 字段。

Codex CLI:用 shell wrapper 改写 exec Prompt

Codex CLI 的 shell wrapper 可以在调用真实 Codex 可执行文件之前修改参数。下面的 Zsh 函数只把 codex exec 交给 Python 脚本处理;交互模式、帮助参数等会原样传给 Codex。将它添加到 ~/.zshrc:

1
2
3
4
5
codex() {
  local real_codex
  real_codex=$(whence -p codex) || return 127
  python3 "$HOME/.local/bin/auto_tagger.py" --codex "$real_codex" "$@"
}

重新加载配置:

1
source ~/.zshrc

Codex 模式通过 os.execv 直接替换 Python 进程,不需要把参数拼成一条 shell 命令,也不会因空格或引号而重新拆分参数。示例实现假设 codex exec 的 Prompt 是最后一个位置参数,CLI 选项放在 Prompt 前面;如果你使用的 Codex 版本支持不同的位置参数形式,先确认 CLI 用法,再调整参数定位逻辑。

例如:

1
codex exec "帮我用 Go 写一个 Redis 连接池健康检查"

脚本会把最后一个 Prompt 参数改成:

1
[TASK: CODE_DEV] 帮我用 Go 写一个 Redis 连接池健康检查

而下面的检查请求会变为:

1
[TASK: LOCAL_TEST] 运行 eslint 检查当前目录

如果请求通过 -i 或 --image 附带图片,或者 Prompt 命中视觉关键词,则会加上 [TASK: VISUAL_TEST]。脚本不会处理 Codex 交互式 TUI 内输入的每一轮 Prompt,因为这些输入不会重新经过 shell 函数。

接入后如何验证

不要只看客户端有没有打印标签,要确认 Magpie 最终收到什么、匹配了哪条规则,以及实际选择了哪个模型。可以按下面的用例逐一检查:

输入预期标签
帮我实现一个 Go HTTP 接口[TASK: CODE_DEV]
运行 eslint 检查当前目录[TASK: LOCAL_TEST]
对比截图里的按钮和页面边距[TASK: VISUAL_TEST]
修改代码并运行单测[TASK: CODE_DEV]
无法确定类别的普通问题不加标签,使用 Magpie 语义兜底

确认 Claude Code 和 Codex 两条链路都能在 Magpie 的请求记录中看到预期标签后,再逐步扩大自动分类范围。如果日志中看不到 Hook 的 additionalContext,不要继续调整正则;问题在标签到达路由层之前的链路,需要更换注入位置。

小结

  • Codex wrapper 可以在调用 CLI 前改写 codex exec 的 Prompt 参数,适合需要把标签放进用户消息文本的场景。
  • Claude Code 的 UserPromptSubmit Hook 可以返回 additionalContext,但它不等同于原地修改 Prompt;必须验证 Magpie 是否能读取这段上下文。
  • 分类器应优先处理明确任务,对混合任务和不确定输入保守处理,并保留 Magpie 的语义兜底。
  • 标签路由最终是否生效,取决于 Magpie 的匹配字段和规则配置,而不只是客户端脚本。