# LQAgentWritePlatform 优化记录

> 更新日期：2026-05-19

## 已完成

### 1. 取消任务链路统一

`views/construction_write/outline_views.py` 已去掉取消任务时的硬编码 Redis 连接，不再写入 `terminate:{task_id}` 和 `progress:{task_id}` 这两套临时 key。

现在大纲任务统一使用：

- `current:{task_id}`：进度快照
- `stream_events:{task_id}`：章节流式事件
- `outline_write:result:{task_id}`：任务结果
- `outline_write:terminate_signal:{task_id}`：取消信号

### 2. Redis URL 特殊字符兼容

以下位置已对 Redis 密码做 URL 编码，避免密码包含 `@`、`#` 等字符时连接串解析失败：

- `foundation/infrastructure/cache/redis_config.py`
- `foundation/infrastructure/messaging/celery_app.py`
- `core/base/progress_manager.py`

### 3. Celery worker 状态可观测性增强

`server/app.py` 已增强自动 worker 管理：

- worker 启动后会快速检查是否立即退出
- `/celery/status` 返回启动命令、日志路径、退出码、最近错误
- `/health` 在自动 worker 预期运行但未运行时返回 `degraded`
- Docker 中通过 `AUTO_START_CELERY_WORKER=False` 关闭 API 内自动拉起 worker

### 4. Docker Compose 拆分 API 和 Worker

`docker/docker-compose.yml` 已修正 YAML 结构，并拆为：

- `lqRedis`
- `LQAgentWriteServer`
- `LQAgentWriteWorker`

生产部署建议使用独立 worker 服务，本地调试可继续使用 API 自动启动 worker。

### 5. 端口和配置段补齐

- `config/config.ini.template` 的 `LAUNCH_PORT` 已统一为 `8004`
- `REDIS_HOST` 已对齐 Docker 服务名 `lqRedis`
- `config/config.ini` 和模板均补充 `[construction_write]`

### 6. 运行产物忽略

`.gitignore` 已补充：

- `logs/`
- `__pycache__/`
- `*.pyc`
- `.env`
- 虚拟环境与 IDE 目录

## 待继续优化

### 1. `content_completion.py` 重复代码收敛

`views/construction_write/shared_api_utils.py` 已存在，但 `content_completion.py` 仍保留一套重复的 DashScope 调用、Redis 初始化、SSE 工具函数。

建议下一步将其改为复用 `shared_api_utils.py`，只保留请求模型、prompt 构造和路由。

### 2. `requirements.txt` 依赖收敛

当前依赖文件仍偏大，并存在未固定版本或重复约束，例如 Celery 相关包未锁定、`numpy` 有重复约束。

建议按施工方案编写服务实际功能重新冻结一版最小依赖。

### 3. 运行实例端口治理

本地调试时避免同时启动多个端口实例。建议固定使用：

- API 内部端口：`8004`
- Docker 外部端口：`18004`

### 4. Reranker 入口统一

`model_setting.yaml` 中列出了 `shutian_qwen3_reranker`，但当前 rerank 主要走 `foundation/ai/models/rerank_model.py` 的独立入口。

建议后续统一到 `model_handler` 或在文档中明确 rerank 的独立调用方式。