Classroom Answer Toolkit

本项目只解决一件事：把试卷生成的答案交付为符合课堂排版要求的 Markdown 和 PDF。

主链：

试卷 PDF
  -> 页面图
  -> 当前 subject-pack 提示词 + AI 作答
  -> 4x 题目级左右重叠视窗 + 无参考答案视觉审计
  -> 可选：参考答案 PDF 复核与校正
  -> Markdown 规则校验
  -> PDF 排版
  -> review 页图、交付专属 snapshot 与 delivery manifest 1.1
  -> workflow run receipt

本项目不是题库系统，不负责试卷入库、标签治理、知识图谱或样例飞轮。原卷与参考答案可以保留在用户自己的资料目录中；运行脚本接受任意明确路径，不要求把资料迁入项目资产结构。

当前状态

• 初中物理运行提示词：prompts/specs/compiled/ 的完整版汇编产物，经 prompts/junior-physics-answer/manifest.json 的 sourceOfTruth.humanSpec 解析；当前版本以该 manifest 为准。
• 已真实跑通 2025 广州中考原卷到 Markdown/PDF 的完整链路。
• 默认主链不再把单次整卷盲答直接送去排版：先以 4x 重渲染原卷，按 PDF.js 题号切成每题两个带重叠的高清视窗（续页继承题号）执行独立视觉审计，再进入可选参考答案复核。
• 局部高清审计能降低滑轮、刻度尺和钩码计数错误，但不能保证消除所有仪表盘歧义；未经参考答案或人工复核仍不得声明答案可信。
• 2015-2026 的答案文件位于 正式交付/广州物理中考参考答案/（每年 PDF + Markdown + DOCX 三格式，目录结构与 习题/ 一致）；习题/广州物理中考试卷/ 是明确版本化的广州真题 golden corpus。其他用户原卷仍可从任意路径输入，无需复制进仓库。
• 该目录是版本化 golden 副本，不是交付 manifest 的载体：它按设计只保留三格式成品，不含 *.delivery-manifest.json、同目录 snapshot 和 <PDF基名>.review/。逐字节交付证据只随 scripts/run-live-answer-workflow.ps1 的新实跑产生，不要用本目录反推某次交付的完整性。
• 2026 的入库状态与回归基线是两件事：2026 的三格式成品已存在，但按 docs/strategy/product-prd.md 与 execution-backlog.md 的 BASELINE-2026-101，2026 仍未取得"首次真实运行授权 + 纳入长期回归"的决策，因此不得把 2026 称为 baseline 或已完成的回归链。
• 新实跑输出默认经 scripts/archive-delivery-run.ps1 归档到仓外并不入 Git（2017-2023 历史归档见 docs/change-evidence/20260823-archive-2017-2023-deliveries.md）；仅当同时具备可重复回归价值、权威输入来源、完整 hash/回执与明确真值边界时，才通过显式基线切片准入。
• 可复现的页面图、裁剪图和诊断输出只写入 ignored tmp/；不得把它们重新提交。长期回归仅保留 eval/real-paper/ 的最小 hash-bound 基准。

最短运行

从原卷直接生成并排版：

pwsh -NoProfile -ExecutionPolicy Bypass -File scripts/run-live-answer-workflow.ps1 `
  -SourcePdf "习题/广州物理中考试卷/2025广州中考.pdf" `
  -ReferencePdf "习题/广州物理中考试卷/2025广州中考（答案）.pdf" `
  -OutputDirectory "tmp/runs/2025广州中考" `
  -KeepReview

若 Node 直连 AI 网关出现 UND_ERR_CONNECT_TIMEOUT，但本机已配置 HTTP_PROXY、HTTPS_PROXY 或 ALL_PROXY，可在同一命令增加 -UseGatewayProxy。该开关只在本次工作流进程内启用 Node 环境代理，并仅从本次子进程的 NO_PROXY 副本中移除 .env 已配置的 AI 网关主机；不会修改持久环境变量。

工作流默认执行视觉审计。只有诊断旧链或明确控制 provider 成本时才使用 -SkipVisualAudit；这会恢复单次盲答路径，不能作为可信交付。

每个 AI 阶段都会原子写入独立的 *.summary.json；工作流最终写入 <原卷名>.workflow-run.json，记录 run id、输入 SHA-256、阶段 completed/skipped/failed、当前阶段产物和最终交付哈希。两类回执在写出时都经 prompts/shared/schemas/ 的 schema 校验，结构漂移即失败。失败回执会指向保留的临时诊断目录；这些回执证明本次执行和文件绑定，不证明答案语义正确。

只对已有答案 Markdown 做校验和 PDF 交付：

npm --prefix tools/latex-renderer run deliver -- `
  "正式交付/广州物理中考参考答案/2025广州中考参考答案.md" `
  "正式交付/广州物理中考参考答案/2025广州中考参考答案.pdf" `
  --subject-pack junior-physics-answer `
  --profile classroom `
  --keep-review

从已交付的答案 Markdown 导出 Word 版本（LaTeX 公式转为 Word 原生 OMML 公式）：

node tools/latex-renderer/export-answer-docx.mjs --markdown "正式交付/广州物理中考参考答案/2025广州中考参考答案.md"

live AI 请求必须显式允许云出网，并读取本机 .env。仓库不存储密钥。

核心目录

• prompts/specs/：人类规范真源；compiled 文件由 assembler 生成。
• prompts/junior-physics-answer/：规则、排版 profile 和版本 manifest；运行提示词由 prompts/specs/compiled/ 的汇编产物承担。
• tools/ai-gateway/：显式云出网的答案生成请求。
• tools/rule-compiler/：subject-pack、规则和 snapshot 编译与校验。
• tools/latex-renderer/：Markdown 校验、PDF 渲染、review 页图和交付 manifest。
• scripts/run-live-answer-workflow.ps1：真实原卷主链入口。
• src/：单项目 WPF 应用；承载主链操作、状态展示与本机适配。
• eval/junior-physics-answer/：共享 renderer/layout 合同与主产品包回归；其他学科只保留独有 case 和 subject-pack sentinel。

验证

按变更面运行最低充分检查：

# WPF 应用
dotnet build ClassroomToolkit.sln -c Debug
dotnet test tests/ClassroomToolkit.Tests/ClassroomToolkit.Tests.csproj -c Debug --no-build --filter "Gate!=ToolchainIntegration"

# subject-pack spec / rules
pwsh -NoProfile -ExecutionPolicy Bypass -File scripts/check-toolchain.ps1 -Mode Core -SubjectPack junior-physics-answer

AI gateway、renderer 和 eval 改动运行各自 package 的 focused Node 测试；workflow、publish、packaging 或 Node CLI 合同再运行 Gate=ToolchainIntegration 的 .NET 集成测试（该集合包含真实启动 node/pwsh 的进程生命周期用例，耗时以分钟计）。Core 只做联合资产合同与目标 subject-pack 的 profile snapshot，通常数秒完成；不再捆绑无关 gateway/renderer 测试或 PDF eval。共享 spec/schema、跨学科或 release 变化才使用 -Mode Full。Core/Full 已内置一次 validate:assets，不要在外层重复执行。

Gate!=ToolchainIntegration 的普通集合只保留纯单元/文件系统用例，以便快速反馈；不要往其中新增需要真实外部进程的测试。

Full 中共享 renderer/layout/delivery 回归只由 junior-physics-answer eval 承担一次；廉价 manifest 合同独立验证负向边界。Senior/Math 仍使用各自 snapshot 和独有 sentinel，不能把共享回归去重解释为跳过跨学科合同。

scripts/bootstrap.ps1 会安装基础依赖，只用于环境初始化，不是日常门禁；可选 OCR 由 renderer 的 review-source-pdf --ocr 显式启用。

已删除的弃用入口（2026-10-09）

2026-09-30 到期的弃用窗口已执行删除，消费者审计结论见 Git 历史：ai-gateway 的 request:text/probe:text/TEXT_PROVIDER_* 旧前缀/--image flag/整卷 visual_audit 模式、rule-compiler 的 resolve:profile、latex-renderer 的 visual:smoke 与各 subject-pack manifest 的 visualSmoke 字段均已移除。视觉审计只保留 findings/merge 两段路径；审计图输入必须搭配 --audit-findings-only。交付过程归档/ 内历史 snapshot 保留 visualSmoke 记录属于当时事实，不改写。

桌面发布边界

WPF 当前是仓库伴随应用，运行 check/deliver 仍依赖外部可写仓库以及其中的 Node/npm、PowerShell、prompt、snapshot 和 eval 状态。scripts/publish-app.ps1 会清空准确的 publish 目录，以 Release 生成应用，并在仓库外复制发布树执行隔离启动 smoke；该 smoke 只验收“应用可启动且缺少仓库时正确 fail closed”，回执绑定 source commit、EXE SHA-256 和 publish-tree SHA-256。

当前不采用 MSIX（决策见 docs/strategy/final-implementation-baseline.md，2026-10-10 移除始终阻断的 pack-msix 墓碑脚本）。不得把当前 publish/smoke 结果描述为自包含安装包验收。

获取与迁移

项目提供四种互不覆盖的分发方式：ordinary-user 标准安装版、ordinary-user 绿色便携版、公开源码开发包和私用开发迁移包。它们都不把真实 API key 放入 GitHub Release 或公开源码包。标准安装版与绿色版共享版本化 runtime bundle；只有完成代表性非开发者验收后，才可标记为 stable 对外发布，代码签名为可选。

交付物目录与发布状态

本机可重建产物统一写入 Git 忽略的 artifacts/，deliveries/、history/、work/ 三层不混放；目录约定与清理命令见 artifacts/README.md，正式公开下载以 GitHub Release 资产为准。GitHub 上的 v1.0.1 是遗留 tag/release 资产，后续 main 的发布、安装和迁移加固尚未由新的 Release 对外发布；不要把本机 artifacts/deliveries/<version>/ 或 Actions 候选包当作线上下载地址。候选包先从 main 按版本构建，失败后可在不创建 tag 的情况下修复重试；代表性非开发者验收同一候选后，再创建版本 tag 并手动发布。步骤见 docs/release-and-transfer.md。

四种分发方式的对照表、安装/导出/导入命令、workspaceContract 升级边界、签名与回滚流程，统一维护在 docs/release-and-transfer.md；该文档与 src/ClassroomToolkit.App/ClassroomToolkit.App.csproj 的 <Version> 是这些事实的单点真源，README 不重复维护命令与表格。

可信边界

delivery-manifest.json 1.1 会把输入 Markdown、最终 PDF、同目录交付 snapshot 和 <PDF基名>.review/ 包内 review 文件绑定到字节数与 SHA-256；validator 会拒绝缺失、篡改或 review 文件集合漂移。.pdf-review/ 只保留可选调试副本，不是归档依赖。该 manifest 证明的是指定文件之间的交付关系，不证明答案语义必然正确。答案可信需要满足以下至少一项：

• 与权威参考答案逐题比对并完成校正；
• 由教师逐题复核；
• 后续自动比对能力给出可审计差异，并由规则或人工处理未决项。

继续扩写 100 KB 级主提示词不是当前主要优化方向。优先级是参考答案复核、局部高清题图、遗漏检测和真实试卷回归。