@sparkelf/dsh-knowledge-base 0.1.5 → 0.1.20

package/lib/types/outlineText.d.ts

@@ -0,0 +1,134 @@
+/**
+ * Deterministic document outline extraction for the knowledge-base index.
+ *
+ * The outline is navigation, never evidence. `summary-v1` copied the first sentence of each
+ * chapter, which made the INDEX.md read like a pile of raw paragraphs. `summary-v2` still
+ * uses no language model: it ranks whole source sentences by legal cues (obligation, ratio,
+ * amount, deadline, article opener), keeps 2–4 of them per chapter, and composes the
+ * document summary from those chapter summaries instead of from the first paragraph.
+ *
+ * Two readability-only normalizations are applied: docx/PDF extraction spaces inside a
+ * Chinese word are removed (`二分 之一` → `二分之一`), and the canonical `“以上”包括本数`
+ * wording is compacted to `“以上含本数”`. Every number, subject and exception still comes
+ * from a source sentence; key facts remain verbatim apart from the article-label prefix.
+ *
+ * `structure-v3` already keeps headings as hard chunk boundaries. This module reconstructs
+ * the heading tree from the leading heading lines of each chunk and turns the chunks under a
+ * node into an extractive summary plus the numeric/exception sentences (`key_facts`) an
+ * operator looks for first.
+ *
+ * @module @sparkelf/dsh-knowledge-base/outlineText
+ */
+/** Version of the extraction rules; bump when the summary shape changes. */
+export declare const SUMMARY_VERSION = "summary-v2";
+/** How many summary sections a document outline keeps in its table of contents. */
+export declare const OUTLINE_MAX_SECTIONS = 500;
+/** One indexed chunk, already ordered by its zero-based ordinal. */
+export interface OutlineChunk {
+    id: number;
+    /** Stable citation key when the index has one. */
+    chunkKey?: string;
+    ordinal: number;
+    /** First line of the chunk, as stored by the indexer. */
+    heading?: string;
+    content: string;
+}
+/** One verbatim sentence that carries a threshold, ratio, body or exception. */
+export interface OutlineKeyFact {
+    /** Article heading or nearest heading label; never generated prose. */
+    fact: string;
+    /** The source sentence, verbatim (bounded). */
+    value: string;
+    chunkId: number;
+}
+/** One heading node and the chunks below it. */
+export interface OutlineSection {
+    /** Document-scoped stable id (`s<docId>-<n>`). */
+    sectionId: string;
+    /** Full path: `第一章 总则 > 第一条 ...`. */
+    headingPath: string;
+    /** This node's own heading text. */
+    title: string;
+    /** 1-based depth; 1 is a chapter/top-level heading. */
+    level: number;
+    /** Extractive summary; 80–200 characters for a chapter when the source allows it. */
+    summary: string;
+    keyFacts: OutlineKeyFact[];
+    /** Chunks whose own heading is this node. */
+    chunkIds: number[];
+    /** Every chunk under this node, including descendants. */
+    sourceChunkIds: number[];
+    parentId?: string;
+}
+/** One table-of-contents row. `sections` carries the full heading path and summaries. */
+export interface OutlineTocEntry {
+    sectionId: string;
+    title: string;
+    level: number;
+    /** Chunks whose own heading is this node. */
+    chunkIds: number[];
+}
+/** Everything one document outline produces. */
+export interface BuiltOutline {
+    /** `#` title when the text has one, otherwise the filename. */
+    documentTitle: string;
+    /** Document-level summary, 200–300 characters when the source allows it. */
+    summary: string;
+    /** Chunks whose sentences were used by the document summary. */
+    sourceChunkIds: number[];
+    toc: OutlineTocEntry[];
+    sections: OutlineSection[];
+}
+/** Input for {@link buildDocumentOutline}. */
+export interface BuildOutlineInput {
+    docId: number;
+    /** Filename (or stored title), used when the text has no `#` title. */
+    docTitle: string;
+    /** Original source path, shown in INDEX.md. */
+    sourcePath: string;
+    chunks: readonly OutlineChunk[];
+}
+interface HeadingLine {
+    title: string;
+    /** Heading depth before tree clamping. */
+    rawLevel: number;
+    kind: 'markdown' | 'chapter' | 'section' | 'article' | 'chinese';
+}
+interface Sentence {
+    text: string;
+    chunkId: number;
+    ordinal: number;
+    position: number;
+    /** Article label inherited across continuation chunks (`第六条` followed by a body-only chunk). */
+    article?: string;
+}
+/** Classify one trimmed line as a heading, or return undefined. */
+export declare function headingLineOf(line: string): HeadingLine | undefined;
+/** Collapse Markdown/table syntax into plain prose, keeping numbers and punctuation. */
+export declare function plainOutlineText(value: string): string;
+/** Split one chunk into non-heading, non-rule sentences. */
+export declare function sentencesOfChunk(chunk: OutlineChunk): Sentence[];
+/**
+ * Build one document's extractive outline.
+ *
+ * Every sentence comes from a chunk; the only generated text is structural framing
+ * ("共 N 章", "章节包括") and the legal-phrase compaction documented above. No number,
+ * responsible body or exception is invented.
+ */
+export declare function buildDocumentOutline(input: BuildOutlineInput): BuiltOutline;
+/** Input for {@link renderOutlineMarkdown}. */
+export interface RenderOutlineInput {
+    docId: number;
+    docTitle: string;
+    sourcePath: string;
+    summaryVersion: string;
+    /** How the summary was produced; omitted for legacy callers means `extractive`. */
+    summaryKind?: 'none' | 'extractive' | 'llm';
+    summary: string;
+    summarySourceChunkIds: readonly number[];
+    toc: readonly OutlineTocEntry[];
+    sections: readonly OutlineSection[];
+}
+/** Render the human/agent-readable INDEX.md for one document. */
+export declare function renderOutlineMarkdown(input: RenderOutlineInput): string;
+export {};

package/lib/types/protocol.d.ts

@@ -44,6 +44,8 @@ export interface KnowledgeConfig {
      * This is the directory a container mounts.
      */
     viewRoot: string;
+    /** Local deployments: configured storage base (default `~/kb`). */
+    storageRoot?: string;
     /** Absolute path where the view tree is mounted inside the container. */
     mountPoint: string;
     /** NFS export host, when the deployment uses the NFS transport. */
@@ -114,6 +116,26 @@ export interface KnowledgeStatus {
         jobId?: string;
         progress?: number;
     };
+    /** Optional vector index coverage; reported only by hosts that have this feature. */
+    vector?: {
+        enabled: boolean;
+        provider?: string;
+        model?: string;
+        embeddedChunks: number;
+        totalChunks: number;
+        embeddedDocs: number;
+        totalDocs: number;
+        failed: number;
+        canManageVector?: boolean;
+        indexing: {
+            running: boolean;
+            total?: number;
+            done?: number;
+            embedded?: number;
+            failed?: number;
+            error?: string;
+        };
+    };
 }
 /**
  * One grant to create.
@@ -207,6 +229,18 @@ export declare const ENDPOINTS: {
      * category yet.
      */
     readonly templates: "/api/resources/wiki/pages/templates";
+    /**
+     * The MinerU address the 「文档识别」 plugin's administrator shares with the deployment.
+     *
+     * Read-only here. The knowledge base keeps its own per-caller address field, and when that
+     * is empty this shared value is what the parser is called with. It is never written back:
+     * a copy in this plugin's settings file would stop following the administrator's later
+     * change and become a second source of truth.
+     *
+     * `AuthGuard`-only on the backend, so any signed-in member may read it: the address is not
+     * a secret, and being allowed to USE it is not being allowed to CHANGE it (`canEdit`).
+     */
+    readonly ocrConfig: "/api/ocr/config";
 };
 /**
  * Resource type the knowledge base records its paths under.

package/lib/types/scopeAliases.d.ts

@@ -0,0 +1,20 @@
+/** Virtual view aliases for the three canonical knowledge scopes. */
+export type ScopeLocale = 'zh' | 'en';
+export declare const CANONICAL_SCOPES: readonly ["global", "department", "personal"];
+export type CanonicalScope = typeof CANONICAL_SCOPES[number];
+/** Display label for one canonical scope. */
+export declare function scopeAliasFor(scope: CanonicalScope, locale?: ScopeLocale): string;
+/** All accepted spellings of one canonical scope. */
+export declare function scopeSpellings(scope: CanonicalScope): string[];
+/**
+ * Map a view path whose first segment is a localized scope alias back to canonical.
+ *
+ * The NFS tree and the index stay `global/department/personal`; aliases are only a
+ * virtual view coordinate accepted at every entry. Unknown first segments are left
+ * untouched (legacy/top-level paths).
+ */
+export declare function resolveScopeAlias(relPath: string): string;
+/** Turn a canonical path into its localized view spelling for display. */
+export declare function localizedScopeForPath(relPath: string, locale?: ScopeLocale): string;
+/** Canonical scope from a path or alias, or undefined for a non-bucket path. */
+export declare function scopeFromAlias(segment: string): CanonicalScope | undefined;

package/lib/types/vectorIndex.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Optional SQLite vector sidecar for hybrid retrieval.
+ *
+ * Vectors are stored as raw Float32 blobs in the same SQLite file as the FTS index.
+ * No sqlite-vec extension is required: candidate rows are read into the process and
+ * cosine similarity is computed here. The table is keyed by the current chunk id, so
+ * a re-chunk simply makes an old row unreachable until it is pruned.
+ *
+ * @module @sparkelf/dsh-knowledge-base/vectorIndex
+ */
+import { DatabaseSync } from 'node:sqlite';
+/** One stored embedding row. */
+export interface VectorEmbeddingRow {
+    chunkId: number;
+    docId: number;
+    path: string;
+    model: string;
+    dim: number;
+    vector: Float32Array;
+    norm: number;
+    contentHash: string;
+}
+/** One chunk that needs an embedding. */
+export interface VectorChunk {
+    id: number;
+    docId: number;
+    path: string;
+    content: string;
+}
+/** Counts for the settings page. */
+export interface VectorIndexStats {
+    totalChunks: number;
+    embeddedChunks: number;
+    totalDocs: number;
+    embeddedDocs: number;
+    failed: number;
+    model: string;
+}
+/** Create the vector tables in an existing index database. */
+export declare function ensureVectorSchema(db: DatabaseSync): void;
+/** Stable content key used to decide whether an embedding is stale. */
+export declare function embeddingContentHash(content: string): string;
+/** L2 norm of a vector; zero vectors cannot be normalized and are never stored. */
+export declare function vectorNorm(vector: ArrayLike<number>): number;
+/** Serialize a vector as little-endian Float32 bytes. */
+export declare function packVector(vector: ArrayLike<number>): Buffer;
+/** Deserialize a Float32 blob without copying the bytes. */
+export declare function unpackVector(blob: Uint8Array): Float32Array;
+/** Cosine similarity; both norms are precomputed for stored rows. */
+export declare function cosineSimilarity(left: ArrayLike<number>, right: ArrayLike<number>, leftNorm: number, rightNorm: number): number;
+/** Upsert one embedding and clear its previous failure. */
+export declare function putEmbedding(db: DatabaseSync, row: {
+    chunkId: number;
+    docId: number;
+    path: string;
+    model: string;
+    vector: readonly number[];
+    contentHash: string;
+    updatedAt: string;
+}): void;
+/** Record a per-chunk failure without pretending a vector exists. */
+export declare function recordVectorFailure(db: DatabaseSync, row: {
+    chunkId: number;
+    docId: number;
+    path: string;
+    model: string;
+    error: string;
+    updatedAt: string;
+}): void;
+/** Read chunks for a set of documents. */
+export declare function chunksForDocuments(db: DatabaseSync, docIds: readonly number[]): VectorChunk[];
+/** Current embedding state for chunks, keyed by chunk id. */
+export declare function embeddingStates(db: DatabaseSync, model: string, chunkIds: readonly number[]): Map<number, {
+    contentHash: string;
+    model: string;
+}>;
+/** Stats for the settings page, optionally for one model. */
+export declare function vectorIndexStats(db: DatabaseSync, model: string): VectorIndexStats;
+/** One vector candidate row before fuse. */
+export interface VectorCandidate {
+    chunkId: number;
+    docId: number;
+    path: string;
+    score: number;
+}
+/**
+ * Read every current embedding for a model and rank it by cosine similarity.
+ *
+ * Scope filtering is applied in SQL before similarity ordering, exactly as the FTS
+ * side does. A caller-supplied `canRead` check still runs on the resulting paths.
+ */
+export declare function vectorCandidates(db: DatabaseSync, options: {
+    model: string;
+    query: readonly number[];
+    clauses: readonly string[];
+    params: readonly (string | number)[];
+    scopeClause: string;
+    scopeParams: readonly (string | number)[];
+    candidateK: number;
+}): VectorCandidate[];
+/** One document target for an explicit vectorization run. */
+export interface VectorDocument {
+    id: number;
+    path: string;
+    scope: string;
+}
+/** Resolve explicit targets by id or path prefix, optionally narrowed by scope. */
+export declare function vectorDocuments(db: DatabaseSync, target: {
+    docId?: number;
+    path?: string;
+    scope?: string;
+    all?: boolean;
+}): VectorDocument[];

package/lib/types/views.d.ts

@@ -17,6 +17,7 @@
  *
  * @module @sparkelf/dsh-knowledge-base/views
  */
+import { type VectorRetrievalConfig } from './embeddings.ts';
 /** One path a user may read, as DataOps resolved it. */
 export interface ResolvedPath {
     /** Path relative to the authoritative root. */
@@ -488,6 +489,10 @@ export interface KnowledgeStorageSettings {
     sshMountOptions?: string;
     /** SSHFS: credential reference holding the private key -- a name, never the key. */
     sshKeyRef?: string;
+    /** Optional vector retrieval settings, stored deployment-wide. */
+    retrieval?: {
+        vector: VectorRetrievalConfig;
+    };
 }
 /** Whether a write must be reviewed before it counts as published. */
 export interface KnowledgeSettings extends KnowledgeStorageSettings {
@@ -540,6 +545,22 @@ export declare function storageSettingsOf(raw: Record<string, unknown>): Knowled
  * @returns The stored settings, or the defaults.
  */
 export declare function readSettings(viewDir: string): Promise<KnowledgeSettings>;
+/**
+ * Whether this caller's settings file holds a MinerU address that was refused as invalid.
+ *
+ * {@link readSettings} normalises a hand-edited or foreign value down to `''`, which makes
+ * "never configured" and "configured with something unusable" indistinguishable. The
+ * settings page has to tell them apart: the second case must not leave the reader thinking
+ * their own address is in use when it was dropped and a fallback answered instead.
+ *
+ * Read separately rather than threaded through {@link readSettings} because only the page
+ * needs it -- the extractor either has a usable address or it does not, and the reason it
+ * does not is a message for a human.
+ *
+ * @param viewDir - the user's view directory.
+ * @returns true when the file holds a non-empty value that the normaliser rejected.
+ */
+export declare function storedMineruInvalid(viewDir: string): Promise<boolean>;
 /**
  * Replace this knowledge base's settings.
  *
@@ -807,12 +828,23 @@ export interface KnowledgeAuditEntry {
      * here" and "who changed it last". A save through the host's own file editor
      * reports here through a side channel (see the `audit.appended` route), which is
      * what keeps the host's write path untouched.
+     *
+     * `delete` is a caller-scoped tombstone (the bytes stay on disk); `external-change`
+     * is written by the filesystem watcher when a process outside these tools (usually
+     * a shell command) modifies the authoritative tree.
      */
-    action: 'create' | 'upload' | 'move' | 'approve' | 'reject' | 'edit';
+    action: 'create' | 'upload' | 'move' | 'approve' | 'reject' | 'edit' | 'delete' | 'external-change';
     /** The path the action concerned, relative to the knowledge root. */
     relPath: string;
     /** For a move, the destination path. */
     toRelPath?: string;
+    /**
+     * Extra detail for actions that have more than one flavour.
+     *
+     * Only `external-change` currently uses it (`updated` / `renamed` / `deleted`).
+     * Optional so older lines remain readable.
+     */
+    detail?: 'updated' | 'renamed' | 'deleted';
     /**
      * What became of it.
      *

package/lib/types/workflowPublish.d.ts

@@ -0,0 +1,114 @@
+/**
+ * The workflow-plaza publish store.
+ *
+ * A workflow authored in a conversation is not public when it is written: the record
+ * lands as `pending`, an administrator reviews the actual prompt, and only `approved`
+ * records enter the plaza. The store lives beside the DSH profile rather than inside the
+ * knowledge tree because it is product metadata, not a document: it has no per-user view,
+ * no trash, and no DataOps grant semantics.
+ *
+ * Writes are read-modify-write over one JSON file, serialized per path and committed by
+ * atomic rename, so two model calls cannot overwrite each other and a restart never sees
+ * a half-written store.
+ *
+ * @module @sparkelf/dsh-knowledge-base/workflowPublish
+ */
+/** Where a published workflow currently is. */
+export type PublishedWorkflowVisibility = 'global' | 'department' | 'private';
+export type PublishedWorkflowStatus = 'pending' | 'approved' | 'rejected' | 'unpublished';
+/** What the model may publish. */
+export interface WorkflowPublishInput {
+    readonly title: string;
+    readonly description: string;
+    readonly instruction: string;
+    readonly cronHint?: string;
+    readonly category?: string;
+    readonly visibility?: PublishedWorkflowVisibility;
+    readonly departmentCode?: string;
+}
+/** One authored workflow as stored. */
+export interface PublishedWorkflow {
+    readonly id: string;
+    readonly title: string;
+    readonly description: string;
+    readonly instruction: string;
+    readonly cronHint: string;
+    readonly category: string;
+    readonly visibility: PublishedWorkflowVisibility;
+    readonly departmentCode?: string;
+    readonly authorId: string;
+    readonly authorName: string;
+    readonly createdAt: string;
+    readonly updatedAt: string;
+    readonly status: PublishedWorkflowStatus;
+    readonly unpublishedAt?: string;
+    readonly sourceSessionId?: string;
+    readonly reviewedAt?: string;
+    readonly reviewedById?: string;
+    readonly reviewedByName?: string;
+    readonly reviewNote?: string;
+    readonly audit: readonly WorkflowAuditEntry[];
+}
+/** One durable review/publish event. */
+export interface WorkflowAuditEntry {
+    readonly at: string;
+    readonly actorId: string;
+    readonly actorName: string;
+    readonly action: 'published' | 'approved' | 'rejected';
+    readonly note?: string;
+}
+/** The whole file. */
+export interface WorkflowPublishStore {
+    readonly version: 1;
+    readonly workflows: readonly PublishedWorkflow[];
+}
+/** Structured store failure; the HTTP route and the tool both map these. */
+export declare class WorkflowPublishError extends Error {
+    readonly code: 'invalid' | 'not-found' | 'already-reviewed' | 'forbidden' | 'io';
+    readonly name = "WorkflowPublishError";
+    constructor(code: 'invalid' | 'not-found' | 'already-reviewed' | 'forbidden' | 'io', message: string);
+}
+/** The profile-local directory the store lives in. */
+export declare function defaultPublishDir(env?: NodeJS.ProcessEnv): string;
+/** Resolve the configured directory, falling back to the profile-local default. */
+export declare function publishDirOf(configured: string | undefined): string;
+/** The one file in that directory. */
+export declare function publishStorePath(directory: string): string;
+/** Validate and normalize one publish request. */
+export declare function normalizePublishInput(input: WorkflowPublishInput): Required<WorkflowPublishInput>;
+/** Parse a store file, treating absence as empty and quarantining corrupt JSON. */
+export declare function readWorkflowStore(path: string): Promise<WorkflowPublishStore>;
+/** Commit the store atomically (write beside it, then rename). */
+export declare function writeWorkflowStore(path: string, store: WorkflowPublishStore): Promise<void>;
+/** The caller who authors/reviews a record. */
+export interface WorkflowActor {
+    readonly id: string;
+    readonly name: string;
+}
+/** Result of a publish attempt; `duplicate` means the pending record already existed. */
+export interface PublishResult {
+    readonly record: PublishedWorkflow;
+    readonly duplicate: boolean;
+}
+/**
+ * Publish one workflow as pending.
+ *
+ * Deduplication is deliberately scoped to `(normalized title, author, pending)`: a
+ * second model call in the same conversation must not create a second review card, while
+ * a rejected workflow may be resubmitted after edits.
+ */
+export declare function publishWorkflow(path: string, input: WorkflowPublishInput, actor: WorkflowActor, sourceSessionId?: string, now?: () => Date): Promise<PublishResult>;
+/** Update one local record's mutable copy, stamping updatedAt and an audit entry. */
+export declare function updatePublishedWorkflow(path: string, id: string, patch: Partial<Pick<PublishedWorkflow, 'title' | 'description' | 'instruction' | 'cronHint' | 'category' | 'visibility' | 'departmentCode'>>, actor: WorkflowActor, now?: () => Date): Promise<PublishedWorkflow>;
+/** Mark one local workflow unpublished (retained for the owner's history). */
+export declare function unpublishPublishedWorkflow(path: string, id: string, actor: WorkflowActor, now?: () => Date): Promise<PublishedWorkflow>;
+/** Every record authored by one person, newest update first (the mine tab source). */
+export declare function listWorkflowsForAuthor(path: string, authorId: string): Promise<readonly PublishedWorkflow[]>;
+/** Put one rejected/unpublished workflow back into the pending review queue. */
+export declare function resubmitPublishedWorkflow(path: string, id: string, actor: WorkflowActor, now?: () => Date): Promise<PublishedWorkflow>;
+/** Approved workflows, newest first. */
+export declare function listApprovedWorkflows(path: string): Promise<readonly PublishedWorkflow[]>;
+/** Pending workflows for the review tab, oldest first so the queue reads in arrival order. */
+export declare function listPendingWorkflows(path: string): Promise<readonly PublishedWorkflow[]>;
+/** Approve or reject one pending workflow. Rejected records stay in the store. */
+export declare function reviewWorkflow(path: string, id: string, decision: 'approve' | 'reject', actor: WorkflowActor, note?: string, now?: () => Date): Promise<PublishedWorkflow>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sparkelf/dsh-knowledge-base",
-  "version": "0.1.5",
+  "version": "0.1.20",
   "description": "DataOps-backed knowledge base for DeepSeek Harness: a left-sidebar destination, Settings configuration, and index tooling over a mounted NAS view.",
   "type": "module",
   "main": "./lib/index.js",
@@ -43,15 +43,11 @@
     "README.md",
     "LICENSE",
     "SKILL.md",
+    "万相AI使用教程.html",
     "i18n/*.json",
     "skills/**/SKILL.md",
     "skills/**/i18n/*.json"
   ],
-  "scripts": {
-    "build": "rm -rf lib && tsc -p tsconfig.build.json && tsdown",
-    "bundle": "tsdown",
-    "prepack": "pnpm run build"
-  },
   "engines": {
     "node": "^22.19.0 || >=24.0.0"
   },
@@ -107,5 +103,9 @@
     "dsh-better-sidebar": {
       "optional": true
     }
+  },
+  "scripts": {
+    "build": "rm -rf lib && tsc -p tsconfig.build.json && tsdown",
+    "bundle": "tsdown"
   }
-}
+}