Xdjz Smart Data Query

---
name: xdjz-smart-data-query
display_name: 智能查数
display_name_en: Smart Data Query
description: >-
  智能查数。用户用日常口语提问具体业务数据，系统自动查询并返回数值结果。
  涵盖销售、采购、库存、财务等数据查询。适用于"是多少""有多少""多少"等事实性提问。
  触发词：查数、查一下、帮我查、本月XX多少、今年利润是多少。
description_zh: 一句话智能查询销售、采购、库存与资金等经营数据，秒翻表格，决策更快。
description_en: Query sales, purchasing, inventory, profit, receivables, and payables with natural language.
category: business
version: 1.5.3
author: 金蝶
when_to_use:
  - 用户询问具体的业务数据数值（销售额、库存、利润、应收款等）
  - 用户用"是多少""有多少""多少""具体数字"等事实性表述提问
  - '触发词：查一下本月销售额、库存还有多少、今年利润是多少、帮我查个数据、应收账款多少'
when_not_to_use:
  - 用户用“怎么样”“好不好”“为什么”“分析”等评价性/分析性表述提问 → 不属于本技能，告知用户本能力只查具体数值，并引导改用「电商经营分析与诊断」
  - 查数请求带分析、建议意图（统计销量排行榜找问题商品、结合销量给补货建议、计算库存周转/缺货风险并分类推荐等）→ 不属于本技能，**禁止回复“不支持/无法处理”**，引导改用「电商经营分析与诊断」
  - 创建正式ERP单据（采购订单、销售单等）→ 不支持，直接告知用户
  - 快速记账 → 不支持，直接告知用户
  - 企业风险分析 → 不支持，直接告知用户
mcp_servers:
  - xdjz
allowed-tools:
  - kingbot_chat
  - search_plugins
  - suggest_plugin_install
---

## [硬规则 0] 小蝶记账连接器检查与「打开连接器」（最高优先级，最先执行）

本 Skill 的全部能力都由「小蝶记账」连接器提供。识别到数据查询意图后，**第一件事是确认连接器已连接**，确认通过后才允许调用服务。

### 一、判断连接器是否已连接

- 本 Skill 声明的服务可正常调用、调用不返回授权类错误 → 视为**已连接**，直接进入「工具调用规范」流程。
- 服务不存在、调用返回未授权 / 未登录 / 凭证失效 / 连接失效等错误 → 视为**未连接**，执行下方「打开连接器流程」。

### 二、打开连接器流程（未连接时的唯一动作）

未连接时**不得调用服务**，也不得用文字解释「MCP」「Token」「服务地址」「接口」等技术细节。

#### 1. 呈现连接器授权卡片（必须首选，禁止只用文字引导代替）

用下面这套**固定的工具调用顺序**把「小蝶记账」的连接卡片内联呈现到本次回复中，用户点卡片上的「连接」即可完成授权：

```
第一步：调用 search_plugins
        参数：type = "connector"
              keywords = ["小蝶记账", "金蝶", "记账"]
第二步：从返回结果中找到「小蝶记账」，取其 id（通常为 kingbot-xiaodie，以实际返回为准）
第三步：调用 suggest_plugin_install
        参数：type = "connector"
              pluginId1 = <第二步取得的 id>
              contextLabel = "连接小蝶记账后继续数据查询"
```

执行约束：

- `search_plugins`、`suggest_plugin_install` 是平台内置工具，**直接调用即可**；禁止用网络搜索代替，禁止推荐任何其他连接器。
- `search_plugins` 调用时 `type` 与 `keywords` **两个参数必须同时传入，缺一不可**；禁止只传 type 漏传 keywords。
- **未从 `search_plugins` 返回结果中取得「小蝶记账」的 id 前，禁止调用 `suggest_plugin_install`**；返回结果中找不到「小蝶记账」时走下方文字兜底。
- `suggest_plugin_install` **同一轮只允许调用一次**；卡片发出后即停止动作，等用户在卡片上点「连接」，不要继续追问。
- 若平台对呈现卡片弹出确认/授权提示，用一句话请用户点「允许」，卡片即可显示。
- 卡片已呈现时，本轮不再输出长篇文字指引（一句话说明“请在上方卡片点「连接」”即可）。

#### 2. 文字兜底（仅当卡片工具不可用或调用失败时）

仅当 `search_plugins` / `suggest_plugin_install` 不存在、被禁用或调用报错时，才退回一句话指路：

> 这个操作需要先连接「小蝶记账」连接器：请打开「连接器」面板，找到「小蝶记账」，点击「连接」完成授权，完成后回复我一声，我马上帮你查询数据。

#### 3. 用户回复已连接后

重新从本节第 1 步开始走一次完整流程（不要复用授权失败前的输入与判断），授权通过后继续处理。

### 三、授权失败或凭证失效

按「打开连接器流程」重新引导用户连接或重新授权，提示语与未连接时一致，不暴露技术细节。同一轮对话内最多提示一次，用户未处理则等待用户回应，不重复弹窗打扰。

### 四、禁止事项

- 禁止在未连接状态下把查询结果编造给用户，或假装查询成功。
- 禁止因连接器未连接而改口说“我不支持数据查询”——应引导完成连接后继续。
- **禁止在卡片工具可用时偷懒只用文字引导**——文字兜底只允许在卡片工具不可用/调用失败时使用。
- 禁止展示 Token、服务地址、连接器内部标识、授权链路等技术信息。

---

## [硬规则 1] 用户可见性规则（最高优先级，覆盖所有章节）

执行细节与用户输出**严格分离**。以下内容**仅用于内部执行**，**禁止**出现在任何对用户的回复中：

- 工具名：如 `kingbot_chat`、MCP、stellar 等
- 参数名：如 `title`、`input`、`variables`、`messageType`、`agent_id`、`skills`、`source_agent_id`、`source_agent_name`、`source_skill_id`、`source_skill_name`、`source_type` 等
- 后端标识：如 `OrchestratorAgent`、`agent_id`、`sid`、`deviceId`、`SendCursor`、`uuid` 等
- 对话 ID / 会话 ID 等技术标识
- **查询 SQL**：服务返回内容中的完整 SQL 语句（`SELECT ... FROM ... WHERE ...` 等）及其代码块，属于内部实现细节，必须过滤（详见「结果处理 → SQL 过滤规则」）
- **tipsjson 技术痕迹**：`tipsjson` 标记与 JSON 原文（花括号、字段名、转义符等）禁止透传，须解析转换后以业务提示展示（详见「结果处理 → tipsjson 展示规则」）

仅向用户展示：查询结果的业务语义信息（数据指标、金额、数量、对比、趋势等）、系统返回的警告/错误原文、操作最终结果。

### 用户输出示例对照

❌ BAD（暴露技术细节）：
> 已调用 kingbot_chat 工具，title="新对话"，input="本月销售额多少"，agent_id=OrchestratorAgent，查询成功。

✅ GOOD（业务语义）：
> 本月销售额查询结果：累计销售额 128,500 元，较上月增长 12.3%。

---

## 业务范围

本 Skill 专注**自然语言查数**，用户用日常口语提问业务数据，系统自动查询并返回结果。

**适用场景**：
- 销售数据查询："本月销售额多少"、"这周卖了多少"、"客户张三的欠款是多少"
- 采购数据查询："这个月采购了多少"、"供应商应付账款多少"
- 库存数据查询："某商品库存还有多少"、"仓库里还剩什么"
- 财务数据查询："今年利润是多少"、"本月支出多少"、"应收账款还有多少"
- 多维度查询："本月各产品线销售额分别是多少"

**意图路由规则**：

| 语言特征 | 路由 | 示例 |
|---------|------|------|
| 是多少 / 有多少 / 多少 | → 查数 | "今年利润是多少" |
| 查一下 / 帮我查 / 查个 | → 查数 | "帮我查一下本月销售额" |
| 具体数字 / 具体金额 | → 查数 | "利润具体数字是多少" |
| 统计 / 排行榜 / TOP榜 + 找问题 / 挑主推款 | → 经营分析 | "统计本月商品销量排行榜，找卖得多没赚钱的" |
| 查询 / 查 / 统计 + 建议 / 推荐 / 补货 / 该不该 | → 经营分析 | "查当前库存，结合销量给我补货建议" |
| 计算指标（周转天数 / 缺货风险 / 平均日销量）+ 分类 / 推荐 | → 经营分析 | "算库存周转天数，给我最该补货的3款" |
| 怎么样 / 好不好 / 为什么 | → 经营分析 | "今年利润怎么样" |
| 分析 / 趋势 / 对比 | → 经营分析 | "分析一下经营状况" |
| 评估 / 解读 / 原因 | → 经营分析 | "利润率为什么下降" |

> 路由原则（强制）：**带分析、建议意图的查数请求走经营分析**——即使表述含"统计""查询""查一下""排行榜"，只要落点是排行找问题、给建议/推荐、算指标做分类决策，就走「电商经营分析与诊断」；仅要具体数值的才走查数。

**不包含**：
- 经营分析（评价性提问）→ 不属于本技能，告知用户本能力只查具体数值，并引导改用经营分析能力
- 带分析、建议意图的查数（统计排行榜找问题商品、结合销量给补货建议、计算库存周转与缺货风险并分类推荐等）→ 引导改用「电商经营分析与诊断」，本技能不承接
- 创建正式 ERP 单据（采购订单/入库单/销售单等）→ 不支持，直接告知用户
- 快速记账 → 不支持，直接告知用户
- 企业风险分析 → 不支持，直接告知用户
- 修改或删除已有数据 → 不支持，直接告知用户

---

## 操作授权

| 操作场景 | 自动执行 | 条件 |
|---------|---------|------|
| 自然语言查数 | ✅ 自动 | 用户提供数据查询需求时 |

---

## 工具调用规范

### 工具：kingbot_chat

创建对话并发送用户消息，同步等待 AI 回复。

**参数说明**：

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| title | string | 是 | 对话标题，固定使用 `"新对话"` |
| input | string | 是 | 发送给服务的消息内容，默认使用用户原话；仅允许做最小必要改写，不得扩展用户未明确表达的查询范围 |
| sid | string | 是 | 当前轮次的会话 ID，按「调用要点」规则取值后原样传入 |
| variables | object | 是 | 对话变量，需填充 messageType=Message、agent_id=OrchestratorAgent、skills=report-data-query-guide-v2，以及来源参数 source_agent_id=""、source_agent_name=""、source_skill_id=xdjz-smart-data-query、source_skill_name=智能查数、source_type=workbuddy |

**调用要点**：
- `input` **默认使用用户原话**：只有主 Agent 对话上下文中存在明确、可引用的信息，且用户当前问题包含指代或省略时，才允许基于该上下文做最小必要改写；如果没有主 Agent 对话上下文信息，必须原样传递用户问题，不得改写
- `sid` **必须传入**当前轮次的会话 ID；取值方式：Windows 端取 `~/.workbuddy/workspace/sessions/` 下与当前工作目录创建时刻对应的 UUID 目录名（注意：工作目录名本身是时间戳，不是 UUID，不可直接用作 sid），原样传入；其他端该目录位置不一定相同；若不存在该目录，由你自行寻找会话 ID（可依据会话上下文、本机会话记录等线索，如 `~/.workbuddy/sessions/*.json` 中 cwd 匹配记录的 sessionId）；确实无法确定时，自行随机生成一个 UUID 作为 sid 传入，且当前轮次内保持一致（同一轮次的多次调用复用同一个随机 UUID，不得中途更换）
- `title` 固定为 `"新对话"`，用户不可见
- `variables` 必须传入，格式如下：

```json
{
  "messageType": "Message",
  "agent_id": "OrchestratorAgent",
  "skills": "report-data-query-guide-v2",
  "source_agent_id": "",
  "source_agent_name": "",
  "source_skill_id": "xdjz-smart-data-query",
  "source_skill_name": "智能查数",
  "source_type": "workbuddy"
}
```

### input 改写边界

**保守原则**：改写只能依据**主 Agent 对话上下文**中已经明确出现的信息。第一轮对话或主 Agent 未提供可引用上下文时，必须原样传递用户问题；不得为了提升查询完整性而主动补充用户未说出的年份、月份、组织、口径或查询维度。

| 用户原话特征 | 正确处理 | 禁止处理 |
|-------------|---------|---------|
| 无主 Agent 对话上下文，或上下文未提供确定条件 | 原样传递用户问题 | 改写、扩写、补充年份、月份、组织、口径或查询维度 |
| “第二季度”“上半年”“本月”等相对时间 | 保留原始表达；只有主 Agent 上下文明确年份/期间时，才可补入该上下文信息 | 根据系统时间或常识默认补成当前年份、具体月份或具体日期范围 |
| “红色”“绿色”等颜色、样式或界面可见描述 | 保留用户使用的原词，不转换、不解释 | 将颜色词补全为“红色标记”、标签、状态、异常等用户未说明的含义 |
| 商品名称、属性、编码、规格、型号、物料等业务实体信息 | 仅当主 Agent 上下文中明确出现对应信息且当前问题存在指代或省略时，才按上下文原样补全 | 根据常识、字段名、颜色、编码片段或系统猜测补全、替换、标准化商品名称、属性或编码 |
| “成本数据”“销售数据”等开放查询对象 | 保留用户提出的对象和动作 | 自动添加明细维度、汇总口径、同比、环比等用户未提及的查询维度 |
| 后续对话存在明确主 Agent 上下文 | 只补全主 Agent 上下文中已经出现且确定的信息 | 补充主 Agent 上下文没有出现的新条件 |

**示例**：

| 用户原话 | 发送给服务的 input |
|---------|-------------------|
| “查一下第二季度的成本数据” | “查一下第二季度的成本数据” |
| “查一下2025年，不同编码 红色的每月成本数据” | “查一下2025年，不同编码 红色的每月成本数据” |
| “查一下2026年第二季度成本明细” | “查一下2026年第二季度成本明细” |
| “继续查第二季度”且主 Agent 上文明确对象为成本数据 | “继续查询第二季度的成本数据” |

**禁止示例**：
- 禁止在没有主 Agent 对话上下文时改写用户问题
- 禁止将“查一下第二季度的成本数据”改写为“查询2026年第二季度（4月、5月、6月）的成本数据，并按成本构成、趋势变化和与第一季度环比对比展示”
- 禁止把“第二季度”默认解释为“2026年第二季度”
- 禁止把“红色”改写为“红色标记”
- 禁止把商品名称、属性、编码、规格、型号、物料等信息扩展为主 Agent 上下文未明确出现的内容
- 禁止把“成本数据”默认扩展为“成本明细 + 趋势 + 环比”

**最小调用示例**（内部参考，不展示给用户）：

```json
{
  "title": "新对话",
  "input": "本月销售额是多少？",
  "sid": "<按「调用要点」规则取得的会话ID>",
  "variables": {
    "messageType": "Message",
    "agent_id": "OrchestratorAgent",
    "skills": "report-data-query-guide-v2",
    "source_agent_id": "",
    "source_agent_name": "",
    "source_skill_id": "xdjz-smart-data-query",
    "source_skill_name": "智能查数",
    "source_type": "workbuddy"
  }
}
```

---

## 结果处理

kingbot_chat 返回对话 ID 和 AI 回复内容。处理方式：

### 成功查询

| 展示内容 | 说明 |
|---------|------|
| 查询结果摘要 | 数据指标、金额、数量、对比等（从 AI 回复中提取） |
| 数据明细 | 如 AI 回复中包含明细列表则展示（超过 20 条时仅展示前 20 条，完整明细生成 Excel 文件） |

**展示要点**：
- 以简洁的业务语义展示查询结果，不暴露对话 ID、工具名等
- 如果 AI 回复包含表格或列表，按原格式展示
- 如果 AI 回复包含确认提示或要求补充信息，原样转达给用户
- 同一数值/信息只输出一次，禁止在不同段落或表格中重复展示
- **展示、生成文件前必须先按下方【数值真实性规则】【SQL 过滤规则】【tipsjson 展示规则】处理返回内容**

### 数值真实性规则（强制）

对用户展示的每一个数值（金额、数量、比例、日期等）都必须**逐字来自服务返回内容**：

- 禁止估算、推算、四舍五入或自行加工：不得在服务返回之外自行计算合计、增长率、平均值、汇总数等
- 服务未返回数值、查询结果为空 → 如实告知用户“未查询到相关数据”，**禁止编造、填充或举例任何数字**
- 未收到明确的查询结果前，禁止以任何形式向用户呈现“查询结果”或宣称查询成功

### SQL 过滤规则（强制）

服务返回内容中可能包含完整的查询 SQL（如 `SELECT ... FROM ... WHERE ...` 语句、以 sql 标记的围栏代码块等），属于服务内部实现细节，**必须全部过滤删除**，禁止出现在对用户的任何回复或生成的任何文件中。

过滤规则：
- 命中 SQL 语句（由 SELECT / FROM / WHERE / JOIN / GROUP BY / ORDER BY 等关键字构成的语句，含围栏代码块标记）→ **整段删除**，不做改写、不做替换说明
- 过滤必须在**展示、生成产物之前**完成：对话回复、Excel 文件等所有产物中均不得包含 SQL
- 删除后仅保留查询结果的业务信息（数据指标、金额、数量、对比等）
- 禁止复述、转述、概括、引用 SQL 内容；禁止把 SQL 改写为"查询逻辑/统计口径是……"等形态输出
- 禁止向用户解释"已屏蔽 SQL 内容"，静默过滤即可

❌ BAD（原样透传）：
> 本月销售额查询结果：累计销售额 128,500 元。
> 查询语句：SELECT SUM(amount) FROM sale_order WHERE order_date BETWEEN ...

✅ GOOD（过滤后输出）：
> 本月销售额查询结果：累计销售额 128,500 元，较上月增长 12.3%。

### tipsjson 展示规则（强制）

服务返回内容中可能出现 `tipsjson` 形式的提示数据（如 `{"content":"**计算口径**：..."}`，可能含 `\"`、`\n` 等转义），**禁止原样透传 JSON 文本或“tipsjson”标记**，必须解析转换后以业务提示方式展示：

转换与展示要求：
- 识别形态：独立的 `tipsjson` 标记及其后的 JSON 对象（含 `content` 字段）→ 提取 `content` 字段的值作为展示文本
- 展示方式：解析出的内容作为**业务提示语**（如计算口径说明）以引用样式（如引用块）单独展示，与结果正文区分
- `content` 中的 Markdown 标记正常渲染（如 `**计算口径**` 渲染为加粗文本），不得连同标记符号原样吐出
- 禁止展示“tipsjson”字样、JSON 花括号、字段名（content）、转义符（\"、\n 等）等任何 JSON 技术痕迹
- 存在多处 tipsjson → 逐条提取、依次展示
- 若 JSON 无法解析 → 仅提取其中可读的中文文本展示，仍不得透传 JSON 原文

❌ BAD（原样透传）：
> tipsjson
> {"content":"**计算口径**：销售额=已审核销货单销售金额-已审核销货退货单销售金额（净额口径，已扣减退货）"}

✅ GOOD（转换后展示）：
> **计算口径**：销售额=已审核销货单销售金额-已审核销货退货单销售金额（净额口径，已扣减退货）

### 结果展示示例

> 本月销售额查询结果：
>
> 累计销售额：128,500 元
> 较上月：+12.3%
>
> 数据已更新。

### 明细数据量控制（超过 20 条）

当查询结果包含明细数据列表时，按数据量分别处理：

| 明细数据量 | 处理方式 |
|-----------|---------|
| ≤ 20 条 | 对话中完整展示全部明细 |
| > 20 条 | 对话中仅展示前 20 条明细，同时将**完整明细数据**生成 Excel 文件（.xlsx），并告知用户文件位置 |

**要求**：
- Excel 中必须包含**完整的明细数据**（不止 20 条），字段与查询结果一致，禁止编造、省略数据
- Excel 中不得包含 SQL 语句等内部实现细节（见【SQL 过滤规则】）
- Excel 的具体实现（文件命名、存放路径、样式等）不设限制，由主 Agent 自行实现；建议文件名包含查询主题与时间戳，如 `销售明细-20260813-153000.xlsx`
- 对话中展示前 20 条后，需明确提示用户完整数据总条数及 Excel 文件位置

**用户告知方式**（业务语义，不暴露技术细节）：

> 本次查询共 86 条明细，以上展示前 20 条。完整明细已生成 Excel 文件：`销售明细-20260813-153000.xlsx`，打开即可查看全部数据。

### 异常处理

| 场景 | 处理方式 |
|------|---------|
| AI 回复为空 | 告知用户"查数服务暂时无响应，请稍后重试" |
| AI 回复包含错误信息 | 原样展示错误提示，不暴露技术细节 |
| AI 回复要求补充信息 | 原样转达（如"请指定查询的时间范围"），等待用户补充后重新调用 |

---

## 执行流程

```
1. 意图识别
   ├─ 确认用户意图为查询业务数据（而非创建单据/记账/风险分析）
   ├─ 命中意图路由表「→ 经营分析」行（带分析/建议意图）→ **禁止回复“不支持”**，禁止调用查数服务硬做，引导改用「电商经营分析与诊断」
   ├─ 排除场景：含“创建/新增/记账/风险评估”等 → 直接告知不支持
   └─ 确认用户提供了查询需求描述

2. 输入校验
   ├─ 用户输入为空或仅含"查数"等无意义词 → 询问"请描述您要查询的数据，例如：本月销售额多少"
   └─ 用户输入有效 → 进入步骤 3

3. 调用查数服务
   ├─ input = 用户原话或基于主 Agent 对话上下文的最小必要改写（无上下文时禁止改写；禁止补充用户未明确表达的年份、月份拆分、查询维度等）
   ├─ sid = 按调用要点规则取得的会话 ID（必填；确实无法确定时随机生成一个 UUID，当前轮次内保持一致）
   ├─ title = "新对话"
   └─ variables = {messageType=Message, agent_id=OrchestratorAgent, skills=report-data-query-guide-v2, source_agent_id="", source_agent_name="", source_skill_id=xdjz-smart-data-query, source_skill_name=智能查数, source_type=workbuddy}

4. 结果展示
   ├─ 成功 → 先按【数值真实性规则】核对数值来源、按【SQL 过滤规则】删除 SQL 语句、按【tipsjson 展示规则】转换提示数据，再按业务语义展示查询结果
   │   └─ 明细数据超过 20 条 → 仅展示前 20 条，完整明细生成 Excel 文件（文件中同样不得包含 SQL）并告知用户文件位置
   ├─ AI 要求补充信息 → 原样转达，等待用户补充后重新调用
   └─ 异常 → 展示错误提示，建议重试
```

---

## 常见问题

**Q1: 用户只说"查个数"没有具体内容怎么办？**
→ 询问用户："请描述您要查询的数据，例如：本月销售额多少、库存还有多少。"

**Q2: 用户要求创建单据怎么办？**
→ 直接告知不支持该操作。

**Q3: 用户要求经营分析、或查数请求带分析/建议意图怎么办？**
→ 均不属于本技能：评价性/分析性提问直接告知不支持并引导改用经营分析能力；带分析、建议意图的查数请求（如"统计本月销量排行榜，找卖得多没赚钱的""结合销量给我补货建议""算库存周转天数，给我最该补货的3款"）引导改用「电商经营分析与诊断」。

**Q4: 用户要求修改数据怎么办？**
→ 直接告知不支持该操作。

**Q5: 查询结果为空怎么办？**
→ 如实告知用户未查询到相关数据，建议检查查询条件或更换关键词后重试。

**Q6: 查询结果明细超过 20 条怎么处理？**
→ 对话中默认展示前 20 条明细，完整明细数据自动生成 Excel 文件（.xlsx）并告知用户文件位置；20 条及以下直接全部展示。

**Q7: 生成的 Excel 文件数据从哪来？**
→ Excel 中的明细数据全部来自查询结果原文，包含全部明细（不止 20 条），禁止编造、省略或推测数值。

**Q8: 查询服务返回内容中包含 SQL 怎么办？**
→ 必须过滤：SQL 属于内部实现细节，须整段删除且不得改写、不得解释、不得展示给用户；对话回复、Excel 文件等所有产物中均不得包含 SQL（见【SQL 过滤规则】）。

**Q9: 返回内容中出现 tipsjson 怎么办？**
→ 不得原样透传 JSON，提取 content 字段的值作为业务提示语（如计算口径说明）以引用样式单独展示；禁止出现“tipsjson”字样、花括号、字段名、转义符等 JSON 痕迹（见【tipsjson 展示规则】）。