feat(mcp): P0 只读 MCP tool runtime + opsxdb-mcp stdio

- aitools 共用 runtime：list/describe/schema/query/redis（纯只读，无写确认） - 白名单 ~/.opsxdb/mcp.json；审计 mcp-audit.jsonl；复用 danger.go - 桌面 connections 双写 ~/.opsxdb/connections.json（ox1. 解码） - Cursor 配置示例与任务书验收勾选更新；写操作与 Agent UI 留 P1
2026-10-15 11:14:08 +08:00
1 parent 5c17d32647
commit 0b68c8344d
@@ -0,0 +1,193 @@
+# OpsxDB AI / MCP / Agent 任务书
+
+> 更新：2026-10-15 · 用户拍板：**先 MCP，再内部会话，最后 GUI 联动**  
+> 对标：优先 [DBX MCP](https://github.com/t8y2/dbx)（`packages/mcp-server` / `crates/dbx-mcp`）；架构思路参考 oh-my-pi；可选对照 Google MCP Toolbox for Databases、DBHub、官方 MCP SDK。
+
+## 产品结论（已采纳用户补充）
+
+### 2026-10-15 产品 / PM / 设计确认（锁定）
+
+| 项 | 决议 |
+|----|------|
+| 顺序 | MCP-first → 内部会话共用 Tools → GUI 插入/回写 |
+| 首版引擎 | **仅** MySQL 族 + PostgreSQL + Redis；其它库不进 P0 |
+| 写操作 | **P0 纯只读**；「确认后才可写」复用现有 dangerConfirm，进 **P1**，MCP 首版不可写 |
+| 代码边界 | 只动根级 `src` + `server`；禁止 `packages/ui`（死树） |
+| Redis | 对齐现有精确 TYPE / 集群 SCAN，不另起搜键 |
+| UI | P0 无新重界面；Ask\|Agent Seg / 步骤时间线 / MCP 状态点属阶段 2–4（见文末设计备忘） |
+| 冲突 | 与未推「补偿包」冲突先停报，勿 silently 覆盖 |
+
+| 问题 | 结论 |
+|------|------|
+| 能不能用 AI 做 MySQL/Redis 等操作？ | 能。底座 `/api/db/*` + danger 已有，缺的是工具层。 |
+| 借鉴谁？ | **优先 DBX**（MCP 工具粒度、只读/可写、连接 scope、审计）。oh-my-pi 借工具调用/会话规范，不当成 DB 产品抄。 |
+| 要不要先做 MCP？ | **要，优先做 MCP**。内部 AI 会话与 Cursor/Claude/Codex/omp **共用同一套 Tools**，避免两套逻辑。 |
+| 形态 | GUI 管连接与会话；MCP 暴露安全的数据操作；Gin 仍是官网/docs，**不是**远程协作后端。 |
+
+
+## P0 / P1 边界（2026-10-15 收紧）
+
+| 阶段 | 范围 |
+|------|------|
+| **P0（本轮）** | **纯只读**。`execute_query` 只允许 SELECT/SHOW/EXPLAIN/DESCRIBE/PRAGMA/WITH…SELECT；任何写/DDL **一律拒绝**（**不做** write mode / confirm token）。Redis 仅白名单读命令（GET/SCAN/TYPE/TTL…）；FLUSH*/KEYS/写命令拒。MCP stdio + tool runtime + 连接落盘 + 审计。 |
+| **P1** | 可写 + 确认令牌/策略；内部 Ask \| Agent UI（设计阶段 2，**先只记文档不实现**）；GUI 联动（插入编辑器 / 结果网格）；设置页 MCP 白名单 UI。 |
+
+设计阶段 2（内部会话 Ask \| Agent）：Agent 调同一 `aitools` runtime；Ask 保持现有生成/解释/优化。**本轮不实现 UI。**
+
+## 落地顺序（锁定）
+
+1. **核心 MCP Tools（最小集）** + 连接落盘可读  
+2. **安全策略**：默认只读、危险 SQL 拦截、连接白名单、审计日志  
+3. **内部 AI 会话**：Ask \| Agent；Agent 调同一工具层（进程内调用，不必绕 stdio）  
+4. **GUI 联动**：SQL 一键插入编辑器；结果可回写网格 / 展示
+
+## P0 工具契约
+
+| Tool | 说明 | 安全默认 |
+|------|------|----------|
+| `opsxdb_list_connections` | 列出可见连接（id/name/driver/host，无密码） | 受白名单过滤 |
+| `opsxdb_list_databases` | 列库 | 连接须在白名单 |
+| `opsxdb_list_tables` | 列表/视图（及引擎等价物） | 只读 |
+| `opsxdb_describe_table` | 字段与表元数据 | 只读 |
+| `opsxdb_get_schema_context` | 紧凑 schema 文本，供模型上下文 | 截断上限（与现 AI schema cap 对齐，约 4k） |
+| `opsxdb_execute_query` | 执行 SQL；最多 N 行（建议 100） | **P0 纯只读**（非读语句直接拒绝）；可写+确认 = P1 |
+| `opsxdb_execute_redis_command` | 执行一条 Redis 命令 | **P0 仅读命令白名单**；FLUSH*/KEYS/写一律拒；P1 再开确认写 |
+
+首版引擎验收：**MySQL 族 + PostgreSQL + Redis（单机）**；其余引擎有连接即可试，不阻塞发版。
+
+## 安全策略（MCP 层统一）
+
+- **P0 强制只读**：`execute_query` 非读类 SQL 一律拒绝；`mcp.json` 的 `mode=read_write` 本轮不生效（P1 才启用写+确认）  
+- 复用 `server/internal/db/danger.go` 的危险词表；无 WHERE 的 DELETE/UPDATE 拦截  
+- **连接白名单**（配置文件 `~/.opsxdb/mcp.json`：`allowed_connection_ids`；空=拒绝全部或仅显式 allow——首版建议「空=拒绝」，避免默认放开）  
+- **行数 / 字节上限**；超时；取消  
+- **审计**：`~/.opsxdb/logs/mcp-audit.jsonl`（时间、tool、connection_id、只读/写、摘要、错误；不含密码/全文大结果）  
+- 不暴露：增删连接、原始密码、远程 HTTP 无 token 的开放端口（stdio 默认；本机 HTTP 可选且必须 bearer）
+
+## 连接存储（MCP 可读）
+
+现状：连接在桌面 `localStorage`（`opsxdb.connections.v1`），独立 MCP 进程读不到。
+
+**本轮必做：** GUI `saveConnections` 同步写 `~/.opsxdb/connections.json`（脱敏字段完整、密码仍按现有混淆策略；MCP 与桌面同钥/同解码逻辑，或 MCP 仅经本机已打开的 session——优先**文件同步 + 现有 secrets 解码**，与 DBX「读桌面连接库」同构）。
+
+## 内部会话与 MCP 的关系
+
+```
+┌─────────────┐     ┌──────────────────┐     ┌─────────────┐
+│ Cursor/omp  │───▶│  opsxdb-mcp      │───▶│ tool runtime │
+└─────────────┘     │  (stdio/HTTP)    │     │ (db.* API)  │
+                    └──────────────────┘     └──────┬──────┘
+┌─────────────┐     ┌──────────────────┐            │
+│ 侧栏 Agent  │───▶│  同一 tool runtime │◀───────────┘
+└─────────────┘     └──────────────────┘
+```
+
+侧栏 **不要**再直接拼 prompt 假装执行；Agent 模式只通过 tool runtime。Ask 模式保持现有生成/解释/优化（可不调执行工具）。
+
+## GUI 联动（第 4 步，可薄）
+
+- 工具结果中的 SQL →「插入当前编辑器」  
+- `execute_query` 结果 → 可选「在结果网格打开」（限行）  
+- 设置页：MCP 开关说明、白名单、只读/可写、复制 Cursor `mcp.json` 片段  
+
+## 刻意首版不做
+
+- MCP 增删连接、Kafka/MQ、桌面 `open_table` 远程遥控（可后置）  
+- 把 Gin `:8788` 做成公网 Agent 后端  
+- 两套危险策略（GUI 一套、MCP 一套）
+
+## 验收清单
+
+- [x] `opsxdb-mcp` stdio：`tools/list` 含上表工具（二进制 + 单测注册表）  
+- [x] 白名单外连接调用失败且有明确错误（空白名单=拒绝全部）  
+- [x] 只读模式下 `DELETE`/`DROP`/写 SQL 被拒；审计写 `mcp-audit.jsonl`  
+- [x] 通路代码就绪；单测用 sqlite 覆盖 list/describe/exec；MySQL/PG 真库待桌面验收  
+- [x] Redis 读白名单 + FLUSH*/KEYS/写拒（单测）；真库待验  
+- [ ] 侧栏 Agent 调同一 runtime（**P1 / 设计阶段 2，本轮不做 UI**）  
+- [x] 文档：`docs/mcp-cursor.example.json` + 本文件  
+
+## 参考路径（本机）
+
+- DBX：`/Users/logan/devops/demo/db-gui/dbx/packages/mcp-server`、`crates/dbx-mcp`  
+- oh-my-pi：`/Users/logan/devops/demo/ai-agent/oh-my-pi/docs/mcp-*.md`、`docs/custom-tools.md`  
+- OpsxDB 现有：`server/internal/db/*`、`server/internal/ai/*`、`src/AiPanel.tsx`、`docs/DATABASE-OPERATIONS-AUDIT.md`
+
+
+## P0 验收方式（命令行优先）
+
+> 产品边界：P0 是 **MCP 工具层**，不是 Web 工作台。验收不走浏览器 `:5174`/官网；Web 只看文档。DeepSeek 侧栏 **Ask 写 SQL** 已可测生成；**Agent 调工具查真库**属阶段 2。
+
+### 环境（本机已有）
+
+| 库 | 端口 | 账号 | 说明 |
+|----|------|------|------|
+| MySQL 8.4 (`opsxdb-mysql`) | 3306 | root 或 opsx / `Demo@123`，库 `demo` | `tests/dbctl.sh up a` |
+| Redis 7 (`opsxdb-redis`) | 6379 | 无密码 | `tests/dbctl.sh up f` |
+
+### A. 单测（无真库也可）
+
+```bash
+cd /Users/logan/devops/opsxdb/server
+go test ./internal/aitools/ -count=1
+```
+
+覆盖：白名单拒绝、只读挡 DROP/DELETE、Redis 危险命令拒绝。
+
+### B. 真库 MCP（推荐主路径）
+
+1. GUI 里保存 MySQL / Redis 连接一次（会双写 `~/.opsxdb/connections.json`），记下 `id`。  
+2. 写白名单：
+
+```bash
+mkdir -p ~/.opsxdb/logs
+cat > ~/.opsxdb/mcp.json <<'EOF'
+{
+  "mode": "read_only",
+  "allowed_connection_ids": ["<mysql-conn-id>", "<redis-conn-id>"]
+}
+EOF
+```
+
+3. 编译并跑：
+
+```bash
+cd /Users/logan/devops/opsxdb/server
+go build -o ../bin/opsxdb-mcp ./cmd/opsxdb-mcp
+# Cursor：mcp.json 指向该二进制；或用临时脚本对 stdio 发 initialize + tools/list + tools/call
+```
+
+4. 用例清单：
+
+| # | 工具 | 期望 |
+|---|------|------|
+| 1 | list_connections | 只见白名单内连接，无密码字段 |
+| 2 | list_tables（MySQL demo） | 有表名 |
+| 3 | describe_table | 有列 |
+| 4 | get_schema_context | 截断文本 |
+| 5 | execute_query `SELECT … LIMIT 10` | 有行，≤100 |
+| 6 | execute_query `DROP TABLE …` | **拒绝** + 审计 |
+| 7 | execute_redis_command `PING` / `GET` | 成功 |
+| 8 | execute_redis_command `FLUSHDB` | **拒绝** |
+| 9 | 白名单外 connection_id | **拒绝** |
+| 10 | 审计文件 | `~/.opsxdb/logs/mcp-audit.jsonl` 有记录 |
+
+### C. DeepSeek（当前能验什么）
+
+- **现在**：设置里选 DeepSeek → Ask「生成/解释」对当前 Tab SQL（不执行工具）。  
+- **阶段 2**：Agent 模式多轮调同一 MCP tool runtime，再验「让 AI 查 demo 表结构再写 SELECT」。
+
+### D. 验收通过后交付物
+
+在本机 `~/Downloads/` 生成：`AI-Agent接入GUI工具开发实践.md`，供 opsxapi / opsxshell 及其他项目复用（MCP-first、只读默认、连接落盘、Ask|Agent、危险确认）。
+
+
+## 设计备忘（阶段 2–4，P0 不实现）
+
+来源：设计师 2026-10-15。紧凑桌面、深浅主题；不抄 dbx 整屏工具条。
+
+1. **Ask | Agent**：输入框上方同高同宽小分段；Ask/Agent 不同占位；危险写在执行前确认条（结果区顶或气泡内），Ask 不生成执行条；模式跟连接/Tab，切换不丢草稿。
+2. **步骤时间线**：挂在该条 Agent 回复下，可折叠，默认最近 3 步；行内状态点+工具名+一行摘要+耗时；点开才见全文；无独立全高工具面板。
+3. **插入/结果**：气泡底「插入当前查询」+「新开查询」；行列结果才给「在结果区打开」；默认不抢焦点。
+4. **MCP 状态**：设置 → AI/MCP（开关+白名单）；有活跃外部会话时标题旁小点「MCP」，悬停摘要，点开最近调用可断开；无活跃不显示。
+
+落地次序：MCP 开关+白名单 → Ask|Agent Seg → 时间线与插入 → MCP 状态点。
@@ -1,6 +1,6 @@
 # OpsxDB 待开发 / 待验证清单

-> 维护：项目经理 / 全栈 / 测试补记 · 更新：2026-09-21  
+> 维护：项目经理 / 全栈 / 测试补记 · 更新：2026-10-14
 > 已完成能力见各迭代验收；本文只列**未做完 / 待真实例 / P1 后置**，方便排人。

 ## 使用说明
@@ -8,7 +8,7 @@
 - **P0**：影响主路径或已承诺，优先排  
 - **P1**：增强体验，可后置  
 - **环境缺口**：代码/表单已有，缺真实例才能验；有环境再测  
- 改代码后：`./run.sh restart`（改 `apps/server` 必须重编）
+- 改代码后：`./run.sh restart`（改 `server` 必须重编）



@@ -20,7 +20,7 @@
 |----|------|------|
 | `./run.sh web` 只起 Gin 官网/docs | **已做** | 浏览器不当客户端 |
 | `:5174` 不作产品入口 | **已做** | 仅桌面 Vite 源；`web-only` 弃用提示 |
-| `apps/web` / `packages/ui` | **保留** | Tauri `devUrl`/`frontendDist` |
+| `src` / `src-tauri` | **保留** | Tauri `devUrl`/`frontendDist` |
 | README 写清形态 | **已做** | 浏览器=站；操作=桌面 |
 | 验收 | 待测 | `gui` 可用；浏览器无工作台主路径；`:8788` 官网/docs 通 |

@@ -50,7 +50,8 @@
 | 键详情（TTL / 重命名 / Hash 增删改 / JSON） | 已交 2026-09-20 | 对标 ARDM + opsxsql |
 | CLI 与 SQL 共用编辑器（Redis 按行、命令补全、通用 Do） | 已交 2026-09-20 | 不另开 CLI 页；独立 REPL 列为后置 |
 | Sentinel / Cluster **表单 + 后端** | 已交 | — |
-| Cluster 真实例测连 + 键浏览 | **本地 3 主拓扑已实测**（2026-09-21：表单建 Cluster 连接、跨分片扫键 19/19 全量、键值/行操作回归） | Sentinel 仍缺真实例 |
+| Cluster 真实例测连 + 键浏览 | **本地 3 主拓扑已实测**（2026-09-21：表单建 Cluster 连接、跨分片扫键 19/19 全量、键值/行操作回归）；2026-10-15 复验修复后 SET/GET/DEL 跨槽正常（见文末补记） | — |
+| Sentinel 真实例 | **已实测**（2026-10-15：docker 起最小拓扑 master+sentinel，FailoverClient 经 sentinel 解析 master，SET/GET/SCAN 键列表/多 DB 0-15 全通；测后容器已清理） | 多 sentinel/主从切换 failover 场景未测 |
 | Sentinel / Cluster 文档 | 已交 2026-09-20 | `08-redis.md` / `04-connect.md` |
 | 独立 Redis CLI Tab / 监控 / 慢日志 | 后置 | 对标 ARDM CliTab、opsxsql 监控页；非主路径 |

@@ -58,15 +59,52 @@

 ## 3. 右键菜单

-| 项 | 状态 | 待办 |
-|----|------|------|
-| 编辑器自绘（执行选中/当前语句、剪贴板、拦系统菜单） | 已收 | 回归防回退 |
-| 对象树：库 / 表 / Redis 键 P0 | 已收 | — |
-| 结果表自绘菜单 | 未做（仅吞系统菜单） | P1：复制单元格/行、导出入口等 |
-| 美化 SQL / 含引号复制 / 创建片段 / AI 自动填充 | P1 | 编辑器右键增强 |
-| 表：设计结构 / 重命名 / 生成 SQL（CREATE·INSERT）/ 导出 | P1 | — |
-| 库：执行 SQL 文件 / 导出转储 / 新建表 | P1 | — |
-| Navicat 级：同步、比较、权限、BI、逆向… | 后置 | 明确不做除非立项 |
+**2026-10-14 对比优化后状态：主路径已补齐一轮，尚未全部验收。** 设计评分与详细不足见 [GUI 对比报告](GUI-COMPARISON.md)。下表覆盖历史补记中相关「已做」口径；已有工具栏功能不等于已接入右键。标记「已接入」表示代码已落地，仍需在桌面 Tauri 中逐项验收，源码与单测不替代实机及方言验证。
+
+| 编号 | 优先级 / 区域 | 功能 | 当前状态 | 待开发 / 验收要求 |
+|------|---------------|------|----------|-------------------|
+| 1 | P0 编辑器 | 格式化 / 美化 SQL | 已接入右键，与工具栏复用 | 有选区仅格式化选区，无选区格式化全文；待桌面回归撤销与各方言 |
+| 2 | P0 编辑器 | 执行选中 / 当前语句 | 右键已有，共用执行逻辑 | 回归选区、空白处、语句边界，与工具栏行为一致 |
+| 3 | P0 编辑器 | 注释 / 取消注释 | 已接入 CodeMirror 注释命令 | 覆盖选区与当前行；非 SQL 驱动禁用；待桌面方言回归 |
+| 4 | P0 编辑器 | 复制为纯文本 / 带连接信息 | 已接入，两种复制方式 | 无选区复制全文；连接摘要仅白名单字段，不含用户、密码、SSH 密钥；剪贴板失败不删除选区 |
+| 5 | P0 编辑器 | 查找替换 / 跳转到定义 | 搜索替换已接入；明确表名可跳 DDL | 仅解析已加载元数据中的明确标识符，跳过字符串/注释；别名、CTE、未加载对象和复杂解析仍后置 |
+| 6 | P0–P1 库 / Schema | 新建查询（带当前库） | 已绑定所点库并持久化 | 普通新查询继承连接默认库；旧标签库不随默认库改变，已有单测；PG Schema 独立上下文见第 10 项 |
+| 7 | P0–P1 库 / Schema | 刷新对象 | 已实现 | 回归刷新范围、加载态与失败提示 |
+| 8 | P0–P1 库 / Schema | 复制连接串 / 主机端口 | 连接/库菜单已增加无凭据地址与主机端口 | IPv6 已覆盖；完整 JDBC、Oracle SID、Redis Sentinel/Cluster 多节点 DSN 仍需按驱动完善，当前地址不宣称可直接导入全部客户端 |
+| 9 | P0–P1 库 / Schema | 断开 / 重连 | 部分：连接节点已有，库节点没有 | 补齐库节点入口或明确归属连接入口；验证状态同步与失败反馈 |
+| 10 | P0–P1 库 / Schema | 设为默认库 | 部分：修改保存的连接配置 | 补齐会话语义：MySQL 默认库切换、PG Schema 的 `SET search_path`；验证后续查询与重连，不只显示成功提示 |
+| 11 | P1 表 / 视图 | 打开表数据 / 前 N 行 | 已接入前 N 行输入（1–10000） | 通过请求分页传递行数，不向预览 SQL 固化 LIMIT；已加载结果每批显示 500 行，可继续展开；待真库分页与大结果验证 |
+| 12 | P1 表 / 视图 | 查看表结构 / DDL | 已有，DDL 按驱动能力控制 | 回归表与视图、目标对象及不支持引擎的禁用状态 |
+| 13 | P1 表 / 视图 | 生成 SELECT / INSERT 模板 | 已接入并新开带库查询，避免覆盖草稿 | 视图不提供 INSERT；引用列名与限定名；INSERT 为待填值模板，待真库方言回归 |
+| 14 | P1 表 / 视图 | 导出表 CSV / JSON（可后置） | 部分：表右键已接「转储 SQL 文件」三态（2026-10-14，见文末补记）；CSV/JSON 整表右键直达仍缺 | 复用导出能力，明确整表与当前结果范围，验证格式与失败提示 |
+| 15 | P1 表 / 视图 | 清空表 / 删除表 | 已实现，按能力裁剪并危险确认 | 回归取消不执行、确认后执行及刷新；视图不显示清空表 |
+| 16 | P1 表 / 视图 | 复制表名（带库前缀） | 已增加限定名复制 | MySQL 使用库前缀，PG/MSSQL 使用 Schema；标识符转义已有单测，异常元数据命名仍需真库回归 |
+| 17 | P1 结果集 | 复制单元格 / 行 / 列（TSV） | 已接入单元格、行号、列头和空白菜单 | 基于实际右键目标与当前排序；TSV 不含表头，保留 NULL/JSON 并引用制表符/换行；待桌面剪贴板验收 |
+| 18 | P1 结果集 | 复制为 INSERT / JSON | 已接入当前行 INSERT/JSON 与当前结果 JSON | INSERT 使用结果自身记录的表来源；任意 SQL 无可靠来源则禁用；不猜测全局表名 |
+| 19 | P1 结果集 | 导出当前结果 | 右键已接入 CSV / JSON | 复用当前结果导出；只导出当前已加载结果，不冒充整表；待桌面保存文件验证 |
+
+### 第二轮：数据展示、上下文操作、视觉细节
+
+产品原则：借鉴 DBFlux 的布局与上下文层级，借鉴 DBX 的实用功能和回归；保持操作简单，不堆功能。以下为代码已落地、待桌面视觉/交互验收项目。
+
+| 方向 | 已落实 | 验收重点 / 剩余限制 |
+|---|---|---|
+| 数据展示 | 本地跨列筛选、匹配数、对象路径/列数/耗时；首批 500 行，可继续显示全部已加载行 | 明确本地筛选不查库；已移除固定 2000 行不可继续查看的限制；分批展示不等于虚拟滚动 |
+| 值可读性 | NULL、空字符串、空白文本和布尔值区别展示；数值右对齐；长 JSON/文本详情可复制 | 详情只读；大整数文本排序已有精度回归，数据库原始值不改动 |
+| 右键实用性 | 单元格：详情/复制；列头：列名/复制列/排序/适应列宽；空白：结果复制/导出 | 按目标隐藏无关操作，不堆一屏禁用按钮；Ctrl/Cmd+C、Shift+F10 和方向键待桌面回归 |
+| 视觉层级 | 修复粘性表头被相对定位覆盖；轻量结果工具条、分批加载提示、双击列边界适应内容 | 浅深主题、窄窗、长列名、滚动和数字对齐待实机验收 |
+| 连接右键 | 复用统一菜单：连接/断开、重连、编辑、复制、危险操作分组 | 视口约束、Esc、方向键、外点焦点保持；对象树旧菜单仍需后续统一 |
+| 状态与正确性 | 列宽/排序按结果集保存，切换时阻止旧状态串写；写回/回滚只更新原结果集；来源不明确禁用 INSERT/写回 | 已新增跨结果更新回归；真实数据库失败与切换时序仍待验证 |
+
+下一轮：完成桌面右键任务验收、PG Schema 默认路径与连接池隔离；之后完善整表导出、驱动专属连接串和真正虚拟滚动。断开/重连归属连接节点，第 9 项的库节点入口暂不重复添加。
+
+本轮验证：前端构建与类型检查通过，54 项测试通过，Go 编译通过；覆盖复制/标识符/库上下文、跨结果集更新、筛选、数值排序与长值展示。新增菜单支持上下方向键、Home/End、Enter、Esc、视口约束与焦点归还。桌面操作工具未获准访问 OpsxDB，视觉、剪贴板与真库验收仍待完成；不据此将评分自动上调。
+
+统一验收：选区与空白右键、菜单视口边界、Esc / 外点关闭、禁用项说明、操作后焦点恢复；涉及执行的操作复用现有危险确认与错误反馈。仅在桌面验收，不把 `:5174` 作为浏览器产品入口。
+
+核查入口：`src/Workspace.tsx` / `src/SqlEditor.tsx`（编辑器）、`src/ObjectTree.tsx` / `src/ConnectionSidebar.tsx`（树与连接）、`src/ResultPane.tsx`（结果集）。
+
+其他后置项：创建片段、AI 自动填充、表重命名、UPDATE/DELETE 模板开放、执行 SQL 文件、索引/外键编辑（设计表 v1 与转储/新建表已于 2026-10-14 落地，见文末补记）。同步、比较、权限、BI、逆向等不在本轮范围，需另行立项。

 ---

@@ -85,20 +123,25 @@

 | 项 | 状态 | 待办 |
 |----|------|------|
-| 多结果集 / 执行计划 / 书签 / 查询历史 | 已收 | — |
+| 多结果集 / 书签 / 查询历史 | 已收 | 执行计划按钮及结果页签按用户要求移除；不再列入近期开发 |
 | 查询取消 | 已收 | — |
 | 内联编辑 / 多格粘贴 / 行删 / 撤销本格 | 已收 | — |
 | 虚拟滚动大数据集 | 部分（限显截断） | P1：真虚拟滚动 |
-| 深色/浅色主题切换 | **已做**（2026-09-21 核正：顶栏按钮 + 偏好持久化已有） | — |
+| 深色/浅色/随系统主题 | **已做**（2026-10-14 补「随系统」：设置三段选择 + `prefers-color-scheme` 监听，系统切换即时生效，编辑器高亮跟随生效主题） | 桌面切换系统外观实测 |

 ---

-## 6. AI
+## 6. AI / MCP / Agent
+
+> 任务书：[15-AI-MCP-Agent.md](15-AI-MCP-Agent.md)（2026-10-15：**MCP-first**，内部会话共用工具层）

 | 项 | 状态 | 待办 |
 |----|------|------|
 | 右侧 AI 面板可开关 | 已收 | — |
-| 真模型接入（生成/解释/优化） | stub | 接配置与流式输出 |
+| 真模型接入（生成/解释/优化） | **已接**（2026-10-14：Provider 预设 + 三协议，见 §23 补记） | 桌面接真实云端 key 验收；流式输出后置 |
+| MCP 最小工具集 + 安全策略（**P0 纯只读**） | **本轮落地** | `aitools` + `opsxdb-mcp` stdio；白名单/审计/connections.json 双写；写+确认=P1；验收盯 MySQL/PG/Redis |
+| 内部 Agent 会话（共用 tool runtime） | 未做（P1） | Ask \| Agent UI（设计阶段 2 先只记文档）；多轮 + 步骤展示 |
+| GUI 联动（插入编辑器 / 结果网格） | 未做（P1） | 设置页 MCP 配置片段 |

 ---

@@ -166,8 +209,8 @@
 | B 层协议冒烟 | 已做；**不摘标** | 真 TiDB/Polar/OB/Gauss/Kingbase/TDSQL 实例到位再验 → 再谈 `verified` |
 | Oracle / 达梦 | 环境限 / 未接入 | 2026-09-20 Oracle 容器起了但 ORA-00442；达梦未接入 |
 | Redis Sentinel·Cluster 真拓扑 | 表单+字段校验已绿 | 有拓扑：测连 + 键浏览（扫/看/删） |
-| 结果表自绘菜单 / 右键 P1 | 未开 | 全栈落地后按产品清单验 |
-| 改 `apps/server` 后 | 约定 | 验收前确认 `./run.sh restart`，避免旧二进制误判 |
+| 结果表自绘菜单 / 右键 P1 | 代码已接入，待桌面验收 | 按 §3 核对右键目标、排序后复制、NULL/换行、多结果切换与文件保存 |
+| 改 `server` 后 | 约定 | 验收前确认 `./run.sh restart`，避免旧二进制误判 |

 验收时勿并开多个 `dbctl` 库；结论回写本文件或群对齐即可。

@@ -177,12 +220,12 @@

 | 项 | 状态 | 说明 |
 |----|------|------|
-| SQL 编辑器右键 P0 结构 | 已钉 | 执行选中/当前语句 · 查看数据/DDL · 剪切复制粘贴全选；禁系统菜单 |
+| SQL 编辑器右键 P0 结构 | 2026-10-14 已扩充 | 格式化、注释、搜索替换、定义跳转与连接摘要复制；实际边界见 §3 |
 | 对象树三套 P0 线框 | 已钉 | 库 / 表 / Redis 键；P1 虚线项见群线框与 §3 |
 | Redis Sentinel·Cluster 表单字段 | 已钉 | 同页切部署模式；节点列表 · masterName · 双密码；Cluster 无 DB 索引 |
 | 引擎缺图 fallback | 待验 | 灰底首字母，禁用蓝 `?`；未就绪灰 / 未验收橙+悬停 |
 | 对象树右键 P1 视觉 | 未开 | 生成 SQL ▸ · 导出 ▸ · 设计表 · 新建表 等，全栈开做时补密度 |
-| 结果表自绘菜单 | 未开 | 与全栈 P1 对齐出结构 |
+| 结果表自绘菜单 | 已接入，待视觉验收 | 标题标明列目标、操作分组、方向键导航、视口约束与焦点恢复 |
 | 顶栏文案 | 已收 | 连接 · 新建连接 · 新建查询 · 查询历史 · 快捷键 |

 线框产物（本机）：`~/devops/opsxdb/.ui-review/ctx-menus/`。新增设计待办只改本文件。
@@ -202,7 +245,8 @@
 | zset Score 毫秒/秒时间戳 → 可读时间副显（`tsLabel`，误判有单测） | 已做 |
 | 表格分批渲染：首屏 100 行 + 「加载更多（已显示 X / 共 Y）」 | 已做 |
 | 集群跨分片 SCAN（`scanAll` ForEachMaster，本地 3 主 19/19 键实测；编辑器 SCAN 同步修） | 已做 |
-| SCAN 游标分页（HSCAN/ZSCAN cursor，>500 大键真翻页） | **未做**（P1） |
+| Key 树 SCAN 续扫（单机/Cluster 按主节点保存游标，逐页合并去重） | 已做；真大键空间/集群拓扑变化待桌面复验 |
+| Hash/Set/ZSet 值分页（HSCAN/ZSCAN cursor，>500 大键真翻页） | 已有续载实现；真实大键待复验 |
 | 批量操作（多选删/按 pattern 批删/导出导入）、监控 INFO/慢日志、更多 viewer（hex/msgpack） | 后置 |
 | Sentinel 真拓扑联调 | 环境缺口 |

@@ -213,11 +257,12 @@
 | 查询历史：去重置顶、一键重跑 ▶、过滤框、耗时/行数/失败红标（上限 200） | 已做 |
 | 点表名打开前 100 行（单击延迟/双击立即，脏 Tab 确认） | 已做 |
 | Tab 标题表名化（打开表的新 Tab 显示表名而非「查询 N」） | 已做 |
-| 表右键：生成 SELECT/INSERT/UPDATE/DELETE（列感知+方言引号+主键 WHERE）+ 截断/删除表（危险确认） | 已做 |
-| 库右键：新建查询 | 已做 |
+| 表右键：生成 SELECT/INSERT/UPDATE/DELETE（列感知+方言引号+主键 WHERE）+ 截断/删除表（危险确认） | 历史交付记录；2026-10-14 已补 SELECT/INSERT 菜单，UPDATE/DELETE 模板未开放；截断/删除已接入，当前状态见 §3 |
+| 库右键：新建查询 | 2026-10-14 已补所点库上下文与持久化回归，见 §3 |
 | 结构页：索引/外键/触发器区块（MySQL 族 information_schema，前端直连） | 已做 |
-| 表设计器 / 表重命名 / CREATE TABLE 生成 / 数据导出（CSV/转储） | **未做**（P1） |
-| 结果表自绘右键 | **未做**（P1，仍仅吞系统菜单） |
+| 表设计器 / 表重命名 / CREATE TABLE 生成 | **未做**（P1）；右侧结构查看已有字段及部分引擎的索引/外键/触发器，不等于修改能力 |
+| 数据导出（CSV/JSON/INSERT/整表/完整查询） | **已有部分入口**；表右键、流式大表验收、文件与失败处理仍待完善，详见专项盘点 |
+| 结果表自绘右键 | 2026-10-14 已补复制与导出，桌面验收待办见 §3 |

 ### 去 Web 客户端收尾（在 §「去 Web 客户端」基础上）
 | 项 | 状态 |
@@ -227,7 +272,7 @@
 | CORS 收紧：仅留 5174（桌面 devUrl）与 tauri:// 两个来源 | 已做 |
 | 文档/官网口径统一：删「Web 自托管」形态卡与双形态表述；FAQ 明确「浏览器不能操作」 | 已做 |

-> 验收口径：以上「已做」项均经 桌面 App 实测（本地 MySQL/Redis 单机 + 3 主 Cluster）或单测覆盖（38 例全绿）；测试侧复跑按 §11 流程。
+> 历史验收口径：当时「已做」项经桌面 App 实测（本地 MySQL/Redis 单机 + 3 主 Cluster）或单测覆盖（38 例全绿）；不代表迁移后的当前状态，右键菜单以 §3 的 2026-10-14 核查及后续桌面复验为准。测试侧复跑按 §11 流程。

 ## 23. 三项目状态收敛 + opsxdb 设置重构与 DataGrip 高亮（2026-10-14）

@@ -238,4 +283,95 @@
 | 「连接已断开」横幅移除 | 已做：整条顶部红色横幅删除（状态行已有提示，顶部横幅不友好）；重连能力保留 |
 | SQL 高亮 DataGrip 风 | 已做：关键字亮蓝加粗 / 字符串红 / 数字浅绿 / 注释灰斜体 / 标识符浅灰白；light 同构对齐 IntelliJ |
 | opsxapi 迁移 | 回滚到可用基线 6452026（apps 布局保留）——用户确认只做 opsxdb；迁移半成品已弃 |
-| 修复：GUI 样式全丢（白底裸控件） | 已修：根级迁移漏了 tailwind.config.ts / postcss.config.js（content 路径已改 ./src + ./packages/ui）与 index.html/public 资源；CSS 产物 12KB→32KB（Tailwind 全量恢复）。教训：单包迁移 checklist 应含样式链 |
+| 修复：GUI 样式全丢（白底裸控件） | 已修：根级迁移漏了 tailwind.config.ts / postcss.config.js（content 路径已改 ./src）与 index.html/public 资源；CSS 产物 12KB→32KB（Tailwind 全量恢复）。教训：单包迁移 checklist 应含样式链 |
+
+- 2026-10-14：完成根级 Tauri 2 目录整理，移除 apps/packages 重复副本，修复启动、打包、sidecar 路径及图标引用；homepage 未改动。
+
+### 对象树与 dbx 表操作补充（2026-10-14）
+
+- 库下保留表、视图、存储过程、函数四类分组，按驱动能力裁剪；视图现在可展开字段。
+- 表下增加索引、外键、触发器分组，展开时才查询；支持独立刷新、复制名称和定义/详情，失败提示重试，未适配引擎明确提示。MySQL 系列、PG 系列、SQLite 已实现目录查询，真实引擎兼容性待验收。元数据最多取 1000 项并提示截断。
+- 表右键补齐「查看结构」及「复制建表 / 视图 SQL」，与已有查看数据、前 N 行、DDL、复制名称、SELECT/INSERT 模板、刷新、危险确认操作组成常用菜单。
+- 当时对 dbx 截图的后续清单：重命名、表级导入、克隆表；UPDATE/DELETE 模板及表级 CSV/JSON 导出已在后续落地。关系图、数据比较后置；检查约束尚未接入。
+- 验证：新增目录查询边界测试；桌面展开/收起、主题、右键定位及真实数据库权限、目录兼容性仍需验收。
+
+### AI 与 Redis 易用性（2026-10-14）
+
+- AI 数据库上下文优先跟随 SQL 标签的当前库；输入区展示连接/库。精简顶部重复选择器和快捷按钮为底部操作选择、多行输入、简短空态。响应仅写入原标签且不覆盖等待期间修改的 SQL。
+- Redis Key 搜索框支持回车/搜索按钮；单机各 DB 节点和 Cluster 顶部有独立搜索。输入阶段不请求服务端；无通配符时自动按 `*关键词*` 扫描，完整同名 Key 单独置顶；每批最多 20 次 SCAN（COUNT 200 为提示而非硬限制）、通常返回约 500 项。后续已加入「加载更多」游标续扫；有限扫描无命中不代表 Key 不存在。Cluster 只显示 Key 树，隐藏 DB0 层。
+- SQL 工具条可切 Redis 单机 DB0–DB15；切换连接时选择该连接的查询标签，或新建一个标签，AI 库上下文只读取当前连接对应的标签。新建/重选旧标签及命令执行统一校正 Redis 库号，Cluster 固定 DB0 并拒绝 SELECT 切到非零库。AI 操作改为可见选项，删除“方言”。Key 树仅标有效期，不重复标“永久”；键详情可修改 TTL 并保存，0 秒禁止误删。
+- 集群拒绝连接增加可操作诊断；本机未发现 7001 监听。需确认用户的种子地址与节点公布地址，不能宣称连接故障已修复。
+- 前端构建及 81 项测试通过，Go 编译及 2 项无网络扫描预算回归通过；需监听端口的 Redis 集成测试受沙箱限制，真实集群和桌面视觉仍待验收。
+
+### 工作台标签整理（2026-10-15）
+
+- 启动时无内容的「查询 1」只作为内部编辑器占位，有实际标签时自动移除；表预览命名为「表名@库名」，旧表标签按当前库显示同样格式。标签只显示驱动图标、名称和未保存标记，连接名移至悬停提示；选中态和关闭按钮统一整理。相同表的当前预览可重复刷新，不再生成同名标签；已有 SQL/草稿不会被表预览覆盖。
+- 验证：82 项前端测试、前端构建通过；真实桌面窄窗口和多标签滚动仍待视觉验收。
+
+### 表设计器对比与增强（2026-10-15）
+
+- 对照 dbx 结构编辑器和 Navicat 截图：此前弹窗只有字段单页与列级 DDL，宽度不足，缺少普通索引与表注释编辑。借鉴分区标签、紧凑网格、固定预览层级；DBFlux 的代码重点在 Schema 树与浏览，当前未直接复制第三方实现。
+- 设计器改为大工作区与字段/索引/外键/触发器/SQL 预览分区。MySQL 系列可编辑普通 BTREE、唯一/复合索引与表注释；特殊索引只读，PG/SQLite 索引及外键/触发器只读。字段排序仅新建表有效。元数据读取失败、存在不支持的变更时禁用应用；实际应用前展示 DDL 确认。
+- 修复 MySQL 列 `Extra` 未传递造成自增属性在字段修改时可能丢失的问题。索引 DDL 与转义有单测，真实桌面交互、MySQL/MariaDB 兼容性以及结构漂移校验仍待验收。
+
+### 查询标签的 USE 切库（2026-10-15）
+
+- 普通 SQL 通过当前标签的库发给本机会话，后端按库打开连接池。原先 MySQL/SQL Server 的 `USE` 只修改池中的单条物理连接，标签与下一条语句可能仍指向旧库；现改为验证目标库并更新发起执行的标签，脚本中后续语句读取新库。无效语法或目标库不可用不改变标签，并停止该批次后续语句以免在旧库误执行。PG 改用工具条切库；Redis 单机 `SELECT n`、集群 DB0。
+
+### 库、表、表设计与数据迁移专项盘点
+
+详见 [DATABASE-OPERATIONS-AUDIT.md](DATABASE-OPERATIONS-AUDIT.md)。右侧结构页已复用对象树的 MySQL/PG/SQLite 元数据查询，查询失败单组提示并可重试；AI 晚到 SQL 的原标签/未保存状态和切库保护已有回归。下一步真库核对与树节点定位 → 字段/索引设计及 DDL 预览 → CSV 导入 → 表级导出完善 → 逻辑备份与恢复。规划项未标为已完成。
+
+### 主题随系统 + AI 真模型接入（2026-10-14 · 参考 opsxshell）
+
+| 项 | 状态 |
+|----|------|
+| 设置→常规主题三段：深色 / 浅色 / 随系统（`prefers-color-scheme` 监听，系统切换即时生效；编辑器高亮跟随生效主题而非原始偏好） | 已做，桌面切换系统外观待实测 |
+| AI Provider 预设（DeepSeek / OpenAI / Qwen / Kimi / GLM / MiniMax / Anthropic / Gemini / Ollama / 自定义，选预设自动填 Base URL、协议、默认模型；`src/aiPresets.ts`） | 已做 |
+| AI 三协议：openai-chat / openai-responses / anthropic（`x-api-key` + `anthropic-version`），Go 端 `server/internal/ai/remote.go` 按协议分派，旧配置按 provider 推断协议 | 已做 |
+| 安全：Base URL 默认仅放行 HTTPS；本地/内网 HTTP 需在设置中显式开启（Ollama 预设默认开启且免鉴权 `authStyle=none`） | 已做 |
+| 修复：保存 AI 配置时 key 留空不再静默清空已存 key（服务端合并旧值）；LoadConfig 补读 protocol/authStyle/allowInsecureHttp | 已修 |
+| 验证：Go ai 包单测（endpoint 校验/三协议解析/协议推断）、前端 aiPresets 测试、64 项前端测试；后端重启后端到端（anthropic 配置回读、HTTP 拦截文案、本机 Ollama 实连返回 404 model not found 证明链路通） | 已过；真实云端 key 桌面验收待做，流式输出后置 |
+
+### 表设计器 v1 + 转储 SQL + ⌘/ 注释（2026-10-14 · 参考 dbx/rustgrid）
+
+| 项 | 状态 |
+|----|------|
+| 表右键「设计表…」/ 库右键「新建表…」→ 设计器 v1（`src/TableDesigner.tsx`）：字段网格（名/类型/长度/NULL/自增/主键/默认/注释）+ 实时 DDL 预览 + 应用 | 已做，真库验收待做 |
+| 设计器 DDL 生成（`src/tableDdl.ts`）：新建 = 方言化 CREATE（MySQL 族 ENGINE/CHARSET、PG 族双引号）；编辑 = 列级 diff ALTER（MySQL ADD/DROP/MODIFY/CHANGE，PG TYPE/NOT NULL/DEFAULT/RENAME，主键组变更 ADD/DROP PRIMARY KEY）；SQLite 仅建表+ADD COLUMN，其余注释说明不静默生成 | 已做，11 项单测覆盖 |
+| 应用走 execSql，ALTER/CREATE 命中服务端危险词表自然进入二段确认；应用后自动刷新对象树 | 已做 |
+| 表右键「转储 SQL 文件 ▸」三态（仅结构 / 仅数据 / 结构和数据），服务端 `POST /api/db/dump` 流式输出 .sql（结构=SHOW CREATE TABLE/拼装 DDL + 注释头；数据=复用 insert 编码；不带 DROP TABLE） | 已做 |
+| 快捷键修正：`⌘/`（Mod-/）= 注释/取消注释（CodeMirror toggleComment，对齐 dbx/dbflux/navicat 惯例）；帮助面板改 `⌘⇧/`（⌘?）；设置与帮助浮层文案同步 | 已做 |
+| 验证：前端 75 项测试全绿、tsc 通过、Go build/vet 通过；MySQL 3306 真库端到端（建库建表插数据 → 三种转储模式输出正确、文件名头正确、`库.表` 参数归一） | 已过 |
+| 桌面验收清单：设计器新建表→改字段→改主键全流程、转储大表流式与取消、⌘/ 在选中/单行/Redis 命令模式行为 | 待做 |
+
+设计器 v1 后续：普通 MySQL 索引已可编辑，特殊索引和 PG/SQLite 索引仍只读；外键/触发器编辑、引擎/字符集选项、重命名表、克隆表、结构漂移重校验仍待做，详见审计文档。
+
+### 表右键与 Redis 键视图细节（2026-10-15）
+
+| 项 | 状态 |
+|----|------|
+| 表右键按「生成 SQL / 导出数据 / 转储 SQL」折叠，SQL 提供 SELECT、INSERT、UPDATE、DELETE、DDL 五项；CSV/JSON 可输入最多 500000 行上限，默认 100000；达到上限可能不完整，不能代替备份 | 已做；复合主键和大表导出回归待做 |
+| Redis Cluster 在隐藏 DB0 层的键树顶部提供搜索；单机与集群统一「加载更多」；String 默认 Raw、切 JSON 格式化高亮并可编辑、复制值；集群连接地址显示配置的种子节点（例如 127.0.0.1:7101） | 已做；真实多主大键空间及视觉验收待做 |
+| CSV 导入向导（预览/列映射/错误行）、结构只读比较、数据比较、导出 XLSX、整库备份/恢复 | 未做；按 `docs/DATABASE-OPERATIONS-AUDIT.md` 的依赖与优先级实施，不加无效按钮 |
+
+### Redis 集群连接失败定位与修复 + 标签确认精简（2026-10-15）
+
+| 项 | 状态 |
+|----|------|
+| 集群诊断结论：`opsxdb-redis-cluster3`（7101-7103，3 主 16384 槽）健康、宿主机可直连；`opsx-redis-cluster`（:7000）是 `cluster_state:fail` 的孤儿容器（0 槽、无 meet）；旧地址 7001-7003 已无监听 | 已定位，**集群无需重启**；建议删除 7000 坏容器避免误连 |
+| 修复：`redisMode` 未显式选择但填了多个节点时自动按 Cluster 处理（Sentinel 需显式选+masterName 不受影响）；单机客户端收到 MOVED/ASK 时错误文案附「切换部署模式为 Cluster」指引 | 已修，`redis_mode_test.go` 补推断与提示单测 |
+| 端到端（127.0.0.1:8790 临时实例）：显式 cluster 与省略 mode 两种方式 SET/GET/DEL 跨槽键全部正常（此前同键 MOVED 直抛）；单机 6379 PING 回归正常 | 已过 |
+| 移除「当前查询未保存…新开标签写入 SELECT？」确认：新开标签不覆盖任何内容，确认无意义；改为 dirty 时直接新开。关闭标签的未保存确认保留（会丢内容） | 已改，前端 75 项测试回归全绿 |
+| ⚠ 环境冲突待用户处理：`:8788` 被同族 `opsxapi` 的 `opsxdbapi-server` 占用（2026-10-15 00:06 启动，两项目默认同端口）；`./run.sh gui` 探测 health 命中后误以为 opsxdb 后端已运行。需停掉 opsxapi 或为其改端口 | 待用户决策 |
+
+### Redis 键浏览与编辑安全（2026-10-15 · 对照 ARDM / DBFlux / dbx）
+
+| 项 | 状态 |
+|----|------|
+| 参照 ARDM 的暂停/继续 SCAN、DBFlux 的 Cluster 主节点独立游标：左侧单机各 DB 与 Cluster 键树提供「继续查找 Key」；每页最多 20 次 SCAN、通常约 500 项，跨分片续扫，同名 Key 合并，输入新搜索词重新从头查 | 已实现；SCAN 非快照，扫描期间增删 Key 仍可能重现或遗漏；真实多主集群大键空间待复验 |
+| String 详情保存改为 `SET … KEEPTTL`，避免编辑清除原 TTL；Redis 6.0 前遇到不支持该参数时用原子脚本读取 PTTL/写回；并发时旧键消失会报错提示刷新 | 已修，真实 Redis TTL 往返待复验 |
+| List 单行删除由 `LREM 1 value` 改为校验索引/原值的原子脚本，避免重复值误删前面一行；按排序/过滤后的真实索引编辑 | 已修；大列表脚本耗时及多人并发需真库复验 |
+| 值详情已有 hash/list/set/zset 分页、过滤排序、行编辑及 TTL 设置；当前过滤仅作用于已加载行（不宣称全键搜索） | 已有；真大集合翻页待复验 |
+| 借鉴 DBFlux 的可见键数量/内存大小、服务端 `SCAN TYPE` 和 stream 值管理，dbx 的搜索历史/视图状态与分组设置 | P1：先做服务器端类型筛选与大键提示，再评估 stream 编辑；搜索历史和自动滚动按实际使用反馈取舍 |
+| CSV/JSON 键级导入导出、批量 UNLINK、离线 RDB 分析、监控/慢日志 | 后置：先验证单键安全与续扫，批量删除不能把 SCAN 结果当作完整集合 |
@@ -0,0 +1,9 @@
+{
+  "mcpServers": {
+    "opsxdb": {
+      "command": "/Users/logan/devops/opsxdb/bin/opsxdb-mcp",
+      "args": [],
+      "env": {}
+    }
+  }
+}
@@ -0,0 +1,6 @@
+{
+  "allowed_connection_ids": ["YOUR_CONNECTION_ID"],
+  "mode": "read_only",
+  "default_limit": 100,
+  "max_limit": 500
+}