vod-devkit 0.5.0 → 0.5.1
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 +27 -0
- package/QUICKSTART.md +1 -1
- package/README.en.md +190 -57
- package/README.md +194 -75
- package/bin/vod-devkit +436 -426
- package/contract/tools.schema.json +78 -8
- package/integrations/codeartsdoer/host.json +11 -0
- package/package.json +4 -1
- package/plugins/vod-devkit/.codex-plugin/plugin.json +1 -1
- package/plugins/vod-devkit/build-info.json +3 -3
- package/plugins/vod-devkit/skills/vod-core/SKILL.md +12 -4
- package/plugins/vod-devkit/skills/vod-core/references/acceptance-criteria.md +9 -0
- package/plugins/vod-devkit/skills/vod-core/references/verification-method.md +29 -0
- package/plugins/vod-devkit/skills/vod-feedback-collect/SKILL.md +57 -11
- package/plugins/vod-devkit/skills/vod-feedback-collect/references/acceptance-criteria.md +28 -0
- package/plugins/vod-devkit/skills/vod-feedback-collect/references/verification-method.md +31 -0
- package/plugins/vod-devkit/skills/vod-problem-classification-rules/SKILL.md +3 -1
- package/plugins/vod-devkit/skills/vod-scoring-rules/SKILL.md +22 -1
- package/plugins/vod-devkit/vod_mcp/__init__.py +1 -1
- package/plugins/vod-devkit/vod_mcp/attribution.py +378 -0
- package/plugins/vod-devkit/vod_mcp/host_adapters/__init__.py +26 -0
- package/plugins/vod-devkit/vod_mcp/host_adapters/base.py +73 -0
- package/plugins/vod-devkit/vod_mcp/host_adapters/codearts.py +57 -0
- package/plugins/vod-devkit/vod_mcp/host_adapters/codex.py +209 -0
- package/plugins/vod-devkit/vod_mcp/host_adapters/dsh.py +176 -0
- package/plugins/vod-devkit/vod_mcp/host_adapters/generic.py +132 -0
- package/plugins/vod-devkit/vod_mcp/host_adapters/hermes.py +76 -0
- package/plugins/vod-devkit/vod_mcp/host_adapters/opencode.py +52 -0
- package/plugins/vod-devkit/vod_mcp/hosts.py +20 -0
- package/plugins/vod-devkit/vod_mcp/packs.py +3 -1
- package/plugins/vod-devkit/vod_mcp/payload.py +174 -0
- package/plugins/vod-devkit/vod_mcp/server.py +13 -1
- package/plugins/vod-devkit/vod_mcp/tools.py +385 -46
- package/plugins/vod-devkit/vod_mcp/update_check.py +31 -3
- package/skills/vod-core/SKILL.md +12 -4
- package/skills/vod-core/references/acceptance-criteria.md +9 -0
- package/skills/vod-core/references/verification-method.md +29 -0
- package/skills/vod-feedback-collect/SKILL.md +57 -11
- package/skills/vod-feedback-collect/references/acceptance-criteria.md +28 -0
- package/skills/vod-feedback-collect/references/verification-method.md +31 -0
- package/skills/vod-problem-classification-rules/SKILL.md +3 -1
- package/skills/vod-scoring-rules/SKILL.md +22 -1
- package/vod_mcp/__init__.py +1 -1
- package/vod_mcp/attribution.py +378 -0
- package/vod_mcp/host_adapters/__init__.py +26 -0
- package/vod_mcp/host_adapters/__pycache__/__init__.cpython-314.pyc +0 -0
- package/vod_mcp/host_adapters/__pycache__/base.cpython-314.pyc +0 -0
- package/vod_mcp/host_adapters/__pycache__/codearts.cpython-314.pyc +0 -0
- package/vod_mcp/host_adapters/__pycache__/codex.cpython-314.pyc +0 -0
- package/vod_mcp/host_adapters/__pycache__/dsh.cpython-314.pyc +0 -0
- package/vod_mcp/host_adapters/__pycache__/generic.cpython-314.pyc +0 -0
- package/vod_mcp/host_adapters/__pycache__/hermes.cpython-314.pyc +0 -0
- package/vod_mcp/host_adapters/__pycache__/opencode.cpython-314.pyc +0 -0
- package/vod_mcp/host_adapters/base.py +73 -0
- package/vod_mcp/host_adapters/codearts.py +57 -0
- package/vod_mcp/host_adapters/codex.py +209 -0
- package/vod_mcp/host_adapters/dsh.py +176 -0
- package/vod_mcp/host_adapters/generic.py +132 -0
- package/vod_mcp/host_adapters/hermes.py +76 -0
- package/vod_mcp/host_adapters/opencode.py +52 -0
- package/vod_mcp/hosts.py +20 -0
- package/vod_mcp/packs.py +3 -1
- package/vod_mcp/payload.py +174 -0
- package/vod_mcp/server.py +13 -1
- package/vod_mcp/tools.py +385 -46
- package/vod_mcp/update_check.py +31 -3
package/CHANGELOG.md
CHANGED
|
@@ -275,3 +275,30 @@
|
|
|
275
275
|
- 061ca39 docs: dsh 插件接入安装手册(三条安装路径/配置/验证/公网反代/FAQ)
|
|
276
276
|
- dbfb31c chore(release): golden 随 v0.4.4 重录(仅 version 字段,人工过目合规)
|
|
277
277
|
|
|
278
|
+
|
|
279
|
+
## v0.5.1(2026-11-12)
|
|
280
|
+
|
|
281
|
+
- 61577bc fix(归因): 没有产品就不提交——删掉 host_default 猜路径 + 名录外回答改为再确认
|
|
282
|
+
- c47e504 feat(采集): 缺产品必须问一次,不许裸提交 UNKNOWN(D-product-ask-1)
|
|
283
|
+
- a50877f fix(归因/分类): 补 1bb9f67 的两个真机缺陷(全大写缩写误归 + 分类取值抛异常)
|
|
284
|
+
- 1bb9f67 refactor(contract): 适配后端外部接口契约收紧——别名本地派生 + 分类按产品取
|
|
285
|
+
- e43e970 fix(codex): 清理旧一代 AGENTS.md 注入——consent 红线的真实破口(真机语料实证)
|
|
286
|
+
- eb5b3e8 fix(doctor): 路由插件副本漂移检查(真机实锤)
|
|
287
|
+
- d703b24 feat(反例集): 原话逐字 + tags 值域(S101/S102,CodeArts 真机实锤)
|
|
288
|
+
- 0b68cb5 feat(技能): 征询话术「给范围不给结论」边界 + 门禁(负责人拍板 A)
|
|
289
|
+
- 11ff813 fix(指路文案): instructions 里归因口径回正 + 文案漂移门禁
|
|
290
|
+
- ae9e163 chore(构建): 重烧 build-info 对齐 head 09eeb47(双副本一致)
|
|
291
|
+
- 09eeb47 feat(宿主): 安装载荷固化 + CodeArts Agent 适配 + 多宿主安装记录(D-payload-1/D-codeartsdoer-1/D-installs-1)
|
|
292
|
+
- 8ffa7fd chore(卫生): 停止跟踪 E2E 运行日志,忽略日志与本地 tgz
|
|
293
|
+
- 72208b4 refactor(宿主): 宿主适配分层 + 通用 MCP 写入器(D-hosts-1,A+B)
|
|
294
|
+
- b4bb21f feat(分类/规则): tags 白名单校验 + 等级定义入评分技能(D-tags-1)
|
|
295
|
+
- 1daa437 chore(技能): 结构/触发词门禁 + 技能级验证文档(对标 huaweicloud-skills,D-skill-structure-1)
|
|
296
|
+
- c8b7b94 docs(归因): 撤回 P6(无消费者);度量改用零 schema 变更方案
|
|
297
|
+
- 1b169f0 docs(归因): 撤回 P5 productKeywords(负责人否),P6 提前为度量前置
|
|
298
|
+
- 3fa6dc8 docs(归因): A 维持 + P5/P6 排序 + B 的复审触发条件(负责人 2026-11-11 拍板)
|
|
299
|
+
- 2a1c387 feat(安装): 远程 attach 模式——MCP 单独部署,宿主一条命令指过去(D-attach-1)
|
|
300
|
+
- 0292248 chore(更新链): skip-version + registry 状态对账 + 类型门禁(D-devtoolchain-7)
|
|
301
|
+
- 4d4e6cb chore(治理): 结构守卫 + 花名册显式清单 + 规则真源对账(D-devtoolchain-6)
|
|
302
|
+
- e613449 feat(dsh): 归因与 MCP 侧同口径——运行期字面解析 + 记忆 + 先验 + 弃权(D-attrib-B)
|
|
303
|
+
- 9b785dd feat(归因): 运行期字面解析取代安装绑定——名录别名 + 短 TTL 记忆 + 弃权(D-attrib-B)
|
|
304
|
+
|
package/QUICKSTART.md
CHANGED
|
@@ -20,7 +20,7 @@
|
|
|
20
20
|
|
|
21
21
|
```bash
|
|
22
22
|
git clone <repo-url> vod-devkit && cd vod-devkit
|
|
23
|
-
bin/vod-devkit install --target hermes --preset collect --product <你的产品>
|
|
23
|
+
bin/vod-devkit install --target hermes --preset collect --product <你的产品> # --product 可选先验
|
|
24
24
|
# 重启 Hermes 会话,工具以 mcp_vod_devkit_* 出现
|
|
25
25
|
```
|
|
26
26
|
|
package/README.en.md
CHANGED
|
@@ -1,76 +1,209 @@
|
|
|
1
1
|
# vod-devkit (English)
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
- **
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
- **
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
3
|
+
[中文](README.md) | English
|
|
4
|
+
|
|
5
|
+
Deliver your AI-agent users' **verbatim feedback** into the VOD (Voice of
|
|
6
|
+
Developer) intake channel: MCP server + skills + declarative guardrails.
|
|
7
|
+
Collection only — analysis and operations live in the vod-system frontend.
|
|
8
|
+
|
|
9
|
+
Three rules that matter more than the skeleton:
|
|
10
|
+
|
|
11
|
+
- **Collect only**: the plugin's single write action is an engine HTTP call
|
|
12
|
+
(`POST /external/voices`). Persistence, quotas, audit and identity checks all
|
|
13
|
+
live server-side; there is no database code path in this repo.
|
|
14
|
+
- **Identity travels with the request**: stdio uses the local anonymous token;
|
|
15
|
+
the remote face reads Bearer from the request header and **never mints an
|
|
16
|
+
identity** (missing key = reject).
|
|
17
|
+
- **Attribution never asks the user**: the product is parsed from the user's own
|
|
18
|
+
words against the engine catalog aliases; only an unambiguous single hit is
|
|
19
|
+
accepted, multiple hits become UNKNOWN for a human to resolve. `--product` at
|
|
20
|
+
install time is an optional prior only.
|
|
21
|
+
|
|
22
|
+
## Prerequisites
|
|
23
|
+
|
|
24
|
+
| Dependency | Requirement | Notes |
|
|
25
|
+
|---|---|---|
|
|
26
|
+
| Node | >= 18 | `npx` bootstrap; the dsh host needs Node 24.9+ per its own docs |
|
|
27
|
+
| Python | >= 3.10 | installer + MCP server; point `VOD_PYTHON` at an interpreter if needed |
|
|
28
|
+
| Host | hermes / opencode / codeartsdoer / codex / dsh | `--target auto` probes, or name one explicitly |
|
|
29
|
+
| Network | reachable VOD engine | defaults to `https://vod-dev.topxtopx.com`, override with `--java-api-base` |
|
|
30
|
+
|
|
31
|
+
The remote face additionally needs the official MCP SDK:
|
|
32
|
+
`pip install 'vod-devkit[remote]'` (stdio has zero third-party deps).
|
|
33
|
+
|
|
34
|
+
## Quick start
|
|
35
|
+
|
|
36
|
+
```bash
|
|
37
|
+
npx -y vod-devkit@latest install --target auto
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
**Restart the session** afterwards (hosts read MCP config at startup), then:
|
|
41
|
+
|
|
42
|
+
```bash
|
|
43
|
+
npx -y vod-devkit@latest doctor # config + skill roster + build-info
|
|
44
|
+
npx -y vod-devkit@latest status # install-manifest: version / source / host / transport
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
`--product <name>` is an optional prior (used only when there is no literal
|
|
48
|
+
evidence and no memory); when given it is validated against the catalog and a
|
|
49
|
+
typo exits 2.
|
|
50
|
+
|
|
51
|
+
## Per-host install
|
|
52
|
+
|
|
53
|
+
`install` takes `--target`; `doctor` / `status` / `verify` / `update` /
|
|
54
|
+
`uninstall` operate on the installed instance (they read `install-manifest`) and
|
|
55
|
+
take no target.
|
|
56
|
+
|
|
57
|
+
### Hermes
|
|
58
|
+
|
|
59
|
+
```bash
|
|
60
|
+
npx -y vod-devkit@latest install --target hermes
|
|
61
|
+
npx -y vod-devkit@latest doctor && npx -y vod-devkit@latest status
|
|
62
|
+
npx -y vod-devkit@latest uninstall # removes the managed MCP entry only
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
Writes `hermes mcp add` into `~/.hermes/config.yaml` plus
|
|
66
|
+
`~/.hermes/mcp/vod-devkit.json`; skills go to `~/.hermes/skills/devops/vod-devkit`.
|
|
67
|
+
|
|
68
|
+
### OpenCode
|
|
69
|
+
|
|
70
|
+
```bash
|
|
71
|
+
npx -y vod-devkit@latest install --target opencode
|
|
72
|
+
npx -y vod-devkit@latest uninstall
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
Merges `mcp.vod-devkit` into `~/.config/opencode/opencode.json` (your provider
|
|
76
|
+
keys are preserved); skills go to `~/.config/opencode/skills`. Uninstall removes
|
|
77
|
+
only our entry and the skill dirs we installed.
|
|
78
|
+
|
|
79
|
+
### Codex
|
|
27
80
|
|
|
28
81
|
```bash
|
|
29
|
-
|
|
30
|
-
npx
|
|
82
|
+
npx -y vod-devkit@latest install --target codex
|
|
83
|
+
npx -y vod-devkit@latest uninstall # removes the native plugin, keeps config.toml
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
Uses the codex native plugin path (`codex plugin marketplace add` + `plugin add`),
|
|
87
|
+
with `.mcp.json` running `vod-devkit serve` over stdio. If the collection circuit
|
|
88
|
+
breaker is tripped, install refuses the collect pack until `--ack-suspension`.
|
|
31
89
|
|
|
32
|
-
|
|
33
|
-
/plugin marketplace add yangaiwu/vod-devkit
|
|
90
|
+
### CodeArts Agent (codeartsdoer)
|
|
34
91
|
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
92
|
+
CodeArts Agent is an OpenCode fork (`SCENARIO=codeartsdoer`, config at
|
|
93
|
+
`~/.codeartsdoer/codearts_cli.json`), so the MCP entry uses the opencode schema:
|
|
94
|
+
`{"type":"local","command":[...],"enabled":true,"environment":{...}}`. Skills go to
|
|
95
|
+
`~/.codeartsdoer/skills`. `doctor` runs `codearts mcp list` as a smoke check.
|
|
96
|
+
Do **not** write `~/.codeartsdoer/mcp/mcp_settings.json` — that path is project-level;
|
|
97
|
+
the user-level mcp_settings lives under `~/.config/opencode/mcp/`.
|
|
98
|
+
|
|
99
|
+
### DeepSeek Harness (dsh)
|
|
100
|
+
|
|
101
|
+
```bash
|
|
102
|
+
npx -y vod-devkit@latest install --target dsh --profile <name>
|
|
39
103
|
```
|
|
40
104
|
|
|
41
|
-
|
|
105
|
+
`--profile` is required; installs the `dsh-vod-devkit` shell package and writes a
|
|
106
|
+
profile `cordis.patch.yml` override. The dsh shell does not speak MCP:
|
|
107
|
+
`--mcp-url` / `--skills-only` exit 2.
|
|
108
|
+
|
|
109
|
+
## Other MCP hosts (generic layer)
|
|
110
|
+
|
|
111
|
+
Hosts without a dedicated adapter are no longer "unsupported":
|
|
42
112
|
|
|
43
113
|
```bash
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
#
|
|
114
|
+
# Known config shapes (Claude Code / Cursor / Windsurf / Cline):
|
|
115
|
+
npx -y vod-devkit@latest install --target generic --mcp-config ~/.claude.json
|
|
116
|
+
|
|
117
|
+
# No path given: print a paste-ready snippet, write nothing
|
|
118
|
+
npx -y vod-devkit@latest install --target generic
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
- Surgical merge: only `mcpServers.vod-devkit` is written, other servers and user
|
|
122
|
+
keys are preserved, first touch leaves a `.bak`
|
|
123
|
+
- Invalid JSON / non-object top level → refuse and leave bytes untouched
|
|
124
|
+
- `--target auto` auto-picks the generic path only when exactly one known host is
|
|
125
|
+
detected; otherwise it asks you to be explicit
|
|
126
|
+
- The generic layer installs the MCP entry only (skill dirs are host-private)
|
|
127
|
+
|
|
128
|
+
Manual snippet (replace `<repo>`):
|
|
129
|
+
|
|
130
|
+
```jsonc
|
|
131
|
+
{ "mcpServers": { "vod-devkit": {
|
|
132
|
+
"command": "python3", "args": ["<repo>/vod_mcp/server.py"] } } }
|
|
48
133
|
```
|
|
49
134
|
|
|
50
|
-
|
|
51
|
-
|
|
135
|
+
## Remote deployment: standalone MCP + host attach
|
|
136
|
+
|
|
137
|
+
One endpoint serves many hosts; identity comes from request headers:
|
|
52
138
|
|
|
53
|
-
|
|
54
|
-
|
|
139
|
+
```bash
|
|
140
|
+
pip install 'vod-devkit[remote]'
|
|
141
|
+
vod-devkit serve --transport remote --port 9528 --host 127.0.0.1 # put TLS/identity in front
|
|
142
|
+
```
|
|
55
143
|
|
|
56
|
-
|
|
144
|
+
Attach a host (token required — the remote face never mints anonymous identity):
|
|
145
|
+
|
|
146
|
+
```bash
|
|
147
|
+
npx -y vod-devkit@latest install --target hermes --mcp-url https://<gateway>/mcp --mcp-token <key>
|
|
148
|
+
npx -y vod-devkit@latest install --target opencode --mcp-url https://<gateway>/mcp --mcp-token <key>
|
|
149
|
+
npx -y vod-devkit@latest install --target codex --mcp-url https://<gateway>/mcp --mcp-token <key>
|
|
150
|
+
```
|
|
57
151
|
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
-
|
|
63
|
-
|
|
64
|
-
|
|
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
|
|
154
|
+
remote face withholds machine-local tools (`vod_draft_voices`,
|
|
155
|
+
`vod_commit_voices`, `vod_list_submitted`) — a shared process has no "local".
|
|
156
|
+
There is no built-in auth: bind to loopback and front it with TLS + identity.
|
|
157
|
+
|
|
158
|
+
## Telemetry and data
|
|
159
|
+
|
|
160
|
+
- **Collected**: nothing. No telemetry, no analytics, no usage counters.
|
|
161
|
+
- **Not collected**: everything. Feedback content goes only to the engine you
|
|
162
|
+
configure, and only after the user agrees.
|
|
163
|
+
- **Transport**: stdio calls the engine directly; the remote face identifies the
|
|
164
|
+
caller from the request header, nothing is stored server-side.
|
|
165
|
+
- **How to opt out**: nothing to opt out of. To disconnect entirely, `uninstall`
|
|
166
|
+
or point `--java-api-base` at your own instance.
|
|
167
|
+
|
|
168
|
+
## Tool surface (single source: contract/tools.schema.json)
|
|
169
|
+
|
|
170
|
+
| Tool | pack | Type | Guardrail |
|
|
171
|
+
|---|---|---|---|
|
|
172
|
+
| vod_submit_voices | collect | write | per-batch confirm; batch <= 50; Java `/external/voices` |
|
|
173
|
+
| vod_draft_voices | collect | write (staging) | local cap 10 / TTL 600s; verbatim echo; no upstream call |
|
|
174
|
+
| vod_commit_voices | collect | write | one-time token + payloadSha256; reuses submit chain |
|
|
175
|
+
| vod_list_submitted | collect | read | local ledger (cap 200) |
|
|
176
|
+
| vod_devkit_info | core | read | version / commitSHA / host clientInfo |
|
|
177
|
+
| vod_auth_status | core | read | fingerprint self-check + 3-step guidance |
|
|
178
|
+
| vod_check_update | core | read | npm latest (24h cache, silent on failure); never self-upgrades |
|
|
179
|
+
| vod_list_skills / vod_retrieve_skill | knowledge | read | rule-skill disclosure (pack filtering refuses with a fix hint) |
|
|
180
|
+
|
|
181
|
+
Security: `safety/policy.json` denies DB-direct intent and credential reads;
|
|
182
|
+
text rules only inspect structural fields, so feedback quoting a secret is not
|
|
183
|
+
misfired (quoting vs reading are different acts).
|
|
65
184
|
|
|
66
185
|
## Quality
|
|
67
186
|
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
187
|
+
```bash
|
|
188
|
+
python3 -m pytest tests/ -q # full: unit + guardrails + packs + installer matrix + real-HTTP + stdio
|
|
189
|
+
python3 -m pyflakes vod_mcp/*.py tests/*.py scripts/*.py bin/vod-devkit
|
|
190
|
+
python3 -m mypy # scope in pyproject [tool.mypy]
|
|
191
|
+
python3 scripts/secret_scan.py
|
|
192
|
+
python3 scripts/sync_case_roster.py --check
|
|
193
|
+
python3 scripts/rules_provenance.py
|
|
194
|
+
```
|
|
195
|
+
|
|
196
|
+
Gates: pre-push hook (pytest + pyflakes + secret_scan) + GitHub Actions on the
|
|
197
|
+
mirror + byte-identical package mirrors + description budget + install-manifest
|
|
198
|
+
roster checks + outward-doc claim checks. Counts are never hand-written into
|
|
199
|
+
docs; measure them.
|
|
200
|
+
|
|
201
|
+
## Docs
|
|
202
|
+
|
|
203
|
+
docs/proposal.md · docs/design.md · docs/scheme-overview.md ·
|
|
204
|
+
docs/safety-model.md · docs/decisions.md · docs/rules-provenance.json ·
|
|
205
|
+
QUICKSTART.md · INSTALL.md · CONTRIBUTING.md · SECURITY.md
|
|
206
|
+
|
|
207
|
+
## License
|
|
73
208
|
|
|
74
|
-
|
|
75
|
-
SECURITY.md · SUPPORT.md · CODE_OF_CONDUCT.md · NOTICE · docs/proposal.md ·
|
|
76
|
-
docs/design.md · docs/scheme-overview.md (one-pager) · CHANGELOG.md
|
|
209
|
+
MIT (see LICENSE.txt). Third-party notices in NOTICE.
|
package/README.md
CHANGED
|
@@ -2,64 +2,159 @@
|
|
|
2
2
|
|
|
3
3
|
[English](README.en.md) | 中文
|
|
4
4
|
|
|
5
|
-
VOD
|
|
6
|
-
|
|
7
|
-
vod-system 前端,不在本插件。对齐 huaweicloud-devkit v2 的工程骨架(installer /
|
|
8
|
-
MCP / skills / packs / policy),面向"服务面插件"的护栏更保守。
|
|
5
|
+
把 **AI agent 产品的用户反馈**原话送进 VOD(Voice of Developer)囤积区:MCP server +
|
|
6
|
+
技能 + 声明式护栏。纯采集形态——分析与运营归 vod-system 前端,不在本插件。
|
|
9
7
|
|
|
10
|
-
|
|
11
|
-
- 贡献:CONTRIBUTING.md | 安全策略与边界:SECURITY.md
|
|
12
|
-
- 支持:SUPPORT.md | 行为准则:CODE_OF_CONDUCT.md | 第三方素材:NOTICE
|
|
13
|
-
- 真源纪律:领域规则技能由 scripts/vendor_rules.py 从 VodTeam/VOD-Project
|
|
14
|
-
按 commitSHA 锁定拉取(规则只改一处)
|
|
15
|
-
- 对账主键:引擎任务 taskId;插件来源主键=commitSHA(build-info.json 构建烧录,
|
|
16
|
-
install-manifest.json 安装落盘,`vod-devkit verify` 到 origin 核对 commit)
|
|
8
|
+
三条纪律(比骨架更重要):
|
|
17
9
|
|
|
18
|
-
|
|
10
|
+
- **只采集**:插件的唯一写动作是调用引擎 HTTP API(`POST /external/voices`)。
|
|
11
|
+
落库、配额、审计、身份判定全在服务端;本仓没有任何数据库连接代码路径。
|
|
12
|
+
- **身份随请求走**:stdio 面走本机匿名令牌;远程面只从请求头取 Bearer,缺 key
|
|
13
|
+
直接拒绝、**不代签匿名令牌**(插件只搬运身份,不产生身份)。
|
|
14
|
+
- **归因不问用户**:产品由插件从用户原话字面解析(引擎名录别名),唯一命中才采信;
|
|
15
|
+
多产品命中=歧义 → 落 UNKNOWN 由运营判。安装时的 `--product` 只是可选先验。
|
|
19
16
|
|
|
20
|
-
|
|
17
|
+
## 前置条件
|
|
18
|
+
|
|
19
|
+
| 依赖 | 要求 | 说明 |
|
|
20
|
+
|---|---|---|
|
|
21
|
+
| Node | >= 18 | `npx` 引导器;dsh 宿主请按其官方要求(Node 24.9+) |
|
|
22
|
+
| Python | >= 3.10 | 安装器与 MCP server;可用 `VOD_PYTHON` 指定解释器 |
|
|
23
|
+
| 宿主 | hermes / opencode / codeartsdoer / codex / dsh 任一 | 用 `--target auto` 探测,或显式指定 |
|
|
24
|
+
| 网络 | 可达你的 VOD 引擎 | 缺省 `https://vod-dev.topxtopx.com`,可 `--java-api-base` 覆盖 |
|
|
25
|
+
|
|
26
|
+
远程面额外需要官方 MCP SDK:`pip install 'vod-devkit[remote]'`(stdio 形态零第三方依赖)。
|
|
27
|
+
|
|
28
|
+
## 快速开始
|
|
29
|
+
|
|
30
|
+
```bash
|
|
31
|
+
npx -y vod-devkit@latest install --target auto
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
装完**重启会话**才生效(宿主在启动时读取 MCP 配置)。随后自检:
|
|
35
|
+
|
|
36
|
+
```bash
|
|
37
|
+
npx -y vod-devkit@latest doctor # 配置 + 技能名册 + build-info 三查(针对已装实例)
|
|
38
|
+
npx -y vod-devkit@latest status # install-manifest:版本 / 来源 / 宿主 / 传输形态
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
`--product <产品名>` 是可选先验(仅在无字面证据且无记忆时兜底);给了就会做名录
|
|
42
|
+
硬校验,拼错直接 `exit 2`,不给也能装。
|
|
43
|
+
|
|
44
|
+
## 按宿主安装
|
|
45
|
+
|
|
46
|
+
五个宿主的装法一致(`install` 带 `--target`),差异在配置落点与注意点。
|
|
47
|
+
`doctor` / `status` / `verify` / `update` / `uninstall` 都是**针对已装实例**
|
|
48
|
+
(读 install-manifest),不带 `--target`。
|
|
49
|
+
|
|
50
|
+
### Hermes
|
|
51
|
+
|
|
52
|
+
```bash
|
|
53
|
+
npx -y vod-devkit@latest install --target hermes
|
|
54
|
+
# 验证 / 更新 / 卸载
|
|
55
|
+
npx -y vod-devkit@latest doctor
|
|
56
|
+
npx -y vod-devkit@latest status
|
|
57
|
+
npx -y vod-devkit@latest install --target hermes # 更新=幂等重装
|
|
58
|
+
npx -y vod-devkit@latest uninstall
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
- 落点:`hermes mcp add` 写 `~/.hermes/config.yaml`,另存 `~/.hermes/mcp/vod-devkit.json`;
|
|
62
|
+
技能装到 `~/.hermes/skills/devops/vod-devkit`
|
|
63
|
+
- 卸载只摘托管的 MCP 条目(走 `hermes mcp remove`),不动你的其它 server
|
|
64
|
+
|
|
65
|
+
### OpenCode
|
|
66
|
+
|
|
67
|
+
```bash
|
|
68
|
+
npx -y vod-devkit@latest install --target opencode
|
|
69
|
+
npx -y vod-devkit@latest doctor && npx -y vod-devkit@latest status
|
|
70
|
+
npx -y vod-devkit@latest uninstall
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
- 落点:`~/.config/opencode/opencode.json` 的 `mcp.vod-devkit`(无损合并,保留你的
|
|
74
|
+
provider 等既有键);技能装到 `~/.config/opencode/skills`
|
|
75
|
+
- **卸载只摘 `mcp.vod-devkit` 与本次装进去的技能目录**——共享配置文件与其它插件的
|
|
76
|
+
技能永不整文件/整目录删除
|
|
77
|
+
|
|
78
|
+
### Codex
|
|
79
|
+
|
|
80
|
+
```bash
|
|
81
|
+
npx -y vod-devkit@latest install --target codex
|
|
82
|
+
npx -y vod-devkit@latest doctor
|
|
83
|
+
npx -y vod-devkit@latest uninstall # 摘原生插件,不删你的 config.toml
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
- 形态:走 codex 原生插件(`codex plugin marketplace add` + `plugin add`),技能随插件
|
|
87
|
+
渐进加载;`.mcp.json` 用 `vod-devkit serve` 拉起 stdio
|
|
88
|
+
- 采集熔断:未确认提交累计触发后 install 会拒绝装 collect,恢复需
|
|
89
|
+
`--ack-suspension`(审计日志落在 `~/.codex/`)
|
|
90
|
+
|
|
91
|
+
### CodeArts Agent(codeartsdoer)
|
|
21
92
|
|
|
22
93
|
```bash
|
|
23
|
-
|
|
24
|
-
npx
|
|
94
|
+
npx -y vod-devkit@latest install --target codeartsdoer
|
|
95
|
+
npx -y vod-devkit@latest doctor # 会用 `codearts mcp list` 冒烟一次
|
|
96
|
+
npx -y vod-devkit@latest uninstall # 只摘 mcp.vod-devkit,provider/model 保留
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
- CodeArts Agent 是 OpenCode 分支(`SCENARIO=codeartsdoer`,配置在
|
|
100
|
+
`~/.codeartsdoer/codearts_cli.json`),MCP 段同 opencode schema;技能装到
|
|
101
|
+
`~/.codeartsdoer/skills`
|
|
102
|
+
- 实测口径:写入后 `codearts mcp list` 显示 `✓ vod-devkit connected`
|
|
103
|
+
- **不要**写 `~/.codeartsdoer/mcp/mcp_settings.json`——那是项目级路径;用户级
|
|
104
|
+
mcp_settings 读的是 `~/.config/opencode/mcp/`
|
|
25
105
|
|
|
26
|
-
|
|
27
|
-
/plugin marketplace add yangaiwu/vod-devkit
|
|
106
|
+
### DeepSeek Harness (dsh)
|
|
28
107
|
|
|
29
|
-
|
|
30
|
-
|
|
108
|
+
```bash
|
|
109
|
+
npx -y vod-devkit@latest install --target dsh --profile <profile名>
|
|
110
|
+
npx -y vod-devkit@latest doctor
|
|
111
|
+
npx -y vod-devkit@latest uninstall
|
|
31
112
|
```
|
|
32
113
|
|
|
33
|
-
|
|
34
|
-
|
|
114
|
+
- `--profile` 必填(profile 名 = `ls ~/.dsh/profiles` 的目录名);装的是壳包
|
|
115
|
+
`dsh-vod-devkit`(npm 同名),配置幂等写进 profile 的 `cordis.patch.yml`
|
|
116
|
+
- **dsh 壳不走 MCP**:`--mcp-url` / `--skills-only` 对它显式报错;远程面模式不覆盖 dsh
|
|
117
|
+
- 卸载会摘插件并从 patch 移除本插件的 config 块,不删其它插件段
|
|
118
|
+
|
|
119
|
+
## 其它 MCP 宿主(通用层)
|
|
35
120
|
|
|
36
|
-
|
|
121
|
+
没有专属适配模块的宿主不再"不支持"——通用层负责写配置或给片段:
|
|
37
122
|
|
|
38
123
|
```bash
|
|
39
|
-
#
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
bin/vod-devkit status # 看 install-manifest(版本+来源+宿主+packs)
|
|
46
|
-
bin/vod-devkit verify # commitSHA 到 origin 核验(篡改/改写告警)
|
|
47
|
-
bin/vod-devkit doctor # 配置+skills+build-info 三查
|
|
48
|
-
bin/vod-devkit uninstall
|
|
49
|
-
|
|
50
|
-
# 直接以 MCP server 运行(任意 MCP 客户端可连)
|
|
51
|
-
python3 -m vod_mcp.server # stdio,JSON-RPC
|
|
52
|
-
VOD_PACKS=core,collect python3 -m vod_mcp.server # packs 裁剪
|
|
124
|
+
# 已知形态(Claude Code / Cursor / Windsurf / Cline):合并 mcpServers 条目
|
|
125
|
+
npx -y vod-devkit@latest install --target generic --mcp-config ~/.claude.json
|
|
126
|
+
npx -y vod-devkit@latest install --target generic --mcp-config ~/.cursor/mcp.json
|
|
127
|
+
|
|
128
|
+
# 不指定路径:只打印可粘贴片段,不写任何文件
|
|
129
|
+
npx -y vod-devkit@latest install --target generic
|
|
53
130
|
```
|
|
54
131
|
|
|
55
|
-
|
|
132
|
+
- **外科式合并**:只写 `mcpServers.vod-devkit`,其它 server 与用户自有键原样保留;
|
|
133
|
+
首次改动前落 `.bak`
|
|
134
|
+
- 文件不是合法 JSON / 顶层不是对象 → 报错退出、字节不动(宁可不装不可装错)
|
|
135
|
+
- `--target auto` 在只探测到一个通用宿主时自动走通用写入;多个/零个要求显式指定
|
|
136
|
+
- 通用层只装 MCP 条目,不装技能(技能目录是宿主私有的;要话术层用 hermes/opencode/codex)
|
|
56
137
|
|
|
57
|
-
|
|
58
|
-
|
|
138
|
+
手写片段(把 `<repo>` 换成本仓绝对路径):
|
|
139
|
+
|
|
140
|
+
```jsonc
|
|
141
|
+
{ "mcpServers": { "vod-devkit": {
|
|
142
|
+
"command": "python3", "args": ["<repo>/vod_mcp/server.py"] } } }
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
MCP 已由别处注册、只想装技能话术时:
|
|
59
146
|
|
|
60
147
|
```bash
|
|
61
|
-
|
|
62
|
-
|
|
148
|
+
npx -y vod-devkit@latest install --target <hermes|opencode|codex> --skills-only
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
## 远程部署:MCP 单独部署 + 宿主 attach
|
|
152
|
+
|
|
153
|
+
一个远程端点服务多个宿主;身份随请求头走,不落服务器:
|
|
154
|
+
|
|
155
|
+
```bash
|
|
156
|
+
pip install 'vod-devkit[remote]'
|
|
157
|
+
vod-devkit serve --transport remote --port 9528 --host 127.0.0.1 # 前面需自建 TLS 反代
|
|
63
158
|
```
|
|
64
159
|
|
|
65
160
|
```jsonc
|
|
@@ -67,55 +162,79 @@ vod-devkit serve --transport remote # 默认 http://127.0.0.1:9528
|
|
|
67
162
|
"type": "remote", "url": "http://localhost:9528", "enabled": true } } }
|
|
68
163
|
```
|
|
69
164
|
|
|
165
|
+
宿主 attach(token 必填——远程面不代签匿名身份,缺 key 会被拒装 `exit 2`):
|
|
166
|
+
|
|
167
|
+
```bash
|
|
168
|
+
npx -y vod-devkit@latest install --target hermes --mcp-url https://<网关>/mcp --mcp-token <key>
|
|
169
|
+
npx -y vod-devkit@latest install --target opencode --mcp-url https://<网关>/mcp --mcp-token <key>
|
|
170
|
+
npx -y vod-devkit@latest install --target codex --mcp-url https://<网关>/mcp --mcp-token <key>
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
写入前先探活:`initialize` + `tools/list` 必须等于远程面工具集,不符即拒装且
|
|
174
|
+
**不写任何配置**;`doctor` 复查端点与工具面。远程面与 stdio 面的实质差别:
|
|
175
|
+
|
|
176
|
+
- **工具面收窄**:草稿/本机账本类工具(`vod_draft_voices` / `vod_commit_voices` /
|
|
177
|
+
`vod_list_submitted`)不在远程面——它们写"本机状态",共享进程没有"本机"
|
|
178
|
+
- token 承载:hermes 走 env `MCP_VOD_DEVKIT_API_KEY`(配置里只留 `${...}` 引用);
|
|
179
|
+
opencode 写在 `headers`(注意文件权限);codex 走 `VOD_MCP_TOKEN`
|
|
180
|
+
- **无内建鉴权**:本进程不校验身份,默认只绑回环;对外必须反代 TLS + 身份校验
|
|
181
|
+
- 技能自带传输面自适应:没有草稿工具 → 单发 + 回显,不承诺"草稿/两步";没有本机
|
|
182
|
+
账本工具 → 不承诺查询历史反馈
|
|
183
|
+
|
|
70
184
|
端口被占用用 `--port <port>`(同步改 url);`--host 0.0.0.0` 可开 LAN 访问。
|
|
71
185
|
|
|
72
|
-
|
|
186
|
+
## 遥测与数据
|
|
73
187
|
|
|
74
|
-
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
-
|
|
81
|
-
|
|
82
|
-
- **无内建鉴权**:本进程不校验身份,默认只绑回环。要对外必须在反代上加 TLS 与
|
|
83
|
-
身份校验——不要把它匿名暴露到公网。
|
|
188
|
+
- **收集什么**:无。本插件不上报任何使用数据——没有遥测、没有埋点、没有用量统计,
|
|
189
|
+
技能加载与工具调用都不回传。
|
|
190
|
+
- **不收集什么**:全部。反馈内容只在用户明确同意后发往**你配置的引擎地址**;插件
|
|
191
|
+
不自建任何回传通道。
|
|
192
|
+
- **传输路径**:stdio 面由宿主进程直连引擎;远程面由请求头里的 key 标识调用方,
|
|
193
|
+
身份不落服务器。
|
|
194
|
+
- **如何关闭**:无需关闭(本就没有)。若要不连引擎:`uninstall`,或把
|
|
195
|
+
`--java-api-base` 指向你自己的实例。
|
|
84
196
|
|
|
85
197
|
## 工具面(契约唯一事实源:contract/tools.schema.json)
|
|
86
198
|
|
|
87
199
|
| 工具 | pack | 类型 | 护栏 |
|
|
88
200
|
|---|---|---|---|
|
|
89
|
-
| vod_submit_voices | collect | 写 | confirm 逐次同意 +
|
|
90
|
-
| vod_draft_voices | collect | 写(暂存) | 本机暂存 cap10/TTL600s
|
|
201
|
+
| vod_submit_voices | collect | 写 | confirm 逐次同意 + 单批<=50;走 Java `/external/voices` |
|
|
202
|
+
| vod_draft_voices | collect | 写(暂存) | 本机暂存 cap10/TTL600s,逐字回显;不触上游 |
|
|
91
203
|
| vod_commit_voices | collect | 写 | 一次性令牌 + payloadSha256 防调包,内部复用提交链 |
|
|
92
204
|
| vod_list_submitted | collect | 只读 | 本机提交账本(cap 200)——agent 替用户对账进度 |
|
|
93
|
-
| vod_devkit_info | core | 只读 |
|
|
94
|
-
| vod_auth_status | core | 只读 | key
|
|
95
|
-
| vod_check_update | core | 只读 |
|
|
96
|
-
| vod_list_skills / vod_retrieve_skill | knowledge | 只读 |
|
|
97
|
-
|
|
98
|
-
安全:deny 拦 DB 直连意图与凭据读取(safety/policy.json 声明式规则;
|
|
99
|
-
文本规则只扫结构性字段,不误杀反馈内容里的凭据引用)。
|
|
100
|
-
|
|
101
|
-
测试:pytest + node:test 全量(单元+护栏+packs+安装器矩阵四宿主+真进程 stdio 回环+
|
|
102
|
-
**协议级真 HTTP 服务器**锁定认证头/双后端路径——E1/E2 的永久回归门)。
|
|
103
|
-
用例数以本地实测为准(`python3 -m pytest tests/ -q`),文档不手写计数——
|
|
104
|
-
手写计数必然漂移,tests/test_claims.py 会拦。决策闭环见 docs/decisions.md。
|
|
205
|
+
| vod_devkit_info | core | 只读 | 版本 / commitSHA / 宿主 clientInfo |
|
|
206
|
+
| vod_auth_status | core | 只读 | key 指纹化自检 + 三步引导(无 key 可跑) |
|
|
207
|
+
| vod_check_update | core | 只读 | registry latest(24h 缓存 / 失败静默);只提醒不升级 |
|
|
208
|
+
| vod_list_skills / vod_retrieve_skill | knowledge | 只读 | 领域规则技能披露(pack 裁剪即拒绝并给恢复命令) |
|
|
105
209
|
|
|
106
|
-
|
|
210
|
+
安全:`safety/policy.json` 声明式规则拦 DB 直连意图与凭据读取;文本规则只扫结构性
|
|
211
|
+
字段,不误杀反馈内容里的凭据引用(引用与读取是两件事)。
|
|
107
212
|
|
|
108
|
-
|
|
109
|
-
公开实验仓同样不触发,平台问题非代码问题,已实测隔离)。期间的机器
|
|
110
|
-
门禁=pre-push 钩子(pytest+pyflakes,红了禁推):
|
|
213
|
+
## 质量与可验证性
|
|
111
214
|
|
|
112
215
|
```bash
|
|
113
|
-
|
|
216
|
+
python3 -m pytest tests/ -q # 全量(单元 + 护栏 + packs + 安装器矩阵 + 协议级真 HTTP + stdio 回环)
|
|
217
|
+
python3 -m pyflakes vod_mcp/*.py tests/*.py scripts/*.py bin/vod-devkit
|
|
218
|
+
python3 -m mypy # 作用域见 pyproject [tool.mypy](新增纯逻辑模块)
|
|
219
|
+
python3 scripts/secret_scan.py
|
|
220
|
+
python3 scripts/sync_case_roster.py --check # docs 与花名册对账
|
|
221
|
+
python3 scripts/rules_provenance.py # 技能与引擎真源对账(无引擎检出时 SKIP)
|
|
114
222
|
```
|
|
115
223
|
|
|
116
|
-
|
|
224
|
+
门禁清单:pre-push 钩子(pytest + pyflakes + secret_scan)+ GitHub Actions(镜像仓)+
|
|
225
|
+
双副本一致性(`vod_mcp` / `skills` 与插件副本逐字节)+ description 截断预算 +
|
|
226
|
+
install-manifest 名册对账(doctor 逐落点)+ 声明计数对账(对外文档不手写用例或工具数)。
|
|
227
|
+
|
|
228
|
+
本文档不放用例数/工具数——手写计数必然漂移;数字一律现场测量。
|
|
229
|
+
|
|
230
|
+
## 文档
|
|
231
|
+
|
|
232
|
+
- 需求 / 设计:[docs/proposal.md](docs/proposal.md) · [docs/design.md](docs/design.md)
|
|
233
|
+
- 一页纸:[docs/scheme-overview.md](docs/scheme-overview.md) | 安全边界:[docs/safety-model.md](docs/safety-model.md)
|
|
234
|
+
- 决策台账:[docs/decisions.md](docs/decisions.md) | 规则真源:[docs/rules-provenance.json](docs/rules-provenance.json)
|
|
235
|
+
- 手动配置与排障:[QUICKSTART.md](QUICKSTART.md) | 分宿主细节:[INSTALL.md](INSTALL.md)
|
|
236
|
+
- 贡献:[CONTRIBUTING.md](CONTRIBUTING.md) | 安全策略:[SECURITY.md](SECURITY.md) | 行为准则:[CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)
|
|
117
237
|
|
|
118
|
-
##
|
|
238
|
+
## 许可
|
|
119
239
|
|
|
120
|
-
|
|
121
|
-
列举、confirm 护栏、宿主感知(U1/U3/U13/U15/U16)。
|
|
240
|
+
MIT(见 LICENSE.txt)。第三方素材见 NOTICE。
|