三剪客 · 课件配图与排版
## ⚠️ 先申请你自己的 API Key
本 Skill 不内嵌任何密钥,也不代付费用。 请到
算力集市 api.a7w.cn 注册并创建你自己的 API Key
(新用户有赠送点数,可以先免费试跑几次)。
拿到后填进环境变量A7W_API_KEY,或直接传给--key参数。
请勿使用他人提供的 Key —— 用量与费用都记在 Key 所属账号上。
能做什么
给一份讲义 / 大纲,一条链路产出一份能直接上课的课件:
outline → pages → images → render
分页方案 每页内容 按页配图 本地排版
页型/标题/ 成稿要点/ 真花钱·先报价· 逐页 PNG + notes.md
配图意图 讲稿备注 断点续跑 + 可选 deck.html(零成本)
(文本钱) (文本钱) (零网络,需要 PIL)
它替代的是备课里最后也最容易翻车的那一步:不是"写不出讲义",
而是"讲师站在投影前发现这一页讲不清"——一页塞了三个概念、图上写着错字、
要点长到看不清、备注没写所以讲师临场编。
| 子命令 | 干什么 | 花钱吗 |
|---|---|---|
outline | 读讲义 → 分页方案(页型 / 标题 / 粗要点 / 配图意图) | 只花文本钱 |
pages | 把骨架展开成成稿(1~6 条要点 + 80~400 字讲稿备注) | 只花文本钱 |
images | 按页出配图(画面里不许有文字) | 真花钱,实测 24 点/张 = 0.24 元(1K),先报价 |
render | 本地排版成逐页 PNG + notes.md + deck.html | 零成本、零网络,需要 PIL |
all | 串起全流程,断点续跑 | 按阶段花钱 |
cost | 只算钱,一次调用都不发 | 零成本 |
models | 列出在架模型与应用 | 零成本 |
| 你最关心 | 答案 |
|---|---|
| 多少钱 | 出图实测 24 点/张(1K)= 0.24 元/张,1 元 = 100 点;images 跑之前先把总价打出来 |
| 要多久 | 文本:7 页分页方案 5.8 秒、7 页成稿 11.9 秒(3 批);出图单张 5~40 秒;本地排版 7 页 0.7 秒 |
| 要装什么 | 零第三方依赖;render 需要 pillow,没有就明确报降级(exit=2),不假装成功 |
| 图上的字会不会糊 | 不会:出图提示词里不许出现任何文字,页上的字全部由本地排版压上去 |
| 一页讲不完怎么办 | 拦截,并报出实际像素与可用像素;绝不静默截断、也不自动缩字号 |
| 中断了怎么办 | 断点续跑:已完成的跳过、已提交的用 task_id 续查(不重复扣费) |
| 改了页型要重出图吗 | 不用。文字版式与出图是两条独立的断点:只改版式就只重渲,图不动(实测只重渲 3/7 页) |
| 会给我 PPTX 吗 | 不给。python-pptx 不是标准库、本包不依赖它;给的是逐页 PNG + deck.html,HTML 可直接打印或导进 PPT |
| 输出放哪 | --outdir 必须在包外;指到包内直接 exit=2(包内不许有图片) |
它和同族 L2 各包不是一回事(改代码前先读这张表)
| 输入 | 产出 | 最小单位 | 有版式引擎吗 | |
|---|---|---|---|---|
sanjianke-course-outline | 一个主题 | 大纲 / 讲义 / 习题(纯文本三件套) | 节(1500~3000 字散文) | 无 |
sanjianke-image-factory | 一篇文章稿 | 文章各段的配图 | 图 | 无 |
sanjianke-cover-factory | 一批标题 | 同一标题 × N 平台的封面 | 封面(一张图 + 一行大字) | 有,但单张 |
| 本包 | 一份讲义 | 一份课件(逐页 PNG + 备注) | 页(页型 + 标题 + 要点 + 备注 + 配图意图) | 有,多页(页序 / 版心 / 溢出判定) |
四个包里只有本包有「页」这个数据结构,也只有本包会问"这一页放不放得下"
并用真实字体排版后给出像素级的结论。
与「给讲义配图」的区别:配图只是本链条里的一步,而且产出的图不含任何文字
——字全部由本地排版压上去。同族的image-factory是把文字交给模型"画"进画面,
本包刻意反过来做,因为出图模型画中文大字基本是错的(缺笔画、错字、糊成一团)。
四种页型与各自的版式
| 页型 | 用途 | 版式 |
|---|---|---|
cover 封页 | 第一页 | 配图整幅铺底 + 压暗层 + 标题居中(92px)+ 要点居中成块 |
section 章节页 | 章节切换 | 同封页,标题略小(71px) |
content 内容页 | 绝大多数页 | 左文右图(文字占左 50.5%,图占右侧);无图时文字限宽 70% |
summary 小结页 | 最后一页 | 同封页,居中 |
无图版式是设计内的一等公民:--every 2 表示每 2 页配一张图,
没有配图的那几页用「文字限宽版式」渲染(不是留白凑数、也不是复用上一页的图)。
实测 7 页 / --every 3 → 3 张图,其余 4 页按无图版式渲染。
三个配色主题
| 主题 | 观感 | 适合 |
|---|---|---|
ink(默认) | 浅底深字,墨白 | 投影、打印、讲义 |
night | 深底浅字 | 录屏、直播间 |
warm | 米底暖字 | 知识付费课程 |
怎么用(命令行)
第 0 步:获取 API Key
到 api.a7w.cn 注册,创建一个 API Key(形如 sk-...)。
第 1 步:装依赖
零第三方依赖。 只要机器上有 Python 3.7+:
python3 --version
scripts/a7w.py 是零依赖客户端(只用 urllib / json / mimetypes),scripts/imgprobe.py 是图片头探针(只用 struct / zlib),run.py 同样只用标准库。
唯一的例外是 render:本地排版需要 pillow(不是标准库)。
pip install pillow # 只有 render 需要
没有 pillow 时 render 明确报错降级 exit=2 并说明原因,绝不静默产出一份
没有版式的"课件"。装上之后原样重跑同一条命令即可(断点续跑不会重复扣钱)。
render还需要一个能渲染中文的系统字体。 脚本会按顺序找msyhbd.ttc/msyh.ttc/simhei.ttf/Deng.ttf/simsun.ttc(Windows)、PingFang.ttc(macOS)、NotoSansCJK/wqy-zenhei(Linux)。
找不到就报降级(exit=2),用--font <字体文件路径>指定一个。
包内不打包字体——字体有授权问题,包内也不许有二进制资源。
约定:
scripts/a7w.py是所有 Skill 包共用的零依赖客户端,我们靠
「包内副本 SHA256 == 规范版」批量校验各包的客户端有没有被意外改坏。
所以本包没有为了自己的业务去改它——需要读图片像素就独立出imgprobe.py,
需要应用专属接口就写在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
python3 scripts/run.py models --type text # 只看文本模型
models 会打两个端点:GET https://api.a7w.cn/api/v1/apps(在架应用)
与 GET https://api.a7w.cn/api/v1/models(在架模型)。
模型名会变,别写死在脚本里。 出图模型的可选值也可以现查:
python3 scripts/a7w.py schema nano_banana
第 4 步:先算钱(不出网,不花钱)
python3 scripts/run.py cost --pages 12 --every 2
输出会告诉你:几次调用、出图几张、预估 token 与金额,以及这个金额是怎么估出来的。
想设上限就加 --budget(单位是元),超了退出码变 3。
第 5 步:出分页方案(只花文本钱)
python3 scripts/run.py outline 讲义.md --pages 12 --level basic \
--topic "零基础短视频剪辑" --outdir D:/slides/ep01
先看不花钱的提示词:
python3 scripts/run.py outline 讲义.md --pages 12 --dry-run
产出 D:/slides/ep01/deck.json(机器读)与 deck.md(人读)。
这一步已经把 页型 / 页标题 / 粗要点 / 配图意图 定下来了。--pages 是目标页数,脚本会拿实际解析出的页数核对,差超过 1 页就标红拦下。
第 6 步:展开成成稿(只花文本钱)
python3 scripts/run.py pages --outdir D:/slides/ep01
默认每 3 页一批调一次模型,批级断点续跑。
成稿必须满足:每页 1~6 条要点、每条 ≤ 40 字、每页备注 80~400 字。
第 7 步:出配图(真花钱,先报价)
# 先报价:不加 --yes 也不加 --budget,在报价阶段就停
python3 scripts/run.py images --outdir D:/slides/ep01 --every 2
# 确认了再出(--budget 本身也是"确认")
python3 scripts/run.py images --outdir D:/slides/ep01 --every 2 --yes
python3 scripts/run.py images --outdir D:/slides/ep01 --every 2 --budget 3
⚠️
--budget本身就是确认。 这条口径与同族一致:need_yes = 不加 --yes 且 没给 --budget。也就是说给了--budget就会真的出图,
花到上限为止。只想看看价钱,请两个都不加,或用--dry-run。
第 8 步:本地排版(零成本、零网络)
python3 scripts/run.py render --outdir D:/slides/ep01
python3 scripts/run.py render --outdir D:/slides/ep01 --theme night --no-html
产出目录长这样:
D:/slides/ep01/
├── deck.json 分页方案 + 成稿(含不可变的 skeleton_pages)
├── deck.md 人读的分页稿
├── images/p01.png ... 配图(**无字**,比例已复核)
├── slides/slide-01.png ... **成片课件**(逐页 PNG,1920x1080)
├── slides/deck.html 可选:自包含 HTML,可直接打印 / 导进 PPT
├── notes.md 讲稿备注单独成册(讲课的人只需要这一份)
├── AUDIT.md 自检报告(逐页像素 / 字节 / 比例复核 / 告警)
└── slide-kit-state.json 断点文件(重跑不重复扣费)
输出目录一定要指到包外(D:/slides/...、%TEMP%\...)。Skill 包的上传白名单只收.md .py .txt .json .sh .js .yaml .yml .csv,包内塞图片会让上传 400。
一条命令跑完:
python3 scripts/run.py all 讲义.md --pages 12 --outdir D:/slides/ep01 --budget 5
中断了就原样重跑,不会重复扣费:
python3 scripts/run.py pages --outdir D:/slides/ep01
# [1/3] 已有成稿,跳过(断点续跑,不再重复扣费)
# ...
# 页内容已写出:…(7 页;0 次调用,跳过 3 批)
python3 scripts/run.py render --outdir D:/slides/ep01
# [1/7] #p01 已渲染,跳过(断点续跑)
# 课件已排版完成:…(7 页,跳过 7 页)
直接用 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": "把这份讲义拆成 6 页课件方案,只输出 JSON"}],
"temperature": 0.7,
"max_tokens": 8192,
"response_format": {"type": "json_object"}
}'
算力网关里成功响应不带
code字段——直接看choices[0].message.content。
带code == 1的那层信封是给生成应用的,本包两种形态都认,
但不要改成用code == 0判成功。
参数说明
全局
| 参数 | 说明 |
|---|---|
--key | 临时指定 Key;优先级最高。别把它写进脚本或文档 |
--json | 以 JSON 输出,写在子命令前面或后面都可以;JSON 模式下 stdout 只有一个完整 JSON,进度走 stderr |
--budget | 成本上限(元;出图按实测 24 点/张 = 0.24 元换算),超了退出码 3 |
--yuan-per-ktok | 文本单价(元/千 token),默认 0.02。这只是估算口径,不是账单 |
--model | 文本模型名,默认 deepseek-chat(实测可用)。用 models 现查 |
--temperature / --max-tokens | 采样温度(默认 0.7)/ 最大输出 token(默认 8192) |
--no-json-mode | 不要求上游返回 JSON 对象(个别模型不支持 response_format 时用) |
outline —— 读讲义 → 分页方案
| 参数 | 说明 |
|---|---|
<讲义文件> | 位置参数。Markdown / 纯文本讲义 |
--text | 直接给正文(与位置参数二选一) |
--pages | 目标页数,默认 12。脚本核对实际页数,差超过 1 页就拦 |
--level | zero / basic(默认) / advanced,决定术语密度与讲练配比 |
--audience | 受众补充说明(谁在学、用在什么场景) |
--topic | 课程主题(兜底标题用) |
--outdir | 产出目录,默认 slide-out;建议指到包外 |
--out | 额外把分页方案 JSON 写一份到指定路径 |
--from-file | 零成本闸门自检:直接拿一份返回 JSON 过闸门,不调模型 |
--dry-run | 只打印将发送的提示词,不调模型 |
--embed | --json 时把完整 deck 也嵌进输出 |
讲义超过 24000 字会直接报错(
exit=2),不会静默截断。
截掉的内容你永远不知道少了什么,所以宁可让你拆成两半分开跑。
pages —— 展开成成稿
| 参数 | 说明 |
|---|---|
--outdir / --deck | 产出目录 / 分页方案文件(默认 <outdir>/deck.json) |
--only / --count | 只处理这些页 / 最多处理几页 |
--style | 讲课风格补充说明 |
--strict-notes | 缺讲稿备注也算闸门失败(默认只告警) |
--from-file | 零成本闸门自检:拿一份返回 JSON 过闸门,不调模型 |
--force | 忽略断点全部重跑(会重复扣费) |
images —— 按页出配图
| 参数 | 说明 |
|---|---|
--every | 每 N 页配一张图(1=每页一图,2=数页一图),默认 1 |
--resolution | 1K(默认) / 2K / 4K。只有 1K 有实测价,2K/4K 拒绝估算 |
--ratio | 出图比例,默认按分页方案(16:9) |
--snap | 出图后按请求比例居中裁准 |
--ratio-tolerance | 比例容差,默认 0.03(实测最大偏差 2.9%) |
--points-per-image | 覆盖单张单价(点) |
--poll-timeout | 单张出图轮询上限(秒),默认 600 |
--yes | 确认真花钱的操作(不加它、也不给 --budget 时只报价) |
--dry-run | 只报价,不花钱 |
--only / --count | 只出这些页的图 / 最多出几张 |
--allow-prompt-hits | 放行出图提示词的闸门命中(页面内容闸门永远不放行) |
render —— 本地排版
| 参数 | 说明 |
|---|---|
--theme | ink(默认) / night / warm |
--font | 中文字体文件路径(默认从系统字体里找) |
--no-html | 不导出 deck.html |
--strict-notes | 缺讲稿备注也算闸门失败 |
--ratio-tolerance | 配图比例容差,默认 0.03 |
--force | 忽略断点全部重渲 |
cost —— 只算钱
--pages / --every / --images(直接指定张数)/ --no-images / --no-text /--no-outline / --no-pages / --resolution / --points-per-image / --budget。
断点 key 里到底有什么(为什么改了东西一定会重做)
| key | 含哪些维度 | 后果 |
|---|---|---|
batch:…(pages) | 不可变骨架的全文摘要 + 模型 + 提示词版本 | 骨架没变 → 重跑 0 次调用、0 元 |
img:…(images) | 页 id + 提示词全文摘要 + 比例 + resolution + 模型 | 改文案或改档位 → 重出重扣;只改版式 → 图不动 |
render:…(render) | 页 id + 页内容摘要 + 页型 + 配图(路径+大小+时间)+ 版式版本 / 主题 / 字体 / 画布 / 页码 | 改主题或版式 → 重渲;图与文本都没改 → 跳过 |
三个坑都踩过、都堵住了:
- 内容截断:用
text[:N]当摘要 → 只改后半句时 key 不变,静默复用旧产物。所以摘要一律取全文。 resolution不入 key:换了档位却复用 1K 的旧图。现在它进 key。- 死参数:命令行加了
--theme却没进 key → 改了参数产物一动不动。现在主题 / 字体 / 版式版本 / 页码全在 key 里。
还有第四个,它比前三个都隐蔽,是上线前真机跑出来的:
key 的某一维不同、产物路径却相同 → 断点命中,但磁盘上是别人的产物。
复现路径只有三步:render --theme ink→render --theme night→render --theme ink。
两个主题写同一个文件名(slides/slide-01.png)。
第三步时 ink 的旧记录所有维度都对得上 → 直接跳过 →
磁盘上留着的却是 night 的图,而命令还在报「已渲染,跳过(断点续跑)」。
也就是说:断点 key 全中、命令说"跳过",产物却是别人的 —— 命令在说谎。
处理口径:断点命中后再核一次产物文件本身的身份(字节数 + mtime,
渲染与出图两处都做)。对不上就重做并说明原因:
```
⚠ 渲染断点 记录说产物是 1204927 字节 / mtime 1790656252,磁盘上却是 1202520 / 1790656256
→ 产物被别人覆盖过,重做
```
升级前的老记录没有产物身份,一律当作"说不清来历"重做 ——
本地渲染是零成本的,宁可多渲一次,也不交一份说不清来历的产物。
凡是「key 的某一维不同、但产物路径相同」的参数都会踩这个坑
(主题 /resolution/ 比例 / 字体…),这在本包是结构性的,不是个例。
改了画法必须把
LAYOUT_VERSION+1(源码里有醒目注释),否则断点会把改动前的
旧 slide 当"已渲染"复用——你会以为改了、其实图还是旧的。
八道本地硬闸门
闸门都是拦截 + 标红 + stderr 汇总 + 退出码非 0,不是"提示一下"。
课件是要一页一页投在墙上的,缺陷出了这道门的代价是学员的时间与你的口碑。
| # | 闸门 | 拦什么 | 判据 |
|---|---|---|---|
| 1 | 合规 | 广告法违禁词 + 教育类效果承诺 | 本地正则表(BANNED_PATTERNS),模型自评不采信 |
| 2 | 占位符残留 | {} / [待填] / XXX / (此处省略) / TODO | 六条正则,括号那条只认枚举词 |
| 3 | prompt_echo | 照抄提示词示例 | 去标点后相等 / Jaccard ≥ 0.75 / 覆盖度 ≥ 0.60 |
| 4 | 出图比例真伪 | 真实像素 ≠ 请求比例 | 读文件头真实像素,容差 3%(地板 0.25%),--snap 裁准 |
| 5 | 每页内容完整性 | 空页 / 零页 / 缺标题 / 要点超长 | 页数 > 0;每页标题 ≤ 30 字;每页 1~6 条要点,每条 ≤ 48 字 |
| 6 | 文字溢出 | 版心放不下 | 真实字体排版后量像素;超了报出实际像素与可用像素 |
| 7 | 成本上限 | 超 --budget | 出图前核;2K/4K 拒绝估算(无实测价) |
| 8 | 产出不许进包 | --outdir 在包内 | exit=2(包内白名单只收文本) |
闸门一里两条实测修正(都是真机跑出来的)
① 教育类效果承诺按高风险单列一档。 知识付费最常见的违规不是"最"字,是效果承诺。
广告法明确禁止教育、培训广告对通过考试、获得学位学历或合格证书作保证性承诺,所以保过 / 包过 / 包学会 / 保证提分 / 保就业 / 包分配 / 一次通过 全部高风险拦截,
这一档没有任何豁免。
② 裸的「特效」被真机打成误伤,已收紧。 本包上线前跑真机,pages 被拦下两次:
| 命中文本 | 判成了什么 | 实际是什么 |
|---|---|---|
| 「很多人以为剪辑是学特效、学转场」 | 医疗功效宣称 | VFX,影视行业的常用词 |
| 「一上手就拖转场特效」 | 医疗功效宣称 | VFX |
处理口径与同族修 唯一 那次一模一样:把裸词收紧成可枚举的搭配。
医疗意义上的「特效」在中文里几乎总是带后缀,所以改成特效(药|疗法|配方|偏方|治疗|作用|成分|功效),裸的「特效」不再命中。
③ 普通中文里的「最」做了可枚举的豁免。 真机连跑讲义时拦下过
「做菜和剪辑最大的共同点是:先做减法,再做加法」——这是在讲常识,不是给商品贴标签。
所以加了一层上下文豁免:最X 后面紧跟(允许夹一个「的」)
`不同 / 区别 / 差异 / 共同 / 相同 / 相似 / 常见 / 容易 / 重要 / 关键 / 主要 / 先 / 后 /
基本 / 简单 / 难 / 麻烦 / 省事 / 常用 / 合适 / 适合 / 保险 / 稳妥` → 判为普通用法,放行。最好的课程 / 最强 / 最高级 / 最大优惠 仍然照拦。
⚠️ 句首不许误豁免——"最大的区别是……"这种句首写法经常正是标题式最高级宣称,
而课件的页标题几乎全在句首,所以这条对本包比对同族更关键。
已知的保守行为:加微信 / 私信我 / vx 这类站外导流词照拦,哪怕课件主题就是
教「私域运营怎么引导加微信」。这是刻意的(平台规则口径),靠改文案解决,不要改闸门。
闸门三为什么是三条路径,而不是两条
这条闸门的教训来自爆款标题工坊的实测事故:提示词里写过的示例,哪怕明确标着
"这是错的写法",模型照样照抄——公众号那一轮最高分 89.0 的标题一字不差就是提示词里的示例。
本包的形态是:示例页标题 / 示例配图意图被照抄 → 整份课件变成"把示例换个主题词",
看起来完全正常,直到你发现它是模板填空题。而课件是要拿去上课的。
Jaccard 在两个长度差几十倍的对象之间会被稀释。 同族实测:把一条 40 字的示例原样
塞进 2400 字的产出,Jaccard 只有 0.171(旧判据放行 ❌),而覆盖度是 1.000
(新判据拦下 ✓)。所以加了第三条路径:示例二元组的覆盖度 ≥ 0.60。
覆盖度只看"示例被抄了多少",不看产出有多长。
阈值标定:逐字照抄 1.000 / 只改标点 1.000 / 少两个字 0.840 / 加一个尾巴 0.857 —— 全部拦;
而真实业务产出只有 0.042 / 0.000 —— 放行,17 倍以上安全距离。
长度守卫是相对的:max(6, len(示例)//2),短串不比(二元组集合太小、指标虚高)。
治本的一面在提示词侧:提示词里不许出现任何一份可直接复制的完整产出,
举例统一用跨主题示例(社区团购选品 / 机械制图停机点 / 架子鼓坐姿,
与知识付费、企业内训的常见主题明显不搭),登记在 PROMPT_SAMPLES 常量里。
实测确认:模板没被照抄。真机跑出来的 7 页标题、要点、备注、配图意图
与 5 条示例的最大覆盖率是 0.000(0 命中)。
闸门四:尺寸按 32 对齐,5/10 种比例给不出精确值
实测到的上游特性(必须知道,否则闸门天天误报):上游先定总像素、再把每边向下取整到
32 的倍数。所以:
| 请求 | 1K 真实像素 | 实际比例 | 偏差 |
|---|---|---|---|
1:1 | 1024x1024 | 1.0000 | 0% |
16:9 | 1344x768 | 1.7500 | 1.56% |
9:16 | 768x1344 | 0.5714 | 1.6% |
3:4 | 864x1184 | 0.7297 | 2.7% |
4:5 | 896x1152 | 0.7778 | 2.8% |
21:9 | 1536x672 | 2.2857 | 2.0% |
这不是网关 bug,是扩散模型按 32 对齐的常规做法。处理方式三条一起用:
a) 默认容差 3%,容差内不算"假",但明确打印真实像素与偏差;
b) 超容差 → 标红 + 退出码 3;
c) --snap 按请求比例精确裁掉多余像素。
本包真机实测:请求
16:9拿到 1344x768(偏差 1.56%),落在容差内 → 放行并如实报出;
拿一个 1024x1024 塞进去 → 偏差 43.75% → 拦下。
闸门六:为什么不做静默截断,也不自动缩字号
事故来源(同族刚翻过的车):sanjianke-xhs-note-factory 1.0.4 及以前写的是cover_text[:20] —— 静默截断:用户改了文案、付了钱重出图,只有第 21 字之后被砍掉,
图看起来一模一样,用户以为"我的改动生效了"。1.0.5 起改成超限直接拦下并报出实际长度。
本包从一开始就照修好的口径做,并且连"静默缩字号"也不做:
放了十几年投影的经验是——缩到看不清比缺一句话更糟。所以只报数字,让你改内容。
一条实测出来的版式事实:闸门六真正会咬住的是有图版式(文本区 865px 宽,
≈19 字/行,6 条 × 40 字就断成 18 行、挤爆 911px 的版心)。
无图版式宽得多,同一份内容装得下。早期把无图版式放宽到画布 82% 时,
闸门六在无图版式下几乎永远不可能触发——一个打不响的闸门等于没有闸门,
所以收到了 70%。
实测记录
以下都是本包上线前在真机上跑出来的数(不编,缺就写缺):
| 动作 | 用量 / 结果 | 耗时 |
|---|---|---|
schema nano_banana(现查) | 7 个入参:model / action / prompt / image_urls / resolution / aspect_ratio / callback_url | <1s |
outline 讲义 → 7 页 | usage = prompt_tokens 1186 / completion_tokens 780 / total_tokens 1966;要求 6 页、实际 7 页(±1 容差内放行) | 5.8s |
pages 7 页(3 批) | 全部通过闸门;成稿要点 1~6 条/页、备注 80~400 字 | 11.9s |
pages 原样重跑 | 0 次调用、0 元(批级断点全跳过) | 0.1s |
images --every 3 → 3 张 | points_cost = 24.0 点/张,合计 72.00 点 = 0.72 元 | 每张 5~20s |
| 出图真实像素 | 1344x768(请求 16:9 = 1.7778,实际 1.7500,偏差 1.56%,容差 3%) | — |
render 7 页 | 逐页 PNG 1920x1080,共 3.8 MB;有图页 780~1052 KB、无图页 73~86 KB | 0.7s |
render 原样重跑 | 7 页全跳过(0.1s);只改 3 页的页型 → 精确重渲 3/7 页 | 0.2s |
| 闸门自检 | 32 个用例全过(8 道闸门各喂坏数据 + 用法错误 + --from-file 零成本路径) | <60s |
--json 契约 | 成功 / 失败 × 前后两种位置 + internal 信封,全部 json.loads 通过、stdout 只有一个 JSON | <20s |
出图实测 1K = 24 点/张(1 元 = 100 点)。2K / 4K 没有实测过,脚本拒绝估算
(exit=3),除非你自己用 --points-per-image 给单价。
文本金额一律是估算口径(默认 0.02 元/千 token):网关不公布文本模型单价
(pricing 表不含文本模型、models 无价格字段、usage 无 points_cost),
所以账单以 api.a7w.cn 控制台为准。
排错
| 现象 / 报错 | 原因 | 怎么办 |
|---|---|---|
没有 PIL:本地排版成逐页 PNG 需要 PIL(exit=2) | 没装 pillow | pip install pillow,然后原样重跑(断点续跑不重复扣钱) |
系统里找不到可用的中文字体(exit=2) | 系统没有中文字体 | --font <字体文件路径> 指定一个 |
输出目录 … 在 Skill 包内(exit=2) | --outdir 指到包内了 | 换到包外,例如 D:/slides/x、%TEMP%\slides |
讲义原文 … 超过上限 …(exit=2) | 讲义 > 24000 字 | 拆成两半分开跑(故意不截断) |
page_count 被拦(exit=3) | 模型出的页数与 --pages 差超过 1 页 | 改 --pages 重跑,或手工调整 deck.json 的页 |
no_image_intent 被拦(exit=3) | 某页没有配图意图 | 让模型重跑该批,或手工在 deck.json 补 image_intent |
empty_page 被拦(exit=3) | 某页一条要点都没有 | 脚本不会拿粗要点兜底(那会掩盖失败)。补内容后重跑 |
bullet_too_long 被拦(exit=3) | 单条要点 > 48 字 | 拆成两条或压缩(不截断) |
text_overflow 被拦(exit=3) | 标题 + 要点排下来超过版心 | 报里给了实际像素与可用像素,减内容,别改闸门 |
ratio_fake 被拦(exit=3) | 真实像素与请求比例差 > 3% | images --snap 重跑该页;或提高 --ratio-tolerance(不推荐) |
命中违禁词 / 占位符 / 照抄示例(exit=3) | 文本里有违规内容或模型照抄了示例 | 命中项逐条打在 stderr。改文案重跑,或 --from-file 零成本复核 |
2K 档没有实测单价,拒绝凭猜估算(exit=3) | 2K/4K 没实测价 | 先用 1K,或用 --points-per-image 自己给单价 |
预估 … 超过预算上限(exit=3) | 超了 --budget | 提高预算、减少页数,或先 cost 试算 |
| 重跑又扣了一次钱 | 断点 key 的某一维变了(文案改了 / 换了 resolution / 换了模型) | 设计如此(内容变了就该重做)。只改版式不会重出图 |
| 页码或配色改了但图没变 | 改了画法却没 bump LAYOUT_VERSION | 把 LAYOUT_VERSION +1(源码里有醒目注释) |
| 模型返回的不是合法 JSON | 模型在 JSON 前后多吐了字符 | 脚本用 json.JSONDecoder.raw_decode 扫第一个完整对象。仍失败就 --no-json-mode |
任务未完成(timeout)(exit=4) | 出图卡在 processing | task_id 已记进断点文件,重跑会续查而不是重新提交(不重复扣费);也可调大 --poll-timeout |
| Windows 下中文乱码 | 控制台代码页不是 UTF-8 | 脚本已把 stdout/stderr 切成 UTF-8;仍有问题先 chcp 65001 或设 PYTHONIOENCODING=utf-8 |
| 想复核一份已有产出,但不想再花钱 | —— | outline --from-file 某份返回.json / pages --from-file … 只跑闸门、不调模型 |
收集排错信息时请附上:完整命令、--dry-run 的输出、AUDIT.md 内容、原始报错文本。
不要在报错信息或截图里带上你的 API Key。
退出码(可直接用于流水线)
| 退出码 | 含义 |
|---|---|
0 | 全部干净,闸门全绿 |
2 | 用法错误(参数错 / 文件找不到 / 没装 PIL / 没字体 / --outdir 在包内) |
3 | 被闸门拦下(违禁词 / 占位符 / 照抄示例 / 比例不符 / 空页 / 溢出 / 超预算 / 拒绝估算 / 页数为 0) |
4 | 调用失败(网络 / 鉴权 / 点数 / 模型名 / 任务未完成) |
130 | 用户中断(Ctrl+C) |
1 | 没预料到的异常(代码 bug):--json 下给 internal 信封 + 完整 traceback 到 stderr |
2 / 3 / 4 分开是有意的:2 = "你命令用错了",3 = "上游没问题,是被本地规则拦了",4 = "上游 / 网络有问题"。CI 里这三种要采取完全不同的动作。
--json 输出契约(给流水线与 agent 消费,只在 --json 下生效):
- 成功:结果对象里多一个
"ok": true;顶层是数组时包成{"ok": true, "data": [...]} - 失败有两种合法形态,消费方要都处理:
- 信封:
{"ok": false, "exit": 3, "error": {"kind": "…", "message": "…"}},
exit 就是本次真实退出码。用在"本次还没吐过任何结果"时
(参数错 / 缺文件 / 预算闸门在报价前拦下 / 拒绝估算)。
- 结果:
{"ok": false, "stage": "gate", "blocked": [...]}
—— 用在"命令已经跑完、产出也给了,只是闸门判定不合格"时。
此时绝不再补信封,否则 stdout 上会有两个 JSON 文档,json.loads 直接 Extra data: line N column 1。
kind取usage/gate/budget/call/interrupt/internalinternal是没预料到的异常(代码 bug)的兜底:stdout 给信封、
完整 traceback 原样打到 stderr、退出码固定 1 —— 报 bug,不藏 bug
- 人读文案照旧走 stderr;退出码语义一个都不变
--json写在子命令前面或后面都可以
文件结构
sanjianke-slide-kit/
├── SKILL.md 本文件
├── README.md 给人看的说明
├── LICENSE.md MIT,署名三剪客
├── references/
│ ├── slide-design-method.md 课件设计方法论(分页 / 要点 / 备注怎么写)
│ ├── layout-specs.md 版式与规格(画布 / 版心 / 字号 / 上限自洽性)
│ └── cost-and-troubleshooting.md 实测单价、报价口径与排错手册
└── scripts/
├── a7w.py api.a7w.cn 零依赖客户端(**逐字节等于规范版,本包不改它**)
├── imgprobe.py 图片头探针(读真实像素,只读)
└── run.py outline / pages / images / render / all / cost / models
端点速查
本包全部能力都走 api.a7w.cn(下面几行的域名都来自算力集市 api.a7w.cn):
| 用途 | 方法与路径 |
|---|---|
| 分页方案 / 每页内容(文本) | POST https://api.a7w.cn/api/v1/chat/completions |
| 在架模型清单 | GET https://api.a7w.cn/api/v1/models |
| 在架生成应用 | GET https://api.a7w.cn/api/v1/apps |
| 出配图(异步提交) | POST https://api.a7w.cn/api/v1/apps/nano_banana/submit |
| 出图任务轮询 | GET https://api.a7w.cn/api/v1/tasks/<task_id> |
协议是 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)。所以"列表里没有"不等于"不能用"。
- 异步任务的
status在data顶层,不在data.result里(平台文档写错了)。
照文档写会永远读不到状态、一路轮询到超时。
- 请求体字段必须现查:
python3 scripts/a7w.py schema nano_banana。
本包用到的 7 个字段全部来自现查结果,不凭记忆。
联系我们
- 技术微信:9872659 —— 加好友时说一下是从哪个 Skill 找过来的,直接给你配套的 API Key 与能跑的示例。
- 要算力 / 要 API Key:算力集市 · 注册领 API Key —— 一个 Key 调用全部 AI 算力,注册、充值、创建 Key 都在这里。
- 更多 AI 插件与接口:AI 插件市场。
相关链接
- 算力集市 api.a7w.cn(注册领 Key):https://api.a7w.cn/
- 课件设计方法论:
references/slide-design-method.md - 版式与规格:
references/layout-specs.md - 成本与排错:
references/cost-and-troubleshooting.md
免责声明:本包内置的违禁词表与判定口径是启发式自检工具,来自公开经验整理,
不构成法律意见,也不代表任何平台的官方审核标准。
课件内容的准确性、版权、以及宣发物料的合规责任由使用者承担;
医疗健康、金融投资、K12、母婴、特殊化妆品等高风险类目必须人工复核后再使用。
分页方案、要点与讲稿备注由大模型生成,上课前请至少通读一遍——
脚本能拦下违禁词、占位符、照抄示例、空页、文字溢出与比例不符,
拦不住事实性错误,也拦不住"这一页的讲法不合适"。