Actual Budget AI 使用政策与实践指南：合规、可审查地借助 AI 为开源项目贡献代码-育师

Actual Budget AI 使用政策与实践指南：合规、可审查地借助 AI 为开源项目贡献代码

【免费下载链接】actualA local-first personal finance app项目地址: https://gitcode.com/GitHub_Trending/ac/actual

Actual Budget 是一个本地优先（local-first）的开源个人财务管理应用，其核心逻辑、Web 客户端、桌面端与同步服务器全部位于同一个 monorepo 中。随着 GitHub Copilot、Cursor、Claude、ChatGPT 等 AI 工具被普遍使用，项目在 ai-usage-policy.md 中明确了 AI 辅助贡献的边界：AI 可以写代码、补测试、修 bug，但质量门槛、人工审查与行为披露不可省略。本文以该政策为骨架，结合仓库中的AGENTS.md、Agent 钩子脚本与 PR 规则文件，完整解读这套机制，并给出可直接执行的提交前检查清单。

政策核心：AI 是工具，贡献者是作者

Actual Budget 欢迎所有人贡献，包括借助 AI 工具产出的贡献。政策的出发点是「AI 是工具」（AI is a tool）：只要它能帮助你交付一个好的改动，项目就乐于接纳。但与此同时，你仍然是提交内容的作者，AI 不是（You are the author of the contribution. The AI is not.）。这句话是整份政策的总纲——AI 负责提速，人类负责理解、验证与最终负责。

基于这一原则，政策从五个维度展开约束：代码质量门槛、与维护者的交互方式、AI 使用披露、PR 数量节奏、提交者的最终责任，外加一套专门针对「自主 AI Agent」的独立规则。下面逐一展开。

允许的 AI 用途与硬性质量门槛

政策明确表示，使用 AI 生成代码、起草测试、修复 bug 或帮助导航代码库都是被允许的。真正的约束不在「是否用了 AI」，而在「最终代码是否达标」：

必须通过yarn typecheck：全仓 TypeScript 类型检查。仓库根目录 package.json 中定义了该脚本，配合typescript-strict-plugin要求新增文件必须是严格类型（stricter type）模式；
必须通过yarn lint:fix：lint 与格式化。当前仓库使用 oxlint + oxfmt（见 .oxlintrc.json），并包含eslint-plugin-actual的自定义规则（如no-untranslated-strings、prefer-trans-over-t、prefer-logger-over-console）；
相关测试必须通过：测试体系见 Testing Guide（Vitest 单元测试 + Playwright E2E + VRT 视觉回归，通过 lage 并行执行）；
必须遵循代码风格：见 Code Style and Conventions（函数式编程优先、命名用isLoaded/hasError等辅助动词、避免as断言、优先satisfies）；
用户可见字符串必须翻译：i18n 规则见 i18n 文档，并通过自定义 ESLint 规则强制。

如果使用 Cursor 这类 AI 编辑器，项目在 Cursor IDE guide 中给出了配置建议：通过 GitHub MCP Server 自动化 PR 流程、利用.cursor/rules目录沉淀团队约定（代码风格、工作流、测试要求、评审标准）。这些规则文件会在 Cursor 生成或审查代码时自动生效，相当于把本文的政策翻译成了编辑器内可执行的行为约束。

从仓库结构看，这些质量门槛并不是「建议」，而是被工程化地固化了：根目录 package.json 的脚本、lage.config.js 的任务编排、以及 pre-commit 阶段由 Husky + nano-staged 触发的 oxfmt/oxlint（见 .nano-staged.json），共同保证每个提交在进入代码库之前先过一遍机器检查。

与维护者交互必须保持「人性」

政策特意划出了一条与代码无关、但同样强制的红线：与维护者的沟通应当是人与人的对话。具体禁止的行为包括：

把评审者的评论直接丢给 AI，再把 AI 生成的原始回复原样粘贴回去；
不加阅读和编辑，就整段用 AI 生成 issue 或 PR 描述；
用 AI 代替自己与维护者争论。

政策给出的理由非常务实：维护者的带宽有限，而代码评审中大部分价值恰恰发生在变更周边的讨论里。如果对话变成「AI 对 AI」或「AI 对人类」，评审就不再有意义。

这一点在仓库中也有镜像体现：CONTRIBUTING.md直接跳转到社区文档站点，而 .github/agents/pr-and-commit-rules.md 要求 AI Agent 在 GitHub 上发布的一切内容（评论、评审、issue 标题与正文）都以 🤖 前缀标记，目的就是让「机器写的内容」在对话流中一眼可辨，从而保障人工对话的纯净性。

必须披露 AI 的使用

政策要求：如果 AI 被用于生成 issue、PR 或其代码的重要部分，必须在提交中说明。披露方式很简单——在 PR 描述里加一句短注记即可，例如：

"The initial implementation was drafted with Claude and then reviewed and edited by me."

（“初始实现由 Claude 起草，随后由我本人审查并编辑。”）

违反披露要求的后果是明确的：看起来像 AI 生成却未披露的 issue 与 PR 可能被不经过评审直接关闭；反复提交未披露 AI 内容、或无视本政策的贡献者，可能被禁止继续贡献。仓库中的 ai-generated-label.yml 工作流进一步说明，这类内容在 CI 层面也被识别与标记，披露不是可选项。

质量优先于数量：一次只开一个 PR

现代 AI 工具让「批量产出版本」变得极其容易，政策因此专门设置了节奏约束：

不要一次性向代码库开一大堆 PR（例如让 AI 扫描整个仓库、把产物全部提交）；
同一作者同时提交的一摞相似 PR，评审成本远超单个经过良好测试的改动，且往往是「内容未经人工阅读与测试」的信号；
项目更希望收到「一个你理解并验证过的改动」，胜过「十个你没读过的改动」；
推荐的节奏是：开一个 PR → 与维护者一起评审并合入 → 再开下一个；
低质量、未测试、未披露的 AI 输出 PR 可能被不经详细评审直接关闭，反复提交者可能被封禁。

这条规则与AGENTS.md中「每个 PR 标题必须以[AI]开头」的要求配合，使得「批量提交 AI 改动」的行为既在社区规范层面被劝阻，又在技术层面可被识别。

提交前责任清单：你对自己交出的每一行负责

政策要求每位贡献者在提交 issue 或 PR 之前，完成三项自查：

理解代码：通读 AI 产出的内容，能够解释每个改动做了什么、为什么需要；
验证可用性：本地运行、跑测试，确认你声称的行为真实存在；
编辑文字：AI 生成的描述往往冗长、重复或不准确，需要删减并确保与实际代码一致。

这三条对应到仓库中的具体操作就是 AGENTS.md 的 Quick Start：提交前先跑yarn typecheck、yarn lint:fix、yarn test（lage 并行全仓测试），需要时用yarn test:debug关缓存调试，再人工走一遍行为验证。

自主 AI Agent 的独立规则：[AI] 前缀与强制钩子

政策的最后一部分专门针对自主 AI Agent（例如通过 Claude Code 或 Cursor Agents 直接在仓库上操作的自动化程序），它们遵循一套独立规则：提交与 PR 标题必须以[AI]开头，并应用AI generated标签。规则正文位于 AGENTS.md 和 .github/agents/pr-and-commit-rules.md。

这套规则不是纸面约定，仓库已经把它做成了机器强制机制。关键实现位于 scripts/agent-hooks/git-guard.sh，它被 Claude、Codex、Cursor 的钩子系统调用，会在 Agent 执行 shell 命令时做确定性拦截：

提交消息必须以[AI]开头：脚本会解析git commit的第一个-m参数（含 heredoc 形式），若消息不以[AI]开头则直接阻断（exit code 2）；
禁止--no-verify/--no-gpg-sign：不允许跳过 git hooks；
禁止推送到 main/master：只允许推送功能分支，force push 需显式用户请求；
禁止创建 GitHub issue：gh issue create会被拦截——开 issue 是人的决定，Agent 只能把拟好的标题与正文转交给用户；
yarn 命令必须从仓库根目录执行：拦截cd packages/...后执行 yarn 的写法，要求使用yarn workspace <name> <cmd>。

该脚本头部注释也坦诚说明了设计边界：它是「尽力而为」（best-effort），防的是 Agent 的诚实失误，而非蓄意绕过；真正的最终防线是 CI 与分支保护。这与政策的整体哲学一致——规则靠人与机器共同维护，而不是靠单点防御。

完整工作流：从 AI 起草到合入的合规路径

把政策、Agent 规则与工程机制串起来，一位使用 AI 辅助的贡献者（或一位驱动 AI Agent 的维护者）的合规流程如下：

起草：用 AI 生成初始实现或修复方案，可以使用 Cursor（参考 Cursor IDE guide 配置规则与 MCP）；
自审：通读 AI 产出，逐处理解；删除冗余，必要时重写用户可见文案；
验证：在仓库根目录执行yarn typecheck、yarn lint:fix、yarn test，按 Testing Guide 补测试；
披露：在 PR 描述中注明 AI 的使用方式（一句话即可）；若是 Agent 提交，确保 commit/PR 标题以[AI]开头并打上AI generated标签（钩子脚本会强制前者）；
提交节奏：一次只开一个 PR，与维护者完成评审与合入后再开下一个；
沟通：评审对话中亲自回复，不把 AI 的原始输出当回复粘贴。

总结

Actual Budget 的 AI 使用政策本质上是一套「透明度 + 责任 + 节奏」的治理框架：代码质量由typecheck/lint/测试/代码风格/i18n 五道门槛兜底，行为边界由「人工对话、主动披露、单 PR 节奏」三条红线约束，而自主 Agent 则由[AI]前缀、AI generated标签和 git-guard.sh 钩子做工程化强制。对想要参与这个 monorepo 的贡献者而言，只需记住一句话：让 AI 替你写代码，但别让它替你思考、替你说话、替你负责。

延伸阅读（均在当前仓库内）：