AGENTS.md

面向 AI 代理与本仓贡献者的说明。读者对本项目一无所知，动手前请通读。本文件约束如何在本仓干活；格式本身的规定在 spec/（未迁入时以主仓内部规范为权威）。

这个仓库是什么

「麻将面对面」（Mahjong Face to Face，面对面围桌、局域网联机的麻将 app）的牌谱格式开放知识库：majojson 格式规范 + 真实 golden 样例 + 天凤互操作知识 + 最小 reader 验收工具。目标是让任何人不依赖这个 app 就能读懂、校验、处理其牌谱。

纯文档仓：不收产品代码、不收引擎实现。编解码/引擎独立开源库是后续另起的仓库，不要在本仓埋代码（tools/ 下的验收用最小 reader 是唯一例外）。
公开仓（GitHub：WallyYangGT/majo-paifu）：一切入库内容即公开。产品内部信息——内网地址、私有仓名、源码文件与行号引用、版本号叙事、真实用户数据——一律不得出现在任何入库文件。写文时拿不准就不写。

目录与状态

目录	内容	状态
`spec/`	`majojson` 牌谱格式规范（产品中立化改写版）	✅ 已迁入
`interop/`	天凤互操作知识（格式细节、坑与目验方法）	✅ 已成文
`examples/`	真实导出的 golden 样例 + 14 负例	✅ 已落盘（生成器在主仓 `feature/golden-dump` 分支）
`tools/`	最小 reader（从零实现、吃样例过校验）	✅ 已通过验收

状态口径只有一处：根 README.md 的导航表。改动任何目录的落地状态，先更新该表，再更新本表，两处必须一致。

硬性规则

脱敏硬前置：examples/ 收录的每个文件入库前逐个复核——昵称/ID/时间戳等一律用「东家/南家/西家/北家」类合成占位。由真实对局导出物提炼的语料不接受「应该没问题」。
许可分离：文档与样例数据 = CC-BY 4.0（根 LICENSE）；tools/ 代码 = Apache-2.0，随代码文件就地标注，不放根 LICENSE。
产品中立化：spec/ 与 interop/ 的正文面向「生成方/消费方」陈述义务，不引用 app 内部符号（源码路径:行号、发版号、产品功能叙事）。来自内部规范的内容改写时逐条过这个筛子。
权威与同步方向：格式的现行权威是主仓的内部规范（本仓之外）；本仓 spec/ 是其产品中立化改写版。格式演进先改主仓规范，再单向同步到本仓，不在本仓发明/修改格式定义。
互操作结论必须可溯源：interop/ 的每条结论注明来源（天凤官方 JS、logconv、@kobalab/tenhou-url-log、mjai-reviewer/convlog 源码核对），不写凭印象的「大家都知道」。
完成口径（验收）：spec/ 完成 = 照文档从零实现的最小 reader（不依赖原始实现）通过 examples/ 全量校验；interop/ 完成 = 其目验方法（天凤官方页面真打开核对）可被陌生人照做成功。

文档与提交约定

文档语言简体中文；文件名用 ASCII（如 tenhou-interop.md）；代码/字段标识符保留原文。
提交信息遵循 Conventional Commits，中文描述（与主仓习惯一致），类型常用 docs / feat / fix / chore，作用域用目录名，示例：docs(spec): 迁入格式规范中立化改写版。
行尾：.gitattributes 已声明 * text=auto，不要手改。
本仓的构建/门禁只有一个：.github/workflows/ci.yml 跑 tools/minimal-reader 校验 examples/ 全量（正例 + 负例断言）。改规范、样例或 reader 后本地先跑一遍再提交： node --experimental-strip-types tools/minimal-reader/majo_reader.ts examples。