From a46b914a8060ac565ec128a087359f37e70d619b Mon Sep 17 00:00:00 2001
From: maogeigei <maogeigei@gmail.com>
Date: Thu, 15 Oct 2026 23:46:16 +0800
Subject: [PATCH] =?UTF-8?q?session-mechanism=EF=BC=9A=E6=9C=AF=E8=AF=AD?=
 =?UTF-8?q?=E8=A1=A8=E6=94=B6=E6=95=9B=E5=88=B0=E4=B8=80=E5=A4=84=20?=
 =?UTF-8?q?=EF=BC=8B=20=E3=80=8C=E5=AE=BF=E4=B8=BB=E3=80=8D=E6=94=B9?=
 =?UTF-8?q?=E6=AD=A3=E5=BC=8F=E5=90=8D=20WorkBuddy=20=E6=9C=AC=E4=BD=93?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

用户令：「宿主 这个词要优化，看看产品规划技能中是如何优化这些难懂的词」。
口径借 product-planning 的语体规范（references/stage-proto-doc/references/doc-language-spec.md
§2.1–§2.4）：技术实现名不当正式名；正式名取界面实显名／术语表／行业通用词；一个东西一个名；首次出现给全称。

- architecture.md §7 立为「术语唯一天条真源」：正式名「宿主」→「WorkBuddy 本体」，表加「旧称／别再叫」列，
  并入 collab-detail §11 的独有条目（设备接入·本地反代／覆盖网络节点·中继客户端／棒／会话）；新增 §7.1 写词的规矩。
- collab-detail.md §11 的两张表删除、改为指针。实测打架：§11 写「宿主提供五样（含执行体·会话）」，
  而 architecture.md 与 collab-detail §1 都写「四样」⇒ 同一条两处两说。§11.1 命名铁律原文保留。
- SKILL.md：description 的悬空指向「见文首术语表」（本包从没有术语表）改为「见 architecture.md §7 术语」；
  「现状地图」首屏加一行「宿主 ＝ WorkBuddy 本体」。
- 01-文档索引.md 加一行（看不懂的词 → architecture §7）；06 的 B⑧ 加术语正本指针。

新增自测 t_term_table_single_source（3 项）：全包只许一处 `| 正式名 |` 表头且必须是 architecture.md、
正本里不许再出现「| **宿主** |」。已做变异对照（塞第二张表 ⇒ 报红；复原 ⇒ 绿）。
---
 session-mechanism/SKILL.md                    |  6 ++-
 session-mechanism/references/01-文档索引.md   |  1 +
 .../references/06-技能优化规程.md             |  1 +
 session-mechanism/references/architecture.md  | 36 ++++++++++++-----
 session-mechanism/references/collab-detail.md | 17 ++------
 session-mechanism/scripts/selftest.py         | 39 +++++++++++++++++++
 6 files changed, 77 insertions(+), 23 deletions(-)

diff --git a/session-mechanism/SKILL.md b/session-mechanism/SKILL.md
index a2988e0..9e8b235 100644
--- a/session-mechanism/SKILL.md
+++ b/session-mechanism/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: session-mechanism
-description: 「**会话机制 ＋ 多会话执行**」的合并总入口（原 `multi-session-collab` ＋ `workbuddy-session-forensics` 已并入本包）。🔴 **2026-10-05 起会话只三类：主会话 ＋ 任务会话 ＋ 检查会话**（唤醒／跟进／队列上报**已整套退役**；**任务会话＝旧称「执行会话」，同一个角色**）｜🔴 **2026-10-03 起「上报」整套真删**——现行机制＝**常驻程序 `collabd.py` 接收（`--report` 写台账）＋ 处理（建检查会话排期）**（⛔ 「协作程序」是 10-03 已退役的旧称，见文首术语表），⛔ **队列变化不再自动通知任何人**，要落事得**显式建执行会话**。两段可分别加载：① **会话机制** —— 管「会话怎么活下去、怎么不哑掉、怎么不失忆、跨机器怎么一键装好」：治「会话卡住 / 一直转圈 / 发消息没反应 / 界面不刷新」「会话日志涨到上限把界面顶死」「上下文爆了要换会话 / 接续会话怎么开」「抢锁 / 执行锁 / 并发 / 别的会话在动」「钩子没生效 / 钩子把我也拦住了」「换一台电脑要重装这一堆钩子」「某个历史会话当时到底干了啥」。② **多会话执行** —— 管「一个主会话带多个执行会话把需求做完」：治「多个会话协同但工期被拖长 / 有会话在干等 / 链条断了没人接 / 分不清『真完成』还是『只排了下一棒』/ 问清主会话·执行会话两类怎么分（**接续会话是撞阈值时的「形态」，⛔ 不是第 3 类**）」。🔴 **主触发句（2026-10-03 用户定案）**：用户说「**使用执行会话完成 XXXX 目标**」「**继续 XXXX 目标**」时**直接走本技能**（＝要派执行会话去把一个目标做完/接着做）。🔴🔴 **未装即装（2026-10-14 用户令）**：说「使用项目机制完成目标：XXXX」时，若本区 **没装机制** ⇒ **当场跑 `install.py --apply --workspace <本区根>` 装好，再往下走**（装机制是这条链的第一环，⛔ 不报成阻碍、⛔ 不绕过机制直接干、⛔ 装完不停手）。其他触发：「怎么协同多个会话」「别的会话都在干等」「任务没推进」「链条断了」「你监督这些会话」「会话卡住」「日志要爆了」「换机器怎么配」「升级 / 安装这套机制」。核心＝**会话机制三件套（钩子 ＋ 锁 ＋ 日志闸）全局生效** ＋ **执行两条通道各走各的**（派活靠自动化／收结果直读宿主库／机械判定下沉到常驻程序／人只看一个看板）＋ **一键配置 `install.py`**（换机器不手抄绝对路径）。
+description: 「**会话机制 ＋ 多会话执行**」的合并总入口（原 `multi-session-collab` ＋ `workbuddy-session-forensics` 已并入本包）。🔴 **2026-10-05 起会话只三类：主会话 ＋ 任务会话 ＋ 检查会话**（唤醒／跟进／队列上报**已整套退役**；**任务会话＝旧称「执行会话」，同一个角色**）｜🔴 **2026-10-03 起「上报」整套真删**——现行机制＝**常驻程序 `collabd.py` 接收（`--report` 写台账）＋ 处理（建检查会话排期）**（⛔ 「协作程序」是 10-03 已退役的旧称，见 architecture.md §7 术语），⛔ **队列变化不再自动通知任何人**，要落事得**显式建执行会话**。两段可分别加载：① **会话机制** —— 管「会话怎么活下去、怎么不哑掉、怎么不失忆、跨机器怎么一键装好」：治「会话卡住 / 一直转圈 / 发消息没反应 / 界面不刷新」「会话日志涨到上限把界面顶死」「上下文爆了要换会话 / 接续会话怎么开」「抢锁 / 执行锁 / 并发 / 别的会话在动」「钩子没生效 / 钩子把我也拦住了」「换一台电脑要重装这一堆钩子」「某个历史会话当时到底干了啥」。② **多会话执行** —— 管「一个主会话带多个执行会话把需求做完」：治「多个会话协同但工期被拖长 / 有会话在干等 / 链条断了没人接 / 分不清『真完成』还是『只排了下一棒』/ 问清主会话·执行会话两类怎么分（**接续会话是撞阈值时的「形态」，⛔ 不是第 3 类**）」。🔴 **主触发句（2026-10-03 用户定案）**：用户说「**使用执行会话完成 XXXX 目标**」「**继续 XXXX 目标**」时**直接走本技能**（＝要派执行会话去把一个目标做完/接着做）。🔴🔴 **未装即装（2026-10-14 用户令）**：说「使用项目机制完成目标：XXXX」时，若本区 **没装机制** ⇒ **当场跑 `install.py --apply --workspace <本区根>` 装好，再往下走**（装机制是这条链的第一环，⛔ 不报成阻碍、⛔ 不绕过机制直接干、⛔ 装完不停手）。其他触发：「怎么协同多个会话」「别的会话都在干等」「任务没推进」「链条断了」「你监督这些会话」「会话卡住」「日志要爆了」「换机器怎么配」「升级 / 安装这套机制」。核心＝**会话机制三件套（钩子 ＋ 锁 ＋ 日志闸）全局生效** ＋ **执行两条通道各走各的**（派活靠自动化／收结果直读宿主库／机械判定下沉到常驻程序／人只看一个看板）＋ **一键配置 `install.py`**（换机器不手抄绝对路径）。
 version: 1.3.0
 updated_at: 2026-10-05
 last_change: |-
@@ -133,6 +133,10 @@ agent_created: true
 
 ## 🗺️ 现状地图（2026-10-05 · ⛔ 看机制**先读这一屏**，读完再往下）
 
+> 🔴 **先把词对上（2026-10-15）**：正文里旧写的「**宿主**」＝ **`WorkBuddy 本体`** ——
+> 装在本机、跑着会话与技能的那个程序。术语正本 ⇒ `references/architecture.md §7 术语`；
+> 「宿主」「协作程序」「垫片」这类旧词，一律照那张表换成正式名（**新写的**按正式名，存量旧文不动字）。
+
 **三类会话（⛔ 只有三类，没有第四类）**
 
 | 角色 | **谁创建它** | 它干什么 | 怎么停 |
diff --git a/session-mechanism/references/01-文档索引.md b/session-mechanism/references/01-文档索引.md
index 8539967..b7d1657 100644
--- a/session-mechanism/references/01-文档索引.md
+++ b/session-mechanism/references/01-文档索引.md
@@ -28,6 +28,7 @@
 | 查某个历史会话干了啥 | `forensics.md` | — |
 | 任务图／多会话分工 | `taskgraph.md` ＋ `collab.md` | — |
 | 怎么回话／排版 | `03-回复排版-核心块.md` ＋ `02-功能优先协作协议.md` | — |
+| **读到看不懂的词／要写新词**（「宿主是什么」「术语」「这个词看不懂」） | `architecture.md §7 术语`（唯一正本） | — |
 | **盘点技能库／技能已无作用**（「盘点技能库」「技能库体检」「技能清单」） | `05-技能库盘点规程.md` | 其余全部 |
 | **优化技能本身／这条规则写在哪**（「优化技能」「技能怎么改更好」「梳理技能」「技能太长」） | `06-技能优化规程.md` | 其余全部 |
 | 对方甩来一句没头绪的话 | `02-功能优先协作协议.md` | — |
diff --git a/session-mechanism/references/06-技能优化规程.md b/session-mechanism/references/06-技能优化规程.md
index 822753c..79a992f 100644
--- a/session-mechanism/references/06-技能优化规程.md
+++ b/session-mechanism/references/06-技能优化规程.md
@@ -58,6 +58,7 @@
 
 **⑧ 命名一致**
 同一概念在全包用同一个叫法。改名前先列**伴随物清单**（只改主体必留隐患）。
+📌 本包的术语正式名与旧称映射，**唯一天条真源**是 `references/architecture.md §7 术语`（⛔ 别另抄一张表 —— 抄了必打架）。
 
 **⑨ 正文不自相矛盾**
 同一件事在技能里出现两种写法（尤其"正文"与"规则段"之间）⇒ 逐条对，留一处。
diff --git a/session-mechanism/references/architecture.md b/session-mechanism/references/architecture.md
index 6081d9c..8df8906 100644
--- a/session-mechanism/references/architecture.md
+++ b/session-mechanism/references/architecture.md
@@ -952,15 +952,33 @@
 
 ## 7 术语（说话／写文档一律用这一列）
 
-| 正式名 | 实体 |
-|---|---|
-| **宿主** | WorkBuddy 本体（地基） |
-| **主会话** | 工作区入口会话（判断 ＋ 派活） |
-| **任务会话** | 被派出去的一次性会话（"一棒一线"） |
-| **常驻程序** | 持有队列、收上报、判定/告警/看板/单例（⛔ 不派活） |
-| **投递** | 逐条读队列、发通知与唤醒、机械判定 |
-| **看板** | 用户唯一入口 |
-| **需求台账** | 常驻程序持有的**唯一**需求状态存放处（**四态**：待执行／执行中／已完成／有阻碍）—— ⛔ 不另开第二处 |
+🔴 **本节是术语的唯一天条真源**（2026-10-15 收敛）：别处只准引用，⛔ 不许另抄一张表。
+实测教训：`collab-detail.md §11` 曾另存一张，把「宿主」写成提供**五样**（含"执行体·会话"），
+而本节正文写的是**四样** —— 同一件事两处两说，读的人无从判断谁对。
+
+| 正式名 | 实体 | 旧称／别再叫 |
+|---|---|---|
+| **WorkBuddy 本体** | 装在本机、跑着会话与技能的那个程序（＝地基，⛔ 不是第 6 个主体）。它只提供**四样**：状态（三张只读表）／调度（自动化排期＝**唯一能开新会话的通道**）／事件（钩子）／互斥（域锁） | 「宿主」「平台」「服务端」 |
+| **主会话** | 工作区入口会话（判断 ＋ 派活） | —— |
+| **任务会话** | 被派出去的一次性会话（"一棒一线"） | 「执行会话」 |
+| **常驻程序** | 持有队列、收上报、判定/告警/看板/单例（⛔ 不派活） | 「协作程序」「协作守护程序」「机械层」「判定层」 |
+| **投递** | 逐条读队列、发通知与唤醒、机械判定 | 「机械层程序」「看门狗」 |
+| **会话** | 执行体：「读—判—写」；一次性、可替换 | —— |
+| **棒** | 一次派活 ＝ 一个会话（「一棒一线」） | —— |
+| **看板** | 用户唯一入口（只读旁路 · 异步快照） | ⛔ 别把 `digest.md`（机械摘要）当用户入口 |
+| **需求台账** | 常驻程序持有的**唯一**需求状态存放处（**四态**：待执行／执行中／已完成／有阻碍）—— ⛔ 不另开第二处 | —— |
+| **设备接入 · 本地反代** | `dsh-client` · 真身 `@dsh-client/device-shim`（`127.0.0.1:20090`）：只绑回环的 HTTP+WS 反代，进程内注入本机 DSH 的会话凭据 | 「垫片」「shim」「薄垫片」 |
+| **覆盖网络节点 · 中继客户端** | `dsh-client` · `<Repo>/lib/net/relay/main.js --client`，由 `overlay-node-daemon.ps1` 监护 | 「设备侧 worker」「worker」「节点进程」 |
+
+### 7.1 写词的规矩（2026-10-15 立 · 口径借 `product-planning` 的语体规范）
+
+- 🔴 **正式名取「读者看得懂」的那个**：界面实显名 ＞ 已确认术语表 ＞ 行业通用词。
+  技术实现名（进程、锁、数据库）不上正式名 —— 「宿主」指的就是 WorkBuddy 那个进程，属此类 ⇒ 正式名改 **`WorkBuddy 本体`**。
+- 🔴 **一个东西一个名**：首次出现写**全称**，之后用上表的正式名；⛔ 不另造简称。
+  （用户 2026-09-30 明令：「垫片」「worker」这类抽象词禁用，一律写「`系统` · `功能名`」。）
+- 🔴 **旧称只作映射**：读到「宿主」「协作程序」「垫片」等旧词 ⇒ 照上表换成正式名。
+  存量旧文**不动字**（改一处带一片，风险大于收益）；**新写的、以及动到那一行时顺手改的**，一律用正式名。
+- 📌 判据来源：`product-planning` 的 `references/stage-proto-doc/references/doc-language-spec.md` §2.1–§2.4。
 
 ---
 
diff --git a/session-mechanism/references/collab-detail.md b/session-mechanism/references/collab-detail.md
index 5d546a6..4fd141f 100644
--- a/session-mechanism/references/collab-detail.md
+++ b/session-mechanism/references/collab-detail.md
@@ -919,20 +919,11 @@ headless chrome ／附着用户 Chrome** ⇒ **不许擅自开浏览器**。但"
 
 ---
 
-## 11 🔴 术语表（**说话／写文档一律用「正式名」这一列**）
+## 11 🔴 术语表
 
-> 2026-09-29 用户指出"宿主是什么／机械程序又是什么，之前只提过**投递**和**常驻程序**" —— 属实：**同一个程序在文件里有 4 个名字**，图当然读不懂。**以本表为准。**
-
-| 正式名 | 实体（在哪） | 干什么 | ⛔ 别再叫它 |
-|---|---|---|---|
-| **宿主** | WorkBuddy 本体 | 提供五样：状态（只读 3 表）／**调度**（自动化排期）／**事件**（钩子）／执行体（会话）／互斥（域锁） | 「平台」「服务端」 |
-| **投递** | `advance-watch.py`（`.workbuddy/tools/`） | 零 token 机械判定：直读 `automation_runs`、判靶点／锁，写 `advance.md` ＋ `needs-ai.json`。⛔ 不派活／不开会话／不联网／不读口令 | 「机械层程序」「机械程序」「看门狗」 |
-| **常驻程序** | `collabd.py`（自述"协作守护程序"） | 队列闸门（`NEXT.md`）＋ **唤醒投递** ＋ 证据分级／真空／断链告警／体检／看板覆写。**⛔ 不做派活** | 「判定层」「常驻程序」「机械层」 |
-| **会话** | `sessions` 表 | 执行体：「读—判—写」；**一次性**、可替换 | —— |
-| **棒** | 一次派活 ＝ 一个会话 | 同一件事的执行单位（「一棒一线」） | —— |
-| **看板** | `boards/会话看板/board.py --serve` → `boards/会话看板/board.html` | **用户唯一入口**（只读旁路 · 异步快照） | ⛔ 别把 `digest.md`（机械摘要）当用户入口；⛔ 也别再提已退役的 `交付物/手机接入-实时状态.md` |
-| **设备接入 · 本地反代** | `dsh-client` · 真身 `@dsh-client/device-shim`（`127.0.0.1:20090`） | 只绑回环的 HTTP+WS 反代，**在进程内注入本机 DSH 的会话凭据**，供覆盖网络中继从设备入口访问桌面 DSH。⚠️ 该包已标「已退役」，计划并入 `@dsh-local/ai1net` 的第 6 块模块**M6「设备接入」**，但**尚未落地**（仓库里还没有 `ai1net` 包） | ⛔ 别再叫它「**垫片**」「shim」「薄垫片」 |
-| **覆盖网络节点 · 中继客户端** | `dsh-client` · `<Repo>/lib/net/relay/main.js --client`，由 `overlay-node-daemon.ps1` 监护 | 本机作为**节点**接入覆盖网络：向中继注册（`registered host=… accepted=[20090]`）、维护长连、转发流 | ⛔ 别再叫它「**设备侧 worker**」「worker」「节点进程」 |
+> 🔴 **正本已收敛到一处**（2026-10-15）：术语表**只有一份** ⇒ `references/architecture.md §7 术语`（说话／写文档一律用那一列）。
+> 本节不再维护表格 —— 曾因两处各存一张而打架：本节写「宿主提供**五样**（含执行体·会话）」，而 `architecture.md §7` 与本节 §1 都写**四样**。
+> 本节只保留**不在正本里**的那部分 ⇒ 下面是 §11.1 命名铁律原文（用户 2026-09-30 明令）。
 
 ### 11.1 🔴 命名铁律（用户 2026-09-30 明令）
 
diff --git a/session-mechanism/scripts/selftest.py b/session-mechanism/scripts/selftest.py
index f24afad..07598e9 100644
--- a/session-mechanism/scripts/selftest.py
+++ b/session-mechanism/scripts/selftest.py
@@ -7881,5 +7881,44 @@ def t_skill_entry_triggers_same_source():
     return rows
 
 
+@case("🔴 术语表只能有一处正本（⛔ 两处必打架 —— 2026-10-15 实测「五样／四样」）")
+def t_term_table_single_source():
+    """🔴 2026-10-15 立（本轮整改"宿主"一词时实测踩到）。
+
+    判据来源：`references/06-技能优化规程.md` 的 **B⑥ 单一真源**。
+
+    实测：`architecture.md §7` 与 `collab-detail.md §11` 各存一张术语表，
+    且对「宿主」给出不同内容 —— 一处写提供**四样**、一处写**五样**（多"执行体·会话"）。
+    已收敛：`architecture.md §7` 是唯一正本，`collab-detail.md §11` 改为指针。
+    ⇒ 判据落在**全包只有一处**带 `| 正式名 |` 表头的表，且那处必须是 `architecture.md`。
+    """
+    rows = []
+    hits = []
+    for p in sorted((HERE.parent / "references").glob("*.md")):
+        try:
+            t = p.read_text(encoding="utf-8", errors="replace")
+        except Exception:
+            continue
+        n = t.count("| 正式名 |")
+        if n:
+            hits.append((p.name, n))
+    try:
+        sk = (HERE.parent / "SKILL.md").read_text(encoding="utf-8", errors="replace")
+        if sk.count("| 正式名 |"):
+            hits.append(("SKILL.md", sk.count("| 正式名 |")))
+    except Exception:
+        pass
+
+    rows.append(("带术语表表头的文件数（应＝1，实测 %d：%s）"
+                 % (len(hits), ", ".join(a for a, _ in hits) or "无"), len(hits) == 1))
+    rows.append(("唯一那处是 architecture.md（术语正本）",
+                 bool(hits) and hits[0][0] == "architecture.md"))
+    rows.append(("术语表里已没有「宿主」当正式名（应改成 WorkBuddy 本体）",
+                 bool(hits) and "| **宿主** |" not in
+                 (HERE.parent / "references" / "architecture.md")
+                 .read_text(encoding="utf-8", errors="replace")))
+    return rows
+
+
 if __name__ == "__main__":
     sys.exit(main())
\ No newline at end of file