# AGENTS.md —— 协作约束（科研审稿模块）

## 项目背景

本项目（PlantAI-rag-new）是植物基因组学文献知识工作台，拥有自研 RAG 与知识库
（Qdrant + Neo4j + vstore）。2026-10 起新增「科研投稿与智能审稿助手」功能
（审稿周期/期刊分析/期刊推荐/投稿前自审/审稿意见辅助/格式检查）。

## 审稿模块（review_service）约束 —— 必须遵守

1. **所有审稿相关新代码只允许写在 `review_service/` 目录下新增**。
   - 服务自身：FastAPI 独立进程，端口 8100（模式同 `paper_writer_service` 8097 / `bioflow_service` 8098）。
   - 环境变量前缀统一 `REVIEW_`；LLM 凭据复用 `DOCGEN_LLM_*` 裸键（回退链见 `review_service/app/services/llm.py`）。
2. **BFF（`sdk/`）层只允许条件注册代理路由**：
   - 允许的全部改动 = `sdk/app/config.py` 增加 `review_enabled` / `review_service_url` 等开关键
     + `sdk/app/main.py` 按开关 `include_router(review_proxy.router)`
     + 新文件 `sdk/app/routers/review_proxy.py`（反代实现）。
   - **严禁**修改 sdk 下其他 router/service/db 的任何既有逻辑。
3. **严禁修改现有 RAG 核心与既有服务代码**，包括但不限于：
   - `agent/`（qa 8091 / methodology 8092 / legacy-rag 8093）
   - `vstore/`（8094，审稿服务只经 HTTP 只读消费其 `/api/vstore/*` 接口）
   - `paper_writer_service/`、`bioflow_service/`、`bioflow_kernel/`
   - `ui/`（前端入口另行按 UI_SPEC 流程评审）
   - `knowledge/`、`kb-libraries/`、`tooling/`（依赖锁另议）
4. **依赖纪律**：审稿服务只使用统一 venv（`tooling/requirements.lock`）中已有的库
   （fastapi / httpx / pydantic-settings 等）。如确需新增全局依赖，
   须先更新 `tooling/requirements.lock` 并经人工确认。
5. **上游对接只读**：PDF 解析走 vstore 8094（`POST /api/vstore/ingest` +
   `GET/DELETE /api/vstore/documents/{id}`）；LLM 走 DeepSeek OpenAI 兼容接口；
   后续期刊数据/期刊推荐等子功能同样以新 service + 新路由在 `review_service/` 内扩展。
6. **format_check 例外**：format_check 允许用 pymupdf 本地解档获取版式元数据
   （字体/边距/行距/页数），因为 vstore 只回文本不返回版式信息。正文提取仍走 vstore。

## 目录速览（审稿模块）

```
review_service/
├── app/main.py                 # FastAPI 入口（/health + 挂载业务路由）
├── app/config.py               # pydantic-settings（REVIEW_ 前缀）
├── app/routers/presubmit.py    # POST /api/review/presubmit（自审稿报告）
├── app/routers/format_check.py # POST /api/review/format-check（版式与规范检查）
├── app/services/llm.py         # DeepSeek httpx 封装（complete_text/complete_json）
├── app/services/paper_parse.py # PDF → 纯文本（经 vstore 解析接口）
├── app/services/format_check.py# 版式规则引擎（pymupdf/docx 本地解档 + 规则检查）
├── restart.sh                  # 8100 重启脚本
└── pytest.ini
```

## 启动

```bash
cd review_service && bash restart.sh   # 默认 8100，venv 从 ../plantai-rag-new-venv 推导
# BFF 开关：sdk/.env 加 REVIEW_ENABLED=1 后 bff_restart（反代 /api/review/*）
```