197 lines
7.3 KiB
Markdown
197 lines
7.3 KiB
Markdown
# PhoneWork
|
|
|
|
Feishu bot that lets users control Claude Code CLI from their phone.
|
|
|
|
## Architecture
|
|
|
|
```
|
|
┌─────────────┐ WebSocket ┌──────────────┐ LangChain ┌─────────────┐
|
|
│ Feishu │ ◄──────────────► │ FastAPI │ ◄──────────────► │ LLM API │
|
|
│ (client) │ │ (server) │ │ (ZhipuAI) │
|
|
└─────────────┘ └──────────────┘ └─────────────┘
|
|
│
|
|
▼
|
|
┌─────────────┐
|
|
│ Claude Code │
|
|
│ (headless) │
|
|
└─────────────┘
|
|
```
|
|
|
|
**Components:**
|
|
|
|
| Module | Purpose |
|
|
|--------|---------|
|
|
| `main.py` | FastAPI entry point, starts WebSocket client + session manager |
|
|
| `bot/handler.py` | Receives Feishu events via long-connection WebSocket |
|
|
| `bot/feishu.py` | Sends text/file/card replies back to Feishu |
|
|
| `bot/commands.py` | Slash command handler (`/new`, `/status`, `/switch`, `/direct`, `/smart`, etc.) |
|
|
| `orchestrator/agent.py` | LangChain agent with per-user history + direct/smart mode toggle |
|
|
| `orchestrator/tools.py` | Tools: `create_conversation`, `send_to_conversation`, `list_conversations`, `close_conversation` |
|
|
| `agent/manager.py` | Session registry with persistence and idle timeout reaper |
|
|
| `agent/pty_process.py` | Runs `claude -p` headlessly, manages session continuity via `--resume` |
|
|
| `agent/audit.py` | Audit log of all interactions |
|
|
|
|
**Flow:** User message → Feishu WebSocket → Handler → (passthrough or LLM) → Session Manager → `claude -p` → Response back to Feishu
|
|
|
|
---
|
|
|
|
## Feishu App Setup
|
|
|
|
### 1. Create App
|
|
|
|
Go to [Feishu Open Platform](https://open.feishu.cn/app) → **Create App** → **Custom App**.
|
|
|
|
Record the **App ID** and **App Secret** from the Credentials page.
|
|
|
|
### 2. Enable Bot Capability
|
|
|
|
**App Features** → **Bot** → Enable.
|
|
|
|
### 3. Subscribe to Events (Long-connection mode)
|
|
|
|
**Event Subscriptions** → **Request URL** tab:
|
|
|
|
- Switch to **"Use long connection to receive events"** (长连接接收事件)
|
|
- No public URL required
|
|
|
|
Add event subscription:
|
|
|
|
| Event | Event Type |
|
|
|-------|-----------|
|
|
| Receive messages | `im.message.receive_v1` |
|
|
|
|
### 4. Required Permissions (API Scopes)
|
|
|
|
Go to **Permissions & Scopes** and add the following:
|
|
|
|
| Permission | API Scope | Used For |
|
|
|------------|-----------|----------|
|
|
| Read private messages sent to the bot | `im:message` (read) | Receiving user messages via WebSocket |
|
|
| Send messages | `im:message:send_as_bot` | Sending text replies |
|
|
| Upload files | `im:resource` | Uploading files before sending |
|
|
| Send messages in private chats | `im:message` (write) | Sending file messages |
|
|
|
|
Minimal scope list to request:
|
|
|
|
```
|
|
im:message
|
|
im:message:send_as_bot
|
|
im:resource
|
|
```
|
|
|
|
> **Note:** `im:resource` covers both file upload (`im.v1.file.create`) and sending
|
|
> file-type messages. Without it, `send_file()` will fail with a permission error.
|
|
|
|
### 5. Publish App
|
|
|
|
After adding all permissions:
|
|
|
|
1. **Version Management** → Create a new version → Submit for review (or self-publish if in the same org)
|
|
2. Install the app to your workspace
|
|
|
|
---
|
|
|
|
## Configuration
|
|
|
|
Copy and fill in credentials:
|
|
|
|
```bash
|
|
cp keyring.example.yaml keyring.yaml
|
|
```
|
|
|
|
`keyring.yaml` fields:
|
|
|
|
```yaml
|
|
FEISHU_APP_ID: cli_xxxxxxxxxxxxxxxx
|
|
FEISHU_APP_SECRET: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
|
|
|
|
OPENAI_BASE_URL: https://open.bigmodel.cn/api/paas/v4/
|
|
OPENAI_API_KEY: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
|
|
OPENAI_MODEL: glm-4.7
|
|
|
|
# Root directory for all project sessions (absolute path)
|
|
WORKING_DIR: C:/Users/yourname/projects
|
|
|
|
# Allowlist of Feishu open_ids that may use the bot.
|
|
# Leave empty to allow all users.
|
|
ALLOWED_OPEN_IDS:
|
|
- ou_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
|
|
```
|
|
|
|
---
|
|
|
|
## Installation & Run
|
|
|
|
**Requirements:** Python 3.11+, [Claude Code CLI](https://claude.ai/code) installed and authenticated.
|
|
|
|
```bash
|
|
python -m venv .venv
|
|
source .venv/Scripts/activate # Windows
|
|
# source .venv/bin/activate # Linux/macOS
|
|
|
|
pip install -r requirements.txt
|
|
python main.py
|
|
```
|
|
|
|
Server listens on `http://0.0.0.0:8000`.
|
|
|
|
Health check: `GET /health`
|
|
Claude smoke test: `GET /health/claude`
|
|
Active sessions: `GET /sessions`
|
|
|
|
---
|
|
|
|
## Bot Commands
|
|
|
|
| Command | Description |
|
|
|---------|-------------|
|
|
| `/new <dir> [msg]` | Create a new Claude Code session in `<dir>` |
|
|
| `/new <dir> [msg] --timeout N` | Create with custom CC timeout (seconds) |
|
|
| `/new <dir> [msg] --idle N` | Create with custom idle timeout (seconds) |
|
|
| `/status` | Show your sessions and current mode |
|
|
| `/switch <n>` | Switch active session to number `<n>` from `/status` |
|
|
| `/close [n]` | Close active session (or session `<n>`) |
|
|
| `/direct` | Direct mode: messages go straight to Claude Code (no LLM overhead) |
|
|
| `/smart` | Smart mode: messages go through LLM for intelligent routing (default) |
|
|
| `/help` | Show command reference |
|
|
|
|
### Message Routing Modes
|
|
|
|
**Smart mode (default):** Messages are analyzed by the LLM, which decides whether to create a new session, send to an existing one, or ask for clarification. Useful when you want the bot to understand natural language requests.
|
|
|
|
**Direct mode:** Messages go straight to the active Claude Code session, bypassing the LLM. Faster and more predictable, but requires an active session. Use `/direct` to enable.
|
|
|
|
### Claude Code Commands
|
|
|
|
Claude Code slash commands (like `/help`, `/clear`, `/compact`, `/cost`) are passed through to Claude Code when you have an active session. Bot commands (`/new`, `/status`, `/switch`, etc.) are handled by the bot first.
|
|
|
|
---
|
|
|
|
## Features
|
|
|
|
### Core Reliability
|
|
|
|
- **Message splitting** - Long responses automatically split into multiple messages instead of getting cut off
|
|
- **Concurrent handling** - Multiple users can message the bot simultaneously without conflicts
|
|
- **Session persistence** - Active sessions survive server restarts (saved to disk)
|
|
- **Direct mode** - Messages go straight to Claude Code, skipping the LLM for faster responses
|
|
|
|
### Better Interaction
|
|
|
|
- **Slash commands** - Direct control via `/new`, `/status`, `/switch`, `/close`, `/direct`, `/smart`
|
|
- **Multi-session switching** - Multiple projects open simultaneously, switch between them
|
|
- **Interactive cards** - Session status displayed in Feishu message cards
|
|
|
|
### Operational Quality
|
|
|
|
- **Health checks** - `/health` endpoint shows WebSocket status and can test Claude Code connectivity
|
|
- **Auto-reconnection** - WebSocket automatically reconnects if the connection drops
|
|
- **Configurable timeouts** - Each session can have custom idle and execution timeout settings
|
|
- **Audit logging** - All conversations logged to files for debugging and accountability
|
|
|
|
### Security
|
|
|
|
- **User allowlist** - Configure which Feishu users are allowed to use the bot
|
|
- **Session isolation** - Each user can only see and access their own sessions
|
|
- **Path sandboxing** - Sessions can only run inside the allowed working directory, blocking path traversal attacks
|