# codebuddy-first-bridge [简体中文](README.md) · **English** > A Cordis plugin for the **DeepSeek Harness (DSH)** that makes the model **prefer the local `codebuddy` CLI** (Tencent CodeBuddy Code) for real work (coding, builds, debugging, multi-file investigation) across **every mode**. DSH stays fully in control of codebuddy (`--permission-mode bypassPermissions`, so codebuddy never prompts). When codebuddy is **rate-limited or the network is down**, it pops a confirmation dialog asking whether to fall back to the **DSH local API config**, and it shows a **live status light** in the session header indicating whether codebuddy is currently working. ![codebuddy status light states](assets/indicator-states.svg) --- ## What it is `codebuddy-first-bridge` contributes two things to a running DSH session: 1. **Three model tools** — `codebuddy_run`, `codebuddy_continue` and `codebuddy_status`, which hand tasks to the local `codebuddy` CLI. 2. **An codebuddy-first policy prompt section** — instructs the model to prefer codebuddy for real work in **all modes** (normal / plan / accept-edits / subagent / workflow / ralph / goal rounds); native tools are reserved for read-only lookups and final verification. On top of that it implements the key capabilities that motivated the project: - **Four backends:** `codebuddy` (domestic npm CLI, default), `codebuddy-intl` (the **international face of that same npm CLI** — `product.ioa.json` catalogue; aliases `codebuddy-ioa` / `codebuddy-international` / `codebuddy-oversea`), `codebuddy-en` (WorkBuddy international desktop CLI; needs a `codebuddyEnToken`) and `workbuddy` (WorkBuddy domestic desktop CLI, zero config). `codebuddy-intl` and `codebuddy-en` are two **distinct** options. Endpoints align automatically to each product's login domain. Sessions route back to their owning backend automatically; the plugin settings let the user pick the preferred CLI, a default model and the international token. Model candidates are read **at runtime** from each install's own product descriptor (v1.4.0+), falling back to a built-in measured list. - **Fallback mechanism (confirmation dialog):** when codebuddy looks rate-limited or the network is unreachable, a dialog pops up offering *"use the DSH local API config (fall back)" / "retry codebuddy once" / "do not fall back"*. - **Live status lights (per project, start-up persistent):** coloured indicators on the right of the browser session header — **one per project (working directory)** — reflecting each project's codebuddy activity in real time (working / ok / failed / fallback); hovering shows the step that project's codebuddy is currently executing. The light is a **home-level plugin** ([`home-plugin/codebuddy-indicator/`](home-plugin/codebuddy-indicator/), registered via `cordis.patch.yml`): it loads automatically with DSH, appears in **every session**, and needs **no approval**. - **Live observation (`codebuddy_status`):** the `codebuddy_status` tool returns a snapshot of what codebuddy is doing RIGHT NOW, sectioned per project — each project's current step (tool name + arguments, or thinking/typing), recent step trail, last completed run. Optional `cwd` filters to one project. Callable mid-flight, no waiting. ## Four forms The same logic ships in four forms; pick per need: | Form | Location | Capabilities | Survives restart | Status light | | --- | --- | --- | --- | --- | | **Persistent agent preset** (recommended) | [`preset/codebuddy-first/`](preset/codebuddy-first/) | tools + policy + fallback dialog + `codebuddy_status` | ✅ yes (persisted preset) | ❌ no (host-plane composition has no browser UI) | | **Home-level status-light plugin** (start-up persistent) | [`home-plugin/codebuddy-indicator/`](home-plugin/codebuddy-indicator/) | status light (every session, no approval) | ✅ yes (cordis.patch.yml) | ✅ yes | | **Dynamic Cordis plugin** (in-session) | [`dynamic/`](dynamic/) | tools + policy + fallback dialog + **status light** + `codebuddy_status` | ❌ no (process-local) | ✅ yes (one-time approval) | | **MCP server** (any MCP host) | [`mcp/`](mcp/) | `codebuddy_run` / `codebuddy_continue` / `codebuddy_status` auto-discovered via `tools/list` by Claude Code, Codex, Cherry Studio, … | ✅ yes (registered in client config) | ❌ no | > **Why does the status light need a home-level plugin?** An agent preset is a **host-plane** composition (`agent.cordis.yml` mounts host plugins), and its `.mjs` runs only on the Node side, so it inherently has no browser UI. The live status light is a **client-plane** (browser Slot) component. A **home-level plugin** (registered via `cordis.patch.yml`, e.g. [`home-plugin/codebuddy-indicator/`](home-plugin/codebuddy-indicator/)) provides both a host half (collecting codebuddy status pushed by each session + an HTTP route) and a client half (the browser poll-and-render light), so it loads with DSH, appears in every session and needs no approval. The dynamic form (one-time GUI approval) and the home-level light coexist: both feed the home-level collector (the dynamic form via `codebuddyCollector.mergeSnapshot`, the preset form via `ctx.emit('codebuddy/status')` events). > > The fallback dialog is a host-side capability and is present in **both** the preset and dynamic forms. The MCP form has no UI; on rate-limit it appends a "don't loop-retry" note to the result text and lets the calling agent decide. See [docs/en/ARCHITECTURE.md](docs/en/ARCHITECTURE.md). ## Quick start ### Option A: install as a persistent agent preset (recommended) > **From v1.2.0 we recommend installing Option B alongside** (`dsh plugin --profile web add codebuddy-first-bridge`): Option A's registration channel is now carried by the status-light plugin — on new DSH (≥ 0.1.7-alpha.1) the preset is registered automatically into the `agentPresets` registry by the indicator (declarative presets), while old DSH (≤ 0.1.6-alpha.2) keeps using the directory-based install below. Either way, installing Option B alone makes the preset available out of the box. Copy the whole `preset/codebuddy-first/` directory into your DSH user preset root (**only needed on dsh ≤ 0.1.6-alpha.2**; from 0.1.7-alpha.1 the `.agent-presets` directory is no longer read — the preset is declared by the Option B indicator plugin instead): ``` ${DSH_HOME:-$HOME/.dsh}/.agent-presets/codebuddy-first/ ``` Windows example (this repo's dev environment): ```powershell Copy-Item -Recurse .\preset\codebuddy-first "$env:DSH_HOME\.agent-presets\codebuddy-first" ``` Then start a new DSH session and select the preset named **`CodeBuddy-First 执行代理`** (id: `codebuddy-first`). It inherits everything from the `standard` preset and adds the `codebuddy_run` / `codebuddy_continue` / `codebuddy_status` tools, the codebuddy-first policy, and the rate-limit/network fallback dialog. > ⚠️ **Do not** edit the shipped `agent-presets` install that ships with the deployment (an upgrade overwrites it). Always install under your **user** preset root as a separate subdirectory. Full steps and validation are in [docs/en/INSTALL.md](docs/en/INSTALL.md). ### Option B: install the home-level status-light plugin (start-up persistent, every session) **Standard install (recommended, v1.1.7+)** — the home-level light is bundled into the main package `codebuddy-first-bridge` (its `dsh.bundle.patch` points at the indicator's bundle patch layer), so a single command installs it: ```powershell dsh plugin --profile web add codebuddy-first-bridge ``` The DSH plugin system mounts the home-level light automatically after installing the main package: the host half resolves the bare package name to `main → lib/index.mjs`, and the client half is auto-registered in the browser roster via the `dsh.client` declaration — no manual copy, no junctions, no `cordis.patch.yml` edits. **Legacy manual install (kept for reference)**: ```powershell # 1) copy the plugin source $dshHome = "$env:APPDATA\DSH Desktop\dsh-home" Copy-Item -Recurse .\home-plugin\codebuddy-indicator "$dshHome\plugins\codebuddy-indicator" # 2) create junctions (needed by both host resolution and the browser roster; 3 in total) New-Item -ItemType Junction -Path "$dshHome\node_modules\codebuddy-indicator" -Target "$dshHome\plugins\codebuddy-indicator" New-Item -ItemType Junction -Path "$dshHome\profiles\node_modules\codebuddy-indicator" -Target "$dshHome\plugins\codebuddy-indicator" New-Item -ItemType Junction -Path "$dshHome\profiles\web\node_modules\codebuddy-indicator" -Target "$dshHome\plugins\codebuddy-indicator" # 3) append one row to cordis.patch.yml (bare name resolves via junction to lib/index.mjs): # - insert: # - id: codebuddy-indicator # name: codebuddy-indicator ``` Pair it with the **preset form** (Option A): the preset's `codebuddy-first-bridge.mjs` emits `ctx.emit('codebuddy/status')` on every state change, which the home-level collector merges and the light renders. After editing `lib/index.mjs`, restart DSH (or temporarily switch to `name: codebuddy-indicator?v=N` to hot-reload); after editing `lib/client.js`, refresh the browser. ### Option C: run as a dynamic Cordis plugin (with the status light) In a DSH session that has Cordis capabilities loaded, define and activate the plugin with `cordis_define` + `cordis_run`, using [`dynamic/host.js`](dynamic/host.js) for the host half and [`dynamic/client.js`](dynamic/client.js) for the client half. The first time the client half runs, the DSH GUI asks for a one-time approval; once granted, the status light appears in the session header. ## Requirements - **DeepSeek Harness (DSH)** with the needed host services mounted: `tools`, `subprocess`, `systemPrompt`, `timer` (optional: `jobs`, `planMode`, `sandboxPolicy`, `userQuestions`). - A local **`codebuddy` CLI** (CodeBuddy Code, `npm i -g @tencent-ai/codebuddy-code`; verified against v2.143.0 during development). **No PATH requirement**: the bridge resolves `subprocess.resolveExecutable('codebuddy')` → `node + CODEBUDDY_BIN` → `node + %APPDATA%\npm\node_modules\@tencent-ai\codebuddy-code\bin\codebuddy`, so a plain npm global install is found. - Optional: the **WorkBuddy desktop app** (for `backend="workbuddy"` office dispatch; its CLI ships at `C:\Program Files\WorkBuddy\resources\app.asar.unpacked\cli\bin\codebuddy`, overridable via `WORKBUDDY_BIN`). Without it that backend returns an actionable error; the default codebuddy backend is unaffected. - Optional: an **international account**. **The two international faces are two distinct options (v1.4.0+)**: - `backend="codebuddy-intl"` (panel name "**CodeBuddy 国际版（npm CLI · 国际面）**"; aliases `codebuddy-ioa` / `codebuddy-international` / `codebuddy-oversea`) — the **international face of the same npm CLI** as `codebuddy` (`product.ioa.json` catalogue: `claude-sonnet-5`, `claude-opus-5`, `gemini-3.1-pro`, `gpt-6-astra`, `hy3-ioa`, …). Note that the international models are **gated server-side per account**: measured on the real machine, `--model claude-sonnet-5` returns `400 model [...] is only available for authorized users` while `--model hy4-preview` (domestic face) returns `PONG`. A domestic account therefore gets a clear authorization error rather than a confusing configuration failure. - `backend="codebuddy-en"` (panel name "**WorkBuddy 国际版（WorkBuddyAI 桌面 CLI）**"; aliases `workbuddy-en` / `workbuddy-ai` accepted since v1.3.3). The international edition is a **separate install** — the CLI bundled with the WorkBuddy AI desktop app (`C:\Program Files\WorkBuddyAI\resources\app.asar.unpacked\cli\bin\codebuddy`, overridable via `CODEBUDDY_EN_BIN`; v1.3.0 wrongly claimed it reuses the same npm CLI, disproven by the real machine's `product.json`). **Credentials are reused automatically, so no configuration is normally needed**: the international edition's own login token is sealed by the desktop app's protector key, which is delivered only over the sidecar channel and is **never written to disk**, so the headless CLI cannot read it (the CLI itself reports `category:"missing-key"`). The bridge therefore tries, in order: the **`codebuddyEnToken` setting → the `CODEBUDDY_AUTH_TOKEN` env var → the DSH credential store** (the `WORKBUDDY_TOKEN` pointing at `workbuddy.ai/v2` in `dsh-home`'s `.credentials.yaml` / `.env` — i.e. the key you already configured for DSH's workbuddy provider). Verified on the real machine: as long as a workbuddy key is configured in DSH, `codebuddy-en` works out of the box; only when all three channels are empty does it return `AUTH_REQUIRED` with guidance instead of a silent 401. For office scenarios, `backend="workbuddy"` (domestic desktop CLI, also zero config) is equally fine. - **Automatic endpoint alignment (v1.3.1):** before each call the bridge reads each product's `auth.domain` from its auth store (plaintext) and injects `CODEBUDDY_BASE_URL` — **only when the login domain differs from the product endpoint**. This fixes a pre-existing defect in the default `codebuddy` backend: the npm CLI's product endpoint is `www.codebuddy.ai` while the machine's login token domain is `www.codebuddy.cn`, so without the override it always 401s. No manual configuration is normally needed; use the `endpointOverride` setting to force one. - The DSH Web GUI (client plane) is additionally required for the status light. ## Tool usage `codebuddy_run(prompt, mode?, model?, effort?, maxTurns?, cwd?, addDirs?, timeoutSec?, background?, backend?)` - `backend`: **four-backend dispatch**. `codebuddy` (default — domestic CodeBuddy npm CLI, product endpoint `www.codebuddy.ai`, coding scenarios), `codebuddy-intl` (**CodeBuddy international** — the international face of that same npm CLI, `product.ioa.json` catalogue; aliases `codebuddy-ioa` / `codebuddy-international` / `codebuddy-oversea`; the international models are gated server-side per account), `codebuddy-en` (WorkBuddy international desktop CLI, product endpoint `www.workbuddy.ai`; requires `codebuddyEnToken`), `workbuddy` (WorkBuddy domestic desktop CLI, product endpoint `copilot.tencent.com`, zero config; office face: documents/slides/spreadsheets, knowledge-base lookups, image/video generation, WeChat/WeCom replies). `codebuddy-intl` and `codebuddy-en` are **two distinct options**. Sessions are archived per backend (each product face's login is exclusive); `codebuddy_continue` routes back to the backend owning the sessionId automatically — an explicit `backend` always wins, and new calls without history follow the **user-preferred default backend** (plugin settings). - `mode`: `auto` (default — follows DSH plan state, choosing `plan`/`accept-edits`), `plan`, `accept-edits`. - `model`: optional model id; when omitted, the **user-preferred default model** (plugin settings, if set) applies, otherwise the CLI-configured default. **Every id carries its multiplier and any live promotion** (`hy3 - free - limited-time free`, `hy4-preview - x0.29 - free at night`), and the settings panel adds a five-row summary (free / priced / unrated / promotions / unauthorized) so cost is easy to judge. **Which layer the data comes from** (fixed in v1.6.1 - the real root cause of the repeatedly wrong model lists): model data has **three layers**, and only layer 1 was ever read before. | Layer | Location | Notes | |---|---|---| | 1. product-face defaults | install dir `product.${env}.json` / `product.json` | factory catalogue only, **carries no promotions** | | 2. account-level config | `cache/acc-product-config-v3.json` under `~/.workbuddy`, `~/.workbuddy-ai` | account-specific, **contains `modelPromotions`** | | 3. client live snapshot | `local_storage/entry_*.info` in the same folder | **exactly what the user menu renders** | Resolution falls back 2 then 3 then 1, **field by field** (multipliers and promotions may come from different files). Two traps: `entry_*.info` is a top-level `[{userId, data}, ...]` **array** (a single file can hold several accounts; the last entry is the newest) while `cache/` holds a bare object; and an international `cache/` file can be **badly stale** (37 entries, no promotions, and neither `hy4-preview` nor `deepseek-v4.1-flash` here) yet sit first in the chain, shadowing the newer `local_storage` snapshot - so the chain now takes the first file that **has content for each field**, not the first readable file. **Promotions (`modelPromotions`) are time-gated**: "free at night" applies 23:00-08:00 with `factor=0` (genuinely free in that window) and only shows a badge during the day, while "limited-time free" has no window. The panel and dropdown show only **currently active** promotions, matching the CLI menu. Promotion prices are written `0.00x` (digits first), the **reverse** of the `credits` field's `x0.29 credits`, and both forms are accepted. **The descriptor is a catalogue, not a usable list**: measured on the real machine, the `-ioa` ids (`glm-5.3-ioa`, `hy3-ioa`, `deepseek-v4-pro-ioa`) are all rejected for this account with `400 ... is only available for authorized users`, while the unsuffixed `glm-5.3` and `hy3` work - the two are different id sets. **To get your account exact live list**, pass a deliberately invalid model id and the server replies with `Currently supported models for your account:` followed by one ` - ` per line (`parseAccountModels()` in core parses it). Since v1.6.0 this parsing runs on the real execution path (`buildResult` into the `rememberAccountCatalog()` cache) at **zero extra cost**, and the panel splits ids into authorized (usable) and unauthorized (a 400 if selected), listing only the former in the dropdown. **Multipliers match across naming schemes**: `lookupModelCredits()` lets the account id `glm-5.3` pick up the `x0.79` recorded for `glm-5.3-ioa` in the descriptor, with an alias table on top (`kimi-k3-1` to `kimi-k3`, `hy3-x` to `hy3`, `default` to `codewise-default-model-v2`). The two 400s mean different things: `model [...] service info not found` = the id is not in this account list; `model [...] is only available for authorized users` = it is in the catalogue but this account is not licensed (`claude-opus-4.8`, `gpt-5.4` and `gpt-6-astra` are all in this group - **they appear in the CLI menu but fail the moment you select them**). Measured here (2026-09-25, all four backends): - `workbuddy` (domestic, 53 entries): `hy3 - free - limited-time free`, `hy4-preview - x0.29 - free at night` (free during the night window), `hy3-b`/`hy3-c - limited-time free`, `deepseek-v4-flash - x0.17 - night discount`, `deepseek-v4-pro - x0.51 - night discount`, `glm-5.2 - x0.79 - night discount`. - `codebuddy-en` (international, 26 entries): `hy3`, `hy4-preview-f` and `deepseek-v4.1-flash` are all **`free - Free now`**. - `codebuddy` / `codebuddy-intl` (npm CLI, 53 entries): no account-level config on this machine, so they resolve at the descriptor layer with no promotions. **Note**: since v1.6.0 the npm-face static-table union is gone (reversing the v1.4.1/v1.4.2 design): the static table both missed ids present in the real CLI menu and kept retired ones, so it now serves only as a fallback when no file can be read. - `effort`: `minimal / low / medium / high / xhigh / max`. - `background: true`: run as a background job and return a `jobId`; collect via `job_output`. - Returns: `{ ok, status, response, sessionId, durationSeconds, numTurns, totalTokens, exitCode, mode, backend, stderr }`; on fallback it is `{ ok:false, fallback:true, status:'FALLBACK_TO_DSH', ... }`. `codebuddy_continue(prompt, sessionId? | latest?, ...)` — continue an existing conversation (`--resume ` / `--continue`); other parameters as above; without an explicit `backend` it routes to the CLI owning the sessionId. `codebuddy_status(cwd?)` — **live observation + usage accounting**: returns a snapshot of what codebuddy is doing right now (`{ state, running, current, trail, lastStatus, lastSessionId, runs, totalTokens, updatedAt, projects[] }`). `projects[]` is sectioned per project (working directory): `current` is the step that project is executing right now (tool name + arguments, or thinking/typing); `trail` is its recent step history; `runs`/`totalTokens` are the **project-cumulative call count and token usage** (codebuddy has no plan/quota API, so token metering is the available substitute). Optional `cwd` filters to one project. Callable while `codebuddy_run`/`codebuddy_continue` is in flight, no waiting. ## DSH fully controls codebuddy Every codebuddy call is forced with `-p`, `--output-format stream-json` and `--permission-mode bypassPermissions` (`--permission-mode plan` in plan mode), so **codebuddy never prompts and never asks before editing files**; mode, model, effort, working directory, timeout, background, and cancellation are all decided by DSH, and a run can be cancelled through `exec.signal` + `handle.terminate()`. codebuddy has no `--print-timeout`; a DSH-side hang guard force-terminates at `timeoutSec+60s` (`HUNG_TIMEOUT`). Each stream-json event (assistant `tool_use`/`thinking`/`text`, user `tool_result`) feeds the `codebuddy_status` snapshot in real time. ## Fallback & status light See [docs/en/FALLBACK-AND-INDICATOR.md](docs/en/FALLBACK-AND-INDICATOR.md). Highlights: - Failure detection: non-zero exit, or `stderr/status` matching `rate limit / 429 / quota / ECONN* / network / timeout / …` (plus Chinese equivalents) — **stderr and status only, never the answer text** (investigation answers almost always mention connection/dns/timeout; numeric codes are word-bounded so "1500" does not match 500). - The dialog uses DSH's `userQuestions.ask()`; when there is no live human answerer (e.g. a delegated subagent) the dialog is skipped and an error is returned, avoiding a permanent block. - Each rate-limit/network failure opens the 3-way dialog once; "Retry" is offered only while retries remain (at most 2 attempts); background failures do not open the dialog (re-run in the foreground to be prompted). - The status light polls the home-level HTTP route `GET /codebuddy-indicator/status` every 1.2s; colours come from theme tokens and adapt to light/dark. ## Visual configuration panel (v1.3.2) A new **CodeBuddy Bridge** section appears in DSH Settings (registered into the official `settings.section` list slot by the browser half — same mechanism as dsh-dream-skin / dsh-mobile-companion). Four preferences, one panel: | Field | Key | Notes | |---|---|---| | Preferred CLI | `preferredBackend` | Dropdown: `codebuddy` / `codebuddy-intl` / `codebuddy-en` / `workbuddy`. Only affects **default dispatch**; an explicit `backend` argument in a session still wins | | Default model | `defaultModel` | Free text with per-backend datalist suggestions (verified model lists). Empty = each CLI's own default | | Endpoint override | `endpointOverride` | Leave empty in normal use (endpoints auto-align to the login domain). Debug only | | International token | `codebuddyEnToken` | Password field; the page only ever shows a masked tail (last 4 chars), plaintext is never sent back to the browser. Saving empty = keep current value; a "Clear" checkbox removes it | Below the form, a **per-backend diagnostics table** shows the effective endpoint (and its source: override / auth-domain / product), the auth library login domain, the credential source (panel / env var / auto-reuse of DSH's credential store), and actionable warnings when a 401 is likely. **Saving takes effect for all three forms immediately, no restart**: the panel POSTs to `/codebuddy-indicator/settings`, which atomically writes `/codebuddy-bridge-settings.json` (single source of truth). The preset bridge, the dynamic plugin and the MCP subprocess **re-read that file on every call** (MCP with a 5s cache). Precedence: settings file > preset row config > defaults. > Why a self-drawn panel instead of the official auto-form: the `Config` projection only covers entries whose fiber is an `include`; preset bridges mount through `PresetTree` and never qualify (verified line-by-line in `dsh-config-editor`). The self-drawn section + own read/write route is the only path where one save reaches all three forms — and it can show live diagnostics on top. ## Repository layout ``` codebuddy-first-bridge/ ├─ README.md / README.en.md ├─ LICENSE ├─ .gitignore ├─ package.json # version metadata (v1.1.0, Node >=18) + scripts (build/test/check) ├─ MCP-POLICY.md # disclose-and-prefer policy for external agents (also ~/.claude/CLAUDE.md, ~/.codex/AGENTS.md) ├─ .github/workflows/ci.yml # node --check + test suite + version/YAML structural validation (Node 18/20/22) ├─ assets/indicator-states.svg # status-light states diagram ├─ core/ │ └─ codebuddy-core.mjs # ★ shared core (single source of truth): pure functions + status engine │ # + line stream + run orchestration + shared copy ├─ scripts/ │ ├─ build.mjs # generates derived artifacts (dynamic/host.js text injection + preset core copy) │ └─ verify.mjs # version quad-lock (package.json ↔ indicator package.json ↔ MCP VERSION ↔ CHANGELOG) + YAML/structure assertions ├─ test/ # node:test suite (125 cases: pure functions / sandbox sim / preset / MCP e2e / settings UI / sync lock) │ ├─ helpers/mockdsh.mjs # DSH host-shape stand-ins (ctx/harness/subprocess/userQuestions) │ ├─ fixtures/fake-codebuddy.mjs # fake codebuddy CLI (MCP e2e fixture) │ └─ *.test.mjs ├─ preset/ │ └─ codebuddy-first/ # persistent agent preset (recommended) │ ├─ preset.yml │ ├─ agent.cordis.yml # standard + one codebuddy plugin row │ ├─ codebuddy-first-bridge.mjs # host adapter (tool registration / event publish / env resolution) │ └─ codebuddy-core.mjs # [generated] core copy — the preset install dir is self-contained ├─ home-plugin/ │ └─ codebuddy-indicator/ # home-level status-light plugin (start-up persistent) │ ├─ package.json # dsh.client declaration (browser roster) │ └─ lib/ │ ├─ index.mjs # host half: collects codebuddy/status events + HTTP route │ ├─ client-entry.mjs # bare-name placeholder entry (prevents double-loading index.mjs) │ └─ client.js # browser half: poll + render per-project light ├─ dynamic/ # dynamic Cordis plugin form (with status light) │ ├─ host.template.mjs # adapter template (with the /*__CORE__*/ injection point) │ ├─ host.js # [generated] code.host body (core text injected — do not edit by hand) │ └─ client.js # code.client body (empty skeleton: UI unified in the home-level light) ├─ mcp/ # MCP server (discoverable by any MCP host) │ ├─ codebuddy-mcp-server.mjs # zero-dependency stdio MCP server (host adapter layer) │ └─ README.md # registration (Claude Code / Codex / DSH / generic) + security guardrail └─ docs/ ├─ INSTALL.md / ARCHITECTURE.md / FALLBACK-AND-INDICATOR.md / CHANGELOG.md (中文) └─ en/INSTALL.md / ARCHITECTURE.md / FALLBACK-AND-INDICATOR.md (English) ``` > **Derived-artifact convention**: `dynamic/host.js` and `preset/codebuddy-first/codebuddy-core.mjs` are generated. Change shared logic in `core/`, dynamic adapters in `host.template.mjs`, then run `npm run build` (the sync lock inside `npm test` fails the commit if you forget). ## Compatibility & support statement Regression-tested against **all 26** published `@deepseek-ai/dsh` versions (0.0.1-rc.1 → 0.1.7-rc.1); the full matrix and evidence live in [docs/COMPATIBILITY.md](docs/COMPATIBILITY.md). Highlights: - **Preset form (Option A)**: **works on every version (fixed in v1.2.0)** — dsh ≤ 0.1.6-alpha.2 uses the directory-based preset (`dsh ≥ 0.1.3-alpha.2` enforces the persona `prefix:`/`suffix:` schema); from dsh ≥ 0.1.7-alpha.1 the `.agent-presets` directory is no longer read (declarative presets), and the preset is registered into the `agentPresets` registry by the status-light plugin (Option B). **On new DSH, install Option A together with Option B.** - **Home-level light via bundle install (Option B)**: `dsh plugin --profile web add codebuddy-first-bridge` works on **all 26 versions** (the plugin CLI / pnpm forwarder / `dsh.bundle.patch` / bundles reconciliation exist since 0.0.1-rc.1). Requires `codebuddy-first-bridge ≥ 1.1.8` (1.1.7's client registration-id mismatch trips a startup fatal screen on **every** dsh version). - **MCP server (Option D)**: zero-dependency standalone process, independent of the dsh version. - When a new dsh version ships, re-run the regression via `npm run compat:dsh` (see [docs/RELEASE-SOP.md](docs/RELEASE-SOP.md) §3). ## Versions & releases Semantic versioning via `package.json` + Git tags + GitHub Releases; per-version npm↔git content audit via `npm run audit:npm` (also wired into CI; see [docs/CHANGELOG.md](docs/CHANGELOG.md)): | Version | DSH compat | Highlights | | --- | --- | --- | | [v1.6.2](https://github.com/new-256/codebuddy-bridge/releases/tag/v1.6.2) | dsh 0.1.7-rc.1 verified / all | **The default-model picker collapsed to a single entry, making the model list look lost.** On your report that only `deepseek-v4.1-flash` showed up, we confirmed the **data was complete** (the live route returns 53 / 53 / 26 / 53 options for `codebuddy` / `codebuddy-intl` / `codebuddy-en` / `workbuddy`, nothing missing) - the fault was in **how it rendered**: the field was an `` + ``, a free-text box whose dropdown the browser **prefix-filters by the current text**. Your `defaultModel` was `deepseek-v4.1-flash`, which also happened to sort first (it carries the Free now promotion at an effective x0.00, so it floats to the top of the free group) - so opening the dropdown left exactly that one entry. Replaced with an explicit **`