AgenticResourceRegistry/AgenticResourceRegistry · 上手攻略

  • 仓库：AgenticResourceRegistry/AgenticResourceRegistry
  • 链接：https://github.com/AgenticResourceRegistry/AgenticResourceRegistry
  • 分类：agent（agent 基础设施 / 团队资源注册中心）
  • 作者：spark
  • 更新：2026-10-30

是什么

Agentic Resource Registry（下文简称 ARR，前身叫 Observal）是一个自托管的团队级 coding agent 资源注册中心。它把散落在各个 git 仓库里、缺乏文档、彼此看不见的 Skills、MCP client、Agent 文件、hooks、prompts 和 sandbox 收拢到一个平台里，让团队成员能搜索、评审、安装和复用这些资源。

架构上分两半：

  • 服务端（你自托管）：API + Web UI + 数据库，走 Docker Compose（10 个服务）或 Kubernetes（Helm）
  • CLI（装在每个开发者的机器上）：叫 observal，负责登录、检测本机的 harness（Claude Code / Cursor / Kiro / Codex / Pi / OpenCode / Copilot 等）、安装遥测 hooks、捕获会话

CLI 的名字目前仍是 observal（旧的 Observal / Observal 链接会重定向到新仓库），但配置文件、文档站（docs.observal.io）和命令前缀都保留 observal 这套词。

项目采用 Apache-2.0 许可（企业友好），技术栈是：前端 Vite 8 + React 19 + TanStack Router + Tailwind CSS 4 + shadcn/ui；后端 Python 3.11+ / FastAPI / Strawberry GraphQL；数据 PostgreSQL 16（注册表）+ ClickHouse（遥测）；队列 Redis + arq；CLI 用 Python / Typer / Rich。

解决什么问题

README 把问题拆成两条，说得很直白：

第一条：缺少发现层（Lack of a discoverability layer）。 几乎每家技术团队都在内部造 Skills、Agent 文件、MCP client，但存在方式就是一堆沉默的 git 仓库，几乎没文档。同事找不到已有的资源，于是同一个东西被不同的人反复造了好几遍。

第二条：缺少反馈闭环（Missing feedback loop）。 MCP client、Skill、Agent 文件的作者发出去之后基本就失去可见度——没人知道它们实际被怎么用。而且 coding agent 的失败没有静态错误码：它会幻觉，或者给出细微但错误的答案，使用者根本不知道哪里出了问题，反馈问题因此被放大。

ARR 的解法是把这两层补上：

  • 集中化：Skills、MCP clients、hooks、prompts、agent files、sandboxes 全部进一个注册表
  • 治理化：管理员评审提交、批准内部 agent、查看版本 diff，给开发者一个"唯一可信的安装来源"
  • 多 harness 渲染：为每个 IDE / CLI 自动生成正确的配置文件，不用为每个 harness 维护一份单独的安装说明
  • Agent 互调：每个通过审批的资源都以开源 ARD（Agentic Resource Discovery） 标准发布，运行中的 agent 可以把任务交给另一个已批准的 agent（无论它来自注册表还是远端 A2A 服务）
  • 用真实数据反哺：基于真实采纳和会话数据，找出哪些 agent / 工具 / prompt 真的在帮团队
  • 会话回放：用 trace 作为调试、评审、审计的证据

快速安装

前置要求（来自 SETUP.md）：

要求 最低 备注
Docker Engine 24.0+，带 Compose v2 用 docker compose 而非 docker-compose
Python 3.11+ 只在用 Python 装 CLI 或跑测试时需要
uv 最新 推荐用于 CLI 开发安装
RAM 4 GB+ ClickHouse 是内存大户，建议 6 GB
磁盘 5 GB+ 镜像和数据卷

方式一：一行命令装服务端（生产/自托管推荐）

需要 Docker Engine ≥ 24.0 且带 Compose v2：

curl -fsSL https://raw.githubusercontent.com/AgenticResourceRegistry/AgenticResourceRegistry/main/install-server.sh | bash

这条命令会下载 Docker Compose 包、生成 operator 所有的密钥文件（限定容器组访问权限）、默认把发布端口绑定到 loopback、从 GHCR 拉镜像并启动整套栈。有终端时会走引导式配置，没有终端时自动套用安全默认值（方便 CI 和 coding agent）。

方式二：从源码起（贡献者）

git clone https://github.com/AgenticResourceRegistry/AgenticResourceRegistry.git
cd AgenticResourceRegistry
cp .env.example .env
make up

.env.example 自带可用默认值，本地开发不用改。第一次构建要拉镜像并编译 Vite 前端，预期 3–5 分钟；之后启动 30 秒内完成。也可以不用 make：

docker compose -f docker/docker-compose.yml up --build -d

方式三：独立二进制装 CLI（不需要 Python）

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/AgenticResourceRegistry/AgenticResourceRegistry/main/install.sh | bash

# Windows (PowerShell)
irm https://raw.githubusercontent.com/AgenticResourceRegistry/AgenticResourceRegistry/main/install.ps1 | iex

方式四：Python 装 CLI

uv tool install observal-cli
# 或
pipx install observal-cli

observal --version

装完后连上服务器并初始化

observal auth login
observal doctor --patch

observal auth login 会提示：服务器 URL（直接回车用 http://localhost）→ 登录方式（选 [E]mail）→ 邮箱密码。新服务器上会预置 demo 账号：

角色 邮箱 密码
Super Admin super@demo.example super-changeme
Admin admin@demo.example admin-changeme
Reviewer reviewer@demo.example reviewer-changeme
User user@demo.example user-changeme

验证：

observal auth whoami
# super@demo.example (super_admin)

observal auth status
# Server:  http://localhost - OK
# Auth:    super@demo.example (super_admin)
# Buffer:  0 pending events

健康检查：

curl http://localhost/health
# {"status":"ok","initialized":true}

核心用法

一、在 harness 里驱动

登录后在 Claude Code / Cursor / Kiro 等里输入 /observal，它就接管了：

/observal pull security-auditor     # 拉取一个已批准的 agent
/observal scan                      # 扫描本机 harness 现状
/observal doctor                    # 诊断配置是否正确

也可以直接跟 agent 说需求，让它自己判断该用哪些命令。

二、给 harness 装遥测 hooks

observal scan                              # 只读，看装了什么
observal doctor patch --all-harnesses      # 安装会话遥测 hooks
observal doctor                            # 验证是否接线正确

scan 绝不修改文件；doctor patch 只管理会话遥测 hooks，不会动你的 MCP 命令。装上之后自动开始捕获会话。

三、注册表浏览与提交

浏览时可按 teamspace、发布者、分类或 harness 搜索，每张卡片显示它支持哪些 harness 以及被拉取次数（pull count）。构建 agent 文件分四步（identity / behavior / components / review），带实时摘要和草稿就绪度检查。组件库有五个页签：MCP servers、skills、hooks、prompts、sandboxes。

Fork 语义：把一个 agent 或组件 fork 进你个人命名空间或有资格的 teamspace，源保持不变；agent fork 保留固定的组件引用而不是拷贝组件。审阅者可以用 "Diff vs upstream" 对比草稿与已批准的基线。

四、ARD：一次搜索覆盖所有已批准资源

ARR 实现了 Agentic Resource Discovery 规范 v0.91。每个已批准的 agent、MCP server、skill、hook、prompt、sandbox 都会发布为一个 ARD 条目，带永久的 urn:air: 标识符，公开 manifest 在 /.well-known/ard.json，搜索 API 在 /api/v1/ard/search。结果只按相关性排序；审批状态、可见性、harness 支持、能否立即使用是分开的独立字段。团队私有的 agent 只有该团队能搜到。

五、A2A：agent 之间交接任务

ARR 支持 Agent2Agent 协议 v1.0（兼容 v0.3）。每次委派都是一个 A2A Task：

  • 注册表内的 agent：在支持 headless 的 harness 里跑（Claude Code、Kiro、Cursor、Codex、OpenCode、Copilot CLI、Antigravity、Pi），跑在你仓库的一份一次性副本里。返回答案 + 文件改动的 patch，永远不会自动给你应用。
  • 远端 A2A agent（别的团队用任意框架跑的服务）：按 Agent Card URL 注册，像其他提交一样走评审，然后直接调用。ARR 从不代理流量，也不存它们的凭据。

每个被拉取的 agent 都自带一个 observal-agents MCP server，四个工具：find_agents、delegate、get_task、cancel_task，不用额外告诉 agent 怎么用。委派有明确限制：只限已批准的 agent，最多两级嵌套，被委派的 agent 最多自己起 3 个任务，拒绝环路。每次委派都记在调用方 session 上，trace 里能看到 session 依赖了哪些 agent。

六、命令行直接委派

# 找出能接活的 agent
observal delegate find "review this branch for auth bugs"

# 直接指定一个
observal delegate run acme/security-reviewer "Review src/auth on this branch for token leaks"

# 远端 A2A agent 注册 / 查看 / 审批
observal registry a2a submit https://agents.acme.com --visibility team --team platform
observal discover inspect urn:air:agents.acme.com:a2a:incident-triage   # 看 card 的 Digest
observal registry a2a review urn:air:agents.acme.com:a2a:incident-triage --approve --digest sha256:...

# 注册表 agent 返回的 patch——只在你同意时才应用
git apply ~/.observal/delegations/<task-id>/changes.patch

七、洞察报告与会话回放

AI 驱动的洞察报告分析跨所有会话的使用模式——什么在起作用、什么在拖后腿、快速改进点在哪。基于 LiteLLM，任何 provider 都行（Anthropic、OpenAI、Bedrock、Gemini、Azure、Ollama），配置见 docs/insights-setup.md。

会话总览含 token 计数、模型、工具和逐轮时间线；每一轮都捕获：用户 prompt、tool call、thinking block、assistant 回复；可以下钻到任意 span 看确切的 tool 输入输出。

八、评审与审计

作者提交 agent 和组件版本；参与者可以检视已脱敏的文件和 diff、在会话里讨论、提交批准或变更请求。发布和审批是两件事：评审策略和必需检查都满足后，审阅者可以手动发布，也可以让策略自动发布。

Apache-2.0 分发里已包含：审计日志（过滤语法 actor: / action: / outcome: / sensitivity:，支持 CSV 导出）、SAML SSO、SCIM provisioning、管理看板。

九、日常运维

make down       # 停所有服务
make rebuild    # 重建镜像并重启
make logs       # tail 所有服务日志
make lint       # ruff check
make format     # ruff format + fix
make check      # 对所有文件跑 pre-commit
make hooks      # 装 pre-commit hooks
make test       # 快速测试
make test-v     # 详细输出

# 重启单个服务
docker compose -f docker/docker-compose.yml restart observal-api

# 危险：清空所有数据
docker compose -f docker/docker-compose.yml down -v

测试全部 mock 外部服务，不需要 Docker 或真实数据库：

cd observal-server && uv run --with pytest --with pytest-asyncio --with pyyaml \
  pytest ../tests/ tests/ ../observal_cli/tests/ -q

端口冲突时每个 host 端口都能用环境变量覆盖：

API_HOST_PORT=8001 WEB_HOST_PORT=3001 \
  docker compose -f docker/docker-compose.yml up --build -d

端口默认值：API_HOST_PORT 8000、WEB_HOST_PORT 3000、POSTGRES_HOST_PORT 5432、CLICKHOUSE_HOST_PORT 8123、REDIS_HOST_PORT 6379、PROMETHEUS_HOST_PORT 9090、GRAFANA_HOST_PORT 3001。

十、贡献者流程

Fork and clone → make hooks 装 pre-commit hooks → 建 feature 分支 → make lint 和 make test → 开 PR。AGENTS.md 里有给 coding agent 看的内部代码库上下文。

十一、诊断

observal doctor support              # 生成脱敏的诊断包
observal doctor support inspect observal-support-*.tar.gz   # 分享前先自己看一遍
observal ops logs                    # 流式看 dev 日志

开发日志基于 loguru（内部代号 "optic"），写在 ~/.observal/logs/dev.log，含每个请求、后台任务、遥测事件的结构化上下文。

典型适用场景

  • 20 人以上、多 harness 混用的团队：有人用 Claude Code、有人用 Cursor、有人用 Codex，想让内部 Skill / MCP client 有唯一可信来源
  • 内部 MCP client 发出去就石沉大海：需要采纳数据和会话 trace 来判断哪个有用、哪个在拖后腿
  • 有合规审计要求的组织：审计日志、SAML SSO、SCIM 供给、trace 回放、版本 diff 审批链都在 Apache-2.0 分发里
  • 想搭 agent 间协作：A2A 委派 + ARD 发现，让主 agent 把子任务交给专门 agent
  • 多模态/音视频场景的雏形应用：sandbox 组件和 A2A 机制可复用

坑与注意

  1. 资源太多，需要一台服务器扛住。10 个服务 + PostgreSQL 16 + ClickHouse + Redis + Prometheus + Grafana。ClickHouse 是内存大户，官方建议 4 GB 起步、6 GB 舒适。个人笔记本上跑起来会很重，团队生产部署建议看 docs/self-hosting/production-deploy.md。
  2. Docker Compose 版本必须是 v2。docker-compose（带连字符的老版）不行。而且 Homebrew 装的 Docker 经常版本过旧，要用 Docker Desktop 或发行版上游包。
  3. 默认端口绑 loopback——这是好设计但会让你以为是"服务没起来"。从别的机器访问需要显式改绑定。
  4. demo 账号是公开在 README 里的。super-changeme 这类默认凭据在上生产前必须换掉：改 SECRET_KEY、POSTGRES_PASSWORD、CLICKHOUSE_PASSWORD，并unset 所有 DEMO_* 变量。服务器包安装脚本会自动生成这些凭据文件，但从源码起的话得自己动手。
  5. .env 只存 NAME_FILE 路径，实际密钥在 secrets/ 目录下的受限文件里（这是服务器包安装的布局），轮换规则见 docs/self-hosting/configuration.md#secret-files。
  6. 升级前先备份。有专门的 docs/self-hosting/backup-and-restore.md，别直接 pull 最新镜像就上生产。
  7. A2A 委派不会自动应用你的代码改动。注册表 agent 返回的是 patch，必须你手动 git apply。这是刻意设计，但第一次用很容易以为"改完没生效"。
  8. 委派限制要记住：最多两级嵌套、被委派 agent 最多起 3 个自己的任务、拒绝环路。想设计深度递归的 agent 编排会撞墙。
  9. 远端 A2A agent 的信任边界：ARR 不代理流量也不存凭据，意味着安全性完全取决于你批准的 Agent Card。审批时务必核对 --digest sha256:...，digest 对不上就别批。
  10. ARD 搜索结果只按相关性排序，不代表可用性。审批状态、可见性、harness 支持、"现在能不能用"是分开的字段——搜索命中不等于能装。
  11. 会话遥测的隐私边界：项目会捕获用户 prompt、tool call 输入输出、thinking block、assistant 回复。这意味着你的代码和 prompt 会进入 ClickHouse。虽然遥测走的是本地先缓冲再 push 的模式，但部署前应确认这符合你团队的数据合规要求。README 未在显著位置标注数据保留期，保留策略在 docs/self-hosting/databases.md。
  12. 审计日志的脱敏：评审时参与者看到的是"已脱敏的文件"，diff 也是脱敏版。需要看完整内容的话流程不同。
  13. observal doctor support 生成的诊断包分享前要自己看。官方也是这个建议（inspect 子命令就是干这个的）。
  14. CLI 改名处于过渡期。包名还是 observal-cli，命令前缀还是 observal，文档站还是 docs.observal.io，Discord 链接还是 discord.observal.io，但仓库名和 README 主标题已经换成 Agentic Resource Registry。搜索资料时两种名字都要试。
  15. CLI 认证走浏览器/终端交互，在纯 CI 环境里可能需要 observal auth login 的非交互替代路径——README 未给出 CI 专用的 token 流程说明，实际接入时需查 docs/getting-started/onboarding.md。

与同类对比

方案 定位 差异
ARR 团队级 agent 资源注册表 + 遥测 + 评审 + A2A 自托管、Apache-2.0、把"发现层"和"反馈闭环"一起做；ARD 开放标准
GitHub Marketplace / 私有 MCP registry 社区级分发 偏公域分发，不解决内部资源无文档和反馈闭环的问题
团队自建 wiki + Confluence 文档型发现 只有文档没有版本、审批、安装命令生成，也拿不到使用数据
MCP 官方 registry 生态 MCP server 单点发现 只覆盖 MCP server，不覆盖 Skills / Agent 文件 / hooks / prompts / sandbox，也没有会话 trace
LangSmith / Langfuse 等 LLM 可观测平台 通用 LLM 追踪 追踪维度更通用，但没有资源注册、审批治理、ARD 发现和 A2A 委派
纯 prompt/agent 目录（如 awesome-list 类） 轻量发现 没有安装命令生成、没有版本 diff、没有审批、没有使用数据回流

ARR 的独特之处在于把"资源发现"和"使用反馈"绑成一个闭环，并且顺手实现了 ARD 开放发现标准和 A2A 委派——这两件事都让它比单纯的内部目录工具更重，但也更有延展性。

一句话推荐结论

如果你有一个 20 人以上、同时用 Claude Code / Cursor / Codex / Kiro 的团队，正被"内部 Skill 找不着、同一个 MCP 被重复造、agent 发出去没人用"这三件事困扰，ARR 是目前少见的把这三件事用一个自托管 Apache-2.0 平台一次解决的方案，值得上生产试；但个人用户或 3 人小团队请直接跳过——为了装个 agent 拉起 10 个容器和 ClickHouse 明显过重。

⚠️ 核验说明：本文基于 2026-10-30 抓取的仓库 README 与 SETUP.md。ARD 规范版本 v0.91、A2A v1.0（兼容 v0.3）、demo 账号凭据、10 个服务的端口与用途、install-server.sh / install.sh / install.ps1 三个安装脚本路径、"提交者 fork 保留固定组件引用"、"委派两级 / 3 任务上限"、"默认绑 loopback"等均逐条取自 README 与 SETUP.md 原文。前端 Vite 8 / React 19 / Tailwind CSS 4、Python 3.11+ / FastAPI / Strawberry GraphQL、PostgreSQL 16 + ClickHouse、Redis + arq 的技术栈表来自 README。遥测捕获内容范围（prompt / tool call / thinking block / 回复）来自 README 的会话截图说明文字。遥测数据保留期、以及 CI 环境下 observal auth login 的非交互替代路径，本文未能从已抓取页面确认，留待查 docs/self-hosting/databases.md 与 docs/getting-started/onboarding.md。