fhgs-pi-rich-markdown0.0.9

Rich Markdown for Pi

English | 简体中文

Rich Markdown（richmd）0.0.9 为 Pi 1.3.0 和 1.4.0 提供更丰富的 Markdown 和本地 LaTeX 排版，在回答仍流式输出时即可渲染已经闭合的公式。它不修改 Pi 的安装源码，不重写消息、已保存会话或工具结果。默认启用、可关闭的提示词规则要求模型使用 LaTeX，而非 Unicode／纯文本替代公式。渲染不调用模型，也不使用云服务。

GitHub 发布 0.0.7 — 2026-10-19：提供输入框内的实时 Markdown／LaTeX 预览，光标进入时展开整个块的源码，并提供确定性的本地输入辅助，以及完整引擎 Mermaid／图像预览和缩放／平移查看器。默认值为 input: "rich"、assist: true 和 draft: false；独立实时草稿预览区、本地图像卡片及紧凑路径标签仍然可用。这是首次 GitHub 0.0.7 发布，包含并取代更新日志中记录的更早本地候选快照。

**分发发布 0.0.9 — 2026-10-28：**以既有包名 fhgs-pi-rich-markdown 准备首次公开 npm 分发，增加明确的文件允许列表、随包 MIT 许可证及打包回归测试。原生 worker 使用转为普通 ESM 的同一栅格验证器，以便在 Node 不允许剥离 TypeScript 类型的 npm node_modules 路径下运行。本次只改变分发与文档，不改变渲染功能、命令、偏好或依赖固定版本。下方 npm／标签命令要求相应版本已经发布；准备源码发布不代表它已在任一发布平台可用。

已有安装不会自动升级。请选择 npm 安装／迁移或全新目录源码升级，不要同时使用两种登记方式。标为 0.0.7 的更早本地快照不是最终 GitHub 发布版；仅凭版本字符串不能确定已安装的快照。准备或发布版本都不会修改正在使用的本地安装。

要在 TUI 中显示类似数学文档的排版公式，请直接在 Ghostty 或 Kitty 中运行 Pi。Apple Terminal 无法显示这些像素，Pi 设置不能为它添加图像协议。 正文仍是终端文字，不会变为浏览器的比例字体。其他终端保留可读的结构化文本，并可显式打开私密浏览器预览。

要求与安装

0.0.9 发布版保留 0.0.8 引入的精确 Pi 1.3.0／1.4.0 兼容。 未改动的 rich-markdown-v0.0.7 标签仍只支持 Pi 1.3.0。从 0.0.8、更早发布版或本地候选快照升级时，请选择下方一种流程，仅替换已有登记，再重载／重启 Pi。不会自动修改已有安装；依赖和偏好设置不变。

要求 Node.js 22.19+，且 Pi SDK/TUI 必须配套、版本恰好为 1.3.0 或 1.4.0。带保护、可恢复的适配器使用私有 Markdown 及默认编辑器布局、点击定位和编辑辅助方法；其他 Pi 版本会保留原生渲染并显示警告。Pi 提供 peer 依赖，不要另装第二套 SDK/TUI。直接依赖版本固定在 package.json；源码安装还使用完整的 package-lock.json。npm 不分发该锁文件，因此 npm 安装按正常规则解析间接依赖；需要完整锁定依赖树时，请使用标签源码安装。不需要构建、系统 TeX 或依赖生命周期脚本。完整 Mermaid 和静态 WebP 渲染另外要求 macOS／Linux 上已安装 Chrome／Chromium。锁定版本的 puppeteer-core 驱动不会下载浏览器。检查固定应用／系统位置；其他位置可通过 RICH_MARKDOWN_BROWSER 指定原生浏览器可执行文件的绝对路径。不会打开个人浏览器配置目录。

npm 安装与升级

fhgs-pi-rich-markdown@0.0.9 发布后，首次安装可使用 Pi 包管理器。安装前请审阅源码：扩展以 Pi 的操作系统权限执行。先检查 pi list、个人／项目设置、显式 -e 路径及自动发现的扩展目录。不要同时加载 npm 副本和本地、Git 或旧式扩展副本。

pi list
npm_config_ignore_scripts=true pi install npm:fhgs-pi-rich-markdown@0.0.9

示例使用 Pi 默认的 npm 后端，仅在本次调用中禁用依赖生命周期脚本。如果自定义了 npmCommand，请使用对应包管理器的禁用生命周期选项，或改用源码安装器。Pi 提供 SDK/TUI peer 并禁止重复安装这些依赖。没有插件 install/postinstall 钩子，不下载浏览器、不调用模型，也不自动安装 Ghostty。个人包声明写入 <agent-dir>/settings.json，包存放于检出目录之外、由 Pi 管理的 npm 存储。只有确实需要项目范围安装时才使用 --local，并遵守 Pi 项目信任规则。重启 Pi 或 /reload，再运行 /rich-markdown status、/rich-markdown setup 和 /rich-markdown demo math。

添加 npm 之前，先迁移已有源码／旧式安装：

1. 私下记录当前精确来源、范围及对象形式的资源过滤条件。保留旧稳定源码目录和 rich-markdown.json 以便回滚。更改登记前停止使用旧副本的会话，不覆盖其文件或依赖。
2. 仅在原范围内移除旧登记。个人本地包使用 pi remove /absolute/path/to/old/copy，只移除声明，不删除本地源码目录；项目声明加 --local。extensions 条目、通配符、自动发现副本／符号链接或显式 -e 参数则必须在实际来源处移除／禁用。不要覆盖整个设置文件或删除无关扩展。Pi 将 npm、Git 和本地路径视为不同身份，不会因为清单中的包名相同就自动去重。
3. 在所选范围安装上方固定版本的 npm 来源，保留原资源过滤条件（包括禁用项），再通过 pi list 和 pi config 核对。如果安装失败，仅恢复旧登记及其过滤条件，不要让两项同时生效。确认只选中一份后再恢复／重载会话。

**后续 npm 升级：**先停止使用受管理副本的会话，再在相同范围运行 pi install npm:fhgs-pi-rich-markdown@<chosen-version>，并禁用生命周期脚本。在受支持宿主上，Pi 替换同名 npm 条目并保留对象形式过滤条件，不会追加第二个版本。显式 @0.0.9 固定版本不会因 pi update --extensions 自动升到新版本，需主动选择。不要用不带参数的 pi update 升级本扩展：该命令更新 Pi 本身，可能超出精确支持的宿主版本。

npm 包只包含明确列出的运行时模块／worker、合成演示图、完整双语指南／更新日志、设计／来源文档、包元数据及 LICENSE。不包含测试、开发／安装器脚本、锁文件、凭据、设置、会话／历史文件、日志或依赖树。setup、check、test 和 test:package npm 脚本是源码工作副本工具，不是已安装 npm 包的命令。Pi 内的 /rich-markdown setup 和 /rich-markdown setup install 仍然可用且行为不变。

引导式安装

从 0.0.6 开始，源码快照包含引导式安装器，npm 包不包含它。 请在此方式与 npm 登记之间二选一。在对应发布标签的源码工作副本中运行：

cd Pi/rich-markdown
./install.sh --check
./install.sh

独立发布归档解包后，在其根目录运行相同命令即可。node scripts/install.mjs 等同于 ./install.sh，也支持 npm run setup -- --check。特意不设置 npm install/postinstall 钩子，不会在 Pi 启动时弹出安装提示，也不会在加载插件时自动安装软件。

安装器先检测并说明计划，再请求批准：

• Node.js 与 Pi：要求 Node.js 22.19+ 和已安装、配套且版本恰好为 1.3.0 或 1.4.0 的 Pi SDK/TUI。缺失或不兼容的宿主会中止安装；不会安装或升级 Pi、Node。非标准宿主位置可通过 PI_SDK_PATH 指定。
• 渲染库：检查锁定版本的依赖元数据与原生 Resvg 包。缺失或不兼容时，通过 npm 根据 package-lock.json 安装，不运行生命周期脚本、不安装开发依赖或第二套 Pi peer。完整依赖直接复用；登记前必须通过合成 PNG 冒烟检查。npm 必须已经可用。
• Ghostty／Kitty：检查 PATH 中的可执行文件及 macOS 系统／用户应用包。已有 Ghostty 或 Kitty，或环境表明正在直接使用兼容终端时，跳过额外终端安装。环境提示不等于图形能力验证；非常规应用位置可能需要手动设置。
• 可选 Ghostty：本地 Mac 上未找到两种终端且 Homebrew 可用时，单独询问是否执行 brew install --cask ghostty。该 cask 重新打包官方签名 macOS DMG，不会安装 Homebrew 本身。缺少 Homebrew、SSH、Linux 发行版差异及不支持平台会获得官方安装指引（英文），而不是下载并执行 shell 脚本、添加软件源或自动提权。插件安装器支持 macOS／Linux，原生 Windows 仍需手动安装。
• 其他 Pi 插件：没有必需项。MathJax、KaTeX 和 Resvg 是包依赖，不是独立 Pi 扩展；不会安装或删除可能冲突的数学渲染插件。

批准后，默认仅将本包及许可证复制到 Git 工作副本之外的 <agent-dir>/local/rich-markdown-<version>。已有相同源码副本会复用，不覆盖不同或不完整的源码副本。包内路径的每个组成部分都必须是真实目录或普通文件，不能是指向 Git 工作副本或其他位置的符号链接。可用 --dir 选择新目录；将已发布的 0.0.8 或更早发布版／本地候选快照升级到 0.0.9 发布版时也应这样做。已登记副本的损坏依赖不会原位修复。只新增／替换个人 Rich Markdown 包条目，使用 Pi 的设置锁，保留对象形式的资源过滤条件和无关设置。已有设置以 0600 权限备份到 <agent-dir>/backups/；安装期间若该包登记发生并发变化，则停止更新。也识别本地 file:// 登记。多个已知个人登记或已知个人 extensions 条目必须先解决重复／完成迁移；项目、命令行、通配符及自动发现的扩展副本仍需用户自行管理。已有禁用过滤规则会保留，必要时使用 pi config 检查。

# Non-interactive: approve only the plugin, not an external terminal.
./install.sh --yes --without-ghostty
# Separately approve Ghostty if missing, supported, and Homebrew is available.
./install.sh --yes --with-ghostty
# Preview a different destination; never modify an active source directory.
./install.sh --check --dir "$HOME/.local/share/pi-extensions/rich-markdown-next"

--check 不写文件、不联网、不执行命令、不弹出确认。非交互环境未提供 --yes 时，取消且不修改内容。单独使用 --yes 不批准 Ghostty；--with-ghostty 是仅限本次调用的独立授权。即使批准了两项，已有兼容终端仍会跳过。每个包管理器命令最多运行 15 分钟；失败时保留副本供检查，不登记验证失败的渲染器，也不回滚包管理器已完成的变更。可选终端安装失败不会撤销已成功安装的插件。Ctrl+C 会取消安装器子进程。请自行打开 Ghostty／Kitty、回到同一目录并运行 pi --continue；安装不会升级 Apple Terminal，也不会迁移正在运行的会话。运行 /reload，再运行 /rich-markdown setup 和 /rich-markdown demo math。拒绝可选安装后，仍可使用文本公式和浏览器预览。

从 0.0.6 或本地 0.0.7 快照升级

本源码专用流程也适用于已发布的 0.0.8。npm 迁移请改用单独流程。

• **已发布的 0.0.6、0.0.7 或 0.0.8：**安装 GitHub 0.0.9 源码快照，而非更早的本地候选快照。保留旧源码目录，直到没有会话使用且不再需要回滚。
• **更早的本地 0.0.7：**版本号相同不代表已安装发布版的功能与修复。默认 rich-markdown-0.0.7 路径中的不同快照会被刻意保留，不会覆盖；无论旧版本标签是什么，都要通过 --dir 为 0.0.9 选择 Git 之外尚未使用的目录。

在发布源码的 Pi/rich-markdown 目录（或独立归档根目录）中操作。先检查只读计划，再显式批准安装到同一个全新目标目录。如果示例目标已存在，请另选目录；不要指向正在使用的副本，也不要在其中原位修复依赖。

./install.sh --check --dir "$HOME/.local/share/pi-extensions/rich-markdown-0.0.9-release"
./install.sh --dir "$HOME/.local/share/pi-extensions/rich-markdown-0.0.9-release" --without-ghostty

批准后的安装器先验证新副本，再仅替换识别出的个人 Rich Markdown 登记，保留无关设置与资源过滤条件。请先处理重复／旧式登记；不要用 pi install 为另一条路径再新增一项，也不要同时加载两份。保留旧副本以便回滚，然后 /reload 或重启 Pi 以启用新登记。本源码安装器不会自动升级、覆盖正在使用的副本或发布到 npm。

缺少 input 和 assist 偏好时，现在使用富输入和输入辅助；缺少 draft 时默认为 false，显式保存的 draft: true 仍启用。使用 input source 回到原生编辑，assist off 只关闭输入辅助，draft on 恢复独立预览区；这些命令均不重写已有草稿。完整 Mermaid／静态 WebP 另外需要已安装 Chrome／Chromium，安装流程不会下载该浏览器。

手动安装与开发

在 Orbit Tools 仓库中进行单次试用，确保没有同时加载另一份 Rich Markdown：

npm --prefix Pi/rich-markdown ci --ignore-scripts --legacy-peer-deps
pi -e ./Pi/rich-markdown/index.ts

首次安装时，将标签快照安装到切换分支的工作副本之外的新稳定目录。如果已经登记 Rich Markdown，请勿运行此登记示例：改用升级步骤，或在测试新副本后手动只替换已有包条目。在仓库根目录获取发布标签后运行：

(
  set -eu
  install_dir="$HOME/.local/share/pi-extensions/rich-markdown-0.0.9"
  test ! -e "$install_dir" || { printf 'Choose a new installation directory.\n' >&2; exit 1; }
  git rev-parse --verify 'rich-markdown-v0.0.9^{commit}' >/dev/null
  mkdir -p "$install_dir"
  git archive rich-markdown-v0.0.9 Pi/rich-markdown | tar -x -C "$install_dir" --strip-components=2
  npm --prefix "$install_dir" ci --ignore-scripts --legacy-peer-deps
  pi install "$install_dir"
)

基于标签的示例要求 rich-markdown-v0.0.9 标签已经发布。更早的本地候选快照标为 0.0.7，但既不是最终 0.0.7 发布版，也不是此次 0.0.9 发布版；不要复用其源码目录。请在新目录中测试开发快照，不要覆盖正在使用的副本。

pi install 只登记个人本地包，不发布任何内容。升级时，先测试新副本，再只替换已有 Rich Markdown 包条目。不要同时登记两份、覆盖整个设置文件，或覆盖正在使用的源码目录。 保留旧副本以便回滚。运行 /reload 或重启 Pi 后，新登记才生效。源码安装不会向 npm 发布包。

命令与配置

/rich-markdown status
/rich-markdown setup
/rich-markdown setup install
/rich-markdown demo
/rich-markdown demo math
/rich-markdown demo blocks
/rich-markdown view
/rich-markdown view demo
/rich-markdown source
/rich-markdown preview
/rich-markdown preview demo
/rich-markdown export
/rich-markdown export demo
/rich-markdown on
/rich-markdown off
/rich-markdown input rich
/rich-markdown input source
/rich-markdown assist on
/rich-markdown assist off
/rich-markdown draft on
/rich-markdown draft off
/rich-markdown math auto
/rich-markdown math text
/rich-markdown images on
/rich-markdown images off
/rich-markdown prompt on
/rich-markdown prompt off
/rich-markdown clear-images

• status（或不带参数的 /rich-markdown）：打开跟随主题、只读的状态覆盖层。摘要按实际渲染模式、终端能力和偏好分组；按 d 查看 worker／图像诊断及配置命令。参见阅读状态界面。
• setup：提供终端相关建议并检测已安装的 Ghostty／Kitty／Homebrew，不修改任何内容。在 Apple Terminal 中解释 Ghostty／Kitty 的要求。不要在不支持的终端强制 PI_IMAGE_PROTOCOL；Pi 设置优先于环境变量。
• setup install：为已有用户提供同样的可选 Ghostty 安装，原生确认对话框显示完整命令。已有兼容终端会跳过。不安装其他 Pi 插件或运行时，不修改终端／Pi 设置或包登记。仅能在 Pi 空闲时启动，拒绝并发重复设置命令；重载／退出会取消活跃安装进程。仅支持 TUI，绝不自动调用。
• demo、demo math、demo blocks：仅显示合成示例，包括高斯积分、巴塞尔级数、小角近似、矩阵、代码、Mermaid 和粉／蓝／绿背景；不请求模型，也不进入模型上下文。
• view／view demo：为最后一条已完成助手回答或合成示例打开图表／图像查看器。Ctrl+Alt+V 打开当前未提交草稿中的图表，不提交内容或替换编辑器；有多项时先显示选择列表。
• source：在 Pi 原生编辑器中打开最后一条已完成助手回答的原始 Markdown／LaTeX，以便选择和复制。编辑结果丢弃，不发送任何内容。这是选择栅格占位符之外的源码复制方式。
• preview／export：只从最后一条已完成助手回答生成私密临时 HTML，排除用户消息、思考和工具。macOS 上 preview 还会打开文件，其他平台显示路径；demo 改用合成内容。这不是永久导出。
• on／off：启用 Rich Markdown 或恢复原生渲染与输入；off 也会停用输入辅助并清除独立预览区，不重写草稿。math auto 在支持时使用图像；math text（兼容别名 math unicode）选择文本公式。
• input rich|source：选择输入框内实时预览或原生源码编辑。input source 也会绕过 Rich Markdown 输入辅助，但不改变独立预览区偏好或会话渲染。它不同于打开最后一条助手回答供复制的 source 命令。
• assist on|off：启用或关闭富输入中的本地输入辅助。assist off 保留输入框内渲染，但将输入原样交给 Pi。Enter 仍提交；配置的换行键用于续写列表／任务／引用。
• draft on|off：只显示或清除编辑器上方独立、只读的实时草稿预览，不再控制输入框内的渲染或辅助。Ctrl+Alt+I 单独为富输入或预览区使用的、被阻止的本地图像打开精确文件确认；不会批准整个文件夹，也不会将图像附加到模型请求。
• images on|off：显式保存 Pi 原生 terminal.showImages 设置并重新加载 Pi，使原生图像组件与插件保持一致。忙碌／压缩中的会话会在保存前拒绝该命令，请空闲后重试。其他命令不改变该偏好。
• prompt on|off：控制交互式 TUI 轮次中的一条稳定 LaTeX 指引，要求行内使用 $...$、独立公式使用 $$...$$。它无法强制模型遵守，也不会重写已有回答；不会把代码、货币或普通符号猜测为公式。
• clear-images：释放插件拥有的 Kitty 图像及可视化缓存，再重新渲染当前内容；适用于外部终端清屏后的恢复或重试失败的图像快照。

偏好位于 <agent-dir>/rich-markdown.json，通常为 ~/.pi/agent/rich-markdown.json。0.0.9 发布版保留 0.0.7／0.0.8 的默认值： enabled: true、math: "auto"、prompt: true、input: "rich"、assist: true 和 draft: false。尊重显式保存的 draft 布尔值，包括已有的 true；缺少 draft 时，现在默认为 false。缺少 input 和 assist 时，默认使用富输入并启用辅助。富输入／辅助要求兼容的默认编辑器；源码模式、自定义编辑器及关闭／不可用的渲染器保留原生输入。独立预览区可与任一输入视图同时使用。已有的 math: "unicode" 配置继续有效。遵守 Pi 的 terminal.showImages、markdown.mermaid、主题和项目信任设置；输入框／预览区中的闭合 Mermaid 围栏现在可以渲染，进入源码块时仍展开可编辑代码。RPC、JSON 和 print 模式均不提供输入辅助、草稿视图、渲染钩子或提示词规则。

阅读状态界面

默认摘要适合常见的 80 列终端，分为四组：

• **Overview（概览）：**渲染器开启、关闭或不可用，当前实际的公式渲染模式，以及选择该模式的简短原因。关闭／不可用意味着使用 Pi 原生渲染，不会误报 Rich Markdown 图像路径正在工作。数学 worker 停止会显示警告；已缓存的图像可能仍然存在。
• Terminal & capability（终端与能力）：终端名称、普通／全屏 TUI 模式、检测到的协议和潜在图像支持。具备能力不等于已启用图像，也不代表某个公式已经完成渲染。
• **Preferences（偏好）：**自动／文本公式、Pi 的 terminal.showImages、实际输入视图及辅助状态、独立草稿预览区偏好，以及用于后续 TUI 轮次的 LaTeX 提示词规则。显式选择源码，或使用自定义／不兼容编辑器时，输入视图显示为原生源码。渲染器关闭或不可用时，预览区不生效；规则已开启但渲染器关闭或尚未初始化时，会注明规则未生效。
• **Commands（命令）：**关闭覆盖层后可运行的终端指引和公式演示。诊断页还列出现有的偏好设置与图像恢复命令；状态界面本身不会执行这些命令。

默认按键：

按键	操作
d	在摘要与诊断之间切换，从所选视图顶部开始
Esc、Enter、Ctrl+C 或 q	关闭并将焦点交回 Pi
Up／Down	内容超出屏幕时逐行滚动
PageUp／PageDown	按页滚动
Home／End	跳到顶部／底部

遵守 Pi 配置的 tui.select.* 取消、确认和导航按键；q、d、Home 和 End 是界面自身的快捷键。需要滚动时，页脚显示实际配置的按键和可见行范围。窄屏按 Unicode 终端列宽折行显示标签／数值，矮屏保留固定页脚并滚动内容。极小屏幕会缩减边框／提示，但仍可用键盘关闭和导航。仅使用普通终端文字、框线和箭头，不依赖 Nerd Font 或专有字体。颜色跟随 Pi 主题，包括覆盖层打开期间的主题变化。

诊断分别显示运行时版本／单元格尺寸、MathJax 任务、保留的 Kitty 图像及本地缩略图。Unavailable（不可用）不是零，Not measured（未测量）不是 0 ms。 最近任务耗时是客户端 worker 时间，不是端到端显示延迟。Pi 提供的单元格尺寸可能是默认值，而非经过确认的测量；保留图像数也不能证明当前正使用图像渲染。界面在宿主重绘时读取内存状态，不使用轮询计时器。

打开、浏览和关闭状态界面不会保存偏好、修改终端设置、添加会话／模型上下文记录、调用模型或启动渲染任务。状态界面不会调用 setup install；引导安装保持独立，必须显式批准。

实时富输入

input: "rich" 时，格式化 Markdown 和已闭合的 LaTeX 显示在 Pi 默认输入框内部，不再仅限于独立预览区。这是以块为单位的实时预览，不是任意公式渲染字形到 TeX 源码的光标映射，也不是完整的所见即所得文档编辑器。

• 当光标位于源码范围之外，或恰好位于块末尾时，完整 Markdown 块会渲染。光标进入范围后，显示整个块的原始源码供编辑；离开或回到块末尾后恢复预览。标题、强调、列表／任务、引用、表格、闭合代码围栏及完整公式复用已有渲染器。普通纯文本保持原生显示。
• 点击渲染块的任意位置，都会定位到其源码起点，而不是指针下的字形。从上方垂直进入时展开源码并定位到起点；从下方进入时定位到最后一个源码字符的位置。点击需要 Pi 的全屏鼠标事件路由；普通模式仍可通过键盘进入。
• 未闭合公式／围栏保留源码。普通代码（包括 tex／latex 围栏）即使带边框／高亮也保持字面内容；只有闭合的 math 围栏可作为公式。闭合 Mermaid 围栏可使用完整引擎预览；未闭合围栏保留代码。无法确定或不安全的显示投影回退为原生源码。
• 完整 LaTeX 遵循 math auto|text：受支持的直接 Ghostty／Kitty 路径使用独立拥有的 Kitty 占位图像，其他环境保留结构化文本／源码。输入框的图像放置与预览区／会话相互独立；绘制预览区不会删除输入框公式。
• 输入框保留 Pi 原生的光标跟随视口：可见行数上限为终端高度的 30%，且该上限至少为五行，不是预览区的 18 行／35% 限制。显示投影限制为 16,384 个源码字符、128 个块、每块 256 个渲染行。文档超限或块不适合投影时，保留可编辑／提交的源码，不用截断文字替换源码。

适配器保留同一个原生 CustomEditor 实例。带 Pi 1.3.0／1.4.0 兼容保护的布局、点击定位及私有编辑方法包装，不替换编辑器工厂，也不将显示投影交换到实际状态。Pi 保留粘贴注册表／展开、撤销、历史、应用／扩展快捷键及光标／IME 标记。渲染从不重写源码或提交内容；Pi 按原生粘贴／提交规则发送源码，而非渲染行。只有下述显式本地输入辅助会编辑草稿文字。原生自动补全期间临时保留源码显示与输入；自定义编辑器及冲突／不兼容覆盖保留原生输入，仍可在上方使用可选预览区。真实终端及 IME 行为尚未验证。

本地输入辅助

assist: true 只在兼容的富输入中启用有上限、确定性的编辑。使用 assist off 可保留实时视图而不改变输入；input source 则回到不含这两项功能的原生源码编辑。两个命令均不重写已有草稿。

输入	行为
Enter	Pi 原生提交操作，不用于续写列表
配置的换行键（tui.input.newLine，默认 Shift+Enter／Ctrl+J）	续写列表／任务／引用标记，保留缩进和标记间距；有序列表递增，续写任务重置为未勾选
空标记处换行	移除列表／任务标记或最内层引用，退出该层，而非提交
成对分隔符	在明确的上下文中插入匹配括号、强调／反引号或显式数学分隔符；重复起始符可形成双分隔符或独立代码围栏
输入结束符／Backspace	跳过由本辅助生成的结束符，或删除本辅助拥有的空对；不将已有／粘贴的分隔符认作自己的配对
可识别数学区域中的 Tab	补全无歧义的本地 frac、sqrt 或希腊字母命令前缀，例如 \fra → \frac{}{}、\sq → \sqrt{}、\alp → \alpha

带参数的补全将光标放入第一个参数；不提供代码片段占位符／Tab 跳转导航。有歧义／未知前缀及普通 Tab 保留原生行为。辅助不调用模型，也不推断正文语义。代码／字面区域、斜杠／shell 命令、括号式粘贴、多字符粘贴／IME 批次及原生自动补全不接受辅助。已有快捷键优先处理；不支持的输入交回 Pi。辅助源码编辑使用原生撤销事务，不在渲染时修改文字。

本地图像与授权

富输入和可选预览区复用同一个有资源上限的图像加载器及精确文件授权。最多选择四个不同的本地图像引用：独立路径（支持引号、反斜杠转义空格、@ 前缀、~/ 和本地 file:/// URL），以及 ![plot](./plot.png) 等 Markdown 图像引用。例如，"./my plot.png" 和 ./my\ plot.png 是路径写法，而非 shell 命令，不执行 shell 展开。不会扫描行内代码或代码围栏来寻找附件。包含数学分隔符的块会保守地将图像引用保留为源码；需要预览时，请将图像放到独立段落。

输入框与预览区图像卡片使用紧凑 [Image · filename] 标签；直接运行 Ghostty／Kitty 时使用可安全滚动的 Kitty 像素占位符，其他路径显示 ANSI 预览或说明标签，两种路径均不需要不透明的原生图像预留行。静态 WebP 在本地浏览器可用时使用其解码器。进入源码块时展开路径／Markdown 语法供编辑；标签不是存储的附件标记。显示前验证 PNG/JPEG/GIF/WebP 结构及内嵌帧尺寸；去除 PNG 附加元数据，GIF 只使用首帧。APNG 和动态 WebP 保持不可用。terminal.showImages: false 时只显示引用标签，两个视图均不读取草稿图像字节。

本地文件授权：启用图像显示时，经过验证、规范化目标位于当前工作目录内的文件可自动读取。目录外目标——包括逃逸工作目录的符号链接及 Pi 剪贴板临时图像路径——会保留标签，直到按 Ctrl+Alt+I 并批准列出的精确规范化文件。授权绑定已验证的文件身份／元数据，不批准整个文件夹、主目录或临时目录根路径。加载器可以在授权前检查路径和元数据，但获得批准前不会读取目录外图像内容；身份变化、拒绝／无法验证或读取失败时，保留被阻止／不可用标签。草稿路径不允许远程获取、网络／UNC 路径或输入中的 data: URL。此授权不会扩大自动会话缩略图的范围，也不替代浏览器预览的独立授权。

草稿 Markdown 图像 token 从不使用会话图像加载器，包括仍保留为源码的引用；只有共享的精确文件加载器才能提供已授权的图像卡片字节。草稿派生可视化数据使用独立于会话可视化的缓存，不只是终端图像放置相互独立。

移除图像引用会丢弃其缓存字节和精确文件权限；重新添加时，目录外文件需要再次授权。过期读取或确认结果不能恢复已移除的草稿；移除其引用也会取消已打开的授权对话框。加载结果是快照，不监听文件变化；如需重试已变化或失败的文件，请移除后重新添加引用。清空／提交编辑器、关闭所有草稿视图、关闭图像显示或卸载时，会清除相应字节／授权。只关闭预览区不会撤销富输入仍在使用的预览；源码输入也可保留已启用的预览区。

渲染不上传内容、不调用模型，不添加会话条目或提示词内容；已有的可选 LaTeX 提示词规则相互独立。图像卡片不能证明图像字节已附加到模型请求。 Pi 粘贴剪贴板图像时插入的是文件路径；Rich Markdown 只预览这些引用。附件元数据、上传及 Pi 的模型附件／提交行为保持不变。读取与渲染限制见隐私与资源限制。

实时草稿预览

原有独立、只读的预览区仍可显示在编辑器上方，但现在默认关闭。通过 /rich-markdown draft on 可与富输入或源码编辑同时使用，也可显示在已有自定义编辑器上方。保留显式保存的 draft: true；缺少 draft 时为 false。draft off 只控制该预览区，不控制输入框内渲染或输入辅助。

预览区在宿主重绘时读取文字，不轮询。视口跟随草稿末尾，最多占 18 行及终端高度的 35%。省略的前文会有标记；矮屏可能只显示较少卡片或一个标题。源码超过 16,384 字符时，预览区显示暂停提示，完整源码仍可编辑和提交。斜杠命令／shell 命令不作为 Markdown 提示词预览。清空／提交编辑器、draft off 或 off 会清除预览区。

预览区中的完整公式使用 Kitty 占位符或结构化文本／源码回退。terminal.showImages 允许时，本地图像卡片和闭合 Mermaid 围栏在直接 Ghostty／Kitty 中使用适配尺寸的 Kitty 占位符，其他路径显示有上限的 ANSI 预览或说明标签。两个草稿视图遵守同一本地图像授权。

渲染与终端支持

下表描述的是会话公式。输入框内和预览区的公式仅在受支持的直接 Ghostty／Kitty 路径使用 Kitty 占位图形，其他环境保留结构化文本／源码；它们不使用原生公式图像预留行。本地图像卡片遵循上文分别说明的输入框／预览区行为。

终端路径	行内 LaTeX	独立 LaTeX
直接运行的 Ghostty／Kitty	可读时使用基线对齐的单行图像	居中图像，支持引用、列表及真实自定义／Translator 卡片
其他 Kitty 协议终端	文本	顶层、无背景块中的原生图像
iTerm2 协议、普通模式	文本	顶层、无背景块中的原生图像
iTerm2 协议、全屏模式	文本	文本；Pi 在全屏中禁用此协议
Apple Terminal、tmux／screen、不支持的路径	文本	结构化文本或完整源码

这是按能力选择的路径，不保证所有终端版本表现相同。过高的行内公式保留文本，不会无限缩小；表格中的行内公式仍为文本。大型分式和矩阵应使用独立公式。原生换行会拆开的行内图像也会回退为文本。栅格图像不是可选择的数学文字，请用 source 或浏览器预览。终端自己的滚动历史已经打印，无法追溯修复。像素外观、字体变化和 GPU 行为仍需真实终端验证。

已闭合的 $...$、\(...\)、$$...$$、\[...\] 和 闭合的 math 围栏可在回答结束前渲染。未闭合内容保持可读，不为瞬时前缀排队。普通代码（包括 tex／latex 围栏）保持字面内容。不会安装第二套终端渲染器或修改 Pi 源码。

MathJax 在有资源限制的 worker 中产生 SVG 路径，Resvg 在严格匹配终端单元格的画布上生成透明 PNG，通常为双倍密度。几何信息与受宽度／主题影响的栅格分开缓存。worker 完成后以 32 毫秒窗口合并重绘请求，这不是固定延迟保证；没有轮询会话的计时器。支持图像的会话预热 worker，纯文本会话不承担这项启动成本。等待图像时先显示文本，完成后原位升级。

Kitty Unicode 占位单元格携带图像网格及会话内稳定的图像 ID。像素通过已有的宿主终端写入接口，在帧之后上传，而不是嵌入可见 Markdown 行，因此保留换行和卡片背景。可恢复的实例级观察器处理相同尺寸的清屏、强制重绘、停止／启动恢复及几何变化。上传去重，只删除自身拥有的 ID；达到预算后拒绝新增图像，而不是驱逐仍被缓存行引用的像素。不使用下划线颜色 SGR 编码，避开 Pi 1.3.0 ANSI 跟踪器的不兼容。详见渲染设计与研究（英文）。

图表、图像与缩放

TUI 现在使用随包提供的 Mermaid 12.2.0 完整引擎，不再仅依赖较小的文本图表转换器。检查时这是 registry 的最新版本；仍采用锁定版本，不自动升级。回归示例覆盖全部 37 个已注册图表变体，包括流程／ELK、时序、类／状态／ER、甘特、饼图、用户旅程、Git、思维导图、时间线、象限／XY／雷达图、需求、桑基、块／数据包、架构、看板、树状矩形、C4、智能体流程、泳道、树视图、事件建模、鱼骨、Venn、用例、Wardley、Cynefin 和铁路语法图。这是已注册变体的覆盖，不代表所有可能输入或第三方插件都可用。

完整图表同时适配宽度与高度，保留整个绘图，不会仅因过宽／过高就截断标签或退回源码。大型绘图缩小时文字可能较小：运行 /rich-markdown view，或对未提交草稿按 Ctrl+Alt+V。查看器按所选视口从原始 SVG 或已授权的完整分辨率图像重新栅格化，不是放大缩略图。放大后有意显示可平移的局部；Fit 恢复全图。语法无效、缺少 Chrome、安全限制或资源耗尽时显示不可用说明，不倾倒原始代码。未闭合围栏、显式关闭 Mermaid 和源码编辑按设计保留源码。

控制	操作
+／=／-，或 [+]／[-]	放大／缩小
f／0，或 [Fit]	适配完整绘图
1，或 [1:1]	在视口缩放上限内恢复原始像素比例
方向键	平移
Esc、配置的取消键、q 或 [Close]	关闭并恢复焦点
Ctrl+滚轮；终端转发的双指滚动	以指针位置为锚点缩放
滚轮／Shift+滚轮；左键拖动	垂直／水平平移；拖动平移

指针控制要求 Pi 全屏模式及终端转发事件。普通模式保留键盘操作。Pi 1.3.0／1.4.0 不提供原生触控板捏合手势；终端可能将捏合用于改变字体大小。直接 Ghostty／Kitty 提供像素预览；其他路径（包括 iTerm2 中的此查看器）显示标明类型、最多 64 列 × 20 行的 ANSI 预览。ANSI 不等于可读的完整分辨率图形。Pi 的图像偏好始终优先。

会话中的独立图像可从 cwd 内的本地文件或有上限的内嵌栅格数据显示；远程图像和正文行内图像保留引用。草稿卡片继续使用既有精确文件授权。显式查看器可为所选目录外文件重新请求仅限本次调用的授权，不批准整个目录、不上传附件。不获取远程 TUI 图像，请使用单独确认的浏览器预览。PNG/JPEG/GIF 不需要 Chrome，GIF 使用首帧；静态 WebP 要求 Chrome，拒绝动态 APNG／WebP。

Mermaid 按需通过私有 DevTools 管道启动启用沙箱的无头浏览器，使用临时 0700 配置目录、受保护的严格模式配置、CSP 和请求阻止。不监听服务器端口、不下载浏览器，不使用外部字体／图标／图像、图表回调或模型请求。支持安全的标题／frontmatter 和普通图表语法，不接受活跃 HTML／资源指令及不安全配置。浏览器空闲 30 秒或正常关闭时退出；崩溃可能遗留临时配置目录，删除前应先检查。浏览器自身缓存及终端日志不在“仅内存”保证范围内。

公式之外的富 Markdown

• 六级标题、嵌套列表／任务和保留序号；带边框、对齐、可换行的表格，在窄屏转为逐条记录。
• 带语言标签的边框式语法高亮代码，保留缩进、连续空格、空行和字面内容。
• 原生强调、删除线、引用和分隔线；支持时使用安全的 OSC 8 链接，否则显示目标。不激活可执行链接协议；原始 HTML 作为源码显示，不执行。
• Markdown、Box 和 Text 区域的整行背景，包括留白、嵌套背景、重置，以及缓存／主题／尺寸变化后的重绘。不会将普通 Text／日志重新解释为 Markdown；原生图像预留行不受影响。
• 仅显示时恢复简短翻译 CJK 冒号标签，如 **说明：**正文 和 **说明： **正文；保留代码、转义、较长分隔符、token 和已存源码。推荐可移植写法 **说明**：正文 或 **说明：** 正文。
• 结构化文本公式使用 KaTeX 公共 MathML，支持分式、根式、上下标、极限、矩阵、分段和对齐。不支持的语义保留原生／紧凑／源码回退，不丢弃符号含义。整体居中而非逐行居中，不会把二维分式随意折行。
• 完整引擎 Mermaid 和有上限的本地栅格预览，包括实时草稿的闭合围栏，提供自动适配与缩放／平移查看器。只在显示过程中绕过原生纯文本 Mermaid 转换；源码、已存消息和 Pi 设置保持不变。
• 会话／输入框／预览区／查看器拥有独立图像放置。远程及正文行内图像保留引用，不新增 TUI 图像获取或模型上传。

隐私与资源限制

显式批准的安装会访问已配置的 npm registry 或 Homebrew／应用下载服务，并使用其正常缓存；不发送会话内容，也不调用模型。引导式源码安装器丢弃包管理器输出，不将其保存到 Pi 会话；Pi 管理的 npm 安装使用 Pi／npm 的正常输出与日志。包管理器可能保留自己的日志／缓存，并安装自身所需依赖。仅对安装器子进程禁用 Homebrew 自动更新、分析上报和 sudo 使用（HOMEBREW_NO_SUDO=1），不修改全局偏好。子进程没有交互式标准输入；需要密码／认证时会失败，不自动处理。取消时先发送 SIGINT，再向所拥有的进程组及已观察到的后代发送 SIGKILL，包括 Homebrew 单独建立的命令进程组。每次发送信号前，有上限的 ps 快照都会重新核对进程 ID、进程组及启动时间，不读取参数或环境。元数据缺失或变化时，不向后代进程／进程组发送信号；仅仍存活的直接子进程可使用备用信号路径。检查和 POSIX 信号发送并非原子操作，启动时间精度也受平台限制，因此进程逃逸或无法核实时只能尽力清理。这不是操作系统沙箱。设置流程不启动应用、不修改 shell 配置、不强制图形协议，也不在会话启动时安装内容。本地设置备份可能含私密信息，请保持私密，并在不再需要时自行删除。

公式源码和 TUI 栅格保留在内存中，另会通过图形字节流发往终端；不会加入消息或主动记录／保存。终端日志、滚动历史和终端自身的图像缓存不受插件控制。worker 诊断被丢弃。渲染器不是操作系统沙箱。

自动本地会话图像读取仍限制在工作目录内。不支持的平台和网络／UNC 路径在任何文件系统访问之前拒绝。检查符号链接及实际打开的描述符：macOS 使用 /usr/sbin/lsof，Linux 使用 /proc/self/fd；缺少验证时保留引用。拒绝 FIFO／非普通文件。包括原生 Windows 在内的不支持平台不会读取无法验证的本地图像。

草稿使用独立的精确文件加载器，遵守相同的平台／描述符验证要求，不扩大会话允许列表。目录外授权仅保留在内存，绑定规范化路径以及设备／inode、模式、大小、修改／状态变更时间戳；在打开和读取前后重新核对。路径替换或文件变动会安全拒绝。移除引用、清空／提交草稿、关闭所有草稿视图或图像显示、卸载时，会撤销对应授权。输入框和预览区共用此加载器：仅执行 draft off 不会撤销富输入仍在使用的文件授权。两个预览均不会主动记录、保存或上传草稿文字和图像字节；终端输出／缓存仍不受其控制。不获取或解码输入中的远程／data: 图像。已授权本地文件在内部生成的栅格数据只用于渲染交接，不代表允许加载任意内嵌输入。

适配器从不将草稿图像 token 交给会话加载器。所选草稿图像引用变化、清空／提交草稿、关闭所有草稿视图或图像显示、释放草稿服务时，还会清除共享可视化缓存及输入框／预览区放置，并退出其 worker／浏览器；过期结果不能恢复已撤销的数据。光标／布局变化只清除受影响的图像放置，不清除已缓存可视化数据或文件授权。显式查看器保留自己的独立、仅限本次调用的已授权快照，直到关闭。

浏览器预览必须显式调用。远程图像要求每次预览单独确认，提示显示主机名而非私密查询参数。批准仅允许有上限的公共 HTTPS 请求／重定向，不发送会话；URL 自身仍可能携带敏感参数。拒绝凭据、自定义端口、局域网／回环／链路本地地址和不安全协议；固定 DNS 结果并重新验证每次跳转。不转发 Cookie、认证头或 Referer。

HTML 嵌入本地字体、KaTeX CSS、Highlight.js 和 Mermaid，不使用 CDN。CSP 阻止外部连接、框架、表单和任意脚本；仅允许带 nonce 的内置 Mermaid 以严格模式运行，不启用初始化指令、点击处理器或外部图标包。不加载外部 SVG／HTML 图像。主动点击普通链接仍会访问目标。标题 slug 处理重复项，预览包含目录和脚注。

资源上限包括：

• 富输入：源码 16,384 字符、128 个块、每块 256 个渲染行；原生视口上限为 max(5, floor(terminalRows * 0.30))。超限／不安全的显示投影回退为源码。输入辅助使用相同源码上限，最多保留 32 个自己生成的分隔符对。
• 独立预览区：源码 16,384 字符；末尾视口最多 18 行／终端高度的 35%，源码超限时显示暂停提示。这些是预览区限制，不是富输入框限制。
• 共享草稿图像：最多四个本地引用，单文件 8 MiB／原始文件字节总计 16 MiB（不是 base64 字符串长度），400 万像素、每边最多 8,192 像素。串行读取，每次五秒期限；超时的操作系统操作必须退出并关闭描述符，才能启动下一个读取器。未变化的失败条目不会每次重绘都重试。
• 临时输入／预览区公式共享一个有上限的惰性 worker／缓存，与会话公式相互独立。输入框每次显示投影跨所有块最多准入八个图像请求；预览区每次组件渲染最多八个。输入框、预览区及会话各自拥有独立 Kitty 放置／传输预算。下述 worker／缓存上限按每个缓存适用，传输上限按每个传输器适用。
• 会话数学：8,192 字符源码、每次组件渲染最多 64 个图像请求、排队／活跃任务共 32 个和 256 KB 请求存储、每任务五秒期限、最多一个活跃或退出中的 worker。worker 损坏或连续三次超时后，重载前不再启动新 worker。
• SVG 几何：128 项／4 MB／4,096 次尝试。栅格：96 项／16 MB／4,096 次尝试。已驱逐／失败请求不会因重绘无限重试。Kitty 传输：保留 128 张图／16 MB 编码数据／3,200 万解码像素，最多 4,096 个 ID 键。PNG 不超过 2 MB／400 万像素；单元格画布每边不超过 4,096 像素，独立公式最多 32 行。
• 结构化数学：源码 2,048 字符、1,024 节点、深度 48、256 × 64 单元格、8,192 个占用单元格及累计工作预算；128 个缓存结果／约 512 KiB。仅在完整可视化回调不可用时，旧纯文本 Mermaid 适配器保留 8,192 字符／160 行的限制。
• 缩略图：输入 8 MiB、400 万像素、最长边 8,192；输出最多 64 × 40 像素／20 行，不放大。八个任务／24 MiB 请求文本、五秒期限、96 项缓存／512 KiB RGBA、4,096 次尝试。同路径文件及失败／驱逐结果只在重载后重试。
• 完整可视化所有权：一个会话缓存、一个由富输入与独立预览区共用的 draftCache，以及每个显式查看器各自独立的缓存。队列、worker、结果缓存和浏览器布局预算按每个缓存适用，不是整个会话共用，也不是每个草稿块各有一份。各显示区域保留独立图像放置；撤销草稿数据不清除会话或查看器缓存。每个查看器关闭时清理自己的缓存。
• 每个完整可视化缓存：Mermaid 源码 64,000 字符、1,000 条边／矢量图元、20,000 个 DOM 节点；每任务 15 秒、浏览器启动 10 秒。八个待处理任务／24 MiB 请求存储；64 个完成结果／16 MiB，128 个失败结果／30 秒；16 个 SVG 布局／4 MB。视口最多 240 列 × 100 行、每边 4,096 像素／400 万像素／2 MB PNG。相对于适配比例的缩放范围为 0.25–4,096 倍，只合并处理最新视口。会话内嵌预览最多 24 行／终端高度的 60%，草稿预览适配更小的视口。自动会话图像快照最多保留 64 个引用／24 MiB 编码字符串存储；clear-images 可重试。图表选择限制为 256 KB Markdown／64 项，内嵌引用限制为 256,000 字符。原始栅格输入继续限制为 8 MiB／400 万像素／每边 8,192 像素。
• 预览：256 KB Markdown，128 个公式、每个最多 8,192 字符；24 个图表、每个最多 50,000 字符／500 条边；12 个不同图像、每个 8 MB／包含重复引用在内共 24 MB；网络总期限 20 秒、单次五秒、最多两次跳转。

预览目录权限为 0700、HTML 文件 0600；最多保留八份，正常重载／关闭时删除。崩溃可能留下临时文件；浏览器内存／历史和用户另存副本不由插件清理。

验证

cd Pi/rich-markdown
npm ci --ignore-scripts --legacy-peer-deps
npm run check
npm test
npm run test:package
npm audit --omit=dev
bash -n install.sh
node --check scripts/install.mjs

请在源码工作副本中运行这些开发检查，而非 npm 包内。独立源码快照请省略 cd Pi/rich-markdown，在快照根目录运行。发布元数据检查验证包内完整 MIT 声明，不依赖仓库祖先目录；隔离回归还会拒绝缺失或损坏的声明，不递归执行测试。仅在 Orbit Tools 仓库工作副本中，另外从仓库根目录运行 cmp LICENSE Pi/rich-markdown/LICENSE，检查与根许可证相等。该仓库专用比较独立于独立源码的 npm test。

test:package 也包含在 npm test 中：它打包含合成隐私探针的隔离目录，核对精确包路径／字节，并通过所选真实 Pi 宿主、复用工作副本的锁定库，从真实 node_modules 路径加载解包后的包。它验证原生数学／缩略图／可视化 worker、随包预览资源，以及 Pi 的 npm 名称／过滤登记规则，不访问 registry 或修改正在使用的设置。

完整测试要求 macOS／Linux、配套且版本恰好为 1.3.0 或 1.4.0 的 Pi SDK/TUI，以及仓库中的 Translator 卡片。使用 PI_SDK_PATH 对每个受支持的宿主分别运行一次；测试和基准测量向兼容保护传入实际加载的 SDK 版本。未知版本（包括其他补丁版本、预发布及带构建后缀的版本）和不配套的 SDK/TUI 均被拒绝。真实浏览器可视化测试还需要已安装 Chrome／Chromium；缺失时显式跳过，不算浏览器验证通过。RICH_MARKDOWN_BROWSER 可选择非标准可执行文件。宿主发现不依赖作者的主目录。PI_SDK_PATH 指向目标 SDK 的 dist/index.js，TUI 从同一安装解析；独立副本还需设置 PI_TRANSLATOR_CARD_PATH 指向 Translator 的 pi/card.mjs。缺依赖会失败，不会静默跳过。类型检查在内存中解析声明，不生成宿主文件。不支持原生 Windows 完整测试；使用 mock 测试其无文件系统回退，不访问真实网络共享。

**0.0.9 验证（2026-10-28，macOS，Node.js 26.12.0）：**修复后的 npm run check 和 npm test -- --test-concurrency=2 在官方配套 SDK/TUI 上通过：Pi 1.3.0 为 687 项测试、Pi 1.4.0 为 691 项，无失败／跳过。锁定依赖安装及全部 31 项发布策略测试通过。源码依赖树和全新隔离 npm 包安装的生产依赖审计均为零漏洞。真实安装后的包在两个宿主上通过原生 worker／预览加载，以及隔离 Pi CLI 安装／重复安装／列出／移除测试；未使用正在运行的设置或安装。普通 ESM 栅格验证器与原 TypeScript 实现去除类型后生成的 JavaScript 字节完全一致。批准发布需要对已提交的 0.0.9 候选运行基于提交的验证器，与届时的 origin/main 比较；打标签／发布前，还需将发布合并提交与其第一父提交比较验证。这些是独立的发布门槛，并不宣称已经获批或发布。真实终端图形、IME 和 Linux 执行仍未验证。

**先前 0.0.8 的 Pi 兼容验证（2026-10-22，macOS，Node.js 26.12.0）：**更新后的源码在通过 PI_SDK_PATH 分别指定的两个宿主上通过 npm run check 和 npm test：Pi 1.4.0 为 688 项测试、零跳过，Pi 1.3.0 为 684 项测试、零跳过。1.4.0 新增的四项覆盖原生 CJK 强调、未闭合公式／表格解析，以及另一个真实 Pi 对话框位于草稿授权上方／下方时的取消。锁定依赖安装、npm audit --omit=dev（零漏洞）、shell 语法及安装器语法检查均通过。这些是本地合成／宿主检查，不代表真实终端或 Linux 验收。

草稿回归测试覆盖：源码／代码及未闭合公式保持字面内容、路径解析、命令／默认值、清空／提交／关闭后的清理、拒绝过期结果、精确文件授权／撤销、符号链接／元数据竞态、串行读取期限及字节／像素限制。test/editor.test.mjs 与 test/editor-assist.test.mjs 覆盖输入框内整块渲染／源码展开、光标／鼠标导航、原生粘贴／撤销／提交及快捷键、Unicode 列宽、自定义编辑器／自动补全回退、独立图形放置、可恢复钩子、列表／任务／引用续写、自生成配对及无歧义数学补全。这些说明回归范围，不是最终测试运行结果。最终发布验证需要修复后的实测检查；更新日志本地候选历史中的较早测量只适用于对应快照，不能作为最终发布的验证。

真实终端图形、IME 行为和 Linux 执行仍未验证。仍需人工检查输入、撤销、自动补全／历史、IME 定位、剪贴板／路径粘贴、拒绝／批准授权、尺寸变化，以及图形和纯文本终端中的两种 TUI 模式。请确认整块源码展开、原生源码准确提交、显式辅助可撤销，以及仅关闭预览区后富输入仍保持活跃。自动光标标记／协议测试不能证明真实输入法候选窗口或像素行为。

测试使用合成内容、隔离配置、真实 Pi 组件／扩展加载、xterm 单元格模拟及模拟 HTTPS，不使用凭据或付费模型调用。覆盖流式闭合、真实自定义／Translator 卡片、源码不变、字面代码、源码复制／提示词控制、图像偏好重载、换行／ANSI 属性、两种 TUI 模式、相同尺寸重绘／恢复、缩放／覆盖层、状态命令加载及键盘焦点／滚动／关闭、状态主题／Unicode／窄屏处理和停用／回退状态、缓存／worker 限制、目录范围／SSRF、预览授权及清理。实际数量和未完成的平台检查见发布说明；自动协议／单元格测试不能证明真实图像质量或浏览器外观。安装器测试使用合成包／应用清单、隔离设置及模拟 npm／Homebrew 命令；通过真实 Node 子进程验证取消与参数处理。这些测试不会安装桌面终端，也不能证明真实 Homebrew／发行版下载一定成功。

运行 node scripts/benchmark.mjs 可测量合成公式从闭合到出现占位符的耗时，经过真实助手组件、worker 和 32 毫秒重绘调度，不包含终端传输／GPU。可选合成图：node test/kitty-proof.mjs 将实际传输的 PNG 合成为单元格网格；FORCE_COLOR=3 node test/render-proof.mjs 生成文本单元格图（可加 --math／--inline）。两者打印私密临时目录，结束后自行删除；它们不是实时截图，系统字体回退可能不同于终端。请在 Ghostty／Kitty 和 Apple Terminal 中人工检查全部演示，并在浏览器检查 preview demo。如果浏览器工具阻止本地文件，不要启动服务器绕过限制。

版本、回滚与移除

0.0.9 准备首次 npm 分发；更早版本是 GitHub／源码发布，不是 npm 回滚目标。日期为 2026-10-19 的 GitHub 0.0.7 发布接续已发布的 0.0.6。此前已标为 0.0.7 的快照明确保留为本地候选历史，不是第二次 GitHub 发布或额外标签。0.0.4 是首次仓库源码发布。更早的本地序列 0.0.1 → 0.0.2 → 0.0.3 只是记录的历史，不是可独立恢复的 Git 发布。参见更新日志及导入来源（英文）。开发分支为 rich-markdown，发布标签为 rich-markdown-v<version>。保留包身份、命令和持久化条目 ID。依赖／Pi 版本独立于插件版本，旧演示条目不迁移。

使用 off 可立即回退为原生渲染／输入并清除预览区。input source 停用富输入及其辅助，但不改变会话渲染或预览区偏好；assist off 只关闭输入辅助；draft off 只关闭独立预览区。所有操作均保留已有编辑器源码。从 npm 回滚时，先停止使用它的会话并仅移除其 npm 登记，再登记上一稳定源码路径、恢复原过滤条件并重新加载。不要尝试安装未发布的旧 npm 版本，也不要保留两个活跃副本。移除此 npm 版本时，运行 pi remove npm:fhgs-pi-rich-markdown@0.0.9（项目范围加 --local），再重启／重载 Pi。卸载稳定源码副本运行 pi remove /absolute/path/to/that/copy，再 /reload；旧式 local/rich-markdown 只需从 Pi 设置移除对应条目。卸载后可按需删除该包目录和 <agent-dir>/rich-markdown.json（其中包含 input、assist 和 draft 偏好）。精确文件草稿授权仅保留在内存，无需删除额外的权限文件。不要删除其他扩展、设置或会话。崩溃后先检查遗留的 pi-rich-preview- 和 pi-rich-visual- 临时目录再删除。不再需要时自行移除 RICH_MARKDOWN_BROWSER 覆盖项；移除此包不会卸载 Chrome／Chromium。已保存的合成演示条目保留。Ghostty／Kitty 与 Homebrew 是独立应用：移除 Rich Markdown 不会卸载它们或其依赖。安装器产生的设置备份及失败稳定副本会保留，供自行检查／清理；不要用旧设置备份覆盖较新的无关变更。

许可证

MIT。依赖许可证与声明随各包保留。设计参考（英文）注明相关 Pi 扩展和图形规范；本包不安装、也不依赖这些可能冲突的渲染器。