108 lines
5.5 KiB
Markdown
108 lines
5.5 KiB
Markdown
# Plugin Command 与 Settings 开发说明
|
||
|
||
> 更新日期：2026-09-02。本文记录第二阶段阶段 D 已实现的 Plugin Command Contribution、Plugin Settings Contribution、Secret 边界和前端 Service Contract。当前回归基线为后端 103 项测试、前端 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 和超时。
|
||
|
||
`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 使用同样的注销/重新注册生命周期，避免前端看到实际不可执行的命令。
|
||
|
||
执行顺序如下：
|
||
|
||
1. 查找已注册 Command；
|
||
2. 使用 Draft 2020-12 JSON Schema 校验 arguments；
|
||
3. 根据 `when` 检查必要上下文；
|
||
4. 仅向执行器传递声明过的 Context 字段；
|
||
5. 在超时范围内调用宿主受控 handler；
|
||
6. 校验 effect 类型、可序列化性和 64 KiB 大小上限；
|
||
7. 返回统一 `PluginCommandResult`。
|
||
|
||
首批 effect 为 `none`、`notification`、`navigate`、`refresh` 和 `job`。前端不得把 effect 当作任意代码执行。
|
||
|
||
Command 审计使用 500 条有界内存队列，仅保留 `command_id`、`plugin_id`、成功/失败状态、耗时、错误码和时间。arguments、正文选区、文件路径、effect 与 Secret 均不进入审计事件。
|
||
|
||
当前声明式宿主提供安全白名单 handler，后续如允许 MCP Server 承担 Command 逻辑，应增加独立的 MCP Command Target Contract，不能把插件给出的模块路径或 Shell 字符串直接执行。
|
||
|
||
## 4. Settings 与 Secret 边界
|
||
|
||
普通 Settings 以 Plugin 为命名空间持久化到：
|
||
|
||
```text
|
||
APP_DATA_DIR/plugins/settings.json
|
||
```
|
||
|
||
该文件只包含：
|
||
|
||
- 当前 Schema 版本；
|
||
- 非敏感字段值；
|
||
- Secret 的确定性引用，例如 `plugin.text-tools.api_key`。
|
||
|
||
Secret 写入必须调用专用端点。后端通过 `SecretStr` 接收明文，再交给现有 `EncryptedCredentialStore`；普通 Settings API 只返回 `{ configured: true|false }`，不会返回 Secret 值。卸载 Plugin 时同时删除普通设置命名空间和对应加密凭据。
|
||
|
||
开发阶段凭据文件由本机 Fernet Key 加密。桌面端落地后，应由 Tauri Host 将同一引用语义迁移到 Stronghold 或系统 Keychain，HTTP Contract 无需因此改变。
|
||
|
||
## 5. HTTP 与前端 Service
|
||
|
||
后端已实现：
|
||
|
||
```text
|
||
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. 验证
|
||
|
||
```powershell
|
||
cd backend
|
||
uv run pytest
|
||
|
||
cd ../frontend
|
||
pnpm test -- --run
|
||
pnpm type-check
|
||
pnpm build
|
||
```
|
||
|
||
阶段 D 测试覆盖注册/注销生命周期、位置过滤、参数与 Context 校验、上下文裁剪、设置影响命令执行、五类设置字段、Schema 版本冲突、Secret 密文与清理、损坏存储、无效贡献文件、OpenAPI 路径和前端 Service 请求格式。
|
||
|
||
生产构建仍会报告现有大 Chunk 警告，不影响构建成功；该问题属于前端按路由和 Markdown 依赖拆包的后续性能任务。
|