@stofone/dsh-agent-roster 0.11.1 → 0.12.0

package/CHANGELOG.md

@@ -4,6 +4,29 @@
 
 ## [Unreleased]
 
+## [0.12.0] - 2026-11-03
+
+### The panel answers "which one", not "show me everything"
+
+Until now the panel was organised by **collection**: expand a source, then read a list. But the real
+question is almost always the opposite — "I need someone who watches data quality" — so the entry
+point is now one search field above the tabs.
+
+- `GET /plugins/dsh-agent-roster/search?q=` searches this machine and every subscribed source in one
+  request, reusing the collection cache (60s) so repeated typing does not hit the network again.
+- Ranking is explainable: every match reports `hits[{field, label, text}]` ("标签：数据质量"), and id
+  matches outrank title matches outrank tag matches outrank member roles. Multiple words are **AND**:
+  "data kubernetes" matches nothing here, instead of matching everything that has "data".
+- A result that lives in another library says so ("来自 agent-roster-collective") and can be pulled
+  from the row itself; a local one opens straight into the roster list filtered to that id.
+- `lib/search.js` is a pure function — no filesystem, no network — so the ranking is unit-tested.
+
+### Added
+
+- `lib/search.js` with `searchRosters`, `searchableFields`, `tokenize`; 6 tests.
+- `/plugins/dsh-agent-roster/search` route (local + remote, bounded source concurrency).
+- Panel lookup field, result rows with match provenance, and `lookup.*` strings in both locales.
+
 ## [0.11.1] - 2026-11-03
 
 ### Fixed
@@ -557,7 +580,8 @@
 - 工具返回值含 `undefined` 键，运行时按 `value is not lossless JSON` 整次拒绝；缺失值统一写 `null`，
   且所有返回值先过 `lib/json.js#lossless`。
 
-[Unreleased]: https://github.com/dsh-agent-roster/dsh-agent-roster/compare/v0.11.1...main
+[Unreleased]: https://github.com/dsh-agent-roster/dsh-agent-roster/compare/v0.12.0...main
+[0.12.0]: https://github.com/dsh-agent-roster/dsh-agent-roster/compare/v0.11.1...v0.12.0
 [0.11.1]: https://github.com/dsh-agent-roster/dsh-agent-roster/compare/v0.11.0...v0.11.1
 [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

package/README.md

@@ -306,6 +306,23 @@ id belongs to the team, and the plugin never writes team state. What it does own
 failure that only exists on a red card never reaches the next compile, which is exactly how a gate
 turns into decoration.
 
+## Find one roster, not a catalogue
+
+The panel used to open on a list of collections. That answers "what is published"; the question people
+actually arrive with is "who can do this". So the first control is now one search field above the tabs:
+
+```
+要找什么能力？例：数据质量、发版、代码评审
+```
+
+It searches this machine and every subscribed source in one request. Each row says **why** it matched
+(`标签：数据质量 · 成员角色：数据质量工程师`) and where it lives (`来自 agent-roster-collective`), and
+carries the action you need next — open it locally, or pull that collection from the row.
+
+Multiple words are AND, not OR: `data kubernetes` returns nothing rather than every roster that merely
+mentions "data". Ranking is a pure function in `lib/search.js`, so it is unit-tested rather than
+eyeballed.
+
 ## Tools
 
 | Tool | Purpose |
@@ -492,7 +509,7 @@ test/             unit tests
 
 Verified on this machine:
 
-- `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 test` — 307/307 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

@@ -292,6 +292,22 @@ node bin/cli.mjs compile --roster examples-orchestration/rosters/core-review \
 
 回执由执行施工图的队长会话写，不由插件写：任务 id 属于团队，插件从不写团队状态。插件负责的是合并——只活在红卡上的失败，下一次编译就消失了，门也就变成了装饰。
 
+## 找一份档案，而不是翻一个目录
+
+面板原来从「合集」进：先展开一个来源，再看里面有什么。那回答的是「发布了什么」，而人真正带来的
+问题是「谁会做这件事」。所以现在第一个控件就是页签上方的一个搜索框：
+
+```
+要找什么能力？例：数据质量、发版、代码评审
+```
+
+一次请求同时搜本机与所有订阅来源。每一行都写清**为什么命中**（`标签：数据质量 · 成员角色：数据质量工程师`）
+与**它住在哪**（`来自 agent-roster-collective`），并且把下一步动作放在行内：本机的直接打开，远端的
+当场把这个集合拉下来。
+
+多个词是「且」不是「或」：`data kubernetes` 一条都不返，而不是把所有提到 data 的档案都堆上来。
+排序逻辑是 `lib/search.js` 里的纯函数，因此它被单测钉住，而不是靠肉眼看着顺。
+
 ## 工具
 
 | 工具 | 作用 |
@@ -463,7 +479,7 @@ test/             单测
 
 本机已验证：
 
-- `npm test` —— 300/300 通过（格式、解析、校验、扫描、路径、桥接、核对四桶、摘要与溯源、档案差异、能力要求与能力闸门、档案库组织、索引 schema、无损 JSON、写入计划与执行、六条路由、快照与提示、两本词典一致、工具契约、客户端加载器契约、包清单、配置视图、样式 token 约束、声明层字段与队长段、schema 与常量对齐、v2 角色/组装/编译三层及其 schema 对齐、v1→v2 迁移、执行回执并入施工图）。
+- `npm test` —— 307/307 通过（格式、解析、校验、扫描、路径、桥接、核对四桶、摘要与溯源、档案差异、能力要求与能力闸门、档案库组织、索引 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

@@ -34,6 +34,7 @@ window.__ModuleLoader__.load({
     const INSTALL_ROUTE = "/plugins/dsh-agent-roster/install";
     const COLLECTION_ROUTE = "/plugins/dsh-agent-roster/collection";
     const APPLY_ROUTE = "/plugins/dsh-agent-roster/apply";
+    const SEARCH_ROUTE = "/plugins/dsh-agent-roster/search";
 
     const EFFORTS = ["low", "medium", "high", "default"];
     const LANGUAGES = ["auto", "zh", "en"];
@@ -1283,6 +1284,39 @@ window.__ModuleLoader__.load({
       const [importing, setImporting] = useState(false);
       const [removing, setRemoving] = useState(null);
       const [toast, setToast] = useState(null);
+      // 「找一份档案」是首屏动作，不是某个页签里的筛选器：它同时问本机与所有订阅来源。
+      const [lookup, setLookup] = useState("");
+      const [lookupState, setLookupState] = useState({ status: "idle", body: null });
+      const [pullingCollection, setPullingCollection] = useState("");
+
+      useEffect(() => {
+        const needle = lookup.trim();
+        if (needle.length < 2) {
+          setLookupState({ status: "idle", body: null });
+          return;
+        }
+        const controller = new AbortController();
+        // 停止输入之后才发请求：每敲一个字都打一次，等于自己给自己造并发。
+        const timer = setTimeout(() => {
+          setLookupState((current) => ({ status: "loading", body: current.body }));
+          readJson(`${SEARCH_ROUTE}?q=${encodeURIComponent(needle)}`, { signal: controller.signal })
+            .then((result) => {
+              if (controller.signal.aborted) return;
+              setLookupState(
+                result.ok && result.body !== null
+                  ? { status: "ready", body: result.body }
+                  : { status: "error", body: null },
+              );
+            })
+            .catch(() => {
+              if (!controller.signal.aborted) setLookupState({ status: "error", body: null });
+            });
+        }, 220);
+        return () => {
+          clearTimeout(timer);
+          controller.abort();
+        };
+      }, [lookup]);
 
       useEffect(() => {
         if (toast === null) return;
@@ -1321,6 +1355,38 @@ window.__ModuleLoader__.load({
         });
       }, [rosters, query, selectedTags]);
 
+      async function openMatch(match) {
+        if (match.scope === "local") {
+          setLookup("");
+          setTab("rosters");
+          setQuery(match.rosterId);
+          return;
+        }
+        setPullingCollection(match.collectionId ?? "");
+        try {
+          const result = await readJson(INSTALL_ROUTE, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ collection: match.collectionId }),
+          });
+          if (!result.ok || result.body === null) {
+            setToast(`${t("misc.failed")} (${String(result.status)})`);
+            return;
+          }
+          const summary = t("source.pulled", {
+            written: result.body.written ?? 0,
+            unchanged: result.body.unchanged ?? 0,
+            conflicts: result.body.conflicts ?? 0,
+          });
+          setToast(summary);
+          library.reload();
+        } catch {
+          setToast(t("misc.failed"));
+        } finally {
+          setPullingCollection("");
+        }
+      }
+
       function toggleTag(tag) {
         setSelectedTags((current) => {
           const next = new Set(current);
@@ -1454,6 +1520,82 @@ window.__ModuleLoader__.load({
         ),
       );
 
+      // 搜索态压过页签：输入了问题就只看答案，不再让人先去挑一个合集。
+      let lookupView = null;
+      const needle = lookup.trim();
+      if (needle !== "") {
+        const body = lookupState.body;
+        const matches = body?.matches ?? [];
+        lookupView = h(
+          "div",
+          { className: "rstr-results" },
+          h(
+            "p",
+            { className: "rstr-results-head" },
+            lookupState.status === "loading" && body === null
+              ? t("lookup.searching")
+              : t("lookup.counts", {
+                  total: String(matches.length),
+                  local: String(body?.counts?.local ?? 0),
+                  remote: String(body?.counts?.remote ?? 0),
+                }),
+          ),
+          lookupState.status === "error"
+            ? h("p", { className: "rstr-muted" }, t("lookup.failed"))
+            : null,
+          lookupState.status === "ready" && matches.length === 0
+            ? h("p", { className: "rstr-muted" }, t("lookup.empty", { q: needle }))
+            : null,
+          matches.map((match) =>
+            h(
+              "article",
+              { key: `${match.scope}:${match.collectionId ?? ""}:${match.rosterId}`, className: "rstr-row" },
+              h(
+                "div",
+                { className: "rstr-row-body" },
+                h("code", { className: "rstr-row-id", title: match.rosterId }, match.rosterId),
+                h(
+                  "div",
+                  { className: "rstr-row-text" },
+                  h("h3", { className: "rstr-row-title" }, match.title === "" ? match.rosterId : match.title),
+                  h(
+                    "p",
+                    { className: "rstr-row-desc" },
+                    match.hits.map((hit) => `${hit.label}：${hit.text}`).join(" · "),
+                  ),
+                ),
+                h(
+                  "div",
+                  { className: "rstr-row-stats" },
+                  h("span", { className: "rstr-stat" }, t("lookup.members", { count: String(match.members) })),
+                  h(
+                    "span",
+                    { className: "rstr-stat" },
+                    match.scope === "local"
+                      ? t("lookup.local")
+                      : t("lookup.remoteFrom", { collection: match.collectionTitle ?? match.collectionId ?? "" }),
+                  ),
+                ),
+                h(
+                  "div",
+                  { className: "rstr-row-actions" },
+                  h(
+                    "button",
+                    {
+                      type: "button",
+                      className: "rstr-btn rstr-btn-sm",
+                      disabled: match.scope === "remote" && pullingCollection !== "",
+                      onClick: () => openMatch(match),
+                    },
+                    match.scope === "local" ? t("lookup.open") : t("lookup.pull"),
+                  ),
+                ),
+              ),
+            ),
+          ),
+        );
+      }
+
       let content = null;
 
       if (tab === "rosters") {
@@ -1599,8 +1741,31 @@ window.__ModuleLoader__.load({
         { className: "rstr-page" },
         header,
         banner,
-        tabs,
-        content,
+        h(
+          "div",
+          { className: "rstr-lookup" },
+          h("input", {
+            className: "rstr-input rstr-lookup-input",
+            value: lookup,
+            placeholder: t("lookup.placeholder"),
+            "aria-label": t("lookup.placeholder"),
+            onChange: (event) => setLookup(event.target.value),
+            onKeyDown: (event) => {
+              if (event.key !== "Escape") return;
+              setLookup("");
+              event.stopPropagation();
+            },
+          }),
+          lookup === ""
+            ? h("span", { className: "rstr-lookup-hint" }, t("lookup.hint"))
+            : h(
+                "button",
+                { type: "button", className: "rstr-btn rstr-btn-sm rstr-btn-ghost", onClick: () => setLookup("") },
+                t("lookup.clear"),
+              ),
+        ),
+        lookupView === null ? tabs : null,
+        lookupView === null ? content : lookupView,
         h(
           "footer",
           { className: "rstr-foot" },
@@ -2347,6 +2512,19 @@ window.__ModuleLoader__.load({
 
 /* ---- 账本（行） ------------------------------------------------------- */
 
+.rstr-lookup { display: flex; align-items: center; gap: 10px; padding: 0 28px 12px; min-width: 0; }
+
+.rstr-lookup-input { flex: 1 1 auto; max-width: 560px; }
+
+.rstr-lookup-hint { font-size: 12px; color: var(--dsw-alias-label-secondary); }
+
+/* 清除按钮不参与压缩：窄面板里被挤成竖排的两个字最难认。 */
+.rstr-lookup > .rstr-btn { flex: 0 0 auto; white-space: nowrap; }
+
+.rstr-results { display: flex; flex-direction: column; min-width: 0; padding: 0 28px 28px; border-top: 1px solid var(--dsw-alias-border-l2); }
+
+.rstr-results-head { margin: 12px 0 4px; font-size: 12px; color: var(--dsw-alias-label-secondary); }
+
 .rstr-cards { display: flex; flex-direction: column; min-width: 0; border-top: 1px solid var(--dsw-alias-border-l2); }
 
 .rstr-row {

package/index.js

@@ -26,6 +26,7 @@ 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 { createTtlCache, fetchCollection } from "./lib/remote.js";
+import { searchRosters } from "./lib/search.js";
 import { registerRosterTools } from "./lib/tools.js";
 import { deleteRosterDocument, readRosterDocument, writeRosterDocument } from "./lib/write.js";
 
@@ -173,6 +174,87 @@ export function apply(ctx, config) {
       "collection route",
     );
 
+    // 搜索是「找一份档案」的入口：一次请求横跨本机与所有订阅来源。
+    // 远端的拉取复用 collection 的 60s 缓存，所以连续输入不会对同一个集合重复打网络。
+    register(
+      "/plugins/dsh-agent-roster/search",
+      async (req, res) => {
+        if (guard(req, res)) return;
+        if (!requireMethod(req, res, "GET")) return;
+        const query = new URL(req.url ?? "/", "http://localhost").searchParams;
+        const q = (query.get("q") ?? "").trim();
+        if (q === "") {
+          sendJson(res, 200, { ok: true, q: "", tokens: [], total: 0, matches: [], counts: { local: 0, remote: 0 }, diagnostics: [] });
+          return;
+        }
+
+        const library = collectLibrary(ctx, settings, { name: pkg.name, version: pkg.version });
+        const entries = [];
+        let localCount = 0;
+        for (const workspace of library.workspaces) {
+          for (const roster of workspace.rosters) {
+            entries.push({ scope: "local", roster, libraryId: workspace.rootDir ?? null, file: roster.file ?? null });
+            localCount += 1;
+          }
+        }
+
+        const diagnostics = [];
+        const collections = [];
+        try {
+          const remote = await loadRemotePanel(settings, {});
+          for (const item of remote.diagnostics ?? []) if (item.severity !== "info") diagnostics.push(item);
+          for (const collection of remote.collections ?? []) collections.push(collection);
+        } catch (error) {
+          diagnostics.push({
+            severity: "warn",
+            code: "search-index-unavailable",
+            message: `订阅索引拉不到，本次只搜索本机档案：${error instanceof Error ? error.message : String(error)}`,
+          });
+        }
+
+        // 来源两两并发：一个慢集合不该把所有来源都拖住，也不该一次打三十个请求。
+        const sourceConcurrency = 2;
+        let cursor = 0;
+        const fetchNext = async () => {
+          while (cursor < collections.length) {
+            const collection = collections[cursor];
+            cursor += 1;
+            const key = `${collection.source ?? ""}::${collection.id}`;
+            try {
+              const cached = collectionCache.get(key);
+              const fetched = cached ?? collectionCache.set(key, await fetchCollection(collection));
+              for (const roster of fetched.rosters ?? []) {
+                entries.push({
+                  scope: "remote",
+                  roster,
+                  collectionId: collection.id,
+                  collectionTitle: collection.title ?? null,
+                  file: roster.file ?? null,
+                });
+              }
+              for (const item of fetched.diagnostics ?? []) if (item.severity === "error") diagnostics.push(item);
+            } catch (error) {
+              diagnostics.push({
+                severity: "warn",
+                code: "search-source-failed",
+                message: `${collection.id} 拉取失败：${error instanceof Error ? error.message : String(error)}`,
+              });
+            }
+          }
+        };
+        await Promise.all(Array.from({ length: Math.min(sourceConcurrency, collections.length) }, fetchNext));
+
+        const result = searchRosters(q, entries);
+        const remoteCount = entries.length - localCount;
+        sendJson(res, 200, {
+          ...result,
+          counts: { local: localCount, remote: remoteCount },
+          diagnostics: diagnostics.slice(0, 20),
+        });
+      },
+      "search route",
+    );
+
     register(
       "/plugins/dsh-agent-roster/locale",
       async (req, res) => {

package/lib/search.js

@@ -0,0 +1,155 @@
+/**
+ * 找一份档案，而不是浏览一堆合集。
+ *
+ * 面板原来的组织单位是「合集」：先展开一个来源，再在里面翻。但真实任务几乎总是反向的——
+ * 「我需要一个能盯数据质量的队伍」，先知道自己要什么，再去找谁有。所以这里把搜索做成
+ * 一等能力：一个问题，横跨本机与所有订阅来源，命中的每一行都要说清**为什么命中**。
+ *
+ * 两条刻意的规则：
+ * 1. **多词是「且」**：`data quality` 要求每个词都落在某个字段里，任一落空即不入选。
+ *    否则「评分」会把一堆只沾了「分」的档案捞上来，搜索结果比列表更难读。
+ * 2. **命中要有出处**：每行返回 `hits[{field,label,text}]`，界面直接显示「命中 标签：数据质量」。
+ *    只给分数是没法解释的——用户凭什么信这一条排在前面。
+ *
+ * 纯函数：不读文件、不联网，输入就是已经装配好的档案视图。
+ */
+
+export const SEARCH_LIMIT = 20;
+
+/** 字段权重：id 是名字，title 是自我描述，tags 是别人怎么找它。 */
+export const SEARCH_FIELDS = [
+  { field: "id", weight: 100, label: "档案 id" },
+  { field: "title", weight: 56, label: "标题" },
+  { field: "tags", weight: 48, label: "标签" },
+  { field: "skills", weight: 40, label: "技能要求" },
+  { field: "requires", weight: 36, label: "能力要求" },
+  { field: "memberRole", weight: 34, label: "成员角色" },
+  { field: "memberName", weight: 26, label: "成员名" },
+  { field: "memberTitle", weight: 22, label: "成员标题" },
+  { field: "description", weight: 18, label: "描述" },
+  { field: "notes", weight: 12, label: "备注" },
+];
+
+const WEIGHT = new Map(SEARCH_FIELDS.map((item) => [item.field, item]));
+
+/** 把一个词切成可比较的片段：空白与中文标点都算分隔。 */
+export function tokenize(query) {
+  if (typeof query !== "string") return [];
+  return query
+    .toLowerCase()
+    .split(/[\s,，、;；|/]+/)
+    .map((token) => token.trim())
+    .filter((token) => token !== "");
+}
+
+function push(list, field, text) {
+  if (typeof text !== "string") return;
+  const value = text.trim();
+  if (value === "") return;
+  const meta = WEIGHT.get(field);
+  if (meta === undefined) return;
+  list.push({ field, label: meta.label, text: value, weight: meta.weight });
+}
+
+/**
+ * 把一份档案摊成「可被搜到的字段」。同一字段里的多个值各自成条，
+ * 这样「标签：数据质量」能精确指出是哪一条标签命中，而不是含糊地说"标签命中"。
+ */
+export function searchableFields(roster) {
+  const fields = [];
+  if (roster === null || typeof roster !== "object") return fields;
+  push(fields, "id", roster.id);
+  push(fields, "title", roster.title);
+  push(fields, "description", roster.description);
+  push(fields, "notes", roster.notes);
+  for (const tag of Array.isArray(roster.tags) ? roster.tags : []) push(fields, "tags", tag);
+  for (const member of Array.isArray(roster.members) ? roster.members : []) {
+    push(fields, "memberName", member?.name);
+    push(fields, "memberRole", member?.role);
+    push(fields, "memberTitle", member?.title);
+    for (const skill of Array.isArray(member?.skills) ? member.skills : []) push(fields, "skills", skill);
+  }
+  const requires = roster.requires !== null && typeof roster.requires === "object" ? roster.requires : null;
+  if (requires !== null) {
+    for (const skill of Array.isArray(requires.skills) ? requires.skills : []) push(fields, "skills", skill);
+    for (const policy of Array.isArray(requires.toolPolicies) ? requires.toolPolicies : []) push(fields, "requires", policy);
+  }
+  return fields;
+}
+
+/**
+ * 一条 token 落在哪个字段上最值钱。
+ * 前缀命中与完全命中各加一点：搜 `data` 时 `data-quality` 应该排在 `reconcile-metadata` 前面。
+ */
+function bestMatch(token, fields) {
+  let best = null;
+  for (const item of fields) {
+    const haystack = item.text.toLowerCase();
+    const index = haystack.indexOf(token);
+    if (index === -1) continue;
+    let score = item.weight;
+    if (index === 0) score += item.weight * 0.4;
+    if (haystack === token) score += item.weight * 0.8;
+    if (best === null || score > best.score) best = { score, item };
+  }
+  return best;
+}
+
+/**
+ * @param {string} query
+ * @param {{scope: "local" | "remote", roster: object, libraryId?: string|null,
+ *          collectionId?: string|null, collectionTitle?: string|null, file?: string|null}[]} entries
+ * @returns {{ok: true, q: string, tokens: string[], total: number,
+ *            matches: {scope: string, rosterId: string, title: string, description: string,
+ *                      tags: string[], members: number, libraryId: string|null,
+ *                      collectionId: string|null, collectionTitle: string|null, file: string|null,
+ *                      score: number, hits: {field: string, label: string, text: string}[]}[]}}
+ */
+export function searchRosters(query, entries, { limit = SEARCH_LIMIT } = {}) {
+  const tokens = tokenize(query);
+  if (tokens.length === 0) return { ok: true, q: "", tokens: [], total: 0, matches: [] };
+
+  const matches = [];
+  for (const entry of Array.isArray(entries) ? entries : []) {
+    const roster = entry?.roster;
+    if (roster === null || typeof roster !== "object") continue;
+    const fields = searchableFields(roster);
+    let score = 0;
+    const hits = [];
+    const seen = new Set();
+    let complete = true;
+    for (const token of tokens) {
+      const found = bestMatch(token, fields);
+      if (found === null) {
+        complete = false;
+        break;
+      }
+      score += found.score;
+      if (!seen.has(found.item.field)) {
+        seen.add(found.item.field);
+        hits.push({ field: found.item.field, label: found.item.label, text: found.item.text });
+      }
+    }
+    if (!complete) continue;
+    const id = typeof roster.id === "string" ? roster.id : "";
+    // 同名匹配下，短 id 更可能是"那一个"：`data-quality` 先于 `data-quality-and-observability-review`。
+    score += Math.max(0, 24 - id.length);
+    matches.push({
+      scope: entry.scope === "remote" ? "remote" : "local",
+      rosterId: id,
+      title: typeof roster.title === "string" ? roster.title : "",
+      description: typeof roster.description === "string" ? roster.description : "",
+      tags: Array.isArray(roster.tags) ? roster.tags.slice(0, 6) : [],
+      members: Array.isArray(roster.members) ? roster.members.length : 0,
+      libraryId: entry.libraryId ?? null,
+      collectionId: entry.collectionId ?? null,
+      collectionTitle: entry.collectionTitle ?? null,
+      file: entry.file ?? null,
+      score: Math.round(score),
+      hits,
+    });
+  }
+
+  matches.sort((left, right) => right.score - left.score || left.rosterId.localeCompare(right.rosterId));
+  return { ok: true, q: query.trim(), tokens, total: matches.length, matches: matches.slice(0, limit) };
+}

package/locale/en.json

@@ -301,5 +301,19 @@
   },
   "source.filter": "Filter this collection",
   "source.filterPlaceholder": "Filter by id, title or member",
-  "source.filterCount": "{shown} of {total}"
+  "source.filterCount": "{shown} of {total}",
+  "lookup": {
+    "placeholder": "What should it do? e.g. data quality, release, review",
+    "hint": "Searches this machine and every subscribed source",
+    "clear": "Clear",
+    "searching": "Searching…",
+    "counts": "{total} matched · candidates: {local} local · {remote} remote",
+    "empty": "Nothing matched “{q}”. Try another wording, or check Sources for a subscription that has it.",
+    "failed": "Search failed: the host did not answer.",
+    "members": "{count} members",
+    "local": "local",
+    "remoteFrom": "from {collection}",
+    "open": "Open",
+    "pull": "Pull"
+  }
 }

package/locale/zh.json

@@ -301,5 +301,19 @@
   },
   "source.filter": "在这份集合里查找",
   "source.filterPlaceholder": "按 id、标题或成员名过滤",
-  "source.filterCount": "{shown} / {total}"
+  "source.filterCount": "{shown} / {total}",
+  "lookup": {
+    "placeholder": "要找什么能力？例：数据质量、发版、代码评审",
+    "hint": "同时搜本机与已订阅的来源",
+    "clear": "清除",
+    "searching": "正在搜索…",
+    "counts": "命中 {total} 份 · 候选：本机 {local} · 远端 {remote}",
+    "empty": "没有找到「{q}」。换个说法，或到「档案源」看看是否订阅了它。",
+    "failed": "搜索失败：宿主没有响应。",
+    "members": "{count} 名成员",
+    "local": "本机",
+    "remoteFrom": "来自 {collection}",
+    "open": "打开",
+    "pull": "拉取"
+  }
 }

package/package.json

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