---
id: FEAT-0032
type: feature
status: closed
stage: done
title: 可选分支隔离 (Optional Branch Isolation)
created_at: '2026-01-11T00:00:00'
updated_at: '2026-01-11T23:52:35.367856'
closed_at: '2026-01-11T23:52:35.367889'
parent: EPIC-0004
solution: implemented
dependencies: []
related: []
domains: []
tags:
- '#EPIC-0004'
- '#FEAT-0032'
author: Monoco Agent
uid: 83e3fb
---

## FEAT-0032: 可选分支隔离 (Optional Branch Isolation)

## 目标 (Objective)

为任务提供灵活的物理隔离层级，同时严格遵循 "Agent-First" (零交互) 设计原则。

## 设计原则 (Design Principles)

1.  **Agent-First**: 所有命令必须是非交互式的（Headless）。禁止 `(Y/n)` 提示。
2.  **Explicit Intent**: 危险操作（如删除分支）必须由显式 Flag (`--prune`, `--force`) 触发。
3.  **Fail-Fast**: 遇到未提交变更或合并冲突时，直接报错退出 (Exit Code != 0)，不尝试自动挽救。

## 需求规格 (Requirements)

### 1. 隔离层级 (Isolation Tiers)

支持三种模式，适应不同场景:

| 模式                        | CLI 参数     | 行为                                                | 适用场景                                 |
| :-------------------------- | :----------- | :-------------------------------------------------- | :--------------------------------------- |
| **Tier 0: 逻辑隔离 (默认)** | (无)         | 仅在 Issue 记录中关联 Commit Tag。不操作 Git HEAD。 | 简单的文案修改、配置调整。               |
| **Tier 1: 分支隔离**        | `--branch`   | `git checkout -b feat/{id}`                         | 人类开发者的标准流程（上下文切换低）。   |
| **Tier 2: 目录隔离**        | `--worktree` | `git worktree add .monoco/worktrees/{id}`           | Agent 并行任务、长耗时测试、破坏性实验。 |

### 2. 启动逻辑 (`start`)

- [x] **Tier 1 (`--branch`)**:
  - 检查分支是否存在。若存在则 `checkout`，若不存在则创建并切换。
- [x] **Tier 2 (`--worktree`)**:
  - 路径规范: `.monoco/worktrees/{id}-{slug}`。
  - 依赖处理: Agent 需自行处理新目录的依赖安装（CLI 不自动运行 `npm install` 以保持单一职责）。
  - 输出: 返回新 Worktree 的绝对路径 JSON，供 Agent 切换上下文。

### 3. 清理逻辑 (`submit` / `close`)

引入 `--prune` 参数，在任务结束生命周期时回收物理资源。

- **Command**: `monoco issue submit --prune`
- **Logic**:
  1.  执行核心逻辑（合并代码/更新状态）。
  2.  若带有 `--prune`:
      - 尝试 `git branch -d` 或 `git worktree remove`。
      - **Success**: Log info, exit 0.
      - **Error (Dirty/Unmerged)**: Log stderr, **exit 1**. (Agent 需捕获错误并决定后续: 手动 Commit 或 `--force` 强制删除)。

### 4. 独立资源管理 (`resource`)

提供给 Agent 的垃圾回收工具。

- **Command**: `monoco resource prune <issue-id>`
- **Flags**:
  - `--force`: 对应 `git branch -D` / `git worktree remove --force`。
  - `--dry-run`: 仅列出目标。

## 技术实现 (Technical Implementation)

- **State Persistence**: 在 Issue Frontmatter 中记录分配的物理资源路径。
  ```yaml
  isolation:
    type: "branch" | "worktree"
    ref: "feat/CHORE-001"
    path: ".monoco/worktrees/CHORE-001..." # 仅 Worktree 模式
  ```
- **Safety Checks**: 禁止删除当前 HEAD 所在的分支或 Worktree (若 Agent 正在其中运行)。

## 交付 (Delivery)

<!-- Monoco Auto Generated -->

**Commits (1)**:

- `fb0c09b` feat(cli): implement optional branch/worktree isolation (FEAT-0004)

**Touched Files (5)**:

- `Issues/Features/open/FEAT-0004-optional-branch-isolation.md` (Note: Updated to FEAT-0032 in future scans)
- `Toolkit/monoco/core/git.py`
- `Toolkit/monoco/features/issue/commands.py`
- `Toolkit/monoco/features/issue/core.py`
- `Toolkit/monoco/features/issue/models.py`

## Review Comments

- [x] Self-Review
