# 试剂盒临床注册文件准备与审核智能体平台

用于复试展示的体外诊断试剂注册申报资料准备与审核系统。

当前项目已根据真实笔试题重构目标定位，重点服务于 NMPA 境内第三类体外诊断试剂注册申报场景，覆盖资料整理、目录汇总、法规完整性检查、关键信息抽取、跨文档一致性核查、风险预警和审计留痕。

## 核心理念

```text
注册审核 Agent = 任务配置 + 资料库 + 法规规则 + 工具集 + 输出模板 + 审计日志 + 模型适配器
```

## 技术路线

V1 采用：

- Django 单体应用
- 独立 Agent Core 模块
- SQLite
- Chroma
- Django Templates
- Docker Compose
- OpenAI API 兼容的 LLM 与 Embedding 接口

默认不强依赖 Dify。系统预留 Adapter 设计，后续可以接入 Dify、OpenAI Agents SDK 或其他 Agent 编排平台。

## 当前业务主线

当前系统围绕以下注册申报审核闭环展开：

1. 导入注册资料包。
2. 解析资料包并识别产品名称。
3. 以解析后的产品名称创建或绑定对话会话。
4. 汇总文件目录与页数。
5. 对照法规要求检查完整性。
6. 抽取产品关键信息。
7. 自动填入注册申报表格或对照清单。
8. 核查跨文档一致性。
9. 输出风险预警、处理建议和飞书通知。

## 当前产品形态

当前原型和需求文档已经统一为 Agent 化产品形态，顶层入口固定为：

1. `审核智能体`
2. `资料包`
3. `知识库`
4. `处理历史`

对应关系如下：

1. `审核智能体` 是主执行入口，承载对话、模板提问、节点跳转和结构化结果。
2. `资料包` 是主业务对象，资料包与会话绑定，对话标题采用解析后的产品名称，并支持按产品名称或批次号搜索。
3. `知识库` 负责法规资料、业务资料、RAG 切片、字段 Schema、模板映射和飞书配置治理。
4. `处理历史` 用于按批次回看历史任务、关联会话、风险状态和通知留痕。

## 模块划分

```text
config
apps.scenarios
apps.documents
apps.chat
apps.audit
agent_core
```

职责边界：

- Django Apps 负责页面、数据、文件、日志等企业应用外壳。
- Agent Core 负责 RAG、工具调用、模型适配、结构化输出和 Agent 编排。
- RAG、工具调用和模型调用不直接写进 Django View。

## 推荐项目结构

```text
universal-agent-demo/
  manage.py
  requirements.txt
  Dockerfile
  docker-compose.yml
  .env.example
  README.md
  AGENTS.md

  config/
  apps/
    scenarios/
    documents/
    chat/
    audit/

  agent_core/
    rag/
    tools/
    schemas/

  configs/
    registration_overview.yaml
    registration_completeness_check.yaml
    registration_field_extraction.yaml
    registration_consistency_review.yaml
    registration_risk_report.yaml

  data/
    uploads/
    chroma/

  docs/
```

## V1 功能范围

V1 需要完成：

- 注册审核任务列表。
- 审核工作台。
- 资料上传与管理。
- 文档解析与入库。
- 目录与页数汇总。
- 法规完整性检查。
- 关键信息抽取与注册申报表格 / 对照清单自动回填。
- 一致性核查。
- 风险预警与审计日志。
- 模型 API 可配置。
- Docker 一键启动。

当前代码基线已经落地的主链能力：

- 首页已收口为 `审核智能体 / 资料包 / 知识库 / 处理历史` 四入口平台总览。
- 非法 YAML 场景配置会被自动跳过，并在首页展示错误摘要，但场景仅作为底层执行配置参考。
- 审核智能体页已采用三栏结构，支持会话历史、文档范围选择、节点式结果、结构化能力卡、导出与通知回看。
- 资料包页支持资料包导入、产品名称 / 批次号搜索、会话跳转、导出记录回看和处理链路展示。
- 处理历史页支持按批次、产品、风险状态、通知状态回看执行快照，并展示通知留痕。
- 知识库页支持治理对象导航、模板映射、责任人映射、飞书配置和跨入口治理动作总览。
- Agent Core 已具备 Prompt 编排、OpenAI 兼容 Provider、结构化输出解析、RAG 检索和工具注册机制。
- 测试环境默认固定使用 Mock Provider，避免误调用本地真实模型配置。

## 本轮需求文档

本轮已按模块重写需求分析，详见：

- [V1 总需求文档](F:\PyCharm\DEMO-AGENT\docs\需求分析\1.V1总需求文档.md)
- [需求重构总览与待确认事项](F:\PyCharm\DEMO-AGENT\docs\需求分析\0.需求重构总览与待确认事项.md)

V1 暂不重点做：

- 多租户。
- 复杂权限。
- 完整工作流引擎。
- 前后端分离。
- 深度 Dify 集成。
- 生产级高并发优化。

## 复试改题流程

拿到题目后：

1. 判断资料包、规则依据和核心审核链路。
2. 调整最接近的任务 YAML 配置。
3. 修改 Agent 角色、目标、指令和输出模板。
4. 上传题目材料并生成资料包。
5. 确认产品名称解析、资料包绑定和会话标题是否正确。
6. 如需业务计算，新增一个工具函数。
7. 用 2 到 3 个预设问题测试目录汇总、完整性检查和字段抽取。
8. 演示对话节点、知识库引用、结构化输出、飞书通知和审计日志。

## 当前页面概览

当前项目包含以下主要页面：

| 页面 | 路径 | 当前能力 |
|---|---|---|
| 首页 / 平台总览 | `/` | 展示四入口主叙事、产品指标、风险摘要和底层场景配置参考 |
| 审核智能体 | `/chat/` 与 `/chat/<conversation_id>/` | 会话驱动审核、节点式结果、上传补传、Word 导出、通知与审计回看 |
| 资料包 | `/documents/` 及相关上传入口 | 查看资料包、按产品名称搜索、跳转会话、查看最近导出和处理链路 |
| 知识库 | `/platform/knowledge-base/` | 管理法规资料、业务资料、切片、字段 Schema、模板映射、责任人映射和飞书配置 |
| 处理历史 | `/audit/` 及详情页 | 查看执行摘要、批次 / 会话 / 产品链路、通知状态、导出摘要和错误信息 |

## 计划启动方式

本地启动：

```bash
pip install -r requirements.txt
python manage.py migrate
python manage.py runserver
```

Docker 启动：

```bash
docker compose up --build
```

当前文档目标已统一为完整 V1 闭环：真实 Chroma RAG、OpenAI 兼容 LLM、OpenAI 兼容 Embedding、工具注册和审计日志。开发阶段可以用测试桩验证页面和边界，但不作为 V1 验收结果。

推荐首次启动步骤：

```bash
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
python manage.py migrate
python manage.py runserver
```

## 环境变量

项目当前通过 `os.environ` 读取配置，核心变量如下：

```env
DJANGO_SECRET_KEY=replace-with-a-local-secret-key
DJANGO_DEBUG=true
DJANGO_ALLOWED_HOSTS=*

LLM_API_KEY=your_llm_api_key
LLM_BASE_URL=https://api.openai.com/v1
LLM_MODEL=gpt-4.1-mini

EMBEDDING_API_KEY=
EMBEDDING_BASE_URL=
EMBEDDING_MODEL=text-embedding-3-small

SCENARIO_CONFIG_DIR=configs
UPLOAD_ROOT=data/uploads
CHROMA_PATH=data/chroma
```

说明：

- `EMBEDDING_API_KEY` 为空时，代码会自动复用 `LLM_API_KEY`。
- `EMBEDDING_BASE_URL` 为空时，代码会自动复用 `LLM_BASE_URL`。
- `.env.example` 只作为模板，不应填写真实密钥并提交到仓库。
- 当前代码会在 Django settings 初始化时自动加载根目录 `.env`，本地 `python manage.py runserver`、`pytest` 和 Docker Compose 可以复用同一套配置。
- Docker Compose 当前在 `docker-compose.yml` 中通过 `env_file` 读取 `.env`。

常见做法：

- 本地开发：复制 `.env.example` 为 `.env`，填入真实参数后运行。
- Docker 演示：确认 `.env` 已配置后，再执行 `docker compose up --build`。

## 测试与验证

当前项目已经补有较完整的模块级测试，覆盖：

- 场景配置读取、非法配置容错和首页展示。
- 对话提交、文档范围传递、结构化结果展示。
- 文档上传、文本抽取、入库成功与失败提示。
- 审计日志落库、筛选、原始输出展示和 API Key 脱敏。
- Agent Core 的 Prompt 编排、结构化解析、RAG fallback 检索。
- Tool Registry 和内置工具行为。
- LLM / Embedding Provider 的配置与请求构造。

常用验证命令：

```bash
pytest
python manage.py check
docker compose config
```

说明：

- 测试环境默认通过 `tests/conftest.py` 固定 `LLM_PROVIDER=mock`，避免回归测试误走真实网络请求。
- 当前本地 `.env` 可能包含真实模型配置，但不会影响自动化测试稳定性。

## 文档入口

- [V1 总需求文档](docs/需求分析/1.V1总需求文档.md)
- [需求重构总览与待确认事项](docs/需求分析/0.需求重构总览与待确认事项.md)
- [Config 模块需求分析](docs/需求分析/1.config模块需求分析.md)
- [Scenarios 模块需求分析](docs/需求分析/2.scenarios模块需求分析.md)
- [Documents 模块需求分析](docs/需求分析/3.documents模块需求分析.md)
- [Chat 模块需求分析](docs/需求分析/4.chat模块需求分析.md)
- [Audit 模块需求分析](docs/需求分析/5.audit模块需求分析.md)
- [Agent Core 模块需求分析](docs/需求分析/6.agent_core模块需求分析.md)
- [业务确认问答清单](docs/需求分析/9.业务确认问答清单.md)
- [资料包导入与目录汇总详细设计](docs/详细设计/1.资料包导入与目录汇总.md)
- [法规完整性检查详细设计](docs/详细设计/2.法规完整性检查.md)
- [字段抽取与统一字段池详细设计](docs/详细设计/3.字段抽取与统一字段池.md)
- [一致性核查详细设计](docs/详细设计/4.一致性核查.md)
- [风险预警详细设计](docs/详细设计/5.风险预警.md)
- [Word 回填导出详细设计](docs/详细设计/6.Word回填导出.md)
- [飞书通知详细设计](docs/详细设计/7.飞书通知.md)
- [注册审核平台整体原型设计](F:\PyCharm\DEMO-AGENT\docs\原型设计\1.整体原型设计.md)
- [原型设计目录](F:\PyCharm\DEMO-AGENT\docs\原型设计)
- [单文件演示站 HTML](F:\PyCharm\DEMO-AGENT\docs\原型设计\registration-prototype-demo.html)
- [协作与编码约定](AGENTS.md)

## 原型设计交付

当前仓库已补充一套围绕注册申报审核主线的原型设计资产，供复试讲解、方案评审和后续页面实现直接参考：

- 原型文档采用“总览 + 分页细设计”方式组织，覆盖资料包导入、审核任务工作台、法规完整性检查、字段抽取与字段池、一致性核查、风险预警、Word 回填导出、飞书通知视图和知识库治理台。
- `docs/原型设计/registration-prototype-demo.html` 提供单文件可交互 mock 演示站，当前已重构为 Agent 化界面，顶层为 `审核智能体 / 资料包 / 知识库 / 处理历史`。
- 资料包与对话会话已在原型中绑定，对话标题采用解析后的产品名称，资料包页支持按产品名称搜索并跳转对应会话。
- 该演示站仅使用 mock 数据，不依赖 Django 路由或真实 Agent Core 执行结果。