同步客户绑定与登录恢复优化

references/commands-and-auth.md

@@ -16,16 +16,16 @@ AI Skill → HTTP → Transit Server (:6357) → WebSocket → Agent → Oracle
 
 1. 中转服务已部署并运行（默认地址: https://ts.henlo.net）
 2. Agent 已部署到数据库服务器并连接中转服务
-3. 本地已安装 Python 依赖：`pip install requests`
+3. 本地已安装 Python 依赖：`pip install requests`；可信设备登录另需 `pip install cryptography`
 
 ## 配置
 
-配置文件位于技能目录下：`D:\work\恒诺\长期支持\跳板查询\demo\ai-skill\config.json`
+配置文件位于技能目录下：`scripts/config.json`
 
 ```json
 {
     "transit_url": "https://ts.henlo.net",
-    "server_id": "server-001",
+    "server_id": "",
     "access_token": "",
     "expires_at": ""
 }
@@ -41,6 +41,37 @@ python oracle_skill.py login <secretKey> [clientCode]
 
 同一个 `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` 按需读取。
+
+```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
+```
+
+本机 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` 脚本：
@@ -108,7 +139,7 @@ python scripts/oracle_skill.py
 curl -X POST https://ts.henlo.net/api/query \
   -H "Content-Type: application/json" \
   -d '{
-    "server_id": "server-001",
+    "server_id": "",
     "action": "analyze_procedure",
     "schema": "BOS",
     "name": "M_RETAIL_SUBMIT",
@@ -122,7 +153,7 @@ curl -X POST https://ts.henlo.net/api/query \
 curl -X POST https://ts.henlo.net/api/query \
   -H "Content-Type: application/json" \
   -d '{
-    "server_id": "server-001",
+    "server_id": "",
     "action": "describe_table",
     "schema": "bosnds3",
     "name": "xcx_so",