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.
- package/CHANGELOG.md +58 -0
- package/QUICKSTART.md +6 -2
- package/README.en.md +23 -2
- package/README.md +204 -16
- package/{contract → assets/contract}/tools.schema.json +127 -1
- package/{skills → assets/skills}/vod-core/SKILL.md +32 -1
- package/bin/vod-devkit +21 -1
- package/integrations/hermes/hooks/vod_guard.py +127 -0
- package/integrations/hermes/hooks/vod_router.py +89 -0
- package/integrations/hermes/host.json +4 -1
- package/npm/cli.js +6 -1
- package/package.json +37 -34
- package/packages/dsh/README.md +60 -0
- package/packages/dsh/package.json +52 -0
- package/plugins/vod-devkit/.codex-plugin/plugin.json +1 -1
- package/plugins/vod-devkit/.mcp.json +2 -0
- package/plugins/vod-devkit/build-info.json +3 -3
- package/plugins/vod-devkit/contract/tools.schema.json +127 -1
- package/plugins/vod-devkit/hooks/vod_guard.py +127 -0
- package/plugins/vod-devkit/hooks/vod_router.py +89 -0
- package/plugins/vod-devkit/skills/vod-core/SKILL.md +32 -1
- package/plugins/vod-devkit/vod_mcp/__init__.py +1 -1
- package/plugins/vod-devkit/vod_mcp/attribution.py +21 -2
- package/plugins/vod-devkit/vod_mcp/config_forms.py +22 -6
- package/plugins/vod-devkit/vod_mcp/diagnose.py +4 -2
- package/plugins/vod-devkit/vod_mcp/host_adapters/base.py +4 -1
- package/plugins/vod-devkit/vod_mcp/host_adapters/codex.py +154 -34
- package/plugins/vod-devkit/vod_mcp/host_adapters/dsh.py +133 -22
- package/plugins/vod-devkit/vod_mcp/host_adapters/hermes.py +216 -59
- package/plugins/vod-devkit/vod_mcp/host_adapters/opencode.py +10 -4
- package/plugins/vod-devkit/vod_mcp/hosts.py +4 -0
- package/plugins/vod-devkit/vod_mcp/net.py +78 -18
- package/plugins/vod-devkit/vod_mcp/packs/__init__.py +97 -22
- package/plugins/vod-devkit/vod_mcp/packs/collect.py +50 -42
- package/plugins/vod-devkit/vod_mcp/packs/core.py +138 -2
- package/plugins/vod-devkit/vod_mcp/paths.py +200 -30
- package/plugins/vod-devkit/vod_mcp/payload.py +10 -5
- package/plugins/vod-devkit/vod_mcp/provenance.py +1 -1
- package/plugins/vod-devkit/vod_mcp/remote_app.py +4 -4
- package/plugins/vod-devkit/vod_mcp/runtime_state.py +151 -28
- package/plugins/vod-devkit/vod_mcp/server.py +52 -7
- package/plugins/vod-devkit/vod_mcp/skills_registry.py +29 -8
- package/plugins/vod-devkit/vod_mcp/tools.py +21 -3
- package/plugins/vod-devkit/vod_mcp/transport_remote.py +22 -3
- package/{vod_mcp → src/vod_mcp}/__init__.py +1 -1
- package/{vod_mcp → src/vod_mcp}/attribution.py +21 -2
- package/{vod_mcp → src/vod_mcp}/config_forms.py +22 -6
- package/{vod_mcp → src/vod_mcp}/diagnose.py +4 -2
- package/{vod_mcp → src/vod_mcp}/host_adapters/base.py +4 -1
- package/{vod_mcp → src/vod_mcp}/host_adapters/codex.py +154 -34
- package/{vod_mcp → src/vod_mcp}/host_adapters/dsh.py +133 -22
- package/src/vod_mcp/host_adapters/hermes.py +361 -0
- package/{vod_mcp → src/vod_mcp}/host_adapters/opencode.py +10 -4
- package/{vod_mcp → src/vod_mcp}/hosts.py +4 -0
- package/{vod_mcp → src/vod_mcp}/net.py +78 -18
- package/src/vod_mcp/packs/__init__.py +142 -0
- package/{vod_mcp → src/vod_mcp}/packs/collect.py +50 -42
- package/src/vod_mcp/packs/core.py +216 -0
- package/src/vod_mcp/paths.py +208 -0
- package/{vod_mcp → src/vod_mcp}/payload.py +10 -5
- package/{vod_mcp → src/vod_mcp}/provenance.py +1 -1
- package/{vod_mcp → src/vod_mcp}/remote_app.py +4 -4
- package/{vod_mcp → src/vod_mcp}/runtime_state.py +151 -28
- package/{vod_mcp → src/vod_mcp}/server.py +52 -7
- package/{vod_mcp → src/vod_mcp}/skills_registry.py +29 -8
- package/{vod_mcp → src/vod_mcp}/tools.py +21 -3
- package/{vod_mcp → src/vod_mcp}/transport_remote.py +22 -3
- package/src/vodkit_cli/auth_cmd.py +81 -0
- package/{vodkit_cli → src/vodkit_cli}/cli.py +38 -8
- package/{vodkit_cli → src/vodkit_cli}/common.py +14 -3
- package/{vodkit_cli → src/vodkit_cli}/doctor.py +147 -9
- package/{vodkit_cli → src/vodkit_cli}/install.py +148 -33
- package/src/vodkit_cli/packs_cmd.py +329 -0
- package/{vodkit_cli → src/vodkit_cli}/remote.py +3 -3
- package/src/vodkit_cli/uninstall.py +315 -0
- package/vod_mcp/host_adapters/__pycache__/__init__.cpython-314.pyc +0 -0
- package/vod_mcp/host_adapters/__pycache__/__init__.cpython-39.pyc +0 -0
- package/vod_mcp/host_adapters/__pycache__/atomcode.cpython-314.pyc +0 -0
- package/vod_mcp/host_adapters/__pycache__/atomcode.cpython-39.pyc +0 -0
- package/vod_mcp/host_adapters/__pycache__/base.cpython-314.pyc +0 -0
- package/vod_mcp/host_adapters/__pycache__/base.cpython-39.pyc +0 -0
- package/vod_mcp/host_adapters/__pycache__/codearts.cpython-314.pyc +0 -0
- package/vod_mcp/host_adapters/__pycache__/codearts.cpython-39.pyc +0 -0
- package/vod_mcp/host_adapters/__pycache__/codeartswork.cpython-314.pyc +0 -0
- package/vod_mcp/host_adapters/__pycache__/codeartswork.cpython-39.pyc +0 -0
- package/vod_mcp/host_adapters/__pycache__/codex.cpython-314.pyc +0 -0
- package/vod_mcp/host_adapters/__pycache__/codex.cpython-39.pyc +0 -0
- package/vod_mcp/host_adapters/__pycache__/codex_desktop.cpython-314.pyc +0 -0
- package/vod_mcp/host_adapters/__pycache__/codex_desktop.cpython-39.pyc +0 -0
- package/vod_mcp/host_adapters/__pycache__/dsh.cpython-314.pyc +0 -0
- package/vod_mcp/host_adapters/__pycache__/dsh.cpython-39.pyc +0 -0
- package/vod_mcp/host_adapters/__pycache__/generic.cpython-314.pyc +0 -0
- package/vod_mcp/host_adapters/__pycache__/generic.cpython-39.pyc +0 -0
- package/vod_mcp/host_adapters/__pycache__/hermes.cpython-314.pyc +0 -0
- package/vod_mcp/host_adapters/__pycache__/hermes.cpython-39.pyc +0 -0
- package/vod_mcp/host_adapters/__pycache__/opencode.cpython-314.pyc +0 -0
- package/vod_mcp/host_adapters/__pycache__/opencode.cpython-39.pyc +0 -0
- package/vod_mcp/host_adapters/__pycache__/workbuddy.cpython-314.pyc +0 -0
- package/vod_mcp/host_adapters/__pycache__/workbuddy.cpython-39.pyc +0 -0
- package/vod_mcp/host_adapters/hermes.py +0 -204
- package/vod_mcp/packs/__init__.py +0 -67
- package/vod_mcp/packs/__pycache__/__init__.cpython-314.pyc +0 -0
- package/vod_mcp/packs/__pycache__/__init__.cpython-39.pyc +0 -0
- package/vod_mcp/packs/__pycache__/collect.cpython-314.pyc +0 -0
- package/vod_mcp/packs/__pycache__/collect.cpython-39.pyc +0 -0
- package/vod_mcp/packs/__pycache__/core.cpython-314.pyc +0 -0
- package/vod_mcp/packs/__pycache__/core.cpython-39.pyc +0 -0
- package/vod_mcp/packs/__pycache__/knowledge.cpython-314.pyc +0 -0
- package/vod_mcp/packs/__pycache__/knowledge.cpython-39.pyc +0 -0
- package/vod_mcp/packs/core.py +0 -80
- package/vod_mcp/paths.py +0 -38
- package/vodkit_cli/__pycache__/__init__.cpython-314.pyc +0 -0
- package/vodkit_cli/__pycache__/__init__.cpython-39.pyc +0 -0
- package/vodkit_cli/__pycache__/cli.cpython-314.pyc +0 -0
- package/vodkit_cli/__pycache__/cli.cpython-39.pyc +0 -0
- package/vodkit_cli/__pycache__/common.cpython-314.pyc +0 -0
- package/vodkit_cli/__pycache__/common.cpython-39.pyc +0 -0
- package/vodkit_cli/__pycache__/doctor.cpython-314.pyc +0 -0
- package/vodkit_cli/__pycache__/doctor.cpython-39.pyc +0 -0
- package/vodkit_cli/__pycache__/install.cpython-314.pyc +0 -0
- package/vodkit_cli/__pycache__/install.cpython-39.pyc +0 -0
- package/vodkit_cli/__pycache__/remote.cpython-314.pyc +0 -0
- package/vodkit_cli/__pycache__/remote.cpython-39.pyc +0 -0
- package/vodkit_cli/__pycache__/uninstall.cpython-314.pyc +0 -0
- package/vodkit_cli/__pycache__/uninstall.cpython-39.pyc +0 -0
- package/vodkit_cli/__pycache__/update.cpython-314.pyc +0 -0
- package/vodkit_cli/__pycache__/update.cpython-39.pyc +0 -0
- package/vodkit_cli/uninstall.py +0 -161
- /package/{safety → assets/safety}/policy.json +0 -0
- /package/{skills → assets/skills}/vod-core/references/acceptance-criteria.md +0 -0
- /package/{skills → assets/skills}/vod-core/references/verification-method.md +0 -0
- /package/{skills → assets/skills}/vod-feedback-collect/SKILL.md +0 -0
- /package/{skills → assets/skills}/vod-feedback-collect/references/acceptance-criteria.md +0 -0
- /package/{skills → assets/skills}/vod-feedback-collect/references/verification-method.md +0 -0
- /package/{skills → assets/skills}/vod-problem-classification-rules/SKILL.md +0 -0
- /package/{skills → assets/skills}/vod-scoring-rules/SKILL.md +0 -0
- /package/{vod_mcp → src/vod_mcp}/detect_framework.py +0 -0
- /package/{vod_mcp → src/vod_mcp}/guardrails.py +0 -0
- /package/{vod_mcp → src/vod_mcp}/host_adapters/__init__.py +0 -0
- /package/{vod_mcp → src/vod_mcp}/host_adapters/atomcode.py +0 -0
- /package/{vod_mcp → src/vod_mcp}/host_adapters/codearts.py +0 -0
- /package/{vod_mcp → src/vod_mcp}/host_adapters/codeartswork.py +0 -0
- /package/{vod_mcp → src/vod_mcp}/host_adapters/codex_desktop.py +0 -0
- /package/{vod_mcp → src/vod_mcp}/host_adapters/generic.py +0 -0
- /package/{vod_mcp → src/vod_mcp}/host_adapters/workbuddy.py +0 -0
- /package/{vod_mcp → src/vod_mcp}/packs/knowledge.py +0 -0
- /package/{vod_mcp → src/vod_mcp}/pending.py +0 -0
- /package/{vod_mcp → src/vod_mcp}/policy.py +0 -0
- /package/{vod_mcp → src/vod_mcp}/runtime.example.json +0 -0
- /package/{vod_mcp → src/vod_mcp}/update_check.py +0 -0
- /package/{vodkit_cli → src/vodkit_cli}/__init__.py +0 -0
- /package/{vodkit_cli → src/vodkit_cli}/update.py +0 -0
package/CHANGELOG.md
CHANGED
|
@@ -373,3 +373,61 @@
|
|
|
373
373
|
- 592024b fix(ci): 发版状态对账在浅克隆下假红(tag 不可见≠未打 tag)
|
|
374
374
|
- 316a872 fix(release): 发版双副本检查/提交清单补插件副本 contract+safety
|
|
375
375
|
|
|
376
|
+
|
|
377
|
+
## v0.5.10(2026-11-16)
|
|
378
|
+
|
|
379
|
+
- 55cc756 !22 merge feat/dsh-b-mode into main
|
|
380
|
+
- e5ea23c feat(dsh): B 模式——工具面走 MCP client,壳只留 UI(D-dsh-mcp-b-1)
|
|
381
|
+
- 9706e28 fix(identity): clean-global 保留共享 state + doctor 并存态 + dsh 半套口径(评审 R1/R2B/R3/R4)
|
|
382
|
+
- d13e7a8 feat(identity): 机器级匿名令牌 + vod_auth_ensure,远程面与本地同效果(S145 / D-token-machine-1)
|
|
383
|
+
- e86e1e7 fix(matrix,audit,test-isolation): 矩阵不再写真机配置 + 巡检判生效入口 + 测试隔离切断继承(S141-S143)
|
|
384
|
+
- 280021b !21 merge feat/state-live-read into main
|
|
385
|
+
- 39684f4 refactor(state): read identity values at call time instead of import time (S140)
|
|
386
|
+
- 7b43e43 !20 merge feat/state-txn into main
|
|
387
|
+
- e6ab464 fix: transactional read-modify-write + key guard covers file/code tools
|
|
388
|
+
- 0dce393 !19 merge feat/packs-consistency into main
|
|
389
|
+
- 46e3257 fix(uninstall): clean skills by skillInstalls and never touch other hosts
|
|
390
|
+
- bafe51b docs: record S136/S137 closure (switch consistency, state atomicity)
|
|
391
|
+
- 08139db fix(state): runtime.json cross-process atomicity, never silently zeroed
|
|
392
|
+
- d05c91b fix(mcp): session-scoped pack switch must answer the same on every surface
|
|
393
|
+
- 69477b5 !18 merge feat/key-guard-hook into main
|
|
394
|
+
- b982fab feat(hooks): block reading the engine key into the conversation (hermes pre_tool_call)
|
|
395
|
+
- dfe47d1 !17 merge feat/doctor-egress into main
|
|
396
|
+
- 4fafaba feat(doctor): report egress proxy and engine reachability
|
|
397
|
+
- d36460f !16 merge feat/packs-configure into main
|
|
398
|
+
- 1d47e5c feat(mcp): session-scoped pack switch (vod_packs_configure) + tools/list_changed
|
|
399
|
+
- 9dcfd70 !15 merge feat/dsh-global-view into main
|
|
400
|
+
- 637c94a feat(cli): version/packs cover hosts outside installs[] (dsh profiles)
|
|
401
|
+
- e799d32 !14 merge docs/readme-skills-path into main
|
|
402
|
+
- 3ab72f4 docs(readme): 目录结构补 assets/(技能/契约/策略真源)与 hook 新位置,写清技能在哪
|
|
403
|
+
- 174f8a5 !13 merge fix/release-paths into main
|
|
404
|
+
- f034c1b chore(release): 质量门的 pyflakes 作用域补上 src/vodkit_cli(与 pre-push 对齐)
|
|
405
|
+
- 1cfd1fc fix(release): 发版链路与本地门禁跟上 S3 路径,字节码挡在包外
|
|
406
|
+
- 7ce767f !12 merge fix/registry-dsh-path into main
|
|
407
|
+
- 1355969 fix(release): registry_reconcile 跟上 packages/dsh 迁移(CI 红修复)
|
|
408
|
+
- 4c9f672 !11 merge feat/s3a-migrate into main
|
|
409
|
+
- d9d096b merge main:S3 规格(!10)与 S3 落地章节并存
|
|
410
|
+
- e3c82e0 !10 merge feat/s3-spec into main
|
|
411
|
+
- a347f23 docs(structure): 对齐 S3-A 后的真实布局
|
|
412
|
+
- 6fc5a66 refactor(structure): S3-A 迁移到 src-layout(两个根 + 入口显式设置)
|
|
413
|
+
- 77a4660 docs(architecture): 按业界对照收紧 S3 规格三处(资产→assets/、入口显式设根、workspace 触发条件)
|
|
414
|
+
- c584043 docs(architecture): 拍死 S3 规格(两个根取值表/插件副本不内嵌 src/回落退出条件/测试影响实测/hooks 归位)
|
|
415
|
+
- 025b93f !9 merge feat/structure-s2 into main
|
|
416
|
+
- 54c15fc refactor(structure): 共享资产收进 src/(S2),发布布局保持不变
|
|
417
|
+
- 09667bb !8 merge feat/install-s127 into main
|
|
418
|
+
- befadc2 docs(structure): 结构契约 + 根预算门禁 + README 对标重写 + CI 单门禁收口(S129)
|
|
419
|
+
- c27dd7a refactor(hooks)!: 预采集路由从 hermes 插件包改为宿主无关 shell hook(D-hook-unify-1)
|
|
420
|
+
- 1ace520 feat(install): 省略 --target 的 0/1/N 交互选择 + --target all 缺落点跳过(S127)
|
|
421
|
+
- fc5f6c0 !7 merge feat/mcp-manifest-evidence into main
|
|
422
|
+
- 9ddfe5d test(scope): 范围锁——云操作面无对象,且用断言锁住(S126)
|
|
423
|
+
- 10f95b9 feat(auth+skills): 凭据单入口 auth status/init + 技能读取"动作优先"教法(S124-S125)
|
|
424
|
+
- 6785ffd feat(cli): 全局命令 version/packs + --target all + uninstall 收窄/清残留 + 未知包即报错(S116-S123)
|
|
425
|
+
- 64abf63 fix(mcp)!: 清单补规范字段 + codex 改写读回验证/失败分类 + doctor 报形态(S111-S115)
|
|
426
|
+
- 7df5ffb docs+refactor(copies): 需求/设计补 S103-S110,生成器与门禁收敛到单一真源
|
|
427
|
+
- a2d9836 fix(release): build-info 指纹断言接受发版提交(prepack 重跑 sync 后 sha 前移一格)
|
|
428
|
+
|
|
429
|
+
|
|
430
|
+
## v0.5.11(2026-11-16)
|
|
431
|
+
|
|
432
|
+
- 36495cd fix(dsh): 壳安装钉版本 + 巡检看真判据(0.5.10 真机实锤)
|
|
433
|
+
|
package/QUICKSTART.md
CHANGED
|
@@ -63,10 +63,14 @@ bin/vod-devkit install --target hermes --product <你的产品> # 宿主任选
|
|
|
63
63
|
# 1) 服务端:起远程面(需官方 MCP SDK;对外自建 TLS 反代)
|
|
64
64
|
pip install 'vod-devkit[remote]'
|
|
65
65
|
vod-devkit serve --transport remote --port 9528 --host 127.0.0.1
|
|
66
|
+
# 开放到非回环地址时:匿名代领默认关闭(调用方须带 Bearer);
|
|
67
|
+
# 可信内网确需共享本机身份,再加 --allow-anon-mint
|
|
66
68
|
|
|
67
|
-
# 2) agent 侧 attach(token
|
|
69
|
+
# 2) agent 侧 attach(token 可选:给了用请求头身份,不给走服务端机器级匿名令牌)
|
|
68
70
|
npx -y vod-devkit@latest install --target opencode \
|
|
69
|
-
--mcp-url http://<host>:9528/mcp --
|
|
71
|
+
--mcp-url http://<host>:9528/mcp --product <你的产品>
|
|
72
|
+
# 需要按调用方隔离身份时再加 --mcp-token <VOD key>
|
|
73
|
+
# 注:--product 写的是本机 state;server 与插件同机才对该 server 的归因生效
|
|
70
74
|
```
|
|
71
75
|
|
|
72
76
|
attach 前安装器会**探活**:连接(initialize)、工具面(tools/list 与契约
|
package/README.en.md
CHANGED
|
@@ -48,6 +48,22 @@ npx -y vod-devkit@latest status # install-manifest: version / source / host /
|
|
|
48
48
|
evidence and no memory); when given it is validated against the catalog and a
|
|
49
49
|
typo exits 2.
|
|
50
50
|
|
|
51
|
+
### Global commands (whole-machine view)
|
|
52
|
+
|
|
53
|
+
```bash
|
|
54
|
+
vod-devkit version # CLI version + per-host installed version + effective packs
|
|
55
|
+
vod-devkit packs status # read each host's real config (not the manifest) for VOD_PACKS
|
|
56
|
+
vod-devkit packs enable collect # dry-run: shows what would change
|
|
57
|
+
vod-devkit packs enable collect --apply # write: managed entry env only, .bak on first change
|
|
58
|
+
vod-devkit install --target all # install to every detected host (hosts without CLI are skipped)
|
|
59
|
+
vod-devkit uninstall --target codex # remove just this host row
|
|
60
|
+
vod-devkit uninstall --target codex --clean-global # also purge payload residue and stale npx cache
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
The multi-host ledger lives in `install-manifest.json` → `installs[]` (deduped by target).
|
|
64
|
+
`--target` defaults to all rows. An unknown id in `VOD_PACKS` makes **both** install and server
|
|
65
|
+
startup exit 2 (never silently filtered — that produced "configured but not in effect").
|
|
66
|
+
|
|
51
67
|
## Per-host install
|
|
52
68
|
|
|
53
69
|
`install` takes `--target`; `doctor` / `status` / `verify` / `update` /
|
|
@@ -84,8 +100,13 @@ npx -y vod-devkit@latest uninstall # removes the native plugin, keeps confi
|
|
|
84
100
|
```
|
|
85
101
|
|
|
86
102
|
Uses the codex native plugin path (`codex plugin marketplace add` + `plugin add`),
|
|
87
|
-
with `.mcp.json`
|
|
88
|
-
|
|
103
|
+
with `.mcp.json` in the Agent Plugins field shape (`$schema` + `type: stdio`) running
|
|
104
|
+
`vod-devkit serve`. The installer then rewrites the cached copy to an absolute
|
|
105
|
+
interpreter plus payload path and reads it back — **that rewrite is where runtime
|
|
106
|
+
correctness comes from**: codex 0.167 does not expand `${PLUGIN_ROOT}` and does not
|
|
107
|
+
use the plugin root as cwd, so always install via `install --target codex` rather than
|
|
108
|
+
adding the marketplace entry by hand. If the collection circuit breaker is tripped,
|
|
109
|
+
install refuses the collect pack until `--ack-suspension`.
|
|
89
110
|
|
|
90
111
|
### CodeArts Agent (codeartsdoer)
|
|
91
112
|
|
package/README.md
CHANGED
|
@@ -1,5 +1,13 @@
|
|
|
1
1
|
# vod-devkit
|
|
2
2
|
|
|
3
|
+
[](https://github.com/yangaiwu/vod-devkit/actions/workflows/ci.yml)
|
|
4
|
+
[](https://www.npmjs.com/package/vod-devkit)
|
|
5
|
+
[](LICENSE.txt)
|
|
6
|
+
|
|
7
|
+
**成熟度:Beta(0.5.x)** —— 运行时接口与契约面稳定,安装/配置面在小版本间可能有
|
|
8
|
+
形态调整(每次在 CHANGELOG 写明);对外采集口径(两段式同意、原话逐字、归因不问用户)
|
|
9
|
+
视为红线,不随版本放宽。
|
|
10
|
+
|
|
3
11
|
[English](README.en.md) | 中文
|
|
4
12
|
|
|
5
13
|
把 **AI agent 产品的用户反馈**原话送进 VOD(Voice of Developer)囤积区:MCP server +
|
|
@@ -9,10 +17,12 @@
|
|
|
9
17
|
|
|
10
18
|
- **只采集**:插件的唯一写动作是调用引擎 HTTP API(`POST /external/voices`)。
|
|
11
19
|
落库、配额、审计、身份判定全在服务端;本仓没有任何数据库连接代码路径。
|
|
12
|
-
- **身份随请求走**:stdio
|
|
13
|
-
|
|
20
|
+
- **身份随请求走**:stdio 面走本机匿名令牌(机器级一份,跨版本/跨宿主共享);远程面优先取
|
|
21
|
+
请求头 Bearer,没有时与本地同链——由服务端领/复用同一枚机器级匿名令牌(`vod_auth_ensure`
|
|
22
|
+
可显式确认)。即"配置了就用配置的,没配置就领匿名",本地/远程同一套语义。
|
|
14
23
|
- **归因不问用户**:产品由插件从用户原话字面解析(引擎名录别名),唯一命中才采信;
|
|
15
|
-
多产品命中=歧义 → 落 UNKNOWN 由运营判。安装时的 `--product`
|
|
24
|
+
多产品命中=歧义 → 落 UNKNOWN 由运营判。安装时的 `--product` 只是可选先验,**且只在原话
|
|
25
|
+
出现自指("这个产品/你们家/本平台")时才生效**——没有语境支撑就不拿先验硬归,回到"先问一次"。
|
|
16
26
|
|
|
17
27
|
## 前置条件
|
|
18
28
|
|
|
@@ -25,12 +35,30 @@
|
|
|
25
35
|
|
|
26
36
|
远程面额外需要官方 MCP SDK:`pip install 'vod-devkit[remote]'`(stdio 形态零第三方依赖)。
|
|
27
37
|
|
|
38
|
+
### 装不上怎么办(四类实测失败,先按这个自查)
|
|
39
|
+
|
|
40
|
+
| 现象 | 判据 | 修法 |
|
|
41
|
+
|---|---|---|
|
|
42
|
+
| `No module named mcp` | 起了 `--transport remote` 却没装 SDK | `pip install 'vod-devkit[remote]'`(stdio 不需要) |
|
|
43
|
+
| 宿主侧工具面为空 / 启动失败 | 宿主 PATH 里没有能用的解释器(沙箱/精简 PATH) | 安装时钉解释器:`VOD_PYTHON=/usr/bin/python3.12 npx -y vod-devkit@latest install ...`;`doctor` 看 MCP 实际形态 |
|
|
44
|
+
| `ETARGET` / 拿到的还是旧版本 | npm 镜像滞后(npmmirror、内部镜像常见) | `npx --yes --registry=https://registry.npmjs.org vod-devkit@latest ...` |
|
|
45
|
+
| 更新了但行为没变 | codex 插件缓存跑旧副本(实测 0.4.2) | 重跑 `install --target codex`;`doctor` 会报"CLI 形态 / 载荷形态" |
|
|
46
|
+
|
|
28
47
|
## 快速开始
|
|
29
48
|
|
|
30
49
|
```bash
|
|
31
50
|
npx -y vod-devkit@latest install --target auto
|
|
32
51
|
```
|
|
33
52
|
|
|
53
|
+
省略 `--target` 时安装器会自动扫描机器上的宿主(判据=宿主 CLI 在 PATH 或配置目录存在,
|
|
54
|
+
数据在 `integrations/<host>/host.json`,不硬编码):
|
|
55
|
+
|
|
56
|
+
- 扫到 **1 个** → 直接装到它;
|
|
57
|
+
- 扫到 **多个** → 交互终端列出编号让你多选(`1` / `1,3` / `all`,回车取消);
|
|
58
|
+
非交互(CI/重定向)**不猜**,报错并提示 `--target <agent>` 或 `--target all`;
|
|
59
|
+
- 扫到 **0 个** → 交互终端问一次 target 名;非交互报错并列出支持列表;
|
|
60
|
+
- 一步全量:`install --target all`(`dsh` 缺 `--profile` 时跳过并说明,不算失败)。
|
|
61
|
+
|
|
34
62
|
装完**重启会话**才生效(宿主在启动时读取 MCP 配置)。随后自检:
|
|
35
63
|
|
|
36
64
|
```bash
|
|
@@ -41,6 +69,36 @@ npx -y vod-devkit@latest status # install-manifest:版本 / 来源 / 宿主
|
|
|
41
69
|
`--product <产品名>` 是可选先验(仅在无字面证据且无记忆时兜底);给了就会做名录
|
|
42
70
|
硬校验,拼错直接 `exit 2`,不给也能装。
|
|
43
71
|
|
|
72
|
+
### 全局命令(一次性看整台机器)
|
|
73
|
+
|
|
74
|
+
```bash
|
|
75
|
+
npx -y vod-devkit@latest version # CLI 版本 + 每个宿主已装版本 + 生效的能力包
|
|
76
|
+
npx -y vod-devkit@latest packs status # 各宿主实际生效的 VOD_PACKS(读宿主真实配置)
|
|
77
|
+
npx -y vod-devkit@latest packs enable collect # 将改什么(默认不写盘)
|
|
78
|
+
npx -y vod-devkit@latest packs enable collect --apply # 真写:只改受管条目的 env,重启用生效
|
|
79
|
+
npx -y vod-devkit@latest install --target all # 所有探测到的宿主一步装全(缺 CLI 的跳过)
|
|
80
|
+
npx -y vod-devkit@latest uninstall --target codex # 只摘这一个宿主,其它安装行保留
|
|
81
|
+
npx -y vod-devkit@latest uninstall --target codex --clean-global # 并清载荷残留与 npx 缓存
|
|
82
|
+
npx -y vod-devkit@latest auth status # 引擎地址 + 凭据指纹 + 档位(key / 匿名令牌)
|
|
83
|
+
npx -y vod-devkit@latest auth init --key <k> # 校验并显示指纹(缺省不写盘)
|
|
84
|
+
npx -y vod-devkit@latest auth init --key <k> --apply # 写 runtime.json(唯一入口,0600)
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
凭据优先级:显式 key(`auth init` 写入)> 环境变量 `VOD_JAVA_API_KEY`(平台/CI 注入)
|
|
88
|
+
> 匿名令牌自动领取(设备绑定)。**换 key 不需要重启宿主会话**:插件在每次调用引擎前现读
|
|
89
|
+
runtime.json 的身份值(`auth init --apply` 之后的下一次提交立刻用新 key)。**不要把 key 写进宿主 MCP 配置的 `env`**——明文,且会随
|
|
90
|
+
配置进 git;`env` 只留给平台注入。
|
|
91
|
+
|
|
92
|
+
多宿主账本在 `install-manifest.json` 的 `installs[]`(按 target 去重)。`--target` 缺省
|
|
93
|
+
作用于全部行;`packs` 的写操作默认 dry-run,`--apply` 才落盘(首改留 `.bak`,写后读回验证,
|
|
94
|
+
`core` 强制包含)。`VOD_PACKS` 里出现未知包 id 时**安装口与 server 启动口都会报错退出**
|
|
95
|
+
——不静默过滤,免得"配了没生效"。
|
|
96
|
+
|
|
97
|
+
dsh 不在账本里(它是 `dsh-vod-devkit` 的 profile 依赖,安装器不写行),所以 `version` /
|
|
98
|
+
`packs status` 会额外**只读探测** `~/.dsh/profiles/*/package.json`,为每个装了壳的 profile
|
|
99
|
+
打一行 `dsh(<profile>)`:版本取 `node_modules` 里实际装的那份,漂移时直接给出
|
|
100
|
+
`install --target dsh --profile <p>`;`packs` 对它是 `[n/a]`(壳不走 MCP env,改面要重装)。
|
|
101
|
+
|
|
44
102
|
## 按宿主安装
|
|
45
103
|
|
|
46
104
|
五个宿主的装法一致(`install` 带 `--target`),差异在配置落点与注意点。
|
|
@@ -84,7 +142,10 @@ npx -y vod-devkit@latest uninstall # 摘原生插件,不删你的 confi
|
|
|
84
142
|
```
|
|
85
143
|
|
|
86
144
|
- 形态:走 codex 原生插件(`codex plugin marketplace add` + `plugin add`),技能随插件
|
|
87
|
-
渐进加载;`.mcp.json`
|
|
145
|
+
渐进加载;`.mcp.json` 是 Agent Plugins 规范字段(`$schema` + `type: stdio`),入口为
|
|
146
|
+
`vod-devkit serve`。安装器随后会把缓存里那份改写成「绝对解释器 + 载荷副本」并读回验证
|
|
147
|
+
——**这是运行时正确性的来源**:codex 0.167 实测不展开 `${PLUGIN_ROOT}`、cwd 也不是
|
|
148
|
+
插件根,静态清单只能走 CLI,所以请用 `install --target codex` 装,别绕过安装器直装
|
|
88
149
|
- 采集熔断:未确认提交累计触发后 install 会拒绝装 collect,恢复需
|
|
89
150
|
`--ack-suspension`(审计日志落在 `~/.codex/`)
|
|
90
151
|
|
|
@@ -129,14 +190,25 @@ npx -y vod-devkit@latest install --target codex-desktop
|
|
|
129
190
|
|
|
130
191
|
```bash
|
|
131
192
|
npx -y vod-devkit@latest install --target workbuddy
|
|
193
|
+
# 重启会话后:验证 / 更新 / 卸载
|
|
194
|
+
npx -y vod-devkit@latest doctor
|
|
195
|
+
npx -y vod-devkit@latest status
|
|
196
|
+
npx -y vod-devkit@latest install --target workbuddy # 更新=幂等重装(不动其它键)
|
|
197
|
+
npx -y vod-devkit@latest uninstall
|
|
132
198
|
```
|
|
133
199
|
|
|
134
200
|
- 落点:`~/.workbuddy/mcp.json` 的 `mcpServers.vod-devkit`;技能装到 `~/.workbuddy/skills`
|
|
201
|
+
- 坑:WorkBuddy 只在 Windows/macOS 有客户端;Linux 上装它等于预置配置,宿主那边不读
|
|
135
202
|
|
|
136
203
|
### AtomCode(atomcode)
|
|
137
204
|
|
|
138
205
|
```bash
|
|
139
206
|
npx -y vod-devkit@latest install --target atomcode
|
|
207
|
+
# 重启会话后:验证 / 更新 / 卸载
|
|
208
|
+
npx -y vod-devkit@latest doctor
|
|
209
|
+
npx -y vod-devkit@latest status
|
|
210
|
+
npx -y vod-devkit@latest install --target atomcode # 更新=幂等重装
|
|
211
|
+
npx -y vod-devkit@latest uninstall
|
|
140
212
|
```
|
|
141
213
|
|
|
142
214
|
- 配置根可由 `ATOMCODE_HOME` 覆盖(默认 `~/.atomcode`),落点 `mcp.json` 的
|
|
@@ -147,7 +219,10 @@ npx -y vod-devkit@latest install --target atomcode
|
|
|
147
219
|
|
|
148
220
|
```bash
|
|
149
221
|
npx -y vod-devkit@latest install --target dsh --profile <profile名>
|
|
222
|
+
# 重启 dsh 后:验证 / 更新 / 卸载
|
|
150
223
|
npx -y vod-devkit@latest doctor
|
|
224
|
+
npx -y vod-devkit@latest status
|
|
225
|
+
npx -y vod-devkit@latest install --target dsh --profile <profile名> # 更新
|
|
151
226
|
npx -y vod-devkit@latest uninstall
|
|
152
227
|
```
|
|
153
228
|
|
|
@@ -155,6 +230,12 @@ npx -y vod-devkit@latest uninstall
|
|
|
155
230
|
`dsh-vod-devkit`(npm 同名),配置幂等写进 profile 的 `cordis.patch.yml`
|
|
156
231
|
- **dsh 壳不走 MCP**:`--mcp-url` / `--skills-only` 对它显式报错;远程面模式不覆盖 dsh
|
|
157
232
|
- 卸载会摘插件并从 patch 移除本插件的 config 块,不删其它插件段
|
|
233
|
+
- **dsh 壳只到"半套"(支持矩阵里的显式差异,不是 bug)**:工具面 6 个
|
|
234
|
+
(submit / list_submitted / info / list_skills / retrieve_skill / check_update,
|
|
235
|
+
没有 MCP 侧的 search_products / auth_status / auth_ensure / draft / commit / packs_configure),
|
|
236
|
+
并且**不共享机器级 state**(它有自己的 `packages/dsh/data/runtime.json` 与 cap 200 环形账本,
|
|
237
|
+
与 MCP 侧 `<state>/runtime.json` 是两份设备锚点)。跨语言共用锁 + 字段契约对齐后才可能合并,
|
|
238
|
+
本轮记为待办;需要完全一致的匿名身份/账本时用 MCP 宿主。
|
|
158
239
|
|
|
159
240
|
## 其它 MCP 宿主(通用层)
|
|
160
241
|
|
|
@@ -202,7 +283,7 @@ vod-devkit serve --transport remote --port 9528 --host 127.0.0.1 # 前面需
|
|
|
202
283
|
"type": "remote", "url": "http://localhost:9528", "enabled": true } } }
|
|
203
284
|
```
|
|
204
285
|
|
|
205
|
-
宿主 attach(token
|
|
286
|
+
宿主 attach(token 可选——给了就用请求头身份,不给就走远程 server 侧的机器级匿名令牌):
|
|
206
287
|
|
|
207
288
|
```bash
|
|
208
289
|
npx -y vod-devkit@latest install --target hermes --mcp-url https://<网关>/mcp --mcp-token <key>
|
|
@@ -213,17 +294,22 @@ npx -y vod-devkit@latest install --target codex --mcp-url https://<网关>/mc
|
|
|
213
294
|
写入前先探活(三步):`initialize`(连接)+ `tools/list`(工具面必须等于
|
|
214
295
|
远程面工具集)+ **key 真伪**(经远程面真调 `vod_auth_status`,引擎三态:
|
|
215
296
|
`rejected` = API Key 无效 → 拒装且**不写任何配置**;`device-mismatch` =
|
|
216
|
-
匿名令牌设备锚点漂移(token 有效、本机非签发设备)→
|
|
217
|
-
|
|
218
|
-
工具面。远程面与 stdio
|
|
219
|
-
|
|
220
|
-
-
|
|
221
|
-
|
|
297
|
+
匿名令牌设备锚点漂移(token 有效、本机非签发设备)→ 放行,首次提交或
|
|
298
|
+
`vod_auth_ensure` 时自动重领;引擎不可达 → 放行,网络问题不是 key 问题)。`doctor` 复查端点与
|
|
299
|
+
工具面。远程面与 stdio 面的一致性(D-token-machine-1,2026-11-16):
|
|
300
|
+
|
|
301
|
+
- **工具面**:与本地一致,唯一例外是 `vod_packs_configure`(进程内开关,HTTP 每请求现造
|
|
302
|
+
server、多 agent 共用会互相影响)。两段式草稿与本机账本在远程同样可用——草稿按宿主
|
|
303
|
+
隔离(`owner`),A 的草稿 B 提交会被拒(`-32011`)。
|
|
304
|
+
- **身份**:请求头 Bearer 优先;没有时与本地同链,用机器级匿名令牌。
|
|
222
305
|
- token 承载:hermes 走 env `MCP_VOD_DEVKIT_API_KEY`(配置里只留 `${...}` 引用);
|
|
223
|
-
opencode 写在 `headers`(注意文件权限);codex 走 `VOD_MCP_TOKEN
|
|
224
|
-
|
|
225
|
-
-
|
|
226
|
-
|
|
306
|
+
opencode 写在 `headers`(注意文件权限);codex 走 `VOD_MCP_TOKEN`;**不给 token 也行**
|
|
307
|
+
(配置里不写认证,提交走服务端匿名令牌)。
|
|
308
|
+
- **`--product` 的边界**:它写进的是**执行安装那台机器**的 state。远程面与插件同机时
|
|
309
|
+
server 读同一份 state(有效);若 server 在另一台机器上,这个先验对 server 的归因不起作用。
|
|
310
|
+
- **无内建鉴权**:本进程不校验身份,默认只绑回环;对外必须反代 TLS + 身份校验。
|
|
311
|
+
**非回环绑定(`--host 0.0.0.0`)默认关闭匿名代领**,调用方必须带 Bearer;
|
|
312
|
+
确需在可信内网共享本机身份,加 `--allow-anon-mint`。
|
|
227
313
|
|
|
228
314
|
端口被占用用 `--port <port>`(同步改 url);`--host 0.0.0.0` 可开 LAN 访问。
|
|
229
315
|
|
|
@@ -271,9 +357,85 @@ install-manifest 名册对账(doctor 逐落点)+ 声明计数对账(对外
|
|
|
271
357
|
|
|
272
358
|
本文档不放用例数/工具数——手写计数必然漂移;数字一律现场测量。
|
|
273
359
|
|
|
360
|
+
## 预采集钩子(hermes)
|
|
361
|
+
|
|
362
|
+
hermes 侧装一个**宿主无关的钩子脚本** `hooks/vod_router.py`,由 `~/.hermes/config.yaml` 的
|
|
363
|
+
`hooks.pre_llm_call` 注册:每轮对用户消息做确定性意图判定(关键词,模型不参与),命中就
|
|
364
|
+
往本轮用户消息追加一段采集指令,未命中零注入。
|
|
365
|
+
|
|
366
|
+
```bash
|
|
367
|
+
# 装完即可核对注册与真拉起(hermes 自带测试面,不需要开会话)
|
|
368
|
+
hermes hooks list
|
|
369
|
+
hermes hooks test pre_llm_call --payload-file payload.json
|
|
370
|
+
```
|
|
371
|
+
|
|
372
|
+
- 首次真实使用 hermes 会弹一次同意(consent 按 `(event, command)` 记);`hooks list` 里
|
|
373
|
+
`✗ not allowlisted` 就是"等你点同意",不是装坏了
|
|
374
|
+
- 老版本装过插件形态(`~/.hermes/plugins/vod-feedback-router`)的机器,本次 install 会
|
|
375
|
+
自动清理并摘掉 `plugins.enabled` 里的旧名字——否则插件与 hook 双份注入
|
|
376
|
+
- 细节(线协议、判据、验证到哪一步、两条 hook 的边界)见
|
|
377
|
+
[docs/hooks.md](docs/hooks.md)
|
|
378
|
+
|
|
379
|
+
## 能力包与技能披露
|
|
380
|
+
|
|
381
|
+
- `VOD_PACKS` 三层:环境变量(平台/CI 注入,启动生效);**会话内开关** `vod_packs_configure`
|
|
382
|
+
工具(stdio 面:`enable`/`disable`/`reset`,立即改工具面并推 `tools/list_changed`,
|
|
383
|
+
**不落盘、重启即清**;远程面无会话、不提供);CLI `packs enable/disable/all --apply`
|
|
384
|
+
(持久,直接改写各宿主配置里的 `VOD_PACKS`,缺省 dry-run,`core` 强制包含)
|
|
385
|
+
- 三层分工一句话:要**当前会话立刻变**用工具,要**以后都变**用 CLI,平台注入用 env。
|
|
386
|
+
MCP 工具不写你的配置文件(持久化只走 CLI 这一个入口)
|
|
387
|
+
- 未知包 id:安装口、server 启动口与 `vod_packs_configure` 都报错并列出可用 id——不静默过滤
|
|
388
|
+
("配了没生效"最难查);采集熔断期间开启 `collect` 会被拒(`-32015`,安全门禁不可绕过)
|
|
389
|
+
- 技能读取:stdio 面 `vod_list_skills` 给 `skillRoot` 与每技能 `path`,教法是**动作优先**
|
|
390
|
+
(先直读 `<skillRoot>/<name>/SKILL.md`,被拒/失败才回落 `vod_retrieve_skill`,绝不反复请求);
|
|
391
|
+
远程面不给服务器本机路径,规则文本走 `vod_retrieve_skill`
|
|
392
|
+
|
|
393
|
+
## 安全模型
|
|
394
|
+
|
|
395
|
+
三层,顺序就是从便宜到贵:
|
|
396
|
+
|
|
397
|
+
1. **技能教**:`vod-feedback-collect` 规定先承接、再征得同意、原话逐字、不猜产品。
|
|
398
|
+
2. **钩子提醒**:pre_llm_call 命中采集意图时注入指令(防止模型把抱怨当排障问题去复现)。
|
|
399
|
+
3. **运行期护栏**:`safety/policy.json` 的声明式规则 + 两段式草稿/令牌
|
|
400
|
+
(`-32010` 未确认、`-32011` 载荷不符、`-32012` 无凭据、`-32013` 过期、`-32014` 单次消费)
|
|
401
|
+
+ 护栏 deny 直连数据库意图。
|
|
402
|
+
|
|
403
|
+
诚实残留(写清楚,不掩):
|
|
404
|
+
|
|
405
|
+
- 钩子分两条:`pre_llm_call` 只"提醒"(不拦);`pre_tool_call`(hermes)会**真正阻断**
|
|
406
|
+
"读 `runtime.json`"与"`env` 导出点名 key"两类动作,并给替代命令(`auth status` 只出指纹)。
|
|
407
|
+
脚本任何异常都 fail-open(阻塞事件里崩溃会拦掉所有工具调用);可 `VOD_HOOK_READ_GUARD=0`
|
|
408
|
+
关闭。**codex/opencode 侧的等价注册未做**——那两个宿主上仍只有技能教法。
|
|
409
|
+
- 宿主对 `runtime.json` 的读取门控(沙箱规则 / allow 列表)**未验证**:插件侧探测不到宿主的
|
|
410
|
+
权限策略,因此不声称"已拦"。降低暴露面的做法是 `runtime.json` 不种 key(安装器故意不把
|
|
411
|
+
`java_key` 写进载荷副本,运行期走匿名令牌)+ `auth status` 只输出指纹。
|
|
412
|
+
- 远程面**不内置鉴权**:默认只绑回环,对外必须自建 TLS 反代与身份校验;身份优先取请求头
|
|
413
|
+
Bearer,没有时按整机匿名令牌(同一台机器上的多 agent 共用一份,多租户场景请各带 Bearer)。
|
|
414
|
+
- 不允许把 key 写进宿主 MCP 配置的 `env`(明文且随配置进 git)——用 `auth init`。
|
|
415
|
+
|
|
416
|
+
## 目录结构(摘要)
|
|
417
|
+
|
|
418
|
+
```
|
|
419
|
+
src/ 可导入 Python 包(真源):vod_mcp/ 运行时、vodkit_cli/ 安装器
|
|
420
|
+
assets/ 项目级资产(真源):skills/ 技能树、contract/ 工具契约、safety/ 护栏策略
|
|
421
|
+
integrations/ 宿主规格 host.json(探测/落点)+ hermes/hooks/vod_router.py(宿主侧钩子)
|
|
422
|
+
packages/dsh/ dsh 壳(独立 npm 包) scripts/ 生成器与门禁(成对)
|
|
423
|
+
plugins/ 宿主发布物(清单 + 生成副本,副本零提交) tests/ pytest(含结构/范围/花名册门禁)
|
|
424
|
+
docs/ 架构/设计/需求/决策/安全/钩子 npm/ bin/ 薄壳(找解释器 + 设根 + 透传)
|
|
425
|
+
```
|
|
426
|
+
|
|
427
|
+
**技能在哪**:真源是 `assets/skills/<技能名>/SKILL.md`(4 个:vod-core、
|
|
428
|
+
vod-feedback-collect、vod-problem-classification-rules、vod-scoring-rules)。
|
|
429
|
+
`plugins/vod-devkit/skills/` 与载荷 `~/.vod-devkit/payloads/<ver>/skills/` 都是**生成副本**
|
|
430
|
+
(v0.5.9 起零提交,`scripts/sync_plugin.py` 生成),不要在仓里找它们。
|
|
431
|
+
|
|
432
|
+
根目录条目受**预算**约束(`tests/test_structure_guards.py::test_s129_*`):新增顶层目录/文件
|
|
433
|
+
必须先改 [docs/architecture.md](docs/architecture.md)(结构契约与迁移分阶)。
|
|
434
|
+
|
|
274
435
|
## 文档
|
|
275
436
|
|
|
276
|
-
- 需求 / 设计:[docs/proposal.md](docs/proposal.md) · [docs/design.md](docs/design.md)
|
|
437
|
+
- 结构契约:[docs/architecture.md](docs/architecture.md) | 需求 / 设计:[docs/proposal.md](docs/proposal.md) · [docs/design.md](docs/design.md)
|
|
438
|
+
- 钩子规则:[docs/hooks.md](docs/hooks.md) | 安全边界:[docs/safety-model.md](docs/safety-model.md)
|
|
277
439
|
- 一页纸:[docs/scheme-overview.md](docs/scheme-overview.md) | 安全边界:[docs/safety-model.md](docs/safety-model.md)
|
|
278
440
|
- 决策台账:[docs/decisions.md](docs/decisions.md) | 规则真源:[docs/rules-provenance.json](docs/rules-provenance.json)
|
|
279
441
|
- 手动配置与排障:[QUICKSTART.md](QUICKSTART.md) | 分宿主细节:[INSTALL.md](INSTALL.md)
|
|
@@ -292,5 +454,31 @@ vod-devkit detect --path . # 只读识别项目语言/框架/构建(不
|
|
|
292
454
|
python3 scripts/host_matrix.py # 9 宿主安装矩阵:装→断言→拉起 server→卸→验干净
|
|
293
455
|
```
|
|
294
456
|
|
|
457
|
+
矩阵 PASS 的**含义边界**(2026-11-16 收窄,别读成"宿主装得上"):沙箱里的宿主 CLI 一律用
|
|
458
|
+
`exit 1` 的 shim 挡住(空 `HERMES_HOME` 下 hermes CLI 会自举依赖、实测卡到 300s),所以矩阵
|
|
459
|
+
验的是"安装器写出的条目 + 按该条目拉起 server 自证",**不验 CLI 注册段**;真机生效入口用
|
|
460
|
+
`python3 scripts/host_matrix.py --audit` 判(它读 config.yaml 的生效条目与 codex 的启用市场,
|
|
461
|
+
报文里带判据来源)。
|
|
462
|
+
|
|
295
463
|
`doctor` 的失败按层分组,不再平铺一列 `FAIL`;`explain` 与它共用同一张规则表
|
|
296
464
|
(`vod_mcp/diagnose.py`),所以"报告里出现的层/原因"和"解释出来的动作"永远一致。
|
|
465
|
+
|
|
466
|
+
`doctor` 末尾固定打两行**出站面**(只报告、不改退出码,离线环境仍可用):
|
|
467
|
+
|
|
468
|
+
```
|
|
469
|
+
[doctor] 出站代理:HTTPS_PROXY=http://***:***@proxy:3128;NO_PROXY=127.0.0.1
|
|
470
|
+
[doctor] 引擎可达:HTTP 401(可达;鉴权/路径响应)http://…/external/meta
|
|
471
|
+
```
|
|
472
|
+
|
|
473
|
+
- 代理只报 env 生效值(`HTTPS_PROXY/HTTP_PROXY/ALL_PROXY/NO_PROXY`),**不建配置文件**
|
|
474
|
+
——尊重既有 HTTP 约定;URL 里的口令一律掩码(doctor 输出常被贴进工单)。
|
|
475
|
+
- 引擎可达**无 key 也探**:401/403 算「可达」(鉴权问题≠网络问题),连不上只 `warn`
|
|
476
|
+
(离线装机 doctor 必须还能用),且不因此改退出码。
|
|
477
|
+
|
|
478
|
+
状态文件(`runtime.json`)的并发与损坏处理:
|
|
479
|
+
|
|
480
|
+
- 同机多个宿主的 server 进程**共用**一份载荷 `runtime.json` → 写入走 tmp + `os.replace`
|
|
481
|
+
(原子替换)+ POSIX `fcntl.flock`(`runtime.json.lock`)。**Windows 没有对等机制,未覆盖**,
|
|
482
|
+
如实标注(那里仍是进程内锁)。
|
|
483
|
+
- 解析失败**不静默归零**:原文件备份为 `runtime.json.corrupt-<时间戳>` 并在 stderr 告警,
|
|
484
|
+
随后以空状态继续——可人工恢复;不会出现"key 和账本一起消失且无人知道"。
|
|
@@ -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.5.
|
|
4
|
+
"version": "0.5.11",
|
|
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>」全文),禁止改写概括——这是用户核对原话是否被改写的唯一窗口。禁止向用户解释内部机制(声音来源/渠道字段/计数规则/配额/归因)。",
|
|
@@ -201,6 +201,132 @@
|
|
|
201
201
|
},
|
|
202
202
|
"backend": "local(无上游;探测时轻量 ping)"
|
|
203
203
|
},
|
|
204
|
+
"vod_auth_ensure": {
|
|
205
|
+
"description": "身份判定 + 领取(幂等,唯一有副作用的认证工具):有可用令牌就原样返回并只做一次探针;没有或已过期/设备不匹配时,由本服务代理向引擎令牌端点领取零字段匿名令牌、落机器级 state 后复探并返回。调用时机:开始采集前一次(不要每次工具调用都调)。本地 stdio 与远程 HTTP(同机独立部署)同一套语义:请求头 Bearer 优先(source=request,不代领);无 Bearer 时由服务端领/复用机器级匿名令牌(整机一份)。显式配置的 key(env 或 auth init 写入)一律不覆盖,被引擎拒绝时如实报错、不静默降级;引擎不可达时不领取、不判定(verified=null)。返回指纹,不下发明文。",
|
|
206
|
+
"input": {
|
|
207
|
+
"type": "object",
|
|
208
|
+
"properties": {}
|
|
209
|
+
},
|
|
210
|
+
"output": {
|
|
211
|
+
"type": "object",
|
|
212
|
+
"properties": {
|
|
213
|
+
"tier": {
|
|
214
|
+
"type": "string",
|
|
215
|
+
"description": "formal|anonymous|none"
|
|
216
|
+
},
|
|
217
|
+
"source": {
|
|
218
|
+
"type": "string",
|
|
219
|
+
"description": "env(平台注入 key)|request(请求头 Bearer)|runtime-key(auth init 写入)|runtime-anonymous(已缓存匿名令牌)|new-anonymous(本次领取)|none"
|
|
220
|
+
},
|
|
221
|
+
"verified": {
|
|
222
|
+
"type": [
|
|
223
|
+
"boolean",
|
|
224
|
+
"null"
|
|
225
|
+
],
|
|
226
|
+
"description": "true=引擎确认有效;false=被拒;null=不可达(不判定)"
|
|
227
|
+
},
|
|
228
|
+
"reason": {
|
|
229
|
+
"type": "string"
|
|
230
|
+
},
|
|
231
|
+
"fingerprint": {
|
|
232
|
+
"type": [
|
|
233
|
+
"string",
|
|
234
|
+
"null"
|
|
235
|
+
]
|
|
236
|
+
},
|
|
237
|
+
"changed": {
|
|
238
|
+
"type": "boolean",
|
|
239
|
+
"description": "是否发生了领取/落盘"
|
|
240
|
+
},
|
|
241
|
+
"base": {
|
|
242
|
+
"type": "string"
|
|
243
|
+
},
|
|
244
|
+
"guidance": {
|
|
245
|
+
"type": "array"
|
|
246
|
+
},
|
|
247
|
+
"note": {
|
|
248
|
+
"type": "string"
|
|
249
|
+
}
|
|
250
|
+
},
|
|
251
|
+
"required": [
|
|
252
|
+
"tier",
|
|
253
|
+
"source",
|
|
254
|
+
"verified",
|
|
255
|
+
"changed"
|
|
256
|
+
]
|
|
257
|
+
},
|
|
258
|
+
"backend": "local(无令牌时调引擎 /external/token)"
|
|
259
|
+
},
|
|
260
|
+
"vod_packs_configure": {
|
|
261
|
+
"description": "会话内开关能力包(stdio 面):enable/disable 包 id 或 reset=true,立即改工具面并推 tools/list_changed。不写 env/宿主配置、重启即清;持久化用 CLI `vod-devkit packs enable|disable <id> --apply`。core 强制包含;未知 id 报错;采集熔断期间不能开启 collect(安全门禁)。",
|
|
262
|
+
"input": {
|
|
263
|
+
"type": "object",
|
|
264
|
+
"properties": {
|
|
265
|
+
"enable": {
|
|
266
|
+
"type": "array",
|
|
267
|
+
"items": {
|
|
268
|
+
"type": "string"
|
|
269
|
+
},
|
|
270
|
+
"description": "要开启的包 id(core/collect/knowledge)"
|
|
271
|
+
},
|
|
272
|
+
"disable": {
|
|
273
|
+
"type": "array",
|
|
274
|
+
"items": {
|
|
275
|
+
"type": "string"
|
|
276
|
+
},
|
|
277
|
+
"description": "要关闭的包 id"
|
|
278
|
+
},
|
|
279
|
+
"reset": {
|
|
280
|
+
"type": "boolean",
|
|
281
|
+
"description": "恢复按 VOD_PACKS 的启动配置(清会话内开关)"
|
|
282
|
+
}
|
|
283
|
+
}
|
|
284
|
+
},
|
|
285
|
+
"output": {
|
|
286
|
+
"type": "object",
|
|
287
|
+
"properties": {
|
|
288
|
+
"packs": {
|
|
289
|
+
"type": "array",
|
|
290
|
+
"items": {
|
|
291
|
+
"type": "string"
|
|
292
|
+
}
|
|
293
|
+
},
|
|
294
|
+
"added": {
|
|
295
|
+
"type": "array",
|
|
296
|
+
"items": {
|
|
297
|
+
"type": "string"
|
|
298
|
+
}
|
|
299
|
+
},
|
|
300
|
+
"removed": {
|
|
301
|
+
"type": "array",
|
|
302
|
+
"items": {
|
|
303
|
+
"type": "string"
|
|
304
|
+
}
|
|
305
|
+
},
|
|
306
|
+
"tools": {
|
|
307
|
+
"type": "array",
|
|
308
|
+
"items": {
|
|
309
|
+
"type": "string"
|
|
310
|
+
}
|
|
311
|
+
},
|
|
312
|
+
"changed": {
|
|
313
|
+
"type": "boolean"
|
|
314
|
+
},
|
|
315
|
+
"persisted": {
|
|
316
|
+
"type": "boolean"
|
|
317
|
+
},
|
|
318
|
+
"note": {
|
|
319
|
+
"type": "string"
|
|
320
|
+
}
|
|
321
|
+
},
|
|
322
|
+
"required": [
|
|
323
|
+
"packs",
|
|
324
|
+
"changed",
|
|
325
|
+
"persisted"
|
|
326
|
+
]
|
|
327
|
+
},
|
|
328
|
+
"backend": "local(无上游)"
|
|
329
|
+
},
|
|
204
330
|
"vod_list_submitted": {
|
|
205
331
|
"description": "查询本机已提交的声音(只读)。本地账本(cap 200),最新在前;跨机/权威查询随引擎端点(VOD-VOI)。终端用户进度追问由 agent 凭此对账回答。",
|
|
206
332
|
"input": {
|
|
@@ -20,6 +20,7 @@ metadata:
|
|
|
20
20
|
| 本机已提交过哪些(进度追问) | `vod_list_submitted`(本地账本口径,换机不保留)**仅 stdio 面可用**;远程面改答"本条收录状态" |
|
|
21
21
|
| 插件版本/来源核验 | `vod_devkit_info`(version + commitSha) |
|
|
22
22
|
| key/认证状态、引擎连通性 | `vod_auth_status`(只报指纹,不下发明文) |
|
|
23
|
+
| 准备采集前确认身份(尤其 MCP 单独部署/无 key) | `vod_auth_ensure`(有可用令牌就复用,没有则由服务代理领匿名令牌;幂等,一次会话调一次) |
|
|
23
24
|
| 有哪些技能、规则技能是否可用 | `vod_list_skills` |
|
|
24
25
|
| 取规则技能全文(分类/评分口径) | `vod_retrieve_skill`(owner pack 被裁剪时返回恢复指引) |
|
|
25
26
|
|
|
@@ -48,4 +49,34 @@ metadata:
|
|
|
48
49
|
5. **不碰内部面**:不尝试数据库直连、不读取或打印凭据;被 deny 时如实告知,
|
|
49
50
|
不要换措辞重试。
|
|
50
51
|
6. **规则口径以技能/披露内容为准**:不凭训练数据回答 VOD 分类与评分——
|
|
51
|
-
vendored 文本与引擎代码同源。
|
|
52
|
+
vendored 文本与引擎代码同源。
|
|
53
|
+
|
|
54
|
+
## 身份准备(MCP 单独部署 / 无 key)
|
|
55
|
+
|
|
56
|
+
采集前要确认身份时,调 **一次** `vod_auth_ensure`(幂等,不要每次工具调用都调):
|
|
57
|
+
|
|
58
|
+
| 返回 | 处理 |
|
|
59
|
+
|---|---|
|
|
60
|
+
| `verified=true` | 直接继续采集;`source` 说明身份来源(`env` 显式 key / `runtime` 本机令牌 / `new-anonymous` 刚领的匿名令牌) |
|
|
61
|
+
| `verified=false` + `reason=rejected` | 显式 key 被引擎拒绝:告诉用户换一把有效 key,**不要**改走匿名档掩盖配置错误 |
|
|
62
|
+
| `verified=null` + `reason=unreachable` | 网络问题不是身份问题:如实说"暂时无法确认身份",不要领新令牌 |
|
|
63
|
+
|
|
64
|
+
不读环境变量、不翻 `runtime.json`/state 文件判断身份——那是服务进程的事(读也会被 hook 拦回,
|
|
65
|
+
只引指纹)。匿名档额度是**整机共享**的:别的宿主用多了,这里也会提前撞上限,属于正常语义。
|
|
66
|
+
|
|
67
|
+
MCP 独立部署(同机常驻 server,agent 用 HTTP 连 127.0.0.1:9528)与本地 stdio **同一套流程**:
|
|
68
|
+
照样调 `vod_auth_ensure`(带 Authorization 就是请求头身份,不带就用整机匿名令牌);
|
|
69
|
+
两段式 `vod_draft_voices`/`vod_commit_voices` 与 `vod_list_submitted` 在远程面同样可用,
|
|
70
|
+
但草稿只能由创建它的那个 agent 提交(按宿主隔离,串了会报"不属于当前客户端")。
|
|
71
|
+
唯一远程没有的是 `vod_packs_configure`(进程内开关)。
|
|
72
|
+
|
|
73
|
+
## 宿主差异:dsh 的工具名带前缀
|
|
74
|
+
|
|
75
|
+
- dsh(装了 `@deepseek-ai/dsh-mcp-client` 的版本)**工具由 MCP 承载**,注册名是
|
|
76
|
+
`mcp__vod-devkit__vod_search_products` / `mcp__vod-devkit__vod_auth_ensure` /
|
|
77
|
+
`mcp__vod-devkit__vod_submit_voices` …(能力面与其它宿主一致)。
|
|
78
|
+
- 没有 mcp-client 的降级形态,工具由 dsh 壳自注册,只有 6 个**短名**
|
|
79
|
+
(vod_submit_voices / vod_list_submitted / vod_devkit_info / vod_list_skills /
|
|
80
|
+
vod_retrieve_skill / vod_check_update),没有 ensure / draft / commit。
|
|
81
|
+
- 调用前**以宿主 tools/list 里的实际名字为准**;两种形态的采集纪律、同意前置、原话逐字
|
|
82
|
+
完全相同,只是名字前缀不同。
|