fix: Git Workflow 多 Session 并发隔离改造 - Closes #124

核心变更:
- _common.sh: setup_worktree 改为 session-unique detached worktree (origin/main)
- 所有 Agent 文档移除 git checkout main / git pull origin main
- Feature branch 统一从 origin/main 创建: git fetch origin && git checkout -b <branch> origin/main
- CLAUDE.md: 新增工作区隔离章节, primary worktree 定义为只读参考区
- 新增 start_generic.sh: Generic session worktree 隔离启动器

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

scripts/_common.sh

@@ -21,37 +21,36 @@ fi
 
 # ── Worktree isolation ─────────────────────────────────────────────────────────
 GITEA_WORKTREE_DIR="${GITEA_WORKTREE_DIR:-$HOME/.gitea/worktrees}"
+_WORKTREE_PATH=""
 
 setup_worktree() {
     local user="$1"
-    local worktree="$GITEA_WORKTREE_DIR/$user"
+    local ts
+    ts="$(date +%Y%m%d-%H%M%S)"
+    local worktree="$GITEA_WORKTREE_DIR/$user/$ts"
 
-    # 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
+    # Ensure origin/main is current so worktree starts from latest
+    git -C "$_MAIN_REPO_DIR" fetch origin main 2>/dev/null || true
 
-    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
+    echo "Creating worktree: $worktree (detached from origin/main)"
+    mkdir -p "$(dirname "$worktree")"
+    git -C "$_MAIN_REPO_DIR" worktree add --detach "$worktree" origin/main
     touch "$worktree/.gitea-worktree"
+
     PROJECT_DIR="$worktree"
+    _WORKTREE_PATH="$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
+    local worktree="${_WORKTREE_PATH:-}"
+    if [ -z "$worktree" ] || [ ! -f "$worktree/.gitea-worktree" ]; then
+        echo "No worktree to clean up (not created by this session)."
+        return 0
     fi
+    rm -f "$worktree/.gitea-worktree"
+    echo "Cleaning up worktree: $worktree"
+    git -C "$_MAIN_REPO_DIR" worktree remove --force "$worktree" 2>/dev/null || true
 }
 
 # ── Validate required environment ──────────────────────────────────────────────

scripts/start_dev_agent.sh

@@ -19,15 +19,13 @@ source "$SCRIPT_DIR/_common.sh"
 setup_worktree "$GITEA_USER"
 
 # Cleanup worktree on exit (optional, comment out to keep for debugging)
-trap 'cleanup_worktree "$GITEA_USER"' EXIT
+trap 'cleanup_worktree' EXIT
 
 banner "Dev"
 require_token
-
-AGENT_CONF="$_MAIN_REPO_DIR/.claude/agents/dev-agent.md"
 launch_agent \
     "dev-agent" \
-    "$AGENT_CONF" \
+    "$PROJECT_DIR/.claude/agents/dev-agent.md" \
     "Dev-Agent" \
     "执行一次 Issue 巡检（单次任务，不要用 /loop）：
 1. python scripts/agent_poller.py --action list 列出所有打开的 Issue

scripts/start_generic.sh

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+# Generic session 启动脚本 — 为人类用户提供 worktree 隔离
+# 用法: bash scripts/start_generic.sh
+# GITEA_USER 默认 pzhangzywl（人类用户），可通过环境变量覆盖
+
+set -eu
+
+export GITEA_USER="${GITEA_USER:-pzhangzywl}"
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+source "$SCRIPT_DIR/_common.sh"
+
+setup_worktree "$GITEA_USER"
+trap 'cleanup_worktree' EXIT
+
+banner "Generic"
+require_token
+
+echo "工作目录: $PROJECT_DIR"
+echo ""
+cd "$PROJECT_DIR"
+claude

scripts/start_qe_agent.sh

@@ -19,15 +19,13 @@ source "$SCRIPT_DIR/_common.sh"
 setup_worktree "$GITEA_USER"
 
 # Cleanup worktree on exit (optional, comment out to keep for debugging)
-trap 'cleanup_worktree "$GITEA_USER"' EXIT
+trap 'cleanup_worktree' EXIT
 
 banner "QE"
 require_token
-
-AGENT_CONF="$_MAIN_REPO_DIR/.claude/agents/qe-agent.md"
 launch_agent \
     "qe-agent" \
-    "$AGENT_CONF" \
+    "$PROJECT_DIR/.claude/agents/qe-agent.md" \
     "QE-Agent" \
     "执行一次 Issue 巡检（单次任务，不要用 /loop）：
 1. python scripts/agent_poller.py --action list --labels test-code 检查 test-code Issue