夜雨聆风学习资料网

ARTICLE · 1390093

DeepSeek Harness 插件开发全流程:八步走完从需求定义到发布复测

DeepSeek Harness 插件开发全流程:八步走完从需求定义到发布复测

项目上线安排散落在文档里,每次都要手动翻找原文。这篇把 DeepSeek Harness(简称 DSH)的插件开发拆成八个步骤,从需求定义到分发复测,帮你理清每一步该做什么、谁来批准。DSH 是 DeepSeek 开源的智能体框架,用来组织模型与程序执行任务。把固定的查询动作做成插件,模型就能在你提问时自动调出原文,省去每次手动翻找的时间。

整个流程分八步:定位宿主→定义需求→复用已有能力→固定环境→委托开发与验收→打包复测→跨软件接入→安全与费用管理。下面逐步展开。

一、插件装在哪个软件里,决定怎样开发

插件必须装在某个软件里,接收任务并执行动作。这个承载插件的软件叫“宿主”,它决定能读什么、怎样加载和分发。DSH 是一个独立的开源框架,与 DeepSeek 官网聊天框或官方对话应用扩展是不同的东西:后者是 DeepSeek 自己运营的在线产品,前者是你可以在本机部署、自行扩展的开发框架。本文讲的是在 DSH 中开发插件,不涉及官方产品的内置功能。

给 DSH 增加工具,与给办公软件接模型,是不同开发路线。 API 是软件调用模型服务的接口,DeepSeek API 提供 DeepSeek 的模型能力。浏览器和办公软件也能使用它,不必安装 DSH。

比较维度
DSH 插件
其他软件的插件
承载软件
DSH 智能体框架
浏览器、办公或笔记软件
资料读取
由框架中的工具实现
由对应软件的扩展实现
安装与设置
遵循框架加载规则
遵循对应软件的权限和扩展渠道

接入现成插件不等于开发新插件。 填写 API Key(访问模型服务的密钥)只是配置已有扩展。新插件还要实现读取和展示,并交付可安装的文件。

在这个分工里,模型负责理解问题并组织回答,程序(也就是插件代码)负责实际查文件和返回原文,宿主(DSH 框架本身)负责控制哪些目录允许被读取、哪些操作需要人批准。模型提出查询不代表文件已被读取,真正的动作和权限始终由宿主一侧把关。

DSH 可以更换模型接入方式,也能增加工具,适合这个教学需求。源码在 GitHub(代码托管平台)提供,发布包在 npm(公开软件包仓库)分发。

它仍是开发者预览版,后续变更可能使旧插件无法加载,需要改代码并重测。演示不证明生产可用,开发时要固定源码版本。

理解 DSH 的插件机制,需要先看清它的三层架构(见下图)。最上层是 Profile(运行设置),决定启动时加载哪些能力组合;中间层是 Bundle(组合包),把一组相关功能打包分发,比如 dsh-base 提供模型适配器和工具注册表,dsh-web-app 提供浏览器界面;最下层是 Plugin(插件),也就是我们自己写的代码,通过框架提供的注册接口把自己的工具挂进去。三层之间是“上层组装下层”的关系,每一层都可以从配置替换,不需要改源码。

二、先把项目查询写成可验收的需求

宿主确定后,“查项目资料”还要变成能检查的输入和结果。第一版只查明确批准目录里的 .md 和 .txt:Markdown 是可用普通文本保存的排版格式,文件使用 UTF-8(一种通用的文字编码,几乎所有现代编辑器都支持)。

先定义可验收的查询,再决定是否自建插件。 程序只做可解释的关键词匹配,不理解所有近义表达,也不替人判断哪份记录最权威。

以下资料、日期和行号都是虚构演示数据,不是实际查询记录。一次合格的工具结果可以这样呈现:

  • 输入:query 为“上线安排”,表示待查的关键词或短语。
  • 文件与位置:会议纪要/排期.md 第 12 行,相对路径只表示资料在批准目录中的位置。
  • 原文片段:“上线安排暂定 12 月 8 日,待项目负责人批准。”
  • 扫描范围:本次检查批准目录中的 3 份合格文本文件,命中 1 处。
  • 是否查完:已查完本次范围,没有读取失败或截断。

模型可据此回答“纪要写的是暂定 12 月 8 日,仍待批准”,并附文件与行号。查到原文不能替代项目批准。 日常使用时你不必再手动翻文件;但在开发和验收阶段,仍需打开对应文件核对行号,确认插件返回的内容确实来自原始资料。

查询要拒绝空白、过长或类型错误的输入,不能把输入拼成终端命令。没有命中应返回无结果;读取失败和扫描未完成应分别说明,不能解释为“项目没有安排”。

达到限额后仍有资料未查,结果要标记截断,也就是还有内容没有检查。查询目录与开发目录分开,未填写或未批准就不读取;符号链接是跳转到别处的文件入口,指向目录外时必须拒绝。

首版不承担这些功能:

  • 不解析 PDF 和办公文档,不识别扫描图片。
  • 不联网或接远程资料库,不增加外部账号。
  • 不做语义检索或权威性裁决,不写回或删除资料。

两份纪要写法不同,工具应保留各自片段和位置,模型指出冲突,不擅自合成唯一日期。文件修改时间只说明文件何时改过,不能证明安排较新或已经批准。

三、需求明确后,优先复用已有能力

确认需要自建之前,先看框架已有的能力够不够用。DSH 已有文件读取和搜索工具,简单查询未必需要新代码。工具是模型能请求执行的程序动作;要固定查找顺序,可以把做事说明交给助手,让它按说明调用已有工具。

现成工具不够执行固定查询规则时,才需要自建。

方法
作用
何时采用
已有工具
读取和搜索文件
临时查原文,先测是否够用
Skill(按需加载的做事说明)
规定已有动作怎样组合
固定先查记录、再核对依据
MCP(Model Context Protocol,一套让模型调用外部工具的标准协议)
连接外部系统工具的规范
资料在外部系统,已有查询接口
自定义工具
把业务规则写进程序
固定目录边界和返回格式

Skill 能要求回答附原文位置,但不能代替程序检查文件真实去向。资料已有外部系统查询接口时,可用 MCP 接入;本机目录查询无需另搭服务。

DSH 命令行默认不启用 MCP。若选择需在本机启动的外部程序,其代码执行和访问范围还要另获批准。

这些方法由同一框架装配,插件也能承担不同功能:

功能类别
解决什么问题
本案是否新增
模型接入
连接提供模型计算的服务
否,复用已有配置
工具动作
让程序执行查询等操作
是,只补查询规则
做事说明
规定已有动作怎样组合
按需使用
外部工具接入
使用别的系统提供的动作
否
会话与存储
保存对话和运行记录
否
界面
展示结果和设置
否,沿用文字界面
定时流程
在指定时间自动执行任务
否

首版不另发模型请求,也不保存模型密钥。开发 Agent 是能生成文件、执行工程任务的助手,负责实现这些约束;实际具备哪些执行能力、能否运行命令,还要先核对并取得批准。

四、复用不够才自建:先固定环境,再弄清一次查询怎样运行

确认需要自建后,第一步不是写代码,而是锁定框架版本。自建工具要依托确定的框架版本,否则旧样例可能无法加载。截至 2026 年 11 月 14 日,GitHub 源码与 npm 发布包的默认版本并不相同。

版本入口
对应版本
本案选择
GitHub 最新预发布
dsh-v0.2.2-rc.3
固定这份源码
npm 的 latest 标签
0.2.2-rc.1
当时默认渠道,不是最高版本号
npm 的 next 标签
0.2.2-rc.3
预览渠道,会随发布变化

源码标签标记一份固定代码,rc.3 表示第 3 个发布候选版本,仍非正式稳定版。本案固定这份源码,安装依赖后构建(转换成可运行文件);只启动发布包不能完成源码开发。

环境准备由 Agent 执行,版本和执行许可先由人确认。 Node.js 是运行程序的环境,固定版本要求至少 24.9.0。pnpm 用来安装项目所需组件,仓库指定 11.28.5。

插件放在框架仓库的 scratch-plugin 内,代码与构建脚本由 Agent 交付。读者核对文件和执行记录,不必手写实现;安装缺失工具也要另行批准。

node --version # 至少24.9.0,否则停止corepack enable# 仅在Corepack已安装可用时执行;首次下载另需联网和执行许可git clone https://github.com/deepseek-ai/deepseek-harness.git # 同名目录存在就停止cd deepseek-harnessgit checkout dsh-v0.2.2-rc.3 # 固定代码版本pnpm --version # 核对为11.28.5,不符就停止pnpm install # 获批准后安装依赖pnpm run build # 构建框架# npx @deepseek-ai/dsh@0.2.2-rc.3 web 仅启动指定发布包,不代替上述源码开发

这些是交给 Agent 的待执行命令,运行后应留下实际记录。构建后从框架根目录统一使用 pnpm dsh 启动,不混用另一份全局安装。

工具登记与调用是前后相接的动作

下图展示了一次查询从加载到返回的完整时序。图中六步对应下方编号列表的六个动作,可以对照阅读。

登记是让模型知道能请求什么,执行才真正查文件。 一次查询按以下六步衔接:

  1. 加载源码:框架从启动配置找到插件源码,等依赖的工具注册表就绪后,启动插件的准备函数。
  2. 依赖就绪:宿主把已有的登记操作交给插件,插件此时才能调用注册接口。
  3. 登记工具:插件报上工具名 project_query、关键词查询用途和输入约定,模型此后才知道可以请求这个工具。
  4. 模型请求:模型在对话中决定调用 project_query,传入 query(例如“上线安排”)。输入必须是文字,程序还要拒绝空白和过长内容。
  5. 执行查询:程序先检查文件的真实去向是否在批准目录内。路径开头匹配只能说明文件“看起来”在正确位置,真正的安全检查要靠操作系统级别的真实路径解析,防止符号链接跳转到别处。确认安全后才只读扫描,把原文、位置和扫描情况返给模型。
  6. 返回结果:模型拿到原文后组织回答,界面展示结果。插件卸载时自动撤销登记并清理资源,避免旧工具残留。

开发 Agent 按固定版本的官方样例实现注册代码。你不需要记住具体的函数名和参数,只需要从三个层面核验:配置是否正确加载、启动日志是否显示插件就绪、实际对话中工具是否被调用并返回了正确的原文和行号。

程序先把原文与扫描情况整理成下面的结构化数据,再转成文字送回模型。位置和查询状态必须由程序如实报告,不能让模型凭空补出。

内部字段
中文用途
status
区分命中、无结果和错误
matches
保存相对路径、行号与原文片段
scannedFiles
记录实际检查的文件数
truncated
标记是否仍有内容未检查
warnings
说明读取失败或限额等问题

程序读到“上线安排暂定 12 月 8 日”后,还要把结果送回模型。返回约定是一段带原文、文件位置、扫描范围和未完成说明的文字,模型才有依据回答。

Agent 在代码中声明返回类型为文字,查询函数返回的也是一段纯文字。自动测试会检查返回值确实是文字、且包含上述全部字段。你验收时只需核对界面中显示的原文和行号是否正确,不需要关心这些内部字段名。

运行设置决定范围与工作量

Config 是程序读取设置时的校验规则,用来检查配置并补默认值。授权目录随部署变化,不能写死在源码或发布包中;配置限制也不能代替人的批准。

设置字段
本案默认值
用途
allowedRoot
必填的批准绝对目录
没设置就不查询
maxResults
5
最多返回 5 个片段
maxFileBytes
1048576 字节
单文件约 1 MB 文本,即 1 MiB(1 MiB = 1048576 字节,是计算机常用的文件大小单位)
maxScanFiles
200
最多扫描 200 份文件

这些是作者选择的教学默认值,不是官方上限;提高片段数会增加返回内容,提高文件或扫描限额会增加读取量,是否够用应拿实际资料规模核对。

运行配置、修改清单、配置目录和安装包各有用途:

名称
具体保存或读取什么
本案怎样用
profile(运行设置)
一套运行设置,保存启动清单
web
 是本案所选的运行设置
patch(补丁配置)
追加或修改启动清单的配置文件
本地追加源码入口,分发时按包名加载
DSH_HOME(配置根目录)
指定存放所有 profile 设置和凭据的目录
换 profile 名仍可能共用全局资料,安装测试另用全新目录
tgz 与 pack
tgz 是含构建文件的压缩安装包,pack 是生成它的动作
把包交给安装者,安装后另填资料目录与限额

五、按职责委托开发,再检查加载和查询证据

人先填写目录并批准范围,Agent 生成文件和自动测试,再由人决定是否真实对话验收。 委托的是可构建、可检查的工程,不只是一个查询函数;以下需求可整段复制。

只有对话能力的办公助手不能代替本地执行,具备工程工具的 Agent 也只能按许可写文件、运行命令。读者不必手写函数,但验收要看交付文件和测试记录。

下面是一份需求模板,结构和措辞可以直接复用,但方括号 [ ] 标注的四处目录路径和三项授权确认需要你先填好再交给 Agent:

【项目资料查询插件开发需求】■ 由人确认的目录(可先请 Agent 提供实际路径)  · 框架源码目录:[待填写的绝对目录]  · 插件目录:[上述源码目录内 scratch-plugin 的绝对目录]  · 授权资料目录:[待填写的绝对目录,与开发目录分开]  · 新测试 DSH_HOME:[人批准、尚不存在的绝对目录]■ 授权确认  · 模型数据授权:[是否允许片段发送到批准的模型服务,默认不允许]  · 付费测试授权:[默认不允许]  · 宿主额外日志上传:[核对并按批准范围关闭,不默认许可]■ 业务要求  1. 开发 DSH 宿主的教学查询插件(不是官网聊天插件或浏览器扩展)。     插件三个名字是同一事物的不同称呼:     包名 dsh-project-query / 模块名 project-query / 工具名 project_query。     固定 dsh-v0.2.2-rc.3。  2. 只查批准目录中的 UTF-8 .md/.txt,必填 query,做关键词匹配。     返回状态、相对路径、原文片段、行号、扫描数量与截断警告。     不解析 PDF 或图片、不联网、不自动裁决冲突、不写回或删除。■ 工程交付  3. 先报告执行能力、计划、读写目录、命令及风险。     核对 Node.js ≥ 24.9.0、pnpm 11.28.5 与实际依赖。  4. 交付 Config 校验定义,检查 allowedRoot / maxResults(5) /     maxFileBytes(1048576) / maxScanFiles(200)。     拒绝空白、过长或类型错误输入,阻止越界和符号链接逃逸。  5. 交付完整源码、package.json、构建脚本、本地 cordis.yml、     分发 cordis.patch.yml。inject 等待 tools,     用 ctx.tools.register(defineTool(...)) 注册。     output.schema 为 string,不留待办占位。  6. 本地 patch 指向源码绝对路径,分发 patch 改为包名。     查询函数只读,不用终端、不额外调用模型,     日志不含资料全文或密钥。■ 测试证据  7. 用虚构资料测试:正常 / 无结果 / 错参数 / 越界 / 读取失败 /     限额 / 超时 / 拒绝授权 / 重复调用 / 卸载重载。     自动测试与对话测试分开。密钥由人配置,不索要或打印。  8. 构建并 pack,查包内无密钥、真实资料、日志或机器路径。     在全新 DSH_HOME 中初始化 web profile,从 tgz 安装,     补目录与全部限额,复测并卸载。■ 人工批准  9. 读取许可 ≠ 执行许可。安装依赖、构建、第三方脚本、     修改权限、访问模型、公开发布,逐项取得批准。 10. 报告实际文件、版本、命令和测试,逐项标记状态。     缺授权或可核实接口就停止;无执行工具时交完整文件,     不声称本地实现或测试通过。

Agent 先检查源码加载,人再配置真实对话

Agent 交付的本地 scratch-plugin/cordis.yml 用来临时追加源码入口。下面的路径都是教学占位,须替换为已批准的实际绝对路径;配置文件放到另一处,不会自动改变源码查找位置。

-insert:-id:project-queryname:'/absolute/path/to/deepseek-harness/scratch-plugin/src/project-query.ts'# 源码绝对路径config:allowedRoot:'/absolute/path/to/project-materials'# 批准的资料目录maxResults:5# 片段数上限maxFileBytes:1048576# 单文件字节上限maxScanFiles:200# 扫描文件数上限

Agent 从已构建框架根目录运行 pnpm dsh web --patch ./scratch-plugin/cordis.yml。浏览器默认打开 http://127.0.0.1:3080,其中 127.0.0.1 表示本机,3080 是服务端口;改配置后地址也可能不同。

Agent 检查配置用 pnpm dsh --profile web --patch ./scratch-plugin/cordis.yml --dump-config,这里 web 与启动命令选同一套运行设置。两次操作保持同一终端中的环境设置,不改变 DSH_HOME、工作目录或 patch 文件。

获准做真实对话后,人打开“设置→模型”,配置已批准的服务和对应凭据并保存,官方 DeepSeek 使用 API 密钥。密钥不交给 Agent 填写或打印。

人再添加并选中批准的测试工作区,选择可用模型,才有可用输入框。选择工作区时核对实际目录,它不替代插件中 allowedRoot 的查询范围批准。

配置、加载与调用证据不能互相替代:

  • 配置里有 project-query,目录和限额符合批准范围,证明启动清单正确。
  • 启动日志显示插件及所需服务已加载,证明代码进入运行状态。
  • 获授权的对话出现 project_query 调用,文件、行号与片段可回查,才证明实际调用。

Agent 的自动程序测试不调用模型,用虚构资料检查错误输入和目录边界。由人批准的对话测试再验证实际工具调用,可能发送片段并产生费用;没有凭据、资料发送许可或付费测试授权,就只做离线和加载检查。

测试情形
业务可检查的结果
证据由谁查看
正常命中、记录冲突
原文位置准确,冲突片段保留
读者打开文件核对行号
无结果、错参数、缺目录
状态明确,不擅自读取
Agent 自动测试记录,读者查结果说明
越界、跳转链接、不可读文件
拒绝或说明失败,不泄露外部内容
Agent 用虚构内外目录测试
大文件、达到限额、输出格式错
读取受限,未查完明确告知
Agent 核对数量和返回文字测试
超时、拒绝权限
停止动作,不冒充无结果
Agent 模拟延迟和拒绝,记录实际停止
重复调用、卸载重载
不重复登记,卸载后不可调用
Agent 查运行记录,读者看调用状态

热重载是卸载旧插件再加载新代码,仅启用对应能力时由 Agent 测试。改动后检查重复登记和旧资源,各项结果记录“已执行”“未执行”或“失败”。

六、源码换成安装包后,重新配置并复测

源码在本地跑通之后,还要验证别人拿到的安装包能不能独立工作。下图展示了从源码到分发的五个阶段,每个阶段在下方正文中都有对应的详细说明。

bundle 是附带启动配置文件的软件包,装进选定的 profile 后按配置加载;普通依赖若没有 bundle 声明,不会因此加载插件配置。

安装包要能独立加载,交付前再查入口和配置。 工具调用仍认 project_query,源码模块和安装包则按下表辨认:

类别
本案文件
如何连接
源码
src/project-query.ts
模块名 project-query;构建为 lib/index.js
包清单
package.json
包名 dsh-project-query;声明入口与打包范围
启动配置
本地 cordis.yml、分发 cordis.patch.yml
本地指向源码;分发按包名加载
安装包
dsh-project-query-0.1.0.tgz
带构建文件与分发配置,不带开发机路径

Agent 按以下清单字段检查安装程序能否找到实际代码。构建必须产出对应入口,不能只写一个不存在的文件名。

清单字段
中文职责
name
、version
包身份和版本,教学包版本为 0.1.0,不是 DSH 版本
main
启动入口,指向实际 lib/index.js
files
打包清单,纳入 lib 与 cordis.patch.yml
type=module
声明代码采用的模块方式
peerDependencies
声明共享宿主提供的组件,避免另装一套
devDependencies
声明开发时构建、检查所需组件
engines.dsh
仅写实际验证过的宿主兼容范围
dsh.bundle.patch
指向 ./cordis.patch.yml,让安装管理器识别配置层

需要共享的 DSH 组件同时声明共享与开发依赖,普通运行依赖也要完整列出。各组件版本从固定源码的清单核对,不能全部照抄 DSH 版本;构建脚本必须真正产出入口文件。

包内容与安装者的资料配置分开。 包内只带必要代码和加载设置,不带密钥、真实资料、日志或机器目录。安装者另行批准资料目录,并填入自己的运行配置。

安装者换资料目录时,Agent 生成完整的 config 设置,同时写明目录和全部查询限额。新设置会替换该插件原来的整份配置,不会自动保留旧字段。

安装者换目录时,Agent 应生成包含全部字段的完整配置(目录 + 所有限额),而不是只写一个目录字段指望旧值自动保留。DSH 的配置覆盖机制是整份替换,省略的字段不会从之前的配置继承,只会回退到代码中写死的默认值。

全新配置目录隔离安装测试

安装测试使用第四节所列的全新 DSH_HOME,避免共用旧设置和凭据。目录由人批准且尚不存在,Agent 不覆盖旧目录;这只是配置分开保存,不是隔离插件代码的沙箱。

固定版本的 web 模板带基础能力 base 和网页界面 web-app。Agent 先在全新设置目录初始化 web,查看启动清单中两者是否存在,再安装查询包。

以下由 Agent 从框架根目录开始,在同一终端依次执行。路径先换成实际新目录,包名以 pack 输出为准;补齐目录和全部限额后才启动。

export DSH_HOME='/absolute/path/to/new-approved-dsh-home'# 必须是全新批准目录pnpm dsh --profile web --dump-config # 初始化,核对基础能力 base 和网页界面 web-app(cd scratch-plugin && pnpm run build && pnpm pack) # 构建并打包插件pnpm dsh plugin --profile web add ./scratch-plugin/dsh-project-query-0.1.0.tgz# 由 Agent 按批准范围补 profile 配置中的目录与全部查询限额pnpm dsh --profile web --dump-config # 重查配置,不带源码 patchpnpm dsh web # 配置齐备后启动,完成加载及获批准的查询测试# 退出运行进程后,仍在同一终端卸载pnpm dsh plugin --profile web remove dsh-project-querypnpm dsh --profile web --dump-config # 核对已移除;再启动核对工具不可调用

旧设置不会因选择 web 自动补齐基础能力和网页界面,本案不重置既有环境。新环境若做对话,仍按第五节由人配置模型和工作区,并单独批准资料发送与费用。

私下交付与公开发布分开批准

验证过的 tgz 已能私下交付,pack 不等于公开发布。若获准把包公开放到 npm 仓库,Agent 先复核包名、版本、包内文件和许可证,插件及依赖分别确认授权。

在插件目录执行 npm login --registry=https://registry.npmjs.org/,完成账号和适用的二次验证,再执行 npm publish --registry=https://registry.npmjs.org/。这是公开上传安装包的步骤,不能仅以打包记录代替。

发布后在独立环境执行 pnpm dsh plugin --profile web add dsh-project-query@0.1.0。Agent 用实际包名和版本复测,留下安装和查询记录,不能以发布成功替代可用证据。

分发方式
安装者拿到什么
额外责任
本地目录
开发文件
只适合调试,不证明发布包完整
tgz 或 npm
预构建包
明确版本,安装后补配置并复测
Git
固定提交的一份源码
安装者执行构建,脚本单独信任

通过 Git 分发源码时锁定提交,避免变化中的分支替换交付代码。prepare 是安装时执行构建的脚本,作者要完整提供,从源码安装也要求 pnpm 可用。

允许运行该包的构建脚本,要另获执行批准。工具沙箱不保证限制这些安装脚本,不能把查询工具获准读取目录当成构建授权。

七、换到其他软件,按宿主机制接入 DeepSeek API

如果查询要嵌进办公或笔记软件,宿主就不再是 DSH。功能目标可以沿用,但 DSH 的加载配置和安装包不能直接当成另一种软件的扩展包。

API 提供模型能力,不替宿主完成授权和写回。 这条路线有公开实例,但不意味着各插件由 DeepSeek 开发,也不证明当前配置都已更新:

第三方实例
谁提供、是什么
证明哪种路线
Tars(TarsLab 提供的 Obsidian 笔记插件)
在笔记软件中接模型生成文本
笔记软件接入路线可行
Dify 的 DeepSeek 插件(langgenius 发布的模型供应商插件)
在 Dify 应用开发平台中配置模型服务
应用平台接入路线可行

这些实例只说明接入路线可行,不作排行或安全推荐。新插件仍需由 Agent 按目标软件的接口实现,并用实际文件和测试验收。

宿主插件按以下顺序工作:

  1. 在批准权限下读取选区或指定资料,只取当前任务需要的内容。
  2. 发送到可信后端(开发者或公司管理的服务器程序,由它保护共享密钥)。后端先检查登录和调用权限,不能让任意人借它消耗付费额度。
  3. 展示模型返回,处理流式输出(内容分批显示),以及超时和错误。失败时不拿半截结果替换原文。
  4. 需要写回时展示修改并取得确认,再由宿主扩展执行,模型建议不是写回授权。
  5. 按宿主渠道打包、安装和测试,再申请发布;权限和商店要求跟随对应软件。

地址、认证与动作执行分别配置

DeepSeek 是模型服务提供方,聊天接口是应用发送问题的入口,密钥认证用来证明调用身份。接口地址必须与密钥所属平台匹配,不能把第三方网关密钥填进官方地址。

聊天接口格式
官方请求端点
请求头中的认证字段
Chat Completions(标准对话接口)
POST https://api.deepseek.com/chat/completionsAuthorization: Bearer <YOUR_API_KEY>
Responses(响应式接口)
POST https://api.deepseek.com/responsesAuthorization: Bearer <YOUR_API_KEY>
Messages(消息式接口)
POST https://api.deepseek.com/anthropic/v1/messagesx-api-key: <YOUR_API_KEY>

这些格式规定应用怎样提交问题和读取回答,不代表字段可以互换。开发 Agent 负责接入所选格式,密钥由人配置;模型名和工具声明也要与对应接口相符。

能力选择
谁执行动作
应用仍负责什么
普通生成
模型生成文字
读取范围、展示、确认写回
自定义工具
应用执行函数(实现动作的程序)
检查参数和权限,回传结果
服务端搜索、阅读链接
DeepSeek 服务器执行
资料发送授权、工具声明和费用
文件解析
服务端处理上传文件
批准上传,再以文件标识引用结果

若另一种软件还要调用官方服务端搜索或阅读链接,开发 Agent 要按所选接口格式使用官方工具声明,不能直接复制另一种格式的字段。这是可选接入,不是本地查询的必做步骤。

截至 2026 年 11 月 14 日,DeepSeek 官方对话应用扩展使用 deepseek-flash 这个模型调用名。它的搜索与阅读链接由 DeepSeek 服务端执行,不同于本案由应用自己执行的 project_query。

搜索和解析可能另行收费,也不替代软件授权。这条路线仍看实际读取、接口返回和写回记录;教学首版只做本地文本查询,不启用这些额外服务。

八、资料发送、费用和升级还要单独管理

即使功能测试通过,DSH 尚未接受安全审计,不能视为安全或生产可用。沙箱是限制部分动作的运行环境,工具审批和沙箱不能限制所有宿主插件及安装脚本,第三方代码仍可能以宿主权限运行。

只读查询不等于没有资料发送,也不等于回答免费。 本案目录检查只是业务限制,测试不能充当安全审计。

自定义日志与框架上传不是同一件事

查询函数本身不记录资料全文或密钥,这只是代码层面的约束。实际上,模型在整理工具返回的结果时,会把原文片段作为对话上下文发送给模型服务;此外 DSH 还有一条独立的会话日志上传通道(详见下方“资料发送按不同路径批准”),这两条路径都可能在你的插件代码之外把资料发出去。接入真实资料之前,应逐条核对并关闭不需要的发送路径。

资料发送按不同路径批准:

  • 模型请求:确认片段发往哪个服务,是否允许处理这些资料。
  • 会话日志:检查“设置→通用→在使用官方模型 API 时上传 Session Log”。Session Log 是会话记录,这个选项默认开启。开启状态下,下一次请求时会补发此前尚未确认上传的完整会话记录,其中可能包含对话内容和工具返回结果,不只是这次问话。
  • 反馈与遥测:反馈可能上传含消息和工具结果的日志,这条发送路径要另行核对。Agent 在获准的启动环境中设置 DSH_TELEMETRY_MODE=DISABLED,禁止这一路遥测发送,不会同时关闭官方模型会话日志贡献。

没有额外发送许可时,会话日志和反馈遥测两条路径分别关闭,不能以一个开关代替另一个。正常聊天请求仍可能包含资料片段,学习测试继续用虚构资料,不宣称彻底不发送。

模型运行方式
资料去向
额外责任
云 API
发给服务提供方
人批准发送范围,核服务条款和账单
本地部署
自管机器计算
向模型发布方确认使用许可,承担硬件与维护成本

密钥保存与实际用量决定费用管理

界面遮住密钥,不代表代码或日志没有泄露它。客户端指用户电脑上运行的网页或扩展,共享密钥不应随它分发。

密钥模式
保存原则
需要确认的风险
开发者共享密钥
放在受控服务器,不进客户端或发布包
服务器检查调用身份,防滥用
个人自填密钥
个人主动选择并承担风险
浏览器本地存储不是安全密钥库

费用按接口返回的实际用量记录核对,通常包含模型的输入和输出 token 数;如果使用了服务端搜索或文件解析等额外工具,还会产生独立的计费项。具体单价以 DeepSeek 官方当前价格页为准,不要按回答字数估算账单。DSH 本身不提供按密钥限制消费的功能,需要你自己跟踪累计费用并设置告警。

在 DeepSeek 官方对话应用扩展中,一次聊天任务可能多次生成和搜索。每次生成的输出长度限制不等于整个任务的账单上限;取消或超时,也不消除已经发生的计算和搜索费用。

单独调用独立搜索或抓取接口,是不伴随模型聊天、直接拿搜索或网页结果的场景。这个场景下失败或无结果不计费,不能据此推断失败的聊天任务免费;重试次数仍要限制,并核对实际用量。

聊天任务和单独搜索接口的计费规则不同: 聊天任务里取消也要付已发生的费用;单独调搜索接口时失败不计费。两者不冲突,区别在于是否伴随模型生成。

升级后重跑查询和安装测试

保留已验证版本、授权说明和虚构测试资料,升级先重跑查询验收,再安装发布包复测。失败时保留或回到已验证版本,不让 latest 或 next 自动改变交付环境;DSH 的 MIT 代码许可证也不替代模型服务条款。

未执行步骤如实保留,不以“完成”措辞当上线依据。第一版先查批准目录里的原文,让模型据结果回答,再凭文件和测试接受交付。人定范围和授权,Agent 实现并留证据;源码加载与安装包都要验收。

回首页,搜索你想要的文档

在首页搜索框输入关键词,快速定位资料

文库首页搜索指引 立即搜索

相关学习资料