隔离Direct埋点状态锁并修正分页注释

采集身份与成果编号改用独立纯内存锁，避免业务落盘锁竞争导致漏采补充锁竞争、原用户归属与恢复边界回归测试修正后台分页注释，同步埋点方案与共享决策
2026-09-22 15:51:48 +00:00
parent bc8e25c0e3
commit 069dec7bdd
5 changed files with 164 additions and 23 deletions
@@ -1,6 +1,6 @@
 # 客户端本地埋点与主站入库契约

-Version: 0.30
+Version: 0.31
 Status: 本地采集及上传、入库、成功清理、后台查询已实现并完成本地隔离环境验收；未部署生产
 Date: 2026-09-21
 需求来源：[Game Agent 埋点设计原始方案](./【需求来源】GameAgent埋点设计原始方案-2026-09-05.md)；原始方案与后续已确认决策有差异时，以本文为准。
@@ -262,6 +262,7 @@ Direct 的自动登录刷新重试仍属同一个 run。原生单次调用结束
 - 当前 Direct 的 outputs_changed 与 manifest_requires_sync 要区分；不能给 revision 递增函数加一个无条件事件后就宣称满足语义。
 - Direct 的宿主 file.write 与正式补丁事务使用持锁目标内容比较和本次已提交项目 revision，成功且内容确实变化时记 source=direct、revision_source=agent。运行期间的全局 fingerprint 和写许可本身不证明本 run 改了文件；末尾投影登记不再重复统计工具已经提交的成果，也不将纯登记修复计为新成果。未经过可观察宿主提交的外部/命令行写入不推断事件。
 - Direct run 的 output_change_detected=true 与 revision_id 来自本 run 已确认的宿主成果提交；保存当前内存中最后一个真实成果 revision，不为埋点新增业务文件版本或同步写盘。没有观察到成果、恢复后缺少该证据时为 null，不能推断 false。后续 run 失败不撤销已提交成果事件。
+- Direct 的采集身份与最新成果编号使用独立的纯内存状态，项目 ID 和原 run 身份在执行会话创建时从最终账本冻结；采集不争用业务持久化锁，不因业务写入或 tick 占锁而漏记。内存锁只保护采集状态读写，事件投递在释放锁后进行，不等待磁盘、网络或队列，不向用户报错。恢复仍使用原 run 身份，但不补造此前未保留的成果编号；旧账本缺少 run 元数据时不套用当前用户身份。
 - 宿主文件通道仅对已识别成果类型采集：策划成果目录、UI 目录以及支持的代码/媒体扩展名；私有控制面、隐藏记录、构建缓存和类型未知的文件不据此统计。该口径不承诺观察全部磁盘文件；恢复后的未知成果证据不补填。
 - Design Agent：仅审批通过后实际进入下一阶段且成功持久化时记录；不严格检查文档版本或文件差异，不增加业务文件 revision。revision_id=design:<session_id>:<target_phase>，使用真实策划会话 ID 和本次实际进入的目标阶段；source=design_agent，revision_source=agent，change_kind=design_document，files_changed_count 省略。该标识只表示阶段推进事实，不代表文件版本。
 - 策划同会话同目标阶段只记一次；同阶段内文件写入、普通对话、工具执行、提交审批、审批拒绝、等待澄清、没有实际阶段变化的批准，以及持久化失败均不产生该成果事件。项目重开、会话恢复或读取现有阶段不补历史。
@@ -501,6 +502,8 @@ session.json 是本地恢复元数据，不是待上传事件；事件文件不

 ## 12. 实施与验证状态

+2026-09-22 Direct 采集锁隔离验证：原生 `analytics` 定向测试 60 项通过、1 项既有跳过，`agent::direct_execution::tests` 24 项全部通过（两组有 1 项重叠）。新增线程用例持续占用业务锁，验证采集身份设置、成果记录、上下文与最新成果读取在释放业务锁前完成，并实际读回原用户的成果事件；另验证恢复不补造历史成果编号、旧账本缺少元数据不套用当前用户。独立代码复核及格式、编码、文档索引、diff 检查通过。分页 DTO 仅修正注释，查询行为不变；退出机制未改，未运行完整 GUI/Provider 联调。
+
 2026-09-22 新项目资格有限恢复验证：原生 `analytics` 定向测试 59 项通过、1 项既有跳过；覆盖创建时无埋点上下文、创建通知队列拒绝、独立锁竞争和临时文件系统故障后的真实受理恢复，以及资格成功落盘后不重授、进程内待办容量限制。既有损坏/备份/身份不符、跨 writer 去重测试继续通过。命令配置、Rust 格式、编码、文档索引与 diff 检查通过；独立代码复核确认业务线程不执行资格文件 I/O，内存锁不覆盖后台 I/O。未执行完整 GUI/Provider 联调或生产发布。

 已做：原产品方案逐项对照；核对现役 Direct/Design 持久化、项目创建、revision、预览、UI 保存与 checkpoint 的源码入口。本文新增合同和参数均以草案标识，不作为已经上线的事实。