Smart Search Tables（找表 / 找数）

本 skill 定义 固定先后顺序 的找表工具链：先 对象实例检索 锁定表与元数据线索，再 部门职责语义查询 补足治理与责任边界，最后 总结。子工具契约以同名 skill 为准；references/ 提供编排说明、样例与跳转。

OpenClaw：metadata.openclaw.skillKey 为 smart-search-tables。流水线与默认 base_url / tools.*.url_path / kn_id / user_id 见 config.json。

在数据分析员工体系中，本 skill 宜由 smart-data-analysis 总入口完成意图与 KN 编排后再进入执行。

必读 references（按步骤）

步骤	说明	Reference
1	query_object_instance（找表/元数据实例）	references/query-object-instance.md
2	department_duty_query（相关部门职责）	references/department-duty-query.md
—	端到端逻辑与总结要点	references/tool-examples.md

主流程（必须按序）

找表进度：
- [ ] 1. 运行 [scripts/query_object_instance.py](scripts/query_object_instance.py)：在元数据 KN 下检索，得到表/视图候选与部门/主题线索；请求体三层结构见 [references/query-object-instance.md](references/query-object-instance.md)
- [ ] 2. 运行 [scripts/department_duty_query.py](scripts/department_duty_query.py)：根据线索构造职责问句并查询；格式见 [references/department-duty-query.md](references/department-duty-query.md)
- [ ] 3. 总结：必须展示候选表（以表业务名 `business_name` 为主、完整全称；并补充表技术名 `technical_name`）；**有则**补充职责要点。若第 2 步失败（如 HTTP **404**，多与职责侧 `kn_id` 与环境不一致），简短说明即可，**仍以第 1 步结果为主要交付**；不暴露 token 与完整调试 URL

进度展示样式（更直观）

状态图例：

• [✓] 已完成
• [ ] 待执行
• [✗] 失败并终止
• [−] 约定可跳过（仅用于第 2 步 404 例外）

minimal（多轮压缩）：

找表进度：1✓ -> 2✓ -> 3✓

standard（默认，推荐）：

### 找表执行进度
- [✓] 1 对象检索：query_object_instance 已返回候选表/视图
- [ ] 2 职责查询：待执行 department_duty_query
- [ ] 3 结果汇总：待输出候选表 + 职责 + 下一步

第 2 步命中 404 例外时，推荐这样回显（保持直观且不误导）：

### 找表执行进度
- [✓] 1 对象检索：已完成
- [−] 2 职责查询：HTTP 404（职责侧 kn_id/环境不一致），按规则跳过
- [✓] 3 结果汇总：已基于第 1 步结果完成交付

阶段进度汇报（硬约束）

• 流程门禁：主流程 1→2→3 中，每一阶段结束后必须先向用户展示该阶段结果/进度，再进入下一阶段；除下文「职责查询失败（如 404）仍进入总结」这一明示例外外，任一阶段失败则终止，不得调用下一阶段脚本或输出“下一阶段已完成”的假象结论。
• 职责查询失败例外：仅当第 2 步 department_duty_query 失败且属于本 skill 已约定的 HTTP 404（职责侧 kn_id / 环境不一致等） 场景时，允许进入第 3 步总结，并必须以第 1 步检索结果为主交付；其他失败（含第 1 步检索失败/无可用候选）不得进入第 2 步或第 3 步。

脚本查询（强制）

两步 必须使用本目录提供的脚本 完成调用：scripts/query_object_instance.py、scripts/department_duty_query.py。默认 URL / kn_id 等与 config.json 及脚本一致，字段细节以 references/ 为准。禁止在本 skill 内新建 _tmp_*.py / _tmp_*.sh 等临时代码作为 HTTP 请求入口。

在 PowerShell 中执行 Python 时，一律使用脚本的完整路径，不要依赖当前工作目录；同一条命令行里串联多个操作时，请使用分号（;）分隔，例如：cd C:\path\to\repo; python C:\path\to\script.py ...。

第 1 步：query_object_instance

• 脚本：scripts/query_object_instance.py
• 认证：--token / -t 或位置参数；否则由脚本内部使用 QOI_TOKEN 和 kweaver token 主动获取
• 检索词：--search / -s 或第 2 个位置参数（默认 企业）
• 必填参数：
  • --base-url / -b：平台网关 base_url，可通过 kweaver auth whoami 的 Issuer 字段获取
  • --account-id / -a：请求头 x-account-id，可通过 kweaver auth whoami 的 User ID 字段获取
• 常用可选：--kn-id、--ot-id、--limit、--url-path、--x-business-domain、--insecure、--timeout、--out
• 说明：脚本内 need_total 为 false；kn_id 须为元数据网且符合 SOUL.md。

第 2 步：department_duty_query

• 脚本：scripts/department_duty_query.py
• 认证：--token / -t 或位置参数；否则由脚本内部使用 DDQ_TOKEN 和 kweaver token 主动获取
• 必填参数：
  • --base-url / -b：平台网关 base_url，可通过 kweaver auth whoami 的 Issuer 字段获取
• 问句：--query / -q 或第 2 个位置参数（未给则用脚本内默认长句）
• 注意：请求 JSON 内 kn_id 当前固定 menu_kg_dept_infosystem_duty，--kn-id 未写入 body。脚本会先向 stdout 打印请求体再发请求，联调时注意区分输出。
• 404：不阻断第 1 步表/视图结论，见「步骤约束」。

临时文件清理（成功后）

本 skill 在调用子能力时，允许在“本机任务目录”创建临时脚本（用于组织请求 JSON/发起 HTTP）与临时数据文件（如 _tmp_*.json / _tmp_*.ndjson）；MUST NOT 将临时文件落在仓库 skills/ 及其任意子目录下，若仓库内另有 .claude/skills/ 等 skill 同步树亦同。宜 使用工作区根目录、系统临时目录等与上述路径隔离的位置。为减少磁盘残留，本 skill 增加清理门禁：

• MUST：当且仅当本轮流程成功完成到“总结（第 3 步）”并输出最终回复后，删除本轮创建的临时脚本文件。
• MUST：仅删除满足以下规则的文件名模式：以 _tmp_ 开头，后缀为 .py / .sh / .ps1（大小写不敏感也视为匹配）。
• MUST：当且仅当本轮流程成功完成到“总结（第 3 步）”并输出最终回复后，删除本轮创建的临时数据文件（以 _tmp_ 开头、后缀为 .json / .ndjson，大小写不敏感也视为匹配）。
• MUST：绝对不删除仓库中的任何 *_request_example* 样例脚本，或用户非本轮创建的临时文件。
• MUST：若流程在任一步骤发生异常并提前终止，则不删除临时脚本与临时数据（保留用于排查）；在异常回执中可提示“临时文件已保留”。
• MUST：若用户明确要求“保留调试文件/导出详情/展开详情”，则不删除相关临时脚本与临时数据。

严格限定（找数场景）

• 来源强约束：找表链路使用的知识网络（kn_id_find_table、query_object_instance.query.kn_id）必须来自 SOUL.md 已配置知识网络。
• 缺失处理：若 SOUL.md 缺失或未配置可用知识网络，必须先提醒用户配置 SOUL.md，并暂停第 1 步检索。
• 找数必须使用元数据知识网络：当用户目标是“找数/找表/找字段/定位资产”时，第 1 步 query_object_instance 的 query.kn_id 只能为元数据知识网络。
• 无元数据 KN 不得执行检索：若当前上下文未提供元数据 KN（或 kn_id 不明确/不在元数据候选中），必须先向用户确认「请提供或确认元数据知识网络 kn_id」；确认前不得继续第 1 步。
• 口径冲突时优先安全：若用户给出的 kn_id 与元数据用途不匹配，先提示并二次确认；未确认前停止执行。

步骤约束（摘要）

1. 双 KN：第 1 步 tools.query_object_instance.kn_id（常为元数据网，须写入请求 JSON 的 query.kn_id）；第 2 步 tools.department_duty_query.kn_id（常为职责网，如 duty）。禁止混用未经验证的 kn_id。
   • 上述 kn_id 均须来自 SOUL.md 配置；未配置不得调用。
2. tool-box URL：若 endpoint 含 agent-operator-integration/v1/tool-box/，第 1 步 POST 体必须为 body + query + header 结构（见 query-object-instance reference）；include_logic_params / include_type_info 用 JSON 布尔 false。
3. 第 2 步的职责 query 必须能由第 1 步结果 派生；若第 1 步无部门线索，则用用户原问题中的部门/组织词，或 简要反问 后再调职责查询。若职责脚本/接口返回 404 等错误，仍须完整交付第 1 步的表/视图结论，并简短说明职责步骤未成功（常见为职责 kn_id 与环境不一致）。
4. 总结 中区分：事实发现（检索到的表）与 治理描述（职责库中的条文）；二者无法强绑定时如实说明。最终结果中，候选表输出必须包含表技术名 technical_name 与表业务名 business_name（若缺失则标注“暂无”）；展示时以 business_name 为主，且必须使用完整全称，禁止截断、省略或缩写。
5. 映射约定：在 query_object_instance 结果中，视图与表按同等关系处理；view_tech_name 等价于 table_tech_name（可归并为 technical_name），view_business_name 等价于 table_business_name（可归并为 business_name）。
6. 禁止创建临时脚本作为入口：本 skill 不得新建 _tmp_*.py / _tmp_*.sh 等临时文件作为 HTTP 请求入口；所有调用必须通过现有脚本或等价内嵌请求逻辑完成。

与 smart-data-analysis 的关系

由 smart-data-analysis 路由到本 skill 时，主意图为 找表/定位；若上下文已有 kn_id_find_table，仅当其可确认是元数据知识网络时，才可用于第 1 步 query_object_instance 的 kn_id。

若 kn_id_find_table 缺失、无法确认或与元数据用途冲突，必须先向用户确认元数据知识网络 kn_id，确认前不得执行第 1 步检索。

用户后续要 指标与 SQL 取数 → 转 smart-ask-data。

配置

• 统一默认：config.json
  • defaults：user_id、x_business_domain
  • base_url：平台网关域名；完整网关 URL 约定为 base_url + tools.<tool>.url_path
  • tools：默认两步流程使用 query_object_instance、department_duty_query；另外可选子工具包括 custom_search_strategy、datasource_rerank（不加入本 skill pipeline）。各工具均以 url_path、kn_id、user_id 为主要配置；若 url_path 含 agent-operator-integration/v1/tool-box/，第 1 步须按 references/query-object-instance.md 组装 body + query（含 kn_id/ot_id/布尔开关）+ header（x-account-id/x-account-type）；默认值见 default_query、envelope_header
  • pipeline：每步 defaults_key 映射到 tools 中的键

调用示例

/smart-search-tables 采购订单相关宽表在哪个库、叫什么，谁在数据治理里负责？
/smart-search-tables 销售域 KPI 用哪张汇总表，对应部门职责怎么说