从零构建智能体 tsrigo/dsh-from-scratch

DeepSeek Harness 从零开始

这是一份可离线使用的教程，有中文和英文两个版本，用 TypeScript 和 Python 两套并行实现，讲清 DeepSeek Harness 的主要运行时机制。

DeepSeek Harness 简称 DSH，提供语言模型执行任务所需的运行时。它组装模型输入、暴露工具、执行校验过的工具调用、记录运行过程，并在一次模型响应不足以完成任务时继续推进。本仓库把这些机制精简成两套实现，可以阅读、运行、测试。仓库里还有一个交互式教程站点，由源码生成。

每套实现都用六个独立的确定性示例，只保留各自问题所需的输入和运行时事件。各章节逐步加入上下文投影、插件生命周期、会话日志、动态插件和长任务续跑。你可以查看源码、模型请求，以及每个机制改动后的运行时状态。

本项目专注讲运行时机制，代码库刻意做小，执行边界也写得很明确。它不提供 DeepSeek Harness 的兼容层，也不覆盖完整产品里的权限、持久化、调度和多智能体功能。

快速开始

需要 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

运行真实模型演示

下面这条命令运行一个有边界的 Python 任务。智能体必须创建 hello.py，用提供的校验器运行它，并确认输出正好是 Hello, world!。文件默认写到 demo-python/hello.py。

pnpm demo

设置了 DEEPSEEK_API_KEY 时，命令使用真实的 DeepSeek 模型。没有设置时，命令离线回放已存储的模型决策，不访问网络，也不模拟流式时序。你可以用环境变量和选项选择模型与工作区：

DEEPSEEK_API_KEY=your-key \
DEEPSEEK_MODEL=deepseek-chat \
pnpm demo -- --workspace ./tmp/python-hello

模型请求、工具调用和 Python 程序输出都记录在 SessionLog 中。想运行最初的离线结账示例，用 pnpm demo:checkout。

数据生成和浏览站点都不发模型请求，也不需要 API key。

运行教程站点

站点包含：

- 所选实现的四张入门卡片：TypeScript 讲类型注解、interface、async / await 和可辨识联合；Python 讲类型注解、dataclass、async / await 以及字典和列表。
- 每种实现各有六个独立机制示例，包含源码、逐章 diff、模型请求、Session Events、执行轨迹，以及和正文对应的插件关系。
- 估算相邻请求的稳定前缀、首个变化部分和 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。生成过程会检查源码范围、代码指南覆盖情况，并在请求证据来自 Session Events 时精确重建请求。

六个章节

下面的章节标题和问题与英文教程站点一致。摘要描述 TypeScript 实现；站点提供对应的 Python 课程。

第 1 章 · Agent Loop

DSH 的 Agent Loop 长什么样？

Agent.runTurn() 把一个 Turn（一次连续执行）拆成若干 Step。每个 Step 包含一次模型请求及其工具执行。Harness 根据当前状态构建请求。模型返回 Tool Call 时，Harness 用 JSON Schema 校验参数，执行工具，再把 Tool Result 加入下一次请求。模型不再调用工具时，Turn 结束。超过 maxSteps 会以显式错误终止。

本章还展示 Programmatic Tool Calling（PTC）如何把多个动作组织成 TypeScript 程序。仓库只做静态对比，不实现 Code Runtime。

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

上下文如何组织，DSH 又如何优化缓存复用？

每次模型请求都是完整记录的一次投影。对于很长的工具结果，模型视图保留开头、结尾，并显式标注省略的字符数。原始结果仍留在会话记录里。稳定的系统指令和工具 schema 排在最前，消息按顺序追加，Step 专属上下文排在最后。这种顺序让相邻请求之间保持更长的相同前缀。
站点会比较最长的相同规范前缀，并估算它的 token 数。实现不会调用或模拟服务商的 Prompt Cache。

第 3 章 · 一切皆插件

DSH 如何做到一切皆插件？

Context 是插件共享的注册接口。插件可以提供运行时 Service、注册 Tool、贡献系统 Prompt、添加 Event Listener。每项贡献都会记录自己的 owner，以及一个 effect，用来在插件生命周期内管理清理。如果 setup 失败，或者已挂载的插件被移除，Context 会按相反顺序执行这些清理函数。

这个小巧的运行时保留了教程所需的 Cordis 生命周期特性：依赖访问、能力归属、setup 回滚、幂等移除、运行时检查。

第 4 章 · 让每次运行都可追溯

DSH 如何记录并保存智能体运行？

SessionLog 按执行顺序追加 Turn 与 Step 边界、用户消息、模型响应、工具调用、工具结果、请求头、上下文检查点、插件变更、Goal 状态变更。每个事件都会获得单调递增的标识符，已存储的事件不会被原地修改。

buildRequest() 从这些事件重建所选 Step 的输入。replayTrace() 从同一来源推导执行轨迹。上下文检查点只在后续模型投影中替换更早的历史；原始事件仍然可用。最小运行时把日志保存在内存中，教程生成器把它序列化成静态 JSON 供站点使用。

第 5 章 · 运行时自进化

DSH 如何在运行时持续进化？

常驻的 Runtime Tools 向智能体暴露 cordis_inspect、cordis_define、cordis_run、cordis_stop、cordis_undefine。智能体可以检查当前能力、提交 Cordis 插件代码、挂载插件、调用新工具验证其行为，然后停止插件或删除其定义。

动态插件仍然走第 3 章的 Context.mount()，所以新工具和新提示词会出现在后续模型请求中，移除时也走同一条清理路径。Node.js 用 node:vm 加载代码。这套机制面向可信的教程 fixture，并不是针对不可信代码的安全沙箱。

第 6 章 · 让长时间任务持续推进

DSH 如何让长时间任务持续推进直到完成？

LongTaskRunner 在智能体 Loop 之外保存 Goal、它的当前状态、已开始的 Round 数、轮次上限。每个 Round 启动一次常规的智能体 Turn，并复用同一个 Context、工作区和 SessionLog。Round 返回结构化的进度、完成或阻塞信息。外层 runner 随后启动下一个 Round，或者以 completed、blocked、max-rounds 结束。
Goal、Round、Turn 和 Step 分别表示长期目标、一次续跑尝试、一次连续执行和一次模型请求。测试覆盖正常完成、无可观察进展、显式阻塞，以及配置的 round 上限。

部署教程站点

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

pnpm site:build 会在 website/dist/ 下生成生产站点。想在本地查看，运行 pnpm site:dev，然后打开终端里打印的地址。

有意划定的范围边界

TypeScript 实现省略了这些生产特性：

- 完整的 DeepSeek Harness 插件目录、预设加载和配置热重载。
- 用于 PTC 的 Code Runtime、通用 shell、任意文件访问和网络工具。
- 面向不可信插件代码的权限、审批流、进程隔离和安全沙箱。
- Session Log 的 JSON Lines 持久化、SQLite 持久化和进程重启恢复。
- 调度、后台任务、子代理和工作流。
- 服务商侧缓存命中的度量、计费模拟和通用上下文压缩策略。

这些边界让每一章的代码都直接对应它要回答的问题。完整产品见 DeepSeek Harness。

参考与许可

运行时行为参考了 DeepSeek Harness。逐章递进的结构，以及正文、源码与录制执行的对齐方式，参考了 pi-from-scratch。分阶段、可复现的动效设计参考了 vibe-motion/skills。本仓库中所有源码、正文、章节结构、组件、布局、动效和执行数据均为独立创作。

本项目采用 MIT License。它是独立的教育实现，与 DeepSeek 及其关联公司无隶属关系，未获其授权，也未与其合作开发。