Sweep GitHub App 安装后使用指南：从创建第一个 Issue 到管理 AI 生成的 PR

• AI 应用
• AI Agent
• 代码智能体
• 后端

本文以 Sweep 仓库中的 docs/installation.md 为骨架，讲解当 Sweep GitHub App 安装成功之后，如何在真实仓库中创建任务、引导 AI 修改代码、通过评论反馈修正 PR，以及用sweep.yaml约束 AI 行为。读完本文，你将掌握 Sweep 的完整工作流（Issue → PR → 反馈循环）、提示词编写技巧、已知能力边界，以及配置文件的核心参数。

一、这份文档是什么

docs/installation.md是用户在 GitHub 上安装 Sweep App 后看到的欢迎引导页。它不是一个「如何部署 Sweep」的教程，而是告诉用户：App 已经装好，接下来在你的仓库里怎么用。因此它强调一个关键前提——Sweep 是为真实项目和真实 Issue 设计的：

Sweep works best with real repositories and real issues; empty or test repositories will break Sweep.

也就是说，一个只有 README 的空仓库、或包含大量无意义测试数据的仓库，会让 Sweep 的代码检索与修改流程失效。官方建议：如果手头没有合适仓库，可以参照 docs/pages/usage/tutorial.mdx 用 Docusaurus 模板走一遍完整流程（fork 模板 → 部署到 Vercel → 安装 Sweep → 创建 Issue → 反馈 → 合并 PR）。

二、动手前的前置条件

在创建第一个任务之前，需要确认两件事：

1. Sweep 已安装到目标仓库：安装时授予 Sweep 对该仓库的读写权限，否则它无法创建分支和 PR。
2. 仓库的 Issues 功能已启用：installation.md末尾特别注明 "you need to have Sweep installed and Issues enabled in Repo"。如果仓库设置中关闭了 Issues，Sweep 将无从接收任务。

三、创建第一个 Sweep Issue

3.1 两种触发方式

installation.md给出了两种完全等价的触发方式：

• 新建 Issue：标题以Sweep:开头，例如Sweep: Add a banner at the top asking the user to star the docusaurus repo with the current number of stars；
• 已有 Issue：为它打上Sweep标签，Sweep 就会开始处理。

对于 PR 同理：可以在标题/正文中前缀Sweep:，也可以使用Sweep标签来触发。

3.2 源码中的触发逻辑

从源码看，这个「前缀 + 标签」机制由两部分实现：

• 标签名是可在环境变量中覆盖的默认值，见 sweepai/config/server.py：GITHUB_LABEL_NAME = os.environ.get("GITHUB_LABEL_NAME", "sweep")，即默认标签为sweep；
• 标题前缀的解析在 sweepai/utils/str_utils.py 的strip_sweep()中完成。它使用正则^[Ss]weep\s?(\([Ss]low\))?(\([Mm]ap\))?(\([Ff]ast\))?\s?:从标题中剥离前缀，同时识别标题里的可选模式，例如Sweep (Slow):、Sweep (Map):、Sweep (Fast):、Sweep (Subissues):、Sweep (Sandbox):、Sweep (Lint):。也就是说，你可以在标题中附加这些括号参数来切换慢速模式、快速模式、Map 模式、子问题拆分、沙箱校验或 Lint 修复等行为。

3.3 首次运行的耗时

installation.md提示：初始启动时间通常需要 3~5 分钟，具体取决于代码库大小。这是因为 Sweep 首次处理任务时需要对仓库做全量扫描与索引（参考仓库中的sweepai/core/lexical_search.py、sweepai/core/vector_db.py等检索模块）。在任务处理期间，用户可以在 Issue 或 PR 上看到 👀 表情，表示 Sweep 正在查看你的消息。

3.4 处理链路：on_ticket

Issue 创建后，webhook 会进入 sweepai/handlers/on_ticket.py 的on_ticket()主函数。它是「新 Issue 被创建」时的核心入口（源码注释明确说明 "on_ticket is the main function that is called when a new issue is created"，且只由 sweepai/api.py 中的 webhook handler 调用）。on_ticket()中会完成：解析标题（strip_sweep）、处理 Issue 描述（process_summary）、初始化日志（ChatLogger）、校验 Issue 合法性（validate_issue）、检索相关文件（fetch_relevant_files）、生成文件修改请求（handle_file_change_requests）并最终创建 PR。这解释了为什么文档要求 Issue 描述尽量详细——它直接影响get_files_to_change等检索与规划步骤的输入质量。

四、修复 Sweep 生成的 PR：反馈循环

Sweep 和人类初级开发者一样，偶尔会出错。installation.md明确指出 "Sweep will mess up sometimes"，并给出了三处反馈入口（与 docs/pages/usage/advanced.mdx 中的描述一致）：

1. 在 Issue 上评论：Sweep 会新建一个 PR 并关闭旧的；也可以直接编辑 Issue 描述来重新触发；
2. 在 PR 上评论：Sweep 根据 PR 评论更新对应实现；
3. 在代码行上评论：Sweep 只更新该评论所在的文件。

反馈示例："use PyTorch instead of Tensorflow"。每当 Sweep 开始查看一条新消息时，你会看到 👀 表情；如果看不到，请确认 PR/Issue 处于打开状态，且消息已用sweep:前缀触发。

此外还有两个高级能力：

• GitHub Actions 联动：配置 sweep.yaml 中的gha_enabled: True后，Sweep 会读取 CI 运行日志，根据 linter/构建错误自动修正 PR。仓库中对应实现是 sweepai/handlers/on_failing_github_actions.py（on_failing_github_actions被on_ticket直接调用）。
• 暂停/关闭任务：在 PR 或 Issue 上移除Sweep标签即可让 Sweep 停止处理。

从源码看，PR 创建与多文件修改逻辑集中在 sweepai/handlers/create_pr.py 的handle_file_change_requests，其中create_branch、commit_multi_file_changes（见 sweepai/utils/github_utils.py）负责在目标仓库上建分支并提交；draft配置则控制 PR 是否以草稿形式创建（草稿 PR 不会触发 GitHub Actions）。

五、Sweep 提示词技巧

installation.md专门列出三条「Prompting Tricks」，并结合 docs/pages/usage/advanced.mdx 可以形成一套完整写法。一个好的 Issue 应包含三要素：在哪找（文件/实体名）、做什么（明确的逻辑改动）、额外上下文（bug / 新功能 / 依赖约束）。

• 点名文件或函数：例如In sweepai/app/ui.py, use an os-agnostic temp directory。Sweep 运行时会检索相关文件，但显式点名可以避免遗漏关键细节；
• 描述具体改动：说明你想修复或实现的行为，可附带实现思路。描述越接近你给初级开发者写的任务说明，效果越好；
• 提供补充上下文：例如see "src/App.test.tsx" for an example of a good unit test——这种「照某文件的样子写」的示范式提示非常有效，因为它把问题转化为一次翻译/模仿任务；
• 用命令式语气：写Optimize this line of code而不是This line of code needs to be optimized；
• 避免空泛指令：不要写「fix typos」「write tests」「optimize the SEO」这类无明确目标的短语，文档警告这会让 Sweep 困惑甚至失败。

文档还建议：提示的详细程度应与问题复杂度成正比——简单问题一句话加一个文件名即可，复杂问题则需要提供人类工程师完成该任务所需的全部信息。

5.1 切换分支

在 Issue 描述中加入一行branch: BRANCH_NAME，可以让 Sweep 针对这一个 Issue 使用指定的基础分支（而不是sweep.yaml中配置的默认分支）。

六、用 sweep.yaml 配置仓库级行为

installation.md指向配置文档（仓库内对应 docs/pages/usage/config.mdx）。sweep.yaml位于仓库根目录；如果仓库还没有该文件，Sweep 在第一次处理 Issue 时会主动创建一个 PR 帮你加上。仓库自身的配置示例就是根目录的 sweep.yaml。

以下是默认配置骨架及核心参数：

# 分支：Sweep 基于它开发并创建 PR，通常为 main/master，也可用 dev/staging branch: 'main' # 是否读取现有 GitHub Actions 的日志与输出，置 False 则禁用 gha_enabled: True # 仓库描述：Sweep 创建 PR 时使用，可说明框架、入口、编码规范 description: '' # 是否以草稿形式创建 PR；为 True 时 GitHub Actions 不会被触发 draft: False # Sweep 不能修改的目录/文件列表 blocked_dirs: [".github/"]

各参数说明：

此外sweep.yaml还可以配置rules（Sweep Rules，在 sweep.yaml 中已有完整示例，例如要求使用 loguru 记录异常、生产代码禁止 debug/print、函数必须带类型注解、新业务逻辑必须配套单元测试等）以及docs字段。源码层面，这些配置的读取集中在 sweepai/config/client.py：

• get_blocked_dirs(repo)（L463-L473）读取sweep.yaml的blocked_dirs，供检索与修改阶段过滤文件；
• get_rules(repo)（L475-L485）读取rules列表，作为代码生成时的约束；
• get_documentation_dict(repo)（L450-L460）读取docs字段。

另外值得注意的是，即使不配置blocked_dirs，SweepConfig类（sweepai/config/client.py）也有内置的默认排除规则：exclude_dirs默认排除.git、node_modules、build、.venv、venv、dist等；exclude_exts默认排除.min.js、.png、.jpg、.pdf、sweep.yaml等二进制/构建产物文件。这些默认规则是大仓库场景下第一道防线。

七、Sweep 的已知局限（Limitations）

installation.md明确列出 Sweep 现阶段（文档撰写时）的能力边界，使用时应提前规避：

• 超大仓库：文件数超过约 5000 时可能无法全覆盖。虽然有默认的排除目录与扩展名规则，但有时仍会漏掉部分目录，此时需要在blocked_dirs中显式屏蔽无关目录。若 Sweep 卡在 0% 超过 30 分钟且仓库有数千文件，建议反馈给官方；
• 大规模重构：单次改动超过 5 个文件或 300 行代码基本做不到，像「把整个代码库从 Tensorflow 迁移到 PyTorch」这类任务不在能力范围内；
• 图片等非文本资产：无法编辑图片/生成 favicon 之类的任务；
• 外部 API 访问：无法访问外部 API 或获取 API token，例如「用 Ethereum 做登录」这类涉及外部服务集成的任务。

这些边界与 docs/pages/usage/advanced.mdx 的补充建议一致（"Try to change less than 300 lines of code / Try to modify less than 5 files"）。在设计 Issue 时，应把任务拆解到这些规模之内。

八、配额方案与 Bug 报告

installation.md同时说明了当时的配额策略：每位用户默认拥有不限量的 GPT-3.5 票据，每月有 5 个 GPT-4 Issue 配额，且每日可用 2 个 GPT-4 Issue；需要更多配额时可订阅 Plus（30 票）或 Pro（无限票 + 优先支持）方案，具体价格与条款以官方最新发布为准。

Bug 报告机制：如果 Sweep 未能在其能力范围内解决某个 Issue（见上文 Limitations），且用户在官方 Discourse 提交了高质量的 bug 报告，官方会重置该用户的票据计数（仅针对 GPT-4 PR）。这属于社区运营政策，具体执行细节请以官方当前规则为准。

九、推荐后续路径

installation.md最后指向三块后续学习资源，对应仓库内的文档分别是：

• docs/pages/usage/tutorial.mdx：用 Docusaurus 模板从零走完「部署模板 → 安装 Sweep → 创建 Issue → 评论反馈 → 合并 PR」的完整闭环；
• docs/pages/usage/advanced.mdx：高级用法，包括文件点名、三处反馈入口、branch:切换、sweep.yaml进阶配置与提示词格式；
• docs/pages/usage/config.mdx：sweep.yaml全参数手册（含默认内容、配置表与逐参数说明）。

十、总结：一条可复现的接入路径

把整份installation.md浓缩成可执行清单：

1. 在真实仓库上安装 Sweep，确认仓库 Issues 已启用；
2. 新建标题以Sweep:开头的 Issue，或在已有 Issue 上添加Sweep标签；
3. 等待 3~5 分钟（视仓库规模），期间可通过 👀 表情确认 Sweep 已响应；
4. 检查 Sweep 生成的 PR：满意则合并；不满意则在 Issue / PR / 代码行上评论或编辑 Issue 描述，让 Sweep 重试或修正；
5. 配置根目录 sweep.yaml，设置gha_enabled: True让 Sweep 根据 GitHub Actions 失败自动修复，并用blocked_dirs、rules、description约束其行为；
6. 控制任务规模（<5 个文件、<300 行），并在标题中显式点名文件/函数，以避开已知局限。

只要遵循这套流程，Sweep 就能在你自己的真实仓库中形成一个「Issue 驱动 → AI 改码 → 人工评审 → 评论修正 → 合并」的闭环，这也是 docs/installation.md 作为安装成功引导页的全部意图。

• AI 应用
• AI Agent
• 代码智能体
• 后端