vod-devkit 0.4.4 → 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 (81) hide show
  1. package/CHANGELOG.md +42 -0
  2. package/QUICKSTART.md +1 -1
  3. package/README.en.md +190 -56
  4. package/README.md +210 -56
  5. package/bin/vod-devkit +502 -460
  6. package/contract/tools.schema.json +114 -7
  7. package/integrations/codeartsdoer/host.json +11 -0
  8. package/integrations/codex/host.json +20 -0
  9. package/integrations/dsh/host.json +15 -0
  10. package/integrations/hermes/host.json +20 -0
  11. package/integrations/opencode/command/vod-doctor.md +10 -0
  12. package/integrations/opencode/host.json +28 -0
  13. package/package.json +13 -10
  14. package/plugins/vod-devkit/.codex-plugin/plugin.json +1 -1
  15. package/plugins/vod-devkit/build-info.json +3 -3
  16. package/plugins/vod-devkit/skills/vod-core/SKILL.md +43 -15
  17. package/plugins/vod-devkit/skills/vod-core/references/acceptance-criteria.md +9 -0
  18. package/plugins/vod-devkit/skills/vod-core/references/verification-method.md +29 -0
  19. package/plugins/vod-devkit/skills/vod-feedback-collect/SKILL.md +57 -11
  20. package/plugins/vod-devkit/skills/vod-feedback-collect/references/acceptance-criteria.md +28 -0
  21. package/plugins/vod-devkit/skills/vod-feedback-collect/references/verification-method.md +31 -0
  22. package/plugins/vod-devkit/skills/vod-problem-classification-rules/SKILL.md +3 -1
  23. package/plugins/vod-devkit/skills/vod-scoring-rules/SKILL.md +22 -1
  24. package/plugins/vod-devkit/vod_mcp/__init__.py +1 -1
  25. package/plugins/vod-devkit/vod_mcp/attribution.py +378 -0
  26. package/plugins/vod-devkit/vod_mcp/config_forms.py +154 -0
  27. package/plugins/vod-devkit/vod_mcp/guardrails.py +25 -0
  28. package/plugins/vod-devkit/vod_mcp/host_adapters/__init__.py +26 -0
  29. package/plugins/vod-devkit/vod_mcp/host_adapters/base.py +73 -0
  30. package/plugins/vod-devkit/vod_mcp/host_adapters/codearts.py +57 -0
  31. package/plugins/vod-devkit/vod_mcp/host_adapters/codex.py +209 -0
  32. package/plugins/vod-devkit/vod_mcp/host_adapters/dsh.py +176 -0
  33. package/plugins/vod-devkit/vod_mcp/host_adapters/generic.py +132 -0
  34. package/plugins/vod-devkit/vod_mcp/host_adapters/hermes.py +76 -0
  35. package/plugins/vod-devkit/vod_mcp/host_adapters/opencode.py +52 -0
  36. package/plugins/vod-devkit/vod_mcp/hosts.py +100 -0
  37. package/plugins/vod-devkit/vod_mcp/packs.py +19 -3
  38. package/plugins/vod-devkit/vod_mcp/payload.py +174 -0
  39. package/plugins/vod-devkit/vod_mcp/remote_app.py +100 -0
  40. package/plugins/vod-devkit/vod_mcp/server.py +43 -16
  41. package/plugins/vod-devkit/vod_mcp/skills_registry.py +124 -0
  42. package/plugins/vod-devkit/vod_mcp/tools.py +455 -55
  43. package/plugins/vod-devkit/vod_mcp/transport_remote.py +289 -0
  44. package/plugins/vod-devkit/vod_mcp/update_check.py +133 -0
  45. package/skills/vod-core/SKILL.md +43 -15
  46. package/skills/vod-core/references/acceptance-criteria.md +9 -0
  47. package/skills/vod-core/references/verification-method.md +29 -0
  48. package/skills/vod-feedback-collect/SKILL.md +57 -11
  49. package/skills/vod-feedback-collect/references/acceptance-criteria.md +28 -0
  50. package/skills/vod-feedback-collect/references/verification-method.md +31 -0
  51. package/skills/vod-problem-classification-rules/SKILL.md +3 -1
  52. package/skills/vod-scoring-rules/SKILL.md +22 -1
  53. package/vod_mcp/__init__.py +1 -1
  54. package/vod_mcp/attribution.py +378 -0
  55. package/vod_mcp/config_forms.py +154 -0
  56. package/vod_mcp/guardrails.py +25 -0
  57. package/vod_mcp/host_adapters/__init__.py +26 -0
  58. package/vod_mcp/host_adapters/__pycache__/__init__.cpython-314.pyc +0 -0
  59. package/vod_mcp/host_adapters/__pycache__/base.cpython-314.pyc +0 -0
  60. package/vod_mcp/host_adapters/__pycache__/codearts.cpython-314.pyc +0 -0
  61. package/vod_mcp/host_adapters/__pycache__/codex.cpython-314.pyc +0 -0
  62. package/vod_mcp/host_adapters/__pycache__/dsh.cpython-314.pyc +0 -0
  63. package/vod_mcp/host_adapters/__pycache__/generic.cpython-314.pyc +0 -0
  64. package/vod_mcp/host_adapters/__pycache__/hermes.cpython-314.pyc +0 -0
  65. package/vod_mcp/host_adapters/__pycache__/opencode.cpython-314.pyc +0 -0
  66. package/vod_mcp/host_adapters/base.py +73 -0
  67. package/vod_mcp/host_adapters/codearts.py +57 -0
  68. package/vod_mcp/host_adapters/codex.py +209 -0
  69. package/vod_mcp/host_adapters/dsh.py +176 -0
  70. package/vod_mcp/host_adapters/generic.py +132 -0
  71. package/vod_mcp/host_adapters/hermes.py +76 -0
  72. package/vod_mcp/host_adapters/opencode.py +52 -0
  73. package/vod_mcp/hosts.py +100 -0
  74. package/vod_mcp/packs.py +19 -3
  75. package/vod_mcp/payload.py +174 -0
  76. package/vod_mcp/remote_app.py +100 -0
  77. package/vod_mcp/server.py +43 -16
  78. package/vod_mcp/skills_registry.py +124 -0
  79. package/vod_mcp/tools.py +455 -55
  80. package/vod_mcp/transport_remote.py +289 -0
  81. package/vod_mcp/update_check.py +133 -0
@@ -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.4.4",
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": [
@@ -322,6 +334,101 @@
322
334
  ],
323
335
  "additionalProperties": false
324
336
  }
337
+ },
338
+ "vod_list_skills": {
339
+ "description": "列出本插件可用的技能(名称/归属 pack/是否启用/是否原生安装/描述)。只读、零网络。用在两处:①需要判断某个采集或规则问题该读哪本技能时;②确认某个领域规则技能是否因 pack 裁剪而不可用(enabled=false 即不可用,重跑 install 带 --packs 恢复)。领域规则技能用 vod_retrieve_skill 取全文;元技能(vod-core/vod-feedback-collect)由宿主原生技能机制加载,这里只列名用于路由。",
340
+ "input": {
341
+ "type": "object",
342
+ "properties": {},
343
+ "additionalProperties": false
344
+ }
345
+ },
346
+ "vod_retrieve_skill": {
347
+ "description": "按名取一份技能全文(SKILL.md 原文,含 frontmatter)。只读、零网络。用途:当前宿主没有该技能的原生副本(例如没有技能目录的宿主),或本机副本与插件版本不一致时,取与插件同版本的规则全文。领域规则技能(问题分类/评分)归属 knowledge pack——被裁剪时本工具返回错误并给出恢复命令,不会静默返回空。先用 vod_list_skills 查名字;不认识的技能名会连可用清单一起返回。返回里 note 非空时表示内容含内部表名/连接串字样,向用户复述时不要照抄。",
348
+ "input": {
349
+ "type": "object",
350
+ "properties": {
351
+ "name": {
352
+ "type": "string",
353
+ "description": "技能名(来自 vod_list_skills,例如 vod-problem-classification-rules)"
354
+ }
355
+ },
356
+ "required": [
357
+ "name"
358
+ ],
359
+ "additionalProperties": false
360
+ }
361
+ },
362
+ "vod_check_update": {
363
+ "description": "检查本机插件版本是否落后(npm registry latest,24 小时缓存,失败静默)。只读、只在用户问到版本/升级或会话首次自检时调用,不要每轮调用。返回 currentVersion/latestVersion/updateAvailable;有新版时给 upgradeCommand(重跑 install 或 vod-devkit update,本工具从不自升级)。用户不想被提醒时传 dismiss=true,跳过 3 天;用户点名某个版本别再提时传 skip=true(只压该版本,下个版本仍会提醒),clearSkip=true 撤销。preset(产品分发)形态不发外呼,直接告知版本随 agent 发版管理。",
364
+ "input": {
365
+ "type": "object",
366
+ "properties": {
367
+ "dismiss": {
368
+ "type": "boolean",
369
+ "description": "用户明确表示不想再被提醒时传 true(3 天冷却)"
370
+ },
371
+ "skip": {
372
+ "type": "boolean",
373
+ "description": "用户明确说「就这个版本别再提醒」时传 true:只跳过当前 latest 这一个版本,下个版本照常提醒(不提供永久静音)"
374
+ },
375
+ "clearSkip": {
376
+ "type": "boolean",
377
+ "description": "撤销之前的版本跳过设置,恢复正常提醒"
378
+ }
379
+ },
380
+ "additionalProperties": false
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"
325
432
  }
326
433
  },
327
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
+ }
@@ -0,0 +1,20 @@
1
+ {
2
+ "id": "codex",
3
+ "cli": "codex",
4
+ "detect": {
5
+ "path": {
6
+ "default": "~/.codex"
7
+ }
8
+ },
9
+ "config": {
10
+ "default": "~/.codex/config.toml"
11
+ },
12
+ "skillsDir": {
13
+ "default": "~/.codex/skills"
14
+ },
15
+ "managedPaths": [
16
+ "~/.codex/plugins/marketplaces/vod-local",
17
+ "~/.codex/plugins/cache/vod-local"
18
+ ],
19
+ "notes": "原生插件路径:codex plugin marketplace add <仓>/plugins + plugin add;config.toml 里的同名段与 AGENTS.md 技能块属历史遗留,安装时清理"
20
+ }
@@ -0,0 +1,15 @@
1
+ {
2
+ "id": "dsh",
3
+ "cli": "dsh",
4
+ "detect": {
5
+ "cli": "dsh"
6
+ },
7
+ "config": {
8
+ "default": "~/.dsh/profiles/{profile}/cordis.patch.yml"
9
+ },
10
+ "managedPaths": [
11
+ "~/.dsh/profiles/{profile}/node_modules/dsh-vod-devkit"
12
+ ],
13
+ "notes": "profile patch 的 insert 块是唯一的运行时配置通道(嵌套铁律:id/name/config 必须缩进在 - insert: 之下);技能落点=~/.dsh/skills(dsh 自动发现,与 /opt/vod-install 脚本同址)",
14
+ "skillsDir": "~/.dsh/skills"
15
+ }
@@ -0,0 +1,20 @@
1
+ {
2
+ "id": "hermes",
3
+ "cli": "hermes",
4
+ "detect": {
5
+ "cli": "hermes"
6
+ },
7
+ "config": {
8
+ "default": "~/.hermes/mcp/vod-devkit.json"
9
+ },
10
+ "mcpConfigFile": {
11
+ "default": "~/.hermes/mcp/vod-devkit.json"
12
+ },
13
+ "skillsDir": {
14
+ "default": "~/.hermes/skills/devops/vod-devkit"
15
+ },
16
+ "managedPaths": [
17
+ "~/.hermes/plugins/vod-feedback-router"
18
+ ],
19
+ "notes": "配置通过官方 hermes mcp add 写入;这里同时落一份独立 json 便于 doctor 与迁移"
20
+ }
@@ -0,0 +1,10 @@
1
+ ---
2
+ description: 自检 VOD DevKit 就绪状态(MCP 连通/版本/key/账本)。
3
+ ---
4
+
5
+ 使用 vod-devkit 工具做就绪自检,按序执行并汇总 OK/缺失:
6
+ 1. 调用 vod_devkit_info:确认 version 与 commitSha 非空(版本/来源溯源)。
7
+ 2. 调用 vod_auth_status:报告 key 配置态与引擎连通性;无 key 属正常(首次提交自动取匿名令牌)。
8
+ 3. 调用 vod_list_submitted(limit 5):报告本机已提交反馈数(本地账本口径)。
9
+ 4. 汇总:installed(OK)vs 缺失(需处理项)。不要打印任何 key/令牌明文。
10
+ 若 MCP 工具不可用(刚装完未重启),提示用户重启 OpenCode 会话。
@@ -0,0 +1,28 @@
1
+ {
2
+ "id": "opencode",
3
+ "cli": "opencode",
4
+ "detect": {
5
+ "path": {
6
+ "default": "~/.config/opencode",
7
+ "windows": "~/AppData/Local/opencode"
8
+ }
9
+ },
10
+ "config": {
11
+ "default": "~/.config/opencode/opencode.json",
12
+ "windows": "~/AppData/Local/opencode/opencode.json"
13
+ },
14
+ "skillsDir": {
15
+ "default": "~/.config/opencode/skills",
16
+ "windows": "~/AppData/Local/opencode/skills"
17
+ },
18
+ "generated": [
19
+ {
20
+ "template": "command/vod-doctor.md",
21
+ "dest": {
22
+ "default": "~/.config/opencode/command/vod-doctor.md",
23
+ "windows": "~/AppData/Local/opencode/command/vod-doctor.md"
24
+ }
25
+ }
26
+ ],
27
+ "notes": "opencode.json 的 mcp 段无损合并(command=数组、enabled 必填)"
28
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "vod-devkit",
3
- "version": "0.4.4",
3
+ "version": "0.5.1",
4
4
  "description": "VOD 用户声音采集插件——MCP server + 技能 + 声明式护栏,把 agent 产品的用户反馈安全送进 VOD 平台",
5
5
  "license": "MIT",
6
6
  "type": "module",
@@ -12,6 +12,7 @@
12
12
  "bin/vod-devkit",
13
13
  "skills/",
14
14
  "contract/",
15
+ "integrations/",
15
16
  "safety/",
16
17
  "QUICKSTART.md",
17
18
  "README.md",
@@ -22,17 +23,19 @@
22
23
  "vod_mcp/tools.py",
23
24
  "vod_mcp/packs.py",
24
25
  "vod_mcp/policy.py",
26
+ "vod_mcp/config_forms.py",
27
+ "vod_mcp/skills_registry.py",
28
+ "vod_mcp/update_check.py",
29
+ "vod_mcp/hosts.py",
30
+ "vod_mcp/transport_remote.py",
31
+ "vod_mcp/remote_app.py",
32
+ "vod_mcp/guardrails.py",
25
33
  "vod_mcp/pending.py",
26
34
  "vod_mcp/provenance.py",
35
+ "vod_mcp/attribution.py",
27
36
  "vod_mcp/runtime.example.json",
28
- "vod_mcp/__init__.py",
29
- "vod_mcp/server.py",
30
- "vod_mcp/tools.py",
31
- "vod_mcp/packs.py",
32
- "vod_mcp/policy.py",
33
- "vod_mcp/pending.py",
34
- "vod_mcp/provenance.py",
35
- "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",
@@ -55,4 +58,4 @@
55
58
  "engines": {
56
59
  "node": ">=18"
57
60
  }
58
- }
61
+ }
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "vod-devkit",
3
- "version": "0.4.4",
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.4.4",
3
- "commitSha": "1e55b12d23386a1df27a1cb6211951a96c66f5c8",
4
- "builtAt": "2026-11-10T09:47:22",
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,23 +1,51 @@
1
1
  ---
2
2
  name: vod-core
3
- description: 'VOD 用户声音分析插件路由入口。任何"分析用户声音/反馈、发起 VOD 分析任务、查任务状态/结果、VOD 评分/分类规则、KB 检索"类请求先经本技能路由到对应工具与领域技能。写操作(发起分析)必须先获用户确认(confirm 护栏)。'
4
- version: 1
3
+ description: 'VOD 用户声音采集插件的路由入口与纪律速查。遇到"提交反馈/采集用户声音/这条反馈入库没有/问题分类与评分规则是什么/插件版本与来源/key 认证状态"类请求先读本技能,再按表路由到具体工具或领域技能。采集写操作必须先获用户明确同意。'
4
+ tags: [vod, feedback, routing]
5
+ metadata:
6
+ version: 2
5
7
  ---
6
8
 
7
- # VOD Core
9
+ # VOD Core(路由与纪律)
8
10
 
9
- VOD 分析能力入口。按意图路由:
11
+ 本插件只做**用户声音采集**:把用户对本产品的抱怨/建议/期望原话送进 VOD 囤积区。
12
+ 分析与运营归 vod-system 前端,插件没有、也不该有发起分析的入口。
13
+
14
+ ## 意图 → 工具
10
15
 
11
16
  | 意图 | 动作 |
12
17
  |---|---|
13
- | 发起分析 | 工具 vod_run_analysis(confirm:必须用户确认后传 confirmed=true;taskId 为对账主键) |
14
- | 查任务进度/结果 | vod_task_status / vod_task_result |
15
- | 知识库检索 | vod_kb_search |
16
- | 插件自述/来源核验 | vod_devkit_info |
17
- | 分类匹配/问题分类/评分规则 | 领域技能(由 vendor 机制从 VOD-Project 真源拉取:vod-category-matching / vod-problem-classification / vod-scoring-rules) |
18
-
19
- 纪律:
20
- 1. 任务 ID 是唯一对账主键,发起后一切追问以 taskId 对账,不凭记忆描述
21
- 2. 单任务条数上限、product 白名单由护栏强制,超限直接拒
22
- 3. 任何 DB 直连/凭据读取意图会被 deny——不要尝试
23
- 4. 领域规则以 vendored 技能文件为准,不凭训练数据回答 VOD 评分口径
18
+ | 用户抱怨/建议,要提交 | `vod_submit_voices`(先征得明确同意,再传 `confirmed=true`);话术见 `vod-feedback-collect` |
19
+ | 想先暂存、等用户确认后再提交 | `vod_draft_voices` → 用户确认 → `vod_commit_voices`(一次性令牌 + payload 校验)**仅 stdio 面可用**:远程 MCP 面没有这两个工具,改用 `vod_submit_voices` 单发 |
20
+ | 本机已提交过哪些(进度追问) | `vod_list_submitted`(本地账本口径,换机不保留)**仅 stdio 面可用**;远程面改答"本条收录状态" |
21
+ | 插件版本/来源核验 | `vod_devkit_info`(version + commitSha) |
22
+ | key/认证状态、引擎连通性 | `vod_auth_status`(只报指纹,不下发明文) |
23
+ | 有哪些技能、规则技能是否可用 | `vod_list_skills` |
24
+ | 取规则技能全文(分类/评分口径) | `vod_retrieve_skill`(owner pack 被裁剪时返回恢复指引) |
25
+
26
+ ## 意图 → 领域技能
27
+
28
+ | 主题 | 技能 | 加载方式 |
29
+ |---|---|---|
30
+ | 采集话术/确认时机/原话逐字纪律 | `vod-feedback-collect` | 宿主原生加载(元技能,已装进本机技能目录) |
31
+ | 六类问题分类口径(引擎 v2.2 真源) | `vod-problem-classification-rules` | 原生副本优先;读不到或怀疑过期时用 `vod_retrieve_skill` |
32
+ | 四项评分公式(引擎 v2 真源) | `vod-scoring-rules` | 同上 |
33
+
34
+ ## 纪律(违反即事故)
35
+
36
+ 1. **同意前置**:用户陈述反馈 ≠ 同意提交。先承接、再问"要提交给产品团队吗"、
37
+ 再用一句固定的引导补充话术,一次说完。
38
+ 2. **原话逐字**:`content` 放用户原话,禁改写/概括/增删语气词;回执
39
+ `echo.contents` 必须逐字转述给用户(「已收录原话:…」)。
40
+ 3. **归因必问一次(D-product-ask-1)**:产品未定时,先问用户"这条是哪个产品的反馈?"
41
+ (用 `vod_search_products` 给 3-5 个候选),回答填 `product`;
42
+ 用户说的产品不在名录("智果"/打错)→ 不按原名提交,用 `vod_search_products` 给候选
43
+ 再确认一次;仍对不上就不提交。
44
+ 用户明确说不知道/随便 → `productNotSpecified=true`,插件**不猜也不提交**,
45
+ 由你告知用户"没有产品归属的反馈不提交"并请他补充产品。
46
+ **不许不填直接提交**(插件会以 -32010 拒绝并给候选)。
47
+ 4. **篇幅边界**:content ≤ 2000 字、单批 ≤ 50 条(护栏强制,超限直接拒)。
48
+ 5. **不碰内部面**:不尝试数据库直连、不读取或打印凭据;被 deny 时如实告知,
49
+ 不要换措辞重试。
50
+ 6. **规则口径以技能/披露内容为准**:不凭训练数据回答 VOD 分类与评分——
51
+ vendored 文本与引擎代码同源。
@@ -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` 全绿