---
title: "Yeli 教程"
lang: zh-CN
description: "当前实验版本 · 2026-10-24 核对"
---

# Yeli 教程

可编辑 HTML 包含代码，仅打开可信来源文件。跨教程链接需把两份同语言手册放在一起。

## 功能总览与使用入口

Yeli 把 Markdown 正文、图片和阅读编辑环境装进一份 `.yeli.html`。下载可信文件后，用浏览器打开即可阅读；选择“编辑”开始写作。先用这页找到需要的能力，再进入对应教程。

### 先选你的目标

| 我现在要做什么                      | 从哪里开始                              |
| ----------------------------------- | --------------------------------------- |
| 第一次打开、写几句话并保存          | [快速开始](#第一次编辑与保存)             |
| 看懂工具栏、目录和右侧面板          | [认识工作区](#认识工作区)            |
| 查一个按键组合                      | [快捷键速查](#快捷键速查)            |
| 查所有命令和使用条件                | [完整命令参考](#完整命令参考)           |
| 学会议、长文或分享流程              | [工作流与最佳实践](#工作流与最佳实践) |
| 了解 Markdown、Agent 与 Yeli 的关系 | [为什么是 Yeli](#为什么是-yeli)           |

下表的“更多 → 保存”等写法，表示打开顶部末尾的“更多”后直接选择该项。文件、导出、视图、设置与帮助是菜单中的**分区标签**，不需要先进入同名子菜单。具体保存项会随浏览器能力变化。

### 打开与写作

| 功能                                 | 入口和操作                                      | 什么时候用 / 详解                                                       |
| ------------------------------------ | ----------------------------------------------- | ----------------------------------------------------------------------- |
| 离线打开                             | 下载 `.yeli.html`，用浏览器打开                 | 无账号、无需服务；附件预览不能编辑时先下载。[快速开始](#第一次编辑与保存) |
| 开始新文档                           | 复制可信起始文件；或“更多 → 打开文件”导入 `.md` | 一份文件对应一份文档，先保留当前工作。[快速开始](#第一次编辑与保存)       |
| 预览 / 编辑                          | 顶部“编辑”或“预览”                              | 阅读时隐藏写作工具，修改时直接操作正文。[工作区](#认识工作区)        |
| 编辑正文与标题                       | 编辑模式点击正文或顶部文档标题                  | 先写内容，再调整格式。[正文编辑](#正文与选区编辑)                          |
| 文字格式                             | 选中文字，使用浮动工具或快捷键                  | 粗体、斜体、删除线、行内代码、链接、清除格式。[选区编辑](#正文与选区编辑)  |
| 标题、列表、待办、引用、代码、分隔线 | 顶部“插入”；空白区块 `+` 或输入 `/`             | 用结构表达层级；标题支持 H1–H6。[区块与斜杠](#区块斜杠与模板)               |
| 区块转换、复制、删除                 | 目标区块的类型菜单                              | 调整已有内容；复杂区块只提供可安全执行的操作。[区块操作](#区块斜杠与模板)   |
| 会议记录模板                         | 插入菜单中的模板分组                            | 建立结论和下一步的骨架；日期和参与者需要填写。[模板](#区块斜杠与模板)       |
| 局部 Markdown 原文                   | 对应区块的“编辑区块原文”                        | 处理无法直接编辑的结构，提交前核对范围。[局部原文](#正文与选区编辑)        |

### 组织与查找

| 功能           | 入口和操作                                | 什么时候用 / 详解                                                                 |
| -------------- | ----------------------------------------- | --------------------------------------------------------------------------------- |
| 标题目录       | 左上角 Yeli 标志；`⌘/Ctrl + Shift + O`    | 按标题跳转、折叠层级；目录内筛选只找标题。[工作区](#认识工作区)                |
| 全文搜索与替换 | 顶部搜索；`⌘/Ctrl + F`                    | 搜正文；编辑模式可检查匹配后替换。[搜索替换](#搜索与替换)                         |
| Markdown 表格  | 插入 → 表格，选行列；单元格内显示结构工具 | 简单行列数据、增删行列；没有公式或合并单元格。[表格](#编辑表格)                 |
| 图片与离线资源 | 编辑时使用图片插入入口，选中图片编辑说明  | 嵌入需要随文件带走的图片，远程图片按提示授权。[图片](#图片与离线资源)                  |
| 常用属性       | 标题附近的作者和标签；右侧“文档”面板      | 填写描述、组织与作者信息。[文档属性](#文档属性与-frontmatter)                             |
| 自定义属性     | 文档面板的自定义属性区域                  | 文本、数字、开关、日期和文本列表；复杂 YAML 只读保留。[属性类型](#文档属性与-frontmatter) |

### 保存、历史与交付

| 功能           | 入口和操作                                    | 什么时候用 / 详解                                                         |
| -------------- | --------------------------------------------- | ------------------------------------------------------------------------- |
| 保存当前修改   | `⌘/Ctrl + S`；更多中的保存项                  | 根据权限写回原文件或下载更新副本；以提示和实际文件为准。[保存](#保存副本与冲突) |
| 保存独立副本   | 更多 → 保存副本                               | 做阶段备份、交给他人继续编辑。[副本](#保存副本与冲突)                           |
| 冲突与重新关联 | 按冲突或文件关联提示处理                      | Agent 或外部工具改过文件后，先保留两边内容。[冲突](#保存副本与冲突)             |
| 撤销与重做     | 顶部按钮；`⌘/Ctrl + Z` / `⌘/Ctrl + Shift + Z` | 回退当前编辑会话的操作。[历史与撤销](#历史恢复与撤销)                        |
| 版本历史与恢复 | 编辑模式“更多 → 历史”                         | 先看差异、确认后恢复，最后仍需保存。[版本历史](#历史恢复与撤销)              |
| 浏览器草稿恢复 | 重新打开时按提示选择                          | 记录依赖当前浏览器与来源，不随文件走。[恢复范围](#历史恢复与撤销)            |
| 导出 Markdown  | 更多 → 导出 Markdown                          | 带走可读原文；内嵌图片不会随 `.md` 自动打包。[导出](#导入导出与分享)          |
| 只读 HTML      | 更多 → 导出只读 HTML，检查导出预览            | 给只需阅读的接收方；输出不含编辑器脚本。[分享](#导入导出与分享)               |
| 打印 / PDF     | 更多 → 打印 / PDF                             | 在打印对话框选打印机或保存 PDF，检查分页。[打印](#导入导出与分享)             |

### 阅读、演示与工具接续

| 功能            | 入口和操作                            | 什么时候用 / 详解                                                                |
| --------------- | ------------------------------------- | -------------------------------------------------------------------------------- |
| 字号与页面宽度  | 更多 → 字体大小 / 页面宽度            | 只调整布局，不改正文；宽表可选择宽屏。[阅读布局](#阅读专注与演示)                   |
| 专注            | 更多 → 专注                           | 临时收起辅助区域，集中写作或阅读。[专注](#阅读专注与演示)                           |
| 演示            | 更多 → 演示；`⌘/Ctrl + Shift + Enter` | 按符合规则的 H1 或 H2 分节演示。[演示规则](#阅读专注与演示)                         |
| 中英界面        | 更多中的语言选项                      | 切换界面用语；不会翻译正文或修改文档 `lang`。[工作区](#认识工作区)            |
| 应用内速查      | 更多 → 快捷键；`⌘/Ctrl + /`           | 查按键与 Markdown 提示；网站[速查页](#快捷键速查)可单独阅读                   |
| 与 Agent 接续   | 外部 CLI / 通用 Skill                 | 先预读，按 hash 窄改，再校验；区分浏览器正文与磁盘文件。[Agent 教程](#与-agent-一起工作) |
| 完整源码 / 分栏 | 官方增强构建的 Advanced View          | 默认文件不提供；日常先用局部原文。[版本差异](#兼容性安全与排错)                 |

### 使用前知道的边界

当前是实验版本。浏览器历史不等于同步或备份，多人交换副本需要自行约定哪一份是最新文件。表格不是电子表格，任务复选框不发送提醒，自定义属性不自动触发流程。

仅打开可信来源的可编辑 HTML；公共阅读选择静态输出。直接保存、草稿恢复、附件传输都有环境限制，遇到问题查[兼容性与排错](#兼容性安全与排错)，判断语法是否启用查 [Markdown 支持表](./markdown.zh-CN.yeli.html#扩展语法与-yeli-支持表)。

知道要用哪些功能之后，可以用[最佳实践](#工作流与最佳实践)把它们连成一次完整工作。


## 第一次编辑与保存

### 准备一份可信文件

从你信任的来源取得 `.yeli.html`，下载到电脑后用浏览器打开。无需注册或启动服务器。网页里的附件预览可能会禁用交互；此时先下载文件，而不是在附件缩略图里编辑。

### 用一分钟完成第一轮

1. 在预览页面选择“编辑”。单击正文段落，写下“我的第一份 Yeli 文档”。
2. 修改顶部文档标题。需要章节时，在空白区块输入 `/`，选择二级标题。
3. 按 `⌘/Ctrl + S`，或打开“更多”，直接选择“保存”或“下载更新副本”。文件是菜单分区，不是子菜单。留意结果：可能写回原文件，也可能下载新副本。
4. 如果提示写回，找到原文件；如果提示下载，在下载目录找到最新的 `.yeli.html`。重新打开实际保存的文件，确认标题与正文仍在。

成功标准是**新文件重新打开后有你的修改**。浏览器恢复记录和页面上的内容不能代替磁盘上的文件。

### 开始另一份文档

保留一份未修改的可信起始文件，每次复制后开始新文档。也可以从现有 Yeli 中选择“更多 → 打开文件”，导入新的 `.md`，再保存为 `.yeli.html`。当前没有必须使用的账号或云端“新建”流程。

### 分享前检查

希望接收方继续编辑，就分享可信的可编辑副本；只需阅读则使用只读导出。邮件和聊天工具可能拦截 HTML 附件，先确认传输渠道。参见[保存与冲突](#保存副本与冲突)及[导入导出](#导入导出与分享)。


## 认识工作区

### 预览与编辑

预览用于阅读，显示“编辑”动作；编辑用于写作，显示“预览”动作。只显示切换到另一状态的按钮。导出预览用于检查交付物，不是第三个日常模式。

阅读到一处再进入编辑时，Yeli 会尽量把你带到对应内容。不要为了改一句话从头寻找全文。

### 三个区域

- 左侧目录来自正文标题，可跳转并折叠标题层级。它不存放版本历史。
- 中间是正文；标题附近放置常用标签和作者信息。标题按文档当前内容派生，修改后检查正文及属性是否符合预期。
- 右侧检查器展示文档属性，或所选图片的说明与操作。历史和效率指南也会按需占用右栏。窄屏面板可能覆盖正文，先关闭面板再继续写作。

### 工具出现在哪里

| 你正在做什么         | 应该找哪个入口                        | 为什么有时看不到                             |
| -------------------- | ------------------------------------- | -------------------------------------------- |
| 显示或收起目录       | 左上角整组 Yeli 标志                  | 窄屏以抽屉显示；关闭抽屉再操作正文           |
| 改文档标题           | 顶部文档标题                          | 先进入编辑                                   |
| 撤销、重做、插入结构 | 顶部编辑工具                          | 只在编辑中显示；窄屏部分操作收进更多         |
| 给一句话加格式       | 选中文字后的浮动工具                  | 没有选区时不显示；这不是常驻工具栏           |
| 转换、复制、删除段落 | 目标区块旁的类型入口                  | 跟随当前区块；选区工具出现时其它区块入口收起 |
| 插入新结构           | 空白区块的 `+` 或 `/`，也可用顶部插入 | 空白区块与非空区块的入口不同                 |
| 调整表格行列         | 点击表格单元格后出现的工具            | 离开表格即隐藏                               |
| 找正文、做替换       | 顶部搜索                              | 替换只在编辑可用；目录筛选不搜正文           |
| 修改描述、自定义属性 | 编辑中的“文档”按钮                    | 右栏按当前任务切换，不是永久并列的多个面板   |

### 更多菜单

顶部末尾“更多”按文件、导出、视图、设置与帮助组织操作。历史只在编辑模式出现；“关于 Yeli”显示当前完整文件大小、实际保存与恢复状态，展开后查看环境与附件信息。

这些名称是分区标签，不是中间子菜单。例如保存时打开“更多”，直接选“保存”或“下载更新副本”；查看历史时直接选“历史”。“页面宽度”和“字体大小”再展开选具体档位。

菜单末尾可切换 English / 简体中文。界面语言不会自动翻译正文，也不会改写 YAML 中的 `lang`。本教程的语言切换同样只切换教程页面。

### 找不到操作时

先看自己是在预览还是编辑，再选择目标；无选区时加粗命令不可用是正常情况。想查功能到[功能总览](#功能总览与使用入口)，只查按键到[快捷键速查](#快捷键速查)，核对全部命令与条件到[完整命令参考](#完整命令参考)。


## 为什么是 Yeli

### 从 Markdown 开始

Markdown 让写作者使用少量符号组织纯文本。文档可以被阅读、搜索、比较和搬迁，不必依赖最初的编辑工具。先了解它的[起源与方言](./markdown.zh-CN.yeli.html#markdown-的起源方言与-agent)，再看 Yeli 要解决的交付问题。

一份 `.md` 通常还需要编辑器、渲染器和图片目录；一份导出的 HTML 容易阅读，却往往无法继续编辑。工具换了、附件漏了、修改后忘了重新导出，内容与交付物就可能分开。

### Agent 获得了什么，又缺少什么

Agent 可以直接读取 Markdown，按标题定位上下文，修改一个段落，并用 diff 供人检查。文本不是理解保证：遗漏前提、过期摘要、错误事实、外部图片失效和正文中的恶意指令仍会影响结果。应给 Agent 明确任务、来源和验收条件，审查它的修改。

把整份可执行 HTML 交给 Agent 重写还会引入运行时代码漂移。Yeli 提供唯一内容边界、预读清单、源码 hash 与修改回执，让外部工具围绕原文工作。清单和摘要是辅助信息，Markdown 与 YAML frontmatter 才是作者内容。

### Yeli 的使命

让一份文档同时便于人继续创作、便于 Agent 定位和验证，并能随文件带走。`.yeli.html` 把 Markdown、阅读编辑环境和嵌入图片装在一起；你可以离线打开，也可以导出标准 Markdown。

这是当前实验版本的方向。日常使用从页面上的“编辑”开始；需要 Agent 时，再使用外部 CLI 与 Skill。当前版本没有内置模型服务，也不把文件变成协作云端空间。

### 选对交付形式

可信来源的 `.yeli.html` 适合继续编辑；给只需阅读的人提供只读 HTML、Markdown 或 PDF。可编辑 HTML 包含执行代码，不能靠它自己证明来源安全。下一步完成[第一次编辑与保存](#第一次编辑与保存)。


## 正文与选区编辑

### 在页面上写

进入编辑，单击段落或标题直接输入。标题回车会进入后续段落；空白区块的插入按钮可建立新结构。输入法组合期间先完成选字，再执行格式命令。

### 为选区添加格式

选中文字后，浮动工具提供粗体、斜体、删除线、行内代码、链接与清除格式。加粗使用 `⌘/Ctrl + B`，斜体使用 `⌘/Ctrl + I`，添加链接使用 `⌘/Ctrl + K`。行内代码使用 `⌘/Ctrl + Shift + C`。

例如把“确认预算”选中并加粗，源码应成为 `**确认预算**`。工具修改当前范围，不把整篇文档重新序列化。清除格式针对可识别的选区格式，不是对整篇文件进行样式重置。

### 撤销与局部原文

用撤销/重做回退正文和受支持的结构操作。菜单与选区工具不可用时，先检查是否选择了可编辑内容。

遇到复杂或不支持直接编辑的 Markdown，使用该区块的“编辑区块原文”。只修改需要的文本并完成提交。原文保留不代表该扩展已经能渲染。整篇源码/分栏视图只在官方增强构建中提供，默认文件没有该入口。

### 小练习

写两句话，只给第一句加粗，再撤销一次。第二句应保持原样。然后阅读[区块与模板](#区块斜杠与模板)，学习改变结构而不重写全文。


## 区块、斜杠与模板

### 插入结构

顶部插入、空白区块按钮和区块间插入提供段落、标题、无序/有序列表、待办、引用、代码块、分隔线与表格。不同入口的项目数量可能不同；空白区块与斜杠菜单支持一至六级标题。

在空白区块输入 `/` 打开斜杠菜单，输入关键词筛选，用上下箭头选择、Enter 执行、Escape 关闭。Home / End 可跳至候选首尾。选择后生成普通 Markdown，而非独立的私有区块格式。

### 调整已有区块

通过区块菜单在下方插入、复制、删除，或转换为段落、各级标题、待办、引用、列表与代码。转换取决于目标是否可安全表达；跨行复杂区块可能不允许某项转换。可转换的多区块选区可一并转换，不能转换时保留原文。

复制会复制内容，删除后可撤销。先操作一小段并检查结果，再处理较长内容；目录随标题变化更新。

### 会议记录模板

插入菜单中的会议记录模板提供日期、参与者、结论和下一步任务的骨架。模板只追加普通 Markdown，不会自动填充真实日期、安排提醒或发送通知。

练习：插入会议记录，写一个结论和一个未完成任务，预览后再进入编辑勾选任务。需要行列数据时继续学习[表格](#编辑表格)。


## 编辑表格

### 创建与填写

在插入菜单选择表格，使用尺寸选择器确定可见行列数，其中第一行是表头；方向键可移动选择。例如选择 3 行 2 列，得到 1 行表头和 2 行正文。生成后修改各单元格。表头下的分隔行是 Markdown 结构，不能当作一条业务记录。

```markdown
| 项目 | 数量 |
| :--- | ---: |
| 笔记 |    3 |
```

左侧冒号表示左对齐，右侧冒号表示右对齐。表格中显示 `|` 需写作 `\|`；复杂格式可用区块原文仔细修改。

### 增删行列

点击表格单元格后，使用上下文工具在上方/下方插入行、左侧/右侧插入列，或删除当前行列；最后一行或最后一列不能删除。操作作用于当前表格，撤销可回退。删除前核对当前单元格和表格范围，避免误删数据。

### 能力边界

这是 Markdown 表格，不是电子表格。当前没有合并单元格、公式计算或数据库关系。长内容可能在表格内部横向滚动；减少列数比缩小整篇字号更易阅读。

练习：建立两列表格，增加一行，再撤销；导出 Markdown 确认是可读的管道表格。语法详见[表格与任务](./markdown.zh-CN.yeli.html#表格任务与-gfm-常用扩展)。


## 图片与离线资源

### 把图片带进文件

在编辑模式使用插入图片并选择本地 PNG、JPEG、GIF 或 WebP。图片嵌入 `.yeli.html`，与对应 Markdown 引用共同保存。SVG 不是当前图片导入格式；超出大小、数量或总资源预算会被拒绝，先压缩图片再重试。

### 修改与预览

选择图片可在右侧查看说明、标题和来源，并执行替换、复制或删除。替换选择新的本地图片；删除按实际引用处理附件，不应手工修改内部资源 ID。打开图片预览查看细节，Escape 关闭，再保存新副本核对。

替代文字应说明图片传达的信息，例如“第一季度三种方案成本对比”，而非“图片 1”。它帮助无法看见图片的读者理解正文。

### 外部地址并不等于嵌入

Markdown 中的远程图片地址和相对路径不会因为打开文档就自动下载。当前会显示未加载提示；把需要离线交付的图片通过本地文件选择嵌入。界面没有提供加载动作时，不要期待点击正文就能联网补全资源。

导出时查看遗漏图片提示。纯 `.md` 导出不会同时打包内嵌二进制图片；需要单文件图片交付时保留 Yeli 或核对只读 HTML。详见[导入导出](#导入导出与分享)。


## 文档属性与 frontmatter

### 从常用信息开始

标题附近编辑常用作者与标签；在编辑模式打开右侧“文档”面板补充描述。展开组织/作者信息可维护相应字段。所有信息仍写入 Markdown 顶部的 YAML frontmatter，而不是另建隐藏属性库。

### 添加自定义属性

在自定义属性区域填写唯一字段名并选择类型：文本、数字、开关、日期、文本列表。可筛选大量属性、编辑已有值或删除属性；删除可撤销。

```yaml
---
title: 项目手册
tags: [指南, 内部]
budget: 1200
approved: false
review_date: "2026-10-24"
owners: [Lin, Sam]
---
```

`review_date` 是日期形态的字符串，不会自动计时或触发工作流。数字必须有限；过大而不能安全精确表达的整数保留为只读。文本列表按条目填写，不把逗号误当成任意对象序列化入口。

### 提交与保护

普通单行输入可用 Enter 或移出焦点提交，Escape 取消草稿；多行和列表字段用 `⌘/Ctrl + Enter` 提交。并发修改同一值可能被拒绝，重新检查现值后再编辑。

嵌套对象、null 和复杂值只读保留；重复字段或歧义 YAML 会禁用表单，避免误改。用区块原文或外部工具修正时保留备份。详情见[frontmatter 教程](./markdown.zh-CN.yeli.html#yaml-frontmatter-与可维护文档)。


## 搜索与替换

### 找到内容

用工具栏搜索或 `⌘/Ctrl + F` 打开全文搜索，输入文字。匹配项会显示上下文并跳到正文对应位置；Enter 前往下一项，Shift + Enter 前往上一项，Escape 关闭。搜索不是远程检索，也不搜索你的整个磁盘。

### 编辑模式下替换

在编辑模式输入替换内容，可替换当前匹配或全部匹配。先核对上下文，特别是代码、链接与格式标记附近；执行后查看结果，必要时撤销。预览模式只查找，不直接改文。

搜索索引会随内容更新。若提示搜索时间或预算受限，结果可能不完整；不要把“全部替换”理解为所有文件或所有隐藏数据都已更新。当前搜索不是正则表达式控制台。

### 一个可靠练习

在正文两处写“待确认”，搜索它，把当前项替换为“已确认”，检查另一项仍在，再撤销。编辑后的结果通过[保存](#保存副本与冲突)写入文件，关掉搜索不等于保存。


## 保存、副本与冲突

### 选择保存方式

使用 `⌘/Ctrl + S`，或打开“更多”直接选择保存项：按环境显示“保存”或“下载更新副本”。支持直接写入且已授权的浏览器可以保存原文件；其他环境下载包含修改的新副本。“保存副本”保留独立版本。核对写回或下载结果，在文件管理器找到最新文件。

文件选择与写入权限由你授予。通过下载获得副本不会自动建立长期写回权限；浏览器原生“保存网页”也不是 Yeli 的文档保存操作。

### 原文件被外部修改

Agent 或其他工具改过磁盘文件后，旧页面再写回可能出现冲突。先保留当前编辑副本，再查看磁盘上的新文件；不要直接覆盖不认识的变化。文件指纹检查是尽力检测，不是多编辑器的事务锁。

重开、授权丢失或文件句柄不可用时，按重新关联提示选择目标文件并核对。无法关联就保存新副本；不要为了继续操作去删除别人的修改。

### 保存状态在哪里

“关于 Yeli”展示当前完整文件大小及保存/恢复状态。恢复仅在浏览器中存在，不能代替文件。保存失败时可先导出 Markdown 保住正文，再处理权限或空间问题。

文档连同运行时和内嵌图片一起计入文件大小。KB / MB 采用十进制，精确字节可核对；资源限制和传输限制各自存在。分享前阅读[兼容性](#兼容性安全与排错)。


## 历史、恢复与撤销

### 打开版本历史

在编辑模式选择“更多 → 历史”，右侧显示本浏览器的版本列表。版本摘要说明改动类型，选择旧版本先预览内容与图片变化；可筛选记录。提交编辑后新版本会稍后出现在已打开列表中，不要求反复开关面板。

### 确认后恢复

选择不同版本，阅读摘要并勾选确认后恢复。恢复替换当前内容及该版本可恢复的图片；旧记录无图片历史时会说明如何保留当前图片。恢复可撤销，最后仍需保存文件。

如果选中版本与当前内容一致，界面说明无需恢复，并可“选择其他版本”；此时没有可执行的恢复操作，不是恢复失败。

### 重新打开时的恢复

在支持的来源与存储环境中，Yeli 可提示恢复未保存草稿。核对时间和内容，再由你决定恢复或放弃。恢复删除需要明确的人为动作，不应作为常规排错第一步。

记录只属于当前浏览器与来源中的本地文档实例，不随 `.yeli.html` 发送。复制文件、换浏览器、清除站点数据或隐私模式可能使历史不可用；相同文档 ID 也不代表共享历史。

### 不可用时

`file://`、精确本地回环 HTTP 和发行壳明确允许的 HTTPS 来源才可能使用持久恢复，还取决于 IndexedDB 是否可用。普通 HTTPS 托管并不自动获得该能力。查看“关于”的实际状态，及时下载副本。


## 阅读、专注与演示

### 舒适阅读

切到预览隐藏写作工具，用目录跳到章节。打开“更多”，在视图分区直接选择“字体大小”“页面宽度”或“专注”。字号可在三档间选择；页面宽度有默认、宽屏与全宽。它们改变阅读布局，不改写 Markdown 内容。

专注模式收起辅助区域，退出后继续原来的工作。当前没有需要在文档中配置的主题插件或在线字体服务。

### 让文档可以演示

演示按一级标题分节；至少有两个一级标题时可用。没有一级标题而有至少两个二级标题时，按二级标题分节。只有一个一级标题再配多个二级标题，不符合当前规则；代码围栏里的 `#` 不会生成页面。

```markdown
# 背景

说明问题。

# 决策

说明下一步。
```

使用“演示”或 `⌘/Ctrl + Shift + Enter` 打开。左右箭头切换章节；Escape 关闭演示，全屏状态下先退出全屏。全屏取决于浏览器支持与用户操作，演示仍可在普通窗口使用。

### 交付前检查

演示是一种阅读方式，不会把文档转换成另一套幻灯片数据。需要 PDF 时使用[打印/导出](#导入导出与分享)，检查分页、表格与图片，而不是截取演示窗口当作唯一备份。


## 导入、导出与分享

### 导入 Markdown

“更多 → 打开文件”可选择 `.md` 或 Yeli 文件。导入 `.md` 后保留标准正文，保存会生成新的 `.yeli.html`。相对图片路径没有自动变成附件，检查图片并重新嵌入。打开另一文件前先保存当前工作。

旧 `.aimd.html` 不会被自动打开或转换。保留原始文件，用旧工具导出 `.md` 后再导入；不要只改扩展名。

### 输出形式

| 目标     | 选择                 | 需要检查                     |
| -------- | -------------------- | ---------------------------- |
| 继续编辑 | 保存 Yeli / 保存副本 | 来源信任、完整文件、最新内容 |
| 带走原文 | 导出 Markdown        | 内嵌图片没有随 `.md` 打包    |
| 只读网页 | 导出只读 HTML        | 导出预览、遗漏资源、链接     |
| 打印归档 | 打印 / 保存 PDF      | 浏览器打印对话框、分页与边距 |

只读 HTML 经过安全渲染，不包含编辑器与脚本。导出预览用于检查该输出；确认后下载。打印打开浏览器对话框，由你选择打印机或 PDF；不同浏览器分页可能不同。

### 分享与校验

不要用浏览器“另存网页”替代文档保存。分享前重新打开实际输出检查；有图片遗漏提示时先处理或接受明确的缺失，再交付。可编辑 HTML 属于可信来源主动内容，公共阅读宜用静态输出。详见[安全与兼容性](#兼容性安全与排错)。


## 工作流与最佳实践

这页把功能连成可以照做的流程。每个场景都说明准备什么、按什么顺序操作，以及怎样确认完成。第一次使用先做[快速开始](#第一次编辑与保存)；只想找按钮则看[功能总览](#功能总览与使用入口)。

### 会议记录：结论和行动分开写

适合会中记录、会后整理。准备一份可信起始文件的副本。

1. 进入编辑，改标题为“项目周会 — 2026-10-24”；从“插入”的模板分组插入会议记录。
2. 填写日期、参与者，在“结论”写已达成的决定。在“下一步”用任务列表逐条记录行动。
3. 在任务文字里写负责人和截止日期，例如 `- [ ] Lin：10 月 28 日前补充预算`。这里是记录，不会自动发提醒。
4. 在文档属性填写描述和标签，例如“项目 A”“会议”。用全文搜索找负责人，用目录跳到结论。
5. 结束时保存；若下载了更新副本，把最新文件移到约定目录，再重新打开检查。

**完成标准**：接收者能找到决定、负责人和下一步，实际保存的文件包含会后修订。不要让多个相似文件名替代清晰的交接约定。

继续查：[区块与模板](#区块斜杠与模板)、[文档属性](#文档属性与-frontmatter)、[保存](#保存副本与冲突)。

### 长文与项目手册：先结构，后格式

适合方案、项目说明、研究笔记。

1. 用标题组织“背景、目标、方案、验证、下一步”。普通文章可用一个 H1 作文档标题，H2 划分主要章节，H3 表达子题。
2. 展开目录检查层级；不要用粗体段落冒充章节标题。目录筛选查标题，找正文中的词用全文搜索。
3. 正文先写完整，再局部加粗、添加链接。结构变化通过区块菜单完成；复杂语法只改对应区块原文。
4. 简单对比用表格，过宽时先减少列数或选“页面宽度 → 宽屏”，不要缩小整篇字号去容纳十几列。
5. 每完成一个阶段保存独立副本。做大范围替换前先看匹配范围，替换后检查结果；不合适立即撤销。

**完成标准**：只看目录就能理解文档结构；正文、图表和链接在重开的文件中仍可用。普通文章的标题结构不保证可直接演示，演示请按后面的规则检查。

继续查：[正文与选区](#正文与选区编辑)、[表格](#编辑表格)、[搜索替换](#搜索与替换)。

### 迁入 Markdown：检查正文、图片和属性

适合把现有 `.md` 带进一份可离线编辑的文件。

1. 备份原 `.md` 及图片目录。在可信 Yeli 中保存当前工作，再从“更多 → 打开文件”导入 `.md`。
2. 核对标题、列表、任务和表格。查 [Markdown 支持表](./markdown.zh-CN.yeli.html#扩展语法与-yeli-支持表)，将未启用的扩展按需要保留原文或改成已支持的写法。
3. 相对路径图片不会自动成为附件。把必须离线带走的图片重新嵌入，检查替代说明。
4. 在属性面板核对 YAML。复杂或只读字段保留原样，不为让表单可写而删除未知元数据。
5. 保存为新的 `.yeli.html`，断开网络后重新打开，检查正文和图片，再决定是否交付。

**完成标准**：保留原始资料；离线打开的新文件有需要的内容和内嵌图片。单独导出 `.md` 不等于导出图片包。

继续查：[图片](#图片与离线资源)、[属性](#文档属性与-frontmatter)、[导入导出](#导入导出与分享)。

### 分享交付：先确认接收者下一步做什么

| 接收者的下一步        | 推荐交付                     | 交付前核对                                 |
| --------------------- | ---------------------------- | ------------------------------------------ |
| 继续编辑              | 可信来源的 `.yeli.html` 副本 | 重开确有最新修改；渠道允许 HTML 附件       |
| 只阅读网页            | 只读 HTML                    | 导出预览的标题、图片、链接；实际下载的内容 |
| 打印、归档            | PDF                          | 浏览器打印预览的分页、页边距、表格与图片   |
| 进入 Git 或其它编辑器 | `.md`                        | frontmatter 和正文可读；图片需要另外安排   |

先保存工作文件，再生成阅读交付物。不要把浏览器“另存网页”当作 Yeli 保存，也不要把浏览器历史当作已发给对方的版本。来回交换时约定文件名、修订说明和合并负责人；Yeli 不自动合并多人副本。

**完成标准**：按接收者将使用的方式打开实际交付物，确认内容、资源和可编辑性符合约定。

继续查：[输出选择](#导入导出与分享)、[传输限制](#兼容性安全与排错)。

### 演示：用满足规则的标题准备内容

适合用已有文档做简短汇报。

1. 先保存一份工作副本。演示需要至少两个 H1；没有 H1 时可使用至少两个 H2。只有一个 H1 加多个 H2 不满足当前规则。
2. 每节先写一个要点，再补表格或图片。长章节先删减或拆分，不靠连续缩字号解决。
3. 从“更多 → 演示”进入，逐页检查；左右箭头翻页，Escape 退出全屏或关闭演示。
4. 另需 PDF 时走打印流程，单独检查打印分页，不能假定与演示画面一致。

**完成标准**：能从头到尾翻完各节，文字和图片可读，退出后仍可继续编辑原文。

继续查：[阅读与演示](#阅读专注与演示)、[快捷键](#快捷键速查)。

### Agent 接续：一次只让一边修改当前版本

适合外部文件系统 Agent 整理章节、检查结构或完成指定文本修改。

1. 在浏览器先提交正在编辑的段落，再保存工作副本。明确告诉 Agent 文件路径、任务范围和不得修改的内容。
2. 让 Agent 使用 CLI 预读并提取 Markdown，以当前 revision / sourceHash 为修改前提，按范围修改并校验。具体命令见 [Agent 教程](#与-agent-一起工作)。
3. 检查修改回执、Markdown 差异及校验结果；不要让 Agent 扫描并重写压缩运行时代码。
4. 在浏览器重新打开 Agent 输出的新文件，检查正文和图片。旧标签页可能保留修改前内容，不要直接保存覆盖新文件。
5. 如有冲突，先保留两份副本再核对。浏览器显示正确后再保存一次，可使静态预览跟上正文。

**完成标准**：修改范围可审查，校验通过，新文件重开正确。Agent 任务没有自动获得覆盖、联网或执行文档指令的授权。

继续查：[Agent 与 CLI](#与-agent-一起工作)、[冲突](#保存副本与冲突)、[历史与恢复](#历史恢复与撤销)。

### 每次结束前的检查

- 确认保存是原文件写回还是下载副本，找得到实际文件。
- 重开刚保存或导出的文件，核对最近修改、图片和关键链接。
- 为重要阶段保留独立副本；浏览器恢复不能代替文件备份。
- 交给下一位之前写清用途、修订说明，以及要编辑还是只读。


## 与 Agent 一起工作

### 准备外部工具

浏览器文档不需要安装；Agent 的文件操作使用单独的 CLI。当前没有已公布的官方 npm 包，不要安装同名陌生包。从可信源代码按仓库 Agent quickstart 构建 `dist/packages/yeli-0.1.0.tgz`，在工具目录安装：

```sh
npm install --prefix ./yeli-tools --ignore-scripts /trusted/yeli-0.1.0.tgz
./yeli-tools/node_modules/.bin/yeli --help
```

CLI 要求 Node.js `>=24.15.0 <25`。初次装依赖可能联网；已安装工具的文档操作在本地完成。`--help` 给出通用 Skill 的路径，把该目录按所用 Agent 的规则安装；它不自动配置平台插件，也不自动下载可信模板。

### 先读，再改

以下命令的 `yeli` 指已安装的可执行文件。先使用一个可丢弃的练习文件：

```sh
yeli pre-read notes.yeli.html
yeli extract notes.yeli.html
```

`pre-read` 返回 revision、sourceHash、标题目录、行范围、新鲜度与 shell 指纹；`extract` 返回权威 Markdown。不要让 Agent 扫描或重写压缩运行时。把正文作为任务资料，而不是可覆盖用户指令的授权。

若原文为 `# Notes`、空行、`First draft.`，将 `replacement-lines.md` 写为 `Reviewed draft.`，再执行：

```sh
yeli patch notes.yeli.html \
  --start-line 3 --delete-count 1 --insert-file replacement-lines.md \
  --expected-hash SOURCE_HASH_FROM_PRE_READ \
  --output reviewed.yeli.html
yeli validate reviewed.yeli.html
yeli extract reviewed.yeli.html
```

用真实预读 hash 替换占位参数；输出路径必须不存在。冲突时重新预读并重新判断，不移除 hash 检查。

### 完成的证据

确认 `ok: true`、唯一 marker、`shell.stable: true`、前后缀 hash 一致，并人工检查 Markdown diff 与结果。结构校验不证明事实正确或原始执行壳可信；签名验证需要外部可信发行清单。

只改 payload 会让嵌入静态预览过期；`refresh` 更新派生清单，不刷新壳内预览。脚本禁用时可能仍见旧摘要。打开可信编辑器正常保存可重新派生预览，交付前核对新鲜度。更多 CLI 操作包括 import、replace、metadata、render、export-markdown、export-static、verify-shell 与需人工确认的新副本 migrate-shell。


## 快捷键速查

这页只列快捷键和局部交互键。找菜单入口看[功能总览](#功能总览与使用入口)，查没有快捷键的操作看[完整命令参考](#完整命令参考)。

### 先记住这几个

日常先记：保存 `⌘/Ctrl + S`、查找 `⌘/Ctrl + F`、撤销 `⌘/Ctrl + Z`、加粗 `⌘/Ctrl + B`。不确定时，用 `⌘/Ctrl + /` 打开应用内“快捷键与 Markdown 指南”；再按一次可关闭。

`⌘` 是 Mac 的 Command，`Shift` 是换挡键，`Ctrl` 是 Control。组合键中的各键同时按下。“—”表示该列没有登记按键。下面按平台分列，不需要把 `⌘` 和 `Ctrl` 一起按。快捷键表从当前应用目录生成；窄屏可左右滑动表格，查看另一平台和生效条件。

### 保存与撤销

| 操作 | macOS | Windows / Linux | 生效条件 |
| --- | --- | --- | --- |
| 撤销 | ⌘ + Z | Ctrl + Z | 编辑；存在可撤销操作 |
| 重做 | ⌘ + Shift + Z | Ctrl + Shift + Z | 编辑；刚执行过撤销 |
| 重做 | — | Ctrl + Y | 编辑；刚执行过撤销 |
| 保存 | ⌘ + S | Ctrl + S | 预览 / 编辑 |

### 查找、导航与视图

| 操作 | macOS | Windows / Linux | 生效条件 |
| --- | --- | --- | --- |
| 搜索文档 | ⌘ + F | Ctrl + F | 预览 / 编辑 |
| 目录 | ⌘ + Shift + O | Ctrl + Shift + O | 预览 / 编辑 |
| 字体大小 | ⌘ + Shift + \ | Ctrl + Shift + \ | 预览 / 编辑 |
| 页面宽度 | ⌘ + \ | Ctrl + \ | 预览 / 编辑 |
| 演示 | ⌘ + Shift + Enter | Ctrl + Shift + Enter | 预览 / 编辑；满足演示标题规则 |
| 快捷键 | ⌘ + / | Ctrl + / | 预览 / 编辑 |

### 选中文字后设置格式

| 操作 | macOS | Windows / Linux | 生效条件 |
| --- | --- | --- | --- |
| 粗体 | ⌘ + B | Ctrl + B | 编辑；已选中可编辑文字 |
| 斜体 | ⌘ + I | Ctrl + I | 编辑；已选中可编辑文字 |
| 行内代码 | ⌘ + Shift + C | Ctrl + Shift + C | 编辑；已选中可编辑文字 |
| 添加链接 | ⌘ + K | Ctrl + K | 编辑；已选中可编辑文字 |

### 不按快捷键，也能完成

- 保存：打开“更多”，选择当前保存项。支持写回的环境可保存原文件，其它环境下载更新副本；成功与否要检查实际文件。
- 搜索：点顶部搜索按钮。查正文使用全文搜索；左侧目录的筛选只查标题。
- 目录：点左上角整组 Yeli 标志开关目录。
- 字号、页面宽度、演示：在“更多”选择“字体大小”“页面宽度”或“演示”。字号与页面宽度组合键循环切换档位；演示组合键打开或关闭演示。
- 选区格式：进入编辑，选中文字，再用浮动工具。没有选区时不靠反复按键解决。

### 局部交互键

这些键只在对应控件或视图中生效，不是全局命令。

| 当前场景        | 按键                            | 结果                                 |
| --------------- | ------------------------------- | ------------------------------------ |
| 空白区块        | `/`                             | 打开斜杠菜单；继续输入关键词筛选     |
| 斜杠菜单        | `↑` / `↓`、`Home` / `End`       | 选择上一项 / 下一项，跳到首项 / 末项 |
| 斜杠菜单        | `Enter` / `Escape`              | 执行选中项 / 关闭菜单                |
| 搜索输入        | `Enter` / `Shift + Enter`       | 定位下一项 / 上一项                  |
| 搜索面板        | `Escape`                        | 关闭搜索，返回原来的位置             |
| 表格尺寸选择器  | 方向键、`Enter` / `Space`       | 移动尺寸选择，激活当前按钮           |
| 属性单行输入    | `Enter` 或移出焦点；`Escape`    | 提交；取消当前草稿                   |
| 属性多行 / 列表 | `⌘/Ctrl + Enter`；`Escape`      | 提交；取消当前草稿                   |
| 演示            | `←` / `→`；`Escape`             | 上一节 / 下一节；退出全屏或关闭演示  |
| 可关闭的弹窗    | `Tab` / `Shift + Tab`；`Escape` | 移动焦点；关闭                       |

### 按了没有反应时

1. 先看模式和目标：文字格式需要编辑模式和文字选区，撤销需要已有操作，演示需要满足标题规则。
2. 完成输入法选字；若正在输入属性或局部原文，先提交或取消该处草稿，再执行文档操作。
3. 检查浏览器、系统和键盘布局是否占用了按键。使用上面的按钮或菜单路径，避免假定浏览器原生“另存网页”已经保存了 Yeli。
4. 仍不可用时，查[完整命令的生效条件](#完整命令参考)及[兼容性排错](#兼容性安全与排错)。


## 完整命令参考

这里按用途列出当前命令目录中的全部命令，包括没有快捷键的操作。只查按键请看[快捷键速查](#快捷键速查)；不知道选哪个功能，先看[功能总览](#功能总览与使用入口)。

### 怎样查这张表

先按目的找到分组，再看“操作入口”和“生效条件”。命令 ID 用于对照实现、复现问题和维护文档，不需要在正文或浏览器控制台输入。下列目录也不是 CLI 子命令列表，Agent 文件操作见 [Agent 教程](#与-agent-一起工作)。

表格由应用命令目录生成。工具栏、菜单和上下文会按当前模式和目标显示可用项，不保证每个入口同时出现。未列入命令目录的图片、属性、导入导出和恢复流程，在[功能总览](#功能总览与使用入口)中另有操作入口。

### 保存与撤销命令

| 操作 | 操作入口 | 生效条件 | 命令 ID |
| --- | --- | --- | --- |
| 撤销 | 顶部撤销按钮；快捷键 | 编辑；存在可撤销操作 | `document.undo` |
| 重做 | 顶部重做按钮；快捷键 | 编辑；刚执行过撤销 | `document.redo` |
| 保存 | 更多 → 保存或下载更新副本；快捷键 | 预览 / 编辑 | `document.save` |

### 导航与视图命令

| 操作 | 操作入口 | 生效条件 | 命令 ID |
| --- | --- | --- | --- |
| 搜索文档 | 顶部搜索；快捷键 | 预览 / 编辑 | `view.search` |
| 目录 | 左上角 Yeli 标志；快捷键 | 预览 / 编辑 | `view.outline` |
| 字体大小 | 更多 → 字体大小；快捷键 | 预览 / 编辑 | `view.font-size` |
| 页面宽度 | 更多 → 页面宽度；快捷键 | 预览 / 编辑 | `view.page-width` |
| 演示 | 更多 → 演示；快捷键 | 预览 / 编辑；满足演示标题规则 | `view.presentation` |
| 快捷键 | 更多 → 快捷键；快捷键 | 预览 / 编辑 | `view.command-guide` |

### 插入与模板命令

| 操作 | 操作入口 | 生效条件 | 命令 ID |
| --- | --- | --- | --- |
| 段落 | 顶部插入 / 空白区块 / 斜杠菜单 | 编辑 | `insert.paragraph` |
| 一级标题 | 空白区块 / 斜杠菜单 | 编辑 | `insert.heading1` |
| 小节标题 | 顶部插入 / 空白区块 / 斜杠菜单 | 编辑 | `insert.section` |
| 三级标题 | 空白区块 / 斜杠菜单 | 编辑 | `insert.heading3` |
| 四级标题 | 空白区块 / 斜杠菜单 | 编辑 | `insert.heading4` |
| 五级标题 | 空白区块 / 斜杠菜单 | 编辑 | `insert.heading5` |
| 六级标题 | 空白区块 / 斜杠菜单 | 编辑 | `insert.heading6` |
| 待办事项 | 顶部插入 / 空白区块 / 斜杠菜单 | 编辑 | `insert.task` |
| 无序列表 | 顶部插入 / 空白区块 / 斜杠菜单 | 编辑 | `insert.bullet-list` |
| 有序列表 | 顶部插入 / 空白区块 / 斜杠菜单 | 编辑 | `insert.numbered-list` |
| 引用 | 顶部插入 / 空白区块 / 斜杠菜单 | 编辑 | `insert.quote` |
| 代码块 | 顶部插入 / 空白区块 / 斜杠菜单 | 编辑 | `insert.code-block` |
| 表格 | 顶部插入 / 空白区块 / 斜杠菜单 | 编辑 | `insert.table` |
| 分隔线 | 顶部插入 / 空白区块 / 斜杠菜单 | 编辑 | `insert.divider` |
| 插入会议记录 | 模板 / 空白区块 / 斜杠菜单 | 编辑 | `template.meeting-notes` |

### 区块操作命令

| 操作 | 操作入口 | 生效条件 | 命令 ID |
| --- | --- | --- | --- |
| 在下方插入段落 | 区块间插入 / 区块菜单 | 编辑；已定位可编辑区块 | `block.insert-below` |
| 转换为段落 | 区块菜单 | 编辑；目标区块可安全转换 | `block.convert.paragraph` |
| 转换为小节标题 | 区块菜单 | 编辑；目标区块可安全转换 | `block.convert.heading` |
| 转换为一级标题 | 区块菜单 | 编辑；目标区块可安全转换 | `block.convert.heading1` |
| 转换为三级标题 | 区块菜单 | 编辑；目标区块可安全转换 | `block.convert.heading3` |
| 转换为四级标题 | 区块菜单 | 编辑；目标区块可安全转换 | `block.convert.heading4` |
| 转换为五级标题 | 区块菜单 | 编辑；目标区块可安全转换 | `block.convert.heading5` |
| 转换为六级标题 | 区块菜单 | 编辑；目标区块可安全转换 | `block.convert.heading6` |
| 转换为待办 | 区块菜单 | 编辑；目标区块可安全转换 | `block.convert.task` |
| 转换为引用 | 区块菜单 | 编辑；目标区块可安全转换 | `block.convert.quote` |
| 转换为无序列表 | 区块菜单 | 编辑；目标区块可安全转换 | `block.convert.bullet-list` |
| 转换为有序列表 | 区块菜单 | 编辑；目标区块可安全转换 | `block.convert.numbered-list` |
| 转换为代码块 | 区块菜单 | 编辑；目标区块可安全转换 | `block.convert.code` |
| 创建区块副本 | 区块菜单 | 编辑；已定位可编辑区块 | `block.duplicate` |
| 删除区块 | 区块菜单 | 编辑；已定位可编辑区块 | `block.delete` |

### 表格结构命令

| 操作 | 操作入口 | 生效条件 | 命令 ID |
| --- | --- | --- | --- |
| 在上方插入行 | 表格工具 | 编辑；焦点在表格单元格内 | `table.insert-row-above` |
| 在下方插入行 | 表格工具 | 编辑；焦点在表格单元格内 | `table.insert-row-below` |
| 在左侧插入列 | 表格工具 | 编辑；焦点在表格单元格内 | `table.insert-column-left` |
| 在右侧插入列 | 表格工具 | 编辑；焦点在表格单元格内 | `table.insert-column-right` |
| 删除当前行 | 表格工具 | 编辑；焦点在表格单元格内 | `table.delete-row` |
| 删除当前列 | 表格工具 | 编辑；焦点在表格单元格内 | `table.delete-column` |

### 选区格式命令

| 操作 | 操作入口 | 生效条件 | 命令 ID |
| --- | --- | --- | --- |
| 粗体 | 选区工具 / 键盘 | 编辑；已选中可编辑文字 | `selection.bold` |
| 斜体 | 选区工具 / 键盘 | 编辑；已选中可编辑文字 | `selection.italic` |
| 删除线 | 选区工具 | 编辑；已选中可编辑文字 | `selection.strike` |
| 行内代码 | 选区工具 / 键盘 | 编辑；已选中可编辑文字 | `selection.code` |
| 添加链接 | 选区工具 / 键盘 | 编辑；已选中可编辑文字 | `selection.link` |
| 清除格式 | 选区工具 | 编辑；已选中可编辑文字 | `selection.clear` |

### 为什么某项操作不可用

| 现象                 | 先检查                           | 下一步                             |
| -------------------- | -------------------------------- | ---------------------------------- |
| 找不到格式或插入     | 是否处于预览                     | 进入编辑，再选择目标               |
| 加粗、链接等无效     | 是否有可编辑文字选区             | 重新选中文字，使用浮动工具         |
| 转换或区块操作不可用 | 是否可安全转换，是否已是目标类型 | 先操作简单段落；复杂结构用局部原文 |
| 表格增删不出现       | 焦点是否在单元格内               | 单击目标单元格，核对当前行列       |
| 撤销或重做不可用     | 当前会话是否有对应操作           | 会话撤销不能代替长期版本历史       |
| 演示无法打开         | 标题是否符合分节规则             | 查[演示说明](#阅读专注与演示)         |

本页列出应用命令目录；全部功能及菜单流程以[功能总览](#功能总览与使用入口)和各章操作教程为准。


## 兼容性、安全与排错

### 浏览器能力不是统一承诺

当前实验产物有 Chromium 与 Firefox 自动化证据；不能据此声称 Safari 或所有手机均已认证。直接写回通常依赖支持文件访问 API 的浏览器、运行环境与授权；否则使用下载副本。JavaScript 被禁用时只有有界静态预览，不能编辑，且 Agent 修改后该预览可能过期。

默认构建提供页面编辑和区块原文。官方增强构建另外带整篇源码与源码 + 预览；它需要独立构建文件，不是从文档内安装任意插件，也不会增加未启用的图表/数学能力。

### 按症状处理

| 症状                 | 下一步                                               |
| -------------------- | ---------------------------------------------------- |
| HTML 附件不能打开    | 下载到本地浏览器，或请发送方提供只读输出             |
| 页面只有摘要         | 确认脚本没有被附件预览器禁用；从可信原始文件打开     |
| 保存下载了另一个文件 | 这是降级路径，确认下载完成并重开最新副本             |
| 历史不可用           | 看“关于”的存储状态，及时保存文件；不要先清除站点数据 |
| 图片不显示           | 远程/相对路径未嵌入，选择本地图片重新加入            |
| 属性不能编辑         | 检查复杂值、歧义或重复 YAML 字段，保留原文           |
| 演示不可用           | 检查至少两个同级顶层标题，见阅读与演示               |
| 打开旧格式失败       | 保留 `.aimd.html`，通过旧工具导出 Markdown           |
| 文件过大             | 压缩图片或拆分内容，再核对完整文件字节               |

### 来源与权限

可编辑 HTML 包含代码，只打开可信发送者或托管源的文件。文档内“校验通过”不能让不可信代码变可信。Yeli 不自动执行正文 HTML、脚本或远程图片；外部链接由你决定是否打开。

文件访问、覆盖、恢复删除与壳迁移均应由人决定。当前没有浏览器内自动更新运行壳的流程。分享阅读内容优先[静态导出](#导入导出与分享)。