用 Agentic Resource Registry 自建团队级 Agent 资源注册表：Docker 起栈、CLI 接入与跨工具委托实操

编码 Agent 用久了会出现一种典型的浪费：张三写了一套内部技能，李四不知道，又写了一套差不多的；某个 MCP 服务配错了参数，没人报错，只是 Agent 开始给出微妙错误的答案，使用者根本无从判断问题出在哪。Agentic Resource Registry（原名 Observal）针对的就是这两件事——它提供一个集中的发现层，把技能、MCP 客户端、hooks、提示词、Agent 文件与沙箱这些资源收进来做治理；同时用真实会话数据形成反馈回路，让「静默失败」变成可操作的信号。它是自托管的，采用 Apache-2.0 许可，已支持 Claude Code、Codex、Cursor、GitHub Copilot、Kiro、Pi、OpenCode、Antigravity CLI 与 Goose 等宿主。本教程六步落地：把服务端跑起来、装 CLI 并接上宿主、在宿主里用注册表命令、理解跨 Agent 委托的边界、发布资源并让它们可被发现、最后把运维与隐私的收尾做完。

🗂️ 本教程适合：团队里已经有多个编码 Agent、资源散落在各仓库、需要统一发现与治理的工程负责人。前置条件是一台能跑 Docker 的机器（服务端一键安装要求 Docker Engine 不低于 24.0 且带 Compose v2），以及一个受支持的编码 Agent。CLI 有独立二进制（不需要 Python）与 Python 3.11 以上两种装法，按你的环境选一种即可。注意它曾用名 Observal：代码、维护者与许可都没变，命令行仍然叫 observal，旧链接会跳转。

Step 1：起服务端：一键脚本，或克隆源码自己起栈

1 服务端是十来个容器的一套栈

整个系统分两部分：自托管的服务端（API 加网页界面加数据库）与装在每个开发者机器上的 CLI。服务端的一键安装脚本会拉取 Docker Compose 包、生成只有运维者可读的密钥文件、从容器镜像仓库取镜像并启动整套栈。有终端时它跑引导式安装，没有终端时自动套用安全默认值。想从源码跑就克隆仓库、复制环境变量模板后启动。

# 一键安装服务端（需要 Docker Engine ≥ 24.0 且带 Compose v2）
curl -fsSL https://raw.githubusercontent.com/AgenticResourceRegistry/AgenticResourceRegistry/main/install-server.sh | bash

# 或者从源码启动（面向贡献者与想改代码的人）
git clone https://github.com/AgenticResourceRegistry/AgenticResourceRegistry.git && cd AgenticResourceRegistry
cp .env.example .env
make up

# 栈里有什么
#   PostgreSQL 16   —— 注册表数据
#   ClickHouse      —— 遥测数据
#   Redis + arq     —— 队列
#   共约 10 个服务；支持 Docker Compose 与 Kubernetes（Helm）两种部署形态

安装脚本默认把对外端口绑在回环地址上，也就是说装完只在本机可达。这在单机试用时很省心，但团队要用就必须自己加反向代理与鉴权——它不会替你决定谁能访问。

自托管意味着运维责任在你：升级、回滚、备份与数据保留策略都要自己排。官方文档里专门有升级、备份与恢复、以及发布校验（核对校验和、出处与签名标签）几节，别等出问题再看。把「升级前先备份」写进你的运维手册。

Step 2：装 CLI 并接上宿主：两条安装路，一条接入命令

2 接完之后它开始自动捕获会话

CLI 有两条装法：不想碰 Python 就用独立二进制脚本，习惯 Python 工具链就用 uv 或 pipx 装 PyPI 上的 observal-cli（注意包名带后缀，装完的命令叫 observal）。装好之后跑登录与诊断修补两条命令：它们会与服务端完成认证、检测你机器上有哪些宿主、装上遥测钩子，并开始自动捕获会话，同时为 Agent 的安装与注册表命令做好准备。

# 独立二进制（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（3.11 及以上）
uv tool install observal-cli
# pipx install observal-cli

# 接入：认证 + 检测宿主 + 装钩子
observal auth login
observal doctor --patch

# 支持的宿主
#   Claude Code、Codex、Cursor、GitHub Copilot、Kiro、Pi、OpenCode、Antigravity CLI、Goose

诊断命令带修补参数这一步别省：它会按检测到的宿主把配置文件一次装好。手工复制配置容易出现「装了一半」的情况，症状是命令能跑但会话捕获不到。

💡 先在一台机器上跑通再铺开：确认诊断命令的输出里列出了你实际在用的宿主，并且捕获到了会话，再给团队发装机说明。批量装机时把遥测默认行为一并写清楚。

Step 3：在宿主里使用：一条斜杠命令接管注册表操作

3 拉取、扫描、诊断都在对话里完成

登录之后，在你的编码 Agent 里输入 /observal，它会接管后续的注册表操作：拉取某个 Agent、提交资源、浏览注册表、跑诊断。命令行示例里有三个最常用：拉取一个安全审计 Agent、扫描当前项目、跑一次诊断。更实际的用法是直接用自然语言告诉 Agent 你要什么，它自己选命令。

# 在编码 Agent 里
/observal pull security-auditor   # 拉取一个已批准的 Agent
/observal scan                    # 扫描当前项目
/observal doctor                  # 跑诊断

# 拉取进来的 Agent 会自动带上一个 MCP 服务：observal-agents
#   可用工具共四个
#     find_agents   找可用的 Agent
#     delegate      把任务交给它
#     get_task      查看任务状态
#     cancel_task   取消任务

这套设计的关键在于：你把 Agent 拉进某个宿主时，它会自动生成那个宿主能识别的配置，不需要你手改 JSON。同一份资源在不同宿主里落地形态不同，这一步替你抹平了差异。

拉进来的脚本会以你 Agent 的权限运行：从注册表拉取的不只是说明文本，往往还带着脚本与 hooks。它们之后在你机器上执行时，权限等同于你给编码 Agent 的权限。新资源先在一次性项目里试跑，确认行为后再进正式仓库。

Step 4：跨 Agent 委托：拿到的是补丁，落地由你决定

4 它不替你合并

委托是这个注册表最有意思的部分：你可以让另一个已批准的 Agent 帮你干活，比如审一个分支上的鉴权问题。命令行提供查找与执行两条，执行时指定目标 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"

# 改动以补丁形式返回，且从不自动应用 —— 同意了才落盘
git apply ~/.observal/delegations/<task-id>/changes.patch

委托有几条明确的边界：只能委托给已批准的 Agent；委托链最多两层；被委托的 Agent 最多自己再发起三个任务；循环委托会被拒绝。这些限制是在防止一条指令把整支 Agent 队伍点燃。

补丁来自另一个模型，不等于它是对的：git apply 之前先 git apply --check 看能不能干净落地，再用你自己的方式审一遍改动内容。安全审计类任务尤其如此——它能提示线索，不能替你担责。另外远程 A2A 服务是注册后直接调用的，注册表不代理流量也不保存其凭据，这一点对你的数据出境判断很重要。

Step 5：发布与发现：四步造一个 Agent，用永久标识符被找到

5 批准过的资源才会进入发现层

资源类型有五类：MCP 服务、技能、hooks、提示词、沙箱；Agent 文件则用四步构建——身份、行为、组件、评审，过程中有实时的草稿就绪检查。提交后由管理员审核，版本差异可比对，这让「谁改了什么」始终可追溯。也可以把别人的资源叉到自己命名空间里改，叉出来的草稿保留固定的组件引用而不是复制一份组件，评审者能直接比对它和上游的差异。

# 发现层基于开放标准 ARD（Agentic Resource Discovery，当前实现 v0.91）
# 每个已批准的 Agent / MCP / 技能 / hook / 提示词 / 沙箱都会发布为一个条目
#   永久标识符：urn:air:（例如 urn:air:agents.acme.com:a2a:incident-triage）
#   公开清单：/.well-known/ard.json
#   搜索接口：/api/v1/ard/search

# 命令行核对某个条目的摘要（Digest）
observal discover inspect urn:air:agents.acme.com:a2a:incident-triage

# 远程 A2A 服务：提交 → 审核 → 调用
observal registry a2a submit https://agents.acme.com --visibility team --team platform
observal registry a2a review urn:air:agents.acme.com:a2a:incident-triage --approve --digest sha256:...

# 叉一个资源到自己命名空间（组件是引用，不是复制）
POST /api/v1/agents/{id}/fork
GET  /api/v1/agents/{id}/fork-diff?version=…

搜索接口有一个容易误解的地方：结果只按相关性排序。批准状态、可见性、支持哪些宿主、以及现在到底能不能用，都是独立的字段。也就是说搜出来的排在前面不代表它已经被批准——把它当成候选列表，不是白名单。

💡 团队私有资源只对该团队可见，这一点与注册表本身的可见性规则一致。想让外部也能发现的，要在提交时把可见性显式放开，别指望默认行为。

Step 6：运维与隐私：日志、支持包与发布校验

6 排错与共享都要留一手

日常排错用日志流命令，日志写在用户目录下的固定路径。需要对外求助时，诊断命令可以生成一份脱敏归档，但在把它发出去之前还有一条专用命令可以让你先检查归档内容。发布版本则建议走官方的发布校验流程，核对校验和、出处与签名标签。

# 流式看日志（日志文件在 ~/.observal/logs/dev.log）
observal ops logs

# 生成脱敏诊断归档
observal doctor support bundle

# 共享前先自己看一遍里面有什么
observal doctor support inspect observal-support-*.tar.gz

# 升级前：先备份，再按官方升级与安全回滚流程走
# 发布校验：核对校验和、出处与签名标签（docs/security/release-verification.md）

还有一个预期要摆正：它解决的「反馈回路」问题，本质是把编码 Agent 那种不报错、只是给出微妙错误答案的失败变成可观测信号。它能告诉你资源被怎么用、在哪一步出问题，但不能替代你对结果的判断。

脱敏不等于可以随便发：支持包虽然经过脱敏处理，官方仍提示共享前人工审查。里面有路径、宿主信息、会话痕迹，企业环境里可能还有内部域名或仓库名。发出去之前用 inspect 命令过一遍，是成本很低的一步。同时注意遥测数据落到 ClickHouse，保留策略要按你们的数据合规要求配置。

💡 先在非关键项目上跑两轮，把「会话捕获到了、报告能看懂、委托补丁能落地」这三件事验证完，再推广到整个团队。推广顺序反过来会消耗掉大家的耐心。

常见问题速查

现象	原因与处理
一键脚本装不上	检查 Docker Engine 是否不低于 24.0 且带 Compose v2
装完只有本机能访问	默认端口绑回环地址；团队访问要自己加反向代理与鉴权
命令装了但用不了	Python 装的包名是 observal-cli，命令名是 observal
会话捕获不到	跑 observal doctor --patch，确认输出里列出了你在用的宿主
/observal 没反应	先 observal auth login 完成认证，再在宿主里用
委托结果没生效	改动以补丁返回且不自动应用，需自己 git apply
委托链太长被拒	最多两层；被委托方最多自起三个任务；循环委托被拒绝
搜索结果不可用	搜索只按相关性排序，批准状态与可见性是独立字段
团队私有资源能被外人搜到吗	不能，可见性规则与注册表一致
远程 A2A 服务的凭据谁保管	注册表不代理流量也不保存其凭据
支持包能直接发吗	已脱敏但仍建议用 inspect 命令先人工过一遍
日志在哪	~/.observal/logs/dev.log，用 observal ops logs 流式看
升级怕出问题	先备份，走官方升级与回滚流程，并按发布校验核对签名
与旧名 Observal 什么关系	同一代码、同一维护者、同为 Apache-2.0，旧链接会跳转

← 返回教程中心