oracle-jump-query-public/SKILL.md

---
name: oracle-jump-query
description: Oracle 跳板查询技能。通过中转服务查询远程 Oracle 数据库的元数据、存储过程源码、依赖、表结构、触发器、业务字典、表空间、服务器体检和 Oracle 运维监控。连接数据库默认为只读，禁止通过 skill 查询通道直接执行 INSERT、UPDATE、DELETE、MERGE、DDL 等写操作。当用户需要分析 Oracle 存储过程、查找依赖表、查询表结构、理解 BOS 业务元数据、生成只读查询 SQL 或生成需人工确认的写库 SQL 示例时触发。
---

# Oracle 跳板查询

> **版本：v1.5.45** · [更新日志](./CHANGELOG.md)

## 使用原则

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

本 skill 的数据库通道默认只读。可以生成 SQL 和说明，但不得通过 `query` / `qperm` 执行写库语句，包括 `INSERT`、`UPDATE`、`DELETE`、`MERGE`、`DDL`、提交存储过程和其他会改变业务数据的调用。用户要求写库时，只生成 SQL，并明确说明未执行。

生产环境查询必须带明确 `WHERE` 条件和行数限制。不要为了“先看看数据”查询整表；涉及库存视图、业务大表、统计查询时尤其要先限定门店、日期、单号、状态、款号、条码或主键范围。

## 参考文档

详细规则已经拆分到 `references/`，处理对应任务时必须读取相关文件：

- [命令、登录与调用方式](./references/commands-and-auth.md)
  登录、client 切换、CLI 命令、HTTP action、故障排查。
- [生产查询限制与常用业务规则](./references/query-and-business-rules.md)
  生产查询限制、商品/款号/条码/库存规则、新增业务记录 SQL 生成规则、字段值域映射。
- [BOS 数据字典与系统地图](./references/bos-metadata.md)
  `AD_TABLE`、`AD_COLUMN`、`AD_REFBYTABLE`、`AD_TABLE_TEXT`、BOS 系统菜单和表结构地图、数据权限模型。
- [通用接口业务逻辑](./references/generic-interface.md)
  `H_INTERFACE`、`H_INSTRUCTION`、`PUSH_LOG`、`INF_LOG`、`AD_PROCESS` 的通用职责、调度任务、入站/出站流程、常见字段、状态核验、分析步骤和风险检查；处理不同客户服务器时必须以目标环境的实际表结构、BOS 元数据、值域和过程源码为准。
- [表空间、服务器体检与 Oracle 运维监控](./references/oracle-ops-and-checkup.md)
  表空间、服务器体检、Oracle 运维报告、SYS/当前账号函数授权方案和 AWR 未来开发计划。
- [整理前完整 SKILL.md 备份](./references/legacy-skill-v1.5.8.md)
  为防止内容遗漏保留的完整原文；如发现拆分文档缺项，以此为准补回。

## 常用命令

命令均在 skill 目录执行：

```powershell
cd C:\Users\qiang\.codex\skills\oracle-jump-query
python scripts/oracle_skill.py <command> [args]
```

登录中转机：

```powershell
python scripts/oracle_skill.py login <secretKey> [clientCode]
```

如果当前 Windows 用户目录中已有已审批的可信设备，也可以直接执行 `python scripts/oracle_skill.py login`；Skill 会自动检测设备并申请中转 token，只有设备不存在、被撤销或已过期时才需要提供登录密钥。

`clientCode` 是客户服务器编号，非必填；不传时中转机会默认选择 BOS 返回的第一个可用 client。登录成功后本地只保存中转机签发的 `access_token` 和过期时间，不保存 BOS `secretKey`。同一个 `secretKey` 同时只允许一个设备在线，其他设备重新登录后，当前 token 会失效。

常用命令：

| 命令 | 说明 |
|------|------|
| `status` | 查看登录状态、当前 client 和 Agent 状态 |
| `clients` | 无感刷新当前用户最新授权的 client 列表（只使用当前登录 token） |
| `device_register [deviceName]` | 在本机生成 Ed25519 密钥并提交可信设备注册请求；后台审批前状态为 `PENDING` |
| `device_login [clientCode]` | 使用本机密钥完成 challenge/signature 可信设备登录；仅限后台已审批设备 |

可信设备私钥和 `device_id` 保存在当前 Windows 用户目录的 `~/.oracle-jump-query/device-key.json`，同一用户下的不同 Skill 安装共享该文件。首次执行 `device_register` 时生成设备 ID；之后始终从该文件读取，不会覆盖或重新生成，因此同一台电脑的设备 ID 不会变化。该文件不提交到 Git。
| `switch <clientCode|clientName>` | 按 code 或名称切换当前 client；找不到时自动刷新 client 列表 |
| `analyze <schema> <proc>` | 完整分析存储过程 |
| `source <schema> <proc>` | 获取存储过程源码 |
| `deps <schema> <proc>` | 获取依赖对象 |
| `tables <schema> <proc>` | 获取相关表结构 |
| `describe <schema> <table>` | 查询表结构 |
| `query <SQL>` | 执行只读 SELECT 查询 |
| `qperm <userId> <tableId> <SQL>` | 带权限过滤的只读查询 |
| `tablespace` / `tablespaces` | 查询表空间 |
| `ops <item> [clientCode]` | 单项 Oracle 运维监控 |
| `ops_report [clientCode]` | Oracle 运维报告 |
| `inspection_report [clientCode] [--json] [--html [path]] [--markdown [path]]` | 生成服务器巡检报告并归档，默认导出固定格式 HTML，可同时导出 Markdown |
| `inspection_latest [clientCode] [--refresh] [--json] [--html [path]] [--markdown [path]]` | 查看最近归档巡检报告并默认导出 HTML；加 `--refresh` 时重新生成 |
| `inspection_get <id> [--json] [--html [path]] [--markdown [path]]` | 按归档 ID 查看历史巡检报告并默认导出 HTML |
| `awr_status [clientCode] [--json]` | 查看 AWR 授权确认、权限、快照和最近生成状态，不触发生成 |
| `awr_list [clientCode] [--json]` | 列出 Agent 已生成并保留的 AWR 报告 |
| `awr_download <clientCode> <yyyyMMdd> [--output path]` | 经中转机下载 Agent 原始 AWR HTML，不在本地渲染 |
| `log_info <path> [--client code] [--json]` | 验证服务器绝对日志路径并返回文件元数据 |
| `log_tail <path> [--client code] [--lines N] [--json]` | 有界读取服务器日志末尾内容 |
| `log_search <path> <pattern...> [--client code] [--regex] [--scope recent|full] [--json]` | 在 Agent 本机流式筛选日志并返回有限上下文 |
| `log_enable [clientCode]` / `log_disable [clientCode]` | 为有权限的客户持久化开启或关闭日志分析 |
| `agent_update [clientCode] [timeout]` | 触发客户 Agent 自动更新；由中转机下发更新动作，Agent 按 OSS latest.json 返回的包地址下载升级 |

## BOS 分析优先路径

遇到不懂的 BOS 业务术语、表单、菜单、模块、按钮、状态、字段含义时，优先走元数据，不要靠表名猜测：

```text
AD_SUBSYSTEM
  -> AD_TABLECATEGORY
  -> AD_ACCORDION
  -> AD_TABLE
  -> AD_COLUMN
  -> AD_REFBYTABLE
  -> AD_ACTION
  -> DIRECTORY
  -> AD_CXTAB / AD_CXTAB_JPARA / AD_CXTAB_DIMENSION / AD_CXTAB_FACT
```

处理单据类表时：

- 先查 `AD_TABLE` 找表名、业务说明、`MASK`、`PROC_SUBMIT`、权限目录。`MASK` 是该表声明支持的业务动作代码：`A` 新增、`M` 修改、`D` 删除、`Q` 查询、`U` 取消提交、`V` 作废、`S` 提交；可由多个字母组合，分析功能时以实际值为准。
- 同查 `AD_TABLE` 的表单事件过程：`HAS_TRIG_BD='Y'` 时 `TRIG_BD` 是删除前触发的存储过程（简称 bd）；`HAS_TRIG_AC='Y'` 时 `TRIG_AC` 是新增后触发的存储过程（简称 ac）；`HAS_TRIG_AM='Y'` 时 `TRIG_AM` 是修改后触发的存储过程（简称 am）。
- 再查 `AD_COLUMN` 理解字段含义、控件类型、默认值、引用列和值域。
- 明细表必须通过 `AD_REFBYTABLE` 查找，不要靠命名规则猜。
- 若 `AD_COLUMN.OBTAINMANNER='select'`，必须通过 `AD_LIMITVALUE_GROUP_ID` 查询 `AD_LIMITVALUE`，把显示值映射成数据库实际值。
- 如果用户提到“提交”，通常指执行或分析 `AD_TABLE.PROC_SUBMIT` 对应提交过程，不要简单理解为直接更新 `STATUS='2'`。
- `AD_TABLE_TEXT` 可作为 BOS 系统地图经验来源：它说明菜单、模块、业务表、字段、主子表、动作、权限目录和报表模板主要由 BOS 元数据表驱动。

常用系统地图 SQL 见 [BOS 数据字典与系统地图](./references/bos-metadata.md)。

## 业务规则速记

- 用户提到“通用接口”“接口指令”“接口方”“推送日志”“接收日志”“数据接口任务”“数据队列封装/推送”，或要求分析 `H_INTERFACE`、`H_INSTRUCTION`、`PUSH_LOG`、`INF_LOG`、`AD_PROCESS`、`H_INSTRUCTION_TASK`、`H_INTERFACE_DATA_TASK`、`H_INTERFACE_TASK01`、`BOS_INF_PUSH`、`INF_PUSH_DEAL`、`GET_HYJINF1` 时，先读取 [通用接口业务逻辑](./references/generic-interface.md)。这些对象是常见模型而不是固定契约；不同服务器可能缺表、增表、增减字段、改变值域、请求头合并规则或处理过程，必须先查目标环境再下结论。
- 商品、款号通常指 `M_PRODUCT`。
- 条码、SKU 通常指 `M_PRODUCT_ALIAS`；查询条码时首查 `M_PRODUCT_ALIAS.NO`。
- 款号和条码是一对多关系。
- 商品明细里的 `M_PRODUCT_ID`、`M_PRODUCTALIAS_ID`、`M_ATTRIBUTESETINSTANCE_ID` 通常分别对应款号、条码、色码属性 ASI。
- `M_ATTRIBUTESETINSTANCE` 是商品色码属性表：`VALUE1`/`VALUE1_CODE`/`VALUE1_ID` 对应颜色名称、颜色编号、颜色表 `M_COLOR.ID`；`VALUE2`/`VALUE2_CODE`/`VALUE2_ID` 对应尺码名称、尺码编号、尺码表 `M_SIZE.ID`。
- 库存通常查 `V_FA_STORAGE`，必须同时带店仓条件和款号/条码条件，并加行数限制。
- 新增业务记录 SQL 示例中，主键 `ID` 使用 `get_sequences('<表名称>')`。
- 如表存在 `DOCNO`，先查 `AD_COLUMN.SEQUENCENAME`；有值时用 `Get_SequenceNo('<SEQUENCENAME>', 37)` 取单据编号。
- 如表存在 `AD_CLIENT_ID`，默认值 `37`；如存在 `AD_ORG_ID`，默认值 `27`。
- 子表的 `AD_CLIENT_ID`、`AD_ORG_ID` 默认继承父表。
- 新增表单若存在 `STATUS`、`STATUSERID`、`STATUSTIME`，通常只设置 `STATUS='1'`，不设置提交人和提交时间。
- 生成提交 SQL 或说明提交流程时，如果已知 `userId`，调用 `AD_TABLE.PROC_SUBMIT` 前需要先更新主单据修改人和修改时间，再调用提交存储过程；修改人、修改时间字段名必须先通过 `AD_COLUMN` 或表结构确认，不要凭经验硬写字段名。

## 运维能力速记

当用户说“给我 HENLO 的 Oracle 运维报告 / 数据库日报 / Oracle 巡检”时，使用：

```powershell
python scripts/oracle_skill.py ops_report HENLO
```

当用户说“给我 HENLO 的服务器巡检报告 / 运维体检报告 / 查看最近一次巡检报告”时，使用：

```powershell
python scripts/oracle_skill.py inspection_report HENLO
python scripts/oracle_skill.py inspection_latest HENLO
python scripts/oracle_skill.py inspection_report HENLO --markdown
```

巡检命令成功后默认在 `outputs/` 生成 HTML；需要 Markdown 时增加 `--markdown` 或 `--md`，也可在参数后指定输出路径。

生成新报告前必须先执行 `sys_function_check`。若 `SYS.HENLO_ORA_MONITOR` 和当前 schema 的 `HENLO_ORA_MONITOR` 均不可执行或版本契约不兼容，立即停止采集并返回完整 SYS 函数与授权 SQL；不得先生成部分报告。Skill 必须使用目标 Agent 返回的有效 Oracle schema 自动替换 `<AGENT_SCHEMA>`，直接向用户提供可执行 SQL，不得让用户手工修改占位符；无法确定 schema 时停止并提示检查 Agent 配置。读取既有历史报告不需要重复执行该预检，只有 `inspection_latest --refresh` 需要。

当用户要求“更新客户 Agent / 触发 Agent 升级 / 给某客户发版升级”时，使用：

```powershell
python scripts/oracle_skill.py agent_update HENLO 300
```

`clientCode` 可省略，默认使用当前已切换的 client；`timeout` 默认 300 秒。该命令只触发中转机的 `/api/admin/agent_update/trigger`，实际升级包由 Agent 从 OSS 下载，不再从 transit-server 本机下载。

涉及 `v$`、`dba_`、AWR、SYS 权限视图时，Agent 会优先调用 `SYS.HENLO_ORA_MONITOR`；如果不可用，再尝试当前登录账号下的 `HENLO_ORA_MONITOR`。函数缺失或无权限时，输出安装 SQL，让用户用 SYS 或有视图查询权限的当前账号安装后再试。

AWR 报告只有在客户 DBA 已确认 Diagnostics Pack 授权，且 Agent 配置 `awr.enabled=true`、`awr.license_confirmed=true` 后才可用。日常巡检不会隐式生成 AWR；Skill 只列出或下载 Agent 已生成的 HTML：

```powershell
python scripts/oracle_skill.py awr_status WEIRUI
python scripts/oracle_skill.py awr_list WEIRUI
python scripts/oracle_skill.py awr_download WEIRUI 20260720
```

日志分析默认关闭。用户提供服务器上的单个绝对文本日志路径后，先执行 `log_info`，再按问题选择 `log_tail` 或 `log_search`；默认只扫描末尾 100 MB。日志正文原样返回给当前 Skill 会话但不写入中转审计库：

```powershell
python scripts/oracle_skill.py log_enable AHMW
python scripts/oracle_skill.py log_info "D:\logs\app.log" --client AHMW --json
python scripts/oracle_skill.py log_search "D:\logs\app.log" ERROR ORA- --client AHMW --before 3 --after 3 --json
```

## 内容维护

Git 提交和发布记录使用简洁、准确的中文描述，并按可独立验证的小功能节点分别提交。Bug 修复通常只说明修复的功能点和用户可见结果，不展开代码层缺陷细节；只有排障或防止复发确有需要时才补充技术原因。每次提交避免混入无关修改。

本 skill 的 Git 源地址分为私有主库和公开镜像：

```text
私有主库：https://gitea.momozhua.site/qiangayi/oracle-jump-query
公开镜像：https://gitea.momozhua.site/qiangayi/oracle-jump-query-public
```

日常开发、提交和 Codex Skill 同步使用私有主库。每次将 Skill 推送到私有 Git 后，必须同步更新公开镜像，不再另行等待确认；公开镜像只导入当前私有 `main` 的无历史快照，并在发布前检查敏感文件和测试结果。不要把 `C:\Users\qiang\.codex\skills\oracle-jump-query` 当作长期源码目录；该目录只用于安装后的运行和验证。

整理文档时不得删除既有内容。需要精简主 `SKILL.md` 时，只能把内容移动到 `references/`，并更新索引；确实要删除内容，必须先得到用户明确同意。


## Agent version query

Natural language: query all customer Agent versions, or query HENLO and RENBEN Agent versions.

Commands:
- python scripts/oracle_skill.py version agent HENLO RENBEN --json
- python scripts/oracle_skill.py version agent --all --json

Online Agents return their current version; offline customers return the last heartbeat version and offline status.

## SYS function deployment bundle

Generate all SYS-created functions required by the Skill for a customer Agent schema:

```powershell
python scripts/oracle_skill.py sys_functions BOSNDS3
```

## Skill 更新方式

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
```

The command reads every SQL file under `references/sys-functions/`, replaces `<AGENT_SCHEMA>`, and only outputs SQL for a DBA to execute. It never writes to the customer database. Any future SYS function must be added to that directory so this command includes it automatically.