vod-devkit 0.4.4 → 0.5.0

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 (37) hide show
  1. package/CHANGELOG.md +15 -0
  2. package/README.en.md +5 -4
  3. package/README.md +44 -9
  4. package/bin/vod-devkit +143 -111
  5. package/contract/tools.schema.json +38 -1
  6. package/integrations/codex/host.json +20 -0
  7. package/integrations/dsh/host.json +15 -0
  8. package/integrations/hermes/host.json +20 -0
  9. package/integrations/opencode/command/vod-doctor.md +10 -0
  10. package/integrations/opencode/host.json +28 -0
  11. package/package.json +10 -10
  12. package/plugins/vod-devkit/.codex-plugin/plugin.json +1 -1
  13. package/plugins/vod-devkit/build-info.json +3 -3
  14. package/plugins/vod-devkit/skills/vod-core/SKILL.md +35 -15
  15. package/plugins/vod-devkit/vod_mcp/__init__.py +1 -1
  16. package/plugins/vod-devkit/vod_mcp/config_forms.py +154 -0
  17. package/plugins/vod-devkit/vod_mcp/guardrails.py +25 -0
  18. package/plugins/vod-devkit/vod_mcp/hosts.py +80 -0
  19. package/plugins/vod-devkit/vod_mcp/packs.py +17 -3
  20. package/plugins/vod-devkit/vod_mcp/remote_app.py +100 -0
  21. package/plugins/vod-devkit/vod_mcp/server.py +30 -15
  22. package/plugins/vod-devkit/vod_mcp/skills_registry.py +124 -0
  23. package/plugins/vod-devkit/vod_mcp/tools.py +70 -9
  24. package/plugins/vod-devkit/vod_mcp/transport_remote.py +289 -0
  25. package/plugins/vod-devkit/vod_mcp/update_check.py +105 -0
  26. package/skills/vod-core/SKILL.md +35 -15
  27. package/vod_mcp/__init__.py +1 -1
  28. package/vod_mcp/config_forms.py +154 -0
  29. package/vod_mcp/guardrails.py +25 -0
  30. package/vod_mcp/hosts.py +80 -0
  31. package/vod_mcp/packs.py +17 -3
  32. package/vod_mcp/remote_app.py +100 -0
  33. package/vod_mcp/server.py +30 -15
  34. package/vod_mcp/skills_registry.py +124 -0
  35. package/vod_mcp/tools.py +70 -9
  36. package/vod_mcp/transport_remote.py +289 -0
  37. package/vod_mcp/update_check.py +105 -0
package/CHANGELOG.md CHANGED
@@ -260,3 +260,18 @@
260
260
  - 1e55b12 fix(dsh): 反馈按钮静默不渲染根治——dock 槽名跨版本漂移,双候选注册+互斥锁
261
261
  - 79c2296 chore(release): golden 随 v0.4.3 重录(仅版本值漂移,人工过目合规)
262
262
 
263
+
264
+ ## v0.5.0(2026-11-11)
265
+
266
+ - 0b72a3f fix(传输): 把"够用就行"的两条账做实——流式逐块写、capabilities 对齐,另补请求头规范化
267
+ - 5f10b75 feat(传输): Streamable HTTP 远程面——形态照 devkit,身份与写面按我们的边界收紧
268
+ - 4020f73 feat(dsh/CI): dsh 补技能落点与只读工具面 + CI 加凭据扫描
269
+ - a4a92e3 docs(decisions): D-devtoolchain-1..5 台账(对表 devkit 的五条改造与残余)
270
+ - 35abac6 refactor(安装器): 宿主适配层数据化(integrations/<host>/host.json)
271
+ - 82d4396 feat(发版/冒烟): publish 终态断言 + 多宿主功能级冒烟
272
+ - 211247a feat(技能/版本): 领域技能披露第二轨 + 版本提醒,并修 vod-core 路由过期
273
+ - bcbc738 feat(安装器): 宿主配置形态守卫 + 单一扫描器(顺带修掉 TOML 孤儿子表真 bug)
274
+ - 13f76fa feat(对账): 用例花名册棘轮 + 声明计数门禁 + doctor golden 三态 + 安全模型文档
275
+ - 061ca39 docs: dsh 插件接入安装手册(三条安装路径/配置/验证/公网反代/FAQ)
276
+ - dbfb31c chore(release): golden 随 v0.4.4 重录(仅 version 字段,人工过目合规)
277
+
package/README.en.md CHANGED
@@ -65,10 +65,11 @@ Verified hosts: Hermes (official `hermes mcp add`), OpenCode
65
65
 
66
66
  ## Quality
67
67
 
68
- 39 tests (unit / guardrails / packs / installer matrix across three hosts /
69
- protocol-level real-HTTP lock /
70
- stdio roundtrip / meta cache / ledger) + pre-push gate + GitHub Actions
71
- CI on the mirror + nightly local E2E against the test environment.
68
+ Full pytest + node:test suite (unit / guardrails / packs / installer matrix across
69
+ four hosts / protocol-level real-HTTP lock / stdio roundtrip / meta cache /
70
+ ledger). Counts are never written into docs by hand — they drift; measure with
71
+ `python3 -m pytest tests/ -q`. Plus pre-push gate + GitHub Actions CI on the
72
+ mirror + nightly local E2E against the test environment.
72
73
 
73
74
  Docs: [README.md (中文)](README.md) · QUICKSTART.md · CONTRIBUTING.md ·
74
75
  SECURITY.md · SUPPORT.md · CODE_OF_CONDUCT.md · NOTICE · docs/proposal.md ·
package/README.md CHANGED
@@ -52,21 +52,56 @@ python3 -m vod_mcp.server # stdio,JSON-RPC
52
52
  VOD_PACKS=core,collect python3 -m vod_mcp.server # packs 裁剪
53
53
  ```
54
54
 
55
- ## 工具面(契约唯一事实源:contract/tools.schema.json)
55
+ ## 远程面(Streamable HTTP)
56
+
57
+ 默认形态是 stdio(各宿主拉起子进程,零端口)。如果你的 agent 支持
58
+ `type: "remote"`(Streamable HTTP),可以单独起一个常驻进程,供多个 agent 共用:
59
+
60
+ ```bash
61
+ pip install 'vod-devkit[remote]' # 远程面依赖官方 MCP SDK(stdio 形态不需要)
62
+ vod-devkit serve --transport remote # 默认 http://127.0.0.1:9528
63
+ ```
56
64
 
57
- | 工具 | 类型 | 护栏 |
58
- |---|---|---|
65
+ ```jsonc
66
+ { "mcp": { "vod-devkit": {
67
+ "type": "remote", "url": "http://localhost:9528", "enabled": true } } }
68
+ ```
69
+
70
+ 端口被占用用 `--port <port>`(同步改 url);`--host 0.0.0.0` 可开 LAN 访问。
71
+
72
+ 边界(与 stdio 形态的实质差别):
73
+
74
+ - **身份从请求头来**:每个请求带 `Authorization: Bearer <VOD key>`;缺 key 时
75
+ `vod_submit_voices` 直接结构化拒绝,**不代签匿名令牌**(匿名令牌按设备锚点签发,
76
+ 一进程一锚点会把配额、声量、归因搅在一起)。
77
+ - **工具面收窄**:草稿/本地账本类工具(`vod_draft_voices` / `vod_commit_voices` /
78
+ `vod_list_submitted`)不在远程面提供——它们写"本机状态",而一个共享进程没有
79
+ "本机"。
80
+ - **插件不写库**:远程面能做的仍然只是调用引擎 HTTP API;落库、配额、审计都在
81
+ 服务端。插件不持有数据库连接,也没有任何 DB 代码路径。
82
+ - **无内建鉴权**:本进程不校验身份,默认只绑回环。要对外必须在反代上加 TLS 与
83
+ 身份校验——不要把它匿名暴露到公网。
84
+
85
+ ## 工具面(契约唯一事实源:contract/tools.schema.json)
59
86
 
60
- | vod_submit_voices | 写 | confirm 逐次同意 + 单批≤50 + source 取握手宿主身份;走 Java /external/voices |
61
- | vod_devkit_info | 只读常驻 | 返回版本/commitSHA/宿主 clientInfo |
62
- | vod_auth_status | 只读常驻 | key 指纹化自检+三步引导(无 key 可跑) |
63
- | vod_list_submitted | 只读 | 本机提交账本(cap 200)——agent 替用户对账进度 |
87
+ | 工具 | pack | 类型 | 护栏 |
88
+ |---|---|---|---|
89
+ | vod_submit_voices | collect | 写 | confirm 逐次同意 + 单批≤50 + source 取握手宿主身份;走 Java /external/voices |
90
+ | vod_draft_voices | collect | 写(暂存) | 本机暂存 cap10/TTL600s,逐字回显 contents;不触上游 |
91
+ | vod_commit_voices | collect | 写 | 一次性令牌 + payloadSha256 防调包,内部复用提交链 |
92
+ | vod_list_submitted | collect | 只读 | 本机提交账本(cap 200)——agent 替用户对账进度 |
93
+ | vod_devkit_info | core | 只读 | 返回版本/commitSHA/宿主 clientInfo |
94
+ | vod_auth_status | core | 只读 | key 指纹化自检+三步引导(无 key 可跑) |
95
+ | vod_check_update | core | 只读 | npm registry latest(24h 缓存/失败静默);只提醒不自升级 |
96
+ | vod_list_skills / vod_retrieve_skill | knowledge | 只读 | 领域规则技能的披露面(pack 裁剪即拒绝并给恢复命令) |
64
97
 
65
98
  安全:deny 拦 DB 直连意图与凭据读取(safety/policy.json 声明式规则;
66
99
  文本规则只扫结构性字段,不误杀反馈内容里的凭据引用)。
67
100
 
68
- 测试:39 用例(单元+护栏+packs+安装器矩阵三宿主+真进程 stdio 回环+**协议级真 HTTP 服务器**
69
- 锁定认证头/双后端路径——E1/E2 的永久回归门)。决策闭环见 docs/decisions.md。
101
+ 测试:pytest + node:test 全量(单元+护栏+packs+安装器矩阵四宿主+真进程 stdio 回环+
102
+ **协议级真 HTTP 服务器**锁定认证头/双后端路径——E1/E2 的永久回归门)。
103
+ 用例数以本地实测为准(`python3 -m pytest tests/ -q`),文档不手写计数——
104
+ 手写计数必然漂移,tests/test_claims.py 会拦。决策闭环见 docs/decisions.md。
70
105
 
71
106
  ## 质量门禁
72
107
 
package/bin/vod-devkit CHANGED
@@ -16,8 +16,14 @@ from pathlib import Path
16
16
 
17
17
  ROOT = Path(__file__).resolve().parent.parent
18
18
  sys.path.insert(0, str(ROOT))
19
- HERMES_MCP_DIR = Path.home() / ".hermes" / "mcp" # 约定:写入前打印供确认
20
- HERMES_SKILLS_DIR = Path.home() / ".hermes" / "skills" / "devops" / "vod-devkit"
19
+
20
+ from vod_mcp import hosts as host_specs # noqa: E402 宿主适配层(数据驱动)
21
+
22
+ # 路径常量一律来自 integrations/<host>/host.json(单一来源):新增宿主=加
23
+ # 目录,不改这里;平台差异也在数据里(opencode 的 windows 分叉)。
24
+ _HERMES_SPEC = host_specs.load("hermes")
25
+ HERMES_MCP_DIR = Path(_HERMES_SPEC["configPath"]).parent # 约定:写入前打印供确认
26
+ HERMES_SKILLS_DIR = Path(_HERMES_SPEC["skillsDir"])
21
27
 
22
28
 
23
29
  def git_sha(strict: bool) -> str | None:
@@ -87,7 +93,7 @@ def _server_env(args, packs: str) -> dict:
87
93
  return env
88
94
 
89
95
 
90
- def _skill_installs(manifest_path: Path, oc_skills, cx_skills) -> list:
96
+ def _skill_installs(manifest_path: Path, extra_dirs) -> list:
91
97
  """多宿主技能落点并集(名册对账):manifest 按「最近一次安装」覆盖会
92
98
  互相冲掉落点(实锤:codex 装完 opencode 落点消失),按 host+dir
93
99
  去重保留历史落点。"""
@@ -105,8 +111,7 @@ def _skill_installs(manifest_path: Path, oc_skills, cx_skills) -> list:
105
111
  prev[(si["host"], d)] = si
106
112
  except Exception:
107
113
  pass
108
- for h, d in (("hermes", HERMES_SKILLS_DIR),
109
- ("opencode", oc_skills), ("codex", cx_skills)):
114
+ for h, d in [("hermes", HERMES_SKILLS_DIR)] + list(extra_dirs or []):
110
115
  if d is not None:
111
116
  prev[(h, str(d))] = {"host": h, "dir": str(d)}
112
117
  return sorted(prev.values(), key=lambda x: (x["host"], x["dir"]))
@@ -193,10 +198,8 @@ def _install_opencode(args, packs: str) -> Path:
193
198
  schema 实测要求:command=数组、enabled 必填;既有内容(provider 等)
194
199
  原样保留(读改写,只动 mcp.vod-devkit 键)。
195
200
  """
196
- import platform
197
- base = Path.home() / (".config/opencode" if platform.system() != "Windows"
198
- else "AppData/Local/opencode")
199
- conf = base / "opencode.json"
201
+ spec = host_specs.load("opencode")
202
+ conf = Path(spec["configPath"])
200
203
  conf.parent.mkdir(parents=True, exist_ok=True)
201
204
  cfg = {}
202
205
  if conf.exists():
@@ -212,43 +215,35 @@ def _install_opencode(args, packs: str) -> Path:
212
215
  }
213
216
  conf.write_text(json.dumps(cfg, ensure_ascii=False, indent=2), encoding="utf-8")
214
217
  print(f"已写入 OpenCode 配置:{conf}(重启 OpenCode 会话生效)")
215
- cmd_dir = base / "command"
216
- cmd_dir.mkdir(parents=True, exist_ok=True)
217
- (cmd_dir / "vod-doctor.md").write_text(
218
- "---\n"
219
- "description: 自检 VOD DevKit 就绪状态(MCP 连通/版本/key/账本)。\n"
220
- "---\n\n"
221
- "使用 vod-devkit 工具做就绪自检,按序执行并汇总 OK/缺失:\n"
222
- "1. 调用 vod_devkit_info:确认 version 与 commitSha 非空(版本/来源溯源)。\n"
223
- "2. 调用 vod_auth_status:报告 key 配置态与引擎连通性;无 key 属正常(首次提交自动取匿名令牌)。\n"
224
- "3. 调用 vod_list_submitted(limit 5):报告本机已提交反馈数(本地账本口径)。\n"
225
- "4. 汇总:installed(OK)vs 缺失(需处理项)。不要打印任何 key/令牌明文。\n"
226
- "若 MCP 工具不可用(刚装完未重启),提示用户重启 OpenCode 会话。\n",
227
- encoding="utf-8")
228
- print(f"已写入 OpenCode 自检命令:/vod-doctor({cmd_dir / 'vod-doctor.md'})")
218
+ # 随装生成物走 integrations/opencode/ 的模板(单一来源——此前模板正文
219
+ # 硬编码在本函数里,改文案要同时改代码与文档两处)
220
+ for g in spec["generated"]:
221
+ dest = Path(g["dest"])
222
+ dest.parent.mkdir(parents=True, exist_ok=True)
223
+ dest.write_text(Path(g["template"]).read_text(encoding="utf-8"),
224
+ encoding="utf-8")
225
+ print(f"已写入 OpenCode 自检命令:/vod-doctor({dest})")
229
226
  return conf
230
227
 
231
228
 
232
229
  def _strip_codex_vod_blocks(text: str) -> str:
233
- """幂等剥离:按行删除 [mcp_servers.vod-devkit] 及 .env 子表整块。
230
+ """幂等剥离:删除 [mcp_servers.vod-devkit] **及其全部子表**。
234
231
 
235
- 不能用行内正则截断式剥离——args = ["…"] 行内的 '[' 会让正则提前断块,
236
- 旧 env 子表残留(实测:二次安装后 env 表×2、旧 VOD_PACKS 滞留,
237
- 换 preset 不生效)。按行扫描到下一个 '[' 开头的节头为止才是整块。
232
+ 不能用行内正则截断式剥离——args = ["…"] 行内的 '[' 会让正则提前断块。
233
+ 也不能只删父表(旧实现):留下 [mcp_servers.vod-devkit.env] 在 TOML
234
+ 语义里会重建父表,装出一个没有 command 的假 server。扫描/删除语义
235
+ 统一在 vod_mcp/config_forms.py(单一实现),形态不受支持时抛
236
+ RuntimeError——调用方必须原样放弃修改。
238
237
  """
239
- out, skipping = [], False
240
- for line in text.splitlines():
241
- s = line.strip()
242
- # P2(深审 2026-11-06):精确匹配表头——startswith("…vod-devkit")
243
- # 会误删 [mcp_servers.vod-devkit2] 等无关表
244
- if s == "[mcp_servers.vod-devkit]":
245
- skipping = True
246
- continue
247
- if skipping and s.startswith("["):
248
- skipping = False
249
- if not skipping:
250
- out.append(line)
251
- return "\n".join(out).rstrip()
238
+ from vod_mcp import config_forms as cf
239
+ try:
240
+ verdict, reason = cf.classify_codex_toml(text)
241
+ except cf.Refused as e:
242
+ raise RuntimeError(f"codex config.toml 形态不受支持:{e}") from e
243
+ if verdict == "refuse":
244
+ raise RuntimeError(f"codex config.toml 形态不受支持:{reason}")
245
+ cleaned, _removed = cf.strip_managed_toml(text)
246
+ return cleaned
252
247
 
253
248
 
254
249
  _AGENTS_MARKER_BEGIN = "<!-- vod-devkit:feedback-skill BEGIN -->"
@@ -289,10 +284,17 @@ def _install_codex(args, packs: str) -> Path:
289
284
  if not codex:
290
285
  print("[vod-devkit] 未找到 codex CLI,无法走原生插件安装", file=sys.stderr)
291
286
  sys.exit(2)
292
- conf = Path.home() / ".codex" / "config.toml"
287
+ spec = host_specs.load("codex")
288
+ conf = Path(spec["configPath"])
293
289
  if conf.exists(): # 历史遗留:config.toml MCP 段与插件同名=双注册,移除
294
290
  text = conf.read_text(encoding="utf-8")
295
- cleaned = _strip_codex_vod_blocks(text)
291
+ try:
292
+ cleaned = _strip_codex_vod_blocks(text)
293
+ except RuntimeError as e:
294
+ # 形态守卫:非已知形态宁可不装——改坏用户整份 codex 配置的代价
295
+ # 远高于装不上(字节未动)
296
+ print(f"[vod-devkit] {e}。安装中止,未改动该文件。", file=sys.stderr)
297
+ sys.exit(2)
296
298
  if cleaned != text.rstrip():
297
299
  conf.write_text(cleaned + "\n", encoding="utf-8")
298
300
  print(f"已移除旧 config.toml MCP 段(原生插件取代):{conf}")
@@ -389,7 +391,7 @@ def _install_dsh(args, packs: str) -> Path:
389
391
  sys.exit(1)
390
392
  print(f"已安装 dsh 插件 dsh-vod-devkit(profile={profile},dsh plugin list 可见)")
391
393
 
392
- patch = Path.home() / ".dsh" / "profiles" / profile / "cordis.patch.yml"
394
+ patch = Path(host_specs.load("dsh", profile)["configPath"])
393
395
  # name 行必须保留:cordis.patch.yml 的 insert 块靠 name 绑定 client 半
394
396
  # (反馈按钮)——只写 id+config 会在重装幂等替换时把 name 吞掉,UI 静默
395
397
  # 失激活(2026-11-06 真机实锤:重装后入口消失)
@@ -410,9 +412,11 @@ def _install_dsh(args, packs: str) -> Path:
410
412
  try:
411
413
  written = _upsert_dsh_patch(patch, block)
412
414
  except Exception as e:
413
- # 回滚/修复指引:插件已装但配置未写 = 半成品,给明确的手动修复格式
415
+ # 回滚/修复指引:插件已装但配置未写 = 半成品,给明确的手动修复格式。
416
+ # 区分两类失败:形态守卫拒绝(文件合法但不在已知形态内,字节未动)
417
+ # 与真实 IO 失败——两者的处置动作不同,文案必须能分辨。
414
418
  print(f"[vod-devkit] 插件已装入 profile={profile},但配置写入失败"
415
- f"({e.__class__.__name__})。请手动把下段并入 {patch}"
419
+ f"({e.__class__.__name__}: {e};该文件未被改动)。请手动把下段并入 {patch}"
416
420
  f"(顶层 YAML 数组元素,已有 - id: vod-devkit 段则原位替换):\n"
417
421
  f"{block}", file=sys.stderr)
418
422
  sys.exit(1)
@@ -424,36 +428,30 @@ def _install_dsh(args, packs: str) -> Path:
424
428
 
425
429
 
426
430
  def _find_dsh_block(lines):
427
- """定位 cordis.patch.yml 中 vod-devkit 块的 (start, end);不存在返回
428
- (None, None)。块边界=下一顶层元素行(`- ` 开头)或 EOF。
429
- 嵌套铁律(真机实锤,2026-11-10 复现):dsh 只认缩进在 `- insert:` 下
430
- 的块——平铺 `- id:` 会被组合层丢弃=插件整个掉出组合树(banner/工具/
431
- UI 全消失)。当命中行是嵌套形态(带缩进)时,start 向上归并到其
432
- `- insert:` 组头,整组替换;平铺旧形态(历史安装器写的)按原语义
433
- 顶格替换。install 的幂等 upsert 与 uninstall 的摘除共用本边界语义
434
- (单一实现,防两处扫描规则漂移——双载体漂移已在本仓 dsh/UI 壳实锤过)。"""
435
- for i, ln in enumerate(lines):
436
- if ln.strip().startswith("- id: vod-devkit"):
437
- start = i
438
- if ln[:1] == " ": # 嵌套形态:向上归并组头(- insert: 或其它顶层 -)
439
- for k in range(i - 1, -1, -1):
440
- if lines[k].startswith("- "):
441
- start = k
442
- break
443
- end = len(lines)
444
- for j in range(start + 1, len(lines)):
445
- if lines[j].startswith("- "): # 下一顶层元素:本块结束
446
- end = j
447
- break
448
- return start, end
449
- return None, None
431
+ """定位 cordis.patch.yml 中 vod-devkit 块的 (start, end)。
432
+
433
+ 扫描/边界语义统一在 vod_mcp/config_forms.find_dsh_block(单一实现,
434
+ install 的幂等 upsert、uninstall 摘除、doctor 自愈三处共用——两处扫描
435
+ 规则漂移在本仓 dsh 壳上实锤过)。本函数只保留名字兼容调用点。
436
+ """
437
+ from vod_mcp import config_forms as cf
438
+ return cf.find_dsh_block(lines)
450
439
 
451
440
 
452
441
  def _upsert_dsh_patch(patch: Path, block: str) -> bool:
453
442
  """幂等写 profile cordis.patch.yml:已存在 `- id: vod-devkit` 段则原位整块
454
443
  替换(不重复插入);无则追加。按行扫描块边界(下一行 `- ` 顶层元素或 EOF),
455
444
  不引 YAML 依赖(本仓零第三方依赖红线)。返回是否有写入。"""
445
+ from vod_mcp import config_forms as cf
456
446
  lines = patch.read_text(encoding="utf-8").splitlines() if patch.exists() else []
447
+ # 形态守卫(先分类后改字节):非已知形态一律拒绝——这个文件坏掉等于
448
+ # 整个 dsh profile 起不来(`[]` 占位实锤),比装不上代价高得多
449
+ try:
450
+ verdict, reason = cf.classify_dsh_patch(lines)
451
+ except cf.Refused as e:
452
+ raise RuntimeError(f"cordis.patch.yml 形态不受支持:{e}") from e
453
+ if verdict == "refuse":
454
+ raise RuntimeError(f"cordis.patch.yml 形态不受支持:{reason}")
457
455
  start, end = _find_dsh_block(lines)
458
456
  if start is None:
459
457
  # 空数组占位清除(四宿主实测实锤:dsh plugin add 自建的模板含字面量
@@ -487,7 +485,17 @@ def _remove_dsh_patch_block(patch: Path) -> bool:
487
485
  """从 cordis.patch.yml 摘除 vod-devkit 块(uninstall 用)。返回是否摘除。"""
488
486
  if not patch.exists():
489
487
  return False
488
+ from vod_mcp import config_forms as cf
490
489
  lines = patch.read_text(encoding="utf-8").splitlines()
490
+ try:
491
+ verdict, reason = cf.classify_dsh_patch(lines)
492
+ except cf.Refused as e:
493
+ verdict, reason = "refuse", str(e)
494
+ if verdict == "refuse":
495
+ # 卸载路径同样不动字节:文件已经坏了,再"尽力删"只会让故障更难定位
496
+ print(f"[vod-devkit] skip(cordis.patch.yml 形态不受支持,未改动):{reason}",
497
+ file=sys.stderr)
498
+ return False
491
499
  start, end = _find_dsh_block(lines)
492
500
  if start is None:
493
501
  return False
@@ -502,16 +510,14 @@ _INSTALLERS = {"hermes": _install_hermes, "opencode": _install_opencode,
502
510
 
503
511
 
504
512
  def detect_targets() -> list:
505
- """0/1/N 探测:按各家配置目录存在性判断已装宿主。"""
513
+ """0/1/N 探测:按 host.json 的 detect 段判断宿主是否在场(CLI 或配置目录)。"""
506
514
  found = []
507
- if shutil.which("hermes"):
508
- found.append("hermes")
509
- if (Path.home() / ".config/opencode").exists():
510
- found.append("opencode")
511
- if (Path.home() / ".codex").exists():
512
- found.append("codex")
513
- if shutil.which("dsh"):
514
- found.append("dsh")
515
+ for host in host_specs.hosts():
516
+ spec = host_specs.load(host)
517
+ if spec.get("detectCLI") and shutil.which(spec["detectCLI"]):
518
+ found.append(host)
519
+ elif spec.get("detectPath") and Path(spec["detectPath"]).exists():
520
+ found.append(host)
515
521
  return found
516
522
 
517
523
 
@@ -694,33 +700,32 @@ def cmd_install(args):
694
700
  print(f"[vod-devkit] 已显式解除 codex 采集熔断(安装成功),审计已记录:{audit}")
695
701
 
696
702
  # G1 修复:技能全量拷贝(目录型技能+平铺规则文档),按 packs 过滤
697
- oc_skills, cx_skills = _install_skills(target, packs)
703
+ extra_dirs = _install_skills(target, packs,
704
+ (getattr(args, "dsh_profile", "") or "").strip() or None)
698
705
 
699
706
  _write_install_manifest(args, target, packs, bound_product, mcp_conf,
700
- oc_skills, cx_skills)
707
+ extra_dirs)
708
+
701
709
 
710
+ def _install_skills(target: str, packs: str, profile: str | None = None):
711
+ """技能段:按 packs 过滤后拷到 hermes 主目录 + 目标宿主的技能发现目录。
702
712
 
703
- def _install_skills(target: str, packs: str):
704
- """技能段:全量拷贝(目录型技能+平铺规则文档),按 packs 过滤,落
705
- hermes 主目录 + opencode/codex 原生目录。返回 (oc_skills, cx_skills)
706
- 落点(供 manifest 名册对账)。"""
713
+ 目标宿主列表由 integrations/<host>/host.json 的 skillsDir 决定——2026-11-11
714
+ 实锤:dsh 此前不在拷贝分支里,npx 装 dsh 只拿到工具、拿不到任何技能文
715
+ 件(同意前置/逐字回显/追问判定这些话术纪律整层缺失),而 ~/.dsh/skills
716
+ 下的副本是 /opt/vod-install 脚本手工刷的,不是安装器产物。
717
+ 返回 [(host, Path)] 落点清单(供 manifest 名册对账)。"""
707
718
  HERMES_SKILLS_DIR.mkdir(parents=True, exist_ok=True)
708
719
  # opencode 原生技能目录(2026-11-06 实测:opencode 自动发现
709
720
  # ~/.config/opencode/skills/ 并经 skill 工具按需加载——此前安装器漏拷,
710
721
  # opencode 只有工具描述一条约束通道,话术类约束全部失效)
711
- oc_skills = None
712
- cx_skills = None
713
- if target == "opencode":
714
- import platform as _pf
715
- oc_base = Path.home() / (".config/opencode" if _pf.system() != "Windows"
716
- else "AppData/Local/opencode")
717
- oc_skills = oc_base / "skills"
718
- oc_skills.mkdir(parents=True, exist_ok=True)
719
- elif target == "codex":
720
- cx_skills = Path.home() / ".codex" / "skills"
721
- cx_skills.mkdir(parents=True, exist_ok=True)
722
+ extra_dirs = [] # [(host, Path)]
723
+ spec = host_specs.load(target, profile)
724
+ if spec.get("skillsDir") and target != "hermes":
725
+ dst = Path(spec["skillsDir"])
726
+ dst.mkdir(parents=True, exist_ok=True)
727
+ extra_dirs.append((target, dst))
722
728
  pack_set = set(p for p in packs.split(",") if p)
723
- extra_skill_dirs = [d for d in (oc_skills, cx_skills) if d is not None]
724
729
  for entry in sorted((ROOT / "skills").iterdir()):
725
730
  if entry.is_dir(): # vod-core / vod-feedback-collect
726
731
  skill = entry.name
@@ -732,17 +737,17 @@ def _install_skills(target: str, packs: str):
732
737
  if dst.exists():
733
738
  shutil.rmtree(dst)
734
739
  shutil.copytree(entry, dst)
735
- for oc_dst in extra_skill_dirs:
740
+ for _host, oc_dst in extra_dirs:
736
741
  dst2 = oc_dst / skill
737
742
  if dst2.exists():
738
743
  shutil.rmtree(dst2)
739
744
  shutil.copytree(entry, dst2)
740
745
  # vendored 领域规则已由 vendor_rules.py 落成技能目录结构
741
- return oc_skills, cx_skills
746
+ return extra_dirs
742
747
 
743
748
 
744
749
  def _write_install_manifest(args, target, packs, bound_product, mcp_conf,
745
- oc_skills, cx_skills) -> None:
750
+ extra_dirs) -> None:
746
751
  """manifest 段:落安装名册(版本/来源/归因/落点指纹),并给出 key
747
752
  配置提示。名册对账口径见各字段注释(原 cmd_install 尾段,整段平移)。"""
748
753
  bi = json.loads((ROOT / "build-info.json").read_text(encoding="utf-8"))
@@ -769,7 +774,7 @@ def _write_install_manifest(args, target, packs, bound_product, mcp_conf,
769
774
  # 不再只盯 hermes 单目录(opencode 漏拷静默失效的针对性防线)。
770
775
  # 多宿主并集合并:manifest 按「最近一次安装」覆盖会互相冲掉落点
771
776
  # (实锤:codex 装完 opencode 落点消失),按 host+dir 去重保留历史
772
- "skillInstalls": _skill_installs(manifest_path(), oc_skills, cx_skills),
777
+ "skillInstalls": _skill_installs(manifest_path(), extra_dirs),
773
778
  "skillHashes": _skill_hashes(),
774
779
  }
775
780
  manifest_path().write_text(json.dumps(manifest, ensure_ascii=False, indent=2),
@@ -813,10 +818,20 @@ def _repair_dsh_patch_block(mf: dict) -> str | None:
813
818
  dsh 的配置序列化只保留它能识别的块,手工游离块会被下次写盘冲掉。
814
819
  """
815
820
  prof = mf["dshProfile"]
816
- patch = Path.home() / ".dsh" / "profiles" / prof / "cordis.patch.yml"
821
+ patch = Path(host_specs.load("dsh", prof)["configPath"])
817
822
  if not patch.exists():
818
823
  return None
824
+ from vod_mcp import config_forms as cf
819
825
  lines = patch.read_text(encoding="utf-8").splitlines()
826
+ try:
827
+ verdict, reason = cf.classify_dsh_patch(lines)
828
+ except cf.Refused as e:
829
+ verdict, reason = "refuse", str(e)
830
+ if verdict == "refuse":
831
+ # 自愈也不越界:文件形态未知时只报告,不动字节
832
+ print(f"[doctor] skip(cordis.patch.yml 形态不受支持,未自愈):{reason}",
833
+ file=sys.stderr)
834
+ return None
820
835
  vod_idx = next((i for i, ln in enumerate(lines)
821
836
  if ln.strip().startswith("- id: vod-devkit")), None)
822
837
  if vod_idx is not None and lines[vod_idx].startswith((" ", "\t")):
@@ -1011,10 +1026,11 @@ def cmd_uninstall(_args):
1011
1026
  print("codex plugin remove:",
1012
1027
  "OK" if r.returncode == 0
1013
1028
  else (r.stderr or r.stdout).strip()[-120:])
1014
- oc_cmd = Path.home() / ".config/opencode/command/vod-doctor.md"
1015
- if oc_cmd.exists():
1016
- oc_cmd.unlink()
1017
- print("removed:", oc_cmd)
1029
+ for g in host_specs.load("opencode")["generated"]:
1030
+ gen = Path(g["dest"])
1031
+ if gen.exists():
1032
+ gen.unlink()
1033
+ print("removed:", gen)
1018
1034
  # dsh 壳(D-dsh-install-1):摘插件 + 从 profile patch 移除 config 段
1019
1035
  dsh = shutil.which("dsh")
1020
1036
  if dsh:
@@ -1022,9 +1038,10 @@ def cmd_uninstall(_args):
1022
1038
  if prof:
1023
1039
  subprocess.run([dsh, "plugin", "--profile", prof, "remove",
1024
1040
  "dsh-vod-devkit"], capture_output=True, text=True)
1025
- patch = Path.home() / ".dsh" / "profiles" / prof / "cordis.patch.yml"
1026
- if _remove_dsh_patch_block(patch):
1027
- print("removed vod-devkit config block:", patch)
1041
+ if prof: # 无 profile 记录=没写过 patch,无需(也无法)摘除
1042
+ patch = Path(host_specs.load("dsh", prof)["configPath"])
1043
+ if _remove_dsh_patch_block(patch):
1044
+ print("removed vod-devkit config block:", patch)
1028
1045
  p.unlink()
1029
1046
  print("removed:", p)
1030
1047
  else:
@@ -1032,6 +1049,11 @@ def cmd_uninstall(_args):
1032
1049
 
1033
1050
 
1034
1051
  def main():
1052
+ # `serve` 后的参数整体透传给 MCP server(argparse 的 REMAINDER 会把
1053
+ # --transport 当成未知参数拦下,devkit 的二进制本身就是 server,同形处理)
1054
+ if len(sys.argv) > 1 and sys.argv[1] == "serve":
1055
+ os.execv(sys.executable,
1056
+ [sys.executable, str(ROOT / "vod_mcp" / "server.py"), *sys.argv[2:]])
1035
1057
  ap = argparse.ArgumentParser(prog="vod-devkit")
1036
1058
  sub = ap.add_subparsers(dest="cmd", required=True)
1037
1059
  sp = sub.add_parser("install")
@@ -1062,10 +1084,20 @@ def main():
1062
1084
  s.set_defaults(fn=fn)
1063
1085
  sub.add_parser("build-info").set_defaults(fn=lambda a: write_build_info(strict=False))
1064
1086
 
1065
- def _serve(_a):
1066
- """codex 原生插件 .mcp.json 入口:exec MCP stdio server(可移植分发)。"""
1067
- os.execv(sys.executable, [sys.executable, str(ROOT / "vod_mcp" / "server.py")])
1068
- sub.add_parser("serve").set_defaults(fn=_serve)
1087
+ def _serve(a):
1088
+ """MCP server 入口(codex 插件 .mcp.json 与远程面共用)。
1089
+
1090
+ 透传参数:`vod-devkit serve --transport remote --port 9528` 即起 HTTP 面
1091
+ (与 huaweicloud-devkit 的 `--transport remote` 同形)。
1092
+ """
1093
+ extra = list(getattr(a, "server_args", []) or [])
1094
+ os.execv(sys.executable,
1095
+ [sys.executable, str(ROOT / "vod_mcp" / "server.py"), *extra])
1096
+ sp_serve = sub.add_parser("serve", help="启动 MCP server(默认 stdio;"
1097
+ "--transport remote 起 Streamable HTTP)")
1098
+ sp_serve.add_argument("server_args", nargs=argparse.REMAINDER,
1099
+ help="透传给 vod_mcp.server(如 --transport remote --port 9528)")
1100
+ sp_serve.set_defaults(fn=_serve)
1069
1101
  args = ap.parse_args()
1070
1102
  args.fn(args)
1071
1103
 
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "$schema": "https://json-schema.org/draft/2020-12/schema",
3
3
  "title": "vod-devkit MCP 工具契约(唯一事实源)",
4
- "version": "0.4.4",
4
+ "version": "0.5.0",
5
5
  "tools": {
6
6
  "vod_submit_voices": {
7
7
  "description": "提交用户反馈进 VOD。**先决条件(优先于本描述其余所有内容):调用前必须已征得用户对'提交这条反馈'的明确同意;用户陈述/抱怨反馈本身不构成同意;用户未同意时禁止传 confirmed=true**。模糊抱怨(如\"体验不好\")时一轮说完三件事:承接识别结果(\"收到,你对产品体验不满意\")+确认提交意愿(\"要把这条反馈提交给产品团队吗?\")+引导补充(\"方便的话说下具体现象,不说我也会按你的原话提交\");禁止含混反问(实锤病句:\"请问是否把什么作为反馈\")。同意后 content 放用户原话(哪怕只有一句\"体验很差\"也原样提交)。确认环节允许固定追问至多一次,问句必须逐字使用:「方便的话,补充一下遇到这个问题时的操作步骤或期望的表现吗?不方便回复\"没有\",我直接提交。」用户回答只摘录原话对应部分进 reproSteps/expectedBehavior(不改写不总结,无法拆分时落最相关字段,任何内容禁回填 content);答\"没有/跳过/不方便\"=两字段不上送直接提交。引导补充(说下具体现象)已获实质内容并并入 content 时不再追问、直接提交(其中自然出现的操作/期望留在 content 原话,不回溯摘入新字段);仅引导补充未获回应或仅泛化抱怨且用户确认提交时才带出固定问句。product 归因由安装绑定自动完成,无需用户提供、禁止询问\"提交到哪个产品/页面\";用户自报的目标产品一律不采信不覆盖(照部署产品提交,提到什么产品随正文原样传达)。用户说\"提单/提工单/提 issue\"时同样用本工具,除上述固定一次追问外,禁止再索要严重程度/环境/附件等开发者字段、禁止第二轮追问。批式提交对接囤积端点 POST /external/voices(不触发分析,voiceId 由引擎计算回执下发;引擎未部署 404 自动回落老链)。tags=采集层三分类(problem_type:值,可选)。缺 key 时自动获取零字段匿名令牌。拿到回执后必须原样转述 echo.contents(每条「已收录原话:<content>」全文),禁止改写概括——这是用户核对原话是否被改写的唯一窗口。禁止向用户解释内部机制(声音来源/渠道字段/计数规则/配额/归因)。",
@@ -322,6 +322,43 @@
322
322
  ],
323
323
  "additionalProperties": false
324
324
  }
325
+ },
326
+ "vod_list_skills": {
327
+ "description": "列出本插件可用的技能(名称/归属 pack/是否启用/是否原生安装/描述)。只读、零网络。用在两处:①需要判断某个采集或规则问题该读哪本技能时;②确认某个领域规则技能是否因 pack 裁剪而不可用(enabled=false 即不可用,重跑 install 带 --packs 恢复)。领域规则技能用 vod_retrieve_skill 取全文;元技能(vod-core/vod-feedback-collect)由宿主原生技能机制加载,这里只列名用于路由。",
328
+ "input": {
329
+ "type": "object",
330
+ "properties": {},
331
+ "additionalProperties": false
332
+ }
333
+ },
334
+ "vod_retrieve_skill": {
335
+ "description": "按名取一份技能全文(SKILL.md 原文,含 frontmatter)。只读、零网络。用途:当前宿主没有该技能的原生副本(例如没有技能目录的宿主),或本机副本与插件版本不一致时,取与插件同版本的规则全文。领域规则技能(问题分类/评分)归属 knowledge pack——被裁剪时本工具返回错误并给出恢复命令,不会静默返回空。先用 vod_list_skills 查名字;不认识的技能名会连可用清单一起返回。返回里 note 非空时表示内容含内部表名/连接串字样,向用户复述时不要照抄。",
336
+ "input": {
337
+ "type": "object",
338
+ "properties": {
339
+ "name": {
340
+ "type": "string",
341
+ "description": "技能名(来自 vod_list_skills,例如 vod-problem-classification-rules)"
342
+ }
343
+ },
344
+ "required": [
345
+ "name"
346
+ ],
347
+ "additionalProperties": false
348
+ }
349
+ },
350
+ "vod_check_update": {
351
+ "description": "检查本机插件版本是否落后(npm registry latest,24 小时缓存,失败静默)。只读、只在用户问到版本/升级或会话首次自检时调用,不要每轮调用。返回 currentVersion/latestVersion/updateAvailable;有新版时给 upgradeCommand(重跑 install 或 vod-devkit update,本工具从不自升级)。用户不想被提醒时传 dismiss=true,跳过 3 天。preset(产品分发)形态不发外呼,直接告知版本随 agent 发版管理。",
352
+ "input": {
353
+ "type": "object",
354
+ "properties": {
355
+ "dismiss": {
356
+ "type": "boolean",
357
+ "description": "用户明确表示不想再被提醒时传 true(3 天冷却)"
358
+ }
359
+ },
360
+ "additionalProperties": false
361
+ }
325
362
  }
326
363
  },
327
364
  "backends": {
@@ -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
+ }