# create-bot-function

> Create a new Telegram Bot function module. Use when user asks to add a new bot command or feature.

- Author: jeremieyuk
- Repository: jeremieyuk/claudecat
- Version: 20260127161802
- Stars: 2
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/jeremieyuk/claudecat
- Web: https://mule.run/skillshub/@@jeremieyuk/claudecat~create-bot-function:20260127161802

---

---
name: create-bot-function
description: Create a new Telegram Bot function module. Use when user asks to add a new bot command or feature.
---

# 创建 Bot Function 模块

当用户要求创建新的 Bot 功能时，**严格按照以下步骤操作**。

## ⚠️ 重要：必须先安装依赖

如果 Function 需要任何外部依赖（npm 包），**必须先安装**：

```bash
cd /Users/jeremieyuk/Downloads/telegram-claude-bot
npm install <package-name>
```

## 创建流程（必须按顺序执行）

### 1. 分析需求
确定功能需要什么依赖包。

### 2. 安装依赖（如有）
```bash
npm install <package-name>
```

### 3. 创建 Function 文件
在 `src/functions/{name}.fn.ts` 创建文件。

### 4. 验证代码
运行 TypeScript 检查确保无错误：
```bash
npx tsc --noEmit src/functions/{name}.fn.ts
```

### 5. 确认热重载成功
查看 Bot 日志确认：
```
🔄 检测到 Function 变化: {name}.fn.ts
📦 Functions 热重载完成
```

## 文件位置

`src/functions/{name}.fn.ts`

## 模板

```typescript
import { FunctionDefinition, FunctionContext } from './types.js';

const myFunction: FunctionDefinition = {
  id: '{id}',
  name: '{显示名称}',
  description: '{功能描述}',
  
  trigger: {
    type: 'command',  // 'command' | 'keyword' | 'regex'
    value: '/{command}'
  },
  
  requireAuth: true,
  
  async handler(ctx: FunctionContext, args?: string): Promise<void> {
    // ctx.bot - Telegram Bot 实例
    // ctx.chatId - 聊天 ID
    // ctx.userId - 用户 ID
    
    await ctx.bot.sendMessage(ctx.chatId, '执行完成！');
  }
};

export default myFunction;
```

## 触发类型

- `command`: 斜杠命令，如 `/weather`
- `keyword`: 关键词触发
- `regex`: 正则匹配

## 可用的上下文 (ctx)

```typescript
interface FunctionContext {
  bot: TelegramBot;      // Telegram Bot 实例
  chatId: number;        // 聊天 ID
  userId: number;        // 用户 ID
  username?: string;     // 用户名
  firstName?: string;    // 名字
}
```

## 注意事项

- ❗ 文件必须以 `.fn.ts` 结尾
- ❗ 必须 `export default` 导出 FunctionDefinition 对象
- ❗ `requireAuth: true` 表示需要白名单授权
- ❗ **所有外部依赖必须先 npm install**
- ❗ **创建前必须验证代码无错误**

## 常用依赖

| 功能 | 依赖 | 安装命令 |
|------|------|----------|
| HTTP 请求 | axios | `npm install axios` |
| AI 功能 | @anthropic-ai/sdk | `npm install @anthropic-ai/sdk` |
| 文件处理 | fs-extra | `npm install fs-extra` |
| 日期处理 | dayjs | `npm install dayjs` |

## 示例：天气查询

```bash
# 1. 安装依赖（如果需要，天气示例不需要额外依赖）
# npm install axios

# 2. 创建文件
# src/functions/weather.fn.ts

# 3. 验证
npx tsc --noEmit src/functions/weather.fn.ts

# 4. 检查日志确认热重载成功
```