Document UX Review

这个 skill 的目标不是“读一遍 README 然后提几点意见”，而是把自己当成第一次接触该项目的用户，在尽量真实的环境里按文档一步一步操作，尽可能覆盖文档里面的每一个环节，找出真正会阻塞上手的问题，并给出可落地的改进建议。

适用范围

• 输入通常是一个 Git 仓库链接，也可以是本地仓库路径。
• 默认审查范围是：README + README 直接指向的安装、快速开始、运行相关文档。
• 如果 README 把关键步骤跳转到 docs/、脚本、示例目录或其他 Markdown 文件，要继续跟进这些直接依赖的文档。
• 不要无边界地通读所有文档；保持“为了完成 README 指导流程而必须阅读什么，就读什么”的范围感。

开始前先确认执行边界

在真正执行前，先尽量确认下面这些信息，避免把环境问题误判成文档问题，也避免重复安装用户已经具备的基础组件：

• 操作系统、Shell、CPU 架构。
• 是否有 GPU / NPU 等加速环境，以及哪些基础环境已经安装好，例如 CUDA、CANN、编译器、Docker。
• 用户是否希望跳过已经具备的基础组件安装，只体验剩余文档流程。
• 是否允许使用 Docker、uv、Python venv、conda、本地 Node 版本管理等隔离手段。
• 是否有网络、权限、代理、公司内网、磁盘空间、端口占用等限制。
• 是否允许登录外部服务、填写密钥、访问云资源。

如果用户没有给足信息：

• 明确写出你的环境假设后继续。
• 把“由于环境信息缺失导致的风险”单独记在报告里。

如果用户明确说某些基础环境已经 OK：

• 不要重复安装。
• 先验证这些环境是否真的可用，再从文档的下一步开始体验。
• 报告中写明“基于用户声明跳过了哪些步骤”。
• 如果当前宿主环境与文档目标环境明显不匹配，而用户又允许 Docker 或其他隔离方案，优先切到更接近文档目标的平台继续体验，并把这件事记为“执行偏差”。例如：宿主机是 macOS，但文档明确面向 Linux 安装环境，此时优先考虑 Docker Linux 容器，而不是硬在宿主机上猜测修补。

环境安全原则

尽量不要污染宿主环境，也不要影响其他用户：

• 优先使用隔离方案，例如 Docker、uv、Python venv、conda、本地项目依赖、临时目录。
• 除非文档明确要求且用户接受，否则不要修改全局配置、系统级包、共享目录或用户已有环境。
• 如果文档只能通过全局安装或高风险步骤完成，先记录这一点；必要时暂停并向用户说明风险。
• 不要静默替用户修文档。任何为了安全、隔离或兼容性做出的偏离，都要在报告中明确记录为“执行偏差”。
• 当有多种隔离方案时，优先选择既贴近文档目标环境、又副作用最小的方案；不要只是因为自己熟悉某个工具就随意换一条执行路线。

执行原则

1. 严格按文档走

• 按 README 的顺序执行，再跟随 README 直接引用的关键文档继续执行。
• 尽量原样执行文档中的命令、路径、环境变量和步骤顺序。
• 不要在心里自动补齐缺失步骤后假装“可以跑通”。如果你需要推断、搜索额外资料或修正命令，说明文档本身已经存在问题。
• 每一步都要记录“文档依据”，至少包含：文档路径、章节标题或小节名、原始命令或关键原文摘录中的一项。不要只写“根据 README”这种模糊说法。

2. 以新手视角审查

把自己当成第一次接触项目的人，重点关注：

• 先决条件是否说清楚了。
• 命令是否可以直接复制执行。
• 变量名、路径名、占位符、分支名、镜像名是否解释清楚。
• 成功执行后的预期输出是否写明。
• 失败时是否给出排查方向。
• 是否默认读者知道某些上下文，但文档并没有明确写出。

3. 实际验证到“能启动”或“被文档阻塞”为止

• 文档如果要求安装依赖、生成配置、启动服务、运行 demo，就尽量真实做到这些步骤。
• 如果项目能成功启动，记录“按文档走通”的证据，例如启动日志、访问结果、测试命令输出。
• 如果被阻塞，不要硬绕过去把结果做成“已完成”；要准确记录阻塞点、前置条件缺失点和可能的文档缺陷。

4. 允许停止的情况

遇到下面情况时，可以停止继续执行该分支，并把它记为报告中的阻塞项：

• 需要真实账号、密钥、验证码、付费资源或公司内部网络。
• 需要高风险系统改动、root 权限、破坏性命令。
• 需要文档未声明但实际必需的特殊硬件或外部依赖。
• 运行代价过高，明显超出“文档上手验证”范畴，例如长时间训练任务。

停止时要写清楚：

• 停在第几步。
• 文档当时如何描述。
• 真实阻塞是什么。
• 这是环境限制，还是文档没有提前说明。

审查清单

至少从以下维度检查：

易用性

• 新人是否知道从哪里开始。
• 步骤顺序是否自然，是否能无歧义地跟随。
• 命令是否能直接复制，是否需要用户猜测路径、版本、变量值。
• 是否有适合不同环境的分支指引，例如 macOS / Linux / Windows，CPU / GPU，Docker / 非 Docker。

正确性

• 命令、包名、路径、文件名、环境变量名是否正确。
• 安装和运行步骤是否完整，是否存在漏步骤、顺序错误、依赖遗漏。
• 文档承诺的结果是否真的能出现。
• 版本要求是否与项目当前状态一致。

可读性

• 术语是否解释清楚。
• 段落、标题、代码块是否组织合理。
• 占位符是否明确，例如 <your-path>、<model-name> 这类值从哪里来。
• 成功结果、失败结果、注意事项是否容易扫读。
• 小白用户是否容易理解“当前做到哪一步、为什么成功/失败、下一步该做什么”。

完整性

• 是否说明前置环境、依赖版本、系统要求、权限要求、网络要求。
• 是否给出初始化数据、配置文件、示例输入、示例输出。
• 是否包含验证步骤，而不仅是安装命令。
• 是否说明常见错误和排查方式。

环境友好性与最佳实践

• 是否鼓励使用隔离环境，避免污染系统。
• 是否避免默认要求全局安装、全局改 PATH、修改共享配置。
• 是否提供最小可行验证路径，而不是让用户先做大量不可逆配置。
• 是否在必要处解释“为什么要这样做”，帮助新手建立心智模型。

开源项目关键章节与行业实践

除了检查“能不能跑通”，还要看这份文档是否具备成熟开源项目常见的关键内容。至少检查以下项目是明确、缺失，还是只部分具备：

• 支持平台 / 兼容矩阵。
• 前置环境要求和版本要求。
• 安装指南。
• 快速开始 / 最小可运行验证路径。
• 配置说明和占位符解释。
• 故障排查 / FAQ。
• 小白用户上手指引，例如成功标志、失败后的下一步。
• 安全、隔离环境或共享环境使用建议。
• 如果只有通过阅读源码、脚本、CI 配置、Dockerfile、Makefile 或测试用例，才能推断出安装、启动、验证或配置方法，要明确记为“文档完整性”问题；不要因为你最终靠读代码跑通了，就把它算作文档可用。

如果这些章节不是严格以单独标题存在，也要从内容层面判断有没有被覆盖，而不是只看目录名。

证据记录要求

每发现一个问题，都尽量给出精确证据：

• 文档位置：例如 README.md:42、docs/install.md:18；如果拿不到精确行号，至少写章节标题。
• 原文依据：尽量补一小段原始命令、占位符或关键原文摘录，帮助读者快速对照。
• 实际执行的命令。
• 真实输出或错误摘要。
• 这是原样执行失败，还是为了安全 / 兼容性做了偏离。
• 是否为了继续执行而额外读取了源码、脚本、配置或 CI 文件；如果读取了，这些信息本应由哪份文档提供。
• 对新手会造成什么影响。

不要只写笼统判断，例如“文档不太清楚”“命令似乎有问题”。要尽量把问题压缩成可复现、可修改、可验证的条目。

严重程度定义

• 阻塞：新人按照文档无法继续，或者核心流程完全跑不通。
• 高：需要明显的额外知识、试错或人工修正才能继续，严重影响上手效率。
• 中：不会立即卡死，但容易误导、浪费时间或导致理解偏差。
• 低：表述、排版、示例质量等优化项，不影响主流程完成。

工作流程

1. 准备工作区

• 优先在临时目录操作，不要污染用户已有仓库。
• 克隆或进入目标仓库后，先定位默认分支和当前 README。
• 建立一份简短的执行计划：你准备按哪些文档走、准备采用什么隔离方式、哪些步骤可能受环境限制。

2. 梳理文档执行路径

• 先读 README。
• 识别其中的先决条件、安装步骤、配置步骤、启动步骤、验证步骤。
• 追踪 README 直接引用的关键文档，并整理成执行顺序。
• 如果必须去读源码、脚本、Makefile、CI 或 Dockerfile 才能知道下一步怎么做，可以读取以帮助定位问题，但必须把这类“文档外补全”单独记录为完整性缺陷，而不是把它当作文档已覆盖。

3. 逐步执行并记录

• 每做一步，都记录文档说了什么、你实际做了什么、结果是什么。
• 对“命令不完整”“文档默认某组件已安装”“成功标准没写”的情况立即记问题，不要等最后再回忆。
• 某一步如果成功，也要写明成功依据，让读者能看懂整条流程里哪些节点是 OK 的，而不只是看到失败项。

4. 做最佳实践对照

• 在体验完成或被阻塞后，再回头从最佳实践角度补一轮审查。
• 特别关注：环境隔离、前置条件透明度、平台分支清晰度、成功验证路径、故障排查说明。

5. 输出标准化报告并渲染 HTML

最终报告默认使用中文，必要时保留原始命令和报错英文。除非用户另有要求，否则先整理成下面的标准化报告结构，再将其渲染为最终 HTML 报告交付给用户。这个 Markdown 结构是中间标准形态，最终交付物应是 HTML，而不是只停留在 Markdown 文本。如果最终报告会产出多个 HTML 页面，必须放进同一个独立文件夹中交付；不要把散落的 HTML 文件直接丢在工作区根目录。

报告格式

严格按这个结构组织，允许在每节内增删少量子项，但不要漏掉核心信息：

# 文档体验审查报告

## 1. 审查对象
- 仓库：
- 审查范围：README + 直接关联文档
- 审查时间：
- 评审分支：
- 评审提交：
- 体验环境：
- 用户声明的已具备环境：
- 采用的隔离策略：

## 2. 总体评分与结论
- 总体评分：`XX/100`
- 评分拆解：正确性 / 易用性 / 可读性 / 完整性 / 环境友好性
- 是否按文档走通：完全走通 / 部分走通 / 未走通
- 结论基线：`<评审分支> @ <评审提交>`
- 总体评价：
- 主要风险：

## 3. 体验流程图
| 步骤 | 文档依据 | 预期动作 | 状态 | 现象 / 结果 | 阻塞原因或成功依据 | 严重程度 |
| --- | --- | --- | --- | --- | --- | --- |

状态建议使用：`OK` / `偏差继续` / `阻塞` / `未执行`

## 4. 执行过程摘要
| 阶段 | 文档依据 | 实际执行 | 结果 | 备注 |
| --- | --- | --- | --- | --- |

## 5. 关键问题概览
| ID | 严重程度 | 分类 | 文档位置 | 问题简述 |
| --- | --- | --- | --- | --- |

## 6. 详细问题

### ISSUE-01 标题
- 严重程度：
- 分类：易用性 / 正确性 / 可读性 / 完整性 / 最佳实践
- 文档位置：
- 文档原文 / 摘录：尽量贴出短摘录、命令片段或占位符原文，帮助读者快速对应原始文档
- 复现上下文：
- 实际现象：
- 影响分析：说明为什么这会让新手卡住、误解或高成本试错
- 修改建议：给出可直接落地的写法、补充步骤或结构调整建议

## 7. 新手友好度观察
- 从小白视角总结：这份文档哪些地方容易迷路、需要猜测、缺少成功/失败判定，哪些地方做得相对友好。
- 文档是否齐全，是否有明显的漏步骤、错步骤，是否有不合理的前置条件假设。
- 如果要靠阅读源码、脚本、CI、Dockerfile、Makefile 或 issue 才能理解如何继续，这本身就是文档完整性问题，要明确写出缺失的文档信息，而不是把“靠自己读代码补齐”视为走通。

## 8. 正向观察
- 写出文档做得好的地方，帮助用户区分“保留什么”和“该改什么”。

## 9. 优先修复建议
1. 先修复阻塞主流程的问题。
2. 再补齐前置条件和验证步骤。
3. 最后优化可读性和最佳实践提示。

## 10. 附录
- 执行中使用的关键命令：
- 关键报错摘要：
- 执行偏差说明：
- 因环境限制未继续的步骤：

评分说明

• 90-100：新手基本可照文档直接走通，只有轻微优化项。
• 75-89：主流程大体可用，但存在明显的可读性、环境说明或排障短板。
• 60-74：需要较多人工判断或额外知识才能走通，体验一般。
• 40-59：文档存在明显阻塞、缺步骤或平台/依赖信息不清，普通用户很难顺利完成。
• 0-39：主流程无法照文档执行，关键路径严重失真或缺失。

输出要求

• 最终交付物应是 HTML 报告，并放在一个独立文件夹中。单场景可以只有 1 个 HTML，也可以是总览 HTML + 详情 HTML；多场景应输出一个总览 HTML 加场景详情 HTML。无论哪种情况，所有 HTML 文件都应位于同一个报告目录。
• 如果你在本地工作区生成了报告文件，也要在回复中说明文件路径。
• 结论必须基于真实执行证据或明确说明的假设，不要把猜测写成事实。
• 如果没有发现明显问题，也要说明你实际检查了哪些步骤、哪些文档、哪些运行结果。
• 报告开头必须给出一个 100 分制总体评分，并说明评分依据。
• 总体结论必须明确写出本次结论对应的评审分支和 commit id，不要只把这些信息埋在附录、文件名或执行日志里。
• 报告必须给出完整的体验流程图或流程表，明确哪一步 OK、哪一步阻塞、阻塞现象是什么、原因是什么、严重程度是什么。
• 对每个关键步骤和问题，优先给“文档依据 + 原文摘录 + 实际现象”的组合，而不只是给行号范围。
• 最终 HTML 报告的 UI 风格、配色、信息层级、卡片 / 标签 / 时间线 / 表格样式应与 scripts/render_report_html.py 定义的样式保持一致；不要自行换成另一套视觉语言。
• 最终 HTML 应该是报告本身，而不是带翻页、反馈按钮或 benchmark 的 review 界面。
• 如果需要把标准化 Markdown 报告转成最终 HTML，应优先使用 bundled script：scripts/render_report_html.py，并以该脚本生成的样式和结构为准。

禁止事项

• 不要把你私下修复过的问题伪装成“文档原本就可用”。
• 不要为了跑通而偷偷跳过关键步骤，却在结论里写成“可正常使用”。
• 不要默认用户愿意接受全局安装、root 权限、系统污染或共享环境修改。
• 不要只给抽象建议，必须给出具体位置和可执行改法。