# 市民请集合 Web Agent Runtime

测试阶段先用浏览器运行成熟 Agent 编排，正式上线时再把同一套 runtime 接回 Electron/EXE。

## 架构

- Web UI：只负责聊天、表格渲染、工具轨迹展示。
- LangGraph Runtime：负责多步规划、工具调用循环、结果汇总。
- Java MCP：负责 DeepSeek、数据库只读查询、业务工具、配置和安全边界。

```mermaid
flowchart LR
  User["管理员 Web 对话"] --> Web["Web UI"]
  Web --> Runtime["LangGraph Agent Runtime"]
  Runtime --> MCP["Java MCP Server"]
  MCP --> DeepSeek["DeepSeek"]
  MCP --> DB["MySQL 只读查询"]
  MCP --> Tools["smqjh 业务工具"]
```

## 本地启动

先启动 MCP：

```powershell
..\scripts\start-mcp.ps1
```

再启动 Web Agent：

```powershell
..\scripts\start-web-agent.ps1
```

浏览器访问：

```text
http://127.0.0.1:5188
```

## 环境变量

| 变量 | 默认值 | 说明 |
| --- | --- | --- |
| `WEB_AGENT_HOST` | `0.0.0.0` | Web Runtime 监听地址 |
| `WEB_AGENT_PORT` | `5188` | Web Runtime 端口 |
| `SMQJH_MCP_URL` | `http://127.0.0.1:8765/mcp` | MCP 服务地址；给同事测试时可改为实际内网 IP |
| `SMQJH_MCP_TOKEN` | 空 | MCP token，当前为空即可 |
| `SMQJH_ENVIRONMENT_NAME` | `test-gateway` | 传给 DeepSeek 的环境名 |
| `SMQJH_BASE_URL` | `http://192.168.1.242:8080` | smqjh 测试网关 |

## 设计约束

- Runtime 不保存 DeepSeek Key、数据库账号或后台账号。
- 业务事实查询必须通过 MCP 工具执行，不让管理员自己复制 SQL。
- 工具输出中的 `columns/rows` 会独立渲染为表格。
- 写入、发券、结算确认等危险动作继续走 MCP 审批/人工确认。