176 lines
6.7 KiB
Markdown
176 lines
6.7 KiB
Markdown
# 命令、登录与调用方式
|
||
|
||
> 本文件由 SKILL.md 整理拆分而来，保留原说明内容。
|
||
|
||
## 概述
|
||
|
||
通过中转服务（Transit Server）查询远程 Oracle 数据库服务器的存储过程元数据，无需开放数据库端口。
|
||
|
||
## 架构
|
||
|
||
```
|
||
AI Skill → HTTP → Transit Server (:6357) → WebSocket → Agent → Oracle
|
||
```
|
||
|
||
## 前置条件
|
||
|
||
1. 中转服务已部署并运行（默认地址: https://ts.henlo.net）
|
||
2. Agent 已部署到数据库服务器并连接中转服务
|
||
3. 本地已安装 Python 依赖：`pip install requests`
|
||
|
||
## 配置
|
||
|
||
配置文件位于技能目录下：`D:\work\恒诺\长期支持\跳板查询\demo\ai-skill\config.json`
|
||
|
||
```json
|
||
{
|
||
"transit_url": "https://ts.henlo.net",
|
||
"server_id": "server-001",
|
||
"access_token": "",
|
||
"expires_at": ""
|
||
}
|
||
```
|
||
|
||
使用查询命令前先登录中转机：
|
||
|
||
```bash
|
||
python oracle_skill.py login <secretKey> [clientCode]
|
||
```
|
||
|
||
登录成功后只保存中转机签发的 `access_token` 和过期时间，不保存 BOS `secretKey`。`clientCode` 是客户服务器编号，非必填；不传时中转机会默认选择 BOS 返回的第一个可用 client。
|
||
|
||
同一个 `secretKey` 同时只允许一个设备在线。另一台设备重新登录后，当前设备的 token 会立即失效，需要重新执行 `login <secretKey> [clientCode]`。
|
||
|
||
## 调用方式
|
||
|
||
使用 `scripts/oracle_skill.py` 脚本：
|
||
|
||
```bash
|
||
python scripts/oracle_skill.py <command> [args]
|
||
```
|
||
|
||
### 可用命令
|
||
|
||
| 命令 | 说明 | 示例 |
|
||
|------|------|------|
|
||
| `analyze <schema> <proc>` | 完整分析存储过程 | `python oracle_skill.py analyze BOS M_RETAIL_SUBMIT` |
|
||
| `list <schema>` | 列出 schema 下所有存储过程 | `python oracle_skill.py list BOS` |
|
||
| `source <schema> <proc>` | 获取存储过程源码 | `python oracle_skill.py source BOS M_RETAIL_SUBMIT` |
|
||
| `deps <schema> <proc>` | 获取依赖（表/存储过程） | `python oracle_skill.py deps BOS M_RETAIL_SUBMIT` |
|
||
| `tables <schema> <proc>` | 获取相关表结构 | `python oracle_skill.py tables BOS M_RETAIL_SUBMIT` |
|
||
| `describe <schema> <table>` | 查询表结构（列、索引、行数） | `python oracle_skill.py describe bosnds3 xcx_so` |
|
||
| `discover [schema] [domain]` | 发现核心业务域（NL2SQL前置） | `python oracle_skill.py discover BOSNDS3 RETAIL` |
|
||
| `nl2sql [schema] [domain]` | 生成 NL2SQL Schema 字典 | `python oracle_skill.py nl2sql BOSNDS3 RETAIL` |
|
||
| `query <SQL>` | 执行 SELECT 查询，生产表必须带过滤条件和行数限制 | `python oracle_skill.py query "SELECT * FROM M_RETAIL WHERE BILLDATE=20260501 AND ROWNUM<=20"` |
|
||
| `perm <userId> <tableId> [col]` | 查询用户数据权限 | `python oracle_skill.py perm 940 12983` |
|
||
| `qperm <userId> <tableId> <SQL>` | 带权限过滤的查询 | `python oracle_skill.py qperm 940 12983 "SELECT * FROM M_OTHER_INOUT"` |
|
||
| `login <secretKey> [clientCode]` | 登录中转机 + 选择客户服务器，clientCode 非必填 | `python oracle_skill.py login mykey HENLO` |
|
||
| `logout` | 登出中转机并清除本地 token | `python oracle_skill.py logout` |
|
||
| `status` | 查看中转机登录状态 + 当前 client | `python oracle_skill.py status` |
|
||
| `switch <clientCode|clientName>` | 按 code 或名称切换 client；找不到时自动刷新 client 列表 | `python oracle_skill.py switch HENLO` |
|
||
| `clients` | 无感刷新当前用户最新授权的 client 列表及在线状态；只使用当前登录 token | `python oracle_skill.py clients` |
|
||
| `agent_update [clientCode] [timeout]` | 触发客户 Agent 自动更新，升级包由 Agent 从 OSS 下载 | `python oracle_skill.py agent_update HENLO 300` |
|
||
| `awr_status [clientCode]` | 查看 AWR 授权和可用状态，不生成报告 | `python oracle_skill.py awr_status WEIRUI` |
|
||
| `awr_list [clientCode]` | 列出 Agent 已生成的 AWR 报告 | `python oracle_skill.py awr_list WEIRUI` |
|
||
| `awr_download <clientCode> <yyyyMMdd>` | 下载 Agent 原始 AWR HTML | `python oracle_skill.py awr_download WEIRUI 20260720` |
|
||
| `servers` | 列出在线 Agent | `python oracle_skill.py servers` |
|
||
| `health` | 检查中转服务状态 | `python oracle_skill.py health` |
|
||
| `tablespace / tablespaces` | 查询表空间使用情况 | `python oracle_skill.py tablespace` |
|
||
|
||
### 交互模式
|
||
|
||
不传参数直接运行，进入交互模式：
|
||
|
||
```bash
|
||
python scripts/oracle_skill.py
|
||
```
|
||
|
||
|
||
## 分析报告内容
|
||
|
||
`analyze` 命令返回完整分析报告，包含：
|
||
- **源码**：完整 PL/SQL 代码
|
||
- **依赖**：涉及的表、视图、嵌套存储过程/函数
|
||
- **表结构**：相关表的列信息（列名、类型、长度、可空）
|
||
- **触发器**：相关表上的触发器列表
|
||
|
||
## 直接 HTTP 调用
|
||
|
||
不通过脚本，直接调用中转服务 API：
|
||
|
||
### 分析存储过程
|
||
|
||
```bash
|
||
curl -X POST https://ts.henlo.net/api/query \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"server_id": "server-001",
|
||
"action": "analyze_procedure",
|
||
"schema": "BOS",
|
||
"name": "M_RETAIL_SUBMIT",
|
||
"timeout": 60
|
||
}'
|
||
```
|
||
|
||
### 查询表结构
|
||
|
||
```bash
|
||
curl -X POST https://ts.henlo.net/api/query \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"server_id": "server-001",
|
||
"action": "describe_table",
|
||
"schema": "bosnds3",
|
||
"name": "xcx_so",
|
||
"timeout": 30
|
||
}'
|
||
```
|
||
|
||
### action 类型
|
||
|
||
| action | 说明 |
|
||
|--------|------|
|
||
| `analyze_procedure` | 完整分析 |
|
||
| `list_procedures` | 列出存储过程 |
|
||
| `get_source` | 源码 |
|
||
| `get_dependencies` | 依赖 |
|
||
| `get_tables` | 表结构（通过存储过程依赖） |
|
||
| `describe_table` | 查询表结构（列、索引、行数、注释） |
|
||
| `execute_query` | 执行 SELECT 查询（只读）—— 表空间查询也复用此 action |
|
||
| `schema_discovery` | 发现核心业务域 |
|
||
| `generate_nl2sql_schema` | 生成 NL2SQL Schema 字典 |
|
||
|
||
|
||
## 故障排查
|
||
|
||
| 问题 | 排查 |
|
||
|------|------|
|
||
| `无法连接中转服务` | 检查 transit_url 地址和端口 |
|
||
| `agent not found` | 确认 Agent 已启动并连接成功 |
|
||
| `请求超时` | Agent 可能卡住，增大 timeout 参数 |
|
||
| Oracle 连接失败 | 检查 Agent 的 config.json 中 Oracle 配置 |
|
||
|
||
|
||
|
||
|
||
## Agent 版本查询
|
||
|
||
自然语言可说：查询所有客户的 Agent 版本号，或查询指定客户版本号。
|
||
|
||
```powershell
|
||
python scripts/oracle_skill.py version agent HENLO RENBEN --json
|
||
python scripts/oracle_skill.py version agent --all --json
|
||
```
|
||
|
||
## Skill Git 更新流程
|
||
|
||
Skill 使用 Gitea Git 仓库作为唯一更新来源，不使用 OSS 或 `skill_update` 命令。源码仓库完成修改、提交和推送后，在已安装目录执行：
|
||
|
||
```powershell
|
||
cd C:\Users\qiang\.codex\skills\oracle-jump-query
|
||
git pull --ff-only origin main
|
||
python scripts/oracle_skill.py capabilities --json
|
||
```
|
||
|
||
在线 Agent 返回当前版本；离线客户返回最后一次心跳版本和离线状态。
|