@usethink/cf-core 0.3.0

package/features/telegram-miniapp/index.ts

@@ -0,0 +1,109 @@
+/**
+ * telegram-miniapp — Telegram Mini App 前端集成
+ *
+ * 提供 Vue 3 Composable，用于在 Telegram Mini App 中：
+ * - 检测运行平台（Telegram / H5 × Mobile / Desktop）
+ * - 应用 Telegram 主题变量到 CSS
+ * - 控制 MainButton / BackButton
+ * - 获取用户信息
+ *
+ * 来源：eshop frontend/src/composables/useTelegram.ts + usePlatform.ts
+ *
+ * 注意：此插件为前端代码，仅在 Vue 3 项目中使用。
+ * 非 Vue 项目可参考实现自行适配。
+ */
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// 平台检测（纯函数，无 Vue 依赖）
+// ═══════════════════════════════════════════════════════════════════════════════
+
+export type Platform = "telegram-mobile" | "telegram-desktop" | "h5-mobile" | "h5-desktop";
+
+export interface PlatformInfo {
+  platform: Platform;
+  isTelegram: boolean;
+  isMobile: boolean;
+  isDesktop: boolean;
+}
+
+/**
+ * 检测当前运行平台
+ */
+export function detectPlatform(): PlatformInfo {
+  const isTg = typeof window !== "undefined" && !!(window as any).Telegram?.WebApp;
+  const ua = typeof navigator !== "undefined" ? navigator.userAgent : "";
+  const isMobileUA = /Android|iPhone|iPad|iPod|webOS|BlackBerry|IEMobile|Opera Mini/i.test(ua);
+
+  const platform: Platform = isTg
+    ? isMobileUA ? "telegram-mobile" : "telegram-desktop"
+    : isMobileUA ? "h5-mobile" : "h5-desktop";
+
+  return {
+    platform,
+    isTelegram: isTg,
+    isMobile: isMobileUA,
+    isDesktop: !isMobileUA,
+  };
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// Telegram 主题映射
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/** Telegram 主题参数 → CSS 变量映射表 */
+export const THEME_MAP: Record<string, string> = {
+  bg_color: "--tg-bg",
+  text_color: "--tg-text",
+  hint_color: "--tg-hint",
+  link_color: "--tg-link",
+  button_color: "--tg-btn",
+  button_text_color: "--tg-btn-text",
+  secondary_bg_color: "--tg-secondary-bg",
+  header_bg_color: "--tg-header-bg",
+  bottom_bar_bg_color: "--tg-bottom-bar-bg",
+  top_bar_bg_color: "--tg-top-bar-bg",
+  destructive_text_color: "--tg-destructive",
+  section_bg_color: "--tg-section-bg",
+};
+
+/**
+ * 将 Telegram 主题参数应用到 CSS 变量
+ */
+export function applyTelegramTheme(params: Record<string, string>): void {
+  if (typeof document === "undefined") return;
+  const root = document.documentElement;
+  for (const [tgKey, cssVar] of Object.entries(THEME_MAP)) {
+    const value = params[tgKey];
+    if (value) root.style.setProperty(cssVar, value);
+  }
+}
+
+/**
+ * 初始化 Telegram WebApp SDK
+ *
+ * @returns Telegram WebApp 实例或 null（非 Telegram 环境）
+ */
+export function initTelegramWebApp(): any | null {
+  if (typeof window === "undefined") return null;
+  const webApp = (window as any).Telegram?.WebApp;
+  if (!webApp) return null;
+
+  webApp.ready();
+  webApp.expand();
+  applyTelegramTheme(webApp.themeParams || {});
+
+  webApp.onEvent?.("themeChanged", () => {
+    applyTelegramTheme(webApp.themeParams || {});
+  });
+
+  return webApp;
+}
+
+/**
+ * 获取 Telegram 用户信息（从 initDataUnsafe）
+ */
+export function getTelegramUser(): { id: number; firstName: string; lastName?: string; username?: string } | null {
+  if (typeof window === "undefined") return null;
+  const webApp = (window as any).Telegram?.WebApp;
+  return webApp?.initDataUnsafe?.user ?? null;
+}

package/features/telegram-miniapp/tests/index.test.ts

@@ -0,0 +1,11 @@
+import { describe, it, expect } from "vitest";
+import { detectPlatform } from "../index";
+
+describe("detectPlatform", () => {
+  it("非浏览器环境返回 h5-desktop", () => {
+    // Node.js 测试环境无 window/navigator
+    const info = detectPlatform();
+    expect(info.isTelegram).toBe(false);
+    expect(info.platform).toBe("h5-desktop");
+  });
+});

package/features/thompson-router/index.ts

@@ -0,0 +1,243 @@
+/**
+ * thompson-router — Thompson Sampling 智能路由插件
+ *
+ * 基于贝叶斯多臂老虎机算法的渠道选择器：
+ * - 自动探索-利用平衡（新渠道多尝试，好渠道多使用）
+ * - Beta 分布建模成功率（α=成功次数, β=失败次数）
+ * - 自动故障转移（选中渠道失败时切换到下一候选）
+ * - 可选多维度评分（成功率+价格+延迟+容量+趋势）
+ *
+ * 来源：vcode src/services/channel-router.ts + channel-scorer.ts
+ */
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// 类型定义
+// ═══════════════════════════════════════════════════════════════════════════════
+
+export interface ChannelCandidate {
+  id: string;
+  name: string;
+  /** Beta 分布参数 α（成功次数 + 先验） */
+  alpha: number;
+  /** Beta 分布参数 β（失败次数 + 先验） */
+  beta: number;
+  /** 是否启用 */
+  enabled: boolean;
+  /** 优先级权重（越小越优先，用于同分时排序） */
+  priority?: number;
+  /** 扩展元数据 */
+  metadata?: Record<string, unknown>;
+}
+
+export interface RouteDecision {
+  /** 选中的渠道 ID */
+  channelId: string;
+  /** 渠道名称 */
+  channelName: string;
+  /** 采样得分 */
+  score: number;
+  /** 候选数量 */
+  candidateCount: number;
+  /** 决策时间 */
+  timestamp: string;
+}
+
+export interface ThompsonRouterConfig {
+  /** Beta 分布先验参数（默认 α=1, β=1，即均匀分布） */
+  priorAlpha?: number;
+  priorBeta?: number;
+  /** 最小样本量（低于此值的渠道会被优先探索） */
+  minSamples?: number;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// 统计采样工具
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/** Marsaglia-Tsang 方法生成 Gamma 分布随机数 */
+function sampleGamma(shape: number): number {
+  if (shape < 1) {
+    return sampleGamma(shape + 1) * Math.pow(Math.random(), 1 / shape);
+  }
+  const d = shape - 1 / 3;
+  const c = 1 / Math.sqrt(9 * d);
+  while (true) {
+    let x: number;
+    let v: number;
+    do {
+      x = gaussianRandom();
+      v = 1 + c * x;
+    } while (v <= 0);
+    v = v * v * v;
+    const u = Math.random();
+    if (u < 1 - 0.0331 * x * x * x * x) return d * v;
+    if (Math.log(u) < 0.5 * x * x + d * (1 - v + Math.log(v))) return d * v;
+  }
+}
+
+/** Box-Muller 变换生成标准正态分布 */
+function gaussianRandom(): number {
+  let u = 0, v = 0;
+  while (u === 0) u = Math.random();
+  while (v === 0) v = Math.random();
+  return Math.sqrt(-2 * Math.log(u)) * Math.cos(2 * Math.PI * v);
+}
+
+/** 从 Beta(α, β) 分布采样 */
+function sampleBeta(alpha: number, beta: number): number {
+  const x = sampleGamma(alpha);
+  const y = sampleGamma(beta);
+  return x / (x + y);
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// ThompsonRouter
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Thompson Sampling 渠道路由器
+ *
+ * @example
+ * ```ts
+ * import { ThompsonRouter } from "@usethink/cf-core/plugins/thompson-router";
+ *
+ * const router = new ThompsonRouter();
+ *
+ * // 从数据库加载候选渠道
+ * const candidates: ChannelCandidate[] = [
+ *   { id: "5sim", name: "5sim.net", alpha: 15, beta: 3, enabled: true },
+ *   { id: "grizzly", name: "GrizzlySMS", alpha: 10, beta: 5, enabled: true },
+ * ];
+ *
+ * // 选择最佳渠道
+ * const decision = router.select(candidates);
+ * console.log(decision.channelName); // 大概率选中 5sim（成功率更高）
+ *
+ * // 反馈结果（更新 Beta 参数）
+ * router.recordSuccess(candidates, "5sim"); // α += 1
+ * router.recordFailure(candidates, "5sim"); // β += 1
+ * ```
+ */
+export class ThompsonRouter {
+  readonly name = "thompson-router";
+  readonly version = "0.1.0";
+
+  private config: Required<ThompsonRouterConfig>;
+
+  constructor(config: ThompsonRouterConfig = {}) {
+    this.config = {
+      priorAlpha: config.priorAlpha ?? 1,
+      priorBeta: config.priorBeta ?? 1,
+      minSamples: config.minSamples ?? 5,
+    };
+  }
+
+  /**
+   * Thompson Sampling 选择最佳渠道
+   */
+  select(candidates: ChannelCandidate[]): RouteDecision {
+    const eligible = candidates.filter((c) => c.enabled);
+    if (eligible.length === 0) {
+      throw new Error("No eligible channel candidates");
+    }
+
+    if (eligible.length === 1) {
+      return {
+        channelId: eligible[0].id,
+        channelName: eligible[0].name,
+        score: 1,
+        candidateCount: 1,
+        timestamp: new Date().toISOString(),
+      };
+    }
+
+    // 优先探索样本不足的渠道
+    const underExplored = eligible.filter(
+      (c) => (c.alpha + c.beta) < this.config.minSamples + this.config.priorAlpha + this.config.priorBeta,
+    );
+    const pool = underExplored.length > 0 ? underExplored : eligible;
+
+    // 对每个候选渠道从 Beta(α, β) 采样
+    let bestCandidate = pool[0];
+    let bestScore = -1;
+
+    for (const candidate of pool) {
+      const alpha = candidate.alpha + this.config.priorAlpha;
+      const beta = candidate.beta + this.config.priorBeta;
+      const score = sampleBeta(alpha, beta);
+
+      if (score > bestScore || (score === bestScore && (candidate.priority ?? 100) < (bestCandidate.priority ?? 100))) {
+        bestScore = score;
+        bestCandidate = candidate;
+      }
+    }
+
+    return {
+      channelId: bestCandidate.id,
+      channelName: bestCandidate.name,
+      score: bestScore,
+      candidateCount: eligible.length,
+      timestamp: new Date().toISOString(),
+    };
+  }
+
+  /**
+   * 选择渠道并支持自动故障转移
+   */
+  selectWithFailover(
+    candidates: ChannelCandidate[],
+    maxAttempts = 3,
+  ): RouteDecision[] {
+    const decisions: RouteDecision[] = [];
+    const remaining = [...candidates];
+
+    for (let i = 0; i < Math.min(maxAttempts, remaining.length); i++) {
+      const decision = this.select(remaining);
+      decisions.push(decision);
+      // 移除已选渠道，下次选择时跳过
+      const idx = remaining.findIndex((c) => c.id === decision.channelId);
+      if (idx >= 0) remaining.splice(idx, 1);
+      if (remaining.length === 0) break;
+    }
+
+    return decisions;
+  }
+
+  /**
+   * 记录成功（更新 α 参数）
+   */
+  recordSuccess(candidates: ChannelCandidate[], channelId: string): void {
+    const channel = candidates.find((c) => c.id === channelId);
+    if (channel) channel.alpha += 1;
+  }
+
+  /**
+   * 记录失败（更新 β 参数）
+   */
+  recordFailure(candidates: ChannelCandidate[], channelId: string): void {
+    const channel = candidates.find((c) => c.id === channelId);
+    if (channel) channel.beta += 1;
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// Wilson Score 成功率估计（小样本更可靠）
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Wilson Score Interval — 小样本成功率估计
+ *
+ * 比简单 success/total 更可靠，被 Reddit/Google 等用于排序。
+ *
+ * @param successes 成功次数
+ * @param total 总次数
+ * @param z 置信水平（默认 1.96 = 95%）
+ */
+export function wilsonScore(successes: number, total: number, z = 1.96): number {
+  if (total === 0) return 0;
+  const p = successes / total;
+  const denominator = 1 + z * z / total;
+  const centre = p + z * z / (2 * total);
+  const adjustment = z * Math.sqrt((p * (1 - p) + z * z / (4 * total)) / total);
+  return (centre - adjustment) / denominator;
+}

package/features/thompson-router/tests/index.test.ts

@@ -0,0 +1,93 @@
+import { describe, it, expect } from "vitest";
+import { ThompsonRouter, wilsonScore } from "../index";
+import type { ChannelCandidate } from "../index";
+
+describe("ThompsonRouter", () => {
+  const candidates: ChannelCandidate[] = [
+    { id: "ch-a", name: "Channel A", alpha: 20, beta: 2, enabled: true },
+    { id: "ch-b", name: "Channel B", alpha: 5, beta: 15, enabled: true },
+    { id: "ch-c", name: "Channel C", alpha: 1, beta: 1, enabled: true },
+  ];
+
+  it("单渠道直接返回", () => {
+    const router = new ThompsonRouter();
+    const single = [{ ...candidates[0] }];
+    const decision = router.select(single);
+    expect(decision.channelId).toBe("ch-a");
+    expect(decision.candidateCount).toBe(1);
+  });
+
+  it("过滤禁用渠道", () => {
+    const router = new ThompsonRouter();
+    const mixed = [
+      { id: "disabled", name: "Disabled", alpha: 100, beta: 0, enabled: false },
+      { id: "enabled", name: "Enabled", alpha: 1, beta: 1, enabled: true },
+    ];
+    const decision = router.select(mixed);
+    expect(decision.channelId).toBe("enabled");
+  });
+
+  it("无可用渠道抛错", () => {
+    const router = new ThompsonRouter();
+    expect(() => router.select([
+      { id: "x", name: "X", alpha: 1, beta: 1, enabled: false },
+    ])).toThrow("No eligible");
+  });
+
+  it("selectWithFailover 返回多个决策", () => {
+    const router = new ThompsonRouter();
+    const decisions = router.selectWithFailover([...candidates], 2);
+    expect(decisions.length).toBe(2);
+    expect(decisions[0].channelId).not.toBe(decisions[1].channelId);
+  });
+
+  it("recordSuccess 增加 alpha", () => {
+    const router = new ThompsonRouter();
+    const c = [{ id: "x", name: "X", alpha: 5, beta: 5, enabled: true }];
+    router.recordSuccess(c, "x");
+    expect(c[0].alpha).toBe(6);
+  });
+
+  it("recordFailure 增加 beta", () => {
+    const router = new ThompsonRouter();
+    const c = [{ id: "x", name: "X", alpha: 5, beta: 5, enabled: true }];
+    router.recordFailure(c, "x");
+    expect(c[0].beta).toBe(6);
+  });
+
+  it("高成功率渠道被选中概率更大", () => {
+    const router = new ThompsonRouter();
+    const high = { id: "high", name: "High", alpha: 100, beta: 5, enabled: true };
+    const low = { id: "low", name: "Low", alpha: 5, beta: 100, enabled: true };
+    let highCount = 0;
+    for (let i = 0; i < 100; i++) {
+      const d = router.select([{ ...high }, { ...low }]);
+      if (d.channelId === "high") highCount++;
+    }
+    // Thompson Sampling 应该大部分时间选中高成功率渠道
+    expect(highCount).toBeGreaterThan(70);
+  });
+});
+
+describe("wilsonScore", () => {
+  it("无数据返回 0", () => {
+    expect(wilsonScore(0, 0)).toBe(0);
+  });
+
+  it("100% 成功率", () => {
+    const score = wilsonScore(100, 100);
+    expect(score).toBeGreaterThan(0.95);
+  });
+
+  it("小样本比大样本保守", () => {
+    const small = wilsonScore(3, 3); // 100% but only 3 samples
+    const large = wilsonScore(100, 100); // 100% with 100 samples
+    expect(small).toBeLessThan(large);
+  });
+
+  it("50% 成功率", () => {
+    const score = wilsonScore(50, 100);
+    expect(score).toBeGreaterThan(0.35);
+    expect(score).toBeLessThan(0.55);
+  });
+});

package/features/webhook/index.ts

@@ -0,0 +1,183 @@
+/**
+ * webhook — Webhook 通知插件
+ *
+ * 支持：
+ * - 多 URL 通知（逗号分隔）
+ * - HMAC-SHA256 签名
+ * - 5s 超时 + 最多 2 次重试
+ * - 事件类型过滤
+ *
+ * 来源：xtools src/services/webhook.ts
+ */
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// 类型定义
+// ═══════════════════════════════════════════════════════════════════════════════
+
+export interface WebhookConfig {
+  /** 通知 URL（支持多个，逗号分隔） */
+  urls: string;
+  /** HMAC-SHA256 签名密钥（可选） */
+  secret?: string;
+  /** 请求超时（毫秒，默认 5000） */
+  timeoutMs?: number;
+  /** 最大重试次数（默认 2） */
+  maxRetries?: number;
+}
+
+export interface WebhookPayload {
+  /** 事件类型 */
+  event: string;
+  /** 事件时间 ISO 8601 */
+  timestamp: string;
+  /** 事件数据 */
+  data: Record<string, unknown>;
+}
+
+export interface WebhookResult {
+  ok: boolean;
+  url: string;
+  status?: number;
+  error?: string;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// WebhookService
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Webhook 通知服务
+ *
+ * @example
+ * ```ts
+ * import { WebhookService } from "@usethink/cf-core/plugins/webhook";
+ *
+ * const webhook = new WebhookService({
+ *   urls: "https://hooks.example.com/a,https://hooks.example.com/b",
+ *   secret: "my-secret",
+ * });
+ *
+ * await webhook.notify("order.paid", { orderId: "123", amount: 9900 });
+ * ```
+ */
+export class WebhookService {
+  readonly name = "webhook";
+  readonly version = "0.1.0";
+
+  private urls: string[];
+  private secret?: string;
+  private timeoutMs: number;
+  private maxRetries: number;
+
+  constructor(config: WebhookConfig) {
+    this.urls = config.urls
+      .split(",")
+      .map((u) => u.trim())
+      .filter((u) => u.startsWith("http"));
+    this.secret = config.secret;
+    this.timeoutMs = config.timeoutMs ?? 5000;
+    this.maxRetries = config.maxRetries ?? 2;
+  }
+
+  /**
+   * 发送通知到所有 URL
+   */
+  async notify(event: string, data: Record<string, unknown>): Promise<WebhookResult[]> {
+    if (this.urls.length === 0) return [];
+
+    const payload: WebhookPayload = {
+      event,
+      timestamp: new Date().toISOString(),
+      data,
+    };
+
+    const results: WebhookResult[] = [];
+
+    for (const url of this.urls) {
+      const result = await this.sendToUrl(url, payload);
+      results.push(result);
+    }
+
+    return results;
+  }
+
+  /**
+   * 发送通知到单个 URL
+   */
+  private async sendToUrl(url: string, payload: WebhookPayload): Promise<WebhookResult> {
+    const body = JSON.stringify(payload);
+
+    const headers: Record<string, string> = {
+      "Content-Type": "application/json",
+      "X-Webhook-Event": payload.event,
+      "X-Webhook-Timestamp": payload.timestamp,
+    };
+
+    if (this.secret) {
+      const signature = await this.sign(body);
+      headers["X-Webhook-Signature"] = signature;
+    }
+
+    for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+      try {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), this.timeoutMs);
+
+        const res = await fetch(url, {
+          method: "POST",
+          headers,
+          body,
+          signal: controller.signal,
+        });
+
+        clearTimeout(timeout);
+
+        if (res.ok) {
+          return { ok: true, url, status: res.status };
+        }
+
+        if (res.status >= 400 && res.status < 500) {
+          return { ok: false, url, status: res.status, error: `HTTP ${res.status}` };
+        }
+
+        if (attempt < this.maxRetries) {
+          await new Promise((r) => setTimeout(r, 1000 * (attempt + 1)));
+          continue;
+        }
+
+        return { ok: false, url, status: res.status, error: `HTTP ${res.status} after ${this.maxRetries + 1} attempts` };
+      } catch (err) {
+        const errMsg = err instanceof Error ? err.message : String(err);
+        if (attempt < this.maxRetries) {
+          await new Promise((r) => setTimeout(r, 1000 * (attempt + 1)));
+          continue;
+        }
+        return { ok: false, url, error: errMsg };
+      }
+    }
+
+    return { ok: false, url, error: "unexpected" };
+  }
+
+  /**
+   * HMAC-SHA256 签名
+   */
+  private async sign(body: string): Promise<string> {
+    const key = await crypto.subtle.importKey(
+      "raw",
+      new TextEncoder().encode(this.secret!),
+      { name: "HMAC", hash: "SHA-256" },
+      false,
+      ["sign"],
+    );
+    const signature = await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(body));
+    return [...new Uint8Array(signature)].map((b) => b.toString(16).padStart(2, "0")).join("");
+  }
+
+  /**
+   * 是否有可用的 URL
+   */
+  get isConfigured(): boolean {
+    return this.urls.length > 0;
+  }
+}

package/features/webhook/tests/index.test.ts

@@ -0,0 +1,21 @@
+import { describe, it, expect } from "vitest";
+import { WebhookService } from "../index";
+
+describe("WebhookService", () => {
+  it("无 URL 时不发送", async () => {
+    const svc = new WebhookService({ urls: "" });
+    expect(svc.isConfigured).toBe(false);
+    const results = await svc.notify("test", { foo: "bar" });
+    expect(results).toEqual([]);
+  });
+
+  it("过滤无效 URL", () => {
+    const svc = new WebhookService({ urls: "not-a-url, https://valid.com/hook" });
+    expect(svc.isConfigured).toBe(true);
+  });
+
+  it("全无效 URL 时 isConfigured=false", () => {
+    const svc = new WebhookService({ urls: "not-a-url, also-not" });
+    expect(svc.isConfigured).toBe(false);
+  });
+});