vod-devkit 0.0.0-stage → 0.1.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 +13 -0
- package/LICENSE.txt +21 -0
- package/QUICKSTART.md +79 -0
- package/README.en.md +75 -0
- package/README.md +84 -2
- package/bin/vod-devkit +464 -0
- package/contract/tools.schema.json +187 -0
- package/npm/cli.js +39 -0
- package/package.json +35 -4
- package/safety/policy.json +48 -0
- package/skills/vod-core/SKILL.md +23 -0
- package/skills/vod-feedback-collect/SKILL.md +90 -0
- package/skills/vod-problem-classification-rules/SKILL.md +45 -0
- package/skills/vod-scoring-rules/SKILL.md +37 -0
- package/vod_mcp/__init__.py +11 -0
- package/vod_mcp/__pycache__/__init__.cpython-314.pyc +0 -0
- package/vod_mcp/__pycache__/packs.cpython-314.pyc +0 -0
- package/vod_mcp/__pycache__/policy.cpython-314.pyc +0 -0
- package/vod_mcp/__pycache__/provenance.cpython-314.pyc +0 -0
- package/vod_mcp/__pycache__/server.cpython-314.pyc +0 -0
- package/vod_mcp/__pycache__/tools.cpython-314.pyc +0 -0
- package/vod_mcp/packs.py +30 -0
- package/vod_mcp/policy.py +98 -0
- package/vod_mcp/provenance.py +43 -0
- package/vod_mcp/runtime.example.json +6 -0
- package/vod_mcp/runtime.json +1473 -0
- package/vod_mcp/server.py +105 -0
- package/vod_mcp/tools.py +620 -0
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## v0.1.0(2026-11-03)
|
|
4
|
+
|
|
5
|
+
首个可用版本:VOD 用户声音采集插件(方案 A 纯采集形态)。
|
|
6
|
+
|
|
7
|
+
- 3 工具:vod_submit_voices(confirm+单批≤50+归因三层+零字段匿名令牌
|
|
8
|
+
自动获取+声量保真 voiceId)、vod_devkit_info、vod_auth_status
|
|
9
|
+
- 动态元数据:meta 拉取+24h 缓存+快照兜底+stale 标记
|
|
10
|
+
- 声明式护栏 + 契约单一事实源 + 溯源(commitSHA verify)+ preset 安装
|
|
11
|
+
- 端到端已实测:真 Hermes 会话→测试环境 Java /external/voice/submit
|
|
12
|
+
→taskId 回执(零引擎侧改动,复用现有接口)
|
|
13
|
+
- 23 用例(单元+护栏+packs+协议级真 HTTP+stdio 回环+meta)
|
package/LICENSE.txt
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 VOD Team
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/QUICKSTART.md
ADDED
|
@@ -0,0 +1,79 @@
|
|
|
1
|
+
# QUICKSTART(外部开发者 · 3 分钟接入)
|
|
2
|
+
|
|
3
|
+
## 你能得到什么
|
|
4
|
+
|
|
5
|
+
把 vod-devkit 装进你的 AI agent / 应用后:
|
|
6
|
+
|
|
7
|
+
1. **采集你产品的用户反馈**进 VOD(唯一写口,需用户确认)
|
|
8
|
+
2. VOD 领域知识技能(问题分类/分类匹配/评分规则,采集预分类用)
|
|
9
|
+
3. 插件自述与来源核验(vod_devkit_info / vod_auth_status)
|
|
10
|
+
|
|
11
|
+
> 首次提交时插件会自动申请零字段匿名令牌(无需注册);
|
|
12
|
+
> 量大后再升级正式 key。
|
|
13
|
+
|
|
14
|
+
## 前置
|
|
15
|
+
|
|
16
|
+
- Python 3.10+
|
|
17
|
+
- 任意支持 MCP stdio 的宿主(Hermes/OpenCode/Codex/…)
|
|
18
|
+
|
|
19
|
+
## 方式一:Hermes(自动安装)
|
|
20
|
+
|
|
21
|
+
```bash
|
|
22
|
+
git clone <repo-url> vod-devkit && cd vod-devkit
|
|
23
|
+
bin/vod-devkit install --target hermes --preset collect --product <你的产品>
|
|
24
|
+
# 重启 Hermes 会话,工具以 mcp_vod_devkit_* 出现
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
## 方式二:OpenCode / Codex(自动安装,2026-11-03 起支持)
|
|
28
|
+
|
|
29
|
+
```bash
|
|
30
|
+
git clone <repo-url> vod-devkit && cd vod-devkit
|
|
31
|
+
bin/vod-devkit install --target opencode --product <你的产品> # 或 codex
|
|
32
|
+
# install --target auto 会探测已装宿主(0/1/N 三分支)
|
|
33
|
+
```
|
|
34
|
+
> opencode/codex 适配层已过配置写出验证(真实宿主回归待首个用户反馈)。
|
|
35
|
+
|
|
36
|
+
## 方式三:npm(npx 一条命令,包已就绪待发布)
|
|
37
|
+
|
|
38
|
+
```bash
|
|
39
|
+
npx vod-devkit install --target <hermes|opencode|codex> --product <你的产品>
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
## 方式四:任意 MCP 客户端(手动配置)
|
|
43
|
+
|
|
44
|
+
把以下片段并入你宿主的 mcpServers 配置:
|
|
45
|
+
|
|
46
|
+
```json
|
|
47
|
+
{
|
|
48
|
+
"mcpServers": {
|
|
49
|
+
"vod-devkit": {
|
|
50
|
+
"command": "python3",
|
|
51
|
+
"args": ["/path/to/vod-devkit/vod_mcp/server.py"],
|
|
52
|
+
"env": {
|
|
53
|
+
"VOD_JAVA_API_BASE": "https://vod-dev.topxtopx.com",
|
|
54
|
+
"VOD_JAVA_API_KEY": "",
|
|
55
|
+
"VOD_PACKS": "core,collect,knowledge"
|
|
56
|
+
}
|
|
57
|
+
}
|
|
58
|
+
}
|
|
59
|
+
}
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
配置好后重启会话。
|
|
63
|
+
|
|
64
|
+
## 验证
|
|
65
|
+
|
|
66
|
+
- 会话里让 agent 调用 `vod_auth_status` → key 状态(指纹)+ 三步引导
|
|
67
|
+
- 提交一条测试反馈:`vod_submit_voices`(voices + confirmed=true)
|
|
68
|
+
|
|
69
|
+
## 升级正式 key(提交量达匿名上限后)
|
|
70
|
+
|
|
71
|
+
联系 VOD 运营 → `bin/vod-devkit install --java-key <KEY>` 重新落位。
|
|
72
|
+
|
|
73
|
+
## 故障排查
|
|
74
|
+
|
|
75
|
+
| 症状 | 含义 |
|
|
76
|
+
|---|---|
|
|
77
|
+
| `上游不可达` | 引擎/网络未就绪,检查 VOD_JAVA_API_BASE |
|
|
78
|
+
| `-32012 鉴权失败` | key 无效或被吊销;无 key 会自动取令牌重试 |
|
|
79
|
+
| 工具不出现 | 确认 VOD_PACKS 含对应 pack;重启会话 |
|
package/README.en.md
ADDED
|
@@ -0,0 +1,75 @@
|
|
|
1
|
+
# vod-devkit (English)
|
|
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
|
|
27
|
+
|
|
28
|
+
```bash
|
|
29
|
+
# Any MCP host (Hermes / OpenCode / Codex clients, …):
|
|
30
|
+
npx github:yangaiwu/vod-devkit # bootstrap probes the host and installs
|
|
31
|
+
|
|
32
|
+
# WorkBuddy / CodeBuddy (the GitHub repo IS the marketplace, no review):
|
|
33
|
+
/plugin marketplace add yangaiwu/vod-devkit
|
|
34
|
+
|
|
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
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
From source:
|
|
42
|
+
|
|
43
|
+
```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
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
Zero config after install: platform base has a default, and the first
|
|
51
|
+
submission automatically requests a zero-field anonymous token.
|
|
52
|
+
|
|
53
|
+
Verified hosts: Hermes (official `hermes mcp add`), OpenCode
|
|
54
|
+
(`opencode mcp list` → connected), Codex CLI (config recognized).
|
|
55
|
+
|
|
56
|
+
## Guarantees
|
|
57
|
+
|
|
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.
|
|
65
|
+
|
|
66
|
+
## Quality
|
|
67
|
+
|
|
68
|
+
39 tests (unit / guardrails / packs / installer matrix across three hosts /
|
|
69
|
+
protocol-level real-HTTP lock /
|
|
70
|
+
stdio roundtrip / meta cache / ledger) + pre-push gate + GitHub Actions
|
|
71
|
+
CI on the mirror + nightly local E2E against the test environment.
|
|
72
|
+
|
|
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
|
package/README.md
CHANGED
|
@@ -1,3 +1,85 @@
|
|
|
1
|
-
#
|
|
1
|
+
# vod-devkit
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[English](README.en.md) | 中文
|
|
4
|
+
|
|
5
|
+
VOD 用户声音采集插件(方案 A 纯采集形态):MCP server + 技能 +
|
|
6
|
+
声明式护栏,把 agent 产品的用户反馈安全送进 VOD。运营能力归
|
|
7
|
+
vod-system 前端,不在本插件。对齐 huaweicloud-devkit v2 的工程骨架(installer /
|
|
8
|
+
MCP / skills / packs / policy),面向"服务面插件"的护栏更保守。
|
|
9
|
+
|
|
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)
|
|
17
|
+
|
|
18
|
+
## 安装(外部用户,零配置)
|
|
19
|
+
|
|
20
|
+
```bash
|
|
21
|
+
# 任意 MCP 宿主(Hermes / OpenCode / Codex 客户端等):
|
|
22
|
+
npx github:yangaiwu/vod-devkit # 引导器自动探测宿主并安装
|
|
23
|
+
|
|
24
|
+
# WorkBuddy / CodeBuddy(GitHub 仓即市场,无审核):
|
|
25
|
+
/plugin marketplace add yangaiwu/vod-devkit
|
|
26
|
+
|
|
27
|
+
# DeepSeek Harness (dsh):npm 包 dsh-vod-devkit(薄壳同语义);
|
|
28
|
+
# npm 首发后可在 dsh 社区目录一键安装,暂可用本地包:
|
|
29
|
+
dsh plugin --profile <profile> add dsh/dsh-vod-devkit-0.1.0.tgz
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
安装后即用:平台地址有默认值,首次提交自动申请零字段匿名令牌。
|
|
33
|
+
手动配置片段与故障排查见 [QUICKSTART.md](QUICKSTART.md)。
|
|
34
|
+
|
|
35
|
+
## 快速使用
|
|
36
|
+
|
|
37
|
+
```bash
|
|
38
|
+
# 安装到 Hermes(写 MCP 配置+skills+install-manifest)
|
|
39
|
+
bin/vod-devkit install --target hermes --preset collect # 对外默认(采集者)
|
|
40
|
+
# 唯一上游 Java backend(key 未配置时首提自动申请匿名令牌):
|
|
41
|
+
VOD_JAVA_API_BASE / VOD_JAVA_API_KEY
|
|
42
|
+
|
|
43
|
+
bin/vod-devkit update # git fetch+ff 拉取+重烧 build-info
|
|
44
|
+
bin/vod-devkit status # 看 install-manifest(版本+来源+宿主+packs)
|
|
45
|
+
bin/vod-devkit verify # commitSHA 到 origin 核验(篡改/改写告警)
|
|
46
|
+
bin/vod-devkit doctor # 配置+skills+build-info 三查
|
|
47
|
+
bin/vod-devkit uninstall
|
|
48
|
+
|
|
49
|
+
# 直接以 MCP server 运行(任意 MCP 客户端可连)
|
|
50
|
+
python3 -m vod_mcp.server # stdio,JSON-RPC
|
|
51
|
+
VOD_PACKS=core,collect python3 -m vod_mcp.server # packs 裁剪
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
## 工具面(契约唯一事实源:contract/tools.schema.json)
|
|
55
|
+
|
|
56
|
+
| 工具 | 类型 | 护栏 |
|
|
57
|
+
|---|---|---|
|
|
58
|
+
|
|
59
|
+
| vod_submit_voices | 写 | confirm 逐次同意 + 单批≤50 + source 取握手宿主身份;走 Java /external/voices |
|
|
60
|
+
| vod_devkit_info | 只读常驻 | 返回版本/commitSHA/宿主 clientInfo |
|
|
61
|
+
| vod_auth_status | 只读常驻 | key 指纹化自检+三步引导(无 key 可跑) |
|
|
62
|
+
| vod_list_submitted | 只读 | 本机提交账本(cap 200)——agent 替用户对账进度 |
|
|
63
|
+
|
|
64
|
+
安全:deny 拦 DB 直连意图与凭据读取(safety/policy.json 声明式规则;
|
|
65
|
+
文本规则只扫结构性字段,不误杀反馈内容里的凭据引用)。
|
|
66
|
+
|
|
67
|
+
测试:39 用例(单元+护栏+packs+安装器矩阵三宿主+真进程 stdio 回环+**协议级真 HTTP 服务器**
|
|
68
|
+
锁定认证头/双后端路径——E1/E2 的永久回归门)。决策闭环见 docs/decisions.md。
|
|
69
|
+
|
|
70
|
+
## 质量门禁
|
|
71
|
+
|
|
72
|
+
GitCode Actions 平台侧当前对本账号不可用(运行 0ms FAILED 零 job、
|
|
73
|
+
公开实验仓同样不触发,平台问题非代码问题,已实测隔离)。期间的机器
|
|
74
|
+
门禁=pre-push 钩子(pytest+pyflakes,红了禁推):
|
|
75
|
+
|
|
76
|
+
```bash
|
|
77
|
+
git config core.hooksPath .githooks # clone 后执行一次
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
`.gitcode/workflows/ci.yml` 已就位,平台恢复后自动叠加服务端门禁。
|
|
81
|
+
|
|
82
|
+
## 测试
|
|
83
|
+
|
|
84
|
+
零第三方运行时依赖;测试需 pytest。真进程 stdio 回环覆盖握手、工具
|
|
85
|
+
列举、confirm 护栏、宿主感知(U1/U3/U13/U15/U16)。
|