# prompt-optimizer

**Repository Path**: eferaw/prompt-optimizer

## Basic Information

- **Project Name**: prompt-optimizer
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-24
- **Last Updated**: 2026-08-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# PromptOrb

**轻量常驻 Prompt 优化器 & Claude Code 启动器** · Windows 桌面工具

<p align="center">
  <img src="assets/PromptOrb.png" width="120" alt="PromptOrb 图标" />
</p>

PromptOrb 是一个仅支持 Windows 的常驻后台工具，提供 **Prompt 优化** 和 **Claude Code 快速启动** 两大核心功能。它使用 C++20、原生 Win32 API、WinHTTP 和 Windows DPAPI，不依赖任何第三方运行环境或动态库。

---

## 目录

- [功能一览](#功能一览)
- [截图](#截图)
- [项目架构](#项目架构)
- [快速开始](#快速开始)
- [构建指南](#构建指南)
- [配置参考](#配置参考)
- [安全模型](#安全模型)
- [API 服务商](#api-服务商)
- [使用说明](#使用说明)
- [测试](#测试)
- [开发指南](#开发指南)
- [发布检查清单](#发布检查清单)
- [路线图](#路线图)
- [许可](#许可)

---

## 功能一览

### 🖱️ 桌面宠物与系统托盘

| 功能 | 说明 |
|---|---|
| 动态 GIF 桌宠 | 置顶透明窗口，逐帧播放 GIF 动画（自研 GIF/LZW 解码，不依赖系统图像编解码器） |
| Claude Code 状态联动 | 轮询 `~/.claude/projects/**` 会话转录：无 Claude Code 进程→待机1.gif；Claude Code 打开等待输入→待机3.gif；思考→思考.gif；执行→执行.gif；完成→完成.gif（约 15 秒庆祝后回待机；回看最近状态事件，跳过辅助事件，`end_turn` 被辅助事件覆盖也能正确识别） |
| 多窗口优先级 | 多个 Claude Code 窗口时：完成 > 执行 > 思考 > 待机 |
| 交互 | 可拖动、边缘吸附、位置记忆；滚轮缩放 40–200%（步进 25%）；设置窗口「常规」页有桌宠大小滑条；双击打开优化器、右键菜单；透明像素点击穿透 |
| 自定义 GIF | 设置窗口「常规」页可为 5 个状态（待机1/待机2/思考/执行/完成）分别指定 GIF 文件，留空使用内置动画；保存后立即生效（存入 `settings.ini` 的 `[PetGifs]` 段） |
| 置顶守卫 | 每秒自检 + 看门狗强制重新置顶——全屏应用（如照片查看器）把桌宠压到 Z 序底层后 1 秒内自动恢复 |
| 多显示器支持 | 跟随所在显示器 DPI 缩放、位置记忆（重启后恢复）；位置在屏幕外时自动移回主屏 |
| 降级路径 | GIF 资源缺失时回退为旧版 42×42 悬浮球并记录错误 |
| 系统托盘图标 | Explorer 崩溃后自动重建、右键菜单 |
| 全局快捷键 | `Ctrl+Alt+P` 打开优化器 · `Ctrl+Alt+C` 启动 Claude Code |

### ✨ Prompt 优化

| 功能 | 说明 |
|---|---|
| 输入/输出编辑框 | 原生 Win32 编辑框，自适应大小 |
| 长度比例控制 | 0.25× ~ 3.00× 滑条调节 |
| 有效字符统计 | 不计空格、换行、制表符 |
| ±5% 容差 | 输出在目标范围内即视为达标 |
| 快速模式（默认） | 单次请求完成优化 |
| 严格长度修正（可选） | 结果不满足目标时，自动执行一次修正请求 |
| 停止按钮 | 设置取消标记，当前网络阶段结束后响应 |
| 复制结果 | 一键复制优化后的 Prompt |

### 🚀 Claude Code 启动

| 功能 | 说明 |
|---|---|
| 智能目录识别 | 自动检测前台资源管理器窗口的当前目录，支持 Windows 11 多标签页——跟随当前激活选项卡（点击选项卡后约 0.5 秒内记录） |
| 选择项目启动 | 弹出文件夹选择对话框 |
| 最近项目 | 自动记录最近 10 个项目目录，去重 |
| 自定义命令 | 可配置可执行文件名称和启动参数 |
| 预设 Effort 等级 | 启动时自动附加 `--effort <等级>`（low/medium/high/xhigh/max） |
| Windows Terminal | 通过 `CreateProcessW` 启动 `wt.exe`，始终可见终端窗口 |

### 👁️ 视觉 MCP 服务

| 功能 | 说明 |
|---|---|
| `analyze_image` 工具 | 为 Claude Code 提供外置视觉能力：图片路径 → 视觉模型描述 → 文本回传上下文 |
| 一键注册/移除 | 设置窗口中一键 `claude mcp add/remove`，user 级注册、全局可用 |
| 服务总开关 | 关闭时 MCP 工具直接返回「服务已禁用」 |
| 自动路径修复 | 检测到注册路径与当前 EXE 不一致时自动重注册 |
| 密钥安全 | 视觉 API Key 仍走 DPAPI 加密存储，不写入 `~/.claude.json` |
| 独立密钥 | 视觉 MCP 可配置独立的 Base URL 与 API Key，与提示词优化服务商解耦；留空则回退使用所选服务商的配置 |

### ⚙️ 设置与管理

| 功能 | 说明 |
|---|---|
| 多服务商支持 | OpenRouter、硅基流动、DeepSeek、自定义 OpenAI 兼容 API |
| API Key 加密 | Windows DPAPI `CryptProtectData` 加密后存储，配置文件无明文密钥 |
| 开机启动 | 可选当前用户开机自启，自动跟踪 EXE 路径变更 |
| 错误日志 | `error.log` 带时间戳的错误记录 |

---

## 截图

> TODO: 添加悬浮球、优化窗口、设置窗口的截图

| 悬浮球 | Prompt 优化窗口 | 设置窗口 |
|---|---|---|
| ![](assets/PromptOrb.png) | — | — |

---

## 项目架构

```
PromptOrb.exe
├─ app.cpp / app.h            ← 主应用：桌宠/悬浮球、系统托盘、窗口管理、UI 交互
│   ├─ 桌宠窗口 (BallProc，ULW 逐像素透明)
│   ├─ 优化器窗口 (OptimizerProc)
│   └─ 设置窗口 (SettingsProc)
├─ pet_gif.cpp / pet_gif.h    ← GIF 动画引擎：帧合成、缩放、透明度渲染（纯 C++）
├─ gif_meta.cpp / gif_meta.h  ← 自研 GIF89a 结构解析 + LZW 解码（可单测）
├─ claude_monitor.cpp/.h      ← Claude Code 会话转录扫描 → 宠物状态（可单测）
├─ config.cpp / config.h      ← 配置管理、INI 读写、DPAPI 加解密、开机启动
├─ api_client.cpp / api.h    ← LLM API 调用（WinHTTP + OpenAI Chat Completions）
├─ prompt_utils.cpp / .h    ← 文本工具：字符统计、JSON 转义/解析、UTF-8、base64
├─ claude_launcher.cpp / .h  ← Claude Code 启动：前台目录识别、WT 启动
├─ mcp_protocol.cpp / .h    ← MCP JSON-RPC 2.0 纯协议层（可单测）
├─ mcp_server.cpp / .h      ← stdio MCP 服务循环（`--mcp` 入口，analyze_image 工具）
├─ mcp_registration.cpp/.h  ← Claude Code MCP 注册/检测/移除（claude CLI + 配置解析）
├─ main.cpp                   ← 入口点：wWinMain → App::Run
├─ resource.h / PromptOrb.rc  ← 图标资源与清单
├─ CMakeLists.txt             ← CMake 构建配置
├─ assets/                    ← 图标资源
├─ tests/                     ← 单元测试
└─ docs/                      ← 验收文档
```

### 数据流：Prompt 优化

```
用户输入 Prompt
     ↓
长度目标计算 (CalculateLengthTarget)
     ↓
系统 Prompt 组装 + 用户 Prompt
     ↓
WinHTTP POST → 服务商 Chat Completions API
     ↓
解析响应 (ParseAssistantContent)
     ↓
有效字符统计 (CountEffectiveCharacters)
     ↓
是否在目标范围内？
├─ 是 → 显示结果
└─ 否 → (可选) 发送修正请求 → 显示结果
```

### 数据流：Claude Code 启动

```
检测前台窗口
     ↓
遍历 ShellWindows → 匹配 HWND
     ↓
Windows 11 多标签 → 优先活跃标签
     ↓
URL → 文件系统路径
     ↓
CreateProcessW("wt.exe -d <目录> cmd /k claude <参数>")
```

---

## 快速开始

### 先决条件

- Windows 10 或 Windows 11
- [Windows Terminal](https://apps.microsoft.com/detail/9n0dx20hk701)（推荐，Claude Code 启动需要）
- [Claude Code](https://docs.anthropic.com/en/docs/claude-code)（可选，用于启动功能）
- 任一 LLM API 服务商的 API Key

### 下载与运行

1. 从 [Releases](https://github.com/your/repo/releases) 下载最新 `PromptOrb.exe`
2. 双击运行，图标出现在系统托盘
3. 右键托盘图标 → 「设置」
4. 选择服务商，填写 API Key 和模型
5. 填写默认项目目录和 Claude 参数（可选）
6. 保存，开始使用

### 首次使用

1. **打开优化器**：双击悬浮球，或按 `Ctrl+Alt+P`，或托盘右键 → 「Prompt 优化」
2. **输入 Prompt**：在输入框中粘贴或输入需要优化的文本
3. **设置比例**：拖动滑条调节输出长度比例（0.25× ~ 3.00×）
4. **选择严格修正**（可选）：勾选「严格长度修正」以获得更精确的长度控制
5. **点击优化**：等待 API 返回结果
6. **复制结果**：点击「复制结果」使用优化后的 Prompt

---

## 构建指南

### 环境要求

- Visual Studio 2022（含「使用 C++ 的桌面开发」工作负载）
- CMake 组件（VS2022 安装时勾选）
- Windows SDK（VS2022 自带）

### 构建步骤

```powershell
# 1. 配置 CMake（仅首次）
cmake -S . -B build -G "Visual Studio 17 2022" -A x64

# 2. 编译 Release
cmake --build build --config Release

# 3. 运行单元测试
ctest --test-dir build -C Release --output-on-failure

# 4. 安装到 dist/
cmake --install build --prefix dist --config Release
```

输出程序：`build/Release/PromptOrb.exe`

> **提示**：也可以在 VS2022 中选择「打开本地文件夹」并打开项目根目录，IDE 会自动识别 `CMakeLists.txt`。

### 构建配置说明

CMakeLists.txt 的关键配置：

| 配置项 | 值 | 说明 |
|---|---|---|
| C++ 标准 | C++20 | `CMAKE_CXX_STANDARD` |
| 运行时库 | 静态链接 | `/MT`（Release）· `/MTd`（Debug） |
| 编译器标记 | `/W4 /permissive- /utf-8 /EHsc` | 严格警告、标准合规、UTF-8 源、C++ EH |
| 链接选项 | `/MANIFEST:NO` | 使用自定义 manifest |
| 依赖库 | `winhttp crypt32 comctl32 shell32 shlwapi ole32 advapi32` | 均为 Windows 系统 DLL |

---

## 配置参考

配置文件存储在：`%LOCALAPPDATA%\PromptOrb\settings.ini`

### settings.ini 完整字段

```ini
[General]
StartWithWindows=1          ; 是否开机启动 (0/1)
ShowFloatingBall=1          ; 是否显示悬浮球 (0/1)

[FloatingBall]
X=1800                      ; 悬浮球/桌宠 X 坐标（-1 为居中）
Y=500                       ; 悬浮球/桌宠 Y 坐标（-1 为居中）
Size=42                     ; 旧版悬浮球大小 (32~96，桌宠模式下忽略)
Opacity=220                 ; 桌宠透明度 (80~255)
PetScale=100                ; 桌宠缩放百分比 (50~200，滚轮调节)

[PromptOptimizer]
Provider=OpenRouter         ; 当前服务商 (OpenRouter/SiliconFlow/DeepSeek/Custom)
DefaultRatio=1.20           ; 默认输出比例 (0.25~3.00)
MinimumRatio=0.25           ; 最小比例
MaximumRatio=3.00           ; 最大比例
LengthTolerance=0.05        ; 长度容差 (±5%)
StrictLengthCorrection=0    ; 严格长度修正 (0=快速/1=严格)

[ClaudeCode]
Executable=claude           ; Claude Code 可执行文件名
Effort=medium               ; 预设 Effort 等级 (low/medium/high/xhigh/max)
DefaultProject=D:\Projects  ; 默认项目目录
Arguments=--dangerously-skip-permissions  ; 启动参数（若已含 --effort 则优先）
Terminal=WindowsTerminal    ; 终端类型（固定值）

[Provider.OpenRouter]
BaseUrl=https://openrouter.ai/api/v1
Model=openai/gpt-4o-mini
EncryptedKey=<DPAPI 加密后的 Base64>

[Provider.SiliconFlow]
BaseUrl=https://api.siliconflow.cn/v1
Model=deepseek-ai/DeepSeek-V3
EncryptedKey=<DPAPI 加密后的 Base64>

[Provider.DeepSeek]
BaseUrl=https://api.deepseek.com
Model=deepseek-v4-flash
EncryptedKey=<DPAPI 加密后的 Base64>

[Provider.Custom]
BaseUrl=
Model=
EncryptedKey=

[VisionModel]
Provider=OpenRouter           ; 视觉模型服务商（可复用其 BaseUrl/API Key，也可独立配置）
BaseUrl=                      ; 视觉专用 API 地址（空则使用所选服务商的 BaseUrl）
EncryptedKey=                 ; 视觉专用 API Key（DPAPI 加密，空则使用所选服务商的密钥）
Model=openai/gpt-4o           ; 视觉模型名（空则按服务商使用默认值）
Enabled=0                     ; 视觉 MCP 服务总开关
McpName=promptorb-vision      ; 注册到 Claude Code 的服务名
```

### 其他文件

| 文件 | 路径 | 说明 |
|---|---|---|
| `settings.ini` | `%LOCALAPPDATA%\PromptOrb\` | 主配置文件（UTF-16LE BOM） |
| `recent_projects.txt` | `%LOCALAPPDATA%\PromptOrb\` | 最近项目列表（最多 10 条） |
| `error.log` | `%LOCALAPPDATA%\PromptOrb\` | 错误日志（带时间戳） |
| `explorer_debug.log` | `%LOCALAPPDATA%\PromptOrb\` | 资源管理器目录识别诊断（启动探测、激活选项卡记录） |

---

## 安全模型

### API Key 加密

PromptOrb 使用 Windows DPAPI（Data Protection API）保护 API Key：

```
用户填写 API Key（明文）
     ↓
CryptProtectData()          ← 加密，绑定到当前 Windows 用户 + 本机
     ↓
Base64 编码
     ↓
写入 settings.ini（密文）

读取时逆向：
     Base64 解码 → CryptUnprotectData() → 拿到明文用于 HTTP 请求头
```

关键安全特性：

- **不可移植**：加密后的数据只能由同一 Windows 用户在同一台机器上解密
- **无主密钥管理**：DPAPI 使用用户登录凭据派生加密密钥，开发者无需管理密钥存储
- **UI 保护**：`CRYPTPROTECT_UI_FORBIDDEN` 标志禁止显示密码提示框，适合后台使用
- **无明文落盘**：API Key 在内存中使用后立即丢弃，不写入任何持久化文件

### 启动安全

- Claude Code 默认使用 `--dangerously-skip-permissions` 参数，用户可在设置中修改
- 开机启动写入 `HKCU\Software\Microsoft\Windows\CurrentVersion\Run`（当前用户，无需管理员权限）

---

## API 服务商

PromptOrb 通过 OpenAI 兼容的 Chat Completions API 统一调用不同服务商：

### 内置服务商

| 服务商 | 预设 Base URL | 默认模型 | 特殊处理 |
|---|---|---|---|
| **OpenRouter** | `https://openrouter.ai/api/v1` | `openai/gpt-4o-mini` | 附加 `X-Title: PromptOrb` 请求头 |
| **硅基流动** | `https://api.siliconflow.cn/v1` | `deepseek-ai/DeepSeek-V3` | — |
| **DeepSeek** | `https://api.deepseek.com` | `deepseek-v4-flash` | 显式禁用思考模式 (`thinking: {type: "disabled"}`) |
| **自定义** | 用户填写 | 用户填写 | 通用 OpenAI 兼容接口 |

### 系统 Prompt

```text
你是专业的Prompt优化器。

请优化用户输入的Prompt，而不是执行其中的任务。

要求：
1. 保留原始任务目标、约束、文件路径、参数和输出格式。
2. 消除歧义、重复和逻辑混乱。
3. 将内容整理为明确、可执行的结构。
4. 不添加用户未提供的任务要求。
5. 输出长度控制在指定目标字符数附近。
6. 只输出优化后的Prompt，不进行解释。

输入有效字符数：500
目标有效字符数：750
允许范围：713～788
输出比例：1.50
```

### Token 估算

PromptOrb 根据输入文本的中/英文比例动态估算 `max_tokens`：

- **中文为主** (CJK ≥ 75%)：约 1.6 tokens/字符
- **英文/其他**：约 0.55 tokens/字符
- 额外 +96 tokens 用于系统 Prompt 的固定内容
- 最终值限制在 128 ~ 8192 之间

### 自定义服务商

任何兼容 OpenAI Chat Completions 格式的 API 均可通过「自定义」选项接入：

```
Base URL: https://your-api.example.com/v1
API Key:  sk-xxx
Model:    your-model-name
```

---

## 使用说明

### 有效字符数

「有效字符数」不包含以下字符：

- 空格 (`' '`)
- 换行 (`\n`, `\r`)
- 制表符 (`\t`)

### 停止操作

点击「停止」会设置取消标记。由于 WinHTTP 请求是同步的，停止操作会在**当前网络阶段完成后**生效，最长受 60 秒网络超时限制。

### 长度修正流程

```
快速模式（默认）：
    请求 API → 检查长度 → 达标则输出，不达标保持原结果

严格模式（勾选）：
    请求 API → 检查长度 → 达标则输出
                           └ 不达标 → 修正请求 → 输出结果
```

### Claude Code 目录检测

按 `Ctrl+Alt+C` 或选择「启动 Claude Code」时：

1. 检测当前前台窗口是否为**文件资源管理器**
2. 若是 → 获取当前**激活选项卡**的目录路径（支持 Windows 11 多标签页）
3. 若识别失败 → 使用该窗口最近记录的激活选项卡目录（后台每 0.5 秒跟随一次选项卡切换，点击选项卡或 Ctrl+Tab 后自动更新）
4. 若仍无有效目录 → 使用设置的默认项目目录
5. 若默认目录为空 → 弹出项目选择对话框

**多标签激活选项卡识别**：程序每 0.5 秒探测前台资源管理器窗口并记录激活选项卡目录（按窗口独立记录）。识别综合两个独立信号——窗口标题栏前缀与各选项卡的名称/完整路径比对（标题栏始终以激活选项卡名称开头，其后为「- 文件资源管理器」等系统后缀），以及各选项卡视图窗口的可见性。每次识别与记录均写入 `%LOCALAPPDATA%\PromptOrb\explorer_debug.log`，便于排查「识别到错误选项卡」的情况。

启动时自动附加预设的 Effort 等级（设置 → Effort 等级，默认 `medium`），例如 `claude --dangerously-skip-permissions --effort high`。若「命令参数」中已手动包含 `--effort`，则以手动填写的为准，不再附加。

### 视觉 MCP 服务

为 Claude Code 提供外置图片识别能力（`analyze_image` 工具）：

1. 打开设置 → 视觉 MCP 页：选择视觉模型服务商与模型（DeepSeek 不提供视觉模型，需使用 OpenRouter / 硅基流动 / 自定义）。默认复用该服务商的 Base URL 与 API Key；如需独立凭据，直接填写页内「Base URL」「API Key」（留空则继续复用服务商配置）；
2. 勾选「启用视觉 MCP 服务」→ 保存（若已启用但未注册会提示一键注册）；
3. 注册成功后需重启 Claude Code 会话生效（`claude --continue` 可恢复上下文）；
4. 会话中直接问图片内容即可，例如「描述这张图片：assets/screenshot.png」。

MCP 模式入口为 `PromptOrb.exe --mcp`：由 Claude Code 按需拉起，不创建任何窗口，stdio 关闭即退出，可多会话并存。视觉 API Key 由 MCP 进程自行从 `settings.ini` 解密读取，不会写入 `~/.claude.json`。

---

## 测试

### 运行测试

```powershell
cmake --build build --config Release
ctest --test-dir build -C Release --output-on-failure
```

### 测试覆盖

单元测试覆盖以下功能（`tests/prompt_utils_tests.cpp`）：

| 测试项 | 验证内容 |
|---|---|
| `CountEffectiveCharacters` | 中英文混合 + 空白字符过滤 |
| `CalculateLengthTarget` | 目标长度、±5% 容差边界 |
| `IsWithinTarget` | 范围内/外判断 |
| `EscapeJson` | 特殊字符转义 |
| `ParseAssistantContent` | Chat Completions 响应解析 |
| UTF-8 往返转换 | Wide ↔ UTF-8 互转一致性 |

---

## 开发指南

### 编码规范

- C++20 标准
- 命名空间 `promptorb`
- Windows 类型使用 `Windows.h` 前缀（`DWORD`, `HWND` 等）
- 字符串使用 `std::wstring`（UTF-16LE）
- 与 API 交互时使用 UTF-8（`WideToUtf8` / `Utf8ToWide`）
- 所有 `windows.h` 相关定义使用 `WIN32_LEAN_AND_MEAN` 和 `NOMINMAX`

### 项目约定

- `app.cpp` 负责所有 UI 交互，保持窗口过程清晰
- `api_client.cpp` 只处理 HTTP 请求与响应解析
- `config.cpp` 封装所有配置 I/O 和加密逻辑
- 避免引入第三方依赖：使用 Win32 API 和 C++ 标准库完成所有功能

### 调试技巧

- 使用 `OutputDebugStringW` 输出调试信息
- 设置 `DPI_AWARENESS_CONTEXT_PER_MONITOR_AWARE_V2` 支持高 DPI
- 悬浮球使用 `WS_EX_LAYERED | WS_EX_TRANSPARENT | WS_EX_TOPMOST` 样式
- 全局快捷键通过 `RegisterHotKey` 注册，无需消息循环改造

---

## 发布检查清单

在发布新版本前，完成以下验证：

- [ ] 三个服务商分别使用有效 API Key 测试优化功能
- [ ] 用明显偏短/偏长的模型结果确认长度修正提示
- [ ] 多显示器间拖动悬浮球并重启，确认吸附和位置恢复
- [ ] 托盘菜单、全局快捷键、Explorer 重启后托盘恢复
- [ ] 带空格和中文的项目路径启动 Claude Code
- [ ] 最近项目去重验证
- [ ] 启用/关闭开机启动，检查注册表值
- [ ] `dumpbin /dependents` 确认无第三方 DLL 依赖
- [ ] 单元测试全部通过

---

## 路线图

### v1.0 ✅ （当前版本）

- [x] 悬浮球与系统托盘
- [x] Prompt 输入/输出与长度比例控制
- [x] 多服务商 API 配置与 DPAPI 密钥加密
- [x] Claude Code 一键启动与最近项目
- [x] 全局快捷键

### v1.1（规划中）

- [ ] 流式输出（打字机效果）
- [ ] 在线模型列表获取
- [ ] 多套 Prompt 模板（精简/标准/扩展/Codex GOAL）
- [ ] 剪贴板快速优化
- [ ] API 请求费用和 Token 统计

### v1.2 ✅（当前版本）

- [x] 视觉 MCP 服务（`analyze_image` 工具 + 一键注册/启停 + 自动路径修复）

---

## 许可

> TODO: 添加许可证信息

---

## 相关文档

- [设计方案](设计方案.md) — 完整的技术方案与设计文档
- [v1.0 验收矩阵](docs/V1_ACCEPTANCE.md) — 功能验收清单与验证方式