feat(plugins): 插件函数契约、能力方向与 Core 协商路由 (#1351 PR 1)

[xiaoyumuxi]

关联 #1351。

为插件后端提供可版本协商的函数契约和共享 Core 调用路由，并保证函数发现、操作 ID 复用及 Provider 关闭时的会话隔离。macOS 和 Windows 的原生函数调用入口、UI 与宿主能力仍待后续接入。

契约与调用路由

• 定义 capabilities.experimental.litheFunctions v1 协商、函数引用与 ID、注册/撤回、调用、进度、结果及稳定错误码；不增加插件清单字段，不提升现有 API 或能力版本。
• 区分领域能力、插件函数和宿主能力：领域操作继续使用类型化协议；v1 拒绝后端递归调用与尚未开放的宿主能力，没有运行时回退。
• 新增 lsp.functionRequest、lsp.startServer.pluginId、functionsChanged、requestProgress 以及客户端函数状态，并通过共享 fixture 固定协议行为。
• 函数注册和撤回整体生效或整体拒绝；撤回正在执行的调用时完成该调用并发送取消。失败同时保留稳定错误码和插件错误码。

会话隔离与生命周期

• 初始化协商成功后发布排序后的初始 functionsChanged，包含空列表，使宿主无需等待动态注册即可发现函数。
• 每次后端调用使用独立的线协议操作 ID，向宿主发布进度时还原宿主操作 ID。取消、超时、成功、失败、撤回和会话关闭都会清理关联；旧调用的迟到消息不会影响复用相同宿主 ID 的新函数或构建请求。
• 无 pluginId 的宿主自有会话不提供、协商、注册或广播插件函数。
• 会话停止或失败时清空函数注册表；关闭期间拒绝迟到的注册、注销和进度消息，避免已撤回能力重新出现。
• macOS 执行模块关闭时回收已就绪及初始化中的 Provider；共享启动完成后的身份与取消检查阻止迟到就绪消息恢复会话或发送构建请求。

测试与文档

• 受控后端覆盖初始发现、宿主归属、各类终态后的 ID 复用、跨函数和构建复用、迟到消息、进程失败及递归调用拒绝。
• 关闭回归使用注册/注销响应作为顺序屏障，确认处理迟到消息后注册表仍为空，且没有新的能力或进度事件。
• macOS 回归覆盖真实执行模块关闭，以及初始化中和已就绪 Provider 的回收、迟到就绪、终态与销毁顺序。
• 更新共享契约检查、中文架构决策笔记和跨平台功能矩阵。共享 Core 已实现，两个原生平台的函数调用入口保持部分实现状态。

本地验证

• Rust Core：1,058 项通过（1,042 单元测试、2 路径回归、9 push 集成、5 watch-context 集成），零失败。
• Core 专项计时：107/107 通过，零跳过、超时或慢测试告警；新增回归最慢 101ms。
• macOS 完整测试目标构建通过；生命周期专项 124/124 通过，新增 Provider 回收回归约 158ms。
• C ABI、应用链接符号、Git 执行集成 12/12、Swift 桥接 9/9 通过。Swift 验证使用 6.3.3 工具链和兼容的 macOS 26.5 SDK。
• Agent Notes、共享契约、跨平台矩阵及变更门禁、服务边界、运行时资源只读边界、Rust 注释/格式和测试稳定性检查通过。
• 广泛 Rust 检查通过；agent-host 的外部真实集成测试有 39 项按原配置跳过，9 项既有慢测试告警，没有硬超时。
• Windows 原生测试未在本机运行。

已合入最新 preview，保留原 PR 提交历史；本次修复文件与已验证版本内容一致。

[lithe-code-review]

Lithe Review

结论： ⛔ 有阻塞
范围： preview ← feat/1351-plugin-function-contract · head: 251c972

Findings

1. [P1] 将 Provider 回收接入项目会话关闭链路
   macos/Sources/LitheExecutionModule/Services/BuildSystemService.swift:218

   • 实际影响：关闭项目窗口后，自有 Provider 进程及其会话轮询仍会常驻，持续占用资源。
   • 触发条件：Provider 已启动，用户直接关闭项目窗口，同时保持 Lithe 运行。
   • 复现步骤：在一个项目窗口加载自有 Provider 的模型，再关闭该窗口。ProjectSessionManager.resetDedicatedWindowSession 经 AppModel.shutdownProjectSession、模块关闭进入 ExecutionFeatureGraph.stop()，最终只调用 BuildSystemService.stop()。新增的 retainProviders { false } 仅位于 reset()；stop() 只取消请求任务，没有停止 Provider。进程登记使用的 ManagedProcessRegistry 仅负责监控，也不会代为终止进程。
   • 来源：本次引入。base 不启动 Provider；本次增加常驻进程，却遗漏既有会话关闭入口。

2. [P2] 清除已结束函数的映射，避免撤回时取消其他请求
   rust/lithe-core/src/lsp/interface/engine.rs:5011

   • 实际影响：撤回旧函数会误取消新的构建请求，并将其错误报告为 plugin.function.revoked；旧函数的迟到进度也可能被当成新操作的进度。
   • 触发条件：函数调用取消或超时后，其他类型的请求复用该调用的 operationId。
   • 复现步骤：在同时协商两种协议的会话中，以操作 ID x 调用 snapshot.refresh，然后取消；接着以 x 发送 lsp.buildRequest，保持其未完成，再让后端撤回 snapshot.refresh。取消路径移除了 pending 请求，却留下 function_by_operation[x]；新构建请求允许使用已不再 pending 的 ID。此处随后依据残留映射移除并取消了新的构建请求。
   • 来源：本次引入。新增映射仅在正常函数回复、撤回或下次函数调用时清理，未覆盖取消和超时路径。

Scope Check

• 关联需求：[Feature] 保留声明式接入，为插件增加可执行后端与原生／Web UI 扩展路径 #1351 的 PR 1。函数契约、协商、注册、路由及受控后端测试已实现；生命周期保证存在上述缺口。
• 实际范围还包含 macOS Provider 启动、模型与依赖请求、市场能力声明和可见加载入口，并非正文所述的纯契约变更；已一并审查。
• SDK、宿主能力、函数调用 UI 和 Windows 后端宿主属于后续阶段，不要求本 PR 完成整个 Issue。
• 已复用现有 LSP 传输、请求及取消机制；未发现新增并行项目事实源的问题。
• 两条 Finding 均由本次变更引入，属于本次生命周期与请求关联职责范围。

Suggestions

1. 合并前必须修复 Finding 1： 在服务停止或对应模块资源释放时回收所有 Provider，覆盖正在初始化和已经就绪的进程；补充直接关闭项目窗口的生命周期回归测试。
2. 非阻塞建议，对应 Finding 2： 在取消、超时等终止路径同步清除函数映射，并在撤回、进度处理时核对当前 pending 请求的函数身份；补充跨请求类型复用操作 ID 的测试。
3. 更新 PR 描述以反映固定范围中的 Provider 接入和功能矩阵变化，并补充构建窗口加载入口的前后截图。提供的上下文没有截图，视觉效果尚未验证。

Summary

契约与平台适配的分工总体清晰，已有测试覆盖常规路由、失败、取消和撤回。项目窗口关闭时的进程泄漏需要在合并前修复；操作映射残留属于非阻塞建议。

Verification

• 静态检查了完整 37 文件变更清单，重点追踪 dispatcher → LSP client/engine、Swift Provider 启动与请求、项目会话关闭链路，以及共享契约、fixtures、测试和矩阵记录。
• 作者报告 Core 1037 个测试及契约、注释、稳定性、Agent Notes、bundle 只读和矩阵校验通过；提供的 Check Run 中有 Rust Core、Swift 和 macOS gate 成功记录。
• 同时存在 Windows Rust、Windows gate 和矩阵发布失败记录，未提供失败日志，无法确认原因或是否已解决。
• 本次未运行任何代码、测试、构建或应用，未访问网络。真实 Provider 生命周期、Windows 验证及 UI 截图仍需补充证据。

[xiaoyumuxi]

@lithe review

[xiaoyumuxi]

整体协议方向合理：插件领域能力与插件私有函数分开、按插件身份路由、禁止后端递归调用宿主领域操作，并复用 LSP 的取消/超时机制，建议保留。

此次 Review 标出 1 项 P1、2 项 P2（见行内评论）。建议合并前优先解决 initialize 初始函数注册表对宿主不可观察的问题，以及复用 operationId 后迟到进度可能被误归属的问题；另外建议加强宿主自有会话的注册边界。

CI 方面，当前提交的检查记录里 Windows CI 的 Git 路径测试失败或超时、Platform Feature Matrix 因未更新矩阵且未获豁免而失败。前者暂不能归因于本次变更，建议对照基线或重新运行；后者应更新能力矩阵或按仓库流程申请 matrix-exempt 并让门禁通过。

建议补充：initialize 直接提供函数 ID 的可观察事件测试；取消→复用同一 operationId→收到旧进度的测试；宿主自有会话尝试动态注册的测试；注册/撤回与并发调用的竞态测试。以上为静态 Code Review，未在本地执行 Rust 测试。