151 lines
14 KiB
Markdown
151 lines
14 KiB
Markdown
|
# 接续包 · 会话机制 → 合并为一个技能包（2026-10-01）
|
|||
|
|
|
|||
|
|
> ## §0 状态（**最新行在最上**）
|
|||
|
|
> | 时间 | 会话 | 发生了什么 |
|
|||
|
|
> |---|---|---|
|
|||
|
|
> | 2026-10-01 14:59 | `会话机制合并包-任务234` | 🔴 **本包已续期 ⇒ 后续一律看 `接续包_会话机制合并技能包-任务234_20261001.md`**（任务 2/3/4 ＋ 归档）。硬档停手（日志 8.02 MiB）。🔴 **推翻本包 §3.4 第 4 条**：转发壳**不可行**（8/9 脚本按自身位置推根 ＋ `settings.json` 钩子条目无 `env` 字段）⇒ 改用**包内 `roots.env` 外置根目录**（已落地 8+1 份补丁，语法全过）。沙箱验收 **5 项过 4 项**。 |
|
|||
|
|
> | 2026-10-01 14:2x | `会话机制合并包-任务0` | ✅ **任务 1 完成**：新包 `~/.workbuddy/skills/session-mechanism/` 已建成 —— **27 个文件全部 `cp` 拷入（⛔ 零 `mv`）**，`py_compile` / **Git-Bash** `bash -n` / `json.loads` 全通过（失败 **0**），且与源**逐字节 md5 一致**；清单见包内 `references/manifest.md`。**旧路径全部原样可用**。 |
|
|||
|
|
> | 2026-10-01 14:2x | `会话机制合并包-任务0` | ✅ **任务 0 完成**：正式方案落盘 `$WS/交付物/会话机制合并技能包-方案-20261001.md` —— 方案对比 **A（单一实现＋转发壳，建议）/ B（mv 全改引用，淘汰）/ C（只做配置器，需求未达淘汰）/ D（硬链接，淘汰）**＋ **红线 R1–R11 逐条自查**（含 R5 权限影响评估、R11 十维自查、R7 拷贝清单）＋ 执行顺序与验收 ＋ 风险回滚。 |
|
|||
|
|
> | 2026-10-01 14:2x | `会话机制合并包-任务0` | 🔴 **更正一处错数**：`$WS/.workbuddy/collab/` **非空**（实测 9 文件 ＋ 4 子目录）⇒ 运行态**源在 `collab/` 而非 `tools/`**；误判成因＝`ls -1 目录A 目录B \| sort` 把两目录输出**合并排序**。已在方案 §2.5 回填 + 踩坑记录。 |
|
|||
|
|
> | 2026-10-01 14:2x | `会话机制合并包-任务0` | 🔴 **下一棒 = 任务 2（写 `install.py`）**；⛔ 开工前**先只读取证**「WorkBuddy 是否读 `~/.workbuddy/AGENTS.md`」。⚠️ 本会话已反序释放锁 ⇒ 接续会话须自己重抢（机制层＝独占，⛔ 不带 `--domains`）。 |
|
|||
|
|
> | 2026-10-01 13:59 | `334140d1` | ⛔ **硬档停手**：本会话诊断日志 **8.03 MiB / 10 MiB**（≈53 次调用余额）⇒ 按 §G 硬档只做到「盘点」就落包停手。**本轮未改任何机制文件**（零改动、零风险）。 |
|
|||
|
|
> | 2026-10-01 13:59 | `334140d1` | 已持**全局独占锁**；本包写完即反序释放 ⇒ **接续会话须自己重新抢**（机制层，走独占，⛔ 不带 `--domains`）。 |
|
|||
|
|
>
|
|||
|
|
> **本包 §3 = 已取证的现状（省掉重跑盘点）；§4 = ⛔ 不要重做清单；§2 = 任务，一次只做一件。**
|
|||
|
|
> 🔴 **任务 0 / 1 已由 `会话机制合并包-任务0` 完成** ⇒ 接续会话**直接从 §2 任务 2 开始**，⛔ 不要重做 0 / 1。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## §1 用户原话与目标（2026-10-01 13:5x）
|
|||
|
|
|
|||
|
|
> 「整合 会话机制相关技能为一个skill包 ， 在将多会话协作机制 也整合到这个技能包，要求换一台电脑的 workbuddy 上运行也能自动完成配置，让所有会话遵循 会话机制，并且可独立使用 多会话协作」
|
|||
|
|
|
|||
|
|
拆成四条硬要求：
|
|||
|
|
1. **一个技能包**装下「会话机制」相关技能；
|
|||
|
|
2. **多会话协作机制**也并进同一个包；
|
|||
|
|
3. **换一台电脑** ⇒ 跑起来能**自动完成配置**（不是手抄 14 处钩子、不是手改绝对路径）；
|
|||
|
|
4. **所有会话遵循会话机制**（全局生效）＋ **多会话协作可独立使用**（不装也行、装了不依赖旁件）。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## §2 待做任务（🔴 一次只做一件，做完即停）
|
|||
|
|
|
|||
|
|
### 任务 0 · 定界与设计落盘（**本任务已完成一半 ⇒ 见 §3.4 已定项；剩下是把方案写成正式文档**）
|
|||
|
|
1、把 §3.4 的「已定项」写成 `$WS/交付物/会话机制合并技能包-方案-20261001.md`（方案对比表 ≥2 项 ＋ 利弊 ＋ 建议，按 §1.5 B 阶段 2）。
|
|||
|
|
2、红线 R1–R11 逐条自查，尤其 R5（权限影响）与 R9（锁）。
|
|||
|
|
|
|||
|
|
### 任务 1 · 建包骨架（先读 §3.4 已定项，⛔ 不要另起设计）
|
|||
|
|
1、建 `~/.workbuddy/skills/session-mechanism/`，按 §3.4 的目录表放文件。
|
|||
|
|
2、机制脚本用 **`cp` 从现址拷入**（⛔ 不 `mv`）—— 保证任何时刻旧路径都还能用。
|
|||
|
|
3、拷完逐个 `py_compile` / `bash -n`，并算 md5 记进包的 `references/manifest.md`。
|
|||
|
|
|
|||
|
|
### 任务 2 · 写 `install.py`（本包的核心交付物 = 「自动完成配置」）
|
|||
|
|
1、按 §3.4 第 5 条实现：钩子接线（幂等 ＋ 备份 ＋ `--dry-run` ＋ `--uninstall`）＋ 工作区初始化 ＋ `--verify`。
|
|||
|
|
2、⛔ 不许硬编码 Python 路径（一律 `sys.executable`）、⛔ 不许硬编码盘符（配置目录按 `CODEBUDDY_CONFIG_DIR` 推导）。
|
|||
|
|
|
|||
|
|
### 任务 3 · 本机实测（⛔ 不许只测 happy path）
|
|||
|
|
1、`--dry-run` 先看 diff；再真装；再 `--verify`。
|
|||
|
|
2、**必测**：跑两遍（幂等 ⇒ 第二遍零改动）／`--uninstall` 后 settings.json 与备份**逐字节同**／钩子仍能 rc=0。
|
|||
|
|
|
|||
|
|
### 任务 4 · 文档与收口
|
|||
|
|
1、写包内 `SKILL.md`（两段可分别加载：会话机制 / 多会话协作）、`references/deploy.md`（换机器）。
|
|||
|
|
2、`07-scripts/` 转发壳（见 §3.4 第 4 条）—— 这一件**有 blast radius，放最后做**。
|
|||
|
|
3、三层沉淀（技能／教训／记忆）＋ 反序释放锁。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## §3 已取证的现状（🆕 2026-10-01 13:5x 实测，⛔ 不要再重跑盘点）
|
|||
|
|
|
|||
|
|
### 3.1 「会话机制」的家当散在**三个互不相干的地方**
|
|||
|
|
|
|||
|
|
| 落点 | 装了什么 | 规模 |
|
|||
|
|
|---|---|---|
|
|||
|
|
| `~/.workbuddy/skills/multi-session-collab/` | 协作机制本体：`collabd.py` 177 KB / `board.py` 67 KB / `guard.py` / `selftest.py` ＋ `references/{architecture 64 KB, deploy, pitfalls, taskgraph}` ＋ `assets/` | 14 文件 |
|
|||
|
|
| `D:/github/dsh_shenxian/dsh-server-docs/07-scripts/` | **宿主钩子 ＋ 锁**：`handoff-guard.sh` 34 KB、`preflight-lock.sh`、`handoff-status.py`、`op-lock.sh`、`lock-guard-hook.py`、`session-log-guard.py`、`stop-dialog-guard.py`、`skill-load-guard.py`、`bash-output-guard.py`（＋与机制无关的 docs-* 共 29 文件） | 9 个属机制 |
|
|||
|
|
| `$WS/.workbuddy/collab/`＋`.workbuddy/tools/` | 运行态：`collabd.config.json`、`goalctl.py`、`wake-session.py`、`board_ext.py`、`wb-result-hook.py`、`stop-collab.py` | 26 文件 |
|
|||
|
|
|
|||
|
|
⚠️ **这就是合并要解决的第一性问题**：机制本体在 skill、钩子与锁在文档库、运行态在工作区 —— 换机器要同时搬三处。
|
|||
|
|
|
|||
|
|
### 3.2 宿主钩子接线现状（`settings.json` 实测 · 共 **14 处** · 指向 **3 个不同目录**）
|
|||
|
|
|
|||
|
|
| 事件 | matcher | 指向 |
|
|||
|
|
|---|---|---|
|
|||
|
|
| PostToolUse | （空） | `07-scripts/session-log-guard.py`（`-S` 调用） |
|
|||
|
|
| PreToolUse | `^AskUserQuestion$` | `ai1net-decision-laya/bridge/decision_bridge.py` |
|
|||
|
|
| PreToolUse | `^Bash$` | `$WS/.workbuddy/tools/wb-result-hook.py` |
|
|||
|
|
| PreToolUse | `Write\|Edit` | `07-scripts/lock-guard-hook.py` |
|
|||
|
|
| PreToolUse | `Bash\|Read` | `07-scripts/bash-output-guard.py` |
|
|||
|
|
| SessionEnd | （空）×2 | `decision_bridge.py` ／ `wb-result-hook.py` |
|
|||
|
|
| SessionStart | `startup\|resume` | `07-scripts/lock-guard-hook.py` |
|
|||
|
|
| SessionStart | （空） | `decision_bridge.py` |
|
|||
|
|
| UserPromptSubmit | （空）×5 | `decision_bridge.py`／`wb-result-hook.py`／`stop-dialog-guard.py`／`skill-load-guard.py`／`session-log-guard.py`（`-S`） |
|
|||
|
|
|
|||
|
|
⚠️ **全部硬编码 python 绝对路径**（`E:\ProgramData\.workbuddy\binaries\python\versions\3.13.12\python.exe`）⇒ 换机器必碎。
|
|||
|
|
⚠️ `decision_bridge.py` 属**另一条线**（`ai1net-decision-laya`），⛔ **不并入本包**。
|
|||
|
|
|
|||
|
|
### 3.3 引用面（搬动前的 blast radius 实测）
|
|||
|
|
|
|||
|
|
`handoff-guard` 被引用：文档库 **5** 处 ／ 工作区 **2** 处；`preflight-lock` 2／1；`op-lock` 3／0；`lock-guard-hook` 3／0；`session-log-guard` 3／0；`stop-dialog-guard` 6／0；`skill-load-guard` 4／0；`bash-output-guard` 5／1。
|
|||
|
|
⇒ **不能直接 `mv` 走**（会静默弄坏文档库的锁与文档检查链）。
|
|||
|
|
|
|||
|
|
### 3.4 🔴 已定项（本轮已拍板 · 接续会话照此执行，⛔ 不要重新设计）
|
|||
|
|
|
|||
|
|
1. **包名与落点**：`session-mechanism`（=`~/.workbuddy/skills/session-mechanism/`）。理由：用户原话就是「会话机制」，不与既有 `multi-session-collab` 抢名。
|
|||
|
|
2. **包内目录（草案）**：
|
|||
|
|
```
|
|||
|
|
SKILL.md # 总入口；两段可分别加载：「会话机制」/「多会话协作」
|
|||
|
|
install.py # 🔴 自动配置（本包核心）
|
|||
|
|
references/{architecture,deploy,pitfalls,taskgraph,collab,rules,forensics,manifest}.md
|
|||
|
|
scripts/hooks/ # 宿主钩子 6 份（自包含，⛔ 不再依赖 07-scripts）
|
|||
|
|
scripts/lock/ # handoff-guard.sh / preflight-lock.sh / handoff-status.py
|
|||
|
|
scripts/collab/ # collabd.py / board.py / board_ext.py / goalctl.py / wake-session.py / guard.py / selftest.py
|
|||
|
|
scripts/forensics/ # proc-parent.py
|
|||
|
|
assets/ # board.html / design-tokens.css
|
|||
|
|
```
|
|||
|
|
3. **哪两个技能并入**：`multi-session-collab`（机制本体）＋ `workbuddy-session-forensics`（会话取证）。
|
|||
|
|
⚠️ **`agent-operating-rules` 判为「不并」**（它是跨项目「作业总规矩／说话方式」层，被大量模板引用）⇒ 只在包内 SKILL.md 里**声明依赖**。
|
|||
|
|
🔴 **这一条是**有取舍的判断 ⇒ **留给用户在任务 0 时一句话推翻**（推翻成本低：多拷 4 个 references）。
|
|||
|
|
4. **单一实现源 ＋ 转发壳**（解法 = 唯一实现 ＋ 零 blast radius）：机制脚本的**唯一实现放包内**；文档库 `07-scripts/<同名>` 改成 **3 行转发壳**（`exec` 包内那份），⛔ **不删原件**、⛔ 不动物流。
|
|||
|
|
⚠️ 理由：`pitfalls` 明写「同名的两份实现是最难查的故障」（实测两份同时跑给出互相矛盾读数）。
|
|||
|
|
5. **`install.py` 五项职责**：① 自解析（`sys.executable` ＋ `CODEBUDDY_CONFIG_DIR`）② 钩子接线：**声明表驱动**（14 处 → 一张表，`decision_bridge` 那条排除在外）、**先删自己旧条目再插**、写前备份、`--dry-run`、`--uninstall` 逐字节还原 ③ 工作区初始化：`--workspace <path>` ⇒ 由 `collabd.config.example.json` 生成 `collabd.config.json`（路径按本机推导）＋ 写工作区规则锚 ④ `--verify`：每个钩子跑空载荷须 rc=0 ＋ `collabd.py --where` ＋ `selftest.py` ⑤ 全部写操作写 `install.log`。
|
|||
|
|
6. **「所有会话遵循」的注入面**：已确认可用的是 ① 全局钩子（`settings.json` 全局生效）② 技能全局可见 ③ `~/.workbuddy/MEMORY.md`（用户级记忆，跨会话注入）。
|
|||
|
|
⚠️ **未取证**：WorkBuddy 是否读 `~/.workbuddy/AGENTS.md` —— `app.asar.unpacked/cli/dist/codebuddy-headless.js` 与 `codebuddy-lite-wb.mjs` 里出现 `AGENTS.md` 字样 ⇒ **任务 2 开工前先只读取证**（⛔ 别猜）。
|
|||
|
|
|
|||
|
|
### 3.5 本轮**没有**改任何文件
|
|||
|
|
只新增：本包（`$WS/接续包_会话机制合并技能包_20261001.md`）＋ `tmp/inv-20261001/`（两个只读盘点脚本）＋ 今日日志一段。⛔ 机制文件零改动 ⇒ 无回滚负担。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## §4 ⛔ 不要重做 / 撤回清单
|
|||
|
|
|
|||
|
|
- ⛔ **不要重跑全库盘点**：§3.1–3.3 就是实测结果（文件数 / 字节 / 钩子 14 处 / 引用面），直接引用。
|
|||
|
|
- ⛔ **不要 `mv` 机制脚本**，一律 `cp` 后再改接线；移除只在「转发壳验完」之后。
|
|||
|
|
- ⛔ **不要动 `decision_bridge.py` 所在的线**（`ai1net-decision-laya`）—— 它只是恰好出现同一张钩子表里。
|
|||
|
|
- ⛔ **不要改 `settings.json` 而不备份**：本目录已有 6 份 `.bak-*` 先例，命名沿用 `settings.json.bak-<用途>-<日期>`。
|
|||
|
|
- ⛔ **不许报未经实测的系数**（延续上一包 §4）：本包只允许写「本轮实测到的字节数 / 计数」。
|
|||
|
|
- ⛔ **不要动自动化排期**（用户明令；唯一例外＝本包自己登记的那条接续会话，已完成）。
|
|||
|
|
- ⛔ **不要在会话里起常驻后台任务**（会把会话日志推过 10 MiB ⇒ 界面静默哑掉）。
|
|||
|
|
- ⛔ **不要为验收烧调用次数**：本会话就是因为跑到 8.03 MiB 才停的手，接续会话预算 ≈ 53 次调用 ⇒ **盘点类动作一律复用 §3**。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## §5 验收判据（任务 3 逐条打钩，⛔ 不许「本机改完了」当交付）
|
|||
|
|
|
|||
|
|
1. `install.py --dry-run` 打印的 settings.json diff 与预期一致；真装后**再跑一遍 ⇒ 零改动**（幂等）。
|
|||
|
|
2. 装机后立刻 `--verify`：6 个钩子空载荷全 rc=0；`collabd.py --where` 路径正确；`selftest.py` **PASS / FAIL 0**。
|
|||
|
|
3. `--uninstall` 后 `settings.json` 与装前备份**逐字节相同**（`cmp` 通过）。
|
|||
|
|
4. 转出路径验一次：把包拷到**另一个目录**再跑 `install.py` ⇒ 钩子指向新路径且 `--verify` 全绿（＝「换电脑」的最小可复现）。
|
|||
|
|
5. 文档库 `07-scripts/` 转发壳：手动调 `handoff-guard.sh --status` ⇒ 行为与原型一致。
|
|||
|
|
|
|||
|
|
## §6 关键路径与命令
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
PY = E:/ProgramData/.workbuddy/binaries/python/versions/3.13.12/python.exe
|
|||
|
|
WS = E:/ProgramData/AIProject/ai1net-dsh-server
|
|||
|
|
DOC = D:/github/dsh_shenxian/dsh-server-docs
|
|||
|
|
技能目标目录 = E:/ProgramData/.workbuddy/skills/session-mechanism/
|
|||
|
|
锁：bash "D:/github/dsh_shenxian/dsh-server-docs/07-scripts/handoff-guard.sh" --claim-exec "<会话名>" # 机制层=独占，⛔ 不带 --domains
|
|||
|
|
释放：--release → --release-exec "<会话名>"
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
收尾：反序释放锁 ＋ 三层沉淀（技能 / 教训 / 记忆）＋ 提交边界（未明确要求 ⇒ 不 commit/push）。
|