tomevault-io Converting Markdown to HTML
Quick Start
# 指定文件，使用默认主题（purple）
python3 scripts/convert.py document.md
# 指定文件和主题
python3 scripts/convert.py document.md --theme blue
# 列出所有可用主题
python3 scripts/convert.py --list-themes
Features
- ✅ 多主题支持：purple（紫色）、blue（蓝色）、green（绿色）、corporate（企业蓝）、minimal（极简灰度）
- ✅ 响应式设计（PC/平板/手机）
- ✅ 打印优化（自动移除渐变和阴影）
- ✅ 智能段落合并：使用专业库，无多余
<br>标签 - ✅ ASCII图清晰显示：用等宽字体保留，结构准确
- ✅ 智能 SVG 转换：AI Agent 将 ASCII 图转换为精美 SVG/HTML
- ✅ 稳定的转换逻辑（Python 脚本，依赖 markdown + PyYAML）
⚠️ 重要约束：UI 图必须静态展示
对于 UI 类型的 ASCII 图（弹出窗、对话框、表单等）：
❌ 禁止：
- 使用 JavaScript 控制显示/隐藏
- 使用
onclick、onhover等事件处理 - 使用
display: none隐藏内容 - 需要用户交互才能看到完整内容
- 生成完整的 HTML 文档（包含
<html>,<head>,<body>,<!DOCTYPE>等标签）
✅ 必须：
- 所有内容直接显示在文档中
- 使用纯 HTML/CSS，不用 JavaScript
- 生成 HTML 片段（fragment），只包含 UI 组件代码
- 目标是展示设计效果，不是实现功能
- 适合打印和导出 PDF
⚠️ HTML 片段规范：
- ✅ 允许：
<div>,<button>,<span>,<p>,<h1>~`` 等标签 - ✅ 允许：内联
style属性和<style>标签 - ❌ 禁止：
<html>,<head>,<body>,<!DOCTYPE>等顶层标签 - ❌ 禁止：
<script>标签（内联或外部脚本）和事件处理属性 - 原因：生成的代码会被插入到已有的 HTML 文档中，包含顶层标签会导致标签嵌套错误
Available Themes
| Theme | Name | Colors | Use Case |
|---|---|---|---|
| purple | 紫色渐变主题 | #667eea → #764ba2 | 售前方案、商务文档 |
| blue | 蓝色科技主题 | #1890ff → #096dd9 | 技术文档、API 文档 |
| green | 绿色清新主题 | #52c41a → #389e0d | 内部报告、运营数据 |
| corporate | 企业蓝主题 | #003366 → #007bff | 正式方案、标书文档 |
| minimal | 极简灰度主题 | 灰度系 | 学术论文、正式报告 |
Usage
Command Line Options
# 基本用法
python3 scripts/convert.py [markdown_file] [options]
# 选项：
# --theme, -t 主题名称（默认：purple）
# --list-themes, -l 列出所有可用主题
# 示例：
python3 scripts/convert.py "文档.md" # 默认紫色主题
python3 scripts/convert.py "文档.md" --theme blue # 蓝色主题
python3 scripts/convert.py "文档.md" --theme green # 绿色主题
python3 scripts/convert.py "文档.md" --theme corporate # 企业蓝主题
python3 scripts/convert.py "文档.md" --theme minimal # 极简主题
python3 scripts/convert.py --list-themes # 列出所有主题
AI 交互流程
流程概述
graph TD
A[开始] --> B{用户指定文件?}
B -->|否| C[使用 AskUserQuestion 选择文件]
B -->|是| D[选择主题模板]
C --> D
D --> E{文件包含 ASCII 图?}
E -->|否| F[直接转换 HTML]
E -->|是| G{处理方式?}
G -->|保留原样| F
G -->|智能转换| H[步骤1: 生成占位符 HTML]
H --> I[步骤2: 提取占位符到 JSON]
I --> J[步骤3: AI 生成 SVG/HTML]
J --> K[步骤4: 替换占位符]
F --> L[验证输出]
K --> L
L --> M[完成]
快速参考
| 步骤 | 操作 | 说明 |
|---|---|---|
| 步骤1 | 选择 Markdown 文件 | 使用 AskUserQuestion 工具 |
| 步骤2 | 选择主题 | purple/blue/green/corporate/minimal |
| 步骤3 | 处理 ASCII 图 | 保留原样 OR 智能转换（3步流程） |
| 步骤4 | 验证输出 | 检查清单见"验证规则"章节 |
⚠️ AI Agent 执行规范
执行脚本时的重要规则：
- 使用完整路径调用脚本：确保脚本能被找到
- 使用完整路径指定输入文件：避免文件找不到
- 不要 cd 切换目录：保持当前工作目录不变
- 明确输出位置：告知用户 HTML 文件的生成位置
❌ 错误示例：
# 错误1：切换目录（会改变工作目录）
cd /path/to/skill && python3 scripts/convert.py document.md
# 错误2：使用相对路径（可能找不到文件）
python3 scripts/convert.py ../../document.md
✅ 正确示例：
# 方法1：使用绝对路径（推荐）
python3 /path/to/skill/scripts/convert.py /path/to/document.md --theme blue
# 方法2：先 cd 到项目目录，再执行
cd /path/to/project
python3 /path/to/skill/scripts/convert.py document.md --theme blue
执行后告知用户：
✅ 转换完成！
📄 输入文件：/path/to/document.md
📄 输出文件：/path/to/document.html
📊 文件大小：XX KB
💡 提示：HTML 文件与 Markdown 文件在同一目录
处理 ASCII 图
检测和类型识别
支持的 5 种图形类型：
architecture- 系统架构图flowchart- 流程图ui- UI 界面图（⚠️ 输出 HTML，不是 SVG）timeline- 时间线图diagram- 通用图
处理方式
如果文档包含 ASCII 图，询问用户处理方式：
选项1：保留原样
- 直接调用
python3 scripts/convert.py [file] --theme [theme] - ASCII 图用等宽字体显示
- 适合快速预览
选项2：智能转换 SVG/HTML（3 步流程）⭐
子步骤 1：生成带占位符的 HTML
AI_SVG_CONVERSION=true python3 scripts/convert.py [file] --theme [theme]
子步骤 2：提取占位符到 JSON
python3 scripts/extract_placeholders.py [file.html]
子步骤 3：AI 生成 SVG/HTML
🔴 核心要求：必须有 Task 工具时，使用多 Task 并行生成
| 方式 | 耗时（8个图） | 说明 |
|---|---|---|
| 顺序处理 | ~80秒 | AI 一个接一个生成 |
| 多 Task 并行 | ~20秒 | 多个 Task 同时工作 |
实现方式：
- 读取 extracted.json，获取所有占位符
- 为每个占位符创建一个 Task（如果平台支持 Task 工具）
- 所有 Task 并行执行
- 等待所有 Task 完成，然后调用替换脚本
质量要求（每个 Task 都必须满足）：
- ✅ 圆角效果（
rx="8"） - ✅ 主题色系（primary、secondary）
- ✅ 字体设置（
font-family） - ✅ HTML class 前缀（
[类型]-[ID]-，避免冲突） - ✅ SVG 代码长度 > 500 字符（不是简略版）
- 调用替换脚本：
python3 scripts/replace_svg.py .cvt-caches/{document}/{session_id}/extracted.json
📖 详细规范和指南（按需加载）
本技能包含以下详细参考资料，AI Agent 仅在需要时加载：
📄 输出格式和代码要求
文件：references/output-specs.md
包含内容：
- SVG 输出要求（architecture/flowchart/timeline/diagram）
- HTML 输出要求（ui 类型）
- 质量检查清单
- 错误示例和常见问题
何时读取：
- AI 需要生成 SVG/HTML 代码时
- 需要验证代码质量时
🎨 ASCII 识别和转换技巧
文件：references/ascii-to-svg.md
包含内容：
- 如何识别不同类型的 ASCII 图
- 转换技巧和最佳实践
- 常见问题解决方案
何时读取：
- AI 需要理解 ASCII 图结构时
- 需要优化转换效果时
🔧 技术细节和常见问题
文件：references/technical-details.md
包含内容：
- 转换流程的技术细节
- 缓存管理机制
- 常见错误和解决方案
何时读取：
- 遇到技术问题时
- 需要调试转换流程时
🤖 AI 生成规范
文件：references/ai-generation-specs.md
包含内容：
- AI 生成代码的详细规范
- 并行生成的实现方式
- 质量标准和验证方法
何时读取：
- 执行智能转换时
- 需要了解生成要求时
验证转换结果
适用范围： 以下验证清单仅针对 AI Agent 生成的 SVG/HTML 代码，不适用于完整 HTML 文档。
快速验证清单
生成代码时检查：
SVG 代码：
- ✅ 以
<svg开头，</svg>结尾 - ✅ 包含
xmlns="http://www.w3.org/2000/svg" - ✅ 有
viewBox属性（不要用硬编码的 width/height） - ✅ 使用主题色系（见"配色速查表"）
- ✅ 包含圆角效果（
rx="8"） - ✅ 字体设置（
font-family）
HTML 代码：
- ✅ 使用语义化 HTML5 标签（
<div>,<button>,<input>等） - ✅ HTML class 必须有前缀（格式：
[类型]-[ID]-，如ui-1-container）⚠️ - ✅ UI 类型必须是静态展示：
- ❌ 不使用
<script>标签（内联或外部脚本） - ❌ 不使用事件处理属性（onclick、onhover 等）
- ❌ 不使用
display:none等隐藏内容 - ❌ 不包含完整 HTML 文档标签（
<html>,<head>,<body>,<!DOCTYPE>） - ✅ 必须是 HTML 片段（可插入到
<body>内部的代码） - ✅ 允许使用
<style>标签和内联style属性 - ✅ 所有内容直接显示在文档中
- ❌ 不使用
替换后检查：
# 检查是否还有未替换的占位符
grep -c "AI-SVG-PLACEHOLDER" output.html
# 输出应该为 0
配色速查表
| 主题 | Primary | Secondary | Background | Text |
|---|---|---|---|---|
| purple | #667eea | #764ba2 | #f8f9fa | #333333 |
| blue | #1890ff | #096dd9 | #f0f5ff | #333333 |
| green | #52c41a | #389e0d | #f6ffed | #333333 |
| corporate | #003366 | #007bff | #ffffff | #1a1a2e |
| minimal | #333333 | #666666 | #ffffff | #333333 |
Examples
基础用法
# 转换单个文件
python3 scripts/convert.py document.md
# 指定主题
python3 scripts/convert.py document.md --theme blue
# 列出主题
python3 scripts/convert.py --list-themes
智能转换流程
# 步骤1：生成占位符
AI_SVG_CONVERSION=true python3 scripts/convert.py document.md --theme purple
# 步骤2：提取占位符
python3 scripts/extract_placeholders.py document.html
# 步骤3：AI 生成 SVG/HTML 并替换
python3 scripts/replace_svg.py document.json
Converted and distributed by TomeVault — claim your Tome and manage your conversions.