📥 Agent Inbox

事前批准，而非事后审计。 一个面向 AI 代理的本地人工介入门控。它会阻止操作，直到你做出决定——而且超时即拒绝。

属于 Aurora Evidence Suite 的一部分——面向 AI 代理的本地优先证据工具。

为什么存在

套件中的其他工具都是回溯性的。Traceboard 回放代理做了什么；ClaimTape 检查它声称了什么；Evolution Ledger 审计它如何改变。所有这些都是事后的。

代理正被赋予越来越多的真实能力——部署、删除、花钱、以你的名义给人发消息。对于这些操作，“我们可以重建出错的过程”是不够的。Agent Inbox 是唯一一个站在操作之前的组件。

        ┌──────────────┐   request_approval    ┌─────────────┐
Agent ──│ Agent Inbox  │◀──── BLOCKS ─────────│  your call  │
        └──────┬───────┘                       └─────────────┘
               │ approved → agent proceeds
               │ denied   → agent stops
               │ timeout  → DENIED (never assumed safe)

Related MCP server: Agent File Guardian

30 秒快速入门

git clone https://github.com/Zijian-Ni/agent-inbox.git
cd agent-inbox && npm install

npx agent-inbox serve        # web UI on http://127.0.0.1:7777
npx agent-inbox pending      # or stay in the terminal

将其接入代理（MCP）：

claude mcp add agent-inbox -- npx agent-inbox-mcp

然后告诉你的代理，在其指令中：

在任何不可逆操作之前——删除数据、部署、花钱，或以用户名义发送消息——调用 request_approval 并等待。拒绝或超时意味着停止并报告；绝不意味着另寻他法。

唯一重要的规则

拒绝是默认。

超时、或遇到崩溃的界面、磁盘已满、无法解析的日志行或任何模糊状态的请求，都解析为拒绝。绝不批准。

这不是为了防御而防御。一个失败时放行的批准网关比没有网关更糟，因为它制造了有人在监视的错觉。如果此工具在运行，沉默必须意味着“不”。

经过测试验证，并通过 stdio 驱动真实的 MCP 服务器：

after a 1500ms deadline with NO human present:
  status  : expired
  approved: false
  guidance: NOT approved. Do not proceed. Report this to the user
            instead of retrying or working around it.

你得到什么

三者都读写同一个仅追加的 JSONL 文件，因此它们之间无需服务器即可保持一致：

~/.agent-inbox/approvals.jsonl     (or $AGENT_INBOX_PATH)

命令

agent-inbox pending              # what needs you
agent-inbox show <id>            # full detail, including the exact payload
agent-inbox approve <id> --reason "checked the diff"
agent-inbox deny <id>    --reason "not tonight"
agent-inbox watch                # follow new requests live
agent-inbox serve --port 7777    # web UI
agent-inbox stats                # counts + median decision time
agent-inbox verify               # has the log been tampered with?
agent-inbox compact              # collapse the log (backs up first)

值得了解的设计决策

你总是看到载荷，而不仅仅是标签。 当实际命令是其他东西时，批准“部署到生产”是对此类工具的明显攻击。CLI 和 Web 界面都在你决定之前显示确切的 detail。

日志是仅追加且经过哈希检查的。 一个决定追加一条记录；它从不重写。每条记录都携带其不可变请求字段的 SHA-256，因此 verify 能捕获批准后编辑的细节，以及从拒绝悄悄改为批准的决定。“谁批准了导致生产故障的事情”仍然可以回答。

已解决的请求不能重新决定。 重放旧的待处理记录不能重新打开你已经拒绝的事情——有一个专门针对此的测试，因为消息重放是代理场景中现实的故障模式。

仅限回环，这是设计使然。 Web 服务器绑定 127.0.0.1，主机不可配置。可从网络访问的批准控制台就是一个有友好面孔的远程代码执行面板。安全边界是“你已经在这台机器上”。

停止始终是阻力最小的方向。 高风险的批准会获得确认速度提升；拒绝从不。

诚实的局限性

• 它只门控代理选择询问的内容。 这是协作，不是沙箱。从不调用 request_approval 的代理不受门控——对于任何真正敌对的东西，请与真实的 OS/容器权限配对。

• 风险级别是代理自己的声明。 risk: "low" 意味着代理这么说了。请阅读载荷。

• 没有身份验证。 任何能访问你机器和该端口的人都可以批准。这是预期的威胁模型；不要暴露它。

• 不是团队队列。 一个人，一台机器。带身份的多用户批准是另一个产品。

隐私

无遥测、无账户、无云。MCP 服务器和 CLI 发出零网络请求。唯一的监听器是你自己启动的回环 Web 界面。

中文说明

Agent Inbox = 事前批准，而不是事后审计。

这套工具里其他几个都是回溯性的：Traceboard 回放 agent 做过什么、ClaimTape 核查它声称了什么、Evolution Ledger 审计它怎么改的自己。只有这一个站在动作之前。

agent 现在被交付越来越多的真实权限——部署、删除、花钱、以你的名义发消息。对这些动作来说，「出事后能还原过程」是不够的。

最重要的一条规则：超时 = 拒绝。

请求超时、界面崩了、磁盘满了、日志有坏行、任何状态不明的情况，一律判为拒绝，绝不放行。这不是过度防御——一个「失败时放行」的批准网关比没有网关更糟，因为它制造了「有人在看着」的错觉。

几个刻意的设计：

• 永远展示真实载荷，而不只是标签。 界面上写「部署到生产」、实际命令却是别的东西，这是这类工具最典型的攻击方式。CLI 和网页在你做决定之前都会把完整 detail 摊开给你看。

• 日志只追加，且带哈希校验。 决定是追加一条新记录，不是改写旧记录；每条都带请求字段的 SHA-256，所以「批准之后偷偷改内容」和「把拒绝悄悄改成批准」都能被 verify 抓出来。

• 已决定的请求不能被重新决定。 重放一条旧的 pending 记录，无法把你已经拒绝的事情重新打开——这条有专门的测试，因为在 agent 场景里消息重放是真实存在的故障模式。

• 只监听本机回环，且不可配置。 一个能从局域网访问的批准面板，本质上就是一个长着友好外表的远程代码执行控制台。

• 「停下」永远是阻力最小的方向。 高风险的批准要多一次确认，拒绝从来不需要。

诚实的边界：它只能拦住 agent 主动来问的事情——这是协作机制，不是沙箱；risk 等级是 agent 自己的说法，请自己读载荷；没有身份认证，所以千万不要暴露到网络上。

贡献

参见 CONTRIBUTING.md。最有价值的贡献是一种让它失败时放行的方法——如果你找到一种，那是一个安全漏洞，我想知道。

许可证

MIT © Zijian Ni