可视化、可解释、工具驱动的 AI Agent 工作台
在线展示 · 视频演示 · 案例回放 · 快速开始 · 架构 · 文档 · 贡献
74 秒动画概览，介绍项目架构、知识检索、工具执行与轨迹复核。下方可直接播放 720p 版本（约 9.3 MB）。
insightagent-promo-v7.mp4
无需安装即可在展示站查看系统分层、任务执行流程，以及知识检索/计算和失败分支恢复的交互回放。展示站读取预设公开记录；实际提问、导入资料和调用模型请运行完整工作台。
截图使用真实工作台界面，通过隔离 HTTP fixture 加载公开案例；素材来源见说明。
InsightAgent 把对话、知识检索、工具执行和结果回放放在同一个工作台中。用户可以查看一项任务如何规划、调用了哪些工具、检索到哪些来源，以及回答如何流式生成；任务结束后，执行轨迹与用量仍可查询、导出和复核。
| 能力 | 当前实现 |
|---|---|
| Execution Trace | 时间线与流程图，展示工具输入、公开结果、依赖、并发分组及失败原因；实时流、历史回放和导出共用 TraceStep。 |
| 工具驱动 Agent | 结构化规划、实际工具执行、Observation 反馈与有界多轮决策；内建知识检索和安全表达式计算，支持配置 HTTP JSON 工具。 |
| Memory / RAG | 会话级语义记忆与用户隔离知识库；UTF-8 文本文件预览、后台导入、文档版本、来源引用、检索调试及共享库权限。 |
| 流式交互 | SSE 输出回答和执行状态，heartbeat、增量 Trace 同步、断线接管、取消与超时处理。 |
| 任务恢复 | 完整任务分支重跑；实验性内建顺序计划 checkpoint，可复用成功前缀，原任务保留。 |
| 治理与观测 | JWT / refresh 会话、用户设置与 Key 加密、RBAC-lite、审计、任务中心、用量统计及低敏请求日志。 |
| 工程验证 | OpenAPI 指纹、主题化回归测试、前后端发布门禁、浏览器 e2e、隔离 PostgreSQL/Chroma 与候选镜像协议验证。 |
“可解释”指可观察的执行依据。Trace 不暴露模型内部思维过程，也不能单独证明答案正确。工具执行以实际 action 与状态为准，模型对执行行为的自然语言描述仍需核对。
- 检索指定知识库并回答问题，复核引用来源和文档版本。
- 把检索事实交给计算或已配置的 HTTP 工具，查看实际输入与公开结果。
- 调试模型规划、取消或恢复任务，对照历史 Trace、导出与用量定位问题。
当前工作台面向有界任务执行和复核；不提供通用操作系统控制、可视化流程编辑或自动长期记忆召回。
flowchart LR
U[用户输入] --> P[结构化规划]
P --> T[工具执行 / DAG]
T --> O[安全 Observation]
O --> D{后续决策}
D -->|继续，受预算约束| T
D -->|结束| A[流式回答]
P -. 状态与证据 .-> X[Execution Trace]
T -. 输入与公开结果 .-> X
A -. 最终回答与用量 .-> X
X --> E[历史回放 / 导出]
首轮规划失败时采用既有规则回退；后续决策失败按任务错误处理。轮次、工具数和证据大小均有上限。完整执行边界见Agent 核心契约。
- 前端：Next.js 16、React 19、TypeScript、Ant Design、Zustand、TanStack Query / Virtual、React Flow。
- 后端：Python 3.14、FastAPI、Uvicorn、Pydantic，OpenAI-compatible 模型适配与模块化 tool runtime。
- 持久化：PostgreSQL 16 保存业务历史与执行账本；Chroma 保存会话 Memory 和知识库向量。
- 验证：unittest / Node tests、Playwright、GitHub Actions、Docker Compose。
InsightAgent/
├── backend/ FastAPI、执行器、持久化、Provider 与回归测试
├── frontend/ 工作台、Trace、治理页面与浏览器测试
├── showcase/ GitHub Pages 静态展示、交互架构与公开案例回放
├── scripts/ 发布门禁、验收、镜像与备份演练工具
└── docs/ 架构、契约、操作指南与验收证据
模块职责、数据边界及设计取舍见架构说明。
本地基线：Python 3.14、Node.js 24+、Docker Desktop / Docker Compose，以及可用的 PostgreSQL 和 Chroma。以下命令在项目根目录执行；首次安装需联网。
python3.14 -m venv backend/.venv
backend/.venv/bin/python -m pip install -r backend/requirements.txt
npm --prefix frontend ci
cp backend/.env.example backend/.env已有运行实例时先检查端口与健康状态，不要重复启动或重建存储。 首次使用、没有既有数据容器时启动依赖：
docker compose -f compose.full.yml up -d postgres chroma分别在两个终端启动应用：
后端
backend/.venv/bin/python -m uvicorn app.main:app --app-dir backend --host 127.0.0.1 --port 8000前端
npm --prefix frontend run dev打开 工作台，注册并登录；首个注册账号具有管理员角色。默认 mock 模式可验证离线演示路径。使用真实模型时，在“模型设置”中填写 remote、模型、兼容 API 地址和 Key，校验后保存。Key 仅发送给后端，不进入前端构建；连接校验不等于真实任务验收。
工作台支持桌面分栏与手机抽屉。模型设置优先展示连接信息，工具配置和运行诊断按需展开；知识库主表展示关键字段，Collection 完整标识在行详情中查看、复制。用量概览、趋势与排行分层展示，费用为估算值。
开发 Compose 使用开发凭据、浮动基础镜像和本地端口；单机试点使用独立的 生产配方与预检。start_insightagent.command 是本机便利脚本，会释放应用端口并执行依赖 up；已有服务或旧 Chroma 数据时优先使用手动命令，先读运行手册和备份说明。
- 在 mock 模式输入
计算 17 * 19，查看回答和 Calculator 的实际 action；mock 是明确演示模式。 - 在模型设置保存 remote 配置。导入 UTF-8 TXT/Markdown 到指定知识库，再询问资料中的事实或派生计算；通过 Trace 核对 source / document_version 与实际工具执行。
- 打开任务详情查看时间线、流程图和 JSON / Markdown 导出。失败后可编辑输入创建独立分支；实验性“从步骤继续”仅复用内建顺序计划的成功前缀。
任务 completed 表示执行和保存结束；回答正确性、引用质量及工具声明还需结合证据复核。计费展示是配置单价估算，不是供应商账单。
PostgreSQL 保存消息、任务、Trace 和用量；Chroma 保存会话级 Memory 与知识库向量。对话自动使用有界历史，Memory 提供手工调试入口；数据分工、隔离与 embedding 见架构说明。
实时展示、历史回放和导出使用同一执行记录。事件、终态、取消/超时、用量与恢复规则统一见运行时契约。
公开展示站已部署至 GitHub Pages。main 上展示目录或发布工作流的改动自动检查、构建并发布，PR 只检查。站点无需登录、后端或模型 Key；展示说明记录页面与素材边界，展示 README提供本地运行与发布命令，验收基线记录线上验证。
完整应用的本地实现与工程收尾已完成，现阶段按可复现问题维护。后端、前端、浏览器、隔离存储、真实 GLM 与历史候选镜像各有独立验证范围，详见验证基线与真实模型记录。完整应用的目标部署、真实业务资料和用户签收尚未验收；静态展示上线不代表完整应用已生产就绪。
写入工具并行、HTTP/DAG checkpoint 延期；PDF/Office/OCR 导入、内建网页搜索和图编辑器不在当前实现范围。开发与测试命令见贡献指南和运行手册，业务任务复核见验收指南。
从文档导航按展示、使用、维护或验收查找资料。接口与实现入口分别见后端 README、前端 README和展示 README；契约变更记录见API 变更记录。
README 提供项目与模块入口，专题文档维护稳定行为，验证基线记录当前状态和证据。使用问题与反馈入口见求助说明，贡献流程见贡献指南，社区协作遵循行为准则，安全问题见 SECURITY.md。项目采用 MIT License。