发票归集 MCP Skill

通过企享云 invoice_aggregation MCP 服务完成发票归集与明细查询。发票归集与税局企业登录强关联，对外优先使用 scripts/invoice_collection_workflow.py collect，不要让用户单独调用登录 Skill。

前置条件：凭证配置

本 skill 依赖企享云开放平台凭证：

• client_appkey
• client_secret

API 密钥申请：https://open.qixiangyun.com

凭证读取优先级：

1. Skill 根目录的 .env
2. Skills 公共父目录的 .env（/Users/xueds/Python/skills/qixiangyun-skill/.env）
3. 系统环境变量 QXY_CLIENT_APPKEY / QXY_CLIENT_SECRET

首次使用时，如果凭证不存在：

1. 询问用户的 client_appkey 和 client_secret
2. 如果用户没有凭证，提示：

appKey和appSecret请注册企享云开放平台申请 https://open.qixiangyun.com

1. 在 skill 根目录或公共父目录创建 .env：

```env

QXY_CLIENT_APPKEY=用户提供的appkey

QXY_CLIENT_SECRET=用户提供的secret

```

1. 后续调用由脚本自动读取，无需再次询问

登录说明

本 skill 的四个发票归集工具与电子税务局企业登录强关联。发票归集入口会使用本 Skill 内置的税局登录能力完成：

• 自然人账号创建/登录
• 自然人短信验证码卡点续跑
• 企业列表发现与选择
• 企业服务订购
• 企业多账号创建
• 企业登录与企业短信验证码卡点续跑
• 归集参数绑定：nsrsbh、必要时的 aggOrgId/accountId

自然人登录密码必须通过环境变量传入，避免明文落入命令历史：

export QXY_LOGIN_PASSWORD="your_password"

如果同一个自然人账号关联多个企业，流程会返回 enterprise_selector 卡点，再由用户补充 --enterprise-index、--nsrmc 或 --nsrsbh 继续同一个 collect 命令。如果用户直接回复数字 1 / 2 / 3，必须按展示顺序把该数字作为 --enterprise-index。

如果用户输入地区与选中企业所属地区不同，企业订购、多账号创建和企业登录都必须使用选中企业的地区代码。不得继续使用用户最初输入的地区覆盖选中企业地区。

如果返回 waiting_for_user_input=true，只能继续调用同一个 collect 命令并补充对应参数：

• user_input_kind=enterprise_selector：展示返回的 enterprises，用户选择后补充 --enterprise-index、--nsrmc 或 --nsrsbh
• user_input_kind=natural_sms_code：补充 --natural-sms-code
• user_input_kind=enterprise_sms_code：补充 --enterprise-sms-code

nsrsbh、aggOrgId、accountId 来自登录选中的企业。用户显式在 --args 中传入这些字段时，必须与登录结果一致；不一致时脚本会阻断调用，不能把 A 企业登录态用于 B 企业发票归集。

严格调用规则

1. 所有发票归集调用都只能通过 bundled script：
• 首选：scripts/invoice_collection_workflow.py collect
• 仅调试 MCP schema/低级工具时：scripts/mcp_client.py
2. 禁止直接使用 curl、requests、OpenAPI、网页浏览或手写 HTTP 请求发起业务调用
3. 禁止输出或记录 client_secret 原文
4. 以 MCP 工具 schema 为实际调用准则；Apifox 文档用于业务字段解释
5. 如果脚本调用失败，直接根据脚本返回的结构化错误处理，不要自行切换到其他调用通道

支持模块

• invoice_aggregation：发票归集

详细映射见 references/mcp-services.md。

四个业务工具

• query_input_output_invoice_info_auto：进销项发票信息
• query_invoice_basic_info_auto：发票基础信息
• query_invoice_detail_aggregation_auto：发票详情归集
• query_taxable_voucher_input_tax_transfer_out_auto：应税凭证进项税额转出

MCP 服务还暴露 clear_cache，仅用于认证缓存清理，不属于本 skill 的四个业务工具。

调用方式

列出当前 skill 支持的服务：

python3 scripts/mcp_client.py --list-services

检查凭证是否已配置：

python3 scripts/mcp_client.py --check-config

列出 invoice_aggregation 服务下的工具：

python3 scripts/mcp_client.py --service invoice_aggregation --list-tools

查看工具 schema：

python3 scripts/mcp_client.py \
  --service invoice_aggregation \
  --describe-tool query_invoice_basic_info_auto

登录并查询进销项发票信息：

python3 scripts/invoice_collection_workflow.py collect \
  --area-code 3100 \
  --phone 13800138000 \
  --password-env QXY_LOGIN_PASSWORD \
  --tool query_input_output_invoice_info_auto \
  --args '{"kprqq":"2026-01-01","kprqz":"2026-01-31","jxxbz":"jx","fplx":"10,14"}'

登录并分页查询发票基础信息：

python3 scripts/invoice_collection_workflow.py collect \
  --area-code 3100 \
  --phone 13800138000 \
  --password-env QXY_LOGIN_PASSWORD \
  --tool query_invoice_basic_info_auto \
  --args '{"jxxbz":"jx","kprqq":"2026-01-01","kprqz":"2026-01-31","pageSize":100,"pageNumber":1}'

登录并查询单张发票详情：

python3 scripts/invoice_collection_workflow.py collect \
  --area-code 3100 \
  --phone 13800138000 \
  --password-env QXY_LOGIN_PASSWORD \
  --tool query_invoice_detail_aggregation_auto \
  --args '{"jxxbz":"jx","kprq":"2026-01-16","gjlx":"1,2,3,4","sdphm":"26112000000*****"}'

登录并查询应税凭证进项税额转出：

python3 scripts/invoice_collection_workflow.py collect \
  --area-code 3100 \
  --phone 13800138000 \
  --password-env QXY_LOGIN_PASSWORD \
  --tool query_taxable_voucher_input_tax_transfer_out_auto \
  --args '{"skssq":"202602"}'

输出要求

输出结果应尽量包含以下信息：

• 当前使用的脚本，优先为 scripts/invoice_collection_workflow.py
• 当前所属模块：invoice_aggregation
• 实际调用的 tool 名称
• 请求中的关键业务参数：nsrsbh、kprqq/kprqz、kprq、jxxbz、fplx、aggOrgId、skssq
• 返回中的 reqId、code、success、message
• 如果存在下载地址，说明 data.jsonUrl
• 如果存在分页数据，说明 data.Total、data.PageNumber、data.PageSize 或 data.total
• 如果失败，给出可执行的下一步建议

登录态规则

• 本地状态里的 enterpriseLogin.verified=true 只表示历史流程走到企业登录完成，不能直接等同于税局缓存仍有效。
• 复用企业登录态前，必须通过 login_enterprise_account 校验缓存或快速登录；校验不 ready 时，保留企业选择、订购和多账号信息，清理企业登录态并重新发起企业短信登录。
• aggOrgId/accountId 可兼容读取历史 camelCase 和内部 snake_case 字段，但提交 invoice_aggregation MCP 前必须统一为 aggOrgId/accountId。
• 四个发票归集工具都必须绑定登录返回的 accountId，否则服务端可能无法解析 gdsdlfs 登录方式并返回“gdsdlfs 不能为空”。
• query_invoice_detail_aggregation_auto 和 query_taxable_voucher_input_tax_transfer_out_auto 必须额外绑定登录返回的 aggOrgId。

参考文件

• 服务别名与工具映射：references/mcp-services.md
• 参数、响应和业务注意事项：references/api-notes.md
• 四个接口的字段摘要：references/api-specs.md