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

云原生运维容器运行时【免费下载链接】arcaneModern Docker Management, Designed for Everyone项目地址https://gitcode.com/gh_mirrors/arcane2/arcane点击查看免费下载本文以 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 工具。规则核心要求关键含义1. 全量披露任何形式的 AI 使用都必须披露注明所用工具如 Claude Code、Cursor、GitHub Copilot、ChatGPT及 AI 辅助的程度不披露即视为违规即使只是部分辅助2. 人工验证AI 创建的 PR 必须经过完整的人工测试验证不得提交理论上正确但未经测试的代码必须运行开发环境、验证前后端、手动测试改动禁止为无权手动测试的平台写代码3. 遵循现有模式写代码前先读 AGENTS.md 获取技术指引违反项目约定的 AI 代码Svelte 5 语法、service 模式、错误处理等将被拒绝4. 全程人工在环Issue 和讨论可以使用 AI但提交前必须由人类审阅并编辑AI 容易冗长和带噪声人类必须做研究并精简5. 禁止 AI 生成媒体不允许 AI 生成图片、视频、音频等媒体内容文本和代码是仅有的可接受 AI 产物6. 违规后果未披露或疑似使用 AI 的 PR 将被关闭屡次违规可能被禁止贡献政策具有强制约束力值得强调的是规则 4 的human-in-the-loop细节AI 辅助生成的内容必须经过人类审阅reviewed并编辑edited而不是仅仅看一眼。政策明确指出 AI非常擅长过度冗长并加入干扰主旨的噪声人类需要做研究并把它裁剪掉。三、Testing RequirementsAI 贡献的强制验证清单AI_POLICY.md 的 Testing Requirements 一节给出了提交任何 AI 辅助贡献前的 6 步强制验证流程这也是政策中唯一一段带具体命令的实操内容启动开发环境./scripts/development/dev.sh start访问前端 http://localhost:3000 并验证其工作正常验证后端 http://localhost:3552 响应正确手动测试你的具体改动确保不存在 lint 错误验证前后端的热重载hot reload都正常工作如果你更习惯用justJustfile 提供了等价快捷方式例如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 贡献验证直接相关的特性包括热重载前端用 ViteHMR后端用 Airauto-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 侧格式化由gciimport 分组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 typesjust 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 贡献流程可以归纳为动笔前完整阅读 AGENTS.md 与 AI_POLICY.md把项目约定喂给 AI 工具或在工具上下文中挂载这两份文档。开发中运行./scripts/development/dev.sh start启动含热重载的开发环境或just dev docker确保前端的每一次改动立即通过 HMR、后端通过 Air 生效。验证时严格按 6 步清单执行——访问http://localhost:3000与http://localhost:3552后端健康检查可直连/health、手动测试具体改动、确认无 lint 错误、确认双端热重载正常。提交前运行just format all与just lint all并修复全部问题运行最窄的相关测试如just test backend。披露时在 PR 描述中如实注明使用的 AI 工具Claude Code、Cursor、GitHub Copilot、ChatGPT 等及 AI 辅助的范围与程度。保持人在环对 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 可以用但必须被看见、被验证、被人类编辑。赞分享云原生运维容器运行时【免费下载链接】arcaneModern Docker Management, Designed for Everyone项目地址https://gitcode.com/gh_mirrors/arcane2/arcane点击查看免费下载相关推荐htop 的 AI 辅助贡献政策Assisted-by 披露规范与贡献者责任边界htop 的 AI 辅助贡献政策Assisted by 披露规范与贡献者责任边界 本文解析 htop 项目发布的《AI Assisted Contributi可观测性指标监控Gentle-AI 的 AI 辅助贡献政策披露、署名与可辩护提交的工程规范Gentle AI 的 AI 辅助贡献政策披露、署名与可辩护提交的工程规范 本篇指南系统解读开源仓库 Gentle AI gentle ai 一个为 ClVisiData AI 贡献等级制度AI Levels全解析从 0 到 10 的透明披露规范与实操指南VisiData AI 贡献等级制度AI Levels全解析从 0 到 10 的透明披露规范与实操指南 导读 本文基于 VisiData 仓库中的 dev数据分析CLI数据可视化上一篇Chat2DB开源版与Pro版深度解析技术决策者的实战指南下一篇5分钟快速上手Chat2DBAI驱动的智能数据库管理工具终极指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考