DeepSeek Harness（dsh）架构解析：本地优先 AI Agent 的 Profile、Plugin 与 Tool 体系

说明：本文基于现有 dsh 项目材料与源码结构整理，重点讨论架构与使用思路。项目归属、发行包名、具体版本与默认配置请以你实际使用的源码仓库为准。

摘要：本文从整体架构、Profile 机制、Plugin 系统、Tool / Skill 工具链、配置加载、Web / Headless / TUI 多模式运行、MCP 集成及开发流程等角度拆解 dsh，并通过架构图、数据流和示例说明如何组织一个本地优先、可扩展的 AI 编程 Agent 运行时。

关键词：AI Agent、dsh、本地优先、Profile、Plugin、Tool、Skill、MCP、LLM、编程助手

---

📋 目录

• 1. 项目概述
• 2. 核心架构图
• 3. 组件依赖关系
• 4. 启动流程详解
• 5. 数据流转图
• 6. 命令使用指南
• 7. Profile 机制解析
• 8. Plugin System
• 9. 工具箱
• 10. Agent Presets 配置
• 11. 开发工作流
• 12. 实战应用案例

---

1. 项目概述

1.1 什么是 DeepSeek Harness？

DeepSeek Harness（dsh）可以理解为一个本地优先的 AI Agent 运行时框架，面向编程辅助与自动化开发场景。它把 Agent、Profile、Plugin、Tool、Skill 等能力拆分为可组合模块，让开发者能够按场景装配文件系统、Shell、网络检索、工作流、子代理等能力，并接入不同的 LLM 后端。

这里的“本地优先”强调运行时、工具链、配置与数据路径优先由本机掌控，并不等同于“完全离线”。如果所选 LLM 后端是云端模型，模型请求仍会经过对应的远程 API；如果接入本地模型，则可以进一步减少数据外发。

1.2 核心理念

1.3 关键特性

特性	描述	价值
本地优先	运行时、工具链与配置优先在本机执行；模型后端可本地或远程	数据路径更可控、便于私有化部署
模块化架构	Profile + Plugin + Tool 三层结构	高度可扩展、可定制
多模式运行	Web UI / Headless / TUI	适应不同使用场景
MCP 支持	可通过 Model Context Protocol 对接外部工具或上下文能力	提升工具生态兼容性
技能规范	Skill 定义标准接口	统一的能力暴露方式

---

2. 核心架构图

2.1 整体系统架构

2.2 三层架构模型

---

3. 组件依赖关系

3.1 核心包依赖树

3.2 插件系统架构

3.3 关键第三方依赖类型

与其给出容易随版本变化的“依赖数量统计”，更适合按职责理解依赖结构：

依赖类别	主要职责
UI / Web	Web 界面、状态管理与交互组件
AI / LLM SDK	模型请求、流式响应与工具调用协议适配
Network / HTTP	HTTP、WebSocket、SSE 等网络通信
Text Processing	文本解析、搜索、格式化与内容处理
Build / Tooling	TypeScript、构建、测试与开发工具链
Type Definitions	类型声明与跨包接口约束

具体依赖名称与版本请以项目 package.json、lockfile 及实际构建结果为准。

---

4. 启动流程详解

4.1 从命令行到运行的完整流程

4.2 Web 模式启动时序

4.3 Headless 模式执行流程

---

5. 数据流转图

5.1 单次对话的数据流

5.2 工具调用闭环

5.3 配置文件加载链

5.4 Token 消耗监控流

---

6. 命令使用指南

6.1 命令层次结构

6.2 常用命令示例

# 1. 基础启动命令
dsh --profile web                 # 启动 Web UI（同：dsh web）
dsh --profile headless "任务描述"  # 单次任务执行
dsh --profile tui                # 终端模式（如果已安装）

# 2. 带配置的启动
dsh --profile web --port 8080    # 自定义端口
dsh --profile headless --patch ./extra.yml "任务"  # 自定义配置

# 3. 配置诊断
dsh --profile web --dump-config         # 查看当前完整配置
dsh --profile web --dump-default-config # 查看默认配置（不含用户覆盖）

# 4. 插件管理
dsh plugin --profile web add @my/plugin     # 添加插件
dsh plugin --profile web remove @old/plugin # 删除插件
dsh plugin --profile web why some-package   # 查看依赖关系

# 5. 查看帮助
dsh --help                    # Launcher 帮助
dsh web --help                # Web 模式帮助
dsh --profile headless --help # Headless 模式帮助

6.3 配置覆盖顺序

配置更适合用“后加载覆盖前加载”来理解，而不是用没有实际含义的百分比分数表示：

通常越靠后的配置层优先级越高；如果你的实现采用不同合并规则，应以 Cordis 的实际 merge / patch 行为为准。

---

7. Profile 机制解析

7.1 Profile 的概念

Profile 是预定义的功能组合包，通过叠加多个插件和工具来实现特定用途。每个 Profile 都是一组可复用的能力集合。

7.2 Profile 文件结构

7.3 Profile 加载顺序

7.4 内置 Profile 对比

Profile	用途	适用场景	包含的主要 Bundles
web	Web UI 界面	图形化交互、IDE 集成	base, web-app, client-ui, tools
headless	无头任务执行	CI/CD、自动化脚本	base, headless, goal, compact
tui	终端界面	命令行交互	base, terminal, session
minimal	最小化配置	资源受限环境	base only
custom	用户自定义	特殊需求场景	用户指定的 bundles

---

8. Plugin System

8.1 插件体系结构

8.2 插件生命周期

8.3 插件注册流程

8.4 常用 Cordis Plugin

Plugin	功能	版本	使用场景
cordis-plugin-loader	插件加载器	^1.0.2	核心加载逻辑
cordis-plugin-hmr	热更新	^1.0.16	开发时快速迭代
cordis-plugin-include	配置包含	^1.0.6	复用配置片段
cordis-plugin-timer	定时器	^1.1.3	周期性任务调度

---

9. 工具箱

9.1 工具分类矩阵

类别	主要功能	核心包	典型用法
文件系统	文件读写、搜索	dsh-tool-fs、dsh-tool-fs-search	代码分析、文本编辑
Shell 执行	命令运行	dsh-tool-bash、dsh-tool-pwsh	Git 操作、构建脚本
网络能力	HTTP 请求、Web 检索	dsh-tool-web	API 调用、信息获取
任务管理	作业队列、Todo 列表	dsh-tool-jobs、dsh-tool-todo	异步任务跟踪
工作流	流程编排	dsh-tool-workflow	复杂任务自动化
子代理	Subagent 控制	dsh-tool-subagent	多层级 Agent 协作
技能	Skill 管理	dsh-tool-skill	能力扩展注册
目标	Goal 驱动	dsh-tool-goal、dsh-command-goal	长期任务规划
算法推理	Ralph 推理引擎	dsh-tool-ralph	数学计算、逻辑推理

9.2 工具注册与调用

9.3 核心工具详细说明

以下函数签名用于说明工具职责与调用方式，属于概念示意；真实 API、参数类型与返回值请以实际源码定义为准。

文件系统工具 (dsh-tool-fs)

// 典型用法
readFile(path: string): Promise<string>
writeFile(path: string, content: string): Promise<void>
searchFiles(pattern: string, options?: SearchOptions): Promise<string[]>
createDirectory(path: string): Promise<void>

Shell 工具 (dsh-tool-bash, dsh-tool-pwsh)

// Unix Bash
execBash(command: string, options?: ExecOptions): Promise<ExecResult>

// Windows PowerShell  
execPowerShell(command: string, options?: ExecOptions): Promise<ExecResult>

interface ExecResult {
    stdout: string
    stderr: string
    exitCode: number
}

网络工具 (dsh-tool-web)

fetchURL(url: string, options?: FetchOptions): Promise<ResponseData>
searchWeb(query: string): Promise<SearchResult[]>
parseHTML(html: string): Promise<ParsedContent>

工作流工具 (dsh-tool-workflow)

startWorkflow(steps: WorkflowStep[]): Promise<WorkflowInstance>
awaitCompletion(instanceId: string, timeout?: number): Promise<WorkflowResult>
cancelWorkflow(instanceId: string): Promise<void>

---

10. Agent Presets 配置

10.1 Preset 配置系统

10.2 Preset 配置文件内容

standard/preset.yml:

name: 标准模式
description: 功能完整的编码 Agent，支持文件编辑、Shell、文件与网页检索、Skills、计划、目标、子代理和工作流。
order: 1  # 在列表中优先显示

minimal/preset.yml:

name: 最小化配置
description: 仅包含基础功能的精简配置
order: 3

10.3 Cordis 配置示例

下例用于展示“通过配置组合能力”的思路，字段名与插件名请以实际项目 Schema 为准。

standard/agent.cordis.yml:

# 定义 Agent 的核心能力和行为规则
plugins:
  - name: dsh-skill
    enabled: true
    config:
      maxConcurrent: 5
      
  - name: dsh-tool-fs
    enabled: true
    permissions:
      readOnly: false
      allowedPaths:
        - "."
        
  - name: dsh-tool-bash
    enabled: true
    sandboxed: true

rules:
  - when: task.type == 'code_edit'
    then: allow_tool(dsh-tool-fs)
    
  - when: task.type == 'shell_exec'
    then: require_confirmation(dsh-tool-bash)

10.4 Preset 选择指南

使用场景	推荐 Preset	理由
日常编码辅助	standard	功能完整，开箱即用
代码审查/重构	code	专注于代码相关能力
快速原型开发	minimal	轻量级，启动快
自定义开发	cordis	包含 Cordis 插件开发能力

---

11. 开发工作流

11.1 从源码构建

11.2 开发循环流程

11.3 调试技巧

方式一：使用 dump-config 诊断

# 查看所有配置的组成
dsh --profile web --dump-default-config

# 查看用户覆盖后的完整配置
dsh --profile web --dump-config

方式二：启用详细日志

# 设置环境变量
export DEBUG=dsh:*
export LOG_LEVEL=debug

# 运行
dsh --profile web

方式三：单步调试

# 使用 Node.js inspect 模式
node --inspect lib/bin.js --profile web

---

12. 实战应用案例

12.1 场景一：在 IDEA 中集成 DSH

以下时序图为集成思路示意，接口路径与快捷键应按实际插件实现调整。

12.2 场景二：CI/CD 自动化流水线

runner.sh 示例：

#!/bin/bash
set -e

echo "Starting automated analysis..."

# Run DSH headless mode
RESULT=$(dsh --profile headless <<EOF
Analyze the following changes:
$(git diff --stat HEAD^ HEAD)

Generate a summary of potential issues:
1. Breaking API changes
2. Security concerns
3. Performance regressions
EOF
)

echo "$RESULT" | tee analysis-report.md

# Optional: Submit to PR
gh pr comment $PR_NUMBER --body-file analysis-report.md

12.3 场景三：自定义 Tool 开发

下例用于说明 Tool 的 Schema + Handler 组织方式，不应视为稳定公开 API。

Tool 定义示例：

// my-awesome-tool.ts
// import { defineTool } from '<your-dsh-skill-package>'; // 以实际包名为准

export const myAwesomeTool = defineTool({
  name: 'analyze-code-quality',
  description: 'Analyze code quality and suggest improvements',
  inputSchema: {
    type: 'object',
    properties: {
      filePath: { type: 'string', description: 'Path to source file' },
      rules: { 
        type: 'array', 
        items: { type: 'string' },
        description: 'Analysis rules to apply'
      }
    },
    required: ['filePath']
  },
  handler: async ({ filePath, rules = [] }) => {
    // Implementation here
    return {
      issues: [],
      suggestions: [],
      score: 85
    };
  }
});

---

13. 总结：dsh 的价值在“可组合的 Agent 运行时”

从架构上看，dsh 的重点并不是把所有能力塞进一个单体 Agent，而是通过 Profile 决定运行方式和能力组合，通过 Plugin 承载可扩展模块，通过 Tool / Skill 暴露可调用能力，再由配置引擎把这些组件组合成具体的编程助手。

这套设计的实际价值主要体现在三点：

1. 本地优先、边界清晰：工具执行、权限控制、配置与项目文件都可以放在本地运行时中管理；是否调用远程模型则由模型后端决定。
2. 按需装配：Web、Headless、TUI 等模式可以复用同一套底层能力，不必为每个入口复制一份 Agent 实现。
3. 适合二次开发：文件系统、Shell、检索、工作流、子代理、MCP 等能力都可以围绕统一的注册与调用机制扩展。

如果你的目标是搭建一个可控、可扩展的 AI 编程助手，那么比“换一个更强的模型”更重要的，往往是把 运行时、工具权限、上下文、工作流与模型接口组织成一套稳定的 Harness。

---

📚 附录

A. 参考资料

资源	建议核对位置	说明
项目仓库	你实际使用的源码仓库	核对项目归属、分支与发布版本
包信息	package.json / lockfile	核对真实包名、版本与依赖
CLI 文档	项目 README.md / --help	核对命令、参数与默认值
配置 Schema	项目源码 / 配置文档	核对 Cordis、Profile、Plugin 与 Tool 字段

发布前建议再做一次“源码对照”：尤其核对包名、默认端口、内置 Profile、插件版本和对外 API，避免把内部实现或示例代码误写成稳定接口。

B. 术语表

术语	英文	解释
Profile	配置集	预定义的功能组合包
Plugin	插件	可扩展的功能模块
Tool	工具	具体的功能实现单元
Skill	技能	Agent 能力的规范定义
Patch	补丁	配置覆盖层
Cordis	Cordis	配置管理引擎
Bundle	组合包	一组相关的插件集合

C. 故障排除速查

问题	可能原因	解决方法
dsh: command not found	npm 未加入 PATH	检查 npm config get prefix
Web 无法启动	端口被占用	换端口：dsh --profile web --port 8081
工具调用失败	Schema 不匹配	检查 Tool 定义和参数
配置冲突	Patch 重叠	使用 --dump-config 检查
插件加载慢	依赖太多	使用 minimal Profile

---

最后整理：2026-08-16
发布建议：项目元信息与外部链接请以实际源码仓库为准。