@sparkelf/dsh-knowledge-base 0.1.5 → 0.1.20

package/lib/types/index.d.ts

@@ -5,8 +5,8 @@
  * 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.
+ * 3. The same-origin HTTP surface the Settings panel reads, plus the
+ *    model-facing `kb_search` / `kb_chunk_get` / `kb_outline` / `kb_file_*` tools.
  *
  * It owns no authorization logic. DataOps AuthGuard and PermissionGuard resolve
  * the caller's roles and grants from the session credential; this plugin only
@@ -19,12 +19,16 @@
  * @module @sparkelf/dsh-knowledge-base
  */
 import type { Context } from '@deepseek-ai/cordis';
+import { type WorkflowActor } from './workflowPublish.ts';
 import z from '@deepseek-ai/schemastery';
 import { type KnowledgeConfig, type KnowledgeGrant, type KnowledgeGrantRequest, type KnowledgeRevokeRequest, type KnowledgeSshView, type KnowledgeStatus } from './protocol.ts';
+import { type ScopeLocale } from './scopeAliases.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';
+import { type MineruBlock } from './extract.ts';
+import { type KnowledgeFileRead } from './knowledgeTools.ts';
 /** Cordis plugin name. */
 export declare const name = "dsh-knowledge-base";
 /**
@@ -74,6 +78,8 @@ export interface Config {
     actualRoot: string;
     /** Absolute path of the per-user view tree on the storage host. */
     viewRoot: string;
+    /** Local deployments: authoritative storage base, default `~/kb`. */
+    storageRoot: 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. */
@@ -116,16 +122,101 @@ export interface Config {
     mineruBaseUrl: string;
     /** Memory ceiling in MiB for the MinerU service, clamped to half the host's RAM. */
     mineruMemoryMaxMiB: number;
+    /**
+     * Directory holding `published.json` for the workflow plaza.
+     *
+     * Empty keeps the profile-local default (`$DSH_HOME/workflow-plaza`): the store is
+     * product metadata of this profile, not knowledge-tree content, so it deliberately
+     * does not live under the mount or the view root.
+     */
+    publishDir: string;
+    /** Sidecar directory for the SQLite FTS5 index (outside the agent-visible tree). */
+    indexDir?: string;
+    /** Optional hybrid retrieval. Disabled by default; no provider is called unless enabled. */
+    retrieval: {
+        vector: import('./embeddings.ts').VectorRetrievalConfig;
+    };
+    /**
+     * Outline generation policy.
+     *
+     * `autoGenerate: false` (the default) means upload/extraction build only the TOC and
+     * section structure. Summaries are written later by the `kb-summarize` skill through
+     * `kb_outline_save`. `true` restores the legacy deterministic extractive summaries.
+     */
+    outline: {
+        autoGenerate: boolean;
+    };
+    /** Locale used for the virtual root aliases in search/citation display paths. */
+    scopeLocale: ScopeLocale;
 }
 /** 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';
+export type KnowledgeErrorCode = 'not-configured' | 'unauthorized' | 'unreachable' | 'bad-response' | 'escapes-knowledge-root' | 'absolute-path' | 'empty-path' | 'nul-byte';
 /** Typed knowledge-base failure. */
 export declare class KnowledgeError extends Error {
     readonly code: KnowledgeErrorCode;
     constructor(message: string, code: KnowledgeErrorCode, options?: ErrorOptions);
 }
+/**
+ * Whether this deployment runs with a DataOps backend at all.
+ *
+ * `baseUrl` is the single fact that decides it: an empty value is a PERSONAL deployment, and
+ * a filled one is a TEAM deployment whose accounts, permissions, grants, shared settings and
+ * templates live in DataOps. This is an environment fact read from configuration, not a
+ * feature flag chosen at runtime -- which is why the personal and team paths are the same
+ * code with different gates rather than two branches selected by a boolean.
+ *
+ * Two consequences follow, and both are deliberate:
+ *
+ * 1. A personal deployment has NO accounts, NO permission model, NO shared settings and NO
+ *    member management. Those are not disabled features; they do not exist without an
+ *    authority to ask.
+ * 2. Every route that used to answer "not configured" now answers normally, gated on the
+ *    local filesystem instead. An unconfigured deployment is a supported shape, not an
+ *    error state.
+ *
+ * @param config - resolved plugin config.
+ * @returns true when a DataOps backend is configured.
+ */
+export declare function isTeamDeployment(config: Config): boolean;
+/**
+ * The identity a personal deployment acts as.
+ *
+ * A personal deployment has no caller to ask about: there is one operator, at the keyboard,
+ * with the file permissions of the process. `viewPathFor` still keys a view directory by
+ * user id, so this constant keeps that code path single rather than adding a second one for
+ * "no user".
+ */
+export declare const LOCAL_USER_ID = "local";
+/**
+ * Why a path was refused in a personal deployment.
+ *
+ * Named rather than silently refused: the reader asked for a file and the answer must say
+ * whether the path left the knowledge root or was simply not there.
+ */
+export interface LocalPathRefusal {
+    /** Machine-readable reason. */
+    readonly code: 'escapes-knowledge-root' | 'absolute-path' | 'empty-path' | 'nul-byte';
+    /** One sentence naming what was wrong with the path. */
+    readonly reason: string;
+}
+/**
+ * Whether a personal deployment may read or write one path.
+ *
+ * A personal deployment has no OTHER users to protect a path from, so there is no grant to
+ * consult -- but that is not the same as having no boundary. The boundary is the knowledge
+ * root itself: a relative path that stays inside `actualRoot` is allowed, and anything that
+ * climbs out is refused with a reason.
+ *
+ * The check is spelled out instead of relying on `join(root, relPath)` to clamp, because a
+ * silent clamp would let `../../etc/passwd` resolve to something inside the tree and report
+ * success for a request that should have been refused.
+ *
+ * @param relPath - the path as the caller sent it, relative to the knowledge root.
+ * @returns undefined when the path is allowed, else why it is not.
+ */
+export declare function checkLocalPath(relPath: string): LocalPathRefusal | undefined;
 /**
  * The resolved layout, derived on the Host.
  *
@@ -135,6 +226,10 @@ export declare class KnowledgeError extends Error {
  * @param config - resolved plugin config.
  * @returns The layout the page renders.
  */
+/** The authoritative root for a local deployment. */
+export declare function localStorageRoot(config: Config): string;
+/** Overlay the profile-local storage-root setting on a config. */
+export declare function withLocalStorageRoot(config: Config, storageRoot: string | undefined): Config;
 export declare function localConfig(config: Config, 
 /**
  * Whether the SSHFS credential currently resolves.
@@ -148,6 +243,7 @@ sshKeyConfigured?: boolean): KnowledgeConfig & {
     backendConfigured: boolean;
     storageProtocol: 'nfs' | 'sshfs';
     ssh: KnowledgeSshView;
+    retrieval: import('./embeddings.ts').VectorRetrievalConfig;
 };
 /**
  * Read the mounted tree's shape without consulting a backend.
@@ -434,6 +530,22 @@ export declare function readKnowledgeFile(ctx: Context, config: Config, relPath:
     kind: 'binary';
     size: number;
 }>;
+/**
+ * Read one file AFTER resolving the caller's permission for it.
+ *
+ * The HTTP `read` route used to rely on the caller's view hardlink alone: the file was
+ * visible because a previous sync linked it, but a revoke or an unsynced view could
+ * leave a readable link behind. Both the read route and the extraction path now share this
+ * function, so the permission answer is DataOps' and the path boundary is still
+ * enforced first.
+ *
+ * @param ctx - Host context.
+ * @param config - resolved plugin config.
+ * @param relPath - path relative to the knowledge root, in view coordinates.
+ * @returns The same shape `readKnowledgeFile` returns.
+ * @throws KnowledgeToolError with a structured code for the model.
+ */
+export declare function readAuthorized(ctx: Context, config: Config, relPath: string): Promise<KnowledgeFileRead>;
 /**
  * Read one file as raw bytes for a save-to-disk.
  *
@@ -616,7 +728,7 @@ export declare function canWritePath(ctx: Context, config: Config, relPath: stri
  * 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;
+export declare const MAX_KNOWLEDGE_WRITE_BYTES: number;
 /**
  * How long the template list may take before the surface gives up.
  *
@@ -672,6 +784,16 @@ export declare function createKnowledgeEntry(config: Config, relPath: string, op
     directory: boolean;
     content?: string;
     bytes?: Uint8Array;
+    /**
+     * The ceiling this write is checked against.
+     *
+     * Defaults to {@link MAX_KNOWLEDGE_WRITE_BYTES}. It is injectable ONLY so a test can
+     * verify the boundary with a small body: the production ceiling is a product decision
+     * that has already moved (1 MiB → 500 MiB), and building a payload at the current
+     * ceiling costs seconds of string work. A test that has to allocate the limit is
+     * measuring the machine's memory bandwidth, not the check.
+     */
+    limitBytes?: number;
 }): Promise<{
     relPath: string;
     kind: 'file' | 'directory';
@@ -687,12 +809,25 @@ export declare function createKnowledgeEntry(config: Config, relPath: string, op
  *
  * @param config - resolved plugin config, for the knowledge root and MinerU port.
  * @param relPath - the uploaded document's path, relative to the knowledge root.
+ * @param mineruUrl - the caller's own stored address, when they have one.
+ * @param readSharedUrl - reads the deployment's shared address. Called only when the caller
+ *   has none of their own, so a deployment without the OCR plugin pays nothing.
  * @returns What happened, or undefined when the format needs no extraction.
  */
-export declare function extractBeside(config: Config, relPath: string, mineruUrl?: string): Promise<{
+/**
+ * Resolve a view-relative path to the authoritative path.
+ *
+ * The agent sees `/workspace/kb` = `views/<uid>`; personal files are flattened from
+ * `actual/personal/<uid>/...`, and a department view may carry the organization chain.
+ * Extraction and indexing must open the actual file, not the view alias, or MinerU gets
+ * `no such document`.
+ */
+export declare function actualRelPathForView(ctx: Context, config: Config, relPath: string, caller?: KnowledgeCaller): Promise<string>;
+export declare function extractBeside(config: Config, relPath: string, mineruUrl?: string, readSharedUrl?: () => Promise<string | undefined>, ctx?: Context): Promise<{
     markdown: string;
     via?: string;
     reason?: string;
+    blocks?: MineruBlock[];
 } | undefined>;
 /**
  * Translate {@link extractBeside}'s answer into a queue terminal state.
@@ -719,13 +854,71 @@ export declare function extractionOutcomeOf(outcome: {
     via?: string;
     reason?: string;
 } | undefined): ExtractionOutcome;
+/**
+ * Where the MinerU address this deployment uses came from.
+ *
+ * The settings page says which of the three applies, so a reader never mistakes a shared
+ * value for their own: the caption under the field is the only thing distinguishing "you
+ * typed this" from "your administrator set this" from "this deployment derives it".
+ */
+export type MineruUrlSource = 'own' | 'shared' | 'derived';
+/** The effective MinerU address and where it came from. */
+export interface MineruUrlResolution {
+    /** The address to call, or undefined when nothing is configured. */
+    readonly url: string | undefined;
+    /** Which input produced {@link url}. */
+    readonly source: MineruUrlSource | undefined;
+}
+/**
+ * Resolve MinerU's base URL for this deployment, in the documented precedence order.
+ *
+ * Three inputs, and the order is the whole point:
+ *
+ * 1. **The caller's own stored address.** It is a deliberate choice, so nothing overrides it.
+ * 2. **The shared address the 「文档识别」 plugin's administrator configured.** One value for
+ *    the whole deployment; the reason a member never has to know MinerU exists.
+ * 3. **The address this deployment derives from its configured port.** Only ever
+ *    `127.0.0.1:<port>`, which is why it is last: it can name nothing but this machine.
+ *
+ * The shared value is READ, never written. This plugin has no business persisting another
+ * plugin's setting, and a copy written back into `.kb-settings.json` would become a second
+ * source of truth that silently stops following the administrator's later change.
+ *
+ * @param config - resolved plugin config.
+ * @param sharedUrl - the deployment's shared address, when the caller has none of their own.
+ * @returns the effective address and its origin.
+ */
+export declare function resolveMineruUrl(config: Config, sharedUrl?: string): MineruUrlResolution;
 /**
  * MinerU's base URL for this deployment, or undefined when it is not configured.
  *
+ * The URL-only view of {@link resolveMineruUrl}, kept because the extractor only needs the
+ * address and threading a source through it would make every caller unpack a field it does
+ * not read.
+ *
  * @param config - resolved plugin config.
- * @returns `http://127.0.0.1:<port>` when the service is expected, else undefined.
+ * @param sharedUrl - the deployment's shared address, when the caller has none of their own.
+ * @returns the address to call, else undefined.
  */
-export declare function mineruUrlFor(config: Config): string | undefined;
+export declare function mineruUrlFor(config: Config, sharedUrl?: string): string | undefined;
+/**
+ * Read the shared MinerU address the 「文档识别」 plugin's administrator configured.
+ *
+ * A read-only peek at another plugin's setting, and deliberately tolerant: the OCR plugin is
+ * optional, its backend route answers `''` when nobody has configured it, and an unreachable
+ * backend must not stop a document upload. Every failure therefore answers "no shared value"
+ * and the caller falls through to its own derivation, which is the behaviour a deployment
+ * without the OCR plugin has.
+ *
+ * This never writes. The value belongs to the OCR plugin's administrator; copying it into
+ * this plugin's settings file would make a stale duplicate of a value that is supposed to
+ * change once for everyone.
+ *
+ * @param ctx - host context carrying the credential store.
+ * @param config - resolved plugin config, for the backend origin and credential.
+ * @returns the shared address, or undefined when none is configured or it cannot be read.
+ */
+export declare function readSharedMineruUrl(ctx: Context, config: Config): Promise<string | undefined>;
 /**
  * Ask DataOps whether the CALLER may manage grants.
  *
@@ -755,6 +948,30 @@ export declare function mineruUrlFor(config: Config): string | undefined;
  * @returns Whether the caller holds the grant-management permission.
  */
 export declare function canManageGrants(ctx: Context, config: Config): Promise<boolean>;
+/**
+ * Who authors or reviews a plaza workflow.
+ *
+ * Team deployments must name the real DataOps caller: a publish record without a
+ * responsible author is not reviewable. A personal deployment has no backend and no
+ * second administrator, so its local operator is both author and reviewer.
+ */
+export declare function resolveWorkflowActor(ctx: Context, config: Config): Promise<WorkflowActor>;
+/**
+ * The backend permission one HTTP method needs.
+ *
+ * The named file operations are the routes the page and the file tools actually call;
+ * leaving a route out is deliberate for read-only status/preferences surfaces whose
+ * data is already scoped by the caller's grants.
+ */
+export declare function permissionForKbRoute(method: string): string | undefined;
+/**
+ * Whether this caller may see and use the review tab.
+ *
+ * In a team deployment this is the same grant-management authority the permission page
+ * uses. A personal deployment has no administrator and no grants; its owner is the
+ * reviewer by construction.
+ */
+export declare function canReviewWorkflows(ctx: Context, config: Config): Promise<boolean>;
 /**
  * Create one grant in the backend permission store.
  *
@@ -807,6 +1024,10 @@ export interface StepRun {
 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";
+/** Second bundled skill: the explicit, model-authored summarisation workflow. */
+export declare const KB_SUMMARIZE_SKILL_NAME = "kb-summarize";
+/** Third bundled skill: explicit document/directory vectorization. */
+export declare const KB_VECTORIZE_SKILL_NAME = "kb-vectorize";
 /**
  * Short description shown in the skill list.
  *
@@ -814,7 +1035,18 @@ export declare const KNOWLEDGE_SKILL_NAME = "knowledge-base";
  * 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.";
+export declare const KNOWLEDGE_SKILL_DESCRIPTION: string;
+/**
+ * Short description of the explicit summary skill.
+ *
+ * Upload and extraction never write summaries. This skill is the only documented way to
+ * turn source chunks into document/section summaries and key facts, and it does so through
+ * the model's own reading plus `kb_outline_save` -- never through a hidden LLM call inside
+ * the plugin.
+ */
+export declare const KB_SUMMARIZE_SKILL_DESCRIPTION: string;
+/** Short description of the explicit vectorization skill. */
+export declare const KB_VECTORIZE_SKILL_DESCRIPTION: string;
 /**
  * Where this package's SKILL.md lives, from either build layout.
  *
@@ -825,6 +1057,28 @@ export declare const KNOWLEDGE_SKILL_DESCRIPTION = "Read and change the shared k
  * @returns absolute path of the SKILL.md this plugin ships.
  */
 export declare function knowledgeSkillPath(): string;
+/**
+ * Where the bundled `kb-summarize` skill lives.
+ *
+ * Same layout reasoning as {@link knowledgeSkillPath}: both `lib/index.js` and a source
+ * run from `src/` sit one level below the package root.
+ *
+ * @returns absolute path of the kb-summarize SKILL.md.
+ */
+export declare function kbSummarizeSkillPath(): string;
+/** Where the bundled `kb-vectorize` skill lives. */
+export declare function kbVectorizeSkillPath(): string;
+/**
+ * Where this package's tutorial document lives, from either build layout.
+ *
+ * Resolved the same way {@link knowledgeSkillPath} is, and for the same reason: the
+ * build emits `lib/index.js` while a source run executes from `src/`, and both sit one
+ * level below the package root. The file is shipped by `files[]` in package.json, so a
+ * published install answers the same path without a second mechanism.
+ *
+ * @returns absolute path of the tutorial this plugin ships.
+ */
+export declare function tutorialTemplatePath(): string;
 /**
  * The skill provider that teaches the model how to use this knowledge base.
  *
@@ -835,6 +1089,10 @@ export declare function knowledgeSkillPath(): string;
  * @returns a provider the skill registry can list and read.
  */
 export declare const KNOWLEDGE_SKILL_RANK = 640;
+/** The summary skill is more specialised, so it sorts after the general KB skill. */
+export declare const KB_SUMMARIZE_SKILL_RANK = 650;
+/** Vectorization is another explicit, specialised action. */
+export declare const KB_VECTORIZE_SKILL_RANK = 660;
 /** Both a human and the model may invoke this skill. */
 export declare const KNOWLEDGE_SKILL_INVOCATION: {
     readonly modelInvocable: true;

package/lib/types/initialize.d.ts

@@ -0,0 +1,105 @@
+/**
+ * First-run initialisation of the authoritative knowledge tree.
+ *
+ * A deployment that has never been used has no `global/`, `department/` or
+ * `personal/` directory, and the reader finds a knowledge base that can hold
+ * nothing. The buckets were previously created only as a side effect of some write
+ * happening to need their parent, so a fresh share, or one whose buckets were
+ * removed, stayed empty with no way to recover.
+ *
+ * Two rules shape everything here:
+ *
+ * 1. **Every run re-checks the directories.** A bucket someone deleted by hand must
+ *    come back on the next start, so "did this already run" is the wrong question
+ *    for them; the answer is recomputed from the filesystem each time and costs three
+ *    `mkdir` calls.
+ * 2. **The tutorial is written once, ever.** It is an ordinary document that the
+ *    reader may edit, and an edit is worth more than a newer built-in version, so a
+ *    second write is refused and the refusal is the success case.
+ *
+ * @module @sparkelf/dsh-knowledge-base
+ */
+/** Buckets that must exist before the knowledge base can hold anything. */
+export declare const KNOWLEDGE_BUCKETS: readonly ["global", "department", "personal"];
+/**
+ * File name of the bundled tutorial, both as shipped and as published.
+ *
+ * One constant for both so a rename cannot leave the writer looking for a file the
+ * package no longer ships, or publishing under a name the template is not stored at.
+ */
+export declare const TUTORIAL_FILE_NAME = "\u4E07\u76F8AI\u4F7F\u7528\u6559\u7A0B.html";
+/** Where the bundled tutorial is published inside the authoritative tree. */
+export declare const TUTORIAL_REL_PATH: string;
+/** What one bucket did on this run. */
+export type BucketOutcome = 'created' | 'exists' | 'failed';
+/** What the tutorial did on this run. */
+export type TutorialOutcome = 'written' | 'skipped' | 'failed';
+/** The result of one initialisation attempt, per item. */
+export interface InitReport {
+    /** One entry per bucket, in the order they are checked. */
+    buckets: {
+        bucket: string;
+        outcome: BucketOutcome;
+    }[];
+    /** What happened to the tutorial document. */
+    tutorial: TutorialOutcome;
+    /** Set when the run could not even reach the tree (a missing mount, a bad root). */
+    error?: string;
+}
+/** The write and read surface, injected so the rules can be tested without a NAS. */
+export interface InitIo {
+    /**
+     * Whether the storage the root lives in is attached.
+     *
+     * Provisioning CREATES the root and its buckets, so it cannot require the root to
+     * exist; what it does require is the thing the root lives in. On a real deployment
+     * that is the mounted share, whose absence means provisioning would manufacture a
+     * directory where a mount belongs -- and the next mount would then refuse it as
+     * non-empty. Answering false leaves the tree untouched and the run unsuccessful, so
+     * the next page load retries once the share appears.
+     */
+    isStorageReady: () => Promise<boolean>;
+    /** Create a directory under the authoritative root; throws `exists` when taken. */
+    createDirectory: (relPath: string) => Promise<void>;
+    /** Create a document with exclusive semantics; throws `exists` when taken. */
+    createDocument: (relPath: string, content: string) => Promise<void>;
+    /** The tutorial body to publish. */
+    tutorialHtml: () => string;
+    /** Personal mode: create only the root, with no buckets or tutorial. */
+    ensureRoot?: () => Promise<void>;
+}
+/** One line of the run log; the caller decides where it goes. */
+export interface InitLogLine {
+    /** `bucket` or `tutorial`. */
+    item: string;
+    /** The outcome word reported for this item. */
+    outcome: BucketOutcome | TutorialOutcome;
+}
+/** The initialiser, as the plugin holds it. */
+export interface Initializer {
+    /**
+     * Make sure the tree is usable, at most one run in flight.
+     *
+     * Concurrent callers share one run rather than queueing: the work is idempotent, so
+     * a second run would only repeat the first one's `mkdir` calls and race it on the
+     * tutorial write. A caller arriving while a run is in flight awaits that run's
+     * result.
+     * @returns The report of the run this caller observed.
+     */
+    ensure: () => Promise<InitReport>;
+    /** Whether any run has completed without a fatal error, for the status route. */
+    hasSucceeded: () => boolean;
+}
+/**
+ * Build the initialiser.
+ *
+ * The IO is injected rather than imported so the four rules this exists to enforce --
+ * idempotent buckets, self-healing, write-once tutorial, single concurrent run -- can
+ * be exercised against a fake tree that can be inspected and mutated between runs.
+ * @param io - the write surface and the tutorial body.
+ * @param log - sink for the per-item report lines.
+ * @returns the initialiser the plugin stores.
+ */
+export declare function createInitializer(io: InitIo, log: (line: InitLogLine) => void, options?: {
+    personal?: boolean;
+}): Initializer;