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

日期：2026-09-06。范围为前端渲染与命令边界；不包含 Tauri IPC、原生菜单或系统级快捷键注册。

1. 格式与渲染

使用引用块语法。GitHub 的 NOTE、TIP、IMPORTANT、WARNING、CAUTION 均可渲染；同时支持 Obsidian 的常用类型、别名、标题、嵌套与折叠。

> [!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。editor.import-note-properties 默认使用 CmdOrCtrl+Alt+P，窗口保存使用 Ctrl/Cmd+S；撤销、重做等 Milkdown/CodeMirror 已有按键只在菜单中标示，不重复绑定。快捷键表需支持平台差异与用户改键，过滤输入法组合和不可用状态。宿主只能调用允许的命令，不执行任意脚本。元数据处理器须按已有桌面需求完成无损 YAML 合并、版本检查、冲突提示及属性/正文一并撤销后才可标记 supported。

3. 验证方法

在 frontend 运行：

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

5. 第三阶段桌面菜单接入

日期：2026-09-07。

无边框窗口的“文件 / 编辑 / 段落 / 格式 / 视图 / 主题 / 帮助”菜单使用 TitleBarMenu.vue 渲染。段落、格式、十四种警告框及快捷键标签集中定义在 editorMenu.ts；桌面生命周期的按键分发引用同一映射。加粗、斜体、撤销和重做继续由编辑器原生键位处理，避免顶层监听重复执行。菜单项通过 editorCommandService 的订阅接口随活动编辑器、模式和可用状态即时更新。

警告框使用二级菜单，支持方向键、Home、End、Esc、Tab 和子菜单左右键。菜单采用 menubar、menu、menuitem / menuitemradio 语义，主题颜色全部来自现有设计变量。

桌面 WebView 的 CSP 在 script-src 中仅增加 'wasm-unsafe-eval'，用于初始化 Shiki 的 Oniguruma WASM；普通 'unsafe-eval' 仍保持禁用。回归测试同时检查发行配置的 CSP 约束，以及真实挂载的 Milkdown 代码块在 GitHub Light / Dark 下生成多种 .shiki-token 颜色。

文件菜单承载新建根目录笔记/文件夹、切换知识库、返回工作区、刷新文件树、保存、导出、下载 Markdown 副本和关闭当前笔记。桌面端导出只保留在文件菜单，Web 端继续保留编辑器标题栏入口。视图菜单提供现有工作区、搜索、对话、智能体、任务、音视频、Skill、Plugin 和 MCP 页面入口；帮助菜单提供日志、Benchmark、社区与设置诊断。切换知识库前先等待当前笔记安全保存，成功打开后再清理旧知识库标签页。

Tauri 的 CmdOrCtrl+Alt+P accelerator 根据 editor.import-note-properties 与 editor.metadata.edit 的联合能力启用。源码模式执行属性导入，写作模式创建或聚焦元数据区域，避免原生禁用项在 Windows 上提前吞掉写作模式快捷键。

8.4 KiB Raw Permalink Blame History Unescape Escape