From 1d8a52677000a648924da570c1e1eb062d6d54ef Mon Sep 17 00:00:00 2001
From: "zhiye.sun" <zhiye.sun@sinitek.com>
Date: Thu, 4 Jun 2026 16:38:18 +0800
Subject: [PATCH] =?UTF-8?q?docs(demo-agent):=20=E5=90=8C=E6=AD=A5=E5=BD=93?=
 =?UTF-8?q?=E5=89=8D=E5=AE=9E=E7=8E=B0=E7=8A=B6=E6=80=81=E4=B8=8E=E5=8D=8F?=
 =?UTF-8?q?=E4=BD=9C=E7=BA=A6=E5=AE=9A?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 AGENTS.md | 110 ++++++++++++----------
 README.md | 266 +++++++++++++++++++++++-------------------------------
 2 files changed, 174 insertions(+), 202 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 9bf2d4c..55661a6 100644
--- a/AGENTS.md
+++ b/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 快速成型。
diff --git a/README.md b/README.md
index b212593..91c6e25 100644
--- a/README.md
+++ b/README.md
@@ -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 快速成型。