vod-devkit 0.5.1 → 0.5.2

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/CHANGELOG.md CHANGED
@@ -302,3 +302,9 @@
302
302
  - e613449 feat(dsh): 归因与 MCP 侧同口径——运行期字面解析 + 记忆 + 先验 + 弃权(D-attrib-B)
303
303
  - 9b785dd feat(归因): 运行期字面解析取代安装绑定——名录别名 + 短 TTL 记忆 + 弃权(D-attrib-B)
304
304
 
305
+
306
+ ## v0.5.2(2026-11-12)
307
+
308
+ - cd1b0b0 feat(追问): 轮次上限 2 次 + 候选可解释(评审采纳)
309
+ - 2eb7886 chore(发版): golden 版本行随 bump 自动重录(两次实锤:v0.5.0/v0.5.1 都在 pre-push 被拦)
310
+
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "$schema": "https://json-schema.org/draft/2020-12/schema",
3
3
  "title": "vod-devkit MCP 工具契约(唯一事实源)",
4
- "version": "0.5.1",
4
+ "version": "0.5.2",
5
5
  "tools": {
6
6
  "vod_submit_voices": {
7
7
  "description": "提交用户反馈进 VOD。**先决条件(优先于本描述其余所有内容):调用前必须已征得用户对'提交这条反馈'的明确同意;用户陈述/抱怨反馈本身不构成同意;用户未同意时禁止传 confirmed=true**。模糊抱怨(如\"体验不好\")时一轮说完三件事:承接识别结果(\"收到,你对产品体验不满意\")+确认提交意愿(\"要把这条反馈提交给产品团队吗?\")+引导补充(\"方便的话说下具体现象,不说我也会按你的原话提交\");禁止含混反问(实锤病句:\"请问是否把什么作为反馈\")。同意后 content 放用户原话(哪怕只有一句\"体验很差\"也原样提交)。确认环节允许固定追问至多一次,问句必须逐字使用:「方便的话,补充一下遇到这个问题时的操作步骤或期望的表现吗?不方便回复\"没有\",我直接提交。」用户回答只摘录原话对应部分进 reproSteps/expectedBehavior(不改写不总结,无法拆分时落最相关字段,任何内容禁回填 content);答\"没有/跳过/不方便\"=两字段不上送直接提交。引导补充(说下具体现象)已获实质内容并并入 content 时不再追问、直接提交(其中自然出现的操作/期望留在 content 原话,不回溯摘入新字段);仅引导补充未获回应或仅泛化抱怨且用户确认提交时才带出固定问句。product 归因由插件从用户原话解析(安装绑定仅作先验),无需用户提供、禁止询问\"提交到哪个产品/页面\";模型/用户自报的目标产品一律不采信(提到的产品随正文原样传达)。用户说\"提单/提工单/提 issue\"时同样用本工具,除上述固定一次追问外,禁止再索要严重程度/环境/附件等开发者字段、禁止第二轮追问。批式提交对接囤积端点 POST /external/voices(不触发分析,voiceId 由引擎计算回执下发;引擎未部署 404 自动回落老链)。tags=采集层三分类(problem_type:值,可选)。缺 key 时自动获取零字段匿名令牌。拿到回执后必须原样转述 echo.contents(每条「已收录原话:<content>」全文),禁止改写概括——这是用户核对原话是否被改写的唯一窗口。禁止向用户解释内部机制(声音来源/渠道字段/计数规则/配额/归因)。",
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "vod-devkit",
3
- "version": "0.5.1",
3
+ "version": "0.5.2",
4
4
  "description": "VOD 用户声音采集插件——MCP server + 技能 + 声明式护栏,把 agent 产品的用户反馈安全送进 VOD 平台",
5
5
  "license": "MIT",
6
6
  "type": "module",
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "vod-devkit",
3
- "version": "0.5.1",
3
+ "version": "0.5.2",
4
4
  "description": "VOD user-feedback collection: structured voice capture and submission to the VOD hoarding endpoint.",
5
5
  "keywords": [
6
6
  "feedback",
@@ -1,6 +1,6 @@
1
1
  {
2
- "version": "0.5.1",
3
- "commitSha": "61577bc0502106f436825f9382b89fcb4591a653",
4
- "builtAt": "2026-11-12T17:13:52",
2
+ "version": "0.5.2",
3
+ "commitSha": "cd1b0b06c73ca2445f82e02997157342d4572ad6",
4
+ "builtAt": "2026-11-12T17:44:15",
5
5
  "sourceRemote": "https://gitcode.com/xiaowu2119/vod-devkit.git"
6
6
  }
@@ -5,7 +5,7 @@
5
5
  2. 外部无 DB 直连路径(护栏 deny 兜底)
6
6
  3. 任务 ID 是唯一对账主键,写类工具返回一律携带
7
7
  """
8
- __version__ = "0.5.1"
8
+ __version__ = "0.5.2"
9
9
  # 默认上游:VOD 测试环境。外部用户本机无 VOD,回环默认值=装完即坏;
10
10
  # 生产地址定型后只改这一处(tools.py 与 bin/vod-devkit 共用本常量)。
11
11
  DEFAULT_JAVA_BASE = "https://vod-dev.topxtopx.com"
@@ -266,17 +266,19 @@ def search_products(params: dict) -> dict:
266
266
  continue
267
267
  seen.add(pid)
268
268
  cands.append({"id": pid, "name": h["product"],
269
- "score": round(min(1.0, len(h["alias"]) / max(len(query), 1)), 2)})
269
+ "score": round(min(1.0, len(h["alias"]) / max(len(query), 1)), 2),
270
+ "matchReason": f"alias:{h['alias']}"})
270
271
  if not cands: # 别名没命中:退回名字子串(用户可能打错/只说一半)
271
272
  q = query.lower()
272
273
  for item in catalog:
273
274
  name = str(item.get("name") or "")
274
275
  if q and (q in name.lower() or name.lower() in q):
275
- cands.append({"id": str(item.get("id")), "name": name, "score": 0.5})
276
+ cands.append({"id": str(item.get("id")), "name": name, "score": 0.5,
277
+ "matchReason": "name-substring"})
276
278
  if not cands: # 完全无关联词:给名录前 N 个当"可选项"(问用户用)
277
279
  for item in catalog[:limit]:
278
280
  cands.append({"id": str(item.get("id")), "name": str(item.get("name") or ""),
279
- "score": 0.0})
281
+ "score": 0.0, "matchReason": "catalog-default"})
280
282
  cands.sort(key=lambda c: (c["score"], len(c["name"])), reverse=True)
281
283
  return {"candidates": cands[:limit], "total": len(catalog)}
282
284
 
@@ -357,25 +359,35 @@ def _attribute_product(items: list, params: dict, client_info: dict | None = Non
357
359
  "ignored": None}
358
360
 
359
361
 
360
- def _require_product_or_ask(attr: dict, items: list) -> None:
362
+ def _require_product_or_ask(attr: dict, items: list, client_info: dict | None = None) -> None:
361
363
  """缺产品且用户没说不知道 → 可执行错误:先问一次(D-product-ask-1)。
362
364
 
363
365
  错误里带候选(来自原话关键词),模型照着问一句就能补齐;不是"参考文档"。
364
366
  """
365
367
  if attr.get("product"):
366
368
  return
369
+ # 追问轮次上限(2026-11-12 评审采纳):同一会话最多追问 2 次,之后明确终止——
370
+ # 避免"用户连续给两个都查不到的名字"时模型无限重问。
371
+ mem = _memory_get(client_info)
372
+ fails = int(mem.get("ask_failures") or 0) + 1
373
+ _memory_put(client_info, ask_failures=fails)
374
+ stop = fails > 2
375
+ tail = "(已追问 2 次仍未确认:别再问了,直接告诉用户这条反馈因为没有产品归属而不提交)"
376
+
367
377
  if attr.get("unmatched_answer"):
368
378
  cands = attr.get("candidates") or []
369
379
  hint = "、".join(f"{c['name']}({c['id']})" for c in cands) or "(名录为空)"
370
380
  raise ToolError(
371
381
  f"用户说的产品「{attr['rawText']}」不在产品名录里,不能按它提交。"
372
- f"请按名录再确认一次是哪一个:{hint};用户仍说不出来就说明这条先不提交。",
382
+ f"请按名录再确认一次是哪一个:{hint};用户仍说不出来就说明这条先不提交。"
383
+ + (tail if stop else ""),
373
384
  code=_UNRESOLVED_CODE)
374
385
  if attr.get("not_specified"):
375
386
  raise ToolError(
376
387
  "用户没有提供产品,这条反馈**不能提交**:请告诉用户「没有产品归属的反馈我不提交,"
377
388
  "因为不知道要转给哪个产品团队」,并请他补充是哪个产品;他仍不想说就说明这条先不提交。"
378
- f"可选候选:{'、'.join(c['name'] + '(' + str(c['id']) + ')' for c in search_products({'query': '\n'.join(x[2] for x in items), 'limit': 5})['candidates'])}",
389
+ f"可选候选:{'、'.join(c['name'] + '(' + str(c['id']) + ')' for c in search_products({'query': '\n'.join(x[2] for x in items), 'limit': 5})['candidates'])}"
390
+ + (tail if stop else ""),
379
391
  code=_UNRESOLVED_CODE)
380
392
  if os.environ.get("VOD_ALLOW_UNKNOWN_PRODUCT") == "1":
381
393
  # 旧客户端兼容(业界口径:可选字段 + 明确默认值,不做破坏性变更):
@@ -431,6 +443,8 @@ def _remember_attribution(result: dict, client_info: dict | None = None) -> None
431
443
  """
432
444
  # 会话记忆(D-product-ask-1):只记「有证据/用户明确回答/用户说不知道」三种
433
445
  src = result.get("source")
446
+ if result.get("product"):
447
+ _memory_put(client_info, ask_failures=0)
434
448
  if src in ("user_input", "user_answer"):
435
449
  _memory_put(client_info, product=result.get("product"),
436
450
  productName=result.get("productName"),
@@ -756,7 +770,7 @@ def submit_voices(params: dict, client_info: dict | None = None,
756
770
  code=-32012)
757
771
 
758
772
  # 缺产品且用户没说不知道 → 可执行错误(先问一次),不许裸提交 UNKNOWN
759
- _require_product_or_ask(attr, items)
773
+ _require_product_or_ask(attr, items, client_info)
760
774
  # ---- 主路径:囤积端点批式提交 ----
761
775
  # 分类白名单按产品取(引擎 ?productId= 下发);product 非数字 id 时取不到→不过滤
762
776
  allowed_tags = _allowed_tags(product)
@@ -5,7 +5,7 @@
5
5
  2. 外部无 DB 直连路径(护栏 deny 兜底)
6
6
  3. 任务 ID 是唯一对账主键,写类工具返回一律携带
7
7
  """
8
- __version__ = "0.5.1"
8
+ __version__ = "0.5.2"
9
9
  # 默认上游:VOD 测试环境。外部用户本机无 VOD,回环默认值=装完即坏;
10
10
  # 生产地址定型后只改这一处(tools.py 与 bin/vod-devkit 共用本常量)。
11
11
  DEFAULT_JAVA_BASE = "https://vod-dev.topxtopx.com"
package/vod_mcp/tools.py CHANGED
@@ -266,17 +266,19 @@ def search_products(params: dict) -> dict:
266
266
  continue
267
267
  seen.add(pid)
268
268
  cands.append({"id": pid, "name": h["product"],
269
- "score": round(min(1.0, len(h["alias"]) / max(len(query), 1)), 2)})
269
+ "score": round(min(1.0, len(h["alias"]) / max(len(query), 1)), 2),
270
+ "matchReason": f"alias:{h['alias']}"})
270
271
  if not cands: # 别名没命中:退回名字子串(用户可能打错/只说一半)
271
272
  q = query.lower()
272
273
  for item in catalog:
273
274
  name = str(item.get("name") or "")
274
275
  if q and (q in name.lower() or name.lower() in q):
275
- cands.append({"id": str(item.get("id")), "name": name, "score": 0.5})
276
+ cands.append({"id": str(item.get("id")), "name": name, "score": 0.5,
277
+ "matchReason": "name-substring"})
276
278
  if not cands: # 完全无关联词:给名录前 N 个当"可选项"(问用户用)
277
279
  for item in catalog[:limit]:
278
280
  cands.append({"id": str(item.get("id")), "name": str(item.get("name") or ""),
279
- "score": 0.0})
281
+ "score": 0.0, "matchReason": "catalog-default"})
280
282
  cands.sort(key=lambda c: (c["score"], len(c["name"])), reverse=True)
281
283
  return {"candidates": cands[:limit], "total": len(catalog)}
282
284
 
@@ -357,25 +359,35 @@ def _attribute_product(items: list, params: dict, client_info: dict | None = Non
357
359
  "ignored": None}
358
360
 
359
361
 
360
- def _require_product_or_ask(attr: dict, items: list) -> None:
362
+ def _require_product_or_ask(attr: dict, items: list, client_info: dict | None = None) -> None:
361
363
  """缺产品且用户没说不知道 → 可执行错误:先问一次(D-product-ask-1)。
362
364
 
363
365
  错误里带候选(来自原话关键词),模型照着问一句就能补齐;不是"参考文档"。
364
366
  """
365
367
  if attr.get("product"):
366
368
  return
369
+ # 追问轮次上限(2026-11-12 评审采纳):同一会话最多追问 2 次,之后明确终止——
370
+ # 避免"用户连续给两个都查不到的名字"时模型无限重问。
371
+ mem = _memory_get(client_info)
372
+ fails = int(mem.get("ask_failures") or 0) + 1
373
+ _memory_put(client_info, ask_failures=fails)
374
+ stop = fails > 2
375
+ tail = "(已追问 2 次仍未确认:别再问了,直接告诉用户这条反馈因为没有产品归属而不提交)"
376
+
367
377
  if attr.get("unmatched_answer"):
368
378
  cands = attr.get("candidates") or []
369
379
  hint = "、".join(f"{c['name']}({c['id']})" for c in cands) or "(名录为空)"
370
380
  raise ToolError(
371
381
  f"用户说的产品「{attr['rawText']}」不在产品名录里,不能按它提交。"
372
- f"请按名录再确认一次是哪一个:{hint};用户仍说不出来就说明这条先不提交。",
382
+ f"请按名录再确认一次是哪一个:{hint};用户仍说不出来就说明这条先不提交。"
383
+ + (tail if stop else ""),
373
384
  code=_UNRESOLVED_CODE)
374
385
  if attr.get("not_specified"):
375
386
  raise ToolError(
376
387
  "用户没有提供产品,这条反馈**不能提交**:请告诉用户「没有产品归属的反馈我不提交,"
377
388
  "因为不知道要转给哪个产品团队」,并请他补充是哪个产品;他仍不想说就说明这条先不提交。"
378
- f"可选候选:{'、'.join(c['name'] + '(' + str(c['id']) + ')' for c in search_products({'query': '\n'.join(x[2] for x in items), 'limit': 5})['candidates'])}",
389
+ f"可选候选:{'、'.join(c['name'] + '(' + str(c['id']) + ')' for c in search_products({'query': '\n'.join(x[2] for x in items), 'limit': 5})['candidates'])}"
390
+ + (tail if stop else ""),
379
391
  code=_UNRESOLVED_CODE)
380
392
  if os.environ.get("VOD_ALLOW_UNKNOWN_PRODUCT") == "1":
381
393
  # 旧客户端兼容(业界口径:可选字段 + 明确默认值,不做破坏性变更):
@@ -431,6 +443,8 @@ def _remember_attribution(result: dict, client_info: dict | None = None) -> None
431
443
  """
432
444
  # 会话记忆(D-product-ask-1):只记「有证据/用户明确回答/用户说不知道」三种
433
445
  src = result.get("source")
446
+ if result.get("product"):
447
+ _memory_put(client_info, ask_failures=0)
434
448
  if src in ("user_input", "user_answer"):
435
449
  _memory_put(client_info, product=result.get("product"),
436
450
  productName=result.get("productName"),
@@ -756,7 +770,7 @@ def submit_voices(params: dict, client_info: dict | None = None,
756
770
  code=-32012)
757
771
 
758
772
  # 缺产品且用户没说不知道 → 可执行错误(先问一次),不许裸提交 UNKNOWN
759
- _require_product_or_ask(attr, items)
773
+ _require_product_or_ask(attr, items, client_info)
760
774
  # ---- 主路径:囤积端点批式提交 ----
761
775
  # 分类白名单按产品取(引擎 ?productId= 下发);product 非数字 id 时取不到→不过滤
762
776
  allowed_tags = _allowed_tags(product)