# 计划：QMT Bridge MCP 能力内建（神之一手自注册 MCP，去三方插件依赖）（阶段航点）

> 编号：PLAN-018 ｜ 粒度：阶段航点 ｜ 创建：2026-09-08 ｜ 状态：待实施（拟迭代 18）
> 派生自终极目标：目标-001（DSH 插件形态·复用宿主 MCP 能力）、目标-008（真实交易系统接入）
> 依据需求：**R-020（已定稿，2026-09-08，Q1-Q6 老师拍板）** —— 符合入范围门槛
> 设计约束：技术约束-003（REST 直连不变）、技术约束-008（连接配置存储/热切换）、产品约束-012（会话头部指示灯体系）、UI约束-002（连接卡片）；沿用技术约束-004/005/006/007

## 目标

让神之一手插件自带 QMT Bridge 的 MCP 能力：插件在自己的 apply 内按 QMT 连接配置动态挂载 **DSH 官方 @deepseek-ai/dsh-mcp-client**（url 自动派生自激活连接 baseUrl + /mcp，serverName 固定 QMT_Bridge_MCP，工具以 mcp__QMT_Bridge_MCP__* 注册给模型；挂载/切换/卸载/状态均由神之一手在插件内管理）；连接 CRUD/激活切换与 MCP 实例全生命周期联动；**卸载三方 dsh-skill-mcp-panel 并移除其宿主 cordis.patch.yml 受管块**，不再依赖三方面板加入 MCP 能力。REST 直连架构不变（技术约束-003）。

## 范围

**做**（对应 R-020 定稿边界，决策编号 Q1-Q6）：
1. **依赖与可行性前置（R-020 计划阶段待办 #1，已实证 2026-09-08）**：@deepseek-ai/dsh-mcp-client@0.1.1-rc.2 已加为 one-divine-lot dependencies，从插件 lib 可 import()，模块导出 {name:'mcp-client', inject:['tools'], apply, Config}，可用 ctx.plugin() 动态挂载（实证通过）；
2. **服务端 MCP 管理器（新增 src/mcp/QmtMcpManager.js）**：
   - 唯一 dsh-mcp-client 实例，serverName 固定 `QMT_Bridge_MCP`，url = 激活连接 baseUrl + `/mcp`（自动派生，Q3）；
   - 启动：解析启动连接（默认→上次激活→第一条，空表回退 cordis qmtBaseUrl）后挂载（对齐 R-004 resolveStartupConnection）；
   - 生命周期编排：activate/update（地址变）/remove（激活被删切默认）→ 先卸后挂（对齐 qmt-connections API 现有热切换点，Q1 仅激活连接挂载）；
   - 失败语义（Q5）：failOnStartupError:false + reconnect（对齐宿主现有受管块配置：initial 500ms / max 30s / maxAttempts 10）；
   - 状态缓存：{ state: connected|connecting|disconnected|disabled, serverName, url, toolCount, error, checkedAt }，供状态端点与指示灯读取；
   - 释放：ctx.effect dispose 时卸载实例；
3. **服务端状态出口（api/qmt-connections.js 或 market.js 扩展）**：
   - mcp-status 端点（含 refresh 即时重查）→ 设置页连接卡片 MCP 状态行 + 会话头部指示灯读取；
   - sync-status 增加 mcp 域（Q4：头部指示灯数据源合并一处）；
4. **设置页「QMT 连接配置」卡片 MCP 状态（UI约束-002 形态内扩展）**：卡片显示 MCP 状态（绿=已连接 + N 工具 / 红=失败原因 / 灰=未启用），「检查 MCP」按钮（手动触发，Q4）；
5. **会话头部指示灯新增 MCP 状态灯（产品约束-012 体系扩展）**：SyncIndicators 三灯 → 四灯（QMT连接｜持仓数据｜行情数据｜MCP），MCP 灯三态对齐（绿=已连接 / 黄=重连中 / 红=断开 / 灰=未启用），点击=refresh（Q4）；
6. **移除三方 dsh-skill-mcp-panel（Q2，2026-09-08 老师澄清）**：dsh plugin remove dsh-skill-mcp-panel（连带其「技能 / MCP」设置菜单）；编辑 ~/.dsh/profiles/web/cordis.patch.yml 删除其受管块（QMT_Bridge_MCP 条目，块外内容逐字节保留）——属宿主组成变更，按 editing-cordis-compositions 技能流程执行 + 老师确认；
7. **构建安装与验收**。

**不做**（本期，R-020 边界）：通用 MCP 服务器管理面板（Q6，含自建任意 MCP 管理 UI）；插件 UI/tab 数据源改走 MCP（技术约束-003）；多 serverName 并存；自研 MCP 协议客户端（老师定：官方 dsh-mcp-client 可依赖，不重造）；认证/鉴权增强（QMT Bridge 无鉴权）。

## 程序结构（新增/改动）

```
src/
├── index.js                        # 服务端入口（改）：注入 mcpManager，启动挂载 + 释放卸载；把 mcpManager 传入 registerApi
├── mcp/                            # （新增域目录，技术约束-016 语义：无合适域先讨论，此处讨论定 = 新增 mcp 域）
│   └── QmtMcpManager.js            # MCP 实例管理（官方 dsh-mcp-client 动态挂载：唯一实例 + 生命周期编排 + 状态缓存）
├── settings.js                     # （小改）：暴露当前激活连接解析辅助（已有 getActiveQmtConnection 可复用，必要时补暴露）
├── api/
│   ├── index.js                    # （改）：runtime 增 mcpManager，注册 mcp-status 方法分发
│   ├── qmt-connections.js          # （改）：热切换点（activate/update/remove）联动 mcpManager 重挂；新增 mcp-status 处理
│   └── market.js                   # （改）：sync-status 增加 mcp 域
└── client/views/
    ├── QmtConnectionChip.jsx       # （改）：内置 SyncIndicators 传 mcp 状态读取
    ├── SyncIndicators.jsx          # （改）：三灯 → 四灯（+MCP），轮询 sync-status 读 mcp 域，点击 refresh
    └── SettingsSection.jsx         # （改）：QmtConnectionCard 增 MCP 状态行 + 「检查 MCP」按钮
package.json                        # （改，已完成）：dependencies + @deepseek-ai/dsh-mcp-client@0.1.1-rc.2 + @modelcontextprotocol/sdk@1.30.0
~/.dsh/profiles/web/cordis.patch.yml # （改）：移除 dsh-skill-mcp-panel 受管块（Q2，宿主配置，独立步骤；插件本体 dsh plugin remove）
```

## 实现步骤（建议顺序）

1. **依赖可行性实证**（任务 1 决策门）：声明 peer + 构建后在宿主实测 import 解析；不可解析则停在这里与老师讨论替代通道；
2. **服务端 mcpManager**：QmtMcpManager 骨架 + 启动挂载/卸载 + 状态缓存（先不接 API，日志验证挂载与工具注册）；
3. **热切换联动**：qmt-connections activate/update/remove 编排点追加 mcpManager.resync()（复用现有 dataSource.setBaseUrl 同点）；
4. **状态端点**：mcp-status + sync-status.mcp 域；本地 curl/HTTP 验证；
5. **设置页卡片**：QmtConnectionCard 增 MCP 状态 + 检查按钮（复用测试连接交互模式与 Toast）；
6. **会话头部 MCP 灯**：SyncIndicators 四灯改造；验证与三灯并存样式一致（对齐 IndicatorDot/sep 布局与主题 token）；
7. **宿主受管块移除**：编辑 cordis.patch.yml（editing-cordis-compositions 流程）→ 重载宿主 → 验证 mcp__QMT_Bridge_MCP__* 工具仍可用（这次来自神之一手）；
8. **构建安装验收**：服务端+客户端构建，dsh plugin add / 重载；逐条核对验收标准。

## 验收标准

1. 移除宿主 cordis.patch.yml QMT_Bridge_MCP 受管块后，模型仍能使用 mcp__QMT_Bridge_MCP__qmt_* 工具（来源=神之一手动态挂载实例），工具集与移除前一致（同一 serverName/url）；
2. 激活连接切换 → MCP 实例 url 跟随切换（工具可用目标随激活配置变化，观察工具调用返回目标数据源变化）；
3. 编辑激活连接地址、删除激活连接（自动切默认）→ MCP 实例同步重挂，无残留旧连接工具；
4. 连接列表为空（无激活）→ 不挂 MCP 实例（mcp-status=disabled），插件其它功能不受影响；
5. QMT Bridge 不可达 → MCP 灯=红（断开），插件不崩、其余灯正常；恢复可达后自动重连至绿灯（Q5 语义）；
6. 设置页连接卡片显示 MCP 状态（已连接 + N 工具 / 失败原因 / 未启用），「检查 MCP」可手动触发并刷新；
7. 会话头部出现第四个指示灯「MCP」：绿=已连接 / 黄=重连中 / 红=断开 / 灰=未启用，点击触发即时检查（Q4）；
8. 现有功能（分仓/策略/交易/设置子 tab/三灯）无回归；typecheck + build 通过。

## 验收方法

- 移除受管块前先完成 1-6 步并在旧块存在时验证（同名冲突预期：两实例同 serverName 后加载报错——因此**验证顺序必须先移除受管块再加载新实例**，步骤 7 与 1-6 的顺序需在实施时按 HMR 重载节奏小心编排，见实施时核查点）；
- 用 qmt 工具的 listTools/实际调用观察目标切换；断开 QMT 观察灯态与自动恢复；
- settings 卡片与头部灯截图/人工核验。

> **实施注意（同名冲突时序）**：宿主现有受管块与神之一手新实例同用 serverName QMT_Bridge_MCP，存活实例重复会报错。安全顺序：① 插件侧完整实现并构建 → ② 移除宿主受管块并重载（此窗口工具短暂消失可接受）→ ③ 插件实例接管（工具恢复，来源变为神之一手）。禁止两实例并存重载。

## 关联

- 需求：R-020（已定稿，2026-09-08）｜ 参考：mcp_router 动态挂载实证、dsh-skill-mcp-panel 受管块现状
- 设计约束新增（定稿时补充）：技术约束：「插件内建 MCP 客户端注册规范」（唯一实例 serverName 固定 + 随激活连接 url 派生 + 生命周期联动）；产品约束：「MCP 状态出口（设置卡片 + 会话头部 MCP 灯）」

## 记录

| 日期 | 变更 |
|---|---|
| 2026-09-08 | 依据 R-020 定稿（Q1-Q6）创建 PLAN-018 |