Demo 路线图与准备

这一篇起进入实战。8 个 Demo 全部基于真实的 DeepSeek Harness npm 包（@deepseek-ai/dsh@0.1.0-rc.6 与 @deepseek-ai/cordis@4.0.1），每个都实际运行验证过。Demo 4 起完全不需要 API Key。

• 路线图
• 环境准备
• Demo 5–8 的共同约定
• 常见问题速查
• 出发

路线图

Demo	依赖真实 dsh？	需要网络/Key？	时长
1–3	仅 Cordis	否	各 3–5 分钟
4	dsh-llm 包	否	5 分钟
5–7	完整 dsh --profile headless	否（Mock）	各 5–10 分钟
8	完整 dsh（profile 机制）	否（Mock）	10 分钟

Demo 1–3 让你亲手操作 Cordis 原语；Demo 4 让你理解 LLM 接缝；Demo 5 是分水岭——第一次让真实的 dsh agent 循环跑起来，只是模型被换成了你自己写的 Mock 插件；Demo 6–7 在这条真实链路上叠加工具与拦截；Demo 8 把实验沉淀成自己的 profile。

环境准备

# 1. 确认 Node 版本 ≥ 20.19（推荐 22+）
node -v

# 2. 进入 demos 目录安装依赖（版本已锁定）
cd demos
npm install

目录结构（每个 Demo 自包含）：

demos/
├── package.json          # 依赖：cordis / dsh / dsh-llm / dsh-tools / tsx
├── 01-first-plugin/      # npm run demo:1
├── 02-events/            # npm run demo:2
├── 03-compose/           # npm run demo:3
├── 04-llm-mock/          # npm run demo:4
├── 05-headless-mock/     # plugins/ + *.patch.yml + read-session.mjs
├── 06-tool-echo/
├── 07-hooks/
└── 08-profile/

Demo 5–8 的共同约定

这三个 Demo 把本地插件以 --patch 覆盖层挂进真实的 dsh --profile headless 进程。两个约定：

① DSH_HOME 指向 Demo 自己的 .dsh-home，会话与设置互不污染：

cd 05-headless-mock
DSH_HOME="$PWD/.dsh-home" npx dsh --profile headless --patch mock.patch.yml "你的任务"

② patch 里本地插件的路径是 ../../../plugins/xxx.ts。原因：Loader 的 baseUrl 是 profile 目录（$DSH_HOME/profiles/headless/），相对路径从那里开始解析：

$DSH_HOME/profiles/headless/          ← baseUrl
../../../plugins/mock-adapter.ts      = <Demo 目录>/plugins/mock-adapter.ts

为什么不用 dsh web？

Web 模式同样可以挂 Mock 适配器（在浏览器里跟"模型"聊天），但 headless 模式输出干净、生命周期一次到位，更适合教学观察。学完 Demo 8 后，把 --profile headless 换成 --profile web 就能在浏览器里体验同一条链路（记得用 --patch 带上 mock 适配器，并在设置页把模型路由切到 mock）。

常见问题速查

• npx dsh 提示找不到包：确认在 demos/ 下执行过 npm install，且当前目录在 demos/ 内（npx 会向上查找本地 node_modules/.bin）。
• MODULE_TYPELESS_PACKAGE_JSON 警告：无害。是因为插件目录没有 package.json 的 type 字段；教学场景可以忽略，或给 plugins/ 加一个 {"type":"module"} 的 package.json。
• 改完插件没生效：headless 是一次性进程，重新运行命令即可（不是缓存问题）。
• Windows 用户：环境变量写法不同（$env:DSH_HOME = "$PWD\.dsh-home"），路径分隔符按 PowerShell 语法调整。

出发

从 Demo 1：第一个插件与可逆副作用 开始。