Pine/deepseek-harness
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases 1 Wiki Activity

docs(python): generalize SDK guide

Browse Source
This commit is contained in:
Yichen Jiang
2026-08-10 19:53:51 +08:00
parent 299cafad01
commit 6dabf0ea99
13 changed files with 40 additions and 40 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/user/guide/python-sdk-minimal.i18n.yaml → docs/user/guide/python-sdk.i18n.yaml
+3 -3
View File
@@ -1,6 +1,6 @@
# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
# 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-minimal.md
python-sdk-minimal.md: e658fadae9575fd8bbc2aab2c622df7079c7addf
python-sdk-minimal.zh.md: ef37e1e801512bf60f212e69b61eb423ce4ab1d1
# pnpm run verify-translation-pairing --write docs/user/guide/python-sdk.md
python-sdk.md: c48bc95c9334cfd16a925d12726c20b2f968c753
python-sdk.zh.md: dc31c391a180a742c7dc10807f6ed2ef8d11927d
docs/user/guide/python-sdk-minimal.md → docs/user/guide/python-sdk.md
+10 -10
View File
@@ -1,8 +1,8 @@
# Run the minimal agent with the Python SDK
# Get started with the Python SDK
English | [中文](python-sdk-minimal.zh.md)
English | [中文](python-sdk.zh.md)
This tutorial runs the minimal agent without the Web UI. The checked-in Cordis composition fixes the system prompt, tool catalog, persistent-shell behavior, and compaction policy so SDK runs use the same model-facing contract as the Web `minimal` preset.
This tutorial installs the Python SDK, runs a checked-in Cordis composition without the Web UI, and uses the same API in your own program. It uses the compact [`minimal.cordis.yml`](../../../examples/jsonrpc-agent/minimal.cordis.yml) configuration as a complete example with a fixed system prompt, tool catalog, persistent-shell behavior, and compaction policy.
## Prerequisites
@@ -30,7 +30,7 @@ python -m pip install deepseek-harness-sdk
A source build additionally requires Git, Node.js ^22.19 or >= 24, Corepack-enabled pnpm 11, and `uv`. The following commands build the runtime for the current supported host platform, build both wheels, and install them into the active virtual environment:
```sh
git clone https://github.com/deepseek-ai/deepseek-harness-sdk.git
git clone https://github.com/deepseek-ai/deepseek-harness-sdk.git deepseek-harness
cd deepseek-harness
python -m pip install uv==0.11.23
corepack enable
@@ -70,12 +70,12 @@ Run one task from the repository checkout:
```sh
python examples/jsonrpc-agent/minimal.py \
--workspace /absolute/path/to/workspace \
--session-root /absolute/path/to/trajectories \
--session-root /absolute/path/to/sessions \
--session-id example-001 \
"Inspect the repository and fix the failing tests."
```
The script prints the final assistant response. The session root receives the JSONL trajectory, including the assembled model request and every tool call.
The script prints the final assistant response. The session root receives a JSONL session log containing the assembled model request and every tool call.
## Use the SDK in your own program
@@ -88,7 +88,7 @@ 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/trajectories").resolve()
sessions = Path("/absolute/path/to/sessions").resolve()
with DeepSeekHarness(
provider="deepseek-official",
@@ -108,7 +108,7 @@ print(result.final_response)
`DeepSeekHarness` starts the bundled JSON-RPC runtime lazily and reuses it until the context manager exits. Reusing the same harness and session id across calls also preserves the session-owned Bash process, including its working directory, exported variables, and shell functions.
## Contract reproduced by the configuration
## Understand the example configuration
| Surface | Fixed value |
|---|---|
@@ -121,9 +121,9 @@ print(result.final_response)
The configuration omits harness identity, workspace prompt text, skills, one-shot Bash, task tools, and every other model-facing plugin. Filesystem policy facts are logged as runtime user context rather than appended to the system prompt. The editor requires absolute paths as an unconditional current contract, so the obsolete `requireAbsolutePath` option is absent.
## Keep runs reproducible
## Choose workspace and session IDs
For comparable trajectories, pin the Harness commit and Python package version together, retain the exact Cordis file, and record the provider, model, endpoint, `max_tokens`, task input, workspace state, and session id for every run. Start independent runs with a clean workspace and a fresh session id; reuse a session only when multi-turn state is intentional.
`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 and is not a Windows agent surface.
docs/user/guide/python-sdk-minimal.zh.md → docs/user/guide/python-sdk.zh.md
+10 -10
View File
@@ -1,8 +1,8 @@
# 使用 Python SDK 运行极简 agent（智能体）
# Python SDK 快速上手
[English](python-sdk-minimal.md) | 中文
[English](python-sdk.md) | 中文
本教程介绍如何在不使用 Web UI 的情况下运行极简 agent。仓库内置的 Cordis 组合固定了系统提示词、工具目录、持久 shell 行为和压缩（compaction）策略，因此 SDK 运行与 Web `minimal` preset 使用相同的面向模型约定。
本教程介绍如何安装 Python SDK、在不使用 Web UI 的情况下运行仓库内置 Cordis 组合，以及如何在自己的程序中调用同一套 API。教程使用精简且完整的 [`minimal.cordis.yml`](../../../examples/jsonrpc-agent/minimal.cordis.yml) 作为示例，其中固定了系统提示词、工具目录、持久 shell 行为和压缩（compaction）策略。
## 前置要求
@@ -30,7 +30,7 @@ python -m pip install deepseek-harness-sdk
从源码构建还需要 Git、Node.js ^22.19 或 >= 24、通过 Corepack 启用的 pnpm 11，以及 `uv`。以下命令为当前受支持的宿主平台构建运行时和两个 wheel 包，并将它们安装进当前虚拟环境：
```sh
git clone https://github.com/deepseek-ai/deepseek-harness-sdk.git
git clone https://github.com/deepseek-ai/deepseek-harness-sdk.git deepseek-harness
cd deepseek-harness
python -m pip install uv==0.11.23
corepack enable
@@ -70,12 +70,12 @@ export DEEPSEEK_API_KEY=sk-your-key-here
```sh
python examples/jsonrpc-agent/minimal.py \
--workspace /absolute/path/to/workspace \
--session-root /absolute/path/to/trajectories \
--session-root /absolute/path/to/sessions \
--session-id example-001 \
"Inspect the repository and fix the failing tests."
```
脚本会打印 assistant 的最终回复。会话根目录会收到 JSONL 运行轨迹，其中包含组装后的模型请求与每次工具调用。
脚本会打印 assistant 的最终回复。会话根目录会收到 JSONL 会话日志，其中包含组装后的模型请求与每次工具调用。
## 在自己的程序中使用 SDK
@@ -88,7 +88,7 @@ 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/trajectories").resolve()
sessions = Path("/absolute/path/to/sessions").resolve()
with DeepSeekHarness(
provider="deepseek-official",
@@ -108,7 +108,7 @@ print(result.final_response)
`DeepSeekHarness` 会延迟启动内置 JSON-RPC 运行时，并持续复用，直至退出上下文管理器。在多次调用中复用同一个 harness 和 session id，还会保留该会话拥有的 Bash 进程，包括其工作目录、已导出的变量与 shell 函数。
## 配置复现的约定
## 了解示例配置
| 方面 | 固定值 |
|---|---|
@@ -121,9 +121,9 @@ print(result.final_response)
该配置省略了 harness 身份、workspace 提示词文本、skill（技能）、一次性 Bash、任务工具和其他所有面向模型的插件。文件系统策略事实记录为运行时用户上下文，而不会追加到系统提示词中。编辑器无条件要求绝对路径，因此配置中没有已经废弃的 `requireAbsolutePath` 选项。
## 保持运行可复现
## 选择 workspace 与 session id
为了让运行轨迹可复现且便于比较，请配套固定 Harness commit 与 Python 包版本，保留确切的 Cordis 文件，并为每次运行记录提供方、模型、端点、`max_tokens`、任务输入、workspace 状态和 session id。独立运行应使用干净的 workspace 和新的 session id；只有有意保留多轮状态时才复用会话。
`cwd` 用于选择 agent 可访问的 workspace，`session_root` 用于保存会话日志和状态。独立任务应使用新的 session id；只有下一次调用需要延续同一段对话和持久 shell 状态时，才复用原有 id。
该组合使用 `danger-full-access`。只能在可丢弃的 checkout 或容器内运行：Bash 与编辑器可以修改运行时进程有权访问的任何路径。持久 PTY 后端需要 POSIX 终端环境，因此该模式不适用于 Windows agent。
docs/user/guide/quickstart.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/quickstart.md
quickstart.md: 13d5b2196282394619747e36ecddfa1d87f61c8d
quickstart.zh.md: 3d775db9280b43bbee2de37f7327fe8d2bd3a121
quickstart.md: 6a0b292ce12b32b7993b7de56b35f1df2e7a7153
quickstart.zh.md: 008245f136e28630c7e8368eeec536e11112a885
docs/user/guide/quickstart.md
+1 -1
View File
@@ -57,7 +57,7 @@ Open `http://127.0.0.1:3080`. The agent can read and write files, run commands,
## Next steps
- [Run the minimal agent with Python](./python-sdk-minimal.md) — use the fixed two-tool composition without the Web UI
- [Get started with the Python SDK](./python-sdk.md) — install the SDK and run a complete Cordis configuration without the Web UI
- [Configure models](./providers.md) — reach providers beyond DeepSeek, and custom gateways
- [Configuration](./config.md) — understand the `cordis.yml` format
- [Develop a plugin](../develop/basic/) — build your own tool or backend
docs/user/guide/quickstart.zh.md
+1 -1
View File
@@ -57,7 +57,7 @@ pnpm run dsh web
## 下一步
- [使用 Python 运行极简 agent](./python-sdk-minimal.md) — 无需 Web UI，即可使用固定的双工具组合
- [Python SDK 快速上手](./python-sdk.md) — 安装 SDK，并在不使用 Web UI 的情况下运行完整 Cordis 配置
- [配置模型](./providers.md) — 接入 DeepSeek 之外的提供方与自定义网关
- [配置文件](./config.md) — 了解 `cordis.yml` 的格式
- [开发插件](../develop/basic/) — 编写自己的工具或后端