证据溯源做成一等公民：Librarium 如何让 AI 研究结果可追溯

核心洞察

Librarium一个证据感知的多提供商研究工具，支持人类和 AI 代理，可组合多种搜索和研究服务。 这个项目有意思的地方在于它把"证据Librarium 中记录的结果来源类型，包括 api_output 和 surface_snapshot，保留收集和访问溯源。溯源"当成了一等公民来设计，而不是事后补个引用链接了事。作者把包拆成三个导入边界这个做法挺克制，说明他清楚库和应用的职责该在哪切开。不过说实话，v2 这套架构对普通用户来说门槛不低，你得先搞明白 core 和 node 各自负责什么才能用顺手。

Librarium 干的事情是这样的：拿一个研究请求，对照你明确指定的 provider 配置做规划，执行选中的任务，然后把整个过程记录下来。它能组合网页搜索、带依据的回答、消费端观察和持久化研究任务。它不会把"多个来源说法一致"当成"证明"。每条结果都保留采集来源和访问链路，调用方自己判断每个结果意味着什么。

v2 把产品拆成三个导入边界：

这几个库边界是刻意做成可组合的。用 librarium/core 的调用方自己持有具体适配器、凭证上下文、时钟、协调存储、产物服务，以及它调用的端口所需的其他运行时依赖。librarium/node 补充的是宿主相关的构建块，它不会把内置目录组装成一个高层运行器。

librarium CLI 和它的 MCP stdio 服务器Librarium 提供的应用接口之一，用于研究运行，与 CLI 并列。是研究运行的完整应用接口。通过 Node 包安装需要 Node.js 22.12 或更高版本。独立二进制和 Homebrew 二进制自带运行时。

核心结论

1. Librarium v2 将产品拆分为三个导入边界：librarium（Worker 安全的 schema 与契约工具）、librarium/core（注入式规划与执行端口）、librarium/node（Node 配置、凭证与可信自定义 provider），三者刻意保持可组合而非捆绑为高层运行器。

2. v2 目录内置 34 个 provider、41 个已实现的公开 profile，profile 以 provider_id/profile_id 为选择和溯源的基本单位；内置工作流基于图的系统，连接多个智能体和函数以执行复杂的多步骤任务，支持类型路由、嵌套、检查点和人机交互模式。仅有 quick、deep、visibility、all 四个，自定义组必须以 custom:<name> 形式存储。

3. Librarium 将证据分级为 api_output（直接 API 响应）与 surface_snapshot（SearchAPI 采集的消费端记录），并明确六个 SearchAPI 消费面共用同一采集器，其一致性属于相关可见性证据而非六次独立确认。

4. librarium plan 在适配器初始化前完成规范请求编译、凭证引用解析与预算准入，不发起任何 provider 请求、不导入自定义 provider 模块、不创建运行目录；被阻止的计划以状态码 2 退出，绝不会呈现为已准入的部分计划。

5. 持久化任务仅对 background/durable profile 使用持久化句柄，background/process-local 无法表示为持久化任务；已发布目录目前只为 valyu/research 声明远程取消，其余 provider 的取消行为需对账而非编造 provider 端取消调用。

快速上手

npm install -g librarium

# 交互式配置凭证并选择 provider
librarium init

# 在真正运行之前，先检查离线的预检计划
librarium plan "PostgreSQL connection pooling"

# 运行默认的快速工作流，并发等待各 provider
librarium run "PostgreSQL connection pooling"

# 或者基于快速工作流生成一个有证据边界的回答
librarium answer "What changed in PostgreSQL 17?" --verify

快速工作流也能给出有证据边界的答案

librarium answer "PostgreSQL 17 有什么变化？" --verify

付费跑之前先跑一遍 librarium doctor，它离线检查配置和凭证是否存在，不会加载你配置的自定义 provider 代码。想测连通性得显式加 --live，这时候会加载受信任的自定义 provider、发出网络请求，也可能产生费用。librarium run --json 只把 JSON 送到标准输出，进度和诊断信息走标准错误。新请求默认走 quick 工作流、sync 模式。用 --group、--providers 或 --mode 覆盖默认值，保存过的配置偏好同样生效。

V2 目录

v2 目录内置 34 个 provider、41 个已实现的公开 profile。profile 是选择和溯源的基本单位：provider_id/profile_id。一个 provider 可以暴露多个 profile，比如 exa/search 和持久化的 exa/research。适配器 ID 属于 Node 实现细节，别把它当公开的 v2 配置存下来。

工作流

内置的只有这四个名字：

自定义组必须以 custom:<name> 的形式存储和选择。旧的内置名 raw、fast、llm、models、comprehensive、social、xai 都不是 v2 工作流。v1 迁移时，用户自建的组会变成 custom:<name>，不会悄悄顶替一个保留的工作流名。

Provider/profile 名册

这是公开的目录名册。background/durable 表示该 profile 有一个持久化的、按 provider 划分的句柄，可以跨进程轮询和取回。background/process-local 只能在拥有它的进程状态还在时继续。其余 profile 都是 inline/none。

grok-x-only/x 是只查 X 的 profile。grok-combined/combined 是另一个独立的组合搜索 profile，不是 grok/web 的别名，在配置、产物和报告里都得保留自己的身份。

SerpBase 需要手动开启，不在默认的 quick 工作流里。把 Node 适配器配成 serpbase-search 或 serpbase-news，带上 SERPBASE_API_KEY。两者都接受 hl、gl 和从 1 开始的 page；只有 Search 接受 device（default、pc 或 mobile）。Search 的 includeRichResults 默认 false。开启后，有文档说明的 organic 和 PAA 来源会被提取，相关搜索只作为非证据建议保留，嵌套 schema 未公开的富模块以有边界的字面数据展示、不带引用。Search、News 和相关搜索的渲染通过了线上冒烟检查；PAA 和不透明的富模块在那几次检查里没返回，仍属线上未验证。

SerpBase 响应每页最多 100 条主结果，保留的文本字段上限 2000 个 UTF-8 字节。带凭证的 URL 会被拒绝，provider 报错时不带上游响应体。

证据意味着什么

• 直接的 API 响应是 api_output。它报告的是那个具名 API 返回了什么，不代表结果放之四海皆准。
• SearchAPI 的消费端 profile 是 surface_snapshot 记录，由 SearchAPI 采集。它们不是 OpenAI、Google、Microsoft 或 Perplexity 的官方 API，也无法证明与某个特定账号、位置、订阅、实验分组或时间点一致。
• 六个 SearchAPI 消费面共用一个采集器。它们之间的一致是相关的可见性证据，不是六次独立确认。
• 引用是为某个结果提供或规范化过的来源参考。它不保证来源可安全抓取、权威、可达，也不保证能支撑附近的每一条论断。把 URL 当作不可信的标识符。
• 溯源记录 provider/profile、操作方、访问模式、可选的采集器和 surface ID，以及未披露时的未知账号/个性化上下文。它记录发生了什么，不是置信度分数，也不是对消费端行为的断言。

CLI

run

librarium run <query> [options]

answer 接受同样的 run 选项，另外加 --verify。验证是有边界、需手动开启的。它可以用本次运行中成功的证据和有限的后续搜索，但不会因为某个模型产出了结果就把它标成已验证。验证不完整、受预算限制或失败时，原始答案原样保留。

plan

librarium plan <query> [--answer] [--verify] [run selection options]

plan 执行与真正运行相同的规范请求编译、本地凭证引用解析、预算准入和付费阶段预留策略，但在适配器初始化之前就停下。

它不会发起任何 provider 请求，也不做测试，不导入自定义 provider 模块，不启动自定义脚本，不做精炼或综合，也不创建运行目录或账本。结构校验通过后，允许查询操作系统钥匙串。所以报告出来的凭证只代表本地存在或引用可解析，并没有经过认证。

默认的预览只做研究。加 --answer 会加上综合，加 --verify 会加上验证，而且必须同时带 --answer。这个命令接受那些控制请求形状的 run 参数：--providers、--group、--mode、--parallel、--timeout、--max-cost、--max-estimated-cost、--no-fallback 和 --refine。--json 会输出一份脱敏的、带版本号的规划回执，里面包含精确选中的 profile 和已配置目标、工作流省略项、回退预留、全部四个付费阶段、已知和未知的估算、生效的限制及其来源、警告和诊断信息。对每个请求的付费阶段，它还会在空的付费尝试账本上，对第一个声明的 provider 套用真实的钱包准入计算，同时保留未来的综合预留。后面的阶段标记为有条件，因为前面的付费尝试会消耗预算。被阻止的计划以状态码 2 退出，绝不会被呈现为已准入的部分计划。plan 语法无效也以状态码 2 退出，在 --json 模式下保持结构化和脱敏。

“计划就绪”只意味着本地预检放行了这个请求。它不是认证检查，不是 provider 可用性检查，不是可执行的冻结计划，不是报价，也不保证最终账单。特别是，当辅助阶段的估算在硬预算下未知时，即使研究计划本身能继续，请求的辅助阶段也可能被跳过。

当 --providers 和 --group 都没提供时，run 会选择精选的 quick 工作流。不可用的 quick provider 会被省略，并给出预检诊断；Librarium 不会把请求扩大到所有已启用的 provider。

其他公开命令有 live-validation、status、usage、browse、html、jsonl、refine、completions、ls、groups、init、doctor、config、cleanup、clear、upgrade、install-skill 和 mcp。

命令选项清单

这份清单刻意保持紧凑，覆盖的是上面 run 表格之外的已注册命令选项。

持久化任务：等待、取回和取消

librarium status --wait --retrieve 会等待已有的 Node CLI 异步任务，然后取回已完成的结果。v2 规范运行时只对 background/durable profile 使用持久化句柄。轮询观察状态，取回则把一个观察到的成功持久化句柄变成终态结果。background/process-local profile 不能被表示为持久化任务。

不要承诺每个后台 provider 都支持远程取消。规范验证协议明确把目标标记为 supported_exact_profile 取消或 reconcile_only。已发布的目录目前只为 valyu/research 声明了远程取消。其他所有取消行为都需要对账，而不是编造一个 provider 端的取消调用。

离线规范验证

live-validation 默认禁止网络。用它来检查精确的公开 provider/profile 矩阵，或者重放一个严格的本地 fixture：

librarium live-validation --fixture /absolute/path/to/fixture.json

付费执行刻意做得更难：它需要 --paid、一个绝对路径的冻结预注册、精确的 --confirm 指纹、匹配的审批环境变量值，以及一个不可变的候选检出，其目录、定价和产物指纹都要匹配。fixture 重放不验证真实账户、provider 行为、价格、隐私设置或生产网络。

配置与迁移

v2 配置是严格的 snake_case JSON。根配置包含 version: 2、execution_defaults、providers、custom_providers、trusted_provider_ids、groups 和 runtime。项目配置只能覆盖文档中列出的可选字段。

{
  "version": 2,
  "execution_defaults": {
    "mode": "sync",
    "max_concurrency": 4,
    "inline_attempt_deadline_ms": 30000,
    "background_attempt_deadline_ms": 1800000,
    "request_deadline_ms": 1800000,
    "poll_interval_ms": 10000
  },
  "providers": { "exa": { "enabled": true } },
  "custom_providers": {},
  "trusted_provider_ids": [],
  "groups": { "custom:team": ["exa/search"] },
  "runtime": { "output_dir": "./agents/librarium", "llm_web_search": true }
}

request_deadline_ms 是可选的。设置后，它会限制整个规范运行，跨越主尝试和回退尝试；它不是单个 provider 的超时。

migrateConfig() 接受 v1 或 v2 数据，返回不可变的 v2 配置加提示，或者结构化的问题列表。它不重写源文件。loadConfigV2() 也从不重写；它要求显式路径。只有 saveConfigV2() 会持久化一个校验过的 v2 配置，原子写入且仅所有者可访问。在 Windows 上无法验证等效的仅所有者保护时，它会失败关闭。

从 CLI 迁移 v1 配置

前提：安装 Librarium 2.x，找到全局 v1 配置，做个备份。常规全局路径是 ~/.config/librarium/config.json；项目配置如果用到，通常是 .librarium.json。把 v1 文件留在原地：config migrate 拒绝把任一源路径用作输出。

先预览。预览是默认行为，不写任何文件。

迁移后的 v2 文档是唯一输出到 stdout 的内容，所以你可以直接检查它，或者当 JSON 消费。迁移通知走 stderr，一行一条 JSON Lines。

librarium config migrate \
  --from ~/.config/librarium/config.json \
  --project ./.librarium.json | jq .

没有项目层就省掉 --project。显式传了一个不存在的项目文件会报错。写盘之前，先过一遍 provider 启用状态、分组、超时、输出路径，以及每一个自定义 provider。迁移不会把自定义 provider 加进 trusted_provider_ids。不受信任的自定义 provider 会产生一条结构化 issue，退出码非零。诊断信息里只有错误码和 JSON 指针路径，不会回显密钥值。

确认没问题了再写，写到一个新的 sidecar 路径：

librarium config migrate \
  --from ~/.config/librarium/config.json \
  --output ~/.config/librarium/config.v2.json

写入时会再走一遍 saveConfigV2() 的校验，用的是它那个原子性的、仅限所有者访问的保存边界。目标文件已存在会被拒绝。--force 可以显式覆盖已有目标，但仍然不能覆盖任何一个源文件，通过符号链接或 Windows 大小写别名也不行。别用 shell 重定向去创建候选文件，那会绕过仅限所有者的保存边界。写入要求有一个 v1 全局源文件。原生 v2 输入可以预览、可以校验，但这个命令不会重写它。

--project 只用于预览。带项目路径的迁移会产出一份合并后的有效 LibrariumConfigV2，它不是可以独立写入的项目层。因为 saveConfigV2() 只校验和保存完整的全局 schema，所以 --project 和 --output 一起用会被拒绝。要写全局迁移就省掉 --project。

常规的 config、doctor、run 预检路径都接受迁移后的原生 v2 全局文件。它们会校验，然后投影成现有 Node CLI 的兼容形状。这不会给自定义 provider 授予信任，也不会绕过正常预检。配置菜单和 onboarding 这类旧版写入器，拒绝用它们的 v1 形状替换一个活跃的原生 v2 文件。项目文件仍然沿用现有的项目配置契约。

验证候选文件不需要调用 provider。等一个单独的、显式的、可回滚的安装步骤把它变成全局配置之后，检查常规 CLI 路径：

librarium config migrate \
  --from ~/.config/librarium/config.v2.json | jq -e '.version == 2'
librarium config --json
librarium doctor --json

包维护者改了迁移或 CLI 行为之后还应该跑 npm test。上面这些命令，包括 doctor 的两种形式，都是离线检查配置和凭证是否存在。它们不认证、不联系 provider、不加载自定义 provider 模块、不启动自定义 provider 脚本。只有需要连通性检查时才用 librarium doctor --live，因为它会加载受信任的自定义 provider 代码、发起 provider 网络请求，还可能产生费用。回滚通常就是删掉 v2 sidecar，这个命令从不改动 v1 源文件。如果你之后通过一个单独的、显式的安装步骤激活了 v2 配置，那就用那个安装流程的回滚方式恢复 v1 备份。

Windows 上，仅限所有者的写入依赖受支持的 Windows PowerShell ACL 边界。如果 Librarium 无法建立并验证一个受保护的、仅当前用户可访问的 DACL，写入会在创建目标文件或其父目录之前以非零退出码失败。预览仍然可用。别退回去用重定向或者更宽松的文件权限。

自定义 provider 是可执行代码。trusted_provider_ids 是允许列表，不是沙箱。一个 npm 模块或脚本能以进程权限和环境运行。审查并信任那段代码这件事得认真做。v2 协议见 provider development 文档。

定价与隐私

Librarium 可以记录 provider 上报的用量，也能在有一份经过审查的价格定义时，预留一个精确的、不联网的价格。缺少估算、缺少上报费用、缺少 API 计价单位或 token 价格，都算未知，绝不是零成本的保证。两个硬预算标志都要求每个主 profile 和 fallback 预留 profile 都有一个有界的、不联网的估算，而且完整的主估算必须在执行被接纳之前放得下。启用任一标志时，共享钱包在每次付费尝试前都要求并预留一个已知估算。--max-estimated-cost 把这些接纳和已承诺的估算做比较。--max-cost 还会在累计的 provider 上报实际支出达到上限时停止启动新工作。已经在进行中的工作仍然可能完成并超出任一上限。plan 会针对一个空的付费尝试账本预览同样的计算，并报告由预留导致的首轮尝试阻塞。后续阶段的接纳仍然取决于前面尝试累积的估算和 provider 上报费用。

估算成本、provider 上报的实际成本、未知成本，是三件不同的事。估算不是报价，两个预算标志都不保证最终账单。精炼、综合和验证共享整个运行期的付费钱包，但它们的支出并不是天然固定的：没有有界估算的 helper 在硬预算下会被跳过或阻塞，而 provider 上报的费用可能要在一次已接纳的尝试结束之后才到。

每次 provider 调用都可能把查询和选定选项发给那个 provider。保留策略、计费和账户相关行为归上游 provider 管。SearchAPI 的 zeroRetention 是一项账户能力：只有显式配置时 Librarium 才会发送，账户拒绝时它会失败关闭。SerpBase 声明它可能为计费、调试、防滥用和账户日志记录搜索查询；它没有公布零保留选项，也没有固定的公开保留期限。Librarium 对这两家 provider 都不做更广泛的合规、保留或隐私承诺。

常规测试套件和这个仓库的 demo 不发起 provider 调用、付费调用或网络调用。单独的实况验证审批协议是唯一可能构造其冻结付费目标的路径。

面向 agent

运行 librarium install-skill 安装随附的 Claude Code skill，或者直接用 MCP stdio 服务器：

claude mcp add librarium -- librarium mcp

MCP 服务器暴露五个工具：research、get_results、check_async、list_providers、list_groups。完整证据留在运行目录里，MCP 客户端只取自己需要的：

1. 调用 research。它的结果索引包含 provider 状态、可用的规范身份、来源计数、已知/未知成本，以及一个 outputDir。不内联任何 provider 内容或私有任务句柄。
2. 用那个 outputDir 作为 runDir 调用 get_results。可选地从索引里选一个精确的 resultId，或者按显示的 provider id 过滤。
3. 当 hasMore 为真时，把 nextCursor 作为 cursor 传入，同时带上相同的显式 runDir、provider、resultId 和 part。每个分块自带不可信证据分隔符和精确的 UTF-16 offset/endOffset 值。按 resultId 组装分块时只去掉外层分隔符。

get_results 默认 part: content。用 part: citations 拿分页 JSON 文本形式的引用元数据，解析前先把一个结果的所有分块组装完。limitChars 默认 8,000（允许范围 256–12,000），作用于整个页面而不是单个 provider。页面和索引最多 20 个条目、16,000 字节的格式化 JSON 负载。完整的 MCP 工具结果，包括文本和结构化副本，上限 64,000 字节。元数据和转义会让页面更短。被截断的索引仍然允许通过不带过滤的页面读取每一个结果。available: false 用来区分缺失证据和保存下来的空结果。超大的元数据会返回一个有界的错误，而不是一个超大的响应。

读取不发起 provider 调用、不轮询、不写产物。证据变了，已有的游标就失效，去掉游标重新开始。缺失或不安全的产物不会远程拉取。历史 schema 版本 2 的运行和规范 schema 版本 3 的运行使用同一套分页接口。

check_async 仍然执行一次有界的恢复过程。对规范 schema 版本 3，它会立即取回一个已观测到的完成结果；它的 retrieve 标志只对历史 schema 版本 2 的运行有效。它返回计数和一个 index，不是完整证据。

MCP 响应迁移： 结果索引、异步索引和证据页面都有 schemaVersion: 1 和各自不同的 librarium.mcp.* 类型。这些是 MCP 信封版本，不是产物版本。以前消费内联规范 response、异步 tasks、来源列表或单个有上限的 get_results 响应的客户端，必须改用上面的索引加分页流程。现有的 runDir/provider 输入仍然支持；保存的产物和公开的 Node/PHP 交换契约不变。

Amp orbs

Amp 只需要 Librarium User Skill 和 v2 CLI，不需要 Amp 插件。全局 User Skill 会自动同步到每个 orb。Librarium 仓库的 .agents/setup 会构建检出的源码并运行 npm install -g .，然后验证 librarium --version 报告主版本 2。其他 orb 项目可以在 v2 发布后安装 librarium@^2。

它们不能悄悄沿用 npm v1 的 latest 标签去跑 v2 的工作流。

TypeScript 与 PHP 的共享边界

contracts/v1 是一份语言无关的终端快照，只定义了七个值：ResearchResponse、ResearchResult、Citation、Source、ResultProvenance、Usage 和 ResearchError。它由 Zod 生成，版本独立于 npm 运行时 API，通过精确审查过的 Git 快照加校验和的方式引入。里面没有请求、尝试、生命周期记录、持久句柄、协调器状态、配置、产物存储、JSONL，也没有自定义 provider 协议。PHP 的 run()/queue() 和 TypeScript 运行时服务都在这个边界之外。终端交换 schema 并不暗示任何一种运行时架构。

由测试守护的文档事实

tests/public-documentation-drift.test.ts 从源码中推导出成员名单、精选工作流、CLI 命令与选项、MCP 工具、包导出、Node 最低版本，以及协议和产物的版本号。它校验这份 README 以及配套公开文档里的事实区块。区块之外的叙述文字仍然由人撰写。

常见问题（FAQ）

Librarium 的“证据溯源”到底是什么意思？

它把溯源当一等公民：每条结果保留采集来源和访问链路，但不会把“多个来源说法一致”当成证明，而是由调用方自己判断结果含义。

librarium、librarium/core、librarium/node 三个导入边界怎么分？

librarium 放 Worker 安全的 schema、目录与纯配置；core 提供注入式规划、传输与执行端口；node 补宿主相关的配置、凭证和校验服务，三者刻意可组合。

Librarium 的 quick 和 deep 工作流有什么区别？

quick 精选低延迟的 grounded 与 search profile，用于快速发现和带引用答案；deep 从已实现的研究报告 profile 派生，适合更长、含持久化的研究任务。