内容
<img src="docs/logo.png" width="96" align="right" alt="DocsReader logo" />
# 文档阅读器
人机交互窗口，连接代理和管理的文件仓库。你可以通过集成的 MCP 服务器读写文档、记忆和任务；而作为文档阅读器，它能以干净的本地应用形式呈现相同的 Markdown 文件。并且，它仍然可以用作任何 Markdown 文件夹的快速阅读器，支持 macOS、Linux 和 Windows。
[](https://github.com/anbturki/docsreader/releases/latest)
[](https://github.com/anbturki/docsreader/releases)
[](https://github.com/anbturki/docsreader/actions/workflows/notarize-staple.yml)
[](https://github.com/anbturki/docsreader/actions/workflows/notarize-staple.yml)
[](https://github.com/anbturki/docsreader/releases/latest/download/DocsReader_0.6.3_universal.dmg)
[](https://github.com/anbturki/docsreader/releases/latest/download/DocsReader_0.6.3_x64-setup.exe)
[](https://github.com/anbturki/docsreader/releases/latest/download/DocsReader_0.6.3_amd64.AppImage)
Linux: AppImage 在大多数发行版上可用，对于 `.deb` （Debian/Ubuntu）或 `.rpm` （Fedora/RHEL），请参阅 [发行版页面](https://github.com/anbturki/docsreader/releases/latest)。
或者，通过 [Homebrew 或一行命令](#安装) 安装。
## 工作原理
所有内容都以纯 Markdown 存储在磁盘上 - 没有数据库，没有锁定，可以 grep 和使用 git 版本控制。代理是主要的写入者；文档阅读器是您观察文档仓库增长的地方，当代理写入时，打开的文档会实时重新加载。
**工作空间** 是一个 Markdown 文件夹。您的默认工作空间位于 `~/notes` （首次写入时创建）；任何项目都可以选择加入其自己的 `<project>/notes`。工作空间内有三个命名空间：
- **文档** 包含实质内容：研究、计划、决策。每个文档都位于与其生命周期状态匹配的文件夹中 - `research/`、`in-progress/`、`done/`、`archived/` - 因此文件夹就是状态，移动文件就是状态更改。可选的阶段子文件夹（例如 `research/v2-launch/`）对工作进行分组。
- **记忆** （`memory/`）包含简短的主题相关事实（例如“用户更喜欢标签页”，“我们部署到登台环境”）。每个主题只有一条记录；重新写入主题会完全替换它。
- **任务** （`tasks/`）是 [Backlog.md](https://github.com/MrLesk/Backlog.md) 格式的文件：`task-N` ID，状态在 frontmatter 中，验收标准清单由代理在执行过程中勾选。
MCP 服务器为所有这些功能提供了工具（`write_doc`、`search_docs`、`set_status`、`write_memory`、`write_task` 等），一个 `docsreader://onboarding` 资源用于教导代理模型，以及每个文档作为可读的 MCP 资源。工具错误会带有恢复提示，因此代理可以自我纠正而不是卡住。
## 连接您的 AI 代理
在文档阅读器中：**设置 → AI 代理 → 连接**。应用程序检测已安装的客户端（Claude Code、Cursor、Windsurf、VS Code、Codex）并将捆绑的 `docsreader-mcp` 服务器注册到每个客户端 - 只需一步，即可全局使用。
要手动注册，请将任何支持 stdio 的 MCP 客户端指向二进制文件：
| 安装方式 | 二进制文件位置 |
| --- | --- |
| Homebrew（macOS） | `docsreader-mcp`（在 PATH 上） |
| DMG（macOS） | `/Applications/DocsReader.app/Contents/MacOS/docsreader-mcp` |
| deb（Linux） | `/usr/bin/docsreader-mcp`（在 PATH 上） |
| Windows | `docsreader-mcp.exe`，与 `DocsReader.exe` 在同一安装文件夹中 |
`docsreader-mcp` 是一个本地 stdio 服务器 - 没有 URL 需要添加；每个客户端都会自行启动二进制文件。以 Claude Code 为例：
```sh
claude mcp add --scope user docsreader -- docsreader-mcp
```
Codex CLI：
```sh
codex mcp add docsreader -- docsreader-mcp
```
VS Code：
```sh
code --add-mcp '{"name":"docsreader","command":"docsreader-mcp"}'
```
Cursor（`~/.cursor/mcp.json`）和 Windsurf（`~/.codeium/windsurf/mcp_config.json`）：
```json
{ "mcpServers": { "docsreader": { "command": "docsreader-mcp" } } }
```
如果 `docsreader-mcp` 不在您的 PATH 上（例如 macOS DMG 安装且没有 Homebrew），请使用上面的表格中的完整二进制文件路径。Homebrew 用户如果在 v0.6.0 之前安装并自动更新了应用程序，请运行 `brew upgrade --cask docsreader` 以便 Homebrew 链接二进制文件 - 内置更新器无法执行此操作。应用程序的“连接”流程始终写入完整的路径，因此无论如何它都能正常工作。
然后告诉您的代理如何使用它：复制 [AGENTS 模板](docs/AGENTS-TEMPLATE.md) 到您的仓库的 `AGENTS.md` 或 `CLAUDE.md` 中。
## 功能
**阅读**
- **渲染：** GitHub 风格的 Markdown via remark-gfm（表格、任务列表、脚注、自动链接、删除线）
- **数学表达式：** LaTeX 内联和块渲染 via KaTeX
- **图表：** Mermaid 渲染器（延迟加载，跟随主题）
- **绘图艺术：** svgbob 将 ASCII 图转换为 SVG（实验性）
- **代码块：** 20 种捆绑语言语法 via Shiki，12 种高亮调色板（5 种浅色，7 种深色）
- **外观：** 浅色、深色或跟随系统主题，有 6 种强调色
- **类型控制：** 字体系列、字体大小和阅读栏目宽度
- **快速编辑：** 任何打开的文档上的铅笔图标会切换到原始 Markdown 以进行快速人工修复；代理仍然是主要的写入者
**浏览**
- **工作空间：** 保持多个无关的文件夹打开并在它们之间切换
- **镜头：** 同一仓库的四种浏览模式（树、最近、标签、固定）
- **跳转到文件：** 跨所有工作空间的模糊查找，打开时默认为 Cmd+P（绑定可配置）
- **文档大纲：** 自动构建的 TOC 跟随活动标题滚动
- **反向链接：** 侧边栏列出链接到当前文档的每个文档，按文件夹分组
- **标签页：** 同时打开多个文档；滚动位置记住每个标签页
- **分屏：** 水平或垂直并排阅读两个文档；每个面板保持其自己的标签页、滚动和外部更改横幅。可从标题栏拖动分割线调整大小，或使用 Cmd+\（水平）或 Cmd+Shift+\（垂直）或 Cmd+1 / Cmd+2 聚焦某个面板。“在其他面板中打开”位于文件上下文菜单中。
- **搜索：** 文件名、路径、frontmatter 标题或标签
- **固定收藏：** 将单个文件固定到任何工作空间的顶部
- **杂物规则：** glob 模式静默排除文件和文件夹不显示在资源管理器中
**代理感知**
- **托管工作空间：** 具有 `.docsreader.yaml` 标记的文件夹在其切换器中显示其显示名称，其首页在首次添加时打开，代理写入时打开的文档会静默重新加载
- **转换提示：** 打开纯文件夹时，提供将其转换为托管工作空间的选项；拒绝则永久保持只读。
- **外部更改通知：** 在非托管文件夹中，当您打开的文件在磁盘上更改（其他编辑器、同步服务、AI 代理）时，横幅显示更改内容并提供重新加载 / 保留 / 显示差异的操作。
- **Git 状态装饰：** 在 git 仓库中，文件树显示每个文件的状态徽章（M / A / D / R / ？ / U），文件更改时刷新
- **Git diff vs HEAD：** 右键单击任何跟踪的文件，查看 HEAD 与工作树的差异，具有统一或并排视图和逐词高亮
**默认静默**
- **极简主义界面：** 扁平的活动状态，无徽章，仅用户发起的动作（ADHD友好，视觉负载低）
- **一次专注于一件事：** 镜头取代树形结构，而不是在树形结构上叠加
- **相同位置，每次启动：** 控制不会在窗口周围移动
- **恢复到您离开的地方：** 标签页、滚动位置、侧边栏和活动镜头在会话之间保持一致
**信任**
- **本地存储：** 无遥测，无同步；唯一的外部请求是更新检查
- **签名更新：** 每个发布工件都附带 minisign 签名；更新器在应用之前进行验证
- **Gatekeeper 友好：** 代码签名和 Apple notarized 在 macOS 上
- **强化渲染器：** 严格的 CSP、清理的 HTML、scheme-allowlisted 链接
发现了错误，想要一个功能，或有反馈？ [打开一个问题](https://github.com/anbturki/docsreader/issues/new) - 我正在积极构建这个，您的反馈将影响路线图。
## 截图
| | |
| --- | --- |
|  |  |
|  |  |
|  |  |
|  |  |
## 安装
### macOS（Homebrew）
```sh
brew install --cask anbturki/tap/docsreader
```
### macOS / Linux（curl）
```sh
curl -fsSL https://raw.githubusercontent.com/anbturki/docsreader/main/install.sh | bash
```
### 手动安装
从 [发行版页面](https://github.com/anbturki/docsreader/releases/latest)：
| 操作系统 | 文件 |
| --- | --- |
| macOS（Intel + Apple Silicon） | `DocsReader_*_universal.dmg` |
| Linux | `DocsReader_*_amd64.AppImage` 或 `.deb` |
| Windows | `DocsReader_*_x64-setup.exe` |
## 安全
参见 [SECURITY.md](./SECURITY.md)。
---
## 开发
使用 [Tauri 2](https://tauri.app/)、React 和 Rust 构建。需要 [Bun](https://bun.sh/)、[Rust](https://rustup.rs/) 和 [Tauri 2 系统依赖](https://tauri.app/start/prerequisites/) 适用于您的操作系统。
```sh
bun install
bun run tauri dev
```
MCP 服务器是同一个 cargo 工作空间中的单独的无 Tauri 二进制文件：
```sh
cargo build --manifest-path src-tauri/Cargo.toml -p docsreader-mcp
```
### 发布
GitHub → Actions → **Cut Release** → 输入版本号（例如 `0.1.2`）。工作流会更新 `tauri.conf.json` + `Cargo.toml` + `Cargo.lock`，提交，标记并触发发布管道（签名，notarize macOS 包，创建 GitHub 发布，更新 Homebrew 软件包）。
