Compiler

# 提示编译器   <p align="center"> <img src="docs/images/cover.jpg" alt="提示编译器封面" width="100%"> </p> **提示编译器** 将模糊的请求转化为结构化的提示、执行计划和策略检查的工作流程 — 这样您就可以在几秒钟内从想法转变为安全、可用的 AI 输出。 它还附带了一个 **PR 安全/合并就绪层**：粘贴 AI 代理的 PR 并获得明确的裁决 — **合并、暂停、拆分或变基** — 在您合并之前。 现在就试试 [prcompiler.com](https://prcompiler.com) — 或打开 [PR 安全](https://prcompiler.com/pr-safety) ([指南](docs/pr-safety.md)) · [VS Code 扩展](integrations/vscode-extension) · [GitHub 工件](docs/pattern-library.md) --- ## 它能做什么 **编译请求。** 输入任何请求 — 功能想法、错误报告、研究问题 — 提示编译器会生成： - **系统提示** — 人物、角色、约束、输出格式 - **用户提示** — 结构化任务定义 - **执行计划** — 协调任务的逐步分解 - **扩展提示** — 准备粘贴到任何 LLM，具有领域感知的 **关键考虑因素** 和识别场景的果断后续问题 - **策略层** — 风险级别、允许的工具、执行模式、数据敏感性 - **就绪检查** — 自我描述的交通灯，告诉您编译的提示是否准备好运行，遵守编译的安全策略 核心管道是 **离线和确定性的** — 编译不需要 API 密钥和网络 — 并通过 1700+ 测试套件和 QA 回归门锁定。 **检查拉取请求。** 将 AI 代理 PR 的标题、描述和更改的文件粘贴到 **PR 安全** 并获得确定性的合并就绪报告： - **裁决** — `合并` · `暂停` · `拆分` · `变基` - **信号** — 风险区域、测试覆盖率、分支新鲜度、范围匹配 - **建议** — 以及可以直接粘贴到 PR 的 GitHub 就绪 Markdown 导出 它完全离线运行（无需 GitHub API，无 AI 调用，无登录）并且永远不会阻止合并 — 它为人工干预提供建议。 --- ## 关键功能 ### 核心提示编译器 引擎分析您的意图并生成核心输出层： - **系统提示**：目标 AI 的角色、角色、约束和输出格式规则 - **用户提示**：从您的输入派生的结构化任务定义 - **执行计划**：根据您的请求分解的步骤 — 协调任务（“执行 X 然后 Y”）被分成有序步骤 - **扩展提示**：一个组合提示，准备粘贴到基于聊天的 LLM 中，丰富了识别场景的 **关键考虑因素** （SQL 性能、文件上传、身份验证流程、时区、浏览器下载、支付等）和 **果断后续问题** competent 工程师会问 - **就绪检查**：一个交通灯样式的横幅，指示编译的提示是否准备好运行以及如何使其更安全 — 它遵守编译的安全策略，因此不会放行风险请求 在 UI 中切换到输出选项卡以检查每个层，并通过单击复制任何结果。 <p align="center"> <img src="docs/images/comp1.PNG" alt="提示编译器 - 主视图" width="100%"> </p> --- ### 探索模式 — 自适应纬度调度 大多数提示工具只会收紧提示。提示编译器还调度 **下游代理应该获得多少纬度**，每个计划步骤，根据它已经衡量的信号（问题提示、诊断意图、风险/策略）： | 模式 | 何时出现 | 它告诉代理 | |---|---|---| | `探索` | 诊断请求 — “X 已损坏；帮助我修复它” | 列出可能的 causes 并在提交修复之前用证据测试它们 | | `决定` | 多步骤诊断计划 | 通过影响、努力和风险收敛到一个选项 — 然后停止探索 | | `执行` | 具体的范围工作 | 最小偏差 — 没有新的要求、依赖或范围 | | `验证` | 破坏性/高风险更改 | 在将结果视为完成之前重新检查边缘情况和回归 | 执行计划在原位标记步骤（`1. [任务]（探索）…`）并在必要时添加 `[决定]` / `[验证]` 步骤，扩展提示获得一个 **工作方法** 部分，每个模式的指令（EN/TR/ES）。 **沉默是一种功能。** 清晰的请求（“修复一个错字”）获得 **零** 额外文本 — 调度器仅在信号保证时参与，并且该保证通过专用门控测试套件锁定。机器可读的调度也包含在 IR（`steps[]。调度` 带有 `模式`/`原因`/`置信度`，以及 `元数据.不确定性配置文件`）中，供代理包、分析和路由使用。 --- ### PR 安全 — 合并就绪层 AI PR 审查机器人会留下评论。 **PR 安全** 回答人类真正关心的问题：**我应该合并这个 PR 还是不应该？** 粘贴 PR 的标题、描述和更改的文件（以及可选的“落后提交”值）并获得带有背后信号的确定性裁决： | 裁决 | 含义 | |---|---| | **合并** | 没有阻塞的安全信号 — 按照正常的审查流程继续 | | **暂停** | 风险区域、缺少测试或范围不匹配 — 在合并之前解决 | | **拆分** | 太大/跨越太多顶级区域 — 分成更小的 PR | | **变基** | 分支已过时（远落后于基准） — 在合并之前更新 | 每个报告还会显示 **风险区域**，**测试覆盖率** 信号，**分支新鲜度**，**范围匹配**，以及具体的 **建议** — 并且可以复制或下载为 **GitHub 就绪 Markdown** 报告，直接粘贴到 PR（不自动评论；您保持控制）。 **v1 是一个离线、确定性的咨询工具。** 它仅在您粘贴的内容上运行 — 无需 GitHub API，无 AI 调用，无登录 — 并且永远不会阻止合并。 在侧边栏或 [`/pr-safety`](https://prcompiler.com/pr-safety) 处打开它； [PR 安全指南](docs/pr-safety.md) 提供了工作示例（文档仅限、身份验证风险、过时分支、需要拆分），`curl` 用于 `POST /pr-safety/report` 的配方，以及用于 GitHub 动作的建议 [GitHub 动作草图](docs/pr-safety-github-action.md)。 --- ### 保守模式 **保守** 切换控制编译器如何积极地解释您的输入。 | 状态 | 行为 | |---|---| | **开启** （默认） | 立足于您实际编写的内容。没有发明的库、伪造的 API 或捏造的要求。缺少的信息会导致澄清而不是捏造。 | | **关闭** | 更积极地扩展、填充空白并倾向于更丰富的提示优化。 | 切换开关在 **网页应用** 和 **浏览器扩展** 中均可用，其状态本地保存。 <p align="center"> <img src="docs/images/comp3offlineheuristics.PNG" alt="离线编译器 - 启发式模式" width="80%"> </p> --- ### 策略感知提示工作流程 提示编译器现在还为更敏感或执行密集型的请求公开了结构化的 IR 和策略层。 - **风险级别**：`低`，`中`，`高` - **执行模式**：`advice_only`，`human_approval_required`，`auto_ok` - **数据敏感性**：`public`，`internal`，`confidential`，`restricted` - **允许/禁止工具** - **净化规则** 这不是一个单独的产品。它是提示编译器中的一个新功能，帮助您在下游代码、研究或自动化流程中运行请求之前检查风险请求。 --- ### 代理生成器 描述一个角色或自主任务，**代理生成器** 生成一个完整、约束驱动的 AI 代理系统。 - **单个代理**：生成具有边界条件的聚焦、单角色代理提示 - **多代理群**：切换多代理模式以生成用于专门 worker 的协作群样式提示 #### 导出按钮 在生成代理后，**导出** 部分可以将输出转换为框架就绪的代码： | 框架 | 输出 | |---|---| | **Claude SDK** | 使用 `anthropic` 客户端的 Python 代码 | | **LangChain** | 带有 `ChatPromptTemplate` 的 Python 代理 | | **LangGraph** | 带有节点/边结构的 Python 图定义 | <p align="center"> <img src="docs/images/agent_generator.png" alt="代理生成器" width="80%"> </p> --- ### 技能和工具生成器 用普通英语描述一个功能，**技能生成器** 将其翻译成结构化的工具定义。 - 生成 **输入模式** 和 **输出模式** 为有效的 JSON - 生成一个字符串化的技能定义，适用于 LangChain、OpenAI 函数或自定义代理框架 #### 导出按钮 在生成技能后，**导出** 部分可以用框架特定的代码包装输出： | 格式 | 输出 | |---|---| | **LangChain 工具** | Python `@tool` 函数加 JSON 模式 | | **Claude tool_use** | 与 Anthropic 的 `tools` 参数兼容的 JSON 配置 | | **Claude MCP 工具存根** | 可运行的 FastMCP `server.py` + `README.md`，准备好注册到 Claude Code、Cursor 或 Claude Desktop | <p align="center"> <img src="docs/images/skills_generator.png" alt="技能生成器界面" width="80%"> </p> --- ### Claude 代理包测试版 **代理包** 侧边栏将一个简短的项目简介（项目类型、堆栈、目标）转换为一个 **可运行的、存储库就绪的 Claude 资产包** — 而不仅仅是一个提示。选择一个包类型、预览文件、复制单个代码片段或将整个包下载为 `.zip`。 此功能目前处于 **测试版**：它旨在让您快速获得一个强大的起点，但您仍应在生产环境中使用之前审查每个生成的文件。 测试版的含义： - **快速搭建，而不是盲目自动化** - 期待有用的存储库内存、设置、代理和工作流程文件，然后根据您的策略和边缘情况进行调整。 - **适用于早期存储库设置和内部实验** - 尤其是在您想要引导 Claude Code 约定时，无需手动编写每个资产。 - **需要人工审查** - 检查提示、权限、拒绝规则、CI 假设和生成的文档，然后再发布。 - **内置安装和审查清单** - 生成后，UI 显示一个逐步的清单，用于将每个文件放入存储库并审查敏感文件，然后再提交。 有四种打包类型可供选择，均来自单一的 Claude-first 端点： | 包类型 | 它发出什么 | 用它来做什么 | |---|---|---| | **项目包** | `CLAUDE.md`，`.claude/settings.json`，`.github/workflows/claude.yml` | 在新存储库中引导 Claude Code，具备策略、拒绝规则和 CI | | **子代理包** | 一个或多个 `.claude/agents/<role>.md` 文件，带有 `name`、`description` 和 `tools` 前置信息 | 为 Claude Code 提供一组专门的审阅者/构建者 | | **PR 审阅者包** | 审阅者子代理 + `.github/workflows/claude.yml` | 将 Claude 引入拉取请求审阅自动化 | | **MCP 工具存根** | FastMCP `server.py` + `README.md`，从技能定义中构建 | 建立一个 MCP 服务器，暴露一个自定义工具给任何 MCP 客户端 | **风险感知生成。** 每个请求都采用 `risk_mode`： | 模式 | 行为 | |---|---| | `balanced` （默认） | 明智的默认值：典型的拒绝列表、常见的允许工具、破坏性命令的温和要求门控 | | `strict` | 加紧拒绝列表、缩小允许的工具、放弃乐观的默认值 — 在将 Claude Code 引入具有敏感数据或不受信任的贡献者的存储库时选择此选项 | **提供者无关的核心。** 包生成器围绕一个 `AgentPackAdapter` 协议构建。Claude 特有的逻辑位于 `app/adapters/claude_code.py`；IR 层位于 `app/adapters/agent_packs.py`，保持中立。Cursor / Codex / 其他提供者的适配器可以在以后通过 core 插件，无需触摸。 **API 表面**： ```bash # 生成清单（预览友好：文件路径、内容、类型、预览顺序） curl -X POST https://api.example.com/agent-packs/claude \ -H "content-type: application/json" \ -d '{ "project_type": "FastAPI 服务", "stack": "Python 3.12, FastAPI, PostgreSQL", "goal": "添加一个带有拒绝规则的 Claude 审阅的 PR 工作流程，用于 .env", "pack_type": "project-pack", "risk_mode": "strict" }' # 相同的有效载荷，返回一个压缩的 .zip，直接放入存储库 curl -X POST https://api.example.com/agent-packs/claude/download \ -H "content-type: application/json" \ -d '{...same body...}' \ --output claude-project-pack.zip ``` **存储库原生采用。** 该存储库遵循自己的原则：编译器本身提供了一个 `CLAUDE.md`，一个强化的 `.claude/settings.json`（拒绝 `.env*`、`secrets/**`、`users.db`、`web/.env.local`；在明确确认之前阻止 `git push`、`fly:`、`railway:`），`.claude/agents/` 中的四个可调度子代理（`compiler-architect`、`frontend-polisher`、`mcp-integrator`、`prompt-safety-reviewer`），以及用于 PR 上托管的 Claude Code 审查的 `claude.yml` 工作流程。 --- ### Token 优化器 在不损失意义、逻辑或变量的情况下，将提示压缩约 **20-30%**。在上下文窗口限制附近非常有用。 <p align="center"> <img src="docs/images/comp2tokenoptimizer.PNG" alt="Token 优化器界面" width="80%"> </p> --- ### 基准测试游乐场 对原始提示与编译后的版本进行 A/B 测试： - **原始 vs. 编译** 侧边比较 - **自动裁判** 评分相关性、质量和清晰度 - **视觉指标** 包括改进百分比 <p align="center"> <img src="docs/images/comp4benchmark.PNG" alt="基准测试游乐场界面" width="80%"> </p> --- ### RAG 和知识库 上传项目文件，如 PDF、Markdown、文本或代码，以使提示编译器基于您自己的领域上下文。 - **上下文管理器** 用于拖放参考文件 - **战略家/批评者流程** 用于注入基础上下文和捕获幻觉主张 - **本地 SQLite 支持检索** 用于快速重用，无需重新上传 --- ### GitHub 工作流程工件 提示编译器可以从自然语言请求中渲染确定性的 Markdown 工件： - **问题简报** - **实施检查清单** - **PR 审查简报** 示例： ```bash python -m cli.main github render --type pr-review-brief --from-file prompt.txt ``` --- ### VS Code 扩展 VS Code 包位于 [`integrations/vscode-extension`](integrations/vscode-extension)。一旦获得 Marketplace 发布者并推送第一个 `vscode-v*` 标签，它就会从以下位置安装： - **VS Code 市场** — [`madara88645.promptc-vscode`](https://marketplace.visualstudio.com/items?itemName=madara88645.promptc-vscode) - **Open VSX** （VSCodium / Cursor） — [`madara88645/promptc-vscode`](https://open-vsx.org/extension/madara88645/promptc-vscode) 在此之前，请从源代码安装（参见 [扩展 README](integrations/vscode-extension/README.md#local-development)）或 `Publish VS Code Extension` 工作流运行的 `.vsix` 工件。 功能： - 命令：`PromptC: 编译选择`、`PromptC: 编译文件`、`PromptC: 重新编译上一次` - 活动栏侧边栏，用于后端状态、最新编译摘要、历史记录和收藏夹 - 面板选项卡：`意图`、`策略`、`提示`、`原始 JSON` - 工件操作：复制、插入编辑器、保存收藏夹 - 设置：`promptc.apiBaseUrl`、`promptc.conservativeMode`、`promptc.requestTimeoutMs`、`promptc.autoOpenPanel`、`promptc.historySize` API 密钥存储在 VS Code 秘密存储中，而不是工作区设置中。 --- ## 安装 ### CLI（pip / pipx） 从 PyPI 安装命令行编译器： ```bash pipx install prcompiler # 推荐 — 隔离安装 # 或 pip install prcompiler ``` 然后编译提示： ```bash promptc compile "写一首关于大海的俳句" promptc --version ``` ### 从源代码（开发） ```bash git clone https://github.com/madara88645/Compiler.git cd Compiler # 后端：pyproject.toml 是源代码 python -m pip install -e .[dev,docs] # 前端 cd web npm ci cd .. ``` ### 环境设置 ```bash cp .env.example .env ``` 核心变量： ```env OPENROUTER_API_KEY=sk-or-v1-your-actual-key OPENROUTER_BASE_URL=https://openrouter.ai/api/v1 OPENROUTER_MODEL=openai/gpt-oss-20b OPENROUTER_HTTP_REFERER= OPENROUTER_TITLE=提示编译器 # 提示编译器模式：保守（默认）或默认 PROMPT_COMPILER_MODE=conservative # 可选的内部身份验证强化（公共应用路由不会要求访问者输入提示编译器 API 密钥） ADMIN_API_KEY=replace-me PROMPTC_REQUIRE_API_KEY_FOR_ALL=false # 可选的 RAG 存储控制 PROMPTC_UPLOAD_DIR=.promptc_uploads PROMPTC_RAG_ALLOWED_ROOTS= ``` 注意： - 公共应用路由旨在无需自定义提示编译器 API 密钥即可工作。 - `OPENROUTER_API_KEY` 是服务器端提供商凭证，而不是访问者应输入到应用中的值。 - 提示编译器的云路径仅限 OpenRouter。Groq 和旧版 OpenAI 备用指南应被视为过时。 - 如果您设置 `PROMPTC_RAG_ALLOWED_ROOTS`，则只有位于这些根目录下的文件才能被路径索引。 --- ## 运行应用程序 **Windows（单击一次）：** 双击 `start_app.bat` **手动： ```bash # 终端 1 - 后端 python -m uvicorn api.main:app --reload --port 8080 # 终端 2 - 前端 cd web npm run dev ``` 打开 [http://localhost:3000](http://localhost:3000)。 --- 1. 在输入框中输入你的想法、提示、任务或请求。 2. 点击 **生成**。 3. 查看结果上的 **** — 它会告诉你编译后的提示是否可以运行以及原因。 4. 查看输出选项卡：`意图`、`系统`、`用户`、`计划`、`扩展`、`JSON`、`质量`。 5. 当你需要可靠的输出时，使用 **保守** 模式。 6. 如果任务在使用结果前检查策略7. 根据需要使用 Agent、技能、优化器、基准和 RAG 接口。 要检查拉取请求，请在侧边栏中打开 **PR 安全**，粘贴 PR 的标题、描述和更改的文件，然后 **分析 PR** 并阅读结果 — 如果有用，请将 Markdown 报告复制到 PR 中。 --- ## 项目结构 ```text api/ FastAPI 端点（编译、代理生成器、技能生成器、优化、RAG） app/ compiler.py 核心编译器管道 emitters.py 提示渲染层 models_v2.py 2 和策略合约 llm_engine/ 混合编译器和提供商逻辑 heuristics/ 离线解析、安全、风险和断 pr_safety/ 离线 PR 安全分析器（ + 信号） rag/ SQLite FTS5 RAG 和检索 testing/归运行器 github.py web/ app/ page.tsx 主要编译器 UI pr-safety/ PR 安全页面 + 报告代理 + Markdown agent-packs/ Claude 代理包生成器 + 安装 agent-generator/ 生成器页面 skills 技能生成器页面 benchmark/ 基准测试游 optimizer/ Token 优化器 components/ 共享 UI 组件 cli/ CLI 入口点 integrations/ vscode-extension/ extension/ 浏览器扩展 tests/ 离线安全测试套件 docs/ 产品和工作流文档 ``` 文档 - [`docs/pr.md`](docs/pr-safety.md PR 安全使用指南、示例和 `curl` 配方 - [`docs/pr-safety-github-action.md`](docs/pr-safety-github-action.md) — 咨询 CI 集成草图 - [`docs/pattern-library.md`](docs/pattern-library.md) - [`docs/promptc-safe-workflowsdocs/promptc-safe-work) - [`examples/github/p-artifact.yml`](examples/github/promptc-artifact.yml) --- ## 许可证 版权所有 © 2026 Mehmet Özel。保留所有权利。 在 [Apache License 2.0](LICENSE) 下授权。 对于托管服务查询： [mehmet.ozel270](mailto:met.ozel2701@gmail.com) 自我托管是免费的，并且保持免费。