vod-devkit 0.5.5 → 0.5.9

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.
Files changed (98) hide show
  1. package/CHANGELOG.md +40 -0
  2. package/QUICKSTART.md +47 -23
  3. package/README.en.md +7 -2
  4. package/README.md +6 -2
  5. package/bin/vod-devkit +12 -1164
  6. package/contract/tools.schema.json +1 -1
  7. package/package.json +11 -2
  8. package/plugins/vod-devkit/.codex-plugin/plugin.json +1 -1
  9. package/plugins/vod-devkit/build-info.json +3 -3
  10. package/plugins/vod-devkit/contract/tools.schema.json +446 -0
  11. package/plugins/vod-devkit/safety/policy.json +48 -0
  12. package/plugins/vod-devkit/vod_mcp/__init__.py +1 -1
  13. package/plugins/vod-devkit/vod_mcp/host_adapters/base.py +3 -1
  14. package/plugins/vod-devkit/vod_mcp/host_adapters/codex.py +14 -0
  15. package/plugins/vod-devkit/vod_mcp/host_adapters/hermes.py +88 -11
  16. package/plugins/vod-devkit/vod_mcp/hosts.py +3 -1
  17. package/plugins/vod-devkit/vod_mcp/net.py +251 -0
  18. package/plugins/vod-devkit/vod_mcp/packs/collect.py +684 -0
  19. package/plugins/vod-devkit/vod_mcp/packs/core.py +80 -0
  20. package/plugins/vod-devkit/vod_mcp/packs/knowledge.py +17 -0
  21. package/plugins/vod-devkit/vod_mcp/paths.py +38 -0
  22. package/plugins/vod-devkit/vod_mcp/payload.py +3 -1
  23. package/plugins/vod-devkit/vod_mcp/policy.py +3 -2
  24. package/plugins/vod-devkit/vod_mcp/provenance.py +3 -2
  25. package/plugins/vod-devkit/vod_mcp/runtime_state.py +324 -0
  26. package/plugins/vod-devkit/vod_mcp/server.py +10 -7
  27. package/plugins/vod-devkit/vod_mcp/skills_registry.py +5 -4
  28. package/plugins/vod-devkit/vod_mcp/tools.py +23 -1298
  29. package/plugins/vod-devkit/vod_mcp/transport_remote.py +21 -9
  30. package/plugins/vod-devkit/vod_mcp/update_check.py +1 -1
  31. package/vod_mcp/__init__.py +1 -1
  32. package/vod_mcp/host_adapters/__pycache__/__init__.cpython-39.pyc +0 -0
  33. package/vod_mcp/host_adapters/__pycache__/atomcode.cpython-39.pyc +0 -0
  34. package/vod_mcp/host_adapters/__pycache__/base.cpython-314.pyc +0 -0
  35. package/vod_mcp/host_adapters/__pycache__/base.cpython-39.pyc +0 -0
  36. package/vod_mcp/host_adapters/__pycache__/codearts.cpython-39.pyc +0 -0
  37. package/vod_mcp/host_adapters/__pycache__/codeartswork.cpython-39.pyc +0 -0
  38. package/vod_mcp/host_adapters/__pycache__/codex.cpython-314.pyc +0 -0
  39. package/vod_mcp/host_adapters/__pycache__/codex.cpython-39.pyc +0 -0
  40. package/vod_mcp/host_adapters/__pycache__/codex_desktop.cpython-39.pyc +0 -0
  41. package/vod_mcp/host_adapters/__pycache__/dsh.cpython-39.pyc +0 -0
  42. package/vod_mcp/host_adapters/__pycache__/generic.cpython-39.pyc +0 -0
  43. package/vod_mcp/host_adapters/__pycache__/hermes.cpython-314.pyc +0 -0
  44. package/vod_mcp/host_adapters/__pycache__/hermes.cpython-39.pyc +0 -0
  45. package/vod_mcp/host_adapters/__pycache__/opencode.cpython-39.pyc +0 -0
  46. package/vod_mcp/host_adapters/__pycache__/workbuddy.cpython-39.pyc +0 -0
  47. package/vod_mcp/host_adapters/base.py +3 -1
  48. package/vod_mcp/host_adapters/codex.py +14 -0
  49. package/vod_mcp/host_adapters/hermes.py +88 -11
  50. package/vod_mcp/hosts.py +3 -1
  51. package/vod_mcp/net.py +251 -0
  52. package/vod_mcp/packs/__pycache__/__init__.cpython-314.pyc +0 -0
  53. package/vod_mcp/packs/__pycache__/__init__.cpython-39.pyc +0 -0
  54. package/vod_mcp/packs/__pycache__/collect.cpython-314.pyc +0 -0
  55. package/vod_mcp/packs/__pycache__/collect.cpython-39.pyc +0 -0
  56. package/vod_mcp/packs/__pycache__/core.cpython-314.pyc +0 -0
  57. package/vod_mcp/packs/__pycache__/core.cpython-39.pyc +0 -0
  58. package/vod_mcp/packs/__pycache__/knowledge.cpython-314.pyc +0 -0
  59. package/vod_mcp/packs/__pycache__/knowledge.cpython-39.pyc +0 -0
  60. package/vod_mcp/packs/collect.py +684 -0
  61. package/vod_mcp/packs/core.py +80 -0
  62. package/vod_mcp/packs/knowledge.py +17 -0
  63. package/vod_mcp/paths.py +38 -0
  64. package/vod_mcp/payload.py +3 -1
  65. package/vod_mcp/policy.py +3 -2
  66. package/vod_mcp/provenance.py +3 -2
  67. package/vod_mcp/runtime_state.py +324 -0
  68. package/vod_mcp/server.py +10 -7
  69. package/vod_mcp/skills_registry.py +5 -4
  70. package/vod_mcp/tools.py +23 -1298
  71. package/vod_mcp/transport_remote.py +21 -9
  72. package/vod_mcp/update_check.py +1 -1
  73. package/vodkit_cli/__init__.py +10 -0
  74. package/vodkit_cli/__pycache__/__init__.cpython-314.pyc +0 -0
  75. package/vodkit_cli/__pycache__/__init__.cpython-39.pyc +0 -0
  76. package/vodkit_cli/__pycache__/cli.cpython-314.pyc +0 -0
  77. package/vodkit_cli/__pycache__/cli.cpython-39.pyc +0 -0
  78. package/vodkit_cli/__pycache__/common.cpython-314.pyc +0 -0
  79. package/vodkit_cli/__pycache__/common.cpython-39.pyc +0 -0
  80. package/vodkit_cli/__pycache__/doctor.cpython-314.pyc +0 -0
  81. package/vodkit_cli/__pycache__/doctor.cpython-39.pyc +0 -0
  82. package/vodkit_cli/__pycache__/install.cpython-314.pyc +0 -0
  83. package/vodkit_cli/__pycache__/install.cpython-39.pyc +0 -0
  84. package/vodkit_cli/__pycache__/remote.cpython-314.pyc +0 -0
  85. package/vodkit_cli/__pycache__/remote.cpython-39.pyc +0 -0
  86. package/vodkit_cli/__pycache__/uninstall.cpython-314.pyc +0 -0
  87. package/vodkit_cli/__pycache__/uninstall.cpython-39.pyc +0 -0
  88. package/vodkit_cli/__pycache__/update.cpython-314.pyc +0 -0
  89. package/vodkit_cli/__pycache__/update.cpython-39.pyc +0 -0
  90. package/vodkit_cli/cli.py +86 -0
  91. package/vodkit_cli/common.py +254 -0
  92. package/vodkit_cli/doctor.py +269 -0
  93. package/vodkit_cli/install.py +260 -0
  94. package/vodkit_cli/remote.py +200 -0
  95. package/vodkit_cli/uninstall.py +161 -0
  96. package/vodkit_cli/update.py +45 -0
  97. /package/plugins/vod-devkit/vod_mcp/{packs.py → packs/__init__.py} +0 -0
  98. /package/vod_mcp/{packs.py → packs/__init__.py} +0 -0
@@ -0,0 +1,684 @@
1
+ """collect pack:用户声音采集全链(校验 → 归因 → 提交/两段式 → 账本 → 回显 → pending)。"""
2
+ import json
3
+ import os
4
+
5
+ from vod_mcp import attribution as _attrib
6
+ from vod_mcp import net, runtime_state as rt
7
+ from vod_mcp.packs import core
8
+
9
+
10
+ _FOLLOWUP_DECLINES = frozenset({
11
+ "没有", "无", "没有。", "没了", "跳过", "不方便", "不用了", "不用",
12
+ "不补充", "算了", "没有了", "没有了。", "不方便说", "no", "none", "skip", "n/a",
13
+ })
14
+
15
+
16
+ def _followup_fields(voice: dict) -> dict:
17
+ """D-followup-impl-2 单源提取(submit 主路径与 draft 暂存共用,禁双边漂移):
18
+ 仅 trim 非空且非拒答词才含键;引擎同口径截 2000;内容永不回流 content。
19
+ followupStatus(评审八点 #3 引擎侧承载的插件上报):三态白名单归一
20
+ (strip+lower),白名单外/缺失省键——引擎侧降 NULL 不拒收,插件侧同口径双保险。"""
21
+ out = {}
22
+ for _f in ("reproSteps", "expectedBehavior"):
23
+ _val = str(voice.get(_f) or "").strip()
24
+ if _val and _val.lower() not in _FOLLOWUP_DECLINES:
25
+ out[_f] = _val[:2000]
26
+ _st = str(voice.get("followupStatus") or "").strip().lower()
27
+ if _st in ("not_asked", "declined", "answered"):
28
+ out["followupStatus"] = _st
29
+ return out
30
+
31
+
32
+ _UNRESOLVED_CODE = -32010 # 「需要先问用户是哪个产品」的可执行错误码
33
+
34
+
35
+ def _attribute_product(items: list, params: dict, client_info: dict | None = None) -> dict:
36
+ """归因(D-product-ask-1,2026-11-11 负责人拍板:不许裸 UNKNOWN,缺产品先问)。
37
+
38
+ 优先级(按拍板口径,不是"原话永远第一"):
39
+ ① 用户明确回答/确认(params.product,仅问过用户后由模型填)
40
+ ② 原话唯一且高置信提及(多产品/歧义=低置信,转去问)
41
+ ③ 会话记忆(30 分钟滑动,进程内;跨会话不继承)
42
+ ④ 安装先验
43
+ 四级都拿不到(含用户明确说"不知道/随便"= params.productNotSpecified)→
44
+ 返回 source=unknown + confidence=low,由调用方抛可执行错误要求追问。
45
+ **不做 host_default 兜底**(2026-11-12 复评删除:宿主产品也是一次推断,
46
+ 错归的产品会进引擎幂等/判重域,污染静默且难追溯)。
47
+ """
48
+ text = "\n".join(content for _i, _v, content in items)
49
+ meta = net._load_meta()
50
+ answer = str(params.get("product") or "").strip()
51
+ mem = rt._memory_get(client_info)
52
+ binding = str(rt._RT.get("product") or "").strip() or None
53
+
54
+ if answer:
55
+ rid = _attrib.resolve_id(answer, meta)
56
+ hit = [c for c in (meta.get("catalog") or [])
57
+ if str(c.get("id")) == str(rid)
58
+ or str(c.get("name") or "").lower() == answer.lower()]
59
+ if not hit and not (meta.get("catalog") or []):
60
+ # 名录不可用(离线/快照/老引擎):没有校验依据,不能假装能核。
61
+ # 按用户回答原样上报,标 low(引擎侧仍会按表解析,未命中落未知池)。
62
+ return {"product": answer, "productName": answer, "source": "user_answer",
63
+ "confidence": "low", "rawText": answer,
64
+ "evidence": [{"reason": "catalog-unavailable", "rawText": answer}],
65
+ "ignored": None}
66
+ if not hit:
67
+ # 用户说了名录里没有的产品("智果"/"XYZ"/打错):**不拿原名硬提交**,
68
+ # 也不要自己猜最像的——把候选交回去,让模型按名录再问一次。
69
+ cands = core.search_products({"query": answer, "limit": 5})["candidates"]
70
+ return {"product": None, "productName": None, "source": "unknown",
71
+ "confidence": "low", "rawText": answer, "unmatched_answer": answer,
72
+ "candidates": cands,
73
+ "evidence": [{"reason": "unmatched-answer", "rawText": answer}],
74
+ "ignored": None}
75
+ name = hit[0].get("name")
76
+ return {"product": str(hit[0].get("id")), "productName": name,
77
+ "source": "user_answer", "confidence": "high", "rawText": answer,
78
+ "evidence": [{"product": name, "alias": "用户回答", "snippet": answer}],
79
+ "ignored": None}
80
+
81
+ result = _attrib.attribute(text, meta,
82
+ memory={k: v for k, v in mem.items()
83
+ if k in ("product", "productName", "alias",
84
+ "snippet", "at")},
85
+ binding=binding)
86
+ result["rawText"] = None
87
+ result["ignored"] = None
88
+ if result["source"] == "user_input":
89
+ result["confidence"] = "high"
90
+ return result
91
+ if result["source"] == "memory" and mem.get("product") and not mem.get("not_specified"):
92
+ result["confidence"] = "medium"
93
+ return result
94
+ if result["source"] == "install_binding":
95
+ result["confidence"] = "medium"
96
+ return result
97
+
98
+ # 用户明确说"不知道/随便":同样是"不猜、不提交"——只影响回执原因字段
99
+ # (productNotSpecified=true),不做任何兜底推断。
100
+ not_specified = bool(params.get("productNotSpecified")) or bool(mem.get("not_specified"))
101
+ ev = list(result.get("evidence") or [])
102
+ if not_specified:
103
+ ev = [{"reason": "user-not-specified"}] + ev
104
+ return {"product": None, "productName": None, "source": "unknown",
105
+ "not_specified": not_specified,
106
+ "confidence": "low", "rawText": None,
107
+ "evidence": (ev or [{"reason": "no-evidence"}]),
108
+ "ignored": None}
109
+
110
+
111
+ def _require_product_or_ask(attr: dict, items: list, client_info: dict | None = None) -> None:
112
+ """缺产品且用户没说不知道 → 可执行错误:先问一次(D-product-ask-1)。
113
+
114
+ 错误里带候选(来自原话关键词),模型照着问一句就能补齐;不是"参考文档"。
115
+ """
116
+ if attr.get("product"):
117
+ return
118
+ # 追问轮次上限(2026-11-12 评审采纳):同一会话最多追问 2 次,之后明确终止——
119
+ # 避免"用户连续给两个都查不到的名字"时模型无限重问。
120
+ mem = rt._memory_get(client_info)
121
+ fails = int(mem.get("ask_failures") or 0) + 1
122
+ rt._memory_put(client_info, ask_failures=fails)
123
+ stop = fails > 2
124
+ tail = "(已追问 2 次仍未确认:别再问了,直接告诉用户这条反馈因为没有产品归属而不提交)"
125
+
126
+ if attr.get("unmatched_answer"):
127
+ cands = attr.get("candidates") or []
128
+ hint = "、".join(f"{c['name']}({c['id']})" for c in cands) or "(名录为空)"
129
+ raise net.ToolError(
130
+ f"用户说的产品「{attr['rawText']}」不在产品名录里,不能按它提交。"
131
+ f"请按名录再确认一次是哪一个:{hint};用户仍说不出来就说明这条先不提交。"
132
+ + (tail if stop else ""),
133
+ code=_UNRESOLVED_CODE)
134
+ if attr.get("not_specified"):
135
+ # 兼容 Python 3.10/3.11:PEP 701 之前 f-string 表达式内不允许反斜杠
136
+ # ('\n' 会触发 SyntaxError),故先在 f-string 外计算查询串再引用。
137
+ _query = "\n".join(x[2] for x in items)
138
+ raise net.ToolError(
139
+ "用户没有提供产品,这条反馈**不能提交**:请告诉用户「没有产品归属的反馈我不提交,"
140
+ "因为不知道要转给哪个产品团队」,并请他补充是哪个产品;他仍不想说就说明这条先不提交。"
141
+ f"可选候选:{'、'.join(c['name'] + '(' + str(c['id']) + ')' for c in core.search_products({'query': _query, 'limit': 5})['candidates'])}"
142
+ + (tail if stop else ""),
143
+ code=_UNRESOLVED_CODE)
144
+ if os.environ.get("VOD_ALLOW_UNKNOWN_PRODUCT") == "1":
145
+ # 旧客户端兼容(业界口径:可选字段 + 明确默认值,不做破坏性变更):
146
+ # 缺 product 的老客户端不让它直接失败,回执标 legacy_default/low,可追溯。
147
+ attr["source"] = "legacy_default"
148
+ attr["confidence"] = "low"
149
+ return
150
+ text = "\n".join(c for _i, _v, c in items)
151
+ cands = core.search_products({"query": text, "limit": 5})["candidates"]
152
+ hint = "、".join(f"{c['name']}({c['id']})" for c in cands) or "(名录未命中,可问用户直接说产品名)"
153
+ raise net.ToolError(
154
+ "这条反馈还没确定是哪个产品:请先问用户一次『这条是哪个产品的反馈?』,"
155
+ "把回答填进 product(产品名或 ID);用户明确说不知道/随便时,传 productNotSpecified=true。"
156
+ f"候选:{hint}", code=_UNRESOLVED_CODE)
157
+
158
+
159
+ def _attach_attribution(result: dict, attr: dict) -> None:
160
+ """回执留痕(D-product-ask-1):来源 + 置信 + 原始回答 + 证据。
161
+
162
+ productSource 枚举:user_input | user_answer | memory | install_binding |
163
+ host_default(后者恒 confidence=low,必须可人工修正)。
164
+ """
165
+ result["productSource"] = attr.get("source") or "unknown"
166
+ result["productConfidence"] = attr.get("confidence") or "low"
167
+ if attr.get("productName"):
168
+ result["productName"] = attr["productName"]
169
+ if attr.get("product") is not None:
170
+ result["productId"] = str(attr["product"])
171
+ if attr.get("rawText"):
172
+ result["productRawText"] = attr["rawText"]
173
+ if attr.get("evidence"):
174
+ result["productEvidence"] = attr["evidence"]
175
+
176
+
177
+ def _merge_ledger(extra: dict | None, attr: dict) -> dict:
178
+ """账本条目带上归因来源与证据:错归可回溯到用户原话(S99)。"""
179
+ out = dict(extra or {})
180
+ out["productSource"] = attr.get("source") or "unknown"
181
+ if attr.get("evidence"):
182
+ out["productEvidence"] = attr["evidence"]
183
+ return out
184
+
185
+
186
+ _SUBMIT_HOARDING = "/rest/developer/manager/hdvodmngservice/v1/external/voices"
187
+
188
+
189
+ _EXISTING_SUBMIT = "/rest/developer/manager/hdvodmngservice/v1/external/voice/submit" # 过渡期 404 回落
190
+
191
+
192
+ def _voice_id(source: str, content: str, nonce: str) -> str:
193
+ """voiceId = f(source, content, 调用级nonce)。
194
+
195
+ R1 修正(声量保真):跨调用不去重——不同用户提交同款反馈必须各占
196
+ 一行(声量是分析核心信号);同调用内重试复用同 nonce 保幂等。
197
+ """
198
+ import hashlib
199
+ return f"ext_{source}_{hashlib.sha1((content + nonce).encode('utf-8')).hexdigest()[:12]}"
200
+
201
+
202
+ def _flush_pending(product):
203
+ """补提交 ~/.vod-devkit/pending-feedback.jsonl 里 status=pending 的条目。
204
+
205
+ 口径(D-pending-1 定稿):同步执行但失败只记日志、绝不回滚主提交;
206
+ 幂等键=条目级(sha1(content+confirmAt+source)),内容级去重由引擎
207
+ uk_voice_id 承担(同内容重提=skipped);重写+原子 rename,失败条目
208
+ 保留 pending;单次上限 100 条最早优先,超 30 天标记 expired 剔除。
209
+ 双通道消息分离:本函数结果只进工具内部诊断(result.pendingFlush),
210
+ 用户侧话术由 skill 层承担(已暂存/自动补交,禁止出现路径)。
211
+ """
212
+ from vod_mcp import pending as _pq
213
+ path = _pq.default_path()
214
+ entries = _pq.load_entries(path)
215
+ if not entries:
216
+ return {"scanned": 0}
217
+ plan = _pq.plan_flush(entries)
218
+ kept = list(plan["kept"])
219
+ flushed, failed, corrected = 0, 0, 0
220
+ for e in plan["to_flush"]:
221
+ content = _pq.canonical_content(e) # D-pending-1 补强:originalLines 权威拼接,剥模型加的标点
222
+ if content != str(e.get("content", "")):
223
+ corrected += 1
224
+ rt._log("pending flush: content 与 originalLines 拼接不一致,以 originalLines 为准(剥除模型拼接改动)")
225
+ hv = {"title": str(content)[:60], "content": str(content)}
226
+ if e.get("tags"):
227
+ hv["tags"] = e["tags"]
228
+ body = {"voices": [hv]}
229
+ if product:
230
+ body["product"] = product
231
+ try:
232
+ out = net._http("POST", _SUBMIT_HOARDING, body, base=net.JAVA_BASE, key=net._eff_key())
233
+ ids = (out or {}).get("voiceIds") or ((out or {}).get("data") or {}).get("voiceIds")
234
+ if ids is None:
235
+ failed += 1
236
+ kept.append(e)
237
+ rt._log("pending flush: 回执未含 voiceIds,条目保留")
238
+ else:
239
+ flushed += 1 # 含幂等 skipped(同内容重提=引擎 skipped,零重复)
240
+ except Exception as err:
241
+ failed += 1
242
+ kept.append(e)
243
+ rt._log(f"pending flush failed (kept pending): {err}")
244
+ _pq.save_entries(path, kept)
245
+ return {"scanned": len(entries), "flushed": flushed,
246
+ "failed": failed, "expired": len(plan["expired"]),
247
+ "corrected": corrected}
248
+
249
+
250
+ def _allowed_tags(product_id=None) -> set:
251
+ """分类白名单(引擎 meta.problemTypes,单一真源)。
252
+
253
+ 2026-11-12 引擎契约变更:problemTypes 不再随无参 meta 下发(那是"全部分类"
254
+ 的假全集),改为 `GET /external/meta?productId=<id>` 按产品下发——真源是
255
+ t_vod_problem_category 按 product_id 分组,不同产品的分类集不同。
256
+
257
+ 取不到(无 product_id / 老引擎 / 快照降级 / 该产品无分类)→ 空集=不知道
258
+ 白名单 → 不过滤:宁可放行也不误杀采集。
259
+ """
260
+ pid = str(product_id or "").strip()
261
+ if not pid or not pid.isdigit():
262
+ return set()
263
+ import time
264
+ cache = rt._RT.get("ptype_cache") or {}
265
+ now = time.time()
266
+ if now - float(cache.get("at") or 0) < net._META_TTL and pid in (cache.get("by") or {}):
267
+ return set(cache["by"][pid] or [])
268
+ by = dict(cache.get("by") or {})
269
+ try:
270
+ path = f"{net._META_PATH}?productId={pid}"
271
+ out = net._http("GET", path, None, base=net.JAVA_BASE, key=net._eff_key(), timeout=10)
272
+ data = out.get("data") or {}
273
+ types = [str(t) for t in (data.get("problemTypes") or []) if str(t).strip()]
274
+ by[pid] = types
275
+ cache = {"at": int(now), "by": by}
276
+ rt._runtime_update({"ptype_cache": cache})
277
+ return set(types)
278
+ except Exception:
279
+ # 任何取不到(网络/超时/引擎异常)= 不知道值域 → 不过滤,绝不阻断提交
280
+ return set(by.get(pid) or [])
281
+
282
+
283
+ _PROBLEM_TYPE_PREFIX = "problem_type:"
284
+
285
+
286
+ def _filter_tags(tags, allowed: set) -> tuple:
287
+ """tags 白名单过滤 → (kept, dropped)。
288
+
289
+ 引擎约定(ExternalVoicesServiceImpl.extractProblemType):分类标注写
290
+ `problem_type:<值>`,值域=meta.problemTypes(六类)。其它语义的 tag 不参与
291
+ 分类校验、原样保留;只有 problem_type 的值会被白名单过滤——脏值丢弃不拒收
292
+ 声音(对标 vod-skill 的 check_classification:分类必须存在于知识库)。
293
+ """
294
+ kept, dropped = [], []
295
+ for t in tags or []:
296
+ s = str(t).strip()
297
+ if not s:
298
+ continue
299
+ if allowed and s.startswith(_PROBLEM_TYPE_PREFIX):
300
+ val = s[len(_PROBLEM_TYPE_PREFIX):].strip()
301
+ if val not in allowed:
302
+ dropped.append(s)
303
+ continue
304
+ s = _PROBLEM_TYPE_PREFIX + val # 归一(去多余空白)
305
+ if s not in kept:
306
+ kept.append(s)
307
+ return kept, dropped
308
+
309
+
310
+ def _collect_voice_items(params: dict) -> tuple[list, list]:
311
+ """校验段:content 非空+≤2000 字(契约 maxLength,防超大 payload)。
312
+ 返回 (items[(index, voice, content)], rejected 明细)。"""
313
+ items, rejected = [], []
314
+ for i, v in enumerate(params.get("voices", [])):
315
+ content = str(v.get("content", "")).strip()
316
+ if not content:
317
+ rejected.append({"index": i, "reason": "content 为空"})
318
+ elif len(content) > 2000:
319
+ rejected.append({"index": i, "reason": f"content 超 2000 字({len(content)})"})
320
+ else:
321
+ items.append((i, v, content))
322
+ return items, rejected
323
+
324
+
325
+ def _echo_plan(items: list, vids: list) -> dict:
326
+ """回显段(方案 A,2026-11-06 拍板):提交回执强制携带原话回显。
327
+ 检测型防线——宿主模型改写用户原话(实锤:"体验不好"→"不友好")
328
+ 在回执处当场可见;agent 必须原样转述,改写露馅。"""
329
+ ok = [(vid, items[min(i, len(items) - 1)][2])
330
+ for i, vid in enumerate(vids) if vid]
331
+ return {
332
+ "requiresUserEcho": bool(ok),
333
+ "instruction": ("请向用户原样转述已收录内容:每条以「已收录原话:」开头,"
334
+ "后接 content 全文。禁止改写、概括、增删字词。"),
335
+ "contents": [{"voiceId": vid, "content": c} for vid, c in ok],
336
+ }
337
+
338
+
339
+ def _ledger_submit(items: list, vids: list, tids: list, product: str | None,
340
+ extra: dict | None = None) -> None:
341
+ """账本段:回执 voiceIds/taskIds 逐条落本地账本(层级①查询的源)。"""
342
+ import time as _time
343
+ entries = [{"voiceId": vid, "taskId": tid,
344
+ "title": items[min(i, len(items) - 1)][2][:40],
345
+ "product": product, "at": _time.strftime("%Y-%m-%dT%H:%M:%S")}
346
+ for i, (vid, tid) in enumerate(zip(vids, tids))]
347
+ if extra:
348
+ for e in entries:
349
+ e.update(extra) # 两段式:stage=committed + draftId 关联(验收③)
350
+ rt._ledger_append(entries)
351
+
352
+
353
+ def _hoard_voice(v: dict, content: str) -> dict:
354
+ """载荷段:单条囤积端点 voice 载荷(title/content + tags/userType +
355
+ D-followup-impl-2 追问补充透传:单源 _followup_fields,拒答词集兜底)。"""
356
+ hv = {"title": content[:60], "content": content}
357
+ if v.get("tags"): # 采集层三分类(problem_type:值)→正式入库
358
+ hv["tags"] = v["tags"]
359
+ if v.get("userType"):
360
+ hv["userType"] = v["userType"]
361
+ hv.update(_followup_fields(v))
362
+ return hv
363
+
364
+
365
+ def _raise_explicit_key_rejected(key: str) -> None:
366
+ """显式 key(安装注入/正式档)被引擎 401 拒绝 → fail fast:
367
+ 不取匿名令牌、不覆盖配置——静默降级匿名档=配置错误被吞
368
+ (归因错位比报错更糟,同 AIShell 错归病根)。囤积/legacy 两路径同口径。"""
369
+ raise net.ToolError(
370
+ f"注入的 key 被引擎拒绝(指纹 {net._fingerprint(key)}):"
371
+ "请核对 key 是否过期/被吊销,或移除 key 走匿名档。"
372
+ + net._legacy_key_hint(),
373
+ code=-32012)
374
+
375
+
376
+ def submit_voices(params: dict, client_info: dict | None = None,
377
+ ledger_extra: dict | None = None) -> dict:
378
+ """V16 切换:主路径=囤积端点 POST /external/voices(Bearer,批式,不触发分析);
379
+ 引擎未部署(404)自动回落老链 /external/voice/submit(提交即分析,过渡语义,
380
+ 部署后 404 分支自然失效)。
381
+
382
+ - voiceId:囤积链由引擎确定性计算(per-token/per-install 命名空间),回执
383
+ voiceIds 为权威对账键;回落老链仍用客户端 nonce id(R1 声量保真)
384
+ - title=用户原文截断;tags=采集层三分类(problem_type:)正式入库通道
385
+ - source:key 持有者被引擎锚定为 host_name;legacy 共用 key 场景带
386
+ per-install nonce 后缀(杜绝跨用户共享命名空间吞声量)
387
+ """
388
+ import uuid
389
+ host = (client_info or {}).get("name") or "unknown-host"
390
+ accepted = 0
391
+ voice_ids: list[str] = []
392
+ task_ids: list[object] = []
393
+ items, rejected = _collect_voice_items(params)
394
+ if not items:
395
+ return {"accepted": 0, "voiceIds": [], "taskIds": [], "rejected": rejected}
396
+ # 归因(D-attrib-B):证据来自用户原话,模型自报不参战
397
+ # 归因(D-product-ask-1):身份/鉴权优先于产品追问,产品校验放在下面 key 守卫之后
398
+ attr = _attribute_product(items, params, client_info)
399
+ product = attr["product"]
400
+
401
+ def _legacy_submit(i, v, content):
402
+ """过渡回落:老链单条提交(提交即分析语义,仅 404 触发)。"""
403
+ nonce = uuid.uuid4().hex[:8] # 调用级:重试复用,跨调用不重复
404
+ vid = _voice_id(host, content, nonce)
405
+ desc = content if len(content) >= 10 else f"{content} [vod-devkit]"
406
+ body = {
407
+ "voiceId": vid,
408
+ "title": content[:128],
409
+ "description": desc,
410
+ "source": f"{host}-{rt._install_nonce()}", # per-install 命名空间(legacy 吞声量修复)
411
+ "customer": v.get("userType"),
412
+ }
413
+ if product:
414
+ body["product"] = product
415
+ out = net._http("POST", _EXISTING_SUBMIT, body, base=net.JAVA_BASE, key=net._eff_key())
416
+ return vid, (out.get("data") or {}).get("taskId")
417
+
418
+ # 服务面(HTTP):身份只能来自请求头。缺 key 时 fail fast——不先打引擎再
419
+ # 靠 401 兜底(那会多一次无意义外呼,且引擎若宽容 200 就绕过了守卫)。
420
+ if net._SERVER_FACE.get() and not net._eff_key():
421
+ raise net.ToolError(
422
+ "服务面(HTTP 传输)不代签身份:请在本请求带上 Authorization: Bearer "
423
+ "<VOD key>(插件只搬运身份,不产生身份;落库与配额都在服务端)",
424
+ code=-32012)
425
+
426
+ # 缺产品且用户没说不知道 → 可执行错误(先问一次),不许裸提交 UNKNOWN
427
+ _require_product_or_ask(attr, items, client_info)
428
+ # ---- 主路径:囤积端点批式提交 ----
429
+ # 分类白名单按产品取(引擎 ?productId= 下发);product 非数字 id 时取不到→不过滤
430
+ allowed_tags = _allowed_tags(product)
431
+ hoard, invalid_tags = [], []
432
+ for i, v, content in items:
433
+ hv = _hoard_voice(v, content)
434
+ if hv.get("tags"):
435
+ kept, dropped = _filter_tags(hv["tags"], allowed_tags)
436
+ if kept:
437
+ hv["tags"] = kept
438
+ else:
439
+ hv.pop("tags", None)
440
+ if dropped:
441
+ invalid_tags.append({"index": i, "tags": dropped})
442
+ hoard.append(hv)
443
+ body = {"voices": hoard}
444
+ if product: # 无归因不带 product(引擎 UNKNOWN 档),不本地拦截
445
+ body["product"] = product
446
+ out = None
447
+ fallback = False
448
+ try:
449
+ out = net._http("POST", _SUBMIT_HOARDING, body, base=net.JAVA_BASE, key=net._eff_key())
450
+ except net.ToolError as ex:
451
+ if ex.code == 404:
452
+ fallback = True # 囤积端点未部署 → 落到下方 legacy 回落
453
+ elif not net._eff_key() or ex.code == -32012:
454
+ if net._SERVER_FACE.get():
455
+ # 服务面(HTTP):不代签身份。匿名令牌按设备锚点签发,一进程
456
+ # 一锚点会把配额/声量/归因全搅在一起(服务端多用户形态的
457
+ # 已拍板口径:formal/host key + 按请求透传)。
458
+ raise net.ToolError(
459
+ "服务面(HTTP 传输)不代签身份:请在本请求带上 "
460
+ "Authorization: Bearer <VOD key>,或改用 stdio 形态的匿名链",
461
+ code=-32012)
462
+ if net._explicit_key():
463
+ _raise_explicit_key_rejected(net._eff_key())
464
+ # 缺 key/匿名令牌失效 → 零字段匿名令牌 → 落 runtime.json → 重试一次
465
+ token = net._acquire_anon_token_or_raise()
466
+ net.JAVA_KEY = token
467
+ rt._save_runtime({"java_key": token, "token_tier": "anonymous"})
468
+ out = net._http("POST", _SUBMIT_HOARDING, body, base=net.JAVA_BASE, key=net._eff_key())
469
+ else:
470
+ raise # 网络/413 等如实上抛
471
+ if not fallback:
472
+ out = out or {} # 类型收窄:非回落分支必然已赋值(初值 None 只是失败占位)
473
+ server_ids = (out.get("voiceIds") or out.get("data", {}).get("voiceIds")
474
+ or [])
475
+ # 引擎侧 rejected(产品校验拒绝等)透出,不吞(对齐 widget rejected 口径)
476
+ engine_rejected = ((out or {}).get("rejected")
477
+ or ((out or {}).get("data") or {}).get("rejected")
478
+ or [])
479
+ if server_ids:
480
+ accepted = len(server_ids)
481
+ voice_ids.extend(server_ids)
482
+ else:
483
+ # 回执缺失/整批被拒 → 不得兜底计成功(实锤缺陷:空 voiceId 记成功
484
+ # 且宿主模型据此谎报"已提交")。accepted 以真实回执为准。
485
+ accepted = 0
486
+ voice_ids.extend([""] * len(items))
487
+ if not engine_rejected:
488
+ engine_rejected = [{"reason": "引擎回执未含 voiceIds(提交结果未知),请勿视为已收录"}]
489
+ task_ids.extend([None] * len(items)) # 囤积语义:无即时任务
490
+ result = {"accepted": accepted, "voiceIds": voice_ids,
491
+ "taskIds": task_ids, "rejected": rejected + engine_rejected,
492
+ "analysis": "deferred", # 囤积语义明示(V6 运营批量消费)
493
+ "path": "hoarding",
494
+ "echo": _echo_plan(items, voice_ids)}
495
+ if invalid_tags: # 分类白名单外值被丢弃(不拒收声音,只丢 tag)
496
+ result["invalidTags"] = invalid_tags
497
+ if out.get("productRegistered") is not None:
498
+ result["productRegistered"] = out.get("productRegistered")
499
+ _attach_attribution(result, attr) # 来源+证据留痕(S99)
500
+ rt._remember_attribution(attr, client_info) # 会话记忆 + 审计(S95/S100)
501
+ _ledger_submit(items, voice_ids, task_ids, product,
502
+ _merge_ledger(ledger_extra, attr))
503
+ result["pendingFlush"] = _flush_pending(product)
504
+ return result
505
+ # ---- 过渡回落:老链单条提交(仅囤积端点 404 触发) ----
506
+ for i, v, content in items:
507
+ try:
508
+ vid, tid = _legacy_submit(i, v, content)
509
+ accepted += 1
510
+ voice_ids.append(vid)
511
+ task_ids.append(tid)
512
+ except net.ToolError as e:
513
+ msg = str(e)
514
+ if "Duplicate entry" in msg: # 极端重放场景:DB 唯一键兜底
515
+ accepted += 1
516
+ voice_ids.append(vid)
517
+ task_ids.append(None)
518
+ elif (not net._eff_key() or e.code == -32012) and not voice_ids:
519
+ if net._SERVER_FACE.get():
520
+ rejected.append({"index": i, "reason":
521
+ "服务面(HTTP 传输)不代签身份:请带 Authorization: Bearer <VOD key>"})
522
+ continue
523
+ if net._explicit_key():
524
+ _raise_explicit_key_rejected(net._eff_key())
525
+ # 零字段匿名令牌:缺 key/401 → 自动取令牌 → 落 runtime.json → 重试一次
526
+ token = net._acquire_anon_token_or_raise()
527
+ net.JAVA_KEY = token
528
+ rt._save_runtime({"java_key": token, "token_tier": "anonymous"})
529
+ vid, tid = _legacy_submit(i, v, content)
530
+ accepted += 1
531
+ voice_ids.append(vid)
532
+ task_ids.append(tid)
533
+ else:
534
+ rejected.append({"index": i, "reason": msg[:120]})
535
+ result = {"accepted": accepted, "voiceIds": voice_ids,
536
+ "taskIds": task_ids, "rejected": rejected,
537
+ "path": "legacy-fallback",
538
+ "echo": _echo_plan(items, voice_ids)}
539
+ _attach_attribution(result, attr)
540
+ if accepted:
541
+ rt._remember_attribution(attr, client_info)
542
+ _ledger_submit(items, voice_ids, task_ids, product,
543
+ _merge_ledger(ledger_extra, attr))
544
+ result["pendingFlush"] = _flush_pending(product)
545
+ return result
546
+
547
+
548
+ def list_submitted(params: dict, client_info: dict | None = None) -> dict:
549
+ """查询本机已提交的声音(只读,采集者对账闭环)。
550
+ 引擎级跨机查询随 VOD-VOI 列表端点;终端用户自助查询维持 P2(签名回执)。"""
551
+ limit = params.get("limit", 20)
552
+ try:
553
+ limit = max(1, min(int(limit), 100))
554
+ except (TypeError, ValueError):
555
+ limit = 20
556
+ ledger = rt._runtime_cfg().get(rt._LEDGER_KEY) or [] # 文件现读(进程内账本可能刚更新)
557
+ return {"total": len(ledger),
558
+ "submissions": ledger[-limit:][::-1], # 最新在前
559
+ "scope": "本机提交记录(换机/重装不保留;引擎级查询随 VOD-VOI)"}
560
+
561
+
562
+ def draft_voices(params: dict, client_info: dict | None = None) -> dict:
563
+ """两段式第一步:校验+暂存草稿+签发一次性令牌(不提交任何数据)。"""
564
+ import time as _time
565
+ voices_in = params.get("voices", [])
566
+ invalid_tags = []
567
+ clean = []
568
+
569
+ # 归因(D-attrib-B)前移:分类白名单按产品下发(?productId=),必须先知道
570
+ # 产品才能取到该产品的分类集,否则过滤会拿到空集而静默失效。
571
+ # 归因只看 content,不依赖 tags,前移不改变其它语义。
572
+ _attr_items = []
573
+ for i, v in enumerate(voices_in):
574
+ _c = str(v.get("content", "")).strip()
575
+ if _c:
576
+ _attr_items.append((i, v, _c))
577
+ attr = (_attribute_product(_attr_items, params, client_info)
578
+ if _attr_items else {"product": None, "source": "unknown",
579
+ "confidence": "low"})
580
+ product = attr.get("product")
581
+ allowed_tags = _allowed_tags(product)
582
+
583
+ for i, v in enumerate(voices_in):
584
+ content = str(v.get("content", "")).strip()
585
+ if not content:
586
+ raise net.ToolError(f"第 {i + 1} 条 content 为空", code=-32602)
587
+ if len(content) > 2000:
588
+ raise net.ToolError(f"第 {i + 1} 条 content 超 2000 字({len(content)})", code=-32602)
589
+ item = {"content": content}
590
+ if v.get("tags"):
591
+ kept, dropped = _filter_tags(v["tags"], allowed_tags)
592
+ if kept:
593
+ item["tags"] = kept
594
+ if dropped:
595
+ invalid_tags.append({"index": i, "tags": dropped})
596
+ if v.get("userType"):
597
+ item["userType"] = v["userType"]
598
+ # D-followup-impl-2:追问补充随 draft 暂存(commit 复用 payload 原样上送),
599
+ # 单源 _followup_fields 与主路径同口径
600
+ item.update(_followup_fields(v))
601
+ clean.append(item)
602
+ if not clean:
603
+ raise net.ToolError("voices 为必填且至少 1 条", code=-32602)
604
+ rt._remember_attribution(attr, client_info)
605
+
606
+ import secrets
607
+ draft_id = "draft_" + secrets.token_hex(8)
608
+ token = secrets.token_hex(16)
609
+ payload: dict[str, object] = {"voices": clean}
610
+ if product:
611
+ payload["product"] = product
612
+ # 载荷 sha(防 draft→commit 间改写:commit 校验插件侧重算值一致)
613
+ import hashlib
614
+ payload_sha = hashlib.sha256(
615
+ json.dumps(payload, sort_keys=True, ensure_ascii=False).encode()).hexdigest()
616
+
617
+ with rt._RT_LOCK: # 读改写整段持锁:并发 draft 不互相丢草稿
618
+ store = rt._drafts_load()
619
+ store[draft_id] = {
620
+ "payload": payload, "payloadSha256": payload_sha,
621
+ "tokenHash": rt._sha256(token),
622
+ # D-resume-commit-1:token 明文随草稿落盘(runtime.json 0600,与 java_key
623
+ # 同级保护)。token 的威胁模型是"防载荷改写"而非"同意凭证"——落盘不放大
624
+ # 风险,换断回合可续:agent 回合中断后凭 draftId 即可恢复提交(此前
625
+ # approvalToken 只存在于 draft 响应文本,回合断即丢失,只能重开草稿)
626
+ "token": token,
627
+ "product": product, "productSource": attr.get("source"),
628
+ "productEvidence": attr.get("evidence") or [],
629
+ "createdAt": _time.strftime("%Y-%m-%dT%H:%M:%S"),
630
+ "expiresAt": _time.time() + rt._DRAFT_TTL,
631
+ }
632
+ while len(store) > rt._DRAFT_CAP: # 环形:最旧先淘汰
633
+ store.pop(next(iter(store)))
634
+ rt._save_runtime({rt._DRAFT_KEY: store})
635
+
636
+ out = {
637
+ "draftId": draft_id,
638
+ "approvalToken": token,
639
+ "payloadSha256": payload_sha,
640
+ "expiresInSeconds": rt._DRAFT_TTL,
641
+ "contents": [{"index": i, "content": it["content"]} for i, it in enumerate(clean)],
642
+ "instruction": ("把 contents 逐条原样展示给用户核对(禁止改写概括),明确问"
643
+ "「确认提交吗」。用户明确同意前禁止调用 vod_commit_voices;"
644
+ "不同意则停(草稿 10 分钟后自动作废)。"),
645
+ }
646
+ _attach_attribution(out, attr) # 草稿阶段也让归因来源可审(commit 回执沿用)
647
+ if invalid_tags:
648
+ out["invalidTags"] = invalid_tags
649
+ return out
650
+
651
+
652
+ def commit_voices(params: dict, client_info: dict | None = None) -> dict:
653
+ """两段式第二步:令牌校验→单次消费→复用 submit_voices 既有提交链。
654
+
655
+ D-resume-commit-1:approvalToken/payloadSha256 可省略——draftId 命中本地
656
+ 未过期草稿时自动恢复(断回合续提交)。显式传入仍走原校验(传了假 sha
657
+ 照样拒),恢复路径的完整性由签发时落盘的 sha/token 保证,语义不放宽。
658
+ """
659
+ draft_id = str(params.get("draftId", ""))
660
+ if not draft_id:
661
+ raise net.ToolError("draftId 为必填(取自 vod_draft_voices 返回原样透传)", code=-32602)
662
+
663
+ store = rt._drafts_load()
664
+ draft = store.get(draft_id)
665
+ if draft is None:
666
+ raise net.ToolError("草稿不存在或已过期(10 分钟 TTL),请重新 vod_draft_voices", code=-32011)
667
+ token = str(params.get("approvalToken", "")) or str(draft.get("token", ""))
668
+ payload_sha = str(params.get("payloadSha256", "")) or str(draft["payloadSha256"])
669
+ if draft["tokenHash"] != rt._sha256(token):
670
+ raise net.ToolError("审批令牌不匹配(draft 返回的 approvalToken 原样透传)", code=-32011)
671
+ if draft["payloadSha256"] != payload_sha:
672
+ raise net.ToolError("载荷校验不符(payloadSha256 与 draft 签发值不一致,禁止改写已确认内容)",
673
+ code=-32011)
674
+ # 单次消费:先摘除再提交——提交中途崩溃也不会二次提交(宁可丢一单重走流程)
675
+ # 整段持锁:并发 commit 同一 draftId 时只有一方能消费成功
676
+ with rt._RT_LOCK:
677
+ store.pop(draft_id)
678
+ rt._save_runtime({rt._DRAFT_KEY: store})
679
+
680
+ out = submit_voices(dict(draft["payload"]), client_info,
681
+ ledger_extra={"stage": "committed", "draftId": draft_id})
682
+ out["twoPhase"] = True
683
+ out["draftId"] = draft_id
684
+ return out