From e8c2a591fe286a9b9708d81f03bbb1d8fe1c93d2 Mon Sep 17 00:00:00 2001
From: bruce <sunzhiye01@outlook.com>
Date: Sat, 30 May 2026 09:25:01 +0800
Subject: [PATCH] =?UTF-8?q?docs(project):=20=E5=90=8C=E6=AD=A5=E5=BD=93?=
 =?UTF-8?q?=E5=89=8D=E5=AE=9E=E7=8E=B0=E4=B8=8E=E5=8D=8F=E4=BD=9C=E7=BA=A6?=
 =?UTF-8?q?=E5=AE=9A?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 AGENTS.md | 33 +++++++++++++++++++++++++++++++
 README.md | 58 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 91 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index da2f4d6..9733d63 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -69,6 +69,14 @@ Django 单体 + 独立 Agent Core + Docker Compose
 9. 完成内置工具系统。
 10. 补 Docker Compose 一键启动。
 
+当前仓库状态说明：
+
+- Django 单体骨架已完成。
+- 5 个预置场景 YAML 已接通首页和对话页。
+- Agent Core 已具备 Prompt 编排、结构化解析、工具注册和 RAG fallback / Chroma 双路径。
+- Chat、Documents、Audit 页面已经可以形成完整演示闭环。
+- 全量测试已覆盖主要模块行为，并默认隔离真实 LLM 网络调用。
+
 ## 编码约定
 
 - Python 代码优先保持简单、直观、可讲解。
@@ -79,6 +87,9 @@ Django 单体 + 独立 Agent Core + Docker Compose
 - 模型调用必须通过 LLM Provider，不允许散落在业务代码中。
 - 审计日志要记录成功和失败两种情况。
 - 不在日志中保存 API Key、密钥或敏感环境变量。
+- 新增或重构模块时，优先补清晰的中文注释，说明职责边界、输入输出和设计取舍。
+- 页面模板优先直接表达业务信息，不在模板中堆积复杂逻辑判断。
+- 测试优先覆盖服务层和核心编排逻辑，再由页面测试补齐关键展示行为。
 
 ## 文档约定
 
@@ -111,6 +122,14 @@ configs/
 - `README.md`
 - `docs/需求分析/1.V1总需求文档.md`
 - 相关模块需求文档
+- `AGENTS.md` 中的协作边界与当前实现状态
+
+推荐同步文档的场景：
+
+- 新增用户可见页面或流程。
+- 调整环境变量、生效方式或部署命令。
+- 修改 Agent Core 的输入输出合约。
+- 新增工具、审计字段或场景配置字段。
 
 ## 测试与验证约定
 
@@ -124,6 +143,20 @@ configs/
 - 审计日志能记录。
 - Docker Compose 可以启动。
 
+当前默认验证命令：
+
+```bash
+pytest
+python manage.py check
+docker compose config
+```
+
+补充约定：
+
+- 若本地 `.env` 存在真实模型密钥，测试仍应保持可离线执行。
+- 每完成一项功能或一轮重构后，应先跑相关测试，再跑全量测试或核心回归测试。
+- 完成改动后，按逻辑分组使用 Conventional Commit 风格提交到本地。
+
 ## 不优先做的事项
 
 第一版不要优先做：
diff --git a/README.md b/README.md
index 93da295..eb61ce8 100644
--- a/README.md
+++ b/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)