dsh-lsp-actions 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -3,6 +3,57 @@
 All notable changes to dsh-lsp-actions are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## 0.3.0 — 2026-08-19
+
+### Added
+
+- **Editor action protocol v1 — the IDE integration backend.** With `editor.enabled: true` in a
+  dedicated headless composition, the plugin serves `lsp.actions.list` / `lsp.actions.run` /
+  `lsp.events` over newline-delimited JSON-RPC 2.0 (wire-framing-compatible with the official
+  SDK/ACP transports), so any editor can consume the LSP capabilities directly — no agent round-trip.
+  - Four v1 actions: `diagnostics.get` (read-only), `completion.get` (read-only, zero-based LSP
+    positions), `quickfix.apply` (selects a server-verified code action by `title`/`index` and
+    applies its edits), and `format` (whole-file or range).
+  - `run` always answers one structured `{ requestId, action, status, result | error }` envelope;
+    failures carry the stable `LSP_ACTION_*` codes, extended with `LSP_ACTION_UNKNOWN`,
+    `LSP_ACTION_INVALID_ARGS`, `LSP_ACTION_APPROVAL_UNAVAILABLE`, and
+    `LSP_PROTOCOL_VERSION_UNSUPPORTED`.
+  - Streamed `lsp.event` notifications: `diagnostics.updated`, `action.status`, `file.changed`,
+    `sessions.changed`; `lsp.events {subscribe}` controls the stream.
+  - **Versioning & backward compatibility**: `lsp-actions/v1` is frozen; evolution is additive
+    only; breaking changes ship under a new protocol version. Documented in the bilingual spec
+    [`docs/editor-protocol.md`](docs/editor-protocol.md) / [`docs/editor-protocol.zh-CN.md`](docs/editor-protocol.zh-CN.md).
+- **Official permission presets and approval for editor writes.** `quickfix.apply` and `format`
+  resolve the addressed session's official sandbox policy (read-only sessions fail with
+  `LSP_ACTION_READ_ONLY` before any server round-trip), write through the `fs/write-intent`
+  waterfall with guarded writes, and resolve the `sandbox_permissions` + `justification` escalation
+  pair through the official `approveEscalation` ask (fail-closed with
+  `LSP_ACTION_APPROVAL_UNAVAILABLE` when no answerer can decide).
+- **Bounded LRU diagnostics cache** (`editor.diagnosticsCacheMaxFiles`, default 64):
+  freshness-stamped snapshots, least-recently-used eviction, invalidated by filesystem
+  observations and by the plugin's own writes; never persisted across restarts. Cached
+  first-error ranges power range-less `quickfix.apply` targeting.
+- **Schema configuration** for the backend: `editor.enabled` (default `false` — only headless
+  backends may claim stdio), `editor.requestTimeoutMs` (default 60000, enforced per run), and
+  `editor.diagnosticsCacheMaxFiles`. Misconfiguration fails at load.
+- **Reversible registration.** The transport, event listeners, and cache live entirely inside the
+  plugin's effect scope; stopping or updating the plugin tears the whole surface down.
+- **`examples/vscode/`**: a minimal UI-only VS Code extension (sidebar with DSH sessions +
+  diagnostics list + one-click quickfix + open-at-range + format) plus the headless backend
+  composition (`backend/cordis.yml` + `bin.mjs`). The extension implements zero LSP logic.
+- **Tests**: bounded-LRU coverage, editor-protocol service semantics (permission gating, escalation
+  fail-closed, timeouts, cache invalidation), and a full diagnostics → quickfix → format chain over
+  real JSON-RPC frames against the fixture LSP server.
+
+### Changed
+
+- **Prompt hygiene commitment**: the plugin injects no persona or prompt prose (model-facing
+  surface = the eight tool schemas); any future prompt segment must open with one short role
+  sentence and stay brief, aligned with the official Minimal persona style.
+- README (EN/zh-CN) now documents the IDE-backend architecture (editor protocol × official ACP
+  server × Python SDK), the versioning promise, the VS Code example, and the extended error-code
+  table; es/hi/pt READMEs point at the canonical protocol docs.
+
 ## 0.2.0 — 2026-08-15
 
 ### Added

package/README.es.md

@@ -8,6 +8,9 @@ Diagnósticos, formateo, completado de código, correcciones rápidas, símbolos
 
 [![Topic: dsh](https://img.shields.io/badge/Topic-dsh-4D6BFE?style=for-the-badge)](https://github.com/topics/dsh)
 [![Topic: dsh-plugin](https://img.shields.io/badge/Topic-dsh--plugin-8257D0?style=for-the-badge)](https://github.com/topics/dsh-plugin)
+[![CI](https://github.com/PerryLink/dsh-lsp-actions/actions/workflows/ci.yml/badge.svg)](https://github.com/PerryLink/dsh-lsp-actions/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/dsh-lsp-actions?style=flat-square)](https://www.npmjs.com/package/dsh-lsp-actions)
+[![npm downloads](https://img.shields.io/npm/dw/dsh-lsp-actions?style=flat-square)](https://www.npmjs.com/package/dsh-lsp-actions)
 [![License](https://img.shields.io/badge/License-Apache%202.0-D22128?style=flat-square)](LICENSE)
 [![Node](https://img.shields.io/badge/Node-%5E22.19%20%7C%7C%20%3E%3D24-43853D?style=flat-square)](package.json)
 
@@ -17,6 +20,8 @@ Diagnósticos, formateo, completado de código, correcciones rápidas, símbolos
 
 ---
 
+> **Nuevo (v0.3.0):** backend de integración IDE — el protocolo de acciones para editores `lsp.actions.list` / `lsp.actions.run` / `lsp.events` (v1) y el ejemplo mínimo de VS Code. La especificación canónica del protocolo está documentada en [README.md](README.md) y [README.zh-CN.md](README.zh-CN.md) (arquitectura, versionado y compatibilidad hacia atrás); la especificación completa del wire: [docs/editor-protocol.md](docs/editor-protocol.md) / [docs/editor-protocol.zh-CN.md](docs/editor-protocol.zh-CN.md).
+
 ## Qué aporta este plugin a tu agente
 
 El seam oficial `ctx.lsp` de DeepSeek Harness cubre la **navegación** (ir a definición, referencias, implementación, hover). `dsh-lsp-actions` completa la **superficie de acción**: el bucle de retroalimentación que un agente necesita mientras escribe y corrige código:
@@ -172,6 +177,12 @@ pnpm run test:coverage   # puertas: líneas/sentencias/funciones ≥ 90%, ramas
 pnpm build           # emite lib/
 ```
 
+## Contribuidores
+
+Gracias a todas las personas que han contribuido a este proyecto:
+
+- [PerryLink](https://github.com/PerryLink) — el plugin en sí: el cliente de acciones LSP y el ciclo de vida del servidor, las ocho herramientas, los tests, la CI y la documentación.
+
 ## License
 
 [Apache License 2.0](LICENSE)

package/README.hi.md

@@ -8,6 +8,9 @@
 
 [![Topic: dsh](https://img.shields.io/badge/Topic-dsh-4D6BFE?style=for-the-badge)](https://github.com/topics/dsh)
 [![Topic: dsh-plugin](https://img.shields.io/badge/Topic-dsh--plugin-8257D0?style=for-the-badge)](https://github.com/topics/dsh-plugin)
+[![CI](https://github.com/PerryLink/dsh-lsp-actions/actions/workflows/ci.yml/badge.svg)](https://github.com/PerryLink/dsh-lsp-actions/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/dsh-lsp-actions?style=flat-square)](https://www.npmjs.com/package/dsh-lsp-actions)
+[![npm downloads](https://img.shields.io/npm/dw/dsh-lsp-actions?style=flat-square)](https://www.npmjs.com/package/dsh-lsp-actions)
 [![License](https://img.shields.io/badge/License-Apache%202.0-D22128?style=flat-square)](LICENSE)
 [![Node](https://img.shields.io/badge/Node-%5E22.19%20%7C%7C%20%3E%3D24-43853D?style=flat-square)](package.json)
 
@@ -17,6 +20,8 @@
 
 ---
 
+> **नया (v0.3.0):** IDE इंटीग्रेशन बैकएंड — एडिटर एक्शन प्रोटोकॉल `lsp.actions.list` / `lsp.actions.run` / `lsp.events` (v1) और न्यूनतम VS Code उदाहरण। प्रोटोकॉल का प्रामाणिक विवरण [README.md](README.md) और [README.zh-CN.md](README.zh-CN.md) में है (आर्किटेक्चर, वर्ज़निंग और बैकवर्ड-कम्पैटिबिलिटी); पूरा wire स्पेक: [docs/editor-protocol.md](docs/editor-protocol.md) / [docs/editor-protocol.zh-CN.md](docs/editor-protocol.zh-CN.md)।
+
 ## यह प्लगइन आपके एजेंट को क्या देता है
 
 आधिकारिक DeepSeek Harness `ctx.lsp` seam **नेविगेशन** (go-to-definition, references, implementation, hover) को कवर करता है। `dsh-lsp-actions` **एक्शन सतह** को पूरा करता है — वह फीडबैक लूप जिसकी एक एजेंट को कोड लिखते और ठीक करते समय ज़रूरत होती है:
@@ -172,6 +177,12 @@ pnpm run test:coverage   # द्वार: पंक्तियाँ/कथ
 pnpm build           # lib/ उत्पन्न करता है
 ```
 
+## योगदानकर्ता
+
+इस प्रोजेक्ट में योगदान देने वाले सभी लोगों का धन्यवाद:
+
+- [PerryLink](https://github.com/PerryLink) — प्लगइन स्वयं: LSP एक्शन क्लाइंट व server जीवनचक्र, सभी आठ टूल, टेस्ट, CI और दस्तावेज़ीकरण।
+
 ## License
 
 [Apache License 2.0](LICENSE)

package/README.md

@@ -2,13 +2,14 @@
 
 # 🛰️ dsh-lsp-actions
 
-**The LSP action surface for DeepSeek Harness — real language servers, real feedback.**
+**The LSP action surface for DeepSeek Harness — real language servers, real feedback, and the IDE integration backend for editors.**
 
-Diagnostics, formatting, code completion, quickfixes, symbols, signature help, inlay hints, and workspace-wide rename for your agent's editor loop, powered by the same language servers your IDE uses.
+Diagnostics, formatting, code completion, quickfixes, symbols, signature help, inlay hints, and workspace-wide rename for your agent's editor loop, powered by the same language servers your IDE uses — plus a stable **editor action protocol** (`lsp.actions.list` / `lsp.actions.run` / `lsp.events`) that lets any editor (VS Code first) consume those capabilities directly over JSON-RPC.
 
 [![Topic: dsh](https://img.shields.io/badge/Topic-dsh-4D6BFE?style=for-the-badge)](https://github.com/topics/dsh)
 [![Topic: dsh-plugin](https://img.shields.io/badge/Topic-dsh--plugin-8257D0?style=for-the-badge)](https://github.com/topics/dsh-plugin)
 [![CI](https://github.com/PerryLink/dsh-lsp-actions/actions/workflows/ci.yml/badge.svg)](https://github.com/PerryLink/dsh-lsp-actions/actions/workflows/ci.yml)
+[![npm downloads](https://img.shields.io/npm/dw/dsh-lsp-actions?style=flat-square)](https://www.npmjs.com/package/dsh-lsp-actions)
 [![npm](https://img.shields.io/npm/v/dsh-lsp-actions?style=flat-square)](https://www.npmjs.com/package/dsh-lsp-actions)
 [![License](https://img.shields.io/badge/License-Apache%202.0-D22128?style=flat-square)](LICENSE)
 [![Node](https://img.shields.io/badge/Node-%5E22.19%20%7C%7C%20%3E%3D24-43853D?style=flat-square)](package.json)
@@ -39,7 +40,13 @@ The official DeepSeek Harness `ctx.lsp` seam covers **navigation** (go-to-defini
 ## Quick start
 
 ```sh
-dsh plugin --profile <name> add <path-or-tarball-of-dsh-lsp-actions>
+dsh plugin --profile <name> add dsh-lsp-actions
+```
+
+Remove it with:
+
+```sh
+dsh plugin --profile <name> remove dsh-lsp-actions
 ```
 
 Configure one entry per language server (the shape mirrors the official `lsp-stdio` config):
@@ -63,6 +70,12 @@ Configure one entry per language server (the shape mirrors the official `lsp-std
             args: [--stdio]
             extensionToLanguage:
               ".py": python
+        # The IDE integration backend — leave disabled in Web/CLI profiles;
+        # enable only in a dedicated headless backend composition (stdout is the wire):
+        editor:
+          enabled: false
+          requestTimeoutMs: 60000
+          diagnosticsCacheMaxFiles: 64
         maxDiagnostics: 200
         maxCompletionItems: 20
         maxCodeActions: 50
@@ -75,6 +88,30 @@ Configure one entry per language server (the shape mirrors the official `lsp-std
 
 The eight tools are always registered. With an **empty `servers` table and no `ctx.lsp` seam mounted, calls fail loudly** with `LSP_ACTION_UNAVAILABLE` telling the user what to configure — the plugin never starts servers you did not configure. A `ctx.lsp` seam mounted **after** this plugin is picked up on the next call (seam detection is per-call, so load order does not matter).
 
+## IDE integration backend: the editor action protocol v1
+
+The plugin is also DSH's **IDE integration backend**. When `editor.enabled: true` is set in a dedicated headless composition, it serves a stable editor protocol over newline-delimited JSON-RPC 2.0 (the same wire framing as the official SDK/ACP transports):
+
+| Method | What it does |
+| --- | --- |
+| `lsp.actions.list` | The `lsp-actions/v1` protocol version, the action catalog (`diagnostics.get`, `completion.get`, `quickfix.apply`, `format` — each flagged `writes`), and the addressable DSH sessions. |
+| `lsp.actions.run` | Executes one action with a structured `{ requestId, action, status, result \| error }` envelope. Errors carry the stable `LSP_ACTION_*` codes below. |
+| `lsp.events` | Subscribes to the streamed `lsp.event` notifications: `diagnostics.updated`, `action.status`, `file.changed`, `sessions.changed`. |
+
+All write actions (`quickfix.apply`, `format`) go through the **official permission presets and approval**: a `read-only` session is refused with `LSP_ACTION_READ_ONLY` before any server round-trip, edits ride the `fs/write-intent` waterfall, and the `sandbox_permissions` + `justification` escalation pair resolves through the official `approveEscalation` ask (fail-closed when no answerer can decide). Full wire spec, bilingual: [`docs/editor-protocol.md`](docs/editor-protocol.md) · [`docs/editor-protocol.zh-CN.md`](docs/editor-protocol.zh-CN.md).
+
+### Versioning and the backward-compatibility promise
+
+- The protocol is versioned — `lsp.actions.list` returns `protocol: "lsp-actions/v1"`, `version: 1`. **v1 is frozen:** field names, action ids, event kinds, and error codes stay stable forever.
+- Evolution is **additive only**: new actions, new fields, and new event kinds arrive without a version bump; existing semantics never change in place; a breaking change ships under a new `protocol` version, which servers may serve side by side.
+- Clients must ignore unknown fields, unknown event kinds, and unknown actions, and route on the stable error `code`, never on message text.
+
+### Minimal VS Code extension
+
+[`examples/vscode/`](examples/vscode/) ships a **UI-only** extension (sidebar with the DSH sessions, the diagnostics list, one-click quickfix apply, open-at-range, and format) plus the headless backend composition (`backend/cordis.yml`) it connects to over ACP-style JSON-RPC. The extension implements zero LSP logic — every capability and every byte written belongs to the plugin. Install steps, settings, and the demo-gif recording script are in [`examples/vscode/README.md`](examples/vscode/README.md).
+
+![Editor demo](docs/editor-demo.gif)
+
 ## Why it is safe by construction
 
 - **Formatting and rename are real mutations, treated like `write`/`edit`.** Every byte goes through the `fs/write-intent` waterfall (observation → guarded write → observation) and the per-call sandbox policy. `lsp_rename` pre-flights every edited file (workspace containment, overlap check, byte-capped read) *before* the first write, so a bad server response cannot leave a half-applied rename.
@@ -83,7 +120,8 @@ The eight tools are always registered. With an **empty `servers` table and no `c
 - **Escalation matches the official tools.** Under a confining filesystem, `lsp_format` and `lsp_rename` advertise the same `sandbox_permissions` / `justification` one-shot retry as `write`/`edit`, resolved through `ctx.approval`.
 - **Conflicts never clobber.** If the file changed on disk after it was read, the guarded write fails with `LSP_ACTION_CONFLICT` and the model is told to choose: re-read and re-run, or apply the diff manually.
 - **Timeouts are the platform's.** Each tool declares `timeoutMs`; the official `dsh-tool-call-timeout-policy` enforces it, and every await honors `exec.signal`.
-- **Nothing is cached.** Results live only in the session log; there is no cross-session persistence.
+- **Nothing is cached on the model path.** Tool results live only in the session log; there is no cross-session persistence. The editor protocol keeps exactly one bounded cache — the LRU diagnostics snapshot cache (config `editor.diagnosticsCacheMaxFiles`), freshness-stamped and invalidated by filesystem observations and the plugin's own writes; it never persists across restarts.
+- **Prompt hygiene.** The plugin injects no persona or prompt prose into the session system prompt — its model-facing surface is the eight tool schemas. Should any future prompt segment be added, it must open with one short role sentence and stay brief (aligned with the official Minimal persona style: `You are a helpful software engineer assistant.`).
 - **Bad servers fail loudly.** A missing executable fails at load; a server that dies at startup fails the call with `LSP_ACTION_SERVER_FAILED` plus its stderr tail (after one fresh-spawn retry).
 
 ## Architecture
@@ -103,12 +141,42 @@ lsp_symbols / lsp_signature / lsp_inlay_hints / lsp_rename
 
 The seam extension is proposed upstream (`upstream/lsp-action-seam.patch`, PR description in `upstream/PR-description.md`). Once it lands, the plugin keeps working unchanged — the built-in client simply stops being used. The built-in client stays as the standalone fallback for the `servers` table. Full research and design notes: [`docs/seam-extension-notes.md`](docs/seam-extension-notes.md).
 
+The **editor protocol** rides the same runner, the same write path, and the same permission machinery:
+
+```
+                 ┌────────────────────────────────────────────────────┐
+                 │ one DSH runtime (headless editor backend)           │
+ VS Code (UI) ───┤  editor action protocol — this plugin               │
+                 │  lsp.actions.list / run / lsp.events                │
+                 │  (editor.enabled: true; same seam-first runner)     │
+                 ├────────────────────────────────────────────────────┤
+ official ACP ───┤  @deepseek-ai/dsh-acp — agent chat sessions         │
+ clients         │  session/new · prompt · session/request_permission  │
+                 ├────────────────────────────────────────────────────┤
+ Python SDK ─────┤  @deepseek-ai/dsh-sdk-jsonrpc-server               │
+ (deepseek-      │  session/prompt · session.event notifications       │
+  harness-sdk)   └────────────────────────────────────────────────────┘
+```
+
+- **Official ACP server** is the agent-conversation transport; its sessions' agents call the `lsp_*` tools, and an ACP client answers editor write escalations through `session/request_permission` (see [`docs/editor-protocol.md`](docs/editor-protocol.md)).
+- **Python SDK** (`pip install deepseek-harness-sdk`) drives the same runtime over the official SDK wire; since the editor protocol shares that wire's framing, SDK-grade clients can call `lsp.actions.*` unchanged.
+
 ## Configuration reference
 
 ```ts
 interface Config {
   /** Named language servers; empty = the plugin's own client serves nothing. */
   servers?: Record<string, LspServerEntry>
+  /** Editor action protocol (the IDE integration backend). */
+  editor?: {
+    /** Serve lsp.actions.* over JSON-RPC stdio. Default false — enable only in a
+     *  dedicated headless backend composition whose stdout nothing else claims. */
+    enabled?: boolean             // default false
+    /** Per-run timeout budget in ms, enforced inside the plugin. */
+    requestTimeoutMs?: number     // default 60000
+    /** Bounded LRU diagnostics-cache size in files (least-recently-used eviction). */
+    diagnosticsCacheMaxFiles?: number  // default 64
+  }
   maxDiagnostics?: number        // default 200
   maxCompletionItems?: number    // default 20
   maxCodeActions?: number        // default 50
@@ -153,10 +221,14 @@ Every failure carries a stable `code` on the error result; models and callers ro
 | `LSP_ACTION_READ_ONLY` | The session's sandbox mode forbids the formatting/rename write. |
 | `LSP_ACTION_WORKSPACE_REQUIRED` | The calling session has no workspace cwd to root the server in. |
 | `LSP_ACTION_NO_SYMBOL` | The server found no renameable symbol at the cursor position. |
+| `LSP_ACTION_UNKNOWN` | Editor protocol: unknown action id, or no code action matched `title`/`index`. |
+| `LSP_ACTION_INVALID_ARGS` | Editor protocol: malformed action parameters. |
+| `LSP_ACTION_APPROVAL_UNAVAILABLE` | Editor protocol: the official approval path could not grant a wider sandbox mode (fail-closed). |
+| `LSP_PROTOCOL_VERSION_UNSUPPORTED` | Editor protocol: the run declared a protocol version this server does not speak. |
 
 ### Host version support
 
-The plugin declares its DeepSeek Harness packages as **peer dependencies** (`@deepseek-ai/dsh-fs`, `dsh-llm`, `dsh-sandbox`, `dsh-subprocess`, `dsh-tools` ≥ `0.1.0-rc.6`), so one copy serves both the host and the plugin. Tested against `0.1.0-rc.6`.
+The plugin declares its DeepSeek Harness packages as **peer dependencies** (`@deepseek-ai/dsh-fs`, `dsh-llm`, `dsh-sandbox`, `dsh-subprocess`, `dsh-tools` ≥ `0.1.0-rc.6`), so one copy serves both the host and the plugin. Tested against `0.1.0-rc.6`; last verified 2026-08-15.
 
 ### Known limitations
 
@@ -169,15 +241,45 @@ The plugin declares its DeepSeek Harness packages as **peer dependencies** (`@de
 ```sh
 pnpm install
 pnpm run lint        # oxlint over src/ and tests/
-pnpm test            # 240+ tests: unit + fixture-server integration + real tsls e2e
+pnpm test            # 290+ tests: unit + fixture-server integration + editor-protocol e2e + real tsls e2e
 pnpm run test:coverage   # gates: lines/statements/functions ≥ 90%, branches ≥ 85%
 pnpm build           # emits lib/
 ```
 
+The editor protocol has dedicated coverage: [`tests/editor-cache.spec.ts`](tests/editor-cache.spec.ts) (bounded LRU), [`tests/editor-protocol.spec.ts`](tests/editor-protocol.spec.ts) (service semantics, permission gating, timeouts, and the full diagnostics → quickfix → format chain over JSON-RPC frames against the fixture LSP server). The `examples/vscode/` backend and extension are standalone npm projects — see [`examples/vscode/README.md`](examples/vscode/README.md).
+
 ### Releasing
 
 CI runs the lint/build/test matrix plus the coverage gate on every push and pull request. Pushing a `v*` tag triggers the publish workflow, which verifies the suite and publishes the package to npm — it needs an `NPM_TOKEN` Actions secret (a publish-scoped npm access token) set once on the repository. The version is bumped manually in `package.json`/`CHANGELOG.md` before tagging.
 
+## Contributors
+
+Thanks to everyone who has contributed to this project:
+
+- [PerryLink](https://github.com/PerryLink) — the plugin itself: the LSP action client and server lifecycle, all eight tools, tests, CI, and documentation.
+
+## PerryLink DSH Plugin Family
+
+This project is one of the [15 DeepSeek Harness plugins](https://github.com/PerryLink) maintained by [PerryLink](https://github.com/PerryLink). If this one helps you, the others likely will too:
+
+| Plugin | One-liner |
+|---|---|
+| [dsh-mcp-panel](https://github.com/PerryLink/dsh-mcp-panel) | Read-only MCP runtime panel: /mcp command + Settings tab with status, tools and errors |
+| [dsh-doublecheck](https://github.com/PerryLink/dsh-doublecheck) | Engineering-discipline guard: requirements grill, test gates, adversary review |
+| [dsh-background-agents](https://github.com/PerryLink/dsh-background-agents) | Durable background child agents with a Web UI sidebar, messaging and interrupt |
+| **[dsh-lsp-actions](https://github.com/PerryLink/dsh-lsp-actions)** | LSP diagnostics, formatting, completion, code actions and rename over language servers |
+| [dsh-output-styles](https://github.com/PerryLink/dsh-output-styles) | Claude Code outputStyles-equivalent runtime style switching |
+| [dsh-checkpoint-rewind](https://github.com/PerryLink/dsh-checkpoint-rewind) | Claude Code /rewind-equivalent: snapshots, session forks, one-shot restore |
+| [dsh-permission-rules](https://github.com/PerryLink/dsh-permission-rules) | Claude Code-style declarative allow/deny/ask permission rules with audit |
+| [dsh-auto-review](https://github.com/PerryLink/dsh-auto-review) | Second-model auto-review on the approval chain, fail-closed by default |
+| [dsh-memento](https://github.com/PerryLink/dsh-memento) | Approval-gated cross-session memory: ctx.memory seam + SQLite + memory tool |
+| [dsh-skill-pack-security](https://github.com/PerryLink/dsh-skill-pack-security) | Security-audit skill pack: secret scan, dependency and supply-chain review |
+| [dsh-session-pin](https://github.com/PerryLink/dsh-session-pin) | Pin sessions in the Web sidebar with durable ordering |
+| [dsh-composer-history](https://github.com/PerryLink/dsh-composer-history) | Terminal-style input history for the web composer: arrows, Ctrl+R search |
+| [dsh-github](https://github.com/PerryLink/dsh-github) | GitHub PR/issues integration for DSH, every write gated by approval |
+| [dsh-plugin-guide](https://github.com/PerryLink/dsh-plugin-guide) | Plugin-development knowledge base as an on-demand agent skill |
+| [dsh-claude-move](https://github.com/PerryLink/dsh-claude-move) | Migrate Claude Code sessions, memory, skills and CLAUDE.md into DSH |
+
 ## License
 
 [Apache License 2.0](LICENSE)

package/README.pt.md

@@ -8,6 +8,9 @@ Diagnósticos, formatação, autocompletar de código, correções rápidas, sí
 
 [![Topic: dsh](https://img.shields.io/badge/Topic-dsh-4D6BFE?style=for-the-badge)](https://github.com/topics/dsh)
 [![Topic: dsh-plugin](https://img.shields.io/badge/Topic-dsh--plugin-8257D0?style=for-the-badge)](https://github.com/topics/dsh-plugin)
+[![CI](https://github.com/PerryLink/dsh-lsp-actions/actions/workflows/ci.yml/badge.svg)](https://github.com/PerryLink/dsh-lsp-actions/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/dsh-lsp-actions?style=flat-square)](https://www.npmjs.com/package/dsh-lsp-actions)
+[![npm downloads](https://img.shields.io/npm/dw/dsh-lsp-actions?style=flat-square)](https://www.npmjs.com/package/dsh-lsp-actions)
 [![License](https://img.shields.io/badge/License-Apache%202.0-D22128?style=flat-square)](LICENSE)
 [![Node](https://img.shields.io/badge/Node-%5E22.19%20%7C%7C%20%3E%3D24-43853D?style=flat-square)](package.json)
 
@@ -17,6 +20,8 @@ Diagnósticos, formatação, autocompletar de código, correções rápidas, sí
 
 ---
 
+> **Novo (v0.3.0):** backend de integração IDE — o protocolo de ações para editores `lsp.actions.list` / `lsp.actions.run` / `lsp.events` (v1) e o exemplo mínimo de VS Code. A especificação canônica do protocolo está em [README.md](README.md) e [README.zh-CN.md](README.zh-CN.md) (arquitetura, versionamento e compatibilidade retroativa); a especificação completa do wire: [docs/editor-protocol.md](docs/editor-protocol.md) / [docs/editor-protocol.zh-CN.md](docs/editor-protocol.zh-CN.md).
+
 ## O que este plugin dá ao seu agente
 
 O seam oficial `ctx.lsp` do DeepSeek Harness cobre **navegação** (ir para definição, referências, implementação, hover). O `dsh-lsp-actions` completa a **superfície de ação** — o loop de feedback que um agente precisa enquanto escreve e corrige código:
@@ -172,6 +177,12 @@ pnpm run test:coverage   # portões: linhas/instruções/funções ≥ 90%, ramo
 pnpm build           # emite lib/
 ```
 
+## Contribuidores
+
+Obrigado a todos que contribuíram com este projeto:
+
+- [PerryLink](https://github.com/PerryLink) — o plugin em si: o cliente de ações LSP e o ciclo de vida do servidor, as oito ferramentas, os testes, a CI e a documentação.
+
 ## License
 
 [Apache License 2.0](LICENSE)

package/README.zh-CN.md

@@ -2,12 +2,15 @@
 
 # 🛰️ dsh-lsp-actions
 
-**DeepSeek Harness 的 LSP 动作面 —— 真实的语言服务器，真实的反馈。**
+**DeepSeek Harness 的 LSP 动作面 —— 真实的语言服务器，真实的反馈，以及面向编辑器的 IDE 集成后端。**
 
-为你的 agent 编辑循环提供诊断、格式化、补全、快速修复、符号、签名提示与内联提示，驱动它们的正是你 IDE 所用的那些语言服务器。
+为你的 agent 编辑循环提供诊断、格式化、补全、快速修复、符号、签名提示与内联提示，驱动它们的正是你 IDE 所用的那些语言服务器 —— 并提供稳定的**编辑器 action 协议**（`lsp.actions.list` / `lsp.actions.run` / `lsp.events`），让任何编辑器（先行 VS Code）通过 JSON-RPC 直接消费这些能力。
 
 [![Topic: dsh](https://img.shields.io/badge/Topic-dsh-4D6BFE?style=for-the-badge)](https://github.com/topics/dsh)
 [![Topic: dsh-plugin](https://img.shields.io/badge/Topic-dsh--plugin-8257D0?style=for-the-badge)](https://github.com/topics/dsh-plugin)
+[![CI](https://github.com/PerryLink/dsh-lsp-actions/actions/workflows/ci.yml/badge.svg)](https://github.com/PerryLink/dsh-lsp-actions/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/dsh-lsp-actions?style=flat-square)](https://www.npmjs.com/package/dsh-lsp-actions)
+[![npm downloads](https://img.shields.io/npm/dw/dsh-lsp-actions?style=flat-square)](https://www.npmjs.com/package/dsh-lsp-actions)
 [![License](https://img.shields.io/badge/License-Apache%202.0-D22128?style=flat-square)](LICENSE)
 [![Node](https://img.shields.io/badge/Node-%5E22.19%20%7C%7C%20%3E%3D24-43853D?style=flat-square)](package.json)
 
@@ -37,7 +40,13 @@
 ## 快速开始
 
 ```sh
-dsh plugin --profile <name> add <path-or-tarball-of-dsh-lsp-actions>
+dsh plugin --profile <name> add dsh-lsp-actions
+```
+
+卸载：
+
+```sh
+dsh plugin --profile <name> remove dsh-lsp-actions
 ```
 
 每个语言服务器配一条 entry（形态与官方 `lsp-stdio` 配置一致）：
@@ -61,6 +70,12 @@ dsh plugin --profile <name> add <path-or-tarball-of-dsh-lsp-actions>
             args: [--stdio]
             extensionToLanguage:
               ".py": python
+        # IDE 集成后端 —— Web/CLI profile 请保持关闭；只在专用 headless
+        # 后端组合中开启（stdout 即协议线）：
+        editor:
+          enabled: false
+          requestTimeoutMs: 60000
+          diagnosticsCacheMaxFiles: 64
         maxDiagnostics: 200
         maxCompletionItems: 20
         maxCodeActions: 50
@@ -73,6 +88,30 @@ dsh plugin --profile <name> add <path-or-tarball-of-dsh-lsp-actions>
 
 八个工具**始终注册**。当 `servers` 表为空且没有挂载 `ctx.lsp` seam 时，调用会**响亮失败**（`LSP_ACTION_UNAVAILABLE`，错误信息指明该配置什么）—— 插件绝不会启动你没有配置的服务器。**在插件之后**挂载的 `ctx.lsp` seam 会在下一次调用时被识别（seam 探测按调用惰性解析，加载顺序无关）。
 
+## IDE 集成后端：编辑器 action 协议 v1
+
+本插件同时是 DSH 的 **IDE 集成后端**。在专用 headless 组合中设置 `editor.enabled: true` 后，它通过换行分帧的 JSON-RPC 2.0（与官方 SDK/ACP 传输同一线格式）提供稳定的编辑器协议：
+
+| 方法 | 作用 |
+| --- | --- |
+| `lsp.actions.list` | 返回 `lsp-actions/v1` 协议版本、动作目录（`diagnostics.get`、`completion.get`、`quickfix.apply`、`format`，逐个标注 `writes`）与可寻址的 DSH 会话。 |
+| `lsp.actions.run` | 执行一个动作，返回结构化 `{ requestId, action, status, result \| error }` 信封。错误携带下方稳定的 `LSP_ACTION_*` 码。 |
+| `lsp.events` | 订阅流式 `lsp.event` 通知：`diagnostics.updated`、`action.status`、`file.changed`、`sessions.changed`。 |
+
+所有写动作（`quickfix.apply`、`format`）都走**官方权限预设与审批**：`read-only` 会话在任何服务器往返前以 `LSP_ACTION_READ_ONLY` 拒绝；编辑走 `fs/write-intent` waterfall；`sandbox_permissions` + `justification` 升级对经官方 `approveEscalation` 询问（无应答方时 fail-closed）。完整线上规范（双语）：[`docs/editor-protocol.md`](docs/editor-protocol.md) · [`docs/editor-protocol.zh-CN.md`](docs/editor-protocol.zh-CN.md)。
+
+### 版本化与向后兼容承诺
+
+- 协议带版本 —— `lsp.actions.list` 返回 `protocol: "lsp-actions/v1"`、`version: 1`。**v1 已冻结：**字段名、动作 id、事件类型与错误码永久稳定。
+- 演进**只做加法**：新动作、新字段、新事件类型无需升版本；既有语义绝不原地变更；破坏性变更以新的 `protocol` 版本发布，服务端可并行服务多版本。
+- 客户端必须忽略未知字段、未知事件类型与未知动作，并按稳定错误 `code` 路由，绝不解析消息文本。
+
+### 最小 VS Code 扩展
+
+[`examples/vscode/`](examples/vscode/) 附带**纯 UI** 扩展（侧栏：DSH 会话、诊断列表、quickfix 一键应用、点击定位、格式化）及其经 ACP 风格 JSON-RPC 连接的 headless 后端组合（`backend/cordis.yml`）。扩展不实现任何 LSP 逻辑——所有能力与每一笔写入都属于插件。安装步骤、设置项与动图录制脚本见 [`examples/vscode/README.md`](examples/vscode/README.md)。
+
+![编辑器演示](docs/editor-demo.gif)
+
 ## 为什么按构造就安全
 
 - **格式化与重命名是真实写入，按 `write`/`edit` 同等对待。** 每个字节都经过 `fs/write-intent` waterfall（观测 → 守卫写 → 观测）与每次调用的沙箱策略。`lsp_rename` 会在第一笔写入**之前**对每个待改文件做预检（工作区包含性、重叠检查、字节上限读取），坏服务器响应不可能留下写了一半的重命名。
@@ -81,7 +120,8 @@ dsh plugin --profile <name> add <path-or-tarball-of-dsh-lsp-actions>
 - **升级路径与官方工具一致。** 在受限文件系统下，`lsp_format` 与 `lsp_rename` 广告与 `write`/`edit` 相同的 `sandbox_permissions` / `justification` 一次性重试，经 `ctx.approval` 裁决。
 - **冲突绝不覆盖。** 若文件在读后被改动，守卫写以 `LSP_ACTION_CONFLICT` 失败，并让模型二选一：重读后重跑，或手工应用 diff。
 - **超时是平台职责。** 每个工具声明 `timeoutMs`，由官方 `dsh-tool-call-timeout-policy` 执行，所有 await 尊重 `exec.signal`。
-- **不缓存任何东西。** 结果只存在于会话日志，无跨会话持久化。
+- **模型路径不缓存任何东西。** 结果只存在于会话日志，无跨会话持久化。编辑器协议只有一处有界缓存 —— LRU 诊断快照缓存（配置 `editor.diagnosticsCacheMaxFiles`），带新鲜度戳，随文件系统观察与本插件自身写入失效，绝不跨重启持久化。
+- **提示词卫生。** 本插件不向会话系统提示词注入任何 persona 或提示词段落——面向模型的接口只有八个工具 Schema。若未来新增任何提示词段落，必须以一句简短角色陈述开头并保持短小（对齐官方 Minimal persona 风格：`You are a helpful software engineer assistant.`）。
 - **坏服务器响亮失败。** 命令缺失在加载期即失败；启动即死的服务器以 `LSP_ACTION_SERVER_FAILED` + stderr 尾部失败（启动失败先自动换新进程重试一次）。
 
 ## 架构
@@ -101,12 +141,42 @@ lsp_symbols / lsp_signature / lsp_inlay_hints / lsp_rename
 
 seam 扩展已向上游提案（`upstream/lsp-action-seam.patch`，PR 描述见 `upstream/PR-description.md`）。合入后插件无需改动即自动迁移 —— 内置客户端停止被使用即可。内置客户端会保留为 `servers` 表的独立兜底。完整调研与设计笔记：[`docs/seam-extension-notes.md`](docs/seam-extension-notes.md)、[`upstream/README.md`](upstream/README.md)。
 
+**编辑器协议**复用同一 runner、同一写入路径与同一权限机制：
+
+```
+                 ┌────────────────────────────────────────────────────┐
+                 │ 一个 DSH 运行时（headless 编辑器后端）             │
+ VS Code（UI）───┤  编辑器 action 协议 —— 本插件                      │
+                 │  lsp.actions.list / run / lsp.events               │
+                 │  (editor.enabled: true；同一 seam-first runner)    │
+                 ├────────────────────────────────────────────────────┤
+ 官方 ACP ───────┤  @deepseek-ai/dsh-acp —— agent 对话会话            │
+ 客户端          │  session/new · prompt · session/request_permission │
+                 ├────────────────────────────────────────────────────┤
+ Python SDK ─────┤  @deepseek-ai/dsh-sdk-jsonrpc-server               │
+ (deepseek-      │  session/prompt · session.event 通知               │
+  harness-sdk)   └────────────────────────────────────────────────────┘
+```
+
+- **官方 ACP server** 是 agent 对话传输；其会话中的 agent 可调用 `lsp_*` 工具，ACP 客户端经 `session/request_permission` 应答编辑器写升级（见 [`docs/editor-protocol.md`](docs/editor-protocol.md)）。
+- **Python SDK**（`pip install deepseek-harness-sdk`）经官方 SDK 线驱动同一运行时；编辑器协议与其共享线格式，SDK 级客户端可直接调用 `lsp.actions.*`。
+
 ## 配置参考
 
 ```ts
 interface Config {
   /** 命名的语言服务器；为空 = 插件自带客户端不服务任何文件。 */
   servers?: Record<string, LspServerEntry>
+  /** 编辑器 action 协议（IDE 集成后端）。 */
+  editor?: {
+    /** 经 JSON-RPC stdio 服务 lsp.actions.*。默认 false —— 只在专用 headless
+     *  后端组合中开启，该组合的 stdout 不得被任何其他东西占用。 */
+    enabled?: boolean             // 默认 false
+    /** 每次运行超时预算（毫秒），插件内部强制。 */
+    requestTimeoutMs?: number     // 默认 60000
+    /** 有界 LRU 诊断缓存大小（按文件计，LRU 淘汰）。 */
+    diagnosticsCacheMaxFiles?: number  // 默认 64
+  }
   maxDiagnostics?: number        // 默认 200
   maxCompletionItems?: number    // 默认 20
   maxCodeActions?: number        // 默认 50
@@ -151,10 +221,14 @@ interface LspServerEntry {
 | `LSP_ACTION_READ_ONLY` | 会话沙箱模式禁止格式化/重命名写入。 |
 | `LSP_ACTION_WORKSPACE_REQUIRED` | 调用会话没有可扎根的 workspace cwd。 |
 | `LSP_ACTION_NO_SYMBOL` | 服务器在光标位置找不到可重命名的符号。 |
+| `LSP_ACTION_UNKNOWN` | 编辑器协议：未知动作 id，或没有 code action 匹配 `title`/`index`。 |
+| `LSP_ACTION_INVALID_ARGS` | 编辑器协议：动作参数不合法。 |
+| `LSP_ACTION_APPROVAL_UNAVAILABLE` | 编辑器协议：官方审批路径未能授予更宽沙箱模式（fail-closed）。 |
+| `LSP_PROTOCOL_VERSION_UNSUPPORTED` | 编辑器协议：该运行声明的协议版本不被本服务端支持。 |
 
 ### 宿主版本支持
 
-插件把 DeepSeek Harness 各包声明为 **peerDependencies**（`@deepseek-ai/dsh-fs`、`dsh-llm`、`dsh-sandbox`、`dsh-subprocess`、`dsh-tools` ≥ `0.1.0-rc.6`），宿主与插件共享同一份副本。已在 `0.1.0-rc.6` 上实测。
+插件把 DeepSeek Harness 各包声明为 **peerDependencies**（`@deepseek-ai/dsh-fs`、`dsh-llm`、`dsh-sandbox`、`dsh-subprocess`、`dsh-tools` ≥ `0.1.0-rc.6`），宿主与插件共享同一份副本。已在 `0.1.0-rc.6` 上实测，最后验证日期 2026-08-15。
 
 ### 已知限制
 
@@ -167,15 +241,45 @@ interface LspServerEntry {
 ```sh
 pnpm install
 pnpm run lint        # oxlint 检查 src/ 与 tests/
-pnpm test            # 240+ 测试：单元 + fixture 服务器集成 + 真实 tsls e2e
+pnpm test            # 290+ 测试：单元 + fixture 服务器集成 + 编辑器协议 e2e + 真实 tsls e2e
 pnpm run test:coverage   # 门禁：行/语句/函数 ≥ 90%，分支 ≥ 85%
 pnpm build           # 产出 lib/
 ```
 
+编辑器协议有专属覆盖：[`tests/editor-cache.spec.ts`](tests/editor-cache.spec.ts)（有界 LRU）、[`tests/editor-protocol.spec.ts`](tests/editor-protocol.spec.ts)（服务语义、权限门禁、超时，以及经 JSON-RPC 帧对 fixture LSP 服务器的诊断 → quickfix → format 全链路）。`examples/vscode/` 的后端与扩展是独立的 npm 工程 —— 见 [`examples/vscode/README.md`](examples/vscode/README.md)。
+
 ### 发布
 
 CI 在每次推送与 PR 上运行 lint/构建/测试矩阵 + 覆盖率门禁。推送 `v*` tag 会触发发布工作流：先验证全套测试再发布到 npm —— 需要在仓库里一次性配置 `NPM_TOKEN` Actions secret（发布权限的 npm access token）。版本号在打 tag 前于 `package.json` / `CHANGELOG.md` 中手动提升。
 
+## 贡献者
+
+感谢为本项目做出贡献的每一个人：
+
+- [PerryLink](https://github.com/PerryLink) —— 插件本体：LSP 动作客户端与服务器生命周期、全部八个工具、测试、CI 与文档。
+
+## PerryLink DSH 插件家族
+
+本项目是 [PerryLink](https://github.com/PerryLink) 维护的 [15 个 DeepSeek Harness 插件](https://github.com/PerryLink)之一。如果你觉得这个插件有用，其余的很可能同样有用：
+
+| 插件 | 一句话说明 |
+|---|---|
+| [dsh-mcp-panel](https://github.com/PerryLink/dsh-mcp-panel) | 只读 MCP 运行时面板：/mcp 命令 + 设置页，状态/工具/错误一览 |
+| [dsh-doublecheck](https://github.com/PerryLink/dsh-doublecheck) | 工程纪律守门：需求审讯、测试证据门、对抗评审 |
+| [dsh-background-agents](https://github.com/PerryLink/dsh-background-agents) | 持久化后台子代理：Web 侧边栏进度、随时留言与打断 |
+| **[dsh-lsp-actions](https://github.com/PerryLink/dsh-lsp-actions)** | 基于语言服务器的诊断/格式化/补全/代码动作/重命名 |
+| [dsh-output-styles](https://github.com/PerryLink/dsh-output-styles) | 对标 Claude Code outputStyles 的运行时风格切换 |
+| [dsh-checkpoint-rewind](https://github.com/PerryLink/dsh-checkpoint-rewind) | 对标 Claude Code /rewind：快照、会话 fork、一键回退 |
+| [dsh-permission-rules](https://github.com/PerryLink/dsh-permission-rules) | Claude Code 风格声明式 allow/deny/ask 权限规则，带审计 |
+| [dsh-auto-review](https://github.com/PerryLink/dsh-auto-review) | 审批链上的第二模型自动审查，默认 fail-closed |
+| [dsh-memento](https://github.com/PerryLink/dsh-memento) | 带审批门的跨会话记忆：ctx.memory + SQLite + memory 工具 |
+| [dsh-skill-pack-security](https://github.com/PerryLink/dsh-skill-pack-security) | 安全审计技能包：密钥扫描、依赖与供应链审查 |
+| [dsh-session-pin](https://github.com/PerryLink/dsh-session-pin) | 在 Web 侧边栏置顶会话，持久排序 |
+| [dsh-composer-history](https://github.com/PerryLink/dsh-composer-history) | Web 作曲器终端式输入历史：方向键、Ctrl+R 搜索 |
+| [dsh-github](https://github.com/PerryLink/dsh-github) | DSH 的 GitHub PR/issue 集成，所有写操作经审批门 |
+| [dsh-plugin-guide](https://github.com/PerryLink/dsh-plugin-guide) | 插件开发知识库，随 bundle 安装的按需 agent 技能 |
+| [dsh-claude-move](https://github.com/PerryLink/dsh-claude-move) | 把 Claude Code 会话、记忆、技能和 CLAUDE.md 迁入 DSH |
+
 ## License
 
 [Apache License 2.0](LICENSE)

package/cordis.patch.yml

@@ -1,12 +1,18 @@
 # LSP action surface: diagnostics, formatting, completion, code actions, symbols, signature
 # help, inlay hints, and rename over language servers.
 # Default config activates no servers (empty table); add one entry per language server.
+# editor.enabled: false keeps the IDE integration backend off (Web/CLI profiles own stdio);
+# enable it only in a dedicated headless backend composition (see examples/vscode/backend).
 - insert:
     - id: lsp-actions
       name: dsh-lsp-actions
       inject: [tools, fs, subprocess]
       config:
         servers: {}
+        editor:
+          enabled: false
+          requestTimeoutMs: 60000
+          diagnosticsCacheMaxFiles: 64
         maxDiagnostics: 200
         maxCompletionItems: 20
         maxCodeActions: 50