在实际企业级应用开发中我们经常面临将内部工具或AI能力安全、便捷地集成到现有办公门户的需求。传统的集成方式如开发独立的微服务或编写复杂的API对接脚本不仅开发周期长而且后期维护、权限控制和用户交互体验都面临挑战。DeepSeek Harness简称DSH及其插件生态的出现为这类场景提供了一种新颖、高效的解决方案。它允许开发者将AI功能、数据处理工具或业务逻辑封装成标准的插件并一键发布到插件市场最终用户可以像安装手机App一样在DeepSeek Harness桌面端或Web门户中直接使用。本文将以一个假设的“政务数据简报生成”场景为例详细演示如何从零开始开发一个DSH插件并将其成功接入一个模拟的政务门户系统中。我们将涵盖从环境搭建、插件开发、本地调试、打包发布到门户集成的完整闭环。通过这个案例你将掌握DSH插件开发的核心流程、关键配置项以及在实际集成中可能遇到的典型问题及其解决方案。无论你是希望将内部AI工具产品化还是寻求更轻量级的系统集成方式本文都能提供一条清晰的实践路径。1. 理解 DeepSeek Harness 插件生态与政务门户集成架构在开始编码之前必须厘清几个核心概念和它们之间的协作关系。这能帮助你在后续步骤中理解每一个配置和代码片段的目的而不是机械地复制粘贴。1.1 DeepSeek Harness (DSH) 是什么DeepSeek Harness 是一个开源的AI应用开发与部署平台。你可以把它理解为一个“容器”或“运行时环境”专门用于托管和运行各种AI能力或工具化应用这些应用以“插件”的形式存在。DSH本身提供了插件管理、生命周期控制、资源隔离以及统一的前端交互框架。开发者无需从零构建一个完整的Web应用只需关注插件的核心业务逻辑。1.2 DSH 插件是什么一个DSH插件就是一个符合其规范的项目包。它通常包含业务逻辑代码用Python、Node.js等语言编写的核心功能。插件声明文件 (plugin.yaml)描述插件的元信息如名称、版本、入口命令、配置参数、前端组件等。前端UI组件可选如果插件需要用户界面可以提供Vue/React组件。依赖声明文件如requirements.txt或package.json。插件被安装到DSH后DSH会为其创建独立的运行环境并负责调用其声明的命令或渲染其UI。1.3 “接入政务门户”意味着什么这里的“政务门户”是一个泛指可以是任何内部OA系统、统一工作台或信息门户。接入方式通常不是直接修改门户源码而是通过以下两种模式嵌入式集成在门户的某个页面内通过 iframe 或 Web Components 嵌入 DSH 桌面端的特定插件页面。门户负责身份认证和权限传递DSH负责插件的渲染和执行。链接跳转在门户上放置一个链接点击后在新窗口或标签页中打开 DSH 桌面端并直接定位到该插件界面。本文重点演示第一种更深度集成的模式。其技术链路可以概括为政务门户 (前端) --[携带Token]-- DSH 桌面端/服务 --[加载并运行]-- 你的插件整个流程的关键在于门户与DSH之间的安全认证如JWT Token传递以及DSH对插件的正确加载。1.4 开发前需要明确的几个问题目标用户是政务内部工作人员他们对插件的稳定性、安全性和易用性要求极高。插件类型你的插件是提供API服务无UI还是需要一个交互界面本文案例是一个带有简单UI的数据处理插件。部署环境DSH是部署在内部服务器还是云端这影响到后续的网络配置和访问地址。2. 环境准备与项目初始化一个顺畅的开发环境能避免很多后续的诡异问题。请严格按照顺序操作。2.1 基础环境检查与安装你需要准备以下工具并确认版本兼容性。建议使用版本管理工具如nvm、pyenv来保持环境纯净。工具推荐版本作用验证命令Node.js18.x 或 20.x (LTS)运行DSH桌面端及前端工具链node --versionpnpm8.0.0推荐使用的包管理器比npm更快、更节省磁盘pnpm --versionPython3.8 - 3.11编写插件后端逻辑如果插件使用Pythonpython --versionGit最新版代码版本管理git --version安装DSH命令行工具DSH CLI它是开发、调试、管理插件的核心。# 使用 pnpm 全局安装 dsh-cli pnpm add -g deepeek/dsh-cli # 安装完成后验证安装是否成功 dsh --version如果出现‘dsh’ 不是内部或外部命令的错误请将pnpm的全局bin目录通常为~/.local/share/pnpm/global/5/node_modules/.bin或类似路径添加到系统的PATH环境变量中。2.2 创建你的第一个插件项目DSH CLI 提供了项目脚手架可以快速生成一个结构规范的插件项目。# 创建一个目录用于存放你的插件项目 mkdir my-gov-plugin cd my-gov-plugin # 使用 dsh cli 初始化插件项目 # 你会被交互式地询问插件名称、描述、类型等信息 dsh plugin init根据提示进行选择例如Plugin name:gov-data-briefingDescription:A plugin to generate daily briefing reports from government data.Plugin type: 选择Basic(基础插件包含前后端示例) 或根据需求选择其他模板。Language: 选择Python或Node.js本文以Python为例。初始化完成后你会得到一个类似如下的目录结构gov-data-briefing/ ├── plugin.yaml # 插件核心声明文件 ├── pyproject.toml # Python项目依赖管理 (如果选Python) ├── src/ │ ├── backend/ # 后端逻辑代码 │ │ └── main.py │ └── frontend/ # 前端UI代码 (如果选带UI的模板) │ ├── App.vue │ └── index.js ├── webpack.config.js # 前端构建配置 └── README.md2.3 理解核心文件plugin.yamlplugin.yaml是插件的“身份证”和“说明书”DSH完全依据这个文件来管理插件。打开它你会看到如下内容具体内容因模板而异# plugin.yaml 示例 name: gov-data-briefing version: 0.1.0 description: A plugin to generate daily briefing reports from government data. author: Your Name your.emailexample.com runtime: type: python version: 3.8 command: python src/backend/main.py # 插件启动命令 frontend: type: vue path: src/frontend port: 3000 # 前端开发服务器端口 permissions: - network # 声明插件需要网络权限 configs: - key: API_ENDPOINT name: 数据API地址 type: string default: http://internal-data.gov/api required: true关键字段解释runtime: 定义了插件的运行环境。command是DSH启动插件进程时执行的命令。frontend: 如果插件有UI这里定义了前端类型、路径和开发端口。DSH在开发模式下会代理这个端口的请求。permissions:安全关键项。插件默认在沙箱中运行无权访问网络、文件系统等。这里声明network插件才能调用外部API如访问政务数据接口。configs: 定义了插件可配置的参数。用户可以在DSH插件管理界面修改这些值插件代码中可以通过环境变量读取。这对于区分测试和生产环境非常有用。3. 开发政务数据简报生成插件现在我们开始为这个插件填充实际业务逻辑。假设场景是插件从内部政务数据API拉取当日关键指标通过AI模型或规则引擎生成一份文本简报并提供给用户查看和下载。3.1 编写后端逻辑 (Python示例)编辑src/backend/main.py。一个最简单的DSH插件后端是一个长期运行的HTTP服务器DSH会向其发送请求。# src/backend/main.py import os import json import logging from http.server import HTTPServer, BaseHTTPRequestHandler import requests from urllib.parse import urlparse, parse_qs # 配置日志方便在DSH控制台查看 logging.basicConfig(levellogging.INFO, format%(asctime)s - %(name)s - %(levelname)s - %(message)s) logger logging.getLogger(__name__) # 从 plugin.yaml 的 configs 中读取配置 API_ENDPOINT os.getenv(API_ENDPOINT, http://default-endpoint) API_TOKEN os.getenv(API_TOKEN, ) # 假设还有一个配置项用于认证 class PluginRequestHandler(BaseHTTPRequestHandler): def do_GET(self): 处理前端GET请求例如获取简报 parsed_path urlparse(self.path) if parsed_path.path /api/briefing: # 1. 调用政务数据API try: headers {Authorization: fBearer {API_TOKEN}} response requests.get(f{API_ENDPOINT}/daily-metrics, headersheaders, timeout10) response.raise_for_status() data response.json() logger.info(f成功获取数据: {data}) except requests.exceptions.RequestException as e: logger.error(f调用数据API失败: {e}) self.send_response(500) self.end_headers() self.wfile.write(json.dumps({error: 数据服务不可用}).encode()) return # 2. 模拟简报生成逻辑 (实际项目中可能调用LLM) briefing_text f 政务数据简报 ({data.get(date, N/A)}) ---------------------------- 今日新增事项: {data.get(new_cases, 0)} 件 办结事项: {data.get(closed_cases, 0)} 件 平均处理时长: {data.get(avg_duration, 0)} 小时 重点关注区域: {, .join(data.get(hot_areas, []))} # 3. 返回结果给前端 self.send_response(200) self.send_header(Content-Type, application/json) self.end_headers() self.wfile.write(json.dumps({briefing: briefing_text, rawData: data}).encode()) else: self.send_response(404) self.end_headers() def do_POST(self): 处理前端POST请求例如触发简报生成并存储 if self.path /api/generate: content_length int(self.headers[Content-Length]) post_data self.rfile.read(content_length) # ... 处理逻辑 ... self.send_response(200) self.send_header(Content-Type, application/json) self.end_headers() self.wfile.write(json.dumps({status: success}).encode()) else: self.send_response(404) self.end_headers() def log_message(self, format, *args): # 将HTTP日志也集成到我们的logger中 logger.info(%s - %s % (self.address_string(), format%args)) if __name__ __main__: server_port int(os.getenv(PORT, 7860)) # DSH会通过PORT环境变量告知监听端口 server HTTPServer((localhost, server_port), PluginRequestHandler) logger.info(f启动插件后端服务器端口: {server_port}) logger.info(f配置的数据API地址: {API_ENDPOINT}) server.serve_forever()关键点说明环境变量API_ENDPOINT和API_TOKEN是从plugin.yaml的configs注入的。这是插件配置化的关键。HTTP Server插件后端需要启动一个HTTP服务器来接收DSH前端或直接调用的请求。DSH负责将外部请求路由到这个服务器的端口。日志使用logging模块输出日志至关重要。你可以在DSH桌面端的“插件日志”面板中查看这些日志这是最重要的调试手段。错误处理务必对网络请求、数据解析等可能失败的操作进行try-except捕获并返回友好的错误信息避免插件进程崩溃。3.2 编写前端界面 (Vue 3示例)编辑src/frontend/App.vue。前端负责与用户交互并通过调用后端API获取数据。!-- src/frontend/App.vue -- template div classplugin-container h1政务数据简报生成器/h1 el-button typeprimary clickfetchBriefing :loadingloading 生成今日简报 /el-button div v-iferror classerror-message {{ error }} /div div v-ifbriefing classbriefing-result h3生成结果/h3 pre{{ briefing }}/pre el-button sizesmall clickdownloadBriefing下载简报文本/el-button h4原始数据/h4 pre{{ rawData }}/pre /div /div /template script setup import { ref } from vue import { ElButton, ElMessage } from element-plus // 假设使用Element Plus UI库 const briefing ref() const rawData ref(null) const loading ref(false) const error ref() const fetchBriefing async () { loading.value true error.value briefing.value rawData.value null try { // 关键这里请求的是相对路径 /api/briefing。 // 在DSH运行时这个请求会被自动代理到插件后端的本地端口。 const response await fetch(/api/briefing) if (!response.ok) { throw new Error(HTTP error! status: ${response.status}) } const data await response.json() briefing.value data.briefing rawData.value data.rawData ElMessage.success(简报生成成功) } catch (err) { console.error(获取简报失败:, err) error.value 获取简报失败: ${err.message}。请检查网络连接或插件后端日志。 ElMessage.error(简报生成失败) } finally { loading.value false } } const downloadBriefing () { if (!briefing.value) return const blob new Blob([briefing.value], { type: text/plain }) const url URL.createObjectURL(blob) const a document.createElement(a) a.href url a.download 政务简报_${new Date().toLocaleDateString()}.txt document.body.appendChild(a) a.click() document.body.removeChild(a) URL.revokeObjectURL(url) } /script style scoped .plugin-container { padding: 20px; } .error-message { color: #f56c6c; margin-top: 10px; padding: 10px; background-color: #fef0f0; border-radius: 4px; } .briefing-result { margin-top: 20px; text-align: left; } pre { white-space: pre-wrap; background-color: #f5f7fa; padding: 10px; border-radius: 4px; font-family: monospace; } /style关键点说明API代理前端代码中请求/api/briefing而不是http://localhost:7860/api/briefing。这是因为在DSH开发和生产模式下它会自动创建一个反向代理将前端对/api的请求转发到插件后端的实际端口。这解决了跨域问题是DSH插件开发的核心机制之一。UI库示例中使用了element-plus你需要在src/frontend目录下安装它 (pnpm add element-plus)。你也可以使用任何其他Vue/React UI库或纯CSS。错误反馈通过error变量和ElMessage向用户清晰反馈操作状态这是良好用户体验的基础。3.3 安装依赖并本地运行前后端代码完成后需要安装依赖并启动本地开发服务器进行测试。# 在插件项目根目录下 # 1. 安装前端依赖 (如果前端目录有 package.json) cd src/frontend pnpm install cd ../.. # 2. 安装Python后端依赖 (如果使用Python) # 确保在项目根目录或 backend 目录下有 requirements.txt # 示例 requirements.txt 内容 # requests2.28.0 pip install -r requirements.txt # 3. 启动插件开发模式 dsh plugin dev执行dsh plugin dev后CLI 会做几件事读取plugin.yaml。启动插件后端进程执行python src/backend/main.py。启动前端开发服务器例如在http://localhost:3000。在DSH桌面端如果已安装并运行或浏览器中打开一个调试窗口加载你的插件前端页面。此时你应该能在DSH桌面端的“本地插件”列表中看到gov-data-briefing并可以点击运行。尝试点击“生成今日简报”按钮观察后端日志和前端响应。4. 插件调试、打包与发布到市场本地运行无误后下一步是将其打包成可分发的格式并发布到DSH插件市场或私有仓库以便其他用户安装。4.1 调试与问题排查在开发过程中你一定会遇到问题。请按以下顺序排查问题现象可能原因检查点与解决方案dsh plugin dev启动失败1.plugin.yaml语法错误。2. 依赖未安装。3. 端口被占用。1. 使用YAML校验器检查plugin.yaml。2. 确保已运行pnpm install和pip install。3. 检查frontend.port和runtime.command中指定的端口是否空闲。前端页面空白或报错1. 前端依赖缺失或构建失败。2. 代理配置错误前端请求无法到达后端。1. 查看浏览器开发者工具 Console 和 Network 面板。2. 检查dsh plugin dev启动日志确认前端服务器是否成功启动。3. 尝试直接访问前端开发服务器地址如http://localhost:3000。点击按钮前端报“Network Error”或“404”1. 后端服务器未启动。2. 后端API路由与前端请求不匹配。3. 插件权限不足。1. 查看dsh plugin dev终端日志确认后端进程是否在运行且无报错。2. 核对前端fetch(‘/api/briefing’)和后端do_GET(‘/api/briefing’)路径是否完全一致。3. 检查plugin.yaml中的permissions是否包含了network如果需要访问外部API。后端日志显示“Connection refused”访问外部API失败1. 网络不通。2. 环境变量未正确注入。3. API需要认证。1. 在后端代码中打印os.getenv(‘API_ENDPOINT’)确认值是否正确。2. 在DSH插件管理界面检查该插件的配置项是否已填写。3. 使用curl或requests在插件环境外手动测试API连通性。插件在DSH中运行正常但接入门户后无法使用1. 门户与DSH的跨域问题。2. 门户传递的认证信息DSH未识别。3. DSH服务地址配置错误。1. 这是集成阶段最常见问题详见第5节。最重要的调试工具是日志。始终确保你的后端代码有充分的日志输出并在DSH桌面端的“插件日志”面板中仔细查看。4.2 打包插件当插件开发测试完成需要打包成一个.dsh-plugin文件本质上是一个zip压缩包便于分发和安装。# 在插件项目根目录执行打包命令 dsh plugin pack该命令会运行前端构建如果存在生成静态文件到dist目录。将plugin.yaml、构建后的前端文件、后端源代码或根据配置排除某些文件一起打包。在项目根目录生成一个类似gov-data-briefing-0.1.0.dsh-plugin的文件。4.3 发布到插件市场你可以将插件发布到官方市场或私有市场。# 1. 登录到DSH插件市场 (需要账户) dsh plugin login # 2. 发布插件 dsh plugin publish ./gov-data-briefing-0.1.0.dsh-plugin发布前请务必更新plugin.yaml中的version字段。编写清晰的README.md说明插件功能、配置方法和注意事项。在插件市场管理后台为插件设置合适的分类、标签和截图。对于政务内部系统你更可能需要搭建私有插件市场。这通常涉及部署一个符合DSH插件市场协议的服务器并将DSH桌面端的市场地址指向它。具体步骤请参考DSH官方文档中关于私有部署的部分。5. 将插件集成到政务门户这是最后也是最关键的一步让插件在门户系统中可用。5.1 集成模式选择模式描述优点缺点适用场景Iframe 嵌入在门户页面中通过iframe标签嵌入 DSH 桌面端中该插件的专属URL。实现简单隔离性好插件更新独立于门户。存在跨域限制需要处理登录态传递UI风格可能与门户不统一。快速集成对UI一致性要求不高的内部工具。API 直调门户后端直接调用已部署的DSH插件提供的API需插件暴露API。性能好门户可完全控制交互逻辑。需要插件设计为纯后端服务门户需自己开发前端界面。插件核心是数据处理能力无需复杂UI。微前端架构将插件前端构建为微前端模块门户通过微前端框架加载。UI融合度最高体验最佳。技术复杂度高需要改造门户和插件前端。大型、长期的项目对用户体验要求极高。本文以最常用的Iframe 嵌入为例。5.2 Iframe 嵌入实战步骤前提DSH桌面端或服务已部署在内部网络地址为https://dsh.internal.gov。你的插件gov-data-briefing已安装并配置好。步骤一在门户页面添加Iframe!-- 在门户的某个.vue/.jsx/.html文件中 -- div classtool-card h3每日数据简报/h3 iframe refpluginFrame :srcpluginUrl width100% height600px frameborder0 allowclipboard-write; loadonIframeLoad /iframe div v-ifloading加载插件中.../div /div步骤二处理认证与URL生成门户用户登录后会有一个身份令牌如JWT。需要将这个令牌安全地传递给DSH。// 在门户前端逻辑中 import { getCurrentUserToken } from /utils/auth; // 假设有获取用户Token的方法 export default { data() { return { pluginUrl: , loading: true }; }, mounted() { this.initPluginFrame(); }, methods: { async initPluginFrame() { const userToken getCurrentUserToken(); // 构造DSH插件URL。格式通常为DSH地址 /plugins/ 插件ID /?token... // 具体格式需参考DSH的嵌入文档或API。 this.pluginUrl https://dsh.internal.gov/plugins/gov-data-briefing/?embedtruetoken${encodeURIComponent(userToken)}; }, onIframeLoad() { this.loading false; // 可以在这里建立与iframe内插件的通信例如使用 postMessage // this.$refs.pluginFrame.contentWindow.postMessage({ type: init }, *); } } };关键安全考虑Token传递切勿使用URL参数传递高敏感Token除非DSH和门户在同一顶级域名下并使用安全的SameSite Cookie。更安全的方式是门户后端与DSH后端通过OAuth 2.0等协议进行服务间认证为每个会话生成一个短期有效的嵌入令牌。同源策略如果dsh.internal.gov与门户不同源iframe通信会受到限制。需要DSH服务端设置正确的CORS头部 (Access-Control-Allow-Origin) 和X-Frame-Options。步骤三DSH服务端配置确保DSH服务端或网关能够验证门户传来的Token并识别用户身份从而在插件运行时注入正确的用户上下文和权限。这通常需要在DSH的部署配置中启用并配置相应的认证中间件。5.3 集成后常见问题排查问题排查方向Iframe 显示“无法连接”或空白1. 检查pluginUrl是否正确能否在浏览器单独访问。2. 检查DSH服务是否健康运行。3. 检查网络策略门户页面能否访问DSH的域名和端口。Iframe 显示“未授权”或“请登录”1. Token未传递或已过期。2. DSH服务端未正确配置该Token的验证方式。3. 该用户无权访问此插件需在DSH中配置插件权限。插件功能异常如无法调用API1. 在DSH桌面端直接运行插件是否正常如果正常问题出在集成环境。2. 检查插件在集成环境下运行时的日志看环境变量如API_ENDPOINT是否正确注入。3. 可能是集成环境与开发环境的网络策略不同导致插件无法访问外部政务数据API。6. 生产环境部署与最佳实践将插件从开发环境推向生产环境需要额外的考量。6.1 配置管理分离配置所有环境相关的配置API地址、密钥、数据库连接必须通过plugin.yaml的configs定义并通过环境变量注入。绝对不要硬编码在代码中。使用密钥管理对于密码、Token等敏感信息应使用DSH提供的密钥管理功能或对接外部密钥管理服务如HashiCorp Vault而不是以明文存储在配置界面。6.2 安全性加固权限最小化在plugin.yaml的permissions中只声明插件运行所必需的最小权限。例如不需要文件读写就不要声明filesystem。输入验证与消毒插件后端必须对所有输入包括来自前端的参数和外部API的响应进行严格的验证和消毒防止注入攻击。依赖扫描定期使用pip-audit,npm audit等工具扫描项目依赖的安全漏洞并及时更新。6.3 可观测性与监控结构化日志确保插件输出结构化的日志JSON格式便于被ELK、Loki等日志系统采集和分析。在日志中记录请求ID、用户ID、关键操作步骤和错误详情。健康检查端点为插件后端添加一个/health端点返回服务状态。这便于容器编排平台如Kubernetes或DSH本身进行健康检查。指标暴露考虑使用Prometheus客户端库暴露插件的关键指标如请求数、延迟、错误率方便监控。6.4 版本与更新语义化版本严格遵守语义化版本控制SemVer。plugin.yaml中的version字段在修复Bug时递增修订号在新增向后兼容的功能时递增次版本号在做出不兼容的变更时递增主版本号。变更日志维护CHANGELOG.md清晰记录每个版本的变更内容特别是破坏性变更和配置项变更。向后兼容更新插件时尽量保持API的向后兼容性。如果必须做出破坏性变更应提供迁移指南并在插件市场中明确标注。通过以上步骤你不仅完成了一个DSH插件的开发更掌握了一套将内部能力快速产品化并集成到现有系统的工程方法。这种插件化思维能够极大地提升团队交付工具的效率和标准化程度。