vod-devkit 0.5.4 → 0.5.8

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 (123) hide show
  1. package/CHANGELOG.md +43 -0
  2. package/QUICKSTART.md +47 -23
  3. package/README.en.md +7 -2
  4. package/README.md +6 -2
  5. package/bin/vod-devkit +12 -1166
  6. package/contract/tools.schema.json +1 -1
  7. package/integrations/atomcode/host.json +5 -3
  8. package/integrations/codeartsdoer/host.json +1 -2
  9. package/package.json +8 -2
  10. package/plugins/vod-devkit/.codex-plugin/plugin.json +1 -1
  11. package/plugins/vod-devkit/build-info.json +3 -3
  12. package/plugins/vod-devkit/contract/tools.schema.json +446 -0
  13. package/plugins/vod-devkit/safety/policy.json +48 -0
  14. package/plugins/vod-devkit/skills/vod-feedback-collect/SKILL.md +13 -4
  15. package/plugins/vod-devkit/skills/vod-problem-classification-rules/SKILL.md +2 -1
  16. package/plugins/vod-devkit/skills/vod-scoring-rules/SKILL.md +2 -1
  17. package/plugins/vod-devkit/vod_mcp/__init__.py +1 -1
  18. package/plugins/vod-devkit/vod_mcp/__pycache__/__init__.cpython-314.pyc +0 -0
  19. package/plugins/vod-devkit/vod_mcp/__pycache__/attribution.cpython-314.pyc +0 -0
  20. package/plugins/vod-devkit/vod_mcp/__pycache__/net.cpython-314.pyc +0 -0
  21. package/plugins/vod-devkit/vod_mcp/__pycache__/paths.cpython-314.pyc +0 -0
  22. package/plugins/vod-devkit/vod_mcp/__pycache__/policy.cpython-314.pyc +0 -0
  23. package/plugins/vod-devkit/vod_mcp/__pycache__/provenance.cpython-314.pyc +0 -0
  24. package/plugins/vod-devkit/vod_mcp/__pycache__/runtime_state.cpython-314.pyc +0 -0
  25. package/plugins/vod-devkit/vod_mcp/__pycache__/skills_registry.cpython-314.pyc +0 -0
  26. package/plugins/vod-devkit/vod_mcp/__pycache__/tools.cpython-314.pyc +0 -0
  27. package/plugins/vod-devkit/vod_mcp/attribution.py +8 -8
  28. package/plugins/vod-devkit/vod_mcp/host_adapters/base.py +3 -1
  29. package/plugins/vod-devkit/vod_mcp/host_adapters/codex.py +16 -3
  30. package/plugins/vod-devkit/vod_mcp/host_adapters/hermes.py +99 -16
  31. package/plugins/vod-devkit/vod_mcp/hosts.py +3 -1
  32. package/plugins/vod-devkit/vod_mcp/net.py +251 -0
  33. package/plugins/vod-devkit/vod_mcp/packs/__pycache__/__init__.cpython-314.pyc +0 -0
  34. package/plugins/vod-devkit/vod_mcp/packs/__pycache__/collect.cpython-314.pyc +0 -0
  35. package/plugins/vod-devkit/vod_mcp/packs/__pycache__/core.cpython-314.pyc +0 -0
  36. package/plugins/vod-devkit/vod_mcp/packs/__pycache__/knowledge.cpython-314.pyc +0 -0
  37. package/plugins/vod-devkit/vod_mcp/packs/collect.py +684 -0
  38. package/plugins/vod-devkit/vod_mcp/packs/core.py +80 -0
  39. package/plugins/vod-devkit/vod_mcp/packs/knowledge.py +17 -0
  40. package/plugins/vod-devkit/vod_mcp/paths.py +38 -0
  41. package/plugins/vod-devkit/vod_mcp/payload.py +3 -1
  42. package/plugins/vod-devkit/vod_mcp/policy.py +3 -2
  43. package/plugins/vod-devkit/vod_mcp/provenance.py +3 -2
  44. package/plugins/vod-devkit/vod_mcp/remote_app.py +25 -0
  45. package/plugins/vod-devkit/vod_mcp/runtime_state.py +324 -0
  46. package/plugins/vod-devkit/vod_mcp/server.py +10 -7
  47. package/plugins/vod-devkit/vod_mcp/skills_registry.py +11 -9
  48. package/plugins/vod-devkit/vod_mcp/tools.py +23 -1300
  49. package/plugins/vod-devkit/vod_mcp/transport_remote.py +68 -8
  50. package/plugins/vod-devkit/vod_mcp/update_check.py +1 -1
  51. package/skills/vod-feedback-collect/SKILL.md +13 -4
  52. package/skills/vod-problem-classification-rules/SKILL.md +2 -1
  53. package/skills/vod-scoring-rules/SKILL.md +2 -1
  54. package/vod_mcp/__init__.py +1 -1
  55. package/vod_mcp/attribution.py +8 -8
  56. package/vod_mcp/host_adapters/__pycache__/__init__.cpython-39.pyc +0 -0
  57. package/vod_mcp/host_adapters/__pycache__/atomcode.cpython-39.pyc +0 -0
  58. package/vod_mcp/host_adapters/__pycache__/base.cpython-314.pyc +0 -0
  59. package/vod_mcp/host_adapters/__pycache__/base.cpython-39.pyc +0 -0
  60. package/vod_mcp/host_adapters/__pycache__/codearts.cpython-39.pyc +0 -0
  61. package/vod_mcp/host_adapters/__pycache__/codeartswork.cpython-39.pyc +0 -0
  62. package/vod_mcp/host_adapters/__pycache__/codex.cpython-314.pyc +0 -0
  63. package/vod_mcp/host_adapters/__pycache__/codex.cpython-39.pyc +0 -0
  64. package/vod_mcp/host_adapters/__pycache__/codex_desktop.cpython-39.pyc +0 -0
  65. package/vod_mcp/host_adapters/__pycache__/dsh.cpython-39.pyc +0 -0
  66. package/vod_mcp/host_adapters/__pycache__/generic.cpython-39.pyc +0 -0
  67. package/vod_mcp/host_adapters/__pycache__/hermes.cpython-314.pyc +0 -0
  68. package/vod_mcp/host_adapters/__pycache__/hermes.cpython-39.pyc +0 -0
  69. package/vod_mcp/host_adapters/__pycache__/opencode.cpython-39.pyc +0 -0
  70. package/vod_mcp/host_adapters/__pycache__/workbuddy.cpython-39.pyc +0 -0
  71. package/vod_mcp/host_adapters/base.py +3 -1
  72. package/vod_mcp/host_adapters/codex.py +16 -3
  73. package/vod_mcp/host_adapters/hermes.py +99 -16
  74. package/vod_mcp/hosts.py +3 -1
  75. package/vod_mcp/net.py +251 -0
  76. package/vod_mcp/packs/__pycache__/__init__.cpython-314.pyc +0 -0
  77. package/vod_mcp/packs/__pycache__/__init__.cpython-39.pyc +0 -0
  78. package/vod_mcp/packs/__pycache__/collect.cpython-314.pyc +0 -0
  79. package/vod_mcp/packs/__pycache__/collect.cpython-39.pyc +0 -0
  80. package/vod_mcp/packs/__pycache__/core.cpython-314.pyc +0 -0
  81. package/vod_mcp/packs/__pycache__/core.cpython-39.pyc +0 -0
  82. package/vod_mcp/packs/__pycache__/knowledge.cpython-314.pyc +0 -0
  83. package/vod_mcp/packs/__pycache__/knowledge.cpython-39.pyc +0 -0
  84. package/vod_mcp/packs/collect.py +684 -0
  85. package/vod_mcp/packs/core.py +80 -0
  86. package/vod_mcp/packs/knowledge.py +17 -0
  87. package/vod_mcp/paths.py +38 -0
  88. package/vod_mcp/payload.py +3 -1
  89. package/vod_mcp/policy.py +3 -2
  90. package/vod_mcp/provenance.py +3 -2
  91. package/vod_mcp/remote_app.py +25 -0
  92. package/vod_mcp/runtime_state.py +324 -0
  93. package/vod_mcp/server.py +10 -7
  94. package/vod_mcp/skills_registry.py +11 -9
  95. package/vod_mcp/tools.py +23 -1300
  96. package/vod_mcp/transport_remote.py +68 -8
  97. package/vod_mcp/update_check.py +1 -1
  98. package/vodkit_cli/__init__.py +10 -0
  99. package/vodkit_cli/__pycache__/__init__.cpython-314.pyc +0 -0
  100. package/vodkit_cli/__pycache__/__init__.cpython-39.pyc +0 -0
  101. package/vodkit_cli/__pycache__/cli.cpython-314.pyc +0 -0
  102. package/vodkit_cli/__pycache__/cli.cpython-39.pyc +0 -0
  103. package/vodkit_cli/__pycache__/common.cpython-314.pyc +0 -0
  104. package/vodkit_cli/__pycache__/common.cpython-39.pyc +0 -0
  105. package/vodkit_cli/__pycache__/doctor.cpython-314.pyc +0 -0
  106. package/vodkit_cli/__pycache__/doctor.cpython-39.pyc +0 -0
  107. package/vodkit_cli/__pycache__/install.cpython-314.pyc +0 -0
  108. package/vodkit_cli/__pycache__/install.cpython-39.pyc +0 -0
  109. package/vodkit_cli/__pycache__/remote.cpython-314.pyc +0 -0
  110. package/vodkit_cli/__pycache__/remote.cpython-39.pyc +0 -0
  111. package/vodkit_cli/__pycache__/uninstall.cpython-314.pyc +0 -0
  112. package/vodkit_cli/__pycache__/uninstall.cpython-39.pyc +0 -0
  113. package/vodkit_cli/__pycache__/update.cpython-314.pyc +0 -0
  114. package/vodkit_cli/__pycache__/update.cpython-39.pyc +0 -0
  115. package/vodkit_cli/cli.py +86 -0
  116. package/vodkit_cli/common.py +254 -0
  117. package/vodkit_cli/doctor.py +269 -0
  118. package/vodkit_cli/install.py +260 -0
  119. package/vodkit_cli/remote.py +200 -0
  120. package/vodkit_cli/uninstall.py +161 -0
  121. package/vodkit_cli/update.py +45 -0
  122. /package/plugins/vod-devkit/vod_mcp/{packs.py → packs/__init__.py} +0 -0
  123. /package/vod_mcp/{packs.py → packs/__init__.py} +0 -0
@@ -21,8 +21,11 @@ devkit 的契约(mcp-server-remote.ts + test/remote-mcp-server.test.ts 实测
21
21
  """
22
22
  import asyncio
23
23
  import json
24
+ import os
24
25
  import sys
25
26
  import threading
27
+
28
+ from vod_mcp import net, paths
26
29
  from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
27
30
 
28
31
  DEFAULT_HOST = "127.0.0.1"
@@ -30,6 +33,44 @@ DEFAULT_PORT = 9528
30
33
  MAX_BODY = 4 * 1024 * 1024
31
34
  LOOPBACK = ("127.0.0.1", "localhost", "::1")
32
35
 
36
+ # 载荷自校验缓存:远程面是长驻无鉴权服务,被改过的服务端载荷要当场拒绝服务,
37
+ # 不能等运维跑 doctor 才发现(devkit 的每请求 verifySkillTree 同思路)。
38
+ # TTL 缓存避免每个请求都做一遍 sha256 全集(40+ 文件)。
39
+ _PAYLOAD_GUARD = {"at": 0.0, "sig": None, "problems": []}
40
+ _PAYLOAD_GUARD_TTL = 30.0
41
+
42
+
43
+ def payload_problems(force: bool = False) -> list:
44
+ """远程面载荷完整性检查(载荷目录不存在/被改 → 非空列表)。
45
+
46
+ 只校验"载荷副本"形态:stdio/仓内直跑没有 payload.json,返回空(不误伤)。
47
+ """
48
+ import time as _t
49
+ from pathlib import Path
50
+ from vod_mcp import payload as _pl
51
+ _P = Path
52
+ # 显式 env 优先(安装期注入),否则按自身所在树推断——*不许* import
53
+ # host_adapters:它的 __init__ 会连带 import 各宿主适配模块,而载荷副本不含
54
+ # integrations/(2026-11-12 实锤:请求线程 KeyError → 每个请求 500)。
55
+ env_dir = (os.environ.get("VOD_PAYLOAD_DIR") or "").strip()
56
+ d = _P(env_dir) if env_dir else None
57
+ if d is None:
58
+ # 从载荷副本直接起来的服务(entry = <payload>/vod_mcp/server.py)没有
59
+ # install 期注入的 payload_dir —— 用自身所在树推断:载荷根里有 payload.json
60
+ # 就说明"我就是那份副本",必须自校验(否则被改的副本会一直对外服务)。
61
+ root = _P(paths.ROOT)
62
+ d = root if (root / "payload.json").exists() else None
63
+ if d is None:
64
+ return []
65
+ meta = _P(d) / "payload.json"
66
+ sig = (str(meta), meta.stat().st_mtime if meta.exists() else 0.0)
67
+ now = _t.time()
68
+ if not force and _PAYLOAD_GUARD["sig"] == sig and now - _PAYLOAD_GUARD["at"] < _PAYLOAD_GUARD_TTL:
69
+ return list(_PAYLOAD_GUARD["problems"])
70
+ problems = _pl.verify(_P(d))
71
+ _PAYLOAD_GUARD.update({"at": now, "sig": sig, "problems": list(problems)})
72
+ return problems
73
+
33
74
 
34
75
  class RemoteRuntime:
35
76
  """持有 asyncio 事件循环 + SDK session manager 的生命周期。"""
@@ -69,6 +110,13 @@ class RemoteRuntime:
69
110
  逐块而不是攒全再写:devkit 的 shell 也是 `for await (chunk of
70
111
  response.body) res.write(chunk)`——SSE 这种长响应攒全再写等于把流式
71
112
  语义废掉(客户端一个字节都看不到,直到响应结束)。
113
+
114
+ 身份传播(2026-11-13 真机实锤修复):contextvars 不跨线程——do_POST
115
+ 在 HTTP 线程 set 的 _REQ_KEY/_SERVER_FACE 到不了事件循环线程的
116
+ on_call_tool(submit 的 -32012 之所以还能触发,是走运的本地态分支)。
117
+ 修法:把 key/face 作为参数传入,投递协程体内 set——run_coroutine_threadsafe
118
+ 在 loop 线程为 run() 建任务,任务继承创建时刻的 context,体内 set 即对
119
+ handle_request 派生的整个协程链(含 asyncio.to_thread 复制)可见。
72
120
  """
73
121
  state = {"body_sent": False}
74
122
 
@@ -90,9 +138,14 @@ class RemoteRuntime:
90
138
  sink.body(chunk)
91
139
 
92
140
  async def run():
141
+ # 协程体内 set:见 request() docstring 的身份传播修复说明
142
+ tok_key = net._REQ_KEY.set(scope.get("x_vod_key") or None)
143
+ tok_face = net._SERVER_FACE.set(True)
93
144
  try:
94
145
  await self.manager.handle_request(scope, receive, send)
95
146
  finally:
147
+ net._SERVER_FACE.reset(tok_face)
148
+ net._REQ_KEY.reset(tok_key)
96
149
  sink.end()
97
150
 
98
151
  fut = asyncio.run_coroutine_threadsafe(run(), self._loop)
@@ -250,23 +303,30 @@ class _Handler(BaseHTTPRequestHandler):
250
303
  if isinstance(message, dict) and "id" not in message:
251
304
  self._empty(202)
252
305
  return
306
+ # 服务端载荷自校验:被改/缺文件的载荷不许继续对外服务
307
+ problems = payload_problems()
308
+ if problems:
309
+ self._json(503, {"jsonrpc": "2.0", "id": message.get("id") if isinstance(message, dict) else None,
310
+ "error": {"code": -32603,
311
+ "message": "服务端载荷校验未通过(拒绝服务):"
312
+ + ";".join(problems[:5])}})
313
+ return
314
+
253
315
  raw_auth = (self.headers.get("Authorization") or "").strip()
254
316
  key = raw_auth[7:].strip() if raw_auth.lower().startswith("bearer ") else ""
255
317
 
256
- from vod_mcp import tools
318
+ # 身份经 scope 传递(x_vod_key),由 RemoteRuntime.request 在事件循环线程
319
+ # 的协程体内 set _REQ_KEY/_SERVER_FACE——HTTP 线程直接 set 的 contextvar
320
+ # 过不了 run_coroutine_threadsafe 的线程边界(2026-11-13 真机实锤)。
321
+ scope = _scope(self, body)
322
+ scope["x_vod_key"] = key
257
323
  sink = _StreamSink(self)
258
- tok_key = tools._REQ_KEY.set(key or None)
259
- tok_face = tools._SERVER_FACE.set(True)
260
324
  try:
261
- self.server.runtime.request(_scope(self, body), body, sink)
325
+ self.server.runtime.request(scope, body, sink)
262
326
  except Exception as e: # 传输层异常:能答就答 500,已经流出去就断连
263
327
  if not sink.started:
264
328
  self._json(500, {"jsonrpc": "2.0", "id": None,
265
329
  "error": {"code": -32603, "message": str(e)}})
266
- return
267
- finally:
268
- tools._SERVER_FACE.reset(tok_face)
269
- tools._REQ_KEY.reset(tok_key)
270
330
 
271
331
 
272
332
  def serve(host: str, port: int) -> int:
@@ -52,7 +52,7 @@ def _version_tuple(v: str) -> tuple:
52
52
 
53
53
 
54
54
  def check(params: dict | None = None) -> dict:
55
- from vod_mcp import __version__, tools
55
+ from vod_mcp import __version__, runtime_state as tools
56
56
  params = params or {}
57
57
  dismiss = bool(params.get("dismiss"))
58
58
  skip = bool(params.get("skip"))
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: vod-feedback-collect
3
- description: '用户抱怨/体验差/太慢/报错/提单 → 采集原话进 VOD。识别到抱怨即承接并征得同意(禁止问哪个产品,禁止复现排查模式);content=原话逐字;一次抱怨一条;回执 echo 原样转述。详见正文流程与禁令。Triggers: "体验差","太难用","太慢","报错了","出bug了","有bug","反馈问题","反馈建议","提个单","报告问题","不生效","不好使","操作不方便","卡住了","崩溃了","report a problem","bug report","poor experience","feedback"'
3
+ description: '用户抱怨/体验差/太慢/报错/提单 → 采集原话进 VOD。识别到抱怨即承接并征得同意(缺产品先问一次是哪个、不猜也不提交;禁止复现排查模式);content=原话逐字;一次抱怨一条;回执 echo 原样转述。详见正文流程与禁令。Triggers: "体验差","太难用","太慢","报错了","出bug了","有bug","反馈问题","反馈建议","提个单","报告问题","不生效","不好使","操作不方便","卡住了","崩溃了","report a problem","bug report","poor experience","feedback"'
4
4
  tags: [vod, feedback, capture, consent]
5
5
  metadata:
6
6
  version: 1
@@ -180,8 +180,10 @@ metadata:
180
180
  ## 采集流程
181
181
 
182
182
  0. 产品归因(D-product-ask-1,2026-11-12 拍板:不许裸提交 UNKNOWN):
183
- 归因次序 = 用户明确回答 > 原话唯一高置信提及 > 会话记忆(30 分钟) >
184
- 安装先验 > 宿主产品(host_default,仅用户说不知道时,低置信)。
183
+ 归因次序 = 用户明确回答 > 原话唯一高置信提及 > 会话记忆(30 分钟) > 安装先验。
184
+ 四级都拿不到 → **不猜、不提交**,按下面的追问规则请用户补一句产品名
185
+ (2026-11-12 复评删除 host_default 兜底:宿主产品也是一次推断,错归会进
186
+ 引擎幂等/判重域,污染静默且难追溯)。
185
187
  - 原话里只有一个产品名、且不是对比/多产品语境 → 直接用,不再问
186
188
  - 原话有两个以上产品("CodeArts 比 MaaS 好"、"从 CodeArts 导出到 MaaS")
187
189
  → 视为**低置信**,必须问:"这条反馈是哪个产品的?可用候选:…"
@@ -217,7 +219,8 @@ metadata:
217
219
  "网页卡回复慢"被宿主改写成「网页打开,…」+「网页卡,…」两条入库建出
218
220
  两个 issue;引擎幂等按内容逐字比对,改写即绕过)。多条仅当用户明确
219
221
  分条给了多个不同反馈
220
- 4. 拿到回执 → 对用户说人话:"已收录,产品团队会看到这条反馈"——
222
+ 4. 拿到回执 → 对用户说人话:"已收录,产品团队会看到这条反馈";
223
+ (若对方是验证者且明确要编号,按第 0 条例外贴 voiceId)——
221
224
  **voiceId 不展示给终端用户**(编号噪音),仅供 agent 对账用;
222
225
  用户追问"提交了吗"时 agent 用 voiceId/taskId 核对后回答状态
223
226
  5. **无通道 fallback(D-pending-1,插件未安装/无 vod 工具时)**:
@@ -241,6 +244,12 @@ metadata:
241
244
  ## 纪律
242
245
 
243
246
  0. 回执纪律(F2,成功与失败路径同口径):给用户的话=人话
247
+
248
+ **验证/对账例外(2026-11-12 拍板)**:当对方是**验证者**(运维/研发/负责人在
249
+ 核对链路,明确说"把 voiceId 贴出来""我核对下入库")时,允许同样打印
250
+ `voiceId`、`productId`、`productSource`——那是他们的对账主键,不是给反馈提交者看的
251
+ 噪音。判据两条同时满足:①对方明确要求要编号;②对方在验证链路而不是在提交自己的
252
+ 抱怨。终端用户(提交反馈的人)问"提交了吗",仍只回答状态、不展示编号。
244
253
  (成功=已收录/产品团队会看到;失败=提交失败,反馈已暂存本机,
245
254
  稍后会自动重试)。**失败时禁止向用户复述内部诊断字段**——HTTP
246
255
  状态码、apiKeyFingerprint、tokenTier、堆栈等属于 agent 内部排障
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: vod-problem-classification-rules
3
- description: VOD 问题分类规则(引擎 v2.2 真实口径)— 六类定义、判定细节、LLM 分类流程。真源=workflow/src/n01_classify.py(VOD-Project 2bb3fc82 实测核对)。
3
+ description: VOD 问题分类规则(引擎 v2.2 真实口径)— 六类定义、判定细节、LLM 分类流程。
4
4
  tags: [vod, classification, rules]
5
5
  metadata:
6
6
  version: 2
@@ -13,6 +13,7 @@ metadata:
13
13
  > 体验优化/其他)已废弃,与引擎不符——它来自过期文档。
14
14
  > 采集定位:预分类仅作参考 hint(tags),引擎 LLM 按六类重判——
15
15
  > 预分类不是终局,别和用户言之凿凿。
16
+ > 对外复述纪律:可讲口径(六类边界/判定要点),不引用仓库路径、文件行号、提交号。
16
17
 
17
18
  ## 六类定义(引擎 DEFAULT_TYPE_DEFS 原文)
18
19
 
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: vod-scoring-rules
3
- description: VOD 评分规则(引擎 v2 真实公式)— 四项加法、上下限、优先级映射。真源=workflow/src/workflow_v2.py(VOD-Project 2bb3fc82 实测核对)。
3
+ description: VOD 评分规则(引擎 v2 真实公式)— 四项加法、上下限、优先级映射。
4
4
  tags: [vod, scoring, rules]
5
5
  metadata:
6
6
  version: 2
@@ -11,6 +11,7 @@ metadata:
11
11
  > 真源纪律:以 workflow_v2.py 评分函数为准,2026-11-03 逐行核对。
12
12
  > 旧版"五项维度含用户价值"口径作废——引擎是四项,且非重点问题
13
13
  > 上限不同(下方原文),旧文档没写。
14
+ > 对外复述纪律:可讲公式要点与上下限,不引用仓库路径、文件行号、提交号。
14
15
 
15
16
  ## 评分公式(引擎代码原文语义)
16
17
 
@@ -5,7 +5,7 @@
5
5
  2. 外部无 DB 直连路径(护栏 deny 兜底)
6
6
  3. 任务 ID 是唯一对账主键,写类工具返回一律携带
7
7
  """
8
- __version__ = "0.5.4"
8
+ __version__ = "0.5.8"
9
9
  # 默认上游:VOD 测试环境。外部用户本机无 VOD,回环默认值=装完即坏;
10
10
  # 生产地址定型后只改这一处(tools.py 与 bin/vod-devkit 共用本常量)。
11
11
  DEFAULT_JAVA_BASE = "https://vod-dev.topxtopx.com"
@@ -163,19 +163,19 @@ def build_alias_index(meta: dict) -> list:
163
163
 
164
164
  # ② 品牌俗称表:把无法从表名推导的口语词挂到目标产品上
165
165
  for target_name, colloquials in (BRAND_ALIASES or {}).items():
166
- slot = canon.get(str(target_name).lower())
167
- if slot is None:
166
+ brand_slot: dict | None = canon.get(str(target_name).lower())
167
+ if brand_slot is None:
168
168
  # 目标产品不在本次 catalog(引擎换库/改名):别名不落地,避免指向
169
169
  # 不存在的 id。宁可丢俗称,也不产生错归。
170
170
  continue
171
171
  for word in (colloquials or []):
172
172
  if word:
173
- slot["aliases"].add(str(word).strip())
173
+ brand_slot["aliases"].add(str(word).strip())
174
174
 
175
175
  # ③ 兼容:若引擎仍下发旧字段(回滚场景),继续采纳,避免双向改造期丢能力
176
176
  for key, aliases in (meta.get("nameAliases") or {}).items():
177
177
  aliases = [str(a) for a in (aliases or []) if a]
178
- target = canon.get(str(key).lower())
178
+ target: dict | None = canon.get(str(key).lower())
179
179
  if target is None:
180
180
  for a in aliases:
181
181
  if a.lower() in canon:
@@ -187,10 +187,10 @@ def build_alias_index(meta: dict) -> list:
187
187
  target["aliases"].add(a)
188
188
  target["aliases"].add(str(key))
189
189
  for key, target_name in (meta.get("aliases") or {}).items():
190
- slot = canon.get(str(target_name).lower())
191
- if slot is None: # 目录/展示名都没有该目标:按别名目标建槽,别丢别名
192
- slot = _slot(target_name, False)
193
- slot["aliases"].add(str(key))
190
+ alias_slot: dict | None = canon.get(str(target_name).lower())
191
+ if alias_slot is None: # 目录/展示名都没有该目标:按别名目标建槽,别丢别名
192
+ alias_slot = _slot(target_name, False)
193
+ alias_slot["aliases"].add(str(key))
194
194
 
195
195
  for slot in canon.values(): # 名字/别名任一命中 catalog → 拿 id
196
196
  for alias in list(slot["aliases"]) + [slot["label"]]:
@@ -4,7 +4,9 @@ import os
4
4
  import shutil
5
5
  from pathlib import Path
6
6
 
7
- ROOT = Path(__file__).resolve().parent.parent.parent
7
+ from vod_mcp import paths
8
+
9
+ ROOT = paths.ROOT
8
10
 
9
11
  # 载荷目录(bin 在 install 前用 payload.stage() 落好并 set_payload_dir 指过来)
10
12
  _PAYLOAD_DIR = None
@@ -16,11 +16,24 @@ _AGENTS_MARKER_BEGIN = "<!-- vod-devkit:feedback-skill BEGIN -->"
16
16
  # 且 1705 个历史会话带着它跑(实测)。清理逻辑必须认这个标记,否则残留继续生效。
17
17
  _LEGACY_ONE_LINER = "<!-- vod-submit-one-liner -->"
18
18
  _AGENTS_MARKER_END = "<!-- vod-devkit:feedback-skill END -->"
19
- _SPEC = host_specs.load("codex")
19
+ _SPEC: dict | None = None
20
+
21
+
22
+ def _spec() -> dict:
23
+ """调用期解析宿主配置(模块 import 期读 integrations/ 会在载荷副本里炸)。
24
+
25
+ 2026-11-12 实锤:载荷副本不含 integrations/,import 期 host_specs.load("codex")
26
+ 直接 KeyError → 远程面每个请求 500。宿主配置只在 install 期用得上,运行期
27
+ server 不需要它。
28
+ """
29
+ global _SPEC
30
+ if _SPEC is None:
31
+ _SPEC = host_specs.load("codex")
32
+ return _SPEC
20
33
 
21
34
 
22
35
  def skills_dir(args):
23
- d = _SPEC.get("skillsDir")
36
+ d = _spec().get("skillsDir")
24
37
  return Path(d) if d else None
25
38
 
26
39
 
@@ -98,7 +111,7 @@ def install(args, packs: str) -> Path:
98
111
  if not codex:
99
112
  print("[vod-devkit] 未找到 codex CLI,无法走原生插件安装", file=sys.stderr)
100
113
  sys.exit(2)
101
- spec = host_specs.load("codex")
114
+ spec = _spec()
102
115
  conf = Path(spec["configPath"])
103
116
  if conf.exists(): # 历史遗留:config.toml MCP 段与插件同名=双注册,移除
104
117
  text = conf.read_text(encoding="utf-8")
@@ -14,19 +14,31 @@ from vod_mcp.host_adapters.base import ROOT, server_env, server_entry
14
14
 
15
15
  HOST = "hermes"
16
16
  SUPPORTS_REMOTE = True
17
- _SPEC = host_specs.load("hermes")
18
- _MCP_DIR = Path(_SPEC["configPath"]).parent
17
+ def _spec() -> dict:
18
+ """调用期现读:host.json 的 ~ 必须在调用期按当前 HOME 解析。
19
+
20
+ 2026-11-12 实锤:模块 import 期求值 _MCP_DIR 后,测试里 monkeypatch HOME
21
+ 写不到隔离目录,直接把真实 ~/.hermes/mcp/vod-devkit.json 覆盖成了桩值
22
+ (command=/x/vod_mcp/server.py)——真机 doctor 当场读到坏条目。
23
+ """
24
+ return host_specs.load("hermes")
19
25
 
20
26
 
21
27
  def skills_dir(args):
22
- return Path(_SPEC["skillsDir"])
28
+ return Path(_spec()["skillsDir"])
23
29
 
24
30
 
25
31
  PLUGIN_NAME = "vod-feedback-router"
26
32
 
27
33
 
28
34
  def _enabled_plugins() -> list:
29
- """读 hermes 配置里的 plugins.enabled(CLI 输出是 "- name" 行)。"""
35
+ """读 hermes 配置里的 plugins.enabled(CLI 输出是 "- name" 行)。
36
+
37
+ 无 CLI 直接返回空:裸 subprocess 会抛 FileNotFoundError 打崩整个 install
38
+ (CI/无宿主机器上实测)——缺 CLI 是"降级"不是"失败"。
39
+ """
40
+ if not shutil.which("hermes"):
41
+ return []
30
42
  r = subprocess.run(["hermes", "config", "get", "plugins.enabled"],
31
43
  capture_output=True, text=True, timeout=60)
32
44
  if r.returncode != 0:
@@ -67,7 +79,7 @@ def enable_plugin(name: str = PLUGIN_NAME) -> str:
67
79
 
68
80
  def install(args, packs: str) -> Path:
69
81
  """Hermes:官方途径 hermes mcp add(config.yaml mcp_servers)。"""
70
- conf = _MCP_DIR / "vod-devkit.json"
82
+ conf = Path(_spec()["configPath"]).parent / "vod-devkit.json"
71
83
  conf.parent.mkdir(parents=True, exist_ok=True)
72
84
  conf.write_text(json.dumps({
73
85
  "name": "vod-devkit", "command": sys.executable,
@@ -76,10 +88,18 @@ def install(args, packs: str) -> Path:
76
88
  env_args = []
77
89
  for k, v in server_env(args, packs).items():
78
90
  env_args.extend([k + "=" + v])
79
- r = subprocess.run(
80
- ["hermes", "mcp", "add", "vod-devkit", "--command", sys.executable,
81
- *["--env"] + env_args, "--args", server_entry()],
82
- input="y\ny\n", capture_output=True, text=True)
91
+ # 无 CLI 时不裸 exec(FileNotFoundError 会打崩 install):JSON 已落盘,
92
+ # 用户可手工并入 config.yaml —— 缺 CLI 是降级,不是失败。
93
+ if shutil.which("hermes"):
94
+ r = subprocess.run(
95
+ ["hermes", "mcp", "add", "vod-devkit", "--command", sys.executable,
96
+ *["--env"] + env_args, "--args", server_entry()],
97
+ input="y\ny\n", capture_output=True, text=True)
98
+ else:
99
+ r = None
100
+ print(f"提示:未找到 hermes CLI(PATH),已写出配置片段:{conf}\n"
101
+ " 将其并入 ~/.hermes/config.yaml 的 mcp_servers 后重启会话生效",
102
+ file=sys.stderr)
83
103
  # D-hook-1:强制评估路由插件(pre_llm_call 确定性意图路由,业界 forced-eval 模式)
84
104
  plug_src = ROOT / "hermes-plugin" / "vod-feedback-router"
85
105
  plug_dst = Path.home() / ".hermes" / "plugins" / PLUGIN_NAME
@@ -92,7 +112,9 @@ def install(args, packs: str) -> Path:
92
112
  "unchanged": "已在 plugins.enabled 中",
93
113
  "skipped": "未自动启用(见上方提示)"}[state]
94
114
  print(f"已安装 {PLUGIN_NAME} 路由插件(~/.hermes/plugins/,{verb};重启会话生效)")
95
- if r.returncode == 0:
115
+ if r is None:
116
+ pass # 无 CLI:上面已经给过指引
117
+ elif r.returncode == 0:
96
118
  print("已注册 Hermes MCP(hermes mcp list 可见;重启会话生效)")
97
119
  else:
98
120
  print(f"提示:hermes mcp add 未成功({r.stderr.strip()[:150]});"
@@ -101,21 +123,82 @@ def install(args, packs: str) -> Path:
101
123
 
102
124
 
103
125
  def install_remote(args, url, token):
104
- """hermes mcp add --url:token 经 env 注入,配置里只留 ${MCP_VOD_DEVKIT_API_KEY} 引用。"""
126
+ """hermes mcp add --url:token 经 env 注入,配置里只留 ${MCP_VOD_DEVKIT_API_KEY} 引用。
127
+
128
+ B1(2026-11-13 真机实锤):hermes mcp add 对已存在条目的交互链是三问
129
+ (Overwrite? → 认证? → Enable all tools?),管道 input 只给两个 y 时第三问
130
+ 读不到输入 → hermes 端 Cancelled 且仍 exit 0 → 安装器打印"已注册"但
131
+ config.yaml 纹丝不动(静默假绿)。修法两道:
132
+ ①stdin 喂不封顶的 y 流(迭代器持续供给,hermes 问几问答几个——多问多答、
133
+ 少问即 EOF 收尾),不再数提示个数;
134
+ ②rc=0 不算数——读回 hermes 配置真源(config.yaml mcp_servers.vod-devkit
135
+ 的 url),断言远程条目真的写进去了;没写进去就非零退出报"未注册",
136
+ 绝不静默。
137
+ """
105
138
  import os
106
139
  env = os.environ.copy()
107
140
  env["MCP_VOD_DEVKIT_API_KEY"] = token
141
+
142
+ def _yes_forever():
143
+ # 交互问数随 hermes 版本变化(首次装=2 问,覆盖装=3 问),流式供给不数数
144
+ for _ in range(64):
145
+ yield "y\n"
146
+
108
147
  r = subprocess.run(
109
148
  ["hermes", "mcp", "add", "vod-devkit", "--url", url, "--auth", "header"],
110
- input="y\ny\n", capture_output=True, text=True, env=env, timeout=180)
111
- if r.returncode != 0:
112
- print(f"[vod-devkit] hermes mcp add(remote)失败:{(r.stderr or r.stdout).strip()[-200:]}",
113
- file=sys.stderr)
149
+ input="".join(_yes_forever()), capture_output=True, text=True, env=env,
150
+ timeout=180)
151
+ # 防静默:读回 config.yaml 断言远程条目在(Cancelled 会 rc=0 但不落配置)
152
+ registered = _hermes_registration_is_remote(url)
153
+ if r.returncode != 0 or not registered:
154
+ reason = (f"hermes mcp add rc={r.returncode},"
155
+ + ("配置读回未见远程条目(交互确认被跳过即静默取消)" if not registered
156
+ else f"stderr={(r.stderr or '').strip()[-150:]}"))
157
+ print(f"[vod-devkit] Hermes 远程 MCP 注册未落盘:{reason}\n"
158
+ " 可手工执行:hermes mcp add vod-devkit --url <url> --auth header "
159
+ "(逐问回答 y)", file=sys.stderr)
114
160
  sys.exit(1)
115
- conf = _MCP_DIR / "vod-devkit.json"
161
+ conf = Path(_spec()["configPath"]).parent / "vod-devkit.json"
116
162
  conf.parent.mkdir(parents=True, exist_ok=True)
117
163
  conf.write_text(json.dumps({"name": "vod-devkit", "url": url,
118
164
  "headers": {"Authorization": "Bearer ${MCP_VOD_DEVKIT_API_KEY}"}},
119
165
  ensure_ascii=False, indent=2), encoding="utf-8")
120
166
  print(f"已注册 Hermes 远程 MCP({url};token 存 ~/.hermes/.env,配置内只留引用)")
121
167
  return conf
168
+
169
+
170
+ def _hermes_registration_is_remote(url: str) -> bool:
171
+ """读回 hermes 内部注册真源(config.yaml mcp_servers),断言 vod-devkit 是远程条目。
172
+
173
+ hermes mcp add 写 ~/.hermes/config.yaml 的 mcp_servers.vod-devkit(url 字段
174
+ 为远程形态标志);Cancelled 的假绿在这里现形。无 yaml 依赖红线:远端
175
+ 安装器零第三方依赖,这里用受限文本扫描(顶层 mcp_servers: 段下缩进块内
176
+ 找 vod-devkit 与 url 行),而非完整 yaml 解析。
177
+ """
178
+ cfg = Path.home() / ".hermes" / "config.yaml"
179
+ if not cfg.is_file():
180
+ return False
181
+ in_section = False
182
+ saw_entry = False
183
+ saw_url = False
184
+ for raw_line in cfg.read_text(encoding="utf-8").splitlines():
185
+ if not raw_line.strip() or raw_line.lstrip().startswith("#"):
186
+ continue
187
+ indented = raw_line[0] == " "
188
+ stripped = raw_line.strip()
189
+ if not indented:
190
+ in_section = stripped.startswith("mcp_servers:")
191
+ continue
192
+ if not in_section:
193
+ continue
194
+ # mcp_servers 段内的行:条目名(一级缩进)与字段(更深缩进)
195
+ if stripped.startswith("vod-devkit:"):
196
+ saw_entry = True
197
+ elif saw_entry and stripped.startswith("url:"):
198
+ if url in stripped:
199
+ saw_url = True
200
+ break
201
+ elif saw_entry and not raw_line.startswith(" vod-devkit") and stripped.endswith(":"):
202
+ if not raw_line.startswith(" " * 4): # 下一个一级条目:停止
203
+ break
204
+ return saw_entry and saw_url
package/vod_mcp/hosts.py CHANGED
@@ -15,7 +15,9 @@ import json
15
15
  import platform
16
16
  from pathlib import Path
17
17
 
18
- ROOT = Path(__file__).resolve().parent.parent
18
+ from vod_mcp import paths
19
+
20
+ ROOT = paths.ROOT
19
21
  INTEGRATIONS = ROOT / "integrations"
20
22
 
21
23