docs(project): 同步当前实现与协作约定

README.md

@@ -107,6 +107,16 @@ V1 需要完成：
 - 模型 API 可配置。
 - Docker 一键启动。
 
+当前代码基线已经落地的能力：
+
+- 首页支持展示场景摘要、适用题型、RAG 状态、工具数量。
+- 非法 YAML 场景配置会被自动跳过，并在首页展示错误摘要。
+- 对话页支持问题输入、文档范围选择、结构化结果、引用片段、工具调用和审计入口展示。
+- 文档页支持上传、列表查看、手动入库、失败原因提示和重试。
+- 审计页支持列表摘要、按场景筛选、详情查看、原始输出展示和敏感信息脱敏。
+- Agent Core 已具备 Prompt 编排、OpenAI 兼容 Provider、结构化输出解析、RAG 检索和工具注册机制。
+- 测试环境默认固定使用 Mock Provider，避免误调用本地真实模型配置。
+
 V1 暂不重点做：
 
 - 多租户。
@@ -128,6 +138,19 @@ V1 暂不重点做：
 6. 用 2 到 3 个问题测试效果。
 7. 演示场景配置、知识库引用、工具调用、结构化输出和审计日志。
 
+## 当前页面概览
+
+当前项目包含以下主要页面：
+
+| 页面 | 路径 | 当前能力 |
+|---|---|---|
+| 场景首页 | `/` | 展示场景名称、描述、适用题型、RAG 状态、工具数和配置异常摘要 |
+| 对话页 | `/chat/<scenario_id>/` | 输入问题、勾选已入库文档、查看结构化结果、引用片段、工具调用和审计入口 |
+| 文档列表页 | `/documents/` | 查看文档状态、错误信息、上传时间并手动触发入库 |
+| 文档上传页 | `/documents/upload/` | 选择场景并上传 `.txt`、`.md`、`.pdf`、`.docx` 文件 |
+| 审计列表页 | `/audit/` | 查看执行摘要并按场景筛选 |
+| 审计详情页 | `/audit/<log_id>/` | 查看输入、最终回答、结构化输出、引用、工具调用、原始输出和错误信息 |
+
 ## 计划启动方式
 
 本地启动：
@@ -146,6 +169,16 @@ 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
+```
+
 ## 环境变量
 
 项目当前通过 `os.environ` 读取配置，核心变量如下：
@@ -181,6 +214,31 @@ CHROMA_PATH=data/chroma
 - 本地开发：复制 `.env.example` 为 `.env`，填入真实参数后运行。
 - Docker 演示：确认 `.env` 已配置后，再执行 `docker compose up --build`。
 
+## 测试与验证
+
+当前项目已经补有较完整的模块级测试，覆盖：
+
+- 场景配置读取、非法配置容错和首页展示。
+- 对话提交、文档范围传递、结构化结果展示。
+- 文档上传、文本抽取、入库成功与失败提示。
+- 审计日志落库、筛选、原始输出展示和 API Key 脱敏。
+- Agent Core 的 Prompt 编排、结构化解析、RAG fallback 检索。
+- Tool Registry 和内置工具行为。
+- LLM / Embedding Provider 的配置与请求构造。
+
+常用验证命令：
+
+```bash
+pytest
+python manage.py check
+docker compose config
+```
+
+说明：
+
+- 测试环境默认通过 `tests/conftest.py` 固定 `LLM_PROVIDER=mock`，避免回归测试误走真实网络请求。
+- 当前本地 `.env` 可能包含真实模型配置，但不会影响自动化测试稳定性。
+
 ## 文档入口
 
 - [V1 总需求文档](docs/需求分析/1.V1总需求文档.md)