feat(editor): add themed callouts and desktop command boundary

2026-09-06 11:33:19 +08:00
parent fcc319d5e1
commit 415efc4444
26 changed files with 759 additions and 13 deletions
@@ -16,6 +16,7 @@ tags: 演示, 入门
 | 03 Mermaid 图表集 | 六种常用图型、主题颜色和大图查看 |
 | 04 星灯项目资料 | 全文搜索、知识库问答与引用定位 |
 | 05 Skill 与 Plugin 操作样例 | 扩展安装、选区命令和只读笔记检查 |
+| [06 警告框与提示框](06%20警告框与提示框.md) | 类型与别名、标题、折叠、嵌套和主题配色 |

 ## 工作区操作

@@ -0,0 +1,150 @@
+---
+title: 警告框与提示框演示
+tags: 演示, Markdown, 警告框, 主题
+---
+
+# 警告框与提示框
+
+本页展示 GitHub 警告框和 Obsidian 提示框的类型、标题、折叠、嵌套及正文格式。打开工作区写作模式查看效果；切换源码模式查看原始语法。
+
+## 五种常用警告框
+
+> [!NOTE]
+> 记录补充信息：这份笔记中的内容都是功能演示，不会执行代码或调用模型。
+
+> [!TIP] 小技巧：快速插入
+> 点击编辑器顶部的“提示框”选择器，选择类型后替换模板内容。
+
+> [!IMPORTANT] 保存与显示状态
+> 点击标题展开或收起，只改变本次显示状态。要修改默认状态，请在源码中的类型标记后添加 `+` 或 `-`。
+
+> [!WARNING] 修改前保留原文
+> 在演示笔记中练习时，可以先复制一段内容；需要恢复时使用撤销。
+
+> [!CAUTION] 需要重点关注的说明
+> `CAUTION` 与 `WARNING` 使用同一警告配色。提示框是笔记内容，不是应用报错弹窗。
+
+## 更多类型
+
+> [!ABSTRACT] 本页摘要
+> 类型区分语义，标题说明重点，正文保留详细信息。
+
+> [!INFO] 环境信息
+> 警告框的边框、标题和背景随主题变化。
+
+> [!TODO] 待办
+> - [ ] 展开下方折叠示例。
+> - [ ] 切换深色主题。
+> - [ ] 保存后重新打开本页。
+
+> [!SUCCESS] 已完成
+> 本段展示成功状态，不代表自动测试或实际任务已经完成。
+
+> [!QUESTION] 可以嵌套吗？
+> 可以。增加一级引用符号即可在提示框中嵌入另一个提示框。
+
+> [!FAILURE] 未达到预期
+> 示例：资料中缺少日期，需要补充后再归档。
+
+> [!DANGER] 风险提示
+> 示例：不要把唯一一份原始资料直接覆盖为整理结果。
+
+> [!BUG] 问题记录
+> 示例：发现显示异常时，记录主题、操作步骤和对应 Markdown 源码。
+
+> [!EXAMPLE] 示例
+> 将提示内容写成一句明确的说明，比只写“注意”更容易理解。
+
+> [!QUOTE] 摘录
+> 一条笔记既要保留结论，也要保留形成结论的依据。
+
+## 默认展开与默认折叠
+
+> [!TIP]+ 默认展开：点击标题试试
+> 类型后的 `+` 表示默认展开。点击标题可收起，再次点击可展开。
+
+> [!WARNING]- 默认折叠：点击查看内容
+> 你已经展开了这段说明。类型后的 `-` 表示重新渲染时默认收起。
+>
+> 正文可以包含 **加粗**、*斜体*、~~删除线~~ 和 `行内代码`。
+
+## 嵌套与混合格式
+
+> [!INFO]+ 一次资料整理
+> 先整理来源，再检查缺漏。
+>
+> 1. 收集原始资料。
+> 2. 按主题分组。
+> 3. 为尚未确认的内容添加说明。
+>
+> > [!SUCCESS] 已收集
+> > 原始笔记、会议纪要和参考链接已放入同一文件夹。
+>
+> > [!WARNING]- 尚待确认
+> > 一条资料缺少发布日期，需要补充来源。
+>
+> | 项目 | 状态 |
+> | --- | --- |
+> | 原始资料 | 已归档 |
+> | 日期核对 | 待补充 |
+>
+> ```python
+> notes = ["原始资料", "整理结果"]
+> print(len(notes))
+> ```
+>
+> 行内公式：$a^2 + b^2 = c^2$。
+
+## 类型别名
+
+别名不区分大小写。下面的表格列出兼容关系。
+
+| 类型 | 别名 |
+| --- | --- |
+| abstract | summary、tldr |
+| tip | hint |
+| success | check、done |
+| question | help、faq |
+| warning | caution、attention |
+| failure | fail、missing |
+| danger | error |
+| quote | cite |
+
+> [!summary] 摘要别名
+> 这段使用 `summary`，外观与 `abstract` 一致。
+
+> [!check] 成功别名
+> 这段使用 `check`，外观与 `success` 一致。
+
+> [!custom-demo] 未知类型的回退
+> 自定义类型暂时使用 note 外观，源文件中的类型名仍然保留。
+
+## 语法对照
+
+以下围栏中的内容应当保持为代码，不渲染成警告框。
+
+```markdown
+> [!NOTE] 自定义标题
+> 正文内容。
+
+> [!WARNING]- 默认折叠
+> 点击标题查看正文。
+
+> [!TIP]+ 默认展开
+> 默认可见的正文。
+```
+
+普通行内代码也保持原样：`[!WARNING]`。
+
+> 这是一段普通引用，没有提示类型标记，因此不应显示为警告框。
+
+## 主题与保存体验清单
+
+- [ ] 在浅色、深色、护眼主题下区分信息、成功、警告与危险颜色。
+- [ ] 使用纸间时光，查看纸张虚线边框和嵌套层次。
+- [ ] 使用 Ocean Blue 与 Midnight Purple，检查标题和正文是否清晰。
+- [ ] 点击折叠标题，并使用 Tab、Enter 或空格体验键盘操作。
+- [ ] 在源码模式修改一个类型或标题，再切回写作模式。
+- [ ] 保存并重新打开，确认类型、标题、正文与默认折叠状态保持一致。
+
+这是一份手动体验清单，未勾选不表示功能失败。桌面容器的原生格式快捷键与元数据转换仍属于第三阶段规划。
@@ -41,6 +41,7 @@
 - [扩展安装持久化与社区包开发说明](development/扩展安装持久化与社区包开发说明.md)
 - [模型上下文管理](development/模型上下文管理.md)
 - [Markdown 渲染检查](development/Markdown渲染检查.md)
+- [警告框与桌面编辑命令开发说明](development/警告框与桌面编辑命令开发说明.md)
 - [主题组件覆盖检查](development/主题组件覆盖检查.md)
 - [第二阶段补充验收工具](development/第二阶段补充验收工具.md)

@@ -21,7 +21,9 @@

 桌面客户端顶部菜单栏的 **段落 → 导入为笔记属性…** 预留元数据格式导入功能，与标题、正文、列表等段落操作归组。它处理笔记内容中的元数据，不是主题包安装入口。

-建议稳定的前端命令标识为 `editor.import-note-properties`，仅为设计标识，尚未注册为 Tauri IPC。原生菜单和编辑器命令面板应分发同一命令，避免两套转换逻辑。快捷键待第三阶段统一分配，不抢占现有编辑快捷键。
+稳定的前端命令标识为 `editor.import-note-properties`，已进入前端 v1 命令目录，但属性转换处理器与 Tauri IPC 尚未实现。原生菜单和编辑器命令面板应分发同一命令，避免两套转换逻辑。快捷键待第三阶段统一分配，不抢占现有编辑快捷键。
+
+Markdown 格式（含警告框）与元数据共用 `editorCommandService` 的能力查询和命令分发接口，详见 [警告框与桌面编辑命令开发说明](../development/警告框与桌面编辑命令开发说明.md)。Host 根据 supported / enabled 显隐或禁用菜单，不能把已预留的命令 ID 当作已可执行能力；原生快捷键不绕过活动文档、只读和冲突检查。

 ### 2.2 输入与转换规则

@@ -30,7 +30,9 @@
 | 自定义字号 span | 装饰渲染 | 清理后 HTML | 既有字号标记测试 |
 | 原始 HTML | 编辑器按自身 HTML 节点规则保留 | 清理后展示，脚本及事件属性移除 | 新增安全 HTML 测试 |

-源码模式展示 Markdown 原文，不隐藏反引号、星号和围栏。脚注、定义列表、Wiki 双链、Obsidian callout、图表以外的自定义围栏等未作为独立渲染扩展启用，不在“已支持”范围内。
+源码模式展示 Markdown 原文，不隐藏反引号、星号和围栏。脚注、定义列表、Wiki 双链、图表以外的自定义围栏等未作为独立渲染扩展启用，不在“已支持”范围内。
+
+2026-09-06 补充：GitHub alerts 与 Obsidian callout 已在工作区和静态预览接入，包含常用类型/别名、自定义标题、嵌套与折叠。语法、命令接口与验证方法见 [警告框与桌面编辑命令开发说明](警告框与桌面编辑命令开发说明.md)。

 自动检查覆盖解析、DOM 输出、部分编辑交互、保存往返和主题变量。尚未完成所有浏览器、所有输入法及每个主题的逐页截图比对；不能据此宣称像素级视觉验收通过。测试使用隔离样例，没有修改用户笔记。

@@ -0,0 +1,90 @@
+# 警告框与桌面编辑命令开发说明
+
+日期：2026-09-06。范围为前端渲染与命令边界；不包含 Tauri IPC、原生菜单或系统级快捷键注册。
+
+## 1. 格式与渲染
+
+使用引用块语法。GitHub 的 NOTE、TIP、IMPORTANT、WARNING、CAUTION 均可渲染；同时支持 Obsidian 的常用类型、别名、标题、嵌套与折叠。
+
+```markdown
+> [!WARNING]- 自定义标题
+> 提示正文，支持 **粗体**、`行内代码`、列表等 Markdown。
+>
+> > [!TIP]+ 嵌套提示
+> > 展开内容
+```
+
+无 `+` / `-` 时不可折叠；`+` 默认展开，`-` 默认折叠。点击折叠只改变本次显示状态，不自动改写源文件中的默认状态。标题作为文本显示，不执行 HTML。未知类型使用 note 外观并保留类型名。
+
+| 规范类型 | 兼容别名 |
+| --- | --- |
+| note | — |
+| abstract | summary、tldr |
+| info、todo | — |
+| tip | hint |
+| important | — |
+| success | check、done |
+| question | help、faq |
+| warning | caution、attention |
+| failure | fail、missing |
+| danger | error |
+| bug、example | — |
+| quote | cite |
+
+工作区顶部“提示框”选择器可插入模板。编辑器保留原生 blockquote 文档节点，以 NodeView 展示标题与折叠按钮，装饰隐藏标记；选区进入标记时显示原文以便修改。序列化仅取消引用首行提示标记的转义，避免保存后退回普通引用。代码中的标记不转换。写作模式会规范化 Markdown 转义；需要永久展示字面标记时使用行内代码或围栏代码。
+
+静态预览使用 marked 的 blockquote renderer，折叠使用原生 details / summary，内容仍经过 DOMPurify。两个入口共享 `callouts.ts` 与 `callouts.css`；颜色继承主题的 info、warning、success、error、surface 和 text 变量，不另存固定浅色配色。因此已有主题和符合主题规范的导入主题均可继承。
+
+## 2. 桌面命令边界 v1
+
+入口：`frontend/src/services/editorCommandService.ts`。
+
+- `editorCommandVersion`：当前版本 1。
+- `getEditorCommandCapabilities()`：返回每个稳定命令 ID 的 supported 与 enabled。预留 ID 不等于已经实现。
+- `executeEditorCommand(id, params?)`：返回 `{ ok: true }` 或 `{ ok: false, reason }`。reason 为 unsupported、unavailable、invalid-params、failed。
+- `registerEditorCommands(target)`：由活动编辑器注册处理器，返回注销函数。旧组件注销不清除替代组件的注册。
+
+成功表示处理器接受并执行了命令；具体格式操作仍遵循编辑器的选区规则。命令不直接写磁盘，变更进入既有脏状态、撤销与自动保存链路。无活动文件、源码模式、只读、冲突、编辑器加载中或文件已切换时禁用当前处理器。
+
+| 已接入 ID（统一加 editor. 前缀） | params |
+| --- | --- |
+| bold、italic、ordered-list、bullet-list、inline-code、code-block、inline-math、math-block、paragraph | 无 |
+| heading | 整数 1–6 |
+| font-size | 有限数值 8–96，单位 px；作用于选区 |
+| insert-markdown | 非空 Markdown 字符串，最多 100000 字符 |
+| callout | `{ type, title?, body?, fold? }`；fold 为空串、+ 或 -；标题不可换行 |
+
+目录还预留删除线、任务列表、引用、Mermaid、链接、图片、表格、分隔线、硬换行、引用式链接、HTML、撤销/重做，以及 `editor.import-note-properties`、`editor.metadata.edit`、`editor.metadata.title`、`editor.metadata.tags`。这些单独的处理器尚未接入，返回 unsupported；现阶段复杂格式可通过 insert-markdown 插入。元数据不得通过普通正文插入接口冒充属性导入。
+
+第三阶段由 Host 将原生菜单/快捷键映射到上述 ID。快捷键表需支持平台差异与用户改键，过滤表单、输入法组合与弹窗焦点；不要重复绑定浏览器和 Milkdown 已有按键。宿主只能调用允许的命令，不执行任意脚本。元数据处理器须按已有桌面需求完成无损 YAML 合并、版本检查、冲突提示及属性/正文一并撤销后才可标记 supported。
+
+## 3. 验证方法
+
+在 frontend 运行：
+
+```sh
+npm run test -- src/utils/callouts.spec.ts src/services/editorCommandService.spec.ts src/features/editor/VisualMarkdownEditor.spec.ts
+npm run build
+```
+
+- callouts：逐个类型与别名、大小写、嵌套、默认折叠、空正文、未知类型、标题注入、普通引用和代码排除。
+- 编辑器：初始解析、直接输入标记、按钮折叠、序列化往返、命令参数校验和冲突禁用。
+- 命令服务：能力查询、无活动目标、未知命令、未实现命令和旧目标注销隔离。
+- 启动开发服务器，访问 `/tests/visual/callouts.html?theme=paper-moments`；依次替换 light、dark、sepia、ocean-blue、midnight-purple。左右分别是工作区和静态预览，核对边框、标题、正文、嵌套与折叠；缩窄窗口检查换行。
+
+此项不宣称支持所有 Markdown 方言；脚注、定义列表、Wiki 双链及 `:::` 等其他警告框语法仍需独立扩展。原生快捷键和元数据转换属于第三阶段验收。
+
+## 4. 六主题适配补充
+
+主题新增 `--color-callout-info/success/warning/danger/important/quote` 六个语义变量。每种类型继续使用共享组件结构，标题、边框与淡色背景取同一语义配色。未知导入主题未定义这些变量时，默认继承其已有状态色。折叠标题补齐悬停、键盘焦点与不可折叠标题状态。
+
+| 主题 | 本次版本 | 外观 |
+| --- | --- | --- |
+| light、dark、sepia | 1.2.0 | 分别使用浅色、深色、暖色配色 |
+| paper-moments | 1.7.0 | 纸张边框、虚线内描边和轻投影；嵌套取消重复投影 |
+| ocean-blue | 1.4.0 | 海蓝与低亮度状态色 |
+| midnight-purple | 2.2.0 | 深色表面与高亮度状态色 |
+
+修正工作区基础选择器覆盖类型颜色的问题，默认色使用低优先级规则。社区预览 iframe 同步载入共享 callouts CSS，并展示 14 种规范类型、默认展开/折叠及嵌套样例。主题安装与预览使用同一 CSS 来源，纸间时光下载包的清单和样式同步更新；已安装旧版可通过主题页既有更新入口升级。
+
+验证增加六主题 × 六配色在实际 8% 混色背景上的标题对比度检查（至少 4.5:1），工作区选择器覆盖回归，以及六主题预览结构检查。此检查针对不透明 sRGB 配色，不代替每个平台的字体与截图验收。
@@ -41,6 +41,8 @@ pnpm dev

 编辑器使用 Milkdown/Crepe 与 CodeMirror 6；Markdown 展示使用 marked、DOMPurify 和 Shiki。Provider logo 位于 `src/assets/providers`，授权与来源说明随目录保存。

+工作区和静态预览支持 GitHub alerts / Obsidian callout 的类型、别名、标题、嵌套与折叠。桌面快捷键使用预留的 v1 编辑命令边界，尚未接入 Tauri 原生快捷键与元数据转换处理器；见 [警告框与桌面编辑命令开发说明](../docs/development/警告框与桌面编辑命令开发说明.md)。
+
 语言设置会即时更新主导航、页面标题和各功能页面，并同步更新文档与编辑器的 `lang`。拼写检查使用浏览器或桌面 WebView 提供的本地词典，开关会即时作用于可视化 Markdown、源码编辑器以及普通文本输入；JSON、密码等结构化或敏感输入保持关闭。

 ## 数据边界
@@ -1,6 +1,6 @@
 theme_id: paper-moments
 name: 纸间时光 · Paper Moments
-version: 1.6.2
+version: 1.7.0
 author: NotesAgent
 description: 奶油纸张、手帐虚线与粉蓝胶带，把每天的灵感好好收藏。
 min_app_version: 0.2.0
@@ -9,6 +9,12 @@ css_entry: theme.css
 license: MIT
 ---
 [data-theme="paper-moments"] {
+  --color-callout-info: #406b7b;
+  --color-callout-success: #536f43;
+  --color-callout-warning: #875f25;
+  --color-callout-danger: #a34e42;
+  --color-callout-important: #805c7e;
+  --color-callout-quote: #6e6053;
  color-scheme: light;
  --color-background-primary: #faf7ee;
  --color-background-secondary: #f3eee3;
@@ -322,3 +328,15 @@ license: MIT
 /* Nested choices retain a quiet paper border without repeating tape/shadows. */
 [data-theme="paper-moments"] .surface-nested { border: 1px dashed #c5b9a7; background: #fffdf5; border-radius: 6px; }
 [data-theme="paper-moments"] .surface-nested.selected { border-color: var(--color-accent-primary); background: var(--color-accent-soft); }
+
+/* Callout paper: no tape over titles, no repeated shadows in nested blocks. */
+[data-theme="paper-moments"] .markdown-callout,
+[data-theme="paper-moments"] .milkdown .ProseMirror blockquote.markdown-callout {
+  border-radius: 10px 3px 10px 3px;
+  outline: 1px dashed color-mix(in srgb, var(--callout-color) 30%, transparent);
+  outline-offset: -6px;
+  box-shadow: 3px 3px 0 color-mix(in srgb, var(--callout-color) 12%, transparent);
+  padding: 14px 18px;
+}
+[data-theme="paper-moments"] .markdown-callout .markdown-callout { box-shadow: none; }
+[data-theme="paper-moments"] .markdown-callout > .callout-title { font-family: Georgia, 'Noto Serif SC', 'Songti SC', SimSun, serif; }
@@ -13,6 +13,8 @@ import { useThemeStore } from '@/stores/theme'
 import { codeBlockConfig } from '@milkdown/kit/component/code-block'
 import { EditorView as CodeMirror } from '@codemirror/view'
 import { renderMarkdown } from '@/utils/markdown'
+import { useEditorStore } from '@/stores/editor'
+import { executeEditorCommand } from '@/services/editorCommandService'

 type EditorComponent = { getEditor: () => Editor | undefined }

@@ -51,6 +53,45 @@ afterEach(() => {
 })

 describe('VisualMarkdownEditor formatting toolbars', () => {
+  it('renders and folds callouts without losing portable Markdown on serialization', async () => {
+    const source = '> [!WARNING]- 注意\n>\n> **正文**\n>\n> > [!TIP] 内层\n> > 内容'
+    const wrapper = mount(VisualMarkdownEditor, { props: { initialContent: source }, attachTo: document.body })
+    mounted.push(wrapper)
+    const editor = await waitForEditor(wrapper)
+    expect(wrapper.findAll('.markdown-callout')).toHaveLength(2)
+    expect(wrapper.get('.markdown-callout').attributes('data-collapsed')).toBe('true')
+    await wrapper.get('.callout-title').trigger('click')
+    expect(wrapper.get('.markdown-callout').attributes('data-collapsed')).toBe('false')
+    const markdown = editor.action(getMarkdown())
+    expect(markdown.trim()).toBe(source)
+  })
+  it('dispatches native-ready commands through editor transactions and rejects invalid parameters', async () => {
+    useEditorStore().currentFilePath = 'test.md'
+    const wrapper = mount(VisualMarkdownEditor, { props: { initialContent: 'text' }, attachTo: document.body })
+    mounted.push(wrapper)
+    const editor = await waitForEditor(wrapper)
+    expect(await executeEditorCommand('editor.heading', 8)).toEqual({ ok: false, reason: 'invalid-params' })
+    expect(await executeEditorCommand('editor.heading', 2)).toEqual({ ok: true })
+    expect(editor.action(getMarkdown())).toContain('## text')
+    expect(await executeEditorCommand('editor.callout', { type: 'tip', body: '**test**' })).toEqual({ ok: true })
+    expect(wrapper.find('.markdown-callout').exists()).toBe(true)
+    useEditorStore().saveStatus = 'conflict'
+    expect(await executeEditorCommand('editor.bold')).toEqual({ ok: false, reason: 'unavailable' })
+  })
+  it('keeps code examples as ordinary quotes and renders newly typed markers', async () => {
+    const wrapper = mount(VisualMarkdownEditor, { props: { initialContent: '> `[!NOTE]`\n\n> text' }, attachTo: document.body })
+    mounted.push(wrapper)
+    const editor = await waitForEditor(wrapper)
+    expect(wrapper.find('.markdown-callout').exists()).toBe(false)
+    editor.action(ctx => {
+      const view = ctx.get(editorViewCtx)
+      let position = 0
+      view.state.doc.descendants((node, pos) => { if (node.isText && node.text === 'text') position = pos })
+      view.dispatch(view.state.tr.insertText('[!TIP]', position, position + 4))
+    })
+    expect(wrapper.find('.markdown-callout').exists()).toBe(true)
+    expect(editor.action(getMarkdown())).toContain('[!TIP]')
+  })
  it('renders the supported format matrix and preserves inline code', async () => {
    const source = ['# H1','## H2','### H3','#### H4','##### H5','###### H6',
      '正文 **粗体** *斜体* ~~删除~~ `s` 与 ``a`b``', '> 引用', '- 项目\n  - 子项', '1. 第一\n2. 第二',
@@ -28,7 +28,9 @@ import {
  wrapInHeadingCommand,
  wrapInOrderedListCommand,
 } from '@milkdown/kit/preset/commonmark'
-import { commandsCtx, editorViewCtx } from '@milkdown/kit/core'
+import { commandsCtx, editorViewCtx, parserCtx } from '@milkdown/kit/core'
+import { Slice } from '@milkdown/kit/prose/model'
+import { registerEditorCommands, type CommandHandler, type EditorCommandId } from '@/services/editorCommandService'
 import { TextSelection } from '@milkdown/kit/prose/state'
 import { callCommand } from '@milkdown/kit/utils'
 import AppIcon from '@/components/common/AppIcon.vue'
@@ -37,6 +39,8 @@ import { useSettingsStore } from '@/stores/settings'
 import { useThemeStore } from '@/stores/theme'
 import { applyMarkdownFontSize, fontSizeMarkdownPlugin } from './fontSizeMarkdown'
 import { inlineCodeInputPlugin } from './inlineCodeInput'
+import { calloutPlugin, configureCalloutSerialization } from './calloutPlugin'
+import { calloutTypes } from '@/utils/callouts'
 import { t } from '@/i18n'
 import '@milkdown/crepe/theme/common/style.css'
 import '@milkdown/crepe/theme/frame.css'
@@ -67,6 +71,61 @@ const fontSizeInput = ref(16)
 let crepe: Crepe | null = null
 let disposeLanguagePicker: (() => void) | undefined
 let disposeCodeLabels: (() => void) | undefined
+let disposeCommands: (() => void) | undefined
+let disposed = false
+
+function insertMarkdown(source: string) {
+  crepe?.editor.action(ctx => {
+    const doc = ctx.get(parserCtx)(source)
+    if (!doc) throw new Error('Invalid Markdown')
+    const view = ctx.get(editorViewCtx)
+    view.dispatch(view.state.tr.replaceSelection(new Slice(doc.content, 0, 0)).scrollIntoView())
+    view.focus()
+  })
+}
+
+function insertCallout(event: Event) {
+  const select = event.target as HTMLSelectElement
+  if (select.value) insertMarkdown(`> [!${select.value.toUpperCase()}]\n> ${t('提示内容', 'Callout content')}`)
+  select.value = ''
+}
+
+function installCommands() {
+  const targetPath = editorStore.currentFilePath
+  const handlers: Partial<Record<EditorCommandId, CommandHandler>> = {}
+  const toolbar: ToolbarCommand[] = ['bold', 'italic', 'ordered-list', 'bullet-list', 'inline-code', 'code-block', 'inline-math', 'math-block']
+  for (const command of toolbar) handlers[`editor.${command}`] = () => { runCommand(command); return { ok: true } }
+  handlers['editor.paragraph'] = () => { crepe!.editor.action(callCommand(turnIntoTextCommand.key)); return { ok: true } }
+  handlers['editor.heading'] = params => {
+    if (!Number.isInteger(params) || Number(params) < 1 || Number(params) > 6) return { ok: false, reason: 'invalid-params' }
+    crepe!.editor.action(callCommand(wrapInHeadingCommand.key, Number(params)))
+    return { ok: true }
+  }
+  handlers['editor.font-size'] = params => {
+    if (typeof params !== 'number' || !Number.isFinite(params) || params < 8 || params > 96) return { ok: false, reason: 'invalid-params' }
+    fontSizeInput.value = params
+    applyFontSizeValue()
+    return { ok: true }
+  }
+  handlers['editor.insert-markdown'] = params => {
+    if (typeof params !== 'string' || !params.trim() || params.length > 100000) return { ok: false, reason: 'invalid-params' }
+    insertMarkdown(params)
+    return { ok: true }
+  }
+  handlers['editor.callout'] = params => {
+    if (!params || typeof params !== 'object') return { ok: false, reason: 'invalid-params' }
+    const { type, title = '', body = '', fold = '' } = params as Record<string, unknown>
+    if (typeof type !== 'string' || !/^[\w-]{1,64}$/.test(type) || typeof title !== 'string' || /[\r\n]/.test(title)
+      || typeof body !== 'string' || !['', '+', '-'].includes(String(fold)) || title.length + body.length > 100000) return { ok: false, reason: 'invalid-params' }
+    insertMarkdown(`> [!${type}]${fold} ${title}\n${body.split(/\r?\n/).map(line => `> ${line}`).join('\n')}`)
+    return { ok: true }
+  }
+  disposeCommands = registerEditorCommands({
+    available: () => !loading.value && !!crepe && editorStore.mode === 'wysiwyg' && editorStore.saveStatus !== 'conflict'
+      && !!targetPath && targetPath === editorStore.currentFilePath && crepe.editor.action(ctx => ctx.get(editorViewCtx).editable),
+    handlers,
+  })
+}
 const diagramPreviews = new Map<string, { source: string; apply: (value: HTMLElement) => void }>()
 function renderDiagram(source: string, apply: (value: HTMLElement) => void) {
  for (const [id, entry] of diagramPreviews) {
@@ -251,6 +310,8 @@ onMounted(async () => {
  })))
  crepe.editor.use(fontSizeMarkdownPlugin)
  crepe.editor.use(inlineCodeInputPlugin)
+  crepe.editor.use(calloutPlugin)
+  crepe.editor.config(configureCalloutSerialization)
  crepe.on((listener) => {
    listener.markdownUpdated((_ctx, markdown, previousMarkdown) => {
      // 忽略编辑器初始化/回显事件，防止无内容变化时触发自动保存循环。
@@ -265,6 +326,7 @@ onMounted(async () => {
  if (editorRoot.value) disposeCodeLabels = installCodeBlockLabels(editorRoot.value)
  applyProofingPreferences()
  loading.value = false
+  if (!disposed) installCommands()
 })

 watch([() => settingsStore.spellCheck, () => settingsStore.language], applyProofingPreferences)
@@ -282,7 +344,7 @@ watch(() => editorStore.headingRequest, request => {
  })
 })

-onBeforeUnmount(() => { diagramPreviews.clear(); disposeCodeLabels?.(); disposeLanguagePicker?.(); void crepe?.destroy() })
+onBeforeUnmount(() => { disposed = true; disposeCommands?.(); diagramPreviews.clear(); disposeCodeLabels?.(); disposeLanguagePicker?.(); void crepe?.destroy() })

 defineExpose({ getEditor: () => crepe?.editor })
 </script>
@@ -324,6 +386,12 @@ defineExpose({ getEditor: () => crepe?.editor })
      <button type="button" :title="t('行内公式', 'Inline formula')" :aria-label="t('行内公式', 'Inline formula')" @pointerdown.prevent="runCommand('inline-math')"><span class="math-glyph">ƒx</span></button>
      <button type="button" :title="t('公式块', 'Formula block')" :aria-label="t('公式块', 'Formula block')" @pointerdown.prevent="runCommand('math-block')"><span class="math-glyph">∑</span></button>
      <button type="button" :title="t('插入链接', 'Insert link')" :aria-label="t('插入链接', 'Insert link')" @pointerdown.prevent="applyLink"><AppIcon :icon="Link" :size="17" /></button>
+      <label class="toolbar-select">
+        <select :aria-label="t('插入警告框', 'Insert callout')" @change="insertCallout">
+          <option value="">{{ t('提示框', 'Callout') }}</option>
+          <option v-for="(_, type) in calloutTypes" :key="type" :value="type">{{ type }}</option>
+        </select>
+      </label>
    </div>
    <div v-if="loading" class="editor-loading">{{ t('正在加载编辑器…', 'Loading editor…') }}</div>
    <div class="milkdown-host" :class="{ loading }">
@@ -0,0 +1,89 @@
+import { $prose } from '@milkdown/kit/utils'
+import { Plugin } from '@milkdown/kit/prose/state'
+import { Decoration, DecorationSet } from '@milkdown/kit/prose/view'
+import { parseCallout } from '@/utils/callouts'
+import '@/styles/callouts.css'
+import { remarkStringifyOptionsCtx, type Editor } from '@milkdown/kit/core'
+
+export const configureCalloutSerialization: Parameters<Editor['config']>[0] = ctx => {
+  ctx.update(remarkStringifyOptionsCtx, options => ({
+    ...options,
+    handlers: { ...options.handlers, blockquote(node, _parent, state, info) {
+      const exit = state.enter('blockquote')
+      const tracker = state.createTracker(info)
+      tracker.move('> ')
+      tracker.shift(2)
+      const result = state.indentLines(state.containerFlow(node, tracker.current()), (line, _index, blank) => `>${blank ? '' : ' '}${line}`)
+      exit()
+      // Only remove escaping from a leading callout marker, never body literals.
+      return result.replace(/^(> )\\\[!([\w-]+)\\?\]/, '$1[!$2]')
+    } },
+  }))
+}
+
+// Keep native blockquotes in the document: typing, undo and Markdown serialization
+// remain Milkdown transactions; the view never rewrites a user's callout source.
+export const calloutPlugin = $prose(() => new Plugin({
+  props: {
+    decorations(state) {
+      const decorations: Decoration[] = []
+      state.doc.descendants((node, position) => {
+        if (node.type.name !== 'blockquote' || node.firstChild?.type.name !== 'paragraph' || node.firstChild.firstChild?.marks.length) return
+        const callout = parseCallout(node.firstChild.textBetween(0, node.firstChild.content.size, '\n', '\n'))
+        if (!callout) return
+        const from = position + 2
+        const to = from + callout.markerLength
+        const editing = state.selection.from <= to && state.selection.to >= from
+        decorations.push(Decoration.inline(from, to, { class: editing ? 'callout-marker-editing' : 'callout-marker' }))
+      })
+      return DecorationSet.create(state.doc, decorations)
+    },
+    nodeViews: {
+      blockquote(initialNode) {
+        const dom = document.createElement('blockquote')
+        const header = document.createElement('button')
+        header.type = 'button'
+        header.className = 'callout-title'
+        header.contentEditable = 'false'
+        const contentDOM = document.createElement('div')
+        contentDOM.className = 'callout-body'
+        dom.append(header, contentDOM)
+        let signature = ''
+        let foldable = false
+        const update = (node: typeof initialNode) => {
+          if (node.type.name !== 'blockquote') return false
+          const callout = node.firstChild?.type.name === 'paragraph' && !node.firstChild.firstChild?.marks.length
+            ? parseCallout(node.firstChild.textBetween(0, node.firstChild.content.size, '\n', '\n')) : null
+          dom.className = callout ? 'markdown-callout' : ''
+          header.hidden = !callout
+          foldable = !!callout?.fold
+          header.disabled = !foldable
+          if (callout) {
+            dom.dataset.callout = callout.type
+            const next = `${callout.name}:${callout.fold}`
+            if (signature !== next) dom.dataset.collapsed = String(callout.fold === '-')
+            signature = next
+            header.textContent = `${foldable ? (dom.dataset.collapsed === 'true' ? '▸ ' : '▾ ') : ''}${callout.title}`
+            if (foldable) header.setAttribute('aria-expanded', String(dom.dataset.collapsed !== 'true'))
+            else header.removeAttribute('aria-expanded')
+          } else {
+            delete dom.dataset.callout
+            delete dom.dataset.collapsed
+            signature = ''
+          }
+          return true
+        }
+        let current = initialNode
+        header.onclick = () => {
+          if (!foldable) return
+          dom.dataset.collapsed = String(dom.dataset.collapsed !== 'true')
+          update(current)
+        }
+        update(initialNode)
+        return { dom, contentDOM, update(node) { current = node; return update(node) },
+          stopEvent: event => header.contains(event.target as Node),
+          ignoreMutation: mutation => mutation.type !== 'selection' && !contentDOM.contains(mutation.target) }
+      },
+    },
+  },
+}))
@@ -4,6 +4,7 @@ import { mount } from '@vue/test-utils'
 // Vitest disables CSS by default, including CSS raw imports. Load the real files here.
 vi.mock('@/styles/features.css?raw', async () => ({ default: (await import('node:fs')).readFileSync(process.cwd() + '/src/styles/features.css', 'utf8') }))
 vi.mock('@/styles/tokens.css?raw', async () => ({ default: (await import('node:fs')).readFileSync(process.cwd() + '/src/styles/tokens.css', 'utf8') }))
+vi.mock('@/styles/callouts.css?raw', async () => ({ default: (await import('node:fs')).readFileSync(process.cwd() + '/src/styles/callouts.css', 'utf8') }))
 import CommunityThemePreview from './CommunityThemePreview.vue'
 import { mockCommunityThemes } from '@/services/themePackageService'
 const themes = [...['light','dark','sepia'].map(theme_id => ({theme_id,name:theme_id,builtin:true})), ...mockCommunityThemes.map(t => ({...t,builtin:false}))]
@@ -15,6 +16,10 @@ it.each(themes)('previews shared component states safely for $theme_id', theme =
    const doc = new DOMParser().parseFromString(iframe.attributes('srcdoc')!, 'text/html')
    expect(doc.documentElement.dataset.theme).toBe(theme.theme_id)
    expect(doc.querySelector('script')).toBeNull()
+    expect(doc.querySelectorAll('.specimen-callouts > aside.markdown-callout')).toHaveLength(14)
+    expect(doc.querySelector('.specimen-callouts > details[open]')).not.toBeNull()
+    expect(doc.querySelector('.specimen-callouts > details:not([open])')).not.toBeNull()
+    expect(doc.querySelector('style')!.textContent).toContain('.callout-title:focus-visible')
    expect(doc.querySelector('meta[http-equiv="Content-Security-Policy"]')?.getAttribute('content')).toContain("default-src 'none'")
    for (const selector of ['input.input','input:disabled','textarea.textarea','select.select','.ui-disclosure[open]','.ui-disclosure:not([open])','.button-primary:disabled','.badge.success','.error-banner','.specimen-markdown code','.specimen-markdown table','.specimen-chart','.specimen-long']) expect(doc.querySelector(selector), selector).not.toBeNull()
    expect(doc.querySelector('style')!.textContent).toContain('.button-primary:hover')
@@ -5,6 +5,8 @@ import { t } from '@/i18n'
 import { getCommunityThemePreviewCss, mockCommunityThemes } from '@/services/themePackageService'
 import tokensCss from '@/styles/tokens.css?raw'
 import featuresCss from '@/styles/features.css?raw'
+import calloutsCss from '@/styles/callouts.css?raw'
+import { calloutTypes } from '@/utils/callouts'
 import specimenHtml from './themeSpecimen.html?raw'

 const props = defineProps<{ themeId: string; name?: string; css?: string }>()
@@ -20,7 +22,7 @@ const previewDocument = computed(() => {
  policy.content = "default-src 'none'; style-src 'unsafe-inline'; img-src data:; font-src data:; base-uri 'none'; form-action 'none'"
  doc.head.append(policy)
  const style = doc.createElement('style')
-  style.textContent = `${tokensCss}\n${featuresCss}\n${props.css ?? getCommunityThemePreviewCss(props.themeId)}\nhtml { height:100% !important; overflow-y:auto !important; overflow-x:hidden !important; overscroll-behavior:contain; } body { height:auto !important; min-height:100%; overflow:visible !important; margin:0; padding:24px; background:var(--color-background-primary); color:var(--color-text-primary); font:16px/1.6 system-ui; } article { min-width:0; } .theme-specimen { display:grid; gap:16px; margin-top:20px; } .surface-nested { padding:12px; border:1px solid var(--color-border-default); border-radius:var(--radius-md); } .specimen-markdown { overflow:auto; } .specimen-markdown code { background:var(--color-code-background, var(--color-background-secondary)); color:var(--color-code-text, var(--color-text-primary)); padding:3px 6px; border-radius:4px; } .specimen-markdown pre { padding:12px; background:var(--color-background-secondary); } .specimen-markdown blockquote { border-left:3px solid var(--color-accent-primary); padding-left:12px; } .specimen-markdown table { width:100%; border-collapse:collapse; } .specimen-markdown td,.specimen-markdown th { padding:8px; border:1px solid var(--color-border-default); } .specimen-markdown th { background:var(--color-markdown-table-header); } .specimen-chart > div { display:flex; align-items:flex-end; gap:12px; height:100px; border-bottom:1px solid var(--color-border-default); } .specimen-chart span { width:36px; } .specimen-long { overflow-wrap:anywhere; } @media(max-width:480px) { body { padding:12px; } .form-grid { grid-template-columns:minmax(0,1fr); } }`
+  style.textContent = `${tokensCss}\n${featuresCss}\n${calloutsCss}\n${props.css ?? getCommunityThemePreviewCss(props.themeId)}\nhtml { height:100% !important; overflow-y:auto !important; overflow-x:hidden !important; overscroll-behavior:contain; } body { height:auto !important; min-height:100%; overflow:visible !important; margin:0; padding:24px; background:var(--color-background-primary); color:var(--color-text-primary); font:16px/1.6 system-ui; } article { min-width:0; } .theme-specimen { display:grid; gap:16px; margin-top:20px; } .surface-nested { padding:12px; border:1px solid var(--color-border-default); border-radius:var(--radius-md); } .specimen-markdown { overflow:auto; } .specimen-markdown code { background:var(--color-code-background, var(--color-background-secondary)); color:var(--color-code-text, var(--color-text-primary)); padding:3px 6px; border-radius:4px; } .specimen-markdown pre { padding:12px; background:var(--color-background-secondary); } .specimen-markdown blockquote { border-left:3px solid var(--color-accent-primary); padding-left:12px; } .specimen-markdown table { width:100%; border-collapse:collapse; } .specimen-markdown td,.specimen-markdown th { padding:8px; border:1px solid var(--color-border-default); } .specimen-markdown th { background:var(--color-markdown-table-header); } .specimen-chart > div { display:flex; align-items:flex-end; gap:12px; height:100px; border-bottom:1px solid var(--color-border-default); } .specimen-chart span { width:36px; } .specimen-long { overflow-wrap:anywhere; } @media(max-width:480px) { body { padding:12px; } .form-grid { grid-template-columns:minmax(0,1fr); } }`

  doc.head.append(style)
  const article = doc.createElement('article')
@@ -33,6 +35,22 @@ const previewDocument = computed(() => {
  const button = doc.createElement('button'); button.className = 'button-primary'; button.textContent = t('示例按钮', 'Example button')
  journal.append(text)
  const specimen = doc.createElement('template'); specimen.innerHTML = specimenHtml
+  const callouts = doc.createElement('section'); callouts.className = 'specimen-callouts'
+  const caption = doc.createElement('h2'); caption.textContent = t('警告框与提示框', 'Alerts and callouts'); callouts.append(caption)
+  for (const type of Object.keys(calloutTypes)) {
+    const block = doc.createElement('aside'); block.className = 'markdown-callout'; block.dataset.callout = type
+    const title = doc.createElement('div'); title.className = 'callout-title'; title.textContent = type
+    const body = doc.createElement('div'); body.className = 'callout-body'; body.textContent = t('提示正文：检查文字、边框与主题配色。', 'Callout body: check text, borders and theme colors.')
+    block.append(title, body); callouts.append(block)
+  }
+  for (const open of [false, true]) {
+    const details = doc.createElement('details'); details.className = 'markdown-callout'; details.dataset.callout = 'warning'; details.open = open
+    const summary = doc.createElement('summary'); summary.className = 'callout-title'; summary.textContent = t('可折叠警告框', 'Collapsible callout')
+    const body = doc.createElement('div'); body.className = 'callout-body'
+    const nested = doc.createElement('aside'); nested.className = 'markdown-callout'; nested.dataset.callout = 'tip'; nested.textContent = t('嵌套提示内容', 'Nested callout content')
+    body.append(nested); details.append(summary, body); callouts.append(details)
+  }
+  specimen.content.append(callouts)
  article.append(header, journal, button, specimen.content); doc.body.append(article)
  return '<!doctype html>' + doc.documentElement.outerHTML
 })
@@ -96,7 +96,7 @@ it.each(mockCommunityThemes)('previews uninstalled $theme_id using its actual CS

 it('offers and applies the paper theme update without discarding the active theme', async () => {
  const store = useThemeStore()
-  const old = await inspectThemePackage(paperPackage.replace('version: 1.6.2', 'version: 1.6.1'))
+  const old = await inspectThemePackage(paperPackage.replace('version: 1.7.0', 'version: 1.6.1'))
  await store.installThemeFromInspection(old.manifest, old.css)
  store.applyTheme('paper-moments')
  wrapper = mount(ThemesView, { global: { stubs: { MarkdownContent: true } } })
@@ -105,6 +105,6 @@ it('offers and applies the paper theme update without discarding the active them
  const card = wrapper.findAll('article.theme-card').find(item => item.text().includes('Paper Moments'))!
  await card.findAll('button').find(button => button.text() === '更新')!.trigger('click')
  await flushPromises()
-  expect(store.allThemes.find(theme => theme.theme_id === 'paper-moments')?.version).toBe('1.6.2')
+  expect(store.allThemes.find(theme => theme.theme_id === 'paper-moments')?.version).toBe('1.7.0')
  expect(document.getElementById('theme-style-paper-moments')!.textContent).toContain('.surface-nested')
 })
@@ -0,0 +1,25 @@
+import { afterEach, expect, it, vi } from 'vitest'
+import { executeEditorCommand, registerEditorCommands, getEditorCommandCapabilities } from './editorCommandService'
+let dispose: (() => void) | undefined
+afterEach(() => dispose?.())
+it('reports unsupported, disabled and invalid commands without side effects', async () => {
+  expect(await executeEditorCommand('editor.bold')).toEqual({ ok: false, reason: 'unavailable' })
+  const handler = vi.fn(() => ({ ok: true as const }))
+  let available = false
+  dispose = registerEditorCommands({ available: () => available, handlers: { 'editor.bold': handler } })
+  expect(getEditorCommandCapabilities().find(item => item.id === 'editor.bold')).toMatchObject({ supported: true, enabled: false })
+  await executeEditorCommand('editor.bold')
+  expect(handler).not.toHaveBeenCalled()
+  available = true
+  expect(await executeEditorCommand('editor.bold')).toEqual({ ok: true })
+  expect(await executeEditorCommand('editor.metadata.edit')).toEqual({ ok: false, reason: 'unsupported' })
+  expect(await executeEditorCommand('arbitrary-command')).toEqual({ ok: false, reason: 'unsupported' })
+})
+it('old editor disposal cannot unregister the replacement editor', async () => {
+  const old = registerEditorCommands({ available: () => true, handlers: {} })
+  dispose = registerEditorCommands({ available: () => true, handlers: { 'editor.bold': () => ({ ok: true }) } })
+  old()
+  expect(await executeEditorCommand('editor.bold')).toEqual({ ok: true })
+  dispose()
+  expect(await executeEditorCommand('editor.bold')).toEqual({ ok: false, reason: 'unavailable' })
+})
@@ -0,0 +1,33 @@
+/** Versioned frontend boundary for future native menus/shortcuts; no Tauri IPC yet. */
+export const editorCommandVersion = 1
+export const editorCommandIds = [
+  'editor.bold', 'editor.italic', 'editor.strikethrough', 'editor.inline-code',
+  'editor.paragraph', 'editor.heading', 'editor.bullet-list', 'editor.ordered-list',
+  'editor.task-list', 'editor.blockquote', 'editor.callout', 'editor.code-block',
+  'editor.inline-math', 'editor.math-block', 'editor.mermaid', 'editor.link',
+  'editor.image', 'editor.table', 'editor.horizontal-rule', 'editor.hard-break',
+  'editor.font-size', 'editor.insert-markdown', 'editor.import-note-properties',
+  'editor.metadata.edit', 'editor.metadata.title', 'editor.metadata.tags',
+  'editor.reference-link', 'editor.html', 'editor.undo', 'editor.redo',
+] as const
+export type EditorCommandId = typeof editorCommandIds[number]
+export type CommandResult = { ok: true } | { ok: false; reason: 'unsupported' | 'unavailable' | 'invalid-params' | 'failed' }
+export type CommandHandler = (params: unknown) => CommandResult | Promise<CommandResult>
+type Target = { available: () => boolean; handlers: Partial<Record<EditorCommandId, CommandHandler>> }
+let active: Target | undefined
+
+export function registerEditorCommands(target: Target) {
+  active = target
+  return () => { if (active === target) active = undefined }
+}
+export function getEditorCommandCapabilities() {
+  return editorCommandIds.map(id => ({ id, supported: !!active?.handlers[id], enabled: !!active?.handlers[id] && active.available() }))
+}
+export async function executeEditorCommand(id: string, params?: unknown): Promise<CommandResult> {
+  if (!(editorCommandIds as readonly string[]).includes(id)) return { ok: false, reason: 'unsupported' }
+  const target = active
+  if (!target || !target.available()) return { ok: false, reason: 'unavailable' }
+  const handler = target.handlers[id as EditorCommandId]
+  if (!handler) return { ok: false, reason: 'unsupported' }
+  try { return await handler(params) } catch { return { ok: false, reason: 'failed' } }
+}
@@ -361,7 +361,7 @@ export const mockCommunityThemes: ThemeManifest[] = [
  {
    theme_id: 'ocean-blue',
    name: 'Ocean Blue',
-    version: '1.3.1',
+    version: '1.4.0',
    author: 'community',
    description: '宁静的海洋蓝色主题，适合长时间阅读',
    min_app_version: '0.2.0',
@@ -373,7 +373,7 @@ export const mockCommunityThemes: ThemeManifest[] = [
  {
    theme_id: 'midnight-purple',
    name: 'Midnight Purple',
-    version: '2.1.1',
+    version: '2.2.0',
    author: 'night-owl',
    description: '深紫色暗夜主题，适合编码',
    min_app_version: '0.2.0',
@@ -464,6 +464,12 @@ export function getCommunityThemePreviewCss(themeId: string): string {
  return buildCommunityThemeCss(themeId, t.is_dark) + `
 [data-theme="${themeId}"] {
  color-scheme: ${t.is_dark ? 'dark' : 'light'};
+  --color-callout-info: ${t.is_dark ? '#9dbbff' : '#126589'};
+  --color-callout-success: ${t.is_dark ? '#a7d58c' : '#267049'};
+  --color-callout-warning: ${t.is_dark ? '#efc886' : '#885c13'};
+  --color-callout-danger: ${t.is_dark ? '#ff9caf' : '#b13d4d'};
+  --color-callout-important: ${t.is_dark ? '#d4afff' : '#7050a3'};
+  --color-callout-quote: ${t.is_dark ? '#b0b9dd' : '#53697d'};
  --color-text-inverse: ${t.is_dark ? '#1a1b26' : '#ffffff'};
  --color-text-disabled: color-mix(in srgb, var(--color-text-primary) 45%, var(--color-surface-primary));
  --color-background-overlay: ${t.is_dark ? '#000000a6' : '#00000073'};
@@ -5,9 +5,9 @@ import * as themePkg from '@/services/themePackageService'
 import { t } from '@/i18n'

 const builtinThemes = (): ThemeConfig[] => [
-  { theme_id: 'light', name: t('浅色', 'Light'), version: '1.1.1', description: t('默认浅色主题', 'Default light theme'), is_dark: false, builtin: true, code_theme: 'github-light' },
-  { theme_id: 'dark', name: t('深色', 'Dark'), version: '1.1.1', description: t('默认深色主题', 'Default dark theme'), is_dark: true, builtin: true, code_theme: 'github-dark' },
-  { theme_id: 'sepia', name: t('护眼', 'Sepia'), version: '1.1.1', description: t('护眼暖色调', 'Warm, low-glare theme'), is_dark: false, builtin: true, code_theme: 'github-light' },
+  { theme_id: 'light', name: t('浅色', 'Light'), version: '1.2.0', description: t('默认浅色主题', 'Default light theme'), is_dark: false, builtin: true, code_theme: 'github-light' },
+  { theme_id: 'dark', name: t('深色', 'Dark'), version: '1.2.0', description: t('默认深色主题', 'Default dark theme'), is_dark: true, builtin: true, code_theme: 'github-dark' },
+  { theme_id: 'sepia', name: t('护眼', 'Sepia'), version: '1.2.0', description: t('护眼暖色调', 'Warm, low-glare theme'), is_dark: false, builtin: true, code_theme: 'github-light' },
 ]

 export type CodeBlockThemePreference = 'auto' | 'github-light' | 'github-dark'
@@ -0,0 +1,28 @@
+/* Semantic tokens inherit every installed theme, including imported themes. */
+:where(.markdown-callout) { --callout-color: var(--color-callout-info, var(--color-info)); }
+.markdown-callout, .milkdown .ProseMirror blockquote.markdown-callout {
+  border: 1px solid color-mix(in srgb, var(--callout-color) 35%, transparent);
+  border-inline-start: 4px solid var(--callout-color);
+  border-radius: var(--radius-md, 8px);
+  background: color-mix(in srgb, var(--callout-color) 8%, var(--color-surface-primary, var(--paper, #fffdf7)));
+  color: var(--color-text-primary, var(--ink, inherit));
+  margin: 12px 0; padding: 12px 16px; min-width: 0;
+}
+.markdown-callout[data-callout='warning'], .markdown-callout[data-callout='question'] { --callout-color: var(--color-callout-warning, var(--color-warning)); }
+.markdown-callout[data-callout='danger'], .markdown-callout[data-callout='failure'], .markdown-callout[data-callout='bug'] { --callout-color: var(--color-callout-danger, var(--color-error)); }
+.markdown-callout[data-callout='success'], .markdown-callout[data-callout='tip'] { --callout-color: var(--color-callout-success, var(--color-success)); }
+.markdown-callout[data-callout='abstract'], .markdown-callout[data-callout='important'], .markdown-callout[data-callout='example'] { --callout-color: var(--color-callout-important, var(--color-accent-secondary)); }
+.markdown-callout[data-callout='quote'] { --callout-color: var(--color-callout-quote, var(--color-text-secondary)); }
+.markdown-callout[data-callout='todo'] { --callout-color: var(--color-callout-info, var(--color-accent-primary)); }
+.markdown-callout > .callout-title { color: var(--callout-color); font-weight: 700; line-height: 1.5; overflow-wrap: anywhere; }
+.markdown-callout > button.callout-title { background: transparent; border: 0; padding: 0; width: 100%; text-align: start; cursor: pointer; }
+.markdown-callout > button.callout-title:disabled { opacity: 1; cursor: default; color: var(--callout-color); }
+.markdown-callout > summary.callout-title { cursor: pointer; }
+.markdown-callout > :is(button, summary).callout-title:focus-visible { outline: 2px solid var(--color-border-focus); outline-offset: 4px; border-radius: var(--radius-sm); }
+.markdown-callout > :is(button:not(:disabled), summary).callout-title:hover { text-decoration: underline; text-underline-offset: 3px; }
+.markdown-callout .callout-body { min-width: 0; overflow-wrap: anywhere; }
+.markdown-callout .callout-body > :last-child { margin-bottom: 0; }
+.markdown-callout[data-collapsed='true'] > .callout-body { display: none; }
+.callout-marker { display: none; }
+.callout-title[hidden] { display: none !important; }
+.callout-marker-editing { opacity: .65; font-family: monospace; }
@@ -22,3 +22,47 @@ it.each(mockCommunityThemes)('provides interaction and Markdown colors in $theme
  }
  expect(css).toContain(`color-scheme: ${theme.is_dark ? 'dark' : 'light'}`)
 })
+
+const calloutThemes = ['light', 'dark', 'sepia', ...mockCommunityThemes.map(theme => theme.theme_id)]
+const calloutTones = ['info', 'success', 'warning', 'danger', 'important', 'quote']
+it.each(calloutThemes)('keeps callout headings readable against tinted surfaces in %s', themeId => {
+  const doc = document.implementation.createHTMLDocument('theme contrast')
+  const style = doc.createElement('style')
+  style.textContent = files['styles/tokens.css'] ?? files['styles\\tokens.css']!
+  style.textContent += getCommunityThemePreviewCss(themeId)
+  doc.head.append(style)
+  const values = new Map<string, string>()
+  for (const rule of Array.from(doc.styleSheets[0]!.cssRules) as CSSStyleRule[]) {
+    if (![':root', `[data-theme='${themeId}']`, `[data-theme="${themeId}"]`].includes(rule.selectorText)) continue
+    for (const name of ['--color-surface-primary', ...calloutTones.map(tone => `--color-callout-${tone}`)]) {
+      const value = rule.style.getPropertyValue(name).trim()
+      if (value) values.set(name, value)
+    }
+  }
+  const rgb = (hex: string) => [1, 3, 5].map(offset => parseInt(hex.slice(offset, offset + 2), 16) / 255)
+  const luminance = (color: number[]) => color.map(value => value <= .04045 ? value / 12.92 : ((value + .055) / 1.055) ** 2.4).reduce((sum, value, index) => sum + value * [.2126, .7152, .0722][index]!, 0)
+  const surface = rgb(values.get('--color-surface-primary')!)
+  for (const tone of calloutTones) {
+    const hex = values.get(`--color-callout-${tone}`)!
+    expect(hex).toMatch(/^#[\da-f]{6}$/i)
+    const ink = rgb(hex)
+    const background = surface.map((value, index) => value * .92 + ink[index]! * .08)
+    const first = luminance(ink), second = luminance(background)
+    expect((Math.max(first, second) + .05) / (Math.min(first, second) + .05), tone).toBeGreaterThanOrEqual(4.5)
+  }
+})
+
+it('preserves warning and success colors inside the editor selector cascade', () => {
+  const style = document.createElement('style')
+  style.textContent = readFileSync(join(root, 'styles/callouts.css'), 'utf8')
+  document.head.append(style)
+  const host = document.createElement('div')
+  host.className = 'milkdown'
+  host.innerHTML = '<div class="ProseMirror"><blockquote class="markdown-callout" data-callout="warning"></blockquote><blockquote class="markdown-callout" data-callout="success"></blockquote></div>'
+  document.body.append(host)
+  try {
+    const blocks = host.querySelectorAll('blockquote')
+    expect(getComputedStyle(blocks[0]!).getPropertyValue('--callout-color')).toContain('--color-callout-warning')
+    expect(getComputedStyle(blocks[1]!).getPropertyValue('--callout-color')).toContain('--color-callout-success')
+  } finally { host.remove(); style.remove() }
+})
@@ -1,4 +1,11 @@
 :root {
+  /* Callout heading colors also serve as borders; keep text readable on tint. */
+  --color-callout-info: var(--color-info);
+  --color-callout-success: var(--color-success);
+  --color-callout-warning: var(--color-warning);
+  --color-callout-danger: var(--color-error);
+  --color-callout-important: var(--color-accent-secondary);
+  --color-callout-quote: var(--color-text-secondary);
  /* Background */
  --color-background-primary: #ffffff;
  --color-background-secondary: #f7f8fa;
@@ -117,7 +124,22 @@
  --statusbar-height: 28px;
 }

+[data-theme='light'] {
+  --color-callout-info: #175da6;
+  --color-callout-success: #236b3b;
+  --color-callout-warning: #855700;
+  --color-callout-danger: #ad2935;
+  --color-callout-important: #7443ad;
+  --color-callout-quote: #59636e;
+}
+
 [data-theme='dark'] {
+  --color-callout-info: #8bbdff;
+  --color-callout-success: #80ce93;
+  --color-callout-warning: #efc66f;
+  --color-callout-danger: #ff9b9b;
+  --color-callout-important: #c8a5ff;
+  --color-callout-quote: #abb6c2;
  --color-background-primary: #0d1117;
  --color-background-secondary: #161b22;
  --color-background-tertiary: #21262d;
@@ -168,6 +190,12 @@
 }

 [data-theme='sepia'] {
+  --color-callout-info: #396578;
+  --color-callout-success: #496b3b;
+  --color-callout-warning: #805918;
+  --color-callout-danger: #a04438;
+  --color-callout-important: #785476;
+  --color-callout-quote: #746653;
  --color-background-primary: #fbf3df;
  --color-background-secondary: #f4e8ca;
  --color-background-tertiary: #eadbb8;
@@ -0,0 +1,39 @@
+// @vitest-environment jsdom
+import { describe, expect, it } from 'vitest'
+import { calloutTypes, parseCallout } from './callouts'
+import { renderMarkdown } from './markdown'
+
+describe('callouts', () => {
+  for (const [type, aliases] of Object.entries(calloutTypes)) {
+    for (const alias of aliases) it(`renders ${alias}`, async () => {
+      const root = document.createElement('div')
+      root.innerHTML = await renderMarkdown(`> [!${alias.toUpperCase()}] 标题\n> **正文** 与 \`code\`\n>\n> - 条目`)
+      expect(root.querySelector('.markdown-callout')?.getAttribute('data-callout')).toBe(type)
+      expect(root.querySelector('.callout-title')?.textContent).toBe('标题')
+      expect(root.querySelector('strong')?.textContent).toBe('正文')
+      expect(root.querySelector('li')?.textContent).toBe('条目')
+    })
+  }
+  it('supports folding, nesting, unknown types, empty bodies and safe titles', async () => {
+    const root = document.createElement('div')
+    root.innerHTML = await renderMarkdown('> [!WARNING]- 外层\n>\n> > [!tip]+ 内层\n> > 内容\n\n> [!custom] <img src=x onerror=alert(1)>\n\n> [!NOTE]')
+    expect(root.querySelector('details')?.hasAttribute('open')).toBe(false)
+    expect(root.querySelector('details details')?.hasAttribute('open')).toBe(true)
+    expect(root.querySelectorAll('.markdown-callout')).toHaveLength(4)
+    expect(root.querySelector('img')).toBeNull()
+    expect(root.textContent).toContain('<img src=x onerror=alert(1)>')
+  })
+  it('renders the editor serialization of nested folded callouts', async () => {
+    const root = document.createElement('div')
+    root.innerHTML = await renderMarkdown('> [!WARNING]- 注意\n>\n> **正文**\n>\n> > [!TIP] 内层\n> > 内容\n')
+    expect(root.querySelectorAll('.markdown-callout')).toHaveLength(2)
+    expect(root.querySelector('strong')?.textContent).toBe('正文')
+  })
+  it('does not convert ordinary quotes, inline code, escaped markers or fenced examples', async () => {
+    const root = document.createElement('div')
+    root.innerHTML = await renderMarkdown('> ordinary\n\n> \\[!NOTE]\n\n`[!TIP]`\n\n```text\n> [!WARNING]\n```')
+    expect(root.querySelector('.markdown-callout')).toBeNull()
+    expect(root.querySelectorAll('blockquote')).toHaveLength(2)
+    expect(parseCallout('prefix [!NOTE]')).toBeNull()
+  })
+})
@@ -0,0 +1,21 @@
+/** GitHub alerts and Obsidian callouts share the same portable Markdown syntax. */
+export const calloutTypes = {
+  note: ['note'], abstract: ['abstract', 'summary', 'tldr'], info: ['info'],
+  todo: ['todo'], tip: ['tip', 'hint'], important: ['important'], success: ['success', 'check', 'done'],
+  question: ['question', 'help', 'faq'], warning: ['warning', 'caution', 'attention'],
+  failure: ['failure', 'fail', 'missing'], danger: ['danger', 'error'], bug: ['bug'],
+  example: ['example'], quote: ['quote', 'cite'],
+} as const
+
+export function parseCallout(text: string) {
+  const match = /^\[!([\w-]+)\]([+-]?)[ \t]*([^\n]*)(?:\n|$)/.exec(text)
+  if (!match) return null
+  const name = match[1]!.toLowerCase()
+  const type = Object.entries(calloutTypes).find(([, aliases]) => (aliases as readonly string[]).includes(name))?.[0] ?? 'note'
+  return { name, type, title: match[3]!.trim() || name.charAt(0).toUpperCase() + name.slice(1),
+    fold: match[2] || null, markerLength: match[0].replace(/\n$/, '').length, body: text.slice(match[0].length) }
+}
+
+export function escapeCalloutTitle(text: string) {
+  return text.replace(/[&<>"']/g, character => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[character]!)
+}
@@ -9,6 +9,19 @@ import { renderMermaid } from '@/services/mermaidService'
 import { appendDiagramControls } from './diagramControls'
 import katex from 'katex'
 import 'katex/dist/katex.min.css'
+import { parseCallout, escapeCalloutTitle } from './callouts'
+import '@/styles/callouts.css'
+
+marked.use({ renderer: { blockquote(token) {
+  const callout = parseCallout(token.text)
+  if (!callout) return false
+  const title = escapeCalloutTitle(callout.title)
+  const body = marked.parse(callout.body, { async: false }) as string
+  const attributes = `class="markdown-callout" data-callout="${callout.type}"`
+  return callout.fold
+    ? `<details ${attributes}${callout.fold === '+' ? ' open' : ''}><summary class="callout-title">${title}</summary><div class="callout-body">${body}</div></details>`
+    : `<aside ${attributes}><div class="callout-title">${title}</div><div class="callout-body">${body}</div></aside>`
+} } })

 function mathHtml(source: string, displayMode: boolean) {
  const result = katex.renderToString(source, {displayMode, throwOnError:false, trust:false, maxExpand:1000, output:'html'})
@@ -6,5 +6,6 @@
 - `/tests/visual/index.html?case=dialog`：检查满视口遮罩、背景无法滚动、内部长内容可滚动、Tab 焦点限定、Escape 关闭与再次打开。
 - `/tests/visual/index.html?case=editor`：逐字输入行内代码；先输入两个反引号、向左移再填字；连续普通/软换行；输入法提交；选区替换；撤销/重做。编辑器单元测试另覆盖 Markdown 序列化往返。
 - `/tests/visual/mermaid-matrix.html`：真实 Mermaid（无渲染 mock）的 6 图型 × 6 主题矩阵。顶部报告检查结果；加 `?theme=paper-moments` 可查看单主题外观。
+- `/tests/visual/callouts.html?theme=paper-moments`：工作区与静态预览的警告框类型、嵌套和折叠对照；可切换上述六个主题，不读写用户笔记。

 运行自动回归：`pnpm test`。AppDialog 测试覆盖滚动锁引用计数、恢复焦点、禁止隐式关闭；主题预览矩阵覆盖六主题的实际共享 CSS、控件状态和 CSP/无脚本隔离。自动结构检查不代替浏览器截图、布局和对比度检查。
@@ -0,0 +1,21 @@
+<!doctype html><html><head><meta charset="utf-8"><title>警告框渲染验收</title></head>
+<body><div id="app"></div><script type="module">
+import { createApp, h } from 'vue';
+import { createPinia } from 'pinia';
+import Editor from '/src/features/editor/VisualMarkdownEditor.vue';
+import MarkdownContent from '/src/components/common/MarkdownContent.vue';
+import { calloutTypes } from '/src/utils/callouts.ts';
+import { getCommunityThemePreviewCss } from '/src/services/themePackageService.ts';
+import '/src/styles/tokens.css';
+import '/src/styles/features.css';
+const theme = new URLSearchParams(location.search).get('theme') || 'light';
+document.documentElement.dataset.theme = theme;
+const style = document.createElement('style');
+style.textContent = getCommunityThemePreviewCss(theme) || '';
+document.head.append(style);
+const source = Object.keys(calloutTypes).map(type => `> [!${type.toUpperCase()}] ${type} 提示\n> 正文 **粗体** 与 \`code\`\n>\n> - 列表项`).join('\n\n') + '\n\n> [!WARNING]- 折叠提示\n>\n> > [!TIP]+ 嵌套提示\n> > 点击展开后可见';
+createApp({ render: () => h('main', {style:'max-width:1200px;margin:auto;display:grid;grid-template-columns:repeat(auto-fit,minmax(320px,1fr));gap:24px'}, [
+  h('section', [h('h1', '工作区'), h(Editor, {initialContent:source})]),
+  h('section', [h('h1', '静态预览'), h(MarkdownContent, {source})]),
+]) }).use(createPinia()).mount('#app');
+</script></body></html>