朱劳斯高师院校智能体大赛助手
把一个已经能运行的教学智能体（Web 应用）做成完整的参赛材料包。
提炼自两次实战：“琴韵智评”（赛道三，真实 AI 输出回放 + ffmpeg 后期）和“演知思政”（赛道四，全新演示环境分场景录屏 + HyperFrames 合成 + 本人声音克隆 + 全套双盲脱敏）。两条路线在下面都有，按作品情况选。
scripts/ 里是实际跑通的脚本模板，references/ 里是各环节的细节。脚本里的路径、账号、选择器、旁白都要按新作品改。
适用赛事与规则适配
本技能适用于高师院校智能体大赛，也可用于中国教育技术协会的智能体大赛，为教学智能体项目准备参赛说明书、应用成效材料、图表、部署包和展示视频。具体赛事名称、参赛资格、赛道设置、评分权重、匿名要求、材料编号、文档页数和视频规格，均须依据用户提供的当届官方通知逐项确认。本技能中的页数、时长、材料编号和评分权重仅为已有赛事示例，不直接作为其他赛事的规定。
交付物（按比赛“材料要求”编号命名，便于上传）
| 编号 | 交付物 | 要点 |
|---|---|---|
| 2 | 访问地址 / 部署包 | 在线服务给地址；本地部署给源码包（pack_deploy.py 带脱敏与密钥扫描） |
| 3 | 展示视频 | MP4、1080P、6–10 分钟、字幕、带章节分段的自动进度条、文件 ≤ 上限 |
| 4 | 智能体设计与应用说明书 | Word，页数按通知（常见 ≤5 页） |
| 5 | 应用场景、成效及推广价值材料 | Word：场景、截图、量化数据、用户反馈、对比成效、推广方案 |
| — | 图与截图 | 原理/框架/机制/流程图 PNG；工作截图；全部已脱敏 |
报名表、盖章的身份证明由用户自己办，交付时提醒截止时间。
第 0 步：一次问清楚
用选择题一次问完，能从材料里读到的不问：
- 比赛通知原文：没有就请用户附上，不凭记忆写评分规则。
- 赛道与组别：给出建议（如“教研创新赛道 · 本科组”）并说明理由，让用户确认。
- 成效数据：规模口径（学校数、课程数、人数各指什么）；有没有真实反馈原话或问卷；没有的话是留黄色待填还是删节。
- 配音：A 标准普通话 AI 配音（推荐，不暴露身份）／B 用本人录音在本机克隆（要录音文件，环境约 3GB，CPU 上需 1–2 小时）／C 本人按稿录制。详见 references/voice.md。
- 演示画面来源：A 在用户部署上真实运行后回放／B 全新本地演示环境分场景录制。详见 references/recording-and-video.md。
- 素材：课堂照片、实拍视频（常要求“裁剪一致”）、logo、测试账号。
- 制作节奏：先审分镜和解说词，还是直接出成片（临近截止时推荐直接出成片，看完再改）。
第 1 步：评分规则对照表
用 PyMuPDF 或 pdftotext -layout 读出通知原文，提取：
- 材料要求：说明书必须含哪些章节；成效材料必须含哪些项（场景、截图、量化数据、用户反馈、对比成效、推广方案）。
- 评分维度和权重，例如高师大赛：合规与伦理 15、创新价值 20、技术实现 25、教学融合与应用设计 25、应用成效与推广价值 15。
- 红线：双盲（不得出现姓名、学校、院系）；数据造假取消资格；视频时长、大小、分辨率、格式；截止时间。
建一张对照表：评分点 → 在材料哪一节回应 → 用什么证据（图、截图、数据）。写作时逐行勾选；视频章节也按它排。
第 2 步：双盲脱敏（贯穿全程）
身份暴露是最容易被忽视、代价最大的问题：照片、截图、实拍视频、图里的机构名、Word 作者属性、源码、测试账号显示名都要查。
完整清单与做法见 references/anonymization.md；工具：anon_images.py（照片截图打码）、face_blur_video.py（视频人脸：自动检测 + 人工关键帧 + 裁剪）、pack_deploy.py --ban（源码扫描）。
第 3 步：为参赛对作品做的小改造（可选，视作品而定）
- 管理端“导出成效数据”：弹窗展示并可下载 Markdown；数字全部由系统记录直接计算，口径写清（总体规模、前后对比、质量表、分级情况）。
- 提示词加一句：“比率和指数已按既定口径计算并四舍五入，直接引用，不要自己重算，也不要讨论口径差异。”否则报告里会出现“口径待核对”。
- 重置演示数据时保留大模型设置；演示种子数据不落在未来时间（以今天 0 点为基准往前推，最后一天为昨天）。
- 改完把每个角色端的每个页面点一遍，确认无报错；跑一遍作品自带测试。
第 4 步：准备演示画面
两种模式，细节见 references/recording-and-video.md：
模式 A：真实输出回放（record_screencast.js、shots.js）
- 在用户本机部署上按视频顺序把剧本真实跑一遍；hook window.fetch 记录每次大模型请求与返回，存 replay.json，记下时间戳 T。
- 密钥由用户自己在面板里填写，绝不代填；先读设置（遮掉 apiKey）并直连一次接口确认能通。
- 每次执行的页面脚本不超过约 40 秒，长流程拆开；上传测试图用 fetch → File → DataTransfer，用完提醒用户删掉测试图。
- 录屏：Playwright + CDP screencast，addInitScript 把时间设到 T-90s，context.route 按请求内容回放 replay.json，每次延时 2–4 秒让“正在分析”出现在画面里；部署上出现过的失败/重试也要重现。
模式 B：全新演示环境分场景录制（record_scenes_cdp.mjs）
- 新数据目录起本地实例；管理员“平台管理员”、教师“演示教师”，用作品自带的“演示用虚构数据”；密钥填占位串。
- 每个场景一个 mp4，可单独重录；跨场景信息写 rec-state.json；弹窗按钮按文字点。
两种模式都要：假鼠标 + 点击波纹、关键区域红框高亮、录完逐段抽帧检查（报错、身份信息、空白页）。
第 5 步：画图
- 四张图：原理图（核心处理链路）、框架图（分层结构 + 安全合规侧栏）、机制图（协同/评价机制，虚线回到再评价）、流程图（角色泳道或闭环，步骤带序号）。
- 做法一：
diagram_mk.py+diagram_specs_example.py（JSON 描述方框箭头 → HTML → 2 倍截图）。 - 做法二：直接写 HTML/CSS（flex/grid 卡片 + 芯片标签）→ 无头 Chrome 2 倍截图 → PIL 裁白边。复杂排版更省事。
- 成效材料另需：三类应用场景图、数据卡图、三步推广图。
- 图内不写“图N”，编号交给文档图题；视频用带标题版、文档用无标题版。
- 复用旧图前检查有没有机构专名（如示范中心名称），有就重画。
- 画完逐张打开：标签压框、框出界、箭头穿字。
第 6 步：旁白与配音
- 先写
script.json（格式见scripts/script_example.json）：每句有ch章节、shot镜头、sub字幕、tts念法。 - 章节按第 1 步对照表排，每个评分维度至少一段；约 50 句、2000–2300 字，成片 7–8 分钟。
- 配音三条路线见
references/voice.md： - A
tts_kokoro.py（sherpa-onnx kokoro，sid=45，speed≈1.05）； - B
tts_f5_clone.py ref → gen → check → retake → assemble； - C 用户自录后走 assemble 的去静音和响度。
- 都要用语音识别抽查（
asr_check.py或tts_f5_clone.py check），并输出timings.json（每句真实时长）。
第 7 步：视频合成
两条路线（references/recording-and-video.md）：
- ffmpeg 后期（post_video.py）：帧按时间戳写 ffconcat；配音按旁白时间点混音；ASS 字幕（≤26 字/条）+ .srt；三层 overlay 进度条，当前章节 enable=between(t,a,b) 高亮；libx264 CRF19、AAC、+faststart。
- HyperFrames（build_hyperframes.py + hf_comp.css）：画面区 + 逐句字幕 + 章节进度条 + 左侧章节标签 + 卡片/图/实拍混排；check 必须通过；render -q delivery --video-frame-format png。
验收：ffprobe（时长、分辨率、编码、大小）、volumedetect、每 ~27 秒抽一帧拼图核对字幕/画面/进度条/身份信息，实拍段放大抽查打码。
第 8 步：两份 Word
脚本：docx_common.js（**粗体**、[[待填]] 黄色高亮、表格、并排图，已含 keepNext/cantSplit/JPG/作者“参赛者”）、doc_design_example.js、doc_effect_example.js。
结构、排版技巧、页数控制见 references/documents.md。
- 用 docx_to_pdf.ps1（Windows Word/WPS）或 soffice 转 PDF，PyMuPDF 数页、逐页渲染拼图检查。
- 标题显式指定颜色（否则 LibreOffice 渲染成蓝色）；表格同时设 columnWidths 和单元格宽度。
第 9 步：打包与交付
pack_deploy.py：只打必要目录，排除数据库/密钥/真实 .env；--ban扫身份词；解压到临时目录用全新数据目录启动并跑测试；缺测试夹具只补那一个文件。- 交付文件夹按材料编号命名：
2-部署包.zip、3-展示视频.mp4、4-说明书.docx/.pdf、5-成效材料.docx/.pdf、配图与截图（已脱敏）/。 - 若通过设备同步工具上传，每次先复制到新的唯一路径再提交（同一路径会被缓存成旧文件），提交后核对大小。
- 最后的回复写清：
- 每份交付物对应哪条要求；
- 哪些数据来自用户口径、哪些来自系统日志；
- 待用户处理的事（试听配音、确认赛道、测试账号显示名、报名表与盖章证明、截止时间）；
- 对作品代码做的改动。
诚信底线
- 不编造规模、成效数字、用户反馈。规模按用户原话写；其他数字只用系统真实导出或日志读出的结果，并写来源。
- 用户转述的反馈整理成“反馈摘要”，不包装成引号原话；没有就留待填或删节，并说明对得分的影响。
- 演示数据里的人名必须虚构；正式材料里的人用“教师A”“某大学××学院教师”。
- 照片若与本作品无关（例如展示的是别的软件），不拿来当应用证据。
- 不代用户输入任何密钥；克隆声音只在用户明确同意并提供本人录音时做，声音数据不上传。
踩过的坑（摘要，完整见 references/env-pitfalls.md）
- 国内网络慢：大文件并行分段下载（
mdl.sh多镜像、pdl.py）；模型从 ModelScope / 直连 HF；先估算再决定 GPU 还是 CPU。 - Windows 路径超长：venv 放短路径；pip 不自升级；版本组合固定。
- 依赖冲突：mediapipe 与 F5-TTS 分两个 venv。
- 弹窗按钮顺序：按文字点，别点“最后一个”。
- 手持视频人脸检测漏检：人工关键帧兜底，读 1:1 网格不换算。
- Windows .bat 里的
>nul可能被改成>/dev/null：用 Python 写文件，只用 ASCII，写完od -c核对。 - 浏览器缓存 ES 模块：
fetch(path,{cache:'no-store'})核对服务端返回的是新代码。 - 杀进程：不要
pkill -f匹配自己命令行里的字符串，也不要按进程名杀全部 python；按端口或 PID 杀。 - 长任务：后台运行，等待“完成或报错”标志，不要短轮询；脚本可续跑，会话中断后先核对产物。
- screencast 只在画面变化时出帧：静止期间由 concat 的 duration 补足。
备赛咨询报告品牌与匿名参赛材料
面向用户的备赛咨询、打印报告按 references/branding-config.md 使用品牌。正式双盲参赛材料以比赛通知为准，不添加可能暴露身份的品牌、Logo 或公众号二维码。
