صفحهٔ اصلی گشت‌و‌گذار راهنما
ورود
huangyang
/
smqjh-agent
1
0
انشعاب 0
پرونده‌ها مشکلات 0 درخواست واکشی 0 ویکی
شاخه: master
شاخه‌ها تگ‌ها
smqjh-agent
/
docs
/
AGENT_DESIGN_REVIEW.md

AGENT_DESIGN_REVIEW.md 15 KB
لینک دائمی تاريخچه خام

市民请集合智能助手 Agent 设计复盘与改造方案

日期：2026-06-05

结论摘要

当前版本已经不是纯聊天窗口，而是一个“桌面端 + MCP + DeepSeek + 只读数据库工具”的 Agent 原型。它的优点是边界清楚、安全意识强、MCP 已经接管了 DeepSeek 和数据库配置；但它仍然更像“AI 帮忙挑固定任务”，还不是成熟的业务智能体。

更成熟的 Agent 应该是：模型根据用户目标自主规划，按需调用工具，拿到结果后继续判断是否还需要查数据库、查外部页面、生成表格或进入人工确认，直到给出可执行、可审计、可下载的结果。工具和安全边界由系统控制，决策和编排尽量交给模型。

一句话方向：从“前端/代码规则驱动的任务助手”升级为“模型驱动、工具受控、可追踪的业务 Agent”。

当前设计

当前项目分成两部分：

  • smqjh-admin-agent：Electron 桌面端，负责窗口、对话 UI、后台登录会话、IPC、表格渲染、导出和本地任务执行。
  • smqjh-mcp-server：Java MCP 服务，负责本机配置读取、DeepSeek 调用、只读数据库查询、业务工具注册和工具结果返回。

当前链路大致如下：

flowchart LR
  User["管理员自然语言输入"] --> UI["Electron 对话界面"]
  UI --> Orchestrator["AssistantOrchestrator"]
  Orchestrator --> Plan["MCP DeepSeek 工具规划"]
  Plan --> Tools["MCP 工具或本地任务"]
  Tools --> DB["MySQL 只读查询"]
  Tools --> Cloud["smqjh 网关接口"]
  Tools --> Market["慢慢买/苏宁公开价格线索"]
  Tools --> Summary["MCP DeepSeek 总结"]
  Summary --> UIResult["回答 + 表格 + 导出"]

已经具备的能力：

能力 当前状态
桌面端 EXE 原型 已有 Electron 框架和界面
后台登录会话 已支持，并持久化 token
DeepSeek 已迁移到 MCP 侧托管
数据库查询 已支持只读 SELECT、白名单表、默认 LIMIT、超时和只读事务
商品查询 已有 smqjh.product.lookup.summary
订单统计 已有 smqjh.order.count.query
通用 SQL 查询 已有 smqjh.database.readonly.query
商品比价 已支持系统价 + 慢慢买/苏宁线索
月结需求 已有 smqjh.settlement.monthly.plan 规划工具

当前主要问题

1. 编排仍然偏一次性

现在的主流程基本是：

  1. DeepSeek 判断一次要不要用工具。
  2. 最多执行 3 个工具。
  3. 再让 DeepSeek 总结结果。

这个流程缺少成熟 Agent 常见的循环能力：如果工具结果为空、SQL 字段不对、查到多个候选、需要再查明细，模型应该基于观察结果继续调用下一步工具，而不是直接结束或让用户自己查。

这解释了之前出现的体验问题：模型能识别意图，也能生成 SQL，但系统没有把 SQL 自动执行并回填结果。

2. 工具分布有点混乱

一部分能力在 MCP：数据库、DeepSeek、配置、订单统计、商品查询。

另一部分还在桌面端本地任务：商品比价、部分导出、市场页面抓取。

这样会导致模型眼里的工具不完整，桌面端还承担了太多业务逻辑。更好的做法是 MCP 统一暴露业务工具，桌面端只负责展示、会话和文件下载。

3. 表结构上下文不足

现在 DeepSeek 主要靠提示词里的“常用表、常用字段、SQL 示例”来生成查询。这个方式能跑起来，但不够稳。真正要让它智能查询数据库，需要把表结构、字段说明、业务口径、逻辑删除规则、金额单位等作为 MCP resources 或专门的 schema 工具提供。

否则模型会出现：

  • 表名猜错。
  • 字段单位搞错。
  • 商品关键词提取不准。
  • 同一个需求在不同问法下表现不一致。

4. 业务结果还没有完全“产物化”

用户要的是结果，不是过程。比如：

  • “帮我做表格”应该直接生成 Excel，并给出下载/打开入口。
  • “查订单物流状态”应该直接给表格。
  • “生成月结报告”应该输出结算表、核对表、异常清单。
  • “有差异”应该自动标记“需人工确认”。

当前已经能渲染一些表格，但文件产物、任务状态、异常清单和后续复核动作还需要变成一等能力。

5. UI 需要表达 Agent 的过程

现在用户看到“思考中”“处理中”时，不知道系统到底在做什么。成熟的 Agent UI 应该能显示：

  • 正在理解意图。
  • 正在调用哪个工具。
  • 正在查询哪类数据。
  • 已拿到多少条结果。
  • 是否生成文件。
  • 哪些地方需要人工确认。

这不是花哨交互，而是让管理员信任结果。

市场上主流 Agent 的正确制作步骤

下面不是某一家产品的唯一标准，而是目前 OpenAI、LangChain、Anthropic、MCP 等主流 Agent 体系共同体现出的落地路径。

标准步骤

阶段 应该做什么 关键产物
1. 定义业务目标 先明确 Agent 要替谁完成什么工作，不是先做聊天框 场景清单、成功标准、风险分级
2. 设计工具边界 把系统能力封装成工具，模型只能通过工具读写业务系统 Tool schema、权限、输入输出规范
3. 提供上下文 给模型表结构、接口说明、业务口径、示例和历史上下文 MCP resources、业务知识库、字段字典
4. 建立 Agent 循环 模型规划、调用工具、观察结果、继续规划、最终回答 多轮工具调用循环、最大步数、失败重试
5. 加安全护栏 对写操作、敏感数据、金额、发券、结算确认加人工审批 只读限制、审批流、审计日志、脱敏
6. 结构化输出 让模型输出表格、JSON、Excel、任务状态，而不是长文本 表格 schema、artifact 文件、下载入口
7. 做评测集 用真实管理员问题持续测试准确率 eval 用例、回归测试、工具调用追踪
8. 上线监控 记录调用链、失败原因、耗时、SQL、工具结果 tracing、日志、告警、成本统计

官方资料参考

当前方案与主流做法对比

对比项 当前 smqjh-agent 主流成熟 Agent 建议
决策方式 DeepSeek 一次性选择工具 模型循环规划，按观察结果继续行动 改成多步 agent loop
工具来源 MCP + 本地任务混合 工具集中注册，schema 清晰 统一迁移到 MCP
数据库能力 有只读 SQL 工具，但表结构靠提示词 schema/resource + SQL 执行 + 校验 增加 schema 查询工具
结果展示 文本和部分表格 文本、表格、文件、状态、依据分离 增加 artifact 层
人工确认 主要靠 dryRun 和文案 写操作前强制审批，差异自动标记 做审批/复核队列
业务知识 写在 prompt 和代码里 可维护的业务知识库和字段字典 建立 business-schema 文档/资源
可观测性 有日志，但链路不完整 每次工具调用、SQL、耗时、错误可追踪 增加 trace 面板
评测 暂无固定问题集 用真实问题做回归评测 建管理员问题 eval 集

推荐目标架构

flowchart TB
  UI["Electron 桌面端<br/>只负责展示、登录、文件入口"] --> Agent["Agent Runtime<br/>多步规划和工具循环"]
  Agent --> MCP["Java MCP Server<br/>统一工具和资源"]
  MCP --> LLM["DeepSeek<br/>意图判断、SQL 草拟、总结"]
  MCP --> Schema["业务 Schema Resource<br/>表结构、字段、业务口径"]
  MCP --> DB["MySQL 只读连接池<br/>SELECT 校验、限流、审计"]
  MCP --> API["smqjh-cloud API<br/>登录态、导出、业务接口"]
  MCP --> Market["外部价格工具<br/>慢慢买、苏宁、后续授权平台"]
  MCP --> Artifact["文件产物服务<br/>Excel、报告、异常清单"]

核心原则：

  1. 桌面端少做业务判断，只做展示和用户交互。
  2. MCP 统一提供工具、资源、提示词和安全边界。
  3. DeepSeek 负责判断“下一步查什么”，系统负责“能不能查、怎么安全查”。
  4. 数据库查询默认只读，写操作必须进入人工确认。
  5. 所有结果都要有依据：SQL、接口地址、外部请求地址、文件来源。

需要优先调整的点

第一阶段：让它真正像 Agent

目标：解决“识别到了但不执行”“问法变化就不会查”“回答不连贯”。

建议改动：

  1. 把 AssistantOrchestrator 改为多步循环：

    • 第一步让 DeepSeek 判断下一步动作。
    • 执行工具。
    • 把观察结果再喂给 DeepSeek。
    • 如果还需要查，就继续。
    • 最多 5 到 8 步，避免无限循环。

  2. 增加一个 MCP 工具：smqjh.database.smart.query。

    • 输入：管理员自然语言问题。
    • 内部：DeepSeek 根据 schema 生成 SELECT。
    • 校验：只读 SQL、安全表、LIMIT、逻辑删除。
    • 输出：执行 SQL、表格 rows、依据、口径说明。

  3. 增加 schema 工具或资源：

    • smqjh.schema.search
    • smqjh.schema.getTable
    • smqjh.schema.businessRules

  4. 明确规则：只要用户问的是业务系统事实，Agent 不应该回复“你可以去后台查”或“你可以执行 SQL”，而是自己调用工具。

第二阶段：把业务产物做完整

目标：让“查询、比价、月结、订单、物流、商品描述”都能输出表格和文件。

建议改动：

  1. 增加通用表格输出 schema：

    • title
    • columns
    • rows
    • summary
    • evidence
    • warnings

  2. 增加文件产物工具：

    • smqjh.artifact.excel.create
    • smqjh.artifact.open
    • smqjh.artifact.list

  3. 月结功能拆成工具链：

    • smqjh.settlement.enterprise.list
    • smqjh.settlement.export.inputs
    • smqjh.settlement.reconcile
    • smqjh.settlement.report.create
    • smqjh.settlement.confirmation.mark

  4. 商品价格对比工具继续保留，但迁移到 MCP：

    • 系统商品价先查数据库。
    • 外部价格优先查慢慢买和苏宁。
    • 结果必须包含平台、商品名、总价、折算单价、规格匹配度、依据地址。
    • 规格不一致时标记“需人工确认”。

第三阶段：上线治理

目标：支持多个客户端使用，降低对业务系统影响，并可审计。

建议改动：

  1. MCP 从“每台客户端本机服务”逐步演进为“内网中心 MCP 服务”。

    • 10 个客户端都各连 MySQL，短期可以接受。
    • 但长期更建议集中 MCP，统一连接池、限流、审计和权限。

  2. 数据库只读连接池：

    • 每个查询短连接也能用，但不利于限流。
    • 中心 MCP 可以用 HikariCP 之类连接池。
    • 限制最大连接数、查询超时、默认 LIMIT。

  3. 权限分级：

    • 只读查询：自动执行。
    • 导出文件：自动生成，但记录日志。
    • 发券、充值、结算确认、修改订单：必须人工确认。

  4. 追踪和评测：

    • 每次记录用户问题、选用工具、SQL、耗时、结果行数、失败原因。
    • 建一批真实问题作为回归评测，例如：
      • 当前百事可乐 500ml 的商品描述是什么？
      • 某手机号下了多少单？
      • 某订单物流状态是什么？
      • 铜仁移动 2026 年 5 月月结报告生成。
      • 某商品和慢慢买/苏宁做价格对比并导出 Excel。

针对当前痛点的具体调整

痛点 原因 调整方式
SQL 生成了但不执行 编排把 SQL 当成回复内容，没有进入工具执行 smart.query 内部生成并执行 SQL
问“商品描述”白屏 前端或工具结果异常没有兜底 加 ErrorBoundary、IPC 异常兜底、结果 schema 校验
问订单物流状态不会查 没有专门工具时编排不敢走通用数据库查询 通用业务事实统一走 database.smart.query
商品比价像固定规则 前端/本地任务承担了太多判断 迁移到 MCP，由 DeepSeek 决定搜索词和筛选口径
表格显示不稳定 文本 Markdown 和表格混在一起 回答文本和 tables 分离渲染
需要 Excel 但没有文件 文件不是一等产物 增加 artifact 工具，结果直接给文件入口
多客户端怕影响数据库 每客户端直连无法统一治理 中期改中心 MCP，连接池和限流

是否需要改成 Python + LangChain

不建议现在为了“更智能”直接大换语言。

原因：

  • 当前真正的问题不是 Java、TypeScript 或 Python，而是 Agent loop、工具 schema、schema 上下文、结果产物和评测没有完善。
  • Java MCP 很适合贴近现有 Spring/Java 业务系统，也方便后续做内网服务、权限和审计。
  • Electron + TypeScript 做桌面端合适，MCP 侧 Java 做业务工具也合适。

可以考虑的折中：

  • 短期：继续 Java MCP + Electron，把 Agent loop 和工具体系补完整。
  • 中期：如果要做复杂多 Agent 编排、长期记忆、评测平台，可以单独增加 Python/LangGraph 服务，但不替换现有 MCP。
  • 长期：MCP 保持为业务工具网关，Agent runtime 可以是 Java、TypeScript 或 Python，按团队维护成本选。

推荐下一步开发清单

优先级 P0：

  1. 新增 smqjh.database.smart.query。
  2. 桌面端编排改成多步工具循环。
  3. 工具结果和表格结果分离，前端稳定渲染。
  4. 加 ErrorBoundary，避免单次异常白屏。
  5. 输出内容必须包含依据。

优先级 P1：

  1. 商品比价迁移到 MCP。
  2. 增加 Excel artifact 工具。
  3. 增加 schema resource 或 schema 查询工具。
  4. 月结结算报告工具链落地。
  5. 增加工具调用日志和 trace 面板。

优先级 P2：

  1. 中心 MCP 部署方案。
  2. 数据库连接池、限流、慢 SQL 告警。
  3. 人工确认和审批队列。
  4. 管理员问题评测集。

最终目标体验

管理员输入：

当前百事可乐 500ml 的商品描述是什么？

Agent 应该自动：

  1. 判断这是业务系统事实查询。
  2. 查 schema，定位商品表和 SKU 表。
  3. 生成只读 SQL。
  4. 通过 MCP 执行。
  5. 返回商品描述、商品状态、价格、规格、依据 SQL。

管理员输入：

帮我生成铜仁移动 2026 年 5 月月结报告。

Agent 应该自动：

  1. 识别企业和月份。
  2. 调用导出接口或读取上传表。
  3. 读取订单、运费、员工积分表。
  4. 按规则计算商品总额、运费、积分抵扣、现金支付、差异。
  5. 标记需人工确认项。
  6. 生成 Excel。
  7. 给出下载入口和核对摘要。

管理员输入：

查一下这个订单的物流状态。

Agent 应该自动：

  1. 从输入中提取订单号。
  2. 查询订单表、配送字段、快递单号。
  3. 如果需要，调用物流接口或提示暂无物流接口。
  4. 用表格给出订单状态、配送状态、快递公司、运单号、更新时间和依据。

这才是我们要做的“智能体”，而不是让管理员根据按钮或固定任务项自己拼流程。