agent-registry

Agent Registry 是专为 Claude Code 设计的 Agent 懒加载管理系统，旨在解决多 Agent 场景下的上下文窗口爆炸问题。该系统通过按需加载机制，可将 Token 开销降低约 95%，显著提升大项目的处理效率。

核心用法遵循"搜索-获取-执行"三步模式：首先通过 search_agents.py 基于意图关键词发现匹配的 Agent；随后使用 get_agent.py 加载选定 Agent 的完整指令；最后执行具体任务。初次使用需运行 install.sh 完成安装，并通过 init_registry.py 将现有 Agent 从 ~/.claude/agents/ 迁移至注册表。系统支持交互式选择界面（基于 questionary 库），可直观查看各 Agent 的 Token 占用估算（🟢<1k 🟡1-3k 🔴>3k），并支持分页浏览（300+ Agent 场景）。

显著优点在于其革命性的懒加载架构。传统方式会预加载所有 Agent 导致上下文膨胀，而 Registry 仅在需要时加载特定 Agent，极大缓解了 "~16k tokens" 警告问题。交互式迁移工具提供平滑过渡体验，自动构建搜索索引并保留原始文件结构。Python 脚本具备良好的错误处理机制，即使缺少依赖也能降级运行。

潜在局限包括：首先，该项目来自 T3 级别来源（个人开发者 @MaTriXy），虽经安全审查但生态持续性存在不确定性。其次，系统引入额外复杂度，对于仅使用 2-3 个 Agent 的轻量用户，安装和维护成本可能超过收益。此外，功能强依赖 Python 3.7+ 环境，且仅适用于 Claude Code 生态，无法迁移至其他 AI 助手平台。

适合群体主要为重度 Claude Code 用户，特别是管理 10 个以上专业 Agent 的开发者、架构师或团队 Lead。对于频繁切换不同领域 Agent（如安全审计、代码审查、文档生成）的复杂工作流场景，该系统能有效维持上下文清爽。同时适合关注 Token 成本的企业级用户。

使用风险主要包括：文件系统操作风险（install.sh 和迁移脚本会移动文件、修改 ~/.claude/ 目录结构，建议操作前备份）；依赖安装风险（自动安装 questionary 包，虽为可信库但涉及 PyPI 下载）；MD5 哈希算法仅用于内容去重而非安全校验；以及 T3 来源的长期维护风险。建议在生产环境使用前审查 install.sh 内容，并在隔离环境测试迁移流程。