DSH VERTICAL KIT · 上手指南检查 / 新人文档检查
上手指南检查清单
它决定一件事:这份上手文档是否让一个新人今天就能开始。
检查规则
| 规则 | 判定 |
|---|---|
empty | 文档为空 → error |
prereq-missing | 没有前置要求段 → error |
command-missing | 没有含安装命令的代码块 → error(只能读的文档不是上手文档) |
success-missing | 没有「你应该看到」段 → error(分不清成功与静默失败) |
help-missing | 没有求助路径 → warn |
time-estimate-missing | 全文没有耗时 → warn(没写多久的文档会被收藏然后永不打开) |
用法
npx onboarding-check README.md --jsonnpx onboarding-check - < ONBOARDING.md
真实输入输出
输入
# 上手
这个项目挺好用的,大家可以看看。$ onboarding-check onb-sample.md
error prereq-missing 第0行 没有前置要求段(认得:## 前置要求、需要先装…、Prerequisites)——新人会卡在第 3 步才发现版本不对
error command-missing 第0行 没有可粘贴的命令代码块(认得:含 npm/pnpm/npx/pip/git clone/docker run 的 ``` 块)——没有命令的上手文档只能读,不能做
error success-missing 第0行 没有「成功长什么样」段(认得:## 你应该看到、成功后…、You should see)——没有预期输出的新人不知道自己是成功了还是静默失败了
warn help-missing 第0行 没有求助路径(认得:## 遇到问题、提 issue、ask in…)——失败时读者只有放弃这一个选项
warn time-estimate-missing 第0行 没有耗时估计(认得:约 5 分钟、15 分钟、under 10 minutes)——没写要花多久的文档不会被开始,读者无法判断值不值得现在做
fail: 0/0 blocks runnable, 3 errors, 2 warnings
出口码:1。输出为真实 CLI 运行的逐字结果,由测试与工具保持同步。
出口码:0 干净、1 有发现、2 用法或读文件错误。--json 输出机器可读结果。DSH 内同样的函数在 POST /onboarding-check/api({"text":"…"} 或 {"path":"…"}),面板与 CI 调同一实现。
这是清单,不是专业人士。合同检查不是法律意见,发票检查不判税务合规,listing 检查不判商业价值。每条发现都是文本里可判定的结构缺陷,带行号。
耗时形态:5 分钟、约 15 分钟、under 10 minutes、1 小时、半小时、30 mins。代码块按内容判断——只有含 npm/pnpm/npx/pip/brew/apt/cargo/go install/git clone/curl/docker run/make 的块才算命令块。只验文档形状,不验命令能否跑通:前置版本写错、这平台上要 sudo、「你应该看到」的输出两版前就过期了——这些要一台干净机器才能发现。 · dsh-vertical-kit · 通用检查(哈希/引用/结构/表格/数字)在 dsh-verify-kit