Lark

Lark

Lark (international) communication channel for zylos.

Depends on: comm-bridge (C4 message routing).

Bundled Capability Modules (lark-cli)

This skill bundles 27 capability modules under references/, each operating against Lark via the lark-cli binary. They are not auto-loaded as top-level skills — Claude Code's skill discovery only scans top-level directories, and these sub-modules live inside this skill. The parent SKILL.md (this file) is the entry point.

How to use a module: when a user's request maps to one of the modules below, Read that module's SKILL.md first to learn its exact commands/flags, then invoke lark-cli <module> ....

Prerequisites (installed automatically by zylos add lark / zylos upgrade lark — see hooks/post-install-shared.js):

• lark-cli binary on PATH (npm install -g @larksuite/cli).
• 27 sub-skill folders under references/lark-*/ (npx xc-skills add larksuite/cli).
• App credentials in lark-cli's keychain (~/.lark-cli/config.json + AES-256-GCM encrypted file under ~/.local/share/lark-cli/); pushed from ~/zylos/.env automatically.

Identity (--as bot vs --as user):

⚠️ Prefer user identity for content operations. When querying or editing documents, wiki / knowledge bases, drive files, sheets, or Base via lark-cli, default to --as user (OAuth-authorized; 7-day rolling refresh token). The bot identity is not a member of any knowledge space and lacks drive scopes, so bot-identity content queries silently find nothing. Bot identity is appropriate for IM messaging operations.

• --as bot works out of the box for app/tenant-level operations (IM messaging, contacts, events). No extra login needed.
• --as user is the default for content operations (docs, wiki, drive, sheets, Base — see note above) and is required for surfaces tied to a real user's data (calendar, mail-write, tasks, attendance, OKR, minutes, VC-agent). The user runs lark-cli auth login --domain <name> once. On auth failure lark-cli exits with a <domain>_user_login_required error envelope; the agent should detect this and notify the owner of the login command.

Module Index

Path prefix for all entries: references/

Messaging & people

Docs & drive

Productivity

HR / workflow

Meetings & A/V

Apps & low-code

Workflows & platform

Loading Convention

Before running lark-cli <module> <subcmd>:

1. Read references/<module>/SKILL.md to confirm exact subcommands, flags, and required vs. optional args.
2. If that module's SKILL.md references additional docs under its own references/ subdirectory, read those as well.
3. Run the command.

Skipping step 1 risks calling wrong subcommand names or missing required flags — lark-cli is feature-rich and each module covers dozens of subcommands.

Sending Messages

# Via C4 bridge (standard path — always use stdin form)
cat <<'EOF' | node ~/zylos/.claude/skills/comm-bridge/scripts/c4-send.js "lark" "<chat_id>"
Hello!
EOF

# Send image
cat <<'EOF' | node ~/zylos/.claude/skills/comm-bridge/scripts/c4-send.js "lark" "<chat_id>"
[MEDIA:image]/path/to/image.png
EOF

# Send file
cat <<'EOF' | node ~/zylos/.claude/skills/comm-bridge/scripts/c4-send.js "lark" "<chat_id>"
[MEDIA:file]/path/to/file.pdf
EOF

⚠️ [MEDIA:...] must be the only content in the message. Send text and media as separate calls.

Direct send (bypasses C4 logging, for testing only):

node ~/zylos/.claude/skills/lark/scripts/send.js <chat_id> "Hello!"

CLI Commands

# Test authentication
npm run cli test

# Send messages
npm run cli send-group oc_xxx "Hello"

# Documents
npm run cli doc <doc_id>
npm run cli sheet-read <token> <range>

# Calendar
npm run cli calendar --days 7

# Groups
npm run cli chats

Admin CLI

Manage bot configuration via admin.js:

ADM="node ~/zylos/.claude/skills/lark/src/admin.js"

# General
$ADM show                                    # Show full config
$ADM show-owner                              # Show current owner
$ADM help                                    # Show all commands

# DM Access Control
$ADM set-dm-policy <open|allowlist|owner>     # Set DM policy
$ADM list-dm-allow                            # Show DM policy + allowFrom list
$ADM add-dm-allow <user_id_or_open_id>        # Add user to dmAllowFrom
$ADM remove-dm-allow <user_id_or_open_id>     # Remove user from dmAllowFrom

# Group Management
$ADM list-groups                              # List all configured groups
$ADM add-group <chat_id> <name> [mode]        # Add group (mode: mention|smart)
$ADM remove-group <chat_id>                   # Remove a group
$ADM set-group-policy <disabled|allowlist|open>  # Set group policy
$ADM set-group-allowfrom <chat_id> <id1,id2>  # Set per-group allowed senders
$ADM set-group-history-limit <chat_id> <n>    # Set per-group context message limit
$ADM migrate-groups                           # Migrate legacy group config to new format

# Legacy aliases (backward-compatible, map to commands above)
# list-allowed-groups, add-allowed-group, remove-allowed-group → list-groups, add-group, remove-group
# list-smart-groups, add-smart-group, remove-smart-group → list-groups, add-group, remove-group
# enable-group-whitelist, disable-group-whitelist → set-group-policy allowlist|open
# list-whitelist, add-whitelist, remove-whitelist → list-dm-allow, add-dm-allow, remove-dm-allow
# enable-whitelist, disable-whitelist → set-dm-policy allowlist|open

After changes, restart: pm2 restart zylos-lark

Downloading Media by Resource Key

In smart group mode, images and files sent without @mention are logged with metadata only (image_key/file_key). Use download.js to fetch them on demand:

# Download image
node ~/zylos/.claude/skills/lark/scripts/download.js image <message_id> <image_key>

# Download file
node ~/zylos/.claude/skills/lark/scripts/download.js file <message_id> <file_key> [filename]

# Examples:
node ~/zylos/.claude/skills/lark/scripts/download.js image om_xxx img_v3_xxx
node ~/zylos/.claude/skills/lark/scripts/download.js file om_xxx file_v3_xxx report.pdf

The keys come from context messages like [image, image_key: xxx, msg_id: xxx] or [file: name.pdf, file_key: xxx, msg_id: xxx].

Output: local file path on success, error message on failure.

Config Location

• Config: ~/zylos/components/lark/config.json
• Logs: ~/zylos/components/lark/logs/
• Media: ~/zylos/components/lark/media/

Lark Setup

1. Credentials

Add to ~/zylos/.env:

LARK_APP_ID=your_app_id
LARK_APP_SECRET=your_app_secret

Get App ID and App Secret from your app's Credentials page: open.larksuite.com/app

2. Console Configuration

In the Lark developer console (open.larksuite.com/app):

1. Enable Bot capability: Add capabilities → Bot (添加应用能力 → 机器人)
2. Subscribe to events: Event subscriptions → Add im.message.receive_v1
3. Set Request URL: Event subscriptions → Request URL → https://<your-domain>/lark/webhook (the path is defined by http_routes in SKILL.md)

3. Event Security

Lark provides two security mechanisms for webhook events.

Verification Token (REQUIRED) — validates that requests come from Lark. The service will refuse to start without it.

In the console: Event subscriptions → Verification Token. Add to config:

{
  "bot": {
    "verification_token": "your_verification_token_from_lark"
  }
}

Encrypt Key — encrypts event payloads using AES-256-CBC:

In the console: Event subscriptions → Encrypt Key. Add to config:

{
  "bot": {
    "encrypt_key": "your_encrypt_key_from_lark"
  }
}

Both can be set together:

{
  "bot": {
    "verification_token": "your_token",
    "encrypt_key": "your_key"
  }
}

Cloudflare Users

If your domain is behind Cloudflare proxy with Flexible SSL mode, Caddy's automatic HTTPS will cause a redirect loop. Options:

1. Change Cloudflare SSL to Full: In Cloudflare dashboard → SSL/TLS → set mode to "Full" (recommended)
2. Use HTTP mode: Run zylos config set protocol http (automatically updates Caddyfile and reloads Caddy)

Owner

First user to send a private message becomes the owner (primary partner). Owner bypasses DM policy and per-group/per-channel allowlist checks. However, groupPolicy: disabled blocks all group messages, including from the owner.

Owner info stored in config.json:

{
  "owner": {
    "bound": true,
    "user_id": "xxx",
    "open_id": "ou_xxx",
    "name": "Howard"
  }
}

Access Control

Permission Flow

DM and group access are controlled by independent top-level policies:

{
  "dmPolicy": "owner",        // "open" | "allowlist" | "owner"
  "dmAllowFrom": ["ou_xxx"],  // used when dmPolicy = "allowlist"
  "groupPolicy": "allowlist", // "open" | "allowlist" | "disabled"
  "groups": { ... }           // per-group config (used when groupPolicy = "allowlist")
}

Private DM (dmPolicy):

1. Owner? → always allowed
2. dmPolicy = open? → anyone can DM
3. dmPolicy = owner? → only owner can DM
4. dmPolicy = allowlist? → check dmAllowFrom list; not in list → dropped

Group message (groupPolicy):

1. groupPolicy = disabled? → all group messages dropped
2. groupPolicy = open? → respond to @mentions from any group
3. groupPolicy = allowlist? → only configured groups; unlisted groups → only owner passes, others dropped silently
4. Per-group allowFrom set? → only listed senders pass (owner always bypasses)
5. Smart group (mode: smart)? → receive all messages, no @mention needed
6. Not smart? → only @mentions are processed, other messages are logged only

Key points:

• Owner bypasses allowlist checks only; groupPolicy: disabled blocks all group messages, including from owner
• dmPolicy and groupPolicy are fully independent — changing one never affects the other
• Group access is controlled by groupPolicy + groups config + per-group allowFrom
• No user-level whitelist for groups; use per-group allowFrom if you need to restrict specific senders

Groups Config Format

Groups are stored in a map keyed by chat_id:

{
  "groupPolicy": "allowlist",
  "groups": {
    "oc_xxx": {
      "name": "研发群",
      "mode": "mention",
      "requireMention": true,
      "allowFrom": [],
      "historyLimit": 10,
      "added_at": "2026-01-01T00:00:00Z"
    },
    "oc_zzz": {
      "name": "核心群",
      "mode": "smart",
      "requireMention": false
    }
  }
}

• mode: "mention" (respond to @mentions only) or "smart" (receive all messages)
• allowFrom: Optional list of user_id/open_id. Empty = all group members allowed. "*" = wildcard.
• historyLimit: Optional per-group context message limit (overrides message.context_messages)

Markdown Card

Outgoing messages can be rendered as interactive cards with proper markdown formatting (code blocks, tables, headers, etc.):

{
  "message": {
    "useMarkdownCard": true
  }
}

On by default. Note mobile display limitation: cards cannot be long-pressed to copy on mobile. Can be disabled via node admin.js set-markdown-card off. When enabled (cards cannot be long-pressed to copy on mobile). When enabled, messages containing markdown are auto-detected and sent as cards; plain text messages are sent normally. Falls back to plain text if card sending fails.

Group Context

When responding to @mentions in groups, the bot includes recent message context so Claude understands the conversation. Context is retrieved from logged messages since the last response.

Configuration in config.json:

{
  "message": {
    "context_messages": 10
  }
}

Message logs are stored in ~/zylos/components/lark/logs/<chat_id>.log.

Service Management

pm2 status zylos-lark
pm2 logs zylos-lark
pm2 restart zylos-lark