openpe

openPE

中文 | English

openPE 是一个本地运行的提示词增强工具。它支持 Codex CLI、Claude Code、Devin CLI 和 Windsurf。

安装 hook 后，你可以直接在客户端对话框输入：

pe 帮我为这个接口补充测试

openPE 会在消息发送前拦截原始内容，读取可用的会话历史，生成更明确的任务描述，并把结果复制到剪贴板供你检查和修改。

默认情况下，原始 pe 消息不会发送给模型。Codex、Claude Code 和 Devin 也支持注入模式，可让客户端直接使用增强结果。

主要特点

• 保留现有工具：继续使用 Codex、Claude Code、Devin 或 Windsurf，只增加发送前的提示词增强。
• 本地配置：请求直接发往你配置的模型 API，不经过 openPE 的第三方服务。
• 会话上下文：在客户端允许的情况下读取最近对话，让“继续上面的方案”这类请求更完整。
• 先检查再发送：默认阻断原始消息并复制增强结果，由你确认后再提交。
• 明确提示风险：增强结果出现上下文外数字、未决定的不可逆动作或语言偏移时，会在交付信息中显示提醒。

快速开始

需要 Go 1.25.12 或更高版本。

1. 安装

go install github.com/AoManoh/openpe/cmd/openpe@latest

日常 hook 只需要 openpe。openpe-server 仅用于 HTTP 自动化或实验性 IDE 按钮：

go install github.com/AoManoh/openpe/cmd/openpe-server@latest

开发者也可以克隆仓库后在仓库内执行 go install ./cmd/openpe 本地构建。这种构建的 openpe --version 显示 Go 工具链根据提交自动生成的开发版本号（形如 v0.0.0-20260826xxxxxx-提交号），而不是发布版本号，便于区分正式版和开发版。

确认安装与版本：

openpe -h
openpe --version

升级到最新发布版本：

openpe update

该命令向 Go 模块下载服务（遵循你已配置的 GOPROXY 镜像）查询最新版本，重新安装 openpe 和 openpe-server，完成后输出升级到的版本号；openpe update --check 只查询提示、不安装。存在新版本时，pe 的反馈信息末尾还会附一条升级提示——版本检查在后台进行、最多每 24 小时一次，不会拖慢增强本身；设置 OPENPE_UPDATE_NOTICE=false 可关闭该提示和后台检查。各版本变化见 CHANGELOG.md。

如果提示 openpe：未找到命令，把 Go 的产物目录加入 PATH（zsh 用户改 ~/.zshrc）：

echo 'export PATH="$PATH:$(go env GOPATH)/bin"' >> ~/.bashrc
source ~/.bashrc
openpe -h

完整排查见 FAQ Q0。

2. 配置模型 API

openPE 使用 .env 配置文件。它是普通文本：每行填写一个 变量名=值，以 # 开头的行是注释。Hook 每次运行都会重新读取配置。建议统一保存到：

mkdir -p ~/.config/openpe

OpenAI-compatible API（默认）

cat > ~/.config/openpe/.env <<'EOF'
OPENPE_BASE_URL=https://your-openai-compatible-endpoint
OPENPE_API_KEY=replace-with-your-api-key
OPENPE_MODEL=your-model
EOF

支持 OpenAI、DashScope、火山引擎和提供 /v1/chat/completions 的自建网关。OPENPE_BASE_URL 没有默认值，请填写实际地址。

Anthropic Messages API

如果端点提供 /v1/messages，必须显式选择 Anthropic 协议：

cat > ~/.config/openpe/.env <<'EOF'
OPENPE_PROVIDER=anthropic
OPENPE_BASE_URL=https://your-anthropic-compatible-endpoint
OPENPE_API_KEY=replace-with-your-api-key
OPENPE_MODEL=your-model
EOF

如果 Anthropic 地址没有设置 OPENPE_PROVIDER=anthropic，openPE 会按默认 OpenAI 协议请求 /v1/chat/completions，通常会返回 HTTP 404。排查见 FAQ Q0.1。

验证配置：

OPENPE_ENV_FILE="$HOME/.config/openpe/.env" \
openpe enhance --prompt "帮我整理这个需求"

能正常返回增强后的提示词，就说明 API 地址、密钥、模型名和协议配置可用。

3. 安装客户端 hook

选择你使用的客户端，可以安装一个或多个：

openpe codex hook install
openpe claude hook install
openpe devin hook install
openpe windsurf hook install

安装后：

• Codex：在 TUI 中执行 /hooks，检查并信任 hook。
• Claude Code：重新启动 Claude Code。
• Devin：用 /hooks 确认 openPE 已加载。
• Windsurf：重新启动 IDE 或重新打开 workspace。

项目级安装、自定义配置路径和各客户端限制见 CLIENTS.md。

4. 使用

在客户端对话框输入以下任一种格式：

pe 帮我把这个测试改成 table-driven
pe:帮我把这个测试改成 table-driven
pe：帮我把这个测试改成 table-driven

每次都要重复叮嘱的固定要求（自查清单、写作规范、提交规范等），可以写成普通文本文件保存为 ~/.config/openpe/specs/<名字>.md——openPE 把这类文件称为「用户规范」，文件名就是引用名。在触发词后加 +<名字> 引用（可连写多个），openPE 会把文件内容原封不动附加在增强结果末尾，随剪贴板一起交付：

pe+三问 帮我完成如下任务xxx
pe+三问+write-style 给 server 写部署说明

引用的规范不存在、内容为空或超过大小上限时，openPE 会阻断本次增强并说明原因，不会悄悄忽略你点名的约束。创建示例见 FAQ Q10.1，完整规则见 CLIENTS.md 与 CONFIG.md。

默认流程：

1. openPE 拦截原始 pe 消息；
2. 调用模型生成增强提示词；
3. 把增强结果复制到剪贴板；
4. 你粘贴、检查、修改后再发送。

如果剪贴板不可用，可以直接读取最近一次结果：

openpe <client> hook last --prompt

<client> 可用 codex、claude、devin 或 windsurf。

触发后客户端会显示 openPE 的反馈，以 Codex 为例：

其余客户端的触发演示见 CLIENTS.md。

交付模式

Review 模式（默认）

原始 pe 消息不会发送给模型。增强结果进入剪贴板和本地缓存，由你确认后再发送。

这也是 Windsurf 唯一支持的 hook 交付方式。

注入模式

Codex、Claude Code 和 Devin 支持把增强结果作为附加上下文直接注入：

OPENPE_HOOK_INJECT=true

也可以只为某个客户端开启：

OPENPE_CODEX_INJECT=true
OPENPE_CLAUDE_INJECT=true
OPENPE_DEVIN_INJECT=true

注入模式会跳过人工检查。对包含数字、部署、删除、发布、支付或 push 等动作的任务，建议继续使用默认 review 模式。

常用配置

环境变量优先级：shell 环境变量 > OPENPE_ENV_FILE 指向的 dotenv > 当前目录 .env。

按使用结果选择参数

具体的修改前后对比、适用场景、副作用和验证方法见 CONFIG.md。可直接复制的完整模板见 .env.example。

会话历史和提醒

openPE 会根据客户端提供的能力读取最近对话：

• Codex：根据当前 prompt 和工作目录定位 session rollout。
• Claude Code：读取 hook 提供的 transcript_path。
• Devin：Linux 上优先识别当前 session；无法精确识别时使用保守的工作目录和时效判断。
• Windsurf：hook 协议没有可靠的会话历史绑定，因此默认不发送历史。

openPE 会明确告诉你本次是否带入历史。没有找到历史时，增强仍然可以成功，只是不包含前文。

增强结果出现以下情况时，交付信息会显示提醒：

• 原始输入和上下文中没有出现的数字；
• 你没有明确要求的 push、部署、删除、发布或支付动作；
• 输出语言与输入的主导语言明显不同，而且自动修正失败。

这些提醒不会修改或阻断增强结果。

HTTP 和裸 CLI

HTTP server 仅用于测试、自动化或实验性 IDE 集成，日常 hook 不需要运行它。

openpe-server

它只允许监听 127.0.0.1、::1 或 localhost。如果确实需要远程访问，请在外层使用 TLS 反向代理或隧道。

最小请求示例：

curl http://127.0.0.1:18980/v1/prompt-enhance \
  -H 'content-type: application/json' \
  -d '{"prompt":"帮我整理这个需求","client":"codex","mode":"agent"}'

裸 CLI：

openpe enhance --prompt "帮我检查这个 Go 项目的测试失败"
openpe enhance --json --prompt "优化这个需求描述"

完整 HTTP、CLI 和调试入口见 CLIENTS.md。

支持范围

详细安装选项、配置文件位置和客户端限制见 CLIENTS.md。

常见问题

优先查看 FAQ.md，其中包括：

• go install 成功但找不到 openpe；
• Anthropic 地址返回 HTTP 404；
• 为什么显示 Prompt blocked；
• 为什么没有带入会话历史；
• 剪贴板没有更新时如何取回增强结果；
• 为什么同一条 prompt 可能触发多个 Devin hook；
• 如何选择 agent 或 human 提示词风格。

工作原理

客户端输入
  -> hook / CLI / HTTP
  -> 客户端适配层
  -> 提示词增强核心
  -> OpenAI-compatible 或 Anthropic provider
  -> 增强结果
  -> 剪贴板 / 缓存 / 注入

项目边界：

• openPE 只在 prompt 进入客户端前做一次改写，不代理完整 agent 对话。
• openPE 不保存长期会话状态，只缓存每个客户端最近一次增强结果。
• Openace 是已废弃且默认关闭的可选上下文来源，不影响核心增强功能。
• IDE bundle patch 是独立实验能力，不替代正式 hook。

开发者接口、模块职责和增强契约见 CLIENTS.md。

文档

开发

go test ./...
go vet ./...
go build ./cmd/openpe ./cmd/openpe-server

提交改动前，请确保相关测试、构建和文档链接均通过检查。