Integrate editor authoring, localization, and runtime debugging

.agents/lessons/L-20261017-01-local-edit-global-indices.md

@@ -0,0 +1,15 @@
+# 局部集合删除也要重算全局位置快照
+
+状态：confirmed
+日期：2026-10-17
+来源：F-20261015-02-editor-authoring-workspace / P3
+
+现象：分支按稳定选项 ID 重排后，删除一个在全局边列表中间的选项，再 Undo，会被 BranchEdit 的预期状态校验拒绝；删除末项的测试却通过。
+
+根因：分支编辑保留局部出边及其全局插入索引。删除一条边后，其后的全局索引前移，而预先生成的 After 快照仍保存旧索引，导致实际状态与历史预期不一致。稳定对象 ID 不能替代集合顺序快照的一致性。
+
+正确做法：生成 After 时，每条保留边的全局位置减去在其前面删除的边数；Undo 使用 Before 中的原始全局位置恢复，其他节点的边保持原顺序。预期校验必须在所有写操作之前完成。
+
+验证：p3-middle-edge-regression.trx 的 Choice/Condition 两用例稳定失败；修正后 p3-middle-edge-fixed.trx 的两种分支与真实控件用例共 3 项通过。用例从三个出口中删除原第二条边，再撤销两步并比较完整作者快照，不只比较局部连线目标。
+
+适用范围：跨多个集合的局部增删、索引重映射、批量历史和投影同步。不能只测试尾部删除，也不能通过放宽状态校验掩盖错误索引。

.agents/lessons/L-20261017-02-tolerant-reader-authoring.md

@@ -0,0 +1,15 @@
+# 容错读取不等于可以安全重写
+
+状态：confirmed
+日期：2026-10-17
+来源：F-20261015-02-editor-authoring-workspace / P4a
+
+现象：AssetMetaCodec 对合法 JSON 中无法类型化的可选字段会回退到默认 DTO；读取仍能取得 ID 和 path，但直接序列化回去会丢掉无效字段及原始扩展内容。
+
+根因：运行时读取的容错策略与作者写入的无损要求不同。文件改名/复制即使只想改 path，也会经过完整 metadata 重写。
+
+正确做法：作者操作先用相同 DTO 和 JSON 配置进行严格类型化校验；失败时拒绝整个文件计划，保留原始资源和 sidecar，不将默认 DTO 当可无损写回的来源。合法 metadata 继续通过 codec 保留 Gallery 和 extension data，不修改 Core 读端既有策略。
+
+验证：ProjectFileTransactionTests.InvalidOptionalMetadataCannotBeSilentlyReplacedByAuthoring 使用 gallery 为字符串且包含 custom 对象的真实 sidecar，改名返回失败，源文件、原 metadata 字节不变，目标不存在。P4a Shared 回归已通过。
+
+适用范围：共享容错 codec 被 Editor 作者写入、迁移或导入工具复用时。禁止仅凭 Deserialize 返回对象就声称数据可无损往返；不能为通过测试静默删掉原字段。

.agents/lessons/L-20261017-03-project-watcher-owner.md

@@ -0,0 +1,15 @@
+# 项目文件监听器必须持有所属项目的身份
+
+状态：confirmed
+日期：2026-10-17
+来源：F-20261015-02-editor-authoring-workspace / P4b
+
+现象：第一轮 P4b 测试在项目关闭后被 FileSystemWatcher 回调中的 NullReferenceException 终止，日志为 p4b-initial.log/trx。回调通过 Index.Root 再读取全局 IProjectService.Current.RootPath，而关闭流程已经清空 Current。
+
+根因：项目 scope 及其后台回调的释放晚于全局当前项目切换。延迟事件不能假设全局 Current 仍是创建监听器的项目；相同问题还可能把旧项目事件投递给新项目。
+
+正确做法：项目 index 在创建时捕获固定根路径；回调先检查 disposed，只使用该固定路径。投递到 UI 后再次核对当前项目身份和 disposed，再更新列表。停止 watcher/timer 后仍需防范已经排队的回调。
+
+验证：修正后 P4b-cases-fixed 的 13 项包括连续创建/关闭项目和真实挂载的文件面板全部通过，未捕获并吞掉原始 NullReferenceException；测试主机不再退出。
+
+适用范围：项目级 watcher、异步扫描、thumbnail 和延迟刷新。禁止让后台回调通过全局 Current 动态决定它的所属根目录。

.agents/lessons/L-20261017-05-scoped-binding-unsubscribe.md

@@ -0,0 +1,15 @@
+# Scoped binding 的订阅必须只退订一次
+
+状态：confirmed
+日期：2026-10-17
+来源：F-20261015-02-editor-authoring-workspace / P6a
+
+现象：DtoEditorTests 首轮 27/29 通过，移除一个 DTO 后订阅计数为 -1，失败工厂与正常项共享测试 binding 时计数为 0 而非 1；证据 p4b-validation/dto-ui-focused.trx。
+
+根因：字段 FieldEditorContext.Dispose 先从 scoped binding 移除订阅，随后 DtoEditorContext.Dispose 再释放 scoped binding，两条释放路径均无条件向借用 source 退订。普通 CLR event 的重复 remove 看似无害，但拥有自定义事件访问器的宿主可能按订阅计数维护资源。
+
+正确做法：包装器显式记录是否实际订阅 source。最后一个字段订阅移除和包装器 Dispose 统一走幂等 Unsubscribe；只移除自己建立的 source 事件，不释放借用 binding。上下文释放保留异常并继续清理其他字段/控件。
+
+验证：修正后共享聚焦 29/29 通过；重复类型重排、移除、创建失败与窗口卸载均检查订阅数量。新增 release failure 用例继续验证其他项仍被释放。
+
+适用：多层 binding/事件转发包装器、控件 lease、并行存在的多次释放入口。禁止把重复 event remove 无异常当作生命周期正确性的证据。

.agents/lessons/L-20261017-06-listbox-scrollable-tail.md

@@ -0,0 +1,13 @@
+# 可滚动尾部留白必须验证满视口并使用主题公开入口
+
+状态：confirmed
+日期：2026-10-17
+来源：F-20261015-02-editor-authoring-workspace / P5a
+
+现象：短列表背景取消选择测试通过，但完整回归中的长列表断言显示最后一项与视口底部间距为 0，而非预期约 64 DIP。首轮 Editor 140/141 通过，失败为 GroupToolbarBatchesAreSingleHistoryStepsAndSpaceInsertsOneAtCapturedAnchor，当时日志见 phase-5a.md；同名 editor.trx 已被最终成功回归覆盖。
+
+根因与验证：初版通过普通样式设置 ItemsPresenter.Margin，没有在所用 Semi 模板下获得实际尾部留白。该模板将 ListBox.Padding 绑定到 ItemsPresenter.Margin；改用 ListBox.Padding 后，不更换 ItemsPanel、不添加伪条目，超过视口时可滚动到最后一项之后的空白，group-tail-fixed.trx 通过。
+
+正确做法：使用主题公开的 Padding 入口，并在项目实际主题下检查滚动到最大 Offset 后最后容器的相对位置。验证列表应超过 Viewport；短列表天然存在的空白不能证明尾部空间有效。不要为留白移除虚拟化或把假 Entry 放进作者集合。
+
+公开模板参考：https://github.com/irihitech/Semi.Avalonia/blob/main/src/Semi.Avalonia/Controls/ListBox.axaml 。参考源码不代替所安装版本的实际控件测试。适用范围：列表尾部插入区域、背景取消选择、虚拟化列表的 margin/padding 调整。

.agents/lessons/L-20261017-07-observable-batch-compensation.md

@@ -0,0 +1,11 @@
+# 可观察集合批量历史要按实际状态补偿
+
+状态：confirmed
+日期：2026-10-17
+来源：F-20261015-02-editor-authoring-workspace / P5b
+
+发现方式：复核 GroupEntryAuthoringService 的 PresenceEdit/OrderEdit。ObservableCollection 会先修改集合再发通知；观察者抛错时，抛错的当前 Insert/Remove/Move 可能已经生效。只统计“正常返回的操作数”再逆向恢复，会漏掉当前一步，导致历史未追加或游标未移动、内容却已变化。
+
+正确做法：批次开始记录受影响集合的实际顺序与对象身份；异常时对照真实集合恢复缺失项、移除本次新增项并恢复顺序/序号。恢复失败抛 HistoryRepairRequiredException，交由项目历史阻止后续写入。不能捕获异常后静默返回成功，也不能仅依赖 CompositeEdit 补偿已经正常返回的子步骤。
+
+验证入口：EntryBatchFailuresRestoreContentAndHistoryOrRequireRepair，覆盖新增/删除/移动、Undo/Redo 失败时状态与游标，以及恢复再失败时项目 RepairRequired。p5b-failure.trx 的故障注入测试已通过，覆盖全部上述路径；适用于会触发同步通知的集合型历史。

.agents/lessons/L-20261017-08-author-metadata-strict-shape.md

@@ -0,0 +1,11 @@
+# 作者元数据扩展要同步严格 Raw shape
+
+状态：confirmed
+日期：2026-10-17
+来源：F-20261015-02-editor-authoring-workspace / P5c
+
+现象：ProjectVariableDefinition 新增 description 后，面板与内存历史可编辑，但保存测试 3/4：Graph/saveVariables/0/description 报 json.fieldUnknown。新增 CLR/JsonPropertyName 和 Clone 不代表作者写入协议已经接通。
+
+根因：ProjectValidationService 独立严格检查 Raw Graph 声明的字段白名单；作者保存先经过此规则，而非只执行类型化序列化。正确做法是在唯一声明 shape 明确允许新元数据并验证其类型，同时同步中立模型克隆、正式格式说明和保存重开测试。不能绕过保存校验、宽泛允许未知字段或在保存时删掉新字段。
+
+证据：p5c-focused.trx 的 description 失败；修正后 p5c-focused-fixed/final.trx 与完整 611 项回归通过。VariableDescriptionIsOptionalTextAndDoesNotRelaxUnknownFields 覆盖字符串/数字/null，变量面板测试覆盖说明及 UID 保存重开。适用范围：给作者 DTO/Graph/Group/settings 增加由 Editor 写出的正式字段时。

.agents/lessons/L-20261018-01-entry-binding-revival.md

@@ -0,0 +1,13 @@
+# Entry 撤销不能复活旧控件的提交权
+
+状态：candidate
+日期：2026-10-18
+来源：F-20261015-02-editor-authoring-workspace / P5d
+
+迁移审查发现，仅按 Entry 存在性和 type ID 校验旧字段不能区分“当前绑定”与“删除/换类型后又撤销恢复的旧绑定”。稳定 Entry ID 应跨撤销保持，但控件绑定的生命周期不能因此恢复。
+
+实现采用参数表单 Dispose、字段集合成员身份及专属控件 schema generation：条目移除/换类型/页面关闭使现有绑定永久失效；撤销恢复作者数据时重新创建绑定。项目历史只保留稳定 ID 和作者值，不保留页面。禁止用“条目又出现了/类型又相同了”作为恢复旧控件提交权的条件。
+
+EntryBindingsPreserveAuthorJsonAndRejectRemovedAndReplacedSchemas 验证换类型、删除及各自撤销后旧字段提交仍返回 obsolete，当前绑定正常读取作者内容；跨页面挂载测试验证页面关闭后旧表单拒绝提交，项目 Undo/Redo 和保存重开仍有效。p5d-binding-focused.trx 的 4 项均通过；本条是审查发现后的防护回归，未记录修复前失败运行，因此保留 candidate，不宣称先前生产环境已复现。
+
+适用：异步 DTO/字段编辑器、资源选择器、页面重建和撤销恢复。相关规则见 docs/spec/editor-groups.md。

.agents/lessons/L-20261018-02-fixture-service-policy.md

@@ -0,0 +1,15 @@
+# 集成 fixture 不应覆盖要验证的生产服务策略
+
+状态：confirmed
+日期：2026-10-18
+来源：F-20261015-02-editor-authoring-workspace / P5e
+
+现象：GUI 已注册 Authoring 仓库，但 AuthoringDraftsReopenInMountedGroupAndKeepOpaqueValuesThroughEditsCopyUndoAndSave 首次仍在 SerializeEntry 抛 Unknown parameter 'future'。堆栈经 ProjectContentSession.SaveAsync，容易误以为生产 DI 没有生效。
+
+根因：公共 Services() fixture 在 AddEditorServices() 后无条件覆盖 IEditorDocumentRepository，手工 new 默认 Complete 仓库；这个覆盖原本只是为了支持文件故障注入，却改变了所有普通用例的生产策略。
+
+修正：没有故障事务时直接保留生产注册；确需注入故障时仅包装明确 Authoring 的仓库。禁止为了让集成测试通过而全局把 CLI 默认模式改为 Authoring，或让所有测试另行手工拼装“等效”生产策略。
+
+验证：修改 fixture 后同一真实 GUI 草稿保存、重开、字段编辑、Entry/Graph 复制和 Undo/Redo 用例通过；p5e-editor-focused.trx 为修复后 2/2，首次失败堆栈保留在本轮工具输出及 phase-5e 记录。
+
+适用：已有 DI 集成 fixture、新增服务策略、临时 fault decorator、production 注册回归。关联 docs/spec/editor-groups.md 与 phase-5e.md。

.agents/lessons/L-20261018-03-derived-control-theme-key.md

@@ -0,0 +1,17 @@
+# 派生主题控件需验证实际模板入口
+
+状态：confirmed
+日期：2026-10-18
+来源：F-20261015-02-editor-authoring-workspace / P6b
+
+现象：StructuredFieldEditor 继承 Expander，测试直接设置 IsExpanded 后能编辑和保存，但实际 Semi 截图缺少标题和折叠按钮，用户无法从界面展开。已有业务状态和子控件测试全部通过，未覆盖主题模板入口。
+
+根因：自定义派生控件默认使用自身类型作为样式键，而宿主只有标准 Expander 的主题。直接设置属性绕过了缺失的交互模板。
+
+正确做法：复用基类主题时显式覆盖 StyleKeyOverride 为 typeof(Expander)；真实挂载后检查模板内的 ToggleButton 存在，并检查截图。自定义独立皮肤则由宿主提供对应类型的完整主题。
+
+补充：覆盖样式键同时影响类型选择器。首轮完整 Editor 回归 155 通过、1 失败：forms|StructuredFieldEditor 不再匹配，四语文案停在英文默认值。宿主改用 Expander.structured-field 类选择器，并以带 owner 的属性名设置自定义 StyledProperty；需要同时验证主题按钮和本地化刷新。
+
+适用：派生 Expander/Button 等模板控件。禁止仅凭属性赋值后业务结果正确，就声称用户能够触发该功能。
+
+证据：StructuredGroupFormTests 检查实际主题 ToggleButton；p6b-structured-group.png 检查展开/收起入口和字段内容。

.agents/lessons/L-20261018-04-query-scope-disposal.md

@@ -0,0 +1,13 @@
+# 查询上下文须随项目 scope 失效
+
+状态：confirmed
+日期：2026-10-18
+来源：F-20261015-02-editor-authoring-workspace / P6e2b
+
+现象：SceneQueryIsPositionBasedAndSelectionsRejectChangedOrClosedProjects 在 CloseAsync 完成后，旧选择仍能解析 handle，首轮新增回归稳定复现。早期 locator-focused.log 已被后续重跑覆盖；保留用例作为关闭/过期行为的回归，最终结果见 timeline-validation/locator-GalNet.Editor.Tests.trx。
+
+根因：ProjectService 关闭时释放项目 scope，EditorDocumentService 对象仍可能被旧控件或局部变量引用，IsLoaded 不等于项目仍处于活动状态。原查询服务仅检查 IsLoaded 和内容版本，没有自己的释放状态。
+
+正确做法：项目 scope 的查询服务实现幂等 IDisposable，释放时清除分析缓存并推进查询代次；旧选择按捕获代次拒绝解析。查询服务不拥有控件，也不应通过主动卸载其他服务来弥补自己的生命周期。
+
+适用：持有不可变分析快照、选择候选或异步返回结果的项目服务。禁止仅以源对象尚可读取或 IsLoaded=true 作为会话仍有效的证据。新增测试同时验证保存相同内容不换代、作者修改/撤销换代、关闭项目使旧选择失效。

.agents/lessons/L-20261019-01-template-ancestor-type-resolution.md

@@ -0,0 +1,15 @@
+# 延迟模板中的祖先类型需要显式解析
+
+状态：confirmed
+日期：2026-10-19
+来源：F-20261015-02-editor-authoring-workspace / Group 属性编辑器改造
+
+现象：Group 字段 DataTemplate 中的反射绑定 `$parent[forms:SchemaForm].ShowLabels` 可以通过 XAML 编译，但实际挂载时抛出 `Unable to resolve type forms:SchemaForm`，整个参数区无法生成。三个真实 Group 控件测试同时失败，单独 FieldEditorContext 测试通过。
+
+根因：该延迟模板的运行期 ReflectionBinding 类型解析上下文不能解析这段表达式的命名空间别名。构建成功不能证明运行时绑定可解析。
+
+修正：用 `ShowLabels, RelativeSource={RelativeSource AncestorType={x:Type forms:SchemaForm}}`，由 XAML 显式解析类型。修正后五项重点测试以及完整 Editor 181 项回归通过，包含宽窄截图、嵌套对象/列表与 Timeline 挂载。
+
+适用：带命名空间祖先类型的延迟 DataTemplate/ControlTemplate 反射绑定。不要凭编译结果宣称模板可用；需要真实主题挂载、交互与截图。此结论针对已复现表达式，不声称所有 `$parent` 语法都不可用。
+
+证据：features/F-20261015-02-editor-authoring-workspace/phase-group-properties.md；Temp/group-properties/group-properties-focused.trx、GalNet.Editor.Tests.verified.trx。

.agents/lessons/L-20261019-02-timeline-exact-key-frame.md

@@ -0,0 +1,17 @@
+# 曲线采样需覆盖精确关键帧边界
+
+状态：confirmed
+日期：2026-10-19
+来源：F-20261015-02-editor-authoring-workspace / P6e3b
+
+现象：Step 段之后的中间关键帧，采样恰好落在其帧号时仍返回前一键值；第 0 帧、末键及区间中点原测试均通过。内联值曲线的键位置与运行时该时刻值可能不同。
+
+根因：TimelineSampler 查找区间使用 next.Frame < frame，把内部键的精确时刻归给前段。Linear/Hermite 在末端返回下一键值，掩盖了问题；Step 保持前值而暴露错误。
+
+发现与复现：新增 0→10→20 三键测试，首段 Step；Evaluate(9.999)=0，Evaluate(10) 应为 1、实际为 0，基线失败日志和 TRX 为 timeline-validation/inline-curve-step-before-fix.*。修正查找为 <=，精确内部键归入它自己的出段，末键仍由已有末端分支处理。
+
+正确做法：动画/曲线采样回归同时覆盖精确内部键、键前后分数时刻、首末键和不同插值组合；Editor 绘制直接复用中立采样器，不在 UI 加偏移来绕过错误。
+
+适用范围：时间区间归属、阶梯/离散插值、曲线与 Runtime 一致性。禁止仅测试区间中点或末键便宣称边界一致。
+
+关联：features/F-20261015-02-editor-authoring-workspace/phase-6e3.md；docs/spec/editor-groups.md。

.agents/lessons/L-20261019-03-isolated-contract-artifacts.md

@@ -0,0 +1,15 @@
+# 全新隔离源码需补齐固定路径契约产物
+
+状态：confirmed
+日期：2026-10-19
+来源：F-20261015-02-editor-authoring-workspace / P6e3b
+
+现象：在 HEAD 加本轮改动的全新源码快照中，离线 restore 成功，使用 --artifacts-path 构建时 Editor Copy 阶段 MSB3030，缺少 Editor.DefaultContracts/bin/Debug/net10.0/GalNet.Project.Contracts.dll；主工作树同参数构建此前成功。
+
+根因：Editor.csproj 的 Content 固定读取默认 bin 路径，而 --artifacts-path 将项目输出移至独立 artifacts/bin/项目/debug。已有工作树残留的普通 bin 产物掩盖了这一前置条件。Editor 的 Contracts()/Deploy() 测试夹具也按源码树 test/Fixtures/*/bin/Debug/net10.0 定位。
+
+发现方式：inline-curve-isolated-build.log 在全新快照中复现；不修改业务项目文件，将该快照本次构建产物补到它自身预期的默认契约与 fixture bin 位置后，inline-curve-isolated-build-2.log 构建通过。
+
+正确做法：在验证脚本中明确准备此类固定路径前置产物，且必须来自同一源码快照；或另立构建修正任务消除硬编码。不要把主工作树不明版本 DLL 复制过来，也不要把有旧 bin 的 --artifacts-path 构建当作干净构建证据。临时快照包含重复 csproj 时放在忽略目录并在验证后清理，避免架构测试递归扫描测试根目录时误识别重复项目。
+
+适用：全新源码快照、多个输出根、动态 schema 测试夹具；不代表新建 Editor 项目需要用户准备 DLL，Editor 仍自带默认契约。