先做一条能用的前端体验

一张漂亮的页面能让人愿意点进去，真正留下来的理由，却常常是他知道下一步做什么，以及操作失败之后有没有办法继续。这一章用轻联的第一次接入来讲。

顺着任务画页面#

轻联的第一次接入只走一条路：打开公开指南 /start，选使用方式（本机、官方托管或自建），再选交给 Agent 或手动安装，把说明复制到目标设备执行。托管模式由本人登录、核对完整公钥指纹、批准一次，最后等首次真实回报。第一次用的人，页面直接建议先选本机，不需要账号。

先拿第 02 篇写下的主路径走一遍：入口是否明显？下一步去哪里操作？失败时能不能分清是自己没装好，还是服务出了问题？轻联复制安装说明后，页面提示“这是给 Agent 的说明，请粘贴到 Agent 对话中，而不是终端”；选手动安装时，提示换成在目标设备的终端粘贴并执行。复制本身不执行任何安装。

页面状态必须跟着真实结果#

轻联的面板守一条规矩：不放示例设备，不显示虚构的在线状态。空列表就写“尚未接入资源设备”，托管面板再补一句“配对批准后，等待首次真实回报”。

这些状态都不表示密钥过期。设备休眠、终端关闭、进程停止或网络不通，都可能导致未回报，提示会让人依次确认设备唤醒、Driver 运行和网络连通。

按钮也要说实话。云端设备未回报时，“采集一次”如实禁用，悬停提示“请启动设备上的 Driver”；旧 Driver 则提示需要更新。点下去之后按钮显示“正在采集…”，只有带着本次请求 ID 的签名回报才算成功，普通周期回报或超时后才到的回报都不算。

用合同组织前后端连接#

将接口地址、请求转换和错误处理集中在客户端层。轻联面板的请求都走 src/api.js 里的同一个函数：统一超时，401 跳回登录页，失败带回错误码。“状态怎么显示、采集按钮能不能点”也写成 src/device-state.js 里的两个函数，设备卡片只按结果渲染。

示意也要标出来。/start 的动画标着“工作原理示意 · 无需操作”；复制后的三张窗口图写着“以下是操作示意；请在对应电脑的真实窗口操作”，切图不会执行安装或批准绑定。前端演示只能证明交互可行，不能证明账号、权限或回报已经在线可用。

公开指南和账号面板各看什么#

/start 不需要登录，只放说明、复制按钮和操作示意；Agent 安装指南也有固定的公开地址，不含账号、身份或设备清单。设备列表、配对批准和撤销都在账号面板里，匿名打开根页面会跳到登录。

导航隐藏用于降低困惑；真正允许谁读取、批准或撤销，仍由控制面判断。它允许从其他网站顶层打开 /start、/login 这些页面，但 API、脚本、iframe 和写请求不适用这个例外。给公开页列允许展示的内容，给登录后的页面列动作；“顺手在公开页显示一下设备数量”这类需求，就该回到登录之后。

做一次真实的路径检查#

先手画流程，再让 Agent 只做第一步，逐步补后面的状态。轻联给 Agent 的安装说明末尾，要求它检查实际结果：健康接口正常，内存和磁盘来自真实采集，选了后台模式就核实服务真的在运行，当前 Agent 实际调用一次 device_center_list_resources，托管模式核实云端收到回报；最后说清还有哪些步骤要用户自己完成。

过关时演示一次成功和一次失败：成功确实拿到真实结果，失败不会丢掉用户输入，也不谎报完成。

轻联是怎么做的#

当时想解决什么。 0.2.0-beta.3 的托管接入要来回搬：在面板点“连接我的电脑”，复制命令到终端运行，再把终端的五分钟配对码填回面板，核对指纹后批准。交给 Agent 安装时，还要回到对话告诉它“已批准”。

交给 Agent 什么。 目标写在接入文档里：让用户只完成必要的复制、粘贴和确认。落到页面上，是一页指南并列两个入口，交给 Agent 或手动安装，目标设备不需要先装 AI Agent；配对码不进入 Agent 对话。

得到什么。 有浏览器的设备运行 connect --browser --confirm，自动打开本次申请；登记票据只放在网址的 fragment 里，页面立刻移除，五分钟有效、只能批准一次，服务端只存摘要。批准后 CLI 自己等首次资源回报。没有浏览器的服务器，仍可在另一台电脑填码。

怎样检查。 批准后 CLI 返回 firstReport.verified：为 true 才继续配置 MCP；为 false 表示已绑定但回报还没证实，去查服务、网络和时钟，不要重新绑定。“已绑定”和“已收到资源回报”在文档和页面上都分开写。到 2026-10-08，/start 的版本角标是 0.2.0-beta.4，npm 的 beta 标签也指向它。

为什么调整。 每多一次搬运，就多一个出错点：配对码只有五分钟，又不该贴进 Agent 对话或截图。浏览器模式干脆不在终端输出它。这次改动也说明，前端路径有时要跟着别的发布物走：新流程需要新版控制面和 CLI 一起交付，只更新网页，旧 CLI 拿不到新参数；新控制面也继续支持旧版填码。

换成你自己的项目#

我的项目是：[一句话说明产品]。请围绕“第一次使用”这条路径改前端，先读现有代码。

1. 写 docs/first-run-path.md：从入口到第一次拿到真实结果的每一步，列出页面状态，以及支持这个状态的真实依据（哪个接口返回了什么）。
2. 检查空列表、加载中、失败、过期或离线这几种状态：去掉示例数据和虚构的成功状态，没有依据的状态不显示。
3. 暂时不能用的按钮如实禁用，写出原因和下一步，不要等用户点了才报错。
4. 分别列出公开页面和登录后页面能展示的字段，确认公开页拿不到账号数据。
5. 在桌面和手机宽度各走一次成功路径和一次失败路径，把操作与实际接口结果记进同一个文档。

• 页面上没有示例数据，空状态给出了下一步
• 每个“成功”提示都对应一次真实的后端结果
• 不可用的按钮写明了原因，失败后用户输入还在
• 公开页面不登录也能打开，而且不返回账号数据
• docs/first-run-path.md 记录了一次失败路径和它的实际响应

下一章实现页面背后的业务规则，让界面看到的结果真正成立。