npm package: @mike_5010/claude-bot
Description: 飞书 Claude Code 机器人 — 基于飞书开放平台 WebSocket 长轮询，集成 Claude Code CLI 的智能对话机器人。
Latest version: 0.3.0

# Claude Bot

飞书 Claude Code 机器人 — 基于飞书开放平台 WebSocket 长轮询，集成 Claude Code CLI 的智能对话机器人。

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## ✨ 功能特性

- **智能对话** - 支持多轮会话，自动续期与恢复
- **文件收发** - 用户上传文件自动下载分析，机器人可发送文件附件
- **定时任务** - 支持 Cron 表达式定时任务，到期自动执行并推送结果
- **实时进度** - Claude 执行期间实时推送工具调用进度到飞书
- **会话持久化** - SQLite 持久化会话和定时任务数据

## 🏗️ 架构概览

```
用户（飞书）
    │  WebSocket 长轮询
    ▼
FeishuClient ──→ index.ts ──→ MessageHandler ──→ Claude CLI
                              │
                              └── CronScheduler（定时任务）
                              │
                              └── Repository（SQLite）
```

完整架构文档见 [docs/architecture.md](docs/architecture.md)

## 🚀 快速开始

### 1. 环境要求

| 依赖 | 版本要求 | 说明 |
|------|----------|------|
| **Node.js** | `>= 20.0.0 < 24.0.0` | 必需。v24 与 better-sqlite3 不兼容 |
| **Claude Code CLI** | `>= 2.1.81` | 必需。需支持 `--output-format=stream-json` |

#### Claude Code CLI 安装

```bash
npm install -g @anthropic-ai/claude-code
```

验证安装：
```bash
claude --version
# 应显示 >= 2.1.81
```

**版本兼容性说明：**
- **>= 2.1.81**: 必需版本。此版本开始 `--print` + `--output-format=stream-json` 需要同时提供 `--verbose` 参数
- **< 2.1.81**: 可能工作，但未经过完整测试

### 2. 安装

```bash
# 全局安装（推荐）
npm install -g @mike_5010/claude-bot

# 初始化配置
claude-bot init

# 启动机器人
claude-bot start
```

#### 从源码安装

```bash
# 克隆仓库
git clone https://github.com/myk5010/claude-bot.git
cd claude-bot

# 安装依赖
npm install

# 编译
npm run build

# 本地链接测试
npm link
claude-bot init
```

### 3. 飞书应用配置

1. 登录 [飞书开放平台](https://open.feishu.cn/app)，创建企业自建应用
2. **权限管理** - 开通以下权限：
   - `im:chat:readonly` - 获取群组信息
   - `im:message.group_msg` - 接收群消息
   - `im:message.p2p_msg` - 接收单聊消息
   - `im:message:send` - 发送消息
   - `im:resource:download` - 下载资源
   - `im:resource:upload` - 上传资源
3. **事件订阅** - 开启 WebSocket 长轮询，订阅 `im.message.receive_v1`
4. **版本管理** - 创建新版本并发布

### 4. 初始化配置

```bash
claude-bot init
```

按提示输入：
- 飞书 App ID
- 飞书 App Secret
- Claude CLI 路径（默认 `claude`）
- 工作目录（默认 `~/.claude-bot/workspace`）

配置文件保存在 `~/.claude-bot/config.json`

### 5. 启动

```bash
# 启动机器人
claude-bot start
```

## 📖 使用指南

### 基础对话

直接在飞书发送消息即可与 Claude 对话，支持单聊和群聊（需 @机器人）。

### 发送文件

对机器人说：
> "把 /path/to/file.txt 发给我"

机器人会通过 `<send-file>` 标签自动发送文件附件。

### 接收文件

直接发送文件给机器人，文件会自动下载到临时目录，Claude 会读取并分析内容。

### 定时任务

- **创建**："每天早上9点提醒我吃维生素"
- **查看**："查看我的定时任务"
- **取消**："取消定时任务 3" 或 "取消所有定时任务"

## ⚠️ 常见问题

### better-sqlite3 编译失败

**原因**：Node.js v24 与 better-sqlite3 存在兼容性问题

**解决**：降级到 Node.js v22 LTS
```bash
nvm install 22
nvm use 22
```

### Claude CLI 无响应或报错

**检查 Claude Code 版本**：
```bash
claude --version
# 必须 >= 2.1.81
```

**检查 Claude CLI 路径**：
```bash
which claude
# 确保路径正确，或在 init 时指定完整路径
```

**检查登录状态**：
```bash
claude auth logout
claude auth login
```

## 🛠️ 开发

```bash
# 运行测试
npm test

# 测试监听模式
npm run test:watch
```

## 📂 项目结构

```
├── src/
│   ├── index.ts           # 启动入口
│   ├── cli.ts             # CLI 命令定义
│   ├── config.ts          # 配置管理
│   ├── claude/
│   │   └── runner.ts      # Claude CLI 封装
│   ├── feishu/
│   │   └── client.ts      # 飞书 SDK 封装
│   ├── handlers/
│   │   └── message.ts     # 消息处理逻辑
│   ├── cron/
│   │   └── scheduler.ts   # 定时任务调度
│   ├── db/
│   │   ├── schema.ts      # 数据库表结构
│   │   └── repository.ts  # 数据访问层
│   └── types.ts           # TypeScript 类型定义
├── docs/
│   └── architecture.md    # 架构文档
└── data/                  # SQLite 数据目录
```

## 🔧 技术栈

| 技术 | 用途 |
|------|------|
| TypeScript ESM | 主语言 |
| `@larksuiteoapi/node-sdk` | 飞书 SDK |
| `better-sqlite3` | SQLite 同步 ORM |
| `node-cron` | 定时任务调度 |
| Claude Code CLI | AI 执行引擎 |

## 📝 License

MIT License © 2024