vod-devkit 0.5.13 → 0.5.14

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 CHANGED
@@ -443,3 +443,9 @@
443
443
  - 4d60d67 fix(release): 发版前必须无未提交改动 + 补交 0.5.12 漏掉的源码(D1/D2/D3/D4)
444
444
  - e9e525b feat(prune): 显式清载荷 + 产品校验复用 state 令牌(D3/D6)
445
445
 
446
+
447
+ ## v0.5.14(2026-11-16)
448
+
449
+ - 5fafa27 feat(quota): 产品名录缓存 + 巡检跳过校验(S149)
450
+ - dea16a6 docs: D3/D6 决策入 ADR + 装机失败分层排查 + 发版纪律教训
451
+
package/README.md CHANGED
@@ -100,6 +100,21 @@ npx -y vod-devkit@latest prune --payloads --apply --yes # 真删(保留当前
100
100
  - **只删载荷**,不碰机器级 state(令牌/账本);单条删除失败记录后继续,最后非零退出;
101
101
  - 拿不准先看 `doctor` 的 `[doctor] 载荷:在用 …;未被任何安装行引用 […]` 那一行。
102
102
 
103
+ ### 装机失败:先分清"限流 / 鉴权 / 网络"(别一上来查网络)
104
+
105
+ `install` 会做**产品硬校验**(`--product` 必须在引擎产品名录里),校验需要一枚令牌。
106
+ 引擎对令牌**签发次数**有限流,所以三种失败各有专属文案:
107
+
108
+ | 文案 | 含义 | 处置 |
109
+ |---|---|---|
110
+ | `令牌签发被限流(HTTP 429…当日/每小时…)` | 同网络/同 IP 的签发次数用满(密集装机、反复巡检、联调都会打满) | 配正式 key `VOD_JAVA_API_KEY`(不占匿名配额);或等窗口(当日/整点);或让运营调限流 |
111
+ | `引擎鉴权异常(HTTP 401)…刚签发的匿名令牌被校验侧拒绝` | 引擎多实例的令牌存储/缓存不同步 | 稍后重跑(安装器已自动重试一次);持续出现找运营核对引擎 |
112
+ | `产品校验不可达(HTTPError/URLError…)` | 真网络/证书/代理问题 | 查 `--java-api-base`、出站代理、DNS |
113
+ | `引擎 meta 无 productCatalog…` | 引擎部署不完整/版本过旧 | 核对引擎是否已部署外部 API(T7i 及以上) |
114
+
115
+ 安装器**优先复用**机器上已有的匿名令牌(`~/.vod-devkit/state`)而不是每次新签——所以正常
116
+ 机器重装/巡检不会再撞限流;仍撞说明这台机器在密集装机(例如批量重装 + 反复跑巡检)。
117
+
103
118
  凭据优先级:显式 key(`auth init` 写入)> 环境变量 `VOD_JAVA_API_KEY`(平台/CI 注入)
104
119
  > 匿名令牌自动领取(设备绑定)。**换 key 不需要重启宿主会话**:插件在每次调用引擎前现读
105
120
  runtime.json 的身份值(`auth init --apply` 之后的下一次提交立刻用新 key)。**不要把 key 写进宿主 MCP 配置的 `env`**——明文,且会随
@@ -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.13",
4
+ "version": "0.5.14",
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>」全文),禁止改写概括——这是用户核对原话是否被改写的唯一窗口。禁止向用户解释内部机制(声音来源/渠道字段/计数规则/配额/归因)。",
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "vod-devkit",
3
- "version": "0.5.13",
3
+ "version": "0.5.14",
4
4
  "description": "VOD 用户声音采集插件——MCP server + 技能 + 声明式护栏,把 agent 产品的用户反馈安全送进 VOD 平台",
5
5
  "license": "MIT",
6
6
  "type": "module",
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "dsh-vod-devkit",
3
- "version": "0.5.13",
3
+ "version": "0.5.14",
4
4
  "description": "VOD user-voice collection tools for DeepSeek Harness (dsh). Thin shell over the VOD external HTTP API — mirrors vod-devkit (MCP) collect semantics.",
5
5
  "type": "module",
6
6
  "main": "lib/index.js",
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "vod-devkit",
3
- "version": "0.5.13",
3
+ "version": "0.5.14",
4
4
  "description": "VOD user-feedback collection: structured voice capture and submission to the VOD hoarding endpoint.",
5
5
  "keywords": [
6
6
  "feedback",
@@ -1,6 +1,6 @@
1
1
  {
2
- "version": "0.5.13",
3
- "commitSha": "98b1621de69aebb4b8e0f8ed1175c29b4391b529",
4
- "builtAt": "2026-11-16T11:53:45",
2
+ "version": "0.5.14",
3
+ "commitSha": "170bbd652b084a33431047fb346c0b5822a914eb",
4
+ "builtAt": "2026-11-16T12:07:23",
5
5
  "sourceRemote": "https://gitcode.com/xiaowu2119/vod-devkit.git"
6
6
  }
@@ -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.13",
4
+ "version": "0.5.14",
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>」全文),禁止改写概括——这是用户核对原话是否被改写的唯一窗口。禁止向用户解释内部机制(声音来源/渠道字段/计数规则/配额/归因)。",
@@ -5,7 +5,7 @@
5
5
  2. 外部无 DB 直连路径(护栏 deny 兜底)
6
6
  3. 任务 ID 是唯一对账主键,写类工具返回一律携带
7
7
  """
8
- __version__ = "0.5.13"
8
+ __version__ = "0.5.14"
9
9
  # 默认上游:VOD 测试环境。外部用户本机无 VOD,回环默认值=装完即坏;
10
10
  # 生产地址定型后只改这一处(tools.py 与 bin/vod-devkit 共用本常量)。
11
11
  DEFAULT_JAVA_BASE = "https://vod-dev.topxtopx.com"
@@ -5,7 +5,7 @@
5
5
  2. 外部无 DB 直连路径(护栏 deny 兜底)
6
6
  3. 任务 ID 是唯一对账主键,写类工具返回一律携带
7
7
  """
8
- __version__ = "0.5.13"
8
+ __version__ = "0.5.14"
9
9
  # 默认上游:VOD 测试环境。外部用户本机无 VOD,回环默认值=装完即坏;
10
10
  # 生产地址定型后只改这一处(tools.py 与 bin/vod-devkit 共用本常量)。
11
11
  DEFAULT_JAVA_BASE = "https://vod-dev.topxtopx.com"
@@ -53,6 +53,8 @@ def main():
53
53
  help="只装技能,不动宿主 MCP 配置(MCP 已由别处/手工注册时用)")
54
54
  sp.add_argument("--no-local-ledger", action="store_true",
55
55
  help="关闭本地提交账本(企业数据驻留要求;vod_list_submitted 将不可用)")
56
+ sp.add_argument("--refresh-product-catalog", action="store_true",
57
+ help="强制向引擎重拉产品名录(默认命中 state 里 7 天内的缓存,省令牌配额)")
56
58
  sp.set_defaults(fn=install.cmd_install)
57
59
  for name, fn in (("status", doctor.cmd_status), ("doctor", doctor.cmd_doctor),
58
60
  ("verify", doctor.cmd_verify), ("update", update.cmd_update),
@@ -216,7 +216,8 @@ def cmd_install(args):
216
216
  # 猜测同源纪律)。插件提交链的 name 兼容通道不受影响(那是老版本插件兼容,
217
217
  # 不是安装期放行理由)。
218
218
  if args.product: # 可选先验:给了就校验,不给不拦装(D-attrib-B)
219
- remote._validate_product_or_exit(args.product, args.java_api_base)
219
+ remote._validate_product_or_exit(args.product, args.java_api_base,
220
+ refresh=bool(getattr(args, "refresh_product_catalog", False)))
220
221
  # D-key-guard-2 红线:preset(产品分发)形态下 key 禁止随包——环境变量里的
221
222
  # key 不透传给宿主配置(客户机一律走匿名令牌自领),并当场告警
222
223
  distribution = args.distribution
@@ -129,7 +129,51 @@ def _remote_reachable(url: str, timeout: int = 6) -> bool:
129
129
  return False
130
130
 
131
131
 
132
- def _validate_product_or_exit(product: str, base: str) -> bool:
132
+ def _catalog_cache_path():
133
+ """产品名录缓存落在机器级 state 目录(与令牌同域,0600)。
134
+
135
+ 为什么缓存:产品名校验每跑一次就要一枚匿名令牌,而引擎对"同网络当日/同 IP 每小时"
136
+ 的**签发次数**限流(真机撞到 100/日、60/小时)。名录 7 天不变的东西不该每次去问引擎。
137
+ """
138
+ from vod_mcp import paths as _paths
139
+ return _paths.machine_state_home() / "product-catalog.json"
140
+
141
+
142
+ def _read_catalog_cache(base: str):
143
+ """命中返回 (catalog, age_secs),否则 None。TTL 可用 VOD_PRODUCT_CATALOG_TTL 覆盖(秒)。"""
144
+ import time
145
+ ttl = float(os.environ.get("VOD_PRODUCT_CATALOG_TTL") or 7 * 86400)
146
+ if ttl <= 0:
147
+ return None
148
+ p = _catalog_cache_path()
149
+ if not p.is_file():
150
+ return None
151
+ try:
152
+ d = json.loads(p.read_text(encoding="utf-8"))
153
+ except (OSError, ValueError):
154
+ return None
155
+ if str(d.get("base") or "") != str(base):
156
+ return None # 换了引擎地址 → 缓存作废
157
+ age = time.time() - float(d.get("at") or 0)
158
+ if age > ttl:
159
+ return None
160
+ cat = d.get("catalog")
161
+ return (cat, age) if isinstance(cat, list) and cat else None
162
+
163
+
164
+ def _write_catalog_cache(base: str, catalog: list) -> None:
165
+ import time
166
+ p = _catalog_cache_path()
167
+ try:
168
+ p.parent.mkdir(parents=True, exist_ok=True)
169
+ p.write_text(json.dumps({"base": str(base), "at": time.time(), "catalog": catalog},
170
+ ensure_ascii=False), encoding="utf-8")
171
+ os.chmod(p, 0o600)
172
+ except OSError:
173
+ pass # 缓存写不进不是安装的失败条件
174
+
175
+
176
+ def _validate_product_or_exit(product: str, base: str, refresh: bool = False) -> bool:
133
177
  """D-product-id-2:安装期产品硬校验(B 案,2026-11-05 拍板)。
134
178
  --product 命中 meta productCatalog(名字大小写不敏感或 id 精确)才放行;
135
179
  未命中/目录不可达一律拒绝安装并给可执行引导(宁可不装不可装错)。
@@ -204,10 +248,25 @@ def _validate_product_or_exit(product: str, base: str) -> bool:
204
248
  cat = data if isinstance(data, list) else None
205
249
  return cat
206
250
 
251
+ if os.environ.get("VOD_SKIP_PRODUCT_CHECK") == "1":
252
+ print("[vod-devkit] 跳过产品校验(VOD_SKIP_PRODUCT_CHECK=1:巡检/离线场景;"
253
+ "归因名单在装机时已验过)", file=sys.stderr)
254
+ return True
255
+
207
256
  catalog, unauthorized, rate_limited, last_exc = None, False, False, None
257
+ if not refresh:
258
+ cached = _read_catalog_cache(base)
259
+ if cached:
260
+ catalog = cached[0]
261
+ print(f"[vod-devkit] 产品校验:命中本地缓存({cached[1] / 3600:.1f} 小时前拉取,"
262
+ "未请求引擎;要强刷用 --refresh-product-catalog)")
208
263
  for attempt in (1, 2):
264
+ if catalog is not None: # 缓存命中:本地比对即可,不打引擎
265
+ break
209
266
  try:
210
267
  catalog = _catalog_once()
268
+ if catalog:
269
+ _write_catalog_cache(base, catalog)
211
270
  last_exc = None
212
271
  break
213
272
  except urllib.error.HTTPError as e: