# 协作模式（同一工作区下的多会话自动协作）

> 同一工作区里同时开多个会话时，插件自动登记谁在写哪个文件，撞车当场提醒。开关与行为见 [README](../README.md) 的「能做什么」。

**要解决的问题**：你同时开几个会话推进同一个项目时，它们彼此看不见 ——
两个会话同时改 `src/index.js`，谁都不知道，最后可能产出"看起来装好了、其实是半成品"的版本。
（本项目自己就栽过一次，所以这个功能是**被自己的事故逼出来的**。）

**为什么插件能做这件事**：DSH 桌面版是**一个进程**托管所有会话，而插件就跑在这个进程里 ——
所以同工作区的会话彼此**天然可见**，不需要轮询文件、不需要外部服务。
文件只是跨重启的兜底与人类可读的面板。

**它自动做四件事：**

| 能力 | 说明 |
|---|---|
| **会话注册表** | 谁在跑、在哪个工作区、什么状态、最后活动时间 |
| **文件占用表** | 谁在写哪个文件；**撞车时当场告诉后来者**（`warn`）或直接拒绝（`block`） |
| **留言板** | 会话之间互相传话（`collab_post`），对方下一个模型步骤就能看到 |
| **自动面板** | 把上面三样写进 `plugin-collab.md` 的自动区块（人也能直接看） |

**三个刻意的设计（都有代价，都是踩出来的）：**

1. **单人单会话时完全静默**：没有任何别的东西可说，就**不往上下文里塞一个字** ——
   所以默认开着，代价为零。（回归测试专门锁死了这一点。）
2. **面板只写标记之间的区块**：`<!-- collab:auto:begin -->` … `<!-- collab:auto:end -->`，
   **标记之外你自己写的文字一字不碰** —— 纯手工维护的协作板就是这样被平滑接管的。
   标记还必须**独占一整行**才算数：这样你在板上讨论格式、把标记当字面量写出来，也不会被误当成区块
   （否则下一次自动维护会把面板插进你那条留言中间，把留言劈成两半）。
3. **转空闲即释放占用**：会话跑完睡下，它占的文件立刻放掉 ——
   否则一个会话崩了就会留下**死锁**，那比冲突更糟。
4. **可以一键关掉**：会话输入框下方那个 `协作已开 / 协作已关` 小开关，
   或「设置 → 协作模式 → 总开关」。关掉后不再互通占用与留言，**立刻生效、无需重启**
   （四个 `collab_*` 工具仍注册着，但会回一句「协作模式已关闭」而不是报错）。

**给模型的四个工具：**

| 工具 | 用途 |
|---|---|
| `collab_status` | 看同工作区其他会话 + 文件占用 + 留言 |
| `collab_post` | 给其他会话留言 |
| `collab_claim` / `collab_release` | 手动认领 / 释放文件占用 |

> 写文件**不需要**模型主动认领：插件从 `tools/pre-execute` 里就已经自动登记了。
> 它只认 `file_path` / `path` 这类**显式路径参数**，**不解析 shell 命令** ——
> 解析命令必然误报，而误报会让人干脆关掉整个功能，比漏报更糟。

**已知限制（写在代码注释里）**：工具的 `execute()` 里拿不到"是谁在调用"，插件用**参数指纹**回溯；
指纹失配时退回到"最近一次带 agent 的调用"，多个会话同一瞬间调用协作工具时可能串号 ——
只影响留言署名，不会写坏协作状态。

**不想要它**：`collabEnabled: false`。只想别被拦：`collabClaimGuard: off`。

---

[← 回到 README](../README.md)