# TOOLS.md - 环境配置备注

本文件记录小斑运行环境中的工具配置和使用备注。技能（skills）定义工具的使用方法，本文件记录环境特有的配置信息。

> ⚠️ **数据库密码、API 密钥等敏感凭证已统一存储在 `secrets.md` 中，本文件不包含明文密码。**

---

## 数据库连接概览

已成功连接全部 6 个数据库：

| 序号 | 数据库 | 用途 | 凭证位置 |
|------|--------|------|----------|
| 1 | Test MySQL | 测试环境业务数据 | `secrets.md` |
| 2 | Online MySQL | 线上环境业务数据 | `secrets.md` |
| 3 | Test PostgreSQL | 测试环境用户行为数据 | `secrets.md` |
| 4 | Online PostgreSQL | 线上环境用户行为数据 | `secrets.md` |
| 5 | Test ES | 测试环境服务日志 | `secrets.md` |
| 6 | Online ES | 线上环境服务日志 | `secrets.md` |

运行脚本前需先配置环境变量，详见 `secrets.md` 中的环境变量配置段落。

---

## 脚本工具

### 用户学习行为导出脚本

- **脚本路径：** `makee_vala/business_knowledge/git_scripts/export_user_id_data.py`
- **功能：** 导出指定角色/账户的全量学习行为数据（音频记录、互动组件记录、课程巩固/挑战/总结记录、统计汇总），输出为多 sheet Excel 文件

**使用方式（三种模式互斥）：**

1. 单个角色导出：`USER_ID = 14607`
2. 多个角色批量导出：`USER_ID_LIST = [14607, 14608, 14609]`
3. 多个账户批量导出：`ACCOUNT_ID_LIST = [2148, 2149, 2150]`

**运行命令：** `python3 makee_vala/business_knowledge/git_scripts/export_user_id_data.py`

**输出路径：** 默认输出到 `output/` 目录下，文件名格式：
- 角色导出：`角色id_{ID}_导出时间_{YYYYMMDD}.xlsx`
- 账户导出：`账户id_{ID}_角色id_{ID}_导出时间_{YYYYMMDD}.xlsx`

---

## 飞书文件发送

使用 `message` 工具发送本地文件（适用于小文件和文本消息）：

```json
{
  "action": "send",
  "channel": "feishu",
  "target": "用户/群飞书ID",
  "file_path": "本地文件绝对路径",
  "message": "可选，附带的消息文本"
}
```

对于大文件（Excel/PDF 等），使用 `skills/feishu_send_file/` 技能中的三步流程（获取 token → 上传文件 → 发送消息）。

---

## 飞书格式化提示

- 飞书消息支持 Markdown，但复杂表格建议用项目符号列表替代
- 长文本建议分段发送，避免一次性输出过多内容

---

## 飞书定时任务强制规则

所有发送到飞书的定时任务/提醒，必须在投递参数中指定 `--account xiaoban`，禁止使用默认 default bot，否则会导致消息发送失败。