dsh-agentic-tool-catalog 0.0.0-stage → 0.3.2

package/docs/detail-hero.svg

@@ -0,0 +1,57 @@
+<svg width="760" height="400" viewBox="0 0 760 400" fill="none" xmlns="http://www.w3.org/2000/svg">
+  <rect width="760" height="400" rx="20" fill="#F5F7FB"/>
+
+  <!-- left: product surface -->
+  <rect x="24" y="32" width="318" height="336" rx="16" fill="#FFFFFF" stroke="#E3E8EF"/>
+  <text x="44" y="62" font-family="system-ui, -apple-system, sans-serif" font-size="12" fill="#8A93A0">In context</text>
+
+  <!-- catalog panel -->
+  <rect x="42" y="78" width="282" height="230" rx="12" fill="#FFFFFF" stroke="#E3E8EF"/>
+  <text x="58" y="104" font-family="system-ui, -apple-system, sans-serif" font-size="13" font-weight="600" fill="#1F2329">Catalog</text>
+  <circle cx="270" cy="99" r="4" fill="#2FBF71"/>
+  <text x="280" y="104" font-family="system-ui, -apple-system, sans-serif" font-size="11" fill="#6B7280">ready</text>
+
+  <rect x="58" y="118" width="250" height="6" rx="3" fill="#E9EDF2"/>
+  <rect x="58" y="118" width="80" height="6" rx="3" fill="#9AA6B5"/>
+  <rect x="138" y="118" width="20" height="6" rx="3" fill="#145AF3"/>
+  <rect x="158" y="118" width="150" height="6" rx="3" fill="#D8DEE7"/>
+
+  <circle cx="61" cy="145" r="4" fill="#9AA6B5"/>
+  <text x="72" y="149" font-family="system-ui, -apple-system, sans-serif" font-size="11.5" fill="#6B7280">Always available</text>
+  <text x="292" y="149" text-anchor="end" font-family="system-ui, -apple-system, sans-serif" font-size="12" fill="#1F2329">32</text>
+
+  <circle cx="61" cy="169" r="4" fill="#145AF3"/>
+  <text x="72" y="173" font-family="system-ui, -apple-system, sans-serif" font-size="11.5" fill="#6B7280">Loaded</text>
+  <text x="292" y="173" text-anchor="end" font-family="system-ui, -apple-system, sans-serif" font-size="12" fill="#1F2329">8</text>
+
+  <circle cx="61" cy="193" r="4" fill="#D8DEE7"/>
+  <text x="72" y="197" font-family="system-ui, -apple-system, sans-serif" font-size="11.5" fill="#6B7280">On demand</text>
+  <text x="292" y="197" text-anchor="end" font-family="system-ui, -apple-system, sans-serif" font-size="12" fill="#1F2329">92</text>
+
+  <text x="58" y="222" font-family="system-ui, -apple-system, sans-serif" font-size="10.5" fill="#8A93A0">19 groups · catalog generated 2m ago</text>
+  <text x="58" y="252" font-family="system-ui, -apple-system, sans-serif" font-size="10.5" fill="#8A93A0">Only this small directory stays in context.</text>
+
+
+  <!-- right: headline + metrics -->
+  <text x="376" y="58" font-family="system-ui, -apple-system, sans-serif" font-size="20" font-weight="700" fill="#1F2329">Tool schemas stay out of context.</text>
+  <text x="376" y="82" font-family="system-ui, -apple-system, sans-serif" font-size="12.5" fill="#4B5563">An agent reads your tools, builds a catalog,</text>
+  <text x="376" y="98" font-family="system-ui, -apple-system, sans-serif" font-size="12.5" fill="#4B5563">and loads tools on demand.</text>
+
+  <rect x="376" y="112" width="344" height="72" rx="12" fill="#FFFFFF" stroke="#E3E8EF"/>
+  <text x="394" y="140" font-family="system-ui, -apple-system, sans-serif" font-size="24" font-weight="700" fill="#145AF3">−83%</text>
+  <text x="474" y="134" font-family="system-ui, -apple-system, sans-serif" font-size="11.5" fill="#6B7280">tool-schema payload</text>
+  <text x="474" y="151" font-family="system-ui, -apple-system, sans-serif" font-size="11.5" fill="#1F2329">131,390 → 21,877 chars</text>
+
+  <rect x="376" y="194" width="344" height="72" rx="12" fill="#FFFFFF" stroke="#E3E8EF"/>
+  <text x="394" y="222" font-family="system-ui, -apple-system, sans-serif" font-size="24" font-weight="700" fill="#145AF3">−62.6%</text>
+  <text x="498" y="216" font-family="system-ui, -apple-system, sans-serif" font-size="11.5" fill="#6B7280">first-request prompt tokens</text>
+  <text x="498" y="233" font-family="system-ui, -apple-system, sans-serif" font-size="11.5" fill="#1F2329">49,504 → 18,536 (real usage)</text>
+
+  <rect x="376" y="276" width="344" height="72" rx="12" fill="#FFFFFF" stroke="#E3E8EF"/>
+  <text x="394" y="304" font-family="system-ui, -apple-system, sans-serif" font-size="24" font-weight="700" fill="#145AF3">100%</text>
+  <text x="474" y="298" font-family="system-ui, -apple-system, sans-serif" font-size="11.5" fill="#6B7280">task success, both arms</text>
+  <text x="474" y="315" font-family="system-ui, -apple-system, sans-serif" font-size="11.5" fill="#1F2329">10/10 · 5 tasks × 2 runs</text>
+
+  <text x="376" y="370" font-family="system-ui, -apple-system, sans-serif" font-size="10.5" fill="#8A93A0">Measured on DSH 0.2.2-rc.1 · deepseek-flash</text>
+  <text x="376" y="384" font-family="system-ui, -apple-system, sans-serif" font-size="10.5" fill="#8A93A0">Same tasks, model and tool surface.</text>
+</svg>

package/docs/detail.md

@@ -0,0 +1,33 @@
+![Agentic Tool Catalog: an agent builds the tool catalog, schemas stay out of context](./detail-hero.svg)
+
+**All your tools. None of the context cost.**
+
+Agentic Tool Catalog keeps a small, agent-built directory in context and loads tool schemas
+only when a task needs them.
+
+DSH normally sends every visible tool schema with every request. This plugin has a DSH
+sub-agent organize your tools into a compact catalog — then only that catalog stays in
+context, and `search_tools` loads the right tools on demand.
+
+## What you get
+
+- **A much smaller context** — in our A/B test the tool-schema payload dropped **83.3%** and
+  the real first-request prompt dropped **62.6%** (about 31k fewer tokens per request).
+- **No setup** — install a plugin or MCP server and the catalog regenerates when tools change.
+- **Works with any tool** — plugin, MCP, or built-in; other plugins don't need to cooperate.
+- **Local and private** — generated by your own model, cached in official DSH Storage.
+
+![With vs without: schema payload −83.3%, first-request prompt tokens −62.6%, total tokens −40.6%](./detail-benchmark.svg)
+
+Same tasks, same model, same tool surface; task success was 100% both with and without the
+plugin. The catalog saves context, not by making tasks cheaper to run.
+
+## Good to know
+
+- Works with DSH `>=0.2.1-rc.2 <0.3.0`; tested on `0.2.2-rc.1` and `0.2.2-rc.2`.
+- v1 covers **tools**; native skills keep their normal behavior.
+- The catalog is derived data and contains no messages, prompts, tool results or credentials.
+- It does **not** regenerate on a timer: only when the set of available tools changes. One-time
+  generation is cached, so a stable tool set costs nothing extra after the first run.
+- If a refresh fails, the last successful catalog stays active and retries; it never silently
+  hides tools.

package/docs/detail.zh.md

@@ -0,0 +1,30 @@
+![Agentic Tool Catalog：由 Agent 生成并维护工具目录，schema 不占上下文](./detail-hero.svg)
+
+**全部工具都在，但不占上下文成本。**
+
+Agent 工具目录在上下文里只保留一份由 Agent 生成的小目录；工具 schema 等到任务真正需要时才加载。
+
+DSH 默认会把每个可见工具的完整 schema 放进每一次请求。这个插件让 DSH 子代理先把工具整理成
+一份紧凑目录——之后上下文里只有目录，`search_tools` 在需要时加载对应工具。
+
+## 它能给你什么
+
+- **上下文小得多**——在我们的 A/B 实测中，工具 schema 载荷下降 **83.3%**，真实首请求 prompt
+  下降 **62.6%**（每请求约少 3.1 万 tokens）。
+- **无需配置**——新装插件或 MCP server 后，工具变化时目录会自动重建。
+- **任何工具都能用**——插件、MCP、内置工具；其他插件不需要配合。
+- **本地、私密**——由本机模型生成，缓存进官方 DSH Storage。
+
+![用 vs 不用：schema 载荷 −83.3%、首请求 prompt −62.6%、总 tokens −40.6%](./detail-benchmark.svg)
+
+同一批任务、同一模型、同一工具面；用与不用这个插件，任务成功率都是 100%。它省的是上下文，
+不是把任务本身变便宜。
+
+## 你需要知道
+
+- 适用于 DSH `>=0.2.1-rc.2 <0.3.0`；已在 `0.2.2-rc.1` 与 `0.2.2-rc.2` 上验证。
+- v1 覆盖 **tools**；DSH 原生 skills 行为不变。
+- 目录是派生数据，不含消息、提示词、工具结果或凭据。
+- **不会定时重新生成**：只有可用工具集发生变化时才重建。生成结果会被缓存，工具集稳定的情况下
+  首次生成之后没有额外成本。
+- 如果刷新失败，会继续使用上一次成功的目录并自动重试，不会静默隐藏工具。

package/icon.svg

@@ -0,0 +1,15 @@
+<svg width="36" height="36" viewBox="0 0 36 36" fill="none" xmlns="http://www.w3.org/2000/svg">
+  <rect x="5" y="6" width="19.5" height="24" rx="3.6" stroke="url(#dsh-atc-card)" stroke-width="3.2" />
+  <path d="M10.5 13.5h8.2M10.5 18h8.2M10.5 22.5h5.2" stroke="url(#dsh-atc-lines)" stroke-width="3.2" stroke-linecap="round" />
+  <path d="M27.6 4.8l1.15 2.95 2.95 1.15-2.95 1.15-1.15 2.95-1.15-2.95L23.5 8.9l2.95-1.15z" fill="#45D9E7" />
+  <defs>
+    <linearGradient id="dsh-atc-card" x1="5" y1="6" x2="24.5" y2="30" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#7CB7FF" />
+      <stop offset="1" stop-color="#145AF3" />
+    </linearGradient>
+    <linearGradient id="dsh-atc-lines" x1="10.5" y1="13.5" x2="18.7" y2="22.5" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#7CB7FF" />
+      <stop offset="1" stop-color="#145AF3" />
+    </linearGradient>
+  </defs>
+</svg>

package/lib/catalog.js

@@ -0,0 +1,208 @@
+/**
+ * policy.js —— Tool Discovery 的非策略底座（2026-11-10 用户决策：只保留真 agent 策略）。
+ *
+ * legacy/rules/bm25/oracle/minimal/Jev/LLM/full-combo 等旧策略已全部移除。
+ * 保留：常驻判定、工具名规范化、引导目录（bootstrap）、确定性搜索、note/摘要。
+ * 真正的分组由 `agent-groups.js` 的真子代理生成；生成完成前用 bootstrap 扁平目录过渡。
+ *
+ * @module @local/dsh-tool-discovery/policy
+ */
+export const DEFAULT_RESIDENT = [
+  // 执行基本盘
+  'bash', 'read', 'write', 'edit', 'glob', 'grep', 'read_image',
+  'ask_user_question', 'todo_write', 'skill', 'job_*', 'web_search', 'web_fetch',
+  'working_directory', 'load_workspace_dependencies', 'exit_plan_mode', 'present',
+  // 委派 / 通信
+  'subagent', 'subagent_fork', 'send_message', 'list_agents', 'interrupt_agent',
+  // MCP 资源读取
+  'list_mcp_resources', 'list_mcp_resource_templates', 'read_mcp_resource',
+  // discovery 自己的入口
+  'search_tools', 'catalog_status',
+  // Agent Teams（own-layer，实际也不可 restrict；显式列出表达"就是常驻"）
+  'spawn_teammate', 'wait_agent', 'team_task_*',
+]
+
+export function compileGlob(pattern) {
+  const escaped = String(pattern).replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*')
+  return new RegExp(`^${escaped}$`)
+}
+
+export function tokensOf(name) {
+  return String(name).toLowerCase().split(/[^a-z0-9]+/).filter(Boolean)
+}
+
+export function normalizeGroupId(raw) {
+  const id = String(raw ?? '').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 64)
+  return id.length > 0 ? id : 'extensions'
+}
+
+export function mcpInfo(name) {
+  if (!name.startsWith('mcp__')) return undefined
+  const rest = name.slice('mcp__'.length)
+  const separator = rest.indexOf('__')
+  if (separator <= 0) return undefined
+  const server = rest.slice(0, separator)
+  return { server, id: `mcp-${normalizeGroupId(server)}` }
+}
+
+export function residentMatcher(config = {}) {
+  const override = Array.isArray(config.resident) && config.resident.length > 0 ? config.resident : undefined
+  const base = override ?? DEFAULT_RESIDENT
+  const patterns = [...base, ...(config.extraKeepResident ?? [])].map(compileGlob)
+  const deferred = (config.extraDeferred ?? []).map(compileGlob)
+  return (name) => {
+    if (deferred.some((re) => re.test(name))) return false
+    return patterns.some((re) => re.test(name))
+  }
+}
+
+function membersDescription(id, members, limit = 200) {
+  const names = members.map((m) => m.name)
+  const sample = names.slice(0, 8).join(', ')
+  const more = names.length > 8 ? ` (+${names.length - 8} more)` : ''
+  const prefix = id.startsWith('mcp-') ? `MCP server "${id.slice('mcp-'.length)}" tools: ` : 'Tools: '
+  const text = `${prefix}${sample}${more}.`
+  return text.length <= limit ? text : `${text.slice(0, limit - 1)}…`
+}
+
+export function summarizeGroups(entries, descriptions = new Map()) {
+  const byGroup = new Map()
+  for (const entry of entries) {
+    if (!byGroup.has(entry.group)) byGroup.set(entry.group, [])
+    byGroup.get(entry.group).push(entry)
+  }
+  return [...byGroup.entries()]
+    .map(([id, members]) => ({
+      id,
+      description: descriptions.get(id) ?? membersDescription(id, members),
+      count: members.length,
+      members: members.map((m) => m.name).sort(),
+    }))
+    .sort((a, b) => b.count - a.count || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0))
+}
+
+/** 引导目录：agent 分组尚未就绪时的最小目录（不假装是分组策略）。 */
+export function buildBootstrapCatalog(tools) {
+  const entries = tools.map((tool) => ({ ...tool, group: 'others' }))
+  return {
+    strategy: 'agentic-tool-catalog',
+    source: 'bootstrap',
+    entries,
+    groups: [],
+    others: entries.map((entry) => entry.name).sort(),
+    warnings: [{ kind: 'catalog-bootstrap', message: `agent 分组尚未就绪：${tools.length} 个工具暂以扁平目录提供` }],
+  }
+}
+
+export const SCORE = { name: 6, description: 2, groupId: 4, groupDescription: 2 }
+
+export const QUERY_STOPWORDS = new Set([
+  'get', 'set', 'list', 'create', 'update', 'delete', 'remove', 'read', 'write',
+  'add', 'edit', 'run', 'query', 'status', 'manage', 'execute', 'copy', 'move',
+])
+
+export function singularize(token) {
+  const t = String(token).toLowerCase()
+  if (t.length <= 3) return t
+  if (t.endsWith('ies')) return `${t.slice(0, -3)}y`
+  if (t.endsWith('es')) return t.slice(0, -2)
+  if (t.endsWith('s')) return t.slice(0, -1)
+  return t
+}
+
+export function queryTokens(query) {
+  const raw = String(query ?? '').toLowerCase().split(/[^a-z0-9]+/).filter(Boolean)
+  const meaningful = raw.filter((t) => !QUERY_STOPWORDS.has(t) && !QUERY_STOPWORDS.has(singularize(t)))
+  const base = meaningful.length > 0 ? meaningful : raw
+  const out = new Set()
+  for (const token of base) {
+    out.add(token)
+    out.add(singularize(token))
+  }
+  return [...out]
+}
+
+export function rankTools(catalog, query, options = {}) {
+  const limit = Math.max(1, Math.min(20, options.limit ?? 6))
+  const groupMax = Math.max(1, options.groupMaxResults ?? 30)
+  const loadedSet = options.loaded instanceof Set ? options.loaded : new Set(options.loaded ?? [])
+  const raw = String(query ?? '').trim().toLowerCase()
+  const groupById = new Map(catalog.groups.map((g) => [g.id.toLowerCase(), g]))
+  const exact = groupById.get(raw)
+  if (exact !== undefined) {
+    const members = exact.members.filter((name) => !loadedSet.has(name))
+    const loaded = members.slice(0, groupMax)
+    return { loaded, more: 0, groupLoad: true, groupId: exact.id, remainingInGroup: members.length - loaded.length }
+  }
+  const tokens = queryTokens(raw)
+  if (tokens.length === 0) return { loaded: [], more: 0, groupLoad: false, groupId: null, remainingInGroup: 0 }
+  const groupText = new Map(catalog.groups.map((g) => [g.id, `${g.id} ${g.description}`.toLowerCase()]))
+  const scored = []
+  for (const entry of catalog.entries) {
+    if (loadedSet.has(entry.name)) continue
+    const name = entry.name.toLowerCase()
+    const description = String(entry.description ?? '').toLowerCase()
+    const gid = entry.group.toLowerCase()
+    const gtext = groupText.get(entry.group) ?? ''
+    let score = 0
+    for (const token of tokens) {
+      if (name.includes(token)) score += SCORE.name
+      if (description.includes(token)) score += SCORE.description
+      if (gid.includes(token)) score += SCORE.groupId
+      if (gtext.includes(token)) score += SCORE.groupDescription
+    }
+    if (score > 0) scored.push({ entry, score })
+  }
+  scored.sort((a, b) => b.score - a.score || (a.entry.name < b.entry.name ? -1 : a.entry.name > b.entry.name ? 1 : 0))
+  const picked = scored.slice(0, limit)
+  return {
+    loaded: picked.map((p) => p.entry.name),
+    more: scored.length - picked.length,
+    groupLoad: false,
+    groupId: null,
+    remainingInGroup: 0,
+  }
+}
+
+/** 系统提示 note：组 + 计数；rules 策略附带 others 名字（上限 maxOtherNames）。 */
+
+export function noteText(catalog, loaded, options = {}) {
+  const maxOtherNames = options.maxOtherNames ?? 20
+  const loadedSet = loaded instanceof Set ? loaded : new Set(loaded ?? [])
+  const groupCounts = new Map()
+  for (const entry of catalog.entries) {
+    if (loadedSet.has(entry.name)) continue
+    if (entry.group === 'others') continue
+    groupCounts.set(entry.group, (groupCounts.get(entry.group) ?? 0) + 1)
+  }
+  const groups = [...groupCounts.entries()]
+    .map(([id, count]) => ({ id, count }))
+    .sort((a, b) => b.count - a.count || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0))
+  const others = catalog.others.filter((name) => !loadedSet.has(name))
+  if (groups.length === 0 && others.length === 0) return ''
+  const groupText = groups.map((g) => `${g.id} (${g.count})`).join(', ')
+  const shownOthers = others.slice(0, maxOtherNames)
+  const moreOthers = others.length - shownOthers.length
+  const othersText = shownOthers.length === 0
+    ? ''
+    : ` Others: ${shownOthers.join(', ')}${moreOthers > 0 ? ` (+${moreOthers} more)` : ''}.`
+  const head = groups.length > 0 ? `Some capability tools are deferred and not loaded: ${groupText}.` : 'Some capability tools are deferred and not loaded.'
+  const prefix = catalog.source === 'bootstrap'
+    ? `Tool catalog is initializing: ${catalog.entries.length} capabilities are searchable by name; grouping completes in the background. `
+    : catalog.source === 'agent-stale'
+      ? 'Note: using the most recent successful grouping while the catalog refreshes. '
+      : ''
+  return `${prefix}${head}${othersText} Use search_tools to load the ones you need before calling them.`
+}
+
+/** 零命中时的目录页：组 + 描述；others 单列。 */
+
+export function catalogSummary(catalog, limit = 200) {
+  const lines = catalog.groups.map((g) => `- ${g.id} (${g.count} tools): ${String(g.description).slice(0, limit)}`)
+  if (catalog.others.length > 0) {
+    const sample = catalog.others.slice(0, 30).join(', ')
+    const more = catalog.others.length > 30 ? ` (+${catalog.others.length - 30} more)` : ''
+    lines.push(`- others (${catalog.others.length} tools): ${sample}${more}`)
+  }
+  return lines.join('\n')
+}