新时代智云-发票查验/企业信息/智能赋码

概述

智云网关财税技能

用途

不经过 zhiyun-agent，直接通过智云网关（地址取自 .env 的 ZHIYUN_GW_URL，缺省 http://localhost:8080）调用真实财税接口，完成三类任务：

1. 购方抬头查询 — 按公司名/税号查开票抬头
2. 智能赋码 — 商品名 → 税收分类编码 + 税率
3. 发票查验 — 四要素验真

首次访问：凭证前置检查（必读，任何业务调用前执行）

本技能调用智云网关必须携带调用方的智云租户凭证（app_key + app_secret）。技能被加载、用户首次提出财税需求时，先不要急着调用工具，先检查本目录 .env 里的 ZHIYUN_APP_KEY 与 ZHIYUN_APP_SECRET 是否已配置且非空：

• 两个都已配置且非空 → 按下方流程正常调用。
• 任一缺失 / 为空 → 立即停下，主动告诉用户需要这两个参数，不要静默尝试调用、也不要默认走兜底凭证：

使用本技能需要智云开放平台的 app_key（租户 Key） 和 SecretKey（SecretKey） 两个凭证。请把这两个值一起发给我（例如「我的智云 Key 是 xxx，Secret 是 yyy」），我保存好就能直接调用了。

• 若用户明确表示自己没有这两个凭证 → 说明这是北京新时代智云科技有限公司发放的租户凭证，引导其去官方渠道申请，不要反复索要：

这两个凭证由「北京新时代智云科技有限公司」发放。如果你还没有，请前往其官网 http://www.newtimeai.com/ 注册 / 申请智云开放平台租户账号，获取 app_key 与 app_secret 后再使用本技能；也可通过官网联系新时代智云客服咨询开通事宜。

注：在对话中收到这两个值后，用 save-cred 子命令写入 .env（600 权限）并自动复用，后续不再索要；回复中不得回显明文。

鉴权模型（重要）

网关不再自行签发 Key。用户与流量管理都在智云平台侧，网关只做透传与归一化，因此调用方需要提供智云租户的两个参数：

网关拿这两个值向智云换取 access_token（带缓存），不会存储用户凭证。

凭证获取：ZHIYUN_APP_KEY / ZHIYUN_APP_SECRET 两者需在首次使用前配置（见上方「首次访问」规则）。网关侧可能存在兜底凭证（config.yaml 的 default_credential），但本技能的默认策略是优先向用户索取其自有租户凭证——因为独立账号的流量 / 配额独立、数据归属清晰。若用户确实没有凭证，引导其前往北京新时代智云科技有限公司官网 http://www.newtimeai.com/ 申请，而非默认使用网关兜底账号。

配置凭证（可选；二选一，效果相同）

1. 对话中输入并保存（推荐，免改文件）：用户把两个值发在对话里，运行 save-cred 子命令写入 .env 并设为 600 权限，之后自动复用。
2. 手动改文件：cp .env.example .env，填入两个值，chmod 600 .env。

首次使用前确认网关可达（地址取自 .env 的 ZHIYUN_GW_URL；从网关下载的技能包已自动写入该地址）。凭证申请方式见 references/api_reference.md。

在对话中设置 / 更换凭证（重要触发规则）

当用户在对话里提供智云凭证时，按以下规则处理：

• 触发信号：用户说"设置/保存我的智云 Key / app_key / SecretKey / 租户密钥"并附带一对字符串。
• 建议拿到两个值再保存（用独立账号，流量/配额独立）。若用户只给了一个，先追问缺失的那个（例如："收到 app_key，还需要对应的 SecretKey"）；若用户明确表示网关已开兜底、无需提供，则可跳过，调用会自动走网关兜底凭证。
• 动作：先运行保存子命令，再继续业务调用：
  • macOS / Linux：bash ~/.workbuddy/skills/newtimeai-invoicehelp/scripts/invoke.sh save-cred <app_key> <app_secret>
  • Windows：powershell -File $HOME.workbuddyskillsnewtimeai-invoicehelpscriptsinvoke.ps1 save-cred <app_key> <app_secret>
• 保存成功后，后续调用自动读取 .env，不要再向用户索要，也不要在回复里回显明文。
• 只想临时用一次不落盘：用环境变量覆盖
  • macOS / Linux：ZHIYUN_APP_KEY=<key> ZHIYUN_APP_SECRET=<secret> bash ~/.workbuddy/skills/newtimeai-invoicehelp/scripts/invoke.sh <tool> '<json>'
  • Windows：$env:ZHIYUN_APP_KEY='<key>'; $env:ZHIYUN_APP_SECRET='<secret>'; powershell -File $HOME.workbuddyskillsnewtimeai-invoicehelpscriptsinvoke.ps1 <tool> '<json>'
• 更换凭证：直接发新的一对值，重新跑 save-cred 覆盖。

调用方式

macOS / Linux 用 scripts/invoke.sh，Windows 用 scripts/invoke.ps1（均自动读 .env、自带健康检查、凭证走请求头不进 URL）：

# macOS / Linux
bash ~/.workbuddy/skills/newtimeai-invoicehelp/scripts/invoke.sh <tool> '<json-arguments>'

# Windows (PowerShell)
powershell -File $HOME.workbuddyskillsnewtimeai-invoicehelpscriptsinvoke.ps1 <tool> '<json-arguments>'

示例：

# 查购方抬头（不知道税号时，只传 nsrmc 即可，网关按名称模糊匹配；kpdwdm 可不传）
bash ~/.workbuddy/skills/newtimeai-invoicehelp/scripts/invoke.sh query_buyer_info '{"nsrmc":"腾讯"}'

# 商品赋码
bash ~/.workbuddy/skills/newtimeai-invoicehelp/scripts/invoke.sh intelligent_code_assign '{"name":"笔记本电脑"}'

# 发票查验（数电票示例）
bash ~/.workbuddy/skills/newtimeai-invoicehelp/scripts/invoke.sh verify_invoice '{"fphm":"24312000000012345678","kprq":"20260315","fpje":"1130.00","fpje_type":"price_total"}'

参数明细、fpje_type 票种对照表、业务错误码见 references/api_reference.md（调用前建议先读一遍）。

技能版本与升级提示

• 技能包在下载时由网关把当前发布的版本号写入 .env 的 ZHIYUN_SKILL_VERSION（无需手动维护）。
• 调用网关时，脚本自动读取该值并通过请求头 X-Skill-Version 上报。
• 当上报版本低于网关管理员设定的最新版本时，网关会在每个响应里附带 skill_upgrade 字段：

  "skill_upgrade": {
    "available": true,
    "latest_version": "1.2.0",
    "your_version": "1.0.0",
    "download_url": "https://gw.example.com/ui/download/skill",
    "message": "当前技能包版本 1.0.0 较低, 建议升级到 1.2.0; 可重新下载技能包获取: https://gw.example.com/ui/download/skill"
  }

• 处理规则：只要响应里出现 skill_upgrade.available == true，就主动提醒用户升级，并把 download_url 作为可点击链接展示出来（例如："你的智云网关技能包版本偏低（当前 1.0.0，最新 1.2.0），建议重新下载更新：<链接>"）。这不影响本次调用结果，正常把 data 返回给用户即可，升级提示仅作引导。

开票业务 SOP（用户要开发票时按此流程）

1. 用户没给购方税号 → 先调 query_buyer_info（用 nsrmc 模糊匹配）
2. 每个商品必须先调 intelligent_code_assign 拿编码和税率
3. 税率选返回 spkysl 数组的最大值；组装参数时税率用小数（0.13 而非 13%）
4. 金额四舍五入到 2 位小数
5. 查验发票时 fpje_type 必须按票种选对（专票=tax_excluded、普票=check_code、数电=price_total）

错误处理

• 外层 code=0 才是网关成功；data.code 是智云业务码：1004 退避 5 秒重试一次；1001 检查参数后重试；1005（税控设备未就绪）如实告知用户，不要重试
• code=1010 → 本次请求未携带有效凭证。网关 msg 会明确指出缺的是 app_key 还是 app_secret（或两者都缺）。据此精准引导，不要笼统说"系统不可用"：
  • 缺 app_key：提示用户提供智云租户 Key（请求头 X-App-Key / 请求体 app_key）
  • 缺 app_secret：提示用户提供智云租户 SecretKey（请求头 X-App-Secret / 请求体 app_secret）
  • 两者都缺：按「首次访问」规则，向用户索取 app_key 与 app_secret 两个值，拿到后用 save-cred 落盘复用；也可让用户自己编辑 .env 填这两项。若用户表示没有凭证，引导其前往北京新时代智云科技有限公司官网 http://www.newtimeai.com/ 注册 / 申请智云开放平台租户账号：

调用智云财税工具需要你的智云租户凭证（把 app_key 和 SecretKey 两个值发给我，我保存好之后就能直接用了）。如果你还没有，请到北京新时代智云科技有限公司官网 http://www.newtimeai.com/ 申请。

• code=1001 → 网关侧必填参数缺失。网关 msg 会列出具体缺哪些参数名（如 query_buyer_info 缺 nsrmc、verify_invoice 缺 fplxdm/fpdm/fphm/kprq/fpje_type/fpje）。逐项提示用户补齐对应参数即可，不要只说"参数错误"。
• code=1002 → 凭证无效（智云换 token 被拒），提示用户核对 app_key/app_secret 是否正确、是否已过期
• 脚本报"网关未启动" → 提示先启动 zhiyun-gateway（安装包用户运行 start.sh/start.bat；源码环境 go run cmd/server/main.go）；网关不在本机时确认 .env 的 ZHIYUN_GW_URL
• 脚本报"未提供智云凭证，将使用网关兜底凭证" → 这是 warn（非错误）。按本技能策略，即便网关有兜底，也应主动询问用户是否有自己的智云租户凭证；若用户没有，引导其前往北京新时代智云科技有限公司官网 http://www.newtimeai.com/ 申请，而不是默认长期使用网关兜底账号。
• 购方查询无结果 → 询问用户税号；赋码无结果 → 询问商品的标准名称

安全约束

• ZHIYUN_APP_KEY / ZHIYUN_APP_SECRET 存于本目录 .env（macOS/Linux 600 权限，Windows 仅当前用户可读写），禁止在回复、日志、生成的文件中打印明文
• 用户在对话中输入凭证进行保存时：仅回复"已保存/已更新"，不得回显明文。注意对话历史本身已包含这两个值，如在不安全环境使用，可提醒其事后在智云平台轮换
• 凭证只通过请求头 X-App-Key / X-App-Secret 下发，不要拼进 URL 查询串
• 查验结果原样告知用户，不要臆测补充