vod-devkit 0.5.9 → 0.5.11

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 (152) hide show
  1. package/CHANGELOG.md +58 -0
  2. package/QUICKSTART.md +6 -2
  3. package/README.en.md +23 -2
  4. package/README.md +204 -16
  5. package/{contract → assets/contract}/tools.schema.json +127 -1
  6. package/{skills → assets/skills}/vod-core/SKILL.md +32 -1
  7. package/bin/vod-devkit +21 -1
  8. package/integrations/hermes/hooks/vod_guard.py +127 -0
  9. package/integrations/hermes/hooks/vod_router.py +89 -0
  10. package/integrations/hermes/host.json +4 -1
  11. package/npm/cli.js +6 -1
  12. package/package.json +37 -34
  13. package/packages/dsh/README.md +60 -0
  14. package/packages/dsh/package.json +52 -0
  15. package/plugins/vod-devkit/.codex-plugin/plugin.json +1 -1
  16. package/plugins/vod-devkit/.mcp.json +2 -0
  17. package/plugins/vod-devkit/build-info.json +3 -3
  18. package/plugins/vod-devkit/contract/tools.schema.json +127 -1
  19. package/plugins/vod-devkit/hooks/vod_guard.py +127 -0
  20. package/plugins/vod-devkit/hooks/vod_router.py +89 -0
  21. package/plugins/vod-devkit/skills/vod-core/SKILL.md +32 -1
  22. package/plugins/vod-devkit/vod_mcp/__init__.py +1 -1
  23. package/plugins/vod-devkit/vod_mcp/attribution.py +21 -2
  24. package/plugins/vod-devkit/vod_mcp/config_forms.py +22 -6
  25. package/plugins/vod-devkit/vod_mcp/diagnose.py +4 -2
  26. package/plugins/vod-devkit/vod_mcp/host_adapters/base.py +4 -1
  27. package/plugins/vod-devkit/vod_mcp/host_adapters/codex.py +154 -34
  28. package/plugins/vod-devkit/vod_mcp/host_adapters/dsh.py +133 -22
  29. package/plugins/vod-devkit/vod_mcp/host_adapters/hermes.py +216 -59
  30. package/plugins/vod-devkit/vod_mcp/host_adapters/opencode.py +10 -4
  31. package/plugins/vod-devkit/vod_mcp/hosts.py +4 -0
  32. package/plugins/vod-devkit/vod_mcp/net.py +78 -18
  33. package/plugins/vod-devkit/vod_mcp/packs/__init__.py +97 -22
  34. package/plugins/vod-devkit/vod_mcp/packs/collect.py +50 -42
  35. package/plugins/vod-devkit/vod_mcp/packs/core.py +138 -2
  36. package/plugins/vod-devkit/vod_mcp/paths.py +200 -30
  37. package/plugins/vod-devkit/vod_mcp/payload.py +10 -5
  38. package/plugins/vod-devkit/vod_mcp/provenance.py +1 -1
  39. package/plugins/vod-devkit/vod_mcp/remote_app.py +4 -4
  40. package/plugins/vod-devkit/vod_mcp/runtime_state.py +151 -28
  41. package/plugins/vod-devkit/vod_mcp/server.py +52 -7
  42. package/plugins/vod-devkit/vod_mcp/skills_registry.py +29 -8
  43. package/plugins/vod-devkit/vod_mcp/tools.py +21 -3
  44. package/plugins/vod-devkit/vod_mcp/transport_remote.py +22 -3
  45. package/{vod_mcp → src/vod_mcp}/__init__.py +1 -1
  46. package/{vod_mcp → src/vod_mcp}/attribution.py +21 -2
  47. package/{vod_mcp → src/vod_mcp}/config_forms.py +22 -6
  48. package/{vod_mcp → src/vod_mcp}/diagnose.py +4 -2
  49. package/{vod_mcp → src/vod_mcp}/host_adapters/base.py +4 -1
  50. package/{vod_mcp → src/vod_mcp}/host_adapters/codex.py +154 -34
  51. package/{vod_mcp → src/vod_mcp}/host_adapters/dsh.py +133 -22
  52. package/src/vod_mcp/host_adapters/hermes.py +361 -0
  53. package/{vod_mcp → src/vod_mcp}/host_adapters/opencode.py +10 -4
  54. package/{vod_mcp → src/vod_mcp}/hosts.py +4 -0
  55. package/{vod_mcp → src/vod_mcp}/net.py +78 -18
  56. package/src/vod_mcp/packs/__init__.py +142 -0
  57. package/{vod_mcp → src/vod_mcp}/packs/collect.py +50 -42
  58. package/src/vod_mcp/packs/core.py +216 -0
  59. package/src/vod_mcp/paths.py +208 -0
  60. package/{vod_mcp → src/vod_mcp}/payload.py +10 -5
  61. package/{vod_mcp → src/vod_mcp}/provenance.py +1 -1
  62. package/{vod_mcp → src/vod_mcp}/remote_app.py +4 -4
  63. package/{vod_mcp → src/vod_mcp}/runtime_state.py +151 -28
  64. package/{vod_mcp → src/vod_mcp}/server.py +52 -7
  65. package/{vod_mcp → src/vod_mcp}/skills_registry.py +29 -8
  66. package/{vod_mcp → src/vod_mcp}/tools.py +21 -3
  67. package/{vod_mcp → src/vod_mcp}/transport_remote.py +22 -3
  68. package/src/vodkit_cli/auth_cmd.py +81 -0
  69. package/{vodkit_cli → src/vodkit_cli}/cli.py +38 -8
  70. package/{vodkit_cli → src/vodkit_cli}/common.py +14 -3
  71. package/{vodkit_cli → src/vodkit_cli}/doctor.py +147 -9
  72. package/{vodkit_cli → src/vodkit_cli}/install.py +148 -33
  73. package/src/vodkit_cli/packs_cmd.py +329 -0
  74. package/{vodkit_cli → src/vodkit_cli}/remote.py +3 -3
  75. package/src/vodkit_cli/uninstall.py +315 -0
  76. package/vod_mcp/host_adapters/__pycache__/__init__.cpython-314.pyc +0 -0
  77. package/vod_mcp/host_adapters/__pycache__/__init__.cpython-39.pyc +0 -0
  78. package/vod_mcp/host_adapters/__pycache__/atomcode.cpython-314.pyc +0 -0
  79. package/vod_mcp/host_adapters/__pycache__/atomcode.cpython-39.pyc +0 -0
  80. package/vod_mcp/host_adapters/__pycache__/base.cpython-314.pyc +0 -0
  81. package/vod_mcp/host_adapters/__pycache__/base.cpython-39.pyc +0 -0
  82. package/vod_mcp/host_adapters/__pycache__/codearts.cpython-314.pyc +0 -0
  83. package/vod_mcp/host_adapters/__pycache__/codearts.cpython-39.pyc +0 -0
  84. package/vod_mcp/host_adapters/__pycache__/codeartswork.cpython-314.pyc +0 -0
  85. package/vod_mcp/host_adapters/__pycache__/codeartswork.cpython-39.pyc +0 -0
  86. package/vod_mcp/host_adapters/__pycache__/codex.cpython-314.pyc +0 -0
  87. package/vod_mcp/host_adapters/__pycache__/codex.cpython-39.pyc +0 -0
  88. package/vod_mcp/host_adapters/__pycache__/codex_desktop.cpython-314.pyc +0 -0
  89. package/vod_mcp/host_adapters/__pycache__/codex_desktop.cpython-39.pyc +0 -0
  90. package/vod_mcp/host_adapters/__pycache__/dsh.cpython-314.pyc +0 -0
  91. package/vod_mcp/host_adapters/__pycache__/dsh.cpython-39.pyc +0 -0
  92. package/vod_mcp/host_adapters/__pycache__/generic.cpython-314.pyc +0 -0
  93. package/vod_mcp/host_adapters/__pycache__/generic.cpython-39.pyc +0 -0
  94. package/vod_mcp/host_adapters/__pycache__/hermes.cpython-314.pyc +0 -0
  95. package/vod_mcp/host_adapters/__pycache__/hermes.cpython-39.pyc +0 -0
  96. package/vod_mcp/host_adapters/__pycache__/opencode.cpython-314.pyc +0 -0
  97. package/vod_mcp/host_adapters/__pycache__/opencode.cpython-39.pyc +0 -0
  98. package/vod_mcp/host_adapters/__pycache__/workbuddy.cpython-314.pyc +0 -0
  99. package/vod_mcp/host_adapters/__pycache__/workbuddy.cpython-39.pyc +0 -0
  100. package/vod_mcp/host_adapters/hermes.py +0 -204
  101. package/vod_mcp/packs/__init__.py +0 -67
  102. package/vod_mcp/packs/__pycache__/__init__.cpython-314.pyc +0 -0
  103. package/vod_mcp/packs/__pycache__/__init__.cpython-39.pyc +0 -0
  104. package/vod_mcp/packs/__pycache__/collect.cpython-314.pyc +0 -0
  105. package/vod_mcp/packs/__pycache__/collect.cpython-39.pyc +0 -0
  106. package/vod_mcp/packs/__pycache__/core.cpython-314.pyc +0 -0
  107. package/vod_mcp/packs/__pycache__/core.cpython-39.pyc +0 -0
  108. package/vod_mcp/packs/__pycache__/knowledge.cpython-314.pyc +0 -0
  109. package/vod_mcp/packs/__pycache__/knowledge.cpython-39.pyc +0 -0
  110. package/vod_mcp/packs/core.py +0 -80
  111. package/vod_mcp/paths.py +0 -38
  112. package/vodkit_cli/__pycache__/__init__.cpython-314.pyc +0 -0
  113. package/vodkit_cli/__pycache__/__init__.cpython-39.pyc +0 -0
  114. package/vodkit_cli/__pycache__/cli.cpython-314.pyc +0 -0
  115. package/vodkit_cli/__pycache__/cli.cpython-39.pyc +0 -0
  116. package/vodkit_cli/__pycache__/common.cpython-314.pyc +0 -0
  117. package/vodkit_cli/__pycache__/common.cpython-39.pyc +0 -0
  118. package/vodkit_cli/__pycache__/doctor.cpython-314.pyc +0 -0
  119. package/vodkit_cli/__pycache__/doctor.cpython-39.pyc +0 -0
  120. package/vodkit_cli/__pycache__/install.cpython-314.pyc +0 -0
  121. package/vodkit_cli/__pycache__/install.cpython-39.pyc +0 -0
  122. package/vodkit_cli/__pycache__/remote.cpython-314.pyc +0 -0
  123. package/vodkit_cli/__pycache__/remote.cpython-39.pyc +0 -0
  124. package/vodkit_cli/__pycache__/uninstall.cpython-314.pyc +0 -0
  125. package/vodkit_cli/__pycache__/uninstall.cpython-39.pyc +0 -0
  126. package/vodkit_cli/__pycache__/update.cpython-314.pyc +0 -0
  127. package/vodkit_cli/__pycache__/update.cpython-39.pyc +0 -0
  128. package/vodkit_cli/uninstall.py +0 -161
  129. /package/{safety → assets/safety}/policy.json +0 -0
  130. /package/{skills → assets/skills}/vod-core/references/acceptance-criteria.md +0 -0
  131. /package/{skills → assets/skills}/vod-core/references/verification-method.md +0 -0
  132. /package/{skills → assets/skills}/vod-feedback-collect/SKILL.md +0 -0
  133. /package/{skills → assets/skills}/vod-feedback-collect/references/acceptance-criteria.md +0 -0
  134. /package/{skills → assets/skills}/vod-feedback-collect/references/verification-method.md +0 -0
  135. /package/{skills → assets/skills}/vod-problem-classification-rules/SKILL.md +0 -0
  136. /package/{skills → assets/skills}/vod-scoring-rules/SKILL.md +0 -0
  137. /package/{vod_mcp → src/vod_mcp}/detect_framework.py +0 -0
  138. /package/{vod_mcp → src/vod_mcp}/guardrails.py +0 -0
  139. /package/{vod_mcp → src/vod_mcp}/host_adapters/__init__.py +0 -0
  140. /package/{vod_mcp → src/vod_mcp}/host_adapters/atomcode.py +0 -0
  141. /package/{vod_mcp → src/vod_mcp}/host_adapters/codearts.py +0 -0
  142. /package/{vod_mcp → src/vod_mcp}/host_adapters/codeartswork.py +0 -0
  143. /package/{vod_mcp → src/vod_mcp}/host_adapters/codex_desktop.py +0 -0
  144. /package/{vod_mcp → src/vod_mcp}/host_adapters/generic.py +0 -0
  145. /package/{vod_mcp → src/vod_mcp}/host_adapters/workbuddy.py +0 -0
  146. /package/{vod_mcp → src/vod_mcp}/packs/knowledge.py +0 -0
  147. /package/{vod_mcp → src/vod_mcp}/pending.py +0 -0
  148. /package/{vod_mcp → src/vod_mcp}/policy.py +0 -0
  149. /package/{vod_mcp → src/vod_mcp}/runtime.example.json +0 -0
  150. /package/{vod_mcp → src/vod_mcp}/update_check.py +0 -0
  151. /package/{vodkit_cli → src/vodkit_cli}/__init__.py +0 -0
  152. /package/{vodkit_cli → src/vodkit_cli}/update.py +0 -0
@@ -68,25 +68,46 @@ def _server_face() -> bool:
68
68
 
69
69
 
70
70
  def list_skills(params: dict) -> dict:
71
- """列出可披露的技能(元技能一并列出,标出 pack 与是否原生安装)。"""
71
+ """列出可披露的技能(元技能一并列出,标出 pack 与是否原生安装)。
72
+
73
+ 字段对齐 devkit 的技能目录:name/description/version/引用文件名,外加
74
+ skillRoot 与每个技能的绝对路径——**只在 stdio 面给**(远程面不给服务器本机路径)。
75
+ 给路径的目的不是装饰:教法是"动作优先",agent 先按路径直读 SKILL.md
76
+ (尝试本身即可达性检查),读不到才回落 vod_retrieve_skill,绝不反复请求。
77
+ """
72
78
  from vod_mcp import packs
73
- enabled = set(packs.enabled_packs())
79
+ enabled = set(packs.effective_packs())
74
80
  items = []
75
81
  for d in _skill_dirs():
76
82
  text = (d / "SKILL.md").read_text(encoding="utf-8")
77
83
  meta = _frontmatter(text)
78
84
  pack = SKILL_PACK.get(d.name, "core")
79
- items.append({
85
+ item = {
80
86
  "name": d.name,
81
87
  "pack": pack,
82
88
  "enabled": pack in enabled,
83
89
  "native": d.name in META_SKILLS,
84
90
  "description": meta.get("description", ""),
85
91
  "chars": len(text),
86
- })
87
- return {"skills": items, "packs": sorted(enabled),
88
- "note": "领域规则技能用 vod_retrieve_skill 取全文;元技能由宿主原生"
89
- "加载,只在本工具里列名以便路由。"}
92
+ }
93
+ if meta.get("version"):
94
+ item["version"] = meta["version"]
95
+ refs = sorted(p.name for p in (d / "references").glob("*")
96
+ if p.is_file()) if (d / "references").is_dir() else []
97
+ if refs:
98
+ item["references"] = refs
99
+ if not _server_face():
100
+ item["path"] = str(d / "SKILL.md")
101
+ items.append(item)
102
+ out = {"skills": items, "packs": sorted(enabled),
103
+ "note": "领域规则技能用 vod_retrieve_skill 取全文;元技能由宿主原生"
104
+ "加载,只在本工具里列名以便路由。"}
105
+ if not _server_face():
106
+ out["skillRoot"] = str(SKILLS_ROOT)
107
+ out["readHint"] = ("动作优先:先直接读 skillRoot/<name>/SKILL.md(尝试本身"
108
+ "即可达性检查,不做预判);被拒/失败才回落 vod_retrieve_skill,"
109
+ "绝不反复请求。")
110
+ return out
90
111
 
91
112
 
92
113
  def retrieve_skill(params: dict) -> dict:
@@ -101,7 +122,7 @@ def retrieve_skill(params: dict) -> dict:
101
122
  known = [p.name for p in _skill_dirs()]
102
123
  raise SkillError(f"未知技能 {name!r};可用:{'、'.join(known)}", -32602)
103
124
  pack = SKILL_PACK.get(name, "core")
104
- enabled = set(packs.enabled_packs())
125
+ enabled = set(packs.effective_packs())
105
126
  if pack not in enabled:
106
127
  raise SkillError(
107
128
  f"技能 {name} 属于 {pack} pack,当前安装未启用(VOD_PACKS="
@@ -46,15 +46,33 @@ _HANDLERS = {
46
46
  "vod_list_submitted": collect.list_submitted,
47
47
  "vod_devkit_info": core.devkit_info,
48
48
  "vod_auth_status": core.auth_status,
49
+ "vod_auth_ensure": core.auth_ensure,
50
+ "vod_packs_configure": core.packs_configure,
49
51
  "vod_draft_voices": collect.draft_voices,
50
52
  "vod_commit_voices": collect.commit_voices,
51
53
  }
52
54
 
53
55
 
56
+ def _needs_client_info(handler) -> bool:
57
+ """handler 是否吃 client_info(按签名判,不靠手写清单)。
58
+
59
+ 为什么不用元组白名单:新增双参 handler 忘登记时**静默收到 None**,宿主归因/
60
+ 设备标识这类字段就丢了,不报错也不告警(本次 vod_packs_configure 只因不吃
61
+ client_info 才没暴露)。签名判参把这类漏登记一次性消掉。
62
+ """
63
+ import inspect
64
+ try:
65
+ params = list(inspect.signature(handler).parameters.values())
66
+ except (TypeError, ValueError): # 内建/不可反射:按单参处理(原行为)
67
+ return False
68
+ positional = [p for p in params
69
+ if p.kind in (p.POSITIONAL_ONLY, p.POSITIONAL_OR_KEYWORD)]
70
+ has_varargs = any(p.kind == p.VAR_POSITIONAL for p in params)
71
+ return has_varargs or len(positional) >= 2
72
+
73
+
54
74
  def dispatch(name: str, params: dict, client_info: dict | None = None) -> dict:
55
75
  handler = _HANDLERS.get(name)
56
76
  if handler is None:
57
77
  raise ToolError(f"未知工具: {name}", code=-32601)
58
- needs_host = handler in (core.devkit_info, collect.submit_voices, core.auth_status,
59
- collect.draft_voices, collect.commit_voices)
60
- return handler(params, client_info) if needs_host else handler(params)
78
+ return handler(params, client_info) if _needs_client_info(handler) else handler(params)
@@ -16,8 +16,9 @@ devkit 的契约(mcp-server-remote.ts + test/remote-mcp-server.test.ts 实测
16
16
  用一个小的 ASGI 适配层把 stdlib http.server 的请求转成 scope/receive/send。
17
17
  协议处理仍然全部在 SDK 里,与 devkit 同源。
18
18
 
19
- 身份:请求头 Authorization: Bearer <key> 逐请求注入(见 tools._REQ_KEY),
20
- 不落盘、不进 env;插件不代签身份——缺 key 时 submit 结构化拒绝。
19
+ 身份:请求头 Authorization: Bearer *** 逐请求注入(见 tools._REQ_KEY),优先生效;
20
+ 没有 Bearer 时与本地同链——由服务端领/复用**机器级匿名令牌**提交(同机独立部署的
21
+ 默认形态,D-token-machine-1)。
21
22
  """
22
23
  import asyncio
23
24
  import json
@@ -329,10 +330,28 @@ class _Handler(BaseHTTPRequestHandler):
329
330
  "error": {"code": -32603, "message": str(e)}})
330
331
 
331
332
 
332
- def serve(host: str, port: int) -> int:
333
+ def _apply_anon_mint_policy(host: str, allow: bool) -> bool:
334
+ """按绑定地址决定是否允许服务端代领匿名令牌(返回是否开启)。
335
+
336
+ 回环(同机独立部署的默认形态)→ 开启,与本地 stdio 一致;
337
+ 非回环(可能经反代/公网触达)→ 默认关闭,需 `--allow-anon-mint` 显式开启。
338
+ 理由:服务面无内建鉴权,代领 = 任何能连端口的进程都能用本机身份提交、消耗额度。
339
+ """
340
+ from vod_mcp import net
341
+ enabled = (host in LOOPBACK) or bool(allow)
342
+ net.ANON_MINT_DISABLED = not enabled
343
+ return enabled
344
+
345
+
346
+ def serve(host: str, port: int, allow_anon_mint: bool = False) -> int:
347
+ anon = _apply_anon_mint_policy(host, allow_anon_mint)
333
348
  if host not in LOOPBACK:
334
349
  print(f"[vod-devkit] 警告:远程 MCP 绑定非回环地址 {host}——本进程无内建鉴权,"
335
350
  "不要把它匿名暴露到公网;TLS 与身份校验应由反代承担。", file=sys.stderr)
351
+ if not anon:
352
+ print("[vod-devkit] 匿名令牌代领已关闭(非回环绑定):调用方须带 "
353
+ "Authorization: Bearer <key>;单机可信网络确需代领时加 --allow-anon-mint",
354
+ file=sys.stderr)
336
355
  runtime = RemoteRuntime(host, port)
337
356
  runtime.start()
338
357
  httpd = ThreadingHTTPServer((host, port), _Handler)
@@ -5,7 +5,7 @@
5
5
  2. 外部无 DB 直连路径(护栏 deny 兜底)
6
6
  3. 任务 ID 是唯一对账主键,写类工具返回一律携带
7
7
  """
8
- __version__ = "0.5.9"
8
+ __version__ = "0.5.11"
9
9
  # 默认上游:VOD 测试环境。外部用户本机无 VOD,回环默认值=装完即坏;
10
10
  # 生产地址定型后只改这一处(tools.py 与 bin/vod-devkit 共用本常量)。
11
11
  DEFAULT_JAVA_BASE = "https://vod-dev.topxtopx.com"
@@ -30,6 +30,15 @@ import re
30
30
 
31
31
  MEM_TTL = 30 * 60 # 记忆窗口:负责人拍板 P2-A(机器级 + 30 分钟)
32
32
 
33
+ # 自指词表(2026-11-16 负责人拍板 A,D-product-ask-1 修订):
34
+ # 安装先验(--product 写入的 binding)**只在原话出现自指时**才作为归因证据。
35
+ # 理由:先验是无字面证据的推断,用户在 A 产品插件里吐槽 B 产品时会错归;
36
+ # 而"这个产品/你们家"这类自指说明用户就在说当前产品,此时先验有语境支撑。
37
+ # 收录口径:只放"指向当前语境"的词,不放泛称("产品"单字不收——太容易误命中)。
38
+ SELF_REFERENCE = ("这个产品", "这款产品", "本产品", "该产品", "你们这个", "你们这款",
39
+ "你们的产品", "你们的这个", "本平台", "这个平台", "这个系统",
40
+ "你们家", "你们这", "咱这个", "咱们这个", "这插件")
41
+
33
42
  _SNIPPET_PAD = 20
34
43
  _SNIPPET_MAX = 80
35
44
  _BOUNDARY = set("abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789_-")
@@ -359,8 +368,18 @@ def attribute(text: str, meta: dict, memory: dict | None = None,
359
368
  "at": mem.get("at"), "reason": "memory"}]}
360
369
 
361
370
  if binding:
362
- return {"product": resolve_id(binding, meta), "productName": str(binding),
363
- "source": "install_binding", "evidence": []}
371
+ # D-product-ask-1 修订(2026-11-16 负责人拍板 A):先验必须有语境支撑。
372
+ # 原话出现自指("这个产品/你们家/本平台")→ 承认先验,证据留痕;
373
+ # 没有自指 → 不拿先验硬归(错归会进引擎幂等/判重域,污染静默难追溯),
374
+ # 与"缺产品先问一次"同一条纪律:宁可多问一句,不可无证据归因。
375
+ hit = next((p for p in SELF_REFERENCE if p in text), None)
376
+ if hit:
377
+ idx = text.find(hit)
378
+ snippet = text[max(0, idx - _SNIPPET_PAD): idx + len(hit) + _SNIPPET_PAD]
379
+ return {"product": resolve_id(binding, meta), "productName": str(binding),
380
+ "source": "install_binding",
381
+ "evidence": [{"product": str(binding), "alias": hit,
382
+ "snippet": snippet, "reason": "self-reference"}]}
364
383
 
365
384
  return {"product": None, "productName": None, "source": "unknown",
366
385
  "evidence": [{"reason": "no-evidence"}]}
@@ -23,6 +23,17 @@ _HEADER = re.compile(r"^\[([^\[\]]+)\]$")
23
23
  _MAPPING_ROOT = re.compile(r"^[A-Za-z_][\w.\-]*\s*:")
24
24
  _DSH_ID = "- id: vod-devkit"
25
25
 
26
+ # 托管块标记(D-dsh-mcp-b-1):B 模式下一次写两条 insert 子项(mcp-client + 壳),
27
+ # 用注释行包裹整块 → 幂等替换、卸载只摘自己,且不与无标记的旧形态混淆。
28
+ _DSH_MARK_START = "# vod-devkit DSH integration start"
29
+ _DSH_MARK_END = "# vod-devkit DSH integration end"
30
+
31
+
32
+ def _is_dsh_id_line(stripped: str) -> bool:
33
+ """精确匹配 `- id: vod-devkit`(前缀匹配会把 `- id: vod-devkit-mcp` 也算进来 →
34
+ classify 判成"多个块"直接 refuse,托管块就永远写不进去)。"""
35
+ return stripped == _DSH_ID or stripped.startswith(_DSH_ID + " ")
36
+
26
37
 
27
38
  class Refused(Exception):
28
39
  """文件形态不在已知集合内:调用方必须原样放弃修改(字节不变)。"""
@@ -124,7 +135,7 @@ def classify_dsh_patch(lines: list) -> tuple:
124
135
  return "refuse", f"根节点是 flow 集合({root[:20]}),本插件只写块数组"
125
136
  if _MAPPING_ROOT.match(root):
126
137
  return "refuse", f"根节点是映射({root[:20]}),不是本插件写的顶层数组"
127
- if sum(1 for ln in lines if ln.strip().startswith(_DSH_ID)) > 1:
138
+ if sum(1 for ln in lines if _is_dsh_id_line(ln.strip())) > 1:
128
139
  return "refuse", "出现多个 `- id: vod-devkit` 块(无法判定哪一份是活的)"
129
140
  return "ok", ""
130
141
 
@@ -132,13 +143,18 @@ def classify_dsh_patch(lines: list) -> tuple:
132
143
  def find_dsh_block(lines: list) -> tuple:
133
144
  """定位 vod-devkit 块的 (start, end);不存在返回 (None, None)。
134
145
 
135
- 块边界=下一顶层元素行(`- ` 开头)或 EOF。嵌套铁律(真机实锤):
136
- dsh 只认缩进在 `- insert:` 之下的块——命中行带缩进时 start 向上归并到
137
- 该组头,整组替换;历史平铺形态按原语义顶格替换。install 的幂等 upsert
138
- 与 uninstall 的摘除共用本边界语义(单一实现,防两处扫描规则漂移)。
146
+ 优先按**托管块标记**定位(D-dsh-mcp-b-1:B 模式下块内含 mcp-client 与壳两条子项,
147
+ 只有标记能划出完整边界);无标记时回落到旧形态扫描(`- id: vod-devkit`,
148
+ 兼容已装机实例)。块边界=下一顶层元素行(`- ` 开头)或 EOF。
139
149
  """
140
150
  for i, ln in enumerate(lines):
141
- if ln.strip().startswith(_DSH_ID):
151
+ if ln.strip() == _DSH_MARK_START:
152
+ for j in range(i + 1, len(lines)):
153
+ if lines[j].strip() == _DSH_MARK_END:
154
+ return i, j + 1
155
+ return i, len(lines) # 只有 start(半坏态):整段到 EOF,由 upsert 重写
156
+ for i, ln in enumerate(lines):
157
+ if _is_dsh_id_line(ln.strip()):
142
158
  start = i
143
159
  if ln[:1] == " ": # 嵌套形态:向上归并组头
144
160
  for k in range(i - 1, -1, -1):
@@ -31,8 +31,10 @@ RULES = [
31
31
  "配置", "宿主没读到我们的 MCP 条目", "检查宿主配置文件里的 mcp 段后重装"),
32
32
  (r"skills 目录缺失|技能文件缺失|技能文件漂移|技能原生副本缺失|技能拷贝件",
33
33
  "技能", "技能副本缺失或与安装指纹不符", "重跑 install 恢复"),
34
- (r"路由插件副本落后|vod-feedback-router",
35
- "插件", "仓内话术已更新但装机副本是旧的", "重跑 install --target hermes"),
34
+ (r"预采集 hook 未注册|vod_router|hook 脚本缺失",
35
+ "配置", "config.yaml 的 hooks.pre_llm_call 没登记我们的脚本", "重跑 install --target hermes"),
36
+ (r"旧插件形态仍在|vod-feedback-router",
37
+ "插件", "老插件与 shell hook 同时生效(双份注入)", "重跑 install --target hermes 清理"),
36
38
  (r"AGENTS\.md 仍含旧一代注入|vod-submit-one-liner",
37
39
  "插件", "旧注入教模型跳过征询(红线失效)", "重跑 install --target codex 自动清理"),
38
40
  (r"远程面|远程 MCP|探活|不可达|401",
@@ -31,7 +31,10 @@ def server_env(args, packs: str) -> dict:
31
31
  # 无 key 不写空串(空串会让探针/严格解析器误当字面值;运行时空=未设置,
32
32
  # 自动兜底 runtime.json java_key 或首提申请匿名令牌)
33
33
  env = {"VOD_PACKS": packs,
34
- "VOD_JAVA_API_BASE": args.java_api_base}
34
+ "VOD_JAVA_API_BASE": args.java_api_base,
35
+ # D-token-machine-1:机器级状态目录显式写进宿主配置——
36
+ # 不依赖"默认值恰好一致",也不随载荷版本目录漂移(升级不换令牌)。
37
+ "VOD_DEVKIT_HOME": str(paths.machine_state_home())}
35
38
  key = os.environ.get("VOD_JAVA_API_KEY", "")
36
39
  if key:
37
40
  env["VOD_JAVA_API_KEY"] = key
@@ -100,6 +100,126 @@ def strip_agents_vod_block(text: str) -> str:
100
100
  return "\n".join(out).rstrip()
101
101
 
102
102
 
103
+ def locate_plugin_mcp(mp_name: str | None = "vod-local"):
104
+ """定位 codex 插件缓存里的 .mcp.json(最近写入的那份)。找不到返回 None。
105
+
106
+ mp_name=None 时扫所有 marketplace(doctor 用:装机实例的 marketplace 名可能是
107
+ `personal`/`vod-local` 等,按名找会漏)。
108
+ """
109
+ import glob as _glob
110
+ mkt = mp_name or "*"
111
+ hits = sorted(
112
+ _glob.glob(str(Path.home() / ".codex" / "plugins" / "cache"
113
+ / mkt / "vod-devkit" / "*" / ".mcp.json")),
114
+ key=lambda p: Path(p).stat().st_mtime, reverse=True)
115
+ return Path(hits[0]) if hits else None
116
+
117
+
118
+ def plugin_mcp_form(mcp_path) -> tuple:
119
+ """判定装机清单的**实际生效形态**,给 doctor 报,别让人猜。
120
+
121
+ 三类(顺序即优先级):
122
+ ("payload", srv) —— command 是绝对路径:版本正确(我们改写成功)
123
+ ("placeholder", srv)—— args 含未展开的 ${...}:宿主收到字面量,起不来
124
+ ("cli", srv) —— command 是裸 CLI 名:跑的是 PATH 上那份,版本不确定
125
+ ("unreadable", None)—— 读不出 mcpServers.vod-devkit
126
+ """
127
+ p = Path(mcp_path)
128
+ try:
129
+ srv = json.loads(p.read_text(encoding="utf-8"))["mcpServers"]["vod-devkit"]
130
+ except (OSError, json.JSONDecodeError, KeyError, TypeError):
131
+ return ("unreadable", None)
132
+ args = srv.get("args") or []
133
+ if any("${" in str(a) for a in args):
134
+ return ("placeholder", srv)
135
+ cmd = str(srv.get("command") or "")
136
+ if "/" in cmd or "\\" in cmd:
137
+ return ("payload", srv)
138
+ return ("cli", srv)
139
+
140
+
141
+ class PluginMcpRewriteError(RuntimeError):
142
+ """插件 .mcp.json 改写失败,按 kind 分类(安装器据此决定 warn 还是 fail)。
143
+
144
+ kind:
145
+ bad-json —— 缓存内文件不是合法 JSON / 缺 mcpServers.vod-devkit(上游格式变更或人工改过)
146
+ not-writable —— 读写抛 OSError(只读挂载 / 权限)
147
+ 这两类都**不该**把整个安装判死:插件自带的静态形态(`python3` +
148
+ `${PLUGIN_ROOT}/vod_mcp/server.py`)本身就能跑,只是解释器版本靠 PATH。
149
+ """
150
+
151
+ REMEDY = {
152
+ "bad-json":
153
+ "缓存内 .mcp.json 结构不符(codex 换了 Agent Plugins 解析形态,或该文件被改过)。"
154
+ "静态形态仍可运行;要改成载荷形态请删插件缓存重装,或改走 "
155
+ "`vod-devkit install --target generic --mcp-config <file>` 手写条目。",
156
+ "not-writable":
157
+ "插件缓存目录不可写(只读挂载/权限)。静态形态仍可运行;若机器上 PATH 的 "
158
+ "python3 < 3.10,请把该文件 command 指向 3.10+ 解释器绝对路径(安装器无法代写)。",
159
+ }
160
+
161
+ def __init__(self, kind: str, detail: str):
162
+ super().__init__(f"{kind}: {detail}")
163
+ self.kind = kind
164
+ self.detail = detail
165
+
166
+
167
+ def rewrite_plugin_mcp(mcp_path, python: str = "", entry: str = "", env: dict | None = None) -> dict:
168
+ """把插件自带 .mcp.json 改写成「绝对解释器 + 载荷副本」,并**读回验证**。
169
+
170
+ 为什么必须读回(2026-11-12 矩阵实锤的后续):写成功 ≠ 落盘就是我们要的
171
+ 形态——并发改写(宿主升级、另一次安装)会把它改回去,而宿主只会静默跑
172
+ 改回去的那份。所以写完再解析一次,逐字段比对。
173
+
174
+ 失败语义分三层,安装器按层处置:
175
+ - PluginMcpRewriteError(bad-json / not-writable)→ warn + 分类补救指引,安装继续
176
+ - RuntimeError(读回与期望不一致)→ 安装失败(半写状态不能留给宿主)
177
+ - 正常 → 返回读回的 server 条目
178
+ """
179
+ python = python or sys.executable
180
+ entry = entry or server_entry()
181
+ want_env = dict(env or {})
182
+ path = Path(mcp_path)
183
+ try:
184
+ raw = path.read_text(encoding="utf-8")
185
+ except OSError as e:
186
+ raise PluginMcpRewriteError("not-writable", f"{path}: {e}") from e
187
+ try:
188
+ mj = json.loads(raw)
189
+ except json.JSONDecodeError as e:
190
+ raise PluginMcpRewriteError("bad-json", f"{path}: {e.msg}") from e
191
+ servers = mj.get("mcpServers") if isinstance(mj, dict) else None
192
+ if not isinstance(servers, dict):
193
+ raise PluginMcpRewriteError("bad-json", f"{path} 缺 mcpServers 对象")
194
+ srv = servers.get("vod-devkit")
195
+ if not isinstance(srv, dict):
196
+ raise PluginMcpRewriteError("bad-json", f"{path} 缺 mcpServers.vod-devkit")
197
+ srv["command"] = python
198
+ srv["args"] = [entry]
199
+ merged = dict(srv.get("env") or {})
200
+ merged.update(want_env)
201
+ srv["env"] = merged
202
+ try:
203
+ path.write_text(json.dumps(mj, ensure_ascii=False, indent=2) + "\n",
204
+ encoding="utf-8")
205
+ except OSError as e:
206
+ raise PluginMcpRewriteError("not-writable", f"{path}: {e}") from e
207
+ try:
208
+ back = json.loads(path.read_text(encoding="utf-8"))
209
+ got = back["mcpServers"]["vod-devkit"]
210
+ except (OSError, json.JSONDecodeError, KeyError, TypeError) as e:
211
+ raise RuntimeError(f"改写后读回失败({path}):{e}") from e
212
+ if got.get("command") != python or got.get("args") != [entry]:
213
+ raise RuntimeError(
214
+ f"改写后验证不通过({path}):期望 {(python, [entry])},"
215
+ f"读回 {(got.get('command'), got.get('args'))}——可能有并发改写该文件")
216
+ got_env = got.get("env") or {}
217
+ missing = {k: v for k, v in want_env.items() if got_env.get(k) != v}
218
+ if missing:
219
+ raise RuntimeError(f"改写后验证不通过({path}):env 未落全 {missing}")
220
+ return got
221
+
222
+
103
223
  def install(args, packs: str) -> Path:
104
224
  """Codex(D-codex-agents-1 终态):原生插件路径——
105
225
  codex plugin marketplace add <仓>/plugins + plugin add vod-devkit@vod-local,
@@ -186,35 +306,29 @@ def install(args, packs: str) -> Path:
186
306
  print("已安装 codex 原生插件 vod-devkit(skills + MCP,重启 Codex 会话生效)")
187
307
  # P1-5(深审 2026-11-06):插件自带的 .mcp.json 硬编码 env.VOD_PACKS=
188
308
  # core,collect——--packs 对 codex 半失效(运行期仍注册 collect 工具)。
189
- # plugin add 后把缓存内 .mcp.json 的 packs 对齐本次安装值。
190
- import glob as _glob
191
- mcp_jsons = sorted(
192
- _glob.glob(str(Path.home() / ".codex" / "plugins" / "cache"
193
- / mp_name / "vod-devkit" / "*" / ".mcp.json")),
194
- key=lambda p: Path(p).stat().st_mtime, reverse=True)
195
- if mcp_jsons:
309
+ # plugin add 后把缓存内 .mcp.json 改写成「绝对解释器 + 载荷副本」并做
310
+ # 读回验证(静态形态是 `python3` + ${PLUGIN_ROOT},解释器版本靠 PATH;
311
+ # 改写解决的是解释器选择,载荷锚定已由 ${PLUGIN_ROOT} 解决)。
312
+ mcp_path = locate_plugin_mcp(mp_name)
313
+ if mcp_path is not None:
196
314
  try:
197
- mj = json.loads(Path(mcp_jsons[0]).read_text(encoding="utf-8"))
198
- srv = mj.get("mcpServers", {}).get("vod-devkit")
199
- if srv is not None:
200
- # 关键修正(2026-11-12 矩阵实锤):插件自带的 .mcp.json 写的是
201
- # command="vod-devkit" + args=["serve"] —— 依赖 PATH 上那个全局包。
202
- # 机器上装着旧版(实测 0.4.2)时,codex 会静默跑旧副本:配置、
203
- # 技能都是新的,工具面却是旧的。改成绝对解释器 + 载荷副本,与其它
204
- # 宿主同一条铁律(入口不依赖 PATH / npx 缓存)。
205
- srv["command"] = sys.executable
206
- srv["args"] = [server_entry()]
207
- merged = dict(srv.get("env") or {})
208
- merged.update(server_env(args, packs))
209
- srv["env"] = merged
210
- Path(mcp_jsons[0]).write_text(
211
- json.dumps(mj, ensure_ascii=False, indent=2) + "\n",
212
- encoding="utf-8")
213
- print(f"已对齐插件 MCP packs:{mcp_jsons[0]}(VOD_PACKS={packs})")
214
- except Exception as e:
215
- print(f"[vod-devkit] warn: 插件 .mcp.json packs 对齐失败({e})——"
216
- "运行期熔断门禁仍会兜底", file=sys.stderr)
217
- return Path(mcp_jsons[0])
315
+ rewrite_plugin_mcp(mcp_path, python=sys.executable,
316
+ entry=server_entry(), env=server_env(args, packs))
317
+ except PluginMcpRewriteError as e:
318
+ # 分类处置:改不了缓存文件不等于装不上(静态形态本身能跑),
319
+ # 但必须说清是哪一类 + 怎么补救,不笼统 catch 后 exit 1。
320
+ print(f"[vod-devkit] warn({e.kind}): 插件 MCP 未改写成载荷形态:{e.detail}",
321
+ file=sys.stderr)
322
+ print(f"[vod-devkit] 补救:{PluginMcpRewriteError.REMEDY.get(e.kind, '见 INSTALL.md')}",
323
+ file=sys.stderr)
324
+ except RuntimeError as e:
325
+ # 读回与期望不一致 = 留了半写状态给宿主,这类必须让安装失败
326
+ print(f"[vod-devkit] 安装失败:{e}", file=sys.stderr)
327
+ sys.exit(2)
328
+ else:
329
+ print(f"已对齐插件 MCP(解释器 + 载荷副本 + packs):{mcp_path}"
330
+ f"(VOD_PACKS={packs})")
331
+ return mcp_path
218
332
  # 深审 P0-3:绝不再返回 ~/.codex/config.toml——它是用户整份 codex 配置,
219
333
  # uninstall 对 mcpConfig 是删除语义,指向它=卸载删光用户配置(破坏性)
220
334
  print("[vod-devkit] warn: 未定位到插件 .mcp.json(uninstall 将跳过 MCP 清理,"
@@ -223,14 +337,19 @@ def install(args, packs: str) -> Path:
223
337
 
224
338
 
225
339
  def install_remote(args, url, token):
226
- """codex mcp add --url + --bearer-token-env-var(token 由用户环境提供)。"""
340
+ """codex mcp add --url [+ --bearer-token-env-var](token 由用户环境提供)。
341
+
342
+ token 可选(D-token-machine-1):给了才加 --bearer-token-env-var;
343
+ 没给就不带 Bearer,由远程 server 用机器级匿名令牌提交。
344
+ """
227
345
  codex = shutil.which("codex")
228
346
  if not codex:
229
347
  print("[vod-devkit] 未找到 codex CLI,无法走远程注册", file=sys.stderr)
230
348
  sys.exit(2)
231
- r = subprocess.run([codex, "mcp", "add", "vod-devkit", "--url", url,
232
- "--bearer-token-env-var", "VOD_MCP_TOKEN"],
233
- capture_output=True, text=True, timeout=180)
349
+ cmd = [codex, "mcp", "add", "vod-devkit", "--url", url]
350
+ if token:
351
+ cmd += ["--bearer-token-env-var", "VOD_MCP_TOKEN"]
352
+ r = subprocess.run(cmd, capture_output=True, text=True, timeout=180)
234
353
  if r.returncode != 0:
235
354
  print(f"[vod-devkit] codex mcp add(remote)失败:{(r.stderr or r.stdout).strip()[-200:]}",
236
355
  file=sys.stderr)
@@ -240,6 +359,7 @@ def install_remote(args, url, token):
240
359
  print("提示:codex 若曾用插件形态安装过 vod-devkit,请先 "
241
360
  "`codex plugin remove vod-devkit@vod-local` 避免双注册(stdio 插件 .mcp.json "
242
361
  "与本次 remote 配置同名)", file=sys.stderr)
243
- print(f"已注册 Codex 远程 MCP({url})。token 由环境变量 VOD_MCP_TOKEN 提供:\n"
244
- f" export VOD_MCP_TOKEN=<你的 key>(写入 shell 配置或宿主 env)")
362
+ print(f"已注册 Codex 远程 MCP({url})。" + (
363
+ "token 由环境变量 VOD_MCP_TOKEN 提供:\n export VOD_MCP_TOKEN=<你的 key>(写入 shell 配置或宿主 env)"
364
+ if token else "未带 token:提交走远程 server 侧的机器级匿名令牌(同机部署默认形态)"))
245
365
  return None