dsh-advisor 0.1.3 → 0.2.0

package/README.i18n.yaml

@@ -3,5 +3,5 @@
 # editing either side, bring the other along and re-record with:
 #   git hash-object README.md
 #   git hash-object README.zh.md
-README.md: c0096d75da8f4c6e528b24a5bf3cdce6722f0358
-README.zh.md: 6b7c4425bb81764d4bc47a6dc417b7e352fc3769
+README.md: 6da971fed9908121287601132c6e39ff66dba750
+README.zh.md: 4c770571e72e38e64c9cf48a789cc41aa544192b

package/README.md

@@ -1,135 +1,62 @@
 # dsh-advisor
 
-English | [中文](README.zh.md)
+[English](README.md) | [中文](README.zh.md)
 
 [![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 ![node](https://img.shields.io/badge/node-%5E22.19%20%7C%7C%20%3E%3D24-339933.svg)
 ![dsh](https://img.shields.io/badge/dsh-DeepSeek%20Harness%20compatible-4B32C3.svg)
+[![dshfind](https://dshfind.com/api/badge/omdsh-dev/dsh-advisor)](https://dshfind.com/plugins/omdsh-dev/dsh-advisor?ref=badge)
 
-A standalone dsh plugin bundle porting the omp "advisor"
-subsystem: a per-session reviewer model that observes the primary transcript,
-reviews each stepped turn with an explicitly configured model (provider +
-model are required), and injects severity-ranked advice (nit / concern /
-blocker) back into the session — without polluting or recursively reviewing
-itself.
+A standalone dsh (DeepSeek Harness) plugin bundle porting the omp "advisor" subsystem: a per-session independent reviewer model that observes the primary transcript, reviews each stepped turn with an explicitly configured model (provider + model are required), and injects severity-ranked advice (nit / concern / blocker) back into the session — without polluting or recursively reviewing itself.
 
-Install with a single command:
+**Advisory only.** The advisor never approves or rejects the primary agent's actions, and never issues commands as if it were the primary agent. Every delivered message is self-described advisory content, and a misbehaving reviewer is bounded end to end (emission guard, immuneTurns cooldown, failure policy) so it can never stall or pollute the primary loop.
 
-```sh
-dsh plugin --profile web add dsh-advisor   # <name> = your profile name
-```
-
-**Advisory only.** The advisor never approves or rejects the primary agent's
-actions; it never issues commands as if it were the primary agent. Every
-delivered message is self-described advisory content, and a misbehaving
-reviewer is bounded end to end (emission guard, immuneTurns cooldown, failure
-policy) so it can never stall or pollute the primary loop.
+Works in both dsh front ends: the **web** profile (Settings → 插件配置 → Advisor card) and the **dsh-tui** terminal profile (`/advisor` + `/advisor config`).
 
-## Install
+## Quick start
 
-### One-line registry install
+### Install
 
 ```sh
-dsh plugin --profile web add dsh-advisor   # <name> = your profile name
+dsh plugin --profile web add dsh-advisor      # web profile (Settings → Advisor card)
+dsh plugin --profile dsh-tui add dsh-advisor  # dsh-tui terminal profile
 ```
 
-A registry install fetches the published tarball, which ships the built
-artifacts (`lib/` + `cordis.patch.yml`), so no `prepare` build or build
-permission is needed. Runtime dependencies (`@deepseek-ai/cordis`, `@deepseek-ai/schemastery`,
-and the `@deepseek-ai/dsh-*` peers) are declared as peerDependencies and resolve
-through the dsh installation's flat profile module fallback — no extra install
-step. Pin an exact version (`dsh-advisor@0.1.0`) for reproducible installs.
+Same plugin, either front end — the only difference is the `--profile` flag. Pin a version with `@<version>` (e.g. `dsh-advisor@0.1.0`). A registry install fetches the published tarball, which ships the built artifacts (`lib/` + `cordis.patch.yml`) — nothing builds on the target machine, and runtime dependencies (`@deepseek-ai/cordis`, `@deepseek-ai/schemastery`, `@deepseek-ai/dsh-*` peers) resolve through the dsh installation's flat profile module fallback — no extra install step. Registry / git / tarball / local-directory variants (local-dir from a built checkout: `dsh plugin --profile web add .` or `dsh plugin --profile dsh-tui add .`), web Settings exposure, uninstall, and `--dump-config` verification → [docs/install.md](docs/install.md).
 
-### Local directory install (recommended for development / verification)
+### Configuration
 
-```sh
-pnpm install                    # build the bundle (the prepare self-build)
-dsh plugin --profile web add .  # <name> = your profile name
+Add an `advisor:` section to the global dsh settings document (default `$DSH_HOME/settings.yaml` — shared across profiles; the web Settings card writes to this same file):
+
+```yaml
+advisor:
+  enabled: true                # master switch (default false) — set explicitly to enable
+  provider: deepseek-official  # REQUIRED when enabled
+  model: deepseek-v4-flash     # REQUIRED when enabled
+  systemPrompt: ""             # optional; "" = built-in reviewer prompt
+  immuneTurns: 3               # int ≥ 0, default 3 — cooldown after a delivered steer
+  maxDeltaMessages: 60         # int ≥ 0, default 60 — delta window; 0 = unbounded
 ```
 
-### Verify
+The advisor is off by default. When enabled, `provider` and `model` are **mandatory**: `enabled: true` without both is a hard gate — the advisor never starts a model call and reports a disabled-with-reason status; unknown config keys are rejected.
 
-```sh
-dsh --profile web --dump-config   # shows a "# == dsh-advisor" layer with the advisor row
-dsh --profile web
-```
+The same keys compose across **three surfaces** (later layers override earlier ones; every surface shares the same key set and the same hard gate, with the host-side gate as the final line of defense on every path):
 
-Tarball install and uninstall are covered in [docs/install.md](docs/install.md).
+1. **Plugin-row config** — the profile patch layer (`$DSH_HOME/profiles/<profile>/cordis.patch.yml`). This is the composition base.
+2. **dsh web Settings page — the "插件配置" (Plugin Configuration) page** — the Advisor **card** (id `advisor`) with the enabled toggle, provider / model selects restricted to system-configured providers and their models, and the optional fields. Saving writes into the `advisor` settings namespace and applies to new sessions immediately — no restart. The card requires a current dsh web build whose shell declares the `settings.plugin.item` card slot and loads packages that declare `dsh.client`; it reads and writes the namespace through the official `GatewayService` RPC channel (`/api/advisor/get` + `/api/advisor/set`), which is not gated by the settings exposure allowlist. It additionally blocks saving while enabled with a required field empty.
+3. **`/advisor` command** — per-session and ephemeral: it flips a session override, never the persisted config (see [Verify](#verify)).
 
-## Config
+In a **dsh-tui** profile there is no settings page: the same two persisted surfaces (profile patch layer + global `$DSH_HOME/settings.yaml`) compose the config, and `/advisor config` prints the composed config as a read-only readback with edit hints. Full reference → [docs/configuration.md](docs/configuration.md).
 
 ![Advisor card on the dsh web Settings (插件配置) page](docs/screenshots/advisor-settings-card.webp)
 
-The advisor is off by default. When enabled, `provider` and `model` are
-**mandatory**: `enabled: true` without both is a hard gate — the advisor never
-starts a model call and reports a disabled-with-reason status. Unknown config
-keys are rejected.
-
-Configuration composes across **three surfaces** (later layers override earlier
-ones; every surface uses the same key set):
-
-1. **Plugin-row config** — `$DSH_HOME/profiles/web/cordis.patch.yml`
-   (below). This is the composition base.
-2. **dsh web Settings page — the "插件配置" (Plugin Configuration) page** —
-   the Advisor **card** (id `advisor`, rendered after the upstream bash /
-   agent-loop / web-search cards) with the enabled toggle, provider / model
-   selects restricted to system-configured providers and their models, and the
-   optional fields. Saving writes into the `advisor` settings namespace and
-   overrides the plugin-row config without editing it. Saving applies to new
-   sessions immediately — no restart (the runtime reads the composed value
-   live). Requires a current dsh web build whose shell declares the
-   `settings.plugin.item` card slot and loads packages that declare
-   `dsh.client`. The card reads and writes the namespace through the
-   **official `GatewayService` RPC channel** (`/api/advisor/get` +
-   `/api/advisor/set`, claimed by the host's typertGateway — the same
-   mechanism the dsh `goals` service uses), which is **not gated by the
-   settings exposure allowlist**: the in-process write
-   (`ctx.settings.update`) carries no exposed-namespace check. No host
-   patching is applied or required.
-3. **`/advisor` command** — per-session and ephemeral: it flips a session
-   override, never the persisted config (see [Usage](#usage)).
-
-Both persisted surfaces share the same hard gate: `enabled: true` with empty
-`provider`/`model` never starts a model call (disabled-with-reason). The
-Settings page additionally blocks saving while enabled with a required field
-empty; the host-side gate stays the final line of defense on every path.
-
-Plugin-row config:
+### Verify
 
-```yaml
-# profiles/web/cordis.patch.yml — the profile's user patch layer
-- id: advisor
-  config:
-    enabled: true              # master switch (default false)
-    provider: deepseek-official  # REQUIRED when enabled
-    model: deepseek-v4-flash     # REQUIRED when enabled
-    systemPrompt: ""           # optional; "" = built-in reviewer prompt
-    immuneTurns: 3             # int ≥ 0, default 3 — cooldown after a delivered interrupt
-    maxDeltaMessages: 60       # int ≥ 0, default 60 — delta window; 0 = unbounded
+```sh
+dsh --profile web --dump-config   # shows a "# == dsh-advisor" layer with the advisor row
 ```
 
-| Key | Type / default | Meaning |
-|---|---|---|
-| `enabled` | bool, `false` | Master switch. |
-| `provider` | string, optional | Provider route. Required (non-empty) when `enabled: true`. |
-| `model` | string, optional | Model id. Required (non-empty) when `enabled: true`. |
-| `systemPrompt` | string, `""` | Overrides the built-in reviewer prompt (severity definitions + JSON-frame output contract). |
-| `immuneTurns` | int ≥ 0, `3` | After a concern/blocker is actually steered, the next N stepped primary turns must complete before another interrupting note may steer; notes inside the window downgrade to inject. |
-| `maxDeltaMessages` | int ≥ 0, `60` | Bounded advisor input window. Deltas beyond N are truncated with a `… <earlier messages omitted>` marker; `0` = unbounded. |
-
-**Model capability & budget**: the advisor call runs with `reasoningEffort:
-'off'` — sent only when the configured model's adapter declares that effort
-(deepseek models do; any other model gets the option omitted automatically, so
-non-reasoning providers keep working) — and a **5120-token** output cap (a
-user-directed 20× supersession of the original 256). Extracted notes are
-bounded (1000 chars) and the notice summary to 120 chars, so the raised budget
-cannot translate into an unbounded injection into the primary session.
-
-## Usage
-
-Once installed and enabled, the advisor observes every session. Control it per
-session with the `/advisor` command (available when a command registry is
-composed):
+With the advisor installed and enabled, control it in-session with the `/advisor` command (available when a command registry is composed):
 
 ```
 /advisor            toggle the advisor for this session
@@ -138,163 +65,53 @@ composed):
 /advisor status     show state, model, runtime status, pending count, last activity
 ```
 
-`/advisor on|off|toggle` are session-scoped and ephemeral: they flip a
-per-session override, never the persisted config. Enabling a session whose
-config lacks `provider`/`model` starts no model call — `/advisor status` (and
-the `/advisor on` reply) shows the gate reason.
-
-`/advisor on` is also the manual recovery path: a session advisor paused by a
-quota/rate-limit (`quota_exhausted` — KD-5 has no auto-resume timer) resumes in
-place, and a halted advisor (permanent model error, e.g. invalid credentials)
-is rebuilt fresh for the session.
+`/advisor on|off|toggle` are session-scoped and ephemeral: they flip a per-session override, never the persisted config. Enabling a session whose config lacks `provider`/`model` starts no model call — `/advisor status` (and the `/advisor on` reply) shows the gate reason: the advisor runs only when enabled **with** both configured. `/advisor on` is also the manual recovery path: a session advisor paused by a quota/rate-limit (`quota_exhausted` — no auto-resume timer) resumes in place, and a halted advisor (permanent model error, e.g. invalid credentials) is rebuilt fresh for the session.
 
-The advisor reviews on a dual-mode trigger, depending on the session shape:
+In a **dsh-tui** profile, `/advisor config` additionally reads back the composed configuration — read-only, with edit hints: the web Settings card is web-only, and the TUI has no settings page and no write command, so edit through the profile patch layer or `$DSH_HOME/settings.yaml`. The `/advisor` / `on|off|status|config` commands are listed in the TUI `/` menu with subcommand completion (command discovery requires the `dsh-tui-command-trees` row — the shipped dsh-tui bundle has it).
 
-- **Standard stepped sessions** — after each stepped primary turn that ends
-  normally (`completed`, `max-tokens`, or `error`), the advisor reviews the
-  incremental transcript delta.
-- **Agentic / harness sessions** (never emit `turn/end`) — after each completed
-  agent reply round: when a new human input arrives (inbox-spliced input
-  included) after an unreviewed assistant increment, the advisor reviews that
-  increment.
+## Features
 
-Either way the advisor emits at most one note per review, ranked by severity:
+- **Independent reviewer per session**: a separate model call observes the primary transcript and reviews each stepped primary turn; advisor messages are excluded from later deltas, so the advisor never reads its own advice back.
+- **Severity-ranked advice with inject/steer semantics**: at most one note per review — **nit** (a minor style, clarity, or quality suggestion; delivered via non-waking `agent.inject`, consumed at the next pre-step boundary), **concern** (a material risk or clearly better direction to weigh before continuing; delivered via waking `agent.steer`, subject to the `immuneTurns` cooldown), **blocker** (continuing clearly wastes work — contradicts an explicit user instruction, going in circles, fundamentally unsound; delivered via `agent.steer`). Delivered messages carry the `[advisor:{severity}]` prefix and are self-described advisory content:
 
-- **nit** — a minor style, clarity, or quality suggestion; delivered via
-  `agent.inject` (non-waking, consumed at the next pre-step boundary).
-- **concern** — a material risk or clearly better direction to weigh before
-  continuing; delivered via `agent.steer` (waking), subject to the
-  `immuneTurns` cooldown.
-- **blocker** — continuing clearly wastes work (contradicts an explicit user
-  instruction, going in circles, fundamentally unsound); delivered via
-  `agent.steer`.
+  ```
+  [advisor:concern] extract the helper into a module and unit-test it
+  ```
 
-Injected advice appears in the session stream as a user-role message carrying
-the advisor source kind and self-describing content, e.g.:
-
-```
-[advisor:concern] extract the helper into a module and unit-test it
-```
-
-The `[advisor:{severity}]` prefix is the only cue the primary model gets about
-how to treat it — the primary system prompt never mentions advisories. Advisor
-messages are excluded from later advisor deltas, so the advisor never reads
-its own advice back.
+- **Explicit model gate**: `enabled` defaults to off; `enabled: true` without `provider` + `model` never starts a model call — status reports disabled-with-reason. Unknown config keys are rejected.
+- **Zero-tool minimal start**: the reviewer is an independent model call only — no advisor tools, nothing it can do to the session besides advisory messages.
+- **No-stall failure policy**: a failing or quota-limited advisor only drops its own bounded backlog — it can never park or pollute the primary loop.
+- **Session-scoped controls**: `/advisor on|off|status|config` work per session; the toggles are ephemeral overrides, never persisted config.
 
 ![Advisor note injected into the session stream](docs/screenshots/advisor-injected-note.webp)
 
-## How it works
-
-The plugin subscribes to `session/event`. Two triggers render an incremental
-markdown delta of the primary transcript (own advisor messages excluded) and
-queue it on a per-session runtime: after each stepped `turn/end` in standard
-stepped sessions, and — in agentic/harness sessions that never emit `turn/end`
-— when a new human input arrives (inbox-spliced input included) after an
-unreviewed assistant increment, i.e. at each completed agent reply round. The
-runtime calls a separately configured model via `ctx.llm.stream`, extracts one
-`{note, severity}` from the JSON-framed reply, gates it through an emission
-guard (normalize / dedupe / content-free suppression / one-note-per-update),
-and routes it: nit → inject, concern/blocker → steer. The advisor call runs
-with reasoning off and a 20x token budget so the JSON note is never starved by
-reasoning output. Compaction and surface rewrites reset the observer, the
-emission guard, and the immuneTurns latch
-(KD-5); the drain is fully async with a bounded backlog, so a failing or
-quota'd advisor can only drop its own backlog — never park the primary loop.
+## Mount-only (no dsh modification)
 
-## Limitations & roadmap
+The plugin installs as a **pure mount**: bundle insert + client card (web Settings 插件配置) + its own gateway channel (`/api/advisor/get|set`, claimed by the host's typertGateway — the same mechanism the dsh `goals` service uses, not gated by the settings exposure allowlist) + the `/advisor` commands — no dsh patches, no postinstall step, and dsh upgrades never require re-patching.
 
-The MVP deliberately drops full omp parity. Accepted gaps (tracked in the
-harness iteration roadmap):
-
-- **Single advisor per session** — no parallel advisor roster or WATCHDOG-style
-  file discovery (next iteration).
-- **No advisor tools** — the reviewer is an independent model call only; it
-  cannot verify claims itself (next-next iteration).
-- **No in-session advisor panel** — advice surfaces only as tagged injected
-  messages (the Advisor card on the "插件配置" settings page is a config
-  surface, not a session view; an in-session card is next-next iteration).
-- **No transcript persistence or cost stats** — no resumable advisor history or
-  cost observability (next-next iteration).
-- **No secret obfuscation of delta content** — secrets present in the transcript
-  can reach the advisor model; mitigate by configuring a trusted reviewer model.
-- **No quarantine of unsafe advisor output** — a misbehaving note can carry
-  directive text; the JSON frame + validation + advisory-only framing
-  (`[advisor:…]`, "weigh, don't blindly obey") are the only mitigation, and the
-  note is delivered as-is into the primary transcript (roadmap).
-- **No `syncBacklog` catch-up wait** — a far-behind advisor does not wait for
-  the primary loop; its backlog is bounded and dropped (never parks the
-  primary), so advisor notes may arrive after the next primary turn started
-  (roadmap: context-maintenance batch).
-- **Bounded advisor context** — long-session full replays are truncated
-  (`maxDeltaMessages`), so the advisor may lose early context after compaction;
-  advisor context maintenance is roadmap (next-next iteration).
-
-## Development
-
-The bundle builds itself on install: `package.json` declares `"prepare": "node
-scripts/setup-dsh-links.mjs && pnpm build"` (the dev-time link farm plus the
-same build `prepack` runs), so any clone is
-immediately buildable **once `DSH_HOME` points at a dsh home whose
-`source/current` is a dsh source tree** (or `DSH_SOURCE_DIR` points at such a
-tree directly). The private
-`@deepseek-ai/dsh-*` runtime dependencies are **peerDependencies only**; at dev
-time `scripts/setup-dsh-links.mjs` (wired into `prepare`, standalone as
-`pnpm dsh:link`, verified with `pnpm dsh:link:check`) links the REAL packages
-from that tree into `node_modules/@deepseek-ai/` — every `@deepseek-ai/*`
-package the tree declares (tool CLIs with a `bin` are skipped: linking them
-would make pnpm write their bins into the shared tree), a bin-less shim for
-the in-box `cordis` framework, and the tree's own `react`/`react-dom` copies
-(node resolution — including externalized CJS deps — must see ONE react
-identity, the identity the real client packages use; the dsh profile
-convention `nodeLinker=hoisted` lives in `pnpm-workspace.yaml` (pnpm 11+
-ignores non-auth settings in `.npmrc`), so no `.pnpm` per-package dirs shadow
-those links). The farm is idempotent, prunes stale entries, and fails with
-guidance when the tree is missing or a peer cannot be linked.
-`pnpm-workspace.yaml` also sets `autoInstallPeers: false` (dsh profile
-convention): the private peers must never be fetched from the npm registry.
+## Limitations & roadmap
 
-```sh
-export DSH_HOME=~/.dsh    # a dsh home with source/current (or set DSH_SOURCE_DIR)
-pnpm install              # registry deps + link farm (via prepare), no private-registry access
-pnpm test                 # vitest (unit + the composed integration loop)
-pnpm typecheck            # tsc --noEmit (node) + tsc -p tsconfig.client.json --noEmit + tsc -p tsconfig.spec.json --noEmit
-pnpm build                # tsc -p tsconfig.build.json emit to lib/ + node scripts/build-client.mjs (client bundle)
-pnpm pack                 # build + produce dsh-advisor-0.0.1.tgz
-```
+The MVP deliberately drops full omp parity. Accepted gaps (tracked in the harness iteration roadmap):
 
-On Windows the link farm creates directory entries as junctions (no special
-privileges), but the cordis shim's file entries use file symlinks, which need
-[Developer Mode](https://learn.microsoft.com/windows/apps/get-started/enable-your-device-for-development)
-(or an admin shell) — enable it before `pnpm install`. Windows has no
-`HOME`, so the script falls back to `USERPROFILE` to resolve the dsh source
-tree.
-
-The in-box `cordis` framework is declared as the scoped peer
-`@deepseek-ai/cordis: ^4.0.1-rc.1` (the range carries the exact publish tag —
-a comparator prerelease such as `^4.0.0-rc.7` never matches the vendored
-`4.0.1-rc.1` per the node-semver tuple rule); after install the link farm's
-bin-less cordis shim at `node_modules/@deepseek-ai/cordis` answers the scoped
-name and resolves to the vendored files, because the real packages type and
-run against the vendored build and module identity requires dev-time
-`import '@deepseek-ai/cordis'` to resolve to the same files. The public
-devDependencies (`@deepseek-ai/schemastery`, `react`, …) resolve from the npm registry as
-usual.
-
-`prepack` runs `pnpm build`; `prepare` runs the link farm and the build, so
-`pnpm pack` runs the build twice (once per lifecycle) — the documented
-tradeoff that keeps git-install builds working. There is no `postinstall`
-step: already-built tarball installs skip the build entirely.
-
-The integration test (`tests/integration.test.ts`) composes the plugin into a
-real cordis context with a stub LLM adapter and drives the full
-turn → delta → advisor call → inject/steer cycle.
+- **Single advisor per session** — no parallel advisor roster or WATCHDOG-style file discovery (next iteration).
+- **No advisor tools** — the reviewer is an independent model call only; it cannot verify claims itself (next-next iteration).
+- **No in-session advisor panel** — advice surfaces only as tagged injected messages; the web Advisor card is a config surface, not a session view (next-next iteration).
+- **No transcript persistence or cost stats** — no resumable advisor history or cost observability (next-next iteration).
+- **No secret obfuscation of delta content** — secrets present in the transcript can reach the advisor model; mitigate by configuring a trusted reviewer model.
+- **No quarantine of unsafe advisor output** — a misbehaving note can carry directive text; the JSON frame + validation + advisory-only framing are the only mitigation, and the note is delivered as-is (roadmap).
+- **No `syncBacklog` catch-up wait** — a far-behind advisor does not wait for the primary loop; its backlog is bounded and dropped, so notes may arrive after the next primary turn started (roadmap: context-maintenance batch).
+- **Bounded advisor context** — long-session full replays are truncated (`maxDeltaMessages`), so the advisor may lose early context after compaction (roadmap: next-next iteration).
 
 ## Documentation
 
 | Doc | Content |
 |---|---|
-| [docs/install.md](docs/install.md) | full install guide: git / tarball / local-directory install, web Settings exposure, uninstall, `--dump-config` verification |
+| [docs/install.md](docs/install.md) | profile install (web + dsh-tui) / registry / git / tarball / local-directory variants / web Settings exposure / uninstall / `--dump-config` verification |
+| [docs/configuration.md](docs/configuration.md) | full `advisor` namespace reference: keys & defaults, explicit model gate (S4), settings surfaces (web card / patch layer / global settings.yaml), example YAML, live re-apply behavior |
+| [docs/consumer-api.md](docs/consumer-api.md) | developer consumption contract: package-root library API, `dsh-advisor/client` entry, `/advisor` command surface, export inventory, lifecycle |
+| [docs/verification.md](docs/verification.md) | verification records: test matrix (16 files / 319 cases), typecheck/build, CI contract, real-environment steps |
+| [docs/release.md](docs/release.md) | release process: PR-driven Release prep + Release workflows, OIDC trusted publishing, version strategy, rollback |
 
 ## License
 
-MIT
+Released under the **MIT** License — see [LICENSE](LICENSE). The LICENSE file is authoritative for copyright and license terms.