AGENTS.md git:20261002.8f8e1e1A

Immutable. This exact content never changes and is served at /api/v1/blob/a6a64ed7e9d372e6.

# 项目维护与 PR 规范

## 修改范围

- 开始前阅读 `SKILL.md` 和对应引擎页，检查工作区已有改动；保留用户及其他 agent 的修改，不擅自回退或一起提交。
- 改动尽量局限于对应引擎的代码、文档和测试。非必要不改主 `SKILL.md`、`guides/`、索引及无关引擎，不顺手做全库格式化。
- 引擎细节写入 `engines/<引擎>.md` 或其子页；引擎共性写入该引擎的主流程，例如 `engines/kirikiri/workflow.md`。实现变化必须同步更新对应说明。

## 文档原则

- **文档按引擎和格式组织，不按游戏记录案例。** 标题、索引、正文和命令示例不引用具体游戏名、游戏专用路径、台词或逐游戏验证数字；改称“本作”“本样本”后保留流水账也不符合要求。实际运行记录只放游戏结果目录。
- 将样本研究中有用的结论改写为识别条件、格式规则、回填约束与兼容边界；不把单个样本的参数或现象推广为引擎共性。示例使用通用占位路径或人工数据。
- 只保留会影响操作与判断的信息，删去开发过程、重复说明及无实际用途的提交号罗列。必要的代码 profile/API 标识保持与实现一致并注明用途；出处和许可证仍须保留，详细来源放 `provenance/`，不要求使用者查阅外部代码。

## 实现原则

- 按引擎或格式设计通用脚本，通过结构识别、参数或明确的方言配置适配差异，不按游戏名不断新增专用脚本。
- 容器算法放 `python/archives/`，剧情语义放 `python/engines/`；JIS 替换等跨引擎能力放公共模块，避免逐引擎重复实现。
- 假设使用本 Skill 的 agent 看不到任何外部仓库。必要算法、数据与说明应随包提供；文档不得要求查看上游代码。开发时参考或移植代码须保留出处和许可证。
- 未知 opcode、编码、密钥或布局先研究并补齐证据，不猜长度、不填空模板、不吞错，不把部分提取宣传为完整支持。
- 遵守 `SKILL.md` 的安全与输出约定：有界解析、不执行游戏代码、不覆盖原游戏文件，结果写入新目录。

## 验证与交付

- 二进制读写改动须验证真实 parser/writer 的原文往返、变长中文回写、重新解析及非文本结构保留；不能用直接复制原文件冒充往返。补充相关合成正反例与回归测试。
- 提交前运行相关测试和 `python tools/check_skill.py`。分别说明解包、语义提取、回填、重封包及游戏显示的实际验证状态，未运行游戏就明确未验证显示。
- 不提交游戏资源、台词/译文、解包产物、机器绝对路径或真实游戏验证记录。运行报告只放游戏结果目录；引擎页和 workflow 不记录逐游戏验收，`provenance/` 仅保留出处与许可资料。
- 交付遵循主流程：`gt_input` 平铺、姓名在正文上方、只导出非空脚本；用 Markdown 表格说明来源、编码、数量和验证情况，推荐具体开场文件少量试注。
- 默认由 agent 执行回写和打包。告知用户“译文按同名文件放回 `gt_output` 后告诉我，我来回写”，不要只交付命令。误改 `gt_input` 时先保存修改到 `gt_output`，再从可靠原始数据恢复输入；不得改 manifest 绕过校验。

## 提交与 PR

- 逐文件或逐块暂存，只提交本任务改动；提交前检查 diff，避免把并行任务和本地产物带入 PR。
- 一个 PR 聚焦一个问题或一组紧密相关的能力。标题直接说明改进；描述简要交代问题、最终行为、修改范围、验证结果及剩余限制，避免粘贴对话过程或逐游戏测试流水账。
- PR 描述以最终实现为准，范围变化后同步更新；测试未执行或失败须如实注明，不把未完成阶段写成已支持。
- 创建 PR 后提供链接，并在支持附件的环境中关联到当前任务；创建 PR 不代表授权合并、部署或覆盖游戏文件。