ambit

---

Ambit 是什么

ambit（源自拉丁语 ambitus：环绕、周界、行动范围）是一个人能够触及的边界。与 Agent 协作时，你的边界由一系列组件共同决定：LLM 提供商、MCP 服务、本地 CLI 工具、技能目录、凭据和机器，各自都有自己的配置文件。

**Agent 配置能做什么，并未记录在任何配置文件中。**它由分别配置的组件组合而成；某个已配置的组件可能无法运行，而且这些配置都没有说明该配置允许做什么。Ambit 会计算你的可达范围，并帮你拓展范围：声明的检查会说明某个组件是否正常运行，你设置的授权会说明哪些操作可以免于询问而运行，工作账本则会记录某项变更是否为你节省了时间。

Ambit 会将这些配置读入一个统一模型，即能力图谱。每个服务、模型、技能和声明的凭据都是一个节点，精选树中的每项能力也都是一个节点；边则记录一个节点依赖于什么，或向另一个节点提供什么。我的设置会列出配置中声明的内容，地图则会绘制精选树，并标出你所在的位置。你触及范围的边缘称为前沿，再向前就是下一步。Ambit 会根据图谱回答：

1. **下一步可以做什么？**列出你已满足前置条件的能力，并为每项能力估算设置时间；还会列出差一步之遥的组合，即只差一两个前置条件就能解锁额外工具的组合。分别配置的工具也能组合使用：向量存储加本地嵌入，就能满足语义检索的前置条件，而这两者单独的配置文件都不会提到这一点。
2. **接下来设置什么最值得？**根据哪些因素一直阻碍你的 Agent，以及每一步能解锁多少内容进行排序；等工作账本记录了几周后，还会根据能节省多少人工精力进行排序。
3. **哪些功能确实可用？**配置了工具，不代表工具能正常运行。Ambit 会运行每项能力声明的验证检查（ambit verify），并区分“已安装 ≠ 可用 ≠ 已授权”。未经验证的能力仍会保留；检查失败的能力则会从计划和权限中排除，直到再次通过检查。
4. **依赖项失效会造成什么影响？**Ambit 会追踪传递依赖：三个看似冗余、却共用同一个 API 凭据的提供商，会被标示为单点故障。

你可以在终端中提问。你的 Agent 可以通过 MCP 提问：在尝试之前，它们能做什么；遇到限制时，怎样才能解除限制，并拟定一项由你审批的变更。Ambit 本身也是一个 MCP 服务，使用与它读取的工具相同的协议：一个 元 MCP 服务。

Ambit 使用的术语

终端和地图使用相同的术语。

• 能力：你的配置可以做的一件事。配置中的每个 MCP 服务、Agent、技能、提供商、模型和命令都会成为一个，精选树中的每个节点也一样。
• 已触达、下一步、受阻：已触达表示有已配置的提供商满足该能力，且满足其必需的前置条件。下一步表示已满足所有必需的前置条件，但缺少已配置的提供商；它紧邻当前边界之外，并显示在 ambit goal 中。受阻表示缺少必需的前置条件。
• 已验证：已触达，且其声明的检查最近已通过。ambit status 会将这些报告为已证实。已触达是关于配置的事实；已验证是关于已运行检查的事实。
• 必需与可选前置条件：必需的前置条件会限制该能力；可选的前置条件会增强该能力，但不会构成限制。只有必需的前置条件会阻塞节点。数据模型和 CLI 将它们称为硬性和软性前置条件。
• 组合能力：精选树定义为由其他能力组合而成的能力，例如由向量存储和本地嵌入组成的语义检索。地图上的每个节点都是组合能力，因此它们的 ID 都以 combo: 开头。
• 时代：能力在树中的层级。较晚的时代依赖较早的时代。时代描述的是顺序，而非重要性。

---

适用对象

任何运行 AI Agent、希望它们发挥更大作用的人。在小型配置中，只有一个运行时和几个 MCP 服务，Ambit 主要会告诉你接下来该添加什么，以及缺少某个前置条件会解锁什么。在较大型的配置中，有多个运行时、数十个服务和第二台机器，Ambit 主要会告诉你哪些已配置的工具未通过检查，以及哪些功能会因此无法使用。

演示会从示例配置的下一步开始，点亮它将解锁的内容，并询问你使用哪个 Agent。粘贴该 Agent 的配置，或勾选它运行的服务，你的配置就会在不上传任何内容的情况下映射到同一张地图上：它能触达树中的哪些部分，以及最值得采取的三个下一步，排序方式与 npx ambit-cli 在本机上的排序相同。示例中的其余内容也都在，供需要了解的人查看：展示这些触达能力所依赖条件的中断事件、一个已经失败的检查，以及每项变更都必须经过的审批。

快速开始

使用方式	能为你做什么
在浏览器中	打开托管演示查看示例配置，或导入你自己的 MCP 配置（来自 Claude Code、Claude Desktop、Cursor、Windsurf、Gemini CLI、Cline、Roo Code、Copilot CLI、Kiro 或 OpenCode），配置就会显示在当前标签页的地图上，不会上传任何内容，并展示再多一步就能为它开启什么。手边没有文件？勾选你运行的服务即可。
在你的设备上	运行 npx ambit-cli（需要 Node 22.18 或更高版本），或运行 brew install zz-plant/tap/ambit && ambit。它会读取你的实际 Agent 配置，列出发现的内容，并展示再多一步就能开启什么。最后会给出一件可执行的事：npx ambit-cli web，在 localhost 上提供相同的地图视图。npm install -g ambit-cli 会将 ambit 添加到你的 PATH。
使用地图	git clone https://github.com/zz-plant/ambit.git && cd ambit && ./bootstrap.sh web 会根据你自己的配置构建关系图，并提供本页图片所示的地图。
在云 IDE 中	在浏览器标签页中运行地图的完整代码库副本，不会接触你设备上的任何内容。容器中没有你的配置，因此显示的地图不包含你的任何内容：这是尝试代码的方式，而不是映射你的配置。
通过你的 Agent	通过 MCP 注册 Ambit 后，Agent 就能在尝试之前询问自己能做什么。将它连接到你的 Agent中提供了代码片段。

npm 和 Homebrew 会在 macOS 或 Linux 上安装带标签的发行版本。./bootstrap.sh 会发现 OpenCode、Claude Code、Cursor、Windsurf、Gemini CLI、Claude Desktop、Codex CLI、Cline、Roo Code、Continue、Zed、VS Code、Copilot CLI、Amp、Goose 和 Kiro，技能目录 ~/.agents/skills、~/.opencode/skills 和 ~/.config/opencode/skills，以及 Ollama 和 LM Studio 保存在磁盘上的模型；随后构建本地 SQLite 关系图，打印与 npx ambit-cli 相同的摘要，并在 ~/.local/bin 位于你的 PATH 中时将 ambit 链接到该目录（否则会打印 ln -s 命令）。./bootstrap.sh --dry-run 不会写入任何内容：它会报告是否存在 OpenCode 配置、正在运行的 Ollama 和技能目录。

---

Ambit 在技术栈中的位置

Ambit 位于协议层之上、工作流编排之下。它的 CLI、MCP 服务和门控机制既不会路由 Agent 的调用，也不会执行这些调用。唯一能够执行 Agent 步骤的部分是控制平面，你需要从代码库副本中自行启动，并且只能使用其选择加入的 Docker 适配器。

系统	查找工具	了解前置条件顺序	区分正常运行与已配置	衡量人工投入	控制 Agent 可执行的操作
向量工具 RAG	按相似度	–	–	–	–
工作流状态机（LangGraph）	–	在单个任务内	–	–	在单个任务内
软件包管理器（Nix、Homebrew）	–	针对二进制文件	–	–	–
扁平 MCP 目录（Smithery、各类注册表）	按名称	–	–	–	–
Ambit	按所需内容	跨整个主机	✓ 声明的检查	✓ 工作台账	✓ 权限契约、签名批准

关于架构基础、经济循环以及与既有工作的比较，请参阅Ambit 背后的理念、你的配置，从 A 到 B和独自构建。

---

在终端中提问

命令	可回答的问题
ambit status	环境健康状况：已连接哪些内容、其中有多少已验证、哪些未通过声明的检查、哪些只有一个提供方、待处理的审批，以及下一步要输入的那条命令
ambit goal <name>	解锁某项能力所需的路径及其顺序，并附上设置时间估算
ambit impact <id>	此依赖失效会导致哪些下游内容无法工作
ambit graph combos	组合能力，包括只差一项前置条件即可具备的能力
ambit authority	每项操作的权限：哪些可在无人干预时运行，哪些需要确认
ambit verify [id]	运行某项能力声明的检查，并记录是否通过
ambit weigh	每个工具服务的工具列表在每次会话、每种运行时中占用多少上下文，以及哪些工具从未出现在使用记录中
ambit history [since <when> [<until>]]	前沿如何变化，并区分已获取的内容与新出现的内容
ambit share	在本地写入一份独立的 HTML 快照，可安全发布

ambit help 介绍首次会话，ambit help --all 展示完整功能，ambit help <term> 介绍一个概念。

上面的命令会读取能力图。另一组命令（attention、work、usage、opportunities、roi、audit）会读取本地工作记录：运行整个技术栈所需的人力时间和成本。在记录会话之前，它们会说明缺少哪些数据，而不会打印数字；记录几周后，它们会提供更多信息。常见问题介绍了如何开始记录。

ambit status — 环境现状

$ ambit status

    39 of 70 reached · 0 proven · 8 with a single provider
    ──────────────────────────────────────────────────────
    proven          0
  › unproven       15  11 provable now · 4 with no check
    failing         0
    entries        24  from your config; checks run on what they provide
    last check  never

    actions: 18/66 reached
    provable now: Automated Tests, Browser Automation, Code Intelligence, Continuous Delivery, Data Access, File Editing, Local Runtime, Shell Execution and 3 more
    domains:
      ████░░░░░░ ai-ml     5/13
      ██████░░░░ backend   7/11
      █████░░░░░ devops    4/8
    …

    Next  ambit verify · turns 11 of the unproven into evidence

这是一个全新图谱，尚未运行任何检查：已连接和已验证的数量排在前面，规则下的四项计数之和等于已连接数，› 标记需要人工处理的计数，最后一行列出下一步要输入的命令。CI 会从一个测试图谱中捕获此代码块；如果它与命令的输出不一致，检查就会失败。

ambit impact — 下游依赖影响

$ ambit impact mcp:playwright

    If playwright went away
    ───────────────────────
  › Stops working  Automated Tests, Browser Automation, Continuous Delivery, Observability · and the 3 actions they confer
    Survives  Tool Protocol (12 other providers)

受影响的能力会优先列出，并以 › 标记，覆盖完整依赖链：如果持续交付依赖自动化测试，那么它也会失效。仍可用的能力会显示剩余提供方数量，并将会一同失效的共享凭据计算在内。给定一项凭据，impact 会说明撤销它会导致哪些内容无法继续运行，与 ambit credentials 的结果一致。

ambit share — 哪些内容可以离开图谱，哪些不可以

ambit share 会根据允许列表生成 HTML：名称、类型、类别、领域、时代、状态、生命周期和边。命令、URL、路径、描述和经济信息都不会写入文件；人员会显示为“一位人员”，而 --redact 会将每个非精选名称替换为其类别。不会上传任何内容；将文件写入本地就是此命令的全部操作。

从脚本或 Agent 的 Shell 中使用

--json 会将任何答案以数据形式打印，只有在终端中才会显示颜色，退出代码则表示命令是否成功。以下两条命令可以像 git diff --exit-code 一样控制脚本：

ambit can shell-execution --exit-code     # 0 go ahead, 1 put it to the person, 2 stop
ambit verify shell-execution --exit-code  # 1 unless every check that ran passed

CLI 参考列出了所有退出代码和标志。

---

将它连接到你的 Agent

你可以先试用 Ambit，再将它连接到任何东西：ambit status 会读取本地 Agent 配置和会话令牌日志（Claude Code、Codex、OpenCode、Amp），并且只写入 Ambit 自己的数据库（~/.local/share/ambit/graph.db）。它不会修改任何配置文件，也不会发起网络请求；删除该文件即可移除它记录的内容。llms.txt 概述了 Agent 应在何时推荐 Ambit；面向 Agent 展示了前后会话指标。

Claude Code

从市场安装插件：

claude plugin marketplace add zz-plant/ambit
claude plugin install ambit@ambit

然后在会话中输入 /ambit，查看你自己的设置概况：它读取了什么、覆盖了树的多少内容，以及哪一步能带来最大的开放范围。该插件会注册 MCP 服务，在会话开始时向 Agent 提供简报，并将工具执行和审批跨度记录到 ~/.local/state/ambit/claude-code.jsonl。它从本地会话日志读取令牌用量，但不会写入这些日志。若要禁用记录，请设置 AMBIT_NO_LEDGER=1。

若不使用插件，手动注册：

claude mcp add ambit -- ambit mcp --profile=agent

--profile=agent 会公开十个工具，即 Agent 在行动前用于检查的规划和验证工具，占用约 4.4KB 的提示词上下文。不指定该标志则会公开所有工具（约 19.5KB）。无论哪种方式，服务都会按名称响应未列出的工具，但大多数客户端只会调用它们看到的工具，因此在 --profile=agent 模式下，连接说明会让 Agent 使用 ambit 命令访问其余内容：单点故障、预算、事件、审计跟踪，以及 ambit help --all 列出的所有内容。深入介绍列出了所有工具，并说明了调用的分派方式。

ambit-gate@ambit 是一个配套插件，会在每次工具调用时运行 ambit gate，因此你在 Ambit 中拒绝或设置为先询问的操作，会被拒绝或向你发起询问。下面的钩子代码块也能手动实现相同功能。

Ambit 还会发布 ambit://briefing 资源，客户端连接时会读取该资源：已触达和已验证的内容、当前失败的内容、等待你处理的事项、上周阻碍工作的因素，以及值得接下来触达的内容及每一步的触达范围，约 1,200 个令牌。若要自行将其置于每个会话的顶部，请在 ~/.claude/settings.json 中添加钩子：

{
  "hooks": {
    "SessionStart": [{ "hooks": [{ "type": "command", "command": "ambit briefing" }] }],
    "PreToolUse": [{ "matcher": "*", "hooks": [{ "type": "command", "command": "ambit gate", "timeout": 10 }] }]
  }
}

PreToolUse 钩子会将 Ambit 的门控机制绑定到 Claude Code。每次工具调用前，ambit gate 都会识别所执行的功能：禁止的操作会被拒绝，需要人工确认的操作会提示用户，获准或未映射的操作则交由 Claude Code 的标准权限流程处理。门控机制只能限制权限，不能扩大权限。每次调用会增加约 130 毫秒的延迟（在搭载 Apple M1 Max 的设备上使用 0.6.0 测得）。在终端中直接运行 ambit gate 可查看其输出。

ambit statusline 会为 Claude Code 的状态栏打印一个片段，并在每条消息后刷新：失败的检查、待处理的提案，以及已验证的功能数量（例如 ! 1 failing: Browser Automation · › 2 proposals to decide）。未启用的类别会被省略，因此健康的图谱会显示 12 verified。该命令以只读方式查询数据库，不会写入任何内容，耗时约 80 毫秒（在搭载 Apple M1 Max 的设备上使用 0.6.0 测得）。由于插件无法自动配置状态栏，ambit connect claude-code --statusline 会将条目添加到 ~/.claude/settings.json，同时将现有文件备份为 settings.json.bak，且绝不会覆盖你已有的状态栏。若要手动配置：

{ "statusLine": { "type": "command", "command": "ambit statusline" } }

Claude Code 只运行一个状态栏命令。若要保留你自己的命令并添加 Ambit，请将以下两行保存为脚本，把 npx ccstatusline 替换为你的命令，然后将 command 指向该脚本：

input=$(cat)
printf '%s  %s\n' "$(printf '%s' "$input" | npx ccstatusline)" "$(printf '%s' "$input" | ambit statusline)"

OpenCode

ambit connect opencode 会根据文件现有格式，将条目添加到 ~/.config/opencode/opencode.json 中，无论它使用的是 OpenCode 1 还是 OpenCode 2 的格式，并会先将文件原有内容保存在 opencode.json.bak 中。若文件含有注释，则不会修改，因为重新写入会删除注释。手动配置时，OpenCode 1 的格式如下：

{
  "mcp": {
    "ambit": {
      "type": "local",
      "command": ["ambit", "mcp", "--profile=agent"],
      "enabled": true
    }
  }
}

OpenCode 2 会将相同条目放在 mcp.servers 下，并用 "disabled": false 代替 "enabled": true。

两个客户端都假定 ambit 位于你的 PATH 中。Homebrew 和 npm install -g ambit-cli 会将它放在那里；如果 ~/.local/bin 已在 PATH 中，bootstrap.sh 也会如此。否则，请使用 npx -y ambit-cli mcp --profile=agent，或使用 cli.js 的绝对路径。Agent 可以读取映射，询问某个目标缺少什么，并提出配置更改。应用更改始终需要批准；批准是单独的本地操作，不是 MCP 工具。

Cursor

ambit connect cursor 会将服务添加到 ~/.cursor/mcp.json。使用 --ledger 时，它还会在 ~/.cursor/hooks.json 中的四个事件上添加一个钩子，与已有钩子并存，并将文件原有内容保存在 hooks.json.bak 中；--dry-run 会打印钩子的命令和事件，不写入任何内容。该钩子会为每个事件向 Claude Code 插件写入的文件 ~/.local/state/ambit/claude-code.jsonl 追加一行，记录：钩子运行的时间和对话 ID；对于已运行的 shell 命令或 MCP 调用，记录服务和工具的名称，以及 Cursor 报告的耗时（不包括你等待批准的时间）；对于失败的调用，记录 Cursor 为其分配的 ID、错误文本、失败类型，以及是否由你中止；以及对话结束的原因。绝不会记录命令文本或输出、MCP 调用的参数或结果、文件、你的提示词或邮箱。Cursor 的钩子不会报告令牌计数或批准提示，因此 Cursor 运行不会记录这些信息。钩子不会向 Cursor 发出任何请求，因此既不能阻止调用，也不能允许调用；AMBIT_NO_LEDGER=1 可将其关闭。手动配置时，请使用试运行打印的路径：

{
  "version": 1,
  "hooks": {
    "afterShellExecution": [{ "command": "node /path/to/ambit-cli/plugins/cursor/ambit-ledger.mjs", "timeout": 5 }],
    "afterMCPExecution": [{ "command": "node /path/to/ambit-cli/plugins/cursor/ambit-ledger.mjs", "timeout": 5 }],
    "postToolUseFailure": [{ "command": "node /path/to/ambit-cli/plugins/cursor/ambit-ledger.mjs", "timeout": 5 }],
    "sessionEnd": [{ "command": "node /path/to/ambit-cli/plugins/cursor/ambit-ledger.mjs", "timeout": 5 }]
  }
}

值得传授的唯一习惯

运行本次会话中尚未使用过的工具之前，请先用该能力调用 ambit_can。若返回 yes，就执行。若返回 ask，就交给对方处理。若返回 no，说明 缺口已记录，因此不要换个名字重试。

服务会在 MCP 握手期间发送这条指示。对于不会向模型上下文公开服务指示的客户端，ambit init-rules 会将指引写入 CLAUDE.md、AGENTS.md 或 .cursorrules。能够访问 shell、但没有 MCP 连接的 Agent，可以使用 ambit can <capability> --exit-code 检查权限。拒绝会作为缺口记录在工作日志中；反复出现的缺口会在下一步待配置事项的排名中上升。

---

地图

./bootstrap.sh web 会在 CLI 读取的图谱上呈现五个视图。

• 地图：绘制了你的可达范围的精选树。顶部的线条会说明地图发现了什么：检查失败，或是能解锁最多内容的下一步。
• 我的设置：配置中声明的条目、检查历史记录，以及每个条目提供的能力；最后列出 Agent 使用了哪些地图上没有对应节点的内容。「简报」部分会显示 Agent 连接时收到的上下文载荷，「环境」部分则会呈现仓库和基础设施扫描结果。每个部分都可通过地址定位，因此链接可以直接打开对应部分。
• 时间与成本：工作账本、无需询问即可执行的操作、接下来可触达的内容，以及过去一周的前沿演变。
• 审计：按时间倒序排列的提案、审批、检查执行和工作会话日志，可按查询条件搜索。
• 提案：决策队列，每张卡片对应 Agent 起草的一项变更；你可以一次决定多项变更。

选择一个节点会显示下游依赖项：如果该节点失效，哪些依赖项也会失败；或者要触达该节点，还缺少哪些前置条件，以及预计的设置时间。模拟故障会呈现级联影响：失效依赖项以红色填充，未配置节点以红色描边，失去冗余提供方的能力以琥珀色标示。模拟解锁会高亮显示只需获取一项前置条件即可触达的节点。两种模拟都不会写入数据。三种视图模式可筛选地图：标准（已触达、下一步、受阻）、关注（导致人工频繁介入的工具）和权限（无人监督、需要人工确认、禁止）。

当 Agent 通过 MCP 提出配置变更时，提案视图会在你签署前将其显示为计划：包含步骤、其中不可撤销的步骤、将解锁的能力、成本，以及相关的早期审批。批准后会创建一份已签名的凭证；ambit apply 会将变更写入 Claude Code、Cursor、OpenCode 或 --to 指定的运行时；如果无法写入，则会打印该运行时自己的命令。

参考文档介绍了其余内容：各标记的含义、焦点、迷你地图、可重放地图历史状态的时间线、一次决定多项草案，以及将草案推送到手机。

---

工作原理

发现流程会将主机配置读入嵌入式 SQLite 图谱，之后由三个界面读取图谱：CLI、MCP 服务和地图。发现、验证和工作账本都会写入图谱。Agent 配置只会通过你批准的提案进行变更；或者通过地图中已有条目的开关进行变更，但该开关无法创建条目。

每个客户端都从自己的标准配置路径读取，每个服务也始终归属于列出它的客户端。如果两个运行时引用了同一个服务，Ambit 会将其建模为一个具有两个提供方的能力，因此同一个二进制文件被列出两次不会被算作冗余。系统会在 Ollama 和 LM Studio 存放文件的磁盘文件夹中查找本地模型，因此这两个服务都无需运行。每个模型都会归入 local 提供方，与托管推理成本分开。

发现的能力会被放入一棵包含九个时期的精选树：其中七个时期面向 Agent 设置，从基础和模型访问到工具使用、记忆、自主性和保障，再到自主掌控；另外两个时期面向 Agent 构建的产品，即产品（托管、生产数据库、账户、支付、电子邮件）和运营（错误跟踪、分析、运行时间、备份，以及在完成发布检查清单后即可到达的准备发布）。每项能力都会列出其前置条件，因此可达状态是根据这些条件计算得出的，而不是采用配置所声称的状态。

已配置不代表可用

Ambit 将两个属性区分开来：

• state 是结构属性：某项内容是否已配置，以及它依赖什么。这些信息会记录在前沿账本中。
• lifecycle 是健康状态：声明的验证命令是否实际通过。某项能力可能已完整配置，但仍处于 broken 状态；也可能处于 degraded 状态，这表示它正在恢复：最近一次检查在此前检查失败后通过了。

可用性由 lifecycle 而非 state 决定，而且检查只能降低可用性：未经验证的能力仍会保留在计划中，而检查失败的能力会从计划、模拟、目标、权限检查和机会排名中排除。一次成功的检查会让处于故障状态的能力恢复为未验证状态；连续通过五次检查前，它都会被标记为正在恢复。ambit status 会报告已验证、未验证和失败的数量；地图会为每个已到达的节点标记徽标：检查通过时显示 ✓，检查失败时显示 !，已配置但从未验证或正在恢复时不显示任何标记。

脆弱性是计算得出的，而非猜测

• 单点故障：只有一个提供方的能力。
• 瓶颈：根据有多少其他能力依赖它们对能力进行排名。地图会用基石标记最重要的几个。
• 共享凭据：共用一个 API 令牌的提供方会同时失效，因此不构成冗余。在 credentials 块中声明共享凭据后，即可使用 ambit impact credential:... 分析凭据撤销的影响。

---

控制平面

Ambit 会判断某个步骤是否可以在被要求执行的地方运行，这个判断会在三个位置生效：始终由 ambit apply 执行；对于经由此拦截器路由的执行，由此拦截器执行；安装 ambit gate 钩子后，由 Claude Code 的工具调用执行。其他运行时可自行决定是否调用 ambit_can。

它从代码检出目录运行。 此拦截器是一个参考实现，不属于 ambit 命令，因此 npm 和 Homebrew 不会安装它。在克隆目录中，npm run demo:incident 会在临时图上重放本节末尾的演示，node --experimental-sqlite src/control_plane/cli.ts --help 会列出其命令。exec <envDir> <dbPath> '<request>' 会针对 dbPath 处的图，将一个步骤经由门控路由。其他命令用于演示：setup-env 会将其测试用 actor 和能力写入指定的图中，并替换任何 ID 相同的行；verify-node 会设置一个没有检查运行记录的生命周期，因此请让这两个命令都指向新文件，绝不要指向 ambit where 打印的图。

主机级 Agent 工具是真实的攻击面，因此拦截器可以位于 Agent 与 shell 之间。经由它路由的工具调用到达你的机器之前，src/control_plane/proxy.ts 中的代理会验证三个条件：前置能力已具备、能力已验证且正常运行，以及调用方已获得明确授权。任何一项不满足，调用都会被拒绝（AMBIT_BLOCKED_UNAUTHORIZED，退出代码为 2），且系统状态不会改变。被拦截的调用会生成一份提案草稿和一个 HMAC 挑战；ambit approve <proposal-id> --by=<person> 会创建一份由执行器验证的签名授权凭证；如果提案被修改，该凭证就会过期或失效。Span 会记录每次评估、挑战和凭证。

决策会针对你指定的图作出。控制平面启动时会确定门控另一端的内容，每个 span 都会标明它。默认的 simulatedAdapter 是一个测试夹具：它会将更改合并到 JSON 文件中，但不会运行任何内容。

使用 AMBIT_ADAPTER=docker，或在 src/control_plane/cli.ts 上使用 --adapter=docker，即可在门控另一端启用 Docker 适配器，已获批准步骤的 payload.command 会在一次性容器中运行。授权针对的是具体命令：人员签署的步骤中会显示该命令，携带不同命令的重试会被拒绝。紧急放行不会在此处运行任何内容，因为 Agent 不能授权自己的命令。每个步骤都会使用你自行拉取的镜像创建一个独立容器（除非 AMBIT_DOCKER_IMAGE 指定其他镜像，否则使用 alpine:3.20），容器无网络、根目录只读、丢弃所有 Linux 能力、使用非特权用户，并限制内存、CPU 和进程数。之后容器会被移除，容器输出会经过截断后返回结果；步骤若以非零状态退出，运行就会以失败告终。只有在启动控制平面时设置了 AMBIT_DOCKER_NETWORK=bridge，且对其能力的 network 操作授权返回 ALLOW，该步骤才能访问网络。除非 AMBIT_DOCKER_WORKDIR 指定某个目录，否则不会挂载主机上的任何内容；即使指定，也只会以只读方式挂载该目录，绝不会挂载你的主目录、其中的点目录或 Docker socket。如果 Docker 无法运行该步骤，控制平面会在运行任何内容之前拒绝执行，且不会回退到模拟器。

这两种适配器都不会将任何内容部署到任何地方。其他适配器（例如 Kubernetes、部署 API）只需实现相同的三方法 EnvironmentAdapter，门控上方的一切都无需改变。INCIDENT_TRACE_001 讲述了一个部署 Agent 在执行过程中被拦截后得到补救的案例，而 npm run demo:incident 可在 90 秒内重放该案例；使用 AMBIT_ADAPTER=docker 时，获授权的部署会在容器中运行 echo。

---

安全不变量

Ambit 会读取开发者工具链，并写入 Agent 配置，因此以下属性是固定的。SECURITY.md 完整说明了每项内容，包括适用范围和不适用范围；AGENTS.md 说明了每项属性的强制执行位置。

1. 仅限环回地址。 API 服务绑定到 127.0.0.1。不接入局域网，不使用隧道。
2. 来源白名单。 如果请求的 Origin 不是 Ambit 自己的页面（包括位于其他本地主机端口的页面），则会在路由之前拒绝请求并返回 403，因为简单请求会跳过预检，仅靠响应标头无法阻止此类请求。
3. 不通过 HTTP 创建条目。 HTTP 层只编辑已存在的条目，不做其他操作。MCP 条目包含运行时稍后会执行的命令，因此通过 HTTP 创建条目会造成远程代码执行；添加服务时会返回一段代码片段，供你粘贴。
4. 不执行你没有输入的出站操作。 图谱是存储在你机器上的嵌入式 SQLite 数据库，且不包含任何遥测。除非你输入命令或 Agent 调用工具，否则不会打开套接字、启动服务或运行检查；服务本身绝不会执行这些操作。FAQ 列出了所有可能访问网络的命令、这些命令发送的内容及其发送位置。

---

文档

• FAQ：需要安装什么、哪些内容会离开你的机器，以及为什么第一天没有任何待关注命令。
• 深入解析：全面介绍上述所有内容所依据的模型、完整图谱，以及 Ambit 在可修订委托循环中的位置。
• 每个 AI Agent 在哪里保存其 MCP 配置 · MCP 服务宕机会造成什么影响 · 审计 Agent 的 MCP 服务 · Ambit 与 MCP 网关：针对人们常搜索的问题，提供上述命令对应的解答。
• 安全 · Agent 不变量 · 支持 · 贡献：完整介绍上述不变量、每项不变量的强制执行位置、各类问题的反馈渠道，以及如何提交更改。
• 其他所有内容：论证、理论、Jev、设计说明、更新日志和事件记录。
• llms.txt：用一页介绍项目，供正在决定是否推荐该项目的 Agent 查看。

---

贡献

欢迎提交新的能力模型、运行时读取器、可视化工作和边缘案例报告。标有 good first issue 的问题限定在半天内可完成，并注明了可着手修改的文件。CONTRIBUTING.md 将引导你从克隆项目到提交通过检查的拉取请求，并列出 CI 运行的所有检查。

---

支持项目

Ambit 是一个个人项目。如果它解答了你的配置文件无法解答的问题，点个星就能让使用相同技术栈的下一个人找到它。

• 分享一份 ambit share --redact 生成的图谱快照。文件中不会包含路径，--redact 会将树未提供的所有名称替换为对应类别，因此你可以展示真实配置而不透露其名称。
• 通过问题模板报告不受支持的运行时或不准确的能力模型。
• 若要收到新运行时读取器或新能力发布的通知，请选择 Watch → Custom → Releases。

---

许可证

MIT © Kanav Jain