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

# COLLABORATION

# 协作指南

本仓两人协作：**主干维护者**（直接提交 main）与**协作者**（自己的分支写页，由主干侧合入）。
规范尽量不靠自觉——能程序化的都挂在 pre-commit 钩子和 intake 脚本上，本文说明"程序挡什么、人看什么"。

## 一次性准备（每个克隆都要做）

```bash theme={null}
npm run hooks:install     # 启用 pre-commit：Key 扫描 + 文档规范校验 + 合并回归防护
```

**这是整套流程里唯一需要你配合的动作。没装钩子，下面所有"程序拦截"都不存在。**

## 铁律（程序拦截，违反无法提交）

| # | 规则                                                      | 拦截者                               |
| - | ------------------------------------------------------- | --------------------------------- |
| 1 | `zh-Hant/` `ja/` `ko/` `ru/` `models/` 是构建产物，禁止手改       | `check-docs` generated-lang       |
| 2 | `docs.json` 只改 `zh` / `en` 两个 language 块                | 人工（intake 时核对）                    |
| 3 | 新页面必须中英成对（`faq/x.mdx` + `en/faq/x.mdx`），且都注册进 docs.json | `check-docs` no-pair / not-in-nav |
| 4 | 站点内容不放仓库根目录——写成 mdx 放进 `faq/` `scenarios/` 等目录          | `check-docs` stray-root-md        |
| 5 | 真实 API Key 不入库，测试脚本从环境变量读                               | `check-secrets`                   |
| 6 | 英文页品牌名写 `APIYI`（代码围栏内逐字保留的源码除外）                         | `check-docs` brand                |
| 7 | 合并 main 时不许把 main 的新改动整体丢弃（详见下节）                        | `check-merge-guard`               |

行级规则（外链、`$` 转义、正文 H1 等）只检查**本次新增的行**，历史遗留不会卡你。

## 合并主干的正确姿势（本次事故的根源，重点读）

**背景**：2026-08-12 复盘发现，协作分支把 main 合进来时，冲突文件全选了"自己的版本"，
导致主干此前的修复（品牌名、BOM 剥离、`one-click-integration` / `lobehub` / `workbuddy`
的内容重写）被静默回退。这种回退在后续 diff 里长得和"新改动"一模一样，主干侧几乎无法分辨。

规矩：

1. **勤合并**：动手写新东西前先 `git merge origin/main`，别攒。攒得越久冲突越多，判断成本越高。
2. **冲突时默认吃掉主干的版本**。把 main 合进你的分支时，main 是 `--theirs`：

   ```bash theme={null}
   git checkout --theirs -- <冲突文件>    # 采纳主干版本
   git add <冲突文件>
   ```

   你在这个文件上的新内容，合并后**重新改一遍**再提交——改动在 diff 里清清楚楚，
   远比"保留旧版把主干修复冲掉"好收拾。
3. **merge-guard 会自动拦**：合并提交时若发现"main 改过的文件被整体退回你的旧版"，提交会被拒绝，
   并列出文件清单和修复命令。真的有理由保留自己版本（极少见），用
   `SKIP_MERGE_GUARD=1 git commit` 并在提交说明里写明原因。

## 写新页面之前：先搜主干，防主题撞车

**背景**：协作分支写了 `faq/log-export-timezone-utc.mdx`，而主干四天后已有同主题的
`faq/log-timezone-and-export.mdx`——文件名不同、措辞不同、内容重复，合入时只能弃掉一篇。
这种撞车程序判不了（实测两篇的文本相似度只有 0.05），只能靠动手前先查：

```bash theme={null}
git fetch origin
git grep -il '时区\|导出' origin/main -- 'faq/'      # 按主题关键词搜
git ls-tree origin/main --name-only faq/              # 或直接过一遍文件名
```

intake 时脚本会把每个新增 mdx 的**标题**列出来，主干侧扫一眼也能兜住——但你先搜一步，两边都省事。

## 协作者提交前自查

```bash theme={null}
npm run check -- --files <你改的文件>   # 规范校验（提交时钩子也会跑）
```

* 只产出简体中文（根目录）+ 英文（`en/`）两版，其余语种是主干侧跑管线生成的
* 时间标注时区：`18:30 (UTC+8)`
* 正文 `$` 转义为 `\$`，frontmatter 里直接写 `$`
* 外链只允许第一方域名（`apiyi.com` 全系、`icover.ai`、企微客服 `work.weixin.qq.com`），
  其它域名写成纯文本 + 反引号
* push 自己的分支，**不推 main**

## 主干侧合入流程

```bash theme={null}
npm run intake <分支名> -- --dry   # 先看报告
npm run intake <分支名>            # 执行取回，停在暂存区
```

intake 会自动：剔除构建产物、**跳过与主干同名的"新增"**（防覆盖，列为"撞车"待人工比对）、
列出新增 mdx 的标题（人眼查主题撞车）、给"主干也改过"的 M 文件标回退警告、跑规范校验。

脚本停下后人工接手：

1. `git diff --cached` 过内容口径（定价话术、折扣数字、竞品措辞——脚本挡不了这些）
2. 人工合并 `docs.json`（只动 zh / en 两块）
3. `npm run i18n:plan` 看成本 → `npm run i18n` 出繁日韩俄
4. `npm run links` 确认坏链不升 → 提交

## 事故档案（规则为什么长这样）

| 日期         | 事故                                                           | 对应防线                            |
| ---------- | ------------------------------------------------------------ | ------------------------------- |
| 2026-08-12 | 协作分支合并 main 时保留旧版，回退主干的品牌名/BOM/内容重写                          | `check-merge-guard`（pre-commit） |
| 2026-08-12 | `log-export-timezone-utc` 与主干 `log-timezone-and-export` 主题撞车 | intake 列标题 + 本文"先搜主干"           |
| 2026-08-12 | `coze-gptimage2-plugin.md` / `workbuddy.md` 躺根目录三周无人可见       | `check-docs` stray-root-md      |
| 2026-07-30 | 合并 main 时弄丢文件                                                | intake 回归检查                     |
| 更早         | `git reset --hard` 抹掉 20 个文件未提交改动                            | CLAUDE.md 禁令：工作区有改动时禁用 `--hard` |