docs: sync rendering pass execution docs

docs/plan/API文档实时同步任务池_2026-04-03.md

@@ -0,0 +1,248 @@
+# API 文档实时同步任务池（2026-04-03，第二轮）
+
+## 文档定位
+
+这份任务池接替已归档的第一轮计划：
+
+- `docs/plan/used/API文档实时同步任务池_2026-04-03_第一轮归档.md`
+
+第一轮已经解决的重点是：
+
+- canonical 目录结构收口
+- 历史缺页补齐
+- 第一轮大规模内容重写
+
+本轮重点不再是“补结构”，而是：
+
+- 重新对照当前工作树源码与测试
+- 清理最近重构后重新出现的内容级失配
+- 继续维护一份适合多人并行认领的增量同步清单
+
+## 当前复核快照
+
+- 最近一次结构审计时间：`2026-04-03 15:07:08`
+- 审计命令：`python -B docs/api/_tools/audit_api_docs.py`
+- 当前结果：
+  - `Public headers: 244`
+  - `Editor source headers: 124`
+  - `Invalid header refs: 0`
+  - `Invalid source refs: 0`
+  - `Broken .md links: 0`
+  - `Stale canonical doc tokens: 0`
+  - `Stale editor doc tokens: 0`
+  - `Stale editor canonical pages: 0`
+
+这说明当前结构层面已经恢复全绿；本轮后续工作以内容级持续同步为主。
+
+## 认领规则
+
+- 一次只认领 `1` 个任务块。
+- 先把 `状态` 改成 `DOING`，再写 `认领人`。
+- 只能改自己任务块的 `写入范围`。
+- 所有改动都必须以“当前源码 + 当前测试 + 当前真实调用链”为依据，不允许按旧文档续写旧行为。
+- 如果清理了过期 API 页面，必须同时清理交叉链接。
+
+## 任务池
+
+## T01 Editor / Viewport 渲染计划与宿主流程内容同步
+
+- 状态: `DONE`
+- 认领人: `Codex`
+- 优先级: `P0`
+- 写入范围:
+  - `docs/api/XCEngine/Editor/Viewport/SceneViewportRenderPlan/**`
+  - `docs/api/XCEngine/Editor/Viewport/ViewportHostRenderFlowUtils/**`
+  - `docs/api/XCEngine/Editor/Viewport/ViewportHostService/**`
+  - 必要时 `docs/api/XCEngine/Editor/Viewport/IViewportHostService/**`
+- 主要源码依据:
+  - `editor/src/Viewport/SceneViewportRenderPlan.h`
+  - `editor/src/Viewport/ViewportHostRenderFlowUtils.h`
+  - `editor/src/Viewport/ViewportHostService.h`
+  - `tests/editor/test_viewport_render_flow_utils.cpp`
+- 已关闭问题:
+  - 旧文档仍把 Scene View 当前主路径写成 builtin post-process 主导
+  - 没写清 grid / selection outline 现在已转为显式 `postScenePasses`
+  - 没写清 overlay pass 是 `editorOverlayFrameData + transientOverlayFrameData` 合并后再创建
+  - 没写清 `Scene object id shader view is unavailable` 是局部降级警告，不是整帧失败
+- 完成记录:
+  - 已重写 `SceneViewportRenderPlan.md`、`BuildSceneViewportRenderPlan.md`、`ApplySceneViewportRenderPlan.md`
+  - 已同步 `ViewportHostRenderFlowUtils.md`、`ViewportHostService.md`、`RenderRequestedViewports.md`
+  - 已清理 `IViewportHostService` 中残留的旧表述
+
+## T02 Core / Asset 缓存接口改名与语义重构同步
+
+- 状态: `DONE`
+- 认领人: `Codex`
+- 优先级: `P0`
+- 写入范围:
+  - `docs/api/XCEngine/Core/Asset/ResourceManager/**`
+  - `docs/api/XCEngine/Core/Asset/AssetImportService/**`
+  - `docs/api/XCEngine/Core/Asset/ProjectAssetIndex/**`
+  - 必要时 `docs/api/XCEngine/Core/Asset/Asset.md`
+  - 必要时 `docs/api/XCEngine/Core/Asset/ArtifactFormats/**`
+- 主要源码依据:
+  - `engine/include/XCEngine/Core/Asset/ResourceManager.h`
+  - `engine/src/Core/Asset/ResourceManager.cpp`
+  - `engine/include/XCEngine/Core/Asset/AssetImportService.h`
+  - `engine/src/Core/Asset/AssetImportService.cpp`
+  - `engine/include/XCEngine/Core/Asset/ProjectAssetIndex.h`
+  - `engine/src/Core/Asset/ProjectAssetIndex.cpp`
+  - `tests/core/Asset/test_resource_manager.cpp`
+- 已关闭问题:
+  - `RefreshAssetDatabase` 已经不存在，但旧文档仍在沿用
+  - `RefreshProjectAssets` / `RebuildProjectAssetCache` / `GetProjectLibraryRoot` 缺页或未写清
+  - `AssetImportService::EnsureArtifact()` 旧文档仍把输出写成 `ResolvedAsset`
+  - `BuildLookupSnapshot()` 旧文档仍按“双 map 出参”描述，而不是 `LookupSnapshot`
+  - `ImportedAsset::runtimeLoadPath` 语义未同步到上层文档
+- 完成记录:
+  - 已删除过期页 `ResourceManager/RefreshAssetDatabase.md`
+  - 已补齐 `RefreshProjectAssets.md`、`RebuildProjectAssetCache.md`、`GetProjectLibraryRoot.md`
+  - 已补齐 `LookupSnapshot.md`、`ImportedAsset.md`、`GetLibraryRoot.md`、`RebuildLibraryCache.md`
+  - 已同步 `Asset.md`、`ArtifactFormats.md`、`ResourceManager/Load.md` 的 `runtimeLoadPath` 口径
+
+## T03 Scripting / Mono 托管销毁入口同步
+
+- 状态: `DONE`
+- 认领人: `Codex`
+- 优先级: `P1`
+- 写入范围:
+  - `docs/api/XCEngine/Scripting/Mono/MonoScriptRuntime/**`
+- 主要源码依据:
+  - `engine/include/XCEngine/Scripting/Mono/MonoScriptRuntime.h`
+  - `engine/src/Scripting/Mono/MonoScriptRuntime.cpp`
+  - `tests/scripting/test_mono_script_runtime.cpp`
+- 已关闭问题:
+  - `DestroyManagedObject(MonoObject*)` 已进入头文件与测试，但文档树没有对应页面
+  - `MonoScriptRuntime.md` 没写清 `Object.Destroy(...)` 会回落到原生对象 / 组件销毁
+- 完成记录:
+  - 已新增 `DestroyManagedObject.md`
+  - 已更新 `MonoScriptRuntime.md` 的 internal call 说明与方法总表
+
+## T04 Cross-Module / 教程层与模块总览口径持续复核
+
+- 状态: `DONE`
+- 认领人: `Codex`
+- 优先级: `P2`
+- 写入范围:
+  - `docs/api/_guides/**`
+  - `docs/api/XCEngine/*/*.md`
+  - 仅限与本轮已确认 API 变更直接相关的总览页
+- 任务目标:
+  - 继续检查教程页、模块总览页是否仍在传播旧心智模型
+  - 尤其关注：
+    - Scene View 仍被写成 builtin post-process 主导
+    - 资源导入链仍被写成 `artifactMainPath` / `RefreshAssetDatabase` 时代的口径
+    - 托管对象销毁路径未在教程层被解释
+- 产出要求:
+  - 只修正已确认失配的 guide / overview 页面
+  - 不做与当前源码无关的泛化扩写
+
+## T05 增量变更监控 / 新一轮差异发现
+
+- 状态: `OPEN`
+- 认领人: ``
+- 优先级: `P2`
+- 写入范围:
+  - 只读检查 `engine/include/**`、`engine/src/**`、`editor/src/**`、`tests/**`
+  - 必要时只向本任务池追加新任务块
+- 任务目标:
+  - 继续结合工作树最新改动，找出新的“源码已变但文档还没跟上”的内容级失配
+  - 优先检查：
+    - 最近改动过的 public headers
+    - 最近改动过的 Editor source headers
+    - 最近新增或更新过的测试
+- 产出要求:
+  - 只记录已确认的问题
+  - 每条新任务都要写明：
+    - 受影响文档
+    - 主要源码依据
+    - 真实失配点
+    - 建议写入范围
+
+## T06 Rendering / Camera request、Passes 与执行链旧口径清理
+
+- 状态: `DONE`
+- 认领人: `Codex`
+- 优先级: `P1`
+- 写入范围:
+  - `docs/api/XCEngine/Rendering/CameraRenderRequest/**`
+  - `docs/api/XCEngine/Rendering/CameraRenderer/**`
+  - `docs/api/XCEngine/Rendering/Passes/**`
+  - `docs/api/XCEngine/Rendering/ObjectIdPass/**`
+  - `docs/api/XCEngine/Rendering/RenderPipeline/**`
+  - `docs/api/XCEngine/Rendering/SceneRenderer/**`
+  - `docs/api/XCEngine/Editor/Viewport/SceneViewportRenderPlan/**`
+  - 必要时 `docs/api/XCEngine/XCEngine.md`
+  - 必要时 `docs/api/_tools/audit_api_docs.py`
+- 主要源码依据:
+  - `engine/include/XCEngine/Rendering/CameraRenderRequest.h`
+  - `engine/include/XCEngine/Rendering/CameraRenderer.h`
+  - `engine/include/XCEngine/Rendering/Passes/BuiltinObjectIdPass.h`
+  - `engine/include/XCEngine/Rendering/Passes/BuiltinObjectIdOutlinePass.h`
+  - `engine/include/XCEngine/Rendering/Passes/BuiltinInfiniteGridPass.h`
+  - `engine/include/XCEngine/Rendering/ObjectIdPass.h`
+  - `engine/include/XCEngine/Rendering/RenderPipeline.h`
+  - `engine/include/XCEngine/Rendering/SceneRenderer.h`
+  - `engine/src/Rendering/CameraRenderer.cpp`
+  - `engine/src/Rendering/SceneRenderer.cpp`
+  - `tests/Rendering/unit/test_camera_scene_renderer.cpp`
+  - `editor/src/Viewport/SceneViewportRenderPlan.h`
+  - `editor/src/Viewport/Passes/SceneViewportGridPass.cpp`
+  - `editor/src/Viewport/Passes/SceneViewportSelectionOutlinePass.cpp`
+  - `editor/src/Viewport/ViewportHostRenderFlowUtils.h`
+  - `tests/Editor/test_viewport_render_flow_utils.cpp`
+  - `tests/Editor/test_scene_viewport_overlay_renderer.cpp`
+- 已关闭问题:
+  - `CameraRenderRequest.md` 仍描述已删除的 `builtinPostProcess` 子请求
+  - 页面仍链接到不存在的 `BuiltinPostProcessRequest/BuiltinPostProcessRequest.md`
+  - Scene View 已改为通过 `postScenePasses` / `overlayPasses` 写回 request，但该页口径未同步
+  - `CameraRenderer.md` 仍保留已删除的 `m_builtinPostProcessBuilder` 历史口径
+  - `Passes.md` 的典型链路只写了 `postScenePasses`，遗漏当前 `overlayPasses` 组装路径
+  - `Rendering/Passes` 下仍残留已删除的 `BuiltinPostProcessPassPlan` / `BuiltinPostProcessPassSequenceBuilder` 页面
+  - `BuiltinObjectIdPass`、`BuiltinInfiniteGridPass` 多个公开入口缺页
+  - `ObjectIdPass.md`、`RenderPipeline.md`、`SceneRenderer.md` 与顶层 `XCEngine.md` 仍在传播 builtin-post-process 心智模型
+- 完成记录:
+  - 已重写 `CameraRenderRequest.md`
+  - 已清理 `2` 个失效 `.md` 链接
+  - 已同步 `CameraRenderer.md` 与 `Passes.md` 的当前执行链路表述
+  - 已删除 `BuiltinPostProcessPassPlan.md`、`BuiltinPostProcessPassSequenceBuilder.md`
+- 已补齐 `BuiltinObjectIdPass` / `BuiltinInfiniteGridPass` 缺失页面，并补充 `SceneViewportRenderPlan` 下 grid / selection outline pass factory 页面
+- 已同步 `ObjectIdPass.md`、`RenderPipeline.md`、`SceneRenderer.md` 与 `XCEngine.md` 的当前口径
+- 已补充 Rendering guide、`CameraRenderer::Render` 与 `ViewportHostService::RenderRequestedViewports` 的 request 级 pass 注入说明
+- 已为 `builtinPostProcess` / `BuiltinPostProcessRequest` / `m_builtinPostProcessBuilder` 增加 canonical 过期符号审计
+- 已复跑结构审计并确认 `Broken .md links: 0`
+
+## T07 Editor / Core `EditorConsoleSink` 生命周期说明同步
+
+- 状态: `DONE`
+- 认领人: `Codex`
+- 优先级: `P1`
+- 写入范围:
+  - `docs/api/XCEngine/Editor/Core/EditorConsoleSink/**`
+  - 必要时 `docs/api/XCEngine/Editor/Managers/Managers.md`
+  - 必要时 `docs/api/_tools/audit_api_docs.py`
+- 主要源码依据:
+  - `editor/src/Core/EditorConsoleSink.h`
+  - `editor/src/Core/EditorConsoleSink.cpp`
+  - `editor/src/panels/ConsolePanel.cpp`
+  - `editor/src/Core/EditorLoggingSetup.h`
+  - `tests/Editor/test_editor_console_sink.cpp`
+- 已关闭问题:
+  - `EditorConsoleSink::GetInstance()` 旧文档仍把它写成会返回 fallback 实例
+  - 相关 overview 页面没有写清活动 sink 销毁后会返回 `nullptr`
+  - 审计脚本此前无法自动拦截这类旧生命周期表述
+- 完成记录:
+  - 已同步 `EditorConsoleSink.md`、`GetInstance.md`、`Destructor.md`
+  - 已同步 `Managers.md` 中对控制台 sink 生命周期的引用口径
+  - 已为 `fallback 实例` 与“不会返回空指针”旧表述增加定向审计
+
+## 当前结论
+
+- 本轮已经关掉五组明确的内容级失配：
+  - `Viewport` 渲染计划与宿主流程
+  - `Core/Asset` 缓存接口与导入服务语义
+  - `MonoScriptRuntime` 托管销毁入口
+  - `Rendering` 相机请求、Passes 与单相机执行链旧口径
+  - `EditorConsoleSink` 生命周期与空指针返回语义
+- 当前结构审计为全绿。
+- 当前仍建议保留 `T04` 与 `T05` 作为持续性并行入口，用来承接你后续重构带来的新文档漂移。

docs/plan/C#脚本模块下一阶段计划.md

@@ -259,7 +259,10 @@ C# 脚本模块已经完成了第一阶段的核心闭环，不再是“从 0
 - 已新增运行时回归用例，验证层级查找、自身命中、组件销毁、GameObject 销毁。
 - 已通过 `MonoScriptRuntimeTest.*` 与 `ProjectScriptAssemblyTest.*` 相关整组验证。
 
-- 下一步建议继续做第二批 Unity API 对齐：
 - 已完成第二步第一小项：`GetComponents<T>()`
-- 下一步候选：`Object.Instantiate`
-- 下一步候选：`tag / CompareTag / layer`
+- 已完成第二步第二小项：`tag / CompareTag / layer`
+- `GameObject`、`Component` 与 `MonoBehaviour` 已提供 Unity 风格 `tag`、`layer`、`CompareTag(string)` 入口。
+- native `GameObject`、场景查找、序列化与反序列化已同步收口，`FindGameObjectWithTag` / `FindGameObjectsWithTag` 已改为基于 tag。
+- 已新增 `TagLayerProbe` 与对应 C++ / Mono 回归测试，覆盖默认 tag、layer 裁剪、脚本侧读写与场景 roundtrip。
+- 相关定向测试全部通过；完整 `MonoScriptRuntimeTest.*:ProjectScriptAssemblyTest.*` 输出全绿，当前仍存在历史性的 `exit code 3` 异常，需后续单独跟踪。
+- 下一步建议继续做第三小项：`Object.Instantiate`