Files

T

CI / test (pull_request) Successful in 22s

Details

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>

2026-06-08 16:11:32 +08:00

3.6 KiB

Raw Blame History

document_analyzer — PRD-to-IR Pipeline

基于 AI 的车机 PRD 文档解析与结构化 IR 生成 pipeline。通过 Dev-Agent 与 QE-Agent 协同迭代，探索 AI Agent 多智能体协作的软件工程闭环。

项目文档（session 启动时读取）

使用 Read 工具加载以下文件（绝对路径，不要用 Glob）：

C:\Users\peterz\projects\document_analyzer\docs\PROJECT_CHARTER.md — 项目愿景、目标、架构、约束
C:\Users\peterz\projects\document_analyzer\docs\GLOBAL_STATE.md — 当前阶段目标、已知问题、最近变更

Gitea 配置

配置文件：~/.gitea/config.yaml，按 GITEA_USER 环境变量选择 profile
默认使用人类用户身份（generic session）：export GITEA_USER=pzhangzywl
Agent 身份通过各自环境变量设置（Dev: pzhang_dev_agent_01，QE: pzhang_qe_agent_01）
所有 Gitea API 操作必须通过 python scripts/agent_poller.py，禁止直接 curl 或硬编码 token

工作区隔离

本项目使用 Git worktree 实现多 Agent 会话隔离，确保多个 Generic/Dev/QE session 并发运行互不干扰：

Primary worktree (C:\Users\peterz\projects\document_analyzer\) 是只读参考区。仅用于代码阅读、git log 查询、文档查阅、启动脚本。不在此目录做任何开发提交。
Generic session 开发：使用 bash scripts/start_generic.sh 启动，自动在 ~/.gitea/worktrees/pzhangzywl/<timestamp>/ 创建隔离工作区。
Agent sessions：由 start_dev_agent.sh / start_qe_agent.sh 自动在 ~/.gitea/worktrees/<user>/<timestamp>/ 创建隔离工作区。
所有 session 的 worktree 以 detached 模式从 origin/main 创建，严禁在任何 worktree 中 checkout main 分支。
Feature branch 直接从 origin/main 创建：git fetch origin && git checkout -b <branch> origin/main

代码同步

Primary worktree：git fetch origin 即可（只读，不 pull）。
隔离 worktree：启动脚本自动从最新 origin/main 创建，始终是最新代码。
Session 运行中需要同步时：git fetch origin，新分支从最新 origin/main 创建。

上下文管理

Context window 有限。当 session 持续较长时间时：

根据对话轮次和消息长度估计 context 使用量
使用量达 ~80% 时主动使用 /compact 压缩对话
压缩时保留：当前 Issue 上下文、GLOBAL_STATE.md、PROJECT_CHARTER.md、Agent 角色定义
压缩后从摘要恢复上下文，继续当前任务

核心规则

代码改动走完整流程：Issue → 分支 → 开发/UT → pytest → PR → CI → merge → 自行验证 → 关闭 Issue
关闭 Issue 必须包含 4 要素：问题 / 根因 / 修复 / 验证
Label 优先原则：Issue 的 label 反映创建者（尤其是人类）的显式意图，Agent 必须尊重
- test-code → QE-Agent 域，product-code → Dev-Agent 域
- 即使内容看似不在自身常规范围，只要 label 指定了自己的域，就必须 pick up
- Label 与内容明显冲突时，先 pick up 并评论确认，不直接跳过
禁止直接改代码：任何对 git 管理内容的修改必须走完整闭环（Issue → 分支 → 开发/UT → pytest → PR → CI → merge → 验证 → 关闭），即使是 trivial 修改也如此。禁止绕过此流程直接编辑文件

Agent 模式

Dev-Agent: 启动时自动加载 .claude/agents/dev-agent.md（功能开发、重构、UT、接口集成测试）
QE-Agent: 启动时自动加载 .claude/agents/qe-agent.md（验收测试、质量门禁）
Generic session: 仅加载本文件，使用人类用户身份工作

3.6 KiB Raw Blame History Unescape Escape