Bruce/DEMO-AGENT

Fork 0

Files

bruce efb06519d8 feat(chat): allow knowledge chat before upload

2026-06-04 22:16:54 +08:00

7.0 KiB

Raw Permalink Blame History

AGENTS.md

本文档约定本项目后续由人或编码 Agent 协作开发时需要遵守的边界、风格、实现顺序和文档同步要求。

项目定位

当前项目已根据真实笔试题切换为：

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

优先目标：

围绕 NMPA 体外诊断试剂注册申报资料场景完成可演示闭环。
保证本地可运行、可测试、可讲解。
保证代码结构清楚，业务流程能从页面、服务层、Agent Core 和审计日志串起来。
允许在保留主架构边界前提下进行大幅度业务重构。

架构原则

采用：

Django 单体 + 独立 Agent Core + Docker Compose

核心边界：

Django 负责页面、数据库、文件上传、导出文件、审计日志、通知留痕和后台管理。
Agent Core 负责 RAG、Prompt、工具调用、治理配置、模型适配和结构化输出。
Django View 不直接写大模型调用、向量检索和工具执行细节。
Agent Core 不依赖 Django View。
业务流程优先放在各模块 services.py，View 只负责请求处理、消息提示和模板渲染。

模块边界

config

负责 Django 项目配置、URL 总入口、环境变量、静态资源、上传路径、Chroma 路径和部署配置。

apps.scenarios

负责注册审核任务配置读取、场景元信息展示和非法 YAML 配置容错。

apps.documents

负责资料包导入、上传文件记录、压缩包展开、文本抽取、章节点归类、页数统计、资料包搜索、异常提示、触发 RAG 入库和导出记录维护。

apps.chat

负责审核工作台、会话列表、用户输入表单、文档范围选择、调用 Agent Core、展示结构化审核结果、补传资料和触发 Word 导出。

apps.audit

负责审计日志模型、日志写入服务、通知留痕、处理历史列表和详情页，以及审核留痕展示。

apps.platform_ui

负责知识库治理台、MCP 中心、Skill 工作室和审核指挥台等演示型平台页面。该模块可以展示治理对象和 mock 业务态势，但不要把主业务执行逻辑写进这里。

agent_core

负责注册审核 Agent 编排、RAG、工具注册、治理配置读取、LLM / Embedding Provider 和结构化输出。

当前实现状态

Django 单体骨架已完成，根路径 / 默认进入审核智能体。
当前主入口为 审核智能体 / 资料包 / 知识库治理台 / 处理历史，底层场景列表保留在 /scenarios/。
通用场景 YAML、Chat、Documents、Audit、Platform UI 和 Agent Core 已具备可重构基础。
资料包导入支持 PDF、DOCX、MD、TXT、ZIP、7Z、RAR。
资料包会自动绑定会话，标题优先使用解析出的产品名称。
审核智能体允许在未上传资料包时直接发起知识库问答，会话保持未绑定资料包状态并走 RAG 检索链路。
Agent Core 已具备 Prompt 编排、结构化解析、工具注册、RAG fallback / Chroma 双路径和 OpenAI 兼容 Provider。
Word 导出已支持生成最小 .docx，并按风险状态形成正式版或草稿版。
飞书通知当前为离线通知留痕，不直接发送真实飞书消息。
全量测试已覆盖主要模块行为，并默认隔离真实 LLM 网络调用。
当前需求文档已按真实笔试题重写到 docs/需求分析/。
当前详细设计文档放在 docs/详细设计/，原型资料放在 docs/原型设计/。

编码约定

Python 代码优先保持简单、直观、可讲解。
不为了抽象而抽象。
View 只做请求处理和页面渲染，复杂逻辑放到 services.py 或 agent_core。
配置化优先，业务场景不要写死在代码中。
工具函数必须通过 Tool Registry 注册。
模型调用必须通过 LLM Provider，不允许散落在业务代码中。
RAG 入库、检索和 Embedding 逻辑必须留在 Agent Core 或 Documents 服务边界内。
审计日志要记录成功和失败两种情况。
不在日志中保存 API Key、密钥或敏感环境变量。
新增或重构模块时，优先补清晰的中文注释，说明职责边界、输入输出和设计取舍。
页面模板优先直接表达业务信息，不在模板中堆积复杂逻辑判断。
测试优先覆盖服务层和核心编排逻辑，再由页面测试补齐关键展示行为。

文档约定

需求文档放在：

docs/需求分析/

详细设计文档放在：

docs/详细设计/

原型设计文档放在：

docs/原型设计/

场景配置放在：

configs/

重要设计变更需要同步更新：

README.md
docs/需求分析/1.V1总需求文档.md
相关模块需求文档
相关详细设计文档
AGENTS.md 中的协作边界与当前实现状态

推荐同步文档的场景：

新增用户可见页面或流程。
调整根路径、URL、环境变量、生效方式或部署命令。
修改资料包、会话、审计、通知或导出模型字段。
修改 Agent Core 的输入输出合约、结构化输出类型或节点状态口径。
新增工具、治理配置字段、场景配置字段或模板映射字段。
改变测试隔离策略、真实模型调用策略或 Docker 启动方式。

测试与验证约定

每个阶段至少验证：

Django 可以启动或 python manage.py check 通过。
根路径和审核智能体页面可以访问。
资料包导入流程可执行。
对话流程可执行，出错时页面有清晰提示。
审计日志能记录成功和失败。
Docker Compose 配置有效。

当前默认验证命令：

pytest
python manage.py check
docker compose config

补充约定：

若本地 .env 存在真实模型密钥，测试仍应保持可离线执行。
每完成一项功能或一轮重构后，应先跑相关测试，再跑全量测试或核心回归测试。
涉及页面结构时，至少补或更新对应页面测试。
涉及导出文件时，需要验证导出记录和下载路径。
完成改动后，按逻辑分组使用 Conventional Commit 风格提交到本地。

不优先做的事项

第一版不要优先做：

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

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

7.0 KiB Raw Permalink Blame History Unescape Escape