知识卡片生成 xv-xiong/article-to-knowledge-cards

make-knowledge-cards

一个基于 Agent Skills 开放规范 的知识卡片技能：把粘贴的文章或本地 Markdown / TXT 文件，转换成 5~8 张知识卡片，每张卡片只讲一个知识点。

技能本体就是一份 SKILL.md（Markdown + YAML frontmatter），不含脚本、不依赖任何运行时私有的 SDK。因此它不限于 WorkBuddy——凡支持 Agent Skills 规范（读取 SKILL.md）的智能体都可直接加载，例如 Claude Code、Codex CLI、DeepSeek Harness、GitHub Copilot、Cursor、Gemini CLI 等；不支持该规范的工具，也可把 SKILL.md 正文当提示词使用（见安装方法）。

另附 agents/openai.yaml（可选）：面向 OpenAI 兼容智能体框架的定义文件，便于显式接入，并非使用本技能的必要条件。

TL;DR (English)

- What: A SKILL.md skill that turns a pasted article or a local .md / .txt file into 5–8 knowledge cards. Each card has four fixed fields: Title / Core knowledge / Plain explanation / Example or self-test question. It follows the open Agent Skills spec, so the same folder runs unchanged in WorkBuddy, Claude Code, Codex CLI, DeepSeek Harness and other compatible agents — and can be pasted as a prompt anywhere else.
- Install: Copy the make-knowledge-cards/ folder into your agent's skills directory — e.g. ~/.workbuddy/skills/, ~/.claude/skills/, ~/.agents/skills/ (see 安装方法). No scripts, no dependencies.
- Try it now: Paste any article and say "做成知识卡片", or copy the SKILL.md body into any chat model as a prompt.

目录

- 1. 这个项目解决什么问题
- 2. 主要功能
- 3. 安装方法
- 4. 使用方法
- 5. 输入输出示例
- 6. 目录结构
- 7. 维护约定
- 8. 反面示例
- 9. 验证（人工检查清单）
- 10. 开源说明
- License

1. 这个项目解决什么问题

读完一篇文章、收藏一篇长文，最常见的结果是——读完就忘。

问题出在"整理"这一步上：

| 常见做法 | 问题 |
| 划重点 / 复制原文 | 只是搬运，没有提炼，复习时还得重读一遍 |
| 让模型写摘要 | 摘要是"压缩复述"，读起来顺畅，但记不住，也没法自测 |
| 让模型随便列要点 | 典型毛病：凑满数量、同一意思拆成好几条、顺手补上原文根本没有的内容 |

make-knowledge-cards 解决的是最后这一类问题。它把长文本切成可记忆、可自测的最小单元，并且用一组硬性约束管住模型最容易犯的错：

- 一张卡片只讲一个知识点（不把两个概念塞进一张卡）
- 去重（原文换种说法重复，只做一张）
- 不编造（每句话都要能在原文里找到依据）
- 不凑数（原文只有 3 个真要点就只出 3 张，绝不为凑满 5~8 张而注水）

目标不是"复述原文"，而是产出一组能拿来复习、能拿来考自己的卡片。

2. 主要功能

固定卡片结构 — 每张卡片四个字段，顺序不变：

- 标题：用一个具体短语命名这一个知识点
- 核心知识：一句话陈述本质事实 / 结论 / 定义
- 简明解释：2~4 句；原文信息不足时 1 句也可，宁短不长。大白话，不使用未定义的术语
- 例子或自测问题：优先用原文自带的例子；没有合适例子就写自测问题，绝不编造例子

六条硬性抽取规则

1. 只取真正重要的知识（定义、机制、原理、关键结论、易混淆的区别）
2. 一卡一点，覆盖两个概念就拆开
3. 去重，换种说法重复同一意思只做一张
4. 不编造，不推断、不延伸、不补充原文没有的事实
5. 不凑数，目标 5~8 张，不足如实少出，超出保留最关键的
6. 语言一致（中文源 → 中文卡；英文源 → 英文卡）

适配 5 类常见文本形态（这是本 Skill 的实用之处，规则里逐条写明了怎么处理）：

| 文本形态 | 处理方式 |
| 技术 / 说明类长文 | 按"定义—机制—结论"逐层抽点，别把例子误当知识点 |
| 论述 / 观点类文章 | 每个独立论点一张卡，论据留在"简明解释"里 |
| 清单 / 攻略类（"N 个方法"） | 先合并含义相近的条目，再按重要性保留 5~8 张 |
| 极短 / 闲聊文本 | 只有 1~2 个真要点就如实少出；毫无知识点则直接说明 |
| 大量外链 / 推荐阅读 / 带广告的文章 | 只取正文实际陈述的信息；标题清单与广告一律剔除；正文只提问、答案在外链的，算作「不可提炼」，不代它作答 |

输入来源：对话中粘贴的文本，或本地 .md / .txt 文件。

明确的能力边界（遇到会直接说明并给出替代方案，不会假装能做）：

- ✗ 网页抓取 / 自动下载 URL 内容
- ✗ 读取或解析 PDF
- ✗ 导出到 Anki 或任何特定复习软件
- ✗ 图形界面 / 可视化卡片排版

3. 安装方法

本技能只有两个文件，不含任何脚本，安装就是复制目录。

方式一：作为 WorkBuddy 技能

把整个 make-knowledge-cards/ 目录复制到对应位置：

| 范围 | 目标路径 | 适用场景 |
| 用户级（推荐） | ~/.workbuddy/skills/make-knowledge-cards/ | 所有项目都能用 |
| 项目级 | <项目>/.workbuddy/skills/make-knowledge-cards/ | 团队共享、随仓库分发 |

Windows 下 ~ 即 C:\Users\<你的用户名>。

用户级（Linux / macOS / Git Bash）
cp -r skills/make-knowledge-cards ~/.workbuddy/skills/

用户级（Windows PowerShell） Copy-Item -Recurse skills/make-knowledge-cards "$env:USERPROFILE/.workbuddy/skills/"

复制后目录结构应为：

~/.workbuddy/skills/make-knowledge-cards/
├── SKILL.md
└── agents/
└── openai.yaml

方式二：作为其他兼容智能体的技能

SKILL.md 遵循 Agent Skills 开放规范，同一份目录无需改动即可被下列运行时加载——区别只在技能目录位置：

| 运行时 | 技能目录（用户级） | 说明 |
| WorkBuddy | ~/.workbuddy/skills/ | 同方式一 |
| Claude Code | ~/.claude/skills/ | 可用 CLAUDE_CONFIG_DIR 覆盖 |
| Codex CLI | ~/.agents/skills/（用户级）、<repo>/.agents/skills/（项目级） | 另有 /etc/codex/skills/（管理员级），见 OpenAI Codex 官方 Skills 文档 |
| DeepSeek Harness（dsh CLI） | $DSH_HOME/skills/ 或 ~/.agents/skills/ | 也扫描项目内 .dsh/skills/、.agents/skills/ |
| 其他（GitHub Copilot、Cursor、Gemini CLI、Cline 等） | 多数读取 ~/.agents/skills/ | 少数有专属目录 |

三点注意：

1. name 必须是 kebab-case，且与技能目录名一致（本技能为 make-knowledge-cards，已符合）。
2. 各运行时只扫描技能根目录的下一层，别把技能埋进更深的子目录。
3. 连 agents/ 目录一起复制过去即可——agents/openai.yaml 会被忽略，不影响加载。

方式三：作为 OpenAI 兼容智能体

agents/openai.yaml 是一个自包含的智能体定义，顶层结构为：

agent:
name: make-knowledge-cards # 与 SKILL.md 的 name 保持一致 description: ... model 未钉死，按部署选择指令遵循能力较强的模型 instructions: | # 已内联完整流程与约束 ...
tools: [] # 无需外部工具，纯靠模型完成
handoffs: []

按目标框架的要求加载即可（如 OpenAI Agents SDK——把本文件的 agent: 块包到 agents: 映射下，再交给 SDK 加载）。instructions 已内联全部规则，无需额外依赖。

方式四：不安装任何东西

把 skills/make-knowledge-cards/SKILL.md 的正文（frontmatter 以下部分）整段复制，直接粘给任意聊天模型当提示词，即可即时试用，无需安装。

4. 使用方法

触发方式 — 安装后在对话中直接说：

把这篇文章做成知识卡片

（并粘贴文章全文）

读取 notes.md，提炼成知识卡片

（给出本地 .md / .txt 路径）

也支持：「总结成学习卡片」「整理成复习卡」「提取要点卡片」等说法。

输出形式 — 以「卡片 N」加四个 - 字段： 粗体块的形式输出（见上方示例），开头有一行说明本次张数与取舍原因：

共 7 张（原文技术点较密，已尽量一卡一点，无重复）。

卡片 1
- 标题：...
- 核心知识：...
- 简明解释：...
- 例子或自测问题：...

落盘 — 默认只输出到对话中；需要保存成文件时再提出，默认写为 knowledge-cards.md（或原文件名加 .cards.md 后缀）。

5. 输入输出示例

输入

对话中粘贴：

HTTP 是无状态协议，每次请求独立；Cookie 由服务器通过 Set-Cookie 下发，浏览器后续请求自动带上，用于维持登录状态。HTTPS 在 HTTP 之下加了 TLS 加密层。
或指定文件：examples/make-knowledge-cards/inputs/technical.md

输出

共 3 张（原文仅 3 个真要点，如实输出，不凑数）。

卡片 1
- 标题：HTTP 是无状态协议
- 核心知识：HTTP 本身不保存前后请求之间的关系，每次请求都是独立的。
- 简明解释：这意味着服务器默认记不住"你上一秒是谁"。要识别同一用户，需要额外机制（如 Cookie）来携带身份。
- 例子或自测问题：自测——为什么刷新页面后有时需要重新登录？什么机制能避免这种情况？

卡片 2
- 标题：Cookie 维持登录状态的原理
- 核心知识：服务器用 Set-Cookie 下发标识，浏览器在后续请求中自动回传，从而让无状态的 HTTP 记住用户。
- 简明解释：登录成功后，服务器把一个"凭证"交给浏览器；之后每次请求浏览器都自动带上它，服务器据此认出用户。
- 例子或自测问题：自测——既然 HTTP 本身无状态，为什么你登录后浏览同一网站的其他页面时，服务器还能认出你？

卡片 3
- 标题：HTTPS = HTTP + TLS 加密层
- 核心知识：HTTPS 在 HTTP 之下增加 TLS，对传输内容加密，防止被窃听或篡改。
- 简明解释：两者关系类似"普通邮寄"与"加了上锁信封的邮寄"；应用层用法不变，但链路被加密保护。
- 例子或自测问题：自测——HTTP 和 HTTPS 在"无状态"这一点上有区别吗？

更多测试用例

examples/make-knowledge-cards/ 提供 5 类文本的真实输入输出，覆盖 Skill 的边界行为：

| 文本类型 | 输入 | 输出 | 体现的规则 |
| 技术说明文 | inputs/technical.md | examples/make-knowledge-cards/outputs/technical.cards.md（7 张） | 密集知识点拆分 |
| 观点论述文 | inputs/essay.txt | examples/make-knowledge-cards/outputs/essay.cards.md（5 张） | 论点成卡、论据入解释 |
| 极短文本 | inputs/short.txt | examples/make-knowledge-cards/outputs/short.cards.md（3 张） | 不凑数 |
| 清单攻略文 | inputs/listicle.md | examples/make-knowledge-cards/outputs/listicle.cards.md（10 条 → 8 张） | 去重 + 拆分 + 截断到 8 张 |
| 日常闲聊 | inputs/chat.txt | examples/make-knowledge-cards/outputs/chat.cards.md（0 张） | 无知识点时如实说明 |

6. 目录结构

article-to-knowledge-cards/
├── README.md
├── CHANGELOG.md # 各版本变更记录（Keep a Changelog 格式） ├── LICENSE # MIT ├── .gitignore ├── .gitattributes ├── skills/make-knowledge-cards/ │ ├── SKILL.md # 技能说明、卡片结构、抽取规则、输入形态适配 │ └── agents/ │ └── openai.yaml # OpenAI 兼容智能体定义（精简版，可选） └── examples/make-knowledge-cards/ ├── inputs/ # 5 组测试用例输入 └── outputs/ # 对应的 5 组卡片输出

整个 Skill 仅 2 个文件、无脚本依赖，全部能力由模型本身完成。

7. 维护约定

抽取规则同时写在两份文件里：SKILL.md（完整，含"常见输入形态"等适配）与 agents/openai.yaml（精简版，字段与硬规则一致）。修改任意一条抽取规则时，必须同步改这两份文件，否则会出现规则漂移。本仓库早期版本就因两份文件措辞不一致，导致示例输出出现了编造例子——这一教训已被写进两份文件的硬规则中。

8. 反面示例

下面三例都来自本仓库示例输出的清洗过程，说明"不允许写成这样"：

❌ 编造事实（原文根本没说）卡片写法：聚簇索引"决定了数据在磁盘上的排列顺序，因此一张表只能有一个聚簇索引。"
✅ 应该：只保留原文明确给出的"主键默认建立聚簇索引，数据行本身按主键顺序物理存放"，删掉"只能有一个"等原文没有的断言。
为什么：原文从未出现"非聚簇索引"或"一张表只能有一个聚簇索引"，这是凭空加的机制。

❌ 编造例子（用原文没有的场景当示例）卡片写法：解释"任务越模糊越容易拖"时举例"「写报告」改成「先列 3 个标题」就更容易动手。"
✅ 应该：改成自测问题——"为什么把模糊的大任务拆成具体小步骤，心理阻力会明显下降？"
为什么：原文只说"拆成具体、可操作的小步骤"，从未举"写报告 / 列标题"的例子；代答式例子等于编造。

❌ 凑数 / 注水（为填满句子硬加原文没有的机制）卡片写法：解释"每完成 4 个番茄钟长休息一次"时写"短休息恢复注意力，长休息防止累积疲劳。"
✅ 应该：只说"完成 4 个番茄钟后安排一次较长的休息，和短休息一起形成专注—休息的节律。"
为什么：原文只说"休息 15~30 分钟"和"避免一直紧绷"，并未给出"恢复注意力 / 防止累积疲劳"这套因果。

9. 验证（人工检查清单）

本仓库不附带脚本（按设计仅 2 个文件、无依赖）。对外发布后，可用 WorkBuddy 内置 skill-creator 的 quick_validate.py 校验；作者已在本地用该脚本验证通过（Skill is valid!）。你也可逐项人工核对：

- [ ] SKILL.md 的 frontmatter 仅含规范字段：name、description、license（不得出现规范外的其他键）
- [ ] name 为 hyphen-case（即 make-knowledge-cards）
- [ ] description 不含尖括号 <>、不含未经验证的功能声明
- [ ] 每张卡片四个字段齐全且顺序为：标题 → 核心知识 → 简明解释 → 例子或自测问题
- [ ] agents/openai.yaml 的 name 与 SKILL.md 一致；instructions 含全部硬规则
- [ ] 全仓库无 BOM、无 CRLF（UTF-8 LF）

10. 开源说明

- 无脚本、无第三方依赖，仅靠模型本身，开箱即用。
- agents/openai.yaml 是 SKILL.md 的精简版（含核心字段、硬规则与输出格式）；完整的「常见输入形态」等适配规则以 SKILL.md 为准。两者可分别在 WorkBuddy 与 OpenAI 兼容框架中使用。
- 欢迎提交 Issue / PR 改进抽取规则与示例。

License

本项目以 MIT 许可证开源，详见 LICENSE。

本项目非 WorkBuddy 官方项目，仅为社区维护的开源 Skill。