qiangayi/oracle-jump-query-public
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Files
3e25ca46962488e75348b24d71f6c1554f752b2d
oracle-jump-query-public/references/commands-and-auth.md
T

12 KiB
Raw Blame History

命令、登录与调用方式

本文件由 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

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

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

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 按需读取。

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 脚本：

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 列表
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

交互模式

不传参数直接运行，进入交互模式：

python scripts/oracle_skill.py

分析报告内容

analyze 命令返回完整分析报告，包含：

  • 源码：完整 PL/SQL 代码
  • 依赖：涉及的表、视图、嵌套存储过程/函数
  • 表结构：相关表的列信息（列名、类型、长度、可空）
  • 触发器：相关表上的触发器列表

直接 HTTP 调用

不通过脚本，直接调用中转服务 API：

分析存储过程

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
  }'

查询表结构

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 版本号，或查询指定客户版本号。

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 命令。源码仓库完成修改、提交和推送后，在已安装目录执行：

cd C:\Users\qiang\.codex\skills\oracle-jump-query
git pull --ff-only origin main
python scripts/oracle_skill.py capabilities --json

在线 Agent 返回当前版本；离线客户返回最后一次心跳版本和离线状态。

Reference in New Issue View Git Blame Copy Permalink