From 6f2206a43813e984bb3ef76a6f59131ce639f34d Mon Sep 17 00:00:00 2001
From: kris <krisoso.com@gmail.com>
Date: Mon, 6 Apr 2026 08:58:39 +0800
Subject: [PATCH] docs: define gui cli device capability and conflict guard

---
 ...-gui-cli-capability-and-conflict-design.md | 477 ++++++++++++++++++
 1 file changed, 477 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-04-06-device-gui-cli-capability-and-conflict-design.md

diff --git a/docs/superpowers/specs/2026-04-06-device-gui-cli-capability-and-conflict-design.md b/docs/superpowers/specs/2026-04-06-device-gui-cli-capability-and-conflict-design.md
new file mode 100644
index 0000000..aba47e5
--- /dev/null
+++ b/docs/superpowers/specs/2026-04-06-device-gui-cli-capability-and-conflict-design.md
@@ -0,0 +1,477 @@
+# Mac/Windows 设备 GUI+CLI 双能力接入与并行冲突控制设计
+
+日期：`2026-04-06`
+
+## 1. 背景
+
+Boss 当前的设备执行主链已经稳定在：
+
+- 设备 heartbeat 上报
+- `local-agent -> codex exec resume`
+- Web / Android 会话与设备控制面
+
+但现状仍有两个结构性缺口：
+
+1. **设备模型还没有把 Codex GUI 与 Codex CLI 当成同一台设备下的两种能力。**
+   - 用户可能只开 GUI
+   - 也可能只开 CLI
+   - 也可能同一台 Mac / Windows 同时开着 GUI 和 CLI
+   - 当前 Boss 还没有显式表达这种“双能力设备”
+
+2. **同一台设备的 GUI 与 CLI 同时推进同一项目时，缺少并行冲突控制。**
+   - 主 Agent 可能通过 CLI 正在推进某个项目
+   - 用户本人也可能在 GUI 中继续操作同一项目
+   - 如果两边都对同一 worktree 写入，很容易出现覆盖、上下文漂移、重复修改、误判进度
+
+本轮设计要解决的是：
+
+- 让 Boss 正式支持 `Mac / Windows` 的 `Codex CLI` 接入
+- 让同一台设备同时支持 `GUI + CLI`
+- 让 GUI / CLI 可以切换默认执行模式
+- 在同项目并行写入风险出现时，默认阻断并弹出风险确认
+
+## 2. 调研结论
+
+### 2.1 官方产品结论
+
+基于官方公开说明，Codex app 与 CLI 的关系更像：
+
+- 同一用户工作空间下的多个入口
+- 共享 `session history`
+- 共享 `configuration`
+- 共享 `skills`
+- 额度与使用量也统一计入同一个产品账户体系
+
+因此，Boss 不应把 GUI 与 CLI 理解成两个完全独立系统。
+
+### 2.2 本地实测结论
+
+在当前 macOS 开发机上，Codex 的核心状态位于：
+
+- `~/.codex/state_5.sqlite`
+- `~/.codex/logs_1.sqlite`
+- `~/.codex/session_index.jsonl`
+- `~/.codex/.codex-global-state.json`
+
+同时 GUI 还有自己的应用壳目录：
+
+- `~/Library/Application Support/Codex`
+
+这说明：
+
+- `~/.codex` 更像主状态库
+- `Application Support/Codex` 更像 GUI 壳层缓存/偏好/会话容器
+
+### 2.3 Windows 实测结论
+
+在局域网 Windows 设备 `192.168.31.18` 上实测：
+
+- `C:\Users\kris\.codex` 存在
+- 且真实包含：
+  - `state_5.sqlite`
+  - `logs_1.sqlite`
+  - `session_index.jsonl`
+  - `.codex-global-state.json`
+  - `auth.json`
+  - `config.toml`
+
+这说明 Windows 上也存在同样的用户级 Codex 核心状态目录。
+
+### 2.4 设计结论
+
+因此在 Boss 中，GUI 与 CLI 应建模为：
+
+- **同一台物理设备下的两种能力**
+- 不是两台设备
+- 不是两套独立项目空间
+
+## 3. 目标与非目标
+
+### 3.1 目标
+
+1. 支持 `Mac / Windows` 的 Codex CLI 接入。
+2. 同一台设备可同时在线：
+   - `GUI`
+   - `CLI`
+3. 设备级支持默认执行模式切换：
+   - `GUI`
+   - `CLI`
+4. 主 Agent 和用户都可以在 GUI / CLI 间切换执行入口。
+5. 检测同设备、同项目、同 folder/worktree 的并行写入风险。
+6. 当发生并行写入风险时：
+   - 默认阻断继续执行
+   - 弹出风险警告
+   - 提供三个动作：
+     - `禁止`
+     - `允许本次`
+     - `永久放行`
+7. `允许本次 / 永久放行` 必须是**项目文件夹/线程级**，不是全局开关。
+8. 整套冲突检测应尽量基于规则层完成，避免持续消耗 token。
+
+### 3.2 非目标
+
+1. 本轮不把 GUI 与 CLI 拆成两台虚拟设备。
+2. 本轮不做 OS 级窗口焦点监测或键鼠监控。
+3. 本轮不重写现有 `local-agent -> codex exec resume` 主链。
+4. 本轮不要求 GUI 与 CLI 对同项目绝对互斥。
+5. 本轮不做真正的多 worktree 自动编排，只做冲突识别与风险控制。
+
+## 4. 用户体验结论
+
+### 4.1 设备模型
+
+一台物理设备在 Boss 中保持单条记录，例如：
+
+- `Mac Studio`
+- `Windows GPU`
+
+但设备详情里要新增两类能力状态：
+
+- `GUI`
+- `CLI`
+
+每种能力分别展示：
+
+- 是否已连接
+- 最近在线时间
+- 最近活跃项目
+
+### 4.2 默认执行模式
+
+设备级新增 `默认执行模式`：
+
+- `GUI`
+- `CLI`
+
+说明：
+
+- 这只是默认值
+- 不会关闭另一种能力
+- 同一台设备允许 `GUI + CLI` 同时在线
+
+### 4.3 前台切换语义
+
+用户层的真实语义是：
+
+- 可以只用 GUI
+- 可以只用 CLI
+- 也可以同一台设备同时使用 GUI 和 CLI
+
+Boss 必须支持三种状态共存，而不是互斥二选一。
+
+## 5. 数据模型设计
+
+### 5.1 Device 新增能力字段
+
+为设备增加能力层字段：
+
+- `capabilities.gui.connected`
+- `capabilities.gui.lastSeenAt`
+- `capabilities.gui.lastActiveProjectId`
+- `capabilities.cli.connected`
+- `capabilities.cli.lastSeenAt`
+- `capabilities.cli.lastActiveProjectId`
+- `preferredExecutionMode`
+
+约束：
+
+- `preferredExecutionMode` 仅允许：
+  - `gui`
+  - `cli`
+
+### 5.2 Project / Folder 级并行风险状态
+
+新增项目级或文件夹级并行状态：
+
+- `deviceId`
+- `folderKey`
+- `projectId`
+- `activeCliExecution`
+- `recentExternalActivityAt`
+- `conflictState`
+- `allowPolicy`
+
+其中：
+
+- `conflictState`:
+  - `none`
+  - `warning`
+  - `blocked`
+- `allowPolicy`:
+  - `forbid`
+  - `allow_once`
+  - `allow_always`
+
+### 5.3 永久放行粒度
+
+`永久放行` 必须是**局部策略**，不是全局策略。
+
+推荐主键：
+
+- `deviceId + folderKey`
+
+如果没有稳定 `folderKey`，退化为：
+
+- `deviceId + projectId`
+
+对于单线程项目，本质上仍然是该线程所在 folder/project 级别策略，而不是全账号或全设备策略。
+
+## 6. 并行冲突检测
+
+## 6.1 冲突定义
+
+满足以下条件时，视为并行冲突风险：
+
+1. 同一台设备
+2. 主 Agent 正通过 `CLI` 执行某项目的写入型任务
+3. 同一项目 / folder / worktree 又出现新的外部活动
+4. 该外部活动并非当前 Boss 发起的同一 CLI 任务的正常进展
+
+这里的“外部活动”不强行区分一定来自 GUI 还是外部 CLI 手工操作。产品语义统一视为：
+
+- **非当前 Boss 任务所控制的人工/外部活动**
+
+如果设备同时具备 `GUI connected = true`，前台提示可优先表述为 GUI 并行操作；否则用更中性的“外部活动”提示。
+
+### 6.2 检测方式
+
+冲突检测应尽量走规则层，而不是 LLM 判断。
+
+规则层输入：
+
+- 当前 CLI 执行任务是否在跑
+- 目标 deviceId / projectId / folderKey
+- 线程 heartbeat / reply / activity 上报
+- 最近外部活动时间
+- 当前任务自己的 trace / taskId / targetThreadRef
+
+输出：
+
+- 是否冲突
+- 冲突归属到哪个 folder/project
+
+### 6.3 Token 策略
+
+本设计要求：
+
+- 冲突检测本身不调用 LLM
+- 冲突提示文案模板化
+- 只有用户主动要求“解释为什么冲突”或“请主 Agent 给建议”时，才允许主 Agent 读取线程状态文档与最近进展事件
+
+因此，这套机制本身不应成为高 token 消耗来源。
+
+## 7. 冲突拦截与用户确认
+
+### 7.1 默认行为
+
+发生并行冲突风险时：
+
+- **默认不继续**
+- 先弹风险警告
+- 不直接自动放行
+
+### 7.2 风险警告文案
+
+默认模板：
+
+- `检测到该项目正在同一设备上发生并行操作。`
+- `主 Agent 当前正通过 CLI 推进，而你也在同一项目中产生了新的人工活动。`
+- `继续执行可能导致文件覆盖、上下文偏移或重复修改。`
+
+### 7.3 用户动作
+
+警告卡必须提供三个动作：
+
+1. `禁止`
+   - 本次不继续
+   - 保持默认阻断
+
+2. `允许本次`
+   - 只放行当前这一次执行
+   - 不改变后续默认策略
+
+3. `永久放行`
+   - 仅对当前异常项目/文件夹生效
+   - 后续同一 `deviceId + folderKey` 再发生同类冲突时，允许继续
+   - 不影响其他项目/文件夹
+
+### 7.4 永久放行撤销
+
+`永久放行` 不是不可逆。
+
+需要提供撤销入口，建议放在：
+
+- 项目文件夹页 / 线程会话信息页
+- 或设备详情中该项目的执行策略区
+
+文案示例：
+
+- `该项目已允许 GUI/CLI 并行继续`
+- `关闭永久放行`
+
+## 8. 执行路由设计
+
+### 8.1 默认执行模式
+
+主 Agent 与普通线程调度时：
+
+- 先读设备的 `preferredExecutionMode`
+- 优先走对应能力
+
+### 8.2 执行能力选择
+
+推荐行为：
+
+- 写入型自动执行：优先 `CLI`
+- 人工观察 / 人工接管 / 人工窗口操作：优先 `GUI`
+
+### 8.3 同时在线
+
+当 `GUI + CLI` 同时在线时：
+
+- 不自动断开其中一边
+- 也不自动把设备拆成两个逻辑设备
+- 只在同项目并行写入风险时触发冲突控制
+
+## 9. 前台设计
+
+### 9.1 设备详情页
+
+新增两个可见区：
+
+1. `连接能力`
+   - `GUI`
+   - `CLI`
+
+2. `默认执行模式`
+   - 单选：
+     - `GUI`
+     - `CLI`
+
+### 9.2 项目文件夹 / 线程会话
+
+当项目存在永久放行策略时，当前页可见：
+
+- `GUI/CLI 并行已允许`
+
+当项目发生实时冲突时，当前页显示风险卡：
+
+- 风险说明
+- `禁止`
+- `允许本次`
+- `永久放行`
+
+### 9.3 主 Agent 交互
+
+主 Agent 遇到此类冲突时：
+
+- 默认停止继续下发
+- 生成风险卡
+- 等用户明确动作
+
+注意：
+
+- 这不代表主 Agent 抢占线程控制权
+- 主 Agent 只是协同与调度者
+- 用户仍可继续直接控制线程
+
+## 10. API 与状态变更建议
+
+### 10.1 设备能力状态
+
+新增或扩展设备详情接口字段：
+
+- `capabilities.gui`
+- `capabilities.cli`
+- `preferredExecutionMode`
+
+### 10.2 项目并行策略
+
+新增项目/文件夹级策略字段：
+
+- `parallelConflictPolicy`
+- `parallelConflictState`
+
+并提供更新入口：
+
+- `forbid`
+- `allow_once`
+- `allow_always`
+
+`allow_once` 应在当前任务完成或取消后自动清空。
+
+### 10.3 冲突事件
+
+建议在 SSE / APP 状态流里补一类事件：
+
+- `project.parallel_conflict.detected`
+- `project.parallel_conflict.cleared`
+- `project.parallel_conflict.policy_updated`
+
+## 11. 测试策略
+
+### 11.1 服务端
+
+覆盖这些场景：
+
+1. 同设备 GUI + CLI 同时在线
+2. CLI 正在执行，出现外部人工活动
+3. 默认阻断
+4. `允许本次` 只放行一次
+5. `永久放行` 只对当前 folder/project 生效
+6. 不同 folder 不受影响
+7. `allow_once` 自动清空
+
+### 11.2 Android / Web
+
+覆盖这些场景：
+
+1. 设备详情页能显示 GUI/CLI 双能力
+2. 默认执行模式切换
+3. 冲突卡三按钮行为
+4. 永久放行状态展示
+5. 撤销永久放行
+
+## 12. 风险与边界
+
+### 12.1 无法精确知道“是 GUI 还是手工 CLI”
+
+本轮不做 OS 级窗口焦点和输入行为追踪，因此“人工活动”只能基于 Boss 可观察到的项目活动来判定。
+
+这意味着：
+
+- 有时只能判断为“外部人工/非 Boss 活动”
+- 不能 100% 精确证明一定是 GUI
+
+这在产品上是可以接受的，因为风险本质是：
+
+- **同项目正在被外部人工推进**
+
+### 12.2 worktree 级精度
+
+如果未来要支持同项目多 worktree 并行，本模型还需再细化到：
+
+- `deviceId + folderKey + worktreeRef`
+
+本轮先按：
+
+- `deviceId + folderKey`
+
+收口。
+
+## 13. 最终结论
+
+本轮正式采用以下设计：
+
+1. **GUI 和 CLI 是同一设备下的双能力，不拆成两个设备。**
+2. **Mac / Windows 都按用户级 `.codex` 主状态库模型接入。**
+3. **默认执行模式按设备级切换。**
+4. **同项目 GUI/CLI 并行写入风险由规则层检测。**
+5. **默认阻断，不自动继续。**
+6. **用户必须在当前异常项目/文件夹级别做出选择：**
+   - `禁止`
+   - `允许本次`
+   - `永久放行`
+7. **永久放行只对当前项目文件夹/线程生效，不做全局开关。**
+
+这套方案既符合 Codex GUI/CLI 的真实关系，也能最大程度避免“主 Agent 与人工开发同时写同一项目”带来的实际风险。