mengzhx/deepseek-harness
1
0
Fork 0
mirror of https://github.com/deepseek-ai/deepseek-harness.git synced 2026-08-29 04:26:38 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs(python): make the dsh profile runtime current

Browse Source 
Document dsh as the only application launcher across architecture, CLI, SDK, app-boot, Python package, contributor, tutorial, and example references. Explain explicit home selection, profile and patch precedence, persistent external plugin installation, the Node-free runtime path, and the absence of complete-config or ~/.dsh fallbacks.

Record the Python profile-runtime decision and update the active naming, installed-wheel, and SEA packaging notes with precise supersession. Regenerate the configuration catalog and module graph after deleting the carrier, update both reviewed languages and pairing records, and classify the retained standalone Cordis files as lower-level test fixtures rather than launch interfaces.
This commit is contained in:
Tianyi Cui
2026-08-24 17:28:27 +08:00
parent 01da043737
commit f0f9b294dd
61 changed files with 480 additions and 324 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/user/guide/python-sdk.i18n.yaml
+2 -2
View File
@@ -2,5 +2,5 @@
# side as of the last confirmed-consistent state. Both languages carry equal authority;
# after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write docs/user/guide/python-sdk.md
python-sdk.md: 21c7a908a8524b16baf8f98453746f59b5d5efc8
python-sdk.zh.md: bb883f6f3799225bda590a80883063ecb29e15b4
python-sdk.md: 4fbc6b343714b232b90a7954b35bf6863716281b
python-sdk.zh.md: 51637ed986d298d46633891077bf2a9d27c35bdd
docs/user/guide/python-sdk.md
+35 -31
View File
@@ -2,7 +2,7 @@
English | [中文](python-sdk.zh.md)
This tutorial is the programmatic alternative to the Web UI. It installs the published Python SDK, runs a checked-in agent composition, and shows how to call the same API from your own program.
This tutorial installs the published Python SDK, runs the checked-in minimal profile overlay, and shows how to customize the same `dsh` profile from your own program.
## Prerequisites
@@ -10,12 +10,10 @@ This tutorial is the programmatic alternative to the Web UI. It installs the pub
- Git
- Linux x64, Linux arm64, or macOS 14 or newer on arm64
- A DeepSeek-compatible API endpoint and credential
- An isolated workspace that the agent may modify
- An isolated workspace and an isolated Harness home
## Install the SDK
Clone the repository for its runnable example, create a virtual environment, and install the SDK with its same-version bundled runtime:
```sh
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
@@ -24,51 +22,48 @@ python -m venv .venv
python -m pip install deepseek-harness-sdk
```
The installed runtime needs no system Node.js. Repository contributors who need to build the runtime or wheels from source should use the [Python contributor workflows](../../../python/development.md).
The installation includes a matching native runtime wheel and the `dsh` command. Normal SDK execution needs no system Node.js. Repository contributors who build the artifacts should use the [Python contributor workflow](../../../python/development.md).
## Run the checked-in example
Set the credential in the environment. Set `DEEPSEEK_BASE_URL` as well when the model is served by an OpenAI-compatible proxy rather than the default DeepSeek endpoint.
Export the credential and, when needed, a compatible proxy endpoint:
```sh
export DEEPSEEK_API_KEY=sk-your-key-here
# export DEEPSEEK_BASE_URL=http://127.0.0.1:8000/v1
# export DSH_MODEL=deepseek-v4-flash
# export DSH_SYSTEM_PROMPT='You are a helpful software engineer assistant.'
```
Run one task against an isolated workspace and session directory:
Run one task with explicit workspace and home paths:
```sh
python examples/python-sdk-agent/minimal.py \
--workspace /absolute/path/to/workspace \
--session-root /absolute/path/to/sessions \
--workspace /absolute/path/to/disposable-workspace \
--dsh-home /absolute/path/to/example-dsh-home \
--session-id example-001 \
"Inspect the repository and fix the failing tests."
```
The script prints the final assistant response. The session directory receives a JSONL log containing the assembled model requests and tool calls.
The script prints the final assistant response. The selected home receives the generated `sdk` profile, settings, credentials if you add them, installed plugins, and Zstandard session logs under `sessions/`. The example and SDK never silently read `~/.dsh`.
## Use the SDK in your own program
The checked-in example is a thin wrapper around this SDK call:
## Use the SDK in your program
```python
from pathlib import Path
from deepseek_harness import DeepSeekHarness
config = Path("examples/python-sdk-agent/minimal.cordis.yml").resolve()
workspace = Path("/absolute/path/to/workspace").resolve()
sessions = Path("/absolute/path/to/sessions").resolve()
workspace = Path("/absolute/path/to/disposable-workspace").resolve()
dsh_home = Path("/absolute/path/to/example-dsh-home").resolve()
patch = Path("examples/python-sdk-agent/minimal.patch.yml").resolve()
with DeepSeekHarness(
provider="deepseek-official",
model="deepseek-v4-flash",
max_tokens=49_152,
cwd=str(workspace),
session_root=str(sessions),
cordis=str(config),
dsh_home=str(dsh_home),
profile="sdk",
patches=(str(patch),),
) as harness:
result = harness.run(
"Inspect the repository and fix the failing tests.",
@@ -78,9 +73,23 @@ with DeepSeekHarness(
print(result.final_response)
```
`DeepSeekHarness` starts the bundled runtime lazily and reuses it until the context manager exits. Reusing the same harness and session id preserves the session-owned Bash process, including its working directory, exported variables, and shell functions. Use a fresh session id for an independent task; reuse an id only when the next call should continue the same durable conversation.
The SDK starts the bundled `dsh --profile sdk` process lazily and reuses it until context-manager exit. The profile, its persistent patch, the home patch, and the ordered `patches` tuple form the application configuration. There is no separate Python runtime bin or complete-config option.
## Understand the example composition
## Install or define plugins
Use `dsh plugin` for dependencies and bundle layers that should persist in this home:
```sh
export DSH_HOME=/absolute/path/to/example-dsh-home
dsh --profile sdk --dump-default-config >/dev/null
dsh plugin --profile sdk add file:/absolute/path/to/my-plugin-bundle
```
The first command initializes the shipped SDK profile. The second forwards package management to `pnpm`, then records any installed package that exports a `dsh.bundle` layer. Install `pnpm` only for this management command; launching the installed SDK does not need it. Edit `$DSH_HOME/profiles/sdk/cordis.patch.yml` for persistent row changes, or pass patch files from Python for per-launch changes.
Another `profile` is valid when it includes `@deepseek-ai/dsh-sdk-app` or another JSON-RPC server row. Missing server rows, unresolved plugins, and invalid patches fail during startup instead of falling back to another composition.
## Understand the minimal overlay
| Property | Value |
|---|---|
@@ -90,15 +99,10 @@ print(result.final_response)
| Bash timeout | 300 seconds |
| Editor output limit | 16,000 characters |
| Context compaction | Disabled |
| Filesystem | Bare local backend; absolute editor paths may address any path visible to the runtime process |
| Session persistence | Uncompressed JSONL under `DSH_SESSION_ROOT` |
| Session persistence | Zstandard JSONL under `<dsh_home>/sessions` |
The composition omits harness identity, workspace prompt text, skills, one-shot Bash, task tools, compaction, and every other model-facing plugin. Sandbox-policy facts are logged as runtime user context rather than appended to the system prompt.
The overlay removes runtime-context prompt messages and most default tools while retaining the SDK application's protocol and persistence. Persistent Bash and the editor can modify any path visible to the runtime, so use a disposable checkout or container. The PTY implementation makes this example POSIX-only.
## Choose workspace and session IDs
Use a fresh home when profiles, plugins, credentials, settings, and sessions must be isolated. Use a fresh session id for independent work; reuse a harness, home, and id only to continue the same durable conversation and session-owned resources.
`cwd` selects the workspace available to the agent, while `session_root` stores session logs and state. Use a fresh session id for an independent task; reuse an id only when the next call should continue the same conversation and persistent shell state.
The composition uses `danger-full-access`. Run it only inside a disposable checkout or container: Bash and the editor can modify any path allowed to the runtime process. The persistent PTY backend requires a POSIX terminal substrate, so this composition does not support Windows agents.
The [`python-sdk-agent` example reference](../../../examples/python-sdk-agent/README.md) owns the exact composition. The [Python SDK reference](../../../python/sdk/README.md) covers lifecycle, results, notifications, runtime selection, and configuration; the [Cordis primer](../../cordis-primer.md) covers composition syntax.
The [example reference](../../../examples/python-sdk-agent/README.md) owns the checked-in overlay. The [Python SDK reference](../../../python/sdk/README.md) covers lifecycle, results, notifications, and low-level behavior; the [dsh CLI reference](../../../apps/cli/reference/README.md) covers profile layering.
docs/user/guide/python-sdk.zh.md
+44 -40
View File
@@ -1,21 +1,19 @@
# Python SDK 快速上手
# Python SDK 入门
[English](python-sdk.md) | 中文
本教程介绍 Web UI 之外的程序化使用方式：安装已发布的 Python SDK、运行仓库内置的 agent（智能体）组合，并在自己的程序中调用同一套 API。
本教程安装已发布的 Python SDK，运行检入的极简 profile overlay，并说明如何从自己的程序自定义同一个 `dsh` profile。
## 前置要求
## 前置条件
- Python 3.10 或更高版本
- Git
- Linux x64、Linux arm64 或 macOS 14 或更高版本的 arm64
- DeepSeek 兼容的 API 端点与凭据
- agent 可以修改的隔离 workspace
- Linux x64、Linux arm64，或 arm64 上的 macOS 14 或更高版本
- DeepSeek 兼容的 API endpoint 与凭据
- 隔离的 workspace 与隔离的 Harness home
## 安装 SDK
克隆仓库以使用其中的可运行示例，创建虚拟环境，并安装 SDK 及其同版本内置运行时：
```sh
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
@@ -24,51 +22,48 @@ python -m venv .venv
python -m pip install deepseek-harness-sdk
```
安装后的运行时不需要系统提供 Node.js。需要从源码构建运行时或 wheel 包的仓库贡献者应使用 [Python 贡献者工作流](../../../python/development.zh.md)。
安装内容包含匹配的原生运行时 wheel 与 `dsh` 命令。普通 SDK 运行不需要系统 Node.js。需要构建产物的仓库贡献者应使用 [Python 贡献者工作流](../../../python/development.zh.md)。
## 运行仓库内置示例
## 运行检入示例
请在环境中设置凭据。如果模型不是由默认 DeepSeek 端点提供，而是通过 OpenAI 兼容代理提供，还需要设置 `DEEPSEEK_BASE_URL`。
导出凭据；使用兼容代理时再设置 endpoint：
```sh
export DEEPSEEK_API_KEY=sk-your-key-here
# export DEEPSEEK_BASE_URL=http://127.0.0.1:8000/v1
# export DSH_MODEL=deepseek-v4-flash
# export DSH_SYSTEM_PROMPT='You are a helpful software engineer assistant.'
```
针对隔离的 workspace 和会话目录运行一个任务：
使用显式 workspace 与 home 路径运行一个任务：
```sh
python examples/python-sdk-agent/minimal.py \
--workspace /absolute/path/to/workspace \
--session-root /absolute/path/to/sessions \
--workspace /absolute/path/to/disposable-workspace \
--dsh-home /absolute/path/to/example-dsh-home \
--session-id example-001 \
"Inspect the repository and fix the failing tests."
```
脚本会打印 assistant 的最终回复。会话目录会收到 JSONL 日志，其中包含组装后的模型请求与工具调用。
脚本会打印最终 assistant 响应。所选 home 会保存生成的 `sdk` profile、设置、调用方添加的凭据、已安装插件，以及 `sessions/` 下的 Zstandard 会话日志。示例与 SDK 绝不会静默读取 `~/.dsh`。
## 在自己的程序中使用 SDK
仓库内置示例是以下 SDK 调用的轻量包装：
## 在程序中使用 SDK
```python
from pathlib import Path
from deepseek_harness import DeepSeekHarness
config = Path("examples/python-sdk-agent/minimal.cordis.yml").resolve()
workspace = Path("/absolute/path/to/workspace").resolve()
sessions = Path("/absolute/path/to/sessions").resolve()
workspace = Path("/absolute/path/to/disposable-workspace").resolve()
dsh_home = Path("/absolute/path/to/example-dsh-home").resolve()
patch = Path("examples/python-sdk-agent/minimal.patch.yml").resolve()
with DeepSeekHarness(
provider="deepseek-official",
model="deepseek-v4-flash",
max_tokens=49_152,
cwd=str(workspace),
session_root=str(sessions),
cordis=str(config),
dsh_home=str(dsh_home),
profile="sdk",
patches=(str(patch),),
) as harness:
result = harness.run(
"Inspect the repository and fix the failing tests.",
@@ -78,27 +73,36 @@ with DeepSeekHarness(
print(result.final_response)
```
`DeepSeekHarness` 会延迟启动内置运行时，并持续复用，直至退出上下文管理器。复用同一个 harness 与 session id 会保留该会话拥有的 Bash 进程，包括其工作目录、已导出的变量与 shell 函数。独立任务应使用新的 session id；只有下一次调用需要延续同一段持久化对话时，才复用原有 id。
SDK 会延迟启动内置的 `dsh --profile sdk` 进程，并复用到上下文管理器退出。Profile、其持久 patch、home patch 与有序 `patches` tuple 共同组成应用配置。不存在独立 Python 运行时 bin 或完整配置选项。
## 了解示例组合
## 安装或定义插件
需要在该 home 中持久保存依赖与 bundle 层时，使用 `dsh plugin`：
```sh
export DSH_HOME=/absolute/path/to/example-dsh-home
dsh --profile sdk --dump-default-config >/dev/null
dsh plugin --profile sdk add file:/absolute/path/to/my-plugin-bundle
```
第一个命令初始化随附的 SDK profile。第二个命令把包管理转发给 `pnpm`，然后记录所有导出 `dsh.bundle` 层的已安装包。只有执行此管理命令时才需要安装 `pnpm`；启动已安装 SDK 不需要它。持久配置项变更应编辑 `$DSH_HOME/profiles/sdk/cordis.patch.yml`；单次启动变更则从 Python 传入 patch 文件。
另一个 `profile` 只有包含 `@deepseek-ai/dsh-sdk-app` 或另一个 JSON-RPC server 配置项时才有效。缺失 server 配置项、无法解析的插件和非法 patch 会在启动时失败，不会回退到其他组合。
## 理解极简 overlay
| 属性 | 值 |
|---|---|
| 系统提示词 | `DSH_SYSTEM_PROMPT`；未设置时使用 `You are a helpful software engineer assistant.` |
| `minimal.py` 使用的模型 | `--model`，其次为 `DSH_MODEL`，最后为 `deepseek-v4-flash` |
| 系统提示词 | `DSH_SYSTEM_PROMPT`，未设置时为 `You are a helpful software engineer assistant.` |
| `minimal.py` 的模型 | `--model`，然后是 `DSH_MODEL`，最后是 `deepseek-v4-flash` |
| 面向模型的工具 | 仅持久 `bash` 与 `str_replace_editor` |
| Bash 超时 | 300 秒 |
| 编辑器输出上限 | 16,000 个字符 |
| 上下文压缩 | 已关闭 |
| 文件系统 | 裸本地后端；编辑器使用绝对路径，可以访问运行时进程可见的任何路径 |
| 会话持久化 | `DSH_SESSION_ROOT` 下未压缩的 JSONL |
| Editor 输出上限 | 16,000 字符 |
| 上下文压缩 | 禁用 |
| 会话持久化 | `<dsh_home>/sessions` 下的 Zstandard JSONL |
该组合省略了 harness 身份、workspace 提示词文本、skill（技能）、一次性 Bash、任务工具、上下文压缩和其他所有面向模型的插件。沙箱策略事实记录为运行时用户上下文，而不会追加到系统提示词中。
该 overlay 会移除运行时上下文提示消息与大多数默认工具，但保留 SDK 应用的协议与持久化。持久 Bash 与 editor 可以修改运行时可见的任何路径，因此应使用一次性 checkout 或容器。由于采用 PTY 实现，本示例只支持 POSIX。
## 选择 workspace 与 session id
需要隔离 profile、插件、凭据、设置与会话时，应使用新的 home。独立工作应使用新的 session id；只有继续同一段持久对话和会话资源时，才同时复用 harness、home 与 id。
`cwd` 用于选择 agent 可访问的 workspace，`session_root` 用于保存会话日志和状态。独立任务应使用新的 session id；只有下一次调用需要延续同一段对话和持久 shell 状态时，才复用原有 id。
该组合使用 `danger-full-access`。只能在可丢弃的 checkout 或容器内运行：Bash 与编辑器可以修改运行时进程有权访问的任何路径。持久 PTY 后端需要 POSIX 终端环境，因此该组合不支持 Windows agent。
准确的组合内容归 [`python-sdk-agent` 示例参考](../../../examples/python-sdk-agent/README.zh.md)所有。[Python SDK 参考](../../../python/sdk/README.zh.md)介绍生命周期、结果、通知、运行时选择和配置；[Cordis primer](../../cordis-primer.zh.md)介绍组合语法。
[示例参考](../../../examples/python-sdk-agent/README.zh.md)定义检入 overlay。[Python SDK 参考](../../../python/sdk/README.zh.md)介绍生命周期、结果、通知与底层行为；[dsh CLI 参考](../../../apps/cli/reference/README.zh.md)介绍 profile 分层。