# Xdjz Smart Order Entry

> 小蝶记账-智能录单，面向小微企业及日常收支场景。用户用口语描述收支事项， 系统自动识别并创建记账记录。涵盖采购支出、销售收入、经营费用、日常收支、业务单据（采购订单/销售单等）、 多事项批量录入、修改已记账目（仅支持同一会话内修改）、自然语言金额/项目/分类提取。触发词：极速录单、记一笔、帮我记账、记个账、记错了、改一下账、开个单。

- Skill: `ahang1598/xdjz-smart-order-entry` (Agent Skill)
- Install (CLI): `npx get-skill add ahang1598/xdjz-smart-order-entry`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ahang1598/xdjz-smart-order-entry/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: ahang1598 (https://skillmd.com/u/ahang1598)
- Updated: 2026-11-18
- Page: https://skillmd.com/skills/ahang1598/xdjz-smart-order-entry

---


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

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

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

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

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

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

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

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

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

执行约束：

- `search_plugins`、`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` 等
- 后端标识：如 `OrchestratorAgent`、`agent_id`、`sid`、`deviceId`、`SendCursor`、`uuid` 等
- 对话 ID / 会话 ID 等技术标识

仅向用户展示：记账结果的业务语义信息（收支类型、金额、科目/分类、备注等）、系统返回的警告/错误原文、操作最终结果。

### 用户输出示例对照

❌ BAD（暴露技术细节）：
> 已调用 kingbot_chat 工具，title="新对话"，input="我今天采购了5本笔记本和一盒圆珠笔..."，agent_id=OrchestratorAgent，记账成功。

✅ GOOD（业务语义）：
> 已记账：办公用品支出 120 元（笔记本 x5、圆珠笔 x1盒）。凭证已生成。

---

## [硬规则 2] 禁止主Agent生成与录入测试数据（最高优先级）

本 Skill 产生的都是**真实账目记录**：后端没有"测试模式"，任何一次调用都会真实入账，且已记的账无法删除。

- 录入内容**只能来源于用户明确描述的真实收支事项**（或用户上传单据图片中识别出的真实要素）
- **主 Agent 一律不得自己生成测试数据**：无论用户是否要求、无论出于任何理由（测试、演示、验证功能、给用户举例引导等），都**禁止主 Agent 自行编造任何用户未描述过的账目**（金额、商品、事项、往来单位等）——**生成即违规**，不以"是否已录入系统"为前提
- **禁止主 Agent 将自行编造的"测试数据"/"示例数据"/"演示数据"传入记账服务录入**，包括但不限于：
  - 用户说"测试一下记账"、"随便记一笔试试"时，主动生成示例事项（如"买咖啡15元"）录入
  - 以"演示效果"、"验证功能"、"丰富账本"等任何理由补充用户没有描述过的账目
  - 在改写 input 时把用户的真实事项替换或扩展为编造的示例内容
- 用户要求"测试/演示"时 → **不调用记账服务**，回复用户："每次记账都会真实入账，无法撤销测试记录。请直接告诉我您真实要记的收支事项，例如：今天采购一台笔记本花了2000块。"
- 因已录入的测试数据无法由本 Skill 删除，必须在录入前拦截：宁可多问一句，不可错录一笔

---

## 业务范围

本 Skill 专注**自然语言快速记账**，面向小微企业及个人的日常收支，用户用口语描述收支事项，系统自动识别并生成会计记录。

**适用场景**：
- 采购支出："今天采购了一批原材料，花了8000元"、"付供应商宏远货款2万"
- 销售收入："今天销售产品收入12000元"、"收到客户张三货款5000元"
- 业务单据："开一张采购订单：向宏远采购原材料100件"、"开销售单：卖给张三公司A产品50件，单价200"
- 经营费用："付办公室房租3000"、"水电费800"、"发员工工资15000"、"物流运费500"
- 多事项合并："今天采购原材料8000，运费500，帮我一起记了"
- 带备注/分类："办公室买矿泉水100块，记到办公费"
- 模糊金额："中午吃了个便饭大概三四十块"
- 修改已记账目（仅限本次会话内记录的账目）："把刚才买笔记本那笔改成150块"、"中午那笔打车费记错了，改成35元"
- 日常支出："今天买咖啡花了15块"、"打车30元"、"午饭吃了28"

### 修改规则（重要）

修改已记账目**仅支持同一会话内**的账目，即只能修改**本次对话中通过本 Skill 记录的账目**。用户要求修改历史会话（其他对话）中的账目（如"把昨天那笔改成XX元"、"上次记的那笔金额错了"）时，直接告知不支持跨会话修改，仅支持修改本次会话内记录的账目。

### 能力边界外的处理（一句话引导，不硬做）

| 用户意图 | 处理方式 |
|---------|----------|
| 想用测试数据试记（"帮我测试一下记账"、"随便记一笔试试"） | **不录入任何测试数据**（见硬规则 2），说明每次记账都会真实入账，引导用户描述真实要记的收支事项 |
| 查具体数据数值（"本月销售额多少""库存还有多少"） | 告知本能力只做记账，并引导用户直接问数据查询（如"查一下本月销售额"） |
| 要趋势/对比/经营分析（"这个月经营怎么样"） | 告知本能力只做记账，并引导用户改用经营分析 |
| 要正式会计凭证（需指定科目/借贷方向） | 直接告知不支持 |
| 要查询客户/供应商等基础资料 | 直接告知不支持 |
| 要删除已记的账 | 直接告知不支持（目前仅支持同一会话内修改） |
| 要修改历史会话中的账（如"把昨天那笔改成XX"、"上次那笔记错了"） | 直接告知不支持跨会话修改，仅支持修改本次会话内记录的账目 |

---

## 操作授权

| 操作场景 | 自动执行 | 条件 |
|---------|---------|------|
| 自然语言记账 | ✅ 自动 | 连接器已连接，且用户提供真实收支事项描述（禁止主Agent以测试数据录入） |
| 修改已记账目 | ✅ 自动 | 连接器已连接，且要修改的是**本次会话内**记录的账目，用户明确指出修改内容 |
| 创建业务单据 | ✅ 自动 | 连接器已连接，且用户提供单据要素（如往来单位、商品、数量/金额） |

---

## 工具调用规范

### 工具：kingbot_chat

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

**参数说明**：

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| title | string | 是 | 对话标题，固定使用 `"新对话"` |
| sid | string | 是 | 当前轮次的会话 ID；优先从当前工作目录路径中提取 UUID，路径无 UUID 时取 `~/.workbuddy/sessions/*.json` 中 cwd 匹配记录的 sessionId（详见下文调用要点） |
| input | string | 是 | 经过改写的完整请求内容（见下方【input 改写规范】），确保单轮即可理解 |
| variables | object | 否 | 对话变量，默认已填充 messageType=Message、agent_id=OrchestratorAgent、skills=quick-accounting。无需传入 |

**调用要点**：
- `input` **必须改写为完整、自给自足的请求内容**（详见下方【input 改写规范】），后端为单轮调用，无法获取上下文
- `title` 固定为 `"新对话"`，用户不可见
- `sid` **必须传入**当前轮次的会话 ID，取值优先级如下（不可为空、不可伪造）：
  1. **首选**：从当前工作目录路径中提取 UUID（格式为 `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`），原样传入。
  2. **兜底（路径为时间戳目录时常用）**：若 cwd 形如 `.../WorkBuddy/2026-09-14-14-44-35` 而无 UUID，则读取 `~/.workbuddy/sessions/*.json`，取其中 `cwd` 与当前工作目录一致、`kind` 为 `interactive` 的那条记录的 `sessionId`（该值即真实会话 ID），原样传入。注意：该记录在会话进程重启后会更新为新 pid，取最新一条即可。
  3. 仅当以上两处都无法取得 UUID 时，才告知用户"服务暂时无法获取会话信息，请稍后重试"，**禁止**在无法获取 sid 的情况下发起调用。
- `variables` 默认值已与后端配置一致，**禁止**覆盖 messageType / agent_id / skills 等默认字段；**禁止**传入任何额外参数

### input 改写规范

由于 kingbot_chat 为**单轮无记忆**调用，`input` 必须包含后端完成任务所需的全部信息，不可依赖上下文指代。

**改写原则**：

| 场景 | 改写要求 |
|------|---------|
| 含指代词（"那笔"、"刚才"、"上面"等） | 替换为具体内容（金额/时间/事项描述） |
| 修改已记账目 | 明确写出原账目信息 + 修改内容 |
| 省略商品名/业务主体（"两杯"、"这个"等） | **必须**从上下文中找到具体名称并补入，不可只补数量或金额 |
| 省略商品名称、属性、编码、规格、型号等业务实体信息 | 只能根据上下文中已经明确出现的信息原样补全；上下文未明确提供时先追问 |
| 省略时间 | 根据对话上下文补全 |
| 用户提供单据图片/截图 | 先读取图片内容，把其中可识别的业务要素（往来单位、商品、数量、单价、金额、日期）改写为文字事项描述；关键要素无法识别时，向用户确认后再调用 |
| 多轮追加信息（"再加一笔"等） | 仅将本轮新增内容改写为完整独立描述，**不重复**已记录的事项 |
| 内容已完整无指代 | 可直接使用，无需改写 |

**改写示例**：

| 用户原话 | 改写后的 input |
|---------|--------------|
| "把刚才那笔改成150块" | "把刚才记的笔记本采购（120元）改成150元" |
| "中午那笔记错了，打车应该是35" | "把今天中午记的打车费（30元）修改为35元" |
| "再加一笔，买水5块" | "买水5元，帮我记一笔"（仅补记本次新增，不重复已记录的午饭/打车） |
| "今天买咖啡花了15块" | 内容完整，直接使用 |
| "今天卖了两杯，一共23"（上文提过奶茶） | "今天卖了两杯奶茶，一共23元，帮我记一下"（商品名必须补入） |

**禁止行为**：
- **禁止编造"测试数据"/"示例数据"/"演示数据"进行录入**：input 只能来自用户明确描述的真实收支事项，禁止以"测试"、"演示"、"验证功能"等任何理由自行生成账目（见硬规则 2）
- 禁止凭空捏造上下文中没有的信息（如金额、商品名）
- 禁止根据常识、字段名、颜色、编码片段或系统猜测补全、替换、标准化商品名称、属性、编码、规格、型号等信息
- 禁止只补金额单位而遗漏商品名/业务主体——商品名与金额同等重要，两者均须完整
- 如上下文信息不足以补全指代（如商品名无法从历史中确认），先向用户追问，确认后再调用

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

```json
{
  "title": "新对话",
  "input": "我今天采购了5本笔记本和一盒圆珠笔，花了120元，帮我记一下。",
  "sid": "<当前工作目录路径中提取的UUID>"
}
```

---

## 结果处理

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

### 成功记账

| 展示内容 | 说明 |
|---------|------|
| 记账结果摘要 | 收支类型、金额、科目/分类、备注等（从 AI 回复中提取） |
| 凭证/记录编号 | 如 AI 回复中包含则展示 |

**展示要点**：
- 以简洁的业务语义展示记账结果，不暴露对话 ID、工具名等
- 如果 AI 回复包含多笔记录，按条目列表展示，并给出笔数与合计金额
- 如果 AI 回复包含确认提示（如"是否确认记入餐饮科目？"），原样转达给用户
- 严格执行下方【输出过滤规则】，屏蔽单据详情引导文案

### 输出过滤规则（强制）

AI 回复中如包含引导用户进入单据详情的文案（如"你可以点击【修改/查看】进入单据详情"及其任何变体），**必须整条删除**，禁止出现在对用户的回复中。当前环境不支持打开单据详情页，透传该文案会误导用户。

过滤规则：
- 命中"修改/查看"、"单据详情"等引导文案 → 整句删除，不做改写、不做替换说明
- 删除后仅保留记账结果的业务信息（收支类型、金额、科目/分类、备注等）
- 禁止向用户解释"已屏蔽某提示"，静默过滤即可

❌ BAD（原样透传）：
> 已记账：餐饮支出 10 元。你可以点击【修改/查看】进入单据详情。

✅ GOOD（过滤后输出）：
> 已记账：办公用品支出 120 元 — 笔记本 x5、圆珠笔 x1盒。记录已保存。

### 结果展示示例

> 已记账：
> 1. 办公用品支出 120 元 — 笔记本 x5、圆珠笔 x1盒
>
> 记录已保存。

### 多笔记账示例

> 已记账：
> 1. 餐饮支出 20 元 — 午饭
> 2. 交通支出 15 元 — 打车
> 3. 办公支出 5 元 — 矿泉水
>
> 共 3 笔，合计 40 元。记录已保存。

### 异常处理

| 场景 | 处理方式 |
|------|---------|
| AI 回复为空 | 告知用户"记账服务暂时无响应，请稍后重试" |
| AI 回复包含失败/错误信息（如"无法解析识别结果"） | 原样展示失败提示，不暴露技术细节；**严禁主 Agent 重试**（禁止重新发起录单或修改调用），等用户调整描述后由用户重新发起 |
| AI 回复要求补充信息 | 原样转达（如"请提供具体金额"），等待用户补充后重新调用（由用户驱动） |
| 调用返回未授权/凭证失效 | 执行「硬规则 0」的打开连接器流程，不展示错误原文 |

### 失败禁止重试（强制）

kingbot_chat **每次调用都会真实入账**。当返回失败信息（如"无法解析识别结果"）时：

- **严禁主 Agent 自行重试**：禁止把同一内容原样、改写或拆分后再次发起录单/修改调用；同一笔事项只允许主 Agent 主动发起**一次**调用
- 正确做法：原样展示失败提示，请用户重新描述或调整要记/改的内容后，由用户再次发起
- 唯一例外：AI 回复要求补充信息时，可原样转达，等用户在对话中补充后再调用（属用户驱动，非主 Agent 自动重试）

---

## 执行流程

```
0. 连接器检查（最先执行）
   ├─ 已连接 → 进入步骤 1
   └─ 未连接 / 授权失效 → search_plugins 找「小蝶记账」→ suggest_plugin_install 呈现连接卡片（同一轮一次）
       └─ 卡片工具不可用/调用失败 → 一句话指路（打开「连接器」→ 找「小蝶记账」→ 点「连接」）
       └─ 用户确认已连接后，重新从步骤 1 开始

1. 意图识别
   ├─ 确认用户意图为快速记账、修改已记账目或创建业务单据（采购订单/销售单等）
   ├─ 排除场景：查询报表/具体数据、经营分析、创建正式会计凭证（指定科目/借贷）、删除已记账目、修改历史会话（跨会话）已记账目 → 告知不支持并一句话引导
   └─ 确认用户提供了收支事项或单据的描述（含图片单据的要素转写）

2. 输入校验
   ├─ 用户输入为空或仅含"记账"等无意义词 → 询问"请描述您要记录的收支事项，例如：今天午饭花了20块"
   ├─ 主Agent拟自行生成测试数据，或用户想"测试/演示" → 按硬规则 2 拦截：禁止生成与录入，不调用服务，引导用户提供真实收支事项
   └─ 用户输入有效 → 进入步骤 3

3. 改写 input（关键步骤）
   ├─ 检查是否含指代词或上下文依赖 → 结合对话历史补全为完整表述
   ├─ 如指代信息不足，无法确定具体内容 → 先向用户追问，确认后再继续
   └─ 内容已完整无指代 → 直接使用

4. 调用记账服务
   ├─ input = 改写后的完整请求内容
   ├─ title = "新对话"
   ├─ sid = 从当前工作目录路径中提取的 UUID（必填；路径中无 UUID 时终止并告知用户）
   ├─ variables 不传（使用默认值）
   └─ 同一笔事项仅发起一次调用；返回失败信息时严禁重试（见结果处理「失败禁止重试」）

5. 结果展示
   ├─ 成功 → 按业务语义展示记账结果（先执行输出过滤：删除"修改/查看单据详情"类引导文案）
   ├─ AI 要求补充信息 → 原样转达，等待用户补充后重新调用
   └─ 异常/失败信息 → 原样展示错误提示，禁止主 Agent 重试，请用户调整描述后重新发起
```

---

## 常见问题

**Q1: 用户只说"记一笔"没有具体内容怎么办？**
→ 询问用户："请描述您要记录的收支事项，例如：今天午饭花了20块、收到客户货款5000元。"

**Q2: 用户输入中金额不明确（如"大概三四十块"）怎么办？**
→ 模糊金额本身属于完整信息，可直接保留在 input 中，后端 AI 会处理或要求用户确认。无需额外推断。

**Q3: 用户要求记多笔怎么办？**
→ 将多笔内容合并为一条完整描述传入 input（如"午饭20元、打车15元、买水5元，帮我记账"），后端服务会拆分多笔记录。

**Q4: 用户要求修改已记的账怎么办？**
→ 仅支持修改**本次会话内**记录的账目。若目标账目是当前对话中刚记录的，支持：结合上下文将指代补全后再传入（如用户说"把刚才的改成150块" → 改写为"把刚才记的笔记本采购（120元）改成150元"），按结果处理规则展示修改结果（仍需执行输出过滤规则）。若用户指的是历史会话中的账目（如"昨天那笔"、"上次记的那笔"），直接告知不支持跨会话修改，仅支持修改本次会话内记录的账目。

**Q5: 用户要求删除已记的账怎么办？**
→ 直接告知不支持该操作。

**Q6: 用户想查账/查数据怎么办？**
→ 告知本能力只做记账，并引导用户直接提问查询（如"查一下本月销售额"），由数据查询能力处理。

**Q7: 用户描述的是采购/销售业务怎么办？**
→ 支持。无论记录采购支出/销售收入的账，还是创建采购订单/销售单等业务单据，均忠实传递用户原话给后端服务处理。

**Q8: 提示需要先连接「小蝶记账」怎么办？**
→ 按硬规则 0 的固定顺序调用 `search_plugins` + `suggest_plugin_install` 呈现「小蝶记账」连接卡片（同一轮最多一次）；仅当卡片工具不可用或调用失败时，才用兜底话术指引用户打开「连接器」面板完成连接。授权前不要向用户追问金额、商品等业务细节。

**Q9: 用户上传了单据图片/截图怎么办？**
→ 先读取图片，把可识别的业务要素转写为文字事项描述（如"向宏远供应商采购原材料100件，单价80元，合计8000元"）再传入；关键要素（金额、往来单位、商品）无法识别时先向用户确认。

**Q10: 用户重复发送同一笔事项怎么办？**
→ 若判断为同一笔（金额、事项、时间一致），先向用户确认"这笔刚刚已经记过，需要再记一次吗？"，确认后再调用，避免重复记账。

**Q11: 用户说"帮我测试一下记账功能"，或主Agent想用测试数据演示怎么办？**
→ 禁止主Agent自己生成测试数据，更禁止录入（硬规则 2）。告知用户："每次记账都会真实入账，无法撤销测试记录。请直接告诉我您真实要记的收支事项，例如：今天午饭花了20块。"等用户提供真实事项后再录入。

**Q12: 调用返回失败信息（如"无法解析识别结果"）怎么办？**
→ 原样展示失败提示，**严禁主 Agent 重试**：不要把同一内容原样或改写后再次发起录单/修改。请用户重新描述或调整内容后，由用户再次发起。

