协作指南
本仓两人协作：主干维护者（负责审阅和获授权的主干合入）与协作者（自己的分支写页，由主干侧合入）。 所有任务默认先拉分支（2026-10-27 起）：开始修改前检查git status 和当前分支，从最新
origin/main 建立 codex/<任务主题> 分支；同一任务继续使用原分支。主干维护者也遵守此规则，
不直接在 main 上编辑或提交。多会话并行优先使用各自独立的 worktree。
规范尽量不靠自觉——能程序化的都挂在 pre-commit 钩子和 intake 脚本上，本文说明”程序挡什么、人看什么”。
协作模型是单向流：内容从协作者分支流向 main，不回流。协作者不合并主干、
不解冲突；主干侧只取”纯新增”，存量页的修改默认不取。这条是 2026-08-14 定的，
替代了此前”勤合并 + 冲突吃主干”的做法（为什么改见下节）。
本机任务：分支 → 直接合入 main → push（2026-11-06 起）
仓库拥有者本机的任务不再走 intake。固定流程：- 文档类改动（页面、
docs.json、规则文档、生成器产物）改完即合入 main 并 push； Mintlify 监听 main 自动部署到docs.apiyi.com，不需要 PR、不需要等intake。npm run intake只用于合入其他人的分支。 - 合并前必须
git fetch origin确认 main 未分叉；分叉时在任务分支上git rebase origin/main，不要把origin/main合并进任务分支。 - push 后看一次 Mintlify 部署结果，失败按构建日志修，不在坏构建上继续叠提交。
- 合并后清理已合并分支与不再使用的 worktree。
- 纯文档改动按
AGENTS.md的「纯文档交付约定」：默认不额外跑文档校验/坏链/预览； 生成器、脚本等逻辑改动仍要自测。
私密内容：钩子必须始终生效
- 供应商、客户、运维凭据、内部成本评估等材料只放任意层级的
private/（.gitignore已忽略）。 - pre-commit 必须保持启用；不得用
--no-verify或SKIP_PRIVATE_CHECK=1绕过 私密内容检查。private/只存在于本机、没有 git 备份，误提交进 GitHub 不可撤回。 - 改过
scripts/check-private.mjs后跑npm run private:selftest；日常盘点用npm run private。
一次性准备（每个克隆都要做）
铁律（程序拦截，违反无法提交）
行级规则（外链、
$ 转义、正文 H1 等）只检查本次新增的行，历史遗留不会卡你。
铁律 3 对协作者的实际含义是”中英两份内容都要写”——注册进 docs.json 由主干侧做。
协作者本地跑 npm run check 时会因为没注册而报 not-in-nav，属预期，push 不受影响。
不要合并主干（单向流的核心规则）
背景：2026-08-12 首次发现协作分支合并 main 时冲突全选了”自己的版本”，静默回退了 主干的修复；当时的对策是”勤合并 + 冲突吃主干”。2026-08-14 复查同一分支，回退再次发生 且规模更大——21 个 M 文件里没有一个是协作者的新内容，全部是回退：BOM 加回来、 外链还原成超链接、写死的折扣数字回来了、one-click-integration 整页退回旧版、
lobehub 模型名退回 gpt-4o、docs.json 里主干新注册的两页被删掉。
结论：靠”记得选对冲突方向”防不住，改成从流程上取消这个动作。
协作者：三条规则
- 从 main 切分支后就一直在上面写，不要再
git merge origin/main，也不用关心主干更新了什么。 分支越写越旧没关系——新增页面不依赖主干的最新状态。 - 只写简体中文（根目录）+ 英文（
en/）两版，不碰zh-Hant/ja/ko/ru/models/， 也不碰docs.json。 - 写完 push 自己的分支，告诉主干侧页面路径（例如”新增
faq/xxx.mdx中英两版”）。
merge-guard 仍在，作为兜底
如果还是合并了主干（比如误操作，或工具自动合并），pre-commit 的check-merge-guard
会在发现”main 改过的文件被整体退回旧版”时拒绝提交，并列出文件清单和修复命令。
真有理由保留自己版本（极少见），用 SKIP_MERGE_GUARD=1 git commit 并在提交说明里写明原因。
写新页面之前：先搜主干，防主题撞车
背景：协作分支写了faq/log-export-timezone-utc.mdx，而主干四天后已有同主题的
faq/log-timezone-and-export.mdx——文件名不同、措辞不同、内容重复，两篇对”汇总导出用哪个时区”
的说法还互相矛盾，合入时必须人工判定谁对、再决定合并还是弃掉一篇。
这种撞车程序判不了（实测两篇的文本相似度只有 0.05），只能靠动手前先查：
协作者提交前自查
- 只产出简体中文（根目录）+ 英文（
en/）两版，其余语种是主干侧跑管线生成的 - 时间标注时区：
18:30 (UTC+8) - 正文
$转义为\$，frontmatter 里直接写$ - 外链只允许第一方域名（
apiyi.com全系、icover.ai、企微客服work.weixin.qq.com）， 其它域名写成纯文本 + 反引号 - JSX 属性值里不要再出现 ASCII 双引号，中文用
「」：<Step title="严格按「自然日」分桶">，写成<Step title="严格按"自然日"分桶">会 MDX 解析失败 - push 自己的分支，不推 main、不合并 main
主干侧合入流程
只取 A，M 默认丢弃
单向流下，分支上的 M 文件绝大多数是合并回退产生的伪增量，不是协作者的新内容 （2026-08-14 实测：21 个 M 文件里回退占 100%）。所以：A类逐个过——这才是要取的东西M类默认全部丢弃。协作者真改了存量页，会另行说明是哪页哪处，届时手动对那一处D类忽略——是协作者剥离的构建产物加上主干新页
docs.json 会加出重复导航。
新增的图片记得比对 blob sha——协作者常把主干已有的图换个文件名重新提交
（git ls-tree -r origin/<分支名> -- images/ 对照主干，sha 相同即重复，不要取）。
脚本停下后人工接手：
git diff --cached过内容口径（定价话术、折扣数字、竞品措辞——脚本挡不了这些）- 人工把新页注册进
docs.json（只动 zh / en 两块）——协作者不改这个文件 npm run check -- --files <新页>过规范npm run i18n:plan看成本 →npm run i18n出繁日韩俄npm run links确认坏链不升 → 提交