Bruce/DEMO-AGENT
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(demo-agent): 同步当前实现状态与协作约定

Browse Source
This commit is contained in:
zhiye.sun
2026-06-04 16:38:18 +08:00
parent 5aa7b5f3d0
commit 1d8a526770
2 changed files with 174 additions and 202 deletions
Download Patch File Download Diff File Expand all files Collapse all files

266
README.md
View File

@@ -2,12 +2,12 @@
用于复试展示的体外诊断试剂注册申报资料准备与审核系统。
当前项目已根据真实笔试题重构目标定位，重点服务于 NMPA 境内第三类体外诊断试剂注册申报场景，覆盖资料整理、目录汇总、法规完整性检查、关键信息抽取、跨文档一致性核查、风险预警和审计留痕。
项目已按真实笔试题收口为 NMPA 境内第三类体外诊断试剂注册申报资料场景，重点演示“资料包导入 -> 审核智能体执行 -> 结构化结果 -> Word 导出 -> 通知与审计留痕”的本地闭环。
## 核心理念
```text
注册审核 Agent = 任务配置 + 资料库 + 法规规则 + 工具集 + 输出模板 + 审计日志 + 模型适配器
注册审核 Agent = 任务配置 + 资料包 + 法规/业务知识库 + 工具集 + 输出模板 + 审计日志 + 模型适配器
```
## 技术路线
@@ -17,42 +17,39 @@ V1 采用：
- Django 单体应用
- 独立 Agent Core 模块
- SQLite
- Chroma
- Chroma / fallback 检索双路径
- Django Templates
- Docker Compose
- OpenAI API 兼容的 LLM 与 Embedding 接口
默认不强依赖 Dify。系统预留 Adapter 设计，后续可以接入 Dify、OpenAI Agents SDK 或其他 Agent 编排平台。
默认不强依赖 Dify。系统保留 Provider / Adapter 边界，后续可接入 Dify、OpenAI Agents SDK 或其他 Agent 编排平台。
## 当前业务主线
当前系统围绕以下注册申报审核闭环展开：
1. 导入注册资料包，支持单文件、多文件和压缩包。
2. 解析文件元数据、页数、章节点和产品名称。
3. 自动创建资料包批次，并绑定审核会话。
4. 在审核智能体工作台选择文档范围并发起目录汇总、完整性检查、字段抽取、一致性核查或风险报告。
5. Agent Core 按场景配置执行 RAG 检索、工具调用、Prompt 编排、LLM 调用和结构化输出解析。
6. 会话页展示节点状态、能力卡、风险摘要、通知信息和导出入口。
7. Word 回填导出生成可下载 `.docx`，并记录到资料包和处理历史。
8. 审计模块保存成功与失败两类执行快照，并沉淀飞书通知留痕。
1. 导入注册资料包。
2. 解析资料包并识别产品名称。
3. 以解析后的产品名称创建或绑定对话会话。
4. 汇总文件目录与页数。
5. 对照法规要求检查完整性。
6. 抽取产品关键信息。
7. 自动填入注册申报表格或对照清单。
8. 核查跨文档一致性。
9. 输出风险预警、处理建议和飞书通知。
## 当前产品入口
## 当前产品形态
当前根路径 `/` 会直接进入审核智能体工作台，便于复试演示聚焦主链路。
当前原型和需求文档已经统一为 Agent 化产品形态，顶层入口固定为：
1. `审核智能体`
2. `资料包`
3. `知识库`
4. `处理历史`
对应关系如下：
1. `审核智能体` 是主执行入口，承载对话、模板提问、节点跳转和结构化结果。
2. `资料包` 是主业务对象，资料包与会话绑定，对话标题采用解析后的产品名称，并支持按产品名称或批次号搜索。
3. `知识库` 负责法规资料、业务资料、RAG 切片、字段 Schema、模板映射和飞书配置治理。
4. `处理历史` 用于按批次回看历史任务、关联会话、风险状态和通知留痕。
| 页面 | 路径 | 当前能力 |
|---|---|---|
| 审核智能体 | `/`、`/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/` | 维护后台模型数据 |
## 模块划分
@@ -62,19 +59,26 @@ apps.scenarios
apps.documents
apps.chat
apps.audit
apps.platform_ui
agent_core
```
职责边界：
- Django Apps 负责页面、数据、文件、日志等企业应用外壳。
- Agent Core 负责 RAG、工具调用、模型适配、结构化输出和 Agent 编排。
- RAG、工具调用和模型调用不直接写进 Django View。
- `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
universal-agent-demo/
DEMO-AGENT/
manage.py
requirements.txt
Dockerfile
@@ -85,103 +89,61 @@ universal-agent-demo/
config/
apps/
scenarios/
documents/
chat/
audit/
chat/
documents/
platform_ui/
scenarios/
agent_core/
rag/
tools/
schemas/
tools/
configs/
registration_overview.yaml
registration_completeness_check.yaml
registration_field_extraction.yaml
registration_consistency_review.yaml
registration_risk_report.yaml
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/
```
## V1 功能范围
## 已落地能力
V1 需要完成：
- 根路径已重定向到审核智能体，降低演示入口复杂度。
- 资料包导入支持 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，避免本地真实模型密钥导致测试走网络。
- 注册审核任务列表。
- 审核工作台。
- 资料上传与管理。
- 文档解析与入库。
- 目录与页数汇总。
- 法规完整性检查。
- 关键信息抽取与注册申报表格 / 对照清单自动回填。
- 一致性核查。
- 风险预警与审计日志。
- 模型 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
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
python manage.py migrate
python manage.py runserver
@@ -193,21 +155,11 @@ Docker 启动：
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
```
Docker Compose 会读取根目录 `.env`，并挂载 `./data` 与 `./configs`。
## 环境变量
项目当前通过 `os.environ` 读取配置，核心变量如下：
项目通过根目录 `.env` 和系统环境变量读取配置。`.env.example` 只作为模板，不应提交真实密钥。
```env
DJANGO_SECRET_KEY=replace-with-a-local-secret-key
@@ -223,35 +175,20 @@ 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`。
- `.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`。
- `EMBEDDING_API_KEY` 为空时自动复用 `LLM_API_KEY`。
- `EMBEDDING_BASE_URL` 为空时自动复用 `LLM_BASE_URL`。
- Django settings 初始化时会自动加载根目录 `.env`。
- 测试环境会在 `tests/conftest.py` 中固定 Mock Provider，避免误调用真实 LLM。
## 测试与验证
当前项目已经补有较完整的模块级测试，覆盖：
- 场景配置读取、非法配置容错和首页展示。
- 对话提交、文档范围传递、结构化结果展示。
- 文档上传、文本抽取、入库成功与失败提示。
- 审计日志落库、筛选、原始输出展示和 API Key 脱敏。
- Agent Core 的 Prompt 编排、结构化解析、RAG fallback 检索。
- Tool Registry 和内置工具行为。
- LLM / Embedding Provider 的配置与请求构造。
常用验证命令：
```bash
@@ -260,10 +197,15 @@ python manage.py check
docker compose config
```
说明：
当前测试覆盖：
- 测试环境默认通过 `tests/conftest.py` 固定 `LLM_PROVIDER=mock`，避免回归测试误走真实网络请求。
- 当前本地 `.env` 可能包含真实模型配置，但不会影响自动化测试稳定性。
- 项目配置、根路由和核心页面可访问性。
- 场景配置读取、非法 YAML 容错和场景列表展示。
- 资料包导入、压缩包展开、文档解析、入库状态和异常提示。
- 会话创建、对话提交、文档范围传递、结构化结果展示和 Word 导出。
- 审计日志落库、筛选、详情展示、通知留痕和敏感信息脱敏。
- Agent Core 的 Prompt 编排、结构化解析、RAG fallback、工具注册、LLM / Embedding Provider 请求构造。
- 平台治理页、指挥台、知识库、MCP 中心和 Skill 工作室展示。
## 文档入口
@@ -283,16 +225,32 @@ docker compose config
- [风险预警详细设计](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)
- [注册审核平台整体原型设计](docs/原型设计/1.整体原型设计.md)
- [单文件演示站 HTML](docs/原型设计/registration-prototype-demo.html)
- [协作与编码约定](AGENTS.md)
## 原型设计交付
## 复试改题流程
当前仓库已补充一套围绕注册申报审核主线的原型设计资产，供复试讲解、方案评审和后续页面实现直接参考：
拿到新题目后：
- 原型文档采用“总览 + 分页细设计”方式组织，覆盖资料包导入、审核任务工作台、法规完整性检查、字段抽取与字段池、一致性核查、风险预警、Word 回填导出、飞书通知视图和知识库治理台。
- `docs/原型设计/registration-prototype-demo.html` 提供单文件可交互 mock 演示站，当前已重构为 Agent 化界面，顶层为 `审核智能体 / 资料包 / 知识库 / 处理历史`。
- 资料包与对话会话已在原型中绑定，对话标题采用解析后的产品名称，资料包页支持按产品名称搜索并跳转对应会话。
- 该演示站仅使用 mock 数据，不依赖 Django 路由或真实 Agent Core 执行结果。
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 快速成型。