From 04fe477e7e632993c3b5ca132bf92718600d8a72 Mon Sep 17 00:00:00 2001 From: Turtle Date: Wed, 12 Aug 2026 10:59:06 +0800 Subject: [PATCH] docs: make Web UI the primary onboarding path --- ...2026-07-04-doc-tiers-and-budgets.i18n.yaml | 4 +- .../2026-07-04-doc-tiers-and-budgets.md | 3 + .../2026-07-04-doc-tiers-and-budgets.zh.md | 3 + BENCHMARK.md | 2 +- README.i18n.yaml | 4 +- README.md | 71 +++------ README.zh.md | 71 +++------ docs/cordis-tutorial/index.i18n.yaml | 4 +- docs/cordis-tutorial/index.md | 2 +- docs/cordis-tutorial/index.zh.md | 2 +- docs/user/develop/basic/index.i18n.yaml | 4 +- docs/user/develop/basic/index.md | 2 +- docs/user/develop/basic/index.zh.md | 2 +- docs/user/guide/config.i18n.yaml | 6 - docs/user/guide/config.md | 72 --------- docs/user/guide/config.zh.md | 72 --------- docs/user/guide/index.i18n.yaml | 4 +- docs/user/guide/index.md | 54 ++----- docs/user/guide/index.zh.md | 54 ++----- docs/user/guide/providers.i18n.yaml | 4 +- docs/user/guide/providers.md | 149 +++--------------- docs/user/guide/providers.zh.md | 149 +++--------------- docs/user/guide/python-sdk.i18n.yaml | 4 +- docs/user/guide/python-sdk.md | 56 ++----- docs/user/guide/python-sdk.zh.md | 56 ++----- docs/user/guide/quickstart.i18n.yaml | 6 - docs/user/guide/quickstart.md | 62 -------- docs/user/guide/quickstart.zh.md | 62 -------- examples/jsonrpc-agent/README.i18n.yaml | 4 +- examples/jsonrpc-agent/README.md | 4 +- examples/jsonrpc-agent/README.zh.md | 4 +- python/sdk/README.i18n.yaml | 4 +- python/sdk/README.md | 2 +- python/sdk/README.zh.md | 2 +- .../request-response.expected.json | 4 +- website/docs.ts | 26 +-- 36 files changed, 190 insertions(+), 844 deletions(-) delete mode 100644 docs/user/guide/config.i18n.yaml delete mode 100644 docs/user/guide/config.md delete mode 100644 docs/user/guide/config.zh.md delete mode 100644 docs/user/guide/quickstart.i18n.yaml delete mode 100644 docs/user/guide/quickstart.md delete mode 100644 docs/user/guide/quickstart.zh.md diff --git a/.agents/notes/implemented/process/2026-07-04-doc-tiers-and-budgets.i18n.yaml b/.agents/notes/implemented/process/2026-07-04-doc-tiers-and-budgets.i18n.yaml index ba3b6a970d..7b251c2470 100644 --- a/.agents/notes/implemented/process/2026-07-04-doc-tiers-and-budgets.i18n.yaml +++ b/.agents/notes/implemented/process/2026-07-04-doc-tiers-and-budgets.i18n.yaml @@ -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 .agents/notes/implemented/process/2026-07-04-doc-tiers-and-budgets.md -2026-07-04-doc-tiers-and-budgets.md: e7b3421d09a1ae5ab9a9373e8040832c1b0d4b97 -2026-07-04-doc-tiers-and-budgets.zh.md: 3bc04ae73a4d8c9c005e154a236772fc1845389e +2026-07-04-doc-tiers-and-budgets.md: 3f263864b9b6ee9479d1133b908617f10073dd66 +2026-07-04-doc-tiers-and-budgets.zh.md: 63b0b2945e1ff3e3fdf6af3cddb80cf44cf448ee diff --git a/.agents/notes/implemented/process/2026-07-04-doc-tiers-and-budgets.md b/.agents/notes/implemented/process/2026-07-04-doc-tiers-and-budgets.md index e7b3421d09..3f263864b9 100644 --- a/.agents/notes/implemented/process/2026-07-04-doc-tiers-and-budgets.md +++ b/.agents/notes/implemented/process/2026-07-04-doc-tiers-and-budgets.md @@ -12,6 +12,7 @@ Standing docs accumulated repeated rules, retold incidents, duplicated package m - **Structure follows the documentation tree.** [docs/AGENTS.md](../../../../docs/AGENTS.md) is the documentation standard: a document owns detail about its subject, summarizes only the purpose, responsibility, and high-level behavior of direct children, and links to deeper owners. [Agent Notes](../../README.md) remain outside this structural contract. Every human-facing document is a tutorial with an ordered outcome or a reference with an explicit lookup scope; a [postmortem](../../../../docs/postmortem/README.md) is an incident-scoped reference whose chronology records evidence. Tutorials introduce concepts in prerequisite order for the reader's starting knowledge. - **A tier taxonomy with one home per fact.** The standard assigns every Markdown tier one job, forbids restating a fact outside its home tier, and carries the slop checklist used when writing or reviewing any doc. +- **One product onboarding path.** The root README owns the recommended package-run path, the source-run alternative, and compact `dsh plugin --profile` usage. The published user guide starts with tasks inside the running Web UI, then links to distinct tutorials or reference owners for other interfaces, plugin development, and advanced configuration instead of repeating Web startup. - **A narrow, hard budget gate.** [scripts/verify-doc-budgets.ts](../../../../scripts/verify-doc-budgets.ts) joins `doc-sync`: every doc listed in [scripts/doc-budgets.manifest.json](../../../../scripts/doc-budgets.manifest.json) must stay under its word ceiling (`wc -w` semantics, whole file), and a budgeted file that is missing fails the gate so a rename cannot silently orphan its budget. Scope is deliberately only the accretion-prone standing docs — the root and subtree `AGENTS.md` files, `architecture.md`, `packages/README.md`, and the standing policy docs they evict content into (`docs/testing.md`, `docs/defensive-patterns.md`). Reference docs, Agent Notes, and package READMEs are unbudgeted: length is legitimate there when every row is a fact, and review plus the slop checklist govern them. - **Ceilings are an enforcement frontier that ratchets.** A doc at or below its target keeps at least 5% headroom as its ceiling ratchets down; a doc above target keeps a frozen ceiling that prevents growth until it reaches the target (root `AGENTS.md` ≤ 1,600 words; `architecture.md` ≤ 1,800; subtree `AGENTS.md` ≤ 600 except `packages/AGENTS.md` ≤ 650 and `docs/AGENTS.md` ≤ 1,250; `packages/README.md` ≤ 600). When the gate goes red, relocate or condense; raise a ceiling only with explicit PR justification. - **A thin workflow skill, contracts in docs.** [.agents/skills/dsh-doc-standards](../../../skills/dsh-doc-standards/SKILL.md) carries the placement/audit/red-gate workflow and defers to the standard as its source of truth, the same split as [dsh-translate-docs](../../../skills/dsh-translate-docs/SKILL.md) over the i18n contract. @@ -20,11 +21,13 @@ Standing docs accumulated repeated rules, retold incidents, duplicated package m - **Skill and review discipline without a gate** — rejected: the accretion above happened while the current-state rule and reviewer attention already existed; a prose rule with no mechanical backstop demonstrably does not hold here, and this repo's own [quality-gates stance](2026-06-11-quality-gates.md) says invariants worth keeping are worth encoding. - **A broad gate over every doc tier** — rejected: a blanket ceiling punishes exactly the right kind of long doc (a feature matrix or type catalog where every row is a fact) and generates per-file override churn that trains contributors to rubber-stamp raises. +- **Independent onboarding tutorials for each documentation entry point** — rejected: duplicated setup steps drift in command order, first outcome, and product identity. A short README path followed by task-focused guides keeps the transition explicit without maintaining competing tutorials. - **Housing the standard inside the skill** — rejected: contracts live in docs and workflows in skills; a standard packed into SKILL.md is invisible to an agent that edits docs without invoking the skill, and `docs/AGENTS.md` already loads as subtree instructions for anyone working under `docs/`. ## Consequences - Adding to a budgeted doc requires displacement: relocate the addition to its taxonomy home with a pointer, or condense existing prose to pay for it. Growth without pruning fails CI. - Structural review starts with ownership and document form before sentence-level editing, so lower-level detail moves to its owner instead of being polished in the wrong place. +- Readers reach a running Web UI before encountering headless execution, SDK embedding, custom profiles, or direct settings files; those interfaces remain available from their reference owners. - Budgeted docs that remain above target cannot grow; reaching the target restores the 5% working headroom. - Word count is a crude proxy accepted deliberately: it cannot judge quality, but it forces the relocation decision at exactly the moment content is being added, which is when the author has the context to place it correctly. diff --git a/.agents/notes/implemented/process/2026-07-04-doc-tiers-and-budgets.zh.md b/.agents/notes/implemented/process/2026-07-04-doc-tiers-and-budgets.zh.md index 3bc04ae73a..63b0b2945e 100644 --- a/.agents/notes/implemented/process/2026-07-04-doc-tiers-and-budgets.zh.md +++ b/.agents/notes/implemented/process/2026-07-04-doc-tiers-and-budgets.zh.md @@ -12,6 +12,7 @@ Status: implemented - **结构遵循文档树。**[docs/AGENTS.md](../../../../docs/AGENTS.md) 是文档标准：文档负责承载其主题的详细内容，仅概述直接子项的目的、职责和高层行为，并链接到更深层内容的归属文档。[Agent Note](../../README.md) 仍不受这一结构约定约束。每份面向人的文档要么是按顺序引导读者达成结果的教程（tutorial），要么是查阅范围明确的参考文档（reference）；[事故复盘（postmortem）](../../../../docs/postmortem/README.md) 是范围限定于单起事故的参考文档，其时间线记录证据。教程结合读者的起始知识，按前置依赖顺序介绍概念。 - **每项事实只归属一处的层级分类。**文档标准为每种 Markdown 层级分配单一职责，禁止在事实归属层级之外重复陈述，并包含编写或评审任何文档时使用的赘余检查清单。 +- **单一产品入门路径。**根 README 负责推荐的包运行路径、从源码运行的备选路径和简要的 `dsh plugin --profile` 用法。已发布的用户指南从运行中的 Web UI 内部任务开始，再链接到其他界面的独立教程或插件开发与进阶配置的参考文档归属处，而不会重复介绍 Web 启动步骤。 - **范围窄且严格的预算门禁。**[scripts/verify-doc-budgets.ts](../../../../scripts/verify-doc-budgets.ts) 接入 `doc-sync`：[scripts/doc-budgets.manifest.json](../../../../scripts/doc-budgets.manifest.json) 列出的每份文档都必须低于其词数上限（采用 `wc -w` 语义，统计整个文件）；预算内文件缺失也会使门禁失败，使重命名无法悄然遗落其预算。范围刻意只涵盖容易膨胀的常设文档——根目录和子树中的 `AGENTS.md` 文件、`architecture.md`、`packages/README.md`，以及它们将内容移入的常设策略文档（`docs/testing.md`、`docs/defensive-patterns.md`）。参考文档、Agent Note 和包 README 不设预算：只要每一行都是事实，长度在这些位置就是合理的；评审和赘余检查清单负责约束它们。 - **上限是只进不退的执行红线。** 达到或低于目标的文档在上限逐步下调时保留至少 5% 的余量；高于目标的文档则维持冻结的上限，在达到目标之前不得增长（根 `AGENTS.md` ≤ 1,600 词；`architecture.md` ≤ 1,800；子树 `AGENTS.md` ≤ 600，但 `packages/AGENTS.md` ≤ 650、`docs/AGENTS.md` ≤ 1,250；`packages/README.md` ≤ 600）。门禁变红时，迁移或压缩内容；只有在 PR（Pull Request）描述中给出明确理由时才提高上限。 - **精简的工作流 skill（技能），约定归文档。**[.agents/skills/dsh-doc-standards](../../../skills/dsh-doc-standards/SKILL.md) 承载文档放置、审计和门禁失败处理工作流，并以文档标准为真源，与 [dsh-translate-docs](../../../skills/dsh-translate-docs/SKILL.md) 和 i18n 约定之间的分工相同。 @@ -20,11 +21,13 @@ Status: implemented - **仅靠 skill 和评审纪律，不设门禁**：否决。上述膨胀正是在现行规则和评审注意力已经存在的情况下发生的；一条没有自动化保障的行文规则在此处已被证明无法维持，而本仓库自身的[质量门禁立场](2026-06-11-quality-gates.md)认为值得保持的不变式就值得编码。 - **对所有文档层级全面设限**：否决。一刀切的上限恰好惩罚了那些正当的长文档（如功能矩阵或类型目录，每一行都是事实），并产生逐文件的例外变更，训练贡献者机械地批准提限。 +- **为每个文档入口维护独立入门教程**：否决。重复的设置步骤会在命令顺序、首个结果和产品定位上产生分歧。简短的 README 路径接上面向任务的指南，可明确衔接两者，且不需要维护相互竞争的教程。 - **将标准放在 skill 内部**：否决。约定归文档，工作流归 skill；如果标准被塞进 SKILL.md，那些不调用该 skill 而直接编辑文档的 agent（智能体）就看不到它，而 `docs/AGENTS.md` 已经作为子树指令被任何在 `docs/` 下工作的人加载。 ## 后果 - 向受预算约束的文档添加内容需要腾挪空间：将新增内容迁移到其分类体系归属地并留下链接，或压缩现有行文来腾出空间。只增不减会导致 CI 失败。 - 结构评审先检查归属关系和文档形式，再进行句子层面的编辑，使较低层级的细节迁移到其归属文档，而不是在错误的位置加以润色。 +- 读者会先进入可运行的 Web UI，再遇到 headless 执行、SDK 嵌入、自定义 profile 或直接 settings 文件；这些入口仍可从各自的参考文档归属处访问。 - 仍高于目标的受预算约束文档不得增长；达到目标后，将恢复 5% 的工作余量。 - 词数是一个粗糙的代理指标，这是有意接受的：它无法判断质量，但它在内容被添加的那一刻强制触发迁移决策，而那正是作者拥有足够上下文来正确放置内容的时刻。 diff --git a/BENCHMARK.md b/BENCHMARK.md index 6e8f466a1f..d5e9dc7831 100644 --- a/BENCHMARK.md +++ b/BENCHMARK.md @@ -1,3 +1,3 @@ # Running benchmarks -To run benchmark tasks with the minimal agent composition, follow [Get started with the Python SDK](docs/user/guide/python-sdk.md). The guide covers installation, running [`minimal.cordis.yml`](examples/jsonrpc-agent/minimal.cordis.yml), and isolating workspaces and session IDs between tasks. +Follow [Get started with the Python SDK](docs/user/guide/python-sdk.md) to install the SDK and run the `jsonrpc-agent` minimal variant. Use separate workspaces and session IDs for independent benchmark tasks. diff --git a/README.i18n.yaml b/README.i18n.yaml index a7f0956a0a..4d38f6e19c 100644 --- a/README.i18n.yaml +++ b/README.i18n.yaml @@ -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 README.md -README.md: 9c19dfec19cba6f1364e4f9d5734af49675d68c2 -README.zh.md: 31d83ede854e9f0dfbbba1f8ce1094d043f6d829 +README.md: 690cde099d93ea2a371b31f441030153b1aca973 +README.zh.md: 2a8046011da7c1970d1210f291973db36e379665 diff --git a/README.md b/README.md index 9c19dfec19..690cde099d 100644 --- a/README.md +++ b/README.md @@ -12,64 +12,43 @@ DeepSeek Harness is under internal testing. Features and interfaces may change. The internal build uploads all Session Logs by default to help diagnose reported problems. Set `DSH_TELEMETRY_DISABLED=1` to disable telemetry. Send feedback through the internal WeChat group. -## Run from source +## Run -Clone this repo, complete the [dependency and API-key setup](docs/user/guide/quickstart.md#step-1-install-and-configure-the-api-key), then run: +Install Node.js ^22.19 or >= 24 and pnpm 11, then run the published package: ```sh +npx @deepseek-ai/dsh web +``` + +The command initializes the Web profile and prints the Web UI URL, which is `http://127.0.0.1:3080` by default. Open it, add a DeepSeek API key under **Settings → Models**, then start a session. The invoking directory is the default workspace; try `Summarize this repository and identify its main packages.` + +Continue with the [Web UI guide](docs/user/guide/). + +### Run from source + +To run a repository checkout instead: + +```sh +git clone https://github.com/deepseek-harness/deepseek-harness.git +cd deepseek-harness +pnpm install pnpm dsh web ``` -## Use DeepSeek Harness +The last command builds the repository and opens the same Web UI path. -### Web UI +## Profiles and plugins -Start the recommended local interface from the repository root: +A profile is an ordered list of plugin bundles. The shipped `web` profile powers `dsh web`. Manage a profile with `dsh plugin --profile `, which forwards the remaining arguments to pnpm in that profile's directory: ```sh -pnpm dsh web +npx -p @deepseek-ai/dsh dsh plugin --profile web add +npx -p @deepseek-ai/dsh dsh plugin --profile web remove ``` -The command builds the repository before starting the Web UI, which is served at `http://127.0.0.1:3080` by default. +`add`, `remove`, `update`, `why`, and other pnpm commands work unchanged. The command initializes a missing profile before changing its packages and updates its bundle list from installed packages that declare `dsh.bundle`. See the [CLI reference](apps/cli/reference/README.md#plugin-management) for the exact behavior. -### Profiles - -The source CLI boots profiles — ordered stacks of plugin-bundle patch layers under your own overrides in `$DSH_HOME/profiles/`: - -```sh -pnpm dsh --profile web # the browser UI -pnpm dsh plugin --profile tui add # install a plugin into a custom profile -pnpm dsh --profile tui # boot it -``` - -The [CLI reference](apps/cli/README.md#profiles) describes profile layout, layer semantics, and config dump commands. - -### Headless - -Run one task, print the final answer, and exit: - -```sh -pnpm dsh --profile headless "summarize this workspace" -``` - -### Automation and SDKs - -From a source checkout with `DEEPSEEK_API_KEY` in the environment or its root `.env`, start the ACP automation server: - -```sh -pnpm run demo:acp -``` - -The [Python SDK](python/README.md) drives a bundled JSON-RPC runtime. The [examples](examples/README.md) cover the runnable headless, ACP, JSON-RPC, Code Mode, and self-referential compositions. - -## Why DeepSeek Harness - -Built-in capabilities cover file reading, editing, and search; shell and persistent PTY execution; reusable skills; task tracking, goals, plans, todos, and background tasks; subagents and workflows; sandboxing and approvals; settings and credentials; persistent, resumable, forkable, and queryable sessions; LSP and web access; context compaction; and telemetry. Each composition selects the subset appropriate to its surface. The Web UI includes Plan Mode. - -- **Everything is a plugin.** Models, tools, policies, storage, context management, and interfaces are composable [Cordis plugins](docs/user/develop/basic/index.md), so deployments can extend or replace behavior without forking the agent loop. See the [architecture](docs/architecture.md) for the underlying design. -- **Runs are reconstructable.** Anything visible to the model is logged in the authoritative session stream; persistence, resume/fork/query, replay, telemetry, and UIs derive from the same events. See the [session-log architecture](docs/architecture.md#session-log). -- **Code Mode (opt-in).** It exposes a `run_code` tool and a generated TypeScript SDK; only program output re-enters model context. See [Code Mode](packages/core/tools/README.md#code-mode). -- **Self-referential Cordis tools are opt-in.** They let the agent inspect its live runtime and mount or unmount plugins while it runs. See the [Cordis tools](packages/self-modification/tool-cordis/README.md). +The [CLI reference](apps/cli/README.md) covers headless execution and custom profiles. The [Python SDK](python/README.md) and [examples](examples/README.md) cover programmatic and custom compositions. ## Community @@ -81,8 +60,6 @@ Start with the [development guide](docs/development.md) and read the [architectu For agents, follow [AGENTS.md](AGENTS.md). -DeepSeek Harness is currently in internal testing. - ## License [BSD 3-Clause](LICENSE) diff --git a/README.zh.md b/README.zh.md index 31d83ede85..2a8046011d 100644 --- a/README.zh.md +++ b/README.zh.md @@ -12,64 +12,43 @@ DeepSeek Harness 正处于内部测试阶段，功能和接口可能发生变化 为帮助诊断上报的问题，内测版本默认上传所有会话日志。设置 `DSH_TELEMETRY_DISABLED=1` 可关闭遥测。请通过内部企业微信群反馈问题和建议。 -## 从源码运行 +## 运行 -克隆本仓库，完成[依赖安装和 API 密钥配置](docs/user/guide/quickstart.md#step-1-install-and-configure-the-api-key)，然后运行： +安装 Node.js ^22.19 或 >= 24 和 pnpm 11，然后运行已发布的包： ```sh +npx @deepseek-ai/dsh web +``` + +该命令会初始化 Web profile 并打印 Web UI 地址，默认地址为 `http://127.0.0.1:3080`。打开该地址，在**设置 → 模型**中添加 DeepSeek API 密钥，然后启动一个会话。调用目录是默认工作区；你可以尝试输入 `Summarize this repository and identify its main packages.`。 + +下一步请阅读 [Web UI 指南](docs/user/guide/)。 + +### 从源码运行 + +如需改为运行仓库 checkout： + +```sh +git clone https://github.com/deepseek-harness/deepseek-harness.git +cd deepseek-harness +pnpm install pnpm dsh web ``` -## 使用 DeepSeek Harness +最后一条命令会构建仓库，并进入相同的 Web UI 路径。 -### Web UI +## Profile 与插件 -请从仓库根目录启动推荐的本地界面： +profile 是按顺序排列的插件 bundle 列表。随附的 `web` profile 为 `dsh web` 提供功能。使用 `dsh plugin --profile ` 管理 profile；该命令会在对应 profile 目录中将剩余参数转发给 pnpm： ```sh -pnpm dsh web +npx -p @deepseek-ai/dsh dsh plugin --profile web add +npx -p @deepseek-ai/dsh dsh plugin --profile web remove ``` -该命令会先构建仓库，再启动 Web UI。Web UI 默认通过 `http://127.0.0.1:3080` 提供服务。 +`add`、`remove`、`update`、`why` 等 pnpm 命令均可直接使用。该命令会先初始化不存在的 profile，再修改其中的包，并根据声明了 `dsh.bundle` 的已安装包更新 bundle 列表。准确行为见 [CLI 参考](apps/cli/reference/README.md#plugin-management)。 -### Profile - -源码 CLI（命令行界面）会启动 profile：按序叠放的插件组合包 patch 层，之上再叠加你在 `$DSH_HOME/profiles/` 中的自有覆盖层： - -```sh -pnpm dsh --profile web # the browser UI -pnpm dsh plugin --profile tui add # install a plugin into a custom profile -pnpm dsh --profile tui # boot it -``` - -profile 布局、层语义与配置输出命令详见 [CLI（命令行界面）参考](apps/cli/README.md#profiles)。 - -### Headless - -运行一项任务，打印最终答案后退出： - -```sh -pnpm dsh --profile headless "summarize this workspace" -``` - -### 自动化与 SDK - -在源码检出中通过环境变量或根目录 `.env` 设置 `DEEPSEEK_API_KEY`，然后启动 ACP（Agent Client Protocol）自动化服务器： - -```sh -pnpm run demo:acp -``` - -[Python SDK](python/README.md) 驱动随附的 JSON-RPC 运行时。[示例](examples/README.md)涵盖可运行的 headless、ACP、JSON-RPC、Code Mode 和自指组合。 - -## 为什么选择 DeepSeek Harness - -内置功能涵盖文件读取、编辑与搜索、shell 和持久 PTY 执行、可复用 skill（技能）、任务跟踪、目标、计划、待办事项与后台任务、subagent 与工作流、沙箱与审批、设置与凭据、可持久化、恢复、fork 与查询的会话、LSP 与 Web 访问、上下文压缩（context compaction），以及遥测。每个组合只选用适合其使用方式的能力子集。Web UI 包含 Plan Mode。 - -- **一切皆插件。** 模型、工具、策略、存储、上下文管理和界面均为可组合的 [Cordis 插件](docs/user/develop/basic/index.md)，部署方无需 fork agent loop（智能体循环）即可扩展或替换行为。底层设计见[架构文档](docs/architecture.md)。 -- **运行可重建。** 凡是模型可见的内容，都会记录在权威会话流中；持久化、恢复／fork／查询、回放、遥测和 UI 均从同一组事件派生。参见[会话日志架构](docs/architecture.md#session-log)。 -- **Code Mode（需显式启用）。** 它会提供 `run_code` 工具和生成的 TypeScript SDK，只有程序输出会重新进入模型上下文。参见 [Code Mode](packages/core/tools/README.md#code-mode)。 -- **自指 Cordis 工具需显式启用。** 这些工具可让 agent 检查自身的实时运行时，并在运行中挂载或卸载插件。参见 [Cordis 工具](packages/self-modification/tool-cordis/README.md)。 +[CLI（命令行界面）参考](apps/cli/README.md)介绍 headless 执行与自定义 profile。[Python SDK](python/README.md) 和[示例](examples/README.md)介绍程序化组合与自定义组合。 ## 社区 @@ -85,8 +64,6 @@ pnpm run demo:acp 面向 agent：遵循 [AGENTS.md](AGENTS.md)。 -DeepSeek Harness 目前处于内测阶段。 - ## 许可证 [BSD 3-Clause](LICENSE) diff --git a/docs/cordis-tutorial/index.i18n.yaml b/docs/cordis-tutorial/index.i18n.yaml index 06857ab177..1ce61a593a 100644 --- a/docs/cordis-tutorial/index.i18n.yaml +++ b/docs/cordis-tutorial/index.i18n.yaml @@ -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/cordis-tutorial/index.md -index.md: fb700344e6d07d3864655009d2edac15ee9eede8 -index.zh.md: a68e931d81e745164d8f9a5dc7ec9aec4cd0e590 +index.md: a10a0f93fde4f710af2ab14f74b854ee07d7c03f +index.zh.md: fb2c4f0959eab8c7a072c44207943c31b0bed8ea diff --git a/docs/cordis-tutorial/index.md b/docs/cordis-tutorial/index.md index fb700344e6..a10a0f93fd 100644 --- a/docs/cordis-tutorial/index.md +++ b/docs/cordis-tutorial/index.md @@ -10,7 +10,7 @@ If you want the condensed concept reference instead of a walkthrough, read the [ ## Setup -You need a clone of this repository with dependencies installed — the [quick start](../user/guide/quickstart.md) covers prerequisites. No API key is needed for this tutorial; every example runs keylessly. +You need a clone of this repository with dependencies installed; the [development guide](../development.md#setup-tutorial) lists the prerequisites. No API key is needed for this tutorial; every example runs keylessly. ```sh git clone https://github.com/deepseek-ai/deepseek-harness.git diff --git a/docs/cordis-tutorial/index.zh.md b/docs/cordis-tutorial/index.zh.md index a68e931d81..fb2c4f0959 100644 --- a/docs/cordis-tutorial/index.zh.md +++ b/docs/cordis-tutorial/index.zh.md @@ -10,7 +10,7 @@ Cordis 是 DeepSeek Harness SDK 底层的插件框架：它是一个小型运行 ## 准备工作 -你需要克隆本仓库并安装依赖，具体前置条件见[快速入门](../user/guide/quickstart.md)。本教程不需要 API 密钥；所有示例均可在无密钥环境中运行。 +你需要克隆本仓库并安装依赖；[开发指南](../development.md#setup-tutorial)列出了前置条件。本教程不需要 API 密钥；所有示例均可在无密钥环境中运行。 ```sh git clone https://github.com/deepseek-ai/deepseek-harness.git diff --git a/docs/user/develop/basic/index.i18n.yaml b/docs/user/develop/basic/index.i18n.yaml index 6684d18070..1bfaea7b92 100644 --- a/docs/user/develop/basic/index.i18n.yaml +++ b/docs/user/develop/basic/index.i18n.yaml @@ -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/develop/basic/index.md -index.md: e57a42b42690bd92450cc26876c13a1622bb80cc -index.zh.md: 240623341618acd6501f2897ae2844fde0a5b73b +index.md: 71b5bd5ef5d296999420c40d3b8c9cf46c918841 +index.zh.md: 5dafe8bf0938337fa1f38634088acf00a2fcab46 diff --git a/docs/user/develop/basic/index.md b/docs/user/develop/basic/index.md index e57a42b426..71b5bd5ef5 100644 --- a/docs/user/develop/basic/index.md +++ b/docs/user/develop/basic/index.md @@ -2,7 +2,7 @@ English | [中文](index.zh.md) -This tutorial creates a minimal Harness plugin and loads it into the Web UI. Start from a repository checkout that has completed the [quick start](../../guide/quickstart.md). +This tutorial creates a minimal Harness plugin and loads it into the Web UI. Start from a repository checkout that has completed the [run-from-source path](../../../../README.md#run-from-source). ## Create a local project diff --git a/docs/user/develop/basic/index.zh.md b/docs/user/develop/basic/index.zh.md index 2406233416..5dafe8bf09 100644 --- a/docs/user/develop/basic/index.zh.md +++ b/docs/user/develop/basic/index.zh.md @@ -2,7 +2,7 @@ [English](index.md) | 中文 -本教程会创建一个最小的 Harness 插件，并将其加载到 Web UI 中。请从已完成[快速开始](../../guide/quickstart.md)的仓库检出开始。 +本教程会创建一个最小的 Harness 插件，并将其加载到 Web UI 中。请从已完成[从源码运行路径](../../../../README.md#run-from-source)的仓库检出开始。 ## 创建本地项目 diff --git a/docs/user/guide/config.i18n.yaml b/docs/user/guide/config.i18n.yaml deleted file mode 100644 index 00a8867092..0000000000 --- a/docs/user/guide/config.i18n.yaml +++ /dev/null @@ -1,6 +0,0 @@ -# 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/config.md -config.md: 1d3ad5ce36d4b360ba5156b6be28a6caae4a23d4 -config.zh.md: 7f8bfaa77066f2976a5667e3ac402814a7afdf96 diff --git a/docs/user/guide/config.md b/docs/user/guide/config.md deleted file mode 100644 index 1d3ad5ce36..0000000000 --- a/docs/user/guide/config.md +++ /dev/null @@ -1,72 +0,0 @@ -# Configuration - -English | [中文](config.zh.md) - -Harness uses `cordis.yml` to describe which plugins an agent loads and the configuration passed to each one. The file composes capabilities; the generated configuration catalog records the fields and defaults each package actually supports. - -## Start from a real configuration - -The repository examples are runnable configurations and the most reliable starting points for a new project: - -- [the `dsh-base` bundle patch](../../../packages/bundle/base/cordis.patch.yml) provides the common model, tools, persistence, policy, and telemetry rows every profile starts from. -- [the `dsh-web-app` bundle patch](../../../packages/bundle/web-app/cordis.patch.yml) adds the browser host, Workspace management, browser interaction, and client plugins. -- [headless-agent](../../../examples/headless-agent/cordis.yml) exposes the coding composition as a one-shot task. -- [acp-agent](../../../examples/acp-agent/cordis.yml) exposes fresh sessions to programmatic ACP clients. - -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' - -- id: agent-loop - name: '@deepseek-ai/dsh-agent-loop' - config: - agents: - - id: main - provider: deepseek-official - model: deepseek-v4-flash -``` - -## Plugin entries - -`name` identifies an npm package or a local module relative to `cordis.yml`; `id` gives the plugin instance a stable identity; and `config` supplies plugin-specific configuration. Set `disabled: true` to skip an entry temporarily. - -```yaml -- id: local-tool - name: './src/my-tool.ts' - disabled: false - config: - toolName: my_tool -``` - -Cordis starts sibling entries concurrently. A plugin declares required services through `inject`; Cordis waits for those services before applying the plugin, so file order does not establish dependency readiness. Missing models, tools, and plugins fail as early as possible instead of being silently ignored. - -## CLI patch layers - -`dsh --profile ` 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//cordis.patch.yml`, the home-level `$DSH_HOME/cordis.patch.yml`, and each `--patch ` 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 `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`. 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() -``` - -The tag is `!!js`, not `!js`. - -## Exact configuration reference - -The generated [plugin configuration catalog](../../config-catalog.md) lists every current field, type, and default. For composition concepts, continue to the [architecture](../../architecture.md) and [capability seams](../../capability-seams.md). To create a configuration, copy the closest entry from the [examples overview](../../../examples/README.md) and adapt it. diff --git a/docs/user/guide/config.zh.md b/docs/user/guide/config.zh.md deleted file mode 100644 index 7f8bfaa770..0000000000 --- a/docs/user/guide/config.zh.md +++ /dev/null @@ -1,72 +0,0 @@ -# 配置文件 - -[English](config.md) | 中文 - -Harness 使用 `cordis.yml` 描述 agent（智能体）加载哪些插件以及每个插件的参数。配置文件负责组合能力；每个包真正支持的字段和默认值由源码生成的配置目录负责记录。 - -## 从真实配置开始 - -仓库中的示例就是可以运行的配置，也是新项目最可靠的起点： - -- [`dsh-base` 组合包补丁](../../../packages/bundle/base/cordis.patch.yml) 提供通用的模型、工具、持久化、策略与遥测配置项，每个 profile 都以此为起点。 -- [`dsh-web-app` 组合包补丁](../../../packages/bundle/web-app/cordis.patch.yml) 添加浏览器宿主、Workspace 管理、浏览器交互与客户端插件。 -- [headless-agent](../../../examples/headless-agent/cordis.yml) 以单次任务形式暴露 coding 组装。 -- [acp-agent](../../../examples/acp-agent/cordis.yml) 向程序化 ACP（Agent Client Protocol）客户端提供全新会话。 - -最小配置由一组插件条目组成： - -```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' - -- id: agent-loop - name: '@deepseek-ai/dsh-agent-loop' - config: - agents: - - id: main - provider: deepseek-official - model: deepseek-v4-flash -``` - -## 插件条目 - -`name` 指定 npm 包或相对于 `cordis.yml` 的本地模块，`id` 为插件实例提供稳定标识，`config` 传入插件自己的配置。需要临时跳过某个条目时可设置 `disabled: true`。 - -```yaml -- id: local-tool - name: './src/my-tool.ts' - disabled: false - config: - toolName: my_tool -``` - -Cordis 会并发启动同级配置项。插件通过 `inject` 声明必需服务；Cordis 会等到这些服务就绪后再应用该插件，因此文件顺序不能保证依赖已就绪。引用不存在的模型、工具或插件会尽早报错，而不是被静默忽略。 - -## CLI 补丁层 - -`dsh --profile ` 按该 profile 的 manifest（元数据清单）中 `dsh.profile.bundles` 列表的顺序，在空根之上组合各组合包补丁层，随后依次应用该 profile 自己的 `~/.dsh/profiles//cordis.patch.yml`、home 级的 `$DSH_HOME/cordis.patch.yml` 与每个 `--patch ` overlay。同一行以较后的层为准。应用 flag 并不是另一层 patch：组合包中的普通插件注入 `cmdlineArgs`，再把解析值作为自身服务提供；注入该服务并保留其 `!!js` 读取的行会让本次调用的取值优先。 - -补丁会替换目标行的整个 `config` 值，而不是深度合并各个键。例如，只用 `config: { thinking: disabled }` 修补 `llm-deepseek`，也会移除该行原有的 `apiKey` 与 `baseURL`；因此必须重新写出该行需要保留的全部键。 - -## JavaScript 值和环境变量 - -Cordis loader 使用 `!!js` 标签读取运行时表达式。API key 等凭据应放在仓库根目录、已被 Git 忽略的 `.env` 中，不能提交到配置文件。 - -```yaml -config: - apiKey: !!js process.env.DEEPSEEK_API_KEY - cwd: !!js process.cwd() -``` - -标签是 `!!js`，不是 `!js`。 - -## 精确配置参考 - -每个插件当前支持的字段、类型和默认值见自动生成的[插件配置目录](../../config-catalog.md)。理解插件如何组合可继续阅读[架构说明](../../architecture.md)和[能力接口](../../capability-seams.md)；要创建自己的配置，优先复制并修改[示例目录说明](../../../examples/README.md)中最接近的例子。 diff --git a/docs/user/guide/index.i18n.yaml b/docs/user/guide/index.i18n.yaml index 056122d1fb..51f8a8802d 100644 --- a/docs/user/guide/index.i18n.yaml +++ b/docs/user/guide/index.i18n.yaml @@ -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/index.md -index.md: a04698e29755d4a08b012f8b61accb79c470dcb0 -index.zh.md: 3808d9506fa9cb3a3e455ed478e4f02c18fc09ab +index.md: 80d288b1aba37e7f0863fe5fc8237cbd2a6ab9b5 +index.zh.md: addfbc94ff93ed015e52f509a23a3f981e36770b diff --git a/docs/user/guide/index.md b/docs/user/guide/index.md index a04698e297..80d288b1ab 100644 --- a/docs/user/guide/index.md +++ b/docs/user/guide/index.md @@ -1,52 +1,28 @@ -# Introduction +# Use the Web UI English | [中文](index.zh.md) -DeepSeek Harness is a **plugin-based agent development framework** built on the [Cordis](https://github.com/cordiverse/cordis) microkernel. Its central idea is simple: **everything is a plugin**. +Start the Web UI through the [root README](../../../README.md#run); the command prints its URL. This guide begins after that server is running. -## What it is +The invoking directory is the default workspace, so the agent can inspect and modify the project where you started `dsh`. -Harness implements every capability an AI agent needs—including LLM calls, tool execution, session management, and subtask delegation—as a composable plugin. A `cordis.yml` file declares which plugins to load and how to configure them, assembling a complete agent. +## Configure a model -```yaml -# Select the LLM backend -- name: '@deepseek-ai/dsh-llm-deepseek' +Open **Settings → Models**, enter a DeepSeek API key, and save it. The model route becomes usable immediately without restarting the server. -# Compose one configured agent -- id: agent-spine - name: '@deepseek-ai/dsh-agent-spine-demo' - config: - agents: - - id: main - provider: deepseek-official - model: deepseek-v4-flash - workspaceContext: false -``` +The [model configuration guide](./providers.md) covers other providers and custom OpenAI-compatible endpoints. -## Who it is for +## Run a task -### Application users +Start a session and send: -To run an existing agent application, such as a coding assistant or conversational agent: +> Summarize this repository and identify its main packages. -1. Copy an example template. -2. Add an API key. -3. Run it. +The agent can read and edit workspace files, run commands, delegate work, and maintain a plan. The Web UI asks before operations that require approval under the active permission policy. -No code is required. See the [quick start](./quickstart.md). +## Continue -### Plugin developers - -To add a custom tool, a new LLM adapter, or another execution backend, write a plugin. Harness provides explicit extension interfaces and a type-safe development experience. See [development](../develop/basic/). - -## Core features - -- **Configuration only** — `cordis.yml` selects the capability set; changing a model or adding a tool is a configuration edit. -- **Hot replacement (HMR)** — edit plugin code during development without restarting the process. - -## Technology - -- **Runtime**: Node.js ^22.19 or >= 24 -- **Language**: TypeScript (ESM) -- **Framework**: Cordis -- **Package manager**: pnpm workspaces (the repository pins pnpm 11) +- [Configure models](./providers.md) +- [Use the Python SDK](./python-sdk.md) +- [Use other CLI modes](../../../apps/cli/README.md) +- [Develop a plugin](../develop/basic/) diff --git a/docs/user/guide/index.zh.md b/docs/user/guide/index.zh.md index 3808d9506f..addfbc94ff 100644 --- a/docs/user/guide/index.zh.md +++ b/docs/user/guide/index.zh.md @@ -1,52 +1,28 @@ -# 介绍 +# 使用 Web UI [English](index.md) | 中文 -DeepSeek Harness 是一个**插件化的 agent（智能体）开发框架**，基于 [Cordis](https://github.com/cordiverse/cordis) 微内核构建。它的核心理念是：**一切皆插件**。 +先按照[根 README](../../../README.md#run)启动 Web UI；命令会打印其访问地址。本指南从服务器已经运行的状态开始。 -## 它是什么 +调用目录是默认工作区，因此 agent（智能体）可以检查并修改启动 `dsh` 时所在的项目。 -Harness 将 AI（人工智能） agent 所需的所有能力——LLM（大语言模型）调用、工具执行、会话管理、子任务分配——全部构建为可组合的插件。你通过一个 `cordis.yml` 配置文件来声明加载哪些插件、使用什么参数，就能组装出一个完整的 agent。 +## 配置模型 -```yaml -# Select the LLM backend -- name: '@deepseek-ai/dsh-llm-deepseek' +打开**设置 → 模型**，输入 DeepSeek API 密钥并保存。模型路由会立即可用，不需要重启服务器。 -# Compose one configured agent -- id: agent-spine - name: '@deepseek-ai/dsh-agent-spine-demo' - config: - agents: - - id: main - provider: deepseek-official - model: deepseek-v4-flash - workspaceContext: false -``` +[模型配置指南](./providers.md)介绍其他提供方和自定义 OpenAI 兼容端点。 -## 适合谁 +## 运行任务 -### 应用使用者 +启动一个会话并发送： -如果你只是想用一个现成的 agent 应用（如编程助手、对话代理），你需要的全部操作就是： +> Summarize this repository and identify its main packages. -1. 复制一个示例模板。 -2. 填写 API 密钥。 -3. 运行。 +agent 可以读取和编辑工作区文件、运行命令、委派工作并维护计划。当操作在当前权限策略下需要审批时，Web UI 会先询问你。 -不需要写任何代码。详见 [快速开始](./quickstart.md)。 +## 继续使用 -### 插件开发者 - -如果你想为 agent 添加新能力——一个自定义工具、一个新的 LLM 适配器、一个新的执行后端——你需要编写一个插件。Harness 提供了清晰的扩展接口和类型安全的开发体验。详见 [开发](../develop/basic/)。 - -## 核心功能 - -- **只需要配置** — `cordis.yml` 决定能力集合，换模型、加工具只需改一行 -- **HMR（热模块替换）** — 开发时修改插件代码，无需重启进程 - -## 技术栈 - -- **运行时**：Node.js ^22.19 或 >= 24 -- **语言**：TypeScript（ESM） -- **框架**：Cordis -- **包管理**：pnpm workspaces（仓库固定使用 pnpm 11） +- [配置模型](./providers.md) +- [使用 Python SDK](./python-sdk.md) +- [使用其他 CLI 模式](../../../apps/cli/README.md) +- [开发插件](../develop/basic/) diff --git a/docs/user/guide/providers.i18n.yaml b/docs/user/guide/providers.i18n.yaml index 9da7fd1113..7dc9c5c42a 100644 --- a/docs/user/guide/providers.i18n.yaml +++ b/docs/user/guide/providers.i18n.yaml @@ -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: 0e7ed11d1b09a8361d75b576a400978ac66d08a7 -providers.zh.md: 060bf3dc41b773e89cd0d78de921c3a20cfc6076 +providers.md: a3f94f0cc86401c0f9e5b94cfd823bf9f08e6bfc +providers.zh.md: 7d74e0086e62d8a0c2fb39085207125b4b4354e7 diff --git a/docs/user/guide/providers.md b/docs/user/guide/providers.md index 0e7ed11d1b..a3f94f0cc8 100644 --- a/docs/user/guide/providers.md +++ b/docs/user/guide/providers.md @@ -2,151 +2,44 @@ English | [中文](providers.zh.md) -Harness ships with DeepSeek and mounts a generic multi-provider adapter alongside it, for the providers in pi-ai's installed catalog — Anthropic, OpenAI, and the rest — and for any OpenAI-compatible gateway or self-hosted server. You have two entry points: the **Models** page in the web UI, and `$DSH_HOME/settings.yaml`. Both write the same document, and a change takes effect on the next request without a restart. +This guide assumes you started the Web UI through the [root README](../../../README.md#run). Model changes take effect on the next request without restarting the server. -## Where providers come from +## Configure DeepSeek -`cordis.yml` decides which **adapters** are installed; the settings document decides which **providers** run. The shipped composition carries two LLM adapters: - -- `llm-deepseek` serves the `deepseek-official` route, the one available out of the box. -- `llm-pi-ai` mounts **dormant**: zero routes and no extra entries in the model picker until an `llm-pi-ai:` settings section supplies provider profiles, at which point those routes register live and drop again when the section empties. - -Adding a provider therefore rarely means editing `cordis.yml` — writing settings is enough, and that is exactly what the Models page does. - -## Configure from the web UI - -Start `pnpm dsh web` and open **Settings → Models**. +Open **Settings → Models**. The DeepSeek card exposes one API-key field; enter the key and save it. ![The Models page: the DeepSeek card, with Add provider and Add a custom provider below it](providers-models-page.png) -**Give DeepSeek its key.** The DeepSeek card carries one API-key field; fill it in, save, and the provider is ready. +Keys are write-only. The page receives a redacted descriptor after saving, never the literal secret. The key is stored in `$DSH_HOME/.credentials.yaml`, while settings retain only its credential reference. -**Add a provider from the installed catalog.** Choose **Add provider**, pick one of pi-ai's catalog providers (anthropic, openai, and so on), and enter that provider's API key. The endpoint, protocol, and model catalog all come from the catalog; the key is the only thing you owe. +## Add a catalog provider -That holds for providers that authenticate with an API key. The catalog also carries Bedrock, Vertex, Azure, and Codex, which need AWS credentials and a region, an ADC project, an `api-version`, and OAuth respectively: filling in the key field alone will not make them work. Those authenticate through pi-ai's own environment discovery, with credentials prepared the way each one requires. +Choose **Add provider**, select a provider such as Anthropic or OpenAI, enter its API key, and save. The installed catalog supplies the endpoint, protocol, and model list. -**Add a custom provider.** Choose **Add a custom provider** for a route the catalog does not ship — a company gateway, a self-hosted server, or a provider newer than the installed catalog. It asks for a Provider ID (the lowercase identifier that names the route in requests and as its credential), a base URL, a protocol, and at least one model. +Providers with native authentication need their native credentials instead. Bedrock, Vertex, Azure, and Codex use AWS credentials and a region, an ADC project, an `api-version`, and OAuth respectively; filling only the API-key field does not configure them. + +## Add a custom provider + +Choose **Add a custom provider** for a company gateway, self-hosted server, or provider absent from the installed catalog. Supply a lowercase Provider ID, base URL, API protocol, credential, and at least one model. ![The custom provider form: Provider ID, display name, base URL, API protocol, and API key](providers-custom-form.png) -Every field but the Provider ID stays editable afterwards: **Edit** on the row reopens the same fields, with the display name and the protocol under **Customized settings** beside the base URL. Clearing the display name falls back to the Provider ID. The Provider ID itself is fixed: it names the route in requests, in `agent-default-model`, and in every session already logged, and it is the stem of the credential reference the page can never read back — so renaming a route means declaring a new provider and deleting the old one. +The Provider ID is permanent because requests, saved sessions, model defaults, and credential references use it. To rename a provider, add a new provider and delete the old one. The display name, base URL, protocol, credential, and models remain editable. -**Let the endpoint report its models.** Expand **Model catalog** and choose **Fetch available models**: the interrogation asks the endpoint **the form currently shows** — including a base URL edited but not yet saved and a key typed but not yet stored — and offers what it reports as candidates to pick from. A route the installed catalog describes is answered from that catalog with no network call. Adopting a candidate only writes rows into the draft; nothing is stored until you save. +Under **Model catalog**, choose **Fetch available models** to query the base URL and credential currently shown in the form. Selecting candidates updates the draft; the provider is not stored until you save. Catalog providers use their installed catalog without a network request. -Keys are write-only: the page only ever holds a redacted descriptor, never the literal secret. A key you enter is stored in `$DSH_HOME/.credentials.yaml`, and the profile records only the variable name that references it. +## Select a model -## settings.yaml for advanced configuration +Configured providers appear in the model picker. Selecting a model also makes it the default for new sessions. A session that has already sent a request retains the model recorded in its own log. -The document lives at `$DSH_HOME/settings.yaml` (`$DSH_HOME` defaults to `~/.dsh`). The Models page writes this file, and you can edit it directly; neither source outranks the other. - -```yaml -llm-deepseek: - reasoningEffort: high - -llm-pi-ai: - providers: - # Catalog route: endpoint, protocol, and models come from pi-ai; you supply - # the credential. - openai: - apiKeyEnv: OPENAI_API_KEY - - # Also a catalog route, moved to a private proxy, with its catalog narrowed - # to one model and that model's capacity corrected. Every unset field still - # comes from the catalog. - anthropic: - apiKeyEnv: ANTHROPIC_API_KEY - baseURL: https://proxy.example.com:8443 - reasoning: high - models: - - id: claude-sonnet-4-5 - contextWindow: 200000 - - # Catalog route with one model reshaped in place; the rest of the catalog - # keeps serving (a models list would replace it instead). - deepseek: - apiKeyEnv: DEEPSEEK_API_KEY - modelOverrides: - deepseek-v4-pro: - reasoningEfforts: - off: - high: high - - # Hand-declared route: pi-ai ships nothing under this key, so the profile - # supplies the whole provider. - acme-gateway: - displayName: Acme Gateway - apiKeyEnv: ACME_GATEWAY_API_KEY - api: openai-completions - baseURL: https://gateway.acme.example/v1 - # Reasoning dialect for an endpoint whose URL pi-ai cannot recognize. - compat: - thinkingFormat: deepseek - models: - - id: acme-large - name: Acme Large - contextWindow: 65536 - maxTokens: 4096 - - id: acme-think - name: Acme Think - # key = level offered in the picker, value = what goes on the wire; - # only off may leave the value empty (supported, send nothing). - reasoningEfforts: - off: - high: high - max: ultra -``` - -A settings section merges over the matching `cordis.yml` configuration **per provider**, so you can override one field of one route and leave the rest as the composition set them. - -A profile the adapter could not serve is refused **where it is written**: a hand-declared route needs `api`, `baseURL`, and at least one model, and a profile missing any of them fails naming the offending route and model rather than being stored and quietly disabling the whole namespace. When an already-stored document is broken by an external edit, settings keeps the last good value and warns. - -## The model catalog - -A profile's `models` list *replaces* that route's installed catalog rather than extending it; omitting it or leaving it empty serves the catalog unchanged. Each entry defaults its unset fields from the installed model of the same `id`, so narrowing a route to two models, correcting one capacity, or adding a model newer than the installed catalog are each a one-line edit — but once you declare the list, every model the route should keep serving must appear in it, an entry of nothing but `id` being enough. - -Reshaping a few catalog models while keeping the rest is `modelOverrides`' job: it is keyed by catalog model id, takes the same fields a `models` entry does, and leaves the rest of the catalog serving untouched. An override naming a model the catalog does not describe — or set beside a `models` list, or on a custom provider — is refused rather than silently skipped. - -The configurable model fields are `id`, `name`, `contextWindow`, `maxTokens`, `reasoningEfforts`, and `compat`. Pricing and input modalities have no consumer and ride the installed entry. - -**Declare reasoning levels per model.** `reasoningEfforts` lists the levels a model offers: each key appears in the composer's effort picker, and its value is what dispatch sends on the wire — `high: high` passes the name through, `max: ultra` renames it for a gateway with its own vocabulary. A level you leave out is not offered. `off` is special: declared without a value, Off appears in the picker and selecting it sends nothing; left out entirely, the picker offers no Off and requests carry no off switch — the provider's own default decides. `reasoningEfforts: false` declares a non-reasoning model, which is also how you strip reasoning from a catalog model your gateway cannot serve. Without this field a custom model does not reason and a catalog model keeps its catalog levels. - -**Pick the reasoning dialect.** How a level travels — plain `reasoning_effort`, DeepSeek's `thinking: {type}` plus effort, and so on — is normally guessed from the endpoint URL, and a private gateway's URL says nothing, so a DeepSeek-style gateway would be spoken to in the OpenAI dialect. `compat.thinkingFormat` sets the dialect explicitly, and `compat.supportsReasoningEffort: false` holds the parameter back from an endpoint that rejects it; both work on the route (its models' default) or per model, for `openai-completions` routes only. - -A model neither the entry nor the catalog sizes takes the route's `defaultContextWindow` (262,144) and `defaultMaxTokens` (32,768). Both are guesses by construction, which is why they are route fields: a deployment whose gateway serves smaller models corrects them once. - -Model ids are not lifecycle configuration. Requesting a model the route does not configure fails with `UNKNOWN_MODEL` before any provider request goes out. - -## Credentials - -Use `apiKeyEnv`: it is a *reference* resolved per request, so no secret enters the configuration file. Omitting it leaves a route unauthenticated, which for a catalog route means pi-ai's own environment discovery. A reference that resolves to nothing fails the request with `MISSING_CREDENTIAL` rather than falling through to whatever unrelated key the environment happens to hold. - -Under `dsh`, references resolve from the inherited environment, the Models page's `$DSH_HOME/.credentials.yaml` store, the invoking directory's `.env`, then `$DSH_HOME/.env`. Without a credential service, a reference reads only the matching environment variable. One credential serves every model on its route. - -## Point an agent at the new provider - -A configured route appears in the web model picker and can be switched at any time. - -Switching there also sets the default: the model you pick becomes the one the next new session starts on, recorded in `settings.yaml` under `agent-default-model`. There is no separate gesture. - -```yaml -agent-default-model: - provider: acme-gateway - model: acme-large - reasoningEffort: high # optional -``` - -After a session has run a turn, its own log remains authoritative for its model selection; the default applies only to sessions without a recorded request. The shipped fallback under this section is the base bundle's `agent-default-model` composition entry (`deepseek-official` / `deepseek-v4-flash`). A self-assembled `cordis.yml` mounts and configures `@deepseek-ai/dsh-agent-default-model`; both direct entry points and Host-backed entry points read that same service. - -If the provider a saved default names is later removed, the composer says **Select model** and refuses input until you pick one, rather than sending to a route nothing serves. +If a saved default names a provider that was deleted, the composer displays **Select model** and blocks input until another model is selected. ## Troubleshooting -- **`MISSING_CREDENTIAL`** — the variable the profile's `apiKeyEnv` names holds no value. Store the key once through the Models page, or export the variable. -- **`UNKNOWN_MODEL`** — the requested model is not in the route's configured catalog. Add it to `models`, or use an id the catalog already carries. -- **`UNSUPPORTED_REASONING_EFFORT`** — the request asked the model for a level it does not offer. Pick a level the composer lists for that model, or declare the missing one in the model's `reasoningEfforts`. -- **`settings-rejected`** — the written profile cannot be served, and the message names the route and model. For a hand-declared route, check that `api`, `baseURL`, and `models` are all present. -- **Fetching available models answers 401** — the endpoint refused the interrogation. Check the key; if the base URL points at an Anthropic-style gateway, note that the interrogation reads only the OpenAI-compatible `GET /models`, so enter the models by hand instead. +- **`MISSING_CREDENTIAL`** — Store the provider key through the Models page or supply the referenced environment variable. +- **`UNKNOWN_MODEL`** — Select a configured model or add the missing model to the custom provider. +- **Fetching available models returns 401** — Check the key. Model discovery calls the OpenAI-compatible `GET /models` endpoint; enter models manually for endpoints that do not provide it. -## Exact field reference +## Advanced configuration -The complete fields, types, and defaults each plugin currently supports live in the generated [plugin configuration catalog](../../config-catalog.md). Each adapter's own semantics belong to its README: [`dsh-llm-pi-ai`](../../../packages/llm/llm-pi-ai/README.md) and [`dsh-llm-deepseek`](../../../packages/llm/llm-deepseek/README.md). For `cordis.yml` itself, see [Configuration](./config.md). +The generated [plugin configuration catalog](../../config-catalog.md) lists every supported field and default. The [`dsh-llm-pi-ai`](../../../packages/llm/llm-pi-ai/README.md) and [`dsh-llm-deepseek`](../../../packages/llm/llm-deepseek/README.md) references own direct `settings.yaml` configuration, catalog resolution, reasoning controls, credentials, and adapter errors. diff --git a/docs/user/guide/providers.zh.md b/docs/user/guide/providers.zh.md index 060bf3dc41..7d74e0086e 100644 --- a/docs/user/guide/providers.zh.md +++ b/docs/user/guide/providers.zh.md @@ -2,151 +2,44 @@ [English](providers.md) | 中文 -Harness 出厂自带 DeepSeek，同时预装了一个通用的多提供方适配器，用来接入 pi-ai 已安装目录中的 Anthropic、OpenAI 等提供方，或任何 OpenAI 兼容的网关与自建服务。你有两个入口：Web 界面的**模型**页，以及 `$DSH_HOME/settings.yaml`。两者写的是同一份文档，改完下一次请求即生效，不用重启。 +本指南假定你已按照[根 README](../../../README.md#run)启动 Web UI。模型变更会在下一次请求时生效，不需要重启服务器。 -## 提供方从哪里来 +## 配置 DeepSeek -`cordis.yml` 决定装了哪些**适配器**，settings 文档决定跑哪些**提供方**。出厂组合里有两个 LLM 适配器： - -- `llm-deepseek` 提供 `deepseek-official` 路由，是默认可用的那个。 -- `llm-pi-ai` 以**休眠**状态挂载：零路由，模型选择器里也不会多出条目，直到 settings 里的 `llm-pi-ai:` 段落给出提供方 profile，路由才注册上来；段落清空则一并撤下。 - -因此新增一个提供方通常不需要改 `cordis.yml`，写 settings 就够了——而模型页做的正是这件事。 - -## 在 Web 界面里配置 - -启动 `pnpm dsh web`，打开**设置 → 模型**。 +打开**设置 → 模型**。DeepSeek 卡片提供一个 API 密钥字段；输入密钥并保存。 ![模型页：DeepSeek 卡片，以及添加提供方与添加自定义提供方两个入口](providers-models-page.zh.png) -**填 DeepSeek 的密钥。** DeepSeek 卡片上只有一个 API 密钥输入框，填好保存即可开始用。 +密钥是只写的。保存后，页面只会收到脱敏描述符，永远不会收到明文密钥。密钥存储在 `$DSH_HOME/.credentials.yaml` 中，settings 只保留它的凭据引用。 -**添加内置目录里的提供方。** 点**添加提供方**，从 pi-ai 内置目录中选一个（anthropic、openai 等），填入该提供方的 API 密钥。端点、协议和模型目录都由内置目录提供，你只需要给密钥。 +## 添加目录提供方 -只对以 API 密钥认证的提供方成立。目录里也有 Bedrock、Vertex、Azure、Codex：它们分别需要 AWS 凭据与区域、ADC 项目配置、`api-version`、OAuth，只填密钥框不会让它们工作——这类提供方靠 pi-ai 自己的环境发现认证，凭据按各自的原生方式准备。 +选择**添加提供方**，选取 Anthropic 或 OpenAI 等提供方，输入其 API 密钥并保存。已安装目录会提供端点、协议和模型列表。 -**添加自定义提供方。** 点**添加自定义提供方**，用于内置目录没有的路由——公司网关、自建服务，或比内置目录更新的提供方。需要填 Provider ID（请求里点名它、也作为凭据名的小写标识）、API 地址、协议，以及至少一个模型。 +使用原生认证的提供方需要各自的原生凭据。Bedrock、Vertex、Azure 和 Codex 分别使用 AWS 凭据与区域、ADC 项目、`api-version` 和 OAuth；只填写 API 密钥字段无法完成配置。 + +## 添加自定义提供方 + +对于公司网关、自建服务器或已安装目录中不存在的提供方，选择**添加自定义提供方**。提供小写 Provider ID、基础 URL、API 协议、凭据和至少一个模型。 ![自定义提供方表单：Provider ID、显示名称、API 地址、API 协议、API 密钥](providers-custom-form.zh.png) -除 Provider ID 外的每个字段之后都还能改：行上的**编辑**会重新打开这些字段，显示名称和协议在「自定义设置」里、紧挨着 API 地址；显示名称清空即退回 Provider ID。Provider ID 本身固定不可改：它在请求里、在 `agent-default-model` 里、在每一条已记录的会话里点名这条路由，同时还是凭据引用的词干，而页面永远读不回凭据值——因此重命名一条路由等于声明一个新提供方再把旧的删掉。 +Provider ID 是永久的，因为请求、已保存会话、模型默认值和凭据引用都会使用它。如需重命名提供方，请添加新提供方并删除旧提供方。显示名称、基础 URL、协议、凭据和模型仍可编辑。 -**让端点自己报模型。** 展开**模型目录**后点**获取可用模型**，会按你**当前表单里**的地址与密钥去问端点（地址改了但没保存、密钥刚输入还没存下，都算数），把它报告的模型列成候选让你勾选。内置目录里的路由直接由目录作答，不联网。采纳只是把行写进草稿，最终还是你点保存才落盘。 +在**模型目录**中选择**获取可用模型**，可查询表单当前显示的基础 URL 和凭据。选择候选项只会更新草稿；保存前不会存储提供方。目录提供方使用已安装目录，不发起网络请求。 -密钥是只写的：页面拿到的永远是脱敏描述符，不是明文。写入的密钥存进 `$DSH_HOME/.credentials.yaml`，profile 里只记录引用它的变量名。 +## 选择模型 -## settings.yaml：进阶配置 +已配置的提供方会出现在模型选择器中。选择模型也会将其设为新会话的默认值。已发送过请求的会话会保留自身日志中记录的模型。 -文档位于 `$DSH_HOME/settings.yaml`（`$DSH_HOME` 默认是 `~/.dsh`）。模型页写的就是这个文件，你也可以直接编辑它——两个来源没有主次之分。 - -```yaml -llm-deepseek: - reasoningEffort: high - -llm-pi-ai: - providers: - # Catalog route: endpoint, protocol, and models come from pi-ai; you supply - # the credential. - openai: - apiKeyEnv: OPENAI_API_KEY - - # Also a catalog route, moved to a private proxy, with its catalog narrowed - # to one model and that model's capacity corrected. Every unset field still - # comes from the catalog. - anthropic: - apiKeyEnv: ANTHROPIC_API_KEY - baseURL: https://proxy.example.com:8443 - reasoning: high - models: - - id: claude-sonnet-4-5 - contextWindow: 200000 - - # Catalog route with one model reshaped in place; the rest of the catalog - # keeps serving (a models list would replace it instead). - deepseek: - apiKeyEnv: DEEPSEEK_API_KEY - modelOverrides: - deepseek-v4-pro: - reasoningEfforts: - off: - high: high - - # Hand-declared route: pi-ai ships nothing under this key, so the profile - # supplies the whole provider. - acme-gateway: - displayName: Acme Gateway - apiKeyEnv: ACME_GATEWAY_API_KEY - api: openai-completions - baseURL: https://gateway.acme.example/v1 - # Reasoning dialect for an endpoint whose URL pi-ai cannot recognize. - compat: - thinkingFormat: deepseek - models: - - id: acme-large - name: Acme Large - contextWindow: 65536 - maxTokens: 4096 - - id: acme-think - name: Acme Think - # key = level offered in the picker, value = what goes on the wire; - # only off may leave the value empty (supported, send nothing). - reasoningEfforts: - off: - high: high - max: ultra -``` - -settings 段落**逐个提供方**地盖在 `cordis.yml` 的同名配置之上，所以你可以只覆盖某个路由的一个字段，其余保持组合里的样子。 - -一份服务不了的 profile 会在**写入处**被拒绝：手工声明的路由必须给出 `api`、`baseURL` 和至少一个模型，缺了会带着路由名和模型名报错，而不是存下来再让整个命名空间静默失效。已经存好的文档被外部改坏时，settings 会保留上一次的好值并告警。 - -## 模型目录 - -`models` 是**替换**该路由的内置目录，不是往里追加；省略或留空则原样使用内置目录。每个条目会从同 `id` 的内置模型继承自己没写的字段，所以「收窄到两个模型」「更正一个容量」「加一个比内置目录更新的模型」都是一行编辑——但一旦声明了这份列表，该路由要继续服务的每个模型就都必须出现在其中，条目哪怕只写一个 `id` 也足够。 - -就地重塑目录里的几个模型、保留其余，归 `modelOverrides` 管：它以目录模型 id 为键，接受与 `models` 条目相同的字段，目录的其余部分原样继续服务。覆盖若点名了目录没有描述的模型，或与 `models` 列表并存，或写在自定义提供方上，都会被拒绝，而不是被静默跳过。 - -可配置的模型字段是 `id`、`name`、`contextWindow`、`maxTokens`、`reasoningEfforts` 与 `compat`。定价与输入模态没有消费方，随内置目录条目走。 - -**按模型声明推理档位。** `reasoningEfforts` 列出模型提供的档位：每个键都会出现在输入框的档位选择器里，其值是分派在协议中实际发送的内容——`high: high` 原样透传名称，`max: ultra` 则为使用自有词汇的网关改名。没写的档位不会被提供。`off` 比较特殊：声明而不给值，选择器里会出现 Off，选中它时什么也不发送；完全不写，选择器不提供 Off，请求也不携带关闭开关——由提供方自己的默认行为决定。`reasoningEfforts: false` 声明一个不具备推理能力的模型，这也是从网关服务不了的目录模型上剥除推理的办法。不写这个字段，自定义模型不推理，目录模型保留目录给出的档位。 - -**选定推理方言。** 档位如何在协议中传输——单独一个 `reasoning_effort`、DeepSeek 的 `thinking: {type}` 加档位，诸如此类——通常靠端点 URL 来猜，而私有网关的 URL 什么也说明不了，于是 DeepSeek 风格的网关只会收到 OpenAI 方言的请求。`compat.thinkingFormat` 用来显式指定方言，`compat.supportsReasoningEffort: false` 则让该参数不再发给拒绝它的端点；两者既可设在路由上（作为其模型的默认值），也可按模型设置，且仅适用于 `openai-completions` 路由。 - -两处容量都没给出的模型，取路由级兜底 `defaultContextWindow`（262144）与 `defaultMaxTokens`（32768）。这两个数按定义就是猜测，所以它们是路由字段：网关服务的模型更小时改一次即可。 - -模型 id 不是生命周期配置：请求一个该路由没有配置的模型，会在任何网络请求之前以 `UNKNOWN_MODEL` 失败。 - -## 凭据 - -使用 `apiKeyEnv`——它是一个**引用**，每次请求时解析，密钥本身不进配置文件。省略它会让路由不带认证，对内置目录路由意味着交给 pi-ai 自己的环境发现。给了引用却解析不到，请求会以 `MISSING_CREDENTIAL` 失败，而不是退回去用环境里碰巧存在的某个不相干的 key 计费。 - -在 `dsh` 下，引用依次从继承环境、模型页的 `$DSH_HOME/.credentials.yaml` 存储、调用目录的 `.env` 和 `$DSH_HOME/.env` 解析。未挂载凭据服务时，引用只读取同名环境变量。一份凭据供该路由上的所有模型使用。 - -## 让 agent（智能体）用上新提供方 - -配好的路由会出现在 Web 的模型选择器里，随时可切。 - -在那里切换同时也就选定了默认值：你选的模型会成为下一个新会话的起点，记录在 `settings.yaml` 的 `agent-default-model` 段里。没有另一个单独的手势。 - -```yaml -agent-default-model: - provider: acme-gateway - model: acme-large - reasoningEffort: high # optional -``` - -会话跑过一轮后，其自身日志仍是模型选择的权威；默认值只适用于尚无请求记录的会话。这个段落之下的出厂兜底是 base 组合包的 `agent-default-model` 组合条目（`deepseek-official` / `deepseek-v4-flash`）。自行组装的 `cordis.yml` 会挂载并配置 `@deepseek-ai/dsh-agent-default-model`；直接入口与 Host 支撑的入口都读取同一服务。 - -如果某个已存默认值指向的提供方后来被删掉了，输入框会显示**选择模型**并拒绝输入，而不是把消息发给一个没人服务的路由。 +如果已保存默认值指向已删除的提供方，输入框会显示**选择模型**，并在选择其他模型前阻止输入。 ## 排错 -- **`MISSING_CREDENTIAL`** — profile 里的 `apiKeyEnv` 指向的变量没有值。用模型页存一次密钥，或导出该环境变量。 -- **`UNKNOWN_MODEL`** — 请求的模型不在该路由配置的目录里。把它加进 `models`，或改用目录里已有的 id。 -- **`UNSUPPORTED_REASONING_EFFORT`** — 请求向模型要了一个它不提供的档位。从输入框为该模型列出的档位里挑一个，或把缺的那个声明进该模型的 `reasoningEfforts`。 -- **`settings-rejected`** — 写入的 profile 服务不了，错误信息会点名具体的路由和模型。手工声明的路由检查 `api`、`baseURL`、`models` 是否齐全。 -- **获取可用模型返回 401** — 端点拒绝了这次探测。检查密钥；若地址指向的是 Anthropic 风格网关，注意探测只读 OpenAI 兼容的 `GET /models`，此时手工填写模型即可。 +- **`MISSING_CREDENTIAL`**：通过模型页存储提供方密钥，或提供被引用的环境变量。 +- **`UNKNOWN_MODEL`**：选择已配置的模型，或向自定义提供方添加缺失的模型。 +- **获取可用模型返回 401**：检查密钥。模型发现会调用 OpenAI 兼容的 `GET /models` 端点；对于不提供该端点的服务，请手动输入模型。 -## 精确字段参考 +## 进阶配置 -每个插件当前支持的完整字段、类型与默认值见自动生成的[插件配置目录](../../config-catalog.md)。两个适配器各自的语义由它们的 README 负责：[`dsh-llm-pi-ai`](../../../packages/llm/llm-pi-ai/README.md) 与 [`dsh-llm-deepseek`](../../../packages/llm/llm-deepseek/README.md)。`cordis.yml` 本身的写法见[配置文件](./config.md)。 +自动生成的[插件配置目录](../../config-catalog.md)列出所有受支持的字段与默认值。[`dsh-llm-pi-ai`](../../../packages/llm/llm-pi-ai/README.md) 和 [`dsh-llm-deepseek`](../../../packages/llm/llm-deepseek/README.md) 参考文档负责直接 `settings.yaml` 配置、目录解析、推理控制、凭据与适配器错误。 diff --git a/docs/user/guide/python-sdk.i18n.yaml b/docs/user/guide/python-sdk.i18n.yaml index e223e8ec2f..11d3323bad 100644 --- a/docs/user/guide/python-sdk.i18n.yaml +++ b/docs/user/guide/python-sdk.i18n.yaml @@ -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: c6aee27e08b266ae3e54f7817cc5b9689ad8fba4 -python-sdk.zh.md: 0b0e37a6fff8ee11d4694163ecb7d22f93bcd550 +python-sdk.md: 3ef0e6595b0b5b7dddfe05e659c58556dcc48874 +python-sdk.zh.md: a46c79aa0c7cd3b6a286e1f64e01a8a81496c0f0 diff --git a/docs/user/guide/python-sdk.md b/docs/user/guide/python-sdk.md index c6aee27e08..3ef0e6595b 100644 --- a/docs/user/guide/python-sdk.md +++ b/docs/user/guide/python-sdk.md @@ -2,59 +2,29 @@ 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 configurable system prompt, a two-tool catalog, persistent-shell behavior, and context compaction disabled. +This tutorial is the programmatic alternative to the Web UI. It installs the published Python SDK, runs a checked-in agent composition, and shows how to call the same API from your own program. ## Prerequisites - Python 3.10 or newer +- Git - 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: +Clone the repository for its runnable example, create a virtual environment, and install the SDK with its same-version bundled runtime: ```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 ``` -### 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. +The installed runtime needs no system Node.js. Repository contributors who need to build the runtime or wheels from source should use the [Python contributor workflows](../../../python/development.md). ## Run the checked-in example @@ -67,7 +37,7 @@ export DEEPSEEK_API_KEY=sk-your-key-here # export DSH_SYSTEM_PROMPT='You are a helpful software engineer assistant.' ``` -Run one task from the repository checkout: +Run one task against an isolated workspace and session directory: ```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." ``` -The script prints the final assistant response. The session root receives a JSONL session log containing the assembled model request and every tool call. +The script prints the final assistant response. The session directory receives a JSONL log containing the assembled model requests and tool calls. ## Use the SDK in your own program -The example is a thin wrapper around this SDK call: +The checked-in example is a thin wrapper around this SDK call: ```python from pathlib import Path @@ -108,9 +78,9 @@ with DeepSeekHarness( 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. +`DeepSeekHarness` starts the bundled runtime lazily and reuses it until the context manager exits. Reusing the same harness and session id preserves the session-owned Bash process, including its working directory, exported variables, and shell functions. Use a fresh session id for an independent task; reuse an id only when the next call should continue the same durable conversation. -## Understand the example configuration +## Understand the example composition | Property | Value | |---|---| @@ -123,7 +93,7 @@ print(result.final_response) | Filesystem | Bare local backend; absolute editor paths may address any path visible to the runtime process | | Session persistence | Uncompressed JSONL under `DSH_SESSION_ROOT` | -The configuration omits harness identity, workspace prompt text, skills, one-shot Bash, task tools, compaction, and every other model-facing plugin. Sandbox-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. +The composition omits harness identity, workspace prompt text, skills, one-shot Bash, task tools, compaction, and every other model-facing plugin. Sandbox-policy facts are logged as runtime user context rather than appended to the system prompt. ## Choose workspace and session IDs @@ -131,4 +101,4 @@ The configuration omits harness identity, workspace prompt text, skills, one-sho 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, so this composition does not support Windows agents. -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). +The [`jsonrpc-agent` example reference](../../../examples/jsonrpc-agent/README.md) owns the exact composition. The [Python SDK reference](../../../python/sdk/README.md) covers lifecycle, results, notifications, runtime selection, and configuration; the [Cordis primer](../../cordis-primer.md) covers composition syntax. diff --git a/docs/user/guide/python-sdk.zh.md b/docs/user/guide/python-sdk.zh.md index 0b0e37a6ff..a46c79aa0c 100644 --- a/docs/user/guide/python-sdk.zh.md +++ b/docs/user/guide/python-sdk.zh.md @@ -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)介绍组合语法。 diff --git a/docs/user/guide/quickstart.i18n.yaml b/docs/user/guide/quickstart.i18n.yaml deleted file mode 100644 index 0cca002d4f..0000000000 --- a/docs/user/guide/quickstart.i18n.yaml +++ /dev/null @@ -1,6 +0,0 @@ -# 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/quickstart.md -quickstart.md: e93e5a430f0cb345728581cd6fa3175ffd20b7d1 -quickstart.zh.md: 69cde830bb802ef19cc1204685395b957a0e02e3 diff --git a/docs/user/guide/quickstart.md b/docs/user/guide/quickstart.md deleted file mode 100644 index e93e5a430f..0000000000 --- a/docs/user/guide/quickstart.md +++ /dev/null @@ -1,62 +0,0 @@ -# Quick start - -English | [中文](quickstart.zh.md) - -This guide gets an agent running in five minutes. - -## Prerequisites - -- [Node.js](https://nodejs.org/) ^22.19 or >= 24 -- [pnpm](https://pnpm.io/) 11 through Corepack -- A [DeepSeek Platform](https://platform.deepseek.com/) API key - -```sh -node -v -corepack enable -pnpm -v -``` - -## Step 1: install and configure the API key - -```sh -git clone https://github.com/deepseek-ai/deepseek-harness.git -cd deepseek-harness -pnpm install -``` - -Create the gitignored repository-root `.env`: - -```sh -DEEPSEEK_API_KEY=sk-your-key-here -``` - -## Step 2: run one Headless task - -Run a non-interactive task and print its final answer: - -```sh -pnpm dsh --profile headless "summarize the architecture of this workspace" -``` - -`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 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 --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 diff --git a/docs/user/guide/quickstart.zh.md b/docs/user/guide/quickstart.zh.md deleted file mode 100644 index 69cde830bb..0000000000 --- a/docs/user/guide/quickstart.zh.md +++ /dev/null @@ -1,62 +0,0 @@ -# 快速开始 - -[English](quickstart.md) | 中文 - -本指南带你在 5 分钟内跑起一个 agent（智能体）。 - -## 环境准备 - -- [Node.js](https://nodejs.org/) ^22.19 或 >= 24 -- 通过 Corepack 使用 [pnpm](https://pnpm.io/) 11 -- [DeepSeek Platform](https://platform.deepseek.com/) API 密钥 - -```sh -node -v -corepack enable -pnpm -v -``` - -## 第一步：安装并配置 API 密钥 - -```sh -git clone https://github.com/deepseek-ai/deepseek-harness.git -cd deepseek-harness -pnpm install -``` - -在仓库根目录创建已被 Git 忽略的 `.env`： - -```sh -DEEPSEEK_API_KEY=sk-your-key-here -``` - -## 第二步：运行一个 Headless 任务 - -运行一个非交互式任务并打印最终回答： - -```sh -pnpm dsh --profile headless "summarize the architecture of this workspace" -``` - -`dsh --profile headless` 创建并持久化一个新会话，打印最终助手回答，然后退出。它不会启动 Web 服务器或监听端口；成功运行时 stderr 为空。 - -## 第三步：使用 Web UI - -启动浏览器界面： - -```sh -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 --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/) — 编写自己的工具或后端 diff --git a/examples/jsonrpc-agent/README.i18n.yaml b/examples/jsonrpc-agent/README.i18n.yaml index 45f02f37d4..d5c070643d 100644 --- a/examples/jsonrpc-agent/README.i18n.yaml +++ b/examples/jsonrpc-agent/README.i18n.yaml @@ -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/jsonrpc-agent/README.md -README.md: 9eb37fd29442dc40c7a17cd266c225e6750a6886 -README.zh.md: f358d3c8b22017a10dff62ce2dedced2bfd6de6c +README.md: 967f3f499962bf1fd1873fc16ac8fd8075b0df3b +README.zh.md: f84ab95132e820cf0fcf45bff4ae30d9bccb55c1 diff --git a/examples/jsonrpc-agent/README.md b/examples/jsonrpc-agent/README.md index 9eb37fd294..967f3f4999 100644 --- a/examples/jsonrpc-agent/README.md +++ b/examples/jsonrpc-agent/README.md @@ -35,4 +35,6 @@ Pass the config path through the Python SDK's `cordis` option or `DSH_CORDIS_CON - 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. [`minimal.py`](minimal.py) runs it through the Python SDK and uses `DSH_MODEL` as its default model; the [Python SDK tutorial](../../docs/user/guide/python-sdk.md) covers setup, session management, and the security boundary. +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. + +[`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. diff --git a/examples/jsonrpc-agent/README.zh.md b/examples/jsonrpc-agent/README.zh.md index f358d3c8b2..f84ab95132 100644 --- a/examples/jsonrpc-agent/README.zh.md +++ b/examples/jsonrpc-agent/README.zh.md @@ -35,4 +35,6 @@ - 所有者作用域内持久化的 `bash` - 提供 `view`、`create`、`str_replace` 与 `insert` 的 `str_replace_editor` -它组合了内置运行时所需的本地 PTY、裸 `fs-local` 后端、供持久 Bash 使用的 danger-full-access 策略，以及未压缩的 JSONL 持久化。[`minimal.py`](minimal.py) 通过 Python SDK 运行该配置，并把 `DSH_MODEL` 作为默认模型；[Python SDK 教程](../../docs/user/guide/python-sdk.md)以此配置介绍设置方式、会话管理与安全边界。 +它组合了内置运行时所需的本地 PTY、裸 `fs-local` 后端、供持久 Bash 使用的 danger-full-access 策略，以及未压缩的 JSONL 持久化。Bash 和编辑器绝对路径可以修改运行时进程有权访问的任何路径，因此只能针对可丢弃的 checkout 或容器运行该变体。持久 PTY 需要 POSIX 终端环境，因此不适用于 Windows agent 接口。 + +[`minimal.py`](minimal.py)通过 Python SDK 运行该组合，并把 `DSH_MODEL` 作为默认模型。[Python SDK 教程](../../docs/user/guide/python-sdk.md)介绍安装、运行、workspace 选择与 session 标识；[SDK 参考](../../python/sdk/README.md)归属运行时生命周期与结果语义。 diff --git a/python/sdk/README.i18n.yaml b/python/sdk/README.i18n.yaml index e13a2ccd31..d1a9bbc81b 100644 --- a/python/sdk/README.i18n.yaml +++ b/python/sdk/README.i18n.yaml @@ -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 python/sdk/README.md -README.md: 8cf366c27c8a604391ea85e298ba725e9987d428 -README.zh.md: a9258ce9aee9bce973107b49114d4ed6e81441e4 +README.md: 686cb46b6d3d12baaf2afdeba10def23d7a08edb +README.zh.md: 6414560deedbb76dd6f8571526251acd1c3f6a80 diff --git a/python/sdk/README.md b/python/sdk/README.md index 8cf366c27c..686cb46b6d 100644 --- a/python/sdk/README.md +++ b/python/sdk/README.md @@ -40,7 +40,7 @@ with DeepSeekHarness( `provider` selects a provider route registered by the chosen Cordis composition; `model` is the model id resolved by that adapter. `max_tokens` is an optional positive per-request output-token cap for the root agent and its in-process descendants; omission leaves the provider default in control. Compaction summaries keep the separate limit configured by their compaction plugin. The bundled default composition registers `deepseek-official`. A custom composition can mount `llm-pi-ai`, configure provider-specific credentials/endpoints there, and select any provider/model present in pi-ai's installed catalog. -The [Python SDK tutorial](../../docs/user/guide/python-sdk.md) uses a complete standalone Cordis file to demonstrate installation, direct SDK usage, and runs without the Web UI. +The [Python SDK tutorial](../../docs/user/guide/python-sdk.md) provides an ordered installation and first-run path without the Web UI. The [`jsonrpc-agent` example](../../examples/jsonrpc-agent/README.md) owns the complete standalone Cordis file used there. `Session.run()` owns an activity interval from its prompt's durable inbox receipt through the next whole-agent idle and returns `RunResult(session_id, final_response, finish_reason, events, notifications, session_root)`. `final_response` is the last committed root-session assistant text in the interval. `finish_reason` is the `kind` of the last root-session `turn/end` in the interval, such as `completed`, `max-tokens`, or `error`, and is `None` when no turn ended. A `turn/end` without a string `data.reason.kind` violates the runtime protocol and raises `SdkProtocolError`. Both result fields describe the owned interval rather than an output or ending causally assigned to the prompt. Steering, injected context, and other queued work may contribute before idle. diff --git a/python/sdk/README.zh.md b/python/sdk/README.zh.md index a9258ce9ae..6414560dee 100644 --- a/python/sdk/README.zh.md +++ b/python/sdk/README.zh.md @@ -37,7 +37,7 @@ with DeepSeekHarness( `provider` 用于选择当前 Cordis 组合已注册的提供方路由；`model` 是该适配器解析的模型 ID。`max_tokens` 是可选的正整数，用于限制根 agent（智能体）及其进程内后代每次请求的输出 token；省略时由提供方默认值控制。压缩摘要继续使用压缩插件单独配置的上限。内置默认组合注册 `deepseek-official`。自定义组合可以挂载 `llm-pi-ai`，在其中配置各提供方的凭据与端点，再选择 pi-ai 已安装目录中的任意提供方/模型组合。 -[Python SDK 教程](../../docs/user/guide/python-sdk.md)使用完整的独立 Cordis 文件演示安装方式、直接调用 SDK，以及在不使用 Web UI 的情况下运行 agent。 +[Python SDK 教程](../../docs/user/guide/python-sdk.md)提供不使用 Web UI 的顺序安装与首次运行路径。[`jsonrpc-agent` 示例](../../examples/jsonrpc-agent/README.md)归属该教程使用的完整独立 Cordis 文件。 `Session.run()` 拥有一个从提示词进入持久 inbox 时开始、到整个 agent 下一次进入空闲状态为止的活动区间，并返回 `RunResult(session_id, final_response, finish_reason, events, notifications, session_root)`。`final_response` 是该区间内根会话最后提交的助手文本。`finish_reason` 是该区间内根会话最后一个 `turn/end` 的 `kind`，例如 `completed`、`max-tokens` 或 `error`；没有轮次结束时为 `None`。缺少字符串 `data.reason.kind` 的 `turn/end` 违反运行时协议，并会抛出 `SdkProtocolError`。两个结果字段描述的都是自有活动区间，而不是因果上归属于该提示词的输出或结束原因。steering（中途引导）、注入的上下文和其他排队工作都可能在进入空闲状态前参与其中。 diff --git a/scripts/snapshots/translation-prompt-v4/request-response.expected.json b/scripts/snapshots/translation-prompt-v4/request-response.expected.json index 6d2784ea0d..a7c283d3ae 100644 --- a/scripts/snapshots/translation-prompt-v4/request-response.expected.json +++ b/scripts/snapshots/translation-prompt-v4/request-response.expected.json @@ -8,11 +8,11 @@ }, { "role": "user", - "content": "# DeepSeek Harness\n\nEnglish | [中文](README.zh.md)\n\nDeepSeek Harness (`dsh`) is an open-source coding agent built on the DeepSeek Harness SDK.\n\nIt uses an architecture where **everything is a plugin**.\n\n## Internal testing notice\n\nDeepSeek Harness is under internal testing. Features and interfaces may change.\n\nThe internal build uploads all Session Logs by default to help diagnose reported problems. Set `DSH_TELEMETRY_DISABLED=1` to disable telemetry. Send feedback through the internal WeChat group.\n\n## Run from source\n\nClone this repo, complete the [dependency and API-key setup](docs/user/guide/quickstart.md#step-1-install-and-configure-the-api-key), then run:\n\n```sh\npnpm dsh web\n```\n\n## Use DeepSeek Harness\n\n### Web UI\n\nStart the recommended local interface from the repository root:\n\n```sh\npnpm dsh web\n```\n\nThe command builds the repository before starting the Web UI, which is served at `http://127.0.0.1:3080` by default.\n\n### Profiles\n\nThe source CLI boots profiles — ordered stacks of plugin-bundle patch layers under your own overrides in `$DSH_HOME/profiles/`:\n\n```sh\npnpm dsh --profile web # the browser UI\npnpm dsh plugin --profile tui add # install a plugin into a custom profile\npnpm dsh --profile tui # boot it\n```\n\nThe [CLI reference](apps/cli/README.md#profiles) describes profile layout, layer semantics, and config dump commands.\n\n### Headless\n\nRun one task, print the final answer, and exit:\n\n```sh\npnpm dsh --profile headless \"summarize this workspace\"\n```\n\n### Automation and SDKs\n\nFrom a source checkout with `DEEPSEEK_API_KEY` in the environment or its root `.env`, start the ACP automation server:\n\n```sh\npnpm run demo:acp\n```\n\nThe [Python SDK](python/README.md) drives a bundled JSON-RPC runtime. The [examples](examples/README.md) cover the runnable headless, ACP, JSON-RPC, Code Mode, and self-referential compositions.\n\n## Why DeepSeek Harness\n\nBuilt-in capabilities cover file reading, editing, and search; shell and persistent PTY execution; reusable skills; task tracking, goals, plans, todos, and background tasks; subagents and workflows; sandboxing and approvals; settings and credentials; persistent, resumable, forkable, and queryable sessions; LSP and web access; context compaction; and telemetry. Each composition selects the subset appropriate to its surface. The Web UI includes Plan Mode.\n\n- **Everything is a plugin.** Models, tools, policies, storage, context management, and interfaces are composable [Cordis plugins](docs/user/develop/basic/index.md), so deployments can extend or replace behavior without forking the agent loop. See the [architecture](docs/architecture.md) for the underlying design.\n- **Runs are reconstructable.** Anything visible to the model is logged in the authoritative session stream; persistence, resume/fork/query, replay, telemetry, and UIs derive from the same events. See the [session-log architecture](docs/architecture.md#session-log).\n- **Code Mode (opt-in).** It exposes a `run_code` tool and a generated TypeScript SDK; only program output re-enters model context. See [Code Mode](packages/core/tools/README.md#code-mode).\n- **Self-referential Cordis tools are opt-in.** They let the agent inspect its live runtime and mount or unmount plugins while it runs. See the [Cordis tools](packages/self-modification/tool-cordis/README.md).\n\n## Community\n\nFollow DeepSeek Harness on Twitter for project updates.\n\n## Development\n\nStart with the [development guide](docs/development.md) and read the [architecture](docs/architecture.md) before changing packages.\n\nFor agents, follow [AGENTS.md](AGENTS.md).\n\nDeepSeek Harness is currently in internal testing.\n\n## License\n\n[BSD 3-Clause](LICENSE)\n\nThird-party dependencies and their licenses are disclosed in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).\n\n## Contributing\n\nRead [CONTRIBUTING.md](CONTRIBUTING.md) before contributing to this repository.\n" + "content": "# DeepSeek Harness\n\nEnglish | [中文](README.zh.md)\n\nDeepSeek Harness (`dsh`) is an open-source coding agent built on the DeepSeek Harness SDK.\n\nIt uses an architecture where **everything is a plugin**.\n\n## Internal testing notice\n\nDeepSeek Harness is under internal testing. Features and interfaces may change.\n\nThe internal build uploads all Session Logs by default to help diagnose reported problems. Set `DSH_TELEMETRY_DISABLED=1` to disable telemetry. Send feedback through the internal WeChat group.\n\n## Run\n\nInstall Node.js ^22.19 or >= 24 and pnpm 11, then run the published package:\n\n```sh\nnpx @deepseek-ai/dsh web\n```\n\nThe command initializes the Web profile and prints the Web UI URL, which is `http://127.0.0.1:3080` by default. Open it, add a DeepSeek API key under **Settings → Models**, then start a session. The invoking directory is the default workspace; try `Summarize this repository and identify its main packages.`\n\nContinue with the [Web UI guide](docs/user/guide/).\n\n### Run from source\n\nTo run a repository checkout instead:\n\n```sh\ngit clone https://github.com/deepseek-harness/deepseek-harness.git\ncd deepseek-harness\npnpm install\npnpm dsh web\n```\n\nThe last command builds the repository and opens the same Web UI path.\n\n## Profiles and plugins\n\nA profile is an ordered list of plugin bundles. The shipped `web` profile powers `dsh web`. Manage a profile with `dsh plugin --profile `, which forwards the remaining arguments to pnpm in that profile's directory:\n\n```sh\nnpx -p @deepseek-ai/dsh dsh plugin --profile web add \nnpx -p @deepseek-ai/dsh dsh plugin --profile web remove \n```\n\n`add`, `remove`, `update`, `why`, and other pnpm commands work unchanged. The command initializes a missing profile before changing its packages and updates its bundle list from installed packages that declare `dsh.bundle`. See the [CLI reference](apps/cli/reference/README.md#plugin-management) for the exact behavior.\n\nThe [CLI reference](apps/cli/README.md) covers headless execution and custom profiles. The [Python SDK](python/README.md) and [examples](examples/README.md) cover programmatic and custom compositions.\n\n## Community\n\nFollow DeepSeek Harness on Twitter for project updates.\n\n## Development\n\nStart with the [development guide](docs/development.md) and read the [architecture](docs/architecture.md) before changing packages.\n\nFor agents, follow [AGENTS.md](AGENTS.md).\n\n## License\n\n[BSD 3-Clause](LICENSE)\n\nThird-party dependencies and their licenses are disclosed in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).\n\n## Contributing\n\nRead [CONTRIBUTING.md](CONTRIBUTING.md) before contributing to this repository.\n" }, { "role": "assistant", - "content": "# DeepSeek Harness\n\n[English](README.md) | 中文\n\nDeepSeek Harness（`dsh`）是一款基于 DeepSeek Harness SDK 构建的开源 coding agent（智能体）。\n\n它采用了**一切皆插件**的架构。\n\n## 内测声明\n\nDeepSeek Harness 正处于内部测试阶段，功能和接口可能发生变化。\n\n为帮助诊断上报的问题，内测版本默认上传所有会话日志。设置 `DSH_TELEMETRY_DISABLED=1` 可关闭遥测。请通过内部企业微信群反馈问题和建议。\n\n## 从源码运行\n\n克隆本仓库，完成[依赖安装和 API 密钥配置](docs/user/guide/quickstart.md#step-1-install-and-configure-the-api-key)，然后运行：\n\n```sh\npnpm dsh web\n```\n\n## 使用 DeepSeek Harness\n\n### Web UI\n\n请从仓库根目录启动推荐的本地界面：\n\n```sh\npnpm dsh web\n```\n\n该命令会先构建仓库，再启动 Web UI。Web UI 默认通过 `http://127.0.0.1:3080` 提供服务。\n\n### Profile\n\n源码 CLI（命令行界面）会启动 profile：按序叠放的插件组合包 patch 层，之上再叠加你在 `$DSH_HOME/profiles/` 中的自有覆盖层：\n\n```sh\npnpm dsh --profile web # the browser UI\npnpm dsh plugin --profile tui add # install a plugin into a custom profile\npnpm dsh --profile tui # boot it\n```\n\nprofile 布局、层语义与配置输出命令详见 [CLI（命令行界面）参考](apps/cli/README.md#profiles)。\n\n### Headless\n\n运行一项任务，打印最终答案后退出：\n\n```sh\npnpm dsh --profile headless \"summarize this workspace\"\n```\n\n### 自动化与 SDK\n\n在源码检出中通过环境变量或根目录 `.env` 设置 `DEEPSEEK_API_KEY`，然后启动 ACP（Agent Client Protocol）自动化服务器：\n\n```sh\npnpm run demo:acp\n```\n\n[Python SDK](python/README.md) 驱动随附的 JSON-RPC 运行时。[示例](examples/README.md)涵盖可运行的 headless、ACP、JSON-RPC、Code Mode 和自指组合。\n\n## 为什么选择 DeepSeek Harness\n\n内置功能涵盖文件读取、编辑与搜索、shell 和持久 PTY 执行、可复用 skill（技能）、任务跟踪、目标、计划、待办事项与后台任务、subagent 与工作流、沙箱与审批、设置与凭据、可持久化、恢复、fork 与查询的会话、LSP 与 Web 访问、上下文压缩（context compaction），以及遥测。每个组合只选用适合其使用方式的能力子集。Web UI 包含 Plan Mode。\n\n- **一切皆插件。** 模型、工具、策略、存储、上下文管理和界面均为可组合的 [Cordis 插件](docs/user/develop/basic/index.md)，部署方无需 fork agent loop（智能体循环）即可扩展或替换行为。底层设计见[架构文档](docs/architecture.md)。\n- **运行可重建。** 凡是模型可见的内容，都会记录在权威会话流中；持久化、恢复／fork／查询、回放、遥测和 UI 均从同一组事件派生。参见[会话日志架构](docs/architecture.md#session-log)。\n- **Code Mode（需显式启用）。** 它会提供 `run_code` 工具和生成的 TypeScript SDK，只有程序输出会重新进入模型上下文。参见 [Code Mode](packages/core/tools/README.md#code-mode)。\n- **自指 Cordis 工具需显式启用。** 这些工具可让 agent 检查自身的实时运行时，并在运行中挂载或卸载插件。参见 [Cordis 工具](packages/self-modification/tool-cordis/README.md)。\n\n## 社区\n\n扫描二维码，或打开 DeepSeek Harness 微信社区申请页面 申请加入。\n\n

\n \"DeepSeek\n

\n\n## 开发\n\n请先阅读[开发指南](docs/development.md)；修改包之前，请阅读[架构文档](docs/architecture.md)。\n\n面向 agent：遵循 [AGENTS.md](AGENTS.md)。\n\nDeepSeek Harness 目前处于内测阶段。\n\n## 许可证\n\n[BSD 3-Clause](LICENSE)\n\n第三方依赖及其许可证在 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) 中披露。\n\n## 参与贡献\n\n向本仓库贡献前，请阅读 [CONTRIBUTING.md](CONTRIBUTING.md)。\n" + "content": "# DeepSeek Harness\n\n[English](README.md) | 中文\n\nDeepSeek Harness（`dsh`）是一款基于 DeepSeek Harness SDK 构建的开源 coding agent（智能体）。\n\n它采用了**一切皆插件**的架构。\n\n## 内测声明\n\nDeepSeek Harness 正处于内部测试阶段，功能和接口可能发生变化。\n\n为帮助诊断上报的问题，内测版本默认上传所有会话日志。设置 `DSH_TELEMETRY_DISABLED=1` 可关闭遥测。请通过内部企业微信群反馈问题和建议。\n\n## 运行\n\n安装 Node.js ^22.19 或 >= 24 和 pnpm 11，然后运行已发布的包：\n\n```sh\nnpx @deepseek-ai/dsh web\n```\n\n该命令会初始化 Web profile 并打印 Web UI 地址，默认地址为 `http://127.0.0.1:3080`。打开该地址，在**设置 → 模型**中添加 DeepSeek API 密钥，然后启动一个会话。调用目录是默认工作区；你可以尝试输入 `Summarize this repository and identify its main packages.`。\n\n下一步请阅读 [Web UI 指南](docs/user/guide/)。\n\n### 从源码运行\n\n如需改为运行仓库 checkout：\n\n```sh\ngit clone https://github.com/deepseek-harness/deepseek-harness.git\ncd deepseek-harness\npnpm install\npnpm dsh web\n```\n\n最后一条命令会构建仓库，并进入相同的 Web UI 路径。\n\n## Profile 与插件\n\nprofile 是按顺序排列的插件 bundle 列表。随附的 `web` profile 为 `dsh web` 提供功能。使用 `dsh plugin --profile ` 管理 profile；该命令会在对应 profile 目录中将剩余参数转发给 pnpm：\n\n```sh\nnpx -p @deepseek-ai/dsh dsh plugin --profile web add \nnpx -p @deepseek-ai/dsh dsh plugin --profile web remove \n```\n\n`add`、`remove`、`update`、`why` 等 pnpm 命令均可直接使用。该命令会先初始化不存在的 profile，再修改其中的包，并根据声明了 `dsh.bundle` 的已安装包更新 bundle 列表。准确行为见 [CLI 参考](apps/cli/reference/README.md#plugin-management)。\n\n[CLI（命令行界面）参考](apps/cli/README.md)介绍 headless 执行与自定义 profile。[Python SDK](python/README.md) 和[示例](examples/README.md)介绍程序化组合与自定义组合。\n\n## 社区\n\n扫描二维码，或打开 DeepSeek Harness 微信社区申请页面 申请加入。\n\n

\n \"DeepSeek\n

\n\n## 开发\n\n请先阅读[开发指南](docs/development.md)；修改包之前，请阅读[架构文档](docs/architecture.md)。\n\n面向 agent：遵循 [AGENTS.md](AGENTS.md)。\n\n## 许可证\n\n[BSD 3-Clause](LICENSE)\n\n第三方依赖及其许可证在 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) 中披露。\n\n## 参与贡献\n\n向本仓库贡献前，请阅读 [CONTRIBUTING.md](CONTRIBUTING.md)。\n" }, { "role": "user", diff --git a/website/docs.ts b/website/docs.ts index 2f25ae9d88..3cf1dab74c 100644 --- a/website/docs.ts +++ b/website/docs.ts @@ -115,44 +115,28 @@ const homeAndGuide = pairedPages([ }, { source: 'docs/user/guide/index.md', - route: 'guide/index.md', - label: { root: '介绍', en: 'Introduction' }, + route: 'guide/quickstart.md', + label: { root: '使用 Web UI', en: 'Use the Web UI' }, sidebar: { root: 'zh-guide', en: 'en-guide' }, section: { root: '入门', en: 'Guide' }, order: 1, sourceAliases: ['docs/user/guide'], }, - { - source: 'docs/user/guide/quickstart.md', - route: 'guide/quickstart.md', - label: { root: '快速开始', en: 'Quick start' }, - sidebar: { root: 'zh-guide', en: 'en-guide' }, - section: { root: '入门', en: 'Guide' }, - order: 2, - }, { source: 'docs/user/guide/providers.md', route: 'guide/providers.md', label: { root: '配置模型', en: 'Configure models' }, sidebar: { root: 'zh-guide', en: 'en-guide' }, section: { root: '入门', en: 'Guide' }, - order: 3, + order: 2, }, { source: 'docs/user/guide/python-sdk.md', route: 'guide/python-sdk.md', label: { root: 'Python SDK', en: 'Python SDK' }, sidebar: { root: 'zh-guide', en: 'en-guide' }, - section: { root: '入门', en: 'Guide' }, - order: 4, - }, - { - source: 'docs/user/guide/config.md', - route: 'guide/config.md', - label: { root: '配置文件', en: 'Configuration' }, - sidebar: { root: 'zh-guide', en: 'en-guide' }, - section: { root: '入门', en: 'Guide' }, - order: 5, + section: { root: '其他接口', en: 'Other interfaces' }, + order: 1, }, ])