zoahdev / dsh-firstrun

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-firstrun

Or run standalone:

npx dsh-firstrun

CLI

dsh-firstrun [--json]

• Prints a check-by-check report with → next steps.
• Exit codes: 0 ready, 1 needs attention, 2 usage error.

npx dsh-firstrun
npx dsh-firstrun --json

In-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:integration

CI 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-firstrun

CLI

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:integration

CI 跑 dsh-plugin-doctor 预检、单元测试、打包集成（真实 quickstart 调用）、Windows 全新 profile 的 dsh web 启动冒烟。

许可证

MIT © 2026 zoahdev