智能税收分类编码匹配
根据商品名称(「手机」「东北大米」)或开票需求描述(「停车场场地租赁该开什么编码」), 匹配税收分类编码,并按纳税人类型给出可用税率。
1. 认证与连接器定位(先做,别急着说"没有工具")
唯一依赖连接器 wpe-general-connector(中文名「腾讯数电发票」),通过它的 call_internal_api 工具调用。
| 项 | 值 |
|---|---|
| 连接器 | wpe-general-connector(中文名「腾讯数电发票」) |
| 税号传递 | 连接器请求头 X-Subject-Id(兼容 X-Merchant-Id / X-Tax-No),不是接口参数 |
| 令牌 | Authorization: Bearer <token> 或 x-mcp-token |
| 生效方式 | 远端 HTTP MCP,授权/改连接头后生效 |
定位与授权流程:
- 会话中找不到该连接器工具 → 用名称
wpe-general-connector(或「腾讯数电发票」)在连接器列表查找并加载 MCP。 - 加载后首次调用不带 token(探活)。返回 HTTP 401 → 未授权,停下提示用户完成 MCP 授权,通过后再继续。
- 服务端是无状态模式,每一步请求都要带
X-Subject-Id,不存在「initialize 过了就放行」。
⚠️ 禁止用脚本、curl 或其它连接器直连服务端点(
server.wpe.tencent.com)——功能只能通过该连接器实现。
2. 工具说明
| 工具 | 用途 | 何时用 |
|---|---|---|
call_internal_api |
调用内部 HTTP 接口 | 本技能唯一入口,api="intelligent_tax_coding" |
health_check |
服务/DB 就绪检查 + 税号接入状态 | 调用失败时排查 |
2.1 call_internal_api(唯一调用方式)
参数:
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
api |
string | ✅ | 固定 intelligent_tax_coding |
params.productName |
string | ✅ | 品名,驼峰;后端 @NotBlank,不能纯空白 |
调用示例:
{"api": "intelligent_tax_coding", "params": {"productName": "笔记本电脑"}}
返回值信封(腾讯云风格,没有 code 字段):
| 字段 | 含义 |
|---|---|
Response.Error |
null=成功;非 null 为业务错误 |
Response.RequestId |
链路追踪号,排障必须一并给出 |
Response.Data.detailList |
结果数组,永远恰好 1 条,从不为空 |
detailList[] 字段:
| 字段 | 类型 | 含义 |
|---|---|---|
taxClassCode |
string | 19 位税收分类编码 |
productName |
string | 匹配到的标准品名(不是传入名称) |
productAbbreviation |
string | 简称/大类,如「电子计算机」 |
taxRate |
string | 税率,已是百分比字符串("13%"),直接展示不要换算 |
taxPreferentialType |
string | 税收优惠类型("免税、按2%简易征收");空串=无优惠 |
matchedDegree |
string | 匹配度("92%");不可当置信度 |
3. 执行流程
步骤 1:提炼查询品名
输入是商品名 → 直接用,可再补 1~2 个更具体说法备交叉验证。
输入是需求描述 → 先提炼货物/服务实质名称(只写"卖的是什么",不写场景/金额/客户名):
用户描述 提炼品名 给客户做设备维修 设备维修服务销售自种大米 大米、东北大米收一个月房租 房屋租赁服务帮客户开发系统 软件开发服务卖二手笔记本电脑 笔记本电脑、二手电脑一次提炼 2~3 个候选品名逐个调用(一次一个
productName),命中同一编码即可交叉验证。
步骤 2:调用
{"api": "intelligent_tax_coding", "params": {"productName": "<品名>"}}
步骤 3:判读(判定以 productName 为准,不看 matchedDegree)
| 检查项 | 动作 |
|---|---|
Error != null |
报业务错误,连同 RequestId 给出 |
productName 与用户输入同类 |
可信,正常输出 |
productName 明显不符 |
判定错配,不采用,换更具体说法重试 |
matchedDegree < 约 60% |
换 2~4 个更具体/同义说法交叉验证(「大米」57% →「东北大米」72%) |
matchedDegree 高但 productName 跑偏 |
仍是错配(「粳米」73% →「植物类饮片」),以 productName 为准 |
步骤 4:输出
按 templates/report-template.md:结果表 + 按纳税人类型可用税率表(必出)+ 交叉验证表(若做)+ 两条风险提示 + 排障信息。
4. 按纳税人类型给出可用税率(必须输出)
匹配只给一个 taxRate(记为 R),实际能开多少取决于开票方身份。输出时按下表展开,不得只报一个百分比:
| 纳税人类型 | 可选用税率 | 推导规则 |
|---|---|---|
| 一般纳税人 | ①一般计税 R;②P 含「简易征收」时可选简易计税(P 写明具体率的用该值,如「按2%简易征收」→2%) | 以 R 为主;简易计税一经选择 36 个月不变 |
| 小规模纳税人 | 按现行征收率(现行 3%,阶段性优惠减按 1%,以现行政策为准);P 含「免税」可免征 | 小规模不按 R 计税 |
| 农业生产者(销售自产) | P 含「免税」时免征 | 粮食/蔬菜/鲜活肉蛋等 |
| 销售旧货/使用过固定资产 | P 含「按2%简易征收」时按 2% | 需符合税法情形 |
组合速查:
taxPreferentialType |
一般纳税人 | 小规模纳税人 |
|---|---|---|
| 空(无优惠) | R | 现行征收率 |
| 「简易征收、按2%简易征收」 | R,或 2% | 现行征收率,符合情形可 2% |
| 「免税、按2%简易征收」 | R,或免征/2% | 可免征 |
| 「免税」 | R,或免征 | 可免征 |
三条纪律:①不替用户拍板选税率;②征收率/优惠会随政策调整,具体数字注明「以现行政策为准」; ③纳税人身份未说明时两种口径都列,不要默认。
5. 错误场景与边界
| 场景 | 现象 | 处置 |
|---|---|---|
| 税号未接入 | 403 / JSON-RPC -32007「当前商户接入状态为 01,请完成接入后再使用」 |
该税号 access_status 未置 00;表现是 WorkBuddy 把整个连接器下线(工具从列表消失,易误判成"MCP 挂了") |
| 连接器未授权 | HTTP 401 | 提示用户完成 MCP 授权(见 §1) |
| 泛称匹配度低 | 「服务」33% 错配到「修理修配服务」 | 品名越具体越准 |
| 无意义输入也返回 | 「zzzz不存在」→「其他日用杂品」82% | 接口永不返空,不能拿匹配度当置信度 |
| 高匹配度错类 | 「粳米」73% →「植物类饮片」 | 一律以 productName 判类 |
常见品名陷阱:简称会跨类(笔记本→纸质文具;苹果→水果),开票品名要写完整; 农业类普遍带「免税、按2%简易征收」,电子设备类普遍带「简易征收、按2%简易征收」, 是否适用取决于销售方身份与货物来源,不要替用户拍板。
参考
- 接口规范、响应信封、鉴权与已知不可信点:
references/api-spec.md - 实测样例(含反例):
references/examples.md - 输出模板:
templates/report-template.md