2026Technology-Competition/DESIGN.md

指摘管理系统（IMS）设计文档

文档版本	修订日期	修订内容
V1.0	2026-08-31	中期成果物：场景与价值、开发范式流程图、Agent 架构图、架构说明、工具/API 清单

配套文档：docs/design-spec-v6.0.md（概要设计说明书 V6.0，含完整需求与接口细节）、docs/ims-tech-overview.md（技术构成简要说明）。 本文档中的架构描述与 src 源码一一对应（评审交叉验证依据）。

---

1. 场景与价值

1.1 业务场景

在项目开发、文档审查、流程管理等环节中，质量问题（指摘）的发现、分配、整改、验证长期依赖人工跟进，普遍存在以下痛点：

痛点	现状问题
流程割裂	指摘创建、指派、催办、状态变更分散在多个表单/页面，操作繁琐、易遗漏
知识复用差	历史问题的根因分析与整改经验散落在个人手中，无法沉淀复用
统计耗时	周报、逾期清单、优先级统计依赖人工汇总
责任不清	指摘长期待办无人跟进，逾期无人催办
决策主观	根因分析、整改建议依赖个人经验，缺乏历史案例支撑

1.2 解决方案

构建 AI Agent 驱动的质量问题全生命周期管理系统（IMS）：用户通过自然语言指令即可让 Agent 自主完成指摘查询、分配、状态更新、催办、周报统计、知识检索等业务操作；高风险写操作由 Agent 发起、人工审批后执行（Human-in-the-loop）；Agent 具备长期记忆，可检索历史相似案例辅助决策；知识库文档全流程本地化存储与向量化，数据不出内网。

1.3 价值与效果总结

维度	价值	客观指标（源码可验证）
提效	自然语言直达业务闭环，替代多表单手工操作	8 个 Agent 工具覆盖查询/新建/更新/分配/催办/周报/分析/检索
人机协同	高风险操作强制人工审批，低风险操作自动执行	5 个写操作工具全部挂接审批流（agent_plans.approval_status）
知识沉淀	成功案例向量化入库，新问题自动检索相似案例	agent_memories 表 1536 维 pgvector + ivfflat 索引
可观测	思考链、工具调用、执行结果全程可审计	SSE 实时推送 6 类事件；tool_executions、ai_call_logs 全量审计
成本可控	本地 Ollama 推理 + DeepSeek API 自动降级	ModelRoutingService 双引擎路由与自动降级

说明：核心功能量化对比数据（如人工作业耗时 vs Agent 作业耗时）正在实测收集中，最终评审前补充（中期阶段进行中）。

1.4 项目性质

项目性质：新规（从零开发的新作品，非存量系统改造）。

---

2. 开发范式流程图

团队采用 "需求分析 → AI生成方案 → 人工审核 → AI编码 → 测试验证 → Bug修复 → 代码清理 → 提交部署" 的 AI 辅助开发范式。范式图各步骤名称与根目录 _AI_USAGE_LOG.md 的"范式步骤"列逐条对应，供评审对照验证。

flowchart LR
    A[需求分析] --> B[AI生成方案]
    B --> C[人工审核]
    C -->|审核通过| D[AI编码]
    C -->|审核驳回| B
    D --> E[测试验证]
    E -->|发现缺陷| F[Bug修复]
    F --> E
    E -->|通过| G[代码清理]
    G --> H[提交部署]
    H --> I[反馈迭代]
    I -.-> A

范式步骤	说明	人工角色
需求分析	梳理业务痛点，输出需求清单与验收标准	产品/架构师主导
AI生成方案	AI 生成技术方案、数据库设计与接口设计	AI 辅助
人工审核	对 AI 方案进行评审，驳回则迭代重生成	人工主导
AI编码	AI 按方案编写代码，人工确认技术选型	AI 主导
测试验证	编写并执行测试（后端单元测试 + 前端 E2E），验证业务闭环	人工主导
Bug修复	对测试发现的缺陷由 AI 定位修复	AI 辅助
代码清理	清理未使用 import/字段/方法，保持代码整洁	AI 辅助
提交部署	代码评审后合入 main 分支，构建部署验证	人工主导

---

3. Agent 架构图（感知-规划-行动-记忆）

3.1 总体架构图

graph TB
    User[用户 / 前端界面] -->|自然语言指令 + SSE 实时流| Orbit[AgentOrchestratorService 编排器]

    subgraph Perception[感知层]
        Ctx[buildIssueContext 指摘上下文] 
        Mem[MemoryService.searchSimilar 相似历史案例检索]
        KB[SearchService.search 知识库相似案例检索]
        Ctx --> Merge[上下文合并]
        Mem --> Merge
        KB --> Merge
    end

    subgraph Planning[规划层]
        PTE[PromptTemplateEngine 模板渲染<br/>SYS_ROLE_001 / PLAN_001 存库可版本化]
        Route[ModelRoutingService 模型路由<br/>Ollama 本地 / DeepSeek 云端 / 自动降级]
        Merge --> PTE --> Route
        Route -->|ToolCallResult 工具调用计划| Plan[AgentPlan 计划落库<br/>planSteps JSONB / status pending]
    end

    subgraph Action[行动层]
        Reg[ToolRegistry 8 个工具注册表]
        Plan --> Reg
        Reg -->|只读工具| Exec[runTool 执行]
        Reg -->|写工具| Approve{人工审批<br/>AgentApprovalRequest}
        Approve -->|批准| Exec
        Approve -->|拒绝| Reject[plan 置 rejected]
        Exec -->|ToolExecution 审计<br/>running/success/failed| Audit[全链路审计<br/>ai_call_logs + SSE 事件]
    end

    subgraph Memory[记忆层]
        Exec -->|完成| Save[MemoryService.add<br/>摘要+步骤向量化 1536维]
        Save --> VDB[(agent_memories<br/>pgvector + ivfflat)]
        VDB --> Mem
    end

    Audit --> User

3.2 感知（Perception）

Agent 执行时先收集四类上下文（AgentOrchestratorService.runPlan()）：

1. 指摘上下文：buildIssueContext() 拼接指摘编号/标题/描述/状态/优先级/阶段等字段；
2. 历史记忆检索：MemoryService.searchSimilar(title, 3) 从 agent_memories 表按向量相似度（1536 维，余弦距离）检索历史成功案例；
3. 知识库检索：SearchService.search() 对 knowledge_chunks 表执行 pgvector 向量检索（1 - (embedding <=> ?) AS score），召回相似领域案例；
4. 系统上下文：SystemContextBuilder.build() 注入当前用户、部门、角色及可用工具描述。

3.3 规划（Planning）

• 由 PromptTemplateEngine 渲染存库模板（SYS_ROLE_001 系统角色、PLAN_001 规划任务），模板支持版本管理（prompt_template_versions）与渲染日志（prompt_render_logs）；
• 经 ModelRoutingService.callWithTools() 调用 AI 引擎：provider 为 ollama 时走 Spring AI 原生 tool calling（模型只声明调用、不内部执行），provider 为 deepseek 时退化为纯文本调用；
• 模型返回的工具调用计划（ToolCallInfo）落库为 AgentPlan（planSteps JSONB、status=pending、记录 modelProvider），并在线程池中异步执行；
• 每分钟每用户限流 10 次（Redis agent:limit:{userId}:{mm}）。

3.4 行动（Action）

• 工具注册表：ToolRegistry 按名称注册全部 8 个工具（见 §5.1），未知工具抛业务异常；
• 写操作保护：ToolRegistry.isWrite() 判定为写操作（update_issue、create_issue、assign_pending、notify_overdue）且未开启 agent.auto-execute-high-risk 时，plan 进入 awaiting_approval 状态，由人工在「Agent 管理 / 审批中心」批准（approve）或拒绝（reject）后执行；
• 执行审计：每次工具执行写入 tool_executions（入参、状态、耗时 executionTimeMs），同时通过 SSE 向前端推送 thought / action / observation / result / prompt_info / model_info / error 事件，思考过程全程可见。

3.5 记忆（Memory）

• 计划完成后 finishPlan() 调用 MemoryService.add()，将目标摘要与解决步骤经嵌入模型向量化（1536 维）写入 agent_memories；
• 后续同类问题再次执行时，感知层自动检索这些历史案例，实现"经验越用越准"的长期记忆闭环。

3.6 异常恢复

异常场景	处理机制
主模型调用失败	ModelRoutingService 自动降级至另一 provider（auto-fallback-enabled=true）
DeepSeek 未配置 Key	抛出业务异常并提示配置，不阻塞本地 Ollama 链路
工具执行失败	ToolExecution 记录 failed 状态，结果经 SSE 推送，plan 状态可追溯
工具参数非法	parseArguments() 解析失败即终止该步骤，不静默跳过
超长任务	线程池（2 线程）异步执行，SSE 连接 10 分钟超时自动断开

---

4. 架构说明

4.1 技术栈

层级	技术选型	说明
前端	React 19 + TypeScript + Vite + Ant Design 6	SPA，Redux Toolkit 状态管理
后端	Java 17 + Spring Boot 3.5 + Spring Security 6	Maven 多模块（ims-common / ims-api / ims-service / ims-web）
AI 框架	Spring AI（ChatModel / EmbeddingModel 接口抽象）	原生 tool calling 接入 Ollama
AI 引擎	Ollama（本地，默认）+ DeepSeek API（备选）	双引擎自动降级，配置存 Redis 可热更新
数据库	PostgreSQL 16 + pgvector	向量检索 ivfflat（lists=100，1536 维）
缓存	Redis 7	限流、AI 配置热更新、JWT 会话
对象存储	MinIO	知识库文档原文（bucket ims-attachments）
数据迁移	Flyway	V1.0 ~ V2.10 共 22 个版本脚本
文档解析	Apache Tika / POI	pdf / docx / xls 文本抽取，chunk 200 / overlap 40 切片

4.2 前后端交互

界面	路径	Agent 能力
指摘详情页	/issues/:id	Agent 指令输入 + SSE 流式执行面板、审批/拒绝、切换人工模式
工作台	/dashboard	Agent 指令输入 + 执行流展示
AI 智能分析	/ai-analysis	AI 根因分析生成/查询、未分析指摘清单
知识库管理	/knowledge-base	文档上传（MinIO + 向量化）、检索
Agent 管理/审批中心	/system/agent-admin	待审批计划列表、批准/拒绝
批量输入	/batch-input	指摘批量登记

4.3 部署架构

数据库（PostgreSQL/Redis/MinIO/Ollama）全部容器化（docker-compose.yml），数据与向量索引全部本地部署，AI 推理默认本地 Ollama，资料不出内网（详见 docs/design-spec-v6.0.md §2）。

---

5. 工具 / API 清单

5.1 Agent 工具清单（backend/ims-service/.../agent/tool/）

工具类	工具名	功能	写操作	关键参数
IssueQueryTool	query_issue	查询指摘详情	否	issue_id
IssueUpdateTool	update_issue	更新指摘字段（状态/优先级/阶段/内容等）	是	issue_id, field, value
IssueCreateTool	create_issue	新建指摘	是	title, description, phase, priority 等
AssignPendingTool	assign_pending	批量分配待处理指摘	是	assignee_name
NotifyOverdueTool	notify_overdue	催办逾期指摘	是	content
WeeklyReportTool	weekly_report	生成周报统计（新增/关闭/逾期/高优先级）	否	—
AiAnalysisTool	ai_analysis	AI 根因分析与整改建议	否	issue_id
KnowledgeSearchTool	search_knowledge	知识库向量检索	否	query, top_k

5.2 主要 REST API

模块	端点（前缀 /api/v1）	说明
认证	POST /auth/login、/auth/refresh	JWT 登录 / 刷新令牌
指摘	GET/POST /issues、GET/PUT /issues/{id}、DELETE	指摘 CRUD + 状态流转
Agent	POST /agent/execute、GET /agent/plan/{planId}/stream（SSE）、POST /agent/approval/{planId}/approve|reject、POST /agent/suggest	Agent 执行、实时流、审批、字段建议
AI 分析	POST /ai-analysis/generate、GET /ai-analysis	根因分析生成与查询
知识库	POST /knowledge/documents/upload、GET /knowledge/search	文档上传、向量检索
Prompt	GET/PUT /prompt-templates	模板查看与热更新
系统	GET /system/users、/system/roles、/system/agent-config	用户、角色、Agent 配置

5.3 AI 配置项（application.yml）

ai:
  provider: ollama              # 默认推理引擎（可经 Redis ai:config 热切换）
  auto-fallback-enabled: true   # 主引擎失败自动降级
ollama:
  base-url: http://localhost:11434
  chat: { model: llama3.1:8b }
  embedding: { model: nomic-embed-text }
deepseek:
  api: { key: "" }              # DeepSeek API Key（经环境变量/Redis 配置注入，不硬编码）
agent:
  max-steps: 10
  auto-execute-high-risk: false # 写操作默认需人工审批
  user-rate-limit: 10           # 每用户每分钟执行上限

---

6. 安全与合规

项目	措施
认证授权	Spring Security + JWT（access + refresh 双令牌）、RBAC 角色权限、数据权限范围
敏感信息	DeepSeek API Key 不落仓库（空值占位，经 Redis 配置热注入）；仓库无密钥/token/.env
高风险操作	Agent 写操作强制人工审批（Human-in-the-loop）
审计	ai_call_logs（模型调用审计）、tool_executions（工具调用审计）、knowledge_search_logs（检索审计）、prompt_render_logs（Prompt 渲染审计）
数据安全	知识库原文与向量全部本地部署，数据不出内网