Tamagui 多仓 Agent 操作契约AGENTS.md 中的完成标准、测试流水线与认证调用规范【免费下载链接】tamaguiStyle React fast with 100% parity on React Native, an optional UI kit, and optimizing compiler.项目地址: https://gitcode.com/GitHub_Trending/ta/tamaguiAGENTS.md是 Tamagui 单仓库monorepo的Agent 操作契约它规定了 AI 编码代理以及人类贡献者在改动代码后如何判定任务完成、如何重建工作区包、如何提交 commit以及 Tamagui 的 Web 集成测试如何按动画驱动animation driver矩阵运行。读完本文你能掌握该仓库的验收标准与验证层级、kitchen-sink 测试套件的双命名约定与四驱动并行机制含 Playwright 配置源码级解读以及 tamagui.dev 站点端侧 API 认证authFetch的强制用法与底层原因。AGENTS.md 是什么一份被所有 Agent 共享的规则文件仓库根目录的 AGENTS.md 定义了跨代理的统一规则而 CLAUDE.md 只是指向它的符号链接——这一点可以直接在仓库中验证CLAUDE.md - AGENTS.md。文档原文明确说明CLAUDE.mdis a symlink to this file, so Claude, Codex, and every other agent read the same rules.这种设计的目的只有一个让 Claude、Codex 等所有 Agent 读取同一份持久化的仓库级指导避免规则在多份文件间漂移。文档还要求将持久、适用于整个仓库的 Agent 指导都沉淀到这份文件里并要求同时阅读 CONTRIBUTING.md。完成标准做完、验证、并合并回 main契约中排名第一的失败模式是过早停止修好的东西留在分支上、迁移写好了但从没执行、关键项下次再做被无限期搁置。AGENTS.md 给出的判定标准是——一项请求只有满足以下条件才算完成已提交、已推送、已验证并且合并回main或已开 PR 并推动到合并。我留在分支上了 / 我把 SQL 准备好了 都不算完成在其改动的层级完成验证代码改动用 typecheck/build 验证站点行为用真实请求或 Playwright 跑一遍验证数据库/RLS 变更用已应用并验证过的查询验证。应该能跑 不构成验证迁移必须真正被执行且线上状态被核验。该仓库的 Tamagui 官网tamagui.dev生产迁移历史不会在部署时自动应用见 Supabase 迁移说明一个提交了但从未运行的迁移是未闭合的缺口而不是修复安全/支付类工作尤其要求端到端闭环——一份没有随已部署的修复一起交付的漏洞记录等于没有修复。文档同时划定了唯一允许硬停的边界对外不可逆的操作——向 npm 发布/发版、force-push、轮转凭据、修改生产基础设施Cloudflare、DNS、Railway 配置。遇到这些情况应暂停并确认如果被它们阻塞就带着精确的手动步骤交还给用户。其余情况继续做而不是报告。构建约定改包要重建长时调试用 watchTamagui 是一个由code/core/**、code/ui/**、code/compiler/**等约 100 个工作区包组成的 bun workspace monorepo见根 package.json 的workspaces字段。AGENTS.md 对此给出两条构建指令改动包时必须重新构建在包目录下执行bun run build例外是你或别人已在仓库根目录运行了bun run watch长时间调试建议后台运行bun run watch它更快并会重建所有包。对照根 package.json 中的脚本可以印证这两条说法build: turbo run build即每个包执行bun run build等价于 turbo 按依赖序重建而watch: npm-run-all --parallel watch:ts watch:packages并行跑 TypeScript 类型重建scripts/watch-ts.ts与 JS 包重建。CONTRIBUTING.md 补充了构建的产物形态JS 编译到dist以支持0-setup安装每个文件编译出.native版本web 文件中把 react-native 替换为 react-native-web类型则输出到各包的./types/*.d.ts。Commit 约定单行 conventional commit changelog 前缀豁免AGENTS.md 对提交信息的要求保持单行关联 GitHub issue 时追加尾部Fixes #以 conventional commit 风格开头——除非该改动不应进入 changelog不应进入 changelog 的改动使用docs:、site:这类前缀。文档Commit Message Conventions小节进一步固化了两条具体规则改动范围应使用的前缀不应使用原因tamagui.dev 站点site:fix(site):不进 changelogCI / workflowci:fix(ci):不进 changelog这与仓库根 package.json 里release: bun ./scripts/release.ts的发布脚本流程相呼应发布工具按包聚合 changelog前缀约定保证了哪些改动会被计入用户可见的版本说明。Kitchen Sink 测试Tamagui 组件的主集成测试场AGENTS.md 指出kitchen-sink包承载 Tamagui 组件的主要集成测试。完整操作路径如下。1. 启动 Web 服务器并打开具体用例cd code/kitchen-sink bun run start:web # 后台启动打开某个测试用例open http://localhost:7979/?testYourTestCaseName——用例名与 code/kitchen-sink/src/usecases/ 下的文件名一致如SelectFocusScopeCase打开某个组件 demoopen http://localhost:7979/?demoSelect——demo 名对应 code/demos/src/ 下去掉Demo后缀的文件名Select对应SelectDemo.tsx。2. 全量 Web 测试default webkit 串行四驱动并行bun run test:web该命令由 code/kitchen-sink/package.json 中的test:web: bun run-tests-parallel.ts指向 run-tests-parallel.ts。阅读源码可以确认 AGENTS.md 描述的执行编排完全属实startServer()以PORT9000、DISABLE_EXTRACTIONtrue启动单个共享的 webpack dev serverwaitForServer()轮询直到页面包含idroot最长 120s随后先串行跑--projectdefault --projectwebkit任一失败立即exit(1)再以Promise.all(DRIVERS.map(runDriver))并行跑四个动画驱动项目每个子进程注入TAMAGUI_TEST_ANIMATION_DRIVERdriver与REUSE_SERVERtrue全部复用同一 dev server并按驱动着色输出[css]/[native]/[reanimated]/[motion]前缀最后打印汇总表。3. 指定单个动画驱动cd code/kitchen-sink NODE_ENVtest TAMAGUI_TEST_ANIMATION_DRIVERcss npx playwright test --projectanimated-css # 可选项目animated-css, animated-native, animated-reanimated, animated-motion四个驱动的取值定义在 tests/test-utils.tsexport const ANIMATION_DRIVERS [css, native, reanimated, motion] as const4. 单文件与调试# 直接指定测试文件 npx playwright test tests/PopoverFocusScope.test.tsx # 指定驱动 NODE_ENVtest TAMAGUI_TEST_ANIMATION_DRIVERcss \ npx playwright test tests/YourTest.animated.test.tsx --projectanimated-css # 调试模式 bun run test:web:debug # 或 npx playwright test --debug测试文件命名约定.test.tsx与.animated.test.tsx的二分测试位于 code/kitchen-sink/tests/命名即调度语义ComponentName.test.tsx—— 标准测试只在默认驱动下运行一次ComponentName.animated.test.tsx—— 动画相关测试在全部四个驱动css、native、reanimated、motion下各运行一遍。这个分离的设计动机在 playwright.config.ts 顶部注释里写明多数测试不需要跨 4 个驱动重复执行二分约定显著压缩了套件总时长。配置文件将其落实为项目project划分default项目testIgnore: **/*.animated.test.{ts,tsx}metadata 驱动为native每个驱动由drivers.map(...)展开为animated-driver项目testMatch: **/*.animated.test.{ts,tsx}例外细节AnimationsWithMediaQueries.animated.test.tsx目前仅在css与motion驱动下通过其余驱动被testIgnore排除另有webkit项目仅匹配RemoveScroll.test.*验证滚动恢复与webkit-sheet项目移动 WebKit匹配SheetWebKeyboard*.test.*注释说明原因是 chromium 的 touch/scroll/rubber-band 行为与 iOS Safari 不同关键运行参数baseURL: http://localhost:9000、viewport: 1920x1080更大的视口以避免 popover 定位问题、timeout: 50_000、CI 下workers: 2 / retries: 2本地workers: 4 / retries: 1。文档给出的经验法则是只有当测试确实在验证跨驱动动画行为时才用.animated.test.tsx。编写测试的实用提示与常见坑AGENTS.md 对焦点/交互类测试给出四条提示并列出三类常见问题为动画与焦点变化预留合适的等待时间trapFocus行为取决于组件的 open 状态同时覆盖焦点被圈住与未被圈住两种场景当trapFocus为 false 时考虑浏览器自身的焦点行为。因时序导致的失败加合适的waitForTimeout焦点测试断言焦点前先确保元素可见popover/dialog 测试等待动画完成后再断言。其他测试层的位置CONTRIBUTING.md 补充了测试分层地图与 AGENTS.md 的 Playwright 部分互为呼应编译器与 CSS 生成测试code/compiler/static-tests大量原生测试code/kitchen-sink/tests核心测试code/core/core-test提交 PR 前应在所有环境组合下确认通过。iOS 开发交给专门文档AGENTS.md 的iOS Development小节是一行指针iOS 原生开发与 Detox 测试的提示见 docs/using-ios.md。仓库中 CONTRIBUTING.md 给出了对应的可运行入口bun run detox:run:ios可加测试名过滤或用DETOX_DEVICEiPhone 16 Pro覆盖模拟器设备以及 Xcode 更新后修复框架缓存的npx detox clean-framework-cache npx detox build-framework-cache。tamagui.dev 端侧 API 认证强制使用 authFetch文档最后一条可执行规则针对 tamagui.dev 的客户端认证调用任何需要认证的 API 请求必须使用authFetch助手import { authFetch } from ~/features/api/authFetch const response await authFetch(/api/some-endpoint, { method: POST, body: JSON.stringify({ ... }), })其源码 code/tamagui.dev/features/api/authFetch.ts 印证了文档声明的动机助手先通过getAccessToken()来自~/features/auth/useSupabaseClient取当前用户的访问令牌统一设置Content-Type: application/json并在令牌存在时写入Authorization: Bearer token头注释明确写道生产环境中仅靠 cookie 认证不可靠跨域/SameSite 问题服务端ensureAuth的校验顺序是Authorization 头Bearer优先cookie 仅作回退且在某些环境不可靠。因此文档强调所有支付/订阅端点都必须走authFetch。这条规则与该仓库的数据库安全基线一致——code/tamagui.dev/supabase/README.md 记录了因缺少 RLS 导致的真实提权事故anon 把自身插入pro_whitelist并要求每张public表启用行级安全策略恰好是 AGENTS.md 中DB/RLS 变更必须应用并验证这一完成标准的落点。小结这份契约回答了什么才算做完AGENTS.md的价值不在罗列工具而在给出可检验的验收语义合并回main才算完成、验证必须发生在被改动的层级、迁移必须真实执行、对外不可逆操作是唯一的硬停边界。配合 bun workspace 的构建命令、kitchen-sink 双命名 四驱动并行的 Playwright 矩阵以及 tamagui.dev 的authFetch强制用法它构成了一份 Agent 与人类贡献者共同遵守的端到端工程合同。【免费下载链接】tamaguiStyle React fast with 100% parity on React Native, an optional UI kit, and optimizing compiler.项目地址: https://gitcode.com/GitHub_Trending/ta/tamagui创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考