vod-devkit 0.4.1 → 0.4.3

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.
package/vod_mcp/tools.py CHANGED
@@ -272,6 +272,133 @@ def _explicit_key() -> bool:
272
272
  return bool(JAVA_KEY) and str(_RT.get("token_tier") or "") != "anonymous"
273
273
 
274
274
 
275
+ # ── D-pending-1:无通道期 pending 反馈 flush(方案 A,2026-11-09)──
276
+
277
+ def _flush_pending(product):
278
+ """补提交 ~/.vod-devkit/pending-feedback.jsonl 里 status=pending 的条目。
279
+
280
+ 口径(D-pending-1 定稿):同步执行但失败只记日志、绝不回滚主提交;
281
+ 幂等键=条目级(sha1(content+confirmAt+source)),内容级去重由引擎
282
+ uk_voice_id 承担(同内容重提=skipped);重写+原子 rename,失败条目
283
+ 保留 pending;单次上限 100 条最早优先,超 30 天标记 expired 剔除。
284
+ 双通道消息分离:本函数结果只进工具内部诊断(result.pendingFlush),
285
+ 用户侧话术由 skill 层承担(已暂存/自动补交,禁止出现路径)。
286
+ """
287
+ from vod_mcp import pending as _pq
288
+ path = _pq.default_path()
289
+ entries = _pq.load_entries(path)
290
+ if not entries:
291
+ return {"scanned": 0}
292
+ plan = _pq.plan_flush(entries)
293
+ kept = list(plan["kept"])
294
+ flushed, failed, corrected = 0, 0, 0
295
+ for e in plan["to_flush"]:
296
+ content = _pq.canonical_content(e) # D-pending-1 补强:originalLines 权威拼接,剥模型加的标点
297
+ if content != str(e.get("content", "")):
298
+ corrected += 1
299
+ _log("pending flush: content 与 originalLines 拼接不一致,以 originalLines 为准(剥除模型拼接改动)")
300
+ hv = {"title": str(content)[:60], "content": str(content)}
301
+ if e.get("tags"):
302
+ hv["tags"] = e["tags"]
303
+ body = {"voices": [hv]}
304
+ if product:
305
+ body["product"] = product
306
+ try:
307
+ out = _http("POST", _SUBMIT_HOARDING, body, base=JAVA_BASE, key=JAVA_KEY)
308
+ ids = (out or {}).get("voiceIds") or ((out or {}).get("data") or {}).get("voiceIds")
309
+ if ids is None:
310
+ failed += 1
311
+ kept.append(e)
312
+ _log("pending flush: 回执未含 voiceIds,条目保留")
313
+ else:
314
+ flushed += 1 # 含幂等 skipped(同内容重提=引擎 skipped,零重复)
315
+ except Exception as err:
316
+ failed += 1
317
+ kept.append(e)
318
+ _log(f"pending flush failed (kept pending): {err}")
319
+ _pq.save_entries(path, kept)
320
+ return {"scanned": len(entries), "flushed": flushed,
321
+ "failed": failed, "expired": len(plan["expired"]),
322
+ "corrected": corrected}
323
+
324
+
325
+
326
+ def _collect_voice_items(params: dict) -> tuple[list, list]:
327
+ """校验段:content 非空+≤2000 字(契约 maxLength,防超大 payload)。
328
+ 返回 (items[(index, voice, content)], rejected 明细)。"""
329
+ items, rejected = [], []
330
+ for i, v in enumerate(params.get("voices", [])):
331
+ content = str(v.get("content", "")).strip()
332
+ if not content:
333
+ rejected.append({"index": i, "reason": "content 为空"})
334
+ elif len(content) > 2000:
335
+ rejected.append({"index": i, "reason": f"content 超 2000 字({len(content)})"})
336
+ else:
337
+ items.append((i, v, content))
338
+ return items, rejected
339
+
340
+
341
+ def _echo_plan(items: list, vids: list) -> dict:
342
+ """回显段(方案 A,2026-11-06 拍板):提交回执强制携带原话回显。
343
+ 检测型防线——宿主模型改写用户原话(实锤:"体验不好"→"不友好")
344
+ 在回执处当场可见;agent 必须原样转述,改写露馅。"""
345
+ ok = [(vid, items[min(i, len(items) - 1)][2])
346
+ for i, vid in enumerate(vids) if vid]
347
+ return {
348
+ "requiresUserEcho": bool(ok),
349
+ "instruction": ("请向用户原样转述已收录内容:每条以「已收录原话:」开头,"
350
+ "后接 content 全文。禁止改写、概括、增删字词。"),
351
+ "contents": [{"voiceId": vid, "content": c} for vid, c in ok],
352
+ }
353
+
354
+
355
+ def _ledger_submit(items: list, vids: list, tids: list, product: str | None,
356
+ extra: dict | None = None) -> None:
357
+ """账本段:回执 voiceIds/taskIds 逐条落本地账本(层级①查询的源)。"""
358
+ import time as _time
359
+ entries = [{"voiceId": vid, "taskId": tid,
360
+ "title": items[min(i, len(items) - 1)][2][:40],
361
+ "product": product, "at": _time.strftime("%Y-%m-%dT%H:%M:%S")}
362
+ for i, (vid, tid) in enumerate(zip(vids, tids))]
363
+ if extra:
364
+ for e in entries:
365
+ e.update(extra) # 两段式:stage=committed + draftId 关联(验收③)
366
+ _ledger_append(entries)
367
+
368
+
369
+ def _hoard_voice(v: dict, content: str) -> dict:
370
+ """载荷段:单条囤积端点 voice 载荷(title/content + tags/userType +
371
+ D-followup-impl-2 追问补充透传:单源 _followup_fields,拒答词集兜底)。"""
372
+ hv = {"title": content[:60], "content": content}
373
+ if v.get("tags"): # 采集层三分类(problem_type:值)→正式入库
374
+ hv["tags"] = v["tags"]
375
+ if v.get("userType"):
376
+ hv["userType"] = v["userType"]
377
+ hv.update(_followup_fields(v))
378
+ return hv
379
+
380
+
381
+ def _raise_explicit_key_rejected(key: str) -> None:
382
+ """显式 key(安装注入/正式档)被引擎 401 拒绝 → fail fast:
383
+ 不取匿名令牌、不覆盖配置——静默降级匿名档=配置错误被吞
384
+ (归因错位比报错更糟,同 AIShell 错归病根)。囤积/legacy 两路径同口径。"""
385
+ raise ToolError(
386
+ f"注入的 key 被引擎拒绝(指纹 {_fingerprint(key)}):"
387
+ "请核对 key 是否过期/被吊销,或移除 key 走匿名档。"
388
+ + _legacy_key_hint(),
389
+ code=-32012)
390
+
391
+
392
+ def _acquire_anon_token_or_raise() -> str:
393
+ """缺 key/匿名令牌失效 → 领零字段匿名令牌;端点不可用则如实报错。"""
394
+ token = _fetch_anon_token()
395
+ if not token:
396
+ raise ToolError(
397
+ "未配置接入 key 且匿名令牌端点不可用。引导:"
398
+ + ";".join(g["label"] for g in _KEY_GUIDANCE), code=-32012)
399
+ return token
400
+
401
+
275
402
  def submit_voices(params: dict, client_info: dict | None = None,
276
403
  ledger_extra: dict | None = None) -> dict:
277
404
  """V16 切换:主路径=囤积端点 POST /external/voices(Bearer,批式,不触发分析);
@@ -287,46 +414,12 @@ def submit_voices(params: dict, client_info: dict | None = None,
287
414
  import uuid
288
415
  host = (client_info or {}).get("name") or "unknown-host"
289
416
  product, ignored_runtime = _resolve_product(params)
290
- accepted, voice_ids, task_ids, rejected = 0, [], [], []
291
417
  global JAVA_KEY
292
- voices_in = params.get("voices", [])
293
- items = [] # (index, voice_map, content)
294
- for i, v in enumerate(voices_in):
295
- content = str(v.get("content", "")).strip()
296
- if not content:
297
- rejected.append({"index": i, "reason": "content 为空"})
298
- continue
299
- if len(content) > 2000: # 契约 maxLength 2000:内容边界(防超大 payload)
300
- rejected.append({"index": i, "reason": f"content 超 2000 字({len(content)})"})
301
- continue
302
- items.append((i, v, content))
418
+ accepted, voice_ids, task_ids = 0, [], []
419
+ items, rejected = _collect_voice_items(params)
303
420
  if not items:
304
421
  return {"accepted": 0, "voiceIds": [], "taskIds": [], "rejected": rejected}
305
422
 
306
- def _echo(vids):
307
- """方案 A(2026-11-06 拍板):提交回执强制携带原话回显。
308
- 检测型防线——宿主模型改写用户原话(实锤:"体验不好"→"不友好")
309
- 在回执处当场可见;agent 必须原样转述,改写露馅。"""
310
- ok = [(vid, items[min(i, len(items) - 1)][2])
311
- for i, vid in enumerate(vids) if vid]
312
- return {
313
- "requiresUserEcho": bool(ok),
314
- "instruction": ("请向用户原样转述已收录内容:每条以「已收录原话:」开头,"
315
- "后接 content 全文。禁止改写、概括、增删字词。"),
316
- "contents": [{"voiceId": vid, "content": c} for vid, c in ok],
317
- }
318
-
319
- def _ledger(vids, tids):
320
- import time as _time
321
- entries = [{"voiceId": vid, "taskId": tid,
322
- "title": items[min(i, len(items) - 1)][2][:40],
323
- "product": product, "at": _time.strftime("%Y-%m-%dT%H:%M:%S")}
324
- for i, (vid, tid) in enumerate(zip(vids, tids))]
325
- if ledger_extra:
326
- for e in entries:
327
- e.update(ledger_extra) # 两段式:stage=committed + draftId 关联(验收③)
328
- _ledger_append(entries)
329
-
330
423
  def _legacy_submit(i, v, content):
331
424
  """过渡回落:老链单条提交(提交即分析语义,仅 404 触发)。"""
332
425
  nonce = uuid.uuid4().hex[:8] # 调用级:重试复用,跨调用不重复
@@ -345,20 +438,7 @@ def submit_voices(params: dict, client_info: dict | None = None,
345
438
  return vid, (out.get("data") or {}).get("taskId")
346
439
 
347
440
  # ---- 主路径:囤积端点批式提交 ----
348
- hoard_voices = []
349
- for i, v, content in items:
350
- hv = {"title": content[:60], "content": content}
351
- tags = v.get("tags") # 采集层三分类(problem_type:值)→【类型名】标题前缀正式入库
352
- if tags:
353
- hv["tags"] = tags
354
- ut = v.get("userType")
355
- if ut:
356
- hv["userType"] = ut
357
- # D-followup-impl-2 追问补充透传:单源 _followup_fields(拒答词集兜底+
358
- # 引擎同口径截 2000+禁回流 content;未追问/答"没有"=键集合零漂移)
359
- hv.update(_followup_fields(v))
360
- hoard_voices.append(hv)
361
- body = {"voices": hoard_voices}
441
+ body = {"voices": [_hoard_voice(v, content) for _, v, content in items]}
362
442
  if product: # 无归因不带 product(引擎 UNKNOWN 档),不本地拦截
363
443
  body["product"] = product
364
444
  out = None
@@ -370,20 +450,9 @@ def submit_voices(params: dict, client_info: dict | None = None,
370
450
  fallback = True # 囤积端点未部署 → 落到下方 legacy 回落
371
451
  elif not JAVA_KEY or ex.code == -32012:
372
452
  if _explicit_key():
373
- # 显式 key(安装注入/正式档)被引擎 401 拒绝 → fail fast:
374
- # 不取匿名令牌、不覆盖配置——静默降级匿名档=配置错误被吞
375
- #(归因错位比报错更糟,同 AIShell 错归病根)
376
- raise ToolError(
377
- f"注入的 key 被引擎拒绝(指纹 {_fingerprint(JAVA_KEY)}):"
378
- "请核对 key 是否过期/被吊销,或移除 key 走匿名档。"
379
- + _legacy_key_hint(),
380
- code=-32012)
453
+ _raise_explicit_key_rejected(JAVA_KEY)
381
454
  # 缺 key/匿名令牌失效 → 零字段匿名令牌 → 落 runtime.json → 重试一次
382
- token = _fetch_anon_token()
383
- if not token:
384
- raise ToolError(
385
- "未配置接入 key 且匿名令牌端点不可用。引导:" +
386
- ";".join(g["label"] for g in _KEY_GUIDANCE), code=-32012)
455
+ token = _acquire_anon_token_or_raise()
387
456
  JAVA_KEY = token
388
457
  _save_runtime({"java_key": token, "token_tier": "anonymous"})
389
458
  out = _http("POST", _SUBMIT_HOARDING, body, base=JAVA_BASE, key=JAVA_KEY)
@@ -403,22 +472,23 @@ def submit_voices(params: dict, client_info: dict | None = None,
403
472
  # 回执缺失/整批被拒 → 不得兜底计成功(实锤缺陷:空 voiceId 记成功
404
473
  # 且宿主模型据此谎报"已提交")。accepted 以真实回执为准。
405
474
  accepted = 0
406
- voice_ids.extend([""] * len(hoard_voices))
475
+ voice_ids.extend([""] * len(items))
407
476
  if not engine_rejected:
408
477
  engine_rejected = [{"reason": "引擎回执未含 voiceIds(提交结果未知),请勿视为已收录"}]
409
- task_ids.extend([None] * len(hoard_voices)) # 囤积语义:无即时任务
478
+ task_ids.extend([None] * len(items)) # 囤积语义:无即时任务
410
479
  result = {"accepted": accepted, "voiceIds": voice_ids,
411
480
  "taskIds": task_ids, "rejected": rejected + engine_rejected,
412
481
  "analysis": "deferred", # 囤积语义明示(V6 运营批量消费)
413
482
  "path": "hoarding",
414
- "echo": _echo(voice_ids)}
483
+ "echo": _echo_plan(items, voice_ids)}
415
484
  if out.get("productRegistered") is not None:
416
485
  result["productRegistered"] = out.get("productRegistered")
417
486
  # D-attrib-A 可观测:模型试图改归因留痕,不静默吞
418
487
  result["productSource"] = "install_binding"
419
488
  if ignored_runtime:
420
489
  result["ignoredRuntimeProduct"] = ignored_runtime
421
- _ledger(voice_ids, task_ids)
490
+ _ledger_submit(items, voice_ids, task_ids, product, ledger_extra)
491
+ result["pendingFlush"] = _flush_pending(product)
422
492
  return result
423
493
  # ---- 过渡回落:老链单条提交(仅囤积端点 404 触发) ----
424
494
  for i, v, content in items:
@@ -435,47 +505,25 @@ def submit_voices(params: dict, client_info: dict | None = None,
435
505
  task_ids.append(None)
436
506
  elif (not JAVA_KEY or e.code == -32012) and not voice_ids:
437
507
  if _explicit_key():
438
- # 显式 key 被拒 → fail fast(同囤积主路径口径,防静默降级)
439
- raise ToolError(
440
- f"注入的 key 被引擎拒绝(指纹 {_fingerprint(JAVA_KEY)}):"
441
- "请核对 key 是否过期/被吊销,或移除 key 走匿名档。"
442
- + _legacy_key_hint(), code=-32012)
508
+ _raise_explicit_key_rejected(JAVA_KEY)
443
509
  # 零字段匿名令牌:缺 key/401 → 自动取令牌 → 落 runtime.json → 重试一次
444
- token = _fetch_anon_token()
445
- if token:
446
- JAVA_KEY = token
447
- _save_runtime({"java_key": token, "token_tier": "anonymous"})
448
- vid, tid = _legacy_submit(i, v, content)
449
- accepted += 1
450
- voice_ids.append(vid)
451
- task_ids.append(tid)
452
- else:
453
- raise ToolError(
454
- "未配置接入 key 且匿名令牌端点不可用。引导:" +
455
- ";".join(g["label"] for g in _KEY_GUIDANCE), code=-32012)
510
+ token = _acquire_anon_token_or_raise()
511
+ JAVA_KEY = token
512
+ _save_runtime({"java_key": token, "token_tier": "anonymous"})
513
+ vid, tid = _legacy_submit(i, v, content)
514
+ accepted += 1
515
+ voice_ids.append(vid)
516
+ task_ids.append(tid)
456
517
  else:
457
518
  rejected.append({"index": i, "reason": msg[:120]})
458
519
  result = {"accepted": accepted, "voiceIds": voice_ids,
459
520
  "taskIds": task_ids, "rejected": rejected,
460
521
  "path": "legacy-fallback",
461
- "echo": _echo(voice_ids)}
462
- _ledger(voice_ids, task_ids)
522
+ "echo": _echo_plan(items, voice_ids)}
523
+ _ledger_submit(items, voice_ids, task_ids, product, ledger_extra)
524
+ result["pendingFlush"] = _flush_pending(product)
463
525
  return result
464
526
 
465
- # 本地账本落账(层级①查询的源)
466
- import time as _time
467
- _contents = [str(v.get("content", ""))[:40]
468
- for v in params.get("voices", []) if str(v.get("content", "")).strip()]
469
- ledger_entries = [
470
- {"voiceId": vid, "taskId": tid,
471
- "title": (_contents[i] if i < len(_contents) else ""),
472
- "product": product, "at": _time.strftime("%Y-%m-%dT%H:%M:%S")}
473
- for i, (vid, tid) in enumerate(zip(voice_ids, task_ids))
474
- ]
475
- _ledger_append(ledger_entries)
476
- return {"accepted": accepted, "voiceIds": voice_ids,
477
- "taskIds": task_ids, "rejected": rejected}
478
-
479
527
 
480
528
  def _fingerprint(key: str) -> str | None:
481
529
  import hashlib
@@ -627,23 +675,33 @@ def _ensure_first_boot(rt_path: Path | None = None) -> dict:
627
675
  return {"action": "stamped"}
628
676
 
629
677
 
678
+ def _uptime_seconds() -> float:
679
+ """本机 uptime(秒)。独立函数:测试可 monkeypatch,消除对宿主机器的依赖
680
+ (实锤:test_clone_image_detection_warns 曾硬编码 boot_age=7 天与真机
681
+ /proc/uptime 实值比较,uptime>7 天的机器必红——环境相关测试缺陷)。"""
682
+ return float(open("/proc/uptime").read().split()[0])
683
+
684
+
630
685
  def _warn_if_cloned(cfg: dict, p: Path) -> None:
631
686
  """preset 克隆镜像检测(D-key-guard-3①延伸,仅告警不阻断):
632
687
  firstBootAt 距今显著超过本机 uptime(>1h 容差)→ 本机状态大概率来自
633
688
  母机镜像克隆——所有克隆机共享同一 device 锚点/账本,声量与配额会收敛。
634
689
  判据:firstBootAt 的"年龄" > uptime+容差 ⇒ 首启发生在"这台机器"存在之前。"""
635
690
  import time as _t
691
+ if _distribution() != "preset":
692
+ return
636
693
  try:
637
- if _distribution() != "preset":
638
- return
639
694
  boot = _t.mktime(_t.strptime(cfg["firstBootAt"], "%Y-%m-%dT%H:%M:%S"))
640
- uptime_s = float(open("/proc/uptime").read().split()[0])
641
- if _t.time() - boot > uptime_s + 3600:
642
- _warn("疑似镜像克隆机:firstBootAt 早于本机 uptime——克隆分发未清 "
643
- "runtime.json,所有克隆机共享同一设备锚点/账本。请在镜像冻结前 "
644
- "uninstall 或删除 runtime.json(装机 checklist ②)")
645
- except Exception:
646
- pass
695
+ uptime_s = _uptime_seconds()
696
+ except (KeyError, ValueError, OSError) as ex:
697
+ # 收窄捕获(原 except Exception: pass 吞掉真实异常,告警失效不可见):
698
+ # 只吞解析类异常(缺字段/格式坏/读不到 /proc),其余如实上抛
699
+ _log(f"clone 检测跳过(无法解析 firstBootAt/uptime):{ex}")
700
+ return
701
+ if _t.time() - boot > uptime_s + 3600:
702
+ _warn("疑似镜像克隆机:firstBootAt 早于本机 uptime——克隆分发未清 "
703
+ "runtime.json,所有克隆机共享同一设备锚点/账本。请在镜像冻结前 "
704
+ "uninstall 或删除 runtime.json(装机 checklist ②)")
647
705
 
648
706
 
649
707
  def _save_runtime(update: dict, replace: bool = False) -> None: