@zleap-ai/dsh-sag 0.1.0

package/docs/embedded.md

@@ -0,0 +1,61 @@
+# dsh-sag embedded 模式
+
+embedded 模式面向需要由 DeepSeek Harness 直接启动 `zleap-sag==0.10.0` 引擎的高级部署。普通本机 SAG 用户不需要此模式。
+
+## 准备运行时
+
+需要 Python 3.11+ 和 `uv`。先把插件安装到目标 profile：
+
+```sh
+dsh plugin --profile web add @zleap-ai/dsh-sag
+```
+
+`dsh plugin ... exec` 会在该 profile 的安装目录中运行命令，因此不依赖当前目录存在 `node_modules`：
+
+```sh
+dsh plugin --profile web exec node node_modules/@zleap-ai/dsh-sag/scripts/setup-runtime.mjs --python python3 --target "$HOME/.local/share/dsh-sag"
+```
+
+命令会创建固定版本的 Python 环境，并输出解释器路径。
+
+## 配置
+
+准备 SAG Engine 环境文件，例如 `/etc/dsh-sag/sag.env`。以下三个环境变量分别表示 Python 解释器、SAG 环境文件和允许使用的 namespace：
+
+```sh
+export DSH_SAG_PYTHON="$HOME/.local/share/dsh-sag/dsh-sag-runtime-0.1.0/bin/python"
+export DSH_SAG_ENV_FILE=/etc/dsh-sag/sag.env
+export DSH_SAG_NAMESPACES='[{"id":"product-docs","label":"产品文档"}]'
+```
+
+Harness home 优先使用 `$DSH_HOME`，未设置时是 `~/.dsh`。将下列 patch 写入 `$DSH_HOME/profiles/web/cordis.patch.yml`；如果未设置 `$DSH_HOME`，对应路径是 `~/.dsh/profiles/web/cordis.patch.yml`：
+
+```yaml
+- id: dsh-sag
+  name: '@zleap-ai/dsh-sag'
+  config:
+    mode: embedded
+    pythonCommand: !!js process.env.DSH_SAG_PYTHON
+    envFile: !!js process.env.DSH_SAG_ENV_FILE
+    namespaces: !!js JSON.parse(process.env.DSH_SAG_NAMESPACES)
+    defaultMode: fast
+    maxResults: 20
+    maxReadEngines: 4
+    requestTimeoutMs: 30000
+    shutdownGraceMs: 5000
+```
+
+每个 namespace 的 `id` 必须与 SAG 数据源一致，不能为空、不能重复，最长 36 个 URL-safe 字符。`label` 只用于向用户和模型说明其内容。
+
+## 启动与诊断
+
+插件加载时会检查 Python 可执行文件、环境文件、协议版本、`zleap-sag` 版本、引擎健康状态、证据读取能力和 namespace 列表。任一检查失败都会停止加载，并在 dsh 日志中给出具体原因。
+
+先在不启动服务的情况下检查最终配置，再启动 `web` profile 并观察启动日志：
+
+```sh
+dsh --profile web --dump-config
+dsh web
+```
+
+卸载插件或停止 dsh 时，插件先向 sidecar 发送 `shutdown` 并等待引擎释放资源；超过 `shutdownGraceMs` 后会终止受管进程树。运行中检索超时由 `requestTimeoutMs` 控制。

package/lib/brand.d.ts

@@ -0,0 +1,13 @@
+/** A string whose meaning is a configured SAG namespace. */
+export type SagNamespaceId = string & {
+    readonly __brand: 'SagNamespaceId';
+};
+/** An opaque reference returned by `sag_search` and consumed by `sag_read`. */
+export type SagEvidenceRef = string & {
+    readonly __brand: 'SagEvidenceRef';
+};
+/** Validate and brand a namespace at a wire or configuration boundary. */
+export declare function sagNamespaceId(value: string): SagNamespaceId;
+/** Validate and brand an opaque evidence reference at a wire boundary. */
+export declare function sagEvidenceRef(value: string): SagEvidenceRef;
+//# sourceMappingURL=brand.d.ts.map

package/lib/brand.js

@@ -0,0 +1,15 @@
+/** Validate and brand a namespace at a wire or configuration boundary. */
+export function sagNamespaceId(value) {
+    if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,35}$/.test(value)) {
+        throw new TypeError(`invalid SAG namespace id: ${JSON.stringify(value)}`);
+    }
+    return value;
+}
+/** Validate and brand an opaque evidence reference at a wire boundary. */
+export function sagEvidenceRef(value) {
+    if (!/^[A-Za-z0-9_-]+$/.test(value) || value.length > 4096) {
+        throw new TypeError('invalid SAG evidence reference');
+    }
+    return value;
+}
+//# sourceMappingURL=brand.js.map

package/lib/cli/runtime.d.ts

@@ -0,0 +1,40 @@
+import { discoverConnection } from '../connection/discovery.js';
+import type { SagConnectionManagerDeps } from '../connection/manager.js';
+import { SagConnectionStore } from '../connection/store.js';
+/** Candidate locations used by one non-interactive connection discovery attempt. */
+export interface CliDiscoveryOptions {
+    readonly paths?: readonly string[];
+    readonly urls?: readonly string[];
+}
+/** The live local services consumed by the command-line interface. */
+export interface CliRuntime {
+    readonly store: SagConnectionStore;
+    readonly discovery: {
+        discover(signal: AbortSignal, options?: CliDiscoveryOptions): ReturnType<typeof discoverConnection>;
+    };
+    readonly inspect?: SagConnectionManagerDeps['inspect'];
+    dispose(): Promise<void>;
+}
+/** One initialized Cordis layer that can release its owned resources. */
+export interface CliRuntimeLayer {
+    dispose(): Promise<void>;
+}
+/** Layer startup operations for the short-lived CLI runtime. */
+export interface CliRuntimeLayerFactory {
+    startSettings(): Promise<CliRuntimeLayer>;
+    startCredentials(): Promise<CliRuntimeLayer>;
+    startRegistration(): Promise<{
+        readonly layer: CliRuntimeLayer;
+        readonly store: SagConnectionStore;
+    }>;
+}
+/** Settings store and reverse-order disposer created from initialized runtime layers. */
+export interface CliRuntimeLifecycle {
+    readonly store: SagConnectionStore;
+    dispose(): Promise<void>;
+}
+/** Start nested runtime layers and guarantee every initialized layer is released in reverse order. */
+export declare function startCliRuntime(factory: CliRuntimeLayerFactory): Promise<CliRuntimeLifecycle>;
+/** Start short-lived local settings and credential providers under the shared DSH home. */
+export declare function createCliRuntime(): Promise<CliRuntime>;
+//# sourceMappingURL=runtime.d.ts.map

package/lib/cli/runtime.js

@@ -0,0 +1,121 @@
+import { readFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { resolve } from 'node:path';
+import { Context } from '@deepseek-ai/cordis';
+import { LocalCredentialProvider } from '@deepseek-ai/dsh-credentials-local';
+import { FileSettingsProvider } from '@deepseek-ai/dsh-settings-file';
+import { resolveConfig } from '../config.js';
+import { discoverConnection, platformConnectionPaths } from '../connection/discovery.js';
+import { SagConnectionStore, registerSagSettings } from '../connection/store.js';
+function runtimeFileSystem() {
+    return {
+        async resolve(path) {
+            const filename = resolve(path);
+            return { targetKey: filename, displayPath: filename };
+        },
+        async readText(target, signal) {
+            if (signal?.aborted)
+                throw signal.reason;
+            return readFile(target.displayPath, 'utf8');
+        },
+    };
+}
+async function disposalFailures(layers) {
+    const failures = [];
+    for (const layer of [...layers].reverse()) {
+        try {
+            await layer.dispose();
+        }
+        catch (error) {
+            failures.push(error);
+        }
+    }
+    return failures;
+}
+function throwDisposalFailures(failures) {
+    if (failures.length === 0)
+        return;
+    if (failures.length === 1)
+        throw failures[0];
+    throw new AggregateError(failures, 'dsh-sag: multiple CLI runtime disposal failures');
+}
+/** Start nested runtime layers and guarantee every initialized layer is released in reverse order. */
+export async function startCliRuntime(factory) {
+    const layers = [];
+    let store;
+    try {
+        layers.push(await factory.startSettings());
+        layers.push(await factory.startCredentials());
+        const registration = await factory.startRegistration();
+        layers.push(registration.layer);
+        store = registration.store;
+    }
+    catch (error) {
+        const failures = await disposalFailures(layers);
+        if (failures.length === 0)
+            throw error;
+        throw new AggregateError([error, ...failures], 'dsh-sag: CLI runtime startup and disposal failed');
+    }
+    return {
+        store: store,
+        async dispose() {
+            throwDisposalFailures(await disposalFailures(layers));
+        },
+    };
+}
+async function activatedLayer(factory) {
+    const layer = factory();
+    try {
+        await layer;
+        return layer;
+    }
+    catch (error) {
+        const failures = await disposalFailures([layer]);
+        if (failures.length === 0)
+            throw error;
+        throw new AggregateError([error, ...failures], 'dsh-sag: CLI runtime layer startup and disposal failed');
+    }
+}
+/** Start short-lived local settings and credential providers under the shared DSH home. */
+export async function createCliRuntime() {
+    const ctx = new Context();
+    const dshHome = process.env.DSH_HOME;
+    const providerConfig = { watch: false, ...(dshHome === undefined ? {} : { dshHome }) };
+    const lifecycle = await startCliRuntime({
+        startSettings: () => activatedLayer(() => ctx.plugin(FileSettingsProvider, providerConfig)),
+        startCredentials: () => activatedLayer(() => ctx.plugin(LocalCredentialProvider, providerConfig)),
+        async startRegistration() {
+            let store;
+            const layer = await activatedLayer(() => ctx.plugin({
+                inject: ['settings', 'credentials'],
+                apply(child) {
+                    store = new SagConnectionStore({ credentials: child.credentials, settings: registerSagSettings(child) });
+                },
+            }));
+            if (store === undefined) {
+                await layer.dispose();
+                throw new Error('dsh-sag: local settings runtime did not start');
+            }
+            return { layer, store };
+        },
+    });
+    const fs = runtimeFileSystem();
+    const defaults = resolveConfig({});
+    if (defaults.mode !== 'local')
+        throw new Error('dsh-sag: local discovery defaults are unavailable');
+    return {
+        store: lifecycle.store,
+        discovery: {
+            discover(signal, options = {}) {
+                return discoverConnection({
+                    fs,
+                    paths: options.paths ?? platformConnectionPaths(process.env, process.platform, homedir()),
+                    urls: options.urls ?? defaults.discoveryUrls,
+                    fetch: (url, init) => fetch(url, init),
+                }, signal);
+            },
+        },
+        dispose: lifecycle.dispose,
+    };
+}
+//# sourceMappingURL=runtime.js.map

package/lib/cli.d.ts

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+import { type CliRuntime } from './cli/runtime.js';
+export type { CliRuntime } from './cli/runtime.js';
+/** Minimal output ports for the reusable command-line entry point. */
+export interface CliIo {
+    stdout(line: string): void;
+    stderr(line: string): void;
+}
+/** Injectable process boundaries for focused command-line tests. */
+export interface CliDependencies {
+    createRuntime(): Promise<CliRuntime>;
+    readFile?(path: string, encoding: 'utf8'): Promise<string>;
+    homedir?(): string;
+    /** Testable hard deadline for one complete connection check. */
+    requestTimeoutMs?: number;
+}
+/** Run setup, doctor, or help with no prompts and an explicit process exit code. */
+export declare function runCli(argv: readonly string[], io: CliIo, dependencies?: CliDependencies): Promise<number>;
+/** Detect direct execution after resolving npm/pnpm bin symlinks without firing when this module is imported. */
+export declare function isDirectCliEntry(moduleUrl: string, argvEntry: string | undefined, resolveRealPath?: (path: string) => string): boolean;
+//# sourceMappingURL=cli.d.ts.map

package/lib/cli.js

@@ -0,0 +1,265 @@
+#!/usr/bin/env node
+import { realpathSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { parseArgs } from 'node:util';
+import { parseConnectionDescriptor } from './connection/descriptor.js';
+import { SAG_SETUP_COMMAND } from './connection/guidance.js';
+import { SagConnectionManager, } from './connection/manager.js';
+import { createCliRuntime } from './cli/runtime.js';
+const HELP = `用法：
+  dsh-sag setup
+  dsh-sag setup --url <SAG 本机地址>
+  dsh-sag setup <SAG 导出文件>
+  dsh-sag doctor
+`;
+const RECOVERY = `请启动 SAG 后重试；也可运行 ${SAG_SETUP_COMMAND} 重新发现。\n`;
+function usage(io, message) {
+    if (message !== undefined)
+        io.stderr(`${message}\n`);
+    io.stderr(HELP);
+    return 2;
+}
+function parse(argv, io) {
+    let result;
+    try {
+        result = parseArgs({
+            args: argv,
+            options: {
+                help: { type: 'boolean', short: 'h' },
+                url: { type: 'string' },
+            },
+            allowPositionals: true,
+            strict: false,
+        });
+    }
+    catch {
+        return usage(io, '参数无效。');
+    }
+    const keys = Object.keys(result.values);
+    if (keys.some(key => key !== 'help' && key !== 'url'))
+        return usage(io, '参数无效。');
+    if (result.values.help === true)
+        return result.positionals.length === 0 && keys.length === 1 ? { kind: 'help' } : usage(io, '参数无效。');
+    const [command, ...positionals] = result.positionals;
+    if (command === 'doctor' && positionals.length === 0 && keys.length === 0)
+        return { kind: 'doctor' };
+    if (command !== 'setup')
+        return usage(io, '参数无效。');
+    const url = result.values.url;
+    if (url !== undefined && (typeof url !== 'string' || positionals.length !== 0))
+        return usage(io, '参数无效。');
+    if (url === undefined && positionals.length > 1)
+        return usage(io, '参数无效。');
+    if (url !== undefined) {
+        try {
+            const parsed = new URL(url);
+            if ((parsed.protocol !== 'http:' && parsed.protocol !== 'https:') || parsed.username || parsed.password)
+                throw new Error('invalid URL');
+        }
+        catch {
+            return usage(io, 'SAG 地址必须是没有用户名或密码的 HTTP(S) 地址。');
+        }
+        return { kind: 'setup', url };
+    }
+    return { kind: 'setup', ...(positionals[0] === undefined ? {} : { path: positionals[0] }) };
+}
+function expandHome(path, getHome) {
+    if (path === '~')
+        return getHome();
+    if (path.startsWith('~/') || path.startsWith('~\\'))
+        return `${getHome()}${path.slice(1)}`;
+    return path;
+}
+function redactedMessage(error, secrets = []) {
+    const message = typeof error === 'string' ? error : error instanceof Error ? error.message : '未知错误';
+    return secrets.reduce((value, secret) => secret ? value.split(secret).join('<redacted>') : value, message)
+        .replace(/Bearer\s+[^\s,;]+/giu, 'Bearer <redacted>')
+        .replace(/([?&](?:access_)?token=)[^&#\s]+/giu, '$1<redacted>')
+        .replace(/(\/\/)[^/@\s]+@/gu, '$1<redacted>@');
+}
+function diagnostic(report, io) {
+    if (report.status !== 'ready') {
+        io.stderr(`SAG 未就绪：${report.status}\n`);
+        for (const error of report.errors ?? [])
+            io.stderr(`- ${redactedMessage(error)}\n`);
+        for (const item of report.discovery?.diagnostics ?? [])
+            io.stderr(`- ${redactedMessage(item.action)}\n`);
+        return;
+    }
+    io.stdout('SAG 已连接。\n');
+    io.stdout(`健康检查：${report.health ? '正常' : '失败'}；就绪检查：${report.ready ? '通过' : '失败'}。\n`);
+    io.stdout(`知识源：${report.sourceCount} 个。\n`);
+    if (report.capabilities !== undefined) {
+        if (report.capabilities.upload !== undefined) {
+            io.stdout(`文件上传：最多 ${report.capabilities.upload.maxMb} MiB；支持 ${report.capabilities.upload.extensions.join('、')}。\n`);
+        }
+        else {
+            io.stdout('文件上传：当前 SAG 未提供。\n');
+        }
+    }
+}
+function setupDiscovery(descriptor) {
+    return { source: 'file', descriptor, diagnostics: [] };
+}
+function setupManager(runtime, discover, requestTimeoutMs) {
+    const deps = {
+        store: {
+            load: async () => undefined,
+        },
+        discover,
+        ...(runtime.inspect === undefined ? {} : { inspect: runtime.inspect }),
+        ...(requestTimeoutMs === undefined ? {} : { requestTimeoutMs }),
+    };
+    return new SagConnectionManager(deps);
+}
+async function runSetup(command, runtime, io, dependencies, rememberSecret) {
+    const controller = new AbortController();
+    let discover;
+    if (command.path !== undefined) {
+        const filename = expandHome(command.path, dependencies.homedir ?? homedir);
+        let descriptor;
+        try {
+            descriptor = parseConnectionDescriptor(JSON.parse(await (dependencies.readFile ?? readFile)(filename, 'utf8')));
+        }
+        catch (error) {
+            io.stderr(`无法读取 SAG 导出文件：${redactedMessage(error)}\n`);
+            return 1;
+        }
+        discover = async () => setupDiscovery(descriptor);
+    }
+    else if (command.url !== undefined) {
+        discover = signal => runtime.discovery.discover(signal, { paths: [], urls: [command.url] });
+    }
+    else {
+        discover = signal => runtime.discovery.discover(signal);
+    }
+    let report;
+    try {
+        report = await setupManager(runtime, discover, dependencies.requestTimeoutMs).ensureConnected(controller.signal);
+    }
+    catch (error) {
+        io.stderr(`连接 SAG 失败：${redactedMessage(error)}\n`);
+        return 1;
+    }
+    if (report.status !== 'ready') {
+        diagnostic(report, io);
+        io.stderr(RECOVERY);
+        return 1;
+    }
+    if (report.descriptor === undefined) {
+        io.stderr('SAG 连接缺少可保存的连接描述。\n');
+        return 1;
+    }
+    rememberSecret(report.descriptor.accessToken);
+    try {
+        await runtime.store.save(report.descriptor);
+    }
+    catch (error) {
+        io.stderr(`保存 SAG 配置失败：${redactedMessage(error, [report.descriptor.accessToken])}\n`);
+        return 1;
+    }
+    diagnostic(report, io);
+    return runDoctor(runtime, io, dependencies.requestTimeoutMs);
+}
+async function runDoctor(runtime, io, requestTimeoutMs) {
+    let report;
+    try {
+        report = await new SagConnectionManager({
+            store: runtime.store,
+            discover: signal => runtime.discovery.discover(signal),
+            ...(runtime.inspect === undefined ? {} : { inspect: runtime.inspect }),
+            ...(requestTimeoutMs === undefined ? {} : { requestTimeoutMs }),
+        }).doctor(new AbortController().signal);
+    }
+    catch (error) {
+        let secrets = [];
+        try {
+            const saved = await runtime.store.load();
+            if (saved !== undefined)
+                secrets = [saved.accessToken];
+        }
+        catch {
+            // The original diagnostic remains the actionable failure.
+        }
+        io.stderr(`SAG 检查失败：${redactedMessage(error, secrets)}\n`);
+        return 1;
+    }
+    diagnostic(report, io);
+    if (report.status === 'ready')
+        return 0;
+    if (report.status === 'not-found')
+        io.stderr(RECOVERY);
+    return 1;
+}
+/** Run setup, doctor, or help with no prompts and an explicit process exit code. */
+export async function runCli(argv, io, dependencies = { createRuntime: createCliRuntime }) {
+    const command = parse(argv, io);
+    if (typeof command === 'number')
+        return command;
+    if (command.kind === 'help') {
+        io.stdout(HELP);
+        return 0;
+    }
+    let runtime;
+    let code = 1;
+    let secrets = [];
+    try {
+        runtime = await dependencies.createRuntime();
+        try {
+            const saved = await runtime.store.load();
+            if (saved !== undefined)
+                secrets = [saved.accessToken];
+        }
+        catch {
+            // The command reports saved configuration failures through its connection manager.
+        }
+        code = command.kind === 'setup'
+            ? await runSetup(command, runtime, io, dependencies, secret => { secrets = [...secrets, secret]; })
+            : await runDoctor(runtime, io, dependencies.requestTimeoutMs);
+    }
+    catch (error) {
+        io.stderr(`dsh-sag 失败：${redactedMessage(error, secrets)}\n`);
+        code = 1;
+    }
+    finally {
+        if (runtime !== undefined) {
+            try {
+                await runtime.dispose();
+            }
+            catch (error) {
+                try {
+                    const saved = await runtime.store.load();
+                    if (saved !== undefined)
+                        secrets = [...secrets, saved.accessToken];
+                }
+                catch {
+                    // Cleanup reporting must continue even when the backing store is unavailable.
+                }
+                io.stderr(`清理 dsh-sag 运行环境失败：${redactedMessage(error, secrets)}\n`);
+                code = 1;
+            }
+        }
+    }
+    return code;
+}
+/** Detect direct execution after resolving npm/pnpm bin symlinks without firing when this module is imported. */
+export function isDirectCliEntry(moduleUrl, argvEntry, resolveRealPath = realpathSync) {
+    if (argvEntry === undefined)
+        return false;
+    try {
+        return resolveRealPath(argvEntry) === fileURLToPath(moduleUrl);
+    }
+    catch {
+        return false;
+    }
+}
+if (isDirectCliEntry(import.meta.url, process.argv[1])) {
+    const code = await runCli(process.argv.slice(2), {
+        stdout: line => process.stdout.write(line),
+        stderr: line => process.stderr.write(line),
+    });
+    process.exitCode = code;
+}
+//# sourceMappingURL=cli.js.map

package/lib/config.d.ts

@@ -0,0 +1,60 @@
+import z from '@deepseek-ai/schemastery';
+import { type SagNamespaceId } from './brand.js';
+import type { SupervisorConfig } from './runtime/supervisor.js';
+export interface NamespaceConfig {
+    readonly id: string;
+    readonly label: string;
+}
+interface ExistingSidecarConfig {
+    readonly pythonCommand: string;
+    readonly envFile: string;
+    readonly cwd?: string;
+    readonly namespaces: readonly NamespaceConfig[];
+    readonly defaultMode?: 'fast' | 'precise';
+    readonly maxResults?: number;
+    readonly maxSnippetChars?: number;
+    readonly maxReadChars?: number;
+    readonly maxReadEngines?: number;
+    readonly requestTimeoutMs?: number;
+    readonly shutdownGraceMs?: number;
+    readonly allowDegraded?: boolean;
+}
+/** Connect to an already-running local SAG server. */
+export interface LocalConfig {
+    readonly mode?: 'local';
+    readonly discoveryUrls?: readonly string[];
+    readonly requestTimeoutMs?: number;
+    readonly maxUploadBytes?: number;
+    readonly maxReadChars?: number;
+    readonly connectionCacheTtlMs?: number;
+}
+/** Run the legacy Python sidecar directly. */
+export interface EmbeddedConfig extends ExistingSidecarConfig {
+    readonly mode: 'embedded';
+}
+/** Loader-facing plugin configuration. Local mode is the default. */
+export type Config = LocalConfig | EmbeddedConfig;
+export declare const Config: z<Config>;
+export interface ResolvedNamespaceConfig {
+    readonly id: SagNamespaceId;
+    readonly label: string;
+}
+export interface ResolvedLocalConfig {
+    readonly mode: 'local';
+    readonly discoveryUrls: readonly string[];
+    readonly requestTimeoutMs: number;
+    readonly maxUploadBytes: number;
+    readonly maxReadChars: number;
+    readonly connectionCacheTtlMs: number;
+}
+export interface ResolvedEmbeddedConfig extends SupervisorConfig {
+    readonly mode: 'embedded';
+    readonly namespaces: readonly ResolvedNamespaceConfig[];
+    readonly defaultMode: 'fast' | 'precise';
+    readonly requestTimeoutMs: number;
+}
+export type ResolvedConfig = ResolvedLocalConfig | ResolvedEmbeddedConfig;
+/** Apply and validate every default before a local client or sidecar observes config. */
+export declare function resolveConfig(config: Config): ResolvedConfig;
+export {};
+//# sourceMappingURL=config.d.ts.map