第9课：自动化 —— Listeners 监听器详解

Action:    用户触发 → 执行
Listener:  事件触发 → 自动执行（你可能都不知道它干了）

// agent/custom_scripts/listeners/finance-email-tracker.ts

export const config = {
    listenerId: "finance-email-tracker",
    name: "财务邮件自动追踪",
    description: "自动识别发票和收据邮件，提取金额记录到财务看板",
    event: "email_received",     // 监听 "收到新邮件" 事件
    enabled: true,               // 默认启用
};

export async function handler(email, context) {
    // 第一步：用简单规则快速过滤（省钱！不是每封邮件都调AI）
    const financeKeywords = ['invoice', 'receipt', 'payment', 'charge', 'billing'];
    const text = `${email.subject} ${email.body_text}`.toLowerCase();
    const mightBeFinance = financeKeywords.some(kw => text.includes(kw));

    if (!mightBeFinance) {
        return; // 不像财务邮件，跳过，不调 AI（省钱）
    }

    // 第二步：调 AI 做精确判断（递归 AI 核心！）
    const analysis = await context.callAgent({
        prompt: `分析这封邮件是否包含财务信息：
            发件人: ${email.from}
            主题: ${email.subject}
            内容: ${email.body_text.slice(0, 1000)}

            如果包含财务信息，提取金额、类型和供应商。`,
        schema: {
            type: "object",
            properties: {
                is_financial: { type: "boolean" },
                transaction_type: {
                    type: "string",
                    enum: ["expense", "income", "refund", "subscription"]
                },
                amount: { type: "number" },
                currency: { type: "string" },
                vendor: { type: "string" },
                category: { type: "string" }
            }
        }
    });

    if (!analysis.is_financial) {
        return; // AI 说不是财务邮件，放行
    }

    // 第三步：记录到财务看板
    const dashboard = await context.uiState.get('financial-dashboard');
    dashboard.transactions.push({
        date: email.date_sent,
        type: analysis.transaction_type,
        amount: analysis.amount,
        vendor: analysis.vendor,
        category: analysis.category,
        emailId: email.messageId,
    });
    await context.uiState.set('financial-dashboard', dashboard);

    // 第四步：给邮件贴标签
    await context.label(email.messageId, 'Finance');

    // 第五步：通知用户
    context.notify(
        `💰 检测到${analysis.transaction_type === 'expense' ? '支出' : '收入'}: ` +
        `${analysis.currency}${analysis.amount} - ${analysis.vendor}`
    );
}

// agent/custom_scripts/listeners/todo-extractor.ts

export const config = {
    listenerId: "todo-extractor",
    name: "待办事项提取器",
    description: "从邮件中自动提取行动项，添加到任务看板",
    event: "email_received",
    enabled: true,
};

export async function handler(email, context) {
    // 只处理来自同事/上司的邮件（跳过营销邮件等）
    const workDomains = ['company.com', 'partner.org'];
    const isWorkEmail = workDomains.some(d => email.from.includes(d));
    if (!isWorkEmail) return;

    // 调 AI 提取待办事项
    const result = await context.callAgent({
        prompt: `从这封工作邮件中提取行动项（如果有的话）：
            发件人: ${email.from}
            主题: ${email.subject}
            内容: ${email.body_text.slice(0, 2000)}

            只提取明确需要你做的事情，不要猜测。`,
        schema: {
            type: "object",
            properties: {
                has_todos: { type: "boolean" },
                todos: {
                    type: "array",
                    items: {
                        type: "object",
                        properties: {
                            title: { type: "string" },
                            priority: { type: "string", enum: ["high", "medium", "low"] },
                            deadline: { type: "string" }
                        }
                    }
                }
            }
        }
    });

    if (!result.has_todos || result.todos.length === 0) return;

    // 添加到任务看板
    const taskBoard = await context.uiState.get('task-board');
    for (const todo of result.todos) {
        taskBoard.tasks.push({
            title: todo.title,
            priority: todo.priority,
            deadline: todo.deadline,
            status: 'todo',
            source: `邮件: ${email.subject}`,
            emailId: email.messageId,
            createdAt: new Date().toISOString(),
        });
    }
    await context.uiState.set('task-board', taskBoard);

    context.notify(`📋 从 "${email.subject}" 中提取了 ${result.todos.length} 个待办事项`);
}

1. 启动时扫描 custom_scripts/listeners/ 目录，加载所有 Listener
2. 监听文件变化 → 热重载（改了代码不用重启）
3. 当事件发生时，找到所有监听该事件的 Listener，逐一执行
4. 记录日志到 .logs/listeners/
5. 处理错误（某个 Listener 出错不影响其他的）

// listeners-manager.ts（简化版）
class ListenersManager {
    private listeners = [];  // 所有已加载的 Listener

    async checkEvent(eventType: string, data: any) {
        // 找到所有监听这个事件的 Listener
        const matching = this.listeners.filter(
            l => l.config.event === eventType && l.config.enabled
        );

        // 逐一执行
        for (const listener of matching) {
            try {
                await listener.handler(data, this.createContext());
                this.log(listener.config.listenerId, 'success', data);
            } catch (error) {
                this.log(listener.config.listenerId, 'error', error);
                // 不抛出异常 → 一个 Listener 出错不影响其他的
            }
        }
    }
}

// 监听文件变化
watch('agent/custom_scripts/listeners/', (event, filename) => {
    if (filename.endsWith('.ts')) {
        console.log(`🔄 Listener 文件变化: ${filename}，重新加载...`);
        this.reloadListeners();
    }
});

┌─────────────────────────────────────┐
│  活跃的监听器                        │
│                                     │
│  ✅ finance-email-tracker           │
│     财务邮件自动追踪                  │
│     事件: email_received            │
│                                     │
│  ✅ todo-extractor                  │
│     待办事项提取器                    │
│     事件: email_received            │
│                                     │
│  ⏸️ urgent-watcher (已暂停)         │
│     紧急邮件监控                     │
│     事件: email_received            │
└─────────────────────────────────────┘