# 命令、登录与调用方式

> 本文件由 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` |
| `log_info <path> [--client code]` | 验证单个绝对日志路径和文件元数据 | `python oracle_skill.py log_info "D:\logs\app.log" --client AHMW --json` |
| `log_tail <path> [--client code]` | 有界读取日志末尾内容 | `python oracle_skill.py log_tail "D:\logs\app.log" --client AHMW --lines 200` |
| `log_search <path> <pattern...>` | 关键词/RE2 正则流式搜索并返回有限上下文 | `python oracle_skill.py log_search "D:\logs\app.log" ERROR --client AHMW --json` |
| `log_enable [clientCode]` / `log_disable [clientCode]` | 开启或关闭目标客户日志分析 | `python oracle_skill.py log_enable AHMW` |
| `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 字典 |
| `log_info` | 本机日志文件元数据 |
| `log_tail` | 本机日志有界尾部读取 |
| `log_search` | 本机日志有界流式筛选 |
| `log_config_set` | 只修改日志分析启用开关 |


## 故障排查

| 问题 | 排查 |
|------|------|
| `无法连接中转服务` | 检查 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 返回当前版本；离线客户返回最后一次心跳版本和离线状态。