{ "canonical_name": "The-PR-Agent/pr-agent", "compilation_id": "pack_3cb9f1a566c5470eb989d71ea3fed95e", "created_at": "2026-05-11T17:27:36.572667+00:00", "created_by": "project-pack-compiler", "feedback": { "carrier_selection_notes": [ "viable_asset_types=skill, recipe, host_instruction, eval, preflight", "recommended_asset_types=skill, recipe, host_instruction, eval, preflight" ], "evidence_delta": { "confirmed_claims": [ "identity_anchor_present", "capability_and_host_targets_present", "install_path_declared_or_better" ], "missing_required_fields": [], "must_verify_forwarded": [ "Run or inspect `pip install pr-agent` in an isolated environment.", "Confirm the project exposes the claimed capability to at least one target host." ], "quickstart_execution_scope": "allowlisted_sandbox_smoke", "sandbox_command": "pip install pr-agent", "sandbox_container_image": "python:3.12-slim", "sandbox_execution_backend": "docker", "sandbox_planner_decision": "deterministic_isolated_install", "sandbox_validation_id": "sbx_0d0e7f6eaeae47e58331cac24f771116" }, "feedback_event_type": "project_pack_compilation_feedback", "learning_candidate_reasons": [], "template_gaps": [] }, "identity": { "canonical_id": "project_8f6634d44f1e106247eda0d6044ba768", "canonical_name": "The-PR-Agent/pr-agent", "homepage_url": null, "license": "unknown", "repo_url": "https://github.com/The-PR-Agent/pr-agent", "slug": "pr-agent", "source_packet_id": "phit_dcee096b88b0475584b8a87860198e8f", "source_validation_id": "dval_f01005a3aa214a0dab63463c792358ed" }, "merchandising": { "best_for": "需要软件开发与交付能力，并使用 chatgpt的用户", "github_forks": 1505, "github_stars": 11175, "one_liner_en": "🚀 PR Agent: The Original Open-Source PR Reviewer.", "one_liner_zh": "🚀 PR Agent: The Original Open-Source PR Reviewer.", "primary_category": { "category_id": "software-development", "confidence": "medium", "name_en": "Software Development", "name_zh": "软件开发与交付", "reason": "matched_keywords:review, git" }, "target_user": "使用 chatgpt 等宿主 AI 的用户", "title_en": "pr-agent", "title_zh": "pr-agent 能力包", "visible_tags": [ { "label_en": "Knowledge Retrieval", "label_zh": "知识检索", "source": "repo_evidence_project_characteristics", "tag_id": "product_domain-knowledge-retrieval", "type": "product_domain" }, { "label_en": "Knowledge Base Q&A", "label_zh": "知识库问答", "source": "repo_evidence_project_characteristics", "tag_id": "user_job-knowledge-base-q-a", "type": "user_job" }, { "label_en": "Code Review", "label_zh": "代码审查", "source": "repo_evidence_project_characteristics", "tag_id": "core_capability-code-review", "type": "core_capability" }, { "label_en": "Node-based Workflow", "label_zh": "节点式流程编排", "source": "repo_evidence_project_characteristics", "tag_id": "workflow_pattern-node-based-workflow", "type": "workflow_pattern" }, { "label_en": "Local-first", "label_zh": "本地优先", "source": "repo_evidence_project_characteristics", "tag_id": "selection_signal-local-first", "type": "selection_signal" } ] }, "packet_id": "phit_dcee096b88b0475584b8a87860198e8f", "page_model": { "artifacts": { "artifact_slug": "pr-agent", "files": [ "PROJECT_PACK.json", "QUICK_START.md", "PROMPT_PREVIEW.md", "HUMAN_MANUAL.md", "AI_CONTEXT_PACK.md", "BOUNDARY_RISK_CARD.md", "PITFALL_LOG.md", "REPO_INSPECTION.json", "REPO_INSPECTION.md", "CAPABILITY_CONTRACT.json", "EVIDENCE_INDEX.json", "CLAIM_GRAPH.json" ], "required_files": [ "PROJECT_PACK.json", "QUICK_START.md", "PROMPT_PREVIEW.md", "HUMAN_MANUAL.md", "AI_CONTEXT_PACK.md", "BOUNDARY_RISK_CARD.md", "PITFALL_LOG.md", "REPO_INSPECTION.json" ] }, "detail": { "capability_source": "Project Hit Packet + DownstreamValidationResult", "commands": [ { "command": "pip install pr-agent", "label": "Python / pip · 官方安装入口", "source": "https://github.com/The-PR-Agent/pr-agent#readme", "verified": true } ], "display_tags": [ "知识检索", "知识库问答", "代码审查", "节点式流程编排", "本地优先" ], "eyebrow": "软件开发与交付", "glance": [ { "body": "判断自己是不是目标用户。", "label": "最适合谁", "value": "需要软件开发与交付能力，并使用 chatgpt的用户" }, { "body": "先理解能力边界，再决定是否继续。", "label": "核心价值", "value": "🚀 PR Agent: The Original Open-Source PR Reviewer." }, { "body": "未完成验证前保持审慎。", "label": "继续前", "value": "publish to Doramagic.ai project surfaces" } ], "guardrail_source": "Boundary & Risk Card", "guardrails": [ { "body": "Prompt Preview 只展示流程，不证明项目已安装或运行。", "label": "Check 1", "value": "不要把试用当真实运行" }, { "body": "chatgpt", "label": "Check 2", "value": "确认宿主兼容" }, { "body": "publish to Doramagic.ai project surfaces", "label": "Check 3", "value": "先隔离验证" } ], "mode": "skill, recipe, host_instruction, eval, preflight", "pitfall_log": { "items": [ { "body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Publish linux/arm64 Docker image for github_app tag", "category": "安装坑", "evidence": [ "community_evidence:github | cevd_8cb9e552d2e2452cbe958628f6e800b6 | https://github.com/The-PR-Agent/pr-agent/issues/2386 | 来源讨论提到 python 相关条件，需在安装/试用前复核。" ], "severity": "medium", "suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。", "title": "来源证据：Publish linux/arm64 Docker image for github_app tag", "user_impact": "可能增加新用户试用和生产接入成本。" }, { "body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug] UnicodeDecodeError in gitea_provider.py when parsing binary files before extension filtering", "category": "安装坑", "evidence": [ "community_evidence:github | cevd_52bd470b7b5e4be6858b290e41c93036 | https://github.com/The-PR-Agent/pr-agent/issues/2380 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。" ], "severity": "medium", "suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。", "title": "来源证据：[Bug] UnicodeDecodeError in gitea_provider.py when parsing binary files before extension filtering", "user_impact": "可能阻塞安装或首次运行。" }, { "body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.31", "category": "安装坑", "evidence": [ "community_evidence:github | cevd_ef0e5f5f982146d8bd002453b969c07f | https://github.com/The-PR-Agent/pr-agent/releases/tag/v0.31 | 来源类型 github_release 暴露的待验证使用条件。" ], "severity": "medium", "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。", "title": "来源证据：v0.31", "user_impact": "可能增加新用户试用和生产接入成本。" }, { "body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.34.2", "category": "安装坑", "evidence": [ "community_evidence:github | cevd_4bc22335937e44c0b529ab84d1e69a60 | https://github.com/The-PR-Agent/pr-agent/releases/tag/v0.34.2 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。" ], "severity": "medium", "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。", "title": "来源证据：v0.34.2", "user_impact": "可能增加新用户试用和生产接入成本。" }, { "body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：AzureDevopsProvider.get_repo_settings drops chunks after the first, silently truncating .pr_agent.toml", "category": "配置坑", "evidence": [ "community_evidence:github | cevd_4ee2a84ba307469b9b329a043a70a224 | https://github.com/The-PR-Agent/pr-agent/issues/2376 | 来源讨论提到 python 相关条件，需在安装/试用前复核。" ], "severity": "medium", "suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。", "title": "来源证据：AzureDevopsProvider.get_repo_settings drops chunks after the first, silently truncating .pr_agent.toml", "user_impact": "可能增加新用户试用和生产接入成本。" }, { "body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Ticket context not scoped per PR in long-lived deployments — stale tickets leak between unrelated PRs", "category": "配置坑", "evidence": [ "community_evidence:github | cevd_a9b90b0cfbbf4529b60d65f564f4592e | https://github.com/The-PR-Agent/pr-agent/issues/2383 | 来源讨论提到 python 相关条件，需在安装/试用前复核。" ], "severity": "medium", "suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。", "title": "来源证据：Ticket context not scoped per PR in long-lived deployments — stale tickets leak between unrelated PRs", "user_impact": "可能增加新用户试用和生产接入成本。" }, { "body": "GitHub 社区证据显示该项目存在一个能力理解相关的待验证问题：v0.34.1", "category": "能力坑", "evidence": [ "community_evidence:github | cevd_eb46a134c8984cd8898e13f61602f165 | https://github.com/The-PR-Agent/pr-agent/releases/tag/v0.34.1 | 来源类型 github_release 暴露的待验证使用条件。" ], "severity": "medium", "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。", "title": "来源证据：v0.34.1", "user_impact": "可能增加新用户试用和生产接入成本。" }, { "body": "README/documentation is current enough for a first validation pass.", "category": "能力坑", "evidence": [ "capability.assumptions | github_repo:662766482 | https://github.com/The-PR-Agent/pr-agent | README/documentation is current enough for a first validation pass." ], "severity": "medium", "suggested_check": "将假设转成下游验证清单。", "title": "能力判断依赖假设", "user_impact": "假设不成立时，用户拿不到承诺的能力。" }, { "body": "未记录 last_activity_observed。", "category": "维护坑", "evidence": [ "evidence.maintainer_signals | github_repo:662766482 | https://github.com/The-PR-Agent/pr-agent | last_activity_observed missing" ], "severity": "medium", "suggested_check": "补 GitHub 最近 commit、release、issue/PR 响应信号。", "title": "维护活跃度未知", "user_impact": "新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。" }, { "body": "no_demo", "category": "安全/权限坑", "evidence": [ "downstream_validation.risk_items | github_repo:662766482 | https://github.com/The-PR-Agent/pr-agent | no_demo; severity=medium" ], "severity": "medium", "suggested_check": "进入安全/权限治理复核队列。", "title": "下游验证发现风险项", "user_impact": "下游已经要求复核，不能在页面中弱化。" }, { "body": "No sandbox install has been executed yet; downstream must verify before user use.", "category": "安全/权限坑", "evidence": [ "risks.safety_notes | github_repo:662766482 | https://github.com/The-PR-Agent/pr-agent | No sandbox install has been executed yet; downstream must verify before user use." ], "severity": "medium", "suggested_check": "转成明确权限清单和安全审查提示。", "title": "存在安全注意事项", "user_impact": "用户安装前需要知道权限边界和敏感操作。" }, { "body": "no_demo", "category": "安全/权限坑", "evidence": [ "risks.scoring_risks | github_repo:662766482 | https://github.com/The-PR-Agent/pr-agent | no_demo; severity=medium" ], "severity": "medium", "suggested_check": "把风险写入边界卡，并确认是否需要人工复核。", "title": "存在评分风险", "user_impact": "风险会影响是否适合普通用户安装。" }, { "body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Bug + feature: `-i` (incremental review) crashes on Azure DevOps; needs full incremental support in AzureDevopsProvider", "category": "安全/权限坑", "evidence": [ "community_evidence:github | cevd_e65762126ba84855a8440bd9e5a685bb | https://github.com/The-PR-Agent/pr-agent/issues/2379 | 来源讨论提到 python 相关条件，需在安装/试用前复核。" ], "severity": "medium", "suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。", "title": "来源证据：Bug + feature: `-i` (incremental review) crashes on Azure DevOps; needs full incremental support in AzureDevopsProvider", "user_impact": "可能阻塞安装或首次运行。" }, { "body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：OSS build silently ignores best_practices.md (currently SaaS-only)", "category": "安全/权限坑", "evidence": [ "community_evidence:github | cevd_f51f28cf40b14b7ca80598af4527661a | https://github.com/The-PR-Agent/pr-agent/issues/2377 | 来源讨论提到 python 相关条件，需在安装/试用前复核。" ], "severity": "medium", "suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。", "title": "来源证据：OSS build silently ignores best_practices.md (currently SaaS-only)", "user_impact": "可能影响授权、密钥配置或安全边界。" }, { "body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：feat: support agent skills for context-aware review guidance", "category": "安全/权限坑", "evidence": [ "community_evidence:github | cevd_59ad4ca55ca248f989c91ce40068cc6d | https://github.com/The-PR-Agent/pr-agent/issues/2384 | 来源类型 github_issue 暴露的待验证使用条件。" ], "severity": "medium", "suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。", "title": "来源证据：feat: support agent skills for context-aware review guidance", "user_impact": "可能影响授权、密钥配置或安全边界。" }, { "body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：litellm success/cost callbacks never fire from pr-agent's async run loop", "category": "安全/权限坑", "evidence": [ "community_evidence:github | cevd_42f0b36e0c434c939c49c91fc7ccb82a | https://github.com/The-PR-Agent/pr-agent/issues/2378 | 来源讨论提到 python 相关条件，需在安装/试用前复核。" ], "severity": "medium", "suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。", "title": "来源证据：litellm success/cost callbacks never fire from pr-agent's async run loop", "user_impact": "可能影响授权、密钥配置或安全边界。" } ], "source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals", "summary": "发现 23 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：Publish linux/arm64 Docker image for github_app tag。", "title": "踩坑日志" }, "snapshot": { "contributors": 228, "forks": 1505, "license": "unknown", "note": "GitHub API 快照，非实时质量证明；用于开工前背景判断。", "stars": 11175, "open_issues": 160, "pushed_at": null }, "source_url": "https://github.com/The-PR-Agent/pr-agent", "steps": [ { "body": "不安装项目，先体验能力节奏。", "code": "preview", "title": "先试 Prompt" }, { "body": "理解输入、输出、失败模式和边界。", "code": "manual", "title": "读说明书" }, { "body": "把上下文交给宿主 AI 继续工作。", "code": "context", "title": "带给 AI" }, { "body": "进入主力环境前先完成安装入口与风险边界验证。", "code": "verify", "title": "沙箱验证" } ], "subtitle": "🚀 PR Agent: The Original Open-Source PR Reviewer.", "title": "pr-agent 能力包", "trial_prompt": "# pr-agent - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 pr-agent 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的软件开发与交付任务。\n我常用的宿主 AI：chatgpt\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: 🚀 PR Agent: The Original Open-Source PR Reviewer. 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. introduction：PR-Agent 简介。围绕“PR-Agent 简介”模拟一次用户任务，不展示安装或运行结果。\n2. system_architecture：系统架构。围绕“系统架构”模拟一次用户任务，不展示安装或运行结果。\n3. ai_integration：AI 模型集成。围绕“AI 模型集成”模拟一次用户任务，不展示安装或运行结果。\n4. tools_overview：工具概述。围绕“工具概述”模拟一次用户任务，不展示安装或运行结果。\n5. review_tool：代码审查工具 (Review)。围绕“代码审查工具 (Review)”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. introduction\n输入：用户提供的“PR-Agent 简介”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. system_architecture\n输入：用户提供的“系统架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. ai_integration\n输入：用户提供的“AI 模型集成”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. tools_overview\n输入：用户提供的“工具概述”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. review_tool\n输入：用户提供的“代码审查工具 (Review)”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / introduction：Step 1 必须围绕“PR-Agent 简介”形成一个小中间产物，并等待用户确认。\n- Step 2 / system_architecture：Step 2 必须围绕“系统架构”形成一个小中间产物，并等待用户确认。\n- Step 3 / ai_integration：Step 3 必须围绕“AI 模型集成”形成一个小中间产物，并等待用户确认。\n- Step 4 / tools_overview：Step 4 必须围绕“工具概述”形成一个小中间产物，并等待用户确认。\n- Step 5 / review_tool：Step 5 必须围绕“代码审查工具 (Review)”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/The-PR-Agent/pr-agent\n- https://github.com/The-PR-Agent/pr-agent#readme\n- README.md\n- pr_agent/agent/pr_agent.py\n- pr_agent/tools/pr_description.py\n- pr_agent/tools/pr_reviewer.py\n- pr_agent/config_loader.py\n- pr_agent/algo/types.py\n- pr_agent/git_providers/__init__.py\n- pr_agent/git_providers/git_provider.py\n- pr_agent/algo/ai_handlers/base_ai_handler.py\n- pr_agent/algo/ai_handlers/openai_ai_handler.py\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 pr-agent 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n", "voices": [ { "body": "来源平台：github。github/github_issue: Publish linux/arm64 Docker image for github_app tag（https://github.com/The-PR-Agent/pr-agent/issues/2386）；github/github_issue: feat: support agent skills for context-aware review guidance（https://github.com/The-PR-Agent/pr-agent/issues/2384）；github/github_issue: Ticket context not scoped per PR in long-lived deployments — stale ticke（https://github.com/The-PR-Agent/pr-agent/issues/2383）；github/github_issue: litellm success/cost callbacks never fire from pr-agent's async run loop（https://github.com/The-PR-Agent/pr-agent/issues/2378）；github/github_issue: [Bug] UnicodeDecodeError in gitea_provider.py when parsing binary files （https://github.com/The-PR-Agent/pr-agent/issues/2380）；github/github_issue: Bug + feature: `-i` (incremental review) crashes on Azure DevOps; needs （https://github.com/The-PR-Agent/pr-agent/issues/2379）；github/github_issue: OSS build silently ignores best_practices.md (currently SaaS-only)（https://github.com/The-PR-Agent/pr-agent/issues/2377）；github/github_issue: AzureDevopsProvider.get_repo_settings drops chunks after the first, sile（https://github.com/The-PR-Agent/pr-agent/issues/2376）；github/github_release: v0.34.2（https://github.com/The-PR-Agent/pr-agent/releases/tag/v0.34.2）；github/github_release: v0.34.1（https://github.com/The-PR-Agent/pr-agent/releases/tag/v0.34.1）；github/github_release: v0.34（https://github.com/The-PR-Agent/pr-agent/releases/tag/v0.34）；github/github_release: v0.33（https://github.com/The-PR-Agent/pr-agent/releases/tag/v0.33）。这些是项目级外部声音，不作为单独质量证明。", "items": [ { "kind": "github_issue", "source": "github", "title": "Publish linux/arm64 Docker image for github_app tag", "url": "https://github.com/The-PR-Agent/pr-agent/issues/2386" }, { "kind": "github_issue", "source": "github", "title": "feat: support agent skills for context-aware review guidance", "url": "https://github.com/The-PR-Agent/pr-agent/issues/2384" }, { "kind": "github_issue", "source": "github", "title": "Ticket context not scoped per PR in long-lived deployments — stale ticke", "url": "https://github.com/The-PR-Agent/pr-agent/issues/2383" }, { "kind": "github_issue", "source": "github", "title": "litellm success/cost callbacks never fire from pr-agent's async run loop", "url": "https://github.com/The-PR-Agent/pr-agent/issues/2378" }, { "kind": "github_issue", "source": "github", "title": "[Bug] UnicodeDecodeError in gitea_provider.py when parsing binary files ", "url": "https://github.com/The-PR-Agent/pr-agent/issues/2380" }, { "kind": "github_issue", "source": "github", "title": "Bug + feature: `-i` (incremental review) crashes on Azure DevOps; needs ", "url": "https://github.com/The-PR-Agent/pr-agent/issues/2379" }, { "kind": "github_issue", "source": "github", "title": "OSS build silently ignores best_practices.md (currently SaaS-only)", "url": "https://github.com/The-PR-Agent/pr-agent/issues/2377" }, { "kind": "github_issue", "source": "github", "title": "AzureDevopsProvider.get_repo_settings drops chunks after the first, sile", "url": "https://github.com/The-PR-Agent/pr-agent/issues/2376" }, { "kind": "github_release", "source": "github", "title": "v0.34.2", "url": "https://github.com/The-PR-Agent/pr-agent/releases/tag/v0.34.2" }, { "kind": "github_release", "source": "github", "title": "v0.34.1", "url": "https://github.com/The-PR-Agent/pr-agent/releases/tag/v0.34.1" }, { "kind": "github_release", "source": "github", "title": "v0.34", "url": "https://github.com/The-PR-Agent/pr-agent/releases/tag/v0.34" }, { "kind": "github_release", "source": "github", "title": "v0.33", "url": "https://github.com/The-PR-Agent/pr-agent/releases/tag/v0.33" } ], "status": "已收录 12 条来源", "title": "社区讨论" } ] }, "homepage_card": { "category": "软件开发与交付", "desc": "🚀 PR Agent: The Original Open-Source PR Reviewer.", "effort": "安装已验证", "forks": 1500, "icon": "code", "name": "pr-agent 能力包", "risk": "可发布", "slug": "pr-agent", "stars": 11160, "tags": [ "知识检索", "知识库问答", "代码审查", "节点式流程编排", "本地优先" ], "thumb": "gray", "type": "Skill Pack" }, "manual": { "markdown": "# https://github.com/The-PR-Agent/pr-agent 项目说明书\n\n生成时间：2026-05-11 17:14:11 UTC\n\n## 目录\n\n- [PR-Agent 简介](#introduction)\n- [系统架构](#system_architecture)\n- [AI 模型集成](#ai_integration)\n- [工具概述](#tools_overview)\n- [代码审查工具 (Review)](#review_tool)\n- [代码改进工具 (Improve)](#improve_tool)\n- [Git 平台集成](#git_providers)\n- [部署方式](#deployment)\n- [配置管理](#configuration)\n- [扩展与定制](#customization)\n\n\n\n## PR-Agent 简介\n\n### 相关页面\n\n相关主题：[系统架构](#system_architecture), [部署方式](#deployment)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/The-PR-Agent/pr-agent/blob/main/README.md)\n- [pr_agent/agent/pr_agent.py](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/agent/pr_agent.py)\n- [pr_agent/tools/pr_description.py](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/tools/pr_description.py)\n- [pr_agent/tools/pr_reviewer.py](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/tools/pr_reviewer.py)\n- [pr_agent/tools/pr_code_suggestions.py](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/tools/pr_code_suggestions.py)\n- [pr_agent/servers/help.py](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/servers/help.py)\n- [pr_agent/algo/utils.py](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/algo/utils.py)\n
\n\n# PR-Agent 简介\n\n## 概述\n\nPR-Agent 是一个由 AI 驱动的自动化工具，旨在帮助开发团队更高效地进行代码审查和 PR（Pull Request）管理。该工具通过分析 PR 代码变更，自动生成描述、代码建议、审查意见等，帮助团队提升代码质量和协作效率。\n\nPR-Agent 支持多种使用方式，包括 GitHub Action、GitLab CLI、Docker 等部署方式，能够与主流代码托管平台无缝集成。资料来源：[README.md:1-30]()\n\n## 核心功能模块\n\nPR-Agent 提供多个独立工具模块，每个模块专注于特定的代码审查任务：\n\n| 模块名称 | 功能描述 | 触发命令 |\n|---------|---------|---------|\n| `describe` | 自动生成 PR 描述、标题、类型和变更摘要 | `/describe` |\n| `review` | 对 PR 进行全面代码审查，识别潜在问题 | `/review` |\n| `improve` | 生成代码改进建议和优化方案 | `/improve` |\n| `ask` | 回答关于 PR 代码变更的问题 | `/ask \"...\"` |\n| `help_docs` | 根据文档路径回答使用问题 | `/help_docs \"...\"` |\n\n资料来源：[pr_agent/servers/help.py:1-50]()\n\n## 架构设计\n\n### 整体架构\n\n```mermaid\ngraph TD\n A[用户触发] --> B[GitHub/GitLab Provider]\n B --> C[PR Agent Core]\n C --> D[工具调度器]\n D --> E[describe 工具]\n D --> F[review 工具]\n D --> G[improve 工具]\n D --> H[ask 工具]\n E --> I[LLM 处理]\n F --> I\n G --> I\n H --> I\n I --> J[Markdown 输出]\n J --> K[PR 评论/更新]\n```\n\n### 工具执行流程\n\n```mermaid\nsequenceDiagram\n participant U as 用户\n participant G as Git Provider\n participant T as 工具模块\n participant L as LLM\n participant P as 输出处理\n\n U->>G: 触发 PR 事件\n G->>T: 获取代码变更\n T->>L: 发送 Prompt\n L->>T: 返回分析结果\n T->>P: 格式化输出\n P->>G: 发布评论\n G->>U: 显示结果\n```\n\n## 核心工具详解\n\n### Describe 工具\n\n`describe` 工具扫描 PR 代码变更，自动生成以下内容：\n\n- **PR 标题**：格式为 `<类型>: <标题>`，简明扼要（最多 10 个词）\n- **PR 类型**：如 Bug fix、Tests、Enhancement、Documentation、Other\n- **摘要说明**：概括本次变更的主要目的\n- **详细清单**：按语义分组列出变更的文件\n\n该工具支持通过标记（Markers）方式控制生成内容，用户可以在 PR 描述中预留 `pr_agent:type`、`pr_agent:summary`、`pr_agent:walkthrough`、`pr_agent:diagram` 等标记，工具将自动填充对应内容。\n\n资料来源：[pr_agent/tools/pr_description.py:1-100]()\n\n### Review 工具\n\n`review` 工具对 PR 进行全面的代码审查，包括：\n\n- 识别代码潜在问题\n- 检查安全问题\n- 评估代码可维护性\n- 提供改进建议\n\n审查结果以结构化的 Markdown 表格形式输出，包含问题类型、严重程度和具体位置链接。\n\n资料来源：[pr_agent/tools/pr_reviewer.py:1-50]()\n\n### Improve 工具\n\n`improve` 工具专注于代码优化建议，能够：\n\n- 扫描 PR 代码变更\n- 自动生成代码优化建议\n- 提供代码改进的 before/after 示例\n\n该工具支持配置项控制，包括建议数量阈值、评分机制等。评分分为 High、Medium、Low 三个等级。\n\n资料来源：[pr_agent/tools/pr_code_suggestions.py:80-120]()\n\n## 配置系统\n\nPR-Agent 使用 TOML 格式的配置文件，主要配置节包括：\n\n| 配置节 | 用途 |\n|-------|------|\n| `pr_description` | PR 描述生成配置 |\n| `pr_reviewer` | 代码审查配置 |\n| `pr_code_suggestions` | 代码建议配置 |\n| `config` | 全局配置 |\n\n配置可以通过以下方式指定：\n\n1. **命令行参数**：使用 `--section.key=value` 格式\n ```bash\n /describe --pr_description.some_config1=...\n ```\n2. **配置文件**：在 `pr_agent.toml` 中定义\n ```toml\n [pr_description]\n some_config1=...\n some_config2=...\n ```\n\n资料来源：[pr_agent/algo/utils.py:200-250]()\n\n## 部署方式\n\n### GitHub Action（推荐）\n\n```yaml\nname: PR Agent\non:\n pull_request:\n types: [opened, synchronize]\njobs:\n pr_agent_job:\n runs-on: ubuntu-latest\n steps:\n - name: PR Agent action step\n uses: the-pr-agent/pr-agent@main\n env:\n OPENAI_KEY: ${{ secrets.OPENAI_KEY }}\n GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}\n```\n\n### CLI 本地运行\n\n```bash\npip install pr-agent\nexport OPENAI_KEY=your_key_here\npr-agent --pr_url https://github.com/owner/repo/pull/123 review\n```\n\n### Docker 部署\n\n```bash\ndocker run -e OPENAI_KEY=your_key pragent/pr-agent:latest \\\n --pr_url https://github.com/owner/repo/pull/123 review\n```\n\n资料来源：[README.md:30-80]()\n\n## 输出格式\n\n### Markdown 表格输出\n\nPR-Agent 生成的输出采用 GitHub Flavored Markdown (GFM) 格式，支持折叠面板和表格：\n\n```html\n\n \n \n \n \n
\n 文件名\n
\n 变更描述内容\n
+10/-5
\n```\n\n### 可访问性处理\n\n工具自动处理特殊字符转义，将单引号替换为反引号，并对文件名进行截断处理。链接格式根据平台不同自动适配 GitHub 或 GitLab 风格。\n\n资料来源：[pr_agent/algo/utils.py:100-150]()\n\n## 自动化配置\n\n工具支持自动化触发，可以配置在以下时机自动执行：\n\n- PR 打开时（`pull_request` 类型为 `opened`）\n- PR 同步更新时（`pull_request` 类型为 `synchronize`）\n\n默认的自动化命令列表：\n```python\npr_commands = [\"/describe\", ...]\n```\n\n可通过配置开启标记模式：\n```python\npr_commands = [\"/describe --pr_description.use_description_markers=true\", ...]\n```\n\n资料来源：[pr_agent/servers/help.py:80-120]()\n\n## 安全性注意事项\n\n根据项目指南：\n\n- 密钥和敏感信息应通过环境变量提供\n- 禁止将 API 密钥直接持久化到代码中\n- 遵循 `CONTRIBUTING.md` 中的提交规范\n- 使用 Conventional Commit 风格的提交信息\n\n资料来源：[AGENTS.md:30-50]()\n\n## 相关链接\n\n- 官方文档：https://docs.pr-agent.ai\n- 安装指南：https://docs.pr-agent.ai/installation/\n- 使用指南：https://docs.pr-agent.ai/usage-guide/\n\n---\n\n\n\n## 系统架构\n\n### 相关页面\n\n相关主题：[PR-Agent 简介](#introduction), [AI 模型集成](#ai_integration), [Git 平台集成](#git_providers)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [pr_agent/tools/pr_description.py](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/tools/pr_description.py)\n- [pr_agent/servers/help.py](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/servers/help.py)\n- [pr_agent/algo/utils.py](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/algo/utils.py)\n- [pr_agent/tools/pr_code_suggestions.py](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/tools/pr_code_suggestions.py)\n- [pr_agent/tools/pr_config.py](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/tools/pr_config.py)\n- [AGENTS.md](https://github.com/The-PR-Agent/pr-agent/blob/main/AGENTS.md)\n- [README.md](https://github.com/The-PR-Agent/pr-agent/blob/main/README.md)\n- [pr_agent/git_providers/bitbucket_server_provider.py](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/git_providers/bitbucket_server_provider.py)\n
\n\n# 系统架构\n\n## 1. 概述\n\nPR-Agent 是一个自动化 Pull Request 分析和处理工具，通过模块化的工具系统实现 PR 描述生成、代码审查、代码建议生成等功能。该系统基于事件驱动架构，支持 GitHub、GitLab、Bitbucket Server 等多个平台。\n\n核心架构由以下几部分组成：\n\n| 组件层 | 职责 | 核心文件 |\n|--------|------|----------|\n| 入口层 | 处理用户命令和事件触发 | `AGENTS.md` |\n| 工具层 | 实现具体功能逻辑 | `pr_description.py`, `pr_code_suggestions.py` |\n| 基础设施层 | Git 集成、配置管理、日志 | `git_provider.py`, `config_loader.py` |\n| 输出层 | 格式化输出和用户交互 | `utils.py`, `help.py` |\n\n## 2. 系统架构图\n\n```mermaid\ngraph TD\n subgraph 入口层\n CMD[命令行/评论命令] --> AGENT[Agent 调度器]\n end\n \n subgraph 工具层\n DESCRIBE[描述工具
pr_description.py]\n REVIEW[审查工具]\n IMPROVE[改进工具]\n ASK[问答工具]\n HELP_DOCS[帮助文档工具]\n CONFIG[配置工具]\n end\n \n subgraph 基础设施层\n GIT[Git Providers
git_provider.py]\n CFG[配置加载器
config_loader.py]\n LOG[日志系统]\n end\n \n subgraph Git平台\n GITHUB[GitHub Provider]\n GITLAB[GitLab Provider]\n BITBUCKET[Bitbucket Provider]\n end\n \n AGENT --> DESCRIBE\n AGENT --> REVIEW\n AGENT --> IMPROVE\n AGENT --> ASK\n AGENT --> HELP_DOCS\n AGENT --> CONFIG\n \n DESCRIBE --> GIT\n REVIEW --> GIT\n IMPROVE --> GIT\n ASK --> GIT\n CONFIG --> CFG\n \n GIT --> GITHUB\n GIT --> GITLAB\n GIT --> BITBUCKET\n \n DESCRIBE --> LOG\n IMPROVE --> LOG\n```\n\n## 3. 核心组件详解\n\n### 3.1 工具系统架构\n\nPR-Agent 的工具系统采用插件化设计，每个工具负责特定功能。所有工具都遵循统一的调用接口：\n\n```mermaid\ngraph LR\n subgraph 输入\n E1[PR 上下文]\n E2[用户命令]\n E3[配置文件]\n end\n \n subgraph 工具处理\n T1[解析输入]\n T2[调用 LLM]\n T3[处理结果]\n end\n \n subgraph 输出\n O1[Markdown 格式]\n O2[评论/更新]\n O3[配置展示]\n end\n \n E1 --> T1\n E2 --> T1\n E3 --> T1\n T1 --> T2\n T2 --> T3\n T3 --> O1\n T3 --> O2\n T3 --> O3\n```\n\n### 3.2 PR 描述工具（pr_description）\n\n`pr_description.py` 负责生成完整的 PR 描述，包括标题、类型、摘要、代码变更列表等。资料来源：[pr_agent/tools/pr_description.py:1-200]()\n\n#### 核心数据结构\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `pr_body` | str | PR 描述主体内容 |\n| `semantic_label` | str | 语义标签分类 |\n| `list_tuples` | list | 文件变更元组列表 |\n| `delta` | int | 列宽度配置 |\n\n#### 输出格式处理\n\nPR 描述工具支持多种输出格式，包括可折叠的文件列表和 GFM（GitHub Flavored Markdown）支持。关键代码位于文件的数据处理部分，通过遍历 `diff_files` 获取每个文件的增删行数统计：\n\n```python\nfor f in diff_files:\n if f.filename.lower().strip('/') == filename.lower().strip('/'):\n num_plus_lines = f.num_plus_lines\n num_minus_lines = f.num_minus_lines\n```\n\n### 3.3 代码建议工具（pr_code_suggestions）\n\n代码建议工具扫描 PR 变更并自动生成改进建议。评分机制分为三个等级：\n\n| 评分等级 | 阈值配置 | 说明 |\n|----------|----------|------|\n| High（高） | `score >= th_high` | 高优先级建议，默认值 9 |\n| Medium（中） | `score >= th_medium` | 中优先级建议，默认值 7 |\n| Low（低） | `score < 7` | 低优先级建议 |\n\n资料来源：[pr_agent/tools/pr_code_suggestions.py:100-120]()\n\n#### 持久化模式\n\n代码建议支持持久化模式，可以保留历史建议记录。该功能通过以下逻辑实现：\n\n1. 检测现有评论中是否存在历史建议\n2. 将新建议与历史建议合并\n3. 按提交进行分组展示\n4. 自动移除最旧的建议以控制数量\n\n### 3.4 帮助系统（help）\n\n帮助系统提供交互式使用指南，支持以下工具的文档：\n\n- `/describe` - PR 描述生成\n- `/review` - 代码审查\n- `/improve` - 代码改进建议\n- `/ask` - 问答功能\n- `/help_docs` - 文档帮助\n\n资料来源：[pr_agent/servers/help.py:1-150]()\n\n## 4. Git Provider 系统\n\n### 4.1 抽象层设计\n\nGit Provider 系统采用适配器模式，为不同平台提供统一接口：\n\n```mermaid\nclassDiagram\n class GitProvider {\n <>\n +get_diff_files()\n +publish_comment()\n +edit_comment()\n +get_settings()\n }\n \n class GithubProvider {\n +is_supported(feature)\n +gfm_markdown support\n }\n \n class GitlabProvider {\n +is_supported(feature)\n +gfm_markdown support\n }\n \n class BitbucketServerProvider {\n +get_diff_code()\n +publish_code_suggestion()\n }\n \n GitProvider <|-- GithubProvider\n GitProvider <|-- GitlabProvider\n GitProvider <|-- BitbucketServerProvider\n```\n\n### 4.2 平台特性差异处理\n\n不同平台对 Markdown 和代码建议的支持程度不同，系统通过 `is_supported()` 方法进行特性检测：\n\n| 平台 | GFM Markdown | 多行代码建议 | 评论编辑 |\n|------|--------------|--------------|----------|\n| GitHub | ✅ | ✅ | ✅ |\n| GitLab | ✅ | ✅ | ✅ |\n| Bitbucket Server | ⚠️ 部分 | ❌ | ⚠️ 受限 |\n\n资料来源：[pr_agent/tools/pr_description.py:20-40]()\n\n### 4.3 代码建议发布差异\n\n对于不支持多行建议的平台（如 Bitbucket），系统会自动降级处理：\n\n```python\n# Bitbucket 不支持多行建议，降级为代码块\nbody = body.replace(\"```suggestion\", \"```\")\n```\n\n资料来源：[pr_agent/git_providers/bitbucket_server_provider.py:50-80]()\n\n## 5. 配置系统\n\n### 5.1 配置加载架构\n\n配置系统支持多层次的配置覆盖：\n\n```mermaid\ngraph TD\n subgraph 配置源\n ENV[环境变量]\n TOML[配置文件
.pr_agent.toml]\n CLI[命令行参数]\n end\n \n subgraph 加载顺序\n O1[环境变量]\n O2[配置文件]\n O3[命令行参数]\n end\n \n O1 --> RESULT[最终配置]\n O2 --> RESULT\n O3 --> RESULT\n```\n\n### 5.2 配置节结构\n\n| 配置节 | 功能模块 | 主要配置项 |\n|--------|----------|------------|\n| `pr_description` | PR 描述 | `enable_help_comment`, `enable_description_markers` |\n| `pr_reviewer` | 代码审查 | 审查规则、标签配置 |\n| `pr_code_suggestions` | 代码建议 | 评分阈值、建议数量限制 |\n| `config` | 全局配置 | `output_relevant_configurations` |\n\n资料来源：[pr_agent/tools/pr_config.py:1-50]()\n\n### 5.3 配置输出展示\n\n系统支持将相关配置以 Markdown 格式输出到 PR 评论中：\n\n```yaml\n[config]\nkey: value\n\n[pr_description]\nenable_help_comment: true\n```\n\n## 6. 工具函数库\n\n`algo/utils.py` 提供了通用的工具函数支持：\n\n| 函数 | 功能 | 应用场景 |\n|------|------|----------|\n| `parse_code_suggestion()` | 解析代码建议字典为 Markdown | 代码建议输出 |\n| `show_relevant_configurations()` | 生成配置展示表格 | 配置工具 |\n| `extract_relevant_lines_str()` | 提取文件指定行范围内容 | 代码审查 |\n| `string_to_uniform_number()` | 字符串转均匀分布数值 | 随机选择逻辑 |\n\n### 6.1 代码建议解析\n\n代码建议解析支持两种输出格式：\n\n| 格式 | 触发条件 | 特点 |\n|------|----------|------|\n| 表格格式 | `gfm_supported=True` 且包含 `relevant_line` | 紧凑、易读 |\n| 列表格式 | 其他情况 | 兼容性更强 |\n\n资料来源：[pr_agent/algo/utils.py:80-150]()\n\n## 7. 部署架构\n\n### 7.1 支持的部署方式\n\n根据 README.md，PR-Agent 支持多种部署方式：\n\n| 部署方式 | 推荐场景 | 配置复杂度 |\n|----------|----------|------------|\n| GitHub Action | 自动化 PR 处理 | 低 |\n| CLI 本地运行 | 开发和测试 | 中 |\n| Docker 容器 | 定制化部署 | 中 |\n| API 服务 | 集成到现有系统 | 高 |\n\n资料来源：[README.md:1-100]()\n\n### 7.2 环境变量配置\n\n| 环境变量 | 必填 | 说明 |\n|----------|------|------|\n| `OPENAI_KEY` | 是 | LLM API 密钥 |\n| `GITHUB_TOKEN` | 是 | GitHub 访问令牌 |\n| `GITLAB_TOKEN` | 否 | GitLab 访问令牌 |\n| `BITBUCKET_TOKEN` | 否 | Bitbucket 访问令牌 |\n\n## 8. 数据流向\n\n```mermaid\ngraph LR\n subgraph 外部输入\n PR[Pull Request Event]\n CMD[命令行指令]\n end\n \n subgraph 处理流程\n PARSE[事件解析]\n LOAD[配置加载]\n FETCH[代码获取]\n ANALYZE[LLM 分析]\n FORMAT[结果格式化]\n end\n \n subgraph 输出\n COMMENT[PR 评论]\n UPDATE[PR 更新]\n LOG[日志输出]\n end\n \n PR --> PARSE\n CMD --> PARSE\n PARSE --> LOAD\n LOAD --> FETCH\n FETCH --> ANALYZE\n ANALYZE --> FORMAT\n FORMAT --> COMMENT\n FORMAT --> UPDATE\n FORMAT --> LOG\n```\n\n## 9. 安全性考虑\n\n根据 AGENTS.md 的安全指南：\n\n- **密钥管理**：所有密钥必须通过环境变量注入，禁止硬编码\n- **权限控制**：操作前需确认工作目录和文件权限\n- **外部调用**：本地构建和外部测试需要提前协调\n- **敏感信息**：禁止提交缓存的凭证、API 密钥或覆盖率报告\n\n## 10. 扩展指南\n\n### 10.1 添加新平台支持\n\n要添加新的 Git Provider，需要：\n\n1. 继承 `GitProvider` 基类\n2. 实现 `is_supported()` 方法声明平台特性\n3. 在 `git_providers/__init__.py` 中注册\n4. 处理平台特定的格式差异\n\n### 10.2 添加新工具\n\n新工具的创建流程：\n\n1. 在 `pr_agent/tools/` 目录下创建新模块\n2. 实现核心处理逻辑\n3. 在 `HelpMessage` 中添加使用指南\n4. 在 Agent 调度器中注册命令\n\n## 11. 相关文档\n\n- [PR-Agent 官方文档](https://qodo-merge-docs.qodo.ai/usage-guide/)\n- [工具使用指南](https://pr-agent-docs.codium.ai/tools/)\n- [配置文件参考](https://pr-agent-docs.codium.ai/usage-guide/configuration_options/)\n\n---\n\n\n\n## AI 模型集成\n\n### 相关页面\n\n相关主题：[系统架构](#system_architecture), [配置管理](#configuration)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [pr_agent/algo/ai_handlers/base_ai_handler.py](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/algo/ai_handlers/base_ai_handler.py)\n- [pr_agent/algo/ai_handlers/openai_ai_handler.py](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/algo/ai_handlers/openai_ai_handler.py)\n- [pr_agent/algo/ai_handlers/litellm_ai_handler.py](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/algo/ai_handlers/litellm_ai_handler.py)\n- [pr_agent/algo/ai_handlers/litellm_helpers.py](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/algo/ai_handlers/litellm_helpers.py)\n- [pr_agent/algo/token_handler.py](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/algo/token_handler.py)\n
\n\n# AI 模型集成\n\n## 概述\n\nPR-Agent 的 AI 模型集成模块负责管理与大语言模型的通信，是整个工具链的核心基础设施。该模块通过抽象化的 Handler 架构，支持多种 AI 服务提供商（OpenAI、Anthropic、Azure 等），并提供统一的接口供各个工具（describe、review、improve 等）调用。\n\n## 架构设计\n\n### 模块位置\n\n```\npr_agent/algo/ai_handlers/\n├── base_ai_handler.py # 基础抽象类\n├── openai_ai_handler.py # OpenAI 具体实现\n├── litellm_ai_handler.py # LiteLLM 统一接口实现\n└── litellm_helpers.py # LiteLLM 辅助函数\n```\n\n### 核心组件\n\n#### 1. BaseAIHandler（基础处理器）\n\n所有 AI 处理器必须继承的基础抽象类，定义了标准接口规范。主要职责包括：\n\n- 定义 `do_complete` 和 `do_complete_streaming` 抽象方法\n- 提供统一的错误处理机制\n- 实现请求重试逻辑\n- 管理超时配置\n\n#### 2. OpenAIHandler（OpenAI 原生实现）\n\n针对 OpenAI API 的专用处理器，支持：\n\n- 标准 Chat Completion API\n- 函数调用（Function Calling）\n- JSON 模式响应\n- 流式输出\n\n#### 3. LiteLLMHandler（统一接口实现）\n\n通过 [LiteLLM](https://github.com/BerriAI/litellm) 库实现的统一处理器，支持：\n\n| 提供商 | 支持模型 |\n|--------|----------|\n| OpenAI | GPT-3.5, GPT-4, GPT-4-Turbo |\n| Anthropic | Claude 2, Claude 3 |\n| Azure | Azure OpenAI Service |\n| Google | Gemini Pro |\n| AWS | Bedrock 系列 |\n\n## Token 管理\n\n`token_handler.py` 模块负责管理 Token 使用量和成本控制。\n\n### 核心功能\n\n```python\n# Token 计数与限制检查\n- 计算请求和响应的 Token 数量\n- 估算处理成本\n- 防止超出上下文窗口限制\n```\n\n### 上下文窗口管理\n\n系统会根据模型的最大上下文长度自动进行分块处理，确保长文本能够正确处理：\n\n```\npr_agent/algo/token_handler.py:1-50\n```\n\n## 工作流程\n\n```mermaid\ngraph TD\n A[工具模块
describe/review/improve] --> B[调用 AI Handler]\n B --> C{选择 Provider}\n C -->|OpenAI| D[OpenAIHandler]\n C -->|LiteLLM| E[LiteLLMHandler]\n D --> F[API 请求]\n E --> G[LiteLLM 路由]\n G --> H[目标 LLM API]\n F --> I[Token 计算]\n H --> I\n I --> J[响应解析]\n J --> K[返回结果给工具]\n```\n\n## 配置管理\n\nAI 模型通过配置文件进行管理，主要配置项位于 `pr_agent/settings/configuration.toml`。\n\n### 关键配置参数\n\n| 配置项 | 说明 | 默认值 |\n|--------|------|--------|\n| `model` | 使用的模型名称 | `gpt-4` |\n| `temperature` | 生成温度参数 | `0.2` |\n| `max_tokens` | 最大输出 Token 数 | `8000` |\n| `api_key` | API 密钥（环境变量） | - |\n\n### 环境变量配置\n\n```bash\n# OpenAI\nexport OPENAI_KEY=sk-...\n\n# Anthropic (通过 LiteLLM)\nexport ANTHROPIC_API_KEY=sk-ant-...\n\n# Azure OpenAI\nexport AZURE_API_KEY=...\nexport AZURE_API_BASE=...\n```\n\n资料来源：[README.md:1-50]()\n\n## 代码建议评分机制\n\nAI 模型在代码建议工具中承担双重职责：生成建议内容和评估建议质量。\n\n### 评分逻辑\n\n```python\n# pr_agent/tools/pr_code_suggestions.py:150-160\ndef get_score_str(self, score: int) -> str:\n th_high = get_settings().pr_code_suggestions.get('new_score_mechanism_th_high', 9)\n th_medium = get_settings().pr_code_suggestions.get('new_score_mechanism_th_medium', 7)\n if score >= th_high:\n return \"High\"\n elif score >= th_medium:\n return \"Medium\"\n else:\n return \"Low\"\n```\n\n### 评分阈值配置\n\n| 等级 | 阈值范围 | 说明 |\n|------|----------|------|\n| High | ≥ 9 | 高优先级建议 |\n| Medium | 7-8 | 中等优先级建议 |\n| Low | < 7 | 低优先级建议 |\n\n资料来源：[pr_agent/tools/pr_code_suggestions.py:145-165]()\n\n## 自反思机制\n\nAI 模型还支持自反思功能，用于改进生成结果的质量：\n\n```python\n# pr_agent/tools/pr_code_suggestions.py:170-190\nasync def self_reflect_on_suggestions(\n self,\n suggestion_list: List,\n patches_diff: str,\n model: str,\n prev_suggestions_str: str = \"\",\n dedicated_prompt: str = \"\"\n) -> str:\n```\n\n此功能允许模型：\n\n1. 回顾之前的建议列表\n2. 分析当前建议的改进空间\n3. 生成更高质量的输出\n\n## 使用示例\n\n### 1. 在工具中使用\n\n```python\nfrom pr_agent.algo.ai_handlers import get_ai_handler\n\nhandler = get_ai_handler(provider=\"openai\")\nresponse = await handler.do_complete(prompt=prompt, model=\"gpt-4\")\n```\n\n### 2. 切换模型提供商\n\n```bash\n# 使用 OpenAI\npr-agent --pr_url https://github.com/... review\n\n# 使用 LiteLLM (支持多种后端)\n# 通过配置设置使用的 provider\n```\n\n## 错误处理与重试\n\nAI Handler 实现了健壮的错误处理机制：\n\n- **网络错误**：自动重试（默认 3 次）\n- **速率限制**：指数退避策略\n- **Token 超限**：自动分块处理\n- **模型不可用**：优雅降级\n\n## 扩展新的 AI Provider\n\n如需添加新的 AI 提供商，只需：\n\n1. 创建新的 Handler 类继承 `BaseAIHandler`\n2. 实现 `do_complete` 方法\n3. 在 `get_ai_handler` 工厂函数中注册\n\n```python\n# 示例结构\nclass CustomAIHandler(BaseAIHandler):\n async def do_complete(self, prompt: str, **kwargs) -> str:\n # 实现自定义逻辑\n pass\n```\n\n## 相关文档\n\n- [PR-Agent 使用指南](https://pr-agent-docs.codium.ai/usage-guide/)\n- [配置选项详解](https://pr-agent-docs.codium.ai/usage-guide/configuration_options/)\n- [工具自动化配置](https://pr-agent-docs.codium.ai/usage-guide/automations_and_usage/)\n\n---\n\n\n\n## 工具概述\n\n### 相关页面\n\n相关主题：[代码审查工具 (Review)](#review_tool), [代码改进工具 (Improve)](#improve_tool)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [pr_agent/tools/pr_description.py](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/tools/pr_description.py)\n- [pr_agent/tools/pr_reviewer.py](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/tools/pr_reviewer.py)\n- [pr_agent/tools/pr_code_suggestions.py](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/tools/pr_code_suggestions.py)\n- [pr_agent/tools/pr_questions.py](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/tools/pr_questions.py)\n- [pr_agent/tools/pr_add_docs.py](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/tools/pr_add_docs.py)\n- [pr_agent/tools/pr_update_changelog.py](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/tools/pr_update_changelog.py)\n- [pr_agent/tools/pr_generate_labels.py](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/tools/pr_generate_labels.py)\n- [pr_agent/servers/help.py](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/servers/help.py)\n
\n\n# 工具概述\n\nPR-Agent 是一款开源的 AI 驱动工具，通过自动分析和生成内容来增强 Pull Request 的处理流程。该工具集提供了多种功能模块，涵盖 PR 描述生成、代码审查、代码建议、问答交互、文档更新和标签管理等方面。\n\n## 核心工具列表\n\nPR-Agent 提供了以下主要工具：\n\n| 工具名称 | 命令触发 | 功能描述 |\n|---------|---------|---------|\n| describe | `/describe` | 生成 PR 描述（标题、类型、摘要、walkthrough、标签） |\n| review | `/review` | 对 PR 进行全面代码审查 |\n| improve | `/improve` | 生成代码改进建议 |\n| ask | `/ask` | 回答关于 PR 的问题 |\n| help_docs | `/help_docs` | 基于文档回答问题 |\n| update_changelog | `/update_changelog` | 自动更新 CHANGELOG 文件 |\n| generate_labels | `/generate_labels` | 生成或建议 PR 标签 |\n\n## 工具架构图\n\n```mermaid\ngraph TD\n A[用户触发 PR-Agent] --> B{触发方式}\n B -->|自动触发| C[GitHub App 配置]\n B -->|手动触发| D[PR 评论命令]\n \n C --> E[PR 事件处理器]\n D --> E\n \n E --> F{工具选择}\n F -->|/describe| G[pr_description.py]\n F -->|/review| H[pr_reviewer.py]\n F -->|/improve| I[pr_code_suggestions.py]\n F -->|/ask| J[pr_questions.py]\n F -->|/help_docs| K[pr_add_docs.py]\n F -->|/update_changelog| L[pr_update_changelog.py]\n F -->|/generate_labels| M[pr_generate_labels.py]\n \n G --> N[Git Provider]\n H --> N\n I --> N\n J --> N\n K --> N\n L --> N\n M --> N\n \n N --> O[PR 评论/更新]\n```\n\n## describe 工具\n\n`describe` 工具负责扫描 PR 代码变更并生成完整的 PR 描述信息。\n\n### 功能特性\n\n- **标题生成**：自动生成符合格式要求的 PR 标题\n- **类型识别**：识别 PR 类型（如 Bug fix、Enhancement、Documentation 等）\n- **摘要编写**：生成代码变更的简要摘要\n- **walkthrough 导航**：提供变更的逐步讲解\n- **标签建议**：基于内容和自定义规则推荐标签\n\n### 配置选项\n\n工具支持通过 `pr_description` 配置段进行自定义：\n\n```toml\n[pr_description]\nextra_instructions=\"\"\"\\\n- The PR title should be in the format: ': '\n- The title should be short and concise (up to 10 words)\n\"\"\"\n```\n\n资料来源：[pr_agent/servers/help.py:46-52]()\n\n### Marker 机制\n\ndescribe 工具支持 Marker 机制，允许用户在 PR 描述中预留占位符：\n\n| Marker | 功能 |\n|--------|------|\n| `pr_agent:type` | PR 类型 |\n| `pr_agent:summary` | PR 摘要 |\n| `pr_agent:walkthrough` | 变更讲解 |\n| `pr_agent:diagram` | 序列图（如果启用） |\n\n资料来源：[pr_agent/servers/help.py:46-60]()\n\n## review 工具\n\n`review` 工具对 PR 进行全面的代码审查，分析代码质量、潜在问题和改进建议。\n\n### 调用方式\n\n通过评论触发：\n```\n/review --pr_reviewer.some_config1=... --pr_reviewer.some_config2=...\n```\n\n通过配置文件：\n```toml\n[pr_reviewer]\nsome_config1=...\nsome_config2=...\n```\n\n资料来源：[pr_agent/servers/help.py:5-12]()\n\n## improve 工具\n\n`improve` 工具扫描 PR 代码变更，自动生成代码改进建议。\n\n### 功能特性\n\n- **代码建议生成**：针对代码质量问题提供改进建议\n- **评分机制**：每个建议带有重要性评分（High/Medium/Low）\n- **建议持久化**：支持跨提交保留历史建议记录\n- **可折叠展示**：通过 `<details>` 标签组织建议输出\n\n### 评分阈值配置\n\n```python\nth_high = get_settings().pr_code_suggestions.get('new_score_mechanism_th_high', 9)\nth_medium = get_settings().pr_code_suggestions.get('new_score_mechanism_th_medium', 7)\nif score >= th_high:\n return \"High\"\nelif score >= th_medium:\n return \"Medium\"\nelse:\n return \"Low\"\n```\n\n资料来源：[pr_agent/tools/pr_code_suggestions.py:67-75]()\n\n### 建议输出格式\n\n```html\n<details><summary>{suggestion_summary}</summary>\n\n___\n\n**{suggestion_content}**\n\n[{relevant_file} {range_str}]({code_snippet_link})\n\n{example_code}\n\n<details><summary>Suggestion importance[1-10]: {score}</summary>\n\nWhy: {score_why}\n\n</details>\n</details>\n```\n\n资料来源：[pr_agent/tools/pr_code_suggestions.py:180-200]()\n\n## ask 工具\n\n`ask` 工具基于 PR 代码变更回答用户问题。\n\n### 功能特性\n\n- **无状态问答**：每次问答独立，不保留对话历史\n- **上下文理解**：可分析整个 PR、特定代码行或相关图片\n- **灵活提问**：支持任意关于 PR 的问题\n\n### 调用方式\n\n```\n/ask \"这段代码为什么要这样实现？\"\n```\n\n资料来源：[pr_agent/servers/help.py:82-91]()\n\n## help_docs 工具\n\n`help_docs` 工具根据给定的文档路径回答问题，可查询本仓库或外部仓库的文档。\n\n### 调用方式\n\n```\n/help_docs \"...\"\n```\n\n资料来源：[pr_agent/servers/help.py:120-128]()\n\n## update_changelog 工具\n\n`update_changelog` 工具自动更新仓库的 CHANGELOG 文件，记录 PR 变更。\n\n## generate_labels 工具\n\n`generate_labels` 工具根据 PR 内容生成或建议标签。\n\n### 自定义标签支持\n\n用户可以在仓库的标签页面定义自定义标签：\n\n| 示例标签 | 含义 |\n|---------|------|\n| `Main topic:performance` | PR 主要涉及性能优化 |\n| `New endpoint` | 新增 API 端点 |\n| `SQL query` | 包含 SQL 查询变更 |\n| `Dockerfile changes` | Dockerfile 修改 |\n\n资料来源：[pr_agent/servers/help.py:66-76]()\n\n## 配置系统\n\n### 配置层级\n\nPR-Agent 采用多层级配置系统：\n\n1. **全局配置**：项目根目录的配置文件\n2. **工具级配置**：各工具独立的配置段\n3. **命令参数**：通过命令行直接传递的配置\n\n### 配置输出功能\n\n当启用 `output_relevant_configurations` 时，系统会在 PR 评论中输出相关配置：\n\n```python\nif get_settings().get('config', {}).get('output_relevant_configurations', False):\n pr_body += show_relevant_configurations(relevant_section='pr_description')\n```\n\n资料来源：[pr_agent/tools/pr_description.py:30-33]()\n\n## 自动化触发\n\n### GitHub App 自动触发\n\n工具可配置为在特定事件发生时自动运行：\n\n```toml\npr_commands = [\"/describe\", ...]\n```\n\n默认情况下，describe 工具会在新 PR 打开时自动运行。\n\n### Marker 模式\n\n通过配置启用 Marker 模式：\n\n```toml\npr_commands = [\"/describe --pr_description.use_description_markers=true\", ...]\n```\n\n此模式下，工具仅替换 PR 描述中的 marker，不会完全重写描述。\n\n## 输出格式化\n\n### GFM 支持检测\n\n工具根据 Git Provider 类型决定输出格式：\n\n```python\nif self.git_provider.is_supported(\"gfm_markdown\"):\n # 使用 HTML 格式增强展示\n pr_body += '<table>...'\nelse: # GitLab\n # 使用 Markdown 标准格式\n pr_body += f\"### {emoji} {key_nice}: {value}\\n\\n\"\n```\n\n资料来源：[pr_agent/algo/utils.py:95-105]()\n\n### 可折叠文件列表\n\n对于包含多个文件的变更，系统使用 `<details>` 标签提供可折叠视图：\n\n```html\n<td><details><summary>{len(list_tuples)} files</summary><table>\n```\n\n资料来源：[pr_agent/tools/pr_description.py:85-88]()\n\n## 工具交互流程\n\n```mermaid\nsequenceDiagram\n participant U as 用户\n participant G as Git Provider\n participant T as 工具处理器\n participant AI as AI Model\n \n U->>G: 触发命令或自动事件\n G->>T: 接收 PR 上下文\n T->>AI: 发送分析请求\n AI->>T: 返回分析结果\n T->>T: 格式化输出内容\n T->>G: 生成评论/更新\n G->>U: 显示结果\n```\n\n## 错误处理与日志\n\n各工具实现了统一的错误处理机制：\n\n```python\ntry:\n # 处理逻辑\nexcept Exception as e:\n get_logger().error(f\"Error processing pr files to markdown {self.pr_id}: {str(e)}\")\n pass\n```\n\n资料来源：[pr_agent/tools/pr_description.py:98-101]()\n\n## 相关文档\n\n- [Describe 工具使用指南](https://pr-agent-docs.codium.ai/tools/describe/)\n- [Review 工具使用指南](https://pr-agent-docs.codium.ai/tools/review/)\n- [Improve 工具使用指南](https://pr-agent-docs.codium.ai/tools/improve/)\n- [Ask 工具使用指南](https://pr-agent-docs.codium.ai/tools/ask/)\n- [Help Docs 工具使用指南](https://pr-agent-docs.codium.ai/tools/help_docs/)\n- [配置选项文档](https://pr-agent-docs.codium.ai/usage-guide/configuration_options/)\n\n---\n\n<a id='review_tool'></a>\n\n## 代码审查工具 (Review)\n\n### 相关页面\n\n相关主题：[工具概述](#tools_overview), [代码改进工具 (Improve)](#improve_tool)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [pr_agent/tools/pr_reviewer.py](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/tools/pr_reviewer.py)\n- [pr_agent/settings/pr_reviewer_prompts.toml](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/settings/pr_reviewer_prompts.toml)\n- [pr_agent/settings/configuration.toml](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/settings/configuration.toml)\n- [pr_agent/servers/help.py](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/servers/help.py)\n- [pr_agent/algo/utils.py](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/algo/utils.py)\n</details>\n\n# 代码审查工具 (Review)\n\n## 概述\n\n代码审查工具（Review）是PR Agent的核心功能之一，用于对Pull Request进行全面的代码质量分析。该工具能够自动扫描PR代码变更，识别潜在问题并提供改进建议。审查工具可以自动触发（当新PR打开时），也可以通过手动评论触发。\n\n## 工作原理\n\n```mermaid\ngraph TD\n A[PR打开/手动触发] --> B[代码变更分析]\n B --> C[多维度审查]\n C --> D[问题识别]\n D --> E[审查报告生成]\n E --> F[PR评论输出]\n \n C --> C1[安全性检查]\n C --> C2[可维护性评估]\n C --> C3[代码质量分析]\n C --> C4[测试覆盖检查]\n```\n\n## 触发方式\n\n### 自动触发\n\n通过GitHub App配置，可在每次新PR打开时自动运行审查工具：\n\n```\npr_commands = [\"/review\", ...]\n```\n\n### 手动触发\n\n通过在PR评论中输入命令触发：\n\n```\n/review --pr_reviewer.some_config1=... --pr_reviewer.some_config2=...\n```\n\n## 配置选项\n\n代码审查工具支持丰富的配置选项，通过`pr_reviewer`配置节进行管理：\n\n### 通用配置\n\n| 配置项 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| `enable_help_comment` | bool | true | 是否在PR中添加帮助提示 |\n| `enable_heuristics` | bool | true | 是否启用启发式分析 |\n| `enable_inline_features` | bool | true | 是否启用内联功能 |\n| `review_simple_summary` | bool | false | 是否生成简化摘要 |\n\n### 审查维度配置\n\n| 配置项 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| `enable_security` | bool | true | 启用安全审查 |\n| `enable_pr_testing` | bool | false | 启用PR测试 |\n| `enable_problematic_section_labels` | bool | true | 启用问题标签 |\n| `enable_review_effort_estimation` | bool | true | 启用审查工作量估算 |\n\n### 输出格式配置\n\n| 配置项 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| `extra_instructions` | str | \"\" | 额外的审查指令 |\n| `include_generated_by` | bool | true | 是否包含生成者标记 |\n\n## 审查报告结构\n\n代码审查工具生成的报告包含以下核心部分：\n\n### 1. 安全性问题\n\n识别代码中的安全漏洞，包括：\n- SQL注入风险\n- XSS跨站脚本攻击\n- 敏感信息泄露\n- 认证/授权缺陷\n\n### 2. 代码质量问题\n\n- 命名规范检查\n- 代码复杂度分析\n- 重复代码检测\n- 代码风格一致性\n\n### 3. 可维护性评估\n\n- 模块耦合度分析\n- 依赖关系检查\n- 技术债务识别\n\n### 4. 测试覆盖\n\n- 单元测试覆盖情况\n- 集成测试完整性\n- 测试质量评估\n\n## 使用示例\n\n### 基本使用\n\n```bash\n/review\n```\n\n### 启用特定审查维度\n\n```bash\n/review --pr_reviewer.enable_security=true --pr_reviewer.enable_pr_testing=true\n```\n\n### 自定义审查指令\n\n```bash\n/review --pr_reviewer.extra_instructions=\"重点关注支付相关代码的安全性\"\n```\n\n### 配置文件方式\n\n```toml\n[pr_reviewer]\nenable_security = true\nenable_pr_testing = false\nextra_instructions = \"\"\"\n- 优先检查数据验证逻辑\n- 关注错误处理完整性\n\"\"\"\n```\n\n## 与其他工具的集成\n\n```mermaid\ngraph LR\n A[Review工具] --> B[Describe工具]\n A --> C[Improve工具]\n A --> D[Test工具]\n \n B --> E[PR描述增强]\n C --> F[代码建议]\n D --> G[测试生成]\n```\n\n代码审查工具与PR Agent的其他工具紧密协作：\n\n- **Describe**：审查结果可作为PR描述生成的输入\n- **Improve**：识别的代码问题可自动生成改进建议\n- **Test**：检测到的代码路径可触发相关测试生成\n\n## 审查结果展示\n\n审查结果以Markdown格式输出到PR评论，支持：\n\n- 可折叠的详细信息区域\n- 代码高亮的引用\n- 问题严重程度标签\n- 相关文件链接\n\n## 相关源码\n\n核心实现位于 `pr_agent/tools/pr_reviewer.py`，使用 `pr_agent/settings/pr_reviewer_prompts.toml` 中定义的提示模板进行代码分析。\n\n## 参考资料\n\n- 官方文档：https://pr-agent-docs.codium.ai/tools/review/\n- 配置文件：https://github.com/Codium-ai/pr-agent/blob/main/pr_agent/settings/configuration.toml\n\n---\n\n<a id='improve_tool'></a>\n\n## 代码改进工具 (Improve)\n\n### 相关页面\n\n相关主题：[工具概述](#tools_overview), [代码审查工具 (Review)](#review_tool)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [pr_agent/tools/pr_code_suggestions.py](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/tools/pr_code_suggestions.py)\n- [pr_agent/servers/help.py](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/servers/help.py)\n- [pr_agent/algo/utils.py](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/algo/utils.py)\n- [pr_agent/tools/pr_config.py](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/tools/pr_config.py)\n- [AGENTS.md](https://github.com/The-PR-Agent/pr-agent/blob/main/AGENTS.md)\n</details>\n\n# 代码改进工具 (Improve)\n\n## 概述\n\n`improve` 是 PR-Agent 项目中的一个核心工具，用于自动扫描 Pull Request 的代码变更并生成改进建议。该工具能够识别代码质量问题并提供具体的优化方案，帮助开发者提升代码质量。工具支持自动触发和手动调用两种模式，可通过评论指令或 GitHub App 配置来使用。\n\n## 核心功能\n\n### 自动化代码扫描\n\nimprove 工具在每次 PR 变更时自动执行代码分析，检测潜在的改进点：\n\n- 识别代码可读性问题\n- 发现性能优化机会\n- 检测最佳实践违规\n- 建议更安全的实现方式\n\n### 评分机制\n\n工具为每个建议分配优先级评分，基于配置的门限值分为三个等级：\n\n| 评分等级 | 高优先级阈值 | 中优先级阈值 | 说明 |\n|---------|------------|------------|------|\n| High（高）| ≥9 | ≥7 | 需要立即关注的重要改进 |\n| Medium（中）| ≥7 | - | 建议考虑的中等优先级改进 |\n| Low（低）| <7 | <7 | 可选的性能或风格改进 |\n\n相关源码：`pr_agent/tools/pr_code_suggestions.py:代码建议生成逻辑`\n\n### 自我反思机制\n\nimprove 工具包含 `self_reflect_on_suggestions` 方法，用于对生成的建议进行二次验证和改进：\n\n```python\nasync def self_reflect_on_suggestions(\n suggestion_list: List,\n patches_diff: str,\n model: str,\n prev_suggestions_str: str = \"\",\n dedicated_prompt: str = \"\"\n) -> str:\n```\n\n该方法接收原始建议列表、补丁差异、模型名称和历史建议，通过反思机制提升建议的质量和相关性。\n\n## 使用方式\n\n### 触发方式\n\n#### 自动触发\n\nimprove 工具可配置为在每次 PR 打开时自动运行。通过 GitHub App 的自动化配置实现，无需用户手动干预。\n\n#### 手动调用\n\n在 PR 评论中输入以下指令触发：\n\n```\n/improve\n```\n\n### 配置参数\n\nimprove 工具通过 `pr_code_suggestions` 配置节进行设置。支持以下配置方式：\n\n#### 评论指令配置\n\n```\n/improve --pr_code_suggestions.some_config1=... --pr_code_suggestions.some_config2=...\n```\n\n#### 配置文件配置\n\n```yaml\n[pr_code_suggestions]\nsome_config1=...\nsome_config2=...\n```\n\n配置文件路径：`pr_agent/settings/configuration.toml` 中的 `pr_code_suggestions` 部分。\n\n## 架构设计\n\n### 工作流程\n\n```mermaid\ngraph TD\n A[PR 代码变更] --> B[代码扫描模块]\n B --> C{分析引擎}\n C --> D[生成建议列表]\n D --> E[自我反思验证]\n E --> F[评分排序]\n F --> G[格式化输出]\n G --> H[发布到 PR 评论]\n H --> I[持久化历史记录]\n```\n\n### 组件结构\n\n| 组件 | 职责 | 源码位置 |\n|------|------|---------|\n| CodeSuggestions | 主处理类，协调整个流程 | `pr_agent/tools/pr_code_suggestions.py` |\n| 提示生成器 | 构建 LLM 提示词 | `pr_code_suggestions_prompts.toml` |\n| 反思模块 | 验证和改进建议质量 | `pr_code_suggestions_reflect_prompts.toml` |\n| 评分引擎 | 计算建议优先级 | `get_score_str()` 方法 |\n| 输出格式化 | 生成 Markdown 输出 | `pr_agent/algo/utils.py` |\n\n## 输出格式\n\n### 建议展示结构\n\n每个代码建议以折叠详情块形式展示：\n\n```markdown\n<details><summary>建议摘要</summary>\n\n___\n**建议内容描述**\n\n[相关文件 范围](代码链接)\n\n```代码示例\n```\n\n<details><summary>建议重要性评分</summary>\n\nWhy: 评分理由说明\n\n</details>\n\n</details>\n```\n\n### 评分显示\n\n建议以表格形式组织，包含文件变更和评分信息：\n\n```html\n<tr>\n <td>建议详情</td>\n <td align=center>High/Medium/Low</td>\n</tr>\n```\n\n## 配置选项\n\n### 常用配置项\n\n| 配置项 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| enable_help_comment | bool | true | 显示帮助信息 |\n| new_score_mechanism | bool | false | 启用新的评分机制 |\n| new_score_mechanism_th_high | int | 9 | 高优先级阈值 |\n| new_score_mechanism_th_medium | int | 7 | 中优先级阈值 |\n\n### 相关配置文档\n\n- 详细配置选项：配置文件参考\n- 自定义标签：自定义标签使用指南\n\n## 提示词模板\n\n### 主要提示模板\n\n工具使用 `pr_code_suggestions_prompts.toml` 中定义的提示词与 LLM 交互，模板包含：\n\n- 代码分析指令\n- 输出格式规范\n- 评估标准定义\n\n### 反思提示模板\n\n`pr_code_suggestions_reflect_prompts.toml` 提供反思验证的提示词，确保生成的建议：\n\n- 与代码实际变更相关\n- 避免冗余或矛盾\n- 具有实际可操作性\n\n## 持久化机制\n\nimprove 工具支持建议历史记录的持久化存储：\n\n1. **历史记录管理**：最多保留指定数量的历史建议\n2. **自动清理**：当历史记录超过上限时，移除最早的条目\n3. **状态追踪**：通过 ✅ 标记确认的建议\n\n持久化数据存储在 PR 评论中，包含当前建议和历史建议两部分。\n\n## 相关文档\n\n- 使用指南：improve 工具详细使用说明\n- 配置选项：完整的配置参数文档\n- 自动化配置：GitHub App 自动触发配置\n- 工具对比：与其他 PR-Agent 工具的配合使用\n\n## 参考资料\n\n- 核心实现：[pr_agent/tools/pr_code_suggestions.py](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/tools/pr_code_suggestions.py)\n- 使用指南：[pr_agent/servers/help.py](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/servers/help.py)\n- 输出格式化：[pr_agent/algo/utils.py](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/algo/utils.py)\n- 配置管理：[pr_agent/tools/pr_config.py](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/tools/pr_config.py)\n- 开发规范：[AGENTS.md](https://github.com/The-PR-Agent/pr-agent/blob/main/AGENTS.md)\n\n---\n\n<a id='git_providers'></a>\n\n## Git 平台集成\n\n### 相关页面\n\n相关主题：[系统架构](#system_architecture), [部署方式](#deployment)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [pr_agent/algo/utils.py](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/algo/utils.py)\n- [pr_agent/tools/pr_description.py](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/tools/pr_description.py)\n- [pr_agent/servers/help.py](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/servers/help.py)\n- [pr_agent/tools/pr_code_suggestions.py](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/tools/pr_code_suggestions.py)\n- [pr_agent/git_providers/git_provider.py](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/git_providers/git_provider.py)\n- [pr_agent/tools/pr_update_changelog.py](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/tools/pr_update_changelog.py)\n</details>\n\n# Git 平台集成\n\n## 概述\n\nPR-Agent 的 Git 平台集成模块是连接核心功能与各类代码托管平台的核心抽象层。该模块通过统一的接口设计，支持 GitHub、GitLab、Bitbucket、Azure DevOps、Gitea 和 Gerrit 等主流 Git 平台，实现了 PR-Agent 工具在不同平台间的无缝切换与功能一致性。\n\n集成架构的核心是抽象基类 `GitProvider`，它定义了所有平台提供商必须实现的标准接口方法，包括 PR 信息获取、评论发布、文件操作等关键功能。资料来源：[pr_agent/git_providers/git_provider.py:1-100]()\n\n## 架构设计\n\n### 核心抽象层\n\n```mermaid\ngraph TD\n A[PR-Agent 工具层] --> B[GitProvider 抽象基类]\n B --> C[GithubProvider]\n B --> D[GitlabProvider]\n B --> E[BitbucketProvider]\n B --> F[AzureDevOpsProvider]\n B --> G[GiteaProvider]\n B --> H[GerritProvider]\n \n C --> I[GitHub API]\n D --> J[GitLab API]\n E --> K[Bitbucket API]\n F --> L[Azure DevOps API]\n G --> M[Gitea API]\n H --> N[Gerrit Review API]\n```\n\n### 功能支持矩阵\n\n| 平台 | GFM Markdown | 自定义标签 | PR 图表 | 代码建议 | 自动评审 |\n|------|-------------|-----------|---------|---------|---------|\n| GitHub | ✅ | ✅ | ✅ | ✅ | ✅ |\n| GitLab | ✅ | ✅ | ✅ | ✅ | ✅ |\n| Bitbucket | 部分支持 | ❌ | ❌ | ✅ | ✅ |\n| Azure DevOps | ✅ | ✅ | ✅ | ✅ | ✅ |\n| Gitea | ✅ | ✅ | ✅ | ✅ | ✅ |\n| Gerrit | ❌ | ❌ | ❌ | ✅ | ✅ |\n\n资料来源：[pr_agent/tools/pr_description.py:1-50]()\n\n## GitProvider 基类接口\n\n### 核心方法定义\n\n`GitProvider` 基类定义了所有平台提供商必须实现的接口规范：\n\n| 方法 | 功能描述 | 返回类型 |\n|------|---------|---------|\n| `get_git_repo_url(issues_or_pr_url)` | 从 PR/Issue URL 提取仓库 URL | `str` |\n| `get_canonical_url_parts(repo_git_url, desired_branch)` | 获取平台特定的 URL 前缀和后缀 | `Tuple[str, str]` |\n| `clone(repo_url, dest, remove_dest_folder)` | 克隆仓库到指定目录 | `ScopedClonedRepo` |\n| `get_pr_description(full)` | 获取 PR 描述 | `str` |\n| `get_pr_branch()` | 获取当前 PR 的源分支 | `str` |\n| `publish_comment(body)` | 发布评论到 PR | `bool` |\n| `get_diff_files()` | 获取 PR 的文件变更列表 | `List[DiffFile]` |\n\n资料来源：[pr_agent/git_providers/git_provider.py:1-80]()\n\n### ScopedClonedRepo 临时克隆管理\n\n`ScopedClonedRepo` 是一个上下文管理器，用于安全地处理临时仓库克隆：\n\n```python\nclass ScopedClonedRepo(object):\n def __init__(self, dest_path: str, remove_on_exit: bool = True):\n self.path = dest_path\n self._should_remove = remove_on_exit\n```\n\n使用示例：\n\n```python\nwith TemporaryDirectory() as tmp_dir:\n returned_obj: GitProvider.ScopedClonedRepo = self.git_provider.clone(\n self.repo_url, tmp_dir, remove_dest_folder=False\n )\n print(returned_obj.path) # 使用返回的路径\n# 此时 returned_obj.path 随时可能被清理，不再使用\n```\n\n资料来源：[pr_agent/git_providers/git_provider.py:80-100]()\n\n## 平台特定实现\n\n### GitHub Provider\n\nGitHub Provider 是最完整的实现，支持所有 PR-Agent 功能特性，包括：\n\n- **GFM (GitHub Flavored Markdown)** 格式支持\n- PR 图表生成\n- 自定义标签处理\n- 自动化触发配置\n\nGitHub Provider 在处理帮助信息时的格式：\n\n```markdown\n> <details> <summary>Need help?</summary>\n> <li>Type <code>/help how to ...</code> in the comments thread</li>\n> <li>Check out the <a href=\"...\">documentation</a></li>\n> </details>\n```\n\n资料来源：[pr_agent/tools/pr_description.py:50-80]()\n\n### GitLab Provider\n\nGitLab Provider 适配 GitLab 的 Markdown 格式差异，帮助信息展示略有不同：\n\n```markdown\n<details><summary>Need help?</summary>\n- Type <code>/help how to ...</code> in the comments thread<br>\n- Check out the <a href=\"...\">documentation</a></li></details>\n```\n\n资料来源：[pr_agent/tools/pr_description.py:80-100]()\n\n### 其他平台\n\nBitbucket、Azure DevOps、Gitea 和 Gerrit Provider 均继承 `GitProvider` 基类，实现了各自平台 API 的适配层。各平台的差异主要体现在：\n\n1. **API 认证方式不同**\n2. **Markdown 渲染能力差异**\n3. **评审功能 API 支持程度**\n\n## Markdown 渲染适配\n\n### GFM 支持检测\n\n各工具通过 `is_supported(\"gfm_markdown\")` 方法检测平台是否支持 GitHub Flavored Markdown：\n\n```python\nenable_pr_diagram = (\n get_settings().pr_description.get(\"enable_pr_diagram\", False) \n and self.git_provider.is_supported(\"gfm_markdown\")\n)\n```\n\n资料来源：[pr_agent/tools/pr_description.py:100-150]()\n\n### 格式转换逻辑\n\n工具层根据平台能力自动选择合适的输出格式：\n\n```mermaid\ngraph LR\n A[数据生成] --> B{平台支持GFM?}\n B -->|是| C[使用details/summary标签]\n B -->|否| D[使用标准Markdown]\n C --> E[可折叠区域]\n D --> F[纯文本描述]\n```\n\nGFM 支持时的输出示例：\n\n```html\n<details><summary><strong>推荐审查重点区域</strong></summary>\n\n相关代码行...\n\n</details>\n```\n\n非 GFM 平台的标准输出：\n\n```markdown\n**推荐审查重点区域**\n\n相关代码行...\n```\n\n资料来源：[pr_agent/algo/utils.py:1-80]()\n\n## 文件变更处理\n\n### Diff 文件结构\n\n`get_diff_files()` 返回的文件变更对象包含以下属性：\n\n| 属性 | 描述 |\n|------|------|\n| `filename` | 文件路径 |\n| `patch` | 统一差异格式 |\n| `num_plus_lines` | 新增行数 |\n| `num_minus_lines` | 删除行数 |\n| `head_file` | 文件完整内容 |\n\n资料来源：[pr_agent/tools/pr_description.py:200-250]()\n\n### 相关代码行提取\n\n`extract_relevant_lines_str` 函数负责从变更中提取指定行号的代码：\n\n```python\ndef extract_relevant_lines_str(end_line, files, relevant_file, start_line, dedent=False) -> str:\n # 从 files 中查找目标文件\n # 优先使用 head_file 内容\n # 回退方案：从 patch 中提取\n```\n\n资料来源：[pr_agent/algo/utils.py:150-200]()\n\n### 变更统计展示\n\n在 PR 描述中展示变更统计：\n\n```python\nfor f in diff_files:\n if f.filename.lower().strip('/') == filename.lower().strip('/'):\n num_plus_lines = f.num_plus_lines\n num_minus_lines = f.num_minus_lines\n diff_plus_minus += f\"+{num_plus_lines}/-{num_minus_lines}\"\n```\n\n资料来源：[pr_agent/tools/pr_description.py:250-300]()\n\n## 代码建议集成\n\n### 建议输出格式\n\n代码建议通过 `<details>` 标签实现可折叠展示：\n\n```html\n<details><summary>建议摘要</summary>\n\n___\n\n**详细建议内容**\n\n[文件名 行号范围](链接)\n\n```代码示例\n```\n\n<details><summary>建议重要性[1-10]: 8</summary>\n\nWhy: 重要性说明...\n\n</details>\n\n</details>\n```\n\n资料来源：[pr_agent/tools/pr_code_suggestions.py:1-80]()\n\n### 评分机制\n\n代码建议采用三级评分体系：\n\n| 分数范围 | 等级标识 | 阈值配置 |\n|---------|---------|---------|\n| ≥ 9 | High | `new_score_mechanism_th_high` |\n| 7-8 | Medium | `new_score_mechanism_th_medium` |\n| < 7 | Low | 默认阈值 |\n\n资料来源：[pr_agent/tools/pr_code_suggestions.py:80-120]()\n\n## 配置与扩展\n\n### 平台配置项\n\n通过 `configuration.toml` 可配置的参数：\n\n| 配置项 | 描述 | 适用平台 |\n|--------|------|---------|\n| `git_provider` | 指定使用的 Git 平台 | 全局 |\n| `enable_gfm_markdown` | 启用 GFM 格式 | 全局 |\n| `collapsible_file_list_threshold` | 可折叠文件列表阈值 | GitHub, GitLab |\n\n资料来源：[pr_agent/servers/help.py:1-100]()\n\n### 新增平台支持\n\n要添加新的 Git 平台支持，需要：\n\n1. 创建新的 Provider 类继承 `GitProvider`\n2. 实现所有抽象方法\n3. 在工厂函数中注册新 Provider\n4. 添加平台特定格式适配逻辑\n\n## 安全注意事项\n\n- 所有敏感信息（如 API Token）通过环境变量注入，不硬编码于代码中\n- 平台 API 凭证通过 GitHub Actions Secrets 管理\n- 临时克隆的仓库路径使用完自动清理\n\n资料来源：[pr_agent/git_providers/git_provider.py:100-120]()\n\n## 相关文档\n\n- [PR Review 工具文档](https://pr-agent-docs.codium.ai/tools/review/)\n- [代码建议工具文档](https://pr-agent-docs.codium.ai/tools/improve/)\n- [PR 描述工具文档](https://pr-agent-docs.codium.ai/tools/describe/)\n- [配置文件指南](https://pr-agent-docs.codium.ai/usage-guide/configuration_options/)\n\n---\n\n<a id='deployment'></a>\n\n## 部署方式\n\n### 相关页面\n\n相关主题：[Git 平台集成](#git_providers), [配置管理](#configuration)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [action.yaml](https://github.com/The-PR-Agent/pr-agent/blob/main/action.yaml)\n- [Dockerfile.github_action](https://github.com/The-PR-Agent/pr-agent/blob/main/Dockerfile.github_action)\n- [docker/Dockerfile](https://github.com/The-PR-Agent/pr-agent/blob/main/docker/Dockerfile)\n- [pr_agent/servers/github_app.py](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/servers/github_app.py)\n- [pr_agent/servers/gitlab_webhook.py](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/servers/gitlab_webhook.py)\n- [pr_agent/servers/bitbucket_app.py](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/servers/bitbucket_app.py)\n- [pr_agent/cli.py](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/cli.py)\n</details>\n\n# 部署方式\n\nPR-Agent 是一个多平台支持的 PR 处理工具，支持多种部署方式以适应不同的开发环境和平台需求。本文详细介绍每种部署方式的核心架构、配置方法和使用场景。\n\n## 概述\n\nPR-Agent 的部署架构设计遵循灵活性原则，支持从自动化 GitHub Action 到本地 CLI 的多种运行模式。不同的部署方式针对不同的使用场景进行了优化，确保用户可以根据其基础设施选择最合适的方案。\n\n```mermaid\ngraph TD\n A[PR-Agent 部署方式] --> B[GitHub Action]\n A --> C[Docker 容器]\n A --> D[GitHub App]\n A --> E[GitLab Webhook]\n A --> F[Bitbucket App]\n A --> G[CLI 本地运行]\n \n B --> B1[自动触发]\n B --> B2[工作流配置]\n \n C --> C1[独立部署]\n C --> C2[自定义镜像]\n \n D --> D1[Webhook 接收]\n D --> D2[持久化服务]\n \n G --> G1[手动执行]\n G --> G2[本地开发]\n```\n\n## GitHub Action 部署\n\nGitHub Action 是推荐的部署方式，适合大多数自动化 PR 审查场景。通过在仓库中创建工作流文件，可以实现 PR 打开或更新时自动触发审查。\n\n### 工作流配置\n\n使用 GitHub Action 部署需要创建 `.github/workflows/pr-agent.yml` 文件：\n\n```yaml\nname: PR Agent\non:\n pull_request:\n types: [opened, synchronize]\njobs:\n pr_agent_job:\n runs-on: ubuntu-latest\n steps:\n - name: PR Agent action step\n uses: the-pr-agent/pr-agent@main\n env:\n OPENAI_KEY: ${{ secrets.OPENAI_KEY }}\n GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}\n```\n\n资料来源：[README.md]()\n\n### 环境变量配置\n\nGitHub Action 部署支持通过环境变量传递敏感信息和配置参数。常用配置项包括：\n\n| 环境变量 | 说明 | 必需 |\n|---------|------|-----|\n| `OPENAI_KEY` | OpenAI API 密钥 | 是 |\n| `GITHUB_TOKEN` | GitHub 访问令牌 | 是 |\n| `GITLAB_TOKEN` | GitLab 访问令牌（用于 GitLab 平台） | 否 |\n| `CONFIG.GIT_PROVIDER` | Git 提供商类型 | 否 |\n\n资料来源：[action.yaml]()\n\n### 触发机制\n\nGitHub Action 模式下，PR-Agent 支持以下触发类型：\n\n- `pull_request.opened` - PR 创建时\n- `pull_request.synchronize` - PR 更新时\n- `pull_request.edited` - PR 编辑时\n\n## Docker 容器部署\n\nDocker 部署提供了最大的灵活性，适合需要自定义运行环境或与其他服务集成的场景。\n\n### 镜像选择\n\n| 镜像版本 | 仓库 | 说明 |\n|---------|------|-----|\n| 0.34.2 及之后 | `pragent/pr-agent` | 官方新版镜像 |\n| 0.31 及之前 | `codiumai/pr-agent` | 旧版归档镜像（不再更新） |\n\n资料来源：[README.md]()\n\n### Dockerfile 结构\n\n主镜像的 Dockerfile 位于 `docker/Dockerfile`，定义了完整的运行时环境：\n\n```dockerfile\nFROM python:3.11-slim\n# 包含所有运行时依赖和 PR-Agent 核心代码\n```\n\nGitHub Action 专用 Dockerfile (`Dockerfile.github_action`) 针对 Action 环境进行了优化，体积更小。\n\n### 自定义镜像构建\n\n如需自定义配置，可以基于官方镜像构建：\n\n```dockerfile\nFROM pragent/pr-agent:latest\n# 添加自定义配置或插件\n```\n\n## GitHub App 部署\n\nGitHub App 部署方式适合需要持续运行服务并管理多个仓库的场景。通过创建 GitHub App，可以实现跨仓库的自动化 PR 处理。\n\n### 核心架构\n\n```mermaid\ngraph LR\n A[GitHub Webhook] --> B[pr_agent/servers/github_app.py]\n B --> C[事件处理器]\n C --> D[PR 工具执行]\n D --> E[评论/更新 PR]\n```\n\n### 服务启动\n\nGitHub App 服务器通过 `pr_agent/servers/github_app.py` 实现，核心启动流程包括：\n\n1. 注册 Webhook 端点\n2. 验证 GitHub App 凭证\n3. 监听 PR 相关事件\n4. 执行相应的 PR 工具\n5. 将结果发布到 PR 评论\n\n资料来源：[pr_agent/servers/github_app.py]()\n\n### 配置参数\n\n| 参数 | 说明 | 来源 |\n|-----|------|-----|\n| `WEBHOOK_SECRET` | Webhook 签名验证密钥 | 环境变量 |\n| `APP_ID` | GitHub App ID | 配置 |\n| `PRIORITY_TOKENS` | API 调用优先级配置 | 配置文件 |\n\n## GitLab Webhook 部署\n\n对于使用 GitLab 的团队，PR-Agent 提供了专门的 Webhook 集成方案。\n\n### 事件处理\n\n```mermaid\ngraph TD\n A[GitLab MR 事件] --> B[pr_agent/servers/gitlab_webhook.py]\n B --> C{事件类型判断}\n C -->|MR 打开/更新| D[MR Review 工具]\n C -->|代码更新| E[MR 描述工具]\n C -->|提问| F[MR Ask 工具]\n \n D --> G[发布评论]\n E --> G\n F --> G\n```\n\n### 特定功能\n\nGitLab 部署模式包含平台特定的 UI 元素，如帮助评论格式：\n\n```python\npr_body += (\"\\n\\n___\\n\\n<details><summary>Need help?</summary>- Type <code>/help how to ...</code> \"\n \"in the comments thread for any questions about PR-Agent usage.<br>- Check out the \"\n \"<a href='https://qodo-merge-docs.qodo.ai/usage-guide/'>documentation</a> for more information.</details>\")\n```\n\n资料来源：[pr_agent/tools/pr_description.py]()\n\n## Bitbucket App 部署\n\nBitbucket 平台支持通过专用 App 服务器实现，核心实现在 `pr_agent/servers/bitbucket_app.py`。\n\n### 与其他平台的差异\n\n| 特性 | GitHub | GitLab | Bitbucket |\n|-----|--------|--------|-----------|\n| Webhook 格式 | JSON | JSON | JSON |\n| 评论 API | REST | REST | REST |\n| 权限模型 | App Token | Access Token | OAuth |\n\n资料来源：[pr_agent/servers/bitbucket_app.py]()\n\n## CLI 本地运行\n\nCLI 方式适合本地开发测试或一次性执行场景。\n\n### 安装与配置\n\n```bash\npip install pr-agent\nexport OPENAI_KEY=your_key_here\npr-agent --pr_url https://github.com/owner/repo/pull/123 review\n```\n\n资料来源：[README.md]()\n\n### CLI 命令行接口\n\n`pr_agent/cli.py` 实现了命令行入口，支持以下操作模式：\n\n```mermaid\ngraph TD\n A[pr-agent CLI] --> B[--pr_url 参数]\n A --> C[--local_repo 参数]\n \n B --> D[远程 PR 处理]\n C --> E[本地仓库处理]\n \n D --> F[review]\n D --> G[describe]\n D --> H[improve]\n D --> I[ask]\n \n E --> F\n E --> G\n E --> H\n E --> I\n```\n\n### 可用命令\n\n| 命令 | 功能 |\n|-----|-----|\n| `review` | 生成 PR 审查意见 |\n| `describe` | 生成 PR 描述 |\n| `improve` | 提供代码改进建议 |\n| `ask` | 回答关于 PR 的问题 |\n\n资料来源：[pr_agent/cli.py]()\n\n## 部署方式对比\n\n### 适用场景矩阵\n\n| 部署方式 | 自动化程度 | 多仓库支持 | 配置复杂度 | 推荐场景 |\n|---------|-----------|-----------|-----------|---------|\n| GitHub Action | 高 | 否 | 低 | 单仓库自动化 |\n| Docker | 中 | 可配置 | 中 | 自定义环境 |\n| GitHub App | 高 | 是 | 中 | 组织级部署 |\n| GitLab Webhook | 高 | 可配置 | 中 | GitLab 用户 |\n| Bitbucket App | 高 | 是 | 中 | Bitbucket 用户 |\n| CLI | 低 | 否 | 低 | 本地测试开发 |\n\n### 性能考虑\n\n不同部署方式的性能特性：\n\n- **GitHub Action**：冷启动时间约 30-60 秒，适合非实时场景\n- **Docker 容器**：启动快，适合高频调用\n- **App 服务器**：常驻内存，响应最快，但需要维护基础设施\n\n## 配置管理\n\n无论采用哪种部署方式，PR-Agent 都通过统一的配置系统管理参数。\n\n### 配置文件位置\n\n| 部署方式 | 配置文件 |\n|---------|---------|\n| GitHub Action | 环境变量或 secrets |\n| Docker | 挂载配置文件或环境变量 |\n| App 服务器 | 配置文件或环境变量 |\n| CLI | `.pr_agent.toml` 或环境变量 |\n\n### 配置示例\n\n```yaml\n[pr_description]\nenable_help_comment = true\nenable_ai_tags = true\n\n[pr_reviewer]\nextra_instructions = \"\"\"\n- Focus on security issues\n- Check test coverage\n\"\"\"\n```\n\n资料来源：[pr_agent/algo/utils.py]()\n\n## 安全建议\n\n### 密钥管理\n\n| 部署方式 | 推荐密钥管理 |\n|---------|-------------|\n| GitHub Action | GitHub Secrets |\n| Docker | 环境变量或 Kubernetes Secrets |\n| App 服务器 | 外部密钥管理服务 |\n| CLI | 本地环境变量 |\n\n### 权限最小化\n\n- GitHub App 应仅请求必要的仓库权限\n- Access Token 应设置最小作用域\n- 定期轮换 API 密钥\n\n资料来源：[AGENTS.md]()\n\n## 故障排除\n\n### 常见问题\n\n| 问题 | 可能原因 | 解决方案 |\n|-----|---------|---------|\n| Action 无法触发 | Webhook 未正确配置 | 检查仓库 Webhook 设置 |\n| 权限错误 | Token 权限不足 | 更新 App 权限或 Token 作用域 |\n| 超时 | 模型响应慢 | 调整超时配置或优化提示词 |\n| 评论未发布 | GFM 不支持 | 检查平台 Markdown 支持 |\n\n### 日志调试\n\n启用调试日志查看详细执行信息：\n\n```yaml\n[config]\ndebug = true\n```\n\n## 升级与迁移\n\n### 版本 0.34.2+ 变化\n\nv0.34.2 起，官方镜像从 `codiumai/pr-agent` 迁移到 `pragent/pr-agent`。升级时需更新：\n\n```yaml\n# 旧版\nimage: pragent/pr-agent:v0.31\n\n# 新版\nimage: pragent/pr-agent:0.34.2\n```\n\n资料来源：[README.md]()\n\n## 总结\n\nPR-Agent 提供了丰富的部署方式选择，从简单的 GitHub Action 到完整的企业级 App 服务器，用户可以根据实际需求选择最适合的方案。建议大多数用户从 GitHub Action 开始，随着需求增长再考虑迁移到更复杂的部署架构。\n\n---\n\n<a id='configuration'></a>\n\n## 配置管理\n\n### 相关页面\n\n相关主题：[扩展与定制](#customization), [部署方式](#deployment)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [pr_agent/tools/pr_description.py](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/tools/pr_description.py)\n- [pr_agent/servers/help.py](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/servers/help.py)\n- [pr_agent/algo/utils.py](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/algo/utils.py)\n- [pr_agent/tools/pr_code_suggestions.py](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/tools/pr_code_suggestions.py)\n- [pr_agent/tools/pr_config.py](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/tools/pr_config.py)\n</details>\n\n# 配置管理\n\n## 概述\n\nPR Agent 的配置管理系统负责管理所有工具和功能的配置选项，包括 PR 描述生成、代码审查、代码建议等。该系统支持通过 TOML 配置文件、环境变量和命令行注释三种方式进行配置覆盖。\n\n资料来源：[pr_agent/tools/pr_description.py:1-50]()\n\n## 配置架构\n\n```mermaid\ngraph TD\n A[配置源] --> B[配置加载器]\n B --> C[get_settings 全局访问]\n C --> D[pr_description 配置段]\n C --> E[pr_code_suggestions 配置段]\n C --> F[pr_reviewer 配置段]\n D --> G[describe 工具]\n E --> H[improve 工具]\n F --> I[review 工具]\n```\n\n## 配置加载机制\n\n### 核心访问方式\n\n系统通过 `get_settings()` 函数提供全局配置访问接口，这是所有模块获取配置的首选方式。\n\n```python\nif get_settings().pr_description.enable_help_comment and self.git_provider.is_supported(\"gfm_markdown\"):\n # 配置访问示例\n```\n\n资料来源：[pr_agent/tools/pr_description.py:1-10]()\n\n### 配置输出功能\n\n`show_relevant_configurations` 函数用于将相关配置以可读的 Markdown 格式输出到 PR 评论中：\n\n```python\nif get_settings().get('config', {}).get('output_relevant_configurations', False):\n pr_body += show_relevant_configurations(relevant_section='pr_description')\n```\n\n资料来源：[pr_agent/tools/pr_description.py:1-10]()\n\n## 配置分段\n\nPR Agent 的配置按照功能模块划分为多个配置段：\n\n| 配置段 | 功能描述 | 触发工具 |\n|--------|----------|----------|\n| `pr_description` | PR 描述生成配置 | `/describe` |\n| `pr_code_suggestions` | 代码建议配置 | `/improve` |\n| `pr_reviewer` | 代码审查配置 | `/review` |\n| `config` | 全局通用配置 | 所有工具 |\n\n资料来源：[pr_agent/servers/help.py:1-50]()\n\n## 配置使用示例\n\n### 工具内访问配置\n\n在工具实现中，配置通过 `get_settings()` 访问特定配置段：\n\n```python\nth_high = get_settings().pr_code_suggestions.get('new_score_mechanism_th_high', 9)\nth_medium = get_settings().pr_code_suggestions.get('new_score_mechanism_th_medium', 7)\nif score >= th_high:\n return \"High\"\n```\n\n资料来源：[pr_agent/tools/pr_code_suggestions.py:1-50]()\n\n### 条件性配置检查\n\n部分功能支持通过配置开关启用或禁用：\n\n```python\nif get_settings().pr_description.enable_help_comment:\n # 启用帮助注释功能\n```\n\n资料来源：[pr_agent/tools/pr_description.py:1-10]()\n\n## 配置输出格式\n\n配置信息以 YAML 格式输出，便于用户查看和调试：\n\n```yaml\n[config]\noutput_relevant_configurations: false\n\n[pr_description]\nenable_help_comment: true\n```\n\n资料来源：[pr_agent/tools/pr_config.py:1-20]()\n\n### 格式化输出函数\n\n`format_settings_to_markdown` 函数负责将配置转换为 Markdown 格式：\n\n```python\nmarkdown_text += f\"**[{relevant_section}]**\\n```yaml\\n\\n\"\nfor key, value in get_settings().get(relevant_section, {}).items():\n if key in skip_keys:\n continue\n markdown_text += f\"{key}: {value}\\n\"\n```\n\n资料来源：[pr_agent/algo/utils.py:1-50]()\n\n## 配置继承与覆盖\n\n系统支持配置值的继承和覆盖机制：\n\n| 优先级 | 配置方式 | 示例 |\n|--------|----------|------|\n| 高 | 命令行注释 | `/describe --pr_description.use_description_markers=true` |\n| 中 | 配置文件 | `.pr_agent.toml` |\n| 低 | 默认值 | `get_settings().get('key', 'default')` |\n\n资料来源：[pr_agent/servers/help.py:1-50]()\n\n## 用户配置方式\n\n### 注释配置\n\n用户可以通过 PR 评论直接修改配置：\n\n```\n/describe --pr_description.some_config1=... --pr_description.some_config2=...\n```\n\n### 配置文件\n\n支持通过 TOML 配置文件集中管理：\n\n```toml\n[pr_description]\nsome_config1=...\nsome_config2=...\n```\n\n资料来源：[pr_agent/servers/help.py:1-50]()\n\n## 工具配置指南\n\n### describe 工具配置\n\n```toml\n[pr_description]\n# 控制描述标记功能\nuse_description_markers=false\n# 启用帮助注释\nenable_help_comment=true\n```\n\n资料来源：[pr_agent/servers/help.py:1-50]()\n\n### improve 工具配置\n\n```toml\n[pr_code_suggestions]\n# 代码建议相关配置\nsome_config1=...\nsome_config2=...\n```\n\n资料来源：[pr_agent/servers/help.py:1-50]()\n\n## 最佳实践\n\n### 配置命名规范\n\n- 配置键名使用小写字母和下划线\n- 配置段名称使用功能模块名称作为前缀\n- 示例：`pr_description.enable_help_comment`\n\n### 配置默认值\n\n始终为配置项提供合理的默认值：\n\n```python\nth_high = get_settings().pr_code_suggestions.get('new_score_mechanism_th_high', 9)\n```\n\n资料来源：[pr_agent/tools/pr_code_suggestions.py:1-50]()\n\n## 相关文件\n\n| 文件路径 | 功能描述 |\n|----------|----------|\n| `pr_agent/settings/configuration.toml` | 默认配置文件 |\n| `pr_agent/algo/utils.py` | 配置格式化工具 |\n| `pr_agent/tools/pr_config.py` | 配置显示工具 |\n\n## 总结\n\nPR Agent 的配置管理系统采用分层设计，通过 `get_settings()` 接口提供统一的配置访问。配置支持运行时修改，通过注释方式可以灵活调整工具行为，同时保留配置文件作为持久化配置方案。\n\n---\n\n<a id='customization'></a>\n\n## 扩展与定制\n\n### 相关页面\n\n相关主题：[配置管理](#configuration), [工具概述](#tools_overview)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [pr_agent/custom_merge_loader.py](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/custom_merge_loader.py)\n- [pr_agent/settings/custom_labels.toml](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/settings/custom_labels.toml)\n- [pr_agent/settings/ignore.toml](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/settings/ignore.toml)\n- [pr_agent/algo/file_filter.py](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/algo/file_filter.py)\n- [pr_agent/settings/pr_description_prompts.toml](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/settings/pr_description_prompts.toml)\n</details>\n\n# 扩展与定制\n\nPR-Agent 是一个高度可扩展的 Pull Request 处理工具，提供了丰富的定制能力，使开发者能够根据项目需求灵活配置工具行为。本文档详细介绍 PR-Agent 的扩展与定制机制，包括配置文件系统、自定义标签、文件过滤规则、自定义提示词等核心扩展点。\n\n## 架构概述\n\nPR-Agent 的扩展与定制系统采用模块化设计，核心扩展点包括配置加载器、自定义标签处理器、文件过滤器以及提示词模板系统。这种设计允许用户在不修改核心代码的情况下，自定义工具的各个方面，从标签分类到文件处理逻辑均可灵活调整。\n\n系统架构可以划分为以下几个主要层次：配置管理层负责加载和管理各类配置文件；扩展加载层处理自定义合并逻辑和插件机制；过滤处理层根据规则筛选文件；提示词生成层负责生成各类 AI 提示词。每一层都提供了相应的扩展接口，用户可以通过配置文件或代码扩展来定制行为。\n\n```mermaid\ngraph TD\n A[配置文件系统] --> B[配置加载器]\n A --> C[自定义标签系统]\n A --> D[忽略规则系统]\n B --> E[文件过滤器]\n E --> F[提示词生成器]\n C --> F\n D --> F\n G[扩展点注册] --> H[运行时加载]\n H --> B\n style A fill:#e1f5fe\n style F fill:#fff3e0\n```\n\n## 配置文件系统\n\n### 配置文件结构\n\nPR-Agent 使用 TOML 格式的配置文件，主要配置项集中在 `pr_agent/settings/configuration.toml` 文件中。该文件定义了所有工具的默认配置参数，包括 `pr_description`、`pr_code_suggestions`、`pr_reviewer` 等各个模块的配置选项。每个模块的配置都可以通过环境变量、配置文件或命令行参数进行覆盖。\n\n配置文件的组织结构采用分层设计，顶层配置包含通用设置，如模型选择、API 密钥等；各工具模块的专用配置则以子节的形式存在。例如，`pr_description` 节包含 `extra_instructions`、`enable_help_comment`、`enable_generated_files_label` 等配置项，这些配置项控制 PR 描述生成的具体行为。\n\n配置系统支持多种配置来源的优先级排序：命令行参数具有最高优先级，其次是环境变量，最后是配置文件中的默认值。这种设计确保了灵活性的同时，也保证了配置的一致性和可维护性。开发者可以通过修改配置文件来改变工具的默认行为，也可以为特定项目创建专属的配置覆盖。\n\n### 自定义配置加载\n\n自定义配置加载通过 `custom_merge_loader.py` 模块实现，该模块提供了一个可扩展的合并配置加载机制。当需要将多个配置源合并时，系统会按照预定义的优先级顺序加载各个配置项，并处理可能存在的冲突情况。合并策略支持深度合并，允许嵌套配置项的部分覆盖。\n\n```python\n# 配置合并加载示意\nclass ConfigMerger:\n def merge_configs(self, base_config, override_config):\n \"\"\"\n 深度合并配置项\n \"\"\"\n merged = base_config.copy()\n for key, value in override_config.items():\n if key in merged and isinstance(merged[key], dict) and isinstance(value, dict):\n merged[key] = self.merge_configs(merged[key], value)\n else:\n merged[key] = value\n return merged\n```\n\n配置加载器还支持动态配置重载，在某些场景下可能需要在运行时更新配置而不重启服务。通过监听配置文件的变化，系统可以自动检测并应用更新后的配置，实现热重载功能。这一特性对于需要频繁调整配置的生产环境特别有用。\n\n## 自定义标签系统\n\n### 标签配置格式\n\nPR-Agent 支持通过 `custom_labels.toml` 文件定义自定义标签，该文件位于 `pr_agent/settings/custom_labels.toml`。自定义标签允许项目根据自身需求定义 PR 分类标准，替代默认的通用标签（Bug fix、Tests、Enhancement、Documentation、Other）。标签配置采用简单的键值对格式，每个标签由标签名称和描述组成。\n\n默认标签配置提供了基础的 PR 类型分类，但在实际项目中，团队可能需要更细粒度的分类方式。自定义标签的定义格式为 `标签名 = \"描述文本\"`，系统会自动将这些自定义标签转换为 PR-Agent 可识别的标签格式。在生成 PR 描述时，工具会根据代码变更的内容自动匹配最合适的自定义标签。\n\n标签系统的设计考虑了向后兼容性，即使没有定义任何自定义标签，系统仍会使用默认标签集。此外，自定义标签可以随时添加或修改，工具会在下次运行时自动加载最新的标签配置。这种灵活性使得不同项目可以根据其领域和流程定义独特的标签体系。\n\n### 标签应用机制\n\n当 PR-Agent 处理 Pull Request 时，会分析代码变更的内容和模式，然后根据预设的标签定义进行分类。标签匹配算法会考虑文件路径、变更类型、代码模式等多个维度，以提高分类的准确性。用户还可以在提示词中指定标签的优先级顺序，确保最重要的标签类型优先被识别。\n\n标签应用还支持多标签场景，一个 PR 可以同时匹配多个标签。例如，一个同时包含性能优化和代码重构的 PR 可能会被标记为 \"Enhancement\" 和 \"Performance\"。这种多标签支持使得 PR 分类更加精确，能够更好地反映 PR 的完整内容。\n\n## 文件过滤与忽略规则\n\n### 忽略规则配置\n\n文件过滤机制由 `ignore.toml` 配置文件和 `file_filter.py` 模块共同实现。忽略规则允许用户指定哪些文件或目录应该被排除在分析之外，这对于大型项目特别重要，可以显著减少处理时间和避免噪音文件的干扰。忽略规则支持 glob 模式匹配，类似于 `.gitignore` 的语法。\n\n`ignore.toml` 文件定义了需要忽略的文件模式和目录列表。常见的忽略内容包括：依赖管理文件（如 `node_modules`、`vendor` 目录）、构建产物文件（如 `dist`、`build` 目录）、配置文件（如 IDE 配置）、大型二进制文件等。用户可以根据项目特点添加或修改这些规则。\n\n过滤规则按照优先级和范围进行组织，某些规则可能只对特定工具生效，而另一些规则则是全局性的。系统会按照规则定义的顺序进行匹配，第一个匹配的规则决定文件的处理方式。这种设计允许精细控制不同类型文件的处理策略。\n\n### 文件过滤器实现\n\n`file_filter.py` 模块是文件过滤的核心实现，提供了 `FileFilter` 类来处理文件路径的匹配逻辑。该模块导入了 TOML 配置文件并解析忽略规则，然后提供 `should_include` 方法来判断文件是否应该被包含在处理范围内。过滤器会检查文件路径是否匹配任何已定义的忽略模式，如果匹配则返回 False 表示忽略该文件。\n\n```python\n# 文件过滤器核心逻辑示意\ndef should_include(self, file_path: str) -> bool:\n \"\"\"\n 判断文件是否应该被包含在分析中\n \"\"\"\n for pattern in self.ignore_patterns:\n if self.matches_pattern(file_path, pattern):\n return False\n return True\n\ndef matches_pattern(self, file_path: str, pattern: str) -> bool:\n \"\"\"使用 glob 模式匹配\"\"\"\n # 实现包括精确匹配、前缀匹配、扩展名匹配等\n pass\n```\n\n文件过滤器还支持动态规则，即根据文件内容或元数据来决定是否忽略。例如，某些配置文件可能只在特定条件下需要分析。过滤器提供了扩展接口，允许开发者注册自定义的过滤函数，以满足更复杂的过滤需求。\n\n## 自定义提示词模板\n\n### 提示词配置结构\n\nPR-Agent 使用 TOML 格式的提示词模板文件来定义各种工具的 AI 提示词，其中 `pr_description_prompts.toml` 是最重要的配置文件之一。该文件定义了 PR 描述生成工具使用的所有提示词模板，包括标题生成、类型识别、总结撰写、详细说明等各个子任务的提示词。通过修改这些模板，用户可以定制工具生成 PR 描述的风格和内容重点。\n\n提示词模板采用参数化设计，允许在运行时插入动态内容。例如，模板中可能包含占位符如 `{pr_title}`、`{changed_files}` 等，系统会在实际生成时替换这些占位符为具体的 PR 信息。这种设计使得模板既易于阅读和维护，又能灵活适应不同的输入数据。\n\n模板系统还支持条件渲染，某些提示词内容可以根据配置或上下文条件选择性地包含或排除。这对于处理不同类型的 PR（如功能开发、缺陷修复、文档更新等）特别有用，可以为每种类型定义专门的处理逻辑。\n\n### 提示词扩展机制\n\n提示词扩展通过 `extra_instructions` 配置项实现，该配置项允许用户在不修改原始模板的情况下添加自定义指令。例如，用户可以在配置中添加如下内容来定制 PR 描述的生成风格：\n\n```toml\n[pr_description]\nextra_instructions = \"\"\"\n- PR 标题格式应为：'<PR类型>: <标题>'\n- 标题应简洁明了，最多 10 个单词\n- 总结部分应突出主要变更内容\n\"\"\"\n```\n\n`extra_instructions` 配置支持多行内容，可以使用 Markdown 格式来组织指令结构。这种设计使得提示词定制变得简单直观，无需深入了解模板引擎的工作原理。系统会在生成最终提示词时，将用户提供的额外指令追加到基础模板之后。\n\n## 工具配置选项\n\n### PR 描述工具配置\n\nPR 描述生成工具（`pr_description`）提供了丰富的配置选项，用于控制生成内容的各个方面。以下是主要配置项及其作用说明：\n\n| 配置项 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| `extra_instructions` | 字符串 | 空 | 额外的指令信息，用于定制生成行为 |\n| `enable_help_comment` | 布尔值 | true | 是否在 PR 描述中添加帮助提示 |\n| `enable_generated_files_label` | 布尔值 | true | 是否标记自动生成的文件 |\n| `use_description_markers` | 布尔值 | false | 是否使用标记替换模式 |\n| `publish_labels` | 布尔值 | true | 是否发布标签到 PR |\n| `publish_review_summary` | 布尔值 | true | 是否发布审查总结 |\n\n这些配置项可以通过命令行参数、配置文件或环境变量进行设置。配置项的设计遵循自解释原则，名称本身通常能够说明其功能。对于需要更精细控制的场景，可以组合使用多个配置项来实现所需的行为。\n\n### 代码建议工具配置\n\n代码建议工具（`pr_code_suggestions`）同样提供了详细的配置选项，用于控制代码改进建议的生成和展示方式。关键配置项包括建议的评分阈值、展示格式、是否启用自我反思等。评分阈值配置项 `new_score_mechanism_th_high` 和 `new_score_mechanism_th_medium` 用于定义高、中、低建议的分界线，帮助用户快速识别最重要的改进建议。\n\n建议的展示格式支持多种模式，包括表格形式、折叠面板形式等。用户可以根据所在平台的特性选择最适合的展示方式。自我反思机制允许工具在生成初始建议后进行二次分析，以提高建议的质量和准确性。\n\n## 扩展点与插件机制\n\n### 自定义合并加载器\n\n`custom_merge_loader.py` 模块是 PR-Agent 的核心扩展点之一，提供了自定义配置合并逻辑的加载机制。该模块定义了一个可扩展的加载器类，允许开发者注册自定义的配置处理函数或插件模块。通过这种机制，用户可以在不修改核心代码的情况下添加新的配置处理逻辑。\n\n加载器采用注册模式工作，开发者首先定义一个处理函数，然后将其注册到加载器实例中。注册时可以指定处理函数的优先级和作用范围，确保多个扩展能够协调工作。加载器会按照优先级顺序调用各个处理函数，并收集处理结果进行合并。\n\n这种设计模式的一个典型应用场景是：多团队共享同一个 PR-Agent 实例，但每个团队需要不同的配置策略。通过自定义合并加载器，可以实现基于团队或项目的配置隔离和覆盖，而无需维护多个独立的配置文件。\n\n### 扩展点注册表\n\n扩展点注册表维护了一个所有可用扩展点的中央索引，包括扩展点的名称、类型、描述和配置接口信息。开发者可以通过查询注册表来了解可用的扩展点，也可以注册新的扩展点供其他模块使用。注册表的实现采用了观察者模式，支持动态添加和移除扩展点。\n\n扩展点的定义包括以下几个关键属性：唯一标识符、类型分类、版本号、依赖声明和执行接口。版本号用于管理扩展点的演进，依赖声明确保扩展的正确加载顺序。执行接口定义了扩展点与主系统之间的交互方式，包括输入参数格式和返回值类型。\n\n## 配置优先级与合并策略\n\n### 优先级层级\n\nPR-Agent 的配置系统遵循明确的优先级层级，从高到低依次为：命令行参数、环境变量、运行时配置、配置文件、项目级配置、全局默认配置。这种层级设计确保了灵活性与一致性的平衡，用户可以根据需要选择最适合的配置方式。\n\n命令行参数适用于一次性调整或自动化脚本场景；环境变量适合容器化部署和持续集成环境；配置文件则是最常用的配置方式，适合大多数使用场景。项目级配置允许不同项目使用不同的配置集，而全局默认配置则提供了开箱即用的合理默认值。\n\n配置合并采用深度合并策略，对于嵌套的配置项，系统会递归地合并各层级的值。这意味着可以在高层级覆盖某个顶级配置项的同时，在低层级保持其他嵌套配置项的原始值。这种精细的控制能力对于复杂项目的配置管理至关重要。\n\n### 合并冲突处理\n\n当不同层级的配置出现冲突时，系统采用最后优先（Last-Write-Wins）的原则进行处理。具体实现中，系统会按照优先级从低到高依次处理各个配置源，后处理的配置源会覆盖先前的值。对于列表类型的配置项，默认行为是替换而非追加，除非特别配置为合并模式。\n\n某些配置项可能声明了特殊的合并规则，例如强制追加规则或智能合并规则。强制追加规则确保列表类型配置项的值会被追加而非替换，适用于标签列表、忽略模式列表等场景。智能合并规则则根据配置项的语义来决定合并策略，需要开发者正确声明配置项的类型和合并行为。\n\n## 最佳实践\n\n### 配置组织建议\n\n在组织 PR-Agent 配置时，推荐采用分层配置结构：全局配置文件存放通用设置，项目级配置文件存放特定于项目的设置，运行时配置用于动态调整。这种分层结构便于维护和版本控制，也能更好地支持多项目场景。\n\n建议将自定义标签定义和忽略规则单独存放，因为这些配置可能需要频繁调整。将提示词模板与业务逻辑配置分离，可以使模板更易于版本化和审阅。对于团队协作场景，应建立配置变更的评审流程，确保配置的合理性和一致性。\n\n### 性能优化考虑\n\n在配置大量忽略规则或复杂的自定义逻辑时，需要考虑性能影响。文件过滤操作在每次处理文件时都会被调用，因此过滤规则的效率直接影响工具的整体性能。建议使用简洁的 glob 模式而非复杂的正则表达式，避免在过滤逻辑中执行耗时的 I/O 操作。\n\n提示词模板的复杂度也会影响生成质量和响应时间。过于复杂的模板可能导致 AI 模型生成冗长或偏离主题的内容。建议定期审视和简化模板，移除不再使用的指令，保持模板的清晰和高效。对于高频使用的工具（如 PR 描述生成），尤其需要注意模板的优化。\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：The-PR-Agent/pr-agent\n\n摘要：发现 23 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：Publish linux/arm64 Docker image for github_app tag。\n\n## 1. 安装坑 · 来源证据：Publish linux/arm64 Docker image for github_app tag\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Publish linux/arm64 Docker image for github_app tag\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_8cb9e552d2e2452cbe958628f6e800b6 | https://github.com/The-PR-Agent/pr-agent/issues/2386 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 2. 安装坑 · 来源证据：[Bug] UnicodeDecodeError in gitea_provider.py when parsing binary files before extension filtering\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug] UnicodeDecodeError in gitea_provider.py when parsing binary files before extension filtering\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_52bd470b7b5e4be6858b290e41c93036 | https://github.com/The-PR-Agent/pr-agent/issues/2380 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 3. 安装坑 · 来源证据：v0.31\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.31\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ef0e5f5f982146d8bd002453b969c07f | https://github.com/The-PR-Agent/pr-agent/releases/tag/v0.31 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 4. 安装坑 · 来源证据：v0.34.2\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.34.2\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_4bc22335937e44c0b529ab84d1e69a60 | https://github.com/The-PR-Agent/pr-agent/releases/tag/v0.34.2 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 5. 配置坑 · 来源证据：AzureDevopsProvider.get_repo_settings drops chunks after the first, silently truncating .pr_agent.toml\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：AzureDevopsProvider.get_repo_settings drops chunks after the first, silently truncating .pr_agent.toml\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_4ee2a84ba307469b9b329a043a70a224 | https://github.com/The-PR-Agent/pr-agent/issues/2376 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 6. 配置坑 · 来源证据：Ticket context not scoped per PR in long-lived deployments — stale tickets leak between unrelated PRs\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Ticket context not scoped per PR in long-lived deployments — stale tickets leak between unrelated PRs\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_a9b90b0cfbbf4529b60d65f564f4592e | https://github.com/The-PR-Agent/pr-agent/issues/2383 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 7. 能力坑 · 来源证据：v0.34.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个能力理解相关的待验证问题：v0.34.1\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_eb46a134c8984cd8898e13f61602f165 | https://github.com/The-PR-Agent/pr-agent/releases/tag/v0.34.1 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 8. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:662766482 | https://github.com/The-PR-Agent/pr-agent | README/documentation is current enough for a first validation pass.\n\n## 9. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:662766482 | https://github.com/The-PR-Agent/pr-agent | last_activity_observed missing\n\n## 10. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:662766482 | https://github.com/The-PR-Agent/pr-agent | no_demo; severity=medium\n\n## 11. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：risks.safety_notes | github_repo:662766482 | https://github.com/The-PR-Agent/pr-agent | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 12. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:662766482 | https://github.com/The-PR-Agent/pr-agent | no_demo; severity=medium\n\n## 13. 安全/权限坑 · 来源证据：Bug + feature: `-i` (incremental review) crashes on Azure DevOps; needs full incremental support in AzureDevopsProvider\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Bug + feature: `-i` (incremental review) crashes on Azure DevOps; needs full incremental support in AzureDevopsProvider\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e65762126ba84855a8440bd9e5a685bb | https://github.com/The-PR-Agent/pr-agent/issues/2379 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 14. 安全/权限坑 · 来源证据：OSS build silently ignores best_practices.md (currently SaaS-only)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：OSS build silently ignores best_practices.md (currently SaaS-only)\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_f51f28cf40b14b7ca80598af4527661a | https://github.com/The-PR-Agent/pr-agent/issues/2377 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 15. 安全/权限坑 · 来源证据：feat: support agent skills for context-aware review guidance\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：feat: support agent skills for context-aware review guidance\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_59ad4ca55ca248f989c91ce40068cc6d | https://github.com/The-PR-Agent/pr-agent/issues/2384 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 16. 安全/权限坑 · 来源证据：litellm success/cost callbacks never fire from pr-agent's async run loop\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：litellm success/cost callbacks never fire from pr-agent's async run loop\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_42f0b36e0c434c939c49c91fc7ccb82a | https://github.com/The-PR-Agent/pr-agent/issues/2378 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 17. 安全/权限坑 · 来源证据：v0.29\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.29\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_fbfdef3db3f84afab5275f43224831e7 | https://github.com/The-PR-Agent/pr-agent/releases/tag/v0.29 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 18. 安全/权限坑 · 来源证据：v0.30\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.30\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ce6f886a0f6640eb8054f5119f22a126 | https://github.com/The-PR-Agent/pr-agent/releases/tag/v0.30 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 19. 安全/权限坑 · 来源证据：v0.32\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.32\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_b1dcd09b757642d08b7dc8d0e77c8b3f | https://github.com/The-PR-Agent/pr-agent/releases/tag/v0.32 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 20. 安全/权限坑 · 来源证据：v0.33\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.33\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_d138961299124bcfaa4cbc15b31c22df | https://github.com/The-PR-Agent/pr-agent/releases/tag/v0.33 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。\n\n## 21. 安全/权限坑 · 来源证据：v0.34\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.34\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_85169c37f8b4494baccd135014cbaffb | https://github.com/The-PR-Agent/pr-agent/releases/tag/v0.34 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。\n\n## 22. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:662766482 | https://github.com/The-PR-Agent/pr-agent | issue_or_pr_quality=unknown\n\n## 23. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:662766482 | https://github.com/The-PR-Agent/pr-agent | release_recency=unknown\n\n<!-- canonical_name: The-PR-Agent/pr-agent; human_manual_source: deepwiki_human_wiki -->\n", "markdown_key": "pr-agent", "pages": "draft", "source_refs": [ { "evidence_id": "github_repo:662766482", "kind": "repo", "supports_claim_ids": [ "claim_identity", "claim_distribution", "claim_capability" ], "url": "https://github.com/The-PR-Agent/pr-agent" }, { "evidence_id": "art_a8e355bcac8a4fbabe2b4be3d781cac3", "kind": "docs", "supports_claim_ids": [ "claim_identity", "claim_distribution", "claim_capability" ], "url": "https://github.com/The-PR-Agent/pr-agent#readme" } ], "summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。", "title": "pr-agent 说明书", "toc": [ "https://github.com/The-PR-Agent/pr-agent 项目说明书", "目录", "PR-Agent 简介", "概述", "核心功能模块", "架构设计", "核心工具详解", "配置系统", "Doramagic 踩坑日志" ] } }, "quality_gate": { "blocking_gaps": [], "category_confidence": "medium", "compile_status": "ready_for_review", "five_assets_present": true, "install_sandbox_verified": true, "missing_evidence": [], "next_action": "publish to Doramagic.ai project surfaces", "prompt_preview_boundary_ok": true, "publish_status": "publishable", "quick_start_verified": true, "repo_clone_verified": true, "repo_commit": "9ab2636f89952c69600dc2038d39f468de699fd0", "repo_inspection_error": null, "repo_inspection_files": [ "pyproject.toml", "README.md", "requirements.txt", "docs/mkdocs.yml", "docs/README.md", "docs/docs/summary.md", "docs/docs/index.md", "docs/docs/.gitbook.yaml", "docs/docs/installation/index.md", "docs/docs/installation/pr_agent.md", "docs/docs/installation/gitlab.md", "docs/docs/installation/azure.md", "docs/docs/installation/bitbucket.md", "docs/docs/installation/github.md", "docs/docs/installation/gitea.md", "docs/docs/installation/locally.md", "docs/docs/usage-guide/index.md", "docs/docs/usage-guide/EXAMPLE_BEST_PRACTICE.md", "docs/docs/usage-guide/changing_a_model.md", "docs/docs/usage-guide/introduction.md", "docs/docs/usage-guide/configuration_options.md", "docs/docs/usage-guide/mail_notifications.md", "docs/docs/usage-guide/automations_and_usage.md", "docs/docs/usage-guide/additional_configurations.md", "docs/docs/overview/data_privacy.md", "docs/docs/core-abilities/compression_strategy.md", "docs/docs/core-abilities/index.md", "docs/docs/core-abilities/fetching_ticket_context.md", "docs/docs/core-abilities/interactivity.md", "docs/docs/core-abilities/self_reflection.md", "docs/docs/core-abilities/dynamic_context.md", "docs/docs/core-abilities/metadata.md", "docs/docs/tools/add_docs.md", "docs/docs/tools/generate_labels.md", "docs/docs/tools/describe.md", "docs/docs/tools/review.md", "docs/docs/tools/index.md", "docs/docs/tools/similar_issues.md", "docs/docs/tools/improve.md", "docs/docs/tools/update_changelog.md" ], "repo_inspection_verified": true, "review_reasons": [], "tag_count_ok": true, "unsupported_claims": [] }, "schema_version": "0.1", "user_assets": { "ai_context_pack": { "asset_id": "ai_context_pack", "filename": "AI_CONTEXT_PACK.md", "markdown": "# pr-agent - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 pr-agent 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。\n\n## Claim 消费规则\n\n- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。\n- **事实最低状态**：`supported`\n- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。\n- `weak`：只能作为低置信度线索，必须要求用户继续核实。\n- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。\n- `unverified`：不得作为事实使用，应明确说证据不足。\n- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。\n\n## 它最适合谁\n\n- **正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**：README 或插件配置提到多个宿主 AI。 证据：`README.md` Claim：`clm_0002` supported 0.86\n\n## 它能做什么\n\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md` Claim：`clm_0001` supported 0.86\n\n## 怎么开始\n\n- `pip install pr-agent` 证据：`README.md` Claim：`clm_0003` supported 0.86\n\n## 继续前判断卡\n\n- **当前建议**：需要管理员/安全审批\n- **为什么**：继续前可能涉及密钥、账号、外部服务或敏感上下文，建议先经过管理员或安全审批。\n\n### 30 秒判断\n\n- **现在怎么做**：需要管理员/安全审批\n- **最小安全下一步**：先跑 Prompt Preview；若涉及凭证或企业环境，先审批再试装\n- **先别相信**：角色质量和任务匹配不能直接相信。\n- **继续会触碰**：角色选择偏差、命令执行、宿主 AI 配置\n\n### 现在可以相信\n\n- **适合人群线索：正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0002` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`README.md` Claim：`clm_0001` supported 0.86\n- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0003` supported 0.86\n\n### 现在还不能相信\n\n- **角色质量和任务匹配不能直接相信。**（unverified）：角色库证明有很多角色，不证明每个角色都适合你的具体任务，也不证明角色能产生高质量结果。\n- **不能把角色文案当成真实执行能力。**（unverified）：安装前只能判断角色描述和任务画像是否匹配，不能证明它能在宿主 AI 里完成任务。\n- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。\n- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。\n- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。 证据：`AGENTS.md`\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n\n### 继续会触碰什么\n\n- **角色选择偏差**：用户对任务应该由哪个专家角色处理的判断。 原因：选错角色会让 AI 从错误专业视角回答，浪费时间或误导决策。\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md`\n- **宿主 AI 配置**：Claude/Codex/Cursor/Gemini/OpenCode 等宿主的 plugin、Skill 或规则加载配置。 原因：宿主配置会改变 AI 后续工作方式，可能和用户已有规则冲突。 证据：`AGENTS.md`\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`README.md`\n- **环境变量 / API Key**：项目入口文档明确出现 API key、token、secret 或账号凭证配置。 原因：如果真实安装需要凭证，应先使用测试凭证并经过权限/合规判断。 证据：`README.md`, `docs/docs/installation/github.md`, `docs/docs/tools/help_docs.md`, `docs/docs/usage-guide/automations_and_usage.md` 等\n- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：先用交互式试用验证任务画像和角色匹配，不要先导入整套角色库。（适用：任何项目都适用，尤其是输出质量未知时。）\n- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）\n- **先备份宿主 AI 配置**：Skill、plugin、规则文件可能改变 Claude/Cursor/Codex 的默认行为。（适用：存在插件 manifest、Skill 或宿主规则入口时。）\n- **不要使用真实生产凭证**：环境变量/API key 一旦进入宿主或工具链，可能产生账号和合规风险。（适用：出现 API、TOKEN、KEY、SECRET 等环境线索时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **准备移除宿主 plugin / Skill / 规则入口**：如果试装后行为异常，可以把宿主 AI 恢复到试装前状态。\n- **保留原始角色选择记录**：如果输出偏题，可以回到任务画像阶段重新选择角色，而不是继续沿着错误角色推进。\n- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。\n- **准备撤销测试 API key 或 token**：测试凭证泄露或误用时，可以快速止损。\n- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。\n\n## 哪些只能预览\n\n- 解释项目适合谁和能做什么\n- 基于项目文档演示典型对话流程\n- 帮助用户判断是否值得安装或继续研究\n\n## 哪些必须安装后验证\n\n- 真实安装 Skill、插件或 CLI\n- 执行脚本、修改本地文件或访问外部服务\n- 验证真实输出质量、性能和兼容性\n\n## 边界与风险判断卡\n\n- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0004` inferred 0.45\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md` Claim：`clm_0005` supported 0.86\n- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。\n- **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。\n- **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。\n\n## 开工前工作上下文\n\n### 加载顺序\n\n- 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。\n- 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。\n- 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。\n- 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。\n- 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。\n\n### 任务路由\n\n- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`README.md` Claim：`clm_0001` supported 0.86\n\n### 上下文规模\n\n- 文件总数：226\n- 重要文件覆盖：40/226\n- 证据索引条目：73\n- 角色 / Skill 条目：46\n\n### 证据不足时的处理\n\n- **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。\n- **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。\n- **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。\n- **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。\n\n## Prompt Recipes\n\n### 适配判断\n\n- 目标：判断这个项目是否适合用户当前任务。\n- 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。\n\n```text\n请基于 pr-agent 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 pr-agent 当作安装前体验资产，而不是已安装工具或真实运行环境。\n\n请严格输出四段：\n1. 先问我 3 个必要问题。\n2. 给出一段“体验剧本”：用 [安装前可预览]、[必须安装后验证]、[证据不足] 三种标签展示它可能如何引导工作流。\n3. 给出安装后验证清单：列出哪些能力只有真实安装、真实宿主加载、真实项目运行后才能确认。\n4. 给出谨慎建议：只能说“值得继续研究/试装”“先补充信息后再判断”或“不建议继续”，不得替项目背书。\n\n硬性边界：\n- 不要声称已经安装、运行、执行测试、修改文件或产生真实结果。\n- 不要写“自动适配”“确保通过”“完美适配”“强烈建议安装”等承诺性表达。\n- 如果描述安装后的工作方式，必须使用“如果安装成功且宿主正确加载 Skill，它可能会……”这种条件句。\n- 体验剧本只能写成“示例台词/假设流程”：使用“可能会询问/可能会建议/可能会展示”，不要写“已写入、已生成、已通过、正在运行、正在生成”。\n- Prompt Preview 不负责给安装命令；如用户准备试装，只能提示先阅读 Quick Start 和 Risk Card，并在隔离环境验证。\n- 所有项目事实必须来自 supported claim、evidence_refs 或 source_paths；inferred/unverified 只能作风险或待确认项。\n\n```\n\n### 角色 / Skill 选择\n\n- 目标：从项目里的角色或 Skill 中挑选最匹配的资产。\n- 预期输出：候选角色或 Skill 列表，每项包含适用场景、证据路径、风险边界和是否需要安装后验证。\n\n```text\n请读取 role_skill_index，根据我的目标任务推荐 3-5 个最相关的角色或 Skill。每个推荐都要说明适用场景、可能输出、风险边界和 evidence_refs。\n```\n\n### 风险预检\n\n- 目标：安装或引入前识别环境、权限、规则冲突和质量风险。\n- 预期输出：环境、权限、依赖、许可、宿主冲突、质量风险和未知项的检查清单。\n\n```text\n请基于 risk_card、boundaries 和 quick_start_candidates，给我一份安装前风险预检清单。不要替我执行命令，只说明我应该检查什么、为什么检查、失败会有什么影响。\n```\n\n### 宿主 AI 开工指令\n\n- 目标：把项目上下文转成一次对话开始前的宿主 AI 指令。\n- 预期输出：一段边界明确、证据引用明确、适合复制给宿主 AI 的开工前指令。\n\n```text\n请基于 pr-agent 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 46 个角色 / Skill / 项目文档条目。\n\n- **Visit Our Docs Portal https://qodo-merge-docs.qodo.ai/**（project_doc）：Visit Our Docs Portal https://qodo-merge-docs.qodo.ai/ 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/README.md`\n- **Repository Guidelines**（project_doc）：- Do match the interpreter requirement declared in pyproject.toml Python ≥ 3.12 and install requirements.txt plus requirements-dev.txt before running tools. - Do run tests with PYTHONPATH=. set to keep imports functional for example PYTHONPATH=. ./.venv/bin/pytest tests/unittest/test fix json escape char.py -q . - Do adjust configuration through .pr agent.toml or files under pr agent/settings/ instead of hard-coding… 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`AGENTS.md`\n- **Big News for PR-Agent**（project_doc）：The Original Open-Source PR Reviewer 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`README.md`\n- **Contributing to PR-Agent**（project_doc）：Thank you for your interest in contributing to the PR-Agent project! 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`CONTRIBUTING.md`\n- **Overview**（project_doc）：Supported Git Platforms: GitHub, GitLab, Bitbucket 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/docs/core-abilities/compression_strategy.md`\n- **Introduction**（project_doc）：Supported Git Platforms: GitHub, GitLab, Bitbucket 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/docs/core-abilities/dynamic_context.md`\n- **Fetching Ticket Context for PRs**（project_doc）：Supported Git Platforms: GitHub, GitLab, Bitbucket 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/docs/core-abilities/fetching_ticket_context.md`\n- **Core Abilities**（project_doc）：PR-Agent utilizes a variety of core abilities to provide a comprehensive and efficient code review experience. These abilities include: 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/docs/core-abilities/index.md`\n- **Interactivity**（project_doc）：Supported Git Platforms: GitHub, GitLab 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/docs/core-abilities/interactivity.md`\n- **Local and global metadata injection with multi-stage analysis**（project_doc）：Local and global metadata injection with multi-stage analysis 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/docs/core-abilities/metadata.md`\n- **Introduction - Efficient Review with Hierarchical Presentation**（project_doc）：Supported Git Platforms: GitHub, GitLab, Bitbucket 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/docs/core-abilities/self_reflection.md`\n- **FAQ**（project_doc）：??? note \"Q: Can PR-Agent serve as a substitute for a human reviewer?\" Answer: 1 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/docs/faq/index.md`\n- **Overview**（project_doc）：PR-Agent https://github.com/the-pr-agent/pr-agent is an open-source, AI-powered code review agent and a community-maintained legacy project of Qodo. It is distinct from Qodo's primary AI code review offering, which provides a feature-rich, context-aware experience. Qodo now offers a free tier that integrates seamlessly with GitHub, GitLab, Bitbucket, and Azure DevOps for high-quality automated reviews. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/docs/index.md`\n- **Azure DevOps Pipeline**（project_doc）：You can use a pre-built Action Docker image to run PR-Agent as an Azure DevOps pipeline. Add the following file to your repository under azure-pipelines.yml : 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/docs/installation/azure.md`\n- **Run as a Bitbucket Pipeline**（project_doc）：You can use the Bitbucket Pipeline system to run PR-Agent on every pull request open or update. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/docs/installation/bitbucket.md`\n- **Run a Gitea webhook server**（project_doc）：1. In Gitea create a new user and give it \"Reporter\" role for the intended group or project. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/docs/installation/gitea.md`\n- **Run as a GitHub Action**（project_doc）：In this page we will cover how to install and run PR-Agent as a GitHub Action or GitHub App, and how to configure it for your needs. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/docs/installation/github.md`\n- **Run as a GitLab Pipeline**（project_doc）：You can use a pre-built Action Docker image to run PR-Agent as a GitLab pipeline. This is a simple way to get started with PR-Agent without setting up your own server. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/docs/installation/gitlab.md`\n- **Installation**（project_doc）：There are several ways to use PR-Agent: 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/docs/installation/index.md`\n- **Using Docker image**（project_doc）：To run PR-Agent locally, you first need to acquire two keys: 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/docs/installation/locally.md`\n- **PR-Agent Installation Guide**（project_doc）：PR-Agent can be deployed in various environments and platforms. Choose the installation method that best suits your needs: 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/docs/installation/pr_agent.md`\n- **Self-hosted PR-Agent**（project_doc）：- If you self-host PR-Agent with your OpenAI or other LLM provider API key, it is between you and the provider. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/docs/overview/data_privacy.md`\n- **Table of contents**（project_doc）：Overview index.md Data Privacy overview/data privacy.md 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/docs/summary.md`\n- **Overview**（project_doc）：The add docs tool scans the PR code changes and suggests documentation for any code components that are missing documentation, such as functions, classes, and methods. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/docs/tools/add_docs.md`\n- **Overview**（project_doc）：The ask tool answers questions about the PR, based on the PR code changes. Make sure to be specific and clear in your questions. It can be invoked manually by commenting on any PR: 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/docs/tools/ask.md`\n- **Overview**（project_doc）：The describe tool scans the PR code changes, and generates a description for the PR - title, type, summary, walkthrough and labels. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/docs/tools/describe.md`\n- **Overview**（project_doc）：The generate labels tool scans the PR code changes and generates custom labels for the PR based on the content and context of the changes. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/docs/tools/generate_labels.md`\n- **Overview**（project_doc）：The help tool provides a list of all the available tools and their descriptions. For PR-Agent users, it also enables to trigger each tool by checking the relevant box. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/docs/tools/help.md`\n- **Overview**（project_doc）：The help docs tool can answer a free-text question based on a git documentation folder. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/docs/tools/help_docs.md`\n- **Overview**（project_doc）：The improve tool scans the PR code changes, and automatically generates meaningful suggestions for improving the PR code. The tool can be triggered automatically every time a new PR is opened ../usage-guide/automations and usage.md github-app-automatic-tools-when-a-new-pr-is-opened , or it can be invoked manually by commenting on any PR: 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/docs/tools/improve.md`\n- **Tools**（project_doc）：Here is a list of PR-Agent tools, each with a dedicated page that explains how to use it: 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/docs/tools/index.md`\n- **Overview**（project_doc）：The review tool scans the PR code changes, and generates feedback about the PR, aiming to aid the reviewing process. The tool can be triggered automatically every time a new PR is opened ../usage-guide/automations and usage.md github-app-automatic-tools-when-a-new-pr-is-opened , or can be invoked manually by commenting on any PR: 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/docs/tools/review.md`\n- **Overview**（project_doc）：The similar issue tool retrieves the most similar issues to the current issue. It can be invoked manually by commenting on any PR: 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/docs/tools/similar_issues.md`\n- **Overview**（project_doc）：The update changelog tool automatically updates the CHANGELOG.md file with the PR changes. It can be invoked manually by commenting on any PR: 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/docs/tools/update_changelog.md`\n- **Recommend Python Best Practices**（project_doc）：This document outlines a series of recommended best practices for Python development. These guidelines aim to improve code quality, maintainability, and readability. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/docs/usage-guide/EXAMPLE_BEST_PRACTICE.md`\n- **Show possible configurations**（project_doc）：The possible configurations of PR-Agent are stored in here https://github.com/the-pr-agent/pr-agent/blob/main/pr agent/settings/configuration.toml {:target=\" blank\"}. In the tools ../tools/index.md page you can find explanations on how to use these configurations for each tool. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/docs/usage-guide/additional_configurations.md`\n- **Local repo CLI**（project_doc）：When running from your locally cloned PR-Agent repo CLI , your local configuration file will be used. Examples of invoking the different tools via the CLI: 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/docs/usage-guide/automations_and_usage.md`\n- **Changing a model in PR-Agent**（project_doc）：See here https://github.com/the-pr-agent/pr-agent/blob/main/pr agent/algo/ init .py for a list of supported models in PR-Agent. The default model of PR-Agent is GPT-5 from OpenAI. To use a different model than the default, you need to edit in the configuration file https://github.com/the-pr-agent/pr-agent/blob/main/pr agent/settings/configuration.toml L7 the fields: 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/docs/usage-guide/changing_a_model.md`\n- **Wiki configuration file**（project_doc）：The different tools and sub-tools used by PR-Agent are adjustable via a Git configuration file. There are three main ways to set persistent configurations: 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/docs/usage-guide/configuration_options.md`\n- **Usage guide**（project_doc）：This section provides a detailed guide on how to use PR-Agent. It includes information on how to adjust PR-Agent configurations, define which tools will run automatically, and other advanced configurations. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/docs/usage-guide/index.md`\n- **Introduction**（project_doc）：After installation ../installation/index.md , there are three basic ways to invoke PR-Agent: 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/docs/usage-guide/introduction.md`\n- **Mail Notifications**（project_doc）：Unfortunately, it is not possible in GitHub to disable mail notifications from a specific user. If you are subscribed to notifications for a repo with PR-Agent, we recommend turning off notifications for PR comments, to avoid lengthy emails: 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/docs/usage-guide/mail_notifications.md`\n- **2023-08-03**（project_doc）：- Optimized PR diff processing by introducing caching for diff files, reducing the number of API calls. - Refactored load large diff function to generate a patch only when necessary. - Fixed a bug in the GitLab provider where the new file was not retrieved correctly. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`CHANGELOG.md`\n- **Contributor Code of Conduct**（project_doc）：As contributors and maintainers of this project, and in the interest of fostering an open and welcoming community, we pledge to respect all people who contribute through reporting issues, posting feature requests, updating documentation, submitting pull requests or patches, and other activities. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`CODE_OF_CONDUCT.md`\n- **Version 0.11 - 2023-12-07**（project_doc）：- codiumai/pr-agent:0.11 - codiumai/pr-agent:0.11-github app - codiumai/pr-agent:0.11-bitbucket-app - codiumai/pr-agent:0.11-gitlab webhook - codiumai/pr-agent:0.11-github polling - codiumai/pr-agent:0.11-github action 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`RELEASE_NOTES.md`\n- **Security Policy**（project_doc）：PR-Agent is an open-source tool to help efficiently review and handle pull requests. Qodo Merge is a paid version of PR-Agent, designed for companies and teams that require additional features and capabilities. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`SECURITY.md`\n\n## 证据索引\n\n- 共索引 73 条证据。\n\n- **Visit Our Docs Portal https://qodo-merge-docs.qodo.ai/**（documentation）：Visit Our Docs Portal https://qodo-merge-docs.qodo.ai/ 证据：`docs/README.md`\n- **Repository Guidelines**（documentation）：- Do match the interpreter requirement declared in pyproject.toml Python ≥ 3.12 and install requirements.txt plus requirements-dev.txt before running tools. - Do run tests with PYTHONPATH=. set to keep imports functional for example PYTHONPATH=. ./.venv/bin/pytest tests/unittest/test fix json escape char.py -q . - Do adjust configuration through .pr agent.toml or files under pr agent/settings/ instead of hard-coding values. - Don’t commit secrets or access tokens; rely on environment variables as shown in the health and e2e tests. - Don’t reformat or reorder files globally; match existing 120-character lines, import ordering, and docstring style. - Don’t delete or rename configuration, prom… 证据：`AGENTS.md`\n- **Big News for PR-Agent**（documentation）：The Original Open-Source PR Reviewer 证据：`README.md`\n- **Contributing to PR-Agent**（documentation）：Thank you for your interest in contributing to the PR-Agent project! 证据：`CONTRIBUTING.md`\n- **License**（source_file）：GNU AFFERO GENERAL PUBLIC LICENSE Version 3, 19 November 2007 证据：`LICENSE`\n- **Overview**（documentation）：Supported Git Platforms: GitHub, GitLab, Bitbucket 证据：`docs/docs/core-abilities/compression_strategy.md`\n- **Introduction**（documentation）：Supported Git Platforms: GitHub, GitLab, Bitbucket 证据：`docs/docs/core-abilities/dynamic_context.md`\n- **Fetching Ticket Context for PRs**（documentation）：Supported Git Platforms: GitHub, GitLab, Bitbucket 证据：`docs/docs/core-abilities/fetching_ticket_context.md`\n- **Core Abilities**（documentation）：PR-Agent utilizes a variety of core abilities to provide a comprehensive and efficient code review experience. These abilities include: 证据：`docs/docs/core-abilities/index.md`\n- **Interactivity**（documentation）：Supported Git Platforms: GitHub, GitLab 证据：`docs/docs/core-abilities/interactivity.md`\n- **Local and global metadata injection with multi-stage analysis**（documentation）：Local and global metadata injection with multi-stage analysis 证据：`docs/docs/core-abilities/metadata.md`\n- **Introduction - Efficient Review with Hierarchical Presentation**（documentation）：Supported Git Platforms: GitHub, GitLab, Bitbucket 证据：`docs/docs/core-abilities/self_reflection.md`\n- **FAQ**（documentation）：??? note \"Q: Can PR-Agent serve as a substitute for a human reviewer?\" Answer: 1 证据：`docs/docs/faq/index.md`\n- **Overview**（documentation）：PR-Agent https://github.com/the-pr-agent/pr-agent is an open-source, AI-powered code review agent and a community-maintained legacy project of Qodo. It is distinct from Qodo's primary AI code review offering, which provides a feature-rich, context-aware experience. Qodo now offers a free tier that integrates seamlessly with GitHub, GitLab, Bitbucket, and Azure DevOps for high-quality automated reviews. 证据：`docs/docs/index.md`\n- **Azure DevOps Pipeline**（documentation）：You can use a pre-built Action Docker image to run PR-Agent as an Azure DevOps pipeline. Add the following file to your repository under azure-pipelines.yml : 证据：`docs/docs/installation/azure.md`\n- **Run as a Bitbucket Pipeline**（documentation）：You can use the Bitbucket Pipeline system to run PR-Agent on every pull request open or update. 证据：`docs/docs/installation/bitbucket.md`\n- **Run a Gitea webhook server**（documentation）：1. In Gitea create a new user and give it \"Reporter\" role for the intended group or project. 证据：`docs/docs/installation/gitea.md`\n- **Run as a GitHub Action**（documentation）：In this page we will cover how to install and run PR-Agent as a GitHub Action or GitHub App, and how to configure it for your needs. 证据：`docs/docs/installation/github.md`\n- **Run as a GitLab Pipeline**（documentation）：You can use a pre-built Action Docker image to run PR-Agent as a GitLab pipeline. This is a simple way to get started with PR-Agent without setting up your own server. 证据：`docs/docs/installation/gitlab.md`\n- **Installation**（documentation）：There are several ways to use PR-Agent: 证据：`docs/docs/installation/index.md`\n- **Using Docker image**（documentation）：To run PR-Agent locally, you first need to acquire two keys: 证据：`docs/docs/installation/locally.md`\n- **PR-Agent Installation Guide**（documentation）：PR-Agent can be deployed in various environments and platforms. Choose the installation method that best suits your needs: 证据：`docs/docs/installation/pr_agent.md`\n- **Self-hosted PR-Agent**（documentation）：- If you self-host PR-Agent with your OpenAI or other LLM provider API key, it is between you and the provider. 证据：`docs/docs/overview/data_privacy.md`\n- **Table of contents**（documentation）：Overview index.md Data Privacy overview/data privacy.md 证据：`docs/docs/summary.md`\n- **Overview**（documentation）：The add docs tool scans the PR code changes and suggests documentation for any code components that are missing documentation, such as functions, classes, and methods. 证据：`docs/docs/tools/add_docs.md`\n- **Overview**（documentation）：The ask tool answers questions about the PR, based on the PR code changes. Make sure to be specific and clear in your questions. It can be invoked manually by commenting on any PR: 证据：`docs/docs/tools/ask.md`\n- **Overview**（documentation）：The describe tool scans the PR code changes, and generates a description for the PR - title, type, summary, walkthrough and labels. 证据：`docs/docs/tools/describe.md`\n- **Overview**（documentation）：The generate labels tool scans the PR code changes and generates custom labels for the PR based on the content and context of the changes. 证据：`docs/docs/tools/generate_labels.md`\n- **Overview**（documentation）：The help tool provides a list of all the available tools and their descriptions. For PR-Agent users, it also enables to trigger each tool by checking the relevant box. 证据：`docs/docs/tools/help.md`\n- **Overview**（documentation）：The help docs tool can answer a free-text question based on a git documentation folder. 证据：`docs/docs/tools/help_docs.md`\n- **Overview**（documentation）：The improve tool scans the PR code changes, and automatically generates meaningful suggestions for improving the PR code. The tool can be triggered automatically every time a new PR is opened ../usage-guide/automations and usage.md github-app-automatic-tools-when-a-new-pr-is-opened , or it can be invoked manually by commenting on any PR: 证据：`docs/docs/tools/improve.md`\n- **Tools**（documentation）：Here is a list of PR-Agent tools, each with a dedicated page that explains how to use it: 证据：`docs/docs/tools/index.md`\n- **Overview**（documentation）：The review tool scans the PR code changes, and generates feedback about the PR, aiming to aid the reviewing process. The tool can be triggered automatically every time a new PR is opened ../usage-guide/automations and usage.md github-app-automatic-tools-when-a-new-pr-is-opened , or can be invoked manually by commenting on any PR: 证据：`docs/docs/tools/review.md`\n- **Overview**（documentation）：The similar issue tool retrieves the most similar issues to the current issue. It can be invoked manually by commenting on any PR: 证据：`docs/docs/tools/similar_issues.md`\n- **Overview**（documentation）：The update changelog tool automatically updates the CHANGELOG.md file with the PR changes. It can be invoked manually by commenting on any PR: 证据：`docs/docs/tools/update_changelog.md`\n- **Recommend Python Best Practices**（documentation）：This document outlines a series of recommended best practices for Python development. These guidelines aim to improve code quality, maintainability, and readability. 证据：`docs/docs/usage-guide/EXAMPLE_BEST_PRACTICE.md`\n- **Show possible configurations**（documentation）：The possible configurations of PR-Agent are stored in here https://github.com/the-pr-agent/pr-agent/blob/main/pr agent/settings/configuration.toml {:target=\" blank\"}. In the tools ../tools/index.md page you can find explanations on how to use these configurations for each tool. 证据：`docs/docs/usage-guide/additional_configurations.md`\n- **Local repo CLI**（documentation）：When running from your locally cloned PR-Agent repo CLI , your local configuration file will be used. Examples of invoking the different tools via the CLI: 证据：`docs/docs/usage-guide/automations_and_usage.md`\n- **Changing a model in PR-Agent**（documentation）：See here https://github.com/the-pr-agent/pr-agent/blob/main/pr agent/algo/ init .py for a list of supported models in PR-Agent. The default model of PR-Agent is GPT-5 from OpenAI. To use a different model than the default, you need to edit in the configuration file https://github.com/the-pr-agent/pr-agent/blob/main/pr agent/settings/configuration.toml L7 the fields: 证据：`docs/docs/usage-guide/changing_a_model.md`\n- **Wiki configuration file**（documentation）：The different tools and sub-tools used by PR-Agent are adjustable via a Git configuration file. There are three main ways to set persistent configurations: 证据：`docs/docs/usage-guide/configuration_options.md`\n- **Usage guide**（documentation）：This section provides a detailed guide on how to use PR-Agent. It includes information on how to adjust PR-Agent configurations, define which tools will run automatically, and other advanced configurations. 证据：`docs/docs/usage-guide/index.md`\n- **Introduction**（documentation）：After installation ../installation/index.md , there are three basic ways to invoke PR-Agent: 证据：`docs/docs/usage-guide/introduction.md`\n- **Mail Notifications**（documentation）：Unfortunately, it is not possible in GitHub to disable mail notifications from a specific user. If you are subscribed to notifications for a repo with PR-Agent, we recommend turning off notifications for PR comments, to avoid lengthy emails: 证据：`docs/docs/usage-guide/mail_notifications.md`\n- **2023-08-03**（documentation）：- Optimized PR diff processing by introducing caching for diff files, reducing the number of API calls. - Refactored load large diff function to generate a patch only when necessary. - Fixed a bug in the GitLab provider where the new file was not retrieved correctly. 证据：`CHANGELOG.md`\n- **Contributor Code of Conduct**（documentation）：As contributors and maintainers of this project, and in the interest of fostering an open and welcoming community, we pledge to respect all people who contribute through reporting issues, posting feature requests, updating documentation, submitting pull requests or patches, and other activities. 证据：`CODE_OF_CONDUCT.md`\n- **Version 0.11 - 2023-12-07**（documentation）：- codiumai/pr-agent:0.11 - codiumai/pr-agent:0.11-github app - codiumai/pr-agent:0.11-bitbucket-app - codiumai/pr-agent:0.11-gitlab webhook - codiumai/pr-agent:0.11-github polling - codiumai/pr-agent:0.11-github action 证据：`RELEASE_NOTES.md`\n- **Security Policy**（documentation）：PR-Agent is an open-source tool to help efficiently review and handle pull requests. Qodo Merge is a paid version of PR-Agent, designed for companies and teams that require additional features and capabilities. 证据：`SECURITY.md`\n- **Atlassian Connect Qodo Merge**（structured_config）：{ \"name\": \"Qodo Merge\", \"description\": \"Qodo Merge\", \"key\": \"app key\", \"vendor\": { \"name\": \"Qodo\", \"url\": \"https://qodo.ai\" }, \"authentication\": { \"type\": \"jwt\" }, \"baseUrl\": \"base url\", \"lifecycle\": { \"installed\": \"/installed\", \"uninstalled\": \"/uninstalled\" }, \"scopes\": \"account\", \"repository:write\", \"pullrequest:write\", \"wiki\" , \"contexts\": \"account\" , \"modules\": { \"webhooks\": { \"event\": \" \", \"url\": \"/webhook\" } }, \"links\": { \"privacy\": \"https://qodo.ai/privacy-policy\", \"terms\": \"https://qodo.ai/terms\" } } 证据：`pr_agent/servers/atlassian-connect-qodo-merge.json`\n- **Atlassian Connect**（structured_config）：{ \"name\": \"CodiumAI PR-Agent\", \"description\": \"CodiumAI PR-Agent\", \"key\": \"app key\", \"vendor\": { \"name\": \"CodiumAI\", \"url\": \"https://codium.ai\" }, \"authentication\": { \"type\": \"jwt\" }, \"baseUrl\": \"base url\", \"lifecycle\": { \"installed\": \"/installed\", \"uninstalled\": \"/uninstalled\" }, \"scopes\": \"account\", \"repository:write\", \"pullrequest:write\", \"wiki\" , \"contexts\": \"account\" , \"modules\": { \"webhooks\": { \"event\": \" \", \"url\": \"/webhook\" } }, \"links\": { \"privacy\": \"https://qodo.ai/privacy-policy\", \"terms\": \"https://qodo.ai/terms\" } } 证据：`pr_agent/servers/atlassian-connect.json`\n- **.dockerignore**（source_file）：.venv/ venv/ pr agent/settings/.secrets.toml pics/ pr agent.egg-info/ build/ 证据：`.dockerignore`\n- **What's Changed**（source_file）：name-template: 'v$RESOLVED VERSION' tag-template: 'v$RESOLVED VERSION' 证据：`.github/release-drafter.yml`\n- **.gitignore**（source_file）：.idea/ .lsp/ .vscode/ .env .venv/ venv/ pr agent/settings/.secrets.toml pycache dist/ .egg-info/ build/ .DS Store docs/.cache/ .qodo poetry.lock 证据：`.gitignore`\n- **.Pr Agent**（source_file）：pr reviewer enable review labels effort = true enable auto approval = true 证据：`.pr_agent.toml`\n- **See https://pre-commit.com for more information**（source_file）：See https://pre-commit.com for more information See https://pre-commit.com/hooks.html for more hooks 证据：`.pre-commit-config.yaml`\n- **Dockerfile**（source_file）：RUN apt-get update && apt-get install --no-install-recommends -y git curl && apt-get clean && rm -rf /var/lib/apt/lists/ 证据：`Dockerfile.github_action`\n- **Dockerfile**（source_file）：FROM pragent/pr-agent:github action 证据：`Dockerfile.github_action_dockerhub`\n- **Manifest**（source_file）：recursive-include pr agent .toml recursive-exclude pr agent .secrets.toml 证据：`MANIFEST.in`\n- **Action**（source_file）：name: 'The PR Agent' description: 'Summarize, review and suggest improvements for pull requests' branding: icon: 'award' color: 'green' runs: using: 'docker' image: 'Dockerfile.github action dockerhub' 证据：`action.yaml`\n- **Codecov**（source_file）：comment: false coverage: status: patch: false project: false 证据：`codecov.yml`\n- **Dockerfile**（source_file）：RUN apt update && apt install --no-install-recommends -y git curl && apt-get clean && rm -rf /var/lib/apt/lists/ 证据：`docker/Dockerfile`\n- 其余 13 条证据见 `AI_CONTEXT_PACK.json` 或 `EVIDENCE_INDEX.json`。\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`docs/README.md`, `AGENTS.md`, `README.md`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`docs/README.md`, `AGENTS.md`, `README.md`\n\n## 用户开工前应该回答的问题\n\n- 你准备在哪个宿主 AI 或本地环境中使用它？\n- 你只是想先体验工作流，还是准备真实安装？\n- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？\n\n## 验收标准\n\n- 所有能力声明都能回指到 evidence_refs 中的文件路径。\n- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。\n- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。\n\n---\n\n## Doramagic Context Augmentation\n\n下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。\n\n## Human Manual 骨架\n\n使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。\n\n宿主 AI 硬性规则：\n- 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。\n- 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。\n- 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。\n\n- **PR-Agent 简介**：importance `high`\n - source_paths: README.md, pr_agent/agent/pr_agent.py, pr_agent/tools/pr_description.py, pr_agent/tools/pr_reviewer.py\n- **系统架构**：importance `high`\n - source_paths: pr_agent/agent/pr_agent.py, pr_agent/config_loader.py, pr_agent/algo/types.py, pr_agent/git_providers/__init__.py, pr_agent/git_providers/git_provider.py\n- **AI 模型集成**：importance `high`\n - source_paths: pr_agent/algo/ai_handlers/base_ai_handler.py, pr_agent/algo/ai_handlers/openai_ai_handler.py, pr_agent/algo/ai_handlers/litellm_ai_handler.py, pr_agent/algo/ai_handlers/litellm_helpers.py, pr_agent/algo/token_handler.py\n- **工具概述**：importance `high`\n - source_paths: pr_agent/tools/pr_description.py, pr_agent/tools/pr_reviewer.py, pr_agent/tools/pr_code_suggestions.py, pr_agent/tools/pr_questions.py, pr_agent/tools/pr_add_docs.py\n- **代码审查工具 (Review)**：importance `high`\n - source_paths: pr_agent/tools/pr_reviewer.py, pr_agent/settings/pr_reviewer_prompts.toml, pr_agent/settings/configuration.toml\n- **代码改进工具 (Improve)**：importance `high`\n - source_paths: pr_agent/tools/pr_code_suggestions.py, pr_agent/settings/code_suggestions/pr_code_suggestions_prompts.toml, pr_agent/settings/code_suggestions/pr_code_suggestions_reflect_prompts.toml\n- **Git 平台集成**：importance `high`\n - source_paths: pr_agent/git_providers/github_provider.py, pr_agent/git_providers/gitlab_provider.py, pr_agent/git_providers/bitbucket_provider.py, pr_agent/git_providers/azuredevops_provider.py, pr_agent/git_providers/gitea_provider.py\n- **部署方式**：importance `high`\n - source_paths: action.yaml, Dockerfile.github_action, docker/Dockerfile, pr_agent/servers/github_app.py, pr_agent/servers/gitlab_webhook.py\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `9ab2636f89952c69600dc2038d39f468de699fd0`\n- inspected_files: `pyproject.toml`, `README.md`, `requirements.txt`, `docs/mkdocs.yml`, `docs/README.md`, `docs/docs/summary.md`, `docs/docs/index.md`, `docs/docs/.gitbook.yaml`, `docs/docs/installation/index.md`, `docs/docs/installation/pr_agent.md`, `docs/docs/installation/gitlab.md`, `docs/docs/installation/azure.md`, `docs/docs/installation/bitbucket.md`, `docs/docs/installation/github.md`, `docs/docs/installation/gitea.md`, `docs/docs/installation/locally.md`, `docs/docs/usage-guide/index.md`, `docs/docs/usage-guide/EXAMPLE_BEST_PRACTICE.md`, `docs/docs/usage-guide/changing_a_model.md`, `docs/docs/usage-guide/introduction.md`\n\n宿主 AI 硬性规则：\n- 没有 repo_clone_verified=true 时，不得声称已经读过源码。\n- 没有 repo_inspection_verified=true 时，不得把 README/docs/package 文件判断写成事实。\n- 没有 quick_start_verified=true 时，不得声称 Quick Start 已跑通。\n\n## Doramagic Pitfall Constraints / 踩坑约束\n\n这些规则来自 Doramagic 发现、验证或编译过程中的项目专属坑点。宿主 AI 必须把它们当作工作约束，而不是普通说明文字。\n\n### Constraint 1: 来源证据：Publish linux/arm64 Docker image for github_app tag\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Publish linux/arm64 Docker image for github_app tag\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_8cb9e552d2e2452cbe958628f6e800b6 | https://github.com/The-PR-Agent/pr-agent/issues/2386 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 2: 来源证据：[Bug] UnicodeDecodeError in gitea_provider.py when parsing binary files before extension filtering\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug] UnicodeDecodeError in gitea_provider.py when parsing binary files before extension filtering\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能阻塞安装或首次运行。\n- Evidence: community_evidence:github | cevd_52bd470b7b5e4be6858b290e41c93036 | https://github.com/The-PR-Agent/pr-agent/issues/2380 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 来源证据：v0.31\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.31\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_ef0e5f5f982146d8bd002453b969c07f | https://github.com/The-PR-Agent/pr-agent/releases/tag/v0.31 | 来源类型 github_release 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 来源证据：v0.34.2\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.34.2\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_4bc22335937e44c0b529ab84d1e69a60 | https://github.com/The-PR-Agent/pr-agent/releases/tag/v0.34.2 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: 来源证据：AzureDevopsProvider.get_repo_settings drops chunks after the first, silently truncating .pr_agent.toml\n\n- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：AzureDevopsProvider.get_repo_settings drops chunks after the first, silently truncating .pr_agent.toml\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_4ee2a84ba307469b9b329a043a70a224 | https://github.com/The-PR-Agent/pr-agent/issues/2376 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: 来源证据：Ticket context not scoped per PR in long-lived deployments — stale tickets leak between unrelated PRs\n\n- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Ticket context not scoped per PR in long-lived deployments — stale tickets leak between unrelated PRs\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_a9b90b0cfbbf4529b60d65f564f4592e | https://github.com/The-PR-Agent/pr-agent/issues/2383 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 7: 来源证据：v0.34.1\n\n- Trigger: GitHub 社区证据显示该项目存在一个能力理解相关的待验证问题：v0.34.1\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_eb46a134c8984cd8898e13f61602f165 | https://github.com/The-PR-Agent/pr-agent/releases/tag/v0.34.1 | 来源类型 github_release 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 8: 能力判断依赖假设\n\n- Trigger: README/documentation is current enough for a first validation pass.\n- Host AI rule: 将假设转成下游验证清单。\n- Why it matters: 假设不成立时，用户拿不到承诺的能力。\n- Evidence: capability.assumptions | github_repo:662766482 | https://github.com/The-PR-Agent/pr-agent | README/documentation is current enough for a first validation pass.\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 9: 维护活跃度未知\n\n- Trigger: 未记录 last_activity_observed。\n- Host AI rule: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- Why it matters: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- Evidence: evidence.maintainer_signals | github_repo:662766482 | https://github.com/The-PR-Agent/pr-agent | last_activity_observed missing\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 10: 下游验证发现风险项\n\n- Trigger: no_demo\n- Host AI rule: 进入安全/权限治理复核队列。\n- Why it matters: 下游已经要求复核，不能在页面中弱化。\n- Evidence: downstream_validation.risk_items | github_repo:662766482 | https://github.com/The-PR-Agent/pr-agent | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n", "summary": "给宿主 AI 的上下文和工作边界。", "title": "AI Context Pack / 带给我的 AI" }, "boundary_risk_card": { "asset_id": "boundary_risk_card", "filename": "BOUNDARY_RISK_CARD.md", "markdown": "# Boundary & Risk Card / 安装前决策卡\n\n项目：The-PR-Agent/pr-agent\n\n## Doramagic 试用结论\n\n当前结论：可以进入发布前推荐检查；首次使用仍应从最小权限、临时目录和可回滚配置开始。\n\n## 用户现在可以做\n\n- 可以先阅读 Human Manual，理解项目目的和主要工作流。\n- 可以复制 Prompt Preview 做安装前体验；这只验证交互感，不代表真实运行。\n- 可以把官方 Quick Start 命令放到隔离环境中验证，不要直接进主力环境。\n\n## 现在不要做\n\n- 不要把 Prompt Preview 当成项目实际运行结果。\n- 不要把 metadata-only validation 当成沙箱安装验证。\n- 不要把未验证能力写成“已支持、已跑通、可放心安装”。\n- 不要在首次试用时交出生产数据、私人文件、真实密钥或主力配置目录。\n\n## 安装前检查\n\n- 宿主 AI 是否匹配：chatgpt\n- 官方安装入口状态：已发现官方入口\n- 是否在临时目录、临时宿主或容器中验证：必须是\n- 是否能回滚配置改动：必须能\n- 是否需要 API Key、网络访问、读写文件或修改宿主配置：未确认前按高风险处理\n- 是否记录了安装命令、实际输出和失败日志：必须记录\n\n## 当前阻塞项\n\n- 无阻塞项。\n\n## 项目专属踩坑\n\n- 来源证据：Publish linux/arm64 Docker image for github_app tag（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：[Bug] UnicodeDecodeError in gitea_provider.py when parsing binary files before extension filtering（medium）：可能阻塞安装或首次运行。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：v0.31（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 来源证据：v0.34.2（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 来源证据：AzureDevopsProvider.get_repo_settings drops chunks after the first, silently truncating .pr_agent.toml（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n\n## 风险与权限提示\n\n- no_demo: medium\n\n## 证据缺口\n\n- 暂未发现结构化证据缺口。\n", "summary": "安装、权限、验证和推荐前风险。", "title": "Boundary & Risk Card / 边界与风险卡" }, "human_manual": { "asset_id": "human_manual", "filename": "HUMAN_MANUAL.md", "markdown": "# https://github.com/The-PR-Agent/pr-agent 项目说明书\n\n生成时间：2026-05-11 17:14:11 UTC\n\n## 目录\n\n- [PR-Agent 简介](#introduction)\n- [系统架构](#system_architecture)\n- [AI 模型集成](#ai_integration)\n- [工具概述](#tools_overview)\n- [代码审查工具 (Review)](#review_tool)\n- [代码改进工具 (Improve)](#improve_tool)\n- [Git 平台集成](#git_providers)\n- [部署方式](#deployment)\n- [配置管理](#configuration)\n- [扩展与定制](#customization)\n\n<a id='introduction'></a>\n\n## PR-Agent 简介\n\n### 相关页面\n\n相关主题：[系统架构](#system_architecture), [部署方式](#deployment)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/The-PR-Agent/pr-agent/blob/main/README.md)\n- [pr_agent/agent/pr_agent.py](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/agent/pr_agent.py)\n- [pr_agent/tools/pr_description.py](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/tools/pr_description.py)\n- [pr_agent/tools/pr_reviewer.py](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/tools/pr_reviewer.py)\n- [pr_agent/tools/pr_code_suggestions.py](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/tools/pr_code_suggestions.py)\n- [pr_agent/servers/help.py](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/servers/help.py)\n- [pr_agent/algo/utils.py](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/algo/utils.py)\n</details>\n\n# PR-Agent 简介\n\n## 概述\n\nPR-Agent 是一个由 AI 驱动的自动化工具，旨在帮助开发团队更高效地进行代码审查和 PR（Pull Request）管理。该工具通过分析 PR 代码变更，自动生成描述、代码建议、审查意见等，帮助团队提升代码质量和协作效率。\n\nPR-Agent 支持多种使用方式，包括 GitHub Action、GitLab CLI、Docker 等部署方式，能够与主流代码托管平台无缝集成。资料来源：[README.md:1-30]()\n\n## 核心功能模块\n\nPR-Agent 提供多个独立工具模块，每个模块专注于特定的代码审查任务：\n\n| 模块名称 | 功能描述 | 触发命令 |\n|---------|---------|---------|\n| `describe` | 自动生成 PR 描述、标题、类型和变更摘要 | `/describe` |\n| `review` | 对 PR 进行全面代码审查，识别潜在问题 | `/review` |\n| `improve` | 生成代码改进建议和优化方案 | `/improve` |\n| `ask` | 回答关于 PR 代码变更的问题 | `/ask \"...\"` |\n| `help_docs` | 根据文档路径回答使用问题 | `/help_docs \"...\"` |\n\n资料来源：[pr_agent/servers/help.py:1-50]()\n\n## 架构设计\n\n### 整体架构\n\n```mermaid\ngraph TD\n A[用户触发] --> B[GitHub/GitLab Provider]\n B --> C[PR Agent Core]\n C --> D[工具调度器]\n D --> E[describe 工具]\n D --> F[review 工具]\n D --> G[improve 工具]\n D --> H[ask 工具]\n E --> I[LLM 处理]\n F --> I\n G --> I\n H --> I\n I --> J[Markdown 输出]\n J --> K[PR 评论/更新]\n```\n\n### 工具执行流程\n\n```mermaid\nsequenceDiagram\n participant U as 用户\n participant G as Git Provider\n participant T as 工具模块\n participant L as LLM\n participant P as 输出处理\n\n U->>G: 触发 PR 事件\n G->>T: 获取代码变更\n T->>L: 发送 Prompt\n L->>T: 返回分析结果\n T->>P: 格式化输出\n P->>G: 发布评论\n G->>U: 显示结果\n```\n\n## 核心工具详解\n\n### Describe 工具\n\n`describe` 工具扫描 PR 代码变更，自动生成以下内容：\n\n- **PR 标题**：格式为 `<类型>: <标题>`，简明扼要（最多 10 个词）\n- **PR 类型**：如 Bug fix、Tests、Enhancement、Documentation、Other\n- **摘要说明**：概括本次变更的主要目的\n- **详细清单**：按语义分组列出变更的文件\n\n该工具支持通过标记（Markers）方式控制生成内容，用户可以在 PR 描述中预留 `pr_agent:type`、`pr_agent:summary`、`pr_agent:walkthrough`、`pr_agent:diagram` 等标记，工具将自动填充对应内容。\n\n资料来源：[pr_agent/tools/pr_description.py:1-100]()\n\n### Review 工具\n\n`review` 工具对 PR 进行全面的代码审查，包括：\n\n- 识别代码潜在问题\n- 检查安全问题\n- 评估代码可维护性\n- 提供改进建议\n\n审查结果以结构化的 Markdown 表格形式输出，包含问题类型、严重程度和具体位置链接。\n\n资料来源：[pr_agent/tools/pr_reviewer.py:1-50]()\n\n### Improve 工具\n\n`improve` 工具专注于代码优化建议，能够：\n\n- 扫描 PR 代码变更\n- 自动生成代码优化建议\n- 提供代码改进的 before/after 示例\n\n该工具支持配置项控制，包括建议数量阈值、评分机制等。评分分为 High、Medium、Low 三个等级。\n\n资料来源：[pr_agent/tools/pr_code_suggestions.py:80-120]()\n\n## 配置系统\n\nPR-Agent 使用 TOML 格式的配置文件，主要配置节包括：\n\n| 配置节 | 用途 |\n|-------|------|\n| `pr_description` | PR 描述生成配置 |\n| `pr_reviewer` | 代码审查配置 |\n| `pr_code_suggestions` | 代码建议配置 |\n| `config` | 全局配置 |\n\n配置可以通过以下方式指定：\n\n1. **命令行参数**：使用 `--section.key=value` 格式\n ```bash\n /describe --pr_description.some_config1=...\n ```\n2. **配置文件**：在 `pr_agent.toml` 中定义\n ```toml\n [pr_description]\n some_config1=...\n some_config2=...\n ```\n\n资料来源：[pr_agent/algo/utils.py:200-250]()\n\n## 部署方式\n\n### GitHub Action（推荐）\n\n```yaml\nname: PR Agent\non:\n pull_request:\n types: [opened, synchronize]\njobs:\n pr_agent_job:\n runs-on: ubuntu-latest\n steps:\n - name: PR Agent action step\n uses: the-pr-agent/pr-agent@main\n env:\n OPENAI_KEY: ${{ secrets.OPENAI_KEY }}\n GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}\n```\n\n### CLI 本地运行\n\n```bash\npip install pr-agent\nexport OPENAI_KEY=your_key_here\npr-agent --pr_url https://github.com/owner/repo/pull/123 review\n```\n\n### Docker 部署\n\n```bash\ndocker run -e OPENAI_KEY=your_key pragent/pr-agent:latest \\\n --pr_url https://github.com/owner/repo/pull/123 review\n```\n\n资料来源：[README.md:30-80]()\n\n## 输出格式\n\n### Markdown 表格输出\n\nPR-Agent 生成的输出采用 GitHub Flavored Markdown (GFM) 格式，支持折叠面板和表格：\n\n```html\n<table>\n <tr>\n <td><details>\n <summary><strong>文件名</strong></summary>\n <hr>\n 变更描述内容\n </details></td>\n <td>+10/-5</td>\n </tr>\n</table>\n```\n\n### 可访问性处理\n\n工具自动处理特殊字符转义，将单引号替换为反引号，并对文件名进行截断处理。链接格式根据平台不同自动适配 GitHub 或 GitLab 风格。\n\n资料来源：[pr_agent/algo/utils.py:100-150]()\n\n## 自动化配置\n\n工具支持自动化触发，可以配置在以下时机自动执行：\n\n- PR 打开时（`pull_request` 类型为 `opened`）\n- PR 同步更新时（`pull_request` 类型为 `synchronize`）\n\n默认的自动化命令列表：\n```python\npr_commands = [\"/describe\", ...]\n```\n\n可通过配置开启标记模式：\n```python\npr_commands = [\"/describe --pr_description.use_description_markers=true\", ...]\n```\n\n资料来源：[pr_agent/servers/help.py:80-120]()\n\n## 安全性注意事项\n\n根据项目指南：\n\n- 密钥和敏感信息应通过环境变量提供\n- 禁止将 API 密钥直接持久化到代码中\n- 遵循 `CONTRIBUTING.md` 中的提交规范\n- 使用 Conventional Commit 风格的提交信息\n\n资料来源：[AGENTS.md:30-50]()\n\n## 相关链接\n\n- 官方文档：https://docs.pr-agent.ai\n- 安装指南：https://docs.pr-agent.ai/installation/\n- 使用指南：https://docs.pr-agent.ai/usage-guide/\n\n---\n\n<a id='system_architecture'></a>\n\n## 系统架构\n\n### 相关页面\n\n相关主题：[PR-Agent 简介](#introduction), [AI 模型集成](#ai_integration), [Git 平台集成](#git_providers)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [pr_agent/tools/pr_description.py](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/tools/pr_description.py)\n- [pr_agent/servers/help.py](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/servers/help.py)\n- [pr_agent/algo/utils.py](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/algo/utils.py)\n- [pr_agent/tools/pr_code_suggestions.py](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/tools/pr_code_suggestions.py)\n- [pr_agent/tools/pr_config.py](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/tools/pr_config.py)\n- [AGENTS.md](https://github.com/The-PR-Agent/pr-agent/blob/main/AGENTS.md)\n- [README.md](https://github.com/The-PR-Agent/pr-agent/blob/main/README.md)\n- [pr_agent/git_providers/bitbucket_server_provider.py](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/git_providers/bitbucket_server_provider.py)\n</details>\n\n# 系统架构\n\n## 1. 概述\n\nPR-Agent 是一个自动化 Pull Request 分析和处理工具，通过模块化的工具系统实现 PR 描述生成、代码审查、代码建议生成等功能。该系统基于事件驱动架构，支持 GitHub、GitLab、Bitbucket Server 等多个平台。\n\n核心架构由以下几部分组成：\n\n| 组件层 | 职责 | 核心文件 |\n|--------|------|----------|\n| 入口层 | 处理用户命令和事件触发 | `AGENTS.md` |\n| 工具层 | 实现具体功能逻辑 | `pr_description.py`, `pr_code_suggestions.py` |\n| 基础设施层 | Git 集成、配置管理、日志 | `git_provider.py`, `config_loader.py` |\n| 输出层 | 格式化输出和用户交互 | `utils.py`, `help.py` |\n\n## 2. 系统架构图\n\n```mermaid\ngraph TD\n subgraph 入口层\n CMD[命令行/评论命令] --> AGENT[Agent 调度器]\n end\n \n subgraph 工具层\n DESCRIBE[描述工具<br/>pr_description.py]\n REVIEW[审查工具]\n IMPROVE[改进工具]\n ASK[问答工具]\n HELP_DOCS[帮助文档工具]\n CONFIG[配置工具]\n end\n \n subgraph 基础设施层\n GIT[Git Providers<br/>git_provider.py]\n CFG[配置加载器<br/>config_loader.py]\n LOG[日志系统]\n end\n \n subgraph Git平台\n GITHUB[GitHub Provider]\n GITLAB[GitLab Provider]\n BITBUCKET[Bitbucket Provider]\n end\n \n AGENT --> DESCRIBE\n AGENT --> REVIEW\n AGENT --> IMPROVE\n AGENT --> ASK\n AGENT --> HELP_DOCS\n AGENT --> CONFIG\n \n DESCRIBE --> GIT\n REVIEW --> GIT\n IMPROVE --> GIT\n ASK --> GIT\n CONFIG --> CFG\n \n GIT --> GITHUB\n GIT --> GITLAB\n GIT --> BITBUCKET\n \n DESCRIBE --> LOG\n IMPROVE --> LOG\n```\n\n## 3. 核心组件详解\n\n### 3.1 工具系统架构\n\nPR-Agent 的工具系统采用插件化设计，每个工具负责特定功能。所有工具都遵循统一的调用接口：\n\n```mermaid\ngraph LR\n subgraph 输入\n E1[PR 上下文]\n E2[用户命令]\n E3[配置文件]\n end\n \n subgraph 工具处理\n T1[解析输入]\n T2[调用 LLM]\n T3[处理结果]\n end\n \n subgraph 输出\n O1[Markdown 格式]\n O2[评论/更新]\n O3[配置展示]\n end\n \n E1 --> T1\n E2 --> T1\n E3 --> T1\n T1 --> T2\n T2 --> T3\n T3 --> O1\n T3 --> O2\n T3 --> O3\n```\n\n### 3.2 PR 描述工具（pr_description）\n\n`pr_description.py` 负责生成完整的 PR 描述，包括标题、类型、摘要、代码变更列表等。资料来源：[pr_agent/tools/pr_description.py:1-200]()\n\n#### 核心数据结构\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `pr_body` | str | PR 描述主体内容 |\n| `semantic_label` | str | 语义标签分类 |\n| `list_tuples` | list | 文件变更元组列表 |\n| `delta` | int | 列宽度配置 |\n\n#### 输出格式处理\n\nPR 描述工具支持多种输出格式，包括可折叠的文件列表和 GFM（GitHub Flavored Markdown）支持。关键代码位于文件的数据处理部分，通过遍历 `diff_files` 获取每个文件的增删行数统计：\n\n```python\nfor f in diff_files:\n if f.filename.lower().strip('/') == filename.lower().strip('/'):\n num_plus_lines = f.num_plus_lines\n num_minus_lines = f.num_minus_lines\n```\n\n### 3.3 代码建议工具（pr_code_suggestions）\n\n代码建议工具扫描 PR 变更并自动生成改进建议。评分机制分为三个等级：\n\n| 评分等级 | 阈值配置 | 说明 |\n|----------|----------|------|\n| High（高） | `score >= th_high` | 高优先级建议，默认值 9 |\n| Medium（中） | `score >= th_medium` | 中优先级建议，默认值 7 |\n| Low（低） | `score < 7` | 低优先级建议 |\n\n资料来源：[pr_agent/tools/pr_code_suggestions.py:100-120]()\n\n#### 持久化模式\n\n代码建议支持持久化模式，可以保留历史建议记录。该功能通过以下逻辑实现：\n\n1. 检测现有评论中是否存在历史建议\n2. 将新建议与历史建议合并\n3. 按提交进行分组展示\n4. 自动移除最旧的建议以控制数量\n\n### 3.4 帮助系统（help）\n\n帮助系统提供交互式使用指南，支持以下工具的文档：\n\n- `/describe` - PR 描述生成\n- `/review` - 代码审查\n- `/improve` - 代码改进建议\n- `/ask` - 问答功能\n- `/help_docs` - 文档帮助\n\n资料来源：[pr_agent/servers/help.py:1-150]()\n\n## 4. Git Provider 系统\n\n### 4.1 抽象层设计\n\nGit Provider 系统采用适配器模式，为不同平台提供统一接口：\n\n```mermaid\nclassDiagram\n class GitProvider {\n <<abstract>>\n +get_diff_files()\n +publish_comment()\n +edit_comment()\n +get_settings()\n }\n \n class GithubProvider {\n +is_supported(feature)\n +gfm_markdown support\n }\n \n class GitlabProvider {\n +is_supported(feature)\n +gfm_markdown support\n }\n \n class BitbucketServerProvider {\n +get_diff_code()\n +publish_code_suggestion()\n }\n \n GitProvider <|-- GithubProvider\n GitProvider <|-- GitlabProvider\n GitProvider <|-- BitbucketServerProvider\n```\n\n### 4.2 平台特性差异处理\n\n不同平台对 Markdown 和代码建议的支持程度不同，系统通过 `is_supported()` 方法进行特性检测：\n\n| 平台 | GFM Markdown | 多行代码建议 | 评论编辑 |\n|------|--------------|--------------|----------|\n| GitHub | ✅ | ✅ | ✅ |\n| GitLab | ✅ | ✅ | ✅ |\n| Bitbucket Server | ⚠️ 部分 | ❌ | ⚠️ 受限 |\n\n资料来源：[pr_agent/tools/pr_description.py:20-40]()\n\n### 4.3 代码建议发布差异\n\n对于不支持多行建议的平台（如 Bitbucket），系统会自动降级处理：\n\n```python\n# Bitbucket 不支持多行建议，降级为代码块\nbody = body.replace(\"```suggestion\", \"```\")\n```\n\n资料来源：[pr_agent/git_providers/bitbucket_server_provider.py:50-80]()\n\n## 5. 配置系统\n\n### 5.1 配置加载架构\n\n配置系统支持多层次的配置覆盖：\n\n```mermaid\ngraph TD\n subgraph 配置源\n ENV[环境变量]\n TOML[配置文件<br/>.pr_agent.toml]\n CLI[命令行参数]\n end\n \n subgraph 加载顺序\n O1[环境变量]\n O2[配置文件]\n O3[命令行参数]\n end\n \n O1 --> RESULT[最终配置]\n O2 --> RESULT\n O3 --> RESULT\n```\n\n### 5.2 配置节结构\n\n| 配置节 | 功能模块 | 主要配置项 |\n|--------|----------|------------|\n| `pr_description` | PR 描述 | `enable_help_comment`, `enable_description_markers` |\n| `pr_reviewer` | 代码审查 | 审查规则、标签配置 |\n| `pr_code_suggestions` | 代码建议 | 评分阈值、建议数量限制 |\n| `config` | 全局配置 | `output_relevant_configurations` |\n\n资料来源：[pr_agent/tools/pr_config.py:1-50]()\n\n### 5.3 配置输出展示\n\n系统支持将相关配置以 Markdown 格式输出到 PR 评论中：\n\n```yaml\n[config]\nkey: value\n\n[pr_description]\nenable_help_comment: true\n```\n\n## 6. 工具函数库\n\n`algo/utils.py` 提供了通用的工具函数支持：\n\n| 函数 | 功能 | 应用场景 |\n|------|------|----------|\n| `parse_code_suggestion()` | 解析代码建议字典为 Markdown | 代码建议输出 |\n| `show_relevant_configurations()` | 生成配置展示表格 | 配置工具 |\n| `extract_relevant_lines_str()` | 提取文件指定行范围内容 | 代码审查 |\n| `string_to_uniform_number()` | 字符串转均匀分布数值 | 随机选择逻辑 |\n\n### 6.1 代码建议解析\n\n代码建议解析支持两种输出格式：\n\n| 格式 | 触发条件 | 特点 |\n|------|----------|------|\n| 表格格式 | `gfm_supported=True` 且包含 `relevant_line` | 紧凑、易读 |\n| 列表格式 | 其他情况 | 兼容性更强 |\n\n资料来源：[pr_agent/algo/utils.py:80-150]()\n\n## 7. 部署架构\n\n### 7.1 支持的部署方式\n\n根据 README.md，PR-Agent 支持多种部署方式：\n\n| 部署方式 | 推荐场景 | 配置复杂度 |\n|----------|----------|------------|\n| GitHub Action | 自动化 PR 处理 | 低 |\n| CLI 本地运行 | 开发和测试 | 中 |\n| Docker 容器 | 定制化部署 | 中 |\n| API 服务 | 集成到现有系统 | 高 |\n\n资料来源：[README.md:1-100]()\n\n### 7.2 环境变量配置\n\n| 环境变量 | 必填 | 说明 |\n|----------|------|------|\n| `OPENAI_KEY` | 是 | LLM API 密钥 |\n| `GITHUB_TOKEN` | 是 | GitHub 访问令牌 |\n| `GITLAB_TOKEN` | 否 | GitLab 访问令牌 |\n| `BITBUCKET_TOKEN` | 否 | Bitbucket 访问令牌 |\n\n## 8. 数据流向\n\n```mermaid\ngraph LR\n subgraph 外部输入\n PR[Pull Request Event]\n CMD[命令行指令]\n end\n \n subgraph 处理流程\n PARSE[事件解析]\n LOAD[配置加载]\n FETCH[代码获取]\n ANALYZE[LLM 分析]\n FORMAT[结果格式化]\n end\n \n subgraph 输出\n COMMENT[PR 评论]\n UPDATE[PR 更新]\n LOG[日志输出]\n end\n \n PR --> PARSE\n CMD --> PARSE\n PARSE --> LOAD\n LOAD --> FETCH\n FETCH --> ANALYZE\n ANALYZE --> FORMAT\n FORMAT --> COMMENT\n FORMAT --> UPDATE\n FORMAT --> LOG\n```\n\n## 9. 安全性考虑\n\n根据 AGENTS.md 的安全指南：\n\n- **密钥管理**：所有密钥必须通过环境变量注入，禁止硬编码\n- **权限控制**：操作前需确认工作目录和文件权限\n- **外部调用**：本地构建和外部测试需要提前协调\n- **敏感信息**：禁止提交缓存的凭证、API 密钥或覆盖率报告\n\n## 10. 扩展指南\n\n### 10.1 添加新平台支持\n\n要添加新的 Git Provider，需要：\n\n1. 继承 `GitProvider` 基类\n2. 实现 `is_supported()` 方法声明平台特性\n3. 在 `git_providers/__init__.py` 中注册\n4. 处理平台特定的格式差异\n\n### 10.2 添加新工具\n\n新工具的创建流程：\n\n1. 在 `pr_agent/tools/` 目录下创建新模块\n2. 实现核心处理逻辑\n3. 在 `HelpMessage` 中添加使用指南\n4. 在 Agent 调度器中注册命令\n\n## 11. 相关文档\n\n- [PR-Agent 官方文档](https://qodo-merge-docs.qodo.ai/usage-guide/)\n- [工具使用指南](https://pr-agent-docs.codium.ai/tools/)\n- [配置文件参考](https://pr-agent-docs.codium.ai/usage-guide/configuration_options/)\n\n---\n\n<a id='ai_integration'></a>\n\n## AI 模型集成\n\n### 相关页面\n\n相关主题：[系统架构](#system_architecture), [配置管理](#configuration)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [pr_agent/algo/ai_handlers/base_ai_handler.py](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/algo/ai_handlers/base_ai_handler.py)\n- [pr_agent/algo/ai_handlers/openai_ai_handler.py](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/algo/ai_handlers/openai_ai_handler.py)\n- [pr_agent/algo/ai_handlers/litellm_ai_handler.py](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/algo/ai_handlers/litellm_ai_handler.py)\n- [pr_agent/algo/ai_handlers/litellm_helpers.py](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/algo/ai_handlers/litellm_helpers.py)\n- [pr_agent/algo/token_handler.py](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/algo/token_handler.py)\n</details>\n\n# AI 模型集成\n\n## 概述\n\nPR-Agent 的 AI 模型集成模块负责管理与大语言模型的通信，是整个工具链的核心基础设施。该模块通过抽象化的 Handler 架构，支持多种 AI 服务提供商（OpenAI、Anthropic、Azure 等），并提供统一的接口供各个工具（describe、review、improve 等）调用。\n\n## 架构设计\n\n### 模块位置\n\n```\npr_agent/algo/ai_handlers/\n├── base_ai_handler.py # 基础抽象类\n├── openai_ai_handler.py # OpenAI 具体实现\n├── litellm_ai_handler.py # LiteLLM 统一接口实现\n└── litellm_helpers.py # LiteLLM 辅助函数\n```\n\n### 核心组件\n\n#### 1. BaseAIHandler（基础处理器）\n\n所有 AI 处理器必须继承的基础抽象类，定义了标准接口规范。主要职责包括：\n\n- 定义 `do_complete` 和 `do_complete_streaming` 抽象方法\n- 提供统一的错误处理机制\n- 实现请求重试逻辑\n- 管理超时配置\n\n#### 2. OpenAIHandler（OpenAI 原生实现）\n\n针对 OpenAI API 的专用处理器，支持：\n\n- 标准 Chat Completion API\n- 函数调用（Function Calling）\n- JSON 模式响应\n- 流式输出\n\n#### 3. LiteLLMHandler（统一接口实现）\n\n通过 [LiteLLM](https://github.com/BerriAI/litellm) 库实现的统一处理器，支持：\n\n| 提供商 | 支持模型 |\n|--------|----------|\n| OpenAI | GPT-3.5, GPT-4, GPT-4-Turbo |\n| Anthropic | Claude 2, Claude 3 |\n| Azure | Azure OpenAI Service |\n| Google | Gemini Pro |\n| AWS | Bedrock 系列 |\n\n## Token 管理\n\n`token_handler.py` 模块负责管理 Token 使用量和成本控制。\n\n### 核心功能\n\n```python\n# Token 计数与限制检查\n- 计算请求和响应的 Token 数量\n- 估算处理成本\n- 防止超出上下文窗口限制\n```\n\n### 上下文窗口管理\n\n系统会根据模型的最大上下文长度自动进行分块处理，确保长文本能够正确处理：\n\n```\npr_agent/algo/token_handler.py:1-50\n```\n\n## 工作流程\n\n```mermaid\ngraph TD\n A[工具模块<br>describe/review/improve] --> B[调用 AI Handler]\n B --> C{选择 Provider}\n C -->|OpenAI| D[OpenAIHandler]\n C -->|LiteLLM| E[LiteLLMHandler]\n D --> F[API 请求]\n E --> G[LiteLLM 路由]\n G --> H[目标 LLM API]\n F --> I[Token 计算]\n H --> I\n I --> J[响应解析]\n J --> K[返回结果给工具]\n```\n\n## 配置管理\n\nAI 模型通过配置文件进行管理，主要配置项位于 `pr_agent/settings/configuration.toml`。\n\n### 关键配置参数\n\n| 配置项 | 说明 | 默认值 |\n|--------|------|--------|\n| `model` | 使用的模型名称 | `gpt-4` |\n| `temperature` | 生成温度参数 | `0.2` |\n| `max_tokens` | 最大输出 Token 数 | `8000` |\n| `api_key` | API 密钥（环境变量） | - |\n\n### 环境变量配置\n\n```bash\n# OpenAI\nexport OPENAI_KEY=sk-...\n\n# Anthropic (通过 LiteLLM)\nexport ANTHROPIC_API_KEY=sk-ant-...\n\n# Azure OpenAI\nexport AZURE_API_KEY=...\nexport AZURE_API_BASE=...\n```\n\n资料来源：[README.md:1-50]()\n\n## 代码建议评分机制\n\nAI 模型在代码建议工具中承担双重职责：生成建议内容和评估建议质量。\n\n### 评分逻辑\n\n```python\n# pr_agent/tools/pr_code_suggestions.py:150-160\ndef get_score_str(self, score: int) -> str:\n th_high = get_settings().pr_code_suggestions.get('new_score_mechanism_th_high', 9)\n th_medium = get_settings().pr_code_suggestions.get('new_score_mechanism_th_medium', 7)\n if score >= th_high:\n return \"High\"\n elif score >= th_medium:\n return \"Medium\"\n else:\n return \"Low\"\n```\n\n### 评分阈值配置\n\n| 等级 | 阈值范围 | 说明 |\n|------|----------|------|\n| High | ≥ 9 | 高优先级建议 |\n| Medium | 7-8 | 中等优先级建议 |\n| Low | < 7 | 低优先级建议 |\n\n资料来源：[pr_agent/tools/pr_code_suggestions.py:145-165]()\n\n## 自反思机制\n\nAI 模型还支持自反思功能，用于改进生成结果的质量：\n\n```python\n# pr_agent/tools/pr_code_suggestions.py:170-190\nasync def self_reflect_on_suggestions(\n self,\n suggestion_list: List,\n patches_diff: str,\n model: str,\n prev_suggestions_str: str = \"\",\n dedicated_prompt: str = \"\"\n) -> str:\n```\n\n此功能允许模型：\n\n1. 回顾之前的建议列表\n2. 分析当前建议的改进空间\n3. 生成更高质量的输出\n\n## 使用示例\n\n### 1. 在工具中使用\n\n```python\nfrom pr_agent.algo.ai_handlers import get_ai_handler\n\nhandler = get_ai_handler(provider=\"openai\")\nresponse = await handler.do_complete(prompt=prompt, model=\"gpt-4\")\n```\n\n### 2. 切换模型提供商\n\n```bash\n# 使用 OpenAI\npr-agent --pr_url https://github.com/... review\n\n# 使用 LiteLLM (支持多种后端)\n# 通过配置设置使用的 provider\n```\n\n## 错误处理与重试\n\nAI Handler 实现了健壮的错误处理机制：\n\n- **网络错误**：自动重试（默认 3 次）\n- **速率限制**：指数退避策略\n- **Token 超限**：自动分块处理\n- **模型不可用**：优雅降级\n\n## 扩展新的 AI Provider\n\n如需添加新的 AI 提供商，只需：\n\n1. 创建新的 Handler 类继承 `BaseAIHandler`\n2. 实现 `do_complete` 方法\n3. 在 `get_ai_handler` 工厂函数中注册\n\n```python\n# 示例结构\nclass CustomAIHandler(BaseAIHandler):\n async def do_complete(self, prompt: str, **kwargs) -> str:\n # 实现自定义逻辑\n pass\n```\n\n## 相关文档\n\n- [PR-Agent 使用指南](https://pr-agent-docs.codium.ai/usage-guide/)\n- [配置选项详解](https://pr-agent-docs.codium.ai/usage-guide/configuration_options/)\n- [工具自动化配置](https://pr-agent-docs.codium.ai/usage-guide/automations_and_usage/)\n\n---\n\n<a id='tools_overview'></a>\n\n## 工具概述\n\n### 相关页面\n\n相关主题：[代码审查工具 (Review)](#review_tool), [代码改进工具 (Improve)](#improve_tool)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [pr_agent/tools/pr_description.py](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/tools/pr_description.py)\n- [pr_agent/tools/pr_reviewer.py](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/tools/pr_reviewer.py)\n- [pr_agent/tools/pr_code_suggestions.py](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/tools/pr_code_suggestions.py)\n- [pr_agent/tools/pr_questions.py](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/tools/pr_questions.py)\n- [pr_agent/tools/pr_add_docs.py](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/tools/pr_add_docs.py)\n- [pr_agent/tools/pr_update_changelog.py](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/tools/pr_update_changelog.py)\n- [pr_agent/tools/pr_generate_labels.py](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/tools/pr_generate_labels.py)\n- [pr_agent/servers/help.py](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/servers/help.py)\n</details>\n\n# 工具概述\n\nPR-Agent 是一款开源的 AI 驱动工具，通过自动分析和生成内容来增强 Pull Request 的处理流程。该工具集提供了多种功能模块，涵盖 PR 描述生成、代码审查、代码建议、问答交互、文档更新和标签管理等方面。\n\n## 核心工具列表\n\nPR-Agent 提供了以下主要工具：\n\n| 工具名称 | 命令触发 | 功能描述 |\n|---------|---------|---------|\n| describe | `/describe` | 生成 PR 描述（标题、类型、摘要、walkthrough、标签） |\n| review | `/review` | 对 PR 进行全面代码审查 |\n| improve | `/improve` | 生成代码改进建议 |\n| ask | `/ask` | 回答关于 PR 的问题 |\n| help_docs | `/help_docs` | 基于文档回答问题 |\n| update_changelog | `/update_changelog` | 自动更新 CHANGELOG 文件 |\n| generate_labels | `/generate_labels` | 生成或建议 PR 标签 |\n\n## 工具架构图\n\n```mermaid\ngraph TD\n A[用户触发 PR-Agent] --> B{触发方式}\n B -->|自动触发| C[GitHub App 配置]\n B -->|手动触发| D[PR 评论命令]\n \n C --> E[PR 事件处理器]\n D --> E\n \n E --> F{工具选择}\n F -->|/describe| G[pr_description.py]\n F -->|/review| H[pr_reviewer.py]\n F -->|/improve| I[pr_code_suggestions.py]\n F -->|/ask| J[pr_questions.py]\n F -->|/help_docs| K[pr_add_docs.py]\n F -->|/update_changelog| L[pr_update_changelog.py]\n F -->|/generate_labels| M[pr_generate_labels.py]\n \n G --> N[Git Provider]\n H --> N\n I --> N\n J --> N\n K --> N\n L --> N\n M --> N\n \n N --> O[PR 评论/更新]\n```\n\n## describe 工具\n\n`describe` 工具负责扫描 PR 代码变更并生成完整的 PR 描述信息。\n\n### 功能特性\n\n- **标题生成**：自动生成符合格式要求的 PR 标题\n- **类型识别**：识别 PR 类型（如 Bug fix、Enhancement、Documentation 等）\n- **摘要编写**：生成代码变更的简要摘要\n- **walkthrough 导航**：提供变更的逐步讲解\n- **标签建议**：基于内容和自定义规则推荐标签\n\n### 配置选项\n\n工具支持通过 `pr_description` 配置段进行自定义：\n\n```toml\n[pr_description]\nextra_instructions=\"\"\"\\\n- The PR title should be in the format: '<PR type>: <title>'\n- The title should be short and concise (up to 10 words)\n\"\"\"\n```\n\n资料来源：[pr_agent/servers/help.py:46-52]()\n\n### Marker 机制\n\ndescribe 工具支持 Marker 机制，允许用户在 PR 描述中预留占位符：\n\n| Marker | 功能 |\n|--------|------|\n| `pr_agent:type` | PR 类型 |\n| `pr_agent:summary` | PR 摘要 |\n| `pr_agent:walkthrough` | 变更讲解 |\n| `pr_agent:diagram` | 序列图（如果启用） |\n\n资料来源：[pr_agent/servers/help.py:46-60]()\n\n## review 工具\n\n`review` 工具对 PR 进行全面的代码审查，分析代码质量、潜在问题和改进建议。\n\n### 调用方式\n\n通过评论触发：\n```\n/review --pr_reviewer.some_config1=... --pr_reviewer.some_config2=...\n```\n\n通过配置文件：\n```toml\n[pr_reviewer]\nsome_config1=...\nsome_config2=...\n```\n\n资料来源：[pr_agent/servers/help.py:5-12]()\n\n## improve 工具\n\n`improve` 工具扫描 PR 代码变更，自动生成代码改进建议。\n\n### 功能特性\n\n- **代码建议生成**：针对代码质量问题提供改进建议\n- **评分机制**：每个建议带有重要性评分（High/Medium/Low）\n- **建议持久化**：支持跨提交保留历史建议记录\n- **可折叠展示**：通过 `<details>` 标签组织建议输出\n\n### 评分阈值配置\n\n```python\nth_high = get_settings().pr_code_suggestions.get('new_score_mechanism_th_high', 9)\nth_medium = get_settings().pr_code_suggestions.get('new_score_mechanism_th_medium', 7)\nif score >= th_high:\n return \"High\"\nelif score >= th_medium:\n return \"Medium\"\nelse:\n return \"Low\"\n```\n\n资料来源：[pr_agent/tools/pr_code_suggestions.py:67-75]()\n\n### 建议输出格式\n\n```html\n<details><summary>{suggestion_summary}</summary>\n\n___\n\n**{suggestion_content}**\n\n[{relevant_file} {range_str}]({code_snippet_link})\n\n{example_code}\n\n<details><summary>Suggestion importance[1-10]: {score}</summary>\n\nWhy: {score_why}\n\n</details>\n</details>\n```\n\n资料来源：[pr_agent/tools/pr_code_suggestions.py:180-200]()\n\n## ask 工具\n\n`ask` 工具基于 PR 代码变更回答用户问题。\n\n### 功能特性\n\n- **无状态问答**：每次问答独立，不保留对话历史\n- **上下文理解**：可分析整个 PR、特定代码行或相关图片\n- **灵活提问**：支持任意关于 PR 的问题\n\n### 调用方式\n\n```\n/ask \"这段代码为什么要这样实现？\"\n```\n\n资料来源：[pr_agent/servers/help.py:82-91]()\n\n## help_docs 工具\n\n`help_docs` 工具根据给定的文档路径回答问题，可查询本仓库或外部仓库的文档。\n\n### 调用方式\n\n```\n/help_docs \"...\"\n```\n\n资料来源：[pr_agent/servers/help.py:120-128]()\n\n## update_changelog 工具\n\n`update_changelog` 工具自动更新仓库的 CHANGELOG 文件，记录 PR 变更。\n\n## generate_labels 工具\n\n`generate_labels` 工具根据 PR 内容生成或建议标签。\n\n### 自定义标签支持\n\n用户可以在仓库的标签页面定义自定义标签：\n\n| 示例标签 | 含义 |\n|---------|------|\n| `Main topic:performance` | PR 主要涉及性能优化 |\n| `New endpoint` | 新增 API 端点 |\n| `SQL query` | 包含 SQL 查询变更 |\n| `Dockerfile changes` | Dockerfile 修改 |\n\n资料来源：[pr_agent/servers/help.py:66-76]()\n\n## 配置系统\n\n### 配置层级\n\nPR-Agent 采用多层级配置系统：\n\n1. **全局配置**：项目根目录的配置文件\n2. **工具级配置**：各工具独立的配置段\n3. **命令参数**：通过命令行直接传递的配置\n\n### 配置输出功能\n\n当启用 `output_relevant_configurations` 时，系统会在 PR 评论中输出相关配置：\n\n```python\nif get_settings().get('config', {}).get('output_relevant_configurations', False):\n pr_body += show_relevant_configurations(relevant_section='pr_description')\n```\n\n资料来源：[pr_agent/tools/pr_description.py:30-33]()\n\n## 自动化触发\n\n### GitHub App 自动触发\n\n工具可配置为在特定事件发生时自动运行：\n\n```toml\npr_commands = [\"/describe\", ...]\n```\n\n默认情况下，describe 工具会在新 PR 打开时自动运行。\n\n### Marker 模式\n\n通过配置启用 Marker 模式：\n\n```toml\npr_commands = [\"/describe --pr_description.use_description_markers=true\", ...]\n```\n\n此模式下，工具仅替换 PR 描述中的 marker，不会完全重写描述。\n\n## 输出格式化\n\n### GFM 支持检测\n\n工具根据 Git Provider 类型决定输出格式：\n\n```python\nif self.git_provider.is_supported(\"gfm_markdown\"):\n # 使用 HTML 格式增强展示\n pr_body += '<table>...'\nelse: # GitLab\n # 使用 Markdown 标准格式\n pr_body += f\"### {emoji} {key_nice}: {value}\\n\\n\"\n```\n\n资料来源：[pr_agent/algo/utils.py:95-105]()\n\n### 可折叠文件列表\n\n对于包含多个文件的变更，系统使用 `<details>` 标签提供可折叠视图：\n\n```html\n<td><details><summary>{len(list_tuples)} files</summary><table>\n```\n\n资料来源：[pr_agent/tools/pr_description.py:85-88]()\n\n## 工具交互流程\n\n```mermaid\nsequenceDiagram\n participant U as 用户\n participant G as Git Provider\n participant T as 工具处理器\n participant AI as AI Model\n \n U->>G: 触发命令或自动事件\n G->>T: 接收 PR 上下文\n T->>AI: 发送分析请求\n AI->>T: 返回分析结果\n T->>T: 格式化输出内容\n T->>G: 生成评论/更新\n G->>U: 显示结果\n```\n\n## 错误处理与日志\n\n各工具实现了统一的错误处理机制：\n\n```python\ntry:\n # 处理逻辑\nexcept Exception as e:\n get_logger().error(f\"Error processing pr files to markdown {self.pr_id}: {str(e)}\")\n pass\n```\n\n资料来源：[pr_agent/tools/pr_description.py:98-101]()\n\n## 相关文档\n\n- [Describe 工具使用指南](https://pr-agent-docs.codium.ai/tools/describe/)\n- [Review 工具使用指南](https://pr-agent-docs.codium.ai/tools/review/)\n- [Improve 工具使用指南](https://pr-agent-docs.codium.ai/tools/improve/)\n- [Ask 工具使用指南](https://pr-agent-docs.codium.ai/tools/ask/)\n- [Help Docs 工具使用指南](https://pr-agent-docs.codium.ai/tools/help_docs/)\n- [配置选项文档](https://pr-agent-docs.codium.ai/usage-guide/configuration_options/)\n\n---\n\n<a id='review_tool'></a>\n\n## 代码审查工具 (Review)\n\n### 相关页面\n\n相关主题：[工具概述](#tools_overview), [代码改进工具 (Improve)](#improve_tool)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [pr_agent/tools/pr_reviewer.py](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/tools/pr_reviewer.py)\n- [pr_agent/settings/pr_reviewer_prompts.toml](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/settings/pr_reviewer_prompts.toml)\n- [pr_agent/settings/configuration.toml](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/settings/configuration.toml)\n- [pr_agent/servers/help.py](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/servers/help.py)\n- [pr_agent/algo/utils.py](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/algo/utils.py)\n</details>\n\n# 代码审查工具 (Review)\n\n## 概述\n\n代码审查工具（Review）是PR Agent的核心功能之一，用于对Pull Request进行全面的代码质量分析。该工具能够自动扫描PR代码变更，识别潜在问题并提供改进建议。审查工具可以自动触发（当新PR打开时），也可以通过手动评论触发。\n\n## 工作原理\n\n```mermaid\ngraph TD\n A[PR打开/手动触发] --> B[代码变更分析]\n B --> C[多维度审查]\n C --> D[问题识别]\n D --> E[审查报告生成]\n E --> F[PR评论输出]\n \n C --> C1[安全性检查]\n C --> C2[可维护性评估]\n C --> C3[代码质量分析]\n C --> C4[测试覆盖检查]\n```\n\n## 触发方式\n\n### 自动触发\n\n通过GitHub App配置，可在每次新PR打开时自动运行审查工具：\n\n```\npr_commands = [\"/review\", ...]\n```\n\n### 手动触发\n\n通过在PR评论中输入命令触发：\n\n```\n/review --pr_reviewer.some_config1=... --pr_reviewer.some_config2=...\n```\n\n## 配置选项\n\n代码审查工具支持丰富的配置选项，通过`pr_reviewer`配置节进行管理：\n\n### 通用配置\n\n| 配置项 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| `enable_help_comment` | bool | true | 是否在PR中添加帮助提示 |\n| `enable_heuristics` | bool | true | 是否启用启发式分析 |\n| `enable_inline_features` | bool | true | 是否启用内联功能 |\n| `review_simple_summary` | bool | false | 是否生成简化摘要 |\n\n### 审查维度配置\n\n| 配置项 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| `enable_security` | bool | true | 启用安全审查 |\n| `enable_pr_testing` | bool | false | 启用PR测试 |\n| `enable_problematic_section_labels` | bool | true | 启用问题标签 |\n| `enable_review_effort_estimation` | bool | true | 启用审查工作量估算 |\n\n### 输出格式配置\n\n| 配置项 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| `extra_instructions` | str | \"\" | 额外的审查指令 |\n| `include_generated_by` | bool | true | 是否包含生成者标记 |\n\n## 审查报告结构\n\n代码审查工具生成的报告包含以下核心部分：\n\n### 1. 安全性问题\n\n识别代码中的安全漏洞，包括：\n- SQL注入风险\n- XSS跨站脚本攻击\n- 敏感信息泄露\n- 认证/授权缺陷\n\n### 2. 代码质量问题\n\n- 命名规范检查\n- 代码复杂度分析\n- 重复代码检测\n- 代码风格一致性\n\n### 3. 可维护性评估\n\n- 模块耦合度分析\n- 依赖关系检查\n- 技术债务识别\n\n### 4. 测试覆盖\n\n- 单元测试覆盖情况\n- 集成测试完整性\n- 测试质量评估\n\n## 使用示例\n\n### 基本使用\n\n```bash\n/review\n```\n\n### 启用特定审查维度\n\n```bash\n/review --pr_reviewer.enable_security=true --pr_reviewer.enable_pr_testing=true\n```\n\n### 自定义审查指令\n\n```bash\n/review --pr_reviewer.extra_instructions=\"重点关注支付相关代码的安全性\"\n```\n\n### 配置文件方式\n\n```toml\n[pr_reviewer]\nenable_security = true\nenable_pr_testing = false\nextra_instructions = \"\"\"\n- 优先检查数据验证逻辑\n- 关注错误处理完整性\n\"\"\"\n```\n\n## 与其他工具的集成\n\n```mermaid\ngraph LR\n A[Review工具] --> B[Describe工具]\n A --> C[Improve工具]\n A --> D[Test工具]\n \n B --> E[PR描述增强]\n C --> F[代码建议]\n D --> G[测试生成]\n```\n\n代码审查工具与PR Agent的其他工具紧密协作：\n\n- **Describe**：审查结果可作为PR描述生成的输入\n- **Improve**：识别的代码问题可自动生成改进建议\n- **Test**：检测到的代码路径可触发相关测试生成\n\n## 审查结果展示\n\n审查结果以Markdown格式输出到PR评论，支持：\n\n- 可折叠的详细信息区域\n- 代码高亮的引用\n- 问题严重程度标签\n- 相关文件链接\n\n## 相关源码\n\n核心实现位于 `pr_agent/tools/pr_reviewer.py`，使用 `pr_agent/settings/pr_reviewer_prompts.toml` 中定义的提示模板进行代码分析。\n\n## 参考资料\n\n- 官方文档：https://pr-agent-docs.codium.ai/tools/review/\n- 配置文件：https://github.com/Codium-ai/pr-agent/blob/main/pr_agent/settings/configuration.toml\n\n---\n\n<a id='improve_tool'></a>\n\n## 代码改进工具 (Improve)\n\n### 相关页面\n\n相关主题：[工具概述](#tools_overview), [代码审查工具 (Review)](#review_tool)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [pr_agent/tools/pr_code_suggestions.py](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/tools/pr_code_suggestions.py)\n- [pr_agent/servers/help.py](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/servers/help.py)\n- [pr_agent/algo/utils.py](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/algo/utils.py)\n- [pr_agent/tools/pr_config.py](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/tools/pr_config.py)\n- [AGENTS.md](https://github.com/The-PR-Agent/pr-agent/blob/main/AGENTS.md)\n</details>\n\n# 代码改进工具 (Improve)\n\n## 概述\n\n`improve` 是 PR-Agent 项目中的一个核心工具，用于自动扫描 Pull Request 的代码变更并生成改进建议。该工具能够识别代码质量问题并提供具体的优化方案，帮助开发者提升代码质量。工具支持自动触发和手动调用两种模式，可通过评论指令或 GitHub App 配置来使用。\n\n## 核心功能\n\n### 自动化代码扫描\n\nimprove 工具在每次 PR 变更时自动执行代码分析，检测潜在的改进点：\n\n- 识别代码可读性问题\n- 发现性能优化机会\n- 检测最佳实践违规\n- 建议更安全的实现方式\n\n### 评分机制\n\n工具为每个建议分配优先级评分，基于配置的门限值分为三个等级：\n\n| 评分等级 | 高优先级阈值 | 中优先级阈值 | 说明 |\n|---------|------------|------------|------|\n| High（高）| ≥9 | ≥7 | 需要立即关注的重要改进 |\n| Medium（中）| ≥7 | - | 建议考虑的中等优先级改进 |\n| Low（低）| <7 | <7 | 可选的性能或风格改进 |\n\n相关源码：`pr_agent/tools/pr_code_suggestions.py:代码建议生成逻辑`\n\n### 自我反思机制\n\nimprove 工具包含 `self_reflect_on_suggestions` 方法，用于对生成的建议进行二次验证和改进：\n\n```python\nasync def self_reflect_on_suggestions(\n suggestion_list: List,\n patches_diff: str,\n model: str,\n prev_suggestions_str: str = \"\",\n dedicated_prompt: str = \"\"\n) -> str:\n```\n\n该方法接收原始建议列表、补丁差异、模型名称和历史建议，通过反思机制提升建议的质量和相关性。\n\n## 使用方式\n\n### 触发方式\n\n#### 自动触发\n\nimprove 工具可配置为在每次 PR 打开时自动运行。通过 GitHub App 的自动化配置实现，无需用户手动干预。\n\n#### 手动调用\n\n在 PR 评论中输入以下指令触发：\n\n```\n/improve\n```\n\n### 配置参数\n\nimprove 工具通过 `pr_code_suggestions` 配置节进行设置。支持以下配置方式：\n\n#### 评论指令配置\n\n```\n/improve --pr_code_suggestions.some_config1=... --pr_code_suggestions.some_config2=...\n```\n\n#### 配置文件配置\n\n```yaml\n[pr_code_suggestions]\nsome_config1=...\nsome_config2=...\n```\n\n配置文件路径：`pr_agent/settings/configuration.toml` 中的 `pr_code_suggestions` 部分。\n\n## 架构设计\n\n### 工作流程\n\n```mermaid\ngraph TD\n A[PR 代码变更] --> B[代码扫描模块]\n B --> C{分析引擎}\n C --> D[生成建议列表]\n D --> E[自我反思验证]\n E --> F[评分排序]\n F --> G[格式化输出]\n G --> H[发布到 PR 评论]\n H --> I[持久化历史记录]\n```\n\n### 组件结构\n\n| 组件 | 职责 | 源码位置 |\n|------|------|---------|\n| CodeSuggestions | 主处理类，协调整个流程 | `pr_agent/tools/pr_code_suggestions.py` |\n| 提示生成器 | 构建 LLM 提示词 | `pr_code_suggestions_prompts.toml` |\n| 反思模块 | 验证和改进建议质量 | `pr_code_suggestions_reflect_prompts.toml` |\n| 评分引擎 | 计算建议优先级 | `get_score_str()` 方法 |\n| 输出格式化 | 生成 Markdown 输出 | `pr_agent/algo/utils.py` |\n\n## 输出格式\n\n### 建议展示结构\n\n每个代码建议以折叠详情块形式展示：\n\n```markdown\n<details><summary>建议摘要</summary>\n\n___\n**建议内容描述**\n\n[相关文件 范围](代码链接)\n\n```代码示例\n```\n\n<details><summary>建议重要性评分</summary>\n\nWhy: 评分理由说明\n\n</details>\n\n</details>\n```\n\n### 评分显示\n\n建议以表格形式组织，包含文件变更和评分信息：\n\n```html\n<tr>\n <td>建议详情</td>\n <td align=center>High/Medium/Low</td>\n</tr>\n```\n\n## 配置选项\n\n### 常用配置项\n\n| 配置项 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| enable_help_comment | bool | true | 显示帮助信息 |\n| new_score_mechanism | bool | false | 启用新的评分机制 |\n| new_score_mechanism_th_high | int | 9 | 高优先级阈值 |\n| new_score_mechanism_th_medium | int | 7 | 中优先级阈值 |\n\n### 相关配置文档\n\n- 详细配置选项：配置文件参考\n- 自定义标签：自定义标签使用指南\n\n## 提示词模板\n\n### 主要提示模板\n\n工具使用 `pr_code_suggestions_prompts.toml` 中定义的提示词与 LLM 交互，模板包含：\n\n- 代码分析指令\n- 输出格式规范\n- 评估标准定义\n\n### 反思提示模板\n\n`pr_code_suggestions_reflect_prompts.toml` 提供反思验证的提示词，确保生成的建议：\n\n- 与代码实际变更相关\n- 避免冗余或矛盾\n- 具有实际可操作性\n\n## 持久化机制\n\nimprove 工具支持建议历史记录的持久化存储：\n\n1. **历史记录管理**：最多保留指定数量的历史建议\n2. **自动清理**：当历史记录超过上限时，移除最早的条目\n3. **状态追踪**：通过 ✅ 标记确认的建议\n\n持久化数据存储在 PR 评论中，包含当前建议和历史建议两部分。\n\n## 相关文档\n\n- 使用指南：improve 工具详细使用说明\n- 配置选项：完整的配置参数文档\n- 自动化配置：GitHub App 自动触发配置\n- 工具对比：与其他 PR-Agent 工具的配合使用\n\n## 参考资料\n\n- 核心实现：[pr_agent/tools/pr_code_suggestions.py](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/tools/pr_code_suggestions.py)\n- 使用指南：[pr_agent/servers/help.py](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/servers/help.py)\n- 输出格式化：[pr_agent/algo/utils.py](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/algo/utils.py)\n- 配置管理：[pr_agent/tools/pr_config.py](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/tools/pr_config.py)\n- 开发规范：[AGENTS.md](https://github.com/The-PR-Agent/pr-agent/blob/main/AGENTS.md)\n\n---\n\n<a id='git_providers'></a>\n\n## Git 平台集成\n\n### 相关页面\n\n相关主题：[系统架构](#system_architecture), [部署方式](#deployment)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [pr_agent/algo/utils.py](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/algo/utils.py)\n- [pr_agent/tools/pr_description.py](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/tools/pr_description.py)\n- [pr_agent/servers/help.py](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/servers/help.py)\n- [pr_agent/tools/pr_code_suggestions.py](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/tools/pr_code_suggestions.py)\n- [pr_agent/git_providers/git_provider.py](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/git_providers/git_provider.py)\n- [pr_agent/tools/pr_update_changelog.py](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/tools/pr_update_changelog.py)\n</details>\n\n# Git 平台集成\n\n## 概述\n\nPR-Agent 的 Git 平台集成模块是连接核心功能与各类代码托管平台的核心抽象层。该模块通过统一的接口设计，支持 GitHub、GitLab、Bitbucket、Azure DevOps、Gitea 和 Gerrit 等主流 Git 平台，实现了 PR-Agent 工具在不同平台间的无缝切换与功能一致性。\n\n集成架构的核心是抽象基类 `GitProvider`，它定义了所有平台提供商必须实现的标准接口方法，包括 PR 信息获取、评论发布、文件操作等关键功能。资料来源：[pr_agent/git_providers/git_provider.py:1-100]()\n\n## 架构设计\n\n### 核心抽象层\n\n```mermaid\ngraph TD\n A[PR-Agent 工具层] --> B[GitProvider 抽象基类]\n B --> C[GithubProvider]\n B --> D[GitlabProvider]\n B --> E[BitbucketProvider]\n B --> F[AzureDevOpsProvider]\n B --> G[GiteaProvider]\n B --> H[GerritProvider]\n \n C --> I[GitHub API]\n D --> J[GitLab API]\n E --> K[Bitbucket API]\n F --> L[Azure DevOps API]\n G --> M[Gitea API]\n H --> N[Gerrit Review API]\n```\n\n### 功能支持矩阵\n\n| 平台 | GFM Markdown | 自定义标签 | PR 图表 | 代码建议 | 自动评审 |\n|------|-------------|-----------|---------|---------|---------|\n| GitHub | ✅ | ✅ | ✅ | ✅ | ✅ |\n| GitLab | ✅ | ✅ | ✅ | ✅ | ✅ |\n| Bitbucket | 部分支持 | ❌ | ❌ | ✅ | ✅ |\n| Azure DevOps | ✅ | ✅ | ✅ | ✅ | ✅ |\n| Gitea | ✅ | ✅ | ✅ | ✅ | ✅ |\n| Gerrit | ❌ | ❌ | ❌ | ✅ | ✅ |\n\n资料来源：[pr_agent/tools/pr_description.py:1-50]()\n\n## GitProvider 基类接口\n\n### 核心方法定义\n\n`GitProvider` 基类定义了所有平台提供商必须实现的接口规范：\n\n| 方法 | 功能描述 | 返回类型 |\n|------|---------|---------|\n| `get_git_repo_url(issues_or_pr_url)` | 从 PR/Issue URL 提取仓库 URL | `str` |\n| `get_canonical_url_parts(repo_git_url, desired_branch)` | 获取平台特定的 URL 前缀和后缀 | `Tuple[str, str]` |\n| `clone(repo_url, dest, remove_dest_folder)` | 克隆仓库到指定目录 | `ScopedClonedRepo` |\n| `get_pr_description(full)` | 获取 PR 描述 | `str` |\n| `get_pr_branch()` | 获取当前 PR 的源分支 | `str` |\n| `publish_comment(body)` | 发布评论到 PR | `bool` |\n| `get_diff_files()` | 获取 PR 的文件变更列表 | `List[DiffFile]` |\n\n资料来源：[pr_agent/git_providers/git_provider.py:1-80]()\n\n### ScopedClonedRepo 临时克隆管理\n\n`ScopedClonedRepo` 是一个上下文管理器，用于安全地处理临时仓库克隆：\n\n```python\nclass ScopedClonedRepo(object):\n def __init__(self, dest_path: str, remove_on_exit: bool = True):\n self.path = dest_path\n self._should_remove = remove_on_exit\n```\n\n使用示例：\n\n```python\nwith TemporaryDirectory() as tmp_dir:\n returned_obj: GitProvider.ScopedClonedRepo = self.git_provider.clone(\n self.repo_url, tmp_dir, remove_dest_folder=False\n )\n print(returned_obj.path) # 使用返回的路径\n# 此时 returned_obj.path 随时可能被清理，不再使用\n```\n\n资料来源：[pr_agent/git_providers/git_provider.py:80-100]()\n\n## 平台特定实现\n\n### GitHub Provider\n\nGitHub Provider 是最完整的实现，支持所有 PR-Agent 功能特性，包括：\n\n- **GFM (GitHub Flavored Markdown)** 格式支持\n- PR 图表生成\n- 自定义标签处理\n- 自动化触发配置\n\nGitHub Provider 在处理帮助信息时的格式：\n\n```markdown\n> <details> <summary>Need help?</summary>\n> <li>Type <code>/help how to ...</code> in the comments thread</li>\n> <li>Check out the <a href=\"...\">documentation</a></li>\n> </details>\n```\n\n资料来源：[pr_agent/tools/pr_description.py:50-80]()\n\n### GitLab Provider\n\nGitLab Provider 适配 GitLab 的 Markdown 格式差异，帮助信息展示略有不同：\n\n```markdown\n<details><summary>Need help?</summary>\n- Type <code>/help how to ...</code> in the comments thread<br>\n- Check out the <a href=\"...\">documentation</a></li></details>\n```\n\n资料来源：[pr_agent/tools/pr_description.py:80-100]()\n\n### 其他平台\n\nBitbucket、Azure DevOps、Gitea 和 Gerrit Provider 均继承 `GitProvider` 基类，实现了各自平台 API 的适配层。各平台的差异主要体现在：\n\n1. **API 认证方式不同**\n2. **Markdown 渲染能力差异**\n3. **评审功能 API 支持程度**\n\n## Markdown 渲染适配\n\n### GFM 支持检测\n\n各工具通过 `is_supported(\"gfm_markdown\")` 方法检测平台是否支持 GitHub Flavored Markdown：\n\n```python\nenable_pr_diagram = (\n get_settings().pr_description.get(\"enable_pr_diagram\", False) \n and self.git_provider.is_supported(\"gfm_markdown\")\n)\n```\n\n资料来源：[pr_agent/tools/pr_description.py:100-150]()\n\n### 格式转换逻辑\n\n工具层根据平台能力自动选择合适的输出格式：\n\n```mermaid\ngraph LR\n A[数据生成] --> B{平台支持GFM?}\n B -->|是| C[使用details/summary标签]\n B -->|否| D[使用标准Markdown]\n C --> E[可折叠区域]\n D --> F[纯文本描述]\n```\n\nGFM 支持时的输出示例：\n\n```html\n<details><summary><strong>推荐审查重点区域</strong></summary>\n\n相关代码行...\n\n</details>\n```\n\n非 GFM 平台的标准输出：\n\n```markdown\n**推荐审查重点区域**\n\n相关代码行...\n```\n\n资料来源：[pr_agent/algo/utils.py:1-80]()\n\n## 文件变更处理\n\n### Diff 文件结构\n\n`get_diff_files()` 返回的文件变更对象包含以下属性：\n\n| 属性 | 描述 |\n|------|------|\n| `filename` | 文件路径 |\n| `patch` | 统一差异格式 |\n| `num_plus_lines` | 新增行数 |\n| `num_minus_lines` | 删除行数 |\n| `head_file` | 文件完整内容 |\n\n资料来源：[pr_agent/tools/pr_description.py:200-250]()\n\n### 相关代码行提取\n\n`extract_relevant_lines_str` 函数负责从变更中提取指定行号的代码：\n\n```python\ndef extract_relevant_lines_str(end_line, files, relevant_file, start_line, dedent=False) -> str:\n # 从 files 中查找目标文件\n # 优先使用 head_file 内容\n # 回退方案：从 patch 中提取\n```\n\n资料来源：[pr_agent/algo/utils.py:150-200]()\n\n### 变更统计展示\n\n在 PR 描述中展示变更统计：\n\n```python\nfor f in diff_files:\n if f.filename.lower().strip('/') == filename.lower().strip('/'):\n num_plus_lines = f.num_plus_lines\n num_minus_lines = f.num_minus_lines\n diff_plus_minus += f\"+{num_plus_lines}/-{num_minus_lines}\"\n```\n\n资料来源：[pr_agent/tools/pr_description.py:250-300]()\n\n## 代码建议集成\n\n### 建议输出格式\n\n代码建议通过 `<details>` 标签实现可折叠展示：\n\n```html\n<details><summary>建议摘要</summary>\n\n___\n\n**详细建议内容**\n\n[文件名 行号范围](链接)\n\n```代码示例\n```\n\n<details><summary>建议重要性[1-10]: 8</summary>\n\nWhy: 重要性说明...\n\n</details>\n\n</details>\n```\n\n资料来源：[pr_agent/tools/pr_code_suggestions.py:1-80]()\n\n### 评分机制\n\n代码建议采用三级评分体系：\n\n| 分数范围 | 等级标识 | 阈值配置 |\n|---------|---------|---------|\n| ≥ 9 | High | `new_score_mechanism_th_high` |\n| 7-8 | Medium | `new_score_mechanism_th_medium` |\n| < 7 | Low | 默认阈值 |\n\n资料来源：[pr_agent/tools/pr_code_suggestions.py:80-120]()\n\n## 配置与扩展\n\n### 平台配置项\n\n通过 `configuration.toml` 可配置的参数：\n\n| 配置项 | 描述 | 适用平台 |\n|--------|------|---------|\n| `git_provider` | 指定使用的 Git 平台 | 全局 |\n| `enable_gfm_markdown` | 启用 GFM 格式 | 全局 |\n| `collapsible_file_list_threshold` | 可折叠文件列表阈值 | GitHub, GitLab |\n\n资料来源：[pr_agent/servers/help.py:1-100]()\n\n### 新增平台支持\n\n要添加新的 Git 平台支持，需要：\n\n1. 创建新的 Provider 类继承 `GitProvider`\n2. 实现所有抽象方法\n3. 在工厂函数中注册新 Provider\n4. 添加平台特定格式适配逻辑\n\n## 安全注意事项\n\n- 所有敏感信息（如 API Token）通过环境变量注入，不硬编码于代码中\n- 平台 API 凭证通过 GitHub Actions Secrets 管理\n- 临时克隆的仓库路径使用完自动清理\n\n资料来源：[pr_agent/git_providers/git_provider.py:100-120]()\n\n## 相关文档\n\n- [PR Review 工具文档](https://pr-agent-docs.codium.ai/tools/review/)\n- [代码建议工具文档](https://pr-agent-docs.codium.ai/tools/improve/)\n- [PR 描述工具文档](https://pr-agent-docs.codium.ai/tools/describe/)\n- [配置文件指南](https://pr-agent-docs.codium.ai/usage-guide/configuration_options/)\n\n---\n\n<a id='deployment'></a>\n\n## 部署方式\n\n### 相关页面\n\n相关主题：[Git 平台集成](#git_providers), [配置管理](#configuration)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [action.yaml](https://github.com/The-PR-Agent/pr-agent/blob/main/action.yaml)\n- [Dockerfile.github_action](https://github.com/The-PR-Agent/pr-agent/blob/main/Dockerfile.github_action)\n- [docker/Dockerfile](https://github.com/The-PR-Agent/pr-agent/blob/main/docker/Dockerfile)\n- [pr_agent/servers/github_app.py](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/servers/github_app.py)\n- [pr_agent/servers/gitlab_webhook.py](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/servers/gitlab_webhook.py)\n- [pr_agent/servers/bitbucket_app.py](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/servers/bitbucket_app.py)\n- [pr_agent/cli.py](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/cli.py)\n</details>\n\n# 部署方式\n\nPR-Agent 是一个多平台支持的 PR 处理工具，支持多种部署方式以适应不同的开发环境和平台需求。本文详细介绍每种部署方式的核心架构、配置方法和使用场景。\n\n## 概述\n\nPR-Agent 的部署架构设计遵循灵活性原则，支持从自动化 GitHub Action 到本地 CLI 的多种运行模式。不同的部署方式针对不同的使用场景进行了优化，确保用户可以根据其基础设施选择最合适的方案。\n\n```mermaid\ngraph TD\n A[PR-Agent 部署方式] --> B[GitHub Action]\n A --> C[Docker 容器]\n A --> D[GitHub App]\n A --> E[GitLab Webhook]\n A --> F[Bitbucket App]\n A --> G[CLI 本地运行]\n \n B --> B1[自动触发]\n B --> B2[工作流配置]\n \n C --> C1[独立部署]\n C --> C2[自定义镜像]\n \n D --> D1[Webhook 接收]\n D --> D2[持久化服务]\n \n G --> G1[手动执行]\n G --> G2[本地开发]\n```\n\n## GitHub Action 部署\n\nGitHub Action 是推荐的部署方式，适合大多数自动化 PR 审查场景。通过在仓库中创建工作流文件，可以实现 PR 打开或更新时自动触发审查。\n\n### 工作流配置\n\n使用 GitHub Action 部署需要创建 `.github/workflows/pr-agent.yml` 文件：\n\n```yaml\nname: PR Agent\non:\n pull_request:\n types: [opened, synchronize]\njobs:\n pr_agent_job:\n runs-on: ubuntu-latest\n steps:\n - name: PR Agent action step\n uses: the-pr-agent/pr-agent@main\n env:\n OPENAI_KEY: ${{ secrets.OPENAI_KEY }}\n GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}\n```\n\n资料来源：[README.md]()\n\n### 环境变量配置\n\nGitHub Action 部署支持通过环境变量传递敏感信息和配置参数。常用配置项包括：\n\n| 环境变量 | 说明 | 必需 |\n|---------|------|-----|\n| `OPENAI_KEY` | OpenAI API 密钥 | 是 |\n| `GITHUB_TOKEN` | GitHub 访问令牌 | 是 |\n| `GITLAB_TOKEN` | GitLab 访问令牌（用于 GitLab 平台） | 否 |\n| `CONFIG.GIT_PROVIDER` | Git 提供商类型 | 否 |\n\n资料来源：[action.yaml]()\n\n### 触发机制\n\nGitHub Action 模式下，PR-Agent 支持以下触发类型：\n\n- `pull_request.opened` - PR 创建时\n- `pull_request.synchronize` - PR 更新时\n- `pull_request.edited` - PR 编辑时\n\n## Docker 容器部署\n\nDocker 部署提供了最大的灵活性，适合需要自定义运行环境或与其他服务集成的场景。\n\n### 镜像选择\n\n| 镜像版本 | 仓库 | 说明 |\n|---------|------|-----|\n| 0.34.2 及之后 | `pragent/pr-agent` | 官方新版镜像 |\n| 0.31 及之前 | `codiumai/pr-agent` | 旧版归档镜像（不再更新） |\n\n资料来源：[README.md]()\n\n### Dockerfile 结构\n\n主镜像的 Dockerfile 位于 `docker/Dockerfile`，定义了完整的运行时环境：\n\n```dockerfile\nFROM python:3.11-slim\n# 包含所有运行时依赖和 PR-Agent 核心代码\n```\n\nGitHub Action 专用 Dockerfile (`Dockerfile.github_action`) 针对 Action 环境进行了优化，体积更小。\n\n### 自定义镜像构建\n\n如需自定义配置，可以基于官方镜像构建：\n\n```dockerfile\nFROM pragent/pr-agent:latest\n# 添加自定义配置或插件\n```\n\n## GitHub App 部署\n\nGitHub App 部署方式适合需要持续运行服务并管理多个仓库的场景。通过创建 GitHub App，可以实现跨仓库的自动化 PR 处理。\n\n### 核心架构\n\n```mermaid\ngraph LR\n A[GitHub Webhook] --> B[pr_agent/servers/github_app.py]\n B --> C[事件处理器]\n C --> D[PR 工具执行]\n D --> E[评论/更新 PR]\n```\n\n### 服务启动\n\nGitHub App 服务器通过 `pr_agent/servers/github_app.py` 实现，核心启动流程包括：\n\n1. 注册 Webhook 端点\n2. 验证 GitHub App 凭证\n3. 监听 PR 相关事件\n4. 执行相应的 PR 工具\n5. 将结果发布到 PR 评论\n\n资料来源：[pr_agent/servers/github_app.py]()\n\n### 配置参数\n\n| 参数 | 说明 | 来源 |\n|-----|------|-----|\n| `WEBHOOK_SECRET` | Webhook 签名验证密钥 | 环境变量 |\n| `APP_ID` | GitHub App ID | 配置 |\n| `PRIORITY_TOKENS` | API 调用优先级配置 | 配置文件 |\n\n## GitLab Webhook 部署\n\n对于使用 GitLab 的团队，PR-Agent 提供了专门的 Webhook 集成方案。\n\n### 事件处理\n\n```mermaid\ngraph TD\n A[GitLab MR 事件] --> B[pr_agent/servers/gitlab_webhook.py]\n B --> C{事件类型判断}\n C -->|MR 打开/更新| D[MR Review 工具]\n C -->|代码更新| E[MR 描述工具]\n C -->|提问| F[MR Ask 工具]\n \n D --> G[发布评论]\n E --> G\n F --> G\n```\n\n### 特定功能\n\nGitLab 部署模式包含平台特定的 UI 元素，如帮助评论格式：\n\n```python\npr_body += (\"\\n\\n___\\n\\n<details><summary>Need help?</summary>- Type <code>/help how to ...</code> \"\n \"in the comments thread for any questions about PR-Agent usage.<br>- Check out the \"\n \"<a href='https://qodo-merge-docs.qodo.ai/usage-guide/'>documentation</a> for more information.</details>\")\n```\n\n资料来源：[pr_agent/tools/pr_description.py]()\n\n## Bitbucket App 部署\n\nBitbucket 平台支持通过专用 App 服务器实现，核心实现在 `pr_agent/servers/bitbucket_app.py`。\n\n### 与其他平台的差异\n\n| 特性 | GitHub | GitLab | Bitbucket |\n|-----|--------|--------|-----------|\n| Webhook 格式 | JSON | JSON | JSON |\n| 评论 API | REST | REST | REST |\n| 权限模型 | App Token | Access Token | OAuth |\n\n资料来源：[pr_agent/servers/bitbucket_app.py]()\n\n## CLI 本地运行\n\nCLI 方式适合本地开发测试或一次性执行场景。\n\n### 安装与配置\n\n```bash\npip install pr-agent\nexport OPENAI_KEY=your_key_here\npr-agent --pr_url https://github.com/owner/repo/pull/123 review\n```\n\n资料来源：[README.md]()\n\n### CLI 命令行接口\n\n`pr_agent/cli.py` 实现了命令行入口，支持以下操作模式：\n\n```mermaid\ngraph TD\n A[pr-agent CLI] --> B[--pr_url 参数]\n A --> C[--local_repo 参数]\n \n B --> D[远程 PR 处理]\n C --> E[本地仓库处理]\n \n D --> F[review]\n D --> G[describe]\n D --> H[improve]\n D --> I[ask]\n \n E --> F\n E --> G\n E --> H\n E --> I\n```\n\n### 可用命令\n\n| 命令 | 功能 |\n|-----|-----|\n| `review` | 生成 PR 审查意见 |\n| `describe` | 生成 PR 描述 |\n| `improve` | 提供代码改进建议 |\n| `ask` | 回答关于 PR 的问题 |\n\n资料来源：[pr_agent/cli.py]()\n\n## 部署方式对比\n\n### 适用场景矩阵\n\n| 部署方式 | 自动化程度 | 多仓库支持 | 配置复杂度 | 推荐场景 |\n|---------|-----------|-----------|-----------|---------|\n| GitHub Action | 高 | 否 | 低 | 单仓库自动化 |\n| Docker | 中 | 可配置 | 中 | 自定义环境 |\n| GitHub App | 高 | 是 | 中 | 组织级部署 |\n| GitLab Webhook | 高 | 可配置 | 中 | GitLab 用户 |\n| Bitbucket App | 高 | 是 | 中 | Bitbucket 用户 |\n| CLI | 低 | 否 | 低 | 本地测试开发 |\n\n### 性能考虑\n\n不同部署方式的性能特性：\n\n- **GitHub Action**：冷启动时间约 30-60 秒，适合非实时场景\n- **Docker 容器**：启动快，适合高频调用\n- **App 服务器**：常驻内存，响应最快，但需要维护基础设施\n\n## 配置管理\n\n无论采用哪种部署方式，PR-Agent 都通过统一的配置系统管理参数。\n\n### 配置文件位置\n\n| 部署方式 | 配置文件 |\n|---------|---------|\n| GitHub Action | 环境变量或 secrets |\n| Docker | 挂载配置文件或环境变量 |\n| App 服务器 | 配置文件或环境变量 |\n| CLI | `.pr_agent.toml` 或环境变量 |\n\n### 配置示例\n\n```yaml\n[pr_description]\nenable_help_comment = true\nenable_ai_tags = true\n\n[pr_reviewer]\nextra_instructions = \"\"\"\n- Focus on security issues\n- Check test coverage\n\"\"\"\n```\n\n资料来源：[pr_agent/algo/utils.py]()\n\n## 安全建议\n\n### 密钥管理\n\n| 部署方式 | 推荐密钥管理 |\n|---------|-------------|\n| GitHub Action | GitHub Secrets |\n| Docker | 环境变量或 Kubernetes Secrets |\n| App 服务器 | 外部密钥管理服务 |\n| CLI | 本地环境变量 |\n\n### 权限最小化\n\n- GitHub App 应仅请求必要的仓库权限\n- Access Token 应设置最小作用域\n- 定期轮换 API 密钥\n\n资料来源：[AGENTS.md]()\n\n## 故障排除\n\n### 常见问题\n\n| 问题 | 可能原因 | 解决方案 |\n|-----|---------|---------|\n| Action 无法触发 | Webhook 未正确配置 | 检查仓库 Webhook 设置 |\n| 权限错误 | Token 权限不足 | 更新 App 权限或 Token 作用域 |\n| 超时 | 模型响应慢 | 调整超时配置或优化提示词 |\n| 评论未发布 | GFM 不支持 | 检查平台 Markdown 支持 |\n\n### 日志调试\n\n启用调试日志查看详细执行信息：\n\n```yaml\n[config]\ndebug = true\n```\n\n## 升级与迁移\n\n### 版本 0.34.2+ 变化\n\nv0.34.2 起，官方镜像从 `codiumai/pr-agent` 迁移到 `pragent/pr-agent`。升级时需更新：\n\n```yaml\n# 旧版\nimage: pragent/pr-agent:v0.31\n\n# 新版\nimage: pragent/pr-agent:0.34.2\n```\n\n资料来源：[README.md]()\n\n## 总结\n\nPR-Agent 提供了丰富的部署方式选择，从简单的 GitHub Action 到完整的企业级 App 服务器，用户可以根据实际需求选择最适合的方案。建议大多数用户从 GitHub Action 开始，随着需求增长再考虑迁移到更复杂的部署架构。\n\n---\n\n<a id='configuration'></a>\n\n## 配置管理\n\n### 相关页面\n\n相关主题：[扩展与定制](#customization), [部署方式](#deployment)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [pr_agent/tools/pr_description.py](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/tools/pr_description.py)\n- [pr_agent/servers/help.py](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/servers/help.py)\n- [pr_agent/algo/utils.py](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/algo/utils.py)\n- [pr_agent/tools/pr_code_suggestions.py](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/tools/pr_code_suggestions.py)\n- [pr_agent/tools/pr_config.py](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/tools/pr_config.py)\n</details>\n\n# 配置管理\n\n## 概述\n\nPR Agent 的配置管理系统负责管理所有工具和功能的配置选项，包括 PR 描述生成、代码审查、代码建议等。该系统支持通过 TOML 配置文件、环境变量和命令行注释三种方式进行配置覆盖。\n\n资料来源：[pr_agent/tools/pr_description.py:1-50]()\n\n## 配置架构\n\n```mermaid\ngraph TD\n A[配置源] --> B[配置加载器]\n B --> C[get_settings 全局访问]\n C --> D[pr_description 配置段]\n C --> E[pr_code_suggestions 配置段]\n C --> F[pr_reviewer 配置段]\n D --> G[describe 工具]\n E --> H[improve 工具]\n F --> I[review 工具]\n```\n\n## 配置加载机制\n\n### 核心访问方式\n\n系统通过 `get_settings()` 函数提供全局配置访问接口，这是所有模块获取配置的首选方式。\n\n```python\nif get_settings().pr_description.enable_help_comment and self.git_provider.is_supported(\"gfm_markdown\"):\n # 配置访问示例\n```\n\n资料来源：[pr_agent/tools/pr_description.py:1-10]()\n\n### 配置输出功能\n\n`show_relevant_configurations` 函数用于将相关配置以可读的 Markdown 格式输出到 PR 评论中：\n\n```python\nif get_settings().get('config', {}).get('output_relevant_configurations', False):\n pr_body += show_relevant_configurations(relevant_section='pr_description')\n```\n\n资料来源：[pr_agent/tools/pr_description.py:1-10]()\n\n## 配置分段\n\nPR Agent 的配置按照功能模块划分为多个配置段：\n\n| 配置段 | 功能描述 | 触发工具 |\n|--------|----------|----------|\n| `pr_description` | PR 描述生成配置 | `/describe` |\n| `pr_code_suggestions` | 代码建议配置 | `/improve` |\n| `pr_reviewer` | 代码审查配置 | `/review` |\n| `config` | 全局通用配置 | 所有工具 |\n\n资料来源：[pr_agent/servers/help.py:1-50]()\n\n## 配置使用示例\n\n### 工具内访问配置\n\n在工具实现中，配置通过 `get_settings()` 访问特定配置段：\n\n```python\nth_high = get_settings().pr_code_suggestions.get('new_score_mechanism_th_high', 9)\nth_medium = get_settings().pr_code_suggestions.get('new_score_mechanism_th_medium', 7)\nif score >= th_high:\n return \"High\"\n```\n\n资料来源：[pr_agent/tools/pr_code_suggestions.py:1-50]()\n\n### 条件性配置检查\n\n部分功能支持通过配置开关启用或禁用：\n\n```python\nif get_settings().pr_description.enable_help_comment:\n # 启用帮助注释功能\n```\n\n资料来源：[pr_agent/tools/pr_description.py:1-10]()\n\n## 配置输出格式\n\n配置信息以 YAML 格式输出，便于用户查看和调试：\n\n```yaml\n[config]\noutput_relevant_configurations: false\n\n[pr_description]\nenable_help_comment: true\n```\n\n资料来源：[pr_agent/tools/pr_config.py:1-20]()\n\n### 格式化输出函数\n\n`format_settings_to_markdown` 函数负责将配置转换为 Markdown 格式：\n\n```python\nmarkdown_text += f\"**[{relevant_section}]**\\n```yaml\\n\\n\"\nfor key, value in get_settings().get(relevant_section, {}).items():\n if key in skip_keys:\n continue\n markdown_text += f\"{key}: {value}\\n\"\n```\n\n资料来源：[pr_agent/algo/utils.py:1-50]()\n\n## 配置继承与覆盖\n\n系统支持配置值的继承和覆盖机制：\n\n| 优先级 | 配置方式 | 示例 |\n|--------|----------|------|\n| 高 | 命令行注释 | `/describe --pr_description.use_description_markers=true` |\n| 中 | 配置文件 | `.pr_agent.toml` |\n| 低 | 默认值 | `get_settings().get('key', 'default')` |\n\n资料来源：[pr_agent/servers/help.py:1-50]()\n\n## 用户配置方式\n\n### 注释配置\n\n用户可以通过 PR 评论直接修改配置：\n\n```\n/describe --pr_description.some_config1=... --pr_description.some_config2=...\n```\n\n### 配置文件\n\n支持通过 TOML 配置文件集中管理：\n\n```toml\n[pr_description]\nsome_config1=...\nsome_config2=...\n```\n\n资料来源：[pr_agent/servers/help.py:1-50]()\n\n## 工具配置指南\n\n### describe 工具配置\n\n```toml\n[pr_description]\n# 控制描述标记功能\nuse_description_markers=false\n# 启用帮助注释\nenable_help_comment=true\n```\n\n资料来源：[pr_agent/servers/help.py:1-50]()\n\n### improve 工具配置\n\n```toml\n[pr_code_suggestions]\n# 代码建议相关配置\nsome_config1=...\nsome_config2=...\n```\n\n资料来源：[pr_agent/servers/help.py:1-50]()\n\n## 最佳实践\n\n### 配置命名规范\n\n- 配置键名使用小写字母和下划线\n- 配置段名称使用功能模块名称作为前缀\n- 示例：`pr_description.enable_help_comment`\n\n### 配置默认值\n\n始终为配置项提供合理的默认值：\n\n```python\nth_high = get_settings().pr_code_suggestions.get('new_score_mechanism_th_high', 9)\n```\n\n资料来源：[pr_agent/tools/pr_code_suggestions.py:1-50]()\n\n## 相关文件\n\n| 文件路径 | 功能描述 |\n|----------|----------|\n| `pr_agent/settings/configuration.toml` | 默认配置文件 |\n| `pr_agent/algo/utils.py` | 配置格式化工具 |\n| `pr_agent/tools/pr_config.py` | 配置显示工具 |\n\n## 总结\n\nPR Agent 的配置管理系统采用分层设计，通过 `get_settings()` 接口提供统一的配置访问。配置支持运行时修改，通过注释方式可以灵活调整工具行为，同时保留配置文件作为持久化配置方案。\n\n---\n\n<a id='customization'></a>\n\n## 扩展与定制\n\n### 相关页面\n\n相关主题：[配置管理](#configuration), [工具概述](#tools_overview)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [pr_agent/custom_merge_loader.py](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/custom_merge_loader.py)\n- [pr_agent/settings/custom_labels.toml](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/settings/custom_labels.toml)\n- [pr_agent/settings/ignore.toml](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/settings/ignore.toml)\n- [pr_agent/algo/file_filter.py](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/algo/file_filter.py)\n- [pr_agent/settings/pr_description_prompts.toml](https://github.com/The-PR-Agent/pr-agent/blob/main/pr_agent/settings/pr_description_prompts.toml)\n</details>\n\n# 扩展与定制\n\nPR-Agent 是一个高度可扩展的 Pull Request 处理工具，提供了丰富的定制能力，使开发者能够根据项目需求灵活配置工具行为。本文档详细介绍 PR-Agent 的扩展与定制机制，包括配置文件系统、自定义标签、文件过滤规则、自定义提示词等核心扩展点。\n\n## 架构概述\n\nPR-Agent 的扩展与定制系统采用模块化设计，核心扩展点包括配置加载器、自定义标签处理器、文件过滤器以及提示词模板系统。这种设计允许用户在不修改核心代码的情况下，自定义工具的各个方面，从标签分类到文件处理逻辑均可灵活调整。\n\n系统架构可以划分为以下几个主要层次：配置管理层负责加载和管理各类配置文件；扩展加载层处理自定义合并逻辑和插件机制；过滤处理层根据规则筛选文件；提示词生成层负责生成各类 AI 提示词。每一层都提供了相应的扩展接口，用户可以通过配置文件或代码扩展来定制行为。\n\n```mermaid\ngraph TD\n A[配置文件系统] --> B[配置加载器]\n A --> C[自定义标签系统]\n A --> D[忽略规则系统]\n B --> E[文件过滤器]\n E --> F[提示词生成器]\n C --> F\n D --> F\n G[扩展点注册] --> H[运行时加载]\n H --> B\n style A fill:#e1f5fe\n style F fill:#fff3e0\n```\n\n## 配置文件系统\n\n### 配置文件结构\n\nPR-Agent 使用 TOML 格式的配置文件，主要配置项集中在 `pr_agent/settings/configuration.toml` 文件中。该文件定义了所有工具的默认配置参数，包括 `pr_description`、`pr_code_suggestions`、`pr_reviewer` 等各个模块的配置选项。每个模块的配置都可以通过环境变量、配置文件或命令行参数进行覆盖。\n\n配置文件的组织结构采用分层设计，顶层配置包含通用设置，如模型选择、API 密钥等；各工具模块的专用配置则以子节的形式存在。例如，`pr_description` 节包含 `extra_instructions`、`enable_help_comment`、`enable_generated_files_label` 等配置项，这些配置项控制 PR 描述生成的具体行为。\n\n配置系统支持多种配置来源的优先级排序：命令行参数具有最高优先级，其次是环境变量，最后是配置文件中的默认值。这种设计确保了灵活性的同时，也保证了配置的一致性和可维护性。开发者可以通过修改配置文件来改变工具的默认行为，也可以为特定项目创建专属的配置覆盖。\n\n### 自定义配置加载\n\n自定义配置加载通过 `custom_merge_loader.py` 模块实现，该模块提供了一个可扩展的合并配置加载机制。当需要将多个配置源合并时，系统会按照预定义的优先级顺序加载各个配置项，并处理可能存在的冲突情况。合并策略支持深度合并，允许嵌套配置项的部分覆盖。\n\n```python\n# 配置合并加载示意\nclass ConfigMerger:\n def merge_configs(self, base_config, override_config):\n \"\"\"\n 深度合并配置项\n \"\"\"\n merged = base_config.copy()\n for key, value in override_config.items():\n if key in merged and isinstance(merged[key], dict) and isinstance(value, dict):\n merged[key] = self.merge_configs(merged[key], value)\n else:\n merged[key] = value\n return merged\n```\n\n配置加载器还支持动态配置重载，在某些场景下可能需要在运行时更新配置而不重启服务。通过监听配置文件的变化，系统可以自动检测并应用更新后的配置，实现热重载功能。这一特性对于需要频繁调整配置的生产环境特别有用。\n\n## 自定义标签系统\n\n### 标签配置格式\n\nPR-Agent 支持通过 `custom_labels.toml` 文件定义自定义标签，该文件位于 `pr_agent/settings/custom_labels.toml`。自定义标签允许项目根据自身需求定义 PR 分类标准，替代默认的通用标签（Bug fix、Tests、Enhancement、Documentation、Other）。标签配置采用简单的键值对格式，每个标签由标签名称和描述组成。\n\n默认标签配置提供了基础的 PR 类型分类，但在实际项目中，团队可能需要更细粒度的分类方式。自定义标签的定义格式为 `标签名 = \"描述文本\"`，系统会自动将这些自定义标签转换为 PR-Agent 可识别的标签格式。在生成 PR 描述时，工具会根据代码变更的内容自动匹配最合适的自定义标签。\n\n标签系统的设计考虑了向后兼容性，即使没有定义任何自定义标签，系统仍会使用默认标签集。此外，自定义标签可以随时添加或修改，工具会在下次运行时自动加载最新的标签配置。这种灵活性使得不同项目可以根据其领域和流程定义独特的标签体系。\n\n### 标签应用机制\n\n当 PR-Agent 处理 Pull Request 时，会分析代码变更的内容和模式，然后根据预设的标签定义进行分类。标签匹配算法会考虑文件路径、变更类型、代码模式等多个维度，以提高分类的准确性。用户还可以在提示词中指定标签的优先级顺序，确保最重要的标签类型优先被识别。\n\n标签应用还支持多标签场景，一个 PR 可以同时匹配多个标签。例如，一个同时包含性能优化和代码重构的 PR 可能会被标记为 \"Enhancement\" 和 \"Performance\"。这种多标签支持使得 PR 分类更加精确，能够更好地反映 PR 的完整内容。\n\n## 文件过滤与忽略规则\n\n### 忽略规则配置\n\n文件过滤机制由 `ignore.toml` 配置文件和 `file_filter.py` 模块共同实现。忽略规则允许用户指定哪些文件或目录应该被排除在分析之外，这对于大型项目特别重要，可以显著减少处理时间和避免噪音文件的干扰。忽略规则支持 glob 模式匹配，类似于 `.gitignore` 的语法。\n\n`ignore.toml` 文件定义了需要忽略的文件模式和目录列表。常见的忽略内容包括：依赖管理文件（如 `node_modules`、`vendor` 目录）、构建产物文件（如 `dist`、`build` 目录）、配置文件（如 IDE 配置）、大型二进制文件等。用户可以根据项目特点添加或修改这些规则。\n\n过滤规则按照优先级和范围进行组织，某些规则可能只对特定工具生效，而另一些规则则是全局性的。系统会按照规则定义的顺序进行匹配，第一个匹配的规则决定文件的处理方式。这种设计允许精细控制不同类型文件的处理策略。\n\n### 文件过滤器实现\n\n`file_filter.py` 模块是文件过滤的核心实现，提供了 `FileFilter` 类来处理文件路径的匹配逻辑。该模块导入了 TOML 配置文件并解析忽略规则，然后提供 `should_include` 方法来判断文件是否应该被包含在处理范围内。过滤器会检查文件路径是否匹配任何已定义的忽略模式，如果匹配则返回 False 表示忽略该文件。\n\n```python\n# 文件过滤器核心逻辑示意\ndef should_include(self, file_path: str) -> bool:\n \"\"\"\n 判断文件是否应该被包含在分析中\n \"\"\"\n for pattern in self.ignore_patterns:\n if self.matches_pattern(file_path, pattern):\n return False\n return True\n\ndef matches_pattern(self, file_path: str, pattern: str) -> bool:\n \"\"\"使用 glob 模式匹配\"\"\"\n # 实现包括精确匹配、前缀匹配、扩展名匹配等\n pass\n```\n\n文件过滤器还支持动态规则，即根据文件内容或元数据来决定是否忽略。例如，某些配置文件可能只在特定条件下需要分析。过滤器提供了扩展接口，允许开发者注册自定义的过滤函数，以满足更复杂的过滤需求。\n\n## 自定义提示词模板\n\n### 提示词配置结构\n\nPR-Agent 使用 TOML 格式的提示词模板文件来定义各种工具的 AI 提示词，其中 `pr_description_prompts.toml` 是最重要的配置文件之一。该文件定义了 PR 描述生成工具使用的所有提示词模板，包括标题生成、类型识别、总结撰写、详细说明等各个子任务的提示词。通过修改这些模板，用户可以定制工具生成 PR 描述的风格和内容重点。\n\n提示词模板采用参数化设计，允许在运行时插入动态内容。例如，模板中可能包含占位符如 `{pr_title}`、`{changed_files}` 等，系统会在实际生成时替换这些占位符为具体的 PR 信息。这种设计使得模板既易于阅读和维护，又能灵活适应不同的输入数据。\n\n模板系统还支持条件渲染，某些提示词内容可以根据配置或上下文条件选择性地包含或排除。这对于处理不同类型的 PR（如功能开发、缺陷修复、文档更新等）特别有用，可以为每种类型定义专门的处理逻辑。\n\n### 提示词扩展机制\n\n提示词扩展通过 `extra_instructions` 配置项实现，该配置项允许用户在不修改原始模板的情况下添加自定义指令。例如，用户可以在配置中添加如下内容来定制 PR 描述的生成风格：\n\n```toml\n[pr_description]\nextra_instructions = \"\"\"\n- PR 标题格式应为：'<PR类型>: <标题>'\n- 标题应简洁明了，最多 10 个单词\n- 总结部分应突出主要变更内容\n\"\"\"\n```\n\n`extra_instructions` 配置支持多行内容，可以使用 Markdown 格式来组织指令结构。这种设计使得提示词定制变得简单直观，无需深入了解模板引擎的工作原理。系统会在生成最终提示词时，将用户提供的额外指令追加到基础模板之后。\n\n## 工具配置选项\n\n### PR 描述工具配置\n\nPR 描述生成工具（`pr_description`）提供了丰富的配置选项，用于控制生成内容的各个方面。以下是主要配置项及其作用说明：\n\n| 配置项 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| `extra_instructions` | 字符串 | 空 | 额外的指令信息，用于定制生成行为 |\n| `enable_help_comment` | 布尔值 | true | 是否在 PR 描述中添加帮助提示 |\n| `enable_generated_files_label` | 布尔值 | true | 是否标记自动生成的文件 |\n| `use_description_markers` | 布尔值 | false | 是否使用标记替换模式 |\n| `publish_labels` | 布尔值 | true | 是否发布标签到 PR |\n| `publish_review_summary` | 布尔值 | true | 是否发布审查总结 |\n\n这些配置项可以通过命令行参数、配置文件或环境变量进行设置。配置项的设计遵循自解释原则，名称本身通常能够说明其功能。对于需要更精细控制的场景，可以组合使用多个配置项来实现所需的行为。\n\n### 代码建议工具配置\n\n代码建议工具（`pr_code_suggestions`）同样提供了详细的配置选项，用于控制代码改进建议的生成和展示方式。关键配置项包括建议的评分阈值、展示格式、是否启用自我反思等。评分阈值配置项 `new_score_mechanism_th_high` 和 `new_score_mechanism_th_medium` 用于定义高、中、低建议的分界线，帮助用户快速识别最重要的改进建议。\n\n建议的展示格式支持多种模式，包括表格形式、折叠面板形式等。用户可以根据所在平台的特性选择最适合的展示方式。自我反思机制允许工具在生成初始建议后进行二次分析，以提高建议的质量和准确性。\n\n## 扩展点与插件机制\n\n### 自定义合并加载器\n\n`custom_merge_loader.py` 模块是 PR-Agent 的核心扩展点之一，提供了自定义配置合并逻辑的加载机制。该模块定义了一个可扩展的加载器类，允许开发者注册自定义的配置处理函数或插件模块。通过这种机制，用户可以在不修改核心代码的情况下添加新的配置处理逻辑。\n\n加载器采用注册模式工作，开发者首先定义一个处理函数，然后将其注册到加载器实例中。注册时可以指定处理函数的优先级和作用范围，确保多个扩展能够协调工作。加载器会按照优先级顺序调用各个处理函数，并收集处理结果进行合并。\n\n这种设计模式的一个典型应用场景是：多团队共享同一个 PR-Agent 实例，但每个团队需要不同的配置策略。通过自定义合并加载器，可以实现基于团队或项目的配置隔离和覆盖，而无需维护多个独立的配置文件。\n\n### 扩展点注册表\n\n扩展点注册表维护了一个所有可用扩展点的中央索引，包括扩展点的名称、类型、描述和配置接口信息。开发者可以通过查询注册表来了解可用的扩展点，也可以注册新的扩展点供其他模块使用。注册表的实现采用了观察者模式，支持动态添加和移除扩展点。\n\n扩展点的定义包括以下几个关键属性：唯一标识符、类型分类、版本号、依赖声明和执行接口。版本号用于管理扩展点的演进，依赖声明确保扩展的正确加载顺序。执行接口定义了扩展点与主系统之间的交互方式，包括输入参数格式和返回值类型。\n\n## 配置优先级与合并策略\n\n### 优先级层级\n\nPR-Agent 的配置系统遵循明确的优先级层级，从高到低依次为：命令行参数、环境变量、运行时配置、配置文件、项目级配置、全局默认配置。这种层级设计确保了灵活性与一致性的平衡，用户可以根据需要选择最适合的配置方式。\n\n命令行参数适用于一次性调整或自动化脚本场景；环境变量适合容器化部署和持续集成环境；配置文件则是最常用的配置方式，适合大多数使用场景。项目级配置允许不同项目使用不同的配置集，而全局默认配置则提供了开箱即用的合理默认值。\n\n配置合并采用深度合并策略，对于嵌套的配置项，系统会递归地合并各层级的值。这意味着可以在高层级覆盖某个顶级配置项的同时，在低层级保持其他嵌套配置项的原始值。这种精细的控制能力对于复杂项目的配置管理至关重要。\n\n### 合并冲突处理\n\n当不同层级的配置出现冲突时，系统采用最后优先（Last-Write-Wins）的原则进行处理。具体实现中，系统会按照优先级从低到高依次处理各个配置源，后处理的配置源会覆盖先前的值。对于列表类型的配置项，默认行为是替换而非追加，除非特别配置为合并模式。\n\n某些配置项可能声明了特殊的合并规则，例如强制追加规则或智能合并规则。强制追加规则确保列表类型配置项的值会被追加而非替换，适用于标签列表、忽略模式列表等场景。智能合并规则则根据配置项的语义来决定合并策略，需要开发者正确声明配置项的类型和合并行为。\n\n## 最佳实践\n\n### 配置组织建议\n\n在组织 PR-Agent 配置时，推荐采用分层配置结构：全局配置文件存放通用设置，项目级配置文件存放特定于项目的设置，运行时配置用于动态调整。这种分层结构便于维护和版本控制，也能更好地支持多项目场景。\n\n建议将自定义标签定义和忽略规则单独存放，因为这些配置可能需要频繁调整。将提示词模板与业务逻辑配置分离，可以使模板更易于版本化和审阅。对于团队协作场景，应建立配置变更的评审流程，确保配置的合理性和一致性。\n\n### 性能优化考虑\n\n在配置大量忽略规则或复杂的自定义逻辑时，需要考虑性能影响。文件过滤操作在每次处理文件时都会被调用，因此过滤规则的效率直接影响工具的整体性能。建议使用简洁的 glob 模式而非复杂的正则表达式，避免在过滤逻辑中执行耗时的 I/O 操作。\n\n提示词模板的复杂度也会影响生成质量和响应时间。过于复杂的模板可能导致 AI 模型生成冗长或偏离主题的内容。建议定期审视和简化模板，移除不再使用的指令，保持模板的清晰和高效。对于高频使用的工具（如 PR 描述生成），尤其需要注意模板的优化。\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：The-PR-Agent/pr-agent\n\n摘要：发现 23 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：Publish linux/arm64 Docker image for github_app tag。\n\n## 1. 安装坑 · 来源证据：Publish linux/arm64 Docker image for github_app tag\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Publish linux/arm64 Docker image for github_app tag\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_8cb9e552d2e2452cbe958628f6e800b6 | https://github.com/The-PR-Agent/pr-agent/issues/2386 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 2. 安装坑 · 来源证据：[Bug] UnicodeDecodeError in gitea_provider.py when parsing binary files before extension filtering\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug] UnicodeDecodeError in gitea_provider.py when parsing binary files before extension filtering\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_52bd470b7b5e4be6858b290e41c93036 | https://github.com/The-PR-Agent/pr-agent/issues/2380 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 3. 安装坑 · 来源证据：v0.31\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.31\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ef0e5f5f982146d8bd002453b969c07f | https://github.com/The-PR-Agent/pr-agent/releases/tag/v0.31 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 4. 安装坑 · 来源证据：v0.34.2\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.34.2\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_4bc22335937e44c0b529ab84d1e69a60 | https://github.com/The-PR-Agent/pr-agent/releases/tag/v0.34.2 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 5. 配置坑 · 来源证据：AzureDevopsProvider.get_repo_settings drops chunks after the first, silently truncating .pr_agent.toml\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：AzureDevopsProvider.get_repo_settings drops chunks after the first, silently truncating .pr_agent.toml\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_4ee2a84ba307469b9b329a043a70a224 | https://github.com/The-PR-Agent/pr-agent/issues/2376 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 6. 配置坑 · 来源证据：Ticket context not scoped per PR in long-lived deployments — stale tickets leak between unrelated PRs\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Ticket context not scoped per PR in long-lived deployments — stale tickets leak between unrelated PRs\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_a9b90b0cfbbf4529b60d65f564f4592e | https://github.com/The-PR-Agent/pr-agent/issues/2383 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 7. 能力坑 · 来源证据：v0.34.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个能力理解相关的待验证问题：v0.34.1\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_eb46a134c8984cd8898e13f61602f165 | https://github.com/The-PR-Agent/pr-agent/releases/tag/v0.34.1 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 8. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:662766482 | https://github.com/The-PR-Agent/pr-agent | README/documentation is current enough for a first validation pass.\n\n## 9. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:662766482 | https://github.com/The-PR-Agent/pr-agent | last_activity_observed missing\n\n## 10. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:662766482 | https://github.com/The-PR-Agent/pr-agent | no_demo; severity=medium\n\n## 11. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：risks.safety_notes | github_repo:662766482 | https://github.com/The-PR-Agent/pr-agent | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 12. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:662766482 | https://github.com/The-PR-Agent/pr-agent | no_demo; severity=medium\n\n## 13. 安全/权限坑 · 来源证据：Bug + feature: `-i` (incremental review) crashes on Azure DevOps; needs full incremental support in AzureDevopsProvider\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Bug + feature: `-i` (incremental review) crashes on Azure DevOps; needs full incremental support in AzureDevopsProvider\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e65762126ba84855a8440bd9e5a685bb | https://github.com/The-PR-Agent/pr-agent/issues/2379 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 14. 安全/权限坑 · 来源证据：OSS build silently ignores best_practices.md (currently SaaS-only)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：OSS build silently ignores best_practices.md (currently SaaS-only)\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_f51f28cf40b14b7ca80598af4527661a | https://github.com/The-PR-Agent/pr-agent/issues/2377 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 15. 安全/权限坑 · 来源证据：feat: support agent skills for context-aware review guidance\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：feat: support agent skills for context-aware review guidance\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_59ad4ca55ca248f989c91ce40068cc6d | https://github.com/The-PR-Agent/pr-agent/issues/2384 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 16. 安全/权限坑 · 来源证据：litellm success/cost callbacks never fire from pr-agent's async run loop\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：litellm success/cost callbacks never fire from pr-agent's async run loop\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_42f0b36e0c434c939c49c91fc7ccb82a | https://github.com/The-PR-Agent/pr-agent/issues/2378 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 17. 安全/权限坑 · 来源证据：v0.29\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.29\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_fbfdef3db3f84afab5275f43224831e7 | https://github.com/The-PR-Agent/pr-agent/releases/tag/v0.29 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 18. 安全/权限坑 · 来源证据：v0.30\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.30\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ce6f886a0f6640eb8054f5119f22a126 | https://github.com/The-PR-Agent/pr-agent/releases/tag/v0.30 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 19. 安全/权限坑 · 来源证据：v0.32\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.32\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_b1dcd09b757642d08b7dc8d0e77c8b3f | https://github.com/The-PR-Agent/pr-agent/releases/tag/v0.32 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 20. 安全/权限坑 · 来源证据：v0.33\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.33\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_d138961299124bcfaa4cbc15b31c22df | https://github.com/The-PR-Agent/pr-agent/releases/tag/v0.33 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。\n\n## 21. 安全/权限坑 · 来源证据：v0.34\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.34\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_85169c37f8b4494baccd135014cbaffb | https://github.com/The-PR-Agent/pr-agent/releases/tag/v0.34 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。\n\n## 22. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:662766482 | https://github.com/The-PR-Agent/pr-agent | issue_or_pr_quality=unknown\n\n## 23. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:662766482 | https://github.com/The-PR-Agent/pr-agent | release_recency=unknown\n\n<!-- canonical_name: The-PR-Agent/pr-agent; human_manual_source: deepwiki_human_wiki -->\n", "summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。", "title": "Human Manual / 人类版说明书" }, "pitfall_log": { "asset_id": "pitfall_log", "filename": "PITFALL_LOG.md", "markdown": "# Pitfall Log / 踩坑日志\n\n项目：The-PR-Agent/pr-agent\n\n摘要：发现 23 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：Publish linux/arm64 Docker image for github_app tag。\n\n## 1. 安装坑 · 来源证据：Publish linux/arm64 Docker image for github_app tag\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Publish linux/arm64 Docker image for github_app tag\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_8cb9e552d2e2452cbe958628f6e800b6 | https://github.com/The-PR-Agent/pr-agent/issues/2386 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 2. 安装坑 · 来源证据：[Bug] UnicodeDecodeError in gitea_provider.py when parsing binary files before extension filtering\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug] UnicodeDecodeError in gitea_provider.py when parsing binary files before extension filtering\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_52bd470b7b5e4be6858b290e41c93036 | https://github.com/The-PR-Agent/pr-agent/issues/2380 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 3. 安装坑 · 来源证据：v0.31\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.31\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ef0e5f5f982146d8bd002453b969c07f | https://github.com/The-PR-Agent/pr-agent/releases/tag/v0.31 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 4. 安装坑 · 来源证据：v0.34.2\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.34.2\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_4bc22335937e44c0b529ab84d1e69a60 | https://github.com/The-PR-Agent/pr-agent/releases/tag/v0.34.2 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 5. 配置坑 · 来源证据：AzureDevopsProvider.get_repo_settings drops chunks after the first, silently truncating .pr_agent.toml\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：AzureDevopsProvider.get_repo_settings drops chunks after the first, silently truncating .pr_agent.toml\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_4ee2a84ba307469b9b329a043a70a224 | https://github.com/The-PR-Agent/pr-agent/issues/2376 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 6. 配置坑 · 来源证据：Ticket context not scoped per PR in long-lived deployments — stale tickets leak between unrelated PRs\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Ticket context not scoped per PR in long-lived deployments — stale tickets leak between unrelated PRs\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_a9b90b0cfbbf4529b60d65f564f4592e | https://github.com/The-PR-Agent/pr-agent/issues/2383 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 7. 能力坑 · 来源证据：v0.34.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个能力理解相关的待验证问题：v0.34.1\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_eb46a134c8984cd8898e13f61602f165 | https://github.com/The-PR-Agent/pr-agent/releases/tag/v0.34.1 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 8. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:662766482 | https://github.com/The-PR-Agent/pr-agent | README/documentation is current enough for a first validation pass.\n\n## 9. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:662766482 | https://github.com/The-PR-Agent/pr-agent | last_activity_observed missing\n\n## 10. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:662766482 | https://github.com/The-PR-Agent/pr-agent | no_demo; severity=medium\n\n## 11. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：risks.safety_notes | github_repo:662766482 | https://github.com/The-PR-Agent/pr-agent | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 12. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:662766482 | https://github.com/The-PR-Agent/pr-agent | no_demo; severity=medium\n\n## 13. 安全/权限坑 · 来源证据：Bug + feature: `-i` (incremental review) crashes on Azure DevOps; needs full incremental support in AzureDevopsProvider\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Bug + feature: `-i` (incremental review) crashes on Azure DevOps; needs full incremental support in AzureDevopsProvider\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e65762126ba84855a8440bd9e5a685bb | https://github.com/The-PR-Agent/pr-agent/issues/2379 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 14. 安全/权限坑 · 来源证据：OSS build silently ignores best_practices.md (currently SaaS-only)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：OSS build silently ignores best_practices.md (currently SaaS-only)\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_f51f28cf40b14b7ca80598af4527661a | https://github.com/The-PR-Agent/pr-agent/issues/2377 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 15. 安全/权限坑 · 来源证据：feat: support agent skills for context-aware review guidance\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：feat: support agent skills for context-aware review guidance\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_59ad4ca55ca248f989c91ce40068cc6d | https://github.com/The-PR-Agent/pr-agent/issues/2384 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 16. 安全/权限坑 · 来源证据：litellm success/cost callbacks never fire from pr-agent's async run loop\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：litellm success/cost callbacks never fire from pr-agent's async run loop\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_42f0b36e0c434c939c49c91fc7ccb82a | https://github.com/The-PR-Agent/pr-agent/issues/2378 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 17. 安全/权限坑 · 来源证据：v0.29\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.29\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_fbfdef3db3f84afab5275f43224831e7 | https://github.com/The-PR-Agent/pr-agent/releases/tag/v0.29 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 18. 安全/权限坑 · 来源证据：v0.30\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.30\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ce6f886a0f6640eb8054f5119f22a126 | https://github.com/The-PR-Agent/pr-agent/releases/tag/v0.30 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 19. 安全/权限坑 · 来源证据：v0.32\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.32\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_b1dcd09b757642d08b7dc8d0e77c8b3f | https://github.com/The-PR-Agent/pr-agent/releases/tag/v0.32 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 20. 安全/权限坑 · 来源证据：v0.33\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.33\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_d138961299124bcfaa4cbc15b31c22df | https://github.com/The-PR-Agent/pr-agent/releases/tag/v0.33 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。\n\n## 21. 安全/权限坑 · 来源证据：v0.34\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.34\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_85169c37f8b4494baccd135014cbaffb | https://github.com/The-PR-Agent/pr-agent/releases/tag/v0.34 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。\n\n## 22. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:662766482 | https://github.com/The-PR-Agent/pr-agent | issue_or_pr_quality=unknown\n\n## 23. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:662766482 | https://github.com/The-PR-Agent/pr-agent | release_recency=unknown\n", "summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。", "title": "Pitfall Log / 踩坑日志" }, "prompt_preview": { "asset_id": "prompt_preview", "filename": "PROMPT_PREVIEW.md", "markdown": "# pr-agent - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 pr-agent 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的软件开发与交付任务。\n我常用的宿主 AI：chatgpt\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: 🚀 PR Agent: The Original Open-Source PR Reviewer. 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. introduction：PR-Agent 简介。围绕“PR-Agent 简介”模拟一次用户任务，不展示安装或运行结果。\n2. system_architecture：系统架构。围绕“系统架构”模拟一次用户任务，不展示安装或运行结果。\n3. ai_integration：AI 模型集成。围绕“AI 模型集成”模拟一次用户任务，不展示安装或运行结果。\n4. tools_overview：工具概述。围绕“工具概述”模拟一次用户任务，不展示安装或运行结果。\n5. review_tool：代码审查工具 (Review)。围绕“代码审查工具 (Review)”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. introduction\n输入：用户提供的“PR-Agent 简介”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. system_architecture\n输入：用户提供的“系统架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. ai_integration\n输入：用户提供的“AI 模型集成”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. tools_overview\n输入：用户提供的“工具概述”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. review_tool\n输入：用户提供的“代码审查工具 (Review)”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / introduction：Step 1 必须围绕“PR-Agent 简介”形成一个小中间产物，并等待用户确认。\n- Step 2 / system_architecture：Step 2 必须围绕“系统架构”形成一个小中间产物，并等待用户确认。\n- Step 3 / ai_integration：Step 3 必须围绕“AI 模型集成”形成一个小中间产物，并等待用户确认。\n- Step 4 / tools_overview：Step 4 必须围绕“工具概述”形成一个小中间产物，并等待用户确认。\n- Step 5 / review_tool：Step 5 必须围绕“代码审查工具 (Review)”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/The-PR-Agent/pr-agent\n- https://github.com/The-PR-Agent/pr-agent#readme\n- README.md\n- pr_agent/agent/pr_agent.py\n- pr_agent/tools/pr_description.py\n- pr_agent/tools/pr_reviewer.py\n- pr_agent/config_loader.py\n- pr_agent/algo/types.py\n- pr_agent/git_providers/__init__.py\n- pr_agent/git_providers/git_provider.py\n- pr_agent/algo/ai_handlers/base_ai_handler.py\n- pr_agent/algo/ai_handlers/openai_ai_handler.py\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 pr-agent 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n", "summary": "不安装项目也能感受能力节奏的安全试用 Prompt。", "title": "Prompt Preview / 安装前试用 Prompt" }, "quick_start": { "asset_id": "quick_start", "filename": "QUICK_START.md", "markdown": "# Quick Start / 官方入口\n\n项目：The-PR-Agent/pr-agent\n\n## 官方安装入口\n\n### Python / pip · 官方安装入口\n\n```bash\npip install pr-agent\n```\n\n来源：https://github.com/The-PR-Agent/pr-agent#readme\n\n## 来源\n\n- repo: https://github.com/The-PR-Agent/pr-agent\n- docs: https://github.com/The-PR-Agent/pr-agent#readme\n", "summary": "从项目官方 README 或安装文档提取的开工入口。", "title": "Quick Start / 官方入口" } }, "validation_id": "dval_f01005a3aa214a0dab63463c792358ed" }