[Refactor](feat) Modular pipeline architecture

docs/fix-validation-flow.md

@@ -0,0 +1,106 @@
+# 编译与测试修复代码的评价和测试机制
+
+## 总体流程
+
+```mermaid
+flowchart TD
+    subgraph BUILD["编译修复循环 (pipeline/build.py)"]
+        B1["Build TA"] --> B2{编译通过?}
+        B2 -->|是| B_DONE["build_passed=true"]
+        B2 -->|否| B3["AI 修复 (ai_fix)"]
+        B3 --> B4["代码评价 (validate_fix)"]
+        B4 --> B5{校验通过?}
+        B5 -->|否| B6["回退修改 + 写入拒绝原因"]
+        B6 --> B7["不消耗 attempt 次数"]
+        B7 --> B3
+        B5 -->|是| B8["记录本次 fix attempt"]
+        B8 --> B9{attempt <= max?}
+        B9 -->|是| B1
+        B9 -->|否| B_FAIL["build_passed=false"]
+    end
+
+    subgraph TEST["测试修复循环 (pipeline/test.py)"]
+        T1["Run pytest"] --> T2{测试通过?}
+        T2 -->|是| T_DONE["test_passed=true"]
+        T2 -->|否| T3{"OOM 检测?"}
+        T3 -->|是| T4["降并发重跑 (最多5次)"]
+        T4 --> T5{OOM 消失?}
+        T5 -->|是| T6["继续正常修复"]
+        T5 -->|否| T_FAIL["test_passed=false"]
+        T3 -->|否| T6
+        T6 --> T7["AI 修复 (ai_fix)"]
+        T7 --> T8["代码评价 (validate_fix)"]
+        T8 --> T9{校验通过?}
+        T9 -->|否| T10["回退修改 + 写入拒绝原因"]
+        T10 --> T11["不消耗 attempt 次数"]
+        T11 --> T7
+        T9 -->|是| T12["Rebuild TA"]
+        T12 --> T13{编译通过?}
+        T13 -->|否| T14["attempt += 1"]
+        T14 --> T15{attempt <= max?}
+        T15 -->|是| T7
+        T15 -->|否| T_FAIL
+        T13 -->|是| T1
+    end
+
+    B_DONE --> NEXT["下一步"]
+    B_FAIL --> TERMINATE["流程终止"]
+    T_DONE --> NEXT
+    T_FAIL --> TERMINATE
+```
+
+## 代码评价机制 (validate_fix)
+
+```mermaid
+flowchart TD
+    A["AI 修复完成"] --> B["获取 modified_files 列表"]
+    B --> C{"有修改文件?"}
+    C -->|否| REJECT["❌ 拒绝: No files modified"]
+    C -->|是| D["逐个检查文件路径"]
+    D --> E{"文件在 third_party/ascend/ 下?"}
+    E -->|全部是| PASS["✅ 校验通过<br/>记录 attempt"]
+    E -->|有文件在外面| F["记录非法文件列表"]
+    F --> G["git checkout -- ."]
+    G --> H["git clean -fd"]
+    H --> I["写入 fix_rejection.txt<br/>包含拒绝原因 + 允许的路径"]
+    I --> J["追加到 fix_errors 列表<br/>(AI 下次修复会看到)"]
+    J --> K["❌ 拒绝: 不消耗 attempt<br/>continue 重新修复"]
+
+    style PASS fill:#4a9,stroke:#333
+    style REJECT fill:#d73,stroke:#333
+    style K fill:#d73,stroke:#333
+```
+
+## AI 自检机制 (prompt.md step 6)
+
+```mermaid
+flowchart LR
+    subgraph AI_SELF["AI 修复时自检 (prompt.md)"]
+        S1["Step 6: SELF-REVIEW before returning"]
+        S2["列出每个修改的文件"]
+        S3{"文件在 third_party/ascend/ 下?<br/>(测试修复也可在 python/triton_ascend/)"}
+        S3 -->|否| S4["在返回前 REVERT 该修改"]
+        S4 --> S3
+        S3 -->|是| S5{"修复针对根因<br/>而非掩盖错误?"}
+        S5 -->|否| S4
+        S5 -->|是| S6["返回修改"]
+    end
+
+    style S4 fill:#d73,stroke:#333
+    style S6 fill:#4a9,stroke:#333
+```
+
+## 双层防护总结
+
+| 层级 | 位置 | 机制 | 失败处理 |
+|------|------|------|----------|
+| **第1层** | AI 自检 (prompt.md) | AI 提交前自查文件路径 + 根因 | 自行回退后重新修复 |
+| **第2层** | 代码校验 (fix.py) | 硬检查 modified_files 路径 | git revert + 反馈文件 + 不消耗 attempt |
+| **第3层** | 编译/测试验证 | 实际 build/test 结果 | 编译/测试失败 → 继续 fix loop |
+
+## 关键设计决策
+
+1. **拒绝不消耗 attempt**：修复被拒后 `continue` 在同一 attempt 重新修复（while 循环），确保 AI 有完整的 max_retries 次有效尝试
+2. **拒绝后回退代码**：`git checkout -- .` + `git clean -fd` 清除所有修改，下一轮从干净状态开始
+3. **拒绝反馈传递给 AI**：`fix_rejection.txt` 追加到 `fix_errors` 列表，AI 下次修复时在 error_logs 中看到
+4. **OOM 单独处理**：OOM 不调用 AI，自动降并发重跑（test_procs 减半），与代码修复完全独立

docs/workflow.md

@@ -1,23 +1,164 @@
+# 单步模式工作流
+
 ```mermaid
 flowchart TD
-    A["ta-kickoff"]
-    A --> B["Phase 0: Initialize"]
-    B --> C["Phase 1: Detect Commits"]
-    C -->|no new commits| D["Done: Already Up-to-Date"]
-    C -->|new commits found| E["Phase 2A: Merge Upstream"]
-    E -->|conflicts| F["Phase 2B: AI Resolve Conflicts"]
-    E -->|no conflicts| G["Phase 2C: Build and Test"]
-    F -->|resolved| G
-    F -->|max retries| H["Failure: write FAILURE.md"]
-    G --> G1["Build: setup.py install"]
-    G1 -->|failed| I["AI Fix Code"]
-    G1 -->|passed| G2["Test: pytest"]
-    G2 -->|failed| I
-    G2 -->|passed| J["Commit Fixes"]
-    I -->|retry| G1
-    I -->|max retries| H
-    J --> K["Phase 2D: Finalize"]
-    K --> L["Success"]
-    L -->|push enabled| M["Push Branch and Create PR"]
-    L -->|push disabled| N["Done: work branch kept"]
-```
+    A["ta-kickoff"] --> B["Phase 0: Prepare<br/>克隆/配置 repo、remotes"]
+    B --> C["Phase 1: Detect<br/>检测待合并的上游 commits"]
+    C -->|无新 commit| D["Done: Already Up-to-Date"]
+    C -->|有新 commit| E["Phase 2: Plan<br/>按行数预算切分步骤"]
+    E --> F["Phase 3: Per-Step Loop"]
+
+    subgraph STEP["每个步骤 (while current_step < total_steps)"]
+        F1["Step A: Merge<br/>git merge upstream commits"]
+        F1 --> F2{有冲突?}
+        F2 -->|是| F3["Step B: Resolve<br/>AI 解决冲突 (max_retries)"]
+        F3 -->|未解决| FAIL["UpgradeFailed"]
+        F3 -->|已解决| F4
+        F2 -->|否| F4{LLVM 版本变更?}
+
+        F4 -->|是| F5["Step C: IR Patch Pipeline<br/>Phase 1: 编译适配<br/>Phase 2: IR 补丁生成+测试"]
+        F4 -->|否| F6["Step C: Build + Fix Loop<br/>编译 - AI 修复 - 重编译"]
+
+        F5 --> F7{IR 补丁通过?}
+        F7 -->|否| FAIL
+        F7 -->|是| F8
+
+        F6 --> F8{编译通过?}
+        F8 -->|否| FAIL
+        F8 -->|是| F9["Step D: Test + Fix Loop<br/>pytest - OOM 重跑 - AI 修复"]
+
+        F9 --> F10{测试通过?}
+        F10 -->|否| FAIL
+        F10 -->|是| F11["Step E: Commit<br/>提交步骤进度"]
+
+        F11 --> F12["current_step += 1"]
+        F12 -->|还有步骤| F1
+        F12 -->|全部完成| G
+    end
+
+    STEP --> G["Phase 4: Finalize<br/>生成 summary + cumulative patch"]
+
+    G -->|PUSH_TO_GITHUB=true| H["Push + Create PR"]
+    G -->|PUSH_TO_GITHUB=false| I["Done: work branch 保留"]
+
+    style FAIL fill:#d73,stroke:#333
+    style D fill:#4a9,stroke:#333
+    style I fill:#4a9,stroke:#333
+    style H fill:#4a9,stroke:#333
+```
+
+## IR Patch Pipeline (LLVM hash 变更时)
+
+```mermaid
+flowchart TD
+    subgraph IR["IR Patch Pipeline"]
+        P1["Phase 1: 编译适配"]
+        P1A["Build clean LLVM"] --> P1B["Build TA"]
+        P1B --> P1C{编译通过?}
+        P1C -->|否| P1D["AI 修复 (只改 third_party/ascend/)<br/>AscendNPU-IR 专项文档"]
+        P1D -->|retries 耗尽| IR_FAIL["IR Pipeline Failed"]
+        P1D --> P1B
+        P1C -->|是| P2["Phase 2: IR 补丁循环"]
+
+        P2A["OP 分析 + LLVM 变更分析"] --> P2B["AI 生成 IR 补丁"]
+        P2B --> P2C["应用补丁 + 编译 LLVM<br/>(失败时 AI 修复, 最多 10 次)"]
+        P2C -->|成功| P2D["Build TA + pytest"]
+        P2C -->|10 次耗尽| IR_FAIL
+        P2D -->|通过| IR_PASS["Pipeline Passed"]
+        P2D -->|失败| P2F["诊断: IR vs 代码"]
+        P2F -->|IR 问题| P2G["重新生成补丁 (最多 3 次)"]
+        P2G --> P2C
+        P2F -->|代码问题| P2H["AI 修复 → Rebuild → 重测"]
+        P2H --> P2D
+    end
+
+    style IR_FAIL fill:#d73,stroke:#333
+    style IR_PASS fill:#4a9,stroke:#333
+```
+
+## 修复代码评价机制
+
+```
+AI 修复
+  ↓
+Layer 1: AI 自检 (prompt.md step 6)
+  └─ 检查文件路径 → 不在允许目录则自行回退
+  ↓
+Layer 2: 代码校验 (validate_fix)
+  └─ 硬检查 → 不通过则 git revert + 反馈 + 不消耗 attempt
+  ↓
+Layer 3: 实际验证
+  └─ 编译/测试结果 → 失败则继续 fix loop
+```
+
+详见 [fix-validation-flow.md](fix-validation-flow.md)
+
+## 环境变量速查
+
+### 仓库 & 分支
+| 变量 | 默认值 | 说明 |
+|------|--------|------|
+| `TRITON_ASCEND_PATH` | (当前目录) | triton-ascend 本地路径 |
+| `TRITON_PATH` | (空) | 上游 triton 本地路径 |
+| `TRITON_TARGET_COMMIT` | (upstream HEAD) | 要合并的目标 commit |
+| `TA_BASE_BRANCH` | `upstream_sync` | 基线分支名 |
+| `TA_WORK_BRANCH_BASE` | `upstream-ascend` | 工作分支 base remote |
+
+### 构建 & 测试
+| 变量 | 默认值 | 说明 |
+|------|--------|------|
+| `BUILD_PROCS` / `MAX_JOBS` | 32 | 并行编译数（`MAX_JOBS` 为旧名，向后兼容） |
+| `TEST_PROCS` / `NUM_PROCS` | 16 | 并行 pytest 数（`NUM_PROCS` 为旧名） |
+| `LLVM_PROJECT_PATH` | `~/llvm-project` | LLVM 源码路径 |
+| `LLVM_INSTALL_PREFIX_SYNC` | `~/llvm-install-sync` | LLVM 安装路径 |
+| `LLVM_INSTALL_PREFIX` | (空) | LLVM 安装前缀（优先级高于上面） |
+| `SKIP_BUILD` | `false` | 跳过编译 |
+| `SKIP_E2E_TEST` | `false` | 跳过测试 |
+| `SKIP_BASELINE_LLVM` | `false` | 跳过基线 LLVM 编译（已有 LLVM 时使用） |
+| `SKIP_LLVM_REBUILD` | `false` | 跳过 LLVM 版本变更时的重编译 |
+
+### 测试目录（可插拔）
+| 变量 | 默认值 | 说明 |
+|------|--------|------|
+| `TA_TEST_DIR` | `third_party/ascend/unittest/pytest_ut` | 主测试目录 |
+| `TA_EXTRA_TEST_DIRS` | (空) | 额外 pytest 目录，逗号/空格分隔 |
+| `TA_TEST_COMMAND` | (空) | 自定义测试命令（在 pytest ut 之后额外执行） |
+
+### AI & 重试
+| 变量 | 默认值 | 说明 |
+|------|--------|------|
+| `AI_BACKEND` | `auto` | AI 后端（`opencode` / `claude`） |
+| `SKIP_AI_ANALYSIS` | `false` | 跳过 AI 调用 |
+| `TA_MAX_RETRIES` | 10 | AI 修复最大重试次数 |
+| `TA_LINE_BUDGET` | 1000 | 每步最大源码行数 |
+
+### PR
+| 变量 | 默认值 | 说明 |
+|------|--------|------|
+| `PUSH_TO_GITHUB` | `false` | 自动创建 PR |
+| `GITHUB_REPO` | `triton-lang/triton-ascend` | PR 目标仓库 |
+
+### 其他
+| 变量 | 默认值 | 说明 |
+|------|--------|------|
+| `TA_SINGLE_STEP_MODE` | `true` | 单步模式 |
+| `TA_RESUME` | `false` | 从缓存恢复（跳过已完成的步骤） |
+| `PYTHON` | `python3` | Python 解释器 |
+| `CONDA_ENV` | `ta-upgrade` | Conda 环境名 |
+| `TA_MAIN2MAIN_WORKSPACE` | `./workspace` | 工作区目录 |
+
+## CLI 参数
+
+```
+ta-kickoff [选项]
+
+  --triton-ascend-path PATH     triton-ascend 仓库路径
+  --triton-path PATH            上游 triton 仓库路径
+  --target-commit SHA           目标 commit
+  --llvm-prefix PATH            LLVM 安装前缀
+  --conda-env NAME              Conda 环境名
+  --build-procs N               并行编译数
+  --test-procs N                并行测试数
+  --extra-test-dirs DIRS        额外测试目录（逗号分隔）
+  --test-command CMD            自定义测试命令
+```

pyproject.toml

@@ -1,20 +1,14 @@
 [project]
 name = "TA_main2main_workflow"
-version = "0.1.0"
-description = "TA_main2main_workflow — Triton-Ascend upstream sync using CrewAI"
+version = "0.2.0"
+description = "TA_main2main_workflow — Triton-Ascend upstream sync (modular pipeline)"
 authors = [{ name = "Your Name", email = "you@example.com" }]
 requires-python = ">=3.10,<3.14"
-dependencies = [
-    "crewai[tools]==1.14.5"
-]
+dependencies = []
 
 [project.scripts]
 ta-kickoff = "TA_main2main_workflow.main:kickoff"
-ta-plot = "TA_main2main_workflow.main:plot"
 
 [build-system]
 requires = ["hatchling"]
 build-backend = "hatchling.build"
-
-[tool.crewai]
-type = "flow"