havline-native/app-src/docs/agent-view-refactor-plan.md

公网 Agent 页（AgentView.vue）整合整改方案

目标：把「公网 Agent」页从"功能堆叠"整理成状态 → 控制 → 生命周期 → 输出四段式结构， 信息层级清晰、操作归属明确、危险操作可控，并完全符合 havline-page-ui 页面 UI 标准。

参照页：DdnsView.vue（状态卡 + 提示）、CertificatesView.vue（统计卡规格）、ProxyView.vue（分组与按钮区）、SettingsView.vue（分区）。 更新日期：2026-09-23

---

一、现状问题清单

#	问题	具体表现	影响
1	状态与操作混在一起	4 张状态卡只覆盖「Agent 连接 / frps 服务 / 80 / 443」；而 Agent 版本、frps 启动命令、配置路径、开机自启、7000 端口散落在「frps 服务控制」卡的 field-grid 里，与启停按钮同处一卡	看状态要跨两张卡，操作区被字段挤占
2	两个 agent-page-grid 列宽漂移	均用 repeat(auto-fit, minmax(360px, 1fr))，窗口宽度变化时卡片宽度与列数跳动，与标准页 repeat(4, minmax(0,1fr)) 的稳定网格不一致	视觉不整齐，窄屏断裂点不可预期
3	loading 粒度太粗	所有按钮都用 :loading="agentActionId === server.id"——任何操作进行中，页面全部按钮一起转圈	无法分辨在跑哪个操作，也无法阻止并发操作
4	输出全部塞进一个 agentOutput	探测 / 安装 / 卸载 / SSH 诊断 / frps 启停 / 下发配置 / 安装 frps 七类输出共用一个 ref，显示在「Agent 生命周期」卡底部	输出归属不明；执行「重启 frps」后输出出现在 SSH 卡里，语义错位
5	日志与输出分居两卡	「frps 最近日志」独立成卡，agentOutput 在另一张卡	排障时要在两处来回看
6	危险操作无二次确认	「卸载（含数据）」按钮点击即执行，rm -rf /var/lib/havline-agent 不可逆	误点即丢路由与证书
7	页面级提示缺失	agent 未连接、frps 未安装等状态只在卡片里体现，没有 n-alert 引导（技能要求：页面级提示放 PageHeader 之后）	新用户不知道下一步该去哪一页
8	跳转卡占位浪费	「公网 Nginx 反代」整卡只放一句说明 + 一个跳转按钮	占掉半行网格，信息密度低
9	轮询与用户操作耦合	10 秒 refreshAll() 里设置 agentActionId，与用户点击共用同一状态	轮询时按钮闪烁 loading
10	默认版本硬编码	frpsInstallVersion.value?.trim() || '0.71.0'，与「官方版本列表」加载结果脱节	列表加载成功后默认值仍可能是写死的旧版本
11	空态用字符串	日志空时渲染 '暂无日志' 文本	与标准页的 EmptyState 不一致
12	窄屏断点不全	只有 @media (max-width: 900px)，缺 760px 档（技能第 7 节）	手机宽度下卡片内按钮换行拥挤

---

二、目标结构

PageHeader（公网 Agent）
  └─ #actions：服务端选择器 · 刷新
n-alert（条件渲染：Agent 未连接 / frps 未安装 / Nginx 缺失 → 一句引导 + 跳转）
stats-row（统一 4 列稳定网格）
  ├─ Agent 连接（在线/未连接 + agent 地址）
  ├─ frps 服务（运行中/未运行 + 版本）
  ├─ 80 端口
  └─ 443 端口
HavlineCard「服务状态详情」
  └─ field-grid：Agent 版本 / 已安装 frps 版本 / frps 启动命令 / 配置文件 / 安装位置 / 开机自启 / 7000 端口（StatusBadge）
HavlineCard「frps 服务控制」
  └─ 按钮区：启动|停止 · 重启 · frps 管理面板 · 下发配置 · [版本选择] 安装/升级
HavlineCard「Agent 生命周期（SSH）」
  └─ 按钮区：探测环境 · 安装/升级 Agent · SSH 诊断 · 卸载（保留数据）· 卸载（含数据，二次确认）
HavlineCard「输出与日志」（n-tabs）
  ├─ Tab 操作输出：带来源标签 + 时间；空态 EmptyState；「清空」按钮
  └─ Tab frps 日志：frps_log_tail；空态 EmptyState

要点：状态只读 → 操作只写 → 输出只展示，三段物理分离；「公网反代」跳转改为 n-alert 或 PageHeader 次级入口。

---

三、逐项改造清单

1. 状态详情独立成卡（解决 #1）

• 把「frps 服务控制」里的 field-grid 整体搬到新的「服务状态详情」卡；
• 状态类字段用 StatusBadge（开机自启、7000 端口、frps 版本），值类字段用 .mono / .mono-wrap；
• 「frps 服务控制」只留按钮区与安装版本选择。

2. 统一网格（解决 #2、#12）

.stats-row { display: grid; grid-template-columns: repeat(4, minmax(0, 1fr)); gap: var(--havline-space-4); margin-bottom: var(--havline-space-4); }
.agent-page-grid { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: var(--havline-space-4); margin-bottom: var(--havline-space-4); }
@media (max-width: 900px) { .stats-row { grid-template-columns: repeat(2, minmax(0, 1fr)); } .agent-page-grid { grid-template-columns: 1fr; } }
@media (max-width: 760px) { .stats-row { grid-template-columns: 1fr; } .agent-actions { width: 100%; } .agent-actions .n-button { flex: 1 1 auto; } }

3. 操作状态精细化（解决 #3、#9）

// 当前进行中的动作：'status' | 'probe' | 'agent-install' | 'agent-uninstall' | 'diagnose'
//              | 'frps-start' | 'frps-stop' | 'frps-restart' | 'frps-install' | 'push-config'
const busy = ref<string | null>(null)
const statusLoading = ref(false)

async function run<T>(action: string, fn: () => Promise<T>): Promise<T | undefined> {
  if (busy.value) return            // 串行化，避免并发操作
  busy.value = action
  try { return await fn() } finally { busy.value = null }
}

// 轮询走静默：不设 busy，只设 statusLoading
async function refreshAll(options: { silent?: boolean } = { silent: true }) { /* ... */ }

按钮写法：:loading="busy === 'frps-restart'"、:disabled="busy !== null && busy !== 'frps-restart'"。

4. 输出与日志合并 + 来源标注（解决 #4、#5、#11）

interface OpOutput { at: string; source: string; text: string; ok: boolean }
const opOutput = ref<OpOutput[]>([])      // 最多保留 20 条

function pushOutput(source: string, text: string, ok = true) {
  opOutput.value = [{ at: new Date().toISOString(), source, text, ok }, ...opOutput.value].slice(0, 20)
}

• 每类操作写入自己的 source（如「重启 frps」「SSH 诊断」「安装 Agent」），失败用 ok=false 标红；
• 展示：n-tabs（操作输出 / frps 日志），操作输出项显示 formatDate(at) 或 formatRelativeTime(at) + 来源徽标 + .code-block；
• 空态用 EmptyState，不再渲染「暂无日志」字符串；
• 提供「清空」按钮（opOutput.value = []）。

5. 危险操作二次确认（解决 #6）

<n-popconfirm @positive-click="uninstallAgent(server, false)">
  <template #trigger><n-button size="small" type="warning">卸载（含数据）</n-button></template>
  将删除 VPS 上的 agent、frps 单元与 /var/lib/havline-agent（路由与证书一并丢失），确认继续？
</n-popconfirm>

「卸载（保留路由/证书）」保持一步执行（--keep-data），仅加 quaternary 视觉区分。

6. 页面级提示（解决 #7、#8）

在 PageHeader 之后按条件渲染 n-alert（互斥，取最高优先级一条）：

条件	类型	文案要点	动作
!agentStatusOk	error	Agent 未连接：检查 VPS 上 havline-agent 是否运行、Agent 地址与 Token 是否正确	「探测环境」
!agentStatus?.frps_active	warning	frps 未运行：可点「启动 frps」或在下方安装	「启动 frps」
反代入口引导（常驻）	info	反代的逐条部署/配置查看/访问控制在「公网反代」页	跳转 /public-proxy

原「公网 Nginx 反代」整卡随之删除。

7. 版本默认值取列表（解决 #10）

const frpsVersionOptions = computed(() => releases.value.map((r) => ({ label: r.version, value: r.version })))
watch(releases, (list) => { if (!frpsInstallVersion.value && list.length) frpsInstallVersion.value = list[0].version })

列表为空时禁用「安装/升级 frps」并提示「正在获取官方版本列表…」，不再回退硬编码版本。

8. 轮询策略

• 保持 10 秒刷新，但 refreshAll({ silent: true }) 不触碰 busy；
• 页面不可见时暂停：document.visibilityState === 'hidden' 时跳过（减少无谓请求）；
• onBeforeUnmount 清理定时器（现有行为保留）。

---

四、涉及文件与验证

文件	改动
web/src/views/AgentView.vue	模板结构重排、脚本状态重构、样式网格与断点补齐（单文件改动）
web/src/api/client.ts / types.ts	预期无需改动（现有 getFrpAgentStatus / probeFrpAgent / installFrpAgent / uninstallFrpAgent / sshDiagnoseFrpAgent / frpsServerActionRaw / pushFrpConfigToAgent / installFrpServer / listFrpReleases 已够用）
cmd/havline/web/dist	构建产物同步（gitignore，不入库）

验证闭环（技能第 8 节）：

cd web
npx vue-tsc --noEmit      # 0 错误
npx vite build            # 成功
# 本地生效：同步 dist → cmd/havline/web/dist 后 go build ./...

回归检查点（真机，VPS 38.95.74.87）：

1. 页面加载：状态卡 4 张、无 loading 闪烁（轮询静默）；
2. 点「重启 frps」：仅该按钮转圈，其余按钮 disabled；输出出现在「操作输出」且来源标为「重启 frps」；
3. 点「SSH 诊断」：输出进入同一区域但来源不同，时间正确；
4. 点「卸载（含数据）」：出现二次确认；取消后不执行；
5. agent 未连接场景：顶部出现 error 级 n-alert，点「探测环境」有反馈；
6. 窄屏（≤760px）：统计卡单列、按钮区铺满不溢出；
7. 暗色主题：所有颜色随令牌切换，无残留写死色值。

---

五、风险与回滚

风险	处理
结构调整导致既有操作失效	只重排模板与状态，不改 api 调用；逐项对照本方案第三节，改完按第四节回归
危险操作加确认后影响老用户肌肉记忆	仅「卸载（含数据）」加确认，其余保持一步
输出改为列表后信息过多	上限 20 条 + 清空按钮
回滚	单文件改动，git checkout -- web/src/views/AgentView.vue 即可回到当前版本（当前版本已按 skill 对齐，可安全回退）

---

六、工作量

步骤	内容	预计
1	状态详情卡拆分 + 网格统一 + 断点	0.5h
2	busy 状态机 + 按钮 loading 精细化	0.5h
3	输出与日志合并（tabs + 来源 + 空态）	1h
4	页面级 n-alert + 删跳转卡	0.5h
5	危险操作确认 + 版本默认值 + 轮询静默	0.5h
6	验证（tsc/build/回归清单）	0.5h

合计约 3–3.5 小时，单文件改动，不涉及后端与 agent。