vod-devkit 0.4.4 → 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.
Files changed (81) hide show
  1. package/CHANGELOG.md +42 -0
  2. package/QUICKSTART.md +1 -1
  3. package/README.en.md +190 -56
  4. package/README.md +210 -56
  5. package/bin/vod-devkit +502 -460
  6. package/contract/tools.schema.json +114 -7
  7. package/integrations/codeartsdoer/host.json +11 -0
  8. package/integrations/codex/host.json +20 -0
  9. package/integrations/dsh/host.json +15 -0
  10. package/integrations/hermes/host.json +20 -0
  11. package/integrations/opencode/command/vod-doctor.md +10 -0
  12. package/integrations/opencode/host.json +28 -0
  13. package/package.json +13 -10
  14. package/plugins/vod-devkit/.codex-plugin/plugin.json +1 -1
  15. package/plugins/vod-devkit/build-info.json +3 -3
  16. package/plugins/vod-devkit/skills/vod-core/SKILL.md +43 -15
  17. package/plugins/vod-devkit/skills/vod-core/references/acceptance-criteria.md +9 -0
  18. package/plugins/vod-devkit/skills/vod-core/references/verification-method.md +29 -0
  19. package/plugins/vod-devkit/skills/vod-feedback-collect/SKILL.md +57 -11
  20. package/plugins/vod-devkit/skills/vod-feedback-collect/references/acceptance-criteria.md +28 -0
  21. package/plugins/vod-devkit/skills/vod-feedback-collect/references/verification-method.md +31 -0
  22. package/plugins/vod-devkit/skills/vod-problem-classification-rules/SKILL.md +3 -1
  23. package/plugins/vod-devkit/skills/vod-scoring-rules/SKILL.md +22 -1
  24. package/plugins/vod-devkit/vod_mcp/__init__.py +1 -1
  25. package/plugins/vod-devkit/vod_mcp/attribution.py +378 -0
  26. package/plugins/vod-devkit/vod_mcp/config_forms.py +154 -0
  27. package/plugins/vod-devkit/vod_mcp/guardrails.py +25 -0
  28. package/plugins/vod-devkit/vod_mcp/host_adapters/__init__.py +26 -0
  29. package/plugins/vod-devkit/vod_mcp/host_adapters/base.py +73 -0
  30. package/plugins/vod-devkit/vod_mcp/host_adapters/codearts.py +57 -0
  31. package/plugins/vod-devkit/vod_mcp/host_adapters/codex.py +209 -0
  32. package/plugins/vod-devkit/vod_mcp/host_adapters/dsh.py +176 -0
  33. package/plugins/vod-devkit/vod_mcp/host_adapters/generic.py +132 -0
  34. package/plugins/vod-devkit/vod_mcp/host_adapters/hermes.py +76 -0
  35. package/plugins/vod-devkit/vod_mcp/host_adapters/opencode.py +52 -0
  36. package/plugins/vod-devkit/vod_mcp/hosts.py +100 -0
  37. package/plugins/vod-devkit/vod_mcp/packs.py +19 -3
  38. package/plugins/vod-devkit/vod_mcp/payload.py +174 -0
  39. package/plugins/vod-devkit/vod_mcp/remote_app.py +100 -0
  40. package/plugins/vod-devkit/vod_mcp/server.py +43 -16
  41. package/plugins/vod-devkit/vod_mcp/skills_registry.py +124 -0
  42. package/plugins/vod-devkit/vod_mcp/tools.py +455 -55
  43. package/plugins/vod-devkit/vod_mcp/transport_remote.py +289 -0
  44. package/plugins/vod-devkit/vod_mcp/update_check.py +133 -0
  45. package/skills/vod-core/SKILL.md +43 -15
  46. package/skills/vod-core/references/acceptance-criteria.md +9 -0
  47. package/skills/vod-core/references/verification-method.md +29 -0
  48. package/skills/vod-feedback-collect/SKILL.md +57 -11
  49. package/skills/vod-feedback-collect/references/acceptance-criteria.md +28 -0
  50. package/skills/vod-feedback-collect/references/verification-method.md +31 -0
  51. package/skills/vod-problem-classification-rules/SKILL.md +3 -1
  52. package/skills/vod-scoring-rules/SKILL.md +22 -1
  53. package/vod_mcp/__init__.py +1 -1
  54. package/vod_mcp/attribution.py +378 -0
  55. package/vod_mcp/config_forms.py +154 -0
  56. package/vod_mcp/guardrails.py +25 -0
  57. package/vod_mcp/host_adapters/__init__.py +26 -0
  58. package/vod_mcp/host_adapters/__pycache__/__init__.cpython-314.pyc +0 -0
  59. package/vod_mcp/host_adapters/__pycache__/base.cpython-314.pyc +0 -0
  60. package/vod_mcp/host_adapters/__pycache__/codearts.cpython-314.pyc +0 -0
  61. package/vod_mcp/host_adapters/__pycache__/codex.cpython-314.pyc +0 -0
  62. package/vod_mcp/host_adapters/__pycache__/dsh.cpython-314.pyc +0 -0
  63. package/vod_mcp/host_adapters/__pycache__/generic.cpython-314.pyc +0 -0
  64. package/vod_mcp/host_adapters/__pycache__/hermes.cpython-314.pyc +0 -0
  65. package/vod_mcp/host_adapters/__pycache__/opencode.cpython-314.pyc +0 -0
  66. package/vod_mcp/host_adapters/base.py +73 -0
  67. package/vod_mcp/host_adapters/codearts.py +57 -0
  68. package/vod_mcp/host_adapters/codex.py +209 -0
  69. package/vod_mcp/host_adapters/dsh.py +176 -0
  70. package/vod_mcp/host_adapters/generic.py +132 -0
  71. package/vod_mcp/host_adapters/hermes.py +76 -0
  72. package/vod_mcp/host_adapters/opencode.py +52 -0
  73. package/vod_mcp/hosts.py +100 -0
  74. package/vod_mcp/packs.py +19 -3
  75. package/vod_mcp/payload.py +174 -0
  76. package/vod_mcp/remote_app.py +100 -0
  77. package/vod_mcp/server.py +43 -16
  78. package/vod_mcp/skills_registry.py +124 -0
  79. package/vod_mcp/tools.py +455 -55
  80. package/vod_mcp/transport_remote.py +289 -0
  81. package/vod_mcp/update_check.py +133 -0
package/CHANGELOG.md CHANGED
@@ -260,3 +260,45 @@
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
+
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,75 +1,209 @@
1
1
  # vod-devkit (English)
2
2
 
3
- Collect product feedback from your AI agent's users and deliver it safely
4
- into the VOD voice-of-customer platform. A pure-collection MCP plugin:
5
- one write endpoint, one upstream, tiered trust — aligned with the
6
- engineering skeleton of huaweicloud-devkit, adapted for a service-facing
7
- plugin.
8
-
9
- ## What it does
10
-
11
- - **vod_submit_voices** — submit user feedback (requires per-batch user
12
- confirmation; content ≤2000 chars; product attribution via
13
- install-binding > explicit > ask-user, never silently guessed)
14
- - **vod_list_submitted** — local ledger of what this machine submitted
15
- (agent answers "did my feedback go through?")
16
- - **vod_auth_status** — key fingerprint self-check + 3-step guidance
17
- (works without a key)
18
- - **vod_devkit_info** — plugin version / commitSHA / host identity
19
-
20
- Zero-field anonymous token: on first submission the plugin automatically
21
- requests a token (no registration). Upgrade to a formal key when volume
22
- grows. Skills: VOD problem-classification (6 categories), category
23
- matching, and scoring rules — sourced from engine code, used for
24
- pre-classification at collection time.
25
-
26
- ## Install
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
- # Any MCP host (Hermes / OpenCode / Codex clients, …):
30
- npx github:yangaiwu/vod-devkit # bootstrap probes the host and installs
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
- # WorkBuddy / CodeBuddy (the GitHub repo IS the marketplace, no review):
33
- /plugin marketplace add yangaiwu/vod-devkit
90
+ ### CodeArts Agent (codeartsdoer)
34
91
 
35
- # DeepSeek Harness (dsh): npm package dsh-vod-devkit (thin shell, same
36
- # semantics); one-click in the dsh community directory once published to
37
- # npm — until then, local tarball:
38
- dsh plugin --profile <profile> add dsh/dsh-vod-devkit-0.1.0.tgz
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
- From source:
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
- git clone https://github.com/yangaiwu/vod-devkit.git
45
- cd vod-devkit
46
- bin/vod-devkit install --target auto --product <your-product> # hermes | opencode | codex
47
- # For any MCP client, see QUICKSTART.md for the manual config snippet
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
- Zero config after install: platform base has a default, and the first
51
- submission automatically requests a zero-field anonymous token.
135
+ ## Remote deployment: standalone MCP + host attach
136
+
137
+ One endpoint serves many hosts; identity comes from request headers:
52
138
 
53
- Verified hosts: Hermes (official `hermes mcp add`), OpenCode
54
- (`opencode mcp list` → connected), Codex CLI (config recognized).
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
- ## Guarantees
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
- - No identity fields in tool schemas — attribution cannot be forged by
59
- the model; user identity travels as data fields only
60
- - Guardrails: per-batch confirm, batch ≤50, credential/DB-intent deny
61
- (scoped so legitimate feedback quoting secrets is not killed)
62
- - Provenance: install-manifest + build-info (commitSHA) +
63
- `vod-devkit verify` tamper detection
64
- - No telemetry. Fail-closed: no traceable credential → no write.
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
- 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.
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
72
208
 
73
- Docs: [README.md (中文)](README.md) · QUICKSTART.md · CONTRIBUTING.md ·
74
- SECURITY.md · SUPPORT.md · CODE_OF_CONDUCT.md · NOTICE · docs/proposal.md ·
75
- 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,85 +2,239 @@
2
2
 
3
3
  [English](README.en.md) | 中文
4
4
 
5
- VOD 用户声音采集插件(方案 A 纯采集形态):MCP server + 技能 +
6
- 声明式护栏,把 agent 产品的用户反馈安全送进 VOD。运营能力归
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
- - 需求/设计:docs/proposal.md、docs/design.md(VOD-PLUGIN)
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
- 完整分宿主指南见 [INSTALL.md](INSTALL.md)。速览:
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 配置)。随后自检:
21
35
 
22
36
  ```bash
23
- # 任意 MCP 宿主(Hermes / OpenCode / Codex 客户端等):npm 公网已发布
24
- npx --yes vod-devkit install --target opencode --product codearts
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`。
25
49
 
26
- # WorkBuddy / CodeBuddy(GitHub 仓即市场,无审核):
27
- /plugin marketplace add yangaiwu/vod-devkit
50
+ ### Hermes
28
51
 
29
- # DeepSeek Harness (dsh):薄壳包 dsh-vod-devkit(npm 同名);目录收录审核中
30
- dsh plugin --profile <profile> add dsh-vod-devkit
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
31
59
  ```
32
60
 
33
- 安装后即用:平台地址有默认值,首次提交自动申请零字段匿名令牌。
34
- 手动配置片段与故障排查见 [QUICKSTART.md](QUICKSTART.md)。
61
+ - 落点:`hermes mcp add` 写 `~/.hermes/config.yaml`,另存 `~/.hermes/mcp/vod-devkit.json`;
62
+ 技能装到 `~/.hermes/skills/devops/vod-devkit`
63
+ - 卸载只摘托管的 MCP 条目(走 `hermes mcp remove`),不动你的其它 server
35
64
 
36
- ## 快速使用
65
+ ### OpenCode
37
66
 
38
67
  ```bash
39
- # 安装到 Hermes(写 MCP 配置+skills+install-manifest)
40
- bin/vod-devkit install --target hermes --preset collect # 对外默认(采集者)
41
- # 唯一上游 Java backend(key 未配置时首提自动申请匿名令牌):
42
- VOD_JAVA_API_BASE / VOD_JAVA_API_KEY
43
-
44
- bin/vod-devkit update # git fetch+ff 拉取+重烧 build-info
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 裁剪
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
53
71
  ```
54
72
 
55
- ## 工具面(契约唯一事实源:contract/tools.schema.json)
73
+ - 落点:`~/.config/opencode/opencode.json` 的 `mcp.vod-devkit`(无损合并,保留你的
74
+ provider 等既有键);技能装到 `~/.config/opencode/skills`
75
+ - **卸载只摘 `mcp.vod-devkit` 与本次装进去的技能目录**——共享配置文件与其它插件的
76
+ 技能永不整文件/整目录删除
56
77
 
57
- | 工具 | 类型 | 护栏 |
58
- |---|---|---|
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)
92
+
93
+ ```bash
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/`
105
+
106
+ ### DeepSeek Harness (dsh)
107
+
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
112
+ ```
113
+
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 宿主(通用层)
120
+
121
+ 没有专属适配模块的宿主不再"不支持"——通用层负责写配置或给片段:
59
122
 
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 替用户对账进度 |
123
+ ```bash
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
130
+ ```
131
+
132
+ - **外科式合并**:只写 `mcpServers.vod-devkit`,其它 server 与用户自有键原样保留;
133
+ 首次改动前落 `.bak`
134
+ - 文件不是合法 JSON / 顶层不是对象 → 报错退出、字节不动(宁可不装不可装错)
135
+ - `--target auto` 在只探测到一个通用宿主时自动走通用写入;多个/零个要求显式指定
136
+ - 通用层只装 MCP 条目,不装技能(技能目录是宿主私有的;要话术层用 hermes/opencode/codex)
137
+
138
+ 手写片段(把 `<repo>` 换成本仓绝对路径):
139
+
140
+ ```jsonc
141
+ { "mcpServers": { "vod-devkit": {
142
+ "command": "python3", "args": ["<repo>/vod_mcp/server.py"] } } }
143
+ ```
144
+
145
+ MCP 已由别处注册、只想装技能话术时:
64
146
 
65
- 安全:deny 拦 DB 直连意图与凭据读取(safety/policy.json 声明式规则;
66
- 文本规则只扫结构性字段,不误杀反馈内容里的凭据引用)。
147
+ ```bash
148
+ npx -y vod-devkit@latest install --target <hermes|opencode|codex> --skills-only
149
+ ```
150
+
151
+ ## 远程部署:MCP 单独部署 + 宿主 attach
152
+
153
+ 一个远程端点服务多个宿主;身份随请求头走,不落服务器:
67
154
 
68
- 测试:39 用例(单元+护栏+packs+安装器矩阵三宿主+真进程 stdio 回环+**协议级真 HTTP 服务器**
69
- 锁定认证头/双后端路径——E1/E2 的永久回归门)。决策闭环见 docs/decisions.md。
155
+ ```bash
156
+ pip install 'vod-devkit[remote]'
157
+ vod-devkit serve --transport remote --port 9528 --host 127.0.0.1 # 前面需自建 TLS 反代
158
+ ```
70
159
 
71
- ## 质量门禁
160
+ ```jsonc
161
+ { "mcp": { "vod-devkit": {
162
+ "type": "remote", "url": "http://localhost:9528", "enabled": true } } }
163
+ ```
72
164
 
73
- GitCode Actions 平台侧当前对本账号不可用(运行 0ms FAILED 零 job、
74
- 公开实验仓同样不触发,平台问题非代码问题,已实测隔离)。期间的机器
75
- 门禁=pre-push 钩子(pytest+pyflakes,红了禁推):
165
+ 宿主 attach(token 必填——远程面不代签匿名身份,缺 key 会被拒装 `exit 2`):
76
166
 
77
167
  ```bash
78
- git config core.hooksPath .githooks # clone 后执行一次
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>
79
171
  ```
80
172
 
81
- `.gitcode/workflows/ci.yml` 已就位,平台恢复后自动叠加服务端门禁。
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
+
184
+ 端口被占用用 `--port <port>`(同步改 url);`--host 0.0.0.0` 可开 LAN 访问。
185
+
186
+ ## 遥测与数据
187
+
188
+ - **收集什么**:无。本插件不上报任何使用数据——没有遥测、没有埋点、没有用量统计,
189
+ 技能加载与工具调用都不回传。
190
+ - **不收集什么**:全部。反馈内容只在用户明确同意后发往**你配置的引擎地址**;插件
191
+ 不自建任何回传通道。
192
+ - **传输路径**:stdio 面由宿主进程直连引擎;远程面由请求头里的 key 标识调用方,
193
+ 身份不落服务器。
194
+ - **如何关闭**:无需关闭(本就没有)。若要不连引擎:`uninstall`,或把
195
+ `--java-api-base` 指向你自己的实例。
196
+
197
+ ## 工具面(契约唯一事实源:contract/tools.schema.json)
198
+
199
+ | 工具 | pack | 类型 | 护栏 |
200
+ |---|---|---|---|
201
+ | vod_submit_voices | collect | 写 | confirm 逐次同意 + 单批<=50;走 Java `/external/voices` |
202
+ | vod_draft_voices | collect | 写(暂存) | 本机暂存 cap10/TTL600s,逐字回显;不触上游 |
203
+ | vod_commit_voices | collect | 写 | 一次性令牌 + payloadSha256 防调包,内部复用提交链 |
204
+ | vod_list_submitted | collect | 只读 | 本机提交账本(cap 200)——agent 替用户对账进度 |
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 裁剪即拒绝并给恢复命令) |
209
+
210
+ 安全:`safety/policy.json` 声明式规则拦 DB 直连意图与凭据读取;文本规则只扫结构性
211
+ 字段,不误杀反馈内容里的凭据引用(引用与读取是两件事)。
212
+
213
+ ## 质量与可验证性
214
+
215
+ ```bash
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)
222
+ ```
223
+
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)
82
237
 
83
- ## 测试
238
+ ## 许可
84
239
 
85
- 零第三方运行时依赖;测试需 pytest。真进程 stdio 回环覆盖握手、工具
86
- 列举、confirm 护栏、宿主感知(U1/U3/U13/U15/U16)。
240
+ MIT(见 LICENSE.txt)。第三方素材见 NOTICE。