企享云风控报告 Skill
通过企享云 MCP 申请企业风控报告，并查询或等待报告生成结果。所有业务入口都绑定首次一次性网页登录取得并已 ACK 的本地企业集合。初次网页登录不得在对话中收集税局手机号、登录密码、短信验证码或登录 Token；后续税局会话失效时按下述聊天验证码流程接收一次短期短信验证码，不重复打开网页。
用户可见输出
脚本 stdout、结构化错误、login_url、agent_handoff、授权摘要和报告诊断字段都属于
Agent 私有编排资料，不得整包复制给用户。面向用户只输出简短自然语言、必要授权确认和
user_interaction：
- 登录入口只渲染为
[打开登录页面](<实际一次性地址>)，不得显示裸 URL；不要接入
第三方短链服务。 - 需要访问凭证时只说“请把开放平台复制出的完整访问凭证直接发给我”，不得展示环境
变量名、分隔格式、配置文件、stdin/argv、脚本路径或内部检查命令。 - 授权确认只展示企业名称、报告格式、授权范围、用途、留存说明和确认示例；不得展示
企业税号、授权手机号、SHA-256 摘要、intent、路径或 Base64。 - 报告状态只展示可理解的状态和下一步；报告地址用
[下载风控报告](<实际地址>)等文字
覆盖。flow、Grant、内部 ID、tool、原始响应和诊断字段一律不展示。
产品授权终态
业务或登录 MCP 返回 code=505069 且命中已登记的测试期/测试次数文案时，只向用户回复：
“您当前使用的是免费版，该产品的测试使用期已结束。为了不影响您的业务正常开展，建议您前往企享云开放平台选购付费版或进行续费，感谢您的支持！”
命中生产次数/税号数量文案时，只回复：
“抱歉，您的产品生产授权已到期，当前服务已暂停。为确保您的业务持续稳定运行，请尽快前往企享云开放平台完成续费或购买，感谢您的配合！
立即订购或续费”
这是不可重试的 failed 终态：申请、查询或等待命中后立即停止，不重新登录、不索取或重配 APIKEY、不自动重试或继续轮询。不得展示原始响应或原始服务端文案。
前置条件：开放平台凭证
本 Skill 需要企享云开放平台访问凭证。用户尚未申请时，只提供
申请访问凭证。下面的字段、命令和
配置协议均为 Agent 私有，不得转述给用户。首次使用时，本地单用户 Agent 必须显式运行：
python3 scripts/mcp_client.py --check-config --allow-agent-credential-configuration
仅当结构化结果同时返回 configuration_required=true、
credential_delivery=user_to_agent_plaintext 和 local_single_user_only=true 时，Agent 才可
渲染返回的 user_interaction.message，请用户把开放平台复制出的完整原值发到当前对话。
Agent 不回显、不拆分，也不让用户修改配置文件或回复“重试”。用户消息仍可能受当前对话
平台留存策略约束，Agent 不得声称聊天本身不留痕。
Agent 必须原样使用结果中的 agent_configuration.argv 参数数组，以 shell=False 启动配置器，并把
{"QXY_API_KEY":"用户原始输入"} 作为唯一 JSON 字段写入敏感 stdin。APIKEY 不得进入 argv、shell 命令、管道、进程列表、stdout、stderr、日志、临时交接文件或工具输出。配置器只更新当前 Skill 的 .env，原子写入并收紧为 0600，清理旧拆分变量且保留其他配置；成功后 Agent 自动用普通 --check-config 复检，并立即恢复最初的风控报告请求。
真实工具调用返回 AUTH_ERROR 时，不能仅凭该错误断定 APIKEY 输入错误；产品权限、路由或部署 Secret 也可能导致相同结果。只有用户明确确认要替换本地单用户 Skill 的现有凭证后，Agent 才可运行：
python3 scripts/mcp_client.py --check-config \
--allow-agent-credential-configuration \
--request-agent-credential-reconfiguration
仅当结果再次返回上述自动配置契约且 reconfiguration_requested=true 时，才按同一敏感 stdin 流程接收并替换 APIKEY。进程环境或公共、集中托管配置会失败关闭且不返回本地重配契约，必须由部署管理员处理。
未显式传入上述 opt-in 时不得在对话中索取访问凭证。进程环境、公共共享 .env、集中托管、多租户或企业共享环境中的凭证错误属于部署边界，不可由本地配置器覆盖；这些环境必须按租户使用平台 Secret/密钥管理系统，并隔离容器、系统账号、运行态、worker 和日志，禁止多个用户共用同一个 Skill .env。凭证缺失时可引导用户点击申请访问凭证。
固定一次性登录流程
apply、query 和 wait 都必须按以下顺序执行：
- Agent 以当前用户和会话生成稳定、不可猜测的私有
login-context-id。 - 首次运行原业务命令。此时只创建一次性登录页，不调用报告业务工具。
- 只渲染
user_interaction.message中的可点击文字
[打开登录页面](<实际一次性地址>)；不得单独展示login_url、flow_id、服务端
request_id、会话证明、Grant、等待命令或原始 JSON。 - Agent 立即把返回的
agent_handoff.waitArgv原样作为参数数组交给后台任务，禁用 shell。该参数同时绑定本次具体flow_id与原login-context-id，不得按会话最新 flow 重建命令。 - 后台任务输出
qxy.agent_login.completed后，原样执行事件中的resumeArgv，不得让用户输入内部参数。 - 恢复后的工作流把顶层字段视为主企业、
enterprises[]视为同一 Grant 的全部授权企业、activeEnterprise视为新申请默认企业；报告查询仍按任务创建时固定的企业账号校验。
风控报告使用四位申请地区码。网页登录返回企享云公共地区码后，工作流必须按企享云官方
地区码表自动转换：受支持的两位省级码补 00，已经是四位的计划单列市等专项码原样沿用。
不得让用户重复提供可自动转换的地区码，也不得从税号或 GB/T 2260 行政区划推导码值。
只有登录结果缺失、格式异常或服务端明确拒绝转换后的码值时，才暂停并请用户向服务商确认；
用户只看到自然语言提示，不展示内部参数名、登录地区原值或企业标识。
同一 flow 的 poll → Grant 与完整多企业状态原子落盘 → ACK → acked 由跨进程锁串行执行。重复等待任务在取得锁后必须重读本地状态；已 ACK 时只从本地恢复，不得再次 poll 或 ACK。failedEnterprises[] 不进入授权集合。Grant 过期或被拒绝只改变短期 Header 状态，不废弃已 ACK 的企业集合，也不创建新页面。
登录链接默认有效 1 小时，登录完成后的 Agent Grant 默认有效 24 小时；税局自身会话
可能提前失效。授权内切换使用同一私有 --login-context-id 调用
list-enterprises / select-enterprise，不重新登录、不更换 Grant；名称或税号不唯一时必须
结合 KPY/BSY 身份消歧。目标不在列表或状态损坏时也不得自动开页；只有用户明确说
“配置企业/重新配置企业/增加企业”后，才可使用 --switch-account 替换整份企业配置。
授权内选择完成后或报告业务明确提示税局会话失效时，调用
scripts/managed_login_flow.py ensure。缓存或快速登录有效则继续；需要短信时只请用户在
聊天框输入验证码，再用 submit --sms-code-stdin 通过敏感 stdin 提交。不得询问手机号、
密码、taskId 或内部企业 ID，不得回显、记录或持久化验证码。发送和提交不自动重放；
Grant 失效仍使用首次保存的活动企业进入聊天验证码流程，不回一次性网页。详细状态机见
references/chat-managed-login.md。
等待结果为 pending 或本轮超时时，继续使用同一等待参数，不创建新链接。普通用户无需配置任何 QXY_AGENT_LOGIN_* 地址或密钥；QXY_AGENT_LOGIN_MCP_ENDPOINT 与 QXY_RISK_REPORT_MCP_ENDPOINT 只供开发、测试或私有化部署覆盖。本机联调时，登录与风控报告端点必须指向同一可信 MCP 部署，共享同一 Agent Grant 存储与校验边界；HTTP 端点仅可在可信测试网络中配合 QXY_AGENT_LOGIN_ALLOW_HTTP=true 使用。
完整多企业响应、状态迁移与选择规则见
references/agent-login-api.md，业务企业与任务绑定见
references/mcp-services.md。
授权与申请长流程
授权必须在网页已经绑定目标企业之后展示，不能在企业身份未知时先取得笼统同意。
- 先确认报告类型：
1为 PDF、2为 JSON、3为 PDF 和 JSON；同时取得授权材料所需手机号。 - 首次运行
apply时不要传--authorization-consent：
python3 scripts/risk_report_workflow.py apply \
--rpt-type 1 \
--authorization-phone 授权手机号 \
--login-context-id Agent内部会话ID
- Agent 展示登录页并后台等待；恢复后，工作流先根据网页选定企业生成授权书，或复制
--authorization-pdf指定的现有 PDF，再在包外私有目录冻结材料并计算 SHA-256 摘要。即使命令已携带肯定语，首次出现的新意图也只能返回waiting_for_user_input=true，不能直接提交。Agent 私下保留结果中的agent_handoff.authorizationIntentArgv参数数组，不得向用户展示、改写或用 shell 执行。 - Agent 只展示工作流返回的
user_interaction：企业名称、报告格式、授权范围、用途、
留存说明和确认示例。范围包括工商、发票、财务、税务申报、个人所得税申报、费用及
其他企业信息；同时说明税局凭证只在网页登录边界处理，不在对话中收集。完整税号、
授权手机号、authorizationDigest和agent_handoff都是私有绑定资料，不得展示。 - 只有用户在看到这次展示后重新明确肯定同意时，Agent 才使用相同业务参数追加
--authorization-consent，并把上一步agent_handoff.authorizationIntentArgv原样追加到参数数组。缺少或不匹配该私有 intent 参数时，即使命令已带旧肯定语也必须再次展示、不能提交。工作流随后验证精确flow/context、企业及账号、报告类型、授权手机号和冻结 PDF 摘要，再原子消费一次性授权意图并只提交该份冻结 PDF；否定、取消、未同意或含糊回复均不得提交。 - 企业、账号、报告类型、授权手机号、PDF 内容、模板或登录上下文发生变化，以及已消费意图被重放时，必须生成新意图并重新展示；旧肯定回复不能直接提交。
- 申请成功仅表示任务已提交，不代表报告已经生成。保留
taskId/riskRptId供后续查询。 - 若申请结果为
state=authorization_binding_failed或queryAvailable=false，说明报告任务已经创建但服务端查询授权记录未建立。Agent 必须停止，不得执行query/wait，也不得重新申请；只向用户说明保存taskId并联系管理员处理。
登录前传入的同意不会写入恢复参数；网页登录选定企业后仍必须重新展示并确认。CLI 不接受原始授权 Base64，已有材料请使用私有 PDF 文件，避免敏感授权内容进入 argv 或 Agent 事件。
报告申请发出前会持久化派发日志。若网络中断、响应解析失败、服务端成功但缺少 taskId，或进程在结果落盘前中断，均视为 outcome_unknown：当前授权意图保持锁定，Agent 不得自动生成新意图、再次索取同意或重提申请，必须先通过服务端记录或人工支持对账。远端明确返回 taskId 后，即使本地任务绑定保存失败，工作流仍须把 taskId 和本地状态告警返回给 Agent，不能把已成功创建的任务伪装成申请失败。若失败的是服务端查询授权绑定，工作流返回 authorization_binding_failed 人工处理终态；该终态禁止自动查询、等待或重提。
查询与等待
单次查询：
python3 scripts/risk_report_workflow.py query \
--task-id 报告任务ID \
--login-context-id Agent内部会话ID
持续等待：
python3 scripts/risk_report_workflow.py wait \
--task-id 报告任务ID \
--interval-seconds 60 \
--max-attempts 35 \
--login-context-id Agent内部会话ID
任务 ID 必须与当前网页登录企业及账号的本地任务绑定一致。未知任务、其他企业任务或绑定不一致时拒绝查询。pending 和等待超时不等于失败或成功；只按服务返回的明确终态报告结果。
查询完成后，面向用户只说明报告状态和必要下一步，并原样渲染
user_download_links 中的 [下载风控报告](<实际地址>)；不得展示裸地址、
reqId/code/raw、任务绑定、企业账号 ID 或原始 JSON。不在 user_download_links 中的
非 HTTPS/异常地址不得转成链接。
Agent 内部登录命令
以下命令只供 Agent 编排，不向用户展示参数：
python3 scripts/risk_report_workflow.py login \
--login-context-id Agent内部会话ID
python3 scripts/risk_report_workflow.py wait-login \
--login-context-id Agent内部会话ID \
--timeout-seconds 3660
python3 scripts/risk_report_workflow.py resume-flow \
--login-flow-id Agent内部flow_id \
--login-context-id Agent内部会话ID
python3 scripts/risk_report_workflow.py list-enterprises \
--login-context-id Agent内部会话ID
python3 scripts/risk_report_workflow.py select-enterprise \
--login-context-id Agent内部会话ID \
--enterprise-name 用户指定企业名称 \
--sflx KPY
所有运行态默认位于 Skill 包外的 ~/.qixiangyun/risk-insight；设置了
XDG_STATE_HOME 时使用 $XDG_STATE_HOME/qixiangyun/risk-insight。其中登录 flow、报告状态、任务绑定、授权材料和凭证配置锁分别使用独立子目录。部署方可用
QXY_RISK_INSIGHT_STATE_DIR 指向当前租户独享的私有持久根目录；
QXY_AGENT_LOGIN_FLOW_DIR 只覆盖登录 flow，不能替代完整的租户状态根配置。兼容性的
QXY_RISK_REPORT_FLOW_STATE_PATH/QXY_RISK_REPORT_LAST_TASK_PATH 只能指向包外私有文件。目录权限为 0700，flow、任务绑定、状态和授权材料文件为 0600；任何运行态、锁、缓存或生成材料都不得进入 Skill 源目录或发布 ZIP。
严格调用规则
- 只使用
scripts/risk_report_workflow.py执行业务闭环。 - 禁止直接使用 HTTP、OpenAPI、浏览器或手写 MCP 请求调用业务接口。
- 通用
scripts/mcp_client.py仅用于受控调试；业务工具调用必须提供原 Agent 的私有login-context-id，并可同时携带本次具体login-flow-id进行精确绑定；脚本自动绑定网页登录身份和 Grant。 agent_login工具禁止通过通用 CLI 直调。- 不输出密码、验证码、APIKEY 原文、会话证明、Grant、授权书 Base64、完整企业账号 ID 或内部状态路径。
- 风控报告只供业务参考，不构成法律或税务最终意见。
apply_risk_report_auto是可能创建任务的写操作，传输失败时不得自动重放；结果未知时必须锁定派发日志并先对账。只有报告查询、登录 poll 和幂等 ACK 可做有界短重试。
MCP 契约
- 服务：
risk_report - 申请工具：
apply_risk_report_auto - 查询工具：
query_risk_report_result_auto - 申请参数使用 MCP Schema 的 camelCase：
areaCode、rptType、aggOrgId、accountId、sqInfo - 查询参数使用
riskRptId
详细参数和响应见现有 bundled scripts 与参考文件。
