@ulthon/ul-opencode-event 0.1.27 → 0.1.28

package/README.md

@@ -1,431 +1,147 @@
-# @ulthon/ul-opencode-event
-
-**Never miss an OpenCode notification, even when you're away from your desk.**
-
-OpenCode multi-channel notification plugin that keeps you informed wherever you are. Perfect for remote development - get notified when tasks complete or errors occur via email or DingTalk, even if you're not at your terminal.
-
-## Why ul-opencode-event?
-
-- 🌍 **Remote Development Friendly** - Desktop notifications don't work when you're away. Our plugin sends notifications to your email (and more channels coming soon), so you'll always know when your AI coding agent finishes a task.
-- 📬 **Multi-Channel Support** - Supports SMTP email and DingTalk robot, with more notification channels planned (webhook, Telegram, Slack, etc.)
-- ⚡ **Real-time Alerts** - Get notified immediately when sessions complete (`idle`) or encounter errors (`error`)
-- 🔧 **Easy Configuration** - Simple JSON config with channel-level customization
-
-## Roadmap
-
-| Channel | Status | Description |
-|---------|--------|-------------|
-| ✅ SMTP (Email) | Available | Email notifications via any SMTP server |
-| 🔜 Webhook | Planned | HTTP webhook for custom integrations |
-| 🔜 Telegram | Planned | Telegram bot notifications |
-| 🔜 Slack | Planned | Slack incoming webhooks |
-| ✅ DingTalk | Available | 钉钉机器人 |
-| 🔜 WeChat Work | Planned | 企业微信 |
-
-**Have a channel request?** Open an issue on our [Gitee repo](https://gitee.com/augushong/ul-opencode-event)!
-
-## Quick Start
-
-```bash
-# 1. 安装
-npm install @ulthon/ul-opencode-event
-
-# 2. 创建配置文件（项目根目录）
-cp node_modules/@ulthon/ul-opencode-event/examples/ul-opencode-event.json ./
-
-# 3. 编辑配置，填入你的 SMTP 信息
-
-# 4. 测试连接
-npx @ulthon/ul-opencode-event test
-
-# 5. 添加到 OpenCode 配置
-# 在 .opencode/settings.json 中添加:
-# { "plugin": ["@ulthon/ul-opencode-event"] }
-```
-## Installation
-```bash
-npm install @ulthon/ul-opencode-event
-```
-Then add to your OpenCode configuration (`.opencode/settings.json`):
-```json
-{
-  "plugin": ["@ulthon/ul-opencode-event"]
-}
-```
-## Configuration
-### Configuration File Locations
-The plugin looks for configuration in these locations (in order of priority):
-1. **Project-level**: `.opencode/ul-opencode-event.json` or `./ul-opencode-event.json`
-2. **Global**: `~/.config/opencode/ul-opencode-event.json`
-Project-level configuration overrides global configuration (channels are merged by name).
-### Minimal Configuration
-Create `ul-opencode-event.json` in your project root:
-```json
-{
-  "channels": [
-    {
-      "type": "smtp",
-      "enabled": true,
-      "name": "My Email",
-      "config": {
-        "host": "smtp.example.com",
-        "port": 465,
-        "secure": true,
-        "auth": {
-          "user": "your-email@example.com",
-          "pass": "your-app-password"
-        }
-      },
-      "recipients": ["receiver@example.com"],
-      "events": {
-        "idle": true,
-        "error": true
-      }
-    }
-  ]
-}
-```
-### Common SMTP Servers
-| Provider | Host | Port | Secure | Auth |
-|----------|------|------|--------|------|
-| QQ Mail | smtp.qq.com | 465 | true | Authorization code |
-| 163 Mail | smtp.163.com | 465 | true | Authorization code |
-| Gmail | smtp.gmail.com | 587 | false | App Password |
-| Outlook | smtp.office365.com | 587 | false | Password |
-> **Note**: For QQ/163 Mail, use the authorization code (授权码), not your login password.
-> For Gmail, use an App Password with 2FA enabled.
-### Full Configuration Example
-```json
-{
-  "projectName": "my-project",
-  "channels": [
-    {
-      "type": "smtp",
-      "enabled": true,
-      "name": "QQ邮箱",
-      "config": {
-        "host": "smtp.qq.com",
-        "port": 465,
-        "secure": true,
-        "auth": {
-          "user": "your@qq.com",
-          "pass": "your-authorization-code"
-        }
-      },
-      "recipients": ["admin@example.com", "dev-team@example.com"],
-      "events": {
-        "created": false,
-        "idle": true,
-        "error": true
-      },
-      "templates": {
-        "idle": {
-          "subject": "[{{projectName}}] 任务完成",
-          "body": "任务已完成\n\n时间: {{timestamp}}\n耗时: {{duration}}\n消息: {{message}}"
-        },
-        "error": {
-          "subject": "[{{projectName}}] 任务错误",
-          "body": "任务发生错误\n\n时间: {{timestamp}}\n错误: {{error}}"
-        }
-      }
-    }
-  ]
-}
-```
-### Channel Configuration
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `type` | string | Yes | Channel type: `smtp` |
-| `enabled` | boolean | No | Whether this channel is active (default: true) |
-| `name` | string | No | Channel name for identification |
-| `config` | object | Yes | SMTP configuration |
-| `recipients` | string[] | Yes | Email recipients |
-| `events` | object | No | Which events to notify |
-| `templates` | object | No | Custom templates for each event |
-### SMTP Configuration
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `host` | string | Yes | SMTP server hostname or IPv4/IPv6 address |
-| `port` | number | Yes | SMTP port (465 for SSL, 587 for STARTTLS) |
-| `secure` | boolean | No | Use SSL (default: true for port 465) |
-| `localAddress` | string | No | Local interface to bind for IPv4/IPv6 control |
-| `auth.user` | string | Yes | SMTP username (usually your email) |
-| `auth.pass` | string | Yes | SMTP password or authorization code |
-
-### DingTalk 机器人配置
-
-通过钉钉群自定义机器人接收 OpenCode 通知消息，支持 Markdown 格式和 @人功能。
-
-#### 获取 Webhook 和 Secret
-
-1. 打开钉钉群，点击右上角 **群设置** > **智能群助手** > **添加机器人**
-2. 选择 **自定义** 机器人，输入机器人名称和头像
-3. **安全设置** 选择 **加签** 模式（推荐），复制生成的 **Secret**
-4. 完成后复制 **Webhook 地址**（格式: `https://oapi.dingtalk.com/robot/send?access_token=xxx`）
-
-> **建议**: 始终开启加签模式，避免 Webhook 被恶意调用。
-
-#### 最小配置
-
-```json
-{
-  "channels": [
-    {
-      "type": "dingtalk",
-      "enabled": true,
-      "name": "钉钉通知",
-      "config": {
-        "webhook": "https://oapi.dingtalk.com/robot/send?access_token=YOUR_ACCESS_TOKEN"
-      },
-      "events": {
-        "idle": true,
-        "error": true
-      }
-    }
-  ]
-}
-```
-
-#### 完整配置示例
-
-```json
-{
-  "channels": [
-    {
-      "type": "dingtalk",
-      "enabled": true,
-      "name": "钉钉通知",
-      "config": {
-        "webhook": "https://oapi.dingtalk.com/robot/send?access_token=YOUR_ACCESS_TOKEN",
-        "secret": "SEC-your-secret-key-here",
-        "at": {
-          "atMobiles": ["13800138000"],
-          "atAll": false
-        }
-      },
-      "events": {
-        "created": false,
-        "idle": true,
-        "error": true
-      },
-      "templates": {
-        "idle": {
-          "body": "### [{{projectName}}] 任务完成\n\n**耗时**: {{duration}}\n**消息**: {{message}}\n\n> {{timestamp}}"
-        },
-        "error": {
-          "body": "### [{{projectName}}] 任务错误\n\n**错误**: {{error}}\n\n> {{timestamp}}"
-        }
-      }
-    }
-  ]
-}
-```
-
-#### DingTalk 配置字段说明
-
-| Field | Type | Required | Default | Description |
-|-------|------|----------|---------|-------------|
-| `webhook` | string | Yes | - | 钉钉机器人 Webhook 地址 |
-| `secret` | string | No | - | 加签密钥（安全设置选"加签"时提供） |
-| `at.atMobiles` | string[] | No | - | 要 @的成员手机号列表 |
-| `at.atAll` | boolean | No | false | 是否 @所有人 |
-
-> **注意**: 钉钉通道不需要 `recipients` 字段，消息发送到机器人所在的钉钉群。
-
-#### @人功能
-
-钉钉支持在消息中 @指定群成员：
-
-- **@指定成员**: 在 `at.atMobiles` 中填写手机号数组，如 `["13800138000", "13900139000"]`
-- **@所有人**: 设置 `at.atAll` 为 `true`
-- **不@任何人**: 不配置 `at` 字段，或设为空对象 `{}`
-
-默认行为是不 @任何人。如果同时设置了 `atMobiles` 和 `atAll=true`，将以 `atAll` 为准。
-
-#### 钉钉常见问题
-
-**Q: 签名失败 (signature mismatch) 怎么办？**
-
-A: 检查以下几点：
-1. 确认 `secret` 值与钉钉后台显示的完全一致（注意前后空格）
-2. 确认服务器时间与标准时间偏差不超过 1 小时
-3. 如果使用代理/TUN 环境，确认网络能正常访问 `oapi.dingtalk.com`
-
-**Q: 消息发送频率有限制吗？**
-
-A: 有。每个机器人每条消息不超过 20 条/分钟。如果短时间内产生大量事件通知（如批量文件编辑），部分消息可能被限流丢弃。
-
-**Q: 钉钉 Markdown 支持哪些格式？**
-
-A: 钉钉 Markdown 支持有限的语法子集：
-- 标题: `#` `##` `###`
-- 加粗: `**text**`
-- 引用: `>`
-- 有序/无序列表
-- 链接: `[text](url)`
-- 图片: `![](url)`
-
-不支持表格、代码块高亮、HTML 标签等。编写自定义模板时请使用支持的语法。
-
-**Q: 消息丢失或收不到怎么办？**
-
-A: 排查步骤：
-1. 运行 `npx @ulthon/ul-opencode-event test --channel "钉钉通知"` 测试连接
-2. 设置环境变量 `UL_OPENCODE_EVENT_DEBUG=1` 查看详细日志
-3. 检查钉钉群中机器人是否已被移除或禁用
-4. 确认 Webhook 地址中的 `access_token` 未过期（通常不会过期）
-
-### IPv4/IPv6 Configuration
-
-By default, the plugin automatically supports both IPv4 and IPv6. Nodemailer will:
-- Resolve DNS to both IPv4 (A) and IPv6 (AAAA) records
-- Try both address families in parallel
-- Use whichever connects successfully
-
-#### Force IPv4
-If you want to force IPv4 connection (e.g., IPv6 is unavailable or unstable):
-```json
-{
-  "config": {
-    "host": "smtp.qq.com",
-    "port": 465,
-    "secure": true,
-    "localAddress": "0.0.0.0",
-    "auth": {
-      "user": "your@qq.com",
-      "pass": "authorization-code"
-    }
-  }
-}
-```
-
-#### Force IPv6
-If you want to force IPv6 connection:
-```json
-{
-  "config": {
-    "host": "smtp.example.com",
-    "port": 465,
-    "secure": true,
-    "localAddress": "::",
-    "auth": {
-      "user": "your@example.com",
-      "pass": "your-password"
-    }
-  }
-}
-```
-
-#### Use IPv6 Address as Host
-You can also use an IPv6 address directly as the host:
-```json
-{
-  "config": {
-    "host": "2001:db8::1",
-    "port": 465,
-    "secure": true,
-    "auth": {
-      "user": "your@example.com",
-      "pass": "your-password"
-    }
-  }
-}
-```
-
-### Events Configuration
-| Event | Default | Description |
-|-------|---------|-------------|
-| `created` | false | When a new session starts |
-| `idle` | true | When a session completes (AI finishes responding) |
-| `error` | true | When a session encounters an error |
-### Template Variables
-| Variable | Description | Available Events |
-|----------|-------------|------------------|
-| `{{eventType}}` | Event type (created, idle, error) | All |
-| `{{timestamp}}` | ISO 8601 timestamp | All |
-| `{{projectName}}` | Project short name (directory basename or config value) | All |
-| `{{projectPath}}` | Project full path (e.g. `/home/user/my-project`) | All |
-| `{{sessionId}}` | Session ID | All |
-| `{{message}}` | Completion message | idle |
-| `{{duration}}` | Task duration | idle |
-| `{{error}}` | Error message | error |
-## CLI Tool
-This package includes a CLI tool to test your notification channel configuration.
-### Test Command
-```bash
-# Test all channels (validates config, tests connection, sends test email)
-npx @ulthon/ul-opencode-event test
-
-# Test a specific channel by name
-npx @ulthon/ul-opencode-event test --channel "My Email"
-
-# Only verify connection without sending email
-npx @ulthon/ul-opencode-event test --no-send
-```
-### Test Output Example
-```
-[ul-opencode-event-cli] Starting channel test...
-[ul-opencode-event-cli] Loaded project config: ./ul-opencode-event.json
-[ul-opencode-event-cli] Found 1 channel(s) to test
-
-[ul-opencode-event-cli] Testing channel: "My Email"
-  Type: smtp
-  Recipients: user@example.com
-
-  [1/3] Validating configuration...
-  [OK] Configuration is valid
-
-  [2/3] Testing SMTP connection to smtp.example.com:465...
-  [OK] Connection successful
-
-  [3/3] Sending test email...
-  [OK] Test email sent successfully
-  Message ID: <xxx>
-
-  [SUCCESS] Channel "My Email" passed all tests
-
-[ul-opencode-event-cli] Test Summary:
-  Passed: 1
-  Failed: 0
-```
-## Troubleshooting
-### SMTP connection failed
-**Q: Does this plugin support IPv4? IPv6?**
-**A: Yes, both are supported.** The plugin uses nodemailer which automatically:
-- Resolves DNS to both IPv4 (A) and IPv6 (AAAA) records
-- Tries both address families in parallel
-- Falls back if one fails
-**Common issues:**
-1. **Wrong password**: Use authorization code for QQ/163, App Password for Gmail
-2. **Wrong port**: Use 465 for SSL, 587 for STARTTLS
-3. **Firewall**: Ensure outbound connections to SMTP port are allowed
-4. **IPv6 issues**: If your network has incomplete IPv6, connections may timeout
-   - Check your network's IPv6 configuration
-   - Contact your network administrator if needed
-### Debug mode
-```bash
-# Enable debug logging
-UL_OPENCODE_EVENT_DEBUG=1 npx @ulthon/ul-opencode-event test
-```
-### No notifications sent
-1. Check if `enabled: true` is set
-2. Check if the event type is enabled in `events`
-3. Check SMTP credentials are correct
-4. Ensure config file exists at correct location
-## Local Development
-```bash
-# Build
-npm run build
-
-# Test locally without publishing
-node dist/cli.js test
-
-# Or use npm link
-npm link
-npx @ulthon/ul-opencode-event test
-
-# Unlink when done
-npm unlink -g @ulthon/ul-opencode-event
-```
-## License
-MIT
+# @ulthon/ul-opencode-event
+
+**Never miss an OpenCode notification, even when you're away from your desk.**
+
+OpenCode multi-channel notification plugin that keeps you informed wherever you are. Get notified when tasks complete or errors occur via email, DingTalk, or Feishu.
+
+## Why ul-opencode-event?
+
+- **Remote Development Friendly** - Get notified when your AI coding agent finishes a task
+- **Multi-Channel Support** - SMTP email, DingTalk robot, Feishu robot, with more planned
+- **Real-time Alerts** - Immediate notifications on session `idle` or `error` events
+- **Easy Configuration** - Simple JSON config with template variables
+
+## Roadmap
+
+| Channel | Status | Description |
+|---------|--------|-------------|
+| SMTP (Email) | Available | Email notifications via any SMTP server |
+| DingTalk | Available | DingTalk robot notifications |
+| Feishu | Available | Feishu robot notifications |
+| Webhook | Planned | HTTP webhook for custom integrations |
+| Telegram | Planned | Telegram bot notifications |
+| Slack | Planned | Slack incoming webhooks |
+| WeChat Work | Planned | Enterprise WeChat |
+
+**Have a channel request?** Open an issue on our [Gitee repo](https://gitee.com/augushong/ul-opencode-event)!
+
+## Quick Start
+
+```bash
+npm install @ulthon/ul-opencode-event
+cp node_modules/@ulthon/ul-opencode-event/examples/ul-opencode-event.json ./
+# Edit config with your SMTP credentials
+npx @ulthon/ul-opencode-event test
+```
+
+Add to `~/.config/opencode/opencode.json`:
+
+```json
+{ "plugin": ["@ulthon/ul-opencode-event"] }
+```
+
+## Configuration
+
+### File Locations
+
+1. **Project-level**: `.opencode/ul-opencode-event.json` or `./ul-opencode-event.json`
+2. **Global**: `~/.config/opencode/ul-opencode-event.json`
+
+Project-level config overrides global (channels merged by name).
+
+### Minimal SMTP Example
+
+```json
+{
+  "channels": [{
+    "type": "smtp",
+    "enabled": true,
+    "name": "My Email",
+    "config": {
+      "host": "smtp.qq.com",
+      "port": 465,
+      "secure": true,
+      "auth": { "user": "your-email@example.com", "pass": "your-app-password" }
+    },
+    "recipients": ["receiver@example.com"],
+    "events": { "idle": true, "error": true }
+  }]
+}
+```
+
+### Common SMTP Servers
+
+| Provider | Host | Port | Auth |
+|----------|------|------|------|
+| QQ Mail | smtp.qq.com | 465 | Authorization code |
+| 163 Mail | smtp.163.com | 465 | Authorization code |
+| Gmail | smtp.gmail.com | 587 | App Password |
+| Outlook | smtp.office365.com | 587 | Password |
+
+> For QQ/163 use the authorization code, not login password. For Gmail use an App Password with 2FA.
+
+### Other Channels
+
+- **DingTalk**: See [docs/dingtalk-channel.md](docs/dingtalk-channel.md) for robot setup, @mentions, and FAQ.
+- **Feishu**: See [docs/feishu-channel.md](docs/feishu-channel.md) for robot setup, card format, and FAQ.
+
+### Events
+
+| Event | Default | Description |
+|-------|---------|-------------|
+| `created` | false | When a new session starts |
+| `idle` | true | When a session completes |
+| `error` | true | When a session encounters an error |
+
+### Template Variables
+
+| Variable | Description | Events |
+|----------|-------------|--------|
+| `{{eventType}}` | Event type (created, idle, error) | All |
+| `{{timestamp}}` | ISO 8601 timestamp | All |
+| `{{projectName}}` | Project short name | All |
+| `{{projectPath}}` | Project full path | All |
+| `{{sessionId}}` | Session ID | All |
+| `{{message}}` | Completion message | idle |
+| `{{duration}}` | Task duration | idle |
+| `{{error}}` | Error message | error |
+
+See [docs/template-configuration.md](docs/template-configuration.md) for customization details.
+
+## CLI Tool
+
+```bash
+npx @ulthon/ul-opencode-event test              # Test all channels
+npx @ulthon/ul-opencode-event test --channel "My Email"  # Test specific channel
+npx @ulthon/ul-opencode-event test --no-send     # Verify connection only
+```
+
+## Documentation
+
+| Document | Description |
+|----------|-------------|
+| [Configuration](docs/configuration.md) | Config file locations, merge rules, events |
+| [SMTP Channel](docs/smtp-channel.md) | Email configuration, IPv4/IPv6, FAQ |
+| [DingTalk Channel](docs/dingtalk-channel.md) | Configuration, @mentions, FAQ |
+| [Feishu Channel](docs/feishu-channel.md) | Configuration, card format, FAQ |
+| [Template Configuration](docs/template-configuration.md) | Template variables and customization |
+| [Channel Development](docs/channel-development.md) | Developing new notification channels |
+
+## Troubleshooting
+
+- **Wrong password**: Use authorization code for QQ/163, App Password for Gmail
+- **Wrong port**: Use 465 for SSL, 587 for STARTTLS
+- **No notifications**: Check `enabled: true`, event types, and config file location
+- **IPv4/IPv6**: Both supported; if IPv6 unstable, set `localAddress` to `"0.0.0.0"`
+- **Debug mode**: `UL_OPENCODE_EVENT_DEBUG=1 npx @ulthon/ul-opencode-event test`
+
+## Local Development
+
+```bash
+npm run build && node dist/cli.js test
+# Or: npm link && npx @ulthon/ul-opencode-event test
+```
+
+## License
+
+MIT

package/dist/cli.js

@@ -14,6 +14,7 @@ import * as os from 'os';
 import { lookup } from 'node:dns/promises';
 import { isIP } from 'node:net';
 import { generateSign, createDingTalkFormatter } from './dingtalk.js';
+import { generateFeishuSign, createFeishuFormatter } from './feishu.js';
 const CLI_PREFIX = '[ul-opencode-event-cli]';
 const LOOKUP_TIMEOUT_MS = 1200;
 /**
@@ -75,8 +76,11 @@ function validateChannel(channel) {
     if (channel.type === 'dingtalk') {
         return validateDingtalkChannel(channel, errors);
     }
+    if (channel.type === 'feishu') {
+        return validateFeishuChannel(channel, errors);
+    }
     if (channel.type !== 'smtp') {
-        errors.push(`Unsupported channel type: "${channel.type}". Supported types: "smtp", "dingtalk".`);
+        errors.push(`Unsupported channel type: "${channel.type}". Supported types: "smtp", "dingtalk", "feishu".`);
         return { valid: false, errors };
     }
     // SMTP validation
@@ -139,6 +143,30 @@ function validateDingtalkChannel(channel, errors) {
     }
     return { valid: errors.length === 0, errors };
 }
+/**
+ * Validate Feishu channel configuration
+ */
+function validateFeishuChannel(channel, errors) {
+    const config = channel.config;
+    // Check webhook URL
+    if (!config.webhook || !config.webhook.trim()) {
+        errors.push('Feishu webhook URL is missing');
+    }
+    else {
+        const webhookUrl = config.webhook.trim();
+        try {
+            new URL(webhookUrl);
+        }
+        catch {
+            errors.push(`Feishu webhook URL is invalid: "${webhookUrl}"`);
+        }
+    }
+    // Check secret (optional but must be non-empty string if provided)
+    if (config.secret !== undefined && typeof config.secret === 'string' && !config.secret.trim()) {
+        errors.push('Feishu secret must be a non-empty string');
+    }
+    return { valid: errors.length === 0, errors };
+}
 /**
  * Create SMTP transporter
  * Supports IPv4/IPv6 via localAddress option
@@ -211,6 +239,10 @@ async function testConnection(channel) {
     if (channel.type === 'dingtalk') {
         return testDingtalkConnection(channel);
     }
+    // Feishu connection test
+    if (channel.type === 'feishu') {
+        return testFeishuConnection(channel);
+    }
     // SMTP connection test (existing logic)
     const config = channel.config;
     const preResolvedHost = await resolveHostViaLookup(config.host);
@@ -311,6 +343,54 @@ async function testDingtalkConnection(channel) {
         return { success: false, error: message };
     }
 }
+/**
+ * Test Feishu webhook connection by sending a minimal text message
+ */
+async function testFeishuConnection(channel) {
+    const config = channel.config;
+    const webhookUrl = config.webhook.trim();
+    // Build message body with signing if secret is configured
+    const body = {
+        msg_type: 'text',
+        content: { text: 'connection test' },
+    };
+    if (config.secret) {
+        // Feishu uses second-level timestamp
+        const timestamp = String(Math.floor(Date.now() / 1000));
+        const sign = await generateFeishuSign(config.secret, timestamp);
+        body.timestamp = timestamp;
+        body.sign = sign;
+    }
+    try {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), 10_000);
+        const response = await fetch(webhookUrl, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(body),
+            signal: controller.signal,
+        });
+        clearTimeout(timer);
+        let result;
+        try {
+            result = (await response.json());
+        }
+        catch {
+            return { success: false, error: 'Failed to parse Feishu API response' };
+        }
+        if (result.code !== undefined && result.code !== 0) {
+            return { success: false, error: `Feishu API error: code=${result.code}, msg=${result.msg ?? 'unknown'}` };
+        }
+        return { success: true };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (message.includes('abort')) {
+            return { success: false, error: 'Feishu connection timed out (10s)' };
+        }
+        return { success: false, error: message };
+    }
+}
 /**
  * Send test email
  */
@@ -454,6 +534,62 @@ If you received this message, your DingTalk notification channel is configured c
         return { success: false, error: message };
     }
 }
+/**
+ * Send test message via Feishu webhook
+ */
+async function sendTestFeishuMessage(channel) {
+    const config = channel.config;
+    const timestamp = new Date().toISOString();
+    const channelName = channel.name || 'Feishu Test';
+    // Use Feishu formatter to generate a properly formatted test message
+    const formatter = createFeishuFormatter(config);
+    const testBody = `This is a test message from OpenCode notification plugin.
+
+Channel: ${channelName}
+Type: ${channel.type}
+Time: ${timestamp}
+
+If you received this message, your Feishu notification channel is configured correctly.`;
+    const formattedMessage = formatter.format(`[Test] OpenCode Notification Channel Test - ${timestamp}`, testBody, { eventType: 'idle', timestamp, projectName: 'test', sessionId: 'cli-test', sessionType: 'main', projectPath: process.cwd() });
+    // Build body with signing if secret is configured
+    const body = { ...formattedMessage };
+    if (config.secret) {
+        // Feishu uses second-level timestamp
+        const ts = String(Math.floor(Date.now() / 1000));
+        const sign = await generateFeishuSign(config.secret, ts);
+        body.timestamp = ts;
+        body.sign = sign;
+    }
+    try {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), 10_000);
+        const response = await fetch(config.webhook.trim(), {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(body),
+            signal: controller.signal,
+        });
+        clearTimeout(timer);
+        let result;
+        try {
+            result = (await response.json());
+        }
+        catch {
+            return { success: false, error: 'Failed to parse Feishu API response' };
+        }
+        if (result.code !== undefined && result.code !== 0) {
+            return { success: false, error: `Feishu API error: code=${result.code}, msg=${result.msg ?? 'unknown'}` };
+        }
+        return { success: true, messageId: `feishu-${timestamp}` };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (message.includes('abort')) {
+            return { success: false, error: 'Feishu send timed out (10s)' };
+        }
+        return { success: false, error: message };
+    }
+}
 /**
  * Test a single channel
  */
@@ -473,10 +609,15 @@ async function testChannel(channel, options) {
     console.log(`  [OK] Configuration is valid`);
     // Step 2: Test connection (type-specific output)
     const isDingtalk = channel.type === 'dingtalk';
+    const isFeishu = channel.type === 'feishu';
     if (isDingtalk) {
         const dtConfig = channel.config;
         console.log(`\n  [2/3] Testing DingTalk webhook: ${dtConfig.webhook}...`);
     }
+    else if (isFeishu) {
+        const fsConfig = channel.config;
+        console.log(`\n  [2/3] Testing Feishu webhook: ${fsConfig.webhook}...`);
+    }
     else {
         const smtpConfig = channel.config;
         console.log(`\n  [2/3] Testing SMTP connection to ${smtpConfig.host}:${smtpConfig.port}...`);
@@ -492,7 +633,7 @@ async function testChannel(channel, options) {
     }
     // Step 3: Send test message (if not skipped)
     if (options.noSend) {
-        const skipLabel = isDingtalk ? 'test message' : 'test email';
+        const skipLabel = isDingtalk || isFeishu ? 'test message' : 'test email';
         console.log(`\n  [3/3] Skipping ${skipLabel} (--no-send flag)`);
         console.log(`\n  [SUCCESS] Channel "${channelName}" passed all tests (connection only)`);
         return true;
@@ -512,6 +653,21 @@ async function testChannel(channel, options) {
         console.log(`\n  [SUCCESS] Channel "${channelName}" passed all tests`);
         console.log(`  Please check your DingTalk group chat.`);
     }
+    else if (isFeishu) {
+        console.log(`\n  [3/3] Sending test message to Feishu...`);
+        const sendResult = await sendTestFeishuMessage(channel);
+        if (!sendResult.success) {
+            console.log(`  [FAIL] Failed to send test message: ${sendResult.error}`);
+            return false;
+        }
+        console.log(`  [OK] Test message sent successfully`);
+        if (sendResult.info) {
+            console.log(`  [INFO] ${sendResult.info}`);
+        }
+        console.log(`  Message ID: ${sendResult.messageId}`);
+        console.log(`\n  [SUCCESS] Channel "${channelName}" passed all tests`);
+        console.log(`  Please check your Feishu group chat.`);
+    }
     else {
         console.log(`\n  [3/3] Sending test email...`);
         const sendResult = await sendTestEmail(channel);

package/dist/config.js

@@ -3,7 +3,7 @@ import * as path from 'path';
 import * as os from 'os';
 import { DEFAULT_SESSION_TYPES } from './types.js';
 import { logger } from './logger.js';
-const SUPPORTED_CHANNEL_TYPES = ['smtp', 'dingtalk'];
+const SUPPORTED_CHANNEL_TYPES = ['smtp', 'dingtalk', 'feishu'];
 /**
  * Default configuration returned when no config files exist
  */

package/dist/feishu.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Feishu (Lark) custom robot webhook sender module
+ *
+ * Sends notifications via Feishu custom robot webhook API using interactive cards.
+ * Uses Web Crypto API for HMAC-SHA256 signing (no external dependencies).
+ * Uses Node.js built-in fetch for HTTP requests.
+ *
+ * Reference: https://open.feishu.cn/document/client-docs/bot-v3/add-custom-bot
+ */
+import type { Channel, ChannelSender, ChannelFormatter, FeishuConfig } from './types.js';
+/**
+ * Generate HmacSHA256 signature for Feishu webhook authentication.
+ *
+ * Algorithm: base64(hmac_sha256(timestamp + "\n" + secret, ""))
+ *
+ * Key difference from DingTalk:
+ * - Feishu: key = timestamp + "\n" + secret, message = "" (empty)
+ * - DingTalk: key = secret, message = timestamp + "\n" + secret
+ *
+ * @param secret - The robot signing secret
+ * @param timestamp - Second-level timestamp string
+ * @returns Base64-encoded signature
+ */
+export declare function generateFeishuSign(secret: string, timestamp: string): Promise<string>;
+/**
+ * Create a Feishu interactive card formatter.
+ *
+ * Converts subject + body into Feishu's interactive card JSON structure:
+ * { msg_type: "interactive", card: { header, elements } }
+ *
+ * Formatting rules:
+ * - Subject becomes card header title, truncated at 100 chars
+ * - Lines matching "key: value" get bold keys (**key**: value)
+ * - Error-looking lines wrapped in ``` code blocks
+ * - No DingTalk-style character escaping (lark_md uses standard Markdown)
+ * - Total content truncated at 4000 chars
+ */
+export declare function createFeishuFormatter(_config: FeishuConfig): ChannelFormatter;
+/**
+ * Create a Feishu webhook sender for the given channel configuration.
+ *
+ * Factory function that validates channel config and returns a sender
+ * or null if the channel is invalid/disabled.
+ *
+ * Validation:
+ * - channel.type must be 'feishu'
+ * - channel.enabled must not be false
+ * - webhook URL must be present and look valid (http:// or https://)
+ */
+export declare function createFeishuSender(channel: Channel): Promise<ChannelSender | null>;

package/dist/feishu.js

@@ -0,0 +1,209 @@
+/**
+ * Feishu (Lark) custom robot webhook sender module
+ *
+ * Sends notifications via Feishu custom robot webhook API using interactive cards.
+ * Uses Web Crypto API for HMAC-SHA256 signing (no external dependencies).
+ * Uses Node.js built-in fetch for HTTP requests.
+ *
+ * Reference: https://open.feishu.cn/document/client-docs/bot-v3/add-custom-bot
+ */
+import { logger } from './logger.js';
+// ─── Signing ───────────────────────────────────────────────
+/**
+ * Generate HmacSHA256 signature for Feishu webhook authentication.
+ *
+ * Algorithm: base64(hmac_sha256(timestamp + "\n" + secret, ""))
+ *
+ * Key difference from DingTalk:
+ * - Feishu: key = timestamp + "\n" + secret, message = "" (empty)
+ * - DingTalk: key = secret, message = timestamp + "\n" + secret
+ *
+ * @param secret - The robot signing secret
+ * @param timestamp - Second-level timestamp string
+ * @returns Base64-encoded signature
+ */
+export async function generateFeishuSign(secret, timestamp) {
+    if (!secret) {
+        return '';
+    }
+    const stringToSign = `${timestamp}\n${secret}`;
+    const encoder = new TextEncoder();
+    // Feishu: key = timestamp + "\n" + secret
+    const keyData = encoder.encode(stringToSign);
+    // Feishu: message = "" (empty)
+    const data = encoder.encode('');
+    const cryptoKey = await crypto.subtle.importKey('raw', keyData, { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
+    const signature = await crypto.subtle.sign('HMAC', cryptoKey, data);
+    // Convert ArrayBuffer to base64 without Buffer (pure browser/Node compat)
+    return btoa(String.fromCharCode(...new Uint8Array(signature)));
+}
+// ─── Formatting ────────────────────────────────────────────
+/** Max title length before truncation */
+const MAX_TITLE_LENGTH = 100;
+/** Max content length before truncation */
+const MAX_CONTENT_LENGTH = 4000;
+/** Keep this many chars when truncating */
+const TRUNCATE_KEEP_LENGTH = 3800;
+const TRUNCATE_SUFFIX = '\n... (truncated)';
+/** Pattern to detect key: value lines for bold formatting */
+const KEY_VALUE_PATTERN = /^(\s*\w[\w\s]*?)\s*:\s*(.+)$/;
+/** Pattern to detect error-like content */
+const ERROR_INDICATORS = /\b(error|Error|stack trace|Stack|Exception)\b/;
+/**
+ * Create a Feishu interactive card formatter.
+ *
+ * Converts subject + body into Feishu's interactive card JSON structure:
+ * { msg_type: "interactive", card: { header, elements } }
+ *
+ * Formatting rules:
+ * - Subject becomes card header title, truncated at 100 chars
+ * - Lines matching "key: value" get bold keys (**key**: value)
+ * - Error-looking lines wrapped in ``` code blocks
+ * - No DingTalk-style character escaping (lark_md uses standard Markdown)
+ * - Total content truncated at 4000 chars
+ */
+export function createFeishuFormatter(_config) {
+    return {
+        format(subject, body, _payload) {
+            // 1. Title: truncate at 100 chars with ... suffix
+            const rawTitle = subject.trim();
+            const title = rawTitle.length > MAX_TITLE_LENGTH
+                ? rawTitle.slice(0, MAX_TITLE_LENGTH) + '...'
+                : rawTitle;
+            // 2. Process body lines
+            const processedLines = [];
+            for (const line of body.split('\n')) {
+                const trimmed = line.trim();
+                if (!trimmed) {
+                    processedLines.push('');
+                    continue;
+                }
+                // Check for key: value pattern -> **key**: value
+                const kvMatch = trimmed.match(KEY_VALUE_PATTERN);
+                if (kvMatch && kvMatch[1] && kvMatch[2]) {
+                    processedLines.push(`**${kvMatch[1].trim()}**: ${kvMatch[2].trim()}`);
+                    continue;
+                }
+                // Check for error-like content -> wrap in code block
+                if (ERROR_INDICATORS.test(trimmed)) {
+                    processedLines.push(`\`\`\`\n${trimmed}\n\`\`\``);
+                    continue;
+                }
+                // Default: pass through (lark_md supports standard Markdown)
+                processedLines.push(trimmed);
+            }
+            // 3. Join lines
+            let text = processedLines.join('\n');
+            if (text.length > MAX_CONTENT_LENGTH) {
+                text = text.slice(0, TRUNCATE_KEEP_LENGTH) + TRUNCATE_SUFFIX;
+            }
+            // 4. Build interactive card message
+            const message = {
+                msg_type: 'interactive',
+                card: {
+                    config: { wide_screen_mode: true },
+                    header: {
+                        title: { tag: 'plain_text', content: title },
+                        template: 'blue',
+                    },
+                    elements: [
+                        {
+                            tag: 'div',
+                            text: { tag: 'lark_md', content: text },
+                        },
+                    ],
+                },
+            };
+            return message;
+        },
+    };
+}
+// ─── Sending ──────────────────────────────────────────────
+const FETCH_TIMEOUT_MS = 10_000;
+/**
+ * Create a Feishu webhook sender for the given channel configuration.
+ *
+ * Factory function that validates channel config and returns a sender
+ * or null if the channel is invalid/disabled.
+ *
+ * Validation:
+ * - channel.type must be 'feishu'
+ * - channel.enabled must not be false
+ * - webhook URL must be present and look valid (http:// or https://)
+ */
+export async function createFeishuSender(channel) {
+    if (channel.type !== 'feishu') {
+        return null;
+    }
+    if (channel.enabled === false) {
+        return null;
+    }
+    const config = channel.config;
+    if (!config.webhook) {
+        return null;
+    }
+    // Validate webhook URL format
+    const webhookUrl = config.webhook.trim();
+    if (!webhookUrl.startsWith('http://') && !webhookUrl.startsWith('https://')) {
+        return null;
+    }
+    const channelName = channel.name || 'Feishu';
+    const secret = config.secret;
+    return {
+        send: async (message) => {
+            // Expect FormattedMessage from createFeishuFormatter
+            const msg = message;
+            if (!msg || msg.msg_type !== 'interactive' || !msg.card) {
+                return;
+            }
+            // Build message body (sign goes in body, not URL)
+            const body = { ...msg };
+            if (secret) {
+                // Feishu uses second-level timestamp (not milliseconds like DingTalk)
+                const timestamp = String(Math.floor(Date.now() / 1000));
+                const sign = await generateFeishuSign(secret, timestamp);
+                body.timestamp = timestamp;
+                body.sign = sign;
+            }
+            // Send via fetch with timeout
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+            logger.debug(`Feishu webhook POST ${webhookUrl}`);
+            try {
+                const response = await fetch(webhookUrl, {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify(body),
+                    signal: controller.signal,
+                });
+                clearTimeout(timer);
+                logger.debug(`Feishu response: ${response.status} ${response.statusText}`);
+                // Parse response - Feishu returns { code: 0, msg: "success" }
+                let result;
+                try {
+                    result = (await response.json());
+                }
+                catch {
+                    result = {};
+                }
+                if (result.code !== undefined && result.code !== 0) {
+                    // Feishu API returned an error
+                    logger.debug(`[${channelName}] Feishu API error: code=${result.code}, msg=${result.msg ?? 'unknown'}`);
+                    return;
+                }
+                // Success (code === 0 or no code in response)
+                logger.debug(`[${channelName}] Feishu message sent successfully`);
+            }
+            catch (error) {
+                clearTimeout(timer);
+                // Network error or abort - log error
+                const message = error instanceof Error ? error.message : String(error);
+                logger.error(`Feishu send failed: ${message}`);
+            }
+        },
+        close: async () => {
+            // No persistent connections for HTTP-based webhook sending
+            // This is a no-op but required by ChannelSender interface
+        },
+    };
+}

package/dist/formatters.d.ts

@@ -6,7 +6,7 @@
  *
  * - SMTP: pass-through (subject + text body)
  * - DingTalk: Markdown formatting with escaping and truncation
- * - Feishu: not yet implemented
+ * - Feishu: Interactive card messages for Feishu bots
  */
 import type { ChannelType, Channel, ChannelFormatter } from './types.js';
 /**
@@ -25,3 +25,4 @@ export declare const emailFormatter: ChannelFormatter;
  */
 export declare function getFormatter(channelType: ChannelType, channel: Channel): ChannelFormatter | null;
 export { createDingTalkFormatter } from './dingtalk.js';
+export { createFeishuFormatter } from './feishu.js';

package/dist/formatters.js

@@ -6,9 +6,10 @@
  *
  * - SMTP: pass-through (subject + text body)
  * - DingTalk: Markdown formatting with escaping and truncation
- * - Feishu: not yet implemented
+ * - Feishu: Interactive card messages for Feishu bots
  */
 import { createDingTalkFormatter } from './dingtalk.js';
+import { createFeishuFormatter } from './feishu.js';
 // ─── Email Formatter (SMTP) ──────────────────────────────
 /**
  * Email/pass-through formatter for SMTP channels.
@@ -25,7 +26,7 @@ export const emailFormatter = {
 /** Built-in formatter lookup by channel type (excluding dingtalk which needs config) */
 const FORMATTER_REGISTRY = {
     smtp: emailFormatter,
-    // feishu: not implemented -> returns null via getFormatter fallback
+    // dingtalk and feishu formatters created dynamically via getFormatter
 };
 // ─── Public API ──────────────────────────────────────────
 /**
@@ -39,7 +40,11 @@ export function getFormatter(channelType, channel) {
     if (channelType === 'dingtalk') {
         return createDingTalkFormatter(channel.config);
     }
+    if (channelType === 'feishu') {
+        return createFeishuFormatter(channel.config);
+    }
     return FORMATTER_REGISTRY[channelType] ?? null;
 }
 // ─── Re-exports ──────────────────────────────────────────
 export { createDingTalkFormatter } from './dingtalk.js';
+export { createFeishuFormatter } from './feishu.js';

package/dist/handler.js

@@ -62,6 +62,19 @@ export function createEventHandler(config) {
                             logger.error(`Failed to initialize channel '${channel.name ?? String(i)}': ${error instanceof Error ? error.message : String(error)}`);
                         }
                     }
+                    else if (channel.type === 'feishu' && channel.enabled !== false) {
+                        try {
+                            const feishuModule = await import('./feishu.js');
+                            const sender = await feishuModule.createFeishuSender(channel);
+                            if (sender) {
+                                const key = channel.name || `channel-${i}`;
+                                senders.set(key, sender);
+                            }
+                        }
+                        catch (error) {
+                            logger.error(`Failed to initialize channel '${channel.name ?? String(i)}': ${error instanceof Error ? error.message : String(error)}`);
+                        }
+                    }
                 }
             }
             // Process each channel using cached senders

package/dist/types.d.ts

@@ -42,7 +42,6 @@ export interface Channel {
 }
 /**
  * Supported channel types
- * Phase 1: Only SMTP is implemented
  */
 export type ChannelType = 'smtp' | 'feishu' | 'dingtalk';
 /**
@@ -69,10 +68,12 @@ export interface SMTPConfig {
     };
 }
 /**
- * Feishu channel configuration (placeholder for future)
+ * Feishu (Lark) custom robot channel configuration
  */
 export interface FeishuConfig {
     webhook: string;
+    /** Secret for HMAC-SHA256 signature verification */
+    secret?: string;
 }
 /**
  * DingTalk channel configuration (placeholder for future)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ulthon/ul-opencode-event",
-  "version": "0.1.27",
-  "description": "OpenCode notification plugin - sends notifications via email or DingTalk when session events occur",
+  "version": "0.1.28",
+  "description": "OpenCode notification plugin - sends notifications via email, DingTalk, or Feishu when session events occur",
   "author": "augushong",
   "license": "MIT",
   "type": "module",
@@ -31,6 +31,7 @@
     "email",
     "smtp",
     "dingtalk",
+    "feishu",
     "cli"
   ],
   "files": [