深入解读 TinaCMS Monorepo从 AGENTS.md 看开源 CMS 的工程规范与协作体系【免费下载链接】tinacmsTinaCMS is the leading open-source headless CMS that supports Markdown and Visual Editing. Your content is stored in your own GitHub repo ❤️项目地址: https://gitcode.com/GitHub_Trending/ti/tinacmsTinaCMS 是一款支持可视化编辑Visual Editing的开源无头 CMS内容直接存储在开发者自己的 Git 仓库中。本文以仓库根目录的 AGENTS.md 为骨架结合package.json、pnpm-workspace.yaml、turbo.json、示例应用与测试源码系统拆解这个 Monorepo 的目录结构、构建开发命令、Workspace 依赖协议、编码规范、Kitchen-Sink 示例架构以及 Issue 提报与分级流程帮助你快速理解该项目并具备直接参与开发与协作的能力。项目概览一个可插拔、多框架覆盖的开源 CMSTinaCMS 是开源的无头 CMS核心卖点是把内容存储在开发者自己的 Git 仓库中并围绕 Markdown / MDX 内容提供可视化编辑能力。整个代码库是一个 Monorepo包含核心包tinacms、CLI、Admin 应用以及面向多个框架的示例应用Example Apps。从 AGENTS.md 的Project Overview一节可以确认仓库的核心组成如下核心包Core Packagestinacms、tinacms-authjs、create-tina-app等位于packages/作用域包Scoped Packagestinacms/cli、tinacms/app、tinacms/datalayer、tinacms/graphql、tinacms/mdx、tinacms/scripts等位于packages/tinacms/框架示例应用Framework Example AppsNext.js、Astro、Hugo、React 的 kitchen-sink 示例以及 Next.js 自托管认证演示位于examples/测试与维护基础设施playwright/Playwright 测试基建、scripts/仓库维护脚本、tests/构建验证测试。安全与漏洞披露Agent 与开发者都必须遵守的硬性规则AGENTS.md 的 Security Disclosure 一节是整个文档中约束最严格的部分同时指向仓库根目录的 SECURITY.md。其核心规则可以归纳为三条硬性红线绝不通过公开 GitHub Issue 提交安全漏洞。无论漏洞严重程度如何都必须通过securitytina.io邮箱或 GitHub Security Advisory 草稿提交。这一点与 SECURITY.md 中 Do not report security vulnerabilities through public GitHub issues 的声明完全一致。绝不把漏洞细节写进测试注释、PR 描述或 commit message。如果某个回归测试是在防御一个已私下报告的已知问题必须使用中性措辞例如Pending upstream fix reported privately per SECURITY.md并且不要把错误信息、堆栈、受影响的函数名、响应体细节留在注释中。发现潜在漏洞时不要立即提交、推送或起草公开 Issue应停下来向用户说明发现内容与位置由用户决定披露路径邮件、草稿 Advisory或确认无害后公开。此外还规定当编写针对私下报告的发现的回归测试时需要用test.fixmePlaywright或框架等效机制标记具体用例并附上通用的 pending upstream fix 消息细节只放在私有渠道。这些规则的作用范围覆盖所有 Agent 可能修改的表面源文件、测试文件、内联注释、commit message、PR 描述、关联的 Issue 草稿乃至 README 片段。值得注意的还有 SECURITY.md 中独特的供应链安全策略新发布的包版本被视为供应链风险需要冷却期。仓库要求不安装发布时间不足 3 天的pkglatest除非获得安全团队签批检查发布时间的命令是npm view pkg time --json紧急升级例如补丁本身修复了一个活跃漏洞正是需要签批的场景而不是跳过签批的理由。这一策略在pnpm-workspace.yaml中也有呼应——配置了minimumReleaseAge: 1440分钟即 1 天以及针对tinacms/*、tinacms等自研包的豁免列表。Monorepo 目录结构核心包、示例与测试的布局逻辑AGENTS.md 给出了清晰的目录地图节选自原文结构packages/ # Core packages (tinacms, tinacms-authjs, create-tina-app, etc.) packages/tinacms/ # Scoped packages (cli, app, datalayer, graphql, mdx, scripts, etc.) examples/ # Framework example apps next/kitchen-sink/ # Next.js 15 — the reference kitchen-sink implementation next/tina-self-hosted-demo/ # Self-hosted with auth astro/kitchen-sink/ # Astro 6 — mirrors Next.js kitchen-sink hugo/kitchen-sink/ # Hugo kitchen-sink react/kitchen-sink/ # React kitchen-sink shared/ # Shared content and public assets across kitchen-sink examples playwright/ # Playwright test infrastructure scripts/ # Repo maintenance scripts tests/ # Build verification tests从实际仓库看这一结构与源码完全对应packages/tinacms/包含react.tsx、client.ts、tina-cms.tsx等核心实现packages/tinacms/cli/、packages/tinacms/graphql/、packages/tinacms/mdx/等各自独立成包examples/下的next/kitchen-sink/、astro/kitchen-sink/、hugo/kitchen-sink/、react/kitchen-sink/均配套了tina/config.tsx与tina/collections/playwright/下还有astro-init/、prebuilt-admin/、tina-playwright/等多个测试工程。其中特别值得关注的是examples/next/kitchen-sink/——AGENTS.md 明确它是参考实现reference implementation其他框架的 kitchen-sink 都以它为基准对齐功能。构建与开发命令pnpm 驱动的 Turbo 流水线AGENTS.md 的 Build Dev Commands 一节给出了四条最常用的命令均从仓库根目录执行命令实际执行内容pnpm install安装依赖pnpm buildturbo run build --filter./packages/**构建核心包pnpm dev先构建再通过tinacms/scripts进入 watch 模式pnpm testturbo run test --filter./packages/**运行核心包测试对照根目录 package.json 可以看到build脚本确实为turbo run build --filter./packages/**test脚本为turbo run test --filter./packages/**而dev/watch脚本则是pnpm run build pnpm --filter./packages/tinacms/scripts run watch——即先构建全部包再由tinacms/scripts的 watch 任务监听源码变更。根 package.json 还限定了运行时环境Node.js22.x || 24.x、npm11.x、pnpm11且packageManager固定为pnpm11.7.0。任务编排由根目录 turbo.json 定义build依赖^build即先构建依赖项test依赖build与typestypes依赖build与^typeslint依赖build与types并分别声明了dist/**、.next/**、coverage/**等输出产物目录。每个示例应用还有自己的dev、build、build:local脚本具体以示例目录下的package.json为准。例如 examples/next/kitchen-sink/package.json 中devcross-env MONOREPO_DEVtrue tinacms dev -c next dev --turbopack——用tinacms dev包一层 Next.js 开发服务器TinaCMS 会包装框架的开发服务器注入可视化编辑所需的能力buildtinacms build next build——先构建 Tina 配置与 Admin再构建 Next.js 应用build:localtinacms build --local --skip-cloud-checks -c next build——本地模式构建跳过云端检查。Workspace 配置与依赖协议workspace:^与workspace:*的区别AGENTS.md 的 Workspace Configuration 一节解释了pnpm-workspace.yaml、turbo.json与依赖协议的细节其中workspace:^vsworkspace:*的差异是理解这个仓库发包策略的关键示例应用使用workspace:*引用本地 TinaCMS 包——因为它们不发布精确锁定即可。在 examples/next/kitchen-sink/package.json 中可以看到tinacms: workspace:*、tinacms/datalayer: workspace:*。发布到 npm 的包其dependencies/peerDependencies中的内部引用必须使用workspace:^。原因是 pnpm 会把workspace:^发布为 caret 范围如^1.2.3npm 可以将内部包与使用方的副本去重而workspace:*会发布为精确固定版本导致重复依赖树嵌套在一个普通消费者应用中可能多出约 320 MB对应 issue #7207。devDependencies不会随包发布因此豁免。这一规则由 tests/workspace-protocol.test.ts 强制校验测试会扫描packages/tinacms/与packages/下所有非 private 包的dependencies、peerDependencies、optionalDependencies三个随包发布的段断言其中任何workspace:开头的引用都必须是workspace:^否则测试失败。这是用测试守护工程规范的典型示例。AGENTS.md 还强调了一个重要推论因为已发布的依赖在 caret 范围内浮动被同级已发布包消费的内部 API 是同一大版本内的兼容性契约——一个已发布的tinacms/cli/tinacms/app可能运行在更新版本的tinacms之上破坏这类 API 需要一次 major 版本升级。pnpm-workspace.yaml 还体现了两个值得关注的工程决策catalog:字段统一管理共享依赖版本如biomejs/biome: ^1.9.4、next: 15.5.21等各包通过catalog:引用避免版本漂移供应链冷却期minimumReleaseAge: 14401 天同时用minimumReleaseAgeExclude豁免自研包tinacms/*、tinacms、create-tina-app、next-tinacms-*保证刚发布的tinacms版本不会被阻塞。编码规范注释是最后手段、错误收窄用if、Biome 严格 TSAGENTS.md 的 Coding Standards 一节给出了四条可执行的硬规范注释是最后手段Comments are a last resort代码应当自解释只注释代码无法表达的内容非显而易见的约束、有文档记录的工作绕过方案。不允许叙述式注释、不允许复述下一行代码在做什么、不允许在几行代码上挂长篇头部注释。错误收窄用if而不是表达式必须写成if (err instanceof Error) { … } else { … }禁止(err instanceof Error err.message) || fallback或在三元表达式中夹带收窄逻辑。Lint/格式化使用 Biome根目录 biome.json 是基准配置示例应用通过extends: [../../../biome.json]继承可参考 examples/next/kitchen-sink/biome.json它额外忽略了.next/**。TypeScript 使用严格模式基础配置在 base.tsconfig.json示例应用通过extends: ../../../base.tsconfig.json继承。需要注意根base.tsconfig.json本身strict: false而示例应用会在自己的 tsconfig.json 中显式覆盖为strict: true——AGENTS.md 所述的strict mode enabled以各包的最终配置为准。包管理器方面规则明确只用 pnpm绝不使用 npm 或 yarn。还有一个针对 Windows 开发者的实用说明仓库里的CLAUDE.md是指向同级AGENTS.md的 git 符号链接。Windows 未开启开发者模式时若git status显示TT类型变更需要运行git config --local core.symlinks falsegit 会将其物化为普通指针文件Linux/macOS 克隆会自动得到真实符号链接。Kitchen-Sink 示例同一内容模型五个框架统一呈现Kitchen-Sink 是 TinaCMS 展示同一套能力跨框架一致可用的核心阵地。AGENTS.md 明确指出所有 kitchen-sink 示例实现相同的内容模型content modelexamples/next/kitchen-sink/是参考实现。统一内容 SchemaCollection格式内容路径集合文件TagJSONcontent/tags/tina/collections/tag.tsAuthorMDcontent/authors/tina/collections/author.tsxPostMDXcontent/posts/tina/collections/post.tsxBlogMDXcontent/blogs/tina/collections/blog.tsxPageMDXcontent/pages/tina/collections/page.tsxGlobalJSONcontent/global/tina/collections/global.ts关于.ts与.tsx的区分AGENTS.md 给出了明确说明.tsx集合文件包含用于自定义字段组件的 JSX例如global.ts的 theme 字段中引用的ColorPickerInput.ts文件则是纯 Schema 定义。这一区分在所有 kitchen-sink 示例中一致。对照实际源码可以印证tina/collections/tag.ts是一个纯 Schema 的 JSON 集合定义name字符串字段并标记isTitle: true、required: true而 examples/next/kitchen-sink/tina/collections/global.ts 是.ts文件却在 theme 字段的ui.component中引用了自定义的ColorPickerInput组件——因为该字段组件本身在../fields/color中实现global.ts只是引用它因此依然是纯 Schema。global.ts还展示了 Global 集合的典型写法ui: { global: true }标识全站级配置字段包括 header含可列表化的 nav 链接、footer含可列表化的社交链接和 theme颜色、字体、暗色模式三选一。Kitchen-Sink 共享模式AGENTS.md 总结了所有 kitchen-sink 应用共有的五条模式TinaCMS 包装框架开发服务器tinacms dev -c framework dev构建顺序tinacms build framework build内容统一放在content/目录各示例使用相同的 MDX/JSON 文件examples/shared/承担共享内容与公共资源Tina 配置在tina/config.tsx集合在tina/collections/Admin UI 输出到public/admin/媒体根目录为public/内的uploads/。这些模式在 examples/next/kitchen-sink/package.json 的脚本里都有直接体现。标准化技术栈工具选型包管理器pnpmworkspace 原生Lint/格式化Biome继承根配置样式Tailwind CSS 4CSS-first 配置TypeScript5.7 strict继承base.tsconfig.jsonTailwind CSS 4 的 CSS-first 配置方式与项目tailwind.config.js、PostCSS 配置如 examples/next/kitchen-sink/postcss.config.js相互配套。Issue 提交流程标准化的 H3 标题模板AGENTS.md 的 Filing Issues 一节详细规定了 Bug 报告的提交流程——无论通过 Discord#ask-for-help、GitHub Issue 表单还是 Agent 调用gh api提交都走同一份检查清单规范来源是.github/ISSUE_TEMPLATE/bug-report.yml。必填的 H3 小节程序化格式化 Issue 正文时必须使用这些精确标题### The exact error message——逐字粘贴的错误信息原文不是转述### Steps to reproduce——用户按顺序点击了什么### What you expected vs. what actually happened——预期与实际差异### Your environment——版本、框架以及任何非默认配置自定义 MediaStore、自定义认证、自托管配置等。可选但鼓励的字段### A way for us to reproduce——最小复现仓库链接### Relevant sections of your schema file——Schema 文件的相关片段### Client ID——与 TinaCloud 相关问题。特别强调### Your environment中的非默认配置细节是最常帮助直接定位根因的字段不要省略。对于 AgentClaude Code、Cursor、ChatGPT 或ssw-yakshaver之类的内部机器人程序化提 Issue应先按上述 H3 标题格式化正文再调用POST /repos/{owner}/{repo}/issues。Issue 分级与标签体系固定的分类法与 Triage 规则AGENTS.md 的 Issue Triage Labels 一节定义了仓库的固定标签分类法。提报或分级 Issue 时需要应用恰好一个主分类标签外加适用的项目/范围标签。主分类标签标签用途bug行为损坏、报错、崩溃、输出错误enhancement功能请求、新能力security漏洞、代码扫描告警先按 SECURITY.md 私下提交documentation文档、README、指南technical-debt重构、死代码、架构清理chore依赖升级、配置、构建、CI、脚手架tests新增或扩展测试覆盖perf慢、规模、吞吐、内存dx面向开发者的 CLI / 报错 / 日志ux视觉、UX、布局、文案、动画rich-textPlate、MDX、markdown 渲染、body 字段、embed 模板form-system表单字段、校验、脏状态、字段插件media媒体库、上传、浏览starter-templatecreate-tina-app、Astro/Next/Hugo starterself-hosted自托管配置、外部化、数据库、sqlite-leveleditorial-workflow分支、PR、受保护分支流程项目/范围标签与主分类并用v4——v4 架构重写的一部分epics #6830–#6837For 4.1——计划在 4.1 发布窗口内完成Pre 4.0——必须在 v4 发布前落地onboarding——适合项目新人的小型、边界清晰任务AI——AI Agent 可以单条 prompt 端到端实现的任务。Triage 规则分类法是固定的不要发明新的分类标签若都不合适则不贴标签并把该 Issue 交给人工分级不要给 v4 项目 Issue 贴onboarding或AI——这些是有意协调的工作关闭 Issue 时必须附带证据PR 编号、评论链接、fixed in version X.Y写进关闭评论若该 Issue 是被父 epic 阻塞的元追踪器则留一条 Triage note — do not close 评论复测提醒当关联 PR 已合并但无人确认修复生效时评论请原始报告者在当前环境上验证后再关闭。这套标签体系与 v4 重写计划packages/v4/目录、AGENTS.md 中提到的 epics #6830–#6837紧密联动说明标签不仅是分类工具更是版本规划与 Agent 任务分发的载体。总结一份可执行的 Agent 协作规范纵观整份 AGENTS.md它并非一份泛泛的贡献指南而是一套围绕 Monorepo 工程实践的可执行协作规范安全披露的红线、pnpm/Turbo 的构建流水线、workspace:^依赖协议及其测试守护、Biome 与严格 TS 的代码标准、五框架统一的 Kitchen-Sink 内容模型以及结构化到 H3 标题级别的 Issue 提报模板和固定标签分类法。对读者而言这份文档给出了参与 TinaCMS 开发的完整地图想跑起来看 package.json 与 pnpm-workspace.yaml想理解示例应用看 examples/next/kitchen-sink 的tina/collections/与tina/config.tsx想提有效 Issue直接套用### The exact error message等四个必填 H3 小节想判断任务是否适合 AI 自动化看AI与onboarding标签。无论你是人类开发者还是 Agent这份文档都足以让你在几分钟内进入可贡献状态。【免费下载链接】tinacmsTinaCMS is the leading open-source headless CMS that supports Markdown and Visual Editing. Your content is stored in your own GitHub repo ❤️项目地址: https://gitcode.com/GitHub_Trending/ti/tinacms创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考