Operations

turing-cli operations 用于查询 Turing Platform/Core 的用量、费用、token、模型和请求明细。

在智能体工作流中,可以配合 SkillHub 上的 Turing Operations skill 使用本页命令;如果还需要先读取账单、表格、PDF 或 PPT 材料,可搭配 Documents skill 调用 turing-cli documents convert。也可以按自己使用的智能体或 IDE 规范自行配置自有 skills。

查询模型可以理解为两类;在调用前先用 capabilities 读取当前调用者的有效权限和业务契约:

dashboards:    查询主体 (--type, 选 1 个) × 独立拆分 (--include, 可选多个) + 指标
grouped-usage: 查询主体 (--type, 选 1 个) × 二维组合 (--group-by, 选 1 组) + 指标

Portal / CoWork(turing-claw, openclaw) 不是 --type,也不是查询过滤条件;它们是 by_channel 返回结果里的组。问"portal 花了多少 / API Key 花了多少"用 --include by_channel。比如“某个人的 Portal / CoWork(turing-claw) 用量”应先用 --type username --value X 查这个人的总用量,再从 by_channel 里读取对应组。

要下钻一把具体 API Key,通常先在 person / client 的 by_apikey 中取得非敏感的 api_key_id(ak_...),再用 --type api_key_id --value ak_xxx 查询这把 Key 的 by_service 或 by_day。默认额度聚合桶没有单一 ID;需要具体默认 Key 时从 Key 管理能力取得其 ak_... ID。不要把 sk-... 密钥传给 Operations 命令。

新增的 api_key_id 和 grouped-usage 依赖对应 Backend 能力。发布时必须先部署 Backend,再发布新 CLI 和本文档;本文不声明尚未确定的最低 CLI 版本。

查询流程

Agent 每个 Operations 任务都先读取当前调用者的有效契约,再规划后续请求:

operations capabilities  -> 确认身份、有效权限、可用 include/group-by 和 Relay 口径
operations search        -> 在授权范围内找到准确的 type/value
operations dashboards    -> 查询 summary 或必要的 by_* 明细
operations grouped-usage -> 查询允许的二维组合

API Key 不通过 operations search 搜索。先查询拥有者或 client 的 by_apikey,从具体 Key 行读取 api_key_id,再按 Key 下钻。

operations capabilities

turing-cli operations capabilities
# 等价别名
turing-cli operations my-capabilities

该命令不查询用量,而是返回当前调用者的自说明契约,并追加本机 CLI 的命令契约。Agent 每个任务必须先调用一次,并遵守:

• “我 / 我的”只使用 subject.preferred_self_target,不从邮箱前缀或姓名猜 username。
• subject.oa 只用于展示已验证的 OA 姓名、工号和部门上下文,不授予部门权限;subject 不包含内部 user_id。
• 查询目标只信 authorization.targets.*.mode/resource_types/actions;mode=none、动作缺失或 allowed=false 均表示不可调用。
• --include / --group-by 只使用对应 action 返回的 allowed_includes / allowed_group_by。
• Relay 参数读取 query_options.relay;其它动作只按 authorization.targets.*.actions 或 authorization.actions 返回的有效契约执行。
• 不通过制造 403 探测权限;权限变化后重新读取 capabilities。

只有 Backend 明确对 capabilities 返回 404 / 501 时,旧客户端才可窄降级到调用方已经明确提供或此前可信验证的本人 username/email,以及从本人结果发现的自有 api_key_id。401 / 403、5xx、网络错误、未知 schema 或本地 CLI 不认识 capabilities 命令都不能当作可降级或“可能有权限”。

operations search

turing-cli operations search [flags]

按关键字在用户、部门和 client 中模糊搜索。它只返回身份字段,不返回费用。

参数	默认值	说明
-q, --q QUERY	空	模糊关键字;为空时列出当前权限可见的用户
--start DATE	当月 1 号	起始日期,格式 YYYY-MM-DD,按北京时间解释
--end DATE	今天	结束日期,格式 YYYY-MM-DD,包含当天
--limit N	50	分页大小,有效范围 1-500
--offset N	0	分页偏移
--include-admin	false	包含 admin 服务账号
--include-relay	false	仅让人维度的用量探活包含 Relay;不改变身份搜索结果
-h, --help		查看命令帮助

搜索维度:

维度	说明
username	用户名
email	邮箱
realname	姓名
employee_id	工号
oa_path	完整部门路径(任意深度,如 鸿鹄实验室/云与物联技术中心/AI应用开发部);path 字段给出有序组件,同名部门按路径区分;是否返回以 capabilities 为准
client	应用 / client / 计费租户

示例:

turing-cli operations search -q zhang
turing-cli operations search -q 鸿鹄 --limit 100
turing-cli operations search --start 2026-05-01 --end 2026-05-27 -q san.zhang

has_usage_in_window 只有在人维度命中时才是真实探活。部门和 client 命中恒为 false,表示“未探活 / 未知”,不代表没有用量;请继续调用 dashboards 查询实际花费。

operations dashboards

turing-cli operations dashboards --type TYPE --value VALUE [flags]

按 type/value 精确查询用量、费用和明细拆分。默认只返回 summary;需要 by_* 明细时用 --include 或 --all。

参数	必填	默认值	说明
--type TYPE	是	空	查询主体;见下方 --type 表
--value VALUE	条件必填	空	resource value;精确值,大小写敏感;platform 不需要
--start DATE	否	当月 1 号	起始日期,格式 YYYY-MM-DD,按北京时间解释
--end DATE	否	今天	结束日期,格式 YYYY-MM-DD,包含当天
--include LIST	否	空	数据拆分,逗号分隔;通常只返回 summary,条件默认项以 capabilities 为准
--include-relay	否	false	常规查询包含 Relay;仅在 capabilities 允许时使用
--all	否	false	返回全部允许的普通拆分;不会隐式包含 Relay
-h, --help	否		查看命令帮助

当前 platform 在完全省略 --include、窗口不超过 366 天且 capability 允许时,会按 default_includes 返回 by_billing_pool;调用方不要把这项条件默认值硬编码为永久规则。

查询主体 --type

--type 只表示“查谁”,每次只能选一个。有效值以 CLI 的 validResourceTypes 为准:

主体家族	type	value
person	username	用户名,如 san.zhang
person	email	邮箱
person	realname	姓名
person	employee_id	工号
org	oa_path	完整部门路径,任意深度;search 的部门命中直接可用;是否可查以 capabilities 为准
org	ldap_1 / ldap_2 / ldap_3	旧版按层级部门名;同名部门会跨子树合并,新查询建议用 oa_path
client	client	client 名称,如 co-patent
platform	platform	不需要 --value;授权的平台常规用量,默认排除 Relay,并非无条件所有 client
API Key	api_key_id	非敏感的 Key ID,如 ak_xxx;不要传 sk-... 密钥

api_key_id scope 用于一把具体 Key,当前可请求 by_service 和 by_day。是否可查以 capabilities 的 API Key target grant 为准;仅知道一个 api_key_id 不会绕过后端鉴权。

数据拆分 --include

--include 表示“怎么拆”,可以逗号分隔选择多个:

include	说明	兼容性
by_client	按 client 拆分;platform 下是各 client 排名	person / org / client / platform
by_day	按北京时间日期拆分	通用,包含 API Key scope
by_user	按用户拆分	仅 org / client;person 本身就是 1 人,platform 不返回
by_apikey	按 API Key 拆分;每行带可为空的 api_key_id;默认额度仍合并为 (default),自定义按名字(无名为 (unnamed)),只显示未删除的	仅 person / client(须锁定单个主体);org / platform / API Key 不返回
by_service	按模型或服务拆分	通用,包含 API Key scope
by_region	按地区 / 环境拆分	仅 client / platform
by_channel	按计费池粗拆(首选):portal vs api_key(再分 turingclaw / aicoding / other);固定 4 行,合计恒等于 summary.bill_usd	person / org / client / platform
by_billing_pool	按成本来源拆分;是否允许及条件默认值以 capabilities 为准。其 relay 成本池与 Relay client 查询范围不是同一维度	capability 控制
by_tool	已废弃的兼容壳:portal / turingclaw / aicoding 三行镜像 by_channel,other 组填 unclassified;新用法一律用 by_channel	person / org / client / platform
all	返回全部允许的普通拆分;不会隐式包含 Relay	仍受 capability 和维度兼容性约束

description / display_name 只在 client 维度或 by_client 行中出现。

指标

summary 始终返回这些指标;各拆分行按 API schema 返回对应字段:

指标	含义
bill_usd	花费,单位 USD （旧名 total / total_usd，兼容别名，2026-08-05 后移除）
request_count	请求数
user_count	去重活跃用户数;platform summary 为 null
tokens	token 总量
input_tokens / output_tokens	input / output token

权威费用、请求数和 token 指标对所有查询主体都跨 cn_live、cn_test、eu_live、sg_live 汇总。by_region 和 region,service 仅限 client / platform,这是地区拆分的适用范围限制,不表示 person、org 或 API Key 的总量只统计中国正式环境。

常用查询

个人总量,并按计费池、模型和 client 拆分。portal / API Key 花费从 by_channel 读取,不是单独的过滤条件:

turing-cli operations dashboards \
  --type username \
  --value san.zhang \
  --include by_channel,by_service,by_client

先列出个人名下的 API Key:

turing-cli operations dashboards \
  --type username \
  --value san.zhang \
  --include by_apikey

by_apikey 的每一行都包含可为空的 api_key_id;by_apikey_truncated=true 时只展示花费 top 100 行。可单独识别的 Key 会返回非敏感的 ak_... ID,可继续查看该 Key 的模型和日期拆分:

turing-cli operations dashboards \
  --type api_key_id \
  --value ak_xxx \
  --include by_service,by_day

name="(default)" 仍表示多个默认额度 Key 的聚合桶,其 api_key_id 为 null,这一个聚合行本身不能作为具体 Key 下钻。如果已从 Key 管理能力取得某把默认 Key 的明确 ak_... ID,仍可直接按该 ID 查询。name="(unnamed)" 只是 Key 没有显示名称;如果该行带 api_key_id,仍可按 ID 下钻。

client 总量,并按地区、模型和用户拆分:

turing-cli operations dashboards \
  --type client \
  --value co-patent \
  --include by_region,by_service,by_user \
  --start 2026-05-01 \
  --end 2026-05-31

按 email 查个人:

turing-cli operations dashboards \
  --type email \
  --value san.zhang@tcl.com

部门维度(用 search 部门命中返回的完整路径):

turing-cli operations dashboards \
  --type oa_path \
  --value "鸿鹄实验室/云与物联技术中心/AI 算法平台部" \
  --start 2026-05-01 \
  --end 2026-05-27

全平台总额 + 各产业排名:

turing-cli operations dashboards --type platform --include by_client

Relay 查询范围与 usage_scope

search 的人维度探活、dashboards 和 grouped-usage 默认排除 Relay 的费用、请求、token 和人数。只有用户明确要求,且 capabilities 的 query_options.relay.allowed=true 时才传:

turing-cli operations dashboards --type platform --include-relay
turing-cli operations grouped-usage \
  --type platform \
  --group-by client,service \
  --include-relay

CLI flag 是 --include-relay,对应 Backend 参数 include_relay=true。精确查询 Relay client 或归属于 Relay 的 api_key_id 时,Backend 会强制纳入。

每个带用量范围的响应都应检查:

{
  "usage_scope": {
    "relay": {
      "client": "efficiency-center",
      "requested": false,
      "included": false,
      "forced": false
    }
  }
}

• requested:调用方是否显式要求包含 Relay。
• included:应用默认值和强制规则后的最终查询范围;不表示一定存在非零 Relay 用量。
• forced:是否因为精确 Relay client / API Key 目标而由 Backend 强制纳入。

页面面向用户时称为 “Relay”;efficiency-center 是当前响应中的技术 client 标识。by_billing_pool.relay 是订阅成本池,和上述 Relay client scope 是两个不同业务轴。老响应没有 usage_scope 时,只能说明“范围未自描述”,不能自行猜测。

operations grouped-usage

turing-cli operations grouped-usage --type TYPE --group-by PAIR [flags]

在一个已鉴权的查询主体内返回二维分组结果。它与 dashboards --include 的多份独立一维列表不同:例如 service,day 的每一行同时表示一个 Service 在某一天的指标。

参数	必填	默认值	说明
--type TYPE	是	空	查询主体;与 dashboards 相同,包含 api_key_id
--value VALUE	条件必填	空	除 platform 外必填;精确值,大小写敏感
--group-by PAIR	是	空	二维组合;见下表,每次只能选一组
--start DATE	否	月初	起始日期,格式 YYYY-MM-DD,按北京时间解释;只传 --end 时取结束日期所在月的 1 号
--end DATE	否	今天	结束日期,格式 YYYY-MM-DD,包含当天
--limit N	否	100	分页大小,有效范围 1-1000;不传或传 0 时 CLI 省略参数并使用服务端默认
--offset N	否	0	分页偏移,必须大于等于 0;不传或传 0 时 CLI 省略参数并使用服务端默认
--include-relay	否	false	包含 Relay;默认排除,精确 Relay 目标由 Backend 强制纳入
-h, --help	否		查看命令帮助

--start 和 --end 都包含当天。服务端补齐默认值后,grouped usage 的查询窗口最多为 366 天;超过限制返回 HTTP 400。

首版严格支持以下组合:

--group-by	适用查询主体	回答的问题
service,day	person / org / client / platform / API Key	一个主体的各 Service 随日期如何变化
client,service	platform	各 client 分别使用了哪些 Service
region,service	client / platform	各地区和环境分别使用了哪些 Service

上述三种组合的反序也可输入,CLI 会规范化为表中的顺序,例如 day,service 会转换为 service,day;其他组合和更多维度会在请求前被拒绝。当前不支持 User × Service,选中一个人时应使用该人的 dashboards --include by_service,选中一把 Key 时使用该 Key 的 dashboards --include by_service。

查看一把 Key 的 Service 日趋势:

turing-cli operations grouped-usage \
  --type api_key_id \
  --value ak_xxx \
  --group-by service,day \
  --start 2026-07-01 \
  --end 2026-07-14

查看全平台的 Client × Service:

turing-cli operations grouped-usage \
  --type platform \
  --group-by client,service \
  --limit 100

查看一个 client 的 Region × Service:

turing-cli operations grouped-usage \
  --type client \
  --value co-patent \
  --group-by region,service \
  --limit 100

响应为分页后的 JSON。total 是分页前命中的分组行数,不是费用;limit / offset 是本次请求采用的分页值。各行的指标位于行顶层,维度值位于 dimensions:

{
  "dimension": {
    "resource_type": "client",
    "resource_value": "co-patent"
  },
  "group_by": ["region", "service"],
  "total": 1,
  "limit": 100,
  "offset": 0,
  "rows": [
    {
      "dimensions": {
        "service": "turing/gpt-5.5",
        "region": {
          "code": "cn-north-1",
          "environment": "live",
          "label": "中国正式"
        }
      },
      "bill_usd": 12.5,
      "request_count": 100,
      "tokens": 60000,
      "input_tokens": 50000,
      "output_tokens": 10000
    }
  ]
}

顶层字段:

字段	含义
dimension	本次查询的主体,包含 resource_type / resource_value 及可选展示信息
group_by	规范化后的二维组合数组
total	应用分页前命中的分组总行数,不是费用
limit / offset	服务端实际采用并回显的分页值
rows	当前页分组行;每行包含 dimensions 和用量指标
org_filter	仅部门主体(oa_path 及旧版 ldap_1 / ldap_2 / ldap_3)返回的可选部门名单诊断;其它主体省略该字段

部门主体使用与 dashboard 相同的最多 20,000 人名单上限。此时 org_filter 的语义为:

{
  "org_filter": {
    "matched_users": 20000,
    "truncated": true,
    "truncation_cap": 20000
  }
}

• matched_users: 本次实际进入聚合的用户名数量。
• truncated: 是否因部门名单超过上限而被截断。
• truncation_cap: 截断时使用的上限;未截断时省略。
• os_users_covered: 部门人数超过 OpenSearch 上限时出现,表示 by_channel / by_billing_pool 只覆盖前这么多人(费用汇总仍覆盖全名单)。

当 truncated=true 时,结果只覆盖最多 20,000 名已解析用户,不能视为该部门的完整用量。

部分返回标记

列表被上限截断时,响应会显式说明,不会静默返回部分数据:

位置	标记	含义
search 响应顶层	truncated: true	底层扫描触顶,total 只是下界;用更具体的关键字重查
dashboard 响应	by_apikey_truncated: true	by_apikey 只展示花费 top 100 行,不是全部 Key
部门主体	org_filter.truncated / os_users_covered	名单截断 / OpenSearch 拆分覆盖不足
grouped-usage	total vs limit / offset	total 是分页前总行数,大于返回行数即有更多页

TypeScript 响应参考:

interface GroupedUsageRegion {
  code: string;
  environment: string;
  label: string;
}

interface GroupedUsageDimensions {
  service?: string;
  day?: string; // YYYY-MM-DD,北京时间
  client?: string;
  client_display_name?: string;
  region?: GroupedUsageRegion;
}

interface GroupedUsageRow {
  dimensions: GroupedUsageDimensions;
  bill_usd: number;
  request_count: number;
  tokens: number;
  input_tokens: number;
  output_tokens: number;
}

interface GroupedUsageResponse {
  dimension: {
    resource_type: string;
    resource_value: string;
    display_name?: string;
    description?: string;
  };
  group_by:
    | ["service", "day"]
    | ["client", "service"]
    | ["region", "service"];
  total: number;
  limit: number;
  offset: number;
  rows: GroupedUsageRow[];
  org_filter?: {
    matched_users: number;
    truncated: boolean;
    truncation_cap?: number;
  };
}

dimensions 只返回当前组合相关的字段:

组合	dimensions 字段
service,day	service, day;day 为北京时间的 YYYY-MM-DD
client,service	client, service,可选 client_display_name
region,service	service, region;region 是 {code, environment, label} 对象,中国正式与测试环境是不同的分组值

grouped usage 采用完整性优先策略。cn_live、cn_test、eu_live、sg_live 中任一预期地区数据源查询失败时,整个请求返回 HTTP 503,不会静默返回缺少部分地区的 200 结果。

兼容矩阵

下表是普通一维拆分的结构兼容性;实际允许项始终以 capabilities 对目标 action 返回的 allowed_includes 为准。

查询主体 --type	by_client	by_day	by_user	by_apikey	by_service	by_region	by_channel	by_tool
person: username / email / realname / employee_id	✓	✓	-	✓	✓	-	✓	✓
org: oa_path(旧版 ldap_1 / ldap_2 / ldap_3 同)	✓	✓	✓	-	✓	-	✓	✓
client: client	✓	✓	✓	✓	✓	✓	✓	✓
platform: platform	✓	✓	-	-	✓	✓	✓	✓
API Key: api_key_id	-	✓	-	-	✓	-	-	-

API Key scope 请显式使用 --include by_service,by_day,不要使用 --all 请求不适用的拆分。

by_billing_pool 是 capability 控制的成本来源拆分,不应从上表自行推断权限。

输出字段

字段	含义
dimension.resource_type / dimension.resource_value	本次查询的账号维度
summary.bill_usd	总花费,单位 USD;费用以后端计费数据为准
summary.request_count	请求数
summary.tokens	token 总量
summary.input_tokens / summary.output_tokens	input / output token
summary.user_count	去重活跃用户数;platform 为 null
usage_scope	本次 Relay 范围的 requested / included / forced;included 不证明有非零 Relay 命中
org_filter	部门主体的名单诊断:matched_users、truncated 和可选 truncation_cap;dashboard 与 grouped usage 语义一致,名单上限为 20,000 人
by_apikey	按 API Key 拆分(仅 person / client);每行包含可为空的 api_key_id、name(自定义 key 名 / (default) / (unnamed))和用量指标;(default) 聚合桶的 ID 为 null;只含未删除的 Key
by_service	按服务 / 模型拆分
by_region	按地区 + 环境拆分
by_channel	按计费池粗拆:portal(Portal 应用池 + 旧版 Portal 网页流量)行 group 为 null;api_key 行按 group 分 turingclaw / aicoding(coding 工具 tag 含 cowork,及 TCoder / Cline 等 UA 识别的 coding agent)/ other(其余含 openclaw、办公插件、生图视频、直接 API 调用);4 行合计恒等于 summary.bill_usd,跨地区差额计入 other
by_billing_pool	capability 控制的 direct / relay 成本来源拆分;其中 relay 不等于 Relay client 查询范围
by_tool	已废弃的兼容壳:portal / turingclaw / aicoding 三行镜像 by_channel
by_tool_scope	by_tool 的标签来源范围;跨地区 client / platform 查询时需结合 unclassified 理解
unclassified	by_channel other 组渲染进旧字段:无 tag 流量、openclaw、办公插件、生图视频、直接 API 调用(含走 portal client 的 sk- API Key 流量)

权限自说明

调用方不需要知道或推断角色与内部授权规则。先调用 turing-cli operations capabilities,再严格按返回的 authorization.targets、目标 action、allowed_includes 和 allowed_group_by 规划查询。没有返回的目标或动作就不调用;OA 信息仅用于解释当前身份,不扩大数据范围。

platform 完全省略 --include 时是否条件默认返回 by_billing_pool,同样以当前调用者 capabilities 的 default_includes.by_billing_pool 为准。

API Key scope 会先按 Key 归属鉴权;知道 ak_... ID 本身不代表有查看权限。越权查询会返回 HTTP 403。每次调用都会在 stderr 输出 [trace] trace_xxx,stdout 保持纯 JSON。

排错

错误	处理
HTTP 400	检查日期顺序和窗口长度、--include、--group-by 及组合适用的查询主体;grouped usage 最多查询 366 天
HTTP 422	检查日期格式和分页范围;grouped usage 的 limit 有效范围为 1-1000
HTTP 403	停止当前目标,重新读取 capabilities,不要换维度反复探测;保留 stderr 中的 trace
HTTP 404	资源不存在;普通主体先用 operations search,具体 Key 从可见范围的 by_apikey 取得 ID
HTTP 503	后端或预期地区数据源不可用;grouped usage 不返回 partial 结果,请稍后重试并保留 trace
connection refused / timeout	检查网络、代理配置或后端服务状态