# 警告框与桌面编辑命令开发说明

日期：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 配色，不代替每个平台的字体与截图验收。