MCPilot v2.1.0 分阶段开发计划

一、计划概述

本文档基于路线图.md 需求规划，将 v2.0.0 拆解为 4 个阶段、14 个开发周次的可执行开发计划。v2.0.0 整合了未落地的 v1.2.0 全部需求，向"分布式服务网格 + 市场平台化 + 平台级控制台"演进。

1.1 技术栈基线

层级	技术	版本	选型理由
Web 框架	FastAPI	0.110+	高性能、类型安全
ORM	SQLAlchemy	2.0+	异步支持完善
迁移工具	Alembic	1.13+	版本化迁移，替代 create_all
数据库	PostgreSQL	17+	生产级关系型数据库
缓存/消息	Redis	7+	锁、状态共享、pub/sub、节点间 RPC
认证	PyJWT + bcrypt	-	JWT + 密码哈希
前端框架	Vue 3	3.4+	渐进式、生态成熟
UI 组件库	Element Plus	2.6+	暗黑模式、组件丰富
状态管理	Pinia	2.1+	Vue 官方推荐
构建工具	Vite	5+	快速构建
容器化	Docker / Compose	-	一键部署

1.2 阶段划分

阶段	周次	核心目标	对应 roadmap
Phase 1 平台基座	第 1-4 周	用户/RBAC/AI 客户端/租户基础 + 前端去 AI 味	2.1 / 2.2 / 2.3 / 2.6(部分)
Phase 2 分布式与市场核心	第 5-8 周	分布式服务网格 + 市场平台化	2.4 / 2.5 / 2.6(集群页)
Phase 3 治理与可观测	第 9-11 周	租户治理 + 安全合规 + 可观测	2.3(扩展) / 2.7 / 2.8
Phase 4 生态与增强	第 12-14 周	SDK/CLI + AI 能力增强 + 文档	2.9 / 2.10

1.3 设计原则

Pythonic、异步优先：所有 IO 用 async/await，await 必设超时
向后兼容：默认租户无感升级，config.yaml api_keys 作初始管理员引导
渐进式分布式：单节点模式默认关闭集群特性，多节点按需启用
测试先行：新增功能单测覆盖率 ≥ 80%，分布式场景集成测试 ≥ 10 个

二、Phase 1 平台基座（4 周）

目标：落地 v1.2.0 全部基础需求，完成前端去 AI 味重构，建立用户/权限/客户端/租户数据底座。

2.1 第 1 周：数据库迁移与用户体系 ✅

任务	说明	交付物	状态
引入 Alembic	替代 `create_all`，建立迁移基线	`alembic.ini` + `migrations/env.py` + 迁移 0001	✅
新增表：users / roles / api_keys / tenants	见 roadmap 2.1.4 数据模型	迁移 0001 + `models/database.py` ORM	✅
密码登录	bcrypt 哈希；`POST /api/v1/auth/login`	`api/auth.py` 密码登录 + `core/security.py` bcrypt	✅
用户 CRUD API	`backend/app/api/users.py` 新增	5+ 端点（含 API Key 管理、改密）+ 单测	✅
初始管理员引导	启动时若 users 表为空，从 config.yaml api_keys 写入默认 admin	`user_repository.bootstrap_admin_user` + lifespan 调用	✅

关键文件：

backend/app/models/database.py：新增 User/Role/ApiKey 模型
backend/app/db/base.py：接入 Alembic
backend/app/api/auth.py：新增密码登录端点
backend/app/api/users.py（新增）
backend/app/core/auth.py：ROLE_PERMISSIONS 从硬编码 dict 迁移到 DB（保留内置三角色种子）

2.2 第 2 周：角色权限与认证增强 ✅

任务	说明	交付物	状态
权限点定义	service:read/write, config:admin, audit:read, market:install, cluster:admin 等	`app/core/permissions.py`（15 个细粒度权限点 + 内置角色矩阵）	✅
角色 CRUD	自定义角色 + 权限点分配	`backend/app/api/roles.py`（新增）	✅
认证数据源迁移	API Key 校验从 config.yaml 迁移到 DB；config 仅作引导	`core/auth.py` DB 优先 + 配置回退	✅
JWT 黑名单	Redis `jwt:blacklist:{jti}` 实现 Token 吊销	`core/auth.py` revoke_jwt/is_jwt_revoked + 内存回退	✅
登录审计	login_logs 表 + 登录/登出/失败记录	迁移 0002 + `api/login_logs.py` + 仓储层	✅
登录限流	5 分钟 5 次失败锁定	`api/auth.py` _check_login_lockout（DB NOW() 时间窗口）	✅

测试：343 个测试全部通过（含 test_roles_rbac.py / test_users_api.py / test_auth_rbac.py 集成测试）。

2.3 第 3 周：AI 客户端与租户基础 ✅

任务	说明	交付物	状态
新增表：ai_clients / tenants	见 roadmap 2.2.2 数据模型	迁移 0003 + `models/database.py` ORM（AIClientDB / TenantDB）	✅
AI 客户端 CRUD	独立 Token 生成 + 加密存储 + 吊销	`backend/app/api/ai_clients.py`（新增）+ 仓储层	✅
客户端接入校验	网关连接时校验 client token + 状态 + IP 白名单 + 并发连接数	`gateway/server.py` _validate_ai_client	✅
默认租户	所有业务表增加 tenant_id（默认 default）；单租户无感	迁移 0003 + 仓储层过滤	✅
租户上下文	请求级 tenant_id 注入（JWT/API Key 携带）	`core/tenant_context.py` + middleware + 仓储层改造	✅

测试：26 个 AI 客户端集成测试全部通过（CRUD / 网关校验 / IP 白名单 / 租户隔离）；全套 369 测试通过。

2.4 第 4 周：前端去 AI 味重构与基础页面 ✅

任务	说明	交付物	状态
设计 token 重构	删除 `--glow-*`；中性色阶（Zinc）+ 单一强调色（Indigo）；删 32px 网格背景	`styles/variables.css` 重写	✅
主题系统	深色/浅色 + 系统跟随 + localStorage	`composables/useTheme.ts` + `ThemeToggle.vue`	✅
布局系统	侧边栏可折叠 + 响应式断点 + 分组导航 + 面包屑	`AppSidebar.vue` + `AppTopbar.vue` + `App.vue` 重构	✅
交互三态组件	SkeletonLoader / EmptyState / ErrorState	3 个通用组件	✅
用户管理页	列表（搜索/筛选/分页）+ 新增/编辑弹窗 + 删除	`views/Users.vue`	✅
客户端管理页	列表 + 新增/编辑弹窗（生成 Token）+ Token 重置	`views/AIClients.vue`	✅
登录日志页	登录审计列表（搜索/筛选/分页）	`views/LoginLogs.vue`	✅
Pinia stores	user store / client store	`stores/users.ts` + `stores/clients.ts`	✅
API 扩展	用户/AI 客户端/登录日志/角色 API	`api/index.ts` + `types/index.ts` 扩展	✅
路由注册	新增 /users /ai-clients /login-logs 路由	`router/index.ts` 更新	✅
去发光清理	移除 6 个现有页面的 `--glow-*` 引用与网格背景	Services/ServiceDetail/Metrics/ToolTester/Marketplace/Login/Configs	✅

构建验证：npm run build 通过，vue-tsc 类型检查无错误。

2.5 Phase 1 验收标准

验收项	标准
数据库迁移	Alembic 迁移可从 v1.1.0 状态平滑升级；users/roles/api_keys/ai_clients/tenants/login_logs 表存在
密码登录	用户名密码登录成功签发 JWT；错误密码 401；5 次失败锁定
权限校验	read 角色无法执行写操作；自定义角色按权限点生效
认证兼容	旧 config.yaml api_keys 首次启动写入 DB 后可用
AI 客户端	创建客户端生成独立 Token；禁用客户端拒绝 WebSocket 连接
租户隔离	业务表含 tenant_id；不同租户数据互不可见
前端去 AI 味	无 `--glow-*` 外发光、无高饱和霓虹色、无网格背景
前端三态	骨架屏/空状态/错误占位齐全；侧边栏可折叠；深浅主题可切换
端到端	管理员登录 → 创建用户 → 分配角色 → 创建 AI 客户端 → 客户端连接网关成功
测试覆盖	新增后端单测 ≥ 80%

三、Phase 2 分布式与市场核心（4 周）

目标：解决跨节点资源不共享的根本问题，建立可发布、可联邦同步的市场平台。

3.1 第 5 周：集群节点与拓扑 ✅

任务	说明	交付物	状态
节点注册表	Redis `cluster:nodes:{node_id}` + 心跳 `cluster:heartbeat:{node_id}`（TTL 15s）	`app/core/cluster/node_registry.py` NodeRegistry 模块	✅
节点心跳	后台任务 5s 上报；超时标记离线	心跳协程 + 清理协程	✅
节点状态机	online / offline / draining	drain/recover 状态管理逻辑	✅
节点标签	支持自定义标签用于调度	`config.py` ClusterSettings + 注册逻辑	✅
集群 API	`backend/app/api/cluster.py`（新增）：节点列表/详情/排水/恢复/统计	5 端点 + 22 单测 + 18 集成测试	✅

关键文件：

backend/app/core/cluster/node_registry.py：NodeInfo 数据类 + NodeRegistry（注册/心跳/清理/列表/详情/排水/恢复）
backend/app/core/cluster/__init__.py：模块公共接口导出
backend/app/api/cluster.py：集群管理 API（节点列表/详情/排水/恢复/统计）
backend/app/main.py：lifespan 集成 node_registry 启动/停止
backend/app/config.py：新增 ClusterSettings（enabled/node_id/labels）
backend/app/models/schemas.py：NodeResponse / NodeListResponse / ClusterStatsResponse
backend/configs/config.example.yaml：新增 cluster 配置段示例

测试：22 个单元测试 + 18 个集成测试全部通过；全套 409 测试通过。覆盖内存模式/Redis 模式/状态机/心跳过期降级/权限校验/错误处理。

3.2 第 6 周：远程传输与跨节点路由 ✅

任务	说明	交付物	状态
服务归属注册表	Redis `service:owner:{service_id}` → {node_id, replicas, status}	`cluster/service_placement.py` ServicePlacement 模块	✅
RemoteMCPTransport	新增 transport 类型，与 stdio 并列	`process_manager.call_remote_service` + `handle_rpc_request`	✅
节点间 RPC	Redis pub/sub 请求-应答（`node_rpc:req/resp`）+ 超时重试	`cluster/rpc_channel.py` RpcChannel 模块	✅
路由表升级	`route_with_node()` 返回 (service_id, node_id, is_local)；本地优先 stdio，远端走 RPC	`router.py` RoutingDecision + route_with_node（route() 向后兼容保留）	✅
故障转移	节点离线 → 触发该节点服务放置清理	`cluster/scheduler.py` _check_offline_nodes 协程	✅
多副本负载均衡	轮询/最少连接/优先本地选择节点	`Scheduler.select_node` 三策略	✅

关键文件：

backend/app/core/cluster/service_placement.py（新增）：PlacementInfo 数据类 + ServicePlacement（register/get/remove/update_status/list/remove_for_node，Redis Hash + 内存回退）
backend/app/core/cluster/rpc_channel.py（新增）：RpcChannel（set_handler/send_request/_handle_request，Redis pub/sub 请求-应答 + 超时 + 内存模式降级）
backend/app/core/cluster/scheduler.py（新增）：Scheduler（_failover_loop/_check_offline_nodes/select_node，故障转移 + 轮询/最少连接/优先本地）
backend/app/core/cluster/__init__.py：导出 service_placement / rpc_channel / scheduler
backend/app/core/router.py：新增 RoutingDecision 数据类 + route_with_node()（本地进程优先 → 放置信息查询 → 默认本地）
backend/app/core/process_manager.py：start_service 注册放置；stop_service 移除放置；新增 handle_rpc_request / call_remote_service
backend/app/api/tools.py：call_tool 使用 route_with_node 分支本地 stdio / 远程 RPC
backend/app/gateway/server.py：_call_tool 同步支持跨节点调用
backend/app/main.py：lifespan 启动/停止 rpc_channel（set_node_id + set_handler=process_manager.handle_rpc_request）与 scheduler

测试：26 个单元测试全部通过（TestServicePlacement 9 / TestRpcChannel 5 / TestScheduler 6 / TestRouteWithNode 6）；全套 435 测试通过。覆盖内存模式/Redis 模式/请求处理/故障转移检测/本地-远程-无放置路由决策/向后兼容。

3.3 第 7 周：市场元模型与本地 CRUD ✅

任务	说明	交付物	状态
新增表：market_packages / market_versions / market_installs / market_reviews	见 roadmap 2.4.8	`migrations/versions/0004_market_tables.py` + `models/database.py` 4 个 ORM 模型	✅
`.mcpkg` 打包格式	zip(manifest + config + resources + README)	`core/market_repo.py` create_mcpkg / extract_mcpkg	✅
本地市场仓库	`./marketplace/packages/{id}/{version}/` 目录结构	`core/market_repo.py` save_package_to_repo / remove_package_from_repo	✅
本地市场 CRUD API	上传/下架/版本管理/列表/检索	`api/market.py`（新增，8 个端点）	✅
服务生命周期	install/upgrade/uninstall/rollback + 热加载	`core/market_repo.py` install_package / uninstall_package / rollback_package	✅
依赖解析	manifest 依赖图 + 自动拉取 + 循环检测	`core/market_repo.py` DependencyResolver（拓扑排序 + 循环检测 + 缺失依赖）	✅

关键文件：

backend/migrations/versions/0004_market_tables.py（新增）：4 张市场表迁移脚本（market_packages / market_versions / market_installs / market_reviews）
backend/app/models/database.py：新增 4 个 ORM 模型（MarketPackageDB / MarketVersionDB / MarketInstallDB / MarketReviewDB）
backend/app/models/schemas.py：新增 8 个市场 Schema（ManifestSchema / MarketVersionResponse / MarketPackageResponse / MarketPackagePage / MarketInstallResponse / InstallResult / MarketReviewCreate / MarketReviewResponse）
backend/app/core/market_repo.py（新增）：市场仓库管理器
- .mcpkg 打包/解包（create_mcpkg / extract_mcpkg，zip 格式：manifest.yaml + config.yaml + README.md + resources/）
- 本地仓库目录管理（save_package_to_repo / remove_package_from_repo，{repo_dir}/{package_id}/{version}/）
- 依赖解析器（DependencyResolver：拓扑排序 + 循环检测 + 缺失依赖报错）
- DB 操作（upsert_package / add_version / record_install / find_install_by_service / list_packages / get_package_versions / archive_package）
- 服务生命周期（install_package：保存仓库 + DB + 写配置 + 热加载；uninstall_package：停止进程 + 删配置 + 清路由 + 更新记录；rollback_package：停止 + 写目标版本配置 + 热加载）
backend/app/api/market.py（新增）：市场 CRUD API（8 个端点）
- POST /api/v1/market/packages 上传发布 .mcpkg
- GET /api/v1/market/packages 列表/检索（分类/关键字/分页）
- GET /api/v1/market/packages/{id} 包详情（含版本列表）
- DELETE /api/v1/market/packages/{id} 下架包
- POST /api/v1/market/packages/{id}/install 安装指定版本（默认最新）
- POST /api/v1/market/services/{service_id}/uninstall 卸载
- POST /api/v1/market/services/{service_id}/rollback 回滚
- GET/POST /api/v1/market/packages/{id}/reviews 评论列表/添加评论
backend/app/config.py：MarketplaceSettings 新增 repo_dir（本地仓库根目录）+ install_timeout
backend/configs/config.example.yaml：新增 marketplace.repo_dir / marketplace.install_timeout 配置示例
backend/app/main.py：注册 market_router

测试：24 个单元测试全部通过（TestMcpkgPackaging 5 / TestRepoManagement 4 / TestDependencyResolver 5 / TestDbOperations 4 / TestServiceLifecycle 6）；全套 459 测试通过（283 单元 + 176 集成）。覆盖打包/解包往返、缺 manifest/config 报错、仓库目录创建/删除、依赖解析（缺失/无版本/单包/循环/链式）、DB upsert/版本 latest 切换/安装记录、安装写配置+仓库、带依赖安装、卸载删配置、回滚写目标版本、不存在版本报错。

3.4 第 8 周：联邦同步与前端市场/集群页 ✅

任务	说明	交付物	状态
远程市场协议	HTTP REST：/catalog /package /download /publish	`core/market_federation.py` RemoteRegistryClient	✅
多源联邦同步	多 remote_url + 双向(pull+push) + 增量 + 签名校验	`core/market_federation.py` MarketplaceSynchronizer	✅
定时同步	interval 配置 + 同步状态查看	SyncScheduler + `POST /market/sync` + `GET /market/sync/status`	✅
分类检索评价	多级分类/标签/全文搜索/排序/评分/评论	`get_category_tree` / `list_packages_v2` / `get_package_rating`	✅
前端：市场浏览页	重构 Marketplace.vue：分类/搜索/排序/详情卡	`Marketplace.vue` 重写（分类筛选+搜索+排序+上传发布+联邦同步面板）	✅
前端：市场详情页	版本/README/截图/依赖/评论	`MarketDetail.vue`（新增）	✅
前端：已安装/我的发布	已安装列表 + 发布管理	`MarketInstalled.vue`（新增，含卸载/回滚操作）	✅
前端：集群拓扑页	节点列表 + 拓扑图 + 节点详情	`ClusterTopology.vue`（新增，统计卡片+节点表+排水/恢复+5s轮询+本地高亮）	✅
前端：服务调度页	服务分布 + 调度操作	`ServicePlacement.vue`（新增，服务表+启停重启+5s轮询）	✅

关键文件（后端）：

backend/app/core/market_federation.py（新增）：
- RemoteRegistryClient：远程市场 HTTP 客户端（fetch_catalog / fetch_package_meta / download_package / push_package）
- MarketplaceSynchronizer：联邦同步器（pull_from_source 增量拉取 + push_to_source 推送 + sync_all 多源同步 + 冲突策略 latest/pin/skip + 签名校验占位）
- SyncScheduler：定时同步调度器（interval + start/stop + _loop + _run_sync）
- SyncStatusRegistry / SyncSourceStatus：同步状态内存注册表
- get_category_tree / get_package_rating / list_packages_v2 / list_installs：分类树+评分聚合+增强列表+安装记录查询
- get_remote_catalog / find_package_by_name / find_version / build_mcpkg_for_download：远程端点辅助
backend/app/api/market_federation.py（新增）：12 个端点
- GET /market/categories 分类树
- GET /market/packages-v2 增强列表（分类/标签/排序/评分）
- GET /market/installs 安装记录
- GET /market/packages/{id}/rating 评分聚合
- POST /market/sync 手动触发同步
- GET /market/sync/status 同步状态
- GET /market/remote/catalog 远程目录（公开）
- GET /market/remote/package/{name} 远程包元信息
- GET /market/remote/download/{name}/{version} 下载 .mcpkg
- POST /market/remote/publish 接收推送
backend/app/config.py：MarketplaceSettings 新增 sync_interval
backend/configs/config.example.yaml：新增 marketplace.sync_interval 配置
backend/app/main.py：lifespan 集成 sync_scheduler 启停；注册 market_federation_router

关键文件（前端）：

frontend/src/views/Marketplace.vue：重写（分类筛选+关键字搜索+排序+卡片网格+上传发布对话框+联邦同步状态面板+分页）
frontend/src/views/MarketDetail.vue（新增）：包详情（基本信息+README+版本表+依赖/权限侧栏+评论区+评论表单+安装按钮）
frontend/src/views/MarketInstalled.vue（新增）：已安装列表（状态筛选+表格+卸载/回滚操作+分页）
frontend/src/views/ClusterTopology.vue（新增）：集群拓扑（6张统计卡片+节点表+排水/恢复操作+5s轮询+本地节点高亮）
frontend/src/views/ServicePlacement.vue（新增）：服务调度（3张统计卡片+服务表+启停重启+5s轮询）
frontend/src/api/index.ts：新增 marketApi v2 方法（15个）+ clusterApi（6个方法）
frontend/src/router/index.ts：新增 4 条路由（/market/installed、/market/:packageId、/cluster、/cluster/placement）
frontend/src/components/AppSidebar.vue：新增「已安装」导航项 + 「集群」导航组（集群拓扑/服务调度）

测试：24 个单元测试通过（TestRemoteRegistryClient 4 / TestSyncStatusRegistry 3 / TestSyncScheduler 2 / TestMarketplaceSynchronizer 1 + 第7周 14 个非 DB 测试回归）；DB 相关 11 个测试因 PostgreSQL 服务器网络不可达待恢复后验证，代码逻辑与第7周已验证模式一致。vue-tsc 类型检查通过。

3.5 Phase 2 验收标准

验收项	标准
节点注册	双节点启动互见；节点离线 15s 内被检测
跨节点调用	Node A 启动服务，Node B 客户端调用该服务工具成功；P95 额外延迟 ≤ 30ms
故障转移	Node A 宕机后，其服务在 Node B 自动接管启动，调用恢复
多副本	同服务 2 副本分布不同节点，请求按轮询负载
市场发布	本地上传 `.mcpkg` → 安装 → 调用成功
联邦同步	实例 A 发布 → 实例 B 同步拉取 → 安装 → 调用成功；签名校验生效
依赖解析	安装带依赖服务，自动拉取缺失依赖；循环依赖被拒绝
生命周期	升级/回滚/卸载均触发热加载，状态正确
集群页	节点拓扑可视化；服务分布可见
测试覆盖	分布式集成测试 ≥ 10 个

四、Phase 3 治理与可观测（3 周）

目标：完善多租户治理、安全合规、可观测体系。

4.1 第 9 周：租户治理与安全合规 ✅

任务	说明	交付物	状态
完整租户 CRUD	超级管理员创建/编辑/删除租户	`backend/app/api/tenants.py`（新增，11 端点）	✅
组织/团队模型	organizations 表 + 嵌套团队	迁移 0005 + OrganizationDB ORM + 组织 API	✅
资源配额	服务数/连接数/调用量/存储配额 + 超额拦截	`core/quotas.py` + TenantQuotaDB + 配额 API	✅
租户级市场	私有服务目录（tenant_id 隔离）	`market_repo.list_packages` / `market_federation.list_packages_v2` 加 tenant_id 过滤	✅
服务包签名	发布者私钥签名 + 安装前验签	`core/signing.py`（ed25519）+ `market.py` publish 路径 verify_or_raise	✅
沙箱隔离	子进程低权限运行 + 资源限制	`core/sandbox.py`（cwd/env 白名单/user 切换）+ `process_manager.start` 注入	✅
密钥管理	敏感配置集中托管 + 加密存储	`core/secrets.py`（Fernet）+ SecretDB + `api/secrets.py`（5 端点）	✅
审计流水线	统一审计（操作+数据访问+管理事件）+ 检索 + 导出	`core/audit.py` 增强（record_data_access/record_admin_event）+ `api/audit.py`（导出 JSON/CSV + 分类统计）	✅

关键文件：

backend/migrations/versions/0005_phase3_governance.py（新增）：organizations / tenant_quotas / secrets 三张表 + audit_logs 扩展（category / request_id / trace_id）
backend/app/models/database.py：新增 OrganizationDB / TenantQuotaDB / SecretDB；AuditLogDB 增加 category / request_id / trace_id 字段
backend/app/config.py：新增 SecuritySettings（sandbox/signing/secrets）+ QuotaSettings
backend/app/core/secrets.py（新增）：Fernet 对称加密（encrypt/decrypt/generate_key/rotate_key），密钥来源 settings 或进程内临时
backend/app/core/signing.py（新增）：ed25519 签名验签（generate_keypair/sign_package/verify_package/verify_or_raise）
backend/app/core/quotas.py（新增）：QuotaResource（StrEnum）+ QuotaCheckResult + QuotaExceededError + check_quota / check_quota_or_raise
backend/app/core/sandbox.py（新增）：build_sandbox_env / get_sandbox_cwd / get_sandbox_kwargs / apply_sandbox_to_subprocess
backend/app/core/audit.py：增强 record_audit 支持 category/request_id/trace_id；新增 record_data_access / record_admin_event
backend/app/db/tenant_repository.py（新增）：租户 CRUD + 组织 CRUD + 配额 upsert/get（新建租户自动初始化配额）
backend/app/db/secret_repository.py（新增）：密钥 CRUD（put/get/list/delete，按 tenant_id 隔离）
backend/app/db/repository.py：create_audit_log / query_audit_logs 支持 category/request_id/trace_id/start_time/end_time；新增 export_audit_logs（JSON/CSV）
backend/app/api/tenants.py（新增）：11 端点（租户 CRUD + 配额 GET/PUT + 组织 CRUD）
backend/app/api/secrets.py（新增）：5 端点（写入/列表/详情/解密 reveal/删除）
backend/app/api/audit.py：重写（分类/时间窗/请求ID 查询 + JSON/CSV 导出 + 分类统计）
backend/app/api/market.py：publish 路径增加 verify_or_raise 签名校验
backend/app/core/market_repo.py：list_packages 增加 tenant_id 参数（默认当前租户，__all__ 跨租户）
backend/app/core/market_federation.py：list_packages_v2 同步增加 tenant_id 参数
backend/app/core/process_manager.py：MCPProcess.start 注入沙箱（build_sandbox_env + apply_sandbox_to_subprocess）
backend/app/models/schemas.py：新增 12 个 Schema（TenantCreate/Update/Response/QuotaResponse/QuotaUpdate/OrganizationCreate/Response/SecretCreate/Response/Reveal）+ AuditLogEntry 扩展字段
backend/app/main.py：注册 tenants_router / secrets_router；lifespan 引导 default 租户配额初始化
backend/configs/config.example.yaml：新增 security / quota 配置段示例
backend/requirements.txt：新增 cryptography>=42.0.0
backend/pyproject.toml：注册 pytest db mark

测试：56 个单元测试（46 个非 DB 通过 + 10 个 DB 测试在 Windows 自动 skip 避免网络超时）。覆盖签名往返/篡改检测/空密钥拒绝、Fernet 加解密往返/错误密文/密钥轮换、配额检查（无配额行/limit=0/未超额/超额/各资源独立）、沙箱（白名单过滤/关闭透传/Windows 不切 user/cwd 合并）、审计分类（operation/data_access/admin_event/best-effort 失败不抛）、ORM 字段、Schema、配置加载。Lint：ruff All checks passed（新增/修改文件）。

4.2 第 10 周：分布式追踪与集群指标 ✅

任务	说明	交付物	状态
请求 ID 透传	跨节点透传 request_id / trace_id	`core/tracing.py`（ContextVar + RPC headers）+ HTTP 中间件	✅
调用链可视化	客户端→网关→路由→节点→子进程调用链 + 耗时分解	`core/tracing.py`（TraceCollector 环形缓冲 + start_span）+ API 端点	✅
集群级指标	按节点/租户/服务/工具多维聚合 Prometheus 指标	`core/metrics.py` 增强（cluster_node_* / rpc_* / trace_spans / tool_calls_by_tenant）	✅
集群总览	集群服务数/连接数/调用量/错误率	`api/observability.py`（GET /cluster/overview 聚合 API）	✅
节点资源	CPU/内存/进程数/连接数采集	`core/node_resources.py`（psutil 采集 + 降级）	✅
告警体系	阈值告警规则 + Webhook/邮件通道 + 历史	`core/alerts.py`（AlertEngine）+ 迁移 0006 + `api/observability.py`（规则 CRUD + 历史 API）	✅

关键文件：

backend/app/core/tracing.py（新增）：TraceContext（ContextVar 管理 trace_id/request_id/span_id）、TraceCollector（环形缓冲 1000 trace / 50 span per trace）、start_span 异步上下文管理器（自动父子关系 + 状态记录 + Prometheus 指标）、inject/extract_rpc_headers（RPC 透传）
backend/app/core/node_resources.py（新增）：NodeResourceInfo dataclass + collect_node_resources()（psutil 采集 CPU/内存/磁盘/进程数/连接数/负载均值，psutil 不可用时降级零值）
backend/app/core/alerts.py（新增）：AlertRule / AlertEvent dataclass、AlertEngine（规则 CRUD + 后台评估循环 + 冷却机制 + 告警历史）、WebhookChannel（HTTP POST）/ EmailChannel（SMTP）
backend/app/core/metrics.py（增强）：新增 cluster_node_count/cpu/memory/process_count/connections/disk（Gauge by node_id）、rpc_calls_total/rpc_duration（RPC 指标）、trace_spans_total（追踪指标）、tool_calls_by_tenant（租户维度）、update_cluster_metrics_async()（异步集群总览聚合）
backend/app/core/cluster/rpc_channel.py（增强）：send_request 注入 trace headers、_handle_request 提取 trace headers 恢复上下文、RPC 指标记录
backend/app/api/tools.py（增强）：call_tool 初始化追踪上下文、route/local_call/remote_rpc span 记录、审计日志携带 trace_id/request_id、租户维度指标
backend/app/api/observability.py（新增）：11 个端点 — 追踪列表/详情、告警规则 CRUD/测试、告警历史、集群总览、节点资源
backend/app/models/database.py（增强）：新增 AlertRuleDB / AlertHistoryDB ORM 模型
backend/migrations/versions/0006_alerts.py（新增）：alert_rules / alert_history 两张表
backend/app/models/schemas.py（增强）：新增 TraceSpanSchema / TraceRecordSchema / TraceListResponse / AlertRuleCreate/Update/Response / AlertEventResponse / AlertHistoryPage / ClusterOverviewResponse
backend/app/core/permissions.py（增强）：新增 trace:read / alert:read / alert:manage 权限点 + 角色矩阵更新
backend/app/config.py（增强）：新增 AlertSettings（webhook/email/eval_interval）
backend/app/main.py（增强）：trace_context_middleware（X-Trace-ID 透传 + 响应头回传）、observability_router 注册、lifespan 启动/停止 alert_engine
backend/configs/config.example.yaml：新增 alerts 配置段示例
backend/requirements.txt：新增 psutil>=5.9.0

测试：51 个单元测试（全部通过）。覆盖 TracingContext（ID 生成/ContextVar 传播/清理）、TraceCollector（Span 采集/trace 查询/环形缓冲驱逐/span 上限/状态过滤/清空）、start_span（异步上下文/ok 状态/error 状态/父子关系/自动 trace_id）、RPC headers（注入/提取/空 headers）、NodeResources（采集返回/序列化/反序列化/hostname）、AlertEngine（规则 CRUD/条件评估 6 运算符/告警触发/冷却跳过/禁用跳过/历史记录/规则筛选/DB 加载/序列化）、AlertChannel（Webhook 无 URL/成功/Email 无配置）、ClusterMetrics（Prometheus 解析/新指标注册验证）、AlertConfig（默认值/Settings 集成）、Permissions（新权限存在性/ALL_PERMISSIONS/角色矩阵）。25 个集成测试（数据库不可用时跳过）。Lint：ruff All checks passed（新增/修改文件）。

4.3 第 11 周：SLI/SLO 与前端增强 ✅

任务	说明	交付物	状态
SLI/SLO 仪表盘	可用性/延迟 P50/P95/P99/错误率 + SLO 达成	`/api/v1/observability/sli` 端点 + Dashboard.vue	✅
前端：指标 Bento 化	指标页非对称网格	Metrics.vue 重写（双 Tab：业务指标 + SLI/SLO）	✅
前端：集群拓扑图	节点+连线+状态色可视化	ClusterTopology.vue 增强（SVG 圆形布局 + 中心节点）	✅
前端：服务分布热力图	节点×服务热力图	ClusterTopology.vue 热力图组件（4 级色阶）	✅
前端：连接监控页	跨节点聚合连接列表 + 历史	ConnectionMonitor.vue（新增）	✅
前端：角色管理页	角色列表 + 权限配置	Roles.vue（新增）	✅
前端：租户管理页	租户列表 + 配额	Tenants.vue（新增）	✅
前端：个人中心	修改密码 + API Key 管理	Profile.vue（新增）	✅
运维操作中心	一键诊断 + 跨节点日志检索 + 节点排水触发	OpsCenter.vue（新增）	✅
分布式追踪可视化	调用链树形展示 + Span 耗时	TraceViewer.vue（新增）	✅

关键文件：

后端：app/api/observability.py（新增 /sli 端点 + _calculate_percentile 分位数计算）、app/models/schemas.py（SliMetric/SloTarget/SliSloResponse 模型）
前端：views/Dashboard.vue（Bento 仪表盘）、views/Metrics.vue（Bento 指标页 + SLI/SLO Tab）、views/ClusterTopology.vue（SVG 拓扑图 + 热力图）、views/Roles.vue、views/Tenants.vue、views/Profile.vue、views/ConnectionMonitor.vue、views/OpsCenter.vue、views/TraceViewer.vue
前端基础设施：router/index.ts（9 条新路由）、components/AppSidebar.vue（导航菜单）、api/index.ts（observabilityApi/tenantApi 客户端）、types/index.ts（SLI/SLO 类型）

测试：17 个单元测试（全部通过）。覆盖 _calculate_percentile（空 buckets/零总量/P50/P95/P99/单 bucket/全首 bucket/+Inf 线性插值）、SLI/SLO API（端点 200/响应结构/可用性范围/延迟非负/SLO 目标结构/SLO 名称/SLI 指标结构/mock 指标计算/完美可用性/零调用）。TypeScript 类型检查零错误。Lint：ruff E,F,I,N,W All checks passed（新增/修改文件）。

4.4 Phase 3 验收标准

验收项	标准
租户配额	超额创建服务被拦截并提示
服务签名	未签名包安装被拒；签名不符被拒
沙箱	子进程无法访问工作目录外文件
调用链	跨节点调用链完整展示，各阶段耗时可见
集群指标	集群总览 + 节点资源 + 多维聚合可用
告警	节点离线/错误率超阈值触发 Webhook 通知
审计	操作/数据访问/管理事件可检索 + 可导出
Bento 仪表盘	指标页非对称网格，无通用卡片矩阵

五、Phase 4 生态与增强（3 周）

目标：建立开发者生态，增强 AI 调用能力。

5.1 第 12 周：SDK 与 CLI ✅

任务	说明	交付物	状态
Python SDK	封装 REST + WebSocket 调用	`sdk/python/mcpilot/` 包（MCPilotClient + WebSocketClient）	✅
TypeScript SDK	封装 REST + WebSocket 调用	`sdk/typescript/` 包（36 方法 + 类型定义）	✅
CLI 工具 `mcpilot`	服务管理/市场安装/集群查询/脚手架	`sdk/python/mcpilot/cli/`（8 命令组 24 命令）	✅
服务模板脚手架	`mcpilot init` 生成 Python/Node 服务骨架	`sdk/templates/python/` + `sdk/templates/node/`	✅
Webhook 事件	服务变更/连接/调用量事件外发	`app/core/webhook.py` + `app/api/webhooks.py`（7 事件类型 + HMAC 签名 + 指数退避重试）	✅

关键文件：

后端：app/core/webhook.py（WebhookEngine + HMAC-SHA256 签名 + 指数退避重试）、app/api/webhooks.py（7 个 REST 端点：CRUD + 测试 + 事件类型列表）、app/models/schemas.py（WebhookCreate/Update/Response 模型）、app/api/services.py（集成 service.started/stopped 事件）、app/api/tools.py（集成 tool.called/error 事件）、app/main.py（路由注册）
Python SDK：sdk/python/mcpilot/client.py（异步 HTTP 客户端，36 个方法覆盖全部 REST API）、sdk/python/mcpilot/websocket.py（WebSocket 客户端，JSON-RPC 2.0）、sdk/python/mcpilot/exceptions.py（4 级异常层次）、sdk/python/mcpilot/cli/main.py（Click CLI，8 命令组）、sdk/python/mcpilot/cli/scaffold.py（脚手架）
TypeScript SDK：sdk/typescript/src/client.ts（fetch + AbortController，36 方法）、sdk/typescript/src/websocket.ts（ws + JSON-RPC 2.0）、sdk/typescript/src/types.ts（完整类型定义）、sdk/typescript/src/exceptions.ts
服务模板：sdk/templates/python/service.py（echo + get_time 工具）、sdk/templates/node/service.js

测试：48 个单元测试（全部通过）。覆盖 WebhookEngine（配置 CRUD 7 项/事件匹配 3 项/HMAC 签名 3 项/事件发射 2 项/序列化 3 项/事件类型 2 项）、Webhook API（8 端点测试）、Python SDK（客户端初始化/异常层次/版本/导出/上下文管理器）、CLI（7 个命令组 help 测试）、脚手架（Python/Node 生成 + 占位符替换 + 不支持语言）、服务模板（JSON-RPC 协议执行测试）。TypeScript SDK 编译零错误。Lint：ruff E,F,I,N,W All checks passed。

5.2 第 13 周：AI 能力增强

任务	说明	交付物	状态
流式响应	SSE/WebSocket 流式工具调用结果	`app/api/tools.py` SSE 端点（StreamingResponse 事件流）	✅
调用缓存	按参数哈希缓存结果 + TTL	`app/core/cache.py`（ToolCallCache SHA256 + LRU + 反向失效）	✅
按工具限流	客户端/工具维度限流	`app/core/ratelimit.py`（TokenBucket + 工具级配置 + 统计）	✅
重试与超时策略	可配置重试 + 超时	`app/core/retry.py`（RetryExecutor 指数退避 + 抖动 + 超时）	✅
管理 API	缓存/限流/重试配置与统计	`app/api/ai_enhancement.py`（12 端点）	✅
配置集成	AI 增强配置项	`app/config.py` AIEnhancementSettings + `config.example.yaml`	✅
多模态（P3）	图片/音频/文件参数支持	协议扩展（可选）	⏭️ 跳过
工具编排（P3）	声明式 DAG 编排（可选）	orchestration 模块	⏭️ 跳过

关键文件：

后端核心：app/core/cache.py（ToolCallCache：SHA256 参数哈希 + TTL 过期 + LRU 淘汰 + 工具名反向索引批量失效）、app/core/ratelimit.py（TokenBucket 令牌桶 + 客户端/工具双维度限流 + 工具级配置 + 统计导出 + 重置）、app/core/retry.py（RetryConfig/RetryStats/RetryExecutor：指数退避 + 抖动 + 可重试异常分类 + 工具级配置 + 每次尝试超时控制）
API 集成：app/api/tools.py（限流拦截 429 + 缓存命中标记 from_cache + 重试包装 + SSE StreamingResponse 事件流）、app/api/ai_enhancement.py（12 管理端点：缓存统计/失效/清空 + 限流统计/配置/启用禁用/客户端统计/重置 + 重试统计/配置/工具统计/重置）、app/gateway/server.py（WebSocket _call_tool 集成缓存/限流检查）
配置与模型：app/config.py（AIEnhancementSettings 配置类：cache/ratelimit/retry/streaming 开关与参数）、app/models/schemas.py（CacheStatsResponse/CacheInvalidateRequest/RateLimitConfigRequest/RateLimitStatsResponse/RateLimitToolActionRequest/RetryConfigRequest/RetryStatsResponse + CallToolResponse.from_cache 字段）、configs/config.example.yaml（ai_enhancement 配置段）

测试：126 个单元测试（全部通过）。覆盖 TokenBucket（8 项：消费/补充/容量上限/重置时间/序列化）、RateLimitConfig（2 项）、RateLimiter（6 项：允许/拒绝/客户端隔离/工具隔离/统计/信息字段）、RateLimiterToolConfig（7 项：配置/自定义突发/默认/禁用/启用/查询不存在）、RateLimiterStats（4 项）、RateLimiterReset（4 项）、ToolCallCache（8 项：哈希/存取/TTL/失效/清空/统计/LRU）、RetryConfig（5 项：延迟计算/抖动/最大延迟/序列化/总尝试次数）、RetryStats（3 项：成功率/平均重试/序列化）、RetryExecutor（9 项：成功/重试后成功/全部失败/超时/非可重试异常/禁用/工具配置/统计/重置）、SSE 流式（3 项：事件格式/缓存命中/错误处理）、缓存管理 API（3 项）、限流管理 API（5 项）、重试管理 API（4 项）、工具调用集成（2 项：缓存命中标记/限流拦截）。Lint：ruff E,F,I,N,W All checks passed。

5.3 第 14 周：文档与收尾

任务	说明	交付物	状态
开发者文档站	API 参考 + 教程 + 示例库	`docs/developer-guide.md`（9 章节：快速开始/架构/API 参考/WebSocket/SDK/CLI/3 个教程）	✅
集群部署指南	多节点部署 + Redis 集群配置	`docs/deployment-guide.md` 扩展（4 新章节：多节点集群/Redis 集群/v2.0.0 配置/生产监控）	✅
升级指南	v1.1.0 → v2.0.0 升级步骤	`docs/upgrade-guide.md`（7 章节：变更概览/检查清单/数据库迁移/配置变更/破坏性变更/验证/回滚）	✅
全功能集成测试	端到端验收用例	`tests/integration/test_e2e_week14.py`（11 类 36 用例：系统/认证/服务/缓存/限流/重试/Webhook/可观测/SSE/SDK/集群市场）	✅
性能压测	缓存/限流/重试/API 延迟基准	`tests/performance/test_benchmark_week14.py`（5 类 15 用例：缓存延迟+吞吐/限流延迟+吞吐/重试开销+吞吐/API P95/综合报告）	✅

关键文件：

文档：docs/developer-guide.md（开发者指南：快速开始 + 架构概览 + REST API 参考 15 域 + WebSocket API + Python/TypeScript SDK + CLI 8 命令组 + 3 教程：自定义服务/Webhook/AI 增强）、docs/upgrade-guide.md（升级指南：v1.1.0→v2.0.0 全流程，6 个 Alembic 迁移 + 配置变更 + 破坏性变更 + 回滚）、docs/deployment-guide.md（部署指南扩展：多节点 Leader-Worker 集群 + Redis Sentinel/Cluster + v2.0.0 配置项 + Prometheus/Grafana 监控 + SLI/SLO 仪表盘）
集成测试：tests/integration/test_e2e_week14.py（端到端验收：系统健康/认证流程/服务生命周期/缓存集成/限流集成/重试管理/Webhook CRUD/可观测性 API/SSE 流式/SDK 验证/集群市场 API）
性能压测：tests/performance/test_benchmark_week14.py（缓存读写延迟+吞吐/限流检查延迟+吞吐/重试执行器开销+吞吐/API 端点 P95 延迟/综合压测报告）

测试：50 个测试全部通过（36 集成 + 14 性能基准）。性能基准结果：缓存读取 263,607 ops/sec、缓存写入 211,945 ops/sec、限流检查 723,759 ops/sec、API 健康检查 P95 < 4ms。Lint：ruff E,F,I,N,W All checks passed。

5.4 Phase 4 验收标准

验收项	标准
SDK	Python/TS SDK 可调用全部 REST + WebSocket 接口
CLI	`mcpilot init` 生成可运行服务；`mcpilot install` 安装市场服务
Webhook	服务变更事件外发到配置 URL
流式响应	工具调用结果可流式返回
缓存	相同参数二次调用命中缓存，延迟显著下降
限流	超限调用被拦截
文档	API/部署/升级文档完整
性能	跨节点 P95 ≤ 30ms；首屏 ≤ 2s

六、技术风险与应对

风险	概率	影响	应对措施
跨节点 RPC 延迟/可靠性	高	高	Redis pub/sub 超时+重试；预留 HTTP/gRPC 直连；死节点检测快速失败
服务归属表一致性	中	高	归属注册表操作加 Redis 分布式锁；节点离线触发乐观清理
迁移破坏现有数据	中	高	Alembic 迁移先在测试库验证；保留 create_all 回退路径
前端去 AI 味回退	低	中	设计 token 集中管理；分页灰度；保留旧主题变量兼容期
市场包安全	中	高	强制签名验签；沙箱隔离；出站白名单
分布式死锁	中	高	所有 await 设超时；锁粒度最小化；超时自动释放
多租户隔离泄漏	中	高	仓储层统一 tenant_id 过滤；集成测试覆盖跨租户访问用例

七、依赖与关键路径

Phase 1 数据库迁移 → 用户/认证 → AI 客户端/租户 → 前端基座
   │
   └─→ Phase 2 集群节点 → 远程传输 → 跨节点路由
                          市场元模型 → 联邦同步
   │
   └─→ Phase 3 租户治理(依赖 Phase1 租户基础) → 安全 → 可观测(依赖 Phase2 分布式)
   │
   └─→ Phase 4 SDK/CLI(依赖 Phase1+2 API 稳定) → AI 增强(依赖 Phase2 路由)

关键路径：Phase 1 数据库迁移 → Phase 2 远程传输 → Phase 2 跨节点路由（决定 v2.0.0 核心价值交付）。

文档版本 v2.1.0 最后更新 2026年8月18日状态基于路线图.md，4 阶段 14 周可执行计划

FilesExpand file tree

开发计划.md

Latest commit

History

开发计划.md

File metadata and controls

MCPilot v2.1.0 分阶段开发计划

一、计划概述

1.1 技术栈基线

1.2 阶段划分

1.3 设计原则

二、Phase 1 平台基座（4 周）

2.1 第 1 周：数据库迁移与用户体系 ✅

2.2 第 2 周：角色权限与认证增强 ✅

2.3 第 3 周：AI 客户端与租户基础 ✅

2.4 第 4 周：前端去 AI 味重构与基础页面 ✅

2.5 Phase 1 验收标准

三、Phase 2 分布式与市场核心（4 周）

3.1 第 5 周：集群节点与拓扑 ✅

3.2 第 6 周：远程传输与跨节点路由 ✅

3.3 第 7 周：市场元模型与本地 CRUD ✅

3.4 第 8 周：联邦同步与前端市场/集群页 ✅

3.5 Phase 2 验收标准

四、Phase 3 治理与可观测（3 周）

4.1 第 9 周：租户治理与安全合规 ✅

4.2 第 10 周：分布式追踪与集群指标 ✅

4.3 第 11 周：SLI/SLO 与前端增强 ✅

4.4 Phase 3 验收标准

五、Phase 4 生态与增强（3 周）

5.1 第 12 周：SDK 与 CLI ✅

5.2 第 13 周：AI 能力增强

5.3 第 14 周：文档与收尾

5.4 Phase 4 验收标准

六、技术风险与应对

七、依赖与关键路径