更新: 多Agent隔离机制改用Git worktree替代自建暂存区

- 隔离:git worktree天然分支隔离,复用diff/merge/conflict能力

- 合并:git merge-tree三方合并预检+git merge实际合并到plan分支

- 冲突:四层防线(层间串行/worktree隔离/编译检查/命令互斥)

- 展示:合并产出落回主对话采用可展开单条(方案C)

- 类型:SubTaskRecord加branch字段,ConflictRecord加conflict_type

- 降级:非Git工程串行执行(无worktree隔离)

- 实施分批同步更新(含git_worktree.rs+编译检查+命令互斥锁)

docs/02-架构设计/专项设计/多Agent并行执行与仲裁合并设计-2026-07-01.md

@@ -91,8 +91,16 @@ ALTER TABLE ai_tool_executions ADD COLUMN subtask_id TEXT;
 
 -- 新建 3 张表（见 ER 图字段）
 CREATE TABLE ai_plans (...);
-CREATE TABLE ai_subtasks (...);
+CREATE TABLE ai_subtasks (
-CREATE TABLE ai_conflicts (...);
+    ...
+    -- worktree 分支名(git worktree 隔离机制,见 §4.2)
+    branch TEXT  -- 如 "subtask/{plan_id}/A"
+);
+CREATE TABLE ai_conflicts (
+    ...
+    -- 冲突类型(见 §4.2 四层防线)
+    conflict_type TEXT DEFAULT 'file'  -- 'file'(同文件) / 'semantic'(编译失败)
+);
 ```
 
 ### 2.4 三层关联查询示例
@@ -162,38 +170,114 @@ Plan.to_layers() → [[subtask_0, subtask_1], [subtask_2], [subtask_3, subtask_4
 
 | 规则 | 说明 |
 |------|------|
-| 层间串行 | 上层全部 done 才进下一层（DAG 依赖保证） |
+| 层间串行 | 上层全部 done + **Git merge 到 plan 分支后** 才创建下一层 worktree(fork 天然包含上层改动) |
-| 层内并行 | 同层 SubTask 用 JoinSet 并发执行 |
+| 层内并行 | 同层 SubTask 各自创建 Git worktree,JoinSet 并发执行 |
-| **写 SubTask 降级串行** | 同层内如有 `write_file`/`patch_file` 工具的 SubTask，降级为串行执行，防 concurrent write |
+| 写工具天然隔离 | 每个 SubTask 在独立 worktree 内工作,write_file/patch_file 写到 worktree 目录(不重定向) |
-| 只读 SubTask 并行 | `read_file`/`search_files`/`list_directory` 等只读工具的 SubTask 可安全并行 |
+| 只读工具天然可见 | read_file 读 worktree 内文件(含本 worktree 改动 + fork 基点的全部历史) |
+| 层内隔离 | 同层并行 SubTask 互相看不到对方的 worktree 改动(独立分支,完全隔离) |
 
-### 4.2 Token 预算管控
+### 4.2 Git worktree 隔离机制
+
+**核心思路**:用 Git worktree 替代自建暂存区,复用 Git 原生的分支隔离/diff/merge/conflict 能力。
+
+#### 优势(vs 自建暂存区)
+
+| 维度 | 自建暂存区 | Git worktree |
+|------|-----------|-------------|
+| 隔离 | 手动 cp 文件 | `git worktree add` 天然隔离 |
+| diff | 自己实现比对 | `git diff` 原生(含上下文/行级/二进制) |
+| 合并 | 手动 cp 或自写 merge | `git merge` 三方合并 |
+| 冲突解决 | 自建 diff 展示 | `git merge-tree` 预检 + conflict markers |
+| 回滚 | 手动备份/恢复 | `git reset` / `git checkout` |
+| 审计 | 自建日志 | commit history 天然审计链 |
+| AI 工具兼容 | write_file 需重定向路径 | worktree 就是普通目录,所有工具原样工作 |
+| PR 集成 | 需额外实现 | plan 分支直接创建 PR |
+
+#### 数据流
+
+```
+Plan 启动:
+  git worktree add .devflow/wt/{plan_id} -b plan/{plan_id}
+  (基于工程当前分支创建 plan 工作分支)
+
+Layer 0 并行:
+  SubTask A → git worktree add .devflow/wt/{plan_id}/A -b subtask/{plan_id}/A
+    (基于 plan 分支创建,A 的所有工具操作在此 worktree 内,天然隔离)
+  SubTask B → git worktree add .devflow/wt/{plan_id}/B -b subtask/{plan_id}/B
+    (同上,B 完全隔离,A 看不到 B 的改动,反之亦然)
+  SubTask A/B done 后各自 git add + git commit(改动落入各自分支)
+
+Layer 0 merge(本层全部 done 后):
+  ① cd .devflow/wt/{plan_id} (plan 分支)
+  ② git diff plan..subtask/{plan_id}/A → A 的改动集
+  ③ git diff plan..subtask/{plan_id}/B → B 的改动集
+  ④ 同文件交集 → git merge-tree (三方合并预检)
+     无冲突 → git merge subtask/{plan_id}/A && git merge subtask/{plan_id}/B
+     有冲突 → Conflict 表记录 + Reviewer 仲裁 / 用户选择
+  ⑤ 合并完成 → plan 分支已含 Layer 0 全部改动
+
+Layer 1 fork:
+  基于 plan 分支最新 commit 创建新 worktree(天然包含 Layer 0 改动)
+
+Plan 完成:
+  ① 编译检查:在 plan worktree 跑 cargo check / tsc --noEmit
+     失败 → semantic 冲突标记
+  ② plan 分支创建 PR(可选,或直接 merge 回主分支)
+  ③ git worktree remove 清理所有子 worktree + plan worktree
+```
+
+#### 读工具兼容规则
+
+| 场景 | 行为 |
+|------|------|
+| 同层并行 SubTask 互读 | 不可见(独立 worktree + 独立分支) |
+| 下一层读上一层产出 | 可见(上一层已 merge 到 plan 分支,新 worktree 基于此创建) |
+| SubTask 读自己 worktree 内的写入 | 可见(worktree 是真实目录,写完即读) |
+
+#### 非 Git 工程的降级
+
+未绑定 Git 的工程(无 .git 目录)降级为串行执行(单 SubTask 逐个跑,无 worktree 隔离)。
+此时 ai_subtasks.branch 为 NULL,Coordinator.dispatch 走原串行路径。
+
+### 4.3 冲突防护四层防线
+
+| 防线 | 机制 | 覆盖冲突类型 |
+|------|------|------------|
+| **第一层:层间串行 + merge 后才 fork** | 上一层 merge 到 plan 分支后,下一层 worktree 基于此创建 | 跨层同文件覆盖 |
+| **第二层:同层 worktree 隔离 + merge-tree 预检** | 独立分支 + git 三方合并检测 | 同文件并发写 |
+| **第三层:编译检查** | merge 完成后在 plan worktree 跑 cargo check / tsc --noEmit,失败 → 标记语义冲突 | 跨文件语义冲突(删函数/改签名) |
+| **第四层:命令互斥锁** | run_command 对同目录的 npm/cargo 加 mutex | 资源竞争(npm install 并发) |
+
+### 4.4 Token 预算管控
 
 ```rust
 struct TokenBudgetPool {
-    total: AtomicU64,        // 全局预算（来自设置项）
+    total: AtomicU64,        // 全局预算(来自设置项)
     consumed: AtomicU64,     // 已消耗
 }
 
 impl TokenBudgetPool {
     fn try_reserve(&self, estimate: u64) -> bool {
-        // CAS 循环：consumed + estimate <= total
+        // CAS 循环:consumed + estimate <= total
     }
 }
 ```
 
 - 每个 SubTask 启动前向预算池申请估算额度
-- 超限时 Coordinator 拒绝启动新 SubTask（降级为串行顺序执行剩余任务）
+- 超限时 Coordinator 拒绝启动新 SubTask(降级为串行顺序执行剩余任务)
-- 预算来源：设置项 `df-ai-plan-token-budget`（默认 100k tokens）
+- 预算来源:设置项 `df-ai-plan-token-budget`(默认 100k tokens)
 
-### 4.3 错误传播
+### 4.5 错误传播
 
 | 场景 | 策略 |
 |------|------|
-| SubTask 执行失败 | 记录 error 状态，**不中断其他同层 SubTask**（容错） |
+| SubTask 执行失败 | 记录 error 状态,**不中断其他同层 SubTask**(容错) |
-| 全部 SubTask 失败 | Coordinator 标记 Plan 状态为 error，前端展示错误 |
+| 全部 SubTask 失败 | Coordinator 标记 Plan 状态为 error,前端展示错误 |
-| 部分 SubTask 失败 | merge 时跳过失败 SubTask 的产出，只合并成功的 |
+| 部分 SubTask 失败 | merge 时跳过失败 SubTask 的分支(不 merge),只合并成功的 |
-| 子 Agent 超时 | 单 SubTask 超时（默认 120s）→ 标记 error，不影响其他 |
+| 子 Agent 超时 | 单 SubTask 超时(默认 120s)→ 标记 error,不影响其他 |
+| Git merge 冲突 | conflict markers 保留在 plan worktree,Reviewer Agent 仲裁或用户手动解决 |
+| 编译检查失败 | 标记 semantic 冲突,Reviewer Agent 尝试修复或标记给用户 |
+| worktree 创建失败 | 降级为串行(无 worktree 隔离,逐 SubTask 在主目录执行) |
 
 ---
 
@@ -274,38 +358,52 @@ impl TokenBudgetPool {
 
 ## 七、实施分批
 
-### Batch 37 — 数据层 + 并行执行
+### 数据层 + Git worktree 隔离 + 并行执行
 
 | # | 任务 | 文件 |
 |---|------|------|
-| 1 | V36 迁移（3 新表 + 2 ALTER） | migrations.rs |
+| 1 | V36 迁移(3 新表 + 2 ALTER + subtasks.branch + conflicts.conflict_type) | migrations.rs |
 | 2 | PlanRepo / SubTaskRepo / ConflictRepo CRUD | 新 repo 文件 |
-| 3 | Coordinator.dispatch JoinSet 层内并行 | coordinator.rs |
+| 3 | Git worktree 生命周期管理(create/commit/merge/remove) | 新 git_worktree.rs |
-| 4 | 写 SubTask 降级串行 + token 预算池 | coordinator.rs |
+| 4 | Coordinator.dispatch JoinSet 层内并行(每 SubTask 绑 worktree) | coordinator.rs |
-| 5 | 4 个新事件类型 | AiChatEvent |
+| 5 | Token 预算池(AtomicU64 CAS,超限降级串行) | coordinator.rs |
-| 6 | PlanProgress 接入真实状态 | PlanProgress.vue |
+| 6 | 子 Agent 独立 ContextManager + fork 快照 + worktree_path | coordinator.rs |
-| 7 | 工具卡按 subtask_id 分组 | MessageList.vue |
+| 7 | 层间 merge 到 plan 分支 + 下一层基于 plan 创建 worktree | coordinator.rs |
+| 8 | 4 个新事件 + 事件双写(emit + publish_event) | AiChatEvent |
+| 9 | 前端类型定义(PlanRecord/SubTaskRecord/ConflictRecord) | api/types.ts |
+| 10 | PlanProgress 接入真实状态 + 发送即展示 | PlanProgress.vue |
+| 11 | 工具卡按 subtask_id 折叠分组 + persona 徽章 | MessageList.vue |
+| 12 | 编译警告清理(coordinator_plan unused / audit 子模块 unused imports) | 各文件 |
 
-### Batch 38 — 仲裁合并 + UI 完善
+### 仲裁合并 + 冲突 UI + 编译检查
 
 | # | 任务 | 文件 |
 |---|------|------|
-| 1 | Coordinator.merge 冲突检测（按文件路径） | coordinator.rs |
+| 1 | Coordinator.merge: git merge-tree 三方合并预检 | coordinator.rs + git_worktree.rs |
-| 2 | Reviewer Agent 仲裁（persona.rs 扩展） | persona.rs + coordinator.rs |
+| 2 | 冲突检测:同文件路径(file 类型) + 编译失败(semantic 类型) | coordinator.rs |
-| 3 | 冲突 diff 展示 + resolution 按钮 | 新 ConflictResolver.vue |
+| 3 | Reviewer Agent 仲裁(persona 扩展:读 diff → 推荐 resolution + 理由) | persona.rs |
-| 4 | AiConflictResolved 事件闭环 | AiChatEvent |
+| 4 | 合并产出落回主对话(方案 C:可展开单条) | coordinator.rs + MessageList.vue |
-| 5 | 技术债扫尾（编译警告 / unused import） | 各文件 |
+| 5 | ConflictResolver.vue(git diff 展示 + resolution 按钮) | 新组件 |
+| 6 | resolve_conflict IPC + AiConflictResolved 事件闭环 | AiChatEvent |
+| 7 | 命令互斥锁(run_command 对同目录 npm/cargo 加 mutex) | audit/approval.rs |
+| 8 | agentic/mod.rs 拆分(2222 行 → 提取 compress/title/knowledge_inject 独立模块) | agentic/*.rs |
+| 9 | AiChat 进度条补全(后端 AiAgentRound 补 max_rounds + 前端 completed 计数) | AiChat.vue |
+| 10 | context.rs 拆分(1956 行 → 提取 sanitize/budget/compress 独立模块) | context/*.rs |
 
 ---
 
 ## 八、子 Agent 上下文隔离
 
-### 8.1 问题
+### 8.1 双重隔离:上下文 + 文件系统
 
-多 Agent 并行执行时,每个 SubTask 需要独立的上下文(messages / currentText / tool_results)。
+多 Agent 并行执行时需要两层隔离:
-如果共享主对话的 ContextManager,多个 SubTask 的产出会交织污染。
 
-### 8.2 方案:子对话快照 + 独立 ContextManager
+| 层 | 隔离对象 | 机制 |
+|---|---------|------|
+| 上下文隔离 | messages / currentText / tool_results / pending_approvals | 独立 ContextManager 实例 |
+| 文件隔离 | 工程文件(worktree 内的源码) | Git worktree(见 §4.2) |
+
+### 8.2 上下文隔离
 
 ```rust
 struct SubTaskContext {
@@ -317,31 +415,37 @@ struct SubTaskContext {
     persona: AgentPersona,
     /// 子任务 id(产出消息标记 subtask_id)
     subtask_id: String,
+    /// Git worktree 路径(工具操作的工作目录,见 §4.2)
+    worktree_path: Option<PathBuf>,  // None = 非 Git 工程降级串行
 }
 ```
 
 **隔离规则**:
 
 | 维度 | 主对话 | 子 Agent |
-|------|--------|---------|
+|------|--------|----------|
 | messages | 用户消息 + 合并产出 | fork 快照 + 独立执行轨迹 |
 | ContextManager | 主对话的 | 每个 SubTask 独立实例 |
 | pending_approvals | 主对话的 | 各 SubTask 独立(无并发写竞争) |
 | tool_results | 写入子 Agent 的 messages | 合并时提取摘要写入主对话 |
+| **文件系统** | 主工程目录 | **Git worktree 隔离**(§4.2) |
+| **工作目录** | 主工程路径 | **worktree_path**(工具的 cwd 重定向到此) |
 
-### 8.3 合并产出落回主对话
+### 8.3 合并产出落回主对话(方案 C:可展开单条)
 
 ```
 SubTask 完成 → ExecutionResult { output, success }
                                        ↓
 Coordinator.merge(results) → MergeResult { merged_output, conflicts }
                                        ↓
-主对话 push 一条 assistant 消息(merged_output) + N 条冲突消息(conflicts[i])
+主对话 push 单条可展开 assistant 消息
 ```
 
-- **合并输出 = 单条 assistant 消息** — 不是把所有子 Agent 的消息都堆进主对话
+**展示策略**:
-- **冲突 = 单独消息** — 每个冲突一条,带 `conflict_id` 供前端定位
+- **默认折叠**:主对话只展示一条 assistant 消息(merged_output 摘要)
-- **子 Agent 执行轨迹不落主对话** — 只在 ai_messages 表中保留(带 subtask_id),前端按需展开查看
+- **点击展开**:展开后按 SubTask 分组,每组显示完整执行轨迹(从 ai_messages WHERE subtask_id=? 拉取)
+- **冲突内联**:合并消息底部内联冲突列表(点击展开 diff + resolution 按钮)
+- **子 Agent 执行轨迹不堆入主对话流**:只在 ai_messages 表保留(带 subtask_id),展开时按需加载
 
 ---
 
@@ -379,18 +483,28 @@ export interface SubTaskRecord {
   status: SubTaskStatus
   layer: number
   deps: string[]  // JSON 解析后的数组
+  /** Git worktree 分支名(NULL=非 Git 工程降级串行) */
+  branch: string | null
   created_at: string
   completed_at: string | null
 }
 
+/** 冲突类型 */
+export type ConflictType = 'file' | 'semantic'
+
 /** 冲突记录 */
 export interface ConflictRecord {
   id: string
   plan_id: string
+  /** 冲突文件路径(semantic 类型时为触发编译失败的入口文件) */
   file_path: string
+  /** 冲突类型:file=同文件路径 / semantic=编译失败 */
+  conflict_type: ConflictType
   subtask_a: string
   subtask_b: string
+  /** git diff 输出(A 的改动) */
   diff_a: string
+  /** git diff 输出(B 的改动) */
   diff_b: string
   resolution: ConflictResolution
   resolved_by: 'reviewer' | 'user' | null