概览

lexmount:remote 把在线电脑或服务器的能力提供给云端任务。文件、进程和网络连接在所选客户端执行，HTTP 服务的处理函数仍在云端 JavaScript 环境执行。使用前按快速开始启动原生客户端。

• host.fs：读写文件、遍历目录和查询文件信息。
• host.fetch：请求客户端本机、内网或公网 HTTP 服务。
• host.process：查询进程、执行和控制 shell 命令。
• host.tcp：建立 TCP 连接和监听。
• host.http：在客户端监听 HTTP，由云端处理请求。

import { getRemoteHosts, remoteHosts } from 'lexmount:remote';

const hosts = await getRemoteHosts();
const info = hosts.find((item) => item.id === '<client-id>');
if (!info) throw new Error('Client is offline or unavailable');
const host = remoteHosts[info.id];
console.log(await host.fs.readTextFile('notes.txt'));

主机发现

getRemoteHosts()

功能： 查询在线客户端并刷新 remoteHosts 映射。

参数： 无。

返回值： Promise<RemoteHostInfo[]>。下列字段只读，无法采集的系统字段为 null。

系统信息在注册或重连时采样。模块首次导入也可能查询主机并失败；需要捕获导入错误时，将 await import('lexmount:remote') 放进 try/catch。

remoteHosts

功能： 提供 Readonly<Record<string, RemoteHost>>，以客户端 ID 查询操作对象。配置后的首次导入及每次 getRemoteHosts() 刷新它，不会持续自动刷新。

访问参数： remoteHosts[id] 中的 id: string 为客户端完整 ID。

返回值： RemoteHost，不存在该项时为 undefined。主机对象包含只读 id: string、fs、fetch、process、tcp 和 http。已取得的对象在调用时仍检查当前连接状态。

客户端权限

在客户端管理中打开「配置」，修改并保存。首次连接的默认配置为：

{
  "fs": { "enabled": true, "allow_write": false },
  "process": { "enabled": true, "allow_exec": true },
  "tcp": { "enabled": true },
  "http_server": { "enabled": true }
}

fs.allow_write=false 限制文件 API 的写操作；已允许的 shell 命令仍可修改文件。文件读取遵循客户端系统用户的权限，没有额外路径白名单。

配置按用户和客户端 ID 保存，不按项目隔离。离线可保存，重连后同步；以客户端确认版本判断是否应用。新配置影响后续操作，已开始的操作继续，关闭与清理始终允许。

错误与资源释放

远端错误是带 name、code 的 Error，例如 RemoteFsError、RemoteFetchError、RemoteProcessError、RemoteTcpError、RemoteHttpError 和注册表的 RemoteError。这些名称不是模块导出的构造函数。按 error.code 判断原因，如 host_disconnected、permission_denied、remote_unavailable；非法参数也可能抛出 TypeError。

未配置远程能力时，主机查询以 remote_unavailable 拒绝。客户端离线、权限变化或网络失败也可能使调用失败，重连不会自动重放业务操作。

目录迭代、进程快照和未消费的响应不会单独保持任务活动；运行中的子进程、TCP 连接与监听器、HTTP 服务会保持任务运行。正常消费并显式关闭资源，任务结束或停止时运行时也会清理。

组合用法见远程接口示例，声明见 remote.d.ts。