@stofone/dsh-agent-roster 0.10.5 → 0.10.6

package/CHANGELOG.md

@@ -4,6 +4,18 @@
 
 ## [Unreleased]
 
+## [0.10.6] - 2026-11-03
+
+### Fixed
+
+- **An index cached before an upgrade kept feeding the old shape.** The cache stored an index document
+  with no notion of what shape it had, so after upgrading to 0.10.3 — the release that added
+  `collection.files` — the panel kept reading a cached index without `files`, fell back to the v1 path, and
+  404'd. Caches now carry `CACHE_VERSION`; a mismatch refetches once.
+- A failed fetch on the v1 fallback path now says *why* it is likely failing: if the collection has no
+  `files` mapping, the diagnostic points at a stale index (refresh, or delete `.index-cache`) instead of
+  leaving a bare `HTTP 404`.
+
 ## [0.10.5] - 2026-11-03
 
 ### Fixed
@@ -512,7 +524,8 @@
 - 工具返回值含 `undefined` 键，运行时按 `value is not lossless JSON` 整次拒绝；缺失值统一写 `null`，
   且所有返回值先过 `lib/json.js#lossless`。
 
-[Unreleased]: https://github.com/dsh-agent-roster/dsh-agent-roster/compare/v0.10.5...main
+[Unreleased]: https://github.com/dsh-agent-roster/dsh-agent-roster/compare/v0.10.6...main
+[0.10.6]: https://github.com/dsh-agent-roster/dsh-agent-roster/compare/v0.10.5...v0.10.6
 [0.10.5]: https://github.com/dsh-agent-roster/dsh-agent-roster/compare/v0.10.4...v0.10.5
 [0.10.4]: https://github.com/dsh-agent-roster/dsh-agent-roster/compare/v0.10.3...v0.10.4
 [0.10.3]: https://github.com/dsh-agent-roster/dsh-agent-roster/compare/v0.10.2...v0.10.3

package/lib/remote.js

@@ -49,6 +49,15 @@ export const DEFAULT_REGISTRY_URL =
 /** 缓存目录名，放在档案库根下，跟着 `$DSH_HOME` 走。 */
 export const CACHE_DIR_NAME = ".index-cache";
 
+/**
+ * 索引缓存的语义版本。
+ *
+ * 缓存里存的是**索引的形状**，而形状会随插件版本变（0.10.3 给 collection 加了 `files`）。
+ * 不认版本号的缓存会在升级后继续提供旧形状，表现就是"面板明明装了新版，仍然 404"。
+ * 索引语义再变时把这里 +1，老缓存自动失效、重取一次。
+ */
+export const CACHE_VERSION = 2;
+
 /** entry 文件所在的仓库前缀（只支持 GitHub raw，不引入 git 协议）。 */
 export const GITHUB_RAW = "https://raw.githubusercontent.com";
 
@@ -266,6 +275,7 @@ export async function loadRegistry(source, options = {}) {
       });
     }
     writeCache(cachePath, {
+      cacheVersion: CACHE_VERSION,
       sourceId: source.id,
       fetchedAt: current,
       etag: fetched.etag,
@@ -567,6 +577,17 @@ export async function fetchCollection(collection, options = {}) {
     }
     if (loaded === null) {
       diagnostics.push(diagnostic("warn", "collection-fetch-failed", `${collection.id}/${rosterId} 拉取失败：${lastError || "未知原因"}`));
+      // 没有 files 映射时退回的是 v1 路径；v2 库在那条路径上必然 404。
+      // 这时最可能的原因是"索引是升级前缓存的"，提示一句比让用户猜有用。
+      if (listedPath === null) {
+        diagnostics.push(
+          diagnostic(
+            "info",
+            "index-may-be-stale",
+            `${collection.id} 的索引里没有 files 映射，回退到了 v1 路径；若刚升级过插件，先刷新索引（缓存按版本失效，也可删 .index-cache）`,
+          ),
+        );
+      }
       continue;
     }
     const parsed = parseDocumentText(loaded.text, { file: loaded.url });
@@ -669,6 +690,7 @@ export function cachePathFor(cacheDir, id) {
 function readCache(file) {
   try {
     const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+    if (parsed?.cacheVersion !== CACHE_VERSION) return null;
     if (typeof parsed?.fetchedAt !== "number" || typeof parsed?.document !== "object" || parsed.document === null) return null;
     return parsed;
   } catch {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stofone/dsh-agent-roster",
-  "version": "0.10.5",
+  "version": "0.10.6",
   "description": "多 Agent 团队的静态成员档案定义与校验层：档案库在面板里看得见、改得动，团队成员的人设、模型与工具边界固化成可校验、可版本化的文件，并在 dsh-agent-teams 创建成员时把档案桥接给运行时。",
   "type": "module",
   "main": "index.js",