dsh-firstrun
First-run health check for DeepSeek Harness (dsh): one command that tells a new user what's missing and what to run next.
It verifies the pieces that trip up every first-hour user — Node.js, pnpm, dsh CLI, home directory, dsh profile, API key (names only, never values), workspace writability, npm registry — and prints actionable next steps. Zero runtime dependencies, read-only.
Install
dsh plugin add dsh-firstrunOr run standalone:
npx dsh-firstrunCLI
dsh-firstrun [--json]- Prints a check-by-check report with
→next steps. - Exit codes:
0ready,1needs attention,2usage error.
npx dsh-firstrun
npx dsh-firstrun --jsonIn-harness usage (agent-callable)
Ask your dsh agent:
帮我体检一下环境，看看还缺什么。
Run a first-run health check: quickstart.The tool returns a dsh-firstrun/v1 report:
{
"schema": "dsh-firstrun/v1",
"ok": false,
"summary": { "total": 8, "pass": 5, "warn": 1, "fail": 2 },
"checks": [
{ "id": "node", "name": "Node.js installed", "status": "pass", "detail": "v24.19.0", "nextStep": null },
{ "id": "api-key", "name": "API key configured", "status": "fail", "detail": "None of DEEPSEEK_API_KEY, OPENAI_API_KEY is set", "nextStep": "Store an API key: export DEEPSEEK_API_KEY=... or use the Web Models page" }
],
"generatedAt": "2026-08-18T00:00:00Z"
}Checks
| Check | Verifies | Status when missing |
|---|---|---|
node | Node.js on PATH | fail |
pnpm | pnpm on PATH | fail |
dsh | dsh CLI on PATH | fail |
home | HOME / USERPROFILE set | fail |
profile | DSH_HOME or ~/.dsh exists | warn |
api-key | one of the API key env vars is set (values never shown) | fail |
workspace | current directory is writable | warn |
registry | npm registry config resolves | warn |
Why it exists
- The official repo's first-hour failures are overwhelmingly setup friction (missing toolchain, missing key, network); most users don't know what to check first.
- Existing tools diagnose plugin health (dsh-plugin-doctor) and network (dsh-cn-boot); this one closes the loop with a single user-facing checklist + next steps.
- Zero runtime dependencies, read-only, values never printed.
Development
pnpm install
pnpm typecheck
pnpm build
pnpm test
pnpm test:integrationCI runs the dsh-plugin-doctor preflight, unit tests, packed-artifact integration (real quickstart invocation), and a fresh-profile dsh web boot smoke on Windows.
License
MIT © 2026 zoahdev
dsh-firstrun（中文）
DeepSeek Harness（dsh）的首次运行体检：一条命令告诉新用户“缺什么、下一步跑什么”。
它检查每个新手第一小时都会踩的点——Node.js、pnpm、dsh CLI、home 目录、dsh profile、API Key（只显示变量名，绝不显示值）、工作区可写性、npm 注册表——并给出可执行的下一步。零运行时依赖、只读。
安装
dsh plugin add dsh-firstrun独立使用：
npx dsh-firstrunCLI
dsh-firstrun [--json]- 输出逐项检查报告，带
→下一步建议。 - 退出码：
0就绪，1需要处理，2用法错误。
npx dsh-firstrun
npx dsh-firstrun --json在 harness 内使用（agent 可调用）
对 agent 说：
帮我体检一下环境，看看还缺什么。
工具返回 dsh-firstrun/v1 报告（结构见英文版 JSON 示例）。
检查项
| 检查 | 验证内容 | 缺失时状态 |
|---|---|---|
node | Node.js 在 PATH | fail |
pnpm | pnpm 在 PATH | fail |
dsh | dsh CLI 在 PATH | fail |
home | HOME / USERPROFILE 已设置 | fail |
profile | DSH_HOME 或 ~/.dsh 存在 | warn |
api-key | 任一 API Key 环境变量已设置（绝不显示值） | fail |
workspace | 当前目录可写 | warn |
registry | npm 注册表配置可解析 | warn |
为什么需要它
- 官方仓库第一小时的失败绝大多数是环境摩擦（缺工具链、缺 Key、网络问题），多数用户不知道先查什么。
- 现有工具管插件健康（dsh-plugin-doctor）和网络（dsh-cn-boot）；本插件用一份面向用户的清单 + 下一步建议闭环。
- 零运行时依赖、只读、绝不输出值。
开发
pnpm install
pnpm typecheck
pnpm build
pnpm test
pnpm test:integrationCI 跑 dsh-plugin-doctor 预检、单元测试、打包集成（真实 quickstart 调用）、Windows 全新 profile 的 dsh web 启动冒烟。
许可证
MIT © 2026 zoahdev
Related ecosystem tools
- dsh-dep-audit - dependency supply-chain hygiene
- dsh-quality-score - plugin quality scorecard + full-registry leaderboard
- dsh-ecosystem - health scan, impact, trend, live dashboard
- dsh-tutorials - bilingual plugin pipeline tutorials
FAQ
- How do I install? dsh plugin add dsh-firstrun or run the CLI directly (see README).
- Does it need an API key? No.
- Is it read-only? Yes by default; any write/apply is an explicit flag.
