Coder/deepseek-harness
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: rename coding demo to repl

Browse Source
This commit is contained in:
Tianyi Cui
2026-07-04 01:07:26 +08:00
parent 4cf2ade4ba
commit 51640362b5
20 changed files with 52 additions and 52 deletions
Download Patch File Download Diff File Expand all files Collapse all files

16
AGENTS.md
View File

@@ -94,7 +94,7 @@ packages/ Harness packages, grouped by role at packages/<group>/<pkg>/.
acp/ Agent Client Protocol bridge: drive the agent from an ACP acp/ Agent Client Protocol bridge: drive the agent from an ACP
editor (Zed) over JSON-RPC stdio editor (Zed) over JSON-RPC stdio
stdio-agent/ stdio chat APP: agent-core spine + console logger + readline stdio-agent/ stdio chat APP: agent-core spine + console logger + readline
UI + a pre-created main agent + a bin (the demo:echo/coding UI + a pre-created main agent + a bin (the demo:echo/repl
front door) front door)
acp-agent/ ACP server APP: agent-core spine + JSONL persistence + the acp-agent/ ACP server APP: agent-core spine + JSONL persistence + the
acp bridge, NO stdout logger + a bin (the demo:acp front door) acp bridge, NO stdout logger + a bin (the demo:acp front door)
@@ -115,10 +115,10 @@ examples/ Runnable demos (not workspaces; see examples/AGENTS.md). Each is a
teaching plugins. The app package bundles the agent-core spine + teaching plugins. The app package bundles the agent-core spine +
front-door cluster + boot glue (a bin). No start.ts. echo-agent = front-door cluster + boot glue (a bin). No start.ts. echo-agent =
mock model + echo tool on dsh-stdio-agent (pnpm run demo:echo, no mock model + echo tool on dsh-stdio-agent (pnpm run demo:echo, no
key). coding-agent = the real thing: DeepSeek V4 + fs tools key). coding-agent = the REPL agent demo: DeepSeek V4 + fs tools
(read/write/edit) + bash tools + subagent + todo_write on the same (read/write/edit) + bash tools + subagent + todo_write on the same
app (pnpm run demo:coding, needs DEEPSEEK_API_KEY). acp-agent = the app (pnpm run demo:repl, needs DEEPSEEK_API_KEY). acp-agent = the
coding agent as an ACP server on dsh-acp-agent (pnpm run demo:acp, ACP server agent demo on dsh-acp-agent (pnpm run demo:acp,
needs DEEPSEEK_API_KEY). needs DEEPSEEK_API_KEY).
cordis.snapshot.yml = the acp leaf with llm-replay for keyless cordis.snapshot.yml = the acp leaf with llm-replay for keyless
snapshot replay. snapshot replay.
@@ -188,10 +188,10 @@ pnpm run verify-node-next-types # assert built declarations typecheck for a
pnpm run doc-sync # doc-typecheck + verify-cordis-catalog + verify-tool-catalog + verify-md-wrap + verify-md-links + verify-doc-refs + verify-package-paths + verify-rfc-classification + verify-type-equiv + verify-translation-pairing (CI runs this) pnpm run doc-sync # doc-typecheck + verify-cordis-catalog + verify-tool-catalog + verify-md-wrap + verify-md-links + verify-doc-refs + verify-package-paths + verify-rfc-classification + verify-type-equiv + verify-translation-pairing (CI runs this)
pnpm run demo:echo # run examples/echo-agent (no API key; type "echo hi" to pnpm run demo:echo # run examples/echo-agent (no API key; type "echo hi" to
# see a tool call) — the mock skeleton # see a tool call) — the mock skeleton
pnpm run demo:coding # run examples/coding-agent — the real agent (needs pnpm run demo:repl # run examples/coding-agent — the REPL agent demo
# DEEPSEEK_API_KEY; give it a coding task) # (needs DEEPSEEK_API_KEY; give it a coding task)
pnpm run demo:acp # run examples/acp-agent — the coding agent as an ACP pnpm run demo:acp # run examples/acp-agent — the ACP server agent demo
# server over JSON-RPC stdio (needs DEEPSEEK_API_KEY; # over JSON-RPC stdio (needs DEEPSEEK_API_KEY;
# drive it from Zed or another ACP client) # drive it from Zed or another ACP client)
``` ```

4
README.i18n.yaml
View File

@@ -2,5 +2,5 @@
# side as of the last confirmed-consistent state. Both languages carry equal authority; # 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: # after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write # pnpm run verify-translation-pairing --write
README.md: 880ca9a3420aec23b82bb2d3e5e96f7895b8b3b6 README.md: 7ddf68bab06ecf891856e6d1393ccdefd9eeba38
README.zh.md: bf733a6699b958a658bd4c2f7becc8ce769dd70b README.zh.md: 4bcee075512c37ea60a8be5ca5ae8acf945f161a

4
README.md
View File

@@ -11,8 +11,8 @@ This monorepo is built on the [Cordis](https://github.com/cordiverse/cordis) fra
```sh ```sh
pnpm install pnpm install
pnpm run test # vitest pnpm run test # vitest
pnpm run demo:coding # coding-agent demo (needs DEEPSEEK_API_KEY) pnpm run demo:repl # REPL agent demo (needs DEEPSEEK_API_KEY)
pnpm run demo:acp # ACP server demo (needs DEEPSEEK_API_KEY) pnpm run demo:acp # ACP server agent demo (needs DEEPSEEK_API_KEY)
``` ```
For humans, start with the [development guide](docs/development.md) for local setup, hooks, environment variables, and quality gates, then read the [architecture design](docs/architecture.md) before package work. Local context lives in [packages/](packages/) and [vendor/](vendor/). For humans, start with the [development guide](docs/development.md) for local setup, hooks, environment variables, and quality gates, then read the [architecture design](docs/architecture.md) before package work. Local context lives in [packages/](packages/) and [vendor/](vendor/).

4
README.zh.md
View File

@@ -11,8 +11,8 @@
```sh ```sh
pnpm install pnpm install
pnpm run test # vitest pnpm run test # vitest
pnpm run demo:coding # coding-agent demo (needs DEEPSEEK_API_KEY) pnpm run demo:repl # REPL agent demo (needs DEEPSEEK_API_KEY)
pnpm run demo:acp # ACP server demo (needs DEEPSEEK_API_KEY) pnpm run demo:acp # ACP server agent demo (needs DEEPSEEK_API_KEY)
``` ```
面向人类读者：先读[开发指南](docs/development.md)了解本地环境搭建、钩子、环境变量与质量门禁，动手改 package 之前再读[架构设计](docs/architecture.md)。局部上下文见 [packages/](packages/) 与 [vendor/](vendor/)。 面向人类读者：先读[开发指南](docs/development.md)了解本地环境搭建、钩子、环境变量与质量门禁，动手改 package 之前再读[架构设计](docs/architecture.md)。局部上下文见 [packages/](packages/) 与 [vendor/](vendor/)。

2
docs/cookbook/extension-cookbook.md
View File

@@ -83,4 +83,4 @@ export function apply(ctx: Context) {
## Runnable wirings ## Runnable wirings
Three complete examples load their plugin trees from `cordis.yml`: [`examples/echo-agent`](../../examples/echo-agent) (mock model + echo tool — the all-mock skeleton check, `pnpm run demo:echo`), [`examples/coding-agent`](../../examples/coding-agent) (DeepSeek V4 + the bash tool suite — the real thing, `pnpm run demo:coding`), and [`examples/acp-agent`](../../examples/acp-agent) (the same coding agent exposed as an ACP server over JSON-RPC stdio — the client-driver shape, `pnpm run demo:acp`). Each leaf is now just its swappable backends plus an app-package entry: the stdio demos load [`@deepseek-ai/dsh-stdio-agent`](../../packages/ui/stdio-agent), the ACP demo loads [`@deepseek-ai/dsh-acp-agent`](../../packages/ui/acp-agent), and both app packages share the spine via the [`@deepseek-ai/dsh-agent-core`](../../packages/core/agent-core) bundle. Three complete examples load their plugin trees from `cordis.yml`: [`examples/echo-agent`](../../examples/echo-agent) (mock model + echo tool — the all-mock skeleton check, `pnpm run demo:echo`), [`examples/coding-agent`](../../examples/coding-agent) (DeepSeek V4 + the bash tool suite behind a terminal REPL UI, `pnpm run demo:repl`), and [`examples/acp-agent`](../../examples/acp-agent) (an agent exposed as an ACP server over JSON-RPC stdio — the client-driver shape, `pnpm run demo:acp`). Each leaf is now just its swappable backends plus an app-package entry: the stdio demos load [`@deepseek-ai/dsh-stdio-agent`](../../packages/ui/stdio-agent), the ACP demo loads [`@deepseek-ai/dsh-acp-agent`](../../packages/ui/acp-agent), and both app packages share the spine via the [`@deepseek-ai/dsh-agent-core`](../../packages/core/agent-core) bundle.

4
docs/development.i18n.yaml
View File

@@ -2,5 +2,5 @@
# side as of the last confirmed-consistent state. Both languages carry equal authority; # 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: # after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write # pnpm run verify-translation-pairing --write
development.md: ce431d95c5dbb976d0c3ffa827af46ba608b400e development.md: 3e11ae594759e6251e46f3bf9e0b021d9e1555c5
development.zh.md: 36155ee2b93f2bc309ca1341cbed82c37e2759c9 development.zh.md: e8cea20a713767411304c2a3c97099004b9392c3

10
docs/development.md
View File

@@ -9,7 +9,7 @@ This guide covers the local setup needed to work on DeepSeek Harness and underst
- Node.js 24 or newer. The repo declares `node >=24`; CI runs the matrix on Node 24 and 26. - Node.js 24 or newer. The repo declares `node >=24`; CI runs the matrix on Node 24 and 26.
- Corepack-enabled pnpm. The repo pins `pnpm@11.7.0` in `package.json`; run `corepack enable` if `pnpm --version` does not resolve through Corepack. - Corepack-enabled pnpm. The repo pins `pnpm@11.7.0` in `package.json`; run `corepack enable` if `pnpm --version` does not resolve through Corepack.
- Git. - Git.
- Optional: a DeepSeek API key for the coding-agent demo and real-API e2e tests. - Optional: a DeepSeek API key for the REPL/ACP agent demos and real-API e2e tests.
## First-time setup ## First-time setup
@@ -45,7 +45,7 @@ pnpm run build
## Environment variables ## Environment variables
The real DeepSeek adapter and coding-agent demo read credentials from the environment or from a gitignored `.env` at the repo root: The real DeepSeek adapter and key-backed agent demos read credentials from the environment or from a gitignored `.env` at the repo root:
```sh ```sh
DEEPSEEK_API_KEY=sk-... DEEPSEEK_API_KEY=sk-...
@@ -118,13 +118,13 @@ The echo demo does not need API credentials:
pnpm run demo:echo pnpm run demo:echo
``` ```
The coding-agent demo uses the real DeepSeek adapter and needs `DEEPSEEK_API_KEY` in the environment or repo-root `.env`: The REPL agent demo uses the real DeepSeek adapter and needs `DEEPSEEK_API_KEY` in the environment or repo-root `.env`:
```sh ```sh
pnpm run demo:coding pnpm run demo:repl
``` ```
The ACP server demo exposes the same coding agent over JSON-RPC stdio and also needs `DEEPSEEK_API_KEY`: The ACP server agent demo exposes the agent over JSON-RPC stdio and also needs `DEEPSEEK_API_KEY`:
```sh ```sh
pnpm run demo:acp pnpm run demo:acp

10
docs/development.zh.md
View File

@@ -9,7 +9,7 @@
- Node.js 24 或更新版本。仓库声明 `node >=24`；CI 在 Node 24 和 26 上跑矩阵。 - Node.js 24 或更新版本。仓库声明 `node >=24`；CI 在 Node 24 和 26 上跑矩阵。
- 启用了 Corepack 的 pnpm。仓库在 `package.json` 中钉住 `pnpm@11.7.0`；如果 `pnpm --version` 无法通过 Corepack 解析，先运行 `corepack enable`。 - 启用了 Corepack 的 pnpm。仓库在 `package.json` 中钉住 `pnpm@11.7.0`；如果 `pnpm --version` 无法通过 Corepack 解析，先运行 `corepack enable`。
- Git。 - Git。
- 可选：一个 DeepSeek API key，用于 coding-agent 演示和真实 API 的 e2e 测试。 - 可选：一个 DeepSeek API key，用于 REPL/ACP agent（智能体）演示和真实 API 的 e2e 测试。
## 首次搭建 ## 首次搭建
@@ -45,7 +45,7 @@ pnpm run build
## 环境变量 ## 环境变量
真实的 DeepSeek 适配器和 coding-agent 演示从环境变量或仓库根目录一个被 gitignore 的 `.env` 读取凭证： 真实的 DeepSeek 适配器和需要密钥的 agent 演示从环境变量或仓库根目录一个被 gitignore 的 `.env` 读取凭证：
```sh ```sh
DEEPSEEK_API_KEY=sk-... DEEPSEEK_API_KEY=sk-...
@@ -118,13 +118,13 @@ echo 演示不需要 API 凭证：
pnpm run demo:echo pnpm run demo:echo
``` ```
coding-agent 演示使用真实的 DeepSeek 适配器，需要环境变量或仓库根目录 `.env` 中的 `DEEPSEEK_API_KEY`： REPL agent 演示使用真实的 DeepSeek 适配器，需要环境变量或仓库根目录 `.env` 中的 `DEEPSEEK_API_KEY`：
```sh ```sh
pnpm run demo:coding pnpm run demo:repl
``` ```
ACP 服务器演示把同一个编码 agent（智能体）通过 JSON-RPC stdio 暴露出来，同样需要 `DEEPSEEK_API_KEY`： ACP 服务器 agent 演示通过 JSON-RPC stdio 暴露 agent，同样需要 `DEEPSEEK_API_KEY`：
```sh ```sh
pnpm run demo:acp pnpm run demo:acp

2
docs/rfc/implemented/architecture/2026-06-20-extract-example-app-packages.md
View File

@@ -37,7 +37,7 @@ The old `base*.yml`/`acp-tail.yml` includes already deduped the *config*, but a
## Verification ## Verification
- Each example directory is `cordis.yml` (+ the acp `cordis.snapshot.yml`) + `README.md` + tests only — no `start.ts`, no infra preamble; `base.yml`/`base-core.yml`/`acp-tail.yml` are gone. - Each example directory is `cordis.yml` (+ the acp `cordis.snapshot.yml`) + `README.md` + tests only — no `start.ts`, no infra preamble; `base.yml`/`base-core.yml`/`acp-tail.yml` are gone.
- `demo:echo` / `demo:coding` / `demo:acp` run via the app-package `bin`s. - `demo:echo` / `demo:repl` / `demo:acp` run via the app-package `bin`s.
- The new packages carry the per-file 100% coverage gate and a README like every `@deepseek-ai/dsh-*`. Each app package has a keyless **real-load-path** smoke that boots it through its `bin` + the cordis Loader (not a hand-built `ctx.plugin({...})` mount), guarding the `unwrapExports` export-shape bug class ([postmortem 0001](../../../postmortem/0001-acp-default-export-drops-inject.md)). - The new packages carry the per-file 100% coverage gate and a README like every `@deepseek-ai/dsh-*`. Each app package has a keyless **real-load-path** smoke that boots it through its `bin` + the cordis Loader (not a hand-built `ctx.plugin({...})` mount), guarding the `unwrapExports` export-shape bug class ([postmortem 0001](../../../postmortem/0001-acp-default-export-drops-inject.md)).
- The ACP snapshot **replay** transcript is unchanged: the boot restructuring preserved the plugin set + load order, so `pnpm run test:snapshot` stays green against the committed goldens with no re-record. - The ACP snapshot **replay** transcript is unchanged: the boot restructuring preserved the plugin set + load order, so `pnpm run test:snapshot` stays green against the committed goldens with no re-record.

6
examples/README.md
View File

@@ -15,12 +15,12 @@ Run with: `pnpm run demo:echo`. When prompted, type "echo <something>" to trigge
## coding-agent ## coding-agent
The real thing: DeepSeek V4 + the `read`/`write`/`edit` filesystem tools + the bash tool suite, `subagent` delegation, and the `todo_write` task tracker on the same `@deepseek-ai/dsh-stdio-agent` app. Where echo-agent proves the skeleton with mocks, this is a usable coding assistant. A REPL agent demo: DeepSeek V4 + the `read`/`write`/`edit` filesystem tools + the bash tool suite, `subagent` delegation, and the `todo_write` task tracker on the same `@deepseek-ai/dsh-stdio-agent` app. The UI is a terminal readline REPL.
Run with: `pnpm run demo:coding` (needs `DEEPSEEK_API_KEY` in the environment or a gitignored repo-root `.env`). See [coding-agent/README.md](coding-agent/README.md) for details. Run with: `pnpm run demo:repl` (needs `DEEPSEEK_API_KEY` in the environment or a gitignored repo-root `.env`). See [coding-agent/README.md](coding-agent/README.md) for details.
## acp-agent ## acp-agent
The same coding agent exposed as an **Agent Client Protocol (ACP)** server over JSON-RPC stdio, via the [`@deepseek-ai/dsh-acp-agent`](../packages/ui/acp-agent) app — drive it from Zed or any other ACP client. Also the home of the keyless snapshot tests. An agent demo exposed as an **Agent Client Protocol (ACP)** server over JSON-RPC stdio, via the [`@deepseek-ai/dsh-acp-agent`](../packages/ui/acp-agent) app — drive it from Zed or any other ACP client. Also the home of the keyless snapshot tests.
Run with: `pnpm run demo:acp` (needs `DEEPSEEK_API_KEY`). See [acp-agent/README.md](acp-agent/README.md) for the Zed setup and the snapshot-test design. Run with: `pnpm run demo:acp` (needs `DEEPSEEK_API_KEY`). See [acp-agent/README.md](acp-agent/README.md) for the Zed setup and the snapshot-test design.

2
examples/acp-agent/README.md
View File

@@ -1,6 +1,6 @@
# acp-agent example # acp-agent example
The DeepSeek Harness coding agent exposed as an **Agent Client Protocol (ACP)** server over JSON-RPC stdio — drive it from Zed or any other ACP client. The DeepSeek Harness agent demo exposed as an **Agent Client Protocol (ACP)** server over JSON-RPC stdio — drive it from Zed or any other ACP client.
```sh ```sh
pnpm run demo:acp # needs DEEPSEEK_API_KEY (repo-root .env or env) pnpm run demo:acp # needs DEEPSEEK_API_KEY (repo-root .env or env)

2
examples/acp-agent/package.json
View File

@@ -1,6 +1,6 @@
{ {
"name": "acp-agent-example", "name": "acp-agent-example",
"description": "Runnable demo: the coding agent as an ACP server over JSON-RPC stdio (Zed & other ACP editors)", "description": "Runnable demo: an agent as an ACP server over JSON-RPC stdio (Zed & other ACP editors)",
"private": true, "private": true,
"version": "0.0.1", "version": "0.0.1",
"type": "module" "type": "module"

8
examples/coding-agent/README.md
View File

@@ -1,6 +1,6 @@
# coding-agent # coding-agent
The real stdio coding-agent wiring: DeepSeek V4 + the `read`/`write`/`edit` filesystem tools + the bash tool suite + subagent delegation + `todo_write` + stdio chat + JSONL persistence, loaded from `cordis.yml`. Where echo-agent proves the skeleton with mocks, this example is a usable coding assistant. The REPL agent demo wiring: DeepSeek V4 + the `read`/`write`/`edit` filesystem tools + the bash tool suite + subagent delegation + `todo_write` + stdio chat + JSONL persistence, loaded from `cordis.yml`. The UI is a terminal readline REPL.
## Run it ## Run it
@@ -8,7 +8,7 @@ The real stdio coding-agent wiring: DeepSeek V4 + the `read`/`write`/`edit` file
# repo root .env (gitignored) or exported env: # repo root .env (gitignored) or exported env:
# DEEPSEEK_API_KEY=sk-… # DEEPSEEK_API_KEY=sk-…
# DEEPSEEK_BASE_URL=https://… # optional; defaults to the public API # DEEPSEEK_BASE_URL=https://… # optional; defaults to the public API
pnpm run demo:coding pnpm run demo:repl
``` ```
Type a coding task. The agent works through the `read`/`write`/`edit` filesystem tools for ordinary file operations and `bash` (+ `bash_output` / `bash_kill` for background tasks) for shell commands, searches, and test runs, each in a fresh `bash -c` (the system prompt tells the model to pass `workdir` instead of `cd`). Both the fs tools and bash resolve relative paths against the session workspace. It can also delegate with `subagent`/`subagent_fork` and track multi-step work with `todo_write` (a whole-list task tracker rendered as a checklist). Reasoning streams dimmed; tool calls/results render inline. Type a coding task. The agent works through the `read`/`write`/`edit` filesystem tools for ordinary file operations and `bash` (+ `bash_output` / `bash_kill` for background tasks) for shell commands, searches, and test runs, each in a fresh `bash -c` (the system prompt tells the model to pass `workdir` instead of `cd`). Both the fs tools and bash resolve relative paths against the session workspace. It can also delegate with `subagent`/`subagent_fork` and track multi-step work with `todo_write` (a whole-list task tracker rendered as a checklist). Reasoning streams dimmed; tool calls/results render inline.
@@ -26,7 +26,7 @@ Type a coding task. The agent works through the `read`/`write`/`edit` filesystem
Each run starts a fresh session by default (its event log lands under `./.sessions/`). To **continue** a previous conversation, set `RESUME_SESSION_ID` to that session's id — the `main` agent then rehydrates the persisted log instead of starting fresh, so the model sees the earlier turns as history: Each run starts a fresh session by default (its event log lands under `./.sessions/`). To **continue** a previous conversation, set `RESUME_SESSION_ID` to that session's id — the `main` agent then rehydrates the persisted log instead of starting fresh, so the model sees the earlier turns as history:
```sh ```sh
RESUME_SESSION_ID=<prior-session-id> pnpm run demo:coding RESUME_SESSION_ID=<prior-session-id> pnpm run demo:repl
``` ```
The id is wired through `cordis.yml` (`resumeSessionId: !!js process.env.RESUME_SESSION_ID`); unset, the agent starts a new session. A missing/unreadable id is non-fatal — it logs a warning and starts no `main` agent. The id is wired through `cordis.yml` (`resumeSessionId: !!js process.env.RESUME_SESSION_ID`); unset, the agent starts a new session. A missing/unreadable id is non-fatal — it logs a warning and starts no `main` agent.
@@ -37,7 +37,7 @@ This example is a thin leaf `cordis.yml`: it picks the swappable backends, loads
| Entry | Demonstrates | | Entry | Demonstrates |
|---|---| |---|---|
| `hmr` (`@cordisjs/plugin-hmr`) | the dev/demo edit-reload loop — a **leaf** entry (not baked into the app) because it is Loader-only and needs `node --expose-internals`, which `demo:coding` passes | | `hmr` (`@cordisjs/plugin-hmr`) | the dev/demo edit-reload loop — a **leaf** entry (not baked into the app) because it is Loader-only and needs `node --expose-internals`, which `demo:repl` passes |
| `llm-deepseek` | real `LlmAdapter` via config (`!!js process.env.…` secrets); swap one line to `@deepseek-ai/dsh-llm-pi-ai` for the library-backed twin | | `llm-deepseek` | real `LlmAdapter` via config (`!!js process.env.…` secrets); swap one line to `@deepseek-ai/dsh-llm-pi-ai` for the library-backed twin |
| `bash` (`dsh-bash-local`) | the executor implementation — the swappable half of the bash seam. The model-facing `bash`/`bash_output`/`bash_kill` tool schemas (`tool-bash`) come from `agent-core`, so only the executor is a leaf choice | | `bash` (`dsh-bash-local`) | the executor implementation — the swappable half of the bash seam. The model-facing `bash`/`bash_output`/`bash_kill` tool schemas (`tool-bash`) come from `agent-core`, so only the executor is a leaf choice |
| `stdio-agent` (`@deepseek-ai/dsh-stdio-agent`) | the app bundle: the agent-core spine + console logger + JSONL persistence + readline UI + a pre-created `main` agent. Its config carries the model, system prompt, `persistenceRoot` (`./.sessions`), and `resumeSessionId` — so persistence and the agent are configured here, not wired as separate leaf plugins | | `stdio-agent` (`@deepseek-ai/dsh-stdio-agent`) | the app bundle: the agent-core spine + console logger + JSONL persistence + readline UI + a pre-created `main` agent. Its config carries the model, system prompt, `persistenceRoot` (`./.sessions`), and `resumeSessionId` — so persistence and the agent are configured here, not wired as separate leaf plugins |

8
examples/coding-agent/cordis.yml
View File

@@ -1,4 +1,4 @@
# The coding-agent plugin tree: the real coding agent. The two swappable # The coding-agent plugin tree: the REPL agent demo. The two swappable
# backends — the DeepSeek adapter and the local bash executor — plus `hmr` for # backends — the DeepSeek adapter and the local bash executor — plus `hmr` for
# the dev/demo reload loop, then the stdio chat app (@deepseek-ai/dsh-stdio- # the dev/demo reload loop, then the stdio chat app (@deepseek-ai/dsh-stdio-
# agent), which bundles the whole agent-core spine (timer, llm, sessions, # agent), which bundles the whole agent-core spine (timer, llm, sessions,
@@ -6,7 +6,7 @@
# logger, JSONL persistence, the readline UI, and a pre-created `main` agent. # logger, JSONL persistence, the readline UI, and a pre-created `main` agent.
# #
# `hmr` is a leaf entry (not baked into dsh-stdio-agent): it is a Loader-only # `hmr` is a leaf entry (not baked into dsh-stdio-agent): it is a Loader-only
# dev plugin that needs `--expose-internals` — the `demo:coding` script passes # dev plugin that needs `--expose-internals` — the `demo:repl` script passes
# it. Requires DEEPSEEK_API_KEY (and optionally DEEPSEEK_BASE_URL) in the # it. Requires DEEPSEEK_API_KEY (and optionally DEEPSEEK_BASE_URL) in the
# environment — the dsh-stdio-agent bin loads the gitignored repo-root .env # environment — the dsh-stdio-agent bin loads the gitignored repo-root .env
# first. cordis.yml reads them via the `!!js` tag. # first. cordis.yml reads them via the `!!js` tag.
@@ -37,7 +37,7 @@
timeoutMs: 60000 timeoutMs: 60000
# The stdio chat app: the whole spine + front-door cluster, configured for a # The stdio chat app: the whole spine + front-door cluster, configured for a
# real coding agent driving a pre-created `main` agent. # REPL agent demo driving a pre-created `main` agent.
- id: stdio-agent - id: stdio-agent
name: '@deepseek-ai/dsh-stdio-agent' name: '@deepseek-ai/dsh-stdio-agent'
config: config:
@@ -46,7 +46,7 @@
# under ./.sessions); unset starts a fresh session each run. # under ./.sessions); unset starts a fresh session each run.
resumeSessionId: !!js process.env.RESUME_SESSION_ID resumeSessionId: !!js process.env.RESUME_SESSION_ID
persistenceRoot: './.sessions' persistenceRoot: './.sessions'
welcome: 'coding-agent ready. Give it a coding task (its tools are read, write, edit, bash, subagent, and todo_write).' welcome: 'agent REPL ready. Give it a coding task (its tools are read, write, edit, bash, subagent, and todo_write).'
systemPrompt: | systemPrompt: |
You are coding-agent, a CLI coding assistant. You are coding-agent, a CLI coding assistant.

2
examples/coding-agent/package.json
View File

@@ -3,5 +3,5 @@
"private": true, "private": true,
"version": "0.0.1", "version": "0.0.1",
"type": "module", "type": "module",
"description": "Runnable demo: a real coding agent — DeepSeek V4 + the bash tool suite" "description": "Runnable demo: an agent REPL UI with DeepSeek V4 and coding tools"
} }

6
examples/coding-agent/tests/keyless-smoke.e2e.ts
View File

@@ -24,7 +24,7 @@ import { afterEach, describe, expect, it } from 'vitest'
* product. * product.
*/ */
// The dsh-stdio-agent bin (the demo:coding entry) and this example's cordis.yml. // The dsh-stdio-agent bin (the demo:repl entry) and this example's cordis.yml.
// The bin resolves its config-path arg from CWD; the test spawns from a temp // The bin resolves its config-path arg from CWD; the test spawns from a temp
// cwd, so we pass the example config's ABSOLUTE path. // cwd, so we pass the example config's ABSOLUTE path.
const binScript = fileURLToPath(new URL('../../../packages/ui/stdio-agent/src/bin.ts', import.meta.url)) const binScript = fileURLToPath(new URL('../../../packages/ui/stdio-agent/src/bin.ts', import.meta.url))
@@ -51,7 +51,7 @@ async function bootAndEof(): Promise<{ stdout: string; code: number }> {
return new Promise((resolve, reject) => { return new Promise((resolve, reject) => {
const proc = spawn( const proc = spawn(
process.execPath, process.execPath,
// --expose-internals: cordis.yml loads the HMR plugin (mirrors demo:coding). // --expose-internals: cordis.yml loads the HMR plugin (mirrors demo:repl).
['--expose-internals', '--import', tsxLoader, binScript, configPath], ['--expose-internals', '--import', tsxLoader, binScript, configPath],
{ {
cwd, cwd,
@@ -94,6 +94,6 @@ describe('coding-agent keyless smoke (real cordis.yml via the Loader)', () => {
it('boots the full plugin tree, prints its banner, and exits cleanly on EOF', async () => { it('boots the full plugin tree, prints its banner, and exits cleanly on EOF', async () => {
const { stdout, code } = await bootAndEof() const { stdout, code } = await bootAndEof()
expect(code).toBe(0) expect(code).toBe(0)
expect(stdout).toContain('coding-agent ready.') expect(stdout).toContain('agent REPL ready.')
}, 15_000) }, 15_000)
}) })

2
package.json
View File

@@ -43,7 +43,7 @@
"doc-sync": "pnpm run doc-typecheck && pnpm run verify-cordis-catalog && pnpm run verify-tool-catalog && pnpm run verify-md-wrap && pnpm run verify-md-links && pnpm run verify-doc-refs && pnpm run verify-package-paths && pnpm run verify-rfc-classification && pnpm run verify-type-equiv && pnpm run verify-translation-pairing", "doc-sync": "pnpm run doc-typecheck && pnpm run verify-cordis-catalog && pnpm run verify-tool-catalog && pnpm run verify-md-wrap && pnpm run verify-md-links && pnpm run verify-doc-refs && pnpm run verify-package-paths && pnpm run verify-rfc-classification && pnpm run verify-type-equiv && pnpm run verify-translation-pairing",
"hygiene": "pnpm run knip && pnpm run publint && pnpm run constraints && pnpm run verify-node-next-types", "hygiene": "pnpm run knip && pnpm run publint && pnpm run constraints && pnpm run verify-node-next-types",
"demo:echo": "node --expose-internals --import tsx packages/ui/stdio-agent/src/bin.ts examples/echo-agent/cordis.yml", "demo:echo": "node --expose-internals --import tsx packages/ui/stdio-agent/src/bin.ts examples/echo-agent/cordis.yml",
"demo:coding": "node --expose-internals --import tsx packages/ui/stdio-agent/src/bin.ts examples/coding-agent/cordis.yml", "demo:repl": "node --expose-internals --import tsx packages/ui/stdio-agent/src/bin.ts examples/coding-agent/cordis.yml",
"demo:acp": "node --import tsx packages/ui/acp-agent/src/bin.ts examples/acp-agent/cordis.yml", "demo:acp": "node --import tsx packages/ui/acp-agent/src/bin.ts examples/acp-agent/cordis.yml",
"postinstall": "node scripts/install-lefthook.mjs" "postinstall": "node scripts/install-lefthook.mjs"
}, },

2
packages/support/ui-stdio/README.md
View File

@@ -15,7 +15,7 @@ This package consolidates what were two near-identical copies under `examples/ec
- id: ui-stdio - id: ui-stdio
name: '@deepseek-ai/dsh-ui-stdio' name: '@deepseek-ai/dsh-ui-stdio'
config: config:
welcome: 'coding-agent ready. Give it a coding task.' welcome: 'agent REPL ready. Give it a coding task.'
``` ```
## Rendering ## Rendering

6
packages/ui/stdio-agent/README.md
View File

@@ -15,7 +15,7 @@ A terminal chat always wants the same cluster, so the package owns it rather tha
| `@deepseek-ai/dsh-session-persistence-jsonl` | durable JSONL session log under `persistenceRoot` | | `@deepseek-ai/dsh-session-persistence-jsonl` | durable JSONL session log under `persistenceRoot` |
| `@deepseek-ai/dsh-ui-stdio` | the readline UI, bound to the `main` agent | | `@deepseek-ai/dsh-ui-stdio` | the readline UI, bound to the `main` agent |
`@cordisjs/plugin-hmr` (the dev/demo edit-reload loop) is deliberately a **leaf** entry, NOT baked in here: it is a Loader-only, subprocess-only dev plugin — its constructor throws without `node --expose-internals` + a live `loader`, and the in-process test tier cannot even import it (so a package whose `apply` statically pulled it in could never carry the per-file coverage gate). Unlike the console logger, a stray `hmr` is not a stdout-purity footgun, so leaving it at the leaf costs no safety. The `demo:echo` / `demo:coding` leaves load it and pass `--expose-internals`. `@cordisjs/plugin-hmr` (the dev/demo edit-reload loop) is deliberately a **leaf** entry, NOT baked in here: it is a Loader-only, subprocess-only dev plugin — its constructor throws without `node --expose-internals` + a live `loader`, and the in-process test tier cannot even import it (so a package whose `apply` statically pulled it in could never carry the per-file coverage gate). Unlike the console logger, a stray `hmr` is not a stdout-purity footgun, so leaving it at the leaf costs no safety. The `demo:echo` / `demo:repl` leaves load it and pass `--expose-internals`.
The leaf `cordis.yml` supplies only the **swappable backends** — an LLM adapter (`llm-deepseek` for the real model, or the mock `mock-llm` for a demo) and a bash executor (`bash-local`) — `hmr`, plus this app's [`Config`](#config). The whole plugin tree a run loads is therefore: this app's cluster, the spine inside `agent-core`, `hmr`, and the two leaf backends. The leaf `cordis.yml` supplies only the **swappable backends** — an LLM adapter (`llm-deepseek` for the real model, or the mock `mock-llm` for a demo) and a bash executor (`bash-local`) — `hmr`, plus this app's [`Config`](#config). The whole plugin tree a run loads is therefore: this app's cluster, the spine inside `agent-core`, `hmr`, and the two leaf backends.
@@ -31,12 +31,12 @@ The leaf `cordis.yml` supplies only the **swappable backends** — an LLM adapte
## The bin ## The bin
`dsh-stdio-agent [path-to-cordis.yml]` (default `./cordis.yml`) loads a gitignored `.env` from the cwd (`DEEPSEEK_API_KEY` / `DEEPSEEK_BASE_URL`), then drives the cordis Loader against the config and awaits the whole plugin tree before returning. Run it under `node --expose-internals`: the cordis Loader resolves the config's bare plugin specifiers (`@deepseek-ai/dsh-*`, npm packages) through its internal module loader, which is only active under that flag. The `demo:echo` / `demo:coding` scripts invoke it that way. `dsh-stdio-agent [path-to-cordis.yml]` (default `./cordis.yml`) loads a gitignored `.env` from the cwd (`DEEPSEEK_API_KEY` / `DEEPSEEK_BASE_URL`), then drives the cordis Loader against the config and awaits the whole plugin tree before returning. Run it under `node --expose-internals`: the cordis Loader resolves the config's bare plugin specifiers (`@deepseek-ai/dsh-*`, npm packages) through its internal module loader, which is only active under that flag. The `demo:echo` / `demo:repl` scripts invoke it that way.
## Example leaf `cordis.yml` ## Example leaf `cordis.yml`
```yaml ```yaml
# A real coding agent: hmr + the DeepSeek adapter + local bash, then this app. # A REPL agent demo: hmr + the DeepSeek adapter + local bash, then this app.
- id: hmr - id: hmr
name: '@cordisjs/plugin-hmr' name: '@cordisjs/plugin-hmr'
config: config:

4
packages/ui/stdio-agent/src/bin.ts
View File

@@ -6,7 +6,7 @@
* duplicated in their `start.ts`: load the gitignored repo-root `.env`, then * duplicated in their `start.ts`: load the gitignored repo-root `.env`, then
* drive the cordis Loader against the config path (default `./cordis.yml`). * drive the cordis Loader against the config path (default `./cordis.yml`).
* *
* Usage: `dsh-stdio-agent [path-to-cordis.yml]`. The `demo:echo` / `demo:coding` * Usage: `dsh-stdio-agent [path-to-cordis.yml]`. The `demo:echo` / `demo:repl`
* scripts invoke it with the example's config. * scripts invoke it with the example's config.
* *
* @module @deepseek-ai/dsh-stdio-agent/bin * @module @deepseek-ai/dsh-stdio-agent/bin
@@ -105,7 +105,7 @@ function assertEntriesLoaded(ctx: Context): void {
* *
* Bare plugin specifiers in the config (`@deepseek-ai/dsh-*`, npm packages) are * Bare plugin specifiers in the config (`@deepseek-ai/dsh-*`, npm packages) are
* resolved by the cordis Loader's internal module loader, which is only active * resolved by the cordis Loader's internal module loader, which is only active
* under `node --expose-internals` (the flag the `demo:echo`/`demo:coding` scripts * under `node --expose-internals` (the flag the `demo:echo`/`demo:repl` scripts
* pass). Without it the Loader falls back to resolving relative to its own module * pass). Without it the Loader falls back to resolving relative to its own module
* and cannot find the config's plugins, so a consumer running the built bin must * and cannot find the config's plugins, so a consumer running the built bin must
* pass `--expose-internals` (or install the plugins where node hoists them). * pass `--expose-internals` (or install the plugins where node hoists them).