WeCom SQL Assistant

企业微信自然语言数据查询集成方案 —— 当前基于 OpenClaw + SQLBot，并维护 Hermes 迁移设计

用户在企业微信中直接提问，系统自动路由至 SQLBot 执行查询，并将摘要、图表和结构化产物回传至企业微信。本仓库提供当前 OpenClaw workspace 配置、SQLBot skill 实现、监控面板和完整运行机制说明，同时在 hermes/ 中记录将 OpenClaw 替换为 Hermes 的初步设计。

• 自然语言直接提问，无需固定命令前缀
• 会话级 SQLBot chat 复用，同一会话内连续追问保持上下文
• 多用户隔离，每个 OpenClaw session 独立绑定 SQLBot chat_id
• workspace / datasource 按会话切换，切换时自动清空旧 chat
• 结构化查询产物：raw-result.json、normalized.json、data.csv、chart.png、manifest.json
• 结构化错误分类：summary.error_kind 提供机器可读的错误类型字段
• 执行链路 Trace：可选开启 JSONL 格式阶段埋点与 telemetry 返回
• Dashboard 截图导出（JPG / PNG / PDF，依赖 Playwright）
• 运维监控面板：基于 FastAPI + Alpine.js 的单页看板，展示链路总览、请求追踪、Session 视图和 SQLBot 健康状态
• Hermes 迁移设计：评估以 Hermes 承接企业微信单聊入口和 agent runtime，SQLBot 继续作为问数引擎

WeCom_SQL_Assistant/
├── README.md
├── corp-assistant-sqlbot-workflow.md        # 完整工作流说明
├── hermes/
│   └── README.md                            # Hermes 迁移初步设计
├── openclaw/
│   ├── AGENTS.md                            # agent 路由规则与行为约束
│   ├── IDENTITY.md                          # agent 身份定义
│   ├── SOUL.md                              # 输出风格约束
│   ├── USER.md                              # 用户模型假设
│   ├── TOOLS.md                             # 工具使用边界与可观测性说明
│   ├── HEARTBEAT.md                         # 运行优先级
│   ├── MEMORY.md                            # agent 记忆文件
│   ├── DREAMS.md                            # 长期目标
│   └── skills/
│       └── sqlbot-workspace-dashboard/
│           ├── SKILL.md                     # skill 调用规范与命令模板
│           ├── README.md                    # skill 说明与新特性文档
│           ├── reference.md                 # 命令参考
│           ├── sqlbot_skills.py             # skill 实现
│           └── .env.example                 # 环境变量模板
└── monitor/                                 # 运维监控面板
    ├── app.py                               # FastAPI 主程序（路由、API、认证）
    ├── auth.py                              # bcrypt 密码存储 + itsdangerous cookie 会话
    ├── config.toml                          # 运行时配置（路径、端口、超时等）
    ├── requirements.txt                     # Python 依赖
    ├── setup.sh                             # 一键部署脚本
    ├── corp-assistant-monitor.service       # systemd unit 文件
    ├── nginx.conf.example                   # nginx 反代配置示例
    ├── readers/
    │   ├── trace.py                         # 读 sqlbot-events.jsonl，计算总览/瀑布
    │   ├── state.py                         # 读 .sqlbot-skill-state.json，检测 session 异常
    │   ├── artifacts.py                     # 扫描 artifacts/ 目录，读取 manifest.json
    │   └── sqlbot_health.py                 # 主动探活 SQLBot API
    ├── templates/
    │   ├── login.html                       # 登录页
    │   └── change_password.html             # 首次登录强制改密页
    └── static/
        └── index.html                       # 单页前端（Alpine.js + Chart.js + Bootstrap 5）

当前生产链路仍以 OpenClaw 为企业微信入口和 agent runtime：

flowchart TD
    User["企业微信用户"] --> WeCom["企业微信机器人"]
    WeCom --> Gateway["OpenClaw Gateway"]
    Gateway --> Corp["corp-assistant"]
    Corp --> Prompt["AGENTS / IDENTITY / SOUL / USER / TOOLS"]
    Prompt --> Route{"消息类型"}
    Route -->|"问候 / 能力说明"| Direct["直接返回预置说明"]
    Route -->|"业务数据请求 / 追问"| Skill["sqlbot-workspace-dashboard"]
    Skill --> SQLBot["SQLBot API"]
    SQLBot --> DB["业务数据源"]
    Skill --> Artifacts["raw / normalized / csv / chart / manifest"]
    Skill --> Trace["monitoring/sqlbot-events.jsonl（可选）"]
    Trace --> Monitor["Corp Assistant Monitor（运维面板）"]
    Artifacts --> Monitor

Hermes 迁移方向如下，详细设计见 hermes/README.md：

flowchart TD
    User["企业微信单聊用户"] --> WeCom["企业微信机器人"]
    WeCom --> Hermes["Hermes WeCom Gateway"]
    Hermes --> Profile["corp-assistant profile"]
    Profile --> Adapter["SQLBot adapter / MCP wrapper"]
    Adapter --> State["Hermes session -> SQLBot chat_id"]
    Adapter --> SQLBot["SQLBot API / MCP"]
    SQLBot --> DB["业务数据源"]
    Adapter --> Trace["trace / artifacts"]
    Trace --> Monitor["Corp Assistant Monitor"]

Hermes 方案的核心原则是：Hermes 负责企业微信单聊入口、会话隔离和 agent profile；SQLBot 继续负责 SQL 生成、查询执行和图表数据；中间 adapter 负责把 Hermes 单聊 session 绑定到 SQLBot chat_id，保留连续追问上下文。

企业微信机器人接入说明：在本地终端部署 OpenClaw 并关联机器人

以下为当前 OpenClaw 生产链路部署流程。Hermes 迁移仍处于设计和验证阶段，先不要直接替换生产入口；迁移步骤见 hermes/README.md。

mkdir -p /root/.openclaw/workspace-corp-assistant-prod
cp -r openclaw/* /root/.openclaw/workspace-corp-assistant-prod/

cd /root/.openclaw/workspace-corp-assistant-prod/skills/sqlbot-workspace-dashboard
cp .env.example .env
# 填写以下字段

Access Key、Secret Key 和企业微信 secret 不得进入版本库。

在 OpenClaw 环境中完成以下配置（本仓库不提供带凭据的 openclaw.json）：

• 配置企业微信 channel（写入 botid 和 secret）
• 注册 corp-assistant agent
• 将 wecom channel 绑定至 corp-assistant
• 指定 workspace 目录为 /root/.openclaw/workspace-corp-assistant-prod

python3 sqlbot_skills.py workspace list

返回 workspace 列表即表示连接和鉴权配置有效。

# 本地图表渲染
pip install pillow

# Dashboard 截图导出
pip install playwright
playwright install chromium

监控面板运行于 192.168.4.15，通过 192.168.4.11（nginx）对外暴露。

# 在 192.168.4.15 上以 root 运行
bash monitor/setup.sh

脚本自动完成：复制文件、创建 Python venv、安装依赖、配置防火墙（仅允许 192.168.4.11 访问 8765 端口）、注册并启动 systemd 服务。

部署完成后访问 http://192.168.4.11（经 nginx 反代），默认账号 admin / admin，首次登录强制修改密码。

根据实际路径编辑 monitor/config.toml：

[data]
trace_file    = "/root/.openclaw/workspace-corp-assistant-prod/skills/sqlbot-workspace-dashboard/monitoring/sqlbot-events.jsonl"
state_file    = "/root/.openclaw/workspace-corp-assistant-prod/skills/sqlbot-workspace-dashboard/.sqlbot-skill-state.json"
artifacts_dir = "/root/.openclaw/workspace-corp-assistant-prod/skills/sqlbot-workspace-dashboard/artifacts/"
sessions_dir  = "/root/.openclaw/agents/corp-assistant/sessions/"
skill_env     = "/root/.openclaw/workspace-corp-assistant-prod/skills/sqlbot-workspace-dashboard/.env"

# 可选：将 session_key（企业微信 userid）映射为显示名
[user_aliases]
# "wxxxxxxxxxxxxxxxxx" = "张三"

每次 ask 在 artifacts/ 目录写入以下文件：

artifacts/
  <scope_id>/
    <YYYYMMDD-HHMMSS>-record-<id>/
      raw-result.json      # SQLBot 原始 API 响应
      normalized.json      # 归一化字段、行数据和图表方案
      data.csv             # 表格数据（有数据时生成）
      chart.png            # 渲染图表（有图表方案时生成）
      manifest.json        # trace 关联、session 信息、文件索引

ask 返回的 compact JSON 包含以下顶层字段：

error_kind 取值：

sqlbot_skills.py ask 支持开启执行链路跟踪：

# trace 默认启用，写入 monitoring/sqlbot-events.jsonl（skill 目录下）
python3 sqlbot_skills.py ask "本周各客户出货量"

# 关闭 trace
python3 sqlbot_skills.py --no-emit-trace ask "本周各客户出货量"

# 自定义 trace 文件路径
python3 sqlbot_skills.py --trace-file /path/to/events.jsonl ask "问题"

# 指定 trace ID
python3 sqlbot_skills.py --trace-id "run-001" ask "问题"

每条事件记录一个执行阶段（JSONL 格式），包含 trace_id、stage、status、duration_ms、error_kind 等字段。ask 返回值中也包含顶层 telemetry 字段，提供完整的阶段耗时分解。

生产流量必须显式携带 session context，禁止使用隐式 default scope。

# 查看当前 session 绑定
python3 sqlbot_skills.py \
  --openclaw-session-key "<sessionKey>" \
  --openclaw-agent-id "corp-assistant" \
  session show

# 发起查询
python3 sqlbot_skills.py \
  --openclaw-session-key "<sessionKey>" \
  --openclaw-agent-id "corp-assistant" \
  ask "本周各客户出货量排行"

# 强制新建 SQLBot chat
python3 sqlbot_skills.py \
  --openclaw-session-key "<sessionKey>" \
  --openclaw-agent-id "corp-assistant" \
  ask --new-chat "重新从客户维度分析本月业务量"

# 切换 datasource
python3 sqlbot_skills.py \
  --openclaw-session-key "<sessionKey>" \
  --openclaw-agent-id "corp-assistant" \
  datasource switch "<datasource>" --workspace "<workspace>"

# 重置当前 session（保留 workspace/datasource 绑定）
python3 sqlbot_skills.py \
  --openclaw-session-key "<sessionKey>" \
  --openclaw-agent-id "corp-assistant" \
  session reset

# 完全重置（清空 workspace/datasource 绑定）
python3 sqlbot_skills.py \
  --openclaw-session-key "<sessionKey>" \
  --openclaw-agent-id "corp-assistant" \
  session reset --full

# 首次 clone 本项目后，初始化子模块
git submodule update --init --recursive

# 更新 SQLBot 到上游最新 commit
cd SQLBot && git pull origin main && cd ..
git add SQLBot
git commit -m "chore: update SQLBot submodule"

当前 OpenClaw 生产链路验收：

Hermes 迁移验收需额外验证：

• 问候类消息和功能说明请求直接由 agent 回复，不进入 SQLBot
• 数据查询请求默认路由至 SQLBot，无需 查询 前缀
• 对外输出为简洁中文摘要，不暴露内部路径、session key 或调试信息
• SQLBot 返回错误时按执行失败处理，不得误判为"无数据"
• summary.error_kind 用于程序路由，不要从人类可读文本猜错误类型

• .env（含 SQLBot API Key）、openclaw.json（含企业微信 secret）均在 .gitignore 中排除，切勿提交
• 监控面板仅允许来自 nginx 反代服务器（192.168.4.11）的请求访问，防火墙已在 setup.sh 中自动配置
• 首次登录强制修改默认密码，密码使用 bcrypt 存储

涉及生产行为调整时，需同步以下文件：

1. openclaw/AGENTS.md
2. openclaw/TOOLS.md
3. openclaw/skills/sqlbot-workspace-dashboard/SKILL.md
4. openclaw/skills/sqlbot-workspace-dashboard/sqlbot_skills.py
5. corp-assistant-sqlbot-workflow.md
6. hermes/README.md（如涉及 Hermes 迁移设计或目标链路）
7. 本 README

✅ 已实现 ⬜ 未实现 🔲 部分实现

面板设计分四个阶段：

• ✅ P0：只读已有文件，快速上线可观测面板
• ✅ P1：补充 SQLBot skill 结构化 trace，精确记录 SQLBot 执行阶段
• ⬜ P2：补充企微入口/出口埋点，精确记录消息接收和投递结果
• ⬜ P3：增加告警和运维操作，但默认保持只读

• ⬜ 企微通道状态（需 P2 企微埋点，暂无数据来源）
• ⬜ corp-assistant agent 状态（需 P2 企微埋点，暂无数据来源）
• ✅ SQLBot API 探活状态
• ✅ 今日请求数、成功率、失败率、空结果率
• ✅ 平均耗时、P95 耗时
• ⬜ 活跃用户数（仅统计了活跃 Session 数，用户数未去重单独展示）
• ✅ 活跃 session 数
• ✅ 最近错误 Top N

• ✅ 时间、企业微信用户（别名映射）、sessionKey、chat_id、record_id、状态、总耗时
• ✅ 按用户、session、状态过滤
• ⬜ sessionId、问题摘要、skill 是否命中（trace JSONL 中无此字段）
• ⬜ delivery_failed / timeout 状态（需 P2 企微埋点）
• ⬜ 按 record_id、时间范围筛选

• ✅ 执行瀑布图（skill 内各阶段）
• ⬜ agent 侧阶段（message_received / message_sent 等，需 P2）
• ⬜ 请求追踪详情页关联 artifacts 文件（raw-result / chart.png / data.csv）

• ✅ scope_key、workspace、datasource、chat_id、record_id、最近问题、更新时间
• ✅ 异常标记：datasource 缺失、default scope、无 chat_id
• ⬜ 异常标记：session 频繁重建、chat 为空但已有连续追问、artifacts 缺失

• ✅ SQLBot API 是否可达（HTTP 探活）
• ✅ query 成功/失败/空结果统计（在总览实现）
• ⬜ 默认 workspace/datasource 是否可解析（仅探活连通性）
• ⬜ 最近 SQLBot record 列表、chart 渲染成功率、CSV 生成成功率

从 artifacts/manifest.json 读取：

• ✅ 按用户、数据源、关键字、状态过滤
• ✅ 展开详情：执行 SQL、返回摘要、error_reason
• ✅ 用户别名配置（服务端持久化，多用户共享）

✅ 已实现 ⬜ 未实现

1. ✅ trace 参数：--trace-id、--trace-file、--no-emit-trace，未传时自动生成 trace_id
2. ✅ 结构化事件日志（JSONL）：写入 monitoring/sqlbot-events.jsonl，字段含 stage / status / error_kind / duration_ms 等
3. ✅ 执行阶段埋点：session_context.resolve / state.load / workspace.resolve / datasource.resolve / chat.start / question.stream / record.data.fetch / result.normalize / chart.plan / artifact.write_* / state.save / ask.finish
4. ✅ 错误分类标准化：config_error / auth_error / network_error / sqlbot_api_error / sql_execution_error / timeout / empty_result / artifact_error / state_error
5. ✅ ask 返回体新增 telemetry 字段：trace_id / started_at / finished_at / duration_ms / stage_durations_ms
6. ✅ artifact manifest：每次 ask 写 manifest.json，含 trace_id / session_key / question / workspace / datasource / chat_id / record_id / row_count / chart_kind / SQL 摘要 / 文件索引
7. ⬜ python3 sqlbot_skills.py health CLI 命令（当前仅面板侧做了 HTTP 探活）
8. ⬜ python3 sqlbot_skills.py session list 全量列表子命令（现只有 session show，面板直接读文件替代）
9. ✅ 隐私与脱敏：trace 不记录 API key / secret；SQL 仅在展开详情时显示

1. 请求追踪详情 → 关联 artifacts 文件：瀑布图下方增加 raw-result / chart.png / data.csv 链接或预览
2. SQLBot 健康 → workspace/datasource 可解析验证：调用 API 确认默认配置实际存在
3. sqlbot_skills.py health CLI 命令：本地一键健康自检，也可供面板调用
4. Session 视图异常检测增强：频繁重建、chat 为空但已有追问
5. P2 企微埋点：message_received / message_sent 阶段，需改动 OpenClaw 或企微 webhook 入口
6. Hermes POC：验证 WeCom 单聊 session 隔离，并实现 Hermes session -> SQLBot chat_id 绑定
7. SQLBot adapter 抽取：将 sqlbot_skills.py 中的 API client、错误分类、artifacts 和 trace 逻辑抽成 Hermes 可调用服务或 MCP wrapper

企业微信交互	OpenClaw 返回	SQLBot 查询结果

• corp-assistant-sqlbot-workflow.md — 完整工作流、状态流转、可观测性机制和验收清单
• hermes/README.md — Hermes 迁移初步设计、单聊 session 隔离和 SQLBot adapter 方案
• openclaw/skills/sqlbot-workspace-dashboard/README.md — skill 新特性说明（trace、error_kind、manifest）
• openclaw/skills/sqlbot-workspace-dashboard/reference.md — 命令快速参考
• Hermes WeCom Bot — Hermes 企业微信 Bot 接入说明
• SQLBot MCP Server — SQLBot MCP 调用说明