@dobby.ai/dobby 0.3.0 → 0.4.0

package/README.md

@@ -192,6 +192,12 @@ dobby config schema show <contributionId> [--json]
 
 配置变更建议直接编辑 `gateway.json`，再通过 `dobby doctor` 或 `dobby start` 做校验。
 
+连接器状态：
+
+```bash
+dobby connector status [connectorId] [--json]
+```
+
 扩展管理：
 
 ```bash
@@ -397,6 +403,8 @@ npm run start -- cron add daily-report \
 - 所有 connector 都会经过宿主侧 health supervisor 包装
   - 统一暴露 `starting / ready / degraded / reconnecting / failed / stopped` 状态
   - 若 connector 长时间停留在 `starting`、`degraded`、`reconnecting` 或 `failed`，宿主会 stop 并重建实例
+- 运行中的 gateway 会把 connector 状态快照写到 `<data.rootDir>/state/connectors-status.json`
+  - `dobby connector status` 会读取这份快照并展示当前 connector 健康状态
 - guild channel 仍按显式 binding 匹配
 - DM 可通过 `bindings.default` 回落到默认 route
 - 线程消息使用父频道 ID 做 binding 查找
@@ -443,7 +451,7 @@ npm run plugins:setup:local
 
 - `plugins/*` 是扩展源码，不是运行时加载入口
 - 本地扩展安装到 extension store 后，才会被宿主识别
-- `@dobby.ai/plugin-sdk` 在插件里按 `peerDependencies` 暴露，开发期通过 `file:../plugin-sdk` 提供
+- `@dobby.ai/plugin-sdk` 在插件里按非 optional 的 `peerDependencies` 暴露，开发期通过 `file:../plugin-sdk` 提供
 
 ## 检查与测试
 

package/dist/src/cli/commands/connector.js

@@ -0,0 +1,77 @@
+import { join } from "node:path";
+import { connectorStatusSnapshotExists, connectorStatusSnapshotPath, isConnectorStatusSnapshotStale, readConnectorStatusSnapshot, } from "../../core/connector-status.js";
+import { requireRawConfig, resolveConfigPath, resolveDataRootDir } from "../shared/config-io.js";
+function formatTimestamp(timestampMs) {
+    return new Date(timestampMs).toISOString();
+}
+function pad(value, width) {
+    return value.padEnd(width);
+}
+function renderTable(items) {
+    const rows = items.map((item) => ({
+        connectorId: item.connectorId,
+        platform: item.platform,
+        availability: item.availability,
+        health: item.health.status,
+        restarts: String(item.health.restartCount ?? 0),
+        updated: formatTimestamp(item.health.updatedAtMs),
+    }));
+    const widths = {
+        connectorId: Math.max("CONNECTOR".length, ...rows.map((row) => row.connectorId.length)),
+        platform: Math.max("PLATFORM".length, ...rows.map((row) => row.platform.length)),
+        availability: Math.max("AVAILABILITY".length, ...rows.map((row) => row.availability.length)),
+        health: Math.max("HEALTH".length, ...rows.map((row) => row.health.length)),
+        restarts: Math.max("RESTARTS".length, ...rows.map((row) => row.restarts.length)),
+        updated: Math.max("UPDATED".length, ...rows.map((row) => row.updated.length)),
+    };
+    const lines = [
+        [
+            pad("CONNECTOR", widths.connectorId),
+            pad("PLATFORM", widths.platform),
+            pad("AVAILABILITY", widths.availability),
+            pad("HEALTH", widths.health),
+            pad("RESTARTS", widths.restarts),
+            pad("UPDATED", widths.updated),
+        ].join("  "),
+    ];
+    for (const row of rows) {
+        lines.push([
+            pad(row.connectorId, widths.connectorId),
+            pad(row.platform, widths.platform),
+            pad(row.availability, widths.availability),
+            pad(row.health, widths.health),
+            pad(row.restarts, widths.restarts),
+            pad(row.updated, widths.updated),
+        ].join("  "));
+    }
+    return lines;
+}
+export async function runConnectorStatusCommand(options) {
+    const configPath = resolveConfigPath();
+    const rawConfig = await requireRawConfig(configPath);
+    const statusPath = connectorStatusSnapshotPath(join(resolveDataRootDir(configPath, rawConfig), "state"));
+    if (!(await connectorStatusSnapshotExists(statusPath))) {
+        throw new Error(`Connector status snapshot '${statusPath}' does not exist. Start 'dobby start' first.`);
+    }
+    const snapshot = await readConnectorStatusSnapshot(statusPath);
+    const items = options.connectorId
+        ? snapshot.items.filter((item) => item.connectorId === options.connectorId)
+        : snapshot.items;
+    if (options.connectorId && items.length === 0) {
+        throw new Error(`Connector '${options.connectorId}' was not found in '${statusPath}'.`);
+    }
+    if (options.json) {
+        console.log(JSON.stringify({ ...snapshot, items }));
+        return;
+    }
+    if (isConnectorStatusSnapshotStale(snapshot)) {
+        console.log("Warning: connector status snapshot is stale; the gateway may not be running.");
+    }
+    if (items.length === 0) {
+        console.log("(empty)");
+        return;
+    }
+    for (const line of renderTable(items)) {
+        console.log(line);
+    }
+}

package/dist/src/cli/commands/start.js

@@ -2,6 +2,7 @@ import { dirname, join } from "node:path";
 import { loadCronConfig } from "../../cron/config.js";
 import { CronService } from "../../cron/service.js";
 import { CronStore } from "../../cron/store.js";
+import { connectorStatusSnapshotPath, DEFAULT_CONNECTOR_STATUS_PUBLISH_INTERVAL_MS, DEFAULT_CONNECTOR_STATUS_STALE_AFTER_MS, writeConnectorStatusSnapshot, } from "../../core/connector-status.js";
 import { DedupStore } from "../../core/dedup-store.js";
 import { Gateway } from "../../core/gateway.js";
 import { BindingResolver, loadGatewayConfig, RouteResolver } from "../../core/routing.js";
@@ -90,6 +91,8 @@ function selectSandboxInstances(config) {
 export async function runStartCommand() {
     const configPath = resolveConfigPath();
     const config = await loadGatewayConfig(configPath);
+    const gatewayStartedAtMs = Date.now();
+    const connectorStatusPath = connectorStatusSnapshotPath(config.data.stateDir);
     await ensureDataDirs(config.data.rootDir);
     const logger = createLogger();
     const loader = new ExtensionLoader(logger, {
@@ -151,18 +154,67 @@ export async function runStartCommand() {
         gateway,
         logger,
     });
+    const publishConnectorStatuses = async () => {
+        await writeConnectorStatusSnapshot(connectorStatusPath, {
+            schemaVersion: 1,
+            generatedAtMs: Date.now(),
+            staleAfterMs: DEFAULT_CONNECTOR_STATUS_STALE_AFTER_MS,
+            gateway: {
+                pid: process.pid,
+                startedAtMs: gatewayStartedAtMs,
+            },
+            items: gateway.listConnectorStatuses(),
+        });
+    };
+    let connectorStatusTimer = null;
+    const startConnectorStatusPublisher = async () => {
+        try {
+            await publishConnectorStatuses();
+        }
+        catch (error) {
+            logger.warn({ err: error, connectorStatusPath }, "Failed to write initial connector status snapshot");
+        }
+        connectorStatusTimer = setInterval(() => {
+            void publishConnectorStatuses().catch((error) => {
+                logger.warn({ err: error, connectorStatusPath }, "Failed to refresh connector status snapshot");
+            });
+        }, DEFAULT_CONNECTOR_STATUS_PUBLISH_INTERVAL_MS);
+    };
+    const stopConnectorStatusPublisher = async () => {
+        if (connectorStatusTimer) {
+            clearInterval(connectorStatusTimer);
+            connectorStatusTimer = null;
+        }
+        try {
+            await publishConnectorStatuses();
+        }
+        catch (error) {
+            logger.warn({ err: error, connectorStatusPath }, "Failed to write final connector status snapshot");
+        }
+    };
     await gateway.start();
     await cronService.start();
+    await startConnectorStatusPublisher();
     logger.info({
         configPath,
         cronConfigPath: loadedCronConfig.configPath,
         cronConfigSource: loadedCronConfig.source,
         cronEnabled: loadedCronConfig.config.enabled,
     }, "Gateway started");
+    let shuttingDown = false;
     const shutdown = async (signal) => {
+        if (shuttingDown) {
+            return;
+        }
+        shuttingDown = true;
         logger.info({ signal }, "Shutting down gateway");
+        if (connectorStatusTimer) {
+            clearInterval(connectorStatusTimer);
+            connectorStatusTimer = null;
+        }
         await cronService.stop();
         await gateway.stop();
+        await stopConnectorStatusPublisher();
         await hostExecutor.close();
         await closeProviderInstances(providers, logger);
         await closeSandboxInstances(sandboxes, logger);

package/dist/src/cli/program.js

@@ -2,6 +2,7 @@ import { existsSync, readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { Command } from "commander";
 import { runConfigListCommand, runConfigSchemaListCommand, runConfigSchemaShowCommand, runConfigShowCommand, } from "./commands/config.js";
+import { runConnectorStatusCommand } from "./commands/connector.js";
 import { runCronAddCommand, runCronListCommand, runCronPauseCommand, runCronRemoveCommand, runCronResumeCommand, runCronRunCommand, runCronStatusCommand, runCronUpdateCommand, } from "./commands/cron.js";
 import { runDoctorCommand } from "./commands/doctor.js";
 import { runExtensionInstallCommand, runExtensionListCommand, runExtensionUninstallCommand, } from "./commands/extension.js";
@@ -127,6 +128,18 @@ export function buildProgram() {
             fix: Boolean(opts.fix),
         });
     });
+    const connectorCommand = program.command("connector").description("Inspect runtime connector status");
+    connectorCommand
+        .command("status")
+        .description("Show status for all connectors or one connector")
+        .argument("[connectorId]", "Connector instance ID")
+        .option("--json", "Output JSON", false)
+        .action(async (connectorId, opts) => {
+        await runConnectorStatusCommand({
+            ...(typeof connectorId === "string" ? { connectorId } : {}),
+            json: Boolean(opts.json),
+        });
+    });
     const cronCommand = program.command("cron").description("Manage scheduled cron jobs");
     cronCommand
         .command("add")

package/dist/src/core/connector-status.js

@@ -0,0 +1,132 @@
+import { access, mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+export const CONNECTOR_STATUS_SNAPSHOT_FILENAME = "connectors-status.json";
+export const DEFAULT_CONNECTOR_STATUS_PUBLISH_INTERVAL_MS = 5_000;
+export const DEFAULT_CONNECTOR_STATUS_STALE_AFTER_MS = 15_000;
+function isRecord(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function createFallbackHealth(detail) {
+    const now = Date.now();
+    return {
+        status: "stopped",
+        detail,
+        statusSinceMs: now,
+        updatedAtMs: now,
+    };
+}
+export function availabilityFromHealthStatus(status) {
+    switch (status) {
+        case "ready":
+            return "online";
+        case "degraded":
+            return "degraded";
+        case "reconnecting":
+            return "reconnecting";
+        case "starting":
+        case "failed":
+        case "stopped":
+        default:
+            return "offline";
+    }
+}
+export function connectorStatusSnapshotPath(stateDir) {
+    return join(resolve(stateDir), CONNECTOR_STATUS_SNAPSHOT_FILENAME);
+}
+export function statusItemFromConnector(connector) {
+    const health = connector.getHealth?.() ?? createFallbackHealth("Connector health is not available");
+    const availability = availabilityFromHealthStatus(health.status);
+    return {
+        connectorId: connector.id,
+        platform: connector.platform,
+        connectorName: connector.name,
+        availability,
+        online: availability === "online",
+        health,
+    };
+}
+async function writeAtomic(filePath, content) {
+    const absolutePath = resolve(filePath);
+    await mkdir(dirname(absolutePath), { recursive: true });
+    const tempPath = `${absolutePath}.tmp-${Date.now()}-${Math.random().toString(16).slice(2)}`;
+    await writeFile(tempPath, content, "utf-8");
+    await rename(tempPath, absolutePath);
+}
+export async function writeConnectorStatusSnapshot(filePath, snapshot) {
+    await writeAtomic(filePath, `${JSON.stringify(snapshot, null, 2)}\n`);
+}
+export async function connectorStatusSnapshotExists(filePath) {
+    try {
+        await access(resolve(filePath));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function parseHealth(value) {
+    if (!isRecord(value)) {
+        return null;
+    }
+    if (typeof value.status !== "string" || typeof value.statusSinceMs !== "number" || typeof value.updatedAtMs !== "number") {
+        return null;
+    }
+    return value;
+}
+function parseStatusItem(value) {
+    if (!isRecord(value)) {
+        return null;
+    }
+    if (typeof value.connectorId !== "string"
+        || typeof value.platform !== "string"
+        || typeof value.connectorName !== "string"
+        || typeof value.availability !== "string"
+        || typeof value.online !== "boolean") {
+        return null;
+    }
+    const health = parseHealth(value.health);
+    if (!health) {
+        return null;
+    }
+    return {
+        connectorId: value.connectorId,
+        platform: value.platform,
+        connectorName: value.connectorName,
+        availability: value.availability,
+        online: value.online,
+        health,
+    };
+}
+export async function readConnectorStatusSnapshot(filePath) {
+    const raw = await readFile(resolve(filePath), "utf-8");
+    const parsed = JSON.parse(raw);
+    if (!isRecord(parsed) || parsed.schemaVersion !== 1 || typeof parsed.generatedAtMs !== "number" || typeof parsed.staleAfterMs !== "number") {
+        throw new Error(`Connector status snapshot '${resolve(filePath)}' has invalid metadata`);
+    }
+    if (!isRecord(parsed.gateway) || typeof parsed.gateway.pid !== "number" || typeof parsed.gateway.startedAtMs !== "number") {
+        throw new Error(`Connector status snapshot '${resolve(filePath)}' has invalid gateway metadata`);
+    }
+    if (!Array.isArray(parsed.items)) {
+        throw new Error(`Connector status snapshot '${resolve(filePath)}' must contain an items array`);
+    }
+    const items = parsed.items.map((item) => {
+        const normalized = parseStatusItem(item);
+        if (!normalized) {
+            throw new Error(`Connector status snapshot '${resolve(filePath)}' contains an invalid connector entry`);
+        }
+        return normalized;
+    });
+    return {
+        schemaVersion: 1,
+        generatedAtMs: parsed.generatedAtMs,
+        staleAfterMs: parsed.staleAfterMs,
+        gateway: {
+            pid: parsed.gateway.pid,
+            startedAtMs: parsed.gateway.startedAtMs,
+        },
+        items,
+    };
+}
+export function isConnectorStatusSnapshotStale(snapshot, now = Date.now()) {
+    return now - snapshot.generatedAtMs > snapshot.staleAfterMs;
+}

package/dist/src/core/gateway.js

@@ -1,5 +1,6 @@
 import { readFile } from "node:fs/promises";
 import { EventForwarder } from "../agent/event-forwarder.js";
+import { statusItemFromConnector } from "./connector-status.js";
 import { parseControlCommand } from "./control-command.js";
 import { createTypingKeepAliveController } from "./typing-controller.js";
 function isImageAttachment(attachment) {
@@ -67,6 +68,11 @@ export class Gateway {
         await this.options.runtimeRegistry.closeAll();
         this.started = false;
     }
+    listConnectorStatuses() {
+        return this.options.connectors
+            .map((connector) => statusItemFromConnector(connector))
+            .sort((a, b) => a.connectorId.localeCompare(b.connectorId));
+    }
     async handleScheduled(request) {
         const connector = this.connectorsById.get(request.connectorId);
         if (!connector) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dobby.ai/dobby",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "private": false,
   "type": "module",
   "description": "Discord-first local agent gateway built on pi packages",