smartcheck-cli 0.1.0__tar.gz → 0.1.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,7 +1,7 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: smartcheck-cli
3
- Version: 0.1.0
4
- Summary: SmartCheck 账号授权与通话管理命令行
3
+ Version: 0.1.1
4
+ Summary: SmartCheck 账号授权、通话管理、洞察与质检配置命令行
5
5
  Requires-Python: >=3.11
6
6
  Requires-Dist: requests<3,>=2.32
7
7
  Requires-Dist: filelock<4,>=3.13
@@ -4,8 +4,8 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "smartcheck-cli"
7
- version = "0.1.0"
8
- description = "SmartCheck 账号授权与通话管理命令行"
7
+ version = "0.1.1"
8
+ description = "SmartCheck 账号授权、通话管理、洞察与质检配置命令行"
9
9
  requires-python = ">=3.11"
10
10
  dependencies = ["requests>=2.32,<3", "filelock>=3.13,<4", "keyring>=25,<26"]
11
11
 
@@ -53,8 +53,14 @@ def confirm(client, pair, args, body):
53
53
  info = client.request("GET", "/call-fields/" + segment(target), token=pair["access_token"])
54
54
  message = (f"删除后不可恢复,字段键也不能再次使用。如果只是暂时不需要,建议停用。"
55
55
  f"确定删除以下字段? {info['label']}({target},{info['field_type']})")
56
+ elif args.group == "asr-settings":
57
+ message = "覆盖本企业的识别语种和整份即时热词,下次提交录音转写时生效。"
56
58
  else:
57
59
  message = f"保存话者识别方式 {body.get('mode', '')},仅对之后首次开始转写的录音生效。"
60
+ confirm_operation(client, pair, message)
61
+
62
+
63
+ def confirm_operation(client, pair, message):
58
64
  note(f"{client.host} · {pair['profile']['enterprise_name']}({pair['profile']['tenant_id']})\n{message} 输入 y 继续,默认取消。")
59
65
  if sys.stdin.readline().strip() != "y":
60
66
  raise Error("已取消", 1)
@@ -62,7 +68,7 @@ def confirm(client, pair, args, body):
62
68
 
63
69
  def run_business(client, vault, args):
64
70
  group, action = args.group, args.action
65
- guarded = action == "delete" or (group, action) == ("speaker-roles", "set")
71
+ guarded = action in ("delete", "set")
66
72
  path = "/" + group
67
73
  if hasattr(args, "identifier"):
68
74
  path += "/" + segment(args.identifier)
@@ -92,6 +98,17 @@ def run_business(client, vault, args):
92
98
  params[key] = value
93
99
  if args.direction:
94
100
  params["direction"] = args.direction
101
+ if bool(args.tag_field) != bool(args.tag):
102
+ raise Error("--tag-field 与 --tag 须同时使用")
103
+ if args.tag:
104
+ tags = list(dict.fromkeys(tag.strip() for tag in args.tag))
105
+ if not all(tags):
106
+ raise Error("标签不能为空")
107
+ if len(tags) > 10:
108
+ raise Error("最多 10 个 --tag")
109
+ if any(len(tag) > 50 for tag in tags):
110
+ raise Error("标签最多 50 个字符")
111
+ params.update(tag_field=args.tag_field, tag=tags)
95
112
  elif action == "download-recording":
96
113
  path += "/recording/" + segment(args.source) + "/audio"
97
114
  output = args.output
@@ -104,6 +121,11 @@ def run_business(client, vault, args):
104
121
  pair = current(client, vault)
105
122
  if group != "calls" and pair["profile"]["role"] != "admin":
106
123
  raise Error("无权访问系统设置", 3, code="FORBIDDEN", status=403)
124
+ if params and "tag_field" in params:
125
+ # The list API silently drops an unusable tag field; the CLI reports it instead.
126
+ fields = client.request("GET", "/calls/tag-fields", token=pair["access_token"])
127
+ if params["tag_field"] not in {field["field_key"] for field in fields}:
128
+ raise Error("标签字段不存在或不可筛选")
107
129
  if group == "accounts" and action in ("create", "update"):
108
130
  body = {key: getattr(args, key) for key in ("name", "email", "phone") if getattr(args, key) is not None}
109
131
  if action == "create":
@@ -127,3 +149,47 @@ def run_business(client, vault, args):
127
149
  result["generated_password"] = generated
128
150
  note("请立即保存该密码")
129
151
  return result
152
+
153
+
154
+ def reidentify_calls(client, vault, args):
155
+ pair = current(client, vault)
156
+ profile = pair["profile"]
157
+ if profile["role"] != "admin":
158
+ raise Error("无权访问系统设置", 3, code="FORBIDDEN", status=403)
159
+ config = client.request("GET", "/speaker-roles", token=pair["access_token"])
160
+ if not config["configured"]:
161
+ raise Error("尚未配置话者识别,请先在网页「系统设置 → 话者识别」保存配置")
162
+ total = len(args.call_ids)
163
+ mode = {"channel": "声道标注", "decision": "决策模型", "llm": "LLM 识别"}[config["mode"]]
164
+ if config["mode"] == "decision":
165
+ mode += ",LLM 兜底:" + ("开" if config["fallback"] else "关")
166
+ note(f"{client.host} · {profile['enterprise_name']}({profile['tenant_id']})")
167
+ note(f"按当前话者识别配置重新识别 {total} 通通话的话轮角色\n识别方式:{mode}")
168
+ note("只更新角色,不重新转写,原文和时间戳不变。识别结果将替换通话详情中当前显示的角色。")
169
+ if not args.yes:
170
+ note("输入 y 继续,默认取消。")
171
+ if sys.stdin.readline().strip() != "y":
172
+ raise Error("已取消", 1)
173
+
174
+ labels = {"reidentified": "已识别", "skipped": "已跳过", "failed": "失败", "unknown": "结果未知"}
175
+ counts = dict.fromkeys(labels, 0)
176
+ results = []
177
+ for index, call_id in enumerate(args.call_ids, 1):
178
+ try:
179
+ # Batches can outlive an access token. Keep the confirmed tenant and account.
180
+ active = current(client, vault)
181
+ if any(active["profile"][k] != profile[k] for k in ("tenant_id", "username", "role")):
182
+ raise Error("登录账号已变更")
183
+ result = client.request("POST", f"/calls/{segment(call_id)}/reidentify-speakers",
184
+ token=active["access_token"])
185
+ if not isinstance(result, dict) or result.get("status") not in ("reidentified", "skipped"):
186
+ raise Error("请求结果未知,请先查询确认后再决定是否重试", 4)
187
+ except Error as error:
188
+ uncertain = error.exit_code == 4
189
+ result = dict(call_id=call_id, status="unknown" if uncertain else "failed",
190
+ reason=error.args[0] if uncertain else str(error))
191
+ status = result["status"]
192
+ counts[status] += 1
193
+ results.append(result)
194
+ note(f"({index}/{total}) {call_id} {labels[status]}")
195
+ return {"results": results, "counts": counts}
@@ -46,12 +46,17 @@ class Client:
46
46
  self.session = requests.Session()
47
47
  self.session.trust_env = False
48
48
 
49
- def request(self, method, path, *, token=None, params=None, body=None, output=None, force=False):
50
- reading = method == "GET"
49
+ def request(self, method, path, *, token=None, params=None, body=None, output=None, force=False,
50
+ upload=None, data=None, read_only=False):
51
+ reading = method == "GET" or read_only
51
52
  attempts = 3 if reading else 1
52
53
  for attempt in range(attempts):
53
54
  try:
54
- with self.session.request(method, self.base + path, params=params, json=body,
55
+ files = None
56
+ if upload is not None:
57
+ upload.seek(0)
58
+ files = {"file": (Path(upload.name).name, upload)}
59
+ with self.session.request(method, self.base + path, params=params, json=body, files=files, data=data,
55
60
  headers={"Authorization": "Bearer " + token} if token else {},
56
61
  timeout=self.timeout, allow_redirects=False,
57
62
  stream=output is not None) as response:
@@ -0,0 +1,260 @@
1
+ """Commands for the tenant's insight configuration."""
2
+
3
+ import json
4
+ from pathlib import Path
5
+
6
+ from .auth import current
7
+ from .commands import confirm_operation, read_object
8
+ from .http import Error, segment
9
+
10
+
11
+ GROUPS = {
12
+ "tag-catalog": ("标签管理", [
13
+ ("list", "列出标签体系", ""), ("get", "读取体系及全部下级目录项", "1"),
14
+ ("create", "新建体系或下级目录项", "--json-file tag.json"),
15
+ ("update", "编辑目录项", "2 --json-file tag.json"),
16
+ ("enable", "启用标签", "4"), ("disable", "停用标签", "4"),
17
+ ("delete", "删除目录项", "4 --yes"),
18
+ ]),
19
+ "product-models": ("品型管理", [
20
+ ("list", "列出产品系列与型号", ""), ("get", "读取品型", "1"),
21
+ ("create", "新建系列或型号", "--json-file model.json"),
22
+ ("update", "保存品型名称、启用状态、别名与属性", "1 --json-file model.json"),
23
+ ("delete", "删除品型", "1 --yes"),
24
+ ]),
25
+ "insight-datasets": ("自定义数据集管理", [
26
+ ("list", "列出数据集", ""), ("get", "读取定义与版本", "ds_store"),
27
+ ("create", "创建数据集", "--json-file dataset.json"),
28
+ ("update", "按基准版本保存定义", "ds_store --json-file definition.json"),
29
+ ("query", "查询记录", "ds_store --json-file query.json"),
30
+ ("add-record", "按基准版本新增记录", "ds_store --json-file row.json"),
31
+ ("update-record", "按记录编号和基准版本编辑记录", "ds_store 1 --json-file row.json"),
32
+ ("enable", "启用数据集", "ds_store"), ("disable", "停用数据集", "ds_store"),
33
+ ("delete", "删除数据集", "ds_store --yes"),
34
+ ("workbook-inspect", "读取 Excel 工作表和表头", "--file stores.xlsx"),
35
+ ("workbook-preview", "校验并预览导入,返回提交令牌", "--file stores.xlsx --json-file plan.json"),
36
+ ("workbook-commit", "使用同一文件、方案和预览令牌确认导入或替换", "--file stores.xlsx --json-file plan.json --token TOKEN --yes"),
37
+ ("export", "导出当前版本的 Excel", "ds_store --output stores.xlsx"),
38
+ ]),
39
+ "tagging-code": ("打标代码管理", [
40
+ ("list", "搜索并分页列出代码", "--keyword 意向 --page 1"), ("get", "读取代码、配置和版本", "intent"),
41
+ ("create", "保存新代码", "--json-file code.json --source-file intent.py"),
42
+ ("update", "按版本保存代码", "intent --json-file update.json --source-file intent.py"),
43
+ ("delete", "删除代码", "intent --yes"),
44
+ ]),
45
+ "tagging-tasks": ("洞察打标任务", [
46
+ ("list", "按名称查询自动任务或临时任务", "--tab temp --keyword 意向"),
47
+ ("options", "查看筛选字段、可绑定代码和模型通道", ""),
48
+ ("get", "读取任务配置、状态和执行统计", "12"),
49
+ ("preview", "统计临时任务命中通话数及已有系统值、人工值的通话数", "--json-file preview.json"),
50
+ ("create", "创建并启用自动任务,或启动一次临时批次", "--tab temp --json-file task.json"),
51
+ ("update", "保存自动任务的完整配置", "12 --json-file task.json"),
52
+ ("enable", "启用自动任务", "12"), ("disable", "停用自动任务", "12"),
53
+ ("cancel", "取消临时批次中尚未开始的会话", "12 --yes"),
54
+ ("retry", "使用临时批次原快照重试未完成会话", "12 --yes"),
55
+ ("runs", "按状态或通话 ID 查询执行记录", "12 --status failed"),
56
+ ("run-detail", "查看单通执行结果、证据和失败原因", "12 9"),
57
+ ("delete", "删除打标任务", "12 --yes"),
58
+ ]),
59
+ "insight-fields": ("洞察字段设置", [
60
+ ("list", "按顺序列出洞察字段", ""), ("get", "按字段键读取定义", "intent"),
61
+ ("create", "新增洞察字段", "--json-file field.json"),
62
+ ("update", "保存字段定义", "intent --json-file update.json"),
63
+ ("enable", "启用字段", "intent"), ("disable", "停用字段", "intent"),
64
+ ("reorder", "排列全部自定义洞察字段", "intent budget"),
65
+ ("candidates", "查询标签、品型或数据集候选项", "--json-file candidates.json"),
66
+ ("delete", "删除字段", "intent --yes"),
67
+ ]),
68
+ }
69
+
70
+ READ_ACTIONS = {"list", "get", "candidates", "query", "export", "options", "preview", "runs", "run-detail"}
71
+ BODY_ACTIONS = {"create", "update", "query", "add-record", "update-record", "candidates",
72
+ "preview", "workbook-preview", "workbook-commit"}
73
+ TARGET_ACTIONS = {"get", "update", "enable", "disable", "delete", "query", "add-record", "update-record", "export",
74
+ "cancel", "retry", "runs", "run-detail"}
75
+
76
+
77
+ def role(group, action):
78
+ if group == "tagging-tasks" and (action == "preview" or action not in READ_ACTIONS):
79
+ return "管理员"
80
+ if action in READ_ACTIONS:
81
+ return "有洞察查看权限的账号"
82
+ return "管理员(洞察已启用)" if group == "tagging-code" else "有洞察编辑权限的账号"
83
+
84
+
85
+ def task_number(value):
86
+ try:
87
+ number = int(value)
88
+ except ValueError:
89
+ number = 0
90
+ if not 1 <= number <= 2**31 - 1:
91
+ raise Error("任务 ID、执行记录 ID 和页码须为 1 至 2147483647 的整数")
92
+ return number
93
+
94
+
95
+ def arguments(parser, group, action):
96
+ add = parser.add_argument
97
+ if action in TARGET_ACTIONS:
98
+ target = {"tag-catalog": "system_id" if action == "get" else "node_id", "product-models": "model_id",
99
+ "insight-fields": "field_key", "insight-datasets": "dataset_key", "tagging-code": "code_key",
100
+ "tagging-tasks": "task_id"}[group]
101
+ add("identifier", metavar=target, type=task_number if group == "tagging-tasks" else str,
102
+ help="当前企业的目标标识")
103
+ if action == "update-record":
104
+ add("number", type=int, metavar="number", help="query 返回的记录编号")
105
+ if action in BODY_ACTIONS:
106
+ add("--json-file", required=True, help="UTF-8 JSON 请求体或工作簿映射方案,示例见 guide")
107
+ if group in ("tagging-code", "tagging-tasks") and action in ("list", "runs"):
108
+ keyword = "通话 ID" if action == "runs" else "名称"
109
+ add("--keyword", default="", help=f"搜索{keyword}")
110
+ add("--page", type=task_number if group == "tagging-tasks" else int, default=1, help="页码,默认 1")
111
+ add("--per-page", type=int, choices=(20, 50, 100), default=20, help="每页条数,默认 20")
112
+ if group == "tagging-code" and action in ("create", "update"):
113
+ add("--source-file", help="从 UTF-8 Python 文件读取 source,覆盖 JSON 中的源码")
114
+ if group == "tagging-tasks":
115
+ if action in ("list", "create"):
116
+ add("--tab", choices=("auto", "temp"), required=action == "create", default="auto",
117
+ help="auto 为自动任务,temp 为临时批次;查询默认 auto,创建时必填")
118
+ if action == "list":
119
+ add("--exact", action="store_true", help="精确匹配任务名称")
120
+ if action == "runs":
121
+ add("--status", choices=("all", "pending", "running", "succeeded", "failed", "cancelled"),
122
+ default="all", help="执行记录状态,默认 all")
123
+ if action == "run-detail":
124
+ add("run_id", type=task_number, metavar="run_id", help="runs 返回的执行记录 ID")
125
+ if action == "reorder":
126
+ add("field_keys", nargs="+", metavar="field_key", help="按新顺序给出全部自定义字段键,系统预置字段固定在首位")
127
+ if action.startswith("workbook-"):
128
+ add("--file", required=True, help="本地 .xlsx 工作簿")
129
+ if action == "workbook-inspect":
130
+ add("--sheet", help="读取指定工作表的表头")
131
+ if action == "workbook-commit":
132
+ add("--token", required=True, help="同一工作簿和方案的预览令牌")
133
+ if action == "export":
134
+ add("--output", required=True, help="本地 .xlsx 目标文件")
135
+ add("--force", action="store_true", help="覆盖已有文件")
136
+ if action in ("delete", "workbook-commit", "cancel", "retry"):
137
+ add("--yes", action="store_true", help="确认执行,非交互环境必填")
138
+
139
+
140
+ def upload_workbook(client, pair, args, path, body):
141
+ action = args.action
142
+ data = {}
143
+ if action == "workbook-inspect":
144
+ if args.sheet is not None:
145
+ data["sheet"] = args.sheet
146
+ else:
147
+ data["plan"] = json.dumps(body, ensure_ascii=False)
148
+ if action == "workbook-commit":
149
+ data["token"] = args.token
150
+ if not args.yes:
151
+ target = body.get("dataset_key")
152
+ change = f"替换数据集 {target}" if target else f"创建数据集 {body.get('name', '')}"
153
+ confirm_operation(client, pair, f"确定使用 {args.file} {change}?")
154
+ source = Path(args.file)
155
+ if source.suffix.lower() != ".xlsx" or source.stat().st_size > 50 * 1024 * 1024:
156
+ raise Error("请选择不超过 50 MB 的 .xlsx 文件")
157
+ with source.open("rb") as workbook:
158
+ return client.request("POST", path + "/workbook/" + action.removeprefix("workbook-"),
159
+ upload=workbook, data=data, read_only=action != "workbook-commit",
160
+ token=pair["access_token"])
161
+
162
+
163
+ def run(client, vault, args):
164
+ group, action = args.group, args.action
165
+ path = "/insights/" + group
166
+ if action in TARGET_ACTIONS:
167
+ key = segment(str(args.identifier))
168
+ if (group, action) != ("insight-fields", "get"):
169
+ path += "/" + key
170
+ body = read_object(args.json_file) if action in BODY_ACTIONS else None
171
+ if getattr(args, "source_file", None):
172
+ try:
173
+ body["source"] = Path(args.source_file).read_text(encoding="utf-8")
174
+ except (OSError, UnicodeError) as exc:
175
+ raise Error("无法读取 UTF-8 Python 源文件") from exc
176
+ pair = current(client, vault)
177
+ options = {"token": pair["access_token"]}
178
+ if action == "delete" and not args.yes:
179
+ confirm_operation(client, pair, f"确定删除{GROUPS[group][0]}中的 {args.identifier}?")
180
+ if action.startswith("workbook-"):
181
+ return upload_workbook(client, pair, args, path, body)
182
+ if (group, action) == ("insight-fields", "get"):
183
+ catalog = client.request("GET", path, **options)
184
+ for field in catalog["fields"]:
185
+ if field["key"] == args.identifier:
186
+ return field
187
+ raise Error("洞察字段不存在", code="NOT_FOUND", status=404)
188
+ if group in ("tagging-code", "tagging-tasks") and action in ("list", "runs"):
189
+ if args.page < 1:
190
+ raise Error("页码须大于 0")
191
+ options["params"] = dict(q=args.keyword, page=args.page, pageSize=args.per_page)
192
+ if group == "tagging-tasks":
193
+ if action == "list":
194
+ options["params"].update(tab=args.tab, exact=args.exact)
195
+ elif action == "create":
196
+ options["params"] = {"tab": args.tab}
197
+ elif action in ("enable", "disable", "cancel", "retry"):
198
+ if action in ("cancel", "retry") and not args.yes:
199
+ change = "取消批次中尚未开始的会话" if action == "cancel" else "按批次原快照重试未完成会话"
200
+ confirm_operation(client, pair, f"任务 {args.identifier}:确定{change}?")
201
+ return client.request("POST", path + "/" + action, **options)
202
+ elif action in ("options", "preview", "runs"):
203
+ path += "/" + action
204
+ if action == "runs":
205
+ options["params"]["status"] = args.status
206
+ elif action == "run-detail":
207
+ path += f"/runs/{args.run_id}"
208
+ if action == "export":
209
+ if Path(args.output).exists() and not args.force:
210
+ raise Error("文件已存在,添加 --force 覆盖")
211
+ return client.request("GET", path + "/export", output=args.output, force=args.force, **options)
212
+ if action in ("enable", "disable"):
213
+ body = {"enabled": action == "enable"}
214
+ elif action == "reorder":
215
+ body = {"field_keys": args.field_keys}
216
+ path += "/_order"
217
+ elif action == "candidates":
218
+ path += "/_candidates"
219
+ elif action == "query":
220
+ path += "/query"
221
+ elif action == "add-record":
222
+ path += "/records"
223
+ elif action == "update-record":
224
+ path += f"/records/{args.number}"
225
+ methods = {"list": "GET", "get": "GET", "create": "POST", "update": "PUT", "delete": "DELETE",
226
+ "enable": "PATCH", "disable": "PATCH", "reorder": "PUT", "candidates": "POST",
227
+ "query": "POST", "add-record": "POST", "update-record": "PUT", "options": "GET",
228
+ "preview": "POST", "runs": "GET", "run-detail": "GET"}
229
+ return client.request(methods[action], path, body=body, read_only=action in READ_ACTIONS, **options)
230
+
231
+
232
+ def examples():
233
+ tag = {"name": "购车需求", "description": "客户提到的购车需求"}
234
+ model = {"name": "A 系列", "enabled": True, "aliases": ["系列 A"], "attributes": []}
235
+ field = {"name": "购车意向", "description": "客户表达的意向", "editable": True, "config": {}}
236
+ dataset = {"name": "门店", "meaning": "门店代码", "columns": [
237
+ {"key": "code", "name": "门店编码", "type": "text", "unique_code": True}]}
238
+ row = {"base_version": 1, "cells": {"code": "S001"}}
239
+ plan = {**dataset, "sheet": "门店", "mapping": {"code": 0}}
240
+ code = {"name": "意向摘要", "enabled": False, "output_fields": ["intent"],
241
+ "source": 'import insight\n\ndef run():\n insight.write("intent", "待确认")'}
242
+ preview = {"filters": {"direction": "inbound"}, "fields": ["intent"]}
243
+ task = {**preview, "name": "呼入购车意向", "kind": "llm",
244
+ "prompt": "根据 {{transcript}} 提取购车意向,以 JSON 返回 intent。", "mappings": {"intent": {"key": "intent"}}}
245
+ return {
246
+ "tag-catalog create": {**tag, "parent_id": None}, "tag-catalog update": tag,
247
+ "product-models create": {**model, "code": "series_a"}, "product-models update": model,
248
+ "insight-fields create": {**field, "key": "intent", "kind": "text"}, "insight-fields update": field,
249
+ "insight-fields candidates": {"kind": "model", "config": {"level": "series", "multiple": False}, "page": 1},
250
+ "insight-datasets create": dataset, "insight-datasets update": {**dataset, "base_version": 1},
251
+ "insight-datasets query": {"conditions": [{"key": "code", "value": "S001"}], "returns": ["code"], "page": 1},
252
+ "insight-datasets add-record": row, "insight-datasets update-record": {**row, "base_version": 2},
253
+ "insight-datasets workbook-preview": plan, "insight-datasets workbook-commit": plan,
254
+ "替换已有数据集的 Excel 方案": {**plan, "dataset_key": "ds_store", "base_version": 2},
255
+ "tagging-code create": {**code, "key": "intent_summary"}, "tagging-code update": {**code, "version": 1},
256
+ "tagging-tasks preview": preview, "tagging-tasks create": task, "tagging-tasks update": task,
257
+ "tagging-tasks create(决策模型,loan 为是否字段)": {"name": "贷款意向", "kind": "decision",
258
+ "prompt": "客户是否明确表示需要贷款?", "fields": ["loan"], "threshold": 0.65},
259
+ "tagging-tasks create(绑定已启用的代码)": {"name": "购车意向摘要", "kind": "code", "code_key": "intent_summary"},
260
+ }
@@ -0,0 +1,142 @@
1
+ """Quality-point experiments and the dataset operations needed to run them."""
2
+
3
+ from pathlib import Path
4
+ from typing import NamedTuple
5
+
6
+ from .auth import current
7
+ from .commands import confirm_operation, read_object
8
+ from .http import Error, segment
9
+
10
+
11
+ class Command(NamedTuple):
12
+ method: str
13
+ path: str
14
+ purpose: str
15
+ example: str
16
+
17
+
18
+ LAB = "/model-lab/quality-points"
19
+ EXPERIMENT = LAB + "/{lab_id}"
20
+ RUN = EXPERIMENT + "/runs/{run}"
21
+ SAMPLE = RUN + "/samples/{sample_id}"
22
+ DATASETS = "/test-datasets"
23
+
24
+ LAB_COMMANDS = {
25
+ "list": Command("GET", LAB, "分页列出质检点实验", "--page 1"),
26
+ "options": Command("GET", LAB + "/options", "读取可绑定的模型、数据集和现有绑定", ""),
27
+ "create": Command("POST", LAB, "创建实验并启动第一轮", "--json-file lab.json"),
28
+ "get": Command("GET", EXPERIMENT, "查看工作台、样本、进度与回归指标", "1 --run 1"),
29
+ "update": Command("PATCH", EXPERIMENT, "保存实验名称、说明及数值容差", "1 --json-file settings.json"),
30
+ "delete": Command("DELETE", EXPERIMENT, "删除实验及其实验记录", "1 --yes"),
31
+ "preview": Command("GET", EXPERIMENT + "/preview", "预览再测样本与有效标注数", "1"),
32
+ "rerun": Command("POST", EXPERIMENT + "/runs", "启动新一轮实验", "1 --note 修改提示词后复测"),
33
+ "cancel": Command("POST", RUN + "/cancel", "取消指定轮次", "1 --run 2 --yes"),
34
+ "retry": Command("POST", RUN + "/retry", "重试指定轮次异常样本", "1 --run 2 --yes"),
35
+ "confirm-rest": Command("POST", RUN + "/confirm", "批量将其余可确认的结果设为标准答案", "1 --run 1 --yes"),
36
+ "sample": Command("GET", SAMPLE, "读取本轮样本的冻结快照", "1 --run 1 --sample 3"),
37
+ "set-truth": Command("PUT", SAMPLE + "/truth", "保存样本标准答案和备注", "1 --run 1 --sample 3 --json-file truth.json"),
38
+ "clear-truth": Command("DELETE", SAMPLE + "/truth", "清除样本标准答案", "1 --run 1 --sample 3 --yes"),
39
+ "debug": Command("POST", SAMPLE + "/debug", "使用临时提示词试跑该样本", "1 --run 1 --sample 3 --json-file debug.json"),
40
+ "download-recording": Command("GET", SAMPLE + "/recording/{source}/audio", "下载实验快照的录音",
41
+ "1 --run 1 --sample 3 --source SOURCE --output sample.mp3"),
42
+ }
43
+ DATASET_COMMANDS = {
44
+ "list": Command("GET", DATASETS, "列出测试数据集", ""),
45
+ "create": Command("POST", DATASETS, "新建测试数据集", "--json-file dataset.json"),
46
+ "preview": Command("POST", DATASETS + "/{dataset_id}/preview", "预览待加入的通话", "2 --json-file selection.json"),
47
+ "add-calls": Command("POST", DATASETS + "/{dataset_id}/items", "加入通话静态快照", "2 --json-file selection.json"),
48
+ }
49
+ COMMANDS = {"quality-labs": LAB_COMMANDS, "test-datasets": DATASET_COMMANDS}
50
+ GROUPS = {
51
+ group: (label, [(name, cmd.purpose, cmd.example) for name, cmd in COMMANDS[group].items()])
52
+ for group, label in [("quality-labs", "质检点实验室"), ("test-datasets", "实验用测试数据集")]
53
+ }
54
+ MEMBER_ACTIONS = {"list", "get", "sample", "download-recording"}
55
+ CONFIRM_ACTIONS = {"delete", "cancel", "retry", "confirm-rest", "clear-truth"}
56
+
57
+
58
+ def positive_id(value):
59
+ number = int(value)
60
+ if not 1 <= number <= 2147483647:
61
+ raise Error("编号须为 1 至 2147483647 的整数")
62
+ return number
63
+
64
+
65
+ def arguments(parser, group, action):
66
+ add = parser.add_argument
67
+ path = COMMANDS[group][action].path
68
+ if "{lab_id}" in path:
69
+ add("lab_id", metavar="LAB_ID", type=positive_id, help="实验 ID")
70
+ if "{dataset_id}" in path:
71
+ add("dataset_id", metavar="DATASET_ID", type=positive_id, help="测试数据集 ID")
72
+ if "{run}" in path or action == "get":
73
+ add("--run", type=positive_id, required="{run}" in path, help="轮次号,查看工作台时默认最新轮")
74
+ if "{sample_id}" in path or action == "get":
75
+ add("--sample", dest="sample_id", type=positive_id, required="{sample_id}" in path, help="工作台返回的样本 ID")
76
+ if group == "quality-labs" and action in ("list", "get"):
77
+ add("--page", type=positive_id, default=1, help="页码")
78
+ add("--per-page", type=int, choices=(20, 50, 100), default=20, help="每页条数")
79
+ add("--keyword", help="搜索关键词")
80
+ if action == "list" and group == "quality-labs":
81
+ add("--output-type", choices=("all", "single_choice", "multi_choice", "number"), help="模型输出类型")
82
+ add("--run-status", choices=("all", "running", "completed", "failed", "cancelled"), help="最新轮次状态")
83
+ if action == "list" and group == "test-datasets":
84
+ add("--call-id", help="标记已收录此通话的数据集")
85
+ if action == "get":
86
+ add("--verdict", choices=("all", "match", "mismatch", "unreviewed", "regressed", "fixed"), help="筛选评估结果")
87
+ add("--view", choices=("eval", "labels"), help="样本评估或标准答案视图")
88
+ add("--has-note", choices=("all", "yes", "no"), help="筛选备注")
89
+ add("--order", choices=("default", "error"), help="样本排序")
90
+ add("--pair", help="混淆矩阵筛选值")
91
+ if action in ("preview", "rerun") and group == "quality-labs":
92
+ add("--model-version", type=positive_id, help="已发布模型版本,默认当前草稿")
93
+ if action == "rerun":
94
+ add("--note", default="", help="本轮备注")
95
+ if action == "download-recording":
96
+ add("--source", type=segment, required=True, help="样本 snapshot.recording.source_id")
97
+ add("--output", required=True, help="本地音频文件路径")
98
+ add("--force", action="store_true", help="覆盖已有文件")
99
+ if action in ("create", "update", "set-truth", "debug", "add-calls") or (group, action) == ("test-datasets", "preview"):
100
+ add("--json-file", required=True, help="UTF-8 JSON 请求体,示例见 guide")
101
+ if action in CONFIRM_ACTIONS:
102
+ add("--yes", action="store_true", help="确认执行,非交互环境必填")
103
+
104
+
105
+ def run(client, vault, args):
106
+ action = args.action
107
+ command = COMMANDS[args.group][action]
108
+ path = command.path.format(**vars(args))
109
+ body = read_object(args.json_file) if hasattr(args, "json_file") else None
110
+ fields = {"keyword": "q", "page": "page", "per_page": "pageSize", "output_type": "outputType",
111
+ "run_status": "runStatus", "call_id": "call_id", "verdict": "verdict", "view": "view",
112
+ "has_note": "hasNote", "order": "order", "pair": "pair"}
113
+ if action == "get":
114
+ fields.update(run="run", sample_id="sample")
115
+ if action == "preview":
116
+ fields["model_version"] = "version"
117
+ params = {key: getattr(args, name) for name, key in fields.items() if getattr(args, name, None) is not None}
118
+ if action == "rerun":
119
+ body = {"note": args.note, "version": args.model_version}
120
+ pair = current(client, vault)
121
+ if action not in MEMBER_ACTIONS and pair["profile"]["role"] != "admin":
122
+ raise Error("仅租户管理员可执行此操作", 3, code="FORBIDDEN", status=403)
123
+ if action in CONFIRM_ACTIONS and not args.yes:
124
+ confirm_operation(client, pair, f"确定{command.purpose}?目标 {path}")
125
+ if action == "download-recording":
126
+ if Path(args.output).exists() and not args.force:
127
+ raise Error("文件已存在,添加 --force 覆盖")
128
+ return client.request("GET", path, token=pair["access_token"], output=args.output, force=args.force)
129
+ return client.request(command.method, path, token=pair["access_token"], body=body, params=params,
130
+ read_only=(args.group, action) == ("test-datasets", "preview"))
131
+
132
+
133
+ def examples():
134
+ selection = {"call_ids": ["CALL001", "CALL002"]}
135
+ return {
136
+ "test-datasets create": {"name": "外呼回归集"},
137
+ "test-datasets preview": selection, "test-datasets add-calls": selection,
138
+ "quality-labs create": {"name": "外呼回归", "model_key": "service_score", "dataset_id": 2},
139
+ "quality-labs update": {"name": "外呼回归", "description": "同一批外呼样本", "tolerance": 1},
140
+ "quality-labs set-truth": {"status": "ok", "value": 8, "note": "已复听"},
141
+ "quality-labs debug": {"prompt": "依据本次样本的对话给出服务评分。"},
142
+ }