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

AGENTS.md

@@ -1,6 +1,6 @@
 # AGENTS.md
 
-本文档约定本项目后续由人或编码 Agent 协作开发时需要遵守的边界、风格和实现顺序。
+本文档约定本项目后续由人或编码 Agent 协作开发时需要遵守的边界、风格、实现顺序和文档同步要求。
 
 ## 项目定位
 
@@ -13,8 +13,8 @@
 优先目标：
 
 - 围绕 NMPA 体外诊断试剂注册申报资料场景完成可演示闭环。
-- 保证本地可运行。
-- 保证代码结构清楚，方便讲解。
+- 保证本地可运行、可测试、可讲解。
+- 保证代码结构清楚，业务流程能从页面、服务层、Agent Core 和审计日志串起来。
 - 允许在保留主架构边界前提下进行大幅度业务重构。
 
 ## 架构原则
@@ -27,59 +27,67 @@ Django 单体 + 独立 Agent Core + Docker Compose
 
 核心边界：
 
-- Django 负责页面、数据库、文件上传、审计日志和后台管理。
-- Agent Core 负责 RAG、Prompt、工具调用、模型适配和结构化输出。
+- Django 负责页面、数据库、文件上传、导出文件、审计日志、通知留痕和后台管理。
+- Agent Core 负责 RAG、Prompt、工具调用、治理配置、模型适配和结构化输出。
 - Django View 不直接写大模型调用、向量检索和工具执行细节。
 - Agent Core 不依赖 Django View。
+- 业务流程优先放在各模块 `services.py`，View 只负责请求处理、消息提示和模板渲染。
 
 ## 模块边界
 
 ### config
 
-负责 Django 项目配置、URL 总入口、环境变量、静态资源、上传路径和部署配置。
+负责 Django 项目配置、URL 总入口、环境变量、静态资源、上传路径、Chroma 路径和部署配置。
 
 ### apps.scenarios
 
-负责注册审核任务列表、任务配置读取、任务元信息展示。
+负责注册审核任务配置读取、场景元信息展示和非法 YAML 配置容错。
 
 ### apps.documents
 
-负责注册资料上传、文件记录、章节点归类、页数与文本处理状态和触发 RAG 入库。
+负责资料包导入、上传文件记录、压缩包展开、文本抽取、章节点归类、页数统计、资料包搜索、异常提示、触发 RAG 入库和导出记录维护。
 
 ### apps.chat
 
-负责审核工作台、用户输入表单、调用 Agent Core 和展示结构化审核结果。
+负责审核工作台、会话列表、用户输入表单、文档范围选择、调用 Agent Core、展示结构化审核结果、补传资料和触发 Word 导出。
 
 ### apps.audit
 
-负责审计日志模型、日志写入服务、日志列表和详情页，以及审核留痕展示。
+负责审计日志模型、日志写入服务、通知留痕、处理历史列表和详情页，以及审核留痕展示。
+
+### apps.platform_ui
+
+负责知识库治理台、MCP 中心、Skill 工作室和审核指挥台等演示型平台页面。该模块可以展示治理对象和 mock 业务态势，但不要把主业务执行逻辑写进这里。
 
 ### agent_core
 
-负责注册审核 Agent 编排、RAG、工具注册、规则执行、LLM Provider 和结构化输出。
+负责注册审核 Agent 编排、RAG、工具注册、治理配置读取、LLM / Embedding Provider 和结构化输出。
 
-## 开发顺序
+## 当前实现状态
 
-建议按以下顺序推进：
-
-1. 创建 Django 项目骨架。
-2. 完成 Config 模块。
-3. 完成 Scenarios 模块，先展示 5 个场景。
-4. 完成 Agent Core 最小闭环，先返回模拟结果。
-5. 完成 Chat 页面，打通对话链路。
-6. 完成 Audit 模块，记录每次对话。
-7. 完成 Documents 模块，支持上传文件。
-8. 完成 RAG 入库和检索。
-9. 完成内置工具系统。
-10. 补 Docker Compose 一键启动。
-
-当前仓库状态说明：
-
-- Django 单体骨架已完成。
-- 通用场景 YAML、Chat、Documents、Audit 和 Agent Core 已具备可重构基础。
-- Agent Core 已具备 Prompt 编排、结构化解析、工具注册和 RAG fallback / Chroma 双路径。
+- Django 单体骨架已完成，根路径 `/` 默认进入审核智能体。
+- 当前主入口为 `审核智能体 / 资料包 / 知识库治理台 / 处理历史`，底层场景列表保留在 `/scenarios/`。
+- 通用场景 YAML、Chat、Documents、Audit、Platform UI 和 Agent Core 已具备可重构基础。
+- 资料包导入支持 PDF、DOCX、MD、TXT、ZIP、7Z、RAR。
+- 资料包会自动绑定会话，标题优先使用解析出的产品名称。
+- Agent Core 已具备 Prompt 编排、结构化解析、工具注册、RAG fallback / Chroma 双路径和 OpenAI 兼容 Provider。
+- Word 导出已支持生成最小 `.docx`，并按风险状态形成正式版或草稿版。
+- 飞书通知当前为离线通知留痕，不直接发送真实飞书消息。
 - 全量测试已覆盖主要模块行为，并默认隔离真实 LLM 网络调用。
 - 当前需求文档已按真实笔试题重写到 `docs/需求分析/`。
+- 当前详细设计文档放在 `docs/详细设计/`，原型资料放在 `docs/原型设计/`。
+
+## 推荐开发顺序
+
+后续新增或重构功能时，建议按以下顺序推进：
+
+1. 先确认需求文档、详细设计或当前页面是否需要同步调整。
+2. 补或调整服务层测试、Agent Core 测试或页面关键展示测试。
+3. 在对应模块的 `services.py` 或 `agent_core` 中实现核心逻辑。
+4. View 只接入服务层结果，模板只做直接展示。
+5. 若涉及用户可见入口，同步更新模板、README 和相关需求/设计文档。
+6. 运行相关测试，再运行核心回归验证。
+7. 按逻辑分组使用 Conventional Commit 风格提交到本地。
 
 ## 编码约定
 
@@ -89,6 +97,7 @@ Django 单体 + 独立 Agent Core + Docker Compose
 - 配置化优先，业务场景不要写死在代码中。
 - 工具函数必须通过 Tool Registry 注册。
 - 模型调用必须通过 LLM Provider，不允许散落在业务代码中。
+- RAG 入库、检索和 Embedding 逻辑必须留在 Agent Core 或 Documents 服务边界内。
 - 审计日志要记录成功和失败两种情况。
 - 不在日志中保存 API Key、密钥或敏感环境变量。
 - 新增或重构模块时，优先补清晰的中文注释，说明职责边界、输入输出和设计取舍。
@@ -99,20 +108,20 @@ Django 单体 + 独立 Agent Core + Docker Compose
 
 需求文档放在：
 
-```text
-docs/
-```
-
-需求分析文档放在：
-
 ```text
 docs/需求分析/
 ```
 
-设计文档放在：
+详细设计文档放在：
 
 ```text
-docs/设计文档/
+docs/详细设计/
+```
+
+原型设计文档放在：
+
+```text
+docs/原型设计/
 ```
 
 场景配置放在：
@@ -126,26 +135,28 @@ configs/
 - `README.md`
 - `docs/需求分析/1.V1总需求文档.md`
 - 相关模块需求文档
+- 相关详细设计文档
 - `AGENTS.md` 中的协作边界与当前实现状态
 
 推荐同步文档的场景：
 
 - 新增用户可见页面或流程。
-- 调整环境变量、生效方式或部署命令。
-- 修改 Agent Core 的输入输出合约。
-- 新增工具、审计字段或场景配置字段。
+- 调整根路径、URL、环境变量、生效方式或部署命令。
+- 修改资料包、会话、审计、通知或导出模型字段。
+- 修改 Agent Core 的输入输出合约、结构化输出类型或节点状态口径。
+- 新增工具、治理配置字段、场景配置字段或模板映射字段。
+- 改变测试隔离策略、真实模型调用策略或 Docker 启动方式。
 
 ## 测试与验证约定
 
 每个阶段至少验证：
 
-- Django 可以启动。
-- 首页可以访问。
-- 场景列表可显示。
-- 对话流程可执行。
-- 出错时页面有清晰提示。
-- 审计日志能记录。
-- Docker Compose 可以启动。
+- Django 可以启动或 `python manage.py check` 通过。
+- 根路径和审核智能体页面可以访问。
+- 资料包导入流程可执行。
+- 对话流程可执行，出错时页面有清晰提示。
+- 审计日志能记录成功和失败。
+- Docker Compose 配置有效。
 
 当前默认验证命令：
 
@@ -159,6 +170,8 @@ docker compose config
 
 - 若本地 `.env` 存在真实模型密钥，测试仍应保持可离线执行。
 - 每完成一项功能或一轮重构后，应先跑相关测试，再跑全量测试或核心回归测试。
+- 涉及页面结构时，至少补或更新对应页面测试。
+- 涉及导出文件时，需要验证导出记录和下载路径。
 - 完成改动后，按逻辑分组使用 Conventional Commit 风格提交到本地。
 
 ## 不优先做的事项
@@ -172,5 +185,6 @@ docker compose config
 - 深度 Dify 集成。
 - 微服务拆分。
 - 分布式任务队列。
+- 真实飞书发送链路。
 
 这些内容可以作为后续增强，不应影响 V1 快速成型。