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 --json
npx 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