From 9cfe7ebea827cc13fbc2cac6d1440aa96db36a80 Mon Sep 17 00:00:00 2001
From: unanmed <1319491857@qq.com>
Date: Mon, 7 Sep 2026 18:26:46 +0800
Subject: [PATCH] docs(01): capture phase context

---
 .planning/phases/01-event/01-CONTEXT.md       | 87 +++++++++++++++++++
 .../phases/01-event/01-DISCUSSION-LOG.md      | 45 ++++++++++
 2 files changed, 132 insertions(+)
 create mode 100644 .planning/phases/01-event/01-CONTEXT.md
 create mode 100644 .planning/phases/01-event/01-DISCUSSION-LOG.md

diff --git a/.planning/phases/01-event/01-CONTEXT.md b/.planning/phases/01-event/01-CONTEXT.md
new file mode 100644
index 0000000..1681941
--- /dev/null
+++ b/.planning/phases/01-event/01-CONTEXT.md
@@ -0,0 +1,87 @@
+# Phase 1: 事件系统 - Context
+
+**Gathered:** 2026-09-07
+**Status:** Ready for planning
+
+## Phase Boundary
+
+本阶段交付 blockly 式低代码事件系统：引擎能通过数据/序列化接口定义事件（blockly 由外部编辑器生成序列化数据），并驱动踩踏触发、对话、开门等简单场景事件流程。事件系统定位为初学者抽象，仅覆盖简单场景，不为复杂场景追求通用表达。
+
+## Implementation Decisions
+
+### 触发绑定
+
+- **D-01:** 事件绑定粒度：对象 + 地图格混合，两者都可绑定事件
+- **D-02:** 触发方式使用 `EventTrigger` 枚举（11 种内置 + 可自行扩展），定义于 `packages-user/data-common/src/event/types.ts`
+- **D-03:** 绑定对象分两类：点事件（不随脚下图块移动）与图块事件（随图块移动）
+- **D-04:** 对象上存储的是 eventStore 的 id，而非事件本身
+- **D-05:** 图块默认事件（怪物→战斗、道具→捡拾、可自定义）也走 eventStore（id 引用），可被自定义事件覆盖
+- **D-06:** 执行顺序：先点事件、后图块事件，各自按优先级从高到低执行
+
+### 执行流
+
+- **D-07:** 事件内容 = Anon Tokyo 的 `Statement[]`，`interpreter.compile()` 编译为 `AnonTokyoExecutable`
+- **D-08:** 执行 = `execute(param, env)`，`param` 为本次执行参数、`env` 为本次执行的环境对象
+- **D-09:** 长事件（如对话）直接用 `await` 等待，不需要序列化执行状态；现阶段不聚焦解释执行的细节
+- **D-10:** before 类触发器（OnBeforeBattle/OnBeforeOpenDoor/OnBeforeChangeFloor）的返回值处理：抽象一个专门对象负责事件执行（含 before 返回值的语义）
+- **D-11:** 事件存储 `GameEventStore`（id → event），不进存档；代码生成的事件生成后立即执行、不落存档
+- **D-12:** 点/图块事件的存档采用 dirty 标记：初始化时 dirty=false，后续变动且与原始数据不同则标记为 true
+- **D-13:** 旧的 `ITrigger` 体系在本次阶段一并删除
+
+### the agent's Discretion
+
+接口设计由用户主导（PROJECT.md 协作模型）；AI 仅在已设计接口上实现、不自行设计接口。
+
+## Canonical References
+
+**Downstream agents MUST read these before planning or implementing.**
+
+### 事件系统
+
+- `packages-user/data-common/src/event/types.ts` — `EventTrigger` 枚举 + `IGameEvent` / `IReadonlyGameEvent` 接口定义
+- `packages-user/data-common/src/store/eventStore.ts` — `GameEventStore`（id → event）
+- `node_modules/anon-tokyo/dist/index.d.ts` — Anon Tokyo 解释器类型（`Statement` / `AnonTokyoInterpreter` / `AnonTokyoExecutable`）
+
+### 待删除的旧体系
+
+- `packages-user/data-system/src/trigger/` — 旧 `ITrigger` 体系（registry/collector/collection/base）
+- `packages-user/data-state/src/content/triggers.ts` — `ChangeFloorTrigger`
+- `packages-user/data-state/src/hero/moverImpl.ts` — 使用 `ITriggerCollector` 的部分
+- `packages-user/data-state/src/core.ts` — `triggerRegistry` / `triggerCollector` 引用
+
+### 规划文档
+
+- `.planning/ROADMAP.md` — Phase 1 目标与成功标准
+- `.planning/REQUIREMENTS.md` — EVT-01 / EVT-02 / EVT-03
+- `.planning/PROJECT.md` — 协作模型与约束
+
+## Existing Code Insights
+
+### Reusable Assets
+
+- `GameEventStore`（`eventStore.ts`）：id → `IReadonlyGameEvent` 的 Map，已实现 `addEvent` / `getEvent`
+- `EventTrigger` 枚举 + `IGameEvent` / `IReadonlyGameEvent` 接口（`types.ts`）：已定义 `compile` / `execute` / `setTrigger` / `setRaw`
+- Anon Tokyo 解释器（`anon-tokyo@0.0.0-alpha.0`，node_modules 中，尚未在源码引用）
+
+### Established Patterns
+
+- 事件执行：`interpreter.compile(Statement[])` → `AnonTokyoExecutable`，`execute(param, env)` 异步返回
+- 数据端分层：事件类型在 L0（data-common），存储用 store（Map）
+
+### Integration Points
+
+- 旧 trigger 体系在 data-system（`TriggerRegistry` / `TriggerCollector`）与 data-state（`core.ts` 的 registry/collector、`moverImpl.ts`、`content/triggers.ts`）——本次删除
+- 新事件系统通过 `eventStore` 暴露给上层（数据层 / 渲染层），事件经 `execute` 驱动游戏状态
+
+## Specific Ideas
+
+无特定外部引用——接口与格式由用户主导，已在 decisions 中锁定。
+
+## Deferred Ideas
+
+None — 讨论保持在阶段范围内，未提出跨阶段新增能力。
+
+---
+
+*Phase: 1-事件系统*
+*Context gathered: 2026-09-07*
diff --git a/.planning/phases/01-event/01-DISCUSSION-LOG.md b/.planning/phases/01-event/01-DISCUSSION-LOG.md
new file mode 100644
index 0000000..7f360ad
--- /dev/null
+++ b/.planning/phases/01-event/01-DISCUSSION-LOG.md
@@ -0,0 +1,45 @@
+# Phase 1: 事件系统 - Discussion Log
+
+> **Audit trail only.** Do not use as input to planning, research, or execution agents.
+> Decisions are captured in CONTEXT.md — this log preserves the alternatives considered.
+
+**Date:** 2026-09-07
+**Phase:** 1-事件系统
+**Areas discussed:** 触发绑定机制, 执行流模型
+
+---
+
+## 触发绑定机制
+
+| Option | Description | Selected |
+|--------|-------------|----------|
+| 对象绑定为主 | 事件挂在对象上，地图格本身无事件 | |
+| 地图格绑定为主 | 事件挂在地图格上，踩上/站在格上触发 | |
+| 对象+地图格混合 | 对象与地图格都可绑定事件，视场景而定 | ✓ |
+
+**User's choice:** 对象 + 地图格混合绑定。
+
+**Notes:** 用户随后给出完整的 8 点设计说明（触发器 EventTrigger 枚举 / Anon Tokyo 类型 / 执行 param+env / 事件返回 / eventStore 存储 / 点事件与图块事件 / 执行顺序优先级 / dirty 存档标记），并明确接口设计由其主导。
+
+---
+
+## 执行流模型
+
+**User's choice:** 通过自由阐述 + 追问确定，关键结论：
+
+- before 类触发器（OnBeforeBattle/OnBeforeOpenDoor/OnBeforeChangeFloor）的返回值处理：抽象一个专门对象负责事件执行
+- 长事件（对话）直接用 `await`，不需要序列化执行状态；现阶段不聚焦解释执行细节
+- 图块默认事件（怪物→战斗、道具→捡拾）也走 eventStore，可被自定义覆盖
+- 旧 `ITrigger` 体系在本次阶段一并删除
+
+**Notes:** Anon Tokyo 解释器（`anon-tokyo@0.0.0-alpha.0`）为领域专用解释器，`compile(Statement[])` → `AnonTokyoExecutable`，执行 `execute(param, env)`。
+
+---
+
+## the agent's Discretion
+
+无——接口设计由用户主导（PROJECT.md 协作模型）；AI 仅在已设计接口上实现、不自行设计接口。
+
+## Deferred Ideas
+
+None——讨论保持在阶段范围内，未提出跨阶段新增能力。