From e1e32b2b048fc58cc985272332cb328ef5a91423 Mon Sep 17 00:00:00 2001 From: gewuyou <95328647+GeWuYou@users.noreply.github.com> Date: Sun, 19 Apr 2026 20:51:44 +0800 Subject: [PATCH] =?UTF-8?q?docs(ai-plan):=20=E8=BF=81=E7=A7=BB=20coroutine?= =?UTF-8?q?=20=E6=97=A9=E6=9C=9F=E8=AE=A1=E5=88=92?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 新增 coroutine-optimization 主题并整合 legacy local-plan todo，补写缺失 trace 的恢复边界\n- 更新 ai-plan 公共索引与治理跟踪，建立 feat/coroutine-optimization 的 topic 映射\n- 删除 worktree 根目录 legacy local-plan 入口，统一从 ai-plan/public 恢复 --- ai-plan/public/README.md | 9 + .../todos/ai-plan-governance-tracking.md | 18 +- .../traces/ai-plan-governance-trace.md | 25 +++ ...oroutine-optimization-history-pre-rp001.md | 211 ++++++++++++++++++ ...oroutine-optimization-history-pre-rp001.md | 40 ++++ .../todos/coroutine-optimization-tracking.md | 53 +++++ .../traces/coroutine-optimization-trace.md | 34 +++ 7 files changed, 384 insertions(+), 6 deletions(-) create mode 100644 ai-plan/public/coroutine-optimization/archive/todos/coroutine-optimization-history-pre-rp001.md create mode 100644 ai-plan/public/coroutine-optimization/archive/traces/coroutine-optimization-history-pre-rp001.md create mode 100644 ai-plan/public/coroutine-optimization/todos/coroutine-optimization-tracking.md create mode 100644 ai-plan/public/coroutine-optimization/traces/coroutine-optimization-trace.md diff --git a/ai-plan/public/README.md b/ai-plan/public/README.md index 8b19c3ef..c885f30c 100644 --- a/ai-plan/public/README.md +++ b/ai-plan/public/README.md @@ -25,6 +25,11 @@ help the current worktree land on the right recovery documents without scanning - Purpose: continue the AI-First config runtime, generator, and consumer DX work for `GFramework.Game`. - Tracking: `ai-plan/public/ai-first-config-system/todos/ai-first-config-system-tracking.md` - Trace: `ai-plan/public/ai-first-config-system/traces/ai-first-config-system-trace.md` +- `coroutine-optimization` + - Purpose: continue the coroutine semantics, host integration, observability, regression coverage, and migration-doc + follow-up work. + - Tracking: `ai-plan/public/coroutine-optimization/todos/coroutine-optimization-tracking.md` + - Trace: `ai-plan/public/coroutine-optimization/traces/coroutine-optimization-trace.md` - `cqrs-rewrite` - Purpose: continue the CQRS migration, registry hardening, and related PR follow-up. - Tracking: `ai-plan/public/cqrs-rewrite/todos/cqrs-rewrite-migration-tracking.md` @@ -46,6 +51,10 @@ help the current worktree land on the right recovery documents without scanning - Worktree hint: `GFramework-cqrs` - Priority 1: `ai-plan-governance` - Priority 2: `cqrs-rewrite` +- Branch: `feat/coroutine-optimization` + - Worktree hint: `GFramework-coroutine-optimization` + - Priority 1: `coroutine-optimization` + - Priority 2: `ai-plan-governance` - Branch: `docs/sdk-update-documentation` - Worktree hint: `GFramework-update-documentation` - Priority 1: `documentation-governance-and-refresh` diff --git a/ai-plan/public/ai-plan-governance/todos/ai-plan-governance-tracking.md b/ai-plan/public/ai-plan-governance/todos/ai-plan-governance-tracking.md index 23843314..635a2183 100644 --- a/ai-plan/public/ai-plan-governance/todos/ai-plan-governance-tracking.md +++ b/ai-plan/public/ai-plan-governance/todos/ai-plan-governance-tracking.md @@ -20,8 +20,7 @@ - 将"主题内 `archive/` 已存在"升级为"active todo/trace 过长时必须归档已完成且已验证阶段"的显式规则 - 让 active `todos/` / `traces/` 只保留当前恢复点、活跃事实、活跃风险、下一步与 archive 指针 - 将 `ai-plan-governance`、`ai-first-config-system` 与 `cqrs-rewrite` 的历史阶段从默认启动入口移出 - - 将当前工作树遗留的 `local-plan` 示例迁入 `ai-plan/public//`，验证治理规则对多个新 topic - 迁移同样成立 + - 验证“只有早期 todo、没有 durable trace”的 legacy `local-plan` 也能迁入 `ai-plan/public//`，且不退化为简单目录平移 ### 已知风险 @@ -55,9 +54,16 @@ - `ai-plan/public/documentation-governance-and-refresh/traces/` - `ai-plan/public/documentation-governance-and-refresh/archive/todos/` - `ai-plan/public/documentation-governance-and-refresh/archive/traces/` +- 已将当前工作树遗留的 coroutine early-plan 恢复文档从 `local-plan/` 迁入： + - `ai-plan/public/coroutine-optimization/todos/` + - `ai-plan/public/coroutine-optimization/traces/` + - `ai-plan/public/coroutine-optimization/archive/todos/` + - `ai-plan/public/coroutine-optimization/archive/traces/` - 已同步更新 `ai-plan/public/README.md`，将分支 `fix/analyzer-warning-reduction-batch` 映射到新 topic - 已同步更新 `ai-plan/public/README.md`，将分支 `docs/sdk-update-documentation` 映射到 `documentation-governance-and-refresh` +- 已同步更新 `ai-plan/public/README.md`，将分支 `feat/coroutine-optimization` 映射到 + `coroutine-optimization` - 已同步更新 `AGENTS.md`、`ai-plan/README.md` 与 `gframework-boot`，明确 active 文档不是追加式日志，已完成且已验证阶段必须归档 ## 验证 @@ -65,15 +71,15 @@ - `find ai-plan/public -maxdepth 5 -type f | sort` - 结果：通过 - 备注：活跃主题、主题内归档文件与主题级归档都已按新目录语义落位 -- `wc -l ai-plan/public/ai-plan-governance/todos/ai-plan-governance-tracking.md ai-plan/public/ai-plan-governance/traces/ai-plan-governance-trace.md ai-plan/public/ai-first-config-system/todos/ai-first-config-system-tracking.md ai-plan/public/ai-first-config-system/traces/ai-first-config-system-trace.md ai-plan/public/cqrs-rewrite/todos/cqrs-rewrite-migration-tracking.md ai-plan/public/cqrs-rewrite/traces/cqrs-rewrite-migration-trace.md ai-plan/public/analyzer-warning-reduction/todos/analyzer-warning-reduction-tracking.md ai-plan/public/analyzer-warning-reduction/traces/analyzer-warning-reduction-trace.md ai-plan/public/documentation-governance-and-refresh/todos/documentation-governance-and-refresh-tracking.md ai-plan/public/documentation-governance-and-refresh/traces/documentation-governance-and-refresh-trace.md` - - 结果：通过 - - 备注：10 个 active 入口文件当前合计 `508` 行，仍保持为按 topic 精简后的恢复入口，而非追加式历史日志 - `find ai-plan/public/analyzer-warning-reduction -maxdepth 3 -type f | sort` - 结果：通过 - 备注：新 topic 已按 `todos/`、`traces/` 与主题内 `archive/` 目录语义落位 - `find ai-plan/public/documentation-governance-and-refresh -maxdepth 3 -type f | sort` - 结果：通过 - 备注：文档治理 topic 已按 `todos/`、`traces/` 与主题内 `archive/` 目录语义落位 +- `find ai-plan/public/coroutine-optimization -maxdepth 3 -type f | sort` + - 结果：通过 + - 备注：更早期、只有 todo 没有 trace 的 coroutine 计划也已按治理规则补齐 active 入口与 archive - `test ! -e local-plan` - 结果：通过 - 备注：当前工作树根目录已不再保留 legacy `local-plan/` @@ -88,6 +94,6 @@ ## 下一步 -1. 继续扫描是否还有遗留的 `local-plan` 或其他非 `ai-plan` 的 durable recovery 文档目录 +1. 继续扫描是否还有遗留的 `local-plan` 或其他非 `ai-plan` 的 durable recovery 文档目录，尤其关注只有 todo 没有 trace 的更早期计划 2. 后续只要某个 active 主题积累了多个已完成且已验证阶段，就在同一变更里将其细节迁入该主题自己的 `archive/` 3. 若某个主题整体完成，再将整个主题目录移入 `ai-plan/public/archive//` diff --git a/ai-plan/public/ai-plan-governance/traces/ai-plan-governance-trace.md b/ai-plan/public/ai-plan-governance/traces/ai-plan-governance-trace.md index 0d337a19..277f0505 100644 --- a/ai-plan/public/ai-plan-governance/traces/ai-plan-governance-trace.md +++ b/ai-plan/public/ai-plan-governance/traces/ai-plan-governance-trace.md @@ -68,3 +68,28 @@ 1. 后续若其他 worktree 仍存在 `local-plan` 一类目录，继续按 topic 归属迁入对应 `ai-plan/public//` 2. 继续保持 topic active 入口精简，避免把迁移后的公共目录重新写成追加式日志 + +### 阶段：coroutine early-plan local-plan 迁移验证（RP-005） + +- 复核当前工作树后确认：遗留的 `local-plan/` 内容属于 coroutine 主题，但它比前两次迁移更早，只保留了 `5` 份 todo， + 没有任何独立 trace +- 按同一治理规则建立 `ai-plan/public/coroutine-optimization/`，并补齐： + - `todos/` + - `traces/` + - `archive/todos/` + - `archive/traces/` +- 将旧 `local-plan` 中分散的五个阶段计划整合进主题内历史跟踪归档，并额外补写一份基于 todo 基线整理出的历史 trace， + 显式记录“缺少原始 trace，只能恢复稳定结论”的边界 +- 新建精简版 active tracking / trace 入口，只保留当前恢复点、活跃事实、风险与下一步 +- 在 `ai-plan/public/README.md` 中建立 + `feat/coroutine-optimization` -> `coroutine-optimization` 的 worktree 映射，并把 `ai-plan-governance` 作为 secondary topic 保留 +- 删除旧 `local-plan` 目录，验证当前工作树根目录已不再保留 legacy 私有恢复入口 +- 额外完成验证： + - `find ai-plan/public/coroutine-optimization -maxdepth 3 -type f | sort` + - `test ! -e local-plan` + - `dotnet build GFramework.Core.Abstractions/GFramework.Core.Abstractions.csproj -c Release -p:RestoreFallbackFolders=` + +### 下一步 + +1. 后续若再遇到“只有 todo、没有 trace”的更早期计划，继续按同一模式迁入 topic archive，并明确标注推导边界 +2. 保持新 topic 的 active 入口精简，不把补写 trace 变成伪造逐日执行日志 diff --git a/ai-plan/public/coroutine-optimization/archive/todos/coroutine-optimization-history-pre-rp001.md b/ai-plan/public/coroutine-optimization/archive/todos/coroutine-optimization-history-pre-rp001.md new file mode 100644 index 00000000..83d0a696 --- /dev/null +++ b/ai-plan/public/coroutine-optimization/archive/todos/coroutine-optimization-history-pre-rp001.md @@ -0,0 +1,211 @@ +# Coroutine Optimization 历史跟踪（Pre-RP-001） + +## 背景 + +本文件整合自旧 `local-plan/todos/coroutine/*.md`。这些材料属于更早期的计划基线，记录了当时已经完成的第一轮实现、 +仍待收口的后续任务、风险和验收标准，但没有与之配套的 durable trace。 + +## 来源文档 + +- `local-plan/todos/coroutine/01-core-semantics.md` +- `local-plan/todos/coroutine/02-core-control-and-observability.md` +- `local-plan/todos/coroutine/03-godot-runtime-integration.md` +- `local-plan/todos/coroutine/04-tests-and-regressions.md` +- `local-plan/todos/coroutine/05-docs-and-migration.md` + +## 历史阶段基线 + +- 当时的整体判断：协程体系已经完成第一轮实现、基础回归和主路径文档同步，后续任务主要是围绕语义一致性、 + 宿主基础设施化、运行时回归覆盖和迁移说明收口 +- 该阶段没有留下独立 trace，因此下述内容应视为“早期计划与状态快照整合稿”，而不是逐日执行日志 + +## Phase 1：Core Semantics + +### 已有基础 + +- `CoroutineScheduler` 已支持 `realtimeTimeSource` +- 已新增 `CoroutineExecutionStage` +- `WaitForSecondsRealtime` 已优先使用真实时间源 +- `WaitForFixedUpdate` / `WaitForEndOfFrame` 已只在匹配阶段推进 + +### 目标 + +- 继续让 Core API 的名字和真实行为完全一致 +- 降低不同宿主对同一等待指令的理解偏差 + +### 后续必做项 + +- 评估 `Delay` 与 `WaitForSecondsScaled` 是否需要长期并存 +- 评估 `WaitForNextFrame` 与 `WaitOneFrame` 的命名差异是否值得保留 +- 为阶段型等待补更多跨宿主说明与样例 +- 审视 `WaitForCoroutine` 在父子调度器不同阶段时的语义 + +### 可选增强 + +- 为等待指令补统一的语义类别元数据 +- 支持宿主自定义阶段映射 + +### 风险与验收 + +- 风险：阶段等待在旧调用路径中可能表现为“以前能过、现在会一直等” +- 风险：文档与示例若不同步强调阶段前提，会放大兼容性误解 +- 验收标准：等待指令名称不再过度承诺，Core 文档能清楚解释时间与阶段语义 + +### 当时状态 + +- 已完成第一轮实现与回归测试 +- 下一步原计划：继续审视其他等待指令的命名与边界 + +## Phase 2：Core Control And Observability + +### 已有基础 + +- 调度器已新增 `CoroutineCompletionStatus` +- 已新增 `WaitForCompletionAsync(...)` +- 已新增 `TryGetCompletionStatus(...)` +- 已新增 `TryGetSnapshot(...)` +- 已新增 `GetActiveSnapshots()` +- 已新增 `OnCoroutineFinished` + +### 目标 + +- 让协程不仅能运行，还能稳定接入业务控制、调试和诊断链路 + +### 后续必做项 + +- 评估是否需要完成历史的上限或清理策略 +- 为快照补更多可观测字段时保持分配与遍历成本可控 +- 审查取消、终止、异常三种完成路径的外部可见语义 +- 评估是否需要暴露最后异常查询 API + +### 可选增强 + +- 编辑器或调试面板中的协程列表 +- 导出运行中协程报告 + +### 风险与验收 + +- 风险：完成历史无限增长会带来内存累积风险 +- 风险：同步完成事件必须保持主线程安全假设 +- 验收标准：业务代码可以等待、查询并区分协程最终状态；运行时诊断不需要反射或私有字段访问 + +### 当时状态 + +- 第一版完成状态与快照 API 已落地 +- 下一步原计划：评估历史清理策略和异常可观测性 + +## Phase 3：Godot Runtime Integration + +### 已有基础 + +- `Timing` 已为各段提供缩放时间源与真实时间源 +- `PhysicsProcess` / `DeferredProcess` 已与阶段语义对齐 +- 已新增 `RunOwnedCoroutine(...)` 与 `Node.RunCoroutine(...)` +- 节点退树时已终止归属协程 +- 已新增节点归属数量和句柄快照查询 + +### 目标 + +- 把 Godot 协程从“可运行”提升到“宿主级基础设施” + +### 后续必做项 + +- 验证节点归属协程在复杂场景切换中的行为 +- 评估是否需要为 `SceneTree` 或页面级作用域提供批量清理 API +- 评估是否要把 `ProcessIgnorePause` 独立暴露更多调试指标 +- 评估节点退出与 `queue_free` 之间的行为是否还需更早终止 + +### 可选增强 + +- 编辑器内协程调试面板 +- 与 Pause 系统的更细粒度联动 + +### 风险与验收 + +- 风险：Godot 线程限制要求所有宿主回调保持主线程驱动 +- 风险：节点归属逻辑需要持续验证信号解绑是否完整 +- 验收标准：节点归属协程在退树时不再泄漏，`WaitForFixedUpdate` 与 `WaitForEndOfFrame` 在 Godot 中语义真实 + +### 当时状态 + +- 第一版宿主接入已落地，并补充了基础时间源测试 +- 下一步原计划：增加更贴近运行时的集成测试 + +## Phase 4：Tests And Regressions + +### 已有基础 + +- 已补充 Core 协程增强测试 +- 已补充 Godot 时间源测试项目 + +### 目标 + +- 为后续协程能力扩展提供稳定回归网 + +### 后续必做项 + +- 增加 Godot 运行时级测试，覆盖节点归属、退树、暂停和各 segment 差异 +- 补异常传播、完成历史与快照字段的更多边界测试 +- 评估是否需要把 `GFramework.Godot.Tests` 接入解决方案级测试流 + +### 可选增强 + +- 文档样例 smoke test +- 基准测试或分配回归测试 + +### 风险与验收 + +- 风险：Godot 运行时测试可能需要额外的测试宿主或场景搭建 +- 风险：解决方案外测试项目容易被遗漏 +- 验收标准：Core 与 Godot 两侧关键协程行为都具备自动化回归；新增阶段和生命周期语义有明确测试覆盖 + +### 当时状态 + +- `dotnet test GFramework.Core.Tests -c Release --filter "FullyQualifiedName~Coroutine"` 已通过 +- `dotnet test GFramework.Godot.Tests/GFramework.Godot.Tests.csproj -c Release` 已通过 +- 下一步原计划：规划 Godot 集成测试宿主 + +## Phase 5：Docs And Migration + +### 已有基础 + +- 已更新 `docs/zh-CN/core/coroutine.md` +- 已更新 `docs/zh-CN/godot/coroutine.md` +- 已更新 `docs/zh-CN/tutorials/coroutine-tutorial.md` + +### 已修正重点 + +- 时间语义与阶段语义说明 +- 节点归属协程入口 +- `StartCoroutine()/StopCoroutine()` 旧示例误导 + +### 目标 + +- 让用户看到的主文档与当前实现保持一致 + +### 后续必做项 + +- 继续扫描仓库中其他 `StartCoroutine()/StopCoroutine()` 文档残留 +- 为迁移场景补“旧示例到新入口”的对照说明 +- 为 `WaitForFixedUpdate` / `WaitForEndOfFrame` 的宿主前提补更多页面说明 + +### 可选增强 + +- 增加 FAQ 和排障章节 +- 增加 Godot 场景级最佳实践示例 + +### 风险与验收 + +- 风险：老文档残留会继续制造错误接入路径 +- 验收标准：用户按主文档示例能直接跑通当前 API，旧接口误导在主路径文档中被清理 + +### 当时状态 + +- 主文档与教程已对齐当前实现 +- 下一步原计划：继续清理其他文档残留并补迁移说明 + +## 历史结论 + +- 旧 `local-plan` 记录的不是“待从零开始”的需求池，而是“第一轮实现已完成后仍待收口的 follow-up backlog” +- 由于当时没有同步留下 trace，后续恢复时不应把本文件视作完整执行历史；真正要继续推进时，应基于 active tracking + 重新选择一个最小切入点，并补回当轮 trace 与验证记录 diff --git a/ai-plan/public/coroutine-optimization/archive/traces/coroutine-optimization-history-pre-rp001.md b/ai-plan/public/coroutine-optimization/archive/traces/coroutine-optimization-history-pre-rp001.md new file mode 100644 index 00000000..e231bc34 --- /dev/null +++ b/ai-plan/public/coroutine-optimization/archive/traces/coroutine-optimization-history-pre-rp001.md @@ -0,0 +1,40 @@ +# Coroutine Optimization 历史追踪（Pre-RP-001） + +## 说明 + +旧 `local-plan/` 只保留了五份 coroutine todo，没有逐日 trace。本文件是基于这些早期计划文档整理出的历史追踪基线， +用于说明当时已经完成的第一轮工作、仍然打开的 follow-up 面，以及哪些结论属于“由 todo 推导出的恢复信息”。 + +## 2026-04-19 + +### 阶段：早期 coroutine 计划基线补录（RP-001） + +- 复核 `local-plan/todos/coroutine/` 后确认，共存在 `5` 份主题文档，覆盖： + - Core semantics + - Core control and observability + - Godot runtime integration + - Tests and regressions + - Docs and migration +- 这些文档都明确指向同一个状态：第一轮 coroutine 语义、宿主接入、基础测试和主路径文档已经完成，后续任务主要是补收口 +- 从文档文字可推导出的已完成能力包括： + - `CoroutineScheduler` 已支持真实时间源 + - `CoroutineExecutionStage` 与阶段型等待已落地 + - 完成状态、等待完成、快照查询和完成事件 API 已落地 + - Godot 的分段时间源、节点归属协程和退树终止语义已落地 + - `docs/zh-CN` 下的 coroutine 主文档与教程已完成一轮纠偏 +- 从文档文字可推导出的未收口面包括： + - 命名与真实行为的一致性仍需继续审视 + - 完成历史清理策略、异常可观测性与更多快照字段仍待评估 + - Godot 复杂场景切换、暂停、`queue_free` 等行为仍需更强验证 + - 更贴近运行时的集成测试与迁移对照文档仍待补齐 +- 已显式记录信息缺口： + - 没有原始执行 trace + - 没有与每个阶段一一对应的完整验证日志 + - 没有可直接还原当时提交边界的恢复点编号 +- 因此，本轮迁移不伪造“已执行的逐步流水”，只把早期计划中可稳定恢复的结论提炼为 archive 基线 + +### 后续恢复约束 + +1. 若继续 coroutine 主题，应把本文件当作“早期计划背景”，而不是完整实现日志 +2. 新一轮推进时必须重新建立当轮 trace、验证命令和恢复点编号 +3. 如果需要更强历史精度，只能再从 Git 历史、测试记录或代码差异中补证，不能把旧 todo 当作完整 trace 使用 diff --git a/ai-plan/public/coroutine-optimization/todos/coroutine-optimization-tracking.md b/ai-plan/public/coroutine-optimization/todos/coroutine-optimization-tracking.md new file mode 100644 index 00000000..17a0cdd7 --- /dev/null +++ b/ai-plan/public/coroutine-optimization/todos/coroutine-optimization-tracking.md @@ -0,0 +1,53 @@ +# Coroutine Optimization 跟踪 + +## 目标 + +继续以“先收敛语义一致性，再补宿主验证和迁移文档”为原则推进当前协程体系，避免 Core 与 Godot 两侧 API 名称、 +阶段语义、可观测性和文档入口再次发生漂移。 + +## 当前恢复点 + +- 恢复点编号：`COROUTINE-OPTIMIZATION-RP-001` +- 当前阶段：`Phase 1` +- 当前焦点： + - 已将 worktree-root 遗留的 `local-plan/` 迁入 `ai-plan/public/coroutine-optimization/`，active 入口只保留当前恢复信息 + - 基于早期计划中已经完成的第一轮实现，重新收敛后续切入点，避免把语义命名、宿主集成、测试扩面和文档清理混成一次大任务 + - 明确记录“旧计划没有 durable trace，只有 todo 基线”，后续恢复时先读 active 入口，再按需展开 archive + +## 当前状态摘要 + +- Core 协程第一轮语义收拢已完成，包括真实时间源、执行阶段与阶段型等待的基础行为调整 +- 调度器第一版控制与可观测能力已落地，包括完成状态、等待完成、快照查询和完成事件 +- Godot 宿主第一版接入已落地，包括分段时间源、节点归属协程入口与退树终止语义 +- Core 与 Godot 两侧已经具备一轮基础测试与文档更新，但更贴近运行时的集成验证、兼容性说明和迁移对照仍未收口 + +## 当前活跃事实 + +- 本主题的详细历史不是从已有 trace 迁入，而是由旧 `local-plan/todos/coroutine/*.md` 整合出的计划基线 +- `RP-001` 的详细工作流拆分、验收标准和缺失 trace 说明已归档到主题内 `archive/` +- 当前工作树分支 `feat/coroutine-optimization` 已在 `ai-plan/public/README.md` 建立 topic 映射 + +## 当前风险 + +- 语义兼容性风险：`Delay`、`WaitForSecondsScaled`、`WaitForNextFrame`、`WaitOneFrame` 等命名与行为若继续调整，可能影响既有调用认知 + - 缓解措施：下一轮只先挑一个语义面收敛，并同步补足迁移说明与宿主前提文档 +- 宿主验证缺口风险：Godot 节点归属、退树、暂停与各 segment 差异仍缺少更贴近运行时的自动化回归 + - 缓解措施：优先规划 Godot 集成测试宿主，再决定是否扩展更多运行时诊断 API +- 历史信息稀疏风险：旧计划没有同步保留当时的执行 trace 与完整验证记录 + - 缓解措施：active 文档只保留当前结论；需要历史语义时回看 archive，并明确哪些内容是从早期 todo 推导出的基线 + +## 活跃文档 + +- 历史跟踪归档：[coroutine-optimization-history-pre-rp001.md](../archive/todos/coroutine-optimization-history-pre-rp001.md) +- 历史 trace 归档：[coroutine-optimization-history-pre-rp001.md](../archive/traces/coroutine-optimization-history-pre-rp001.md) + +## 验证说明 + +- 旧 `local-plan` 的五份 coroutine todo 已整合进主题内历史归档，不再作为 worktree-root durable recovery 入口保留 +- active 跟踪文件只保留当前恢复点、活跃事实、风险与下一步，避免把更早期计划直接平移成新的追加式日志 + +## 下一步 + +1. 若继续该主题，先在 `Core Semantics`、`Control And Observability`、`Godot Runtime Integration`、`Tests And Regressions`、`Docs And Migration` 中只选一个切入点推进 +2. 若优先补验证，先规划 Godot 集成测试宿主与节点归属/退树/暂停场景，再扩运行时诊断 API +3. 若优先补文档与迁移说明，先清理其余 `StartCoroutine()/StopCoroutine()` 残留，再为阶段等待和新入口补统一对照说明 diff --git a/ai-plan/public/coroutine-optimization/traces/coroutine-optimization-trace.md b/ai-plan/public/coroutine-optimization/traces/coroutine-optimization-trace.md new file mode 100644 index 00000000..752c98f3 --- /dev/null +++ b/ai-plan/public/coroutine-optimization/traces/coroutine-optimization-trace.md @@ -0,0 +1,34 @@ +# Coroutine Optimization 追踪 + +## 2026-04-19 + +### 阶段：legacy local-plan 迁移建档（RP-001） + +- 复核当前工作树后确认：`local-plan/` 仅保存 coroutine 主题的早期 todo 基线，共 `5` 份分阶段文档，没有独立 trace +- 按 `ai-plan` 治理规则建立 `ai-plan/public/coroutine-optimization/` 主题目录，并补齐： + - `todos/` + - `traces/` + - `archive/todos/` + - `archive/traces/` +- 将旧 `local-plan` 中分散的五个阶段计划整合为主题内历史跟踪归档，避免后续恢复仍依赖 worktree-root 私有目录 +- 因旧计划没有 durable trace，本次额外补写一份“基于早期 todo 基线整理出的历史 trace”，显式记录信息缺口与推导边界 +- 新建精简版 active tracking / trace 入口，并在 `ai-plan/public/README.md` 中建立 + `feat/coroutine-optimization` -> `coroutine-optimization` 的 worktree 映射 +- 删除旧 `local-plan` 目录，确保后续 `boot` 只从 `ai-plan/public/coroutine-optimization/` 进入 +- 额外完成验证： + - `find ai-plan/public/coroutine-optimization -maxdepth 3 -type f | sort` + - `test ! -e local-plan` + - `dotnet build GFramework.Core.Abstractions/GFramework.Core.Abstractions.csproj -c Release -p:RestoreFallbackFolders=` + +### Archive Context + +- 历史跟踪归档： + - `ai-plan/public/coroutine-optimization/archive/todos/coroutine-optimization-history-pre-rp001.md` +- 历史 trace 归档： + - `ai-plan/public/coroutine-optimization/archive/traces/coroutine-optimization-history-pre-rp001.md` + +### 下一步 + +1. 后续若继续 coroutine 主题，只从 `ai-plan/public/coroutine-optimization/` 进入，不再恢复 `local-plan/` +2. 下一轮只选择一个主切入点推进，避免语义、宿主、测试和文档扩面同时发生 +3. 若 active 入口后续积累多轮已完成且已验证阶段，再按同一模式迁入该主题自己的 `archive/`