发票归集 MCP Skill
通过企享云 invoice_aggregation MCP 服务完成发票归集与明细查询。四个业务工具首次使用时走一次性网页登录闭环，完成 ACK 后长期复用本地企业集合；用户不接触内部 flow、证明或短期授权。
前置条件：企享云凭证
本 Skill 使用单一的企享云开放平台 APIKEY：
QXY_API_KEY=<appkey>.<secret>
APIKEY 申请地址：https://open.qixiangyun.com/#/productRelated/aiProduct
凭证读取优先级为进程环境变量、Skill 根目录 .env、qixiangyun-skill/.env；每个来源必须提供完整 APIKEY，禁止跨来源拼接。不得在日志、对话、错误信息或业务参数中输出 APIKEY 原文。
标准调用闭环
- 使用
scripts/invoice_collection_workflow.py collect传入业务工具和业务参数。多租户 Agent 应同时传入稳定且私有的--login-context-id。 - 首次调用只创建一次性登录会话，不调用发票归集 MCP。返回结果中：
- 只向用户展示login_url和简短操作说明；
-flow_id、agent_handoff、waitArgv仅供 Agent 内部使用；
- Agent 应在后台执行agent_handoff.waitArgv，不要要求用户回传任何内部标识。 - 等待器收到
qxy.agent_login.completed后，原样执行内部resumeArgv续跑原始collect。waitArgv始终携带本次具体--login-flow-id，绑定会话时还同时携带同一个--login-context-id；不得只按“该会话的最新 flow”重建命令，以免并发业务串单。 - Skill 从私有 flow 恢复全部
authenticatedEnterprises[]；新业务默认绑定activeEnterpriseContext，显式企业参数必须准确命中授权列表中的同一项。短期 Grant 仍有效时附加 Header，过期或无效时只停止发送该 Header，不删除企业配置。
登录完成时，顶层字段代表主企业，enterprises[] 代表同一 Grant 授权的全部成功企业，
failedEnterprises[] 不参与业务授权。授权内切换使用同一私有 --login-context-id 调用
list-enterprises / select-enterprise，不重新登录、不轮询或 ACK，也不更换 Grant；同名或
同税号多身份必须结合 KPY/BSY 消歧。目标不在列表、Grant 失效或 flow 损坏都不得自动
创建第二个网页；只有用户明确说“配置企业/重新配置企业/增加企业”后，才可使用
--switch-account 替换整份企业配置，不能用于授权内切换。
选择完成后或归集业务明确提示税局会话失效时，调用 scripts/managed_login_flow.py
ensure。缓存或快速登录有效则继续原业务；需要短信时只请用户在聊天框输入验证码，再用
submit --sms-code-stdin 通过敏感 stdin 提交。不得询问手机号、密码、taskId 或内部企业
ID，不得回显、记录或持久化验证码。发送和提交不自动重放，Grant 失效仍使用本地企业
配置进入聊天验证码流程，不回一次性网页。
详细状态机见 references/chat-managed-login.md。
登录结果的安全事务顺序固定为：
completed -> 原子落盘 Grant 与完整多企业状态 -> ACK -> acked
同一 flow 的整段事务会跨线程、跨进程串行执行。敏感完成态在 ACK 前原子落盘并持久化文件及父目录；ACK 前按受限传输的最坏超时与重试路径动态计算 Grant 安全窗口（默认 402 秒），ACK 后再次校验。已 acked 的后续等待器只能从本地私有状态恢复，不得再次 poll 或 ACK。Grant 到期只把 agentGrantState 标记为 expired，不会删除已 ACK 企业集合、改变 active 或生成新的登录页。
详细协议见 references/agent-login-api.md。
本机、测试或私有化联调时，可通过 QXY_AGENT_LOGIN_MCP_ENDPOINT 和
QXY_INVOICE_AGGREGATION_MCP_ENDPOINT 覆盖端点；登录与发票归集端点必须指向同一
可信 MCP 部署，共享同一 Agent Grant 存储与校验边界。这些覆盖项不得作为普通用户的
使用步骤，HTTP 端点仅可在可信测试网络中配合 QXY_AGENT_LOGIN_ALLOW_HTTP=true 使用。
严格调用规则
- 发票归集业务只通过
scripts/invoice_collection_workflow.py collect或它生成的内部续跑命令执行。 scripts/mcp_client.py可用于列服务和查看 schema；业务工具必须携带有效的--login-flow-id，且该客户端禁止直调agent_login。- 禁止让用户或调用方提供、传递或手工拼接 Agent Grant；公开
call_tool只接受 flow 标识，Grant 只能由其内部从acked私有 flow 读取。 - 禁止使用
curl、requests、OpenAPI、网页自动化或手写 HTTP 绕过工作流。 - 用户在
--args显式传入的企业字段必须准确命中同一授权企业；跨企业拼接或命中失败时在联网前阻断。 - MCP 工具 schema 是实际调用准则；接口资料只用于解释业务字段。
产品授权终态
业务或登录 MCP 返回 code=505069 且命中已登记的测试期/测试次数文案时，只向用户回复：
“您当前使用的是免费版，该产品的测试使用期已结束。为了不影响您的业务正常开展，建议您前往企享云开放平台选购付费版或进行续费，感谢您的支持！”
命中生产次数/税号数量文案时，只回复：
“抱歉，您的产品生产授权已到期，当前服务已暂停。为确保您的业务持续稳定运行，请尽快前往企享云开放平台完成续费或购买，感谢您的配合！”
这是不可重试的 failed 终态：立即停止，不重新登录、不索取或重配 APIKEY、不自动重试，且不得把失败响应保存为成功的最近调用。不得展示原始响应或原始服务端文案。
支持的业务工具
query_input_output_invoice_info_auto：进销项发票信息query_invoice_basic_info_auto：发票基础信息query_invoice_detail_aggregation_auto：发票详情归集query_taxable_voucher_input_tax_transfer_out_auto：应税凭证进项税额转出
字段绑定保持既有业务契约：
- 四个工具都绑定网页登录结果中的
nsrsbh和accountId。 query_invoice_detail_aggregation_auto与query_taxable_voucher_input_tax_transfer_out_auto额外绑定aggOrgId。
调用示例
检查凭证：
python3 scripts/invoice_collection_workflow.py check-config
发起进销项发票信息归集：
python3 scripts/invoice_collection_workflow.py collect \
--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 \
--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 \
--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 \
--tool query_taxable_voucher_input_tax_transfer_out_auto \
--args '{"skssq":"202602"}'
查看业务工具 schema：
python3 scripts/mcp_client.py \
--service invoice_aggregation \
--describe-tool query_invoice_basic_info_auto
输出要求
- 登录未完成：只向用户提供
login_url和操作说明，内部字段留给 Agent。 - 登录完成：只展示安全的企业名称和 KPY/BSY 身份；内部企业 ID、flow、Grant 和原始 JSON 不向用户展示。
- 分页结果说明
data.Total/PageNumber/PageSize/List或data.total/list。 - 下载结果仅在用户确实需要时提供
data.jsonUrl，并提示链接可能有有效期。 - 不输出完整企业标识、签名下载地址、APIKEY 原文、会话证明或 Agent Grant。
参考文件
- 一次性登录协议与安全边界：references/agent-login-api.md
- 服务别名与工具映射：references/mcp-services.md
- 参数、响应和业务注意事项：references/api-notes.md
- 四个接口的字段摘要：references/api-specs.md
