会话监控器（Session Monitor）

一个持久运行的后台进程，持续轮询 Agent 会话目录下的所有 JSONL 转录文件，解析新增条目，并将格式化后的 HTML 更新推送到 Telegram 聊天窗口。同一时间窗口内的消息通过 editMessageText 合并发送，以避免刷屏。

适用场景

• 用户需要对 Agent 活动进行持续、推送式（push-based）监控
• 用户希望在 Telegram 聊天窗口中拥有一个实时仪表盘（live dashboard），直观展示 Agent 的行为
• 不适用于一次性查询——此类场景请改用 sessions_list / sessions_history

快速开始

# 1. 配置
cp scripts/.env.example scripts/.env
# 编辑 scripts/.env，填入 Bot Token、聊天 ID、会话目录路径、用户/群组映射等信息

# 2. 试运行（验证解析逻辑是否正常）
node scripts/test.js

# 3. 启动（支持 exec 会话安全运行 — 即使 Agent 会话结束也不会退出）
node scripts/index.js > scripts/monitor.log 2>&1 &

⚠️ Agent exec 会话注意事项：通过 Agent 的 exec 工具内使用 nohup & 启动的进程，在 exec 会话被清理时可能被终止。 建议在你的 HEARTBEAT.md 中添加看门狗脚本实现自动重启：

PID=$(cat scripts/.pid 2>/dev/null)
if [ -z "$PID" ] || ! ps -p "$PID" > /dev/null 2>&1; then
  cd scripts && node index.js > monitor.log 2>&1 &
fi

配置（.env）

显示格式说明：私聊显示为 ✈ AgentName↔UserName，群组显示为 ✈ GroupName。

架构设计

scripts/
├── index.js      — 主循环：轮询 JSONL 文件、累积新条目、发送/编辑 Telegram 消息
├── parser.js     — 将 JSONL 条目解析为 {sender, text} 格式的展示对象
├── formatter.js  — 合并同发送者消息、按会话排序、构建 HTML 内容
├── sender.js     — Telegram API 封装：sendMessage / editMessageText，含队列机制
├── sessions.js   — 会话键查找、标签格式化、子 Agent 名称解析
├── config.js     — 加载 .env 配置
├── test.js       — 试运行：解析最近条目并输出至 stdout
├── .env.example  — 配置模板文件
└── .env          — 本地配置文件（已加入 .gitignore）

调优参数

在 scripts/index.js 中可调整以下参数：

• POLL = 3000 — 轮询间隔（毫秒），默认为 3 秒
• MERGE_WINDOW = 1 — 将 N 分钟内产生的变更合并为一条 Telegram 消息
• NEW_MSG_THRESHOLD = 3000 — 当当前消息字符数超过该阈值时，强制开启新消息

消息格式

详细格式规范请参阅 references/REFERENCE.md，包括：

• 发送者图标（🤖 assistant、👤 user、⚡ system、↩️ tool result）
• Tool call 的格式化与截断规则
• 会话标签（session tag）的格式与排序逻辑
• Telegram 消息投递机制与速率限制策略

进程管理

PID 文件位于 scripts/.pid，启动时写入，退出时清除。 为避免共享机器上多个监控器冲突，请始终使用绝对路径：

# 检查是否正在运行
SKILL_DIR=/path/to/session-monitor
cat "$SKILL_DIR/scripts/.pid" && ps -p $(cat "$SKILL_DIR/scripts/.pid") -o pid,command

# 停止
kill $(cat "$SKILL_DIR/scripts/.pid")

# 查看日志
tail -f "$SKILL_DIR/scripts/monitor.log"

⚠️ 同一台机器上可共存多个 Session Monitor 实例（各自拥有独立的 .env、.pid 和日志文件）。请确保始终引用正确的 Skill 目录路径。

重启 / 停止 / 状态检查

请将 SKILL_DIR 替换为本 Skill 所在目录（即 scripts/ 的父目录）。

# 状态检查 — 监控器是否正在运行？
SKILL_DIR=/absolute/path/to/session-monitor
PID=$(cat "$SKILL_DIR/scripts/.pid" 2>/dev/null)
if [ -n "$PID" ] && ps -p "$PID" > /dev/null 2>&1; then
  echo "✅ Monitor 运行中（PID $PID）"
else
  echo "❌ Monitor 未运行"
fi

# 停止
kill $(cat "$SKILL_DIR/scripts/.pid")

# 启动
cd "$SKILL_DIR/scripts" && node index.js > monitor.log 2>&1 &

# 重启（先停止再启动）
kill $(cat "$SKILL_DIR/scripts/.pid") 2>/dev/null; sleep 1
cd "$SKILL_DIR/scripts" && node index.js > monitor.log 2>&1 &

注意事项

• 零依赖 — 完全基于 Node.js 标准库实现
• 启动时会发送一条示例横幅消息，用于验证 Telegram 连通性
• 单条消息超过 4000 字符时将被截断，并在下一次轮询时强制开启新消息
• Telegram API 调用间至少间隔 3 秒（防限流）