tickflow-assist 0.3.5 → 0.3.6

package/README.md

@@ -17,6 +17,7 @@
 其中，`configure-openclaw` 会把上述配置写入 `~/.openclaw/openclaw.json` 的 `plugins.entries["tickflow-assist"].config`，插件启用后会在本地 `databasePath` 下持久化 LanceDB 数据，并运行监控 / 日更等后台服务。
 如果你不想把密钥写进配置文件，运行时也支持环境变量回退，优先级是 `openclaw.json / local.config.json` > 环境变量 > 默认值。
 常用环境变量：`TICKFLOW_ASSIST_TICKFLOW_API_KEY` / `TICKFLOW_API_KEY`、`TICKFLOW_ASSIST_LLM_API_KEY` / `LLM_API_KEY`、`TICKFLOW_ASSIST_LLM_BASE_URL` / `LLM_BASE_URL`、`TICKFLOW_ASSIST_LLM_MODEL` / `LLM_MODEL`、`TICKFLOW_ASSIST_MX_SEARCH_API_KEY` / `MX_SEARCH_API_KEY` / `MX_APIKEY`、`TICKFLOW_ASSIST_JIN10_API_TOKEN` / `JIN10_API_TOKEN`。
+如果你希望尽量避免把密钥落盘，推荐先把这些变量写进 `~/.openclaw/.env`，再运行配置向导补齐非密钥项。
 
 ## 安装
 
@@ -24,7 +25,7 @@
 
 ```bash
 openclaw plugins install tickflow-assist
-npx -y tickflow-assist configure-openclaw
+node ~/.openclaw/extensions/tickflow-assist/dist/dev/tickflow-assist-cli.js configure-openclaw
 cd ~/.openclaw/extensions/tickflow-assist/python && uv sync
 openclaw plugins enable tickflow-assist
 openclaw config validate
@@ -38,7 +39,7 @@ openclaw gateway restart
 如果你希望先审阅配置，再只打印最少的后续步骤，可使用：
 
 ```bash
-npx -y tickflow-assist configure-openclaw --no-enable --no-restart
+node ~/.openclaw/extensions/tickflow-assist/dist/dev/tickflow-assist-cli.js configure-openclaw --no-enable --no-restart
 ```
 
 如果你在 Linux 或 macOS 上需要 PNG 告警卡正常显示中文，请额外手动安装 `fontconfig` 与 Noto CJK 一类中文字体，例如：

package/dist/bootstrap.js

@@ -75,6 +75,7 @@ import { resolvePreferredOpenClawTmpDir } from "./runtime/openclaw-temp-dir.js";
 import { RealtimeMonitorWorker } from "./background/realtime-monitor.worker.js";
 import { DailyUpdateWorker } from "./background/daily-update.worker.js";
 import { Jin10FlashWorker } from "./background/jin10-flash.worker.js";
+import { createAlertDiagnosticLogger } from "./utils/alert-diagnostic-log.js";
 export function createAppContext(config, options = {}) {
     const runtime = {
         configSource: options.configSource ?? "local_config",
@@ -109,6 +110,7 @@ export function createAppContext(config, options = {}) {
     const analysisService = new AnalysisService(config.llmBaseUrl, config.llmApiKey, config.llmModel, analysisLogRepository);
     const watchlistProfileService = new WatchlistProfileService(mxApiService, analysisService);
     const tradingCalendarService = new TradingCalendarService(config.calendarFile);
+    const alertDiagnosticLogger = createAlertDiagnosticLogger(config.databasePath);
     const alertService = new AlertService({
         openclawCliBin: config.openclawCliBin,
         channel: config.alertChannel,
@@ -120,6 +122,7 @@ export function createAppContext(config, options = {}) {
                 runtime: runtime.pluginRuntime,
             }
             : undefined,
+        diagnosticLogger: alertDiagnosticLogger,
     });
     const alertMediaService = new AlertMediaService(config.databasePath, undefined, undefined, resolveAlertMediaTempRootDir());
     const indicatorService = new IndicatorService(config.pythonBin, config.pythonArgs, config.pythonWorkdir, runCommandWithTimeout);
@@ -137,7 +140,7 @@ export function createAppContext(config, options = {}) {
     const postCloseReviewTask = new PostCloseReviewTask();
     const compositeStockAnalysisTask = new CompositeStockAnalysisTask(keyLevelsRepository, analysisLogRepository);
     const compositeAnalysisOrchestrator = new CompositeAnalysisOrchestrator(analysisService, marketAnalysisProvider, financialAnalysisProvider, newsAnalysisProvider, klineTechnicalSignalTask, financialFundamentalTask, financialFundamentalLiteTask, newsCatalystTask, compositeStockAnalysisTask, technicalAnalysisRepository, financialAnalysisRepository, newsAnalysisRepository, compositeAnalysisRepository);
-    const monitorService = new MonitorService(config.databasePath, config.requestInterval, config.alertChannel, watchlistService, quoteService, tradingCalendarService, keyLevelsRepository, alertLogRepository, klinesRepository, intradayKlinesRepository, klineService, alertService, alertMediaService);
+    const monitorService = new MonitorService(config.databasePath, config.requestInterval, config.alertChannel, watchlistService, quoteService, tradingCalendarService, keyLevelsRepository, alertLogRepository, klinesRepository, intradayKlinesRepository, klineService, alertService, alertMediaService, alertDiagnosticLogger);
     const jin10FlashMonitorService = new Jin10FlashMonitorService(config.databasePath, config.jin10FlashPollInterval, config.jin10FlashRetentionDays, config.jin10FlashNightAlert, watchlistService, jin10McpService, analysisService, alertService, jin10FlashRepository, jin10FlashDeliveryRepository);
     const updateService = new UpdateService(klineService, config.tickflowApiKeyLevel, indicatorService, klinesRepository, indicatorsRepository, intradayKlinesRepository, watchlistService, tradingCalendarService);
     const postCloseReviewService = new PostCloseReviewService(watchlistService, compositeAnalysisOrchestrator, analysisService, postCloseReviewTask, keyLevelsRepository, keyLevelsHistoryRepository, klinesRepository, intradayKlinesRepository, jin10FlashDeliveryRepository, jin10FlashRepository);

package/dist/services/alert-service.d.ts

@@ -1,5 +1,6 @@
 import type { OpenClawPluginConfig, OpenClawPluginRuntime } from "../runtime/plugin-api.js";
 import type { KeyLevels } from "../types/domain.js";
+import { AlertDiagnosticLogger } from "../utils/alert-diagnostic-log.js";
 interface AlertRuntimeContext {
     config: OpenClawPluginConfig;
     runtime: OpenClawPluginRuntime;
@@ -10,6 +11,7 @@ interface AlertServiceOptions {
     account: string;
     target: string;
     runtime?: AlertRuntimeContext;
+    diagnosticLogger?: AlertDiagnosticLogger;
 }
 export interface AlertSendInput {
     message: string;
@@ -22,6 +24,7 @@ export interface AlertSendResult {
     mediaAttempted: boolean;
     mediaDelivered: boolean;
     error: string | null;
+    deliveryUncertain?: boolean;
 }
 export declare class AlertService {
     private readonly options;
@@ -62,6 +65,11 @@ export declare class AlertService {
     private trySendViaRuntime;
     private invokeRuntimeChannelSend;
     private trySendViaCommand;
+    private prepareCommandPayload;
+    private getCommandRunOptions;
     private buildCliArgs;
+    private logCompletion;
+    private logTransportFailure;
+    private logDiagnostic;
 }
 export {};

package/dist/services/alert-service.js

@@ -1,4 +1,9 @@
+import { randomBytes } from "node:crypto";
+import { copyFile, mkdir, unlink } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
 import { createCommandRunner } from "../runtime/command-runner.js";
+import { basenameOrUndefined, buildAlertMessageHash, buildAlertSendId, truncateDiagnosticText, } from "../utils/alert-diagnostic-log.js";
 import { calculateProfitPct, formatCostPrice } from "../utils/cost-price.js";
 export class AlertService {
     options;
@@ -16,55 +21,84 @@ export class AlertService {
     async sendWithResult(input) {
         this.lastError = null;
         const payload = normalizeSendInput(input);
+        const sendId = buildAlertSendId(payload.message);
+        const messageHash = buildAlertMessageHash(payload.message);
+        const diagnosticContext = {
+            sendId,
+            step: "primary",
+            messageHash,
+        };
         const mediaAttempted = Boolean(payload.mediaPath);
-        const primaryError = await this.trySendPayload(payload);
-        if (primaryError === null) {
-            return {
+        await this.logDiagnostic("send_started", {
+            sendId,
+            step: diagnosticContext.step,
+            channel: this.channel,
+            messageHash,
+            messageLength: payload.message.length,
+            hasMedia: mediaAttempted,
+            mediaFile: basenameOrUndefined(payload.mediaPath),
+            filename: payload.filename,
+            accountConfigured: Boolean(this.options.account.trim()),
+            targetConfigured: Boolean(this.options.target.trim()),
+            runtimeAvailable: Boolean(this.options.runtime),
+            messagePreview: truncateDiagnosticText(payload.message.split("\n")[0] ?? ""),
+        });
+        const primaryFailure = await this.trySendPayload(payload, diagnosticContext);
+        if (primaryFailure === null) {
+            const result = {
                 ok: true,
                 mediaAttempted,
                 mediaDelivered: mediaAttempted,
                 error: null,
             };
+            await this.logCompletion(sendId, messageHash, payload, result);
+            return result;
         }
         if (payload.mediaPath) {
-            if (payload.message.trim()) {
-                const mediaOnlyError = await this.trySendPayload({
-                    ...payload,
-                    message: "",
-                });
-                if (mediaOnlyError === null) {
-                    const textFollowupError = await this.trySendPayload({ message: payload.message });
-                    return {
-                        ok: textFollowupError === null,
-                        mediaAttempted: true,
-                        mediaDelivered: true,
-                        error: textFollowupError,
-                    };
-                }
+            if (primaryFailure.ambiguous) {
+                const result = {
+                    ok: false,
+                    mediaAttempted: true,
+                    mediaDelivered: false,
+                    error: primaryFailure.error,
+                    deliveryUncertain: true,
+                };
+                await this.logCompletion(sendId, messageHash, payload, result);
+                return result;
             }
             const textFallback = normalizeSendInput(payload.message);
-            const textFallbackError = await this.trySendPayload(textFallback);
-            if (textFallbackError === null) {
-                return {
+            const textFallbackFailure = await this.trySendPayload(textFallback, {
+                sendId,
+                step: "text_fallback",
+                messageHash,
+            });
+            if (textFallbackFailure === null) {
+                const result = {
                     ok: true,
                     mediaAttempted: true,
                     mediaDelivered: false,
-                    error: primaryError,
+                    error: primaryFailure.error,
                 };
+                await this.logCompletion(sendId, messageHash, payload, result);
+                return result;
             }
-            return {
+            const result = {
                 ok: false,
                 mediaAttempted: true,
                 mediaDelivered: false,
-                error: this.combineErrors(primaryError, textFallbackError),
+                error: this.combineErrors(primaryFailure.error, textFallbackFailure.error),
             };
+            await this.logCompletion(sendId, messageHash, payload, result);
+            return result;
         }
-        return {
+        const result = {
             ok: false,
             mediaAttempted: false,
             mediaDelivered: false,
-            error: primaryError,
+            error: primaryFailure.error,
         };
+        await this.logCompletion(sendId, messageHash, payload, result);
+        return result;
     }
     getLastError() {
         return this.lastError;
@@ -132,17 +166,35 @@ export class AlertService {
         }
         return `${runtimeError}; ${fallbackError}`;
     }
-    async trySendPayload(payload) {
-        const runtimeError = await this.trySendViaRuntime(payload);
-        if (runtimeError === null) {
+    async trySendPayload(payload, context) {
+        // OpenClaw documents `api.runtime.channel` as channel-plugin-specific helper
+        // surface. For a regular tool/service plugin like tickflow-assist, Telegram
+        // and QQ Bot delivery are more reliable via the shared
+        // `openclaw message send` CLI path.
+        if (this.channel === "telegram" || this.channel === "qqbot") {
+            return await this.trySendViaCommand(payload, context);
+        }
+        const runtimeFailure = await this.trySendViaRuntime(payload, context);
+        if (runtimeFailure === null) {
             return null;
         }
-        return await this.trySendViaCommand(payload);
+        // Only image/media sends are risky to replay after an ambiguous transport error.
+        // Text-only notifications (for example session boundary notifications) should
+        // still fall back to the CLI path so transient runtime failures do not drop them.
+        if (runtimeFailure.ambiguous && payload.mediaPath) {
+            return runtimeFailure;
+        }
+        return await this.trySendViaCommand(payload, context);
     }
-    async trySendViaRuntime(payload) {
+    async trySendViaRuntime(payload, context) {
         const runtimeContext = this.options.runtime;
         if (!runtimeContext || !this.options.target.trim()) {
-            return "runtime delivery unavailable";
+            const failure = {
+                error: "runtime delivery unavailable",
+                ambiguous: false,
+            };
+            await this.logTransportFailure("runtime_unavailable", context, payload, failure);
+            return failure;
         }
         const baseOptions = {
             accountId: this.options.account || undefined,
@@ -152,33 +204,51 @@ export class AlertService {
         };
         try {
             switch (this.channel) {
-                case "telegram":
-                    await this.invokeRuntimeChannelSend(runtimeContext.runtime.channel, "telegram", "sendMessageTelegram", this.options.target, payload.message, baseOptions);
-                    return null;
                 case "discord":
                     await this.invokeRuntimeChannelSend(runtimeContext.runtime.channel, "discord", "sendMessageDiscord", this.options.target, payload.message, {
                         ...baseOptions,
                         filename: payload.filename,
                     });
-                    return null;
+                    break;
                 case "slack":
                     await this.invokeRuntimeChannelSend(runtimeContext.runtime.channel, "slack", "sendMessageSlack", this.options.target, payload.message, {
                         ...baseOptions,
                         uploadFileName: payload.filename,
                         uploadTitle: payload.filename,
                     });
-                    return null;
+                    break;
                 case "signal":
                     await this.invokeRuntimeChannelSend(runtimeContext.runtime.channel, "signal", "sendMessageSignal", this.options.target, payload.message, baseOptions);
-                    return null;
+                    break;
                 default:
                     // OpenClaw 2026.3.31 narrows the typed runtime channel surface.
                     // Fall back to `openclaw message send` for channels not exposed here.
-                    return `runtime delivery not supported for channel: ${this.channel}`;
+                    const failure = {
+                        error: `runtime delivery not supported for channel: ${this.channel}`,
+                        ambiguous: false,
+                    };
+                    await this.logTransportFailure("runtime_unsupported", context, payload, failure);
+                    return failure;
             }
+            await this.logDiagnostic("transport_success", {
+                sendId: context.sendId,
+                step: context.step,
+                transport: "runtime",
+                channel: this.channel,
+                messageHash: context.messageHash,
+                hasMedia: Boolean(payload.mediaPath),
+                mediaFile: basenameOrUndefined(payload.mediaPath),
+            });
+            return null;
         }
         catch (error) {
-            return `runtime delivery failed: ${formatErrorMessage(error)}`;
+            const detail = formatErrorMessage(error);
+            const failure = {
+                error: `runtime delivery failed: ${detail}`,
+                ambiguous: !isRuntimeCapabilityUnavailableError(detail),
+            };
+            await this.logTransportFailure("runtime_failed", context, payload, failure);
+            return failure;
         }
     }
     async invokeRuntimeChannelSend(runtimeChannel, channelName, methodName, target, message, options) {
@@ -189,19 +259,94 @@ export class AlertService {
         }
         await method.call(channelApi, target, message, options);
     }
-    async trySendViaCommand(payload) {
+    async trySendViaCommand(payload, context) {
+        const prepared = await this.prepareCommandPayload(payload);
+        const commandOptions = this.getCommandRunOptions(prepared.payload);
         try {
-            const result = await this.runCommandWithTimeout(this.buildCliArgs(payload), { timeoutMs: 15_000 });
+            const result = await this.runCommandWithTimeout(this.buildCliArgs(prepared.payload), commandOptions);
             if (result.code === 0) {
+                const commandOutcome = inspectCommandDeliveryResult(result.stdout);
+                if (commandOutcome?.error) {
+                    const failure = {
+                        error: commandOutcome.error,
+                        ambiguous: false,
+                    };
+                    await this.logTransportFailure("command_reported_error", context, payload, failure, {
+                        timeoutMs: commandOptions.timeoutMs,
+                        termination: result.termination,
+                        messageId: commandOutcome.messageId,
+                        stdout: truncateDiagnosticText(result.stdout.trim()),
+                    });
+                    return failure;
+                }
+                await this.logDiagnostic("transport_success", {
+                    sendId: context.sendId,
+                    step: context.step,
+                    transport: "command",
+                    channel: this.channel,
+                    messageHash: context.messageHash,
+                    hasMedia: Boolean(payload.mediaPath),
+                    mediaFile: basenameOrUndefined(payload.mediaPath),
+                    timeoutMs: commandOptions.timeoutMs,
+                    termination: result.termination,
+                    messageId: commandOutcome?.messageId,
+                });
                 return null;
             }
-            return (result.stderr.trim()
-                || result.stdout.trim()
-                || `command exited with ${result.code ?? "unknown"}`);
+            const failure = {
+                error: result.stderr.trim()
+                    || result.stdout.trim()
+                    || `command exited with ${result.code ?? "unknown"}`,
+                ambiguous: true,
+            };
+            await this.logTransportFailure("command_failed", context, payload, failure, {
+                code: result.code,
+                timeoutMs: commandOptions.timeoutMs,
+                termination: result.termination,
+                stderr: truncateDiagnosticText(result.stderr.trim()),
+                stdout: truncateDiagnosticText(result.stdout.trim()),
+            });
+            return failure;
         }
         catch (error) {
-            return `command delivery failed: ${formatErrorMessage(error)}`;
+            const failure = {
+                error: `command delivery failed: ${formatErrorMessage(error)}`,
+                ambiguous: false,
+            };
+            await this.logTransportFailure("command_error", context, payload, failure);
+            return failure;
+        }
+        finally {
+            await prepared.cleanup();
+        }
+    }
+    async prepareCommandPayload(payload) {
+        if (!shouldStageQQBotMedia(this.channel, payload.mediaPath)) {
+            return {
+                payload,
+                cleanup: async () => { },
+            };
+        }
+        const stagedMediaPath = await stageQQBotMediaFile(payload.mediaPath);
+        return {
+            payload: {
+                ...payload,
+                mediaPath: stagedMediaPath,
+            },
+            cleanup: async () => {
+                await unlink(stagedMediaPath).catch((error) => {
+                    if (error.code !== "ENOENT") {
+                        throw error;
+                    }
+                });
+            },
+        };
+    }
+    getCommandRunOptions(payload) {
+        if (payload.mediaPath) {
+            return { timeoutMs: 45_000 };
         }
+        return { timeoutMs: 15_000 };
     }
     buildCliArgs(payload) {
         const args = [
@@ -223,8 +368,40 @@ export class AlertService {
         if (this.options.account) {
             args.push("--account", this.options.account);
         }
+        args.push("--json");
         return args;
     }
+    async logCompletion(sendId, messageHash, payload, result) {
+        await this.logDiagnostic("send_completed", {
+            sendId,
+            channel: this.channel,
+            messageHash,
+            hasMedia: Boolean(payload.mediaPath),
+            mediaFile: basenameOrUndefined(payload.mediaPath),
+            ok: result.ok,
+            mediaAttempted: result.mediaAttempted,
+            mediaDelivered: result.mediaDelivered,
+            deliveryUncertain: result.deliveryUncertain === true,
+            error: result.error ? truncateDiagnosticText(result.error) : null,
+        });
+    }
+    async logTransportFailure(event, context, payload, failure, extra = {}) {
+        await this.logDiagnostic(event, {
+            sendId: context.sendId,
+            step: context.step,
+            transport: event.startsWith("command") ? "command" : "runtime",
+            channel: this.channel,
+            messageHash: context.messageHash,
+            hasMedia: Boolean(payload.mediaPath),
+            mediaFile: basenameOrUndefined(payload.mediaPath),
+            ambiguous: failure.ambiguous,
+            error: truncateDiagnosticText(failure.error),
+            ...extra,
+        });
+    }
+    async logDiagnostic(event, details) {
+        await this.options.diagnosticLogger?.append("alert_service", event, details);
+    }
 }
 function formatErrorMessage(error) {
     if (error instanceof Error) {
@@ -240,11 +417,62 @@ function formatErrorMessage(error) {
         return String(error);
     }
 }
+function isRuntimeCapabilityUnavailableError(detail) {
+    return /runtime channel .* unavailable/i.test(detail);
+}
 function normalizeSendInput(input) {
     return typeof input === "string"
         ? { message: input }
         : input;
 }
+function inspectCommandDeliveryResult(stdout) {
+    const payload = extractCommandJsonPayload(stdout);
+    if (!payload) {
+        return null;
+    }
+    const directResult = isRecord(payload.result) ? payload.result : null;
+    const directResultMeta = isRecord(directResult?.meta) ? directResult.meta : null;
+    const error = getNonEmptyString(directResult?.error)
+        ?? getNonEmptyString(directResultMeta?.error)
+        ?? getNonEmptyString(payload.error);
+    const messageId = getNonEmptyString(directResult?.messageId)
+        ?? getNonEmptyString(directResultMeta?.messageId)
+        ?? getNonEmptyString(payload.messageId);
+    if (!error && !messageId) {
+        return null;
+    }
+    return {
+        ...(error ? { error } : {}),
+        ...(messageId ? { messageId } : {}),
+    };
+}
+function extractCommandJsonPayload(stdout) {
+    const root = extractTrailingJsonObject(stdout);
+    if (!root) {
+        return null;
+    }
+    return isRecord(root.payload) ? root.payload : root;
+}
+function extractTrailingJsonObject(stdout) {
+    const trimmed = stdout.trim();
+    if (!trimmed) {
+        return null;
+    }
+    for (let start = trimmed.lastIndexOf("{"); start >= 0; start = trimmed.lastIndexOf("{", start - 1)) {
+        const candidate = trimmed.slice(start);
+        try {
+            const parsed = JSON.parse(candidate);
+            const record = isRecord(parsed) ? parsed : null;
+            if (record) {
+                return record;
+            }
+        }
+        catch {
+            // Keep scanning backward until the trailing JSON object is found.
+        }
+    }
+    return null;
+}
 function getRuntimeChannelApi(runtimeChannel, channelName) {
     if (!isRecord(runtimeChannel)) {
         return null;
@@ -255,6 +483,60 @@ function getRuntimeChannelApi(runtimeChannel, channelName) {
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
+function getNonEmptyString(value) {
+    if (typeof value !== "string") {
+        return undefined;
+    }
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
+function shouldStageQQBotMedia(channel, mediaPath) {
+    return channel === "qqbot"
+        && typeof mediaPath === "string"
+        && mediaPath.length > 0
+        && !isRemoteMediaPath(mediaPath)
+        && !isUnderQQBotManagedMediaRoot(mediaPath);
+}
+function isRemoteMediaPath(mediaPath) {
+    return /^(?:https?:|data:)/i.test(mediaPath.trim());
+}
+function isUnderQQBotManagedMediaRoot(mediaPath) {
+    const candidate = path.resolve(mediaPath);
+    const mediaRoot = path.resolve(getQQBotManagedMediaRoot());
+    const relative = path.relative(mediaRoot, candidate);
+    return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+async function stageQQBotMediaFile(mediaPath) {
+    const destinationDir = path.join(getQQBotManagedMediaRoot(), "tickflow-assist");
+    await mkdir(destinationDir, { recursive: true });
+    const sourceExt = path.extname(mediaPath);
+    const sourceBase = path.basename(mediaPath, sourceExt);
+    const safeBase = sanitizeFileNamePart(sourceBase) || "alert-media";
+    const safeExt = sanitizeFileExtension(sourceExt);
+    const stagedName = `${safeBase}-${Date.now()}-${randomBytes(3).toString("hex")}${safeExt}`;
+    const stagedPath = path.join(destinationDir, stagedName);
+    await copyFile(mediaPath, stagedPath);
+    return stagedPath;
+}
+function getQQBotManagedMediaRoot() {
+    return path.join(resolveHomeDir(), ".openclaw", "media", "qqbot");
+}
+function resolveHomeDir() {
+    const fromOs = os.homedir();
+    if (fromOs) {
+        return fromOs;
+    }
+    return process.env.HOME || process.env.USERPROFILE || ".";
+}
+function sanitizeFileNamePart(value) {
+    return value.replace(/[^a-zA-Z0-9._-]+/g, "_");
+}
+function sanitizeFileExtension(value) {
+    if (!value) {
+        return "";
+    }
+    return /^\.[a-zA-Z0-9]+$/.test(value) ? value.toLowerCase() : "";
+}
 function getAlertStyle(ruleCode, fallbackTitle) {
     switch (ruleCode) {
         case "stop_loss_hit":

package/dist/services/monitor-service.d.ts

@@ -1,4 +1,5 @@
 import type { MonitorState } from "../types/monitor.js";
+import { AlertDiagnosticLogger } from "../utils/alert-diagnostic-log.js";
 import { QuoteService } from "./quote-service.js";
 import { TradingCalendarService } from "./trading-calendar-service.js";
 import { WatchlistService } from "./watchlist-service.js";
@@ -23,7 +24,8 @@ export declare class MonitorService {
     private readonly klineService;
     private readonly alertService;
     private readonly alertMediaService;
-    constructor(baseDir: string, requestInterval: number, alertChannel: string, watchlistService: WatchlistService, quoteService: QuoteService, tradingCalendarService: TradingCalendarService, keyLevelsRepository: KeyLevelsRepository, alertLogRepository: AlertLogRepository, klinesRepository: KlinesRepository, intradayKlinesRepository: IntradayKlinesRepository, klineService: KlineService, alertService: AlertService, alertMediaService: AlertMediaService);
+    private readonly diagnosticLogger?;
+    constructor(baseDir: string, requestInterval: number, alertChannel: string, watchlistService: WatchlistService, quoteService: QuoteService, tradingCalendarService: TradingCalendarService, keyLevelsRepository: KeyLevelsRepository, alertLogRepository: AlertLogRepository, klinesRepository: KlinesRepository, intradayKlinesRepository: IntradayKlinesRepository, klineService: KlineService, alertService: AlertService, alertMediaService: AlertMediaService, diagnosticLogger?: AlertDiagnosticLogger | undefined);
     start(): Promise<string>;
     stop(): Promise<string>;
     enableManagedLoop(): Promise<{
@@ -59,4 +61,5 @@ export declare class MonitorService {
     private cleanupAlertMedia;
     private getRunLockFilePath;
     private getAlertClaimFilePath;
+    private logDiagnostic;
 }

package/dist/services/monitor-service.js

@@ -1,5 +1,6 @@
 import { mkdir, readFile, rm, stat, writeFile } from "node:fs/promises";
 import path from "node:path";
+import { basenameOrUndefined, buildAlertMessageHash, truncateDiagnosticText, } from "../utils/alert-diagnostic-log.js";
 import { formatChinaDateTime } from "../utils/china-time.js";
 import { calculateProfitPct, formatCostPrice } from "../utils/cost-price.js";
 const DEFAULT_STATE = {
@@ -36,7 +37,8 @@ export class MonitorService {
     klineService;
     alertService;
     alertMediaService;
-    constructor(baseDir, requestInterval, alertChannel, watchlistService, quoteService, tradingCalendarService, keyLevelsRepository, alertLogRepository, klinesRepository, intradayKlinesRepository, klineService, alertService, alertMediaService) {
+    diagnosticLogger;
+    constructor(baseDir, requestInterval, alertChannel, watchlistService, quoteService, tradingCalendarService, keyLevelsRepository, alertLogRepository, klinesRepository, intradayKlinesRepository, klineService, alertService, alertMediaService, diagnosticLogger) {
         this.baseDir = baseDir;
         this.requestInterval = requestInterval;
         this.alertChannel = alertChannel;
@@ -50,6 +52,7 @@ export class MonitorService {
         this.klineService = klineService;
         this.alertService = alertService;
         this.alertMediaService = alertMediaService;
+        this.diagnosticLogger = diagnosticLogger;
     }
     async start() {
         const watchlist = await this.watchlistService.list();
@@ -464,21 +467,54 @@ export class MonitorService {
     }
     async trySendAlert(symbol, ruleName, input) {
         const sessionKey = getSessionKey();
+        const message = typeof input === "string" ? input : input.message;
+        const messageHash = buildAlertMessageHash(message);
+        const hasMedia = typeof input !== "string" && Boolean(input.mediaPath);
+        await this.logDiagnostic("try_send_alert_enter", {
+            symbol,
+            ruleName,
+            sessionKey,
+            messageHash,
+            hasMedia,
+            mediaFile: typeof input === "string" ? undefined : basenameOrUndefined(input.mediaPath),
+        });
         const claim = await this.tryAcquireAlertClaim(symbol, ruleName, sessionKey);
         if (!claim) {
+            await this.logDiagnostic("try_send_alert_claim_busy", {
+                symbol,
+                ruleName,
+                sessionKey,
+                messageHash,
+            });
             await this.cleanupAlertMedia(input);
             return false;
         }
         try {
             if (await this.alertLogRepository.isSentThisSession(symbol, ruleName, sessionKey)) {
+                await this.logDiagnostic("try_send_alert_already_sent", {
+                    symbol,
+                    ruleName,
+                    sessionKey,
+                    messageHash,
+                });
                 await this.cleanupAlertMedia(input);
                 return false;
             }
             const result = await this.sendAlertAndCleanupMedia(input);
-            if (!result.ok) {
+            await this.logDiagnostic("try_send_alert_result", {
+                symbol,
+                ruleName,
+                sessionKey,
+                messageHash,
+                ok: result.ok,
+                mediaAttempted: result.mediaAttempted,
+                mediaDelivered: result.mediaDelivered,
+                deliveryUncertain: result.deliveryUncertain === true,
+                error: result.error ? truncateDiagnosticText(result.error) : null,
+            });
+            if (!result.ok && !result.deliveryUncertain) {
                 return false;
             }
-            const message = typeof input === "string" ? input : input.message;
             await this.alertLogRepository.append({
                 symbol,
                 alert_date: sessionKey,
@@ -486,6 +522,12 @@ export class MonitorService {
                 message,
                 triggered_at: formatChinaDateTime(),
             });
+            await this.logDiagnostic("try_send_alert_logged", {
+                symbol,
+                ruleName,
+                sessionKey,
+                messageHash,
+            });
             return true;
         }
         finally {
@@ -616,6 +658,9 @@ export class MonitorService {
     getAlertClaimFilePath(symbol, ruleName, sessionKey) {
         return path.join(this.baseDir, "alert-claims", `${sanitizeAlertClaimPart(sessionKey)}_${sanitizeAlertClaimPart(symbol)}_${sanitizeAlertClaimPart(ruleName)}.lock`);
     }
+    async logDiagnostic(event, details) {
+        await this.diagnosticLogger?.append("monitor_service", event, details);
+    }
 }
 function formatRunningState(state, requestInterval) {
     const heartbeat = getHeartbeatStatus(state, requestInterval);

package/dist/tools/test-alert.tool.js

@@ -53,6 +53,11 @@ export function testAlertTool(alertService, alertMediaService, configSource = "o
                     mediaLocalRoots: mediaFile.mediaLocalRoots,
                     filename: mediaFile.filename,
                 });
+                if (result.deliveryUncertain) {
+                    return result.error
+                        ? `⚠️ PNG 告警疑似已送达，但通道返回异常；为避免重复未执行拆分补发\n原因: ${result.error}`
+                        : "⚠️ PNG 告警疑似已送达，但通道返回异常；为避免重复未执行拆分补发";
+                }
                 if (result.ok && result.mediaDelivered) {
                     if (result.error) {
                         return [

package/dist/utils/alert-diagnostic-log.d.ts

@@ -0,0 +1,12 @@
+export declare const ALERT_DIAGNOSTIC_LOG_ENV = "TICKFLOW_ALERT_DIAGNOSTIC_LOG";
+export declare class AlertDiagnosticLogger {
+    private readonly filePath;
+    constructor(baseDir: string, fileName?: string);
+    getFilePath(): string;
+    append(scope: string, event: string, details?: Record<string, unknown>): Promise<void>;
+}
+export declare function createAlertDiagnosticLogger(baseDir: string, env?: NodeJS.ProcessEnv): AlertDiagnosticLogger | undefined;
+export declare function buildAlertMessageHash(message: string): string;
+export declare function buildAlertSendId(message: string): string;
+export declare function basenameOrUndefined(filePath?: string): string | undefined;
+export declare function truncateDiagnosticText(value: string, maxLength?: number): string;

package/dist/utils/alert-diagnostic-log.js

@@ -0,0 +1,60 @@
+import { createHash } from "node:crypto";
+import { appendFile, mkdir } from "node:fs/promises";
+import path from "node:path";
+import { formatChinaDateTime } from "./china-time.js";
+const DEFAULT_LOG_FILE = "alert-delivery-debug.ndjson";
+export const ALERT_DIAGNOSTIC_LOG_ENV = "TICKFLOW_ALERT_DIAGNOSTIC_LOG";
+export class AlertDiagnosticLogger {
+    filePath;
+    constructor(baseDir, fileName = DEFAULT_LOG_FILE) {
+        this.filePath = path.join(baseDir, fileName);
+    }
+    getFilePath() {
+        return this.filePath;
+    }
+    async append(scope, event, details = {}) {
+        try {
+            await mkdir(path.dirname(this.filePath), { recursive: true });
+            await appendFile(this.filePath, `${JSON.stringify({
+                at: formatChinaDateTime(),
+                scope,
+                event,
+                ...details,
+            })}\n`, "utf-8");
+        }
+        catch {
+            // Diagnostic logging must never break alert delivery.
+        }
+    }
+}
+export function createAlertDiagnosticLogger(baseDir, env = process.env) {
+    if (!isAlertDiagnosticLogEnabled(env)) {
+        return undefined;
+    }
+    return new AlertDiagnosticLogger(baseDir);
+}
+function isAlertDiagnosticLogEnabled(env) {
+    const raw = env[ALERT_DIAGNOSTIC_LOG_ENV]?.trim().toLowerCase();
+    return raw === "1" || raw === "true" || raw === "yes" || raw === "on";
+}
+export function buildAlertMessageHash(message) {
+    return createHash("sha1")
+        .update(message)
+        .digest("hex")
+        .slice(0, 12);
+}
+export function buildAlertSendId(message) {
+    return `${formatChinaDateTime().replace(/[^0-9]/g, "").slice(0, 14)}-${buildAlertMessageHash(message)}`;
+}
+export function basenameOrUndefined(filePath) {
+    if (!filePath) {
+        return undefined;
+    }
+    return path.basename(filePath);
+}
+export function truncateDiagnosticText(value, maxLength = 160) {
+    if (value.length <= maxLength) {
+        return value;
+    }
+    return `${value.slice(0, maxLength)}...`;
+}

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "tickflow-assist",
   "name": "TickFlow Assist",
-  "version": "0.3.5",
+  "version": "0.3.6",
   "description": "A-share watchlist analysis, monitoring, and alert delivery powered by TickFlow and OpenClaw.",
   "skills": [
     "skills"
@@ -10,6 +10,35 @@
     "onCapabilities": ["tool", "hook"]
   },
   "setup": {
+    "providers": [
+      {
+        "id": "tickflow",
+        "authMethods": ["api-key"],
+        "envVars": ["TICKFLOW_ASSIST_TICKFLOW_API_KEY", "TICKFLOW_API_KEY"]
+      },
+      {
+        "id": "llm",
+        "authMethods": ["api-key"],
+        "envVars": [
+          "TICKFLOW_ASSIST_LLM_BASE_URL",
+          "LLM_BASE_URL",
+          "TICKFLOW_ASSIST_LLM_API_KEY",
+          "LLM_API_KEY",
+          "TICKFLOW_ASSIST_LLM_MODEL",
+          "LLM_MODEL"
+        ]
+      },
+      {
+        "id": "mx-search",
+        "authMethods": ["api-key"],
+        "envVars": ["TICKFLOW_ASSIST_MX_SEARCH_API_KEY", "MX_SEARCH_API_KEY", "MX_APIKEY"]
+      },
+      {
+        "id": "jin10",
+        "authMethods": ["api-key"],
+        "envVars": ["TICKFLOW_ASSIST_JIN10_API_TOKEN", "JIN10_API_TOKEN"]
+      }
+    ],
     "requiresRuntime": true
   },
   "configContracts": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tickflow-assist",
-  "version": "0.3.5",
+  "version": "0.3.6",
   "description": "面向 A 股投资与盯盘场景的 OpenClaw 智能股票插件，基于 TickFlow API 提供实时监控、收盘后复盘、多维综合分析、关键价位跟踪与告警能力。OpenClaw smart stock plugin for A-share investing and watchlist workflows, powered by TickFlow API for realtime monitoring, post-close review, multi-dimensional analysis, key level tracking, and alerts.",
   "license": "MIT",
   "type": "module",
@@ -53,6 +53,11 @@
       "minGatewayVersion": "2026.3.31",
       "builtWithOpenClawVersion": "2026.4.11"
     },
+    "install": {
+      "npmSpec": "tickflow-assist",
+      "defaultChoice": "npm",
+      "minHostVersion": ">=2026.3.31"
+    },
     "extensions": [
       "dist/plugin.js"
     ]
@@ -72,6 +77,6 @@
     "openclaw": "^2026.4.11",
     "typescript": "^5.8.2"
   },
-  "readme": "# TickFlow Assist\n\n基于 [OpenClaw](https://openclaw.ai) 的 A 股监控与分析插件。它使用 [TickFlow](https://tickflow.org/auth/register?ref=BUJ54JEDGE) 获取行情与财务数据，并可选接入 [金十数据 MCP](https://mcp.jin10.com/app/) 快讯流，结合 LLM 生成技术面、基本面、资讯面的综合判断，并把结果持久化到本地 LanceDB。\n\n最近更新：`v0.3.5` 对齐 OpenClaw `2026.4.11` metadata 与社区安装提示，修复源码升级时本地链接扫描 `node_modules` 失败的问题，并支持通过环境变量回退 TickFlow / LLM / MX / Jin10 配置。完整发布记录见 <https://github.com/robinspt/tickflow-assist/blob/main/CHANGELOG.md>。\n\n当前主线按 OpenClaw `v2026.3.31+` 对齐，并已验证社区安装在 `v2026.4.11` 上兼容。\n\n## 安装前准备\n\n在执行社区安装前，建议先确认你已经准备好以下配置：\n\n- 核心必需：`tickflowApiKey`、`llmApiKey`、`llmBaseUrl`、`llmModel`\n- 告警投递：`alertChannel`、`alertTarget`、`alertAccount`\n- 可选增强：`mxSearchApiKey`、`jin10ApiToken`\n\n其中，`configure-openclaw` 会把上述配置写入 `~/.openclaw/openclaw.json` 的 `plugins.entries[\"tickflow-assist\"].config`，插件启用后会在本地 `databasePath` 下持久化 LanceDB 数据，并运行监控 / 日更等后台服务。\n如果你不想把密钥写进配置文件，运行时也支持环境变量回退，优先级是 `openclaw.json / local.config.json` > 环境变量 > 默认值。\n常用环境变量：`TICKFLOW_ASSIST_TICKFLOW_API_KEY` / `TICKFLOW_API_KEY`、`TICKFLOW_ASSIST_LLM_API_KEY` / `LLM_API_KEY`、`TICKFLOW_ASSIST_LLM_BASE_URL` / `LLM_BASE_URL`、`TICKFLOW_ASSIST_LLM_MODEL` / `LLM_MODEL`、`TICKFLOW_ASSIST_MX_SEARCH_API_KEY` / `MX_SEARCH_API_KEY` / `MX_APIKEY`、`TICKFLOW_ASSIST_JIN10_API_TOKEN` / `JIN10_API_TOKEN`。\n\n## 安装\n\n社区安装：\n\n```bash\nopenclaw plugins install tickflow-assist\nnpx -y tickflow-assist configure-openclaw\ncd ~/.openclaw/extensions/tickflow-assist/python && uv sync\nopenclaw plugins enable tickflow-assist\nopenclaw config validate\nopenclaw gateway restart\n```\n\n安装阶段允许先落插件，再通过第二条命令写入 `tickflowApiKey`、`llmApiKey`、`llmBaseUrl`、`llmModel` 等正式配置。\n`configure-openclaw` 会写入 `~/.openclaw/openclaw.json` 中的 `plugins.entries[\"tickflow-assist\"].config`，并打印后续建议执行的命令；它不再自动执行 `openclaw`、`uv` 或系统包安装命令，也不会重新执行插件安装；如果你已经设置了环境变量，密钥项可留空，输入 `-` 可主动清空已有配置并切回环境变量。\n如果检测到 `plugins.installs[\"tickflow-assist\"]` 来自 `clawhub`，向导还会把被旧版本钉死的 `spec` 归一化为 `clawhub:tickflow-assist`，避免后续升级继续锁在旧版本。\n\n如果你希望先审阅配置，再只打印最少的后续步骤，可使用：\n\n```bash\nnpx -y tickflow-assist configure-openclaw --no-enable --no-restart\n```\n\n如果你在 Linux 或 macOS 上需要 PNG 告警卡正常显示中文，请额外手动安装 `fontconfig` 与 Noto CJK 一类中文字体，例如：\n\n```bash\n# Debian / Ubuntu\nsudo apt-get update\nsudo apt-get install -y fontconfig fonts-noto-cjk\nfc-cache -fv\n\n# RHEL / Fedora / Rocky / AlmaLinux\nsudo dnf install -y fontconfig google-noto-sans-cjk-ttc-fonts\nfc-cache -fv\n\n# Arch / Manjaro\nsudo pacman -Sy --noconfirm fontconfig noto-fonts-cjk\nfc-cache -fv\n\n# Alpine\nsudo apk add fontconfig font-noto-cjk\nfc-cache -fv\n\n# macOS (Homebrew)\nbrew install fontconfig\nbrew install --cask font-noto-sans-cjk\nfc-cache -fv\n```\n\n社区安装后的升级方式：\n\n```bash\nopenclaw plugins update tickflow-assist\nopenclaw gateway restart\n```\n\n## 配置\n\n插件正式运行读取：\n\n```text\n~/.openclaw/openclaw.json\n```\n\n配置路径：\n\n```text\nplugins.entries[\"tickflow-assist\"].config\n```\n\n建议按完整功能显式填写以下字段，不要只填 API Key：\n\n- 核心运行：`tickflowApiKey`、`llmApiKey`、`llmBaseUrl`、`llmModel`\n- 本地数据：`databasePath`、`calendarFile`\n- 告警投递：`alertChannel`、`alertTarget`、`alertAccount`\n- 能力补充：`mxSearchApiKey`、`jin10ApiToken`\n\n其中，`mxSearchApiKey` 用于 `mx_search`、`mx_select_stock` 以及非 `Expert` 财务链路的 lite 补充；`jin10ApiToken` 用于 24 小时金十数据快讯监控；`jin10FlashNightAlert` 默认 `false`（开启夜间静默），设为 `true` 可恢复 24 小时快讯告警；`alertTarget`、`alertAccount` 建议在准备启用 `test_alert`、实时监控告警、金十数据快讯告警和定时通知前一并配好，避免配置不完整导致功能缺失。\n如果你使用环境变量，运行时支持以下回退：\n\n- `tickflowApiUrl`：`TICKFLOW_ASSIST_TICKFLOW_API_URL` / `TICKFLOW_API_URL`\n- `tickflowApiKey`：`TICKFLOW_ASSIST_TICKFLOW_API_KEY` / `TICKFLOW_API_KEY`\n- `tickflowApiKeyLevel`：`TICKFLOW_ASSIST_TICKFLOW_API_KEY_LEVEL` / `TICKFLOW_API_KEY_LEVEL`\n- `llmBaseUrl`：`TICKFLOW_ASSIST_LLM_BASE_URL` / `LLM_BASE_URL`\n- `llmApiKey`：`TICKFLOW_ASSIST_LLM_API_KEY` / `LLM_API_KEY`\n- `llmModel`：`TICKFLOW_ASSIST_LLM_MODEL` / `LLM_MODEL`\n- `mxSearchApiUrl`：`TICKFLOW_ASSIST_MX_SEARCH_API_URL` / `MX_SEARCH_API_URL`\n- `mxSearchApiKey`：`TICKFLOW_ASSIST_MX_SEARCH_API_KEY` / `MX_SEARCH_API_KEY` / `MX_APIKEY`\n- `jin10McpUrl`：`TICKFLOW_ASSIST_JIN10_MCP_URL` / `JIN10_MCP_URL`\n- `jin10ApiToken`：`TICKFLOW_ASSIST_JIN10_API_TOKEN` / `JIN10_API_TOKEN`\n\n## 功能\n\n- 自选股管理、日 K / 分钟 K 抓取与指标计算\n- 技术面、财务面、资讯面的综合分析\n- 实时监控、定时日更、收盘后复盘\n- 金十数据 24 小时快讯监控与自选关联提醒\n- 本地 LanceDB 数据留痕与分析结果查看\n\n## 运行说明\n\n- 插件会在本地 `databasePath` 下持久化 LanceDB 数据。\n- 后台服务会按配置执行定时日更、实时监控与金十数据快讯监控。\n- Python 子模块仅用于技术指标计算，不承担主业务流程。\n\n## 依赖与可选能力\n\n- [TickFlow](https://tickflow.org/auth/register?ref=BUJ54JEDGE)：提供日线、分钟线、实时行情与财务数据接口。\n- [金十数据 MCP](https://mcp.jin10.com/app/)：可选，用于 24 小时快讯流接入、自选关联筛选与事件驱动告警。\n- [东方财富妙想 Skills](https://marketing.dfcfs.com/views/finskillshub/)：可选，用于 `mx_search`、`mx_select_stock` 与非 `Expert` 财务链路的 lite 补充。\n\n## 仓库\n\n- GitHub: [robinspt/tickflow-assist](https://github.com/robinspt/tickflow-assist)\n",
+  "readme": "# TickFlow Assist\n\n基于 [OpenClaw](https://openclaw.ai) 的 A 股监控与分析插件。它使用 [TickFlow](https://tickflow.org/auth/register?ref=BUJ54JEDGE) 获取行情与财务数据，并可选接入 [金十数据 MCP](https://mcp.jin10.com/app/) 快讯流，结合 LLM 生成技术面、基本面、资讯面的综合判断，并把结果持久化到本地 LanceDB。\n\n最近更新：`v0.3.5` 对齐 OpenClaw `2026.4.11` metadata 与社区安装提示，修复源码升级时本地链接扫描 `node_modules` 失败的问题，并支持通过环境变量回退 TickFlow / LLM / MX / Jin10 配置。完整发布记录见 <https://github.com/robinspt/tickflow-assist/blob/main/CHANGELOG.md>。\n\n当前主线按 OpenClaw `v2026.3.31+` 对齐，并已验证社区安装在 `v2026.4.11` 上兼容。\n\n## 安装前准备\n\n在执行社区安装前，建议先确认你已经准备好以下配置：\n\n- 核心必需：`tickflowApiKey`、`llmApiKey`、`llmBaseUrl`、`llmModel`\n- 告警投递：`alertChannel`、`alertTarget`、`alertAccount`\n- 可选增强：`mxSearchApiKey`、`jin10ApiToken`\n\n其中，`configure-openclaw` 会把上述配置写入 `~/.openclaw/openclaw.json` 的 `plugins.entries[\"tickflow-assist\"].config`，插件启用后会在本地 `databasePath` 下持久化 LanceDB 数据，并运行监控 / 日更等后台服务。\n如果你不想把密钥写进配置文件，运行时也支持环境变量回退，优先级是 `openclaw.json / local.config.json` > 环境变量 > 默认值。\n常用环境变量：`TICKFLOW_ASSIST_TICKFLOW_API_KEY` / `TICKFLOW_API_KEY`、`TICKFLOW_ASSIST_LLM_API_KEY` / `LLM_API_KEY`、`TICKFLOW_ASSIST_LLM_BASE_URL` / `LLM_BASE_URL`、`TICKFLOW_ASSIST_LLM_MODEL` / `LLM_MODEL`、`TICKFLOW_ASSIST_MX_SEARCH_API_KEY` / `MX_SEARCH_API_KEY` / `MX_APIKEY`、`TICKFLOW_ASSIST_JIN10_API_TOKEN` / `JIN10_API_TOKEN`。\n如果你希望尽量避免把密钥落盘，推荐先把这些变量写进 `~/.openclaw/.env`，再运行配置向导补齐非密钥项。\n\n## 安装\n\n社区安装：\n\n```bash\nopenclaw plugins install tickflow-assist\nnode ~/.openclaw/extensions/tickflow-assist/dist/dev/tickflow-assist-cli.js configure-openclaw\ncd ~/.openclaw/extensions/tickflow-assist/python && uv sync\nopenclaw plugins enable tickflow-assist\nopenclaw config validate\nopenclaw gateway restart\n```\n\n安装阶段允许先落插件，再通过第二条命令写入 `tickflowApiKey`、`llmApiKey`、`llmBaseUrl`、`llmModel` 等正式配置。\n`configure-openclaw` 会写入 `~/.openclaw/openclaw.json` 中的 `plugins.entries[\"tickflow-assist\"].config`，并打印后续建议执行的命令；它不再自动执行 `openclaw`、`uv` 或系统包安装命令，也不会重新执行插件安装；如果你已经设置了环境变量，密钥项可留空，输入 `-` 可主动清空已有配置并切回环境变量。\n如果检测到 `plugins.installs[\"tickflow-assist\"]` 来自 `clawhub`，向导还会把被旧版本钉死的 `spec` 归一化为 `clawhub:tickflow-assist`，避免后续升级继续锁在旧版本。\n\n如果你希望先审阅配置，再只打印最少的后续步骤，可使用：\n\n```bash\nnode ~/.openclaw/extensions/tickflow-assist/dist/dev/tickflow-assist-cli.js configure-openclaw --no-enable --no-restart\n```\n\n如果你在 Linux 或 macOS 上需要 PNG 告警卡正常显示中文，请额外手动安装 `fontconfig` 与 Noto CJK 一类中文字体，例如：\n\n```bash\n# Debian / Ubuntu\nsudo apt-get update\nsudo apt-get install -y fontconfig fonts-noto-cjk\nfc-cache -fv\n\n# RHEL / Fedora / Rocky / AlmaLinux\nsudo dnf install -y fontconfig google-noto-sans-cjk-ttc-fonts\nfc-cache -fv\n\n# Arch / Manjaro\nsudo pacman -Sy --noconfirm fontconfig noto-fonts-cjk\nfc-cache -fv\n\n# Alpine\nsudo apk add fontconfig font-noto-cjk\nfc-cache -fv\n\n# macOS (Homebrew)\nbrew install fontconfig\nbrew install --cask font-noto-sans-cjk\nfc-cache -fv\n```\n\n社区安装后的升级方式：\n\n```bash\nopenclaw plugins update tickflow-assist\nopenclaw gateway restart\n```\n\n## 配置\n\n插件正式运行读取：\n\n```text\n~/.openclaw/openclaw.json\n```\n\n配置路径：\n\n```text\nplugins.entries[\"tickflow-assist\"].config\n```\n\n建议按完整功能显式填写以下字段，不要只填 API Key：\n\n- 核心运行：`tickflowApiKey`、`llmApiKey`、`llmBaseUrl`、`llmModel`\n- 本地数据：`databasePath`、`calendarFile`\n- 告警投递：`alertChannel`、`alertTarget`、`alertAccount`\n- 能力补充：`mxSearchApiKey`、`jin10ApiToken`\n\n其中，`mxSearchApiKey` 用于 `mx_search`、`mx_select_stock` 以及非 `Expert` 财务链路的 lite 补充；`jin10ApiToken` 用于 24 小时金十数据快讯监控；`jin10FlashNightAlert` 默认 `false`（开启夜间静默），设为 `true` 可恢复 24 小时快讯告警；`alertTarget`、`alertAccount` 建议在准备启用 `test_alert`、实时监控告警、金十数据快讯告警和定时通知前一并配好，避免配置不完整导致功能缺失。\n如果你使用环境变量，运行时支持以下回退：\n\n- `tickflowApiUrl`：`TICKFLOW_ASSIST_TICKFLOW_API_URL` / `TICKFLOW_API_URL`\n- `tickflowApiKey`：`TICKFLOW_ASSIST_TICKFLOW_API_KEY` / `TICKFLOW_API_KEY`\n- `tickflowApiKeyLevel`：`TICKFLOW_ASSIST_TICKFLOW_API_KEY_LEVEL` / `TICKFLOW_API_KEY_LEVEL`\n- `llmBaseUrl`：`TICKFLOW_ASSIST_LLM_BASE_URL` / `LLM_BASE_URL`\n- `llmApiKey`：`TICKFLOW_ASSIST_LLM_API_KEY` / `LLM_API_KEY`\n- `llmModel`：`TICKFLOW_ASSIST_LLM_MODEL` / `LLM_MODEL`\n- `mxSearchApiUrl`：`TICKFLOW_ASSIST_MX_SEARCH_API_URL` / `MX_SEARCH_API_URL`\n- `mxSearchApiKey`：`TICKFLOW_ASSIST_MX_SEARCH_API_KEY` / `MX_SEARCH_API_KEY` / `MX_APIKEY`\n- `jin10McpUrl`：`TICKFLOW_ASSIST_JIN10_MCP_URL` / `JIN10_MCP_URL`\n- `jin10ApiToken`：`TICKFLOW_ASSIST_JIN10_API_TOKEN` / `JIN10_API_TOKEN`\n\n## 功能\n\n- 自选股管理、日 K / 分钟 K 抓取与指标计算\n- 技术面、财务面、资讯面的综合分析\n- 实时监控、定时日更、收盘后复盘\n- 金十数据 24 小时快讯监控与自选关联提醒\n- 本地 LanceDB 数据留痕与分析结果查看\n\n## 运行说明\n\n- 插件会在本地 `databasePath` 下持久化 LanceDB 数据。\n- 后台服务会按配置执行定时日更、实时监控与金十数据快讯监控。\n- Python 子模块仅用于技术指标计算，不承担主业务流程。\n\n## 依赖与可选能力\n\n- [TickFlow](https://tickflow.org/auth/register?ref=BUJ54JEDGE)：提供日线、分钟线、实时行情与财务数据接口。\n- [金十数据 MCP](https://mcp.jin10.com/app/)：可选，用于 24 小时快讯流接入、自选关联筛选与事件驱动告警。\n- [东方财富妙想 Skills](https://marketing.dfcfs.com/views/finskillshub/)：可选，用于 `mx_search`、`mx_select_stock` 与非 `Expert` 财务链路的 lite 补充。\n\n## 仓库\n\n- GitHub: [robinspt/tickflow-assist](https://github.com/robinspt/tickflow-assist)\n",
   "readmeFilename": "README.md"
 }

package/skills/stock-analysis/SKILL.md

@@ -7,12 +7,11 @@ metadata:
     requires:
       config:
         - plugins.entries.tickflow-assist.enabled
-        - plugins.entries.tickflow-assist.config.tickflowApiKey
-        - plugins.entries.tickflow-assist.config.llmApiKey
 ---
 # 股票分析与监控
 
 这是 TickFlow Assist 插件内置的技能，用于通过插件工具完成 A 股自选股管理、日线更新、分钟K抓取、技术分析、关键价位回测、实时监控、定时日更、结果查看与告警测试。
+运行前需要提供 TickFlow / LLM 等凭证；这些值既可以来自 `plugins.entries["tickflow-assist"].config`，也可以来自文档约定的环境变量 fallback，不要求必须明文写在插件配置里。
 
 此技能随插件加载，不需要手动复制到 workspace。