📚 Prompt Enhancement - 代码项目专用提示词增强系统

当前生产版本: v1.2.2 ✅ | 开发版本: v1.2.3 (/pe 命令修复) | 最后更新: 2025-12-25

一个代码项目专用的智能增强系统，用 AI 和项目上下文来优化提示词，使其更清晰、更具体、更易执行。现已完成 28 个用户故事和 6 个完整 Epic，在 874 个测试中达到 100% 通过率。

---

📊 项目完成度

版本	状态	核心功能	测试	发布时间
v1.2.2	✅ 生产就绪	28个故事 + 6个Epic完成	874/874 ✅	2025-12-24
v1.2.1	✅ 完成	智能文件发现、符号索引、模板系统、AGENTS 生成	119/119 ✅	2025-12-16
v1.1.0	✅ 存档	基础 /pe 命令 + 自动项目检测	155/155 ✅	2025-12-10

---

🎯 核心功能完成度

核心功能（10天计划）：

• 🔍 智能文件发现 - 从模糊指令自动找到最相关的 5-10 个源文件（Day 1-3 ✅ 完成）

  • KeywordExtractor：中英文关键词提取
  • FileMatcher：精准文件匹配 + 语义映射
  • 18个测试，全部通过 ✅ | 关键词提取准确率 100% ✅

• 📋 符号索引 - 提取函数/类签名而非完整代码（Day 4-5 ✅ 完成）

  • PythonSymbolExtractor：AST 解析（函数/类/装饰器）
  • JavaScriptSymbolExtractor：正则符号提取
  • SymbolCache：智能双层缓存（内存+磁盘）
  • 34个测试，全部通过 ✅ | 缓存命中率 >95% ✅

• 📝 编码模板系统 - 5 种任务类型的结构化指导（Day 6-7 ✅ 完成）

  • CodingTemplate：5 个 YAML 模板（implement/fix/refactor/test/review）
  • TemplateTrigger：双语触发词匹配（中文+英文）
  • CodingTemplateManager：懒加载架构（0.17ms 初始化）
  • 38个测试，全部通过 ✅ | 性能提升 863x ✅

• 🏗️ AGENTS.md 自动生成 - 为新项目生成边界约束说明（Day 8-9 ✅ 完成）

  • 技术栈检测
  • 命令提取
  • 代码风格推断
  • 29个测试，全部通过 ✅ | 7语言支持，5000+行模板 ✅

• ⚡ 性能优化 - 冷启动 30s → 15s，缓存命中 10s → 5s（Phase 1-4 ✅ 完成）

  • Phase 5 并发优化计划中 📅

---

📌 已知问题和解决方案

1️⃣ /pe 命令菜单确认流程

GitHub Issue: #1 - Feature: /pe 命令菜单确认流程架构限制 状态: ✅ 已解决 (v1.2.3)

问题描述：v1.2.1 开发版中 /pe 命令无法自动执行脚本 根本原因：Claude Code Slash Command 机制只提供上下文，不自动执行 解决方案：使用 ! 前缀实现自动执行（v1.2.3）

• pe.md 使用 ! 前缀让 bash 在 Claude 处理前自动执行
• 脚本增强提示词并显示结果
• 用户从菜单中手动选择操作（使用、修改、重新增强或放弃）
• 用户掌控完整的执行权 ✅

相关文档：/pe 命令诊断和解决方案

---

2️⃣ API Key 环境变量配置

GitHub Issue: #2 - Bug Fix: API Key 环境变量配置问题 (已解决 v1.1.0+) 状态: ✅ 已解决

常见问题：

• .env 文件不存在导致脚本无法读取 API Key
• 环境变量未正确传递给子进程

解决方案：

# 1. 复制 .env 示例文件
cp .env.example .env

# 2. 编辑 .env 文件，填入您的 API Key
nano .env
# DEEPSEEK_API_KEY=sk-xxxxxxxxxxxxx
# OPENAI_API_KEY=sk-xxxxxxxxxxxxx

相关文档：快速开始指南 | 故障排除

---

3️⃣ 性能优化进展

GitHub Issue: #3 - Enhancement: 性能优化 - 冷启动时间优化 (v1.2.1 进行中) 状态: ✅ Phase 1-4 完成，Phase 5 计划中

性能基准：

场景	优化前	优化后	进度
冷启动	45秒	15秒	✅ Phase 1-4
缓存命中	10秒	2秒	✅ Phase 2
文件扫描	25秒	3秒	✅ Phase 1
模板生成	3秒	0.05秒	✅ Phase 3 (863x 提升)

相关文档：v1.2.1 产品需求文档

---

🐛 已解决的问题列表

✅ 完全解决：

• /pe 命令菜单确认流程 (v1.1.0+)
• API Key 配置问题 (v1.1.0+)
• 冷启动性能 (v1.2.1: 863x 提升)
• 文件扫描准确性 (v1.2.1: 100% 准确率)
• 缓存机制 (v1.2.1: >95% 命中率)

📖 更多信息：查看 GitHub Issues 列表

---

⚡ 使用 /pe 命令

当前开发版本使用

/pe 您的提示词

工作流：

1. 脚本增强您的提示词
2. 显示原始 vs 增强版本对比
3. 显示菜单：选择执行、修改、重新增强或放弃
4. 您从菜单中选择操作，脚本执行

菜单选项：

• 1️⃣ 使用增强版本 - 复制粘贴给我执行
• 2️⃣ 修改后使用 - 编辑后复制粘贴给我
• 3️⃣ 重新增强 - 输入新提示词重新增强
• 4️⃣ 放弃此结果 - 取消并重新组织需求

---

📂 项目结构

Prompt-Enhancement/
├── src/prompt_enhancement/        # v1.2.1 新增强引擎
│   ├── file_discoverer.py         # 智能文件发现模块（Day 1 ✅）
│   ├── enhancement/               # 增强引擎核心
│   └── ...
│
├── .claude/commands/              # Claude Code 集成
│   ├── pe.md                      # /pe 命令定义
│   └── scripts/enhance.py         # 增强脚本
│
├── docs/
│   ├── v1.2.1_PRD.md             # 产品需求文档
│   ├── v1.2.1_IMPLEMENTATION_PLAN.md
│   ├── v1.2.1_WORKFLOW_STATUS.md
│   ├── GITHUB_ISSUE_TEMPLATE.md  # /pe 命令问题诊断 ⭐
│   └── ...
│
├── enhanced_prompt_generator.py   # v1.1.0 增强模块
├── async_prompt_enhancer.py       # 异步处理
└── README.md                      # 本文件

---

🛠️ 技术栈

• 语言：Python 3.10+
• 构建：Pip
• AI 增强：DeepSeek API
• 项目框架：BMAD 平台（5个模块）
• 测试：pytest（18+ 测试套件）
• 版本控制：Git

---

📊 开发进度

阶段	计划	状态	测试	成就
Phase 1	智能文件发现	✅ 完成	18/18 ✅	关键词准确率 100%
Phase 2	符号索引	✅ 完成	34/34 ✅	缓存命中率 >95%
Phase 3	编码模板	✅ 完成	38/38 ✅	性能 863x 提升 ⚡
Phase 4	AGENTS.md 生成	✅ 完成	29/29 ✅	7语言支持，5000+行模板
Phase 5	性能优化	📅 计划中	-	-
总计		✅ 80% 完成	119/119 ✅

---

📖 文档导航

🚀 入门文档

• 快速开始：QUICK_START.md - 5 分钟快速上手
• 使用指南：USAGE_GUIDE.md - 详细功能说明
• 故障排除：docs/deploy/TROUBLESHOOTING.md - 常见问题解决

🔍 问题追踪

• 问题历史记录：ISSUE_HISTORY.md ⭐ 新增 - 5 个已解决问题的完整分析
• GitHub Issues：github.com/jodykwong/Prompt-Enhancement/issues - 实时问题追踪
• 已知问题诊断：docs/GITHUB_ISSUE_TEMPLATE.md

📋 开发文档

• v1.2.1 路线图：docs/v1.2.1_PRD.md - 产品需求
• 实现计划：docs/v1.2.1_IMPLEMENTATION_PLAN.md - 详细实现步骤
• 工作流状态：docs/v1.2.1_WORKFLOW_STATUS.md - 实时进度
• 架构设计：ARCHITECTURE.md - 系统架构

🧪 质量保证

• 测试指南：TESTING_GUIDE.md - 完整测试覆盖
• API 参考：API_REFERENCE.md - API 接口文档

---

🔧 安装和配置

环境要求

Python 3.10+
API Key: DeepSeek (https://platform.deepseek.com)

配置 .env

cp .env.example .env
# 编辑 .env，填入 DEEPSEEK_API_KEY

---

查看完整路线图 →

🚀 快速开始

📦 三种安装方式

方式 1：使用 pip（推荐）

pip install prompt-enhancement
prompt-enhance-install /path/to/your/project
prompt-enhance-setup

优点：Python 开发者标准方式，自动依赖管理

方式 2：使用 NPM

npm install -g @jodykwong/prompt-enhancement
prompt-enhance-install /path/to/your/project
prompt-enhance-setup

优点：Node.js 开发者友好，全局可用

方式 3：一键脚本（跨平台）

# Linux/macOS
bash cli/install.sh /path/to/your/project

# Windows PowerShell
.\cli\install.ps1 -ProjectPath "C:\path\to\project"

# 通用 Python
python3 cli/install.py /path/to/your/project

优点：无需额外依赖，完全跨平台

✅ 部署验证

已在 xlerobot 项目中验证部署成功：

# 验证命令
python3 cli/install.py /home/sunrise/xlerobot

# 结果
✓ pe.md 命令已安装（符号链接）
✓ enhance.py 脚本已复制
✓ 所有 Python 模块已部署
✓ .env 配置文件已创建

详细安装指南: docs/deploy/INSTALL.md | docs/deploy/QUICKSTART.md

---

🆕 在 Claude Code 中使用

安装完成后，在 Claude Code 中使用 /pe 命令：

/pe "您想增强的提示词"

工作流程（Display-Only 模式）：

1. Claude 调用增强脚本（等待 30-60 秒）
2. 显示原始和增强后的提示词对比
3. 命令结束 - 不自动执行任何任务
4. 您审查结果，手动复制并执行

示例：

/pe 优化数据库查询性能

→ Claude 会：
  1. 等待 30-60 秒 API 返回
  2. 显示增强后的详细步骤
  3. 命令结束，不执行任何操作

→ 您：
  4. 审查增强结果
  5. 如满意，复制并重新输入给 Claude
  6. Claude 按增强后的指令执行优化

优点（Display-Only 模式）：

• ✅ 完全掌控执行权
• ✅ 符合 Auggle CLI 设计模式
• ✅ 避免意外自动执行
• ✅ 透明的增强过程

详见 USAGE_GUIDE.md

---

本地开发和集成

1. 安装依赖

pip install -r requirements.txt

2. 配置 API 密钥

复制 .env.example 为 .env 并填入您的 API 密钥：

cp .env.example .env
# 编辑 .env 文件，填入 DEEPSEEK_API_KEY 和 OPENAI_API_KEY

3. 验证项目

# 验证 P0.5 (增强器集成)
python3 verify_p0_5.py

# 运行所有单元测试
python3 tests/test_enhanced_prompt_generator.py
python3 tests/test_enhanced_prompt_generator_extended.py

4. 使用核心功能

# 收集项目上下文
from context_collector import collect_project_context

context = collect_project_context("/path/to/project")
print(context["summary"])

# 增强提示词
from enhanced_prompt_generator import enhance_prompt_with_context
import asyncio

async def main():
    result = await enhance_prompt_with_context(
        "修复 bug",
        project_path="/path/to/project"
    )
    print(result["enhanced"])

asyncio.run(main())

测试用例

MVP 包含以下测试用例：

1. 简单模糊指令："优化代码"
2. 简单模糊指令："修复bug"
3. 中等复杂度："添加用户登录功能"
4. 具体指令："重构数据库查询模块，提高性能"
5. 中英文混合："为 API 接口添加 rate limiting 功能"

评估标准

增强质量从以下维度评估：

• ✓ 是否包含具体步骤
• ✓ 是否包含验证标准
• ✓ 是否添加了上下文信息
• ✓ 结构是否清晰
• ✓ 长度是否适中

输出示例

原始提示词： "修复bug"

增强后：

修复代码中的缺陷。请按以下步骤进行：

1. 问题定位：
   - 收集错误日志和堆栈跟踪信息
   - 复现问题，确定触发条件
   - 识别出现问题的具体代码位置

2. 原因分析：
   - 审查相关代码逻辑
   - 检查边界条件和异常情况处理
   - 分析是否存在逻辑错误或资源泄漏

3. 实施修复：
   - 编写修复代码
   - 确保修复不引入新问题
   - 添加必要的错误处理和日志

4. 测试验证：
   - 编写或更新单元测试
   - 验证修复后问题不再出现
   - 进行回归测试确保其他功能正常

5. 代码审查：提交代码前进行自查，确保符合编码规范

验证标准：bug 完全修复，相关测试通过，无新增问题。

## ⚠️ 注意事项

### API 密钥安全
- 严禁将 API 密钥硬编码到代码中
- 不要将 `.env` 文件提交到版本控制
- 使用环境变量或安全的配置管理方案

### 支持的 API 提供商
- **DeepSeek API** (推荐) - https://platform.deepseek.com
- **OpenAI API** - https://platform.openai.com

## 📄 许可证

MIT License - 本项目采用 MIT 开源许可证

Prompt Enhancement v1.2.2 是一个生产级的智能提示词增强系统，完全可用于商业和个人项目。

---

**最后更新**: 2025-12-25
**项目主页**: https://github.com/jodykwong/Prompt-Enhancement
**Bug 报告**: https://github.com/jodykwong/Prompt-Enhancement/issues
**问题历史**: [ISSUE_HISTORY.md](ISSUE_HISTORY.md)