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

package/lib/store.js

@@ -0,0 +1,108 @@
+/**
+ * store.js —— 目录持久化：只使用 DSH 官方 Storage（storageDomain）。
+ *
+ * 数据是派生缓存（丢了重新生成一次即可），但按用户决策统一走官方持久化：
+ *   - 声明 domain `agentic-tool-catalog`（version 1）：`catalogs` 表按目录指纹存原始分组，
+ *     `state` 表存最近一次成功分组（lastGood）；
+ *   - 没有 `storageDomain` 服务的 profile → 纯内存缓存（功能可用，重启重新生成一次），
+ *     **不做第二份文件后端**；
+ *   - 写入 fire-and-forget：失败只记日志，不影响当前会话；读取在启动时 hydrate 到共享内存。
+ *
+ * @module @local/dsh-agentic-tool-catalog/store
+ */
+import { defineDomain, domainTable } from '@deepseek-ai/dsh-storage-domain'
+import { z } from 'zod'
+
+/** 一个分组（模型输出的原始形状，tools 为工具名；读取时复用 generation.validateAgentGroups 校验）。 */
+const groupRecord = z.object({
+  id: z.string(),
+  description: z.string(),
+  tools: z.array(z.string()),
+})
+
+/** 按目录指纹存的一版分组。 */
+const catalogRecord = z.object({
+  fingerprint: z.string(),
+  groups: z.array(groupRecord),
+  createdAt: z.number(),
+})
+
+/** 最近一次成功分组（生成失败时保持目录连续；状态会显式标 stale，不静默）。 */
+const lastGoodRecord = z.object({
+  fingerprint: z.string(),
+  groups: z.array(groupRecord),
+  at: z.number(),
+})
+
+/** 我们的存储 domain：唯一身份/版本/schema 来源。 */
+export const CATALOG_DOMAIN = defineDomain({
+  name: 'agentic_tool_catalog',
+  version: 1,
+  tables: {
+    catalogs: domainTable(catalogRecord),
+    state: domainTable(lastGoodRecord),
+  },
+})
+
+/**
+ * 创建目录存储。
+ * @param ctx - 插件 ctx（需要 `ctx.get('storageDomain')` 与 effect 生命周期）。
+ * @param shared - 进程级共享状态（`groups` Map / `lastGood`）。
+ * @param logger - 可选 logger。
+ */
+export function createCatalogStore(ctx, shared, logger) {
+  const storageDomain = ctx.get?.('storageDomain')
+  const info = { available: false, state: storageDomain === undefined ? 'unavailable' : 'opening', lastError: null }
+  let domain
+  let ready = Promise.resolve(false)
+
+  const log = (message) => logger?.warn?.(`dsh-agentic-tool-catalog: ${message}`)
+
+  if (storageDomain !== undefined) {
+    ready = (async () => {
+      try {
+        domain = await storageDomain.open(CATALOG_DOMAIN)
+        ctx.effect(() => () => domain.close())
+        for (const [fingerprint, record] of domain.table('catalogs').entries()) {
+          if (record !== undefined && Array.isArray(record.groups)) shared.groups.set(fingerprint, record.groups)
+        }
+        const lastGood = domain.table('state').get('lastGood')
+        if (lastGood !== undefined && Array.isArray(lastGood.groups)) shared.lastGood = lastGood
+        info.available = true
+        info.state = 'ready'
+        return true
+      } catch (error) {
+        info.available = false
+        info.state = 'failed'
+        info.lastError = String(error?.message ?? error).slice(0, 200)
+        log(`官方 Storage 打开失败，使用纯内存缓存：${info.lastError}`)
+        return false
+      }
+    })()
+  }
+
+  /** 启动时 hydrate 完成（true=官方存储可用；false=内存模式）。 */
+  const whenReady = () => ready
+  const available = () => info.available
+  const status = () => ({ ...info })
+
+  /** 保存一版目录分组（fire-and-forget；失败只记日志）。 */
+  const saveGroups = (fingerprint, groups) => {
+    shared.groups.set(fingerprint, groups)
+    if (!info.available) return
+    Promise.resolve()
+      .then(() => domain.table('catalogs').put(fingerprint, { fingerprint, groups, createdAt: Date.now() }))
+      .catch((error) => log(`目录缓存写入失败（不影响当前会话）：${String(error?.message ?? error).slice(0, 160)}`))
+  }
+
+  /** 保存最近一次成功分组（fire-and-forget）。 */
+  const saveLastGood = (lastGood) => {
+    shared.lastGood = lastGood
+    if (!info.available) return
+    Promise.resolve()
+      .then(() => domain.table('state').put('lastGood', lastGood))
+      .catch((error) => log(`最近成功分组写入失败（不影响当前会话）：${String(error?.message ?? error).slice(0, 160)}`))
+  }
+
+  return { whenReady, available, status, saveGroups, saveLastGood, info }
+}

package/lib/subagent-compat.js

@@ -0,0 +1,87 @@
+/**
+ * subagent-compat.js —— 唯一知道宿主 `ctx.subagents.startActivation()` 入参形状的地方。
+ *
+ * 背景（2026-11-12 实测）：
+ *   - DSH 0.2.1-rc.2 … 0.2.2-rc.1：请求字段装在 `spec.request` 里
+ *     （`{ provider, label, request: { parent, prompt, maxDepth, outputSchema, ... }, signal, delivery }`）；
+ *   - DSH 0.2.2-rc.2+：同一组字段被拍平到 spec 顶层，`startActivation` 直接读 `spec.parent.id`。
+ *
+ * 兼容策略：同时发送两种形状。
+ *   - 顶层字段服务 0.2.2-rc.2+；
+ *   - 不可枚举的 `request` 属性服务旧版（旧版只做属性读取 `spec.request`，仍可访问）；
+ *   - 不可枚举很重要：rc.2 的外部 provider 路径会把 spec 的剩余字段展开进 provider 请求，
+ *     可枚举的 `request` 会泄漏过去；不可枚举属性不会被展开。
+ *   - 两个版本的实现都只读自己认识的字段、不校验未知字段，因此并集是安全的。
+ *
+ * 这里是**唯一**允许出现版本形状差异的文件；其余代码只调用 `startSubagentActivation()`。
+ * 契约由 `scripts/verify-subagent-compat.mjs` 用真实的
+ * `@deepseek-ai/dsh-subagent@0.2.2-rc.1` / `@0.2.2-rc.2` 实现验证。
+ *
+ * @module @local/dsh-agentic-tool-catalog/subagent-compat
+ */
+
+/** 适配器同时支持的激活 spec 形状（用于状态观测；不代表宿主版本）。 */
+export const ACTIVATION_SHAPES = Object.freeze(['flat', 'nested'])
+
+/** 属于 `SubagentStartRequest`（随版本在顶层 / request 之间搬家的字段）。 */
+export const ACTIVATION_REQUEST_FIELDS = Object.freeze([
+  'cwd',
+  'agentPreset',
+  'prompt',
+  'parent',
+  'agentOptions',
+  'outputSchema',
+  'maxDepth',
+])
+
+/**
+ * 把扁平请求构造成两种宿主都能读的 activation spec。
+ * @param spec - 扁平请求（含 provider / label / signal / delivery 与 request 字段）。
+ * @returns 可直接传给 `ctx.subagents.startActivation()` 的 spec。
+ */
+export function buildSubagentActivationSpec(spec) {
+  const request = {}
+  for (const key of ACTIVATION_REQUEST_FIELDS) {
+    if (spec[key] !== undefined) request[key] = spec[key]
+  }
+  const activationSpec = {
+    provider: spec.provider,
+    label: spec.label,
+    ...(spec.name === undefined ? {} : { name: spec.name }),
+    ...(spec.childId === undefined ? {} : { childId: spec.childId }),
+    // 0.2.2-rc.2+：字段在顶层。
+    ...request,
+    signal: spec.signal,
+    delivery: spec.delivery,
+  }
+  // 0.2.1-rc.2 … 0.2.2-rc.1：字段在 request 里。不可枚举，避免 rc.2 的外部 provider 展开时泄漏。
+  Object.defineProperty(activationSpec, 'request', {
+    value: request,
+    enumerable: false,
+    configurable: true,
+    writable: false,
+  })
+  return activationSpec
+}
+
+/**
+ * 启动一个子代理激活，自动适配宿主的 spec 形状。
+ * @param subagents - `ctx.get('subagents')` 得到的服务。
+ * @param spec - 扁平请求（见 {@link ACTIVATION_REQUEST_FIELDS}）。
+ * @returns `startActivation()` 的原样结果。
+ */
+export function startSubagentActivation(subagents, spec) {
+  return subagents.startActivation(buildSubagentActivationSpec(spec))
+}
+
+/**
+ * 判断一个失败是否像"宿主不认识 activation spec 形状"（而非业务/模型失败）。
+ * 仅用于观测与软闸门：形状错误发生在创建子代理之前，无副作用。
+ * @param error - 捕获到的错误。
+ * @returns 是否匹配各版本读取缺失字段时的 TypeError。
+ */
+export function isActivationShapeError(error) {
+  if (!(error instanceof TypeError)) return false
+  const message = String(error.message ?? '')
+  return /Cannot read properties of undefined \(reading '(?:id|parent|prompt|request|maxDepth|outputSchema|cwd|agentPreset|agentOptions)'\)/.test(message)
+}

package/locale/en.json

@@ -0,0 +1,7 @@
+{
+  "meta": {
+    "title": "Agentic Tool Catalog",
+    "description": "An agent builds and maintains the tool catalog: keep tool schemas out of context, search the catalog and load tools on demand for the current session.",
+    "detail": "docs/detail.md"
+  }
+}

package/locale/zh.json

@@ -0,0 +1,7 @@
+{
+  "meta": {
+    "title": "Agent 工具目录",
+    "description": "由 Agent 自动生成并维护工具目录：工具 schema 默认不占上下文，按需搜索并加载到当前会话。",
+    "detail": "docs/detail.zh.md"
+  }
+}

package/package.json

@@ -1,6 +1,92 @@
 {
   "name": "dsh-agentic-tool-catalog",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.2",
+  "description": "Agentic Tool Catalog for DSH: an agent builds and maintains a tool catalog; schemas stay out of context and tools load on demand.",
+  "icon": "./icon.svg",
+  "type": "module",
+  "exports": {
+    ".": "./lib/index.js",
+    "./client": "./lib/client.js",
+    "./package.json": "./package.json",
+    "./locale/*.json": "./locale/*.json"
+  },
+  "files": [
+    "CHANGELOG.md",
+    "LICENSE",
+    "README.md",
+    "README.zh.md",
+    "cordis.patch.yml",
+    "docs/assets/*",
+    "docs/assets/plugin-page.png",
+    "docs/benchmark.md",
+    "docs/data-card.md",
+    "docs/detail-benchmark.svg",
+    "docs/detail-hero.svg",
+    "docs/detail.md",
+    "docs/detail.zh.md",
+    "icon.svg",
+    "lib/*.js",
+    "locale/*.json"
+  ],
+  "peerDependencies": {
+    "@deepseek-ai/dsh-scope": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-tools": "^0.2.0-rc.2",
+    "@deepseek-ai/schemastery": "~3.18.4",
+    "@deepseek-ai/dsh-storage-domain": "^0.2.2-rc.1",
+    "zod": "^4.4.3"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/dsh-scope": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-tools": {
+      "optional": true
+    },
+    "@deepseek-ai/schemastery": {
+      "optional": true
+    }
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "immediately": true,
+      "inject": [
+        "@deepseek-ai/dsh-client-ui-conversation"
+      ]
+    }
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/laughinbytes/dsh-agentic-tool-catalog.git"
+  },
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "deepseek-harness",
+    "tool-catalog",
+    "on-demand",
+    "mcp",
+    "context",
+    "agent"
+  ],
+  "author": "laughinbytes",
+  "homepage": "https://github.com/laughinbytes/dsh-agentic-tool-catalog#readme",
+  "bugs": {
+    "url": "https://github.com/laughinbytes/dsh-agentic-tool-catalog/issues"
+  },
+  "engines": {
+    "node": ">=22.19.0",
+    "dsh": ">=0.2.1-rc.2 <0.3.0-0"
+  },
+  "scripts": {
+    "test": "node scripts/verify-agentic-tool-catalog.mjs && node scripts/verify-agentic-tool-catalog-schema.mjs && node scripts/verify-subagent-compat.mjs",
+    "test:schema": "node scripts/verify-agentic-tool-catalog-schema.mjs",
+    "test:compat": "node scripts/verify-subagent-compat.mjs",
+    "pack:check": "npm pack --dry-run",
+    "test:presentation": "node scripts/verify-presentation.mjs"
+  }
+}