# AGENTS.md

## 目标

从空目录实现 Adult Tension：一个可直接安装的通用 Agent Skill，由 AI 负责叙事、由本地确定性运行时负责状态。本目录的 Markdown 文档是唯一需求来源。先做可玩的单世界垂直切片，再扩充玩法与内容。

引擎代码能运行不等于交付完成。交付物是“安装 → 加载 → 开局 → 长线游玩 → 存读档 → 升级后续玩”全程可用的 Skill，并附 `ACCEPTANCE.md` 要求的全部证据。

## 阅读顺序

1. `README.md`：总览与交接须知。
2. `PRODUCT_SPEC.md`：做什么、为谁做、功能分级（P0/P1/P2）。
3. `NARRATIVE_RULES.md`：玩法灵魂——玩家主权、NPC 决策、表里语态、内心可见、亲密场景写作合同、输出格式。
4. `DESIGN_DECISIONS.md`：已拍板的决定与可自行决定的范围。
5. `DATA_CONTRACTS.md`、`RUNTIME_PROTOCOL.md`：数据语义与调用协议。
6. `CONTENT_BIBLE.md`：世界包、开局质量与内容扩充流程。
7. `SKILL_PACKAGING.md`、`SKILL_TEMPLATE.md`：Skill 封装、安装、宿主差异。
8. `ACCEPTANCE.md`：验收门禁。
9. `ARCHITECTURE.md`、`DELIVERY_PLAN.md`、`TRACEABILITY.md`：建议架构、阶段计划和需求追踪。

`REVIEW.md` 是本蓝图的修订说明，不是需求来源，不随本目录复制进新仓库；即使看到也不必读。

## 冲突优先级

`PRODUCT_SPEC.md` > `NARRATIVE_RULES.md` > `DESIGN_DECISIONS.md` > `DATA_CONTRACTS.md` > `RUNTIME_PROTOCOL.md` > `CONTENT_BIBLE.md` > `SKILL_PACKAGING.md` > `ACCEPTANCE.md` > `ARCHITECTURE.md` > `DELIVERY_PLAN.md`。

规范文件只读：不要为了迁就实现去修改它们。发现规范有错或做不到时，记入 `PROGRESS.md` 并请用户决定。

发现冲突时按优先级取舍，并把冲突、选择和理由记入 `PROGRESS.md`。发现文档之间的空白（没写到但必须决定的事）时，按“玩家体验优先、数据语义不丢、实现最简”自行决定并记录。

## 来源边界

- 不得读取、搜索、复制、导入或运行旧项目的代码、测试、素材、存档、Git 历史和维护记录，也不得按旧项目字段、目录或命令做兼容层。
- 如果本目录或工作区里出现旧项目副本（例如含 `maintenance/` 的 `adult-tension/` 目录；你按本规范建立的 `skill/adult-tension/` 不算），视为误放的杂物：不打开、不引用，在 `PROGRESS.md` 记录其位置并提醒用户移走。宿主里已经安装的旧版同名 Skill、旧项目的会话记录同样对待。
- 可以查阅 Python、SQLite、Agent Skill 规范和目标宿主的官方文档核对环境事实；外部资料不能覆盖本目录的产品合同。
- 用户以后明确提供的新材料除外。
- 文档中的 JSON 示例是数据示例，字段名可以优化，语义不能丢。

## 实施原则

- 领域层保持纯净：不导入数据库、CLI、文件系统、宿主或模型 SDK。
- 状态只有一个写入口；所有写操作都带 `request_id`，会话内的写操作还要带 `expected_revision`（创建会话的调用此时还没有 revision，见 `RUNTIME_PROTOCOL.md` §2.1）；重试不能重复推进。
- 运行时只使用 Python 标准库；开发工具可以有独立依赖，但不能进入发布路径。
- 未知字段、未知操作、悬空引用一律报错，不静默忽略；一次返回全部可发现的错误及其 JSON 路径。
- 先用一个世界打通开局、回合、事务、存档和 Skill 外壳，再加世界。
- 程序目录与用户数据目录分离；升级、卸载和首次初始化都必须保留并保护用户存档。
- 只为真实行为写测试。错误事务、确定性、长线运行、边界与安全阻断必须测试；不用海量快照测试复刻实现细节。
- 每个阶段只跑相关测试后继续推进，阶段收尾再跑全套。

## 自主决策

以下完全由实现者决定，只要满足公开合同：包管理与开发工具、内部类名与模块切分、SQLite 表结构、日志、CI、随机算法的具体实现、上下文投影的内部组织、世界包内部文件拆分、测试框架（验收命令入口保持不变即可）。

遇到比文档更简单且不损失语义的设计，可以直接采用，并在 `PROGRESS.md` 写明替代了什么、为什么、如何验证。

不得为了减少工作量而改变：玩家体验、数据语义、P0 功能范围、验收数字、来源边界。

## 验收纪律

- 不得通过删测试、skip、放松断言、吞异常、mock 领域层、固定产物冒充运行或只挑成功 seed 达标。
- 连续三次修复仍卡在同一门禁时，停止局部补丁，记录根因并重做该模块边界。
- 创建并持续更新 `PROGRESS.md`：阶段、执行过的命令、实际数字、遗留问题、下一步。
- 完成时提交 `ACCEPTANCE.md` 中所有命令输出、性能数字、反向验证和端到端证据。