# 步骤 1a：项目分析

在查看代码结构、入口点或编写任何检测工具之前，先理解该软件在真实世界中是做什么的。这份分析是后续每个步骤的基础——它决定了哪些入口点应优先处理、定义哪些评估标准、使用什么追踪输入，以及构建哪些数据集条目。

---

## 需要调查的内容

阅读项目的 README、文档以及顶层源文件。你需要找到以下五个问题的答案：

### 1. 该软件是做什么的？

用一段简明易懂的语言来概括。它解决了什么问题？一次成功的运行是什么样的？

### 2. 谁在使用它以及为什么？

目标用户是谁？主要用例是什么？它解决了哪些替代方案无法解决的问题？这有助于你理解对该应用而言"质量"意味着什么——一个与客户对话的聊天机器人，与一个综合多源报告的研究型代理，有着截然不同的质量要求。

### 3. 能力清单

列出该应用提供的各项独立能力、模式或功能。要具体。例如：

- 对于一个爬取库：单页爬取、多页爬取、基于搜索的爬取、语音输出、脚本生成
- 对于一个语音代理：问候语、FAQ 处理、账户查询、转接人工、通话摘要
- 对于一个研究代理：主题研究、多源综合、引文生成、报告格式化

每项能力可能需要自己的入口点、自己的追踪记录以及自己的数据集条目。该清单直接为步骤 1c（用例）和步骤 4（数据集多样性）提供输入。

### 4. 真实的输入是什么样的？

描述该应用在真实世界中处理的输入——而非玩具示例：

- 对于一个网页爬取器："包含导航、广告、动态内容、表格、嵌套结构的杂乱 HTML 页面——通常为 5KB–500KB 的 HTML"
- 对于一个研究代理："需要多源综合的开放式研究问题，包含 3–10 个子问题"
- 对于一个语音代理："带有背景噪音、打断和模糊请求的多轮对话"

要具体说明**规模**（多大）、**复杂度**（有多杂乱/多样）以及**多样性**（有哪些种类）。这直接为追踪输入选择（步骤 2）提供依据——如果你不在这里描述真实的输入特征，最终就会使用绕过应用真实逻辑的玩具输入。

**本节是一项操作约束，而不仅仅是文档。** 步骤 2c（追踪输入）和步骤 4c（数据集条目）将交叉引用这些特征，以验证追踪输入和数据集条目是否匹配真实世界的规模和复杂度。要具体且量化——写"5KB–500KB 的 HTML 页面"，而不是"各种 HTML 页面"。

### 5. 难点/故障模式有哪些？

是什么让该应用的工作变得困难？它在实际使用中会在哪些地方失败？这些将成为最有价值的评估场景：

- 对于一个爬取器："格式错误的 HTML、动态 JS 渲染内容、复杂的嵌套模式、超出上下文窗口的超大页面"
- 对于一个研究代理："相互矛盾的来源、需要多步推理的问题、编造引用"
- 对于一个语音代理："模糊的来电者意图、账户查询失败、同时进行的工具调用"

每个故障模式应至少映射到一个评估标准（步骤 1c）和至少一个数据集条目（步骤 4）。

---

## 输出：`pixie_qa/00-project-analysis.md`

将你的发现写入该文件。**在进入子步骤 1b 之前，完成全部五个部分。** 该文档被后续每个步骤引用。

### 模板

```markdown
# 项目分析

## 该软件的功能

<一段话：它做什么，用通俗易懂的语言。不是类名或文件路径——它为使用者解决了什么问题？>

## 目标用户与价值主张

<谁使用它，为什么，它解决了哪些替代方案无法解决的问题>

## 能力清单

1. <能力名称>：<一行描述>
2. <能力名称>：<一行描述>
3. ...

## 真实输入特征

<真实世界输入的样子——规模、复杂度、杂乱程度、多样性。要具体说明规模和结构。>

## 难点与故障模式

1. <故障模式>：<为什么难，会出什么问题>
2. <故障模式>：<为什么难，会出什么问题>
3. ...
```

### 质量检查

在继续之前，请验证：

- "该软件的功能"部分应以非技术用户能理解的方式描述应用的用途——而不仅仅是"它运行一个图"或"它调用 OpenAI"
- 能力清单至少列出 3 项能力（如果项目具备的话）——如果你只找到了 1 项，可能只看了代码库的一部分
- 真实输入特征应描述真实世界的规模和复杂度，而非最简单可能的输入
- 故障模式应针对该应用的特定领域，而非泛泛而谈（"输入错误"不是一个故障模式；"格式错误的 HTML 带有未闭合标签导致解析器崩溃"才是）

### 项目中应忽略的内容

项目中可能包含属于其自身开发/测试基础设施的目录和文件——例如 `tests/`、`fixtures/`、`examples/`、`mock_server/`、`docs/`、演示脚本等。这些是为项目开发者准备的，而不是为你的评估管道准备的。

**关键**：请勿将项目的测试夹具、模拟服务器、示例数据或单元测试基础设施用作评估追踪或数据集条目的输入。它们是为开发速度和隔离性而设计的——数据规模小、干净、确定性强，绕过了所有真实世界的难点。使用它们会产生过于简单的评估，无法捕捉到真正的质量问题。

当你在分析过程中遇到这些目录时，注意它们的存在，但将其视为项目的实现细节——而不是你的 QA 管道的数据来源。你的 QA 管道必须在真实世界条件下测试应用，而不是使用项目自身的测试捷径。