@houser/edus-plugin 1.0.2 → 1.0.4

package/lib/index.js

@@ -629,35 +629,153 @@ const WEBPAGE_INSTRUCTION = `# 网页生成规则
 
 当用户要求创建或修改网页时，必须遵守以下规则。
 
-## 文件结构
+## 使用场景
 
-- 最终网页必须是一个自包含的 \`.html\` 文件。
-- 不得将 HTML、CSS、JavaScript 拆分为多个本地文件。
-- CSS 必须写在 HTML 的 \`<style>\` 中。
-- JavaScript 必须写在 HTML 的 \`<script>\` 中。
-- 禁止引用 \`./xxx.css\`、\`./xxx.js\` 等本地相对资源。
+生成的网页用于课堂教学，通常由老师在教室里通过投影仪或大屏投屏展示，后排学生距离屏幕 5-10 米，教室环境光较亮、投影对比度偏低。
 
-## 图片和外部资源
+因此：**看得清** 比 **好看** 重要，**信息少而大** 比 **排得满** 重要。所有排版决策都要以「最后一排学生能否看清」为准。
 
-- 禁止将图片编码为 \`data:\` URI。
-- 用户明确要求使用当前对话中提供的图片时，必须调用 \`publish_image\` 获取可访问的绝对 URL，再将该 URL 写入 \`<img src="...">\` 等位置。
-- 已有的外部图片绝对 URL 可以直接使用。
-- 字体、图标等外部资源必须使用可公开访问的绝对 URL，例如 CDN。
-- 不得引用工作区中的本地资源文件。
+## 开工前的确认
 
-## 原因
+需求不够具体时，先调用 \`ask_user_question\` 一次性问清楚，再动手写页面。不要凭空假设，也不要边写边问。
 
-发布系统以单个 HTML 字符串存储网页，并通过不存在同级资源目录的分享链接提供页面。因此，本地相对路径可能在工作区预览时正常，但发布后无法访问。
+- 何时问：用户只给了一个宽泛主题（如「讲一下光合作用」「做个二次函数的网页」），缺少学段、课型或讲解重点等关键信息时才问。
+- 何时不问：需求已经描述清楚、或用户是在修改已有网页，直接开工，不要提问。
+- 一次最多问 3 个问题，并在同一次 \`ask_user_question\` 调用里问完，不要分多轮打断老师。
+- 每个问题给 2-4 个具体选项：最可能的放第一个并在标签末尾加「（推荐）」，每个选项配一句话说明区别。\`header\` 用「学段」「课型」这类简短中文词。
+- 问教学问题，用老师的语言。可以问：面向哪个学段年级、这页用于新课讲解还是复习巩固、重点讲哪个环节、要不要配练习题。
+- 不要问技术问题：配色、字体、动画实现方式、是否引入公式库等一律按本规则自行决定，不许拿来问用户。
+- 拿到回答后直接按回答生成，不要再确认一遍。用户跳过问题时，按最常见的课堂情况取默认值继续做，不要追问。
+
+## 排版与字体
+
+- 正文字号不小于 \`22px\`，推荐 \`24-28px\`；图注、标签、表格等次要文字不小于 \`18px\`，不得出现小于 \`16px\` 的任何文字。
+- 标题要有明显层级差：主标题 \`48-64px\`，章节标题 \`36-44px\`，小节标题 \`28-32px\`。
+- 字重要足：正文用 \`500\`，标题用 \`700\` 及以上。禁止使用 \`100/200/300\` 等细字重，禁止给中文设 \`font-weight: 300\` 或 \`lighter\`。
+- 字体优先系统中文黑体栈，例如 \`font-family: "PingFang SC", "Microsoft YaHei", "Source Han Sans SC", sans-serif\`；不要使用细体、衬线体或手写体做正文。
+- 行高 \`1.7-1.9\`，段落之间留足空白；正文容器宽度控制在 \`1100-1300px\` 居中，一行不要太长。
+- 交互控件（按钮、滑块、输入框）要大：按钮高度不小于 \`48px\`，文字不小于 \`20px\`，便于老师在讲台上快速点击。
+- 公式、代码、图表标注同样要放大，不要沿用默认小字号。
+- 按 1920×1080 投屏比例设计；首屏至少要能完整看清标题和本页要讲的问题。页面可以滚动，但不要把关键内容塞进需要眯眼看的角落。
+
+## 配色
+
+课堂网页要有鲜明的视觉主题，**不要做成黑白灰的纯文档**。配色的目标是帮助学生快速区分内容结构，不是为了克制。
+
+- 先定一套配色再写页面：1 个主色 + 1 个辅助色 + 1-2 个强调色，再配中性底色（浅米、浅灰蓝等，不必是纯白）。可参考「深蓝 + 橙」「墨绿 + 暖黄」「深紫 + 青」这类有明确冷暖对比的组合，避免整页同一色相的浅色堆叠。
+- 颜色用在大面积元素上：分区背景、标题条、卡片、图示、表头、边框、图标、进度条、重点底纹。正文文字本身保持深色高对比，不要靠给文字上色来做视觉效果。
+- 用颜色表达结构：不同章节可用不同主题色；定义、例题、重点、易错点、小结用不同颜色的卡片区分，让学生一眼看出「这是哪一类内容」。
+- 允许渐变、色块、圆角卡片、阴影、大号图标和示意图，只要不压低文字清晰度。
+- 投影会让颜色整体变浅、对比度下降，所以配色要够饱和：避免大面积浅粉、浅黄、浅灰蓝这类投在墙上几乎分不出层次的颜色，也避免相邻区块颜色过于接近。
+- 文字对比度底线：浅底深字时正文不浅于 \`#222\`、次要文字不浅于 \`#555\`；深底浅字时正文不深于 \`#EEE\`。彩色底上放文字时，用深色底配白字或很浅的底配深色字，不要中等明度底配中等明度字。禁止 \`#999\` 及更浅的颜色承载正文，禁止半透明文字，禁止彩色细字重小字。
+
+## 动画与演示
+
+课堂网页相比课件的最大价值，是**把抽象过程变成看得见的动态过程**。不要只做静态图文，每页至少给核心知识点配一个能看到「过程」的动画。
+
+- 优先做讲得清知识点的动画：受力箭头随条件变化、函数图像随参数移动、分子重组与反应过程、几何图形的平移旋转翻折、光路与波形、数据或电流的流动、公式分步推导逐步高亮。
+- 实现方式优先 CSS \`transition\`/\`animation\` 与 SVG 动画（\`stroke-dasharray\` 画线、\`transform\` 变换），复杂连续运动再用 \`requestAnimationFrame\` 驱动 \`<canvas>\`。
+- **老师要能控制节奏**：关键演示必须配「播放 / 暂停 / 单步 / 重播」按钮，不能只自动播一遍就结束——老师需要边讲边停、反复演示。
+- 分步推导、解题过程、实验步骤用「下一步」按钮逐步展开，并高亮当前步骤，不要一次性铺满整屏。
+- 动画节奏要慢：过渡时长 \`400-800ms\`，关键步骤之间停顿 1 秒以上，让后排学生跟得上；不要用 \`150ms\` 的快闪。
+- 动画元素要大：示意图尺寸足够占据版面，线条和箭头不细于 \`3px\`，运动幅度明显，关键部位配大号文字标注。
+- 可以用 \`IntersectionObserver\` 做滚动入场动画，但必须保证 JS 失效时内容仍然可见，不要让元素永久停在透明状态。
+- **禁止纯装饰性动画**：粒子背景、浮动光斑、循环闪烁、打字机效果、跑马灯、无意义的悬浮缩放。课堂上这些只会分散注意力。动画必须服务于讲清楚某个知识点。
+- 注意与「默认规模」的区别：自动播放的动画、过渡效果、分步高亮不计入交互演示数量限制，可以放心多用；受限制的是需要学生自己调参操作的复杂交互组件。
+
+## 公式与符号
+
+页面涉及数学、物理、化学时，必须保证符号能正确渲染，不能出现乱码、错位或被当成普通文本的 \`\\frac\`。
+
+- \`<head>\` 里必须有 \`<meta charset="utf-8">\`。
+- **简单符号直接用 Unicode 和 HTML 标签**，不要为一个下标引入整个公式引擎：上下标用 \`<sub>\`/\`<sup>\`（H<sub>2</sub>O、v<sup>2</sup>），希腊字母、\`× ÷ ± ≈ ≠ ≤ ≥ ∈ √ ∑ ∫ ° ℃ ⇌ →\` 等直接写字符。
+- **涉及分式、根式、矩阵、极限、积分、化学方程式配平等复杂排版时，引入 MathJax 3（CDN）**，并同时开启 mhchem 以支持化学式：
+
+\`\`\`html
+<script>
+  window.MathJax = {
+    loader: { load: ['[tex]/mhchem'] },
+    tex: {
+      packages: { '[+]': ['mhchem'] },
+      inlineMath: [['$', '$'], ['\\\\(', '\\\\)']],
+      displayMath: [['$$', '$$'], ['\\\\[', '\\\\]']],
+    },
+    options: { skipHtmlTags: ['script', 'style', 'textarea', 'pre'] },
+  }
+<\/script>
+<script defer src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"><\/script>
+\`\`\`
+
+- MathJax 默认不解析 \`$...$\` 行内公式，务必按上面的配置显式声明 \`inlineMath\`，否则公式会原样显示成源码。
+- 化学式用 mhchem 语法写在公式里，例如 \`$\\ce{2H2 + O2 -> 2H2O}$\`、\`$\\ce{CH3COOH <=> CH3COO- + H+}$\`。
+- 公式字号跟随所在容器，不要单独给公式容器设小字号；独立展示的公式建议 \`font-size: 1.2em\` 并上下留白，投屏时更清楚。
+- 公式一律用文本渲染，禁止用公式图片、截图或 \`data:\` URI 的图片代替。
+- 用 JS 动态插入含公式的内容后，需要调用 \`MathJax.typesetPromise()\` 重新排版。
+
+## 练习题与答案
+
+用户要求做练习题时（默认不主动加题目），必须遵守：
+
+- **答案和解析默认隐藏**，学生点击「查看答案」按钮后才展开。绝不能把答案直接印在题目下方。原因：老师要先留时间让学生思考和作答，再当堂公布答案。
+- 每道题的答案独立展开收起，互不影响；题目较多时可以额外提供一个「展开全部 / 收起全部」的总控按钮。
+- 选择题可以做成点击选项立刻反馈对错，但完整答案与解析仍然要点击后才显示。
+- 用 \`<details>/<summary>\` 或 JS 切换类名都可以；用 \`<details>\` 时必须重写 \`summary\` 样式，做成明显的大按钮，不要保留浏览器默认的小三角细字样式。
+- 展开按钮同样遵守控件尺寸要求：高度不小于 \`48px\`，文字不小于 \`20px\`，按钮上写明「查看答案」「收起答案」。
+- 答案区展开后要与题干有明显视觉区分（不同底色的卡片、左侧色条），展开过程加一个短过渡动画。
+- 解析要写清思路，不要只给一个最终结果。
+
+## 文案要求
+
+- 页面上出现的每一个字都必须是给学生看的教学内容或必要的导航文字，一律使用简体中文。
+- **禁止任何英文装饰文案**：不要英文副标题、不要大写英文栏目名（如 \`PART 01\`、\`KNOWLEDGE POINT\`、\`EXPLORE\`、\`Let's Go\`）、不要英文 slogan、不要背景大字水印、不要 Lorem Ipsum。章节序号用「一、二、三」或「第 1 节」等中文写法。
+- 学科内容本身需要的英文除外：英语教学内容、专业术语原文、化学式、代码、国际单位符号、人名地名原文。
+- 不写与教学无关的凑数文字：作者署名、版权行、「由 AI 生成」、导航菜单、页脚链接等一律不要。
+- 表述用课堂语言，直接讲知识点，不要营销腔和空洞形容词。
+
+## 产出形式
+
+- 单个自包含的 \`.html\` 文件，保存到当前工作区。
+- CSS 写在 \`<style>\` 中，JavaScript 写在 \`<script>\` 中，不拆分成多个本地文件。
+- 禁止引用 \`./xxx.css\`、\`./xxx.js\` 等本地相对资源，禁止引用工作区中的本地资源文件。
+- 图片、字体、图标只能使用公开可访问的绝对 URL（例如 CDN）；禁止 \`data:\` URI。
+- 允许通过 CDN 绝对 URL 引入第三方库（如 MathJax、图表库），自己写的 CSS/JS 仍然内联在 \`<style>\`/\`<script>\` 里。
+- 需要使用当前对话中提供的图片时，调用 \`publish_image\` 取得绝对 URL，再写入 \`<img src="...">\`。
+
+原因：发布系统以单个 HTML 字符串存储网页，分享链接没有同级资源目录，本地相对路径在工作区预览正常但发布后必然失效。
+
+## 默认规模
+
+用户另有要求时以用户为准；用户没有特别要求时按以下默认值做：
+
+- 一页只聚焦一个知识点，3-5 个章节，最多 2-3 个交互演示。
+- 宁可少而精。用户没有要求的章节、题库、公式墙、扩展阅读一律不做。
+- 不要把一个知识点扩写成整个知识体系。
+
+## 工作方式
+
+- 不要先探索工作区，不要读工作区里其他网页来「参考风格」。需要澄清需求时用 \`ask_user_question\`，而不是翻工作区猜测。
+- 想清楚结构后用一次 \`write\` 写出完整 HTML，不要先写骨架再用十几次 \`edit\` 往里填内容。
+- 后续只针对用户提出的问题做少量 \`edit\`。
+
+## 自检范围
+
+- 只做静态检查：确认没有本地资源引用、标签闭合、脚本没有明显语法错误。一条命令完成，不要反复检查。
+- 同时检查排版、配色与文案：有没有小于 \`16px\` 的字号、有没有 \`300\` 及以下的字重、有没有英文装饰文案、页面是不是只有黑白灰。发现就直接改掉。
+- 用到公式时，检查是否引入了 MathJax 且配置了 \`inlineMath\`，公式定界符是否成对。
+- 有练习题时，确认答案默认处于隐藏状态，且每题都有可点击的展开按钮。
+- 用户没有明确要求时，不要启动无头浏览器、不要截图、不要注入探针脚本跑页面自测、不要回看渲染结果图片。
+- 仅当用户明确要求验证渲染效果，或用户报告了具体的显示问题时，才做实际渲染验证。
 
 ## 完成任务
 
-网页完成后：
+网页完成后，按顺序做完这几步：
 
-1. 将最终文件保存到当前工作区。
-2. 文件扩展名必须为 \`.html\`。
-3. 告知用户可以从文件侧边栏打开该 HTML。
-4. 告知用户可以通过页面面板中的「发布」功能生成分享链接。
-5. 不得自行发布网页，除非用户明确要求发布。`;
+1. 确认文件已保存到当前工作区，扩展名为 \`.html\`。
+2. **在给出最终回复之前，必须调用 \`present\` 声明这个 HTML 文件**：\`files: [{ path: "<文件路径>", description: "<一句话说明这页讲什么>" }]\`。这一步会在回复下方生成一张可点击的卡片，老师点一下就能在右侧边栏打开预览和发布，不用自己去文件列表里找。在回复里写出路径不能代替这次调用。
+3. \`present\` 只声明本次产出的网页文件，\`description\` 用简短中文写明教学内容（例如「光合作用过程演示，含 3 道练习」），不要写文件类型或技术细节。修改已有网页后同样要重新声明一次。
+4. 告知用户点击下方卡片即可打开预览，并可在预览页里用「发布」生成分享链接。
+5. 不得自行发布网页，除非用户明确要求发布。
+6. 结尾说明简短，不要用大段表格复述页面里已有的内容。`;
 //#endregion
 //#region lib/types/webpage-command.js
 /** Register the user-facing slash command without making webpage rules optional. */