hello-dsh

DeepSeek Harness 的入门第一课

从「怎么打开终端」开始，30 分钟做出你的第一个插件

English · 中文 · 开始学 →

---

DSH 的第一句自我介绍是 "Everything is a Plugin"。

这不是修辞。装好之后点 Settings → Plugins → Plugin list，看右上角那个数字：

133 个。 里面有 llm（模型适配器）、session（会话记录）、webserver（你正在看的网页服务器）、ui-sidebar（左边那条侧边栏），还有 agent-loop —— agent 的主循环本身也是一个插件。

这个仓库带你从「打开终端」开始，一步步做出你自己的插件，并亲眼看到它的生命周期。

---

开始

→ 完整教程：Hello DSH

🌏 教程目前只有中文版，英文版整理中。

⚠️ 网页版要带 --patch 启动，否则技能不生效且不报错。教程第 3 步有说明， 或直接看下面的「一个要注意的坑」。

假设你什么都没有：没装过 Node，没用过命令行。每一节都有检查点，看到指定结果才往下走。

步骤	内容	时间
1–2	打开终端、装 Node.js	7 分钟
3–5	启动 DSH、配置密钥、选工作区	10 分钟
6	亲眼看到 133 个插件	3 分钟
7–8	做第一个插件、看它的生命周期	10 分钟
9–10	接下来做什么、原理（选读）	13 分钟

前 8 步约 30 分钟，跑完就能用。

---

给 DSH 加东西的两条路

路线	写什么	门槛	适合
Markdown（技能）	一个文本文件	5 分钟	改变模型的判断标准、输出格式、工作流程
TypeScript（代码插件）	一个代码模块	半小时起	注册新工具、接外部服务、改界面

判断依据：能用大白话说清楚要它怎么做的，走 Markdown 路线。

教程两条都会带你走一遍。

---

现成的例子

跑完教程想直接用的话，examples/skills/ 里有 22 个写好的中文技能。

让 AI 帮你装（最省事）

把这个链接丢给 Codex、Claude Code、或 DSH 自己：

https://github.com/pingfanfan/hello-dsh/blob/main/INSTALL-FOR-AGENTS.md
照这个装

它会先检查 Node、DSH、API 密钥三项前置，再拷文件。

或者自己跑一条命令

git clone https://github.com/pingfanfan/hello-dsh.git
cd hello-dsh && ./install.sh

先看会做什么：./install.sh --dry-run 移除：./install.sh --uninstall

技能清单

技能	什么时候用
hello-dsh	第一课：验证插件系统，按层讲解生命周期与原理
dsh-onboarding	第一次跑 DSH，或卡在启动、工作区、权限
dsh-skill-dev	写技能（Markdown 路线）的完整规则
dsh-first-plugin	从零做出第一个代码插件（实测流程 + 三个报错）
dsh-plugin-dev	写插件（TypeScript 路线）的完整规则
dsh-troubleshoot	起不来、配置没生效、UNKNOWN_TOOL、技能不见了
plan-before-code	任务要改多处、有不确定性、超过半天
code-review-cn	审查代码改动、PR、diff
debug-systematically	遇到 bug、测试失败、本来是好的现在坏了
explain-codebase	快速理解陌生项目
refactor-safely	重构、拆函数、消除重复
test-first	写测试、实现功能、修缺陷
api-design	设计接口、加公开方法、定数据结构
error-handling	设计错误处理、决定该抛还是该返回
perf-optimize	优化性能、排查慢的原因
security-review-cn	安全审查、评估攻击面、检查凭据处理
commit-message	写提交信息、拆分改动
pr-description	写 PR 描述、准备评审
write-tech-cn	写中文文档、README、技术博客
write-docs-cn	写或整理项目文档、API 说明、教程
web-research	联网查资料、核实事实、技术选型
ask-good-questions	提技术问题、报 bug、写 issue

装完之后对 DSH 说 「hello dsh」，它会带你走一遍，可以一层层往下问。

---

一个要注意的坑

⚠️ DSH 的网页版默认关闭了技能功能（命令行版是开着的）。实测于 0.1.0-rc.6。

网页版要用技能的话：

npx @deepseek-ai/dsh web --patch ./enable-skills-in-web.yml

配置文件在本仓库根目录。

---

写这份教程时实测到的行为

为了写这个，我在两台干净的 Mac 上从头跑了 DSH。下面这些行为都写进了教程，因为每一条都会让新手卡住而且不报错：

发现	为什么重要
网页版出厂时 tool-skill 和 skill-filesystem 是禁用的，headless 是启用的	同一个技能命令行能用、网页版静默失效，没有任何报错
网页版必须先选工作区，发送按钮才会激活	命令行版没这个限制，所以用 headless 验证时撞不上
旧的 DSH 进程占着 3080 时，页面照样能正常打开	新实例报 EADDRINUSE 退出，浏览器连的是旧进程，改什么配置都不生效
--patch 是插入而不是覆盖，被 patch 的插件会挂载两份	无害，但插件列表会显示 7 个 skill 插件而不是 5 个
frontmatter 键名写成驼峰会丢弃整个技能，只留一条警告	官方有意的 fail-closed 设计，但不知道的话很难查

全部实测于 0.1.0-rc.6。

配套工具

dsh-doctor —— DSH 配置体检，一条命令扫出会导致静默失效的问题：

npx dsh-doctor

只读不改。每条检查都对应 DeepSeek 官方文档或事故报告里记录过的真实故障。

---

这些技能是怎么写的

参照 DSH 官方仓库的 .agents/skills/，那里有 11 个 DeepSeek 自己在用的技能。共同点：

1. 是判断指引，不是清单（官方原话："This skill is guidance, not a complete checklist"）
2. 列出事实来源，并说明「读它，不要复述它」
3. 分层：阻断项 / 检查项 / 不要做的事
4. 单独写「不要做的事」 —— 挡住的问题往往比「要做什么」更多

详见 docs/writing-skills.md。

---

欢迎投稿

见 CONTRIBUTING.md。要求两条：中文、并且你真的在用它。

许可

MIT

---

非官方社区项目，与 DeepSeek 无隶属关系。