技能包：配置与代码分家 —— 每包自建 env/ 放本机专属配置，scripts/ 不再写死本机路径

用户 2026-10-11 原话：
· 19:22「这个环境都是针对一台机器的，同步到别的机器把环境都搞坏了」
· 19:28「不用挪出 用env文件夹区分就行，重点是 脚本是脚本 配置是配置」
· 19:29「每个技能 需要环境配置的 都有自己的 env文件夹」
· 19:30「修改完成后要仔细检查 避免调整后 各技能脚本运行失败」

改动：
1、session-mechanism 新增 env/（roots.env＝本机真身不入库 ＋ roots.env.example＝样例入库），
   install.py 的 ROOTS_ENV 改指 env/roots.env；全包脚本/hook 的配置定位统一为
   「向上 4 层 × env/roots.env 优先 → 包根 roots.env 兼容 → 技能库那份兜底」。
2、去硬编码：collabctl / keepalive / supervise-launch / board-launch 里的本机路径与本机工作区
   清单全清，改为 DSH_AIROOT（兜底 dirname(DSH_WS_ROOT)）＋ 扫 <AIROOT>/*/.workbuddy/collab/
   自动发现；保活任务名按 collabd-keepalive-<工作区名> 现推；启动器默认值改 ~/.workbuddy 形态。
3、browser-harness：bh_chrome_keepalive.py 默认值全部改 env 驱动，新增 env/bh.env.example。
4、.gitignore：env/ 下只放行 *.example（三行三种层级）＋ 兜住旧位置的包根 roots.env。
5、改包纪律.md 新增「四、包结构：脚本是脚本，配置是配置」，立为全仓通用规矩。
6、文档同步：SKILL.md / deploy.md（新增 §3b 配置层级、§6 换机器必查 6 件事）/ rules.md /
   pitfalls.md / supervise-persistence.md。

验收（本机）：py_compile 34 个 py 全过；selftest PASS 109 / FAIL 0；
逐文件实证 8 个 loader 命中 env/roots.env；preflight-lock.sh 同目录实测解出两个根；
install.py --manifest 77 份、语法失败 0。

异机验证（包拷成「新克隆」（只有 *.example）＋ 另造假工作区 ws-alpha/ws-beta）：
install.py --apply 自生成该机 env/roots.env；collabctl/keepalive 自动发现的确实是
ws-alpha/ws-beta、任务名现推（写死清单确已消除）；部署副本本地无 roots.env 时靠
CODEBUDDY_CONFIG_DIR 兜底读到技能库那份；整套 selftest 有宿主库时 PASS 108 / FAIL 1
（唯一 FAIL＝该区没有常驻心跳，环境所致；本机常驻在跑时同一套为 PASS 109 / FAIL 0）。

session-mechanism/scripts/hooks/_env.py

@@ -44,7 +44,7 @@ import time
 from pathlib import Path
 
 _STAMP_NAME = "env-stamp.json"
-_ROOTS_ENV = "roots.env"          # 技能根的权威落点（install.py 生成）
+_ROOTS_ENV = "roots.env"          # 文件名；落点是技能包 `<包>/env/roots.env`（install.py 生成）
 # 🔴🔴 2026-10-04 单包自包含改造：识别特征改成**多个候选**，⛔ 不再只认
 #    `agent-operating-rules`（那是**另一个**技能 ⇒ 只装本包时会把真技能库判成"不存在"）。
 #   🔴 旧写法的病：`skills_root()` / `env_check()` 三处都拿`(root)/_SNIFF).is_dir()` 当
@@ -74,21 +74,24 @@ def _norm(p) -> str:
 
 
 def _load_roots_env() -> dict:
-    """读技能包里的 `roots.env`（⛔ 各脚本的 `_sm_load_roots()` 注入 env 前的原始来源）。"""
+    """读技能包里的 `env/roots.env`（⛔ 各脚本的 `_sm_load_roots()` 注入 env 前的原始来源）。
+
+    查找顺序：向上逐层 `<d>/env/roots.env`（现行落点）→ `<d>/roots.env`（包根兼容）。
+    """
     out = {}
     d = Path(__file__).resolve().parent
     for _ in range(5):
-        f = d / _ROOTS_ENV
-        if f.is_file():
-            try:
-                for ln in f.read_text(encoding="utf-8").splitlines():
-                    ln = ln.strip()
-                    if ln and not ln.startswith("#") and "=" in ln:
-                        k, v = ln.split("=", 1)
-                        out[k.strip()] = v.strip()
-                return out
-            except Exception:
-                return {}
+        for f in (d / "env" / _ROOTS_ENV, d / _ROOTS_ENV):
+            if f.is_file():
+                try:
+                    for ln in f.read_text(encoding="utf-8").splitlines():
+                        ln = ln.strip()
+                        if ln and not ln.startswith("#") and "=" in ln:
+                            k, v = ln.split("=", 1)
+                            out[k.strip()] = v.strip()
+                    return out
+                except Exception:
+                    return {}
         n = d.parent
         if n == d:
             break

session-mechanism/scripts/hooks/bash-output-guard.py

@@ -29,24 +29,27 @@
 ⛔ **别给本脚本加 `-E`**：`-E` 会屏蔽 `PYTHONUTF8`/`PYTHONIOENCODING` ⇒ stdin 回退 cp936 ⇒
    含中文的 payload 解析失败且**静默 fail-open**（同目录 `stop-dialog-guard.py` 已因此"白排查一天"）。
 """
-# [session-mechanism] roots.env 外置（由 install.py 生成；缺失则回落到按位置推导）
+# [session-mechanism] 环境配置外置（由 install.py 生成）；2026-10-11 起落在本包 `env/roots.env`
 def _sm_load_roots():
     import os as _os
     _here = _os.path.dirname(_os.path.abspath(__file__))
+    # 🔴 2026-10-11：「脚本是脚本 配置是配置」⇒ 配置落本包 `env/`。
+    #    首选 `env/roots.env`；并兼容旧的包根 `roots.env`（拷贝未同步时照旧能跑）。
     for _up in range(4):
-        _p = _os.path.join(_here, *([".."] * _up), "roots.env")
-        _p = _os.path.normpath(_p)
-        if _os.path.isfile(_p):
-            try:
-                with open(_p, encoding="utf-8") as _f:
-                    for _ln in _f:
-                        _ln = _ln.strip()
-                        if _ln and not _ln.startswith("#") and "=" in _ln:
-                            _k, _v = _ln.split("=", 1)
-                            _os.environ.setdefault(_k.strip(), _v.strip())
-            except Exception:
-                pass
-            return
+        _base = _os.path.normpath(_os.path.join(_here, *([".."] * _up)))
+        for _rel in (("env", "roots.env"), ("roots.env",)):
+            _p = _os.path.join(_base, *_rel)
+            if _os.path.isfile(_p):
+                try:
+                    with open(_p, encoding="utf-8") as _f:
+                        for _ln in _f:
+                            _ln = _ln.strip()
+                            if _ln and not _ln.startswith("#") and "=" in _ln:
+                                _k, _v = _ln.split("=", 1)
+                                _os.environ.setdefault(_k.strip(), _v.strip())
+                except Exception:
+                    pass
+                return
 _sm_load_roots()
 
 import io

session-mechanism/scripts/hooks/lock-guard-hook.py

@@ -32,24 +32,27 @@ lock-guard-hook.py — 「无锁不许改库」的强制钩子（WorkBuddy PreTo
 
 退出码：始终 0（判定通过 JSON 输出表达）；脚本自身异常也放行，绝不误伤。
 """
-# [session-mechanism] roots.env 外置（由 install.py 生成；缺失则回落到按位置推导）
+# [session-mechanism] 环境配置外置（由 install.py 生成）；2026-10-11 起落在本包 `env/roots.env`
 def _sm_load_roots():
     import os as _os
     _here = _os.path.dirname(_os.path.abspath(__file__))
+    # 🔴 2026-10-11：「脚本是脚本 配置是配置」⇒ 配置落本包 `env/`。
+    #    首选 `env/roots.env`；并兼容旧的包根 `roots.env`（拷贝未同步时照旧能跑）。
     for _up in range(4):
-        _p = _os.path.join(_here, *([".."] * _up), "roots.env")
-        _p = _os.path.normpath(_p)
-        if _os.path.isfile(_p):
-            try:
-                with open(_p, encoding="utf-8") as _f:
-                    for _ln in _f:
-                        _ln = _ln.strip()
-                        if _ln and not _ln.startswith("#") and "=" in _ln:
-                            _k, _v = _ln.split("=", 1)
-                            _os.environ.setdefault(_k.strip(), _v.strip())
-            except Exception:
-                pass
-            return
+        _base = _os.path.normpath(_os.path.join(_here, *([".."] * _up)))
+        for _rel in (("env", "roots.env"), ("roots.env",)):
+            _p = _os.path.join(_base, *_rel)
+            if _os.path.isfile(_p):
+                try:
+                    with open(_p, encoding="utf-8") as _f:
+                        for _ln in _f:
+                            _ln = _ln.strip()
+                            if _ln and not _ln.startswith("#") and "=" in _ln:
+                                _k, _v = _ln.split("=", 1)
+                                _os.environ.setdefault(_k.strip(), _v.strip())
+                except Exception:
+                    pass
+                return
 _sm_load_roots()
 
 

session-mechanism/scripts/hooks/session-log-guard.py

@@ -69,13 +69,19 @@
 （原写「5 条 hook 入口」，2026-10-01 起为 **7 条**：lock-guard ×2 / bash-output-guard / skill-load-guard /
 stop-dialog-guard / **session-log-guard ×2**）。
 """
-# [session-mechanism] roots.env 外置（由 install.py 生成；缺失则回落到按位置推导）
+# [session-mechanism] roots.env 外置（由 install.py 生成 ⇒ `<包>/env/roots.env`）
+#   查找顺序：向上 4 层 × (env/roots.env 优先 → 包根 roots.env 兼容) → 技能库那份。
 def _sm_load_roots():
     import os as _os
     _here = _os.path.dirname(_os.path.abspath(__file__))
+    _cands = []
     for _up in range(4):
-        _p = _os.path.join(_here, *([".."] * _up), "roots.env")
-        _p = _os.path.normpath(_p)
+        _base = _os.path.normpath(_os.path.join(_here, *([".."] * _up)))
+        for _rel in (("env", "roots.env"), ("roots.env",)):
+            _cands.append(_os.path.join(_base, *_rel))
+    _conf = _os.environ.get("CODEBUDDY_CONFIG_DIR") or _os.path.expanduser("~/.workbuddy")
+    _cands.append(_os.path.join(_conf, "skills", "session-mechanism", "env", "roots.env"))
+    for _p in _cands:
         if _os.path.isfile(_p):
             try:
                 with open(_p, encoding="utf-8") as _f:

session-mechanism/scripts/hooks/skill-load-guard.py

@@ -41,13 +41,19 @@ AI 仍按常驻判据把两个**非门禁**问题（"106 旧控制面要不要
    18:38 起本钩子与 `stop-dialog-guard` 就在真实用户发言上**热生效**，未重启宿主；`PreToolUse` 同类）。
    ⇒ 改完仍应**喂一次模拟载荷端到端自证**，⛔ 别只改配置就宣布"修好了"。
 """
-# [session-mechanism] roots.env 外置（由 install.py 生成；缺失则回落到按位置推导）
+# [session-mechanism] roots.env 外置（由 install.py 生成 ⇒ `<包>/env/roots.env`）
+#   查找顺序：向上 4 层 × (env/roots.env 优先 → 包根 roots.env 兼容) → 技能库那份。
 def _sm_load_roots():
     import os as _os
     _here = _os.path.dirname(_os.path.abspath(__file__))
+    _cands = []
     for _up in range(4):
-        _p = _os.path.join(_here, *([".."] * _up), "roots.env")
-        _p = _os.path.normpath(_p)
+        _base = _os.path.normpath(_os.path.join(_here, *([".."] * _up)))
+        for _rel in (("env", "roots.env"), ("roots.env",)):
+            _cands.append(_os.path.join(_base, *_rel))
+    _conf = _os.environ.get("CODEBUDDY_CONFIG_DIR") or _os.path.expanduser("~/.workbuddy")
+    _cands.append(_os.path.join(_conf, "skills", "session-mechanism", "env", "roots.env"))
+    for _p in _cands:
         if _os.path.isfile(_p):
             try:
                 with open(_p, encoding="utf-8") as _f:

session-mechanism/scripts/hooks/stop-dialog-guard.py

@@ -32,13 +32,19 @@
    含中文的 payload 解码即炸。本脚本现已改为走 `buffer` 显式 UTF-8（读写都加固），但**不要靠加固兜底**，
    装的时候也别再引入新雷。（2026-09-15 实测：`-S -E` 曾让本钩子"看起来从未被调用"整整一天。）
 """
-# [session-mechanism] roots.env 外置（由 install.py 生成；缺失则回落到按位置推导）
+# [session-mechanism] roots.env 外置（由 install.py 生成 ⇒ `<包>/env/roots.env`）
+#   查找顺序：向上 4 层 × (env/roots.env 优先 → 包根 roots.env 兼容) → 技能库那份。
 def _sm_load_roots():
     import os as _os
     _here = _os.path.dirname(_os.path.abspath(__file__))
+    _cands = []
     for _up in range(4):
-        _p = _os.path.join(_here, *([".."] * _up), "roots.env")
-        _p = _os.path.normpath(_p)
+        _base = _os.path.normpath(_os.path.join(_here, *([".."] * _up)))
+        for _rel in (("env", "roots.env"), ("roots.env",)):
+            _cands.append(_os.path.join(_base, *_rel))
+    _conf = _os.environ.get("CODEBUDDY_CONFIG_DIR") or _os.path.expanduser("~/.workbuddy")
+    _cands.append(_os.path.join(_conf, "skills", "session-mechanism", "env", "roots.env"))
+    for _p in _cands:
         if _os.path.isfile(_p):
             try:
                 with open(_p, encoding="utf-8") as _f:

session-mechanism/scripts/hooks/supervise-ensure-hook.py

@@ -49,17 +49,21 @@ except Exception:
 #       ① stdin 的 `payload.cwd`（宿主一定给）
 #       ② `roots.env` 的 `DSH_WS_ROOT`（副本专属，⛔ 不能只靠宿主 env）
 def _sm_load_roots() -> None:
-    """把 `roots.env` 以 setdefault 注入 env（宿主 env 优先，⛔ 不覆盖）。"""
-    p = SKILL / "roots.env"
-    try:
-        for line in p.read_text(encoding="utf-8").splitlines():
-            line = line.strip()
-            if not line or line.startswith("#") or "=" not in line:
-                continue
-            k, v = line.split("=", 1)
-            os.environ.setdefault(k.strip(), v.strip())
-    except Exception:
-        pass
+    """把本包 `env/roots.env` 以 setdefault 注入 env（宿主 env 优先，⛔ 不覆盖）。"""
+    cands = [SKILL / "env" / "roots.env", SKILL / "roots.env"]
+    _cfg = os.environ.get("CODEBUDDY_CONFIG_DIR") or os.path.expanduser("~/.workbuddy")
+    cands.append(Path(_cfg) / "skills" / "session-mechanism" / "env" / "roots.env")
+    for p in cands:
+        try:
+            for line in p.read_text(encoding="utf-8").splitlines():
+                line = line.strip()
+                if not line or line.startswith("#") or "=" not in line:
+                    continue
+                k, v = line.split("=", 1)
+                os.environ.setdefault(k.strip(), v.strip())
+            return
+        except Exception:
+            continue
 
 
 _sm_load_roots()