Arcane AI 贡献策略全解析：从披露、人工验证到与 AGENTS.md 协同的贡献规范

• 云原生
• 运维
• 容器运行时

本文以 AI_POLICY.md 为核心骨架，结合 AGENTS.md、CONTRIBUTING.md、Justfile 与 scripts/development/dev.sh 等仓库文件，系统解读 Arcane 对 AI 辅助贡献的规则、验证流程与工程落地方式。读完你将掌握：AI 参与贡献必须遵守的披露要求、可执行的本地验证清单、项目对 AI 生成代码的"合规边界"，以及如何配置 AI 工具以匹配项目编码模式。

一、政策背景：为什么 Arcane 需要一份 AI 使用政策

Arcane 是一个以 Go 后端 + SvelteKit 前端 + Cobra CLI 构成的现代 Docker 管理平台（仓库结构可参见 AGENTS.md 的 Repository layout 一节），其维护者明确表示"AI 在本项目中被欢迎"（AI is Welcome Here），并且维护者自身在日常工作流中大量使用 AI 工具。然而，AI 生成的低质量 PR 数量上升——未经测试的代码、不遵循项目模式、解决并不存在的问题——这给志愿维护者带来了巨大的审阅负担。

因此 AI_POLICY.md 的出发点不是反 AI 立场，而是对贡献质量的管控：政策针对的是"工具产生的结果"，而不是"使用工具的人"。这也是理解该政策全部条款的钥匙。

二、六条核心规则：AI 贡献者的"合规边界"

AI_POLICY.md 用六条规则划定了所有外部贡献者（outside contributors）必须遵守的边界。维护者（maintainers）豁免于这些规则，可在自行判断下使用 AI 工具。

值得强调的是规则 4 的"human-in-the-loop"细节：AI 辅助生成的内容必须经过人类审阅（reviewed）并编辑（edited），而不是仅仅"看一眼"。政策明确指出 AI"非常擅长过度冗长并加入干扰主旨的噪声"，人类需要做研究并把它裁剪掉。

三、Testing Requirements：AI 贡献的强制验证清单

AI_POLICY.md 的 Testing Requirements 一节给出了提交任何 AI 辅助贡献前的 6 步强制验证流程，这也是政策中唯一一段带具体命令的实操内容：

1. 启动开发环境：./scripts/development/dev.sh start
2. 访问前端 http://localhost:3000 并验证其工作正常
3. 验证后端 http://localhost:3552 响应正确
4. 手动测试你的具体改动
5. 确保不存在 lint 错误
6. 验证前后端的热重载（hot reload）都正常工作

如果你更习惯用just，Justfile 提供了等价快捷方式，例如just dev docker、just lint frontend和just test backend。

3.1 这些端口与命令在仓库中的落地

上述端口号并非凭空而来，而是有源码与配置背书：

• 后端默认端口 3552 定义在 backend/internal/config/config.go 中：Port stringenv:"PORT" default:"3552"``，同时APP_URL默认值为http://localhost:3552。配置测试 backend/internal/config/config_test.go 也断言了该默认值。
• 前端开发服务器端口 3000 由 Justfile 中"Run frontend dev server on port 3000"的注释与_dev_frontend目标确认。
• 后端健康检查端点/health由 backend/internal/health/module.go 注册（GET 与 HEAD），其实现 backend/internal/health/handler.go 返回system.HealthResponse{Status: "UP"}。也就是说，你可以用curl http://localhost:3552/health快速确认后端存活。

3.2 dev.sh 脚本：一键起停的验证环境

scripts/development/dev.sh 是 AI 政策验证流程的核心工具，它支持start、stop、restart、status、env、logs、clean、rebuild、shell、help等子命令。与 AI 贡献验证直接相关的特性包括：

• 热重载：前端用 Vite（HMR），后端用 Air（auto-rebuild and restart），这正是验证清单第 6 步"验证 hot reload"的依据。
• 环境自检：脚本启动时会检查 Docker 与 Docker Compose 是否可用，缺失时会询问是否用项目脚本自动安装到项目内dist/目录（见 scripts/development/dev.sh 的offer_installation与check_requirements）。
• 健康检查与持久化：启动后自动打印 Frontend/Backend 地址，并通过 compose 卷持久化开发数据。

3.3 质量门禁：format + lint

政策要求"确保不存在 lint 错误"，Justfile 将其落实为可执行的命令链：

just format all # 依次运行 frontend / js / go / just 四个格式化目标 just lint all # 依次运行 js / go / proto 的 lint 目标

具体到 Go 侧，格式化由gci（import 分组）+gofumpt完成，三个 Go 模块（backend/、cli/、types/）分别执行；lint 由golangci-lint配合仓库根目录.golangci.yml配置驱动。AI 生成的代码如果不能通过这两道门禁，同样会被拒绝。

四、There are Humans Here：政策的人性化一面

AI_POLICY.md 专门用一节提醒贡献者："Arcane 由人类维护"。每一个讨论、issue、PR 都会被人类阅读和审阅，贡献是与他人工作的交互点。以低质量、未经验证的提交接近这个社区，是不尊重志愿维护者的时间。

这一节的价值在于解释政策动机：理想世界中 AI 每次都能产出高质量、正确的代码，但现实取决于使用 AI 的人。正因为看到了太多"未测试、不遵循项目模式、解决不存在问题"的 AI 贡献，社区才需要明确的规则来保护维护者时间。

五、AI is Welcome Here：政策的开放姿态

政策明确重申：

• Arcane 本身就借助 AI 辅助开发，维护者高效地在工作流中使用 AI 工具；
• 项目欢迎"负责任地使用 AI"的贡献者；
• 政策的理由不是反 AI，而是回应低质量 AI PR 的增加；
• 政策关注的是贡献质量，而非工具本身。

六、Technical Guidance：如何配置 AI 工具以匹配项目标准

AI_POLICY.md 最后一节将技术指引指向 AGENTS.md——这是 AI 工具（以及人）理解 Arcane 编码约定的主文档，包含架构模式、应避免的反模式（anti-patterns）和项目特定约定。

6.1 AGENTS.md 中的关键约定摘要

从 AGENTS.md 可以提炼出 AI 工具需要内化的核心规则：

通用规则（适用于每次改动）

• 不得运行改变 Git 状态的命令（不 stage、commit、push、tag、stash、建分支、建 worktree）；
• 新增函数/服务/API 客户端/组件/工具前，先搜索所属 domain 与既有 helpers，直接更新现有逻辑及其调用方；
• 不添加 stub、兼容 shim、透传 wrapper 或重复实现；
• 仅对新功能添加测试；bug 修复与重构更新既有测试并运行相关覆盖，不加回归测试；
• 不添加 handler 测试，新业务行为在 service 层或所属逻辑包测试；
• 每次改动（包括文档改动）后运行just format all，然后just lint all，修复所有问题并保留格式化输出。

后端约定

• Echo v5 作为 router、Huma v2 用于类型化 REST/OpenAPI 操作；带权限的端点用middleware.RegisterWithPermission注册；
• handler 只做 HTTP 数据翻译并调用 service，不得包含业务逻辑；
• 使用slog结构化日志、标准errors与fmt.Errorf("…: %w")、internal/common.Classify语义错误、types/base.FieldError校验字段。

前端约定

• 使用 SvelteKit v3 + Svelte 5 runes（$props、$state、$derived、$effect），禁用export let、$:、on:event、$$props、$$restProps与 legacy slots；
• 扩展BaseAPIService，复用既有 service 与 query/mutation 模式；
• 错误路径必须比console.error做得更多：一次性动作用handleApiResultWithCallbacks；流式/轮询源显示内联不可用状态；页面加载用throwPageLoadError重新抛出。

测试与验证

• 运行最窄的相关既有覆盖，再选择测试目标：just test backend/just test cli/just test types；just test e2e需要可用浏览器环境，just test all包含 E2E 及其前置条件；
• 不要隐式启动开发栈来满足测试目标；纯文档改动不需要新增测试。

6.2 政策与 AGENTS.md 的分工关系

可以这样理解两者的配合：

• AI_POLICY.md 回答"能不能用、怎么证明用了"——披露、人工验证、人类在环、禁用媒体、违规后果；
• AGENTS.md 回答"代码怎么写才对"——仓库布局、domain 文件集、命名规范、测试配对、Svelte 5 约定、错误处理模式。

前者是贡献的准入与质量闸门，后者是代码本身的工程契约。AI 工具只有在两者同时满足时，其产出才可能被合并。

七、给 AI 贡献者的实践建议

结合 AI_POLICY.md、AGENTS.md 与 CONTRIBUTING.md，一个合规且高效的 AI 贡献流程可以归纳为：

1. 动笔前：完整阅读 AGENTS.md 与 AI_POLICY.md，把项目约定喂给 AI 工具（或在工具上下文中挂载这两份文档）。
2. 开发中：运行./scripts/development/dev.sh start启动含热重载的开发环境（或just dev docker），确保前端的每一次改动立即通过 HMR、后端通过 Air 生效。
3. 验证时：严格按 6 步清单执行——访问http://localhost:3000与http://localhost:3552（后端健康检查可直连/health）、手动测试具体改动、确认无 lint 错误、确认双端热重载正常。
4. 提交前：运行just format all与just lint all并修复全部问题；运行最窄的相关测试（如just test backend）。
5. 披露时：在 PR 描述中如实注明使用的 AI 工具（Claude Code、Cursor、GitHub Copilot、ChatGPT 等）及 AI 辅助的范围与程度。
6. 保持人在环：对 AI 生成的内容做研究性裁剪，去除冗长与噪声，让 PR 聚焦于真实问题。

八、常见疑问与边界

Q：用 AI 写文档/翻译也算违规吗？政策禁止的是"AI 生成的媒体"（图片、视频、音频等）；文本和代码是允许的 AI 产物，但同样必须披露、遵循"人类在环"的审阅与编辑要求。翻译场景下，仓库通过 Crowdin 管理除英文外的所有语言（参见 AGENTS.md 的 Translations 一节与 CONTRIBUTING.md），人工编辑仍是必要环节。

Q：维护者是否受这些规则约束？不受。AI_POLICY.md 明确"These rules apply to all outside contributions"，维护者豁免并可按判断使用 AI 工具，因为他们已被证明能够应用良好判断。

Q：如果 AI 被我用于分析而非生成代码，需要披露吗？政策要求"All AI usage in any form must be disclosed"，任何形式的 AI 使用都需披露，并说明工具与辅助程度。本着透明原则，最稳妥的做法是统一在 PR/issue 中声明。

结语

AI_POLICY.md 是一份短小但边界清晰的项目治理文档：它不拒绝 AI，而是用"披露—验证—人在环—禁媒体—后果"五道闸门，把 AI 从"低质量 PR 的来源"转化为"负责任贡献者的效率工具"。配合 AGENTS.md 的工程契约与 Justfile、scripts/development/dev.sh 的可执行验证链路，Arcane 为 AI 辅助开源贡献提供了一个可复制的实践样板：AI 可以用，但必须被看见、被验证、被人类编辑。

• 云原生
• 运维
• 容器运行时