wehub-skill-sync
103 lines
5.6 KiB
Markdown
103 lines
5.6 KiB
Markdown
# 步骤 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 管道必须在真实世界条件下测试应用，而不是使用项目自身的测试捷径。
|