协作指南
本仓两人协作：主干维护者（直接提交 main）与协作者（自己的分支写页，由主干侧合入）。 规范尽量不靠自觉——能程序化的都挂在 pre-commit 钩子和 intake 脚本上，本文说明”程序挡什么、人看什么”。 协作模型是单向流：内容从协作者分支流向 main，不回流。协作者不合并主干、 不解冲突；主干侧只取”纯新增”，存量页的修改默认不取。这条是 2026-08-14 定的， 替代了此前”勤合并 + 冲突吃主干”的做法（为什么改见下节）。一次性准备（每个克隆都要做）
铁律（程序拦截，违反无法提交）
行级规则（外链、
$ 转义、正文 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确认坏链不升 → 提交