voyager-agent

@dir-ai/voyager-agent

唯一通用的 Voyager。 一个轻量、与模型无关的编排器，将模块化的 Voyager 感知能力——voyager-repo（代码）、voyager-net（主机），以及连接它们的认知契约——整合为一个 Agent。你只需指定目标；Voyager 就会激活所需的感知能力，执行一场实时任务，将证据关联到同一张图中，并得出结论。

这是组合，而非单体。 Agent 不会吸收感知能力，而是调用已发布的器官，并将它们观察到的内容转换到共享的 CognitiveClaim 基础层。推理模型是一个可替换的接口（Brain）；随附的规则型大脑无需 LLM 即可运行。

感知是自主的，行动不是。 这里的每种感知能力都为只读。任务中发现的任何补救措施都会作为需经同意、暂不执行的操作列出，并且此编排器绝不会应用这些操作。

安装

npm i -g @dir-ai/voyager-agent

使用

# Orient in a repo and flag risk (voyager-repo)
voyager-agent mission "audit this project" --repo .

# Audit ONE host you own (voyager-net — fail-closed, needs --authorized)
voyager-agent mission "check my server's exposure" --host example.com --authorized

# Observe a live page (voyager-browser — read-only, static HTML)
voyager-agent mission "check my landing page" --url https://example.com

# All three senses in one mission; vet 10 dependencies; machine-readable
voyager-agent mission "full audit" --repo . --host example.com --authorized --url https://example.com --check-deps 10 --json

各种感知能力会并行启动，并且具有弹性：发生错误（甚至抛出异常）的感知能力会生成低置信度、带标记的观察结果——它绝不会导致任务崩溃，也不会丢弃其他感知能力的有效结果。

随后，任务会重新规划：它会根据信息增益，选出最能提供信息的下一个探测并执行，执行轮数受 maxRounds 限制。探测的执行方式由可注入的 dispatch 接口决定（由模型决策）；安全默认行为只会重新读取（深入审查仓库依赖），绝不会采取行动。verify 声明会结束任务，因此 state().satisfied 能准确反映任务是否已满足。

Voyager — one agent, one entry.
goal: "orient in this repo and flag risk"

  👁 observe  [repo]  (70% · moderate)
     @dir-ai/[email protected] — The one universal Voyager…
     ↳ [low] no-lockfile: no lockfile — installed versions are not pinned/reproducible
  🧠 infer  [memory]  (70% · moderate)
     repo observed; 0 high/critical signal(s). No high-severity issue surfaced.

next probe: [repo] open src/index.ts

作为 MCP 服务

一个工具：run_mission——描述目标，即可获取完整的声明图。

voyager-agent mcp            # stdio

{
  "command": "voyager-agent",
  "args": ["mcp"]
}

作为库使用

import { runMission, DeterministicBrain, type Brain } from '@dir-ai/voyager-agent'

const { mission } = await runMission(
  'audit this repo and my host',
  { repoPath: '.', host: 'example.com', authorized: true /* your own host */ },
  Date.now(),
)

for (const claim of mission.allClaims()) console.log(claim.operation, claim.sense, claim.verdict)
console.log(mission.state().bestNextProbe)   // the most informative next step
console.log(mission.state().contradictions)  // where two senses disagree

使用你自己的模型

Brain 接口正是关键所在——LLM 可以通过它接入，而无需改动感知能力、记忆或任务机制。随附现成的 LlmBrain：只需为它提供一个与模型无关的 complete() 函数，它就能通过模型进行规划和综合。可接入 Claude、本地服务或任何兼容 OpenAI 的端点——Voyager 从不依赖特定 SDK。

import { runMission, LlmBrain } from '@dir-ai/voyager-agent'

const brain = new LlmBrain({
  // Return the model's text for these messages — that's the whole dependency.
  async complete(messages) {
    const res = await myModel.chat(messages)   // Claude, local, OpenAI-compatible…
    return res.text
  },
})

await runMission('audit this repo and my host', { repoPath: '.', brain }, Date.now())

LlmBrain 故障安全：如果模型出错或返回无法解析的输出，它会在该步骤回退到内置规则型大脑——错误的补全绝不会导致任务失败，只会让该步骤变得不那么聪明。你也可以直接实现 Brain 接口，获得完全控制权。

工作原理

        intent ─▶ Brain.decompose ─▶ goals
                        │
          ┌─────────────┼───────────────┐
          ▼             ▼                ▼
   voyager-repo    voyager-net      (more senses…)
     scout()         scan()
          │             │
          ▼             ▼
      adapters: brief ─▶ CognitiveClaim
          │             │
          └──────▶ MissionGraph ◀───────┘
                 (contradictions, causal chain,
                  best-next-probe, memory)
                        │
                        ▼
              Brain.synthesize ─▶ conclusion

每种感知能力都会生成一个 CognitiveClaim；MissionGraph 会将它们关联起来——自动检测跨感知能力的矛盾、构建因果链，并根据信息增益指出最能提供信息的下一个探测。感知能力发生错误时，会生成一个低置信度的 observe 声明，并标记未知项——绝不会错误地宣称“一切正常”。

Voyager 系列

软件包	感知能力	功能
@dir-ai/voyager	网络	经过验证的互联网检索，受 OSV 检查
@dir-ai/voyager-repo	代码	熟悉代码仓库，审查依赖
@dir-ai/voyager-net	主机	经授权的只读主机审计
@dir-ai/voyager-contract	—	感知能力使用的认知契约
@dir-ai/voyager-agent	全部	组合这些感知能力的唯一 Agent

安全

• 只读检测。 不会在你的系统上安装、执行或修改任何内容。
• 故障时拒绝访问的主机审计。 只有指定 --authorized / authorized: true 时，才会扫描主机；仅限单台主机（不支持范围/URL），并会阻止访问云元数据。
• 经同意后采取行动。 会说明补救措施并暂不执行，将其作为声明中的 unknown 显示——此编排器绝不会应用该措施。
• 如实说明不确定性。 会明确标注置信度和 strength；检测出错会标记为未知，而非给出无问题的结论。

许可证

MIT © dir-ai