图文知识学习 Skill
给一个主题，交付一篇能讲清原理的中文知识文章、已经生成并嵌入的解释图，以及可追溯的来源和提示词，保存到用户的 Obsidian。
运行前提
宿主需能加载技能或执行本套指令，具备联网、文件读写和可调用的生图模型。推荐具备这些能力的 Codex / ChatGPT 环境；其他 Agent 可使用已配置的生图工具。直接写入本机 Obsidian 还需要本地文件访问，只有导出能力时交付文章与图片并说明入库缺口。先检查实际工具，不能仅凭产品名称认定能力齐全。
选择输出形式
- 知识文章：按下方 1–6 步完成资料查证、图文讲解与 Obsidian 入库。
- 项目图文 README：先读 README 工作流，围绕“能做什么、产出长什么样、如何安装、第一次怎么用”组织图文，保存在项目中。此形式不要求 Obsidian 配置，也不套用知识长文的篇幅、图量、YAML 和总结图要求。查证、写作与配图原则继续复用。
范围与默认结果
- 完整文章通常约 3000–6000 中文字、3–5 张解释图；图量含结尾综合总结图，按主题调整。
- 开头用浅底色的概念导语交代“是什么、怎样工作、解决什么问题”，保留完整定义；随后介绍必要背景、动机与由来。
- 图片默认采用 Jiale 的 AI 工坊风格。正文与图注就地交代影响理解的条件，图片直接解释知识。
- 修订任务只改用户指定部分。只调整开头卡片时，保留正文、配图、图注与配图风格；用户明确要求重绘后再改图。
- 在已授权范围内完成查证、写作、生成和入库。缺少影响结果的配置时集中询问，不把普通版式选择变成审批。
1. 确定笔记库与依赖
读取技能根目录的 config.local.json（如存在）。本次明确要求优先于配置；配置缺项再使用用户环境或知识库指引。字段见 归档规则。缺少目标库且无法从上下文确定时，只询问目标库路径，先完成独立的研究与草稿工作。
进入目标库后，读取存在的 AGENTS.md、使用指南和首页；参考同类笔记确定目录、元信息与链接方式。依赖 wikilink 内容时打开实际文件。
按本阶段需要使用以下能力，从当前环境的技能目录定位，避免写死安装路径：
| 能力 | 优先复用 | 未安装时 |
|---|---|---|
| 平台搜索与读取 | agent-reach；先读其说明，使用实际可用渠道 | 使用宿主可用的只读检索，并说明本次采用的渠道 |
| 通用网页与论文查证 | 宿主联网工具；可辅以 research-workflow | 直接阅读一手资料 |
| 写作与配图规划 | 本包规则；可辅以 content-research-writer、baoyu-article-illustrator | 按本包流程完成 |
| 位图生成或编辑 | 宿主可调用的生图工具；有原生 Image / imagegen 时优先使用 | 保留已完成草稿与配图计划，明确图片缺口 |
| 本地入库 | Python 3.10+、本包归档脚本 | 明确缺失环境，保留可迁移的工作文件 |
这些外部技能不随本包分发。已有授权覆盖的步骤继续执行；遵守宿主工具的真实能力和限制。
2. 查证并建立资料底稿
在本次工作目录保存 sources.md：记录实际打开的资料、URL、版本或日期、支持的结论与未解决问题。先查官方文档、论文、源代码和原始发布；平台帖子用于发现线索、实践经验或争议。适合的平台资料优先通过 Agent Reach 获取。
文章中的重要数字、年代、架构和性能结论对应实际读过的原文。检索摘要只作为线索；区分事实、推断、教学算例与实测结果。涉及起源和演变时核对原始来源。按需要读已有笔记，复用概念并核实链接目标。
完成条件：核心机制和背景均有依据，关键分歧已说明，资料足够支撑文章中的具体例子。
3. 写出学习主线
读取 写作规则，形成带 YAML frontmatter 的 Markdown 草稿。用完整定义开篇，按“背景与动机 → 整体过程 → 关键机制 → 具体例子 → 工程取舍 → 学习收束”组织内容，顺序随主题调整。
在有图解价值的位置放唯一标记，例如 <!-- figure:01 -->。正文解释原因和中间推理，图展示结构、过程或差异；来源链接靠近相应结论。结尾综合总结图位于主要讲解之后、原始资料列表之前。
完成条件：读者能解释因果过程、复述一个例子并判断适用条件；开头定义、背景和结尾总结衔接，关键结论与资料底稿一致。
4. 规划并生成配图
读取 视觉规范，保存 illustration-plan.md，列明每张图的问题、对应段落、节点、连线、数值与图注。若复用宝玉配图，将该视觉规范复制到本次目录的 .baoyu-skills/baoyu-article-illustrator/EXTEND.md。
每张图的完整最终提示词保存为 prompts/01-flow.md 等文件。按“解释目的、具体对象和关系、版式、视觉、逐字标签、画幅”组织正面描述。使用宿主可调用的生图工具，有原生 Image / imagegen 时优先使用；参数与调用方式遵守当前工具规则，通常每批两张。
从工具结果定位真实文件，复制到本次工作目录。逐张打开检查术语、中文字、数字、箭头、比较尺度和可读性。发现明确错误时保存修订提示词并定向修正；保留可用版本，仍有缺口就如实记录。配图缺失或未核验时不能宣称完整图文结果。
5. 保存到 Obsidian
读取 归档规则，保存 images.json。先对真实草稿、图片、提示词和资料记录执行归档脚本的 --dry-run，确认结果后入库。将技能目录解析为实际路径，再调用 scripts/archive_note.py，明确传入目标库、笔记目录与附件目录。
归档脚本只新增笔记，同名时创建版本后缀。修改已有文章时，先备份并按本次授权原位修改；不要重复归档出第二篇，也不要让未改动的图片重新生成。
需要定义卡片样式时使用 assets/jiale-knowledge.css；首次安装样式只追加该片段，保留用户已有设置和定制。知识库存在合适索引时补充一条链接，避免重复。
6. 完成核对
核对最终文章、图片及文件是否实际存在，figure 标记是否全部替换，嵌入和 wikilink 是否可解析。文件检查、图中文字审阅和界面预览分别报告真实验证范围。
交付时简要说明完成内容、保存位置与实际缺口，附可打开的笔记或导出文件。知识文章只有资料、正文、真实配图与入库均完成，才标记为完整交付；项目 README 按对应工作流的完成条件核对。