oracle-jump-query-public/SKILL.md

name, description

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

Oracle 跳板查询

版本：v1.5.47 · 更新日志

使用原则

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

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

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

参考文档

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

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

常用命令

命令均在 skill 目录执行：

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

登录中转机：

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 业务术语、表单、菜单、模块、按钮、状态、字段含义时，优先走元数据，不要靠表名猜测：

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 数据字典与系统地图。

处理单据类表时：

• 先查 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 数据字典与系统地图。

业务规则速记

• 用户提到“通用接口”“接口指令”“接口方”“推送日志”“接收日志”“数据接口任务”“数据队列封装/推送”，或要求分析 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 时，先读取 通用接口业务逻辑。这些对象是常见模型而不是固定契约；不同服务器可能缺表、增表、增减字段、改变值域、请求头合并规则或处理过程，必须先查目标环境再下结论。
• 商品、款号通常指 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 巡检”时，使用：

python scripts/oracle_skill.py ops_report HENLO

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

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 升级 / 给某客户发版升级”时，使用：

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：

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 会话但不写入中转审计库：

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 源地址分为私有主库和公开镜像：

私有主库：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:

python scripts/oracle_skill.py sys_functions BOSNDS3

Skill 更新方式

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

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.