docs(python): generalize SDK guide

2026-08-15 21:04:50 +00:00 · 2026-08-10 19:53:51 +08:00
parent 299cafad01
commit 6dabf0ea99
13 changed files with 40 additions and 40 deletions
--- a/docs/user/guide/python-sdk-minimal.i18n.yaml
+++ b/docs/user/guide/python-sdk-minimal.i18n.yaml
@@ -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
--- a/docs/user/guide/python-sdk-minimal.md
+++ b/docs/user/guide/python-sdk-minimal.md
@@ -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.

--- a/docs/user/guide/python-sdk-minimal.zh.md
+++ b/docs/user/guide/python-sdk-minimal.zh.md
@@ -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。

--- a/docs/user/guide/quickstart.i18n.yaml
+++ b/docs/user/guide/quickstart.i18n.yaml
@@ -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
--- a/docs/user/guide/quickstart.md
+++ b/docs/user/guide/quickstart.md
@@ -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
--- a/docs/user/guide/quickstart.zh.md
+++ b/docs/user/guide/quickstart.zh.md
@@ -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/) — 编写自己的工具或后端
--- a/examples/jsonrpc-agent/README.i18n.yaml
+++ b/examples/jsonrpc-agent/README.i18n.yaml
@@ -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 examples/jsonrpc-agent/README.md
-README.md: 863b39eb9c7c65d36ceca77e945379fdd1d5fe22
-README.zh.md: a8334320896d2b16e166ef0f0ec300ab1cb0ca93
+README.md: 5f60a64a4888c64e4fd68835f78e4a334ffed263
+README.zh.md: 8d2f9807ff259000b5a6823357f8c41b43bfa434
--- a/examples/jsonrpc-agent/README.md
+++ b/examples/jsonrpc-agent/README.md
@@ -21,7 +21,7 @@ The surrounding runtime also loads JSONL session persistence and automatic conte
 | `DEEPSEEK_BASE_URL` | Host endpoint used by `dsh-llm-deepseek` |
 | `DSH_CWD` | Agent workspace for bash and filesystem tools |
 | `DSH_MAX_TOKENS_AS_SUCCESS` | `true` (default) accepts token-limited results; `false` reports them as errors |
-| `DSH_SESSION_ROOT` | JSONL trajectory directory |
+| `DSH_SESSION_ROOT` | JSONL session directory |
 | `DSH_SYSTEM_PROMPT` | Deployment-provided coding persona |

 Pass the config path through the Python SDK's `cordis` option or `DSH_CORDIS_CONFIG`. The bundled executable already carries every plugin named by this file; the target machine does not need Node.js.
@@ -33,4 +33,4 @@ Pass the config path through the Python SDK's `cordis` option or `DSH_CORDIS_CON
 - owner-scoped persistent `bash`
 - `str_replace_editor` with `view`, `create`, `str_replace`, and `insert`

-It composes the local PTY, filesystem intent policy, session sandbox policy, and JSONL persistence needed by the bundled runtime. [`minimal.py`](minimal.py) runs it through the Python SDK; the [minimal Python SDK tutorial](../../docs/user/guide/python-sdk-minimal.md) covers setup, repeatable runs, and the security boundary.
+It composes the local PTY, filesystem intent policy, session sandbox policy, and JSONL persistence needed by the bundled runtime. [`minimal.py`](minimal.py) runs it through the Python SDK; the [Python SDK tutorial](../../docs/user/guide/python-sdk.md) uses this configuration to cover setup, session management, and the security boundary.
--- a/examples/jsonrpc-agent/README.zh.md
+++ b/examples/jsonrpc-agent/README.zh.md
@@ -21,7 +21,7 @@
 | `DEEPSEEK_BASE_URL` | `dsh-llm-deepseek` 使用的宿主端点 |
 | `DSH_CWD` | bash 和文件系统工具使用的 agent workspace |
 | `DSH_MAX_TOKENS_AS_SUCCESS` | `true`（默认）接受受 token 上限限制的结果；`false` 将其报告为错误 |
-| `DSH_SESSION_ROOT` | JSONL 轨迹目录 |
+| `DSH_SESSION_ROOT` | JSONL 会话目录 |
 | `DSH_SYSTEM_PROMPT` | 由部署提供的编码人格 |

 通过 Python SDK 的 `cordis` 选项或 `DSH_CORDIS_CONFIG` 传入配置路径。内置可执行文件已携带此文件中指定的每个插件；目标机器无需 Node.js。
@@ -33,4 +33,4 @@
 - 所有者作用域内持久化的 `bash`
 - 提供 `view`、`create`、`str_replace` 与 `insert` 的 `str_replace_editor`

-它组合了内置运行时所需的本地 PTY、文件系统意图策略、会话沙箱策略与 JSONL 持久化。[`minimal.py`](minimal.py) 通过 Python SDK 运行该配置；[极简 Python SDK 教程](../../docs/user/guide/python-sdk-minimal.md)介绍设置方式、可重复运行与安全边界。
+它组合了内置运行时所需的本地 PTY、文件系统意图策略、会话沙箱策略与 JSONL 持久化。[`minimal.py`](minimal.py) 通过 Python SDK 运行该配置；[Python SDK 教程](../../docs/user/guide/python-sdk.md)以此配置介绍设置方式、会话管理与安全边界。
--- a/python/sdk/README.i18n.yaml
+++ b/python/sdk/README.i18n.yaml
@@ -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 python/sdk/README.md
-README.md: 2350fbfd5dd0094bfd7a11f81d8226e960879923
-README.zh.md: 5120a8c5f65360485d450614186d5cb2702fda17
+README.md: 9640c7e8dfd011b94acdc781ae0e4fdc8ad87378
+README.zh.md: 47ac04f9083ef41e23fda8ec527c1da160fe4769
--- a/python/sdk/README.md
+++ b/python/sdk/README.md
@@ -40,7 +40,7 @@ with DeepSeekHarness(

 `provider` selects a provider route registered by the chosen Cordis composition; `model` is the model id resolved by that adapter. `max_tokens` is an optional positive per-request output-token cap for the root agent and its in-process descendants; omission leaves the provider default in control. Compaction summaries keep the separate limit configured by their compaction plugin. The bundled default composition registers `deepseek-official`. A custom composition can mount `llm-pi-ai`, configure provider-specific credentials/endpoints there, and select any provider/model present in pi-ai's installed catalog.

-The [minimal-agent tutorial](../../docs/user/guide/python-sdk-minimal.md) provides a complete standalone Cordis file and runnable SDK example for using the two-tool minimal mode without the Web UI.
+The [Python SDK tutorial](../../docs/user/guide/python-sdk.md) uses a complete standalone Cordis file to demonstrate installation, direct SDK usage, and runs without the Web UI.

 `Session.run()` owns an activity interval from its prompt's durable inbox receipt through the next whole-agent idle and returns `RunResult(session_id, final_response, events, notifications, session_root)`. The result has no prompt-level status or turn reason: `final_response` is the last committed root-session assistant text in the interval, not an output causally assigned to the prompt. Steering, injected context, and other queued work may contribute before idle.

--- a/python/sdk/README.zh.md
+++ b/python/sdk/README.zh.md
@@ -37,7 +37,7 @@ with DeepSeekHarness(

 `provider` 用于选择当前 Cordis 组合已注册的提供方路由；`model` 是该适配器解析的模型 ID。`max_tokens` 是可选的正整数，用于限制根 agent（智能体）及其进程内后代每次请求的输出 token；省略时由提供方默认值控制。压缩摘要继续使用压缩插件单独配置的上限。内置默认组合注册 `deepseek-official`。自定义组合可以挂载 `llm-pi-ai`，在其中配置各提供方的凭据与端点，再选择 pi-ai 已安装目录中的任意提供方/模型组合。

-[极简 agent 教程](../../docs/user/guide/python-sdk-minimal.md)提供完整的独立 Cordis 文件与可运行的 SDK 示例，用于在不使用 Web UI 的情况下使用双工具极简模式。
+[Python SDK 教程](../../docs/user/guide/python-sdk.md)使用完整的独立 Cordis 文件演示安装方式、直接调用 SDK，以及在不使用 Web UI 的情况下运行 agent。

 `Session.run()` 拥有一个从提示词进入持久 inbox 时开始、到整个 agent 下一次进入空闲状态为止的活动区间，并返回 `RunResult(session_id, final_response, events, notifications, session_root)`。结果不携带提示词级状态或轮次原因：`final_response` 是该区间内根会话最后提交的助手文本，并非因果上归属于该提示词的输出。steering（中途引导）、注入的上下文和其他排队工作都可能在进入空闲状态前参与其中。

--- a/website/docs.ts
+++ b/website/docs.ts
@@ -139,9 +139,9 @@ const homeAndGuide = pairedPages([
    order: 3,
  },
  {
-    source: 'docs/user/guide/python-sdk-minimal.md',
-    route: 'guide/python-sdk-minimal.md',
-    label: { root: 'Python SDK 极简模式', en: 'Minimal mode with Python' },
+    source: 'docs/user/guide/python-sdk.md',
+    route: 'guide/python-sdk.md',
+    label: { root: 'Python SDK', en: 'Python SDK' },
    sidebar: { root: 'zh-guide', en: 'en-guide' },
    section: { root: '入门', en: 'Guide' },
    order: 4,