yumoqing/world_sync
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
world_sync/docs/work-log-2026-09-20.md
agent.develop c66868cbd3 deliver: 交付收口（引擎代为提交）
2026-09-20 19:24:09 +08:00

9.0 KiB
Raw Blame History

work-log 2026-09-20 — world_sync（M11b-2a 迁移 + M11b-2a-1 根包合规 + M11b-2a-2 文档归档）

  • 仓库：modules/world_sync（remote yumoqing/world_sync，branch main）
  • 记录人：agent.develop　｜　记录时间：2026-09-20 19:20 (+08:00)
  • 关联任务：[M11b-2a] u6kCWdLV2k5cmuG8Yb5BY（父）／[M11b-2a-1] dPgvSjRDNQ6kIQi0K-6HT（approved）／[M11b-2a-2] hVZNlBKmtiNNzn6BPeA3J（本记录）
  • 关联迭代：pbls-初始迭代　｜　响应 QC 未过项：#1 开发说明缺失、#2 过程归档缺失（#3 由 M11b-2a-1 处置）

1. Scope（本任务链做了什么 / 不做什么）

做：

  1. 把 M11b-2「单事务事件+状态原子写入」实现从应用侧 apps/scense/pkgs/world_sync/world_sync/ 迁移到模块仓库 modules/world_sync/world_sync/（5 个新增子模块 + __init__.py + init.py），tests/scripts 同迁 —— 落实「develop 模块源码必须落 modules/」。
  2. 三处接线：内层包 re-export 契约符号、init.py loader 命名与 ServerEnv 登记、根包导出（后者经核对判定违规后撤销，见 §3）。
  3. 结构合规处置：删除仓库根 __init__.py（156 行转发包）+ pyproject.toml 收紧打包面 + 导入闭包重验。
  4. 文档归档（M11b-2a-2）：projects/pbls/docs/02-develop/dev-notes-m11b2a-world-sync-migration.md + 本 work-log。

不做： 业务逻辑（事务/行锁/回滚/乐观并发/权限判定）零改动；models/ JSON 表定义零改动（M11b-2b）；apps 侧部署副本清理未强制（§5 遗留项 3）。

2. Commit 列表

commit 时间 内容
01941aa 2026-09-20 deliver: 交付收口（引擎代为提交） —— 迁移本体落库：world_sync/{pbl_runtime_errors,pbl_runtime_sql,pbl_runtime_tx,pbl_runtime_tx_env,pbl_runtime_tx_sqlor}.py + __init__.py(6187B) + init.py(22123B) + tests/scripts；三处接线成立（含当时的根包转发，156 行）
9f97d58 09-20 18:31 M11b-2a: resolve root-package spec compliance (drop repo-root __init__.py forwarding package) —— 删除 modules/world_sync/__init__.py（1 file changed, 156 deletions）；commit message 内记录宿主接线行号证据与删除后复验结论；用 pathspec 有意排除 M11b-2b WIP scripts/validate_models_json.py
95b405f 09-20 deliver: 交付收口（引擎代为提交） —— M11b-2a-1 交付件收口
aff1f0d 09-20 19:12 M11b-2a: resolve root-package spec compliance (rev2: tighten packaging surface, record real import evidence) —— pyproject.toml:25-28 [tool.setuptools.packages.find] where=["."] include=["world_sync*"] namespaces=false；更正 rev1 不实的 case1 输出，补 host（venv editable）取证
本任务 — 仅新增文档：projects/pbls/docs/02-develop/dev-notes-m11b2a-world-sync-migration.md、modules/world_sync/docs/work-log-2026-09-20.md（git 收口由引擎执行，本记录不自称已 commit/push）

3. 关键决策与陷阱

3.1 为何「删除」根包转发，而不是「保留 + 收紧」（QC #3 给了二选一）

  • 规范：module-development-spec 规定 mymodule/ 是仓库根、mymodule/mymodule/ 才是 Python 包，仓库根不列 __init__.py；同机构 modules/pbl_runtime_ext/ 等仓库根均无 __init__.py。
  • 宿主接线实测不依赖它：apps/scense/app/scense.py:50 from world_sync.init import load_world_sync（L57 调用）、apps/yuanjing/app/yuanjing.py:66 __import__(f'{module}.init', ...) —— 两者都以 sys.path=仓库根解析到内层 world_sync/init.py。转发表无人调用 = 死代码。
  • 风险：根包 + packages.find include=["world_sync*"] 组合会把仓库根一并发现为包，产生「同一模块两条导入路径、两份 __init__ 语义」的双路径歧义，后续 develop 极易误用根包路径写出跑不通的接线。
  • 决策：走 (a) 删除（9f97d58），并追加 (b) 的配置部分（aff1f0d）把约束固化进 pyproject.toml，防回归。

3.2 陷阱：init/ 数据目录遮蔽 init.py（case1 的真实 FAIL）

modules/world_sync/init/data.json 是模块既有数据目录。当 sys.path 落在模块父目录 modules/ 时，world_sync.init 优先解析到该目录（namespace 片段）而非 init.py，于是 from world_sync.init import load_world_sync → ImportError: cannot import name 'load_world_sync' from 'world_sync.init' (unknown location)。 用删除前基线 01941aa 沙箱复刻同场景：删除前同样 FAIL ⇒ 非本次删除引入的回归。结论：world_sync 的 loader 接线以 sys.path=仓库根（宿主实际做法）为准，sys.path=modules/ 不作为契约路径；若要支持需单独立项（重命名数据目录或调 scripts/load_path.py 注入顺序）。

3.3 陷阱：把「删除前的验证输出」当成「删除后的证据」（流程教训）

M11b-2a-1 rev1 文档 §4.2 与交付摘要 §3 中 case1 的 OK 输出块为不实记录（错误归因），被 QC #7/#8/#14 指出。rev2 已删除伪造块、以 bash projects/pbls/scripts/m11b2a1_rev2_revalidate.sh 落盘输出替换（全文 projects/pbls/evidence/m11b2a1_rev2_import_closure.txt）。本 work-log 与 dev-notes 中所有输出为 2026-09-20 19:20 再次独立复跑，与 rev2 一致。教训：验证必须在处置动作之后重跑，且证据要落盘可复核。

3.4 决策：单一真源

契约函数实现只在 world_sync/pbl_runtime_tx_sqlor.py，__init__.py:40 from .init import (...) / L119–120 只做 re-export（实测 write_event_with_state.__module__ == 'world_sync.pbl_runtime_tx_sqlor'），不允许在包 __init__ 或根包中写第二份实现。

4. 验证（2026-09-20 19:20 实测）

项 命令 结果
语法 python3 -m py_compile world_sync/*.py scripts/*.py rc=0 全通过
case2 sys.path=仓库根 import world_sync / from world_sync.init import load_world_sync / 4 契约符号 OK；__file__ → modules/world_sync/./world_sync/__init__.py；仓库根 __init__.py 存在性 = False；__all__ len=62 MISSING=[]；issubclass(ConcurrentStateConflict, PblRuntimeError)=True
case1 sys.path=modules/ 同上 FAIL（_NamespacePath/__file__=None/ImportError (unknown location)），根因 §3.2，非回归
host sys.path=apps/scense/pkgs/world_sync 同上 OK；__file__ → apps 副本内层包；__all__: 62 MISSING: []
迁移一致性 diff -q 8 个 .py（模块仓库 vs apps 副本） 8/8 IDENTICAL
工作区 git status --porcelain 无输出 = clean；branch main，remotes/origin/main 存在，另有 archive/m11b1-in-world-sync

完整输出块见 projects/pbls/docs/02-develop/dev-notes-m11b2a-world-sync-migration.md §4。

5. 受环境限制未验证项（不得当作已验证）

  1. 真实 DB 建连与写入路径未跑：沙箱无 MySQL/PG。configure_runtime_writer(init.py:326)、单事务内「事件写 + 实体状态写 + 行锁」原子性、失败回滚、ConcurrentStateConflict 实际抛出路径 —— 均只有静态/import/mock 级覆盖，需部署态联调。
  2. tests/test_m11b2_single_tx.py / test_m11b2_wiring.py 未执行：依赖 DB fixture，本轮只保证可编译可导入。
  3. env.pbl_runtime_conn_factory 端到端解析未跑：init.py:480/483 的 ServerEnv 键解析链需应用启动态验证。
  4. apps 侧薄壳清理未做（原任务第 4 项为可选）：apps/scense/pkgs/world_sync/world_sync/ 保留 8 个 IDENTICAL 文件，因为宿主 scense.py:50 实际加载的就是该 editable 副本；删除会让 scense 立即失去模块。建议后续改为部署期同步产物（build.sh / scripts/sync_models_to_app.py）+ .gitignore 排除，做到「模块仓库唯一真源」。
  5. models/ JSON 与 SQL 列清单 diff：留 M11b-2b（scripts/m11b2b_column_diff.py 已就位）。
  6. sys.path=modules/ 契约路径：已确认不可用并文档化（§3.2），未修复。

6. 当前 branch-commit 状态（记录时点）

branch: main（tracking remotes/origin/main）；工作区 clean
HEAD:   aff1f0d M11b-2a: resolve root-package spec compliance (rev2: tighten packaging surface, record real import evidence)
        95b405f deliver: 交付收口（引擎代为提交）
        9f97d58 M11b-2a: resolve root-package spec compliance (drop repo-root __init__.py forwarding package)
        01941aa deliver: 交付收口（引擎代为提交）
仓库根结构：README.md / pyproject.toml / init/(数据目录) / json/ / models/ / scripts/ / skill/ / tests/ / wwwroot/ / world_sync/(内层包) / docs/(本记录)
无仓库根 __init__.py —— 对外唯一路径：world_sync.init（loader）、world_sync（内层包，sys.path=仓库根）、world_sync.world_sync.*（子模块，sys.path=仓库根时等价 world_sync.*）

本任务（M11b-2a-2）新增文档后的 commit 由引擎交付收口统一执行，本记录不自称已 commit/push。