申报 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

凭证读取优先级：

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
3. 在 skill 根目录或公共父目录创建 .env：

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

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

严格调用规则

1. 所有调用都只能通过 bundled scripts：
   • scripts/mcp_client.py
   • scripts/declaration_workflow.py
2. 禁止直接使用 curl、requests、OpenAPI、网页浏览或手写 HTTP 请求
3. 禁止去探测、修改或依赖本地 Claude 的 MCP 配置文件
4. 如果脚本调用失败，直接根据脚本报错处理，不要自行切换到其他调用通道
5. 这个 skill 的目标是“只走 MCP”，不是“只要拿到结果就行”
6. 运行 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