内容
# HOL 注册中心 Codex 插件
|  | Codex 插件，用于 [HOL 注册中心](https://hol.org/registry)。此存储库添加了一个 Codex 面向的 MCP 服务器和技能，使 Codex 能够询问代理是否委托、检查候选人、召唤选定的代理以及在稍后恢复代理会话。<br><br>对于更广泛的公共注册中心代理技能和 CLI，请使用 [hashgraph-online/registry-broker-skills](https://github.com/hashgraph-online/registry-broker-skills) 和 [`@hol-org/registry`](https://www.npmjs.com/package/@hol-org/registry)。 |
| :--- | :--- |
[](https://github.com/hashgraph-online/registry-broker-codex-plugin/actions/workflows/ci.yml)
[](./LICENSE)
[](https://hol.org/registry)
[![Registry Broker plugin trust badge][trust-badge-img]][trust-badge-link]
[](https://github.com/hashgraph-online/registry-broker-codex-plugin/issues)
[](https://github.com/hashgraph-online/registry-broker-codex-plugin/commits/main)
[](./package.json)
[](./package.json)
[](./package.json)
[](./package.json)
[](./package.json)
[](./.codex-plugin/plugin.json)
[](./.mcp.json)
[](https://codesandbox.io/p/github/hashgraph-online/registry-broker-codex-plugin/main?import=true)
[](https://stackblitz.com/github/hashgraph-online/registry-broker-codex-plugin)
HOL 插件配置文件：[hol.org/registry/plugins/hol%2Fregistry-broker-codex-plugin](https://hol.org/registry/plugins/hol%2Fregistry-broker-codex-plugin)
## 概述
此存储库在 Codex 中公开了四个面向用户的代理工具：
- `registryBroker.delegate`：询问代理任务是否应被委托、审查为候选列表或本地处理。
- `registryBroker.findAgents`：检查代理推荐的候选列表。
- `registryBroker.summonAgent`：向代理选定的代理或已知的 UAID 发送子任务，或使用 `dryRun` 预览确切的分派。
- `registryBroker.sessionHistory`：为以前的会话恢复代理对话，并附有简洁的最新状态摘要。
代理返回三种推荐状态之一：
- `delegate-now`
- `review-shortlist`
- `handle-locally`
Codex 可以使用该推荐来决定是否立即委托、首先显示候选人或保持工作本地。
## 何时使用此插件
当 Codex 任务可以受益于代理选定的外部专家时，请使用此插件，例如：
- 错误修复和验证
- 实现审查
- 研究和竞争分析
- 商业计划或 GTM 工作
- 着陆页、引导或 UX 探索
- 启动消息和生命周期复制
如果您只需要公共注册中心代理技能或 CLI 在 Codex 之外，请使用：
- [hashgraph-online/registry-broker-skills](https://github.com/hashgraph-online/registry-broker-skills)
- [`@hol-org/registry`](https://www.npmjs.com/package/@hol-org/registry)
## 安装
要求：
- Node `>=20`
- pnpm `>=10`
从存储库根目录：
```bash
pnpm install
pnpm run build
```
打包的 MCP 服务器入口点是：
```json
{
"mcpServers": {
"registryBroker": {
"command": "node",
"args": ["./dist/cli.cjs", "up", "--transport", "stdio"]
}
}
}
```
公共 HOL 注册中心代理 API 基本 URL 是 `https://hol.org/registry/api/v1`。
## 配置
支持的公共配置：
- `REGISTRY_BROKER_API_KEY`
可选。如果您的代理部署需要 API 密钥，则启用身份验证的代理聊天流程。
- `MCP_SERVER_NAME`
可选。覆盖 MCP 服务器显示名称。
- `REGISTRY_BROKER_PLUGIN_LOG_LEVEL`
可选。默认为 `info`。
## 在 Codex 中使用
首先使用任务形状的提示。Codex 可以首先调用 `registryBroker.delegate`，然后决定是否列出候选人或召唤。
对于更高风险的委托，您也可以传递结构化的简介：
- `deliverable`
- `constraints`
- `mustInclude`
- `acceptanceCriteria`
示例提示：
- `委托此错误调查并返回修复计划。`
- `为此 TypeScript 验证任务查找代理候选人。`
- `在发送此补丁审查之前，预运行代理交接。`
- `为此产品编写商业计划和 GTM 大纲。`
- `为此功能设计一个着陆页和引导方向。`
- `研究市场并比较最强大的替代方案。`
典型流程：
1. Codex 调用 `registryBroker.delegate`。
2. 代理返回 `delegate-now`、`review-shortlist` 或 `handle-locally`。
3. Codex 调用 `registryBroker.summonAgent`，显示 `registryBroker.findAgents`，或保持本地工作。
4. 如果发生了委托，Codex 可以使用 `registryBroker.sessionHistory` 恢复代理对话。
插件现在返回显式的下一步操作有效负载，以便 Codex 可以直接从委托规划移动到候选人列表审查、调度预览、实时召唤和会话恢复。
## 验证
存储库检查：
```bash
pnpm run lint
pnpm run typecheck
pnpm test
pnpm run build
```
GitHub Actions 还会在每次推送和拉取请求时运行 [HOL Codex 插件扫描器操作](https://github.com/hashgraph-online/codex-plugin-scanner/tree/main/action)，将 SARIF 上传到 GitHub 代码扫描，并强制执行此插件的最低扫描器分数和严重性门槛。
代理支持的烟雾测试：
如果您的代理需要 API 密钥，请在运行命令之前在您的 shell 中设置 `REGISTRY_BROKER_API_KEY`。
```bash
REGISTRY_BROKER_E2E_DISCOVERY_QUERY="<应返回目标候选人的搜索短语>" \
REGISTRY_BROKER_E2E_DISCOVERY_EXPECT_UAID="<uaid:aid:可发现的代理>" \
REGISTRY_BROKER_E2E_UAID="<uaid:aid:目标代理>" \
REGISTRY_BROKER_E2E_MESSAGE="<您的探测消息>" \
REGISTRY_BROKER_E2E_EXPECT="<预期的响应子字符串>" \
pnpm run e2e:broker
```
可选的查询驱动的召唤验证：
```bash
REGISTRY_BROKER_E2E_QUERY_SUMMON_QUERY="<应解析为可聊天的代理的查询>" \
REGISTRY_BROKER_E2E_QUERY_SUMMON_EXPECT_UAID="<uaid:aid:查询选定的代理>" \
REGISTRY_BROKER_E2E_QUERY_SUMMON_EXPECT="<预期的委托响应子字符串>" \
pnpm run e2e:broker
```
烟雾测试支持：
- 本地代理验证，当您提供已知的工作目标时
- 针对 `https://hol.org/registry/api/v1` 的 HOL 主机推荐消费验证
- 使用结构化委托简介的干运行召唤验证
- 用于后续工作的会话历史摘要
## 存储库布局
- `src/mcp.ts`：MCP 工具定义和编排
- `src/brief.ts`：结构化委托简介渲染
- `src/delegation.ts`：规划器选择、备用搜索和召唤助手
- `src/planner.ts`：规划器选择和候选人列表格式化助手
- `src/broker.ts`：代理客户端适配器
- `src/config.ts`：运行时配置
- `src/tool-contracts.ts`：共享 MCP 模式
- `src/tool-results.ts`：下一步和会话历史摘要
- `scripts/e2e-local-broker.ts`：代理支持的烟雾测试
- `skills/registry-broker-orchestrator/SKILL.md`：Codex 使用指南
## 贡献
在贡献之前，请阅读我们的 [贡献指南](./CONTRIBUTING.md) 和 [行为准则](./CODE_OF_CONDUCT.md)。
对于错误和功能请求，请使用 [问题跟踪器](https://github.com/hashgraph-online/registry-broker-codex-plugin/issues/new/choose)。
## 安全
有关安全问题，请参阅 [SECURITY.md](./SECURITY.md)。
## 维护者
请参阅 [MAINTAINERS.md](./MAINTAINERS.md)。
## 许可证
Apache-2.0
[trust-badge-img]: https://img.shields.io/endpoint?url=https%3A%2F%2Fhol.org%2Fapi%2Fregistry%2Fbadges%2Fplugin%2Fhol%252Fregistry-broker-codex-plugin%3Fmetric%3Dtrust%26style%3Dflat
[trust-badge-link]: https://hol.org/registry/plugins/hol%2Fregistry-broker-codex-plugin
