用途
Stranger Test Protocol 用于验证文档、README 和入门指南是否能让零背景的读者理解。它回答一个核心问题：“一位有能力的开发者，在零上下文的情况下，能否在 5 分钟内理解这个项目做什么、为什么存在以及如何开始？”该协议提供系统化的评估框架，帮助作者发现文档中的理解障碍。
主要能力
协议将评估分为三个层级：
- Level 1：初次接触（30 秒）——评估 README 首屏。检查是否有一句话清晰描述“这是什么”、目标受众是否明确、是否说明问题或价值、是否有维护活跃信号（近期活动、徽章、日期）。
- Level 2：理解（2 分钟）——评估读完完整 README 后的理解程度。检查能否在餐巾纸上勾勒系统架构、核心抽象是否定义、范围边界是否清晰（做什么与不做什么）、与生态中其他工具的关系是否说明。
- Level 3：激活（5 分钟）——评估入门体验。检查前置条件是否明确列出、安装步骤是否可复制粘贴、能否运行 hello-world 获得首次成功、安装后是否有清晰的后续步骤。
使用方式
测试按以下步骤进行：
- 采用陌生人思维：暂时忘记所有项目上下文，像第一次在 GitHub 上遇到它一样阅读，记录每一个困惑时刻，即使你“知道答案”。
- 顺序限时阅读：按顺序阅读仓库名称和描述、README.md（从上到下）、第一个链接的指南（如有）、第一个代码示例（如有），并计时。
- 记录困惑点：对每个困惑点记录位置（如 README.md 第 23 行）、困惑内容、严重程度（高/中/低）和修复建议。
- 逐项评估：将每个标准评为 PASS、PARTIAL 或 FAIL，并提供证据。
- 生成报告：报告包含测试者、日期、首次理解时间、首次成功时间，以及三个层级的评估结果、按严重程度排序的困惑点和按影响排序的建议。
适用场景
该协议可应用于不同类型的文档，侧重点不同：
- README：侧重 Level 1 和 Level 3，因为 README 是前门，必须立即回答“是什么”和“如何开始”。
- API 文档：侧重 Level 2 和 Level 3，开发者需要理解概念并快速完成首次 API 调用。
- 贡献指南：侧重 Level 3，读者有动机但需要从“我想帮忙”到“我提交了 PR”的清晰路径。
- 架构文档：侧重 Level 2，新团队成员能否理解系统以便知道在哪里做修改。
协议还可与 CI 集成，在 PR 模板中加入检查项，例如：新贡献者能否从链接文档理解 PR 上下文、新概念是否在首次使用前定义、文档中的命令是否可复制粘贴并经过测试。
限制
协议明确指出若干反模式：作者不能自己当陌生人，需要新鲜视角；“这很明显”如果还需要说，对陌生人就不明显；添加术语表只治标，在首次使用时定义术语才治本；应在每次重大文档变更后运行陌生人测试，而非一次性测试；完美主义不可取，带行动计划的 PARTIAL 通过胜过从不测试。
常见失败案例
协议列举了常见失败模式及改进示例：
- 未定义术语：坏例子“本仓库管理 ORGANVM 八器官模型的 Taxis 编排层。”好例子“本仓库在 ORGANVM 上编排自动化工作流——一个将约 100 个仓库组织为 8 个功能组（‘器官’）的系统，涵盖理论、艺术、商业和治理。”
- 缺失前置条件：坏例子只有
npm install和npm start。好例子注明前置条件 Node.js 20+、npm 10+，提供验证命令，并说明打开 http://localhost:3000 应看到仪表盘。 - 假设上下文：坏例子“参见治理规则了解晋升约束。”好例子“参见 promotion-readiness-checklist 技能了解定义状态机的晋升约束。”
- 死胡同文档：坏例子 README 在安装说明后结束。好例子 README 包含“下一步”部分，列出 3-4 个具体后续步骤。