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

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

⚠️ 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

⚡ Single-User Mode: Zero Configuration

Recommended for personal use!

# 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

👥 Multi-User Mode: Manual Configuration

For teams and organizations.

# 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

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)

📖 Guide: 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

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 ✅

// 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

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

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

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

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)

{
  "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)

{
  "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

# 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

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)

Feishu Agent Relay - Multi-Bot Collabora