# 接入、跨步骤决策与恢复

首次进入或恢复会话时读取本文件，再按 [Skill 的步骤索引](../SKILL.md#按需读取)读取当前一步。七个步骤各自维护操作细节，本文件只负责共同的接入与交接。

## PREFLIGHT — 接入与基线

1. 盘点用户想法、参考图、已有 Lua、GIA、存档和反馈，检查工作区 `AGENTS.md`。
2. 按下方[知识库发现与可用性核验](#知识库发现与可用性核验)，先检查工作区和当前 AI 宿主已配置的资料来源，再判断缺项；不要一开始就要求安装插件或提供文档。
3. 检查会话实际提供的模拟器、浏览器和美术能力；目录存在或安装成功不等于工具可见。MCP、Web 和 Harness 的接入形式不同，使用当前宿主说明与 schema。
4. 已有工程先读策划案、production-plan、测试、最近试玩记录、存档与源码；找出本轮目标和最早缺失的证据，确定一个当前步骤。
5. 在 `docs/production-plan.md` 记当前步骤、目标、退出证据、阻塞项。只创建当前任务需要的文件，不为空阶段建占位产物。

PREFLIGHT 不计入七步。新游戏按策划案 → TDD 用例 → HTML → 美术 → Lua → 测试 → 真机推进；已有工程和窄修复按证据选择步骤。

## 知识库发现与可用性核验

启动制作前完成一次有范围的检查；恢复会话时复用已记录来源，工具、资料版本或任务涉及的 API 变化时再定向复核。

1. **先查工作区入口。** 从 `AGENTS.md`、README、项目索引及其引用位置寻找官方 Lua API、客户端脚本使用指南、控件/模板与脚本挂载说明、已知问题和真机记录。检查项目内的 Skill、MCP 或插件配置；本地知识库可能位于被 Git 忽略的目录，按已发现的目录定向检索，不扫描整块磁盘。
2. **再查当前 AI 宿主的配置与能力目录。** 优先使用宿主提供的插件、MCP、Skill 列表；必要时只读其已知项目级/用户级配置中相关的名称、启用状态、资源入口和本地路径。寻找 `miliastra-toolbox` 系列（如 `dsh-plugin-miliastra-toolbox`）、其他知识库服务及本地文件知识库。名称可能是别名，不能只凭插件名认定资料覆盖范围；不改配置、不回显令牌或无关配置内容。
3. **核验实际内容。** 对候选来源检查当前会话是否能调用/读取，再定向取一段官方 Lua API 和相关使用指南，确认属于千星客户端 2D UI + Lua，并能读取函数签名、参数/枚举和操作说明。不要为检查可用性加载整套文档。仅提供 3D 节点图资料、只有检索摘要或接口表缺失的来源，不算已取得所需 Lua 官方资料。
4. **记录来源和缺项。** 在 `docs/production-plan.md` 记录来源名称、工具/路径、文档标题与可得的版本/日期、适用范围、当前读取结果。区分“已配置”“本会话可调用/读取”“已取得所需官方资料”；配置不可读或工具未加载时记“尚未核实/当前不可用”，不推断用户没有配置。官方文档、实战经验、真机观察和模拟器策略分别标注；不同版本冲突先核对来源，不拼凑签名。
5. **优先复用，再补缺项。** 已有资料够用就继续，不重复要求安装；连接不可用但本地资料够用时使用本地资料并记录来源。只有缺少本轮所需内容时，才简短说明缺哪份资料或哪个能力，请用户启用已有连接、提供可读路径或补充相应文档。可继续步骤 1–4，依赖缺失 API 的 Lua 实现须等资料补齐。

向用户简述找到的可用来源与实际缺项即可，无需报告全部配置清单。模拟器工具可用与知识库可用分别检查，不能互相替代。

## 产物位置与恢复

`workspace/<slug>/` 是项目产物位置，下列路径相对该目录：

| 产物 | 用途 |
|---|---|
| `docs/gdd.md`、按需 `docs/game-spec.md` | 玩法语义、范围与契约 |
| `docs/production-plan.md` | 当前步骤、知识来源与可用性、证据位置、未完成项和下一步 |
| `tests/` | 规则用例；测试 JSON 不是存档 |
| `prototype/` | HTML 展示与操作说明 |
| `docs/art-bible.md` | 参考图、目标素材和 UI 还原方案 |
| `main.lua`、`<slug>.save.json` | 源码与完整工程，存档头部附近有 `"format": "qxqy-simulator-save"` |
| `docs/tech-architecture.md` | 文件/控件职责、变量/信号、数据流和脚本挂载 |
| `docs/device-handoff.md` | 真机导入、真实索引、脚本路径/挂载、同步方式与待办；可合并进已有交付说明 |
| `records/playtest.md`、`export/` | 试玩/修复证据与交付资产 |

试玩记录按 `runtime=html|simulator|device` 标来源、执行者、步骤、期望/实际、未知项和修复后回归。恢复时先读实际产物与证据，避免仅凭聊天摘要重做项目；用户已提供的信息直接复用。

## 回退与完成

- 设计问题：回步骤 1–3，更新契约和用例。
- 素材问题：回步骤 4，记录目标 ID 与还原方案。
- 规则或代码缺陷：补步骤 2 的最小用例，再到步骤 5–6 修复和回归。
- 真机差异：在步骤 7 留存证据，回到受影响步骤修复，再验证真机结果。

只加载受影响步骤，不把回退理解为整套重跑。真机未验证时交付状态为“模拟器候选”；只有目标行为有真机证据时才标记该行为通过。