AGW Web Client

AGW Web Client 是面向智能体平台的前端展示框架。它把智能体后端输出的对话、事件流、计划、工具调用、人工确认、产物和用量数据，整理成一个可直接使用的 Web 工作台。

后端负责智能体如何运行；AGW Web Client 负责把运行过程展示清楚，并提供操作、调试和交付界面。

这个项目是什么

agent-webclient 是 AGW / AGENT 协议的 Web 客户端。它不包含智能体后端，也不定义模型、工具、调度、记忆或权限的最终语义；它消费上游 /api/* 与 /ws 能力，为智能体平台提供统一前端。

公开对话分享不由本项目运行或代理。Desktop 常驻 Worker 从 Agent Platform 获取 ConversationSnapshotV1、从本项目正在运行的 HTTP Host 获取模板并创建 HTML，Tunnel 在公开 /share/{shareId} 直接返回已存储的字节；WebClient 不参与匿名访问热路径。

对话静态 HTML 使用 src/export/ 的独立只读组件树和严格 ConversationSnapshotV1 parser。生产构建生成轻量 frontend/dist/export/conversation.template.html 和内容寻址的 conversation-export-assets/<hash>：模板只保留唯一 Snapshot JSON、初始 DOM、外部 CSS link 和外部 deferred runtime script，不包含内联样式或可执行脚本。资源路径固定到内容哈希，但 origin 不在构建时写死；浏览器使用 Blob parts，Desktop 使用 Worker 字节算法注入 Snapshot、CSS/JS 与 CSP 地址。React、ReactDOM 与 KaTeX 进入主 JS/CSS，ECharts 与 Mermaid 只在命中对应代码块时从同一不可变资产目录按需加载；所有入口资源带 SRI。Tunnel 托管不可变的内容寻址资产，WebClient 与 Desktop 都不参与匿名访问热路径。

接入以后，一个智能体后端可以快速拥有：

• 面向用户的对话主界面。
• 面向研发的事件时间轴、计划面板和 debug 侧边栏。
• 面向运营的 usage 统计和 budget 配置入口。
• 面向业务的 HITL、表单、审批、业务视图和文件预览能力。

能做什么

智能体对话工作台

主界面围绕“选 Agent、发消息、看执行、接管运行”组织。顶部按钮提供新对话、用量统计、debug 面板和运行状态入口；左侧用于 Agent 与对话导航；中间展示时间轴；底部 Composer 提供发送、附件、运行参数、模型覆盖、访问级别、steer 和 interrupt 等操作。

运行过程可观测

运行中的每个事件都会进入时间轴：消息内容、推理、规划、工具调用、来源、产物、等待用户输入和错误状态都能按顺序展示。结构化计划会进入计划面板，展示任务状态、进度、耗时和任务关联的运行内容。

Usage 与预算管理

前端支持 usage.snapshot，可以展示当前调用、最新 run、对话累计和上下文压缩相关用量，包括输入 / 输出 / 推理 token、总 token、缓存命中、LLM 调用数、工具调用数、上下文窗口、首字延迟、输出速度和预计费用。Agent 管理台支持维护 budget JSON，把 token、步骤、工具调用等预算约束交给后端执行。

Debug 联调侧边栏

右侧 debug 侧边栏可以按 run、request、content、reasoning、planning、plan、task、tool、awaiting、artifact、source、memory 等类型筛选事件，并查看原始事件、前端归并状态和可读 transcript。它是协议联调、现场排障和演示解释时最有用的面板之一。

人在回路交互

支持 question、approval、form、plan 四类 HITL 场景。智能体运行到关键节点时，可以向用户提问、请求审批、展示表单或发起计划确认；用户提交后，结果会回到运行流并在时间轴中回显。历史加载时以 Platform 返回的顶层 awaiting 为唯一可提交状态，孤立旧 ask 不会锁住输入框。

业务视图容器

支持 Viewport HTML 和 Frontend Tool iframe 容器。后端可以把业务页面、工具界面或表单视图交给前端展示，前端负责加载、初始化、通信、提交和关闭。Artifact 面板支持图片、PDF、HTML、文本、音频、视频、Office 等文件预览。

Chat 图片与 Artifact 使用后端返回的不含 chatId 的 ChatScope <relativePath> URL。前端统一分类：ChatScope 在内部加当前 chatId 后转为 GET /api/resource?file=...，普通 Agent 的 Workspace POSIX 绝对路径与 /tmp/... 转为带 chatId 的鉴权请求，Team 拒绝全部绝对路径；HTTP(S)、data:、blob: 原样使用。真实 /api/resource、file://、<currentChatId>/<relativePath> 和 traversal 都不是 Markdown 地址，不发起请求；历史 endpoint Markdown 不迁移且不再预览。

侧边栏与管理入口

左侧侧边栏聚合 Agent、Team、对话、pending awaiting、active run 和未读状态。管理页提供 Agent 定义查看、创建、编辑、排序和诊断；Registry 页面管理 provider、model、viewport server 与非 MCP tools，MCP 连接器及所属工具由独立页面管理。

能带来什么好处

• 更快搭平台：不用从零做智能体前端，对话、时间轴、计划、HITL、业务视图、用量统计和部署方式都已就绪。
• 更容易联调：事件流、debug 侧边栏和历史回放让协议问题、工具问题、状态问题更容易定位。
• 更适合交付：用户看到的不只是聊天框，而是一个能看计划、批操作、填表单、预览产物、接管运行的工作台。
• 更方便控成本：usage 让消耗可见，budget 让限制进入 Agent 定义，便于团队治理和运营复盘。

工作方式

前端只消费后端协议和资源，不替后端决定智能体如何规划、如何调用工具、如何鉴权或如何存储数据。后端仍是事实源，Web Client 负责把事实源展示成可用的产品界面。

快速开始

前置要求

• Node.js 18+
• npm 9+
• GNU Make
• 可访问的 AGW / AGENT API 服务

1. 初始化配置

cp .env.example .env

本地开发至少需要设置：

BASE_URL=http://localhost:11949

• PORT：可选。本地开发端口，未设置时默认使用 11948；也可由 CLI args、环境变量或 Desktop 宿主注入。
• BASE_URL：AGW / AGENT 后端地址，前端会把 /api/* 和 /ws 代理到这里。
• BACKEND_MODE：默认 platform，保留 Bearer Token；设置为 gateway 时使用同源 Session Cookie，并在最终 401 后进入 Gateway 配置的登录流程。

2. 安装依赖并启动

make install
make dev

打开 http://localhost:11948。

开发模式下，Webpack Dev Server 会代理：

• /api/* 到 BASE_URL
• /ws 到 BASE_URL
• /auth/* 到 BASE_URL，供 Gateway OIDC/SSO 使用

3. 测试和构建

make test
make build

构建产物输出到 dist/；dist/export/ 同时生成由 WebClient Host 提供的轻量模板、资产 manifest 和待同步到 Tunnel 的内容寻址资产集合。模板随 WebClient Program Bundle 发布，不再同步到 Agent Platform；npm run sync:conversation-export 只追加当前 Tunnel 资产集，不删除或覆盖历史资产。

Desktop Program Bundle 发布

项目支持打包为 Desktop 托管的 Program Bundle：

make release

等价命令：

make release-program

默认生成：

dist/release/agent-webclient-vX.Y.Z-darwin-arm64.tar.gz
dist/release/agent-webclient-vX.Y.Z-windows-amd64.zip

Program Bundle 包含 manifest.json、.env.example、frontend/dist/ 和 Desktop 启停脚本。它不内置后端服务，HTTP 托管、静态资源服务和代理路由由 Desktop main process 负责。Desktop Program Bundle 中的 PORT、DESKTOP_APP 和普通 /api 的 BASE_URL 由 Desktop 在 host-managed start 阶段提供，不写入 bundle .env；Agent Platform /ws 只由 Desktop Main Broker 持有，guest 不具备该路由。

DESKTOP_APP=true 只支持 canonical Platform Frame Port。Frame Port 缺失、transportVersion 不兼容或旧 Program manifest 都显示稳定阻断页，不安装兼容 adapter，也不会临时回落 Standalone；contract hash、WebClient bundle 和 Desktop 内置资源必须原子发布与回滚。

配置说明

环境变量契约以 .env.example 为准。

变量	必填	说明
PORT	否	本地开发端口；Program Bundle 运行时由 Desktop 宿主注入
BASE_URL	是	AGW / AGENT 后端 HTTP API 与主 /ws 基地址
BACKEND_MODE	否	platform（默认）保留 Token 认证；gateway 使用 Session Cookie、CSRF 与登录回跳
DEBUG_PANEL_ENABLED	否	是否显示调试面板入口
SETTINGS_MENU_ENABLED	否	是否显示设置入口
CONVERSATION_EXPORT_ASSET_ORIGIN	HTML 导出时是	Tunnel 资源 origin；生产必须为 HTTPS，本地开发可使用 loopback HTTP，例如 http://127.0.0.1:11961

本地开发和 Program Bundle 构建复用同一组变量名。.env 是本地真实配置，不提交版本库。

上游服务要求

AGW Web Client 需要一个可访问的上游智能体服务。常用入口包括：

• GET /api/agents?includeTeam=true：返回按最近 lastRunId 混排的 Agent / Team 扁平列表；Team 带 kind: "team"、对话统计与最近 chats。HTTP 与 WebSocket /api/agents 使用相同字段。
• GET /api/chats：可带 agentKey、mode；mode 只影响 Agent-owned chat，必须保留 Team-owned chat。
• GET /api/chat
• POST /api/query
• GET /api/attach
• POST /api/submit
• POST /api/interrupt
• POST /api/steer
• GET /api/viewport
• GET /api/resource
• GET /ws

前端统一按 ApiResponse 结构读取数据，并把错误包装为可展示的前端错误态。具体协议语义以后端 AGW / AGENT 服务为事实源。

项目结构

public/                 HTML 模板等静态入口资源
docs/                   中文专题设计文档和截图资源，专题按模块编号
src/app/                应用壳层、路由、布局、状态与页面入口
src/export/             静态对话 HTML 的独立只读渲染运行时
src/features/           对话、时间线、工具、计划、worker 等功能模块
src/shared/data/        API 端点注册、请求客户端、鉴权和轻量缓存
src/shared/styles/      全局主题变量和样式入口
src/shared/ui/          通用基础 UI 组件
src/shared/utils/       通用工具函数
scripts/                Program Bundle、协议同步和构建辅助脚本

深入文档

项目细节拆分在 docs/ 下。文档按两位编号分段，建议按模块阅读：

01 应用基础

• 01-应用基础-应用入口路由与布局壳层
• 02-应用基础-全局状态与Reducer
• 03-应用基础-运行时配置与功能开关

10 协议数据

• 10-协议数据-事件数据结构与协议枚举
• 11-协议数据-API端点注册与DTO
• 12-协议数据-请求路由缓存与鉴权错误
• 13-协议数据-流式传输SSE与WebSocket

20 对话输入

• 20-对话输入-对话加载回放与LiveSummary
• 21-对话输入-Composer输入与快捷交互
• 22-对话输入-消息发送路由与运行控制
• 23-对话输入-运行参数模型与访问级别
• 24-对话输入-附件上传与引用

30 运行时间线

• 30-运行时间线-时间线事件处理与渲染
• 31-运行时间线-Reasoning与Planning节点
• 32-运行时间线-计划事件与任务视图
• 33-运行时间线-Artifact发布与资源预览

40 交互容器

• 40-交互容器-Viewport视图容器
• 41-交互容器-FrontendTool容器协议
• 42-交互容器-HITL-Awaiting协议与状态机
• 43-交互容器-HITL-Question问题交互
• 44-交互容器-HITL-Approval审批交互
• 45-交互容器-HITL-Form表单HTML交互
• 46-交互容器-HITL-Plan计划决策

50 Worker管理

• 50-Worker管理-AgentTeam选择与Worker列表
• 51-Worker管理-Agent管理台
• 52-Worker管理-Registry管理台与工具目录

60 页面能力

• 60-页面能力-Memory页面
• 61-页面能力-Archive归档页面
• 62-页面能力-Automation页面
• 63-页面能力-Project文件浏览器

70+ 周边能力与交付

• 70-语音能力-语音输入ASR与TTS
• 80-界面基础-样式主题基础UI与国际化
• 81-宿主集成-Desktop宿主桥接
• 90-交付运维-开发代理与Desktop托管
• 91-交付运维-版本化打包与部署
• 92-质量验证-手工测试用例

常见问题

页面能打开，但接口请求失败

检查 .env 中的 BASE_URL 是否能被本地开发环境访问，并确认目标服务端口正确。

WebSocket 无法连接

确认上游服务实际提供 /ws。本地开发检查 Webpack Dev Server 代理配置，Desktop 中检查 host-managed 服务状态与 Main Broker 日志。

实时输出变慢或一次性刷出

检查上游事件是否逐帧 flush，并确认本地开发代理或 Desktop 托管层没有积压响应。

本地启动端口冲突

修改 .env 中的 PORT 后重新执行：

make dev

边界说明

• 本仓库只提供 Web 客户端，不包含智能体后端。
• 前端不定义后端协议的最终语义，只消费和展示后端事件。
• 模型、工具、权限、记忆、任务调度和资源存储以后端服务为事实源。
• 脱离可访问的 AGW / AGENT API 服务，无法完成核心联调。