> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ycloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# AGENTS

# YCloud 文档仓库 Agent 约定

## 仓库模型

* 本仓库使用 Mintlify。页面是 MDX，配置入口是 `docs.json`，重定向列表在 `config/redirects.json`。
* `en/` 是唯一英文源。直接修改英文内容时只能修改这里。
* `zh/`、`es/`、`pt/` 和 `ru/` 是本地化内容。
* `openapi/` 保存 API 定义。
* `product-assets/` 和 `logo/` 保存公开静态资源。
* `tooling/` 统一保存测试、导入、迁移和本地化代码。
* `.i18n/config.json` 定义 AI 本地化的源目录、目标语言和质量门槛。

## 修改前

1. 阅读 `README.md`。
2. 运行 `git status --short`，保留用户已有改动。
3. 先从 `docs.json` 的英文默认导航找到对应页面，确认目标语言、导航入口和实际 MDX 路径。侧栏分组名与磁盘目录不一定相同，文件存在不代表它仍是维护入口。
4. 检查 `config/redirects.json` 和下方 EOL 约定。旧地址已有重定向时，维护其当前目标页面，不要继续编辑退役页。
5. 查找符号和影响范围时优先使用 CodeGraph；查找字面文本时使用 `rg`。
6. 如果 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 改动在交付前应运行：

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
mint broken-links
mint validate
python3 -m unittest discover -s tooling/tests -v
```

移动或删除页面时增加：

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
mint broken-links --check-redirects
```

如果检查无法运行或因已有问题失败，报告具体命令和错误。不要把未运行的检查描述为通过。

## 外部资料

* 当前环境提供 Mintlify MCP 时，优先用它查询 Mintlify 行为。
* 没有 Mintlify MCP 时，仅使用 Mintlify 官方文档核实可能变化的行为。
* 不要为了普通内容修改安装额外技能或插件。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.