Plugin Command 与 Settings 开发说明

更新日期：2026-09-02。本文记录第二阶段阶段 D 已实现的 Plugin Command Contribution、Plugin Settings Contribution、Secret 边界和前端 Service Contract。当前回归基线为后端 121 项测试、前端 29 项测试，TypeScript 类型检查和生产构建通过。

1. 阶段目标

阶段 D 在阶段 C 的 Plugin Runtime 与隔离 MCP Host 上补齐两类宿主贡献：

Command：插件声明命令，宿主负责注册、展示、校验、执行和返回白名单 effect；
Settings：插件声明设置 Schema，宿主负责动态表单 Contract、非敏感值持久化和 Secret 加密引用；
Frontend Contract：提供稳定的 TypeScript DTO 与 Service，供后续命令面板、右键菜单和插件设置页直接联调。

本阶段不实现前端页面，也不把第三方代码导入 FastAPI 进程。操作系统级安全沙箱仍按规划在第三阶段桌面基础集成完成后、Tauri/Rust 沙箱正式构建前处理。

2. 包内声明

Plugin 在 plugin.yaml 的 contributes.commands 与 contributes.settings_sections 声明贡献标识，并分别提供 commands.yaml、settings.yaml。安装时宿主要求声明集合与文件内容完全一致，拒绝重复项、越过 Plugin 命名空间的 ID、未声明权限和无效 Schema。

commands.yaml 的首批字段包括：

command_id、标题、描述、宿主图标；
locations：command_palette、context_menu 或 toolbar；
when 与允许传入执行器的 Context 字段；
参数 JSON Schema、可选权限、执行目标和超时；
执行目标必须在宿主白名单 handler 与当前插件命名空间的 mcp_tool 之间二选一。
可选 secrets 字段：只声明当前 Command 允许按需读取的 Secret Setting Key，不暴露给前端 DTO。

settings.yaml 采用递增 schema_version，首批字段类型固定为 string、number、boolean、select、secret。宿主会校验默认值、必填项、数值边界、Select 选项，以及 Secret 不得携带默认明文。

仓库内 text-tools 是联调 Fixture，覆盖 Command 和五种 Settings 字段类型。

3. Command 运行链路

CommandRegistry 只发布处于启用状态的 Plugin Command。Plugin 禁用、Host 不可用或重启时，Command 与 Tool 使用同样的注销/重新注册生命周期，避免前端看到实际不可执行的命令。

执行顺序如下：

查找已注册 Command；
使用 Draft 2020-12 JSON Schema 校验 arguments；
根据 when 检查必要上下文；
仅向执行器传递声明过的 Context 字段；
在超时范围内调用宿主受控 handler，或调用独立的 MCP Command Target；
校验 effect 类型、可序列化性和 64 KiB 大小上限；
返回统一 PluginCommandResult。

首批 effect 为 none、notification、navigate、refresh 和 job。前端不得把 effect 当作任意代码执行。

Command 执行器通过受控 Resolver 按需读取 commands.yaml 已声明且确实属于当前 Plugin Schema 的 Secret；使用 Secret 的 Plugin 还必须声明并获授 secrets.use 权限。读取未声明字段返回 PLUGIN_SECRET_ACCESS_DENIED，必填 Secret 未配置则返回 PLUGIN_SECRET_REQUIRED。Secret 不会并入普通 Settings 字典。Command 审计使用 500 条有界内存队列，仅保留 command_id、plugin_id、成功/失败状态、耗时、错误码和时间。arguments、正文选区、文件路径、effect 与 Secret 均不进入审计事件。

MCP Command Target 是专用执行目标，不注册进 Agent ToolRegistry，因此模型无法绕过 Command 权限与 Context 裁剪直接调用。宿主通过 _notesagent 保留包装传入 command_id、已校验 arguments、已裁剪 Context 和声明过的 Secret；MCP Server 必须返回结构化的白名单 effect。远程原始错误不直接透传给 HTTP 调用方。插件仍不能把模块路径或 Shell 字符串作为执行器。

Command 与 Tool 的 JSON Schema 只允许当前文档内的 Fragment 引用（#...）；宿主在注册前递归拒绝 $ref / $dynamicRef 指向的文件、HTTP 或其他外部资源，避免 Schema 校验触发未授权 I/O。

4. Settings 与 Secret 边界

普通 Settings 以 Plugin 为命名空间持久化到：

APP_DATA_DIR/plugins/settings.json

该文件只包含：

当前 Schema 版本；
非敏感字段值；
Secret 的确定性定长引用，格式为 plugin.<sha256(plugin_id\\0setting_key)>。

Secret 写入必须调用专用端点。后端通过 SecretStr 接收明文，再交给现有 EncryptedCredentialStore；普通 Settings API 只返回 { configured: true|false }，不会返回 Secret 值。plugin.* 是保留命名空间，通用凭据 API、Provider 配置、Provider 临时测试凭据和 Provider Resolver 均不得访问，防止覆盖、删除或外发 Plugin Secret。卸载 Plugin 时同时删除普通设置命名空间和对应加密凭据。

读取持久化引用时，宿主会重新计算并核对 plugin.<sha256(...)>，引用不匹配即按损坏存储拒绝处理，不能借由篡改 settings.json 读取或删除 Provider 等其他命名空间的凭据。删除单个 Secret 或卸载 Plugin 时先原子更新 Settings 引用，再删除加密凭据；底层删除失败会恢复原引用。多 Secret 卸载使用一次凭据表原子替换，避免分批删除部分删除。

开发阶段凭据文件由本机 Fernet Key 加密。桌面端落地后，应由 Tauri Host 将同一引用语义迁移到 Stronghold 或系统 Keychain，HTTP Contract 无需因此改变。

5. HTTP 与前端 Service

后端已实现：

GET    /api/plugin-contributions/commands?location=command_palette
POST   /api/plugin-contributions/commands/{command_id}/execute
GET    /api/plugins/{plugin_id}/settings
PUT    /api/plugins/{plugin_id}/settings
PUT    /api/plugins/{plugin_id}/settings/{key}/secret
DELETE /api/plugins/{plugin_id}/settings/{key}/secret

前端 pluginService 已提供对应方法及 Wire DTO，但阶段 D 不创建命令面板或动态设置表单页面。调用方必须使用服务层，不自行拼接路径；Secret 不得写入 Pinia、LocalStorage 或调试日志。

6. 主要错误边界

Command 未注册、冲突、参数或 Context 无效；
执行超时、执行器异常、effect 无效或过大；
Settings Schema 无效、版本冲突、字段类型/边界错误；
Secret 字段不存在、空 Secret、凭据存储异常；
Settings JSON 根结构或 Plugin 命名空间损坏。

以上错误统一转换为 ExtensionError 和稳定业务错误码，HTTP 层不暴露内部堆栈、Secret 或插件返回的原始异常。

7. 验证

cd backend
uv run pytest

cd ../frontend
pnpm test -- --run
pnpm type-check
pnpm build

阶段 D 测试覆盖注册/注销生命周期、位置过滤、参数与 Context 校验、上下文裁剪、设置影响命令执行、声明式 Secret Resolver 与越权拒绝、真实 MCP Command Target 与 Agent Tool 隔离、必填 Secret 传递、外部 Schema 引用拒绝、定长 Secret Reference、篡改引用的跨命名空间阻断、Secret 删除与卸载失败回滚、Provider/通用凭据命名空间隔离、五类设置字段、Schema 版本冲突、Secret 密文与清理、损坏存储、空 Command 列表等无效贡献文件、OpenAPI 路径和前端 Service 请求格式。

生产构建仍会报告现有大 Chunk 警告，不影响构建成功；该问题属于前端按路由和 Markdown 依赖拆包的后续性能任务。

7.5 KiB Raw Blame History Unescape Escape