# dms_agent

**Repository Path**: madalin/dms_agent

## Basic Information

- **Project Name**: dms_agent
- **Description**: 一个智能体终端，用于企业应用环境
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-17
- **Last Updated**: 2026-08-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# DMS Agent Workspace

企业级 DMS 智能工作台。

用户通过聊天提出业务诉求，后端通过 Hermes Agent 编排受控工具，以 Chat + Artifact 的方式展示结果。采用**可插拔业务系统架构**：Workspace（工作台）与业务系统（如 DMS）通过 MCP 协议解耦，业务系统作为独立进程运行，支持动态注册、本体描述和热插拔。

## 文档

| 文档 | 说明 |
|------|------|
| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | **架构与集成说明** — 第零节是「到底要启动什么」，配置前先看这个 |
| [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) | 故障排查 — 已实际发生并定位的问题 |
| [docs/PRD.md](docs/PRD.md) | 产品需求文档（早期 MVP 定义，部分内容已被实现超越） |

## 一句话版启动说明

**8001 和 8002 都要启动，不是二选一。** MCP 端点挂在这两个服务里面，没有独立的 MCP 进程。
Hermes 只连 8001，由 8001 转发到 8002（这一步负责注入 DMS token）。

详见 [docs/ARCHITECTURE.md 第零节](docs/ARCHITECTURE.md)。

## 架构概览

```text
┌─────────────┐     HTTP/SSE     ┌────────────────────┐     MCP      ┌──────────────┐
│   前端       │ ◄──────────────► │  后端 (Workspace)   │ ◄──────────► │  dms-server   │
│  React/Vite  │      :8001       │  FastAPI + SQLite   │    :8002     │  MCP Server   │
└─────────────┘                  └────────────────────┘              └──────────────┘
                                        │                                     │
                                        │ MCP (代理调用)                       │ X-Access-Token
                                        ▼                                     ▼
                                 ┌──────────────────┐              ┌──────────────────┐
                                 │  其他业务系统 MCP  │              │  真实 DMS API     │
                                 │  (可动态注册)      │              │  (JeecgBoot)      │
                                 └──────────────────┘              └──────────────────┘
```

- **Workspace（后端）**：通用工作台，管理会话、消息、Artifact、文件，通过 MCP 暴露通用工具（`create_artifact`、`read_file`、`get_ontology`、`call_business_tool`）
- **dms-server**：独立进程，将 DMS 业务工具（部门、员工、工作任务、汇报）暴露为 MCP Tools，对接真实 DMS API（JeecgBoot）
- **业务系统管理**：通过 `/api/systems` 和前端 `/systems` 页面动态注册业务系统，存储本体和概要到 SQLite

Hermes 只连接 Workspace MCP，**不直连 dms-server** —— DMS token 只有 `call_business_tool` 会注入。

## 当前能力

- **DMS 真实对接**：对接 JeecgBoot DMS API，支持验证码登录、token 加密存储、自动注入
- **工作任务查询**：查询工作任务列表，支持状态筛选，`Table Artifact` 动态列渲染
- **员工查询**：查询员工信息
- **工作汇报创建**：为指定任务创建工作汇报（写操作需确认）
- **任务详情查询**：查看任务详细信息
- **动态表格列**：`Table Artifact` 支持自动推断列名/类型，支持隐藏字段（`hidden_fields`）
- **分页限制**：列表工具强制 `page_size ≤ 10`，防止数据过多
- **HTML Artifact**：支持内嵌 HTML 渲染（仪表盘、报表、PPT 预览）
- **Markdown Artifact**：支持 Markdown 渲染 + 编辑/预览切换
- **多标签管理**：Artifact 面板支持多标签页，可切换/关闭
- **文件加载**：支持从 output 目录加载 HTML/Markdown 文件
- **文件上传**：支持拖拽/选择上传文件到会话
- **业务系统管理**：动态注册/编辑/删除业务系统，测试 MCP 连接，验证码登录
- **本体模型**：`ontology/` 目录存放业务系统本体描述参考模板（YAML/JSON）
- 工具调用审计、消息持久化、会话恢复、SSE 流式事件
- MCP Server：Workspace 和 DMS 各自独立暴露 MCP Tools（Streamable HTTP + SSE）
- 亮色 / 暗色主题切换

**已知不可用**：`dms_get_departments`（部门查询）—— DMS 端接口路径返回 404，详见
[docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md)。

## 技术栈

- 后端：FastAPI、SQLAlchemy 2.x、SQLite、Pydantic、MCP SDK
- dms-server：FastAPI、MCP SDK、Pydantic（独立进程，独立依赖）
- 前端：React、TypeScript、Vite、Tailwind CSS、Zustand、react-markdown、remark-gfm
- 通信：HTTP + SSE + MCP (Streamable HTTP / SSE)
- Agent：`MockHermesAgentClient`（mock 模式）/ `RealHermesAgentClient`（对接 Hermes）

## 目录结构

```text
backend/              Workspace 后端（FastAPI）
  app/api/            REST API 路由（chat、conversations、artifacts、files、systems 等）
  app/agent/          Agent 客户端（mock / real）
  app/mcp/            Workspace MCP Server（通用工具）
  app/tools/          Workspace 工具（artifact、file、ontology、business_caller、style）
  app/db/             SQLAlchemy 模型与会话
  app/services/       业务服务（SSE、审计、pending action、MCP 客户端等）
  app/auth/           认证与用户上下文
  data/               SQLite 数据库
  logs/               运行日志（自动轮转，已 gitignore）
  output/             文件 Artifact 输出目录

dms-server/           DMS 业务系统 MCP Server（独立进程，对接真实 DMS API）
  tools/              DMS 业务工具（department、employee、task、report）
  api_client.py       RealDMSClient — JeecgBoot API 客户端
  token_context.py    token 上下文管理（全局变量，见 ARCHITECTURE 第四节）
  mcp_server.py       MCP Server 构建与工具注册
  main.py             ASGI 应用入口（含 token 提取）
  config.py           配置（DMS_BASE_URL、端口等）
  dms/                旧 Mock 客户端（已废弃，可删除）

frontend/             React 工作台
  src/components/     UI 组件（chat、artifacts、sidebar、layout）
  src/pages/          页面（Home、Systems）
  src/api/            API 客户端
  src/stores/         Zustand 状态管理
  src/types/          TypeScript 类型定义

ontology/             业务系统本体参考模板（不会自动同步到数据库）
docs/                 架构、排查、需求文档
skills/               本地技能定义（当前为空，Hermes 通过 MCP 工具描述自主推断）
```

## 运行要求

- Python `3.11+`
- Node.js `18+`
- 下文命令为 Windows PowerShell 示例，均使用**相对路径**，请先 `cd` 到仓库根目录

## 后端启动（Workspace）

创建虚拟环境并安装依赖：

```powershell
cd backend
py -3.11 -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e ".[dev]"
```

启动后端：

```powershell
cd backend
.\.venv\Scripts\Activate.ps1
python -m uvicorn app.main:app --reload --port 8001
```

配置项在 `backend/.env` 中管理：

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `AGENT_MODE` | `mock` | `mock` 使用本地模拟 Agent，`real` 对接 Hermes |
| `HERMES_API_URL` | `http://127.0.0.1:8642` | Hermes 服务地址 |
| `HERMES_API_KEY` | `dms-agent-workspace-2026` | Hermes API Key |
| `CORS_ORIGINS` | `http://localhost:5173,...` | CORS 允许的前端地址 |
| `OUTPUT_DIR` | `backend/output` | 文件 Artifact 的输出目录 |
| `ONTOLOGY_SECRET_KEY` | (内置默认值) | 业务系统认证配置加密密钥 |

运行测试：

```powershell
cd backend
.\.venv\Scripts\Activate.ps1
python -m pytest tests
```

数据库迁移（Alembic）：后端启动时自动执行 `alembic upgrade head`，无需手动迁移。
修改 `models.py` 后生成迁移文件（pre-commit hook 会自动执行，也可手动）：

```powershell
cd backend
.\.venv\Scripts\Activate.ps1
alembic revision --autogenerate -m "描述变更"
```

健康检查与 MCP 端点：

```text
GET  http://127.0.0.1:8001/api/health
POST http://127.0.0.1:8001/mcp/workspace          # Streamable HTTP（主协议）
GET  http://127.0.0.1:8001/mcp/workspace/sse      # SSE 传输（兼容旧协议）
GET  http://127.0.0.1:8001/mcp/workspace/health
```

日志输出到 `backend/logs/app.log`（自动轮转，10MB/文件，保留 5 份）。`logging.basicConfig` 使用 `force=True` 确保 uvicorn reload 时日志配置不丢失。

## dms-server 启动（DMS 业务系统）

DMS 作为独立 MCP Server 运行，与 Workspace 后端解耦。

```powershell
cd dms-server
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e .
```

启动：

```powershell
cd dms-server
.\.venv\Scripts\Activate.ps1
python -m uvicorn main:app --host 127.0.0.1 --port 8002
```

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `DMS_PORT` | `8002` | dms-server 监听端口 |
| `DMS_BASE_URL` | `http://221.14.88.199:20061/jeecg-boot` | DMS API 基础地址 |

MCP 端点与工具清单见 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) 第六节。

## Hermes 配置

```yaml
# %LOCALAPPDATA%\hermes\config.yaml
mcp_servers:
  workspace-tools:
    url: http://127.0.0.1:8001/mcp/workspace
    enabled: true
  dms-tools:
    enabled: false        # 必须禁用：直连会绕过 token 注入
```

验证：`hermes mcp list`。完整说明与踩坑提示见
[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) 第二节。

## 前端启动

```powershell
cd frontend
npm install
$env:VITE_API_BASE_URL="http://127.0.0.1:8001"
npm run dev
```

类型检查与构建：

```powershell
cd frontend
npm run check
npm run build
```

前端默认请求 `http://localhost:8001`；如果本地端口不同，可通过 `VITE_API_BASE_URL` 覆盖。

## 业务系统管理

前端 `/systems` 页面提供业务系统的可视化管理：

- **注册新系统**：填写 MCP 地址、本体描述、概要等信息
- **测试连接**：一键测试 MCP 连接并拉取工具列表
- **DMS 登录**：带验证码的登录流程，token 加密存储到数据库
- **启用/禁用**：控制系统是否对 Agent 可用
- **编辑/删除**：管理系统配置

注册后，Workspace 的 `RealClient` 会自动将已启用系统的概要注入 Hermes 的 `system_message`，Agent 可通过 `get_ontology` 深入了解系统结构，通过 `call_business_tool` 代理调用系统工具。

> 录入本体和概要时注意格式要求（`summary_json` 必须扁平），
> 见 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) 第五节。

### DMS 登录流程

```text
用户点击"登录" → 加载验证码图片 → 输入用户名/密码/验证码
→ 工作台代理调 DMS /sys/login → 获取 token → 加密存入 auth_config
→ 系统状态变为 "connected"
```

## 交互验收

启动后端 + dms-server + 前端，并确认 `hermes mcp list` 配置正确后，按以下顺序验收：

1. **DMS 登录** — 系统管理页点"登录"，输入用户名、密码、验证码，确认状态变为 connected

2. **工作任务查询** — 输入 `查一下我的任务`

   预期：聊天区出现工具执行状态；右侧打开工作任务表格（≤10 条，id 等字段隐藏）；刷新页面后仍能恢复当前 Artifact

3. **员工查询** — 输入 `查一下张三`

   预期：右侧打开员工列表表格

4. **工作汇报** — 输入 `为任务1创建一个工作汇报`

   预期：弹出确认对话框，确认后创建成功

## SSE 事件

`message.delta`、`message.completed`、`tool.started`、`tool.completed`、`tool.failed`、`artifact.created`、`error`

## 安全与边界

- Agent 不直连业务系统，只能通过 Workspace MCP 的 `call_business_tool` 代理调用
- 写操作必须经过 Pending Action 确认
- 业务系统认证配置使用 `ONTOLOGY_SECRET_KEY` 加密存储
- 日志中不得记录 DMS Token 或敏感凭证
- 文件 API 限制在 output 目录内，防止路径遍历
- dms-server 与 Workspace 后端独立进程，故障隔离
- Workspace 的 MCP 会话上下文通过 Token 注册表传递，不依赖全局变量。
  **注意 dms-server 的 DMS token 仍是全局变量**，见 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) 第四节

## 版本演进

| 版本 | 内容 |
|------|------|
| M1–M2 | 项目骨架、会话、消息、SSE、Tool Registry、工具审计 |
| M3–M6 | Table / Detail / Form / Confirmation Artifact，Pending Action 确认 |
| M7 | Artifact V2 — 多标签、HTML/Markdown 支持、文件加载 |
| V4 | 可插拔业务系统底座 — DMS 独立进程、Workspace MCP 分离、业务系统管理、本体模型 |
| V5 | 工作台交互增强 — 思考动画、拖拽上传、ArtifactLinkCard、交付物恢复、动态表格列 |
| V6 | DMS 真实对接 — 验证码登录、token 管理、员工/任务/汇报、隐藏字段、分页限制 |

## 后续方向

- 修复 `dms_get_departments` 的 DMS 接口路径（当前 404）
- dms-server token 改为 per-request 存储，消除全局变量竞态
- 用户级认证：每个用户独立 token，替代当前系统级共享 token
- Token 主动刷新：基于过期时间主动刷新，替代当前被动检测
- 更多 DMS 接口：项目、审批、考勤等
- 表格前端分页：大数据量时支持前端分页加载
- MCP Server 增强：只读工具模式、工具权限配置
- Markdown 编辑保存（`PUT /api/files/write`）
- 输出目录浏览器（侧边栏文件树）
- MCP 上下文迁移至 Redis（多 Worker / 多进程场景）