oracle-dba-agentic-skills

"> # Oracle DBA —代理技能 ### 一个优先考虑安全性的工具包，允许 AI 助手 *理解* **和** *操作* Oracle 数据库 — 原生，在数据库所在的机器上。    CP](https://img/MCP-SQLcl%20%2B%--dba-green)   *两层，一个库：**Oracle 官方知识** （大脑）+ **分层执行自动化** （执行层） — 通过安全带和两个 MCP 服务器连接。* </div> --- ## 目录 - [60 秒版本](#the-60-second-version) - [为什么存在](#why-this-exists) - [思维模型：大脑 + 执行层](#the-mental-model-brain--hands) - [自主模型（请阅读此部分）](#the-autonomy-model-read-this-part) - [如何在数据库 VM 上原生运行](#how-it-runs-natively-on-a-database-vm) - [内部结构](#whats-inside) - [24 个操作域](#the-24-action-domains) - [知识库](#the-knowledge-base) - [oracle-dba-ops MCP-oracle-dops-mcp-server) - [快速入门](#quick-start) - [使用实例](#usage-walkthroughs) - [操作技能剖析](#anatomy-of-an-action-skill) - [安全与治理](#safety--governance) - [验证与测试](#validation--testing) - [仓库布局](#repository-layout) - [版本与兼容性说明](#version--compatibility-notes) - [设计决策（FAQ）](#design-decisions-faq) - [路线图](#roadmap) - [贡献](#contributing) - [许可证、归属与商标](#license-attribution--trademarks) --- ## 60 秒版本 该仓库将 AI 编程助手（为 **Claude Code** 构建，可由任何支持 MCP 的客户端使用）转变为一个**有纪律的到高级 Oracle DBA**，可在 **24 个操作域**中工作 — 备份和恢复、Data Guard、RAC、性能、安全、补丁、多租户等 — 在 **Oracle Database 19c 和 23ai/26ai**、**Linux 和 Windows**它通过结合AI”演示中的三个方面来实现这一点： 1. **真实、源自官方的知识。165 个 Oracle （从 Oracle [`oracle/skills`](https://github.com/oracle/skills) 仓库以1.0 ），使代理**正确推理** — 包括 Oracle 自己的**代理安全模式**检查、、`DBMS_ASSERT`）。 2. **可执行、验证的自动化。** 210 个 Bash210 个 PowerShell 脚249 个 SQL 文件恢复手册 —按**风险，并连接到共享的安全3. **治理模型，而不是建议 只读工作可以自由运行；可逆工作**默认先运行**；破坏恢复工作**从不**自动执行 — 它批准令牌，并到打印的手册 **一句话：** *知识层告诉代理 ** 和 **为什么**层 **执行**层策略确保代理永远不会悄悄执行它执行的操作。* --- 存在 大多数“将 LLM 连接到数据库仅限于 *是一个 SQL 工具，请自便。”* 这对于分析沙盒来说问题的，但对于真正的来说**不是**有三个： - **DBA 工作在数据库之外。** 备份 (`rman`)、Data角色转换 (`dl`)、集群服务 (`srvctl`)、Data Pump (`expdp`/`impdp`)、诊断 (`adrci`，AHF/TFA)、补丁和恢复都是**主机命令** — 而 Oracle 自己的数据库内 MCP 服务器故意*无法*运行它们。 - **巨大。** 粗心的 `DROP TABLE ...`、 `TRUNCATE`、 `UNTIL TIME` 恢复或 `FAILOVER` 可能无法恢复。 将这些视为其他 SQL 一样的代理是一种责任。 - **操作前需要判断。** 好的 DBA 和危险的 DBA 之间的区别在于飞行前的思考：*什么依赖？这是可逆的吗备份吗？谁访问权限？*推理必须在代理执行**之前**可用并该库将这三个问题编码为结构，而不是“仅仅知道”： | 问题 | 本回答 | |---|---| | 主机操作超出数据库工具的可达范围 | **自定义受控 MCP 服务器** （`oracle-dba-ops`）作为 RMAN Pump / dgmgrl / srvctl恢复 / 操作系统的类型化、权限工具表面 破坏性操作 | 每个操作都**按层分类（T1/T2/T3）**带强制执行干燥运行默认值和危险操作的明确批准 | | 模型缺乏 DBA 判断 | **源自官方的知识库** （包括 Oracle 的代理安全通过知识↔操作映射连接到每个操作域 思维模型：大脑 + 执行层 ┌──────────────────────────────┐ ┌──────┐ │ 🧠 知识 （大脑） │ 🛠️ 操作 （执行层） │ │ 知识/ · 165 .md │ │ 24 个域 · 669 个制品 │ │ 源自官方的 Oracle 文档 │ │ .sh / .ps1 / .sql + 手册│ “如何及为什么” │ │ “执行 — 在层” │ └───────────────┬──────────────┘ └──────────────┘ │ 引用/KNOWLEDGE-MAP每个域之间架 │ └─────────────────────────┬────────────────────────────── ▼ ILL.md （） 将请求 路由到大脑或执行层， 加载代理安全模式，始终强制执行层级 ``` - **大脑** — 只读 Markdown。代理*读取*它；它从不执行。范围远超运维：SQL/PL-SQL 编写、应用程序开发（JDBC/MLE/驱动程序）、框架、迁移*到*其他数据库、ORDS、模式设计、性能概念，以及重要的`代理模式。 - **执行层** — 可执行、分层控制的自动化，*执行，每个脚本都源自共享的 `_common/` 安全带（`connect_db`、`log_event`、`require_dry_run`、`require_approval_token`、`precheck`、`postcheck`、`emit_metric`）。 - **路由器** — `SKILL.md` *这是“How do design / explain / migrate”问题吗？*脑。*执行 X / monitor / / recover”请求吗？* → 执行层，在层级策略下## 自主模型阅读此部分）核心。每个操作 — 在代码中 网关中 —分类为三个层安全带****代理在预下可以执行的操作。 | 层级 | 含义 | 代表性任务 | 代理可以自主|:---:|---|---|---| | 🟢 **T1** | **观察** — 只读 | 健康检查、AWR/ASH、空间/延迟/锁/阻塞报告、状态、`LIST`/`REPORT` | **自由运行。** 没有可能的突变。 | | 🟡 **T2** | **** — 低破坏半径 | 计划备份、`RMAN CONFIGURE`统计信息、Data导出、创建恢复期内进行 | **默认干燥运行。** 打印确切的执行内容 + 日检查；式 `--execute `execute=true`执行。 | | **T3** | **破坏性 / / 高可用性结构性** |/恢复、P/TSPIT块媒体恢复、故障转移、`DROPTRUNCATE`、补丁应用、逐、TDE操作、停用从执行。** 需要人类**批准令牌** *和* 默认生成可复制的**手册**。 网关拒绝运行它。 | **工作示例 — 代理被要求“清理 OE 模式的旧订单表”：** 1. 路由器看到*更改*请求knowledge/agent/destructive-op-guards.md `schema-discovery。 2. **飞行前**1）：行数、依赖视图/MV、子 FK、授予、 synonym、活动锁、调度作业引用它。 3. 它呈现发现结果并 `DROP TABLE` （回收-bin，**非** `PURGE`）— 一个 **T3** 操作。 4. 由于是 T3，代理**不**执行。 它生成确切的语句 + 回滚注释 (`FLASHBACK TABLE ... TO BEFORE DROP`) 并请求批准令牌/人工执行。 这反映了 Oracle 自己发布的 LLM 数据库访问指南：**最小权限用户（绝不使用 SYS/SYSTEM），优先使用无害的生产环境，审计所有 AI 活动，绝不启用自动批准。** 库的座右铭：**当有疑问时，使用手册。** --- ## 如何在数据库 VM 上原生运行 两个协作的 MCP 服务器，都注册到 Claude Code，都使用标准输入输出： ``` ┌──────────────────────────────────────── Claude ──stdio──▶│ 1) sqlcl （Oracle `sql -`） │数据库内 （此技能） │ │ 工具：运行 SQL · 连接 · 列出连接 │ SQL / PL-SQL │ │ 限制级别 4（无主机命令） │ 通过最小权限 │ │ 自动审计：DBTOOLS$MCP_LOG，V$SESSION 标签 │ dba_ai_conn（钱包） │ └─────────────────────────────────────────────┘ │ ┌─────────────────────────────────────────────┐ └──stdio──▶│ 2) oracle-dba-ops （此仓库 · Python） │ 主机 / 操作系统 │ 类型化、分层网关到脚本 │ RMAN · Data Pump └────────────────────┬────────────────────────┘ dgmgrl · srvctl │ 解析 <domain>/scripts/<action>， AHF · 恢复 │ 读取其 `# TIER:` 横幅，强制 │ 干燥运行 / 执行 / 批准，日志 ▼ 24 操作域 ──源──▶ _common/ （connect_db · log_event · require_dry_run · (.shps1 / + 手册)_approval_token · 前/后检查 ·） ``` - **`sqlcl`** — Oracle 官方的 SQLcl MCP`sql -mcpcl **25.2+**RE 17）。它拥有连接**钱包**使用 `-savepwd，从不在运行时传递），并**自动标记 AI 会话** （`V$SESSION.MODULE` = 客户端，$SESSION.ACTION` = 模型，每个查询前缀 `/* LLM in use … */`）到 `DBTOOLS$M 审计表，它在** 4**主机命令 — 这就是为什么存在第二个服务器的原因。 - **`oracle-dba-ops`** — 此仓库中的服务器（cp-server/oracle_dba_ops_mcp.py`）。纯 Python 3 标准库（无需 `pip` 安装 — 在任何 Oracle Linux 盒子上运行）。它是一个**网关，而不是重新实现**：它解析请求 `<domain>/scripts/<action>`该脚本 TIER:` 横唯一的事实来源带有 `shell=False` 的已验证执行政策。 和开放问题/IN-PLAYBOOKreferences/INTEGRATION-PLAYBOOK.md权威的 SQLcl 参考（已移植）： [`knowledge/sqlcl-mcp-serverknowledge/sqlcl/sqlcp-server.md)。 --- ## 内部结构 | 层级 | 路径 | 数量 | |---|---|---| | 主路由器技能 | `SKILL.md` | 1 | | 共享安全common/` | `lib.sh` + `lib.ps1` + 约定 | | **操作域** | 24 个目录 | **210 `.sh` + 210 `.ps1` + 249 `.sql`** + 24 个手册 + cron 规格 | | **知识库** | `knowledge/` | **165 `.md`**，涵盖 18 个类别（已移植，UPL-1.0） | | 主机操作 MCP 服务器 | `mcp-server/` | `oracle_dba_ops_mcp.py` + `selftest.py` （15/15） | | 虚拟机引导 | `bootstrap/` | `bootstrap.sh` + `bootstrap.ps1` | | 安装 / 验证 | `install.sh` / `install.ps1` | npx-skills-style 安装程序 + 验证套件 | | 桥梁与文档 | `references/` | `INTEGRATION-PLAYBOOK.md`，`KNOWLEDGE-MAP.md` | --- ## 24 操作域 每个域都附带一个 `SKILL.md` （带有**范围和风险映射** 表）、幂等 `scripts/*.{sh,ps1}` （+ 只读 `checks/`）、`sql/*.sql` （通过 SQLcl MCP 运行）、用于 T3 操作的深入 `references/runbooks.md`、 `references/version-notes.md` （19c 与 23ai/26ai）以及 `cron/` 调度。 | # | 域 | 涵盖内容 | 层级混合 | |--:|---|---|:--:| | 1 | `provisioning-installation-configuration` | RDBMS/GI 安装、DBCA、ASM、监听器、参数、NLS、DB 链接 | T2·T3 | | 2 | `user-role-access-management` | 用户、角色、配置文件、授予、密码策略、重新认证 | T1·T2 | | 3 | `monitoring-alerting` | 运行/关闭、警报日志、空间、监控、作业、OEM 模板 | T1·T2 | | 4 | `space-storage-management` | 数据文件、表空间、ASM、FRA、撤销/临时、清理、重组 | T1·T2 | | 5 | `backup-and-recovery` | RMAN 完整/增量/归档日志、Data Pump、交叉检查、恢复点、恢复手册 | T1·T2·T3 | | 6 | `performance-tuning-diagnostics` | AWR/ASH、Top-SQL、统计信息、计划基准、SQL 调优顾问、终止会话 | T1·T2 | | 7 | `patching-upgrades` | OPatch/RU、datapatch、AutoUpgrade、滚动和备用补丁 | T2·T3 | | 8 | `rac-high-availability` | srvctl 服务、VIP/SCAN、OCR、节点添加/删除、集群软件 RCA | T1·T2·T3 | | 9 | `data-guard-disaster-recovery` | 传输/应用延迟、代理、切换/故障转移、备用构建、观察者 | T1·T2·T3 | | 10 | `goldengate-replication` | 提取/复制、跟踪文件、初始加载、心跳、物化视图、CDR | T1· | | 11 | `cloning-refresh-migration` | RMAN DUPDB 克隆/刷新、TTS/XTTS、ZDM、数据 | T2·T3 | | 12 | `multitenant-cdb` | PDB 打开/保存状态、克隆、插入/拔出、资源管理器、锁定 | T1·T2·T3 | | 13 | `job-scheduling-automation` | DBMS_SCHEDULER 作业、链、外部作业、故障诊断 | T1·T2 | | 14 | `routine-maintenance` | 编译无效对象、清理回收站/审计、索引重建、物化视图刷新 | T1·T2 | | 15 | `security-encryption-auditing` | 统一审计、CIS 加固、TDE/钱包、数据脱敏、VPD、Vault | T1·T2·T3 | | 16 | `networking-connectivity` | 监听器配置、tnsnames、CMAN、ORA-12xxx、SQL*Net 调优 | T1·T2 | | 17 | `flashback-technologies` | 闪回查询/表/删除/事务、恢复点、FDA、闪回数据库 | T1·T2·T3 | | 18 | `capacity-planning-reporting` | 状态/空间/SLA 报告、增长预测、计费 | T1·T2 | | 19 | `incident-problem-management` | 故障诊断、ORA-错误/RCA、挂起/死锁、AHF/TFA、ORA-600/7445、SR 工作流程 | T1·T2·T3 | | 20 | `exadata-engineered-systems` | exachk、单元格管理、IORM、智能扫描/闪存缓存、扩展 | T1·T2·T3 | | 21 | `advanced-features` | 压缩/HCC、In-Memory、分区、数据分片、结果缓存 | T1·T2·T3 | | 22 | `enterprise-manager-oem-tooling` | OEM 目标/代理/黑屏/模板、存储库、云控制 | T1·T2 | | 23 | `cloud-autonomous-oci` | 自主/Base DB 配置、云备份、自动扩展、ZDM/DMS | T1·T2·T3 | | 24 | `decommissioning-lifecycle-end` | 最终备份、关闭/停用、清理、存档、安全销毁 | T2·T3 | --- ## 知识库 `knowledge/` 来自 Oracle 官方的 [`oracle/skills`](https://github.com/oracle/skills) `db/` 领域（UPL-1.0）。它是代理的参考库： | 类别 | 亮点 | |---|---| | `agent/` | **破坏性操作防护、幂等性模式、安全 DML、模式发现、ORA-错误目录、NL→SQL、意图消歧** — 安全大脑 | | `sqlcl/` | SQLcl 基础知识、脚本编写、Liquibase、DDL 生成、数据加载、CI/CD、**MCP 服务器文档** | | `performance/` | 解释计划、AWR、ASH、等待事件、优化器统计信息、索引、内存 | | `plsql/` · `sql-dev/` | 包/错误/性能设计、集合、游调试；SQL 模式、动态 SQL、注入防范 | | `security/` | 特权管理、VPD蔽、审计、加密、网络安全 | | `appdev/`frameworks/` | JDBC、node-oracledb、python-oracledb、.NET、Go、、Django、JPA、MyBatis、TypeORM、 | | `migrations/` | 来自 PostgreSQL、MySQL、DB、Snowflake2、Sybase、Teradata、Redshift、SQLite | | `architecture/` · `design/` · `devops/` · `features/` · `admin/` · `monitoring/` ·/` · `containers/` | RAC/Multitenant/Exadata/In-Memory/DG 架构；ERD/分区/表空间；模式迁移和 EBR；AQ/调度器/MV/矢量搜索/Select AI；ORDS；OCR 容器 | [`references/KNOWLEDGE-MAP.md`](references/KNOWLEDGE ## `oracle-dba-ops` MCP 服务器 纯stdlib **Python 3** stdio MCP服务器（`mcp-server/oracle_dba_ops_mcp.py`）- 零依赖，在任何Python 3运行环境中均可运行。它将主机侧的动作层暴露为一个安全、类型化的工具表面。 **通用网关工具** | 工具 | 层级 | 目的 | |---|:--:|---| | `list_domains` | T1 | 列出此主机上存在的24个动作域 | | `list_actions` | T1 | 列出某个域的可运行脚本，每个脚本都有其层级 | | `describe_action` | T1 | 显示脚本的头部/用法 + 层级（不执行） | | `read_runbook` | T1 | 返回某个域的Tier-3运行手册，用于规划 | | `run_action` | 分层 | 在自治策略下运行某个域的动作 | **命名便捷工具** （可发现的`run_action`包装器，具有相同的防护措施）： `rman_backup` *(完整 / 增量 / 归档日志)* · `backup_status` · `dataguard_status` · `db_health` · `tablespace_usage` · `alert_log_scan` · `blocking_locks` · `perf_triage` · `audit_report` · `datapump_export` · `crosscheck_delete` · `gather_stats` · `recompile_invalid`. **安全属性：** 读取脚本头部的层级；T1运行，T2默认干预运行，T3被拒绝 → 运行手册；拒绝Shell元字符；包含路径遍历到技能根目录下；使用`shell=False`启动；从不处理凭证；记录每次调用。 **示例 - T2调用默认安全预览：** ```jsonc // tools/call → rman_backup { "name": "rman_backup", "arguments": { "kind": "full" } } // → "tier=T2 decision=dry-run would run: bash .../rman_full_backup.sh --dry-run" // (除非您传递"execute": true，否则不会备份任何内容) ``` **示例 - T3调用被拒绝，附带运行手册：** ```jsonc { "name": "run_action", "arguments": { "domain": "backup-and-recovery", "action": "restore_database" } } // → "TIER-3 BLOCKED (no valid approval token) … RUNBOOK: .../references/runbooks.md" ``` 注册和测试： ```bash claude mcp add oracle-dba-ops python3 /path/to/oracle-dba-agentic-skills/mcp-server/oracle_dba_ops_mcp.py python3 mcp-server/selftest.py # -> 15 passed, 0 failed ``` 更多信息： [`mcp-server/README.md`](mcp-server/README.md). --- ## 快速入门 ### 先决条件（在数据库虚拟机或可以访问它的主机上） - **SQLcl 25.2+** 和 **JRE 17 或 21** （SQLcl MCP 要求） - **Python 3** （用于 `oracle-dba-ops` — 仅标准库） - **Claude Code** （或另一个 MCP 客户端） - 一个 **最小权限** 的 DB 用户，用于 AI 访问 — 永远不要使用 SYS/SYSTEM （参见 `knowledge/security/privilege-management.md`） ### 1. 安装技能 ```bash git clone https://github.com/Shreyas70773/oracle-dba-agentic-skills.git cp -r oracle-dba-agentic-skills ~/.claude/skills/oracle-dba-super # 或项目本地的 .claude/skills/ ``` ### 2. 引导虚拟机 + 注册两个MCP服务器（先预览） ```bash # Linux/macOS ./bootstrap/bootstrap.sh --sqlcl-bin /opt/sqlcl/bin/sql --register-mcp # 干预运行预览 ./bootstrap/bootstrap.sh --sqlcl-bin /opt/sqlcl/bin/sql --register-mcp --execute # 应用 ``` ```powershell # Windows ./bootstrap/bootstrap.ps1 -SqlclBin C:\sqlcl\bin\sql.exe -RegisterMcp -Execute ``` ### 3. 保存最小权限连接（引导程序从不获取密码） ```sql sql /nolog SQL> conn -save dba_ai_conn -savepwd <DBA_AI_USER>/<pwd>@//<host>:1521/<service> ``` ### 4. 一步安装 + 验证 ```bash ./install.sh --register-mcp # 安装，注册MCP，运行验证套件 ./install.sh --validate-only # 仅重新运行验证 ``` 完整虚拟机演练： [`INSTALL.md`](INSTALL.md). ### 将舰队（许多虚拟机）纳入管理 - 一个命令 手动设置每个虚拟机（SSH密钥，复制存储库，保存SQLcl连接，注册MCP服务器）很乏味且容易出错。 **舰队注册器** 可以从库存文件中完成所有这些操作： ```bash cp fleet/inventory.example.json fleet/inventory.json # 列出您的虚拟机（此处不含密码） python3 fleet/onboard.py --inventory fleet/inventory.json --dry-run # 预览 python3 fleet/onboard.py --inventory fleet/inventory.json # 将它们全部纳入管理 ``` 每个虚拟机，它安装SSH密钥，部署存储库，并运行一个虚拟机**自动配置器**，该程序检测`ORACLE_HOME`/SQLcl，**查找或安装Java 17** （`sql -mcp`需要但捆绑的JDK缺少），编写一个自包含的SQLcl包装器，并**保存`dba_ai_conn`连接** — 优先使用OS身份验证`/ as sysdba`（不需要监听器），否则自动发现主机/端口/服务来自`lsnrctl`（在`ALTER SYSTEM REGISTER`之后），并验证它。然后它注册**两个**MCP服务器，命名为范围限定（`oracle-dba-ops-<vm>`，`sqlcl-<vm>`），因此多个虚拟机共存。您 **一次**输入每个虚拟机的SSH和数据库密码；磁盘或命令行上不存储任何内容。它直接写入`.mcp.json`（比`claude mcp add`更可靠）。所有现场陷阱 - Java 17，环境变量在SSH上未设置的问题，1521-vs-1522 / NAT-IP / `.localdomain`监听器混乱，带括号的粘贴 - 在[`fleet/README.md`](fleet/README.md)中处理或记录。 > **Linux舰队和`.ps1`：** MCP服务器在**每个Linux虚拟机**上运行（通过SSH），因此它们自动选择`.sh`脚本 - `.ps1`文件仅在Windows主机部署中未使用。无需采取任何操作；实际上这不是一个不匹配的问题。 --- ## 使用演练 安装完成后，您只需与您的助手对话。技能会自动路由并强制执行层级。 **🟢 "这个数据库今天早上是否健康？"** → 路由到 `monitoring-alerting` （T1）→ 运行 `db_health` / `check_*` 只读脚本和SQLcl MCP → 返回正常/异常，空间，延迟，阻塞锁，失效对象，最后一次备份状态。不需要确认（只读）。 **🟡 "对PRODDB进行完整RMAN备份。"** → 路由到 `backup-and-recovery` （T2）→ 首先返回RMAN脚本 + 通道 + 目标 + 保留影响的**干预运行预览** → 您说“执行” → 它重新运行并带有`execute=true`，记录结构化输出，并在备份集上运行后检查。 **🔴 "我们丢失了一个数据文件 - 将数据库恢复到14:00。"** → 路由到 `backup-and-recovery` 恢复（T3）→ 它**不**运行任何操作。它读取 `references/runbooks.md`，呈现确切的`RESTORE`/`RECOVER ... UNTIL TIME` 序列，一个预检清单（备份可用性，空间，停机窗口，批准），验证步骤和回滚/中止路径 - 并请求一个人类批准令牌。 --- ## 动作技能的解剖结构 每个域都遵循相同的结构，因此代理（和您）始终知道在哪里查找： ``` backup-and-recovery/ ├── SKILL.md # 范围和风险图：任务 | 级别 | 层级 | 机制 | 是否幂等？ ├── scripts/ │ ├── rman_full_backup.sh/.ps1 # T2：默认干预运行，--execute 执行，幂等，记录 │ ├── crosscheck_delete.sh/.ps1 # T2：仅在保留期内删除；从不DELETE FORCE │ └── checks/ │ └── check_backup_status.sh/.ps1 # T1：只读 ├── sql/ │ └── *.sql # 通过SQLcl MCP在dba_ai_conn上运行 ├── references/ │ ├── runbooks.md # T3：PITR，媒体恢复，TSPITR，块恢复（人为运行） │ └── version-notes.md # 19c与23ai/26ai差异 └── cron/ ├── crontab.d # Linux计划 └── task-scheduler.xml # Windows任务计划程序导入 ``` 每个`.sh`/`.ps1`都带有`# TIER:`横幅，源自 `_common`，默认为T2+的干预运行，发出结构化日志，在失败时退出非零，并检测“已经完成”以保持幂等。 --- ## 安全性和治理 - **最小权限和仅钱包。** 代理连接为专用低权限用户（`dba_ai_conn`）；凭证存储在SQLcl钱包中，从不放置在argv，env或文件中。 - **分层自主，两次强制执行** — 每次在脚本内部的 `_common` 封装器中，一次在 `oracle-dba-ops` MCP网关中。 - **T3由人控制。** 破坏性/恢复/HA工作是运行手册+审批令牌；网关拒绝在没有令牌的情况下自动执行它（它将您路由到程序）。 - **内置审计性。** SQLcl自动记录所有AI活动（`DBTOOLS$MCP_LOG`，`V$SESSION` MODULE/ACTION标记，`/* LLM in use */`查询标记）； ops服务器编写结构化日志行。 - **注入强化网关** （OWASP MCP05 / CWE-78）：直接启动，无Shell，Shell元字符拒绝，路径遍历控制。 - **与Oracle自己的指导方针保持一致：** 最小权限，优先使用无害的非生产环境，审计LLM查询，**绝不启用自动批准**。 --- ## 验证和测试 | 网关 | 结果 | |---|---| | 所有动作 + 引导脚本上的 `bash -n` | ✅ 所有通过 | | 所有`.ps1`上的PowerShell解析 | ✅ 所有通过 | | `.sh` / `.ps1`行为一致性 | ✅ 没有孤立 | | `oracle-dba-ops` MCP自我测试（协议，层级，干预运行/执行，T3拒绝，注入/遍历） | ✅ **15 / 15** | | `install.* --validate-only` | ✅ **PASS** | | 每个域的深层T3运行手册 | ✅ | | 提交的秘密/日志 | ✅ 无 | > **诚实状态：** 以上所有内容均为**静态/协议**验证。 其中没有一个在**实时Oracle数据库**上运行过。 在非生产虚拟机上，运行 **T1（只读）**，然后 **T2在 `--dry-run`**，然后 **--execute** — 正如自主模型所期望的那样。 --- ## 仓库布局 ``` . ├── SKILL.md · README.md · LICENSE · NOTICE.md · INSTALL.md · MANIFEST.md ├── install.sh / install.ps1 # 安装 + 验证套件 ├── _common/ # lib.sh · lib.ps1 · references/conventions.md ├── bootstrap/ # bootstrap.sh · bootstrap.ps1 · README.md ├── mcp-server/ # oracle_dba_ops_mcp.py · selftest.py · README.md ├── references/ # INTEGRATION-PLAYBOOK.md · KNOWLEDGE-MAP.md · action-domains-router.md ├── knowledge/ # 165个Oracle指导文件（UPL-1.0）+ UPL-LICENSE.txt └── <24个动作域>/ # backup-and-recovery/ · rac-high-availability/ · … ``` --- ## 版本和兼容性说明 - **基准19c。** 动作自动化是针对 **19c 和 23ai** 编写和验证的；知识笔记在适用时引用 **26ai**。 将任何特定版本视为 *verify-before-trust* 与正在运行的版本。 - **版本/拓扑结构：** 构建为企业版，单实例 + 数据卫士，本地；许多域带有RAC/Exadata/Autonomous注释。 - **操作系统：** 每个主机级任务都提供Bash（`.sh`）和PowerShell（`.ps1`）。 --- ## 设计决策（FAQ） **为什么使用单独的MCP服务器而不是降低SQLcl的限制级别？** SQLcl的限制级别4（无主机命令）是一个功能，而不是限制 — 您*希望*在DB中将工具沙盒化。主机操作属于其自己的类型化，层级感知，记录的表面。 将它们分开意味着DB路径保持最小权限，而主机路径被显式管理。 **为什么MCP服务器调用脚本而不是直接运行`rman`/`expdp`？** 重用和安全。 脚本已经编码了干预运行默认值，幂等性，日志记录和层级横幅。 网关读取横幅作为唯一事实来源，从不即兴编写命令行 — 比重新实现每个二进制文件要少得多错误。 **为什么供应商Oracle的知识而不是链接它？** 自包含和在锁定虚拟机上的离线使用。 它是UPL-1.0，因此允许以属性引用；参见 [`NOTICE.md`](NOTICE.md)。 刷新说明如下。 **将其指向生产环境是否安全？** 仅在非生产环境验证后：T1只读→T2干预运行→T2执行，T3由人批准。 架构旨在使该路径成为阻力最小的路径。 --- ## 路线图 - [x] 24个可执行的、分层控制的动作域 + 共享的封装器 - [x] 供应商Oracle知识库 + 知识 ↔ 动作桥 - [x] 原生双MCP集成（SQLcl + 自定义`oracle-dba-ops`）+ 虚拟机引导 - [x] MCP自我测试 + 安装/验证工具 + 命名便捷工具 - [ ] 在实时非生产数据库上验证端到端 - [ ] GitHub Actions CI（在每次推送时运行`bash -n` + PowerShell解析 + MCP自我测试） - [ ] 随着使用模式的出现，扩展每个域的命名MCP工具 - [ ] `knowledge/`的定期上游重新同步 --- ## 贡献 欢迎提出问题和PR。 请保持使此安全的功能： - 新主机脚本提供 **两者** `.sh` 和 `.ps1`，带有 `# TIER:` 横幅，默认为T2+的干预运行，源自 `_common`，并保持幂等。 - T3工作是 **运行手册**，而不是自动执行的脚本。 - 知识页面遵循Oracle的作者风格（`## Overview` → 示例 → 最佳实践 → `## Oracle Version Notes` → `## Sources`）。 - 在打开PR之前运行 `python3 mcp-server/selftest.py` 和 `./install.sh --validate-only`。 从上游刷新供应商知识： ```bash git clone --depth 1 https://github.com/oracle/skills.git /tmp/oracle-skills cp -r /tmp/oracle-skills/db/. knowledge/ # 保留NOTICE.md + knowledge/UPL-LICENSE.txt ``` --- ## 许可证，属性和商标 - **原始作品** （`knowledge/`之外的一切）— **MIT**，参见 [`LICENSE`](LICENSE). - **`knowledge/`** - 来自 [`oracle/skills`](https://github.com/oracle/skills)，**UPL-1.0**， Oracle和/或其关联公司版权所有 2025。 参见 [`NOTICE.md`](NOTICE.md) 和 `knowledge/UPL-LICENSE.txt`. - Oracle，Oracle数据库，SQLcl，RMAN，Data Guard，GoldenGate，Exadata，Autonomous Database和相关标志是Oracle和/或其关联公司的商标，仅用于标识。 > **免责声明：** 这是一个独立的社区项目。 它 **不隶属于，不赞助或支持** Oracle。 数据库管理具有高风险 - 在非生产环境中验证，保留破坏性操作的人类批准，并自担风险使用。 <div align="center"> *构建时偏向安全性。 只读免费，可逆转谨慎执行，绝不无需人类批准。* </div>