indykite-ciq-read

IndyKite ContX IQ - 只读策略 + 知识查询

ContX IQ（CIQ）是 IndyKite 在 IKG（IndyKite 的知识图谱）之上的上下文感知数据层。IKG 是一个使用 Cypher（Neo4j / openCypher 图查询语言）查询的属性图数据库。CIQ 策略声明可以访问哪些图元素以及在什么条件下访问；CIQ 知识查询声明如何处理这些元素；执行调用则会在运行时使用具体参数值运行知识查询。

本技能涵盖只读流程：

• 策略的 condition.cypher 用于匹配节点和关系，而 allowed_reads 则将知识查询可以返回的变量列入允许列表。
• 知识查询在 nodes、relationships 和/或 aggregate_values 中列出这些变量。
• execute 调用为策略的部分筛选条件（$variable）提供值，并返回行。

allowed_upserts 和 allowed_deletes 在此处有意不在范围内——只读场景请完全省略这些字段。

适用场景

在以下情况下启用此技能：

• 用户想要从 IKG 读取数据，并通过 CIQ 策略 + 知识查询塑造结果；
• 用户正在构建 indykite-agent-gateway 技能从 ContX IQ 获取的 (workflow, agent_list) 查询；
• 用户正在准备一个由 indykite-mcp-server 技能通过 ciq_execute 运行的知识查询；
• 用户正在排查读取型 CIQ 返回空结果，或向本应有权访问的主体返回 403 的问题。

在以下情况下不要启用此技能：

• 用户需要通过 CIQ 创建、更新或删除节点或关系——这需要使用 allowed_upserts / allowed_deletes 和 upsert_* / delete_* 知识查询字段。为使说明更清晰，本技能不涉及这些内容；
• 用户正在调用 AuthZEN 进行是/否授权判定（请使用 authzen_evaluate 和 MCP 技能）；
• 用户正在调用外部数据解析器，以便在查询时从外部 API 获取数据（这是另一项功能）。

前提条件

• 一个 IndyKite 项目、一个 AppAgent，以及 AppAgent 凭据（执行时传入 X-IK-ClientKey 的令牌）。
• 一个具有 Config API 访问权限的服务账号令牌，以及 PROJECT_GID 中的项目 GID（两者均用于创建策略和知识查询）。
• 已填充 IKG，其中包含策略将匹配的节点和关系。CIQ 只负责筛选和投影，不会写入初始数据。
• 一个用于身份验证的主体类型——Person、User、_Application 等。CIQ 策略仅限单一主体类型，因此如果需要支持两个主体，请规划两个策略。

如果缺少其中任何一项，请停止并告知用户——先解决这些问题，远比排查原因不明的 CIQ 拒绝错误容易。

步骤

1. 选择主题和 Cypher 模式

主题类型 - 选择一种。两种选择的架构相同；只有 subject.type、过滤条件和执行时的身份验证有所不同：

主题	适用场景	执行时的身份验证	过滤条件约定
_Application	系统端／ETL／目录相关工作；不涉及用户。	仅需 X-IK-ClientKey。	subject.external_id = $_appId（保留字段）。
Person / User	已通过身份验证的用户亲自执行操作。	X-IK-ClientKey + Authorization: Bearer <token>。	subject.external_id = $token.sub。

策略仅限于单一主题类型——如果两种类型都需要允许，请编写两条策略。cypher 中主题的变量通常命名为 subject。下面的可运行示例使用 Person；_Application 变体（例如，读取目录的服务）仅在 subject.type、过滤条件和执行请求头上有所不同。

Cypher 模式 - 命名查询将访问的每个节点和关系的 MATCH / OPTIONAL MATCH 子句。每个节点和关系都必须有一个变量名，以便策略和知识查询可以引用它们。如果不确定项目 IKG 中的确切节点类型、关系类型或属性拼写，请先从 Data Schema API 中读取（indykite-data-schema）——拼写错误的名称不会报错，只会静默地匹配不到任何内容。

本技能中始终使用的示例：

Person（主题）拥有 Car，关系类型为 OWNS。给定某人的 external_id，返回其拥有的车辆。

MATCH (subject:Person)-[r:OWNS]->(car:Car)

变量：subject、r、car。

2. 编写只读 CIQ 策略

构建策略 JSON。对于只读策略，只需要以下三项：

• meta.policy_version - 当前为 1.0-ciq。
• subject.type - 选择的主题类型。
• condition.cypher 和（可选）condition.filter - 模式和所有过滤条件。使用 $varname 标记执行时将提供的部分过滤条件。此外还有一项可选的 condition.skip_resource_label，用于锚定并限定范围后仍然较慢的条件——使用前请参阅策略参考。
• allowed_reads - 列出知识查询获准返回的所有变量。使用 <var>.* 允许读取节点／关系的所有属性，或使用 <var>.property.<name> 允许读取单个属性。

完全省略 allowed_upserts 和 allowed_deletes——省略它们是禁止写入的受支持方式。

运行示例的完整只读策略：请参阅 assets/policy-read-cars.json。

通过 Config API 创建策略：

# set the current project_id, and stringify only the `policy` field, before POSTing
jq --arg pid "$PROJECT_GID" '.project_id = $pid | .policy |= tojson' assets/policy-read-cars.json \
  | curl -X POST "$API_URL/configs/v1/authorization-policies" \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer $SERVICE_ACCOUNT_TOKEN" \
      -d @-

返回 201 Created 时会包含策略的 id（GID）。将其导出为 POLICY_ID——创建知识查询时会将其注入 policy_id。

完整架构（所有运算符、所有属性模式以及 token_filter 的用途）请参阅 references/policy-reference.md。

3. 创建知识查询

只读知识查询引用策略，并列出要返回的内容。以下四个字段与读取相关：

• nodes - 要包含在响应中的节点变量（或 <var>.property.<name>）。
• relationships - 要包含在响应中的关系变量。
• aggregate_values - cypher 中聚合函数生成的变量（例如，COLLECT(...) AS xs → "xs"）。
• batch_read - 仅当你预计结果集足够大、可能触发默认超时时才设为 true；此设置会将超时时间延长至 5 分钟。

运行示例对应的完整知识查询：参见 assets/knowledge-query-read-cars.json。

通过 Config API 创建（将 POLICY_ID 设为上一步中策略的 GID）：

# set the current project_id and policy_id, and stringify only the `query` field, before POSTing
jq --arg pid "$PROJECT_GID" --arg polid "$POLICY_ID" '.project_id = $pid | .policy_id = $polid | .query |= tojson' assets/knowledge-query-read-cars.json \
  | curl -X POST "$API_URL/configs/v1/knowledge-queries" \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer $SERVICE_ACCOUNT_TOKEN" \
      -d @-

返回 201 Created 时会包含知识查询的 id（GID）。execute（以及 MCP ciq_execute 工具）将引用此 ID。

所有知识查询字段（包括读场景中未涉及的 upsert_* 和 delete_*）的架构详情：references/knowledge-query-reference.md。

4. 执行查询

execute 端点会在运行时使用具体参数值执行知识查询：

POST <API_URL>/contx-iq/v1/execute

身份验证：

• 始终需要：X-IK-ClientKey: <AppAgent-credentials-token>。
• 如果 subject.type 不是 _Application：还需要 Authorization: Bearer <user-access-token>。令牌的 sub 是主体标识符。要查看令牌解析出的确切 type / id，请调用 GET /contx-iq/v1/whoami（indykite-ciq-whoami）。
• 如果 subject.type 是 _Application：系统会从应用的 external_id 自动填充保留参数 $_appId；不要在 input_params 中传入此参数。

请求：

{
  "id": "<knowledge_query_gid_or_name>",
  "input_params": {
    "person_external_id": "alice"
  }
}

可运行的 Shell 辅助脚本：scripts/execute.sh。

大型结果集支持分页，可使用两个可选请求体字段：page_size（每页行数，默认值为 100）和 page_token（从 1 开始的页码；1 或省略表示第一页，2 表示下一页）。响应不包含令牌，因此需要自行递增页码，并在某页返回的行数少于 page_size 时停止。辅助脚本会发送第一页；要获取其他页，请将这两个字段添加到原始请求体中。MCP ciq_execute 工具接受相同的两个可选参数（indykite-mcp-server）。

完整的 execute 参考文档（身份验证组合、响应格式、分页和错误语义）见 references/execution-reference.md。

5. 读取并验证响应

响应格式如下：

{
  "data": [
    { "nodes": { "<var>.<attr>": "<value>", ... } },
    { "relationships": { ... } }
  ]
}

每个匹配项对应一行，nodes 以 <var>.<attr> 为键，relationships 也以类似格式为键。如果策略或知识查询将某个变量加入白名单，但 IKG 中没有匹配项，则数据数组会为空。

如果响应不符合预期，请先按以下清单逐项检查，再修改策略：

1. 响应中是否包含该变量？ 它必须同时出现在策略的 allowed_reads.nodes / relationships / aggregate_values 中，以及知识查询的 nodes / relationships / aggregate_values 中。只有两者的交集才会返回。
2. 筛选条件是否实际生效？ attribute 中的拼写错误（例如 subject.external_id 与 person.external_id 不一致）会导致无法匹配任何内容。请重新查看属性命名约定。
3. 主体是否设置正确？ 对于非 _Application 主体，Bearer 令牌的 sub 是主体标识符；如果没有令牌，主体将不会绑定，许多策略都无法匹配任何内容。
4. IKG 中是否确实存在数据？ 使用相同结构运行探测查询，并添加 IS NOT NULL 筛选条件，以确认数据存在。

预期结果

成功应用此技能后：

• 项目中存在一个只读 CIQ 策略；它只有一个 subject.type，包含带命名变量的 cypher 模式、可选的部分筛选条件和 allowed_reads 白名单，但没有 allowed_upserts 或 allowed_deletes。
• 一个 Knowledge Query 引用该策略，并在 nodes / relationships / aggregate_values 中准确列出应返回的变量。
• 对于有效的 input_params，POST /contx-iq/v1/execute（或 MCP ciq_execute 工具）会返回预期的行；对于有效但不匹配的参数，则返回空的 data 数组。
• 无需进一步更改，即可通过 indykite-mcp-server 技能中的 ciq_execute 调用同一个 Knowledge Query。

此技能中的文件

• references/policy-reference.md - 只读策略架构、运算符、属性命名、部分筛选条件、token_filter 和 step-up 建议。
• references/knowledge-query-reference.md - Knowledge Query 架构，包括此处使用的只读字段，以及其他每个字段的单行说明，供参考。
• references/execution-reference.md - POST /contx-iq/v1/execute 的请求和响应结构、身份验证组合、常见错误代码。
• assets/policy-read-cars.json - 可运行的只读策略，用于 Person -[:OWNS]-> Car 示例。
• assets/knowledge-query-read-cars.json - 匹配的 Knowledge Query。
• scripts/execute.sh - Bash 辅助脚本，使用正确的标头向 /contx-iq/v1/execute 发送请求。

特定于 Agent 的说明

此技能使用通用 Markdown 指令，可用于 README 中列出的所有 Agent。Agent 需要能够发送 HTTP 请求（使用 curl、HTTP 客户端或 IndyKite Terraform provider，参见参考资料）。无需 Claude Code hooks、Cursor @ 提及或 Copilot 工作区上下文。

参考资料

• ContX IQ 指南（开发者中心）
• Config API 文档
• Cypher 查询语言手册（Neo4j；openCypher） - CIQ 策略和 Knowledge Query 中的条件所使用的图查询语言，用于查询 IndyKite Knowledge Graph。
• IndyKite Terraform provider - indykite_authorization_policy 和 indykite_knowledge_query
• 凭据指南
• 外部数据解析器指南（不在此处的讨论范围内，但对后续工作很有帮助）