cala

Cala — AI Agent 的知识层

Cala 是一个涵盖全球公开数据的知识图谱：其中包含命名实体、实体属性、实体之间的关系，以及带时间戳的观测数据——每个值都附带来源和日期。查询它，而不是抓取网络。

本技能假设已加载 Cala 工具（其架构包含参数和请求体结构）。它涵盖架构无法说明的内容：该使用哪个工具、查询语言、读取规范，以及如何处理失败。

访问

MCP（首选）： 使用你的 API 密钥连接到 https://api.cala.ai/mcp/，然后直接调用工具。如果你的上下文中没有 Cala 工具，则说明服务未配置——停止，并引导用户访问 https://docs.cala.ai/integrations/mcp。

REST（备用）： 基础 URL 为 https://api.cala.ai/v1，请求头为 X-API-KEY: <key>。端点与工具名称一一对应；规范见 https://api.cala.ai/openapi.json。可在 https://console.cala.ai/api-keys 获取密钥。

选择合适的工具

Filter / list / "find all X where Y"?          → knowledge_query
Open-ended "what", "who", "explain"?           → knowledge_search
Have a name, want the entity (a seed UUID)?    → entity_search
Have a UUID, want a coarse profile?            → entity_retrieval (no body)
Have a UUID, don't know what's queryable?      → entity_introspection
Have a UUID, want specific fields/rels/metrics → entity_introspection → entity_retrieval

优先使用结构化查询。 knowledge_query 和指定字段的 entity_retrieval 所需的令牌远少于 knowledge_search，行为也更可预测。如果你知道答案的结构，就采用结构化路径；只有在问题确实开放时才使用 knowledge_search。

knowledge_query — 结构化筛选

一种点号表示法查询语言。将每个 . 视为跨越图谱的一次跳转：OpenAI.founded.year 先沿 founded 边跳转，再读取 year。系统会解析字段名称的自然变体，因此按你的意思编写即可。

• 运算符：= 精确匹配 · != 不等于 · > < <= >= 数值比较 · , = 对同一字段执行 AND（investors=Sequoia Capital,Andreessen Horowitz → 必须同时得到 两者 的支持，而非其中任意一个）。
• 修饰符，子句顺序为 filters → order_by → limit → return()：
  • order_by=field ASC|DESC — 改变哪些记录会出现，而不只是改变顺序（默认按相关性排序）。
  • limit=N — 限制结果数量。
  • return(f1, f2, ...) — 仅投影这些字段；降低令牌成本。
• 数值字段可能返回近似字符串（"over 100M"、"~206,753"）——请综合判断，不要将其视为精确值。

{"input": "OpenAI.founded.year"}
{"input": "startups.location=Spain.funding>10M.order_by=funding DESC.limit=5.return(name, funding, sector)"}
{"input": "companies.investors=Sequoia Capital,Andreessen Horowitz"}
{"input": "companies.sector=climate tech.funding_round.series=A,B.location=Southern Europe.return(name, funding, investors)"}

返回 results（行）和 entities（所有提及的实体——地点、人物等，与行并非一一对应）。将实体 UUID 传给 entity_retrieval 以获取更深入的信息。

命名实体 — entity_search → entity_retrieval

使用 entity_search 将名称解析为种子实体（模糊名称 → UUID；每条命中结果都包含 name、entity_type、description——根据描述进行选择）。

从种子 UUID 出发，entity_retrieval 支持两种读取模式：

• 粗略概况 — 不提供请求体；仅返回默认属性，不包含关系或数值观测数据。
• 投影 — 提供请求体，指定确切的 properties、relationships 和 numerical_observations；这是获取关系或时间序列的唯一方式，也是最精简的读取方式。

先检查，再投影。 每个实体可查询的架构各不相同，因此应先对种子实体运行 entity_introspection——它会返回已填充的邻域信息（属性、传入／传出的关系，以及指标 UUID）。然后只投影这些内容。盲目投影会浪费请求次数，还可能请求空边。

关系结构。 边采用 UPPER_SNAKE 类型，并带有方向；遍历方向分为传入或传出。边类型有数十种——例如，传入公司实体的 FOUNDED（创始人）、IS_CEO_OF（高管）、IS_DIRECT_OWNER_OF（投资者）；传出的 IS_ULTIMATE_PARENT_OF（子公司）。某个实体实际具备哪些边，以内省结果为准。

观测数据（numerical_observations）是时间序列数据——包括财务数据、宏观指标、外汇和持仓信息——每条都由内省结果中的指标 UUID 标识。这些数据是带有历史记录的最新来源数据，并非实时行情。

每项属性和关系都带有其来源信息（sources：名称、文档 URL、日期）。请保留这些信息——呈现事实时一并传递来源和日期。

knowledge_search — 附带来源信息的叙述性回答

适用于开放式问题。返回 content（Markdown 格式）以及来源链：

• explainability[i] = {content: "claim", references: [ctx-id, ...]} — 每项声明都映射到上下文 ID。
• context[j] = 来源文档，每个文档都包含 id 和 origins[k].document.url（可引用的链接）及 origins[k].source.name（发布者）。

引用某项声明：将其 references 与 context[j].id 匹配，然后使用该上下文的 origins URL 和发布者。entities 保存用于深入查询的 UUID。

失败时——立即停止，不要编造

发生任何故障时，立即停止并说明情况。绝不要悄悄改用网页搜索、训练数据记忆或记忆内容——那只是伪装成 Cala 回答的编造内容。用户可以明确要求使用备用方案。

• 无法连接 → 停止；提供 https://console.cala.ai/api-keys 和 https://docs.cala.ai/integrations/mcp。
• 超时（查询最长可能需要 180 秒；通常是主机而非 Cala 的问题）→ 使用相同调用重试一次，然后停止：“将 MCP 客户端超时设置提高到约 180 秒后重试。”
• 无数据 → 区分 {"results": [], "entities": []}（没有匹配项／问题过于含糊）与 {"results": [{"error": "...too complex..."}], "entities": null}（问题过于复杂）。扩大或简化问题，或改用 knowledge_search；如果仍无结果，则停止。
• 请求受限（HTTP 429）→ 停止并说明情况，不要重试。