Imported from yexi-by/att (
AGENTS.md). Install upstream withnpx skills add yexi-by/att. Copyright stays with the author.
AGENTS.md
本文件只保存 ATT 长期有效、项目特有且会改变后续工作的规则:产品与架构不变量、知识归属、 条件性阅读入口和最低验收门禁。当前命令、参数、字段、第三方库、完成状态和详细流程由现行 规格、代码、测试或指南负责。
总纲:从真实用户结果反推纵向切片,由语义所有者承担规则和状态;设计只展开到当前直接 依赖,影响分析横向覆盖全部当前调用方和同语义实现;以最小完整改动保持全局一致;任何 内部或外部内容都必须存在当前消费者。
1. 知识职责与版本边界
每项事实只有一个权威来源,其他材料通过链接或明确引用使用它:
- 本文件保存长期产品方向、架构不变量、项目边界和知识同步规则;
- 现行规格定义已经确认的产品行为与外部接口契约;
- 指南说明调查、取证、验证和发布方法,不重新定义规格;
- 代码和测试保存已经实现的行为与验证证据,不能反向覆盖现行规格;
- 代表性真实材料、权威说明、实际读写关系和验证记录证明领域事实;
- Skill 组织触发、读取顺序、操作、验收和恢复,不复制产品契约或实现细节。
文档必须能够独立阅读和审查。发现知识缺口时,先补充并验证相应权威来源,再让其他入口引用; 缺失的契约不能藏在代码、测试或 Skill 中。
ATT 只实现当前系统版本,业务模型、输入输出协议、持久化格式和配置不建立业务版本分支。旧实现、
协议、格式、配置、测试、Skill 和工作流只保留在版本控制历史中,不在当前工作树建立兼容解析、
迁移、双读双写或历史权威;archive/ 只保存与当前版本无关、用于验证领域事实和失败模式的原始材料。
2. 产品与架构不变量
ATT 用一个 CLI 聚合多个游戏引擎的翻译能力。统一入口只承担真正跨引擎一致的进程级职责和 路由;每个引擎完整拥有自己的命令域、外部契约、编排、状态和错误语义,再在契约之下复用 语义一致的能力。
- 一个纵向切片从用户入口延伸到可观察结果,包含所需业务判断、状态交接和副作用;项目进度 以真实结果衡量,不以目录、模块、crate 或底层组件数量衡量。
- 从当前目标定位真正拥有规则、状态和不变量的语义所有者,在所有者处解决根因,不在调用方 堆叠特殊分支、重复校验或局部绕过。
- 设计只展开到当前目标的直接依赖及其公开契约;共享规则、接口、状态或实现变化时,横向检查 全部当前调用方和同语义实现。
- 直接依赖只在当前模块确有独立需要、调用职责级契约、不绕过其他语义所有者、保持单向且候选 中间层没有额外业务责任时成立;纯改名或转发层不构成边界。
- 语义、规则、不变量、错误语义和生命周期一致时复用同一实现;只有部分职责一致时提炼最小 公共能力;仅代码形状相似时保持独立。
- 新增引擎时重新检查现有能力。相同语义在同一次改动中提炼为唯一共享实现并迁移全部受影响 调用方;引擎特有规则留在对应切片,不复制既有切片或在共享模块累积引擎分支。
- 最小完整改动必须解决根因并同步受影响的实现、调用方、测试、配置、规格和发行内容;不能用 最小 diff 留下已确认的语义分叉、重复知识或下一处同根故障。
- 当前消费者原则同时适用于 CLI、配置、环境变量、外部文件、协议、模型消息、输出、日志、 诊断、任务记录、发行内容以及内部字段、状态、缓存、接口和抽象。可稳定推导或无人消费的 内容不重复输入、保存或输出;测试、示例和文档自身不是产品消费者。
- 用户入口只表达本次意图和必须当场选择的事项;统一配置只收纳部署环境、外部服务或操作者 能够长期选择的策略,固定产品语义、内部资源参数、调度细节和运行时数据由实现负责。
- 除文件、计算、存储、网络和时间等环境根接口外,领域判断、状态转换和编排使用真实实现; Composition Root 只负责配置转换、构造和生命周期,生产入口只连接已经验证的能力。
- 扩展能够用核心契约表达结果时,转换后交给语义所有者统一验收;无法表达时,私有协议自行承担 解析、状态、一致性、事务、恢复和往返验证,未经核心契约验收不得宣称为核心受管状态。
跨引擎规划保持一项长期不变量:Extract、共享 Planner 和引擎适配器分别承担规格定义的语义 责任;语义一致的 Planner 与模型协议使用唯一共享实现和共同契约测试。文本层次、装箱、模型 责任和临时 ID 的先后关系只由 TaskBlock 规划规格定义。
3. 跨切片边界
- 面向人的 CLI、配置、文件名、日志、错误和文档使用源文件名、自然编号、字段名或简短业务名, 不要求或展示 hash、UUID、数据库随机主键或编码 locator。内部身份不得泄露为普通操作凭据; 原始数据库 Lua 仅作为使用者主动选择的低级接口。临时文件、日志、任务记录和恢复目录也使用 目标文件名、命令名或自然编号;并发安全由原子创建、项目租约或目标锁保证。
- 发行根中已经存在的活动
config.toml属于使用者状态。普通资源同步或工具更新不得覆盖、删除、 改名或随父目录替换;缺失时才根据当前模板首次创建。配置无效时保留原文件,诊断指出无效字段、 原因和修改方法;完整行为由配置与发行物规格定义。 - ATT 不自行限制项目总量。活动窗口只限制同时处理的工作,窗口满时等待,不把合法文件、目录、 Lua、SQLite 或业务对象数量转成容量错误。
- 并发、批处理、队列、超时、重试、容量拒绝和磁盘暂存必须由外部硬限制、可复现故障或测量证据 支持;并发只能改变完成时间,不能改变自然顺序、分组、提交、错误语义或持久化一致性。
- 日志、指标、追踪和任务记录默认只提供证据,不参与提交、恢复、重放或副作用准入;只有现行 契约明确规定读取者、权威性、持久化和失败语义时才能成为业务状态。具体行为由项目日志规格定义。
- 生产代码和测试不得读取、解析或断言 Skill、Markdown 文档、文档示例标记、导航、固定文字、 链接或发行副本。自动化测试只验证产品可观察行为与数据契约;Skill 引导在仓库外评估。
- 领域模型、自然顺序、关联范围和边界行为必须由代表性真实材料、权威说明和实际读写关系共同 验证。示例与夹具只解释已经确认的事实;需要定位、继承或写回的原始字段和原值必须可追溯。
4. 条件性必读材料
先做确定当前目标所需的最小只读定位。确认涉及下列主题后,在设计或改动前读完对应权威来源; 同一行列出多个命令时,只读取本次实际涉及的命令规格。
| 主题 | 必读材料 |
|---|---|
| Extract 文本层次、TaskBlock 或临时 ID | TaskBlock 规划 |
| 维护共享 Planner 或新增引擎的规划实现 | 先读TaskBlock 规划,再读规划验证指南 |
| Prompt、user message 或模型响应 | Prompt 与模型协议 |
| 模型任务记录 | 模型任务记录规格 |
| 语言判断或语言验收 | 语言规格 |
| Placeholder | Placeholder 规格 |
| 术语 | 术语规格 |
| CLI 语法、输出或退出码 | CLI 规格 |
| 配置、配置校验或固定配置目录 | 配置规格 |
| HTTP、模型请求协议、超时、重试、代理、限速或敏感信息 | OpenAI-compatible HTTP 规格 |
| 项目日志、诊断、RunId 或呈现失败 | 项目日志规格 |
| SQLite schema、项目状态、事务或数据库诊断 | SQLite 规格 |
| 候选目录、原子发布、恢复现场或发布终态 | 目录发布规格 |
| 性能目标、核心路径、并发或资源机制 | 性能工程要求 |
| 实际测量、性能候选取舍或参数实验 | 先读性能工程要求,再读性能验证指南 |
| 发行内容、发行根、禁止项或完整发行验证 | 发行物规格 |
| 修改、执行或诊断发行资源同步 | 先读发行物规格,再检查发行资源同步脚本 |
| 准备或发布公开 GitHub Release | 先读发行物规格,再读公开发行指南并检查当前 Release workflow |
| RPG Maker Init、Extract、Rules、Translate 或 WriteBack | 对应的 Init、Extract、Rules、Translate或WriteBack规格 |
| Generic JSONL、Init、Extract、Translate 或 WriteBack | 对应的 JSONL、Init、Extract、Translate或WriteBack规格 |
| 原子数据库 Lua | Lua 规格 |
已公开标签和 Release 不移动,也不追溯改写其当时许可。当前版本完成普通验证并形成既定提交后,
用户要求发包或发布即进入发行执行模式:既定提交和版本随即冻结;先确认身份、干净工作树和远端
main 精确指向该提交,在发起发布的 Windows 本机运行唯一一次 release-stress,成功后只创建并
推送版本标签、触发 Release workflow,以及确认公开 Release 和附件。普通 push 不进入发行执行模式。
此阶段不得调用子 agent、重新审查或重跑普通验收、修改业务代码或 workflow、扩大范围、改变版本或
派生补丁。release-stress 失败即结束当前候选的发行执行,不创建版本标签或触发 workflow。用户选择
修复时,流程返回普通开发阶段:修改代码并完成普通门禁;涉及核心性能路径时按
性能验证指南完成真实样本验证。形成新提交并推送到远端
main 后,该提交成为新的发布候选,再重新进入发行执行模式并运行
release-stress。后续动作失败时只报告失败动作、具体事实和可重试位置,等待用户决定。
5. 验证、同步与完成
- 修改 Rust 生产代码时,提交前至少对受影响 crate 或 target 执行格式检查、编译或类型检查、 Clippy 和按行为影响确定的测试;共享 crate、公共契约或跨引擎能力变化必须覆盖全部受影响调用方。
- 常规开发、提交前和 PR 门禁只运行普通行为测试,不启用
release-stressfeature。合成的大容量、 超深结构和墙钟性能回归只存在于release-stress测试组,由发起公开 GitHub Release 的 Windows 本机在推送版本标签、触发 workflow 和远端打包前唯一运行;Actions runner 不运行该组。不得把该组 重新并入普通cargo test或用 ignored 测试代替。 - 本次检查产生的新 warning、当前修改或受影响范围内的 warning 和未分类诊断必须处理;能够证明 与本次范围无关的既有 warning 可以保留,但交付时明确说明。
- 任务要求入口到结果时,用最小真实样本通过生产入口验证完整路径。局部测试、单个 crate 编译 或底层组件完成不能单独证明纵向切片完成。
- 进程级主成功测试和端到端测试使用正式默认;配置变更必须接通生产入口,并覆盖省略后的默认、 合法显式值和无效值。
- 性能改动按性能工程要求和验证指南取证;无性能影响的文档改动不运行性能基准。
- 外部能力、流程、权限、副作用、环境、成功失败或恢复方式变化时,同步相应权威规格、测试、 指南、受影响的 Skill 和发行资源;执行者工作方式未变化时不为制造差异而修改 Skill。
- 普通翻译任务只交付译本、静态 QA 和人工实机检查项。只有任务发起者明确要求维护经验时,才
更新
skills/translate-with-att/references/:同一触发条件合并既有条目,只保存可复用的结构、 动作、证据和验证边界;新证据替换旧结论及边界,只在客观结构不同且需要不同动作时拆分文件, 不保存游戏名、安装路径、具体译文或一次性任务过程。 - 架构图、规格和测试只描述已经实现并验证的事实,候选设计明确标注为候选;各材料在自己的 职责内与唯一权威一致,不复制同一事实。
- 完成意味着约定用户结果或上游承诺成立,失败语义明确,并完成与风险相称的真实入口、状态 交接和副作用验证;未实现、未连接或未验证的范围必须明确说明。
