mirror of
https://github.com/deepseek-ai/deepseek-harness.git
synced 2026-08-30 04:40:37 +00:00
docs(python): make the dsh profile runtime current
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
@@ -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 分层。
|
||||
|
||||
Reference in New Issue
Block a user