如果你是一名開(kāi)發(fā)者最近可能已經(jīng)注意到一個(gè)現(xiàn)象無(wú)論是 GitHub 趨勢(shì)榜還是技術(shù)社區(qū)的討論圍繞“AI 編程助手”的敘事正在發(fā)生一次微妙的轉(zhuǎn)向。過(guò)去我們談?wù)摰氖侨绾斡?Copilot 補(bǔ)全代碼或是如何向 ChatGPT 描述需求。但現(xiàn)在一個(gè)更深入的問(wèn)題被提了出來(lái)如何讓 AI 助手真正理解我的項(xiàng)目上下文、我的技術(shù)棧、我的團(tuán)隊(duì)規(guī)范并在此基礎(chǔ)上自動(dòng)化執(zhí)行那些重復(fù)、繁瑣但至關(guān)重要的開(kāi)發(fā)任務(wù)這正是 DeepSeek Harness簡(jiǎn)稱 dsh試圖回答的問(wèn)題。它不是一個(gè)簡(jiǎn)單的代碼補(bǔ)全工具而是一個(gè)旨在將 AI 深度集成到開(kāi)發(fā)者工作流中的“智能開(kāi)發(fā)環(huán)境”。其核心在于“插件”Skill生態(tài)。通過(guò)插件你可以教會(huì) dsh 如何與你的 Git 倉(cāng)庫(kù)、數(shù)據(jù)庫(kù)、API、甚至內(nèi)部部署的系統(tǒng)進(jìn)行交互從而將自然語(yǔ)言指令轉(zhuǎn)化為一系列精準(zhǔn)的自動(dòng)化操作。然而當(dāng)你興沖沖地打開(kāi)官方文檔準(zhǔn)備開(kāi)發(fā)自己的第一個(gè)插件時(shí)可能會(huì)立刻陷入困惑概念抽象、示例零散、社區(qū)資料匱乏。你搜索“dsh 插件開(kāi)發(fā)教程”找到的往往是“安裝教程”或“使用體驗(yàn)”關(guān)于“如何從零構(gòu)建一個(gè)真正有用的插件”的實(shí)戰(zhàn)指南幾乎是一片空白。這篇文章的目的就是填補(bǔ)這片空白。我將帶你從零開(kāi)始深入 DeepSeek Harness 插件開(kāi)發(fā)的核心。我們不會(huì)停留在概念復(fù)述而是通過(guò)構(gòu)建一個(gè)真實(shí)可用的“項(xiàng)目健康度檢查插件”來(lái)拆解整個(gè)開(kāi)發(fā)流程。你將清晰地理解dsh 插件到底是什么它與 VSCode 插件、瀏覽器插件有何本質(zhì)不同開(kāi)發(fā)一個(gè)插件的完整生命周期是怎樣的從環(huán)境搭建、項(xiàng)目初始化、代碼編寫、本地調(diào)試到最終發(fā)布。如何設(shè)計(jì)一個(gè)“好用”的插件如何定義清晰的意圖Intent、處理復(fù)雜的用戶輸入、與外部服務(wù)安全交互開(kāi)發(fā)過(guò)程中有哪些“坑”如何調(diào)試、如何測(cè)試、如何確保插件的穩(wěn)定性和安全性本文假設(shè)你具備基本的 Python 開(kāi)發(fā)經(jīng)驗(yàn)并對(duì)命令行操作有一定了解。我們的目標(biāo)不僅是讓你“跑通”一個(gè)示例更是讓你掌握設(shè)計(jì)并實(shí)現(xiàn)一個(gè)能解決實(shí)際工程問(wèn)題的 dsh 插件的核心能力。1. 重新理解 DeepSeek Harness 與插件它到底解決了什么痛點(diǎn)在開(kāi)始寫代碼之前我們必須先厘清一個(gè)根本問(wèn)題為什么需要 dsh 和它的插件體系這能幫助我們判斷投入時(shí)間學(xué)習(xí)它是否值得。傳統(tǒng)的 AI 編程助手如 Copilot、ChatGPT工作模式是“問(wèn)答式”或“補(bǔ)全式”。你提出一個(gè)問(wèn)題或一段注釋它生成一段代碼。這種模式的瓶頸在于缺乏上下文AI 不知道你項(xiàng)目的完整結(jié)構(gòu)、依賴關(guān)系、配置文件。無(wú)法執(zhí)行AI 可以告訴你“運(yùn)行g(shù)it status”但你需要自己切換到終端去執(zhí)行。難以復(fù)用一套復(fù)雜的操作流程如“為新功能創(chuàng)建分支、初始化模塊、更新文檔”無(wú)法被沉淀為可一鍵觸發(fā)的自動(dòng)化腳本。DeepSeek Harness 的定位是“AI-Native 的集成開(kāi)發(fā)環(huán)境”。它試圖將 AI 作為整個(gè)開(kāi)發(fā)工作流的“大腦”和“執(zhí)行臂”。而插件就是為這個(gè)“執(zhí)行臂”安裝的“工具手”。一個(gè)插件的本質(zhì)是一組可供 AI 調(diào)用的、定義清晰的能力Capabilities。舉個(gè)例子沒(méi)有插件你對(duì) dsh 說(shuō)“檢查一下主分支和開(kāi)發(fā)分支的差異。”dsh 可能只能回復(fù)你一個(gè) Git 命令git diff main..develop。有了 Git 插件你對(duì) dsh 說(shuō)同樣的話。dsh 會(huì)自動(dòng)調(diào)用Git 插件。插件執(zhí)行真正的git diff命令解析輸出并返回一個(gè)結(jié)構(gòu)化的、易于閱讀的對(duì)比摘要甚至高亮顯示關(guān)鍵變更。這個(gè)過(guò)程中dsh 的核心價(jià)值在于理解意圖將你的自然語(yǔ)言“檢查差異”映射到插件定義的“執(zhí)行 Git diff”操作。管理上下文它知道當(dāng)前工作目錄就是你的項(xiàng)目根目錄。安全調(diào)度在受控的環(huán)境中執(zhí)行插件代碼。呈現(xiàn)結(jié)果將插件返回的結(jié)構(gòu)化數(shù)據(jù)轉(zhuǎn)化為友好的對(duì)話式回復(fù)。因此開(kāi)發(fā) dsh 插件不是你為 AI 寫一個(gè)“腳本”而是為你和你的團(tuán)隊(duì)定義一套可以被自然語(yǔ)言觸發(fā)的、標(biāo)準(zhǔn)化的工程操作協(xié)議。它解決的痛點(diǎn)是“知識(shí)沉淀”和“操作自動(dòng)化”的結(jié)合。2. 核心概念拆解Skill、Manifest、Runtime 與 Tool開(kāi)始編碼前需要掌握四個(gè)核心概念它們構(gòu)成了 dsh 插件開(kāi)發(fā)的基石。2.1 Skill技能/插件這是插件本身。一個(gè) Skill 就是一個(gè)獨(dú)立的、可安裝的單元用于擴(kuò)展 dsh 的能力。它通常是一個(gè)包含特定文件結(jié)構(gòu)的目錄或 Python 包。2.2 Manifest (skill.yaml)這是插件的“身份證”和“說(shuō)明書”。一個(gè)skill.yaml文件定義了插件的一切元信息基礎(chǔ)信息名稱、ID、版本、作者、描述。能力聲明這個(gè)插件提供了哪些“工具”Tools或“動(dòng)作”Actions。配置要求插件運(yùn)行需要哪些環(huán)境變量、權(quán)限或系統(tǒng)命令。依賴關(guān)系需要安裝哪些 Python 包。AI 在決定是否調(diào)用一個(gè)插件時(shí)首先閱讀的就是這個(gè)skill.yaml文件。它的描述description和工具定義必須清晰、準(zhǔn)確否則 AI 無(wú)法正確理解和使用你的插件。2.3 Runtime運(yùn)行時(shí)這是插件代碼執(zhí)行的環(huán)境。dsh 為插件提供了一個(gè)隔離的、安全的運(yùn)行時(shí)環(huán)境通常是一個(gè) Python 環(huán)境并注入了必要的上下文信息如當(dāng)前工作目錄、用戶輸入、會(huì)話歷史等。你的插件代碼在這個(gè) Runtime 中被加載和執(zhí)行。2.4 Tool / Action工具/動(dòng)作這是插件提供的具體功能點(diǎn)。一個(gè)插件可以包含多個(gè) Tool。每個(gè) Tool 需要明確名稱name用于內(nèi)部調(diào)用的標(biāo)識(shí)符。描述description用自然語(yǔ)言描述這個(gè)工具是做什么的。這是最重要的部分直接決定了 AI 能否在合適的時(shí)候調(diào)用它。參數(shù)parameters定義工具接收的輸入?yún)?shù)包括名稱、類型、描述和是否必需。執(zhí)行函數(shù)function當(dāng)工具被調(diào)用時(shí)實(shí)際執(zhí)行的 Python 函數(shù)。它們之間的關(guān)系是一個(gè)Skill通過(guò)Manifest聲明自己包含多個(gè)Tool。當(dāng) dsh 決定調(diào)用某個(gè) Tool 時(shí)它會(huì)在Runtime中加載對(duì)應(yīng)的 Skill 并執(zhí)行相應(yīng)的函數(shù)。3. 環(huán)境準(zhǔn)備安裝 dsh 并搭建開(kāi)發(fā)環(huán)境在開(kāi)發(fā)插件之前你必須先有一個(gè)可以運(yùn)行的 dsh 環(huán)境。這里會(huì)涵蓋從安裝到驗(yàn)證的完整步驟并解決最常見(jiàn)的安裝問(wèn)題。3.1 安裝 DeepSeek Harness (dsh)官方推薦使用 pip 進(jìn)行安裝。請(qǐng)確保你的 Python 版本在 3.8 以上。# 使用 pip 安裝 dsh pip install deepseek-harness安裝完成后在終端驗(yàn)證安裝是否成功# 查看 dsh 版本 dsh --version # 或運(yùn)行 dsh 進(jìn)入交互式命令行 dsh如果你遇到‘dsh’ 不是內(nèi)部或外部命令的錯(cuò)誤請(qǐng)按以下步驟排查檢查 Python 和 Pip確保python --version和pip --version命令能正確執(zhí)行并且你安裝包的 pip 和當(dāng)前使用的 python 是同一個(gè)環(huán)境。檢查 PATH 環(huán)境變量Python 的Scripts目錄Windows或bin目錄macOS/Linux是否已添加到系統(tǒng)的 PATH 環(huán)境變量中。Windows 典型路徑C:\Users\你的用戶名\AppData\Local\Programs\Python\Python3xx\Scripts\macOS/Linux 典型路徑~/.local/bin/或/usr/local/bin/使用 Python 模塊方式運(yùn)行如果 PATH 配置無(wú)誤但仍找不到命令可以暫時(shí)使用python -m harness --version3.2 配置 dsh可選但推薦首次運(yùn)行 dsh 前建議進(jìn)行基礎(chǔ)配置特別是設(shè)置 AI 模型。dsh 本身不提供模型需要你配置一個(gè)后端如 OpenAI API、DeepSeek API 或本地模型。# 啟動(dòng)配置向?qū)?dsh config根據(jù)提示你需要提供模型提供商如openai,deepseek等。API Key對(duì)應(yīng)提供商的有效 API 密鑰。模型名稱如gpt-4,deepseek-chat等。配置完成后你可以與 dsh 進(jìn)行簡(jiǎn)單對(duì)話測(cè)試基礎(chǔ)功能是否正常。3.3 初始化你的第一個(gè)插件項(xiàng)目dsh 提供了腳手架命令來(lái)快速創(chuàng)建插件項(xiàng)目結(jié)構(gòu)。# 創(chuàng)建一個(gè)名為 health-checker 的插件項(xiàng)目 dsh skill create health-checker執(zhí)行命令后它會(huì)引導(dǎo)你輸入一些基本信息如插件名、描述、作者等并自動(dòng)生成一個(gè)標(biāo)準(zhǔn)化的項(xiàng)目目錄。如果該命令不可用你也可以手動(dòng)創(chuàng)建結(jié)構(gòu)如下health-checker/ ├── skill.yaml # 插件清單文件核心 ├── __init__.py # Python包初始化文件 ├── skill.py # 插件主邏輯文件 ├── requirements.txt # Python依賴列表 └── README.md # 項(xiàng)目說(shuō)明文檔現(xiàn)在你的開(kāi)發(fā)環(huán)境已經(jīng)就緒。接下來(lái)我們將深入skill.yaml和skill.py開(kāi)始構(gòu)建邏輯。4. 實(shí)戰(zhàn)開(kāi)發(fā)“項(xiàng)目健康度檢查”插件我們將開(kāi)發(fā)一個(gè)實(shí)用的插件它能夠分析指定 Git 倉(cāng)庫(kù)的“健康度”包括查看未提交的更改、檢查分支是否落后于遠(yuǎn)程、分析最近提交記錄等。這個(gè)插件將涉及文件系統(tǒng)操作、執(zhí)行 Git 命令、解析命令行輸出等常見(jiàn)任務(wù)。4.1 設(shè)計(jì)插件清單 (skill.yaml)skill.yaml是藍(lán)圖。我們首先定義插件提供的兩個(gè)核心工具。# skill.yaml name: Project Health Checker id: com.example.health-checker version: 0.1.0 author: Your Name description: 檢查Git項(xiàng)目的健康狀態(tài)包括未提交的更改、分支同步狀態(tài)和近期提交歷史。 幫助開(kāi)發(fā)者快速了解項(xiàng)目代碼庫(kù)狀況。 runtime: type: python entrypoint: skill:HealthCheckSkill tools: - name: check_git_status description: 檢查當(dāng)前Git倉(cāng)庫(kù)的狀態(tài)。列出所有已修改、未暫存、未跟蹤的文件。 這是一個(gè)輕量級(jí)的快速檢查。 parameters: - name: directory type: string description: 要檢查的Git項(xiàng)目目錄路徑。默認(rèn)為當(dāng)前目錄。 required: false default: . returns: type: object properties: summary: { type: string } modified_files: { type: array, items: { type: string } } untracked_files: { type: array, items: { type: string } } - name: analyze_branch_health description: 深度分析指定分支的健康狀況。包括 1. 該分支是否落后或超前于遠(yuǎn)程跟蹤分支。 2. 最近N條提交的摘要。 這是一個(gè)更全面的分析工具。 parameters: - name: directory type: string description: Git項(xiàng)目目錄路徑。 required: false default: . - name: branch type: string description: 要分析的分支名稱例如 ‘main‘, ‘develop‘。默認(rèn)為當(dāng)前分支。 required: false - name: commit_count type: integer description: 要查看的最近提交數(shù)量默認(rèn)為5條。 required: false default: 5 returns: type: object properties: branch_name: { type: string } remote_tracking: { type: string } ahead_count: { type: integer } behind_count: { type: integer } recent_commits: { type: array, items: { type: string } } health_status: { type: string }關(guān)鍵點(diǎn)解析id必須是全局唯一的通常使用反向域名格式。description務(wù)必詳細(xì)、準(zhǔn)確。AI 主要靠它來(lái)理解工具用途。parameters定義了工具的輸入。required和default字段讓工具更靈活。returns定義了工具的輸出結(jié)構(gòu)。清晰的返回模式有助于 AI 理解和格式化最終回復(fù)給用戶的結(jié)果。runtime.entrypoint指向 Python 模塊中 Skill 類的路徑 (skill:HealthCheckSkill表示skill.py文件中的HealthCheckSkill類)。4.2 實(shí)現(xiàn)插件核心邏輯 (skill.py)接下來(lái)在skill.py中實(shí)現(xiàn)HealthCheckSkill類并完成兩個(gè)工具函數(shù)。# skill.py import os import subprocess import json from typing import Dict, Any, List from harness.skill import BaseSkill, tool class HealthCheckSkill(BaseSkill): 項(xiàng)目健康度檢查技能的核心實(shí)現(xiàn)類。 tool(name“check_git_status”) def check_git_status(self, directory: str “.”) - Dict[str, Any]: 執(zhí)行 git status 命令并解析結(jié)果。 Args: directory: Git 倉(cāng)庫(kù)的路徑。 Returns: 包含狀態(tài)摘要和文件列表的字典。 # 1. 切換到目標(biāo)目錄并驗(yàn)證是否為Git倉(cāng)庫(kù) original_cwd os.getcwd() try: os.chdir(directory) # 檢查.git目錄是否存在 if not os.path.isdir(“.git”): return { “summary”: f“目錄 ‘{directory}‘ 不是一個(gè)Git倉(cāng)庫(kù)。”, “modified_files”: [], “untracked_files”: [] } except Exception as e: return {“error”: f“無(wú)法訪問(wèn)目錄 ‘{directory}‘: {str(e)}”} finally: os.chdir(original_cwd) # 2. 執(zhí)行 git status --porcelain 獲取機(jī)器可讀的輸出 try: result subprocess.run( [“git”, “status”, “--porcelain”], cwddirectory, capture_outputTrue, textTrue, checkTrue ) except subprocess.CalledProcessError as e: return {“error”: f“Git命令執(zhí)行失敗: {e.stderr}”} except FileNotFoundError: return {“error”: “系統(tǒng)中未找到Git命令請(qǐng)確保Git已安裝并配置在PATH中。”} # 3. 解析輸出 output result.stdout.strip() modified_files [] untracked_files [] for line in output.split(‘\n‘): if not line: continue # porcelain格式XY filename # X: 暫存區(qū)狀態(tài) Y: 工作區(qū)狀態(tài) status line[:2] filename line[3:] if status ‘??‘: untracked_files.append(filename) elif status ! ‘ ‘: # 非空狀態(tài)包括 M, A, D, R 等 modified_files.append(filename) # 4. 生成摘要 total_modified len(modified_files) total_untracked len(untracked_files) summary_parts [] if total_modified 0: summary_parts.append(f“有 {total_modified} 個(gè)文件被修改?！? if total_untracked 0: summary_parts.append(f“有 {total_untracked} 個(gè)未跟蹤的新文件。”) if not summary_parts: summary “工作目錄是干凈的沒(méi)有未提交的更改?！?else: summary “ ”.join(summary_parts) return { “summary”: summary, “modified_files”: modified_files, “untracked_files”: untracked_files } tool(name“analyze_branch_health”) def analyze_branch_health(self, directory: str “.”, branch: str None, commit_count: int 5) - Dict[str, Any]: 分析指定分支的健康狀況。 Args: directory: 項(xiàng)目目錄。 branch: 分支名默認(rèn)為當(dāng)前分支。 commit_count: 要分析的最近提交數(shù)量。 Returns: 包含分支同步狀態(tài)和提交歷史的字典。 original_cwd os.getcwd() try: os.chdir(directory) if not os.path.isdir(“.git”): return {“error”: f“目錄 ‘{directory}‘ 不是一個(gè)Git倉(cāng)庫(kù)?！眪 except Exception as e: return {“error”: f“目錄訪問(wèn)錯(cuò)誤: {str(e)}”} finally: os.chdir(original_cwd) result_dict { “branch_name”: branch or “current”, “remote_tracking”: “None”, “ahead_count”: 0, “behind_count”: 0, “recent_commits”: [], “health_status”: “unknown” } try: # 1. 獲取當(dāng)前分支名如果未指定 if not branch: branch_result subprocess.run( [“git”, “branch”, “--show-current”], cwddirectory, capture_outputTrue, textTrue, checkTrue ) branch branch_result.stdout.strip() result_dict[“branch_name”] branch # 2. 獲取遠(yuǎn)程跟蹤分支信息 remote_result subprocess.run( [“git”, “for-each-ref”, f“refs/heads/{branch}”, “--format%(upstream:short)”], cwddirectory, capture_outputTrue, textTrue ) remote_tracking remote_result.stdout.strip() if remote_tracking: result_dict[“remote_tracking”] remote_tracking # 3. 計(jì)算領(lǐng)先/落后于遠(yuǎn)程的提交數(shù) revlist_result subprocess.run( [“git”, “rev-list”, “--left-right”, f“{branch}...{remote_tracking}”], cwddirectory, capture_outputTrue, textTrue ) if revlist_result.stdout: ahead 0 behind 0 for line in revlist_result.stdout.split(‘\n‘): if line.startswith(‘‘): ahead 1 elif line.startswith(‘‘): behind 1 result_dict[“ahead_count”] ahead result_dict[“behind_count”] behind # 4. 獲取最近提交歷史 log_format “%h - %an, %ar : %s” log_result subprocess.run( [“git”, “l(fā)og”, f“-{commit_count}”, “--oneline”, f“--format{log_format}”], cwddirectory, capture_outputTrue, textTrue, checkTrue ) commits [line.strip() for line in log_result.stdout.split(‘\n‘) if line] result_dict[“recent_commits”] commits # 5. 評(píng)估健康狀態(tài)簡(jiǎn)單邏輯示例 if result_dict[“behind_count”] 10: result_dict[“health_status”] “需要關(guān)注嚴(yán)重落后于遠(yuǎn)程” elif result_dict[“behind_count”] 3: result_dict[“health_status”] “良好略有落后” elif result_dict[“ahead_count”] 0 and result_dict[“behind_count”] 0: result_dict[“health_status”] “優(yōu)秀有未推送的提交” else: result_dict[“health_status”] “優(yōu)秀與遠(yuǎn)程同步” except subprocess.CalledProcessError as e: result_dict[“error”] f“Git命令執(zhí)行失敗: {e.stderr}” result_dict[“health_status”] “分析失敗” except Exception as e: result_dict[“error”] f“分析過(guò)程中發(fā)生未知錯(cuò)誤: {str(e)}” result_dict[“health_status”] “分析失敗” return result_dict4.3 定義依賴 (requirements.txt)我們的插件使用了 Python 標(biāo)準(zhǔn)庫(kù)沒(méi)有額外第三方依賴。但這是一個(gè)好習(xí)慣明確聲明依賴。# requirements.txt # 本項(xiàng)目暫無(wú)額外第三方依賴。 # 未來(lái)如需添加例如 requests可在此處注明 # requests2.28.05. 本地安裝、調(diào)試與測(cè)試插件插件代碼寫完后必須在本地安裝并測(cè)試確保它能被 dsh 正確識(shí)別和調(diào)用。5.1 在開(kāi)發(fā)模式下安裝插件進(jìn)入插件項(xiàng)目根目錄使用 dsh 命令進(jìn)行本地安裝。# 確保當(dāng)前目錄是 health-checker/ cd /path/to/health-checker # 在開(kāi)發(fā)模式下安裝插件 dsh skill install --dev .--dev參數(shù)表示以開(kāi)發(fā)模式安裝dsh 會(huì)鏈接到當(dāng)前目錄的源代碼。這意味著你對(duì)skill.py或skill.yaml的任何修改在重新加載后都會(huì)立即生效無(wú)需重復(fù)安裝。5.2 驗(yàn)證插件安裝安裝成功后可以通過(guò)以下命令查看已安裝的插件列表確認(rèn)我們的插件在其中。# 列出所有已安裝的技能 dsh skill list你應(yīng)該能看到com.example.health-checker(Project Health Checker) 出現(xiàn)在列表中。5.3 與插件交互測(cè)試現(xiàn)在啟動(dòng) dsh 的交互式對(duì)話測(cè)試插件功能。# 啟動(dòng) dsh 對(duì)話 dsh在 dsh 的對(duì)話界面中嘗試輸入以下指令觀察 AI 是否會(huì)調(diào)用我們的插件并返回結(jié)構(gòu)化的結(jié)果測(cè)試輕量檢查“幫我檢查一下當(dāng)前這個(gè)項(xiàng)目的 Git 狀態(tài)?！睖y(cè)試深度分析“分析一下 main 分支的健康狀況看看最近 3 次提交?！睖y(cè)試路徑參數(shù)“檢查/home/user/my-project目錄下的 Git 狀態(tài)?！崩硐氲慕换チ鞒淌悄爿斎胱匀徽Z(yǔ)言指令。dsh 理解意圖識(shí)別出需要調(diào)用health-checker插件的某個(gè)工具。dsh 在后臺(tái)執(zhí)行插件代碼。dsh 將插件返回的 JSON 結(jié)果轉(zhuǎn)化為一段清晰、友好的文本回復(fù)給你。5.4 調(diào)試與日志查看如果插件沒(méi)有被調(diào)用或者調(diào)用后出錯(cuò)你需要進(jìn)行調(diào)試。檢查工具描述確保skill.yaml中tools.description足夠清晰能讓 AI 準(zhǔn)確匹配。查看 dsh 日志dsh 運(yùn)行時(shí)通常會(huì)輸出詳細(xì)日志其中會(huì)記錄意圖識(shí)別、工具選擇和調(diào)用過(guò)程。根據(jù)你的安裝方式日志可能輸出到終端或特定日志文件。在插件代碼中添加日志你可以在skill.py中使用print語(yǔ)句或 Python 的logging模塊輸出調(diào)試信息。在開(kāi)發(fā)模式下這些信息通常會(huì)顯示在 dsh 的后臺(tái)輸出中。# 在 skill.py 的函數(shù)中添加簡(jiǎn)單調(diào)試信息 def check_git_status(self, directory: str “.”): print(f“[DEBUG] check_git_status called with directory: {directory}”) # 調(diào)試輸出 # ... 其余代碼 ...6. 插件發(fā)布到 dsh 插件市場(chǎng)當(dāng)插件在本地測(cè)試穩(wěn)定后你可以考慮將其發(fā)布到 dsh 的插件市場(chǎng)如 dshmarket供其他開(kāi)發(fā)者使用。發(fā)布前準(zhǔn)備完善skill.yaml確保所有描述準(zhǔn)確版本號(hào)符合語(yǔ)義化版本規(guī)范如0.1.0。編寫清晰的README.md說(shuō)明插件功能、安裝方法、使用示例和配置要求。代碼清理移除調(diào)試用的print語(yǔ)句確保代碼整潔。選擇發(fā)布平臺(tái)目前 dsh 插件可能支持發(fā)布到官方市場(chǎng)或第三方索引。請(qǐng)查閱最新的 dsh 文檔獲取發(fā)布命令。一個(gè)常見(jiàn)的發(fā)布流程可能類似于# 1. 打包插件 (假設(shè)命令為 skill pack) dsh skill pack # 2. 發(fā)布到市場(chǎng) (假設(shè)命令為 skill publish) dsh skill publish --registry https://market.dsh.ai請(qǐng)注意發(fā)布前務(wù)必仔細(xì)閱讀目標(biāo)市場(chǎng)的發(fā)布協(xié)議和規(guī)范確保你的插件不包含惡意代碼且符合安全標(biāo)準(zhǔn)。7. 常見(jiàn)問(wèn)題與排查思路在開(kāi)發(fā)和使用 dsh 插件過(guò)程中你可能會(huì)遇到以下典型問(wèn)題。問(wèn)題現(xiàn)象可能原因排查方式解決方案dsh命令未找到1. Python Scripts 目錄未在 PATH 中。2. pip 安裝失敗或未安裝。1. 執(zhí)行python -m harness --version測(cè)試。2. 檢查 pip listgrep harness。插件安裝失敗1.skill.yaml格式錯(cuò)誤。2. 依賴 (requirements.txt) 安裝失敗。3. 插件 ID 沖突。1. 使用 YAML 在線校驗(yàn)器檢查skill.yaml。2. 查看安裝錯(cuò)誤信息。3. 檢查dsh skill list。1. 修正 YAML 語(yǔ)法。2. 手動(dòng)安裝依賴或解決網(wǎng)絡(luò)問(wèn)題。3. 修改插件 ID。AI 不調(diào)用我的插件1. 工具描述 (description) 不清晰。2. 用戶指令與工具描述匹配度低。3. 插件未正確加載。1. 在 dsh 對(duì)話中直接輸入“使用[插件名]做[某事]”。2. 查看 dsh 的意圖識(shí)別日志。1. 重寫skill.yaml中的描述使其更貼近自然語(yǔ)言場(chǎng)景。2. 確保插件已通過(guò)dsh skill list列出。插件被調(diào)用但執(zhí)行出錯(cuò)1. 插件代碼存在語(yǔ)法或運(yùn)行時(shí)錯(cuò)誤。2. 缺少系統(tǒng)依賴如 Git。3. 權(quán)限不足如訪問(wèn)特定目錄。1. 查看 dsh 的錯(cuò)誤日志或插件函數(shù)返回的 error 字段。2. 在插件代碼開(kāi)頭添加更完善的異常捕獲和日志。1. 在本地獨(dú)立運(yùn)行插件代碼片段進(jìn)行調(diào)試。2. 在插件文檔中明確聲明系統(tǒng)依賴。3. 在代碼中檢查路徑和權(quán)限。插件返回結(jié)果 AI 不理解返回的 JSON 數(shù)據(jù)結(jié)構(gòu)與skill.yaml中returns定義不匹配。對(duì)比插件函數(shù)實(shí)際返回的字典與skill.yaml中定義的properties。確保返回的字典鍵名和類型與returns定義完全一致。8. 插件開(kāi)發(fā)最佳實(shí)踐與進(jìn)階建議掌握了基礎(chǔ)開(kāi)發(fā)流程后遵循以下最佳實(shí)踐能讓你的插件更健壯、更易用、更強(qiáng)大。8.1 設(shè)計(jì)原則單一職責(zé)一個(gè)工具只做一件事并把它做好。避免創(chuàng)建“瑞士軍刀”式的巨型工具。描述即契約skill.yaml中的description是給 AI 看的“產(chǎn)品說(shuō)明書”務(wù)必用完整、無(wú)歧義的自然句子描述工具的功能、輸入和輸出。防御性編程插件代碼必須健壯。始終驗(yàn)證輸入?yún)?shù)處理外部命令可能失敗的情況如 Git 未安裝、網(wǎng)絡(luò)超時(shí)并進(jìn)行詳細(xì)的錯(cuò)誤處理返回友好的錯(cuò)誤信息。8.2 工程化建議版本管理使用語(yǔ)義化版本控制 (major.minor.patch)。每次發(fā)布新版本時(shí)更新skill.yaml中的version字段。依賴管理在requirements.txt中精確指定依賴版本如requests2.28.0以避免未來(lái)因依賴更新導(dǎo)致插件崩潰。單元測(cè)試為你的工具函數(shù)編寫單元測(cè)試。雖然 dsh 插件框架可能沒(méi)有標(biāo)準(zhǔn)的測(cè)試運(yùn)行器但你可以單獨(dú)測(cè)試你的 Python 函數(shù)確保其邏輯正確。配置化將硬編碼的常量如 API 端點(diǎn)、默認(rèn)值提取到配置中可以通過(guò)環(huán)境變量或配置文件注入提高插件的靈活性。8.3 進(jìn)階能力探索狀態(tài)管理復(fù)雜的插件可能需要維護(hù)跨多次調(diào)用的狀態(tài)。研究 dsh SDK 是否提供了會(huì)話Session或上下文Context存儲(chǔ)機(jī)制。流式輸出對(duì)于執(zhí)行時(shí)間較長(zhǎng)的任務(wù)研究是否支持流式Streaming返回結(jié)果以提升用戶體驗(yàn)。與其他服務(wù)集成你的插件不僅可以調(diào)用本地命令更強(qiáng)大的用途是作為“適配器”連接 dsh 與你團(tuán)隊(duì)內(nèi)部的 CI/CD 系統(tǒng)、項(xiàng)目管理工具Jira、監(jiān)控系統(tǒng)Grafana等通過(guò) API 調(diào)用實(shí)現(xiàn)深度自動(dòng)化。開(kāi)發(fā) DeepSeek Harness 插件本質(zhì)上是在定義人機(jī)協(xié)作的新接口。你不再需要記憶復(fù)雜的命令和參數(shù)而是用你最習(xí)慣的自然語(yǔ)言去驅(qū)動(dòng)一個(gè)由你親手定義和打磨的自動(dòng)化工作流。從今天這個(gè)簡(jiǎn)單的“健康檢查”插件起步你可以逐步將團(tuán)隊(duì)里所有重復(fù)、繁瑣的研發(fā)操作都封裝成 Skills最終構(gòu)建一個(gè)完全貼合你團(tuán)隊(duì)需求的、智能化的開(kāi)發(fā)助手環(huán)境。