Merge remote-tracking branch 'origin/main' into feat/knowledge-retrieval-core
# Conflicts: # README.md # backend/app/routes.py # docs/architecture/AI笔记软件技术栈说明-团队版-v2.3.md # docs/development/Knowledge与Retrieval-Core开发说明.md
This commit is contained in:
@@ -2,7 +2,7 @@
|
||||
|
||||
> 本文档用于团队开发和模块联调，记录当前已经落地的核心边界与使用方式。
|
||||
|
||||
> 更新日期：2026-09-01。第一阶段 AI Core、Agent Core、Extension Core 和 Model Core 主链路已经完成；第二阶段 Agent Trace 持久化、可恢复 SSE、stdio MCP Bridge 与隔离 Plugin Host 已落地，后端当前回归基线为 92 项测试通过。
|
||||
> 更新日期：2026-09-02。第一阶段 AI Core、Agent Core、Extension Core 和 Model Core 主链路已经完成；第二阶段 Agent Trace 持久化、可恢复 SSE、stdio MCP Bridge、隔离 Plugin Host 以及 Plugin Command/Settings 已落地，后端当前回归基线为 136 项测试通过。
|
||||
|
||||
## 当前实现
|
||||
|
||||
@@ -68,7 +68,7 @@ Router 只负责 HTTP/SSE 与错误转换，不实现 Agent、Tool 或 Provider
|
||||
- Note、NoteBlock、Markdown Parser：由 Knowledge Core 提供；
|
||||
- FTS5、Vector、RRF、Reranker、Citation：由 Retrieval Core 提供；
|
||||
- 文件系统和 API Key 明文读取：由 Rust Host 提供；
|
||||
- Frontend Extension Slot 与 Plugin Command/Settings：按第二阶段后续阶段实现。
|
||||
- Frontend Extension Slot 与 Plugin Command/Settings UI：后端 Contract 与前端 Service 已完成，页面由前端后续联调。
|
||||
|
||||
## Provider
|
||||
|
||||
@@ -347,6 +347,6 @@ Skill Manifest
|
||||
- Run/Trace 已通过 Repository 接入 SQLite；后续增加按保留策略归档和 Benchmark 引用保护。
|
||||
- Permission 已有核心等待/恢复机制，前端确认 UI 已完成联调和中文展示。
|
||||
- Task 已持久化到 SQLite；Attachment Tool 读取 Host 管理目录中的 UTF-8 文件。
|
||||
- `audio.transcribe` 当前消费 Host 预生成的 transcript；faster-whisper 与说话人分离仍按技术基线在第二阶段接入。
|
||||
- `audio.transcribe` 当前消费 Host 预生成的 transcript；faster-whisper 与说话人分离仍待第二阶段后续接入。
|
||||
- Extension 安装记录暂存内存；后续接入持久化 Registry 与版本升级流程。
|
||||
- 当前 Plugin Host 支持内置声明式 handler 和本地 stdio MCP Server；Streamable HTTP、OS 级沙箱、Plugin Command/Settings 与 UI Contribution 留在后续阶段。
|
||||
- 当前 Plugin Host 支持内置声明式 handler、本地 stdio MCP Server 以及 Plugin Command/Settings；独立 MCP Server Registry 另行支持 stdio、Streamable HTTP 与旧 SSE 兼容。OS 级沙箱与 UI Contribution 留在后续阶段。
|
||||
|
||||
@@ -3,7 +3,7 @@
|
||||
> 本文档用于团队开发和模块联调，记录 Knowledge Core / Retrieval Core 已经落地的
|
||||
> 模块边界、数据模型、接口与使用方式，对应分工表中的杨星萱。
|
||||
|
||||
> 更新日期：2026-09-01。第一阶段 Knowledge/Retrieval 主链路已经完成，并已接入 Agent Tool Registry；完整后端回归基线为 92 项测试通过。
|
||||
> 更新日期：2026-09-02。第一阶段 Knowledge/Retrieval 主链路已经完成，并已接入 Agent Tool Registry；完整后端回归基线为 136 项测试通过。
|
||||
|
||||
## 当前实现
|
||||
|
||||
@@ -198,7 +198,7 @@ cd backend
|
||||
uv run pytest -q
|
||||
```
|
||||
|
||||
当前后端完整测试共 120 个用例通过（单元 + 端到端）。测试通过 `tests/conftest.py` 的 autouse fixture 把
|
||||
当前后端完整测试共 218 个用例通过（单元 + 端到端）。测试通过 `tests/conftest.py` 的 autouse fixture 把
|
||||
数据目录/DB/Vault 重定向到临时目录，不读写真实 `backend/data`，任何本机状态下结果确定。
|
||||
|
||||
## 配置
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# MCP Bridge 与 Plugin Host 开发说明
|
||||
|
||||
> 更新日期：2026-09-01。本文记录第二阶段阶段 C 已实现的本地 stdio MCP Bridge、隔离 Plugin Host、Tool Contract 转换和离线测试方式。Plugin Command 与 Settings 属于阶段 D，不在本文实现范围内。
|
||||
> 更新日期：2026-09-02。本文记录第二阶段阶段 C 已实现的本地 stdio MCP Bridge、隔离 Plugin Host、Tool Contract 转换和离线测试方式。阶段 D 的 Plugin Command 与 Settings 已在其独立开发说明中落地。
|
||||
|
||||
## 1. 目标与实现状态
|
||||
|
||||
@@ -235,6 +235,7 @@ backend/extensions/fixtures/mcp-echo
|
||||
- `mcp-fixture.large`：验证结果大小上限；
|
||||
- `mcp-fixture.environment`：验证宿主 Secret/路径没有进入子进程；
|
||||
- `mcp-fixture.exit`：验证异常退出、Tool 注销和 Restart。
|
||||
- `mcp-fixture.command`：作为 Plugin Command 专用 MCP Target，验证 Context 裁剪、Secret 传递和与 Agent Tool 的隔离。
|
||||
|
||||
Fixture 的 `tools/list` 使用两页响应，用于覆盖分页发现。测试还会启动缺少 tools capability、返回无效 Schema/initialize result，以及输出超长无换行 stdout 的变体。
|
||||
|
||||
@@ -279,4 +280,4 @@ pnpm build
|
||||
- 一键安装前的完整命令展示与确认 UI；
|
||||
- Tool 列表热更新的无中断替换。
|
||||
|
||||
阶段 D 将在当前 Plugin Runtime 上继续增加 Command、Settings、Secret Contract 和命名空间 Storage，不修改 Agent 使用内部 Tool Contract 的原则。
|
||||
阶段 D 已在当前 Plugin Runtime 上增加 Command、Settings、Secret Contract 和命名空间 Storage，且未修改 Agent 使用内部 Tool Contract 的原则。实现细节见《Plugin Command 与 Settings 开发说明》。
|
||||
|
||||
@@ -0,0 +1,117 @@
|
||||
# Plugin Command 与 Settings 开发说明
|
||||
|
||||
> 更新日期：2026-09-03。本文记录第二阶段阶段 D 已实现的 Plugin Command Contribution、Plugin Settings Contribution、Secret 边界及前端闭环。当前回归基线为后端 136 项测试、前端 32 项测试，TypeScript 类型检查和生产构建通过。
|
||||
|
||||
## 1. 阶段目标
|
||||
|
||||
阶段 D 在阶段 C 的 Plugin Runtime 与隔离 MCP Host 上补齐两类宿主贡献：
|
||||
|
||||
- Command：插件声明命令，宿主负责注册、展示、校验、执行和返回白名单 effect；
|
||||
- Settings：插件声明设置 Schema，宿主负责动态表单 Contract、非敏感值持久化和 Secret 加密引用；
|
||||
- Frontend：Plugin 详情页提供 Host 状态、动态设置、Secret 管理与命令执行，全局命令面板加载 command_palette Contribution。
|
||||
|
||||
第三方代码不会导入 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 不得携带默认明文；`NaN` 与正负无穷不能用作上下界。
|
||||
|
||||
仓库内 `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，或调用独立的 MCP Command Target；
|
||||
6. 按 effect 类型校验专属 payload、可序列化性和 64 KiB 大小上限；
|
||||
7. 返回统一 `PluginCommandResult`。
|
||||
|
||||
首批 effect 为 `none`、`notification`、`navigate`、`refresh` 和 `job`。后端分别限制通知级别与消息、宿主路由名、刷新范围和 Job ID；Pydantic 与 TypeScript 均使用同一判别语义，前端不得把 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、已校验的非敏感 Settings 和声明过的 Secret。启用阶段只检查目标 `inputSchema` 在顶层 `properties` 中直接声明 `_notesagent: { type: object }`，不自行求解 JSON Schema，也不用空对象伪造业务数据；引用和组合约束可以放在 `_notesagent` 对象内部。执行阶段再用保留的完整 Schema 和官方 Draft 2020-12 Validator 校验真实信封。MCP Server 必须返回结构化的白名单 effect。远程原始错误不直接透传给 HTTP 调用方。插件仍不能把模块路径或 Shell 字符串作为执行器。
|
||||
|
||||
Command 与 Tool 的 JSON Schema 只允许当前文档内的 Fragment 引用（`#...`）；宿主在注册前递归拒绝 `$ref` / `$dynamicRef` 指向的文件、HTTP 或其他外部资源，避免 Schema 校验触发未授权 I/O。文档内引用使用 Draft 2020-12 Resource Resolver 预检，嵌套 `$id` 创建的新资源及其 Anchor 按各自作用域解析，无法解析的引用在注册阶段返回稳定错误。
|
||||
|
||||
## 4. Settings 与 Secret 边界
|
||||
|
||||
普通 Settings 以 Plugin 为命名空间持久化到：
|
||||
|
||||
```text
|
||||
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 时同时删除普通设置命名空间和对应加密凭据。
|
||||
|
||||
没有默认值的 `required` 普通字段必须在启用 Plugin 前配置。Enable 和每次 Command Execute 都会重新检查有效设置；缺失时返回 `PLUGIN_SETTINGS_REQUIRED`，不启动 MCP Host，也不调用 Command handler。
|
||||
|
||||
读取持久化引用时，宿主会重新计算并核对 `plugin.<sha256(...)>`，引用不匹配即按损坏存储拒绝处理，不能借由篡改 `settings.json` 读取或删除 Provider 等其他命名空间的凭据。删除单个 Secret 或卸载 Plugin 时先原子更新 Settings 引用，再删除加密凭据；底层删除失败会恢复原引用。多 Secret 卸载使用一次凭据表原子替换，避免分批删除部分删除。
|
||||
|
||||
开发阶段凭据文件由本机 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，Plugin 详情页据此展示 MCP Host 状态和重启入口、动态生成五类设置字段、独立写入或删除 Secret，并执行带参数的 Plugin Command。全局命令面板打开时获取 `command_palette` 命令；需要必填参数的命令会引导用户进入详情页填写。调用方必须使用服务层，不自行拼接路径。
|
||||
|
||||
Secret 明文仅存在于当前密码输入框绑定的组件内存，提交后立即清空；不得写入 Pinia、LocalStorage、普通 Settings 请求或调试日志。前端不会读取 Secret 明文，只展示后端返回的 `configured` 状态。
|
||||
|
||||
## 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 校验、上下文裁剪、设置影响命令执行、声明式 Secret Resolver 与越权拒绝、真实 MCP Command Target 与 Agent Tool 隔离、必填 Secret 传递、外部 Schema 引用拒绝、定长 Secret Reference、篡改引用的跨命名空间阻断、Secret 删除与卸载失败回滚、Provider/通用凭据命名空间隔离、五类设置字段、Schema 版本冲突、Secret 密文与清理、损坏存储、空 Command 列表等无效贡献文件、OpenAPI 路径、前端 Service 请求格式、Host 状态展示和动态 Secret 表单。
|
||||
|
||||
生产构建仍会报告现有大 Chunk 警告，不影响构建成功；该问题属于前端按路由和 Markdown 依赖拆包的后续性能任务。
|
||||
@@ -1,6 +1,6 @@
|
||||
# 前端写作体验优化开发说明
|
||||
|
||||
> 更新日期：2026-08-30。本文所述优化均已进入当前分支；前端完整回归基线为 14 项测试通过，TypeScript 检查和 Vite 生产构建通过。
|
||||
> 更新日期：2026-09-02。本文所述优化均已进入 `main`；当前前端完整回归基线为 29 项测试通过，TypeScript 检查和 Vite 生产构建通过。
|
||||
|
||||
## 1. 本次目标
|
||||
|
||||
@@ -103,7 +103,7 @@ pnpm build
|
||||
pnpm test
|
||||
```
|
||||
|
||||
验证结果：TypeScript 类型检查与 Vite 生产构建均通过。当前前端完整回归测试共 14 项；其中写作与文件切换相关回归覆盖：
|
||||
验证结果：TypeScript 类型检查与 Vite 生产构建均通过。当前前端完整回归测试共 29 项；其中写作与文件切换相关回归覆盖：
|
||||
|
||||
- 顶部工具栏对选区应用加粗；
|
||||
- 浮动工具栏对选区应用斜体；
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# 前端壳子与接口层开发说明
|
||||
|
||||
> 更新日期：2026-08-30
|
||||
> 更新日期：2026-09-02
|
||||
> 适用范围：Vue 3 + TypeScript 页面、Workspace、公共 Service、FastAPI 接口适配和 SSE。
|
||||
> 文档用途：帮助团队理解当前前端可用能力、模块边界、启动方式和后续页面开发入口。
|
||||
|
||||
@@ -186,13 +186,13 @@ pnpm build
|
||||
|
||||
```text
|
||||
pnpm build passed
|
||||
pnpm test 27 passed
|
||||
uv run pytest 92 passed
|
||||
pnpm test 29 passed
|
||||
uv run pytest 136 passed
|
||||
preview smoke HTTP 200
|
||||
git diff --check passed
|
||||
```
|
||||
|
||||
当前前端使用 Vitest 执行 Store、Workspace API Adapter、SSE 恢复游标、文件树、编辑器组件、智能体标签、轻量动效约束、Markdown 对比度 Token、scoped CSS 选择器约束和 Shiki GitHub 双主题测试；`pnpm build` 同时执行 `vue-tsc -b` 与 Vite 生产构建。后端测试出现过 `.pytest_cache` 无法写入的 Windows 权限警告，不影响 92 项测试结果，也不涉及产品代码。
|
||||
当前前端使用 Vitest 执行 Store、Workspace API Adapter、SSE 恢复游标、Plugin Command/Settings Service、文件树、编辑器组件、智能体标签、轻量动效约束、Markdown 对比度 Token、scoped CSS 选择器约束和 Shiki GitHub 双主题测试；`pnpm build` 同时执行 `vue-tsc -b` 与 Vite 生产构建。后端测试出现过 `.pytest_cache` 无法写入的 Windows 权限警告，不影响 136 项测试结果，也不涉及产品代码。
|
||||
|
||||
Vite 当前会提示 Chat 与 Workspace 的部分异步 Chunk 超过 500 kB，这是 Milkdown、CodeMirror、KaTeX 和 Shiki 等编辑/渲染依赖带来的性能优化项，不影响构建成功或功能正确性；进入桌面打包前应通过手动分包或更细粒度动态加载继续优化。
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# 模型提供商与模型发现开发说明
|
||||
|
||||
> 更新日期：2026-08-30。OpenAI、DeepSeek、Ollama 预设、模型自动发现、默认模型选择和开发阶段加密凭据存储均已实现并接入设置页。
|
||||
> 更新日期：2026-09-02。OpenAI、DeepSeek、Ollama 预设、模型自动发现、默认模型选择和开发阶段加密凭据存储均已实现并接入设置页。
|
||||
|
||||
## 1. 本次目标
|
||||
|
||||
@@ -104,4 +104,4 @@ pnpm build
|
||||
|
||||
自动化验证覆盖 Provider 预设、OpenAI-Compatible `/models` 请求与鉴权头、模型映射、前端自动刷新、排序去重及按 Provider 隔离错误。生产构建同时执行 Vue 和 TypeScript 类型检查。
|
||||
|
||||
当前完整回归基线：后端 92 项测试、前端 27 项测试通过，前端类型检查和生产构建通过。Provider 配置目前仍保存在内存 Registry，AI Core 重启后需要重新创建；凭据密文会保留。OpenAI Responses 与 Anthropic Messages Adapter 尚未实现，设置页正式预设不会使用这两种协议。
|
||||
当前完整回归基线：后端 136 项测试、前端 29 项测试通过，前端类型检查和生产构建通过。Provider 配置目前仍保存在内存 Registry，AI Core 重启后需要重新创建；凭据密文会保留。`plugin.*` 为 Plugin Secret 保留命名空间，Provider 配置、临时测试凭据和通用凭据 API 均拒绝该前缀。OpenAI Responses 与 Anthropic Messages Adapter 尚未实现，设置页正式预设不会使用这两种协议。
|
||||
|
||||
@@ -0,0 +1,141 @@
|
||||
# 独立 MCP Server 配置中心开发说明
|
||||
|
||||
> 更新日期：2026-09-03。本文记录第二阶段 C.1 的完整实现；独立 MCP Server Registry 与 Plugin 自带 MCP Host 是两个并列入口。
|
||||
|
||||
## 1. 已实现范围
|
||||
|
||||
- 独立 Server 的创建、读取、版本化编辑、删除和 Tool 摘要查询；
|
||||
- `stdio`、Streamable HTTP 和旧版 HTTP+SSE 三种 Transport；
|
||||
- stdio 可执行文件、参数、普通/加密环境变量，以及 HTTP URL、普通/加密 Header；
|
||||
- 配置摘要确认、连接测试、启停、异常状态与最近一次测试结果；
|
||||
- MCP initialize、`tools/list`、`tools/call`、取消与动态 Tool 注册，名称为 `mcp.{server_id}.{tool}`；
|
||||
- Streamable HTTP Session、协议版本 Header、JSON/SSE POST 响应、可选 GET 事件流和 `Last-Event-ID` 重连；
|
||||
- 旧 HTTP+SSE 的 endpoint 事件与消息 POST，并强制消息地址和配置地址同源；
|
||||
- 前端表单/JSON 双模式、三种模板、高风险变更确认及请求期 Secret 输入。
|
||||
|
||||
Streamable HTTP 按 MCP 当前规范实现；SSE 仅用于兼容旧 Server，不应作为新部署首选。
|
||||
|
||||
## 2. 配置、版本与 Secret
|
||||
|
||||
普通配置原子写入 `APP_DATA_DIR/mcp/servers.json`。更新请求必须携带读取到的 `version`；版本过期返回 `409 MCP_SERVER_VERSION_CONFLICT`，避免多个页面互相覆盖。改变 Transport、命令、URL、Header、环境变量或权限后，旧授权和测试结果立即失效。
|
||||
|
||||
`backend/data/mcp/` 是本机运行数据，包含连接配置、授权状态和第三方进程工作目录，不属于团队共享配置。`.gitignore` 忽略整个目录以及 `server.json`、`servers.json` 文件名；不得强制添加到 Git。提交前检查暂存文件清单，不要将本地密钥、连接配置或运行数据推送到远程。
|
||||
|
||||
Secret 使用带类型和键名哈希的 `mcp.*` 内部 ID 写入 Fernet 凭据存储。查询 API 只返回环境变量或 Header 是否配置，不返回明文。删除 Server 或移除 Secret 键会同步清理密文。前端密码框提交后立即清空；用户主动粘贴到 JSON 的密钥仅在当前编辑会话中暂存，解析后从 JSON 中移除，不写入 localStorage、普通配置或日志。
|
||||
|
||||
环境变量的凭据 ID 使用区分大小写的 v2 名称规则，Header ID 保持大小写不敏感。更新配置按凭据 ID 的差集删除密文，因此 `Authorization` 改为 `authorization` 不会丢失认证信息。启动时对无歧义的旧环境变量凭据原子迁移密文，不覆盖新 ID 已有的值；若旧配置把 `TOKEN`、`token` 合并存到了同一个 ID，无法推断原来的两个值，会保留旧密文、停用连接并要求重新录入和测试。删除服务器时也会清理这些保留的旧密文。
|
||||
|
||||
### 2.1 JSON 导入与 API Key 填写
|
||||
|
||||
前端支持 NotesAgent 完整/精简配置、单个 `command / args / env` 配置，以及只含一个服务器的 `mcpServers` 包装。JSON 与表单之间切换会补齐数组、对象及超时默认值，并校验字段类型。批量导入暂不支持；后端配置接口仍只接收 NotesAgent DTO，兼容转换发生在前端。
|
||||
|
||||
可以先声明 `secret_environment_keys`，保存后在服务器卡片的密码框填写密钥；也可以把密钥放进 JSON 的 `environment` 或通用配置的 `env`。前端会将已声明的敏感变量，以及名称含 API Key、Token、Secret、Password、Authorization、Cookie、Credential 的常见字段拆出：普通配置请求只包含键名，密钥另经 Secret API 加密保存。其他敏感字段必须显式声明，不能只依赖名称识别；命令与参数中不要携带密钥。
|
||||
|
||||
例如 MiniMax 的输入结构如下，占位值需在自己的本地页面替换，不要把真实密钥贴进聊天或提交到 Git：
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "MiniMax Coding Plan",
|
||||
"command": "uvx",
|
||||
"args": ["--index-url", "https://pypi.tuna.tsinghua.edu.cn/simple", "--with", "mcp<2", "minimax-coding-plan-mcp", "-y"],
|
||||
"environment": {
|
||||
"MINIMAX_API_HOST": "https://api.minimaxi.com",
|
||||
"MINIMAX_API_KEY": "<在本地填入新密钥>"
|
||||
},
|
||||
"secret_environment_keys": ["MINIMAX_API_KEY"],
|
||||
"startup_timeout_seconds": 120,
|
||||
"tool_timeout_seconds": 300
|
||||
}
|
||||
```
|
||||
|
||||
旧版前端将 `environment.MINIMAX_API_KEY` 与 `secret_environment_keys` 原样一起发送，触发后端“普通与敏感变量不可同名”的校验。这是配置保存失败，不是模型服务返回的鉴权失败。现在在前端拆分两类请求，后端仍保留互斥校验。
|
||||
|
||||
导入兼容规则：`env` 转为 `environment`；`timeout` 作为启动超时；`sse_read_timeout` 作为工具等待上限，不保留其原客户端 SSE 读取超时语义。启动超时范围为 1–120 秒，工具超时为 1–300 秒。URL 必须是纯地址，不能使用 Markdown 链接，JSON 中不能包含 `\_` 这样的非法转义。
|
||||
|
||||
另一个已修复的失败原因是运行时适配层复用了 `PluginBackend` 的整数超时与 60 秒启动上限，导致合法的 120 秒或小数超时配置在保存返回、读取或测试时失败。独立 Server 现在使用专门的 Bridge 适配模型，保留自己的浮点超时范围，不改变 Plugin 清单原有约束。已有的 120 秒记录可直接读取，无需删库重建。
|
||||
|
||||
配置保存成功但后续 Secret 写入失败时，窗口保留服务器 ID、新版本和未写入的密钥。点击保存会更新同一服务器并重试，不重复创建记录；取消会清除未保存密钥，已经保存的服务器和凭据不会回滚。错误信息显示在配置窗口内。保存配置不会自动运行第三方进程，仍需确认、测试和启用。
|
||||
|
||||
暂存的 Header Secret 与已保存凭据使用一致的大小写规则：将 `Authorization` 改为 `authorization` 不会丢弃尚未保存的值，提交时采用当前声明名。重新输入同一 Header 的值会覆盖旧草稿；真正删除声明才清除草稿。环境变量仍区分大小写，不会把 `TOKEN` 的草稿转交给 `token`。
|
||||
|
||||
跨 Registry 与凭据存储的删除以“失败后可重试”为顺序约束：先原子清理密文，再提交新版本或删除 Registry 记录。凭据存储失败时保留原版本和 Server 记录，避免出现返回 500 但配置已提交、版本无法重试或密文失去清理入口的状态。
|
||||
|
||||
写入或删除 Secret 会先停用正在运行的连接、注销动态 Tool，并撤销当前配置的测试通过状态；必须使用新凭据重新测试后才能启用。这样页面展示的凭据状态不会与运行中进程实际持有的旧凭据不一致。
|
||||
|
||||
## 3. 启用与运行时规则
|
||||
|
||||
一次连接按以下顺序执行：
|
||||
|
||||
1. 用户检查服务端生成的连接摘要并确认当前摘要；
|
||||
2. 后端临时连接，完成 initialize 和 `tools/list` 后关闭连接；
|
||||
3. 只有当前摘要测试成功，启用操作才会启动长期连接并注册 Tool；
|
||||
4. 停用、删除、超时或异常退出会注销 Tool 并关闭连接。
|
||||
|
||||
运行期连接异常或 Tool 列表变化时，Registry 会在同一生命周期临界区内标记不可用、注销 Tool，并从 Bridge 移除 Host。每次启动分配独立的连接代次；失败回调取得锁后先核对代次，旧连接延迟到达的回调不能停用新连接。停用、测试结束及关闭服务时撤销对应代次。
|
||||
|
||||
所有独立 MCP API 都通过工作线程执行，包括新增、确认授权和读取接口。虽然部分操作不直接访问网络，但仍可能等待正在测试或启动的连接持有的锁，不能在 FastAPI 事件循环上同步等待。
|
||||
|
||||
HTTP Header 中 `Host`、`Content-Type`、`MCP-Session-Id` 等协议保留项不可由配置覆盖。URL 不允许内嵌凭据或 Fragment。旧 SSE 返回的 POST endpoint 必须与初始 URL 同源，防止认证 Header 被转发到其他站点。
|
||||
|
||||
启动与 Tool 请求超时会同时应用于业务等待和底层 HTTP 请求；旧 SSE 的 endpoint 等待也使用启动超时。非主动结束的旧 SSE 事件流视为 Host 不可用，宿主随后注销 Tool。注册表加载时逐条校验 Server ID、配置字段、Transport 组合和摘要格式，损坏记录统一返回 `MCP_REGISTRY_INVALID`。
|
||||
|
||||
两种 HTTP Transport 共用有界 SSE 行解析器：按响应字节块检查未完成行及当前事件的累计大小，再扩展缓冲区，不依赖 `iter_lines()` 先缓存完整行。持续无换行输入也会及时触发上限；解析兼容跨块 UTF-8、首行 BOM、LF/CR/CRLF、多行 data 和事件间计数重置。`tests/test_mcp_sse_limits.py` 覆盖这些边界，防止仅在完整行生成后检查大小。
|
||||
|
||||
stdio 命令不经过 Shell，管道、重定向和命令拼接不会被解释。Windows 使用新进程组并通过 `taskkill /T` 回收子树；POSIX 使用独立 session/process group 并向进程组发信号。Python 阶段仍无法提供文件、网络、系统调用或操作系统版本差异下的绝对隔离保证。
|
||||
|
||||
`uvx` 模板使用 `--isolated`、明确的 `--from` 和固定包版本。它只能隔离依赖，不能替代安全沙箱。非开发环境仍拒绝启动 stdio Server，并返回 `403 MCP_SANDBOX_REQUIRED`；远程 HTTP Transport 不创建本机子进程，但仍要求摘要确认和成功测试。第三阶段前的 C.5 将冻结 Tauri/Rust 沙箱设计。
|
||||
|
||||
## 4. 接口
|
||||
|
||||
```text
|
||||
GET /api/mcp/servers
|
||||
POST /api/mcp/servers
|
||||
GET /api/mcp/servers/{server_id}
|
||||
PUT /api/mcp/servers/{server_id}
|
||||
DELETE /api/mcp/servers/{server_id}
|
||||
GET /api/mcp/servers/{server_id}/tools
|
||||
POST /api/mcp/servers/{server_id}/trust
|
||||
POST /api/mcp/servers/{server_id}/test
|
||||
POST /api/mcp/servers/{server_id}/enable
|
||||
POST /api/mcp/servers/{server_id}/disable
|
||||
PUT /api/mcp/servers/{server_id}/secrets/{key}?kind=environment|header
|
||||
DELETE /api/mcp/servers/{server_id}/secrets/{key}?kind=environment|header
|
||||
```
|
||||
|
||||
完整字段、状态和错误码见《第二阶段接口契约-开发版》。协议实现参考 MCP 官方的 [Transports](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports) 与 [Lifecycle](https://modelcontextprotocol.io/specification/2025-11-25/basic/lifecycle)。
|
||||
|
||||
## 5. 验证
|
||||
|
||||
```powershell
|
||||
cd backend
|
||||
uv run pytest -q tests/test_mcp_registry.py tests/test_extension_core.py
|
||||
|
||||
cd ../frontend
|
||||
npm run type-check
|
||||
npm test
|
||||
npm run build
|
||||
```
|
||||
|
||||
后端测试使用无需网络或真实密钥的 stdio Fixture，以及 `httpx.MockTransport` 驱动的确定性 HTTP/SSE Server Fixture。覆盖摘要授权、Secret 不回显、版本冲突、生产门禁、重启恢复、Streamable HTTP Session/Header/工具调用及旧 SSE 同源校验；新增覆盖旧回调隔离、路由线程卸载、凭据大小写差异与旧密文迁移。前端覆盖模板切换、JSON 默认值与格式兼容、明文拆分、模式切换、部分保存失败重试、取消清理、测试失败和删除确认。此处的 MiniMax 配置转换测试使用假密钥，不等同于真实 MiniMax 网络调用验证。
|
||||
|
||||
## 6. 后续边界
|
||||
|
||||
### 本轮 P1/P2 修复验收
|
||||
|
||||
| 审阅问题 | 修复方式 | 回归验证 |
|
||||
| --- | --- | --- |
|
||||
| P1：新增或授权等待生命周期锁时阻塞事件循环 | 独立 MCP 路由统一交给工作线程 | `test_mcp_lifecycle_lock_contention_keeps_event_loop_responsive`：分别阻塞 create/trust，在锁释放前仍能执行健康检查 |
|
||||
| P2：旧失败回调误停新连接 | 回调在锁内核对连接代次 | `test_old_failure_callback_cannot_stop_replacement_host`：旧回调排队期间重启连接，释放锁后新连接仍可用，当前代次的失败仍正确停用 |
|
||||
| P2：精简 JSON 切换模式或编辑保存报错 | 运行时校验、默认值补全、统一转换 | `configuration.spec.ts` 与 `McpServersView.spec.ts`：精简 JSON、编辑版本、模式切换和 Secret 保存重试 |
|
||||
| P2：Header 大小写改名删除凭据 | 按规范化凭据 ID 而非原始键名计算差集 | `test_header_case_only_rename_preserves_secret` |
|
||||
| P2：大小写不同的环境变量覆盖同一凭据 | 区分大小写的 v2 ID，带迁移标记的旧密文迁移 | `test_environment_secrets_are_case_sensitive_and_delete_independently` 及 legacy migration 测试，包含删除后不复活旧密钥 |
|
||||
| P1：SSE 无换行输入在大小校验前无限缓冲 | 在行拼接前校验字节数与事件累计大小 | `test_mcp_sse_limits.py`，包括小块持续输入和跨块换行 |
|
||||
| P2：Header 大小写改名丢失未保存密钥 | 草稿使用规范化名称匹配，并重新绑定当前声明名 | `configuration.spec.ts` 与页面保存回归测试 |
|
||||
|
||||
这些修复不放宽 stdio 的 JSON-RPC 校验。第三方程序向 stdout 打印普通日志造成的握手失败，应由服务端调整输出或使用不打印日志的启动入口处理。
|
||||
|
||||
### 后续工作
|
||||
|
||||
- 增加真实第三方 Server 的兼容矩阵；确定性 Fixture 只能证明宿主协议行为，不能代表所有实现兼容；
|
||||
- C.5 在第二阶段开发与测试完成后、第三阶段桌面端实现前冻结沙箱 Contract；
|
||||
- 第三阶段将 stdio 进程创建和 Secret 托管迁移至 Tauri/Rust Host 与 Stronghold/系统 Keychain。
|
||||
Reference in New Issue
Block a user