Alert Cert Forms

证件更新流程

⛔ MCP 调用已封装为脚本（AI 禁止裸调 MCP 工具）

本专家所有 MCP 工具调用已封装为 skills/<skill>/references/scripts/ 下的 Python 脚本（共享客户端 skills/_common/mcp_client.py）。AI 只通过 execute_command 运行脚本获取结果，禁止直接裸调 MCP 工具。

脚本已内置：参数构造（字段类型 / 嵌套结构 / repeated 裸数组等）、入口守卫（has_pending_review / 审批中）、一致性校验（no≠old_no / 图片域名）、失败上抛（绝不降级）。 本地 references/tools/<tool>.md 仍为脚本行为的权威文档，改动脚本须同步更新。

概述

"证件更新"能力，接管以下证件的更新流程（对应 OrgCertUpdateType 枚举）：

核心特征：

• 入口守卫 — has_pending_review=true 时直接告知用户，不引导上传截图（审批中禁提）
• 先传后识别 — 用户直接上传截图，由 alert-ocr 自动判定类型
• 批量收集，一次提交 — 用户可完成多类证件的 OCR 后一次性提交 update_org_cert(cert_types=[...])
• UI 内直接提交 — OCR 结果经 build_cert_ui_params.py 封装后调起 UI，用户核对/修改后在 UI 内直接完成提交；UI 回 submit.next_step 通知 Agent 进入提交后流程（命名步骤「提交证件到远程」）
• 整组覆盖语义 — 一类证件出现在 cert_types 中则该类全部字段被入参覆盖，Skill 必须把该类所有 K-V 填齐

触发场景

由专家在以下情境加载：

• 用户直接对话："我要更新证件"、"证件到期了怎么办"等

上下文（可能已知）：

• 待更新证件清单（含 cert_type +剩余天数）—— 通过 ../alert-info-fetcher 调query_todo_detail.py 获取

工作流程

Step 0: 入口守卫（has_pending_review）

⭐ 入口守卫已由「任务零」统一负责：query_todo_detail.py 内置 updatable / has_pending_review 守卫，只有真正可处理的项才会进 todo_cards，因此正常进入本任务时 has_pending_review 必为 false。本步骤仅作独立直接加载时的兜底。

若本 skill 未走任务零、被独立直接加载，则先确认当前无审批中申请单：

true 时的话术：

当前机构信息有申请单待审批, 审批完成后才能提交证件更新。

⛔ 硬约束：has_pending_review=true 时绝对不能调用 update_org_cert（无论 cert_types 里放什么），也不能引导用户走OCR 消耗时间。

Step 1: 提示上传证件原图

⭐ 进入本任务第一时间（发起任何工具调用之前）MUST 先告知用户下一步预期："已为您进入证件更新流程，下一步需要您上传证件照片，上传后我会自动识别证件类型和关键字段"。⛔ 不得静默发起工具调用只让用户看"过程消息"。

到期清单：由「任务零」query_todo_detail.py 提供（含 cert_type + 剩余天数），本步骤直接展示。

⚠️ 身份证标签：根据首次查询脚本输出的 org.type_of_organization 决定（等价于 institution_type，脚本已随 org 字段返回）：

• type_of_organization ∈ {1, 2} → "法人身份证"
• type_of_organization == 3 → "专项基金负责人身份证"

Step 2: 类型粗判 + 云 OCR（每张图独立处理）

对每张上传的图，加载 skills/alert-ocr，走两步：

1. 类型粗判（strategy_id: cert_type_detection，LLM 视觉）→ 参考 ../alert-ocr/references/cert-type-detection.md

   • cert_type_detection 只是策略标签，不是工具、脚本或 MCP 名称；每个唯一图片路径读取一次，当前模型直接按 Prompt 粗判，禁止搜索所谓视觉工具
   • 输出 cert_type ∈ {1, 2, 3-front, 3-back, unknown}
   • unknown → 提示用户重传，不进入云 OCR

2. 云 OCR 一键 pipeline（engine_type: cloud_cert_pipeline）：一键运行脚本完成「取临时凭证 + 上传 + 提交检测 + 轮询」全链路（详见 ../alert-ocr/SKILL.md）

   cd skills/alert-ocr/references/scripts && python3 remote_ocr.py <文件> --private 0|1 --ocr_type 0|1
   

   • 身份证（3-front/3-back）→ --private 1 --ocr_type 1（私有桶，COS 原始域名）；其他证件 → --private 0 --ocr_type 0（公有桶，CDN 域名）
   • --private 与 --ocr_type 必须同为 0 或同为 1（身份证=1、其它=0），否则脚本直接报错
   • 脚本返回上传链接 + K-V 识别结果；30 秒无结果即失败退出（不降级），需重识别时重新运行本脚本

Step 3: 类型判定结果分支

⚠️ 身份证正反面合并：

• 正面提供：name / id_card / idcard_front
• 反面提供：有效期起/ 有效期止 / 长期标记 / idcard_back
• 两面齐后由 Skill 层拼接 id_card_validity（格式 YYYY-MM-DD~YYYY-MM-DD 或 YYYY-MM-DD~长期，见 references/idcard.md）

Step 4: 排队检查（一起提交）

若到期清单里还有其他证件未上传，用 AskUserQuestion 弹出可点击二选一（不得用纯文本代替）：提示语"提交后需等运营审核通过才能更新其他证件，建议一起提交"，选项为「继续上传其他证件」/「直接提交」。

AskUserQuestion(
  question: "提交后需等运营审核通过才能更新其他证件, 建议一起提交。是否继续上传其他证件？",
  header: "提交确认",
  multiSelect: false,
  options: [
    { label: "[继续上传其他证件]回到上传步骤补全剩余证件", description: "[继续上传其他证件]回到上传步骤补全剩余证件" },
    { label: "[直接提交]仅提交已识别完成的证件", description: "[直接提交]仅提交已识别完成的证件" }
  ]
)

• 用户选"继续上传其他证件" → 回 Step 2 上传剩余证件
• 用户选"直接提交" → 进入 Step 5（本步骤前的识别结果只含已完成的类）
• ⚠️ 目的：审批中禁提（has_pending_review），一旦提交进入审批，剩下的证件必须等审批完成后才能再更新，所以要主动提示"一起提交"，避免用户误以为可以分多次提交

Step 5: 调起证件更新确认 UI（open_org_cert_update_review_ui）

触发时机（满足其一）：

• 全部到期证件都已识别完成（用户本轮上传并 OCR 的证件已覆盖任务零给出的到期清单，无遗漏）
• 用户在 Step 4 明确选择「直接提交」（仅提交已识别完成的证件；⚠️ 单面身份证等未完整识别的类，按下方红线整体排除出 cert_types，不得只传单面）

核心动作：把 cert_types + 各块 K-V 组装成 org_cert_update_review 业务体（JSON 文件，字段格式见 references/tools/org_cert_update_review_input.md），运行封装脚本（脚本做守卫复查 + 类/块一致性 + 身份证域名校验，成功时把 UI 入参小 JSON（仅 caller_expert_id + data_cache_id 两字段）写入 --output 文件）：

⛔ 禁止不跑脚本、自己读 inputSchema 拼参直接调 open_org_cert_update_review_ui。正确流程（三步）：

1. AI 先把已完成 OCR 的证件 K-V 打包成 org_cert_update_review 业务体（JSON 文件）；⚠️ cert_types 必须是裸 int 数组（如 [1, 3]），禁止包成对象——脚本会强制校验
2. 运行下方脚本生成 UI 入参文件（--output）
3. 读取 --output 文件内容，作为 open_org_cert_update_review_ui 工具的 parameters 调用（⛔ 不要自行重新组装、不要读 inputSchema、不要往里追加业务字段）

cd skills/alert-cert-forms/references/scripts && python3 build_cert_ui_params.py --json-file <org_cert_update_review.json> [--output <cert_ui_params.json>]

红线（MUST 遵守）：

• ⛔ 未完成 OCR 的类不进 cert_types，其块也不传，更不传空对象占位 —— 否则整组覆盖语义会清空后端该类数据
• ⛔ cert_types 数量为 0 时禁止调用 open_org_cert_update_review_ui
• ⛔ 身份证正反面都齐才能把 3 放进 cert_types；身份证 URL 必须用 COS 原始域名（私有桶），其余证件用 CDN 域名

调起后行为（对齐 alert-expert 编排层「命名步骤：提交证件到远程」）：

• ✅ open_org_cert_update_review_ui 调用返回成功后，本轮立即结束——只输出一句极简提示（如"证件信息已识别完成，已为您打开确认页面，请在页面中确认并提交"），不再输出任何其它文字或发起任何工具调用
• ✅ 然后等待 Agent 收到 submit.next_step 重新调度执行命名步骤 提交证件到远程（⛔ 不是"UI 直接结构化回调"）
• ❌ MUST NOT 自行轮询 / 猜测用户是否已提交
• ❌ MUST NOT 收到 submit.next_step 后再次调用任何提交接口（提交已在 UI 内完成，命名步骤「提交证件到远程」只进入提交后流程）

命名步骤：提交证件到远程（UI 内提交后由 Agent 依据 submit.next_step 重新调度触发，进入提交后流程）

⭐ 步骤名 MUST 逐字符为 提交证件到远程 —— submit.next_step 固定文案里点名这个名字，改一个字 Agent 就没法正确重新调度到本步骤。

触发语义：用户在 UI 页面点"提交"时，提交动作已由 UI 内直接完成（后端 update_org_cert 接口在 UI 侧校验并提交）。UI 随后回一句 submit.next_step 文案给 Agent，仅作为"已提交完成"的通知信号，不携带需要 Agent 再处理的数据。

执行：收到 submit.next_step 后，MUST NOT 再调用任何提交接口（提交已在 UI 内完成），直接进入提交后流程：

1. Step 6：向用户输出成功话术（已提交 N 项证件更新、进入审核）
2. 若还有未提交的证件，按 Step 6 提示待审核完成后再次进入

⚠️ 覆盖语义：cert_types 含的每类必须全填，未填字段会被覆盖为空——此语义由 UI 内提交时后端接口按 cert_types 覆盖处理，Agent 无需干预。

Step 6: 提交后话术

提交成功：

✅ 已提交 [N] 项证件更新, 预计运营 1-3 个工作日审核。
审批完成前无法再次提交证件更新。

若 cert_types_done ⊊ cert_types_pending（用户选了"就先提交"，还有未上传的；cert_types_pending = 任务零给出的到期清单里的全部 cert_type 集合，cert_types_done = 本轮已完成 OCR 并计入的 cert_type 集合）：

⚠️ 本次未提交的证件仍在到期清单中:
- [missing 的可读标签]
待运营审核完成后, 您可再次进入本流程更新剩余证件。

⚠️ 提交失败由 UI 页面自行提示处理（Agent 不感知、不处理失败分支）；Agent 收到 submit.next_step 即视为提交成功。

铁律

• ❌ has_pending_review=true 时仍引导用户上传截图 （应直接告知结束）
• ❌ 让用户"先选证件类型再传图"（新流程反了）
• ❌ 用 LLM 视觉替代云OCR 做主识别（会失去 K-V 结构化能力）
• ❌ K-V 校验异常时不提示用户就往前走
• ❌ 收到 submit.next_step 后再次调用任何提交接口（提交已在 UI 内完成）
• ❌ 跳过 UI 二次确认，直接用 OCR 原始 K-V 提交（用户没机会核对/修改）
• ❌ cert_types 中包含某类但对应字段块部分为空（覆盖语义会导致空字段被清空）
• ❌ cert_types 中不包含某类但仍传对应字段块（误伤覆盖）
• ❌ permanent=1（长期）时仍传 end_date 非空值
• ❌ 身份证走公有桶 / 用 CDN 域名（必须私有桶 + COS 原始域名）
• ❌ 法人证书 / 公开募捐证书走私有桶（应用公有桶 + CDN 域名）
• ❌ 自行区分"法人身份证"vs"专项基金负责人身份证"（统一走 idcard 字段块，服务端判定）
• ❌ id_card_validity 用旧格式 YYYY.MM.DD-YYYY.MM.DD（应用 ~ 分隔的新格式）
• ❌ 提交成功后立即再提交另一类（此时 has_pending_review 已变 true，会被守卫拦截）
• ❌ 用户上传后未走完整流程就先发到远程存储（COS 上传是必需的写外部动作，但只在 alert-ocr Step 2 触发；update_org_cert 之前不再有远程写）
• ❌ 在调起 UI（Step 5）之前，把 OCR 识别问题（类型不明确、K-V 校验异常等）处理成"拒绝调用 UI/终止流程"的硬阻断且不给继续路径——真正的强制校验由 UI 前端 + 后端接口在提交时完成；调起 UI 前最多"提示 + 让用户手动纠正/确认后继续"
• ❌ 不调 open_org_cert_update_review_ui，改在对话里让用户逐字段核对

📌 语法级约束（cert_types 裸 int 数组、int32 传数字、图片域名、身份证正反面）已写入 references/tools/org_cert_update_review_input.md，由 build_cert_ui_params.py 强制，无需在此重复。

特殊情况处理

数据主权与隐私合规

• 用户上传的证件截图：只在会话内使用（走 alert-ocr → COS 上传是必需的写外部动作，但不落地到 workbuddy 侧）
• OCR 中间结果（K-V JSON）：只在会话内展示给用户核对（通过 UI 二次确认），用户在 UI 内点"确认提交"即完成提交
• 身份证 K-V（含身份证号、姓名）：属于敏感信息，仅在当前上传者本人的会话内展示，不跨会话缓存

参考文件

• references/tools/org_cert_update_review_input.md — ⭐ build_cert_ui_params.py 的 --json-file 输入格式（org_cert_update_review 业务体：3 个块的字段表、类型硬约束、输入文件示例）
• references/tools/open_org_cert_update_review_ui.md — ⭐ 调起证件更新确认 UI（顶层两字段入参、缓存完整 JSON 形状、"结构里没有的两样东西"、UI 主校验职责、回调机制）
• references/cert-kv-validation.md — K-V 合理性校验规则（用于Step 2 类型自检）
• references/legal-registration.md — 社会组织法人登记证书字段块（cert_type=1）
• references/fundraising-cert.md — 慈善组织公开募捐资格证书字段块（cert_type=2，仅公募机构）
• references/idcard.md — 负责人身份证字段块（cert_type=3，含正反面合并 + id_card_validity 拼接）
• OCR 引擎：../alert-ocr/SKILL.md（三步 pipeline + 类型粗判）