在「**杯」信息通信建设工程安全生产知识竞赛的备战中，参赛者面临一个典型困境：多人拍照上传题目、OCR识别、查找答案、整理汇总——哪个环节不需要人工干预？耗时且易错是常态。Question-Photo-Workflow 正是奔着这个痛点来的。它将「照片→题目→答案→表格」这条长链路拆解为三个紧密耦合的阶段，同时内置四级答案查找优先级与题库自积累机制，依托 WorkBuddy AI 平台实现了端到端的自动化处理。
接下来，我们深入拆解这个技能的功能设计、技术架构、核心优势与现存局限，看看一个完备的 AI Agent 技能究竟应该怎么搭。
背景：**杯知识竞赛的挑战
「**杯」是通信建设领域的重要赛事，参赛者需要在短时内处理大量题目。但典型的工作流，至少有四个绕不开的瓶颈：
- 多人协作碎片化：多人分别拍照上传，题目次序七零八落，编号散乱，整合起来相当头大。
- 手动作答低效：每道题都得人工翻法规、搜题库，重复劳动特别多。
- 汇总整理繁琐：答案散落在聊天记录里，缺少统一的表格化输出和统计分析。
- 知识无法沉淀：做完一批题就随风消散，下次遇到同样的题还得重新翻。
核心洞察：这四个问题不是孤立的——它们本质上是同一条流水线上「断裂」的四个环节。Question-Photo-Workflow 的要义在于：把这四个环节焊接成一条端到端的自动化流水线。
功能全景：三阶段协作流水线
技能采用三阶段串行流水线架构，阶段之间通过结构化数据文件（JSON）传递信息，形成清晰的数据契约。
▶ 阶段1: 照片获取与上传 ──→ ▶ 阶段2: 题目文本提取 ──→ ▶ 阶段3: 答案查找与输出
多人拍照 → 本地存储 Vision OCR → questions.json 四级检索 → 表格 + HTML
阶段 1：照片获取与上传
支持多人拍照上传、URL下载、天翼云盘拉取、本地目录扫描四种来源。统一命名为 jianan_01.jpg 等有序文件名，存入 .workbuddy/photos/ 工作目录。
阶段 2：题目文本提取
利用 macOS 内置 Vision OCR 引擎（零下载、<1s/图）提取照片中的文字。自动识别题型（单选/多选/判断/填空）、拆分选项、统一题号，输出结构化 questions.json。
阶段 3：答案查找与输出
四级优先级检索（本地索引→知识库→Web→推理），输出 Markdown 答案表格 + HTML 预览页。完成后执行10步收尾清单，确保题库自积累、索引重建、统计汇总全部到位。
技术架构：文件体系与数据流
技能的设计遵循关注点分离原则，将配置、阶段指令、工作流、数据格式、HTML 模板分别存储在独立子目录中：
| 目录/文件 | 职责 | 设计意图 |
|---|---|---|
SKILL.md | 入口文件，流程概述 + 决策树 | 单一入口，减少认知负荷 |
config/ | 知识库 ID、搜索策略、降级路径 | 单点配置，避免多处硬编码 |
stages/ | 三阶段详细执行指令（各独立 md） | 阶段解耦，可独立调试/优化 |
workflows/ | 收尾清单（10步强制步骤） | 确保质量闭环，不遗漏任何步骤 |
templates/ | HTML 预览页模板 | 统一输出格式，统计卡片 + 分析面板 |
data-formats/ | questions.json / question_bank.json 的 Schema 定义 | 显式数据契约，上下游对齐 |
关键数据文件流转
| 文件 | 产出阶段 | 消费阶段 | 用途 |
|---|---|---|---|
questions.json | 阶段2 | 阶段3 | 当前批次的题目结构化数据 |
question_bank.json | 阶段3（收尾） | 后续批次（P0索引） | 跨批次累计题库，支持去重 |
question_index.json | 阶段3（收尾） | 后续批次（P0索引） | 精确哈希 + 倒排索引，毫秒级检索 |
answer_view.html | 阶段3 | 用户预览 | 可视化答题结果，含统计 + 分析 |
kb_upload.txt | 阶段3（收尾） | IMA知识库 | 格式化Q&A文本，供知识库上传 |
设计哲学：每个阶段的输出都是明确的、结构化的文件——而不是内存中的临时变量。这使得整个流水线天然支持「中断-恢复」模式：即使会话中断，下一个会话可以直接从上一阶段的输出文件继续工作。
核心技术亮点：四级答案查找优先级
阶段3是整个流水线中最关键也最复杂的环节。技能设计了一套四级降级检索策略，在速度与准确性之间取得平衡：
| 优先级 | 策略 | 详情 | 耗时 |
|---|---|---|---|
| P0 | 本地索引（毫秒级） | 预构建 question_index.json，包含 exact_map（O(1)哈希）+ inverted_index（倒排索引）+ kb_raw（全文兜底）。命中后直接返回答案。 | ~5ms |
| P1 | IMA 知识库（双库并行搜索） | 同时向两个知识库发起搜索——个人库（500题 + 20 法规文件）与共享库（2024/2025真题 + 解析 + 教材）。双库一致取高置信度，不一致时优先共享库（更新）。 | ~3000ms |
| P2 | Web 搜索 | 知识库均无结果时，使用题干关键词进行互联网搜索。适用于通用知识题或知识库覆盖盲区。 | ~5000ms |
| P3 | 大模型推理 | 所有检索手段耗尽后，由大模型基于自身知识进行推理，标注低置信度（answer_confidence: low）供用户复核。 | 可变 |
性能飞跃：P0 索引将「Grep + Read 文件」的 ~1000ms 查找优化到「Read JSON + 内存哈希」的 ~5ms，提速 200 倍。随着题库积累，P0 命中率持续攀升，后续批次的处理速度呈指数级增长。
双库并行搜索策略
P1 知识库搜索不是简单的「搜一下」，而是设计了三轮递进式查询：未完待续...
