# 使用 Bookmark Research

[English](user-guide.en.md) · **中文**

中英文用户使用同一个插件。提供数据包，并说明问题、范围和交付要求，宿主模型会读取 Skill、调用工具执行；不需要固定触发词。

## 首次使用

安装后新建宿主会话，以加载当前 Skill 和工具。提供自己的 Bookmark Canvas 目录、ZIP 或单卡 JSON：

> 用 Bookmark Research 读取 "/absolute/path/to/my-package"，先离线列出卡片、文件夹和书签数量。

本地查询无需 API Key。插件不附带个人书签或预建数据库。之后可沿用已登记来源；同一画布的新导出应明确说明沿用原来源。

## 选择研究深度与范围

| 任务 | 提问示例 | 实际行为 |
| --- | --- | --- |
| 本地查询 | “这个书签在哪张卡片里？” | 查询本地元数据和画布关系。 |
| 快速查证 | “读一下我收藏的官方页面，确认它是否支持 MCP。” | 读取已有 URL，必要时搜索发现来源，再带引用答复。 |
| 主动搜索 | “比较这些卡片中的搜索工具，包括认证方式与研究能力。” | 根据卡片语境拆问题，搜索、读文，并沿证据缺口继续补查。 |
| 深度研究 | “用已配置的研究 API 深入调查这个问题，核查关键原文并保存 Wiki。” | 直接提交 API 任务、观察进度、审阅报告与关键来源。 |
| 完整资料审计 | “全量研究这个包，核验排行榜，与我们的插件比较，保存报告和 Wiki。” | 按需启用高级目录，保留完整清单，核验来源与覆盖。 |

快速查证不会把宿主切换成非推理模型。深度与范围分别决定：深度研究可以只覆盖明确指定的卡片；要求研究整包时，保留每个原始 URL 和重复书签各自的语境。分页、分批和子代理数量不能缩小范围。搜索摘要和外部报告不能代替读取原始网页。

深度研究可以使用宿主的推理、子代理或已有工作流。可选的 OpenAI Deep Research／Parallel Task API 需要单独启用并配置凭据。搜索可用不代表专业研究服务已启用；明确指定的服务不可用时应说明，不静默替换。

## 快照与持续目录

普通导出默认使用 `snapshot`，接入后保存必要原文件和索引，下载包移走或删除后仍可使用。Git 仓库中的目录默认使用 `live`；已登记来源沿用原模式。长期完整镜像可这样说明：

> 把这个目录登记为持续来源，它是完整的画布同步目录。

MCP 进程运行期间及查询前会检查 live 目录。一次性 CLI 命令执行后退出；要持续监控，运行前台 `python3 src/cli.py watch`。Git 同步仍由原有同步工具执行。

局部导出保留此次未提供的文件；完整镜像可删除缺失文件。已提供完整栏目内的 item 删除在局部模式下也会同步，单卡固定使用局部模式。两种模式都会保存可恢复版本。输入变化会提示研究／Wiki 复核，不会自动抓网页或改写结论。

## 配置

说“显示 Bookmark Research 的配置”，或运行 `python3 src/cli.py config show`。要修改长期偏好，可以说“以后只用 Exa 搜索”；仅临时覆盖时说明“这次”。

| 项目 | 默认值 | 修改示例 |
| --- | --- | --- |
| 网页搜索 | Exa + Parallel；每次搜索每目标 5 条命中 | “以后只用 Exa 搜索。” |
| 正文读取 | Exa；请求长度 12,000 字符 | “这次用 Parallel 读取。” |
| 普通网页归档 | 开启 | “这次读取不要归档。” |
| 研究深度 | `auto` | “这次用深度研究。” |
| 答复语言 | `auto`，跟随提问 | “以后的报告默认用中文。” |
| 服务检查 | 缓存 15 分钟，配置／密钥变化后刷新 | “每次新问题前都检查服务可用性。” |
| 专业研究 API | 关闭 | “显示启用 OpenAI 研究需要什么配置。” |

搜索结果条数不限制数据包范围；长度参数不保证完整正文。API 结果与完整审计的任务证据独立保存，不受普通网页归档开关影响。

可运行 `python3 <插件根目录>/src/cli.py setup` 引导设置偏好并隐藏输入密钥。密钥优先从宿主环境读取，其次读取配置旁的私有 `credentials.json`：`EXA_API_KEY`、`PARALLEL_API_KEY`、`TAVILY_API_KEY`、`JINA_API_KEY`；OpenAI 专业研究使用 `OPENAI_API_KEY`。访问和额度取决于服务方。宿主自身研究无需另配专业研究服务密钥。

需要诊断访问问题时，可用高级 `research_readiness` 检查所选服务和已观察到的宿主工具；cached／always／manual 控制频率，本地查询保持离线。setup 展示可选原生 MCP 的接入／授权步骤，实际 OAuth 由宿主管理。已填密钥、工具可见与实际操作成功分别报告，检查不会创建付费研究任务。详见[配置与就绪检查](../skills/bookmark-research/references/zh/settings-and-archive.md)。

默认配置位于 `~/.config/bookmark-research/settings.json`，数据位于 `~/.local/share/bookmark-research/`，支持 XDG 及插件的数据／配置路径覆盖。SQLite 保存本地查询索引，旁边保存来源快照、网页归档、研究档案与 Wiki 修订。多个宿主可以共享这些位置，用户数据应位于插件和原始画布包之外。

## 语言与证据

答复、进展、报告正文和 Wiki 标题／章节优先采用本次明确要求，其次是保存的 `research.response_language`；`auto` 跟随实际任务和对话。例如：

> 调查这些中英文资料，用中文写报告，保留原文引用，译文单独列出。

Skill 指令本身的语言不决定输出语言。安装器 `--lang auto|en|zh` 控制帮助与提示；向导另外询问并保存答复语言。`auto` 依次读取 `LC_ALL`、`LC_MESSAGES`、`LANG`；中文 locale 使用中文，其余或未设置时使用英文。`BOOKMARK_RESEARCH_INSTALL_LANG` 用于 Shell 向 Python 安装器传递界面语言。

执行 Skill 和方法参考已使用英文，配完整中文阅读对照，[指令索引](instructions.md)也包含双语宿主提示说明。宿主将输出语言保存在研究 brief 并传给子代理；脚本工作流支持 `output_language`。任务和对话都没有选择语言时默认英文。

原始 URL、标识符、正文证据和引用保留原样。工具／JSON 字段、技术诊断及报告／Wiki 的固定元数据标签仍使用英文，宿主编写的正文使用指定语言。历史研究记录保留原语言。

旧会话只暴露部分 MCP 工具时，宿主可用同包 CLI 执行缺少的操作，新建会话后加载新版 Skill 和工具列表。仅选择路由或接入数据包不会启动后台研究。

实现细节见[中文 Skill 说明](../skills/bookmark-research/references/zh/skill-guide.md)、[配置参考](../skills/bookmark-research/references/zh/settings-and-archive.md)和[Wiki 指南](../skills/bookmark-research/references/zh/wiki.md)；实际加载的是[英文执行 Skill](../skills/bookmark-research/SKILL.md)。