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.
2026-08-30 04:40:37 +00:00 · 2026-08-24 17:28:27 +08:00
parent 01da043737
commit f0f9b294dd
61 changed files with 480 additions and 324 deletions
@@ -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/python-sdk-agent/README.md
-README.md: 279aa5bcf0e988168cc936fbd6d96b69e74a5873
-README.zh.md: d843d8be719349b24e0369a2177748f2b09e40d6
+README.md: e46765b0419b0b614163fa507cadef0e5c5a53b9
+README.zh.md: 13c297bdbf01b612369ded5909ec8b7f71bab26c
@@ -2,39 +2,41 @@

 English | [中文](README.zh.md)

-The unattended coding-agent composition for the Python SDK's bundled JSON-RPC runtime. It intentionally loads no terminal UI, console logger, approval UI, or user-questions tool because stdout belongs to the SDK protocol and turns are driven by the SDK.
+Runnable Python SDK example over the sole application launcher, `dsh --profile sdk`. The Python client owns JSON-RPC stdio; the profile owns the agent composition, persistence, permissions, and plugins.

-The model-facing tools are:
+## Run the minimal agent

- `bash`, foreground only
- `read`, `write`, and `edit`
- `subagent`, using one foreground in-process spawn provider
- `todo_write`
+Install `deepseek-harness-sdk`, export a model credential, then supply an isolated Harness home and workspace:

-The surrounding runtime also loads JSONL session persistence and automatic context compaction. `maxTokensAsSuccess` keeps a token-limited model turn as an accepted evaluation result while preserving its `max-tokens` reason.
+```sh
+export DEEPSEEK_API_KEY=sk-your-key-here
+python examples/python-sdk-agent/minimal.py \
+  --dsh-home /absolute/path/to/example-dsh-home \
+  --workspace /absolute/path/to/disposable-workspace \
+  --session-id example-001 \
+  "Inspect the repository and fix the failing tests."
+```

-## Runtime environment
+Set `DEEPSEEK_BASE_URL` for a compatible proxy, `DSH_MODEL` for the default model, or `DSH_SYSTEM_PROMPT` for the deployment persona. `--model` and `--profile` override their script defaults. The selected home stores the generated profile and Zstandard session logs under `sessions/`; the script never reads `~/.dsh` implicitly.

-| Variable | Purpose |
-|---|---|
-| `DEEPSEEK_API_KEY` | Credential passed to the OpenAI-compatible host endpoint |
-| `DEEPSEEK_BASE_URL` | Host endpoint used by `dsh-llm-deepseek` |
-| `DSH_CWD` | Agent workspace for bash and filesystem tools |
-| `DSH_CONTEXT_WINDOW` | Context capacity recorded for the `DSH_MODEL` catalog entry in the minimal variant |
-| `DSH_MAX_TOKENS_AS_SUCCESS` | `true` (default) accepts token-limited results; `false` reports them as errors |
-| `DSH_MODEL` | Default model used by `minimal.py`; `--model` takes precedence |
-| `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.
-
-## Minimal variant
-
-[`minimal.cordis.yml`](minimal.cordis.yml) is the complete standalone counterpart of the Web `minimal` preset. `DSH_SYSTEM_PROMPT` selects its system prompt, with `You are a helpful software engineer assistant.` as the fallback. It suppresses every system-prompt runtime-context contribution for fresh sessions and mounts no context-compaction plugin. Its model-facing tools are exactly:
+[`minimal.patch.yml`](minimal.patch.yml) is an ordered overlay on the shipped SDK profile. It preserves the SDK application bundle but narrows model-visible behavior to:

 - owner-scoped persistent `bash`
 - `str_replace_editor` with `view`, `create`, `str_replace`, and `insert`

-It composes the local PTY, bare `fs-local` backend, danger-full-access policy for persistent Bash, and uncompressed JSONL persistence needed by the bundled runtime. Bash and absolute editor paths can modify any path available to the runtime process, so run this variant only against a disposable checkout or container. The persistent PTY requires a POSIX terminal environment and is not a Windows agent interface.
+The patch omits Harness identity and runtime-context messages, local instruction discovery, skills, compaction, plan/goal/task/web/subagent/workflow tools, and the profile's one-shot Bash. It inserts the local PTY and persistent Bash providers and sets the editor output limit to 16,000 characters.

-[`minimal.py`](minimal.py) runs the composition through the Python SDK and uses `DSH_MODEL` as its default model. The [Python SDK tutorial](../../docs/user/guide/python-sdk.md) covers installation, execution, workspace selection, and session identity; the [SDK reference](../../python/sdk/README.md) owns runtime lifecycle and result semantics.
+This variant is intentionally POSIX-only. Its persistent PTY and editor can modify any path available to the runtime process, so use a disposable checkout or container.
+
+## Add plugins
+
+Use the runtime wheel's `dsh` command against the same explicit home for persistent profile changes:
+
+```sh
+export DSH_HOME=/absolute/path/to/example-dsh-home
+dsh plugin --profile sdk add file:/absolute/path/to/my-plugin-bundle
+```
+
+The Python call can also pass additional absolute patch paths in `patches=(...)`; later files win. A selected profile must retain `@deepseek-ai/dsh-sdk-app` or another JSON-RPC server row. Complete standalone Cordis files in this directory remain test fixtures for lower-level composition coverage; they are not Python SDK launch interfaces.
+
+See the [Python SDK tutorial](../../docs/user/guide/python-sdk.md) and [SDK reference](../../python/sdk/README.md).
@@ -2,39 +2,41 @@

 [English](README.md) | 中文

-面向 Python SDK 内置 JSON-RPC 运行时的无人值守编码 agent（智能体）组合。它有意不加载终端 UI、控制台日志记录器、批准界面或用户交互工具，因为 stdout 属于 SDK 协议，轮次由 SDK 驱动。
+基于唯一应用启动器 `dsh --profile sdk` 的可运行 Python SDK 示例。Python 客户端负责 JSON-RPC stdio；profile 负责 agent 组合、持久化、权限与插件。

-面向模型的工具为：
+## 运行极简 agent

- `bash`，仅前台
- `read`、`write` 和 `edit`
- `subagent`，使用一个在进程内以前台方式运行的 spawn 提供方
- `todo_write`
+安装 `deepseek-harness-sdk`、导出模型凭据，然后提供隔离的 Harness home 与 workspace：

-周边运行时还加载 JSONL 会话持久化和自动上下文压缩（context compaction）。`maxTokensAsSuccess` 将受 token 上限限制的模型轮次保留为已接受的评估结果，同时保留其 `max-tokens` 原因。
+```sh
+export DEEPSEEK_API_KEY=sk-your-key-here
+python examples/python-sdk-agent/minimal.py \
+  --dsh-home /absolute/path/to/example-dsh-home \
+  --workspace /absolute/path/to/disposable-workspace \
+  --session-id example-001 \
+  "Inspect the repository and fix the failing tests."
+```

-## 运行时环境
+兼容代理使用 `DEEPSEEK_BASE_URL`，默认模型使用 `DSH_MODEL`，deployment persona 使用 `DSH_SYSTEM_PROMPT`。`--model` 与 `--profile` 会覆盖脚本默认值。所选 home 保存生成的 profile，并在 `sessions/` 下保存 Zstandard 会话日志；脚本绝不会隐式读取 `~/.dsh`。

-| 变量 | 用途 |
-|---|---|
-| `DEEPSEEK_API_KEY` | 传给 OpenAI 兼容宿主端点的凭据 |
-| `DEEPSEEK_BASE_URL` | `dsh-llm-deepseek` 使用的宿主端点 |
-| `DSH_CWD` | bash 和文件系统工具使用的 agent workspace |
-| `DSH_CONTEXT_WINDOW` | 极简变体中为 `DSH_MODEL` 目录项记录的上下文容量 |
-| `DSH_MAX_TOKENS_AS_SUCCESS` | `true`（默认）接受受 token 上限限制的结果；`false` 将其报告为错误 |
-| `DSH_MODEL` | `minimal.py` 使用的默认模型；`--model` 优先 |
-| `DSH_SESSION_ROOT` | JSONL 会话目录 |
-| `DSH_SYSTEM_PROMPT` | 由部署提供的编码人格 |
+[`minimal.patch.yml`](minimal.patch.yml) 是随附 SDK profile 上的有序 overlay。它保留 SDK 应用 bundle，但将模型可见行为收窄为：

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

-## 极简变体
+该 patch 会省略 Harness 身份与运行时上下文消息、本地指令发现、skill、compaction，以及 plan／goal／task／web／subagent／workflow 工具和 profile 的单次 Bash。它插入本地 PTY 与持久 Bash provider，并把 editor 输出上限设为 16,000 字符。

-[`minimal.cordis.yml`](minimal.cordis.yml) 是 Web `minimal` preset 的完整独立版本。`DSH_SYSTEM_PROMPT` 选择它的系统提示词，未设置时使用 `You are a helpful software engineer assistant.`。它为新建会话抑制每个 system-prompt runtime-context 贡献，且不挂载上下文压缩插件。面向模型的工具严格只有：
+此变体刻意只支持 POSIX。其持久 PTY 与 editor 可以修改运行时进程可访问的任何路径，因此只应在一次性 checkout 或容器中使用。

- 所有者作用域内持久化的 `bash`
- 提供 `view`、`create`、`str_replace` 与 `insert` 的 `str_replace_editor`
+## 添加插件

-它组合了内置运行时所需的本地 PTY、裸 `fs-local` 后端、供持久 Bash 使用的 danger-full-access 策略，以及未压缩的 JSONL 持久化。Bash 和编辑器绝对路径可以修改运行时进程有权访问的任何路径，因此只能针对可丢弃的 checkout 或容器运行该变体。持久 PTY 需要 POSIX 终端环境，因此不适用于 Windows agent 接口。
+对同一个显式 home 使用运行时 wheel 提供的 `dsh` 命令，以进行持久 profile 变更：

-[`minimal.py`](minimal.py)通过 Python SDK 运行该组合，并把 `DSH_MODEL` 作为默认模型。[Python SDK 教程](../../docs/user/guide/python-sdk.zh.md)介绍安装、运行、workspace 选择与 session 标识；[SDK 参考](../../python/sdk/README.zh.md)归属运行时生命周期与结果语义。
+```sh
+export DSH_HOME=/absolute/path/to/example-dsh-home
+dsh plugin --profile sdk add file:/absolute/path/to/my-plugin-bundle
+```
+
+Python 调用也可以在 `patches=(...)` 中传入更多绝对 patch 路径；后面的文件优先。所选 profile 必须保留 `@deepseek-ai/dsh-sdk-app` 或另一个 JSON-RPC server 配置项。本目录中的完整独立 Cordis 文件仍作为底层组合测试 fixture；它们不是 Python SDK 启动接口。
+
+另见 [Python SDK 教程](../../docs/user/guide/python-sdk.zh.md)与 [SDK 参考](../../python/sdk/README.zh.md)。
@@ -3,10 +3,9 @@
 # key or network; every other entry remains shared. The replay provider
 # catalog claims the `deepseek-official` provider so the SDK server's `initialize`
 # finds it owned and never mounts the real-adapter fallback. The SDK snapshot
-# suite passes this path explicitly through `DSH_CORDIS_CONFIG` (the
-# jsonrpc-demo bin performs no DSH_SNAPSHOT config swap of its own), and
-# `llm-replay` reads `DSH_SNAPSHOT_FILE` / `DSH_SNAPSHOT_CHILD_FILES` from the
-# harness. Stdout remains reserved for JSON-RPC frames.
+# suite selects this complete-config fixture explicitly, and `llm-replay`
+# reads `DSH_SNAPSHOT_FILE` / `DSH_SNAPSHOT_CHILD_FILES` from the harness.
+# It is not a Python launch interface. Stdout remains reserved for JSON-RPC.
 - id: base
  name: '@deepseek-ai/cordis-plugin-include'
  config:
@@ -1,5 +1,6 @@
-# Unattended coding-agent deployment for the bundled dsh-jsonrpc-agent runtime.
-# stdout is reserved for JSON-RPC; do not add a console logger or terminal UI.
+# Complete JSON-RPC composition fixture for lower-level Loader and SDK tests.
+# Python users launch `dsh --profile sdk` and apply patches instead.
+# Stdout is reserved for JSON-RPC; do not add a console logger or terminal UI.

 - id: sdk-jsonrpc-server
  name: '@deepseek-ai/dsh-sdk-jsonrpc-server'
@@ -1,7 +1,6 @@
-# Complete unattended minimal-agent composition for the Python SDK. The model
-# sees one deployment-selected system prompt and only the owner-scoped
-# persistent Bash and string-replace editor tools. Runtime-context injection and
-# context compaction are absent.
+# Complete minimal-agent composition fixture for lower-level snapshot tests.
+# Python users apply `minimal.patch.yml` to `dsh --profile sdk`. This fixture
+# retains the same two-tool behavior without defining a supported launch path.

 - id: sdk-jsonrpc-server
  name: '@deepseek-ai/dsh-sdk-jsonrpc-server'