DeepSeek Harness Python SDK 通俗指南

DeepSeek Harness Python SDK 让你用 Python 代码指挥 AI 智能体自动完成软件开发任务——修 bug、跑测试、改代码，全程程序化调用。

一句话理解它是什么

DeepSeek Harness Python SDK 是一个 Python 库，让你在代码里调用 DeepSeek AI 智能体（agent）来自动完成软件开发任务——比如修 bug、跑测试、改代码。

打个比方：你在 DeepSeek 的 Web 界面里跟 AI 对话，让它帮你分析代码、跑命令、改文件，这个过程是手动的一次次发消息。而 Python SDK 把这件事变成了程序化调用——你写一段 Python 脚本，AI 就自动在隔离的工作区里检查代码、执行 Bash 命令、编辑文件，最后把结果返回给你。

它内置了两个核心工具给 AI 使用：

▸ bash——AI 可以在终端里执行 Shell 命令（跑测试、装依赖、看日志等）

▸ str_replace_editor——AI 可以精确编辑文件内容（查找、替换、插入）

简单说：它是一个"AI 程序员"的编程接口，你用 Python 代码指挥它干活。

它解决了什么问题

如果你用过 DeepSeek 的 Web 界面做编程任务，可能会遇到这些局限：

▸ 无法批量自动化——你想对 10 个仓库跑同一套"检查并修复测试"的流程，Web 界面只能一个个手动操作

▸ 无法嵌入自己的工作流——你想在 CI/CD 流水线里自动让 AI 检查代码，Web 界面做不到

▸ 会话状态不好管理——你想要"上一次对话的 shell 环境和工作目录保留到下一次"，手动操作很麻烦

▸ 无法程序化处理结果——AI 的回复你想存到数据库、发到飞书、触发后续流程，Web 界面给不了结构化输出

Python SDK 把这些能力开放出来：你可以用脚本批量调度 AI 任务、管理会话状态、拿到结构化的返回结果，然后把 AI 编程能力嵌入任何自动化流程里。

什么场景下使用

场景一：CI/CD 中的自动化代码修复
你的 CI 流水线跑测试失败时，自动触发 SDK 让 AI 去分析失败原因、尝试修复代码、再跑一遍测试验证。全程无人值守。

场景二：批量代码仓库巡检
你有几十个微服务仓库，想定期让 AI 逐一检查是否有已知模式的 bug、依赖是否过期、测试是否覆盖。用 SDK 写个脚本循环跑，每个仓库独立 session，互不干扰。

场景三：持续对话式代码开发
你在一个项目里持续开发，需要 AI 记住上次的上下文（工作目录在哪、环境变量设了什么、之前改了哪些文件）。复用同一个 session_id，AI 就能延续上次的工作。

场景四：自定义工具链集成
你想让 AI 除了 bash 和文件编辑之外，还能调用你自己的 API（比如查 Jira、发飞书消息）。通过 Cordis 配置文件扩展工具集，在 SDK 里加载自定义组合。

前置要求

安全提醒

内置示例使用 danger-full-access 策略，AI 的 Bash 和编辑器可以访问运行时进程有权访问的任何路径。务必在可丢弃的 checkout 或容器内运行，不要在包含敏感文件的环境里直接跑。

安装 SDK

三步完成：克隆仓库 → 创建虚拟环境 → 安装 SDK。

# 1. 克隆仓库（仓库里有可运行的示例代码）
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness

# 2. 创建并激活虚拟环境
python -m venv .venv
. .venv/bin/activate

# 3. 安装 SDK（自带运行时，不需要系统装 Node.js）
python -m pip install deepseek-harness-sdk

安装完成后，配置 API 凭据环境变量：

# 必填：DeepSeek API Key
export DEEPSEEK_API_KEY=sk-your-key-here

# 可选：如果你用的是 OpenAI 兼容代理而非 DeepSeek 官方端点
# export DEEPSEEK_BASE_URL=http://127.0.0.1:8000/v1

# 可选：指定模型（默认 deepseek-v4-flash）
# export DSH_MODEL=deepseek-v4-flash

# 可选：自定义系统提示词
# export DSH_SYSTEM_PROMPT='You are a helpful software engineer assistant.'

核心 API 速览

整个 SDK 的核心就是一个类：DeepSeekHarness。它是一个上下文管理器，用 with 语句打开，用 run() 方法发任务。

from pathlib import Path
from deepseek_harness import DeepSeekHarness

config = Path("examples/jsonrpc-agent/minimal.cordis.yml").resolve()
workspace = Path("/absolute/path/to/workspace").resolve()
sessions = Path("/absolute/path/to/sessions").resolve()

with DeepSeekHarness(
    provider="deepseek-official",   # API 提供方
    model="deepseek-v4-flash",       # 使用的模型
    max_tokens=49_152,              # 最大 token 数
    cwd=str(workspace),             # AI 可访问的工作区
    session_root=str(sessions),     # 会话日志保存目录
    cordis=str(config),             # Cordis 组合配置文件
) as harness:
    result = harness.run(
        "Inspect the repository and fix the failing tests.",
        session_id="example-001",
    )
    print(result.final_response)

关键概念：

▸ workspace（工作区）：cwd 参数，AI 能访问和修改的目录。应该是隔离的可丢弃环境。

▸ session_id（会话 ID）：标识一段对话。同一个 session_id 复用时，AI 保留之前的 shell 进程、工作目录、环境变量。独立任务用新 ID。

▸ cordis（组合配置）：YAML 文件，定义 AI 用哪些工具、超时多少、系统提示词等。

▸ result.final_response：AI 的最终文本回复。会话目录还会收到 JSONL 日志，记录完整的模型请求和工具调用过程。

示例一：自动检查仓库并修复失败的测试

场景：你有一个项目，测试跑挂了。你想让 AI 自动去检查仓库、定位失败原因、尝试修复。

第 1 步：准备隔离工作区

# 把项目代码放到一个隔离目录
mkdir -p /tmp/ai-workspace/my-project
cp -r /path/to/your/project/* /tmp/ai-workspace/my-project/

# 创建会话日志目录
mkdir -p /tmp/ai-sessions

第 2 步：设置环境变量

export DEEPSEEK_API_KEY=sk-your-key-here

第 3 步：运行任务

python examples/jsonrpc-agent/minimal.py \
  --workspace /tmp/ai-workspace/my-project \
  --session-root /tmp/ai-sessions \
  --session-id fix-tests-001 \
  "Inspect the repository and fix the failing tests."

第 4 步：查看结果

▸ 终端会打印 AI 的最终回复（告诉你它做了什么、改了哪些文件）

▸ /tmp/ai-sessions/ 下会生成 JSONL 日志，记录完整的工具调用过程

▸ 去工作区检查 AI 改了什么，跑一遍测试验证

第 5 步：如果没修好，继续追问

# 复用同一个 session_id，AI 记得上次的上下文
python examples/jsonrpc-agent/minimal.py \
  --workspace /tmp/ai-workspace/my-project \
  --session-root /tmp/ai-sessions \
  --session-id fix-tests-001 \
  "The tests are still failing. Check the error log again and try a different approach."

用 Python 代码代替命令行

上面的命令行等价于这段 Python 脚本，你可以把它集成到自己的流程里：

from pathlib import Path
from deepseek_harness import DeepSeekHarness

config = Path("examples/jsonrpc-agent/minimal.cordis.yml").resolve()
workspace = Path("/tmp/ai-workspace/my-project").resolve()
sessions = Path("/tmp/ai-sessions").resolve()

with DeepSeekHarness(
    provider="deepseek-official",
    model="deepseek-v4-flash",
    max_tokens=49_152,
    cwd=str(workspace),
    session_root=str(sessions),
    cordis=str(config),
) as harness:
    # 第一轮：让 AI 检查并修复
    result = harness.run(
        "Inspect the repository and fix the failing tests.",
        session_id="fix-tests-001",
    )
    print("=== 第一轮回复 ===")
    print(result.final_response)

    # 第二轮：复用 session，让 AI 继续处理
    result2 = harness.run(
        "The tests are still failing. Check the error log and try again.",
        session_id="fix-tests-001",  # 同一个 ID，上下文延续
    )
    print("=== 第二轮回复 ===")
    print(result2.final_response)

示例二：批量巡检多个仓库

场景：你有 3 个微服务仓库，想逐个让 AI 检查代码质量、是否有明显 bug、依赖是否过期。每个仓库独立 session，互不干扰。

from pathlib import Path
from deepseek_harness import DeepSeekHarness

config = Path("examples/jsonrpc-agent/minimal.cordis.yml").resolve()
sessions = Path("/tmp/ai-sessions").resolve()

# 要巡检的仓库列表
repos = [
    {"name": "user-service",     "path": "/tmp/ai-workspace/user-service"},
    {"name": "order-service",    "path": "/tmp/ai-workspace/order-service"},
    {"name": "payment-service",  "path": "/tmp/ai-workspace/payment-service"},
]

results = []

for repo in repos:
    workspace = Path(repo["path"]).resolve()
    session_id = f"audit-{repo['name']}-001"

    with DeepSeekHarness(
        provider="deepseek-official",
        model="deepseek-v4-flash",
        max_tokens=49_152,
        cwd=str(workspace),
        session_root=str(sessions),
        cordis=str(config),
    ) as harness:
        result = harness.run(
            f"Review the codebase of {repo['name']}. "
            "Check for: 1) obvious bugs, 2) outdated dependencies, "
            "3) missing tests. Summarize your findings.",
            session_id=session_id,  # 每个仓库用独立 session
        )
        results.append({
            "repo": repo["name"],
            "response": result.final_response,
        })

# 输出汇总报告
for r in results:
    print(f"\n{'='*60}")
    print(f"仓库: {r['repo']}")
    print(f"{'='*60}")
    print(r["response"])

这段脚本会依次对每个仓库执行 AI 巡检，每个仓库用独立的 session_id（audit-user-service-001、audit-order-service-001 等），互不干扰。AI 在每个仓库里的 shell 环境和工作目录都是独立的。

你可以把 results 存到数据库、生成报告、发到飞书——完全程序化处理。

重要注意事项

1. 安全隔离是第一原则

内置示例使用 danger-full-access 策略，AI 的 Bash 和编辑器能访问运行时进程可见的任何路径。务必在可丢弃的 checkout 或 Docker 容器内运行，不要在包含 SSH 密钥、数据库密码等敏感文件的环境里直接跑。

2. session_id 的复用规则

3. 不支持 Windows

内置示例的运行时需要 POSIX 终端环境（持久 PTY 后端），因此不支持在 Windows 上运行 agent。Windows 用户可以通过 WSL（Linux 子系统）使用。

4. 内置示例的默认配置

5. 性能提示

DeepSeekHarness 会延迟启动内置运行时，并在上下文管理器存活期间持续复用。如果你要执行多个任务，建议在同一个 with 块内复用同一个 harness，避免反复启动运行时的开销。只有需要切换 workspace 时才创建新的 harness 实例。

DeepSeek Harness Python SDK 通俗指南
参考文档：官方 Python SDK 指南