szsip239/peter-zhou

Peter Zhou

Peter Zhou is the navigator skill for a single-student wrong-question learning loop. Route each request to one focused subskill instead of expanding this file.

Routing

• recognition/ — ingest paper files, build source manifests, and use model-native vision to produce RecognitionResult.
• mistake-bank/ — validate, persist, review, confirm, and query mistake-bank records.
• explanation/ — generate cached structured explanations and optional rich teaching pages.
• xiaohei-illustration/ — generate original Xiaohei teaching comics used by explanation and knowledge pages.
• correction-practice/ — generate printable correction papers and record returned-paper grading results.
• knowledge-learning/ — create reusable first-principles HTML learning pages for weak knowledge tags.
• overview/ — compute progress, mastery, weak-tag, and recent-activity reports.
• references/issue-reporting.md — report confirmed product defects or feature requests from an installed user host to the project Issue tracker.

Rules

• Use model-native vision for paper and handwriting understanding. Do not use OCR as the primary recognition path.
• Let scripts own durable JSON, ids, status transitions, crops, generated PDFs, counters, and validation.
• Let the agent own visual interpretation, grading judgment, explanation, teaching design, and review reports.
• Read docs/agents/REFERENCE_ADAPTATION.md before copying ideas from the reference projects.
• Do not import TeachAny publishing/TTS/knowledge-graph/AI-tutor workflows or K12 OCR/Word/WorkBuddy-memory behavior.
• Resolve the private runtime paths with scripts/runtime_config.py show --json. On first use, ask for the local paper-source directory and initialize it with scripts/runtime_config.py init --source-dir <dir> --json; never guess a machine-specific path. Use init-ssh only when the user explicitly chooses a remote Windows source.
• Keep runtime configuration and student data outside Git. A normal installation uses one local source directory and one local data directory on the Agent host. Optional remote-source synchronization is an explicit adapter, not a default dependency.

Workflow

1. For a general “开始使用 Peter Zhou”, “查看状态”, “我的进度”, or “今天做什么” request, resolve <data-dir> from scripts/runtime_config.py show --json, run scripts/chat_dashboard.py --data-dir <data-dir> --top-n 3 --json, send its markdown field as the main chat response, and retain its actions for routing. If the config is missing, complete First Install first.
2. Let the user回复编号 or directly state an operation from the dashboard. Resolve the numbered item against the current Dashboard JSON and execute its structured execution contract; use prompt only as fallback, never as shell text. For “今日 10 分钟复习”, show only next_action.question, privately read agent_context_ref, grade the student's answer, and resume once with both --student-answer and an agent_chat_item_grading.v1 file.
3. When the user already asks for a specific operation such as “生成数学订正卷” or “打印这份试卷”, skip the dashboard and直接路由 to that subskill.
4. Read that subskill's SKILL.md and load only the schemas, prompts, scripts, or templates needed for the request.
5. Use scripts/workflow.py start/status/resume/list for normal recognition, grading, explanation, knowledge-courseware, correction-paper, and Agent-chat paths. Read only the returned next_action; compatibility CLIs are for diagnosis or repair. Use the read-only metrics command only for performance diagnosis.
6. Run scripts/doctor.py --workflow <kind> --json before a workflow when checking local capabilities; it is read-only and must not auto-install dependencies.
7. Run scripts/smoke_test.py --json after installation to verify the deterministic local workflow without real student data or model calls.
8. Use scripts/data_doctor.py audit|storage|prune-cache for read-only diagnostics. Cache pruning is dry-run unless --apply is explicit.
9. Prefer the smallest verifiable slice and run the relevant validator or test before reporting completion.
10. When the user reports a Peter Zhou malfunction, first distinguish a product defect from normal mistake-review correction or source-data uncertainty. For a confirmed product problem, follow references/issue-reporting.md; do not improvise an Issue body or upload student artifacts.

Chat Dashboard

• Dashboard statistics are computed live from canonical JSON. Never cache or hand-maintain a second dashboard store.
• “待入库” counts SourceDocument.status=new from the latest prepared source queue; “待审核” counts status=processed. failed sources are shown separately as待重试.
• Route “检查待入库试卷” to recognition/ and run scripts/runtime_config.py refresh --json. Route “处理待入库试卷” through one paper_recognition_batch with all returned manifest paths; follow its single current action until it returns the aggregate review/failure summary.
• Keep the generated emoji and compact Markdown structure. Add a short personalized sentence only when it materially helps.
• Every action has a stable action_id, workflow_kind when applicable, structured execution, and natural-language prompt. Prefer the controlled argv or named subskill operation so runtime paths and command assembly stay script-owned.
• Markdown links are valid only for existing local HTML/PDF assets. Plain skills cannot provide portable click-to-run buttons, so do not pretend numbered actions are hyperlinks; they are concise chat commands.
• When the user asks for the Minecraft/知识世界 Dashboard, run scripts/chat_dashboard.py --data-dir <data-dir> --top-n 5 --minecraft-html <data-dir>/dashboard/minecraft/index.html and provide the generated local HTML link. It is an optional read-only projection of the same live Dashboard object, not a second progress store or a replacement for the Agent-chat controls. Its buttons may copy Agent instructions, but must not claim to execute recognition, grading, or writes from the browser.
• Discover deep-learning courseware from data/knowledge-modules/*/topic-*/courseware-metadata.json, not knowledge-pages/index.json. Show only metadata with status="rendered_and_validated" whose html_ref resolves to an existing file inside data/. Do not hand-maintain a courseware index.
• If data/ is empty, show the onboarding dashboard and offer new-paper recognition plus the first-use profile interview.

First Install

• Default to a pure skill installation. Do not require an npm package for the current agent-driven workflow.
• Use npm only if a future requirement needs a long-running local service, cross-shell executable distribution, or non-agent entry point.
• Ask the user for the local folder containing paper PDFs/images, then run scripts/runtime_config.py init --source-dir <dir> --json. The default private data directory is ~/.peter-zhou/data; use --data-dir only when the user chooses another location.
• After initializing paths, run scripts/doctor.py --json, then scripts/smoke_test.py --json.
• If no local profile exists and the user enters explanation, correction practice, knowledge learning, or overview personalization, run scripts/learning_profile.py interview-prompt --json, ask only the listed short questions, write a candidate JSON, then persist it with scripts/learning_profile.py upsert --data-dir <data-dir> --candidate <json> --now <iso-time> --json.
• Missing LearningProfile must not block paper recognition.

Product Feedback

• A local failure, reproducible wrong behavior, installation defect, or documentation mismatch may become an Issue after local diagnosis. Routine recognition review, correction of an individual mistake record, and low-confidence student-content judgments remain in the normal learning workflow.
• Ask once before the external write unless the user already explicitly requested “提交 Issue” or equivalent. After confirmation, read and follow references/issue-reporting.md.