Google Jules 教程：从 GitHub Issue 到可审查 Pull Request

Google Jules 最适合处理边界清楚、能够用测试或检查命令验收的 GitHub 任务。本教程不会把“开发一个完整产品”这种模糊需求交给 Agent，而是用一个真实维护任务走完仓库授权、环境配置、计划审查、代码修改、测试、diff 和 Pull Request。

示例任务是：为一个已经存在的解析函数补齐空输入与异常输入测试，并修复测试暴露的问题。你可以替换成依赖升级、小型 Bug、文档同步或 Lint 修复。

这篇教程会完成什么

完成后你会得到一套可重复的 Jules 工作流：

1. 只授权一个练习仓库。
2. 用 AGENTS.md 告诉 Jules 项目命令与边界。
3. 配置最小 setup script。
4. 从 GitHub Issue 或 Jules 页面创建任务。
5. 审查计划，而不是直接让 Agent 自由修改。
6. 检查活动日志、diff、测试和未完成项。
7. 创建 Pull Request，通过独立 CI 后再合并。
8. 记录成功率与返工时间，决定是否继续使用或升级。

开始前需要准备

• 一个 GitHub 账号和可测试的仓库。
• 仓库中已有安装锁文件，例如 package-lock.json、pnpm-lock.yaml 或 uv.lock。
• 至少一条稳定的测试命令。
• 一个不会接触生产数据的测试环境。
• 明确的分支保护和 Pull Request 审查规则。
• Jules 账号。免费层当前足够完成首次练习。

不要选择包含未轮换生产密钥的仓库。先运行秘密扫描，并检查 .env、CI 配置、部署脚本和示例文件是否泄露凭据。

第一步：只授权必要仓库

登录 Jules 后连接 GitHub。GitHub App 的授权页面通常允许选择所有仓库或指定仓库。首次使用应选择“Only select repositories”，只授权练习仓库。

完成任务后，如果暂时不用 Jules，可以在 GitHub 设置的 Applications 中重新配置或撤销访问。不要因为方便就把个人账号下的所有私有仓库永久授权给任何 Agent。

Jules 每个任务会在云端 VM 中克隆仓库并运行命令。官方说明 VM 有互联网访问，因此仓库里的安装脚本、测试脚本和依赖都可能产生外部请求。授权范围只是第一层，执行权限同样要控制。

第二步：准备 AGENTS.md

Jules 会读取仓库根目录的 AGENTS.md。内容应该短、具体、能影响执行，不要复制一整本工程手册。

示例：

Repository instructions

- Install dependencies with `npm ci`.
- Run unit tests with `npm test -- --runInBand`.
- Run type checks with `npm run typecheck`.
- Do not modify files under `infra/` or `migrations/`.
- Do not add dependencies unless the task explicitly requires it.
- Keep public function signatures backward compatible.
- Before finishing, list changed files, tests run, failures, and remaining risks.

这份文件解决三个问题：Agent 怎样准备环境、什么命令算验收、哪些范围不能修改。规则互相冲突时，应先修正文档再创建任务。

不要在 AGENTS.md 中写 API Key、服务器地址、客户数据或生产凭据。它会被提交到仓库，应该像 README 一样可公开审查。

第三步：配置最小 setup script

在 Jules 的仓库配置中添加环境准备命令。Node.js 项目可以从下面开始：

npm ci
npm run typecheck
npm test -- --runInBand

第一次配置时使用“Run and Snapshot”验证。安装成功后，Jules 可以复用环境快照，后续任务启动更快。

setup script 应当满足：

• 使用锁文件确定依赖版本。
• 非交互执行，不等待用户输入。
• 不启动 npm run dev 这类长期进程。
• 不访问生产数据库。
• 不执行部署。
• 不输出环境变量和密钥。
• 失败时返回非零退出码。

如果项目安装需要私有包，创建只读、短期 token，并限制到对应 registry。不要复用拥有发布权限的个人 token。

第四步：写一个可验收的 GitHub Issue

差的任务：

修好解析器，顺便优化一下代码。

好的任务：

src/parseQuery.ts 在空字符串和包含重复分隔符时行为不一致。请先在 tests/parseQuery.test.ts 添加失败测试，再做最小修复。保持 parseQuery(input: string) 的公开签名不变，不修改 infra/ 和依赖。完成条件：npm test -- --runInBand 与 npm run typecheck 通过，并在总结中说明异常输入策略。

一个合格任务至少写清楚：

• 问题或期望结果。
• 允许修改的文件范围。
• 禁止修改的接口和目录。
• 必须先增加还是只运行测试。
• 验收命令。
• 失败时停止并报告的条件。

如果需求需要产品经理、设计师或安全负责人做多次选择，先不要交给异步 Agent。拆到决策完成后再委派实现部分。

第五步：创建 Jules 任务

有三种常用方式。

Jules 网页

选择仓库与起始分支，把 Issue 内容粘贴到任务输入框，点击生成计划。适合第一次使用，因为所有步骤可见。

GitHub Issue 标签

确保 Jules GitHub App 已访问仓库，然后给 Issue 添加 jules 标签。Jules 会创建任务并在完成后提供 Pull Request 链接。适合已经稳定使用、Issue 模板完整的团队。

Jules CLI

安装并登录：

npm install -g @google/jules
jules login

从当前仓库创建任务：

jules remote new --repo . --session "按 Issue #123 补充失败测试并做最小修复；运行 AGENTS.md 中的全部验证命令。"

CLI 适合脚本化，但不要把未经筛选的整个 TODO 列表一次性并行发出。先控制在一到三个任务，观察 review 负载。

第六步：认真审查计划

Jules 通常会先读仓库并提出计划。至少检查：

• 是否定位到正确文件和测试。
• 是否准备先复现问题。
• 是否承诺最小改动。
• 是否出现升级依赖、改数据库或重构的额外范围。
• 是否会运行指定的全部验收命令。
• 是否遗漏向后兼容要求。

发现问题时在批准前反馈。例如：

不要修改解析器的公开签名，也不要新增依赖。先补两个失败测试，再做最小逻辑修复。若现有行为在调用方中被依赖，请停止并报告。

不要把“计划看起来很专业”当成正确。对照 Issue 的完成定义逐条检查。

第七步：观察执行但不要过度干预

任务运行后，Jules 会在活动流中记录安装、搜索、修改与测试。出现瞬时网络或依赖错误时可能自动重试；setup script 不完整、命令长期运行、提示范围太大时，任务可能失败。

如果方向明显错误，暂停任务并给出具体反馈。不要连续发送互相矛盾的指令。每次反馈只修正一个边界，然后等 Agent 重新规划。

还要留意“为了通过测试而删除测试”“用宽泛 try/catch 吞错误”“把真实逻辑换成硬编码”等投机修改。测试绿灯不能替代 diff 审查。

第八步：检查 diff 和测试证据

完成后先看摘要，再逐文件审查。

检查清单：

• 改动是否只在允许范围。
• 新测试是否真的覆盖原问题。
• 有没有跳过、删除或放宽断言。
• 是否新增依赖、网络请求或数据收集。
• 错误处理是否与项目约定一致。
• 是否改变公共 API、配置或数据库。
• Agent 声称运行的命令是否有对应日志。
• 是否诚实列出失败测试和未完成项。

然后在你自己的受信环境重新运行：

npm ci
npm run typecheck
npm test -- --runInBand

如果是前端，再运行构建、无障碍检查和关键页面截图对比；如果涉及安全边界，增加静态扫描和人工威胁审查。

第九步：创建 Pull Request 并保留门禁

确认 diff 合理后，让 Jules 发布分支或创建 Pull Request。PR 描述应包含：

• 原问题和修复策略。
• 修改文件。
• 新增或更新的测试。
• 实际运行的命令与结果。
• 已知限制。
• 需要 reviewer 特别关注的风险。

保持分支保护：至少一名人类 reviewer、独立 CI 必须通过、禁止直接推送主分支。数据库迁移、基础设施、权限和支付代码应要求更高等级审批。

第十步：记录效果再决定升级

免费层当前提供 15 个任务/日、3 个并发。不要第一天就把并发开满。先记录两周：

• 任务总数与成功完成数。
• 首次测试通过率。
• 人工发现的缺陷数。
• 平均 review 与返工时间。
• 失败原因分类。
• 与手工完成相比节省的时间。
• 是否发生权限或秘密处理问题。

如果高频任务稳定成功且 review 没有成为瓶颈，再考虑 Jules in Pro。官方当前 Pro 为 100 个任务/日、15 并发，Ultra 为 300/60；额度、模型和地区价格可能变化，应在升级当天复查。

常见错误

环境安装失败

先在干净容器或新 clone 中验证 setup script。锁定运行时和包管理器版本，避免依赖本机缓存。

任务一直扩大范围

重写 Issue，把允许修改目录、公共接口和完成命令写清楚。一个任务只解决一个可验证问题。

测试通过但结果不对

检查测试是不是只验证实现细节，补充用户可见行为、边界输入和回归用例。不要让同一个 Agent 成为唯一的测试作者和 reviewer。

需要生产密钥才能运行

这通常说明测试环境设计有问题。提供 mock、沙箱账号或只读测试资源；如果无法隔离，不要把任务交给云端 Agent。

CLI 或 API 自动化失控

限制每次创建任务数，设置预算和并发上限，记录创建者与来源。Jules REST API 当前属于实验性接口，应加入版本适配与失败降级。

什么时候该换别的工具

• 需求还在探索、需要开发者实时决定方向：选择 Claude Code 或 Codex 本地工作流。
• 需要本地未推送代码：选择支持直接操作本地工作区的 Agent。
• 团队需要持续任务池、共享会话和集中治理：评估 Devin。
• 组织必须使用 GitHub 原生企业策略：比较 GitHub Copilot Coding Agent。
• 仓库不能进入第三方云端：使用符合组织部署与数据边界的本地或企业方案。

最终建议

把 Jules 当成可审查的异步执行者，不是自动合并机器人。先用一个受控仓库、一个明确 Issue 和一套可靠测试证明价值；在任务、权限和 review 责任稳定之前，不要扩大仓库授权和并发。

官方资料

• Jules 入门文档
• 运行任务
• 环境配置
• 安全 FAQ
• Jules CLI
• 使用额度