mirror of
https://github.com/deepseek-ai/deepseek-harness.git
synced 2026-08-29 04:26:38 +00:00
docs(python): define the standalone minimal profile
Record sdk-minimal as the narrow repository-owned exception to base-first profile composition: callers still launch only dsh and cannot provide an arbitrary Cordis tree, while the shipped bundle may own a complete explicit roster. Cross-link the launcher, profile-bundle, Python-runtime, minimal-agent, snapshot, and telemetry decisions; the supersession audit keeps each older note active because its remaining rationale is independent. Update the CLI, architecture, Python tutorial/reference, example, runtime-wheel reference, and bundle documentation. The docs distinguish the full sdk profile from sdk-minimal, explain explicit-home/plugin/patch customization, state the minimal permission and persistence choices, and retain the separately packaged web profile and frontend assets for direct dsh use. Correct dsh-base descriptions to cover base-backed profiles, make SDK startup configuration visible in the generated config catalog, add sdk-minimal to the module graph, and regenerate the base-composition graph. English and Chinese pairs are re-recorded at the exact reviewed contents.
This commit is contained in:
Tianyi Cui
@@ -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: 98d7f8160dee0874338c1d914796dcfb72400a48
|
||||
python-sdk.zh.md: 8a0417b24be859b8d327a8650ce1db23adb4dba2
|
||||
python-sdk.md: 2cf6acbd6718be560ec4365b356c031b17fb070e
|
||||
python-sdk.zh.md: 2c53886ba3409e6fc21ec57fc79b81bf6907349c
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
English | [中文](python-sdk.zh.md)
|
||||
|
||||
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.
|
||||
This tutorial installs the published Python SDK, runs the shipped standalone minimal profile, and shows how to customize the same `dsh` profile from your own program.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
@@ -43,7 +43,7 @@ python examples/python-sdk-agent/minimal.py \
|
||||
"Inspect the repository and fix the failing tests."
|
||||
```
|
||||
|
||||
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`.
|
||||
The script prints the final assistant response. The selected home receives the generated `sdk-minimal` profile, installed plugins, and uncompressed JSONL session logs under `sessions/`. The example and SDK never silently read `~/.dsh`.
|
||||
|
||||
## Use the SDK in your program
|
||||
|
||||
@@ -54,16 +54,14 @@ from deepseek_harness import DeepSeekHarness
|
||||
|
||||
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),
|
||||
dsh_home=str(dsh_home),
|
||||
profile="sdk",
|
||||
patches=(str(patch),),
|
||||
profile="sdk-minimal",
|
||||
env={"DSH_MODEL": "deepseek-v4-flash"},
|
||||
) as harness:
|
||||
result = harness.run(
|
||||
"Inspect the repository and fix the failing tests.",
|
||||
@@ -73,7 +71,7 @@ with DeepSeekHarness(
|
||||
print(result.final_response)
|
||||
```
|
||||
|
||||
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.
|
||||
The SDK starts the bundled `dsh --profile sdk-minimal` process lazily and reuses it until context-manager exit. The profile, its persistent patch, the home patch, and any ordered `patches` tuple form the application configuration. There is no separate Python runtime bin or complete-config option.
|
||||
|
||||
## Install or define plugins
|
||||
|
||||
@@ -81,15 +79,15 @@ Use `dsh plugin` for dependencies and bundle layers that should persist in this
|
||||
|
||||
```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
|
||||
dsh --profile sdk-minimal --dump-default-config >/dev/null
|
||||
dsh plugin --profile sdk-minimal 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.
|
||||
The first command initializes the shipped standalone 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-minimal/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
|
||||
## Understand the minimal profile
|
||||
|
||||
| Property | Value |
|
||||
|---|---|
|
||||
@@ -98,11 +96,13 @@ Another `profile` is valid when it includes `@deepseek-ai/dsh-sdk-app` or anothe
|
||||
| Model-facing tools | Persistent `bash` and `str_replace_editor` only |
|
||||
| Bash timeout | 300 seconds |
|
||||
| Editor output limit | 16,000 characters |
|
||||
| Context compaction | Disabled |
|
||||
| Session persistence | Zstandard JSONL under `<dsh_home>/sessions` |
|
||||
| Runtime context and compaction | Absent |
|
||||
| Session persistence | Uncompressed JSONL under `<dsh_home>/sessions` |
|
||||
|
||||
The overlay allowlists persistent Bash and the editor for every SDK-created root agent, so later base-profile tools cannot appear implicitly. It suppresses unrelated prompt sections and runtime-context messages, disables local instruction discovery and compaction, and retains the SDK application's protocol, persistence, policy, settings, credentials, and providers. 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.
|
||||
The profile's sole bundle inserts the complete tree over an empty root and does not include `dsh-base`; later base-profile tools therefore cannot appear implicitly. It contains the SDK protocol, one environment-configured DeepSeek adapter, local execution, and persistence, while settings, managed credentials, telemetry, Web tools, subagents, local instruction discovery, and compaction are absent. It pins `danger-full-access`, so persistent Bash and the editor can modify any path visible to the runtime; use a disposable checkout or container. The PTY implementation makes this example POSIX-only.
|
||||
|
||||
The installed wheel still packages the full `web` profile and frontend assets. Run `dsh web` against an explicit `DSH_HOME` when a Python SDK deployment also needs the browser application; `web` is a separate CLI application and cannot serve a Python SDK client.
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
The [bundle reference](../../../packages/bundle/sdk-minimal/README.md) owns the exact tree, and the [example reference](../../../examples/python-sdk-agent/README.md) owns the runnable program. 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.
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
[English](python-sdk.md) | 中文
|
||||
|
||||
本教程安装已发布的 Python SDK，运行检入的极简 profile overlay，并说明如何从自己的程序自定义同一个 `dsh` profile。
|
||||
本教程安装已发布的 Python SDK，运行随附的独立极简 profile，并说明如何从自己的程序自定义同一个 `dsh` profile。
|
||||
|
||||
## 前置条件
|
||||
|
||||
@@ -43,7 +43,7 @@ python examples/python-sdk-agent/minimal.py \
|
||||
"Inspect the repository and fix the failing tests."
|
||||
```
|
||||
|
||||
脚本会打印最终 assistant 响应。所选 home 会保存生成的 `sdk` profile、设置、调用方添加的凭据、已安装插件，以及 `sessions/` 下的 Zstandard 会话日志。示例与 SDK 绝不会静默读取 `~/.dsh`。
|
||||
脚本会打印最终 assistant 响应。所选 home 会保存生成的 `sdk-minimal` profile、已安装插件，以及 `sessions/` 下的未压缩 JSONL 会话日志。示例与 SDK 绝不会静默读取 `~/.dsh`。
|
||||
|
||||
## 在程序中使用 SDK
|
||||
|
||||
@@ -54,16 +54,14 @@ from deepseek_harness import DeepSeekHarness
|
||||
|
||||
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),
|
||||
dsh_home=str(dsh_home),
|
||||
profile="sdk",
|
||||
patches=(str(patch),),
|
||||
profile="sdk-minimal",
|
||||
env={"DSH_MODEL": "deepseek-v4-flash"},
|
||||
) as harness:
|
||||
result = harness.run(
|
||||
"Inspect the repository and fix the failing tests.",
|
||||
@@ -73,7 +71,7 @@ with DeepSeekHarness(
|
||||
print(result.final_response)
|
||||
```
|
||||
|
||||
SDK 会延迟启动内置的 `dsh --profile sdk` 进程，并复用到上下文管理器退出。Profile、其持久 patch、home patch 与有序 `patches` tuple 共同组成应用配置。不存在独立 Python 运行时 bin 或完整配置选项。
|
||||
SDK 会延迟启动内置的 `dsh --profile sdk-minimal` 进程，并复用到上下文管理器退出。Profile、其持久 patch、home patch 与任何有序 `patches` tuple 共同组成应用配置。不存在独立 Python 运行时 bin 或完整配置选项。
|
||||
|
||||
## 安装或定义插件
|
||||
|
||||
@@ -81,15 +79,15 @@ SDK 会延迟启动内置的 `dsh --profile sdk` 进程，并复用到上下文
|
||||
|
||||
```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
|
||||
dsh --profile sdk-minimal --dump-default-config >/dev/null
|
||||
dsh plugin --profile sdk-minimal 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。第二个命令把包管理转发给 `pnpm`，然后记录所有导出 `dsh.bundle` 层的已安装包。只有执行此管理命令时才需要安装 `pnpm`；启动已安装 SDK 不需要它。持久配置项变更应编辑 `$DSH_HOME/profiles/sdk-minimal/cordis.patch.yml`；单次启动变更则从 Python 传入 patch 文件。
|
||||
|
||||
另一个 `profile` 只有包含 `@deepseek-ai/dsh-sdk-app` 或另一个 JSON-RPC server 配置项时才有效。缺失 server 配置项、无法解析的插件和非法 patch 会在启动时失败，不会回退到其他组合。
|
||||
|
||||
## 理解极简 overlay
|
||||
## 理解极简 profile
|
||||
|
||||
| 属性 | 值 |
|
||||
|---|---|
|
||||
@@ -98,11 +96,13 @@ dsh plugin --profile sdk add file:/absolute/path/to/my-plugin-bundle
|
||||
| 面向模型的工具 | 仅持久 `bash` 与 `str_replace_editor` |
|
||||
| Bash 超时 | 300 秒 |
|
||||
| Editor 输出上限 | 16,000 字符 |
|
||||
| 上下文压缩 | 禁用 |
|
||||
| 会话持久化 | `<dsh_home>/sessions` 下的 Zstandard JSONL |
|
||||
| 运行时上下文与 compaction | 不存在 |
|
||||
| 会话持久化 | `<dsh_home>/sessions` 下的未压缩 JSONL |
|
||||
|
||||
该 overlay 会为每个由 SDK 创建的根 agent allowlist 持久 Bash 与 editor，因此基础 profile 以后新增的工具不会隐式出现。它会抑制无关提示词段与运行时上下文消息，停用本地指令发现与 compaction，并保留 SDK 应用的协议、持久化、策略、settings、credentials 与 provider。持久 Bash 与 editor 可以修改运行时可见的任何路径，因此应使用一次性 checkout 或容器。由于采用 PTY 实现，本示例只支持 POSIX。
|
||||
该 profile 的唯一组合包会在空根之上插入完整配置树，且不包含 `dsh-base`，因此基础 profile 以后新增的工具不会隐式出现。它包含 SDK 协议、一个由环境配置的 DeepSeek 适配器、本地执行与持久化；settings、托管凭据、遥测、Web 工具、subagent、本地指令发现和 compaction 均不存在。它固定使用 `danger-full-access`，因此持久 Bash 与 editor 可以修改运行时可见的任何路径；应使用一次性 checkout 或容器。由于采用 PTY 实现，本示例只支持 POSIX。
|
||||
|
||||
已安装 wheel 仍会打包完整 `web` profile 与前端产物。如果 Python SDK 部署还需要浏览器应用，请针对显式 `DSH_HOME` 运行 `dsh web`；`web` 是独立 CLI 应用，不能为 Python SDK client 提供服务。
|
||||
|
||||
需要隔离 profile、插件、凭据、设置与会话时，应使用新的 home。独立工作应使用新的 session id；只有继续同一段持久对话和会话资源时，才同时复用 harness、home 与 id。
|
||||
|
||||
[示例参考](../../../examples/python-sdk-agent/README.zh.md)定义检入 overlay。[Python SDK 参考](../../../python/sdk/README.zh.md)介绍生命周期、结果、通知与底层行为；[dsh CLI 参考](../../../apps/cli/reference/README.zh.md)介绍 profile 分层。
|
||||
[组合包参考](../../../packages/bundle/sdk-minimal/README.zh.md)定义确切配置树，[示例参考](../../../examples/python-sdk-agent/README.zh.md)定义可运行程序。[Python SDK 参考](../../../python/sdk/README.zh.md)介绍生命周期、结果、通知与底层行为；[dsh CLI 参考](../../../apps/cli/reference/README.zh.md)介绍 profile 分层。
|
||||
|
||||
Reference in New Issue
Block a user