docs: 中期成果物整理 - 新增DESIGN.md/AGENTS.md、更新README、规范化文件命名与路径

README.md

@@ -1,7 +1,24 @@
 # 指摘管理系统（IMS）
 
+**项目性质：新规**（从零开发的新作品）
+
 基于 AI Agent 驱动的质量问题全生命周期管理系统。
 
+## 项目概述
+
+针对项目开发、文档审查、流程管理中质量问题跟踪效率低、知识无法沉淀复用、高风险操作缺乏管控等痛点，本系统以 **Agent（智能体）** 为核心决策与执行单元：用户通过自然语言指令即可让 Agent 自主完成指摘查询、新建、分配、状态更新、逾期催办、周报统计、根因分析、知识检索等业务操作；高风险写操作由 Agent 发起、人工审批后执行；Agent 具备长期记忆（pgvector 向量检索历史案例）；知识库文档本地化存储与向量化，数据不出内网。
+
+## 整体功能说明
+
+| 模块 | 功能 |
+|------|------|
+| 指摘管理 | 指摘全生命周期（创建/分配/整改/验证/关闭）、状态流转、优先级/阶段/影响等级管理、附件、批量登记 |
+| Agent 引擎 | 自然语言指令驱动业务闭环：感知（上下文+记忆+知识检索）→ 规划（LLM 工具调用计划）→ 行动（8 个工具，写操作人工审批）→ 记忆（案例向量化入库），SSE 实时流展示思考/行动/结果 |
+| AI 智能分析 | 根因分析、整改建议、未分析指摘清单 |
+| 知识库 | 文档上传（Tika/POI 解析 + 切片 + 1536 维向量化）、pgvector 相似检索 |
+| 工作台 | 指标看板、Agent 指令快速入口 |
+| 系统管理 | 用户/角色权限、Agent 管理审批中心、Prompt 模板热更新、系统日志 |
+
 ## 技术栈
 
 | 层级 | 技术选型 |
@@ -16,14 +33,19 @@
 ## 目录结构
 
 ```
-├── backend/             后端（Maven 多模块）
-│   ├── ims-common/      公共模块（工具类、统一返回结构）
-│   ├── ims-api/         API 模块（Controller 定义、DTO）
-│   ├── ims-service/     业务模块（Entity、Repository、Security）
-│   └── ims-web/         Web 启动模块
-├── frontend/            前端（Vite + React）
-├── docs/                设计文档
-└── docker-compose.yml   数据库层（PostgreSQL + Redis + MinIO）
+├── README.md              01 项目说明（本文件）
+├── DESIGN.md              02 设计文档（范式图 + Agent 架构图）
+├── AGENTS.md              AI 协作方式与项目说明
+├── backend/               后端（Maven 多模块）
+│   ├── ims-common/        公共模块（工具类、统一返回结构）
+│   ├── ims-api/           API 模块（Controller 定义、DTO）
+│   ├── ims-service/       业务模块（Entity、Repository、Security）
+│   └── ims-web/           Web 启动模块
+├── frontend/              前端（Vite + React）
+├── tests/                 04 实验报告（测试代码 + 覆盖率报告，进行中）
+├── data/                  样本数据（进行中）
+├── docs/                  设计文档、演示视频（demo.mp4 待录制）
+└── docker-compose.yml     数据库层（PostgreSQL + Redis + MinIO + Ollama）
 ```
 
 ## 快速启动
@@ -165,5 +187,48 @@ npm run dev
 
 ## 分支说明
 
-- `master` — 项目骨架，各组基于此分支创建功能分支
-- 各功能模块在独立分支上开发，完成后合并回 master
+- `main` — 成果物主分支（评审系统按此分支拉取），持续提交演进
+
+## 效果总结（核心指标摘要）
+
+| 指标 | 数值 | 状态 |
+|------|------|------|
+| Agent 工具 | 8 个（查询/新建/更新/分配/催办/周报/分析/知识检索） | 已完成 |
+| 写操作审批保护 | 5 个写工具全部挂接人工审批流 | 已完成 |
+| 后端模块 | Maven 4 模块，22 个 Flyway 迁移版本（V1.0~V2.10） | 已完成 |
+| 知识库向量检索 | pgvector 1536 维 + ivfflat 索引，余弦相似度召回 | 已完成 |
+| Agent 闭环成功率 | 实测数据收集中 | 进行中（最终评审前补齐） |
+| 人工作业 vs Agent 作业耗时对比 | 实测数据收集中 | 进行中（最终评审前补齐） |
+| 测试用例与覆盖率 | 后端单元测试 + 前端 Playwright E2E（9 个 spec） | 进行中（测试执行报告后续补充） |
+
+## 团队分工
+
+| 成员 | 角色 | 职责 |
+|------|------|------|
+| （待填写） | 产品/架构 | 需求分析、总体设计、方案评审 |
+| （待填写） | 后端开发 | Spring Boot 业务实现、Agent 引擎、知识库 |
+| （待填写） | 前端开发 | React 界面、SSE 交互、E2E 测试 |
+| （待填写） | 测试/文档 | 测试执行、实验报告、演示视频 |
+
+## 规模与技术难度自我评估
+
+| 评估项 | 说明 |
+|--------|------|
+| 代码规模 | 后端 ~100 个 Java 类（实体/仓库/服务/控制器/Agent 工具），前端 10+ 页面组件 |
+| 技术难点 | ① Agent 感知-规划-行动-记忆闭环设计；② Ollama/DeepSeek 双引擎路由与自动降级；③ pgvector 向量检索与 ivfflat 索引调优；④ Spring AI 原生 tool calling 与人工审批（Human-in-the-loop）集成；⑤ SSE 实时流式交互；⑥ Prompt 模板存库版本化热更新 |
+| 集成复杂度 | PostgreSQL + pgvector、Redis、MinIO、Ollama、DeepSeek 五类外部依赖统一编排（docker-compose） |
+| 团队规模 | 4 人小组，2~3 周内完成骨架到可运行闭环 |
+
+## 中期提交状态说明
+
+按《参赛成果物提交规范·赛道一》§1，本仓库为中期提交（2026-08-31），以下成果物状态：
+
+| 成果物 | 状态 |
+|--------|------|
+| 01 README.md | 已完成 |
+| 02 DESIGN.md | 已完成 |
+| 03 源码（Agent + 界面 + 存储 + 工具） | 已完成，可运行 |
+| 04 tests/ + coverage/ | 测试已开发，执行报告/覆盖率报告后续提交 |
+| 05 _AI_USAGE_LOG.md | 持续更新 |
+| 06 演示视频 demo.mp4 | 待录制（最终评审前提交） |
+| 样本数据 data/ | 待补充 |