Make Knowledge Cards

把用户提供的文章提炼成 5～8 张知识卡片，并在项目根目录下生成一个以核心关键词命名的目录，把每张卡片保存为一张 PNG 图片。目标是帮助读者用最少的卡片记住原文真正重要的知识，而不是复述全文。

输入与边界

支持

用户直接粘贴的文章正文。
本地 Markdown 或 TXT 文件路径。

读取文件

使用当前环境可用的文件读取工具读取完整内容，不要凭文件名猜测内容。
文件不存在、为空或无法读取时，说明原因并请用户重新提供，不要继续生成。

不支持

网页抓取、PDF、Anki 导出。
遇到 URL 或 PDF 时，用一句话说明暂不支持，并请用户粘贴正文或提供 .md / .txt 文件。

图形界面

本 Skill 本身是文本流程。仓库中的 app/ 提供一个调用本 Skill 的 macOS 图形界面，详见 README；界面不改变上述输入边界。

语言

卡片默认使用与原文相同的语言。
用户明确指定输出语言时，以用户要求为准。

输出物

对话中的卡片 Markdown。
项目根目录下 <关键词>/card-01.png、card-02.png 等 PNG 图片，每张卡片一张。

依赖与环境

Python 3.9+。
Pillow（用于渲染 PNG）。
支持卡片语言的字体。脚本会自动查找 Hiragino Sans GB、PingFang、Noto Sans CJK、微软雅黑等常见字体；找不到时用 --font / --font-bold 指定。
没有 Pillow 时，优先用 uv run --with pillow python ...，或安装： python3 -m pip install --user pillow。

工作流程

1. 通读原文

先完整阅读，再开始提炼。确认文章主题、核心结论和论证/操作结构。

2. 提取候选知识点

在内部列出候选知识点。每个候选必须是一个独立、可单独理解的知识点，例如一个结论、原理、方法、步骤或关键定义。

3. 筛选真正重要的内容

用这个标准判断：如果读者只能记住少数内容，这一条是否值得占用一张卡片？

优先保留：

全文的核心结论或主张。
关键原理、因果机制或判断依据。
可执行的步骤、方法或决策规则。
理解后文所必需的定义或前提。

优先删除：

背景铺垫、客套话和与主题无关的细节。
轶事、修辞、重复举例。
常识性内容，或读者不看文章也知道的信息。
只出现一次且不影响主线的次要数据。

目标数量为 5～8 张。若原文确实只有少量重要知识点，只输出有依据的卡片，并注明「原文信息有限，共提炼出 N 张卡片」。不要为凑数量拆分、重复或抬高次要细节。

4. 去重与合并

同一知识点在不同段落重复出现时，只保留一张卡片。
多个候选相互重叠时，合并为信息更完整的一张。
一个知识点的多个子点，若必须放在一起才成立，合并为一张卡片。

5. 写卡片

每张卡片严格包含四项：

### 卡片 N：标题

- **核心知识**：用一句话说清这张卡片唯一的知识点。
- **简明解释**：2～4 句，说明原因、机制或适用条件。
- **例子或自测**：二选一——原文中的例子，或一道能由本卡片回答的自测题。

写作要求：

标题具体，避免「背景」「总结」这类空泛标题。
标题必须与核心知识一致，不要用标题概括超出该卡片的内容。
核心知识必须能脱离原文独立理解。
解释只使用原文信息，不补充外部知识。
保留原文的信息关系：原文是并列就写并列，是推测就保留不确定语气；不要把并列信息改写成因果，也不要补充原文没有的程度、评价或建议。
例子优先取自原文。若原文没有合适例子，改写为自测问题，不要虚构案例、数据或引文。
卡片按逻辑顺序排列（例如：是什么 → 为什么 → 怎么做 → 注意事项），不必照搬原文顺序。
每张卡片只讲一个知识点，卡片之间尽量不依赖彼此。

按文章类型调整

科普/说明文：优先保留机制、结论和影响条件，不要罗列所有研究细节。
操作/教程文：按操作目标或使用场景合并步骤，不要一个命令、一个步骤就单独成卡。
观点/议论文：优先保留中心主张、主要理由和适用边界，不要逐条复述例子。
信息稀少的短文：只提炼有实质内容的点，卡片可以少于 5 张。

6. 确定目录关键词

从整组卡片中选择权重最大的关键词，作为输出目录名：

优先选择贯穿多张卡片、处于主题中心的具体名词或术语，例如产品名、技术名、核心概念。
不要用「方法」「总结」「知识」「介绍」「笔记」等通用词。
与卡片语言一致；中文建议 2～12 字，英文 1～3 个词。
找不到明确关键词时使用文章主题；仍无法确定时使用「知识卡片」。
目录名中的空格和路径非法字符会被替换为 -。
同一关键词目录已存在时，脚本会自动追加 -2、-3，不会覆盖旧目录。

7. 渲染 PNG

把最终卡片 Markdown 写入系统临时目录中的临时文件，不要写进输出目录。卡片标题和字段标签可以用中文模板，也可以用 Card N: / Core knowledge / Explanation / Example or self-test，脚本两者都支持。

在项目根目录运行（把 <skill-dir> 换成实际 Skill 目录）：

uv run --with pillow python <skill-dir>/scripts/render_cards.py \
  --keyword "<关键词>" \
  --output-root "<项目根目录>" \
  --input "<临时卡片文件>"

如果系统已安装 Pillow，把 uv run --with pillow python 换成 python3 即可。

脚本会在 <项目根目录>/<关键词>/ 下生成 card-01.png 到 card-NN.png。渲染成功后删除临时文件。
渲染失败时不要伪造路径：保留对话中的卡片文本，说明失败原因，并给出可复现的命令。

8. 输出前自检

逐项确认：

输出

默认直接在对话中输出卡片，不输出候选列表、分析过程或长篇前言。
同时生成 PNG：<项目根目录>/<关键词>/card-01.png、card-02.png……，每张卡片一张。
PNG 目录中只放图片，不要放临时文件、Markdown 源文件或脚本。
开头可用一句话说明共几张卡片；若少于 5 张，说明是原文信息有限。
结尾用一句话说明 PNG 输出目录和图片数量。
用户明确要求保存 Markdown 时，可另存 knowledge-cards.md；不要默认放进 PNG 目录。

避免

把文章目录或小标题直接当成知识点。
把同一结论拆成多张卡片充数。
为「更完整」而补充原文没有的背景、数据或建议。
用「总之」「由此可见」等空话代替具体知识。
输出与卡片无关的摘要、读后感或延伸阅读。
用「方法」「总结」「知识」等通用词作为目录名。
在未成功渲染时声称 PNG 已生成，或编造文件路径。

make-knowledge-cards