dsh-plugin-dbgraph-tool 0.0.0-stage → 0.1.0

package/lib/command.d.ts

@@ -0,0 +1,86 @@
+/**
+ * The human `/dbgraph` slash command.
+ *
+ * The model-facing tools answer the same questions, but a person at the composer should not have to
+ * spend a model turn asking "what is indexed?". This command runs directly against `ctx.dbgraph` in
+ * the UI's command plane: nothing it returns becomes a model message or a token.
+ *
+ * Registered through conditional injection (`ctx.inject(['commands'], …)`) for the same reason the
+ * model-facing tools are not: the command registry is a host composition choice, and its absence
+ * must not hide the tools this plugin also registers. `@deepseek-ai/dsh-commands` is deliberately
+ * not imported — the service may be absent, so its public shape is mirrored structurally here.
+ * @module dsh-plugin-dbgraph-tool/command
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Command name, without the leading slash. */
+export declare const COMMAND_NAME = "dbgraph";
+/** One-line discovery copy the UI shows in its command list. */
+export declare const COMMAND_DESCRIPTION = "\u67E5\u770B\u6216\u91CD\u5EFA\u672C\u5730\u6570\u636E\u5E93\u7ED3\u6784\u7D22\u5F15\uFF08status / index / connections\uFF09";
+/** Input syntax the UI shows after the command name. */
+export declare const COMMAND_INPUT_HINT = "[status|index [--connection <id>] [--mode l1|l2|full]|connections]";
+/** The usage line every rejection repeats, so one screen never offers half an answer. */
+export declare const COMMAND_USAGE = "\u7528\u6CD5\uFF1A/dbgraph [status|index [--connection <id>] [--mode l1|l2|full]|connections]";
+/**
+ * Branded identity of this definition, mirroring `CommandDefinitionId` from
+ * `@deepseek-ai/dsh-commands/brand` without importing it.
+ *
+ * The registry treats the value as an opaque string; the local brand only keeps a plain string from
+ * being passed where a stable definition identity is meant.
+ */
+export type CommandDefinitionId = string & {
+    readonly __commandDefinitionId: 'CommandDefinitionId';
+};
+/** Stable identity, independent of the display name or the UI's per-run id. */
+export declare const COMMAND_DEFINITION_ID: CommandDefinitionId;
+/** What a handler settles with; mirrors the registry's `success | error` result. */
+export type CommandResult = {
+    readonly kind: 'success';
+    readonly text?: string;
+} | {
+    readonly kind: 'error';
+    readonly text: string;
+};
+/**
+ * The invocation face a command handler receives, declared structurally — only the members this
+ * command reads.
+ */
+export interface CommandInvocation {
+    /** Everything after the command name, including its leading separator whitespace. */
+    readonly rawInput: string;
+    /** UI request cancellation, forwarded to every seam call. */
+    readonly signal?: AbortSignal;
+}
+/** One command registration, as the registry's `register` takes it. */
+export interface CommandDefinition {
+    /** Stable plugin-namespaced identity. */
+    readonly definitionId: CommandDefinitionId;
+    /** Lowercase command name, without the slash. */
+    readonly name: string;
+    /** Discovery copy, shown in the UI's command list. */
+    readonly description: string;
+    /** Input syntax shown after the name. */
+    readonly input: {
+        readonly hint: string;
+    };
+    /**
+     * Run the command.
+     * @param invocation - the accepted command line and its context.
+     * @returns the settled result the UI renders.
+     */
+    readonly handler: (invocation: CommandInvocation) => CommandResult | Promise<CommandResult>;
+}
+/** The command registry's registration surface, declared structurally. */
+export interface CommandRegistry {
+    /**
+     * Register one command definition.
+     * @param definition - discovery metadata and handler.
+     * @returns the disposer unregistering it.
+     */
+    register(definition: CommandDefinition): () => void;
+}
+/**
+ * Register the `/dbgraph` command when the host composition provides a command registry.
+ * @param ctx - the plugin context (must carry `dbgraph`; `commands` is optional).
+ */
+export declare function registerCommands(ctx: Context): void;
+//# sourceMappingURL=command.d.ts.map

package/lib/command.js

@@ -0,0 +1,186 @@
+/**
+ * The human `/dbgraph` slash command.
+ *
+ * The model-facing tools answer the same questions, but a person at the composer should not have to
+ * spend a model turn asking "what is indexed?". This command runs directly against `ctx.dbgraph` in
+ * the UI's command plane: nothing it returns becomes a model message or a token.
+ *
+ * Registered through conditional injection (`ctx.inject(['commands'], …)`) for the same reason the
+ * model-facing tools are not: the command registry is a host composition choice, and its absence
+ * must not hide the tools this plugin also registers. `@deepseek-ai/dsh-commands` is deliberately
+ * not imported — the service may be absent, so its public shape is mirrored structurally here.
+ * @module dsh-plugin-dbgraph-tool/command
+ */
+import { DBGRAPH_INDEX_MODES, DBGRAPH_INDEX_WRITERS } from "./schema.js";
+import { dbgraphRoot } from "./prompt.js";
+import { describeIndexState } from "./render.js";
+/** Command name, without the leading slash. */
+export const COMMAND_NAME = 'dbgraph';
+/** One-line discovery copy the UI shows in its command list. */
+export const COMMAND_DESCRIPTION = '查看或重建本地数据库结构索引（status / index / connections）';
+/** Input syntax the UI shows after the command name. */
+export const COMMAND_INPUT_HINT = '[status|index [--connection <id>] [--mode l1|l2|full]|connections]';
+/** The usage line every rejection repeats, so one screen never offers half an answer. */
+export const COMMAND_USAGE = `用法：/${COMMAND_NAME} ${COMMAND_INPUT_HINT}`;
+/** Brand one plugin-namespaced command identity. */
+function commandDefinitionId(value) {
+    return value;
+}
+/** Stable identity, independent of the display name or the UI's per-run id. */
+export const COMMAND_DEFINITION_ID = commandDefinitionId('dsh-plugin-dbgraph/command/dbgraph');
+/**
+ * Register the `/dbgraph` command when the host composition provides a command registry.
+ * @param ctx - the plugin context (must carry `dbgraph`; `commands` is optional).
+ */
+export function registerCommands(ctx) {
+    try {
+        ctx.inject(['commands'], child => {
+            const commands = child.commands;
+            child.effect(() => commands.register({
+                definitionId: COMMAND_DEFINITION_ID,
+                name: COMMAND_NAME,
+                description: COMMAND_DESCRIPTION,
+                input: { hint: COMMAND_INPUT_HINT },
+                handler: invocation => runCommand(ctx, invocation),
+            }), 'dbgraph: slash command');
+        });
+    }
+    catch (error) {
+        console.warn('[dbgraph] commands service unavailable; /dbgraph is not registered:', error);
+    }
+}
+/**
+ * Parse and dispatch one invocation.
+ *
+ * A handler that throws makes the registry settle the command as an error from the thrown value
+ * instead of from a result, so every expected failure is returned as `kind: 'error'` here; only a
+ * defect escapes, and it still surfaces as the command's error.
+ * @param ctx - the plugin context carrying `dbgraph`.
+ * @param invocation - the accepted command line and its context.
+ * @returns the settled result.
+ */
+async function runCommand(ctx, invocation) {
+    const words = invocation.rawInput.trim() === '' ? [] : invocation.rawInput.trim().split(/\s+/u);
+    const [subcommand = 'status', ...rest] = words;
+    try {
+        switch (subcommand) {
+            case 'status':
+                return await statusCommand(ctx);
+            case 'connections':
+                return await connectionsCommand(ctx);
+            case 'index':
+                return await indexCommand(ctx, rest, invocation.signal);
+            default:
+                return { kind: 'error', text: `未知的子命令 "${subcommand}"。${COMMAND_USAGE}` };
+        }
+    }
+    catch (error) {
+        return { kind: 'error', text: String(error) };
+    }
+}
+/** The connection target clause: host and database, when the connection names them. */
+function targetOf(connection) {
+    const parts = [];
+    if (connection.host !== undefined)
+        parts.push(connection.host);
+    if (connection.database !== undefined)
+        parts.push(connection.database);
+    return parts.length === 0 ? '' : ` ${parts.join('/')}`;
+}
+/** One connection as a line: id, label, engine, target, index state, credential state. */
+function connectionLine(connection) {
+    const label = connection.label === undefined ? '' : ` "${connection.label}"`;
+    const credential = connection.credentialConfigured ? '' : '（凭据未配置）';
+    return `${connection.id}${label} (${connection.engine})${targetOf(connection)} — `
+        + `${describeIndexState(connection.index)}${credential}`;
+}
+/** Report every configured connection's index at a glance. */
+async function statusCommand(ctx) {
+    const root = ctx.dbgraph.storeRoot ?? dbgraphRoot();
+    const connections = await ctx.dbgraph.listConnections();
+    if (connections.length === 0) {
+        return {
+            kind: 'success',
+            text: `还没有配置连接。索引根：${root}\n在 ${root}/connections.json 里添加连接后运行 /${COMMAND_NAME} index。`,
+        };
+    }
+    const lines = [`索引根：${root}`, ...connections.map(connectionLine)];
+    return { kind: 'success', text: lines.join('\n') };
+}
+/** List the connections without their index state — what the model passes as `--connection`. */
+async function connectionsCommand(ctx) {
+    const connections = await ctx.dbgraph.listConnections();
+    if (connections.length === 0)
+        return { kind: 'success', text: '还没有配置连接。' };
+    const lines = connections.map(connection => `${connection.id} (${connection.engine})${targetOf(connection)}`);
+    return { kind: 'success', text: lines.join('\n') };
+}
+/**
+ * Build or refresh an index right now.
+ *
+ * Unlike the model-facing tool this never moves to a background job: a human ran a command and is
+ * waiting for its answer, and the command plane has no `job_output` equivalent to read later.
+ * @param ctx - the plugin context carrying `dbgraph`.
+ * @param words - the subcommand's arguments.
+ * @param signal - stops the run.
+ * @returns the completed run's summary, or why the arguments are unusable.
+ */
+async function indexCommand(ctx, words, signal) {
+    const parsed = parseIndexFlags(words);
+    if ('error' in parsed)
+        return { kind: 'error', text: `${parsed.error}。${COMMAND_USAGE}` };
+    const report = await ctx.dbgraph.index(parsed.request, signal);
+    const lines = [
+        `已索引 ${report.connection}（${report.level}）：${report.objects} 对象 / ${report.columns} 列 / `
+            + `${report.edges} 关系，${report.terms} 检索词，writer ${report.writer}，${report.elapsedMs} ms。`,
+    ];
+    if (report.warnings.length > 0)
+        lines.push(...report.warnings.map(warning => `警告：${warning}`));
+    return { kind: 'success', text: lines.join('\n') };
+}
+/**
+ * Parse `index`'s flags.
+ * @param words - the argument words after `index`.
+ * @returns the request, or one message naming the unusable argument.
+ */
+function parseIndexFlags(words) {
+    let connection;
+    let mode = 'full';
+    let writer;
+    for (let index = 0; index < words.length; index += 1) {
+        const word = words[index];
+        const next = words[index + 1];
+        switch (word) {
+            case '--connection':
+                if (next === undefined || next.trim() === '')
+                    return { error: '--connection 需要一个连接 id' };
+                connection = next;
+                index += 1;
+                break;
+            case '--mode':
+                if (next === undefined || !DBGRAPH_INDEX_MODES.includes(next)) {
+                    return { error: `--mode 只能是 ${DBGRAPH_INDEX_MODES.join(' / ')}` };
+                }
+                mode = next;
+                index += 1;
+                break;
+            case '--writer':
+                if (next === undefined || !DBGRAPH_INDEX_WRITERS.includes(next)) {
+                    return { error: `--writer 只能是 ${DBGRAPH_INDEX_WRITERS.join(' / ')}` };
+                }
+                writer = next;
+                index += 1;
+                break;
+            default:
+                return { error: `未知参数 "${word}"` };
+        }
+    }
+    return {
+        request: {
+            ...connection === undefined ? {} : { connection },
+            mode,
+            ...writer === undefined ? {} : { writer },
+        },
+    };
+}
+//# sourceMappingURL=command.js.map

package/lib/index.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Model-facing `dbgraph` tool family over `ctx.dbgraph`.
+ *
+ * Two tools, deliberately separate. `dbgraph` is the read side, with the eight operations the seam
+ * answers directly; `dbgraph_index` builds or refreshes the on-disk index on explicit request. They
+ * are separate because `defineTool`'s `timeoutMs` is fixed per registration, not per call: a query
+ * is milliseconds and an index build is minutes, so one budget cannot fit both.
+ *
+ * The plugin also owns the system-prompt section that carries the schema digest. That section's
+ * `text` is a function, not a string: the host re-evaluates it on every assembly, which is what lets
+ * the model learn which tables exist for free instead of spending a discovery round-trip. The
+ * function reads a small JSON sidecar synchronously — opening SQLite, or reaching a server, from an
+ * assembly would tax every request.
+ *
+ * The tools own every default the seam refuses to guess — result limits, prompt budgets, the
+ * background-index threshold — so the seam's requests stay fully specified and a deployment can
+ * retune the model's answer size without touching a store. The `/dbgraph` command attaches through
+ * conditional injection instead, so a host without a command registry still gets the tool family.
+ *
+ * Namespace plugin (named exports, no default export).
+ * @module dsh-plugin-dbgraph-tool
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { IndexReport } from 'dsh-plugin-dbgraph-service';
+import type { DbgraphIndexToolValue, DbgraphToolArgs } from './schema.ts';
+export { renderDbgraph, renderDbgraphIndex } from './render.ts';
+export { DBGRAPH_INDEX_MODES, DBGRAPH_INDEX_OUTPUT_SCHEMA, DBGRAPH_INDEX_PARAMETERS, DBGRAPH_INDEX_WRITERS, DBGRAPH_OPERATIONS, DBGRAPH_OUTPUT_SCHEMA, DBGRAPH_PARAMETERS, type DbgraphIndexToolArgs, type DbgraphIndexToolValue, type DbgraphToolArgs, type DbgraphToolOperation, type DbgraphToolValue, type DbgraphValueFor, } from './schema.ts';
+export { COMMAND_DEFINITION_ID, COMMAND_DESCRIPTION, COMMAND_INPUT_HINT, COMMAND_NAME, COMMAND_USAGE, registerCommands, } from './command.ts';
+export type { CommandDefinition, CommandDefinitionId, CommandInvocation, CommandRegistry, CommandResult } from './command.ts';
+export { DBGRAPH_PROMPT_TEXT, DEFAULT_MAX_PROMPT_CHARS, DEFAULT_MAX_PROMPT_TABLES, dbgraphPromptHint, dbgraphRoot, formatAge, readIndexDirectories, readStatusFile, renderStatusDigest, } from './prompt.ts';
+export type { DigestLimits, PromptHintOptions } from './prompt.ts';
+/** Cordis plugin name for loader diagnostics. */
+export declare const name = "tool-dbgraph";
+/** Services required by this plugin. */
+export declare const inject: string[];
+/** Default tool-call timeout budget (ms) for the query-side `dbgraph` tool. */
+export declare const DEFAULT_DBGRAPH_TOOL_TIMEOUT_MS = 30000;
+/** Default timeout budget (ms) for `dbgraph_index`. Building an index is a different order of work than a query. */
+export declare const DEFAULT_DBGRAPH_INDEX_TIMEOUT_MS = 300000;
+/** Objects per connection past which an index run moves to a background job under `backgroundIndex: 'auto'`. */
+export declare const DEFAULT_BACKGROUND_INDEX_THRESHOLD = 500;
+/** Rows a `find` or `sql` call returns when the model names no `limit`. */
+export declare const DEFAULT_TOOL_LIMIT = 50;
+/** Largest `limit` honored, whatever the model asks for. */
+export declare const DEFAULT_MAX_TOOL_LIMIT = 200;
+/** Plugin configuration: the defaults and caps the seam requires the consumer to own. */
+export interface Config {
+    /** Rows returned when the model names no `limit` (default 50). */
+    defaultLimit?: number;
+    /** Largest `limit` honored (default 200). */
+    maxLimit?: number;
+    /** Objects the prompt digest lists at most, across all connections (default 40). */
+    maxPromptTables?: number;
+    /** Characters the prompt digest may occupy (default 6000). */
+    maxPromptChars?: number;
+    /** Hours after which the digest marks the index stale (default 6, the seam's default). */
+    indexStaleHours?: number;
+    /** Whether to register the system-prompt section (default true). Off hides the digest, not the tools. */
+    prompt?: boolean;
+    /**
+     * Whether an index run moves to the host's background-job registry: `'auto'` (default) decides by
+     * the connection's last indexed object count, `true` always uses a job when the host offers one,
+     * and `false` always runs synchronously inside the tool call.
+     */
+    backgroundIndex?: 'auto' | boolean;
+    /** Objects the last index must have covered before `'auto'` uses a job (default 500). */
+    backgroundIndexThreshold?: number;
+    /** Tool-call timeout budget in ms for the query-side `dbgraph` tool (default 30000). */
+    timeoutMs?: number;
+    /** Tool-call timeout budget in ms for `dbgraph_index` (default 300000). */
+    indexTimeoutMs?: number;
+}
+/** Every configuration field with its default applied. */
+export type ResolvedConfig = Required<Config>;
+/**
+ * Apply every default and reject a value that would fail at call time instead.
+ * @param config - the deployment's configuration.
+ * @returns the resolved configuration.
+ */
+export declare function resolveConfig(config?: Config): ResolvedConfig;
+/**
+ * Register the two model-facing tools, their system-prompt section, and the `/dbgraph` command.
+ * @param ctx - the plugin context (must inject `tools`, `dbgraph`, `systemPrompt`).
+ * @param config - the plugin configuration, or a partial one.
+ */
+export declare function apply(ctx: Context, config?: Config): void;
+/**
+ * The one-line label a pending call shows.
+ * @param args - the validated tool arguments.
+ * @returns the card title naming the operation and whichever subject the operation takes.
+ */
+export declare function callTitle(args: DbgraphToolArgs): string;
+/** Project every finished index run onto the model-facing field names. */
+export declare function completedIndexValue(reports: readonly IndexReport[]): DbgraphIndexToolValue;
+//# sourceMappingURL=index.d.ts.map