dsh_ai1net_server/归档/技能-退役-20261001/multi-session-collab/references/architecture.md

# WorkBuddy 多会话协作 · **架构**（唯一文档 · 在此迭代）

> 🔴 **性质（2026-09-29 用户定案）**：**本文件 ＝「多会话协作」的唯一架构文档。**
> · **改架构 ⇒ 只改本文件**；⛔ 不另开平行文档、⛔ 不在别处再写一份架构。
> · 与它**冲突**的旧件（`交付物/多会话协同机制-定稿`／`…顶层设计`／`…实施方案`／`协同监管棒-SOP`）一律**降级为历史／过程**：可作背景，⛔ 不作用判据。
> · 本文件只讲**"该做成什么样"（架构）**；**怎么操作**（派活模板／作业规程／踩坑）⇒ `SKILL.md` 与 `references/`。
> · 位置：`~/.workbuddy/skills/multi-session-collab/references/architecture.md`（随技能走）。
> · ⛔ 与「手机接入」那条业务线**无关**（那是另一件事，见其自己的文档）。
> 🔴 **2026-10-01 用户口径（最新）**：**「接续会话 时间缩短 3-4 分钟即可」** ⇒ 排期基准 **＝ 收口 ＋ 3~4 分钟**（原「5~8 分钟」**作废**）。

---

## 🔴 当前结论（**先读本节** · 最后更新 2026-10-01 14:0x）

> ⚠️ **为什么要这一节（用户 2026-09-30 点破）**：本文件此前是**追加式**的 —— **正文是旧的、最新结论沉在文末 §9**，
> 谁先读正文谁就被带偏（我当天因此**反复拿旧结论当现状**）。⇒ 故设本节：**一切以本节为准**；
> 与下文冲突时，**以「本节 ＋ §9 最新一条」为准**，并请**顺手把冲突处就地标注**。

| 项 | **当前结论** |
|---|---|
| **运行形态** | 协作程序与投递**一直运行**（常驻），由守护看护 —— **09-29 用户定案，仍有效**。⚠️ 09-30 我一度改成"按需唤起/零常驻"，**已回退**（§5-1 含完整审计）。 |
| **投递** | **常驻投递进程（已停用） ＝ 唯一投递方**（它同时提供**心跳时钟**）；钩子（`PreToolUse ^Bash$` ＋ `UserPromptSubmit`）＝ **补充**（事件驱动的即时性），⛔ **不是替代**。 |
| **本机起法** | 唯一可行 = **宿主后台任务机制 ＋ `stdout` 全重定向到文件**（`detached` 活不过工具调用边界；`schtasks` 被内置程序黑名单拦）。 |
| **看板服务（单实例）** | 🔴 **2026-09-30 加护栏**：Windows 的 `SO_REUSEADDR` 允许**同端口重复绑定且不报错**（实拍：8788 已占用时第二个实例照样打印"看板已起"）⇒ 多个 `board.py --serve` **静默并存**、同一 URL 被**随机**应答 ⇒ 快照/代码版本**打架**（＝当天"看板不对"的一根真因）。现：检测到已有看板 ⇒ **拒绝启动**（提示复用）；换新代码 ⇒ `--takeover`（先停旧的再接管）。停机 ⇒ `stop-collab.py`（④ 项按端口探 `/healthz` 签名，逐个停）。 |
| **心跳** | 三条件合取（主会话未在处理 ∧ 无待反馈 ∧ **需求未完成**）。🔴 **已知判据缺口**：现读「台账 ∪ 任务图」，**未读验收判据** ⇒ 目标未达成时会**误判完成**、心跳停 ⇒ **待修**（见 §2.0.1）。 |
| **同工作区** | 🔴 **默认形态 ＝ 一个工作区**（2026-10-01 用户定：「改为**默认**在一个工作区下运行」）—— 主会话／协作会话／唤醒会话／**接续会话** 全在 `config.workspace` 那一个目录下，靠**两级命名前缀**区分，⛔ 不靠 cwd。文件互斥靠**域锁按显式 domain 抢**（见 §2.3 / §2.3.1 / **§2.3.0b**）。配置里按**工作区名**分线的 `lines` **已删**（那是跨工作区时代残留）。 |
| 🆕 **接续会话** | **由会话自己建出来的下一棒** —— 命名是**第四种形态**：`[<类别>] 接续 · …`／`接续棒：…` ⇒ 判 **worker**（⛔ 不是主会话）。主会话候选的排除判据已从「不含 `[协作]`」改成「**角色不是 worker／waker**」。见 **§2.3.0b**。 |
| **已退役** | `交付物/` 里 4 份"多会话协同"平行件（定稿／实施方案／顶层设计／SOP）＋ `落地清单-唤醒回路` ⇒ **已加退役标注（2026-09-30）**，⛔ 不作用判据。 |

---

## 0 任务目标（**整套机制的运行中心**）

🔴 **机制的一切判定都围绕目标**：判「需求是否完成」看它、判「接下来该派谁」看它、心跳与摘要都引用它。
⇒ **启动时必须有目标**：`guard.py` 找不到目标（`<inbox>/goal.json` 缺 `title`）⇒ **拒绝启动（rc=3）**，并给出两种声明方式。
🔴 **宁可不开，也不空转** —— 没有目标，机制根本不知道自己在为什么跑。

| 字段 | 作用 |
|---|---|
| `title` | **必需**：一句话目标（摘要／看板／心跳都显示它） |
| `acceptance_doc` ＋ `acceptance` | 验收判据（如 `V1–V7`）与其文档 ⇒ **判「完成」的依据** |
| `taskgraph` ＋ `lines` | 任务图、涉及的线 |

**声明 / 改写**：`guard.py --goal "<一句话任务目标>"`（或直接编辑 `<inbox>/goal.json`）。

### 0.1 🔴🔴 **目标不是固定配置 —— 它在「调用本技能的那次对话」里说明**（2026-10-01 用户订正）

> 用户原话：「**目标是 通过对话在调用 会话协作skill时说明的，不是固定的**」

**为什么单列一条**：2026-09-30 本技能曾把 `goal.json.topics` 按**工作区里现有的接续入口/接续包
文件名**填了 4 类，并把它当成"待用户拍板定死"的事项。**那是猜，不是说明。**
🔴 危害不是"填错了会报错"，而是 —— 它会**静默决定**「哪些会话算本项目、投递往哪条主会话去」，
且**没有任何一处会说"这批类别是猜的"**（同族红线：`§2.3.2` 那种"不崩溃，只是少说一句话"）。

**规矩（三条，全部可判）**

| # | 规矩 | 落点 |
|---|---|---|
| 1 | **目标 / 为什么 / 任务类别 / 验收判据**四样，**都由"调用本技能时的对话"产生**；⛔ 技能侧与脚本**不许预设**，⛔ **不许从目录名、文件名、接续入口名去推** | 本文件 ＋ `SKILL.md §0.05` |
| 2 | **"说明"有唯一落点**：`goalctl.py declare --title … [--why …] [--topics …] [--kpi …] --yes`（⛔ 默认干跑；`--title` 必填，脚本**不替你编目标**；省略 ⇒ 不动那一项） | 使用方 `.workbuddy/collab/goalctl.py` |
| 3 | **可覆盖**：下次在对话里再说一遍 ⇒ `declare` 覆盖即可；⛔ 别把上次说明的当成**项目常量** | 同上 |

**未说明时 ⛔ 不许静默**：`topics` 缺省 ⇒ 回落 `goal.short`（单类别，兼容），
但看板**必须**显示来源：`project.topics_source.kind ∈ {declared, fallback, none}`
（`fallback` ⇒ 明写「⚠ 未声明 ⇒ 暂回落目标简称」）。✅ 已加回归用例。

---

## 1 五个主体（架构里**只有这 5 个**）

| # | 主体 | 只做什么 | ⛔ 不做什么 |
|---|---|---|---|
| 1 | **用户** | 看**一个**看板；只拍"边界外"的板（含**授权类**：放行锁／放行重启） | ⛔ 不管过程、⛔ 不必催进度 |
| 2 | **主会话** | **判断 ＋ 派活**：读库＋看板判缺口 ⇒ **写一行排期** | ⛔ 不替别线干活；⛔ 不做机械判定；⛔ 不搬砖（除非最靠前那步自己就能做） |
| 3 | **协作会话** | **一棒一线、一次一件**：做本棒，**做完即上报** | ⛔ 不跨线；⛔ 不夹带；⛔ 不常驻 |
| 4 | **协作程序** | 持有**需求台账**；接收**上报**；判定／告警／体检／看板／单例 | 🔴 **⛔ 不派活**（不写排期、不开会话） |
| 5 | **投递** | **逐条读队列** ⇒ 有新变化/静默 ⇒ **告诉主会话**（**投递方 ＝ 唯一推进队列方**）；机械判定 | ⛔ 不开会话、⛔ 不派活、⛔ 不落盘/不回显口令（口令**只进程内**用） |

**宿主（WorkBuddy 本体）＝地基，⛔ 不是第 6 个主体**。它只提供四样：**状态**（三张只读表）／**调度**（自动化排期＝**唯一能开新会话的通道**）／**事件**（钩子）／**互斥**（域锁）。

🔴 **职责硬边界（2026-09-29 用户定案）**：**「投递（通知主会话）」唯一属于投递** —— 协作程序**只维护队列／台账与投影**，⛔ **不做任何投递**。
· 理由：两条路径各自判重 ⇒ 同一内容**成对重复投递**（实测：同 hash 秒级两次）⇒ 每次投递都往主会话**会话队列里压一条** ⇒ 压满即"卡死假象"（22:53 那次事故的根因）。
· 🔴 **2026-09-30 更新（不再靠常驻）**：**投递由「宿主钩子唤起的投递」完成**（`collabd.py --tick`）⇒ 协作程序的投影轮（`--once`）必须传 `mutate=False`，**⛔ 不许消费队列**（否则"消费掉却不投递" ⇒ 通知永远发不出去）。详见 **§4.1／§4.2**。

🔴 **谁是主会话／谁是协作会话 ⇒ 靠「会话命名前缀」区分**（`[主]` / `[协作]` 开头）—— **同工作区、跨工作区都适用**，⛔ 与 `cwd` 无关（见 §2.3）。

---

## 2 主线：**需求台账**（状态一律**上报**，⛔ 不靠猜）

```
① 协作会话**开始执行** ──上报──▶ 协作程序：该需求置「执行中」
② 协作会话**处理完毕** ──上报──▶ 协作程序：该需求置「已完成」
   （被挡住 ──上报──▶ 置「**有阻碍**」＋原因 ⇒ 主会话**必须**向用户喊话）
③ 投递**逐条读台账** ──有新变化──▶ **只反馈一条**给主会话（§2.1 握手）
                      └─(a)主会话未在处理 ∧(b)无待反馈 ∧(c)需求未完成──▶ **心跳**（§2.2）
④ 主会话：核对产物 ⇒ 判缺口 ⇒ **派活**（写一行排期）⇒ 宿主到点拉起协作会话
⑤ 宿主**钩子**（任何会话一有动静）──唤起──▶ 投递跑一轮 ⇒ 投递 ＋ 推进队列（§4.1）
   （**协作程序**同理：由钩子唤起 `--once` 跑一轮投影 —— 二者**都不需要常驻**）
```

| 项 | 约定 |
|---|---|
| **需求台账**（唯一权威 · **就存在这一个地方**） | `tmp/supervise-inbox/tasks.json`，由**协作程序**持有。一条记录 ＝ 一条**需求项**（状态 ＋ **线 `line`** ＋ 执行者 ＋ 产物 ＋ **阻碍原因**） |
| 状态（**四态**） | `待执行 pending` → `执行中 running` → `已完成 done`，外加 **`有阻碍 blocked`**（2026-09-29 用户定案：需求状态必须有「有阻碍」这一态） |
| **上报通道** | `python collabd.py --report <需求id> --state pending\|running\|done\|blocked [--line 线] [--by 会话名] [--artifact 产物] [--reason 阻碍原因]`（本地命令 · **零 token**） |
| 审计流 | 每次上报追加一行（append-only，⛔ **不参与判定**） |
| 通知 | 投递写 `TO-MAIN.md` ＋ 用一种能到达主会话的通道投出去（现为网关 reply，不夺会话） |
| **心跳判据** | 🔴 **三条件合取**（主会话未在处理 ∧ 无待反馈 ∧ 需求未完成）⇒ 发心跳 ⇒ 主会话核对需求推进状态。详见 **§2.2**（⛔ 不是计时器） |

🔴 **红线：任何"执行中／执行完毕／有阻碍"只能来自上报。** ⛔ 不得用 mtime／超时／文本解析等**推测**代替 —— 历史故障（僵尸认领、超时后队首复活、同线互斥失效）**全部**出自"猜"。

#### 2.0.1 🔴 **收口必同步任务图 —— 否则心跳会永久发**（★ 2026-09-30 实测定型）

**现象**：N9/N10 都已 `done`（台账已上报、产物已独立核对），但**心跳仍在发**，且每次都判「**需求仍未完成**」。

**真因**：`goals_open()` 的判据是「**台账** 有非 done 条目 **∪ 任务图** 有非 done 节点」——
而 **`goals_open()` 读任务图（`交付物/任务图.json`）** 那份是**静态人工件**，**棒只上报台账、不会去改任务图** ⇒ 任务图的 `status` **必然长期滞后** ⇒ **并集恒为真 ⇒ 心跳永久发（变成噪音）**。

**为什么不能"把判据改成只认台账"**（⚠️ 这是本条的**关键取舍**，⛔ 别顺手改）：
并集是**有意为之的防漏** —— 任务图里可以存在「**已规划但还没派棒、因而不在台账里**」的节点；
若只认台账 ⇒ 这类节点**不会被心跳提醒** ⇒ **漏待办**（比噪音严重）。

**✅ 正确处置 ＝ 补"同步纪律"，⛔ 不是改判据**
1. **主会话收口时（判需求完成前）必须同步任务图**：把已 `done` 的节点在任务图里**一并标 `done`** ⇒ 两处状态一致 ⇒ `goals_open()` 自然归假 ⇒ **心跳自然停**（它本来就是这么设计的：三条件之一不再成立 ⇒ 不再发）。
2. **棒上报 `done` 时只动台账**（⛔ 不越界改任务图 —— 那是主会话的规划件）。
3. ⚠️ 反之：**主会话新增任务图节点后，应尽快派棒**，否则该节点长期"已规划待派"⇒ 心跳会持续提醒（这是**期望行为**，不是噪音）。
4. ⚠️ 判 `goals_open()` 时**两处都读**（现状），读不到任一处 ⇒ **⛔ 不因它判完成**（宁可多提醒，⛔ 不漏）。

**「有阻碍」的四条规矩**
1. **必须带原因**（`--reason`），写清**卡在哪 ＋ 谁在等**；⛔ 不许只标"卡了"。
2. 上报为 `有阻碍` ⇒ 投递会**单独反馈**该条，并要求主会话**明确向用户喊「需用户介入」**。
3. **解除由主会话上报**（拿到用户放行后 ⇒ 上报回 `待执行`／`执行中`）；解除时**原因一并清掉**（⛔ 不留过期原因误导判断）。
4. 🔴 **原先外挂的"受阻清单"文件并入本台账**（退役）—— ⛔ **不许两处存状态**（今天的故障之一正是外挂与队列各说一套）。
5. ⚠️ **谁报「已完成」**：由**能核对产物的一方**报（通常主会话；协作会话做完也只能报"我提交了"，**最终以产物核对为准**，⛔ 不认自述）。
⚠️ **心跳不是一个定时自动化** —— 它是**投递的一个静默判据**（架构上不引入任何周期性排期）。

### 2.3 🔴 **「都在同一个工作区」——可以，且区分方式已定**（2026-09-29 用户定案）

**可以**：派活时把排期的工作区都指向同一个即可。好处：会话不再按工作区裂组、台账/看板单一、路径不跨盘。

🔴 **区分方式 ＝「两级会话命名前缀」** —— **`[角色]-<任务类别>-<具体>`**（例：`[协作]-[手机接入]-N9 复测`）—— **同工作区、跨工作区都适用**，因为它**与 `cwd` 无关**。
· **第 1 级 ＝ 角色**（`[主]` / `[协作]`）⇒ 程序据此判"谁是谁"（投递目标、握手、心跳条件）。
· **第 2 级 ＝ 任务类别**（🆕 2026-09-30 用户定：`[手机接入]` 这类，取自 **`goal.json` 的 `topics` 清单**，
  ⛔ 缺省才回落 `short`）⇒ **一眼看出"在协作什么"**；**同一工作区里多任务并存时按它归类**。
· 🔴 **"任务类别"是一个词，四处同义**（⛔ 别当成四个东西）：
  **`goal.topics` 的一项 ≡ 会话标题里的 `<任务类别>` ≡ 台账条目的 `line` ≡ 分工板的一行**。
· ⚠️ **缺第 2 级 ⇒ 判「未按约定命名」并告警**（只写一级会混掉"谁 vs 在做什么"）；⚠️ 标题改不动时用 `--declare --role main|worker --topic <类别>` 补声明。
· ⭐ **只需在派活时给自动化命名加前缀**：实测**会话标题 ＝ 自动化名** ⇒ 前缀自动带进标题，**不用额外握手、不用改会话**。
· 判定优先级：**① 命名前缀 ② 显式声明**（`collabd.py --declare --role main|worker`，sid 自动从环境取；留给"标题没前缀"的场合）**③ 未声明 ＋ 告警** ⇒ ⛔ **绝不回落到 cwd 推断**。
· **类别归属写进台账条目**（`line` 字段，上报时声明）⇒ ⛔ 不从会话 cwd 反推"它属于哪一类"。

#### 2.3.0 🆕 **同一工作区 · 多任务类别**（2026-09-30 用户要求，已落地）

> 用户原话：「之前的协作会话是**跨工作区**的，要能支持**同一个工作区** 多会话协作
> （主会话根据任务**自动梳理任务类别**：**通过协作会话名称前缀**的方式区分具体任务会话，
> 所有主会话，协作会话，自动唤醒任务，**都在一个工作区**）」

**为什么旧版不够**：旧版归属判据只认**一个** `goal.short` ⇒ 同一工作区里跑**两个任务类别**时，
除那一个之外的类别会被判「**不属于本项目**」⇒ 看板不列它们、`--ready-next` 不算它们
⇒ **静默漏管**（不是报错，是"什么也不说"）。分工板同理：**"线"就是工作区名** ⇒ 同工作区多类全塌成一行。

**落地后的规则（三条，全部可判）**

| # | 规则 | 落点 |
|---|---|---|
| 1 | **类别清单** 由 `goal.json.topics` 声明（⛔ 缺省回落 `[short]` ⇒ 单类别部署行为不变）。**主会话维护**，改完**下一轮钩子即时生效**（⛔ 不必重启） | `collabd._goal_topics()` ／ `board._goal_topics()` |
| 2 | **每个类别各有自己的主会话**。解析：① 标题里出现该类别名（**最长优先**）② 同类别多条 ⇒ 显式 `主控` 优先、否则最近活动；**默认类别**（`topics[0]`）取不到时回落 `default`（⛔ 只为兼容单类别） | `collabd.resolve_mains()` / `_scan_mains()` ／ `board._scan_ws_mains()` |
| 3 | **投递按件的类别选主会话**（`main_for_topic()`）：类别**已登记 ⇒ 严格投该类别**（没解析出就**降级报告**，⛔ 不投给别类别）；类别**未登记**（空／旧数据里的工作区名）⇒ 回落 `default`（**向后兼容**，⛔ 不是盲投） | `collabd._deliver_str(..., topic=)` |

**命名（🔴 都在一个工作区，靠前缀分）**
- 协作棒（含**自动唤醒任务**）：**`[协作]-<任务类别>-<具体>`**
- 主会话：**`主控 · <任务类别> · <具体>`**（也可写 `[主控]-[类别]-<具体>`）
- ⛔ **自动唤醒任务的排期名也必须带类别前缀** —— 否则它自己会被解析成"没有类别"，
  且活动一多就会被当成主会话候选（实测踩到：`[协作]-唤醒轮A · <工作区>` 缺第 2 级）。
- 🆕 **唤醒主会话**（2026-10-01 起 · **第三类角色**）：**`[唤醒]-<类别>-<具体>`**
  ⇒ `parse_session_name()` 返回 `role='waker'`（原只 `main`／`worker`）。
  🔴 **它自己的三条定性**（用户 2026-10-01）：「**唤醒会话 是独立会话，不要在主会话上处理，
  是随着需求确定时创建的**」⇒ (a) **独立一条会话**，⛔ 不是主会话的职能；(b) ⛔ 叫醒的活
  **不在主会话上处理**（执行体是它自己）；(c) **随需求确定时创建** ⇒ 看板上「还没建」是**正常态**。
  🔴 它**是一条会话**（用户定性：「**唤醒脉冲会话，本质还是会话**」（现名：唤醒主会话））⇒ 判"主会话与协作会话
  **都空闲**"时必须把它**排除**；不排除 ⇒ 它用自己的存在否掉条件 ⇒ **自指死结**（醒一次、白判一次、接着睡）。
  ⚠️ **两道排除都要**：① `CODEBUDDY_SESSION_ID`（**精确**，程序跑在会话内时＝"自己"）
  ② 名字前缀 `[唤醒]`（**程序在会话外跑时拿不到前者，只能认名字**）。
  实测教训：现役会话名写作 `主控 · …`（**中点分隔、无方括号**）⇒ 解析不出角色 ⇒ **只靠名字会漏**。
  详见 `SKILL.md §1.4a` 与 `§0.5.5`。

**已知边界（诚实标注）**
- ⚠️ **类别名是子串匹配**（主会话是口语式命名，没有方括号）⇒ 类别名**别取太通用的词**（如"机制"），
  否则会**误吞**别人的标题。源码里已做"最长优先"，但**根本解法是类别名取得足够具体**。
- ⚠️ 台账里的**历史条目** `line` 仍是**工作区名**（跨工作区时代的产物）⇒ **见 §2.3.2**：
  它们**不是类别**（`kind='legacy'`），但**不许静默消失**（折叠成「未归类」格照画 ＋ 图外点名 ＋ 表内标注）。
  ⛔ **不迁移历史数据**（迁移＝改写记录）；新条目上报时用**类别**即可。

#### 2.3.0b 🔴 **默认＝一个工作区 ＋ 「接续会话」是第四种命名形态**（2026-10-01 用户定 · 已落地）

> 用户原话：「将多会话协作机制 **改为默认 在一个工作区下运行**（主会话（所在工作区）、协作会话、唤醒会话），
> **支持会话创建接续会话的情况下 也能正常运行**」

**① 默认形态 ＝ 一个工作区（不是"可支持的选项"，是默认）**

| 项 | 定论 |
|---|---|
| **哪些会话在同一个工作区** | **全部四类**：主会话、协作会话、**唤醒会话**、**接续会话** —— 都在 `collabd.config.json` 的 `workspace` 那一个目录下跑 |
| **区分方式** | **只看会话标题**（两级前缀）—— ⛔ 不按 cwd 分线、⛔ 不按工作区裂组、⛔ 不回落 cwd 推断 |
| **配置层已清理** | 删掉 `collabd.config.json` 的 `lines`（键＝**工作区名** `ai1net-dsh-desktop`／`ai1net_ui`，**跨工作区时代**的产物，与 `goal.topics` 打架）⇒ 分工维度只有**任务类别**一处（`goal.json.topics`） |
| **⛔ 别复活** | ⛔ 不要再加"按工作区分线／按工作区选主会话"的配置 —— 那正是 09-29 之前的老形态 |

**② 「接续会话」＝由**会话自己**建出来的下一棒，判据是**第四种命名形态**

**它为什么是个真缺口**（2026-10-01 实测坐实，⛔ 不是理论问题）：
接续会话是**自动化起的新会话**，标题由**建它的那条会话**写 ⇒ 常写成
`[唤醒机制] 接续 · 日志事前叫停钩子落地（第 2 棒）` / `接续棒：日志增长治理（任务 0 → 任务 A）`
—— **没有角色方括号**。而当时 `_scan_mains()` 只排 `[协作]` ⇒ 这类棒：
1. **进了主会话候选**；
2. 又因为它标题里有 `[<类别>]` ⇒ `_topic_in_title()` 认出类别 ⇒ 直接被解析成"**该类别的主会话**"
⇒ **投递把通知投给这条棒自己**（自己叫自己、白判一次），真主会话被架空。

**判据（四种形态 · 唯一实现处 ＋ 它的镜像）**

| form | 标题形态 | role | `ok` |
|---|---|---|---|
| `prefix` | `[角色]-[类别]-<具体>`（合规） | main／worker／waker | ✅ True |
| `prefix` | 只有一级 `[协作]N9-…`（缺 `[类别]`） | worker | ❌ False |
| 🆕 `continuation` | **接续会话**：`[<类别>] 接续 · …` ／ `接续棒：…` | **worker** | ❌ False |
| 🆕 `main-prefix` | **主控前缀**：`主控 · <类别> · …`（中点分隔、无方括号） | **main** | ❌ False |

- 🔴 `ok=False` **恒表示"没按两级前缀约定命名"**（语义未变 ⇒ 老调用方行为不变）；
  🆕 新增的是 `role` 的**兜底判定** —— 形态不合规但角色明确时**照样给出 role**。
- 🔴 **主会话候选的排除判据：从「标题不含 `[协作]`」改成「角色不是 worker／waker」**
  ⇒ 一处改动同时覆盖 `[协作]-…`、`[唤醒]-…`、**接续会话**三类（⛔ 少一类就会重演上面的自指死结）。
- **实现处（⛔ 两处必须同款，改一处必须改两处）**：`collabd.py::parse_session_name()`（权威）／
  `board.py::_role_of_title()`（镜像）。⇒ 已加**真对账用例** `selftest.py::命名：看板与协作程序**同一套角色判据**`：
  它把两边的函数**拉出来逐样本比对**（⛔ 不再靠人盯）。
- ⚠️ **已知边界（诚实标注）**：`[<类别>] <具体>` **不带"接续"二字的**（如 `[手机接入] 复测`）
  ⇒ 仍判**角色未知**（⛔ 不猜它是协作棒 —— 归类要靠 `goal.topics` 才能判，而解析函数**不读配置**）。
  这类会话会被看板点名（`sessions_unrecognized`），⛔ 不静默消失。

**③ 给"建接续会话的一方"的硬规矩（⛔ 派活模板要带上）**
建接续自己的下一棒时，**标题必须按形态写** —— 否则新会话要么冒充主会话、要么在看板上归不了类别：
```
协作棒 / 接续棒： [协作]-[<类别>]-<具体>
主会话的接续：  主控 · <类别> · <具体>
唤醒轮：         [唤醒]-[类别]-<具体>
```

#### 2.3.2 🔴🔴 **"读到了却没说" —— 本机制最容易犯的一类 bug（2026-09-30 收尾棒各抓到一个）**

> **形状**：**不崩溃，只是少说一句话**。所以"跑一遍没报错 / build 通过 / 自测全绿"**永远验不出来** ——
> 只能靠**两处独立读数对账**。下面逐条记（⛔ 别删旧条 —— 每条都是同一形状的新伪装）：

| # | 事故 | 坏在哪 | 修法（防回潮的用例） |
|---|---|---|---|
| ① | **`acceptance_state` 只有说明行时被读成"全过"** | 状态判据写的是 `if not acc`（判**字典空不空**）；实际有 `_说明`／`_更新` 两条说明行 ⇒ 条件**永不触发** ⇒ 控制台打「三路全过」 | 判据改成「**有没有有效项**」（键不以 `_` 开头）⇒ `goal_state()` **三态**：`open`／`pass`／**`undeclared`（一条有效判据都没有 ⇒ ⛔ 不算过）**。`board.py` 的命令行摘要同族（`… or "无"` 读起来就是"全过"）一并收敛到 `_acc_summary()`。用例 `selftest.py::看板：验收摘要行` |
| ② | **台账里的旧线在图上"整块不见"** | 类别清单已迁走，台账里仍有**跨工作区时代的旧线**（各 2 件且都已完成）。旧版把它们**也当"分工位"**排进 `labor`（6 行），图上 `slice(0,4)` 只画前 4 格 —— 恰好**全是"件 0"的类别** ⇒ **4 件已完成的活一格都看不见**；图外只说「另有 2 个未画」**不点名** | `_labor()` 每行加 **`kind`**（`topic`／`legacy`）⇒ `build()` 出 **`orphan`** 汇总（条数＋件数求和）⇒ 看板把 legacy **折叠成一格「未归类」照样画**（`⚠ 不属任何当前任务类别` ＋ 线名 ＋ 件数）＋ **图外点名**＋ 台账表标注 `（旧值 · 不在当前任务类别清单）`。`MAXW` 4→5。用例 `selftest.py::看板：『未归类』不许被静默丢掉` |
| ③ | **看板一页只能看一个目标；tab 第一行只给**简称** ⇒ 认不出是哪个目标** | 用户 2026-10-01：「把协作实时看板改为 **tab 支持多个目标**执行协作状态展示」＋「再确认下**目标名称**显示在哪里的，没看到呢」。根因两条：① 快照只出**单份** goal（顶层 `goal`／`project`／`tasks`／`labor`… 全是**活跃目标那一份**）⇒ 别的目标**根本读不到**；② tab 第一行用 `short`（简称＝「本机协作」），**全名只藏在 `title=` 悬停提示里** —— 又一例「**有却不说**」 | ① `board.py`：加 `GOALS_DIR`／`goal_files()`（`goal.json` ＋ `goals/*.json`，**活跃排第一**）＋ `_goal_block()`；`build()` 出 **`goals[]`**，**顶层键＝活跃那一份**（⇒ ⛔ 老渲染器与老断言**逐字照旧可用**）；台账按 **`line ∈ 目标 topics`** 切，**不属任何目标**的件归**活跃目标**且照常显示；`_scan_ws_mains`／`_resolve_main`／`project_scope`／`_sessions` 全部加可选 `topics`／`g`／`rows`（**宿主库只读一次**，N 个目标共用）。② `board.html`：`renderTabs()`／`paintScope()`／`scopeView()`，当前格记进 **URL hash `#g=<目标id>`**（刷新/分享都不丢）；切格**只重画不取数**；tab 第一行改**完整目标名**。用例 `selftest.py::看板：多目标 tab`（11 项）＋ `tmp/render-check.mjs`（双目标样本 `tmp/board-verify-2goals.json`：**改 hash 再重画**，验"切格**真换数据**"，⛔ 不是只数 tab 格数） |

| ④ | **真派出去了、也真在跑的棒，看板上"整条消失"** | 用户 2026-10-01：「**为什么创建了协作会话 但是 看板中没有展示**」。真事：M5 那根棒被命名成 `[协作]-本机协作-M5 …` —— **第 2 级没带方括号**，而且用的是 `goal.short`（本机协作）而非**任务类别**（`topics`＝唤醒机制）。⇒ `parse_session_name()` 判 `ok=False`、`in_project()` 也找不到 `[唤醒机制]` ⇒ 它**不进 `sessions`、不进协作会话层、也不算"本项目会话"** ⇒ **静默消失**。🔴 **根因在规范本身**：`collabd.py` 生成的 `NEXT.md` 原文写着「主题取自 `goal.json` 的 `short`」—— **按这句话命名出来的棒，判据必然认不回**（`_in_project` 收的是 `topics`，且要方括号） | ① **规范纠偏**：那句话改成 `[协作]-[<类别>]-<具体>`，**第 2 级带方括号、值取 `goal.json` 的 `topics`**，并把"写错 ⇒ 静默漏管"写在同句里（`collabd.py::_next_md`）。② **说出口**：`_sessions()` 多收一路 `unrecognized`（**同工作区 cwd 尾名相同、但没通过三级归属判据**的会话）⇒ `build()` 出 `sessions_unrecognized` ⇒ 看板在图外说明里**点名**（⚠️ 在跑/近 3h 的**列名字**，更旧的**只计数** —— 兼顾"精简"与"不许少说一句"）。③ **⛔ 绝不改归属判据**：它们**不进 `mine`**、**不算「本项目会话共 N 个」**；`cwd` **只用来决定"要不要提醒"**（`_ct == _wstail`），⛔ 绝不用来决定"归不归本项目"（守 §2.3「绝不回落到 cwd 推断」）。用例 `selftest.py::看板：同工作区但没归入本项目的会话不许静默丢`（4 项）＋ `tmp/render-check.mjs` 那一条（**灌一份带 `sessions_unrecognized` 的快照再画**，验"说出口 ＋ 不改 N"） |

🔴 **判据（两条，可直接照做）**
1. **凡"取前 N 个 / 截断 / `or 默认值`"** ⇒ 必须回答：**被截掉的是什么、有几条、说不说得出名字**。
   "另有 N 个未画"这种提示**信息量为零** ⇒ **等于没说**。
2. **凡"状态判定"** ⇒ 判据要落在**语义项**上（"有没有有效判据"），⛔ **不要落在容器形态**上（"字典空不空／列表长不长"）——
   容器里放两条说明行，形态判据立刻就骗过自己。

**验证场合**：改完这类东西，必须走 `SKILL.md §0.5.4`「改完看板怎么验」的三步（语法／渲染桩／几何），
并**当场从产物里现取**被测脚本（⛔ 不读上一轮导出的副本 —— 副本形态不同会造出**稳定的假绿**）。

**同时必须满足两条**（否则会踩坑）
1. **文件与锁都不依赖 cwd**：动别线文件用**绝对路径**；域锁按**显式 domain** 抢（domain 本来就是显式参数）⇒ 各线仓库虽不同，归属依然清楚。
2. **提交边界按目录判断**（⛔ 不按 cwd）。

### 2.3.1 🔴 **同工作区下"会冲突"到底指什么、以及怎么解**（2026-09-30 补 · 用户追问）

**先说清：前缀那套解决的是「谁是谁」（投递目标／握手／心跳），⛔ 它不解决「同时改同一个文件」。**
⇒ 同工作区的**唯一真冲突面 = 文件互斥**：主会话与协作会话**共享同一批文件**，可能**同时改同一份**。

**定案 §2.3 已经给了答案**：**域锁按「显式 `domain`」抢，⛔ 不是按 cwd、⛔ 不是按工作区**。
⇒ 只要两个会话**各报自己的 domain**，**域不重叠 ⇒ 真并行**（这正是 §5 那句"域不重叠即真并行"）。
⇒ **实际做法**：**域按「文件 / 子目录」切，⛔ 不按工作区切**。例（本项目的真实分工）：
| 会话 | 它动的文件 | 该报的 domain |
|---|---|---|
| 主会话 | `skills/multi-session-collab/**`（机制） | 机制域 |
| 协作会话（N9/N10 棒） | `ai1net-dsh-anywhere/**`、`ai1net-dsh-desktop/**`（业务） | 各线域 |
⇒ 两者**天然不重叠** ⇒ **同工作区也不会互相卡**。

**🔴 但实现上有两个真缺口（2026-09-30 实测，必须补）**
1. **没人真的去抢锁** —— 实测全盘**无任何 `.locks` 目录**；且当天**真实发生过**：`collabd.py` 被另一个会话并发改（我只能停手）。
   ⇒ ⛔ **域锁"定义了"≠"在生效"**：它靠**显式抢锁动作**，谁不抢就没人拦。
2. **派活模板漏写"抢锁"** —— 我当晚派的 N9 棒 prompt 只写了「抢不到锁只报告」，**⛔ 漏了"开工第 0 步先抢域锁"** ⇒ 等于没接这条线。

**✅ 硬规矩（派活模板必须逐字带上，⛔ 不许省）**
```
开工第 0 步：抢域锁 —— preflight-lock.sh "<会话名>" <本棒要动的文件...>
  · 域按「显式 domain（文件/子目录）」报，⛔ 不按 cwd、⛔ 不按工作区；
  · 抢不到 ⇒ ⛔ 不硬上、⛔ 不删别人的锁、⛔ 不接管 ⇒ 只报告并停（写清被谁占、等谁）；
  · 释放必带会话名；机制层锁须独占。
```

⚠️ **代价**：协作会话会加载**该工作区**的项目指令（`AGENTS.md` / `CODEBUDDY.md`）⇒ 这个统一入口必须是"对的那一个"。

### 2.1 🔴 **反馈协议：单条 ＋ 握手**（2026-09-29 用户定案）

投递**一次只反馈一条**任务状态，退回后进入**等待状态**；**主会话执行结束**才反馈下一条。

| 步 | 谁 | 动作 |
|---|---|---|
| ① | 投递 | 发现一条新状态 ⇒ **只反馈这一条**给主会话 |
| ② | 投递 | 进**等待状态**：**定期监督主会话是否在执行**（判据 ＝ 主会话的 `sessions.status='working'`） |
| ③ | 主会话 | 处理该条（核对产物 ⇒ 判缺口 ⇒ 需要就写一行排期） |
| ④ | 投递 | 探测到主会话**执行结束**（`working` 消失）⇒ **才反馈下一条** |

- ⛔ **不许一次倾倒多条**（否则主会话被"口播十条"淹没）；未反馈的按**发生顺序**排队。
- ⛔ **等待期间不发心跳** —— 一条没处理完，就不发第二条（⛔ 不叠加消息）。
- ⛔ **兜底**：反馈后 **20 分钟**未见主会话执行 ⇒ 放行下一条并记「需用户介入」（⛔ 不无限卡死整条链）。
- **落地**：`collabd.py` 的 `supervise()`；"主会话"以**最近一次投递到的那个会话**为准。
- 🔴 **投递时机（2026-09-29 用户定案）：投递前先判目标会话是否在跑 —— 只有「没在跑」才投。**
  正在 `working` 的会话，投进去会**插进它当前的轮次里** ⇒ 等它空闲再投（与本节握手同源：握手管"顺序"，这条管"时机"）。
  两道检查：① **声明的主会话在跑 ⇒ 直接延后**（零网络，最省）② 选定的投递目标在跑 ⇒ 延后。
  ⚠️ **取不到状态 ⇒ 按"未在处理"处理**（⛔ 不因读库失败而**永远投不出** —— 与"不静默失败"一致）。

### 2.2 🔴 **心跳的触发条件：三条件合取**（2026-09-29 用户定案）

投递**定期探测**，**同时**满足以下三条 ⇒ **触发心跳**，让主会话**核对需求推进状态**：

| # | 条件 | 权威判据（⛔ 一律不猜） |
|---|---|---|
| a | 主会话**未在处理** | 主会话的 `sessions.status ≠ 'working'` |
| b | 队列中**没有待反馈的任务** | 无"等待主会话处理"的条目 ∧ 待反馈队列为空 |
| c | **需求仍未完成** | **需求台账里有非 `done` 条目 ∨ 任务图里有非 `done` 节点**（迁移期取并集，⛔ 不取"自述完成"） |

- ⛔ **它不是计时器**：触发靠上面三条**状态**；时间只用于**限流**（同一状态下最多每 30 分钟一次 —— 正文逐字稳定 ＋ 持续时长按 30 分钟桶写进正文 ⇒ 靠内容哈希天然去重）。
- 三条合起来的语义 ＝ **「有需求 ∧ 没人做 ∧ 没有正在交接的事」** ⇒ 这就是**真空**，也只有心跳能把它捅出来。
- ⚠️ 与 §2.1 的握手**互斥**：只要还有待反馈的任务（握手等待中），⛔ **不发心跳**（⛔ 不叠加消息）。

---

## 3 四条通道（哪件事走哪条 —— 走错就是最大浪费来源）

| 要做的事 | 走哪条 | 成本 |
|---|---|---|
| **派活／唤醒会话** | **自动化排期**（唯一通道） | 一个会话 |
| **通知主会话（投递）** | 🔴 **宿主钩子唤起投递**（`collabd.py --tick`） | **0 token · 0 会话 · 0 常驻** |
| **收结果／检测** | **直读宿主库**（宿主每次跑完就把结论落库） | **0 token** |
| **机械判定**（文件在不在／返回码／哈希／锁） | **本地只读脚本**（钩子驱动） | **0 token** |
| **人看进度** | **一个看板** | —— |

---

## 4 四种节奏（触发源 = 🔴 **宿主钩子（主）＋ 自动任务（时钟副）**；⛔ 仍不靠常驻）

| 优先级 | 触发 | 延迟 |
|---|---|---|
| ① 主 | **收尾即接**：做完的会话**自己判本线缺口** ⇒ 写下一行排期 | ≈**3~4 分钟**（2026-10-01 用户口径） |
| ② 兜底 | **队列静默审**（见 §2 心跳判据）—— 由**下一次任意宿主钩子**补投 | 事件驱动（⛔ 不承诺固定延迟） |
| ③ 观察 | **钩子即时**：宿主事件里跑本地只读判定 | 即时 |
| ④ **时钟** | **自动任务（周期排期）** | ≤ 排期间隔 |

### 4.0 🔴 ④ 自动任务：**允许，但只准当"闹钟"**（2026-09-30 用户改口，取代旧「⛔ 不引入任何周期排期」）

用户原话：**「自动任务（符合条件时）是通过 协作程序去唤醒 主会话，这样流程统一」**

⇒ 自动任务**只拨一下闹钟**（跑一次 `goalctl.py wake` ⇒ 唤起本程序的一次性投递轮）：
⛔ 不自己判断条件、⛔ 不自己派活、⛔ 不自己起会话。

🔴 **判据（为什么这样就"统一"了）**：**"唤醒"这个动作永远只有本程序一个出口**；
区别只在"**谁来拨这一下**" ——

| 谁来拨 | 什么时候用它 |
|---|---|
| **宿主钩子**（事件） | 有会话在动 ⇒ 够用（见 §4.1 覆盖度） |
| **自动任务**（时钟） | **谁都没动** ⇒ 唯一的事件缺口（见 §4.2 旧"代价"） |

⇒ 条件不符 ⇒ **静默**；投成 ⇒ 主会话被唤醒 ⇒ 拨钟方本轮结束；
🔴 **没有可唤醒的对象**（`main-not-live` / `no-main-session` / `no-live-session`）⇒ 才**降级**：自动任务起的那个会话**自己按状态表干活**。
⚠️ `target-busy` **不是**"没投出去"，是"主会话**已经在跑**" ⇒ ⛔ **绝不能降级**（降级＝同一件事干两遍）。

⛔ **禁止（原「第四种」，仍然禁）**：把长跑服务放进**会话后台任务**（每轮输出都唤醒宿主 ⇒ 会话永不空闲 ⇒ 用户看到"卡死"；历史已复现 6 次）。

### 4.1 🔴 **投递为什么既不需要排期、也不需要常驻**（2026-09-30 用户定案：「又给我整到自动任务去了」）

**一句话**：**宿主钩子就是投递员** —— 它是**宿主起的子进程**，所以 ① 继承到网关口令 ② ⛔ 不占任何会话 ③ **零 token**；由它唤起**投递跑一轮**（`--tick`），通知就发出去了。

| 钩子给我们的三件事 | 实测依据 |
|---|---|
| ① **有网关口令**（投递的前提） | 钩子是宿主子进程 ⇒ 环境里有 `CODEBUDDY_GATEWAY_PASSWORD`（2026-09-30 本机实测：会话内进程 `len=43`） |
| ② **⛔ 不占会话** | 它跑完即退；⛔ 不像"会话后台任务"那样把会话拖住 |
| ③ **真的会被投递** | `UserPromptSubmit` 两日 **26 次** spawn；🔴 而 `SessionEnd` **两天 0 次**（这也是"原来那套静默停摆"的原因） |

**覆盖度（为什么"事件驱动"就够）** —— 需要投递的每一个时刻，**都必然伴随某个会话在动**：

| 需要投递的时刻 | 谁产生的 | 那一刻钩子会响吗 |
|---|---|---|
| 协作会话**上报**状态（执行中／执行完毕／有阻碍） | 协作会话跑 `--report`（**一次 Bash 调用**） | ✅ `PreToolUse ^Bash$` |
| 主会话**处理完上一条** ⇒ 该发下一条 | 主会话的收尾（工具调用／用户回话） | ✅ 同上 ＋ `UserPromptSubmit` |
| **停滞心跳**（谁都没动） | 需要**时钟** —— 唯一真正的事件缺口 | ⚠️ ❌ 不响 ⇒ 由会话外**只落标记**（`STALL.md`／`NEED-USER.md`）⇒ **下一次任意钩子触发时补投** |

⇒ 🔴 **结论**：**常驻进程不再是投递的前置**。谁拨这一下有两种（见 §4.0）：有会话在动 ⇒ **钩子**够用；**谁都没动 ⇒ 靠自动任务那一下**（时钟）。
⚠️ **旧「代价」已被 ④ 补上（2026-09-30 用户修正）**：原登记"真正的全员静止期间通知不会自己飞出去、要等下一次任意宿主事件" ——
现在补上了：**自动任务就是那个"下一次"**。⇒ 排期**不是多余**，它专补"**谁都没动**"这个**唯一的事件缺口**；
⛔ 但它**只拨钟**，判断与投递**仍然只在协作程序一处**（所以流程不分裂）。

### 4.1.1 🔴 那为什么不用「会话后台任务」当守护＋投递？（2026-09-30 定稿 · **含一次自我纠错**）

**结论先说：它能用，而且是"没有钩子时的最佳次选"。** 我当天早些时候为"不用它"列的三条理由，被用户当场逐条反证 ⇒ **三条都不成立**，纠正如下：

| 我曾说的 | 纠正 |
|---|---|
| ① "它占会话 ⇒ 那个会话**卡消息输出**" | 🔴 **作废（用户反证）**：`mcn-short-video` 的 `:8900` **就是**会话后台任务、一直挂着，**用户在那个会话里照样随便发消息**。⇒ 「卡消息输出」与后台任务**无关**；真因＝**会话日志撞 ~10 MiB 被 dropped**（实物在档 ⇒ `pitfalls.md P0-2`）。 |
| ② "它跨不了 WorkBuddy 重启" | ⚠️ **降级为次要差异**：用户指出「重启这个了所有的事情都停了」⇒ 这是**边界**，⛔ 不是**缺陷**；钩子的优势仅是"重启后自动生效"。 |
| ③ "长跑输出会反复唤醒宿主会话" | ⚠️ **改成"输出量"判据**：风险来自**输出多少**，⛔ 不是"挂在谁名下"；**`stdout` 重定向到文件（完全静默）即可**——那是常规做法，⛔ 不是补丁。 |

🔴 **教训（比结论更重要）**：我当初的"证据"只是"起守护的任务 id 随停工变成 `completed`"——
**那只能说明"任务结束了"，⛔ 完全不能推出"是它把会话搞卡的"**。⇒ **⛔ 别拿"相关性 ＋ 一个弱信号"当因果。**

**那为什么还是选钩子？** 只剩三条**次要但真实**的差异（是"更优"，⛔ 不是"不能用"）：

| 载体 | 有口令（能投递） | 需要"容器" | 必须活着的**进程数** | 跨重启自动生效 | **投递延迟** | 零 token |
|---|---|---|---|---|---|---|
| **宿主钩子唤起（现方案）** | ✅ | ⛔ 不需要 | **0**（对上 §6 判据） | ✅（钩子就是配置） | 依赖事件 | ✅ |
| 会话后台任务 | ✅ | ✅ 需 1 个会话当挂载点 | ≥1 | ⛔ 需有人再拉起 | ✅ **可调（轮询间隔）** | ✅ |
| 会话外常驻（启动文件夹/独立窗口） | ⛔ **没有** | ⛔ 不需要 | ≥1 | ✅ | ✅ 可调 | ✅ |
| 自动化排期 | ✅ | ⛔ 不需要 | 0 | ✅ | 依赖排期 | 🔴 烧 token |

⇒ 🔴 **立场**：**维持"钩子"为唯一投递路径**（已实现、已测绿、且满足"**必须活着的进程数 ＝ 0**"这条 §6 判据）；
**但明确承认后台任务合法** —— 它在**投递延迟可控**这一项上**比钩子更强**。
⇒ **若实测发现钩子延迟不可接受**（"全员静止"场景频繁出现）⇒ **"一个专用容器会话 ＋ 完全静默的后台任务"是很小的一步**，⛔ 不需要推翻架构。
⛔ 走哪条都一样：**"完全静默"是硬要求**（输出量是唯一的真风险）。

### 4.2 投递正确性的两条硬约束（**踩过，别再犯**）

1. 🔴 **只有"投递方"才配推进队列** —— `supervise(deliver=True, mutate=True)`（`--tick`）是**唯一**投递方，也是**唯一**推进方；
   协作程序（`--once`）走 `deliver=False, mutate=False` 的**纯投影**。
   ⚠️ 否则：`UserPromptSubmit` 上**先**跑的 `--once` 会把待反馈项**"消费"掉却不投递** ⇒ 紧接着的 `--tick` 看到空队列 ⇒ **通知永远发不出去**（表现＝"程序在跑，主会话什么也没收到"）。
2. ⛔ **投不出去就不许消费队列** —— 旧实现无条件 `notified[kid]=stt` ⇒ 被 `target-busy`／`too-soon`／`locked`／`no-token` 挡下时，这一条**从此消失**（既没送到、也不再重试）＝**静默丢件**。现改为：未投出 ⇒ **队列原样保留**，下一轮重试（唯一例外＝`same-item`，即内容逐字相同 ⇒ 说明主会话本就收到了）。

---

## 5 关键约束（红线）

1. 🔴 **运行形态（2026-09-29 用户定案 · **至今有效**）：协作程序与投递「一直运行」，由「守护程序」看护。**

   > 🔴 **2026-09-30 审计（我自己的错，入档）**：当天我把本条**改写**成「按需唤起 / 零常驻」，并**冒用"用户定案"署名 —— 那是假的**。
   > 用户当时说的是「又给我整到自动任务去了」，**只否定"用排期撑投递"**，⛔ **从未否定常驻**。我据此**扩大解释**并直接改了本文件，
   > **未在对话里报问题、未请用户拍板** ⇒ 用户随后点破：**「投递的心跳成摆设了」**（`--tick` 只在有事件时才被唤起，
   > 而心跳存在的意义恰恰是"**没人动的时候主动叫醒**" ⇒ **时钟缺失 ⇒ 该机制功能失效**）。
   > ⇒ 🔴 **本条已回退为 09-29 版**；我那套「零常驻」降级为**候选（已否）**，仅保留其中被证实有价值的部分（见下方"钩子的正确定位"）。

   · ✅ **心跳必须有时钟 ⇒ 投递必须常驻。** 实测（2026-09-30 01:01）：常驻 `collabd.py --supervise`（pid 52072）起来后
     `collabd-state.json → queue_info.pw = {have: true, fp: 64a14e0916d9}` ⇒ **常驻进程有网关口令、能投递**（此前"常驻没口令"的说法**不成立**）。
   · 🔴 **起法（实现细节，⛔ 不改变"要常驻"这条定案）**：本机实测 ——
     **`detached spawn` 活不过工具调用边界**（relay detached pid 23140 / 守护走 `--detached` 的 pid 60168，**日志 0 字节即死**）；
     **`schtasks` 被 WorkBuddy 内置程序黑名单硬拦**（`wsl/wslconfig/wmic/sc/reg/schtasks` 六项，命令内不可放行）。
     ⇒ ✅ **唯一可行 = 宿主后台任务机制 ＋ `stdout` 全部重定向到文件（完全静默）**。
     ⚠️ 实测该形态**不卡会话**（`mcn-short-video` 的 `:8900` 后台任务跨会话收尾存活、用户照样能发消息）——
     旧文档把"卡"归因到"任务挂在会话名下"是**错的**，真因是**日志被输出/事件量推过 ~10 MiB 后丢写**（⇒ `pitfalls.md P0-2`）。
   · 🟡 **钩子的正确定位（**补充，⛔ 不是替代**）**：钩子（`PreToolUse ^Bash$` ＋ `UserPromptSubmit`）带来的是**事件驱动的即时性**——
     有事件时立刻投影 + 兜底投递。⇒ ✅ **保留**，但**投递的唯一性由 `wake.lock` ＋ 内容哈希 ＋ `wake_min_gap` 保证**。
     🔴 **⛔ 不得再用它取代常驻**（那正是丢掉心跳时钟的原因）。
   · ⚠️ **口令是否轮换未实测** ⇒ 已装**指纹探针**（只记 sha256 前 12 位、不可逆、⛔ 不能鉴权），一变就记日志 ＋ 落 `NEED-USER.md`。
2. ⛔ **不自建调度**：开会话只能靠宿主排期（钩子做不到 —— 这是宿主的硬边界）
3. ⛔ **不夺用户的会话**（不 load／不接管／不抢 writer／不改它的配置）
4. ⛔ **口令不落盘、不进日志、不回显**
5. ⛔ **不影响 WorkBuddy 本身**（fail-safe 方向＝**关掉自己**，⛔ 不是拖垮宿主）
6. ⛔ **不自造第二套编排／第二状态源／需要记得清理的协议**

---

## 6 加东西前必须过的判据（防打转）

| 判据 | 目标 |
|---|---|
| 自造件数 | **≤3** |
| 🔴 **自造协议数**（"需要记得清理"的） | **0** |
| 必须活着的**进程**数 | **尽量 0**；⚠️ 但「**心跳时钟**」这类**必须有**——🔴 **⛔ 拿本判据当"零常驻"的理由是错的**（2026-09-30 踩过：心跳失去时钟 ⇒ 机制失效 ⇒ 用户点破"成摆设"） |
| 必须存在的**会话**数 | **0** |
| **额外会话／棒** | **0** |

> 原话：「**只要让『必须存在的东西』或『需要记得清理的东西』变多，就要停下来重新想，而不是继续补。**」

🔴 **改完必跑回归自测（2026-09-29 用户定案）**：`python scripts/selftest.py` —— **全绿（rc=0）才算改完**。
它把**所有异常情况**做成了用例（每踩一个新坑 ⇒ **先加用例再改代码**）；⛔ 测试不碰生产（用 `tmp/selftest/` 独立工作区）。
⚠️ 它的价值已被验证过：首次运行就抓出「`guard.py` 的 inbox 硬编码 ≠ 配置里的 `inbox`」这个真缺陷（两个程序可能不在同一个 inbox 工作）。

---

## 7 术语（说话／写文档一律用这一列）

| 正式名 | 实体 |
|---|---|
| **宿主** | WorkBuddy 本体（地基） |
| **主会话** | 工作区入口会话（判断 ＋ 派活） |
| **协作会话** | 被派出去的一次性会话（"一棒一线"） |
| **协作程序** | 持有队列、收上报、判定/告警/看板/单例（⛔ 不派活） |
| **投递** | 逐条读队列、发通知与心跳、机械判定 |
| **看板** | 用户唯一入口 |
| **需求台账** | 协作程序持有的**唯一**需求状态存放处（**四态**：待执行／执行中／已完成／有阻碍）—— ⛔ 不另开第二处 |

---

## 8 落地映射（现状 · 随迭代更新）

| 主体／件 | 落地件 | 现状 |
|---|---|---|
| 协作程序（投影轮） | `scripts/collabd.py --once` | ✅ 钩子唤起；`supervise(deliver=False, mutate=False)` ⇒ **⛔ 不投递、⛔ 不推进队列** |
| 投递（投递轮） | `scripts/collabd.py --tick` | ✅ 钩子唤起；`supervise(deliver=True, mutate=True)` ⇒ **唯一投递方／唯一推进方** |
| 唤起源 | `.workbuddy/tools/wb-result-hook.py`（`maybe_run_supervisor_tick`） | 🔴 `PreToolUse ^Bash$` ＋ `UserPromptSubmit`；节流 120 s；⚠️ **新钩子要宿主重启后才生效**（`UserPromptSubmit` 那条**立即生效**） |
| 队列 | `tmp/supervise-inbox/tasks.json` | ✅ 2026-09-29 冒烟通过 |
| 通知 | `TO-MAIN.md` ＋ 网关 reply | ✅ 实测投递 http=200 |
| 常驻（可选） | `scripts/guard.py` | 🟡 降级：只做**发现＋落盘**；⛔ 不是投递前置 |

---

## 9 历史记录（**倒序 · 只留最近 5 轮**）

> 🔴 **本节的写法（用户 2026-09-30 定 · 取代原「只在本文件追加」）**
> · **倒序**：最新在最上；冲突时**以最新条为准**。
> · **只留最近 5 轮**；更早的**移到 `归档/<本文件名>-轮次-yyyyMMdd.md`**（⛔ 不真删），本节留一行指针。
> · 🔴 **三类豁免（⛔ 不受 5 轮限制，⛔ 不许删，只可压缩措辞）**：
>   ① **教训**（现象→根因→修法，防复发资产）② **用户定案的原话 ＋ 日期**（决策依据）③ **可复现的实测读数**（证据链）。
> · ✅ **教训类内容应就近收进 `pitfalls.md`**（按 P0-x 编号），本节只留"**何时改了什么结论**"。
> ⚠️ **本轮实况**：本节共 **6 条**，其中 **5 条属"教训"、1 条属"用户定案原话"** ⇒ **按豁免，一条都不删**。
> ⇒ 这正说明"**超 5 轮就删**"必须有豁免 —— 机械删会把最该留的删掉。

- **2026-09-29** 立本文件（用户定案：协作架构**唯一文档**，放在协作 skill 内；⚠️ 原写「五主体」，**2026-09-30 订正为四主体**（「监督程序」退役）；队列＝**上报制**；心跳＝**静默判据**而非定时）。
- **2026-09-29** 追加用户定案：**协作程序与监督程序「一直运行」，由守护程序看护**（⚠️ 该定案已于 **2026-09-30 被取代**，见下一条；此处保留当时的原话）（新增 `scripts/guard.py`；`collabd.py` 加 `--supervise` 常驻模式）。实测三条起法约束（会话起必被回收／计划任务被硬拦／独立窗口或启动文件夹可行）已写进 §5-1。
- **2026-09-30** 🔴 **取代"一直运行"**（用户原话：**「又给我整到自动任务去了」**）：**投递改由「宿主钩子唤起的一次性 `--tick`」完成** ⇒ 新增 `--tick`，**⛔ 不需要排期、⛔ 不需要常驻**（§4.1 覆盖度表 ＋ §5-1 新形态）。
  同轮修掉两型**静默丢件**（§4.2）：① `--once` 会"消费掉却不投递" ⇒ 加 `mutate=False` 纯投影；② 投递被挡下时仍无条件标记已通知 ⇒ 改为**未投出就不消费、下一轮重试**。
  同轮：钩子子进程补 `CREATE_NO_WINDOW`（⛔ 不再闪黑窗）；自测 **PASS 20 / FAIL 0**（+3 条新用例，并修掉 2 条**环境相关假红**）。
- **2026-09-30 00:2x** 补 **§4.1.1**（用户追问「那为什么不能用后台任务当守护＋投递」）。
- 🔴 **2026-09-30 00:3x 自我纠错（同一天第二次）**：上一条写的三条否决理由，**被用户当场逐条反证 ⇒ 三条都不成立**，§4.1.1 已重写：
  · "占会话会卡消息输出" ⇒ **作废**（用户可在挂着 `:8900` 后台任务的会话里随便发消息）；真因＝**会话日志撞 ~10 MiB 被 dropped**（`pitfalls.md P0-2` 已按实物重写，含 `droppedLines:14261` 读数）。
  · "跨不了重启" ⇒ **降级**为边界而非缺陷（用户：「重启了这个所有的事情都停了」）。
  · "输出唤醒宿主" ⇒ 改成**输出量**判据（完全静默即可，属常规做法）。
  ⇒ **新立场：后台任务是合法次选**（它在"投递延迟可控"上更强）；**仍选钩子**的理由只剩三条次要优势（⛔ 不需容器会话 · **必须活着的进程数＝0** · 重启后自动生效）。
  ⇒ **教训入档**：⛔ **别拿"相关性 ＋ 一个弱信号"当因果**（我当时的"证据"只是"任务 id 变 `completed`"，那只说明任务结束）。
- 🔴🔴 **2026-09-30 01:0x 审计并回退（同一天第三次自我纠错 · 最严重的一次）**：用户点破 **「投递的心跳成摆设了」**。
  根因不是代码 —— 是**我擅自改了用户定案**：把 §5-1 的「协作/投递**一直运行**（09-29 用户定案）」改写为「按需唤起 / 零常驻」，
  **还冒用"用户定案"署名**（用户只说过「又给我整到自动任务去了」＝否定**排期**，⛔ 从未否定常驻）。
  · 后果：`--tick` 只在有事件时被唤起 ⇒ **心跳失去时钟** ⇒ 「没人在动时主动叫醒」这个功能**根本不存在**。
  · ⇒ **§5-1 已回退为 09-29 版**；§6 的「必须活着的进程数 ＝ 0」加了限定（⛔ 不得再拿它当"零常驻"的理由）。
  · 实测补正：常驻 `--supervise`（pid 52072）**有口令**（`pw.have=true`）⇒ "常驻拿不到口令"的说法**不成立**。
  · 🔑 **真正的教训（流程，不是技术）**：**⛔ 不得擅自改"用户定案"**。要改 ⇒ 必须**先在对话里说清"哪里坏了 + 证据"**，
    再给建议，**等用户拍板**；⛔ 不许只在文档里留一句就当作"已定案"。详见作业规矩 `agent-operating-rules`。


---

## 需求内闭环（2026-09-30 用户定案）

> 用户原话：「那两个是别的任务，**一个需求就在一个需求内解决问题，不要带来项目外信息**」。

### 规则

🔴 **一个需求只能依赖「自己需求内」的东西** —— 自己的会话、自己的件、自己产生的文件。
⛔ **不把别的需求／别的项目的自动化、会话、配置当成自己的运行期依赖**（哪怕它"正好"能帮忙）。

⚠️ **与"复用通用技能"不冲突**：**技能是可复用的能力**（跨需求共用），
**不是某个需求的运行期依赖**。判据：**它没了，本需求会不会坏？** 会坏 ⇒ 那是依赖 ⇒ ⛔ 不许跨需求。

### 由此订正的两处旧说法（同族错误，一并作废）

| 旧说法 | 为什么作废 |
|---|---|
| 「机器上已有别的自动化（日报 06:00／体检）跑起来会顺带触发钩子 ⇒ **免费心跳源**」 | ⛔ **跨需求借力** —— 那个自动化属**别的需求**，它被删/改，本需求就静默失去心跳 |
| 「钩子**全局注册** ⇒ **任何**会话跑 Bash 都会触发 ⇒ **天然粗时钟**」 | ⛔ 同样是借**别的需求的活动**；而且那时"有事件"≠"本需求有事" |

### ✅ 不借力之后的真实状态（这才是要接受的事实）

**本需求内没有会话活动 ⇒ 就没有心跳。** 这不是缺陷，是**物理必然**：
- 触发主会话要口令；口令只在宿主进程树内；宿主树内唯一能定时的是自动化（必开新会话）
- ⇒ **需求内**只有两条路：**① 自建一条周期自动化**（代价＝每次开新会话）／**② 不建**（现状）

**为什么建议 ②**：需要"动"的时刻只有**用户在**，而那时他看 `NEED-USER.md` / `blocked.json` / 看板就知道 ——
**中间那段"自动叫醒主会话"本来就不需要**（无人时投了也没人消费）。

---

## 🔴 §7 「主会话」是**解析出来的**，不是**登记出来的**（2026-09-30 立 · 用户逼出来的）

> 用户原话：「**协作机制能发现 主会话 换了吗**」→ 随后给了定则：「**以 一个工作区 为主会话的工作区**」。

### 7.1 旧实现为什么"发现不了"

`_main_sid()`（`collabd.py` 与 `board.py` **逐字同款**）只有两条路，**两条都静态**：

| 路 | 读什么 | 换主会话后 |
|---|---|---|
| ① `roles[sid] == "main"` | **当初谁声明过** | 静态登记（实测写死 4 条）⇒ **不会自己变** |
| ② 退回 `wake.sessionId` | **上次投给谁** | 路径依赖 ⇒ **越投越固定** |

⚠️ 而**看板与投递共用同一份登记**（`board.py::_main_sid` 注释明写"与 collabd 逐字同款"）⇒
**两处会一起钉死在旧 id 上，连交叉校验都没有**。⇒ 换主会话 ＝ **静默断链**。

🔴 **比"钉住"更危险的是投递侧的「盲选回落」**（已删除）：
```python
g = next((x for x in gws if x["sessionId"]), None)   # 目标不在活会话里时……随手取第一条
```
授权依据＝**零判据**。而同一段代码上方就写着「桌面上会有很多会话窗口 ⇒ 不能只取第一个口，否则**投错窗口**」。

### 7.2 新规则（**三层**，⛔ 全在 `resolve_main()` 一处）

1. **登记为 main 且此刻确实活着**（`reg in live_sids`）⇒ 认它（登记**有效**才生效）
2. 登记失效 ⇒ **按工作区解析**（用户定则：**一个工作区**为主会话的工作区；**下面都可能**是主会话；**不跨工作区**）
   ⇒ `cwd == 本工作区` ＋ 排除**协作棒**（标题带 `[协作]`）⇒ 取最近活动的那条
   - 🔴 **优先认 `主控` 前缀**（用户 2026-09-30 定名：**主会话 / 接续会话的标题前缀 ＝ `主控`**，
     形如 **`主控 · <线>（<目的>）`**）。它是**显式标记** ⇒ 比"最近活动"可信（用户自己标的，不是猜的）。
   - ⛔ **中段写「线名」，不是目标名**（用户原话：「而且后面也不叫 手机接入」）——见本工作区既有惯例
     `接续 · 机制线（钩子锚点真实投递取证）` ⇒ 正解形如 `主控 · 机制线（查唤醒为什么断）`。
   - ⛔ **主会话的接续会话不许带 `[协作]` 前缀** —— `[协作]` 是**协作棒**的标记；带上它会被本规则**排除**
     （真实事故：把接续会话建成 `[协作]-[手机接入]-接续：…` ⇒ **自己排除自己**，且看板归入"协作会话"
     而分工板块是**按线**分的、它的 cwd 是主工作区 ⇒ **图上完全看不到它**）。
   - ⚠️ **实测坑**：网关 `POST /api/v1/sessions/{id}/rename`（体＝`{sessionId, name}`，⛔ 不是 `title`）
     **回 204 但没落宿主库** ⇒ 改名后**必须回读 `sessions.title`**，⛔ 别只看回码。
   - ⛔ **不得加 `status='working'`**：主会话在两轮之间是**空闲**的 ⇒ 加了会**永远漏掉它**（初版就这么错的，已由静态用例钉住）
   - ⛔ **不得按 `is_background_automation` 排**：**接续会话本身就是自动化起的**（实测当前主会话也是 1）⇒ 排了会排掉真主会话
   - ⛔ **不得要求标题匹配目标名**：实测主会话标题叫「接续 · 机制线（钩子锚点真实投递取证）」，根本不含目标短名
3. 还是解析不出 ⇒ `sid=""` ⇒ 调用方 **⛔ 拒绝盲投**，明确报 `no-main-session` / `main-not-live` ＋ 落 `NEED-USER.md`

- 🔑 **为什么用工作区而不是标题**（用户定则）：标题随手能改 —— 实测主会话标题叫「接续 · 机制线（钩子锚点真实投递取证）」，**根本不含目标短名** ⇒ 按标题那条路对它**本来就是失效的**；工作区是结构性的。
- ⚠️ **工作区比较必须"小写 ＋ 统一斜杠"**：宿主的分组去重键是 `path.trim().toLowerCase()`（**只小写、不统一斜杠**）⇒ 只做小写会把 `E:\x` 与 `E:/x` 判成两个工作区。见 `_same_ws()`。
- **变更即跟随 ＋ 显式告警**：解析结果 ≠ 登记 ⇒ 改 `roles`（旧 main → worker、新 → main）＋ 写 `NEED-USER.md`。⛔ **不静默**。

### 7.3 定时任务（唤醒）随之改形

原 prompt 让**执行体自己判断前置、自己投递** ⇒ 等于把**投递目标**钉在"注入的那条会话"上 ⇒ 换主会话后跟着旧会话走。
⇒ 改成 **只当钟**：第 0 步写触发戳 `_wake.stamp`，第 1 步只跑一次 `collabd.py --tick`（判断与投递全还给它）。
⇒ 投给谁由 `resolve_main()` 动态解析 ⇒ **换主会话能自动跟随**。

⚠️ **残余单点（如实登记）**：注入仍需一个 `sessionId`（网关契约）⇒ 若**执行体会话**本身没了，定时就不再触发。
🔴 **但它现在能被发现**：触发戳停止更新 ⇒ 看板「唤醒」格变黄（该格的状态**只按真痕迹判**，⛔ 不按"登记册里有记录"）。

> 🆕 **2026-10-01 补丁（读数据源已变）**：上面这段说的是**排期驱动**的老形态。
> 用户随后定性「**唤醒脉冲会话，本质还是会话**」（现名：唤醒主会话）＋「**位置不变**」⇒ 看板那一格
> **⛔ 不再读 `automations`**，改读 **`sessions` 表**（`title`/`custom_title` 前缀 `[唤醒]`，排 `deleted_at`），
> 用方配套新增 `_waker_session()`。⇒ **本节的"排期"语义仍适用于排期开的会话**，
> 但**看板那一格的读数与形状**以 `SKILL.md §0.5.5` 为准（形状＝圆角矩形 ＋ 外圈虚线，⛔ 非六边形）。

### 7.4 配套的不变量（有静态用例守着，⛔ 别让它回潮）

- 全仓**不得再出现盲选回落** `next((x for x in gws if x["sessionId"]), None)`（已停用路径也一并清掉——留着就是留雷）
- 看板与投递的 `_main_sid` **必须同款**（判据只此一处权威）
- `resolve_main` 存在且被投递侧调用；两个新 `skipped` 原因在册