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.54** · [更新日志](./CHANGELOG.md)

## 使用原则

每次开始使用本 Skill（包括仅参考业务知识）时，先执行 `python scripts/oracle_skill.py capabilities --brief --json`。CLI 每次启动记录最后使用时间；按运行电脑本地日期，当天第一次启动自动从当前 `origin/main` 抓取更新并尝试快进安装，成功后自动重新启动当前命令。无需登录即可检测；当天后续启动只记录使用时间。没有使用的日期不启动后台任务。

每个对话只需确定一次目标客户：从用户提供的客户、工单或当前对话上下文解析出明确 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
```

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

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

品小二环境存在已知字符集兼容问题：中文条件直接写成 `LIKE '%中文%'`（或直接把中文写入等值条件）可能返回 0 行。查询该环境的中文值时，优先将中文转换为 Oracle `UNISTR` Unicode 转义，例如“零售单”使用 `LIKE '%' || UNISTR('\96F6\552E\5355') || '%'`；直接返回 0 行时先用该写法重试，不要据此判断没有数据。该规则是品小二的客户级差异；其他 client 若直接中文字面量已验证可用，不必强制改写，但可将 `UNISTR` 作为避免传输编码转换的通用兜底。

## 参考文档

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

- [命令、登录与调用方式](./references/commands-and-auth.md)
  登录、client 切换、CLI 命令、HTTP action、故障排查。
- [生产查询限制与常用业务规则](./references/query-and-business-rules.md)
  生产查询限制、商品/款号/条码/库存规则、BOS 新建表最小结构、业务单据表单默认配置、新增业务记录 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
```

用户提供表名称、且未明确要求绕过 BOS 元数据直接查询物理数据库对象时，先查 `AD_TABLE` 的 `NAME`、`DESCRIPTION`、`REALTABLE_ID`。若 `REALTABLE_ID` 非空，原名称可能只是 BOS 虚拟表，应改查其指向的实际表；若 `AD_TABLE` 未注册该名称，再按数据库表、视图、物化视图的顺序查找。完整 SQL 和判定规则见 [BOS 数据字典与系统地图](./references/bos-metadata.md)。

处理单据类表时：

- 先查 `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)。

## 业务规则速记

- 为 BOS 新建表生成 DDL 时，至少保留 `ID`、`AD_CLIENT_ID`、`AD_ORG_ID`、`OWNERID`、`CREATIONDATE`、`MODIFIERID`、`MODIFIEDDATE`、`ISACTIVE` 八个基础字段及 `ID` 主键；类型、可空性和默认值按 [BOS 新建表最小结构](./references/query-and-business-rules.md#bos-新建表最小结构仅生成-ddl) 模板生成。DDL 只供人工确认执行，不通过 Skill 查询通道执行。
- 新建 BOS 业务单据表单通常包含 `DOCNO`、`STATUS`、`ISACTIVE`、提交时间和提交人，所在表读写规则默认 `AD_TABLE.MASK='MDQSV'`。`DOCNO` 维护单据编号生成器，读写方式为“单据编号”；`STATUS`、`ISACTIVE` 读写方式为“下拉框选项”，选项名称分别为 `STATUS`、`YESNO`，字段翻译器均为 `nds.web.alert.LimitValueAlerter`，默认值分别为 `1`、`Y`。三个字段读写打印规则均为 `0010111111`。完整配置与元数据核实要求见 [业务单据表单默认配置](./references/query-and-business-rules.md#bos-新建业务单据表单默认配置)。
- 用户提到“通用接口”“接口指令”“接口方”“推送日志”“接收日志”“数据接口任务”“数据队列封装/推送”，或要求分析 `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。
- 业务单据的商品明细支持新增、需要在商品新增输入框输入条码录入时，`AD_TABLE.CLASSNAME` 配置为 `nds.schema.AttributeDetailSupportTableImpl`；ASI 字段 `M_ATTRIBUTESETINSTANCE_ID` 的读写规则一般为 `1100000000`，只在新增时可见。明细新增动作和实际字段名先核实，完整规则见 [商品明细的条码新增配置](./references/query-and-business-rules.md#业务单据商品明细的条码新增配置)。
- `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('<表名称>')`。
- 取单号函数为 `Get_SequenceNo('<CODE>', AD_CLIENT_ID)`；默认约定是 `CODE` 取该单据 `DOCNO` 字段对应的 `AD_COLUMN.SEQUENCENAME` 值，第二个参数取单据实际的 `AD_CLIENT_ID`。先核实元数据；配置为空时不猜测 `CODE`，实际业务有特殊规则时按核实结果处理。只生成 SQL 示例，不通过查询通道调用取号函数。
- 取号 `CODE` 的定义在 `AD_SEQUENCE` 表；分析编号规则时，沿 `DOCNO -> AD_COLUMN.SEQUENCENAME -> AD_SEQUENCE` 核实对应定义。
- 如表存在 `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 更新方式

每日检测和使用记录保存在本机 `scripts/update-state.json`，包含 `last_used_at`、`last_checked_at`、`last_check_date`、`status` 及检测到的提交 ID；文件和并发锁均不提交 Git，不保存登录凭证或查询内容。检测失败仍记为当天已尝试，下次使用日再自动检测；可随时执行下面的手动拉取命令重试。自动安装只允许 `main` 分支快进：源码有未提交修改、存在暂存修改、分支分叉或配置冲突时保留本机文件并继续原命令；本机 `config.json`、`scripts/config.json` 保留原内容。网络抓取设有 10 秒超时，提示只输出到 stderr，`--json` 的 stdout 保持可解析。没有 `.git` 的下载目录仍记录使用时间，但需先安装为 Git checkout 才能自动更新。

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.