如果你是一名开发者最近可能已经注意到一个现象无论是 GitHub 趋势榜还是技术社区的讨论围绕“AI 编程助手”的叙事正在发生一次微妙的转向。过去我们谈论的是如何用 Copilot 补全代码或是如何向 ChatGPT 描述需求。但现在一个更深入的问题被提了出来如何让 AI 助手真正理解我的项目上下文、我的技术栈、我的团队规范并在此基础上自动化执行那些重复、繁琐但至关重要的开发任务这正是 DeepSeek Harness简称 dsh试图回答的问题。它不是一个简单的代码补全工具而是一个旨在将 AI 深度集成到开发者工作流中的“智能开发环境”。其核心在于“插件”Skill生态。通过插件你可以教会 dsh 如何与你的 Git 仓库、数据库、API、甚至内部部署的系统进行交互从而将自然语言指令转化为一系列精准的自动化操作。然而当你兴冲冲地打开官方文档准备开发自己的第一个插件时可能会立刻陷入困惑概念抽象、示例零散、社区资料匮乏。你搜索“dsh 插件开发教程”找到的往往是“安装教程”或“使用体验”关于“如何从零构建一个真正有用的插件”的实战指南几乎是一片空白。这篇文章的目的就是填补这片空白。我将带你从零开始深入 DeepSeek Harness 插件开发的核心。我们不会停留在概念复述而是通过构建一个真实可用的“项目健康度检查插件”来拆解整个开发流程。你将清晰地理解dsh 插件到底是什么它与 VSCode 插件、浏览器插件有何本质不同开发一个插件的完整生命周期是怎样的从环境搭建、项目初始化、代码编写、本地调试到最终发布。如何设计一个“好用”的插件如何定义清晰的意图Intent、处理复杂的用户输入、与外部服务安全交互开发过程中有哪些“坑”如何调试、如何测试、如何确保插件的稳定性和安全性本文假设你具备基本的 Python 开发经验并对命令行操作有一定了解。我们的目标不仅是让你“跑通”一个示例更是让你掌握设计并实现一个能解决实际工程问题的 dsh 插件的核心能力。1. 重新理解 DeepSeek Harness 与插件它到底解决了什么痛点在开始写代码之前我们必须先厘清一个根本问题为什么需要 dsh 和它的插件体系这能帮助我们判断投入时间学习它是否值得。传统的 AI 编程助手如 Copilot、ChatGPT工作模式是“问答式”或“补全式”。你提出一个问题或一段注释它生成一段代码。这种模式的瓶颈在于缺乏上下文AI 不知道你项目的完整结构、依赖关系、配置文件。无法执行AI 可以告诉你“运行git status”但你需要自己切换到终端去执行。难以复用一套复杂的操作流程如“为新功能创建分支、初始化模块、更新文档”无法被沉淀为可一键触发的自动化脚本。DeepSeek Harness 的定位是“AI-Native 的集成开发环境”。它试图将 AI 作为整个开发工作流的“大脑”和“执行臂”。而插件就是为这个“执行臂”安装的“工具手”。一个插件的本质是一组可供 AI 调用的、定义清晰的能力Capabilities。举个例子没有插件你对 dsh 说“检查一下主分支和开发分支的差异。”dsh 可能只能回复你一个 Git 命令git diff main..develop。有了 Git 插件你对 dsh 说同样的话。dsh 会自动调用Git 插件。插件执行真正的git diff命令解析输出并返回一个结构化的、易于阅读的对比摘要甚至高亮显示关键变更。这个过程中dsh 的核心价值在于理解意图将你的自然语言“检查差异”映射到插件定义的“执行 Git diff”操作。管理上下文它知道当前工作目录就是你的项目根目录。安全调度在受控的环境中执行插件代码。呈现结果将插件返回的结构化数据转化为友好的对话式回复。因此开发 dsh 插件不是你为 AI 写一个“脚本”而是为你和你的团队定义一套可以被自然语言触发的、标准化的工程操作协议。它解决的痛点是“知识沉淀”和“操作自动化”的结合。2. 核心概念拆解Skill、Manifest、Runtime 与 Tool开始编码前需要掌握四个核心概念它们构成了 dsh 插件开发的基石。2.1 Skill技能/插件这是插件本身。一个 Skill 就是一个独立的、可安装的单元用于扩展 dsh 的能力。它通常是一个包含特定文件结构的目录或 Python 包。2.2 Manifest (skill.yaml)这是插件的“身份证”和“说明书”。一个skill.yaml文件定义了插件的一切元信息基础信息名称、ID、版本、作者、描述。能力声明这个插件提供了哪些“工具”Tools或“动作”Actions。配置要求插件运行需要哪些环境变量、权限或系统命令。依赖关系需要安装哪些 Python 包。AI 在决定是否调用一个插件时首先阅读的就是这个skill.yaml文件。它的描述description和工具定义必须清晰、准确否则 AI 无法正确理解和使用你的插件。2.3 Runtime运行时这是插件代码执行的环境。dsh 为插件提供了一个隔离的、安全的运行时环境通常是一个 Python 环境并注入了必要的上下文信息如当前工作目录、用户输入、会话历史等。你的插件代码在这个 Runtime 中被加载和执行。2.4 Tool / Action工具/动作这是插件提供的具体功能点。一个插件可以包含多个 Tool。每个 Tool 需要明确名称name用于内部调用的标识符。描述description用自然语言描述这个工具是做什么的。这是最重要的部分直接决定了 AI 能否在合适的时候调用它。参数parameters定义工具接收的输入参数包括名称、类型、描述和是否必需。执行函数function当工具被调用时实际执行的 Python 函数。它们之间的关系是一个Skill通过Manifest声明自己包含多个Tool。当 dsh 决定调用某个 Tool 时它会在Runtime中加载对应的 Skill 并执行相应的函数。3. 环境准备安装 dsh 并搭建开发环境在开发插件之前你必须先有一个可以运行的 dsh 环境。这里会涵盖从安装到验证的完整步骤并解决最常见的安装问题。3.1 安装 DeepSeek Harness (dsh)官方推荐使用 pip 进行安装。请确保你的 Python 版本在 3.8 以上。# 使用 pip 安装 dsh pip install deepseek-harness安装完成后在终端验证安装是否成功# 查看 dsh 版本 dsh --version # 或运行 dsh 进入交互式命令行 dsh如果你遇到‘dsh’ 不是内部或外部命令的错误请按以下步骤排查检查 Python 和 Pip确保python --version和pip --version命令能正确执行并且你安装包的 pip 和当前使用的 python 是同一个环境。检查 PATH 环境变量Python 的Scripts目录Windows或bin目录macOS/Linux是否已添加到系统的 PATH 环境变量中。Windows 典型路径C:\Users\你的用户名\AppData\Local\Programs\Python\Python3xx\Scripts\macOS/Linux 典型路径~/.local/bin/或/usr/local/bin/使用 Python 模块方式运行如果 PATH 配置无误但仍找不到命令可以暂时使用python -m harness --version3.2 配置 dsh可选但推荐首次运行 dsh 前建议进行基础配置特别是设置 AI 模型。dsh 本身不提供模型需要你配置一个后端如 OpenAI API、DeepSeek API 或本地模型。# 启动配置向导 dsh config根据提示你需要提供模型提供商如openai,deepseek等。API Key对应提供商的有效 API 密钥。模型名称如gpt-4,deepseek-chat等。配置完成后你可以与 dsh 进行简单对话测试基础功能是否正常。3.3 初始化你的第一个插件项目dsh 提供了脚手架命令来快速创建插件项目结构。# 创建一个名为 health-checker 的插件项目 dsh skill create health-checker执行命令后它会引导你输入一些基本信息如插件名、描述、作者等并自动生成一个标准化的项目目录。如果该命令不可用你也可以手动创建结构如下health-checker/ ├── skill.yaml # 插件清单文件核心 ├── __init__.py # Python包初始化文件 ├── skill.py # 插件主逻辑文件 ├── requirements.txt # Python依赖列表 └── README.md # 项目说明文档现在你的开发环境已经就绪。接下来我们将深入skill.yaml和skill.py开始构建逻辑。4. 实战开发“项目健康度检查”插件我们将开发一个实用的插件它能够分析指定 Git 仓库的“健康度”包括查看未提交的更改、检查分支是否落后于远程、分析最近提交记录等。这个插件将涉及文件系统操作、执行 Git 命令、解析命令行输出等常见任务。4.1 设计插件清单 (skill.yaml)skill.yaml是蓝图。我们首先定义插件提供的两个核心工具。# skill.yaml name: Project Health Checker id: com.example.health-checker version: 0.1.0 author: Your Name description: 检查Git项目的健康状态包括未提交的更改、分支同步状态和近期提交历史。 帮助开发者快速了解项目代码库状况。 runtime: type: python entrypoint: skill:HealthCheckSkill tools: - name: check_git_status description: 检查当前Git仓库的状态。列出所有已修改、未暂存、未跟踪的文件。 这是一个轻量级的快速检查。 parameters: - name: directory type: string description: 要检查的Git项目目录路径。默认为当前目录。 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. 该分支是否落后或超前于远程跟踪分支。 2. 最近N条提交的摘要。 这是一个更全面的分析工具。 parameters: - name: directory type: string description: Git项目目录路径。 required: false default: . - name: branch type: string description: 要分析的分支名称例如 ‘main‘, ‘develop‘。默认为当前分支。 required: false - name: commit_count type: integer description: 要查看的最近提交数量默认为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 }关键点解析id必须是全局唯一的通常使用反向域名格式。description务必详细、准确。AI 主要靠它来理解工具用途。parameters定义了工具的输入。required和default字段让工具更灵活。returns定义了工具的输出结构。清晰的返回模式有助于 AI 理解和格式化最终回复给用户的结果。runtime.entrypoint指向 Python 模块中 Skill 类的路径 (skill:HealthCheckSkill表示skill.py文件中的HealthCheckSkill类)。4.2 实现插件核心逻辑 (skill.py)接下来在skill.py中实现HealthCheckSkill类并完成两个工具函数。# skill.py import os import subprocess import json from typing import Dict, Any, List from harness.skill import BaseSkill, tool class HealthCheckSkill(BaseSkill): 项目健康度检查技能的核心实现类。 tool(name“check_git_status”) def check_git_status(self, directory: str “.”) - Dict[str, Any]: 执行 git status 命令并解析结果。 Args: directory: Git 仓库的路径。 Returns: 包含状态摘要和文件列表的字典。 # 1. 切换到目标目录并验证是否为Git仓库 original_cwd os.getcwd() try: os.chdir(directory) # 检查.git目录是否存在 if not os.path.isdir(“.git”): return { “summary”: f“目录 ‘{directory}‘ 不是一个Git仓库。”, “modified_files”: [], “untracked_files”: [] } except Exception as e: return {“error”: f“无法访问目录 ‘{directory}‘: {str(e)}”} finally: os.chdir(original_cwd) # 2. 执行 git status --porcelain 获取机器可读的输出 try: result subprocess.run( [“git”, “status”, “--porcelain”], cwddirectory, capture_outputTrue, textTrue, checkTrue ) except subprocess.CalledProcessError as e: return {“error”: f“Git命令执行失败: {e.stderr}”} except FileNotFoundError: return {“error”: “系统中未找到Git命令请确保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: 暂存区状态 Y: 工作区状态 status line[:2] filename line[3:] if status ‘??‘: untracked_files.append(filename) elif status ! ‘ ‘: # 非空状态包括 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} 个文件被修改。”) if total_untracked 0: summary_parts.append(f“有 {total_untracked} 个未跟踪的新文件。”) if not summary_parts: summary “工作目录是干净的没有未提交的更改。” 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: 项目目录。 branch: 分支名默认为当前分支。 commit_count: 要分析的最近提交数量。 Returns: 包含分支同步状态和提交历史的字典。 original_cwd os.getcwd() try: os.chdir(directory) if not os.path.isdir(“.git”): return {“error”: f“目录 ‘{directory}‘ 不是一个Git仓库。”} except Exception as e: return {“error”: f“目录访问错误: {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. 获取当前分支名如果未指定 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. 获取远程跟踪分支信息 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. 计算领先/落后于远程的提交数 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”, “log”, 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. 评估健康状态简单逻辑示例 if result_dict[“behind_count”] 10: result_dict[“health_status”] “需要关注严重落后于远程” 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”] “优秀有未推送的提交” else: result_dict[“health_status”] “优秀与远程同步” except subprocess.CalledProcessError as e: result_dict[“error”] f“Git命令执行失败: {e.stderr}” result_dict[“health_status”] “分析失败” except Exception as e: result_dict[“error”] f“分析过程中发生未知错误: {str(e)}” result_dict[“health_status”] “分析失败” return result_dict4.3 定义依赖 (requirements.txt)我们的插件使用了 Python 标准库没有额外第三方依赖。但这是一个好习惯明确声明依赖。# requirements.txt # 本项目暂无额外第三方依赖。 # 未来如需添加例如 requests可在此处注明 # requests2.28.05. 本地安装、调试与测试插件插件代码写完后必须在本地安装并测试确保它能被 dsh 正确识别和调用。5.1 在开发模式下安装插件进入插件项目根目录使用 dsh 命令进行本地安装。# 确保当前目录是 health-checker/ cd /path/to/health-checker # 在开发模式下安装插件 dsh skill install --dev .--dev参数表示以开发模式安装dsh 会链接到当前目录的源代码。这意味着你对skill.py或skill.yaml的任何修改在重新加载后都会立即生效无需重复安装。5.2 验证插件安装安装成功后可以通过以下命令查看已安装的插件列表确认我们的插件在其中。# 列出所有已安装的技能 dsh skill list你应该能看到com.example.health-checker(Project Health Checker) 出现在列表中。5.3 与插件交互测试现在启动 dsh 的交互式对话测试插件功能。# 启动 dsh 对话 dsh在 dsh 的对话界面中尝试输入以下指令观察 AI 是否会调用我们的插件并返回结构化的结果测试轻量检查“帮我检查一下当前这个项目的 Git 状态。”测试深度分析“分析一下 main 分支的健康状况看看最近 3 次提交。”测试路径参数“检查/home/user/my-project目录下的 Git 状态。”理想的交互流程是你输入自然语言指令。dsh 理解意图识别出需要调用health-checker插件的某个工具。dsh 在后台执行插件代码。dsh 将插件返回的 JSON 结果转化为一段清晰、友好的文本回复给你。5.4 调试与日志查看如果插件没有被调用或者调用后出错你需要进行调试。检查工具描述确保skill.yaml中tools.description足够清晰能让 AI 准确匹配。查看 dsh 日志dsh 运行时通常会输出详细日志其中会记录意图识别、工具选择和调用过程。根据你的安装方式日志可能输出到终端或特定日志文件。在插件代码中添加日志你可以在skill.py中使用print语句或 Python 的logging模块输出调试信息。在开发模式下这些信息通常会显示在 dsh 的后台输出中。# 在 skill.py 的函数中添加简单调试信息 def check_git_status(self, directory: str “.”): print(f“[DEBUG] check_git_status called with directory: {directory}”) # 调试输出 # ... 其余代码 ...6. 插件发布到 dsh 插件市场当插件在本地测试稳定后你可以考虑将其发布到 dsh 的插件市场如 dshmarket供其他开发者使用。发布前准备完善skill.yaml确保所有描述准确版本号符合语义化版本规范如0.1.0。编写清晰的README.md说明插件功能、安装方法、使用示例和配置要求。代码清理移除调试用的print语句确保代码整洁。选择发布平台目前 dsh 插件可能支持发布到官方市场或第三方索引。请查阅最新的 dsh 文档获取发布命令。一个常见的发布流程可能类似于# 1. 打包插件 (假设命令为 skill pack) dsh skill pack # 2. 发布到市场 (假设命令为 skill publish) dsh skill publish --registry https://market.dsh.ai请注意发布前务必仔细阅读目标市场的发布协议和规范确保你的插件不包含恶意代码且符合安全标准。7. 常见问题与排查思路在开发和使用 dsh 插件过程中你可能会遇到以下典型问题。问题现象可能原因排查方式解决方案dsh命令未找到1. Python Scripts 目录未在 PATH 中。2. pip 安装失败或未安装。1. 执行python -m harness --version测试。2. 检查 pip listgrep harness。插件安装失败1.skill.yaml格式错误。2. 依赖 (requirements.txt) 安装失败。3. 插件 ID 冲突。1. 使用 YAML 在线校验器检查skill.yaml。2. 查看安装错误信息。3. 检查dsh skill list。1. 修正 YAML 语法。2. 手动安装依赖或解决网络问题。3. 修改插件 ID。AI 不调用我的插件1. 工具描述 (description) 不清晰。2. 用户指令与工具描述匹配度低。3. 插件未正确加载。1. 在 dsh 对话中直接输入“使用[插件名]做[某事]”。2. 查看 dsh 的意图识别日志。1. 重写skill.yaml中的描述使其更贴近自然语言场景。2. 确保插件已通过dsh skill list列出。插件被调用但执行出错1. 插件代码存在语法或运行时错误。2. 缺少系统依赖如 Git。3. 权限不足如访问特定目录。1. 查看 dsh 的错误日志或插件函数返回的 error 字段。2. 在插件代码开头添加更完善的异常捕获和日志。1. 在本地独立运行插件代码片段进行调试。2. 在插件文档中明确声明系统依赖。3. 在代码中检查路径和权限。插件返回结果 AI 不理解返回的 JSON 数据结构与skill.yaml中returns定义不匹配。对比插件函数实际返回的字典与skill.yaml中定义的properties。确保返回的字典键名和类型与returns定义完全一致。8. 插件开发最佳实践与进阶建议掌握了基础开发流程后遵循以下最佳实践能让你的插件更健壮、更易用、更强大。8.1 设计原则单一职责一个工具只做一件事并把它做好。避免创建“瑞士军刀”式的巨型工具。描述即契约skill.yaml中的description是给 AI 看的“产品说明书”务必用完整、无歧义的自然句子描述工具的功能、输入和输出。防御性编程插件代码必须健壮。始终验证输入参数处理外部命令可能失败的情况如 Git 未安装、网络超时并进行详细的错误处理返回友好的错误信息。8.2 工程化建议版本管理使用语义化版本控制 (major.minor.patch)。每次发布新版本时更新skill.yaml中的version字段。依赖管理在requirements.txt中精确指定依赖版本如requests2.28.0以避免未来因依赖更新导致插件崩溃。单元测试为你的工具函数编写单元测试。虽然 dsh 插件框架可能没有标准的测试运行器但你可以单独测试你的 Python 函数确保其逻辑正确。配置化将硬编码的常量如 API 端点、默认值提取到配置中可以通过环境变量或配置文件注入提高插件的灵活性。8.3 进阶能力探索状态管理复杂的插件可能需要维护跨多次调用的状态。研究 dsh SDK 是否提供了会话Session或上下文Context存储机制。流式输出对于执行时间较长的任务研究是否支持流式Streaming返回结果以提升用户体验。与其他服务集成你的插件不仅可以调用本地命令更强大的用途是作为“适配器”连接 dsh 与你团队内部的 CI/CD 系统、项目管理工具Jira、监控系统Grafana等通过 API 调用实现深度自动化。开发 DeepSeek Harness 插件本质上是在定义人机协作的新接口。你不再需要记忆复杂的命令和参数而是用你最习惯的自然语言去驱动一个由你亲手定义和打磨的自动化工作流。从今天这个简单的“健康检查”插件起步你可以逐步将团队里所有重复、繁琐的研发操作都封装成 Skills最终构建一个完全贴合你团队需求的、智能化的开发助手环境。 DeepSeek Harness插件开发实战：从零构建AI驱动的自动化开发工具
如果你是一名开发者最近可能已经注意到一个现象无论是 GitHub 趋势榜还是技术社区的讨论围绕“AI 编程助手”的叙事正在发生一次微妙的转向。过去我们谈论的是如何用 Copilot 补全代码或是如何向 ChatGPT 描述需求。但现在一个更深入的问题被提了出来如何让 AI 助手真正理解我的项目上下文、我的技术栈、我的团队规范并在此基础上自动化执行那些重复、繁琐但至关重要的开发任务这正是 DeepSeek Harness简称 dsh试图回答的问题。它不是一个简单的代码补全工具而是一个旨在将 AI 深度集成到开发者工作流中的“智能开发环境”。其核心在于“插件”Skill生态。通过插件你可以教会 dsh 如何与你的 Git 仓库、数据库、API、甚至内部部署的系统进行交互从而将自然语言指令转化为一系列精准的自动化操作。然而当你兴冲冲地打开官方文档准备开发自己的第一个插件时可能会立刻陷入困惑概念抽象、示例零散、社区资料匮乏。你搜索“dsh 插件开发教程”找到的往往是“安装教程”或“使用体验”关于“如何从零构建一个真正有用的插件”的实战指南几乎是一片空白。这篇文章的目的就是填补这片空白。我将带你从零开始深入 DeepSeek Harness 插件开发的核心。我们不会停留在概念复述而是通过构建一个真实可用的“项目健康度检查插件”来拆解整个开发流程。你将清晰地理解dsh 插件到底是什么它与 VSCode 插件、浏览器插件有何本质不同开发一个插件的完整生命周期是怎样的从环境搭建、项目初始化、代码编写、本地调试到最终发布。如何设计一个“好用”的插件如何定义清晰的意图Intent、处理复杂的用户输入、与外部服务安全交互开发过程中有哪些“坑”如何调试、如何测试、如何确保插件的稳定性和安全性本文假设你具备基本的 Python 开发经验并对命令行操作有一定了解。我们的目标不仅是让你“跑通”一个示例更是让你掌握设计并实现一个能解决实际工程问题的 dsh 插件的核心能力。1. 重新理解 DeepSeek Harness 与插件它到底解决了什么痛点在开始写代码之前我们必须先厘清一个根本问题为什么需要 dsh 和它的插件体系这能帮助我们判断投入时间学习它是否值得。传统的 AI 编程助手如 Copilot、ChatGPT工作模式是“问答式”或“补全式”。你提出一个问题或一段注释它生成一段代码。这种模式的瓶颈在于缺乏上下文AI 不知道你项目的完整结构、依赖关系、配置文件。无法执行AI 可以告诉你“运行git status”但你需要自己切换到终端去执行。难以复用一套复杂的操作流程如“为新功能创建分支、初始化模块、更新文档”无法被沉淀为可一键触发的自动化脚本。DeepSeek Harness 的定位是“AI-Native 的集成开发环境”。它试图将 AI 作为整个开发工作流的“大脑”和“执行臂”。而插件就是为这个“执行臂”安装的“工具手”。一个插件的本质是一组可供 AI 调用的、定义清晰的能力Capabilities。举个例子没有插件你对 dsh 说“检查一下主分支和开发分支的差异。”dsh 可能只能回复你一个 Git 命令git diff main..develop。有了 Git 插件你对 dsh 说同样的话。dsh 会自动调用Git 插件。插件执行真正的git diff命令解析输出并返回一个结构化的、易于阅读的对比摘要甚至高亮显示关键变更。这个过程中dsh 的核心价值在于理解意图将你的自然语言“检查差异”映射到插件定义的“执行 Git diff”操作。管理上下文它知道当前工作目录就是你的项目根目录。安全调度在受控的环境中执行插件代码。呈现结果将插件返回的结构化数据转化为友好的对话式回复。因此开发 dsh 插件不是你为 AI 写一个“脚本”而是为你和你的团队定义一套可以被自然语言触发的、标准化的工程操作协议。它解决的痛点是“知识沉淀”和“操作自动化”的结合。2. 核心概念拆解Skill、Manifest、Runtime 与 Tool开始编码前需要掌握四个核心概念它们构成了 dsh 插件开发的基石。2.1 Skill技能/插件这是插件本身。一个 Skill 就是一个独立的、可安装的单元用于扩展 dsh 的能力。它通常是一个包含特定文件结构的目录或 Python 包。2.2 Manifest (skill.yaml)这是插件的“身份证”和“说明书”。一个skill.yaml文件定义了插件的一切元信息基础信息名称、ID、版本、作者、描述。能力声明这个插件提供了哪些“工具”Tools或“动作”Actions。配置要求插件运行需要哪些环境变量、权限或系统命令。依赖关系需要安装哪些 Python 包。AI 在决定是否调用一个插件时首先阅读的就是这个skill.yaml文件。它的描述description和工具定义必须清晰、准确否则 AI 无法正确理解和使用你的插件。2.3 Runtime运行时这是插件代码执行的环境。dsh 为插件提供了一个隔离的、安全的运行时环境通常是一个 Python 环境并注入了必要的上下文信息如当前工作目录、用户输入、会话历史等。你的插件代码在这个 Runtime 中被加载和执行。2.4 Tool / Action工具/动作这是插件提供的具体功能点。一个插件可以包含多个 Tool。每个 Tool 需要明确名称name用于内部调用的标识符。描述description用自然语言描述这个工具是做什么的。这是最重要的部分直接决定了 AI 能否在合适的时候调用它。参数parameters定义工具接收的输入参数包括名称、类型、描述和是否必需。执行函数function当工具被调用时实际执行的 Python 函数。它们之间的关系是一个Skill通过Manifest声明自己包含多个Tool。当 dsh 决定调用某个 Tool 时它会在Runtime中加载对应的 Skill 并执行相应的函数。3. 环境准备安装 dsh 并搭建开发环境在开发插件之前你必须先有一个可以运行的 dsh 环境。这里会涵盖从安装到验证的完整步骤并解决最常见的安装问题。3.1 安装 DeepSeek Harness (dsh)官方推荐使用 pip 进行安装。请确保你的 Python 版本在 3.8 以上。# 使用 pip 安装 dsh pip install deepseek-harness安装完成后在终端验证安装是否成功# 查看 dsh 版本 dsh --version # 或运行 dsh 进入交互式命令行 dsh如果你遇到‘dsh’ 不是内部或外部命令的错误请按以下步骤排查检查 Python 和 Pip确保python --version和pip --version命令能正确执行并且你安装包的 pip 和当前使用的 python 是同一个环境。检查 PATH 环境变量Python 的Scripts目录Windows或bin目录macOS/Linux是否已添加到系统的 PATH 环境变量中。Windows 典型路径C:\Users\你的用户名\AppData\Local\Programs\Python\Python3xx\Scripts\macOS/Linux 典型路径~/.local/bin/或/usr/local/bin/使用 Python 模块方式运行如果 PATH 配置无误但仍找不到命令可以暂时使用python -m harness --version3.2 配置 dsh可选但推荐首次运行 dsh 前建议进行基础配置特别是设置 AI 模型。dsh 本身不提供模型需要你配置一个后端如 OpenAI API、DeepSeek API 或本地模型。# 启动配置向导 dsh config根据提示你需要提供模型提供商如openai,deepseek等。API Key对应提供商的有效 API 密钥。模型名称如gpt-4,deepseek-chat等。配置完成后你可以与 dsh 进行简单对话测试基础功能是否正常。3.3 初始化你的第一个插件项目dsh 提供了脚手架命令来快速创建插件项目结构。# 创建一个名为 health-checker 的插件项目 dsh skill create health-checker执行命令后它会引导你输入一些基本信息如插件名、描述、作者等并自动生成一个标准化的项目目录。如果该命令不可用你也可以手动创建结构如下health-checker/ ├── skill.yaml # 插件清单文件核心 ├── __init__.py # Python包初始化文件 ├── skill.py # 插件主逻辑文件 ├── requirements.txt # Python依赖列表 └── README.md # 项目说明文档现在你的开发环境已经就绪。接下来我们将深入skill.yaml和skill.py开始构建逻辑。4. 实战开发“项目健康度检查”插件我们将开发一个实用的插件它能够分析指定 Git 仓库的“健康度”包括查看未提交的更改、检查分支是否落后于远程、分析最近提交记录等。这个插件将涉及文件系统操作、执行 Git 命令、解析命令行输出等常见任务。4.1 设计插件清单 (skill.yaml)skill.yaml是蓝图。我们首先定义插件提供的两个核心工具。# skill.yaml name: Project Health Checker id: com.example.health-checker version: 0.1.0 author: Your Name description: 检查Git项目的健康状态包括未提交的更改、分支同步状态和近期提交历史。 帮助开发者快速了解项目代码库状况。 runtime: type: python entrypoint: skill:HealthCheckSkill tools: - name: check_git_status description: 检查当前Git仓库的状态。列出所有已修改、未暂存、未跟踪的文件。 这是一个轻量级的快速检查。 parameters: - name: directory type: string description: 要检查的Git项目目录路径。默认为当前目录。 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. 该分支是否落后或超前于远程跟踪分支。 2. 最近N条提交的摘要。 这是一个更全面的分析工具。 parameters: - name: directory type: string description: Git项目目录路径。 required: false default: . - name: branch type: string description: 要分析的分支名称例如 ‘main‘, ‘develop‘。默认为当前分支。 required: false - name: commit_count type: integer description: 要查看的最近提交数量默认为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 }关键点解析id必须是全局唯一的通常使用反向域名格式。description务必详细、准确。AI 主要靠它来理解工具用途。parameters定义了工具的输入。required和default字段让工具更灵活。returns定义了工具的输出结构。清晰的返回模式有助于 AI 理解和格式化最终回复给用户的结果。runtime.entrypoint指向 Python 模块中 Skill 类的路径 (skill:HealthCheckSkill表示skill.py文件中的HealthCheckSkill类)。4.2 实现插件核心逻辑 (skill.py)接下来在skill.py中实现HealthCheckSkill类并完成两个工具函数。# skill.py import os import subprocess import json from typing import Dict, Any, List from harness.skill import BaseSkill, tool class HealthCheckSkill(BaseSkill): 项目健康度检查技能的核心实现类。 tool(name“check_git_status”) def check_git_status(self, directory: str “.”) - Dict[str, Any]: 执行 git status 命令并解析结果。 Args: directory: Git 仓库的路径。 Returns: 包含状态摘要和文件列表的字典。 # 1. 切换到目标目录并验证是否为Git仓库 original_cwd os.getcwd() try: os.chdir(directory) # 检查.git目录是否存在 if not os.path.isdir(“.git”): return { “summary”: f“目录 ‘{directory}‘ 不是一个Git仓库。”, “modified_files”: [], “untracked_files”: [] } except Exception as e: return {“error”: f“无法访问目录 ‘{directory}‘: {str(e)}”} finally: os.chdir(original_cwd) # 2. 执行 git status --porcelain 获取机器可读的输出 try: result subprocess.run( [“git”, “status”, “--porcelain”], cwddirectory, capture_outputTrue, textTrue, checkTrue ) except subprocess.CalledProcessError as e: return {“error”: f“Git命令执行失败: {e.stderr}”} except FileNotFoundError: return {“error”: “系统中未找到Git命令请确保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: 暂存区状态 Y: 工作区状态 status line[:2] filename line[3:] if status ‘??‘: untracked_files.append(filename) elif status ! ‘ ‘: # 非空状态包括 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} 个文件被修改。”) if total_untracked 0: summary_parts.append(f“有 {total_untracked} 个未跟踪的新文件。”) if not summary_parts: summary “工作目录是干净的没有未提交的更改。” 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: 项目目录。 branch: 分支名默认为当前分支。 commit_count: 要分析的最近提交数量。 Returns: 包含分支同步状态和提交历史的字典。 original_cwd os.getcwd() try: os.chdir(directory) if not os.path.isdir(“.git”): return {“error”: f“目录 ‘{directory}‘ 不是一个Git仓库。”} except Exception as e: return {“error”: f“目录访问错误: {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. 获取当前分支名如果未指定 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. 获取远程跟踪分支信息 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. 计算领先/落后于远程的提交数 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”, “log”, 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. 评估健康状态简单逻辑示例 if result_dict[“behind_count”] 10: result_dict[“health_status”] “需要关注严重落后于远程” 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”] “优秀有未推送的提交” else: result_dict[“health_status”] “优秀与远程同步” except subprocess.CalledProcessError as e: result_dict[“error”] f“Git命令执行失败: {e.stderr}” result_dict[“health_status”] “分析失败” except Exception as e: result_dict[“error”] f“分析过程中发生未知错误: {str(e)}” result_dict[“health_status”] “分析失败” return result_dict4.3 定义依赖 (requirements.txt)我们的插件使用了 Python 标准库没有额外第三方依赖。但这是一个好习惯明确声明依赖。# requirements.txt # 本项目暂无额外第三方依赖。 # 未来如需添加例如 requests可在此处注明 # requests2.28.05. 本地安装、调试与测试插件插件代码写完后必须在本地安装并测试确保它能被 dsh 正确识别和调用。5.1 在开发模式下安装插件进入插件项目根目录使用 dsh 命令进行本地安装。# 确保当前目录是 health-checker/ cd /path/to/health-checker # 在开发模式下安装插件 dsh skill install --dev .--dev参数表示以开发模式安装dsh 会链接到当前目录的源代码。这意味着你对skill.py或skill.yaml的任何修改在重新加载后都会立即生效无需重复安装。5.2 验证插件安装安装成功后可以通过以下命令查看已安装的插件列表确认我们的插件在其中。# 列出所有已安装的技能 dsh skill list你应该能看到com.example.health-checker(Project Health Checker) 出现在列表中。5.3 与插件交互测试现在启动 dsh 的交互式对话测试插件功能。# 启动 dsh 对话 dsh在 dsh 的对话界面中尝试输入以下指令观察 AI 是否会调用我们的插件并返回结构化的结果测试轻量检查“帮我检查一下当前这个项目的 Git 状态。”测试深度分析“分析一下 main 分支的健康状况看看最近 3 次提交。”测试路径参数“检查/home/user/my-project目录下的 Git 状态。”理想的交互流程是你输入自然语言指令。dsh 理解意图识别出需要调用health-checker插件的某个工具。dsh 在后台执行插件代码。dsh 将插件返回的 JSON 结果转化为一段清晰、友好的文本回复给你。5.4 调试与日志查看如果插件没有被调用或者调用后出错你需要进行调试。检查工具描述确保skill.yaml中tools.description足够清晰能让 AI 准确匹配。查看 dsh 日志dsh 运行时通常会输出详细日志其中会记录意图识别、工具选择和调用过程。根据你的安装方式日志可能输出到终端或特定日志文件。在插件代码中添加日志你可以在skill.py中使用print语句或 Python 的logging模块输出调试信息。在开发模式下这些信息通常会显示在 dsh 的后台输出中。# 在 skill.py 的函数中添加简单调试信息 def check_git_status(self, directory: str “.”): print(f“[DEBUG] check_git_status called with directory: {directory}”) # 调试输出 # ... 其余代码 ...6. 插件发布到 dsh 插件市场当插件在本地测试稳定后你可以考虑将其发布到 dsh 的插件市场如 dshmarket供其他开发者使用。发布前准备完善skill.yaml确保所有描述准确版本号符合语义化版本规范如0.1.0。编写清晰的README.md说明插件功能、安装方法、使用示例和配置要求。代码清理移除调试用的print语句确保代码整洁。选择发布平台目前 dsh 插件可能支持发布到官方市场或第三方索引。请查阅最新的 dsh 文档获取发布命令。一个常见的发布流程可能类似于# 1. 打包插件 (假设命令为 skill pack) dsh skill pack # 2. 发布到市场 (假设命令为 skill publish) dsh skill publish --registry https://market.dsh.ai请注意发布前务必仔细阅读目标市场的发布协议和规范确保你的插件不包含恶意代码且符合安全标准。7. 常见问题与排查思路在开发和使用 dsh 插件过程中你可能会遇到以下典型问题。问题现象可能原因排查方式解决方案dsh命令未找到1. Python Scripts 目录未在 PATH 中。2. pip 安装失败或未安装。1. 执行python -m harness --version测试。2. 检查 pip listgrep harness。插件安装失败1.skill.yaml格式错误。2. 依赖 (requirements.txt) 安装失败。3. 插件 ID 冲突。1. 使用 YAML 在线校验器检查skill.yaml。2. 查看安装错误信息。3. 检查dsh skill list。1. 修正 YAML 语法。2. 手动安装依赖或解决网络问题。3. 修改插件 ID。AI 不调用我的插件1. 工具描述 (description) 不清晰。2. 用户指令与工具描述匹配度低。3. 插件未正确加载。1. 在 dsh 对话中直接输入“使用[插件名]做[某事]”。2. 查看 dsh 的意图识别日志。1. 重写skill.yaml中的描述使其更贴近自然语言场景。2. 确保插件已通过dsh skill list列出。插件被调用但执行出错1. 插件代码存在语法或运行时错误。2. 缺少系统依赖如 Git。3. 权限不足如访问特定目录。1. 查看 dsh 的错误日志或插件函数返回的 error 字段。2. 在插件代码开头添加更完善的异常捕获和日志。1. 在本地独立运行插件代码片段进行调试。2. 在插件文档中明确声明系统依赖。3. 在代码中检查路径和权限。插件返回结果 AI 不理解返回的 JSON 数据结构与skill.yaml中returns定义不匹配。对比插件函数实际返回的字典与skill.yaml中定义的properties。确保返回的字典键名和类型与returns定义完全一致。8. 插件开发最佳实践与进阶建议掌握了基础开发流程后遵循以下最佳实践能让你的插件更健壮、更易用、更强大。8.1 设计原则单一职责一个工具只做一件事并把它做好。避免创建“瑞士军刀”式的巨型工具。描述即契约skill.yaml中的description是给 AI 看的“产品说明书”务必用完整、无歧义的自然句子描述工具的功能、输入和输出。防御性编程插件代码必须健壮。始终验证输入参数处理外部命令可能失败的情况如 Git 未安装、网络超时并进行详细的错误处理返回友好的错误信息。8.2 工程化建议版本管理使用语义化版本控制 (major.minor.patch)。每次发布新版本时更新skill.yaml中的version字段。依赖管理在requirements.txt中精确指定依赖版本如requests2.28.0以避免未来因依赖更新导致插件崩溃。单元测试为你的工具函数编写单元测试。虽然 dsh 插件框架可能没有标准的测试运行器但你可以单独测试你的 Python 函数确保其逻辑正确。配置化将硬编码的常量如 API 端点、默认值提取到配置中可以通过环境变量或配置文件注入提高插件的灵活性。8.3 进阶能力探索状态管理复杂的插件可能需要维护跨多次调用的状态。研究 dsh SDK 是否提供了会话Session或上下文Context存储机制。流式输出对于执行时间较长的任务研究是否支持流式Streaming返回结果以提升用户体验。与其他服务集成你的插件不仅可以调用本地命令更强大的用途是作为“适配器”连接 dsh 与你团队内部的 CI/CD 系统、项目管理工具Jira、监控系统Grafana等通过 API 调用实现深度自动化。开发 DeepSeek Harness 插件本质上是在定义人机协作的新接口。你不再需要记忆复杂的命令和参数而是用你最习惯的自然语言去驱动一个由你亲手定义和打磨的自动化工作流。从今天这个简单的“健康检查”插件起步你可以逐步将团队里所有重复、繁琐的研发操作都封装成 Skills最终构建一个完全贴合你团队需求的、智能化的开发助手环境。