ARTICLE DETAIL

资讯详情

深耕郑州网站建设与运营推广的一线实战洞察。

VoiceStudio 的 AI 代理协作契约:AGENTS.md 规则体系、合并协议与确定性 CI 的工程实践

VoiceStudio 的 AI 代理协作契约:AGENTS.md 规则体系、合并协议与确定性 CI 的工程实践 VoiceStudio 的 AI 代理协作契约AGENTS.md 规则体系、合并协议与确定性 CI 的工程实践【免费下载链接】VoiceStudioVoiceStudio is the open-source, fully-local ElevenLabs alternative — voice cloning, voice design, video dubbing, dictation, transcription audiobook creation in 646 languages.项目地址: https://gitcode.com/GitHub_Trending/om/VoiceStudio本篇技术指南围绕开源仓库 VoiceStudio 根目录的 AGENTS.md 展开剖析该项目如何为 Claude、Codex、Cursor 及各类 review bot 等 AI 代理制定一份可执行、可测试的仓库级运营契约operating contract。读者读完后将完整掌握该契约中的 Token 经济纪律、跨平台行为对等原则、五条硬性合并协议、六类变更约束以及配套的 issue 跟踪、triage 标签与领域文档消费约定并理解机械规则全部下沉到确定性测试、代理精力留给判断这一核心工程理念。AGENTS.md 的定位操作契约与完整宪法的分工VoiceStudio 在仓库根目录同时维护了两份面向 AI 代理的规范文档职责刻意分离CLAUDE.md是完整宪法full constitution承载项目背景、技术栈、版本化、docs-sync、changelog、本地化、修复质量、保持 main 绿色等全部长期约束并以 GSD 注释块分区组织Project / Technology Stack / Conventions / Architecture / Skills / Workflow。AGENTS.md是操作契约operating contract对所有AI 代理生效——包括 Claude、Codex、Cursor、审查机器人等——只收录那些每天都会被触发的操作性规则如何回答、如何合并、如何改代码、用什么控件。两者发生冲突时CLAUDE.md 胜出。同时 CLAUDE.md 明确要求AGENTS.md carries this contract for all agents — keep the two in sync即两份文档必须保持同步AGENTS.md 本质上是 CLAUDE.md 工作流部分的浓缩可执行版。Token Economy代理响应的第一纪律AGENTS.md 的开篇规则来自所有者在 2026-07-20 下达、07-28 收紧的指令核心是默认给出能完整回答问题的最短响应结构优先大纲和表格优于散文不要开场白preamble、不要复述刚做的事、不要重新解释 diff 里已经展示的修复。该纪律适用于每一条响应而非仅限状态更新。结果先行不叙事、不复述 diff、无填充式夸奖、不预告接下来要执行的计划。状态更新一行最终报告只写会改变读者下一步行动的内容。不重复造轮子CI、linter、审查机器人已经算过的结果直接读取——gh pr checks、gh api .../pulls/N/comments。最具可操作性的原则是机械规则mechanical rules放在确定性测试里绝不消耗代理精力。AGENTS.md 为此列举了四组已落地的确定性测试机械规则承载测试作用changelog 风格quiet styletests/test_changelog_style.py检查 CHANGELOG 的**Highlights**、单行条目、(#N)引用与致谢locale 一致性tests/test_locale_parity.py保证 21 个语言文件键值对等版本锁步tests/test_app_version.py校验所有版本文件同步test_all_version_files_in_lockstepCJK 硬编码tests/test_no_hardcoded_cjk.py拦截翻译层之外的用户可见 CJK 字符串以 tests/test_changelog_style.py 为例可以看到把规则编码成测试的典型做法_MAX_ENTRY_CHARS 400限制单条长度_REF_REQUIRED_SECTIONS {Added, Fixed}强制这两类小节必须携带(#N)或— thanks user!致谢并以_STYLE_EPOCH 2026-07-17为界对旧版本文档做 grandfathered 豁免。测试文件里还自带 linter 自测每个规则必须真的能触发以及版本只允许一个 section的重复版本检测。此外Token 经济还有一条 CI 诚实验证原则测试要用HF_HUB_OFFLINE1 空HF_HUB_CACHE模拟 CI——本地填充的模型缓存会掩盖真实的下载失败只有离线空缓存才能暴露问题。跨平台对等行为一致而非性能一致AGENTS.md 澄清了一个关键边界对等规则覆盖用户可见的行为BEHAVIOUR不覆盖性能。硬件加速因主机而异是设计使然CUDA / MPS / DirectML、Triton 可用性、torch.compile都属于主机相关能力某个优化在物理上无法工作时跳过它不算违反对等。反之不要用在所有平台禁用某项正常优化的方式来修复对等性问题——那等于用一个语义上的退化换取一个真实回归。判断标准是用户能做什么而不是跑得多快一个功能在一个 OS 上可见可用、在另一个 OS 上不可用就是违规。CLAUDE.md 给出了更完整的定义默认模式下开箱即用的功能必须在 macOS、Windows、Linux 上行为一致平台专属特性如 macOS 专属全局快捷键必须放在显式 opt-in 之后Settings 开关、环境变量或 CLI flag。默认行为在某平台不工作时属于P0 bug——要么修复缺失平台要么移入 opt-in没有第三条路。Merge 协议五条硬规则AGENTS.md 的合并协议是hard rules逐条不可妥协无审查不合并先收割 CodeRabbit Greptile 的评论两者均以 greptile.json 等配置注入上下文存在未读的 Critical/P1 评论时禁止合并——包括代理自己开的 PR。不接受原样 PR所有发现必须在合并前于 PR 分支上修复维护者提交没问题但要在 CHANGELOG 中致谢贡献者。禁止先合并再修merge-then-fix也禁止评论后走人。陈旧分支先合并 main 再判断 CIPR 在旧工作流下绿 ≠ 在新工作流下绿判断前必须把当前main合入。合并闸门Tests (backend frontend)检查通过 PR 处于MERGEABLE状态。每次合并后盯紧 main用gh run list --branch main观察 main 自己的 post-merge 运行red main 等于放下一切先修。这套协议与 docs/agents/issue-tracker.md 中的补充一致合并必须显式传--body给gh pr merge --squash防止自动生成Co-authored-by:尾注该仓库禁止 AI 署名尾注。Change Rules六类变更硬约束AGENTS.md 摘要了六类变更规则每类都在仓库中有可验证的落点。根因式修复与回归测试修复必须修一类而非一例root-cause the class配套fail-before / pass-after 回归测试并做最小正确变更smallest correct change。CLAUDE.md 补充了防复发加固的要求——例如若锁文件漂移只在 Docker 中失败就要让 CI 也能捕获。默认行为跨平台一致macOS / Windows / Linux 默认行为必须完全一致平台专属功能放在显式 opt-in 之后默认行为分叉 P0见上文对等小节。Local-first 保证不新增必需的网络调用任何 HFHugging Face下载必须被已安装状态或用户显式操作门控所有合成音频必须经过mark_synthetic关口——从源码搜索可见该关口分布在 backend/services/watermark.py、backend/api/routers/generation.py、backend/worker/executor.py等生成路径中与 backend/core/analytics.py 的 opt-in 分析体系共同构成数据不出机器的防线。用户可见字符串全部走 i18n所有用户可见字符串必须存在于全部 21 个语言文件中并带真实翻译不只是占位。语言文件集中在 frontend/src/i18n/locales覆盖ar/de/en/es/fr/hi/id/it/ja/ko/nl/pl/pt/ru/sv/th/tr/uk/vi/zh-CN/zh-TWCI 通过 tests/test_no_hardcoded_cjk.py 拦截翻译层之外的 CJK 硬编码功能性 CJK文本处理正则、模型词汇、测试夹具等则通过_ALLOWED_FILES白名单放行并逐条记录理由。文档同步与 CHANGELOG 风格docs-sync改动若影响 README、docs/**、许可协议等文档描述的内容必须在同一个 PR内同步更新文档过期文档视为 bugCHANGELOG## [Unreleased]采用 quiet 风格——先是简短的**Highlights**列表然后是### Changed / Added / Fixed / Docs / CI等小节每个条目是单行、以(#N)结尾社区贡献附— thanks user!。当前 CHANGELOG.md 即为此风格的实例。版本单一来源与锁文件frontend/package.json 是唯一版本真相来源未经所有者要求不得 bump工具链必需的镜像frontend/src-tauri/Cargo.toml、pyproject.toml、backend/core/version.py的_FALLBACK_VERSION必须与之锁步tauri.conf.json直接读../package.json由 tests/test_app_version.py 守卫修改frontend/package.json依赖必须重新生成根目录 bun.lock——deploy/Dockerfile 以bun install --frozen-lockfile构建普通bun install会静默容忍漂移。议题策略Issue 要么吸收、要么拒绝绝不推迟到未来版本实现社区报告的问题前先检查 open-PR 队列避免与贡献者重复劳动。共享选择控件规范AGENTS.md 对前端交互组件有一条明确约束所有新建或改版的下拉选择框必须使用 frontend/src/components/SearchableSelect.jsx语音选择复用 frontend/src/components/VoiceSelector.jsx禁止引入原生select控件。配套要求提供本地化的ariaLabel可访问性在滚动或裁剪容器内使用menuPortal避免菜单被裁切保留键盘选择与 disabled 状态。这是一致性优先于自由度的典型决策全仓库统一一个可搜索选择控件既保证可访问性与键盘导航一致也让 i18n 和样式维护集中化。Agent Skills 生态与配套文档技能锁定机制项目开发技能通过 skills-lock.json 钉死来源与哈希当前为mindrally/skills的fastapi-python与vite两个技能各带computedHash按声明安装到.agents/skills/目录。仓库规则与 issue tracker 映射优先级高于通用技能指引——即仓库契约覆盖通用技能建议。Issue Trackergh CLI 工作流AGENTS.md 规定 issue 跟踪走 GitHub Issues 与ghCLI详见 docs/agents/issue-tracker.md。该配套文档给出了可直接套用的命令模板# 创建 issue多行 body 用 heredoc gh issue create --title ... --body ... # 查看 issue含评论与标签 gh issue view number --comments # 列出 issue结构化 JSON 输出 gh issue list --state open --json number,title,body,labels,comments \ --jq [.[] | {number, title, body, labels: [.labels[].name], comments: [.comments[].body]}] # 评论 / 打标签 / 关闭 gh issue comment number --body ... gh issue edit number --add-label ... / --remove-label ... gh issue close number --comment ...文档还定义了 wayfinding 工作流wayfinder:map单 issue 作为地图、子 issue 作为 ticket通过 GitHub 原生blocked_by依赖表示阻塞frontier query选取无阻塞、无 assignee 的最早地图子项claim为gh issue edit n --add-assignee meresolve为作答、关闭并在地图 Decisions-so-far 中追加上下文指针。Triage 标签体系AGENTS.md 定义了五个规范角色每个标签字符串与其名称相同映射见 docs/agents/triage-labels.md标签含义needs-triage维护者需要评估该 issueneeds-info等待报告者补充信息ready-for-agent已充分描述可交给 AFK 代理ready-for-human需要人工实现wontfix不会被处理wontfix与needs-info早于本文件即已使用因此是恒等映射而非别名表——文档明确要求复用、不得制造变体如wont-fix。triage 标签与类型标签bug、enhancement、documentation、good first issue等正交打 triage 标签绝不意味着移除类型标签。领域文档消费约定AGENTS.md 要求单上下文仓库以CONTEXT.md docs/adr 承载领域知识详见 docs/agents/domain.md。要点包括探索代码前先读CONTEXT.md当前尚未创建与相关 ADR文件缺失时静默继续不主动建议创建输出领域概念时必须使用CONTEXT.md词汇表定义的术语不得漂移到同义词若输出与既有 ADR 矛盾显式标记冲突而非默默覆盖。从仓库现状看docs/adr 已沉淀了 5 份决策记录SPIKE-01-gguf-research.md、SPIKE-01-gguf.md、SPIKE-02-singing.md、apprun-strategy.md、inbound-node-mode.md覆盖 GGUF 研究、歌唱能力、应用启动策略等方向是决策落文档文化的直接证据。契约分层带来的工程启示纵观 VoiceStudio 的代理协作体系可以提炼出三层结构宪法层CLAUDE.md长期约束与价值观——版本化、docs-sync、local-first、修复质量契约层AGENTS.md每日操作规则——响应纪律、合并协议、变更约束、控件规范技能与文档层skills-lock.json docs/agents/工具能力与领域知识的接入方式。而贯穿始终的原则只有一条凡是能写成确定性测试的机械规则绝不消耗代理与人类的判断精力。changelog 风格、locale 对等、版本锁步、CJK 拦截均有对应测试守卫代理的精力只留给真正的判断——根因分析、跨文件语义、产品意图。这种规则可执行、违规可检测、冲突有优先级的契约设计正是多 Agent 协作仓库值得借鉴的工程模式。【免费下载链接】VoiceStudioVoiceStudio is the open-source, fully-local ElevenLabs alternative — voice cloning, voice design, video dubbing, dictation, transcription audiobook creation in 646 languages.项目地址: https://gitcode.com/GitHub_Trending/om/VoiceStudio创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表