@a2hmarket/a2hmarket 0.5.6 → 0.6.0

package/index.ts

@@ -122,7 +122,7 @@ export default {
       });
     });
 
-    // ── Customize feishu card when a2h tools were used ───────────
+    // ── Notify human when a2h tools were used ────────────────────
     const a2hToolUsedSessions = new Set<string>();
 
     api.on("after_tool_call", (event) => {
@@ -143,33 +143,18 @@ export default {
 
       const agentId = apiClient?.agentId ?? "";
 
-      import("./src/feishu-notify.js").then(({ sendFeishuCard }) => {
-        const feishuConfig = (() => {
-          try {
-            const creds = loadCredentials();
-            if (!creds.notify || creds.notify.channel !== "feishu") return null;
-            const cfg = api.runtime.config.loadConfig() as Record<string, unknown>;
-            const channels = (cfg.channels ?? {}) as Record<string, Record<string, unknown>>;
-            const f = channels.feishu;
-            if (!f?.appId || !f?.appSecret) return null;
-            return { appId: f.appId as string, appSecret: f.appSecret as string, target: creds.notify.target };
-          } catch { return null; }
-        })();
-
-        if (!feishuConfig) return;
-
-        sendFeishuCard({
-          appId: feishuConfig.appId,
-          appSecret: feishuConfig.appSecret,
-          target: feishuConfig.target,
-          title: "🤖 A2H Market · 查询结果",
-          titleColor: "indigo",
-          elements: [
+      import("./src/notify.js").then(({ notifyCustom }) => {
+        notifyCustom(
+          "🤖 A2H Market · 查询结果",
+          "indigo",
+          [
             { tag: "markdown", content },
-            { tag: "markdown", content: `---\n*我的 Agent ID: ${agentId}*` },
+            { tag: "markdown", content: `---\n*我的A2H Agent: ${agentId}*` },
           ],
-        }).catch((err) => {
-          api.logger.error(`a2hmarket: feishu card override failed: ${err.message}`);
+          `**🤖 A2H Market · 查询结果**\n\n${content}\n\n---\n_我的A2H Agent: ${agentId}_`,
+          { info: (m) => api.logger.info(m), error: (m) => api.logger.error(m) },
+        ).catch((err) => {
+          api.logger.error(`a2hmarket: notify failed: ${err.message}`);
         });
       });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@a2hmarket/a2hmarket",
-  "version": "0.5.6",
+  "version": "0.6.0",
   "type": "module",
   "files": [
     "index.ts",

package/scripts/install.mjs

@@ -85,6 +85,21 @@ function checkOpenclaw() {
   }
 }
 
+function detectChannels() {
+  // Detect enabled channels from openclaw.json
+  const channels = [];
+  try {
+    const cfg = JSON.parse(readFileSync(join(OPENCLAW_DIR, "openclaw.json"), "utf-8"));
+    const ch = cfg.channels ?? {};
+    for (const [name, config] of Object.entries(ch)) {
+      if (config?.enabled !== false) {
+        channels.push({ name, config });
+      }
+    }
+  } catch {}
+  return channels;
+}
+
 function detectFeishuTarget() {
   try {
     const output = execSync(
@@ -160,7 +175,222 @@ async function pollForAuth(code) {
   return { error: "授权超时（5分钟），请重新运行安装" };
 }
 
-// ── Main ─────────────────────────────────────────────────────────────────
+// ── Feishu Card Helper ───────────────────────────────────────────────────
+
+async function getFeishuToken(appId, appSecret) {
+  const resp = await fetch("https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ app_id: appId, app_secret: appSecret }),
+  });
+  const data = await resp.json();
+  if (data.code !== 0) throw new Error(`feishu token error: code=${data.code}`);
+  return data.tenant_access_token;
+}
+
+const ONBOARDING_TEXT =
+  "🎉 A2H Market · 安装成功\n\n" +
+  "我已经进入 A2H 市场了！这边特别热闹，很多人在摆摊出售各种东西，也有很多人在挑选商品和讨价还价。\n\n" +
+  "我可以帮你做三件事：\n\n" +
+  "🏪 **摆摊** — 帮你在市场上出售商品或服务，也可以直接接别人的悬赏任务赚钱\n\n" +
+  "🛍️ **逛街** — 帮你在市场上找东西买，我来搜、来比、来砍价，你拍板就行\n\n" +
+  "👀 **逛逛** — 还没想好也没关系！我帮你逛逛市场，看看有什么赚钱机会或者值得买的好东西\n\n" +
+  "你是想**摆摊卖东西**、**买点什么**，还是先让我帮你**逛逛**看看有什么机会？";
+
+async function sendOnboardingFeishu(appId, appSecret, target, agentId) {
+  const token = await getFeishuToken(appId, appSecret);
+  const receiveIdType = target.startsWith("oc_") ? "chat_id" : "open_id";
+
+  const card = {
+    schema: "2.0",
+    config: { wide_screen_mode: true },
+    header: {
+      title: { tag: "plain_text", content: "🎉 A2H Market · 安装成功" },
+      template: "green",
+    },
+    body: {
+      elements: [
+        { tag: "markdown", content: "我已经进入 A2H 市场了！这边特别热闹，很多人在摆摊出售各种东西，也有很多人在挑选商品和讨价还价。" },
+        { tag: "markdown", content: "我可以帮你做三件事：" },
+        { tag: "markdown", content:
+            "🏪 **摆摊** — 帮你在市场上出售商品或服务，也可以直接接别人的悬赏任务赚钱\n\n" +
+            "🛍️ **逛街** — 帮你在市场上找东西买，我来搜、来比、来砍价，你拍板就行\n\n" +
+            "👀 **逛逛** — 还没想好也没关系！我帮你逛逛市场，看看有什么赚钱机会或者值得买的好东西" },
+        { tag: "markdown", content: "你是想**摆摊卖东西**、**买点什么**，还是先让我帮你**逛逛**看看有什么机会？" },
+        { tag: "markdown", content: `---\n*我的A2H Agent: ${agentId}*` },
+      ],
+    },
+  };
+
+  const resp = await fetch(`https://open.feishu.cn/open-apis/im/v1/messages?receive_id_type=${receiveIdType}`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json", Authorization: `Bearer ${token}` },
+    body: JSON.stringify({ receive_id: target, msg_type: "interactive", content: JSON.stringify(card) }),
+  });
+  const data = await resp.json();
+  if (data.code !== 0) throw new Error(`feishu send error: code=${data.code} msg=${data.msg}`);
+}
+
+async function sendOnboardingDiscord(botToken, channelId, agentId) {
+  const text = ONBOARDING_TEXT + `\n\n---\n_我的A2H Agent: ${agentId}_`;
+  const resp = await fetch(`https://discord.com/api/v10/channels/${channelId}/messages`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json", Authorization: `Bot ${botToken}` },
+    body: JSON.stringify({ content: text }),
+  });
+  const data = await resp.json();
+  if (!resp.ok) throw new Error(`discord send error: ${data.code} ${data.message}`);
+}
+
+async function sendOnboarding(channel, target, agentId) {
+  const cfg = JSON.parse(readFileSync(join(OPENCLAW_DIR, "openclaw.json"), "utf-8"));
+  const channelCfg = cfg?.channels?.[channel];
+  if (!channelCfg) throw new Error(`channel "${channel}" not found in config`);
+
+  if (channel === "feishu") {
+    if (!channelCfg.appId || !channelCfg.appSecret) throw new Error("feishu appId/appSecret missing");
+    await sendOnboardingFeishu(channelCfg.appId, channelCfg.appSecret, target, agentId);
+  } else if (channel === "discord") {
+    if (!channelCfg.token) throw new Error("discord bot token missing");
+    await sendOnboardingDiscord(channelCfg.token, target, agentId);
+  } else {
+    throw new Error(`unsupported channel: ${channel}`);
+  }
+}
+
+// ── Update ───────────────────────────────────────────────────────────────
+
+async function runUpdate() {
+  log(`\n${BOLD}🏪 A2H Market — Update${RESET}\n`);
+
+  // 1. Check OpenClaw
+  logStep(1, "检查环境");
+  const version = checkOpenclaw();
+  if (!version) {
+    log(`    ${CROSS} OpenClaw 未安装`);
+    process.exit(1);
+  }
+  log(`    ${CHECK} ${version}`);
+
+  try {
+    const info = execSync("openclaw plugins info a2hmarket 2>&1", { encoding: "utf-8" });
+    if (!info.includes("a2hmarket")) throw new Error("not found");
+    log(`    ${CHECK} 插件已安装`);
+  } catch {
+    log(`    ${CROSS} 插件未安装，请先运行: npx -y ${NPM_SPEC} install`);
+    process.exit(1);
+  }
+
+  // 2. Check versions
+  logStep(2, "检查版本");
+  let currentVersion = "unknown";
+  try {
+    const pluginPkg = join(OPENCLAW_DIR, "extensions", "a2hmarket", "package.json");
+    if (existsSync(pluginPkg)) {
+      const pkg = JSON.parse(readFileSync(pluginPkg, "utf-8"));
+      currentVersion = pkg.version ?? "unknown";
+    }
+  } catch {}
+
+  let latestVersion = "unknown";
+  try {
+    latestVersion = execSync(`npm view ${NPM_SPEC} version 2>/dev/null`, { encoding: "utf-8" }).trim();
+  } catch {
+    log(`    ${CROSS} 无法获取最新版本`);
+    process.exit(1);
+  }
+
+  log(`    当前版本: ${CYAN}${currentVersion}${RESET}`);
+  log(`    最新版本: ${CYAN}${latestVersion}${RESET}`);
+
+  if (currentVersion === latestVersion) {
+    log(`\n    ${CHECK} 已是最新版本，无需更新`);
+    process.exit(0);
+  }
+
+  // 3. Update plugin
+  logStep(3, "更新插件");
+  try {
+    log(`    卸载旧版本...`);
+    execSync('echo y | openclaw plugins uninstall a2hmarket 2>&1', { encoding: "utf-8", stdio: "pipe" });
+    log(`    安装新版本...`);
+    execSync(`echo y | openclaw plugins install ${NPM_SPEC} 2>&1`, { encoding: "utf-8", stdio: "pipe" });
+    log(`    ${CHECK} 更新完成`);
+  } catch (err) {
+    log(`    ${CROSS} 更新失败: ${err.message}`);
+    process.exit(1);
+  }
+
+  // 4. Re-link openclaw module
+  log(`    配置模块依赖...`);
+  try {
+    const pluginDir = join(OPENCLAW_DIR, "extensions", "a2hmarket");
+    if (existsSync(pluginDir)) {
+      let openclawPkg = null;
+      try {
+        const realBin = execSync("realpath $(which openclaw) 2>/dev/null || readlink -f $(which openclaw) 2>/dev/null", { encoding: "utf-8" }).trim();
+        if (realBin) {
+          let dir = realBin;
+          for (let i = 0; i < 5; i++) {
+            dir = join(dir, "..");
+            const pj = join(dir, "package.json");
+            if (existsSync(pj)) {
+              try {
+                const pkg = JSON.parse(readFileSync(pj, "utf-8"));
+                if (pkg.name === "openclaw") { openclawPkg = dir; break; }
+              } catch {}
+            }
+          }
+        }
+      } catch {}
+
+      if (!openclawPkg) {
+        for (const p of [
+          "/opt/homebrew/lib/node_modules/openclaw",
+          "/usr/local/lib/node_modules/openclaw",
+        ]) {
+          if (existsSync(join(p, "package.json"))) { openclawPkg = p; break; }
+        }
+      }
+
+      if (openclawPkg) {
+        const symlinkDir = join(pluginDir, "node_modules");
+        const symlinkTarget = join(symlinkDir, "openclaw");
+        mkdirSync(symlinkDir, { recursive: true });
+        try { execSync(`rm -f "${symlinkTarget}"`, { stdio: "pipe" }); } catch {}
+        execSync(`ln -sf "${openclawPkg}" "${symlinkTarget}"`, { stdio: "pipe" });
+        log(`    ${CHECK} openclaw/plugin-sdk 已链接`);
+      } else {
+        log(`    ${WARN} 未找到 openclaw 包路径`);
+      }
+    }
+  } catch (err) {
+    log(`    ${WARN} 模块链接失败: ${err.message}`);
+  }
+
+  // 5. Restart gateway
+  logStep(4, "重启服务");
+  try {
+    execSync("openclaw gateway restart 2>&1", { encoding: "utf-8", stdio: "pipe" });
+    log(`    ${CHECK} Gateway 已重启`);
+  } catch {
+    log(`    ${WARN} 请手动执行: openclaw gateway restart`);
+  }
+
+  // 6. Verify
+  logStep(5, "验证");
+  await new Promise((r) => setTimeout(r, 5000));
+  try {
+    const info = execSync("openclaw plugins info a2hmarket 2>&1", { encoding: "utf-8" });
+    if (info.includes("Status: loaded")) {
+      log(`    ${CHECK} 插件运行正常`);
+    }
+  } catch {
+    log(`    ${WARN} 请检查: openclaw plugins info a2hmarket`);
+  }
+
+  log(`\n${GREEN}${BOLD}🎉 更新完成！${RESET} ${currentVersion} → ${CYAN}${latestVersion}${RESET}\n`);
+}
 
 // ── Uninstall ────────────────────────────────────────────────────────────
 
@@ -215,10 +445,15 @@ async function main() {
     return await runUninstall();
   }
 
+  if (cmd === "update") {
+    return await runUpdate();
+  }
+
   if (cmd !== "install") {
     log(`\n${BOLD}A2H Market — OpenClaw Plugin${RESET}\n`);
     log(`  安装:    npx -y ${NPM_SPEC} install`);
     log(`  快速:    npx -y ${NPM_SPEC} install --agent ag_xxx:key`);
+    log(`  更新:    npx -y ${NPM_SPEC} update`);
     log(`  卸载:    npx -y ${NPM_SPEC} uninstall\n`);
     process.exit(0);
   }
@@ -449,19 +684,53 @@ async function main() {
     mqtt_url: mqttUrl,
   };
 
-  // Auto-detect feishu notification target
-  const feishuTarget = detectFeishuTarget();
-  if (feishuTarget) {
-    log(`    检测到飞书用户: ${CYAN}${feishuTarget}${RESET}`);
+  // Detect available channels and let user choose
+  const channels = detectChannels();
+  if (channels.length > 0) {
+    log(`    检测到 ${channels.length} 个可用渠道:`);
+    channels.forEach((ch, i) => {
+      log(`      ${CYAN}${i + 1}${RESET}. ${ch.name}`);
+    });
+
     const prompt2 = createPrompt();
-    const useFeishu = await prompt2.ask("启用飞书通知? (Y/n)", "Y");
-    prompt2.close();
-    if (useFeishu.toLowerCase() !== "n") {
-      credsData.notify = { channel: "feishu", target: feishuTarget };
-      log(`    ${CHECK} 飞书通知已配置`);
+    const choice = await prompt2.ask(
+      `选择通知渠道 (1-${channels.length}，回车跳过)`,
+      "",
+    );
+
+    if (choice) {
+      const idx = parseInt(choice, 10) - 1;
+      if (idx >= 0 && idx < channels.length) {
+        const chosen = channels[idx];
+        let target = "";
+
+        if (chosen.name === "feishu") {
+          // Auto-detect feishu target or ask
+          target = detectFeishuTarget() || "";
+          if (target) {
+            log(`    检测到飞书用户: ${CYAN}${target}${RESET}`);
+          } else {
+            target = await prompt2.ask("输入飞书 open_id (ou_xxx) 或 chat_id (oc_xxx)", "");
+          }
+        } else if (chosen.name === "discord") {
+          target = await prompt2.ask("输入 Discord 频道 ID", "");
+        } else {
+          target = await prompt2.ask(`输入 ${chosen.name} 目标 ID`, "");
+        }
+
+        if (target) {
+          credsData.notify = { channel: chosen.name, target };
+          log(`    ${CHECK} 通知渠道已配置: ${chosen.name} → ${target}`);
+        } else {
+          log(`    ${WARN} 未输入目标 ID，跳过通知配置`);
+        }
+      }
+    } else {
+      log(`    ${DIM}跳过通知配置${RESET}`);
     }
+    prompt2.close();
   } else {
-    log(`    ${DIM}未检测到飞书，跳过通知配置${RESET}`);
+    log(`    ${DIM}未检测到可用渠道，跳过通知配置${RESET}`);
   }
 
   writeFileSync(CREDS_FILE, JSON.stringify(credsData, null, 2) + "\n");
@@ -492,6 +761,17 @@ async function main() {
     log(`    ${WARN} 请检查: openclaw plugins info a2hmarket`);
   }
 
+  // ── Step 7: Send onboarding message ──────────────────────────
+  if (credsData.notify?.channel && credsData.notify?.target) {
+    logStep(7, "发送欢迎消息");
+    try {
+      await sendOnboarding(credsData.notify.channel, credsData.notify.target, agentId);
+      log(`    ${CHECK} 欢迎消息已发送到 ${credsData.notify.channel}`);
+    } catch (err) {
+      log(`    ${WARN} 欢迎消息发送失败: ${err.message}`);
+    }
+  }
+
   // ── Done ───────────────────────────────────────────────────────
   log(`\n${GREEN}${BOLD}🎉 安装完成！${RESET}\n`);
   log(`  Agent ID:  ${CYAN}${agentId}${RESET}`);

package/src/agent-service.ts

@@ -19,8 +19,7 @@ import { MqttTokenClient } from "./mqtt-token.js";
 import { createSendTransport } from "./mqtt-transport.js";
 import { buildEnvelope, signEnvelope } from "./protocol.js";
 import { getA2HRuntime } from "./runtime.js";
-import { sendFeishuCard, buildA2HNotifyCard, buildPaymentCard } from "./feishu-notify.js";
-import { recordCardPeer } from "./reply-bridge.js";
+import { notifyHuman, notifyPayment, resolveNotifyConfig, type NotifyLog } from "./notify.js";
 
 // ── MQTT Send Helper ─────────────────────────────────────────────────────
 
@@ -46,60 +45,9 @@ async function mqttSendText(
   }
 }
 
-// ── Feishu Notification ──────────────────────────────────────────────────
+// ── Re-export notifyHuman for external callers ──────────────────────────
 
-function resolveFeishuConfig(): { appId: string; appSecret: string; target: string } | null {
-  try {
-    const creds = loadCredentials();
-    if (!creds.notify || creds.notify.channel !== "feishu") return null;
-
-    const runtime = getA2HRuntime();
-    const cfg = runtime.config.loadConfig() as Record<string, unknown>;
-    const channels = (cfg.channels ?? {}) as Record<string, Record<string, unknown>>;
-    const feishuCfg = channels.feishu;
-    if (!feishuCfg?.appId || !feishuCfg?.appSecret) return null;
-
-    return {
-      appId: feishuCfg.appId as string,
-      appSecret: feishuCfg.appSecret as string,
-      target: creds.notify.target,
-    };
-  } catch {
-    return null;
-  }
-}
-
-export function notifyHumanCard(
-  type: "inbound" | "reply",
-  peerId: string,
-  content: string,
-  agentId: string,
-  log?: { info: (m: string) => void; error: (m: string) => void },
-): void {
-  const feishu = resolveFeishuConfig();
-  if (!feishu) {
-    log?.info("feishu not configured, skip notification");
-    return;
-  }
-
-  const card = buildA2HNotifyCard({ type, peerId, content, agentId });
-
-  sendFeishuCard({
-    appId: feishu.appId,
-    appSecret: feishu.appSecret,
-    target: feishu.target,
-    title: card.title,
-    titleColor: card.titleColor,
-    elements: card.elements,
-  })
-    .then((msgId) => {
-      log?.info(`feishu card sent: ${msgId}`);
-      if (msgId) {
-        recordCardPeer(msgId, peerId, feishu.target);
-      }
-    })
-    .catch((err) => log?.error(`feishu card failed: ${err.message}`));
-}
+export { notifyHuman as notifyHumanCard } from "./notify.js";
 
 // ── Agent Service ────────────────────────────────────────────────────────
 
@@ -196,28 +144,17 @@ export async function startAgentService(ctx: AgentServiceContext): Promise<void>
           }
 
           // ④ Custom notification: notify human about the reply
-          //    If reply contains a Stripe checkout URL, send a dedicated payment card
+          //    If reply contains a Stripe checkout URL, send a dedicated payment notification
           const paymentUrlMatch = formatted.match(/(https:\/\/checkout\.stripe\.com\S+)/);
           if (paymentUrlMatch) {
-            const feishu = resolveFeishuConfig();
-            if (feishu) {
-              const paymentCard = buildPaymentCard({
-                peerId: event.senderId,
-                orderId: event.messageId ?? "unknown",
-                paymentUrl: paymentUrlMatch[1],
-                agentId: creds.agentId,
-              });
-              sendFeishuCard({
-                appId: feishu.appId,
-                appSecret: feishu.appSecret,
-                target: feishu.target,
-                ...paymentCard,
-              })
-                .then((msgId) => notifyLog.info(`feishu payment card sent: ${msgId}`))
-                .catch((err) => notifyLog.error(`feishu payment card failed: ${err.message}`));
-            }
+            notifyPayment({
+              peerId: event.senderId,
+              orderId: event.messageId ?? "unknown",
+              paymentUrl: paymentUrlMatch[1],
+              agentId: creds.agentId,
+            }, notifyLog);
           } else {
-            notifyHumanCard("reply", event.senderId, formatted.slice(0, 500), creds.agentId, notifyLog);
+            notifyHuman("reply", event.senderId, formatted.slice(0, 500), creds.agentId, notifyLog);
           }
         },
 

package/src/notify.ts

@@ -0,0 +1,256 @@
+/**
+ * Unified notification service — dispatches to Feishu (card) or other channels (text).
+ *
+ * Channel resolution:
+ *   1. Read credentials.notify.channel + target
+ *   2. Feishu → rich interactive card via Feishu Open API
+ *   3. Discord → plain text via Discord bot API
+ *   4. Others → log warning (unsupported)
+ */
+
+import { loadCredentials } from "./credentials.js";
+import { getA2HRuntime } from "./runtime.js";
+import { sendFeishuCard, buildA2HNotifyCard, buildPaymentCard, type FeishuCardElement } from "./feishu-notify.js";
+import { recordCardPeer } from "./reply-bridge.js";
+
+// ── Types ────────────────────────────────────────────────────────────
+
+export type NotifyType = "inbound" | "reply" | "approval" | "payment" | "payment_complete";
+
+export interface NotifyLog {
+  info: (m: string) => void;
+  error: (m: string) => void;
+}
+
+interface ChannelConfig {
+  channel: string;
+  target: string;
+  // Feishu-specific
+  appId?: string;
+  appSecret?: string;
+  // Discord-specific
+  botToken?: string;
+}
+
+// ── Channel Config Resolution ────────────────────────────────────────
+
+export function resolveNotifyConfig(): ChannelConfig | null {
+  try {
+    const creds = loadCredentials();
+    if (!creds.notify?.channel || !creds.notify?.target) return null;
+
+    const runtime = getA2HRuntime();
+    const cfg = runtime.config.loadConfig() as Record<string, unknown>;
+    const channels = (cfg.channels ?? {}) as Record<string, Record<string, unknown>>;
+
+    const channelName = creds.notify.channel;
+    const channelCfg = channels[channelName];
+
+    if (channelName === "feishu") {
+      if (!channelCfg?.appId || !channelCfg?.appSecret) return null;
+      return {
+        channel: "feishu",
+        target: creds.notify.target,
+        appId: channelCfg.appId as string,
+        appSecret: channelCfg.appSecret as string,
+      };
+    }
+
+    if (channelName === "discord") {
+      if (!channelCfg?.token) return null;
+      return {
+        channel: "discord",
+        target: creds.notify.target,
+        botToken: channelCfg.token as string,
+      };
+    }
+
+    // Unknown channel — return basic config, will be handled as text
+    return { channel: channelName, target: creds.notify.target };
+  } catch {
+    return null;
+  }
+}
+
+// ── Discord Text Sender ──────────────────────────────────────────────
+
+async function sendDiscordText(botToken: string, channelId: string, text: string): Promise<string> {
+  const resp = await fetch(`https://discord.com/api/v10/channels/${channelId}/messages`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bot ${botToken}`,
+    },
+    body: JSON.stringify({ content: text }),
+  });
+
+  const data = (await resp.json()) as { id?: string; message?: string; code?: number };
+  if (!resp.ok) {
+    throw new Error(`discord send error: ${data.code} ${data.message}`);
+  }
+  return data.id ?? "";
+}
+
+// ── Text Formatters ──────────────────────────────────────────────────
+
+function formatNotifyText(type: NotifyType, peerId: string, content: string, agentId?: string): string {
+  const headers: Record<NotifyType, string> = {
+    inbound: "📩 A2H Market · 收到消息",
+    reply: "🤖 A2H Market · 已自动回复",
+    approval: "🔔 A2H Market · 需要确认",
+    payment: "💳 A2H Market · 待支付",
+    payment_complete: "✅ A2H Market · 支付完成",
+  };
+
+  const peerLabel = type === "reply" ? "回复给" : "来自";
+  const lines = [
+    `**${headers[type]}**`,
+    `${peerLabel}: \`${peerId}\``,
+    "",
+    content,
+  ];
+  if (agentId) {
+    lines.push("", `---`, `_我的A2H Agent: ${agentId}_`);
+  }
+  return lines.join("\n");
+}
+
+function formatPaymentText(params: {
+  peerId: string;
+  orderId: string;
+  amount?: number;
+  currency?: string;
+  paymentUrl: string;
+  agentId?: string;
+}): string {
+  const lines = [
+    `**💳 A2H Market · 待支付**`,
+    `订单: \`${params.orderId}\``,
+    `金额: ${params.amount ? (params.amount / 100).toFixed(2) : "?"} ${params.currency?.toUpperCase() ?? "USD"}`,
+    `来自: \`${params.peerId}\``,
+    "",
+    `👉 点击支付: ${params.paymentUrl}`,
+  ];
+  if (params.agentId) {
+    lines.push("", `---`, `_我的A2H Agent: ${params.agentId}_`);
+  }
+  return lines.join("\n");
+}
+
+// ── Public API ───────────────────────────────────────────────────────
+
+/**
+ * Send a notification to the human user via their configured channel.
+ */
+export function notifyHuman(
+  type: NotifyType,
+  peerId: string,
+  content: string,
+  agentId: string,
+  log?: NotifyLog,
+): void {
+  const config = resolveNotifyConfig();
+  if (!config) {
+    log?.info("notify: no channel configured, skip");
+    return;
+  }
+
+  if (config.channel === "feishu" && config.appId && config.appSecret) {
+    const card = buildA2HNotifyCard({ type, peerId, content, agentId });
+    sendFeishuCard({
+      appId: config.appId,
+      appSecret: config.appSecret,
+      target: config.target,
+      title: card.title,
+      titleColor: card.titleColor,
+      elements: card.elements,
+    })
+      .then((msgId) => {
+        log?.info(`feishu card sent: ${msgId}`);
+        if (msgId) recordCardPeer(msgId, peerId, config.target);
+      })
+      .catch((err) => log?.error(`feishu card failed: ${err.message}`));
+    return;
+  }
+
+  if (config.channel === "discord" && config.botToken) {
+    const text = formatNotifyText(type, peerId, content, agentId);
+    sendDiscordText(config.botToken, config.target, text)
+      .then((msgId) => log?.info(`discord message sent: ${msgId}`))
+      .catch((err) => log?.error(`discord send failed: ${err.message}`));
+    return;
+  }
+
+  log?.info(`notify: unsupported channel "${config.channel}", skip`);
+}
+
+/**
+ * Send a payment notification card/text to the human.
+ */
+export function notifyPayment(
+  params: {
+    peerId: string;
+    orderId: string;
+    amount?: number;
+    currency?: string;
+    paymentUrl: string;
+    agentId?: string;
+  },
+  log?: NotifyLog,
+): void {
+  const config = resolveNotifyConfig();
+  if (!config) return;
+
+  if (config.channel === "feishu" && config.appId && config.appSecret) {
+    const card = buildPaymentCard(params);
+    sendFeishuCard({
+      appId: config.appId,
+      appSecret: config.appSecret,
+      target: config.target,
+      ...card,
+    })
+      .then((msgId) => log?.info(`feishu payment card sent: ${msgId}`))
+      .catch((err) => log?.error(`feishu payment card failed: ${err.message}`));
+    return;
+  }
+
+  if (config.channel === "discord" && config.botToken) {
+    const text = formatPaymentText(params);
+    sendDiscordText(config.botToken, config.target, text)
+      .then((msgId) => log?.info(`discord payment message sent: ${msgId}`))
+      .catch((err) => log?.error(`discord payment send failed: ${err.message}`));
+    return;
+  }
+}
+
+/**
+ * Send a custom card (Feishu) or plain text (others) notification.
+ * Used by index.ts message_sending hook and onboarding.
+ */
+export async function notifyCustom(
+  title: string,
+  titleColor: string,
+  elements: FeishuCardElement[],
+  plainText: string,
+  log?: NotifyLog,
+): Promise<void> {
+  const config = resolveNotifyConfig();
+  if (!config) return;
+
+  if (config.channel === "feishu" && config.appId && config.appSecret) {
+    await sendFeishuCard({
+      appId: config.appId,
+      appSecret: config.appSecret,
+      target: config.target,
+      title,
+      titleColor,
+      elements,
+    });
+    return;
+  }
+
+  if (config.channel === "discord" && config.botToken) {
+    await sendDiscordText(config.botToken, config.target, plainText);
+    return;
+  }
+}