YCloud 文档仓库 Agent 约定
仓库模型
- 本仓库使用 Mintlify。页面是 MDX，配置入口是
docs.json，重定向列表在config/redirects.json。 en/是唯一英文源。直接修改英文内容时只能修改这里。zh/、es/、pt/和ru/是本地化内容。openapi/保存 API 定义。product-assets/和logo/保存公开静态资源。tooling/统一保存测试、导入、迁移和本地化代码。.i18n/config.json定义 AI 本地化的源目录、目标语言和质量门槛。
修改前
- 阅读
README.md。 - 运行
git status --short，保留用户已有改动。 - 先从
docs.json的英文默认导航找到对应页面，确认目标语言、导航入口和实际 MDX 路径。侧栏分组名与磁盘目录不一定相同，文件存在不代表它仍是维护入口。 - 检查
config/redirects.json和下方 EOL 约定。旧地址已有重定向时，维护其当前目标页面，不要继续编辑退役页。 - 查找符号和影响范围时优先使用 CodeGraph；查找字面文本时使用
rg。 - 如果 CodeGraph 未初始化，询问用户是否运行
codegraph init -i，不要自行初始化。
Messaging 旧目录（EOL）
api-reference/guides/messaging/已 EOL，冻结内容维护；近期及后续 WhatsApp 指南改动应放到en/api-reference/guides/whatsapp-platform/。- 当前页面为
send-whatsapp-message.mdx、handle-whatsapp-inbound-messages.mdx、whatsapp-messages-api-best-practices.mdx和upload-whatsapp-media.mdx；其他语言使用相同相对路径。同步docs.json的所有语言导航，并为已发布的旧路径保留永久重定向。 - 旧目录中的
send-sms.mdx、send-email.mdx和send-voice-code.mdx暂时保留兼容并冻结维护，不要移入 WhatsApp 目录。 - EOL 仅指旧文档目录，不表示 SMS、Email、Voice 或 WhatsApp 消息产品 EOL。
documentation/whatsapp-business-platform/messaging/仍是当前产品概念文档，继续按正常流程维护。
修改规则
- 使用主动语态和第二人称，保持句子简短。
- 标题使用 sentence case。
- UI 元素使用粗体；命令、路径、字段和代码使用代码格式。
- 内部链接必须包含语言前缀，例如
/en/...或/zh/...。 - 保持 frontmatter、代码块和 MDX 组件有效。
- 新增、移动或删除页面时同步检查
docs.json。 - 多语言导航结构以
docs.json的英文默认导航为生成源。结构变更必须同步所有语言；本地化条目只修改显示名称和语言路径前缀。不要只通过 Mintlify Web Editor 修改单个语言的导航结构。 - 改变已发布路径时在
config/redirects.json添加重定向。 - 不要在示例中写入真实凭证或个人信息。
- 不要修改任务范围之外的语言和页面。
本地化规则
--paths相对于en/，不要包含en/前缀；自动化也可以使用--changed-from <ref> --changed-to <ref>限定 Git 变更范围。- 先用同一组
--paths或--changed-from/--changed-to参数运行plan。 - 写入前用相同范围运行
translate ... --dry-run。 - 只有任务明确要求生成翻译时才使用
--write。 - 使用
--write时必须用--paths或--changed-from限定范围，除非用户明确要求全量处理。 - 工具直接读取
en/，不会生成英文镜像。 - 不要提交
.env.i18n.local或任何密钥。 - 不要绕过
.i18n/review-queue/的质量门槛。
验证
文档、导航、工具或 OpenAPI 改动在交付前应运行：外部资料
- 当前环境提供 Mintlify MCP 时，优先用它查询 Mintlify 行为。
- 没有 Mintlify MCP 时，仅使用 Mintlify 官方文档核实可能变化的行为。
- 不要为了普通内容修改安装额外技能或插件。