# External Mindstudio Document UX Review > 当用户希望你像第一次接触项目的人一样，真实按仓库的 README、安装文档或 quick start 跑一遍，并判断“新人能不能走通”“文档是否可用”“哪里会卡住”“安装/启动说明是否对新手友好”时，使用这个 skill。它适用于 repo onboarding audit、documentation UX review、quickstart validation、README walkthrough、按文档验证安装与运行并输出问题报告的场景；即使用户只是说“按 README 试一下”“帮我检查这个仓库文档能不能跑通”“看看 quick start 为什么带不动新人”，也应触发。不要用于纯翻译、润色、摘要、风格对比、治理项检查，或只想直接修环境/修单个报错而不做完整文档体验审查的请求。 - Skill: `ascend-ai-coding/external-mindstudio-document-ux-review` (Agent Skill, multi-file: 4 files) - Install (CLI): `npx skillmds@latest add ascend-ai-coding/external-mindstudio-document-ux-review` - Raw SKILL.md: https://api.skillmd.com/api/skills/ascend-ai-coding/external-mindstudio-document-ux-review/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Security - License: UNKNOWN - Author: ascend-ai-coding (https://skillmd.com/u/ascend-ai-coding) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/ascend-ai-coding/external-mindstudio-document-ux-review --- # 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。 ### 正确性 - 命令、包名、路径、文件名、环境变量名是否正确。 - 安装和运行步骤是否完整，是否存在漏步骤、顺序错误、依赖遗漏。 - 文档承诺的结果是否真的能出现。 - 版本要求是否与项目当前状态一致。 ### 可读性 - 术语是否解释清楚。 - 段落、标题、代码块是否组织合理。 - 占位符是否明确，例如 ``、`` 这类值从哪里来。 - 成功结果、失败结果、注意事项是否容易扫读。 - 小白用户是否容易理解“当前做到哪一步、为什么成功/失败、下一步该做什么”。 ### 完整性 - 是否说明前置环境、依赖版本、系统要求、权限要求、网络要求。 - 是否给出初始化数据、配置文件、示例输入、示例输出。 - 是否包含验证步骤，而不仅是安装命令。 - 是否说明常见错误和排查方式。 ### 环境友好性与最佳实践 - 是否鼓励使用隔离环境，避免污染系统。 - 是否避免默认要求全局安装、全局改 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 文件直接丢在工作区根目录。 ## 报告格式 严格按这个结构组织，允许在每节内增删少量子项，但不要漏掉核心信息： ```markdown # 文档体验审查报告 ## 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 权限、系统污染或共享环境修改。 - 不要只给抽象建议，必须给出具体位置和可执行改法。