本文件适用于整个仓库。处理 content/**、WASM 文档结构、审核记录和生成产物时，必须遵守以下规则。
- 修改任何 MDX 正文前，必须完整阅读当前页面，理解页面目标、上下文、示例、相关页面和 API 归属。
- 正文必须逐页手工修改。禁止使用脚本、正则、批量替换或生成器统一生成、插入、删除、翻译或重写正文。
- 即使多个页面需要相似内容，也必须根据每页的 API、参数、响应、事件和业务场景分别撰写，不能机械复制模板后替换方法名。
- 生成器只用于建立或维护页面结构、导航和确定性的派生数据，不负责产出最终正文。
- 脚本只允许用于只读盘点、校验、构建、生成索引和修改完全固定的结构字段。不得让脚本修改 MDX 正文。
- 每完成一页正文修改，必须同步检查并更新该页的可追溯审核记录。
- 中文文档优先。中文全部完成并审核通过后，才能开始英文正文；英文在此之前只保留延后发布的结构骨架。
- 页面结构和组织方式可以参考 Sendbird，但正文中的能力、API、参数、响应、事件和数据模型必须来自 OpenIM。
- 不得为了匹配 Sendbird 页面而编造 OpenIM 不存在的频道、元数据、计数器、翻译、推送、举报、Application 或其他能力。
- OpenIM 专属能力必须按实际领域补齐，不能因 Sendbird 没有对应页面而遗漏。
- 参考现有 OpenIM 文档时，应使用审核清单固定的不可变提交链接，并结合固定 WASM 声明核对。
- WASM API 基线为
@openim/wasm-client-sdk@3.8.3-patch.15.1。 - WASM 包只作为核对 API、参数、响应和事件的证据，不得添加为站点运行时或构建依赖。
- 除
wasm/logger日志页外，正文和示例中不说明或传递operationID。日志页可以集中说明其调用链路追踪用途、自动生成规则和最小示例，其他 API 页面不得重复展开。 - 已废弃方法不写入公开正文；其能力必须在替代 API 页面中说明。
setConversationDraft()作为独立草稿能力正常记录，正文不讨论其错误的 deprecated 声明。- 不记录非分页的
getFriendList()和getAllConversationList()；好友列表和会话列表必须使用分页接口。 Login和UnUsedEvent不写入公开事件文档。- 用户、会话、群组、消息和音视频通话使用 OpenIM 的真实领域划分，不恢复 Sendbird Channel 模型。
- 任务型指南页面应把参数语义紧贴对应操作和示例说明，不得为了形式完整单独复制 TypeScript 方法签名、
Promise<WsResponse<...>>或通用“API 参数”章节。 - 参数和结果说明以“操作”为组织单位，不以整页或 API 数量为单位。每个 API 必须归入明确的操作标题；同一页面包含多个 API 时，各自的参数和结果必须留在对应操作内部，不得在页面级章节中混合罗列。
- 统一使用“参数说明”和“返回结果”作为说明标题，不使用“请求参数”“返回值”“参数列表”等平行叫法。标题不是必备模板：内容用一两句话即可讲清时，直接紧贴示例说明，不为追求形式一致增加空洞章节。
- 单个操作包含三个及以上业务字段，或存在分页、筛选、枚举、单位、互斥关系、必填边界及易混淆字段时，才在该操作内部使用“参数说明”表格。无参数、单个简单值或一至两个含义明确的字段使用正文说明。
- 不得把多个 API 的参数合并到同一张表。两个 API 即使参数对象相同，也应在各自操作中说明调用差异；只有当它们共同构成一个不可拆分的操作并且字段语义完全一致时，才可以先说明共同字段，但仍需明确字段分别传给哪个 API。
- 参数说明只能列固定 SDK 声明中的真实参数或对象字段。示例变量、业务状态和后续 API 的参数必须在对应上下文中说明，不得伪装成当前 API 参数。
- “返回结果”应描述 Promise 成功的业务含义和页面实际使用的
data。只有返回对象包含多个需要查阅的字段、分页信息、嵌套结构或易混淆状态时才使用表格；void、unknown、简单标量和元素类型已有归属页的简单数组使用正文说明。 - 不得把
WsResponse<unknown>、泛型占位或完整 TypeScript 返回签名当作文档价值。查询 API 应说明返回的快照类型；状态变更 API 应说明 Promise 成功代表请求完成到哪个阶段，但不得将其等同于事件到达或所有端状态已经更新。 - 一个操作的推荐顺序是：场景和方法说明、参数说明（必要时）、调用示例、返回结果与后续影响。若先展示完整调用更有助于理解，可以把参数说明放在示例之后，但同一操作内不得穿插其他 API 后再回头解释参数。
- 多个同类创建 API 可以按消息类型等业务维度组织，并在页面末尾统一说明它们共同返回的对象及“只创建、不发送”等共同边界；共享结果说明不得掩盖各 API 特有的参数和行为。
- 会改变状态的 API 页面必须说明：Promise 成功代表什么、相关事件、事件载荷、客户端合并标识和完整监听代码所在页面。
- Promise 成功、事件到达和重新查询校准是三个不同阶段，不得写成同一件事。
- 每个事件只有一个正文归属页面。只有归属页面可以展示完整的
OpenIM.on()、OpenIM.off()和状态合并代码。 - 非归属页面只说明事件影响并链接到归属页面，不得重复注册相同事件。
- 所有
OpenIM.on()示例都必须使用稳定函数引用，并提供对应的OpenIM.off()清理示例。 - 查询 API 负责建立快照，事件负责合并增量。纯查询、消息对象创建和本地操作不得被错误描述为触发共享事件。
- 没有证据证明某 API 必然触发事件时，使用条件措辞或说明以调用结果、事件或重新查询校准，不能编造确定关系。
- 事件归属以
data/structure/wasm-api-ownership.json为准；调整归属时必须同时更新正文、所有权清单、审核记录和测试。
常用状态合并标识：
- 会话：
conversationID - 会话分组：
conversationGroupID - 群组：
groupID - 群成员：
groupID:userID - 好友和黑名单：
userID - 消息：
clientMsgID，必要时同时限定conversationID - 通话：
roomID，参与者状态同时使用用户 ID
不得使用数组下标、展示名称或当前分页长度作为事件合并标识。
-
页面合并或删除时，必须同步处理导航、路由、中文正文、英文骨架、旧地址重定向、API/事件所有权和审核记录。
-
被合并或删除的页面仍需保留可追溯审核记录；真实能力合并后应保留合理的永久重定向。
-
不得把生成产物当作人工审核证据。审核状态必须对应真实的逐页检查。
-
修改完成后至少运行
pnpm check；涉及路由、页面结构、构建逻辑或发布状态时还必须运行pnpm build。 -
pnpm build可能改写next-env.d.ts。构建后恢复仓库约定的导入：import "./.next/dev/types/routes.d.ts";
-
保留用户已有的无关改动，不得使用破坏性 Git 命令清理工作区。
This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in node_modules/next/dist/docs/ (resolved from this file's directory; in monorepos the next package may not be visible from the repo root) before writing any code. Heed deprecation notices.
This block is written and re-added by next dev — verify at node_modules/next/dist/server/lib/generate-agent-files.js. Removing it from a diff only re-creates the uncommitted change; committing it with your work keeps the tree clean.