AGENTS.md

本文件面向在 user-usage-docs/ 目录内工作的 AI Agent 或维护者，说明这个目录的作用、推荐阅读顺序、写作约束与引用真源。

本目录用途

• 这是一个“用户使用说明子站”，面向用户、运营、支持等非代码实现视角读者。
• 本目录负责把仓库里已经成立的正式路由规则，改写成更容易理解的说明文档。
• 本目录不是代码真源，也不是数据库或运行时实现的权威定义来源。

先读这些文件

1. README.md
2. navmenu.md
3. upstream-supply-route-group-api-key.md
4. supply-management-and-route-group-selection.md
5. ../docs/architecture/request-routing.md
6. ../docs/domains/vendor-routing.md
7. ../docs/domains/api-overview.md
8. ../AGENTS.md

写作约束

• 优先使用用户、运营、支持同学能直接理解的表达，少用未解释术语。
• 不得虚构路由规则、绑定关系、API 行为、页面入口或实现边界。
• 当本目录说明与仓库权威文档冲突时，以仓库权威文档为准，并同步修正本目录内容。
• 新增页面时，必须同步更新 README.md 与 navmenu.md，让入口和导航保持一致。
• navmenu.md 的导航层级来自标题层级，不来自列表缩进；不要跳级，也不要使用四级以上标题表达导航结构。
• 页面内容优先保持 mkdocs 内容页风格：明确 H1、简短摘要、任务化二级标题、页尾相关页面。
• 这里的正文重点是帮助理解，不要把数据库表名、DI 细节或测试约束直接堆成主体内容。
• 不得再把 user_supply_binding、用户 availability 或 isEnabledForUser 说成当前正式用户侧真源。
• 不得再写 dashboard 可以通过 upstream supply 页面控制“对当前用户生效”。
• 若提到 Route Group 编辑入口，必须使用当前 vendor 维度的三类来源口径，而不是旧的 availability / binding 口径。

引用真源

• ../docs/architecture/request-routing.md
• ../docs/domains/vendor-routing.md
• ../docs/domains/api-overview.md
• ../AGENTS.md

交付前检查

• 本目录新增或修改的页面，是否都能从 README.md 和 navmenu.md 找到入口。
• 文中是否清楚区分了 Local Api Key 与 upstream API key。
• 文中是否错误写成了“Route Group 直接绑定 upstream key”或“系统会自动组外 fallback”。
• 文中是否还把 user_supply_binding、用户 availability 或 isEnabledForUser 当成当前正式用户侧真源。
• 文中是否错误写成 dashboard 可以在 supply 页面编辑“对当前用户生效”。
• 如果提到 Route Group 编辑方式，是否已经改成 All Private Supply / Self Shared Supply / Other User Shared Supply。
• 所有相对链接是否都真实存在。
• 如果引用实现口径，是否已经回到仓库正式文档核对过。