dsh-plugin-library 0.1.0

package/dist/host.js

@@ -0,0 +1,1626 @@
+// ../../shared/host/route.mjs
+function json(body, status) {
+  return Response.json(body, { status, headers: { "cache-control": "no-store" } });
+}
+function ok(value) {
+  return json({ ok: true, value: value ?? null }, 200);
+}
+function fail(code, message) {
+  return json({ ok: false, error: { code, message } }, 200);
+}
+var FeatureError2 = class extends Error {
+  /**
+   * @param {string} code - stable machine-readable code, for example `connector/not-found`.
+   * @param {string} message - human-readable reason shown to the user.
+   */
+  constructor(code, message) {
+    super(message);
+    this.name = "FeatureError";
+    this.code = code;
+  }
+};
+function registerFeatureRoute(ctx, { feature, handlers, methods = ["POST"] }) {
+  const path = `/api/dsh-skills/${feature}`;
+  return ctx.effect(
+    () => ctx.connection.fetch.register({
+      path,
+      methods: [...methods],
+      requestBody: "buffered",
+      fetch: async (request) => {
+        try {
+          if (request.method !== "POST") return fail("method-not-allowed", "\u6B64\u8DEF\u7531\u53EA\u63A5\u53D7 POST");
+          const body = await request.json().catch(() => null);
+          if (body === null || typeof body !== "object" || Array.isArray(body)) {
+            return fail("malformed-request", "\u8BF7\u6C42\u4F53\u5FC5\u987B\u662F JSON \u5BF9\u8C61");
+          }
+          const { endpoint, payload } = body;
+          if (typeof endpoint !== "string") return fail("malformed-request", "endpoint \u5FC5\u987B\u662F\u5B57\u7B26\u4E32");
+          const handler = Object.hasOwn(handlers, endpoint) ? handlers[endpoint] : void 0;
+          if (typeof handler !== "function") return fail("unknown-endpoint", `\u672A\u77E5\u7AEF\u70B9 ${JSON.stringify(endpoint)}`);
+          const result = await handler(payload ?? {}, request);
+          return result instanceof Response ? result : ok(result);
+        } catch (error) {
+          const code = typeof error?.code === "string" && error.code.length > 0 ? error.code : "handler-failed";
+          return fail(code, String(error?.message ?? error));
+        }
+      }
+    }),
+    `dsh-skills: ${feature} route`
+  );
+}
+
+// ../../shared/dsh-package.mjs
+import { createRequire } from "node:module";
+import { isAbsolute, join } from "node:path";
+import { pathToFileURL } from "node:url";
+function dshResolutionAnchors({ argv = process.argv, cwd = process.cwd() } = {}) {
+  const anchors = [];
+  if (typeof argv[1] === "string" && isAbsolute(argv[1])) anchors.push(argv[1]);
+  if (typeof argv[2] === "string" && isAbsolute(argv[2])) anchors.push(join(argv[2], "package.json"));
+  anchors.push(join(cwd, "package.json"));
+  return [...new Set(anchors)];
+}
+var stubs = /* @__PURE__ */ new Map();
+function resolveDshPackage(specifier, options = {}) {
+  if (stubs.has(specifier)) return `stub:${specifier}`;
+  const tried = [];
+  for (const anchor of dshResolutionAnchors(options)) {
+    try {
+      return createRequire(anchor).resolve(specifier);
+    } catch (error) {
+      tried.push(`${anchor} (${error?.code ?? error?.name ?? "error"})`);
+    }
+  }
+  throw new Error(
+    `dsh-skills: cannot resolve ${JSON.stringify(specifier)} from the dsh installation or the profile.
+Tried: ${tried.join(", ")}
+A Host half must not import an official package by bare specifier: Node resolves that from
+this plugin's realpath, which is outside the installation. Use importDshPackage() instead.`
+  );
+}
+async function importDshPackage(specifier, options) {
+  const stub = stubs.get(specifier);
+  if (stub !== void 0) return stub;
+  return import(pathToFileURL(resolveDshPackage(specifier, options)).href);
+}
+
+// ../../shared/host/storage.mjs
+var cached;
+async function storageKit() {
+  if (cached !== void 0) return cached;
+  const [domain, zod] = await Promise.all([
+    importDshPackage("@deepseek-ai/dsh-storage-domain"),
+    importDshPackage("zod")
+  ]);
+  const z = zod.z ?? zod.default ?? zod;
+  if (typeof domain?.defineDomain !== "function" || typeof domain?.domainTable !== "function") {
+    throw new Error("dsh-skills: @deepseek-ai/dsh-storage-domain no longer exports defineDomain/domainTable");
+  }
+  if (typeof z?.object !== "function") {
+    throw new Error("dsh-skills: the installation's zod does not expose z.object");
+  }
+  cached = { defineDomain: domain.defineDomain, domainTable: domain.domainTable, descriptorOf: domain.descriptorOf, z };
+  return cached;
+}
+
+// src/attribution.js
+import { resolve } from "node:path";
+function absolutePath(path, cwd) {
+  if (cwd === void 0 || cwd.length === 0) return path;
+  return resolve(cwd, path);
+}
+function registerDeliverableImport(ctx, manager) {
+  const warn = (message) => ctx.logger?.warn?.(`dsh-plugin-library: ${message}`);
+  const inflight = /* @__PURE__ */ new Set();
+  const dispose = ctx.on("session/event", (session, event) => {
+    if (event?.type !== "deliverables/presented") return;
+    const sessionId = String(session?.id ?? "");
+    if (sessionId.length === 0) return;
+    const cwd = session?.header?.cwd;
+    const files = Array.isArray(event?.data?.files) ? event.data.files : [];
+    const seen = /* @__PURE__ */ new Set();
+    for (const file of files) {
+      const path = absolutePath(file?.path ?? "", cwd);
+      if (path.length === 0) continue;
+      if (seen.has(path)) continue;
+      seen.add(path);
+      const run = (async () => {
+        const entry = await manager.importTaskFile({
+          path,
+          sourceTaskId: sessionId
+        });
+        ctx.emit("library/deliverable-imported", { sessionId, path, entry });
+      })().catch((cause) => {
+        warn(`\u4EA4\u4ED8\u5165\u5E93\u5931\u8D25\uFF1A${path}\uFF08${cause instanceof Error ? cause.message : String(cause)}\uFF09`);
+      });
+      inflight.add(run);
+      run.finally(() => {
+        inflight.delete(run);
+      });
+    }
+  });
+  return {
+    dispose,
+    flush: async () => {
+      while (inflight.size > 0) await Promise.allSettled([...inflight]);
+    }
+  };
+}
+
+// src/domains.js
+var LOCAL_PRINCIPAL = "local";
+function buildLibraryDomains({ z, defineDomain, domainTable }) {
+  const loose = z.record(z.string(), z.unknown());
+  const stateSchema = z.object({
+    schemaVersion: z.literal(1),
+    /** Tree nodes: folders and asset nodes. `id` is the node id (equal to `assetId` for assets). */
+    nodes: loose,
+    /** Asset records keyed by asset id. */
+    assets: loose,
+    /** Immutable revision records keyed `${assetId}:${sha256}`. */
+    revisions: loose,
+    /**
+     * Editable drafts keyed by draft id, added after the first release.
+     *
+     * `.default({})`, never a plain required key: the domain facility validates
+     * **every stored record on `open()`**, before any consumer sees it, and an
+     * unparsable record is a hard `DomainError`. A plain key would therefore make
+     * every library record written before drafts existed fail to parse — taking
+     * the route, the tools and the whole panel down on the next launch. This is
+     * exactly the failure docs/PORTING-NOTES.md §15 records for experts.
+     */
+    drafts: loose.default({})
+  });
+  return {
+    stateSchema,
+    libraryDomain: defineDomain({
+      name: "dsh_skills_library",
+      version: 1,
+      layout: "per-record",
+      tables: { states: domainTable(stateSchema) }
+    })
+  };
+}
+
+// src/manager.js
+import { createHash, randomUUID } from "node:crypto";
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { basename, dirname, extname as extname2, join as join2, resolve as resolve2, sep } from "node:path";
+
+// src/convert.js
+import { extname } from "node:path";
+var KINDS_BY_EXTENSION = {
+  ".md": "markdown",
+  ".markdown": "markdown",
+  ".txt": "text",
+  ".html": "html",
+  ".htm": "html",
+  ".json": "json",
+  ".csv": "csv",
+  ".log": "log"
+};
+var MEDIA_TYPES_BY_KIND = {
+  markdown: "text/markdown",
+  text: "text/plain",
+  html: "text/html",
+  json: "application/json",
+  csv: "text/csv",
+  log: "text/plain",
+  binary: "application/octet-stream"
+};
+var ENTITIES = { amp: "&", lt: "<", gt: ">", quot: '"', apos: "'", nbsp: " " };
+function kindForName(name2) {
+  return KINDS_BY_EXTENSION[extname(String(name2)).toLowerCase()] ?? "binary";
+}
+function mediaTypeForKind(kind) {
+  return MEDIA_TYPES_BY_KIND[kind] ?? MEDIA_TYPES_BY_KIND.binary;
+}
+function decodeEntities(value) {
+  return value.replace(/&(#x[0-9a-f]+|#\d+|[a-z]+);/gi, (whole, code) => {
+    if (code[0] !== "#") return ENTITIES[code.toLowerCase()] ?? whole;
+    const point = code[1]?.toLowerCase() === "x" ? Number.parseInt(code.slice(2), 16) : Number.parseInt(code.slice(1), 10);
+    return Number.isFinite(point) ? String.fromCodePoint(point) : whole;
+  });
+}
+function stripHtml(source) {
+  const withoutComments = source.replace(/<!--[\s\S]*?-->/g, " ");
+  const withoutHidden = withoutComments.replace(
+    /<(script|style|noscript|template|svg|canvas)(?:\s[^>]*)?>[\s\S]*?<\/\1\s*>/gi,
+    " "
+  );
+  const broken = withoutHidden.replace(/<(br|hr)\s*\/?>/gi, "\n").replace(/<\/(p|div|section|article|main|header|footer|li|tr|h[1-6]|ul|ol|table|blockquote|pre)\s*>/gi, "\n");
+  const text = decodeEntities(broken.replace(/<[^>]*>/g, " "));
+  return `${text.split("\n").map((line) => line.replace(/[\t ]+/g, " ").trim()).filter(Boolean).join("\n\n")}
+`;
+}
+function deriveText(kind, bytes) {
+  if (kind === "binary") {
+    return {
+      text: "",
+      status: "unavailable",
+      warnings: ["\u8BE5\u683C\u5F0F\u6CA1\u6709\u6587\u672C\u8F6C\u6362\uFF0C\u4EC5\u4FDD\u5B58\u539F\u4EF6\uFF1B\u4E0D\u53C2\u4E0E\u6B63\u6587\u641C\u7D22\u3002"]
+    };
+  }
+  let source;
+  try {
+    source = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+  } catch {
+    return {
+      text: "",
+      status: "failed",
+      warnings: ["\u6587\u4EF6\u4E0D\u662F\u6709\u6548\u7684 UTF-8 \u6587\u672C\uFF0C\u65E0\u6CD5\u751F\u6210\u68C0\u7D22\u6587\u672C\uFF1B\u539F\u4EF6\u5DF2\u5B8C\u6574\u4FDD\u5B58\u3002"]
+    };
+  }
+  const normalized = source.replace(/\r\n?/g, "\n");
+  if (kind === "html") {
+    return {
+      text: stripHtml(normalized),
+      status: "ready",
+      warnings: ["\u811A\u672C\u3001\u6837\u5F0F\u3001SVG \u4E0E\u753B\u5E03\u5185\u5BB9\u4E0D\u8FDB\u5165\u68C0\u7D22\u6587\u672C\uFF1B\u539F\u59CB HTML \u4ECD\u6309\u5B57\u8282\u4FDD\u5B58\u3002"]
+    };
+  }
+  return { text: normalized, status: "ready", warnings: [] };
+}
+
+// src/native-open.js
+var cached2;
+async function loadNativeCommand() {
+  if (cached2 !== void 0) return cached2;
+  try {
+    const mod = await importDshPackage("@deepseek-ai/dsh-native-command");
+    if (typeof mod?.openNativeAssociatedPath === "function") {
+      cached2 = mod;
+      return cached2;
+    }
+  } catch {
+  }
+  cached2 = {
+    openNativeAssociatedPath: async () => {
+      throw new FeatureError2("library/native-unavailable", "\u5F53\u524D\u73AF\u5883\u65E0\u6CD5\u8C03\u7528\u7CFB\u7EDF\u7A0B\u5E8F\u6253\u5F00\u6587\u4EF6\uFF08\u539F\u751F\u547D\u4EE4\u5C42\u4E0D\u53EF\u7528\uFF09\u3002");
+    },
+    nativeFileApplications: async () => [],
+    openNativeFileApplication: async () => {
+      throw new FeatureError2("library/native-unavailable", "\u5F53\u524D\u73AF\u5883\u65E0\u6CD5\u8C03\u7528\u7CFB\u7EDF\u7A0B\u5E8F\u6253\u5F00\u6587\u4EF6\uFF08\u539F\u751F\u547D\u4EE4\u5C42\u4E0D\u53EF\u7528\uFF09\u3002");
+    }
+  };
+  return cached2;
+}
+async function openInSystemApp(absolutePath2, appId, ctx) {
+  if (typeof absolutePath2 !== "string" || !absolutePath2.startsWith("/")) {
+    throw new FeatureError2("library/invalid-request", "\u9700\u8981\u4E00\u4E2A\u672C\u673A\u7EDD\u5BF9\u8DEF\u5F84\u3002");
+  }
+  const signal = new AbortController().signal;
+  const native = await loadNativeCommand();
+  try {
+    if (typeof appId === "string" && appId.length > 0) {
+      if (typeof native.openNativeFileApplication !== "function") {
+        throw new FeatureError2("library/native-unavailable", "\u5F53\u524D\u539F\u751F\u547D\u4EE4\u5C42\u4E0D\u652F\u6301\u6307\u5B9A\u7A0B\u5E8F\u6253\u5F00\u3002");
+      }
+      await native.openNativeFileApplication(absolutePath2, appId, signal);
+      return { opened: true, appId };
+    }
+    await native.openNativeAssociatedPath(absolutePath2, signal);
+    return { opened: true, appId: void 0 };
+  } catch (error) {
+    if (error instanceof FeatureError2) throw error;
+    ctx?.logger?.warn?.(`dsh-plugin-library: \u7CFB\u7EDF\u6253\u5F00\u5931\u8D25 ${absolutePath2}\uFF08${appId ?? "\u9ED8\u8BA4"}\uFF09\uFF1A${String(error?.message ?? error)}`);
+    throw new FeatureError2("library/open-failed", `\u6CA1\u6709\u6253\u5F00\u6210\u529F\uFF1A${String(error?.message ?? error)}`);
+  }
+}
+async function fileApplications(absolutePath2) {
+  if (typeof absolutePath2 !== "string" || !absolutePath2.startsWith("/")) return [];
+  const signal = new AbortController().signal;
+  const native = await loadNativeCommand();
+  if (typeof native.nativeFileApplications !== "function") return [];
+  const rows = await native.nativeFileApplications(absolutePath2, signal);
+  return Array.isArray(rows) ? rows : [];
+}
+
+// src/manager.js
+var MAX_BYTES = 50 * 1024 * 1024;
+var MAX_TOTAL_BYTES = 5 * 1024 * 1024 * 1024;
+var MAX_HITS = 50;
+var NAME_ATTEMPTS = 5;
+var DRAFT_TTL_MS = 7 * 24 * 60 * 60 * 1e3;
+var EDITABLE_KINDS = /* @__PURE__ */ new Set(["markdown", "text"]);
+var FS_CODES = {
+  FS_NOT_FOUND: "library/not-found",
+  FS_NOT_REGULAR_FILE: "library/not-a-file",
+  FS_TOO_LARGE: "library/file-size",
+  FS_SANDBOX_DENIED: "library/read-denied",
+  FS_ABORTED: "library/aborted",
+  FS_IO_ERROR: "library/read-failed"
+};
+function sha256Hex(bytes) {
+  return createHash("sha256").update(bytes).digest("hex");
+}
+function requireString(value, field) {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new FeatureError2("library/invalid-request", `\u7F3A\u5C11\u5B57\u6BB5 ${field}\u3002`);
+  }
+  return value;
+}
+function optionalId(value) {
+  return typeof value === "string" && value.length > 0 ? value : void 0;
+}
+function cleanName(value) {
+  const name2 = typeof value === "string" ? value.trim() : "";
+  if (name2.length === 0 || name2.length > 256 || name2 === "." || name2 === ".." || /[/\\\u0000-\u001f]/.test(name2)) {
+    throw new FeatureError2("library/invalid-name", "\u540D\u79F0\u9700\u8981 1\u2013256 \u4E2A\u5B57\u7B26\uFF0C\u4E14\u4E0D\u80FD\u5305\u542B\u8DEF\u5F84\u5206\u9694\u7B26\u3002");
+  }
+  return name2;
+}
+function cleanCreateName(value) {
+  const name2 = cleanName(value);
+  if (name2.includes("..")) {
+    throw new FeatureError2("library/invalid-name", '\u540D\u79F0\u4E0D\u80FD\u5305\u542B\u8DEF\u5F84\u5206\u9694\u7B26\u3001\u63A7\u5236\u5B57\u7B26\u6216 ".."\u3002');
+  }
+  return name2;
+}
+function requireContent(value) {
+  if (typeof value !== "string") {
+    throw new FeatureError2("library/invalid-request", "\u7F3A\u5C11\u5B57\u6BB5 content\u3002");
+  }
+  return value;
+}
+function emptyState() {
+  return { schemaVersion: 1, nodes: {}, assets: {}, revisions: {}, drafts: {} };
+}
+function draftsOf(state) {
+  const drafts = state?.drafts;
+  return drafts !== null && typeof drafts === "object" ? drafts : {};
+}
+function sweepDrafts(state) {
+  const drafts = draftsOf(state);
+  const keys = Object.keys(drafts);
+  if (keys.length === 0) return state;
+  const cutoff = Date.now() - DRAFT_TTL_MS;
+  const kept = {};
+  for (const key of keys) {
+    const stamp = Date.parse(drafts[key]?.updatedAt ?? "");
+    if (Number.isFinite(stamp) && stamp >= cutoff) kept[key] = drafts[key];
+  }
+  if (Object.keys(kept).length === keys.length) return state;
+  return { ...state, drafts: kept };
+}
+var LibraryManager = class {
+  /**
+   * @param {import('@deepseek-ai/cordis').Context} ctx - Host context.
+   * @param {{ libraryDomain: object }} domains - built spec.
+   * @param {{ root?: string, maxBytes?: number, maxTotalBytes?: number }} [options] - overrides, used by tests.
+   */
+  constructor(ctx, domains, options = {}) {
+    this.ctx = ctx;
+    this.domains = domains;
+    const home = options.home ?? process.env.DSH_HOME ?? join2(homedir(), ".dsh");
+    this.root = resolve2(options.root ?? join2(home, "dsh-skills-library"));
+    this.maxBytes = options.maxBytes ?? MAX_BYTES;
+    this.maxTotalBytes = options.maxTotalBytes ?? MAX_TOTAL_BYTES;
+    this.table = void 0;
+    this.serial = Promise.resolve();
+  }
+  /** Open the domain. Creates nothing on disk. */
+  async init() {
+    const domain = await this.ctx.storageDomain.open(this.domains.libraryDomain);
+    this.ctx.effect(() => () => domain.close(), "dsh-plugin-library: domain");
+    this.table = domain.table("states");
+  }
+  // ---- read surface --------------------------------------------------------
+  /** Root, limits and live usage; the panel's header data. */
+  overview() {
+    const state = this.load();
+    const revisions = Object.values(state.revisions);
+    return {
+      root: this.root,
+      limits: { maxBytes: this.maxBytes, maxTotalBytes: this.maxTotalBytes },
+      usage: {
+        bytes: revisions.reduce((total, row) => total + (row.originalByteLength ?? 0), 0),
+        revisions: revisions.length,
+        assets: Object.values(state.assets).filter((row) => row.removedAt === void 0).length,
+        folders: Object.values(state.nodes).filter((row) => row.kind === "folder" && row.removedAt === void 0).length
+      }
+    };
+  }
+  /** Every live node, folders first within each parent, for the client to nest. */
+  tree() {
+    const state = this.load();
+    return Object.values(state.nodes).filter((node) => node.removedAt === void 0).map((node) => this.entry(state, node)).sort((a, b) => {
+      if (a.kind !== b.kind) return a.kind === "folder" ? -1 : 1;
+      return a.name.localeCompare(b.name, "zh-CN");
+    });
+  }
+  /** One asset with its full immutable revision history, newest first. */
+  assetDetail(assetId) {
+    const state = this.load();
+    const node = this.requireLiveNode(state, assetId);
+    this.requireAsset(state, assetId);
+    const view = this.entry(state, node);
+    const revisions = Object.values(state.revisions).filter((row) => row.assetId === assetId).sort((a, b) => b.number - a.number);
+    return { node: view, asset: view.asset, revisions, folderPath: this.folderPath(state, node.parentId) };
+  }
+  /**
+   * Search derived text.
+   *
+   * Non-`ready` revisions are listed by name (so an unconvertible file is visible)
+   * but are never text-matched, and a disabled or removed asset never appears.
+   * @param {string} query - keyword; empty returns everything active.
+   * @param {string} [kind] - optional asset kind filter.
+   * @returns {Promise<object[]>} up to {@link MAX_HITS} hits, best first.
+   */
+  async search(query, kind) {
+    const needle = String(query ?? "").trim().toLocaleLowerCase();
+    const state = this.load();
+    const hits = [];
+    for (const asset of Object.values(state.assets)) {
+      if (asset.status !== "active" || asset.removedAt !== void 0) continue;
+      const node = state.nodes[asset.id];
+      if (node === void 0 || node.removedAt !== void 0) continue;
+      if (kind !== void 0 && asset.kind !== kind) continue;
+      const revision = state.revisions[`${asset.id}:${asset.currentRevisionId}`];
+      if (revision === void 0) continue;
+      const titleMatch = needle.length > 0 && node.name.toLocaleLowerCase().includes(needle);
+      let excerpt = "";
+      let score = 0;
+      if (revision.conversionStatus === "ready" && needle.length > 0) {
+        const text = await this.readContent(revision);
+        const offset = text.toLocaleLowerCase().indexOf(needle);
+        if (!titleMatch && offset < 0) continue;
+        const start = Math.max(0, offset < 0 ? 0 : offset - 80);
+        excerpt = text.slice(start, start + 240).replace(/\s+/g, " ").trim();
+        score = titleMatch ? 2 : 1;
+      } else if (revision.conversionStatus !== "ready" && needle.length > 0) {
+        if (!titleMatch) continue;
+        score = 1;
+      }
+      hits.push({
+        assetId: asset.id,
+        nodeId: node.id,
+        revisionId: revision.id,
+        revisionNumber: revision.number,
+        name: node.name,
+        kind: asset.kind,
+        folderPath: this.folderPath(state, node.parentId),
+        conversionStatus: revision.conversionStatus,
+        byteLength: asset.byteLength,
+        updatedAt: asset.updatedAt,
+        excerpt,
+        score
+      });
+    }
+    return hits.sort((a, b) => b.score - a.score || b.updatedAt.localeCompare(a.updatedAt) || a.name.localeCompare(b.name, "zh-CN")).slice(0, MAX_HITS);
+  }
+  /**
+   * Read the derived searchable text of one revision.
+   * @param {string} assetId - the asset.
+   * @param {string} [revisionId] - a pinned revision; defaults to the current one.
+   * @returns {Promise<string>} the derived text.
+   */
+  async readText(assetId, revisionId) {
+    const { revision } = this.resolveReadable(assetId, revisionId);
+    return this.readContent(revision);
+  }
+  /**
+   * Read the original bytes of one revision.
+   *
+   * This is the one read that does not need a derived text view: an asset with
+   * `unavailable` or `failed` conversion can still hand back its exact bytes. A
+   * *disabled* asset is still refused, because disable is meant to stop history
+   * references from resolving at all.
+   * @param {string} assetId - the asset.
+   * @param {string} [revisionId] - a pinned revision; defaults to the current one.
+   * @returns {Promise<Uint8Array>} the exact stored bytes.
+   */
+  async readOriginal(assetId, revisionId) {
+    const { revision } = this.resolveStored(assetId, revisionId);
+    return new Uint8Array(await readFile(this.safePath(revision.originalRelativePath)));
+  }
+  /**
+   * The on-disk facts about one revision's original: where it lives and whether
+   * the bytes there still hash to the stored revision id.
+   *
+   * The client uses this to offer 「用系统程序打开」 a file the OS can edit, and
+   * then to notice — by the digest changing — that the user has saved a new
+   * version outside, so 「导入新版本」 can be offered against real evidence
+   * rather than a guess.
+   * @param {string} assetId - the asset.
+   * @param {string} [revisionId] - a pinned revision; defaults to the current one.
+   * @returns {Promise<{ absolutePath: string, exists: boolean, matchesRevision: boolean }>} the disk facts.
+   */
+  async originalPath(assetId, revisionId) {
+    const { revision } = this.resolveStored(assetId, revisionId);
+    const absolutePath2 = this.safePath(revision.originalRelativePath);
+    let bytes;
+    try {
+      bytes = await readFile(absolutePath2);
+    } catch {
+      return { absolutePath: absolutePath2, exists: false, matchesRevision: false };
+    }
+    return { absolutePath: absolutePath2, exists: true, matchesRevision: sha256Hex(bytes) === revision.id };
+  }
+  /**
+   * Hand one revision's original to the OS-associated application (WPS,
+   * PowerPoint, Preview …). The save afterwards writes the disk file directly;
+   * the library learns about the edit only when 「导入新版本」 is invoked.
+   * @param {string} assetId - the asset.
+   * @param {string} [revisionId] - a pinned revision; defaults to the current one.
+   * @returns {Promise<{ opened: true, absolutePath: string }>} the receipt with the opened path.
+   */
+  async openInSystemApp(assetId, revisionId, open, appId = void 0) {
+    const { revision } = this.resolveStored(assetId, revisionId);
+    const absolutePath2 = this.safePath(revision.originalRelativePath);
+    await open(absolutePath2, appId);
+    return { opened: true, absolutePath: absolutePath2, ...appId !== void 0 ? { appId } : {} };
+  }
+  /**
+   * Re-read the on-disk original and file it as a new revision when its bytes
+   * differ from the stored ones. Content addressing decides: identical bytes
+   * reuse the existing revision (`reused: true`), changed bytes append a new
+   * one, and the previous revisions stay readable.
+   * @param {string} assetId - the asset whose original was edited outside.
+   * @returns {Promise<object>} the entry from `storeBytes`, with `reused` set.
+   */
+  async importExternalChanges(assetId) {
+    return this.enqueue(async () => {
+      const state = this.load();
+      const node = this.requireLiveNode(state, assetId);
+      if (node.kind !== "asset") {
+        throw new FeatureError2("library/not-an-asset", "\u8BE5\u8282\u70B9\u4E0D\u662F\u8D44\u6599\u3002");
+      }
+      const asset = state.assets[assetId];
+      const revision = state.revisions[`${assetId}:${asset.currentRevisionId}`];
+      const absolutePath2 = this.safePath(revision.originalRelativePath);
+      let bytes;
+      try {
+        bytes = await readFile(absolutePath2);
+      } catch {
+        throw new FeatureError2("library/not-found", `\u539F\u4EF6\u4E0D\u5728\u78C1\u76D8\u4E0A\uFF08${absolutePath2}\uFF09\uFF0C\u65E0\u6CD5\u5BFC\u5165\u5916\u90E8\u4FEE\u6539\u3002`);
+      }
+      this.assertFolder(state, node.parentId);
+      const name2 = node.name;
+      return this.storeBytes({ name: name2, parentId: node.parentId, bytes, source: asset.source ?? "import" });
+    });
+  }
+  // ---- write surface -------------------------------------------------------
+  /** Create one folder. */
+  createFolder(input) {
+    return this.enqueue(async () => {
+      const name2 = cleanName(input?.name);
+      const parentId = optionalId(input?.parentId);
+      const state = this.load();
+      this.assertFolder(state, parentId);
+      this.assertUniqueName(state, parentId, name2);
+      const now = (/* @__PURE__ */ new Date()).toISOString();
+      const node = {
+        id: randomUUID(),
+        kind: "folder",
+        name: name2,
+        ...parentId !== void 0 ? { parentId } : {},
+        createdAt: now,
+        updatedAt: now
+      };
+      await this.put({ ...state, nodes: { ...state.nodes, [node.id]: node } });
+      return node;
+    });
+  }
+  /**
+   * Import a file from an absolute path, reading it through `ctx.fs`.
+   *
+   * The asset is identified by `(parentId, name)`: importing a changed file under
+   * the same name appends a revision to that asset rather than creating a second
+   * node, which is what makes "re-import" mean "new revision".
+   * @param {{ path: string, parentId?: string, name?: string }} input - the import request.
+   * @returns {Promise<object>} the resulting tree entry.
+   */
+  async importFromPath(input) {
+    const sourcePath = requireString(input?.path, "path");
+    const fs = this.fs();
+    let target;
+    try {
+      target = await fs.resolve(sourcePath);
+    } catch (error) {
+      throw this.fsFailure(error);
+    }
+    const info = await Promise.resolve(fs.stat(target)).catch((error) => {
+      throw this.fsFailure(error);
+    });
+    if (info === void 0) throw new FeatureError2("library/not-found", "\u627E\u4E0D\u5230\u8981\u5BFC\u5165\u7684\u6587\u4EF6\u3002");
+    if (info.type !== "file") throw new FeatureError2("library/not-a-file", "\u53EA\u80FD\u5BFC\u5165\u666E\u901A\u6587\u4EF6\uFF0C\u4E0D\u80FD\u5BFC\u5165\u76EE\u5F55\u3002");
+    const name2 = cleanName(input?.name ?? basename(target.displayPath ?? sourcePath));
+    if (typeof info.size === "number" && info.size > this.maxBytes) {
+      throw new FeatureError2("library/file-size", `\u6587\u4EF6\u8D85\u8FC7\u5355\u4E2A\u6587\u4EF6\u4E0A\u9650 ${this.maxBytes} \u5B57\u8282\u3002`);
+    }
+    let bytes;
+    try {
+      bytes = await fs.readBytes(target, void 0, this.maxBytes);
+    } catch (error) {
+      throw this.fsFailure(error);
+    }
+    return this.importBytes({ name: name2, parentId: optionalId(input?.parentId), bytes, source: "import" });
+  }
+  /**
+   * Store one buffer as an immutable revision of `(parentId, name)`.
+   *
+   * Identical bytes reuse the existing revision — same id, same number, no
+   * second directory — which is the content-addressing contract. A disabled asset
+   * accepts a re-import and becomes the current revision again, but stays disabled.
+   * @param {{ name: string, parentId?: string, bytes: Uint8Array, source?: string }} input - the payload.
+   * @returns {Promise<object>} the resulting tree entry, with `reused` set.
+   */
+  importBytes(input) {
+    return this.enqueue(() => this.storeBytes(input));
+  }
+  /**
+   * Store one delivered file as `source: 'task'` — a 本地产物.
+   *
+   * The ingest path behind automatic deliverable attribution. It is **not** a
+   * second implementation: the bytes go through the same {@link storeBytes} the
+   * `import` endpoint uses, so hashing, the `objects/<assetId>/<revisionId>/`
+   * layout, `revision.json`, the derived `content.md` and every read behave
+   * identically.
+   *
+   * Two things make it a distinct entry point rather than a call to
+   * {@link importFromPath}:
+   *
+   *   1. `source` is `'task'` and the producing session is recorded as
+   *      `sourceTaskId`, which is what the panel's 本地产物 filter matches on.
+   *      `import` deliberately keeps `source: 'import'`.
+   *   2. A name collision does **not** mean "same asset, new revision". Two
+   *      different deliverables called `report.md` are two different files;
+   *      folding them into one asset would make one overwrite the other's body.
+   *      So the name is advanced to `report (2).md`, `report (3).md` … up to
+   *      {@link NAME_ATTEMPTS}, and a refusal is the honest outcome after that.
+   *
+   * Re-delivering *the same bytes* for the *same task* is idempotent: the bytes
+   * hash to the same revision id, so the existing `source: 'task'` asset is
+   * reused and `reused` comes back `true` instead of minting `report (2).md`.
+   *
+   * @param {{ path: string, name?: string, parentId?: string, sourceTaskId?: string }} input - the request.
+   * @returns {Promise<object>} the resulting tree entry, with `reused` set.
+   */
+  async importTaskFile(input) {
+    const sourcePath = requireString(input?.path, "path");
+    const fs = this.fs();
+    let target;
+    try {
+      target = await fs.resolve(sourcePath);
+    } catch (error) {
+      throw this.fsFailure(error);
+    }
+    const info = await Promise.resolve(fs.stat(target)).catch((error) => {
+      throw this.fsFailure(error);
+    });
+    if (info === void 0) throw new FeatureError2("library/not-found", "\u627E\u4E0D\u5230\u8981\u5BFC\u5165\u7684\u6587\u4EF6\u3002");
+    if (info.type !== "file") throw new FeatureError2("library/not-a-file", "\u53EA\u80FD\u5BFC\u5165\u666E\u901A\u6587\u4EF6\uFF0C\u4E0D\u80FD\u5BFC\u5165\u76EE\u5F55\u3002");
+    if (typeof info.size === "number" && info.size > this.maxBytes) {
+      throw new FeatureError2("library/file-size", `\u6587\u4EF6\u8D85\u8FC7\u5355\u4E2A\u6587\u4EF6\u4E0A\u9650 ${this.maxBytes} \u5B57\u8282\u3002`);
+    }
+    let bytes;
+    try {
+      bytes = await fs.readBytes(target, void 0, this.maxBytes);
+    } catch (error) {
+      throw this.fsFailure(error);
+    }
+    const baseName = cleanName(input?.name ?? basename(target.displayPath ?? sourcePath));
+    const parentId = optionalId(input?.parentId);
+    const sourceTaskId = optionalId(input?.sourceTaskId);
+    return this.enqueue(async () => {
+      const state = this.load();
+      this.assertFolder(state, parentId);
+      const revisionId = sha256Hex(bytes);
+      if (sourceTaskId !== void 0) {
+        const reused = Object.values(state.assets).find((asset) => asset.removedAt === void 0 && asset.source === "task" && asset.sourceTaskId === sourceTaskId && asset.currentRevisionId === revisionId);
+        if (reused !== void 0 && state.nodes[reused.id]?.removedAt === void 0) {
+          return { ...this.entry(state, state.nodes[reused.id]), reused: true };
+        }
+      }
+      const name2 = this.freeName(state, parentId, baseName);
+      return this.storeBytes({ name: name2, parentId, bytes, source: "task", sourceTaskId });
+    });
+  }
+  /**
+   * A sibling-free name for one import, or a refusal after {@link NAME_ATTEMPTS}.
+   *
+   * Runs inside a serialized task, so the name it returns is still free when
+   * {@link storeBytes} writes it.
+   * @param {object} state - the current state record.
+   * @param {string|undefined} parentId - the destination folder.
+   * @param {string} baseName - the name to start from.
+   * @returns {string} `baseName`, or `name (2)` … up to the attempt ceiling.
+   */
+  freeName(state, parentId, baseName) {
+    const taken = new Set(Object.values(state.nodes).filter((node) => node.removedAt === void 0 && node.parentId === parentId).map((node) => node.name.toLocaleLowerCase()));
+    if (!taken.has(baseName.toLocaleLowerCase())) return baseName;
+    const extension = extname2(baseName);
+    const stem = extension.length > 0 ? baseName.slice(0, -extension.length) : baseName;
+    for (let attempt = 2; attempt <= NAME_ATTEMPTS; attempt++) {
+      const candidate = `${stem} (${attempt})${extension}`;
+      if (!taken.has(candidate.toLocaleLowerCase())) return candidate;
+    }
+    throw new FeatureError2("library/name-conflict", `\u540C\u540D\u8D44\u6599\u5DF2\u6709 ${NAME_ATTEMPTS} \u4EFD\uFF0C\u65E0\u6CD5\u518D\u81EA\u52A8\u5165\u5E93\u3002`);
+  }
+  /**
+   * This is the panel's "new document" path and the only write that originates
+   * in the browser, but it is **not** a second ingest implementation: the
+   * content becomes the asset's first revision through the same
+   * {@link storeBytes} the `import` endpoint uses, so hashing, the
+   * `objects/<assetId>/<revisionId>/` layout, the derived `content.md`, the
+   * conversion status and every read (`tree` / `search` / `read-text` /
+   * `read-original`) behave identically.
+   *
+   * What deliberately differs from `import`: identity. An import addressed by
+   * `(parentId, name)` appends a revision to an existing asset, while a create
+   * refuses an existing name with the same `library/name-conflict` rule
+   * `create-folder` uses — "new document" must never silently replace the body
+   * of a document that already exists.
+   *
+   * The asset is recorded with `source: 'created'`, the panel's own label for
+   * it; the kind still comes from the name's extension exactly as an import's
+   * does (`kindForName`), so a `.md` / `.markdown` name is markdown and `.txt`
+   * is text.
+   *
+   * @param {{ name: string, content: string, parentId?: string }} input - the request.
+   * @returns {Promise<object>} the resulting tree entry, with `reused: false`.
+   */
+  createText(input) {
+    return this.enqueue(async () => {
+      const name2 = cleanCreateName(input?.name);
+      const parentId = optionalId(input?.parentId);
+      const content = requireContent(input?.content);
+      const state = this.load();
+      this.assertFolder(state, parentId);
+      this.assertUniqueName(state, parentId, name2);
+      const bytes = new TextEncoder().encode(content);
+      if (bytes.byteLength > this.maxBytes) {
+        throw new FeatureError2("library/file-size", `\u5185\u5BB9\u8D85\u8FC7\u5355\u4E2A\u6587\u4EF6\u4E0A\u9650 ${this.maxBytes} \u5B57\u8282\u3002`);
+      }
+      return this.storeBytes({ name: name2, parentId, bytes, source: "created" });
+    });
+  }
+  /**
+   * The shared ingest body behind `import`, `importFromPath` and `createText`.
+   *
+   * Runs inside {@link enqueue}: callers are already serialized, and it must not
+   * be called from inside another queued task (that would deadlock the chain).
+   * @param {{ name: string, parentId?: string, bytes: Uint8Array, source?: string }} input - the payload.
+   * @returns {Promise<object>} the resulting tree entry, with `reused` set.
+   */
+  async storeBytes(input) {
+    const name2 = cleanName(input?.name);
+    const parentId = optionalId(input?.parentId);
+    const bytes = input?.bytes;
+    if (!(bytes instanceof Uint8Array)) throw new FeatureError2("library/invalid-request", "\u7F3A\u5C11\u6587\u4EF6\u5185\u5BB9\u3002");
+    const state = this.load();
+    this.assertFolder(state, parentId);
+    const existing = Object.values(state.nodes).find((node2) => node2.kind === "asset" && node2.removedAt === void 0 && node2.parentId === parentId && node2.name.toLocaleLowerCase() === name2.toLocaleLowerCase());
+    const assetId = existing?.id ?? randomUUID();
+    const revisionId = sha256Hex(bytes);
+    const key = `${assetId}:${revisionId}`;
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const found = state.revisions[key];
+    if (found !== void 0) {
+      const asset2 = state.assets[assetId];
+      const nextAsset = { ...asset2, currentRevisionId: revisionId, updatedAt: now };
+      const nextNode2 = { ...existing, updatedAt: now };
+      await this.put({
+        ...state,
+        assets: { ...state.assets, [assetId]: nextAsset },
+        nodes: { ...state.nodes, [assetId]: nextNode2 }
+      });
+      return { ...this.entry({ ...state, assets: { ...state.assets, [assetId]: nextAsset } }, nextNode2), reused: true };
+    }
+    const used = Object.values(state.revisions).reduce((total, row) => total + (row.originalByteLength ?? 0), 0);
+    if (used + bytes.byteLength > this.maxTotalBytes) {
+      throw new FeatureError2("library/quota-exceeded", `\u8D44\u6599\u5E93\u539F\u4EF6\u603B\u91CF\u5C06\u8D85\u8FC7 ${this.maxTotalBytes} \u5B57\u8282\u4E0A\u9650\u3002`);
+    }
+    const kind = kindForName(name2);
+    const derived = deriveText(kind, bytes);
+    const extension = extname2(name2).toLowerCase() || ".bin";
+    const relativeBase = join2("objects", assetId, revisionId);
+    const originalRelativePath = join2(relativeBase, `original${extension}`);
+    const contentRelativePath = join2(relativeBase, "content.md");
+    const metadataRelativePath = join2(relativeBase, "revision.json");
+    const number = Object.values(state.revisions).filter((row) => row.assetId === assetId).length + 1;
+    const revision = {
+      id: revisionId,
+      assetId,
+      number,
+      kind,
+      originalSha256: revisionId,
+      contentSha256: sha256Hex(new TextEncoder().encode(derived.text)),
+      originalByteLength: bytes.byteLength,
+      originalRelativePath,
+      contentRelativePath,
+      metadataRelativePath,
+      conversionStatus: derived.status,
+      conversionWarnings: [...derived.warnings],
+      createdAt: now
+    };
+    await this.writeObject({
+      directory: this.safePath(relativeBase),
+      entries: [
+        { relativePath: originalRelativePath, data: bytes },
+        { relativePath: contentRelativePath, data: derived.text },
+        {
+          relativePath: metadataRelativePath,
+          data: `${JSON.stringify({
+            schemaVersion: 1,
+            assetId,
+            revisionId,
+            kind,
+            originalSha256: revisionId,
+            originalByteLength: bytes.byteLength,
+            conversionStatus: derived.status,
+            conversionWarnings: derived.warnings,
+            createdAt: now
+          }, null, 2)}
+`
+        }
+      ]
+    });
+    const node = existing ?? {
+      id: assetId,
+      kind: "asset",
+      name: name2,
+      ...parentId !== void 0 ? { parentId } : {},
+      createdAt: now,
+      updatedAt: now
+    };
+    const asset = {
+      id: assetId,
+      kind,
+      mediaType: mediaTypeForKind(kind),
+      byteLength: bytes.byteLength,
+      status: existing !== void 0 ? state.assets[assetId]?.status ?? "active" : "active",
+      currentRevisionId: revisionId,
+      source: typeof input?.source === "string" ? input.source : "import",
+      ...typeof input?.sourceTaskId === "string" && input.sourceTaskId.length > 0 ? { sourceTaskId: input.sourceTaskId } : {},
+      createdAt: existing !== void 0 ? state.assets[assetId]?.createdAt ?? now : now,
+      updatedAt: now
+    };
+    const nextNode = { ...node, updatedAt: now };
+    const nextState = {
+      ...state,
+      nodes: { ...state.nodes, [assetId]: nextNode },
+      assets: { ...state.assets, [assetId]: asset },
+      revisions: { ...state.revisions, [key]: revision }
+    };
+    await this.put(nextState);
+    return { ...this.entry(nextState, nextNode), reused: false };
+  }
+  /** Rename one folder or asset node. */
+  rename(nodeId, name2) {
+    return this.enqueue(async () => {
+      const state = this.load();
+      const node = this.requireLiveNode(state, nodeId);
+      const next = cleanName(name2);
+      this.assertUniqueName(state, node.parentId, next, node.id);
+      const updated = { ...node, name: next, updatedAt: (/* @__PURE__ */ new Date()).toISOString() };
+      await this.put({ ...state, nodes: { ...state.nodes, [nodeId]: updated } });
+      return this.entry({ ...state, nodes: { ...state.nodes, [nodeId]: updated } }, updated);
+    });
+  }
+  /** Move one folder or asset node to another folder (or the root). */
+  move(nodeId, parentIdInput) {
+    return this.enqueue(async () => {
+      const parentId = optionalId(parentIdInput);
+      const state = this.load();
+      const node = this.requireLiveNode(state, nodeId);
+      this.assertFolder(state, parentId);
+      if (parentId === nodeId || parentId !== void 0 && this.descendants(state, nodeId).has(parentId)) {
+        throw new FeatureError2("library/cycle", "\u6587\u4EF6\u5939\u4E0D\u80FD\u79FB\u52A8\u5230\u5B83\u81EA\u5DF1\u7684\u5B50\u76EE\u5F55\u91CC\u3002");
+      }
+      this.assertUniqueName(state, parentId, node.name, node.id);
+      const moved = { ...node, parentId, updatedAt: (/* @__PURE__ */ new Date()).toISOString() };
+      if (moved.parentId === void 0) delete moved.parentId;
+      await this.put({ ...state, nodes: { ...state.nodes, [nodeId]: moved } });
+      return this.entry({ ...state, nodes: { ...state.nodes, [nodeId]: moved } }, moved);
+    });
+  }
+  /**
+   * Soft-remove a node and its subtree.
+   *
+   * Bytes and revision records are kept: "remove" hides the entry from the tree
+   * and from every read, it never deletes the immutable originals. This is what
+   * makes the operation safe to offer without a second confirmation step.
+   */
+  remove(nodeId) {
+    return this.enqueue(async () => {
+      const state = this.load();
+      this.requireLiveNode(state, nodeId);
+      const ids = /* @__PURE__ */ new Set([nodeId, ...this.descendants(state, nodeId)]);
+      const now = (/* @__PURE__ */ new Date()).toISOString();
+      const nodes = { ...state.nodes };
+      const assets = { ...state.assets };
+      for (const id of ids) {
+        nodes[id] = { ...nodes[id], removedAt: now, updatedAt: now };
+        if (assets[id] !== void 0) assets[id] = { ...assets[id], status: "removed", removedAt: now, updatedAt: now };
+      }
+      await this.put({ ...state, nodes, assets });
+      return { removed: true, nodes: ids.size };
+    });
+  }
+  /** Enable or disable one asset. A disabled asset stops resolving immediately. */
+  setEnabled(assetId, enabled) {
+    return this.enqueue(async () => {
+      if (typeof enabled !== "boolean") throw new FeatureError2("library/invalid-request", "enabled \u5FC5\u987B\u662F\u5E03\u5C14\u503C\u3002");
+      const state = this.load();
+      const node = this.requireLiveNode(state, assetId);
+      if (node.kind !== "asset") throw new FeatureError2("library/not-an-asset", "\u53EA\u6709\u8D44\u6599\u53EF\u4EE5\u542F\u505C\u3002");
+      const asset = this.requireAsset(state, assetId);
+      const now = (/* @__PURE__ */ new Date()).toISOString();
+      const nextAsset = { ...asset, status: enabled ? "active" : "disabled", updatedAt: now };
+      const nextNode = { ...node, updatedAt: now };
+      const nextState = {
+        ...state,
+        assets: { ...state.assets, [assetId]: nextAsset },
+        nodes: { ...state.nodes, [assetId]: nextNode }
+      };
+      await this.put(nextState);
+      return this.entry(nextState, nextNode);
+    });
+  }
+  // ---- draft → publish -----------------------------------------------------
+  /**
+   * Open an editable draft over one revision's derived text.
+   *
+   * The port of upstream's `createDraft`. A draft is **working scratch, not a
+   * revision**: it lives in the state record, never in `objects/`, so the
+   * immutable store is untouched until 发布新版本. Cancelling a draft is
+   * therefore a client-side `setDraft(undefined)` — there is nothing to undo,
+   * and an abandoned draft is swept by {@link DRAFT_TTL_MS}.
+   *
+   * A draft is identified by `(assetId, baseRevisionId)` and re-opening the same
+   * base returns the *same* draft with its edits intact, which is what makes
+   * 取消 → 编辑 behave. Opening against a different revision starts a fresh
+   * draft, because the text being edited is different text.
+   *
+   * @param {string} assetId - the asset to edit.
+   * @param {string} [revisionId] - the revision to base the draft on; defaults to the current one.
+   * @returns {Promise<{id: string, assetId: string, baseRevisionId: string, number: number, content: string, revision: string, createdAt: string, updatedAt: string}>} the draft.
+   */
+  createDraft(assetId, revisionId) {
+    return this.enqueue(async () => {
+      const state = this.load();
+      const { node, asset, revision } = this.resolveEditable(state, assetId, revisionId);
+      const drafts = draftsOf(state);
+      const existing = Object.values(drafts).find((row) => row.assetId === asset.id && row.baseRevisionId === revision.id);
+      if (existing !== void 0) return { ...existing };
+      const now = (/* @__PURE__ */ new Date()).toISOString();
+      const draft = {
+        id: randomUUID(),
+        assetId: asset.id,
+        baseRevisionId: revision.id,
+        // The revision the panel was showing, so a publish can prove the view
+        // the user edited against is still the current one.
+        number: revision.number,
+        content: await this.readContent(revision),
+        revision: randomUUID(),
+        createdAt: now,
+        updatedAt: now
+      };
+      void node;
+      await this.put({ ...state, drafts: { ...drafts, [draft.id]: draft } });
+      return { ...draft };
+    });
+  }
+  /**
+   * Replace a draft's content under an optimistic revision check.
+   *
+   * `expectedRevision` is the draft token the client last read. A mismatch means
+   * another editor (or another tab) saved in between, and the write is refused
+   * rather than applied, so neither editor's text is silently overwritten.
+   * @param {string} draftId - the draft.
+   * @param {string} content - the complete replacement text.
+   * @param {string} expectedRevision - the draft token the client holds.
+   * @returns {Promise<object>} the updated draft.
+   */
+  updateDraft(draftId, content, expectedRevision) {
+    return this.enqueue(async () => {
+      const id = requireString(draftId, "draftId");
+      const expected = requireString(expectedRevision, "expectedRevision");
+      const text = requireContent(content);
+      const state = this.load();
+      const draft = this.requireDraft(state, id);
+      if (draft.revision !== expected) throw this.staleDraft();
+      const bytes = new TextEncoder().encode(text);
+      if (bytes.byteLength > this.maxBytes) {
+        throw new FeatureError2("library/file-size", `\u5185\u5BB9\u8D85\u8FC7\u5355\u4E2A\u6587\u4EF6\u4E0A\u9650 ${this.maxBytes} \u5B57\u8282\u3002`);
+      }
+      const next = { ...draft, content: text, revision: randomUUID(), updatedAt: (/* @__PURE__ */ new Date()).toISOString() };
+      await this.put({ ...state, drafts: { ...draftsOf(state), [id]: next } });
+      return { ...next };
+    });
+  }
+  /**
+   * Publish a draft as a **new immutable revision** of its asset.
+   *
+   * The commit step, and deliberately not a second ingest implementation: the
+   * draft text becomes UTF-8 bytes and goes through {@link storeBytes} — the same
+   * body `import` and `create-text` use — so hashing, the
+   * `objects/<assetId>/<revisionId>/` layout, `revision.json`, the derived
+   * `content.md` and every existing read behave identically. Nothing here
+   * rewrites `objects/`: publishing *appends*, and the base revision stays
+   * readable byte for byte.
+   *
+   * Two guards run before the write:
+   *
+   *   1. `expectedRevision` must match the draft token, or the *text* being
+   *      committed is not the text the user saw — refused, not applied.
+   *   2. the asset's current revision must still be the draft's base. If someone
+   *      re-imported or published in between, the draft was written against a
+   *      body that is no longer current, and committing it would drop that change.
+   *
+   * A publish that stores bytes identical to the base revision reuses that
+   * revision (content addressing) and the asset simply points at it again, so
+   * 发布新版本 with no edits is harmless.
+   *
+   * @param {string} draftId - the draft.
+   * @param {string} expectedRevision - the draft token the client holds.
+   * @returns {Promise<object>} the resulting tree entry, `reused` included.
+   */
+  publishDraft(draftId, expectedRevision) {
+    return this.enqueue(async () => {
+      const id = requireString(draftId, "draftId");
+      const expected = requireString(expectedRevision, "expectedRevision");
+      const state = this.load();
+      const draft = this.requireDraft(state, id);
+      if (draft.revision !== expected) throw this.staleDraft();
+      const node = this.requireLiveNode(state, draft.assetId);
+      if (node.kind !== "asset") throw new FeatureError2("library/not-an-asset", "\u8349\u7A3F\u5BF9\u5E94\u7684\u8282\u70B9\u4E0D\u662F\u8D44\u6599\u3002");
+      const asset = this.requireAsset(state, draft.assetId);
+      if (asset.status === "disabled") {
+        throw new FeatureError2("library/disabled", "\u8D44\u6599\u5DF2\u505C\u7528\uFF0C\u65E0\u6CD5\u53D1\u5E03\u8349\u7A3F\uFF1B\u91CD\u65B0\u542F\u7528\u540E\u518D\u8BD5\u3002");
+      }
+      if (!EDITABLE_KINDS.has(asset.kind)) {
+        throw new FeatureError2("library/not-editable", "\u53EA\u6709 Markdown \u548C\u7EAF\u6587\u672C\u8D44\u6599\u53EF\u4EE5\u7F16\u8F91\u5E76\u53D1\u5E03\u65B0\u7248\u672C\u3002");
+      }
+      if (asset.currentRevisionId !== draft.baseRevisionId) {
+        throw new FeatureError2("library/draft-conflict", "\u8FD9\u4EFD\u8D44\u6599\u5DF2\u7ECF\u6709\u4E86\u66F4\u65B0\u7684\u4FEE\u8BA2\uFF0C\u8349\u7A3F\u57FA\u4E8E\u7684\u5185\u5BB9\u4E0D\u662F\u5F53\u524D\u7248\u672C\uFF1B\u8BF7\u91CD\u65B0\u6253\u5F00\u8349\u7A3F\u540E\u518D\u53D1\u5E03\u3002");
+      }
+      const bytes = new TextEncoder().encode(draft.content);
+      if (bytes.byteLength > this.maxBytes) {
+        throw new FeatureError2("library/file-size", `\u5185\u5BB9\u8D85\u8FC7\u5355\u4E2A\u6587\u4EF6\u4E0A\u9650 ${this.maxBytes} \u5B57\u8282\u3002`);
+      }
+      const entry = await this.storeBytes({
+        name: node.name,
+        parentId: node.parentId,
+        bytes,
+        source: asset.source
+      });
+      const drafts = { ...draftsOf(this.load()) };
+      delete drafts[id];
+      await this.put({ ...this.load(), drafts });
+      return entry;
+    });
+  }
+  /** The route dispatch table. */
+  handlers() {
+    return {
+      overview: () => this.overview(),
+      tree: () => this.tree(),
+      asset: (payload) => this.assetDetail(requireString(payload.assetId, "assetId")),
+      "create-folder": (payload) => this.createFolder({ name: payload.name, parentId: payload.parentId }),
+      "create-text": (payload) => this.createText({ name: payload.name, content: payload.content, parentId: payload.parentId }),
+      "import-task": (payload) => this.importTaskFile({
+        path: requireString(payload.path, "path"),
+        name: payload.name,
+        parentId: payload.parentId,
+        sourceTaskId: payload.sourceTaskId
+      }),
+      rename: (payload) => this.rename(requireString(payload.nodeId, "nodeId"), requireString(payload.name, "name")),
+      move: (payload) => this.move(requireString(payload.nodeId, "nodeId"), payload.parentId),
+      remove: (payload) => this.remove(requireString(payload.nodeId, "nodeId")),
+      "set-enabled": (payload) => this.setEnabled(requireString(payload.assetId, "assetId"), payload.enabled),
+      "create-draft": (payload) => this.createDraft(
+        requireString(payload.assetId, "assetId"),
+        optionalId(payload.revisionId)
+      ),
+      "update-draft": (payload) => this.updateDraft(
+        requireString(payload.draftId, "draftId"),
+        requireContent(payload.content),
+        requireString(payload.expectedRevision, "expectedRevision")
+      ),
+      "publish-draft": (payload) => this.publishDraft(
+        requireString(payload.draftId, "draftId"),
+        requireString(payload.expectedRevision, "expectedRevision")
+      ),
+      import: (payload) => this.importFromPath(payload),
+      "original-path": (payload) => this.originalPath(requireString(payload.assetId, "assetId"), optionalId(payload.revisionId)),
+      "open-in-system": async (payload) => this.openInSystemApp(
+        requireString(payload.assetId, "assetId"),
+        optionalId(payload.revisionId),
+        (absolutePath2, appId) => openInSystemApp(absolutePath2, appId, this.ctx),
+        typeof payload.appId === "string" && payload.appId.length > 0 ? payload.appId : void 0
+      ),
+      "file-applications": async (payload) => {
+        const { absolutePath: absolutePath2 } = await this.originalPath(requireString(payload.assetId, "assetId"), optionalId(payload.revisionId));
+        return { applications: await fileApplications(absolutePath2) };
+      },
+      "import-external": (payload) => this.importExternalChanges(requireString(payload.assetId, "assetId")),
+      search: (payload) => this.search(
+        typeof payload.query === "string" ? payload.query : "",
+        typeof payload.kind === "string" && payload.kind.length > 0 ? payload.kind : void 0
+      ),
+      "read-text": (payload) => this.readText(requireString(payload.assetId, "assetId"), optionalId(payload.revisionId)),
+      "read-original": async (payload) => {
+        const assetId = requireString(payload.assetId, "assetId");
+        const revisionId = optionalId(payload.revisionId);
+        const node = this.requireLiveNode(this.load(), assetId);
+        const bytes = await this.readOriginal(assetId, revisionId);
+        const asset = this.requireAsset(this.load(), assetId);
+        return {
+          name: node.name,
+          mediaType: asset.mediaType,
+          byteLength: bytes.byteLength,
+          base64: Buffer.from(bytes).toString("base64")
+        };
+      }
+    };
+  }
+  // ---- internals -----------------------------------------------------------
+  /** The current state record, or the empty state. */
+  load() {
+    if (this.table === void 0) throw new FeatureError2("library/not-ready", "\u8D44\u6599\u5E93\u5B58\u50A8\u5C1A\u672A\u5C31\u7EEA\u3002");
+    return this.table.get(LOCAL_PRINCIPAL) ?? emptyState();
+  }
+  /** Persist one state record, dropping drafts that have gone stale. */
+  async put(next) {
+    if (this.table === void 0) throw new FeatureError2("library/not-ready", "\u8D44\u6599\u5E93\u5B58\u50A8\u5C1A\u672A\u5C31\u7EEA\u3002");
+    await this.table.put(LOCAL_PRINCIPAL, sweepDrafts(next));
+  }
+  /** Serialize one mutation. */
+  enqueue(run) {
+    const queued = this.serial.then(run, run);
+    this.serial = queued.then(() => void 0, () => void 0);
+    return queued;
+  }
+  /** `ctx.fs` or a clear refusal; the real composition always provides it. */
+  fs() {
+    const fs = this.ctx.get?.("fs") ?? this.ctx.fs;
+    if (fs === void 0 || typeof fs.resolve !== "function") {
+      throw new FeatureError2("library/fs-unavailable", "\u6587\u4EF6\u7CFB\u7EDF\u670D\u52A1\u4E0D\u53EF\u7528\uFF0C\u65E0\u6CD5\u8BFB\u53D6\u5BFC\u5165\u6765\u6E90\u3002");
+    }
+    return fs;
+  }
+  /** Map an `fs` refusal onto the library's own vocabulary. */
+  fsFailure(error) {
+    if (error instanceof FeatureError2) return error;
+    const code = typeof error?.code === "string" ? error.code : void 0;
+    const mapped = code !== void 0 ? FS_CODES[code] : void 0;
+    if (mapped !== void 0) return new FeatureError2(mapped, String(error?.message ?? "\u8BFB\u53D6\u5931\u8D25\u3002"));
+    if (error?.name === "AbortError") return new FeatureError2("library/aborted", "\u5BFC\u5165\u5DF2\u53D6\u6D88\u3002");
+    return new FeatureError2("library/read-failed", `\u8BFB\u53D6\u6765\u6E90\u6587\u4EF6\u5931\u8D25\uFF1A${String(error?.message ?? error)}`);
+  }
+  /** The panel/tool view of one node, with its asset and current revision attached. */
+  entry(state, node) {
+    const asset = node.kind === "asset" ? state.assets[node.id] : void 0;
+    const revision = asset !== void 0 ? state.revisions[`${asset.id}:${asset.currentRevisionId}`] : void 0;
+    const draft = asset !== void 0 ? Object.values(draftsOf(state)).find((row) => row.assetId === asset.id) : void 0;
+    return {
+      id: node.id,
+      kind: node.kind,
+      name: node.name,
+      ...node.parentId !== void 0 ? { parentId: node.parentId } : {},
+      ...node.removedAt !== void 0 ? { removedAt: node.removedAt } : {},
+      createdAt: node.createdAt,
+      updatedAt: node.updatedAt,
+      ...asset !== void 0 ? {
+        asset: {
+          id: asset.id,
+          kind: asset.kind,
+          mediaType: asset.mediaType,
+          byteLength: asset.byteLength,
+          status: asset.status,
+          currentRevisionId: asset.currentRevisionId,
+          source: asset.source,
+          revisionCount: Object.values(state.revisions).filter((row) => row.assetId === asset.id).length,
+          createdAt: asset.createdAt,
+          updatedAt: asset.updatedAt
+        },
+        /**
+         * Whether this asset may be edited at all. The rule lives here, next to
+         * the refusals that enforce it, and the panel renders 编辑 from this
+         * rather than re-deriving it from `kind` and `status` — one source of
+         * truth for a condition two halves have to agree on.
+         */
+        editable: asset.status === "active" && EDITABLE_KINDS.has(asset.kind) && revision?.conversionStatus === "ready",
+        ...draft !== void 0 ? { draft: { id: draft.id, baseRevisionId: draft.baseRevisionId, updatedAt: draft.updatedAt } } : {}
+      } : {},
+      ...revision !== void 0 ? { revision } : {}
+    };
+  }
+  /** Resolve `(assetId, revisionId)` to a revision an edit may start from. */
+  resolveEditable(state, assetId, revisionId) {
+    const node = this.requireLiveNode(state, assetId);
+    if (node.kind !== "asset") throw new FeatureError2("library/not-an-asset", "\u53EA\u6709\u8D44\u6599\u53EF\u4EE5\u7F16\u8F91\u3002");
+    const asset = this.requireReadableAsset(state, assetId);
+    if (!EDITABLE_KINDS.has(asset.kind)) {
+      throw new FeatureError2("library/not-editable", "\u53EA\u6709 Markdown \u548C\u7EAF\u6587\u672C\u8D44\u6599\u53EF\u4EE5\u7F16\u8F91\uFF1B\u5176\u4ED6\u683C\u5F0F\u8BF7\u4E0B\u8F7D\u540E\u5728\u672C\u673A\u4FEE\u6539\u518D\u91CD\u65B0\u5BFC\u5165\u3002");
+    }
+    const revision = state.revisions[`${assetId}:${revisionId ?? asset.currentRevisionId}`];
+    if (revision === void 0) throw new FeatureError2("library/not-found", "\u627E\u4E0D\u5230\u8BE5\u4FEE\u8BA2\u3002");
+    if (revision.conversionStatus !== "ready") {
+      throw new FeatureError2("library/conversion-unavailable", "\u8BE5\u4FEE\u8BA2\u6CA1\u6709\u53EF\u7F16\u8F91\u7684\u6D3E\u751F\u6B63\u6587\u3002");
+    }
+    return { node, asset, revision };
+  }
+  /** One live draft, or a refusal that names the reason. */
+  requireDraft(state, draftId) {
+    const draft = draftsOf(state)[draftId];
+    if (draft === void 0) throw new FeatureError2("library/draft-not-found", "\u8349\u7A3F\u4E0D\u5B58\u5728\u6216\u5DF2\u8FC7\u671F\u3002");
+    return draft;
+  }
+  /**
+   * The refusal a stale draft token earns.
+   *
+   * One code and one sentence for every caller, so 取消/发布/再次编辑 all say the
+   * same thing and the panel can surface it verbatim.
+   */
+  staleDraft() {
+    return new FeatureError2("library/draft-conflict", "\u8349\u7A3F\u5DF2\u88AB\u66F4\u65B0\uFF0C\u8BF7\u5237\u65B0\u540E\u91CD\u8BD5\u3002");
+  }
+  /** Resolve `(assetId, revisionId)` to a readable revision, refusing anything inactive. */
+  resolveReadable(assetId, revisionId) {
+    const resolved = this.resolveStored(assetId, revisionId);
+    const { revision } = resolved;
+    if (revision.conversionStatus !== "ready") {
+      throw new FeatureError2(
+        "library/conversion-unavailable",
+        revision.conversionStatus === "failed" ? "\u8BE5\u4FEE\u8BA2\u7684\u6587\u672C\u8F6C\u6362\u5931\u8D25\uFF0C\u65E0\u6CD5\u8BFB\u53D6\u6B63\u6587\uFF1B\u539F\u4EF6\u4ECD\u53EF\u4E0B\u8F7D\u3002" : "\u8BE5\u683C\u5F0F\u6CA1\u6709\u6587\u672C\u8F6C\u6362\uFF0C\u53EA\u80FD\u8BFB\u53D6\u539F\u4EF6\u3002"
+      );
+    }
+    return resolved;
+  }
+  /** Resolve `(assetId, revisionId)` to an enabled revision, without a conversion requirement. */
+  resolveStored(assetId, revisionId) {
+    const state = this.load();
+    const node = this.requireLiveNode(state, assetId);
+    if (node.kind !== "asset") throw new FeatureError2("library/not-an-asset", "\u8BE5\u8282\u70B9\u4E0D\u662F\u8D44\u6599\u3002");
+    const asset = this.requireReadableAsset(state, assetId);
+    const revision = state.revisions[`${assetId}:${revisionId ?? asset.currentRevisionId}`];
+    if (revision === void 0) throw new FeatureError2("library/not-found", "\u627E\u4E0D\u5230\u8BE5\u4FEE\u8BA2\u3002");
+    return { state, node, asset, revision };
+  }
+  /** Read a derived-text file, guarded by `safePath`. */
+  readContent(revision) {
+    return readFile(this.safePath(revision.contentRelativePath), "utf8");
+  }
+  /**
+   * Write one revision directory atomically.
+   *
+   * Staged under `.tmp/<uuid>` and renamed into place, so a crash can never leave
+   * a half-written revision that a later read would treat as authoritative.
+   */
+  async writeObject({ directory, entries }) {
+    const staging = this.safePath(join2(".tmp", randomUUID()));
+    await mkdir(staging, { recursive: true, mode: 448 });
+    try {
+      for (const entry of entries) {
+        const target = this.safePath(entry.relativePath);
+        await writeFile(join2(staging, basename(target)), entry.data, { flag: "wx", mode: 384 });
+      }
+      await mkdir(dirname(directory), { recursive: true, mode: 448 });
+      await rename(staging, directory);
+    } catch (error) {
+      await rm(staging, { recursive: true, force: true });
+      throw error;
+    }
+  }
+  /**
+   * Resolve a library-relative path, refusing anything outside the root.
+   *
+   * Every disk access in this module goes through here. A corrupted or hostile
+   * state record therefore cannot make the library read or write outside its own
+   * directory, which is the whole reason the check exists.
+   * @param {string} relative - a path relative to the library root.
+   * @returns {string} the absolute path.
+   * @throws {FeatureError} `library/path-escape` when the target is outside the root.
+   */
+  safePath(relative) {
+    const target = resolve2(this.root, String(relative ?? ""));
+    if (target !== this.root && !target.startsWith(`${this.root}${sep}`)) {
+      throw new FeatureError2("library/path-escape", "\u5BF9\u8C61\u8DEF\u5F84\u8D85\u51FA\u8D44\u6599\u5E93\u6839\u76EE\u5F55\uFF0C\u5DF2\u62D2\u7EDD\u3002");
+    }
+    return target;
+  }
+  /** A node that is neither removed nor missing. */
+  requireLiveNode(state, id) {
+    const node = state.nodes[id];
+    if (node === void 0 || node.removedAt !== void 0) {
+      throw new FeatureError2("library/not-found", "\u8D44\u6599\u4E0D\u5B58\u5728\u6216\u5DF2\u79FB\u9664\u3002");
+    }
+    return node;
+  }
+  /** An asset record that has not been removed (disabled is allowed; reads check separately). */
+  requireAsset(state, assetId) {
+    const asset = state.assets[assetId];
+    if (asset === void 0) throw new FeatureError2("library/not-found", "\u8D44\u6599\u4E0D\u5B58\u5728\u3002");
+    if (asset.status === "removed") throw new FeatureError2("library/not-found", "\u8D44\u6599\u5DF2\u79FB\u9664\u3002");
+    return asset;
+  }
+  /** An asset record a read is allowed to resolve: present and enabled. */
+  requireReadableAsset(state, assetId) {
+    const asset = this.requireAsset(state, assetId);
+    if (asset.status === "disabled") {
+      throw new FeatureError2("library/disabled", "\u8D44\u6599\u5DF2\u505C\u7528\uFF0C\u8BFB\u53D6\u4E0E\u68C0\u7D22\u88AB\u963B\u65AD\uFF1B\u91CD\u65B0\u542F\u7528\u540E\u53EF\u7EE7\u7EED\u4F7F\u7528\u3002");
+    }
+    return asset;
+  }
+  /** A parent id must be a live folder when present. */
+  assertFolder(state, parentId) {
+    if (parentId === void 0) return;
+    const node = state.nodes[parentId];
+    if (node === void 0 || node.removedAt !== void 0) throw new FeatureError2("library/not-found", "\u76EE\u6807\u6587\u4EF6\u5939\u4E0D\u5B58\u5728\u3002");
+    if (node.kind !== "folder") throw new FeatureError2("library/not-folder", "\u76EE\u6807\u4E0D\u662F\u6587\u4EF6\u5939\u3002");
+  }
+  /** Two live siblings may not share a name (case-insensitively). */
+  assertUniqueName(state, parentId, name2, exceptId) {
+    const conflict = Object.values(state.nodes).some((node) => node.removedAt === void 0 && node.id !== exceptId && node.parentId === parentId && node.name.toLocaleLowerCase() === name2.toLocaleLowerCase());
+    if (conflict) throw new FeatureError2("library/name-conflict", "\u540C\u4E00\u76EE\u5F55\u4E0B\u5DF2\u6709\u540C\u540D\u9879\u76EE\u3002");
+  }
+  /** Every descendant id of one node. */
+  descendants(state, id) {
+    const result = /* @__PURE__ */ new Set();
+    const queue = [id];
+    while (queue.length > 0) {
+      const parent = queue.shift();
+      for (const node of Object.values(state.nodes)) {
+        if (node.parentId === parent && !result.has(node.id)) {
+          result.add(node.id);
+          queue.push(node.id);
+        }
+      }
+    }
+    return result;
+  }
+  /** Human breadcrumb for a folder id. */
+  folderPath(state, parentId) {
+    const parts = [];
+    const seen = /* @__PURE__ */ new Set();
+    let current = parentId;
+    while (current !== void 0 && !seen.has(current)) {
+      seen.add(current);
+      const node = state.nodes[current];
+      if (node === void 0) break;
+      parts.unshift(node.name);
+      current = node.parentId;
+    }
+    return parts.length > 0 ? `\u8D44\u6599\u5E93 / ${parts.join(" / ")}` : "\u8D44\u6599\u5E93";
+  }
+};
+
+// src/tools.js
+function compileValue(node) {
+  if (node === null || typeof node !== "object") throw new Error("dsh-plugin-library: schema node must be an object");
+  if (node.type === "object") {
+    const properties = {};
+    const required = [];
+    for (const [key, value] of Object.entries(node.properties ?? {})) {
+      if (value?.required === true) required.push(key);
+      properties[key] = compileValue(value);
+    }
+    return {
+      type: "object",
+      additionalProperties: node.additionalProperties === true,
+      properties,
+      ...required.length > 0 ? { required } : {},
+      ...node.description !== void 0 ? { description: node.description } : {}
+    };
+  }
+  if (node.type === "array") {
+    return {
+      type: "array",
+      ...node.items !== void 0 ? { items: compileValue(node.items) } : {},
+      ...node.description !== void 0 ? { description: node.description } : {}
+    };
+  }
+  return {
+    type: node.type,
+    ...node.description !== void 0 ? { description: node.description } : {},
+    ...node.enum !== void 0 ? { enum: [...node.enum] } : {}
+  };
+}
+function compileParameters(spec) {
+  const properties = {};
+  const required = [];
+  for (const [key, value] of Object.entries(spec ?? {})) {
+    if (value?.required === true) required.push(key);
+    properties[key] = compileValue(value);
+  }
+  return { type: "object", properties, ...required.length > 0 ? { required } : {} };
+}
+function fallbackDefineTool(options) {
+  return {
+    name: options.name,
+    description: options.description,
+    parameters: compileParameters(options.parameters),
+    output: { schema: compileValue(options.output.schema), render: options.output.render },
+    execute: options.execute
+  };
+}
+var cached3;
+async function loadDefineTool() {
+  if (cached3 !== void 0) return cached3;
+  try {
+    const mod = await importDshPackage("@deepseek-ai/dsh-tools");
+    if (typeof mod?.defineTool === "function") {
+      cached3 = mod.defineTool;
+      return cached3;
+    }
+  } catch {
+  }
+  cached3 = fallbackDefineTool;
+  return cached3;
+}
+function hitForModel(hit) {
+  return {
+    asset_id: hit.assetId,
+    revision_id: hit.revisionId,
+    revision_number: hit.revisionNumber,
+    name: hit.name,
+    kind: hit.kind,
+    folder_path: hit.folderPath,
+    conversion_status: hit.conversionStatus,
+    byte_length: hit.byteLength,
+    updated_at: hit.updatedAt,
+    excerpt: hit.excerpt
+  };
+}
+async function registerLibraryTools(ctx, manager) {
+  const defineTool = await loadDefineTool();
+  ctx.effect(() => ctx.tools.register(defineTool({
+    name: "library_search",
+    description: "\u641C\u7D22\u672C\u5730\u8D44\u6599\u5E93\u7684\u6D3E\u751F\u6B63\u6587\uFF0C\u8FD4\u56DE\u4E0D\u53EF\u53D8\u7684 asset_id + revision_id \u5F15\u7528\u3002\u8D44\u6599\u4E0D\u5728\u5DE5\u4F5C\u533A\u6587\u4EF6\u7CFB\u7EDF\u91CC\uFF0C\u4E0D\u9700\u8981\u4E5F\u4E0D\u5E94\u8BE5\u5148\u7528\u6587\u4EF6\u5DE5\u5177\u53BB\u627E\u3002",
+    parameters: {
+      query: { type: "string", required: true, description: "\u6807\u9898\u6216\u6B63\u6587\u5173\u952E\u8BCD\u3002" },
+      kind: {
+        type: "string",
+        description: "\u53EA\u770B\u67D0\u4E00\u7C7B\u8D44\u6599\u3002",
+        enum: ["markdown", "text", "html", "json", "csv", "log", "binary"]
+      }
+    },
+    output: {
+      schema: {
+        type: "object",
+        additionalProperties: false,
+        properties: {
+          hits: {
+            type: "array",
+            required: true,
+            items: {
+              type: "object",
+              additionalProperties: false,
+              properties: {
+                asset_id: { type: "string", required: true },
+                revision_id: { type: "string", required: true },
+                revision_number: { type: "integer", required: true },
+                name: { type: "string", required: true },
+                kind: { type: "string", required: true },
+                folder_path: { type: "string", required: true },
+                conversion_status: { type: "string", required: true },
+                byte_length: { type: "integer", required: true },
+                updated_at: { type: "string", required: true },
+                excerpt: { type: "string", required: true }
+              }
+            }
+          }
+        }
+      },
+      render: (_args, value) => [{
+        type: "text",
+        text: value.hits.length > 0 ? value.hits.map((hit) => `${hit.name} (${hit.folder_path} \xB7 ${hit.kind} \xB7 \u4FEE\u8BA2 ${hit.revision_number} \xB7 ${hit.conversion_status})
+${hit.excerpt}`).join("\n\n") : "\u8D44\u6599\u5E93\u91CC\u6CA1\u6709\u5339\u914D\u7684\u8D44\u6599\u3002"
+      }]
+    },
+    async execute(args) {
+      const hits = await manager.search(args.query, args.kind);
+      return { hits: hits.map(hitForModel) };
+    }
+  })), "dsh-plugin-library: tool library_search");
+  ctx.effect(() => ctx.tools.register(defineTool({
+    name: "library_read",
+    description: "\u6309 asset_id \u8BFB\u53D6\u672C\u5730\u8D44\u6599\u5E93\u67D0\u4E2A\u4FEE\u8BA2\u7684\u6D3E\u751F\u6B63\u6587\uFF1B\u53EF\u6307\u5B9A revision_id \u8BFB\u53D6\u5386\u53F2\u4FEE\u8BA2\u3002\u53EA\u8BFB\uFF0C\u4E0D\u4FEE\u6539\u4EFB\u4F55\u5185\u5BB9\u3002",
+    parameters: {
+      asset_id: { type: "string", required: true, description: "library_search \u8FD4\u56DE\u7684 asset_id\u3002" },
+      revision_id: { type: "string", description: "\u5386\u53F2\u4FEE\u8BA2 id\uFF1B\u7701\u7565\u5219\u8BFB\u5F53\u524D\u4FEE\u8BA2\u3002" },
+      offset: { type: "integer", description: "\u4ECE 0 \u5F00\u59CB\u7684\u5B57\u7B26\u504F\u79FB\u3002" },
+      limit: { type: "integer", description: "\u672C\u6B21\u6700\u591A\u8FD4\u56DE\u7684\u5B57\u7B26\u6570\uFF0C1\u201320000\u3002" }
+    },
+    output: {
+      schema: {
+        type: "object",
+        additionalProperties: false,
+        properties: {
+          asset_id: { type: "string", required: true },
+          revision_id: { type: "string", required: true },
+          conversion_status: { type: "string", required: true },
+          content: { type: "string", required: true },
+          offset: { type: "integer", required: true },
+          truncated: { type: "boolean", required: true },
+          next_offset: { type: "integer" }
+        }
+      },
+      render: (_args, value) => [{ type: "text", text: value.content }]
+    },
+    async execute(args, exec) {
+      const offset = args.offset ?? 0;
+      const limit = args.limit ?? 12e3;
+      if (!Number.isInteger(offset) || offset < 0 || !Number.isInteger(limit) || limit < 1 || limit > 2e4) {
+        throw new Error("library/invalid-page");
+      }
+      const detail = manager.assetDetail(args.asset_id);
+      const revisionId = args.revision_id ?? detail.asset.currentRevisionId;
+      const revision = detail.revisions.find((row) => row.id === revisionId);
+      const complete = await manager.readText(args.asset_id, revisionId);
+      const content = complete.slice(offset, offset + limit);
+      const next = offset + content.length;
+      const truncated = next < complete.length;
+      return {
+        asset_id: args.asset_id,
+        revision_id: revisionId,
+        conversion_status: revision?.conversionStatus ?? "ready",
+        content,
+        offset,
+        truncated,
+        ...truncated ? { next_offset: next } : {}
+      };
+    }
+  })), "dsh-plugin-library: tool library_read");
+  ctx.effect(() => ctx.tools.register(defineTool({
+    name: "library_import",
+    description: "\u628A\u5185\u5BB9\u6216\u6587\u4EF6\u5BFC\u5165\u672C\u5730\u8D44\u6599\u5E93\uFF0C\u6210\u4E3A\u4E00\u4E2A\u65B0\u7684\u8D44\u6599\uFF08Markdown / TXT \u53EF\u7F16\u8F91\uFF1BCSV \u7B49\u6309\u6269\u5C55\u540D\u5165\u5E93\uFF09\u3002\u4E8C\u9009\u4E00\uFF1A\u7ED9 content\uFF08\u6587\u672C\u5185\u5BB9\uFF0CMarkdown \u6587\u672C\u63A8\u8350\uFF09\u6216\u7ED9 path\uFF08\u672C\u673A\u5DF2\u6709\u6587\u4EF6\u7684\u7EDD\u5BF9\u8DEF\u5F84\uFF09\u3002\u540C\u540D\u8D44\u6599\u5DF2\u5B58\u5728\u4F1A\u88AB\u62D2\u7EDD\uFF08library/name-conflict\uFF09\uFF0C\u4E0D\u4F1A\u9759\u9ED8\u8986\u76D6\u3002\u5BFC\u5165\u540E\u53EF\u7528 library_search / library_read \u627E\u5230\u5B83\u3002",
+    parameters: {
+      name: { type: "string", required: true, description: "\u8D44\u6599\u540D\u79F0\uFF08\u542B\u6269\u5C55\u540D\uFF0C\u5982 \u9700\u6C42.md \u6216 \u6570\u636E.csv\uFF09\u3002.md / .markdown / .txt \u6309\u6269\u5C55\u540D\u5B9A\u7C7B\u578B\u4E14\u53EF\u7F16\u8F91\u3002" },
+      content: { type: "string", description: "\u6587\u672C\u5185\u5BB9\uFF08\u4E0E path \u4E8C\u9009\u4E00\uFF09\u3002Markdown / \u7EAF\u6587\u672C\u7528\u8FD9\u4E2A\uFF1A\u5185\u5BB9\u4F1A\u6210\u4E3A\u7B2C\u4E00\u4E2A\u4FEE\u8BA2\uFF0C\u4E4B\u540E\u53EF\u5728\u9762\u677F\u91CC\u7F16\u8F91\u5E76\u53D1\u5E03\u65B0\u7248\u672C\u3002" },
+      path: { type: "string", description: "\u672C\u673A\u5DF2\u6709\u6587\u4EF6\u7684\u7EDD\u5BF9\u8DEF\u5F84\uFF08\u4E0E content \u4E8C\u9009\u4E00\uFF09\u3002\u7531 Host \u8BFB\u6587\u4EF6\u5B57\u8282\u5165\u5E93\uFF1B\u9002\u5408 CSV / PDF \u7B49\u5DF2\u6709\u6587\u4EF6\u3002" },
+      parent_id: { type: "string", description: "\u53EF\u9009\uFF1A\u76EE\u6807\u6587\u4EF6\u5939\u7684 node id\uFF1B\u7701\u7565\u5219\u653E\u5230\u6839\u76EE\u5F55\u3002" }
+    },
+    output: {
+      schema: { type: "object", additionalProperties: true, description: "\u5165\u5E93\u540E\u7684\u8D44\u6599\u6761\u76EE\uFF08\u542B asset_id \u4E0E reused \u6807\u8BB0\uFF09\u3002" },
+      render: (_args, value) => [{
+        type: "text",
+        text: [
+          `\u5DF2\u5BFC\u5165\u8D44\u6599\u300C${String(value?.name ?? "")}\u300D`,
+          value?.reused === true ? "\uFF08\u4E0E\u5DF2\u6709\u4FEE\u8BA2\u5185\u5BB9\u4E00\u81F4\uFF0C\u76F4\u63A5\u590D\u7528\uFF09" : "",
+          `asset_id=${String(value?.asset?.id ?? value?.id ?? "")}`,
+          value?.source === "task" ? "\uFF08\u672C\u5730\u4EA7\u7269\uFF09" : ""
+        ].filter(Boolean).join(" ")
+      }]
+    },
+    async execute(args) {
+      const hasContent = typeof args.content === "string" && args.content.length > 0;
+      const hasPath = typeof args.path === "string" && args.path.length > 0;
+      if (hasContent && hasPath) {
+        throw new FeatureError("library/invalid-request", "content \u4E0E path \u53EA\u80FD\u4E8C\u9009\u4E00\u3002");
+      }
+      if (!hasContent && !hasPath) {
+        throw new FeatureError("library/invalid-request", "content \u4E0E path \u5FC5\u987B\u4E8C\u9009\u4E00\uFF1A\u7ED9\u6587\u672C\u5185\u5BB9\uFF0C\u6216\u7ED9\u4E00\u4E2A\u672C\u673A\u6587\u4EF6\u7684\u7EDD\u5BF9\u8DEF\u5F84\u3002");
+      }
+      if (hasPath) {
+        return manager.importFromPath({ path: args.path, name: args.name, parentId: args.parent_id });
+      }
+      return manager.createText({ name: args.name, content: args.content, parentId: args.parent_id });
+    }
+  })), "dsh-plugin-library: tool library_import");
+}
+
+// index.js
+var name = "dsh-plugin-library";
+var inject = ["connection", "storageDomain", "tools", "fs"];
+async function apply(ctx, options = {}) {
+  const kit = await storageKit();
+  const manager = new LibraryManager(ctx, buildLibraryDomains(kit), options);
+  await manager.init();
+  registerFeatureRoute(ctx, { feature: "library", handlers: manager.handlers() });
+  await registerLibraryTools(ctx, manager);
+  const attribution = registerDeliverableImport(ctx, manager);
+  if (typeof options.attribution === "object" && options.attribution !== null) {
+    options.attribution.flush = attribution.flush;
+  }
+}
+export {
+  apply,
+  inject,
+  name
+};