Add output preview phase and callout types specifications

- Implemented Phase 4: Output & Preview for text formatter, including saving formatted content, generating statistics, and providing HTML preview. - Created callout types documentation with detection patterns and conversion rules for BBCode and HTML. - Added element mapping specifications detailing detection patterns and conversion matrices for various Markdown elements. - Established format conversion rules for BBCode and Markdown, emphasizing pixel-based sizing and supported tags. - Developed BBCode template with structured document and callout templates for consistent formatting.
2026-02-14 02:42:04 +08:00 · 2026-01-13 16:53:25 +08:00
parent 549e6e70e4
commit 94ae9e264c
9 changed files with 2076 additions and 0 deletions
--- a/.claude/skills/text-formatter/specs/callout-types.md
+++ b/.claude/skills/text-formatter/specs/callout-types.md
@@ -0,0 +1,293 @@
+# Callout Types
+
+Obsidian 风格的 Callout/Admonition 类型定义和转换规则。
+
+## When to Use
+
+| Phase | Usage | Section |
+|-------|-------|---------|
+| Phase 2 | 检测 Callout | Detection patterns |
+| Phase 3 | 格式转换 | Conversion rules |
+
+---
+
+## Callout 语法
+
+### Obsidian 原生语法
+
+```markdown
+> [!TYPE] 可选标题
+> 内容行1
+> 内容行2
+```
+
+### 支持的类型
+
+| Type | Alias | Icon | Color | 用途 |
+|------|-------|------|-------|------|
+| `note` | - | 📝 | blue | 普通提示 |
+| `info` | - | ℹ️ | blue | 信息说明 |
+| `tip` | `hint` | 💡 | green | 技巧提示 |
+| `success` | `check`, `done` | ✅ | green | 成功状态 |
+| `warning` | `caution`, `attention` | ⚠️ | orange | 警告信息 |
+| `danger` | `error` | ❌ | red | 危险/错误 |
+| `bug` | - | 🐛 | red | Bug 说明 |
+| `example` | - | 📋 | purple | 示例内容 |
+| `quote` | `cite` | 💬 | gray | 引用内容 |
+| `abstract` | `summary`, `tldr` | 📄 | cyan | 摘要 |
+| `question` | `help`, `faq` | ❓ | yellow | 问题/FAQ |
+| `todo` | - | 📌 | orange | 待办事项 |
+
+---
+
+## 检测 Pattern
+
+```javascript
+// Callout 检测正则
+const CALLOUT_PATTERN = /^>\s*\[!(\w+)\](?:\s+(.+))?$/;
+
+// 检测函数
+function detectCallout(line) {
+  const match = line.match(CALLOUT_PATTERN);
+  if (match) {
+    return {
+      type: match[1].toLowerCase(),
+      title: match[2] || null
+    };
+  }
+  return null;
+}
+
+// 解析完整 Callout 块
+function parseCalloutBlock(lines, startIndex) {
+  const firstLine = lines[startIndex];
+  const calloutInfo = detectCallout(firstLine);
+
+  if (!calloutInfo) return null;
+
+  const content = [];
+  let i = startIndex + 1;
+
+  while (i < lines.length && lines[i].startsWith('>')) {
+    content.push(lines[i].replace(/^>\s*/, ''));
+    i++;
+  }
+
+  return {
+    ...calloutInfo,
+    content: content.join('\n'),
+    endIndex: i - 1
+  };
+}
+```
+
+---
+
+## 转换规则
+
+### BBCode 转换
+
+```javascript
+const CALLOUT_BBCODE = {
+  note: {
+    icon: '📝',
+    color: '#2196F3',
+    label: '注意'
+  },
+  info: {
+    icon: 'ℹ️',
+    color: '#2196F3',
+    label: '信息'
+  },
+  tip: {
+    icon: '💡',
+    color: '#4CAF50',
+    label: '提示'
+  },
+  success: {
+    icon: '✅',
+    color: '#4CAF50',
+    label: '成功'
+  },
+  warning: {
+    icon: '⚠️',
+    color: '#FF9800',
+    label: '警告'
+  },
+  danger: {
+    icon: '❌',
+    color: '#F44336',
+    label: '危险'
+  },
+  bug: {
+    icon: '🐛',
+    color: '#F44336',
+    label: 'Bug'
+  },
+  example: {
+    icon: '📋',
+    color: '#9C27B0',
+    label: '示例'
+  },
+  quote: {
+    icon: '💬',
+    color: '#9E9E9E',
+    label: '引用'
+  },
+  question: {
+    icon: '❓',
+    color: '#FFEB3B',
+    label: '问题'
+  }
+};
+
+function calloutToBBCode(type, title, content, style = 'forum') {
+  const config = CALLOUT_BBCODE[type] || CALLOUT_BBCODE.note;
+  const displayTitle = title || config.label;
+
+  if (style === 'compact') {
+    return `[quote][b]${config.icon} ${displayTitle}[/b]
+${content}[/quote]`;
+  }
+
+  // Forum style - more visual
+  return `[quote]
+[color=${config.color}][size=4][b]${config.icon} ${displayTitle}[/b][/size][/color]
+
+${content}
+[/quote]`;
+}
+```
+
+### HTML 转换
+
+```javascript
+function calloutToHTML(type, title, content) {
+  const config = CALLOUT_BBCODE[type] || CALLOUT_BBCODE.note;
+  const displayTitle = title || config.label;
+
+  return `<div class="callout callout-${type}">
+  <div class="callout-title">
+    <span class="callout-icon">${config.icon}</span>
+    <span class="callout-title-text">${displayTitle}</span>
+  </div>
+  <div class="callout-content">
+    ${content}
+  </div>
+</div>`;
+}
+```
+
+### Hybrid 转换
+
+```javascript
+function calloutToHybrid(type, title, content) {
+  const config = CALLOUT_BBCODE[type] || CALLOUT_BBCODE.note;
+  const displayTitle = title || config.label;
+
+  // HTML container + BBCode styling + MD content
+  return `<div class="callout ${type}">
+
+[color=${config.color}][b]${config.icon} ${displayTitle}[/b][/color]
+
+${content}
+
+</div>`;
+}
+```
+
+---
+
+## Callout CSS 样式
+
+```css
+/* Base callout styles */
+.callout {
+  padding: 1rem;
+  margin: 1rem 0;
+  border-left: 4px solid;
+  border-radius: 4px;
+  background: #f8f9fa;
+}
+
+.callout-title {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  font-weight: 600;
+  margin-bottom: 0.5rem;
+}
+
+.callout-icon {
+  font-size: 1.2em;
+}
+
+/* Type-specific colors */
+.callout-note, .callout-info {
+  border-color: #2196F3;
+  background: #E3F2FD;
+}
+
+.callout-tip, .callout-success {
+  border-color: #4CAF50;
+  background: #E8F5E9;
+}
+
+.callout-warning {
+  border-color: #FF9800;
+  background: #FFF3E0;
+}
+
+.callout-danger, .callout-bug {
+  border-color: #F44336;
+  background: #FFEBEE;
+}
+
+.callout-example {
+  border-color: #9C27B0;
+  background: #F3E5F5;
+}
+
+.callout-quote {
+  border-color: #9E9E9E;
+  background: #FAFAFA;
+}
+
+.callout-question {
+  border-color: #FFC107;
+  background: #FFFDE7;
+}
+```
+
+---
+
+## 折叠 Callout
+
+支持可折叠的 Callout 语法：
+
+```markdown
+> [!NOTE]+ 默认展开
+> 内容
+
+> [!NOTE]- 默认折叠
+> 内容
+```
+
+### BBCode 折叠
+
+```bbcode
+[collapse=📝 注意]
+内容
+[/collapse]
+```
+
+### HTML 折叠
+
+```html
+<details class="callout callout-note">
+  <summary>📝 注意</summary>
+  <div class="callout-content">
+    内容
+  </div>
+</details>
+```
--- a/.claude/skills/text-formatter/specs/element-mapping.md
+++ b/.claude/skills/text-formatter/specs/element-mapping.md
@@ -0,0 +1,209 @@
+# Element Mapping
+
+内容元素到 BBCode + Markdown 混合格式的映射表。
+
+## When to Use
+
+| Phase | Usage | Section |
+|-------|-------|---------|
+| Phase 2 | 元素识别 | Detection patterns |
+| Phase 3 | 格式转换 | Conversion rules |
+
+---
+
+## Element Detection Patterns
+
+### 标题检测
+
+| 类型 | Pattern | 示例 |
+|------|---------|------|
+| ATX 标题 | `/^#{1,6}\s+(.+)$/` | `# Title`, `## Subtitle` |
+| Setext H1 | `/^(.+)\n={3,}$/` | `Title\n====` |
+| Setext H2 | `/^(.+)\n-{3,}$/` | `Subtitle\n----` |
+
+### 列表检测
+
+| 类型 | Pattern | 示例 |
+|------|---------|------|
+| 无序列表 | `/^[\s]*[-*+]\s+(.+)$/` | `- item`, `* item` |
+| 有序列表 | `/^[\s]*\d+\.\s+(.+)$/` | `1. item`, `2. item` |
+| 任务列表 | `/^[\s]*[-*]\s+\[([ x])\]\s+(.+)$/` | `- [ ] todo`, `- [x] done` |
+
+### Callout 检测
+
+| 类型 | Pattern | 示例 |
+|------|---------|------|
+| Callout 开始 | `/^>\s*\[!(\w+)\](?:\s+(.+))?$/` | `> [!NOTE] 标题` |
+| Callout 内容 | `/^>\s*(.*)$/` | `> 内容行` |
+| 可折叠展开 | `/^>\s*\[!(\w+)\]\+/` | `> [!NOTE]+` |
+| 可折叠收起 | `/^>\s*\[!(\w+)\]-/` | `> [!NOTE]-` |
+
+### 代码检测
+
+| 类型 | Pattern | 示例 |
+|------|---------|------|
+| 代码块开始 | `/^```(\w*)$/` | ` ```js ` |
+| 代码块结束 | `/^```$/` | ` ``` ` |
+| 行内代码 | `/`([^`]+)`/` | `` `code` `` |
+
+### 其他元素
+
+| 类型 | Pattern | 示例 |
+|------|---------|------|
+| 链接 | `/\[([^\]]+)\]\(([^)]+)\)/` | `[text](url)` |
+| 图片 | `/!\[([^\]]*)\]\(([^)]+)\)/` | `![alt](url)` |
+| 普通引用 | `/^>\s+(.+)$/` | `> quote` |
+| 分隔线 | `/^[-*_]{3,}$/` | `---`, `***` |
+| 高亮 | `/==(.+?)==/` | `==highlight==` |
+| 粗体 | `/\*\*(.+?)\*\*/` | `**bold**` |
+| 斜体 | `/\*(.+?)\*/` | `*italic*` |
+| 删除线 | `/~~(.+?)~~/` | `~~strike~~` |
+
+---
+
+## Element Conversion Matrix
+
+### 标题映射 (Pixel-Based)
+
+| Element | Markdown | BBCode Output |
+|---------|----------|---------------|
+| **H1** | `# text` | `[size=150][color=#2196F3][b]text[/b][/color][/size]` |
+| **H2** | `## text` | `[size=120][color=#2196F3][b]text[/b][/color][/size]` |
+| **H3** | `### text` | `[size=100][color=#333][b]text[/b][/color][/size]` |
+| **H4** | `#### text` | `[b]text[/b]` |
+| **H5** | `##### text` | `[b]text[/b]` |
+| **H6** | `###### text` | `[b]text[/b]` |
+
+### 文本样式映射
+
+| Element | Markdown | BBCode |
+|---------|----------|--------|
+| **Bold** | `**text**` | `[b]text[/b]` |
+| **Italic** | `*text*` | `[i]text[/i]` |
+| **Bold+Italic** | `***text***` | `[b][i]text[/i][/b]` |
+| **Strike** | `~~text~~` | `[s]text[/s]` |
+| **Highlight** | `==text==` | `[color=yellow]text[/color]` |
+| **Code (inline)** | `` `text` `` | 保持原样 |
+
+### 块级元素映射
+
+| Element | Markdown | BBCode |
+|---------|----------|--------|
+| **Code Block** | ` ```lang\ncode\n``` ` | `[code]code[/code]` |
+| **Quote** | `> text` | `[quote]text[/quote]` |
+| **HR** | `---` | `---` (保持 Markdown) |
+| **List Item** | `- text` | `• text` |
+| **Paragraph** | `text\n\ntext` | `text\n\ntext` |
+
+### 链接和媒体映射
+
+| Element | Markdown | BBCode |
+|---------|----------|--------|
+| **Link** | `[text](url)` | `[url=url]text[/url]` |
+| **Image** | `![alt](url)` | `[img]url[/img]` |
+
+---
+
+## Callout Mapping
+
+### 类型到样式映射
+
+| Callout Type | Color | Icon | Label |
+|--------------|-------|------|-------|
+| note | #2196F3 | 📝 | 注意 |
+| info | #2196F3 | ℹ️ | 信息 |
+| tip | #4CAF50 | 💡 | 提示 |
+| hint | #4CAF50 | 💡 | 提示 |
+| success | #4CAF50 | ✅ | 成功 |
+| check | #4CAF50 | ✅ | 完成 |
+| done | #4CAF50 | ✅ | 完成 |
+| warning | #FF9800 | ⚠️ | 警告 |
+| caution | #FF9800 | ⚠️ | 注意 |
+| attention | #FF9800 | ⚠️ | 注意 |
+| danger | #F44336 | ❌ | 危险 |
+| error | #F44336 | ❌ | 错误 |
+| bug | #F44336 | 🐛 | Bug |
+| example | #9C27B0 | 📋 | 示例 |
+| question | #FF9800 | ❓ | 问题 |
+| help | #FF9800 | ❓ | 帮助 |
+| faq | #FF9800 | ❓ | FAQ |
+| quote | gray | 💬 | 引用 |
+| cite | gray | 💬 | 引用 |
+| abstract | #2196F3 | 📄 | 摘要 |
+| summary | #2196F3 | 📄 | 摘要 |
+| tldr | #2196F3 | 📄 | 摘要 |
+| todo | #FF9800 | 📋 | 待办 |
+| important | #F44336 | ⭐ | 重要 |
+
+### Callout 输出模板
+
+```bbcode
+[quote]
+[size=100][color={color}][b]{icon} {title}[/b][/color][/size]
+
+{content}
+[/quote]
+```
+
+---
+
+## Unsupported Elements
+
+### 不支持转换的元素
+
+| 元素 | 原因 | 降级方案 |
+|------|------|----------|
+| 表格 | BBCode 表格支持有限 | 转为代码块或列表 |
+| 脚注 | 不支持 | 转为括号注释 `(注: ...)` |
+| 数学公式 | 不支持 | 保留原始文本 |
+| 嵌入内容 | 不支持 | 转为链接 |
+| 任务列表 | 复选框不支持 | 转为普通列表 `☐`/`☑` |
+
+### 降级示例
+
+**表格**:
+```
+| A | B |
+|---|---|
+| 1 | 2 |
+
+→ 降级为:
+
+A: 1
+B: 2
+```
+
+**脚注**:
+```
+文本[^1]
+
+[^1]: 脚注内容
+
+→ 降级为:
+
+文本 (注: 脚注内容)
+```
+
+**任务列表**:
+```
+- [ ] 待办
+- [x] 已完成
+
+→ 降级为:
+
+☐ 待办
+☑ 已完成
+```
+
+---
+
+## Validation Rules
+
+### 转换验证
+
+- [ ] 所有 H1-H3 使用像素值 size (150/120/100)
+- [ ] 未使用 `[align]` 标签
+- [ ] 未使用 `[hr]` 标签
+- [ ] 分隔线保持 `---`
+- [ ] Callout 正确识别并转换
+- [ ] 颜色值使用 hex 格式
--- a/.claude/skills/text-formatter/specs/format-rules.md
+++ b/.claude/skills/text-formatter/specs/format-rules.md
@@ -0,0 +1,260 @@
+# Format Conversion Rules
+
+BBCode + Markdown 混合格式转换规则（论坛优化）。
+
+## When to Use
+
+| Phase | Usage | Section |
+|-------|-------|---------|
+| Phase 3 | 格式转换 | All sections |
+
+---
+
+## Core Principles
+
+### 1. Pixel-Based Sizing
+
+**重要**: 使用像素值而非 1-7 级别
+
+| 元素 | Size (px) | 说明 |
+|------|-----------|------|
+| 主标题 (H1) | 150 | 文档标题 |
+| 章节标题 (H2) | 120 | 主要章节 |
+| 子标题 (H3) | 100 | 子章节 |
+| 正文 | (默认) | 不指定 size |
+| 备注/灰色 | 80 | 脚注、元数据 |
+
+### 2. Supported Tags Only
+
+**支持的 BBCode 标签**:
+- `[size=N]` - 字号（像素值）
+- `[color=X]` - 颜色（hex 或名称）
+- `[b]`, `[i]`, `[s]` - 粗体、斜体、删除线
+- `[quote]` - 引用块
+- `[code]` - 代码块
+- `[url]`, `[img]` - 链接、图片
+- `[list]`, `[*]` - 列表
+
+**禁止使用的标签**:
+- `[align]` - 不渲染，显示为文本
+- `[hr]` - 不渲染，使用 Markdown `---`
+- `[table]` - 支持有限，避免使用
+- HTML 标签 (`<div>`, `<span>`) - 不支持
+
+### 3. Markdown as Separator
+
+分隔线使用 Markdown 语法：`---`
+
+---
+
+## Element Conversion Rules
+
+### 标题转换
+
+| Markdown | BBCode Output |
+|----------|---------------|
+| `# H1` | `[size=150][color=#2196F3][b]H1[/b][/color][/size]` |
+| `## H2` | `[size=120][color=#2196F3][b]H2[/b][/color][/size]` |
+| `### H3` | `[size=100][color=#333][b]H3[/b][/color][/size]` |
+| `#### H4+` | `[b]H4[/b]` (不加 size) |
+
+### 文本样式
+
+| Markdown | BBCode |
+|----------|--------|
+| `**bold**` | `[b]bold[/b]` |
+| `*italic*` | `[i]italic[/i]` |
+| `***both***` | `[b][i]both[/i][/b]` |
+| `~~strike~~` | `[s]strike[/s]` |
+| `==highlight==` | `[color=yellow]highlight[/color]` |
+
+### 代码
+
+| Markdown | BBCode |
+|----------|--------|
+| `` `inline` `` | 保持原样或 `[color=#9C27B0]inline[/color]` |
+| ` ```code``` ` | `[code]code[/code]` |
+
+### 链接和图片
+
+| Markdown | BBCode |
+|----------|--------|
+| `[text](url)` | `[url=url]text[/url]` |
+| `![alt](url)` | `[img]url[/img]` |
+
+### 列表
+
+```
+Markdown:
+- item 1
+- item 2
+  - nested
+
+BBCode:
+• item 1
+• item 2
+  • nested
+```
+
+注意：使用 `•` 符号而非 `[list][*]`，因为部分论坛渲染有问题。
+
+### 引用
+
+```
+Markdown:
+> quote text
+
+BBCode:
+[quote]
+quote text
+[/quote]
+```
+
+---
+
+## Callout (标注) 转换
+
+### Obsidian Callout 语法
+
+```markdown
+> [!TYPE] 可选标题
+> 内容行 1
+> 内容行 2
+```
+
+### 支持的 Callout 类型
+
+| Type | Color | Icon | 中文标签 |
+|------|-------|------|----------|
+| note, info | #2196F3 | 📝 | 注意 / 信息 |
+| tip, hint | #4CAF50 | 💡 | 提示 |
+| success, check, done | #4CAF50 | ✅ | 成功 |
+| warning, caution, attention | #FF9800 | ⚠️ | 警告 |
+| danger, error, bug | #F44336 | ❌ | 危险 / 错误 |
+| example | #9C27B0 | 📋 | 示例 |
+| question, help, faq | #FF9800 | ❓ | 问题 |
+| quote, cite | gray | 💬 | 引用 |
+| abstract, summary, tldr | #2196F3 | 📄 | 摘要 |
+
+### Callout 转换模板
+
+```bbcode
+[quote]
+[size=100][color={color}][b]{icon} {title}[/b][/color][/size]
+
+{content}
+[/quote]
+```
+
+**示例**:
+
+```markdown
+> [!WARNING] 注意事项
+> 这是警告内容
+```
+
+转换为：
+
+```bbcode
+[quote]
+[size=100][color=#FF9800][b]⚠️ 注意事项[/b][/color][/size]
+
+这是警告内容
+[/quote]
+```
+
+### 可折叠 Callout
+
+Obsidian 支持 `> [!NOTE]+` (展开) 和 `> [!NOTE]-` (折叠)。
+
+由于 BBCode 不支持折叠，统一转换为普通 quote。
+
+---
+
+## Color Palette
+
+### 语义颜色
+
+| 语义 | Hex | 使用场景 |
+|------|-----|----------|
+| Primary | #2196F3 | 标题、链接、信息 |
+| Success | #4CAF50 | 成功、提示、特性 |
+| Warning | #FF9800 | 警告、注意 |
+| Error | #F44336 | 错误、危险 |
+| Purple | #9C27B0 | 示例、代码 |
+| Gray | gray | 备注、元数据 |
+| Dark | #333 | 子标题 |
+
+### 颜色使用规则
+
+1. **标题颜色**: H1/H2 使用 #2196F3，H3 使用 #333
+2. **Callout 颜色**: 根据类型使用语义颜色
+3. **备注颜色**: 使用 gray
+4. **强调颜色**: 根据语义选择（成功用绿色，警告用橙色）
+
+---
+
+## Spacing Rules
+
+### 空行控制
+
+| 元素 | 前空行 | 后空行 |
+|------|--------|--------|
+| 标题 | 1 | 1 |
+| 段落 | 0 | 1 |
+| 列表 | 0 | 1 |
+| 代码块 | 1 | 1 |
+| Callout | 1 | 1 |
+| 分隔线 `---` | 1 | 1 |
+
+### 示例输出结构
+
+```bbcode
+[size=150][color=#2196F3][b]文档标题[/b][/color][/size]
+
+[size=80][color=gray]作者 | 日期[/color][/size]
+
+---
+
+[size=120][color=#2196F3][b]第一章节[/b][/color][/size]
+
+正文内容...
+
+[quote]
+[size=100][color=#4CAF50][b]💡 提示[/b][/color][/size]
+
+提示内容
+[/quote]
+
+---
+
+[size=120][color=#2196F3][b]第二章节[/b][/color][/size]
+
+更多内容...
+
+---
+
+[size=80][color=gray]— 全文完 —[/color][/size]
+```
+
+---
+
+## Quality Checklist
+
+### 转换完整性
+
+- [ ] 所有标题使用像素值 size
+- [ ] 未使用 `[align]` 或 `[hr]`
+- [ ] 分隔线使用 `---`
+- [ ] Callout 正确转换为 quote
+- [ ] 颜色符合语义规范
+- [ ] 空行控制正确
+
+### 常见错误
+
+| 错误 | 正确做法 |
+|------|----------|
+| `[size=5]` | `[size=120]` |
+| `[align=center]` | 删除，默认左对齐 |
+| `[hr]` | 使用 `---` |
+| `<div class="...">` | 删除 HTML 标签 |