HookPrompt

中文 | English

HookPrompt

把随口说出的需求，自动整理成可执行、可验收的专业提示词
因合并关系，本仓库已迁入 Kim Service 合集，不再单独发布新版本。请前往 Kim Service 获取新版本、安装说明和更新记录。

简介

HookPrompt 是一个面向 Claude Code、Codex 等 Agent 工具的 UserPromptSubmit Hook。它会在用户输入进入模型前，把自然语言请求整理成更适合执行的结构化任务简报。

它重点解决三类问题：

- 用户只说了模糊需求，Agent 不知道真实目标和验收标准。
- 用户反馈很短，例如“这个不行”“报错了”“帮我看看”，但其实需要诊断或修复。
- 任务需要清晰边界、成功标准和验证计划，否则容易变成“看起来执行了，但没有真的完成”。

HookPrompt 默认要求模型在首条回复中展示三段式结果：

优化后的完整提示词会使用 role-first、outcome-contract、tagged structure、success criteria 和 verification plan，让后续执行更清楚、更可控。

工作方式

HookPrompt 不会替代模型执行任务。它做的是在任务开始前把意图、边界、输出格式和验证标准说清楚。

核心能力

输入过滤规则

快速开始

1. 本项目内验证

在项目根目录运行：

测试脚本会验证短输入过滤、诊断触发、正常需求优化和 Codex JSON 输入提取。

2. 复制到 Claude Code 项目

把 .claude 目录复制到目标项目根目录：

Windows PowerShell：

目标项目中的 .claude/settings.json 应使用 UserPromptSubmit：

3. 复制到 Codex 项目

把 .codex 目录复制到目标项目根目录：

Codex 入口会从标准输入 JSON 中提取 prompt 字段，并通过 hookSpecificOutput.additionalContext 返回模型可见上下文。

全局安装

Claude Code

Windows PowerShell：

macOS / Linux：

然后在 ~/.claude/settings.json 中配置绝对路径更稳：

Codex

把 .codex/hooks/user-prompt-submit.js 复制到你的 Codex hook 目录，并在对应 hooks.json 中配置 UserPromptSubmit。项目级使用时，直接保留本仓库的 .codex/hooks.json 即可。

配置选项

完整体验与紧凑模式

默认模式会注入完整 meta 模板，保证用户可见回复包含完整三段式：

- 原始输入
- 优化后的理解
- 优化后的完整提示词

只有在明确需要更短后台上下文时，才设置：

自定义优化规则

编辑 .claude/prompt-optimizer-meta.md 可以调整：

- 任务角色判断方式
- 目标、范围和验收标准字段
- 输出格式
- 高风险操作的暂停条件
- 示例和自查清单

文件结构

测试

运行：

建议在修改 Hook 逻辑、过滤规则、Codex 适配或提示词模板后都运行一次。

测试通过只代表本地脚本行为符合预期；真实工具内是否展示优化结果，还需要在 Claude Code 或 Codex 会话中实际触发一次确认。

故障排查

Hook 没有执行

优先检查：

1. settings.json 的键名必须是 UserPromptSubmit，不是 user-prompt-submit。
2. hooks 值必须是数组结构。
3. 命令里必须包含 type: "command"。
4. 本机必须能运行 node -v。
5. 修改配置后需要重启 Claude Code 或重新打开相关会话。

Windows 找不到脚本

Windows 下建议使用绝对路径，并使用 / 或转义后的 \\：

返回 {} 不代表安装失败

HookPrompt 会主动跳过“测试”“测试输入”“好的”等没有明确任务含义的短文本，此时返回 {}…