pelican-engine 0.0.0-stage → 0.3.1

package/docs/AI-WORKFLOW.md

@@ -0,0 +1,517 @@
+# pelican：100% 外部 AI 开发工作流规划
+
+> 本文描述完整目标工作流。M0 已实现的子集、实际命令和限制见 [M0-USAGE.md](M0-USAGE.md)；未实现的规划命令不能当作现有功能。
+
+> 状态：设计规划，尚未实现。本文中的目录约定、CLI、协议、Schema、任务状态、测试设施和自动化行为均为拟定契约，不代表仓库当前已具备这些功能。本文不提供可直接执行的现成功能承诺，也不实现引擎代码。
+>
+> 本文定义外部 AI 如何研发引擎，以及如何使用引擎开发游戏。已确认产品要求以 [DECISIONS.md](DECISIONS.md) 为准，总体技术设计见 [ARCHITECTURE.md](ARCHITECTURE.md)，里程碑与依赖顺序以 [ROADMAP.md](ROADMAP.md) 为准。本文集中维护拟定 CLI、工作流协议、任务协作与验收操作面，不重复定义底层总体架构。
+
+## 1. 目标与设计哲学
+
+### 当前执行策略（D50、D51）
+
+D50 禁止测试、浏览器、GPU、性能、smoke、额外校验及其他验证，仅允许编译/构建及必要步骤，CI 同样遵守。D51 要求在 `main` 的单一工作树串行开发，不创建并行工作树或开发分支。下文原有 D49 和并行协作方案是历史设计，不是当前执行指令；历史结果不代表当前源码通过。
+
+### 历史验证策略（D49，已由 D50 覆盖）
+
+开发迭代优先选择能最快发现当前变更缺陷的验证，不把测试数量或重复证据当进度。纯文档/元数据改动做相应一致性检查；局部实现做类型检查及受影响单元/契约；跨模块或 GPU 行为增加一条小规模真实端到端和关键失败/生命周期路径。只有相关渲染算法、资源契约或画质发生变化才重跑对应矩阵，性能主要在优化前后及冻结节点采样。npm 安装/打包验证放在分发链路变化或版本冻结时，不随无关运行时改动重复执行。真实 GPU 测试串行；CPU 独立工作可以并行。源码未稳定前不反复冻结，不重跑未变模块来制造通过数。稳定候选和里程碑发布前仍要完成全部必需门禁；缓存或历史结果必须能证明覆盖对应未变输入，不能将未跑、跳过或弱证据记为完整通过。
+
+多 worktree 默认由子任务执行局部测试，主线合入后集中做一次全仓类型检查；只有需要类型反馈时，子任务才单独执行同一检查。子任务已验证且文件/依赖未变的结果可以复用，主线优先补接口整合与交叉行为，不机械重复所有子任务测试。重型浏览器探针可用 `npm run probe:m3 -- --list` / `--checks <IDs>` 选择，自动加入必要依赖并记录 omitted；默认完整模式只用于稳定候选。
+
+仓库的 `npm test` 串行运行测试文件，因为浏览器测试可能共享 Vite 依赖缓存和本机端口；不要在同一工作区同时运行多个完整套件。局部研发可用 `npx tsx --test <受影响测试文件>` 加速，但涉及浏览器或 GPU 的用例仍需避免资源争用。默认跳过的硬件专项需在相应验收时单独执行，普通测试通过不代表硬件验收。
+
+pelican 是面向 100% AI 开发的高质量游戏引擎。引擎研发与未来游戏开发均由游戏进程之外的 AI 编码工具执行，人只提出需求、约束和反馈，不承担编码、环境安装、资产编辑、调试、测试操作、任务拆分或集成工作。
+
+AI 友好意味着能力完整、接口一致、规则可发现、结果可观察、错误可定位、失败可恢复。它不意味着只支持原型、缩减游戏表达能力，或以降低画质替代实现目标。引擎研发 AI 必须将人的需求转化为明确任务并完成验证，不能反复把技术选择和执行工作推回给人。
+
+工作流必须满足以下原则：
+
+- 不依赖特定模型、AI 客户端、插件、MCP 或专有在线开发平台。具备文件操作与终端执行能力的外部 AI 可以完成标准流程；视觉判断由具备视觉能力的外部工具承担。
+- 不在引擎或游戏运行时嵌入大模型、AI 智能体、模型密钥或推理服务依赖。本文不规划自研 AI 编排平台。
+- 所有必要操作都有程序化入口，无编辑器点击、人工拖拽、人工安装和人工截图等必经步骤。
+- 代码、定义、文档、测试、任务状态和证据保存在可交接的文件中，不以对话记忆作为唯一依据。
+- 完成依据是可复现的交付证据，不是命令退出成功、静态检查通过或 AI 的文字自述。
+- 高质量资产可以来自现有授权素材、外部服务或程序化生成；引擎不限定创作工具，不承诺将低质量输入自动变成高质量成品。
+
+## 2. Owner、职责与使用规范
+
+### 2.1 引擎所有者与引擎研发 AI
+
+引擎所有者提出 pelican 的产品需求、优先级、约束与反馈。引擎研发 AI 在引擎侧任务中负责设计、实现、测试、文档、示例、迁移、版本管理和主线集成。
+
+引擎研发 AI 可以按任务范围修改引擎源码；公开 API 变更必须同步更新契约、示例、迁移规则及验证。是否接受能力扩展和何时纳入版本，由引擎侧需求与研发计划决定。
+
+### 2.2 游戏所有者与游戏开发 AI
+
+游戏所有者可能是引擎所有者，也可能是完全独立的其他使用者。游戏开发 AI 根据其用户需求，通过 pelican 公开 API 开发游戏，而不是参与引擎内部研发。
+
+游戏侧标准规范为：
+
+- 可以定义组件、玩法系统、场景、预制体、材质、后处理、GPU 计算等公开扩展点。
+- 不修改引擎源码，不导入内部模块，不绕过封装调用 Three.js、原生 WebGPU 或内部依赖。
+- 不把游戏工程遇到的能力缺口自行转成引擎修改任务，不以临时修改依赖冒充正常游戏实现。
+- 如有缺口，记录需求、最小复现、现有接口不足之处与影响；已有公开能力能够提供的替代方式必须明确说明差异，不能静默降级。
+- 使用者可修改的游戏模板与应保持稳定的引擎实现必须标注明确。
+
+这些是生态与工程规范，不是安全边界、防篡改机制、技术封锁或许可限制。正常的导入与依赖检查用于发现误用和给出修复建议，不用于鉴别恶意使用者或封禁构建产物。
+
+### 2.3 开源与许可记录
+
+引擎自有代码采用 MIT。不得将“推荐通过公开 API 开发游戏”转化为额外的开源许可限制。引擎开源与游戏侧按公开 API 开发同时成立。
+
+第三方组件和资产保留各自的来源、版本、许可证及所需声明；用户游戏代码与用户资产的许可单独管理。不得未经检查就把第三方素材归为 MIT，或把所有游戏强制要求为开源。
+
+## 3. 三种执行主体必须分清
+
+| 主体                | 执行位置                         | 负责内容                                             | 不负责内容                                 |
+| ------------------- | -------------------------------- | ---------------------------------------------------- | ------------------------------------------ |
+| 外部研发或开发 AI   | Windows 开发环境                 | 读需求、写代码、调用工具、分析证据、修复问题         | 不进入玩家游戏进程执行推理                 |
+| 测试自动化驱动      | 开发测试环境，可与测试版游戏连接 | 驱动输入、控制测试时间、查询状态、捕获画面、生成报告 | 不承担正式游戏角色决策，不成为生产运行依赖 |
+| 游戏逻辑与 NPC 行为 | 玩家游戏运行时                   | 规则、动画、寻路、巡逻、追击、战斗决策等普通代码     | 不包含大模型智能体，不请求开发 AI 指挥游戏 |
+
+“外部 AI 分析截图”指截图落盘后由开发流程中的视觉 AI 判断。“测试驱动发出移动输入”指自动化操作测试版游戏。这两者都不意味着游戏运行时具有 AI 智能体。
+
+## 4. 环境与交付边界
+
+### 4.1 开发环境
+
+引擎研发和游戏开发首发仅支持 Windows。路径、进程管理、依赖准备和浏览器自动化必须在 Windows 实测，包括空格、中文目录、ZIP 解压目录和非管理员账户场景。
+
+首次准备允许自动联网获取锁定的工具与依赖。工具链应优先复用已有可兼容环境或安装到项目内、用户级目录，不把全局安装、管理员权限、人工修改环境变量或打开软件配置作为标准前置条件。
+
+若机器政策、网络或驱动条件确实无法满足，必须停止受影响步骤并报告确切原因与诊断，不能虚报准备成功，也不能把“请人工安装后继续”作为正常开箱流程。GPU 或驱动不可用时，仍应清楚区分能完成的非图形检查与被阻塞的图形验收。
+
+### 4.2 玩家运行环境
+
+不设置玩家操作系统、浏览器品牌或版本白名单。优先 WebGPU，不可用时由 Three.js WebGPURenderer 内置机制回退到 WebGL2。通过 `render.capabilities()` 查询后端与可用模式；compute/光追/降噪不可用时给稳定错误码与修复建议，不静默降画质、不伪装模式、不基于品牌直接拦截。WebGL2 证据与主里程碑真实 WebGPU 证据分开。
+
+固定机器、浏览器和驱动信息只是复现实验与性能比较的测试基准，不是玩家使用门槛。诊断应尽量说明具体能力，不把“未认证环境”冒充技术错误。
+
+### 4.3 成本与离线要求
+
+默认不依赖付费工具、服务或引擎在线平台，不静默创建付费资源。额外费用超出已授权范围时，由外部 AI 提供用途、费用与替代方案，交由需求方决定。
+
+准备完成且所需工具、依赖、资产及测试运行组件均已缓存后，开发、检查、测试和构建应可离线执行。离线缺失内容应列明缓存项，不隐式联网，也不以在线授权或遥测作为必需条件。
+
+资产生成服务由开发者及其外部 AI 自主选择和调用，引擎不提供必需的生成服务编排、模型选择、供应商队列或生成计费系统。导入后资产处理属于引擎工具链职责。
+
+## 5. 从 Git、ZIP 或已有目录发现引擎
+
+### 5.1 统一发现原则
+
+仓库及其完整目录本身就是交付物。获取方式包括 Git、下载 ZIP、已有解压目录、复制目录及外部引擎路径，任何标准工作流都不得以 `.git` 存在为前提。
+
+拟定的目录级发现信息应包含：引擎标识、引擎版本、工作流协议版本、公开 API 入口、环境准备入口、模板入口和文档入口。这些信息必须随源码目录存在，不依赖仓库地址、Git 标签或原始下载位置。
+
+外部 AI 应只读取完成当前任务所需的入口信息，再按模块索引查阅，避免必须先理解整个引擎源码。后续入口指引需要明确游戏模式与引擎研发模式；本文不创建其他入口文件。
+
+### 5.2 首次获取与识别流程
+
+1. 将用户提供的信息识别为仓库地址、ZIP 文件或目录；确认目标内容与现有文件状态。
+2. 需要下载或解压时，由外部 AI 自动执行，保留原始输入，不覆盖已有游戏或不相关文件。
+3. 处理 ZIP 顶层包装目录，通过引擎标识定位真实根目录，不依赖固定文件夹名。
+4. 读取版本、公开入口、环境需求与工作流契约，建立本次使用记录。
+5. 自动执行环境诊断与准备，再验证最小样例；任一步失败均记录状态与证据。
+6. 选择游戏工作区位置，生成项目记录并验证公开 API 引用。
+
+Git 可以提供历史和可选协作能力，但初始化、版本识别、缓存定位、恢复点和迁移均需要不依赖 Git 的路径。Git 操作不能成为 ZIP 使用者的必经步骤。
+
+## 6. 游戏目录与外部引擎路径
+
+两种模式同等支持：引擎目录内的默认游戏工作区，以及引擎目录之外的独立游戏工程。目录内模式只是最快起点，不是强制结构。
+
+| 信息       | 记录方式与要求                                                           |
+| ---------- | ------------------------------------------------------------------------ |
+| 游戏根目录 | 每次任务明确解析，命令显式使用该上下文，不依赖终端碰巧所在位置           |
+| 引擎定位   | 项目记录本地引用及解析基准；相对路径按项目根解析，外部绝对路径可明确配置 |
+| 引擎版本   | 来源目录内的版本标识、内容标识和公开契约版本，不依赖 `.git`              |
+| 依赖与缓存 | 标明所属项目及可写位置，不要求写入受保护的全局目录                       |
+| 构建与证据 | 输出到游戏所属目录或明确配置的位置，不混入引擎源码                       |
+
+游戏开发 AI 不通过复制内部代码来解决引用问题。若引擎需要预构建，环境准备工具只能写入规定的生成或缓存目录，不更改引擎源码、公开契约或依赖版本。
+
+外部目录开发的完整路径应为：发现引擎 → 准备环境 → 在指定目录创建游戏 → 建立本地公开引用 → 检查 → 开发运行 → 自动测试 → 构建 `dist/`。所有步骤在无 Git 条件下也成立。
+
+目录被搬移后，可以重新指定或解析引擎路径并验证版本，不要求用户重新创建游戏。发布产物不得残留开发机器上的引擎绝对路径。
+
+## 7. 环境准备与缓存规划
+
+环境准备工具拟按以下顺序执行：
+
+1. 识别 Windows 环境、可写目录、已有工具、网络及 WebGPU 测试条件。
+2. 读取锁定依赖、工具版本和来源信息，拒绝以“自动取最新版本”代替可重复准备。
+3. 复用校验通过的缓存；只下载缺失或损坏项，并验证可用的完整性信息。
+4. 在项目内或用户级目录完成安装与配置，避免永久修改系统配置。
+5. 准备自动化浏览器等测试依赖，确认实际运行环境，而不是仅检查文件存在。
+6. 验证公开 API 最小示例、基础资产和工具协议，输出准备报告。
+7. 再次执行时应复用结果，不覆盖游戏文件、不重复创建工程、不悄悄升级依赖。
+
+缓存按工具、版本、目标与内容标识隔离。清理只能处理明确归属的缓存项；不可用宽泛的目录删除替代恢复。网络失败、校验失败和不兼容环境应分别诊断，不能无限重试。
+
+## 8. 拟定 CLI 操作面
+
+以下命令名称仅为设计建议，尚未实现。正式语法、选项、可执行入口与安装方式以后续实现为准；本文不宣称当前运行这些命令会成功。拟定 CLI 名称与行为集中以本节为准，其他规划文档引用本节，不另行固化不同命令清单。
+
+初始计划阶段不创建 `package.json` 命令、启动脚本或伪 CLI 来对应本文清单。后续只有在任务正式实现并验证后，才增加实际入口，并同步标明实现状态。
+
+所有入口应支持明确的项目上下文、必要的引擎路径、结构化输出和帮助信息。不要求游戏使用者另行安装特定 AI 插件。
+
+| 拟定命令    | 职责                                             | 必要输出与验证                                       |
+| ----------- | ------------------------------------------------ | ---------------------------------------------------- |
+| `doctor`    | 只读诊断环境、路径、版本、缓存和图形能力         | 可用项、缺失项、原因、建议动作；不自动改环境         |
+| `setup`     | 自动准备锁定工具、依赖及必要测试组件             | 变更清单、缓存来源、版本与准备验证结果               |
+| `create`    | 从模板创建游戏，支持目录内和外部目录             | 引擎引用、生成文件清单、起始验证结果；不覆盖已有内容 |
+| `dev`       | 启动开发服务、增量构建和受控测试会话             | 项目与会话标识、服务地址、就绪状态、诊断路径         |
+| `check`     | 检查类型、定义、资产引用、公开接口使用和内容契约 | 稳定诊断码与源位置，不冒充实际运行验收               |
+| `test`      | 执行单元、集成、玩法、回放及跨系统测试           | 用例状态、断言、失败证据、跳过原因与环境             |
+| `capture`   | 按场景、视角、时间及输入序列生成画面证据         | 截图或录制、捕获条件、帧与场景标识、缺失说明         |
+| `inspect`   | 查询开发测试会话的状态，并执行明确的测试控制动作 | 结构化状态、请求结果、事件记录与相关实体标识         |
+| `benchmark` | 执行固定负载的性能与资源测试                     | 帧时间分布、卡顿、加载、内存、实际模式与环境         |
+| `build`     | 内容编译、依赖分析、优化与发布构建               | `dist/`、资源清单、构建标识及依赖解释报告            |
+| `migrate`   | 分析并执行显式版本迁移                           | 影响清单、恢复点、变更记录、待办与复测结果           |
+
+长任务的启动、查询、取消及证据导出必须有一致语义；它们可以作为上述命令的子操作，不必为了工作流而增加独立平台。命令退出成功不得掩盖后台仍在失败、必要测试未执行或服务尚未就绪。
+
+## 9. 结构化协议与诊断契约
+
+### 9.1 统一 JSON envelope
+
+机器模式采用版本化 JSON envelope。短操作输出完整结果，长操作可按行输出同结构事件并提供最终结果文件；普通进度文本不得混入机器输出流。面向人的日志与机器结果分流，编码统一为 UTF-8。
+
+| 字段              | 拟定语义                                                                          |
+| ----------------- | --------------------------------------------------------------------------------- |
+| `protocolVersion` | 工作流协议版本，与引擎版本分别管理；不兼容时给出明确诊断                          |
+| `taskId`          | 本次任务的稳定标识；跨查询、日志、取消与产物一致                                  |
+| `status`          | `queued`、`running`、`succeeded`、`failed`、`cancelled`、`timed_out` 或 `blocked` |
+| `errors`          | 始终存在的结构化错误数组；无错误时为空，不用一段日志替代                          |
+| `artifacts`       | 始终存在的产物数组；说明产物标识、类型、路径、完整性与归属                        |
+| `result`          | 命令对应的数据结果；可包含检查覆盖、跳过、警告和失败分类                          |
+
+可扩展字段包括请求标识、父任务标识、事件序号、时间戳、进度和耗时。任务标识不是身份认证凭证。路径需要注明相对基准；项目可搬移后，证据引用仍可解析。
+
+以下仅演示拟定协议，不表示文件或命令已经存在，也不是当前工具输出：
+
+```json
+{
+  "protocolVersion": "0.1-draft",
+  "taskId": "example-capture-001",
+  "status": "failed",
+  "errors": [
+    {
+      "code": "TCWF_CAPTURE_NOT_PRODUCED",
+      "message": "目标帧未生成，不能完成视觉验收。",
+      "retryable": false,
+      "sourceLocation": null,
+      "relatedIds": [],
+      "suggestedAction": "检查运行会话诊断，修复后重新捕获。"
+    }
+  ],
+  "artifacts": [],
+  "result": {
+    "requiredChecks": [{ "id": "visual-review", "status": "blocked" }]
+  }
+}
+```
+
+最终成功需要实际操作完成且产物验证通过。测试命令还必须报告通过、失败、跳过和阻塞数量。必需检查被跳过或阻塞时，上层验收不能成功。命令本身成功与整个研发任务完成是不同层级，例如截图生成成功不代表视觉审查通过。
+
+非零退出或异常中断须尽可能保留最终 envelope；若子进程崩溃无法输出，由调用层记录退出状态、最近事件和恢复线索。不得只依赖一个固定退出码表达所有失败。
+
+### 9.2 可定位、可关联的诊断
+
+诊断按环境、编译、资产、运行、视觉、性能、迁移和协议等类别区分，具有稳定错误码、严重程度、原因、建议动作及相关证据。
+
+能关联源码时，提供路径、行列范围与源映射；没有源码位置时明确为空，不编造位置。编译后的内容错误应尽可能映射回 TypeScript 定义或原始资产。
+
+系统、实体、资源、场景、测试和断言使用可关联的稳定 ID。ID 不应仅由当前行号、显示名称或遍历顺序构成；运行实体还须区分会话和实体代际。源位置允许随修改变化，逻辑 ID 应尽量保持可追踪。
+
+错误应能串联“源定义 → 编译内容 → 运行实体或资源 → 系统阶段 → 测试 → 证据”。大批重复错误可以聚合，但需保留原始记录，不能吞掉首个根因。
+
+## 10. 任务生命周期、有限重试与恢复
+
+任务契约应在开始前确定总预算或截止条件、单步超时、心跳条件、重试上限和取消方式。预算是执行边界，不是对整套引擎研发工期的虚构承诺。
+
+- 网络抖动、临时进程启动失败等可恢复故障可以有限重试；拟定默认同一步最多额外重试两次，具体可由任务缩小或调整。
+- 类型错误、缺失功能、错误凭据和不兼容协议不通过重复同一命令解决，须先分析根因。
+- 每次重试记录原因、输入、变化和结果；连续相同失败且没有新证据时停止无效循环。
+- 外部 AI 修复后启动新的验证尝试，关联原始失败，不能删除失败记录后伪装首次成功。
+- 长任务必须可查询进度并响应取消，不能靠无限等待表现为仍在工作。
+- 超时与取消保留独立状态；部分产物标为不完整，不晋升为发布结果。
+- 清理只针对本任务拥有的进程和临时内容，不终止其他项目，不删除未知目录。
+- 中断恢复先检查已完成阶段、版本与输入标识；只复用有效结果，不盲目重跑或信任半成品。
+
+失败记录包含发生阶段、输入标识、环境摘要、最后成功步骤、错误链、产物位置和恢复入口。无法自动消除的外部阻塞必须明确报告；“等待人排查代码或点击工具”不是计划中的恢复路径。
+
+## 11. 开发态运行控制与生产边界
+
+开发测试会话拟提供输入注入、暂停、单步、时间推进、随机种子设置、状态查询、快照、回放、事件订阅和画面捕获。控制动作必须经明确接口执行，记录执行时间、目标与结果。
+
+测试控制应尽量使用真实输入与公开能力。直接设置状态可用于测试准备，但不能替代待验收的交互步骤；报告必须区分“测试准备”“模拟玩家操作”和“直接状态修改”。
+
+这些能力属于开发工具与测试设施。默认只连接本机、当前项目和明确启动的测试会话，不默认监听外部网络，不把开发控制地址或凭据写入游戏资产。
+
+生产 `dist/` 默认不包含或启用开发控制端点、测试驱动、调试状态导出、开发密钥和外部 AI 接口。生产游戏逻辑不需要开发控制服务才能运行。若为某项正式游戏功能保留诊断，应单独定义公开行为，不能顺带暴露开发控制能力。
+
+## 12. 单一事实源与可发现资料
+
+公开 API 类型、定义 Schema、CLI 参数契约、协议 Schema 和错误码目录应各有唯一权威来源，再由它们生成对应参考资料、机器索引和可校验示例。不同时手写多份含义相同但可能漂移的定义。
+
+拟定要求包括：
+
+- 文档入口按“首次使用、创建游戏、常见任务、扩展接口、诊断修复、发布迁移”组织，并可查到所属版本。
+- API 文档标明生命周期、单位、坐标约定、默认值、所有权、资源释放、限制及失败行为。
+- 示例只使用公开 API，参与对应版本的编译与运行测试；示例里的错误恢复路径也需验证。
+- 生成资料与手写教程职责分离，持续检查失效链接、未知符号、Schema 不匹配和过时命令。
+- 错误码、任务协议、资源标识及迁移契约可以按需检索，不要求 AI 每次通读全部文档。
+- 修改权威来源后同步更新生成结果；生成资料不得反向变成另一个事实源。
+
+本文中的协议示例只是规划占位，正式实现时应纳入 Schema 校验；不能把本文与未来 Schema 维护成两套不一致的协议。
+
+## 13. 游戏开发的完整闭环
+
+### 13.1 从需求到可运行版本
+
+1. **接收需求：** 外部游戏开发 AI 整理玩法、表现、输入、内容、质量目标及明确不做事项；能合理判断的技术细节自行处理。
+2. **发现引擎：** 按 Git、ZIP 或目录路径读取入口，确认引擎版本、公开能力及开发规范。
+3. **准备环境：** 完成诊断、锁定依赖准备、缓存和最小运行验证。
+4. **建立项目：** 选择目录内或外部工作区，记录引擎引用，保留已有文件，建立任务与验收记录。
+5. **能力映射：** 将需求映射到公开模块、示例与扩展点，先确认关键需求可以表达；能力缺口提前显式报告。
+6. **构建垂直切片：** 先形成可玩的输入、角色、场景、交互、UI 与反馈闭环，随后逐步增加系统和正式内容。
+7. **获取与导入资产：** 由外部开发流程自由选择来源；导入工具处理校验、转换、依赖、优化与资源登记。
+8. **增量迭代：** 修改代码或定义，执行增量检查，在兼容时热更新，读取结构化诊断并修复。
+9. **自动试玩：** 通过测试驱动执行玩家操作，验证玩法状态、失败恢复、存档及跨系统交互。
+10. **视觉与性能检查：** 捕获画面给外部视觉工具判断，同时执行固定负载测试，保留全部失败。
+11. **冷启动复验：** 停止旧会话，从干净启动验证，避免只在热更新状态下正确。
+12. **构建与交付：** 生成 `dist/`，通过静态服务器预览发布产物，完成产物级回归和交付说明。
+
+流程可按功能循环，但不能先堆积全部代码，再把集成、视觉和性能问题集中留到最后。每次交付说明应对应实际证据与未完成项。
+
+### 13.2 增量与热更新约定
+
+增量结果需要记录输入与依赖；变化影响范围不明时应重新校验，而不是误用缓存。运行会话应报告哪些代码、定义、资产和管线被更新。
+
+热更新必须说明状态保留策略：应用新默认值、保留现有状态、迁移状态或重新启动。不兼容时自动选择明确的安全重载路径并报告原因，不构造无法解释的混合状态。
+
+热更新和缓存用于加速开发，不能作为省略冷启动与干净构建的理由。正式验收结果应记录是否使用缓存、是否从冷启动执行及所用输入标识。
+
+## 14. 资产、外部服务与密钥
+
+仓库应提供可用于完整玩法验证的基础资产和程序化内容能力，使不配置外部生成服务也能完成游戏。正式高质量美术仍需要合适的高质量输入，可由购买或取得授权的素材、开发者自主调用的服务，或代码生成获得。
+
+引擎工具链接收结果后，拟检查格式、依赖、尺度、坐标、动画、材质、纹理、碰撞、资源体积及相应优化条件。优化需要保留源资产或可恢复路径，并报告处理前后差异；不能为满足体积或性能目标静默破坏必要细节。
+
+每项外部资产记录来源、作者或提供方、许可证或授权凭据引用、版本、内容标识、处理步骤与派生关系。生成资产可以记录可获得的生成来源和参数，但不得将敏感请求内容或服务密钥写入元数据。
+
+来源或授权信息不明时，应保留“待核实”状态并在交付中显式说明，不编造授权结论。原始授权材料可保存在适当的私有位置，仓库只保留必要引用和可公开声明。
+
+外部服务密钥由外部开发工具通过适当的环境或凭据设施使用，不写入源码、提交记录、提示词记录、普通日志、截图元数据或 `dist/`。错误记录对凭据做脱敏；生产游戏不能继承开发资产服务的凭据。
+
+## 15. 视觉检查与可复现验证
+
+### 15.1 捕获与外部视觉判断
+
+视觉证据必须记录构建或内容标识、场景、相机、视口、渲染模式、质量配置、随机种子、模拟时间、输入回放及运行环境。对动画、流送、透明、拖影等时序问题，需要连续帧或录制，不能只截一张静态图。
+
+截图交给游戏进程外部的视觉 AI 分析。分析结果包含检查目标、具体异常、对应画面位置、证据引用与结论；适当记录外部审查工具的版本以便追踪。截图相似度只能辅助，不能独立证明画面质量或玩法正确。
+
+以下情况必须可见地失败或阻塞：
+
+- 截图没有生成、全黑、场景未就绪、资源缺失或捕获的是错误视角。
+- 必要视觉工具不可用，或只完成了捕获而没有执行要求的视觉检查。
+- 视觉审查发现错误，但后续报告只引用编译成功来宣称完成。
+- 自动更新参考图、删除失败截图或扩大容差，用来掩盖未经确认的回归。
+
+正常审美选择以用户需求和项目标准为准。现有自动化无法判断时，应标为不确定并补充检查，不能捏造“视觉通过”。用户可以提出审美反馈，但用户看图不能成为技术验收的必经人工操作。
+
+### 15.2 状态、回放与跨环境容差
+
+玩法测试使用受控时间、随机源、输入记录和状态断言。同一受控环境追求可复现；不同 GPU、驱动或浏览器采用明确容差，不承诺跨硬件逐位或逐像素一致。
+
+快照、回放与玩家存档分别记录格式和版本。恢复必须检查实体、资源引用及实际状态，不能仅以文件成功读入作为正确性结论。测试直接恢复快照时，也须另有真实交互路径的验证。
+
+## 16. 性能、画质与跨系统证据
+
+画质能力、功能正确性与性能分别验收，不用达到帧率来定义高画质。光栅、混合实时光追、动态全路径追踪等实际模式必须写入报告，不允许静默切换渲染模式、关闭目标效果或降低分辨率后宣称原目标达标。
+
+已有目标为主流独立显卡、原生 1920×1080、60 FPS 的基准场景；具体机器、负载与阈值需要通过技术验证量化。这不等于承诺全部场景、全部模拟和动态路径追踪同时开启仍达到同一性能。各模式应给出实际测试条件、质量证据、性能和限制。
+
+性能报告至少说明：环境、内容标识、场景负载、预热与采样方式、帧时间分位数、卡顿、加载耗时、资源驻留，以及可可靠获取的 CPU/GPU 和内存指标。不能获得的指标标为未知或估算，不编造精确数值。
+
+跨系统测试按能力矩阵组织，例如：
+
+- 动画、布料或软体形变后，实际渲染、相关碰撞与光追结构是否同步。
+- 建造、破坏和地形修改后，导航、物理、流送与存档是否一致。
+- 连续场景卸载再加载后，状态、资源引用、UI、音频和任务是否恢复。
+- 资源反复创建释放及长时间运行后，是否出现增长、失效引用或行为漂移。
+
+这些示例用于规定验证方式，不替代各模块的正式交互支持矩阵。孤立演示能运行不代表系统组合已经完成。
+
+## 17. 标准发布产物与静态部署
+
+游戏构建输出为游戏工程中的 `dist/`，其内容应足以部署到 Web 服务器运行，不依赖引擎目录、源码仓库、开发工具、开发 AI 或 pelican 在线服务。
+
+拟定发布流程为：
+
+1. 固定项目输入、引擎版本、依赖与资产清单，完成所需检查。
+2. 构建内容、按需模块与资源分包，生成产物标识和依赖解释报告。
+3. 检查路径、文件存在性、资源清单、必要许可声明与敏感信息遗漏。
+4. 用静态服务器启动实际 `dist/`，验证入口、资源加载、主要玩法与错误提示。
+5. 验证部署子路径、资源地址和流送行为，确认没有开发机器绝对路径。
+6. 检查生产构建没有默认启用开发控制、测试驱动或模型服务依赖。
+7. 输出产物路径、部署配置说明、验收报告、已知限制与回滚所需标识。
+
+部署可以在服务器根路径或明确配置的子路径，不能假设固定域名和托管平台。静态产物仍须满足实际浏览器运行条件；“生成了文件”不能替代服务器预览验收。
+
+构建产物交付与向外部服务器上传是两个动作。默认完成可部署的 `dist/`；只有需求中包含部署且已有对应权限与凭据时，外部开发流程才执行上传，不把发布到自建平台作为必经步骤。
+
+## 18. 版本锁定、迁移与恢复
+
+游戏记录其引擎版本、内容标识和兼容契约；不自动跟随最新目录或远程分支。引擎、工作流协议、内容格式、存档和回放分别标识版本，不用一个模糊版本号承诺全部兼容。
+
+版本迁移拟定流程如下：
+
+1. 读取当前与目标版本，检查引擎路径、项目输入及迁移支持范围。
+2. 先生成影响报告，区分自动转换、外部 AI 需修改的游戏代码和未支持项。
+3. 创建项目与必要存档的可恢复副本或文件清单，不能只备份唯一副本的部分内容。
+4. 执行已明确的转换，记录文件变更；游戏开发 AI 只改游戏侧内容，不为适配而补丁修改引擎。
+5. 切换到目标引擎版本的公开引用，重新准备所需依赖与生成结果。
+6. 执行类型、内容、冷启动、玩法、视觉、性能及适用的存档回放验证。
+7. 成功后更新版本记录；失败则保留证据并恢复原引用和项目状态。
+
+Git 检查点可以辅助，但 ZIP 和普通目录必须可通过备份、内容清单及变更日志恢复。迁移工具不得强制丢弃旧存档或覆盖唯一有效数据。
+
+不支持的转换不能假装自动完成；应输出定位明确的迁移任务供外部 AI 处理。若目标版本存在真实能力缺口，报告阻塞，不通过绕过公开 API 解决。
+
+## 19. 仓库任务契约与 AI 交接
+
+研发计划、任务记录、决策、验证报告及证据应采用可读文件和机器可解析字段保存于仓库约定位置。具体位置以后续实现确定，本文不要求立即创建这些文件。
+
+每个任务至少应具备以下契约：
+
+| 字段            | 内容                                                               |
+| --------------- | ------------------------------------------------------------------ |
+| `taskId` 与目标 | 稳定标识、所属里程碑、待解决问题及可观察结果                       |
+| Owner 与角色    | 引擎侧或游戏侧职责，主线负责者与执行者分工                         |
+| 输入版本        | 引擎、契约、内容和依赖版本；有 Git 时可附提交，无 Git 时用内容清单 |
+| 前置依赖        | 必须完成的任务、已确认接口与运行环境                               |
+| 修改范围        | 允许修改的文件或模块、生成目录及需要协调的共享契约                 |
+| 非目标          | 当前任务不承担的功能，避免执行过程无限扩张                         |
+| 交付物          | 代码或设计、文档、示例、迁移及证据要求                             |
+| 验收方式        | 实际实现后可执行的命令、输入、断言、质量指标及证据路径             |
+| 执行边界        | 超时、重试、取消、资源与费用边界                                   |
+| 状态与交接      | 已完成步骤、未完成项、失败记录、恢复点与下一步                     |
+
+任务状态至少区分待处理、进行中、待集成、待验证、完成及阻塞。阻塞记录必须说明缺少什么、影响哪些任务；尚未验证不能直接标为完成。
+
+交接材料应让没有对话上下文的另一个外部 AI 知道：当前版本、已做变更、哪些结果可信、如何复现失败、下一步应执行什么。对话摘要可以补充，但不是唯一状态来源。
+
+## 20. 多 AI 并行与主线集成（历史设计，D51 下不执行）
+
+允许外部主线 AI 统筹多个研发 AI，但不把多 AI 作为使用或研发前提。现成编码工具、目录、任务文件和普通进程即可承载协作，不建设模型调度、代理市场或常驻 AI 服务。
+
+拟定协作流程为：
+
+1. 主线 AI 根据依赖图拆分任务，先固定共享接口、Schema 和验收条件。
+2. 为并行任务分配明确修改范围，使用隔离工作副本或适当的独立工作区；Git worktree 可选，不强制依赖 Git。
+3. 执行者先核实输入版本；共享契约需要变化时提交变更说明，由主线协调，避免各自发明不兼容接口。
+4. 各执行者交付变更清单、必要文档、验证记录、产物与已知问题，不以一句“已完成”交接。
+5. 主线 AI 检查范围、公开契约、重复实现与集成影响，按依赖顺序合入。
+6. 在主线环境重新运行受影响的跨系统检查；分支通过不能替代集成通过。
+7. 主线确认交付证据齐全后更新任务与里程碑状态，失败则保留原记录并形成后续任务。
+
+任务范围是协作约定，不是文件安全隔离机制。遇到用户已有修改或未知产物，先识别归属，不覆盖或删除以求环境干净。
+
+只有单个 AI 时，按相同任务契约串行执行，并明确区分实现、自查和集成复验阶段；不能伪称存在独立审查者。确需无上下文复测的验收，另起干净会话执行，而非在原会话中口头宣称忘记历史。
+
+## 21. 无上下文 AI 实作基准
+
+“100% AI 可用”必须通过真实任务验证，不能只验证工具能启动。基准执行者只获得用户需求、引擎仓库地址或目录、约定的本地环境，不获得研发聊天记录、内部实现提示或专门为该题准备的解答。
+
+### 21.1 必测场景
+
+| 场景                                | 验证重点                                          |
+| ----------------------------------- | ------------------------------------------------- |
+| Git 获取后的首个游戏                | 能发现入口、准备环境、使用公开 API 并交付可玩版本 |
+| ZIP 解压、无 `.git`、中文及空格路径 | 识别不依赖 Git、固定目录名或开发者机器路径        |
+| 外部引擎目录与独立游戏目录          | 本地引用、产物归属、引擎源码保持原样              |
+| 已缓存后的离线开发                  | 真实断网条件下检查、测试和构建，不偷用在线服务    |
+| 2D、2.5D 与 3D 代表任务             | 不只会修改第三人称样板，公开接口可迁移到其他玩法  |
+| 自定义材质、玩法与计算扩展          | 可仅凭公开文档完成扩展，不需导入内部模块          |
+| 已植入的逻辑或资产缺陷              | 能根据诊断定位、修复并复测，而不是只让构建变绿    |
+| 视觉错误与截图失败                  | 能分析外部截图；必要证据缺失时明确失败或阻塞      |
+| 中断与超时恢复                      | 任务不丢状态，进程与半成品可正确处理              |
+| 版本迁移与失败回退                  | 可自动处理游戏侧变更并保持旧版本可恢复            |
+| `dist/` 静态服务器运行              | 交付物独立于源码和开发服务，主要流程实际可玩      |
+
+### 21.2 记录与判定
+
+记录完成率、成功与失败原因、尝试次数、耗时、工具调用、诊断有效性、文档缺口、接口误用、证据完整度及是否需要人介入。执行环境、模型或工具版本、输入需求和测试条件应可追踪，但不能把某一模型的通过结果等同于所有 AI 永久可用。
+
+必需流程一旦需要人工安装、手改配置、点击工具、解释内部接口或代为定位缺陷，该次无人介入验收即不通过。人的新需求和审美反馈可以触发新任务，但不得用于掩盖原任务未完成。
+
+失败应回流到接口、工具、诊断、资料或样例的改进。重新测试须记录版本变化，保留原始失败；不得只挑选成功样例或反复更换执行者直到偶然通过。
+
+## 22. 研发推进与里程碑门禁
+
+正式研发先做已经确定的高风险技术验证，不在实测前编造完整工期，也不把工作流文档完成视为引擎能力完成。
+
+### 22.1 M0：风险原型，四条端到端链路
+
+- **编译链路：** 从受约束 TypeScript 定义到校验、内容结果与可运行样例，并将错误映射回源位置。
+- **动态渲染：** 代表性动态场景在目标渲染模式中的内容共享、更新与画质性能证据，明确实际限制。
+- **交互模拟：** 代表性刚体与布料、绳索、软体、流体交互，验证状态查询、渲染同步与恢复链路。
+- **外部 AI 闭环：** 无研发上下文的外部 AI 根据目录指引完成修改、启动、测试操作、捕获、诊断、修复与复验。
+
+每条原型保留输入、环境、代码或设计版本、操作记录、失败、证据与结论。原型只回答关键技术问题，不代表完整系统交付。组合成本或目标冲突须有证据与备选方案，不能静默删除已确认能力。
+
+### 22.2 M0—M8 工作流交付映射
+
+里程碑编号与研发计划统一，不在本文另建平行编号。下表描述各阶段的工作流责任，不替代 ROADMAP 的详细任务、依赖与能力验收。
+
+| 编号 | 阶段               | 工作流交付与门禁                                                                  |
+| ---- | ------------------ | --------------------------------------------------------------------------------- |
+| M0   | 风险原型           | 完成前述四条端到端链路；保留实测与失败证据，确认后续选型依据                      |
+| M1   | 基础               | 建立发现、环境准备、版本与协议契约、诊断事实源及最小工具闭环；覆盖 ZIP 和外部目录 |
+| M2   | 垂直切片           | 打通代表性可玩内容的编写、运行、测试操作、截图分析、冷启动与 `dist/` 预览         |
+| M3   | 光追与 PT          | 将动态模式、画质、更新成本和性能分别转成可重复测试；报告真实执行模式              |
+| M4   | 模拟               | 建立各类交互模拟、跨模块同步、状态恢复及失败诊断的证据链                          |
+| M5   | 世界、导航、动画   | 验证连续世界修改、路径更新、动画与过场，以及流送和持久化一致性                    |
+| M6   | UI、2D、音频、玩法 | 补齐各正式模块的公开示例、自动化交互、视觉或音频证据及组合任务                    |
+| M7   | 优化发布           | 完成负载测试、按需构建、离线缓存、静态部署、敏感信息检查与迁移恢复复验            |
+| M8   | 独立 AI 验收       | 无研发上下文地执行代表性需求、故障修复与交付；确认整个流程无需人工技术执行        |
+
+无上下文实作、文档校验和跨系统回归应从早期持续开展，不能全部拖到 M8。M8 是独立的最终验证，不是首次尝试使用引擎；M0 的小规模 AI 原型也不能替代 M8。
+
+历史设计允许并行推进；当前 D51 要求单主线串行。未完成或实验性能力显式标注，不能因接口已定义就计入正式范围。
+
+## 23. 工作流完成标准与最终交付证据
+
+单项任务完成需要满足：需求有对应实现或明确设计成果，公开契约一致，必要文档与示例同步，相关检查实际执行，失败已处理或显式标为未完成，证据可定位且可重复运行。
+
+整个 AI 工作流达到正式可用状态，还需证明：
+
+- 在受支持 Windows 开发环境中，不经人工安装或管理员步骤即可准备所需工具。
+- Git、ZIP、已有目录及外部引擎路径都能开始开发，目录名和 Git 元数据不是隐藏前提。
+- 单个外部 AI 不依赖专用插件即可完成标准流程，多 AI 可按相同任务契约协作。
+- 游戏开发只使用公开 API，不修改引擎，不需要理解内部依赖才能完成代表性任务。
+- 必要资产可本地获得；不配置生成服务也能开发完整可玩游戏，已有缓存时可离线工作。
+- 状态检查、自动操作、回放、视觉分析和性能报告形成可复验的修复闭环。
+- 缺失截图、缺失视觉判断、失败用例、超时及阻塞均可见，没有伪成功。
+- 版本迁移有恢复点，原有有效项目和存档不会被不受控覆盖。
+- `dist/` 可在 Web 服务器运行，默认不暴露开发控制，也不依赖外部 AI 或模型服务。
+- 任务、证据和决策足以支持无历史上下文的 AI 接续执行。
+
+最终交付报告应列出版本与输入、完成范围、实际执行的验证、产物路径、失败或限制、恢复方式和后续任务。任何未取得证据的承诺都应保持“待验证”，不能写成“已支持”。
+
+本文仅定义工作流规划。后续实现应逐项建立对应工具与验收证据；在此之前，不能宣称上述 CLI、协议或全自动能力已经可用。
+
+## 并行编码的 Worktree 隔离（历史设计，D51 下不执行）
+
+多代理不是游戏开发的前置条件。使用多代理编码时，每个任务必须在独立 Git worktree 内执行。主线分配接口和精确文件写入范围，负责审查、集成与最终验收；子任务不直接写主工作区，不提交、推送或发布。
+
+- 每批任务使用同一基线。若里程碑有未提交代码，在 detached worktree 应用同一二进制 diff，复制所需新文件，并记录 HEAD、路径与基线哈希。不通过临时提交破坏同节点发布规则。
+- 各任务写入集合互不重叠。共享 SDK、IR、实体和时间契约由主线固化；接口变化先通知依赖任务，再同步和验证。
+- 依赖可使用只读目录联接复用。子任务不修改共享依赖，依赖安装和版本调整由主线统一执行。
+- 合入前审查差异与测试，并确认主线文件仍符合该任务的基线哈希。只接收允许路径；主线同文件已变更时逐处合并，不整目录覆盖。
+- 每批合入后执行跨模块验证。子任务通过不等于里程碑验收；冻结后完成独立 AI 工作流与发布门禁，再统一中文 Conventional Commit、推送和 Release。
+- 清理前验证 worktree 绝对路径与归属，并保留未集成结果。不删除未知目录，不因任务停顿重建仍在工作的分支。