docs: API 4 调试适配器插件指南，等级表与示例补上 LLDB

README.md

@@ -54,11 +54,14 @@ Lithe 读取并校验 `plugin.json`，然后自己启动其中声明的外部进
 | --- | --- | --- |
 | `1` | 语言、语言服务器（随包附带或使用用户安装的命令）、运行和测试 | Lua、Go、PHP |
 | `2` | 增加：用 Node.js / Java 运行时启动、启动模板、插件设置、工具窗口和命令 | — |
-| `3` | 增加：按能力声明版本（`requires`）、声明式构建系统、构建后端 | Gradle、Maven、Cargo |
+| `3` | 增加：按能力声明版本（`requires`）、声明式构建系统、构建后端、VCS 提供者 | Gradle、Maven、Cargo |
+| `4` | 增加：调试适配器（`debugAdapters`，DAP 进程）、用选定的运行时启动适配器 | LLDB（预发布） |
 
 三个版本号不要混淆：`schemaVersion` 永远是 `2`，表示清单格式；`pluginAPIVersion` 是上表的等级；`version` 是你自己插件的版本。
 
-API 3 必须在 `requires` 里逐项列出实际用到的能力。例如只用声明式构建系统时写 `"requires": { "buildSystems": 1 }`，不要多写。
+API 3 及以上必须在 `requires` 里逐项列出实际用到的能力。例如只用声明式构建系统时写 `"requires": { "buildSystems": 1 }`，不要多写。
+
+API 4 需要 Lithe 明确支持 API 4：旧版 Lithe 在插件市场里会提示升级，而不是安装。目前只有 macOS 宿主实现了调试适配器。
 
 ## 在编辑器里校验 plugin.json
 
@@ -118,13 +121,15 @@ SDK 的源码都在本仓库的 `sdk/` 下，发布在[本仓库的 Releases](ht
 | [Gradle](https://github.com/Lithe-IDEA/lithe-plugin-gradle) | 3 | 纯声明式构建系统，不需要后端 |
 | [Maven](https://github.com/Lithe-IDEA/lithe-plugin-maven) | 3 | 用 Java SDK 写的构建后端 |
 | [Cargo](https://github.com/Lithe-IDEA/lithe-plugin-cargo) | 3 | 用 Node.js SDK 写的构建后端和插件设置 |
+| [LLDB](https://github.com/Lithe-IDEA/lithe-plugin-lldb) | 4 | 调试适配器的参考实现；用 Xcode 自带的 `lldb-dap` 调试 C、C++、Swift 和 Rust，含 `executable` 查找和调试控制台补全 |
 
 ## 教程
 
 | 教程 | 内容 |
 | --- | --- |
 | [LSP 插件完整生命周期](guides/lsp-plugin-lifecycle.md) | 从 Lua 模板开始：清单、服务器打包、激活、状态目录、停止、升级与卸载 |
 | [构建、运行与测试接入](guides/build-tool-integration.md) | 可用的执行提供者示例、工程后端边界，以及开发中的 API 3 状态 |
+| [编写调试适配器插件](guides/debug-adapter-plugin.md) | API 4：从最小清单到启动方式、先编译再调试的 `executable`、调试控制台补全，以及预发布与转正 |
 
 收录和上架的规则由 Lithe Store 维护：[发布社区插件](https://github.com/Lithe-IDEA/Lithe-store/blob/main/docs/publishing.md)讲怎么打包、提交收录和发布新版本，[版本追踪与更新](https://github.com/Lithe-IDEA/Lithe-store/blob/main/docs/versioning-and-updates.md)讲 Lithe 怎么选择可安装的版本。
 

contract.lock.json

@@ -3,12 +3,12 @@
   "source": {
     "repository": "https://github.com/1lck/Lithe-IDEA",
     "directory": "shared/contracts/plugins/v1",
-    "revision": "d046fd1768d00a52b1fc99d45067d06cf535bc23"
+    "revision": "32021a86f0c6c4ad2964dbbe3c2bb7854d84ad67"
   },
   "files": [
     {
       "path": "README.md",
-      "sha256": "87b6738fdd0d764b93f33556992d0586dfb97e68abb58e0bc3a5ac690ec97aab"
+      "sha256": "75cf6add5c473eb333caca793dc9add6394476c7f4c5196b2bf5f1aea7873d59"
     },
     {
       "path": "fixtures/backend.plugin.json",
@@ -50,6 +50,14 @@
       "path": "fixtures/command-plans.json",
       "sha256": "a188fd65f6cdb47f9e9ad4b0de3a7ddcd17e4e577b34f6e25b96d2c1f2bdca7c"
     },
+    {
+      "path": "fixtures/debug-adapter-rejections.json",
+      "sha256": "0aaa586c19884025eb9bee36dc213fbebacc4d0503c3f5ed10a196c922cfaeaf"
+    },
+    {
+      "path": "fixtures/debug-adapter.plugin.json",
+      "sha256": "81038febbde31e0554451789106f8fc255e87038c8185602ce0c7e918f90ff78"
+    },
     {
       "path": "fixtures/function-protocol.json",
       "sha256": "980e8d39db2af9d7f922cdc01b0ec06e2cb8c33da2142ec8040befa975b7eae5"
@@ -160,7 +168,7 @@
     },
     {
       "path": "plugin-manifest.schema.json",
-      "sha256": "a70921c16f1d45e342777fc6f8fe9fc91efa82427d377461d356b8f00054008f"
+      "sha256": "f35d510bf76feeff2978289bebbeba19453cd60b1e101b7677c6106934a27f95"
     }
   ]
 }

contract/v1/README.md

@@ -377,6 +377,7 @@ files sorted by path, or an empty list when no project marker is present.
 | `1` | Languages, `packaged` and `systemCommand` language servers, `node` and `go` runtime dependencies, run and test providers. |
 | `2` | `runtime` launches with a packaged or discovered runtime, host integrations, the `java` runtime, launch templates, `initializationOptions`, and plugin settings. |
 | `3` | Capability versions (`requires`), `buildSystems`: declarative build tools with detection, options, a project model, tasks, run entries, tests, diagnostics, dependencies, and sync, and [`vcsProviders`](#api-level-3-vcs-providers). |
+| `4` | [`debugAdapters`](#api-level-4-debug-adapters) and `serverProcess` 2 (`runSelectedRuntime`). |
 
 A level 2 feature in a level 1 manifest is refused with
 `plugin.manifest.invalid` (`plugin.runtime.unsupported` for the `java` tool),
@@ -407,6 +408,7 @@ hosts. Level 3 versions each section on its own. A level 3 manifest lists in
 | `buildSystems` | Declarative build detection, models, and command plans | `1` |
 | `buildProviders` | `buildSystems[].provider`, including own-process and shared language-server providers | `1` |
 | `vcsProviders` | `vcsProviders[]` | `1` |
+| `debugAdapters` | [`debugAdapters[]`](#api-level-4-debug-adapters) | `1` |
 | `projectGenerators` | [`projectGenerators[]`](#project-generators): entries of the New Project window | `1` |
 | `backend` | [`backend`](#plugin-backend): the plugin's own long-lived process for its pages | `1` |
 
@@ -494,6 +496,8 @@ Rules for publishing across levels and capability versions:
 | `process.test` | any provider declares `test` |
 | `process.build` | `buildSystems` is not empty |
 | `process.vcs` | `vcsProviders` is not empty |
+| `debug.launch` | `debugAdapters` is not empty |
+| `debug.attach` | an adapter lists `attach` in `requests` (and only then) |
 | `project.generate` | `projectGenerators` is not empty |
 | `ui.contribute` | `ui` is declared |
 | `ui.web` | a tool window shows [web content](#web-content-ui-2) |
@@ -507,6 +511,7 @@ Rules for publishing across levels and capability versions:
 | `onTest:<id>` | Activate the test provider when the user lists or runs tests. |
 | `onBuildSystem:<id>` | Activate the build system before its first plan, model, or decode. |
 | `onVcsRoot:<id>` | Start the VCS provider once a root of its VCS is detected in the workspace. |
+| `onDebug:<id>` | Start the debug adapter when a debug session needs it (API level 4). |
 
 Each provider needs its event and each event needs a provider. Enabling a
 plugin only permits activation; nothing starts until its event occurs.
@@ -1007,6 +1012,38 @@ its VCS client (`vcsTool`) and `mayUseNetwork`. Requests go through
 `vcs.decodeReply`. The fields, operations, reply shapes, and error codes are
 defined in [the VCS provider contract](https://github.com/1lck/Lithe-IDEA/blob/preview/shared/contracts/vcs-provider-v1.md).
 
+## API level 4: debug adapters
+
+`debugAdapters[]` declares debug adapters the plugin implements. Each one is a
+DAP process the host starts and talks to over stdio or a loopback TCP port.
+The declaration is data only: there is no resolver, workflow, host integration,
+or `initializationOptions`, and any such field is refused. Requires
+`requires.debugAdapters` 1, `debug.launch` (plus `debug.attach` when an
+adapter serves `attach`), and one `onDebug:<id>` activation event per adapter.
+A manifest below level 4 may not declare `debugAdapters`, and a level 3 manifest may not require `debugAdapters` or `serverProcess` 2.
+
+| Field | Meaning |
+| --- | --- |
+| `id`, `displayName` | Plugin-local ID (unique in the plugin) and its title. |
+| `adapterID` | DAP `initialize.adapterID`; defaults to `id`. |
+| `requests` | `launch` (default) and/or `attach`. |
+| `selectors[]` | Optional automatic matching by `targetKinds` and `languageIDs`; absent means explicit selection only. |
+| `configurationTypes` | Imported `launch.json` `type` values the adapter answers to. |
+| `configurations.launch/attach` | Default DAP `arguments`, a packaged `parametersSchema`, and `targetBindings` (`program` ← `target.path`, `processId` ← `target.processID`, `cwd` ← `target.workingDirectory`). A configuration for an undeclared request is refused. |
+| `configurations.launch.executable` | For a target that is a source file the adapter cannot debug directly (C, C++, Swift): `setting` names a `file` setting of the plugin, `candidates[]` (up to 8) are the paths a host looks for when the user chose nothing. Each candidate starts with `${workspaceFolder}/` or `${fileDirectory}/`, may use `${fileBasenameNoExtension}`, and has no `..`. Declare it together with `targetBindings.program: "target.executable"` and neither without the other; a launch fills `program` with the path the host settled on. The user's setting always wins: a chosen path that is not a runnable file is an error, not a reason to try the candidates. The host shows the path it found in that setting, and the setting's `description` is where the plugin teaches how to produce the program. |
+| `capabilities.disabled` | Standard DAP `supports*` names or `exceptionBreakpointFilters` the host treats as absent. |
+| `console.commandPrefix` | Text (1–8 characters, no spaces; for lldb-dap a backtick) the adapter's console reads as "what follows is a debugger command". The host puts it before the typed line only when it asks the adapter to complete, and moves the adapter's answer back, so the user never sees it. An adapter that treats a bare word as an expression (lldb-dap) otherwise mixes language keywords such as `long` into the first word's completions; the prefix limits them to commands. Declare at least this or `console.commands[]` when `console` is present. |
+| `console.commands[]` | Debugger commands (`name`, optional one-line `description`) the Debug Console offers as completions. An adapter that answers the DAP `completions` request completes live, so list commands only for an adapter that does not (or whose live answers lack some commands); the host merges both. Names are inserted as written, unique, and not padded with spaces; descriptions are shown as written and not translated. |
+| `launch.process` | The shared `serverProcess` launch fields without `initializationOptions`, or `{"launch": {"kind": "runSelectedRuntime", "tool": "python" \| "java" \| "node"}}`, which needs `serverProcess` 2 and is the only use of it. |
+| `launch.transport` | `stdio`, `tcpAnnounced` (`endpoint`: `stream`, one-line `prefix`, `value` = `port` or `hostPort`), or `tcpPort` (`endpoint.port`). TCP endpoints are loopback only. |
+
+The cases in `fixtures/debug-adapter-rejections.json` state the stable code and
+field for each refusal and the layer that reports it: `schema`,
+`coreManifest`, `corePlan` (one start: stale registration or runtime
+selection, a target missing a fact a binding reads), and `coreInstall`
+(a `parametersSchema` that is missing or links outside the package).
+`fixtures/debug-adapter.plugin.json` is a valid example.
+
 ## Plugin backend
 
 A plugin with its own pages may need code that a page cannot run: database