[xiaoyumuxi]

Refs #1495

API-35 第一阶段：两个已安装、已启用的插件之间，可以经 Rust Core 中转调用对方明确导出的插件函数（插件 1 → Core → 插件 2）。本 PR 不含安装期依赖解析、版本冲突处理、依赖闭包和资源租约。不新增 API 编号。

改动

• 清单：新增能力键 requires.pluginFunctions: 1 和顶层 pluginFunctions { exports, calls }。

  • 导出项是 { id, version, context }。context 第一阶段只能是 "workspace"，缺失或取未知值时整个清单被拒。
  • 调用方声明 { id, version }，版本必须与导出方完全相等。
  • 导出的函数仍须在运行时用 lithe/function/register 注册。
  • schema、README、有效与无效 fixtures、Core 校验、Swift hostCapabilities 镜像和 verify-shared-contracts.sh 一起更新。

• 协议：litheFunctions 增加版本 4。协商到 4 且声明了 calls 的后端可以使用 lithe/host/functions/providers（发现提供方）和 lithe/host/functions/invoke（调用）。协议 3 及以下返回 plugin.host.unavailable；没声明 calls 返回 plugin.host.permissionDenied。

• Core 中转（function_relay.rs、engine_function_relay.rs、plugins/plugin_functions.rs）：

  • 按固定顺序检查：调用方声明、被调方启用、导出、版本、上下文、本地工作区、参数大小、调用链无环（含自调）、深度 ≤ 4、每个调用方并发 ≤ 8。第一个失败的检查决定错误码。
  • 结果上限 256 KiB；默认超时 60 秒，最长 10 分钟；取消沿调用链向下传播；远程工作区被拒（API-40）。

• 信任不传递：被调方用自己的权限运行，调用方的 pluginID 不写进被调方的会话身份。Core 在转发的 lithe/function/invoke 里写入顶层 caller: { pluginID }：只发给协商到协议 4 的被调方；宿主发起的调用没有这个字段；调用方伪造会得到 plugin.host.unsupportedOption。契约要求导出函数不得接受调用方传来的可执行路径或命令。没有新增权限项：调用方声明 calls、被调方声明 exports，就是双方的同意。

• 被调方未运行：Core 只发出 functionProviderStartRequired，由 macOS 作为 I/O 启动它的后端。Core 最多等 30 秒，超时返回 plugin.function.providerUnavailable。

• 热激活：宿主用新命令 lsp.configureFunctionRelay 向 Core 发布插件与上下文快照。被调方被禁用、卸载，或更新后不再导出时，发现结果立即更新，进行中的调用以明确的错误结束。

• 错误码，每个数值只对应一种错误：

  字符串码	数值
  plugin.function.notDeclared	-32027
  plugin.function.notExported	-32028
  plugin.function.providerDisabled	-32029
  plugin.function.versionMismatch	-32030
  plugin.function.callCycle	-32065
  plugin.function.depthExceeded	-32066
  plugin.function.tooManyCalls	-32067
  plugin.function.payloadTooLarge	-32068
  plugin.function.providerUnavailable	-32069
  plugin.function.failed（被调函数自己返回错误）	-32070
  plugin.function.invalidResult（被调方没有返回 result，或结果超过 1 MiB）	-32071

  -32603 仍只表示 plugin.host.failed，即 Core 内部失败。-32031..-32064 留给并行中的其他插件 API PR；-32060..-32063 是 Core 命令 API（日志查看器）的码，属于另一个命名空间，不冲突。

• 旧规则不变：后端发 lithe/function/invoke 或 lithe/build/* 仍然得到 recursiveCall；引用别的插件的私有函数仍然是 wrongPlugin。

• macOS（只做 I/O）：MacPluginBackendSessions 发布快照并响应启动请求；PluginHostServiceDispatch 把 functions 服务列为由 Core 直接应答的授权；hostCapabilities 增加 pluginFunctions。

• 文档：README 新增 “Cross-plugin calls (protocol version 4)” 一节；rust-core-api.md 补充 lsp.configureFunctionRelay；已实现 Note 2026-10-20-plugin-function-contract.md 增加决策 8；提议 Note 2026-10-25-plugin-dependencies-and-exports.md 标出第一阶段已落地的部分；功能矩阵新增 plugin-cross-plugin-function-calls（Windows 行为不变，不声明 pluginFunctions）。

宿主方法

原计划编号	方法	用途
API-35	lithe/host/functions/providers	列出导出某个函数、已启用并且版本匹配的插件
API-35	lithe/host/functions/invoke	经 Core 调用另一个插件导出的函数；本轮评审新增可选参数 parentOperationID

评审修复（本轮）

• P1：一个后端不读 stdin 会卡住所有中转。原来只有一个中转工作线程，向被调方写入时如果对方管道写满，所有插件的中转调用都会排队。
  • 改成主工作线程只负责规划，每个目标会话一条写入车道（Lanes / run_lane）。一个后端不读输入，只会拖慢发给它自己的调用、回复和取消。
  • 每次中转写入都有截止时间（bounded_relay_write，等于会话的请求超时）。超时后由会话 monitor 让该会话失败（transportFailed，阶段 relayWrite）并结束进程，被卡住的写入随之释放，这个会话上的调用按会话失败的规则结束。
  • 车道里的调用写出前会再确认它仍在运行，已结束的调用不会再写给被调方。
• 跨调用取消外泄。一个后端同时服务多个调用时，原来新发起的子调用会挂到它服务的所有调用下，取消其中一个就可能把别的调用的子调用也一起取消。
  • lithe/host/functions/invoke 增加可选的 parentOperationID，值是被调方收到的那个调用的 operationID。调用链和取消只沿这一条走。
  • 指向宿主发起的操作时，子调用从一条新链开始。
  • 父调用不在调用方会话里运行（未知或已结束）时返回 plugin.host.cancelled；值不是 1–128 字节的字符串时返回 plugin.host.invalidParams。
  • 不填时保持原来的行为。检查顺序表新增一行，fixture 新增两条用例。
• 上下文失效没有结束调用。新快照让调用所在的工作区上下文关闭或换代时，等待被调方启动的调用和已经在运行的调用都立即以 plugin.host.contextExpired 结束，运行中的调用同时取消被调方。
• 运行中的调用可能永不过期。截止时间到了以后再给 2 秒宽限（RUNNING_GRACE），让被调方自己的超时先回答；宽限过后仍没有回答，就以 plugin.host.timeout 结束并取消被调方。等待被调方启动的那段时间不会把已经开始运行的调用判为超时。
• 日志门禁：Rust 的 let _ = 和 Swift 解码清单的 try? 补了 log-exempt 标注（Swift 只改了这一行注释）。
• 宿主语言闸门：functionProviderStartRequired 事件改为复用已有的 push_negotiated_provider_event，这个新文件不再出现工具名，基线没有增加。
• 文档：契约 README 的 relay 一节（调用参数、检查顺序、调用链、宽限、上下文失效、新增“Isolation between backends”）、function-protocol.json fixture、Note 决策 8 一起更新。顺带更正了“热激活”的描述：只有新安装或更新后端插件才需要重启，禁用、启用、替换和卸载都是即时生效的。
• 新增测试
  • 纯逻辑：上下文关闭或换代时，等待中和运行中的调用都会结束；父调用限定调用链和取消范围；不填父调用的旧行为；宿主操作开始一条新链；拒绝不在会话里运行的父调用；宽限期内不结束、宽限后超时；is_running。
  • 引擎级：不读输入的后端不拖住另一对插件，阻塞写入超时后会话失败；父调用限定取消；未知、已结束和格式错误的父调用；上下文关闭或换代时结束等待中的调用；上下文关闭时结束运行中的调用并取消被调方。

同步 preview

• 合入最新 preview（含 feat(plugins): 编辑器 Provider 与多车道编辑器动作（API-25、API-27） #1730、docs(agents): Java 插件改为普通插件身份，记录宿主前置条件 #1754）。契约 README 的 fixture 目录表和新章节有冲突，两边都保留：编辑器 Provider（协议 3）一节在前，跨插件调用（协议 4）一节在后。invalid-manifests.json 两边新增的用例也都保留。
• 之前同步 preview 时带进来的 docs(contracts): 删除工具链契约草案，已实现部分写进正式契约，测试改用内联数据 #1752 让宿主语言闸门失败。修复提交和 feat(plugins): 编辑器 Provider 与多车道编辑器动作（API-25、API-27） #1730 里的同一份修复内容相同，现在已经在 preview 里。
• docs(contracts): 插件契约 fixtures 按功能分目录并修正能力版本表 #1747 把契约 fixtures 移进了子目录。MacPluginBackendSessionsTests 的 installFunctionPlugin 改为从 fixtures/backend/ 读取 plugin-functions-exporter / -caller 清单，否则三个跨插件调用的 Swift 测试找不到文件。

验证

合入 preview cf2697c83 之后在本地执行：

• cargo test -p lithe-core：1967 个单元测试和全部集成测试通过。合入之前的一次全量运行中，search_everywhere_pages_all_sources_past_200... 超时失败过一次；它和本 PR 无关，单独运行通过，合入之后的全量运行也通过。
• function_relay / engine_function_relay 相关测试连续跑 5 次，结果稳定。
• scripts/macos/test/test-macos.sh --filter 'MacPluginBackendSessionsTests|PluginHostServiceDispatchTests|PluginPublicHostAPITests|PluginEditorProvider'：4 个套件共 51 个测试通过；脚本自带的 bundle 不可变检查和 i18n 检查也通过。
• lithe-plugin-docs node scripts/sdk-e2e.mjs --source <本仓库> --ref review/1742：Node、Java、Rust 三个 SDK 的示例后端共 9 个测试通过。
• 门禁：verify-shared-contracts.sh、Rust 注释规范、generate-i18n.mjs --check、verify-app-language-localization.mjs、日志门禁（0 违规）、Agent Note 校验、功能矩阵、测试稳定性规则、verify-no-host-language-specifics.mjs（绝对模式和 --base origin/preview 都通过，基线没有增加）、git diff --check。
• 没有执行：macOS 实机验收、Windows。

已知未完成

• macOS 上，新安装或更新的后端插件仍需重启 Lithe 后才会出现在发现结果里；禁用、启用、替换和卸载是即时的。属于 fix(remote): #1507 远程工作区、构建与插件执行适配 #1515 的后续工作。
• 选择被调方会话用的是启发式规则：优先选与调用方 root_uri 相同的会话，否则取会话 ID 字典序第一个。
• 三个 SDK 还没有自动填 parentOperationID。不填时行为和以前一样，SDK 的 relay 封装和这个字段在 lithe-plugin-docs 另开 PR 处理。
• 没有在 macOS 实机上验收，功能矩阵里的验证状态是“待验证”；Windows/Tauri 目前没有插件后端宿主。
• docs/development/macos-plugin-api-plan.md 中 API-35 一行还没更新，等 fix(remote): #1507 远程工作区、构建与插件执行适配 #1515 合入后统一改。
• 合并后需要在 lithe-plugin-docs 运行 node scripts/contract.mjs sync --revision <合并后的 preview commit>，并在协议更新记录、API 总表和“宿主方法（按 API 编号）”索引里登记。

[lithe-code-review]

Lithe Review

结论： ⛔ 有阻塞
范围： preview ← feat/1495-plugin-function-relay · head: 8e21f84

Findings

1. [P1] 避免阻塞写入卡住整个中转队列
   rust/lithe-core/src/lsp/interface/engine_function_relay.rs:199

   • 实际影响：派发、回复和取消共用一个工作线程；任一管道写入阻塞后，其他插件的中转调用也无法完成，包括超时回复和取消。
   • 触发条件：调用方或被调方进程存活，但停止读取 stdin。
   • 复现步骤：A 调用 B 后停止读取 stdin，让 B 返回约 200 KiB 的合法结果。此处 relay_reply 最终进入 process.rs:253 的阻塞 write_all，且没有写入截止时间。该调用已从 relay 表删除，没有剩余请求期限能终止这次回复写入；随后 C→D 的调用即使超时，回复也只能排在同一工作线程后面。派发处第 249 行存在相同的阻塞边界。
   • 来源：本次引入。实际影响超过正文所述“排队直到各自超时”。

2. [P2] 快照更新时终止上下文已经失效的调用
   rust/lithe-core/src/lsp/interface/function_relay.rs:681

   • 实际影响：工作区关闭或 generation 改变后，旧调用仍可继续执行，甚至在被调方稍后启动时才首次派发。
   • 触发条件：调用通过准入检查后，其工作区上下文被关闭或换代。
   • 复现步骤：以有效的 w1/generation=1 发起调用，让它等待提供方；保持插件声明不变，发布 contexts: []，再启动并注册提供方。此函数只复查调用声明和导出版本，dispatch_plan 也不复查上下文，因此仍会发送旧上下文。macOS 已发布关闭快照，但这些请求由 Core 直接处理，不在 Swift dispatcher 的上下文取消表中。
   • 来源：本次引入。

3. [P2] 按实际父调用关联子调用，避免并发请求干扰取消
   rust/lithe-core/src/lsp/interface/function_relay.rs:592

   • 实际影响：取消一条调用链后，其下游工作仍可能运行，直到另一个无关父调用也结束；不同调用链还会被合并，产生错误的环路或深度拒绝。
   • 触发条件：同一个后端会话同时服务两个中转调用。
   • 复现步骤：同时保持 A→B 和 D→B 运行，让 B 为 A 的请求发起 B→C，然后取消 A→B。这里会把两条入站调用都加入 C 的 parents；第 663 行要求所有父项都消失才取消 C，因此 D→B 未结束时，C 收不到沿链取消。应用级共享后端使不同工作区也会遇到此问题。
   • 来源：本次引入。

4. [P2] 处理新增的 Result 丢弃，恢复日志门禁
   rust/lithe-core/src/lsp/interface/engine_function_relay.rs:186

   • 实际影响：第 186、199、208 行的三个 let _ = ... 均会命中现有日志检查，且没有要求的 log-exempt 标记。
   • 触发条件：CI 执行 node scripts/logging/verify-log-usage.mjs。
   • 复现步骤：检查器第 110 行明确匹配这些语句，扫描范围包含该生产模块，且 rust.let-underscore 不允许加入永久豁免名单。静态代码已足以确认这些违规；提供的 head 检查也显示 Structured Logging 失败，但未提供日志，无法判断是否还有其他失败原因。
   • 来源：本次引入。

Scope Check

• 本 PR 只覆盖 [Feature] macOS 存量重构计划：清理废弃实现，将 Maven/Java 领域逻辑完整迁入插件后端 #1495 阶段 C 中的跨插件调用基础能力，不代表整个迁移计划完成。
• 已增加清单声明、协议 4、Core 中转、macOS 快照与启动接线，并同步契约、fixtures、Note 和功能矩阵。
• 安装依赖解析、免重启安装/更新、Windows 后端宿主和 macOS 原生验收明确未完成。
• 实现复用了现有函数协议与会话引擎，共享规则放在 Core；未发现新增 Maven/Java 领域事实的并行实现。
• 四项 Finding 均由本次新增代码引入，属于本 PR 的生命周期、并发和验证职责。

Suggestions

1. 为每个会话提供有界写入及独立超时恢复，隔离阻塞会话；避免派发、回复和取消共同等待一个可能永久阻塞的写入。补充阻塞管道时其他调用仍能结束的引擎测试。
2. 配置快照时复查每个调用的上下文与 generation，结束失效的等待项并取消运行项；覆盖等待启动和运行期间关闭、换代的场景。
3. 在协议中传递 Core 可校验的实际父 operation 标识，按调用归属维护链与取消关系，并同步契约、SDK 和并发回归测试。
4. 显式处理丢弃的失败；确属已记录或预期缺失的路径，补充符合封闭例外规则的具体标记，再提供日志门禁结果。

Summary

Core 归属和基础设施复用方向合理，但阻塞写入缺少隔离，上下文失效与并发取消也未满足所声明的生命周期保证。现有成功路径测试不能覆盖这些问题。

Verification

• 静态检查指定 824d2f4...8e21f84 的变更，重点追踪中转状态机、引擎派发/回复/监控、原生管道写入、macOS 后端与上下文、清单校验、契约和相关测试。
• 作者报告：Core 1946 个测试、macOS 33 个测试及 SDK 9 个端到端测试通过。提供的 head 状态中 Rust Core 等检查成功；Structured Logging 失败，Swift、发布包和部分 Windows 检查仍在运行。
• 本次未运行任何仓库代码、测试或应用，未访问网络；以上复现依据为静态调用链分析。
• 尚缺两个真实插件的 macOS 验收，以及阻塞管道、上下文失效、并发父调用的回归证据；未提供运行时 bundle 不变性检查结果。

[lithe-code-review]

Lithe 运行验收

版本：8e21f846738e9a37d1bcc4d341962778b33268bd；状态：partial。
本报告独立于代码审查；只报告实际执行的场景，不代表所有问题均已修复。

对照：共同祖先 824d2f4b6b00fca87a8048902b1845a463b02ae4 → PR head；当前目标分支合并适用性：未运行。

• 条件不足，未验证：Manifest contract: accept exports, calls and both with requires.pluginFunctions:1 and no new permission; require workspace export context; reject malformed declaration shapes, unsupported context, missing capability, backend 1, invalid IDs, invalid version bounds and more than 32 exports. Preserve ordinary backend manifests.
  • Probe audit: The probe exercises JSON Schema through Ajv, bypassing production validation. Windows plugin_host/scan.rs calls plugins.declarative.validate, implemented in Rust Core plugins/declarative.rs. All probe markers could pass while that production path rejects valid relay manifests, so the required production behavior oracle is missing. Static audit only; probe not run.
• 条件不足，未验证：Exercise actual Core session routing, caller provenance, discovery updates and revocation of running or waiting calls when plugin/context snapshots change. This specifically targets the review's stale-context finding, beyond initial admission validation.
  • Cargo and rustc are inventoried, but the Windows C compiler, native linker and SDK needed by Core's native dependencies are not. No prebuilt Core runner is supplied. Treat that toolchain as unavailable under the inventory rule; do not attempt a build or substitute frontend mocks. A native runner linking each exact checkout and bounded backend fixtures are prerequisites.
• 条件不足，未验证：Validate MacPluginBackendSessions snapshot publication and lazy provider startup, Core-served functions authorization, real plugin lifecycle behavior, trust isolation, runtime resource immutability and process cleanup.
  • This environment is headless Windows. The macOS product, Swift/Xcode toolchain, interactive macOS session and two provisioned backend plugin packages are unavailable. A verified way to isolate application support/state from the user's installation is also required.

未覆盖：

• Neither blocked scenario supplies native runtime evidence. The runnable schema probe cannot prove Rust manifest validation, Core relay behavior, Swift integration or installed-product behavior.
• Native manifest semantics remain uncovered: duplicate declarations, canonical sorting, exact requires/section correspondence, exporter activation without a page or activation event, functions launch grants, hostCapabilities mirroring, and Windows rejection with plugin.api.unsupported.
• Protocol negotiation and compatibility remain uncovered: v4 availability, v3-and-earlier plugin.host.unavailable, undeclared calls producing permissionDenied, capability discovery, ordinary language/build traffic, recursiveCall for direct backend function/build requests, and wrongPlugin for private references.
• The complete admission order and numeric error mapping remain uncovered: declaration, enabled provider, export/runtime registration, exact version, current context, local authority, payload, cycles/self-call, depth =4 and per-caller concurrency =8. Multiple simultaneous failures must verify first-error precedence.
• Payload/result boundaries remain uncovered: serialized 256 KiB limits, valid null results, missing result and results over 1 MiB, provider failures with retained pluginErrorCode and bounded messages, and keeping -32603 exclusive to plugin.host.failed.
• Timeout and lifecycle coverage remains missing: default 60 seconds, maximum 10 minutes, 30-second provider-start limit, provider exit/unregister, caller-session termination, late-result suppression, no retry, and cancellation throughout nested chains.
• The concurrent-parent review finding remains uncovered: simultaneous A-B and D-B followed by B-C must preserve actual parent ownership, cancel C when its originating call ends, and avoid false cycle/depth rejection. The wire protocol's parent association needs clarification before freezing that probe.
• Blocked-pipe isolation remains uncovered. A non-reading caller/provider could stall unrelated relay replies, dispatch and cancellation. Native stalled-pipe fixtures and a prespecified statistical protocol with repetitions, latency thresholds and decision rules are required before making performance or intermittent-reliability claims.
• Trust isolation needs native evidence beyond caller tagging: forged top-level caller rejection, unchanged nested params.caller data, field omission for host calls and protocol =3 providers, provider-owned permissions/state/credentials, and provider enforcement against caller-selected executable paths or commands.
• Provider selection across multiple sessions/workspaces and the documented root_uri/lexicographic fallback remain uncovered.
• macOS lifecycle, remote-workspace rejection, bundle immutability and process cleanup remain blocked. Windows product behavior is also unverified; this PR does not provide a Windows plugin backend host.
• Hot-install/update expectations are inconsistent: README promises immediate discovery, while the PR body and feature matrix require restart. Resolve the contract before accepting those actions. Installation dependency resolution, conflict handling, dependency closure and resource leases are explicitly outside this PR.
• Documentation/fixture synchronization, logging-gate findings, capability/feature-matrix consistency and repository validation gates were not executed. External lithe-plugin-docs contract synchronization and Node/Java/Rust SDK compatibility are unverified; that checkout and Java are unavailable.

工作副本与运行状态已清理；可复用编译缓存按 12 GiB / 7 天预算保留。
详细步骤和原始证据保存在服务器受限目录（14 天、总计不超过 1 GiB）；当前没有公开下载链接。