deepseek-harness-acp

Standalone Agent Client Protocol (ACP) Server powered by DeepSeek Harness with real-time token streaming, thought trace transparency, tool execution lifecycle updates, and cross-process session recovery.

中文文档

✨ Features

• ⚡ Real-time Token Streaming: Word-by-word streaming (agent_message_chunk) for ultra-low latency.

• 🧠 Thought Trace Streaming: Live reasoning and thinking flow (agent_thought_chunk).

• 📊 Comprehensive Token & Performance Metrics: Standard usage (input/output/cached/thought tokens) and detailed _meta.metrics (TTFT, tok/s, cache hit rate, turns, steps) in session/prompt response.

• 🛠️ Tool Lifecycle Updates: Observable tool execution states (tool_call & tool_call_update).

• 🧩 MCP (Model Context Protocol) Support: Connect to external Stdio / Streamable HTTP MCP servers, auto-discovering project .mcp.json / .cursor/mcp.json / .vscode/mcp.json and ACP session parameters to seamlessly expand the agent's tool ecosystem. Legacy SSE transport is unsupported by Harness 0.1.6.

• 🔄 Session Recovery & Listing: Seamless multi-turn session resume (session/load, session/resume, session/list).

• ⚙️ Dynamic Configuration: Real-time model switching (deepseek-v4-pro / deepseek-v4-flash).

• 📦 Zero-Config Startup: Built-in default configuration — start immediately with only DEEPSEEK_API_KEY.

🚀 Quick Start

1. Global Installation (CLI)

Requires Node.js 24 or later. Uses DeepSeek Harness 0.1.6-alpha.2.

# Install globally via npm (using full name or short alias)
npm install -g deepseek-harness-acp
# or
npm install -g dsh-acp

# Or run directly via npx without installation
npx dsh-acp
# or
npx deepseek-harness-acp

2. Environment Variables

Create a .env file or export environment variables:

export DEEPSEEK_API_KEY="sk-your-api-key"
# Optional overrides:
export DEEPSEEK_BASE_URL="https://api.deepseek.com"
export DEEPSEEK_PROTOCOL="messages" # messages (default) | chat-completions
export DEEPSEEK_MODEL="deepseek-v4-pro"
export DSH_PERMISSION_MODE="workspace-write" # workspace-write | danger-full-access

Alternatively, run the interactive setup once to store your key in ~/.dsh/.env ($DSH_HOME is respected); it is loaded automatically on every start:

dsh-acp --setup

🔌 Integration with Third-Party Clients

Zed Editor

Add the following to your Zed settings (~/.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

In FreeBuddy settings or custom agent configuration, specify:

• Command: deepseek-harness-acp (or dsh-acp)
• Environment: DEEPSEEK_API_KEY=sk-...

Node.js / TypeScript SDK

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: 'Hello DeepSeek!' }],
})

🧩 MCP (Model Context Protocol) Configuration

deepseek-harness-acp natively operates as an MCP Client, connecting to external MCP servers and exposing their tools directly to the DeepSeek agent:

1. Workspace Configuration Discovery

Create a .mcp.json (or .cursor/mcp.json / .vscode/mcp.json) in your project root:

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

2. Dynamic ACP Session Parameters

When an editor client requests session/new or session/resume, specify the mcpServers list in the parameters. The server will dynamically connect and register the tools into DeepSeek's decision context.

📜 Supported ACP Methods

📄 License

MIT © maojindao55