vod-devkit 0.0.0-stage → 0.1.0

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 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
- # Temporary Holding Version
1
+ # vod-devkit
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
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)。