三剪客 · 课程生产线
## ⚠️ 先申请你自己的 API Key
本 Skill 不内嵌任何密钥,也不代付费用。 请到
算力集市 api.a7w.cn 注册并创建你自己的 API Key
(新用户有赠送点数,可以先免费试跑几次)。
拿到后填进环境变量A7W_API_KEY,或直接传给--key参数。
请勿使用他人提供的 Key —— 用量与费用都记在 Key 所属账号上。
能做什么
给一个主题和一个受众水平,一条流水线跑完课程三件套:大纲 → 逐节讲义 → 习题与解析。
它替代的是备课里最耗时的那个环节:不是"写不出来",而是"要先想清楚讲什么、讲多长、
学员学完能做到什么、拿什么检验"。这三件事想清楚了,写只是时间问题;
想不清楚,写出来的讲义就是一堆正确但没用的废话。
四个子命令对应四个阶段,每一步的产出都能单独拿去用:
| 子命令 | 做什么 | 产出 |
|---|---|---|
plan | 出课程大纲 | 章节 / 小节 / 每节学习目标 / 每节时长(Markdown 表格 + JSON) |
lesson | 按大纲逐节写讲义 | 每节 1500~3000 字正文(四段结构,见下) |
quiz | 按大纲逐节出习题 | 基础 / 应用 / 进阶三档,每题带答案与解析 |
all | 串起来跑完整套 | outline.md + lessons/*.md + quiz/*.json + 合并稿 course.md + 质检报告 |
cost | 只算钱 | 预估 token 与金额,一次调用都不发 |
models | 现查在架模型 | 模型清单(免费) |
| 你最关心 | 答案 |
|---|---|
| 多少钱 | 本地估算(0.02 元/千 token,可覆盖)。实测一套 1 章 2 节约 12095 token、≈0.24 元 |
| 要多久 | 实测:大纲 7 秒、一节课讲义 10 秒、一节 6 道题 9 秒;串起来跑主要看节数 |
| 要装什么 | 什么都不用装。只用 Python 标准库,不需要 pip install 任何东西 |
| 中断了怎么办 | 断点续跑:已完成的节直接跳过,重跑不重复扣费(实测第二次 0 次调用、0.1 秒) |
| 会瞎编数据吗 | 提示词里写死了"不编数据、不编人名机构、不做效果承诺",并用合规闸门兜底 |
| 受众水平怎么体现 | --level zero/basic/advanced 决定术语解释密度与讲练配比 |
讲义的四段结构
lesson 产出的每节讲义都必须包含这四块,顺序固定:
- 本节要解决的问题 —— 为什么学它,不学会在哪里卡住
- 核心内容 —— 概念 + 步骤 + 至少一个能跟着做的具体例子
- 常见错误 —— 至少 2 条,每条写清"错在哪、为什么错、怎么改"
- 小结与承接 —— 3~5 条要点 + 一句引出下一节的话
第 3 块是"能用的课"与"搬运教程"的分水岭。没有常见错误的讲义,学员做错时还是不知道错在哪。
习题的三档分层
| 档位 | 能力指向 | 合适的题型 |
|---|---|---|
| 基础 | 能复述、能识别、能照着做 | 单选、判断 |
| 应用 | 能在新场景里用出来、能改参数 | 情境单选、简答 |
| 进阶 | 能判断取舍、能排错、能迁移到没讲过的情形 | 案例分析、纠错型判断 |
每档题数由 --per-tier 决定(默认 2,即每节 6 道)。脚本会逐档核对数量,
某档对不上就标红——"分层"名存实亡是分层习题最常见的偷懒方式。
每道题的解析必须说清三件事:为什么这个答案对、其他选项错在哪、这题考的是哪个知识点。
空解析直接被拦。
怎么用(命令行)
第 0 步:获取 API Key
到 api.a7w.cn 注册,创建一个 API Key(形如 sk-...)。
第 1 步:装依赖
零依赖。 不需要 pip install 任何东西,只要机器上有 Python 3.7+:
python3 --version
包里自带的 scripts/a7w.py 是零依赖客户端(只用 urllib / json / mimetypes),scripts/run.py 也只用标准库。
约定:
scripts/a7w.py是所有 Skill 包共用的零依赖客户端,我们靠
「包内副本 SHA256 == 规范版」批量校验各包的客户端有没有被意外改坏。
所以本包没有为了自己的业务去改它——课程生产线需要的东西全写在run.py里。
第 2 步:填 Key
# Linux / macOS
export A7W_API_KEY=sk-你的key
# Windows PowerShell
$env:A7W_API_KEY="sk-你的key"
也可以存进配置文件反复用(推荐):
python3 scripts/a7w.py login --key sk-你的key
第 3 步:先确认网关通(免费,不花点数)
python3 scripts/run.py models
这个命令打的是 GET https://api.a7w.cn/api/v1/models,会列出当前在架的模型。
课程生产线是纯文本任务,只看 type_code=text 的那一批:
python3 scripts/run.py models --type text
模型名会变,一定用
models子命令现查,别写死在脚本里。
但要注意:deepseek-chat这个别名实测可用(会路由到deepseek-flash),
而它不在/api/v1/models的返回列表里 —— 所以"列表里没有"不等于"不能用"。
第 4 步:先算钱(不出网,不花钱)
python3 scripts/run.py cost --chapters 4 --sections-per-chapter 2
输出会告诉你:几次调用、预估 token、预估金额,以及这个金额是怎么估出来的。
想设上限就用 --budget,超了退出码变 3。
第 5 步:出大纲
python3 scripts/run.py plan --topic "零基础短视频剪辑" --level zero \
--chapters 4 --sections-per-chapter 2 --json --out outline.json
先看不花钱的提示词:
python3 scripts/run.py plan --topic "零基础短视频剪辑" --dry-run
第 6 步:写讲义 / 出习题
# 写全部小节的讲义
python3 scripts/run.py lesson --plan outline.json --json --out lessons.json
# 出全部小节的习题(--lessons-file 让题目严格出自讲义)
python3 scripts/run.py quiz --plan outline.json --per-tier 2 --out quiz.md
第 7 步(推荐):一条命令跑完整套
# 先试算,确认预算
python3 scripts/run.py cost --chapters 4 --sections-per-chapter 2
# 跑完整套,带预算上限与输出目录
python3 scripts/run.py all --topic "零基础短视频剪辑" --level zero \
--chapters 4 --sections-per-chapter 2 --per-tier 2 \
--budget 5 --outdir ./course-out
产出目录长这样:
course-out/
├── outline.md / outline.json 大纲
├── lessons/1-1.md ... 每节讲义正文
├── quiz/1-1.json ... 每节习题(含答案与解析)
├── course.md 合并讲稿(大纲 + 讲义 + 习题),可直接发给讲师
├── AUDIT.md / audit.json 质量与合规自检报告
└── course-outline-state.json 断点文件
输出目录一定要指到包外(./course-out、%TEMP%\...)。Skill 包的上传白名单只收.md .py .txt .json .sh .js .yaml .yml .csv,包内塞图片会让上传 400。
中断了就原样重跑,不会重复扣费:
python3 scripts/run.py all --topic "零基础短视频剪辑" --outdir ./course-out
# [1/3] 大纲已完成,跳过(断点续跑,不再重复扣费)
# [2/3] 讲义 1-1 已完成,跳过
# ...
# 已用 0 次调用 · token prompt=0 completion=0 total=0
直接用 curl 调(不依赖本包脚本)
课程生产线底层就是一个标准的 OpenAI 兼容调用(下面这行的域名来自算力集市 api.a7w.cn):
curl -sS -X POST "https://api.a7w.cn/api/v1/chat/completions" \
-H "Authorization: Bearer $A7W_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "deepseek-chat",
"messages": [{"role": "user", "content": "给「零基础短视频剪辑」出 3 章大纲,只输出 JSON"}],
"temperature": 0.7,
"max_tokens": 4096,
"response_format": {"type": "json_object"}
}'
算力网关里成功响应不带
code字段——直接看choices[0].message.content。
带code == 1的那层信封({"code":1,"data":{...}})是给生成应用的,
本包两种形态都认,但不要改成用code == 0判成功。
参数说明
全局
| 参数 | 说明 |
|---|---|
--key | 临时指定 Key;优先级最高。别把它写进脚本或文档 |
--model | 模型名,默认 deepseek-chat(实测可用)。用 models 现查在架模型 |
--temperature | 采样温度,默认 0.7 |
--max-tokens | 最大输出 token,默认 8192;讲义一次几千字,别调太低 |
--budget | 成本上限(元,估算口径)。发起调用前就核,超了停止并返回退出码 3 |
--yuan-per-ktok | 单价(元/千 token),默认 0.02。这只是估算口径,不是账单 |
--json | 以 JSON 输出,写在子命令前面或后面都可以(plan --json --out 可喂给 lesson / quiz);JSON 模式下 stdout 只有一个完整 JSON,进度走 stderr |
--out <文件> | 把结果写到文件 |
--dry-run | 只打印将发送的提示词,不调模型、不花钱 |
--no-json-mode | 不要求上游返回 JSON 对象(个别模型不支持 response_format 时用) |
plan —— 出大纲
| 参数 | 说明 |
|---|---|
--topic | 必填。课程主题 |
--chapters | 章数,默认 4。脚本会拿实际解析出的章节数核对,对不上标红 |
--sections-per-chapter | 每章小节数,默认 2 |
--total-minutes | 全课时长目标(分钟),默认不约束 |
--level | zero(零基础,默认) / basic(入门) / advanced(进阶) |
--audience | 受众补充说明(谁在学、用在什么场景) |
--requirements | 必须覆盖的硬性要求,会原样给到模型 |
lesson —— 逐节写讲义
| 参数 | 说明 |
|---|---|
--plan | 必填。plan --json --out 产出的文件 |
--count | 最多写几节,默认全部 |
--level | 受众水平;给了 --plan 时以大纲里的 level 为准(大纲已定死讲练深度) |
--from-file | 闸门复检用:不调模型,直接拿一份返回 JSON 过闸门(见「排错」最后一节) |
quiz —— 逐节出习题
| 参数 | 说明 |
|---|---|
--plan | 必填。同上 |
--count | 最多出几节,默认全部 |
--per-tier | 每档难度出几道题,默认 2(三档共 6 道) |
--lessons-file | lesson --json --out 的结果;给了就让题目严格出自讲义 |
--from-file | 同 lesson |
all —— 串起来跑完整套(断点续跑)
| 参数 | 说明 |
|---|---|
--topic | 必填。课程主题 |
--outdir | 输出目录,默认 course-out;建议指到包外 |
--chapters / --sections-per-chapter / --total-minutes | 同 plan |
--count | 最多处理几节,默认全部 |
--per-tier | 同 quiz |
--force | 忽略断点全部重跑(会重复扣费,只在确实要重做时用) |
cost —— 只算钱
| 参数 | 说明 |
|---|---|
--chapters / --sections-per-chapter | 规模,默认 4 × 2 |
--lessons / --quizzes | 覆盖实际要跑几节;--quiz-off 表示不算习题的钱 |
--budget | 预算上限(元),超了退出码 3 |
models —— 列出在架模型
| 参数 | 说明 |
|---|---|
--type | 模型类型,默认 text;传 all 看全部 |
--json | 原始 JSON |
受众水平(--level)到底改了什么
| 水平 | 术语解释 | 讲练配比 | 单节时长建议 |
|---|---|---|---|
zero 零基础 | 每个术语第一次出现用一句大白话解释,多用生活化类比 | 概念 40% / 演示 45% / 练习 15% | 30~45 分钟 |
basic 入门 | 跳过名词解释,重点讲"为什么这么做"和常见错误 | 概念 25% / 演示 50% / 练习 25% | 30~60 分钟 |
advanced 进阶 | 不解释基础概念,直接讲原理、边界条件与取舍 | 概念 20% / 演示 40% / 练习 40% | 45~60 分钟 |
五道本地硬闸门
闸门都是拦截 + 标红 + stderr 汇总 + 退出码非 0,不是"提示一下"。
讲义会被印出来、录出来发给学员,缺陷出了这道门的代价是学员的时间与你的口碑。
| # | 闸门 | 拦什么 | 判据 |
|---|---|---|---|
| 1 | 合规 | 广告法违禁词 + 教育类效果承诺 | 本地正则表(BANNED_PATTERNS),模型自评不采信 |
| 2 | 占位符残留 | {} / [填空] / XXX / 待补充 | 四条正则,括号那条只认枚举词 |
| 3 | prompt_echo | 照抄提示词示例 | 去标点后相等 / Jaccard ≥ 0.75 / 覆盖度 ≥ 0.60 |
| 4 | 结构校验 | 大纲缺章节 / 缺小节 / 缺学习目标 / 目标是无信息量套话 | 逐层校验,缺项标红 |
| 5 | 成本上限 | 超 --budget | 发起调用前核一次,每节提交前再核一次 |
闸门一的两条实测修正(都是真机跑出来的)
① 教育类效果承诺按高风险单列一档。 知识付费最常见的违规不是"最"字,是效果承诺。
广告法明确禁止教育、培训广告对通过考试、获得学位学历或合格证书作保证性承诺,所以保过 / 包过 / 包学会 / 保证学会 / 提分保证 / 保证提分 / 保就业 / 包分配 全部高风险拦截。
② 普通中文里的「最」做了可枚举的豁免。 真机连跑 4 次讲义,1 次被拦,拦下的是:
做菜和剪辑最大的共同点是:先做减法,再做加法。
这是在讲一件常识,不是给商品贴最高级标签。所以加了一层上下文豁免:
"最 X"后面紧跟(允许夹一个「的」)`不同 / 区别 / 差异 / 共同 / 相同 / 相似 / 常见 /
容易 / 重要 / 关键 / 主要 / 先 / 后 / 基本 / 简单 / 难 / 麻烦 / 省事 / 常用 / 合适 /
适合 / 保险 / 稳妥` → 判为普通用法,放行。最好的课程 / 最强 / 最高级 / 最大优惠 仍然照拦。
这条豁免只对以「最」开头的命中生效,教育类效果承诺没有任何豁免。
同类修正还有一例:原来那条排他性规则写成裸的 唯一,而真机跑习题时模型在题干里写了
「判断一段画面是不是废片,唯一标准是画面够不够清晰稳定(答案:错)」——
这是把"唯一"当普通词用,属于必然误伤,已收紧为唯一(选择|指定|授权|官方|认证|品牌|推荐|渠道|合作)。
闸门三为什么是三条路径,而不是两条
这条闸门的教训来自爆款标题工坊的实测事故:提示词里写过的示例,哪怕明确标着
"这是错的写法",模型照样照抄——公众号那一轮最高分 89.0 的标题一字不差就是提示词里的示例,
最高分变成"抄标准答案",排序就废了。
本包的形态是:示例章节名被照抄 → 整份大纲变成"把示例换个主题词",
看起来完全正常,直到你发现它是模板填空题。
而本次真机实测又抓到这条闸门自己的一个设计缺陷:Jaccard 在两个长度差几十倍的对象
之间会被稀释。把一条 40 字的示例原样塞进一份 2400 字的讲义:
| 输入 | Jaccard | 覆盖度 | 只靠 Jaccard 会怎样 |
|---|---|---|---|
| 2400 字讲义里夹带 40 字示例 | 0.171 | 1.000 | 侥幸放行 |
| 真实讲义(实测 2483 / 2226 字) | 0.000 | ≤ 0.05 | 放行 |
所以加了第三条路径:示例二元组的覆盖度 ≥ 0.60。覆盖度只看"示例被抄了多少",
不看产出有多长,长文夹带照抄躲不过去。
阈值标定:正常产出与示例之间有 10 倍以上安全距离(真实章节名 vs 示例 Jaccard = 0.077)。
治本的一面在提示词侧:提示词里不许出现任何一份可直接复制的完整产出,
举例统一用跨主题示例(社区团购选品 / 机械制图停机点 / 架子鼓坐姿,与短视频剪辑明显不搭),
登记在 PROMPT_SAMPLES 常量里。万一以后有人把真实示例加回提示词,闸门会兜住。
闸门四:为什么 lesson / quiz 要再校验一遍
大纲是 JSON 文件,手工改坏它是最容易被忽略的失败入口;拿一份结构残缺的大纲去写讲义,
等于把错误放大到几十节。所以 lesson / quiz 在载入大纲时会重新跑一遍结构校验,
不合格直接返回退出码 3,一节讲义都不会写。
闸门五:成本口径是估算,不是账单
网关不公布逐模型的逐 token 单价,所以我们不编单价:默认口径是0.02 元 / 千 token(可用 --yuan-per-ktok 覆盖),文档与输出里都标成"估算"。
真实用量来自每次调用返回的 usage,all 跑完会把累计真实 token 打出来供你核对;usage 缺失时脚本按估值记账并明确标出"含 N 次估值非真实 usage",不假装是实测。
账单以 api.a7w.cn 控制台为准。
实测记录
以下都是本包上线前真实跑出来的数(模型 deepseek-chat,主题"零基础短视频剪辑"):
| 动作 | token(prompt / completion) | 耗时 | 结果 |
|---|---|---|---|
plan 4 章 × 2 节 | 715 / 1237(total 1952) | 7.1s | 结构校验 7 项全过,总时长 315 分钟 |
lesson 1 节 | 780 / 1700(total 2480) | 10.3s | 2172 字,闸门全绿 |
quiz 1 节 × 每档 2 题 | 827 / 1453(total 2280) | 9.2s | 6 题,分层完整,闸门全绿 |
all 1 章 2 节(5 次调用) | 6861 / 5234(total 12095) | 34.1s | 全部产出落盘,闸门全绿 |
all 原样重跑 | 0 / 0 | 0.1s | 全部跳过,不重复扣费 |
讲义字数实测分布在 1858 ~ 2210 字(连续 4 次),落在要求的 1500~3000 区间内;
4 次里有 1 次命中「最」类违禁词被拦下(就是上面那条已修正的误伤)。
排错
| 现象 / 报错 | 原因 | 怎么办 |
|---|---|---|
Missing or invalid relay API key(HTTP 401) | Key 无效、已过期或写错 | 重新到 https://api.a7w.cn/ 领取;确认没把 Bearer 重复写进环境变量 |
| 点数不足(HTTP 402) | 账号点数用完 | 到 https://api.a7w.cn/ 充值后重试 |
| 模型不存在(HTTP 404) | 模型名写错或已下架 | python3 scripts/run.py models --type text 现查在架模型名 |
| 模型返回的不是合法 JSON | 模型在 JSON 前后多吐了字符或解释 | 脚本已用 json.JSONDecoder.raw_decode 扫描第一个完整对象。仍失败就加 --no-json-mode 并换模型 |
| 大纲结构校验未通过(退出码 3) | 缺章节 / 缺小节 / 缺学习目标 / 目标是"了解 XX"这种套话 | 脚本会逐项打印哪一节缺什么。加大 --max-tokens 重跑,或直接手工补 outline.json(补完 lesson / quiz 会再校验一遍) |
| 讲义命中违禁词 / 字数越界(退出码 3) | 模型写了"最好"这类词,或字数不在 1500~3000 | 命中项会在 stderr 逐条列出。是误伤就改对应那句重跑;字数不够就让模型重写,脚本不会替你截断 |
| 习题命中"第 N 题没有解析"(退出码 3) | 模型漏写解析 | 加大 --per-tier 或减少节数减轻单次输出压力;也可以只对该节重跑 |
| 讲义字数普遍不足 1500 | 模型没按要求展开 | 加大 --max-tokens(不低于 8192);或把这一节拆成两节(改大纲的 minutes) |
预估 N 元超过 --budget | 超了成本上限 | 提高 --budget、减少节数,或先 cost 试算 |
| 重跑又扣了一次钱 | 大纲/讲义内容改了 → 断点 key 变了,被当成新的一项 | 这是设计如此(内容变了就该重做)。想省钱就别改,直接重跑即可跳过 |
--outdir 指到了 ./course-out 以外的地方还是报错 | 输出目录不可写 | 换路径;确认不在只读目录里跑 |
| Windows 下中文乱码 | 控制台代码页不是 UTF-8 | 脚本已把 stdout/stderr 切成 UTF-8;仍有问题就先 chcp 65001 或设 PYTHONIOENCODING=utf-8 |
| 想复核一份已有产出,但不想再花钱 | —— | 用 --from-file:lesson --plan outline.json --count 1 --from-file 某份返回.json 只跑闸门、不调模型 |
收集排错信息时请附上:完整命令、--dry-run 的输出、AUDIT.md 内容、原始报错文本。
不要在报错信息或截图里带上你的 API Key。
退出码(可直接用于流水线)
| 退出码 | 含义 |
|---|---|
0 | 全部干净,闸门全绿 |
3 | 被闸门拦下(违禁词 / 占位符 / 照抄示例 / 结构不合格 / 超预算) |
4 | 调用失败(网络 / 鉴权 / 点数 / 模型名) |
130 | 用户中断(Ctrl+C) |
--json 输出契约(给流水线与 agent 消费,只在 --json 下生效):
- 成功:结果对象里多一个
"ok": true;顶层是数组时包成{"ok": true, "data": [...]} - 失败:stdout 输出一个 JSON 信封,形如
{"ok": false, "exit": 3, "error": {"kind": "gate", "message": "…"}}(exit 就是本次真实退出码),kind 取 gate / usage / budget / call / interrupt / internal。internal 是没预料到的异常(代码 bug)的兜底:此时 stdout 给信封、
完整 traceback 原样打到 stderr、退出码固定 1 —— 报 bug,不藏 bug
—— 只有在本次还没吐过任何 JSON 结果时才补这个信封;已经吐过结果时
(例如跑到一半才发现比例不合格),ok 就写在那个结果里,退出码不变
- 人读文案照旧走 stderr;退出码语义一个都不变;非
--json模式输出与以前完全一致 --json写在子命令前面或后面都可以
3 与 4 分开是有意的:3 = "上游没问题,是被本地规则拦了",4 = "上游/网络有问题"。CI 里这两种要采取完全不同的动作。
文件结构
sanjianke-course-outline/
├── SKILL.md 本文件
├── README.md 给人看的说明
├── LICENSE.md MIT,署名三剪客
├── references/
│ ├── course-design-method.md 课程设计方法与判定口径
│ ├── quality-gates.md 五道闸门的判据与标定数据
│ └── compliance.md 合规红线(教育类专有条目)
└── scripts/
├── a7w.py api.a7w.cn 零依赖客户端(**逐字节等于规范版,本包不改它**)
└── run.py plan / lesson / quiz / all / cost / models
端点速查
本包全部能力都走同一个大模型端点(下面两行的域名都来自算力集市 api.a7w.cn):
| 用途 | 方法与路径 |
|---|---|
| 大纲 / 讲义 / 习题(算力集市 api.a7w.cn) | POST https://api.a7w.cn/api/v1/chat/completions |
| 在架模型清单(算力集市 api.a7w.cn) | GET https://api.a7w.cn/api/v1/models |
协议是 OpenAI 兼容:Authorization: Bearer <Key>,请求体用model / messages / temperature / max_tokens / response_format。
两条实测记下来的口径:
- 走
/chat/completions的成功响应不带code字段,直接读
choices[0].message.content;{"code":1,"data":{...}} 那层信封是给生成应用的。
deepseek-chat不在/api/v1/models的返回列表里,但实测可用(路由到
deepseek-flash)。所以"列表里没有"不等于"不能用"。
联系我们
- 技术微信:9872659 —— 加好友时说一下是从哪个 Skill 找过来的,直接给你配套的 API Key 与能跑的示例。
- 要算力 / 要 API Key:算力集市 · 注册领 API Key —— 一个 Key 调用全部 AI 算力,注册、充值、创建 Key 都在这里。
- 更多 AI 插件与接口:AI 插件市场。
相关链接
- 算力集市 api.a7w.cn(注册领 Key):https://api.a7w.cn/
- 课程设计方法与判定口径:
references/course-design-method.md - 五道闸门的判据与标定数据:
references/quality-gates.md - 合规红线(教育类专有条目):
references/compliance.md
免责声明:本包内置的违禁词表与判定口径是启发式自检工具,来自公开经验整理,
不构成法律意见,也不代表任何平台的官方审核标准。
课程内容的准确性、版权、以及宣发物料的合规责任由使用者承担;
医疗健康、金融投资、母婴、特殊化妆品等高风险类目必须人工复核后再使用。
讲义与习题由大模型生成,录用前请至少通读一遍——脚本能拦下违禁词、占位符、
照抄示例与结构残缺,拦不住事实性错误。