vod-devkit 0.5.12 → 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
@@ -436,3 +436,16 @@
436
436
 
437
437
  - 7574e3c docs(dsh): 接入手册按 0.5.11 实现重写(两种形态 / 托管块 / 身份两套账本)
438
438
 
439
+
440
+ ## v0.5.13(2026-11-16)
441
+
442
+ - fd804b0 fix(query/prune): 门禁边界 + basetemp 判据 + 壳 add 超时 + prune 文档(评审 a/b/c/d)
443
+ - 4d60d67 fix(release): 发版前必须无未提交改动 + 补交 0.5.12 漏掉的源码(D1/D2/D3/D4)
444
+ - e9e525b feat(prune): 显式清载荷 + 产品校验复用 state 令牌(D3/D6)
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
@@ -82,8 +82,39 @@ npx -y vod-devkit@latest uninstall --target codex --clean-global # 并清载
82
82
  npx -y vod-devkit@latest auth status # 引擎地址 + 凭据指纹 + 档位(key / 匿名令牌)
83
83
  npx -y vod-devkit@latest auth init --key <k> # 校验并显示指纹(缺省不写盘)
84
84
  npx -y vod-devkit@latest auth init --key <k> --apply # 写 runtime.json(唯一入口,0600)
85
+ npx -y vod-devkit@latest prune --payloads # 列出可清旧载荷(默认 dry-run,不删)
86
+ npx -y vod-devkit@latest prune --payloads --apply --yes # 真删(保留当前版本与在用的版本)
85
87
  ```
86
88
 
89
+ ### 旧载荷清理(prune)
90
+
91
+ 每升一版会在 `~/.vod-devkit/payloads/<版本>/` 落一份载荷(宿主入口指向它,与 npx 缓存解耦)。
92
+ 旧版本**不会自动删**——install 永不隐式删用户文件(删错=某宿主配置指向的 `server.py` 消失)。
93
+ 要收空间用显式命令:
94
+
95
+ - **只清清单内**:`payloads/<版本>/` 且带 `payload.json`(安装器 `stage()` 落的);
96
+ 没有该文件的手工目录与残留一律不在此列,绝不按 glob 删目录;
97
+ - **保留**:当前版本 + 任何安装行 `payloadDir` 在用的版本;`--keep N` 额外保留最新 N 份;
98
+ - **默认 dry-run**(打印 版本/大小/路径 + 总量);`--apply` 才删,交互式再问 y/N,
99
+ 非 tty 必须 `--yes`,否则拒绝执行(exit 2);
100
+ - **只删载荷**,不碰机器级 state(令牌/账本);单条删除失败记录后继续,最后非零退出;
101
+ - 拿不准先看 `doctor` 的 `[doctor] 载荷:在用 …;未被任何安装行引用 […]` 那一行。
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
+
87
118
  凭据优先级:显式 key(`auth init` 写入)> 环境变量 `VOD_JAVA_API_KEY`(平台/CI 注入)
88
119
  > 匿名令牌自动领取(设备绑定)。**换 key 不需要重启宿主会话**:插件在每次调用引擎前现读
89
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.12",
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.12",
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.12",
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.12",
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.12",
3
- "commitSha": "b747ba182caad5b571b0aedd03a7032225f0890a",
4
- "builtAt": "2026-11-16T11:29:02",
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.12",
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.12"
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"
@@ -167,13 +167,13 @@ def install(args, packs: str) -> Path:
167
167
  from vod_mcp import __version__ as _ver
168
168
  pkg = f"dsh-vod-devkit@{_ver}"
169
169
  r = subprocess.run([dsh, "plugin", "--profile", profile, "add", pkg],
170
- capture_output=True, text=True, timeout=300)
170
+ capture_output=True, text=True, timeout=60)
171
171
  if r.returncode != 0:
172
172
  print(f"[vod-devkit] dsh plugin add {pkg} 失败,回落不钉版本:"
173
173
  f"{(r.stderr or r.stdout).strip()[-200:]}", file=sys.stderr)
174
174
  r = subprocess.run([dsh, "plugin", "--profile", profile,
175
175
  "add", "dsh-vod-devkit"],
176
- capture_output=True, text=True, timeout=300)
176
+ capture_output=True, text=True, timeout=60)
177
177
  if r.returncode != 0:
178
178
  print(f"[vod-devkit] dsh plugin add 失败:{(r.stderr or r.stdout).strip()[-300:]}",
179
179
  file=sys.stderr)
@@ -178,4 +178,75 @@ def residue() -> list:
178
178
  if not base.is_dir():
179
179
  return []
180
180
  return [p for p in sorted(base.iterdir())
181
- if p.is_dir() and not (p / "payload.json").exists()]
181
+ if p.is_dir() and not (p / "payload.json").exists()]
182
+
183
+
184
+ def _vkey(name: str) -> tuple:
185
+ """版本目录名排序键(0.5.9 < 0.5.10 < 0.5.11;非数字段落当 0,不抛异常)。"""
186
+ out = []
187
+ for part in str(name).replace("-", ".").split("."):
188
+ out.append(int(part) if part.isdigit() else 0)
189
+ return tuple(out)
190
+
191
+
192
+ def _tree_size(p: Path) -> int:
193
+ try:
194
+ return sum(f.stat().st_size for f in p.rglob("*") if f.is_file())
195
+ except OSError:
196
+ return 0
197
+
198
+
199
+ def prune_candidates(rows=None, keep: int = 0) -> list:
200
+ """可清理的旧载荷清单 —— 只认安装器自己落过的,且没有宿主在跑(D3,0.5.13)。
201
+
202
+ 约束(负责人 2026-11-16 定案):
203
+ · 只删清单内:必须是 `<payload_home>/payloads/<ver>/` 且带 `payload.json`
204
+ (= stage() 落的),绝不按 glob 删目录;
205
+ · 保留当前版本,以及任何安装行 payloadDir 指向的版本(在用的不碰);
206
+ · keep>0 时额外保留最新的 keep 份;
207
+ · 只读 payloads/ 目录,不碰机器级 state(令牌/账本)。
208
+ 返回 [(path, version, size_bytes)],按版本升序(最旧的在前)。
209
+ """
210
+ from vod_mcp import __version__
211
+ base = payload_home() / "payloads"
212
+ if not base.is_dir():
213
+ return []
214
+ used = set()
215
+ for r in (rows or []):
216
+ d = str(r.get("payloadDir") or "").strip()
217
+ if d:
218
+ try:
219
+ used.add(str(Path(d).resolve()))
220
+ except OSError:
221
+ used.add(d)
222
+ cand = []
223
+ for d in sorted(base.iterdir(), key=lambda p: _vkey(p.name)):
224
+ if not d.is_dir() or not (d / "payload.json").exists():
225
+ continue
226
+ try:
227
+ if str(d.resolve()) in used:
228
+ continue
229
+ except OSError:
230
+ continue
231
+ if d.name == __version__:
232
+ continue
233
+ cand.append(d)
234
+ if keep > 0:
235
+ cand = cand[:-keep] if len(cand) > keep else []
236
+ return [(d, d.name, _tree_size(d)) for d in cand]
237
+
238
+
239
+ def remove_payloads(cands, quiet: bool = False) -> tuple:
240
+ """按清单删除载荷目录:单条失败记录后继续,返回 (removed, failed)。"""
241
+ removed, failed = [], []
242
+ for path, ver, _size in cands:
243
+ try:
244
+ shutil.rmtree(path)
245
+ removed.append(str(path))
246
+ if not quiet:
247
+ print(f"removed old payload {ver}: {path}")
248
+ except OSError as e: # noqa: BLE001 单条失败不中断整体
249
+ failed.append((str(path), str(e)))
250
+ if not quiet:
251
+ print(f"[warn] 删除失败 {path}: {e}")
252
+ return removed, failed
@@ -5,7 +5,7 @@
5
5
  2. 外部无 DB 直连路径(护栏 deny 兜底)
6
6
  3. 任务 ID 是唯一对账主键,写类工具返回一律携带
7
7
  """
8
- __version__ = "0.5.12"
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"
@@ -167,13 +167,13 @@ def install(args, packs: str) -> Path:
167
167
  from vod_mcp import __version__ as _ver
168
168
  pkg = f"dsh-vod-devkit@{_ver}"
169
169
  r = subprocess.run([dsh, "plugin", "--profile", profile, "add", pkg],
170
- capture_output=True, text=True, timeout=300)
170
+ capture_output=True, text=True, timeout=60)
171
171
  if r.returncode != 0:
172
172
  print(f"[vod-devkit] dsh plugin add {pkg} 失败,回落不钉版本:"
173
173
  f"{(r.stderr or r.stdout).strip()[-200:]}", file=sys.stderr)
174
174
  r = subprocess.run([dsh, "plugin", "--profile", profile,
175
175
  "add", "dsh-vod-devkit"],
176
- capture_output=True, text=True, timeout=300)
176
+ capture_output=True, text=True, timeout=60)
177
177
  if r.returncode != 0:
178
178
  print(f"[vod-devkit] dsh plugin add 失败:{(r.stderr or r.stdout).strip()[-300:]}",
179
179
  file=sys.stderr)
@@ -178,4 +178,75 @@ def residue() -> list:
178
178
  if not base.is_dir():
179
179
  return []
180
180
  return [p for p in sorted(base.iterdir())
181
- if p.is_dir() and not (p / "payload.json").exists()]
181
+ if p.is_dir() and not (p / "payload.json").exists()]
182
+
183
+
184
+ def _vkey(name: str) -> tuple:
185
+ """版本目录名排序键(0.5.9 < 0.5.10 < 0.5.11;非数字段落当 0,不抛异常)。"""
186
+ out = []
187
+ for part in str(name).replace("-", ".").split("."):
188
+ out.append(int(part) if part.isdigit() else 0)
189
+ return tuple(out)
190
+
191
+
192
+ def _tree_size(p: Path) -> int:
193
+ try:
194
+ return sum(f.stat().st_size for f in p.rglob("*") if f.is_file())
195
+ except OSError:
196
+ return 0
197
+
198
+
199
+ def prune_candidates(rows=None, keep: int = 0) -> list:
200
+ """可清理的旧载荷清单 —— 只认安装器自己落过的,且没有宿主在跑(D3,0.5.13)。
201
+
202
+ 约束(负责人 2026-11-16 定案):
203
+ · 只删清单内:必须是 `<payload_home>/payloads/<ver>/` 且带 `payload.json`
204
+ (= stage() 落的),绝不按 glob 删目录;
205
+ · 保留当前版本,以及任何安装行 payloadDir 指向的版本(在用的不碰);
206
+ · keep>0 时额外保留最新的 keep 份;
207
+ · 只读 payloads/ 目录,不碰机器级 state(令牌/账本)。
208
+ 返回 [(path, version, size_bytes)],按版本升序(最旧的在前)。
209
+ """
210
+ from vod_mcp import __version__
211
+ base = payload_home() / "payloads"
212
+ if not base.is_dir():
213
+ return []
214
+ used = set()
215
+ for r in (rows or []):
216
+ d = str(r.get("payloadDir") or "").strip()
217
+ if d:
218
+ try:
219
+ used.add(str(Path(d).resolve()))
220
+ except OSError:
221
+ used.add(d)
222
+ cand = []
223
+ for d in sorted(base.iterdir(), key=lambda p: _vkey(p.name)):
224
+ if not d.is_dir() or not (d / "payload.json").exists():
225
+ continue
226
+ try:
227
+ if str(d.resolve()) in used:
228
+ continue
229
+ except OSError:
230
+ continue
231
+ if d.name == __version__:
232
+ continue
233
+ cand.append(d)
234
+ if keep > 0:
235
+ cand = cand[:-keep] if len(cand) > keep else []
236
+ return [(d, d.name, _tree_size(d)) for d in cand]
237
+
238
+
239
+ def remove_payloads(cands, quiet: bool = False) -> tuple:
240
+ """按清单删除载荷目录:单条失败记录后继续,返回 (removed, failed)。"""
241
+ removed, failed = [], []
242
+ for path, ver, _size in cands:
243
+ try:
244
+ shutil.rmtree(path)
245
+ removed.append(str(path))
246
+ if not quiet:
247
+ print(f"removed old payload {ver}: {path}")
248
+ except OSError as e: # noqa: BLE001 单条失败不中断整体
249
+ failed.append((str(path), str(e)))
250
+ if not quiet:
251
+ print(f"[warn] 删除失败 {path}: {e}")
252
+ return removed, failed
@@ -3,7 +3,8 @@ import argparse
3
3
  import os
4
4
  import sys
5
5
 
6
- from vodkit_cli import auth_cmd, common, doctor, install, packs_cmd, uninstall, update
6
+ from vodkit_cli import (auth_cmd, common, doctor, install, packs_cmd, prune_cmd,
7
+ uninstall, update)
7
8
 
8
9
 
9
10
  def main():
@@ -52,6 +53,8 @@ def main():
52
53
  help="只装技能,不动宿主 MCP 配置(MCP 已由别处/手工注册时用)")
53
54
  sp.add_argument("--no-local-ledger", action="store_true",
54
55
  help="关闭本地提交账本(企业数据驻留要求;vod_list_submitted 将不可用)")
56
+ sp.add_argument("--refresh-product-catalog", action="store_true",
57
+ help="强制向引擎重拉产品名录(默认命中 state 里 7 天内的缓存,省令牌配额)")
55
58
  sp.set_defaults(fn=install.cmd_install)
56
59
  for name, fn in (("status", doctor.cmd_status), ("doctor", doctor.cmd_doctor),
57
60
  ("verify", doctor.cmd_verify), ("update", update.cmd_update),
@@ -95,6 +98,20 @@ def main():
95
98
  sp_auth.add_argument("--apply", action="store_true",
96
99
  help="真正写盘(缺省只校验并显示指纹)")
97
100
  sp_auth.set_defaults(fn=auth_cmd.cmd_auth)
101
+ def _prune(a):
102
+ """cmd_prune 返回退出码(0=干净/no-op,1=有删除失败,2=参数/确认问题)。"""
103
+ sys.exit(prune_cmd.cmd_prune(a))
104
+
105
+ sp_prune = sub.add_parser("prune", help="显式清理旧载荷(默认 dry-run;二次确认)")
106
+ sp_prune.add_argument("--payloads", action="store_true",
107
+ help="清理旧载荷版本(当前唯一的清理对象)")
108
+ sp_prune.add_argument("--keep", type=int, default=0,
109
+ help="额外保留最新的 N 份旧载荷(默认 0)")
110
+ sp_prune.add_argument("--apply", action="store_true",
111
+ help="真正删除(缺省只打印清单,dry-run 优先)")
112
+ sp_prune.add_argument("--yes", action="store_true",
113
+ help="非交互环境确认删除(交互式会再问一次 y/N)")
114
+ sp_prune.set_defaults(fn=_prune)
98
115
  sub.add_parser("build-info").set_defaults(fn=lambda a: common.write_build_info(strict=False))
99
116
 
100
117
  def _serve(a):
@@ -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
@@ -0,0 +1,75 @@
1
+ """prune:显式清理旧载荷(D3,2026-11-16 负责人定案)。
2
+
3
+ 为什么单独一个命令、而不是 install 顺手删:
4
+ · 安装时删用户文件不可接受(无法回滚、误删风险高、用户没预期);
5
+ · 卸载才清理又太晚(很多机器只升级不卸载,旧载荷永远留着)。
6
+
7
+ 约束(定案原文的落法):
8
+ · 只删清单内:`payload.prune_candidates()` 只认 `<payload_home>/payloads/<ver>/`
9
+ 且带 `payload.json`(stage() 落的)的目录,绝不 glob 盲删;
10
+ · 保留当前版本 + 任何安装行 payloadDir 指向的版本;`--keep N` 额外保留最新 N 份;
11
+ · 默认 dry-run(只打印清单);真删要 `--apply`;
12
+ · 二次确认:交互式 y/N;非 tty 必须 `--yes`,否则拒绝;
13
+ · 逐条打印 路径/版本/大小;
14
+ · 只删载荷目录,不碰机器级 state;
15
+ · 单条删除失败记录后继续,最后以非零退出码收尾。
16
+ """
17
+ import sys
18
+
19
+ from vod_mcp import payload as _payload
20
+
21
+
22
+ def _fmt(n: float) -> str:
23
+ for unit in ("B", "KB", "MB", "GB"):
24
+ if n < 1024 or unit == "GB":
25
+ return f"{n:.0f}{unit}" if unit == "B" else f"{n:.1f}{unit}"
26
+ n /= 1024
27
+ return f"{n:.1f}GB"
28
+
29
+
30
+ def _rows() -> list:
31
+ from vodkit_cli import common
32
+ import json
33
+ p = common.manifest_path()
34
+ if not p.exists():
35
+ return []
36
+ try:
37
+ mf = json.loads(p.read_text(encoding="utf-8"))
38
+ except (OSError, ValueError):
39
+ return []
40
+ return mf.get("installs") or ([mf] if mf.get("target") else [])
41
+
42
+
43
+ def cmd_prune(args) -> int:
44
+ if not getattr(args, "payloads", False):
45
+ print("只支持 --payloads(当前唯一的清理对象)", file=sys.stderr)
46
+ return 2
47
+ rows = _rows()
48
+ keep = int(getattr(args, "keep", 0) or 0)
49
+ cands = _payload.prune_candidates(rows, keep=keep)
50
+ if not cands:
51
+ print("没有可清理的旧载荷(当前版本与安装行在用的都保留)")
52
+ return 0
53
+ total = sum(size for _p, _v, size in cands)
54
+ print(f"可清理 {len(cands)} 份旧载荷,共 {_fmt(total)}"
55
+ + (f"(额外保留最新 {keep} 份)" if keep else ""))
56
+ for path, ver, size in cands:
57
+ print(f" - {ver:<10s} {_fmt(size):>9s} {path}")
58
+ print(" 保留:当前版本 + 安装行在用的版本 + 机器级 state(不在本命令范围内)")
59
+
60
+ if not getattr(args, "apply", False):
61
+ print("(dry-run:未删除。确认后加 --apply 执行)")
62
+ return 0
63
+ if not getattr(args, "yes", False):
64
+ if not sys.stdin.isatty():
65
+ print("非交互环境需加 --yes 才执行删除(二次确认)", file=sys.stderr)
66
+ return 2
67
+ ans = input(f"确认删除上述 {len(cands)} 份载荷?[y/N] ").strip().lower()
68
+ if ans not in ("y", "yes"):
69
+ print("已取消")
70
+ return 0
71
+
72
+ removed, failed = _payload.remove_payloads(cands)
73
+ print(f"已删除 {len(removed)} 份"
74
+ + (f",失败 {len(failed)} 份(见上)" if failed else ""))
75
+ return 1 if failed else 0
@@ -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
  未命中/目录不可达一律拒绝安装并给可执行引导(宁可不装不可装错)。
@@ -166,10 +210,35 @@ def _validate_product_or_exit(product: str, base: str) -> bool:
166
210
  with urllib.request.urlopen(req, timeout=10) as resp:
167
211
  return resp.status, resp.read().decode("utf-8", "replace")
168
212
 
213
+ def _state_identity() -> tuple:
214
+ """机器级 state 里已存的匿名令牌 + 它的设备锚点(install_nonce)。
215
+
216
+ 装机校验**不该每次新签一枚**:引擎对"同网络当日签发次数"有限流
217
+ (实测撞到 100/日 → 429,整批装机全被挡)。复用 state 的令牌既省配额,
218
+ 又避免一次新的设备锚点漂移;device 必须用 state 的 install_nonce,
219
+ 否则令牌与设备不配对(S1 设备绑定)。
220
+ """
221
+ try:
222
+ from vod_mcp import runtime_state as _rt
223
+ cfg = _rt._runtime_cfg() or {}
224
+ if str(cfg.get("token_tier") or "") != "anonymous":
225
+ return ("", "")
226
+ tok = str(cfg.get("java_key") or "")
227
+ dev = str(_rt._install_nonce() or "")
228
+ return (tok, dev) if (tok and dev) else ("", "")
229
+ except Exception: # noqa: BLE001 读不到就当没有,回落新签
230
+ return ("", "")
231
+
169
232
  def _catalog_once():
170
- """一个回合:新设备锚点 → 领令牌 → 读目录(一次校验只耗一枚令牌)。"""
171
- device = uuid.uuid4().hex[:32]
172
- token = key or _mint(device)
233
+ """一个回合:有 state 令牌就复用,否则新设备锚点 + 领令牌 → 读目录。"""
234
+ reuse_tok, reuse_dev = _state_identity()
235
+ if key:
236
+ device, token = uuid.uuid4().hex[:32], key
237
+ elif reuse_tok:
238
+ device, token = reuse_dev, reuse_tok
239
+ else:
240
+ device = uuid.uuid4().hex[:32]
241
+ token = _mint(device)
173
242
  status, text = _get(f"{base}{api_prefix}/external/meta", token, device)
174
243
  data = (json.loads(text) or {}).get("data") or {}
175
244
  cat = data.get("productCatalog")
@@ -179,16 +248,35 @@ def _validate_product_or_exit(product: str, base: str) -> bool:
179
248
  cat = data if isinstance(data, list) else None
180
249
  return cat
181
250
 
182
- catalog, unauthorized, last_exc = None, False, None
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
+
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)")
183
263
  for attempt in (1, 2):
264
+ if catalog is not None: # 缓存命中:本地比对即可,不打引擎
265
+ break
184
266
  try:
185
267
  catalog = _catalog_once()
268
+ if catalog:
269
+ _write_catalog_cache(base, catalog)
186
270
  last_exc = None
187
271
  break
188
272
  except urllib.error.HTTPError as e:
189
273
  last_exc = e
190
274
  if e.code == 401:
191
275
  unauthorized = True
276
+ if e.code == 429:
277
+ # 限流:重试只会更糟(配额头是"当日/网络"),立刻停
278
+ rate_limited = True
279
+ break
192
280
  if attempt == 2:
193
281
  break
194
282
  except Exception as e: # noqa: BLE001 网络抖动也重试一次
@@ -197,7 +285,13 @@ def _validate_product_or_exit(product: str, base: str) -> bool:
197
285
  break
198
286
 
199
287
  if catalog is None:
200
- if unauthorized:
288
+ if rate_limited:
289
+ print("[vod-devkit] 产品校验失败:令牌签发被限流(HTTP 429,同网络当日签发次数上限)。\n"
290
+ " 这不是装机器本身的问题——安装器每校验一次都要一枚匿名令牌,"
291
+ "密集重装/联调会把日配额打满。\n"
292
+ " 处置:配 VOD_JAVA_API_KEY 走正式 key(不占匿名配额);或明天再试;"
293
+ "或找 VOD 运营调整限流。", file=sys.stderr)
294
+ elif unauthorized:
201
295
  print("[vod-devkit] 产品校验失败:引擎鉴权异常(HTTP 401)——刚签发的匿名令牌被"
202
296
  "校验侧拒绝。\n"
203
297
  " 典型原因:引擎多实例的令牌存储/缓存不同步(重试一次通常就过),"
@@ -222,6 +222,13 @@ def _clean_global(rows: list, remaining: list | None = None) -> None:
222
222
  continue
223
223
  shutil.rmtree(res, ignore_errors=True)
224
224
  print("removed payload residue:", res)
225
+ # 旧载荷(带 payload.json 的安装器产物):与 `prune --payloads` 同一实现
226
+ #(D3 定案:显式、只删清单内、保留 remaining 宿主仍在引用的版本)。
227
+ old = _payload.prune_candidates(remaining or [])
228
+ if old:
229
+ _removed, _failed = _payload.remove_payloads(old)
230
+ if _failed:
231
+ print(f"[warn] 旧载荷删除失败 {len(_failed)} 份(见上)")
225
232
  # D-token-machine-1:机器级 state(跨版本/跨宿主共享的那一份)。
226
233
  state = _paths.machine_state_home()
227
234
  if remaining: