ACP 独立服务端maojindao55/deepseek-harness-acp

DeepSeek Harness ACP 协议独立服务

npm version
npm downloads
license

基于 DeepSeek Harness 构建的轻量级独立 Agent Client Protocol (ACP) 服务端。支持实时 Token 打字机流、深度思考链流式输出、工具执行生命周期卡片、跨进程历史会话恢复与动态模型切换。

English

✨ 核心特性

- ⚡ 实时打字机 Token 流：逐字返回（agent_message_chunk），极致响应体验。
- 🧠 思考链 / 深度思考流：实时查看模型推理思考过程（agent_thought_chunk）。
- 📊 完整用量与性能指标：session/prompt 响应返回标准 usage（输入/输出/Cache命中/思考Token）与 _meta.metrics（轮步数、TTFT首字延迟、tok/s生成速度、缓存命中率）。
- 🛠️ 工具执行生命周期：完整的工具调用中与完成状态更新（tool_call & tool_call_update）。
- 🧩 MCP (Model Context Protocol) 扩展：支持 Stdio / SSE 外部 MCP 服务，自动发现项目 .mcp.json / .cursor/mcp.json / .vscode/mcp.json 与 ACP 会话参数，无缝扩充 Agent 工具生态。
- 🔄 跨进程会话恢复与列表：支持多轮对话接续与历史会话读取（session/load、session/resume、session/list）。

- ⚙️ 动态配置项：支持客户端动态切换模型（deepseek-v4-pro / deepseek-v4-flash）。
- 📦 零配置开箱即用：内置默认沙箱与智能体配置，只需配置 DEEPSEEK_API_KEY 即可一行命令启动。

🚀 快速开始

1. 全局安装（CLI）

全局安装（支持全称或短别名）
npm install -g deepseek-harness-acp
或
npm install -g dsh-acp

或直接免安装秒级运行
npx dsh-acp
或
npx deepseek-harness-acp

2. 配置环境变量

创建 .env 文件或直接导出环境变量：

export DEEPSEEK_API_KEY="sk-your-api-key"
可选环境变量：
export DEEPSEEK_BASE_URL="https://api.deepseek.com"
export DSH_PERMISSION_MODE="workspace-write" # workspace-write | danger-full-access

🔌 第三方客户端接入指南

Zed 编辑器

在 Zed 配置文件（~/.config/zed/settings.json）中添加：

{
"assistant": {
"version": "2",
"custom_agents": [
{
"name": "DeepSeek Harness",
"command": "deepseek-harness-acp",
"env": {
"DEEPSEEK_API_KEY": "sk-your-deepseek-api-key"
}
}
]
}
}

FreeBuddy

在 FreeBuddy 设置中指定：
- 执行命令：deepseek-harness-acp（或 dsh-acp）
- 环境变量：DEEPSEEK_API_KEY=sk-...

Node.js / TypeScript 代码集成

import { spawn } from 'node:child_process'
import { ClientSideConnection, ndJsonStream } from '@agentclientprotocol/sdk'

const proc = spawn('deepseek-harness-acp', [], {
env: { ...process.env, DEEPSEEK_API_KEY: 'sk-your-api-key' },
stdio: ['pipe', 'pipe', 'inherit'],
})

const stream = ndJsonStream(proc.stdin, proc.stdout)
const client = new ClientSideConnection(
(agent) => ({
sessionUpdate: async ({ update }) => {
if (update.sessionUpdate === 'agent_message_chunk') {
process.stdout.write(update.content.text) // 实时打字机输出
} else if (update.sessionUpdate === 'agent_thought_chunk') {
process.stderr.write(update.content.text) // 思考流
}
},
requestPermission: async () => ({ outcome: { outcome: 'selected', optionId: 'allow-once' } }),
}),
stream,
)

await client.initialize({ protocolVersion: 1, clientCapabilities: {} })
const { sessionId } = await client.newSession({ cwd: process.cwd(), mcpServers: [] })

await client.prompt({
sessionId,
prompt: [{ type: 'text', text: '你好，DeepSeek！' }],
})

🧩 MCP (Model Context Protocol) 配置指南

deepseek-harness-acp 原生支持作为 MCP Client 连接外部 MCP 服务器并将其提供的工具注册给 DeepSeek 智能体：

1. 工作区配置文件自动加载

在项目工作区根目录下创建 .mcp.json（或 .cursor/mcp.json / .vscode/mcp.json）：

{
"mcpServers": {
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_..."
}
},
"fetch": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-fetch"]
},
"remote-sse": {
"url": "http://localhost:8080/sse"
}
}
}

2. ACP 会话参数动态传入

当编辑器发起 session/new 或 session/resume 请求时，在参数中携带 mcpServers 列表，服务会自动连接并将工具注入 DeepSeek 的决策上下文中。

📜 协议方法清单

| 方法 / 通知 | 说明 |
|---|---|
| initialize | 协议协商（公布 loadSession: true、sessionCapabilities.close/list/resume） |
| session/new | 创建新会话并返回初始可用配置项 |
| session/load | 跨进程加载历史会话并重构上下文 |
| session/resume | 恢复已有活跃或持久化会话 |
| session/list | 列出已知会话并支持按工作区 cwd 过滤 |
| session/set_config_option | 动态修改会话配置项（如切换模型） |
| session/prompt | 发送用户提问并等待 Agent 执行完毕 |
| session/cancel | 中途取消/打断正在处理的提问 |
| session/close | 主动释放会话资源 |
| session/update (流式推送) | 实时接收文本分片、思考链分片与工具执行状态 |

📄 开源许可

MIT © maojindao55