# MNAI Scholar 1.4.1：安装与使用说明

MNAI Scholar 是运行在 MarginNote 4 内的本地研究助手。MarginNote 插件负责读取当前文献、选区和卡片上下文；本地 Companion 负责索引、EndNote 只读同步以及调用本机 Codex CLI。两部分必须使用相同版本。

## 系统要求

- Apple Silicon Mac；
- macOS 14 或更新版本；
- MarginNote 4.2.3 或更新版本，建议使用当前最新版；
- Node.js 22.5 或更新版本；若缺失，安装器可以自动安装私有 Node.js 22 LTS；
- 已登录可用的 Codex CLI，用于问答、研究和证据脑图；
- 可选：MinerU，用于 Detailed reading index。

当前发布包不支持 Intel Mac；辅助程序均为 arm64 架构。

## 安装顺序

### 1. 安装 Companion

1. 打开一次 MarginNote 4，让系统创建应用容器，然后完全退出 MarginNote。
2. 解压 `MNAI-Scholar-Companion-v1.4.1-macOS-arm64.zip`。
3. 双击其中的 `install.command`。
4. 如果没有 Node.js ≥22.5，安装器会先询问：
   - **私有 Node.js（推荐）**：从 Node.js 官方下载 v22.22.0 arm64 包，校验固定 SHA-256 后安装到 MNAI Scholar 自己的目录，不修改全局 PATH；
   - **Homebrew node@22**：仅在用户已安装 Homebrew 时可选，会修改 Homebrew 环境；
   - **退出**：不安装 Companion。
5. Node.js 就绪后，安装器询问 MinerU，可选择：
   - **Core（推荐）**：启用 MNAI Scholar 所需的 Detailed reading index；
   - **All**：同时安装 macOS MLX 等 MinerU 扩展，下载体积更大；
   - **跳过**：不影响 Chat、Quick reading index、EndNote 和 Codex 功能，之后可重新运行安装器添加。
6. 看到 `MNAI Scholar Companion 1.4.1 installed successfully` 后关闭终端窗口。

私有 Node.js 安装位置：`~/Library/Application Support/MNAI Scholar/Runtime/node-v22.22.0`。

MinerU 会安装到独立环境 `~/Library/Application Support/MNAI Scholar/Optional/mineru`，不会修改现有 conda 或系统 Python 环境。安装依赖下载量较大，首次实际解析时还可能继续下载模型。

如果 macOS 阻止运行，右键 `install.command` 并选择“打开”。安装器不会把令牌、文献或个人路径打入发布包。

### 2. 安装 MarginNote 插件

1. 双击已签名的 `MNAI-Scholar-v1.4.1.mnaddon`，选择使用 MarginNote 4 打开；也可以从 MarginNote 的扩展管理界面导入。
2. 打开一本笔记本。
3. 点击 MarginNote 插件栏中的 MNAI Scholar 图标。
4. 顶部状态应显示本地 Companion 在线。

签名前内部测试可以使用文件名带 `unsigned` 的包，但需在 MarginNote 设置中允许加载未经认证插件。公开发布时应替换为官方认证后的 `.mnaddon`。

## 主要功能

- **Chat**：添加选中文本、剪贴板文字或图片、选中卡片、当前页文字/图片作为上下文，并继续追问文献。
- **Answer / Evidence Map**：生成带证据约束的回答，或先预览 Codex 卡片树再写入 MarginNote。
- **Quick reading index**：为当前 PDF 建立可复用的快速阅读索引。
- **Detailed reading index**：使用 MinerU 建立保留版式信息的详细索引。
- **Indexed documents**：检索已索引文献，并将一个或多个索引加入当前对话。
- **EndNote**：以只读方式连接 `.enl` 文献库，同步元数据和 PDF 关联；直接写回 EndNote 文献库未启用。
- **Web search**：在发送问题时允许 Codex 检索学术网络来源。

## 首次使用建议

1. 打开一篇 PDF。
2. 在 **Index** 中先运行 **Quick reading index**。
3. 返回 **Chat**，点击 **+ Selection text** 或把当前 PDF 索引加入 Context。
4. 输入问题，选择 **Answer** 或 **Evidence Map**，再点击 **Send**。
5. 保存到脑图前检查预览，确认后再执行写入。

## 数据与权限边界

- Companion 只监听 `127.0.0.1:48673`，不向局域网开放端口。
- 插件和 Companion 使用本机生成的私有凭据通信；凭据不包含在发布包中。
- Codex CLI、可选 OpenAI-compatible API 与网络检索可能把用户明确提交的上下文发送给相应服务；是否使用 Web search 由用户在界面中选择。
- EndNote 集成为只读索引与导出工作流，不直接修改原始 EndNote 文献库。
- 卸载 Companion 不会自动删除 `~/.mnai-scholar` 中的索引和会话数据。

## 故障排查

### Companion offline

在终端运行：

```bash
curl -fsS http://127.0.0.1:48673/health
```

正常时应返回版本 `1.4.1` 和构建标识 `2026-07-21-literature-toolkit-route-1.4.1`。

日志位于：

`~/.mnai-scholar/logs/companion-launch-agent.log`

### Codex CLI is not ready

确认 Codex.app 或 ChatGPT.app 已安装且已登录，或者确保 `codex` 命令可执行，然后重新运行 Companion 安装器。

如果提示缺少 `codex-code-mode-host`，请更新 Codex.app 或 ChatGPT.app。不要只把 `codex` 单个文件或软链接复制到其他目录；该主程序需要同目录的配套 host。新版 Companion 安装器会解析软链接并绑定完整运行时。

### Detailed reading index 不可用

这是可选的 MinerU 依赖未找到。重新运行 Companion 安装器，在交互提示中选择 Core 或 All；安装器会在独立环境中完成安装，并把正确路径写入 LaunchAgent。

### 插件显示未认证

公开版本应使用 MarginNote 官方认证后的 `.mnaddon`，并确保 MarginNote ≥ 4.2.3。若此前装过未认证版本，请先在扩展管理界面删除旧版，再安装认证版。

## 版本信息

- 插件版本：1.4.1
- Companion 版本：1.4.1
- Build ID：`2026-07-21-literature-toolkit-route-1.4.1`
- 已恢复和核对的 MarginNote 环境：MarginNote 4.4.4