Codex/phase1 dev tools

AGENTS.md

@@ -0,0 +1,45 @@
+# PySTG Agent Instructions
+
+This file applies to the whole repository.
+
+## Editor roadmap
+
+Before making substantial changes to the Godot-style authoring editor, read
+[`docs/EDITOR_ROADMAP_TODO.md`](docs/EDITOR_ROADMAP_TODO.md) completely.
+
+The roadmap is the durable source of truth for:
+
+- implementation order and dependencies;
+- editor/runtime architecture boundaries;
+- the current milestone and deferred scope;
+- completion gates and verification evidence.
+
+Do not begin a later roadmap phase merely because its UI is easier to demo.
+Foundation, runtime parity, and preview gates must be completed in dependency
+order.
+
+## Working rules
+
+1. Check `git status --short` before editing. Preserve unrelated user changes.
+2. For substantial work, propose the intended roadmap task IDs, boundaries, and
+   tradeoffs before implementation.
+3. Keep authoring documents as the source of truth. Generated Python is an
+   optional export and must not become the only runnable representation.
+4. Never expand high-density bullets into scene-tree nodes or attach a Python
+   per-frame callback to every bullet.
+5. Preview results must use the formal runtime path. Label structural tests,
+   simulated previews, and visually accepted results separately.
+6. All document mutations initiated by editor UI must participate in Undo/Redo.
+7. New document schema versions require migration and round-trip tests.
+8. Use project-relative resource references and `ProjectContext`; do not add new
+   current-working-directory assumptions.
+9. Do not mark a roadmap phase complete until its explicit gate passes.
+10. After completing roadmap work, update the checkboxes and append concise,
+    reproducible evidence to the roadmap completion log.
+
+## Verification baseline
+
+Use the narrowest relevant tests while iterating. Before declaring a roadmap
+gate complete, run the gate-specific checks plus the repository merge checks
+listed in `docs/EDITOR_ARCHITECTURE.md`. Qt tests should use an offscreen
+platform when no interactive display is available.

README.md

@@ -146,6 +146,9 @@ flowchart TB
 | [纹理资产系统](docs/TEXTURE_ASSET_SYSTEM.md) | 图集加载、精灵定义、动画配置 |
 | [开发工具链](docs/DEVTOOLS_PHASE1.md) | 资源校验、热重载、Pattern Lab 和符卡预览 |
 | [编辑器架构边界](docs/EDITOR_ARCHITECTURE.md) | 编辑器、文档、运行时和资源服务的依赖约束 |
+| [作者资源契约](docs/AUTHORING_RESOURCE_CONTRACTS.md) | M0 资源头、引用、迁移、坐标、时间和注册表协议 |
+| [弹幕资源与正式运行时契约](docs/PATTERN_RESOURCE_CONTRACT.md) | M1 PatternDocument、不可变 IR、批量 runner 与预览/游戏同源边界 |
+| [编辑器长期路线 TODO](docs/EDITOR_ROADMAP_TODO.md) | 分阶段任务、依赖、Gate 与完成证据 |
 
 也可以本地启动 VitePress 文档站点：
 

docs/AUTHORING_RESOURCE_CONTRACTS.md

@@ -0,0 +1,120 @@
+# 作者资源契约（M0）
+
+本文冻结 Godot 式编辑器 Phase 0 使用的最小公共协议。弹幕配方、时间轴、UI
+布局和背景的领域字段将在后续阶段分别定义；它们不得绕过这里的身份、版本、引用、
+坐标、时间和注册表契约。
+
+## 文件与公共资源头
+
+所有版本化作者资源保留 `*.pystg.json` 后缀。资源类型由 JSON 内的 `type`
+决定，不依赖文件名猜测：
+
+```json
+{
+  "schema_version": 1,
+  "type": "pystg.pattern",
+  "id": "08ac589e-a51a-45dc-beb9-7af6f4e136db",
+  "name": "星符「星轨回廊」",
+  "symbol_name": "star_corridor",
+  "metadata": {}
+}
+```
+
+M0 注册以下类型：
+
+| `type` | 资源浏览器类别 | 领域正文冻结阶段 |
+|---|---|---|
+| `pystg.scene` | Scene | 已有 v1，Phase 4 扩展时间轴 |
+| `pystg.pattern` | Pattern | Phase 1 |
+| `pystg.ui` | UI | Phase 6 |
+| `pystg.background` | Background | Phase 6 |
+
+公共字段语义：
+
+- `schema_version`：该 `type` 的整数 schema 版本，不是应用版本。
+- `id`：稳定 UUID，用于引用和对象身份。
+- `name`：面向作者的 Unicode 显示名，可直接使用中文。
+- `symbol_name`：可选的便携 Python 标识符，仅在代码导出/脚本绑定需要时使用。
+- `metadata`：JSON 对象；不能替代需要验证的正式领域字段。
+
+显示名、UUID 和脚本符号是三个不同概念。不得为了生成 Python 而限制显示名。
+
+## 资源引用
+
+新写入的引用统一使用：
+
+```text
+res://assets/images/bullet.json#orb
+res://game_content/patterns/star-ring.pystg.json
+```
+
+- `res://` 后是相对项目根目录的 POSIX 路径。
+- `#fragment` 是可选子资源名。
+- 禁止绝对路径、盘符、`.` 和 `..` 穿越。
+- 读取器在迁移期可接受旧的项目相对路径，但保存的新引用必须规范化为 `res://`。
+- 路径解析必须通过 `ResourceReference` 和 `ProjectContext`。
+
+## 迁移
+
+迁移由 `MigrationRegistry` 按 `(resource_type, from_version)` 显式注册，且每次只
+允许从 `N` 迁移到 `N+1`。迁移函数：
+
+1. 接收并返回 JSON object；
+2. 不得改变 `type`；
+3. 必须把 `schema_version` 精确增加 1；
+4. 必须有输入 fixture、迁移结果和 round-trip 测试；
+5. 遇到未来版本或缺失迁移路径时给出可操作错误，不能猜测降级。
+
+旧无版本场景通过已注册的 `pystg.scene` v0→v1 迁移进入当前模型。
+
+## 坐标
+
+作者空间是与实际窗口缩放无关的逻辑画布：
+
+| 项目 | 约定 |
+|---|---|
+| 基准尺寸 | 384×448 |
+| 作者原点 | 左上 |
+| 作者 X | 向右 |
+| 作者 Y | 向下 |
+| 运行时原点 | 画面中心 |
+| 运行时 X/Y | `[-1, 1]` |
+| 运行时 Y | 向上 |
+
+转换公式由 `src.authoring.coordinates.CoordinateSpace` 唯一实现。视口放大到
+768×896 或其他尺寸不能改变最终运行时位置。
+
+## 时间
+
+- 文档主时间使用非负整数帧。
+- 默认 tick rate 为 60Hz。
+- 秒和拍是编辑器显示/输入单位，由 `Timebase` 转换。
+- 时间轴排序、对象身份和确定性回放不得依赖浮点秒相等判断。
+
+## 注册表
+
+`ResourceTypeRegistry` 为每个资源类型提供以下可选 contribution：
+
+- loader；
+- validator；
+- editor factory；
+- compiler；
+- preview handler。
+
+`NodeTypeRegistry` 为每个场景节点提供：
+
+- 属性 schema 和 Inspector 提示；
+- 父子约束和验证器；
+- Viewport 表现；
+- editor factory；
+- runtime compiler。
+
+编辑器外壳使用注册表查询，不得为了新资源/节点类型继续添加编译或绘制类型分支。
+
+## Phase 0 与后续阶段的边界
+
+M0 只冻结公共契约和贡献入口，不预先虚构 Pattern/UI/Background 正文字段。领域
+文档可以由 `GenericResourceDocument` 无损保存，在相应阶段由注册表替换为强类型
+loader/validator，并通过新的 schema 迁移演进。
+
+Generated Python 始终是可选导出物，不是作者资源的唯一可运行表示。

docs/EDITOR_ARCHITECTURE.md

@@ -21,7 +21,10 @@ Runtime / renderer / resource service
 
 ## 文档
 
-- 新场景文件使用 `pystg.scene` 类型和整数 `schema_version`。
+- 所有作者资源使用 `*.pystg.json`，由文档内的 `type` 区分
+  `pystg.scene`、`pystg.pattern`、`pystg.ui` 和 `pystg.background`。
+- 公共资源头、引用、迁移、坐标和时间契约见
+  [`AUTHORING_RESOURCE_CONTRACTS.md`](AUTHORING_RESOURCE_CONTRACTS.md)。
 - 文档、节点和时间轴事件都有稳定 UUID。
 - `DocumentStore` 只允许读写项目目录内文件，并使用原子替换保存。
 - 新 schema 必须提供迁移函数和 round-trip 测试。
@@ -36,11 +39,21 @@ Runtime / renderer / resource service
 
 ## 资源
 
-- `ResourceService` 是运行时和编辑器创建资源模型的统一入口。
+- `ResourceTypeRegistry` 是版本化作者资源的 loader、validator、editor、compiler
+  和 preview contribution 入口；编辑器外壳不得按资源类型增加编译分支。
+- `ResourceService` 继续负责当前运行时纹理目录和富编辑纹理兼容模型。
 - `TextureAssetManager` 是当前正式运行时纹理目录。
 - `UnifiedTextureManager` 暂作为富编辑类型兼容模型，由 `ResourceService.editor` 管理。
 - 两种内部表示迁移完成前，关键资源必须通过契约测试证明解析结果一致。
 
+## 坐标与时间
+
+- 作者画布使用固定逻辑像素，基准尺寸为 `384x448`，原点在左上，Y 向下。
+- 正式运行时坐标以画面中心为原点，X/Y 范围均为 `[-1, 1]`，Y 向上。
+- 编辑器、文档编译器和预览只能通过 `CoordinateSpace` 做两者转换。
+- 文档时间存储为声明 tick rate 下的非负整数帧；第一版 tick rate 为 60Hz。
+- 秒和拍仅为显示/输入单位，通过 `Timebase` 转换，不以浮点秒作为时间轴主键。
+
 ## 编辑操作
 
 - Inspector、场景树和时间轴修改必须经过 `CommandStack`，以支持 Undo/Redo。