LQAgentWritePlatform — 项目结构文档

施工方案 AI 自动生成平台 — FastAPI + Celery + LangGraph + Milvus

目录树

LQAgentWritePlatform/
│
├── README.md                              # 项目说明与部署指南
├── requirements.txt                       # Python 依赖清单
├── run.sh                                 # Uvicorn 启动脚本（默认 8004 端口）
├── deploy_agent.sh                        # 一键部署脚本（git pull → build → deploy）
├── Dockerfile                             # 应用镜像（基于 base 镜像，仅复制源码）
├── Dockerfile.base                        # 基础镜像（Python 3.12-slim + 所有 pip 依赖）
├── .dockerignore                          # 构建排除文件
│
├── config/                                # 配置与资源
│   ├── config.ini                         # 运行时配置（数据库连接、密钥、端点）
│   ├── config.ini.template                # 配置模板（可提交到版本库）
│   ├── model_setting.yaml                 # 模型路由配置（功能→模型映射）
│   ├── prompt/                            # AI Prompt 模板
│   │   ├── intent_prompt.yaml             # 意图分类 Prompt
│   │   └── system_prompt.yaml             # 系统 Prompt
│   ├── sql/                               # 数据库初始化脚本
│   │   ├── doc_callback_task_id_table.sql # 文档回调任务表
│   │   ├── lq_db.sql                      # 数据库初始化
│   │   └── test.sql                       # 测试数据
│   └── yolo/                              # YOLO 模型权重
│       └── best.pt
│
├── core/                                  # 业务逻辑层
│   ├── base/                              # 通用基础设施
│   │   ├── progress_manager.py            # 任务进度追踪（Redis-backed）
│   │   ├── sse_manager.py                 # SSE（Server-Sent Events）统一管理器
│   │   └── workflow_manager.py            # 工作流提交与任务管理
│   └── construction_write/                # 施工方案编写业务
│       ├── component/
│       │   ├── milvus.py                  # Milvus 轻量条件查询工具
│       │   ├── outline_generator.py       # 大纲生成核心逻辑
│       │   ├── similar_fragment_service.py # 相似片段检索服务
│       │   └── state_models.py            # LangGraph 状态模型定义
│       └── workflows/
│           ├── agent.py                   # Agent 工作流入口（测试/预留）
│           └── outline_workflow.py        # LangGraph 大纲生成工作流
│
├── docker/                                # Docker 编排
│   └── docker-compose.yml                 # Redis + App 服务编排
│
├── foundation/                            # 基础设施层（可复用）
│   ├── ai/                                # AI 模型层
│   │   └── models/
│   │       ├── model_config_loader.py     # 从 YAML 加载模型配置
│   │       ├── model_handler.py           # 模型调用统一处理器
│   │       └── rerank_model.py            # Reranker 模型封装（预留未接入）
│   ├── database/                          # 数据库层
│   │   └── base/
│   │       └── vector/                    # 向量存储
│   │           ├── base_vector.py         # 抽象接口定义
│   │           ├── milvus_vector.py       # Milvus 实现（dense+sparse 混合搜索）
│   │           └── pg_vector.py           # PostgreSQL pgvector 实现
│   ├── infrastructure/                    # 基础设施
│   │   ├── cache/                         # 缓存与锁
│   │   │   ├── redis_config.py            # Redis 配置
│   │   │   ├── redis_connection.py        # Redis 连接池
│   │   │   ├── async_redis_lock.py        # 异步分布式锁
│   │   │   └── redis_lock.py             # 同步分布式锁
│   │   ├── config/
│   │   │   └── config.py                  # INI 配置读取单例（config_handler）
│   │   ├── messaging/                     # 消息队列
│   │   │   ├── celery_app.py              # Celery 应用定义
│   │   │   └── tasks.py                   # Celery 任务定义
│   │   └── tracing/                       # 链路追踪
│   │       ├── trace_context.py           # Trace ID 上下文
│   │       └── celery_trace.py            # Celery Trace 传播
│   ├── observability/                     # 可观测性
│   │   ├── logger/
│   │   │   └── loggering.py               # 结构化日志配置（文件轮转）
│   │   └── monitoring/
│   │       └── time_statistics.py         # 耗时统计工具
│   └── utils/                             # 工具函数
│       ├── common.py                      # 通用工具
│       ├── md5.py                         # MD5 哈希
│       ├── redis_utils.py                 # Redis 辅助函数
│       ├── tool_utils.py                  # 杂项工具
│       └── yaml_utils.py                  # YAML 解析辅助
│
├── logs/                                  # 运行日志（自动生成）
│   ├── agent_debug.log
│   ├── agent_info.log
│   ├── agent_warning.log
│   └── construction_write/
│       ├── celery_worker.err.log
│       ├── celery_worker.out.log
│       ├── construction_write_debug.log
│       ├── construction_write_info.log
│       └── construction_write_warning.log
│
├── server/                                # 服务入口
│   └── app.py                             # FastAPI 应用创建、路由注册、CORS、Celery 生命周期
│
└── views/                                 # HTTP API 路由层
    ├── construction_write/
    │   ├── outline_views.py               # 大纲生成、重生成、任务管理、上下文生成
    │   ├── content_completion.py          # 内容补全 API（续写/扩写/润色/补全）
    │   └── similar_plan_recommend.py      # 相似片段检索 API

API 接口总览

所有业务接口均挂载在 /sgbx 前缀下。

通用接口

方法	路径	说明
GET	`/health`	服务健康检查
GET	`/celery/status`	Celery Worker 状态

大纲管理（`outline_views.py`）

方法	路径	说明	响应
POST	`/sgbx/generating_outline`	SSE 流式生成大纲	SSE
POST	`/sgbx/regenerate_outline`	SSE 流式重新生成指定章节	SSE
POST	`/sgbx/task_cancel`	取消运行中的任务	JSON
GET	`/sgbx/task_status`	查询任务状态	JSON
GET	`/sgbx/active_tasks`	列出所有活跃任务	JSON

上下文/内容生成（`outline_views.py` + `content_completion.py`）

方法	路径	说明	响应
POST	`/sgbx/context_generate`	SSE 流式生成段落内容	SSE
GET	`/sgbx/context_generate_health`	上下文生成健康检查	JSON
GET	`/sgbx/context_generate_modes`	列出可用模式（续写/扩写/润色/补全）	JSON
POST	`/sgbx/content_completion`	SSE 流式内容补全（独立端点）	SSE
GET	`/sgbx/content_completion_health`	内容补全健康检查	JSON
GET	`/sgbx/content_completion_modes`	列出补全模式	JSON

相似片段检索（`similar_plan_recommend.py`）

方法	路径	说明	响应
POST	`/sgbx/similar_fragment_search`	Milvus 混合检索相似片段	JSON
GET	`/sgbx/similar_fragment_search_health`	检索服务健康检查	JSON

核心模块说明

1. `server/app.py` — 应用入口

创建 FastAPI 实例，配置 CORS 中间件
注册所有路由模块（outline / content_completion / similar_fragment）
通过 lifespan 钩子管理 Celery Worker 的自动启停
提供 /health 和 /celery/status 工具接口

2. `core/base/` — 通用基础能力

模块	职责
`progress_manager.py`	Redis-backed 进度管理，Redis 不可用时降级为内存存储
`sse_manager.py`	SSE 连接管理，按任务 ID 路由事件到对应客户端
`workflow_manager.py`	Celery 任务提交、进度查询、结果获取的统一编排层

3. `core/construction_write/` — 施工方案业务

模块	职责
`component/outline_generator.py`	大纲生成核心：模板加载、并发章节生成、进度追踪
`component/similar_fragment_service.py`	相似片段检索：两阶段 pipeline（混合召回 → parent_id 聚合）
`component/milvus.py`	Milvus 轻量条件查询（`condition_query`），按 `parent_id` 回查全文
`workflows/outline_workflow.py`	LangGraph 状态机：初始化 → 加载模板 → 生成大纲 → 推荐案例 → 关联知识库 → 完成

4. `foundation/` — 基础设施层

子模块	职责
`ai/models/`	LLM 调用：支持多模型路由（DashScope/蜀天/豆包/本地），Embedding、Reranker 封装
`database/base/vector/`	向量存储：Milvus（dense+sparse 混合）+ PostgreSQL pgvector 两套实现
`infrastructure/cache/`	Redis 连接池 + 分布式锁（同步/异步）
`infrastructure/config/`	INI 配置读取单例，支持 `${ENV_VAR}` 变量展开
`infrastructure/messaging/`	Celery 异步任务框架，支持 Windows `--pool=solo`
`infrastructure/tracing/`	请求级 Trace ID，自动传播至 Celery 任务
`observability/`	结构化日志（文件轮转 10MB/5 备份）+ 耗时统计
`utils/`	MD5、Redis 辅助、YAML 解析、通用工具

5. `config/` — 配置管理

文件	说明
`config.ini`	运行时配置：数据库连接、Redis、Milvus、API 密钥、日志级别
`config.ini.template`	配置模板，不含敏感信息，可提交到版本库
`model_setting.yaml`	功能到模型的路由映射（文档分类/完整性审查/RAG/语法检查等各有专用模型）
`prompt/*.yaml`	AI Prompt 模板（意图分类 + 系统提示词）

技术栈

类别	技术
Web 框架	FastAPI + Uvicorn
异步任务	Celery（Redis broker）
工作流	LangGraph
向量数据库	Milvus（dense embedding + BM25 sparse 混合搜索）
缓存/消息	Redis
LLM	通义千问 Qwen3.5 系列 / 蜀天算力 / 豆包 / DeepSeek
Embedding	Qwen3-Embedding-8B
Reranker	BGE-reranker-v2-m3 / Qwen3-Reranker-8B（预留未接入）
部署	Docker Compose（base 镜像 + 应用镜像两阶段构建）

部署架构

外部请求
    │
    ▼
端口 18004 ──► Docker 容器 (8004) ──► FastAPI + Uvicorn
    │                                      │
    ├── outline_generation (Celery async) ─┤
    ├── content_completion (SSE stream)    │
    └── similar_fragment_search (Milvus) ──┤
                                           │
Redis ◄──────── 任务状态 / 缓存 / 分布式锁
Milvus ◄─────── 向量检索（dense+sparse 混合）

镜像构建流程：

Dockerfile.base → lq-agent-base:latest（预装所有 pip 依赖，仅在 requirements.txt 变化时重建）
Dockerfile → lq_agent_write_platform_server_dev:vX.XX（基于 base 镜像复制源码，秒级构建）

一键部署： 执行 deploy_agent.sh → git pull → 停容器 → 构建镜像 → 更新 compose 版本号 → 启动

README_PROJECT.md 12 KB Állandó hivatkozás Előzmények Nyers

LQAgentWritePlatform — 项目结构文档

目录树

API 接口总览

通用接口

大纲管理（outline_views.py）

上下文/内容生成（outline_views.py + content_completion.py）

相似片段检索（similar_plan_recommend.py）

核心模块说明

1. server/app.py — 应用入口

2. core/base/ — 通用基础能力

3. core/construction_write/ — 施工方案业务

4. foundation/ — 基础设施层

5. config/ — 配置管理

技术栈

部署架构

README_PROJECT.md 12 KB

Állandó hivatkozás Előzmények Nyers

大纲管理（`outline_views.py`）

上下文/内容生成（`outline_views.py` + `content_completion.py`）

相似片段检索（`similar_plan_recommend.py`）

1. `server/app.py` — 应用入口

2. `core/base/` — 通用基础能力

3. `core/construction_write/` — 施工方案业务

4. `foundation/` — 基础设施层

5. `config/` — 配置管理