OpenIsle/docs/AGENTS.md

Docs 协作指引

1) 适用范围

• 作用于 docs/ 目录及其子目录。
• 文档需服务“开发者真实使用”，优先准确性与可执行性。

2) 文档架构

• 内容目录：content/docs/
• 生成脚本：scripts/generate-docs.ts
• OpenAPI 输入配置：lib/openapi.ts
• 前端框架：Fumadocs + Next.js（Bun 工具链）

3) 编辑规则

• 优先修正“与代码不一致”的文档，不复制过时描述。
• 涉及技术栈说明时，以当前代码为准（例如后端为 JPA/Repository）。
• OpenAPI 自动生成目录（content/docs/openapi/(generated)）不要手工细改，改源头配置与脚本。
• 结构性改动优先维持导航稳定（meta.json 与已有 slug）。

4) OpenAPI 同步规则

• 后端 API 变更后，应重新生成文档页面：
  • bun run generate
• 若接口来源地址或文档聚合策略变化，更新：
  • lib/openapi.ts
  • scripts/generate-docs.ts

5) 验证命令

• 安装依赖：bun install
• 生成 API 文档：bun run generate
• 构建校验：bun run build
• 本地预览：bun dev

6) 输出要求

• 说明更新了哪些文档入口（backend/frontend/openapi）。
• 说明是否需要后端先部署后再刷新文档产物。