新时代智云-发票开具/智能赋码/发票下载

概述

智云开票技能

⚠️ 二次认证扫码话术（最高优先级，必须逐字遵守）

开票返回 code=1030 需要扫码认证时，二维码只能用「微信」扫。绝不可以说「电子税务局 App」「电子税务局」「税务工具」扫码——这是最常见的错误，说错会让用户按错误入口操作、反复失败。

必须向用户输出的原话（不要改写、不要增删、不要自己发挥）：

请用微信扫一扫下方卡片上的二维码，按页面提示完成登录认证；成功后回复「继续开票」，我会用同一流水号重试。

• data.auth_type = sms_login → 二维码是短信验证码登录（在微信里按提示收短信验证码完成登录），不是人脸认证，不要提"人脸"。
• data.auth_type = face_auth → 二维码是人脸认证，在微信里完成刷脸。
• 卡片页脚已按类型写明「短信验证码登录（非人脸认证）」或「人脸认证」，以卡片页脚为准，不要另行编造 App 名称或步骤。
• 严禁出现这些词：「电子税务局 App」「电子税务局扫码」「个税 App」「税务工具」「自然人电子税务局」。

用途

通过「新时代智云开票网关」完成发票开具全流程：

1. 登录 — 开票账号 + 密码，换取网关 token（真实 token 不出网关）
2. 企业信息 — 查当前账号下税号、开票点、票种、征管信息（blxx）
3. 销方信息 — 查销方名称 / 地址电话 / 开户行账号 / 收款人复核人开票人
4. 内容识别 — AI 把「开一张技术服务费，给滴滴」解析成购方 + 商品明细（含税收编码与税率）
5. 开具发票 — 蓝字发票（数电普票 82 / 数电专票 81），返回发票号码与版式文件

旧版三个工具（query_buyer_info / intelligent_code_assign / verify_invoice）仍保留，但走的是 app_key/app_secret 旧鉴权，仅作兼容；开票主流程请用上面的新工具。

鉴权模型（重要）

网关采用 账号密码登录 + 网关 token 模式：

用户 ──(czydm + 密码)──> 网关 ──(MD5 密码)──> 智云登录接口
                          │
                          ├─ 拿到「真实 token」→ 仅存网关内存
                          └─ 签发「网关 token(gwt_...)」→ 返回给客户端

• 客户端（本技能）只持有网关 token，不接触真实 token。
• 后续业务调用自动带请求头 X-Gateway-Token: gwt_...，网关换回真实 token 再请求开票接口。
• 未登录 / token 过期 → 网关返回 code=1020，需重新登录。

首次使用 / 登录（必须遵守）

判断是否已登录：.env 中存在未过期的 ZHIYUN_GW_TOKEN。

• 已登录 → 直接进入开票 SOP。
• 未登录，但本机已记住账号密码 → 直接调用业务工具，脚本会自动静默重登，不要再问用户。
• 未登录且没有记住的凭据 → 只回这一句：

请把开票账号和密码发我，登录后才能继续开票。

不要解释原因、不要列后续步骤、不要提前问购方名称/税率/商品/金额。

• 拿到后执行（密码只传给脚本，不要在回复里回显）：
  • macOS / Linux：bash <skill>/scripts/invoke.sh login <czydm> <密码>
  • Windows：powershell -File <skill>scriptsinvoke.ps1 login <czydm> <密码>
• 默认记住账号密码：登录成功后，脚本把凭据存入系统安全存储（macOS Keychain / Windows DPAPI）；不可用时降级为 600 权限的 .cred 文件。密码不写入 .env。
• 之后 token 过期（约 2 小时）或网关重启，业务调用会自动用记住的凭据重登一次，用户无需再次输入。
• 登录成功只回复「已登录」，不得回显 token 或密码。
• 用户要退出登录（保留记住的密码，下次自动重登）：invoke.sh logout。
• 用户要完全忘记密码：invoke.sh forget（清 token + 本机凭据）。
• 排查问题：invoke.sh status 一次打印网关地址/在线状态、可用工具、token 是否有效、记住的账号（不显示密码）。
• 用户要求「这次不记住」：登录时加 --no-remember。
• 账号密码错误（code=1002，上游提示「校验码错误」等）→ 如实告知账号或密码不对；若之前记住过，提醒用户凭据可能已变更，先 forget 再重新登录。

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

1. 确保已登录（见上）。
2. 查企业信息 query_czyfwq → 取：
   • 先不带条件拉全量：query_czyfwq '{}'（不要传 nsrmc/nsrsbh）。上游不支持模糊查询，传了关键字反而返回空。
   • sole=true（只有 1 家）→ 直接用它，不要问用户选哪家；多家 → 用 {"keyword":"企业简称/地区/税号片段"} 在网关侧本地过滤；仍不唯一才让用户从候选企业名里选。
   • kpdwdm = 销方税号（后续 xhdwsbh 与识别接口的 nsrsbh）
   • blxx = 征管信息（含 "08" 视为小规模，默认税率 1%）
   • kpdwmc = 销方名称
   • 不要因为查不到就回头问用户要销方名称/税号：先看返回的 hint（含可用企业名），把候选列给用户选；只有账号下确实没有企业才提示核对账号。
3. 查销方信息 query_seller_info（kpdwdm）→ 取 xhdwmc / xhdwdzdh（地址+空格+电话）/ xhdwyhzh（开户行+空格+账号）。
   • 开票时只传 xhdwsbh 即可：名称/地址电话/银行账号由网关自动从 searchKphxxById 补齐并拼好，不需要你逐个抄，也不要因缺地址去问用户（上游「销售方地址不允许为空」已前置处理）。
4. 解析开票内容：
   • 用户给的是自然语言 / 图片 / 文件：图片或文件先由 WorkBuddy 转成文本，再调 recognize_invoice（nsrsbh=销方税号，txt=内容）→ 得到购方名称 ghdwmc 与商品明细 zbmx（含 spbm 税收编码、sl 税率）。
   • 用户直接给了商品、金额、税率/编码：以用户为准，不要擅自改。
5. 税率规则（网关自动执行，不用自己判断），优先级从高到低：
   • 用户明确给了税率 → 以用户为准，原样传。
   • 未给且 blxx 含 "08"（小规模）→ 默认 0.01。
   • 未给且非小规模 → 取该编码的建议税率（赋码接口 spkysl 第一个，通常 0.06）。
   • 税率没给不用追问用户，把 blxx 传上去即可；auto_fixes 会说明实际用了多少。
   • 只有连 blxx 都没有（未查企业信息）时，先补查企业。
6. 金额规则：用户给价税合计时传 je + hsbz="1"（含税）；网关自动算不含税金额、税额与三项合计，四舍五入 2 位小数。

该问什么 / 不该问什么：

• 必须问（只在这两项真的缺时问，可以并列一次性问）：商品品名、金额。
  • 品名缺失 → 必须问，不要擅自默认成「技术服务费」。
• 不要问：购方写个人的姓名（直接填「个人」）、税率、税收编码/简称、销方地址电话/银行账号、发票类型（默认 82）。
• 销方：账号下只有 1 家（sole=true）→ 直接用，不要问；多于 1 家 → 问一次「用哪家开」并列出企业名+税号。
• 信息齐了就直接出结果：立刻 prepare 预检、把完整信息列给用户核对，用「开 / 修改 / 取消开具」一次拍板；不要再问第二遍，也不要把能自动定的项抛回给用户。

1. 数量 / 单价规则（不要追问，交给网关）：
   • 只给数量没给单价（或反之）→ 直接传已给的那个，网关会按金额自动补算另一个。
   • 两个都没给 → 正常，只按金额开票。
   • 只有「数量、单价、金额都没有」才需要问金额。
2. 税收分类编码规则（关键）：
   • 禁止自己调用任何赋码 / 编码查询接口（含旧工具 intelligent_code_assign）。赋码由网关在 issue_invoice 内部完成，外部调用会导致编码不可控。
   • 用户没给编码 → items 只传 spmc（品名），网关自动赋码。
   • 用户给了编码 → 原样传；若上游判定为汇总项（不能直接开在明细行），网关会自动换末级编码并用同一流水号重试，返回 auto_fixes 说明。
   • spbmjc（税收分类简称）也交给网关：赋码返回 分类--编码--使用率--品名，上游要的简称是第一段分类（如 *生产生活服务*），不是具体品名。网关会自动写入，并在 spmc 缺前缀时补成 *生产生活服务*技术服务费。不要自己拼简称，否则会报「商品简称不合法」。
3. 先预检再核对（关键）：执行 invoke.sh prepare '<开票参数 JSON>'，返回 data.preview —— 这是最终字段（已赋码、已定简称、已定税率、已补销方），不会真正开票。
   • dry_run 由脚本强制注入，不要自己塞；也不要用 issue_invoice 手工传 dry_run。
   • 脚本会先检测网关是否支持预检，旧网关直接报错停止（need_upgrade）；此时绝不能改调 issue_invoice 去试，否则会真开票。
   • 预检结果带 submitted: false 且没有 fphm；若看到 fphm，说明不是预检，立即停下。
   • 用 preview 整理表格（别只甩 JSON）：购方名称/税号、商品明细（spmc/spbm/spbmjc/数量/单价/金额/税率/税额）、hjje/hjse/jshj、销方名称/税号/地址电话/开户行账号、发票类型（默认 82）、备注。
   • 编码、简称、税率必须取自预检结果，不要自己手写或猜。
   • 结尾必须给出三个选项：「请回复：开 / 修改（说明改哪里）/ 取消开具。」
     • 「开/开具/确认」才提交；
     • 「修改」或直接给新内容 → 重新预检后再确认，不得直接提交；
     • 「取消/不开了」→ 终止，不调 issue_invoice，已生成的 fpqqlsh 一并丢弃；
     • 回答含糊（「嗯」「知道了」）→ 再确认一次，不得当作同意。
4. 提交开票 issue_invoice：直接调（不经过 prepare），fpqqlsh 沿用预检返回的值。这是唯一会产生发票的动作。
5. 结果处理：
   • 成功 → 展示发票号码 fphm、开票日期、价税合计，以及 pdf / ofd / xml 中非空的下载链接。
   • 若返回 auto_fixes，如实说明网关自动做了什么（自动赋码 / 补算单价 / 汇总项换码重开），不要隐瞒。
   • 失败 → 保留返回的 fpqqlsh，重试时沿用同一流水号（网关默认也会保持）；不要换号重开。
   • 失败原因是编码/汇总项时，网关已自动重试过一次；仍失败就如实告知并建议换品名或人工给编码，不要自己反复换编码试。
   • 上游报 10336 要分两种，看返回里有没有 data.need_manual_check：
     • 没有该标记（如「流水号已存在/请勿重复提交」）→ 网关已自动换新流水号重试一次，auto_fixes 会写明，你无需介入。
     • data.need_manual_check = true（如「当前开具请求异常，请先修复发票确认是否已开具成功」）→ 这张票可能已经开出来了，绝对不要再次提交。把 data.hint 如实转述给用户：先去电子税务局/开票客户端核对是否已有这张票、并执行「修复发票」；确认没有开出后，用户说「重新开」再用新流水号重开。禁止用同一流水号重试，也禁止自动换号重试。
   • 用户要"重新开一张/换金额重开" → 重新预检，不要带上一张的流水号。

工具清单

issue_invoice 的 items[] 每行：spmc（*简称*名称）、spbm（税收编码）、je（金额）、sl（税率小数）、hsbz（1 含税/0 不含税，默认 1）、dw、spsl、ggxh；mc/spbmjc 缺省时网关从 spmc 推导。

参数明细见 references/api_reference.md。

调用方式

macOS / Linux：bash <skill>/scripts/invoke.sh <tool> '<json-arguments>' Windows：powershell -File <skill>scriptsinvoke.ps1 <tool> '<json-arguments>'

# 登录
bash <skill>/scripts/invoke.sh login dqycs 'your-password'

# 查企业信息（不传条件拉全量，再按关键字本地过滤）
bash <skill>/scripts/invoke.sh query_czyfwq '{}'
bash <skill>/scripts/invoke.sh query_czyfwq '{"keyword":"百旺"}'

# 查销方信息
bash <skill>/scripts/invoke.sh query_seller_info '{"kpdwdm":"91230102MA1BLW1A96"}'

# AI 识别开票内容
bash <skill>/scripts/invoke.sh recognize_invoice '{"nsrsbh":"91230102MA1BLW1A96","txt":"开一张技术服务费，给滴滴"}'

# 开票
bash <skill>/scripts/invoke.sh issue_invoice '{"ghdwmc":"滴滴","xhdwsbh":"91230102MA1BLW1A96","xhdwmc":"哈尔滨市百旺金赋信息技术咨询有限公司","items":[{"spmc":"*生产生活服务*技术服务费","spbm":"3079900000000000000","je":"1.00","sl":"0.01"}]}'

# 获取人脸认证扫码入口（开票返回 1030 时）
bash <skill>/scripts/invoke.sh qr 91230102MA1BLW1A96

# 下载 PDF/OFD 版式文件（保存到 ZHIYUN_OUTPUT_DIR，默认 ~/Downloads/zhiyun-invoice/）
bash <skill>/scripts/invoke.sh pdf 25617000000099998888 20261024101010 pdf

二次认证（扫码登录 / 人脸）与版式文件

• issue_invoice 返回 code=1030 → 先看 data.auth_type：
  • sms_login = 需要短信验证码登录（上游 302，用微信扫）；
  • face_auth = 需要人脸认证（上游报错文案提到人脸，用微信扫脸）。

两者提示语与卡片文案不能混用。data.ewm 是扫码入口，data.fpqqlsh 是本次流水号。

• 记录 data.auth_type，执行 invoke.sh qr <销方税号> <auth_type>（如 invoke.sh qr 91230102MA1BLW1A96 sms_login 或 invoke.sh qr 91230102MA1BLW1A96 face_auth）：脚本会生成一张「认证码」卡片（HTML，页脚文案随 auth_type 自动切换——短信登录显示「短信验证码登录（非人脸认证）」、人脸显示「人脸认证」），返回 {"type":"html","path":"..."}。
• 用 present_files 展示该卡片文件；不要贴 base64、不要只发小图、不要只给链接。
• 展示卡片后，逐字输出顶部「二次认证扫码话术」里的原话（不要改写，不得提任何 App 名称）：
  • sms_login → 话术强调「短信验证码登录，不是人脸认证」；
  • face_auth → 话术强调「人脸认证」。
  • 严禁说「电子税务局 App」「电子税务局」「税务工具」扫码。
• 用户认证成功后，用同一个 fpqqlsh 重试开票。
• 开票成功后：执行 invoke.sh pdf <fphm> <kprq> [pdf|ofd]，脚本把文件保存到 ZHIYUN_OUTPUT_DIR（默认 ~/Downloads/zhiyun-invoice/），返回 path 与 size。

红冲（红字发票）

只在用户主动要求时做，不要自动红冲。 最少只需：原发票号码（冲红原因默认 01 开票有误）。

如果这张票是本网关刚开出来的（同一次运行内），网关会自动带出销方、明细、金额、购方，只传票号即可。

跨会话/网关重启过（缓存失效）时，才需要补 xhdwsbh + 明细（items 或 spmc+je+sl）。

冲红原因（sqyy）：01 开票有误（默认）/ 02 销货退回 / 03 服务终止 / 04 销售折让。

1. 摘要确认（原票号、原因、金额、品名、销方），让用户回「开 / 修改 / 取消开具」。
2. 执行：

bash <skill>/scripts/invoke.sh red_invoice '{"yfphm":"26512000004811424826","sqyy":"01","xhdwsbh":"91230102MA1BLW1A96","ghdwmc":"个人","items":[{"spmc":"*生产生活服务*技术服务费","je":"1.00","sl":"0.01"}]}'

• je 传正数（原票金额），网关自动换算成负数不含税金额 + 负数税额。
• spbm 可省略，网关自动赋码。

1. 网关内部两步：申请红字信息表（拿 xxbbh）→ 开负数发票（kplx=1、tzbdh=xxbbh、yfphm）。
2. 返回 fphm 即红票号码，取 PDF 与蓝票一致（invoke.sh pdf <fphm> <kprq> pdf，日期带横线也能处理）。
3. 若返回 need_confirm: true（红字信息表状态不是「无需确认」）→ 不要开票，让用户先去电子税务局确认该信息表，确认后再重试。
4. 302 / 人脸认证处理与蓝票一致（看 auth_type）。

错误处理

脚本报「网关未启动」→ 提示用户启动 zhiyun-gateway，并确认 .env 的 ZHIYUN_GW_URL。

安全约束

• 密码不回显、不写入 .env/日志：只在 login 时作为参数传给脚本。为支持「记住密码」，脚本默认把账号密码存入系统安全存储（macOS Keychain / Windows DPAPI）；都不可用时才降级为 600 权限的 .cred 文件。
• 用户可随时执行 invoke.sh forget 清除本机保存的凭据；logout 只清 token、保留凭据。
• 网关 token 存 .env 的 ZHIYUN_GW_TOKEN（600 权限），也不要在回复中回显。
• 真实上游 token 只在网关内存，客户端拿不到；网关重启后 token 失效，会自动重登（凭据仍在）或请用户重新登录（凭据已清除）。
• 开票是不可逆操作：必须经用户确认摘要后再提交。

技能版本与升级提示

技能包下载时网关会写入 ZHIYUN_SKILL_VERSION，调用时通过 X-Skill-Version 上报。若响应出现 skill_upgrade.available == true，主动提醒用户升级并展示 download_url，但不影响本次结果。