feat(core): finalize rvw stability updates and pending module changes
Summary: - Harden RVW prompt protocol handling and methodology review flow with 20-checkpoint coverage, divide-and-conquer execution, and timeout tuning - Update RVW frontend methodology report rendering to show real structured outputs and grouped checkpoint sections - Include pending backend/frontend updates across IIT admin, SSA, extraction forensics, and related integration files - Sync system and RVW status documentation, deployment checklist, and RVW architecture/plan docs Validation: - Verified lint diagnostics for touched RVW backend/frontend files show no new errors - Kept backup dump files and local test artifacts untracked Made-with: Cursor
This commit is contained in:
@@ -1,10 +1,11 @@
|
||||
# AIclinicalresearch 系统当前状态与开发指南
|
||||
|
||||
> **文档版本：** v6.9
|
||||
> **文档版本：** v7.0
|
||||
> **创建日期：** 2025-11-28
|
||||
> **维护者：** 开发团队
|
||||
> **最后更新：** 2026-03-09
|
||||
> **最后更新：** 2026-03-13
|
||||
> **🎉 重大里程碑：**
|
||||
> - **🆕 2026-03-13：RVW 方法学稳定性增强（V3.0.2）！** 方法学 20 检查点结构化增强 + A/B/C 分治并行评估 + 规则汇总器统一结论 + 前端展示口径收敛（按三大项分组展示检查点）
|
||||
> - **🆕 2026-03-09：认证模块接入阿里云短信验证码！** 登录验证码链路支持 `mock/aliyun` 双模式 + 后端短信服务封装 + 独立联调脚本（`npm run test:sms`）+ 实机发送验证通过
|
||||
> - **🆕 2026-03-08：SSA 智能统计分析 Agent 模式 MVP 完成！** Agent 核心 Prompt 接入运营管理端（PlannerAgent + CoderAgent 动态化 + 三级容灾）+ Phase 5A 防错护栏 + Prompt 全景盘点（Agent 仅用 2 个 Prompt，QPER 11 个已归档）
|
||||
> - **🆕 2026-03-07：SSA Agent 通道体验优化 + Plan-and-Execute 架构设计完成！** 方案 B 左右职责分离 + 10 项 Bug 修复（JWT 刷新/代码截断/重试流式/R Docker 结构化错误/进度同步/导出按钮）+ 分步执行架构评审通过（代码累加策略 + 5 项工程护栏）
|
||||
@@ -38,6 +39,7 @@
|
||||
> - **2026-01-22：OSS 存储集成完成！** 阿里云 OSS 正式接入平台基础层
|
||||
>
|
||||
> **🆕 最新进展（含认证短信集成 2026-03-09）：**
|
||||
> - ✅ **🆕 RVW 方法学稳定性增强（V3.0.2）** — `checkpoints` 结构化输出（20项）+ 方法学 A/B/C 分治并行评估（1-9/10-14/15-20）+ 规则汇总器统一 `summary/conclusion` + 前端展示按三大项分组
|
||||
> - ✅ **🆕 认证短信验证码接入完成** — `sendVerificationCode` 接入阿里云短信网关（保留 `mock`）+ 发送成功后再落库验证码 + 环境变量校验 + 联调脚本 `test:sms` + 实机发送验证通过
|
||||
> - ✅ **🆕 SSA Agent 模式 MVP 完成** — Agent 核心 Prompt 接入运营管理端（`SSA_AGENT_PLANNER` + `SSA_AGENT_CODER` 动态化）+ 三级容灾（DB→缓存→fallback）+ 种子脚本幂等写入 + Prompt 全景盘点（Agent 2 个 / QPER 11 个归档）
|
||||
> - ✅ **🆕 SSA Agent 通道体验优化（12 文件, +931/-203 行）** — 方案 B 左右职责分离 + JWT 刷新 + 代码截断修复 + 重试流式生成 + R Docker 结构化错误（20+ 模式）+ Prompt 铁律 + 进度同步 + 导出按钮恢复 + ExecutingProgress 动态 UI
|
||||
@@ -96,7 +98,7 @@
|
||||
| **IIT** | IIT Manager Agent | CRA Agent - LLM Tool Use + 自驱动质控 + 统一驾驶舱 | ⭐⭐⭐⭐⭐ | 🎉 **V3.1完成 + GCP报表 + Bug修复！** 质控引擎升级 + 4张GCP业务报表 + AI时间线增强 + 一键全量质控 | **P1-2** |
|
||||
| **SSA** | 智能统计分析 | **Agent 模式（PlannerAgent + CoderAgent + R Docker）** + QPER 备用 | ⭐⭐⭐⭐⭐ | 🎉 **Agent 模式 MVP 完成** — Prompt 运营管理化 + Phase 5A 护栏 + 体验优化 + Plan-and-Execute 架构设计，仅用 2 个核心 Prompt | **P1** |
|
||||
| **ST** | 统计分析工具 | 126 个轻量化统计工具（旧系统 iframe 嵌入） | ⭐⭐⭐⭐ | ✅ **旧系统集成完成** — Token 注入 + Wrapper Bridge + E2E 验证通过 | P2 |
|
||||
| **RVW** | 稿件审查系统 | 方法学评估 + 🆕数据侦探（L1/L2/L2.5验证）+ Skills架构 + Word导出 | ⭐⭐⭐⭐ | 🚀 **V2.0 Week3完成（85%）** - 统计验证扩展+负号归一化+文件格式提示+用户体验优化 | P1 |
|
||||
| **RVW** | 稿件审查系统 | 方法学评估 + 🆕数据侦探（L1/L2/L2.5验证）+ Skills架构 + Word导出 | ⭐⭐⭐⭐ | 🚀 **V3.0.2 进行中（90%）** - 方法学分治并行+20检查点结构化+展示收敛 | P1 |
|
||||
| **ADMIN** | 运营管理端 | Prompt管理、租户管理、用户管理、运营监控、系统知识库 | ⭐⭐⭐⭐⭐ | 🎉 **Phase 4.6完成（88%）** - Prompt知识库集成+动态注入 | **P0** |
|
||||
|
||||
---
|
||||
|
||||
@@ -1,10 +1,10 @@
|
||||
# RVW稿件审查模块 - 当前状态与开发指南
|
||||
|
||||
> **文档版本：** v6.1
|
||||
> **文档版本：** v6.2
|
||||
> **创建日期：** 2026-01-07
|
||||
> **最后更新：** 2026-03-10
|
||||
> **最后更新：** 2026-03-13
|
||||
> **维护者：** 开发团队
|
||||
> **当前状态：** 🚀 **V3.0.1 "性能与体验增强" 完成（4模块并行 + 增量展示 + 导出补全）**
|
||||
> **当前状态：** 🚀 **V3.0.2 "方法学稳定性增强" 进行中（分治并行 + 20检查点覆盖 + 展示口径收敛）**
|
||||
> **文档目的：** 快速了解RVW模块状态，为新AI助手提供上下文
|
||||
>
|
||||
> **🎉 V3.0 进展（2026-03-07）：**
|
||||
@@ -20,6 +20,13 @@
|
||||
> - ✅ **增量结果持久化**：每个 Skill 完成即写入任务中间结果，`getTaskDetail` 返回模块级 `reviewProgress`
|
||||
> - ✅ **先出先看**：TaskDetail 在审查中即可展示已完成模块（无需等待全流程结束）
|
||||
> - ✅ **Word 导出修复**：补齐“数据验证”章节，导出汇总 + 表格明细 + 该表问题列表
|
||||
>
|
||||
> **🆕 V3.0.2 进展（2026-03-13）：**
|
||||
> - ✅ **方法学 Prompt 动静分离收敛**：业务提示词继续走运营管理端，系统协议负责结构化输出
|
||||
> - ✅ **20检查点结构化增强**：方法学结果新增 `checkpoints`（id 1-20，状态与发现可追踪）
|
||||
> - ✅ **方法学分治并行评估（A/B/C）**：按 1-9 / 10-14 / 15-20 三段并行，降低整包超时概率
|
||||
> - ✅ **规则汇总器合并结果**：统一生成 `overall_score/summary/conclusion/checkpoints/parts`，并保留降级兜底
|
||||
> - ✅ **前端展示口径统一**：方法学报告按“三大项->检查点”展示，去除重复占位文案并显示真实LLM内容
|
||||
>
|
||||
> **V2.0 进展回顾：**
|
||||
> - ✅ L1 算术验证 + L2 统计验证 + L2.5 一致性取证
|
||||
@@ -40,7 +47,7 @@
|
||||
| **商业价值** | ⭐⭐⭐⭐⭐ 极高 |
|
||||
| **独立性** | ⭐⭐⭐⭐⭐ 极高（用户群完全不同） |
|
||||
| **目标用户** | 期刊初审编辑 |
|
||||
| **开发状态** | ✅ **V3.0.1 完成：4维审查并行提速 + 增量结果展示 + Word导出补全** |
|
||||
| **开发状态** | 🚀 **V3.0.2 进行中：方法学分治并行 + 20检查点覆盖展示 + 超时优化** |
|
||||
|
||||
### 核心目标
|
||||
|
||||
@@ -463,6 +470,17 @@ Content-Type: multipart/form-data
|
||||
| 前端先出先看 | ✅ 已完成 | 审查过程中实时展示已完成 Tab |
|
||||
| Word 导出补齐数据验证 | ✅ 已完成 | 导出包含数据验证汇总、表格明细、该表问题列表 |
|
||||
|
||||
### 🆕 V3.0.2 "方法学稳定性增强" 开发进度（2026-03-13）
|
||||
|
||||
| 任务 | 状态 | 说明 |
|
||||
|------|------|------|
|
||||
| 方法学 `checkpoints` 扩展 | ✅ 已完成 | 结果结构支持 20 检查点逐项状态与发现 |
|
||||
| 方法学前端展示收敛 | ✅ 已完成 | 采用“三大项分组 + 检查点明细”，移除重复占位展示 |
|
||||
| 方法学分治并行评估 | ✅ 已完成 | A/B/C 三段并行执行（1-9/10-14/15-20） |
|
||||
| 方法学规则汇总器 | ✅ 已完成 | 合并分段结果并统一结论；分段失败可降级 |
|
||||
| 方法学超时窗口扩展 | ✅ 已完成 | MethodologySkill 超时从 5min 调整到 8min |
|
||||
| 快速模式开关（后续） | ⏳ 规划中 | 长文档自动降耗与更短输出预算 |
|
||||
|
||||
### 后续版本（V3.1+）
|
||||
|
||||
- [ ] 全面移除评分机制（只列问题，不打分）
|
||||
@@ -479,7 +497,7 @@ Content-Type: multipart/form-data
|
||||
|
||||
---
|
||||
|
||||
**文档版本：** v6.1
|
||||
**最后更新：** 2026-03-10
|
||||
**当前状态：** 🚀 V3.0.1 "性能与体验增强" 完成（4模块并行 + 增量展示 + 导出补全）
|
||||
**下一步：** V3.1 移除评分机制 + 单模块重试
|
||||
**文档版本：** v6.2
|
||||
**最后更新：** 2026-03-13
|
||||
**当前状态：** 🚀 V3.0.2 "方法学稳定性增强" 进行中（分治并行 + 20检查点覆盖 + 展示口径收敛）
|
||||
**下一步：** V3.0.2 收尾验证（超时率/覆盖率） + V3.1 单模块重试与评分策略优化
|
||||
|
||||
220
docs/03-业务模块/RVW-稿件审查系统/04-开发计划/RVW V4.0 智能审稿输出解耦开发计划.md
Normal file
220
docs/03-业务模块/RVW-稿件审查系统/04-开发计划/RVW V4.0 智能审稿输出解耦开发计划.md
Normal file
@@ -0,0 +1,220 @@
|
||||
# RVW V4.0 智能审稿输出解耦开发计划
|
||||
|
||||
> 文档版本：v1.1
|
||||
> 创建日期：2026-03-13
|
||||
> 维护者：RVW 模块开发组
|
||||
> 优先级：P0
|
||||
> 目标周期：2 阶段（P0: 1 周快速上线；P1: 2 周配置化增强）
|
||||
> 适用范围：方法学、稿约规范性、临床评估、数据验证四通道
|
||||
|
||||
---
|
||||
|
||||
## 1. 背景与目标
|
||||
|
||||
### 1.1 当前痛点
|
||||
|
||||
1. 运营端可编辑 Prompt 与系统 JSON 协议同时约束输出，存在格式冲突。
|
||||
2. 专家希望掌控最终报告呈现（A/B/C、1/2/3/4 等），但当前展示仍受通道实现细节影响。
|
||||
3. JSON 解析稳定性与专家自然语言表达存在天然张力。
|
||||
4. 运营发布后难以快速验证“是否真的生效”（缺少统一版本指纹与可观测性）。
|
||||
|
||||
### 1.2 V4.0 核心目标
|
||||
|
||||
构建“数据与展示分离”的稳定架构，并采用“先快后全”的实施策略：
|
||||
|
||||
- LLM 负责结构化评估数据（系统可解析、可存储、可统计）。
|
||||
- P0 先使用代码内置默认模板渲染专家报告，快速验证核心链路。
|
||||
- P1 再开放运营端模板配置（Handlebars），实现风格动态化。
|
||||
- 系统协议只负责结构约束，不覆盖业务判断。
|
||||
- 支持版本化、回滚、可观测，避免“看起来没生效”。
|
||||
|
||||
---
|
||||
|
||||
## 2. 方案边界与设计原则
|
||||
|
||||
### 2.1 In Scope（本期纳入）
|
||||
|
||||
- 四通道统一双轨输出：`structured_review` + `rendered_report_text`。
|
||||
- P0：后端新增“硬编码默认模板”渲染层与失败降级策略。
|
||||
- P1：运营端新增“报告模板”配置能力（DRAFT/ACTIVE/发布/回滚）。
|
||||
- 前端报告页与导出统一使用 `rendered_report_text` 展示。
|
||||
- 增加 Prompt/Template 版本指纹日志与排障接口。
|
||||
|
||||
### 2.2 Out of Scope（本期不纳入）
|
||||
|
||||
- 双 Agent Writer 高拟人化撰写链路（保留为后续增强）。
|
||||
- 全量替换所有模型适配器为单一厂商 Structured Outputs（先做兼容层）。
|
||||
- 复杂可视化模板编辑器（先不上，后续按运营反馈决定）。
|
||||
- P0 阶段不开放模板运营配置界面（先用代码默认模板快速上线）。
|
||||
|
||||
### 2.3 设计原则
|
||||
|
||||
1. 业务可变（运营可配）与协议稳定（研发固化）严格分层。
|
||||
2. 失败可降级但不可静默：所有 fallback 必须留痕并告警。
|
||||
3. 默认向后兼容：旧任务、旧报告不破坏。
|
||||
4. 能复用现有能力就不重复造轮子（PromptService、Handlebars、pg-boss、现有审查流程）。
|
||||
|
||||
---
|
||||
|
||||
## 3. 目标架构（V4.0）
|
||||
|
||||
## 3.1 双轨输出模型
|
||||
|
||||
- 结构化轨（系统轨）
|
||||
- 字段：`overall_score`、`conclusion`、`issues/parts/items` 等。
|
||||
- 用途：存库、统计、评分、后续机器处理。
|
||||
|
||||
- 展示轨（专家轨）
|
||||
- 字段：`report_text`（Markdown/纯文本）。
|
||||
- 来源：`report_template` + 结构化数据渲染。
|
||||
- 用途：前端展示、导出、人工审阅。
|
||||
|
||||
## 3.2 通道配置拆分
|
||||
|
||||
每个通道最终拆分为两份可配置资产（P1 落地）：
|
||||
|
||||
- `RVW_xxx_PROMPT`：专家评估标准（不含输出格式约束）。
|
||||
- `RVW_xxx_REPORT_TEMPLATE`：专家展示模板（Handlebars）。
|
||||
|
||||
系统保留一份研发固化协议：
|
||||
|
||||
- `RVW_PROTOCOL_xxx`：结构化字段 schema/协议约束（代码侧维护）。
|
||||
|
||||
---
|
||||
|
||||
## 4. 分阶段实施计划
|
||||
|
||||
## 4.1 Phase P0（Week 1）快速上线：硬编码默认模板 + 预留配置能力
|
||||
|
||||
目标：1 周内上线“稳定结构化 + 专家样式展示”的核心能力。
|
||||
|
||||
- 梳理四通道当前输入输出、协议、前端渲染路径。
|
||||
- 标记并移除“业务硬编码覆盖”点（仅保留协议校验/解析兜底）。
|
||||
- 新增 `reportRenderer` 服务，内置四通道默认模板（代码内维护）。
|
||||
- `reviewWorker` 汇总阶段写入 `rendered_report_text`。
|
||||
- 前端报告页与导出优先展示 `rendered_report_text`，旧数据兼容兜底。
|
||||
- 增加可观测字段：`promptVersion`、`promptFingerprint`、`render_fallback`。
|
||||
- 预留配置扩展点：模板来源抽象接口（先实现 `code` provider，后续接 `db` provider）。
|
||||
|
||||
交付物：
|
||||
|
||||
- `backend/src/modules/rvw/services/reportRenderer.ts`（默认模板模式）
|
||||
- 四通道渲染接入点
|
||||
- 前端展示/导出统一到展示轨
|
||||
- P0 上线验收报告与回滚脚本
|
||||
|
||||
## 4.2 Phase P1（Week 2-3）增强：运营端模板配置化
|
||||
|
||||
目标：在不改变 P0 主链路的前提下，实现模板动态可配、可发布、可回滚。
|
||||
|
||||
- 运营端 Prompt 管理增加四通道模板条目。
|
||||
- 模板版本流程：DRAFT 编辑 -> 预览渲染 -> 发布 ACTIVE -> 回滚。
|
||||
- `reportRenderer` 增加 `db` provider，并支持 provider 切换。
|
||||
- 增加“模板变量提示面板”（减少占位符写错）。
|
||||
- 增加模板指纹与版本审计：`templateVersion/templateFingerprint`。
|
||||
|
||||
交付物：
|
||||
|
||||
- 模板配置与发布流程可用
|
||||
- 模板预览页（输入样例 JSON 即时渲染）
|
||||
- 版本变更审计记录
|
||||
- P1 灰度发布与稳定性报告
|
||||
|
||||
---
|
||||
|
||||
## 5. 验收标准（分阶段）
|
||||
|
||||
### 5.1 P0 功能验收（快速上线门槛）
|
||||
|
||||
1. 四通道都能产出 `rendered_report_text`，并用于前端展示与导出。
|
||||
2. JSON 解析失败不影响最终展示（可读降级报告 + 告警）。
|
||||
3. 默认模板可输出专家认可的报告结构（如 1/2/3/结论）。
|
||||
4. 本阶段不依赖运营端模板配置即可上线。
|
||||
|
||||
### 5.2 P1 功能验收（配置化门槛）
|
||||
|
||||
1. 四通道可在运营端单独修改“展示模板”。
|
||||
2. 运营发布后，新任务可命中 ACTIVE 模板并产出对应格式报告。
|
||||
3. 模板从 A/B/C 改为 1/2/3/4，无需发版即可生效。
|
||||
|
||||
### 5.3 稳定性验收
|
||||
|
||||
1. 四通道 JSON 解析成功率 >= 99%（含修复链路）。
|
||||
2. 模板渲染失败率 < 1%，且全部可回退到默认模板。
|
||||
3. fallback 事件 100% 有日志与可追踪任务 ID。
|
||||
|
||||
### 5.4 可观测性验收
|
||||
|
||||
每次审稿必须可追溯：
|
||||
|
||||
- `promptVersion` / `promptFingerprint`
|
||||
- `templateVersion` / `templateFingerprint`（P1 生效）
|
||||
- `isDraft` / `render_fallback` / `protocol_repair_used`
|
||||
|
||||
---
|
||||
|
||||
## 6. 关键风险与应对
|
||||
|
||||
| 风险 | 影响 | 等级 | 应对 |
|
||||
|---|---|---|---|
|
||||
| 模板变量拼写错误导致渲染失败 | 报告显示异常 | 高 | P0 仅默认模板规避；P1 增加变量白名单 + 预览 + 默认模板降级 |
|
||||
| 多模型结构化能力差异 | JSON 不稳定 | 高 | 统一 schema 校验 + repair + 明确模型兼容矩阵 |
|
||||
| 历史任务缺少展示轨字段 | 页面兼容风险 | 中 | 前端双读逻辑（新字段优先，旧字段兜底） |
|
||||
| 运营频繁发布造成“版本感知混乱” | 排障困难 | 中 | 强制记录版本指纹并在任务详情可见 |
|
||||
|
||||
---
|
||||
|
||||
## 7. 回滚策略
|
||||
|
||||
1. 模板回滚：P0 使用代码版本回滚，P1 支持运营端一键回滚到上一 ACTIVE 版本。
|
||||
2. 服务回滚：保留旧展示拼装逻辑，Feature Flag 控制新渲染链路。
|
||||
3. 故障兜底：渲染失败自动走默认模板，不阻塞任务完成状态。
|
||||
4. 数据回滚：不删除结构化结果，仅切换展示来源。
|
||||
|
||||
---
|
||||
|
||||
## 8. 任务拆解（可直接进入排期）
|
||||
|
||||
### 后端（P0 先做）
|
||||
|
||||
- [ ] 新增 `reportRenderer` 服务（代码默认模板）
|
||||
- [ ] 四通道接入模板渲染与降级日志
|
||||
- [ ] 任务结果结构新增 `rendered_report_text`（含兼容）
|
||||
- [ ] 增加 `promptVersion/promptFingerprint/render_fallback` 日志
|
||||
- [ ] 预留模板 provider 扩展接口（`code` -> `db`）
|
||||
|
||||
### 前端（P0 先做）
|
||||
|
||||
- [ ] 任务详情优先展示 `rendered_report_text`
|
||||
- [ ] 导出链路切换至展示轨
|
||||
- [ ] 旧数据兼容兜底视图
|
||||
|
||||
### 后端/前端（P1 再做）
|
||||
|
||||
- [ ] 模板配置页支持预览与变量提示
|
||||
- [ ] 接入模板版本发布/回滚流程
|
||||
- [ ] 版本信息可视化（可选：调试面板）
|
||||
|
||||
### QA/运维
|
||||
|
||||
- [ ] 四通道回归测试用例补齐
|
||||
- [ ] 模板异常、fallback、回滚演练
|
||||
- [ ] 上线检查清单与告警看板更新
|
||||
|
||||
---
|
||||
|
||||
## 9. 里程碑
|
||||
|
||||
- M1（Week 1 结束）：P0 上线，四通道默认模板渲染可用，前端/导出展示轨打通。
|
||||
- M2（Week 2 结束）：P1 配置化开发完成并进入灰度。
|
||||
- M3（Week 3 结束）：P1 稳定上线，模板发布/回滚流程可用。
|
||||
|
||||
---
|
||||
|
||||
## 10. 版本记录
|
||||
|
||||
| 日期 | 版本 | 说明 |
|
||||
|---|---|---|
|
||||
| 2026-03-13 | v1.0 | 首版计划，确立“结构化评估 + 动态模板展示”双轨架构 |
|
||||
| 2026-03-13 | v1.1 | 调整为“P0 硬编码默认模板快速上线 + P1 模板配置化增强”两阶段策略 |
|
||||
|
||||
99
docs/03-业务模块/RVW-稿件审查系统/08-技术架构建议/智能审稿终极稳定架构白皮书.md
Normal file
99
docs/03-业务模块/RVW-稿件审查系统/08-技术架构建议/智能审稿终极稳定架构白皮书.md
Normal file
@@ -0,0 +1,99 @@
|
||||
# **智能审稿系统 \- LLM 输出格式隔离与终极稳定架构白皮书**
|
||||
|
||||
**文档目的：** 彻底解决大模型“自然语言排版”与“系统结构化解析”之间的抢占与冲突，提供可作为平台底层规范的长期稳定架构方案。
|
||||
|
||||
**适用场景：** RVW 智能审稿、AIA 报告生成、ASL 深度检索总结等一切需要“既要系统存数据，又要给用户看报告”的业务。
|
||||
|
||||
## **一、 问题本质：为什么大模型总会“格式崩盘”？**
|
||||
|
||||
大模型本质上是一个“词汇接龙”的概率引擎。当我们要求它\*\*“既做评判专家（逻辑分析），又做排版文秘（JSON转义与文本排版）”**时，它面临着严重的**职责过载 (Responsibility Overload)\*\*。
|
||||
|
||||
1. **Attention（注意力）稀释**：Prompt 中复杂的业务规则（20条标准）占用了大量的注意力权重，导致模型在生成到后半段时，往往会“忘记”输出合规的格式。
|
||||
2. **JSON 转义灾难**：如果采用“将长文本报告塞入 JSON 字段”的做法，模型需要在生成长文本时，对每一个回车换行（\\n）、双引号（\\"）进行严格的转义。一旦模型在几千字中漏掉一个转义符，前端 JSON.parse() 就会直接崩溃。
|
||||
|
||||
## **二、 终极演进方向：大模型的 MVC 架构 (LLM-MVC)**
|
||||
|
||||
软件工程中解决耦合的终极方案永远是**分层**。我们需要将大模型的工作流拆分为 **Model（数据层）**、**View（展示层）** 和 **Controller（控制层）**。
|
||||
|
||||
* **Model (判官)**：彻底剥离排版任务。LLM **只负责**看文章、找问题、打分。强制输出极致精简的、无大段长文本的 JSON 数据。
|
||||
* **View (文秘)**：负责将精简的 JSON 数据，渲染成带有专家个人风格（1/2/3 排版、温暖/严厉口吻）的自然语言报告。
|
||||
* **Controller (系统)**：负责业务调度、存库、进度条控制。
|
||||
|
||||
基于这个核心思想，针对贵司当前的基建现状，有以下三套递进的终极解决方案：
|
||||
|
||||
## **三、 三套终极解决方案 (按彻底程度递进)**
|
||||
|
||||
### **方案 A：底层原生强约束 (Structured Outputs) —— “从 API 层面锁死”**
|
||||
|
||||
不要在 Prompt 里写“请输出 JSON”，这是软约束。
|
||||
|
||||
各大主流模型（OpenAI, DeepSeek-V3）均已支持底层的结构化输出能力。
|
||||
|
||||
* **架构实现**：
|
||||
1. 在你们后端的 LLMFactory / StreamingService 中，调用模型时强行传入 response\_format: { type: "json\_schema", json\_schema: {...} }。
|
||||
2. 这个 Schema 由系统通过 Zod 或纯 JSON Schema 严格定义（必须有哪些字段，字段必须是枚举或数字）。
|
||||
3. 此时，大模型在底层的 Logits 采样阶段就会被加上 Mask（掩码），**它在物理层面上根本无法输出破坏 JSON 结构的 Token**。
|
||||
* **优点**：100% 解决 JSON 解析错误，改造成本极低。
|
||||
* **缺点**：依然没有解决“专家想自定义报告文本排版”的问题，且如果 JSON 中包含超长文本，依然可能导致 Token 浪费和轻微的截断。
|
||||
|
||||
### **方案 B：纯数据 JSON \+ Handlebars 动态模板 —— “零幻觉的完美解”**
|
||||
|
||||
💡 强烈推荐！我看你们在 ADMIN Phase 3.5.2 中已经实现了 Handlebars，这是最完美的契合点！
|
||||
|
||||
完全剥夺大模型的排版权利，大模型只负责提取“缺陷数据”。专家的排版要求，通过 Handlebars 模板在运营后台配置。
|
||||
|
||||
* **工作流**：
|
||||
1. **大模型推理**：输出极其干燥的数据（仅供系统流转）。
|
||||
{
|
||||
"score": 80,
|
||||
"issues": \[
|
||||
{"code": "ME-01", "name": "未做共线性检验", "suggestion": "补充 VIF 检验"}
|
||||
\]
|
||||
}
|
||||
|
||||
2. **专家后台配置 (View 模板)**：主编在运营管理端，像写 Word 模板一样配置：
|
||||
\#\#\# 方法学预审报告
|
||||
您好，本次得分：{{score}} 分。
|
||||
系统发现了以下 {{issues.length}} 个问题：
|
||||
{{\#each issues}}
|
||||
{{@index}}. 【{{this.name}}】：建议您 {{this.suggestion}}。
|
||||
{{/each}}
|
||||
|
||||
3. **系统渲染**：后端将 LLM 吐出的 JSON 喂给 Handlebars 模板，瞬间生成纯净的 Markdown 报告推给前端。
|
||||
* **优点**：
|
||||
* **彻底解耦**：专家爱怎么改排版就怎么改，永远不会导致系统报错。
|
||||
* **极致稳定**：LLM 只需要输出极短的 JSON，速度飞快，绝无转义灾难。
|
||||
* **复用基建**：完美复用你们已有的 PromptService 和 Handlebars 引擎。
|
||||
* **缺点**：要求主编掌握一点点 {{}} 占位符的写法（运营端可提供可视化插入按钮来降低门槛）。
|
||||
|
||||
### **方案 C：双轨 Agent 协同管线 (Pipeline/Map-Reduce) —— “高度拟人化的终局”**
|
||||
|
||||
如果期刊主编不仅要求格式，还要求极度灵活的语气（例如：“如果得分低于 60，就在开头严厉批评；如果高于 80，就热情表扬”），这就超出了 Handlebars 静态模板的能力。此时需要引入**双 Agent 协同**（类似你们 SSA 模块的 Plan-and-Execute 架构）。
|
||||
|
||||
* **工作流**：
|
||||
1. **Agent 1 (方法学判官 Evaluator)**：搭载复杂的 20 项规则 Prompt，负责深度思考和“找茬”。开启严格的 JSON 模式，只输出结构化问题列表，后台落库。
|
||||
2. **Agent 2 (撰稿编辑 Writer)**：接到 Agent 1 的 JSON 后被唤醒。它的 Prompt 是主编配置的口吻与格式要求（“请根据以下 JSON 缺陷数据，以极其严厉的专家口吻，按 1/2/3 的格式写一封给作者的退修信”）。
|
||||
3. **流式输出 (Streaming)**：Agent 2 直接采用流式 SSE 输出纯 Markdown 文本，前端打字机般实时渲染给责编。
|
||||
* **优点**：
|
||||
* **终极体验**：前端用户看到的是行云流水的打字效果，而后端数据库早已稳稳存下了 Agent 1 的结构化数据。
|
||||
* **职责单一**：每个 LLM 都在做自己最擅长的事，能力被压榨到极致。
|
||||
* **缺点**：消耗 2 次 LLM 调用，略微增加 Token 成本与耗时。但在多模块并行（Promise.allSettled）架构下，这一点时间是可以被接受的。
|
||||
|
||||
## **四、 给 RVW 模块 V4.0 的最终决策建议**
|
||||
|
||||
综合考量贵司“敏捷迭代”、“已有基建（Handlebars/PromptService）”和“商业化 SaaS”的诉求，我建议采取 **方案 B 作为核心底座，特定场景引入方案 C** 的融合架构：
|
||||
|
||||
#### **第一步：重构 PromptService 的输入输出协议 (落实方案 B)**
|
||||
|
||||
1. 运营端页面拆分：将现有的一个大输入框，拆分为\*\*【评判标准库 (Prompt)】**和**【报告展示模板 (Handlebars)】\*\*两个配置区。
|
||||
2. 约束模型：系统底层强制开启模型的 Structured Output (JSON Schema)，LLM 输出只用于落库和填充模板。
|
||||
|
||||
#### **第二步：引入双通道确认机制 (类似 SSA Phase IV)**
|
||||
|
||||
在责编工作台中，左侧是 AI 找出的【结构化问题卡片】（供责编打勾/忽略），右侧是实时根据勾选状态，利用 Handlebars 重新渲染的【最终意见函预览】。
|
||||
|
||||
#### **长期演进**
|
||||
|
||||
当遇到需要根据不同分数输出截然不同口吻的高级定制化期刊时，再为该期刊开启 **方案 C (双 Agent 模式)**，把撰写意见函的工作交给 Writer Agent 实时生成。
|
||||
|
||||
**总结**：不要试图在一个 Prompt 里用自然语言去“恳求”大模型兼顾结构化和排版。**用底层 API（JSON Schema）锁死结构化数据，用中间层引擎（Handlebars / Writer Agent）解决排版展示**，才是云原生时代的终极稳定架构。
|
||||
89
docs/03-业务模块/RVW-稿件审查系统/08-技术架构建议/架构评审报告.md
Normal file
89
docs/03-业务模块/RVW-稿件审查系统/08-技术架构建议/架构评审报告.md
Normal file
@@ -0,0 +1,89 @@
|
||||
# **RVW 模块方法学解析失败 \- 架构方案评审意见**
|
||||
|
||||
仔细阅读了您的分析与解决方案，以及《RVW稿件审查模块 \- 当前状态与开发指南 (v6.1)》，我对您的整体思路表示**高度赞同**。您的分析非常精准地抓住了当前大模型（LLM）工程化落地中的核心痛点：**人类语言的弹性与机器协议的刚性之间的矛盾。**
|
||||
|
||||
以下是我对您方案的详细评审，包括我完全认可的部分，以及我认为需要微调或补充的“不认可/需优化”部分。
|
||||
|
||||
## **✅ 一、 我完全认可的观点（高度赞同）**
|
||||
|
||||
### **1\. 对“为什么必须是 JSON”的业务判定**
|
||||
|
||||
**完全认可。** 您的分析一针见血。在 RVW V3.0.1 的架构中，方法学评估并不是一个“终点”，而是流水线的一环。
|
||||
|
||||
* 系统依赖解析出 overall\_score 和 methodologyStatus 来更新数据库。
|
||||
* 前端的 MethodologyReport.tsx 和 TaskDetail.tsx 依赖结构化数组（parts\[\]/issues\[\]）来渲染多维度的进度条和增量展示。
|
||||
* 如果退化为纯文本，RVW 模块引以为傲的“4模块并行”、“增量结果持久化”和“结构化 Word 导出”将全线崩溃。
|
||||
|
||||
### **2\. 对“核心区别：软约束 vs 硬约束”的定性**
|
||||
|
||||
**完全认可。** 仅在 Prompt 中强调“请输出JSON”是典型的**软约束**。业务专家在运营端（PromptService）修改提示词时，往往会引入更多复杂的业务逻辑描述，这极易稀释模型对格式指令的注意力（Attention 偏移），导致模型在输出时“情不自禁”地加上“好的，以下是评估结果：”等前缀，从而破坏 JSON 解析。
|
||||
|
||||
### **3\. 将“方案A（Structured Output）”作为最优解**
|
||||
|
||||
**完全认可。** 采用 Function Calling 或 Structured Output（Response Format）是当前 LLM 工程界的最佳实践。它将“格式对齐”的工作下沉到了 API 协议层甚至模型的推理采样层（通过 Logits 掩码强制符合 Schema），从而释放了 Prompt 的空间，让 Prompt 可以纯粹服务于业务逻辑。
|
||||
|
||||
## **❌ 二、 我不完全认可 / 需要补充完善的观点**
|
||||
|
||||
虽然大方向极佳，但从您当前的系统架构（已使用 DeepSeek-V3，具有 LLMFactory 和 PromptService）来看，有几个工程落地的细节我**不完全认可**或认为**需要优化**：
|
||||
|
||||
### **1\. 关于“方案B：先自然语言，再二次抽取结构”的定位**
|
||||
|
||||
* **您的观点**：这是一个可选方案，增加了修复层。
|
||||
* **我的意见（不推荐）**：在你们当前的 V3.0.1 架构中，极度**不建议**将其作为常规链路。你们的核心指标是“上传到出报告 \< 3分钟（4模块并行）”。如果方法学每次都跑两遍 LLM（甚至第二遍还要等第一遍长文本生成完），不仅 token 成本翻倍，时延也会大幅增加，破坏现有的并发体验。二次抽取**只能**作为万不得已的 Error Retry 兜底，绝不能是主干方案。
|
||||
|
||||
### **2\. 关于“schema优先 \+ JSON兜底”的必要性**
|
||||
|
||||
* **您的观点**：优先走结构化输出，失败再走 JSON 解析或修复，本质是多层容灾。
|
||||
* **我的意见（略显冗余）**：现在的基座模型（如你们默认的 DeepSeek-V3 和备选的 Qwen3-72B）对 Structured Output / JSON Mode 的支持已经非常成熟。
|
||||
* 如果您在 API 层面开启了 response\_format: { type: "json\_object" } 或提供了强 Schema，模型返回的一定是格式完好的 JSON 字符串。
|
||||
* 此时如果解析失败，往往是**模型幻觉导致缺少必填字段**，而不是**JSON格式本身损坏**。因此，容灾的重点不应是“尝试用正则重新抠 JSON”，而应该是直接记录 error\_details（你们已在 V3.0 支持 partial\_completed）并触发基于格式错误的重试逻辑。
|
||||
|
||||
### **3\. 遗漏了最核心的系统层解法：“Prompt 动静分离”（关键补充！）**
|
||||
|
||||
您的方案主要集中在 LLM 的调用方式上，但忽略了**运营管理端的设计缺陷**。专家修改 Prompt 导致 JSON 崩坏，根本原因是**专家触碰了他们不该触碰的代码约定**。
|
||||
|
||||
* **真正的解法**：在您的 PromptService 中，应该将 Prompt 拆分为两部分：
|
||||
1. **System/Format Prompt（系统保留，研发控制）**：包含严格的 JSON Schema 定义、输出格式要求等。这部分在前端运营管理后台是**隐藏或只读**的。
|
||||
2. **Business Criteria Prompt（专家可编辑）**：仅包含纯粹的评估标准，如“如何判定T检验误用”、“FINER标准是什么”。
|
||||
3. **最终组装**：在 MethodologySkill 执行时，由代码自动将两部分拼接发送给 LLM。这样无论专家怎么改业务逻辑，都不会破坏格式指令。
|
||||
|
||||
## **🚀 三、 针对 RVW V3.0.1 的具体落地建议**
|
||||
|
||||
结合您的现有代码结构（backend/src/modules/rvw/），我建议您按以下三步实施“彻底解决 JSON 崩溃”的方案：
|
||||
|
||||
### **Step 1: 在 LLMFactory 中启用 JSON Mode**
|
||||
|
||||
修改 @/common/llm/LLMFactory，支持传入 response\_format 或 tools。DeepSeek-V3 原生支持强校验的 JSON 输出。
|
||||
|
||||
// 示例：强制要求模型仅返回 JSON
|
||||
const response \= await llmClient.chat.completions.create({
|
||||
model: 'deepseek-chat',
|
||||
messages: \[...\],
|
||||
response\_format: { type: 'json\_object' } // 启用 JSON Mode
|
||||
});
|
||||
|
||||
### **Step 2: 实施 Prompt 动静分离 (改造 PromptService)**
|
||||
|
||||
在数据库 prompt\_templates 表或 MethodologySkill 中做拆分：
|
||||
|
||||
// 在 methodologyService.ts 或 methodologySkill.ts 中组装
|
||||
const formatInstruction \= \`
|
||||
你必须严格按照以下 JSON 结构输出结果，不要包含任何额外的解释文本或 Markdown 标记：
|
||||
{
|
||||
"overall\_score": 85,
|
||||
"methodologyStatus": "error" | "warn" | "pass",
|
||||
"parts": \[
|
||||
{ "name": "统计方法描述", "issues": \[{"severity": "high", "desc": "..."}\] }
|
||||
\]
|
||||
}\`;
|
||||
|
||||
// expertPrompt 是专家在运营管理端配置的内容
|
||||
const finalPrompt \= expertPrompt \+ '\\n\\n' \+ formatInstruction;
|
||||
|
||||
### **Step 3: 善用 V3.0 现有的 partial\_completed 兜底**
|
||||
|
||||
既然 V3.0 已经实现了 Promise.allSettled 和 error\_details，如果（极小概率下）大模型返回的 JSON 缺少了关键字段导致 Schema 校验失败（比如少了 parts 数组）：
|
||||
|
||||
* **不要尝试用正则表达式去猜**。
|
||||
* 直接 throw new Error("Methodology JSON schema validation failed")。
|
||||
* 让外层的 SkillExecutor 捕获，把当前任务标记为 partial\_completed，并在 error\_details 写入原因。前端的“琥珀色警告横幅”会自动提示用户该模块暂时失败，保证系统的绝对健壮性。
|
||||
@@ -26,6 +26,7 @@
|
||||
| BE-2 | 新增 Agent 计划参数编辑接口 `PATCH /api/v1/ssa/agent-executions/:executionId/plan-params`（复用参数约束配置） | `backend/src/modules/ssa/routes/agent-execution.routes.ts`, `backend/src/modules/ssa/index.ts` | 重新构建镜像 | Phase 5A.5 后端入口，限制 `plan_pending` 状态可编辑 |
|
||||
| BE-3 | Agent 切换为严格分步模式：`confirm_plan` 不生成整段代码，执行阶段统一按步骤生成 + 失败后依赖短路跳过后续步骤 | `backend/src/modules/ssa/services/ChatHandlerService.ts` | 重新构建镜像 | 修复“第3步失败仍尝试第4步”问题，降低无效重试与误导性结果 |
|
||||
| BE-4 | R 代码语法修复器纠正 `} else` 处理策略，避免引入 `unexpected 'else'` | `backend/src/modules/ssa/services/CodeRunnerService.ts` | 重新构建镜像 | 修复线上语法错误噪声，减少重试失败 |
|
||||
| BE-5 | RVW 审稿通道改造：4 通道 Prompt 动静分离（业务提示词可编辑 + 系统协议固化）+ 方法学/稿约 JSON 结构化修复兜底 + DataForensics 默认切换为 LLM-only（规则验证默认关闭） | `backend/src/modules/rvw/services/promptProtocols.ts`, `backend/src/modules/rvw/services/editorialService.ts`, `backend/src/modules/rvw/services/methodologyService.ts`, `backend/src/modules/rvw/services/clinicalService.ts`, `backend/src/modules/rvw/skills/library/DataForensicsSkill.ts`, `backend/src/modules/rvw/skills/core/types.ts`, `backend/src/common/document/ExtractionClient.ts`, `backend/src/common/prompt/prompt.fallbacks.ts` | 重新构建镜像 | 解决运营端改 Prompt 导致 JSON 解析失败；数据侦探默认仅“表格提取+LLM判断”，规则代码保留可回切 |
|
||||
|
||||
### 前端变更
|
||||
|
||||
@@ -39,7 +40,7 @@
|
||||
|
||||
| # | 变更内容 | 涉及文件 | 需要操作 | 备注 |
|
||||
|---|---------|---------|---------|------|
|
||||
| — | *暂无* | | | |
|
||||
| PY-1 | Forensics API 新增 `EXTRACT_ONLY` 模式并默认仅提取表格（不执行 L1/L2 规则校验） | `extraction_service/forensics/api.py`, `extraction_service/forensics/types.py` | 重新构建镜像 | 与后端 RVW LLM-only 路径配套，避免规则与 LLM 双轨冲突 |
|
||||
|
||||
### R 统计引擎变更
|
||||
|
||||
@@ -51,7 +52,7 @@
|
||||
|
||||
| # | 变更内容 | 服务 | 变量名 | 备注 |
|
||||
|---|---------|------|--------|------|
|
||||
| — | *暂无* | | | |
|
||||
| ENV-1 | 新增 RVW 数据侦探规则引擎开关（默认关闭） | nodejs-backend-test / nodejs-backend-prod | `RVW_FORENSICS_RULES_ENABLED=false` | `false`=仅表格提取+LLM判断（推荐）；如需恢复规则验证可设为 `true` |
|
||||
|
||||
### 基础设施变更
|
||||
|
||||
|
||||
Reference in New Issue
Block a user