# Tester Feedback Analysis — Claude Code Prompt

> **用途：** 在 Claude Code agent 窗口中读取本文件，agent 将自动完成「测试反馈分析 → Bug 修复文档生成」的全流程。
>
> **使用方式：** 打开 Claude Code，输入：
> ```
> 请读取 researchclaw/feedback/FEEDBACK_ANALYSIS_PROMPT.md，然后按照指示处理 feedback_inbox/ 目录下的所有测试反馈。
> ```

---

## 你的角色

你是 AutoResearchClaw 项目的高级 QA 工程师和代码架构师。你需要分析来自不同学科领域测试者的反馈，与当前 Pipeline 代码进行对比，生成一份结构化的 **Bug 修复文档**。

---

## 背景

AutoResearchClaw 是一个 23 阶段的全自动学术研究 Pipeline（从选题到论文生成）。我们招募了来自不同学科的测试者运行 Pipeline，他们提交了运行反馈和交付物。你需要帮我把这些反馈转化为可执行的 Bug 修复方案。

### ⚠️ 关键认知：测试者使用的可能是旧版本

**这一点极其重要，必须贯穿你的整个分析过程：**

测试者运行 Pipeline 的时间点各不相同，他们使用的代码版本很可能**不是当前主分支的最新版本**。我们的代码在快速迭代中，很多问题在他们测试之后可能已经被修复、部分修复或因架构调整而不再适用。

因此你必须：
- **不要无条件信任反馈中描述的 Bug** —— 它可能已经不存在了
- **对每个问题都要在当前代码中实际验证** —— 读代码确认，而不是仅凭反馈文字就下结论
- **保持批判性思维** —— 测试者的问题描述可能基于旧的代码行为、旧的配置格式、旧的依赖版本
- **如果反馈中提到的函数/类/文件已被重构或删除，直接标记为「已修复/架构已变更」**
- **如果能从压缩包中识别出测试者使用的版本（如 git hash、版本号、时间戳），请记录下来，有助于判断问题时效性**

---

## 输入：反馈目录结构

所有测试反馈存放在 `feedback_inbox/` 目录下（如果实际路径不同，用户会告知）。结构如下：

```
feedback_inbox/
├── tester_alice/
│   ├── 反馈文档.md              # 反馈文档（可能是 .md / .txt / .docx / .pdf）
│   ├── screenshots/             # 截图文件夹（可选）
│   │   ├── error1.png
│   │   └── stage12_fail.png
│   └── artifacts.zip            # Pipeline 交付物压缩包（论文、代码、各阶段输出）
├── tester_bob/
│   ├── feedback.md
│   └── deliverables.tar.gz
├── tester_charlie/
│   └── 测试报告.txt
└── ...
```

**注意：**
- 每个子文件夹 = 一个测试者
- 反馈文档命名不固定，但通常是唯一的文本文件
- 压缩包内是完整的 Pipeline 运行输出目录
- 有些测试者可能只有反馈文档没有压缩包，反之亦然
- 截图可能散落在子文件夹内或专门的 screenshots/ 目录里

---

## 你的工作流程

### 第一步：扫描并读取所有反馈

1. 列出 `feedback_inbox/` 下所有子目录
2. 对每个子目录：
   - 找到反馈文档并读取全文
   - 如有截图，记录文件名（用于在报告中引用）
   - 如有压缩包，列出内容目录（不必完整解压），重点关注：
     - 错误日志（含 error / fail / traceback 的文件）
     - 阶段输出 JSON（stage_*.json / checkpoint.json）
     - Pipeline 元数据（run_meta.json / pipeline_summary.json）
   - 如果压缩包中有明显的报错信息，提取关键片段

### 第二步：理解当前 Pipeline 架构

在分析之前，你需要了解当前代码的最新状态。请阅读以下关键文件：

- `researchclaw/pipeline/stages.py` — 23 阶段定义和状态机
- `researchclaw/pipeline/executor.py` — 核心执行逻辑（重点关注各阶段的 execute 函数）
- `researchclaw/pipeline/runner.py` — Pipeline 运行入口
- `researchclaw/config.py` — 配置结构
- `researchclaw/llm/client.py` — LLM 调用逻辑
- `researchclaw/literature/search.py` — 文献搜索
- `researchclaw/experiment/docker_sandbox.py` — Docker 沙箱执行
- `researchclaw/pipeline/code_agent.py` — 代码生成 Agent
- `researchclaw/templates/converter.py` — LaTeX 转换
- `researchclaw/prompts.py` — Prompt 模板

**不需要逐行阅读，但要对整体架构和各模块职责有清晰认识。**

### 第三步：逐个分析反馈

对每个测试者的反馈，执行以下分析：

#### 3a. 提取问题列表

从反馈文本中提取每一个独立的问题/Bug/需求，包括：
- 明确报告的 Bug（"XX 阶段报错了"）
- 模糊描述的问题（"效果不太好"、"生成的论文有问题"）
- 功能需求（"希望能支持 XX"）
- UX 问题（"不知道怎么配置"）
- 性能问题（"跑了 3 小时还没完"）

#### 3b. 对比代码进行验证

对每个提取的问题：

1. **定位相关代码** — 根据问题描述和涉及的 Pipeline 阶段，找到对应的源代码文件和函数
2. **判断是否仍然存在** — 阅读当前代码，判断这个 Bug 是否已被修复（主分支在快速迭代，部分问题可能已解决）
3. **分析根因** — 如果 Bug 仍存在，分析具体的根本原因（不是表面现象）
4. **评估价值** — 判断这个问题是否值得修复：
   - **值得修复：** 影响 Pipeline 正常运行、影响论文质量、多人反馈的共性问题
   - **暂缓处理：** 边缘场景、个别配置问题、已有 workaround
   - **不处理：** 设计如此、超出范围的需求、无法复现

#### 3c. 生成修复方案

对每个确认的 Bug，给出：
- **具体是什么 Bug** — 一句话描述
- **根因在哪里** — 哪个文件、哪个函数、什么逻辑有问题
- **怎么修复** — 具体的代码修改方案（不需要写完整代码，但要足够具体，比如"在 executor.py 的 `_run_experiment` 函数中，第 XX 行的异常处理需要增加 TimeoutError 的 catch"）
- **修复后的预期行为** — 修好后应该是什么样的

### 第四步：生成 Bug 修复文档

将所有分析结果汇总为一份 Markdown 文档，保存到 `docs/BUG_FIX_DOCUMENT_<日期>.md`。

---

## 输出文档格式

```markdown
# Bug Fix Document — AutoResearchClaw Pipeline

> 生成日期：YYYY-MM-DD
> 反馈来源：N 位测试者
> 总计问题：N 个

## 📊 总览

| 分类 | 数量 |
|------|------|
| 🔴 确认的 Bug（需修复） | N |
| 🟢 已修复（无需处理） | N |
| 🔵 功能需求 | N |
| 🟡 需要更多信息 | N |
| ⚪ 不处理 | N |

## 🔥 修复优先级

| 优先级 | ID | 问题 | 阶段 | 涉及文件 |
|--------|----|------|------|----------|
| 🔴 CRITICAL | xxx-001 | ... | ... | ... |
| 🟠 HIGH | xxx-002 | ... | ... | ... |
| ... | ... | ... | ... | ... |

---

## 确认的 Bug — 详细修复方案

### 🔴 `xxx-001` — Bug 标题

| 字段 | 内容 |
|------|------|
| **严重程度** | CRITICAL / HIGH / MEDIUM / LOW |
| **所属阶段** | STAGE_NAME |
| **报告者** | tester_id |

**问题描述：**
xxx

**根因分析：**
xxx（具体到文件名、函数名、行号、逻辑问题）

**涉及文件：**
- `researchclaw/xxx/yyy.py`

**修复方案：**
xxx（具体的修改步骤，另一台机器上的 agent 能直接按此执行）

**修复后预期行为：**
xxx

<details>
<summary>原始反馈证据</summary>
（测试者的原话和截图引用）
</details>

---

（重复以上格式，直到所有确认的 Bug 都写完）

---

## 功能需求

### 🔵 `xxx-010` — 需求标题
- 报告者：xxx
- 描述：xxx
- 建议：xxx

---

## 已修复（无需处理）

| ID | 问题 | 报告者 | 已修复原因 |
|----|------|--------|-----------|
| ... | ... | ... | ... |

---

## 附录：按测试者分组

### 测试者：`tester_alice`
- 学科/领域：xxx（如果能从反馈中推断）
- 总计问题：N
- 确认 Bug：N
- 已修复：N

| ID | 问题 | 状态 | 严重程度 |
|----|------|------|---------|
| ... | ... | ... | ... |
```

---

## 重要原则

1. **代码为准：** 判断 Bug 是否存在时，以当前代码为准，不要猜测。实际读代码确认。
2. **具体到位：** 修复方案要具体到文件、函数、逻辑，让另一个 agent 能直接执行。不要只说"需要优化"这种模糊描述。
3. **合并去重：** 多个测试者报告同一个问题时，合并为一条，注明所有报告者。
4. **区分表里：** 测试者描述的可能是表面现象，你需要找到深层根因。
5. **务实判断：** 不是所有反馈都值得处理。有些是配置问题、有些是预期行为、有些修复代价远大于收益 —— 这些需要你做出判断。
6. **保留证据：** 每个问题都保留测试者的原始描述作为证据。
7. **中文输出：** 文档用中文书写（技术术语、代码、文件名保持英文）。

---

## 特殊情况处理

- **反馈文档是英文：** 正常分析，输出仍用中文。
- **没有压缩包只有反馈文档：** 仅基于反馈文本分析，标注"无法验证运行产物"。
- **没有反馈文档只有压缩包：** 从压缩包的错误日志和阶段输出中推断问题。
- **反馈内容模糊难以定位：** 归类为"需要更多信息"，说明缺少什么信息。
- **反馈涉及已删除/重构的功能：** 标记为"已修复"或"架构已变更"。

---

## 第五步：提交并推送

分析完成、文档生成后，你需要完成以下操作：

1. **切换到主分支：** `git checkout main`
2. **将 Bug 修复文档提交到 `docs/` 目录：**
   - 文件命名格式：`docs/BUG_FIX_DOCUMENT_<YYYYMMDD>.md`
   - 如果当天已有同名文档，加序号：`docs/BUG_FIX_DOCUMENT_<YYYYMMDD>_02.md`
3. **提交并推送到远程主分支：**
   ```
   git add docs/BUG_FIX_DOCUMENT_<date>.md
   git commit -m "docs: add bug fix document from tester feedback (<date>)"
   git push origin main
   ```
4. **告知用户：** 推送完成后，告知用户文档路径和 Bug 摘要，以便在其他机器上拉取并执行修复。

**重要：** 提交时不要加 Co-Authored-By，commit 作者只能是用户自己。

---

## 开始

现在请扫描 feedback inbox 目录，开始工作。
