申报 MCP Skill

通过企享云申报 MCP 完成申报准备、申报执行和申报后核验。

前置依赖：登录 Skill

执行申报前必须先完成登录 skill：

依赖 skill：qixiangyun-tax-login-skill
先用登录 skill 完成企业账号登录就绪校验
登录成功后会在 skills 仓库根目录生成共享登录态 .qxy_login_state.json
当前申报 workflow 启动时会自动检查该登录态

如果没有安装 qixiangyun-tax-login-skill，或没有共享登录态，申报脚本会直接报错并提示先安装/先登录。

前置条件：凭证配置

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

client_appkey
client_secret

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

凭证读取优先级：

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

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

询问用户的 client_appkey 和 client_secret
如果用户没有凭证，提示： appKey和appSecret请注册企享云开放平台申请 https://open.qixiangyun.com

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

QXY_CLIENT_APPKEY=用户提供的appkey
QXY_CLIENT_SECRET=用户提供的secret

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

严格调用规则

所有调用都只能通过 bundled scripts：
- scripts/mcp_client.py
- scripts/declaration_workflow.py
禁止直接使用 curl、requests、OpenAPI、网页浏览或手写 HTTP 请求
禁止去探测、修改或依赖本地 Claude 的 MCP 配置文件
如果脚本调用失败，直接根据脚本报错处理，不要自行切换到其他调用通道
这个 skill 的目标是“只走 MCP”，不是“只要拿到结果就行”
运行 scripts/declaration_workflow.py run ... 前，必须先由 qixiangyun-tax-login-skill 产生共享登录态

可用脚本

`scripts/mcp_client.py` — 原子调用

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

支持能力：

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

`scripts/declaration_workflow.py` — 闭环调用

用于按固定步骤执行申报闭环。

适合场景：

申报准备闭环
标准申报闭环
申报核验闭环
完整申报闭环

支持模块

roster_entry：获取应申报清册
initialize_data：初始化
declaration_submission：上传申报数据
pdf_download：获取 PDF
declaration_query：申报信息查询
missing_declaration_check：漏报检查

详细映射见 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

发起获取应申报清册：

python3 scripts/mcp_client.py \
  --service roster_entry \
  --tool initiate_declaration_entry_task_auto \
  --args '{"aggOrgId":"YOUR_AGG_ORG_ID","year":2026,"period":4}'

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

python3 scripts/mcp_client.py \
  --service roster_entry \
  --tool query_roster_entry_task_auto \
  --args '{"aggOrgId":"YOUR_AGG_ORG_ID","taskId":"任务ID"}'

发起初始化任务：

python3 scripts/mcp_client.py \
  --service initialize_data \
  --tool load_init_data_task \
  --args @/tmp/init-data.json

发起申报信息查询：

python3 scripts/mcp_client.py \
  --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

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

BDA0610135 个人所得税

输出要求

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

当前使用的脚本
当前所属模块
实际调用的服务别名和 tool 名称
请求中的关键业务参数
返回中的 aggOrgId、taskId、businessStatus
当前是“原子调用”还是“闭环流程”
若失败，给出可执行的下一步建议

参考文件

服务别名与工具映射：references/mcp-services.md
参数、轮询和任务状态说明：references/api-notes.md
闭环配置说明：references/workflow.md
常见申报错误说明：references/common-errors.md