zoahdev/dsh-firstrun

dsh-firstrun

npm

CI
License: MIT
dsh-plugin

DeepSeek Harness (dsh) 的首次运行健康检查：一条命令即可告诉新用户缺少什么以及接下来该运行什么。

它会验证每个新手在第一小时都会遇到问题的环节——Node.js、pnpm、dsh CLI、主目录、dsh 配置文件、API 密钥（仅名称，绝不显示值）、工作区可写性、npm registry——并打印可操作的后续步骤。零运行时依赖，只读。

安装

dsh plugin add dsh-firstrun

或独立运行：

npx dsh-firstrun

CLI

dsh-firstrun [--json]

- 打印逐项检查报告，并附带 → 后续步骤。
- 退出码：0 就绪，1 需要关注，2 用法错误。

npx dsh-firstrun
npx dsh-firstrun --json

在 harness 内使用（可由 agent 调用）

向你的 dsh agent 提问：

帮我体检一下环境，看看还缺什么。
Run a first-run health check: quickstart.

该工具会返回一份 dsh-firstrun/v1 报告：

{
"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"
}

检查项

| 检查项 | 验证内容 | 缺失时的状态 |
|---|---|---|
| node | PATH 中存在 Node.js | fail |
| pnpm | PATH 中存在 pnpm | fail |
| dsh | PATH 中存在 dsh CLI | fail |
| home | 已设置 HOME / USERPROFILE | fail |
| profile | DSH_HOME 或 ~/.dsh 存在 | warn |
| api-key | 已设置某个 API 密钥环境变量（绝不显示值） | fail |
| workspace | 当前目录可写 | warn |
| registry | npm registry 配置可解析 | warn |

为什么需要它

- 官方仓库中第一小时的失败绝大多数是环境配置摩擦（缺少工具链、缺少密钥、网络问题）；大多数用户不知道首先该检查什么。
- 现有工具可诊断插件健康状况（dsh-plugin-doctor）和网络（dsh-cn-boot）；本工具通过一份面向用户的单一检查清单 + 后续步骤来闭环。
- 零运行时依赖，只读，绝不打印值。

开发

pnpm install
pnpm typecheck
pnpm build
pnpm test
pnpm test:integration

CI 在 Windows 上运行 dsh-plugin-doctor 预检、单元测试、打包产物集成测试（真实调用 quickstart），以及全新配置文件的 dsh web 启动冒烟测试。
许可证

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
相关生态工具

- dsh-dep-audit - 依赖供应链卫生
- dsh-quality-score - 插件质量评分卡 + 全注册表排行榜
- dsh-ecosystem - 健康扫描、影响、趋势、实时仪表盘
- dsh-tutorials - 双语插件流水线教程
常见问题

- 如何安装？ dsh plugin add dsh-firstrun 或直接运行 CLI（见 README）。
- 需要 API key 吗？ 不需要。
- 是只读的吗？ 默认是；任何写入/应用都是显式标志。