194 lines
11 KiB
Markdown
194 lines
11 KiB
Markdown
---
|
||
title: 前端架构
|
||
created: 2026-04-13
|
||
updated: 2026-05-15
|
||
type: concept
|
||
tags: [frontend, architecture, convention, agent]
|
||
sources: [packages/frontend/src/, packages/frontend/src/modules/agent/store/chat.ts, packages/frontend/src/modules/agent/views/chat.vue, packages/frontend/src/modules/agent/components/chat/ChatComposer.vue, packages/frontend/src/modules/agent/views/memory.vue, packages/frontend/src/modules/agent/views/agent-edit.vue, packages/frontend/src/modules/agent/views/tools.vue, packages/frontend/src/modules/agent/views/skills.vue, packages/frontend/src/modules/agent/views/channel-management.vue, packages/frontend/src/modules/agent/components/channel-group-panel.vue, packages/frontend/src/modules/agent/tools/renderer-registry.ts, packages/frontend/src/modules/agent/components/tool-process-timeline.vue, packages/frontend/src/modules/agent/utils/tool-process-display.ts, packages/frontend/src/modules/geo/]
|
||
---
|
||
|
||
# 前端架构
|
||
|
||
前端基于 Vue 3 + Vite + Element Plus + Cool Admin。Agent 模块在近期重构后，重点从“普通聊天页面”升级为“Session Tree 快照消费 + 工具治理 projection + 子 Agent runtime 可视化”的管理和运行界面。
|
||
|
||
## 模块结构
|
||
|
||
业务模块仍遵循 Cool Admin 的模块化结构：
|
||
|
||
```text
|
||
modules/{name}/
|
||
config.ts
|
||
views/
|
||
components/
|
||
store/
|
||
hooks/
|
||
types/
|
||
static/
|
||
```
|
||
|
||
Agent 相关代码集中在 `packages/frontend/src/modules/agent/`。
|
||
|
||
## Agent Chat Store
|
||
|
||
`modules/agent/store/chat.ts` 是对话页状态核心。当前它不再只维护线性 message 数组，而是消费 [[session-tree-runtime]] 的 snapshot：
|
||
|
||
- `sessionMeta`: 当前 session 元信息。
|
||
- `entries`: session tree 节点列表。
|
||
- `entryById`: 节点索引。
|
||
- `childrenByParentId`: 父子索引。
|
||
- `activePathIds`: 当前活动路径。
|
||
- `visibleEntries`: 对话 UI 可展示节点。
|
||
- `subagentRuntimeByBatchId`: 子 Agent 批次运行状态。
|
||
- `toolRuntimeRoutesByBatchId`: 子 Agent 工具路由状态。
|
||
- `selectedEntryId`: 当前树面板选中的节点。
|
||
- `switchingLeafEntryId`: 正在切换为 leaf 的目标节点。
|
||
- `pendingLeafConfirmation`: 已选中但尚未真正切换的继续发送目标。
|
||
- `subagentEvidenceSummariesByEntryId`、`subagentProcessEventsByEntryId`、`subagentTaskPanelsByEntryId`、`subagentProjectionDiagnosticsByEntryId`: 统一消费后端 `subagentProjection` 后得到的展示态索引。
|
||
- 删除会话时，前端会优先从会话列表中取该会话自己的 `agentId`，再调用 `/open/netaclaw/session/delete`，避免 MySQL session-tree 会话因当前选中 Agent 不一致而走错 provider。
|
||
|
||
localStorage 只保存：
|
||
|
||
- `neta:agent-chat:last-tree-session`
|
||
- `neta:agent-chat:last-agent`
|
||
|
||
它不是完整历史存储。刷新后历史恢复依赖后端 session tree snapshot。
|
||
|
||
## Agent 对话页
|
||
|
||
`views/chat.vue` 的职责：
|
||
|
||
- 加载或恢复最近 Agent/session。
|
||
- 渲染普通消息、压缩摘要、分支摘要、自定义消息、子 Agent 批次和结果。
|
||
- 展示 token/thinking/tool 调用过程。
|
||
- 保证长对话区域可滚动，避免消息增多后底部不可见。
|
||
- 消费后端工具路由和 blocked reason，而不是在前端重新推导。
|
||
- 提供会话树节点选择、continue-from-entry、分支继续发送和 pending guard 交互。
|
||
- 对 `subagent_result` 节点优先渲染后端生成的 task panel、tool execution、evidence card、process timeline 和 projection diagnostics。
|
||
- 对 `subagent_batch` 节点只展示批次运行态和工具路由概览，不把它当作唯一回放来源。
|
||
- 流式工具卡片会保留工具参数和结构化 `rawResult`，例如 bash 工具会把命令展示在执行卡片里，流结束后仍能从 `skillExecutions` metadata 恢复。
|
||
- 当后端推送 `tool_confirmation_request` 时，`ChatComposer.vue` 会把输入区临时切换为工具确认 UI，显示工具名、命令/参数和风险原因；用户点击允许或拒绝后发送 `tool_confirmation_response`。这条链路主要保护 bash 删除、强制 git、数据库清空等高风险操作。
|
||
|
||
工具执行过程中的乱码问题通常来自命令执行 shell/编码和后端 stderr/stdout 处理；前端应只负责正确展示 UTF-8 文本和结构化结果。
|
||
|
||
## 工具管理页
|
||
|
||
`views/tools.vue` 面向全局 [[tool-governance]]：
|
||
|
||
- 查看工具 catalog 和 DB 同步结果。
|
||
- 调整全局启停、核心工具、是否可关闭、Prompt Hint、排序。
|
||
- 展示 `effectiveRuntimeProfile`、worker routing、blocked reason。
|
||
- 页面必须有可滚动容器，工具数量增加后不能裁掉底部内容。
|
||
|
||
## 记忆管理页
|
||
|
||
`views/memory.vue` 面向 [[memory-system]]：
|
||
|
||
- 左侧按 Agent 统计记忆数量，并标识 MySQL/SQLite 后端。
|
||
- 右侧支持 Agent、类型、关键词筛选和分页。
|
||
- 新增/编辑记忆时可写入 JSON metadata，编辑提交带 `updatedAt` 乐观锁。
|
||
- 类型管理弹窗读取 `memory_type` 服务，系统内置类型不可删除。
|
||
- Agent 下拉使用 `agent/page` 返回的 label，避免展示内部 name。
|
||
|
||
## Agent 编辑页
|
||
|
||
`views/agent-edit.vue` 面向单个 Agent 配置：
|
||
|
||
- 配置模型、Prompt、上下文压缩、辅助模型。
|
||
- 配置工具局部启停。
|
||
- 配置子 Agent 开关、并发、可用预设 Agent、可用工具。
|
||
- 展示后端 projection 中的 effective runtime profile 和 effective subagent allowed。
|
||
- 保存本地存储/workspace/shell/readonly 等配置时，应影响 [[tool-runtime-policy]] 推导。
|
||
|
||
Agent 编辑页不能只接入 i18n；核心是把后端新的工具治理和子 Agent 策略完整接进配置面。
|
||
|
||
## Skill 管理页
|
||
|
||
`views/skills.vue` 和 `components/skill-detail.vue` 已从简单列表升级为 [[skill-runtime]] 的管理入口：
|
||
|
||
- Skill 卡片展示 `classification`：`prompt`、`compute-entry`、`compute-toolkit`。
|
||
- 顶部加载 `/admin/netaclaw/skill/diagnostics`，按 error / warning 显示诊断横幅。
|
||
- 详情抽屉分为“基本信息 / 配置 / 诊断”。
|
||
- “配置”页读取 `/admin/netaclaw/skill/envSchema`，保存时调用 `/admin/netaclaw/skill/secrets`，只提交用户填写的新 secret。
|
||
- 安装 GitHub skill 后，如果元数据声明 setup 脚本，前端会弹窗确认后再调用 `installDeps`。
|
||
|
||
这意味着 Skill 页不再只是安装器 UI，也承担 compute skill 的运行前配置和健康检查职责。
|
||
|
||
## 数据源管理页
|
||
|
||
`packages/frontend/src/modules/base/views/data-source.vue` 是 [[mysql-data-source]] 的后台配置入口，挂在“系统管理 -> 数据源管理”。页面通过 `/admin/netaclaw/data-source/list|save|delete|test` 管理 MySQL 数据源。
|
||
|
||
页面职责包括：
|
||
|
||
- 配置 host/IP、端口、数据库、用户名、密码、SSL、连接超时和连接池上限。
|
||
- 端口使用普通输入框并校验 1-65535，避免 `el-input-number` 的步进控件和位数限制影响 MySQL 端口录入。
|
||
- 配置授权 Agent、表白名单、表黑名单、脱敏列、schema 可见性、最大返回行数、最大 JOIN 表数和查询超时。
|
||
- “测试连接”只把配置提交给后端测试，不在前端暴露密钥解密逻辑；密码展示使用 `hasPassword` 投影。
|
||
|
||
该页面依赖 [[base-module]] 的动态菜单路由。现有库如果没有“数据源管理”菜单，需要由后端启动同步 `base/menu.json` 与 `base/event/menu.ts`，而不是在 `modules/base/config.ts` 再加静态路由。
|
||
|
||
## 频道管理页
|
||
|
||
`views/channel-management.vue` 在 2026-05-14 后承担两类微信渠道配置：
|
||
|
||
- `weixin`：ClawBot 私聊助手，仍保留扫码登录、重连、断开和清空会话。
|
||
- `weixin-db`：本地 PC 微信数据库代理，要求 Windows + 已登录 PC 微信，表单要求填写 `wxid` 并做同 wxid 唯一性校验。
|
||
|
||
weixin-db 表单新增“微信自动回复（v4 桌面操作）”区块：
|
||
|
||
- `weixinReply.enabled` 控制是否启用双 Agent 自动回复。
|
||
- `desktopAgentId` 选择桌面操作 Agent；前端显示所有 Agent，后端保存时自动补齐 `weixin_desktop` toolset 和 `weixin_send_text` 路由。
|
||
- 可配置每群每分钟、每天上限、小号安全模式和水印策略。
|
||
- 频道卡片展示群聊启用数、微信版本、wxid 和连接状态。
|
||
|
||
`components/channel-group-panel.vue` 管理 channel 下群白名单、每群绑定 Agent 和每群回复身份。weixin-db 频道编辑页不再配置频道级默认 Agent、机器人别名或默认回复身份；每个群必须独立指定 reply agent 和回复身份。前端不直接处理本机微信数据库，消息读取、白名单缓存和自动发送都在 [[agent-channel]] 与 [[desktop-op-module]] 后端侧完成。
|
||
|
||
## 工具渲染
|
||
|
||
工具调用展示通过 `tools/renderer-registry.ts` 收敛，不建议在 chat 页面散落大量工具名判断。运行时策略文案通过 `tools/runtime-policy.ts` 收敛，保持与后端 projection 一致。
|
||
|
||
2026-05-07 后，长耗时工具和 compute-entry Skill 的 [[runtime-process-events]] 由 `tool-process-timeline.vue` 和 `tool-process-display.ts` 展示，可从实时事件或历史 metadata 恢复。例如 [[vehicle-damage-skill]] 的抽帧、检测、定位和复核阶段不再只能等待最终 JSON。
|
||
|
||
## Geo 前端模块
|
||
|
||
`packages/frontend/src/modules/geo/` 是新增的 [[geo-module]] 前端入口：
|
||
|
||
- `accounts.vue`：账号列表、平台选择、绑定 Agent/IP、启动浏览器、抓取 cookie、重置会话和切换 IP。
|
||
- `proxies.vue`：代理 IP 管理、绑定状态、区域/城市/套餐和健康信息。
|
||
- `dashboard.vue`：Geo 模块概览入口。
|
||
|
||
该模块不是 Agent 对话页的一部分，但会通过账号的 `agentId`、`sessionName` 和 cookie/profile 生命周期与 [[netabrowser-runtime]]、Agent 自动化任务发生关系。
|
||
|
||
对子 Agent 可视化还有一个新的边界约束：
|
||
|
||
- 前端 `store/subagent_projection.ts` 仍保留 legacy fallback 解析逻辑，但这是为了兼容历史数据。
|
||
- 当前实现的主路径是后端在 `session-tree/subagent_projection.ts` 生成 canonical projection，前端只做提取、排序、折叠和交互展示。
|
||
- 如果某次会话页面展示异常，应先排查后端 projection 是否缺失或 `fallbackUsed` 是否异常，而不是优先怀疑 Vue 组件渲染层。
|
||
|
||
这套结构使新增工具时需要同步考虑：
|
||
|
||
- 后端工具实现。
|
||
- catalog/governance/manifest。
|
||
- resolver projection。
|
||
- 前端工具管理页。
|
||
- Agent 编辑页。
|
||
- 对话页渲染。
|
||
|
||
## 相关页面
|
||
|
||
- [[agent-runtime]]
|
||
- [[session-tree-runtime]]
|
||
- [[tool-governance]]
|
||
- [[tool-runtime-policy]]
|
||
- [[tool-operations]]
|
||
- [[runtime-process-events]]
|
||
- [[geo-module]]
|
||
- [[netabrowser-runtime]]
|
||
- [[desktop-op-module]]
|
||
- [[subagent-session]]
|
||
- [[memory-system]]
|
||
- [[skill-system]]
|
||
- [[skill-runtime]]
|
||
- [[mysql-data-source]]
|
||
- [[websocket-gateway]]
|
||
- [[cool-admin-framework]]
|