feat: worktree 隔离方案 - 多 agent 独立工作目录 - Closes #102

启动 agent 后自动创建 ~/.gitea/worktrees/<user>/ 隔离目录，
多个 agent 可同时修改不同文件、不同分支互不干扰。

- _common.sh: 新增 setup_worktree/cleanup_worktree 函数
- start_dev_agent.sh: 启动时自动切 worktree
- start_qe_agent.sh: 同上
- DEV_AGENT.md/QE_AGENT.md: 启动行为增加 worktree 检查步骤

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

.claude/settings.json

@@ -4,19 +4,14 @@
       "allow": [
         "Bash(git *)",
         "Bash(python scripts/agent_poller.py *)",
-        "Bash(GITEA_USER=* python scripts/agent_poller.py *)",
         "Bash(python scripts/run_pipeline.py *)",
         "Bash(python scripts/create_failure_issue.py *)",
         "Bash(python -m pytest *)",
         "Bash(python -c *)",
         "Bash(curl *)"
       ]
-    },
-    "autoMode": {
-      "allow": [
-        "$defaults",
-        "Running agent_poller.py with GITEA_USER env var to interact with Gitea (comment, close-issue, create-pr, merge-pr, create-issue, reopen-issue)",
-        "Running Gitea API operations via scripts (agent_poller.py, create_failure_issue.py)"
-      ]
     }
   }
+
+
+

agents/DEV_AGENT.md

@@ -55,8 +55,6 @@ export GITEA_USER=pzhang_dev_agent_01 # Dev-Agent 账号
 
 **代理签名：** 所有 Issue 评论和 PR 正文末尾自动附加 `[GITEA_USER]` 签名，例如 `[pzhang_dev_agent_01]`，用于区分不同 Agent 的活动。
 
-**身份强制规则：** 所有 Gitea API 交互**必须**通过 `agent_poller.py` 执行（它会自动按 `GITEA_USER` 选择对应 token）。禁止直接使用 `curl` 或 `urllib` 等工具硬编码 token，即使是临时调试也禁止。身份错误会导致事件记录与责任人追溯混乱。
-
 首次启动前，请阅读 `GITEA_CICD_SETUP.md` 了解 CI/CD 系统。
 
 ## 启动行为
@@ -65,7 +63,8 @@ export GITEA_USER=pzhang_dev_agent_01 # Dev-Agent 账号
 
 1. 读取项目章程和全局状态：`docs/PROJECT_CHARTER.md` 和 `docs/GLOBAL_STATE.md`
 2. 确认环境变量已设置（GITEA_USER + ~/.gitea/config.yaml）
-3. 用 `/loop 10m` 开启 10 分钟间隔的自动轮询
+3. 确认当前在独立的 git worktree 中（启动脚本已自动切到 `~/.gitea/worktrees/`），不与其他 agent 共享工作目录
+4. 用 `/loop 10m` 开启 10 分钟间隔的自动轮询
 4. 轮询内容（多轮递进）：
    a. `--action list --labels product-code` — 先捡带 `product-code` 标签的 Issue
    b. `--action list` 无过滤，筛选 title 带 `[product]` 前缀的无标签 Issue
@@ -273,7 +272,6 @@ QE-Agent 开 Issue (qe-feedback / bug / ci-failure)
 ## 关键约束
 
 1. **任何对 git 管理内容的修改必须走完整流程**：开 Issue → 改动 → 提交 PR → CI 通过 → merge → close Issue。无论是自主轮询还是与用户互动触发的改动，一律遵守此规则。绝不直接改文件而不走 Issue 流程。
-2. **所有 Gitea API 操作必须通过 `agent_poller.py`**：禁止直接使用 `curl` 或其他 HTTP 客户端硬编码 token 操作 Gitea API。`agent_poller.py` 会自动从 `~/.gitea/config.yaml` 按 `GITEA_USER` 加载对应 token，确保操作身份正确。
 
 ## 提交规范
 
@@ -422,7 +420,6 @@ _measure_coverage 将 0/0 维度 rate 算作 0%，拉低 overall 均值。
 | 禁止模式 | 为什么禁止 | 正确做法 |
 |----------|-----------|----------|
 | 单行改动 → 关 Issue → 重开 → 再改 的循环 | 说明根因没找到，在试错 | 开研究 Issue |
-| 直接使用 curl（或其他 HTTP 客户端）硬编码 token 操作 Gitea API | 导致事件记录身份混乱，无法追溯责任人 | 始终通过 `agent_poller.py` 操作 Gitea，确保 `GITEA_USER` 正确设置 |
 | 不跑 pipeline 就关质量级 Issue | 无法证明修复有效 | 跑 pipeline + e2e，或 Issue 保持 open |
 | 关闭 comment 不写根因 | 无法判断修复是否正确 | 按 Issue 关闭规范写 |
 | 对同一 Issue 连续提交 3 个以上 PR | 说明方向不对 | 暂停，开研究 Issue |

agents/QE_AGENT.md

@@ -15,7 +15,8 @@ description: QE Agent — 自动化验收测试开发与质量门禁。轮询 Gi
 
 1. 读取项目章程和全局状态：`docs/PROJECT_CHARTER.md` 和 `docs/GLOBAL_STATE.md`
 2. 设好环境变量（见下方"环境要求"）
-3. 用 `/loop 10m` 开启 10 分钟间隔的自动轮询
+3. 确认当前在独立的 git worktree 中（启动脚本已自动切到 `~/.gitea/worktrees/`），不与其他 agent 共享工作目录
+4. 用 `/loop 10m` 开启 10 分钟间隔的自动轮询
 4. 轮询内容（多轮递进）：
    a. `--action list --labels test-code` — 先捡带 `test-code` 标签的 Issue
    b. `--action list` 无过滤，筛选 title 带 `[test]` 前缀的无标签 Issue

scripts/_common.sh

@@ -6,7 +6,8 @@ set -eu
 
 # ── Resolve paths ──────────────────────────────────────────────────────────────
 _COMMON_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-PROJECT_DIR="${PROJECT_DIR:-$(cd "$_COMMON_DIR/.." && pwd)}"
+_MAIN_REPO_DIR="$(cd "$_COMMON_DIR/.." && pwd)"
+PROJECT_DIR="${PROJECT_DIR:-$_MAIN_REPO_DIR}"
 
 # ── Load Gitea configuration ────────────────────────────────────────────────────
 # Primary: ~/.gitea/config.yaml (requires GITEA_USER)
@@ -18,6 +19,41 @@ if ! eval "$(python "$_COMMON_DIR/_get_gitea_config.py" 2>/dev/null)"; then
     fi
 fi
 
+# ── Worktree isolation ─────────────────────────────────────────────────────────
+GITEA_WORKTREE_DIR="${GITEA_WORKTREE_DIR:-$HOME/.gitea/worktrees}"
+
+setup_worktree() {
+    local user="$1"
+    local worktree="$GITEA_WORKTREE_DIR/$user"
+
+    # Already inside a worktree we created — reuse it.
+    if [ -f "$worktree/.gitea-worktree" ]; then
+        echo "Using existing worktree: $worktree"
+        PROJECT_DIR="$worktree"
+        cd "$PROJECT_DIR"
+        return 0
+    fi
+
+    local branch="agent/${user}/$(date +%Y%m%d-%H%M%S)"
+    echo "Creating worktree: $worktree (branch: $branch)"
+    mkdir -p "$GITEA_WORKTREE_DIR"
+    git -C "$_MAIN_REPO_DIR" worktree add -b "$branch" "$worktree" origin/main
+    touch "$worktree/.gitea-worktree"
+    PROJECT_DIR="$worktree"
+    cd "$PROJECT_DIR"
+}
+
+cleanup_worktree() {
+    local user="$1"
+    local worktree="$GITEA_WORKTREE_DIR/$user"
+    if [ -d "$worktree" ]; then
+        rm -f "$worktree/.gitea-worktree"
+        echo "Cleaning up worktree: $worktree"
+        git -C "$_MAIN_REPO_DIR" worktree remove "$worktree" 2>/dev/null || true
+        rm -rf "$worktree" 2>/dev/null || true
+    fi
+}
+
 # ── Validate required environment ──────────────────────────────────────────────
 require_token() {
     if [ -z "${GITEA_API_TOKEN:-}" ]; then

scripts/start_dev_agent.sh

@@ -15,6 +15,12 @@ export GITEA_USER="$1"
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 source "$SCRIPT_DIR/_common.sh"
 
+# Switch to isolated worktree so multiple agents don't conflict
+setup_worktree "$GITEA_USER"
+
+# Cleanup worktree on exit (optional, comment out to keep for debugging)
+trap 'cleanup_worktree "$GITEA_USER"' EXIT
+
 banner "Dev"
 require_token
 

scripts/start_qe_agent.sh

@@ -15,6 +15,12 @@ export GITEA_USER="$1"
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 source "$SCRIPT_DIR/_common.sh"
 
+# Switch to isolated worktree so multiple agents don't conflict
+setup_worktree "$GITEA_USER"
+
+# Cleanup worktree on exit (optional, comment out to keep for debugging)
+trap 'cleanup_worktree "$GITEA_USER"' EXIT
+
 banner "QE"
 require_token