# 如何理解用户问题

## 概述

对用户输入做**润色、纠错、指代消解**，全程保持原意，不增删关键事实。本步负责**理解用户要问什么**，并识别商户角色与 API 版本。

## 原则

- **忠实**：不改变用户要问什么。
- **清晰**：消除歧义，多轮对话补全省略信息。
- **节制**：能推断的不反复追问；不过度改写。

## 多轮：指代消解

当前问题依赖前文时：

- 将「它 / 这个接口 / 上面那种」等还原为具体对象（产品名、接口名、错误现象等）。
- 继承前文已确定的商户角色、API 版本、业务场景，避免答非所问。
- 消解后仍须遵守「保留的技术原文」规则。

## 单轮：润色与纠错

**目标**：把零散、口语、含糊的表述整理成适合检索的规范问句。

- **明确所问**：补全隐含条件，描述清楚「要什么、在什么场景下」。
- **规范用语**：纠正错别字与明显笔误；口语可改为书面语，但不改变技术含义。
- **去冗余**：删掉重复寒暄，保留与问题相关的关键实体与动作。

### 保留的技术原文

润色只整理表述，不改动用户已给出的技术细节。下列片段须**原样保留**（不得改写、替换或「纠正」字面内容，即使看起来像笔误）；仅可在其前后补充说明性文字：

- 官方文档或接口 URL（含文档 `doc_id`）
- 接口路径与 HTTP Method
- 错误码、错误报文片段
- 字段名、参数名、枚举值
- 支付产品名、API 证书等官方术语

## 角色与 API 版本判定

供后续检索收敛范围。**多实体**（券 / 证书 / 密钥等）走知识库使用指南「用户描述模糊时的澄清话术」，与本节无关。

**对比类**（如「V2 和 V3 的分账有什么区别」）本节不适用，用户要对比的各侧全部保留。

判定顺序：**`AGENTS.md` → 用户原文 → 命中路径分布**。前两档能定就停；第三档只看路径落在哪一侧，不精读、不作答。商户身份与 API 版本均**无默认值**，歧义必须停下来问。

1. 读项目根目录 `AGENTS.md`，已记录则直接采用。
2. 否则从用户原文识别：角色对照 `<SKILL目录>/assets/wechatpay-docs-guide.md` 的「角色与文档路径对照」（`mchid`→普通商户、`sp_mchid`→服务商、`brand_id`→品牌商户等）；版本看是否点名 `APIv2` / `APIv3`。
3. 仍无法确定则看命中路径：集中于单一角色或单一版本则按该侧收敛；跨多角色或 `APIv2`/`APIv3` 两侧都有则立即停止，只输出对应话术：

     > 找到了以下角色下的相关文档：[列出命中的角色]。请问您需要全部查看，还是只看某个角色的文档？

     > 找到了 APIv2 和 APIv3 下的相关文档。请问您需要全部查看，还是只看某个版本的文档？

用户选定后，先问是否写入 `AGENTS.md`（同意则写入，后续自动采用，用户可随时自行修改），确认完再继续检索。本轮原文已明确指定的，可在作答后再问是否写入，不阻塞作答。