opencode-metrics-plugin 0.3.3 → 0.3.4

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.3.4（2026-09-14）
+
+- 修复 0.3.3 发布事故：package.json 误带 UTF-8 BOM，npm 可安装但 opencode 解析插件清单失败并**静默跳过加载**——所有 0.3.3 用户完全不采集、不上传、日志无任何痕迹。升级本版后必须删除插件缓存并重启 opencode（Windows `%USERPROFILE%\.cache\opencode\packages\opencode-metrics-plugin*`，macOS `~/Library/Caches/opencode/packages/` 同名目录）；事故期间未采集的会话无法补录，装好后孤儿补传会自动补传 7 天内未上终态的历史快照。
+- 用户可编辑文件读取容忍 BOM：`opencode-metrics.json(.jsonc)` 与 `agc-apiclient.json` 用 Windows PowerShell 或旧版编辑器保存不再静默失效。
+- 发布防复发：`prepublishOnly` 增加 package.json BOM 守卫，命中即发布失败。
+
 ## 0.3.3（2026-09-12）
 
 - session-end 三层保障，修复宿主进程突然死亡导致会话终态包永不产出的问题：

package/README.md

@@ -4,7 +4,7 @@
 
 - **开箱即用**：宿主只需在 `opencode.json` 加一行，无需任何配置
 - **实时落盘**：会话进行中每 2s 增量写盘，中途退出不丢数据
-- **开箱即传**：上传默认开启（包内 AGC 凭证），`git commit` / 会话结束自动打包上传，安卓源码工程自动剔除，`upload.enabled: false` 可关
+- **开箱即传**：上传默认开启（包内 AGC 凭证），`git commit` / 根会话 task 完成 / 会话结束自动打包上传，安卓源码工程自动剔除，`upload.enabled: false` 可关
 - **独立配置文件**：`.opencode/opencode-metrics.json(.jsonc)` 支持注释，存在即完全接管内联配置；用户目录 `~/.config/opencode/` 可放全局兜底配置
 - **失败不丢**：上传失败的包保留在 `failed/`（与云端路径同构，可手动上传），下次启动自动补偿重传
 - **零打扰**：不修改工作区、不执行 clean
@@ -71,10 +71,16 @@
 
 | 平台 | 路径 |
 |---|---|
-| Windows | `%LOCALAPPDATA%\opencode-metrics-plugin\Log\{metrics,events}`、`...\Log\log\plugin\YYYYMMDD.log`（运行日志按日期归档，保留 30 天）、`...\Data\upload-staging` |
+| Windows | `%LOCALAPPDATA%\opencode-metrics-plugin\Log\{metrics,events}`（metrics 下另有 `.sent/` 已传终态标记）、`...\Log\log\plugin\YYYYMMDD.log`（运行日志按日期归档，保留 30 天）、`...\Data\upload-staging` |
 | Linux | `~/.local/state/opencode-metrics-plugin/{metrics,events}` |
 | macOS | `~/Library/Logs/opencode-metrics-plugin/{metrics,events}` |
 
+## 升级与排障
+
+- **升级不生效**：opencode 将插件缓存在本机且不自动更新，升级后须删缓存再重启——Windows `%USERPROFILE%\.cache\opencode\packages\` 下的 `opencode-metrics-plugin*` 目录，macOS `~/Library/Caches/opencode/packages/` 下同名目录。
+- **装上完全没反应（日志无 `[MetricsPlugin] started`）**：若装的是 0.3.3，系发布事故——该版 package.json 误带 UTF-8 BOM，opencode 静默跳过插件（不采集、不上传、无报错）。升级 0.3.4+ 并删缓存即恢复；期间丢的会话无法补录，装好后 7 天内未上终态的老快照会被孤儿补传自动救回。
+- **验证插件已加载**：插件日志（`log/plugin/YYYYMMDD.log`）首屏出现 `[MetricsPlugin] started` 行。
+
 ## 配置项速查
 
 全部可选；独立文件与内联第二参字段相同。

package/dist/metrics/configLoader.js

@@ -58,7 +58,7 @@ function readFirstExisting(baseDirectory, names) {
     for (const name of names) {
         const candidate = path.join(baseDirectory, name);
         try {
-            return { configPath: candidate, raw: fs.readFileSync(candidate, "utf-8") };
+            return { configPath: candidate, raw: fs.readFileSync(candidate, "utf-8").replace(/^\uFEFF/, "") };
         }
         catch {
             // 该名字的文件不存在，尝试下一个

package/dist/metrics/upload/agcUploader.js

@@ -31,7 +31,7 @@ export function defaultAgcConfigPath() {
 export function loadAgcCredentials(configPath, tokenCacheDir) {
     let raw;
     try {
-        raw = fs.readFileSync(configPath, "utf-8");
+        raw = fs.readFileSync(configPath, "utf-8").replace(/^\uFEFF/, "");
     }
     catch (err) {
         return { ok: false, reason: `读取配置失败 ${configPath}: ${String(err)}` };

package/dist/metrics/upload/uploadManager.js

@@ -258,9 +258,9 @@ export function createUploadManager(options) {
         return scenarios.find((s) => s.enabled && s.events.includes("session.deleted"))?.label ?? "session-end";
     }
     /**
-     * 扫描 metrics 目录孤儿快照并补打 session-end 包：mtime 静默 [idleMs, maxAgeMs]
-     * 且不属于本进程活跃会话的快照视为孤儿。上传成功后快照即被删除，
-     * "文件仍在"天然等价于"终态未传出"，无需额外标记。
+     * 扫描 metrics 目录孤儿快照并补打 session-end 包：mtime 静默 [idleMs, maxAgeMs]、
+     * 无已传标记（metrics/.sent/<sessionId>）且不属于本进程活跃会话的快照视为孤儿。
+     * 快照原件永久保留为本地记录，已传标记才是防重复补传的依据。
      *
      * @param idleMs   静默下限（毫秒）
      * @param maxAgeMs 年龄上限（毫秒）

package/package.json

@@ -1,6 +1,6 @@
-{
+{
   "name": "opencode-metrics-plugin",
-  "version": "0.3.3",
+  "version": "0.3.4",
   "description": "opencode plugin: auto-records every session's metrics (tokens/rounds/steps/sub-agents/hvigor builds) to snapshot JSON. Zero DB, zero config. Pair with session-viewer for visualization.",
   "type": "module",
   "license": "MIT",
@@ -33,7 +33,7 @@
     "build": "node -e \"fs.rmSync('dist', { recursive: true, force: true })\" && tsc",
     "typecheck": "tsc --noEmit",
     "test": "tsx example/smoke.mts",
-    "prepublishOnly": "npm run build && npm test"
+    "prepublishOnly": "node -e \"if(require('fs').readFileSync('package.json','utf8').charCodeAt(0)===0xFEFF){console.error('package.json 含 BOM，禁止发布');process.exit(1)}\" && npm run build && npm test"
   },
   "engines": {
     "node": ">=18"