Enables multi-Agent collaboration on Feishu by relaying tasks between coordinator and specialist Bots with user ID mapping and proactive messaging.
---
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)
don't have the plugin yet? install it then click "run inline in claude" again.