授权空间发现与跨空间查询¶

OWL 默认查询当前工作空间。需要查询其他工作空间时，先区分授权数据查询和同组织 Trace 查询，再选择对应工具。

选择查询方式¶

场景	空间发现	查询方式
本空间	无需发现空间	不传空间参数，直接查询
授权跨空间数据	目标未确定时调用 `owl.workspace.data_authorized.list`	DQL 工具传 `workspace_uuids` 和 `target_region`，一次查询限定一个目标站点
同组织跨空间 Trace	目标 UUID 未确定时调用 `owl.account.workspace.same_org.list`	`owl.data.same_org.trace.query` 传 `trace_id` 和所选 `workspace_uuids`；省略或空数组只查本空间

已有明确的发现结果可直接复用。同组织空间列表不代表普通数据查询授权，不能替代授权空间列表。查询失败或返回空结果时，不应切换凭据、扩大空间范围或改用另一类查询路径。

升级与成员工具迁移¶

使用前确认目标站点已支持授权空间发现和跨空间查询。CLI 升级至 v1.4.0，服务端配套升级 Registry 与工具目录后，执行全量同步；MCP 客户端重新发现工具。

owl sync
owl tool list --category workspace

新增的 workspace 分类包含 owl.workspace.data_authorized.list 和 owl.workspace.member.list。旧 member 分类移除，旧名 owl.member.list 保留为成员工具的调用别名，复用相同参数和权限校验，但不会作为独立工具出现在列表中。

owl exec owl.workspace.member.list -p '{"search":"alice"}'
# 兼容旧脚本
owl exec owl.member.list -p '{"search":"alice"}'

旧版 CLI 不支持别名，仅同步目录无法保证旧命令可用。请先升级 CLI，再执行 owl sync，不要只同步 workspace 分类。

发现授权空间¶

owl.workspace.data_authorized.list 按站点列出向当前工作空间授予数据查询权限的空间。

owl exec owl.workspace.data_authorized.list -p '{}'

参数	类型	说明
`region_code`	string	可选，筛选目标站点；保留返回的完整编码，包括 `custom:` 等前缀
`search`	string	可选，按空间名称或 UUID 搜索
`page_index`	integer	每站点页码，从 1 开始，默认 1
`page_size`	integer	每站点每页 1 至 100 个空间，默认 100

可选字符串无值时省略，不能传 null、空字符串或纯空白。使用返回的 workspace_uuid 和 region_code 选择目标，不切换到目标空间的 API Key。

返回结果中的 current_workspace 是当前空间，sites[] 包含各站点的 workspaces 与独立的 page_info。没有全局页码；当某个站点仍有下一页时，保留筛选条件并单独查询该站点：

owl exec owl.workspace.data_authorized.list -p '{"region_code":"cn2","page_index":2,"page_size":100}'

按 (region_code, workspace_uuid) 区分空间。列表说明空间之间存在查询授权，具体数据类型和日志索引权限仍由查询接口校验；page_size 也不是查询空间数量上限。

查询一个目标站点的数据¶

CLI 使用 owl.data.query 或 owl.data.simple_query_file；MCP 使用 owl.data.simple_query。跨空间查询在现有 DQL 参数之外增加：

参数	类型	规则
`workspace_uuids`	string[]	非空数组，元素取自授权空间列表的 `workspace_uuid`
`target_region`	string	取自列表的 `region_code`；提供此参数时必须同时提供 `workspace_uuids`

省略两者时查询当前空间。只传空间 UUID 时，服务端根据已有授权推导站点。同一请求可以选择一个站点内的多个授权空间，但不能混合多个站点；显式查询远端站点时不能同时包含当前空间。

workspace_uuids=["*"] 表示目标站点的全部授权空间；省略目标站点时使用当前站点并包含当前空间。* 不能与明确 UUID 混用，且每次翻页都会重新解析授权；需要固定查询范围时传明确 UUID。

CLI 示例¶

将示例中的空间、站点、数据源和时间替换为实际值。时间使用 13 位毫秒时间戳，结束时间晚于开始时间，跨度最多 7 天。

owl exec owl.data.simple_query_file -p '{"namespace":"L","source":"nginx","start_time":1772516130000,"end_time":1772516140000,"limit":100,"workspace_uuids":["wksp_b","wksp_c"],"target_region":"cn2"}'

CLI 将查询结果保存为 data 文件，并在文件索引的参数中保留空间和站点范围。不要假设每条数据都带有空间字段，也不要把所有数据归到第一个空间。

MCP 示例¶

facade 模式先发现 workspace 分类中的授权空间工具，获取查询范围后，通过 exec_tool 调用：

{
  "tool_name": "owl.data.simple_query",
  "parameters": {
    "namespace": "L",
    "source": "nginx",
    "start_time": 1772516130000,
    "end_time": 1772516140000,
    "workspace_uuids": ["wksp_b", "wksp_c"],
    "target_region": "cn2"
  }
}

static 模式从 tools/list 发现工具后，以业务工具名直接调用 tools/call，将上述 parameters 对象作为 arguments。两种模式均使用当前连接的认证信息。

翻页和处理错误¶

授权空间列表使用页码，数据查询使用游标。数据响应中 data.page_info.has_more=true 时，将返回的 next_cursor_time / next_cursor_token 原样作为下一次 cursor_time / cursor_token，保留原有时间、条件、空间和站点范围。

游标时间可能使用微秒，不要转换成 13 位毫秒；也不要将列表的 page_index、page_size 用于数据查询。每次调用只获取一页，后续页由调用方显式请求。

先检查 CLI 的 success 或 MCP 的 isError，再解析工具结果；text 工具的 AIAPI 响应位于 OWL 执行结果的 output 字符串中。
成功但数据为空是有效结果，不应自动扩大范围重查。
参数、授权或站点不一致时，修正参数或重新确认授权范围；不要逐空间重试来绕过失败。
如果返回 trace ID 或结构化错误诊断字段，保留这些信息用于排查。
目标站点不支持工具或跨空间参数时，先联系管理员确认服务端版本，不要删除空间参数后重试。