[xiaoyumuxi]

背景

contract/v1 下的 fixtures 平铺在一起，找不到某个功能对应的样例；仓库里也没有一处能看到 API-01–44 全集和每个协议的全部版本；文档只有中文，宿主现状的说法还停在旧稳定版上。这个 PR 做四件事：

1. 同步主仓库 #1747（契约 fixtures 按功能分目录）合入后的契约，并改好仓库内引用的路径；
2. 新增中英双语的 reference/：API 总表、全部版本对照、按功能分页的参考；
3. README 和全部指南改成上中文、下英文的双语页面，宿主现状统一以主仓库最新 preview 为准核对并修正；
4. 新增只有中文的插件协议更新记录，逐个记下哪天、哪个 PR、谁改了哪个协议、能力或 API。

改动

1. 契约同步（contract/、contract.lock.json）

• 用 node scripts/contract.mjs sync 同步到 1lck/Lithe-IDEA@644afdaac（#1747 合入后的 preview），没有手改副本。
• fixtures 改为按功能分目录（backend/、build/、debug/、marketplace/、toolchains/ 等），Java 模板示例按要求保留。
• 644afdaac 的契约内容和此前同步的 0fb748a41 完全相同，锁文件只换了修订号。
• 三个 SDK 测试里读取 function-protocol.json 的路径改为 fixtures/backend/function-protocol.json（Node backend.test.mjs、host.test.mjs，Java BackendTest、HostTest，Rust host_services.rs）。

2. 新增 reference/（中英双语）

• reference/README.md：参考区入口，说明各页的用途和阅读顺序。
• reference/api-catalog.md：API-01–44 总表，每个 API 写明所属领域、清单字段/协议、能力版本、Core/macOS/Windows 现状和对应的参考页。
• reference/capabilities-and-versions.md：每个能力、进程协议、文档格式的全部版本用表格列出，并逐版对照 Rust Core、macOS、Windows 和三个官方 SDK 的支持情况。还有 SDK 各版本要求的协议与 litheLogging 表。核对基准是 preview 644afdaac。
• reference/domains/ 按功能分 15 页：manifest、package-trust、marketplace、languages、editor、settings、ui、backend、build-providers、build-systems、debug-adapters、toolchains、vcs、keymap-import、project-generators。每页列出该领域的字段、版本表、相关 fixture 和宿主对照。

3. README 与指南改为双语

README.md 和 guides/ 下全部 7 篇（build-tool-integration、debug-adapter-plugin、lsp-plugin-lifecycle、native-build-workflows、native-terminals、plugin-backend-workspace、plugin-logging）都改为统一的双语结构，README 的导航表同时加入 reference/ 各页：

• 标题 中文 / English，下面是 [中文](#中文) · [English](#english) 切换链接；
• 先是 ## 中文 全文，--- 之后是 ## English 全文；
• 原来的中文小节标题保持不变，已有的中文锚点链接仍然有效。指南之间互相引用的英文锚点也已对齐。

4. 按最新 preview 修正的现状说明

• 基准：README、指南和 reference 都说明宿主现状按主仓库最新 preview 核对。不再钉具体稳定版版本号，只提醒稳定版可能还没有其中的能力，发布前以目标版本为准。
• API 3 / 构建与调试：build-providers、build-systems、debug-adapters 去掉“开发中”标注；原生构建工作流说明改为“macOS 宿主已实现 buildProviders 2–6，Windows 不支持构建提供者”。
• litheLogging 与 SDK 兼容：SDK 0.3.0（Node/Java）和 Rust 0.2.0 要求宿主提供 litheLogging 1，preview 已提供；需要兼容不提供它的版本时，继续用 Node/Java 0.2.0 或 Rust 0.1.0，并且在稳定版提供之前把 Release 标为预发布。调试适配器指南里的预发布/转正规则也按这个改写。
• 调试 attach 的限制（debug-adapter-plugin）：宿主的调试入口对插件适配器只发 launch。清单可以声明 attach，但宿主目前只在构建提供者服务运行的连接调试（buildProviders 11）中选用；用户手填主机和端口的远程 attach 还没有宿主入口。debug.attach 权限只在适配器列出 attach 时需要，也只有这时才允许。
• --build-workflows 的默认行为（native-build-workflows）：契约镜像已包含 buildProviders 6，所以默认的 sdk-e2e.mjs 就会运行原生构建工作流场景。这个参数只用于对较旧的镜像或宿主分支显式加入这些场景，每周的 preview 检查也显式带上它。
• LSP 生命周期指南（guides/lsp-plugin-lifecycle.md）：
  • Lua 模板更新到 v0.3.1：命令和产物名改为 0.3.1；最小示例改为 API 2，参数 ["${logDir}"] 与模板启动器一致；说明 API 1 参数是字面量，只支持 API 1 的启动器要自己选日志目录；模板还带运行 lua <文件> 的执行提供者。
  • 启动器说明：把宿主的 ${logDir} 传给 --logpath，meta 放在 ~/Library/Caches/io.github.lithe-idea.lua-support/meta，再 exec 真实服务器。API 2 直连示例改为 --logpath=${logDir} 加 --metapath=${workspaceStateDir}。
  • 安装路径：写清 macOS 上的两条路径。“从磁盘安装插件…”接受 zip 或解压目录，必有安装审查，标为发布者与仓库未验证，但不检查索引和 Release 摘要。自己的插件源走“管理插件仓库…”和根目录的 lithe-plugin-index.json，发布前至少走一次。开发构建按本地开发包处理是另一条信任路径。
  • 免重启范围：只有贡献全部是调试适配器或语法、且没有后端的插件，安装后才在运行中立即生效。LSP 插件的安装、更新、回滚、恢复和卸载在下次启动完成；本次启动已注册的插件可即时启用/禁用；卸载先停用。验收要覆盖重启前后两种状态。
  • 进程停止：macOS 上 Core 强停只针对直接子进程，Windows 按进程树结束。默认超时已核对：初始化 30 秒、请求 30 秒、关闭 2 秒。
  • Windows 现状：只能从磁盘安装声明式包，没有插件市场浏览器，不支持 executionProviders，也不提供 logDirectory，所以用到 ${logDir} 的启动会以 plugin.launch.invalidRequest 被拒绝。排查表新增这一行。
  • 发布：--expect-tag v0.3.1；回滚使用安装记录中保留的上一版本，LSP 插件在重启后切换。
• 其他指南的 Windows 与磁盘安装说明：各指南的 Windows 段落按 preview 的实际能力改写（languages 1、languageServers 1–2、serverProcess 1、settings 1–2、ui 1–2；没有后端、构建、调试和执行提供者）。

5. 新增插件协议更新记录（reference/protocol-changelog.md，只有中文）

• 收录范围：主仓库 preview 第一父历史中，修改了契约 shared/contracts/plugins/v1/、Core 能力表 capabilities.rs 或插件函数协议 plugin_function.rs 的 PR，从 #1170（2026-10-14，契约 v1 进入 preview）到 #1747（2026-11-05），共 42 个。三处都没改、只改宿主内部实现的 PR 不收录。
• 按协议查首次出现：三张表，分别列出插件 API 级别与文档格式、每个 requires 能力版本、每个进程协议版本，各自是哪天由哪个 PR 引入。
• 时间线：按合入日期倒序，每个 PR 一行，写明修改人、改动的协议/API 和具体内容。新增的版本号加粗，同一版本内的补充、宿主接入、说明修正不加粗。
• 修改人：原 PR 的作者，写成 [@账号](https://github.com/账号) 链接，账号用 gh 从 1lck/Lithe-IDEA 逐个查出。文件里的链接不会通知任何人；通知靠同步 PR 描述里的 @，见下方“请修改人核对”。
• 核对方式：每个版本号和改动内容都按对应 PR 在 capabilities.rs、plugin_function.rs、manifest/index schema 和契约 README 上的 diff 核对。时间线的 42 行和上述 git log 结果逐个比对，无缺漏、无重复。日期是合入 preview 的提交日期。
• 维护：页尾写明每次 node scripts/contract.mjs sync 时，在同一个 PR 里怎么补：用给出的 git log 命令列出两次同步之间的 PR，补到时间线最上面，新版本加粗并写进首次出现表，用给出的 gh pr view 命令查修改人，改“记录到”的 commit，同步更新版本对照页和受影响的功能页，最后在同步 PR 描述里 @ 每位修改人。主仓库 AGENTS.md 同步加上了这条登记规则（docs(agents): 插件协议和 API 变更合入后要在 lithe-plugin-docs 登记并 @ 修改人 1lck/Lithe-IDEA#1750）。
• 入口：reference/README.md 的“从哪里开始”（中英两半，英文半标注 Chinese only），以及根 README 的 reference 表和契约同步维护说明，都加了这一页的链接。

请修改人核对

这次登记了 42 个 PR，请各位核对自己那几行的协议/API 和改动说明：

• @Mucheen：#1558、#1517、#1483、#1424、#1420
• @FxRayHughes：#1646、#1581
• @1lck：#1695、#1470、#1170
• @arkleselect：#1423
• @xiaoyumuxi：其余 31 个

验证

• node scripts/contract.mjs verify --upstream：91 个文件与 644afdaac 一致
• node scripts/contract.mjs drift --ref preview：与上游 preview 无漂移
• node --test scripts/*.test.mjs：16/16 通过
• node --test sdk/node/test/*.test.mjs：77/77 通过
• mvn -f sdk/java/pom.xml test：64/64 通过
• cargo test --manifest-path sdk/rust/Cargo.toml --test host_services：13/13 通过
• 本地相对链接与锚点检查：README、reference、guides 共 27 个文件 1274 条链接，0 条失效

本 PR 没有改动 SDK 源码和发布流程，不需要发 SDK 新版本。