feat(extension): 实现 Plugin Command 与 Settings Contribution #10

2026-09-02T20:05:35+08:00

Kronecker commented

2026-09-02 20:05:35 +08:00

变更概述

完成第二阶段 Stage D 的 Plugin Command 与 Settings Contribution，实现插件命令注册、执行、设置管理、敏感配置传递及 MCP 命令目标适配，并补充前后端契约、测试和开发文档。

主要改动

Plugin Command

支持从插件清单注册和注销命令
支持查询插件命令列表
支持命令参数 JSON Schema 校验
支持基于运行上下文和 when 条件控制命令可用性
支持命令执行超时和审计记录
区分 Plugin Command 与 Agent Tool，避免混用执行语义
支持声明式宿主命令和 MCP 命令目标
为 MCP 命令建立固定 _notesagent 调用信封：
- command_id
- arguments
- context
- settings
- secrets

Settings Contribution

支持插件设置 Schema、类型、默认值及版本管理
支持普通设置的持久化和运行时读取
插件启用和命令执行前检查必填设置
缺少必填设置时返回 PLUGIN_SETTINGS_REQUIRED
支持敏感设置的加密引用存储
敏感配置通过独立 secrets 命名空间传递
避免在接口响应、日志和命令 Effect 中暴露明文密钥
支持设置写入的事务性处理

Command Effect 契约

将命令执行结果收紧为判别联合类型：

notification
navigate
refresh
job
none

同时限制：

通知级别和消息长度
前端路由名称
可刷新资源范围
后台任务 ID 格式

前后端现已使用一致的严格 Effect 类型定义。

审阅修复

MCP 目标 Schema 未进入运行时

原因： MCP 工具发现阶段只识别了目标名称，没有保存对应的 inputSchema。

后果： 插件启用后无法验证实际命令信封是否满足 MCP 服务端契约。

修复：

在插件运行记录中保存 MCP 命令 Schema
在禁用、重启、回滚和不可用状态下同步清理
执行前使用 Draft 2020-12 校验器验证完整调用信封
校验失败统一映射为 PLUGIN_COMMAND_TARGET_SCHEMA_MISMATCH

MCP 协议兼容性判断不稳定

原因： 启用阶段曾使用空测试数据推断 Schema 是否兼容，容易误拒绝带业务约束的合法 Schema。

修复：

改为检查顶层 properties._notesagent
要求 _notesagent 明确声明为 object
_notesagent 内部允许 $ref、allOf、oneOf、not 等标准约束
完整约束交由正式 Draft 2020-12 校验器在执行阶段处理
移除不完整的自定义 Schema 可满足性判断逻辑

必填普通设置未阻止运行

原因： 原实现只读取已有设置，没有检查无默认值的必填项。

后果： 插件可能在配置不完整时启用或执行，导致运行期错误。

修复：

插件启用前检查必填设置
每次命令执行前重新检查
缺少配置时返回明确的 409 错误

敏感配置测试覆盖不足

原因： MCP 测试服务即使未收到密钥也可能返回成功，无法证明密钥传递链路有效。

修复：

MCP fixture 在未收到 secrets.api_key 时返回错误
测试仅验证密钥是否到达，不返回或记录密钥明文

空 Echo 命令产生无效 Effect

原因： 空消息仍被构造为通知 Effect，与通知消息最小长度约束冲突。

后果： 合法空 Echo 调用会被转换成 502 响应。

修复：

空消息返回 none Effect
非空消息继续返回通知 Effect
增加空值和非空值回归测试

文档更新

更新第二阶段接口契约开发版
更新 Plugin Command 与 Settings 开发说明
补充 Effect 类型、错误码、MCP 信封协议及必填设置规则
明确 MCP Schema 的启用阶段检查和执行阶段校验边界

验证结果

后端测试：136 passed
前端测试：29 passed
TypeScript 类型检查：通过
前端生产构建：通过
uv lock --check：通过
git diff --check：通过

前端构建仍存在已有的大体积 chunk 提示，不影响本次合并。

后续事项

生产环境 MCP 执行仍需等待 Tauri/Rust 安全沙箱阶段完成后开放。本阶段保留运行时边界、协议校验及测试能力，不将当前进程执行方式视为最终生产安全方案。

## 变更概述完成第二阶段 Stage D 的 Plugin Command 与 Settings Contribution，实现插件命令注册、执行、设置管理、敏感配置传递及 MCP 命令目标适配，并补充前后端契约、测试和开发文档。 ## 主要改动 ### Plugin Command - 支持从插件清单注册和注销命令 - 支持查询插件命令列表 - 支持命令参数 JSON Schema 校验 - 支持基于运行上下文和 `when` 条件控制命令可用性 - 支持命令执行超时和审计记录 - 区分 Plugin Command 与 Agent Tool，避免混用执行语义 - 支持声明式宿主命令和 MCP 命令目标 - 为 MCP 命令建立固定 `_notesagent` 调用信封： - `command_id` - `arguments` - `context` - `settings` - `secrets` ### Settings Contribution - 支持插件设置 Schema、类型、默认值及版本管理 - 支持普通设置的持久化和运行时读取 - 插件启用和命令执行前检查必填设置 - 缺少必填设置时返回 `PLUGIN_SETTINGS_REQUIRED` - 支持敏感设置的加密引用存储 - 敏感配置通过独立 `secrets` 命名空间传递 - 避免在接口响应、日志和命令 Effect 中暴露明文密钥 - 支持设置写入的事务性处理 ### Command Effect 契约将命令执行结果收紧为判别联合类型： - `notification` - `navigate` - `refresh` - `job` - `none` 同时限制： - 通知级别和消息长度 - 前端路由名称 - 可刷新资源范围 - 后台任务 ID 格式前后端现已使用一致的严格 Effect 类型定义。 ## 审阅修复 ### MCP 目标 Schema 未进入运行时 **原因：** MCP 工具发现阶段只识别了目标名称，没有保存对应的 `inputSchema`。 **后果：** 插件启用后无法验证实际命令信封是否满足 MCP 服务端契约。 **修复：** - 在插件运行记录中保存 MCP 命令 Schema - 在禁用、重启、回滚和不可用状态下同步清理 - 执行前使用 Draft 2020-12 校验器验证完整调用信封 - 校验失败统一映射为 `PLUGIN_COMMAND_TARGET_SCHEMA_MISMATCH` ### MCP 协议兼容性判断不稳定 **原因：** 启用阶段曾使用空测试数据推断 Schema 是否兼容，容易误拒绝带业务约束的合法 Schema。 **修复：** - 改为检查顶层 `properties._notesagent` - 要求 `_notesagent` 明确声明为 `object` - `_notesagent` 内部允许 `$ref`、`allOf`、`oneOf`、`not` 等标准约束 - 完整约束交由正式 Draft 2020-12 校验器在执行阶段处理 - 移除不完整的自定义 Schema 可满足性判断逻辑 ### 必填普通设置未阻止运行 **原因：** 原实现只读取已有设置，没有检查无默认值的必填项。 **后果：** 插件可能在配置不完整时启用或执行，导致运行期错误。 **修复：** - 插件启用前检查必填设置 - 每次命令执行前重新检查 - 缺少配置时返回明确的 409 错误 ### 敏感配置测试覆盖不足 **原因：** MCP 测试服务即使未收到密钥也可能返回成功，无法证明密钥传递链路有效。 **修复：** - MCP fixture 在未收到 `secrets.api_key` 时返回错误 - 测试仅验证密钥是否到达，不返回或记录密钥明文 ### 空 Echo 命令产生无效 Effect **原因：** 空消息仍被构造为通知 Effect，与通知消息最小长度约束冲突。 **后果：** 合法空 Echo 调用会被转换成 502 响应。 **修复：** - 空消息返回 `none` Effect - 非空消息继续返回通知 Effect - 增加空值和非空值回归测试 ## 文档更新 - 更新第二阶段接口契约开发版 - 更新 Plugin Command 与 Settings 开发说明 - 补充 Effect 类型、错误码、MCP 信封协议及必填设置规则 - 明确 MCP Schema 的启用阶段检查和执行阶段校验边界 ## 验证结果 - 后端测试：136 passed - 前端测试：29 passed - TypeScript 类型检查：通过 - 前端生产构建：通过 - `uv lock --check`：通过 - `git diff --check`：通过前端构建仍存在已有的大体积 chunk 提示，不影响本次合并。 ## 后续事项生产环境 MCP 执行仍需等待 Tauri/Rust 安全沙箱阶段完成后开放。本阶段保留运行时边界、协议校验及测试能力，不将当前进程执行方式视为最终生产安全方案。

Kronecker added 7 commits 2026-09-02 20:05:36 +08:00

Kronecker merged commit ff3da5d6b1 into main

2026-09-02 20:05:43 +08:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: Kronecker/NotesAgentic#10