docs(extension): 补充阶段C MCP开发说明
This commit is contained in:
@@ -1,6 +1,6 @@
|
||||
# 后端接口契约（开发版）
|
||||
|
||||
> 更新日期：2026-08-31。本文档记录当前前后端联调使用的已实现接口；机器可读字段、校验规则和响应模型以 FastAPI 运行时生成的 OpenAPI 为准。第二阶段尚未实现的规划接口见 `第二阶段接口契约-开发版.md`，不要将规划路径视为当前服务能力。
|
||||
> 更新日期：2026-09-01。本文档记录当前前后端联调使用的已实现接口；机器可读字段、校验规则和响应模型以 FastAPI 运行时生成的 OpenAPI 为准。第二阶段尚未实现的规划接口见 `第二阶段接口契约-开发版.md`，不要将规划路径视为当前服务能力。
|
||||
|
||||
## 契约入口
|
||||
|
||||
@@ -76,6 +76,8 @@ Web 联调阶段只暴露后端通过 `APP_VAULT_PATH` 配置的单一 Vault，
|
||||
| POST | `/api/plugins/{plugin_id}/enable` | 启用 Plugin |
|
||||
| POST | `/api/plugins/{plugin_id}/disable` | 停用 Plugin |
|
||||
| PUT | `/api/plugins/{plugin_id}/permissions` | 设置 Plugin 已授权权限 |
|
||||
| GET | `/api/plugins/{plugin_id}/host` | 获取隔离 MCP Host 状态、工具数和协商信息 |
|
||||
| POST | `/api/plugins/{plugin_id}/host/restart` | 重启 MCP Host 并重新发现、校验和注册 Tool |
|
||||
| DELETE | `/api/plugins/{plugin_id}` | 卸载 Plugin |
|
||||
|
||||
### Provider
|
||||
@@ -174,7 +176,7 @@ RunCancelled
|
||||
|
||||
## 当前实现状态
|
||||
|
||||
更新至 2026-09-01：后端 81 项回归测试通过。
|
||||
更新至 2026-09-01：后端 87 项回归测试通过。
|
||||
|
||||
- Chat、Agent Run、Agent Events、Tool 列表、Provider 配置生命周期、模型列表和连接测试已经接入 AI Core。
|
||||
- Agent Run/Event 已持久化到 SQLite；SSE 帧携带 sequence `id`，断线后可以回放缺失事件。Trace API 与 Benchmark 共用同一事件事实，并在入库前执行 Secret 脱敏和结果限长。
|
||||
@@ -183,6 +185,7 @@ RunCancelled
|
||||
- Workspace 已接入后端配置的真实 Vault；文件树、笔记读写、文件/目录新建、重命名和删除不再使用前端 Mock Fallback。
|
||||
- Note Move 保留 `note_id`；Citation 的字符偏移统一使用 UTF-16 code unit，供浏览器编辑器直接定位。
|
||||
- Plugin 启用前必须通过权限接口记录授权，未知权限默认拒绝。
|
||||
- 本地 stdio MCP Server 已通过独立子进程接入 Plugin Runtime；Agent 只消费内部 Tool Contract。Host 支持 initialize、分页发现、调用、超时取消、状态查询、重启和异常退出后的 Tool 注销。
|
||||
- Attachment Tool 读取 Host 管理的 `attachments` 目录；音频接口读取 Host 生成的转写文本，真实本地语音模型在第二阶段接入。
|
||||
- 接入业务模块时保持当前路径和 Contract，不在 Router 中直接实现数据库、Provider 或 Agent 逻辑。
|
||||
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
> 文档状态：接口冻结草案
|
||||
>
|
||||
> 更新日期：2026-08-31
|
||||
> 更新日期：2026-09-01
|
||||
>
|
||||
> 依据：`../architecture/第二阶段团队分工表.md`、`../architecture/AI笔记软件技术栈说明-团队版-v2.3.md`、`后端接口契约-开发版.md`
|
||||
|
||||
@@ -45,8 +45,8 @@
|
||||
| Transcription | POST | `/api/media/transcriptions/{job_id}/notes` | 计划新增 | 将 Transcript 写入 Knowledge Core |
|
||||
| Agent Trace | GET | `/api/agent/runs/{run_id}/events` | 已实现 | 支持游标恢复并增加模型与权限事件 |
|
||||
| Agent Trace | GET | `/api/agent/runs/{run_id}/trace` | 已实现 | 分页读取可回放 Trace 快照 |
|
||||
| Plugin Host | GET | `/api/plugins/{plugin_id}/host` | 计划新增 | 获取 MCP Host 健康状态 |
|
||||
| Plugin Host | POST | `/api/plugins/{plugin_id}/host/restart` | 计划新增 | 重启异常 Host 并重新发现 Tool |
|
||||
| Plugin Host | GET | `/api/plugins/{plugin_id}/host` | 已实现 | 获取 MCP Host 健康状态 |
|
||||
| Plugin Host | POST | `/api/plugins/{plugin_id}/host/restart` | 已实现 | 重启异常 Host 并重新发现 Tool |
|
||||
| Plugin Command | GET | `/api/plugin-contributions/commands` | 计划新增 | 获取前端可展示的 Command |
|
||||
| Plugin Command | POST | `/api/plugin-contributions/commands/{command_id}/execute` | 计划新增 | 受控执行 Command |
|
||||
| Plugin Settings | GET | `/api/plugins/{plugin_id}/settings` | 计划新增 | 获取 Schema 与非敏感配置 |
|
||||
@@ -427,7 +427,29 @@ class McpBridge(Protocol):
|
||||
async def stop(self, plugin_id: str) -> None: ...
|
||||
```
|
||||
|
||||
首个实现支持本地 `stdio`。Host 负责 initialize、capability negotiation、进程生命周期、超时、取消、stderr 隔离和异常退出后的 Tool 注销。
|
||||
首个实现已支持本地 `stdio`，按 MCP `2025-11-25` 发起 initialize，并兼容 `2025-06-18`、`2025-03-26` 和 `2024-11-05` 协商结果。Host 负责 capability negotiation、分页 `tools/list`、进程生命周期、超时取消、stderr 隔离和异常退出后的 Tool 注销。stdio 消息使用 UTF-8 单行 JSON-RPC；当前不实现 Streamable HTTP。
|
||||
|
||||
MCP Plugin 的 `backend` 增加：
|
||||
|
||||
```yaml
|
||||
backend:
|
||||
type: mcp
|
||||
transport: stdio
|
||||
command: python
|
||||
args: [server.py]
|
||||
startup_timeout_seconds: 5
|
||||
tool_timeout_seconds: 30
|
||||
```
|
||||
|
||||
命令通过参数数组直接启动，不经过 Shell。带路径的 executable 必须位于 Plugin 包内；PATH 中的命令可以按名称引用。子进程只继承运行所需的系统环境变量，不继承 `OPENAI_API_KEY`、`APP_DB_PATH`、Vault 路径等宿主状态。Secret 注入留给阶段 D 的专用引用接口。
|
||||
|
||||
远端 Tool 的可选项目权限放在 MCP `_meta`：
|
||||
|
||||
```json
|
||||
{ "_meta": { "notesagent/permission": "notes.read" } }
|
||||
```
|
||||
|
||||
该权限必须属于项目已知权限并同时出现在 Plugin Manifest 中。发现结果必须与 `contributes.tools` 的命名空间 ID 完全一致；校验全部成功后才一次性发布到 Tool Registry。
|
||||
|
||||
当前 Web 开发接口 `POST /api/plugins/install` 使用 `package_path`。桌面 Host 接入后，`ExtensionInstallRequest` 增加 `package_id`，由文件选择器产生临时包句柄；`package_path` 只在明确的 development 环境保留并标记 deprecated，生产构建拒绝任意前端路径。
|
||||
|
||||
@@ -460,6 +482,8 @@ error
|
||||
|
||||
`POST /api/plugins/{plugin_id}/host/restart` 返回 `202 OperationResponse`。重启期间先注销旧 Tool，发现和校验全部成功后再一次性发布新 Tool 集合，避免半注册状态。
|
||||
|
||||
当前实现还返回协商后的 `protocol_version`、`server_name` 和 `server_version`。单条协议消息上限为 2 MiB，单次 Tool Result 上限为 256 KiB；超限分别按 Host/Result 错误处理。Server 异常退出或发送无效 stdout 消息时，Host 进入 `unhealthy`，Plugin 进入 `error`，相关 Tool 立即注销。
|
||||
|
||||
### 7.3 Command Contribution 列表
|
||||
|
||||
`GET /api/plugin-contributions/commands?location=command_palette`
|
||||
|
||||
Reference in New Issue
Block a user