docs: make Web UI the primary onboarding path
This commit is contained in:
Turtle
@@ -2,59 +2,29 @@
|
||||
|
||||
[English](python-sdk.md) | 中文
|
||||
|
||||
本教程介绍如何安装 Python SDK、在不使用 Web UI 的情况下运行仓库内置 Cordis 组合，以及如何在自己的程序中调用同一套 API。教程使用精简且完整的 [`minimal.cordis.yml`](../../../examples/jsonrpc-agent/minimal.cordis.yml) 作为示例，其中包含可配置的系统提示词、双工具目录和持久 shell 行为，并关闭上下文压缩（context compaction）。
|
||||
本教程介绍 Web UI 之外的程序化使用方式：安装已发布的 Python SDK、运行仓库内置的 agent（智能体）组合，并在自己的程序中调用同一套 API。
|
||||
|
||||
## 前置要求
|
||||
|
||||
- Python 3.10 或更高版本
|
||||
- Git
|
||||
- Linux x64、Linux arm64 或 macOS arm64
|
||||
- DeepSeek 兼容的 API 端点与凭据
|
||||
- agent 可以修改的隔离 workspace
|
||||
|
||||
## 安装 SDK
|
||||
|
||||
可以选择安装公开包或从源码构建。两种方式都会安装 `deepseek-harness-sdk` 分发包，并提供 `deepseek_harness` Python 模块。
|
||||
|
||||
### 从 PyPI 安装
|
||||
|
||||
请创建虚拟环境，并安装 SDK 及其同版本内置运行时：
|
||||
克隆仓库以使用其中的可运行示例，创建虚拟环境，并安装 SDK 及其同版本内置运行时：
|
||||
|
||||
```sh
|
||||
git clone https://github.com/deepseek-harness/deepseek-harness.git
|
||||
cd deepseek-harness
|
||||
python -m venv .venv
|
||||
. .venv/bin/activate
|
||||
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.git deepseek-harness
|
||||
cd deepseek-harness
|
||||
python -m pip install uv==0.11.23
|
||||
corepack enable
|
||||
pnpm install
|
||||
|
||||
case "$(uname -s):$(uname -m)" in
|
||||
Linux:x86_64) runtime_platform=linux-x64 ;;
|
||||
Linux:aarch64|Linux:arm64) runtime_platform=linux-arm64 ;;
|
||||
Darwin:arm64) runtime_platform=macos-arm64 ;;
|
||||
*) echo "unsupported platform" >&2; exit 1 ;;
|
||||
esac
|
||||
|
||||
pnpm exec tsx scripts/build-exe-for-python-sdk.ts --targets="node24-$runtime_platform"
|
||||
version="$(node -p "require('./package.json').version")"
|
||||
python scripts/build-python-release.py --package sdk --output-dir dist-python
|
||||
python scripts/build-python-release.py \
|
||||
--package runtime \
|
||||
--platform "$runtime_platform" \
|
||||
--runtime-exe "dist-exe/dsh-jsonrpc-agent-pkg-$runtime_platform" \
|
||||
--output-dir dist-python
|
||||
python -m pip install --find-links dist-python "deepseek-harness-sdk==$version"
|
||||
```
|
||||
|
||||
运行时 wheel 包含 JSON-RPC 可执行文件，以及完整 [`minimal.cordis.yml`](../../../examples/jsonrpc-agent/minimal.cordis.yml) 使用的每个插件，因此两种安装方式完成后都不再需要 Node.js。
|
||||
安装后的运行时不需要系统提供 Node.js。需要从源码构建运行时或 wheel 包的仓库贡献者应使用 [Python 贡献者工作流](../../../python/development.md)。
|
||||
|
||||
## 运行仓库内置示例
|
||||
|
||||
@@ -67,7 +37,7 @@ export DEEPSEEK_API_KEY=sk-your-key-here
|
||||
# export DSH_SYSTEM_PROMPT='You are a helpful software engineer assistant.'
|
||||
```
|
||||
|
||||
从仓库 checkout 运行一个任务：
|
||||
针对隔离的 workspace 和会话目录运行一个任务：
|
||||
|
||||
```sh
|
||||
python examples/jsonrpc-agent/minimal.py \
|
||||
@@ -77,11 +47,11 @@ python examples/jsonrpc-agent/minimal.py \
|
||||
"Inspect the repository and fix the failing tests."
|
||||
```
|
||||
|
||||
脚本会打印 assistant 的最终回复。会话根目录会收到 JSONL 会话日志，其中包含组装后的模型请求与每次工具调用。
|
||||
脚本会打印 assistant 的最终回复。会话目录会收到 JSONL 日志，其中包含组装后的模型请求与工具调用。
|
||||
|
||||
## 在自己的程序中使用 SDK
|
||||
|
||||
该示例是以下 SDK 调用的轻量包装层：
|
||||
仓库内置示例是以下 SDK 调用的轻量包装：
|
||||
|
||||
```python
|
||||
from pathlib import Path
|
||||
@@ -108,9 +78,9 @@ with DeepSeekHarness(
|
||||
print(result.final_response)
|
||||
```
|
||||
|
||||
`DeepSeekHarness` 会延迟启动内置 JSON-RPC 运行时，并持续复用，直至退出上下文管理器。在多次调用中复用同一个 harness 和 session id，还会保留该会话拥有的 Bash 进程，包括其工作目录、已导出的变量与 shell 函数。
|
||||
`DeepSeekHarness` 会延迟启动内置运行时，并持续复用，直至退出上下文管理器。复用同一个 harness 与 session id 会保留该会话拥有的 Bash 进程，包括其工作目录、已导出的变量与 shell 函数。独立任务应使用新的 session id；只有下一次调用需要延续同一段持久化对话时，才复用原有 id。
|
||||
|
||||
## 了解示例配置
|
||||
## 了解示例组合
|
||||
|
||||
| 属性 | 值 |
|
||||
|---|---|
|
||||
@@ -123,7 +93,7 @@ print(result.final_response)
|
||||
| 文件系统 | 裸本地后端；编辑器使用绝对路径，可以访问运行时进程可见的任何路径 |
|
||||
| 会话持久化 | `DSH_SESSION_ROOT` 下未压缩的 JSONL |
|
||||
|
||||
该配置省略了 harness 身份、workspace 提示词文本、skill（技能）、一次性 Bash、任务工具、上下文压缩和其他所有面向模型的插件。沙箱策略事实记录为运行时用户上下文，而不会追加到系统提示词中。编辑器无条件要求绝对路径，因此配置中没有已经废弃的 `requireAbsolutePath` 选项。
|
||||
该组合省略了 harness 身份、workspace 提示词文本、skill（技能）、一次性 Bash、任务工具、上下文压缩和其他所有面向模型的插件。沙箱策略事实记录为运行时用户上下文，而不会追加到系统提示词中。
|
||||
|
||||
## 选择 workspace 与 session id
|
||||
|
||||
@@ -131,4 +101,4 @@ print(result.final_response)
|
||||
|
||||
该组合使用 `danger-full-access`。只能在可丢弃的 checkout 或容器内运行：Bash 与编辑器可以修改运行时进程有权访问的任何路径。持久 PTY 后端需要 POSIX 终端环境，因此该组合不支持 Windows agent。
|
||||
|
||||
完整的 SDK 生命周期与结果约定见 [Python SDK 参考](../../../python/sdk/README.md)。Cordis 组合语法见[配置](./config.md)。
|
||||
准确的组合内容归 [`jsonrpc-agent` 示例参考](../../../examples/jsonrpc-agent/README.md)所有。[Python SDK 参考](../../../python/sdk/README.md)介绍生命周期、结果、通知、运行时选择和配置；[Cordis primer](../../cordis-primer.md)介绍组合语法。
|
||||
Reference in New Issue
Block a user