chore: publish secure public mirror

references/commands-and-auth.md

@@ -0,0 +1,175 @@
+# 命令、登录与调用方式
+
+> 本文件由 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 返回当前版本；离线客户返回最后一次心跳版本和离线状态。