vod-devkit 0.5.5 → 0.5.9

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 (98) hide show
  1. package/CHANGELOG.md +40 -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 -1164
  6. package/contract/tools.schema.json +1 -1
  7. package/package.json +11 -2
  8. package/plugins/vod-devkit/.codex-plugin/plugin.json +1 -1
  9. package/plugins/vod-devkit/build-info.json +3 -3
  10. package/plugins/vod-devkit/contract/tools.schema.json +446 -0
  11. package/plugins/vod-devkit/safety/policy.json +48 -0
  12. package/plugins/vod-devkit/vod_mcp/__init__.py +1 -1
  13. package/plugins/vod-devkit/vod_mcp/host_adapters/base.py +3 -1
  14. package/plugins/vod-devkit/vod_mcp/host_adapters/codex.py +14 -0
  15. package/plugins/vod-devkit/vod_mcp/host_adapters/hermes.py +88 -11
  16. package/plugins/vod-devkit/vod_mcp/hosts.py +3 -1
  17. package/plugins/vod-devkit/vod_mcp/net.py +251 -0
  18. package/plugins/vod-devkit/vod_mcp/packs/collect.py +684 -0
  19. package/plugins/vod-devkit/vod_mcp/packs/core.py +80 -0
  20. package/plugins/vod-devkit/vod_mcp/packs/knowledge.py +17 -0
  21. package/plugins/vod-devkit/vod_mcp/paths.py +38 -0
  22. package/plugins/vod-devkit/vod_mcp/payload.py +3 -1
  23. package/plugins/vod-devkit/vod_mcp/policy.py +3 -2
  24. package/plugins/vod-devkit/vod_mcp/provenance.py +3 -2
  25. package/plugins/vod-devkit/vod_mcp/runtime_state.py +324 -0
  26. package/plugins/vod-devkit/vod_mcp/server.py +10 -7
  27. package/plugins/vod-devkit/vod_mcp/skills_registry.py +5 -4
  28. package/plugins/vod-devkit/vod_mcp/tools.py +23 -1298
  29. package/plugins/vod-devkit/vod_mcp/transport_remote.py +21 -9
  30. package/plugins/vod-devkit/vod_mcp/update_check.py +1 -1
  31. package/vod_mcp/__init__.py +1 -1
  32. package/vod_mcp/host_adapters/__pycache__/__init__.cpython-39.pyc +0 -0
  33. package/vod_mcp/host_adapters/__pycache__/atomcode.cpython-39.pyc +0 -0
  34. package/vod_mcp/host_adapters/__pycache__/base.cpython-314.pyc +0 -0
  35. package/vod_mcp/host_adapters/__pycache__/base.cpython-39.pyc +0 -0
  36. package/vod_mcp/host_adapters/__pycache__/codearts.cpython-39.pyc +0 -0
  37. package/vod_mcp/host_adapters/__pycache__/codeartswork.cpython-39.pyc +0 -0
  38. package/vod_mcp/host_adapters/__pycache__/codex.cpython-314.pyc +0 -0
  39. package/vod_mcp/host_adapters/__pycache__/codex.cpython-39.pyc +0 -0
  40. package/vod_mcp/host_adapters/__pycache__/codex_desktop.cpython-39.pyc +0 -0
  41. package/vod_mcp/host_adapters/__pycache__/dsh.cpython-39.pyc +0 -0
  42. package/vod_mcp/host_adapters/__pycache__/generic.cpython-39.pyc +0 -0
  43. package/vod_mcp/host_adapters/__pycache__/hermes.cpython-314.pyc +0 -0
  44. package/vod_mcp/host_adapters/__pycache__/hermes.cpython-39.pyc +0 -0
  45. package/vod_mcp/host_adapters/__pycache__/opencode.cpython-39.pyc +0 -0
  46. package/vod_mcp/host_adapters/__pycache__/workbuddy.cpython-39.pyc +0 -0
  47. package/vod_mcp/host_adapters/base.py +3 -1
  48. package/vod_mcp/host_adapters/codex.py +14 -0
  49. package/vod_mcp/host_adapters/hermes.py +88 -11
  50. package/vod_mcp/hosts.py +3 -1
  51. package/vod_mcp/net.py +251 -0
  52. package/vod_mcp/packs/__pycache__/__init__.cpython-314.pyc +0 -0
  53. package/vod_mcp/packs/__pycache__/__init__.cpython-39.pyc +0 -0
  54. package/vod_mcp/packs/__pycache__/collect.cpython-314.pyc +0 -0
  55. package/vod_mcp/packs/__pycache__/collect.cpython-39.pyc +0 -0
  56. package/vod_mcp/packs/__pycache__/core.cpython-314.pyc +0 -0
  57. package/vod_mcp/packs/__pycache__/core.cpython-39.pyc +0 -0
  58. package/vod_mcp/packs/__pycache__/knowledge.cpython-314.pyc +0 -0
  59. package/vod_mcp/packs/__pycache__/knowledge.cpython-39.pyc +0 -0
  60. package/vod_mcp/packs/collect.py +684 -0
  61. package/vod_mcp/packs/core.py +80 -0
  62. package/vod_mcp/packs/knowledge.py +17 -0
  63. package/vod_mcp/paths.py +38 -0
  64. package/vod_mcp/payload.py +3 -1
  65. package/vod_mcp/policy.py +3 -2
  66. package/vod_mcp/provenance.py +3 -2
  67. package/vod_mcp/runtime_state.py +324 -0
  68. package/vod_mcp/server.py +10 -7
  69. package/vod_mcp/skills_registry.py +5 -4
  70. package/vod_mcp/tools.py +23 -1298
  71. package/vod_mcp/transport_remote.py +21 -9
  72. package/vod_mcp/update_check.py +1 -1
  73. package/vodkit_cli/__init__.py +10 -0
  74. package/vodkit_cli/__pycache__/__init__.cpython-314.pyc +0 -0
  75. package/vodkit_cli/__pycache__/__init__.cpython-39.pyc +0 -0
  76. package/vodkit_cli/__pycache__/cli.cpython-314.pyc +0 -0
  77. package/vodkit_cli/__pycache__/cli.cpython-39.pyc +0 -0
  78. package/vodkit_cli/__pycache__/common.cpython-314.pyc +0 -0
  79. package/vodkit_cli/__pycache__/common.cpython-39.pyc +0 -0
  80. package/vodkit_cli/__pycache__/doctor.cpython-314.pyc +0 -0
  81. package/vodkit_cli/__pycache__/doctor.cpython-39.pyc +0 -0
  82. package/vodkit_cli/__pycache__/install.cpython-314.pyc +0 -0
  83. package/vodkit_cli/__pycache__/install.cpython-39.pyc +0 -0
  84. package/vodkit_cli/__pycache__/remote.cpython-314.pyc +0 -0
  85. package/vodkit_cli/__pycache__/remote.cpython-39.pyc +0 -0
  86. package/vodkit_cli/__pycache__/uninstall.cpython-314.pyc +0 -0
  87. package/vodkit_cli/__pycache__/uninstall.cpython-39.pyc +0 -0
  88. package/vodkit_cli/__pycache__/update.cpython-314.pyc +0 -0
  89. package/vodkit_cli/__pycache__/update.cpython-39.pyc +0 -0
  90. package/vodkit_cli/cli.py +86 -0
  91. package/vodkit_cli/common.py +254 -0
  92. package/vodkit_cli/doctor.py +269 -0
  93. package/vodkit_cli/install.py +260 -0
  94. package/vodkit_cli/remote.py +200 -0
  95. package/vodkit_cli/uninstall.py +161 -0
  96. package/vodkit_cli/update.py +45 -0
  97. /package/plugins/vod-devkit/vod_mcp/{packs.py → packs/__init__.py} +0 -0
  98. /package/vod_mcp/{packs.py → packs/__init__.py} +0 -0
package/CHANGELOG.md CHANGED
@@ -333,3 +333,43 @@
333
333
  - 6c2d9a1 fix(宿主): hermes 路径改为调用期解析 + 新增 host_matrix --audit 巡检
334
334
  - 0e688e3 docs(验证): 记真机可达边界 + AtomCode 真机验证结论
335
335
 
336
+
337
+ ## v0.5.6(2026-11-13)
338
+
339
+ - 71cd3c7 chore(sync): plugins 副本同步远程 attach 修复(发版守卫拦出)
340
+ - 665b313 chore(lint): 清 pyflakes 未用 import(release 质量门拦出)
341
+ - 55610b6 docs(手册): README/QUICKINSTALL 对齐 token 探活三态与远程部署形态
342
+ - d85db82 fix(远程attach): B1/B2/B3 三缺陷修复——探活验token、hermes防静默、contextvars身份传播
343
+
344
+
345
+ ## v0.5.7(2026-11-13)
346
+
347
+ - 3c20721 fix(兼容): tools.py f-string 表达式内反斜杠致 Python 3.10/3.11 SyntaxError——join 提至 f-string 外(行为等价),双副本同步;release.sh 质量门新增旧解释器语法扫(B4)
348
+
349
+
350
+ ## v0.5.8(2026-11-15)
351
+
352
+ - 6186b93 merge: P2+P8 并入 main(含拆分正则误伤 origin/main 的修复 + 护栏)
353
+ - 9feafaa fix(cli): 拆分正则误伤 "origin/main" → "origin/cli.main"(update 静默失效)+ 护栏
354
+ - b71033a Merge commit '69a9353' into merge/p2-f8-into-main
355
+ - 6d4f8cf !5 merge fix/ci-gates-v2 into main
356
+ - fd9d963 fix(ci): 三处只在 CI 暴露的红灯(rules_provenance / hermes 无 CLI / host_matrix 探测)
357
+ - 69a9353 !4 merge refactor/f8-bin-split into refactor/p2-pack-split
358
+ - ab6948f refactor(cli)!: bin/vod-devkit 按命令域拆分(F8)+ 两处测试 patch 面跟随实现
359
+ - b15e53d refactor(packs)!: tools.py 按 pack 纵切 + patch 面迁移(P2 结构债收口)
360
+ - 7296c94 !2 merge fix/findings-f1-f7 into main
361
+ - 3d6c4f0 test(gate): 契约→pack 归属的反方向门禁(F4 核查后的真缺口)
362
+ - f78d8e1 fix(dsh)+test(parity): 归因双实现漂移修复 + 运行时路径兜底(F1/F6/F7)
363
+ - 5443342 fix(tools): 运行期状态单点写入 + 锁(F2/F3)+ 清死代码与重复常量(F5/F7)
364
+ - 7db9b2b !1 merge refactor/p1-paths-and-gates into main
365
+ - c5c7732 refactor(paths)!: 根定位单点化 + 插件副本自包含(P1)
366
+ - 6ccf729 test(gates): 门禁先行——插件副本自包含用例(红) + mypy 反转整包 + pre-push 补门
367
+
368
+
369
+ ## v0.5.9(2026-11-15)
370
+
371
+ - 58489fa refactor(copies): 插件副本零提交(生成物)——双漂移从构造上消失
372
+ - 91bc0a2 fix(copies): 双副本漂移根治——同一门禁同时断言内容一致与已提交
373
+ - 592024b fix(ci): 发版状态对账在浅克隆下假红(tag 不可见≠未打 tag)
374
+ - 316a872 fix(release): 发版双副本检查/提交清单补插件副本 contract+safety
375
+
package/QUICKSTART.md CHANGED
@@ -13,33 +13,29 @@
13
13
 
14
14
  ## 前置
15
15
 
16
- - Python 3.10+
17
- - 任意支持 MCP stdio 的宿主(Hermes/OpenCode/Codex/…)
16
+ - Node >= 18(`npx` 引导器;dsh 宿主按其官方要求 Node 24.9+)
17
+ - Python 3.10+(可用 `VOD_PYTHON` 指定解释器)
18
+ - 宿主任选其一:hermes / opencode / codeartsdoer / codeartswork / codex /
19
+ codex-desktop / dsh / workbuddy / atomcode(其它 MCP 客户端走
20
+ `--target generic`)
21
+ - 网络可达 VOD 引擎(缺省 `https://vod-dev.topxtopx.com`)
18
22
 
19
- ## 方式一:Hermes(自动安装)
23
+ ## 方式一:npm(推荐,一条命令)
20
24
 
21
25
  ```bash
22
- git clone <repo-url> vod-devkit && cd vod-devkit
23
- bin/vod-devkit install --target hermes --preset collect --product <你的产品> # --product 可选先验
24
- # 重启 Hermes 会话,工具以 mcp_vod_devkit_* 出现
26
+ npx -y vod-devkit@latest install --target auto --product <你的产品>
27
+ # --target auto 探测已装宿主;显式指定如 --target hermes / opencode / codex
25
28
  ```
26
29
 
27
- ## 方式二:OpenCode / Codex(自动安装,2026-11-03 起支持)
30
+ ## 方式二:从仓库装
28
31
 
29
32
  ```bash
30
- git clone <repo-url> vod-devkit && cd vod-devkit
31
- bin/vod-devkit install --target opencode --product <你的产品> # 或 codex
32
- # install --target auto 会探测已装宿主(0/1/N 三分支)
33
+ git clone https://gitcode.com/xiaowu2119/vod-devkit.git && cd vod-devkit
34
+ bin/vod-devkit install --target hermes --product <你的产品> # 宿主任选
35
+ # 重启宿主会话后工具出现(宿主在启动时读 MCP 配置)
33
36
  ```
34
- > opencode/codex 适配层已过配置写出验证(真实宿主回归待首个用户反馈)。
35
37
 
36
- ## 方式三:npm(npx 一条命令,包已就绪待发布)
37
-
38
- ```bash
39
- npx vod-devkit install --target <hermes|opencode|codex> --product <你的产品>
40
- ```
41
-
42
- ## 方式四:任意 MCP 客户端(手动配置)
38
+ ## 方式三:任意 MCP 客户端(手动配置)
43
39
 
44
40
  把以下片段并入你宿主的 mcpServers 配置:
45
41
 
@@ -51,7 +47,6 @@ npx vod-devkit install --target <hermes|opencode|codex> --product <你的产品>
51
47
  "args": ["/path/to/vod-devkit/vod_mcp/server.py"],
52
48
  "env": {
53
49
  "VOD_JAVA_API_BASE": "https://vod-dev.topxtopx.com",
54
- "VOD_JAVA_API_KEY": "",
55
50
  "VOD_PACKS": "core,collect,knowledge"
56
51
  }
57
52
  }
@@ -59,21 +54,50 @@ npx vod-devkit install --target <hermes|opencode|codex> --product <你的产品>
59
54
  }
60
55
  ```
61
56
 
62
- 配置好后重启会话。
57
+ 配置好后重启会话。装完自检:`npx -y vod-devkit@latest doctor` /
58
+ `status`(针对已装实例,读 install-manifest)。
59
+
60
+ ## 方式四:远程部署(MCP 单独服务多 agent)
61
+
62
+ ```bash
63
+ # 1) 服务端:起远程面(需官方 MCP SDK;对外自建 TLS 反代)
64
+ pip install 'vod-devkit[remote]'
65
+ vod-devkit serve --transport remote --port 9528 --host 127.0.0.1
66
+
67
+ # 2) agent 侧 attach(token 必填——远程面不代签匿名身份)
68
+ npx -y vod-devkit@latest install --target opencode \
69
+ --mcp-url http://<host>:9528/mcp --mcp-token <VOD key> --product <你的产品>
70
+ ```
71
+
72
+ attach 前安装器会**探活**:连接(initialize)、工具面(tools/list 与契约
73
+ 比对)、**key 真伪**(经远程面真调 vod_auth_status,引擎判定)。坏 key 当场
74
+ 拒装零副作用;匿名令牌设备漂移(`device-mismatch`)和引擎不可达会放行——
75
+ 网络问题不是 key 问题。详见 [INSTALL.md](INSTALL.md) 远程部署节。
63
76
 
64
77
  ## 验证
65
78
 
66
- - 会话里让 agent 调用 `vod_auth_status` → key 状态(指纹)+ 三步引导
79
+ - 会话里让 agent 调用 `vod_auth_status` → key 状态(指纹)+ 引导
67
80
  - 提交一条测试反馈:`vod_submit_voices`(voices + confirmed=true)
68
81
 
69
82
  ## 升级正式 key(提交量达匿名上限后)
70
83
 
71
- 联系 VOD 运营 → `bin/vod-devkit install --java-key <KEY>` 重新落位。
84
+ 联系 VOD 运营拿 key → 安装/更新时经 env 提供(安装器写入宿主 MCP 配置):
85
+
86
+ ```bash
87
+ VOD_JAVA_API_KEY=<KEY> npx -y vod-devkit@latest \
88
+ install --target <宿主> --product <你的产品>
89
+ ```
90
+
91
+ 升级后 `vod_auth_status` 的 keyCheck 会显示 `verified`。
72
92
 
73
93
  ## 故障排查
74
94
 
75
95
  | 症状 | 含义 |
76
- |---|---|
96
+ | --- | --- |
77
97
  | `上游不可达` | 引擎/网络未就绪,检查 VOD_JAVA_API_BASE |
78
98
  | `-32012 鉴权失败` | key 无效或被吊销;无 key 会自动取令牌重试 |
99
+ | `token 无效(引擎判定 rejected)` | attach 时坏 key——确认 VOD 平台签发的 key |
100
+ | `设备绑定校验失败` | 匿名令牌跨设备使用——本设备首次提交会自动重领 |
79
101
  | 工具不出现 | 确认 VOD_PACKS 含对应 pack;重启会话 |
102
+
103
+ 更多:[INSTALL.md](INSTALL.md)(每宿主安装细节/故障表/安全边界)。
package/README.en.md CHANGED
@@ -149,8 +149,13 @@ npx -y vod-devkit@latest install --target opencode --mcp-url https://<gateway>/m
149
149
  npx -y vod-devkit@latest install --target codex --mcp-url https://<gateway>/mcp --mcp-token <key>
150
150
  ```
151
151
 
152
- Liveness is probed before any write: `initialize` + `tools/list` must equal the
153
- remote tool set, otherwise the install is refused with zero side effects. The
152
+ Liveness is probed before any write — three steps: `initialize` (connectivity),
153
+ `tools/list` (must equal the remote tool set, otherwise refuse with zero side
154
+ effects), and **key validity** (a real `vod_auth_status` call through the
155
+ remote face; the engine decides: `rejected` = invalid API key → refuse
156
+ install; `device-mismatch` = anonymous token bound to another device (the
157
+ token itself is fine) → allow, re-minted automatically on first submit; engine
158
+ unreachable → allow — a network problem is not a key problem). The
154
159
  remote face withholds machine-local tools (`vod_draft_voices`,
155
160
  `vod_commit_voices`, `vod_list_submitted`) — a shared process has no "local".
156
161
  There is no built-in auth: bind to loopback and front it with TLS + identity.
package/README.md CHANGED
@@ -210,8 +210,12 @@ npx -y vod-devkit@latest install --target opencode --mcp-url https://<网关>/mc
210
210
  npx -y vod-devkit@latest install --target codex --mcp-url https://<网关>/mcp --mcp-token <key>
211
211
  ```
212
212
 
213
- 写入前先探活:`initialize` + `tools/list` 必须等于远程面工具集,不符即拒装且
214
- **不写任何配置**;`doctor` 复查端点与工具面。远程面与 stdio 面的实质差别:
213
+ 写入前先探活(三步):`initialize`(连接)+ `tools/list`(工具面必须等于
214
+ 远程面工具集)+ **key 真伪**(经远程面真调 `vod_auth_status`,引擎三态:
215
+ `rejected` = API Key 无效 → 拒装且**不写任何配置**;`device-mismatch` =
216
+ 匿名令牌设备锚点漂移(token 有效、本机非签发设备)→ 放行,首次提交自动
217
+ 重领;引擎不可达 → 放行,网络问题不是 key 问题)。`doctor` 复查端点与
218
+ 工具面。远程面与 stdio 面的实质差别:
215
219
 
216
220
  - **工具面收窄**:草稿/本机账本类工具(`vod_draft_voices` / `vod_commit_voices` /
217
221
  `vod_list_submitted`)不在远程面——它们写"本机状态",共享进程没有"本机"