Omi 公开文档站治理指南读懂 docs/AGENTS.md 的内容边界与发布规则【免费下载链接】FriendAI that sees your screen, listens to your conversations and tells you what to do项目地址: https://gitcode.com/GitHub_Trending/fr/Frienddocs/AGENTS.md是 Omi 开源仓库中负责定义公开文档站docs.omi.me内容边界的治理文件。本文以其为骨架系统讲解该文件的三层规则——站点定位、允许发布的内容清单、严禁混入的内部资料类型并结合仓库中docs.json、Cursor.mdx、backend/docs/等真实路径说明贡献者在编辑公开文档时必须遵守的约束帮助贡献者与 AI Agent 正确区分公开文档与内部知识。一、文件定位docs/ 是公开站点不是仓库内部 Wikidocs/AGENTS.md开篇就明确了核心事实docs/目录是公开的 Mintlify 站点对应线上域名 docs.omi.me它不是仓库的内部 Wiki。这意味着两件事docs/下的内容会被 Mintlify 渲染成公开网页任何访问 docs.omi.me 的人都能看到仓库内部的知识设计文档、runbook、不变量等有各自的存放位置不应该暂时放进docs/。需要特别注意的是Mintlify 会忽略非 MDX 文件例如AGENTS.md本身但这并不代表隐藏只要docs/下存在未在导航中列出的 MDX 或 MD 文件它依然会以公开 URL 的形式存在。docs.json决定的是导航nav中的展示llms.txt会索引导航页面没有出现在 docs.json 中不等于保密。这一设计在 docs/doc/developer/Cursor.mdx 中被再次强调docs/是公开站点.cursor/是编辑器/Agent 配置目录两者有本质区别。二、允许发布的内容清单Allow Listdocs/AGENTS.md将允许发布到公开站点上的内容限定为三类如何使用 App面向普通用户的产品使用指南例如 docs/doc/get_started/introduction.mdx、docs/doc/get_started/chat_tips.mdx硬件与 DIY硬件组装、购买指南、刷机等例如 docs/doc/assembly/Build_the_device.mdx、docs/doc/assembly/Buying_Guide.mdx、docs/doc/hardware/OmiConsumer.mdx如何在 Omi 上构建Apps、API、MCP、CLI、SDK、固件以及贡献搭建相关例如 docs/doc/developer/apps/Introduction.mdx、docs/doc/developer/api/overview.mdx、docs/doc/developer/mcp/introduction.mdx、docs/doc/developer/cli/introduction.mdx、docs/doc/developer/sdk/sdk.mdx、docs/doc/developer/firmware/Compile_firmware.mdx、docs/doc/developer/Contribution.mdx。对照 docs/docs.json 中navigation.tabs的组织Documentation、API Reference、Build Apps、Hardware、MCP、CLI 六大 Tab可以清楚看到整个公开站点就是围绕这三类内容搭建的。三、严禁混入的内容Forbiddendocs/AGENTS.md用两个 Do not 明确了红线红线一不要往 docs.json 添加不符合 Allow List 的页面。只有符合上述三类内容主题的页面才有资格进入 docs/docs.json 的导航结构。红线二不要把内部资料暂时扔进 docs/。文件明确点名了以下内部资料类型设计笔记design noterunbook运维手册invariant产品不变量特性开关表flag table白名单allowlist应急开关kill switchwriter mode事故记录incidentepic仅供 Agent 使用的规则这些内容必须放在所属代码旁边具体路径包括资料类型正确存放位置仓库相对路径后端设计/运维文档backend/docs/如runbooks/、feature-flag-registry.md、durable_queues.mdx桌面端macOS文档desktop/macos/docs/Agent 专用规则.github/agent-docs/产品不变量product/invariants/如memory-tiers.md、auth-session.md、task-capture-suggestion-only.md或私有追踪器——以 product/invariants/ 为例该目录下存放了account-cohort-cutover.md、memory-canonical-fail-closed.md、desktop-shell-feature-parity.md等 20 个不变量文档这些是团队内部的产品约束绝不应当出现在公开文档站上。四、公开与保密的边界文档公开不等于仓库公开docs/AGENTS.md特别澄清了一个容易被误解的点Omi 仓库本身是公开的backend/docs/下的文件本来就存在于 GitHub 上。docs/目录只控制哪些内容会发布到 docs.omi.me它不是一个保密机制。换句话说即使某些内部文档没有出现在公开站点上也不代表它们在仓库里是隐藏的。贡献者如果希望内容保密正确做法是放入私有追踪器而不是寄希望于不把页面加进 docs.json。五、编辑规范修改 docs/ 前必须遵守的流程文件末尾给出了三条编辑约束先读本文件再动手在docs/下添加任何内容之前必须先阅读docs/AGENTS.md确认内容符合 Allow List贡献者 Cursor 配置的位置贡献者的 Cursor 配置说明位于 docs/doc/developer/Cursor.mdx该文件会引导读者回到本治理规则而仓库根目录的.cursor/是编辑器/Agent 配置目录包含rules/、hooks/、mcp.json等不是公开站点内容移动页面时同步更新引用移动页面后必须在同一次变更中更新仓库内的相关链接避免出现失效链接。六、源码佐证docs.json 与 .cursor 的呼应通过观察 docs/docs.json 可以印证治理规则的落地情况该文件的navigation.tabs中包含了 Documentation、API Reference、Build Apps、Hardware、MCP、CLI 六个 Tab所有页面均属于 App 使用、硬件 DIY、Omi 构建三类 Allow List 主题没有出现任何 runbook、flag table 或不变量页面。同时docs/doc/developer/Cursor.mdx 详细说明了.cursor/目录的用途rules/按 glob 自动生效的规则文件、skills/可复用的 playbook含SKILL.md、commands/、agents/、commands/、agents/、docs/内部 Agent 参考文档、hooks/与mcp.json。仓库中实际存在的.cursor/rules/backend-imports.mdc、.cursor/rules/flutter-localization.mdc、.cursor/hooks/format.sh等文件正是这一结构的体现且 Cursor.mdx 明确提醒不要把 secrets 放进 .cursor 文件、不要往公开站点放运维 runbook、flag 和 invariant——这与docs/AGENTS.md的禁止清单完全一致。七、实操清单贡献者与 Agent 的决策速查结合全文可以整理出一份可执行的决策清单新增公开文档先读docs/AGENTS.md→ 判断内容是否属于三类 Allow List → 是则新增 MDX 并在docs.json登记 → 否则不放docs/内部知识归档按类型放入backend/docs/、desktop/macos/docs/、.github/agent-docs/、product/invariants/或私有追踪器移动/重命名页面在同一变更中同步更新所有仓库内链接保密预期管理记住docs/不是保密机制公开仓库中的文件天然可见真正的保密要靠私有渠道AI Agent 参与编辑Agent 在处理docs/相关任务时同样以docs/AGENTS.md为最高准则防止把内部 runbook、flag 表等误写入公开站点。这份文件虽短却是整个 Omi 开源项目公开文档与内部知识分流的枢纽它决定了哪些内容能对全世界用户可见哪些内容必须留在代码旁边由团队掌控值得每一位贡献者与自动化 Agent 在触碰docs/之前认真阅读。【免费下载链接】FriendAI that sees your screen, listens to your conversations and tells you what to do项目地址: https://gitcode.com/GitHub_Trending/fr/Friend创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
