ACR — Agent Composition Records

ACR — Agent 组合记录

AI Agent 的行为注册表。 ACR 会记录 Agent 发出的每一次外部工具调用，将这些信号编译成交互档案，并展示时间花在了哪里——首先会在每次会话结束时显示一张概览卡片。

快速开始（60 秒，Claude Code）

npm i -g @tethral/acr-hook && acr-hook init

设置就这么简单。此 hook 会为你的 Agent 创建身份（无需账户，也无需管理 API 密钥），将自身接入 Claude Code 的工具 hook，并自动记录每一次工具调用。下次会话结束时，终端中会显示一张卡片：

── ACR session card ──
  142 tool calls | 4.1% of active time waiting
  Top sinks: platform:bash 38s · mcp:github 12s
  Full report: https://dashboard.acr.nfkey.ai/agents/…

随时可以用 acr-hook remove 卸载（会还原设置备份）。

ACR 是什么

ACR 是一个交互档案注册表。Agent 会记录自己的操作（工具调用、API 请求、MCP 交互）；这些信号会编译成行为档案，你可以通过视角查询——每种视角都是读取同一组底层记录的不同方式。

首个发布的是摩擦视角：按目标显示延迟和故障明细、耗时瓶颈，以及与自身历史记录的趋势对比。其他视角还包括覆盖情况、显露偏好（声明使用的组合与实际使用的组合对比）、故障、趋势和稳定性。

ACR 不是安全产品。它不会评估技能、检测入侵或阻止任何操作。它会记录事件并传递通知：如果网络在 Agent 组合中的某个组件上观察到异常信号，Agent 就会收到通知。是否重要，由你决定。

当前可用功能与随网络扩展的功能

ACR 会如实说明自身的成熟度。每种视角都会标明其处于以下三种状态之一：有真实数据、数据不足（并说明如何改变这种状态），或已降级（查询失败——显示为不可用，绝不会显示为正常的零值）。

第一天即可使用，即使只有一个 Agent：

• 通过 hook 自动记录每一次工具调用（耗时、状态、目标）
• 使用自身数据查看摩擦视角：耗时瓶颈、按目标统计的延迟和故障、会话卡片
• 与自身历史记录对比趋势（本周与上周）
• 覆盖情况：你填充了哪些信号，以及这些信号解锁了哪些视角

随网络扩展而启用（群体功能要求每个目标至少有 5 个持久 Agent——低于此数量时，视角会显示“你就是基准”，而不是虚构对比数据）：

• 群体基准（“在 api:openai.com 上比网络慢 42%”）
• 网络状态：整个 Agent 群体的系统运行状况，按最差优先排序
• 异常信号通知：你声明的某个组件在至少 20 次交互中被至少 3 个不同 Agent 报告异常 → 你会收到通知

hook 无法看到的内容（视角会如实说明，而不是显示零值）：

• 深层故障——hook 只能观察到表面错误；未到达工具结果边界的网络／超时／身份验证故障不会显示。0 failures 表示 0 visible failures。
• 重试次数、队列等待时间、调用链结构、令牌用量——只有使用这些字段调用 log_interaction 的 Agent 才会填充这些数据。仅使用 hook 的档案会将这些部分显示为 n/a，而不会显示为正常的零值。

添加 MCP 服务（可选，用于在 Agent 内查询视角）

hook 负责记录；MCP 服务让 Agent 能够读取自己的档案并记录更丰富的信号。在 Claude Code 中运行一条命令：

claude mcp add acr -s user -- npx -y @tethral/acr-mcp@latest

也可用于任何 MCP 客户端（Cursor、Continue、Claude Desktop 等）：

{
  "mcpServers": {
    "acr": {
      "command": "npx",
      "args": ["-y", "@tethral/acr-mcp@latest"]
    }
  }
}

hook 和 MCP 共用同一个身份文件——任一方都可以为另一方完成初始化。不确定从何开始？调用 orient_me。

核心 MCP 工具

工具	功能
orient_me	我在哪里，接下来该做什么 — 基于状态的路由
log_interaction	记录一次交互，支持丰富字段（retry_count、chain_id、tokens_used…）
get_friction_report	阻力视角：时间和令牌都花在哪里
summarize_my_agent	会话结束总结
get_notifications	与你的组合相关的未读异常信号通知
get_my_agent	身份、仪表板链接、注册状态

这七个工具构成了完整的默认工具集——刻意保持精简，因为每个工具架构都会占用宿主 Agent 窗口中的上下文。完整的 29 个工具集（次级视角，如 get_coverage/get_trend/get_revealed_preference/get_stable_corridors、组合管理、技能注册表、监控项、网络视图）可通过在 MCP 配置中设置一个环境变量启用：

{ "command": "npx", "args": ["-y", "@tethral/acr-mcp@latest"], "env": { "ACR_ADVANCED": "1" } }

orient_me 和 get_my_agent 会告知模型高级工具集的存在，因此没有任何内容被隐藏——只是默认不启用，以免产生开销。

添加到任意 Agent（SDK）

npm install @tethral/acr-sdk    # TypeScript/Node.js
pip install tethral-acr          # Python

import { ACRClient } from '@tethral/acr-sdk';

const acr = new ACRClient();

// Register your agent's composition
const reg = await acr.register({
  public_key: 'your-agent-key-here-min-32-chars',
  provider_class: 'anthropic',
  composition: { skill_hashes: ['hash1', 'hash2'] },
});

// Log an interaction (the foundation — every lens reads these)
await acr.logInteraction({
  target_system_id: 'mcp:github',
  category: 'tool_call',
  status: 'success',
  duration_ms: 340,
});

// Query the friction lens
const friction = await acr.getFrictionReport(reg.agent_id, { scope: 'day' });

// Check for anomaly signal notifications
const notifs = await acr.getNotifications(reg.agent_id);

异常信号通知

异常信号是跨多个互不相关的 Agent 观察到的行为模式——并非安全警报。注册时（或更新组合时），ACR 会为你订阅所声明的组件。如果网络随后观察到其中某个组件出现升高的异常信号——至少 3 个不同的报告 Agent，涉及至少 20 次交互——系统就会向你的 Agent 发送通知：

[HIGH] Component in your composition reported anomalies
   3 agents reported anomalies across 41 interactions.
   Anomaly rate: 34.1%. Review with your operator before continuing use.

此流程已在 CI 中进行端到端测试（参见 scripts/db-contract-test.mjs）：已订阅技能的种子异常报告必须生成通知，否则构建将失败。ACR 不会追踪 Agent 背后的人，因此通知会发送给 Agent，而非所有者。

技能注册表

ACR 会观察公共注册表（npm、GitHub）中已有的技能，并追踪与之相关的行为信号：采用次数、异常信号、版本历史。它不是供你安装技能的目录，也不是安全检查——它只记录网络观察到的内容。搜索结果会优先显示带有信号的技能；无法识别有效身份的目录条目会在抓取时被拒绝。

架构

Agents (Claude, OpenClaw, custom)
  |
  +--> Capture hook (@tethral/acr-hook — primary capture path)
  |      PreToolUse/PostToolUse receipts, SessionEnd card
  |
  +--> MCP Server (@tethral/acr-mcp) or SDK (@tethral/acr-sdk / tethral-acr)
  |      Lens queries, log_interaction, notifications
  |
  +--> Resolver API (Cloudflare Workers, edge-cached)
  |      Lookups, composition checks, notification feed
  |
  +--> Ingestion API (Vercel serverless)
  |      Registration, interaction receipts, lens queries, notifications
  |
  +--> CockroachDB (distributed SQL)
  |      Interaction profiles, agent registry, skill observation data
  |
  +--> Scheduled jobs (GitHub Actions -> /api/cron/*)
         system-health aggregation + chain analysis (15 min)
         skill signal computation + watch evaluation + pattern detection (30 min)
         friction baselines + data archival + agent expiration (daily)
         Every run writes a heartbeat; /health reports pipeline liveness
         separately from network activity.

数据收集

ACR 仅收集交互元数据：目标系统名称、时间信息、状态、链上下文和提供方类别。不收集请求/响应内容、API 密钥、提示词或个人身份信息。你的交互档案仅对你可见；总体基线使用持久 Agent 的聚合统计数据。

**我们收集的内容：**目标系统名称（mcp:github、api:stripe.com）、交互时间信息（持续时间、时间戳、队列等待时间、重试次数）、交互状态、Agent 提供方类别、组合哈希（SKILL.md 内容的 SHA-256）、链上下文、Agent 报告的异常标记（仅类别）。

**我们不收集的内容：**请求/响应负载、凭据、提示词或补全内容、个人身份信息、文件内容，或 Agent 背后人类的身份。

保留期限（由定时运行的 data-archival 和 agent-expiration 作业强制执行）：交互回执保留 90 天，随后归档为每日摘要；通知保留 90 天；Agent 注册在闲置 90 天后软过期；技能观察数据在技能仍被观察期间保留。

**第三方共享：**无。**联系方式：**[email protected] · 完整条款

测试框架

node scripts/test-agent-lifecycle.mjs   # full agent lifecycle against the live API
node scripts/e2e-smoke.mjs              # do -> read-back loop through the default lens (runs in CI on schedule)
node scripts/db-contract-test.mjs       # every migration, cron, and lens against a real CockroachDB (runs in PR CI)

db-contract 测试框架之所以存在，是因为单元测试会模拟数据库，而生产环境运行的是 CockroachDB——方言差异曾导致同一个视角查询连续三次出错，之后才添加了该框架。每个视角路由都必须返回 200、状态非降级，且计数与种子数据一致；通知承诺则通过端到端断言进行验证。

开发

pnpm install                    # Install dependencies
pnpm build                      # Build all packages
pnpm test:unit                  # Run unit tests
node scripts/run-migration.mjs up      # Run DB migrations

**发布规则：**更改 packages/mcp-server、packages/acr-hook 或 SDK 时，必须提升版本号（PR CI 会强制检查），合并到 master 后会自动发布所有版本号已提升的包。已合并却从未发布到 npm 的修复，就等于从未发生。

**可选：开发此仓库时试用 ACR。**将 .mcp.json.example 复制为 .mcp.json，任何打开此目录且支持 MCP 的客户端都会加载已发布的 @tethral/acr-mcp。此功能默认选择加入：.mcp.json 已加入 gitignore，因此不会在不知情的情况下将贡献者纳入其中。要测试本地 MCP 更改，请在运行 pnpm build 后，将 command 指向 node，并将 args 指向 ./packages/mcp-server/dist/cli/stdio.js。

许可证

MIT

链接

• API：https://acr.nfkey.ai
• npm（钩子）： @tethral/acr-hook
• npm（MCP）：@tethral/acr-mcp
• npm（SDK）：@tethral/acr-sdk
• PyPI：tethral-acr