tickflow-assist 0.2.11 → 0.2.13

package/README.md

@@ -2,7 +2,7 @@
 
 基于 [OpenClaw](https://openclaw.ai) 的 A 股监控与分析插件。它使用 [TickFlow](https://tickflow.org/auth/register?ref=BUJ54JEDGE) 获取行情与财务数据，结合 LLM 生成技术面、基本面、资讯面的综合判断，并把结果持久化到本地 LanceDB。
 
-最近更新：`v0.2.11` 优化复盘/告警文本样式，接入 PNG 告警卡发送与临时文件清理，并按 A 股习惯调整涨跌主色。
+最近更新：`v0.2.13` 在 `configure-openclaw` 与一键安装脚本中加入 Linux 中文字体自动安装，减少 VPS 上 PNG 告警卡中文乱码；并补充 GitHub README 效果预览图。
 
 ## 安装
 
@@ -13,6 +13,9 @@ openclaw plugins install tickflow-assist
 npx -y tickflow-assist configure-openclaw
 ```
 
+安装阶段允许先落插件，再通过第二条命令写入 `tickflowApiKey`、`llmApiKey` 等正式配置。
+在 Linux 上，`configure-openclaw` 还会 best-effort 安装 PNG 告警卡所需的中文字体；如需跳过，可追加 `--no-font-setup`。
+
 第二条命令会写入 `~/.openclaw/openclaw.json` 中的 `plugins.entries["tickflow-assist"].config`，并默认执行：
 
 - `openclaw plugins enable tickflow-assist`

package/dist/bootstrap.js

@@ -152,7 +152,7 @@ export function createAppContext(config, options = {}) {
             startMonitorTool(monitorService, runtime),
             stopDailyUpdateTool(dailyUpdateWorker, runtime),
             stopMonitorTool(monitorService, runtime),
-            testAlertTool(alertService),
+            testAlertTool(alertService, alertMediaService),
             updateAllTool(dailyUpdateWorker),
             viewAnalysisTool(analysisViewService),
         ],

package/dist/dev/tickflow-assist-cli.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { spawnSync } from "node:child_process";
+import { readFileSync } from "node:fs";
 import { access, mkdir, readFile, writeFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
@@ -38,6 +39,7 @@ Options:
   --no-enable                 Do not run 'openclaw plugins enable'
   --no-restart                Do not run 'openclaw gateway restart'
   --no-python-setup           Do not run 'uv sync' for Python dependencies
+  --no-font-setup             Do not try to install Linux Chinese fonts for PNG alerts
   --openclaw-bin <path>       OpenClaw CLI binary, default: openclaw
   --tickflow-api-key <key>
   --tickflow-api-key-level <Free|Start|Pro|Expert>
@@ -61,6 +63,7 @@ function parseArgs(argv) {
         restart: true,
         enable: true,
         pythonSetup: true,
+        fontSetup: true,
         openclawBin: DEFAULTS.openclawCliBin,
         overrides: {},
     };
@@ -115,6 +118,9 @@ function parseArgs(argv) {
             case "--no-python-setup":
                 options.pythonSetup = false;
                 break;
+            case "--no-font-setup":
+                options.fontSetup = false;
+                break;
             case "--no-enable":
                 options.enable = false;
                 break;
@@ -623,6 +629,162 @@ async function setupPythonDeps(pythonWorkdir, nonInteractive) {
     }
     console.log("Python dependencies installed successfully.");
 }
+function isCommandAvailable(command) {
+    const result = spawnSync("which", [command], { stdio: "ignore" });
+    return result.status === 0;
+}
+function isRootUser() {
+    return typeof process.getuid === "function" && process.getuid() === 0;
+}
+function hasChineseFonts() {
+    const result = spawnSync("fc-list", [":lang=zh", "family"], { encoding: "utf-8" });
+    return result.status === 0 && Boolean(result.stdout.trim());
+}
+function detectLinuxDistro() {
+    try {
+        const raw = readFileSync("/etc/os-release", "utf-8");
+        const record = Object.fromEntries(raw
+            .split("\n")
+            .map((line) => line.trim())
+            .filter(Boolean)
+            .filter((line) => !line.startsWith("#") && line.includes("="))
+            .map((line) => {
+            const index = line.indexOf("=");
+            const key = line.slice(0, index);
+            const value = line.slice(index + 1).replace(/^"/, "").replace(/"$/, "");
+            return [key, value];
+        }));
+        const ids = [
+            String(record.ID ?? "").toLowerCase(),
+            ...String(record.ID_LIKE ?? "")
+                .toLowerCase()
+                .split(/\s+/)
+                .filter(Boolean),
+        ];
+        if (ids.some((value) => ["debian", "ubuntu"].includes(value))) {
+            return "debian";
+        }
+        if (ids.some((value) => ["rhel", "fedora", "centos", "rocky", "almalinux"].includes(value))) {
+            return "rhel";
+        }
+        if (ids.some((value) => ["arch", "manjaro"].includes(value))) {
+            return "arch";
+        }
+        if (ids.includes("alpine")) {
+            return "alpine";
+        }
+    }
+    catch {
+        // fall through
+    }
+    return "unknown";
+}
+function getManualFontCommands(distro) {
+    switch (distro) {
+        case "debian":
+            return ["sudo apt-get update", "sudo apt-get install -y fontconfig fonts-noto-cjk", "fc-cache -fv"];
+        case "rhel":
+            return [
+                "sudo dnf install -y fontconfig google-noto-sans-cjk-ttc-fonts",
+                "fc-cache -fv",
+            ];
+        case "arch":
+            return ["sudo pacman -Sy --noconfirm fontconfig noto-fonts-cjk", "fc-cache -fv"];
+        case "alpine":
+            return ["sudo apk add fontconfig font-noto-cjk", "fc-cache -fv"];
+        default:
+            return [
+                "请安装 fontconfig 和任意可用的中文字体包，例如 Noto Sans CJK",
+                "安装后执行: fc-cache -fv",
+            ];
+    }
+}
+function buildPrivilegedCommand(argv, nonInteractive) {
+    if (isRootUser()) {
+        return argv;
+    }
+    if (!isCommandAvailable("sudo")) {
+        return null;
+    }
+    return nonInteractive ? ["sudo", "-n", ...argv] : ["sudo", ...argv];
+}
+function runSetupCommand(argv, description) {
+    console.log(description);
+    const result = spawnSync(argv[0], argv.slice(1), { stdio: "inherit" });
+    if (result.error) {
+        console.warn(`Warning: failed to run ${description}: ${result.error.message}`);
+        return false;
+    }
+    if (result.status !== 0) {
+        console.warn(`Warning: ${description} exited with status ${result.status}`);
+        return false;
+    }
+    return true;
+}
+async function setupLinuxChineseFonts(nonInteractive) {
+    if (process.platform !== "linux") {
+        return;
+    }
+    if (!isCommandAvailable("fc-list")) {
+        console.warn("Warning: fontconfig is not installed; PNG alerts may not render Chinese text correctly.");
+    }
+    else if (hasChineseFonts()) {
+        console.log("Chinese fonts detected for PNG alert cards.");
+        return;
+    }
+    const distro = detectLinuxDistro();
+    console.log("Chinese fonts not detected. TickFlow Assist will try to install Noto CJK fonts for PNG alert cards.");
+    const attempts = [];
+    switch (distro) {
+        case "debian":
+            attempts.push(["apt-get", "update"]);
+            attempts.push(["apt-get", "install", "-y", "fontconfig", "fonts-noto-cjk"]);
+            break;
+        case "rhel":
+            attempts.push(["dnf", "install", "-y", "fontconfig", "google-noto-sans-cjk-ttc-fonts"]);
+            attempts.push(["dnf", "install", "-y", "fontconfig", "google-noto-cjk-fonts"]);
+            attempts.push(["yum", "install", "-y", "fontconfig", "google-noto-sans-cjk-ttc-fonts"]);
+            attempts.push(["yum", "install", "-y", "fontconfig", "google-noto-cjk-fonts"]);
+            break;
+        case "arch":
+            attempts.push(["pacman", "-Sy", "--noconfirm", "fontconfig", "noto-fonts-cjk"]);
+            break;
+        case "alpine":
+            attempts.push(["apk", "add", "fontconfig", "font-noto-cjk"]);
+            break;
+        default:
+            break;
+    }
+    let attemptedInstall = false;
+    for (const baseArgv of attempts) {
+        if (!isCommandAvailable(baseArgv[0])) {
+            continue;
+        }
+        const argv = buildPrivilegedCommand(baseArgv, nonInteractive);
+        if (!argv) {
+            break;
+        }
+        attemptedInstall = true;
+        if (!runSetupCommand(argv, `Running ${argv.join(" ")}`)) {
+            continue;
+        }
+        if (isCommandAvailable("fc-cache")) {
+            runSetupCommand(["fc-cache", "-fv"], "Refreshing font cache with fc-cache -fv");
+        }
+        if (isCommandAvailable("fc-list") && hasChineseFonts()) {
+            console.log("Chinese fonts installed successfully.");
+            return;
+        }
+    }
+    console.warn("Warning: automatic Chinese font setup did not complete.");
+    if (!attemptedInstall && nonInteractive) {
+        console.warn("Non-interactive mode skipped any sudo password prompt.");
+    }
+    console.warn("Manual install examples:");
+    for (const command of getManualFontCommands(distro)) {
+        console.warn(`  ${command}`);
+    }
+}
 async function configureOpenClaw(options) {
     const configPath = resolveOpenClawConfigPath(options.configPath);
     const stateDir = resolveStateDir(configPath);
@@ -636,6 +798,9 @@ async function configureOpenClaw(options) {
     if (options.pythonSetup) {
         await setupPythonDeps(config.pythonWorkdir, options.nonInteractive);
     }
+    if (options.fontSetup) {
+        await setupLinuxChineseFonts(options.nonInteractive);
+    }
     applyPluginConfig(root, config, target);
     const backupPath = await writeConfig(configPath, root);
     console.log("");

package/dist/plugin-commands.js

@@ -208,7 +208,7 @@ export function registerPluginCommands(api, tools, app) {
         },
         {
             name: "ta_testalert",
-            description: "发送一条测试告警，不经过 AI 对话。",
+            description: "发送一条文本 + PNG 测试告警，不经过 AI 对话。",
             requireAuth: true,
             handler: async () => ({
                 text: await runToolText(testAlert),

package/dist/tools/test-alert.tool.d.ts

@@ -1,5 +1,6 @@
 import { AlertService } from "../services/alert-service.js";
-export declare function testAlertTool(alertService: AlertService): {
+import { AlertMediaService } from "../services/alert-media-service.js";
+export declare function testAlertTool(alertService: AlertService, alertMediaService: AlertMediaService): {
     name: string;
     description: string;
     optional: boolean;

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

@@ -1,21 +1,101 @@
 import { formatChinaDateTime } from "../utils/china-time.js";
-export function testAlertTool(alertService) {
+export function testAlertTool(alertService, alertMediaService) {
     return {
         name: "test_alert",
-        description: "Send a test alert through the configured OpenClaw alert delivery path.",
+        description: "Send a text plus PNG test alert through the configured OpenClaw alert delivery path.",
         optional: true,
         async run() {
-            const ok = await alertService.send(alertService.formatSystemNotification("🧪 TickFlow 测试告警", [
-                `时间: ${formatChinaDateTime()}`,
-                "说明: 这是一条手动触发的测试消息，用于验证 channel 投递链路正常。",
-            ]));
-            if (ok) {
-                return "✅ 测试告警发送成功";
+            const now = formatChinaDateTime();
+            const message = alertService.formatSystemNotification("🧪 TickFlow 测试告警", [
+                `时间: ${now}`,
+                "说明: 这是一条手动触发的测试消息，用于验证文本与 PNG 告警卡投递链路正常。",
+            ]);
+            let mediaFile = null;
+            try {
+                mediaFile = await alertMediaService.writeAlertCard({
+                    symbol: "000001.SZ",
+                    ruleName: "test_alert",
+                    image: buildTestAlertImage(now),
+                });
             }
-            const detail = alertService.getLastError();
-            return detail
-                ? `❌ 测试告警发送失败\n原因: ${detail}`
-                : "❌ 测试告警发送失败";
+            catch (error) {
+                const textOnlyResult = await alertService.sendWithResult({ message });
+                if (textOnlyResult.ok) {
+                    return [
+                        "⚠️ 测试告警文本已发送，但 PNG 生成失败",
+                        `原因: ${formatErrorMessage(error)}`,
+                    ].join("\n");
+                }
+                const detail = textOnlyResult.error ?? alertService.getLastError() ?? "未知错误";
+                return [
+                    "❌ 测试告警发送失败",
+                    `PNG 生成失败: ${formatErrorMessage(error)}`,
+                    `文本发送失败: ${detail}`,
+                ].join("\n");
+            }
+            try {
+                const result = await alertService.sendWithResult({
+                    message,
+                    mediaPath: mediaFile.filePath,
+                    mediaLocalRoots: mediaFile.mediaLocalRoots,
+                    filename: mediaFile.filename,
+                });
+                if (result.ok && result.mediaDelivered) {
+                    return "✅ 测试告警发送成功（文本 + PNG）";
+                }
+                if (result.ok) {
+                    return "⚠️ 测试告警文本已发送，但 PNG 未送达，已回退为纯文本";
+                }
+                const detail = result.error ?? alertService.getLastError();
+                return detail
+                    ? `❌ 测试告警发送失败\n原因: ${detail}`
+                    : "❌ 测试告警发送失败";
+            }
+            finally {
+                if (mediaFile) {
+                    await alertMediaService.removeFile(mediaFile.filePath).catch(() => { });
+                }
+            }
+        },
+    };
+}
+function buildTestAlertImage(now) {
+    const triggerPrice = 12.18;
+    const currentPrice = 12.36;
+    return {
+        tone: "breakthrough",
+        alertLabel: "测试告警",
+        name: "平安银行",
+        symbol: "000001.SZ",
+        timestampLabel: `测试告警 | ${now.slice(0, 16)}`,
+        currentPrice,
+        triggerPrice,
+        changePct: 2.15,
+        distancePct: ((currentPrice - triggerPrice) / triggerPrice) * 100,
+        costPrice: 11.92,
+        profitPct: ((currentPrice - 11.92) / 11.92) * 100,
+        note: "用于验证 PNG 告警卡发送、媒体上传与纯文本回退链路。",
+        points: [
+            { time: "09:30", price: 12.02 },
+            { time: "10:00", price: 12.08 },
+            { time: "10:30", price: 12.12 },
+            { time: "11:30", price: 12.15 },
+            { time: "13:00", price: 12.19 },
+            { time: "14:00", price: 12.27 },
+            { time: "15:00", price: currentPrice },
+        ],
+        levels: {
+            stopLoss: 11.86,
+            support: 12.08,
+            resistance: 12.30,
+            breakthrough: triggerPrice,
+            takeProfit: 12.68,
         },
     };
 }
+function formatErrorMessage(error) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    return String(error);
+}

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "tickflow-assist",
   "name": "TickFlow Assist",
-  "version": "0.2.11",
+  "version": "0.2.13",
   "description": "A-share watchlist analysis, monitoring, and alert delivery powered by TickFlow and OpenClaw.",
   "skills": [
     "skills"
@@ -9,7 +9,6 @@
   "configSchema": {
     "type": "object",
     "additionalProperties": false,
-    "required": ["tickflowApiKey", "llmApiKey"],
     "properties": {
       "tickflowApiUrl": {
         "type": "string",
@@ -19,7 +18,7 @@
       "tickflowApiKey": {
         "type": "string",
         "minLength": 1,
-        "description": "Required. TickFlow API key used for market and financial data."
+        "description": "TickFlow API key used for market and financial data. Required before using the plugin."
       },
       "tickflowApiKeyLevel": {
         "type": "string",
@@ -45,7 +44,7 @@
       "llmApiKey": {
         "type": "string",
         "minLength": 1,
-        "description": "Required. API key for the analysis model endpoint configured in llmBaseUrl."
+        "description": "API key for the analysis model endpoint configured in llmBaseUrl. Required before using analysis features."
       },
       "llmModel": {
         "type": "string",
@@ -114,7 +113,7 @@
   "uiHints": {
     "tickflowApiKey": {
       "label": "TickFlow API Key",
-      "help": "Required for TickFlow market and financial data.",
+      "help": "Required before using TickFlow market and financial data.",
       "sensitive": true
     },
     "tickflowApiKeyLevel": {
@@ -132,7 +131,7 @@
     },
     "llmApiKey": {
       "label": "LLM API Key",
-      "help": "Required for analysis model requests.",
+      "help": "Required before using analysis model requests.",
       "sensitive": true
     },
     "llmModel": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tickflow-assist",
-  "version": "0.2.11",
+  "version": "0.2.13",
   "description": "OpenClaw plugin for TickFlow-based A-share analysis, monitoring, and alerting.",
   "license": "MIT",
   "type": "module",
@@ -29,7 +29,7 @@
     "dev": "tsc -p tsconfig.json --watch",
     "prepack": "npm run build && node ./scripts/prepare-package-assets.mjs",
     "postpack": "node ./scripts/restore-package-assets.mjs",
-    "test": "npm run build && node --test dist/plugin-registration.test.js",
+    "test": "npm run build && node --test dist/plugin-registration.test.js dist/tools/test-alert.tool.test.js",
     "community-setup": "node dist/dev/tickflow-assist-cli.js configure-openclaw",
     "tool": "node dist/dev/run-tool.js",
     "monitor-loop": "node dist/dev/run-monitor-loop.js",

package/skills/usage-help/SKILL.md

@@ -83,6 +83,7 @@ TickFlow Assist 常用指令：
 
 14. 测试告警
 `测试告警`
+会发送一条文本 + PNG 告警卡测试消息
 
 15. 查看数据库表
 `数据库里有哪些表`