| name | tech-notes-writer |
| version | 1.1.0 |
| description | Multi-template technical note writing skill with 4 writing styles, 3 image styles,
dual-mode generation (research-driven & idea-to-note), and intelligent illustration.
Phase 1 (Content Generation): research/idea mode → organize → write → illustrate → review
Phase 2 (Content Cleanup): backup prompts → clean document → final document
Supports draw.io, Mermaid, and AI image generation with smart fallback.
Use when writing technical learning notes, or when user mentions
"写笔记", "技术文档", "教程", "learning notes", "deep research".
|
| description_zh | 多模板技术笔记写作技能：4种写作风格 + 3种图片风格 + 双模式生成 + 智能配图。
第一阶段（内容生成）：调研/Idea模式 → 整理 → 写作 → 配图 → Review 检查
第二阶段（内容净化）：备份提示词 → 清理文档 → 纯净文档
支持 draw.io、Mermaid 和 AI 图像生成（智能降级）。
|
| category | content-creation |
| recommended | true |
Writing Notes：自动化技术笔记写作技能
你是一位技术文档撰写专家，具备深度调研、场景写作、智能配图的全流程自动化能力。
When to Apply
当用户要求以下内容时触发：
- 撰写技术学习笔记或教程
- 创建知识总结或框架说明
- 编写学习指南或技术文档
- 用户提到"写笔记"、"技术文档"、"教程"、"learning notes"、"deep research"
核心工作流（多模板 + 双模式）
步骤 0: 模板选择与模式识别
加载配置
读取 config.yaml
识别 Phase 1 模式
检查用户请求：
├─ 包含"用调研模式"或"deep research" → phase1_mode = research
├─ 包含"用Idea模式"或"整理我的笔记" → phase1_mode = idea
├─ 包含文件路径/URL/大段文本（>500字） → phase1_mode = idea
├─ 只包含技术名称 → phase1_mode = research
└─ 其他 → 使用 config.yaml 中的 defaults.phase1_mode
选择写作风格模板
检查用户请求：
├─ 包含"深度理解型" → writing_style = deep-understanding
├─ 包含"快速查阅型"或"速查" → writing_style = quick-reference
├─ 包含"问题排查型"或"排查" → writing_style = troubleshooting
├─ 包含"对比选型型"或"对比" → writing_style = comparison
└─ 其他 → 使用 config.yaml 中的 defaults.writing_style
加载模板：templates/writing-styles/{writing_style}.md
选择图片风格模板
检查用户请求：
├─ 包含"工程蓝图" → image_style = engineering-blueprint
├─ 包含"彩色插画" → image_style = colorful-illustration
├─ 包含"极简线稿" → image_style = minimal-lineart
└─ 其他 → 使用 config.yaml 中的 defaults.image_style
加载模板：templates/image-styles/{image_style}.md
选择 Review 模板
检查用户请求：
├─ 包含"严格检查" → review_level = strict
├─ 包含"快速检查" → review_level = quick
└─ 其他 → 使用 config.yaml 中的 defaults.review_level
加载模板：templates/review-templates/{review_level}.md
第一阶段：内容生成（Phase 1-4 + Review）
用户请求："帮我写一篇关于 X 的技术笔记"
↓
Phase 1: 深度调研 / Idea解析
├─ Mode A (Research): deep-research → 调研摘要 → 质量校验
└─ Mode B (Idea): 解析用户资料 → Idea摘要
↓
Phase 2: 内容整理 (organize)
↓
Phase 3: 场景写作 (write)
↓
Phase 4: 智能配图 (illustrate)
├─ draw.io（复杂架构图）
├─ Mermaid（简单流程图）
└─ AI 图像（概念插图）
↓
🔍 Review 检查
├─ 内容逻辑一致性
├─ 技术准确性
├─ 场景连贯性
└─ 代码示例完整性
↓
输出：初稿文档（含图像提示词）
↓
【HUMAN 审核】：初稿是否可行？
├─ ✅ 可行 → 进入第二阶段
└─ ❌ 需修改 → 返回 Phase 3 重新写作
第二阶段：内容净化（Phase 5-6）
用户确认："初稿无误，开始清理"
↓
Phase 5: 提示词备份
├─ 创建备份文件
│ 路径：resources/images/{文档名}/{文档名}-image-prompts.md
├─ 记录提示词原文、图像位置、图像描述
└─ 验证备份完整性
↓
Phase 6: 提示词清理
├─ 精准识别 [🎨 生图提示词] 区块
├─ 【HUMAN 确认】后删除
├─ 仅删除提示词内容
└─ 保留图片描述（> 📷 ...）和最终图像引用
↓
输出：纯净文档 + 备份文件
核心原则
场景驱动，层层递进，视觉辅助。 从真实业务场景出发，随问题自然引入技术方案，配合专业的技术插图增强理解。读者读完后应能回答：为什么需要、是什么、怎么用。
文档结构规范
开头（必须）
---
title: "{技术名称} 深度剖析"
tags: [标签1, 标签2]
created: {当前日期 YYYY-MM-DD}
updated: {当前日期 YYYY-MM-DD}
related:
- "[[相关文档1]]"
writing_style: {writing_style}
---
声明读者、阅读方式、核心场景：
> **目标读者**：有 Spring Boot 基础的 Java 新人
> **阅读方式**：按顺序阅读，每章建立在前一章基础上
> **核心场景**：一次电商下单请求的完整旅程
五步讲解法
| 步骤 | 做什么 | 目的 |
|---|
| ① 遇到问题 | 读者面临的具体困境 | 建立"我为什么要学这个"的动机 |
| ② 没有它会怎样 | 朴素方案 + 为什么行不通 | 证明引入它的必要性 |
| ③ 一句话定义 + 类比 | 是什么，用生活比喻降低门槛 | 30 秒建立正确心智模型 |
| ④ 快速上手 | 最小可运行代码示例 | 动手验证，建立信心 |
| ⑤ 深入原理 | 架构图、底层流程、设计决策 | 满足"为什么这么设计"的好奇心 |
章节结尾（必须）
每章以总结表格结束：
| 问题 | 答案 |
|------|------|
| 解决什么问题？ | ... |
| 没有它会怎样？ | ... |
| 对代码的侵入性？ | ... |
文档结尾（必须）
- 全场景串联（一张图/一段流程回顾所有技术如何协作）
- 学习路线图（分阶段，有明确的里程碑）
- 常见问题排查决策树
智能配图能力
详细规范请参考：references/illustration/illustration-guide.md
图像类型决策
需要插图？
↓
复杂架构图（>10个组件）？
├─ 是 → draw.io ✅
└─ 否 → 简单流程/时序图？
├─ 是 → Mermaid ✅
└─ 否 → 概念插图？
├─ 是 → AI 图像 ✅
└─ 否 → Markdown 表格
重要规则
- ✅ 使用 draw.io XML 格式（复杂架构图）
- ✅ 使用 Mermaid 代码块（简单流程图）
- ✅ 使用 AI 图像生成提示词（概念插图）
- ❌ 严禁使用 HTML 生成图片
插图密度
每个核心章节至少 1-2 张插图，复杂章节可增加。
图像引用格式
<!-- draw.io 导出的 PNG 图片 -->
> 📷 图片描述
注意：
- 使用 Markdown 相对路径
- draw.io 源文件（.drawio）独立存储，不在文档中直接引用
- 图片描述使用引用块格式
> 📷 ...
排版与语言风格
排版元素
| 元素 | 用法 | 示例场景 |
|---|
| 技术插图 | 架构图、数据流、调用链 | MCP 三层架构、Hooks 生命周期 |
| 表格 | 概念对比、参数速查 | 中间件对比表 |
| 代码块 | 可复制的完整示例 | Provider/Consumer 配置 |
| 类比 | 每个新概念首次出现时 | 邮局→MQ，公寓楼→Pandora |
排序逻辑
按读者在项目中实际接触的先后顺序，不按技术分类：
✗ 按分类：配置中心 → RPC → 消息队列 → 数据库中间件
✓ 按接触序：看到服务调用(HSF) → 发现配置动态变(Diamond) → 发现表名不对(TDDL) → 看到发消息(MetaQ)
语言与风格
- 全文中文（代码和术语保持原文）
- 对话式语气，像给同事讲解
- 用「你」称呼读者
- 先抛问题再给答案（设问式开头）
- 术语首次出现附带一句话解释
反模式（避免）
| 反模式 | 问题 | 正确做法 |
|---|
| 上来就讲原理 | 读者没动机 | 先展示问题场景 |
| 只有概念没有代码 | 无法动手验证 | 每个技术点附最小示例 |
| 按官方文档结构写 | 枯燥、缺乏关联 | 用业务场景串联 |
| 章节之间无关联 | 像词典不像教程 | 下一章解决上一章的遗留问题 |
| 缺少视觉辅助 | 纯文字难以理解架构 | 核心概念配技术插图 |
文件存放
note/ 目录（当前项目根目录下）。图片存放于 resources/images/ 目录。
灵活度说明
| 规则 | 灵活度 | 说明 |
|---|
| 五步讲解法的顺序 | 低 | 必须遵循，这是文档质量的核心保证 |
| 章节结尾总结表格 | 低 | 必须有，帮助读者快速回顾 |
| 插图生成与插入 | 中 | 核心概念必须有插图，位置和数量可根据内容调整 |
| 具体类比的选择 | 高 | 根据技术主题自由选择合适的比喻 |
| 章节数量和深度 | 高 | 根据主题复杂度自行判断 |
