poco-ai/Agentero · 上手攻略
- 仓库：poco-ai/Agentero
- 链接：https://github.com/poco-ai/Agentero
- 分类：agent / 科研文献工作台（PDF 阅读 + 结构化上下文 + 本地 Agent）
- 作者：spark
- 更新：2026-11-05
资料核对说明：本篇基于 2026-11-05 抓取的 GitHub README（中文版）与
docs/usage/getting-started.md原文撰写，仓库最近提交 2026-11-04，Stars 1079，MIT 许可。系统要求（macOS 12.0+ / Ubuntu 22.04+ 且需 webkit2gtk 4.1）、快捷键、Vault 目录结构、homebrew 命令均来自官方文档原文，本篇未实测安装。官网 agentero.app 与文档站 agentero-docs.poco-ai.com 本轮未抓取正文，文中凡涉及这两处的内容仅按 README 表述转述。仓库当前未在 README 中给出明确的版本号，本篇不引用具体 release 版本。
一、它是什么
Agentero 是一个开源的本地科研文献工作台，定位是「人与 Agent 协作的统一研究工作区」。
它的核心命题写在 README 里："Context is everything"——如果今天的模型是 f，输出 y 由输入 x（context）决定。科研场景的 context 今天是碎的：PDF 和高亮批注在 Zotero，笔记在 Obsidian，你和 AI 的讨论、提问、方案留在对话框里，三者互不相通，再聪明的 Agent 也只能读到碎片。
所以 Agentero 的目标是同时做两件事：
- 保留人类舒适的 PDF 阅读习惯（大纲导航、划词、高亮批注、全文检索）。
- 为模型提供纯净的结构化上下文（自动解析公式、伪代码、表格，生成结构化 Markdown + LaTeX）。
人机分工（README 的划分很清晰）：
- 人类负责：提出研究问题、做学术价值判断、深度研读与核心结论推导。
- Agent 负责：批量检索筛选、元数据抓取、图表与公式提取、引用关系梳理、基础总结。
用一句话概括：它不是 Zotero 的替代品，而是补齐「Zotero 时代的人机上下文断点」的一层。
二、它解决什么问题
README 明确列了传统文献工具链的四个断点，逐个对应它的设计：
断点 1：上下文严重分散。 论文在 Zotero、笔记在 Obsidian、推导在对话框，三者隔离。要让 Agent 结合某篇具体论文和历史笔记做深入推导，只能反复手动复制粘贴。 → Agentero 把文献、笔记、交互记录统一沉淀到本地 Vault。
断点 2：文献格式对模型不友好。 人类爱看排版良好的 PDF，但模型解析双栏排版、跨页表格、复杂公式和交叉引用成本极高，极易产生识别错误与幻觉。结构化 Markdown 与 LaTeX 才是模型容易准确理解的格式。 → Agentero 自动把公式、算法伪代码、表格解析成结构化 Markdown + LaTeX。
断点 3：维护成本高。 AI 伴读、全文翻译、笔记同步这些高频需求，往往要装多个社区插件，配置门槛高，版本升级容易兼容性问题。 → Agentero 内置这些能力。
断点 4：批量自动化能力有限。 Deep Research 或自动化检索发现的大量文献，目前还得人工在浏览器逐篇点保存。 → 内置极客 CLI，支持脚本化批量导入、提取元数据、写入笔记。
三、快速安装
系统要求（官方文档原文）
| 平台 | 最低要求 |
|---|---|
| macOS | 12.0+ |
| Windows | 发布页 x64 安装包 |
| Linux | Ubuntu 22.04+（需 webkit2gtk 4.1，包名常见 libwebkit2gtk-4.1-0） |
Linux 桌面包在 Ubuntu 22.04 上构建。更旧的发行版（如 Ubuntu 20.04，只有 webkit2gtk 4.0）请先升级系统——官方文档说得很直接。
方式 A：Homebrew（macOS）
brew tap poco-ai/agentero
brew install --cask agentero
方式 B：命令行 CLI（不是桌面 cask）
brew tap poco-ai/agentero
brew install agentero
# 查看常用命令与参数
agentero --help
CLI 是无头命令行工具，用来在终端或脚本里批量导入文献、提取元数据、写入笔记。
方式 C：发布页下载
到 GitHub Releases 或官网 agentero.app 下载对应平台的预编译安装包。
方式 D：开发者本地跑
pnpm install
pnpm tauri dev
Linux 依赖踩坑处理
安装 .deb 时若提示缺 libwebkit2gtk-4.1-0（常见于 Ubuntu 20.04）：
1. 升级到 22.04+，或
2. 改用发布页的 AppImage 版本。
官方文档为此专门开了 issue 追踪（#253）。
方式 E：DeepSeek Harness 插件
在 dsh 里直接用 Agentero 的文献库、笔记和 PDF 阅读器：
dsh plugin --profile web add @poco-ai/agentero-dsh
详见 agentero-dsh-plugin（本篇未抓取该仓库）。
首次使用不需要装 Zotero 或任何 Agent
官方文档明确写："首次使用不需要先安装 Zotero 或 Agent。" 只有在浏览器导入或 AI 辅助阅读时，才需要继续配置对应软件。
四、核心用法
4.1 创建第一个 Vault
- 启动 Agentero
- 欢迎页选 Create Vault
- 选一个长期保存研究资料的位置，例如
~/Documents/ResearchVault - 等左侧文件树和中间 Library 加载完成
Vault 就是普通目录。 官方建议：不要放在临时目录、下载目录，或会被自动清理的同步缓存里。
创建后的目录结构：
ResearchVault/
├── papers/
├── notes/
│ ├── 01 论文导入与管理.md
│ ├── 02 Agent 与 Skill.md
│ └── 03 Markdown 与双链.md
├── .agents/
│ └── skills/
├── AGENTS.md
└── .agentero/
└── catalog.sqlite
notes/下三篇教程会按当前语言自动生成，首次创建 Vault 后自动打开第一篇- 它们就是普通 Markdown，可以自由编辑或删除（删除后不会自动恢复）
- 不要手动编辑
.agentero/catalog.sqlite。论文正文和笔记可以直接用外部编辑器改，但结构化元数据应通过 Agentero 操作
4.2 打开已有 Vault
欢迎页选 Open Vault，选一个包含 papers/、notes/ 或 Markdown 资料的目录。
文件没立即出现在 Library？ 三步走：打开 Library → 点 Rescan → 等扫描完成。
有 Zotero 文库的话，欢迎页也提供「从 Zotero 迁移」选项（迁移前会先创建 Vault），可一键导入整个 Zotero 数据库，保留已有标签、笔记与附件；也兼容 Zotero 浏览器扩展直接保存网页论文，支持导出 BibTeX / BibLaTeX。
4.3 认识工作台
| 区域 | 作用 |
|---|---|
| 左侧文件树 | 浏览 Vault；顶部有 Library、回收站；魔棒可入库 |
| 中间工作区 | Dockview 文档面板：Library 表、PDF、Markdown、回收站 |
| 右侧栏（可选） | Agent / 批注 / References（引用卡片 + 近邻图）/ Figures；编辑器状态栏看双链反链 |
| 左下角 | 后台任务（下载、入库、精读等） |
| 右上角 | 错误 / 警告 Toast |
打开论文时默认左右分屏：左侧 PDF（或 HTML），右侧 NOTES.md。可用 Layout 菜单或快捷键开关 NOTES。
4.4 核心功能：PDF 阅读与批注
- 大纲导航、整页与宽度自适应、平滑划词、高亮批注、全文检索
- 图表与公式提取：自动解析数学公式、算法伪代码及表格，生成结构化 Markdown 与 LaTeX——这是给模型喂干净上下文的关键一步
- 分屏阅读与分析：左侧高亮批注，右侧本地 Agent 基于准确的结构化上下文答疑与推导
- 划词翻译与实时记录：阅读中提取的要点可直接沉淀到本地 Markdown 笔记
4.5 双向链接笔记
内置所见即所得（WYSIWYG）Markdown 编辑器，支持 [[双链]] 引用语法、/ 快捷指令、LaTeX 实时渲染，笔记与文献建立原生关联。编辑器状态栏能看到双链与反链。
4.6 多模式翻译
支持划词翻译、按页对照翻译、全文翻译，内置可用翻译通道，并支持配置自定义 API Key（BYOK）。
4.7 接入本地 Agent（ACP 协议）
底层遵循 Agent Client Protocol（ACP），支持连接各类本地运行的 Agent——Claude Code、OpenCode、Codex 或本地模型——不绑定特定厂商，上下文完全保留在本地。
交互方式（官方文档的首次检查清单）：
⌘P快速打开面板- 划词后
⌘K快速对话 ⇧⌘L加入 Agent 对话⌘L切换右栏
组合键可在「设置 → 快捷键」修改。
4.8 内置 MCP Server
Agentero 可作为 MCP Server 运行，允许 ChatGPT Web、Claude Desktop 等外部客户端直接检索并调用你的本地文献库作为上下文。
也就是说 Agentero 同时扮演两个角色：ACP 的客户端（拉起本地 Agent）和 MCP 的服务端（对外暴露文献库）。这个双向设计是它区别于普通文献管理器的地方。
4.9 学术雷达与批量发现
- 多渠道抓取：内置集成 Cool Papers 与魔搭社区，可在软件内直接浏览并一键归档文献；支持学术 RSS 订阅
- 个性化推荐：基于本地已有文献库的内容特征，自动推荐每日 arXiv 的相关最新论文
- 引用关系自动梳理：自动解析文献末尾参考文献列表，一键批量抓取入库；获取出版商元数据并追踪后续被引动态
4.10 其它
- 本地文件夹透明管理：不使用私有数据库或散列混淆目录，所有文献与笔记以标准文件（PDF、Markdown）保存在本地规范文件夹中，可自由使用外部编辑器读取
- 多端同步与远程访问：支持与 S3 兼容云存储同步；支持通过 SSH 隧道访问部署在远程服务器上的文献库
- 技能扩展：浏览并安装社区提供的科研技能，扩展论文精读与写作分析能力（存于
.agents/skills/） - 主题风格：亮色/暗色及多种配色风格，支持自适应系统外观
五、典型适用场景
- 重度 PDF 精读 + 要问 AI：左边读论文划高亮，右边问 Agent，答案基于提取出的公式与表格而不是模糊的 PDF 文本。
- 跨工具上下文断裂的痛点：本来用 Zotero + Obsidian + ChatGPT 三件套，现在想在一个地方把三者合起来。
- 批量文献处理：用 CLI 把 Deep Research 找到的一堆论文批量导入、提元数据、写笔记，不用逐篇点。
- 本地优先、隐私敏感：文献库在本地，Agent 也是本地跑的（Claude Code / Codex / 本地模型），不出本机。
- 想让 ChatGPT Web / Claude Desktop 用上自己的文献库：开启 MCP Server 即可，不换客户端。
- 跨机器科研：S3 同步 + 远程服务器部署 + SSH 隧道，实验室服务器和笔记本用同一个库。
- Zotero 老用户迁移：一键导入整个 Zotero 数据库，标签、笔记、附件都保留，再按 Agentero 的方式用。
不适合：只需要一个轻量 PDF 阅读器的人（它偏重）；完全不能接受 GUI 桌面应用、只想用脚本的人（虽然有 CLI，但没有 GUI 体验）；需要多用户协作与权限管理的团队。
六、坑与注意
- Linux 必须 Ubuntu 22.04+。Ubuntu 20.04 只有 webkit2gtk 4.0，官方明说请先升级系统；退而求其次用 AppImage。这是 Linux 上最常见的安装失败点。
.agentero/catalog.sqlite不能手动编辑。论文正文和笔记可以用外部编辑器直接改，但结构化元数据必须走 Agentero，否则索引会不一致。- notes/ 里三篇教程删除后不会恢复——它们是普通 Markdown，可以随便改，但别指望找回。
- Vault 别放临时目录/下载目录/会自动清理的同步缓存里。官方明确警告，Vault 是长期资产，放错地方会丢。
- 文件不显示先 Rescan，别急着重装。打开 Library → Rescan → 等扫描完成。
- 必须整体备份 Vault。
.agentero/catalog.sqlite也应随 Vault 一起备份，否则 Library 元数据丢失。用 Git 的话优先提交 Markdown、JSON、TeX 等源文件。 - 用量记录在 Vault 之外：
~/.local/share/agentero/usage.sqlite存本机使用记录，不在 Vault 内，在「设置 → 通用 → 隐私」里可关或清除。想做隐私清理的别漏掉这个文件。 - 自动更新失败报「无法安装更新，请重试」通常是网络/代理问题：换代理节点、确认能访问 GitHub Releases、检查「设置 → 通用 → 网络代理」配置；仍失败就直接去发布页手动下载。
- 右侧栏 / NOTES 面板是可开关的，默认左右分屏但可改 Layout。找不到 NOTES 时先看 Layout 菜单。
- 快捷键是 macOS 风格的（⌘K / ⇧⌘L / ⌘L / ⌘P / ⌘F），Windows/Linux 用户需要自己换成 Ctrl 组合，可在设置里改。
- 翻译走 BYOK 自定义 Key，密钥由你自己保管，注意别把配置提交进公开仓库（Vault 如果用 Git 记得检查 .gitignore）。
- ACP / MCP 都是本地协议栈：ACP 连的是本地 Agent，MCP 暴露的也是本地文献库。别把 MCP Server 端口暴露到公网——那等于把你的整个文献库开放出去。
- 开源但第三方组件多：README 提到
.github/THIRD_PARTY_NOTICES.md列了第三方组件与许可清单，商用前应过一遍。 - 官网与文档站本轮未核：agentero.app 与 agentero-docs.poco-ai.com 的内容本篇未抓取，界面截图与功能细节以 README 表述为准。
七、与同类对比
| 维度 | Agentero | Zotero | Obsidian | PaperQA2 / 各类 AI 阅读器 | NotebookLM |
|---|---|---|---|---|---|
| 核心定位 | 人机协同的本地文献工作台 | 文献归档与引用管理 | 通用 Markdown 笔记 | 面向论文的 RAG 问答 | 上传资料后问答 |
| 人类阅读体验 | ✅ 保留 PDF 阅读 + 批注 | ✅ 成熟 | 一般（PDF 插件） | 一般 | ✅ 简洁 |
| 给模型的上下文 | ✅ 自动公式/表格/伪代码 → Markdown+LaTeX | ❌ 主要是附件元数据 | ⚠️ 手动整理 | ⚠️ 侧重文本切块 | ⚠️ 云端切块 |
| 本地 Agent 接入 | ✅ ACP（Claude Code / OpenCode / Codex / 本地模型） | ❌ | ⚠️ 靠插件 | ❌ | ❌ |
| 对外暴露文献库 | ✅ 内置 MCP Server | ❌ | ⚠️ 靠插件 | ❌ | ❌ |
| 文件形态 | ✅ 透明文件夹（PDF + Markdown） | ⚠️ SQLite + 附件目录 | ✅ Markdown | ⚠️ 向量化库 | ❌ 云端 |
| Zotero 迁移 | ✅ 一键，保留标签/笔记/附件 | — | 需手动 | ❌ | ❌ |
| 批量自动化 | ✅ CLI | ⚠️ 有限 | ⚠️ 脚本 | ✅ | ⚠️ |
| 隐私 | ✅ 全本地 | ✅ 本地 | ✅ 本地 | ⚠️ | ❌ 云端 |
| 协作/多人 | ❌ 无 | ⚠️ 有 WebDAV/群组库 | ⚠️ 靠同步 | — | ✅ |
| 费用 | 免费开源 | 免费 | 免费 | 视项目 | 免费额度 |
核心差异：Zotero 和 Obsidian 各自都做得好，但都是「人类工具」，把 AI 当外挂；Agentero 是「Agent 原生」——PDF 阅读习惯保留，但结构化上下文、ACP 接入、MCP 暴露、CLI 批量这四件事是一等公民。
八、一句话推荐结论
推荐：给需要深度精读大量论文、且要把 AI 真正接进研究流的科研者——尤其本来就困在「Zotero + Obsidian + ChatGPT」三件套断裂里的人。ACP 接本地 Agent + 内置 MCP Server + 透明本地文件夹，这个组合目前没有明显竞品能完整替代。
要认清的：Linux 用户先确认 Ubuntu 22.04+（或用 AppImage）；没有多人协作；catalog.sqlite 别手改；对外暴露 MCP Server 前想清楚安全边界。
九、参考来源
- 仓库 README（中文）：https://github.com/poco-ai/Agentero —— 2026-11-05 抓取
- 安装与首次使用文档：
docs/usage/getting-started.mdhttps://raw.githubusercontent.com/poco-ai/Agentero/main/docs/usage/getting-started.md —— 2026-11-05 抓取（系统要求、Vault 目录、快捷键、备份建议、自动更新失败处理均出自此文件） - 仓库仓库卡片：
organized/repo_cards/4870-poco-ai-agentero.md - README 中提及但本轮未抓取的链接：https://agentero.app/ ；https://agentero-docs.poco-ai.com ；https://github.com/poco-ai/agentero-dsh-plugin ；https://papers.cool/ ；https://github.com/poco-ai/Agentero/issues/253