教案生成器 Skill 2.2.1
本 Skill 的唯一完整行為規範。其他 agent 入口只要求先讀取本文件和 通用提示詞.md，不要複製另一套欄位或生成規則。目前支援 Windows 和 macOS。模型負責理解資料並產出完整 Content 2.2 JSON；Python 只負責確定性校驗、格式化和模板對應，不能代替模型創作正文。2.2.1 是 Lesson / WorkOrder 交付契約修正版，不修改 Word 模板、正文品質演算法或 WorkOrder 評分契約。
任務入口與 Intake Runtime 2.1.1
任務開始時先讀取當前對話、使用者上傳檔案和可用課程資料：能力圖譜、章節任務拆解、課程標準、教材目錄、舊教案及使用者指定的 Word 模板。正式規劃前必須進入 INTAKE_PENDING，把當前理解整理成一次集中、全中文的課程基本資訊確認；即使資訊已從對話或附件中推斷出來，也必須展示並請求使用者確認一次。確認完成後進入 INTAKE_CONFIRMED，直接開始資料檢索、課程級 outline、Content 2.2、QA 和 DOCX。
使用者介面只使用中文標籤，不把內部欄位名當作提問內容。一次確認的必含課程基本盤是：課程名稱、專業、授課對象、總課時。確認摘要還必須包含以下非阻斷資訊：理論課時、實踐課時、理論與實踐組織方式、單課課時預設 2 學時、使用教材、輔助參考資料、是否同時生成實踐任務工單。
當四個核心欄位中有資訊缺失時，在同一確認摘要中顯示「待補充」；總課時只能接受使用者明確提供的事實。若專業或授課對象只是 Agent 的推斷，必須標註「目前理解 / 如不準確請修改」。當理論/實踐拆分、組織方式或實踐任務工單偏好沒有明確提供時，必須顯示「待確認」，不能按 50/50、綜合式或「否」自動補齊。default_hours=2 只能用於說明按 2 學時估算約有多少課次，不能據此推斷理論/實踐比例。內部欄位對應與狀態規則見 docs/intake-contract-v2.1.1.json；使用者介面只顯示「輔助參考資料」，內部狀態仍使用 auxiliary_references，不得把該英文 key 當作使用者問題。
首次回應應類似：
我先確認一下課程基本資訊：
- 課程名稱：《資料結構高級》
- 專業：目前理解 / 如不準確請修改
- 授課對象：目前理解 / 如不準確請修改
- 總課時：40 學時
- 理論課時：待確認
- 實踐課時：待確認
- 理論與實踐組織方式：待確認（可選：全部理論 / 全部實踐 / 分段組織 / 綜合組織）
- 單課課時：預設 2 學時
- 使用教材：未指定（如有指定教材請告訴我；沒有也可以繼續）
- 輔助參考資料：未指定
- 是否同時生成實踐任務工單：待確認
以上資訊是否正確？如需調整，請一次性告訴我。
教材是 recommended, not required：已提供檔案或書名直接展示，未提供也不能阻斷生成。practice_work_orders 未提供時保持待確認；只有使用者明確選擇後才決定是否聯動 WorkOrder Skill。明確選擇 false 時，實踐學時仍計入課程總課時，但不生成 Practice Task Contract、handoff、WorkOrder 或實踐側額外檔案。明確選擇 true 後，Lesson Agent 在完成 Lesson QA/DOCX 和 Practice Task Contract handoff 後檢測並呼叫可用的 WorkOrder Skill，由 WorkOrder Agent 創作完整 Content V1、執行 QA 並生成工單，最後統一交付；不可用時僅交付 Lesson 與 handoff，並明確 實踐任務工單產生器目前不可用，已儲存實踐任務資料檔案，可在工單產生器可用後繼續產生。，不偽造工單 DOCX。
Intake 未確認前，不得確定專案數量或名稱、理論/實踐課次結構、實踐任務數量、逐課教學內容或生成 DOCX；除非使用者已經明確提供了相應事實。確認一次後不得再次詢問 outline、專案名稱、逐課任務、評分、模板、輸出目錄或「是否開始生成 DOCX」。預設模板和預設輸出規則直接採用。只有使用者主動改變要求、確認資訊出現無法合理解決的直接衝突，或遇到安全/檔案覆蓋等真正需要使用者決定的事項，才允許再次停下。
若使用者明確選擇「全部理論」，正規化為 theory_hours=total_hours、practice_hours=0、delivery_mode=theory_only，並將實踐任務工單設為 false；若明確選擇「全部實踐」，正規化為 theory_hours=0、practice_hours=total_hours、delivery_mode=practice_only。其他拆分必須滿足 theory_hours + practice_hours = total_hours；不相等時先報告衝突，不得開始 outline。
資料檢索優先使用使用者提供的教材/課程資料和使用者指定教材；有聯網能力時再查找出版社或學校官方頁、標準/指南、官方技術文件和可核實公開文獻。只給出書名時只能寫入真實核實的作者、出版社、ISBN、版次或年份；網路不可用時正常繼續，不因無法聯網中斷生成。
- 使用者允許合理推斷後，按專案化教學補齊專案、任務、教學內容、評價和預生成反思；
- 正式 DOCX 不出現「資料不足、推斷、AI、QA、similarity、confidence」等內部說明。
沒有任務資料時也必須先形成課程級 outline，再生成逐課內容。outline 至少包含 lesson_id、unit、task、lesson_type、hours、theory_hours、practice_hours、prior_learning、capability_stage、deliverable、next_bridge 和 practice_task_ids。長課程可以內部按 4 至 6 課一批生成，但最終必須用完整課程上下文統一 QA。
Content Contract V2.2
預設使用 assets/templates/lesson-plan/v1.1.2/template.docx。
正式生產輸入預設是 content_contract_version: "2.2"，與 Word 模板版本獨立；執行時相容讀取 "2.1" 和 "2.0"。預設 Word 模板為 lesson-plan v1.1.2，並繼續支援 v1.0 legacy-coordinate、v1.1.0/v1.1.1 semantic-bookmark 與舊 compatibility 模板路徑；舊 sparse JSON 不再生產生成。
課程級必填欄位：
content_contract_version, course_name, major, audience,
default_hours, total_hours, delivery_plan, course_materials,
reference_pool, artifact_plan, outline, lessons
每個 2.2 理論課次必須直接提供：
lesson_id, unit, task, lesson_type, hours, theory_hours, practice_hours,
progression, reference_ids, practice_task_ids,
student_analysis, teaching_content, goals,
key_point, difficult_point, teaching_methods, resources,
implementation, evaluation, reflection
2.0 輸入仍讀取課次內的 references 物件；2.1 相容輸入保留原有課次語義。2.2 只透過課程級 reference_pool 的 reference_ids 選取來源，且每個理論 Lesson 至少有 1 項 reference。2.2 的 Lesson DOCX 只承載理論：sum(lesson.hours) == theory_hours，所有 Lesson 為 lesson_type=theory、practice_hours=0；實踐不進入 Lesson DOCX。僅當 artifact_plan.practice_work_orders=true 時，實踐才進入 Practice Task Contract / WorkOrder handoff；false 時不得攜帶 contract 或任何任務 ID，practice_task_ids 僅保留 schema 要求的空陣列。practice_task_ids 表示與理論課次關聯的實踐任務，不表示要生成實踐 Lesson DOCX。delivery_plan 支援 theory_only、practice_only、split_lessons、integrated_lessons、hybrid，並且 theory_hours + practice_hours == total_hours。integrated 只描述 artifact-level 理實一體組織，不把實踐小時塞進 Lesson DOCX，也不固定 1+1。
default_hours 是 Agent 建立每課時使用的預設單課學時；某課顯式提供的 hours 可以覆蓋它，default_hours 不要求等於所有 lessons.hours。default_hours、total_hours 和每課 hours 都必須是正整數課時：數值可為 1、2、4、12 等整數，字串可為 "1"、"2"、"2.0"；不接受空白字串、分數、零、負數、NaN 或 Infinity。unit 使用專案化名稱（如「專案一……」）；progression 包含 prior_lesson_id、具體的 prior_learning、capability_stage、deliverable、next_bridge。capability_stage 只能使用 認知、理解、模仿、獨立、綜合、最佳化、遷移，不要求機械線性遞增。第一課的 prior_lesson_id 必須為 null，後續課次只能引用已經出現的前序課次。四課及以上不得所有能力階段完全相同。
student_analysis 的 base/problems/strategies、三類 goals 均至少兩項；teaching_content 至少三項；重難點均須有 content 和 strategy；methods 至少兩項，resources 至少兩項。2.2 理論 Lesson 的 reference_ids 不得為空；空 reference 直接失敗。純實踐課程可以沒有 Lesson DOCX；只有明確選擇生成實踐工單時才必須用 Practice Task handoff 表達實踐學時，明確不生成時不建立 handoff，也不能虛構理論課次。
每課 implementation 必須按以下九個 ID、固定順序完整提供，且每個階段的 label、minutes、modality、content、teacher_actions、student_actions、objective 全部來自 JSON：
before_class_preparation
task_introduction
operation_demonstration
task_implementation
task_extension
project_practice
peer_review
lesson_summary
after_class_improvement
課前準備和課後完善屬於課外階段；中間七個階段的分鐘數必須嚴格等於 hours * 45。每個課外階段允許 0 分鐘，但不得超過 max(60, hours * 45)，兩個課外階段合計不得超過 2 * hours * 45；報錯必須指出 lesson ID、stage、actual 和 limit。operation_demonstration 是語義行位，可在護理、會計、機械等課程中顯示為方法示範、案例分析或技能示範。
評價必須顯式提供 85–96 的 evaluation.score，使用 0.5 分步進，並提供 canonical 13 個 criterion IDs 的逐課 remarks。每條 remark 必須有實質內容；所有 Content V2 模板版本統一執行不超過 48 個有意義字元的契約上限，manifest 只能進一步收緊，超限必須失敗而不能截斷。未指定分數時建議自然集中在 88–94，但不得全為 90、任意短週期迴圈、嚴格遞增或遞減。score_breakdown() 只負責把顯式總分確定性拆分到既有表格行；Python 不創作備註，不使用三套固定 remarks 迴圈或機械分數 fallback。反思必須顯式提供 summary、innovation、improvement，允許課前預生成，但要圍繞本課任務、重難點、組織、預期表現、問題和下一課銜接產生差異。
2.2 的 course_materials.textbook 單獨表示教材，可為物件或 null；它預設不會自動寫入 Word 的 references 儲存格。Agent 在逐課生成前先形成 course_reference_pool / reference_catalog planning concept，落盤欄位仍是 reference_pool，不是新的 JSON contract 欄位。每項必須有 reference_id、reference_type、可識別的具體標題、source_kind、source_region（domestic/foreign/unknown）和相應 evidence；逐課只寫 reference_ids。allow_textbook_as_reference 預設 false，只有顯式為 true 時教材才允許進入 references。references 只表示可以閱讀、查閱、引用或作為課程依據的文獻/文件來源，包括專著、課程/教學標準、國家/行業/職業標準、指南/規範、論文、公開文獻、官方技術文件、官方產品手冊和使用者提供的正式教學文件。resources 表示實施教學時使用的工具、裝置、環境和材料，例如 MySQL Workbench、資料庫伺服器、PPT、投影機、護理模型、虛擬機器、實訓任務單和案例資料集；這些不能為了湊數寫入 references。每課通常選 1–3 項 reference，課程級合法 reference 可重複使用。
source_kind 仍保留 provided、generic、verified_public；provided 需要使用者真實材料 evidence，verified_public 需要 URL 或可定位官方來源，generic 只可使用具體的文件語義且不得偽造詳細書目資訊。禁止「統一建模語言相關公開文件」「相關網路資源」「相關公開文獻」等泛化佔位文字，也禁止猜作者、ISBN、出版社、版次、年份或標準編號。國內來源優先：使用者提供資料、國內出版物/專著、國內高校資料、國家/行業/職業標準和國內權威檔案優先於外國經典；國內佔比低於 70% 只是 quality warning，不是 hard fail，確有國際標準/經典或國內來源不足時可補充外國來源。reference 跨課完全重複允許，屬於 reference_reusable，明確退出 exact/item/sentence/field/structural/frequency/whole-course 反重複 hard-fail；同一課內部重複 ID 或重複內容仍 hard-fail。References 的重複不屬於教案正文重複問題。禁止為了降低課程重複率編造不同教材、作者、ISBN、出版社、標準編號或公開文獻；同一教材重複 18 次優於編造 18 本教材。evidence 只用於輸入和 QA，DOCX 只寫正式引用文字，不寫 evidence 元資料。
Practice Task Contract V1
僅當 artifact_plan.practice_work_orders=true 時，2.2 輸入必須提供 practice_task_contract，版本為 1.0、granularity: "per_task"。實踐學時必須為正偶數；任務欄位是 task_id、project_id、title、lesson_ids、practice_hours、scenario、objectives、required_inputs、tools_or_materials、steps、deliverables、acceptance_criteria、safety_or_compliance。每個 Practice Task 固定 2 學時，任務數嚴格等於 practice_hours / 2；每個任務對應一個 WorkOrder，project_id 只用於分組，不能重新規劃粒度。lesson_ids 是提供理論準備/前置知識的理論 Lesson ID，可跨多個課次；純實踐課程沒有理論 Lesson 時為空陣列。practice_work_orders=false 時不允許 contract 或 handoff，所有 practice_task_ids 必須保持為空陣列。true 時 Lesson 只負責生成並 QA canonical handoff，再由已檢測到的 WorkOrder Skill 透過 Agent orchestration 消費 handoff；Lesson Python generator 不得 subprocess 呼叫 WorkOrder Python，也不得自動對應成工單正文。WorkOrder Skill 不可用時只輸出 practice-task-contract.json handoff，並明確 unavailable 狀態，不偽造實踐工單 DOCX。
當前 2.2 完整規則見 docs/content-contract-v2.md；examples/tasks-v21.example.json 保留為 2.1 相容範例，examples/tasks.example.json 保留為 2.0 相容範例。欄位說明見 docs/content-contract-v2.md 和 docs/practice-task-contract-v1.md，機器約束見 schemas/lesson-plan-input.schema.json 與倉庫 canonical schemas/shared/practice-task-contract.schema.json；schemas/practice-task-contract.schema.json 僅為相容入口。
Python 與 Agent 的邊界
Agent 負責課程級規劃和所有逐課教學正文；生成器只做 schema 校驗、編號、換行、分鐘格式化、欄位對應和模板寫入。V2 正式路徑不得呼叫舊的 generated_lesson_fields、implementation_cell_values、reflection_cell_values，不得使用 flows[:3] 或根據缺失欄位創作正文。若內容超出 manifest 的 max_chars 或 max_paragraphs，必須失敗並指出 lesson、field、actual chars、limit，不能截斷或靜默刪減。
生成與 QA 順序
讀取資料 → 一次性課程基本資訊確認
-> 課程 outline
-> Content V2.2 JSON
-> Input Contract QA
-> Content Quality QA
-> Template QA
-> candidate DOCX generation
-> Output Structure + Content-to-DOCX Fidelity QA
-> optional LibreOffice render smoke
-> atomic commit to final output and external QA report
-> when practice_work_orders=true, detect and call WorkOrder Skill Agent, then unify Lesson + WorkOrder delivery
-> Agent representative-page visual inspection
使用 scripts/generate_lesson_plans.py 生成。所有 DOCX 先寫入與正式目錄同父目錄的 candidate；Content QA、模板 QA、輸出結構/書籤/格式保護、內容保真 QA 和請求的 render smoke 都通過後才交換到正式目錄。顯式 --qa-report 時，外部報告會在其同父目錄先 staging，並與輸出目錄一起提交；任一交換失敗都恢復舊輸出和舊報告。非空正式目錄需要 --backup-existing；交換失敗必須恢復舊目錄。提交成功後，stdout 只報告正式目錄中真實存在的 DOCX 路徑。課程基本資訊確認後不再為生成 DOCX 追加確認；Agent 的代表頁視覺檢查屬於提交後的驗收；若發現溢位、截斷、異常分頁或空白頁，應重寫 V2 內容並使用 --backup-existing 重新事務生成。qa-report.json 只寫報告，不寫入 DOCX。
獨立 scripts/content_quality.py 必須在本機確定性執行，不呼叫線上 API、embedding 或模型服務。它檢查既有正文重複、實體屏蔽後的 structural similarity、重複長句、舊套話、完整性、intra-lesson coherence、progression coherence、score pattern、13 項評價備註 density 和非 IT 汙染；本輪只新增 2.2 reference 必填、source-region 統計和理論/實踐 handoff 檢查，不改變既有 repetition、progression、評分或 implementation coherence 演算法。non_it_contamination 及其 scope 元資料只檢測「輸入沒有但模板或生成器注入輸出」的 IT 預設詞，不是通用課程分類器。診斷只保留有限片段和穩定 SHA-256，不輸出整段使用者正文。所有 detector 共用唯一 reuse policy：narrative_strict、terminology_reusable、resource_reusable、reference_reusable、fixed_rubric_reusable 和 ignore。教學方法、必要資源、合法 reference 與 attendance/compliance/habits 固定 rubric 可以記錄復用證據但不 hard fail；reference 允許跨課完全重複，且完全退出 exact/item/sentence/field/structural/frequency/whole-course 反重複 hard-fail；同課內部 exact duplicate 和明顯的純工具/裝置 reference 必須 hard-fail。短課程術語豁免不得進入 narrative field。不得為了降低課程重複率虛構參考文獻。
progression 的 artifact inheritance 和 forward transition 都必須同時通過詞面/coherence 證據與 substantive_anchor 證據；「設計、操作、分析、檢查、流程、實施」等通用動作不能獨立作為 anchor。非相鄰 prior_lesson_id 仍允許；若物理順序鏈為 review，報告必須置 requires_agent_review=true 並列出 from/to/reason/score/declared_prior。Agent 最終驗收不能靜默忽略 physical sequence review；無法解釋實際授課順序時必須重寫 progression。
確定性 QA 通過並完成原子提交後，Agent 還要逐課內部複審：這一課比上一課新增什麼、使用了上一課什麼知識或成果、產出了什麼、下一課如何使用該成果。這個複審不寫入 DOCX。請求 --render 時，Python 報告只表示 render.scope=smoke，頁數方法是輕量 pdf_page_object_regex；它不等同於 visual QA 或 pagination verified，也不能證明沒有溢位、截斷、異常分頁或表格變形。Agent 應檢查第一課、正文最密集課、最後一課，課程達到 12 課時再檢查 1–2 個中間課，關注 clipping、overflow、overlap、blank pages、abnormal row height 和 table boundary。真實檢查後使用 scripts/record_visual_inspection.py 顯式寫入獨立 visual-inspection.json；該檔案記錄代表頁、checks、notes、關聯 qa-report、output fingerprint 和 timestamp，Python 不會自動聲稱視覺通過。視覺失敗時必須修改 V2 JSON，用 --backup-existing 重新事務生成並重新檢查。
預設輸出 QA 會讀取原始 V2 JSON，透過純 formatter 計算 expected，再對照 semantic bookmark 或 v1.0 座標；不重新呼叫教學內容創作函式。模板佈局、70 個 semantic bookmarks、bookmark IDs/names、fingerprint、v1.0/v1.1 compatibility 和 canonical 二進位均受保護。若本機存在 LibreOffice，使用 --render 做 render smoke；沒有 renderer 時 structural QA 仍通過，報告標記 render.status=not_executed。真實分頁、溢位和視覺佈局結論只來自 Agent 的代表頁檢查。
介面卡安裝語義固定為：預設是 instruction-only adapter install（僅規則/指令安裝），只安裝專案規則和最小 instructions，不複製完整 runtime，也不承諾目標專案可以獨立執行 generator；只有追加 --copy-engine 才是 full runnable project-local Lesson engine（完整可執行引擎）。目標專案需要直接呼叫 .lesson-plan-docx-generator/scripts/generate_lesson_plans.py 時必須使用 --copy-engine。visual-inspection.json 是 Agent visual inspection attestation for the current generated DOCX/QA state，表示 Agent 對當前生成 DOCX/QA 狀態的代表頁檢查，不是所檢查 PDF/圖片的加密證明。
路徑 preflight 在 mkdir、生成、move、backup、delete 之前執行，保護 Skill root、輸入 JSON、schema、selected/custom template、manifest、canonical/compatibility package、scripts 和 tests，並拒絕 ancestor、descendant、resolved symlink 及 Windows lexical/8.3 alias overlap。不要把輸出寫入受保護目錄或自訂模板包。
命令
Windows：
python scripts/generate_lesson_plans.py `
--tasks-json tasks.json `
--output-dir output `
--render
macOS：
python3 scripts/generate_lesson_plans.py \
--tasks-json tasks.json \
--output-dir output \
--render
單獨校驗輸出：
scripts/validate_template.py --json
scripts/validate_output.py --input-json tasks.json --output-dir output --render
scripts/validate_visual_inspection.py --output-dir output --qa-report output/qa-report.json --evidence output/visual-inspection.json
手動安裝及依賴檢查（安裝器不會自動修改 Python 環境）：
python scripts/install.py --skills-dir <skills-dir>
python <skills-dir>\lesson-plan-docx-generator\scripts\check_dependencies.py
check_dependencies.py 只讀檢查 docx、yaml、jsonschema；缺失時提示 pip install -r requirements.txt。Agent 生產流程禁止使用 --skip-template-validation 或 --skip-output-validation；這兩個相容參數只有在顯式設定 LESSON_ALLOW_UNSAFE_VALIDATION_SKIP=1 時才可用於受控測試，並必須在報告中明確為 skipped。輸入契約、內容品質和路徑保護不能被跳過。臨時 JSON、PDF、圖片和 candidate 目錄在任務結束後清理，不提交生成 DOCX。
模板檔案
assets/templates/lesson-plan/v1.1.2/template.docx
assets/templates/lesson-plan/v1.1.2/manifest.yaml
assets/templates/lesson-plan/v1.1.1/template.docx
assets/templates/lesson-plan/v1.1.1/manifest.yaml
assets/templates/lesson-plan/v1.0.0/template.docx
assets/templates/lesson-plan/v1.0.0/manifest.yaml
schemas/lesson-plan-input.schema.json
scripts/content_contract.py
scripts/content_quality.py
scripts/generate_lesson_plans.py
scrip
…
[truncated for translation]