Skip to content

refactor(plugins): 契约发布到 lithe-plugin-docs，fixture 按能力改名，SDK 移出主仓库 #1442

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
xiaoyumuxi merged 3 commits into from
Oct 23, 2026
Merged

refactor(plugins): 契约发布到 lithe-plugin-docs，fixture 按能力改名，SDK 移出主仓库 #1442

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
ed4a4ff
refactor(plugins): 契约发布到 lithe-plugin-docs，fixture 按能力改名，SDK 移出主仓库
xiaoyumuxi Oct 23, 2026
aab249d
Merge branch 'preview' into feat/plugin-contract-publishing
xiaoyumuxi Oct 23, 2026
9c86a17
docs(plugins): SDK 与契约的每周检查跟踪 preview 而不是默认分支 main
xiaoyumuxi Oct 23, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions .agents/notes/implemented/architecture/2026-10-17-build-system-plugin-contract.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ Rust Core 负责校验声明、识别工程、展开每一条命令行，并把

没有声明的能力不报错，也不会出现在界面上。例如 Cargo fixture 没有声明依赖树，Build 工具窗口就不显示依赖区。

字段全集只写在 `shared/contracts/plugins/v1/README.md` 的 “API level 3: build systems” 一节和 `plugin-manifest.schema.json` 里，本 Note 不重复。四个 fixture（`cargo-build`、`go-build`、`gradle-build`、`maven-build`）是完整示例，`gradle-provider`、`mix-provider` 分别示范 Provider 的两种写法。
字段全集只写在 `shared/contracts/plugins/v1/README.md` 的 “API level 3: build systems” 一节和 `plugin-manifest.schema.json` 里，本 Note 不重复。四个 fixture 各示范一种模型来源，按能力命名而不是按真实插件命名：`build-static-file`（读项目文件，内容用 Cargo）、`build-command-stdout`（解码命令输出，内容用 Go）、`build-command-output-file`（解码命令写出的文件，内容用 Gradle）、`build-host-integration`（交给宿主集成，内容用 Maven）。`build-provider`、`build-provider-language-server` 分别示范 Provider 的两种写法。

### 2. Core 与宿主的分工

Expand Down Expand Up @@ -333,11 +333,11 @@ macOS 接入规则（2026-10-18）：
## 验证

- `cargo test --manifest-path rust/Cargo.toml -p lithe-core --lib build_systems`：四个 fixture 通过校验；`build-plans.json` 的全部标准答案；在临时工作区里验证 Cargo 运行入口与内置探测器逐字一致、嵌套、优先级与拒绝、Maven reactor 识别、Gradle 规范格式输出文件、JUnit 报告、同步指纹、Maven 任务参数与内置实现一致，以及互斥条件下允许重复引用选项。
- `cargo test --manifest-path rust/Cargo.toml -p lithe-core --lib build_systems` 还覆盖 Provider：`build-plans.json` 里 `gradle-provider`、`mix-provider` 的请求计划和 `result` 解码；`provider_processes_are_install_review_programs`（自有进程和共享写法在安装审查中的条目）；`launch_plans_name_exactly_one_process`；`provider_models_are_not_read_during_detection`。
- `cargo test --manifest-path rust/Cargo.toml -p lithe-core --lib build_systems` 还覆盖 Provider：`build-plans.json` 里 `build-provider`、`build-provider-language-server` 的请求计划和 `result` 解码；`provider_processes_are_install_review_programs`（自有进程和共享写法在安装审查中的条目）；`launch_plans_name_exactly_one_process`；`provider_models_are_not_read_during_detection`。
- `cargo test --manifest-path rust/Cargo.toml -p lithe-core --lib declarative_plugins`：`invalid-manifests.json` 里的非法清单，包括社区插件声明 `hostIntegration`、未声明权限、路径越界、未保护的模板变量和选项重复放置，以及 Provider 的十种错误写法（没有来源使用、混写、缺少标志、缺少权限、入口越界、不支持的运行时、未声明的设置等），和裁剪后不再接受的九种写法（静态 `yaml`、命令 `json`、任务规则、顶层目标、`parent`、映射标签、`parentDirectory`、依赖 `children`、`layout.generated`）；`command-plans.json` 里按 `buildSystemID` 选中的启动计划。
- `declarative_plugins::build_providers_require_their_own_host_capability` 与 `marketplace_plugins::build_provider_versions_require_host_support_before_download` 验证 Provider 能力与声明式构建分开，安装审查的共享 fixture 同时覆盖自有进程和共享写法。
- `cargo test -p lithe-core --lib lsp`：`lsp/interface/build_provider.rs` 验证只有宿主提供过的版本算协商成功、版本 1 只接受两个方法；`engine.rs` 的测试验证协商后的会话写出 `lithe/build/*` 并返回结果，未协商或方法不在版本里时直接失败、不写入进程。
- `./scripts/test-macos.sh --filter 'BuildSystemServiceTests'` 的 Provider 用例：`providerModelSendsThePlannedRequestAndDecodesItsReply`、`providerDependenciesDecodeTheProvidersReply` 验证请求原样发给按插件、构建系统和工作区确定的目标，回复作为 `providerResult` 交给 Core 解码且不启动命令；`workspaceSwitchAndDisabledPluginStopTheirProviders` 验证停用插件和切换工作区停止进程、插件列表不变时保留；`providerModelFailsWithoutAProviderHost`、`failedProviderRequestReportsItsMessage` 验证失败路径。`providerModelLoadCarriesTheResolvedToolWithoutRefresh`、`providerReloadsAskForARefresh`、`providerLoadsWithoutTheToolWhenResolutionFails`、`commandModelLoadsDoNotResolveAProviderTool` 验证加载原因和工具路径：首次加载不带 `refresh`、重新加载的模型和依赖都带，工具只在 Provider 请求时解析，解析失败时请求照常发出且 Build Output 写明原因；`MacBuildProviderSessionsTests.providerHintsReachTheProcessUnchanged` 验证这两个字段原样到达进程，`PluginWebBridgeTests.pageRefreshReloadsTheModel` 验证网页的 `build.refresh` 算重新加载。`build-plans.json` 的 `gradle provider … refresh …`、`… tool must be an absolute path`、`gradle model command ignores …` 用例覆盖 Core 的写入、校验和命令来源忽略。`PluginMarketplaceServiceTests.buildProvidersAreAcceptedByTheMacOSHost` 验证 `gradle-provider`、`mix-provider` 能通过 macOS 的安装审查。`MacBuildProviderSessionsTests` 用真实的 `MacBuildProviderSessions` 和脚本化 Core 验证：重复请求复用进程，按插件停止后下一次请求重新启动；设置变化后按新参数重启；包内入口不可执行时不启动进程。`PluginPackageStoreTests.unusablePackagedBuildProviderIsRefused`、`buildProviderRuntimeEntryMustBeInThePackage` 验证安装时校验 Provider 的包内入口：缺失、不可执行、经过符号链接都被拒绝，运行时入口缺失也被拒绝。
- `./scripts/test-macos.sh --filter 'BuildSystemServiceTests'` 的 Provider 用例：`providerModelSendsThePlannedRequestAndDecodesItsReply`、`providerDependenciesDecodeTheProvidersReply` 验证请求原样发给按插件、构建系统和工作区确定的目标，回复作为 `providerResult` 交给 Core 解码且不启动命令；`workspaceSwitchAndDisabledPluginStopTheirProviders` 验证停用插件和切换工作区停止进程、插件列表不变时保留；`providerModelFailsWithoutAProviderHost`、`failedProviderRequestReportsItsMessage` 验证失败路径。`providerModelLoadCarriesTheResolvedToolWithoutRefresh`、`providerReloadsAskForARefresh`、`providerLoadsWithoutTheToolWhenResolutionFails`、`commandModelLoadsDoNotResolveAProviderTool` 验证加载原因和工具路径：首次加载不带 `refresh`、重新加载的模型和依赖都带，工具只在 Provider 请求时解析，解析失败时请求照常发出且 Build Output 写明原因；`MacBuildProviderSessionsTests.providerHintsReachTheProcessUnchanged` 验证这两个字段原样到达进程，`PluginWebBridgeTests.pageRefreshReloadsTheModel` 验证网页的 `build.refresh` 算重新加载。`build-plans.json` 的 `gradle provider … refresh …`、`… tool must be an absolute path`、`gradle model command ignores …` 用例覆盖 Core 的写入、校验和命令来源忽略。`PluginMarketplaceServiceTests.buildProvidersAreAcceptedByTheMacOSHost` 验证 `build-provider`、`build-provider-language-server` 能通过 macOS 的安装审查。`MacBuildProviderSessionsTests` 用真实的 `MacBuildProviderSessions` 和脚本化 Core 验证：重复请求复用进程，按插件停止后下一次请求重新启动；设置变化后按新参数重启；包内入口不可执行时不启动进程。`PluginPackageStoreTests.unusablePackagedBuildProviderIsRefused`、`buildProviderRuntimeEntryMustBeInThePackage` 验证安装时校验 Provider 的包内入口：缺失、不可执行、经过符号链接都被拒绝，运行时入口缺失也被拒绝。
- `./scripts/verify-shared-contracts.sh`：schema 与 fixture 一致；`build-plans.json` 的用例名唯一、操作合法、拒绝码都有文档、不含机器路径；`command-plans.json` 的每个用例只给出 `languageID`、`buildSystemID` 之一。
- `./scripts/verify-rust-core-comments.sh`：`build/` 模块的注释规范。
- `./scripts/test-macos.sh --filter 'BuildSystemToolWindowTests'`：选项根选择保留各实例的候选和生效值，原生菜单动作覆盖自定义单选替换、多选追加及取消已选自定义值；原生 `NSTextField` 提交验证 text/file/directory 清空后提交 `""` 而非重置。设置 `LITHE_BUILD_CAPTURE_DIR` 后可导出选项行的明暗截图。`BuildSystemServiceTests.instanceOptionEditsPreserveSiblingOnlySelections` 验证编辑一个实例不会丢掉另一个实例独有的选择；`languageImportPublishesTheSameEffectiveOptionsAsBuildPlansAndClearsDisabledPlugins` 验证插件配置与构建计划使用同一份生效值、修改后重新发布、停用及重置清理；`RustBuildSystemOperationsTests.languageImportMapsPluginOptionIDsWithoutBuildSystemNameAssumptions` 验证真实 Core 的导入映射和 Maven 可选执行字段解码。本地 Maven、Gradle fixture 副本经真实 Core 校验后读出 `icon`、`presentation`、选项图标和 `category`；模型任务自带的 `category`；每个构建系统推导出的窗口和命令（ID、标题、停靠、命令与窗口分开的动作），以及注册表校验通过。补充回归覆盖窗口所属模块激活、命令 pending 状态、独立窗口停靠与显隐恢复、旧 Maven 贡献及命令移除、参数任务根工程与目标作用范围。临时插件包中的窗口与选项明暗 SVG 加载后，目录清单和每个文件的字节必须完全不变。
Expand Down
4 changes: 2 additions & 2 deletions ...ts/notes/implemented/architecture/2026-10-20-host-plugin-function-invocation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -148,13 +148,13 @@ if pluginID == "dev.lithe.maven" { 启动带函数的会话 } // 宿主按插
- 每个 Provider 带独有的 `LITHE_PLUGIN_BACKEND_SCOPE`，会话结束后宿主按该标记优雅结束遗留进程。
- `./scripts/verify-runtime-bundle-immutability.sh`：确认没有新增写入 bundle 的路径。
- macOS 原生验收（2026-10-20，PR #1366 合并 PR #1365 后的 debug 应用）：
- 环境：`sdk/node/examples/sample-build` 加一个只用于验收的网页窗口，作为开发包从磁盘安装；另装一个带自己构建系统和网页窗口的验收插件；示例工作区含成功、失败（退出码 3）和长时间运行三个项目。页面把每一步结果写进 `ui.setState`，验收读取 Application Support 中的状态文件核对。
- 环境：Node SDK 的示例插件 `sdk/node/examples/sample-build`（当时在主仓库，现位于 lithe-plugin-docs）加一个只用于验收的网页窗口，作为开发包从磁盘安装；另装一个带自己构建系统和网页窗口的验收插件；示例工作区含成功、失败（退出码 3）和长时间运行三个项目。页面把每一步结果写进 `ui.setState`，验收读取 Application Support 中的状态文件核对。
- `functions.list` 返回 `snapshot.read`、`workspace.build`；一次成功构建后再列出，多了运行时注册的 `snapshot.clear`。
- `functions.invoke` 带 `call` 时，页面依次收到 `Preparing`、`Building app`、`Done` 三个 `functions.progress`，结果作为 `{ value }` 到达；失败项目返回 `plugin.function.failed`，并带上插件自己的 `pluginErrorCode: sample.buildFailed`。
- `functions.cancel` 后调用以 `requestCancelled` 结束；构建子进程在取消后立刻退出（采样中最后一次出现早于取消约 0.1 秒）。对已结束的 `call` 再取消返回 `{}`。未注册的函数返回 `plugin.function.unknown`，`params` 不是对象返回 `plugin.web.invalidRequest`。
- 另一个插件的页面用 `sample:.` 调用 `functions.list` / `functions.invoke` 都得到 `plugin.web.forbidden`，并且在弹同意框之前就被拒绝；它调用自己实例上的 `snapshot.read` 得到 `plugin.function.unknown`，说明函数按进程隔离。
- 进程清理：调用进行中关闭项目、或在设置里停用插件，Provider 及其构建子进程都会退出（`ps`/`pgrep` 确认）；从磁盘替换插件包时旧 Provider 也会停止；退出应用后没有任何 Lithe 或插件进程残留。重启应用后 `snapshot.read` 返回上次会话的快照。
- 验收发现示例的路径检查在宿主 `rootUri` 带尾部斜杠时拒绝所有路径（macOS 传的是目录 URL 的 `absoluteString`），所有构建都报 `sample.config`。已在示例里用 `path.resolve` 规范化根目录，并让 `rust/lithe-core/tests/plugin_sdk_node.rs` 用带尾部斜杠的 `rootUri`；未修复时该测试失败，修复后通过。
- 验收发现示例的路径检查在宿主 `rootUri` 带尾部斜杠时拒绝所有路径（macOS 传的是目录 URL 的 `absoluteString`），所有构建都报 `sample.config`。已在示例里用 `path.resolve` 规范化根目录，并让当时主仓库的 `rust/lithe-core/tests/plugin_sdk_node.rs`（现为 lithe-plugin-docs 的 `sdk/e2e/plugin_sdk_node.rs`）用带尾部斜杠的 `rootUri`；未修复时该测试失败，修复后通过。
- `./scripts/verify-platform-feature-matrix.sh`：`plugin-functions` 的 macOS 证据已更新。

## 适用范围
Expand Down
Loading
Loading