# 命令、登录与调用方式

> 本文件由 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`；可信设备登录另需 `pip install cryptography`

## 配置

配置文件位于技能目录下：`scripts/config.json`

```json
{
    "transit_url": "https://ts.henlo.net",
    "server_id": "",
    "access_token": "",
    "expires_at": ""
}
```

使用查询命令前先登录中转机：

```bash
python oracle_skill.py login <secretKey> [clientCode]
```

登录成功后只保存中转机签发的 `access_token` 和过期时间，不保存 BOS `secretKey`。`clientCode` 是客户服务器编号，非必填；不传时中转机会默认选择 BOS 返回的第一个可用 client。

同一个 `secretKey` 同时只允许一个设备在线。另一台设备重新登录后，当前设备的 token 会立即失效，需要重新执行 `login <secretKey> [clientCode]`。

## 对话客户绑定与快速调用（1.5.54）

每个对话只需确定一次目标客户：从用户提供的客户、工单或当前对话上下文解析出明确 client code，后续沿用，用户明确切换时更新。不得从其他对话或共享配置的“当前客户”推断本对话目标；无法确定时询问客户，名称有多个匹配时列出候选，不猜测。查询客户名称映射优先读取本地 `scripts/config.json` 的 `client_list`（只读取 code/title/name，不输出 token）；找不到时执行 `clients` 刷新授权列表。

助手每次调用单 Agent 命令时自动在命令名后、业务参数前带 `--client CODE`，用户无需在每句话重复客户。该参数仅影响本次命令，不修改默认客户；命令开始即固定客户、中转地址，多步查询、权限获取、预检、下载和续登重试保持原目标。旧位置参数仍兼容；与 `--client` 不一致时直接报错。未指定时兼容本地默认客户，但为空则停止，不选择占位服务器或第一个客户。

常规查询无需先执行 `status`、`switch` 或手动登录：CLI 自动处理 token 缺失/过期，401 时复用其他进程的新 token 或可信设备续登，仅重发一次。设备未审批、撤销、过期或无本机密钥时提示原因，再由用户提供登录密钥；不自动注册设备。403、参数错误、客户离线直接返回，查询超时不重复执行。`status` 用于排障，`switch` 仅用于显式维护旧用法的默认客户。

普通查询及元数据命令可在业务参数前加 `--json`，stdout 只返回 JSON（含 `client_code`），登录、更新和诊断提示输出到 stderr。完整能力定义仍可用 `capabilities --json` 按需读取。

```powershell
python scripts/oracle_skill.py capabilities --brief --json
python scripts/oracle_skill.py describe --client WEIRUI --json BOSNDS3 M_PRODUCT
python scripts/oracle_skill.py query --client WEIRUI --json "SELECT ID, NAME FROM M_PRODUCT WHERE ID=123 AND ROWNUM<=1"
python scripts/oracle_skill.py qperm --client HENLO --json 940 12983 "SELECT ID FROM M_OTHER_INOUT WHERE ID=123 AND ROWNUM<=1"
python scripts/oracle_skill.py ops_report --client HENLO
python scripts/oracle_skill.py awr_download --client WEIRUI 20261008
```

本机 token 仍由同一安装目录中的 `scripts/config.json` 共享；不同对话共享身份、各自绑定目标。续登锁和配置锁最多等待 45 秒，锁由操作系统在进程退出时释放。配置按最新文件合并修改字段，并用同目录临时文件原子替换；锁、临时文件及设备私钥不提交 Git。不同安装目录间的认证共享未在本次实现。`logout` 会退出共享同一安装配置的所有对话。

`--client` 适用于 query/qperm/perm、analyze/source/deps/tables/describe/list/discover/nl2sql、agent、ops/ops_report、tablespace(s)、inspection_report/inspection_latest、awr_status/awr_list/awr_download、日志命令及 agent_update。历史报告 `inspection_get` 仍按报告 ID 和服务端授权访问；批量 Agent 版本仍按逐客户参数或 `--all` 访问。

`--json` 的新增前缀用法适用于 query/qperm/perm、analyze/source/deps/tables/describe/list/discover/nl2sql；巡检、AWR 和日志命令保留已有 JSON 用法。SQL 内的 `--client`、`--json` 文本不会被当作选项。

### 旧用法兼容说明

使用本 skill 时，先确认当前登录状态和 client。用户指定“恒诺 / 品小二 / 未芮 / 康奈”等服务器时，可以用 `switch <clientCode|clientName>` 按 code 或名称切换；找不到目标服务器时，skill 会先刷新 client 列表再重试匹配。若名称不够准确并匹配到多个 client，只列出候选项，请用户指定更准确的 client code，不要直接猜测切换。

上述先检查、再切换的旧操作仍可用于排障及维护默认客户；多对话查询使用本节的显式目标流程。手动 `device_login [clientCode]` 可强制重新申请 token，并协调同时启动的设备登录；普通命令自动续登无需手动调用。手动密钥登录保留原有选择默认客户的语义。

## 调用方式

使用 `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": "",
    "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": "",
    "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 返回当前版本；离线客户返回最后一次心跳版本和离线状态。