Common Ground

Common Ground

规划一场让整个朋友圈都满意的夜晚。 适合总为去哪儿争论不休的朋友。每个人说出几支喜欢的乐队、几部喜欢的电影、剧集或书。 Qloo 的跨领域品味图谱会把大家共同的喜好转化为你所在城市的晚餐、饮品和现场音乐。 每个站点都会列出选中它的心头好，并显示每位朋友的品味占比。

打开在线应用 · 演示视频（85 秒） · MCP 端点 · 在线模式检查

为什么需要 Qloo

• 一个领域的品味能帮你挑选另一个领域的去处。 朋友圈里没人提到餐厅或酒吧。Ana 喜欢 Radiohead 和 Dune，Tom 喜欢 Kendrick Lamar 和 The Bear。Qloo 会将这些音乐、电影和电视品味关联到所在城市的真实场所。单靠搜索引擎或大模型，无法为这种关联提供针对每个人的评分。
• Qloo 会说明原因。 每个站点都会使用 Qloo 的 feature.explainability。应用会列出促成推荐的心头好（“Radiohead、Ana、16%”），并按朋友拆分各自的推荐占比。如果某位朋友的品味几乎没有影响，应用会明确说明，并请对方再提供一个心头好。
• 每位朋友都有真实评分。 Qloo Insights 会为每位朋友提供其对每个候选场所的亲和度。每个站点都是让最不满意的朋友也尽可能满意的场所。评分是 Qloo 的原始亲和度，因此实际差异会清楚呈现，难分高下的结果也会标明。
• 绝不捏造信息。 每个心头好都会通过 Qloo 搜索进行匹配。无法识别的名称会如实报告，不会猜测。在线调用失败时会显示错误，而非虚假数据。

30 秒上手

1. 打开在线应用。“里斯本周五”已准备好，包含四位朋友。
2. 点击 规划我们的夜晚。大约需要 4 至 9 秒。
3. 查看三个站点。“推荐依据”会列出促成各场所推荐的心头好。“品味占比”会显示每位朋友所占的份额。
4. 打开 查看 Qloo 的处理过程，查看在线调用次数和匹配到的 Qloo 实体。
5. 试试“纽约生日”或“伦敦团队之夜”，也可以输入你自己的朋友。

在夜晚规划器下方，“或者一起挑选一项”会用同样公平的方式，为大家推荐一部电影、一部剧集、一本书、一位艺术家或一家餐厅。无需登录。

在 Agent 中使用

两个流程都是 MCP 工具，使用同一个 Streamable HTTP 端点：plan_night_out 和 find_common_ground。

claude mcp add --transport http common-ground https://common-ground.lipmichal.workers.dev/mcp

然后可以这样向 Agent 提问：“规划一场在里斯本的夜晚。Ana 喜欢 Radiohead 和 Dune，Tom 喜欢 Kendrick Lamar 和 The Bear，Priya 喜欢 Phoebe Bridgers 和 Normal People。” plan_night_out 接受一个 city，以及 2 至 6 位 members，每人提供 1 至 4 个 likes。它会返回三个站点、每个站点背后的心头好、每位朋友的占比，以及调用记录。 find_common_ground 的输入包括 kind、可选的 tasteFrom（某个类别，或用于混合喜好的 any）、可选的 location，以及 2 至 8 位 members，每人提供 2 至 5 个 likes。 该工具会返回推荐结果、三个备选项、针对每个人的理由，以及 Qloo 调用记录。

在官方 MCP 注册表中的注册名称为 io.github.theluckystrike/common-ground。

由 Michael Lip 为 Qloo Agentic Hackathon 打造。采用 MIT 许可证。

设置

使用 Node.js 22 或更高版本以及 npm。

npm ci
npm test
npm run typecheck
npm run dev

打开 Wrangler 输出的本地 URL。 没有密钥时，应用会使用本地合成数据运行（见下文）。

如需在本地使用在线模式，请将密钥放入 .dev.vars。 添加一行，写入变量名称和实际值。 请妥善保管此文件。

QLOO_API_KEY=YOUR_API_KEY

Qloo 如何规划夜晚行程

1. GET /search 会在艺术家、电影、电视节目和书籍中解析每个喜好项。每个喜好项都会保留 Qloo 返回的类型。
2. 对于每个行程点（晚餐、饮品、现场音乐），会调用一次 GET /v2/insights，将所有人的喜好项作为 signal.interests.entities 发送，并设置 filter.type=urn:entity:place、包含城市名称的 filter.location.query、行程点标签，以及 feature.explainability=true。行程点标签分别为 urn:tag:genre:place:restaurant、urn:tag:category:place:bar 和 urn:tag:genre:place:live_music_venue。
3. 群组调用会请求城市内的 30 个场所（filter.location.radius=0）。应用最多保留 20 个真实场所。场所必须在 Qloo 中有营业时间，且类别符合行程点需求，例如晚餐场所应为餐厅。商店、购物中心、市场和活动租赁场所都会被排除，街道和地区也不例外。晚餐优先选择非酒吧或咖啡馆的餐厅，现场音乐优先选择非餐厅的音乐场所。只有当某座城市的纯类别场所少于 3 个时，才会分别回退到混合类别场所。随后，每位朋友会各自再进行一次 Insights 调用，通过 filter.results.entities 为这些场所评分。
4. 每个行程点会选择原始亲和度最低分最高的场所。若出现并列，则以群组平均分打破平局。同一场所一晚只会使用一次。
5. 获胜场所的 query.explainability 评分会指出哪些喜好项促成了该结果。当 Qloo 对各喜好项的权重基本相同时，应用会将该场所描述为平衡折中方案，而不是显示几乎相同的百分比。每位朋友的占比为其喜好项评分之和。共同喜好项会均分。

四位朋友的行程规划会进行 8 次搜索和 15 次 Insights 调用。30 分钟内的相同行程会从缓存中返回，因此评委重放时不会消耗配额。

Qloo 如何驱动单一选择

Worker 会从环境中读取 QLOO_API_KEY。 在 Cloudflare 上，该值是 Worker secret。 浏览器永远不会收到这个密钥。

1. GET /search 会使用 query 和 types 解析每个喜好项。使用 tasteFrom 时，会在对应类别中解析喜好项，例如音乐艺术家。
2. 每个人都会分别运行一次 GET /v2/insights。
3. 每个 Insights 请求都会发送 filter.type、signal.interests.entities 和 take=50。
4. 餐厅请求还会发送 filter.location.query 和 filter.tags=urn:tag:genre:place:restaurant，从而排除博物馆和车站。
5. 客户端会读取每个实体的 query.affinity，其范围按文档定义为 0 到 1。
6. 工具会汇总每个人的热门候选项，最多包含 50 个 ID。
7. 每个人都会再进行一次 Insights 调用，通过 filter.results.entities 为这些候选项评分。
8. 每个人的评分都会除以其自身的最高亲和度。
9. 对于某个人，若 Qloo 未为某个候选项评分，该候选项对该人的评分将记为 0。
10. 工具会移除已知喜好项，并选择最低分最高的候选项。

密钥只会通过 X-Api-Key 请求标头传递。 黑客马拉松调用使用 https://hackathon.api.qloo.com。 调用会在五秒后超时，可解释性调用则为九秒。超时后会重试一次。 调用之间会留出间隔，以确保低于黑客马拉松每秒 10 次请求的限制。 收到 429 响应后，会在一秒后重试两次。 身份验证、配额和网络错误都会被报告。 实时调用失败时，绝不会切换到固定数据。

参阅 搜索参考、 Insights 参考 和 黑客马拉松开发者指南。

不使用密钥运行

这仅用于本地开发。托管应用使用实时数据。 不使用密钥时，同一个 Qloo 客户端会读取本地合成测试数据。 两种模式都会运行相同的解析和公平性代码。 页面横幅、结果备注、JSON 响应和 MCP 响应都会显示当前模式。 测试数据中的亲和度和 ID 均为虚构。 它们不能证明 Qloo 的推荐结果或真实用户偏好。 夜间计划测试使用一组为里斯本团体记录的真实 Qloo 响应，并将其精简为 ID、名称、类型、亲和度和可解释性数据。

测试数据文件引用了文档中的响应架构。 搜索会返回 success、duration 和 results 数组。 Insights 会返回 success 和包含 entities 与 duration 的 results。 每个 Insights 实体都有 query.affinity。

示例涵盖电影、书籍、餐厅、艺术家和电视节目。 只有测试数据目录中列出的名称才能在不使用密钥时解析。 未知名称会被报告，而不是凭空编造。 测试数据中的餐厅均为虚构，并仅限于华沙示例。 这些名称不代表现实中存在相应场所。

部署

使用你自己的 Cloudflare 账户对 Wrangler 进行身份验证。

npm run deploy
npx wrangler secret put QLOO_API_KEY
npm run verify:live -- https://YOUR-WORKER.workers.dev

密钥命令会提示输入密钥。 它会更新已部署的 Worker，而不会将密钥存储在源代码中。 验证命令会检查模式并执行一次真实的团体选择。 它不会打印凭据，也不会存储任何 Qloo 数据。

GET /health 会报告所选模式以及是否已配置密钥。 仅有实时健康检查响应只能证明配置已完成。 成功的实时选择则能确认 Qloo 已作出响应。

Agent 访问

将 Streamable HTTP MCP 客户端连接到已部署主机上的 /mcp。 列出工具，并使用与 /api/pick 相同的输入调用 find_common_ground。

{
  "kind": "movie",
  "members": [
    { "name": "Ana", "likes": ["Prisoners", "Gone Girl"] },
    { "name": "Tom", "likes": ["Interstellar", "Inception"] }
  ]
}

添加 "tasteFrom": "artist"，即可从音乐收藏中选择电影。

该工具会返回结构化结果和纯文本。 它是只读的，不会预订场所或购买媒体。

限制

夜间计划支持 2 至 6 位朋友，每人有 1 至 4 个收藏，并且需要足够大的城市。 可解释性分数通常相差很小，因此「选择依据」显示的是影响因素，而非单一原因。 场所检查会使用 Qloo 的类别标签和营业时间。它会排除街道、城区、商店和市场，但在小城市中，兼具多种类型的场所（例如餐厅兼酒吧）仍可能胜出。

团体人数为 2 至 8 人，每个人都有不同的姓名。 每个人提供 2 至 5 个收藏。 餐厅选择需要提供城市，并将具名场所作为收藏。 菜系名称不会被视为餐厅实体 ID。 搜索会选取所请求类型的第一个结果。 它不会要求用户确认有歧义的匹配结果。

每个人最多会有 50 个候选项。 缺失的结果会按零处理，这可能反映了覆盖范围有限。 此方法不会为每个人评估所有可能的候选项。 第二轮 Insights 会为每个人评估共享候选池中的最多 50 个候选项，因此最低分为零的情况很少见。 匹配分数是在每个人返回的列表中进行相对比较得出的。 它们并非用户喜欢某项内容的概率。 有可用的共享标签时，理由会使用这些标签；否则会使用具名输入。 这些理由并非模型生成的因果解释。

餐厅结果仍可能包含被 Qloo 标记为餐厅的酒吧和咖啡馆。 一次请求最多可执行 40 次搜索和 16 次 Insights 调用。 公共端点没有应用级速率限制器或持久缓存。 Qloo 的限制可能会导致 HTTP 429。 该应用没有账户，也不会存储提交的团体资料。 实时模式下，收藏名称和实体 ID 会发送给 Qloo。 成员姓名仅保留在应用请求中。 黑客松结束后，API 是否可用取决于 Qloo 的访问权限。

检查

npm test 使用固定响应和模拟的 fetch 函数。 它不会调用 Qloo。 夜间计划测试会重放记录的 Qloo 响应。 测试涵盖夜间计划、可解释性分享、每个停靠点一个场所、公平性、资源池评分、输入错误、身份验证错误、速率限制、超时处理、固定数据重放和 MCP 调用。

gitleaks detect --source . --redact --no-banner
gitleaks detect --no-git --source . --redact --no-banner

扫描配置仅允许字面形式的指南占位符和本地忽略的文档 HTML。 MIT 适用于源代码。 Qloo 服务访问和数据仍受 Qloo 条款约束。