peter-zhou-recognition

# 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 `处理待入库试卷`, pass all returned `manifest_paths` to one `paper_recognition_batch` start command as repeated `--source-manifest` arguments. Follow only its current `next_action`; the script advances papers and aggregates review/failure refs. - 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 multi-file path is `scripts/workflow.py start --kind paper_recognition_batch --source-manifest <manifest-1> --source-manifest <manifest-2> ...`. Use `paper_recognition` directly only for one explicit paper or diagnostics. The batch exposes exactly one child paper's prompt/images at a time, preserves each child review report, continues after a terminal child failure, and reuses completed/interrupted children unless `--refresh` is explicit. - Every child 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`.