make-knowledge-cards

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

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

2. 在项目根目录运行（把 <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 即可。

3. 脚本会在 <项目根目录>/<关键词>/ 下生成 card-01.png 到 card-NN.png。渲染成功后删除临时文件。

4. 渲染失败时不要伪造路径：保留对话中的卡片文本，说明失败原因，并给出可复现的命令。

8. 输出前自检

逐项确认：

• 每张卡片只有一个知识点。
• 所有内容都能在原文中找到依据，没有编造的人名、数字、因果或结论。
• 没有把原文的并列、推测改写成因果或确定判断。
• 已删除重复和高度重叠的内容。
• 卡片数量为 5～8 张，或已说明原文信息不足的原因。
• 开头声明的卡片数量与实际卡片数量一致。
• 每张卡片都包含标题、核心知识、简明解释、例子或自测四项。
• 标题与核心知识一致，没有夸大单张卡片的范围。
• 读者只看单张卡片也能理解。
• 已选出唯一关键词，目录名不是通用词。
• PNG 数量与卡片数量一致，文件名连续。
• 每张 PNG 都能打开，文字没有溢出或截断。
• 临时文件已删除，PNG 目录中只有图片。

输出

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

避免

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