Skip to content
BranchesTags
 
 

Repository files navigation

GEO_Claw

OpenClaw 多智能体平台，服务于 GEO 品牌分析。姊妹产品：GEO_Agent（Web Chat SaaS）。

本仓库包含两条独立产品线，共用 OpenClaw Gateway，但入口、数据流、部署方式不同：

产品线 用途 入口
Chat MAS 飞书 / WebChat 多租户对话分析 control_plane/ + OpenClaw geo-analyst
Batch Pipeline 批量生产 Query / Response / Metrics（源自 QASystem） Celery + OpenClaw geo-query-craft / qa-response-annotate

两条线不共享租户鉴权；仅共用 ximuGEO 生产 PostgreSQL（Chat 只读，Pipeline 读写 geo_db schema）。

系统架构

                         ┌─────────────────────────────────────────┐
                         │         OpenClaw Gateway :18789          │
                         │  skills: geo-analyst | geo-query-craft |    │
                         │          qa-response-annotate            │
                         └───────────────┬─────────────────────────┘
                                         │ HTTP /v1/chat/completions
              ┌──────────────────────────┼──────────────────────────┐
              │                          │                          │
    ┌─────────▼─────────┐    ┌───────────▼──────────┐    ┌────────▼────────┐
    │  control_plane    │    │  python_bridge MCP   │    │ geo_claw/       │
    │  FastAPI :8100    │    │  (stdio → GEO tools) │    │ pipeline/       │
    │  租户 / 简报 / 桥接 │    │                      │    │ Celery Worker   │
    └─────────┬─────────┘    └───────────┬──────────┘    └────────┬────────┘
              │                          │                          │
    ┌─────────▼─────────┐    ┌───────────▼──────────┐    ┌────────▼────────┐
    │ geo_claw/tools/geo│    │ crews/ + skills/     │    │ Redis 队列       │
    │ STI / 可见度 / 洞察│    │ Agent 人格与任务指令  │    │ pending_products │
    └─────────┬─────────┘    └──────────────────────┘    │ pending_queries  │
              │                                          └────────┬────────┘
    ┌─────────▼─────────┐                                         │
    │ GEO_DB (只读)      │                              ┌──────────▼──────────┐
    │ ximuGEO 生产库     │                              │ DB (读写) geo_db     │
    └───────────────────┘                              │ product_queries /    │
                                                       │ query_responses /    │
                                                       │ brand_metrics        │
                                                       └─────────────────────┘

Batch Pipeline 数据流（详见 docs/PIPELINE.md）：

网站推送产品 → pending_products
    → [Task 2] 竞品发现 → OpenClaw 生成 Query → Probe 质检 → product_queries → pending_queries
    → [Task 3] LLM 采集 Response → 标注（OpenClaw + 幻觉校验）→ 指标聚合 → PostgreSQL
    ↑
[Task 1] 每日 cron：active queries 重新入队 pending_queries

目录说明

根目录

路径 说明
README.md 本文件：总览、目录索引、快速启动
.env / .env.example 运行时密钥与配置模板（控制面 + Pipeline + OpenClaw）
requirements.txt Python 依赖
celery_app.py Celery CLI 薄封装 → geo_claw.pipeline.celery_app
Dockerfile 控制面镜像（uvicorn :8100）
docker-compose.yml 全栈：postgres、redis、control-plane、celery worker/beat
openclaw.version 锁定的 OpenClaw npm 版本

geo_claw/ — 核心 Python 包

路径 说明
core/ 控制面配置（config.py）、租户上下文、ximuGEO 只读库（geo_db.py）、Redis
tools/geo/ Chat 侧 GEO 分析工具（STI、可见度、竞品、洞察）；自 GEO_Agent 同步的副本
agent/ Agent 回复引用（citation）辅助
briefing/ 竞品情报定时简报生成逻辑
pipeline/ 批量数据生产（QASystem 移植），见下表

geo_claw/pipeline/ — 批量流水线

路径 说明
settings.py Pipeline 专用环境变量（与 core/config.py 分离）
database.py Pipeline 写库 PostgreSQL 客户端
pending_queues.py Redis 队列：pending_products、pending_queries
celery_app.py / beat_schedule.py Celery 应用与 3 个定时/轮询任务
tasks/ Celery 任务入口（见 任务一览）
queries/ Query 生成：competitor_discovery → openclaw_generator → query_probe
responses/ Response 采集（collector）、标注（annotator + annotation_verify）、聚合（aggregator、daily_metrics_calculator）
tools/ Pipeline 专用工具：OpenAI 重试、域名解析、Perplexity、多 LLM 提供商
openclaw_bridge/ OpenClaw Gateway HTTP 客户端

control_plane/ — Chat 控制面

FastAPI 应用（:8100）：多租户管理、飞书渠道绑定、GEO 工具 HTTP 桥接、简报 Web UI（/briefs）。

python_bridge/ — MCP 桥

mcp_server.py：stdio MCP 服务，将 geo_claw/tools/geo 暴露给 OpenClaw 会话。

crews/ + skills/ — OpenClaw 智能体

Crew（crews/*/AGENTS.md） Skill（skills/*/SKILL.md） 用途
main — 根 Agent
geo-analyst geo-analyst Chat：品牌 STI / 可见度 / 洞察分析
competitor-intel — 定时竞品简报（HEARTBEAT.md + tenants.json）
geo-query-craft geo-query-craft Pipeline：GEO 提问工坊 — Query 生成 + Probe 修订
qa-response-annotate qa-response-annotate Pipeline：Response 品牌标注 + 反幻觉审计

scripts/setup-crew.sh 将 crews/skills 同步到 ~/.openclaw/workspace-geo-claw。
注册表：crews/index.md。

config-templates/

openclaw.json 模板：Gateway 端口、Token 鉴权、Feishu 渠道、Skill 注册。由 scripts/setup_openclaw_config.py 渲染到 ~/.openclaw/openclaw.json。

scripts/ — 运维与测试脚本

脚本 用途
install.sh 一键安装：venv、pip、OpenClaw npm、配置、crews
dev.sh 启动控制面（uvicorn :8100）
setup-crew.sh 同步 crews/skills 到 OpenClaw workspace
setup_openclaw_config.py 渲染 OpenClaw 配置
start_pipeline.sh / stop_pipeline.sh Celery beat + worker 启停
setup_briefing_cron.sh 竞品简报 cron
run_all_tests.sh 全量测试
smoke_openclaw_queries.py 仅测 Query 生成（不经 Celery）
smoke_api.sh / smoke_geo_tools.py 控制面 / GEO 工具冒烟
compare_annotation_hallucination.py 标注幻觉与 token 对比
run_competitor_intel.py 手动触发竞品情报 crew
celery/log_rotator.sh Celery 日志按日轮转

tests/ — 自动化测试

路径 说明
test_*.py 单元测试（probe、竞品发现、OpenClaw 集成等）
smoke/ 端到端冒烟：push_pending_product.py、pending_product_pipeline.py

docs/ — 专题文档

文档 内容
ARCHITECTURE.md 架构详解、双库模型、设计决策
PIPELINE.md 批量流水线：任务、队列、QASystem 对照
OPENCLAW_SETUP.md OpenClaw 安装与 Gateway 配置
FEISHU_SETUP.md 飞书渠道接入
MULTI_TENANCY.md 多租户模型
BRIEFING.md 竞品情报简报
PRODUCT_LINES.md GEO_Agent vs GEO_Claw 定位

运行时数据（不入库 / 本地生成）

路径 说明
brand-context/ 各租户 BRAND.md 与简报输出
data/ 控制面 SQLite（本地开发）
logs/ Pipeline 日志与 smoke 报告 JSON

docker/ — Pipeline 独立部署

docker/docker-compose.yml：仅 Celery worker + beat，通过 host.docker.internal 访问宿主机 OpenClaw。与根目录全栈 docker-compose.yml 二选一。

Celery 任务

# 任务 触发 作用
1 load_active_queries_to_pending_queries_queue 每日 cron 将 PG 中 active queries 推入 pending_queries
2 generate_queries_from_pending_products 轮询 pending_products → 竞品发现 → OpenClaw → Probe → DB
3 generate_responses_and_calculate_metrics_from_pending_queries 轮询 pending_queries → 采集 → 标注 → 指标 → DB（单事务）

快速启动

Chat MAS（飞书对话）

./scripts/install.sh
cp .env.example .env          # 填写 GEO_DB_*、FEISHU_*、OPENCLAW_GATEWAY_TOKEN
./scripts/dev.sh              # 控制面 :8100
openclaw gateway --config ~/.openclaw/openclaw.json

详见 docs/OPENCLAW_SETUP.md、docs/FEISHU_SETUP.md。

Batch Pipeline（数据生产）

openclaw gateway --force      # Query 生成 / 标注必需
bash scripts/start_pipeline.sh
python tests/smoke/pending_product_pipeline.py --num-queries 3

详见 docs/PIPELINE.md。

测试

GEO_CLAW_FAKE_REDIS=1 ./scripts/run_all_tests.sh

环境变量速查

分组 关键变量 读取位置
控制面 CONTROL_PLANE_*、FEISHU_*、TOOL_BRIDGE_TOKEN geo_claw/core/config.py
GEO 只读库 GEO_DB_HOST/PORT/NAME/USER/PASSWORD geo_claw/core/geo_db.py
Pipeline 写库 DB_*（未设则回退 GEO_DB_*） geo_claw/pipeline/settings.py
Celery CELERY_BROKER_URL、CELERY_RESULT_BACKEND（Redis DB /2） geo_claw/pipeline/settings.py
OpenClaw OPENCLAW_GATEWAY_URL、OPENCLAW_GATEWAY_TOKEN 两处 settings
Query 生成 QUERY_PROBE_MODEL、QUERY_MAX_REVISION_ROUNDS pipeline/settings.py
标注 ANNOTATOR_USE_OPENCLAW、ANNOTATOR_VERIFY_MENTIONS pipeline/settings.py

完整列表见 .env.example。

主动简报

http://127.0.0.1:8100/briefs · docs/BRIEFING.md

About

OpenClaw Multi-Agent GEO platform (Feishu/WebChat)

Resources

Readme
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Contributors

Languages