tsrigo/dsh-from-scratch

DeepSeek Harness from Scratch

| English

一个可离线运行的中英文教程，用 TypeScript 与 Python 两套实现解释 DeepSeek Harness 的主要运行机制。

DeepSeek Harness（DSH）为语言模型执行任务提供运行环境。它组织模型输入，向模型提供工具，执行经过校验的工具调用，保存运行过程，并在一次模型回复不足以完成任务时继续推进。这个仓库把上述机制整理成两套可以阅读、运行和测试的最小实现，同时提供一个与源码同步的交互式教学网站。

两套实现都使用六个独立的确定性样本，只保留当前问题需要的输入和运行事件。章节之间逐步加入上下文投影、插件生命周期、会话日志、动态插件和长程任务续行。读者可以分别检查每项机制引起的源码、模型请求和运行状态变化。

本项目面向机制教学，代码规模和运行边界都有意保持有限。它不提供 DeepSeek Harness 的兼容接口，也不覆盖完整产品中的权限、持久化、任务调度和多 Agent 协作能力。

快速开始

需要 Node.js 22 或更高版本。项目使用 pnpm 11，版本已经写入 package.json。

git clone https://github.com/tsrigo/dsh-from-scratch.git
cd dsh-from-scratch
corepack enable
pnpm install
pnpm tutorial:generate
pnpm site:dev

运行真实模型 Demo

下面的命令完成一个受限的 Python 任务。Agent 需要创建 hello.py，调用验证器运行它，并确认输出正好是 Hello, world!。文件默认写入 demo-python/hello.py。

pnpm demo

设置 DEEPSEEK_API_KEY 后，命令调用真实的 DeepSeek 模型；没有设置时，命令离线重放仓库中保存的模型决策，不访问网络，也不模拟流式等待。可以通过环境变量指定模型和工作区：

DEEPSEEK_API_KEY=你的密钥 \
DEEPSEEK_MODEL=deepseek-chat \
pnpm demo -- --workspace ./tmp/python-hello

模型请求、工具调用和 Python 程序的实际输出都会进入 SessionLog。如果只想运行原来的离线购物车样本，可以使用 pnpm demo:checkout。

生成过程与网站浏览都不调用模型，也不需要模型服务的应用程序编程接口（Application Programming Interface，API）密钥。

浏览教学网站

网站包含以下内容：

- 四张与当前实现语言对应的阅读准备卡。TypeScript 版解释类型标注、interface、async / await 和可区分联合类型；Python 版解释类型标注、dataclass、async / await 与字典和列表。
- 两套实现各有六个彼此独立的最小机制样本，以及与当前段落对应的源码、逐章差异、模型请求、Session Event（会话事件）、执行过程和插件关系。
- 相邻请求的稳定前缀、首次变化位置和 token（模型处理文本的计量单位）数量估算。这些数据只用于解释请求结构，实际缓存命中与计费以模型服务返回的数据为准。

pnpm tutorial:generate 会依次运行 TypeScript 和 Python 生成器。TypeScript 生成器读取 docs/checkpoints.json 或 docs/checkpoints.en.json、对应的正文与阅读准备内容，写入 website/public/generated/tutorial.json 和 website/public/generated/tutorial.en.json。Python 生成器读取 python_harness/、docs/lessons-python/、docs/lessons-python-en/、对应的 Python 阅读准备内容，以及用于英文覆盖内容的 docs/python-chapters.en.json，写入 website/public/generated/tutorial-python.json 和 website/public/generated/tutorial-python.en.json。生成期间会检查源码行号、代码讲解覆盖范围，以及可以从事件重建的模型请求是否与原请求一致。

六章内容

以下概要对应 TypeScript 实现；网站中提供了同一组六章问题的 Python 教学版本。

第一章·Agent Loop

DSH 的 Agent Loop 是什么样的?

Agent.runTurn() 把一个 Turn（一次连续执行）分成多个 Step（一次模型请求及其工具执行）。每个 Step 都从当前状态构造请求。模型返回 Tool Call（工具调用）后，Harness 使用 JSON Schema 校验参数，执行工具，再把 Tool Result（工具结果）加入下一次请求。模型没有继续调用工具时结束 Turn，超过 maxSteps 时明确终止。

本章还对照程序化工具调用（Programmatic Tool Calling，PTC）怎样把多个动作组织成 TypeScript 程序。仓库只提供静态对照，不实现 Code Runtime（代码运行环境）。

第二章·上下文与缓存复用

上下文是怎样组织的，为缓存复用做了什么优化？

模型请求从完整记录投影得到。长工具结果只在模型视图中保留开头、结尾和省略字符数，原始结果继续保存在会话记录中。请求把稳定的系统提示词和工具定义放在前面，按顺序追加消息，把当前 Step 的动态说明放在最后，以保留较长的相同前缀。

页面比较相邻请求经过规范化后的最长相同前缀，并估算对应的 token 数量。这里没有调用或模拟模型服务的 Prompt Cache（提示词缓存）。

第三章·一切皆插件

如何实现“一切皆插件”？

Context 是插件统一使用的注册入口。插件可以提供 Service（运行时服务）、注册 Tool、贡献系统 Prompt（提示词），以及添加 Event Listener（事件监听器）。每项贡献都记录来源和 effect（随插件生命周期管理的操作）。插件安装失败或主动卸载时，Context 按相反顺序执行 effect 中登记的清理函数。

这个最小运行时保留了 Cordis 插件生命周期中与教程直接相关的部分：依赖获取、能力归属、安装回滚、幂等卸载和运行时检查。

第四章·让运行有迹可循

DSH 怎么记录和保存 Agent 执行过程?

SessionLog 按发生顺序追加 Turn、Step、用户消息、模型回复、工具调用、工具结果、请求头、上下文检查点、插件变化和 Goal 状态。每个事件取得连续编号，已经写入的事件不会原地修改。

buildRequest() 从这些事件重建指定 Step 的模型输入，replayTrace() 从同一组事件生成执行过程。上下文检查点只替换后续模型请求看到的较早历史，原始事件仍然保留。当前最小实现把日志保存在内存中；教程生成器将它序列化为网站使用的静态 JSON 数据。

第五章·运行时自进化

DSH 是如何持续自进化的?

常驻的 Runtime Tools（运行时工具）向 Agent 提供 cordis_inspect、cordis_define、cordis_run、cordis_stop 和 cordis_undefine。Agent 可以检查已有能力，提交一段 Cordis 插件代码，挂载插件，调用新增工具验证结果，再停止插件或删除定义。

动态插件仍然经过第三章的 Context.mount()，所以新增工具与 Prompt 会进入后续模型请求，卸载时也使用相同的清理路径。代码通过 Node.js 的 node:vm 执行环境加载；这项实现用于可信教学样本，不构成面向不可信代码的安全沙箱。

第六章·长程任务续行

DSH 是如何持续完成长程任务的？

LongTaskRunner 在 Agent Loop 外保存 Goal（长期目标）、当前状态、已经开始的 Round（续行轮次）和轮数上限。每个 Round 启动一个普通 Agent Turn，并沿用同一个 Context、工作区和 SessionLog。单轮返回结构化的进展、完成或受阻结果，外层据此继续下一轮，或者以 completed、blocked、max-rounds 结束。

Goal、Round、Turn 和 Step 分别处理长期目标、跨轮续行、一次连续执行和一次模型请求。测试覆盖正常完成、没有可观察进展、显式受阻和达到轮数上限。

部署教学网站

pnpm tutorial:generate
pnpm site:build
pnpm site:dev

pnpm site:build 生成生产版本，输出目录是 website/dist/。本地查看时使用 pnpm site:dev，然后打开终端显示的地址。

实现边界

当前 TypeScript 版本有意省略以下生产能力：

- 完整 DeepSeek Harness 的插件目录、preset 加载与配置热重载。
- PTC 的 Code Runtime、通用 Shell、任意文件读写和网络工具。
- 面向不可信插件代码的权限、审批、进程隔离和安全沙箱。
- Session Log 的 JSON Lines（JSONL，每行一条 JSON 记录）或 SQLite 持久化，以及进程重启后的恢复。
- Schedule（定时任务）、后台 Job（作业）、Subagent（子 Agent）和 Workflow（工作流）。
- 模型服务端缓存命中的测量、计费模拟和通用上下文压缩策略。

这些边界让每章的代码与它回答的问题保持直接对应。需要完整产品能力时，请阅读 DeepSeek Harness。

参考与许可

架构行为参考 DeepSeek Harness。章节的渐进实现、正文与源码同步方式参考 pi-from-scratch。程序化动效的阶段划分与可复现状态方法参考 vibe-motion/skills。本仓库的源码、文案、章节组织、组件、布局、动效和过程数据均为独立创作。

项目使用 MIT License。本项目为独立教学实现，与 DeepSeek 及其关联方不存在隶属、授权或合作关系。