@sparkelf/dsh-knowledge-base 0.0.0-stage → 0.1.1

package/lib/types/index.d.ts

@@ -0,0 +1,899 @@
+/**
+ * Knowledge-base Host plugin.
+ *
+ * This package owns three things and nothing else:
+ * 1. The protocol contract toward the DataOps knowledge API (`protocol.ts`).
+ * 2. Idempotent deployment recipes for the remote pieces, run over the
+ *    ssh-manager seam (`deploy.ts`, `remote.ts`).
+ * 3. The same-origin HTTP surface the Settings panel reads, plus the two
+ *    model-facing tools.
+ *
+ * It owns no authorization logic. DataOps AuthGuard and PermissionGuard resolve
+ * the caller's roles and grants from the session credential; this plugin only
+ * forwards requests (AGENTS.md "Managed DataOps Authorization").
+ *
+ * Content retrieval is deliberately absent. Once the view tree is mounted the
+ * official `grep`, `read`, `write`, and `edit` tools operate on it as an
+ * ordinary local path, so this capability does not duplicate them.
+ *
+ * @module @sparkelf/dsh-knowledge-base
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import { type KnowledgeConfig, type KnowledgeGrant, type KnowledgeGrantRequest, type KnowledgeRevokeRequest, type KnowledgeSshView, type KnowledgeStatus } from './protocol.ts';
+import { type KnowledgeStorageSettings, type ViewDelta } from './views.ts';
+import { type DeployPlanContext, type MineruBackend, type MineruTier } from './deploy.ts';
+import { type RemoteHost, type RemoteRunner } from './remote.ts';
+import { type ExtractionOutcome } from './extractionQueue.ts';
+/** Cordis plugin name. */
+export declare const name = "dsh-knowledge-base";
+/**
+ * Host services this plugin needs.
+ *
+ * `credentials` resolves the session token per request so a rotated token
+ * reaches the next request without a restart. `webServer` serves the
+ * same-origin routes the Settings panel reads. The SSH transport is reached
+ * over HTTP at the ssh-manager's own route, so it is not injected here.
+ */
+export declare const inject: string[];
+/** Plugin configuration. */
+export interface Config {
+    /**
+     * Base URL of the DataOps knowledge API. Empty disables the DataOps-backed
+     * status/index routes, leaving only the local deployment controls.
+     */
+    baseUrl: string;
+    /** Credential reference holding the DataOps session token. */
+    credentialRef: string;
+    /** Request timeout in milliseconds for DataOps API calls. */
+    timeoutMs: number;
+    /**
+     * Where documents are stored.
+     *
+     * `local` keeps them in the workspace's own directory (`mountPoint`): no mount, no
+     * sync, no remote round trip per read. `remote` keeps the synchronized shape, where
+     * the browsable pointer is a per-user view inside an NFS share refreshed from
+     * `actualRoot`. The two modes share listing, preview, edit, permission and audit and
+     * differ only in where the bytes live.
+     */
+    storageMode: 'local' | 'remote';
+    /**
+     * How a `remote` deployment reaches its share.
+     *
+     * Orthogonal to {@link storageMode}: a local deployment stores nothing remotely, so it
+     * ignores this. `nfs` is the original shape -- an export mounted on the Host at
+     * {@link mountPoint}. `sshfs` reaches the same kind of directory over SSH instead, which
+     * is what a host behind NAT needs: NFSv4 callbacks cannot traverse NAT, while an
+     * outbound SSH connection can. The rest of the plugin does not branch on this: both
+     * protocols end as a directory bound into the container at `mountPoint`.
+     */
+    storageProtocol: 'nfs' | 'sshfs';
+    /** Path inside the container where the user's view tree is mounted. */
+    mountPoint: string;
+    /** Absolute path of the authoritative tree on the storage host. */
+    actualRoot: string;
+    /** Absolute path of the per-user view tree on the storage host. */
+    viewRoot: string;
+    /** Comma-separated export spec of clients allowed to mount the NFS export. */
+    permitted: string;
+    /** Host serving the export, as an address or `address:/path` pseudo root. */
+    nfsServer: string;
+    /** SSHFS: remote host, as an address or hostname. */
+    sshHost: string;
+    /** SSHFS: login user on that host. */
+    sshUser: string;
+    /** SSHFS: TCP port the SSH daemon listens on. */
+    sshPort: number;
+    /**
+     * SSHFS: credential reference holding the private key.
+     *
+     * A reference, never the key itself: the panel reports only this name and whether it
+     * resolves, so the secret stays in the credential store and out of the settings file.
+     */
+    sshKeyRef: string;
+    /** SSHFS: absolute path of the shared directory on the remote host. */
+    sshRemotePath: string;
+    /**
+     * SSHFS: extra `-o` options for the mount.
+     *
+     * Kept as one string because that is how `sshfs -o` takes them, and the operator is
+     * the one who knows whether their host needs `allow_other` or a different identity
+     * file. The mount step always adds the reconnect options this deployment needs.
+     */
+    sshMountOptions: string;
+    /** MinerU quality tier to deploy. */
+    mineruTier: MineruTier;
+    /** MinerU small-model backend to deploy. */
+    mineruBackend: MineruBackend;
+    /** TCP port the MinerU API listens on where it is deployed. */
+    mineruPort: number;
+    /**
+     * MinerU's full base address, or `''` to derive it from `mineruPort`.
+     *
+     * Deployment-level fallback for the setting a caller can change on the settings page.
+     * Empty keeps the derivation, so a deployment that never sets this keeps working.
+     */
+    mineruBaseUrl: string;
+    /** Memory ceiling in MiB for the MinerU service, clamped to half the host's RAM. */
+    mineruMemoryMaxMiB: number;
+}
+/** Config schema; an invalid value fails the profile load loudly. */
+export declare const Config: z<Config>;
+/** Why a knowledge-base request failed, with a stable machine-routable code. */
+export type KnowledgeErrorCode = 'not-configured' | 'unauthorized' | 'unreachable' | 'bad-response';
+/** Typed knowledge-base failure. */
+export declare class KnowledgeError extends Error {
+    readonly code: KnowledgeErrorCode;
+    constructor(message: string, code: KnowledgeErrorCode, options?: ErrorOptions);
+}
+/**
+ * The resolved layout, derived on the Host.
+ *
+ * There is no backend counterpart to ask: DataOps serves no knowledge config
+ * route, so the mounted layout the container was started with is the answer. A
+ * remote call here would only ever answer 404.
+ * @param config - resolved plugin config.
+ * @returns The layout the page renders.
+ */
+export declare function localConfig(config: Config, 
+/**
+ * Whether the SSHFS credential currently resolves.
+ *
+ * Passed in rather than resolved here because this function is synchronous and called from
+ * a dozen places that never touch the SSH transport. A caller that shows the panel resolves
+ * it first; every other caller leaves it false, which only means "this answer does not
+ * claim a key".
+ */
+sshKeyConfigured?: boolean): KnowledgeConfig & {
+    backendConfigured: boolean;
+    storageProtocol: 'nfs' | 'sshfs';
+    ssh: KnowledgeSshView;
+};
+/**
+ * Read the mounted tree's shape without consulting a backend.
+ *
+ * The count comes from the mounted directory itself, which is the same tree the
+ * model's grep and read tools see, so the number the page reports cannot drift
+ * from what retrieval actually reaches.
+ * @param config - resolved plugin config.
+ * @returns The visible file count, or null when the mount is absent.
+ */
+export declare function localStatus(config: Config): Promise<KnowledgeStatus>;
+/**
+ * Why the visible tree is not readable, when it is not.
+ *
+ * A null count used to be one condition and is really two, and the page told the
+ * reader the wrong one. It means either the mounted tree is absent, or the pointer
+ * at `mountPoint` has not been built yet -- a per-user symlink that only a view
+ * sync creates. The second is the ordinary state for a caller who has been granted
+ * nothing yet, and reporting it as "not mounted" sends the reader to inspect a
+ * mount that is working.
+ *
+ * The distinction is a filesystem fact, not a policy: whether the configured path
+ * exists at all, versus whether it is a pointer this plugin can build on demand.
+ */
+export type KnowledgeMountState = 'mounted' | 'pointer-missing' | 'absent';
+/** The fields a sync reports beyond the filesystem delta. */
+export interface SyncReportFields {
+    /** The browsable path that was retargeted. */
+    mountPoint: string;
+    /** Whether the pointer now points at this caller's view. */
+    mountPointed: boolean;
+    /** The identity the view is keyed by. */
+    userId: string;
+    /** Human-readable name of the caller, when the backend reported one. */
+    label?: string;
+    /** Candidate paths considered. */
+    considered: number;
+    /** Paths DataOps resolved as readable. */
+    resolved: number;
+    /** The view directory this caller's files are linked into. */
+    viewPath: string;
+}
+/**
+ * Classify why the browsable path does or does not yield a file count.
+ *
+ * Reads the configured path rather than inferring from the count, because a count
+ * of null is compatible with both failure modes and cannot tell them apart.
+ * @param config - resolved plugin config.
+ * @returns The state, in order of increasing severity.
+ */
+export declare function classifyMount(config: Config): Promise<KnowledgeMountState>;
+/**
+ * Rebuild the caller's visible tree and point the browsable path at it.
+ *
+ * Shared by the explicit `views.sync` route and the status route's first-load
+ * repair, so both take exactly the same path: one implementation means the
+ * automatic case cannot drift from the button the reader can press.
+ *
+ * It is idempotent and writes nothing when the resolved set is unchanged, which is
+ * what makes it safe to run without being asked -- `syncView` returns
+ * `unchanged > 0, linked: []` in that case.
+ *
+ * The decision stays with DataOps: the resolve route is self-scoped, and this
+ * function only links what that answer allows.
+ * @param host - the plugin context, for the backend calls.
+ * @param config - resolved plugin config.
+ * @param paths - candidate relative paths; omitted means walk the authoritative root.
+ * @returns The sync report, or a refusal the caller should relay.
+ */
+export declare function syncCallerView(host: Context, config: Config, paths?: string[]): Promise<(ViewDelta & SyncReportFields & {
+    status: number;
+    error?: never;
+}) | {
+    status: number;
+    error: string;
+}>;
+/**
+ * Enumerate every file under the authoritative root, as relative paths.
+ *
+ * The view builder needs candidate paths to ask the permission store about. When a
+ * caller does not supply them, this walks the tree and produces exactly the set a
+ * view could ever hold: hidden names are skipped, matching what the explorer shows
+ * and keeping editor scratch files out of every user's view.
+ * @param root - the authoritative directory.
+ * @returns Relative paths of the files under it.
+ */
+export declare function listRelativeFiles(root: string): Promise<string[]>;
+/**
+ * One directory's measured shape, for the indexing table.
+ *
+ * Every field is a fact read from the filesystem: the count, the newest
+ * modification instant, and whether the caller could read it. Nothing here is an
+ * estimate of a job state, because this plugin has no index job to report.
+ */
+export interface DirectoryShape {
+    /** Path relative to the mount point; an empty string is the mount itself. */
+    relPath: string;
+    /** Files below this directory, counted recursively. */
+    fileCount: number;
+    /** Newest modification instant in Unix ms, absent when nothing could be read. */
+    mtimeMs?: number;
+    /** Whether this directory's own entries could be listed. */
+    readable: boolean;
+    /**
+     * Whether some part of this subtree could not be read, making `fileCount` a
+     * lower bound rather than a total.
+     *
+     * Separate from {@link readable} because the two describe different things: a
+     * directory can be listable itself while containing a subdirectory that is not.
+     * Rolling both into one flag would either call a readable directory unreadable
+     * or present a partial count as a whole one.
+     */
+    partial: boolean;
+}
+/**
+ * Report the mount's per-directory shape.
+ *
+ * The indexing page needs rows, and the only true rows available are directories
+ * of the mounted tree: this plugin has no index of its own, so there is no
+ * per-directory index status to report and none is invented. What is measurable
+ * is how many files sit below each directory, when the newest one changed, and
+ * whether the caller can read it.
+ *
+ * Only the first level is listed. A row per every nested directory would be a
+ * tree dump rather than a table, and the children of an expanded directory are
+ * already reachable from the file tree beside this page.
+ *
+ * Hidden entries are skipped, matching every other walk in this module: they are
+ * editor scratch files rather than knowledge documents.
+ * @param root - the directory to report on, normally the mount point.
+ * @returns One row per visible child directory, plus the root's own row.
+ */
+export declare function listDirectoryShapes(root: string): Promise<DirectoryShape[]>;
+/**
+ * Fetch the grant table from the backend.
+ *
+ * The route answers `{ grants: [...] }`, not a bare array. Reading it as an array
+ * would hand a `.map` call an object -- which is what the empty panel was
+ * reporting as "map is not a function" -- so both shapes are accepted here: a
+ * backend that answers the bare array keeps working, and the shape this
+ * deployment returns is the one the panel sees.
+ *
+ * @param ctx - Host context.
+/**
+ * Fetch the grant table from the backend.
+ *
+ * Two translations happen here, and both are the reason this is not a one-line
+ * relay:
+ *
+ * 1. The route answers `{ grants: [...] }`, not a bare array. Reading it as an
+ *    array handed a `.map` an object, which is what the empty panel reported as
+ *    "map is not a function".
+ * 2. A backend grant names its document `resourceId` and does not carry a
+ *    `kind`, `grantedBy` or `grantedAt`. Those are this plugin's own vocabulary,
+ *    so they are derived here: the path is the resource id, a path with an
+ *    extension is a file, and the grantor and timestamp fall back to neutral
+ *    answers rather than being invented.
+ *
+ * @param ctx - Host context.
+ * @param config - resolved plugin config.
+ * @returns the grants, empty when the body carries none.
+ */
+export declare function fetchGrants(ctx: Context, config: Config): Promise<KnowledgeGrant[]>;
+/** One match the search surface can render. */
+export interface KnowledgeHit {
+    /** Path relative to the mount point, which is also the grant's resource id. */
+    relPath: string;
+    /** File name alone, for a compact row. */
+    name: string;
+    /** Whether the term matched the file's text rather than only its name. */
+    inContent: boolean;
+    /** Matching line, when the term matched inside the file. */
+    line?: string;
+    /** 1-based line number of {@link line}. */
+    lineNumber?: number;
+    /** Last-modified instant in Unix ms, when the stat succeeded. */
+    mtimeMs?: number;
+}
+/**
+ * Search the mounted tree by file name and text.
+ *
+ * This is a direct walk rather than an index, matching how retrieval works here:
+ * the tools read the mount with grep and read, so there is no separate index whose
+ * contents could disagree with the files. Only text files are opened, and only up
+ * to a byte budget, so a search over a large mount stays bounded.
+ * @param root - the mount point to walk.
+ * @param term - case-insensitive term to look for.
+ * @param limit - maximum hits to return.
+ * @returns The hits, name matches first.
+ */
+export declare function searchKnowledge(root: string, term: string, limit?: number): Promise<KnowledgeHit[]>;
+/** One directory entry, as the page's own listing renders it. */
+export interface KnowledgeEntry {
+    /** Path relative to the mount point. */
+    relPath: string;
+    /** Name alone. */
+    name: string;
+    /** Whether this entry is a directory. */
+    isDir: boolean;
+    /** Last-modified instant in Unix ms, when it could be read. */
+    mtimeMs?: number;
+    /** Size in bytes for files. */
+    size?: number;
+    /**
+     * Whether the calling user may read this path; `true` on every row a permission
+     * check produced.
+     *
+     * A row carries the file's name, size and modification time, so a denied path
+     * cannot be published with a "not yours" marker on it: the marker is not what
+     * discloses the file. Denied and undecided paths are removed from the result
+     * instead (see {@link listDirectoryWithPermissions}), which is also why the flag
+     * is redundant here and only kept for a row that was explicitly resolved.
+     */
+    readable?: boolean;
+    /** Number of direct children, for a directory row. */
+    childCount?: number;
+    /**
+     * Whether a reader exists for this file's format.
+     *
+     * Set on file rows only. The page uses it to decide whether "extract markdown" is a
+     * meaningful action for this row, so the menu does not have to know the extractor's
+     * extension list.
+     */
+    canExtract?: boolean;
+    /**
+     * Whether this file's `.md` sibling already exists.
+     *
+     * Set on file rows only, and only for formats that have an extractor. Lets the page
+     * say "already extracted" rather than offering a retry that would be refused.
+     */
+    hasMarkdown?: boolean;
+}
+/**
+ * List one directory level with each child's modification time.
+ * @param root - the mount point, used to make paths relative.
+ * @param dir - absolute directory to read.
+ * @returns The entries, directories first then files, each in name order.
+ */
+export declare function listDirectory(root: string, dir: string): Promise<KnowledgeEntry[]>;
+/**
+ * List one directory level, keeping only the entries DataOps resolved as readable.
+ *
+ * The listing and the permission check are separate concerns, so this composes
+ * them rather than growing {@link listDirectory}: a caller that only needs the
+ * filesystem facts (the preview, the search) keeps using that one.
+ *
+ * Removing a row rather than tagging it is the whole point. A row carries the
+ * file's name, size and modification time, so returning a denied path with a "not
+ * yours" marker on it discloses precisely what the check was meant to withhold:
+ * the marker is not what reveals the file, and a reader can still fetch its bytes.
+ * Proving that a name is off limits is not a reason to show the name.
+ *
+ * Every unresolved case fails closed. An empty base URL, a missing caller id, and a
+ * resolve call that throws all drop the row, because "the answer could not be
+ * obtained" is not a licence to publish. Answering the unknown case with the full
+ * listing is what made an unreachable backend publish every file.
+ * @param ctx - Host context.
+ * @param config - resolved plugin config.
+ * @param root - the mount point.
+ * @param dir - absolute directory to read.
+ * @param userId - the caller whose view the answer is about.
+ * @returns The rows DataOps resolved as readable, in listing order.
+ */
+export declare function listDirectoryWithPermissions(ctx: Context, config: Config, root: string, dir: string, userId: string | undefined): Promise<KnowledgeEntry[]>;
+/**
+ * Read one knowledge file for the preview.
+ *
+ * The preview must not depend on a conversation session. The listing is served by
+ * this plugin's own route and needs none, so a session-backed read would leave the
+ * page able to list files and unable to open them, which reads as a broken preview
+ * rather than as a missing session. Containment is checked here because the path
+ * arrives from the browser.
+ * @param ctx - Host context.
+ * @param config - resolved plugin config.
+ * @param relPath - path relative to the mount point.
+ * @returns The file's text, truncation flag and modification instant.
+ */
+export declare function readKnowledgeFile(ctx: Context, config: Config, relPath: string): Promise<{
+    kind: 'text';
+    content: string;
+    truncated: boolean;
+    mtimeMs?: number;
+} | {
+    kind: 'binary';
+    size: number;
+}>;
+/**
+ * Read one file as raw bytes for a save-to-disk.
+ *
+ * Separate from {@link readKnowledgeFile}, which is shaped for the preview pane: that one
+ * truncates a large text file and refuses a binary one, because the pane cannot show
+ * more. A download has the opposite requirement -- the reader asked for THIS file, so it
+ * is returned whole or refused with a reason, never silently shortened.
+ *
+ * Base64 rather than a byte array: the answer travels as JSON, and a `number[]` for a
+ * megabyte file is several times the payload and slower to parse on both ends.
+ * @param ctx - the plugin context.
+ * @param config - resolved plugin config.
+ * @param relPath - the file to read, relative to the mount point.
+ * @returns The file's bytes and a suggested name, or a refusal reason.
+ */
+export declare function readKnowledgeFileForDownload(ctx: Context, config: Config, relPath: string): Promise<{
+    name: string;
+    base64: string;
+    size: number;
+    mime: string;
+}>;
+/** One row the permission surface offers as a principal. */
+export interface PrincipalOption {
+    /** Value the grant must carry: a user's UUID, or a code for every other kind. */
+    id: string;
+    /** Human-facing name, falling back to the id when the backend sends none. */
+    label: string;
+    /** Login name, for users only: two accounts can share a display name. */
+    username?: string;
+    /**
+     * Role codes this principal belongs to.
+     *
+     * Users only, and only when the directory reported it. The permission overview needs
+     * this to answer "what does this PERSON have": a role grant confers access on every
+     * member, so without the membership a reader whose access is entirely role-derived
+     * would look like they hold nothing. Absent means the directory did not say -- which
+     * the page reports as unavailable inheritance rather than as no inheritance.
+     */
+    roleCodes?: string[];
+}
+/**
+ * Read the principals of one kind from the backend.
+ *
+ * The permission store matches a user by primary key and every other kind by
+ * `code`, and there is nowhere else a valid value can come from. Reading the
+ * directory here is what keeps the surface from asking an operator to transcribe
+ * a UUID.
+ *
+ * Failures are reported as an empty list rather than thrown: the directories are
+ * a convenience over a field that also accepts a typed value, so a caller whose
+ * account may not read them can still grant by hand.
+ * @param ctx - Host context.
+ * @param config - resolved plugin config.
+ * @param kind - principal kind to list.
+ * @returns The options, in the order the backend returned them.
+ */
+export declare function fetchPrincipals(ctx: Context, config: Config, kind: KnowledgeGrantRequest['principalType']): Promise<PrincipalOption[]>;
+/** The calling user, as DataOps describes them. */
+export interface KnowledgeCaller {
+    /** Stable user id. Keys the caller's view directory, so it must be a safe name. */
+    userId: string;
+    /** Human-facing name, for reporting. */
+    label: string;
+    /** Role codes the backend reported. Kept for reporting, not for authorization. */
+    roleCodes: string[];
+    /**
+     * DataOps department code, when the caller belongs to one.
+     *
+     * Read for LAYOUT only: it selects which `department/<code>/` subtree the view
+     * links, and never decides whether a path may be read — {@link canReadPath}
+     * stays the single authority for that. A caller with no department simply gets
+     * no department bucket.
+     */
+    departmentCode?: string;
+    /** Department display name, for reporting beside the bucket. */
+    departmentName?: string;
+    /**
+     * The caller's organization path, root first, as DataOps reported it.
+     *
+     * Layout only, exactly like {@link departmentCode}: it decides how deep the
+     * department bucket nests and never whether a path may be read. Empty when the
+     * backend does not report it (an older DataOps), in which case the bucket keeps its
+     * single-level shape rather than disappearing.
+     */
+    departmentPathCodes?: string[];
+    /** The organization path's display names, index-aligned with the codes. */
+    departmentPathNames?: string[];
+}
+/**
+ * Read a `{ code, name }` pair DataOps nests under the profile.
+ *
+ * The organization path arrays are read here too, but each is independent: a backend
+ * that reports `code`/`name` without the arrays (every deployment today) still yields a
+ * usable department, and the caller simply gets a single-level bucket. That is why the
+ * two are separate fields rather than one required structure — the old shape must keep
+ * working without a version check.
+ *
+ * A path is only used when the two arrays agree in length and the leaf matches `code`.
+ * A mismatch means the profile contradicts itself, and half of a contradicting pair
+ * would place documents under a folder the reader cannot recognize.
+ *
+ * @param value - the raw field, which is absent on older backends.
+ * @returns The pair with a non-empty code plus any usable path, or undefined.
+ */
+export declare function readDepartmentOf(value: unknown): {
+    code: string;
+    name: string;
+    pathCodes?: string[];
+    pathNames?: string[];
+} | undefined;
+export declare function fetchCaller(ctx: Context, config: Config): Promise<KnowledgeCaller>;
+/**
+ * Ask DataOps whether the CALLER may read one path.
+ *
+ * The decision is the backend's, not this plugin's: the route is self-scoped, so
+ * the answer is about the credential's own user and this function cannot be used
+ * to ask about anyone else. That is what keeps a per-user view from becoming a
+ * second permission implementation.
+ *
+ * A failed request answers `false` rather than throwing, so one unreadable path
+ * cannot leave a view half-built. An unreachable backend therefore produces an
+ * empty view instead of a wrong one.
+ * @param ctx - Host context.
+ * @param config - resolved plugin config.
+ * @param relPath - path relative to the authoritative root.
+ * @returns Whether the caller may read it.
+ */
+/**
+ * The root resource id one knowledge-base-wide grant is stored under.
+ *
+ * A grant needs a non-empty `resourceId` (DataOps rejects an empty one with
+ * "资源ID不能为空"), so "the whole knowledge base" is named explicitly rather than by an
+ * empty string. A document can never have this id, because document ids come from titles
+ * and never start with `@`.
+ */
+export declare const KB_ROOT_RESOURCE_ID = "@kb-root";
+/**
+ * The ancestor chain for one knowledge path, nearest parent first.
+ *
+ * DataOps resolves a permission by matching the resource's own id OR any ancestor named
+ * here, so passing this chain is what turns "grant the knowledge base once" into "every
+ * document inside it inherits that grant". Without it each file needs its own row, which
+ * is why a freshly created document used to look unreadable to an administrator.
+ *
+ * The chain walks the path's parents (`a/b/c.md` → `a/b` → `a`) and ends at the root id,
+ * so a grant on any level applies to everything beneath it and the most specific level
+ * still wins for a deny.
+ * @param relPath - the path being authorised; empty or the root id stands for the root.
+ * @returns Ancestor references, nearest first, root last.
+ */
+export declare function knowledgeAncestorsFor(relPath: string): Array<{
+    resourceType: string;
+    resourceId: string;
+}>;
+export declare function canReadPath(ctx: Context, config: Config, relPath: string): Promise<boolean>;
+/**
+ * Ask DataOps whether the CALLER may write one path.
+ *
+ * The same self-scoped resolve route {@link canReadPath} uses, read for a different
+ * field. A move needs this and not merely read: it destroys the source path, so a
+ * caller who can only read must not be able to relocate a document out from under
+ * the people who own it. The backend distinguishes the two (`canRead` and
+ * `canWrite` are separate conclusions drawn from the same grants), and this reads
+ * its answer rather than re-deriving one from the other.
+ *
+ * A failed request answers `false` rather than throwing, so an unreachable backend
+ * refuses the move instead of authorizing it.
+ * @param ctx - Host context.
+ * @param config - resolved plugin config.
+ * @param relPath - path relative to the authoritative root.
+ * @returns Whether the caller may write it.
+ */
+export declare function canWritePath(ctx: Context, config: Config, relPath: string): Promise<boolean>;
+/**
+ * Largest document the create and upload routes will write.
+ *
+ * A knowledge document is text a person reads, not a data dump, and the route
+ * buffers the body in memory before writing it. The ceiling is what keeps one
+ * request from taking the Host's heap: without it a caller with write access could
+ * post an arbitrarily large body, because nothing downstream limits the size of a
+ * file on the share.
+ */
+export declare const MAX_KNOWLEDGE_WRITE_BYTES = 1048576;
+/**
+ * How long the template list may take before the surface gives up.
+ *
+ * Shorter than the plugin's general timeout on purpose: a template list decorates a
+ * page, and the shared backend can be busy with unrelated work for far longer than
+ * a reader should wait to see some cards.
+ */
+export declare const TEMPLATE_READ_TIMEOUT_MS = 5000;
+/**
+ * A refusal from the write path, with a code the route maps to a status.
+ *
+ * Kept apart from {@link KnowledgeError}, whose codes describe how a TRANSPORT
+ * call ended. These say why a write was not performed, which is a different
+ * question with different statuses: a name already taken is a conflict, a path
+ * outside the root is a bad request, and a document over the ceiling is too large.
+ */
+export declare class KnowledgeWriteError extends Error {
+    readonly code: 'bad-path' | 'exists' | 'too-large' | 'write-failed';
+    constructor(message: string, code: KnowledgeWriteError['code'], options?: ErrorOptions);
+}
+/**
+ * Create one document or directory in the authoritative tree.
+ *
+ * The path is written under `actualRoot` rather than under the caller's own view
+ * directory, and that choice is the whole design:
+ *
+ * - The view is NOT storage. `syncView` mirrors the resolved grant set onto it, so
+ *   a file that appears there is removed by the next sync unless DataOps resolves
+ *   it as readable. Measured: a document written into a view was gone after the
+ *   next `syncView` (`delta.unlinked` named it). Writing there would hand the
+ *   reader a document that any later permission change silently deletes.
+ * - `actual/` is the authoritative tree, so a document written there survives, and
+ *   the grant system then decides who sees it. Creating is therefore SHARED by
+ *   construction: the creator needs write access, and everyone DataOps resolves as
+ *   a reader will find the document in their view at their next sync. That is what
+ *   a knowledge base is for, and it is the semantic the product already has.
+ *
+ * There is deliberately no `userId` component in the path. `actual/` is shared and
+ * has no per-user dimension; inventing `actual/<uid>/...` would create a shape the
+ * rest of the plugin does not understand, because a view is built from grants and
+ * not from a directory per user.
+ *
+ * The write is exclusive (`wx`), so the kernel refuses to replace an existing file.
+ * A stat-then-write would leave a window in which another caller's document could
+ * be overwritten, and the check would still be the thing that was raced.
+ * @param config - resolved plugin config.
+ * @param relPath - destination, relative to the authoritative root.
+ * @param options - `directory` creates a directory; `content` is the file body.
+ * @returns The path written.
+ * @throws KnowledgeError when the path escapes the root, exists, or cannot be written.
+ */
+export declare function createKnowledgeEntry(config: Config, relPath: string, options: {
+    directory: boolean;
+    content?: string;
+    bytes?: Uint8Array;
+}): Promise<{
+    relPath: string;
+    kind: 'file' | 'directory';
+}>;
+/**
+ * Extract an uploaded document's text into a `.md` sibling.
+ *
+ * Called after the original is written, never before: the bytes the user chose
+ * are the deliverable, and an extraction that fails must not take them down with
+ * it. The sibling keeps the original extension in its name (`报告.docx.md`), so it
+ * cannot collide with a handwritten `报告.md` and a reader can still tell which
+ * document it came from.
+ *
+ * @param config - resolved plugin config, for the knowledge root and MinerU port.
+ * @param relPath - the uploaded document's path, relative to the knowledge root.
+ * @returns What happened, or undefined when the format needs no extraction.
+ */
+export declare function extractBeside(config: Config, relPath: string, mineruUrl?: string): Promise<{
+    markdown: string;
+    via?: string;
+    reason?: string;
+} | undefined>;
+/**
+ * Translate {@link extractBeside}'s answer into a queue terminal state.
+ *
+ * The extractor reports three different outcomes through two fields, and they mean
+ * different things to a reader deciding what to do next:
+ *
+ * - `markdown` set, no `reason` — the sibling was written (`succeeded`).
+ * - `markdown` set WITH a `reason` — the text was produced but writing the sibling was
+ *   refused, typically because it already exists. The reason is kept so a retry can
+ *   report why nothing changed (`failed`, with the refusal verbatim).
+ * - `markdown` empty, `reason` set — no authority could read the document; this is the
+ *   `no-extractor-succeeded: …` case a reader retries after an upgrade.
+ *
+ * An `undefined` answer means the format has no extractor at all, which the queue
+ * normally prevents by asking `isExtractable` first; it is mapped for the caller that
+ * bypassed that gate rather than left to throw.
+ *
+ * @param outcome - what {@link extractBeside} returned.
+ * @returns the state the queue records.
+ */
+export declare function extractionOutcomeOf(outcome: {
+    markdown: string;
+    via?: string;
+    reason?: string;
+} | undefined): ExtractionOutcome;
+/**
+ * MinerU's base URL for this deployment, or undefined when it is not configured.
+ *
+ * @param config - resolved plugin config.
+ * @returns `http://127.0.0.1:<port>` when the service is expected, else undefined.
+ */
+export declare function mineruUrlFor(config: Config): string | undefined;
+/**
+ * Ask DataOps whether the CALLER may manage grants.
+ *
+ * The question is put to the authority instead of being inferred here. The route
+ * read below is guarded by exactly `data:access-grant:manage` -- the permission the
+ * grant and revoke calls require -- so the backend's own answer to the read is the
+ * answer to "may this caller manage grants": a `200` means the permission is held,
+ * a `403` means it is not. Nothing about the body is used, and the filter keeps the
+ * response to this resource type rather than downloading the whole grant table.
+ *
+ * Every other outcome denies. An unreachable backend, a timeout, a rejected token
+ * and a malformed body all leave the permission unproven, and an unproven permission
+ * must not publish a management surface: an administrator who is wrongly denied
+ * retries after the backend recovers, while a non-administrator who is wrongly
+ * allowed keeps an entry point the backend would refuse anyway.
+ *
+ * Role names were considered as the judge and rejected on measured evidence, so that
+ * the reason survives the next reader. `/auth/me` returns `roles[].code` as the
+ * role's DISPLAY name -- measured 2026-10-16 against the running backend, which
+ * answers `管理员` and `超级管理员` -- while `SUPER_ADMIN` / `ADMIN` are the separate
+ * `system_key` values that route never exposes. Matching the constant names would
+ * therefore deny every real administrator, and matching display names would let a
+ * role rename silently change who may manage grants. The enforced permission point
+ * has neither problem, which is why it is the only judge used here.
+ * @param ctx - Host context.
+ * @param config - resolved plugin config.
+ * @returns Whether the caller holds the grant-management permission.
+ */
+export declare function canManageGrants(ctx: Context, config: Config): Promise<boolean>;
+/**
+ * Create one grant in the backend permission store.
+ *
+ * The plugin names the principal and the path; DataOps decides whether the
+ * principal exists and whether the caller may write the grant at all. That split
+ * is why this is a thin relay rather than a policy of its own.
+ * @param ctx - Host context.
+ * @param config - resolved plugin config.
+ * @param body - the grant to create.
+ * @returns The backend's acknowledgement.
+ */
+export declare function createGrant(ctx: Context, config: Config, body: KnowledgeGrantRequest): Promise<unknown>;
+/** Remove one grant from the backend permission store. */
+export declare function revokeGrant(ctx: Context, config: Config, body: KnowledgeRevokeRequest): Promise<unknown>;
+/**
+ * Overlay the operator's stored choices onto the deployment configuration.
+ *
+ * Two sources answer "which storage shape": the profile, which is fixed when the container is
+ * created, and `.kb-settings.json`, which the panel writes. The file wins, because it is the
+ * one the operator can still change -- a saved choice that the running process ignored would
+ * be the same dead control this route exists to replace.
+ *
+ * Only the fields the panel owns are overlaid. `mountPoint`, `actualRoot`, `viewRoot` and
+ * `permitted` stay as the deployment declares them: those are bind mounts and export specs,
+ * decided when the container starts, so a file that changed them would point the plugin at
+ * paths nothing serves.
+ * @param config - the deployment configuration.
+ * @param stored - what the settings file holds.
+ * @returns The configuration the request should use.
+ */
+export declare function withStoredStorage(config: Config, stored: KnowledgeStorageSettings): Config;
+/** Build the substitution context for the deployment recipes. */
+export declare function planContext(config: Config): DeployPlanContext;
+/** One recorded step execution. */
+export interface StepRun {
+    stepId: string;
+    hostId: string;
+    state: 'running' | 'succeeded' | 'failed';
+    startedAt: string;
+    finishedAt: string | null;
+    /** Human-readable transcript assembled from per-command results. */
+    log: string[];
+}
+/**
+ * Register the knowledge-base routes and tools.
+ * @param ctx - Host context carrying credentials, tools, and the Web server.
+ * @param config - resolved plugin configuration.
+ */
+/** Provider name this plugin registers its bundle skill under. */
+export declare const KNOWLEDGE_SKILL_PROVIDER = "dsh-knowledge-base";
+/** Name the model sees in the skill catalog. */
+export declare const KNOWLEDGE_SKILL_NAME = "knowledge-base";
+/**
+ * Short description shown in the skill list.
+ *
+ * Kept beside the SKILL.md body rather than parsed out of its frontmatter: the
+ * catalog answers `list()` without reading any skill content, so the text has to
+ * be available before the file is opened.
+ */
+export declare const KNOWLEDGE_SKILL_DESCRIPTION = "Read and change the shared knowledge base: browse, search, create, upload, rename, move and delete documents in the \u5168\u5C40 / \u90E8\u95E8 / \u4E2A\u4EBA trees.";
+/**
+ * Where this package's SKILL.md lives, from either build layout.
+ *
+ * The build emits `lib/index.js`, so the file sits one level up; a source run
+ * resolves from `src/`, which is also one level up. Both answer the same path,
+ * which is why this does not need to believe in a single layout.
+ *
+ * @returns absolute path of the SKILL.md this plugin ships.
+ */
+export declare function knowledgeSkillPath(): string;
+/**
+ * The skill provider that teaches the model how to use this knowledge base.
+ *
+ * One bundled skill, read from disk on `get()` rather than kept in memory: the
+ * body is documentation, and a host that never asks for it should not pay for
+ * holding it.
+ *
+ * @returns a provider the skill registry can list and read.
+ */
+export declare const KNOWLEDGE_SKILL_RANK = 640;
+/** Both a human and the model may invoke this skill. */
+export declare const KNOWLEDGE_SKILL_INVOCATION: {
+    readonly modelInvocable: true;
+    readonly userInvocable: true;
+};
+/**
+ * The skill provider that teaches the model how to use this knowledge base.
+ *
+ * One bundled skill, read from disk on `get()` rather than kept in memory: the
+ * body is documentation, and a host that never asks for it should not pay for
+ * holding it.
+ *
+ * `rank` places it after the bundled GenUI skill (600): a task that needs both
+ * wants the fence reference first, because the knowledge skill's own answers are
+ * mostly prose and shell commands.
+ *
+ * @returns a provider the skill registry can list and read.
+ */
+export declare function knowledgeBaseSkillProvider(): {
+    readonly name: string;
+    readonly list: (options: {
+        readonly cwd?: string;
+        readonly signal?: AbortSignal;
+    }) => Promise<readonly SkillCandidateLike[]>;
+    readonly get: (candidate: SkillCandidateLike, options: {
+        readonly cwd?: string;
+        readonly signal?: AbortSignal;
+    }) => Promise<SkillDefinitionLike | undefined>;
+};
+/**
+ * One catalog entry, shaped like the host's `SkillCandidate`.
+ *
+ * Declared here instead of imported: this plugin does not depend on the skill
+ * package (the registry is an optional injection), so the structural contract is
+ * restated rather than turning an optional neighbour into a build requirement. The
+ * registry merges these by the fields it reads, so a shape that satisfies them is
+ * the whole contract.
+ */
+export interface SkillCandidateLike {
+    readonly name: string;
+    readonly description: string;
+    readonly invocation: {
+        readonly modelInvocable: boolean;
+        readonly userInvocable: boolean;
+    };
+    readonly source: 'bundled';
+    readonly provider: string;
+    readonly path: string;
+    readonly resourceBase: {
+        readonly kind: 'directory';
+        readonly path: string;
+    };
+    readonly rank: number;
+    readonly locator: string;
+}
+/** One loaded skill, shaped like the host's `SkillDefinition`. */
+export interface SkillDefinitionLike extends SkillCandidateLike {
+    readonly content: string;
+}
+export declare function apply(ctx: Context, deploymentConfig: Config): void;
+/** Re-exported for tests and for callers that need the host shape. */
+export type { RemoteHost, RemoteRunner };