0
0
0
项目概览与快速启动
2026-08-14
2026-08-14
文章摘要
|
# 入门01：项目概览与快速启动
> 如果你是前端开发者，可以把 DeepSeek Harness 理解成："给 AI 大模型配的浏览器 + DevTools"。
> 就像浏览器让网页能跑 JS、操作 DOM、调 API，Harness 让 AI 能执行代码、读写文件、搜索网页。
---
## 1. 这玩意儿是干啥的？
**DeepSeek Harness**（简称 `dsh`）是一个**开源 AI Agent 运行时框架**。说人话就是：它让你能**运行、管理和扩展 AI 智能体**。
你可能用过 DeepSeek 网页版聊天。但如果你想：
- 让 AI 自动帮你写代码并跑测试
- 让 AI 去搜索网页再整理结果
- 让 AI 操作文件、执行命令、调用各种 API
那你不能只靠一个聊天框。你需要一个"框架"来给 AI 配上"手脚"——这就是 Harness 做的事。
> 类比：AI 模型 = 大脑（会思考），Harness = 身体（能行动）。没有身体，大脑再聪明也只能打字聊天。
### 核心特性（用前端话翻译）
- **一切皆插件**：就像 Vite 插件或 Chrome 扩展，你可以按需加功能、换实现
- **时空可组合性**：听起来很玄乎，其实就是 React 组件树那套——父 Agent 套子 Agent，能力继承
- **事件溯源**：就像 Git 的 commit log，只追加不修改，任何时候都能回溯
- **多后端支持**：DeepSeek、GPT 等模型都能接，就像 axios 换 adapter
- **沙箱隔离**：类似于 iframe 的 sandbox 属性，防止 AI 乱搞
- **跨语言 SDK**：TypeScript 和 Python 都能调
### 项目状态
当前版本 `0.1.0-rc.5`，属于开发者预览版，还在快速迭代中，API 可能随时变。
---
## 2. 整体架构（先看图，有个印象就行）
```mermaid
graph TB
subgraph "用户入口"
CLI[apps/cli - 命令行]
WEB[apps/web - Web UI]
SDK[SDK - TypeScript/Python]
end
subgraph "宿主层 Host"
AP[apiproxy - API网关]
WS[webserver - HTTP服务器]
FS[frotend-static - 静态资源]
end
subgraph "核心层 Core"
AG[agent - Agent注册表]
AL[agent-loop - Agent循环]
SE[session - 事件溯源会话]
SC[scope - 作用域系统]
TL[tools - 工具注册表]
SP[system-prompt - 提示组装]
end
subgraph "LLM 层"
LLM[llm - LLM运行时]
DS[llm-deepseek - DeepSeek适配器]
PI[llm-pi-ai - Pi.ai适配器]
TM[token-meter - Token统计]
end
subgraph "功能插件"
SUB[subagent - 子Agent]
PLAN[plan - 计划模式]
WF[workflow - 工作流引擎]
MCP[mcp - MCP客户端]
FSYS[fs - 文件系统]
STO[storage - 存储枢纽]
ACP[acp - ACP协议]
WEBX[web - 网页搜索]
TTY[terminal - 终端]
...
end
subgraph "持久化层"
PERS[session-persistence - 会话持久化]
QUERY[session-query - 会话查询]
COMP[compaction - 会话压缩]
end
subgraph "沙箱层"
SL[sandbox-local - 本地沙箱]
SE2B[e2b - E2B沙箱]
SW[sandbox-windows-acl - Windows沙箱]
end
CLI --> AP
WEB --> WS
SDK --> AP
AP --> AL
WS --> AP
AL --> AG
AL --> SE
AL --> TL
AL --> SP
AL --> LLM
LLM --> DS
LLM --> PI
AL --> PERS
SUB --> AG
PLAN --> SE
WF --> AG
MCP --> TL
FSYS --> TL
WEBX --> TL
TTY --> TL
SL --> FSYS
SE2B --> FSYS
```
### 各层是干啥的？
| 层级 | 用前端话解释 | 相当于 |
|------|-------------|--------|
| **用户入口** | 你咋跟它交互 | CLI 像终端，Web UI 像页面，SDK 像 axios |
| **宿主层** | 提供 HTTP 接口 | 就像 Express 的 router + 中间件 |
| **核心层** | Agent 的大脑和骨架 | 管理 Agent 创建、会话记录、工具调度 |
| **LLM 层** | 接各种 AI 模型 | 就像 axios 的 adapter，换模型只需换配置 |
| **功能插件** | 各种能力扩展 | 相当于 Vite 插件，按需加载 |
| **持久化层** | 存聊天记录 | 相当于 localStorage + 数据库 |
| **沙箱层** | 安全隔离 | 类似于 iframe sandbox + Docker |
---
## 3. 核心设计理念（用前端视角理解）
### 3.1 一切皆插件
> 你用过 Vite 插件、webpack loader、Chrome 扩展吗？对，就是那个意思。
整个系统就是一堆插件拼起来的。你想加 Web 搜索功能？装个插件。想换 DeepSeek 为 GPT？装个插件。想自己写个工具？写个插件。
```mermaid
graph LR
A[Cordis 容器
相当于 Vue app] --> B[Agent循环插件] A --> C[工具系统插件] A --> D[Web搜索插件] A --> E[文件系统插件] A --> F[终端插件] A --> G[你自己的插件] ``` **好处**： - 不需要的功能就不装，轻装上阵 - 可以换实现（比如本地沙箱换成云端沙箱），接口不变 - 你也写一个，发到 npm 大家用 ### 3.2 时空可组合性 > 其实就是 React 组件树那套。父组件包子组件，子组件继承父组件的 props 和 context。 Agent 可以嵌套。主 Agent 创建一个子 Agent 去干活，子 Agent 能看到父 Agent 的"家当"（文件系统、工具等），但也能有自己的限制。 ``` 主 Agent（啥都能干） └── 子 Agent A（只能读文件） └── 子 Agent A1（只能搜网页） ``` ### 3.3 事件溯源 > 像 Git 一样，每次变更都 commit，不覆盖历史。 所有对话记录只追加不修改。你问"今天天气"，AI 答"晴"，然后 AI 执行了搜索工具——这些都是一条条事件，按顺序追加到日志里。AI 下次看到的内容，是从这些事件"算"出来的。 **好处**： - 能回放到任意历史时刻 - 可以从某个时间点"分叉"出新的对话分支 - 永远不会丢数据 --- ## 4. 上手跑起来 ### 前置条件 - **Node.js**: `^22.19.0 || >=24.0.0`（版本要求比较高） - **pnpm**: `^11.7.0`（推荐用 `corepack`） - **Git**: 你肯定有 ### 安装步骤 ```bash # 1. 克隆 git clone https://github.com/deepseek-ai/deepseek-harness.git cd deepseek-harness # 2. 装 pnpm corepack enable corepack prepare pnpm@11.7.0 --activate # 3. 装依赖（第一次比较慢，50+ 个包） pnpm install # 4. 构建 pnpm run build # 5. 验证 pnpm dsh --version ``` ### 启动 Web UI ```bash pnpm dsh web ``` 打开浏览器访问 `http://127.0.0.1:3080`，就能看到界面了。 ### 启动 CLI ```bash # 直接跑一个任务 pnpm dsh --profile headless "帮我列出当前目录的文件" # 或者交互式 pnpm dsh ``` --- ## 5. 项目目录长啥样 ``` deepseek-harness/ ├── apps/ # 应用入口（就像 Vite 的 src/main.ts） │ ├── cli/ # 命令行工具 │ └── web/ # Web UI ├── packages/ # 所有插件包（就像 node_modules 里的包） │ ├── core/ # 核心骨架 │ ├── llm/ # LLM 适配器 │ ├── fs/ # 文件系统 │ ├── sandbox/ # 沙箱 │ ├── subagent/ # 子Agent │ ├── ... ├── vendor/ # 第三方框架（Cordis） ├── docs/ # 文档 ├── examples/ # 示例项目 ├── website/ # 文档站点源码 ├── python/ # Python SDK └── native/ # 原生插件 ``` --- ## 6. 学习路线 | 顺序 | 学啥 | 大概内容 | |------|------|---------| | 01（本文） | 项目概览 | 看完你就知道这东西是干嘛的了 | | 02 | Cordis 框架 | 插件系统的基础，相当于学 Vue 先学组件 | | 03 | 核心包 | Agent、Session、Tools 等核心模块 | | 04 | Agent 循环 | 用户发消息后，系统内部是怎么跑的 | | 05 | 工具与 LLM | AI 怎么调用工具，怎么接不同模型 | | 06 | 会话持久化 | 聊天记录怎么存、怎么查 | | 07 | 安全机制 | 沙箱、凭证、超时等安全措施 | | 08 | 宿主层与 SDK | HTTP API、SDK 调用 | | 09 | 功能包全景 | 所有功能包一览 | | 10 | 插件开发 | 自己写一个插件实战 | --- ## 要点总结 - **DeepSeek Harness** = 给 AI 模型配的"身体"，让它能执行代码、操作文件、搜索网页 - 核心思想：**一切皆插件**（像 Vite 插件）、**可嵌套**（像 React 组件树）、**事件溯源**（像 Git） - 快速上手：`pnpm install && pnpm run build && pnpm dsh web` - 约 50+ 个包，用 pnpm workspace 管理 ## 进阶阅读 - 官方文档：`docs/` 目录 - 示例项目：`examples/` 目录 - 名词速查：[附录-AI 概念名词速查手册](附录-AI概念名词速查手册.md) - 下一步：[02-Cordis 插件框架核心概念](02-Cordis插件框架核心概念.md)
相当于 Vue app] --> B[Agent循环插件] A --> C[工具系统插件] A --> D[Web搜索插件] A --> E[文件系统插件] A --> F[终端插件] A --> G[你自己的插件] ``` **好处**： - 不需要的功能就不装，轻装上阵 - 可以换实现（比如本地沙箱换成云端沙箱），接口不变 - 你也写一个，发到 npm 大家用 ### 3.2 时空可组合性 > 其实就是 React 组件树那套。父组件包子组件，子组件继承父组件的 props 和 context。 Agent 可以嵌套。主 Agent 创建一个子 Agent 去干活，子 Agent 能看到父 Agent 的"家当"（文件系统、工具等），但也能有自己的限制。 ``` 主 Agent（啥都能干） └── 子 Agent A（只能读文件） └── 子 Agent A1（只能搜网页） ``` ### 3.3 事件溯源 > 像 Git 一样，每次变更都 commit，不覆盖历史。 所有对话记录只追加不修改。你问"今天天气"，AI 答"晴"，然后 AI 执行了搜索工具——这些都是一条条事件，按顺序追加到日志里。AI 下次看到的内容，是从这些事件"算"出来的。 **好处**： - 能回放到任意历史时刻 - 可以从某个时间点"分叉"出新的对话分支 - 永远不会丢数据 --- ## 4. 上手跑起来 ### 前置条件 - **Node.js**: `^22.19.0 || >=24.0.0`（版本要求比较高） - **pnpm**: `^11.7.0`（推荐用 `corepack`） - **Git**: 你肯定有 ### 安装步骤 ```bash # 1. 克隆 git clone https://github.com/deepseek-ai/deepseek-harness.git cd deepseek-harness # 2. 装 pnpm corepack enable corepack prepare pnpm@11.7.0 --activate # 3. 装依赖（第一次比较慢，50+ 个包） pnpm install # 4. 构建 pnpm run build # 5. 验证 pnpm dsh --version ``` ### 启动 Web UI ```bash pnpm dsh web ``` 打开浏览器访问 `http://127.0.0.1:3080`，就能看到界面了。 ### 启动 CLI ```bash # 直接跑一个任务 pnpm dsh --profile headless "帮我列出当前目录的文件" # 或者交互式 pnpm dsh ``` --- ## 5. 项目目录长啥样 ``` deepseek-harness/ ├── apps/ # 应用入口（就像 Vite 的 src/main.ts） │ ├── cli/ # 命令行工具 │ └── web/ # Web UI ├── packages/ # 所有插件包（就像 node_modules 里的包） │ ├── core/ # 核心骨架 │ ├── llm/ # LLM 适配器 │ ├── fs/ # 文件系统 │ ├── sandbox/ # 沙箱 │ ├── subagent/ # 子Agent │ ├── ... ├── vendor/ # 第三方框架（Cordis） ├── docs/ # 文档 ├── examples/ # 示例项目 ├── website/ # 文档站点源码 ├── python/ # Python SDK └── native/ # 原生插件 ``` --- ## 6. 学习路线 | 顺序 | 学啥 | 大概内容 | |------|------|---------| | 01（本文） | 项目概览 | 看完你就知道这东西是干嘛的了 | | 02 | Cordis 框架 | 插件系统的基础，相当于学 Vue 先学组件 | | 03 | 核心包 | Agent、Session、Tools 等核心模块 | | 04 | Agent 循环 | 用户发消息后，系统内部是怎么跑的 | | 05 | 工具与 LLM | AI 怎么调用工具，怎么接不同模型 | | 06 | 会话持久化 | 聊天记录怎么存、怎么查 | | 07 | 安全机制 | 沙箱、凭证、超时等安全措施 | | 08 | 宿主层与 SDK | HTTP API、SDK 调用 | | 09 | 功能包全景 | 所有功能包一览 | | 10 | 插件开发 | 自己写一个插件实战 | --- ## 要点总结 - **DeepSeek Harness** = 给 AI 模型配的"身体"，让它能执行代码、操作文件、搜索网页 - 核心思想：**一切皆插件**（像 Vite 插件）、**可嵌套**（像 React 组件树）、**事件溯源**（像 Git） - 快速上手：`pnpm install && pnpm run build && pnpm dsh web` - 约 50+ 个包，用 pnpm workspace 管理 ## 进阶阅读 - 官方文档：`docs/` 目录 - 示例项目：`examples/` 目录 - 名词速查：[附录-AI 概念名词速查手册](附录-AI概念名词速查手册.md) - 下一步：[02-Cordis 插件框架核心概念](02-Cordis插件框架核心概念.md)