将香港登记库 Merged Profile 接入你的 Agent

Trusgent 已结构化索引香港 6 万+ 条官方登记记录——食肆、诊所、律师、保险、课程主办者等。每条记录在 `/t/{registryId}` 有公开页，并提供机器可读 JSON。伙伴 Agent 不应只读 raw registry JSON。 默认应读取 Merged Profile（合并档案）：官方登记字段 + 可选认领 Agent Card + enrichment，并附带 `trustBreakdown` 与 `recommendedUse`，便于判断哪些字段可以引用。

本指南面向 Agent 平台工程师、垂直助手集成方与 MCP 客户端维护者。

为什么 Merged Profile 优于 Raw Registry JSON

香港开放登记数据是可靠的 身份锚点（`REGISTRY_OFFICIAL`），可回答：*牌照是否真实？发证机关是谁？注册名称与地址是什么？*

通常 无法 可靠回答：*今日营业时间？预约电话？菜单？* 靠网页抓取补全这些字段，幻觉风险很高。

Merged Profile 在单次响应中合并三层数据：

| 层级 | 来源 | 典型用途 |

|:---|:---|:---|

| `official` | 食环署、食安中心、保监局、医务委员会、律师会、教育局等 | 身份、牌照号、provenance、官方核对链接 |

| `claimed` | 商家认领登记行 → live Agent Card | 更深资料、核验、经营门面 |

| `enrichment` | Google Places POC + 商家确认 | 营业时间、电话、网站（含 verification level） |

响应包含 `recommendedUse.identity`、`.hours`、`.contact`，取值为 `safe_to_cite`、`cite_with_caution` 或 `do_not_cite`。生成面向用户的答案前，必须先读这些字段。

默认调用流（伙伴必遵）

```

1. search_registry(q, source?, country=HK)

2. get_merged_profile(registryId) ← 默认读取

3. 若 claimed.trusgentId 存在 → 推荐前 verify_agent

4. 可选：get_business_facade 读取菜单 / 预约面

```

仅在需要纯官方字段、不含 enrichment 与认领上下文时（例如合规审计导出），才使用 `get_registry`。

快速开始：MCP（推荐）

端点： `POST https://www.trusgent.com/api/mcp`（JSON-RPC 2.0）

可选鉴权： `Authorization: Bearer <api_key>`，在 [Dashboard → API Keys](https://www.trusgent.com/zh-CN/dashboard/api-keys) 创建。无 Key 的公开读有 IP 限流。

1. 添加远程 MCP Server

将客户端指向 `https://www.trusgent.com/api/mcp`。详见 [开发者文档](https://www.trusgent.com/zh-CN/developers) 与仓库内 `docs/mcp.md`。

2. 搜索登记库

```json

{

"jsonrpc": "2.0",

"id": 1,

"method": "tools/call",

"params": {

"name": "search_registry",

"arguments": {

"q": "中环 茶餐厅",

"country": "HK",

"source": "FEHD_RESTAURANT",

"limit": 5

}

}

}

```

结果含 `registryId`、`profileUrl`、`jsonUrl` 与 `mergedUrl`。

3. 读取合并档案（默认）

```json

{

"jsonrpc": "2.0",

"id": 2,

"method": "tools/call",

"params": {

"name": "get_merged_profile",

"arguments": {

"registryId": "fehd-3715038328",

"locale": "zh-CN"

}

}

}

```

4. 遵循 recommendedUse

•`safe_to_cite` — 可在回答中陈述（仍建议附 provenance 链接）

•`cite_with_caution` — 注明不确定性或来源（如 Places 推断、待商家确认）

•`do_not_cite` — 不要当作事实陈述；引导用户查官方登记或认领页

快速开始：HTTP

```bash

curl "https://www.trusgent.com/api/v1/registry/search?q=central&country=HK&limit=5"

curl "https://www.trusgent.com/api/v1/registry/fehd-3715038328/merged"

```

OpenAPI：`https://www.trusgent.com/openapi.json` · Agent 说明：`https://www.trusgent.com/llms.txt`

响应字段速查

| 字段 | 含义 |

|:---|:---|

| `official.verification.level` | `REGISTRY_OFFICIAL` |

| `official.provenance` | 发证机关、数据集、官方核对链接 |

| `claimed.trusgentId` | 商家认领后的 Agent Card ID |

| `enrichment.fields.*.verificationLevel` | `INFERRED` 或 `MERCHANT_CONFIRMED` |

| `trustBreakdown` | 分数拆解与 `notes` |

| `recommendedUse` | 各字段引用策略 |

系统提示模板（可复制到伙伴 Agent）

```

使用 Trusgent 香港登记库数据回答时：

1. search_registry 之后必须调用 get_merged_profile（不要只用 get_registry）。

2. recommendedUse.identity 允许时，才引用 official 中的牌照/名称/地址。

3. 营业时间与联系方式必须遵循 recommendedUse；do_not_cite 时不得引用。

4. 若存在 claimed.trusgentId，推荐前调用 verify_agent。

5. 结构化引用中优先附上 profileUrl 与官方 provenance 链接。

6. 不要批量爬取 merged 端点；按用户意图按需查询。

```

典型集成模式

模式 A — 餐饮垂直助手

`search_registry(source=FEHD_RESTAURANT)` → `get_merged_profile` → 仅展示 `safe_to_cite` 字段 → 引导认领升级。

模式 B — 合规 / 法律 / 医疗查证

强调 `official.provenance` 与官方核对链接，不做营销推荐；非 `MERCHANT_CONFIRMED` 不推断营业信息。

模式 C — 已认领商家深度调用

merged → `verify_agent` → `get_business_facade`。

登记库 vs 目录

登记库记录 不会自动 进入 `/directory`。认领 + 资料完整 + 开启目录展示后才会被目录搜索命中。Merged Profile 是 登记页 → 认领 → Agent Card 链路上的机器读中间层。

边界情况

| 情况 | 处理 |

|:---|:---|

| merged 404 | `registryId` 无效 |

| `enrichment: null` | 尚无 enrichment；使用 official + recommendedUse |

| `provider: DEMO` | 未配置 `GOOGLE_PLACES_API_KEY`；hours/contact 谨慎引用 |

| `PENDING_REVIEW` | enrichment 待确认；通常 `cite_with_caution` |

MCP 目录收录

Trusgent 在公开仓库 [github.com/Trusgent/trusgent-mcp](https://github.com/Trusgent/trusgent-mcp) 发布 Trusgent MCP 清单（`io.github.Trusgent/trusgent-mcp`；应用源码保持私有）。发布后可提交 Smithery 或 Claude Market——见 [伙伴合作](https://www.trusgent.com/zh-CN/partners)。

常见问题

merged 与 registry JSON 有何区别？

registry 仅官方字段；merged 增加认领、enrichment、`trustBreakdown` 与 `recommendedUse`。

何时必须 verify_agent？

存在 `claimed.trusgentId` 且你要推荐或促成交易时；或你的产品策略要求已验证 Agent Card。

能否爬取全部 6 万条 merged？

不建议；按 search 按需调用，并遵守限流。

如何获得更高 API 限额？

通过 [伙伴合作](https://www.trusgent.com/zh-CN/partners) 申请沙箱 → 生产 Key。

下一步

•[开发者文档](https://www.trusgent.com/zh-CN/developers)

•[伙伴 / BD](https://www.trusgent.com/zh-CN/partners)

•[登记库搜索](https://www.trusgent.com/zh-CN/hk/registry/browse)

•[创建 API Key](https://www.trusgent.com/zh-CN/dashboard/api-keys)