data-query-agent

Data Query Agent

一个通过飞书长连接接收自然语言、使用 Codex SDK 编写 MaxCompute SQL、执行只读查询并自动发布飞书在线表格的 Python 服务。

功能

• 飞书 WebSocket 长连接，无需公网回调地址。
• 每个“聊天类型 + chat_id + 用户 open_id”独立保留 Codex 多轮线程。
• new/clear/help/skills 命令及对应 /、中文别名。
• Codex 自动选择并完整加载仓库内 Skill；优先复用 Skill SQL、模板和确定性脚本，通用探索再生成 SQL。
• SQL AST 只读校验、项目白名单、分区条件检查、超时和最多行数限制。
• 查询成功后生成 CSV/XLSX，并导入为企业内链接可读的飞书电子表格。
• SQLite 只保存会话、消息去重和运行元数据；查询结果保存在 runtime/runs/。

快速开始

cd /Users/liulidong/project/data_query_agent
cp .env.example .env            # 本工程首次创建时已按授权尝试迁移参考工程凭证
vim .env                        # 补齐缺失项，尤其是白名单
./scripts/setup.sh
./scripts/check.sh              # 只读检查飞书、ODPS 和 Codex/OpenRouter
./scripts/start.sh
./scripts/status.sh

日志在 logs/service.log。停止或重启：./scripts/stop.sh、./scripts/restart.sh。

如果 ./scripts/check.sh 在 OpenRouter 步骤返回 401 User not found，请在 .env 中替换 OPENROUTER_API_KEY；再运行检查，三项均为 OK 后启动服务。

飞书后台配置

应用必须是企业自建应用，启用机器人能力，并在“事件与回调”中选择长连接、订阅 im.message.receive_v1。给应用开通收发消息、获取机器人信息、上传文件、云文档导入与权限管理所需权限。只处理白名单群中真正 @ 当前机器人的消息；群内用户不另设白名单，私聊不处理。

运行边界

默认 OpenRouter provider 使用 Responses API，模型为 openai/gpt-5.6-terra。Codex 仅使用只读文件工具加载 Skill、SQL 模板和业务参考，禁止读取 .env、runtime 和日志；它只继承模型 provider 密钥，不继承 ODPS 和飞书凭证。ODPS 查询、Skill 脚本和飞书发布均由 Python 主服务执行，ODPS 账户仍应配置为只读权限。