Merge remote-tracking branch 'origin/master' into worktree/custom-provider-edit-parity-f8c160
This commit is contained in:
Yichen Jiang
@@ -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/config.md
|
||||
config.md: cd778065801ae58a46703ae3447f835f80abf062
|
||||
config.zh.md: 6f6d37bfe8f7ad29c154d65c1763279655006435
|
||||
config.md: 1d3ad5ce36d4b360ba5156b6be28a6caae4a23d4
|
||||
config.zh.md: 7f8bfaa77066f2976a5667e3ac402814a7afdf96
|
||||
|
||||
@@ -18,6 +18,10 @@ A minimal configuration is a list of plugin entries:
|
||||
```yaml
|
||||
- id: llm-deepseek
|
||||
name: '@deepseek-ai/dsh-llm-deepseek'
|
||||
config:
|
||||
apiKey: !!js process.env.DEEPSEEK_API_KEY
|
||||
models:
|
||||
- deepseek-v4-flash
|
||||
|
||||
- id: bash
|
||||
name: '@deepseek-ai/dsh-bash-local'
|
||||
@@ -47,16 +51,17 @@ Cordis starts sibling entries concurrently. A plugin declares required services
|
||||
|
||||
## CLI patch layers
|
||||
|
||||
`dsh --profile <name>` composes the profile's bundle patch layers (its manifest's `dsh.profile.bundles` list, in order) over an empty root, then the profile's own `~/.dsh/profiles/<name>/cordis.patch.yml`, then each `--patch <path>` overlay, then CLI-flag patches. Later layers win per row.
|
||||
`dsh --profile <name>` composes the profile's bundle patch layers (its manifest's `dsh.profile.bundles` list, in order) over an empty root, then the profile's own `~/.dsh/profiles/<name>/cordis.patch.yml`, the home-level `$DSH_HOME/cordis.patch.yml`, and each `--patch <path>` overlay. Later layers win per row. App flags are not another patch layer: an ordinary bundle plugin injects `cmdlineArgs` and provides parsed values as its own service, while rows that inject and retain a `!!js` read of that service give the invocation value precedence.
|
||||
|
||||
A patch replaces a row's entire `config` value; it does not deep-merge keys. For example, patching `llm-deepseek` with only `config: { thinking: disabled }` also removes that row's configured `apiKeyEnv` and `baseURL`, so restate every key the row must retain.
|
||||
A patch replaces a row's entire `config` value; it does not deep-merge keys. For example, patching `llm-deepseek` with only `config: { thinking: disabled }` also removes that row's configured `apiKey` and `baseURL`, so restate every key the row must retain.
|
||||
|
||||
## JavaScript values and environment variables
|
||||
|
||||
The Cordis loader evaluates runtime expressions tagged with `!!js` for non-secret runtime values. Bundled LLM adapters carry credential references such as `apiKeyEnv`; the value belongs in an environment layer or `$DSH_HOME/.credentials.yaml`, not Cordis configuration.
|
||||
The Cordis loader evaluates runtime expressions tagged with `!!js`. Keep API keys and other secrets in the gitignored `.env` file at the repository root, never in committed configuration.
|
||||
|
||||
```yaml
|
||||
config:
|
||||
apiKey: !!js process.env.DEEPSEEK_API_KEY
|
||||
cwd: !!js process.cwd()
|
||||
```
|
||||
|
||||
|
||||
@@ -18,6 +18,10 @@ Harness 使用 `cordis.yml` 描述 agent（智能体）加载哪些插件以及
|
||||
```yaml
|
||||
- id: llm-deepseek
|
||||
name: '@deepseek-ai/dsh-llm-deepseek'
|
||||
config:
|
||||
apiKey: !!js process.env.DEEPSEEK_API_KEY
|
||||
models:
|
||||
- deepseek-v4-flash
|
||||
|
||||
- id: bash
|
||||
name: '@deepseek-ai/dsh-bash-local'
|
||||
@@ -47,16 +51,17 @@ Cordis 会并发启动同级配置项。插件通过 `inject` 声明必需服务
|
||||
|
||||
## CLI 补丁层
|
||||
|
||||
`dsh --profile <name>` 按该 profile 的 manifest（元数据清单）中 `dsh.profile.bundles` 列表的顺序，在空根之上组合各组合包补丁层，随后依次应用该 profile 自己的 `~/.dsh/profiles/<name>/cordis.patch.yml`、home 级 `$DSH_HOME/cordis.patch.yml`、每个 `--patch <path>` overlay，最后是 CLI（命令行界面）标志补丁。同一行以较后的层为准。
|
||||
`dsh --profile <name>` 按该 profile 的 manifest（元数据清单）中 `dsh.profile.bundles` 列表的顺序，在空根之上组合各组合包补丁层，随后依次应用该 profile 自己的 `~/.dsh/profiles/<name>/cordis.patch.yml`、home 级的 `$DSH_HOME/cordis.patch.yml` 与每个 `--patch <path>` overlay。同一行以较后的层为准。应用 flag 并不是另一层 patch：组合包中的普通插件注入 `cmdlineArgs`，再把解析值作为自身服务提供；注入该服务并保留其 `!!js` 读取的行会让本次调用的取值优先。
|
||||
|
||||
补丁会替换目标行的整个 `config` 值，而不是深度合并各个键。例如，只用 `config: { thinking: disabled }` 修补 `llm-deepseek`，也会移除该行原有的 `apiKeyEnv` 与 `baseURL`；因此必须重新写出该行需要保留的全部键。
|
||||
补丁会替换目标行的整个 `config` 值，而不是深度合并各个键。例如，只用 `config: { thinking: disabled }` 修补 `llm-deepseek`，也会移除该行原有的 `apiKey` 与 `baseURL`；因此必须重新写出该行需要保留的全部键。
|
||||
|
||||
## JavaScript 值和环境变量
|
||||
|
||||
Cordis loader 会求值以 `!!js` 标记的运行时表达式，用于非机密的运行时值。仓库内置的 LLM（大语言模型）适配器携带 `apiKeyEnv` 等凭据引用；对应的值应放在环境层或 `$DSH_HOME/.credentials.yaml`，而不是 Cordis 配置中。
|
||||
Cordis loader 使用 `!!js` 标签读取运行时表达式。API key 等凭据应放在仓库根目录、已被 Git 忽略的 `.env` 中，不能提交到配置文件。
|
||||
|
||||
```yaml
|
||||
config:
|
||||
apiKey: !!js process.env.DEEPSEEK_API_KEY
|
||||
cwd: !!js process.cwd()
|
||||
```
|
||||
|
||||
@@ -64,4 +69,4 @@ config:
|
||||
|
||||
## 精确配置参考
|
||||
|
||||
每个插件当前支持的字段、类型和默认值见自动生成的[插件配置目录](../../config-catalog.md)。理解插件如何组合可继续阅读[架构说明](../../architecture.md)和[能力 seam](../../capability-seams.md)；要创建自己的配置，优先复制并修改[示例目录说明](../../../examples/README.md)中最接近的例子。
|
||||
每个插件当前支持的字段、类型和默认值见自动生成的[插件配置目录](../../config-catalog.md)。理解插件如何组合可继续阅读[架构说明](../../architecture.md)和[能力接口](../../capability-seams.md)；要创建自己的配置，优先复制并修改[示例目录说明](../../../examples/README.md)中最接近的例子。
|
||||
|
||||
@@ -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/providers.md
|
||||
providers.md: b5217ca7eaa00e7f31db4b3269ddb0d489fe3923
|
||||
providers.zh.md: a27adefdbb76c43d099982b0503a9adde139597f
|
||||
providers.md: 0e7ed11d1b09a8361d75b576a400978ac66d08a7
|
||||
providers.zh.md: 060bf3dc41b773e89cd0d78de921c3a20cfc6076
|
||||
|
||||
@@ -15,7 +15,7 @@ Adding a provider therefore rarely means editing `cordis.yml` — writing settin
|
||||
|
||||
## Configure from the web UI
|
||||
|
||||
Start `pnpm run dsh web` and open **Settings → Models**.
|
||||
Start `pnpm dsh web` and open **Settings → Models**.
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -15,7 +15,7 @@ Harness 出厂自带 DeepSeek，同时预装了一个通用的多提供方适配
|
||||
|
||||
## 在 Web 界面里配置
|
||||
|
||||
启动 `pnpm run dsh web`，打开**设置 → 模型**。
|
||||
启动 `pnpm dsh web`，打开**设置 → 模型**。
|
||||
|
||||
|
||||
|
||||
|
||||
6
docs/user/guide/python-sdk.i18n.yaml
Normal file
6
docs/user/guide/python-sdk.i18n.yaml
Normal file
@@ -0,0 +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.md
|
||||
python-sdk.md: 0713de6f96c110624d5f5a8f2ccf56dd4ce01096
|
||||
python-sdk.zh.md: f8fa877b407a43c643fda405e1059fb487182761
|
||||
130
docs/user/guide/python-sdk.md
Normal file
130
docs/user/guide/python-sdk.md
Normal file
@@ -0,0 +1,130 @@
|
||||
# Get started with the Python SDK
|
||||
|
||||
English | [中文](python-sdk.zh.md)
|
||||
|
||||
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
|
||||
|
||||
- Python 3.10 or newer
|
||||
- Linux x64, Linux arm64, or macOS arm64
|
||||
- A DeepSeek-compatible API endpoint and credential
|
||||
- An isolated workspace that the agent may modify
|
||||
|
||||
## Install the SDK
|
||||
|
||||
Choose either the public package or a source build. Both install the `deepseek-harness-sdk` distribution and expose the `deepseek_harness` Python module.
|
||||
|
||||
### Install from PyPI
|
||||
|
||||
Create a virtual environment and install the SDK with its same-version bundled runtime:
|
||||
|
||||
```sh
|
||||
python -m venv .venv
|
||||
. .venv/bin/activate
|
||||
python -m pip install deepseek-harness-sdk
|
||||
```
|
||||
|
||||
### Build from source
|
||||
|
||||
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.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"
|
||||
```
|
||||
|
||||
The runtime wheel contains the JSON-RPC executable and every plugin used by the complete [`minimal.cordis.yml`](../../../examples/jsonrpc-agent/minimal.cordis.yml), so neither installation path needs Node.js after installation.
|
||||
|
||||
## Run the checked-in example
|
||||
|
||||
Set the credential in the environment. Set `DEEPSEEK_BASE_URL` as well when the model is served by an OpenAI-compatible proxy rather than the default DeepSeek endpoint.
|
||||
|
||||
```sh
|
||||
export DEEPSEEK_API_KEY=sk-your-key-here
|
||||
# export DEEPSEEK_BASE_URL=http://127.0.0.1:8000/v1
|
||||
```
|
||||
|
||||
Run one task from the repository checkout:
|
||||
|
||||
```sh
|
||||
python examples/jsonrpc-agent/minimal.py \
|
||||
--workspace /absolute/path/to/workspace \
|
||||
--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 a JSONL session log containing the assembled model request and every tool call.
|
||||
|
||||
## Use the SDK in your own program
|
||||
|
||||
The example is a thin wrapper around this SDK call:
|
||||
|
||||
```python
|
||||
from pathlib import Path
|
||||
|
||||
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/sessions").resolve()
|
||||
|
||||
with DeepSeekHarness(
|
||||
provider="deepseek-official",
|
||||
model="deepseek-v4-flash",
|
||||
max_tokens=49_152,
|
||||
cwd=str(workspace),
|
||||
session_root=str(sessions),
|
||||
cordis=str(config),
|
||||
) as harness:
|
||||
result = harness.run(
|
||||
"Inspect the repository and fix the failing tests.",
|
||||
session_id="example-001",
|
||||
)
|
||||
|
||||
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.
|
||||
|
||||
## Understand the example configuration
|
||||
|
||||
| Surface | Fixed value |
|
||||
|---|---|
|
||||
| System prompt | `You are a helpful software engineer assistant.` |
|
||||
| Model-facing tools | Persistent `bash` and `str_replace_editor` only |
|
||||
| Bash timeout | 300 seconds |
|
||||
| Editor output limit | 16,000 characters |
|
||||
| Compaction | Trigger ratio `0.8`, retain `20,480` tokens, summary cap `8,192` tokens, one retry |
|
||||
| Session persistence | Uncompressed JSONL under `DSH_SESSION_ROOT` |
|
||||
|
||||
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.
|
||||
|
||||
## Choose workspace and session IDs
|
||||
|
||||
`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.
|
||||
|
||||
For the complete SDK lifecycle and result contract, see the [Python SDK reference](../../../python/sdk/README.md). For Cordis composition syntax, see [Configuration](./config.md).
|
||||
130
docs/user/guide/python-sdk.zh.md
Normal file
130
docs/user/guide/python-sdk.zh.md
Normal file
@@ -0,0 +1,130 @@
|
||||
# Python SDK 快速上手
|
||||
|
||||
[English](python-sdk.md) | 中文
|
||||
|
||||
本教程介绍如何安装 Python SDK、在不使用 Web UI 的情况下运行仓库内置 Cordis 组合，以及如何在自己的程序中调用同一套 API。教程使用精简且完整的 [`minimal.cordis.yml`](../../../examples/jsonrpc-agent/minimal.cordis.yml) 作为示例，其中固定了系统提示词、工具目录、持久 shell 行为和压缩（compaction）策略。
|
||||
|
||||
## 前置要求
|
||||
|
||||
- Python 3.10 或更高版本
|
||||
- Linux x64、Linux arm64 或 macOS arm64
|
||||
- DeepSeek 兼容的 API 端点与凭据
|
||||
- agent 可以修改的隔离 workspace
|
||||
|
||||
## 安装 SDK
|
||||
|
||||
可以选择安装公开包或从源码构建。两种方式都会安装 `deepseek-harness-sdk` 分发包，并提供 `deepseek_harness` Python 模块。
|
||||
|
||||
### 从 PyPI 安装
|
||||
|
||||
请创建虚拟环境，并安装 SDK 及其同版本内置运行时：
|
||||
|
||||
```sh
|
||||
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。
|
||||
|
||||
## 运行仓库内置示例
|
||||
|
||||
请在环境中设置凭据。如果模型不是由默认 DeepSeek 端点提供，而是通过 OpenAI 兼容代理提供，还需要设置 `DEEPSEEK_BASE_URL`。
|
||||
|
||||
```sh
|
||||
export DEEPSEEK_API_KEY=sk-your-key-here
|
||||
# export DEEPSEEK_BASE_URL=http://127.0.0.1:8000/v1
|
||||
```
|
||||
|
||||
从仓库 checkout 运行一个任务：
|
||||
|
||||
```sh
|
||||
python examples/jsonrpc-agent/minimal.py \
|
||||
--workspace /absolute/path/to/workspace \
|
||||
--session-root /absolute/path/to/sessions \
|
||||
--session-id example-001 \
|
||||
"Inspect the repository and fix the failing tests."
|
||||
```
|
||||
|
||||
脚本会打印 assistant 的最终回复。会话根目录会收到 JSONL 会话日志，其中包含组装后的模型请求与每次工具调用。
|
||||
|
||||
## 在自己的程序中使用 SDK
|
||||
|
||||
该示例是以下 SDK 调用的轻量包装层：
|
||||
|
||||
```python
|
||||
from pathlib import Path
|
||||
|
||||
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/sessions").resolve()
|
||||
|
||||
with DeepSeekHarness(
|
||||
provider="deepseek-official",
|
||||
model="deepseek-v4-flash",
|
||||
max_tokens=49_152,
|
||||
cwd=str(workspace),
|
||||
session_root=str(sessions),
|
||||
cordis=str(config),
|
||||
) as harness:
|
||||
result = harness.run(
|
||||
"Inspect the repository and fix the failing tests.",
|
||||
session_id="example-001",
|
||||
)
|
||||
|
||||
print(result.final_response)
|
||||
```
|
||||
|
||||
`DeepSeekHarness` 会延迟启动内置 JSON-RPC 运行时，并持续复用，直至退出上下文管理器。在多次调用中复用同一个 harness 和 session id，还会保留该会话拥有的 Bash 进程，包括其工作目录、已导出的变量与 shell 函数。
|
||||
|
||||
## 了解示例配置
|
||||
|
||||
| 方面 | 固定值 |
|
||||
|---|---|
|
||||
| 系统提示词 | `You are a helpful software engineer assistant.` |
|
||||
| 面向模型的工具 | 仅持久 `bash` 与 `str_replace_editor` |
|
||||
| Bash 超时 | 300 秒 |
|
||||
| 编辑器输出上限 | 16,000 个字符 |
|
||||
| 压缩 | 触发比例 `0.8`、保留 `20,480` 个 token、摘要上限 `8,192` 个 token、重试 1 次 |
|
||||
| 会话持久化 | `DSH_SESSION_ROOT` 下未压缩的 JSONL |
|
||||
|
||||
该配置省略了 harness 身份、workspace 提示词文本、skill（技能）、一次性 Bash、任务工具和其他所有面向模型的插件。文件系统策略事实记录为运行时用户上下文，而不会追加到系统提示词中。编辑器无条件要求绝对路径，因此配置中没有已经废弃的 `requireAbsolutePath` 选项。
|
||||
|
||||
## 选择 workspace 与 session id
|
||||
|
||||
`cwd` 用于选择 agent 可访问的 workspace，`session_root` 用于保存会话日志和状态。独立任务应使用新的 session id；只有下一次调用需要延续同一段对话和持久 shell 状态时，才复用原有 id。
|
||||
|
||||
该组合使用 `danger-full-access`。只能在可丢弃的 checkout 或容器内运行：Bash 与编辑器可以修改运行时进程有权访问的任何路径。持久 PTY 后端需要 POSIX 终端环境，因此该模式不适用于 Windows agent。
|
||||
|
||||
完整的 SDK 生命周期与结果约定见 [Python SDK 参考](../../../python/sdk/README.md)。Cordis 组合语法见[配置](./config.md)。
|
||||
@@ -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: ce196641f205324334533c025b4ac1dc791f857d
|
||||
quickstart.zh.md: 3a5d6d0748ec0c7ec83c74570d0fad1e8d66a97c
|
||||
quickstart.md: e93e5a430f0cb345728581cd6fa3175ffd20b7d1
|
||||
quickstart.zh.md: 69cde830bb802ef19cc1204685395b957a0e02e3
|
||||
|
||||
@@ -19,10 +19,9 @@ pnpm -v
|
||||
## Step 1: install and configure the API key
|
||||
|
||||
```sh
|
||||
git clone https://github.com/deepseek-ai/deepseek-harness-sdk.git
|
||||
git clone https://github.com/deepseek-ai/deepseek-harness.git
|
||||
cd deepseek-harness
|
||||
pnpm install
|
||||
pnpm run build
|
||||
```
|
||||
|
||||
Create the gitignored repository-root `.env`:
|
||||
@@ -36,27 +35,28 @@ DEEPSEEK_API_KEY=sk-your-key-here
|
||||
Run a non-interactive task and print its final answer:
|
||||
|
||||
```sh
|
||||
pnpm run dsh run "summarize the architecture of this workspace"
|
||||
pnpm dsh --profile headless "summarize the architecture of this workspace"
|
||||
```
|
||||
|
||||
`dsh run` creates and persists a fresh session, prints the final assistant answer, and exits. It starts no Web server or listening port, and a successful run leaves stderr empty.
|
||||
`dsh --profile headless` creates and persists a fresh session, prints the final assistant answer, and exits. It starts no Web server or listening port, and a successful run leaves stderr empty.
|
||||
|
||||
## Step 3: use the Web UI
|
||||
|
||||
Start the browser interface:
|
||||
|
||||
```sh
|
||||
pnpm run dsh web
|
||||
pnpm dsh web
|
||||
```
|
||||
|
||||
Open `http://127.0.0.1:3080`. The agent can read and write files, run commands, delegate subtasks, and track a plan. Try: `Create hello.js in the current directory, print "Hello from Harness!", and run it`.
|
||||
|
||||
## What happened
|
||||
|
||||
`dsh run` boots the `headless` profile: [`dsh-base`](../../../packages/bundle/base/cordis.patch.yml) and [`dsh-headless`](../../../packages/bundle/headless/cordis.patch.yml) compose over an empty root, then the runner drives the core Agent and Session services directly. `dsh web` instead composes `dsh-base` with [`dsh-web-app`](../../../packages/bundle/web-app/cordis.patch.yml), which owns the Host, HTTP, and browser layers. Both read the same default DeepSeek model route from `dsh-base`.
|
||||
`dsh --profile headless` boots the `headless` profile: [`dsh-base`](../../../packages/bundle/base/cordis.patch.yml) and [`dsh-headless`](../../../packages/bundle/headless/cordis.patch.yml) compose over an empty root, then the runner drives the core Agent and Session services directly. `dsh web` instead composes `dsh-base` with [`dsh-web-app`](../../../packages/bundle/web-app/cordis.patch.yml), which owns the Host, HTTP, and browser layers. Both read the same default DeepSeek model route from `dsh-base`.
|
||||
|
||||
## Next steps
|
||||
|
||||
- [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
|
||||
|
||||
@@ -19,10 +19,9 @@ pnpm -v
|
||||
## 第一步：安装并配置 API 密钥
|
||||
|
||||
```sh
|
||||
git clone https://github.com/deepseek-ai/deepseek-harness-sdk.git
|
||||
git clone https://github.com/deepseek-ai/deepseek-harness.git
|
||||
cd deepseek-harness
|
||||
pnpm install
|
||||
pnpm run build
|
||||
```
|
||||
|
||||
在仓库根目录创建已被 Git 忽略的 `.env`：
|
||||
@@ -36,27 +35,28 @@ DEEPSEEK_API_KEY=sk-your-key-here
|
||||
运行一个非交互式任务并打印最终回答：
|
||||
|
||||
```sh
|
||||
pnpm run dsh run "summarize the architecture of this workspace"
|
||||
pnpm dsh --profile headless "summarize the architecture of this workspace"
|
||||
```
|
||||
|
||||
`dsh run` 创建并持久化一个新会话，打印最终助手回答，然后退出。它不会启动 Web 服务器或监听端口；成功运行时 stderr 为空。
|
||||
`dsh --profile headless` 创建并持久化一个新会话，打印最终助手回答，然后退出。它不会启动 Web 服务器或监听端口；成功运行时 stderr 为空。
|
||||
|
||||
## 第三步：使用 Web UI
|
||||
|
||||
启动浏览器界面：
|
||||
|
||||
```sh
|
||||
pnpm run dsh web
|
||||
pnpm dsh web
|
||||
```
|
||||
|
||||
打开 `http://127.0.0.1:3080`。agent 可以读写文件、运行命令、分配子任务和跟踪计划。可以尝试：`Create hello.js in the current directory, print "Hello from Harness!", and run it`。
|
||||
|
||||
## 运行原理
|
||||
|
||||
`dsh run` 启动 `headless` profile：[`dsh-base`](../../../packages/bundle/base/cordis.patch.yml) 和 [`dsh-headless`](../../../packages/bundle/headless/cordis.patch.yml) 在空根之上组合，随后 runner 直接驱动 core Agent 与 Session 服务。`dsh web` 则由 `dsh-base` 与 [`dsh-web-app`](../../../packages/bundle/web-app/cordis.patch.yml) 组合，后者拥有 Host、HTTP 与浏览器层。二者都从 `dsh-base` 读取同一个默认 DeepSeek 模型路由。
|
||||
`dsh --profile headless` 启动 `headless` profile：[`dsh-base`](../../../packages/bundle/base/cordis.patch.yml) 和 [`dsh-headless`](../../../packages/bundle/headless/cordis.patch.yml) 在空根之上组合，随后 runner 直接驱动 core Agent 与 Session 服务。`dsh web` 则由 `dsh-base` 与 [`dsh-web-app`](../../../packages/bundle/web-app/cordis.patch.yml) 组合，后者拥有 Host、HTTP 与浏览器层。二者都从 `dsh-base` 读取同一个默认 DeepSeek 模型路由。
|
||||
|
||||
## 下一步
|
||||
|
||||
- [Python SDK 快速上手](./python-sdk.md) — 安装 SDK，并在不使用 Web UI 的情况下运行完整 Cordis 配置
|
||||
- [配置模型](./providers.md) — 接入 DeepSeek 之外的提供方与自定义网关
|
||||
- [配置文件](./config.md) — 了解 `cordis.yml` 的格式
|
||||
- [开发插件](../develop/basic/) — 编写自己的工具或后端
|
||||
|
||||
Reference in New Issue
Block a user