| 1 | # Feishu / Lark Bridge |
| 2 | |
| 3 | This bridge lets a Feishu or Lark chat control a local `codewhale serve --http` |
| 4 | runtime from a phone. It uses the official Lark/Feishu Node SDK long-connection |
| 5 | mode, so the first version does not need a public webhook URL. |
| 6 | |
| 7 | Security model: |
| 8 | |
| 9 | - `codewhale serve --http` stays bound to `127.0.0.1`. |
| 10 | - `/v1/*` runtime calls use `CODEWHALE_RUNTIME_TOKEN`. |
| 11 | - Feishu/Lark chats must be allowlisted in `CODEWHALE_CHAT_ALLOWLIST` unless |
| 12 | `CODEWHALE_ALLOW_UNLISTED=true` |
| 13 | is set for first pairing. |
| 14 | - Direct messages are the intended MVP control surface. Group chat control is |
| 15 | disabled unless `FEISHU_ALLOW_GROUPS=true`. |
| 16 | - Tool approvals are text commands: `/allow <approval_id>` or `/deny <approval_id>`. |
| 17 | - Feishu/Lark only sees the prompts, status, thread summaries, and approval |
| 18 | messages the bridge sends. The workspace, shell, and runtime HTTP listener |
| 19 | stay local behind the Codewhale runtime token. |
| 20 | |
| 21 | ## Setup |
| 22 | |
| 23 | ```bash |
| 24 | cd /opt/codewhale/feishu-bridge |
| 25 | npm install --omit=dev |
| 26 | cp .env.example /etc/codewhale/feishu-bridge.env |
| 27 | sudoedit /etc/codewhale/feishu-bridge.env |
| 28 | node src/index.mjs |
| 29 | ``` |
| 30 | |
| 31 | Validate the env files before starting the service: |
| 32 | |
| 33 | ```bash |
| 34 | npm run validate:config -- \ |
| 35 | --env /etc/codewhale/feishu-bridge.env \ |
| 36 | --runtime-env /etc/codewhale/runtime.env \ |
| 37 | --workspace-root /opt/whalebro \ |
| 38 | --check-filesystem |
| 39 | ``` |
| 40 | |
| 41 | For first pairing, temporarily set `CODEWHALE_ALLOW_UNLISTED=true`, send the |
| 42 | bot `/status`, copy the returned `chat_id`, `open_id`, or `union_id` into |
| 43 | `CODEWHALE_CHAT_ALLOWLIST`, then turn `CODEWHALE_ALLOW_UNLISTED=false`. |
| 44 | |
| 45 | For a Tencent Lighthouse deployment, use: |
| 46 | |
| 47 | ```bash |
| 48 | sudo systemctl enable --now codewhale-runtime codewhale-feishu-bridge |
| 49 | sudo journalctl -u codewhale-feishu-bridge -f |
| 50 | ``` |
| 51 | |
| 52 | ## Commands |
| 53 | |
| 54 | - `/status` |
| 55 | - `/threads` |
| 56 | - `/new` |
| 57 | - `/resume <thread_id>` |
| 58 | - `/model <name|default>` |
| 59 | - `/interrupt` |
| 60 | - `/compact` |
| 61 | - `/allow <approval_id> [remember]` |
| 62 | - `/deny <approval_id>` |
| 63 | |
| 64 | Anything else is sent as a prompt. If group control is explicitly enabled, |
| 65 | messages should start with the Codewhale prefix `/cw`, for example: |
| 66 | |
| 67 | ```text |
| 68 | /cw check git status and tell me what is dirty |
| 69 | ``` |
| 70 |