@stofone/dsh-agent-roster 0.10.6 → 0.11.0

package/CHANGELOG.md

@@ -4,6 +4,30 @@
 
 ## [Unreleased]
 
+## [0.11.0] - 2026-11-03
+
+### Changed
+
+- **Expanding a collection no longer walks its rosters one by one.** `fetchCollection` runs up to six
+  fetches at a time and keeps the index order for both rosters and diagnostics: the 21-roster
+  `agent-roster-collective` went from **9.4 s to 0.8 s** on this machine (serial vs parallel, real network).
+- The collection route memoises the fetched result for 60 s, and the panel keeps the last expansion in
+  memory — re-opening a collection paints immediately instead of re-fetching 21 files.
+
+### Added
+
+- A filter box inside an expanded collection: narrows by roster id, title or member name, and shows
+  `shown / total`. It only hides rows; it never writes anything.
+
+## [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
@@ -524,7 +548,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.6...main
+[Unreleased]: https://github.com/dsh-agent-roster/dsh-agent-roster/compare/v0.11.0...main
+[0.11.0]: https://github.com/dsh-agent-roster/dsh-agent-roster/compare/v0.10.7...v0.11.0
+[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

package/README.md

@@ -392,9 +392,18 @@ 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.
+- **Expanding is fast and filterable**: opening a collection fetches its rosters in parallel (up to six in
+  flight) instead of one after another — the 21-roster collective went from **9.4 s to 0.8 s** on this
+  machine. The route memoises the fetched result for 60 seconds, and the panel keeps the last expansion in
+  memory, so re-opening is instant and re-opening after a minute costs one round of six requests, not 21.
+  A filter box inside the expanded list narrows by id, title or member name; it only hides rows, it never
+  changes data.
 - **Where each roster lives**: a collection's `rosters[]` is just the list of ids; the optional
   `files` map says where each one is (`{"core-review": "dist/core-review-1.0.0.json"}`). It is optional —
   without it the fetcher assumes the v1 layout `<id>/roster.yaml` — but a v2 library needs it, because an
@@ -441,7 +450,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 +471,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 +492,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` — 300/300 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,12 @@ 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」不需要靠删目录来排查。
+- **展开很快、也能查找**：展开一个集合时档案是**并发**拉的（最多 6 条在飞），不是一份一份排队——
+  21 份的集合在本机从 **9.4 秒降到 0.8 秒**。服务端把结果记 60 秒，面板也记住上次展开的内容，
+  所以再点开是瞬间的，隔一分钟再点开也只花一轮 6 个请求而不是 21 个。展开区里带一个查找框，
+  按 id、标题或成员名过滤；它只隐藏行，不改任何数据。
 - **拉取到本机**：写入是幂等的，四种结果都会报给你——
   `created`（新写入）、`updated`（显式覆盖）、`unchanged`（内容一致，不写盘）、`conflict`（本地不一样，**默认不覆盖**）。
   冲突要你自己决定：要么在编辑器里合并，要么再点一次「拉取到本机」并在请求里带 `overwrite`。
@@ -417,7 +423,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 +442,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 +463,7 @@ test/             单测
 
 本机已验证：
 
-- `npm test` —— 295/295 通过（格式、解析、校验、扫描、路径、桥接、核对四桶、摘要与溯源、档案差异、能力要求与能力闸门、档案库组织、索引 schema、无损 JSON、写入计划与执行、六条路由、快照与提示、两本词典一致、工具契约、客户端加载器契约、包清单、配置视图、样式 token 约束、声明层字段与队长段、schema 与常量对齐、v2 角色/组装/编译三层及其 schema 对齐、v1→v2 迁移、执行回执并入施工图）。
+- `npm test` —— 300/300 通过（格式、解析、校验、扫描、路径、桥接、核对四桶、摘要与溯源、档案差异、能力要求与能力闸门、档案库组织、索引 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/client.js

@@ -1663,11 +1663,27 @@ window.__ModuleLoader__.load({
      * 拉取是**显式动作**：后端按内容比对，相同的跳过、不同的默认不覆盖（会把冲突数报回来）。
      * 前端不做这份判断——它只把结果说清楚，避免"点一下按钮，本地改动就没了"。
      */
+    // 展开过的 collection 记在模块里：再点开先画缓存，再在后台刷新。
+    // 服务端也有一份 60s 缓存，两层各管一段——这层管"切换页签不白等"，那层管"重复展开不打网络"。
+    const SOURCE_DETAIL_TTL_MS = 60_000;
+    const sourceDetailCache = new Map();
+
+    function cachedSourceDetail(key) {
+      const entry = sourceDetailCache.get(key);
+      if (entry === undefined) return null;
+      if (Date.now() - entry.at >= SOURCE_DETAIL_TTL_MS) {
+        sourceDetailCache.delete(key);
+        return null;
+      }
+      return entry.body;
+    }
+
     function SourcesTab({ remote, onToast, onPulled, onRefresh, refreshing }) {
       useTranslation();
       const [pulling, setPulling] = useState("");
       const [openId, setOpenId] = useState("");
       const [detail, setDetail] = useState(null);
+      const [filter, setFilter] = useState("");
 
       const collections = remote?.collections ?? [];
       const indexes = remote?.indexes ?? [];
@@ -1700,24 +1716,77 @@ window.__ModuleLoader__.load({
         }
       }
 
+      function detailKey(collection) {
+        return `${collection.origin?.source ?? ""}::${collection.id}`;
+      }
+
       async function toggle(collection) {
         if (openId === collection.id) {
           setOpenId("");
           setDetail(null);
           return;
         }
+        const key = detailKey(collection);
+        const remembered = cachedSourceDetail(key);
         setOpenId(collection.id);
-        setDetail({ id: collection.id, status: "loading", body: null });
+        setFilter("");
+        // 有缓存就先出内容，用户看到的"等待"只剩网络那一半。
+        setDetail(remembered === null ? { id: collection.id, status: "loading", body: null } : { id: collection.id, status: "ready", body: remembered });
         const query = new URLSearchParams({ id: collection.id });
         if (collection.origin?.source !== undefined) query.set("source", collection.origin.source);
         const result = await readJson(`${COLLECTION_ROUTE}?${query.toString()}`);
         if (result.ok && result.body !== null) {
+          sourceDetailCache.set(key, { at: Date.now(), body: result.body });
           setDetail({ id: collection.id, status: "ready", body: result.body });
-        } else {
+        } else if (remembered === null) {
           setDetail({ id: collection.id, status: "error", body: null });
         }
       }
 
+      /**
+       * 展开区：先把「查什么」和「查到几条」放出来，再列档案。
+       * 查找只过滤视图，不改任何数据，也不触发网络。
+       */
+      function renderDetail() {
+        const all = detail?.body?.rosters ?? [];
+        const needle = filter.trim().toLowerCase();
+        const shown =
+          needle === ""
+            ? all
+            : all.filter((roster) =>
+                [roster.id, roster.title, roster.description, ...(roster.members ?? []).map((member) => member.name)]
+                  .filter((value) => typeof value === "string")
+                  .some((value) => value.toLowerCase().includes(needle)),
+              );
+        return h(
+          "div",
+          { className: "rstr-source-detail" },
+          h(
+            "div",
+            { className: "rstr-source-filter" },
+            h("input", {
+              className: "rstr-input rstr-search",
+              value: filter,
+              placeholder: t("source.filterPlaceholder"),
+              "aria-label": t("source.filter"),
+              onChange: (event) => setFilter(event.target.value),
+            }),
+            h("span", { className: "rstr-muted rstr-small" }, t("source.filterCount", { shown: shown.length, total: all.length })),
+          ),
+          shown.map((roster) =>
+            h(
+              "div",
+              { key: roster.id, className: "rstr-source-roster" },
+              h("span", { className: "rstr-mono" }, roster.id),
+              h("span", { className: "rstr-muted" }, roster.title ?? ""),
+              h(Badge, { tone: "neutral" }, `${(roster.members ?? []).length}`),
+            ),
+          ),
+          shown.length === 0 ? h("p", { className: "rstr-muted" }, t("panel.noMatch")) : null,
+          (detail.body?.diagnostics ?? []).length > 0 ? h(DiagnosticList, { items: detail.body.diagnostics }) : null,
+        );
+      }
+
       // 刷新是档案源自己的动作：绕过 TTL 重新回源，而不是重读本地快照。
       const head = h(
         "div",
@@ -1810,22 +1879,7 @@ window.__ModuleLoader__.load({
                   ? h("p", { className: "rstr-muted" }, t("source.loading"))
                   : detail.status === "error"
                     ? h("p", { className: "rstr-muted" }, t("misc.failed"))
-                    : h(
-                        "div",
-                        { className: "rstr-source-detail" },
-                        (detail.body?.rosters ?? []).map((roster) =>
-                          h(
-                            "div",
-                            { key: roster.id, className: "rstr-source-roster" },
-                            h("span", { className: "rstr-mono" }, roster.id),
-                            h("span", { className: "rstr-muted" }, roster.title ?? ""),
-                            h(Badge, { tone: "neutral" }, `${(roster.members ?? []).length}`),
-                          ),
-                        ),
-                        (detail.body?.diagnostics ?? []).length > 0
-                          ? h(DiagnosticList, { items: detail.body.diagnostics })
-                          : null,
-                      )
+                    : renderDetail()
                 : null,
             ),
           ),
@@ -2447,6 +2501,18 @@ window.__ModuleLoader__.load({
   border-left: 2px solid var(--dsw-alias-border-l2);
   margin-left: 2px;
 }
+.rstr-source-filter {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  min-width: 0;
+  padding: 2px 0 6px;
+}
+.rstr-source-filter .rstr-search {
+  flex: 1 1 auto;
+  min-width: 0;
+  max-width: 320px;
+}
 .rstr-source-roster {
   display: grid;
   grid-template-columns: minmax(120px, 180px) minmax(0, 1fr) auto;

package/index.js

@@ -25,7 +25,7 @@ import { validateRoster } from "./lib/validate.js";
 import { validateRoster2 } from "./lib/roster2.js";
 import { sendError, sendJson, createAuthGate, readJsonBody, requireMethod } from "./lib/http.js";
 import { buildPanelSnapshot, installCollection, loadRemotePanel, resolveRoots } from "./lib/service.js";
-import { fetchCollection } from "./lib/remote.js";
+import { createTtlCache, fetchCollection } from "./lib/remote.js";
 import { registerRosterTools } from "./lib/tools.js";
 import { deleteRosterDocument, readRosterDocument, writeRosterDocument } from "./lib/write.js";
 
@@ -129,6 +129,10 @@ export function apply(ctx, config) {
       "library route",
     );
 
+    // 同一份 collection 一分钟内被展开两次，第二次不该再打一轮请求。
+    // 缓存的是**已校验的结果**，不是响应体，所以不存在"把非法内容缓存下来"的问题。
+    const collectionCache = createTtlCache({ ttlMs: 60_000 });
+
     register(
       "/plugins/dsh-agent-roster/collection",
       async (req, res) => {
@@ -145,7 +149,9 @@ export function apply(ctx, config) {
           sendJson(res, 404, { ok: false, error: { code: "collection-not-found" }, known: remote.collections.map((item) => item.id) });
           return;
         }
-        const fetched = await fetchCollection(collection);
+        const cacheKey = `${source}::${id}`;
+        const cached = query.get("refresh") === "1" ? null : collectionCache.get(cacheKey);
+        const fetched = cached ?? collectionCache.set(cacheKey, await fetchCollection(collection));
         sendJson(res, 200, {
           ok: fetched.diagnostics.every((item) => item.severity !== "error"),
           collection: {

package/lib/remote.js

@@ -550,76 +550,75 @@ export function validateRegistry(value, meta = {}) {
  * @param {(id: string) => boolean} [options.only] 只要这几份（面板按需拉取时用）
  * @returns {Promise<{ collection: object, rosters: object[], diagnostics: object[] }>}
  */
-export async function fetchCollection(collection, options = {}) {
-  const fetchImpl = options.fetchImpl ?? globalThis.fetch;
-  const wanted = collection.rosters.filter((id) => options.only === undefined || options.only(id));
-  const rosters = [];
-  const diagnostics = [];
-
-  for (const rosterId of wanted) {
-    let loaded = null;
-    let lastError = "";
-    const listedPath = collection.files?.[rosterId] ?? null;
-    const candidateNames = listedPath === null ? ["roster.yaml", "roster.yml", "roster.json"] : [null];
-    for (const fileName of candidateNames) {
-      const url = listedPath === null ? collectionFileUrl(collection, rosterId, fileName) : collectionFileUrl(collection, rosterId, "");
-      try {
-        const response = await fetchImpl(url, { signal: AbortSignal.timeout(TIMEOUT_MS) });
-        if (!response.ok) {
-          lastError = `HTTP ${String(response.status)}`;
-          continue;
-        }
-        loaded = { url, fileName, text: await response.text() };
-        break;
-      } catch (error) {
-        lastError = error instanceof Error ? error.message : String(error);
-      }
-    }
-    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）`,
-          ),
-        );
+/**
+ * 拉一份档案（成功就返回 roster，失败就返回诊断）。
+ *
+ * 抽成独立函数是为了让 `fetchCollection` 能并发跑多份：串行 21 次 HTTPS 往返
+ * 实测 2.4 秒，用户点「展开」就是等它。并发只改变等待形状，不改变结果形状。
+ */
+async function fetchOneRoster(collection, rosterId, { fetchImpl }) {
+  let loaded = null;
+  let lastError = "";
+  const listedPath = collection.files?.[rosterId] ?? null;
+  const candidateNames = listedPath === null ? ["roster.yaml", "roster.yml", "roster.json"] : [null];
+  for (const fileName of candidateNames) {
+    const url = listedPath === null ? collectionFileUrl(collection, rosterId, fileName) : collectionFileUrl(collection, rosterId, "");
+    try {
+      const response = await fetchImpl(url, { signal: AbortSignal.timeout(TIMEOUT_MS) });
+      if (!response.ok) {
+        lastError = `HTTP ${String(response.status)}`;
+        continue;
       }
-      continue;
+      loaded = { url, fileName, text: await response.text() };
+      break;
+    } catch (error) {
+      lastError = error instanceof Error ? error.message : String(error);
     }
-    const parsed = parseDocumentText(loaded.text, { file: loaded.url });
-    if (parsed.ok && parsed.value !== null && typeof parsed.value === "object" && parsed.value.kind === ROSTER2_KIND) {
+  }
+  if (loaded === null) {
+    const diagnostics = [
+      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）`,
+        ),
+      );
+    }
+    return { roster: null, diagnostics };
+  }
+  const parsed = parseDocumentText(loaded.text, { file: loaded.url });
+  if (parsed.ok && parsed.value !== null && typeof parsed.value === "object" && parsed.value.kind === ROSTER2_KIND) {
+    return {
+      roster: null,
+      diagnostics: [
         diagnostic(
           "warn",
           "collection-roster-needs-roles",
           `${collection.id}/${rosterId} 是 v2 组装，成员是角色引用，单个文件拉不到角色目录；索引应指向 dist/ 里的编译产物`,
         ),
-      );
-      continue;
-    }
-    let checked;
-    if (parsed.ok && parsed.value !== null && typeof parsed.value === "object" && parsed.value.kind === COMPILED_KIND) {
-      const compiled = validateCompiled(parsed.value, { file: loaded.url });
-      if (!compiled.ok) {
-        diagnostics.push(...compiled.diagnostics);
-        continue;
-      }
-      checked = validateRoster(flattenCompiledToRoster(compiled.compiled), { file: loaded.url, expectedId: rosterId });
-      checked = { ...checked, format: "compiled" };
-    } else {
-      checked = parsed.ok
-        ? validateRoster(parsed.value, { file: loaded.url, expectedId: rosterId })
-        : { ok: false, diagnostics: parsed.diagnostics };
-    }
-    if (!checked.ok) {
-      diagnostics.push(...checked.diagnostics);
-      continue;
-    }
-    rosters.push({
+      ],
+    };
+  }
+  let checked;
+  if (parsed.ok && parsed.value !== null && typeof parsed.value === "object" && parsed.value.kind === COMPILED_KIND) {
+    const compiled = validateCompiled(parsed.value, { file: loaded.url });
+    if (!compiled.ok) return { roster: null, diagnostics: compiled.diagnostics };
+    checked = validateRoster(flattenCompiledToRoster(compiled.compiled), { file: loaded.url, expectedId: rosterId });
+    checked = { ...checked, format: "compiled" };
+  } else {
+    checked = parsed.ok
+      ? validateRoster(parsed.value, { file: loaded.url, expectedId: rosterId })
+      : { ok: false, diagnostics: parsed.diagnostics };
+  }
+  if (!checked.ok) return { roster: null, diagnostics: checked.diagnostics };
+  return {
+    roster: {
       ...checked.roster,
       ...(checked.format === undefined ? {} : { format: checked.format }),
       origin: {
@@ -631,12 +630,86 @@ export async function fetchCollection(collection, options = {}) {
         path: collection.path,
         url: loaded.url,
       },
-    });
-  }
+    },
+    diagnostics: [],
+  };
+}
+
+/** 并发上限：raw.githubusercontent 是无认证的，6 条并行既快又不会被当成抓取器。 */
+export const FETCH_CONCURRENCY = 6;
+
+/**
+ * 拉取一个 collection 里的档案。
+ *
+ * 并发上限由 `options.concurrency` 覆盖（测试用它把时序摊平）；返回的 `rosters`
+ * 与 `diagnostics` 都保持索引顺序，和串行版本的输出逐字一致。
+ *
+ * @param {object} collection `validateRegistry` 校验过的 collection
+ * @param {object} [options]
+ * @param {string} [options.only] 只拉这一份（测试/预览用）
+ * @param {typeof fetch} [options.fetchImpl]
+ * @param {number} [options.concurrency]
+ * @returns {Promise<{collection: object, rosters: object[], diagnostics: object[]}>}
+ */
+export async function fetchCollection(collection, options = {}) {
+  const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+  const wanted = collection.rosters.filter((id) => options.only === undefined || options.only(id));
+  const concurrency = Math.max(1, Math.min(Number.isInteger(options.concurrency) ? options.concurrency : FETCH_CONCURRENCY, wanted.length || 1));
+  const results = new Array(wanted.length);
+  let next = 0;
+  const workers = Array.from({ length: Math.min(concurrency, wanted.length) }, async () => {
+    for (;;) {
+      const index = next;
+      next += 1;
+      if (index >= wanted.length) return;
+      results[index] = await fetchOneRoster(collection, wanted[index], { fetchImpl });
+    }
+  });
+  await Promise.all(workers);
 
+  const rosters = [];
+  const diagnostics = [];
+  for (const result of results) {
+    if (result === undefined) continue;
+    if (result.roster !== null) rosters.push(result.roster);
+    diagnostics.push(...result.diagnostics);
+  }
   return { collection, rosters, diagnostics };
 }
 
+/**
+ * 一份进程内的 TTL 缓存。
+ *
+ * 用途只有一个：同一个 collection 在短时间内被展开两次时，第二次不该再打 21 个请求。
+ * 缓存的是**结果**（已校验的档案），不是响应体——所以没有"缓存了不合法内容"的风险。
+ *
+ * @param {{ttlMs?: number, now?: () => number}} [options]
+ */
+export function createTtlCache({ ttlMs = 60_000, now = () => Date.now() } = {}) {
+  const entries = new Map();
+  return {
+    get(key) {
+      const entry = entries.get(key);
+      if (entry === undefined) return null;
+      if (now() - entry.at >= ttlMs) {
+        entries.delete(key);
+        return null;
+      }
+      return entry.value;
+    },
+    set(key, value) {
+      entries.set(key, { at: now(), value });
+      return value;
+    },
+    clear() {
+      entries.clear();
+    },
+    get size() {
+      return entries.size;
+    },
+  };
+}
+
 /** 拼一份档案的 raw 地址（relativePath 由索引给出，或回退到 v1 的 `<id>/roster.<ext>`）。 */
 export function collectionFileUrl(collection, rosterId, fileName) {
   const repo = collection.repo.replace(/^github:/, "");

package/locale/en.json

@@ -298,5 +298,8 @@
       "undeclared": "not declared, runtime uses {actual}",
       "unknown": "deployment unreadable"
     }
-  }
+  },
+  "source.filter": "Filter this collection",
+  "source.filterPlaceholder": "Filter by id, title or member",
+  "source.filterCount": "{shown} of {total}"
 }

package/locale/zh.json

@@ -298,5 +298,8 @@
       "undeclared": "未声明，运行时用 {actual}",
       "unknown": "读不到部署配置"
     }
-  }
+  },
+  "source.filter": "在这份集合里查找",
+  "source.filterPlaceholder": "按 id、标题或成员名过滤",
+  "source.filterCount": "{shown} / {total}"
 }

package/package.json

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