---
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]]