一个基于PHP的钉钉机器人开发框架，支持插件化扩展和完整的日志记录系统。

二次开发使用Code Buddy IDE进行辅助开发。感谢CNB.COOL提供代码托管服务

• 版本: v1.1.0
• 作者: Qicloud admin@zets.cn
• 适用于: 钉钉群聊机器人
• 更新: 支持新版钉钉机器人 SessionWebhook

• 支持新版钉钉机器人 SessionWebhook（推荐）
• 兼容传统钉钉机器人配置方式
• 插件化架构，支持自定义功能扩展
• 完整的日志记录系统
• 管理员权限控制（基于钉钉isAdmin字段）
• 定时任务支持
• 消息发送统计
• 自动兼容新旧版钉钉机器人

• 文本消息 (text)
• Markdown消息 (markdown)
• 链接消息 (link)
• 卡片消息 (actionCard)
• 订阅消息 (feedCard)

• 聊天消息日志: ./Data/Log/Chat/[日期]/chat.log
• 原始消息日志: ./Data/Log/Other/[日期]-raw.log
• 其他类型消息: ./Data/Log/Other/[日期].log
• 未知消息日志: ./Data/Log/Other/[日期]-unknown.log
• 定时任务日志: ./Data/Cron/Cron_[任务名].log
• 安全验证日志: ./Data/Log/Security/[日期]-security.log 🔒
• 消息统计: ./Data/num.txt

BOT_API/
├── index.php              # 主入口文件
├── inc/
│   ├── config.php         # 配置文件
│   └── function.php       # 函数库
├── plugins/               # 插件目录
│   ├── Hello World.php    # 示例插件
│   ├── GroupSign.php      # 群签到插件
│   ├── Weather_List.php   # 天气查询插件
│   ├── Hitokoto.php       # 一言插件
│   ├── Time.php           # 时间插件
│   └── Rand.php           # 随机数插件
├── Data/                  # 数据目录（自动创建）
│   ├── Log/               # 日志目录
│   │   ├── Chat/          # 聊天日志
│   │   └── Other/         # 其他日志
│   ├── Cron/              # 定时任务日志
│   └── num.txt            # 消息统计
├── themes/                # 主题目录
└── docs/                  # 文档目录

编辑 inc/config.php 文件：

// 是否使用新版钉钉机器人（使用 sessionWebhook）
$Use_SessionWebhook = 'true';

// 钉钉机器人签名验证配置（重要安全功能）
$Enable_Sign_Verification = 'true';  // 生产环境强烈建议开启
$BOT_AppSecret = '你的机器人AppSecret';  // 从钉钉开发者后台获取

// 其他配置
$BOT_Sleep = 'false';
$API_Server = '你的API地址';
$API_Token = '你的API_Token';
$Cron_Token_Required = 'false';

// 使用传统配置模式
$Use_SessionWebhook = 'false';

// 钉钉机器人的Webhook地址
$BOT_Server = 'https://oapi.dingtalk.com/robot/send';

// 钉钉机器人的Access_Token
$BOT_Token = '你的access_token';

// 钉钉机器人的关键词
$BOT_Keyword = '你的关键词';

// 签名验证配置（可选但推荐）
$Enable_Sign_Verification = 'true';
$BOT_AppSecret = '你的机器人AppSecret';

// 其他配置
$BOT_Sleep = 'false';
$API_Server = '你的API地址';
$API_Token = '你的API_Token';
$Cron_Token_Required = 'false';

特性	新版 SessionWebhook	传统版本
关键词	❌ 不需要	✅ 必须配置
Access Token	❌ 不需要	✅ 必须配置
Webhook地址	🔄 动态获取	📝 手动配置
配置复杂度	🟢 简单	🟡 中等
推荐程度	⭐⭐⭐⭐⭐	⭐⭐⭐

钉钉机器人支持签名验证来确保请求的合法性，强烈建议在生产环境中启用：

// 开启签名验证
$Enable_Sign_Verification = 'true';

// 设置机器人的AppSecret（从钉钉开发者后台获取）
$BOT_AppSecret = '你的机器人AppSecret';

1. 时间戳验证: 请求时间戳与系统当前时间相差超过1小时则拒绝
2. 签名验证: 使用 timestamp + "\n" + AppSecret 进行 HmacSHA256 签名并 Base64 编码
3. 双重验证: 只有时间戳和签名同时验证通过才认为是合法请求

系统会自动记录安全相关事件：

• 验证成功: ./Data/Log/Security/[日期]-security.log
• 验证失败: 包含IP地址和失败原因
• 异常请求: 缺少必要头部信息的请求

1. 登录钉钉开发者后台
2. 找到你的机器人应用
3. 在机器人配置页面获取 AppSecret
4. 将 AppSecret 配置到 $BOT_AppSecret 变量中

⚠️ 安全提醒:

• AppSecret 是敏感信息，请妥善保管
• 生产环境务必开启签名验证
• 定期检查安全日志

如果需要使用定时任务功能，可以通过以下方式触发：

在钉钉群中发送以下命令之一：

• "执行定时任务"
• "检查定时任务"
• "触发定时任务"

通过crontab等定时器定期访问接口：

不需要token验证（默认配置）：

# 每分钟执行一次
* * * * * curl "http://你的域名/?trigger_tasks=true"

需要token验证（生产环境推荐）：

1. 在config.php中设置：$Cron_Token_Required = 'true';
2. 设置crontab：

# 每分钟执行一次
* * * * * curl "http://你的域名/?trigger_tasks=true&token=你的API_Token"

将项目文件上传到Web服务器，确保PHP环境支持：

• PHP 7.0+
• cURL扩展
• 文件写入权限

在钉钉群聊中添加自定义机器人，将Webhook地址设置为：

https://你的域名/

插件文件放置在 plugins/ 目录下，基本结构：

<?php
/*
* @Plugin Name：示例插件
* @Author：你的名字
* @Version：1.0.0
* @Modified for：钉钉机器人
*/

// 检查消息内容
if(isset($Data['text']['content'])) {
    $message = $Data['text']['content'];
    
    // 匹配关键词
    if(strpos($message, '你好') !== false) {
        // 使用新的发送函数（推荐）
        send_text('你好！我是机器人');
        
        // 或者发送Markdown消息
        send_markdown('问候', '**你好！** 我是机器人\n\n欢迎使用！');
    }
    
    // 处理其他命令
    if(strpos($message, '帮助') !== false) {
        $helpText = "# 机器人帮助\n\n";
        $helpText .= "- 发送「你好」获取问候\n";
        $helpText .= "- 发送「帮助」查看此信息\n";
        
        send_markdown('帮助信息', $helpText);
    }
}
?>

<?php
// 旧版插件写法仍然支持
if(isset($Data['text']['content'])) {
    $message = $Data['text']['content'];
    
    if(strpos($message, '你好') !== false) {
        // 旧版写法（仍然可用）
        http_post_json('text', '你好！我是机器人');
    }
}
?>

• send_text($content) - 发送文本消息（推荐）
• send_markdown($title, $text) - 发送Markdown消息（推荐）
• send_message($msgType, $content) - 通用发送函数（推荐）
• http_post_json($msgType, $content, $sessionWebhook) - 原始发送函数（兼容）

• curl($url, $guise, $UA) - HTTP请求
• Curl_Post($server, $data) - POST请求

• BOT_Time_Inr($name, $minutes) - 间隔执行
• BOT_Time_Day($name, $time) - 每天定时执行
• BOT_Time_One($name, $datetime) - 单次定时执行
• BOT_Time_Hour($name, $minute) - 整点执行

• call_api($endpoint, $params) - 调用外部API

框架自动识别钉钉群管理员权限（基于isAdmin字段），管理员可使用特殊命令：

• 重启命令: 发送包含"重启"的消息可重启机器人服务

[2024-01-20 14:30:25] 用户昵称(用户ID): 消息内容

[2024-01-20 14:30:25] {"msgtype":"text","text":{"content":"消息内容"},...}

开启延时策略可避免消息发送过于频繁：

$BOT_Sleep = 'true';  // 开启延时

在 themes/ 目录下创建 index.php 可自定义访问页面。

1. 权限设置: 确保 Data/ 目录有写入权限
2. 关键词配置: 钉钉机器人需要配置关键词才能正常发送消息
3. 服务器要求: 需要支持PHP和cURL扩展
4. 日志管理: 定期清理日志文件避免占用过多空间

• 优化管理员权限判断，使用钉钉返回的isAdmin字段
• 简化配置文件，移除不必要的Admin_ID配置
• 完善日志记录系统
• 支持多种消息类型发送

如有问题或建议，请查看 docs/ 目录下的相关文档。

本项目基于开源项目二次开发，仅供学习和研究使用。

• 原作者: Hanximeng https://github.com/hanximeng/BOT_API