docs: 补短架构与文档索引

2026-10-19 21:19:02 +08:00
1 parent 40b9bdcc8c
commit 9e7135782b
@@ -63,6 +63,8 @@ open http://127.0.0.1:8788/docs      # 文档

 见 [docs/BACKLOG.md](docs/BACKLOG.md)。AI/MCP 任务书：[docs/15-AI-MCP-Agent.md](docs/15-AI-MCP-Agent.md)。

+文档索引与短架构：[docs/README.md](docs/README.md)、[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)。
+
 ## MCP（P0 只读）

 外部 Agent（Cursor / Claude Code 等）可通过本机 stdio MCP 安全查库：
@@ -0,0 +1,66 @@
+# OpsxDB 架构（短）
+
+> 一页总览。专题不在这里展开：AI/MCP 见 [15-AI-MCP-Agent.md](./15-AI-MCP-Agent.md)，会话层见 [16-AI-Session-Harness.md](./16-AI-Session-Harness.md)。审计/对比文是参考，不是第二套总览。
+
+## 产品边界
+
+```text
+浏览器  →  只看官网 + 文档（Gin）
+操作    →  只走桌面 Tauri（./run.sh gui）
+```
+
+- **产品 UI 只认根级 `/src`**。验收、回归、交互口径都以 `/src` 为准。
+- `packages/` 里只有 MCP 的 npm 壳 `packages/opsxdb-mcp`，**没有** `packages/ui` 产品面，不进验收。
+- `src` 的 Vite（默认 `:5174`）只是桌面 `devUrl` / 打包源，**不是**浏览器工作台。
+- Gin（`server`）= 官网 / docs / health / 本机驱动与查询 API。不是远程多人协作后端。
+- `homepage/` 保持独立，不并进桌面 UI。
+
+## 模块
+
+| 路径 | 职责 |
+|------|------|
+| `/src` | React 桌面 UI：连接、对象树、SQL 工作台、结果、Redis 键面板、AI 侧栏 |
+| `src-tauri/` | Tauri 2 壳、本机 sidecar、能力配置 |
+| `server/` | Gin：官网/docs、`/health`、`/api/db/*`、AI/MCP 工具运行时 |
+| `connection-types/` | 引擎注册表（`ready` / `verified`）；未就绪的界面须灰态 |
+| `agents/` | JDBC / JVM agent 桥（达梦、Mongo、ZooKeeper 等） |
+| `packages/opsxdb-mcp` | 外部 Agent 用的 npm 启动壳，不是产品 UI |
+
+引擎分发在 `server/internal/db`（MySQL 族、Postgres、SQL Server、Oracle、SQLite、Redis、ES、Influx、agent）。注册表与代码现阶段手工对齐，以代码为准。
+
+## 端口
+
+| 服务 | 默认 | 环境变量 | 说明 |
+|------|------|----------|------|
+| Gin | **8788** | `OPSXDB_SERVER_PORT` | 官网、文档、本机 API。只绑本机 |
+| Vite | **5174** | `OPSXDB_WEB_PORT` | 仅 `./run.sh gui` / 打包。`strictPort`，代理 `/api`、`/health` → 8788 |
+
+## 关键数据流
+
+```text
+./run.sh gui
+  Tauri 壳 ──加载──▶ /src（开发态 Vite :5174，生产包内嵌）
+       │
+       ▼
+  本机 Gin :8788   /api/db/* 、AI
+       │
+       ├─ 原生驱动 / ES / Influx
+       └─ agents/ JDBC·JVM 桥
+```
+
+- 开发态 `/src` 经 Vite 把 `/api` 转到 `127.0.0.1:8788`；桌面包由 sidecar 注入 API 地址，否则回落 `http://127.0.0.1:8788`。
+- 连接保存在桌面本机，并双写 `~/.opsxdb/connections.json`，供 MCP 读。密码按现有混淆，不是钥匙串。
+- **Redis**：单机键浏览在 `/src` 的 `RedisKeyPane`，执行走 `server/internal/db/redis.go`。Sentinel/Cluster 表单与后端路径在，真拓扑以环境验收为准。危险命令（如 FLUSH*）未带确认则不执行。
+
+## MCP 与危险写
+
+工具层在 `server/internal/aitools`，桌面 Agent 与 `opsxdb-mcp`（stdio）共用。现状（以代码为准，不是早期「P0 纯只读」规划）：
+
+- 连接白名单 `~/.opsxdb/mcp.json` 的 `allowed_connection_ids` **为空 = 拒绝全部**。
+- **缺省无文件**时策略默认 `mode=read_write` 且 `allow_dangerous=true`；**已有文件**缺字段则按只读、且不允许危险 SQL。
+- 写路径：`mode=read_write` **并且**用户确认后才执行。`confirm_danger` / `ConfirmDanger` **不会**被模型自动带上（Agent 执行前会剥掉调用方的确认位）。未确认返回 `needConfirm`，不静默写。
+- 工作台 SQL 同样：`ExecSQL` 在 `ConfirmDanger` 未置位时，命中危险词表只回确认、不执行。
+- Redis：`FLUSH*` / `KEYS` / `CONFIG` 在工具层始终拒绝；其余写命令同样要 `read_write` + 确认。
+- 审计：`~/.opsxdb/logs/mcp-audit.jsonl`（不含密码）。
+
+会话状态机、incomplete、续跑见 [16-AI-Session-Harness.md](./16-AI-Session-Harness.md)。工具清单与历史阶段说明见 [15-AI-MCP-Agent.md](./15-AI-MCP-Agent.md)（文首已标明只读默认是历史规划）。
@@ -0,0 +1,25 @@
+# docs 索引
+
+日常小刀（S0/S1）：直接改，BACKLOG 记一行即可，**不要**套下面的 SDD 模板。
+
+S2/S3（跨模块、有契约或危险写路径）：把 [sdd-template.md](./sdd-template.md) 拷成 `SDD-xxx.md` 再填。模板只服务这类变更，不另开第三套总览。
+
+## 现在以哪份为准
+
+| 文档 | 用途 |
+|------|------|
+| [ARCHITECTURE.md](./ARCHITECTURE.md) | 短架构：边界、`/src` 唯一产品 UI、端口、数据流、MCP/危险写 |
+| [BACKLOG.md](./BACKLOG.md) | 待办与验收清单 |
+| [15-AI-MCP-Agent.md](./15-AI-MCP-Agent.md) | MCP / 工具层任务书 |
+| [16-AI-Session-Harness.md](./16-AI-Session-Harness.md) | 会话状态机、incomplete、Harness |
+| [sdd-template.md](./sdd-template.md) | 仅 S2/S3 拷贝使用 |
+
+## 参考（不当代码现状）
+
+| 文档 | 用途 |
+|------|------|
+| [DATABASE-OPERATIONS-AUDIT.md](./DATABASE-OPERATIONS-AUDIT.md) | 库表/迁移缺项盘点 |
+| [DB-CLIENT-REVIEW.md](./DB-CLIENT-REVIEW.md) | 与 DBX / DBeaver 的静态评审 |
+| [GUI-COMPARISON.md](./GUI-COMPARISON.md) | 与 DBFlux / DBX / RustGrid 的布局对比 |
+
+配置样例：`mcp.json.example`、`mcp-cursor.example.json`。
@@ -0,0 +1,62 @@
+# SDD 模板路径: docs/sdd-template.md
+
+# SDD 模板（S2 / S3 使用）
+
+# SDD-xxx：<功能名称>
+
+| 字段           | 内容                  |
+|----------------|-----------------------|
+| 版本 / 变更级别 | 0.1 / S2 或 S3        |
+| 设计状态       | Draft                 |
+| 实现状态       | Not Started           |
+| 负责人 / 日期  | 待指定 / YYYY-MM-DD   |
+| 关联需求       | -                     |
+| 批准状态       | 未批准                |
+
+## 1. 背景、目标与范围
+- **当前行为与证据**：
+- **本次目标**：
+- **非目标**：
+- **必须保留的行为**：
+
+## 2. 需求与约束
+- FR-01：当 <条件> 时，系统必须 <行为>。
+- NFR-01：<性能 / 安全 / 兼容要求及测量方式>
+- 边界条件、异常场景、权限要求
+
+## 3. 架构与方案
+- 涉及模块及职责
+- 关键数据流 / 调用关系
+- 复用哪些现有能力
+- 关键取舍及理由
+- Agent 可自主决定的实现细节
+
+## 4. 接口、数据与配置契约
+（已有权威文件时直接引用路径，仅说明差异）
+- 接口变更：
+- 数据模型 / 迁移：
+- 配置变更：
+- 兼容性：
+
+## 5. 风险与验收
+
+### 风险
+| 风险或失败场景 | 防护 / 降级 / 恢复 | 可观察信号 |
+|----------------|--------------------|------------|
+|                |                    |            |
+
+### 验收标准
+| AC    | 对应需求 | 前置条件与操作 | 预期结果 | 验证方式 | 结果     |
+|-------|----------|----------------|----------|----------|----------|
+| AC-01 | FR-01    |                |          |          | Not Run  |
+
+## 6. 发布与恢复（S3 必填）
+- 前置条件（配置、迁移、备份等）
+- 发布顺序与健康检查
+- 回滚或前向修复步骤
+- 不可逆操作说明
+
+## 7. 待决问题
+| 问题 | 是否阻塞 | 推荐方案 |
+|------|----------|----------|
+|      |          |          |