ClawdBot 插件开发：为 Telegram 机器人添加新快捷命令的实践

这段代码做了四件事： ① 定义插件类，继承 Plugin 基类； ② 重写 describe() 告诉系统这个命令叫什么、怎么用； ③ 重写 execute() 实现核心逻辑，自动处理消息来源、截断、提示词构造、模型调用； ④ 导出 plugin 实例，作为 ClawdBot 的加载入口。

注意：ctx.llm.chat(...) 是 ClawdBot 提供的统一模型调用接口，你无需关心模型地址、API Key、重试逻辑——它已与你的 clawdbot.json 中配置的 vLLM 服务打通。

3.3 编写插件配置（plugin.yaml）

在 ~/.clawdbot/plugins/summary/plugin.yaml 中声明元信息：

# ~/.clawdbot/plugins/summary/plugin.yaml
name: summary
version: "0.1.0"
author: "your-name"
description: "为长文本生成简洁摘要"
enabled: true
commands:
  - name: summary
    aliases: ["sum", "摘要"]
    description: "生成文本摘要"
    scope: ["private", "group", "supergroup"]

• scope 指定该命令可在哪些场景使用（私聊、普通群、超级群）；
• aliases 支持多个别名，用户输 /sum 或 /摘要 同样生效；
• enabled: true 表示默认启用。

3.4 加载并验证插件

保存文件后，在终端执行：

clawdbot plugins reload

你会看到类似输出：

🦞 Clawdbot 2026.1.24-3 — Reloading plugins...
Loaded plugin 'summary' (0.1.0) with commands: [/summary, /sum, /摘要]

接着，打开 Telegram，随便发一段话（比如产品需求文档节选），然后回复这条消息输入 /summary，几秒后就会收到结构清晰的摘要结果。

成功标志：命令出现在 /help 列表中，且能正常返回结果； ❌ 常见问题：plugin.yaml 格式错误、main.py 语法错误、模型未就绪（可用 clawdbot models list 确认）。

4. 进阶技巧：让插件更智能、更健壮

写完基础功能只是开始。真正好用的插件，往往藏在细节里。

4.1 支持多模态输入：不只是文字

ClawdBot 的 CommandContext 对象还提供了 ctx.get_media_file() 方法，可获取用户发送的图片、语音、PDF 等附件。我们可以轻松扩展 /summary 插件，让它支持'上传 PDF 自动提取摘要'。

只需在 execute() 开头加几行：

# 检查是否上传了文件
media = ctx.get_media_file()
if media and media.mime_type in ["application/pdf", "image/png", "image/jpeg"]:
    # 调用内置 OCR 或 PDF 解析服务（ClawdBot 已集成 PaddleOCR）
    text = await ctx.ocr.extract_text(media.path)
    if not text.strip():
        return CommandResult.error("未能从文件中识别出有效文字")
    # 后续仍走原有摘要逻辑...

这样，用户发一张会议白板照片，或拖入一份 PRD PDF，都能一键生成摘要——而你几乎不用新增模型代码，全靠 ClawdBot 已有的多模态能力复用。

4.2 添加缓存与限流：保护你的本地模型

本地 vLLM 资源有限，不能任由用户高频刷 /summary。ClawdBot 提供了开箱即用的限流器：

# 在 main.py 中添加
from clawdbot.utils.rate_limit import RateLimiter

class SummaryPlugin(Plugin):
    def __init__(self, config: Dict[str, Any]):
        super().__init__(config)
        # 每用户每 60 秒最多调用 3 次
        self.limiter = RateLimiter("summary_per_user", window=60, limit=3)

    async def execute(self, ctx: CommandContext) -> CommandResult:
        # 检查限流
        if not await self.limiter.allow(ctx.user_id):
            return CommandResult.error("操作太频繁，请 60 秒后再试")
        # ...原有逻辑

同样，摘要结果也可缓存（基于文本哈希），避免重复计算：

from clawdbot.utils.cache import get_cache
import hashlib

cache = get_cache("summary")
cache_key = hashlib.md5(text.encode()).hexdigest()
cached = await cache.get(cache_key)
if cached:
    return CommandResult.success(cached)

# 执行模型推理...
await cache.set(cache_key, summary_text, expire=3600)  # 缓存 1 小时

4.3 与 MoltBot 无缝联动：复用现有能力

MoltBot 的 /wiki 和 /weather 插件，其实就放在 ~/.clawdbot/plugins/wiki/ 和 ~/.clawdbot/plugins/weather/ 下。你可以直接参考它们的写法，甚至 import 其工具函数：

# 在 summary/main.py 中复用天气插件的地理解析逻辑
try:
    from weather.utils import parse_location
    location = parse_location("上海浦东")
except ImportError:
    location = None

这种'插件即模块'的设计，让整个生态形成正向循环：你写的插件，别人也能拿来二次开发；别人写的插件，你也能快速集成——这才是开源协作的真实力量。

5. 调试与发布：从本地实验到团队共享

开发完成不等于结束。一个成熟的插件，还需要经过调试、文档、打包三步。

5.1 使用 Web 控制台实时调试

ClawdBot 的 Web UI（通过 clawdbot dashboard 访问）不仅是个配置面板，更是强大的调试中心：

• 进入 Plugins → Summary 页面，可手动触发 execute 并传入模拟参数；
• 查看 Logs → Plugin Logs，筛选 summary 关键字，实时观察报错堆栈；
• 在 Models → Test Chat 中，直接测试你用的提示词效果，快速迭代 prompt 工程。

比起反复重启服务、切窗口、发消息验证，这种方式效率提升 5 倍以上。

5.2 编写用户友好的帮助文档

在 ~/.clawdbot/plugins/summary/README.md 中写一段简明说明：

# Summary 插件
为长文本、PDF、图片生成精准摘要。

## 使用方式
- 私聊中直接发送：`/summary 这是一段很长的需求描述...`
- 在群聊中，先发送文字/图片，再回复 `/summary`
- 支持中文，推荐输入 100–800 字内容

## 配置项（可选）
在 `plugin.yaml` 中添加：
```yaml
config:
  model: "vllm/Qwen3-4B-Instruct-2507"
  max_length: 500

ClawdBot 会自动将此 README 渲染到 Web UI 的插件详情页，用户点开就能看懂怎么用。

#### 5.3 打包为独立镜像（可选）

如果你希望把 `summary` 插件和 MoltBot 一起打包成 Docker 镜像分发，只需在 `Dockerfile` 中加入：

```dockerfile
COPY ~/.clawdbot/plugins/summary /app/plugins/summary
RUN chmod -R 755 /app/plugins/summary

然后构建镜像，其他人 docker run -p 7860:7860 moltbot-summary 即可获得预装摘要功能的 Telegram 翻译机器人——无需任何额外配置。

6. 总结：插件开发的本质，是能力的乐高化

ClawdBot 的插件开发，不是教你写更多代码，而是教你用更少的代码，组合出更强的能力。它把模型调用、消息路由、权限控制、限流缓存、日志监控这些'脏活累活'全部封装好，只留下最干净的接口让你发挥创意。

你不需要成为 vLLM 专家，也能调用 Qwen3； 你不需要懂 Telegram Bot API，也能让命令在群聊中生效； 你不需要研究 OCR 原理，也能让图片变文字再变摘要。

这正是现代 AI 工程的进化方向：从'造轮子'转向'搭积木'，从'写代码'转向'编排能力'。

当你写下第一个 plugin = SummaryPlugin({})，你就已经站在了 AI 应用开发的快车道上——接下来，是给你的机器人加一个 /todo 待办管理？还是 /code 代码解释器？又或者 /translate 图片内文字翻译？选择权，完全在你手中。