zeekrAI/document_analyzer
1
0
Fork 1
Code Issues 2 Pull Requests Actions Packages Projects Releases Wiki Activity

[product] Git Workflow 多 Session 并发隔离改造 #124

New Issue
Closed
opened 2026-06-08 16:07:35 +08:00 by pzhang_zywl · 2 comments
pzhang_zywl commented 2026-06-08 16:07:35 +08:00
Owner
Copy Link
Copy Source

问题

当前项目支持 Generic / Dev-Agent / QE-Agent 三种 Claude Code session，每种可能同时运行多个实例。但现有 git worktree 机制存在严重并发缺陷：

  1. QE-Agent checkout main — agents/QE_AGENT.md Step 3.1 指示 git checkout main，锁死 main 分支
  2. Worktree 按用户名命名 — ~/.gitea/worktrees/<GITEA_USER>/，同类型多 session 冲突
  3. Generic session 无 worktree 隔离 — CLAUDE.md 没有 worktree 机制
  4. Agent git 命令不感知并发 — git pull origin main 假设 base 不会变
  5. Primary worktree 无明确定位 — 当前陷入 detached HEAD

设计方案

核心原则

  1. 任何 session 都不 checkout main — main 只在 primary worktree 中
  2. 所有开发在 session-unique worktree: ~/.gitea/worktrees///
  3. Worktree 以 detached 模式创建: git worktree add --detach origin/main
  4. Feature branch 直接从 origin/main 创建: git fetch origin && git checkout -b origin/main
  5. Primary worktree 定位为只读参考区

文件变更

文件 变更
scripts/_common.sh setup_worktree: session-unique 路径 + detached + fetch；cleanup_worktree: 无参数 + --force
scripts/start_dev_agent.sh trap 无参数
scripts/start_qe_agent.sh 同上
CLAUDE.md 新增工作区隔离章节，代码同步改 fetch-only
agents/DEV_AGENT.md Step 3: git pull origin main → git fetch origin && git checkout -b ... origin/main
agents/QE_AGENT.md Step 3.1: git checkout main → git fetch origin && git checkout -b test/issue-N origin/main
.claude/agents/dev-agent.md 同上 + 补充 worktree 说明
.claude/agents/qe-agent.md 同上 + 补充 worktree 说明
scripts/start_generic.sh 新文件 — generic session worktree 隔离启动器

保护机制

即使 Agent 忽略文档仍运行 git checkout main：primary worktree 持有 main → agent checkout 报错 already checked out，硬阻止。

[pzhangzywl]

## 问题 当前项目支持 Generic / Dev-Agent / QE-Agent 三种 Claude Code session，每种可能同时运行多个实例。但现有 git worktree 机制存在严重并发缺陷： 1. **QE-Agent checkout main** — agents/QE_AGENT.md Step 3.1 指示 git checkout main，锁死 main 分支 2. **Worktree 按用户名命名** — ~/.gitea/worktrees/<GITEA_USER>/，同类型多 session 冲突 3. **Generic session 无 worktree 隔离** — CLAUDE.md 没有 worktree 机制 4. **Agent git 命令不感知并发** — git pull origin main 假设 base 不会变 5. **Primary worktree 无明确定位** — 当前陷入 detached HEAD ## 设计方案 ### 核心原则 1. 任何 session 都不 checkout main — main 只在 primary worktree 中 2. 所有开发在 session-unique worktree: ~/.gitea/worktrees/<user>/<timestamp>/ 3. Worktree 以 detached 模式创建: git worktree add --detach origin/main 4. Feature branch 直接从 origin/main 创建: git fetch origin && git checkout -b <branch> origin/main 5. Primary worktree 定位为只读参考区 ### 文件变更 | 文件 | 变更 | |------|------| | scripts/_common.sh | setup_worktree: session-unique 路径 + detached + fetch；cleanup_worktree: 无参数 + --force | | scripts/start_dev_agent.sh | trap 无参数 | | scripts/start_qe_agent.sh | 同上 | | CLAUDE.md | 新增工作区隔离章节，代码同步改 fetch-only | | agents/DEV_AGENT.md | Step 3: git pull origin main → git fetch origin && git checkout -b ... origin/main | | agents/QE_AGENT.md | Step 3.1: git checkout main → git fetch origin && git checkout -b test/issue-N origin/main | | .claude/agents/dev-agent.md | 同上 + 补充 worktree 说明 | | .claude/agents/qe-agent.md | 同上 + 补充 worktree 说明 | | scripts/start_generic.sh | 新文件 — generic session worktree 隔离启动器 ### 保护机制 即使 Agent 忽略文档仍运行 git checkout main：primary worktree 持有 main → agent checkout 报错 already checked out，硬阻止。 --- [pzhangzywl]
pzhang_zywl added the product-code label 2026-06-08 16:07:35 +08:00
pzhang_zywl commented 2026-06-08 16:14:04 +08:00
Author
Owner
Copy Link
Copy Source

PR: #125

变更:

  • _common.sh: setup_worktree 改为 session-unique detached worktree (origin/main) + cleanup_worktree 无参数 --force
  • 所有 Agent 文档移除 git checkout main / git pull origin main
  • Feature branch 统一从 origin/main 创建
  • CLAUDE.md 新增工作区隔离章节
  • 新增 start_generic.sh

等待 CI 通过后 merge。

[pzhangzywl]

PR: https://git.zywl.me/zeekrAI/document_analyzer/pulls/125 变更: - _common.sh: setup_worktree 改为 session-unique detached worktree (origin/main) + cleanup_worktree 无参数 --force - 所有 Agent 文档移除 git checkout main / git pull origin main - Feature branch 统一从 origin/main 创建 - CLAUDE.md 新增工作区隔离章节 - 新增 start_generic.sh 等待 CI 通过后 merge。 --- [pzhangzywl]
pzhang_zywl commented 2026-06-08 16:15:08 +08:00
Author
Owner
Copy Link
Copy Source

问题

多 Agent/Gereric session 并发运行时，git worktree 机制存在严重冲突：QE-Agent checkout main 锁死 main、worktree 按用户名命名导致同类型多 session 冲突、Generic session 无隔离、Agent git 命令不感知并发。

根因

  1. QE_AGENT.md Step 3.1 指示 git checkout main，导致 main 被 worktree 独占
  2. setup_worktree() 按用户名命名路径，不具备 session 唯一性
  3. CLAUDE.md 无 worktree 隔离机制，所有 generic session 共享 primary worktree
  4. Agent 文档使用 git pull origin main 假设 base 不变
  5. Primary worktree 无明确定位

修复

  1. _common.sh setup_worktree: session-unique 路径 (user/timestamp) + detached from origin/main + 新变量 _WORKTREE_PATH
  2. _common.sh cleanup_worktree: 无参数，基于 _WORKTREE_PATH + --force
  3. 所有 Agent 文档: git checkout main / git pull origin main → git fetch origin + git checkout -b origin/main
  4. CLAUDE.md: 新增工作区隔离章节，primary 定义为只读参考区
  5. 新增 start_generic.sh: Generic session 工作区隔离启动器

验证

  • pytest: 117 passed, 15 skipped (无回归)
  • PR #125 CI: success (22s)
  • Primary worktree 回到 main (dc0b9ba)
  • git worktree list 仅 1 个 entry，无 main lock

[pzhangzywl]

## 问题 多 Agent/Gereric session 并发运行时，git worktree 机制存在严重冲突：QE-Agent checkout main 锁死 main、worktree 按用户名命名导致同类型多 session 冲突、Generic session 无隔离、Agent git 命令不感知并发。 ## 根因 1. QE_AGENT.md Step 3.1 指示 git checkout main，导致 main 被 worktree 独占 2. setup_worktree() 按用户名命名路径，不具备 session 唯一性 3. CLAUDE.md 无 worktree 隔离机制，所有 generic session 共享 primary worktree 4. Agent 文档使用 git pull origin main 假设 base 不变 5. Primary worktree 无明确定位 ## 修复 1. _common.sh setup_worktree: session-unique 路径 (user/timestamp) + detached from origin/main + 新变量 _WORKTREE_PATH 2. _common.sh cleanup_worktree: 无参数，基于 _WORKTREE_PATH + --force 3. 所有 Agent 文档: git checkout main / git pull origin main → git fetch origin + git checkout -b <branch> origin/main 4. CLAUDE.md: 新增工作区隔离章节，primary 定义为只读参考区 5. 新增 start_generic.sh: Generic session 工作区隔离启动器 ## 验证 - pytest: 117 passed, 15 skipped (无回归) - PR #125 CI: success (22s) - Primary worktree 回到 main (dc0b9ba) - git worktree list 仅 1 个 entry，无 main lock --- [pzhangzywl]
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
blocked
被其他 issue 阻塞，暂不处理
 product-code
产品功能相关
 test-code
QE-Agent 测试代码相关
No Label product-code
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
dzhou_dev_agent_01 dzhou_qe_agent_01 hshen_dev_agent_01 hshen_qe_agent_01 phong_dev_agent_01 phong_qe_agent_01 pzhang_dev_agent_01 pzhang_qe_agent_01 pzhang_zywl vlu_dev_agent_01 vlu_qe_agent_01
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: zeekrAI/document_analyzer#124
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?