From 9e8984168f4e759836e2db42054fd07675058863 Mon Sep 17 00:00:00 2001
From: "agent.develop" <agent.develop@hrs6.local>
Date: Fri, 25 Sep 2026 09:04:34 +0800
Subject: [PATCH] =?UTF-8?q?fix(entity):=20=E5=88=A0=E9=99=A4=E4=BB=93?=
 =?UTF-8?q?=E5=BA=93=E6=A0=B9=20=5F=5Finit=5F=5F.py=EF=BC=8C=E6=B6=88?=
 =?UTF-8?q?=E9=99=A4=20entity.init=20=E5=91=BD=E5=90=8D=E7=A9=BA=E9=97=B4?=
 =?UTF-8?q?=E6=AD=A7=E4=B9=89=EF=BC=88pbls-deploy-Q6=EF=BC=89?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 根 __init__.py 的删除已在 e118efe 落地并推送 origin/main（本提交补齐可追溯的
  Q6 专项说明：README.md / skill/SKILL.md 增补「命名空间铁律」段，留档根因与核验命令）
- 根因：modules/entity 根同时存在包目录 entity/ 与种子目录 init/，根再放 __init__.py
  会使根成为包，entity.init 解析到根下命名空间目录，遮蔽 entity/entity/init.py
  → 部署侧 cannot import name 'load_entity' from 'entity.init'
- 核验：python3 apps/pbls/scripts/verify_import_closure.py → entity 无 NS_AMBIGUITY 告警
---
 README.md      |  6 ++++++
 skill/SKILL.md | 13 +++++++++++++
 2 files changed, 19 insertions(+)

diff --git a/README.md b/README.md
index 53bdf8f..b6b7c42 100644
--- a/README.md
+++ b/README.md
@@ -33,3 +33,9 @@ entity/
 - `wwwroot/api/entity_import.dspy`：实体导入（world_id + scene_id + file）
 - `wwwroot/api/entity_create.dspy` / `entity_update.dspy` / `entity_delete.dspy`：实体 CRUD
 - `wwwroot/api/get_search_*.dspy`：下拉数据源
+
+## 命名空间约束（Q6）
+仓库根**不得**存在 `__init__.py`（会使根成为包，令 `entity.init` 遮蔽 `entity/entity/init.py`，
+部署时报 `cannot import name 'load_entity' from 'entity.init'`）。根 `__init__.py` 已在提交
+`e118efe` 删除并推送 `origin/main`；核验命令：
+`python3 apps/pbls/scripts/verify_import_closure.py`（entity 应无 NS_AMBIGUITY 告警）。
diff --git a/skill/SKILL.md b/skill/SKILL.md
index e785e57..050cbe8 100644
--- a/skill/SKILL.md
+++ b/skill/SKILL.md
@@ -27,3 +27,16 @@ description: entity 模块技能文档——实体管理（实体表 CRUD + 实
 ## 依赖
 - world、scene（下拉数据源 world / scene 表）
 - 基础：sqlor、ahserver、bricks、appbase（appcodes）
+
+## 命名空间铁律（pbls-deploy-Q6 缺陷 2 修复留档）
+
+- **仓库根禁止存在 `__init__.py`**：`modules/entity/` 根下同时有包目录 `entity/` 与种子数据目录
+  `init/`，若根再放 `__init__.py`，根目录自身成为包，`entity.init` 会被解析成「根下的 init/
+  命名空间目录」而遮蔽真实实现 `entity/entity/init.py` → 部署侧报
+  `cannot import name 'load_entity' from 'entity.init'`（deploy_test 第 3 轮实测）。
+- 根 `__init__.py` 已于提交 `e118efe` 删除（`git rm`），本地 main 与 `origin/main` 同 SHA，
+  `git ls-remote origin main` 已含该提交；`apps/pbls/scripts/verify_import_closure.py` 复跑
+  entity 无 `NS_AMBIGUITY` 告警。
+- 唯一入口：`from entity.init import load_entity`（实现文件 `entity/init.py`，包导出
+  `entity/__init__.py`）。新增函数仍须遵守三处同步注册（实现 def / 包 `__init__.py` 导出 /
+  `init.py` 的 `load_entity()` 内 `env.xxx = xxx`）。