@stofone/dsh-agent-roster 0.10.5 → 0.10.7

package/CHANGELOG.md

@@ -4,6 +4,27 @@
 
 ## [Unreleased]
 
+## [0.10.7] - 2026-11-03
+
+### Documentation
+
+- README (both languages) now describes the cache that knows its own version, the two remote-source
+  diagnostics added in 0.10.6, and a `lib/` listing that matches what is actually there — the previous one
+  still named only the v1-era modules and omitted `compile2`/`plan`/`migrate`/`run`/`role`/`roster2`.
+- Test count corrected to 297/297.
+
+## [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 +533,9 @@
 - 工具返回值含 `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.7...main
+[0.10.7]: https://github.com/dsh-agent-roster/dsh-agent-roster/compare/v0.10.6...v0.10.7
+[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/README.md

@@ -392,6 +392,9 @@ repository's `index/registry.json`, and anyone who subscribes can see them in th
 - **How often it refreshes**: TTL **one hour** — that is the unauthenticated GitHub budget of 60 requests/hour.
   `?refresh=1` (or the tools' `refresh`) bypasses the cache, throttled to one try per 60 seconds so the quota is not
   burned. On failure the last cached index is reused and labelled "cached (fetch failed)" in the panel.
+  The cache records **which shape of index it holds** (`CACHE_VERSION`): a plugin upgrade that changes the
+  index shape invalidates old caches and refetches once, so "I upgraded but the panel still 404s" is not a
+  thing you have to debug by deleting a directory.
 - **Pulling**: writes are idempotent and report one of `created`, `updated` (explicit overwrite), `unchanged`
   (same content, nothing written) or `conflict` (the local copy differs and is **not** overwritten by default).
   Conflicts are yours to resolve: merge in the editor, or pull again with `overwrite` in the request body.
@@ -441,7 +444,7 @@ Validation reports errors, warnings and infos with `file`, `path` and `reason`.
 - safety: `reserved-character` (`^`, `$`, `|`, braces), `forbidden-content` (prompt-injection patterns), `single-line-required`
 - limits: `string-too-long`, `too-many-members`, `too-many-values`
 - library level: `library-missing`, `library-unusable`, `missing-roster-file`, `multiple-roster-files`, `unexpected-file`, `unreadable-file`, `unreadable-dir`, `duplicate-roster-id`, `tool-policy-cross-check-skipped`
-- remote sources: `index-unreachable`, `index-invalid`, `index-refresh-throttled`, `index-source-invalid`, `collection-fetch-failed`, `collection-not-found`
+- remote sources: `index-unreachable`, `index-invalid`, `index-refresh-throttled`, `index-source-invalid`, `collection-fetch-failed`, `collection-not-found`, `index-may-be-stale` (a v1-path fetch failed on a collection that has no `files` map — the index is probably older than the library), `collection-roster-needs-roles` (the entry points at a v2 assembly, which cannot travel as one file)
 
 An empty library is not an error. A missing one is reported as info, not error. `tool-policy-cross-check-skipped` is emitted **once per library** (not once per roster) when no `knownToolPolicies` are configured — a per-roster warning would turn one fact into n lines of noise.
 
@@ -462,8 +465,11 @@ Layout:
 
 ```
 index.js          host plugin: Config, apply, six routes
-lib/              format, parse, validate, registry, bridge, verify, render, library,
-                  config-view, json, http, write, service, teams-state, tools
+lib/              reading: format, format-v2, frontmatter, parse, validate, role, roster2,
+                  capabilities, organization, registry, remote, library, home
+                  compiling: compile2, plan, migrate, run
+                  speaking to the runtime: bridge, verify, diff, digest, render, tools, service,
+                  teams-state, captain, write, apply, serialize, config-view, json, http
 client.js         client plugin: sidebar entry, main panel (rosters/teams/health), settings section
 locale/           panel + listing dictionaries (en/zh)
 schema/           roster v1 / role v1 / roster v2 / compiled v1 / capabilities / organization / registry
@@ -480,7 +486,7 @@ test/             unit tests
 
 Verified on this machine:
 
-- `npm test` — 295/295 passing (format, parse, validate, registry, paths, bridge, verify buckets, digests and provenance, roster diff, capability requirements and the capability gate, library organization, registry schema, lossless JSON, write plan/apply, all routes, panel snapshot and hints, dictionary consistency, tool contracts, client loader contract, library snapshot, config view, package manifest, declared fields and captain block, schema/constant alignment, the v2 role/roster/compiled layers and their schema alignment, v1→v2 migration, run records feeding the plan, remote registry and one-click install).
+- `npm test` — 297/297 passing (format, parse, validate, registry, paths, bridge, verify buckets, digests and provenance, roster diff, capability requirements and the capability gate, library organization, registry schema, lossless JSON, write plan/apply, all routes, panel snapshot and hints, dictionary consistency, tool contracts, client loader contract, library snapshot, config view, package manifest, declared fields and captain block, schema/constant alignment, the v2 role/roster/compiled layers and their schema alignment, v1→v2 migration, run records feeding the plan, remote registry and one-click install).
 - `npm run smoke` — `apply()` registers all six tools through a real `defineTool` from a DSH bundle; `roster_list` / `roster_show` / `roster_create` / `roster_verify` / `roster_diff` execute, every output survives `lossless` checks, `path` overrides are honored, effect disposal runs cleanly. The same command then loads `client.js` against a stubbed module table and asserts the three slot registrations, style injection and effect disposal.
 - CLI: `validate --dir examples` returns exit 0 over both example libraries.
 - Installed into a real profile with the plugin manager (`plugin_manager install_bundle` against this directory → `link:` dependency + bundle entry); the profile re-reads the linked files on restart.

package/README.zh.md

@@ -369,6 +369,8 @@ node bin/cli.mjs compile --roster examples-orchestration/rosters/core-review \
   留空 = 只用官方源 `dsh-agent-roster/dsh-agent-roster` 的 `index/registry.json`；显式写 `false` 才彻底不连远端。
 - **多久更新一次**：TTL **一小时**——等于未认证 GitHub 的 60 次/小时配额。`?refresh=1`（或工具的 `refresh`）
   可绕过缓存，但 60 秒内最多一次，避免把配额烧光。拉取失败时沿用上次缓存并在页面上写明「缓存（拉取失败）」。
+  缓存里记着**它存的是哪一种形状的索引**（`CACHE_VERSION`）：升级插件后如果索引形状变了，旧缓存自动失效、重取一次，
+  所以「我升级了，面板却还 404」不需要靠删目录来排查。
 - **拉取到本机**：写入是幂等的，四种结果都会报给你——
   `created`（新写入）、`updated`（显式覆盖）、`unchanged`（内容一致，不写盘）、`conflict`（本地不一样，**默认不覆盖**）。
   冲突要你自己决定：要么在编辑器里合并，要么再点一次「拉取到本机」并在请求里带 `overwrite`。
@@ -417,7 +419,7 @@ node bin/cli.mjs compile --roster examples-orchestration/rosters/core-review \
 - 安全：`reserved-character`（`^`、`$`、`|`、花括号）、`forbidden-content`（提示注入特征）、`single-line-required`
 - 上限：`string-too-long`、`too-many-members`、`too-many-values`
 - 档案库级：`library-missing`、`library-unusable`、`missing-roster-file`、`multiple-roster-files`、`unexpected-file`、`unreadable-file`、`unreadable-dir`、`duplicate-roster-id`、`tool-policy-cross-check-skipped`
-- 远端源：`index-unreachable`、`index-invalid`、`index-refresh-throttled`、`index-source-invalid`、`collection-fetch-failed`、`collection-not-found`
+- 远端源：`index-unreachable`、`index-invalid`、`index-refresh-throttled`、`index-source-invalid`、`collection-fetch-failed`、`collection-not-found`、`index-may-be-stale`（没有 `files` 映射却回退到 v1 路径并失败——索引多半比档案库旧）、`collection-roster-needs-roles`（条目指向 v2 组装，而组装不能以单文件旅行）
 
 空档案库不是错误；目录不存在只算 info。`tool-policy-cross-check-skipped` **每座档案库只发一条**（不是每份档案一条）——没配 `knownToolPolicies` 是一件库级的事，按档案重复只会把一个事实放大成 n 行噪音。
 
@@ -436,8 +438,11 @@ node scripts/check-locale.mjs   # client.js 里的静态 t() 键必须两本词
 
 ```
 index.js          宿主半边：Config、apply、六条路由
-lib/              format / parse / validate / registry / bridge / verify / render / library /
-                  config-view / json / http / write / service / teams-state / tools
+lib/              读：format / format-v2 / frontmatter / parse / validate / role / roster2 /
+                  capabilities / organization / registry / remote / library / home
+                  编译：compile2 / plan / migrate / run
+                  对运行时说话：bridge / verify / diff / digest / render / tools / service /
+                  teams-state / captain / write / apply / serialize / config-view / json / http
 client.js         客户端半边：左侧栏图标 + 主面板（档案/团队/体检）+ 设置页小节
 locale/           面板与列表词典（en/zh）
 schema/           roster v1 / role v1 / roster v2 / compiled v1 / capabilities / organization / registry
@@ -454,7 +459,7 @@ test/             单测
 
 本机已验证：
 
-- `npm test` —— 295/295 通过（格式、解析、校验、扫描、路径、桥接、核对四桶、摘要与溯源、档案差异、能力要求与能力闸门、档案库组织、索引 schema、无损 JSON、写入计划与执行、六条路由、快照与提示、两本词典一致、工具契约、客户端加载器契约、包清单、配置视图、样式 token 约束、声明层字段与队长段、schema 与常量对齐、v2 角色/组装/编译三层及其 schema 对齐、v1→v2 迁移、执行回执并入施工图）。
+- `npm test` —— 297/297 通过（格式、解析、校验、扫描、路径、桥接、核对四桶、摘要与溯源、档案差异、能力要求与能力闸门、档案库组织、索引 schema、无损 JSON、写入计划与执行、六条路由、快照与提示、两本词典一致、工具契约、客户端加载器契约、包清单、配置视图、样式 token 约束、声明层字段与队长段、schema 与常量对齐、v2 角色/组装/编译三层及其 schema 对齐、v1→v2 迁移、执行回执并入施工图）。
 - `npm run smoke` —— 用真实 DSH bundle 的 `defineTool` 注册六个工具，逐个调用：输出全部通过无损校验、`path` 覆盖生效、释放干净；同一条命令随后用桩模块表加载 `client.js`，断言三处槽位注册、样式只注入一次、effect 可回收。
 - CLI：`validate --dir examples` 对两座示例库退出码 0。
 - 用插件管理器真的装进了本机 profile（`plugin_manager install_bundle` 指向本仓库 → `link:` 依赖 + bundle 条目），重启后按链接读取本仓库文件。

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.7",
   "description": "多 Agent 团队的静态成员档案定义与校验层：档案库在面板里看得见、改得动，团队成员的人设、模型与工具边界固化成可校验、可版本化的文件，并在 dsh-agent-teams 创建成员时把档案桥接给运行时。",
   "type": "module",
   "main": "index.js",