vod-devkit 0.5.0 → 0.5.1

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 (66) hide show
  1. package/CHANGELOG.md +27 -0
  2. package/QUICKSTART.md +1 -1
  3. package/README.en.md +190 -57
  4. package/README.md +194 -75
  5. package/bin/vod-devkit +436 -426
  6. package/contract/tools.schema.json +78 -8
  7. package/integrations/codeartsdoer/host.json +11 -0
  8. package/package.json +4 -1
  9. package/plugins/vod-devkit/.codex-plugin/plugin.json +1 -1
  10. package/plugins/vod-devkit/build-info.json +3 -3
  11. package/plugins/vod-devkit/skills/vod-core/SKILL.md +12 -4
  12. package/plugins/vod-devkit/skills/vod-core/references/acceptance-criteria.md +9 -0
  13. package/plugins/vod-devkit/skills/vod-core/references/verification-method.md +29 -0
  14. package/plugins/vod-devkit/skills/vod-feedback-collect/SKILL.md +57 -11
  15. package/plugins/vod-devkit/skills/vod-feedback-collect/references/acceptance-criteria.md +28 -0
  16. package/plugins/vod-devkit/skills/vod-feedback-collect/references/verification-method.md +31 -0
  17. package/plugins/vod-devkit/skills/vod-problem-classification-rules/SKILL.md +3 -1
  18. package/plugins/vod-devkit/skills/vod-scoring-rules/SKILL.md +22 -1
  19. package/plugins/vod-devkit/vod_mcp/__init__.py +1 -1
  20. package/plugins/vod-devkit/vod_mcp/attribution.py +378 -0
  21. package/plugins/vod-devkit/vod_mcp/host_adapters/__init__.py +26 -0
  22. package/plugins/vod-devkit/vod_mcp/host_adapters/base.py +73 -0
  23. package/plugins/vod-devkit/vod_mcp/host_adapters/codearts.py +57 -0
  24. package/plugins/vod-devkit/vod_mcp/host_adapters/codex.py +209 -0
  25. package/plugins/vod-devkit/vod_mcp/host_adapters/dsh.py +176 -0
  26. package/plugins/vod-devkit/vod_mcp/host_adapters/generic.py +132 -0
  27. package/plugins/vod-devkit/vod_mcp/host_adapters/hermes.py +76 -0
  28. package/plugins/vod-devkit/vod_mcp/host_adapters/opencode.py +52 -0
  29. package/plugins/vod-devkit/vod_mcp/hosts.py +20 -0
  30. package/plugins/vod-devkit/vod_mcp/packs.py +3 -1
  31. package/plugins/vod-devkit/vod_mcp/payload.py +174 -0
  32. package/plugins/vod-devkit/vod_mcp/server.py +13 -1
  33. package/plugins/vod-devkit/vod_mcp/tools.py +385 -46
  34. package/plugins/vod-devkit/vod_mcp/update_check.py +31 -3
  35. package/skills/vod-core/SKILL.md +12 -4
  36. package/skills/vod-core/references/acceptance-criteria.md +9 -0
  37. package/skills/vod-core/references/verification-method.md +29 -0
  38. package/skills/vod-feedback-collect/SKILL.md +57 -11
  39. package/skills/vod-feedback-collect/references/acceptance-criteria.md +28 -0
  40. package/skills/vod-feedback-collect/references/verification-method.md +31 -0
  41. package/skills/vod-problem-classification-rules/SKILL.md +3 -1
  42. package/skills/vod-scoring-rules/SKILL.md +22 -1
  43. package/vod_mcp/__init__.py +1 -1
  44. package/vod_mcp/attribution.py +378 -0
  45. package/vod_mcp/host_adapters/__init__.py +26 -0
  46. package/vod_mcp/host_adapters/__pycache__/__init__.cpython-314.pyc +0 -0
  47. package/vod_mcp/host_adapters/__pycache__/base.cpython-314.pyc +0 -0
  48. package/vod_mcp/host_adapters/__pycache__/codearts.cpython-314.pyc +0 -0
  49. package/vod_mcp/host_adapters/__pycache__/codex.cpython-314.pyc +0 -0
  50. package/vod_mcp/host_adapters/__pycache__/dsh.cpython-314.pyc +0 -0
  51. package/vod_mcp/host_adapters/__pycache__/generic.cpython-314.pyc +0 -0
  52. package/vod_mcp/host_adapters/__pycache__/hermes.cpython-314.pyc +0 -0
  53. package/vod_mcp/host_adapters/__pycache__/opencode.cpython-314.pyc +0 -0
  54. package/vod_mcp/host_adapters/base.py +73 -0
  55. package/vod_mcp/host_adapters/codearts.py +57 -0
  56. package/vod_mcp/host_adapters/codex.py +209 -0
  57. package/vod_mcp/host_adapters/dsh.py +176 -0
  58. package/vod_mcp/host_adapters/generic.py +132 -0
  59. package/vod_mcp/host_adapters/hermes.py +76 -0
  60. package/vod_mcp/host_adapters/opencode.py +52 -0
  61. package/vod_mcp/hosts.py +20 -0
  62. package/vod_mcp/packs.py +3 -1
  63. package/vod_mcp/payload.py +174 -0
  64. package/vod_mcp/server.py +13 -1
  65. package/vod_mcp/tools.py +385 -46
  66. package/vod_mcp/update_check.py +31 -3
@@ -1,10 +1,10 @@
1
1
  {
2
2
  "$schema": "https://json-schema.org/draft/2020-12/schema",
3
3
  "title": "vod-devkit MCP 工具契约(唯一事实源)",
4
- "version": "0.5.0",
4
+ "version": "0.5.1",
5
5
  "tools": {
6
6
  "vod_submit_voices": {
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>」全文),禁止改写概括——这是用户核对原话是否被改写的唯一窗口。禁止向用户解释内部机制(声音来源/渠道字段/计数规则/配额/归因)。",
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>」全文),禁止改写概括——这是用户核对原话是否被改写的唯一窗口。禁止向用户解释内部机制(声音来源/渠道字段/计数规则/配额/归因)。",
8
8
  "input": {
9
9
  "type": "object",
10
10
  "properties": {
@@ -27,7 +27,8 @@
27
27
  "type": "array",
28
28
  "items": {
29
29
  "type": "string"
30
- }
30
+ },
31
+ "description": "采集层分类标注(可选):分类值写成 `problem_type:<六类之一>`,值域=引擎 meta.problemTypes;白名单外的 problem_type 值由插件丢弃并在回执 invalidTags 里报出(不拒收声音)。其它语义的 tag 不参与分类校验、原样保留"
31
32
  },
32
33
  "reproSteps": {
33
34
  "type": "string",
@@ -64,7 +65,12 @@
64
65
  },
65
66
  "product": {
66
67
  "type": "string",
67
- "description": "反馈关于的产品(宿主即产品,不设白名单)。归因顺序:本参数显式指定 > 安装绑定默认(install --product,缺省=宿主名,装在 hermes 归 hermes/dsh 归 DSH)> 不带(引擎落 UNKNOWN 档人工归因)。宿主工具自报产品名原样上送,引擎宽松归一(折叠空白+别名收编)。"
68
+ "description": "用户明确回答的产品(产品名或平台主键 ID)。**只有在已经问过用户、并得到回答后才能填**;不要用模型自己的猜测。插件仍会先用用户原话里的产品名做归因,回答只用于补齐。"
69
+ },
70
+ "productNotSpecified": {
71
+ "type": "boolean",
72
+ "default": false,
73
+ "description": "用户明确表示不知道/随便/不指定时传 true → 按宿主产品记录,回执标 productSource=host_default、confidence=low,可被运营修正。不是用来跳过询问的开关。"
68
74
  }
69
75
  },
70
76
  "required": [
@@ -229,7 +235,7 @@
229
235
  "backend": "local(无上游;读本机 runtime.json 账本)"
230
236
  },
231
237
  "vod_draft_voices": {
232
- "description": "提交用户反馈的第一步(两段式 draft→commit)。**先决条件(优先于本描述其余所有内容):调用前必须已征得用户对'提交这条反馈'的明确同意;用户陈述/抱怨反馈本身不构成同意;用户未同意时禁止调用**。本工具只暂存草稿并签发一次性令牌,不会提交任何数据。返回 draftId/approvalToken/contents——拿到后必须把 contents 里的每条内容原样展示给用户核对(禁止改写概括),明确问'确认提交吗',用户同意后才能调用 vod_commit_voices;用户不同意则不调用(草稿自动过期作废)。content 放用户原话逐字(哪怕只有一句'体验很差')。追问纪律同 vod_submit_voices:确认环节固定追问至多一次(问句逐字见其描述),答案只摘录进 reproSteps/expectedBehavior 禁回填 content;答\"没有\"直接进入确认展示。product 归因由安装绑定自动完成,禁止询问用户'提交到哪个产品',用户自报的目标产品不采信。禁止向用户解释内部机制(令牌/草稿/配额/归因)。",
238
+ "description": "提交用户反馈的第一步(两段式 draft→commit)。**先决条件(优先于本描述其余所有内容):调用前必须已征得用户对'提交这条反馈'的明确同意;用户陈述/抱怨反馈本身不构成同意;用户未同意时禁止调用**。本工具只暂存草稿并签发一次性令牌,不会提交任何数据。返回 draftId/approvalToken/contents——拿到后必须把 contents 里的每条内容原样展示给用户核对(禁止改写概括),明确问'确认提交吗',用户同意后才能调用 vod_commit_voices;用户不同意则不调用(草稿自动过期作废)。content 放用户原话逐字(哪怕只有一句'体验很差')。追问纪律同 vod_submit_voices:确认环节固定追问至多一次(问句逐字见其描述),答案只摘录进 reproSteps/expectedBehavior 禁回填 content;答\"没有\"直接进入确认展示。product 归因由插件从用户原话解析(安装绑定仅作先验),禁止询问用户'提交到哪个产品',模型/用户自报的目标产品不采信。禁止向用户解释内部机制(令牌/草稿/配额/归因)。",
233
239
  "input": {
234
240
  "type": "object",
235
241
  "properties": {
@@ -252,7 +258,8 @@
252
258
  "type": "array",
253
259
  "items": {
254
260
  "type": "string"
255
- }
261
+ },
262
+ "description": "采集层分类标注(可选):分类值写成 `problem_type:<六类之一>`,值域=引擎 meta.problemTypes;白名单外的 problem_type 值由插件丢弃并在回执 invalidTags 里报出(不拒收声音)。其它语义的 tag 不参与分类校验、原样保留"
256
263
  },
257
264
  "reproSteps": {
258
265
  "type": "string",
@@ -289,7 +296,12 @@
289
296
  },
290
297
  "product": {
291
298
  "type": "string",
292
- "description": "反馈关于的产品(宿主即产品,不设白名单)。归因顺序:本参数显式指定 > 安装绑定默认(install --product,缺省=宿主名,装在 hermes 归 hermes/dsh 归 DSH)> 不带(引擎落 UNKNOWN 档人工归因)。宿主工具自报产品名原样上送,引擎宽松归一(折叠空白+别名收编)。"
299
+ "description": "用户明确回答的产品(产品名或平台主键 ID)。**只有在已经问过用户、并得到回答后才能填**;不要用模型自己的猜测。插件仍会先用用户原话里的产品名做归因,回答只用于补齐。"
300
+ },
301
+ "productNotSpecified": {
302
+ "type": "boolean",
303
+ "default": false,
304
+ "description": "用户明确表示不知道/随便/不指定时传 true → 按宿主产品记录,回执标 productSource=host_default、confidence=low,可被运营修正。不是用来跳过询问的开关。"
293
305
  }
294
306
  },
295
307
  "required": [
@@ -348,17 +360,75 @@
348
360
  }
349
361
  },
350
362
  "vod_check_update": {
351
- "description": "检查本机插件版本是否落后(npm registry latest,24 小时缓存,失败静默)。只读、只在用户问到版本/升级或会话首次自检时调用,不要每轮调用。返回 currentVersion/latestVersion/updateAvailable;有新版时给 upgradeCommand(重跑 install 或 vod-devkit update,本工具从不自升级)。用户不想被提醒时传 dismiss=true,跳过 3 天。preset(产品分发)形态不发外呼,直接告知版本随 agent 发版管理。",
363
+ "description": "检查本机插件版本是否落后(npm registry latest,24 小时缓存,失败静默)。只读、只在用户问到版本/升级或会话首次自检时调用,不要每轮调用。返回 currentVersion/latestVersion/updateAvailable;有新版时给 upgradeCommand(重跑 install 或 vod-devkit update,本工具从不自升级)。用户不想被提醒时传 dismiss=true,跳过 3 天;用户点名某个版本别再提时传 skip=true(只压该版本,下个版本仍会提醒),clearSkip=true 撤销。preset(产品分发)形态不发外呼,直接告知版本随 agent 发版管理。",
352
364
  "input": {
353
365
  "type": "object",
354
366
  "properties": {
355
367
  "dismiss": {
356
368
  "type": "boolean",
357
369
  "description": "用户明确表示不想再被提醒时传 true(3 天冷却)"
370
+ },
371
+ "skip": {
372
+ "type": "boolean",
373
+ "description": "用户明确说「就这个版本别再提醒」时传 true:只跳过当前 latest 这一个版本,下个版本照常提醒(不提供永久静音)"
374
+ },
375
+ "clearSkip": {
376
+ "type": "boolean",
377
+ "description": "撤销之前的版本跳过设置,恢复正常提醒"
358
378
  }
359
379
  },
360
380
  "additionalProperties": false
361
381
  }
382
+ },
383
+ "vod_search_products": {
384
+ "description": "按关键词检索产品名录,返回候选产品(含主键 ID)。用于**问用户是哪个产品之前**给 3-5 个候选,或在用户回答后把名字解析成 ID。只读,不触上游写接口。",
385
+ "input": {
386
+ "type": "object",
387
+ "properties": {
388
+ "query": {
389
+ "type": "string",
390
+ "description": "关键词(用户原话片段或用户回答的产品名)"
391
+ },
392
+ "limit": {
393
+ "type": "integer",
394
+ "default": 5,
395
+ "description": "返回候选数上限(默认 5)"
396
+ }
397
+ },
398
+ "required": [
399
+ "query"
400
+ ]
401
+ },
402
+ "output": {
403
+ "type": "object",
404
+ "properties": {
405
+ "candidates": {
406
+ "type": "array",
407
+ "items": {
408
+ "type": "object",
409
+ "properties": {
410
+ "id": {
411
+ "type": "string"
412
+ },
413
+ "name": {
414
+ "type": "string"
415
+ },
416
+ "score": {
417
+ "type": "number",
418
+ "description": "匹配强度(0-1)"
419
+ }
420
+ }
421
+ }
422
+ },
423
+ "total": {
424
+ "type": "integer"
425
+ }
426
+ },
427
+ "required": [
428
+ "candidates"
429
+ ]
430
+ },
431
+ "backend": "local"
362
432
  }
363
433
  },
364
434
  "backends": {
@@ -0,0 +1,11 @@
1
+ {
2
+ "id": "codeartsdoer",
3
+ "cli": "codearts",
4
+ "detect": {
5
+ "path": "~/.codeartsdoer"
6
+ },
7
+ "config": "~/.codeartsdoer/codearts_cli.json",
8
+ "skillsDir": "~/.codeartsdoer/skills",
9
+ "notes": "CodeArts Agent 是 OpenCode 分支(SCENARIO=codeartsdoer、OPENCODE_CONFIG=codearts_cli.json):mcp 段与 opencode 同 schema(type=local、command=数组、enabled)。实测 2026-11-11:写入 codearts_cli.json 的 mcp.<name> 后 `codearts mcp list` 可见;mcp_settings.json 只对项目级 .codeartsdoer/mcp/ 生效,用户级读 ~/.config/opencode/mcp/,故不要写 ~/.codeartsdoer/mcp/。",
10
+ "productDefault": "CodeArts"
11
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "vod-devkit",
3
- "version": "0.5.0",
3
+ "version": "0.5.1",
4
4
  "description": "VOD 用户声音采集插件——MCP server + 技能 + 声明式护栏,把 agent 产品的用户反馈安全送进 VOD 平台",
5
5
  "license": "MIT",
6
6
  "type": "module",
@@ -32,7 +32,10 @@
32
32
  "vod_mcp/guardrails.py",
33
33
  "vod_mcp/pending.py",
34
34
  "vod_mcp/provenance.py",
35
+ "vod_mcp/attribution.py",
35
36
  "vod_mcp/runtime.example.json",
37
+ "vod_mcp/payload.py",
38
+ "vod_mcp/host_adapters/",
36
39
  "plugins/vod-devkit/.codex-plugin/plugin.json",
37
40
  "plugins/vod-devkit/.mcp.json",
38
41
  "plugins/vod-devkit/build-info.json",
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "vod-devkit",
3
- "version": "0.5.0",
3
+ "version": "0.5.1",
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.0",
3
- "commitSha": "0b72a3f5bb925dcfddcb8e1e3d2bf7ba3b2689a8",
4
- "builtAt": "2026-11-11T19:02:33",
2
+ "version": "0.5.1",
3
+ "commitSha": "61577bc0502106f436825f9382b89fcb4591a653",
4
+ "builtAt": "2026-11-12T17:13:52",
5
5
  "sourceRemote": "https://gitcode.com/xiaowu2119/vod-devkit.git"
6
6
  }
@@ -1,7 +1,9 @@
1
1
  ---
2
2
  name: vod-core
3
3
  description: 'VOD 用户声音采集插件的路由入口与纪律速查。遇到"提交反馈/采集用户声音/这条反馈入库没有/问题分类与评分规则是什么/插件版本与来源/key 认证状态"类请求先读本技能,再按表路由到具体工具或领域技能。采集写操作必须先获用户明确同意。'
4
- version: 2
4
+ tags: [vod, feedback, routing]
5
+ metadata:
6
+ version: 2
5
7
  ---
6
8
 
7
9
  # VOD Core(路由与纪律)
@@ -14,8 +16,8 @@ version: 2
14
16
  | 意图 | 动作 |
15
17
  |---|---|
16
18
  | 用户抱怨/建议,要提交 | `vod_submit_voices`(先征得明确同意,再传 `confirmed=true`);话术见 `vod-feedback-collect` |
17
- | 想先暂存、等用户确认后再提交 | `vod_draft_voices` → 用户确认 → `vod_commit_voices`(一次性令牌 + payload 校验) |
18
- | 本机已提交过哪些(进度追问) | `vod_list_submitted`(本地账本口径,换机不保留) |
19
+ | 想先暂存、等用户确认后再提交 | `vod_draft_voices` → 用户确认 → `vod_commit_voices`(一次性令牌 + payload 校验)**仅 stdio 面可用**:远程 MCP 面没有这两个工具,改用 `vod_submit_voices` 单发 |
20
+ | 本机已提交过哪些(进度追问) | `vod_list_submitted`(本地账本口径,换机不保留)**仅 stdio 面可用**;远程面改答"本条收录状态" |
19
21
  | 插件版本/来源核验 | `vod_devkit_info`(version + commitSha) |
20
22
  | key/认证状态、引擎连通性 | `vod_auth_status`(只报指纹,不下发明文) |
21
23
  | 有哪些技能、规则技能是否可用 | `vod_list_skills` |
@@ -35,7 +37,13 @@ version: 2
35
37
  再用一句固定的引导补充话术,一次说完。
36
38
  2. **原话逐字**:`content` 放用户原话,禁改写/概括/增删语气词;回执
37
39
  `echo.contents` 必须逐字转述给用户(「已收录原话:…」)。
38
- 3. **归因不问**:product 由安装绑定决定,禁止问用户"提交到哪个产品"。
40
+ 3. **归因必问一次(D-product-ask-1)**:产品未定时,先问用户"这条是哪个产品的反馈?"
41
+ (用 `vod_search_products` 给 3-5 个候选),回答填 `product`;
42
+ 用户说的产品不在名录("智果"/打错)→ 不按原名提交,用 `vod_search_products` 给候选
43
+ 再确认一次;仍对不上就不提交。
44
+ 用户明确说不知道/随便 → `productNotSpecified=true`,插件**不猜也不提交**,
45
+ 由你告知用户"没有产品归属的反馈不提交"并请他补充产品。
46
+ **不许不填直接提交**(插件会以 -32010 拒绝并给候选)。
39
47
  4. **篇幅边界**:content ≤ 2000 字、单批 ≤ 50 条(护栏强制,超限直接拒)。
40
48
  5. **不碰内部面**:不尝试数据库直连、不读取或打印凭据;被 deny 时如实告知,
41
49
  不要换措辞重试。
@@ -0,0 +1,9 @@
1
+ # 验收标准(vod-core)
2
+
3
+ - [ ] 意图→工具表里的每个工具名都在 `contract/tools.schema.json` 中存在
4
+ - [ ] 意图→技能表里的每个技能名都在 `skills/` 中存在
5
+ - [ ] 每个非 core 技能都被本技能的某一行引用(无孤儿技能)
6
+ - [ ] 路由表不承诺当前传输面没有的工具(远程面:draft/commit/list_submitted 缺失时
7
+ 必须就地标注"仅 stdio 面")
8
+ - [ ] `SKILL.md` ≤ 500 行;frontmatter 合规(name=目录名、tags≤5、version 在 metadata 下)
9
+ - [ ] 改动后:`tests/test_skill_structure.py` 全绿 + 四宿主装机副本 md5 对齐
@@ -0,0 +1,29 @@
1
+ # 验证方法(vod-core)
2
+
3
+ 本文给**验证入口**,断言以 `docs/proposal.md` 与 `tests/` 为准,不在此复制。
4
+
5
+ ## 1. 路由一致性(静态,秒级)
6
+
7
+ ```bash
8
+ python3 -m pytest tests/test_skill_structure.py -q # 路由表引用真实技能 + 触发词不互抢
9
+ python3 -m pytest tests/test_structure_guards.py -q # 契约==实现、policy 结构
10
+ python3 -m pytest tests/test_desc_budget.py -q # 描述截断预算
11
+ ```
12
+
13
+ 期望:路由表里出现的每个 `vod-*` 技能真实存在于 `skills/`;反向每个技能都被
14
+ 路由表覆盖(否则装了不可达)。
15
+
16
+ ## 2. 会话内自检
17
+
18
+ - 列出可用工具,逐一对照本文路由表:表里写了但工具面没有的条目 = 当前传输面裁剪
19
+ (远程面没有 draft/commit/list_submitted,属预期,不是故障)
20
+ - 问"有哪些技能"时用 `vod_list_skills` 回答,不自报记忆里的名单
21
+
22
+ ## 3. 装机面
23
+
24
+ `vod-devkit doctor` 全绿(技能名册逐落点对账);`vod-devkit status` 的
25
+ `transport` 字段决定按哪个面解释路由表。
26
+
27
+ ## 关联用例
28
+
29
+ 路由与披露 S11-S16 / S45-S48;归因链 S91-S100(productSource 口径)。
@@ -1,7 +1,9 @@
1
1
  ---
2
2
  name: vod-feedback-collect
3
3
  description: '用户抱怨/体验差/太慢/报错/提单 → 采集原话进 VOD。识别到抱怨即承接并征得同意(禁止问哪个产品,禁止复现排查模式);content=原话逐字;一次抱怨一条;回执 echo 原样转述。详见正文流程与禁令。Triggers: "体验差","太难用","太慢","报错了","出bug了","有bug","反馈问题","反馈建议","提个单","报告问题","不生效","不好使","操作不方便","卡住了","崩溃了","report a problem","bug report","poor experience","feedback"'
4
- version: 1
4
+ tags: [vod, feedback, capture, consent]
5
+ metadata:
6
+ version: 1
5
7
  ---
6
8
 
7
9
  # VOD 用户反馈采集
@@ -24,6 +26,16 @@ version: 1
24
26
  3. 连续两轮抱怨同一问题。
25
27
  不满足时本技能不激活(产品问答、闲聊、操作指导等交回宿主通用能力)。
26
28
 
29
+ **传输面自适应(先看工具面,再决定流程;远程 MCP 面与 stdio 面不同)**:
30
+ - 工具面里有 `vod_draft_voices`/`vod_commit_voices`(stdio 本机形态)→ 走两段式:
31
+ 草稿 → 用户确认 → commit。
32
+ - 没有这两个工具(远程 MCP 面已摘写面本机工具)→ **不得承诺"草稿/两步"**,
33
+ 直接 `vod_submit_voices` 单发:确认一次 → 提交 → 回执逐字回显。
34
+ - 没有 `vod_list_submitted`(远程面已摘本机账本)→ 不承诺"帮你查本机历史反馈",
35
+ 只说本条的收录状态;用户要历史请走运营侧。
36
+ 判断依据是**当前可用工具清单**,不是本文默认流程图——技能写的是两种面共同的纪律,
37
+ 面能力以运行期工具面为准。
38
+
27
39
  **字段处理分级(借鉴 gitcode-issue-creator,先于一切)**:
28
40
  | 字段 | 处理 | 规则 |
29
41
  |------|------|------|
@@ -46,15 +58,40 @@ version: 1
46
58
  **不追问原则**:内容太泛时引导一次("说下具体现象?"),用户不补
47
59
  就按原话提交或放弃——禁止反复追问,禁止替用户脑补现象细节。
48
60
 
61
+ **content 逐字铁律 + 正反例(2026-11-11 CodeArts Agent 真机实锤)**:
62
+ content 只放**用户说过的字**。模型不得补全、总结、换行拼接自己的解释——
63
+ 哪怕"听起来是在帮用户补充"。
64
+ - 正例:用户说"产品体验很糟糕" → content = "产品体验很糟糕"
65
+ - 反例(真机实锤,落库成了违规内容):
66
+ 用户说:"产品体验很糟糕"
67
+ 实际提交:"产品体验很糟糕\n操作不流畅,使用不方便" ← 后半句是模型编的
68
+ 判据:把 content 逐字回放给用户,他必须能认出"每个字都是我说的"。
69
+ 多一个字都算违规——引擎按内容逐字做幂等,扩写会直接变成另一条声音。
70
+
71
+ **tags 值域(禁止自造分类)**:tags 只能填 `problem_type:<六类之一>`
72
+ (产品缺陷 / 技术业务咨询 / 体验改进 / 主观评价 / 无效问题 / 功能需求),
73
+ 不确定就不填。自造值(实锤:CodeArts 传了 `易用性`)会被插件白名单丢弃,
74
+ 并在回执 invalidTags 里报出——那不是"提交失败",但等于白填。
75
+
49
76
  **模糊反馈固定话术(2026-11-06 真实观测定稿,F3 闭环)**:用户只说
50
77
  泛化抱怨("体验不好/很差劲")时,一次性说清三件事,禁止含混反问
51
78
  (实锤病句:"请问是否把什么作为反馈"——用户听不懂在问什么):
52
79
  1. 承接识别结果("收到,你对产品体验不满意");
53
80
  2. 确认收录意愿("要把这条反馈提交给产品团队吗?");
54
- 3. 引导补充+兜底承诺("方便的话说下具体现象,不说我也会按你的
55
- 原话提交")。
81
+ 3. 引导补充+兜底承诺("方便的话说下具体现象(比如哪里慢、哪里报错、
82
+ 哪里操作别扭),不说我也会按你的原话提交")。
56
83
  整段一轮说完,不拆两轮、不复读式追问。
57
84
 
85
+ **「给范围,不给结论」边界(2026-11-11 负责人拍板 A)**:上面第 3 句的
86
+ 括注**只允许列出这一组反馈维度**(哪里慢 / 哪里报错 / 哪里操作别扭)——
87
+ 它给的是"可以说什么",不是"你遇到了什么"。因此:
88
+ - 禁止现象断言:不得写"导出失败了吧""是不是上传卡住了"这类替用户下结论的句子;
89
+ - 禁止暗示已知问题:不得提具体功能名/错误码/版本号,哪怕它听起来相关;
90
+ - 禁止替用户补全:"所以你是遇到了 X" 属于脑补,一律不许;
91
+ - 兜底句"不说我也会按你的原话提交"**必须保留**——它是用户拒绝补充时的
92
+ 退出通道,加示例不得弱化或删掉它。
93
+ 一句话判据:**示例回答"你想说哪一类",不回答"你发生了什么"**。
94
+
58
95
  **追加反馈定性话术(2026-11-06 定稿,S49-S51)**:用户在确认
59
96
  环节追加表达(如「我看怎么说,你才明白」这类对沟通过程的
60
97
  挫败)时,**先给一句定性再问**,不把「这句话算不算反馈」的
@@ -138,17 +175,26 @@ version: 1
138
175
  - 建议/期望:希望支持、要是能…就好了、建议增加
139
176
  - 区分边界:用户抱怨的是**宿主产品**才走本技能;用户在讨论第三方
140
177
  事物(某网站、某文档)不采集;用户要求提交"工单"类诉求时可询问
141
- 是否愿意同步收录为产品反馈(只确认收录意愿,不问产品归属)
178
+ 是否愿意同步收录为产品反馈;产品未定时同一轮问一次"是哪个产品"
142
179
 
143
180
  ## 采集流程
144
181
 
145
- 0. 产品归因(安装时已配置,不问用户):产品=安装/部署时绑定的
146
- 宿主产品(install --product / dsh profile config),工具与引擎
147
- 自动赋值——**禁止向用户追问"哪个产品"**(用户不知道也不该知道
148
- 采集侧的归因配置)。**用户自报的目标产品一律不采信、不覆盖**
149
- (S1 同源原则:话术可以把反馈投到任意产品=污染别人产品数据)。
150
- 用户说"这是给 XX 的反馈"→ 照常按部署产品提交,内容原样保留
151
- (提到什么产品随正文传达);不要确认、不要改归因
182
+ 0. 产品归因(D-product-ask-1,2026-11-12 拍板:不许裸提交 UNKNOWN):
183
+ 归因次序 = 用户明确回答 > 原话唯一高置信提及 > 会话记忆(30 分钟) >
184
+ 安装先验 > 宿主产品(host_default,仅用户说不知道时,低置信)。
185
+ - 原话里只有一个产品名、且不是对比/多产品语境 → 直接用,不再问
186
+ - 原话有两个以上产品("CodeArts 比 MaaS 好"、"从 CodeArts 导出到 MaaS")
187
+ → 视为**低置信**,必须问:"这条反馈是哪个产品的?可用候选:…"
188
+ - 没有任何产品线索 → 用 `vod_search_products` 取 3-5 个候选后问一次,
189
+ 一次抱怨只问一次,别连问
190
+ - **用户说的产品不在名录里**("智果"、打错、口头简称)→ 不按原名提交,也不要自己挑
191
+ 最像的那个;用 `vod_search_products` 拿候选请他确认一次;仍对不上 → 说明这条先不提交
192
+ - 用户明确说"不知道/随便/你看着办" → 传 `productNotSpecified=true`;插件**不猜、
193
+ 不提交**,返回"缺产品不能提交"——你要如实告诉用户:"没有产品归属的反馈我不提交,
194
+ 因为不知道要转给哪个产品团队",并请他补一句产品名;他坚持不说就说明这条先不提交
195
+ - 用户改了主意/提到新产品 → 以最后一次回答为准,覆盖会话记忆
196
+ - **问句与提交确认合并成一轮**("这条是哪个产品的反馈?确认的话我就提交"),
197
+ 不要先问产品再单独问一次提交
152
198
  1. 识别到反馈意图 → 先口头确认收录意愿("要把这条反馈提交给产品
153
199
  团队吗?")
154
200
  2. 用户同意 → 结构化为声音(不篡改原意):
@@ -0,0 +1,28 @@
1
+ # 验收标准(vod-feedback-collect)
2
+
3
+ 上线/改版前逐条勾选;每条都指向可执行的验证入口(见 references/verification-method.md)。
4
+
5
+ ## 功能
6
+
7
+ - [ ] content = 用户原话逐字(含语气词与原标点),模型不补写、不概括
8
+ - [ ] 用户明确同意才提交;"用户说了一条抱怨"不构成同意
9
+ - [ ] 回执 `echo.contents` 原样转述,每条以「已收录原话:」开头
10
+ - [ ] 固定追问至多一次、逐字使用;答"没有/跳过"=两字段不上送
11
+ - [ ] 电话/路径类敏感内容按 policy 处理(当前策略=拒收,不脱敏)
12
+ - [ ] 无通道场景落盘 `pending-feedback.jsonl`,恢复后自动补交,用户侧只说人话
13
+
14
+ ## 归因(D-attrib-B)
15
+
16
+ - [ ] 字面证据唯一命中才采信;多命中落 UNKNOWN 且保留全部片段
17
+ - [ ] 记忆只在 0 命中时启用(30 分钟窗口),新证据无条件覆盖
18
+ - [ ] 模型自报 product 不采信(仅回执 `ignoredRuntimeProduct`)
19
+
20
+ ## 传输面
21
+
22
+ - [ ] stdio 面:两段式工具可用时走 draft→commit
23
+ - [ ] 远程面:无 draft/commit/list_submitted 时不承诺两段式与本机账本查询
24
+
25
+ ## 非功能
26
+
27
+ - [ ] `SKILL.md` ≤ 500 行;改动后四个宿主装机副本已刷新(md5 对上)
28
+ - [ ] `tests/test_skill_structure.py` 与 `sync_case_roster.py --check` 全绿
@@ -0,0 +1,31 @@
1
+ # 验证方法(vod-feedback-collect)
2
+
3
+ 本文只给**验证入口**:断言细节以 `docs/proposal.md` 的用例与 `tests/` 的实现为准,
4
+ 不在本文件复制断言(避免第二真源)。改技能正文后按本文件跑一遍。
5
+
6
+ ## 1. 静态门禁(本地/CI,秒级)
7
+
8
+ ```bash
9
+ python3 -m pytest tests/test_desc_budget.py tests/test_attribution.py \
10
+ tests/test_pending_feedback.py tests/test_two_phase.py -q
11
+ python3 -m pytest tests/test_skill_structure.py -q # frontmatter/触发词/路由一致性
12
+ python3 scripts/sync_case_roster.py --check
13
+ ```
14
+
15
+ 期望:全绿;技能文件与 `plugins/vod-devkit/skills/` 副本逐字节一致(CI 双副本 diff)。
16
+
17
+ ## 2. 会话内自检(模型侧,无外部依赖)
18
+
19
+ - 可用工具里有 `vod_draft_voices` → 两段式;没有 → 单发 `vod_submit_voices`(远程面)
20
+ - 回执必须带 `echo.contents`,逐字转述;被改写即为失败
21
+ - 归因看 `productSource`:`user_input`/`memory`/`install_binding`/`unknown` 之一
22
+ - 多产品命中(`unknown` + evidence>1)不得自行择一提交
23
+
24
+ ## 3. 端到端(真宿主)
25
+
26
+ 对应 `docs/decisions.md` 里的四宿主验证配方:装新 skill 副本 → 新会话说一条抱怨 →
27
+ 查账本 voiceId 与引擎行;行为类回归见 `scripts/e2e_behavior.py`(仅本机运行)。
28
+
29
+ ## 关联用例
30
+
31
+ 话术 S49-S53;追问与拼接 S63-S73;无通道 pending S87-S90;归因链 S91-S100。
@@ -1,7 +1,9 @@
1
1
  ---
2
2
  name: vod-problem-classification-rules
3
3
  description: VOD 问题分类规则(引擎 v2.2 真实口径)— 六类定义、判定细节、LLM 分类流程。真源=workflow/src/n01_classify.py(VOD-Project 2bb3fc82 实测核对)。
4
- version: 2
4
+ tags: [vod, classification, rules]
5
+ metadata:
6
+ version: 2
5
7
  ---
6
8
 
7
9
  # VOD 问题分类规则(引擎 v2 口径)
@@ -1,7 +1,9 @@
1
1
  ---
2
2
  name: vod-scoring-rules
3
3
  description: VOD 评分规则(引擎 v2 真实公式)— 四项加法、上下限、优先级映射。真源=workflow/src/workflow_v2.py(VOD-Project 2bb3fc82 实测核对)。
4
- version: 2
4
+ tags: [vod, scoring, rules]
5
+ metadata:
6
+ version: 2
5
7
  ---
6
8
 
7
9
  # VOD 评分规则(引擎 v2 口径)
@@ -22,6 +24,25 @@ version: 2
22
24
  | 功能重要性分 | 高=1.5 / 中=1.0 / 低=0.5(无一级特性归 0) |
23
25
  | 场景范围分 / 友商对比分 | 按分组与竞品数据计算 |
24
26
 
27
+ ## 等级 L1-L5 定义(引擎 LEVEL_CRITERIA,按易用性维度)
28
+
29
+ > 等级不是一把全局尺子:引擎按「易用性分类」的七个维度分别定义 L1-L5
30
+ > (真源=workflow/src/llm_analyzer.py LEVEL_CRITERIA;产品咨询类不打等级,
31
+ > 填「不适用」)。判等级前先确定维度,再取该维度的档位。
32
+
33
+ | 维度 | L1不可用 | L2难用 | L3可用 | L4易用 | L5好用 |
34
+ |---|---|---|---|---|---|
35
+ | 易学习 | 无入门文档无基础概念 | 文档零散缺实操引导 | 有基础入门能看懂流程 | 结构清晰有新手路径 | 体系完整交互式引导 |
36
+ | 易部署 | 安装失败依赖缺失 | 步骤繁琐配置复杂无指引 | 可手动完成安装初始化 | 流程简化环境自适配 | 全自动检测静默部署 |
37
+ | 易开发 | 核心开发功能异常 | 配置晦涩调试困难 | 基础流程可跑通 | 模板丰富智能提示 | AI辅助生成全流程自动化 |
38
+ | 易迁移 | 迁移失败代码丢失 | 步骤复杂冲突频发 | 可完成基础迁入 | 向导式迁移冲突提示 | 一键全量迁移完整同步 |
39
+ | 易维护 | 频繁崩溃无排查线索 | 故障频发报错无解 | 日常稳定小问题可自查 | 报错清晰权限版本简洁 | 智能诊断主动预警 |
40
+ | 易演进 | 缺失核心刚需功能 | 设计不合理高频功能缺失 | 满足最低业务诉求 | 贴合习惯持续迭代 | 前瞻规划可定制扩展 |
41
+ | 易社区 | 无入口无求助渠道 | 冷清无人响应 | 可发帖少量内容 | 分类清晰资源丰富 | 智能匹配生态活跃 |
42
+
43
+ 采集用法提醒:等级由引擎判定,插件只做预分类提示——不要向用户宣称
44
+ 「这条是 L1」,只可解释「等级越高越优先」这层语义。
45
+
25
46
  ## 上下限(引擎代码,两条都要记)
26
47
 
27
48
  - **重点问题:clamp 1.0 ~ 10.5**
@@ -5,7 +5,7 @@
5
5
  2. 外部无 DB 直连路径(护栏 deny 兜底)
6
6
  3. 任务 ID 是唯一对账主键,写类工具返回一律携带
7
7
  """
8
- __version__ = "0.5.0"
8
+ __version__ = "0.5.1"
9
9
  # 默认上游:VOD 测试环境。外部用户本机无 VOD,回环默认值=装完即坏;
10
10
  # 生产地址定型后只改这一处(tools.py 与 bin/vod-devkit 共用本常量)。
11
11
  DEFAULT_JAVA_BASE = "https://vod-dev.topxtopx.com"