狸想岛 · AI 实战学习社区

🎯 学实际测试开发者体验：不是审纸上谈兵的计划，而是打开浏览器自己去走一遍——用浏览工具导航文档、走 onboarding 流、计时 TTHW（TTHW：上手时间指标）、截图错误信息——然后给出有证据的 DX 评分。 ⏱️ 预计时间：35 分钟

[!quote]- 📖 原Skill精要 技能名称：devex-review 核心功能：活网站开发者体验审计。使用浏览工具实际测试开发者体验：导航文档、走 onboarding 流程、计时 TTHW、截图错误信息、评估 CLI 帮助文本。产出带证据的 DX 评分卡。与 [[L6-06-开发者体验评审|plan-devex-review]] 形成回旋镖（计划说 3 分钟，现实说 8 分钟）。 所属体系：gstack 虚拟工程团队 协作关系：建议在发布面向开发者的功能后运行

1. 课程概览

💡 白话小课堂：devex-review 和 plan-devex-review 的关系就像"菜单上的照片"和"实际端上来的菜"。plan-devex-review 读计划文档说"TTHW 应该 < 5 分钟"，devex-review 打开浏览器真的去走一遍——计时、截图、记录每一步的摩擦点，然后拿出一份"回旋镖对比表"：你计划的是 3 分钟吗？我实测 8 分钟——多出来的 5 分钟全花在找 API key 上了。这不止是一份审计报告，这面"镜子"让你的团队看到"我们以为的开发者体验"和"开发者实际感受到的体验"之间的鸿沟。

2. 纸上 DX vs 实际 DX

Plan vs Reality

plan-devex-review（L6-06）： → 从计划文档中评审 API 设计、CLI 界面的"意图" → 假设：文档写得对，快速入门真的只需 3 分钟

devex-review（本课）： → 打开浏览器，真的去走一遍 → 计时、截图、记录每一步的摩擦点 → "你说 3 分钟——我实测 8 分钟，多出来的 5 分钟全花在找 API key 上了"

回旋镖比较（Boomerang）： → 如果存在 prior /plan-devex-review 评分 → 展示对比表 → plan 得分 vs live 得分 → 差异 > 2 分 = ⚠️ 警报 → TTHW：计划说的是 N 分钟，现实是 M 分钟 → 这对用户意味着什么？

3. DX 第一性原理

devex-review 的所有建议都追溯到这八个原则：

DX First Principles

T0 零摩擦。前五分钟决定一切。一键开始。不看文档就能 hello world。不需要信用卡。不需要 demo 预约。
渐进步骤。绝不强迫开发者在理解整个系统之前就无法从一个部分获得价值。温和坡道，不是悬崖。
边做边学。Playground、沙盒、能在上下文中工作的复制粘贴代码。参考文档是必要的，但永远不够。
替我决定，允许我覆盖。有主见的默认值是功能。逃生舱口是需求。强观点，弱持有。
对抗不确定性。开发者需要知道：下一步做什么？它成功了吗？如果没成功，怎么修？每个错误 = 问题 + 原因 + 修复。
在上下文中展示代码。Hello world 是谎言。展示真实的认证、真实的错误处理、真实的部署。解决 100% 的问题。
速度是功能。迭代速度就是一切。响应时间、构建时间、完成一个任务的代码行数、需要学习的概念数。
创造魔法时刻。什么会让人感觉像魔法？Stripe 的即时 API 响应。 Vercel 的 Push 即部署。找到你的魔法时刻，让它成为开发者体验的第一件事。

🔑 核心秘诀：DX 第一性原理的第 8 条"创造魔法时刻"是最容易被忽视的。

4. 八步审计流程

Step 0: 目标发现

→ 从 CLAUDE.md、README.md、package.json 自动提取 URL → 缺失时询问用户 → 检查是否有之前的 plan-devex-review 评分（回旋镖基线）

Step 1: 快速入门审计

→ 用浏览工具导航到文档/着陆页 → 截图 → 记录每一步： Step 1: [开发者做了什么] Time: [实际] Friction: [低/中/高] → TTHW 基准（Time to Hello World）：

< 2 min → 冠军级，3-4x 更高的采纳率
2-5 min → 有竞争力，基线
5-10 min → 需要改善，显著流失
10 min → 红旗，50-70% 放弃

Step 2: API/CLI/SDK 人体工学

→ CLI: 运行 --help → 评估输出质量、标志设计、可发现性 → API playground: 如果可以浏览器访问 → 导航并截图 → 命名一致性：整个 API 表面的 createX/deleteX/listX 模式？

Step 3: 错误消息审计

→ 触发常见错误场景：

浏览器：导航到 404、提交无效表单、尝试未认证访问
CLI：缺参数、无效标志、错误输入 → 每个错误截图 → 对 Elm/Rust/Stripe 三级模型评分：
指出问题 + 解释原因 + 展示修复 = 满分
只指出问题 = 及格
返回堆栈跟踪 = 不及格

Step 4: 文档审计

→ 导航文档结构 → 测试搜索（3 个常见查询） → 验证代码示例是否 copy-paste 完整 → 检查语言切换器行为 → 信息架构：2 分钟内能找到需要的东西吗？

Step 5: 升级路径审计

→ 读取 CHANGELOG 质量（清晰？面向用户？有迁移说明？） → 迁移指南（存在？一步步？） → 代码中的弃用警告

Step 6: 开发环境审计

→ README 的设置指引（步骤？前置条件？平台覆盖？） → CI/CD 配置（存在？有文档？） → TypeScript 类型（如果适用） → 测试工具/夹具

Step 7: 社区与生态审计

→ 社区链接（GitHub Discussions, Discord, Stack Overflow） → GitHub issues（响应时间、模板、标签） → 贡献指南

Step 8: DX 衡量审计

→ 反馈机制：Bug 报告模板、NPS、文档分析

5. 证据驱动评分

评分体系（0-10）

分数	含义
9-10	世界级。Stripe/Vercel 级别。开发者为之狂热。
7-8	好。开发者可以无挫败感地使用。有小差距。
5-6	可接受。能用但有摩擦。开发者忍受。
3-4	差。开发者抱怨。采纳受损。
1-2	坏了。开发者首次尝试后放弃。
0	没有考虑。对这个维度没有任何投入。

证据来源标注

→ TESTED：用浏览工具实际测试（截图证据） → PARTIAL：部分可测（如 CLI --help 可测，但本地安装不可测） → INFERRED：从源码文件中推断（如 CHANGELOG、README）

差距方法

→ 对于每个评分，解释"这个产品的 10 分长什么样" → 然后指出当前距离 10 的差距 → 不是"你很差"，而是"这是最好的样子，这是你现在的样子，这是差距"

6. DX 记分卡与回旋镖

DX 记分卡

维度	得分	证据	方法
快速入门	__/10	[截图]	TESTED
API/CLI/SDK	__/10	[截图/CLI输出]	PARTIAL
错误消息	__/10	[截图]	PARTIAL
文档	__/10	[截图]	TESTED
升级路径	__/10	[文件引用]	INFERRED
开发环境	__/10	[文件引用]	INFERRED
社区	__/10	[截图]	TESTED
DX 衡量	__/10	[文件引用]	INFERRED

回旋镖对比（如果存在之前的 plan-devex-review）

维度	Plan 得分	Live 得分	差值	警报
快速入门	__/10	__/10	__	⚠/✓
...	...	...	...	...
TTHW	__ min	__ min	__ min	⚠/✓

→ 任何 live 得分 < plan 得分 - 2 的维度标记为 ⚠️ 警报 → 现实比计划差的维度是最值得投入的改进方向

7. 浏览器能测什么、不能测什么

Browse Tool 能做到的

✅ 文档页面 ✅ API playground / 在线沙盒 ✅ Web 控制台 ✅ 注册流 ✅ 交互式教程 ✅ 错误页面 ✅ 社区论坛 ✅ CLI --help 输出（通过 bash）

Browse Tool 做不到的

❌ CLI 安装摩擦 ❌ 终端输出质量 ❌ 本地环境设置 ❌ 邮件验证流 ❌ 需要真实凭据的认证 ❌ 离线行为 ❌ 构建时间 ❌ IDE 集成

处理不可测维度

→ 用 bash 读取文件（CHANGELOG、README、package.json） → 标记为 INFERRED from artifacts → 绝不猜测 → 每个评分都注明证据来源

8. 结构拆解：开发者体验审计 Skill 模板

活网站 DX 审计型 Skill 模板

核心特征

→ 管理对象 = 面向开发者的产品的实际使用体验（非计划文档，是活网站/CLI） → 核心原则 = 证据驱动（截图+计时+实测）+ 回旋镖对比（Plan vs Live）+ Gap 方法（通往 10 分的差距） → 关键设计 = 八步审计流程、DX 第一性原理（8 条）、TTHW 基线评级、三级错误评分模型

通用结构

Target Discovery（目标发现）

自动提取 URL（CLAUDE.md / README / package.json）
检查 prior plan-devex-review 评分（回旋镖基线）

Live Audit Pipeline（八步审计管道）

Step 1: 快速入门审计 → TTHW 计时（<2min 冠军 / >10min 红旗）
Step 2: API/CLI/SDK 人体工学 → 命名一致性、标志设计、可发现性
Step 3: 错误消息审计 → Elm/Rust/Stripe 三级模型评分
Step 4: 文档审计 → 搜索、代码示例完整性、信息架构
Step 5-8: 升级路径 / 开发环境 / 社区 / DX 衡量

Evidence-Driven Scoring（证据驱动评分）

评分 0-10 + 证据来源标注（TESTED / PARTIAL / INFERRED）
Gap 方法："产品的 10 分长什么样 → 你现在的样子 → 差距"
回旋镖对比表（Plan vs Live）→ 差异 > 2 分 = 警报

Browser Capability Boundary（浏览器能力边界）

可测：文档页面、API playground、注册流、错误页面、CLI --help
不可测：CLI 安装摩擦、终端输出、本地环境、构建时间
不可测维度 → INFERRED from artifacts → 绝不猜测

9. 电商 Skill 案例：活网站 DX 审计——电商开放平台文档

🛒 实战案例：某电商开放平台上线了面向ISV的API文档站（含REST API参考、SDK指南、Webhook说明），plan-devex-review从设计文档上看评分6.5/10（可接受）。用devex-review实际走一遍后发现：Plan评分与Live体验差距巨大，回旋镖警报触发。

TTHW实测计时：[00:00]打开docs.shop-api.example.com→首页Logo+"欢迎来到Shop API v3"+3个文档链接，Friction低。
[00:45]点击"快速入门"→4步教程（注册→获取Key→npm install→创建商品），Friction低。
[02:30]致命摩擦：步骤1"注册账号"→跳转商家后台，注册表单12个字段含营业执照上传和法人身份证照片——开发者只想试用API，不需要上线开店！
[08:30]表单终于填完→提示"审核1-3个工作日"。TTHW=∞（无法在当天完成Hello World）。预计50-70%的开发者在此流失。Plan评分<5分钟，Live实测>1工作日，回旋镖落差>2分。

API人体工学审计：curl GET /v3/products -H "Authorization: Bearer $SANDBOX_KEY"→返回{"error":"unauthorized"}。指出问题？是。解释原因？否（没说Key格式不对还是权限不足）。展示修复？否。对比Stripe同类错误响应——{"error":{"type":"invalid_request_error","message":"...","doc_url":"https://stripe.com/docs/error-codes"}}——问题+原因+文档链接，满分。该平台评分：FAIL。

错误消息审计：测试3个场景——(1)404端点GET /v3/produts（拼写错误）→返回404空JSON{}，未提示正确端点/v3/products；(2)空body的POST /v3/products→返回{"error":"validation_error"}未指明哪个字段、什么错误、正确格式；(3)无API Key访问GET /v3/orders→返回Nginx默认HTML 401页面而非JSON——API返回HTML是低级错误。3/3 FAIL。

文档审计：搜索"创建商品"→0结果（文档用英文create product但首页是中文界面，中英混杂导致索引断裂）。搜索"webhook"→3条结果全是概念介绍，无事件列表、无payload示例、无签名验证说明。搜索"错误码"→1条结果"请参考HTTP状态码标准"——没有自定义错误码文档，开发者收到error_code:30012时完全不知道是什么意思。

STOP综合评分：Setup 1/10（审核3天）→Task 4/10（有示例但不能用）→Ongoing 5/10（API可用但每次查文档）→Pain 1/10（错误信息不可解）。总评分2.75/10（Plan评分的6.5/10是虚假的55%溢价）。

🔑 启示：DX审计的"回旋镖比较"才是真相——Plan评审是从文档/设计推测体验（乐观偏误），Live审计是用真实的浏览器和curl走一遍（现实检验）。Plan说<5分钟，Live说1.5天——落差不是优化空间，是信任裂缝。

DX 记分卡与回旋镖

| 维度       | Plan 得分 | Live 得分 | 差值  | 警报 |
|-----------|----------|----------|-------|------|
| 快速入门   | 7/10     | 1/10     | -6    | ⚠️⚠️⚠️ |
| API/CLI   | 6/10     | 3/10     | -3    | ⚠️ |
| 错误消息   | 7/10     | 2/10     | -5    | ⚠️⚠️ |
| 文档      | 6/10     | 4/10     | -2    | ⚠️ |
| 升级路径   | N/A      | N/A      | N/A   | - |
| 开发环境   | 5/10     | 5/10     | 0     | ✓ |
| 社区      | N/A      | N/A      | N/A   | - |
| DX 衡量   | N/A      | N/A      | N/A   | - |

Live DX 综合评分：3/10 — 差 🚩
Plan vs Live 差异：计划比现实乐观了 3.5 分

改进优先级

P0（本周）：
  → 开放 Sandbox 环境（免注册、免审核、立即获取 Key）
    修复 TTHW：从 > 1 工作日 → < 3 分钟
  → JSON 格式的统一错误响应（含错误码 + 修复建议）

P1（下周）：
  → 文档搜索支持中英文
  → 每个 API 端点提供 curl 可运行的完整示例
  → 文档首页添加 3 分钟快速体验（用 Sandbox Key）

P2（下月）：
  → Webhook 事件文档 + payload 示例
  → 错误码完整文档
  → 交互式 API Explorer（浏览器内可直接调 API）


> ⚠️ **避坑指南**： 这个案例最刺痛的地方是回旋镖比较——plan 说"TTHW < 5 分钟"，实际是"无限长（要等审核）"。Planner 写了完美的快速入门流程，但忘了"第一步是注册审核"这个现实。

***

## 10. 掌握检验

**Q1**：devex-review 中 TTHW 的"红旗"标准是什么？
- A) 5-10 分钟
- B) 2-5 分钟
- C) > 10 分钟
- D) < 2 分钟

**Q2**：错误消息的"三级模型"要求每个错误消息至少具备哪三个要素才算满分？
- A) HTTP 状态码 + 时间戳 + 请求 ID
- B) 指出问题 + 解释原因 + 展示修复
- C) 错误类型 + 堆栈跟踪 + 行号
- D) 友好文案 + emoji + 客服链接

**Q3**：回旋镖比较中，"任何 live 得分 < plan 得分 - 2 的维度标记为警报"——阈值为什么是 2 分而不是 1 分或 3 分？请分析这个阈值设计反映了什么方法论。

**Q4**：在电商 API 案例中，回旋镖比较发现快速入门维度的 Plan 得分（7/10）vs Live 得分（1/10）差距巨大。请用 DX 第一性原理的框架，找出至少 3 条被违反的原则，并各用一句话解释。

**Q5**："浏览器能测什么、不能测什么"的边界中，如果某个维度被标记为 INFERRED from artifacts，这类证据的可靠性如何？在什么情况下 INFERRED 证据会给出完全错误的结论？请举例。

**Q6**：Gap 方法（"你的 10 分长什么样 → 你现在的样子 → 差距"）vs 传统评分（直接给 3/10）。从开发者心理和团队沟通两个角度，为什么 Gap 方法更有建设性？

***

## 11. 答案

<details>
<summary>点击查看答案</summary>

**Q1**：**C** —— > 10 分钟是"红旗"，预计 50-70% 的开发者会在此放弃。

**Q2**：**B** —— 指出问题 + 解释原因 + 展示修复。

**Q3**：2 分不是随意选的——1 分差距可能是正常的测试方差（Plan 评估时乐观了一点点但方向一致），3 分差距则说明方向错了（太少被捕获为问题）。2 分刚好是"明显超出了评估偏差但仍然有可能是系统性偏差"的阈值——它捕捉的是"Plan 和 Live 有实质性差异"而不仅仅是"Plan 稍微乐观了些"。2 分的阈值既不过敏（不对每个小偏差拉警报），也不迟钝（能在真正有问题时立刻捕捉）。

**Q4**：至少 3 条被违反的原则：①T0 零摩擦——"前五分钟决定一切"，但注册审核需要 1-3 个工作日，开发者在决定是否使用之前就已经断开了；②边做边学——"Playground、沙盒、能复制粘贴的代码"，但案例中没有任何沙盒环境，开发者必须先通过完整注册流程；③对抗不确定性——"每个错误 = 问题 + 原因 + 修复"，但案例中的错误消息只返回了状态码或空 JSON，开发者不知道自己错在哪。

**Q5**：INFERRED 从源文件推断的可靠性中等——它取决于文件质量和实际情况。例如：从 package.json 推断依赖项管理，但 package.json 中的脚本可能已经过时（"npm start" 指向 2 年前就废弃的命令）；从 README 推断设置指引，但 README 可能没被更新。最危险的错误结论：INFERRED 给出开发环境 8/10 因为"README 写得很好"，但实际新开发者在本地跑不起来因为缺少关键的 .env 文件生成脚本——INFERRED 只能见"文档的承诺"，见不到"实际的体验"。

**Q6**：开发者心理角度——"3/10"是一个终审判决，暗示"你不值得更好的分"。开发者本能防御。而"你的 10 分长这样（Stripe 级别的错误消息），你现在的样子是这样，差距在这里"是一个邀请——不是评判你是 3 分，而是刺激你"我怎样才能从 3 分变 10 分"。团队沟通角度——"3/10"会被当作一个"评价"来争吵（"我们真的有这么差吗？"），而 Gap 方法把对话重心从"你现在多差"转移到"你如何变好"——这是一个建设性对话而非防御式争论。

（5/6 通过）
</details>

***

## 延伸阅读
- [[L6-12-设计稿转代码|设计稿转代码 —— 把设计图变成能直接用的网页代码]]
- [[L6-06-开发者体验评审|开发者体验评审 —— 让你的API和工具好用到让人上瘾]]
- [[L6-14-设计系统哲学|设计系统哲学 —— 理解为什么"好看"不是拍脑袋决定的]]

L6-13：活网站开发者体验审计 —— 像用户一样体验你自己的API