course-authoring

name	course-authoring
description	写学习讲义、深度课程、教程，或出任何测验题（quiz、自测、面试模拟）时使用。2026-07-24 用户对旧讲义系统性批评后定的标准；2026-07-29 增补格式骨架 + 写作硬规则 + 图表规范。

深度讲义与出题标准

维护记录：2026-07-24 定讲义七条/出题两条/交付三查；2026-07-29 增补「章节骨架」「写作硬规则」「图表规范」「交付前自查」——针对用户 review：格式与图表已达标，文字仍不够详细、毛病多。

讲义七条（2026-07-24 大改判，以 Codex 增强版模板为准）

1. 零比喻：不要「大厨/接待员」式类比，不准发明新词；术语用标准名 + 首次一句白话解释。
2. 密度降下来：短段落、直白句。旧版败因就是「文字密度过高，看起来费劲」。
3. 3W 结构：每个概念交代 What / Why / Where（项目里哪个文件）。黑箱拆到底。
4. 强项目针对性：先讲够上手手头项目的核心知识，别想到哪讲到哪。
5. 消除知识→实践 gap：手把手步骤、每步配验证方法；讲得好的地方直接给官方/中文文档链接 （cn.vuejs.org、MDN 中文等，不得编造 URL）。
6. 必备栏目：适合谁 / 读完能做到 / 一句话本质 / 概念地图 / 最先要干的事（打开哪些真实文件）/ 学习路径建议 / 项目实操（步骤 + 可编辑练习 + 排查表）/ 学完之后自查清单 / 全章知识地图。
7. 引用的项目路径/行号必须先读真码核实，不许凭印象写。

出题两条（2026-07-22 用户批评后定）

1. 干扰项必须是真实常见误解，禁止一眼假。好干扰项 =「学习者真的会这么想的错误」： 「401 和 403 是一回事」「Base64 是加密」「HTTP 200 就代表业务成功」。 一眼假的干扰项（「@PreAuthorize 是样式」）让选择题退化成词汇辨认。解析里顺带拆穿干扰项为什么错。
2. 答案位置打散，不全放第一个选项，防按位置猜题。

边界（2026-08-14）：若产物是「自足单文件学习笔记 HTML」（外链策展式），排版与产出交给 learning-notes-html skill——它已声明出题标准以本 skill 为正本；本 skill 是内容与出题标准的正本，单文件排版流水线归它。

HTML 讲义交付前三查（2026-07-24 事故后立）

1. 数 <div> / </div> 配平（曾因头部丢一个闭合标签，全页白字白底）
2. 浏览器实渲染 + 对比度扫描，不能只靠标签配对脚本
3. 目录条目与正文标题逐条比对

---

章节骨架（2026-07-29 增补：照抄结构，别照抄那套 ugly 视觉）

骨架完整写在下面，直接照抄，不依赖外部样板；视觉范本用 learning-notes-html 的黄金范本（02-Python基础.html，群青蓝极简系）。（2026-08-14：原指向的公司平台课程样板按「公司项目内容永久排除」规矩移除，且其暖纸主题本就自评偏丑不可照搬。）

一章 = 开场闸门 → 编号正文 → 收尾三件套。

开场闸门（进正文前）

• 标题 + 一句 lead，重述本页要往下挖什么
• 三卡：适合谁 / 读完能做到 / 一句话本质（本质加粗）
• 概念地图：把本章名词串成一条「从源码到数据」的执行链，不是孤立名词表
• 最先要干的事：钉住 3–5 个真实文件，让读者当成标签页打开
• What / Why / Where 三卡
• 官方资料在哪查：真链接 + 何时查（不得编 URL）
• 怎样循序渐进读完：第一遍 / 第二遍 / 第三遍 + 时间预算

编号正文 §01…§N —— 每节复用同一微骨架

• H2 标题
• 紧跟一句本质句（例：「一句话：算值用 computed，干活用 watch」）
• 正文：概念 → 对立 → 机制（先立矛盾再点破机器，别一上来甩术语）
• 一张内嵌图 + 图注
• 需要时开「深挖 ①/②」讲更硬的机制
• 练手代码块，末尾「进阶到真项目」指向真文件 + 行

收尾三件套

• 项目实操：只读警告 → 任务目标 → 步骤 A–E（每步末尾「验证：…」）→ 标注真码 → 参考答案 → 排查表（现象 / 第一检查点 / 不要先做什么）
• 自查清单：四项判断「是否真会了」
• 全章知识地图：分带（源码到页面 / 横切机制 / 文件地图 / 证据闭环）

md 版用轻量同骨：本章要点 → 正文 → 自测·思考题 → 解答 → 常见误区·实际情况 → 一条实用判据 → 小结（与 operation-notes\写作规矩.md 一致）。

---

写作硬规则（把「文字不详细」变成可当场打勾的动作）—— 本次重点

七条第 2/3/5 条只给了原则（「密度降下来」「3W」「消除 gap」），产出仍飘。下面每条都能当场判「过不过」。 ❌ 取自真实弱样本，✅ 是改法。

1. 讲机制，不罗列。 每列一个功能 / 接口 / 名词，必须紧跟「它怎么运作 / 何时被谁调用 / 与旁边那个的区别」。纯清单不算讲。

   • ❌「订单包含五类：配额订单；任务订单；服务订单；预置调用订单；存储订单。」（五个名词，不画区别）
   • ✅ 逐类一句：什么动作触发它、结算口径差在哪。

2. 每个断言都还「为什么」。 写下一个设计事实，后面必须跟机制或原因；硬处用自问句引出（「X 为什么必须存在？」）。

   • ❌「实时逐笔结算既昂贵又易乱，批量结算更稳更省。」（贵在哪、乱在哪，没给）
   • ✅「逐笔每来一条调用就写一次账、抢一次锁……所以改成每 N 分钟批一次。」

3. 类比只引入、不替代。 类比之后必须落到真名词，否则删。

   • ❌「响应式：用它包起来的变量会『被界面盯着』。」（止于比喻）
   • ✅「……底层是 Proxy 把变量读写记账（track），值一变就通知用到它的组件重渲染。」

4. 术语先定义后使用。 首次出现给一句白话解释；「富化 / 业务载体」这类黑话当场兑现，不许先用后不解释。

5. 锚到真文件 + 行 + 代码。 概念引用项目代码，必须点名文件、给行号、贴出那一行并逐行注释；禁止甩裸路径，禁止把所有路径堆到文末一节。

   • ❌「页面矩阵由 src/api/roleMatrix.ts 静态维护。」（点名却不打开）
   • ✅ 贴出该文件关键几行 + 注释，就地讲。

6. 概念配一步能做的实操 + 闭卷验证。 讲到某文件不能只说「去看」，走一个最小实例；每步末尾一句「合上文件，说出这几步」。

7. 每篇至少一条「一镜到底」。 把一次真实请求 / 一次点击从头到尾串讲一遍（不是目录式清单），让读者看到链路而非索引。

8. 删免责噪音。 少写「不要误以为……」这类元声明；确有边界，一句点到即止，不单开一节堆七条。版面让给「讲清楚」。

9. 每个标题下先一句本质。 进细节前先给一句平白结论。

---

图表规范（图表是强项，定住别跑偏）

• 先问这张图省了什么事：能一句话或一张两列表说清的，别上图。图用在「多映射 / 一处影响多处 / 时序变化 / 层级结构」。
• 配色走项目色板：优先复用目标项目已有的深浅两态同源色板；没有就按 dataviz skill 的校验色板来，别每处硬编 hex；深色要有专用色序（中性灰沉底，避免大扇区发糊）。
• 深浅都要能看：canvas 图用不到 CSS 变量，深色需在代码里套色；SVG 手绘图注意深底对比度。
• 轴 / 图例 / 单位齐全；别为装饰给扇区、条形加渐变到读不出数值。
• 色板与可达性细则见 dataviz skill。

---

交付前自查（写作硬规则的落地清单，与上面「HTML 三查」并列）

逐条打勾再交：

1. 有没有纯罗列的功能 / 接口 / 名词段？→ 每条补上机制或区别
2. 有没有断言没给「为什么」？
3. 类比有没有落到真名词？
4. 术语首次出现有没有一句解释？
5. 点名的文件有没有给行号 + 贴码？还是只甩了路径？
6. 每个实操步骤有没有配验证？
7. 全篇有没有至少一条「一镜到底」？
8. 有没有免责噪音可删？
9. 每个 H2 下有没有一句本质句？