Metadata-Version: 2.4
Name: feishu-cc
Version: 0.1.0
Summary: Feishu (Lark) bot messaging and remote control for Claude Code and terminals
Author-email: Step Tian <step@example.com>
License: MIT
Project-URL: Homepage, https://github.com/steptian/feishu-notify
Project-URL: Documentation, https://github.com/steptian/feishu-notify#readme
Project-URL: Repository, https://github.com/steptian/feishu-notify.git
Project-URL: Issues, https://github.com/steptian/feishu-notify/issues
Keywords: feishu,lark,claude-code,notification,remote-control,bot
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Communications :: Chat
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Terminals
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: lark-oapi>=1.4.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: sphinx>=7.0; extra == "dev"
Requires-Dist: sphinx-rtd-theme>=2.0; extra == "dev"

# feishu-notify

[![PyPI version](https://badge.fury.io/py/feishu-notify.svg)](https://badge.fury.io/py/feishu-notify)
[![Python](https://img.shields.io/pypi/pyversions/feishu-notify.svg)](https://pypi.org/project/feishu-notify/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

飞书 (Lark) 机器人消息推送与远程控制。支持从飞书远程操控 Claude Code 或其他终端。

**English** | [中文](#中文文档)

---

## Features

- 🔔 **Instant Push** - Auto-notify on task completion
- 🎮 **Remote Control** - Send commands from Feishu to terminal
- 🪟 **Multi-window** - On-duty mode for window management
- 📱 **Mobile Friendly** - Optimized output for mobile reading
- 🎴 **Interactive Cards** - Window list with card display
- 🌐 **i18n** - Chinese and English support

## Installation

```bash
# From PyPI (recommended)
pip install feishu-notify

# From source
git clone https://github.com/steptian/feishu-notify.git
cd feishu-notify
pip install -e .
```

## Quick Start

### 1. Configure Feishu App

1. Visit [Feishu Open Platform](https://open.feishu.cn/app) to create an app
2. Get **App ID** and **App Secret**
3. Configure permissions: `im:message`, `im:message:send_as_bot`
4. Publish the app and add to a group chat

### 2. Set Environment Variables

```bash
# Create config directory
mkdir -p ~/.config/feishu-notify

# Create .env file
cat > ~/.config/feishu-notify/.env << 'EOF'
FEISHU_APP_ID=cli_xxxxxxxxxx
FEISHU_APP_SECRET=xxxxxxxxxxxxxxxxxx
EOF

chmod 600 ~/.config/feishu-notify/.env
```

### 3. Start Long Polling Client

```bash
feishu-notify start
```

Or run directly:

```bash
python -m feishu_notify.client
```

### 4. Configure Claude Code Hook (Optional but Recommended)

Edit `~/.claude/settings.json`:

```json
{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "feishu-notify hook"
          }
        ]
      }
    ]
  }
}
```

## Usage

### From Feishu

Send messages directly (no prefix needed):

```
帮我写一个冒泡排序
今天上海天气怎么样？
```

Window management:

```
/windows          # View active windows (interactive card)
/switch 1         # Switch to window 1
/on-duty          # View current on-duty window
```

### In Claude Code

```bash
feishu-notify send "Title" "Content"    # Send custom notification
feishu-notify send "Task done"          # Send simple notification
feishu-notify test                       # Test push
feishu-notify config --check             # Validate configuration
```

### Command Line

```bash
feishu-notify send "Title" "Content"    # Send notification
feishu-notify test                       # Test
feishu-notify config --check             # Check config
```

### As a Python Library

```python
from feishu_notify import send_to_feishu, Config

# Load config from environment
config = Config.from_env()
config.validate()

# Send message
send_to_feishu("Hello from Python!", config=config)
```

## Architecture

```
┌─────────────┐                    ┌─────────────┐
│  Feishu App │◄────WebSocket────►│   Client    │
└─────────────┘                    └──────┬──────┘
                                          │
                                          ▼
                                   ┌─────────────┐
                                   │ tmux session│
                                   │(Claude Code)│
                                   └─────────────┘
                                          ▲
                                          │
                                   ┌──────┴──────┐
                                   │  Stop Hook  │
                                   │ (auto-reply)│
                                   └─────────────┘
```

## File Structure

```
feishu-notify/
├── src/feishu_notify/
│   ├── __init__.py
│   ├── cli.py           # CLI entry point
│   ├── client.py        # WebSocket client
│   ├── config.py        # Configuration management
│   ├── sender.py        # Message sending
│   └── i18n.py          # Internationalization
├── tests/
│   ├── test_config.py
│   └── test_sender.py
├── skills/              # Claude Code Skill
│   └── feishu-notify/
│       └── SKILL.md
├── pyproject.toml
└── README.md
```

## Configuration

### Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `FEISHU_APP_ID` | ✅ | Feishu App ID |
| `FEISHU_APP_SECRET` | ✅ | Feishu App Secret |
| `FEISHU_WEBHOOK_URL` | ❌ | Group bot webhook (for simple push) |
| `FEISHU_NOTIFY_LANG` | ❌ | Language: `zh` (default) or `en` |

### Multi-window Scenario

When you have multiple Claude Code windows, use **on-duty mode**:

1. In Claude Code terminal: `feishu-notify on-duty`
2. Messages from Feishu will only go to the on-duty window
3. Switch windows: Send `/windows` in Feishu → Click to switch

## Troubleshooting

### Message Send Failed

1. Check `.env` configuration is correct
2. Check if Feishu app is published
3. Check if app is added to group chat

### Reply Not Sent to Feishu

1. Confirm Stop Hook is configured
2. Confirm long polling client is running
3. Check logs: `tail -f /tmp/feishu-longpoll.log`

## Development

```bash
# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run tests with coverage
pytest --cov=feishu_notify

# Type check
pyright src/
```

## License

MIT

---

## 中文文档

飞书机器人消息推送与远程控制 Skill，支持从飞书远程操控 Claude Code。

### 特性

- 🔔 **即时推送** - 任务完成自动通知到飞书
- 🎮 **远程控制** - 从飞书发送命令到 Claude Code
- 🪟 **多窗口管理** - 值班模式，指定窗口接收消息
- 📱 **手机友好** - 输出优化，适合手机阅读
- 🎴 **交互卡片** - 窗口列表卡片展示

### 安装

```bash
pip install feishu-notify
```

### 快速开始

1. 配置飞书应用并获取 App ID 和 App Secret
2. 创建 `~/.config/feishu-notify/.env` 文件
3. 运行 `feishu-notify start` 启动长连接客户端

### 使用方式

从飞书发消息（无需前缀）：
```
帮我写一个冒泡排序
今天上海天气怎么样？
```

窗口管理：
```
/windows          # 查看活跃窗口
/switch 1         # 切换到窗口 1
/on-duty          # 查看当前值班窗口
```

### 故障排除

**消息发送失败**
1. 检查 `.env` 配置是否正确
2. 检查飞书应用是否已发布
3. 检查应用是否已添加到群聊

**回复没有发送到飞书**
1. 确认 Stop Hook 已配置
2. 确认长连接客户端正在运行
3. 检查日志：`tail -f /tmp/feishu-longpoll.log`

### 许可证

MIT
