實(shí)戰(zhàn)：從零構(gòu)建政務(wù)數(shù)據(jù)簡(jiǎn)報(bào)生成工具)
在實(shí)際企業(yè)級(jí)應(yīng)用開發(fā)中我們經(jīng)常面臨將內(nèi)部工具或AI能力安全、便捷地集成到現(xiàn)有辦公門戶的需求。傳統(tǒng)的集成方式如開發(fā)獨(dú)立的微服務(wù)或編寫復(fù)雜的API對(duì)接腳本不僅開發(fā)周期長(zhǎng)而且后期維護(hù)、權(quán)限控制和用戶交互體驗(yàn)都面臨挑戰(zhàn)。DeepSeek Harness簡(jiǎn)稱DSH及其插件生態(tài)的出現(xiàn)為這類場(chǎng)景提供了一種新穎、高效的解決方案。它允許開發(fā)者將AI功能、數(shù)據(jù)處理工具或業(yè)務(wù)邏輯封裝成標(biāo)準(zhǔn)的插件并一鍵發(fā)布到插件市場(chǎng)最終用戶可以像安裝手機(jī)App一樣在DeepSeek Harness桌面端或Web門戶中直接使用。本文將以一個(gè)假設(shè)的“政務(wù)數(shù)據(jù)簡(jiǎn)報(bào)生成”場(chǎng)景為例詳細(xì)演示如何從零開始開發(fā)一個(gè)DSH插件并將其成功接入一個(gè)模擬的政務(wù)門戶系統(tǒng)中。我們將涵蓋從環(huán)境搭建、插件開發(fā)、本地調(diào)試、打包發(fā)布到門戶集成的完整閉環(huán)。通過這個(gè)案例你將掌握DSH插件開發(fā)的核心流程、關(guān)鍵配置項(xiàng)以及在實(shí)際集成中可能遇到的典型問題及其解決方案。無(wú)論你是希望將內(nèi)部AI工具產(chǎn)品化還是尋求更輕量級(jí)的系統(tǒng)集成方式本文都能提供一條清晰的實(shí)踐路徑。1. 理解 DeepSeek Harness 插件生態(tài)與政務(wù)門戶集成架構(gòu)在開始編碼之前必須厘清幾個(gè)核心概念和它們之間的協(xié)作關(guān)系。這能幫助你在后續(xù)步驟中理解每一個(gè)配置和代碼片段的目的而不是機(jī)械地復(fù)制粘貼。1.1 DeepSeek Harness (DSH) 是什么DeepSeek Harness 是一個(gè)開源的AI應(yīng)用開發(fā)與部署平臺(tái)。你可以把它理解為一個(gè)“容器”或“運(yùn)行時(shí)環(huán)境”專門用于托管和運(yùn)行各種AI能力或工具化應(yīng)用這些應(yīng)用以“插件”的形式存在。DSH本身提供了插件管理、生命周期控制、資源隔離以及統(tǒng)一的前端交互框架。開發(fā)者無(wú)需從零構(gòu)建一個(gè)完整的Web應(yīng)用只需關(guān)注插件的核心業(yè)務(wù)邏輯。1.2 DSH 插件是什么一個(gè)DSH插件就是一個(gè)符合其規(guī)范的項(xiàng)目包。它通常包含業(yè)務(wù)邏輯代碼用Python、Node.js等語(yǔ)言編寫的核心功能。插件聲明文件 (plugin.yaml)描述插件的元信息如名稱、版本、入口命令、配置參數(shù)、前端組件等。前端UI組件可選如果插件需要用戶界面可以提供Vue/React組件。依賴聲明文件如requirements.txt或package.json。插件被安裝到DSH后DSH會(huì)為其創(chuàng)建獨(dú)立的運(yùn)行環(huán)境并負(fù)責(zé)調(diào)用其聲明的命令或渲染其UI。1.3 “接入政務(wù)門戶”意味著什么這里的“政務(wù)門戶”是一個(gè)泛指可以是任何內(nèi)部OA系統(tǒng)、統(tǒng)一工作臺(tái)或信息門戶。接入方式通常不是直接修改門戶源碼而是通過以下兩種模式嵌入式集成在門戶的某個(gè)頁(yè)面內(nèi)通過 iframe 或 Web Components 嵌入 DSH 桌面端的特定插件頁(yè)面。門戶負(fù)責(zé)身份認(rèn)證和權(quán)限傳遞DSH負(fù)責(zé)插件的渲染和執(zhí)行。鏈接跳轉(zhuǎn)在門戶上放置一個(gè)鏈接點(diǎn)擊后在新窗口或標(biāo)簽頁(yè)中打開 DSH 桌面端并直接定位到該插件界面。本文重點(diǎn)演示第一種更深度集成的模式。其技術(shù)鏈路可以概括為政務(wù)門戶 (前端) --[攜帶Token]-- DSH 桌面端/服務(wù) --[加載并運(yùn)行]-- 你的插件整個(gè)流程的關(guān)鍵在于門戶與DSH之間的安全認(rèn)證如JWT Token傳遞以及DSH對(duì)插件的正確加載。1.4 開發(fā)前需要明確的幾個(gè)問題目標(biāo)用戶是政務(wù)內(nèi)部工作人員他們對(duì)插件的穩(wěn)定性、安全性和易用性要求極高。插件類型你的插件是提供API服務(wù)無(wú)UI還是需要一個(gè)交互界面本文案例是一個(gè)帶有簡(jiǎn)單UI的數(shù)據(jù)處理插件。部署環(huán)境DSH是部署在內(nèi)部服務(wù)器還是云端這影響到后續(xù)的網(wǎng)絡(luò)配置和訪問地址。2. 環(huán)境準(zhǔn)備與項(xiàng)目初始化一個(gè)順暢的開發(fā)環(huán)境能避免很多后續(xù)的詭異問題。請(qǐng)嚴(yán)格按照順序操作。2.1 基礎(chǔ)環(huán)境檢查與安裝你需要準(zhǔn)備以下工具并確認(rèn)版本兼容性。建議使用版本管理工具如nvm、pyenv來(lái)保持環(huán)境純凈。工具推薦版本作用驗(yàn)證命令Node.js18.x 或 20.x (LTS)運(yùn)行DSH桌面端及前端工具鏈node --versionpnpm8.0.0推薦使用的包管理器比npm更快、更節(jié)省磁盤pnpm --versionPython3.8 - 3.11編寫插件后端邏輯如果插件使用Pythonpython --versionGit最新版代碼版本管理git --version安裝DSH命令行工具DSH CLI它是開發(fā)、調(diào)試、管理插件的核心。# 使用 pnpm 全局安裝 dsh-cli pnpm add -g deepeek/dsh-cli # 安裝完成后驗(yàn)證安裝是否成功 dsh --version如果出現(xiàn)‘dsh’ 不是內(nèi)部或外部命令的錯(cuò)誤請(qǐng)將pnpm的全局bin目錄通常為~/.local/share/pnpm/global/5/node_modules/.bin或類似路徑添加到系統(tǒng)的PATH環(huán)境變量中。2.2 創(chuàng)建你的第一個(gè)插件項(xiàng)目DSH CLI 提供了項(xiàng)目腳手架可以快速生成一個(gè)結(jié)構(gòu)規(guī)范的插件項(xiàng)目。# 創(chuàng)建一個(gè)目錄用于存放你的插件項(xiàng)目 mkdir my-gov-plugin cd my-gov-plugin # 使用 dsh cli 初始化插件項(xiàng)目 # 你會(huì)被交互式地詢問插件名稱、描述、類型等信息 dsh plugin init根據(jù)提示進(jìn)行選擇例如Plugin name:gov-data-briefingDescription:A plugin to generate daily briefing reports from government data.Plugin type: 選擇Basic(基礎(chǔ)插件包含前后端示例) 或根據(jù)需求選擇其他模板。Language: 選擇Python或Node.js本文以Python為例。初始化完成后你會(huì)得到一個(gè)類似如下的目錄結(jié)構(gòu)gov-data-briefing/ ├── plugin.yaml # 插件核心聲明文件 ├── pyproject.toml # Python項(xiàng)目依賴管理 (如果選Python) ├── src/ │ ├── backend/ # 后端邏輯代碼 │ │ └── main.py │ └── frontend/ # 前端UI代碼 (如果選帶UI的模板) │ ├── App.vue │ └── index.js ├── webpack.config.js # 前端構(gòu)建配置 └── README.md2.3 理解核心文件plugin.yamlplugin.yaml是插件的“身份證”和“說明書”DSH完全依據(jù)這個(gè)文件來(lái)管理插件。打開它你會(huì)看到如下內(nèi)容具體內(nèi)容因模板而異# 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 # 插件啟動(dòng)命令 frontend: type: vue path: src/frontend port: 3000 # 前端開發(fā)服務(wù)器端口 permissions: - network # 聲明插件需要網(wǎng)絡(luò)權(quán)限 configs: - key: API_ENDPOINT name: 數(shù)據(jù)API地址 type: string default: http://internal-data.gov/api required: true關(guān)鍵字段解釋runtime: 定義了插件的運(yùn)行環(huán)境。command是DSH啟動(dòng)插件進(jìn)程時(shí)執(zhí)行的命令。frontend: 如果插件有UI這里定義了前端類型、路徑和開發(fā)端口。DSH在開發(fā)模式下會(huì)代理這個(gè)端口的請(qǐng)求。permissions:安全關(guān)鍵項(xiàng)。插件默認(rèn)在沙箱中運(yùn)行無(wú)權(quán)訪問網(wǎng)絡(luò)、文件系統(tǒng)等。這里聲明network插件才能調(diào)用外部API如訪問政務(wù)數(shù)據(jù)接口。configs: 定義了插件可配置的參數(shù)。用戶可以在DSH插件管理界面修改這些值插件代碼中可以通過環(huán)境變量讀取。這對(duì)于區(qū)分測(cè)試和生產(chǎn)環(huán)境非常有用。3. 開發(fā)政務(wù)數(shù)據(jù)簡(jiǎn)報(bào)生成插件現(xiàn)在我們開始為這個(gè)插件填充實(shí)際業(yè)務(wù)邏輯。假設(shè)場(chǎng)景是插件從內(nèi)部政務(wù)數(shù)據(jù)API拉取當(dāng)日關(guān)鍵指標(biāo)通過AI模型或規(guī)則引擎生成一份文本簡(jiǎn)報(bào)并提供給用戶查看和下載。3.1 編寫后端邏輯 (Python示例)編輯src/backend/main.py。一個(gè)最簡(jiǎn)單的DSH插件后端是一個(gè)長(zhǎng)期運(yùn)行的HTTP服務(wù)器DSH會(huì)向其發(fā)送請(qǐng)求。# 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控制臺(tái)查看 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, ) # 假設(shè)還有一個(gè)配置項(xiàng)用于認(rèn)證 class PluginRequestHandler(BaseHTTPRequestHandler): def do_GET(self): 處理前端GET請(qǐng)求例如獲取簡(jiǎn)報(bào) parsed_path urlparse(self.path) if parsed_path.path /api/briefing: # 1. 調(diào)用政務(wù)數(shù)據(jù)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成功獲取數(shù)據(jù): {data}) except requests.exceptions.RequestException as e: logger.error(f調(diào)用數(shù)據(jù)API失敗: {e}) self.send_response(500) self.end_headers() self.wfile.write(json.dumps({error: 數(shù)據(jù)服務(wù)不可用}).encode()) return # 2. 模擬簡(jiǎn)報(bào)生成邏輯 (實(shí)際項(xiàng)目中可能調(diào)用LLM) briefing_text f 政務(wù)數(shù)據(jù)簡(jiǎn)報(bào) ({data.get(date, N/A)}) ---------------------------- 今日新增事項(xiàng): {data.get(new_cases, 0)} 件 辦結(jié)事項(xiàng): {data.get(closed_cases, 0)} 件 平均處理時(shí)長(zhǎng): {data.get(avg_duration, 0)} 小時(shí) 重點(diǎn)關(guān)注區(qū)域: {, .join(data.get(hot_areas, []))} # 3. 返回結(jié)果給前端 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請(qǐng)求例如觸發(fā)簡(jiǎn)報(bào)生成并存儲(chǔ) 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會(huì)通過PORT環(huán)境變量告知監(jiān)聽端口 server HTTPServer((localhost, server_port), PluginRequestHandler) logger.info(f啟動(dòng)插件后端服務(wù)器端口: {server_port}) logger.info(f配置的數(shù)據(jù)API地址: {API_ENDPOINT}) server.serve_forever()關(guān)鍵點(diǎn)說明環(huán)境變量API_ENDPOINT和API_TOKEN是從plugin.yaml的configs注入的。這是插件配置化的關(guān)鍵。HTTP Server插件后端需要啟動(dòng)一個(gè)HTTP服務(wù)器來(lái)接收DSH前端或直接調(diào)用的請(qǐng)求。DSH負(fù)責(zé)將外部請(qǐng)求路由到這個(gè)服務(wù)器的端口。日志使用logging模塊輸出日志至關(guān)重要。你可以在DSH桌面端的“插件日志”面板中查看這些日志這是最重要的調(diào)試手段。錯(cuò)誤處理務(wù)必對(duì)網(wǎng)絡(luò)請(qǐng)求、數(shù)據(jù)解析等可能失敗的操作進(jìn)行try-except捕獲并返回友好的錯(cuò)誤信息避免插件進(jìn)程崩潰。3.2 編寫前端界面 (Vue 3示例)編輯src/frontend/App.vue。前端負(fù)責(zé)與用戶交互并通過調(diào)用后端API獲取數(shù)據(jù)。!-- src/frontend/App.vue -- template div classplugin-container h1政務(wù)數(shù)據(jù)簡(jiǎn)報(bào)生成器/h1 el-button typeprimary clickfetchBriefing :loadingloading 生成今日簡(jiǎn)報(bào) /el-button div v-iferror classerror-message {{ error }} /div div v-ifbriefing classbriefing-result h3生成結(jié)果/h3 pre{{ briefing }}/pre el-button sizesmall clickdownloadBriefing下載簡(jiǎn)報(bào)文本/el-button h4原始數(shù)據(jù)/h4 pre{{ rawData }}/pre /div /div /template script setup import { ref } from vue import { ElButton, ElMessage } from element-plus // 假設(shè)使用Element Plus UI庫(kù) 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 { // 關(guān)鍵這里請(qǐng)求的是相對(duì)路徑 /api/briefing。 // 在DSH運(yùn)行時(shí)這個(gè)請(qǐng)求會(huì)被自動(dòng)代理到插件后端的本地端口。 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(簡(jiǎn)報(bào)生成成功) } catch (err) { console.error(獲取簡(jiǎn)報(bào)失敗:, err) error.value 獲取簡(jiǎn)報(bào)失敗: ${err.message}。請(qǐng)檢查網(wǎng)絡(luò)連接或插件后端日志。 ElMessage.error(簡(jiǎn)報(bào)生成失敗) } 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 政務(wù)簡(jiǎn)報(bào)_${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關(guān)鍵點(diǎn)說明API代理前端代碼中請(qǐng)求/api/briefing而不是http://localhost:7860/api/briefing。這是因?yàn)樵贒SH開發(fā)和生產(chǎn)模式下它會(huì)自動(dòng)創(chuàng)建一個(gè)反向代理將前端對(duì)/api的請(qǐng)求轉(zhuǎn)發(fā)到插件后端的實(shí)際端口。這解決了跨域問題是DSH插件開發(fā)的核心機(jī)制之一。UI庫(kù)示例中使用了element-plus你需要在src/frontend目錄下安裝它 (pnpm add element-plus)。你也可以使用任何其他Vue/React UI庫(kù)或純CSS。錯(cuò)誤反饋通過error變量和ElMessage向用戶清晰反饋操作狀態(tài)這是良好用戶體驗(yàn)的基礎(chǔ)。3.3 安裝依賴并本地運(yùn)行前后端代碼完成后需要安裝依賴并啟動(dòng)本地開發(fā)服務(wù)器進(jìn)行測(cè)試。# 在插件項(xiàng)目根目錄下 # 1. 安裝前端依賴 (如果前端目錄有 package.json) cd src/frontend pnpm install cd ../.. # 2. 安裝Python后端依賴 (如果使用Python) # 確保在項(xiàng)目根目錄或 backend 目錄下有 requirements.txt # 示例 requirements.txt 內(nèi)容 # requests2.28.0 pip install -r requirements.txt # 3. 啟動(dòng)插件開發(fā)模式 dsh plugin dev執(zhí)行dsh plugin dev后CLI 會(huì)做幾件事讀取plugin.yaml。啟動(dòng)插件后端進(jìn)程執(zhí)行python src/backend/main.py。啟動(dòng)前端開發(fā)服務(wù)器例如在http://localhost:3000。在DSH桌面端如果已安裝并運(yùn)行或?yàn)g覽器中打開一個(gè)調(diào)試窗口加載你的插件前端頁(yè)面。此時(shí)你應(yīng)該能在DSH桌面端的“本地插件”列表中看到gov-data-briefing并可以點(diǎn)擊運(yùn)行。嘗試點(diǎn)擊“生成今日簡(jiǎn)報(bào)”按鈕觀察后端日志和前端響應(yīng)。4. 插件調(diào)試、打包與發(fā)布到市場(chǎng)本地運(yùn)行無(wú)誤后下一步是將其打包成可分發(fā)的格式并發(fā)布到DSH插件市場(chǎng)或私有倉(cāng)庫(kù)以便其他用戶安裝。4.1 調(diào)試與問題排查在開發(fā)過程中你一定會(huì)遇到問題。請(qǐng)按以下順序排查問題現(xiàn)象可能原因檢查點(diǎn)與解決方案dsh plugin dev啟動(dòng)失敗1.plugin.yaml語(yǔ)法錯(cuò)誤。2. 依賴未安裝。3. 端口被占用。1. 使用YAML校驗(yàn)器檢查plugin.yaml。2. 確保已運(yùn)行pnpm install和pip install。3. 檢查frontend.port和runtime.command中指定的端口是否空閑。前端頁(yè)面空白或報(bào)錯(cuò)1. 前端依賴缺失或構(gòu)建失敗。2. 代理配置錯(cuò)誤前端請(qǐng)求無(wú)法到達(dá)后端。1. 查看瀏覽器開發(fā)者工具 Console 和 Network 面板。2. 檢查dsh plugin dev啟動(dòng)日志確認(rèn)前端服務(wù)器是否成功啟動(dòng)。3. 嘗試直接訪問前端開發(fā)服務(wù)器地址如http://localhost:3000。點(diǎn)擊按鈕前端報(bào)“Network Error”或“404”1. 后端服務(wù)器未啟動(dòng)。2. 后端API路由與前端請(qǐng)求不匹配。3. 插件權(quán)限不足。1. 查看dsh plugin dev終端日志確認(rèn)后端進(jìn)程是否在運(yùn)行且無(wú)報(bào)錯(cuò)。2. 核對(duì)前端fetch(‘/api/briefing’)和后端do_GET(‘/api/briefing’)路徑是否完全一致。3. 檢查plugin.yaml中的permissions是否包含了network如果需要訪問外部API。后端日志顯示“Connection refused”訪問外部API失敗1. 網(wǎng)絡(luò)不通。2. 環(huán)境變量未正確注入。3. API需要認(rèn)證。1. 在后端代碼中打印os.getenv(‘API_ENDPOINT’)確認(rèn)值是否正確。2. 在DSH插件管理界面檢查該插件的配置項(xiàng)是否已填寫。3. 使用curl或requests在插件環(huán)境外手動(dòng)測(cè)試API連通性。插件在DSH中運(yùn)行正常但接入門戶后無(wú)法使用1. 門戶與DSH的跨域問題。2. 門戶傳遞的認(rèn)證信息DSH未識(shí)別。3. DSH服務(wù)地址配置錯(cuò)誤。1. 這是集成階段最常見問題詳見第5節(jié)。最重要的調(diào)試工具是日志。始終確保你的后端代碼有充分的日志輸出并在DSH桌面端的“插件日志”面板中仔細(xì)查看。4.2 打包插件當(dāng)插件開發(fā)測(cè)試完成需要打包成一個(gè).dsh-plugin文件本質(zhì)上是一個(gè)zip壓縮包便于分發(fā)和安裝。# 在插件項(xiàng)目根目錄執(zhí)行打包命令 dsh plugin pack該命令會(huì)運(yùn)行前端構(gòu)建如果存在生成靜態(tài)文件到dist目錄。將plugin.yaml、構(gòu)建后的前端文件、后端源代碼或根據(jù)配置排除某些文件一起打包。在項(xiàng)目根目錄生成一個(gè)類似gov-data-briefing-0.1.0.dsh-plugin的文件。4.3 發(fā)布到插件市場(chǎng)你可以將插件發(fā)布到官方市場(chǎng)或私有市場(chǎng)。# 1. 登錄到DSH插件市場(chǎng) (需要賬戶) dsh plugin login # 2. 發(fā)布插件 dsh plugin publish ./gov-data-briefing-0.1.0.dsh-plugin發(fā)布前請(qǐng)務(wù)必更新plugin.yaml中的version字段。編寫清晰的README.md說明插件功能、配置方法和注意事項(xiàng)。在插件市場(chǎng)管理后臺(tái)為插件設(shè)置合適的分類、標(biāo)簽和截圖。對(duì)于政務(wù)內(nèi)部系統(tǒng)你更可能需要搭建私有插件市場(chǎng)。這通常涉及部署一個(gè)符合DSH插件市場(chǎng)協(xié)議的服務(wù)器并將DSH桌面端的市場(chǎng)地址指向它。具體步驟請(qǐng)參考DSH官方文檔中關(guān)于私有部署的部分。5. 將插件集成到政務(wù)門戶這是最后也是最關(guān)鍵的一步讓插件在門戶系統(tǒng)中可用。5.1 集成模式選擇模式描述優(yōu)點(diǎn)缺點(diǎn)適用場(chǎng)景Iframe 嵌入在門戶頁(yè)面中通過iframe標(biāo)簽嵌入 DSH 桌面端中該插件的專屬URL。實(shí)現(xiàn)簡(jiǎn)單隔離性好插件更新獨(dú)立于門戶。存在跨域限制需要處理登錄態(tài)傳遞UI風(fēng)格可能與門戶不統(tǒng)一。快速集成對(duì)UI一致性要求不高的內(nèi)部工具。API 直調(diào)門戶后端直接調(diào)用已部署的DSH插件提供的API需插件暴露API。性能好門戶可完全控制交互邏輯。需要插件設(shè)計(jì)為純后端服務(wù)門戶需自己開發(fā)前端界面。插件核心是數(shù)據(jù)處理能力無(wú)需復(fù)雜UI。微前端架構(gòu)將插件前端構(gòu)建為微前端模塊門戶通過微前端框架加載。UI融合度最高體驗(yàn)最佳。技術(shù)復(fù)雜度高需要改造門戶和插件前端。大型、長(zhǎng)期的項(xiàng)目對(duì)用戶體驗(yàn)要求極高。本文以最常用的Iframe 嵌入為例。5.2 Iframe 嵌入實(shí)戰(zhàn)步驟前提DSH桌面端或服務(wù)已部署在內(nèi)部網(wǎng)絡(luò)地址為https://dsh.internal.gov。你的插件gov-data-briefing已安裝并配置好。步驟一在門戶頁(yè)面添加Iframe!-- 在門戶的某個(gè).vue/.jsx/.html文件中 -- div classtool-card h3每日數(shù)據(jù)簡(jiǎn)報(bào)/h3 iframe refpluginFrame :srcpluginUrl width100% height600px frameborder0 allowclipboard-write; loadonIframeLoad /iframe div v-ifloading加載插件中.../div /div步驟二處理認(rèn)證與URL生成門戶用戶登錄后會(huì)有一個(gè)身份令牌如JWT。需要將這個(gè)令牌安全地傳遞給DSH。// 在門戶前端邏輯中 import { getCurrentUserToken } from /utils/auth; // 假設(shè)有獲取用戶Token的方法 export default { data() { return { pluginUrl: , loading: true }; }, mounted() { this.initPluginFrame(); }, methods: { async initPluginFrame() { const userToken getCurrentUserToken(); // 構(gòu)造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內(nèi)插件的通信例如使用 postMessage // this.$refs.pluginFrame.contentWindow.postMessage({ type: init }, *); } } };關(guān)鍵安全考慮Token傳遞切勿使用URL參數(shù)傳遞高敏感Token除非DSH和門戶在同一頂級(jí)域名下并使用安全的SameSite Cookie。更安全的方式是門戶后端與DSH后端通過OAuth 2.0等協(xié)議進(jìn)行服務(wù)間認(rèn)證為每個(gè)會(huì)話生成一個(gè)短期有效的嵌入令牌。同源策略如果dsh.internal.gov與門戶不同源iframe通信會(huì)受到限制。需要DSH服務(wù)端設(shè)置正確的CORS頭部 (Access-Control-Allow-Origin) 和X-Frame-Options。步驟三DSH服務(wù)端配置確保DSH服務(wù)端或網(wǎng)關(guān)能夠驗(yàn)證門戶傳來(lái)的Token并識(shí)別用戶身份從而在插件運(yùn)行時(shí)注入正確的用戶上下文和權(quán)限。這通常需要在DSH的部署配置中啟用并配置相應(yīng)的認(rèn)證中間件。5.3 集成后常見問題排查問題排查方向Iframe 顯示“無(wú)法連接”或空白1. 檢查pluginUrl是否正確能否在瀏覽器單獨(dú)訪問。2. 檢查DSH服務(wù)是否健康運(yùn)行。3. 檢查網(wǎng)絡(luò)策略門戶頁(yè)面能否訪問DSH的域名和端口。Iframe 顯示“未授權(quán)”或“請(qǐng)登錄”1. Token未傳遞或已過期。2. DSH服務(wù)端未正確配置該Token的驗(yàn)證方式。3. 該用戶無(wú)權(quán)訪問此插件需在DSH中配置插件權(quán)限。插件功能異常如無(wú)法調(diào)用API1. 在DSH桌面端直接運(yùn)行插件是否正常如果正常問題出在集成環(huán)境。2. 檢查插件在集成環(huán)境下運(yùn)行時(shí)的日志看環(huán)境變量如API_ENDPOINT是否正確注入。3. 可能是集成環(huán)境與開發(fā)環(huán)境的網(wǎng)絡(luò)策略不同導(dǎo)致插件無(wú)法訪問外部政務(wù)數(shù)據(jù)API。6. 生產(chǎn)環(huán)境部署與最佳實(shí)踐將插件從開發(fā)環(huán)境推向生產(chǎn)環(huán)境需要額外的考量。6.1 配置管理分離配置所有環(huán)境相關(guān)的配置API地址、密鑰、數(shù)據(jù)庫(kù)連接必須通過plugin.yaml的configs定義并通過環(huán)境變量注入。絕對(duì)不要硬編碼在代碼中。使用密鑰管理對(duì)于密碼、Token等敏感信息應(yīng)使用DSH提供的密鑰管理功能或?qū)油獠棵荑€管理服務(wù)如HashiCorp Vault而不是以明文存儲(chǔ)在配置界面。6.2 安全性加固權(quán)限最小化在plugin.yaml的permissions中只聲明插件運(yùn)行所必需的最小權(quán)限。例如不需要文件讀寫就不要聲明filesystem。輸入驗(yàn)證與消毒插件后端必須對(duì)所有輸入包括來(lái)自前端的參數(shù)和外部API的響應(yīng)進(jìn)行嚴(yán)格的驗(yàn)證和消毒防止注入攻擊。依賴掃描定期使用pip-audit,npm audit等工具掃描項(xiàng)目依賴的安全漏洞并及時(shí)更新。6.3 可觀測(cè)性與監(jiān)控結(jié)構(gòu)化日志確保插件輸出結(jié)構(gòu)化的日志JSON格式便于被ELK、Loki等日志系統(tǒng)采集和分析。在日志中記錄請(qǐng)求ID、用戶ID、關(guān)鍵操作步驟和錯(cuò)誤詳情。健康檢查端點(diǎn)為插件后端添加一個(gè)/health端點(diǎn)返回服務(wù)狀態(tài)。這便于容器編排平臺(tái)如Kubernetes或DSH本身進(jìn)行健康檢查。指標(biāo)暴露考慮使用Prometheus客戶端庫(kù)暴露插件的關(guān)鍵指標(biāo)如請(qǐng)求數(shù)、延遲、錯(cuò)誤率方便監(jiān)控。6.4 版本與更新語(yǔ)義化版本嚴(yán)格遵守語(yǔ)義化版本控制SemVer。plugin.yaml中的version字段在修復(fù)Bug時(shí)遞增修訂號(hào)在新增向后兼容的功能時(shí)遞增次版本號(hào)在做出不兼容的變更時(shí)遞增主版本號(hào)。變更日志維護(hù)CHANGELOG.md清晰記錄每個(gè)版本的變更內(nèi)容特別是破壞性變更和配置項(xiàng)變更。向后兼容更新插件時(shí)盡量保持API的向后兼容性。如果必須做出破壞性變更應(yīng)提供遷移指南并在插件市場(chǎng)中明確標(biāo)注。通過以上步驟你不僅完成了一個(gè)DSH插件的開發(fā)更掌握了一套將內(nèi)部能力快速產(chǎn)品化并集成到現(xiàn)有系統(tǒng)的工程方法。這種插件化思維能夠極大地提升團(tuán)隊(duì)交付工具的效率和標(biāo)準(zhǔn)化程度。 DeepSeek Harness插件開發(fā)實(shí)戰(zhàn)：從零構(gòu)建政務(wù)數(shù)據(jù)簡(jiǎn)報(bào)生成工具
在實(shí)際企業(yè)級(jí)應(yīng)用開發(fā)中我們經(jīng)常面臨將內(nèi)部工具或AI能力安全、便捷地集成到現(xiàn)有辦公門戶的需求。傳統(tǒng)的集成方式如開發(fā)獨(dú)立的微服務(wù)或編寫復(fù)雜的API對(duì)接腳本不僅開發(fā)周期長(zhǎng)而且后期維護(hù)、權(quán)限控制和用戶交互體驗(yàn)都面臨挑戰(zhàn)。DeepSeek Harness簡(jiǎn)稱DSH及其插件生態(tài)的出現(xiàn)為這類場(chǎng)景提供了一種新穎、高效的解決方案。它允許開發(fā)者將AI功能、數(shù)據(jù)處理工具或業(yè)務(wù)邏輯封裝成標(biāo)準(zhǔn)的插件并一鍵發(fā)布到插件市場(chǎng)最終用戶可以像安裝手機(jī)App一樣在DeepSeek Harness桌面端或Web門戶中直接使用。本文將以一個(gè)假設(shè)的“政務(wù)數(shù)據(jù)簡(jiǎn)報(bào)生成”場(chǎng)景為例詳細(xì)演示如何從零開始開發(fā)一個(gè)DSH插件并將其成功接入一個(gè)模擬的政務(wù)門戶系統(tǒng)中。我們將涵蓋從環(huán)境搭建、插件開發(fā)、本地調(diào)試、打包發(fā)布到門戶集成的完整閉環(huán)。通過這個(gè)案例你將掌握DSH插件開發(fā)的核心流程、關(guān)鍵配置項(xiàng)以及在實(shí)際集成中可能遇到的典型問題及其解決方案。無(wú)論你是希望將內(nèi)部AI工具產(chǎn)品化還是尋求更輕量級(jí)的系統(tǒng)集成方式本文都能提供一條清晰的實(shí)踐路徑。1. 理解 DeepSeek Harness 插件生態(tài)與政務(wù)門戶集成架構(gòu)在開始編碼之前必須厘清幾個(gè)核心概念和它們之間的協(xié)作關(guān)系。這能幫助你在后續(xù)步驟中理解每一個(gè)配置和代碼片段的目的而不是機(jī)械地復(fù)制粘貼。1.1 DeepSeek Harness (DSH) 是什么DeepSeek Harness 是一個(gè)開源的AI應(yīng)用開發(fā)與部署平臺(tái)。你可以把它理解為一個(gè)“容器”或“運(yùn)行時(shí)環(huán)境”專門用于托管和運(yùn)行各種AI能力或工具化應(yīng)用這些應(yīng)用以“插件”的形式存在。DSH本身提供了插件管理、生命周期控制、資源隔離以及統(tǒng)一的前端交互框架。開發(fā)者無(wú)需從零構(gòu)建一個(gè)完整的Web應(yīng)用只需關(guān)注插件的核心業(yè)務(wù)邏輯。1.2 DSH 插件是什么一個(gè)DSH插件就是一個(gè)符合其規(guī)范的項(xiàng)目包。它通常包含業(yè)務(wù)邏輯代碼用Python、Node.js等語(yǔ)言編寫的核心功能。插件聲明文件 (plugin.yaml)描述插件的元信息如名稱、版本、入口命令、配置參數(shù)、前端組件等。前端UI組件可選如果插件需要用戶界面可以提供Vue/React組件。依賴聲明文件如requirements.txt或package.json。插件被安裝到DSH后DSH會(huì)為其創(chuàng)建獨(dú)立的運(yùn)行環(huán)境并負(fù)責(zé)調(diào)用其聲明的命令或渲染其UI。1.3 “接入政務(wù)門戶”意味著什么這里的“政務(wù)門戶”是一個(gè)泛指可以是任何內(nèi)部OA系統(tǒng)、統(tǒng)一工作臺(tái)或信息門戶。接入方式通常不是直接修改門戶源碼而是通過以下兩種模式嵌入式集成在門戶的某個(gè)頁(yè)面內(nèi)通過 iframe 或 Web Components 嵌入 DSH 桌面端的特定插件頁(yè)面。門戶負(fù)責(zé)身份認(rèn)證和權(quán)限傳遞DSH負(fù)責(zé)插件的渲染和執(zhí)行。鏈接跳轉(zhuǎn)在門戶上放置一個(gè)鏈接點(diǎn)擊后在新窗口或標(biāo)簽頁(yè)中打開 DSH 桌面端并直接定位到該插件界面。本文重點(diǎn)演示第一種更深度集成的模式。其技術(shù)鏈路可以概括為政務(wù)門戶 (前端) --[攜帶Token]-- DSH 桌面端/服務(wù) --[加載并運(yùn)行]-- 你的插件整個(gè)流程的關(guān)鍵在于門戶與DSH之間的安全認(rèn)證如JWT Token傳遞以及DSH對(duì)插件的正確加載。1.4 開發(fā)前需要明確的幾個(gè)問題目標(biāo)用戶是政務(wù)內(nèi)部工作人員他們對(duì)插件的穩(wěn)定性、安全性和易用性要求極高。插件類型你的插件是提供API服務(wù)無(wú)UI還是需要一個(gè)交互界面本文案例是一個(gè)帶有簡(jiǎn)單UI的數(shù)據(jù)處理插件。部署環(huán)境DSH是部署在內(nèi)部服務(wù)器還是云端這影響到后續(xù)的網(wǎng)絡(luò)配置和訪問地址。2. 環(huán)境準(zhǔn)備與項(xiàng)目初始化一個(gè)順暢的開發(fā)環(huán)境能避免很多后續(xù)的詭異問題。請(qǐng)嚴(yán)格按照順序操作。2.1 基礎(chǔ)環(huán)境檢查與安裝你需要準(zhǔn)備以下工具并確認(rèn)版本兼容性。建議使用版本管理工具如nvm、pyenv來(lái)保持環(huán)境純凈。工具推薦版本作用驗(yàn)證命令Node.js18.x 或 20.x (LTS)運(yùn)行DSH桌面端及前端工具鏈node --versionpnpm8.0.0推薦使用的包管理器比npm更快、更節(jié)省磁盤pnpm --versionPython3.8 - 3.11編寫插件后端邏輯如果插件使用Pythonpython --versionGit最新版代碼版本管理git --version安裝DSH命令行工具DSH CLI它是開發(fā)、調(diào)試、管理插件的核心。# 使用 pnpm 全局安裝 dsh-cli pnpm add -g deepeek/dsh-cli # 安裝完成后驗(yàn)證安裝是否成功 dsh --version如果出現(xiàn)‘dsh’ 不是內(nèi)部或外部命令的錯(cuò)誤請(qǐng)將pnpm的全局bin目錄通常為~/.local/share/pnpm/global/5/node_modules/.bin或類似路徑添加到系統(tǒng)的PATH環(huán)境變量中。2.2 創(chuàng)建你的第一個(gè)插件項(xiàng)目DSH CLI 提供了項(xiàng)目腳手架可以快速生成一個(gè)結(jié)構(gòu)規(guī)范的插件項(xiàng)目。# 創(chuàng)建一個(gè)目錄用于存放你的插件項(xiàng)目 mkdir my-gov-plugin cd my-gov-plugin # 使用 dsh cli 初始化插件項(xiàng)目 # 你會(huì)被交互式地詢問插件名稱、描述、類型等信息 dsh plugin init根據(jù)提示進(jìn)行選擇例如Plugin name:gov-data-briefingDescription:A plugin to generate daily briefing reports from government data.Plugin type: 選擇Basic(基礎(chǔ)插件包含前后端示例) 或根據(jù)需求選擇其他模板。Language: 選擇Python或Node.js本文以Python為例。初始化完成后你會(huì)得到一個(gè)類似如下的目錄結(jié)構(gòu)gov-data-briefing/ ├── plugin.yaml # 插件核心聲明文件 ├── pyproject.toml # Python項(xiàng)目依賴管理 (如果選Python) ├── src/ │ ├── backend/ # 后端邏輯代碼 │ │ └── main.py │ └── frontend/ # 前端UI代碼 (如果選帶UI的模板) │ ├── App.vue │ └── index.js ├── webpack.config.js # 前端構(gòu)建配置 └── README.md2.3 理解核心文件plugin.yamlplugin.yaml是插件的“身份證”和“說明書”DSH完全依據(jù)這個(gè)文件來(lái)管理插件。打開它你會(huì)看到如下內(nèi)容具體內(nèi)容因模板而異# 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 # 插件啟動(dòng)命令 frontend: type: vue path: src/frontend port: 3000 # 前端開發(fā)服務(wù)器端口 permissions: - network # 聲明插件需要網(wǎng)絡(luò)權(quán)限 configs: - key: API_ENDPOINT name: 數(shù)據(jù)API地址 type: string default: http://internal-data.gov/api required: true關(guān)鍵字段解釋runtime: 定義了插件的運(yùn)行環(huán)境。command是DSH啟動(dòng)插件進(jìn)程時(shí)執(zhí)行的命令。frontend: 如果插件有UI這里定義了前端類型、路徑和開發(fā)端口。DSH在開發(fā)模式下會(huì)代理這個(gè)端口的請(qǐng)求。permissions:安全關(guān)鍵項(xiàng)。插件默認(rèn)在沙箱中運(yùn)行無(wú)權(quán)訪問網(wǎng)絡(luò)、文件系統(tǒng)等。這里聲明network插件才能調(diào)用外部API如訪問政務(wù)數(shù)據(jù)接口。configs: 定義了插件可配置的參數(shù)。用戶可以在DSH插件管理界面修改這些值插件代碼中可以通過環(huán)境變量讀取。這對(duì)于區(qū)分測(cè)試和生產(chǎn)環(huán)境非常有用。3. 開發(fā)政務(wù)數(shù)據(jù)簡(jiǎn)報(bào)生成插件現(xiàn)在我們開始為這個(gè)插件填充實(shí)際業(yè)務(wù)邏輯。假設(shè)場(chǎng)景是插件從內(nèi)部政務(wù)數(shù)據(jù)API拉取當(dāng)日關(guān)鍵指標(biāo)通過AI模型或規(guī)則引擎生成一份文本簡(jiǎn)報(bào)并提供給用戶查看和下載。3.1 編寫后端邏輯 (Python示例)編輯src/backend/main.py。一個(gè)最簡(jiǎn)單的DSH插件后端是一個(gè)長(zhǎng)期運(yùn)行的HTTP服務(wù)器DSH會(huì)向其發(fā)送請(qǐng)求。# 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控制臺(tái)查看 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, ) # 假設(shè)還有一個(gè)配置項(xiàng)用于認(rèn)證 class PluginRequestHandler(BaseHTTPRequestHandler): def do_GET(self): 處理前端GET請(qǐng)求例如獲取簡(jiǎn)報(bào) parsed_path urlparse(self.path) if parsed_path.path /api/briefing: # 1. 調(diào)用政務(wù)數(shù)據(jù)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成功獲取數(shù)據(jù): {data}) except requests.exceptions.RequestException as e: logger.error(f調(diào)用數(shù)據(jù)API失敗: {e}) self.send_response(500) self.end_headers() self.wfile.write(json.dumps({error: 數(shù)據(jù)服務(wù)不可用}).encode()) return # 2. 模擬簡(jiǎn)報(bào)生成邏輯 (實(shí)際項(xiàng)目中可能調(diào)用LLM) briefing_text f 政務(wù)數(shù)據(jù)簡(jiǎn)報(bào) ({data.get(date, N/A)}) ---------------------------- 今日新增事項(xiàng): {data.get(new_cases, 0)} 件 辦結(jié)事項(xiàng): {data.get(closed_cases, 0)} 件 平均處理時(shí)長(zhǎng): {data.get(avg_duration, 0)} 小時(shí) 重點(diǎn)關(guān)注區(qū)域: {, .join(data.get(hot_areas, []))} # 3. 返回結(jié)果給前端 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請(qǐng)求例如觸發(fā)簡(jiǎn)報(bào)生成并存儲(chǔ) 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會(huì)通過PORT環(huán)境變量告知監(jiān)聽端口 server HTTPServer((localhost, server_port), PluginRequestHandler) logger.info(f啟動(dòng)插件后端服務(wù)器端口: {server_port}) logger.info(f配置的數(shù)據(jù)API地址: {API_ENDPOINT}) server.serve_forever()關(guān)鍵點(diǎn)說明環(huán)境變量API_ENDPOINT和API_TOKEN是從plugin.yaml的configs注入的。這是插件配置化的關(guān)鍵。HTTP Server插件后端需要啟動(dòng)一個(gè)HTTP服務(wù)器來(lái)接收DSH前端或直接調(diào)用的請(qǐng)求。DSH負(fù)責(zé)將外部請(qǐng)求路由到這個(gè)服務(wù)器的端口。日志使用logging模塊輸出日志至關(guān)重要。你可以在DSH桌面端的“插件日志”面板中查看這些日志這是最重要的調(diào)試手段。錯(cuò)誤處理務(wù)必對(duì)網(wǎng)絡(luò)請(qǐng)求、數(shù)據(jù)解析等可能失敗的操作進(jìn)行try-except捕獲并返回友好的錯(cuò)誤信息避免插件進(jìn)程崩潰。3.2 編寫前端界面 (Vue 3示例)編輯src/frontend/App.vue。前端負(fù)責(zé)與用戶交互并通過調(diào)用后端API獲取數(shù)據(jù)。!-- src/frontend/App.vue -- template div classplugin-container h1政務(wù)數(shù)據(jù)簡(jiǎn)報(bào)生成器/h1 el-button typeprimary clickfetchBriefing :loadingloading 生成今日簡(jiǎn)報(bào) /el-button div v-iferror classerror-message {{ error }} /div div v-ifbriefing classbriefing-result h3生成結(jié)果/h3 pre{{ briefing }}/pre el-button sizesmall clickdownloadBriefing下載簡(jiǎn)報(bào)文本/el-button h4原始數(shù)據(jù)/h4 pre{{ rawData }}/pre /div /div /template script setup import { ref } from vue import { ElButton, ElMessage } from element-plus // 假設(shè)使用Element Plus UI庫(kù) 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 { // 關(guān)鍵這里請(qǐng)求的是相對(duì)路徑 /api/briefing。 // 在DSH運(yùn)行時(shí)這個(gè)請(qǐng)求會(huì)被自動(dòng)代理到插件后端的本地端口。 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(簡(jiǎn)報(bào)生成成功) } catch (err) { console.error(獲取簡(jiǎn)報(bào)失敗:, err) error.value 獲取簡(jiǎn)報(bào)失敗: ${err.message}。請(qǐng)檢查網(wǎng)絡(luò)連接或插件后端日志。 ElMessage.error(簡(jiǎn)報(bào)生成失敗) } 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 政務(wù)簡(jiǎn)報(bào)_${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關(guān)鍵點(diǎn)說明API代理前端代碼中請(qǐng)求/api/briefing而不是http://localhost:7860/api/briefing。這是因?yàn)樵贒SH開發(fā)和生產(chǎn)模式下它會(huì)自動(dòng)創(chuàng)建一個(gè)反向代理將前端對(duì)/api的請(qǐng)求轉(zhuǎn)發(fā)到插件后端的實(shí)際端口。這解決了跨域問題是DSH插件開發(fā)的核心機(jī)制之一。UI庫(kù)示例中使用了element-plus你需要在src/frontend目錄下安裝它 (pnpm add element-plus)。你也可以使用任何其他Vue/React UI庫(kù)或純CSS。錯(cuò)誤反饋通過error變量和ElMessage向用戶清晰反饋操作狀態(tài)這是良好用戶體驗(yàn)的基礎(chǔ)。3.3 安裝依賴并本地運(yùn)行前后端代碼完成后需要安裝依賴并啟動(dòng)本地開發(fā)服務(wù)器進(jìn)行測(cè)試。# 在插件項(xiàng)目根目錄下 # 1. 安裝前端依賴 (如果前端目錄有 package.json) cd src/frontend pnpm install cd ../.. # 2. 安裝Python后端依賴 (如果使用Python) # 確保在項(xiàng)目根目錄或 backend 目錄下有 requirements.txt # 示例 requirements.txt 內(nèi)容 # requests2.28.0 pip install -r requirements.txt # 3. 啟動(dòng)插件開發(fā)模式 dsh plugin dev執(zhí)行dsh plugin dev后CLI 會(huì)做幾件事讀取plugin.yaml。啟動(dòng)插件后端進(jìn)程執(zhí)行python src/backend/main.py。啟動(dòng)前端開發(fā)服務(wù)器例如在http://localhost:3000。在DSH桌面端如果已安裝并運(yùn)行或?yàn)g覽器中打開一個(gè)調(diào)試窗口加載你的插件前端頁(yè)面。此時(shí)你應(yīng)該能在DSH桌面端的“本地插件”列表中看到gov-data-briefing并可以點(diǎn)擊運(yùn)行。嘗試點(diǎn)擊“生成今日簡(jiǎn)報(bào)”按鈕觀察后端日志和前端響應(yīng)。4. 插件調(diào)試、打包與發(fā)布到市場(chǎng)本地運(yùn)行無(wú)誤后下一步是將其打包成可分發(fā)的格式并發(fā)布到DSH插件市場(chǎng)或私有倉(cāng)庫(kù)以便其他用戶安裝。4.1 調(diào)試與問題排查在開發(fā)過程中你一定會(huì)遇到問題。請(qǐng)按以下順序排查問題現(xiàn)象可能原因檢查點(diǎn)與解決方案dsh plugin dev啟動(dòng)失敗1.plugin.yaml語(yǔ)法錯(cuò)誤。2. 依賴未安裝。3. 端口被占用。1. 使用YAML校驗(yàn)器檢查plugin.yaml。2. 確保已運(yùn)行pnpm install和pip install。3. 檢查frontend.port和runtime.command中指定的端口是否空閑。前端頁(yè)面空白或報(bào)錯(cuò)1. 前端依賴缺失或構(gòu)建失敗。2. 代理配置錯(cuò)誤前端請(qǐng)求無(wú)法到達(dá)后端。1. 查看瀏覽器開發(fā)者工具 Console 和 Network 面板。2. 檢查dsh plugin dev啟動(dòng)日志確認(rèn)前端服務(wù)器是否成功啟動(dòng)。3. 嘗試直接訪問前端開發(fā)服務(wù)器地址如http://localhost:3000。點(diǎn)擊按鈕前端報(bào)“Network Error”或“404”1. 后端服務(wù)器未啟動(dòng)。2. 后端API路由與前端請(qǐng)求不匹配。3. 插件權(quán)限不足。1. 查看dsh plugin dev終端日志確認(rèn)后端進(jìn)程是否在運(yùn)行且無(wú)報(bào)錯(cuò)。2. 核對(duì)前端fetch(‘/api/briefing’)和后端do_GET(‘/api/briefing’)路徑是否完全一致。3. 檢查plugin.yaml中的permissions是否包含了network如果需要訪問外部API。后端日志顯示“Connection refused”訪問外部API失敗1. 網(wǎng)絡(luò)不通。2. 環(huán)境變量未正確注入。3. API需要認(rèn)證。1. 在后端代碼中打印os.getenv(‘API_ENDPOINT’)確認(rèn)值是否正確。2. 在DSH插件管理界面檢查該插件的配置項(xiàng)是否已填寫。3. 使用curl或requests在插件環(huán)境外手動(dòng)測(cè)試API連通性。插件在DSH中運(yùn)行正常但接入門戶后無(wú)法使用1. 門戶與DSH的跨域問題。2. 門戶傳遞的認(rèn)證信息DSH未識(shí)別。3. DSH服務(wù)地址配置錯(cuò)誤。1. 這是集成階段最常見問題詳見第5節(jié)。最重要的調(diào)試工具是日志。始終確保你的后端代碼有充分的日志輸出并在DSH桌面端的“插件日志”面板中仔細(xì)查看。4.2 打包插件當(dāng)插件開發(fā)測(cè)試完成需要打包成一個(gè).dsh-plugin文件本質(zhì)上是一個(gè)zip壓縮包便于分發(fā)和安裝。# 在插件項(xiàng)目根目錄執(zhí)行打包命令 dsh plugin pack該命令會(huì)運(yùn)行前端構(gòu)建如果存在生成靜態(tài)文件到dist目錄。將plugin.yaml、構(gòu)建后的前端文件、后端源代碼或根據(jù)配置排除某些文件一起打包。在項(xiàng)目根目錄生成一個(gè)類似gov-data-briefing-0.1.0.dsh-plugin的文件。4.3 發(fā)布到插件市場(chǎng)你可以將插件發(fā)布到官方市場(chǎng)或私有市場(chǎng)。# 1. 登錄到DSH插件市場(chǎng) (需要賬戶) dsh plugin login # 2. 發(fā)布插件 dsh plugin publish ./gov-data-briefing-0.1.0.dsh-plugin發(fā)布前請(qǐng)務(wù)必更新plugin.yaml中的version字段。編寫清晰的README.md說明插件功能、配置方法和注意事項(xiàng)。在插件市場(chǎng)管理后臺(tái)為插件設(shè)置合適的分類、標(biāo)簽和截圖。對(duì)于政務(wù)內(nèi)部系統(tǒng)你更可能需要搭建私有插件市場(chǎng)。這通常涉及部署一個(gè)符合DSH插件市場(chǎng)協(xié)議的服務(wù)器并將DSH桌面端的市場(chǎng)地址指向它。具體步驟請(qǐng)參考DSH官方文檔中關(guān)于私有部署的部分。5. 將插件集成到政務(wù)門戶這是最后也是最關(guān)鍵的一步讓插件在門戶系統(tǒng)中可用。5.1 集成模式選擇模式描述優(yōu)點(diǎn)缺點(diǎn)適用場(chǎng)景Iframe 嵌入在門戶頁(yè)面中通過iframe標(biāo)簽嵌入 DSH 桌面端中該插件的專屬URL。實(shí)現(xiàn)簡(jiǎn)單隔離性好插件更新獨(dú)立于門戶。存在跨域限制需要處理登錄態(tài)傳遞UI風(fēng)格可能與門戶不統(tǒng)一。快速集成對(duì)UI一致性要求不高的內(nèi)部工具。API 直調(diào)門戶后端直接調(diào)用已部署的DSH插件提供的API需插件暴露API。性能好門戶可完全控制交互邏輯。需要插件設(shè)計(jì)為純后端服務(wù)門戶需自己開發(fā)前端界面。插件核心是數(shù)據(jù)處理能力無(wú)需復(fù)雜UI。微前端架構(gòu)將插件前端構(gòu)建為微前端模塊門戶通過微前端框架加載。UI融合度最高體驗(yàn)最佳。技術(shù)復(fù)雜度高需要改造門戶和插件前端。大型、長(zhǎng)期的項(xiàng)目對(duì)用戶體驗(yàn)要求極高。本文以最常用的Iframe 嵌入為例。5.2 Iframe 嵌入實(shí)戰(zhàn)步驟前提DSH桌面端或服務(wù)已部署在內(nèi)部網(wǎng)絡(luò)地址為https://dsh.internal.gov。你的插件gov-data-briefing已安裝并配置好。步驟一在門戶頁(yè)面添加Iframe!-- 在門戶的某個(gè).vue/.jsx/.html文件中 -- div classtool-card h3每日數(shù)據(jù)簡(jiǎn)報(bào)/h3 iframe refpluginFrame :srcpluginUrl width100% height600px frameborder0 allowclipboard-write; loadonIframeLoad /iframe div v-ifloading加載插件中.../div /div步驟二處理認(rèn)證與URL生成門戶用戶登錄后會(huì)有一個(gè)身份令牌如JWT。需要將這個(gè)令牌安全地傳遞給DSH。// 在門戶前端邏輯中 import { getCurrentUserToken } from /utils/auth; // 假設(shè)有獲取用戶Token的方法 export default { data() { return { pluginUrl: , loading: true }; }, mounted() { this.initPluginFrame(); }, methods: { async initPluginFrame() { const userToken getCurrentUserToken(); // 構(gòu)造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內(nèi)插件的通信例如使用 postMessage // this.$refs.pluginFrame.contentWindow.postMessage({ type: init }, *); } } };關(guān)鍵安全考慮Token傳遞切勿使用URL參數(shù)傳遞高敏感Token除非DSH和門戶在同一頂級(jí)域名下并使用安全的SameSite Cookie。更安全的方式是門戶后端與DSH后端通過OAuth 2.0等協(xié)議進(jìn)行服務(wù)間認(rèn)證為每個(gè)會(huì)話生成一個(gè)短期有效的嵌入令牌。同源策略如果dsh.internal.gov與門戶不同源iframe通信會(huì)受到限制。需要DSH服務(wù)端設(shè)置正確的CORS頭部 (Access-Control-Allow-Origin) 和X-Frame-Options。步驟三DSH服務(wù)端配置確保DSH服務(wù)端或網(wǎng)關(guān)能夠驗(yàn)證門戶傳來(lái)的Token并識(shí)別用戶身份從而在插件運(yùn)行時(shí)注入正確的用戶上下文和權(quán)限。這通常需要在DSH的部署配置中啟用并配置相應(yīng)的認(rèn)證中間件。5.3 集成后常見問題排查問題排查方向Iframe 顯示“無(wú)法連接”或空白1. 檢查pluginUrl是否正確能否在瀏覽器單獨(dú)訪問。2. 檢查DSH服務(wù)是否健康運(yùn)行。3. 檢查網(wǎng)絡(luò)策略門戶頁(yè)面能否訪問DSH的域名和端口。Iframe 顯示“未授權(quán)”或“請(qǐng)登錄”1. Token未傳遞或已過期。2. DSH服務(wù)端未正確配置該Token的驗(yàn)證方式。3. 該用戶無(wú)權(quán)訪問此插件需在DSH中配置插件權(quán)限。插件功能異常如無(wú)法調(diào)用API1. 在DSH桌面端直接運(yùn)行插件是否正常如果正常問題出在集成環(huán)境。2. 檢查插件在集成環(huán)境下運(yùn)行時(shí)的日志看環(huán)境變量如API_ENDPOINT是否正確注入。3. 可能是集成環(huán)境與開發(fā)環(huán)境的網(wǎng)絡(luò)策略不同導(dǎo)致插件無(wú)法訪問外部政務(wù)數(shù)據(jù)API。6. 生產(chǎn)環(huán)境部署與最佳實(shí)踐將插件從開發(fā)環(huán)境推向生產(chǎn)環(huán)境需要額外的考量。6.1 配置管理分離配置所有環(huán)境相關(guān)的配置API地址、密鑰、數(shù)據(jù)庫(kù)連接必須通過plugin.yaml的configs定義并通過環(huán)境變量注入。絕對(duì)不要硬編碼在代碼中。使用密鑰管理對(duì)于密碼、Token等敏感信息應(yīng)使用DSH提供的密鑰管理功能或?qū)油獠棵荑€管理服務(wù)如HashiCorp Vault而不是以明文存儲(chǔ)在配置界面。6.2 安全性加固權(quán)限最小化在plugin.yaml的permissions中只聲明插件運(yùn)行所必需的最小權(quán)限。例如不需要文件讀寫就不要聲明filesystem。輸入驗(yàn)證與消毒插件后端必須對(duì)所有輸入包括來(lái)自前端的參數(shù)和外部API的響應(yīng)進(jìn)行嚴(yán)格的驗(yàn)證和消毒防止注入攻擊。依賴掃描定期使用pip-audit,npm audit等工具掃描項(xiàng)目依賴的安全漏洞并及時(shí)更新。6.3 可觀測(cè)性與監(jiān)控結(jié)構(gòu)化日志確保插件輸出結(jié)構(gòu)化的日志JSON格式便于被ELK、Loki等日志系統(tǒng)采集和分析。在日志中記錄請(qǐng)求ID、用戶ID、關(guān)鍵操作步驟和錯(cuò)誤詳情。健康檢查端點(diǎn)為插件后端添加一個(gè)/health端點(diǎn)返回服務(wù)狀態(tài)。這便于容器編排平臺(tái)如Kubernetes或DSH本身進(jìn)行健康檢查。指標(biāo)暴露考慮使用Prometheus客戶端庫(kù)暴露插件的關(guān)鍵指標(biāo)如請(qǐng)求數(shù)、延遲、錯(cuò)誤率方便監(jiān)控。6.4 版本與更新語(yǔ)義化版本嚴(yán)格遵守語(yǔ)義化版本控制SemVer。plugin.yaml中的version字段在修復(fù)Bug時(shí)遞增修訂號(hào)在新增向后兼容的功能時(shí)遞增次版本號(hào)在做出不兼容的變更時(shí)遞增主版本號(hào)。變更日志維護(hù)CHANGELOG.md清晰記錄每個(gè)版本的變更內(nèi)容特別是破壞性變更和配置項(xiàng)變更。向后兼容更新插件時(shí)盡量保持API的向后兼容性。如果必須做出破壞性變更應(yīng)提供遷移指南并在插件市場(chǎng)中明確標(biāo)注。通過以上步驟你不僅完成了一個(gè)DSH插件的開發(fā)更掌握了一套將內(nèi)部能力快速產(chǎn)品化并集成到現(xiàn)有系統(tǒng)的工程方法。這種插件化思維能夠極大地提升團(tuán)隊(duì)交付工具的效率和標(biāo)準(zhǔn)化程度。