Skill: glassmarbles/feishu-agent-relay (version 1.0.0)

--- name: feishu-agent-relay description: Build multi-Agent collaboration systems on Feishu (Lark). Provides complete patterns for: (1) orchestrator-specialist Agent architecture, (2) cross-Agent user identity mapping with Feishu open_id isolation, (3) Agent-to-Agent task relay via sessions_send, (4) specialist Agents proactively messaging users. Use when building multi-Bot coordination workflows where users contact one Bot but receive responses from different specialist Bots. --- # Feishu Agent Relay ## 🚨 Installation: Choose Your Mode First! **⚠️ BEFORE SETUP: You must choose a deployment mode!** | Mode | For | User ID | Setup | Security | |------|-----|---------|-------|----------| | **Single-User** | Personal use | Auto ("me") | ✅ 5 min | ✅ High | | **Multi-User** | Teams | Manual entry | ⚠️ 30 min | ⚠️ Low | ### Quick Decision Guide **Choose Single-User Mode if:** - ✅ Only YOU will use the Bots - ✅ Personal productivity system - ✅ Want ZERO manual configuration - ✅ Want fastest setup (5 minutes) 📖 **Guide:** [references/single-user-setup.md](references/single-user-setup.md) **Choose Multi-User Mode if:** - ✅ Multiple people will use the system - ✅ Team or organization - ✅ Need to track different users - ✅ Planning to add verification later 📖 **Guide:** [references/feishu-bot-setup.md](references/feishu-bot-setup.md) --- ## ⚠️ Important Limitations **Read this before using the skill:** ### 1. Manual User ID Registration ⚠️ SECURITY LIMITATION (Multi-User Mode Only) **Current flow requires users to manually enter their User ID:** ``` User → Bot: "你好" Bot → User: "请告诉我您的 User ID（工号/用户名）" User → Bot: "我的 user ID 是：user_demo_001" ← ⚠️ MANUAL STEP - NO VERIFICATION ``` **⚠️ Risks:** - ❌ **No identity verification** - System trusts whatever user types - ❌ **Identity spoofing possible** - User could claim another person's ID - ❌ **Human error** - Users may mistype their ID - ❌ **No audit trail** - Cannot prove who actually registered - ❌ **NOT production-ready** - **Internal/personal use ONLY** **✅ Acceptable for:** - Personal projects (use Single-User Mode!) - Small team internal tools - Testing and prototyping **❌ NOT acceptable for:** - Production systems - External-facing applications - Security-sensitive operations **🔧 Single-User Mode avoids this:** No manual ID entry needed! --- ### 2. Multiple Feishu Bots Required 🔧 SETUP REQUIRED This skill requires **multiple Feishu Bot applications**: | Bot Type | Quantity | Example Names | |----------|----------|---------------| | **Coordinator** | 1 | 协调员 | | **Specialists** | 2+ | 技术专家，产品专家 | 📖 **Setup Guide:** [references/feishu-bot-setup.md](references/feishu-bot-setup.md) --- ## ⚡ Single-User Mode: Zero Configuration **Recommended for personal use!** ```bash # 1. Set environment variable export DEPLOYMENT_MODE=single-user # 2. Create empty mapping table (no users needed) cat > user-mapping.json << 'EOF' { "version": "1.0", "users": {}, "agents": { ... } } EOF # 3. Contact any Bot - auto-registers you! # That's it! No manual User ID entry needed. ``` **How it works:** - First contact: Bot auto-registers you as userid "me" - All Bots: Automatically track your open_id - Relay: Uses hardcoded userid "me" (no queries needed) - Security: No identity spoofing risk (only you) 📖 **Full guide:** [references/single-user-setup.md](references/single-user-setup.md) --- ## 👥 Multi-User Mode: Manual Configuration **For teams and organizations.** ```bash # 1. Set environment variable export DEPLOYMENT_MODE=multi-user # 2. Each user must register: User → Bot: "你好" Bot → User: "请告诉我您的 User ID" User → Bot: "我的 user ID 是：zhangsan" ``` **⚠️ Security Warning:** Manual User ID entry has NO verification. Internal use only! 📖 **Full guide:** [references/feishu-bot-setup.md](references/feishu-bot-setup.md) --- ## Quick Start This skill enables **multi-Agent collaboration on Feishu** where: - Users contact a **coordinator Bot** - Coordinator relays tasks to **specialist Bots** - Specialists **proactively message users** ``` User → Coordinator Bot → sessions_send → Specialist Bot → User (proactive DM) (userid only) queries mapping ``` --- ## 📋 Setup Checklist ### Phase 1: Feishu Bot Configuration (~30 minutes) - [ ] Create Feishu Developer Account - [ ] Create Coordinator Bot + Specialist Bots - [ ] Configure Permissions - [ ] Configure Event Subscriptions - [ ] Test Each Bot 📖 **Guide**: [references/feishu-bot-setup.md](references/feishu-bot-setup.md) ### Phase 2: Choose Deployment Mode - [ ] **Single-User**: Set `DEPLOYMENT_MODE=single-user` - [ ] **Multi-User**: Set `DEPLOYMENT_MODE=multi-user` - [ ] Initialize mapping table - [ ] Deploy mapping API 📖 **Single-User Guide**: [references/single-user-setup.md](references/single-user-setup.md) ### Phase 3: Testing (~15 minutes) - [ ] Test first contact (auto-register or manual) - [ ] Test relay flow - [ ] Test proactive message - [ ] Verify mapping table --- ## When to Use This Skill **Use when:** - ✅ Multiple Feishu Bots working together - ✅ Users contact one Bot, receive responses from different Bots - ✅ Cross-Bot user identity management needed - ✅ Specialist Bots proactively message users **Don't use for:** - ❌ Single-Bot scenarios - ❌ Production without verification (multi-user) - ❌ External-facing applications --- ## Architecture ``` ┌─────────────────┐ │ User │ │ (Feishu DM) │ └────────┬────────┘ │ 1. User contacts coordinator ▼ ┌─────────────────┐ 2. Coordinator identifies user │ Coordinator │ (auto or manual) │ Agent │ │ (orchestrator) │ 3. Relay via sessions_send └────────┬────────┘ (userid only) │ ▼ ┌─────────────────┐ 4. Specialist queries mapping │ Specialist │ for own open_id │ Agent │ └────────┬────────┘ 5. Send proactive DM │ ▼ ┌─────────────────────────┐ │ user-mapping.json │ │ userid → open_id map │ └─────────────────────────┘ ``` --- ## Critical Concept: Feishu open_id Isolation **Each Bot has different open_id for the same user:** ``` Same user (userid: user_demo_001): ├─ Coordinator Bot: ou_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa ├─ Tech Expert Bot: ou_bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb └─ Product Expert Bot: ou_cccccccccccccccccccccccccccccccc ``` **You CANNOT use one Bot's open_id for another Bot!** ### Correct Relay Pattern ✅ ```javascript // 1. Coordinator queries userid const user = await mapping.getUserByOpenId('coordinator', userOpenId); // 2. Send relay (userid only, NO open_id) await sessions_send({ agentId: 'product-expert', sessionKey: 'agent:product-expert:main', // ✅ Key! message: `【转接任务】用户 User ID: ${user.userid}` }); // 3. Specialist queries mapping for ITS OWN open_id const userOpenId = mapping.users[userId]?.botOpenIds?.['product-expert']; // 4. Send message using correct open_id await message({ action: 'send', channel: 'feishu', target: userOpenId, // ✅ This Bot's open_id message: '您好，我是产品专家...' }); ``` --- ## Workflows ### Workflow 1A: Single-User - Auto Registration ```javascript const DEPLOYMENT_MODE = process.env.DEPLOYMENT_MODE || 'single-user'; const SINGLE_USER_ID = 'me'; const userOpenId = getMessageContext().from; // Auto-register on first contact const existing = await mapping.getBotOpenId(SINGLE_USER_ID, 'coordinator'); if (!existing) { await mapping.updateBotOpenId(SINGLE_USER_ID, 'coordinator', userOpenId, 'Default User'); await message({ message: `您好！🎉 系统已自动配置完成（单用户模式）。` }); return; } ``` ### Workflow 1B: Multi-User - Manual Registration ```javascript const userOpenId = getMessageContext().from; const user = await mapping.getUserByOpenId('coordinator', userOpenId); if (!user) { // Ask for User ID await message({ message: `您好！请告诉我您的 User ID（工号/用户名）。` }); return; } await mapping.updateBotOpenId(user.userid, 'coordinator', userOpenId, user.name); ``` ### Workflow 2: Coordinator Relay ```javascript const user = await mapping.getUserByOpenId('coordinator', userOpenId); await sessions_send({ agentId: 'product-expert', sessionKey: 'agent:product-expert:main', message: `【转接任务】用户 User ID: ${user.userid}, 任务：${task}` }); ``` ### Workflow 3: Specialist Proactive Message ```javascript const userId = extractUserId(message); const userOpenId = mapping.users[userId]?.botOpenIds?.['product-expert']; if (!userOpenId) { await sessions_send({ agentId: 'coordinator', message: `用户 ${userId} 尚未与我建立对话` }); return; } await message({ action: 'send', channel: 'feishu', target: userOpenId, message: '您好，我是产品专家...' }); ``` --- ## User Mapping Table ### Single-User Mode (Auto-populated) ```json { "version": "1.0", "users": { "me": { "name": "Default User", "botOpenIds": { "coordinator": "ou_xxx", "tech-expert": "ou_yyy", "product-expert": "ou_zzz" } } }, "agents": { ... } } ``` ### Multi-User Mode (Manual registration) ```json { "version": "1.0", "users": { "zhangsan": { "name": "张三", "botOpenIds": { "coordinator": "ou_abc...", "product-expert": "ou_def..." } }, "lisi": { ... } }, "agents": { ... } } ``` --- ## Configuration ### Environment Variables | Variable | Values | Default | Description | |----------|--------|---------|-------------| | `DEPLOYMENT_MODE` | `single-user`, `multi-user` | `multi-user` | Deployment mode | | `SINGLE_USER_ID` | Any string | `"me"` | User ID for single-user | ### Agent SOUL.md Template ```markdown # SOUL.md - 协调者 ## 部署模式 - Mode: single-user (或 multi-user) - User ID: "me" (single-user) 或 dynamic (multi-user) ## 配置 - Bot App ID: cli_xxx - 映射表：/path/to/user-mapping.json ``` --- ## Error Handling ### 400 "cross app open_id" **Cause:** Using wrong Bot's open_id. **Fix:** Each Bot must use its own open_id from mapping. ### User not found **Cause:** First-time user, not registered. **Fix:** Auto-register (single-user) or ask for ID (multi-user). --- ## Testing Checklist - [ ] Bots created and configured - [ ] Deployment mode set - [ ] Mapping table initialized - [ ] First contact works - [ ] Relay flow works - [ ] Proactive message works - [ ] Mapping table updated correctly --- ## Best Practices ### DO ✅ - Use `agent:xxx:main` for sessionKey - Pass only userid in relay - Let specialists query own open_id - Use mapping API (not direct file access) - **Choose appropriate deployment mode** - **Auto-register in single-user mode** ### DON'T ❌ - Pass open_id in relay - Use one Bot's open_id for another - Use `feishu:direct:openid` sessionKey - **Use multi-user for production without verification** - **Share single-user Bots with others** --- ## Security Considerations ### Single-User Mode ✅ - No identity spoofing risk (only you) - No manual ID entry - Automatic registration - **Recommended for personal use** ### Multi-User Mode ⚠️ - Manual ID entry (no verification) - Identity spoofing possible - **Internal use only** - **Add verification for production** --- ## Resources ### scripts/ - `mapping-api.js` - Unified mapping API ### references/ - **`single-user-setup.md`** - Single-user mode guide (START HERE for personal use) - **`feishu-bot-setup.md`** - Multi-user mode guide - `mapping-schema.md` - Schema details - `relay-examples.md` - Code examples --- **Version:** 1.2 **Last Updated:** 2026-03-07 **Deployment Modes:** Single-User (zero-config) | Multi-User (manual) **Recommendation:** Start with Single-User for testing, switch to Multi-User for teams **Status:** ✅ Functional for internal/personal use | ⚠️ Not production-ready (multi-user mode)


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (HIGH)