申报与缴款 MCP Skill

通过企享云 MCP 完成申报准备、申报执行、申报后核验、税款缴纳与完税证明获取。

用户可见输出

脚本 stdout、结构化错误、login_url、flow、命令数组和申报步骤明细都属于 Agent 私有
编排资料，不得整包复制给用户。面向用户只输出简短自然语言、必要确认和
user_interaction.message：

• 登录入口只渲染为 [打开登录页面](<实际一次性地址>)，不得显示裸 URL；不要接入
  第三方短链服务。
• 本地单用户凭证未就绪且脚本返回交互提示时，只原样渲染
  user_interaction.message；其他配置异常只给简短原因和下一步。两种情况都不得展示
  环境变量名、值格式、配置文件、命令、路径或原始异常。
• 申报或缴款结果只说明企业名称、税款所属期/申报期、税种、金额、当前状态、是否需要用户处理和
  下一步。不得展示脚本、模块、service/tool、taskId、企业/账号内部 ID、请求参数、原始
  响应、checkpoint 路径或调试日志。
• 申报 PDF、完税证明等业务文件只渲染脚本返回的 user_download_links，例如
  [下载申报文件](<实际地址>)；原始地址留在 Agent 私有结果中，不在正文铺开长地址。

产品授权终态

脚本返回 code=505069 且 message 为以下任一固定文案时，只向用户原样展示该文案，
并立即结束当前申报、缴款或完税证明流程：

• 您当前使用的是免费版，该产品的测试使用期已结束。为了不影响您的业务正常开展，建议您前往企享云开放平台选购付费版或进行续费，感谢您的支持！
• 抱歉，您的产品生产授权已到期，当前服务已暂停。为确保您的业务持续稳定运行，请尽快前往企享云开放平台完成续费或购买，感谢您的配合！

该终态不可重试，不得重新登录、索取或重配 APIKEY，也不得展示服务端原始响应、内部
错误或任务字段。

前置条件：凭证配置

本 Skill 依赖企享云开放平台访问凭证。用户尚未申请时，只提供
申请访问凭证；以下字段和配置
规则只供 Agent/部署管理员使用，不得转述给普通用户。

凭证检查与配置：

1. 按“进程环境 → 当前 Skill .env → qixiangyun-skill/.env”的优先级读取
   内部访问凭证；部署平台可通过受控 Secret 注入进程环境。值必须是开放平台复制出的
   完整原值，同一来源不得保留旧拆分变量。
2. 本地单用户 Agent 需要自动配置时，必须以
   --check-config --allow-agent-credential-configuration 显式检查。只有返回
   configuration_required=true 时，才向用户原样显示 user_interaction.message；该提示
   必须包含聊天平台数据留存提醒，用户确认后可直接发送开放平台复制出的完整访问凭证。
3. 收到凭证后将其视为不透明敏感值，不回显、不解释、不记录；严格使用返回的固定
   agent_configuration.argv 参数数组，以 sensitive_stdin=true 的 JSON 标准输入传给
   配置器，禁用 shell。不得把真实值放入命令参数、临时文件、日志或普通 stdout。
4. 配置成功后重新执行原业务请求，无需要求用户修改文件或回复“重试”。面向用户的提示
   不得出现内部字段名、值格式、配置文件、路径或命令。
5. 未显式 opt-in、云端/多租户部署，或进程环境与公共共享配置异常时，均不得提供本地
   改写契约；只允许部署管理员在受控 Secret 边界处理。

一次性外部网页登录

所有申报、缴款和完税证明业务命令都必须先使用内置 agent_login MCP 创建或恢复本地企业配置。
初次网页登录不得要求用户在对话中提供税局手机号、密码、验证码、登录 Token，也不得继续
读取旧的 .qxy_login_state.json 或依赖 qixiangyun-tax-login-skill。首次配置完成并 ACK
后，税局会话失效按下述聊天验证码流程接收一次短期短信验证码，不再打开网页。

首次运行原业务命令时，脚本返回两层内容：

• 面向用户：只渲染 login.user_interaction.message
• 仅供 Agent：原始 login.login_url、login.flow_id 和
  login.agent_handoff.waitArgv

Agent 必须：

1. 原样渲染 user_interaction.message 中的文字链接，不单独发送 login_url。
2. 立即在后台原样以参数数组启动 waitArgv，禁用 shell。该参数同时绑定本次具体
   --login-flow-id 和原 --login-context-id，不得按会话最新 flow 重建命令。
3. 收到 qxy.agent_login.completed 后原样执行事件中的 resumeArgv。
4. 把完成事件顶层字段视为主企业、enterprises[] 视为同一 Grant 的授权集合、
   activeEnterprise 视为新业务默认企业；不要从自然语言反推内部 ID。

不得向用户展示或要求用户保存 flow_id、服务端 request_id、waitCommand、
原始会话证明、Agent Grant、内部 login-context-id 或原始 JSON。短期 Agent Grant
仅保存在权限为 0600 的私有 flow 文件中，并由 bundled scripts 自动写入
X-QXY-Agent-Grant 请求头；不得作为 MCP 参数、命令参数或普通日志输出。

登录链接默认有效 1 小时，登录完成后的 Agent Grant 默认有效 24 小时。授权内切换使用
同一私有 --login-context-id 调用 list-enterprises / select-enterprise，只改变新业务默认
企业，不创建、轮询或 ACK 新登录，也不替换 Grant；同名或同税号 KPY/BSY 身份必须消歧。
目标不在 enterprises[]、Grant 失效或状态损坏时也不得自动创建第二个页面。只有用户
明确说“配置企业/重新配置企业/增加企业”后，才可用 --switch-account 替换整份企业
配置；它不能用于授权内切换。短期 Grant 过期或无效时保留本地企业集合，停止发送 Grant
Header，并继续使用本地 APIKEY 与精确企业绑定。

选择完成后或申报、缴款业务明确提示税局会话失效时，调用
scripts/managed_login_flow.py ensure。缓存或快速登录有效则继续原业务；需要短信时只请
用户在聊天框输入验证码，再用 submit --sms-code-stdin 通过敏感 stdin 提交。不得询问
手机号、密码、taskId 或内部企业 ID，不得回显、记录或持久化验证码。发送和提交不自动
重放；Grant 失效仍使用首次保存的企业上下文进入聊天验证码流程，不回一次性网页。详细状态机见
references/chat-managed-login.md。

云端或多租户 Agent 必须传稳定且不可猜测的 --login-context-id。该值只在本机生成
SHA-256 指纹；原始会话标识不落盘、不发送给登录服务。将
QXY_AGENT_LOGIN_FLOW_DIR 配置为租户隔离、私有、可写、持久目录。未配置时，bundled
scripts 默认使用 Skill 包外的 ~/.qixiangyun/tax-declaration/agent-login-flows；也可通过
QXY_TAX_DECLARATION_STATE_DIR 统一覆盖私有运行态根目录。普通用户无需配置
QXY_AGENT_LOGIN_* 地址或密钥；这些覆盖项仅用于开发、测试或私有化部署。若本地联调
同时调用业务服务时，必须把 QXY_ROSTER_ENTRY_MCP_ENDPOINT、
QXY_TAX_PAYMENT_MCP_ENDPOINT、QXY_TAX_PAYMENT_CERTIFICATE_MCP_ENDPOINT 与
QXY_AGENT_LOGIN_MCP_ENDPOINT 指向同一可信 MCP 部署，确保它们共享 Agent Grant 存储。

登录链路为：

原业务命令 -> 创建 login_url -> 后台 wait-login -> 原子保存完整企业列表与 Agent Grant
-> ACK -> qxy.agent_login.completed -> resume-flow -> 继续原申报、缴款或完税证明命令

完整多企业响应、私有状态、旧 flow 兼容和授权内选择规则见
references/agent-login-api.md；各 MCP 的企业绑定边界见
references/mcp-services.md。

手工检查登录入口：

python3 scripts/declaration_workflow.py login \
  --login-context-id Agent内部会话ID

后台等待和恢复只由 Agent 使用：

python3 scripts/declaration_workflow.py wait-login \
  --login-context-id Agent内部会话ID \
  --timeout-seconds 3660

python3 scripts/declaration_workflow.py resume-flow \
  --login-flow-id Agent内部flow_id \
  --login-context-id Agent内部会话ID

严格调用规则

1. 所有调用都只能通过 bundled scripts：
   - scripts/mcp_client.py
   - scripts/declaration_workflow.py
   - scripts/enterprise_filing_workflow.py
2. 禁止直接使用 curl、requests、OpenAPI、网页浏览或手写 HTTP 请求
3. 禁止去探测、修改或依赖本地 Claude 的 MCP 配置文件
4. 如果脚本调用失败，直接根据脚本报错处理，不要自行切换到其他调用通道
5. 这个 skill 的目标是“只走 MCP”，不是“只要拿到结果就行”
6. 不得绕过 bundled 登录工作流直接调用 agent_login tools
7. 申报、缴款与完税证明 MCP 调用必须使用当前私有 flow 自动取得的 Agent Grant
8. 登录服务不可用时停止流程并提示稍后重试，不得切换到旧登录链路或收集税局账号密码
9. 不得打包、上传或提交 .agent_login_flows、.checkpoints、.enterprise-checkpoints、
   .pytest_cache、.mypy_cache、__pycache__ 或 .DS_Store；公开输出和 --output
   文件必须脱敏企业、账号和纳税人标识

本机回归测试使用
PYTHONDONTWRITEBYTECODE=1 python3.13 -m pytest -p no:cacheprovider，避免在 Skill
包内生成 pytest 或 Python 字节码缓存。

可用脚本

scripts/mcp_client.py — 原子调用

用于单个服务、单个 tool 的调用。

支持能力：

• 列出服务
• 列出服务下工具
• 查看工具 Schema
• 调用指定工具

scripts/declaration_workflow.py — 闭环调用

用于按固定步骤执行申报、缴款和完税证明闭环，并通过私有 checkpoint 防止缴款中断后重复发起。

适合场景：

• 申报准备闭环
• 标准申报闭环
• 申报核验闭环
• 完整申报闭环
• 明确确认后的税款缴纳闭环
• 完税证明获取与安全下载链接

支持模块

• roster_entry：获取应申报清册
• initialize_data：初始化
• declaration_submission：上传申报数据
• pdf_download：获取 PDF
• declaration_query：申报信息查询
• missing_declaration_check：漏报检查
• tax_payment：税款缴纳
• tax_payment_certificate：获取完税证明并解析

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

调用方式

列出当前 skill 支持的服务：

python3 scripts/mcp_client.py --list-services

检查凭证是否已配置：

python3 scripts/mcp_client.py --check-config

列出某个服务下的工具：

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

以下原子业务调用中的 --login-flow-id 只能由 Agent 从私有完成事件中自动追加，
不能要求用户填写：

发起获取应申报清册：

python3 scripts/mcp_client.py \
  --login-flow-id Agent内部flow_id \
  --login-context-id Agent内部会话ID \
  --service roster_entry \
  --tool initiate_declaration_entry_task_auto \
  --args '{"aggOrgId":"YOUR_AGG_ORG_ID","year":2026,"period":4}'

查询应申报清册任务结果：

python3 scripts/mcp_client.py \
  --login-flow-id Agent内部flow_id \
  --login-context-id Agent内部会话ID \
  --service roster_entry \
  --tool query_roster_entry_task_auto \
  --args '{"aggOrgId":"YOUR_AGG_ORG_ID","taskId":"任务ID"}'

发起初始化任务：

python3 scripts/mcp_client.py \
  --login-flow-id Agent内部flow_id \
  --login-context-id Agent内部会话ID \
  --service initialize_data \
  --tool load_init_data_task \
  --args @/tmp/init-data.json

发起申报信息查询：

python3 scripts/mcp_client.py \
  --login-flow-id Agent内部flow_id \
  --login-context-id Agent内部会话ID \
  --service declaration_query \
  --tool load_declare_info_task \
  --args '{"aggOrgId":"YOUR_AGG_ORG_ID","year":2026,"period":4}'

生成闭环配置模板：

python3 scripts/declaration_workflow.py scaffold-config \
  --year 2026 \
  --period 4 \
  --output /tmp/declaration-config.json

说明：

• 顶层 period 表示申报月份，不是税款所属期月份
• 例如 2026 年 4 月办理 3 月所属期月报时，应传 year=2026、period=4
• init_data.zsxmList[] 如未直接传 ssqQ、ssqZ，可使用本地字段 period_cycle 指定 monthly、quarterly、annual
• init_data 查询阶段会按税种逐个短轮询；“初始化任务还在执行中，请稍后获取”会识别为 pending
• current_pdf.zsxmList 兼容字符串数组或对象数组，脚本会自动归一化为 {"yzpzzlDm": ...} 结构
• 若税种目录已固定周期（如 annual），本地传入冲突的 period_cycle 会直接报错

执行申报准备闭环：

python3 scripts/declaration_workflow.py \
  run \
  --config /tmp/declaration-config.json \
  --steps fetch_roster,init_data

执行完整申报闭环：

python3 scripts/declaration_workflow.py run --config /tmp/declaration-config.json

工作流配置说明见 references/workflow.md

执行企业级申报编排（同一登录可授权多个企业；每个具体申报任务仍须准确绑定其中一家）：

python3 scripts/enterprise_filing_workflow.py scaffold-config \
  --year 2026 \
  --period 4 \
  --output /tmp/enterprise-filing-config.json

python3 scripts/enterprise_filing_workflow.py run \
  --config /tmp/enterprise-filing-config.json

企业级编排说明见 references/enterprise-filing-workflow.md

申报后缴款与完税证明

企业级申报结果中的 payment_preparation.payment_config 可直接交给本 Skill 的
declaration_workflow.py；它默认写入 steps.payment.confirmed=false，不得直接发起扣款。

执行缴款前必须：

1. 向用户展示企业名称、所属期、税种、逐项金额、合计金额及脱敏扣款账户。
2. 明确询问是否缴费；只有用户清楚回复“确认缴费”等同义确认后，才在 Agent 私有配置中
   将 steps.payment.confirmed 改为 true。
3. 使用同一登录上下文执行 payment；不得通过 mcp_client.py 直调发起工具。

确认摘要必须在一次性登录绑定企业后生成。每笔明细至少应从可信申报/税局结果取得
yhzh 或 agreementAccount 之一；若只能取得税种和金额而没有扣款账户，停止在
payment_information_incomplete，不得让用户在聊天中发送完整账号，也不得发起扣款。

python3 scripts/declaration_workflow.py run \
  --config /tmp/payment-config.json \
  --steps payment

缴款发起取得 taskId 后，脚本会先写入权限为 0600 的私有 checkpoint，再查询结果。
中断、超时或查询失败时，只使用 resume --checkpoint 或 query-step 继续查询，禁止重新
执行发起阶段。即使 resume_mode=rerun_failed，失败的缴款也不会自动再次扣款。

不能只凭 businessStatus=3 宣布缴款成功；必须同时核对脚本归一化状态、payState、
实际缴款金额和结果消息。未缴款、金额不一致、失败、处理中或状态不明确时立即停止，
不得继续获取完税证明。

缴款明确成功后，才可启用 certificate 并执行：

python3 scripts/declaration_workflow.py run \
  --config /tmp/payment-config.json \
  --steps certificate

只向用户展示脚本返回的 HTTPS user_download_links。本 Skill 保存的是私有 checkpoint 中
的解析结果和安全下载链接，不宣称已把证明文件永久下载或归档到本地。

配置字段和边界见 references/payment-workflow.md，缴款返回
说明见 references/payment-api-notes.md。

初始化数据时，当前已知本地会提前拦截不支持的税种：

• BDA0610135 个人所得税

输出要求

面向用户只输出：

• 本次办理的企业名称、税款所属期/申报期和税种
• “准备中 / 待确认 / 申报中 / 已完成 / 需要人工处理”等可理解状态
• 用户必须确认或补充的内容
• 失败时的简短原因和可执行下一步
• 可下载业务文件的文字链接

脚本、模块、服务别名、tool、请求参数、aggOrgId/accountId/taskId/businessStatus、原子/闭环
编排方式及原始 JSON 都只供 Agent 诊断。除非用户明确要求技术排障，否则不得展示字段名或
字段值；即使技术排障，也不得展示企业账号标识、凭证、Grant、会话证明或私有路径。

参考文件

• 服务别名与工具映射：references/mcp-services.md
• 参数、轮询和任务状态说明：references/api-notes.md
• 闭环配置说明：references/workflow.md
• 常见申报错误说明：references/common-errors.md
• 缴款与完税证明配置：references/payment-workflow.md
• 缴款返回字段说明：references/payment-api-notes.md
• 缴款常见错误说明：references/payment-common-errors.md