# 嗑唠的宝子 (Clawdboz) - 飞书 Bot

[![Version](https://img.shields.io/badge/version-2.6.6-blue.svg)](#)
[![Python](https://img.shields.io/badge/python-3.9+-green.svg)](https://www.python.org/)
[![License](https://img.shields.io/badge/license-MIT-yellow.svg)](#)

基于 Kimi Code CLI 的智能飞书机器人，OpenClaw 的平替，更适合代码任务，飞书丝滑适配，交互体验优化得很好。

## ✨ 核心亮点

- 🚀 **开箱即用**：`pip install` 后三行代码即可运行
- 🎯 **代码友好**：原生支持 Kimi Code CLI，代码编辑、文件操作、终端命令样样精通
- 💬 **飞书适配**：自动获取群聊上下文，流式卡片输出，体验丝滑

## 📺 演示

<p float="left">
  <img src="https://raw.githubusercontent.com/Dr-Lv/clawdboz/main/clawdboz_demo.gif" width="48%" alt="Bot 对话演示" />
  <img src="https://raw.githubusercontent.com/Dr-Lv/clawdboz/main/clawdboz_demo2.gif" width="48%" alt="代码执行演示" />
</p>

## 功能特性

| 特性 | 说明 |
|------|------|
| 🤖 **AI 对话** | 基于 Kimi Code CLI 的智能对话 |
| 📝 **流式回复** | 实时显示思考过程，Markdown 卡片美化输出 |
| 🔧 **MCP 工具** | 支持 MCP 协议调用外部工具，内置飞书文件/消息发送 |
| 📦 **文件处理** | 自动下载图片/文件，支持发送文件到飞书 |
| 💬 **群聊适配** | 自动获取群聊历史，理解对话脉络 |
| ⏰ **定时任务** | 内置定时任务调度，支持自定义定时执行 |
| 🔍 **运维监控** | 自动监控 Bot 状态，故障自动恢复 |
| 🚀 **自动配置** | `init` 自动生成 MCP 配置和内置 Skills |

## 🚀 三行代码运行

```python
from clawdboz import Bot

bot = Bot(app_id="your-app-id", app_secret="your-app-secret")
bot.run()
```

就这么简单！

## 快速开始

### 1. 环境准备

**⚠️ 前置依赖：请先安装 [Kimi Code CLI](https://www.kimi.com/code/docs/kimi-cli/guides/getting-started.html)**

Kimi Code CLI 是嗑唠的宝子的核心依赖，提供 AI 对话能力和工具调用支持。

安装方式：
```bash
# 通过 pip 安装
pip install kimi-cli

# 或使用 uv 安装（推荐）
uv tool install --python 3.13 kimi-cli

# 验证安装
kimi --version

# 注意：首次安装需要登陆kimi code
```

### 2. 安装嗑唠的宝子

```bash
pip install clawdboz
```

或从源码安装：

```bash
git clone <repository-url>
cd larkbot
pip install -e .
```

### 3. 初始化项目（推荐）

安装完成后，强烈建议先初始化项目：

```bash
# 创建项目目录并进入
mkdir my-bot && cd my-bot

# 初始化项目（自动生成配置文件、MCP、Skills）
clawdboz init
```

`clawdboz init` 会自动完成：
- ✅ 检测 Kimi CLI 安装和登录状态
- ✅ 创建 `config.json`，自动填入 Python 路径
- ✅ 创建 `.kimi/mcp.json`，配置飞书 MCP 工具
- ✅ 复制内置 Skills（scheduler、local-memory、find-skills）
- ✅ 创建 `bot_manager.sh` 管理脚本
- ✅ 创建 `bot0.py` 启动脚本
- ✅ 创建 `.bots.md` Agent 指令文件

### 4. 启动 Bot

#### 方式一：三行代码（快速体验）

```python
from clawdboz import Bot

bot = Bot(app_id="your-app-id", app_secret="your-app-secret")
bot.run()
```

#### 方式二：使用 bot_manager.sh（推荐生产使用）

**1. 初始化项目**

```bash
# 创建项目目录并进入
mkdir my-bot && cd my-bot

# 初始化项目（自动生成配置文件、MCP、Skills）
clawdboz init
```

`clawdboz init` 会自动完成：
- ✅ 检测 Kimi CLI 安装和登录状态
- ✅ 创建 `config.json`，自动填入 Python 路径
- ✅ 创建 `.kimi/mcp.json`，配置飞书 MCP 工具
- ✅ 复制内置 Skills（scheduler、local-memory、find-skills）
- ✅ 创建 `bot_manager.sh` 管理脚本
- ✅ 创建 `bot0.py` 启动脚本
- ✅ 创建 `.bots.md` Agent 指令文件

**2. 配置飞书凭证**

编辑生成的 `config.json`：

```json
{
  "feishu": {
    "app_id": "cli_xxxxxxxxxxxxxxxx",
    "app_secret": "xxxxxxxxxxxxxxxxxxxxxx"
  }
}
```

或使用环境变量：
```bash
export FEISHU_APP_ID="cli_xxxxxxxxxxxxxxxx"
export FEISHU_APP_SECRET="xxxxxxxxxxxxxxxxxxxxxx"
```

**3. 管理命令**

```bash
# 启动 Bot
./bot_manager.sh start

# 停止 Bot
./bot_manager.sh stop

# 重启 Bot
./bot_manager.sh restart

# 查看状态
./bot_manager.sh status

# 查看日志（最后50行）
./bot_manager.sh log 50

# 实时跟踪日志
./bot_manager.sh follow

# 运维检查
./bot_manager.sh check
```

#### 定时运维监控（推荐）

配置 crontab 定时任务，每 30 分钟自动检查 Bot 状态：

```bash
# 编辑 crontab
export EDITOR=vim && crontab -e

# 添加以下行（每 30 分钟检查一次，故障时自动通知并尝试修复）
*/30 * * * * cd /path/to/your/bot && ./bot_manager.sh check >/dev/null 2>&1
```

**check 命令功能：**
- 检查 Bot 进程状态
- 检查 WebSocket 连接
- 检查所有日志文件错误
- 检查 MCP 配置
- 检查 Skills 状态
- 检查 Python 环境
- 发现异常时自动发送飞书通知
- 自动调用 Kimi 修复（需安装 Kimi CLI）

**3. 自定义启动脚本 bot0.py**

如果需要在 `bot0.py` 中添加自定义逻辑，创建该文件：

```python
#!/usr/bin/env python3
import os
from clawdboz import Bot

# 从环境变量或 config.json 读取配置
app_id = os.environ.get('FEISHU_APP_ID', 'your-app-id')
app_secret = os.environ.get('FEISHU_APP_SECRET', 'your-app-secret')

bot = Bot(app_id=app_id, app_secret=app_secret)
bot.run()
```

管理脚本会优先使用 `bot0.py`，如果不存在则使用内置模块启动。

## 项目结构

运行 `clawdboz init` 后生成的项目结构：

```
.
├── .kimi/                      # Kimi CLI 配置目录
│   ├── mcp.json               # MCP 配置（自动生成）
│   └── skills/                # Skills 目录（自动生成）
│       ├── find-skills/
│       ├── local-memory/
│       └── scheduler/
│
├── WORKPLACE/                  # 工作目录（临时文件存放）
│   ├── user_images/           # 用户图片下载目录
│   └── user_files/            # 用户文件下载目录
│
├── logs/                       # 日志目录
│   ├── main.log
│   ├── bot_debug.log
│   └── feishu_api.log
│
├── .bots.md                    # Agent 指令文件（自动生成）
├── bot0.py                     # 启动脚本（自动生成）
├── bot_manager.sh              # 管理脚本（自动生成）
└── config.json                 # 配置文件（自动生成）
```

**源码结构**（安装包内）：

```
clawdboz/                       # 主包
├── __init__.py
├── simple_bot.py               # 简化版 Bot API
├── bot.py                      # Bot 核心类
├── cli.py                      # 命令行工具
└── .kimi/                      # 内置 Skills 模板
    └── skills/
        ├── auto-test/
        ├── find-skills/
        ├── local-memory/
        └── scheduler/

feishu_tools/                   # 飞书 MCP 工具
├── mcp_feishu_file_server.py
├── mcp_feishu_msg_server.py
└── notify_feishu.py
```

## 飞书应用配置

### 1. 创建应用

1. 前往 [飞书开放平台](https://open.feishu.cn/) 登录开发者账号
2. 点击「开发者后台」→「创建企业自建应用」
3. 填写应用名称和描述，点击「创建」
4. 进入应用详情页，获取 **App ID** 和 **App Secret**

### 2. 配置权限

**需要的权限**:

| 权限类型 | 权限名称 | 用途 |
|---------|---------|------|
| API 权限 | `im:message:send` | 发送消息 |
| API 权限 | `im:message:send_as_bot` | 发送消息卡片 |
| API 权限 | `im:message:update` | 更新消息卡片 |
| API 权限 | `im:message.resource` | 获取图片、文件 |
| API 权限 | `im:chat:readonly` | 获取聊天记录 |
| API 权限 | `im:file:create` | 上传文件 |
| API 权限 | `im:file:send` | 发送文件消息 |
| API 权限 | `im:image:create` | 上传图片 |
| 事件订阅 | `im.message.receive_v1` | 接收消息 |
| 机器人能力 | `receive_message` | 接收消息 |
| 机器人能力 | `send_message` | 发送消息 |

1. 在应用详情页，点击「权限管理」→ 申请上述 API 权限
    备注：可通过feishu_permissions.json批量配置权限
2. 点击「事件与回调」→ 选择长连接方式，勾选所有事件和回调选项
    备注：初次配置长连接，需要先启动bot进行连接，才能在飞书后台配置成功
3. 点击「机器人」→ 开启「接收消息」和「发送消息」能力

### 3. 发布应用

1. 点击「版本管理与发布」→「创建版本」
2. 填写版本号（如 1.0.0）
3. 选择「可用性状态」为「所有员工」
4. 点击「保存」并「申请发布」

### 4. 添加机器人到聊天

- **单聊**：搜索机器人名称，进入对话
- **群聊**：群设置 →「群机器人」→ 添加机器人 → 在群聊中 @机器人

## 与 Bot 交互

- **单聊**：直接发送消息给 Bot
- **群聊**：在群聊中 @Bot 后发送消息
- **文件/图片**：Bot 自动下载到工作目录并分析
- **发送文件**：使用 MCP 工具发送本地文件到飞书

## 打包发布

```bash
# 清理并重新打包
rm -rf build/ dist/ *.egg-info
python3 -m build

# 生成的文件
# dist/clawdboz-2.2.0-py3-none-any.whl
# dist/clawdboz-2.2.0.tar.gz
```

## 许可证

MIT License
