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