Kweaver-dip smart-search-tables

install

source · Clone the upstream repo

git clone https://github.com/kweaver-ai/kweaver-dip

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/kweaver-ai/kweaver-dip "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/smart-search-tables" ~/.claude/skills/kweaver-ai-kweaver-dip-smart-search-tables && rm -rf "$T"

manifest: skills/smart-search-tables/SKILL.md

source content

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
```
与元数据用途不匹配，先提示并二次确认；未确认前停止执行。

步骤约束（摘要）

双 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
```
  配置；未配置不得调用。
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
。
第 2 步的职责
query
必须能由第 1 步结果派生；若第 1 步无部门线索，则用用户原问题中的部门/组织词，或 简要反问 后再调职责查询。若职责脚本/接口返回 404 等错误，仍须完整交付第 1 步的表/视图结论，并简短说明职责步骤未成功（常见为职责
```
kn_id
```
与环境不一致）。
总结中区分：事实发现（检索到的表）与 治理描述（职责库中的条文）；二者无法强绑定时如实说明。最终结果中，候选表输出必须包含表技术名
```
technical_name
```
与表业务名
```
business_name
```
（若缺失则标注“暂无”）；展示时以
```
business_name
```
为主，且必须使用完整全称，禁止截断、省略或缩写。
映射约定：在
```
query_object_instance
```
结果中，视图与表按同等关系处理；
```
view_tech_name
```
等价于
```
table_tech_name
```
（可归并为
```
technical_name
```
），
```
view_business_name
```
等价于
```
table_business_name
```
（可归并为
```
business_name
```
）。
禁止创建临时脚本作为入口：本 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 用哪张汇总表，对应部门职责怎么说

Kweaver-dip smart-search-tables

Smart Search Tables（找表 / 找数）

必读 references（按步骤）

主流程（必须按序）

进度展示样式（更直观）

阶段进度汇报（硬约束）

脚本查询（强制）

第 1 步：
`query_object_instance`

第 2 步：
`department_duty_query`

临时文件清理（成功后）

严格限定（找数场景）

步骤约束（摘要）

与 smart-data-analysis 的关系

配置

调用示例

Kweaver-dip smart-search-tables

Smart Search Tables（找表 / 找数）

必读 references（按步骤）

主流程（必须按序）

进度展示样式（更直观）

阶段进度汇报（硬约束）

脚本查询（强制）

第 1 步：query_object_instance

第 2 步：department_duty_query

临时文件清理（成功后）

严格限定（找数场景）

步骤约束（摘要）

与 smart-data-analysis 的关系

配置

调用示例

第 1 步：
`query_object_instance`

第 2 步：
`department_duty_query`