peter-zhou-recognition

name	peter-zhou-recognition
description	Recognize wrong questions from scanned/photo/PDF papers using model-native vision. Use for source manifests, page order reasoning, teacher-mark interpretation, unmarked-paper grading, and RecognitionResult creation.

Recognition

Use this subskill when a source paper or wrong-question image needs visual understanding.

Core contract:

• Scripts scan files, render PDFs, create source manifests, and persist results.
• Use scripts/source_queue.py prepare for deterministic source discovery and manifest creation.
• For the Dashboard action 检查待入库试卷, run scripts/runtime_config.py refresh --json and report status=new as待入库. For 处理待入库试卷, process the returned manifest_paths one at a time through native vision, canonical result selection, and intake.
• The default source is a local top-level directory configured during first use. If an advanced installation explicitly needs a remote Windows source, scripts/ssh_source_sync.py refresh is an optional SSH adapter; credentials stay in the host's SSH configuration or runtime environment and never enter Peter Zhou configuration or output. Use --retry-failed only when the user or workflow explicitly requests failed-source retry.
• For PDFs, source manifests include one stitched document_image_path for whole-paper recognition plus individual page PNGs for close reading and crop references.
• Use scripts/recognize_manifest.py build-prompt to prepare the native-vision prompt from an explicit source manifest.
• The agent should inspect the whole-paper image first for document-level structure, then use individual page images for close reading and crop-region coordinates.
• Prefer crop_regions[].image_ref="page" with normalized 0-1000 bbox coordinates; use image_ref="document" only when the region cannot be located reliably on one page image.
• Treat crop_regions[].bbox as a rough visual anchor, not a pixel-perfect contract. Set crop_regions[].crop_policy="auto_expand" for normal wrong-question screenshots so scripts expand the crop to nearby printed/handwritten evidence. Use crop_policy="exact_bbox" only for clean standalone visual assets or deliberately tight review crops.
• If a question depends on a visually separate diagram, table, chart, graph, map, circuit, or labeled illustration, include that visual area as an additional crop region for the same wrong question.
• Set question_kind to text for pure text questions and visual for questions that need a figure, table, chart, graph, map, circuit, geometry figure, or labeled illustration.
• Store required source context in context_text. For any reading-comprehension item, including Chinese and English, include the original passage or enough passage excerpt to answer the subquestion; do not persist only the subquestion. When the prompt asks to answer with "本文", "文章", "全文", "选文", or a passage, a short summary is not enough.
• Also transcribe the needed visual data into clean student_facing_assets[], because correction papers do not print raw crop screenshots.
• For printable visual assets, use this priority: safe true-image crop first, then controlled diagram_spec/SVG redraw for geometry-style figures. Do not use generated-image replication as a canonical student asset.
• When a clean printed visual area has no student answer, handwriting, or teacher mark, add student_facing_assets[].asset_regions[] for that clean area. The intake script will crop it into student-assets/ and persist an asset_ref for printable correction papers.
• If no clean visual crop exists, leave out asset_regions. For geometry-style figures, reconstruct the needed relationships through a reviewed diagram_spec/SVG redraw workflow; for other visual data, reconstruct the needed diagram/table/chart information in student_facing_assets[].content and lower confidence if review is needed.
• Preserve natural math symbols in text, and add formula_latex[] for formulas, roots, fractions, equations, geometry relations, or units that need stable later rendering.
• When correct_answer comes from teacher correction or from model derivation, state the source in simple_mistake_analysis. If teacher handwriting conflicts with reliable derivation or is hard to read, lower confidence and include a review note such as 批改字迹需复核.
• The agent reads source manifest images with native vision and returns a structured RecognitionResult.
• The normal path is scripts/workflow.py start --kind paper_recognition --source-manifest <manifest>. The workflow first permits the Agent to identify a returned Peter Zhou correction paper from visible content rather than the file name; those files are automatically routed to returned-scan extraction and unified answer grading instead of mistake ingestion.
• For returned correction papers, trust printed page numbers over file/render order. Submit only visible answers. Review every unanswered item for a missing, cropped, or contradictory stem/diagram through unanswered_item_reviews; blank answers must never become attempts.
• After returned-scan grading succeeds, the workflow marks the source document and manifest processed and the correction paper answered, so source refresh does not queue the same file again.
• If native vision fails structurally or technically, use Doubao seed-2.0-pro fallback through runtime configuration.
• Do not write durable JSON directly from prose output.
• Validate RecognitionResult records with scripts/validate_record.py; see references/schema.md.
• Use scripts/recognize_manifest.py select-result so native output stays primary and fallback output cannot create a duplicate mistake set.
• Persist selected recognition results with scripts/intake_recognition.py ingest, then show the returned derived review report to the user. Normal crops should already be auto-expanded; use intake_recognition.py repair-crops only when a screenshot is still incomplete, too loose, or needs a deliberately different multi-region stitch.
• For normal operation, do not manually repeat build-prompt, select-result, and ingest; resume the workflow using the exact schema named by next_action.