Skip to content

README_CN.md

Latest commit

 

History

History
622 lines (480 loc) · 20.3 KB

README_CN.md

File metadata and controls

622 lines (480 loc) · 20.3 KB
Raw

OpenClaw GitHub Trending 插件

npm version License: MIT

English | 简体中文

OpenClaw 插件，用于获取 GitHub 趋势仓库并通过 AI 生成的摘要推送到飞书或邮件。

功能特性

  • 🔥 GitHub 热榜 — 获取今日、本周或本月热榜项目
  • 🤖 AI 摘要 — 使用 OpenAI 或 Anthropic 生成智能摘要
  • 📢 多渠道推送 — 支持飞书、邮件和微信通知
  • 🔄 智能去重 — 追踪仓库历史，在 Star 大幅增长时重新推送
  • ⏰ 定时任务 — 与 OpenClaw 任务调度器集成，实现自动化更新

安装

openclaw plugins install openclaw-github-trending

⚠️ 安全提示 - 允许非捆绑插件

由于本插件属于非官方捆绑插件，安装后请在 OpenClaw 的配置文件中显式允许加载，否则网关处会出现安全警告。

  1. 打开 OpenClaw 配置文件（通常位于 ~/.openclaw/openclaw.json）。

  2. 在 plugins.allow 列表中添加本插件的 ID：

{
  "plugins": {
    "allow": [
      "openclaw-github-trending"
    ]
  }
}

此配置告诉 OpenClaw 信任并允许加载此插件。配置完成后，安全警告将消失。

快速开始

⚡ 最小配置

最低仅需配置一个飞书 Webhook URL 即可运行，插件会自动继承 OpenClaw 全局配置中的 AI 设置：

{
  "plugins": {
    "openclaw-github-trending": {
      "channels": {
        "feishu": {
          "webhook_url": "https://open.feishu.cn/open-apis/bot/v2/hook/xxx"
        }
      }
    }
  }
}

最完整配置示例：

{
  "plugins": {
    "enabled": true,
    "allow": [
      // 配置允许加载本插件，否则网关处在查看状态或者重启的时候总是会报提醒。
      "openclaw-github-trending",
    ],
    "entries": {
      "openclaw-github-trending": {
        "enabled": true,
        "config": {
          // 可选：AI 提供商，不配置会自动调用 openclaw 的全局 AI 配置。
          "ai": {
            "provider": "openai",
            "api_key": "sk-sp-xxx",
            "base_url": "https://coding.dashscope.aliyuncs.com/v1",
            "model": "kimi-k2.5"
          },
          // 可选：最大并发数，默认 5。根据你的 AI 模型情况调整，可以加速对仓库的摘要生成。
          "max_workers": 5,
          //  可选：GitHub 个人访问令牌，频繁调用可能会限制访问，配置后基本上可以避免触发 GitHub 速率限制。不建议配置，因为本身这个插件的调用频率也不高。
          "github_token": "xxx",
          // 必须：配置一个通道（飞书、邮件或微信），否则无法通知到你。
          "channels": {
            "feishu": {
              "webhook_url": "https://open.feishu.cn/open-apis/bot/v2/hook/xxx"
            },
            "email": {
              "smtp_host": "smtp.qq.com",
              "smtp_port": 587, // 建议 QQ 邮箱的话优先使用 587 端口
              "sender": "xxx@qq.com",
              "password": "xxx",
              "recipient": "yyy@qq.com"
            },
            "wechat": {
              "enabled": true,
              "receiver_id": "your-wechat-user-id@im.wechat" // 可选：微信用户 ID，不配置会尝试自动获取
            }
          },
          // 可选：开启历史记录功能，用于智能去重
          "history": {
            "enabled": true,
            "star_threshold": 100
          },
          // 可选：如果你的网络能直接访问到 GitHub，就不需要配置改代理了
          "proxy": {
            "enabled": true,
            "url": "http://127.0.0.1:7897"
          }
        }
      }
    }
  }
}

如何获取飞书 Webhook URL：

  1. 创建飞书机器人：

    • 创建群组
    • 点击群组设置 → 机器人管理
    • 点击群机器人 → "添加机器人"
    • 选择自定义机器人

  2. 配置机器人：

    • 为机器人命名（例如："GitHub 热榜"）
    • 上传头像（可选）
    • 添加描述
    • 点击"添加"

  3. 获取 Webhook URL：

    • 创建完成后，你会看到一个 webhook URL，格式如下： 
      https://open.feishu.cn/open-apis/bot/v2/hook/YOUR_WEBHOOK_ID
    • 复制此 URL 并粘贴到配置文件的 webhook_url 字段中
    • ⚠️ 安全提示： 请妥善保管此 URL！任何拥有此 URL 的人都可以向你的机器人发送消息。

  4. 测试机器人：

    • 使用 curl 发送测试消息： 
      curl -X POST https://open.feishu.cn/open-apis/bot/v2/hook/YOUR_WEBHOOK_ID \
  -H "Content-Type: application/json" \
  -d '{"msg_type":"text","content":{"text":"测试消息"}}'
    • 你应该会在飞书聊天中看到这条消息。

3. 设置定时任务或立即执行

使用注册的 gen-cron CLI 命令快速设置定时任务或立即执行。在你能使用 openclaw 命令的那个命令行中中直接执行以下命令：

# 立即执行：获取今日热榜并推送到飞书和邮箱
openclaw gen-cron now daily email,feishu

# 创建定时任务：每周三 10:00 获取本周热榜并推送到飞书
openclaw gen-cron "0 10 * * 3" weekly feishu

# 创建定时任务：每月 1 号 9:00 获取本月热榜并推送到邮箱和飞书
openclaw gen-cron "0 9 1 * *" monthly email,feishu

# 创建定时任务：每天早上 8:00 获取今日热榜并推送到邮箱
openclaw gen-cron "0 8 * * *" daily email

命令参数说明：

openclaw gen-cron <mode> <since> <channels>
参数 说明 示例
mode 执行模式：now 表示立即执行，或 Cron 表达式（格式：分 时 日 月 周） now
"0 10 * * 3"
since 热榜周期：daily（今日）、weekly（本周）、monthly（本月） daily
channels 推送渠道：email、feishu、wechat 或 email,feishu,wechat（多个渠道用逗号分隔） email,feishu,wechat

Cron 表达式格式：

  • 格式：分(0-59) 时(0-23) 日(1-31) 月(1-12) 周(0-7, 0和7都是周日)
  • 时区：使用服务器本地时间（通常为系统时间）

常用 Cron 示例：

  • "0 8 * * *" - 每天 8:00
  • "0 10 * * 3" - 每周三 10:00
  • "0 9 1 * *" - 每月 1 号 9:00

⚠️ 注意：gen-cron 命令必须在命令行中执行，不能在 OpenClaw 聊天界面中使用。

  • 命令行：直接在终端执行 openclaw gen-cron ...
  • OpenClaw 聊天：如需在聊天中执行，需要使用完整的 openclaw cron add 命令（见下方）

在 OpenClaw 聊天中设置任务

如果想在 OpenClaw 聊天界面中设置任务，使用完整的 cron add 命令：

# 在 OpenClaw 聊天中粘贴以下命令（需要先转义引号）

# 每周三 10:00 获取本周热榜并推送到飞书和邮箱
openclaw cron add --name "GitHub 热榜 每周 飞书+邮箱" \
  --cron "0 10 * * 3" \
  --system-event '{"tool":"openclaw-github-trending","params":{"since":"weekly","channels":["feishu","email"]}}'

🗣️ 自然语言创建任务

通过与 OpenClaw 自然对话快速创建定时任务，无需记忆复杂的命令格式。插件支持智能解析自然语言指令，自动生成并执行定时任务。

使用方法：

直接在 OpenClaw 聊天界面中用自然语言描述需求：

使用openclaw-github-trending工具，帮我创建一个每天 18:45 推送 GitHub 月榜到邮箱的定时任务

支持的自然语言示例：

// 每日推送
- "使用openclaw-github-trending工具，帮我创建每天早上 8:00 推送 GitHub 今日热榜到邮箱的任务"
- "我想使用openclaw-github-trending工具，在每天 18:45 收到 GitHub 今日热榜，并把内容发送到我的邮箱"
- "使用openclaw-github-trending工具创建定时任务：每天 9:00 获取今日热榜并推送到飞书"

// 每周推送
- "使用openclaw-github-trending工具，帮我创建每周一 10:00 推送 GitHub 本周热榜到飞书的任务"
- "我想使用openclaw-github-trending工具，每周五 18:00 收到本周热榜，发到飞书和邮箱"
- "使用openclaw-github-trending工具，每周三早上 9:00 获取本周热榜并推送到飞书"

// 每月推送
- "使用openclaw-github-trending工具，帮我创建每月 1 号 9:00 推送 GitHub 月榜到邮箱的任务"
- "我想使用openclaw-github-trending工具，每月 15 号 18:45 收到 GitHub 月榜，发到我的邮箱"
- "使用openclaw-github-trending工具，帮我创建一个每天 18:45，推送每月 GitHub 热榜的定时任务，需要将 GitHub 热榜内容发送到我的邮箱中"

// 多渠道推送
- "使用openclaw-github-trending工具，帮我创建每天 8:00 推送今日热榜到飞书和邮箱的任务"
- "我想使用openclaw-github-trending工具，每天 10:00 收到热榜，同时发到飞书和我的邮箱"

// 微信推送
- "使用openclaw-github-trending工具，帮我创建每天 8:00 推送今日热榜到微信的任务"
- "我想使用openclaw-github-trending工具，每周五 18:00 收到本周热榜，发到我的微信"
- "使用openclaw-github-trending工具，帮我创建每月 1 号 9:00 推送月榜到微信的任务"
- "使用openclaw-github-trending工具，帮我创建每天 10:00 推送热榜到飞书、邮箱和微信的任务"

智能解析能力：

✅ 时间识别：自动解析"每天 8:00"、"每周一 10:00"、"每月 1 号 9:00"等时间表达 ✅ 周期识别：自动识别"今日/每天"→daily、"本周/每周"→weekly、"月榜/每月"→monthly ✅ 渠道识别：自动识别"邮箱"→email、"飞书"→feishu、"微信"→wechat、"飞书和邮箱"→["feishu","email"]、"飞书、邮箱和微信"→["feishu","email","wechat"] ✅ 任务创建：自动生成合适的 Cron 表达式并创建定时任务

执行流程：

  1. 用户在 OpenClaw 聊天中输入自然语言指令，需要携带 openclaw-github-trending 工具名称
  2. OpenClaw 解析指令并识别工具（openclaw-github-trending）
  3. 自动提取时间、周期、推送渠道等参数
  4. 生成对应的 cron add 命令并创建任务
  5. 返回任务创建成功信息，包括任务 ID 和执行时间

优势：

✨ 简单易用：无需记忆命令格式，像聊天一样创建任务 ✨ 灵活表达：支持多种自然语言表达方式 ✨ 智能识别：自动解析时间、周期和推送渠道 ✨ 快速配置：一句话完成复杂的定时任务配置

查看命令帮助

运行命令时如果不带参数或参数错误，会自动显示详细的帮助信息：

openclaw gen-cron -h

输出将包含：

  • 命令用法
  • 参数说明
  • 使用示例
  • Cron 表达式格式说明

管理定时任务

设置定时任务后，可以使用 OpenClaw 的 cron 命令管理它们：

# 列出所有定时任务
openclaw cron list

# 查看运行历史
openclaw cron runs

# 手动触发任务
openclaw cron run <job-id>

# 删除任务
openclaw cron rm <job-id>

AI 配置项详细说明

插件支持兼容 OpenAI API 的供应商。如果插件中未配置，将使用 OpenClaw 的 AI 配置。

字段 类型 必填 默认值 说明
provider string 否 "openai" AI 提供商，支持自定义供应商
api_key string 否* - AI 提供商的 API Key
base_url string 否 "https://api.openai.com/v1" API 基础 URL（用于兼容 OpenAI 的供应商）
model string 否 "gpt-4o-mini" 用于生成摘要的模型名称

如果未提供，将使用 OpenClaw 的默认 AI 配置

支持的 AI 供应商

  • OpenAI: provider: "openai"，使用默认 base URL
  • Anthropic: provider: "anthropic"
  • 自定义供应商: 任何兼容 OpenAI API 的服务（如：灵积、月之暗面、DeepSeek 等）

自定义供应商示例：

{
  "ai": {
    "provider": "openai",
    "api_key": "sk-xxx",
    "base_url": "https://coding.dashscope.aliyuncs.com/v1",
    "model": "kimi-k2.5"
  }
}

GitHub 配置

字段 类型 必填 默认值 说明
github_token string 否 - GitHub 个人访问令牌（提高速率限制）

为什么要配置 GitHub Token？

并发配置

字段 类型 必填 默认值 说明
max_workers number 否 5 AI 摘要并发数（建议：3-10）

推送渠道配置

飞书

字段 类型 必填 说明
webhook_url string 是* 飞书机器人 Webhook URL

邮件

字段 类型 必填 默认值 说明
smtp_host string 否 "smtp.gmail.com" SMTP 服务器地址
smtp_port number 否 587 SMTP 服务器端口（465 为 SSL，587 为 STARTTLS）
sender string 是* - 发件人邮箱地址
password string 是* - 邮箱密码或应用专用密码
recipient string 否 同 sender 收件人邮箱地址（如未配置，默认使用发件人地址）
from_name string 否 "GitHub Trending" 发件人显示名称
timeout number 否 30 SMTP 连接超时时间（秒）

微信

字段 类型 必填 默认值 说明
enabled boolean 否 true 通过 @tencent-weixin/openclaw-weixin 插件启用微信通知
receiver_id string 否 自动获取 微信接收者 ID（格式：xxx@im.wechat）

receiver_id 自动获取机制：

插件会按以下优先级自动获取 receiver_id，通常无需手动配置：

  1. 插件配置：plugins.openclaw-github-trending.config.channels.wechat.receiver_id
  2. 环境变量：OPENCLAW_WECHAT_RECEIVER_ID
  3. 消息上下文：如果当前会话来自微信，自动回复给发送者
  4. 会话历史：从 ~/.openclaw/agents/main/sessions/sessions.json 中提取最近使用的微信 ID
  5. OpenClaw 配置：从微信插件的配置和会话中查找

⚠️ 重要提示：

  • 微信 ID 区分大小写，例如：xxx@im.wechat
  • 如果自动获取失败，会显示详细的配置指南和获取方法

微信推送配置要求：

  1. 安装微信插件：

    openclaw plugins install @tencent-weixin/openclaw-weixin

  2. 在 OpenClaw 中配置 (~/.openclaw/openclaw.json)：

    {
  "plugins": {
    "entries": {
      "openclaw-weixin": {
        "enabled": true
      }
    }
  }
}

  3. 可选：配置 receiver_id（仅在需要推送到特定用户时）：

    {
  "plugins": {
    "entries": {
      "openclaw-github-trending": {
        "config": {
          "channels": {
            "wechat": {
              "enabled": true,
              "receiver_id": "xxx@im.wechat"
            }
          }
        }
      }
    }
  }
}

    💡 提示：如果不配置 receiver_id，插件会自动从会话历史中获取。

🔍 如何获取你的微信 ID：

# 方法 1：查看 OpenClaw 会话历史
cat ~/.openclaw/agents/main/sessions/sessions.json | jq 'to_entries[] | select(.key | contains("wechat")) | {key, lastTo}'

# 方法 2：查看消息发送记录
cat ~/.openclaw/agents/main/sessions/sessions.json | grep -i "o9cq.*@im.wechat"

# 方法 3：发送一次测试消息后查看日志
openclaw message send --channel openclaw-weixin --target "你的微信 ID" "测试"

⚠️ 注意事项：

  • 微信 ID 格式：xxx@im.wechat（区分大小写！）

  • 如果自动获取失败，错误信息会包含详细的配置指南

           "enable_login": true
     }
   },
   "openclaw-github-trending": {
     "enabled": true,
     "config": {
       "channels": {
         "wechat": {
           "enabled": true,
           "receiver_id": "xxx@im.wechat"
         }
       }
     }
   }
 }

    } }

  1. 配置方式（三选一）：

    • 配置文件（推荐）：在 openclaw.json 的 wechat 配置中设置 receiver_id
    • 环境变量：设置 OPENCLAW_WECHAT_RECEIVER_ID
    • 默认值：使用内置默认配置（仅用于测试）

  2. 登录微信：

    • OpenClaw 会提示您使用个人微信扫描二维码
    • 登录后，消息将发送到配置的微信账号

  3. 使用方法： ⚠️ 重要：微信推送仅支持在 OpenClaw 聊天环境中使用，不支持 CLI 模式（openclaw gen-cron 命令）

    在 OpenClaw 聊天中使用（推荐）：

    使用 openclaw-github-trending 工具获取今日热榜并推送到微信
或
立即执行：获取今日热榜并推送到微信

    在聊天中创建定时任务：

    openclaw cron add --name "GitHub 热榜 每日 微信" \
  --cron "0 18 * * *" \
  --system-event '{"tool":"openclaw-github-trending","params":{"since":"daily","channels":["wechat"]}}'

注意事项：

  • 微信通知以 Markdown 格式发送到您的个人微信账号
  • 消息包含新项目（完整 AI 摘要）和持续霸榜项目（简要摘要）
  • 微信推送功能依赖 @tencent-weixin/openclaw-weixin 插件提供的 executeTool API
  • CLI 模式下使用微信通道会返回错误提示
  • 如果微信插件未安装或未配置，插件会显示警告但继续向其他渠道推送

*使用该渠道时必填

历史记录配置

字段 类型 必填 默认值 说明
enabled boolean 否 true 启用历史记录追踪和去重
star_threshold number 否 100 Star 增长达到此数值时重新推送

代理配置

字段 类型 必填 默认值 说明
enabled boolean 否 false 启用代理访问 GitHub
url string 否 - 代理 URL（支持 http://user:pass@host:port 或 https://host:port 格式）

示例：

{
  "plugins": {
    "openclaw-github-trending": {
      "proxy": {
        "enabled": true,
        "url": "http://127.0.0.1:7890"
      }
    }
  }
}

带认证的代理：

{
  "plugins": {
    "openclaw-github-trending": {
      "proxy": {
        "enabled": true,
        "url": "http://username:password@192.168.1.1:8080"
      }
    }
  }
}

智能去重

插件会追踪仓库历史记录，智能决定何时重新推送：

  • 首次发现：始终推送新发现的仓库
  • Star 增长：当 Star 增长达到 star_threshold（默认 100）时重新推送
  • 历史追踪：记录仓库详情、AI 摘要和推送历史

安全最佳实践

API Keys

  • 将 API Keys 存储在 .openclaw/openclaw.json 中（而非环境变量）
  • 使用应用专用密码（如 Gmail 应用密码）
  • 限制 API Key 权限到最小必需范围

邮件配置

对于 Gmail：

  1. 启用两步验证
  2. 生成应用专用密码：https://myaccount.google.com/apppasswords
  3. 在 password 字段中使用应用专用密码

飞书 Webhook

  • 保持 Webhook URL 私密
  • 定期轮换 Webhook URL
  • 如果可用，使用 IP 白名单

开发

构建

npm run build

测试

npm test
npm run test:coverage

本地开发

# 链接到本地 OpenClaw
npm link

# 在 OpenClaw 项目中
openclaw plugins install openclaw-github-trending

贡献

欢迎贡献！请阅读贡献指南了解详情。

许可证

MIT © 王允

支持

更新日志

查看 CHANGELOG.md 了解版本历史。