Operations
turing-cli operations 用于查询 Turing Platform/Core 的用量、费用、token、模型和请求明细。
在智能体工作流中,可以配合 SkillHub 上的 Turing Operations skill 使用本页命令;如果还需要先读取账单、表格、PDF 或 PPT 材料,可搭配 Documents skill 调用 turing-cli documents convert。也可以按自己使用的智能体或 IDE 规范自行配置自有 skills。
查询模型可以理解为:
账号维度 (--type, 选 1 个) × 数据拆分 (--include, 可选多个) + 指标
Portal / CoWork(turing-claw, openclaw) 不是 --type,也不是查询过滤条件;它们是 by_tool 返回结果里的 bucket。比如“某个人的 Portal / CoWork(turing-claw, openclaw) 用量”应先用 --type username --value X 查这个人的总用量,再从 by_tool 里读取对应 bucket。API Key 的花费拆分则用 --include by_apikey(仅 person / client 维度)。
查询流程
大多数查询分两步:
operations search -> 找到准确的 type/value
operations dashboards -> 查询 summary 或 by_* 明细
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 服务账号 |
-h, --help | 查看命令帮助 |
搜索维度:
| 维度 | 说明 |
|---|---|
username | 用户名 |
email | 邮箱 |
realname | 姓名 |
employee_id | 工号 |
ldap_1 / ldap_2 / ldap_3 | 部门层级 |
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 |
--all | 否 | false | 返回全部拆分,等价于 --include all |
-h, --help | 否 | 查看命令帮助 |
账号维度 --type
--type 只表示“查谁”,每次只能选一个。有效值以 CLI 的 validResourceTypes 为准:
| 账号家族 | type | value |
|---|---|---|
| person | username | 用户名,如 san.zhang |
| person | email | 邮箱 |
| person | realname | 姓名 |
| person | employee_id | 工号 |
| org | ldap_1 / ldap_2 / ldap_3 | 部门名 |
| client | client | client 名称,如 co-patent |
| platform | platform | 不需要 --value;全平台所有 client 汇总 |
数据拆分 --include
--include 表示“怎么拆”,可以逗号分隔选择多个:
| include | 说明 | 兼容性 |
|---|---|---|
by_client | 按 client 拆分;platform 下是各 client 排名 | 通用 |
by_day | 按北京时间日期拆分 | 通用 |
by_user | 按用户拆分 | 仅 org / client;person 本身就是 1 人,platform 不返回 |
by_apikey | 按 API Key 拆分;默认额度合并为 (default),自定义按名字(无名为 (unnamed)),只显示未删除的 | 仅 person / client(须锁定单个主体);org / platform 不返回 |
by_service | 按模型或服务拆分 | 通用 |
by_region | 按地区 / 环境拆分 | 仅 client / platform |
by_tool | 按工具入口拆分;Portal / CoWork(turing-claw, openclaw) / AI Coding 等在这里看 | 通用 |
all | 返回全部拆分 | 仍受上方兼容性约束 |
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 |
常用查询
个人总量,并按工具、模型和 client 拆分。Portal / CoWork(turing-claw, openclaw) 从 by_tool bucket 读取,不是单独的过滤条件:
turing-cli operations dashboards \
--type username \
--value san.zhang \
--include by_tool,by_service,by_client
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
部门维度:
turing-cli operations dashboards \
--type ldap_2 \
--value "AI 算法平台部" \
--start 2026-05-01 \
--end 2026-05-27
全平台总额 + 各产业排名:
turing-cli operations dashboards --type platform --include by_client
兼容矩阵
account --type | by_client | by_day | by_user | by_service | by_region | by_tool |
|---|---|---|---|---|---|---|
person: username / email / realname / employee_id | ✓ | ✓ | - | ✓ | - | ✓ |
org: ldap_1 / ldap_2 / ldap_3 | ✓ | ✓ | ✓ | ✓ | - | ✓ |
client: client | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
platform: platform | ✓ | ✓ | - | ✓ | ✓ | ✓ |
输出字段
| 字段 | 含义 |
|---|---|
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 |
by_apikey | 按 API Key 拆分(仅 person / client);每行 name(自定义 key 名 / (default) / (unnamed))+ bill_usd 等指标;只含未删除的 key |
by_service | 按服务 / 模型拆分 |
by_region | 按地区 + 环境拆分 |
by_tool | 按工具 / 产品线拆分 |
by_tool_scope | by_tool 的标签来源范围;跨地区 client / platform 查询时需结合 unclassified 理解 |
unclassified | 未被工具桶覆盖的剩余流量 |
权限范围
| 角色 | 可查范围 |
|---|---|
| self | 任意已登录用户可查自己 |
| CLIENT_ADMIN | 可查自己管理的 client |
| OPERATOR(图灵平台管理员) | 可查别人、部门维度、其它 client 和 platform |
如果你是图灵平台管理员(OPERATOR),查询
platform维度时即使不带--include,也会默认返回额外的平台级拆分视角,不止总额;其它角色看不到这部分。
越权查询会返回 HTTP 403。每次调用都会在 stderr 输出 [trace] trace_xxx,stdout 保持纯 JSON。
排错
| 错误 | 处理 |
|---|---|
HTTP 403 | API Key 权限不足 |
HTTP 404 | 资源不存在;先用 operations search 找正确写法 |
HTTP 503 | 后端短暂不可用;稍后重试并保留 trace |
connection refused / timeout | 检查网络、代理配置或后端服务状态 |