wehub-skill-sync
5.6 KiB
步骤 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 之前，完成全部五个部分。 该文档被后续每个步骤引用。
模板
# 项目分析
## 该软件的功能
<一段话：它做什么，用通俗易懂的语言。不是类名或文件路径——它为使用者解决了什么问题？>
## 目标用户与价值主张
<谁使用它，为什么，它解决了哪些替代方案无法解决的问题>
## 能力清单
1. <能力名称>：<一行描述>
2. <能力名称>：<一行描述>
3. ...
## 真实输入特征
<真实世界输入的样子——规模、复杂度、杂乱程度、多样性。要具体说明规模和结构。>
## 难点与故障模式
1. <故障模式>：<为什么难，会出什么问题>
2. <故障模式>：<为什么难，会出什么问题>
3. ...
质量检查
在继续之前，请验证：
- "该软件的功能"部分应以非技术用户能理解的方式描述应用的用途——而不仅仅是"它运行一个图"或"它调用 OpenAI"
- 能力清单至少列出 3 项能力（如果项目具备的话）——如果你只找到了 1 项，可能只看了代码库的一部分
- 真实输入特征应描述真实世界的规模和复杂度，而非最简单可能的输入
- 故障模式应针对该应用的特定领域，而非泛泛而谈（"输入错误"不是一个故障模式；"格式错误的 HTML 带有未闭合标签导致解析器崩溃"才是）
项目中应忽略的内容
项目中可能包含属于其自身开发/测试基础设施的目录和文件——例如 tests/、fixtures/、examples/、mock_server/、docs/、演示脚本等。这些是为项目开发者准备的，而不是为你的评估管道准备的。
关键：请勿将项目的测试夹具、模拟服务器、示例数据或单元测试基础设施用作评估追踪或数据集条目的输入。它们是为开发速度和隔离性而设计的——数据规模小、干净、确定性强，绕过了所有真实世界的难点。使用它们会产生过于简单的评估，无法捕捉到真正的质量问题。
当你在分析过程中遇到这些目录时，注意它们的存在，但将其视为项目的实现细节——而不是你的 QA 管道的数据来源。你的 QA 管道必须在真实世界条件下测试应用，而不是使用项目自身的测试捷径。