Node/pnpm/monorepo/ESM/TypeScript——每条项目命令都能看懂。Node 版本 ^22.19 || >=24，包名 @deepseek-ai/dsh-*。
Node.jspnpm / npmmonorepoESMTypeScript
从零基础到「会用 · 会写插件 · 能教别人」——19 课 + 三个动手实验 + 命令速查表
| 你的目标 | 对应课程 | 学完你能 |
|---|---|---|
| ① 设计思路、理念 | 阶段 1（L03–L07） | 用三句话讲清这个项目为什么长这样 |
| ② 使用技巧（含进阶） | 阶段 2（L08–L11） | 熟练使用，并用 profile/patch/MCP 定制 |
| ③ 开发插件 | 阶段 3（L12–L18） | 写出工具/拦截器/服务插件并发布；看懂社区插件 |
| ④ 命令清单 | commands.html | 随用随查，可搜索、可复制 |
| 给同事讲解 | 阶段 4（L19） | 拿着讲稿完成 10 分钟内部分享 |
learn/ 是学习材料，不属于 deepseek-harness 项目本身，随时可删除或移动。只补齐"看懂本项目命令与代码"所需的最小 Node 知识集，已熟悉可跳过。
Node/pnpm/monorepo/ESM/TypeScript——每条项目命令都能看懂。Node 版本 ^22.19 || >=24，包名 @deepseek-ai/dsh-*。
拿到仓库不迷路：packages/（插件包，按 core/llm/shell/… 分组）、docs/、vendor/（内嵌 Cordis 源码）；三步跑起来 pnpm install → build → pnpm dsh web。
三句话讲清 dsh：一切皆插件、能力可整体替换、日志是唯一事实源——也是 L19 讲稿的素材。
智能体 = 大模型 + 工具 + 循环；Harness = 给模型套上马具的框架（管会话、工具、权限、日志）。开发者预览期，抓理念别死记 API。
连模型适配、工具注册表、会话日志、agent 循环本身都是插件。三个好处：没有特权核心、注册即效果（拔掉干净消失）、热重载。
插件框架五概念：插件对象 / ctx 插座板 / inject 依赖注入 / 类型化事件（emit·waterfall·parallel·serial）/ 可撤销效果。≈ Spring 的 IoC 容器 + 事件总线，但类型安全且一切可逆。
Definition（声明接口）→ Provider（提供实现）→ Consumer（消费使用，通常是工具）。换 Provider = 换掉整个产品的某项能力，其他角色无感。铁律：扩展插件只依赖 Definition。
只追加的事件流水账；模型历史由 deriveMessages() 推导而非另存。铁律「模型可见即可日志」。turn = 一轮对话，step = 一次模型请求+工具调用。银行流水类比：存的是流水，余额是算出来的。
先当用户用顺，再谈定制。L10、L11 是你区别于普通用户的进阶关键。
两种启动：免安装 npx @deepseek-ai/dsh web；源码三步曲。Settings → Models 填 API key 即存即用。先添加 workspace 再开会话。
会话新建/恢复/分叉；权限预设与审批；Plan mode（先方案后执行）；todo 工具；上下文压缩 compaction。
不写一行代码重新组装 dsh。四层叠加后到者胜：bundle 清单 → profile 补丁 → home 补丁 → --patch。神技 --dump-config：打印真实插件树，任何一行都可被你的补丁按 id 替换。
MCP（一服务器一插件）、Skills（Markdown 教模型工作流）、Hooks（复用 Claude Code/Codex 配置）、子智能体、定时任务；SDK/ACP 把 dsh 当引擎嵌入自己的程序。
每课都有动手环节，产出一个属于你的 scratch-plugin。学完 L18 能读懂任意社区插件。
name / inject / apply(ctx)——最小可运行插件，--patch 挂载，亲身体验热重载与"注册即效果"。
给模型造一个它能看见并调用的工具：name/description/parameters/execute/output 五要素，20 行写一个 greet。渲染意图（generic/terminal/diff）是设计的一部分。
定义 Config，cordis.yml 传参。配错大声失败（fail loud）；默认值走显式 resolve() 而非隐藏 ??；!!js 表达式只允许出现在 config 和 disabled。
四种派发模式选型 + waterfall 洋葱模型（不调 next() 即短路）；实战：在 tools/pre-execute 写 allow/deny/ask 权限门。
Service 子类（默认导出）vs 函数插件（命名导出，混用会静默丢功能）；把 L13 工具拆成三角色三包，体验换 Provider 不动 Consumer；invariant 测试验收。
聊天流里插业务卡片（ConversationNode）；给插件配设置面板，用户不用改 YAML。一切 UI 从 session/event 事件流渲染。
打包成 bundle（package.json 声明 dsh.bundle + 补丁文件）发布；读插件五步法：dsh 字段 → inject → apply → Config → README 的 Model Experience。
阶段 1 的内容直接可当讲义；本课组织成一场可复述的内部分享。
三张图（插座板 / turn-step 循环 / 三角色）+ 演示五步（跑起来 → 真实任务 → 20 行代码加工具 → 热重载 → 模型当场调用）+ 三个高频问题标准答案。L04–L07 可直接投屏。
有，而且大部分不用写代码。按投入从低到高：
| 扩展面 | 写代码？ | 一句话说明 | 典型场景 |
|---|---|---|---|
| YAML 组合 | 否 | profile / bundle / patch / preset：换配置、换组合、按 id 替换任意插件实现 | 把持久化换成 SQLite、给团队定制 profile |
| Skills 技能 | 否（写 Markdown） | 教模型"某类任务的标准做法"，按需加载 | 团队编码规范、发布流程 |
| Hooks 桥 | 否（写配置） | 直接复用 Claude Code / Codex 已有 hook 配置 | 已有 hook 资产的团队迁移 |
| MCP 服务器 | 否（任意语言、进程外） | 外部工具服务器经 MCP 挂进来，一服务器一插件 | 接内部工具链、数据库、工单系统 |
| TypeScript 插件 | 是 | 一切深度扩展的正路：工具、拦截器、服务、UI 全能写 | 深度定制产品行为 |
| SDK / ACP（进程外） | 是 | 把 dsh 当引擎嵌进你自己的程序 | 集成进公司系统 |
packages/extensions/）——dsh 相当独特的演示点。