DEMO-AGENT/README.md

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

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

项目已按真实笔试题收口为 NMPA 境内第三类体外诊断试剂注册申报资料场景，重点演示“资料包导入 -> 审核智能体执行 -> 结构化结果 -> Word 导出 -> 通知与审计留痕”的本地闭环。

## 核心理念

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

## 技术路线

V1 采用：

- Django 单体应用
- 独立 Agent Core 模块
- SQLite
- Chroma / fallback 检索双路径
- Django Templates
- Docker Compose
- OpenAI API 兼容的 LLM 与 Embedding 接口

默认不强依赖 Dify。系统保留 Provider / Adapter 边界，后续可接入 Dify、OpenAI Agents SDK 或其他 Agent 编排平台。

## 当前业务主线

1. 进入审核智能体后，可以先不上传资料，直接通过对话查询法规和业务知识库。
2. 导入注册资料包，支持单文件、多文件和压缩包。
3. 解析文件元数据、页数、章节点和产品名称。
4. 自动创建资料包批次，并绑定审核会话。
5. 在审核智能体工作台选择文档范围并发起目录汇总、完整性检查、字段抽取、一致性核查或风险报告。
6. Agent Core 按场景配置执行 RAG 检索、工具调用、Prompt 编排、LLM 调用和结构化输出解析。
7. 会话页展示节点状态、能力卡、风险摘要、通知信息和导出入口。
8. Word 回填导出生成可下载 `.docx`，并记录到资料包和处理历史。
9. 审计模块保存成功与失败两类执行快照，并沉淀飞书通知留痕。

## 当前产品入口

当前根路径 `/` 会直接进入审核智能体工作台，便于复试演示聚焦主链路。

| 页面 | 路径 | 当前能力 |
|---|---|---|
| 审核智能体 | `/`、`/chat/`、`/chat/<conversation_id>/` | 无资料包知识库问答、会话驱动审核、文档范围选择、节点式结果、能力卡、补传资料、Word 导出、通知与审计回看 |
| 资料包 | `/documents/`、`/documents/upload/` | 导入资料包、搜索产品或批次、查看解析状态、异常提示、最近导出和处理链路 |
| 处理历史 | `/audit/`、`/audit/<log_id>/` | 按批次、产品、风险状态、通知状态回看执行快照、原始输出、导出摘要和通知回执 |
| 知识库治理台 | `/platform/knowledge-base/` | 查看法规规则包、RAG 文档源、切片、字段 Schema、Word 模板、责任人映射和飞书配置 |
| MCP 中心演示页 | `/platform/mcp-center/` | 展示外部连接器治理视图 |
| Skill 工作室演示页 | `/platform/skills/` | 展示审核 Skill 编排和发布状态 |
| 审核指挥台 | `/platform/command-center-v2/` | 面向讲解的大屏式审核流程与风险状态视图 |
| 底层场景列表 | `/scenarios/` | 展示 YAML 场景配置和非法配置错误摘要 |
| Django Admin | `/admin/` | 维护后台模型数据 |

## 模块划分

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

职责边界：

- `config` 负责 Django 配置、路由入口、环境变量、静态资源和上传路径。
- `apps.scenarios` 负责读取 YAML 场景配置，非法配置可被跳过并展示错误摘要。
- `apps.documents` 负责资料包、上传文件、章节点识别、页数统计、文本抽取、RAG 入库触发和导出记录。
- `apps.chat` 负责审核工作台、会话绑定、用户输入、调用 Agent Core、补传资料和 Word 导出编排。
- `apps.audit` 负责审计日志、通知留痕、处理历史列表和详情回看。
- `apps.platform_ui` 负责知识库治理台、MCP 中心、Skill 工作室和指挥台等演示型治理页面。
- `agent_core` 负责 RAG、工具注册、治理配置、LLM Provider、Prompt 编排和结构化输出。

约束：RAG、工具调用和模型调用不直接写进 Django View；View 只做请求处理和页面渲染，复杂业务逻辑放到 `services.py` 或 `agent_core`。

## 项目结构

```text
DEMO-AGENT/
  manage.py
  requirements.txt
  Dockerfile
  docker-compose.yml
  .env.example
  README.md
  AGENTS.md

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

  agent_core/
    rag/
    schemas/
    tools/

  configs/
    document_review.yaml
    governance.yaml
    knowledge_qa.yaml
    quality_analysis.yaml
    risk_audit.yaml
    ticket_assistant.yaml

  data/
    uploads/
    chroma/
    db.sqlite3

  docs/
    需求分析/
    详细设计/
    原型设计/
    原始材料/

  templates/
  tests/
```

## 已落地能力

- 根路径已重定向到审核智能体，降低演示入口复杂度。
- 审核工作台允许未上传资料时直接发起知识库问答，后续再通过右侧上传区导入资料包。
- 资料包导入支持 PDF、DOCX、MD、TXT、ZIP、7Z、RAR；压缩包内仅导入支持格式，其他文件会生成提示。
- 导入时会创建 `SubmissionBatch`、`UploadedDocument` 和绑定的 `Conversation`。
- 文档解析覆盖文本抽取、PDF 页数统计、DOCX 页数元数据读取、章节点识别、文档角色识别和人工复核标记。
- 审核工作台支持会话历史、资料范围选择、预设问题、节点状态、结构化能力卡、补传资料、Word 导出和通知回看。
- Agent Core 已具备 Prompt 编排、OpenAI 兼容 Provider、结构化输出解析、RAG 检索、工具注册和治理配置读取。
- Word 导出会生成最小可下载 `.docx`，按风险状态区分正式版或草稿版，并写入导出记录。
- 审计日志记录输入、检索片段、工具调用、结构化输出、原始输出、模型名、耗时、状态和错误信息。
- 飞书通知首版为离线留痕，不直接依赖真实飞书网络发送；支持 `task_completed` 与 `task_failed` 两类原因。
- 知识库治理台展示法规规则、RAG 源、切片、字段 Schema、Word 模板、责任人映射和飞书配置。
- 自动化测试默认使用 Mock Provider，避免本地真实模型密钥导致测试走网络。

## 启动方式

推荐首次本地启动：

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

Docker 启动：

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

Docker Compose 会读取根目录 `.env`，并挂载 `./data` 与 `./configs`。

## 环境变量

项目通过根目录 `.env` 和系统环境变量读取配置。`.env.example` 只作为模板，不应提交真实密钥。

```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
GOVERNANCE_CONFIG_PATH=configs/governance.yaml
UPLOAD_ROOT=data/uploads
CHROMA_PATH=data/chroma
```

说明：

- `EMBEDDING_API_KEY` 为空时自动复用 `LLM_API_KEY`。
- `EMBEDDING_BASE_URL` 为空时自动复用 `LLM_BASE_URL`。
- Django settings 初始化时会自动加载根目录 `.env`。
- 测试环境会在 `tests/conftest.py` 中固定 Mock Provider，避免误调用真实 LLM。

## 测试与验证

常用验证命令：

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

当前测试覆盖：

- 项目配置、根路由和核心页面可访问性。
- 场景配置读取、非法 YAML 容错和场景列表展示。
- 资料包导入、压缩包展开、文档解析、入库状态和异常提示。
- 会话创建、对话提交、文档范围传递、结构化结果展示和 Word 导出。
- 审计日志落库、筛选、详情展示、通知留痕和敏感信息脱敏。
- Agent Core 的 Prompt 编排、结构化解析、RAG fallback、工具注册、LLM / Embedding Provider 请求构造。
- 平台治理页、指挥台、知识库、MCP 中心和 Skill 工作室展示。

## 文档入口

- [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)
- [注册审核平台整体原型设计](docs/原型设计/1.整体原型设计.md)
- [单文件演示站 HTML](docs/原型设计/registration-prototype-demo.html)
- [协作与编码约定](AGENTS.md)

## 复试改题流程

拿到新题目后：

1. 判断资料包、规则依据和核心审核链路。
2. 调整最接近的 YAML 场景配置，优先从 `configs/document_review.yaml` 入手。
3. 修改 Agent 角色、目标、指令和输出模板。
4. 上传题目材料并生成资料包。
5. 确认产品名称解析、资料包绑定和会话标题是否正确。
6. 如需业务计算，新增工具函数并通过 Tool Registry 注册。
7. 用 2 到 3 个预设问题测试目录汇总、完整性检查、字段抽取和风险报告。
8. 演示节点结果、知识库引用、结构化输出、Word 导出、通知留痕和审计日志。

## V1 不优先做

- React / Vue 前端。
- 多租户。
- 复杂 RBAC。
- 完整工作流引擎。
- 深度 Dify 集成。
- 微服务拆分。
- 分布式任务队列。
- 真实飞书发送链路。

这些内容可以作为后续增强，不应影响 V1 快速成型。