# agent-markdown-preview 中文文档

规范地址：https://npmcn.com/package/agent-markdown-preview/

版本：0\.13\.3
npm 元数据更新时间：2026-11-03T01:53:06.075Z
中文译文更新时间：2026-11-03T02:15:29.750Z
软件包许可：MIT

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/agent-markdown-preview
原文对照：https://npmcn.com/package/agent-markdown-preview/?lang=original
项目主页：https://github.com/omaclaren/agent-markdown-preview#readme
源码仓库：https://github.com/omaclaren/agent-markdown-preview

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：788 kB，102 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：2 个
- 首次发布：2026-09-25T05:01:18.937Z
- 最新版本发布：2026-11-03T01:53:05.917Z
- 已发布版本数：23（近 12 个月 23 个）

## 中文简介

浏览器预览编码代理响应（Claude Code, Codex, Pi, OpenCode）和本地Markdown， LaTeX，代码和diff文件，具有数学，语法高亮显示和Mermaid。

## 安装

```sh
npm install agent-markdown-preview
```

也可以使用：`pnpm add agent-markdown-preview`、`yarn add agent-markdown-preview`、`bun add agent-markdown-preview`

## README

# agent-markdown-preview

在浏览器中预览编码代理响应 [克劳德代码](https://docs.claude.com/en/docs/claude-code)， [食典委](https://github.com/openai/codex)， [π](https://pi.dev/) 或者 [OpenCode](https://opencode.ai/)． 每个会话都有一个选项卡，显示其响应，其中包含数学、语法高亮显示和Mermaid图表，并且可以实时跟踪每个回合，显示提示、工具调用和代理记录的结果。它读取每个代理已经写入的会话历史，因此不需要设置代理。它还可以预览本地Markdown、LaTeX、代码和diff文件。

在项目目录中运行它，以获取该项目最近会话的索引，或使用 `agent-markdown-preview --all` 浏览按项目分组的目录。每个项目也有一个来自其任何会议的最新完成响应的合并预览。

## 截图

截图使用合成会话。

**项目的会话索引：**

![Session index](https://npmcn.com/package/agent-markdown-preview/screenshots/index.png)

**响应预览，遵循系统亮/暗设置：**

| 光 | 黑暗 |
| --- | --- |
| ![Light preview](https://npmcn.com/package/agent-markdown-preview/screenshots/preview-light.png) | ![Dark preview](https://npmcn.com/package/agent-markdown-preview/screenshots/preview-dark.png) |

## 安装

```bash
npm install -g agent-markdown-preview
```

或者在不安装的情况下运行 `npx agent-markdown-preview`.

你需要Node.js 22或更高版本（22.13+读取OpenCode的数据库）和 [Pandoc](https://pandoc.org/installing.html) （`brew install pandoc` 在macOS;集 `PANDOC_PATH` 如果不在你的 `PATH`）. 美人鱼图、一些方程式和PDF图形的MathJax回退会在页面第一次需要时从jsdeliver或unpkg加载固定模块，因此这些功能需要网络访问。它是在macOS上开发和测试的，应该也可以在Linux上运行，并且没有在Windows上测试过。

## 快速启动

在使用代理的项目目录中，运行：

```bash
agent-markdown-preview --live
```

这将打开项目最近代理会话的索引。打开一个会话以获得一个选项卡，该选项卡显示代理完成其回合时的每个响应，点击之前的响应即可。 **工作**，在每个响应旁边显示提示、工具调用和导致响应的结果。打开 **按照活动** 在工具栏中（或按Ctrl+Alt+A）观看工作中的每个回合；当这个回合结束时，页面返回到响应。关闭Follow活动后，标签会在每个回合后更新。

![Live: a turn in progress, with a tool call still waiting for its result (synthetic session)](https://npmcn.com/package/agent-markdown-preview/screenshots/live.png)

Working将记录的提示和工具输出显示给具有选项卡链接的任何人。仅对于响应，运行 `agent-markdown-preview` 没有 `--live`． 预览仍然会在每个回合结束时自动更新； `--live` 在Working中添加正在进行的活动。

## 使用

| 命令 | 描述 |
| --- | --- |
| `agent-markdown-preview --live` | 会话索引与工作和 [生活](https://npmcn.com/package/agent-markdown-preview/#readme-live-and-working) |
| `agent-markdown-preview --working` | 没有Live也是一样 |
| `agent-markdown-preview --repl` | 添加 [REPL页面](https://npmcn.com/package/agent-markdown-preview/#readme-shared-repl-sessions-optional)：共享的REPL会话最近的记录提交 |
| `agent-markdown-preview` | 会话索引，仅响应 |
| `agent-markdown-preview --all` | 最近的会话跨目录，按项目分组 |
| `agent-markdown-preview --merged` | 在这里预览任何会议的最新回应 |
| `agent-markdown-preview --session <path|ses_id>` | 预览单个会话日志或OpenCode会话 |
| `agent-markdown-preview <file>` | 预览Markdown、LaTeX、代码或diff文件并跟踪其更改 |

| 选项 | 描述 |
| --- | --- |
| `--agent claude,codex,pi,opencode` | 要遵循的代理（默认值：所有） |
| `--cwd <dir>` | 要遵循其会话的项目目录（默认：当前目录） |
| `-a`， `--all`， `--all-projects` | 从每个文件夹中跟踪最近的会话 |
| `--opencode-db <path>` | OpenCode数据库读取，而不是默认值 |
| `--history <n>` | 每个预览都以早期响应开始（默认值为10，最大值为20；0只显示最新的） |
| `--theme <name|file>` | `agent` (默认), `neutral`， `claude`， `codex`， `opencode`， `pi`， `pi-studio`， `auto`,一个 `-light`/`-dark` 变体，或者Pi主题 `.json` 文件 |
| `--agent-theme <agent=theme>` | 一个代理的调色板，例如。 `pi=pi-studio`;可重复的 |
| `--appearance <mode>` | `system` (默认), `light` 或者 `dark` |
| `--font-size <px>` | 基础字体大小 |
| `--open` / `--no-open` | 总是/从不打开浏览器选项卡 |

### 生活和工作

Working显示了响应的记录提示、进度、任何公开的推理，以及它的工具调用和结果。提示开始扩展，活动开始折叠。命令、文件读取和编辑具有可读视图，可以使用记录的JSON，并且可以放大记录的图像。发送到共享REPL的代码(pi-repl、代理- REPL或 [π工作室](https://github.com/omaclaren/pi-studio))显示它的运行时和代码，而它的结果只显示输出，并以它所属的调用为标题。克劳德的问题显示了选项和给出的答案。 **Ctrl + Alt + P** 和 **Ctrl + Alt + W** （macOS上的控制+选项）在预览和工作之间切换。 **Ctrl + Alt + L** 从任何视图转到预览中的最新响应，包括较早的工作页。Working在会话预览中可用，而不是文件预览。

与 `--live` 和 **按照活动** 开启时，页面开始时移动到工作状态，结束时返回预览状态。如果你向上滚动或移动到另一个页面，它会把你留在那里。更新到达时，代理会记录它们，而不是逐个标记，因此工具调用在记录结果之前显示“尚未记录结果”。对于OpenCode （v2会话），一旦OpenCode记录完整的文本块，就会出现文本块，当工具完成时，就会出现工具的输出。 法典任务如果没有最终答案（如压缩）而结束，则返回到最新的预览。在索引单独列出的新会话日志中，一个恢复的法典线程继续运行。Live漏掉的任何内容，比如超出显示限制的卡片，都会在状态行中列出。

**隐私:** 提示、工具输出和记录的图像可能包含秘密，并且没有任何内容被编辑。只与你信任的人分享这些链接。Working使用自己记住的凭据，因此您从普通预览中共享的链接不会获得此访问权限。停止 `--live` 或者 `--working` 进程撤销它。

有些内容可能会被缩短或省略； [细节](https://npmcn.com/package/agent-markdown-preview/docs/details.md#working) 列出了工作读取的内容及其限制。

### 共享的REPL会话（可选）

这是可选的，关闭，除非你要求它。它适用于 [pi-repl](https://github.com/omaclaren/pi-repl)，代理-回复和 [π工作室](https://github.com/omaclaren/pi-studio)，其共享的REPL会话在tmux中运行；没有他们，把它关掉。

`--repl` 添加一个 **REPL** 页面，在“预览”和“工作”旁边，用于与共享的代理一起工作 [pi-repl](https://github.com/omaclaren/pi-repl) 或者代理-应答会话。它列出了pi-repl的共享会话(`pi-repl-python`， `pi-repl-julia`,……)。打开其中一个，在它们到达时跟踪它最近的记录提交：谁发送了每一个（一个代理的名字；一个人的名字） **用户**，或者根据发送工具记录的发送方式的名称，例如 **Sam·via终端**;Pi工作室的发送者说 **via Pi Studio**)、状态和时间、代码（高亮显示）和输出。图像和PDF文件提交的代码或输出名称，并在运行时写入，例如保存的绘图(`plt.savefig("attachments/fit.png")`)，在它下面显示：图像缩略图，pdf作为链接，每个打开一个新的选项卡。相对路径根据会话的工作目录解析。只在窗口中显示的绘图不会被捕获，提交只读取或在运行前写入的文件也不会被捕获；后来提交重写的文件显示在该文件下。如果pi-repl将会话记录标记为保存在与预览的记录目录不同的记录目录中(一个不同的 `TMPDIR`（比如），页面是这么说的，而不是显示出来的；只有这些工具的旧版本写的记录，没有标记，但据说未经证实。 **选择/ Alt +离开了** 上升，从会议到列表，从那里到预览，然后 **复制链接** 将链接复制到另一个浏览器的会话。这个 **REPL** 链接, **Ctrl + Alt + R** （控制+选项在macOS上）返回到REPL页面，你最后在该选项卡上，所以你可以快速切换它，预览和工作。它无需等待响应即可进行更新，并且独立于 `--live`． 添加 `--live` 并在Working中跟踪代理正在进行的活动。直接输入到终端的代码不在记录中，所以它不会出现在这里。

页面只读取：它从不运行或发送代码，并且在不更改任何内容的情况下检查tmux。它显示了一个会话的生命周期；如果会话结束或新会话以相同的名称开始，它会这样说，而不会遵循新会话。

#### 演示

[![Shared REPL code and inline figures in the browser preview](https://npmcn.com/package/agent-markdown-preview/docs/assets/demo-poster.png)](https://omaclaren.github.io/agent-markdown-preview/#demo)

[观看一分钟的演示](https://omaclaren.github.io/agent-markdown-preview/#demo)：可选 `--repl` 页面显示了由Pi、一个操作符和Claude code共享的Python会话中的代码和绘图。录音使用自动输入，并对内部元数据进行编校。 [关于共享的REPL](https://omaclaren.github.io/agent-repl/).

**隐私:** REPL页面将使用这些会话的任何代理或项目的代码和输出（包括将来的提交）显示给具有该链接的任何人。这是一个独立于工作链接的选项，工作链接永远不会获得它。与 `--repl`，链接和地址永远不会被记住，所以它们在进程停止时停止工作，重新启动时打印新的链接和地址。

### 会议和预习

该指数列出了最近三天内活跃的会话，每个代理最多8个会话，每个会话的标题（或第一个提示）以及最后一次活跃的时间； **工作** 标志着进步的转折。新会话自己出现，包括代理启动后的新日志 `/clear`.

预览显示了每个回合的最终响应：代理在其最后一次工具调用后写入的文本。它从会话的最后10个响应开始，并保持到20个。用 **之前的**， **下一个** 和 **最新的** 在 **当前/总▾** 柜台菜单，或配菜 **选择/ Alt +左/右** (添加 **转变** 最老的或最新的)。新闻 **？** 获取键盘快捷键列表，或选择 **键盘快捷键** 在柜台菜单上。在较旧的响应中，页面保持不变并进行标记 **最新的(新)** 当有东西到达时。 **所有会话（合并）** 显示目录中任何会话的最新响应。文件预览会在每次文件更改时添加一个版本，并保持您的读取位置。

`--all-projects` （`-a` 或者 `--all`)按文件夹分组会话，每个都有自己的合并预览，并总共跟踪64个会话。它不能与 `--cwd`， `--session`，文件参数或 `--merged`.

![Cross-project session index](https://npmcn.com/package/agent-markdown-preview/screenshots/all-projects.png)

### 链接到本地文件

到本地文件的链接在同一选项卡中打开，然后返回到您所在的位置。在渲染文件上， **选择/ Alt +离开了** 也可以追溯到前一页 **←返回预览** 直接跳转到你打开它的回复。响应中的相对链接针对项目目录进行解析，而文件中的链接针对文件的目录进行解析。Markdown、LaTeX、文本和代码以呈现快照的形式打开（刷新以重新读取它们）。图像、pdf和HTML页面在浏览器中打开，HTML在沙盒中运行。其他文件和文件夹打开一个带有按钮的页面，以显示它们在其文件夹中，在其默认应用程序中打开它们，或复制路径。每个链接也有 **复制本地路径** 和 **⋯文件动作** 在它的旁边。

这些操作在承载预览的机器上运行，并且在其默认应用程序中打开文件可以运行它。任何有预览链接的人都可以使用它们，所以只与你信任的人分享链接。

### 重新启动

当命令重新启动时，预览保留其地址，并且在最后一天打开的预览再次开始，因此打开的选项卡重新连接并重建其历史记录。一个新地址打开一个浏览器选项卡；记住的就没有了，所以用 `--open` 如果你已经关闭了旧的标签页。地址存储在 `~/.agent-markdown-preview/servers.json`，或 `$AGENT_MARKDOWN_PREVIEW_HOME`.

### 主题

默认情况下，每个响应使用其代理的调色板并遵循系统的亮/暗设置；索引和文件预览使用中性调色板。 `--theme` 为所有东西设置一个调色板， `--agent-theme pi=pi-studio` 改变一个代理的，和 `--appearance` 修复光或暗：

```bash
agent-markdown-preview -a --agent-theme pi=pi-studio
agent-markdown-preview --theme neutral --appearance dark
```

![Default agent palettes and the optional Pi Studio pair — synthetic examples](https://npmcn.com/package/agent-markdown-preview/screenshots/defaults-palettes.png)

少年派主题 `.json` 文件给出了一个单一的固定主题。在Pi内部，Pi -markdown-preview直接使用Pi的选定主题。 [细节](https://npmcn.com/package/agent-markdown-preview/docs/details.md#themes) 涵盖了库存Pi调色板和其他主题规则。

### 如何找到响应

Claude Code， Codex和Pi编写JSONL日志；OpenCode使用SQLite。Agent-markdown-preview读取它们而不更改它们。

| 代理 | 会话日志 | 转弯的最后反应 |
| --- | --- | --- |
| 克劳德代码 | `~/.claude/projects/<directory>/*.jsonl` (尊重 `CLAUDE_CONFIG_DIR`） | 结束回合的辅助信息(`stop_reason: end_turn`)，其文本块连接在一起 |
| 食典委 | `~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl` (尊重 `CODEX_HOME`)，与每个文件中记录的工作目录相匹配 | `task_complete` 事件, `last_agent_message` |
| π | `~/.pi/agent/sessions/--<directory>--/*.jsonl` | 助理留言 `stopReason: "stop"` |
| OpenCode v1 | `~/.local/share/opencode/opencode.db` (尊重 `XDG_DATA_HOME`） | 完成后的助理留言带有终端完成原因，文字由其单独组成 |
| OpenCode v2 | 相同的数据库; `session_v2` / `session_message` | 最后完成的文本答案之前的回合是明确的 `idle` 标记;按消息序列排序 |

忽略了子代理会话，并且还不支持Gemini CLI。这些格式是每个代理的内部格式，可以在不同版本之间更改。 `--agent opencode` 涵盖了OpenCode版本和 `--session` 也接受OpenCode `ses_…` ID。Node 22可能会警告它的SQLite模块是实验性的。 [细节](https://npmcn.com/package/agent-markdown-preview/docs/details.md#opencode) 介绍了OpenCode阅读器。

### 安全

索引和每个预览只听 `127.0.0.1`，每个都有自己的随机标记。任何拥有预览链接的人都可以阅读它并使用它的文件操作，索引链接列出了您的会话（跨每个文件夹） `-a`)，所以要保持这些链接的私密性。 **复制链接** 在工具栏中提供了另一个浏览器的新链接。remembered-addresses文件包含令牌和可读的只有你。 [细节](https://npmcn.com/package/agent-markdown-preview/docs/details.md#security) 描述预览服务的内容。

## 与pi-markdown-preview的关系

Agent-markdown-preview使用浏览器呈现器和监视页面 [pi-markdown-preview](https://github.com/omaclaren/pi-markdown-preview)，因此它们在没有Pi的情况下运行。在Pi内部，使用Pi -markdown-preview本身：它还提供终端图像预览，PDF导出和颜色从你的Pi主题。

## 开发

```bash
npm install
npm test            # builds, then runs all tests
npm run typecheck
```

源代码是TypeScript中的 `src/`，编译为 `dist/`． 设置 `PUPPETEER_EXECUTABLE_PATH` 到Chromium版本，例如 `chrome-headless-shell`，也运行了一个真实浏览器的明暗切换测试。

`src/render.ts` 是由pi-markdown-preview生成的，不应该手工编辑，而 `src/client` 和 `src/shared` 都是原封不动地从它复制过来的。在这个旁边有一个pi-markdown-preview checkout：

```bash
npm run extract     # regenerate src/render.ts from ../pi-markdown-preview
cp ../pi-markdown-preview/client/* src/client/ && cp ../pi-markdown-preview/shared/*.{js,lua} src/shared/
npm test
```

`scripts/extract-render-core.cjs` 逐字逐句地按顺序复制渲染器所依赖的顶级声明，只替换Pi的声明 `Theme` 使用结构等效项键入。 `test/equivalence.test.mjs` 检查呈现的HTML是否与pi-markdown-preview的字节相同。它使用 `../pi-markdown-preview`，或者进入的路径 `AMP_REFERENCE`，如果两者都不可用，则跳过。 `src/themes` 持有Pi工作室的主题文件和固定的Pi颜色，以及出处和许可。

## 许可证

麻省理工学院

## 常见问题

### agent-markdown-preview 是什么？

浏览器预览编码代理响应（Claude Code, Codex, Pi, OpenCode）和本地Markdown， LaTeX，代码和diff文件，具有数学，语法高亮显示和Mermaid。

### 如何安装 agent-markdown-preview？

在项目目录运行 npm install agent-markdown-preview，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 agent-markdown-preview，可以用 npx agent-markdown-preview 直接运行。

### agent-markdown-preview 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### agent-markdown-preview 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### agent-markdown-preview 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### agent-markdown-preview 可以商用吗？

agent-markdown-preview 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### agent-markdown-preview 还在维护吗？

最新版本 0\.13\.3 发布于 2026/11/03（今天）；至今共发布 23 个版本，其中过去 12 个月发布了 23 个；首次发布于 2026/09/25。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。