11 KiB
CyberStrikeAI 机器人使用说明
本文档说明如何通过钉钉、飞书与 CyberStrikeAI 对话（长连接模式），在手机端即可使用，无需在服务器上打开网页。按下面步骤操作可避免常见弯路。
一、在 CyberStrikeAI 里从哪里配置
- 登录 CyberStrikeAI Web 端
- 左侧导航进入 系统设置
- 在左侧设置分类中点击 机器人设置（位于「基本设置」与「安全设置」之间）
- 按平台勾选并填写（钉钉填 Client ID / Client Secret，飞书填 App ID / App Secret）
- 点击 应用配置 保存
- 重启 CyberStrikeAI 应用（只保存不重启，机器人不会连上）
配置会写入 config.yaml 的 robots 段，也可在配置文件中直接编辑。修改钉钉/飞书配置后必须重启，长连接才会生效。
二、支持的平台（长连接）
| 平台 | 说明 |
|---|---|
| 钉钉 | 使用 Stream 长连接，程序主动连接钉钉接收消息 |
| 飞书 | 使用长连接，程序主动连接飞书接收消息 |
下面第三节会按平台写清：在开放平台要做什么、要复制哪些字段、填到 CyberStrikeAI 的哪一栏。
三、各平台配置项与详细步骤
3.1 钉钉
先搞清楚：两种钉钉机器人不一样
| 类型 | 从哪里创建 | 能否做「用户发消息→机器人回复」 | 本程序是否支持 |
|---|---|---|---|
| 自定义机器人 | 钉钉群里：群设置 → 添加机器人 → 自定义（Webhook） | ❌ 不能，只能你往群里发消息 | ❌ 不支持 |
| 企业内部应用机器人 | 钉钉开放平台 创建应用并开通机器人 | ✅ 能 | ✅ 支持 |
如果你手里是「自定义机器人」的 Webhook 地址（oapi.dingtalk.com/robot/send?access_token=xxx）和加签密钥（SEC...），不能直接填到本程序，必须按下面步骤在开放平台创建「企业内部应用」并拿到 Client ID、Client Secret。
钉钉配置完整步骤（按顺序做）
-
打开钉钉开放平台
浏览器访问 https://open.dingtalk.com，用企业管理员账号登录。 -
进入应用开发
左侧选 应用开发 → 企业内部开发 → 点击 创建应用（或选择已有应用）。填写应用名称等基本信息后创建。 -
拿到 Client ID 和 Client Secret
- 左侧点 凭证与基础信息（在「基础信息」下）。
- 页面上有 Client ID（原 AppKey） 和 Client Secret（原 AppSecret）。
- 点击复制，不要手打，注意：数字 0 和字母 o、数字 1 和字母 l 容易抄错（例如
ding9gf9tiozuc504aer中间是数字 504 不是 5o4）。
-
开通机器人并选 Stream 模式
- 左侧 应用能力 → 机器人。
- 打开「机器人配置」开关。
- 填写机器人名称、简介等（必填项按提示填）。
- 关键：消息接收方式要选 「Stream 模式」（流式接入）。若只有「HTTP 回调」或未选 Stream，本程序收不到消息。
- 保存。
-
权限与发布
- 左侧 权限管理：搜索「机器人」「消息」等，勾选接收消息、发送消息等机器人相关权限，并确认授权。
- 左侧 版本管理与发布：若有未发布配置，点击 发布新版本 / 上线，否则修改不生效。
-
填回 CyberStrikeAI
- 回到 CyberStrikeAI → 系统设置 → 机器人设置 → 钉钉。
- 勾选「启用钉钉机器人」。
- Client ID (AppKey) 粘贴第 3 步复制的 Client ID。
- Client Secret 粘贴第 3 步复制的 Client Secret。
- 点击 应用配置，然后重启 CyberStrikeAI。
CyberStrikeAI 钉钉栏位对照
| CyberStrikeAI 中填写项 | 在钉钉开放平台的来源 |
|---|---|
| 启用钉钉机器人 | 勾选即启用 |
| Client ID (AppKey) | 凭证与基础信息 → Client ID（原 AppKey） |
| Client Secret | 凭证与基础信息 → Client Secret（原 AppSecret） |
3.2 飞书 (Lark)
| 配置项 | 说明 |
|---|---|
| 启用飞书机器人 | 勾选后启动飞书长连接 |
| App ID | 飞书开放平台应用凭证中的 App ID |
| App Secret | 飞书开放平台应用凭证中的 App Secret |
| Verify Token | 事件订阅用（可选） |
飞书配置简要步骤：登录 飞书开放平台 → 创建企业自建应用 → 在「凭证与基础信息」中获取 App ID、App Secret → 在「应用能力」中开通机器人并启用相应权限 → 发布应用 → 将 App ID、App Secret 填到 CyberStrikeAI 机器人设置 → 保存并重启应用。
四、机器人命令
在钉钉/飞书中向机器人发送以下文本命令（仅支持文本）：
| 命令 | 说明 |
|---|---|
| 帮助 | 显示命令帮助与说明 |
| 列表 或 对话列表 | 列出所有对话的标题与对话 ID |
| 切换 <对话ID> 或 继续 <对话ID> | 指定对话 ID，后续消息在该对话中继续 |
| 新对话 | 开启一个新对话，后续消息在新对话中 |
| 清空 | 清空当前对话上下文（效果等同「新对话」） |
| 当前 | 显示当前对话 ID 与标题 |
| 停止 | 中断当前正在执行的任务 |
| 角色 或 角色列表 | 列出所有可用角色（渗透测试、CTF、Web 应用扫描等） |
| 角色 <角色名> 或 切换角色 <角色名> | 切换当前使用的角色 |
| 删除 <对话ID> | 删除指定对话 |
| 版本 | 显示当前 CyberStrikeAI 版本号 |
除以上命令外，直接输入任意文字会作为用户消息发给 AI，与 Web 端对话逻辑一致（渗透测试/安全分析等）。
五、如何使用（要 @ 机器人吗？）
- 单聊（推荐）：在钉钉/飞书里搜索并打开该机器人，进入与机器人的私聊，直接输入「帮助」或任意文字即可，不需要 @。
- 群聊：若机器人被添加到群里，在群内只有 @机器人 后发送的消息才会被机器人收到并回复；不 @ 的群消息不会触发机器人。
总结：和机器人单聊时直接发；在群里用时需要 @机器人 再发内容。
六、推荐使用流程（避免漏步骤）
- 在开放平台：按第三节完成钉钉或飞书应用创建、凭证复制、机器人开通（钉钉务必选 Stream 模式）、权限与发布。
- 在 CyberStrikeAI：系统设置 → 机器人设置 → 勾选对应平台，粘贴 Client ID/App ID、Client Secret/App Secret → 点击 应用配置。
- 重启 CyberStrikeAI 进程（否则长连接不会建立）。
- 在手机钉钉/飞书：找到该机器人（单聊直接发，群聊需 @机器人），发「帮助」或任意内容测试。
若发消息没反应，先看 第九节排查 和 第十节常见弯路。
七、配置文件示例
config.yaml 中机器人相关片段示例：
robots:
dingtalk:
enabled: true
client_id: "your_dingtalk_app_key"
client_secret: "your_dingtalk_app_secret"
lark:
enabled: true
app_id: "your_lark_app_id"
app_secret: "your_lark_app_secret"
verify_token: ""
修改后需重启应用，长连接在应用启动时建立。
八、如何验证是否可用（无需钉钉/飞书客户端）
在未安装钉钉或飞书时，可用测试接口验证机器人逻辑是否正常：
- 先登录 CyberStrikeAI Web 端（保证有登录态）。
- 使用 curl 调用测试接口（需携带登录后的 Cookie）：
# 将 YOUR_COOKIE 替换为登录后获得的 Cookie（浏览器 F12 → 网络 → 任意请求 → 请求头中的 Cookie）
curl -X POST "http://localhost:8080/api/robot/test" \
-H "Content-Type: application/json" \
-H "Cookie: YOUR_COOKIE" \
-d '{"platform":"dingtalk","user_id":"test_user","text":"帮助"}'
若返回 JSON 中含有 "reply":"【CyberStrikeAI 机器人命令】..."，说明命令处理正常。可再试 "text":"列表"、"text":"当前" 等。
接口说明：POST /api/robot/test（需登录），请求体 {"platform":"可选","user_id":"可选","text":"必填"}，响应 {"reply":"回复内容"}。
九、钉钉发消息没反应时排查
按顺序检查：
-
笔记本合盖睡眠 / 断网后
钉钉、飞书均使用长连接收消息，睡眠或断网后连接会断开。程序会自动重连（约 5 秒～60 秒内重试）。唤醒或恢复网络后稍等一会儿再发消息；若仍无反应，可重启 CyberStrikeAI 进程。 -
Client ID / Client Secret 是否与开放平台完全一致
从「凭证与基础信息」里复制粘贴，不要手打。注意数字 0 与字母 o、数字 1 与字母 l（例如ding9gf9tiozuc504aer中间是 504 不是 5o4）。 -
是否在保存配置后重启了应用
机器人长连接在应用启动时建立。在 Web 端点击「应用配置」只写入配置文件，必须重启 CyberStrikeAI 进程后钉钉连接才会生效。 -
看程序日志
- 启动后应看到：
钉钉 Stream 正在连接…、钉钉 Stream 已启动（无需公网），等待收消息。 - 若出现
钉钉 Stream 长连接退出且带错误信息，多为 Client ID / Client Secret 错误或开放平台未开通流式接入。 - 在钉钉里发一条消息后，若有收到，应有日志：
钉钉收到消息；若没有，说明钉钉未把消息推到本程序（回头检查开放平台「机器人」是否开通、是否选用 Stream 模式）。
- 启动后应看到：
-
开放平台侧
应用需已发布；在「机器人」能力中需开启流式接入（Stream） 用于接收消息（仅 HTTP 回调不够）；权限管理里需有机器人接收、发送消息等权限。
十、常见弯路（避免踩坑）
- 用错了机器人类型：在钉钉群里添加的「自定义」机器人（Webhook + 加签）不能用来做对话，本程序只支持**开放平台「企业内部应用」**里的机器人。
- 只保存没重启：在 CyberStrikeAI 里改完机器人配置后必须重启应用，否则长连接不会建立。
- Client ID 抄错：开放平台是
504就填504，不要填成5o4；尽量用复制粘贴。 - 钉钉只开了 HTTP 回调没开 Stream：本程序通过 Stream 长连接收消息，开放平台里机器人的消息接收方式必须选 Stream 模式。
- 应用没发布：开放平台里修改了机器人或权限后，要在「版本管理与发布」里发布新版本，否则不生效。
十一、注意事项
- 钉钉、飞书均仅处理文本消息；其他类型（如图片、语音）会提示暂不支持或忽略。
- 会话与 Web 端共用同一套对话数据：在机器人里创建的对话会在 Web 端「对话」列表中看到，反之亦然。
- 机器人执行逻辑与
/api/agent-loop/stream一致（含进度回调、过程详情写入数据库），仅不向客户端推送 SSE，最后将完整回复一次性发回钉钉/飞书/企业微信。