让 AI Agent 和 J6 台架高效、稳定、安全地协作

从远程执行脚本出发，设计一个结果可验证、故障可恢复、权限有边界的台架交互工具。

摘要

在征程 6（J6）开发中，查看状态、分析日志、下发脚本、回收结果，都是高频操作。让 AI Agent 承担这些工作，需要处理多跳连接、结果判定、任务恢复、设备隔离和权限控制。

本文复盘一次台架交互工具的设计与迭代，介绍关键问题、实现思路和验证方法，供读者搭建自己的工具参考。

说明：工具名称、设备标识和目录已作抽象处理。benchctl 及命令片段均为接口示意；实测数据的口径见第七节。

一、从一次台架诊断看问题

一个常见需求是：

检查指定台架的运行状态，分析最近的错误日志，执行诊断脚本，并取回结果。

执行步骤并不复杂：连接设备 → 确认环境 → 检查日志 → 上传并执行脚本 → 下载结果。

人工操作时，工程师会根据经验检查设备、识别错误、判断是否重试。交给 Agent 后，这些判断需要有明确依据。

环节	典型问题	后果
连接	多跳认证、每次重新握手	短命令的等待时间偏长
执行	多层 Shell 改变引号、变量或管道语义	实际执行偏离原意
判定	用“有输出”或成功提示判断成败	在错误前提上继续分析
传输	文件塞进命令参数，缺少校验与暂存	传输失败、内容不全或覆盖旧结果
长任务	本地超时，远端状态不明	重试导致重复执行
设备切换	沿用默认设备或旧连接	操作了错误台架

工具的设计目标由此收敛为四项：身份明确、结果可信、异常可恢复、权限受约束。

二、先定义接口与执行约定

2.1 用少量动作覆盖常见操作

将台架操作收敛为几类动作，并明确每类动作应返回什么：

动作	必须返回的信息
环境检查	连接状态、目标身份、磁盘与时钟等检查结果
状态与日志查询	查询内容、截断标记、策略判定
命令执行	执行状态、退出码、失败阶段与错误输出
文件上传、下载	校验结果、目标处理方式、失败后的数据状态
后台任务管理	设备与任务标识、运行状态、退出结果、后续查询方式

职责分工也要明确：Agent 负责规划和分析；工具负责检查、执行和记录；人负责确定目标设备、权限和需要授权的操作。

PC 与 J6 台架可按网络条件直连，或通过跳板机中转：

图 1：PC 与 J6 台架连接示意。AI Agent 与台架交互工具运行在 PC 端；跳板机按网络环境选用。

两种路径共用一个工具入口，统一处理设备选择、参数校验、策略检查和结果封装。

2.2 每次操作显式选择设备

不同台架可能具有相似的目录、软件和主机名；隔离网络中的设备还可能使用相同地址。单次 hostname 输出不足以确认访问对象。

为每条访问链路建立设备档案，记录跳板路径、目标端点、登录身份和凭据引用。每次操作显式选择档案，返回结果携带设备标识。

远程操作不设置默认设备。缺少设备参数时直接报错。 这个约束增加少量输入，可以降低连续操作选错设备的风险。

2.3 分开表达请求、执行和业务结果

工具需要区分三个层次：

请求结果：连接是否建立，查询是否完成；
执行结果：远端命令是否结束，退出码是多少；
业务结论：诊断结果是否表明设备正常。

例如，状态查询可以成功，被查询的任务却执行失败；诊断脚本也可能退出码为 0，同时报告设备异常。

输出采用 JSON 等结构化格式：标准输出只返回一个完整对象，额外提示写入标准错误。成功、参数错误和异常路径遵守同一格式，便于 Agent 稳定解析。

三、高效：复用连接，减少无效数据

3.1 连接复用必须区分访问链路

Agent 经常连续执行查进程、看磁盘、读日志等短命令。此时，连接建立可能占据主要耗时。OpenSSH 连接复用可以让连续调用共用已认证连接，空闲后再释放。

实现时需要检查两点：

缓存身份完整：区分跳板路径、目标端点和登录身份，避免切换路径后仍复用旧连接；
缓存故障可降级：缓存目录不可用时退回普通连接，避免性能优化影响基本可用性。

3.2 明确脚本与文件的数据通道

将文件编码后塞进命令参数，会受到操作系统参数长度限制，并增加内存开销。文件应通过数据流分块传输，命令通过明确的脚本通道传递。

这次迭代中的一个典型问题是 stdin 所有权冲突：远端解释器从标准输入读脚本，同时又收到压缩文件，结果把文件字节当成命令。

因此，同一次调用中，标准输入必须有明确用途：

执行脚本时：可以通过 stdin 传递脚本；
上传文件时：stdin 承载文件数据，远端执行脚本通过另一种受控方式提供。

工具仍需正确处理路径引用和调用端 Shell 的参数边界，尤其是中文、空格和特殊字符。

3.3 先筛选日志，再返回结果

大日志先在台架上按关键词、时间或模块筛选，再返回相关片段。完整日志通过文件下载留存。

文本输出同时设置行数和字节上限。单行 JSON 也可能很大，仅限制行数无法控制返回量。截断时需标记范围，说明保留的是头部、尾部还是指定片段，便于 Agent 判断证据是否充分。

四、稳定：保留未知状态，提供恢复路径

4.1 本地超时后，先查询原任务

假设台架已经启动任务，但确认应答在链路中丢失，本地最终超时。此时只能确认“未收到完整应答”，远端任务可能仍在运行。直接重试可能启动两份测试，造成资源争用或结果覆盖。

长任务应采用“提交—查询—取结果”的执行方式：

提交前确定任务标识，在目标设备上登记任务；
执行期间保存日志，结束后记录退出结果；
连接恢复后接续查询，使用原设备与原任务标识，避免重新提交。

同设备的同名任务需要防止重复占用。该机制降低重复执行风险，但不能据此承诺任意故障下都“恰好执行一次”。

超时响应可以表达为：

字段为设计示意，不代表实际工具的响应格式。

任务状态至少区分运行中、已结束、未知。进程消失但没有退出记录时，保留未知状态，并返回原因和恢复线索。

错误判断还要结合阶段：初次认证失败时，启动请求尚未执行；任务提交后，状态查询才认证失败时，原任务仍可能运行。同一个错误码，在不同阶段对应不同处理方式。

4.2 文件先暂存、再校验、最后发布

文件传输采用三个步骤：

写入本次独立暂存区；
校验文件摘要或目录内容；
校验通过后发布到目标位置。

校验失败时清理本次暂存数据，保留原目标。Agent 以“校验通过且发布完成”为后续操作的前置条件。

目录更新还需要明确替换语义。整体替换可以避免旧文件残留，但发布过程应设计备份与回滚，并单独验证跨文件系统、掉电等边界。同一目标的并发写入需要互斥；归档解包需要检查越界路径、链接和特殊文件。

4.3 根据错误类型和执行阶段决定是否重试

已知情况	处理方式
认证失败	检查凭据或访问权限，停止连续重试
主机身份变化	停止连接，由人核实变更
远端命令非零退出	检查命令、输入和错误输出
超时且远端状态不明	查询原任务，保留现场
策略拒绝	说明命中规则及原因
已确认未提交操作的临时连接失败	在次数和时间预算内重试

重试前检查执行阶段、副作用和幂等性，即重复执行是否会产生额外副作用。统一重试所有非零退出，会掩盖这些差别。

五、安全：用权限限制影响，用规则减少误操作

5.1 默认普通账户，按需提权

脚本、输出和测试数据放在授权工作目录中，默认使用普通账户。确需提权时，使用显式入口，说明原因和影响。

系统账户、目录权限和提权配置决定实际可操作范围；命令过滤用于减少常见误操作。需要更强隔离时，再采用受限账户、受限执行入口等系统级措施。

5.2 分离设备配置、凭据和主机信任

设备档案只保存连接信息与凭据引用。密码、私钥等由专门的凭据存储机制管理，避免进入对话、命令参数、配置示例和分发包。

首次连接应通过可信途径核对 SSH 主机指纹；后续发现变化，先停止并核实，再更新信任记录。

凭据诊断也要区分“未配置”与“当前进程不可读”。权限、沙箱或凭据后端异常，都可能导致读取失败。应先定位访问问题，避免反复要求用户录入已有凭据。

5.3 明确策略的能力边界

操作按规则分为直接执行、需要确认和禁止执行三类。判断前规范化常见命令形态和选项组合，减少简单字符串匹配的遗漏。策略加载失败或规则无法解析时，明确报错，避免以空规则表继续执行。

“只读分析”同样需要说明边界：拦截已知写操作可以减少误操作，无法证明任意 Shell 命令都只读。需要严格只读时，应收窄为固定查询接口，并由系统权限约束执行范围。

5.4 确认具体影响，记录关键操作

确认信息应包含操作对象、影响和恢复方式，例如“将中断该台架正在运行的测试”。Agent 先说明风险，取得明确授权后再继续。

若 Agent 能自行取得并提交确认参数，该机制只能提供操作缓冲，无法独立证明人已同意。强制审批需要在独立执行边界校验授权。

多人使用或需要追溯时，可启用脱敏记录，保存设备、动作、策略判定和结果，并限制访问权限与保留范围。本地日志的防篡改能力需要另行设计。

六、用边界用例修正设计

几次迭代暴露的问题，主要集中在超时、时间计算和安装交付。对应修正应落实到可复现的用例中：

问题	修正思路	验证重点
无输出时超时不生效	避免阻塞读取使超时检查无法执行	构造无输出的长任务，检查本地按时返回、远端状态如实标记
任务耗时异常	在同一时钟域内计算经过时间	检查时钟偏差场景，日志对齐前确认时间基准
源码可用，安装产物失效	检查资源打包、加载路径与说明书版本	在干净环境安装真实产物，验证策略、命令和错误输出

每增加一项能力，都要回答三个问题：失败后留下什么状态？如何接续？返回信息是否足以决定下一步？

七、收益与效果

在固定开发机、单级跳板路径与 J6 台架的测试记录中，短命令调用和文件传输结果如下：

测量项	结果	统计口径
CLI 冷连接调用	约 0.94 秒	包含连接建立与 Python 启动等开销
CLI 连接复用后的调用	平均约 0.16 秒	预热后连续 3 次记录的平均值
单文件上传	约 3 MB，约 1.4 秒	该次样本传输并通过内容校验

这组记录中，预热后的短命令耗时约为冷连接的六分之一。首次连接仍有建立成本，完整诊断流程的收益还取决于网络、认证方式和业务执行时间。

复测时，应固定设备、跳板路径和认证方式，用低开销只读命令分别测量冷连接与预热后的多次调用，并统一计入解释器启动开销。文件传输同时记录大小、耗时和校验结果。

稳定性验证覆盖上传、执行、下载闭环，以及命令失败、超时、重复提交、退出记录缺失、目标写入冲突和跨设备任务查询。验证结果支持按原设备与任务标识接续查询，并保留业务失败的退出码。

这些结果说明了具体行为与恢复能力。整体故障率、端到端人工耗时和长期运行表现，还需要持续测量。

八、从最小闭环开始实现

自用工具可以从一台设备、一条固定链路开始，按以下顺序扩展：

步骤	实现内容	验收重点
1. 执行闭环	显式选择设备，执行无副作用命令，返回真实结果	区分认证失败、命令失败和参数错误
2. 操作边界	普通账户、授权目录、必要的策略检查	应放行的操作通过，应拒绝的操作被拦截
3. 文件传输	暂存、校验、发布	空文件、大文件、特殊路径、已有目标及失败后旧数据保留
4. 后台任务	启动、查询、记录结果、接续	应答丢失后查询原任务，避免重复提交
5. 效率与交付	连接复用、日志筛选、工具与说明书统一管理	本地测量收益，在干净环境验证安装产物

Agent 使用说明重点写清五件事：动作选择、设备选择、结果解释、错误处理、授权要求。工具应提供实际版本与参数查询方式，便于 Agent 核对用法。

最小接口可以参考以下流程：

起步时，命令行工具加一份使用说明即可。后续接入其他 Agent 协议时，复用同一执行入口，统一设备、策略和结果处理，控制多套实现的维护成本。

结语

台架诊断需要完成观察、判断、执行和验证。Agent 可以组织步骤、分析脚本和日志，工具需要提供可核验的结果、可恢复的执行过程和明确的权限约束。

这次实践形成了几条执行原则：操作前明确设备，执行后核验结果，未知状态如实保留，失败路径能够接续，权限约束落实到系统。

从一条常用查询开始，把这些约定逐步做实，就能构建适合自己的台架助手，让工程师将更多精力投入问题分析和技术判断。