Knowledge learning

Knowledge Learning

Use this subskill when the user asks to learn a knowledge point, a weak tag surfaced by overview, or a larger system topic such as "指数方程中的分类讨论" rather than one surface wrong-question tag.

Core contract:

• Use scripts/workflow.py start --kind knowledge_courseware after graph selection and verified practice are ready. The workflow stops only for graph_teaching_draft.v1, then scripts build and validate the courseware.
• Normalize subject and knowledge tag.
• Check scripts/learning_profile.py show --data-dir <dir> --json and use grade/stage, explanation preference, difficulty preference, goals, and weak subjects when present. For deep modules, build-context reads LearningProfile automatically when available and marks the Phase 1 contract as source="inferred" when it is missing; do not block module generation solely because the profile has not been created yet.
• For deep learning, first select a bounded graph learning unit. The graph owns the topic boundary, prerequisite order, target skills, misconceptions, and verified exercises.
• If a broad tag would pull unrelated evidence into a system topic, pass curated --wrong-question-id <id> values so the module is grounded in the exact wrong questions the agent selected.
• Render the archival continuous deep module with scripts/knowledge_learning.py render-page --data-dir <dir> --context <context.json> --json when a long reference page is useful.
• Use scripts/knowledge_learning.py build-courseware as the only default student-courseware entry. It builds the context, renders HTML, and runs semantic validation in one command. Do not separately call render-courseware as a shortcut.
• Start every source-backed junior-high module with one deterministic preflight: scripts/knowledge_graph.py prepare-courseware-inputs --data-dir <dir> --subject <subject> --topic <slug> --json. It audits packaged sources, validates the normalized seed, resolves or bootstraps the topic package, builds/reuses the topic slice and verified exercise pool, and returns exactly one structured next_action. Do not manually replay its internal commands during the normal path.
• Keep recognition-time knowledge_tags[] as lightweight display/aggregation fields. Use optional knowledge_refs[] only after a reviewed topic overlay maps a wrong question to stable graph nodes. Every ref carries topic_id, graph_version, node_id, role (primary, secondary, or prerequisite), and a short rationale.
• Follow the preflight next_action literally. When it requests knowledge_courseware_preparation_choice.v1, choose one listed coherent learning unit and one or more listed, relevant wrong-question ids, write only that choice file, then invoke the returned resume_argv. The resumed command validates the choice, creates the bounded graph selection and three verified practice tasks, and returns the exact knowledge_courseware workflow start command.
• If preflight returns bootstrap_required, the running Agent writes only the requested knowledge_topic_overlay.v1 candidate to output_ref, using the supplied graph and mistake-bank refs, then invokes resume_argv. The script validates and archives it as agent_generated; packaged topics remain packaged_reviewed. Final selection and courseware metadata preserve asset_origin, verification_status, and source_refs.
• Keep audit-sources, validate-seed, resolve-topic-package, build-topic-slice, select-subgraph, exercise-pool commands, and archive-agent-topic as script-owned diagnostics/repair primitives. They are not the normal Agent orchestration path. Never let the Agent hand-edit mistake-bank arrays or student-facing grading keys.
• In rendered practice, keep the correct answer collapsed. 显示答案 stays disabled until the student enters and submits that task's answer; submission locks the answer field, then enables the separate answer toggle. Downloaded submission JSON continues to carry the student's answer for later Agent grading.
• After the topic package is resolved, the running agent creates only graph_teaching_draft.v1 for the courseware stage. The draft contains one entry, exactly three mechanism cards, one summary, and semantic animation specs. Every mechanism card must cite selected node ids. The agent may write friendly explanations, analogies, and minimal examples, but it must not alter the resolved knowledge scope, prerequisite path, linked evidence, or practice set.
• Build graph-backed courseware with build-courseware --knowledge-selection <selection.json> --knowledge-practice <practice.json> --teaching-draft <draft.json>. The script owns evidence quality filtering, context assembly, graph_lesson_blueprint.v1, rendering, metadata, and final validation.
• render-courseware rejects any context without graph_lesson_blueprint.v1. Do not retry through the historical topic-name/TeachAny renderer. render-page remains the archival continuous-page path for historical contexts.
• If preflight resolution finds no topic package, do not call lower-level commands manually. Complete its one explicit bootstrap task and resume the same preflight. The candidate must use asset_origin="agent_generated" and verification_status="agent_verified", include provenance plus exactly three verified prerequisite/core/transfer exercises, and must never enter the Skill's packaged overlay directory or claim packaged_reviewed.
• One eligible wrong question is enough to ground a deep module; three wrong questions are not required. The separate requirement is exactly three verified practice roles. If the agent cannot verify the candidate, any exercise, or a coherent learning unit, mark the uncertainty outside the archive and stop. Do not bypass the archive validator or claim that courseware was completed.
• Agent topic archives record generated_by, generated_at, base_graph_version, source_refs, content_hash, and validation_report. Same-hash regeneration is reused. Different content requires explicit --refresh. If a packaged topic later appears, it takes precedence while the Agent archive remains a distinguishable audit asset.
• Wrong-question evidence is script-filtered before it can influence the lesson or mastery links. Records with total confidence < 0.70, or without visible question, student answer, or mistake analysis, are listed under excluded_wrong_question_evidence and are not linked to the generated courseware.
• Content target: 55% graph/verified exercises, 25% current-model teaching translation, 15% student mistake evidence, and 5% fixed template copy. Previously frozen Agent prose may contribute at most 5% and cannot be the source of a knowledge claim.
• A deep module is not a wrapper around one tag and is not a wrong-question explanation. Wrong questions select emphasis; they do not define the entire lesson sequence.
• Wrong questions are supporting evidence for why the topic matters. They should not be the main teaching path, the only worked example, or the default Xiaohei prompt input.
• Use the same pixel/Minecraft visual language and wide-screen useful canvas as the current Peter Zhou pages. The default student HTML is exactly six cards: entry/diagnosis with visible eligible mistake evidence, three graph-grounded mechanisms, three linked exercises, and one exam-check summary.
• Do not add animation to entry, practice, or summary cards. Each mechanism card has one teaching animation with a single stated goal.
• Animation defaults to paused. It provides previous, next, optional auto-play, and replay controls. Steps persist earlier mathematical states, highlight only the change, and finish with a concrete student check. Decorative card motion does not satisfy the contract.
• Use a subject visual adapter only when it reveals a mechanism: algebra area/formula morph, geometry construction, physics state/force evolution, or another causal change. Prefer a static figure when time does not matter.
• Reuse the adapted xiaohei-illustration/ child skill for default knowledge-module comics: concept_anchor, solution_path, and trap_guardrail.
• For each default comic, build the prompt with scripts/knowledge_learning.py build-xiaohei-prompt --data-dir <dir> --context <context.json> --purpose <purpose> --output <prompt.txt> --json, generate a real original Xiaohei bitmap when image generation is available, copy it under data/knowledge-modules/<subject>/<normalized_topic>/assets/, then attach it with scripts/knowledge_learning.py attach-xiaohei-image --data-dir <dir> --context <context.json> --purpose <purpose> --image-ref <ref> --json.
• Re-render the module after attaching images. If image generation is unavailable or a generated image fails QA, keep the shot list and saved prompt without blocking the learning artifact.
• Treat overview knowledge_page_recommendations[] as lightweight suggestions. If the recommendation is status="recommended", ask for user confirmation before generating a page. If it is status="archived", reuse the existing html_ref.
• Use scripts/knowledge_overview.py knowledge-page only for the existing lightweight subject/tag KnowledgePage path.
• Store/reuse lightweight page metadata through data/knowledge-pages/index.json.
• Use --refresh only when an archived page should be regenerated after template/content improvements or user-requested correction.
• Generate local HTML focused on the minimum graph-selected first principles, mechanism animations, examples, common errors, three linked exercises, and a reusable final check. Extra illustrations or games are optional assets and must not expand the default six-card path unless the user requests them.
• Do not create learning-session or completion-tracking tables.

Distinction:

• ExplanationArtifact: teaches one wrong question.
• KnowledgePage: lightweight reusable page for one normalized weak tag.
• KnowledgeModuleContext: archived system-topic evidence plus a validated graph lesson blueprint generated from multiple wrong-question signals.