ahang1598 OCR 能力
⛔ 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/scripts/*.py的 docstring 与实现为准，改动脚本须同步更新其 docstring。
概述
专家内部使用的 OCR 封装，采用混合路由策略：
- 证件类（法人登记证书 / 慈善组织公开募捐资格证书 / 负责人身份证） → 走后端提供的 3 步云 OCR pipeline（对应 3 类
OrgCertUpdateType枚举：1、2、3） - 备案号 → 走 codebuddy 多模态视觉能力 + prompt 约束
⚠️ 证件类型口径统一：cert_type=3（负责人身份证）在服务端按机构类型判定是"法人身份证"还是"专项基金负责人身份证"，Skill 层不做区分，统一走 idcard 字段块（见 alert-cert-forms/references/idcard.md）。
触发场景
仅由预警专家的其他 skill 内部调用：
alert-cert-forms调证件类三步 pipelinealert-record-forms调 LLM 视觉
识别策略路由
strategy_id |
执行方式 | 参考 |
|---|---|---|
cloud_cert_pipeline |
调用后端 3 步云 OCR pipeline（COS 上传 → 提交检测 → 轮询结果） | 见下方“三步 pipeline”章节 |
cert_type_detection |
当前模型读取证件图片并进行类型粗判 | references/cert-type-detection.md |
llm_vision_record |
当前模型读取备案表图片并按 prompt 提取字段 | references/llm-vision-record.md |
⛔
strategy_id只是流程路由标签，不是工具名、脚本名、函数名或 MCP 名称。cert_type_detection与llm_vision_record均由当前模型直接完成视觉理解，禁止搜索或调用名为cert_type_detection、llm_vision_record、LLM OCR、multimodal的额外工具。
LLM 视觉策略统一执行契约
- 优先读取用户消息提供的
image_local_path；每个唯一图片路径在正常流程中只调用一次图片读取能力。 - 图片读取返回后，判断是否成功的唯一依据是「你自己是否实际看到了图片的视觉内容（能否描述图片里有什么）」——只要你能感知到图片内容，就是
image_loaded=true，已获得像素输入；这不等于字段提取已经完成。⛔ 不要被返回文本里的技术措辞（如 "unknown""stored at""blob" 等图片来源/存储说明）误导成"没读到图片"——那些不是失败信号。 - 图片载入后，当前模型立即按对应 reference prompt 完成类型判断或字段提取，不再执行工具发现、能力搜索或引擎切换。
- 只有图片读取明确返回拒绝/错误字样（"文件不存在""格式不支持""无法呈现图片""图片内容被过滤""当前模型不支持图片"等）、且你确实看不到图片内容时，才能记为
image_loaded=false并提示用户重传。⛔ 严禁在已经能看到图片内容的情况下，仅凭返回文本里的 "unknown""stored at" 等措辞就宣称"不支持图片/内容被过滤"；不得因工具列表中没有视觉工具而宣称无法识别。 - 多图场景按唯一图片路径逐张载入：备案号主表与合作方图各最多读取一次；正常读取次数应等于唯一图片路径数量。
- 同一路径仅在明确读取失败且用户要求重试时允许再次读取；结构化 JSON 解析失败只重新结构化一次，不重复读取图片。
⚠️ 云 OCR 走 pipeline 而非单一接口：不同于 LLM 视觉策略，实际后端将证件 OCR 拆分为 3 步（上传 → 提交 → 轮询），需 Skill 层承担编排。
三步 pipeline（证件类专用，已封装为一键脚本）
⛔ AI 禁止裸调
get_org_cos_credential/get_org_ocr_data/get_org_ocr_result，一律运行封装脚本。
一键运行（凭证 → 上传 → 提交 → 轮询 全链路）
cd skills/alert-ocr/references/scripts && python3 remote_ocr.py <文件> --private 0|1 --ocr_type 0|1
脚本内部依次完成：取 COS 临时凭证 → 上传 → get_org_ocr_data 提交 → 轮询 get_org_ocr_result 直到 state=1，直接返回：
{ "success": true, "access_url": "<上传链接>", "key": "<任务key>", "fields": [{"name":"...","value":"..."}], "original_data": {...} }
关键规则（脚本已强制）：
- 身份证必须走私有桶（
--private 1）→ 访问链接用 COS 原始域名；其他证件走公有桶（--private 0）→ CDN 域名 --private与--ocr_type必须同为 0 或同为 1（身份证=1，其它=0），否则脚本直接报错- 仅支持图片（jpg/jpeg/png）和 PDF（pdf）
- 轮询策略：5 秒/次，30 秒总超时；超时即失败退出，不静默降级（由调用方决定策略）
- 失败恢复：轮询超时须从 Step 1（即重新运行本脚本）重来
（如需仅上传不识别，仍可运行 upload_cos.py <文件> --private 0|1。）脚本参数与行为详见 references/scripts/upload_cos.py 与 references/scripts/remote_ocr.py。
LLM 证件视觉分支
strategy_id: cert_type_detection 由当前模型执行：按上方视觉策略统一契约载入单张证件图片，再依据 references/cert-type-detection.md 粗判证件类型。它不是可调用工具，不得搜索同名能力。完整 K-V 识别仍须进入云 OCR pipeline。
LLM 备案号视觉分支
strategy_id: llm_vision_record 由 alert-record-forms 调用：按上方视觉策略统一契约载入 1～2 张备案表图片，再依据 references/llm-vision-record.md 生成精简 record_input.json。它不是可调用工具，不得搜索同名能力。
备案号视觉分支必须按以下边界交付结果：
- 图片载入完成只得到
IMAGE_LOADED，不得直接组装 UI 业务 JSON。 - 当前模型提取字段，并合并用户选项目时已保存的
context，生成 schema 2.0 的record_input.json。 - 输入文件只落一份，位于当前工作目录（cwd）；不生成
raw_ocr_text、evidence、独立校验文件、项目上下文文件或 UI 参数文件。 no与会话selected_old_no的提示和用户确认先由 Agent 完成；确认后调用alert-record-forms/references/scripts/run_record_ui.py一次完成校验、实时守卫、缓存和 UI 两字段输出。- 脚本终态自动清理输入文件；stdout 不输出业务字段或图片原文。
云 OCR pipeline vs LLM 视觉
| 维度 | 云 OCR 三步 pipeline | LLM 视觉（llm-vision-record.md） |
|---|---|---|
| 覆盖对象 | 证件类（登记证 / 募捐资格证 / 身份证） | 备案号 |
| 精度 | 高（专业训练模型） | 中（依赖 prompt 约束） |
| 结构化 | K-V 强结构（后端解析） | K-V 弱结构（LLM 从 prompt 中提取） |
| 延迟 | 5-30 秒（异步） | 秒级（同步） |
| 图片依赖 | 需 COS 上传后的链接 | 直接传图片本体（多模态） |
| 适用场景 | 版式复杂、字段多 | 版式规整、字段少 |
输出契约
云 OCR pipeline
云 OCR 脚本继续使用其现有返回结构：success、fields、original_data，失败时包含实际错误信息。不得把云 OCR 返回形状与 LLM 视觉 envelope 混用。
备案号 LLM 视觉
备案号视觉提取只允许使用 references/llm-vision-record.md 定义的精简输入：
{
"schema_version": "2.0",
"strategy_id": "llm_vision_record",
"source": {"image_count": 1, "has_partner_image": false},
"context": {
"id": 12345,
"org_no": "100027",
"org_name": "当前机构",
"selected_old_no": "当前备案号",
"quality_warning_confirmed": false,
"confirmed_charity_org_name": ""
},
"fields": {},
"quality": {"confidence": "high", "uncertain_fields": [], "warnings": []}
}
⛔ 禁止输出旧版扁平结构或生成 raw_ocr_text/evidence；禁止在 Agent 完成质量和编号提示前调用单步脚本。
约束原则
- 不静默降级：三步 pipeline 任一步失败时不自动切换 LLM 视觉，返回错误由调用方（alert-cert-forms）决定策略
- 多张图独立处理：一次调用可传多张图，每张独立走三步 pipeline（不合并 taskKey）
- 不生成 OCR 原文：备案号快速路径只输出业务字段和机器质量代码，不生成
raw_ocr_text或evidence - 不修改字段值：视觉阶段只提取；格式归一化由单步脚本完成
- 身份证必走私有桶：private=1，且访问链接用 COS 原始域名（不能用CDN）
特殊情况处理
| 情况 | 处理方式 |
|---|---|
| COS 临时凭证接口超时 | success: false, failed_at_step: upload, 由调用方提示用户重试 |
| COS 上传超时（运行 upload_cos.py） | success: false, failed_at_step: upload, 可重试 1 次 |
| 提交 OCR 检测失败 | success: false, failed_at_step: submit |
| 轮询超过 30 秒无结果 | success: false, failed_at_step: poll, 需从 Step 1 重来 |
| LLM 视觉识别不出字段 | fields 中缺失的字段为 null, confidence: low |
| 图片格式不支持 | success: false, 上传前拦截 |
| 图片模糊/过暗 | 云 OCR 可能返回低置信度或报错，LLM 视觉可能置信度低 |
铁律
- ❌ 身份证走公有桶（必须 private=1）
- ❌ 公有桶用 COS 原始域名（应替换为 CDN 域名，规则见
references/scripts/upload_cos.py） - ❌ 三步 pipeline 中间断路（上传成功但不提交 / 提交成功但不轮询）
- ❌ 轮询间隔 < 5 秒（浪费后端资源）
- ❌ 轮询超过 30 秒不放弃（无限等待）
- ❌ 30 秒超时后不重新上传（后端可能已丢弃任务上下文，用旧 taskKey 无意义）
- ❌ 云OCR 失败静默降级到 LLM 视觉（用户不知精度已下降）
- ❌ 备案号走云 OCR pipeline（应用 LLM 视觉，字段少且版式规整）
参考文件
references/scripts/upload_cos.py— Step 1：取 COS 临时凭证 + 上传 + 链接拼接（含域名映射规则）references/scripts/remote_ocr.py— Step 2 + Step 3：提交 OCR 检测 + 轮询查询结果（全链路一体）references/llm-vision-record.md— 备案号 LLM prompt（不走pipeline）references/cert-type-detection.md— 证件类型检测