|
|
@@ -2,15 +2,15 @@
|
|
|
|
|
|
English | [中文](architecture.zh.md)
|
|
|
|
|
|
-Read this before changing anything under `packages/`. It assumes you know Cordis; if you do not, start with the [primer](cordis-primer.md) or the [tutorial](cordis-tutorial/index.md).
|
|
|
+Read before changing `packages/`. For Cordis prerequisites, use the [primer](cordis-primer.md) or [tutorial](cordis-tutorial/index.md).
|
|
|
|
|
|
We recommend using an agent to explore the codebase and understand its architecture.
|
|
|
|
|
|
## Cordis
|
|
|
|
|
|
-[Cordis](cordis-primer.md) is the framework under dsh: plugins contribute services, typed events, and reversible effects to a shared context. Every part of the product is a plugin, including the model adapter, the tool registry, the session log, and the agent loop itself, so each is replaceable from configuration.
|
|
|
+[Cordis](cordis-primer.md) gives plugins a shared context for services, typed events and reversible effects. Every product component is a plugin, including model adapters, tools, session logs and the agent loop; configuration can replace each one.
|
|
|
|
|
|
-There is no privileged core to patch: you extend dsh by mounting a plugin beside the others, and registrations are effects that unwind when their plugin unloads.
|
|
|
+There is no privileged core to patch. Mount plugins to extend dsh; their registrations unwind on unload.
|
|
|
|
|
|
## Profiles and bundles
|
|
|
|
|
|
@@ -22,7 +22,7 @@ A **bundle** is a distribution format for Cordis config rows and the code they m
|
|
|
|
|
|
Each declares itself in its own `package.json` under a `dsh` field: `dsh.profile` lists a profile's bundles, and `dsh.bundle` points at a bundle's patch file.
|
|
|
|
|
|
-[`dsh-base`](../packages/bundle/base/README.md) is the shared first layer of the `web`, `headless`, `sdk`, and `acp` profiles: model adapters, tools, persistence, sandbox and approval policy, settings, credentials, telemetry. [`dsh-web-app`](../packages/bundle/web-app/README.md) adds the browser application, [`dsh-headless`](../packages/bundle/headless/README.md) adds a one-shot runner with no server, [`dsh-sdk-app`](../packages/bundle/sdk-app/README.md) adds the SDK JSON-RPC server, and [`dsh-acp-app`](../packages/bundle/acp-app/README.md) adds the automation-only ACP server. [`dsh-sdk-minimal`](../packages/bundle/sdk-minimal/README.md) is the deliberate exception: one bundle owns its complete explicit SDK tree and does not apply `dsh-base`.
|
|
|
+[`dsh-base`](../packages/bundle/base/README.md) supplies model adapters, tools, persistence, sandbox, approval, settings, credentials and telemetry to `web`, `headless`, `sdk` and `acp`. Their application layers are [`dsh-web-app`](../packages/bundle/web-app/README.md) (browser), [`dsh-headless`](../packages/bundle/headless/README.md) (one-shot runner without a server), [`dsh-sdk-app`](../packages/bundle/sdk-app/README.md) (SDK JSON-RPC server), and [`dsh-acp-app`](../packages/bundle/acp-app/README.md) (automation-only ACP server). [`dsh-sdk-minimal`](../packages/bundle/sdk-minimal/README.md) owns a complete SDK tree without `dsh-base`.
|
|
|
|
|
|
Layers apply to an empty entry list in this order: each bundle in the profile's listed order, then the profile's `cordis.patch.yml`, then the home-level one, then any `--patch` overlay. A patch targets a row by id and replaces its whole config, or inserts new rows.
|
|
|
|
|
|
@@ -42,21 +42,21 @@ Composition mechanics are in [app-boot](../packages/boot/app-boot/README.md#prof
|
|
|
|
|
|
## Application launch
|
|
|
|
|
|
-Every supported Node application starts at the `dsh` CLI with a named profile. The shipped applications are `dsh web` (the deliberate alias for `--profile web`), `dsh --profile headless`, `dsh --profile sdk`, `dsh --profile sdk-minimal`, and `dsh --profile acp`. The TypeScript SDK resolves its same-version `dsh` dependency and selects `sdk`; custom plugin composition remains a profile plus ordered patch files, not another executable or inline application tree. `sdk-minimal` is a repository-owned standalone bundle behind the same launcher, not a caller-supplied Cordis tree.
|
|
|
+Supported Node applications launch through `dsh --profile <name>`; `dsh web` aliases `--profile web`. The TypeScript SDK resolves its same-version `dsh` dependency and selects `sdk`. Custom compositions use profiles and ordered patch files, never another executable or an inline application tree. The shipped `sdk-minimal` bundle uses this launcher rather than accepting a caller-supplied Cordis tree.
|
|
|
|
|
|
Vendored CLIs, build-only and test-only executables, direct in-process plugin mounting, and the private browser WebWorker preview are not Harness application launchers. [`verify-application-entrypoints`](../scripts/verify-application-entrypoints.ts) keeps every package bin, executable source, and root demo in an explicit class and rejects a Node application path that bypasses `dsh`.
|
|
|
|
|
|
-The Python SDK follows the same application architecture. Its runtime wheel packages the normal `dsh` CLI as `deepseek-harness-sdk-runtime-<platform>-<arch>`, and the client launches `dsh --profile sdk` with an explicit Harness home by default. The minimal example selects the shipped `sdk-minimal` profile. Python exposes profile selection and ordered patch files rather than a complete Cordis tree; persistent external plugins are installed through `dsh plugin`. The removed private direct-config carrier has no compatibility bin or fallback parser.
|
|
|
+The Python SDK's `deepseek-harness-sdk-runtime-<platform>-<arch>` wheel contains the normal `dsh` CLI. Clients launch `sdk` with an explicit Harness home by default; the minimal example selects `sdk-minimal`. Python exposes profiles and ordered patches, with persistent plugins installed through `dsh plugin`. The removed private direct-config carrier has no compatibility bin or fallback parser.
|
|
|
|
|
|
## Desktop application
|
|
|
|
|
|
The [Electron desktop application](../apps/desktop/README.md) carries its exact dsh production runtime in signed application resources. The reserved `$DSH_HOME/profiles/desktop` contains external plugins and links to host-owned packages; compatible upgrades retain plugin files and refresh these links without installing core dependencies. CLI profiles share supported product data under `$DSH_HOME`, while executable packages, plugin activation, lockfiles, and package-manager state remain separate.
|
|
|
|
|
|
-Electron starts the private Desktop Host package under its bundled upstream Node.js process; that package loads the bundled dsh backend and matching client graph together with enabled profile plugins. Unary RPC, Remote streams, and version-matched client assets cross versioned framed byte pipes with Node IPC reserved for lifecycle control, then reach the renderer through the secure `dsh-app://` protocol; the desktop composition opens no Web server or loopback port. Only shell-owned UI can run plugin transactions through the bundled pnpm and its private `$DSH_HOME/desktop/pnpm/store`.
|
|
|
+Electron's bundled upstream Node.js runs the private Desktop Host, loading the matching backend, client graph and enabled plugins. Versioned byte pipes carry unary RPC, Remote streams and version-matched assets; Node IPC handles lifecycle control. The renderer uses `dsh-app://`, without a Web server or loopback port. Only shell-owned UI runs plugin transactions through bundled pnpm and `$DSH_HOME/desktop/pnpm/store`.
|
|
|
|
|
|
## Core packages
|
|
|
|
|
|
-Here are some core packages that contribute to the Cordis tree.
|
|
|
+Core packages:
|
|
|
|
|
|
| Package | Owns | `ctx` key |
|
|
|
|---|---|---|
|
Yichen Jiang