Actual Budget AI 使用政策与实践指南合规、可审查地借助 AI 为开源项目贡献代码【免费下载链接】actualA local-first personal finance app项目地址: https://gitcode.com/GitHub_Trending/ac/actualActual 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:fixlint 与格式化。当前仓库使用 oxlint oxfmt见 .oxlintrc.json并包含eslint-plugin-actual的自定义规则如no-untranslated-strings、prefer-trans-over-t、prefer-logger-over-console相关测试必须通过测试体系见 Testing GuideVitest 单元测试 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 testlage 并行全仓测试需要时用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 issuegh 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 替你写代码但别让它替你思考、替你说话、替你负责。延伸阅读均在当前仓库内AGENTS.md面向 AI Agent 的完整代码库指南架构、命令、代码风格、测试策略PR and Commit RulesAgent 的 PR/commit/评论规则明细Testing GuideVitest / Playwright / VRT 测试体系Code Style and ConventionsTypeScript 与 React 编码约定Cursor IDE guideAI 编辑器配置与规则管理【免费下载链接】actualA local-first personal finance app项目地址: https://gitcode.com/GitHub_Trending/ac/actual创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Actual Budget AI 使用政策与实践指南：合规、可审查地借助 AI 为开源项目贡献代码
Actual Budget AI 使用政策与实践指南合规、可审查地借助 AI 为开源项目贡献代码【免费下载链接】actualA local-first personal finance app项目地址: https://gitcode.com/GitHub_Trending/ac/actualActual 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:fixlint 与格式化。当前仓库使用 oxlint oxfmt见 .oxlintrc.json并包含eslint-plugin-actual的自定义规则如no-untranslated-strings、prefer-trans-over-t、prefer-logger-over-console相关测试必须通过测试体系见 Testing GuideVitest 单元测试 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 testlage 并行全仓测试需要时用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 issuegh 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 替你写代码但别让它替你思考、替你说话、替你负责。延伸阅读均在当前仓库内AGENTS.md面向 AI Agent 的完整代码库指南架构、命令、代码风格、测试策略PR and Commit RulesAgent 的 PR/commit/评论规则明细Testing GuideVitest / Playwright / VRT 测试体系Code Style and ConventionsTypeScript 与 React 编码约定Cursor IDE guideAI 编辑器配置与规则管理【免费下载链接】actualA local-first personal finance app项目地址: https://gitcode.com/GitHub_Trending/ac/actual创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考