前言¶

在 Agent 里做企业税务申报，常见做法是让模型自己拼 HTTP、curl 或 OpenAPI，调用路径容易发散，税局登录与企业上下文也难稳定复用。下面介绍 SkillHub 上的「企业税提交与纳税申报」（@user_bbae3f97/qixiangyun-tax-declaration-skill，当前版本 1.0.9），它通过企享云 MCP 和包内 Python 脚本固定调用面，把应申报清册、初始化、申报上传、PDF、查询、漏报检查，以及可选的缴款与完税证明，收敛成可编排的闭环；税局侧首次授权则走一次性 HTTPS 登录页，再由私有 flow、后台等待与短期 Agent Grant 接回业务。

这是什么¶

定位：面向需要「先拿到税局企业账号上下文、再按步骤申报与核验」场景的 Agent Skill，分类为 professional，来源 community，发布者为 user_bbae3f97。SkillHub 页面标注 requires_api_key=true。

维护与分发：技能坐标 @user_bbae3f97/qixiangyun-tax-declaration-skill；展示页与 API 入口分别为 SkillHub 技能页 与 官方地址。截至页面抓取信息，评分为 100000，下载约 1361 次。

要解决的问题：在 Agent 内完成申报准备、执行、核验，以及经用户明确确认后的缴款与完税证明获取，且禁止用 Bash/curl/手写 HTTP 绕过包内脚本直连企享云接口。

核心功能¶

经 Skill 包内 SKILL.md 与参考文档核实，能力大致分为三层。

MCP 业务模块¶

两类脚本入口¶

1. scripts/mcp_client.py：按服务别名做单次 tool 调用（列服务、列工具、看 Schema、调工具）。
2. scripts/declaration_workflow.py：按 JSON 配置跑申报/缴款/证明闭环，支持 checkpoint，避免缴款中断后重复发起扣款。
3. scripts/enterprise_filing_workflow.py：同一登录下多企业场景的申报编排（每个具体任务仍须绑定到其中一家企业）。

登录与企业上下文¶

所有申报、缴款、完税证明命令须先通过内置 agent_login MCP 创建或恢复本地企业配置：

• 首次：脚本返回一次性 login_url；用户在外部 HTTPS 网页完成税局登录并选择企业与办税账号；Agent 在后台按返回的 waitArgv 等待，收到 qxy.agent_login.completed 后执行 resumeArgv 继续原命令。登录链接默认有效 1 小时；完成后的 Agent Grant 默认有效 24 小时，保存在权限 0600 的私有 flow 文件中。
• 会话失效后：不再要求用户在对话里提供税局密码；通过 scripts/managed_login_flow.py 走聊天验证码流程（详见包内 references/chat-managed-login.md）。

Skill 明确要求：未经用户明确确认绝不发起扣款；缴款前须展示企业、所属期、税种、金额与脱敏扣款账户，并在配置里将 steps.payment.confirmed 设为 true 后才可执行 payment 步骤。

安装与启用¶

1、安装 SkillHub CLI（若尚未安装）¶

command -v skillhub && skillhub --version

未安装时可按 SkillHub 安装说明 执行官方安装脚本。

2、安装本 Skill¶

安装时必须用 --dir 指向当前 Agent 的 skills 目录，否则默认落在 ./skills/ 可能不会被识别：

skillhub install @user_bbae3f97/qixiangyun-tax-declaration-skill --dir <skills 目录>

常见路径（摘自 SkillHub 安装文档）：

• Cursor：~/.cursor/skills/
• Claude Code：~/.claude/skills/
• Codex：~/.codex/skills/ 或项目下的 .agents/skills/

也可让 Agent 按 SkillHub 页面提示，参照 https://skillhub.cn/install/skillhub.md 完成安装。

3、配置企享云访问凭证¶

本 Skill 依赖企享云开放平台访问凭证（标签 requires_api_key=true）。未申请时可在 企享云开放平台 申请。

Agent/部署侧按优先级读取：进程环境 → 当前 Skill 目录下的 .env → qixiangyun-skill/.env，环境变量名为 QXY_API_KEY（完整开放平台复制值）。本地单用户场景可用脚本显式检查：

python3 scripts/mcp_client.py --check-config

需要引导用户在聊天中提交凭证时，须使用 --check-config --allow-agent-credential-configuration，并严格按脚本返回的 agent_configuration.argv 与 sensitive_stdin=true 传入，不得把密钥写入命令行参数或日志。

4、可选运行态目录（多租户/私有化）¶

• QXY_AGENT_LOGIN_FLOW_DIR：租户隔离、可写的 Agent 登录 flow 目录。
• QXY_TAX_DECLARATION_STATE_DIR：统一覆盖私有运行态根目录；未配置时默认使用 ~/.qixiangyun/tax-declaration/agent-login-flows。
• 联调时若同时调用业务与登录 MCP，需将 QXY_ROSTER_ENTRY_MCP_ENDPOINT、QXY_TAX_PAYMENT_MCP_ENDPOINT、QXY_TAX_PAYMENT_CERTIFICATE_MCP_ENDPOINT 与 QXY_AGENT_LOGIN_MCP_ENDPOINT 指向同一可信部署，以共享 Agent Grant 存储。

安装后阅读技能包内 SKILL.md 与 references/ 下的 workflow、登录与缴款说明，再让 Agent 加载该 Skill。

典型用法¶

以下命令均在已安装的技能包根目录执行，且假设 Agent 已从私有登录完成事件中自动注入 --login-flow-id 与 --login-context-id（不得要求终端用户手填这些 ID）。

探查服务与凭证¶

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 \
  --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"}'

说明：顶层 period 表示申报月份，不是税款所属期月份。例如 2026 年 4 月办理 3 月所属期月报时，应传 year=2026、period=4。

闭环申报：生成配置并执行¶

生成配置模板：

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

仅做申报准备（清册 + 初始化）：

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

完整申报闭环（默认步骤见 references/workflow.md）：

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

多企业编排可先 scaffold 再 run：

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

缴款与完税证明（须用户确认）¶

用户明确确认缴费后，在 Agent 私有配置中将 steps.payment.confirmed 改为 true，再执行：

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

缴款成功且状态核对通过后，方可执行证明步骤：

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

面向用户只应展示脚本返回的 HTTPS user_download_links 等形式的安全下载链接，不宜铺开原始 URL 或内部 taskId。

适用场景与注意¶

适合谁

• 财税、代账或企业 IT 场景下，希望 Agent 只通过 MCP + 包内脚本完成申报链路，避免模型自行发散 HTTP 调用。
• 需要标准化「登录 → 清册 → 初始化 → 申报 → PDF/查询/漏报检查 →（可选）缴款与证明」的编排与 checkpoint 恢复。

调用约束（Skill 强制）

1. 禁止 curl、requests、OpenAPI 或手写 HTTP 直连企享云；禁止绕过 bundled 登录流直接调 agent_login tools。
2. 禁止探测或修改本地 Claude/Cursor 的 MCP 配置文件来「凑合」出结果。
3. 脚本失败时按报错处理，不要私自换通道。
4. 不得向用户展示 flow_id、Agent Grant、checkpoint 路径、原始 JSON 或环境变量名；登录入口在对话中应以 Markdown 链接形式给出，不展示裸 URL。
5. 产品授权终态（如 code=505069 的固定文案）不可重试，应原样提示用户前往企享云开放平台续费或选购付费版。
6. 初始化阶段本地会拦截不支持的税种，例如 BDA0610135（个人所得税）。

环境与合规

• 需要有效的 QXY_API_KEY 及企享云产品授权；免费版测试期或生产授权到期时，业务会按 Skill 约定返回固定提示并终止流程。
• 云端或多租户部署必须为每个租户使用稳定、不可猜测的 --login-context-id，并配置隔离的 flow 目录。
• 包内回归测试文档建议使用 PYTHONDONTWRITEBYTECODE=1 python3.13 -m pytest -p no:cacheprovider，与日常 Agent 调用相互独立。

结尾¶

「企业税提交与纳税申报」把企享云申报相关 MCP 能力收进固定脚本与闭环配置，用一次性网页登录和私有 flow 解决企业上下文问题，适合在 Agent 里做可审计、可恢复的申报与核验流程。安装与详情见 SkillHub：https://www.skillhub.cn/skills/user_bbae3f97/qixiangyun-tax-declaration-skill，API 入口：https://api.skillhub.cn/user_bbae3f97/qixiangyun-tax-declaration-skill。