> **名称辨析**：DeepSeek Harness 的命令行工具名就是 **dsh**（DeepSeek Harness 的缩写），二者是同一个东西—— > dsh 是 DeepSeek 于 2026 年 8 月开源的 AI Agent 运行时框架（Harness 层基础设施），npm 包为 `@deepseek-ai/dsh`。 ## 国内源安装 ``` ## 临时指定（推荐） npx --registry=https://registry.npmmirror.com @deepseek-ai/dsh web ## 永久配置（一劳永逸） npm config set registry https://registry.npmmirror.com ``` 内测声明 - DeepSeek Harness 目前的 0.1 版本仍处在面向 Harness 开发者进行测试的阶段，还有许多地方需要持续改进和打磨，希望听取广大开发者的反馈建议。预计 DeepSeek Harness 的核心插件以及基础 API 都会在接下来的一段时间内快速迭代、持续演化。 - 我们期待与全球开发者一起，在开源、开放、可复用、可组合的基础设施之上，共同探索智能上限。欢迎全球 Harness 开发者加入 DSH 插件生态。 ## 标准安装 - https://github.com/deepseek-ai/deepseek-harness/blob/master/README.zh.md#run ``` npx @deepseek-ai/dsh web Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned git clone https://github.com/deepseek-ai/deepseek-harness.git cd deepseek-harness pnpm install pnpm run build pnpm dsh web ``` - http://127.0.0.1:3080

## 理念一：Agent = Model + Harness（马具公式） - **模型**负责思考与决策；**Harness（马具/驾驭框架）**负责把模型接入文件系统、终端、网络等现实世界 - Harness 组织上下文、工具调用与任务循环——模型的智能要靠这一层才能兑现为行动 - dsh 开源的正是这一层：与具体模型解耦，模型可换，Harness 沉淀为可复用基础设施 ## 理念二：开源"底盘"，而非"成品车" - Claude Code / Codex CLI 这类产品把 Harness 层做成**整套成品**，只能整体使用 - dsh 开源的是**底盘与零件**：模型适配器、工具、沙箱环境，甚至 **Agent 主循环（Agent Loop）本身**都可自由拆装、替换 - 定位是"构建和改造 Agent 的基础设施"，而不是开箱即用的完整应用 ## 理念三：一切皆插件（Everything is a Plugin） - 框架中**没有特权内核**，所有能力都以插件形态存在 - 可替换：同一能力换实现不改核心代码；可组合：按需装配插件组合 - 可观测：插件边界即观测边界，配合事件日志形成完整运行轨迹

## 基于 Cordis 的插件树 - 底层使用 **Cordis 元框架**：它不管具体功能，只管插件如何加载/卸载、声明依赖、通过服务与事件通信 - **能力接缝设计**：每种能力拆成"接口插件 + 实现插件" - 例：Shell 执行能力 = 接口定义插件 + 本地实现插件 / 沙箱实现插件，改配置即可切换 - 连 Agent Loop 也是插件——想换一套推理-行动循环，替换插件即可 ## 可观测轨迹（Trajectory） - dsh 把模型看到的一切（系统提示、工具调用、中间状态）记录到**追加式事件日志** - 提供 **Trajectory** 界面：可检查、回放、分叉（Fork）任意一次 Agent 运行 - 对调试、评估、复现线上问题非常有价值

## 四种预设模式（Preset = 一组配好的插件组合） | 预设 | 内容 | 适用场景 | |------|------|---------| | Standard 标准 | 功能最全：文件读写、终端、搜索、子代理 | 日常编码开发 | | PTC / Code | 标准模式 + SDK，模型编写 TypeScript 程序编排多步工具调用 | 批处理、自动化流水线 | | Minimal 极简 | 仅持久化 bash + 文本编辑工具 | 最小化基准测试 | | Creator 创造 | 对话中途可安装/替换/销毁插件 | 开发与调试插件本身 | ## 现状：Developer Preview - 0.1 版本仍处面向 Harness 开发者的测试阶段，核心插件与基础 API 快速迭代 - 可能出现**破坏性变更**，暂不适合生产环境关键流程 - 插件生态开放共建：欢迎开发者基于 DSH 插件体系扩展能力

## 核心哲学：刻意做减法的"手艺人"路线 Pi（原 badlogic/pi-mono，现 earendil-works/pi）的信条是"**如果不需要，就不构建**"，把控制权完全交还给开发者。 - **工具极简**：默认只给模型 **4 个工具**（`read` / `bash` / `edit` / `write`），系统提示词极短。理念：有了 bash，绝大多数操作都能走命令行完成，无需堆砌专用工具 - **透明可控**：上下文显式、可检查、无隐藏注入；记忆靠可见的 `AGENTS.md` 等文件，而非黑盒向量库 - **无内置权限系统**：继承启动用户的权限；需要隔离时用容器（Docker / 微 VM）从外部兜底 - **刻意不做**：sub-agents、MCP、内置计划模式——需要时通过扩展机制自建 ## 四种用法与扩展机制 | 形态 | 说明 | |------|------| | TUI 交互 | 终端全屏交互界面（差分渲染） | | `--print` / `-p` | 无头一次性模式，处理完即退出，适合脚本管道 | | `--mode json` | 结构化事件流（print 模式的事件版），便于程序消费 | | `--mode rpc` / SDK | stdin/stdout JSONL 集成；或作为库嵌入 Node.js 应用 | 扩展机制：**TypeScript 扩展**（工具/命令/事件/自定义 UI）、**Skills**（按需加载的能力包）、Prompt 模板、主题、可分享的 pi 包。

## 安装（Node.js 环境） ``` npm install -g --ignore-scripts @earendil-works/pi-coding-agent pi --version ``` ## 自定义模型供应商：~/.pi/agent/models.json 内置 google/anthropic/openai 等供应商目录；**任意 OpenAI 兼容端点**（DeepSeek、Ollama、vLLM、代理网关）都可注册： ``` { "providers": { "deepseek": { "baseUrl": "https://api.deepseek.com/v1", "api": "openai-completions", "apiKey": "$deepseek_api_key", "models": [{ "id": "deepseek-v4-flash", "name": "DeepSeek V4 Flash" }] } } } ``` - `api: "openai-completions"` 声明走 OpenAI Chat Completions 协议 - `apiKey: "$VAR"` 用 `$` 引用环境变量，**密钥不落盘明文** - 注册后用 `--model deepseek/deepseek-v4-flash` 选用（`供应商/模型id` 格式）

## Python 侧调用（已实测跑通） 完整可执行版本见 notebook：`D:/wks/jupyter/agent/pi_demo_1.ipynb`（0 报错，输出已留档）。 ```python import os, json, shutil, subprocess from dotenv import load_dotenv load_dotenv("D:/wks/jupyter/env.txt") # 注入 deepseek_api_key 等 PI = shutil.which("pi") # Windows 下解析到 pi.CMD MODEL = f"deepseek/{os.getenv('deepseek_model')}" def run_pi(args, cwd=None, timeout=240): # 列表参数 + shell=True：cmd.exe 负责转义中文提示词 return subprocess.run([PI, *args], shell=True, cwd=cwd, env=dict(os.environ), capture_output=True, text=True, timeout=timeout, encoding="utf-8", errors="replace") # 用法一：print 模式一次性问答（无头嵌入） p = run_pi(["-p", "--model", MODEL, "用一句话回答：什么是 Agent Harness？"]) print(p.stdout) # 用法二：JSON 事件流，观察工具调用循环（write + bash） p = run_pi(["-p", "--mode", "json", "--model", MODEL, "创建 hello.py 打印斐波那契数列前10项，然后用 bash 运行它"], cwd="D:/wks/jupyter/agent/pi_workspace") for line in p.stdout.splitlines(): if line.strip().startswith("{"): ev = json.loads(line) if ev.get("type") == "tool_execution_start": print("[工具调用]", ev["toolName"]) ``` ## 实测事件流（pi 0.87.0 + deepseek-v4-flash） 事件类型链路：`session → agent_start → turn_start → message_start/update/end → tool_execution_start/update/end → turn_end → agent_end` ``` [工具调用] write: {"path": ".../pi_workspace/hello.py", "content": "def fibonacci(n): ..."} [工具结束] write ✅ [工具调用] bash: {"command": "cd .../pi_workspace && python hello.py"} [工具结束] bash ✅ 最终答复: [0, 1, 1, 2, 3, 5, 8, 13, 21, 34] ``` 一次提示 = 两次工具调用（write、bash），轨迹完整可解析——这正是 Harness 层"透明可控"的直接体现。

## 核心定位：面向复杂、长周期任务的"工业化"路线 DeepAgents 是 LangChain 团队的 agent harness（`pip install deepagents`），用系统化机制解决**上下文窗口限制**与**任务拆解**两大难题，底层跑在 **LangGraph 运行时**上（持久执行、流式、人机交互）。 ## 三层核心机制 | 机制 | 实现 | 解决的问题 | |------|------|-----------| | 任务规划 | `write_todos`（v0.7+ 经 `TodoListMiddleware` 开启） | 复杂指令拆成 pending/in_progress/completed 清单，避免随机探索 | | 虚拟文件系统 | `ls` / `read_file` / `write_file` / `edit_file` / `glob` / `grep` | 大型工具结果落盘，上下文只留路径引用，省 token | | 子代理委托 | 内置 `task` 工具 + `subagents` 档案 | 子任务在独立上下文执行，主上下文不被污染 | ## 长任务与企业级能力 - **长任务优化**：上下文压缩/摘要、提示缓存，保证 token 上限内持续运行 - **企业级扩展**：异步子代理（并行+中途干预）、`interrupt_on` 人机审批、可插拔存储后端（StateBackend/StoreBackend 等）

## create_deep_agent：model + tools + system_prompt 已实测跑通（deepagents 0.7.16 + deepseek-v4-flash），完整版本见 `D:/wks/jupyter/agent/deepagents_demo_1.ipynb`。 ```python import os from dotenv import load_dotenv, find_dotenv from langchain_openai import ChatOpenAI _ = load_dotenv(find_dotenv(filename="D:/wks/jupyter/env.txt")) llm = ChatOpenAI(model=os.getenv("deepseek_model"), openai_api_key=os.getenv("deepseek_api_key"), openai_api_base=os.getenv("deepseek_base_url"), temperature=0) from deepagents import create_deep_agent def multiply(a: int, b: int) -> int: """两个整数相乘""" return a * b agent = create_deep_agent(model=llm, tools=[multiply], system_prompt="你是简洁的数学助手。") res = agent.invoke({"messages": [{"role": "user", "content": "用工具算 12*13"}]}) ``` 实测消息流：`HumanMessage(提问) → AIMessage(tool_calls) → ToolMessage(156) → AIMessage(12 × 13 = 156)`； 返回的 state 除 `messages` 外自带 `files` 字段（虚拟文件系统开箱即在）。

## write_todos 规划 + 虚拟文件系统落盘 ```python from langchain.agents.middleware import TodoListMiddleware agent = create_deep_agent( model=llm, middleware=[TodoListMiddleware()], # 装上 write_todos system_prompt="你是写作助手。先规划，再把结果写入虚拟文件。", ) res = agent.invoke({"messages": [{"role": "user", "content": "规划并写一篇关于'AI Agent'的60字简介：1) 先用write_todos列计划 " "2) 把简介写入 intro.md 3) 读回来确认"}]}) print(res["todos"]) # 待办清单（含 status 流转） print(res["files"]) # 虚拟文件系统：{'/intro.md': {...}} ``` 实测产出： ``` [completed] 拟定AI Agent简介内容（约60字） [completed] 将简介写入 intro.md [completed] 读回 intro.md 核对字数与内容 虚拟文件系统: /intro.md —— "# AI Agent 简介\n\nAI Agent是能自主感知环境、规划任务并调用工具执行动作的智能体……" ``` 关键设计：中间产物写进文件而非堆在上下文——长任务省 token 的核心手段。

## subagents 档案 + task 工具委派 ```python def city_score(city: str) -> str: """查询城市宜居评分（示例假数据）""" return f"{city}: 8.5分（空气8/交通9/房价压力6）" researcher = { "name": "city-researcher", "description": "城市宜居研究员，负责打分与点评", "system_prompt": "你是城市研究员，先调用工具获取评分，再用两三句话点评。", "tools": [city_score], } agent = create_deep_agent( model=llm, subagents=[researcher], system_prompt="遇到城市研究类任务，必须委派给 city-researcher 子代理完成。", ) res = agent.invoke({"messages": [{"role": "user", "content": "研究一下杭州的宜居程度"}]}) ``` 实测：主代理发起 `task` 工具调用（参数为委派描述），子代理在**独立上下文**完成研究并返回结构化报告， 主代理汇总成多维度评分表答复用户。 - **上下文隔离**：每次委派创建全新子代理实例，只把最终报告带回主代理 - **可并行**：支持异步子代理，多任务并行委派、可中途干预

## 三个框架，三种哲学 | 维度 | Pi | DeepAgents | dsh（DeepSeek Harness） | |------|-----|-----------|------------------------| | 一句话定位 | 极简终端 Agent 底座 | 工业化长任务编排库 | 开源 Agent 运行时底盘 | | 核心哲学 | 刻意做减法，透明可控 | 内置系统化机制 | 一切皆插件，无特权内核 | | 默认工具 | read/bash/edit/write 四件 | 文件系统+规划+task 全家桶 | 由插件组合决定（四种预设） | | 技术栈 | Node.js / TypeScript | Python / LangGraph | TypeScript / Cordis 插件框架 | | 运行形态 | TUI、print、json 事件流、RPC、SDK | Python 库（LangGraph 图） | CLI + Web 界面 + 插件生态 | | 上下文策略 | 显式可见，AGENTS.md 记忆 | 压缩/摘要/缓存 + 虚拟文件 | 追加式事件日志 + Trajectory 回放 | | 扩展方式 | TypeScript 扩展、Skills、模板 | middleware、subagents、backend | 插件树（连 Agent Loop 都可换） | | 成熟度 | 0.x，迭代活跃 | 0.7.x，LangChain 官方维护 | 0.1 Developer Preview |

## 怎么选 - **要轻量、透明、可嵌入的 Agent 运行时**，或喜欢命令行工作流解决问题 → 选 **Pi** - 典型：作为 SDK 嵌入自有应用；脚本化的一次性编码任务 - **要处理多步骤复杂任务、长期运行且具备良好扩展性** → 选 **DeepAgents** - 典型：带规划的研究型 Agent、需要上下文隔离的多子任务系统 - **要构建/改造自己的 Agent 基础设施**，深度定制每一层 → 关注 **dsh** - 典型：自研 Agent 产品底盘、插件生态共建（注意其 Developer Preview 状态） ## 共同趋势 三者都在回答同一个问题——**模型之外的 Harness 层该怎么做**： 把工具调用、上下文管理、任务循环从应用代码中沉淀为可复用、可观测、可替换的基础设施层。