flaqai/deepeseek-harness-guide

DeepSeek Harness 指南

DeepSeek Harness 指南 — 从首次运行到 Agent 开发

一份面向开发者的多语言指南，帮助你理解、运行、扩展 DeepSeek Harness 并基于它构建 agent。

DeepSeek Harness（dsh）是 DeepSeek AI 推出的开源 agent 运行时与组合框架。它将模型、提示词、工具、权限、沙箱、会话、子 agent、遥测和用户界面连接成一个可运行的 agent——并通过共享的插件架构让这些部分都可替换。

本仓库以实用的方式讲解该系统。它是一个独立的社区指南，并非 DeepSeek 官方项目。

[!IMPORTANT]
DeepSeek Harness 处于开发者预览阶段，明确允许破坏兼容性的变更。请固定你的项目所使用的 DSH 版本，并对照官方仓库核实命令和 API。

从这里开始

| 我想要…… | 阅读此内容 |
|---|---|
| 了解 DSH 是什么 | 什么是 DeepSeek Harness？ |
| 了解架构 | 架构和技术指南 |
| 运行 Web UI 或 SDK | 快速开始和使用手册 |
| 安装并测试 DSH 插件 | OpenPencil 插件演练 |
| 在 DSH 上构建 agent | 使用 DSH 开发 agent |
| 构建或打包插件 | 扩展模型和官方插件教程 |
| 让编码 agent 协助处理 DSH | 可复用的 Agent Skills |
| 审查第三方插件 | 安全性与兼容性 |

目录

- 什么是 DeepSeek Harness？
- 架构
- 快速开始
- 安装并使用 DSH 插件：OpenPencil 示例
- 使用 DSH 开发 agent
- 选择合适的扩展
- 文档地图
- 可复用的 Agent Skills
- 安全性与兼容性
- flaq.ai 模型 API 与联盟计划

什么是 DeepSeek Harness？
模型可以生成文本或工具调用，但它本身并不管理工作区、安全执行工具、保留会话、请求批准、从取消中恢复、协调子代理或暴露用户界面。代理框架（agent harness） 提供了这一操作层。

DSH 在两个相关的角色中很有用：

1. 一个开箱即用的代理应用 —— 启动官方 Web UI，配置模型，选择工作区，并运行代理会话。
2. 一个用于组装代理产品的框架 —— 替换或添加模型提供者、工具、代理循环、存储、沙箱、策略、界面和工作流，而无需维护完整的运行时分支。

其核心思想是一切皆插件。内置能力和第三方扩展使用相同的组合机制，由 Cordis 提供支持。这使得 DSH 更接近于一个可配置的代理运行时，而非单一的固定编码助手。

本项目新增的内容

官方项目提供了实现和参考契约。本指南增加了：

- 针对快速变化的源码树的稳定心智模型；
- 多语言的架构与操作文档；
- 针对代理、工具、提供者、会话和 UI 开发的决策路径；
- 安全与生命周期审查清单；
- 可复用的技能（Skills），帮助编码代理探索、搭建、构建和审查 DSH 扩展。

架构

DSH 有两个协同的结构：

- 运行时插件图定义了哪些能力可用、它们在何处可见，以及谁拥有它们的生命周期；
- 会话事件流保留了重建模型可见历史和界面状态所需的持久事实。

代理循环通过从图中读取模型、提示、工具、策略和存储能力，执行工作，并将结果写回会话来连接二者。

flowchart LR
C["Profile + Bundles + Patches"] --> L["Cordis Loader"]
L --> G["Runtime plugin graph"]
G --> A["Agent Loop"]
A --> M["Model providers"]
A --> T["Tools + policy + sandbox"]
A --> S["Session event stream"]
S --> A
S --> H["Host APIs"]
H --> U["Web / desktop / TUI / other clients"]

运行时组合

| 概念 | 职责 |
|---|---|
| 插件（Plugin） | 一个挂载到 Cordis 上下文中的 TypeScript 函数、对象或服务类。 |
| 上下文（Context） | 控制能力可见性和资源所有权。 |
| 服务（Service） | 由某个插件提供、其他插件通过 inject 消费的类型化能力。 |
| 纤程（Fiber） | 一次带有自身生命周期的实时插件挂载。 |
| 副作用（Effect） | 一种资源注册，在其所属纤程卸载时进行清理。 |
| 事件（Event） | 插件之间的类型化观察点或拦截点。 |
| 加载器（Loader） | 将有序配置协调为实时插件图。 |

部署组合

| 概念 | 职责 |
|---|---|
| 包（Bundle） | 一个通过 dsh.bundle 贡献配置层的 npm 包。 |
| Profile | 一个命名的可运行组合，包含有序的 Bundle 和本地依赖。 |
| Patch | 一种后期 YAML 覆盖层，用于插入或替换配置行。 |
| Preset | 会话级 Agent 行为；它不是另一个进程级 Profile。 |

Agent 执行

一个典型的轮次遵循以下路径：

1. 从持久化的 Session 事件重建模型可见的上下文；
2. 组装系统提示词、工具 schema、模型路由和策略状态；
3. 流式输出模型响应；
4. 验证、授权、批准并执行请求的工具；
5. 将规范结果持久化为 Session 事件；
6. 继续执行，直到满足 Agent Loop 的完成条件；
7. 将相同的事件状态投射到 Web 或其他客户端。

关于 Context、Service、Fiber、Effect、Event、Session、Turn/Step、缓存和安全边界，请阅读技术架构指南。

快速开始

运行官方 Web UI

安装 Node.js 22.19 或 24+ 版本（并在部署前重新查看官方开发指南），然后运行：

npx @deepseek-ai/dsh web

打开 http://127.0.0.1:3080，在 Settings → Models 中配置模型服务，选择一个工作区，然后从一个非破坏性任务开始。

在调试扩展之前，检查生效的插件树：

dsh --profile web --dump-config

从源码运行

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build
pnpm dsh web

也可以通过官方 Python SDK 进行编程式嵌入。有关 SDK 设置、插件安装、回滚和故障排除，请参阅使用手册。

安装并使用 DSH Plugin：OpenPencil 示例

本演练将所引用指南中展示的 OpenPencil 流程转化为可复现的插件工作流。在 DSH 中，Plugin 提供运行时行为，Bundle 通过 dsh.bundle 分发配置层，而 Profile 为某个可运行环境选择有序的 Bundle 和本地配置。因此，将包安装到 web 中会改变该 Profile；它不会修改每一个 DSH 安装。

[!NOTE]
所引用的示例将 DSH 固定为 0.1.0-rc.6，但使用 @latest 安装插件。请将以下命令视为经过测试的快照，而非对当前兼容性的承诺。安装、检查、启动和移除时请使用相同的 DSH 版本；验证后，也请将插件固定到确切版本。

1. 检查先决条件

- 在 DSH 中配置一个支持工具调用的模型提供商。可以使用已配置的 flaq.ai 模型，但 OpenPencil 是一个工具插件，而非仅限 Flaq 的集成。
- 在更改其 Profile 之前，停止正在运行的 Web UI。
- 从其官方仓库安装 OpenPencil，并使用 op --version 确认其 op 可执行文件对 shell 可见。
- 在同一项目环境中运行所有命令，以便它们解析到相同的 DSH home 和 web Profile。

2. 将插件安装到 Web Profile

所引用的示例使用公开的 OpenPencil 插件包：

npx --yes -p @deepseek-ai/dsh@0.1.0-rc.6 dsh plugin --profile web add @zseven-w/dsh-openpencil@latest

对于生产或共享开发环境，请先验证包的发布者、源仓库、发布说明、请求的权限、安装脚本以及兼容范围。将 @latest 替换为你测试过的确切版本。

3. 检查生效的配置

在启动 UI 之前，确认预期的 Bundle 和插件行已存在：

npx --yes -p @deepseek-ai/dsh@0.1.0-rc.6 dsh --profile web --dump-config

--dump-config 显示在 Bundle 补丁、Profile 补丁、home 级补丁和命令行补丁之后的最终有序组合。如果插件缺失，请检查所选的 Profile 以及是否每条命令都解析到相同的 DSH home。

4. 重启并测试

npx --yes -p @deepseek-ai/dsh@0.1.0-rc.6 dsh web

打开 Web UI，选择配置好的模型和工作区，创建一个新会话，并尝试一个有边界的请求，例如：

Create a simple editable OpenPencil document with a title, a subtitle,
and two feature cards. Save it as harness-guide.op, inspect the document,
and summarize its layers.

一次成功的运行应当向模型暴露 OpenPencil 工具，创建一个 .op 文档，并返回可检查或可编辑的结果。在批准之前审查提议的工具调用，并在一次性工作区中开始。

5. 移除或回滚

停止 Web UI，从同一 Profile 中移除该包，再次检查组合，然后重启：

npx --yes -p @deepseek-ai/dsh@0.1.0-rc.6 dsh plugin --profile web remove @zseven-w/dsh-openpencil
npx --yes -p @deepseek-ai/dsh@0.1.0-rc.6 dsh --profile web --dump-config

如果升级失败，请恢复之前测试过的 DSH 和插件版本，而不是同时更改两者。

故障排除

| 症状 | 检查 |
|---|---|
| UI 中缺少插件 | 停止并重启 UI；确认 DSH 版本、Profile、DSH home 和 --dump-config 输出。 |
| OpenPencil 工具未注册 | 确认 Bundle 已挂载该插件，并且其 tools 依赖可用。 |
| 找不到 op | 安装 OpenPencil CLI，修复 PATH，验证 op --version，然后重启 DSH。 |
| 安装被构建脚本策略阻止 | 先检查依赖及其脚本；仅对你信任的包允许构建脚本。 |
| 选择模型后工具调用失败 | 验证提供程序支持工具调用以及所需的请求、schema 和流式行为。 |
| 升级破坏了插件 | 回退到最后一对测试过的版本，检查上游发布说明，然后一次升级一个组件。 |

从使用插件到开发插件
一个专注的 DSH Tool 插件遵循一个小型生命周期感知契约：

import type { Context } from '@deepseek-ai/cordis'
import { defineTool } from '@deepseek-ai/dsh-tools'

export const name = 'example-tool'
export const inject = ['tools']

export function apply(ctx: Context) {
ctx.tools.register(defineTool({
name: 'echo_text',
description: 'Return text for a connectivity test.',
parameters: {
text: { type: 'string', required: true, description: 'Text to return.' },
},
output: {
schema: { type: 'string' },
render: (_args, value) => [{ type: 'text', text: value }],
},
async execute({ text }) {
return text
},
}))
}

重要的设计规则如下：

1. 用 inject 声明所消费的 Service，使插件仅在其依赖就绪时挂载；
2. 保持 parameters 严格，并校验所有外部输入；
3. 让 execute 返回规范结果，并使用 output.render 生成面向模型的内容；
4. 通过所属的 Context 注册定时器、监听器、工具及其他资源，以便卸载时清理它们；
5. 先用 Patch 在本地测试，然后使用 dsh.bundle 将配置打包为 Bundle；
6. 安装到一次性 Profile 中，检查 --dump-config，并测试加载、拒绝、取消、卸载、重新挂载、移除和回滚；
7. 固定 Git/包依赖并审查生命周期脚本，因为安装脚本会在 Agent 沙箱之外执行。

继续阅读官方首个插件教程、Tool 教程、插件打包指南，以及本仓库的 dsh-plugin-scaffold 和 dsh-tool-builder Skills。

使用 DSH 开发 Agent

构建 Agent 通常意味着组合多个 DSH 扩展点，而不是编写一个大型插件。

1. 定义 Agent 契约

写下目标用户、任务边界、允许的副作用、所需数据、完成条件、预算、取消行为以及人工审批点。这决定了实际需要哪些运行时能力。

2. 选择运行时组合

从接近目标主机的 Profile 开始，添加带版本的 Bundle，并将环境特定的更改保留在 Patch 中。在开发外部插件时使用一次性 Profile。

3. 配置模型和上下文

选择或实现模型提供方，然后定义提示词组装、工作区指令、记忆、压缩和工具可见性。尽可能保持稳定的提示词和工具 schema 前缀不变，以便提供方侧的前缀缓存仍然有效。

4. 以专注插件的形式添加能力

创建窄范围的提供方和消费方：

- 用于模型请求操作的 tools；
- 用于可复用运行时能力的 Services；
- 用于观测和拦截的 Events；
- 当现有实现不适用时，使用 model、filesystem、process、sandbox、storage、telemetry 或 subagent providers。

通过 inject 声明所消费的 Services，并通过具备生命周期感知能力的 ctx 辅助函数注册资源。

5. 塑造 Agent Loop 与策略

当仅提示词、工具或策略发生变化时，使用现有的 loop。仅当规划、路由、校验、交接、重试或完成语义确实不同时，才替换或包装 Agent Loop。将 schema 校验、授权、用户批准和操作系统沙箱保持为独立的控制项。

6. 使状态可重放

如果某个事实之后对模型或 UI 可见，则将其持久化为规范的 Session 事件。将 UI 状态视为投影，而非事实来源。测试取消、部分工具失败、重启、压缩和重放。

7. 仅在需要处添加界面

运行时行为属于 Host。浏览器呈现属于 Client 插件。跨边界功能应使用类型化的远程 API，而不是在 UI 中重复状态。

8. 打包并验证

将可分发配置打包为 Bundle，将其安装到一次性 Profile 中，检查 --dump-config，并测试挂载、正常使用、拒绝、超时、卸载、重新挂载、重启、移除和回滚。

选择正确的扩展

| 目标 | 优先选择 | 避免与之混淆 |
|---|---|---|
| 添加模型可以请求的操作 | Tool 插件 | Agent Skill |
| 共享运行时能力 | Service provider 插件 | 生命周期控制之外的全局单例 |
| 更改规划或完成行为 | 优先使用 Prompt/policy 插件；必要时使用 Agent Loop | 为每种行为新建一个 Profile |
| 添加模型或基础设施后端 | Provider 插件 | 将其硬编码到 loop 中 |
| 保留记忆或审计状态 | Session/storage 插件和持久事件 | 仅 UI 状态 |
| 添加 Web 面板或结果卡片 | Client 插件加类型化 Host API | 特权浏览器代码 |
| 交付配置和插件 | Bundle | Profile |
| 组装可安装的运行时 | Profile | Runtime fork |
| 连接独立应用程序 | Client 或协议桥接 | 进程内插件 |
| 在开发过程中指导编码 agent | Agent Skill | DSH 运行时插件 |

常见的 Agent 产品模块包括工作流与规划、工具与集成、上下文与记忆、会话与重放、子代理、模型路由、浏览器与视觉、策略与沙箱、UI 界面，以及运维/遥测。使用手册提供了分类模块图和安装检查清单。

文档地图

| 资源 | 用途 |
|---|---|
| 技术指南 | 架构、生命周期、Session 模型、缓存和安全边界 |
| 使用手册 | 安装、模块选择、插件/工具工作流、故障排除和发布检查 |
| 可复用技能 | 供智能体阅读的 DSH 开发工作流 |
| 贡献指南 | 来源、翻译、审阅与贡献规则 |
| 路线图 | 计划中的示例、验证、兼容性元数据与生态工作 |

目前每个 README、架构指南和使用手册都有 15 个语言入口。

可复用智能体技能

这些仓库本地技能可引导兼容的编码智能体完成常见的 DSH 工作。技能是一种指令工作流；它不会随 dsh plugin 安装，也不会在 DSH 运行时内执行。

| 技能 | 用途 |
|---|---|
| dsh-repository-explorer | 梳理 Profiles、Bundles、Patches、packages、Services、Events、Sessions 以及 Host/Client 归属关系。 |
| dsh-plugin-scaffold | 构建一个范围窄小、生命周期安全的插件，并可选进行打包。 |
| dsh-tool-builder | 设计一个有类型、感知策略、有边界且可重放的工具。 |
| dsh-plugin-review | 审计兼容性、生命周期、供应链、权限、密钥与重放风险。 |

安全与兼容性

- 固定 DSH 及第三方插件的修订版本；预览版 API 并非稳定契约。
- 检查 dsh --profile  --dump-config 以验证实际组合。
- 在允许依赖安装脚本和 prepare 脚本运行之前，先审阅它们。
- 将同进程插件、生成的 JavaScript、子进程、文件系统访问和网络访问视为特权行为。
- 不要将 inject 描述为沙箱。依赖可见性、策略、审批与操作系统隔离是相互独立的边界。
- 让真实凭据、私有 Sessions、截图、二维码和联系方式远离示例与文档。
- 将生态收录视为发现渠道，而非安全背书。

官方与社区来源

- DeepSeek Harness 官方仓库
- 官方架构
- 官方首个插件教程
- 官方工具教程
- 官方打包与安装指南
- Cordis 及其时空可组合性论文
- 社区生态分类参考

flaq.ai 模型 API 与联盟计划
flaq.ai 是一个第三方 AI 模型聚合与 API 平台。其 LLM API 提供了一个托管的 Chat Completions 路由，并附有 JavaScript、Python 和 cURL 的流式示例。为基于 DSH 的 Agent 评估模型提供商的开发者，可以查看以下 DeepSeek V4 端点：

| API | 建议的评估重点 |
|---|---|
| DeepSeek V4 Pro Text-to-Text | 推理、写作、编码辅助、分析以及生产级文本工作流 |
| DeepSeek V4 Flash Text-to-Text | 快速、注重成本的文本生成、摘要、写作和自动化 |

在将任何第三方端点连接到 DSH 之前，请对照两个服务的最新文档，核实当前的 base URL、模型标识符、流式行为、工具调用支持、定价、数据处理、速率限制和错误契约。此处收录仅为一种集成选项，并不构成对可用性、性能或兼容性的保证。

开发者和内容创作者也可以申请 flaq.ai 联盟计划。参与该计划受当前协议和适用法律约束；联盟成员必须进行必要的披露，避免误导性推广，并且不应假定任何有保证的流量、佣金、付款或收益。

贡献与许可

欢迎提供更正、翻译、示例、固定修订版本的案例研究以及 Skills。请参阅 CONTRIBUTING.md。本指南在 MIT License 下提供。