diff --git a/docs/work-log-2026-09-20.md b/docs/work-log-2026-09-20.md index 7f1cc80..6fb9009 100644 --- a/docs/work-log-2026-09-20.md +++ b/docs/work-log-2026-09-20.md @@ -1,9 +1,12 @@ # 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) +- 记录人：agent.develop +- 首轮记录：2026-09-20 19:20（+08:00）｜**响应轮更正：2026-09-20（`c66868c` 收口之后复跑并补记，见 §2/§3.5/§6/§7）** - 关联任务：`[M11b-2a]` u6kCWdLV2k5cmuG8Yb5BY（父）／`[M11b-2a-1]` dPgvSjRDNQ6kIQi0K-6HT（approved）／`[M11b-2a-2]` hVZNlBKmtiNNzn6BPeA3J（本记录） -- 关联迭代：pbls-初始迭代　｜　响应 QC 未过项：#1 开发说明缺失、#2 过程归档缺失（#3 由 M11b-2a-1 处置） +- 关联迭代：pbls-初始迭代　｜　响应 QC 未过项：#1 开发说明缺失（含范围声明失实）、#2 过程归档缺失（#3 由 M11b-2a-1 处置） + +> ⚠️ 响应轮更正要点：首轮 §2 commit 列表只写到 `aff1f0d`，把本任务描述成「仅新增 2 个 md」。实测 `git show c66868c --numstat` 显示本任务收口 commit 除 work-log（+96）外**还包含 `scripts/validate_models_json.py` 的 rev4 代码改动（+104/−35）**。该改动属 M11b-2b 范围，因引擎统一 git 收口而被一并提交 —— 现于 §2 补记、§7 显式声明「跨任务混提」。 --- @@ -11,11 +14,12 @@ **做：** 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）。 +2. 三处接线：内层包 re-export 契约符号、`init.py` loader 命名与 ServerEnv 登记、根包导出（后者经核对判定违规后撤销，见 §3.1）。 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）。 +**不做：** 业务逻辑（事务/行锁/回滚/乐观并发/权限判定）零改动；`models/` JSON 表定义内容零改动（M11b-2b）；apps 侧部署副本清理未强制（§5 遗留项 4）。 +**范围澄清（响应轮）**：「本任务不改代码」只对**主动编写的迁移/业务代码**成立 —— 收口 commit `c66868c` 实际含一次非本任务范围的脚本改动（§7），不得对外表述为「零代码改动」。 --- @@ -27,7 +31,9 @@ | `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） | +| **`c66868c`** | 09-20 19:24 | `deliver: 交付收口（引擎代为提交）` —— **本任务（M11b-2a-2）的收口 commit**，`git show --numstat` 实测含 **2 项变更 / 200 insertions(+) 35 deletions(-)**：① `docs/work-log-2026-09-20.md` **+96 / −0**（本文件，QC #2 要求的 dated work-log，归属 M11b-2a-2）；② `scripts/validate_models_json.py` **+104 / −35**（rev4 修复：`RULE_STATS_TAGS` 结构重构、`_rule_tag()` 候选元组语义、`other==0` 硬门禁 + `RULE_STATS_OTHER_DETAIL`、新增 `--allow-registered-deviation` CLI、「引用式写法」key/schema 判 ERROR。**归属 M11b-2b**，因引擎统一收口被一并提交，见 §7 跨任务混提声明） | + +首轮此表缺 `c66868c` 一行（响应轮补记）；`9f97d58` 行原述「pathspec 有意排除 validate_models_json.py」仍准确，但需与 §7 连读 —— 排除只对该 commit 生效，最终仍由 `c66868c` 入库。 --- @@ -53,20 +59,26 @@ M11b-2a-1 rev1 文档 §4.2 与交付摘要 §3 中 case1 的 OK 输出块为不 契约函数实现只在 `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__` 或根包中写第二份实现。 +### 3.5 陷阱（响应轮新增）：文档范围声明与仓库最终态脱节 + +首轮交付摘要写「本任务仅新增 2 个 md，零代码改动」，dev-notes §6 第 6 行写 `validate_models_json.py`「未纳入 commit」—— 两句都与 `git show c66868c --numstat` 的事实矛盾（该 commit 明确含脚本 +104/−35）。根因：产线 git 收口由**引擎在 deliver 时代为执行**，提交范围 = 工作区全部未提交变更，develop 无法指定 pathspec；因此「文档任务」的收口 commit 也可能带代码。 +教训与对策：① 交付摘要与 work-log 的 commit 列表必须在**收口后**以 `git show --numstat` 复核，不能按任务意图预写；② 工作区存在其它任务 WIP 时，deliver 前先清理/stash，或如本文 §7 显式声明混提归属；③ 文档类任务的「零代码改动」措辞要改为「本任务未主动改动业务代码，随包收口项见 §7」。 + --- -## 4. 验证（2026-09-20 19:20 实测） +## 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，非回归 | +| 语法 | `python3 -m py_compile world_sync/*.py scripts/*.py` | `rc=0` 全通过（含 rev4 后的 `scripts/validate_models_json.py`） | +| 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**（`__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` | +| rev4 校验脚本自测（响应轮新增） | `python3 scripts/validate_models_json.py --help` / `... models` | 开关 `--allow-registered-deviation` 真实存在；本仓库 `files=5 errors=2 registered_deviations=0`，全部归入 `RULE_STATS: reference_style_key_schema=2`，无 other 黑洞，`RESULT: FAIL rc=1`（暴露 models JSON 待修项，归 M11b-2b） | +| 工作区 | `git status --porcelain` | 无输出 = clean；branch `main` @ `c66868c`，tracking `[origin/main]`，另有 `archive/m11b1-in-world-sync` | -完整输出块见 `projects/pbls/docs/02-develop/dev-notes-m11b2a-world-sync-migration.md` §4。 +完整输出块见 `projects/pbls/docs/02-develop/dev-notes-m11b2a-world-sync-migration.md` §4（含 §4.6 git numstat、§4.7 rev4 自测）。 --- @@ -76,21 +88,44 @@ M11b-2a-1 rev1 文档 §4.2 与交付摘要 §3 中 case1 的 OK 输出块为不 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` 已就位）。 +5. **`models/` JSON 与 SQL 列清单 diff**：留 M11b-2b（`scripts/m11b2b_column_diff.py` 已就位）。rev4 校验脚本已实测报出 `models/` 5 文件中 2 条 `reference_style_key_schema` ERROR（§4），**该修复本身未随本任务完成**，属 M11b-2b 待办。 6. **`sys.path=modules/` 契约路径**：已确认不可用并文档化（§3.2），未修复。 +7. **`git push` 结果未由本角色验证**：收口由引擎执行，`git branch -vv` 显示 `main c66868c [origin/main]` 无 ahead 标记，但推送日志不在本记录取证范围。 --- -## 6. 当前 branch-commit 状态（记录时点） +## 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) +branch: main（tracking remotes/origin/main）；工作区 clean（git status --porcelain 无输出） +HEAD: c66868c deliver: 交付收口（引擎代为提交） ← 本任务收口：work-log(+96) + validate_models_json.py rev4(+104/−35) + 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: 交付收口（引擎代为提交） +其它分支：archive/m11b1-in-world-sync @ 052d257 仓库根结构：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。 +本记录（M11b-2a-2）首轮文档已随 `c66868c` 入库；响应轮的更正（§2 补记 `c66868c`、§3.5、§4 新增 rev4 行、§5 第 5/7 项、§6、§7）由引擎下一次交付收口统一提交，本记录不自称已 commit/push。 + +--- + +## 7. 跨任务混提声明（响应 QC #1 第 ④ 点） + +**事实**：`c66868c` 同时承载两个任务的产物 —— + +| 文件 | 变更 | 归属任务 | +|---|---|---| +| `docs/work-log-2026-09-20.md` | +96 / −0（新增） | `[M11b-2a-2]` 本任务（QC #2 归档） | +| `scripts/validate_models_json.py` | +104 / −35（修改） | **`[M11b-2b]`**（models JSON 机械校验工具 rev4） | + +**为何发生**：rev4 改动是 M11b-2b 在途 WIP，遗留在工作区未提交。`9f97d58`（结构处置）当时**有意用 pathspec 排除**它，避免混进 2a 的结构 commit；但本任务 `deliver` 时 git 收口由**引擎代为执行**，范围 = 工作区全部未提交变更，不支持人工 pathspec，于是该脚本随本任务收口被提交为 `c66868c`。 + +**为何未单独收口 / 不回退**：① 改动已入库且工作区 clean，从已推送的 `main` 历史剥离需改写历史，风险大于收益；② rev4 属纯工具侧改动，不触碰 `world_sync/` 包与业务逻辑，对 M11b-2a 的迁移/接线/结构结论无影响（§4 复跑仍 OK）；③ 它是 M11b-2b 的前置能力，提前入库不阻塞 2b，反而让 2b 能直接基于 rev4 去修 `models/` 的 2 条 ERROR。 + +**给 QC / PM 的判读约定**： +- `c66868c` 中 `scripts/validate_models_json.py` 的**变更归属 = M11b-2b**，本任务仅为随包收口载体，不得据此认为 M11b-2b 已交付（models JSON 的 2 条 ERROR 仍未修）； +- 本任务对 M11b-2a 迁移范围（`world_sync/` 包、`pyproject.toml`）**代码零改动**的结论仍然成立； +- 若产线要求「一 commit 一任务」，建议列为流程改进：`deliver` 前强制清理工作区 WIP，或引擎收口支持 pathspec —— 而非作为本任务的返工项。