Documentation
¶
Overview ¶
Package agent 实现 RelayMesh 终端 Agent:运行在被管理主机上的常驻进程, 主动连接 Hub(服务端)的通用入口,按需在本机的伪终端里运行 shell,并把它安全地中继给 Web 浏览器。
关键性质:
- 伪终端由「会话守护进程」(internal/agent/holder)持有:外置模式下它是独立进程,Agent 升级、重启乃至崩溃都不会 打断会话;内嵌模式(Windows 临时启动、`--holder=embedded`)下它与 Agent 同进程,会话随进程结束,且会如实标注;
- 伪终端的寿命只取决于守护进程自身、显式 kill 与 TTL,绝不取决于网络连接(INV-P1);
- 身份是 Ed25519 密钥,机器码由公钥派生;服务端只存公钥,没有任何可冒充主机的秘密;
- Agent 必须验证服务端(系统 CA / --pin 指纹 / TOFU),失败即关闭,绝不降级为明文;
- 限额由守护进程自己强制执行,服务端策略只能收紧。
Index ¶
- Constants
- Variables
- func AutoAttemptsPath(dataDir string) string
- func AutoCheckNotePath(dataDir string) string
- func AutoUpgradeMode(dataDir string) string
- func AutoUpgradePath(dataDir string) string
- func ClearAutoAttempts(dataDir string) error
- func DefaultConfigDir() string
- func DefaultDataDir() string
- func Fingerprint(der []byte) string
- func HardenDir(dir string) error
- func HostMeta(version, kind string) termproto.Meta
- func IdentityPath(dir string) string
- func IsElevated() bool
- func NormalizePin(s string) (string, error)
- func PrivLevel() string
- func ReadUpgradeNote(dataDir string) *termproto.UpgradeNote
- func RecordAutoAttempt(dataDir, version string, now time.Time) error
- func RemoveAutoCheckNote(dataDir string) error
- func RemoveAutoUpgrade(dataDir string) error
- func RemoveIdentity(dir string) error
- func RemoveOnlineMarker(dataDir string)
- func SetWebUpgradeAllowed(dataDir string, on bool) error
- func StagedBinaryPath(dataDir string) string
- func UpgradeDir(dataDir string) string
- func WebUpgradeAllowed(dataDir string) bool
- func WebUpgradeFlagPath(dataDir string) string
- func WriteAutoCheckNote(dataDir string, n AutoCheckNote) error
- func WriteAutoUpgrade(dataDir string, cfg AutoUpgradeConfig) error
- func WriteOnlineMarker(dataDir, version string, now time.Time) error
- func WriteUpgradeNote(dataDir string, n termproto.UpgradeNote) error
- type Agent
- type AutoAttempts
- type AutoCheckNote
- type AutoSettings
- type AutoUpgradeConfig
- type AutoWindow
- type Event
- type FileOptions
- type GuiWakeOptions
- type HolderMode
- type Identity
- type KnownServers
- type Limits
- type Manager
- type OnlineMarker
- type Options
- type SelfUpgrade
- type ServerTarget
- type ShellFunc
- type State
- type TrustOptions
Constants ¶
const ( // OpenWrtReleaseFile 是 OpenWrt 系固件(QWRT、ImmortalWrt、iStoreOS 等)都带的版本文件,用它识别这类系统。 OpenWrtReleaseFile = "/etc/openwrt_release" // OpenWrtDataDir 是 OpenWrt 上 root 的默认数据目录:它在 overlay(闪存)上,重启不丢。 OpenWrtDataDir = "/etc/relaymesh-agent" )
const AgentWSPath = "/api/v1/terminal/agent/ws"
AgentWSPath 是 Hub 上通用 Agent 入口的路径。
Variables ¶
var ErrNoIdentity = errors.New("identity file does not exist")
ErrNoIdentity 表示持久身份文件不存在。
var Rev = ""
Rev 是这个二进制的「Agent 侧代码指纹」(见 internal/agentrev、termproto.ValidAgentRev),构建时通过 -ldflags "-X main.rev=…" 注入后由 main 赋值;空表示非发布构建,此时服务端回退到版本号比较。
var Version = "dev"
Version 是 Agent 的版本号,独立二进制构建时通过 -ldflags "-X github.com/teacat99/RelayMesh/v2/internal/agent.Version=…" 注入。
Functions ¶
func AutoAttemptsPath ¶
AutoAttemptsPath 是尝试记录的路径(与升级相关的其他文件放在一起)。
func AutoCheckNotePath ¶
AutoCheckNotePath 是检查结果文件的路径(与升级相关的其他文件放在一起)。
func AutoUpgradeMode ¶
AutoUpgradeMode 返回握手里声明的模式:已开启时是 notify / silent,否则是 off。
func ClearAutoAttempts ¶
ClearAutoAttempts 清掉尝试记录(所有者重新 enable、或收回同意时)。文件不存在不算错。
func DefaultConfigDir ¶
func DefaultConfigDir() string
DefaultConfigDir 返回服务配置与已信任服务器指纹(known_servers)的默认目录。
func DefaultDataDir ¶
func DefaultDataDir() string
DefaultDataDir 返回身份文件等持久数据的默认目录(按是否以管理员权限运行区分)。
Linux root : /var/lib/relaymesh-agent 普通用户: $XDG_STATE_HOME 或 ~/.local/state 下的 relaymesh-agent OpenWrt root: /etc/relaymesh-agent (OpenWrt 的 /var 指向 /tmp,是内存盘,放在那里重启就会丢掉身份) macOS root : /Library/Application Support/RelayMesh Agent 普通用户: ~/Library/Application Support/RelayMesh Agent Windows 管理员: %ProgramData%\RelayMesh\Agent 普通用户: %LocalAppData%\RelayMesh\Agent
func Fingerprint ¶
Fingerprint 返回证书(DER)的 SHA-256 指纹,格式 "sha256:<小写十六进制>"。
func HardenDir ¶
HardenDir 把目录收紧为仅本人(与管理员 / SYSTEM)可访问:Unix 由创建时的 0700 保证,Windows 设置私有 ACL。 会话守护进程的目录(状态文件与本地套接字)靠它防止其他用户接入。
func NormalizePin ¶
NormalizePin 接受 "sha256:AB:CD…" / "AB:CD…" / 纯十六进制,统一成 "sha256:<小写十六进制>"。
func ReadUpgradeNote ¶
func ReadUpgradeNote(dataDir string) *termproto.UpgradeNote
ReadUpgradeNote 读取上一次升级的结果(已净化);没有或损坏时返回 nil。
func RecordAutoAttempt ¶
RecordAutoAttempt 记一次「对 version 开始静默升级」。同一个版本累加,换了版本从 1 重新数。 要在开始下载之前写好:Agent 在升级中途崩溃、或升级后被还原重启,这次尝试也不会丢。
func RemoveAutoCheckNote ¶
RemoveAutoCheckNote 删除检查结果(收回同意时一并清掉,免得 status 以后还展示一份过期的结果)。文件不存在不算错。
func RemoveAutoUpgrade ¶
RemoveAutoUpgrade 收回同意。文件本来就不存在不算错。
func RemoveIdentity ¶
RemoveIdentity 删除 dir 下的持久身份文件(文件不存在不算错误)。
func RemoveOnlineMarker ¶
func RemoveOnlineMarker(dataDir string)
RemoveOnlineMarker 删除上线标记(升级进程在重启服务之前清掉旧标记,避免把旧版本留下的标记当成新版本上线)。
func SetWebUpgradeAllowed ¶
SetWebUpgradeAllowed 打开或关闭开关。关闭时文件本来就不存在不算错。
func StagedBinaryPath ¶
StagedBinaryPath 是下载并校验过的新版本的存放路径。
func WebUpgradeAllowed ¶
WebUpgradeAllowed 报告主机所有者是否允许从 Web 升级:开关文件存在且是普通文件。 每次都现读,不缓存——所有者随时可以用 `web-upgrade off` 收回。
func WebUpgradeFlagPath ¶
WebUpgradeFlagPath 是「允许从 Web 升级」开关文件的路径。
func WriteAutoCheckNote ¶
func WriteAutoCheckNote(dataDir string, n AutoCheckNote) error
WriteAutoCheckNote 保存最近一次检查的结果。
func WriteAutoUpgrade ¶
func WriteAutoUpgrade(dataDir string, cfg AutoUpgradeConfig) error
WriteAutoUpgrade 写入同意(先写临时文件再改名,读的一方不会看到写了一半的内容)。
func WriteOnlineMarker ¶
WriteOnlineMarker 记下「本 Agent(version)已经与 Hub 握手成功」。
func WriteUpgradeNote ¶
func WriteUpgradeNote(dataDir string, n termproto.UpgradeNote) error
WriteUpgradeNote 保存上一次升级的结果。
Types ¶
type Agent ¶
type Agent struct {
// contains filtered or unexported fields
}
Agent 是终端 Agent 的运行实例。
func (*Agent) Run ¶
Run 保持与 Hub 的连接直到 ctx 被取消:断线自动重连,会话在重连期间继续运行。 内嵌模式下返回时已终止全部会话(PTY 的寿命不超过 Agent 进程);外置守护进程模式下会话由守护进程继续持有。
func (*Agent) SessionsOutliveAgent ¶
SessionsOutliveAgent 报告会话是否由外置守护进程持有(Agent 退出后仍在运行)。auto 模式在 Run 开始后才有确定答案。
type AutoAttempts ¶
type AutoAttempts struct {
Version string `json:"version"`
Count int `json:"count"`
// At 是最近一次尝试的 Unix 秒,只用于展示。
At int64 `json:"at,omitempty"`
// Unreadable 表示记录文件存在但读不清:按「已经试满」处理(不写进文件)。
Unreadable bool `json:"-"`
}
AutoAttempts 记录「对哪个版本已经开始过几次静默升级」。
func ReadAutoAttempts ¶
func ReadAutoAttempts(dataDir string) AutoAttempts
ReadAutoAttempts 读取尝试记录。文件不存在是「没有试过」;存在但不是合规的内容则标记 Unreadable, 交给调用方按「已经试满」处理——宁可停下,也不要因为记录坏了而无限重试。
func (AutoAttempts) Paused ¶
func (a AutoAttempts) Paused(version string) bool
Paused 判断对 version 是否已经停止尝试:同一个版本试满次数,或记录本身读不清。
type AutoCheckNote ¶
type AutoCheckNote struct {
// At 是检查完成的 Unix 秒(本机时钟)。
At int64 `json:"at"`
// Status 是 Hub 的回答(termproto.AutoOffer*)或 autoCheckNoReply。
Status string `json:"status"`
// Latest 是 Hub 上最新的 Agent 版本(回答里有时才有);Current 是检查时本机的版本。
Latest string `json:"latest,omitempty"`
Current string `json:"current,omitempty"`
// Install 与 Detail 只有静默模式才有:这一轮检查之后,静默升级做了什么决定(autoInstall*)以及原因的一句话说明。
Install string `json:"install,omitempty"`
Detail string `json:"detail,omitempty"`
}
AutoCheckNote 是最近一次自动升级检查的结果,写在数据目录里,供 `auto-upgrade status` 在本机展示。
func ReadAutoCheckNote ¶
func ReadAutoCheckNote(dataDir string) (AutoCheckNote, bool)
ReadAutoCheckNote 读取最近一次检查的结果;不存在、过大或损坏时返回 false。
type AutoSettings ¶
type AutoSettings struct {
// Mode 是 notify 或 silent。
Mode string
// Window 是允许开始升级的时间段;WindowText 是它的原文(不限为空)。
Window AutoWindow
WindowText string
// TrustKeys 是主机所有者钉住的公钥(已解析、已去重)。完整的信任名单还要加上编进程序的公钥,见 Keys。
TrustKeys []ed25519.PublicKey
// Problem 非空表示设置文件里有读不懂的内容(时间段写法不对、公钥无法解析、公钥太多)。
// 静默安装遇到它一律不做——读不清楚的时候必须落在不升级的一侧。
Problem string
}
AutoSettings 是读出来之后经过校验的静默升级设置。
func ReadAutoSettings ¶
func ReadAutoSettings(dataDir string) (AutoSettings, bool)
ReadAutoSettings 读取并整理同意文件;没有同意(或读不清)时第二个返回值为 false。
func (AutoSettings) Keys ¶
func (s AutoSettings) Keys() []ed25519.PublicKey
Keys 是静默升级的完整信任名单:编进程序的发布公钥,加上主机所有者钉住的公钥,按密钥标识去重。 名单为空时静默模式没有任何办法验证新版本,所以既不能开启也不会安装。
type AutoUpgradeConfig ¶
type AutoUpgradeConfig struct {
// Mode 是 termproto.AutoUpgradeNotify 或 termproto.AutoUpgradeSilent。
Mode string `json:"mode"`
// At 是写入时刻(Unix 秒),只用于 `auto-upgrade status` 展示。
At int64 `json:"at,omitempty"`
// Window 是静默升级允许开始的时间段(HH:MM-HH:MM,主机本地时间);空表示不限。只对静默模式有意义。
Window string `json:"window,omitempty"`
// TrustKeys 是主机所有者钉住的发布公钥(rmpub1:…):与编进程序的公钥一起构成静默升级的信任名单。
// 只对静默模式有意义;Hub 既不能读到它,也无法添加。
TrustKeys []string `json:"trust_keys,omitempty"`
}
AutoUpgradeConfig 是主机所有者对「自动升级」的同意。
func ReadAutoUpgrade ¶
func ReadAutoUpgrade(dataDir string) (AutoUpgradeConfig, bool)
ReadAutoUpgrade 读取同意。文件不存在、不是普通文件、过大、不是合规的 JSON、模式不认识,一律视为「没有同意」(false): 自动升级是一项会改动程序的能力,读不清楚的时候必须落在关闭的一侧。
func (AutoUpgradeConfig) Settings ¶
func (c AutoUpgradeConfig) Settings() AutoSettings
Settings 把同意文件的内容整理成可用的设置;写法不对的地方记在 Problem 里,而不是悄悄忽略。
type AutoWindow ¶
type AutoWindow struct {
// contains filtered or unexported fields
}
AutoWindow 是静默自动升级允许「开始」的时间段:主机本地时间、24 小时制、精确到分钟,可以跨午夜(23:00-02:00)。 零值表示不限。时间段只约束「什么时候开始一次升级」;开始之后的下载与安装不会因为时间段结束而被放弃—— 升级做到一半被打断,比稍微超出时间段更糟。
func ParseAutoWindow ¶
func ParseAutoWindow(s string) (AutoWindow, error)
ParseAutoWindow 解析 HH:MM-HH:MM。空串是「不限」;起止相同的写法含义含糊(是整天还是一分钟都没有),一律拒绝。
type Event ¶
type Event struct {
State State
Detail string
// Code 是对端的 WebSocket 关闭码(没有则为 0)。
Code int
// Retry 在 StateRetrying 时给出下次重试前的等待时间。
Retry time.Duration
}
Event 描述一次状态变化。
type FileOptions ¶
type FileOptions struct {
// AllowPrivateURLs 允许 push_url 访问回环 / 私网 / 链路本地地址(默认不允许,防止借这台主机探测内网或元数据服务)。
// 只有这台主机的拥有者能在本机启动参数里打开它,服务端无法设置。
AllowPrivateURLs bool
}
FileOptions 是文件能力的本机选项。本机只有两个旋钮:一票否决(Options.Exec.DenyExec,与模型执行共用)和这里的网址范围。
type GuiWakeOptions ¶ added in v2.2.0
type GuiWakeOptions struct {
// DataDir 是 Agent 的数据目录:同意文件、幂等表、审计日志都放在这里。
DataDir string
// Timing 与 Now 供测试注入(零值取默认)。
Timing guiwake.Timing
Now func() time.Time
}
GuiWakeOptions 让这个 Agent 具备「GUI 唤醒」能力(#295):Hub 可以经这条 Agent 通道,请本机的 Cursor 客户端 (主机所有者用 --remote-debugging-port 启动的那个)新建一个会话,或在旧会话里发一句唤醒词。
能力是否真的可用,完全由主机所有者在本机的同意文件(<DataDir>/gui-wake.json,用 `gui-wake enable` 写)决定: 没有这个文件,Hub 发来的任何 gui_req 都只会得到 gui_disabled。nil 表示这个 Agent 根本不提供(临时身份、没有数据目录), 握手里也不声明。执行器本身的行为见 internal/agent/guiwake。
type HolderMode ¶
type HolderMode string
HolderMode 决定终端会话由谁持有。
const ( // HolderEmbedded 让会话运行在 Agent 进程内:行为与最初的实现一致,会话随进程结束,不具持久性。 // 它也是 Options 的零值——库与测试不会意外去连接机器上真实的守护进程。 HolderEmbedded HolderMode = "embedded" // HolderExternal 只使用外置守护进程;连不上就报告「不可用」并重试,绝不静默退化为内嵌 // (那会产生不持久的会话,还可能与守护进程里的会话重复)。 HolderExternal HolderMode = "external" // HolderAuto 启动时能连上外置守护进程就用它,否则使用内嵌模式。 HolderAuto HolderMode = "auto" )
func ParseHolderMode ¶
func ParseHolderMode(s string) (HolderMode, error)
ParseHolderMode 解析 --holder 选项的取值。
type Identity ¶
type Identity struct {
Priv ed25519.PrivateKey
Pub ed25519.PublicKey
// Kind 是 persistent(存盘,重启后机器码不变)或 temporary(仅内存,每次运行都不同)。
Kind string
// Path 是持久身份的文件路径(临时身份为空)。
Path string
// Created 表示这次调用新生成了密钥(首次运行)。
Created bool
}
Identity 是 Agent 的身份:一对 Ed25519 密钥。机器码由公钥派生,服务端只保存公钥, 因此「知道机器码」不等于「能冒充该主机」——冒充需要私钥。
func LoadIdentity ¶
LoadIdentity 读取 dir 下的持久身份;不存在时返回 ErrNoIdentity。
func LoadOrCreateIdentity ¶
LoadOrCreateIdentity 读取持久身份,不存在则生成并安全地写盘(首次运行时才生成,绝不随镜像分发)。
func NewTemporaryIdentity ¶
NewTemporaryIdentity 生成仅存于内存的临时身份:进程退出即消失,下次运行机器码不同,需要重新启用。
func ResetIdentity ¶
ResetIdentity 丢弃现有持久身份并重新生成(机器码随之改变,需要在 Web 上重新启用)。
type KnownServers ¶
type KnownServers struct {
Path string
// contains filtered or unexported fields
}
KnownServers 是 TOFU 的指纹记录:每行 "host:port sha256:<hex>"。
func (*KnownServers) Add ¶
func (k *KnownServers) Add(host, fp string) error
Add 追加一条记录(原子写入,文件权限 0600)。
type Limits ¶
Limits 与 ShellFunc 的实现在 holder 包里(会话由守护进程持有);这里保留别名, 让命令行与测试沿用 agent.Limits / agent.DefaultLimits 这些名字。
type OnlineMarker ¶
type OnlineMarker struct {
Version string `json:"version"`
PID int `json:"pid"`
// At 是写入时刻(Unix 秒)。
At int64 `json:"at"`
}
OnlineMarker 是新版本 Agent 握手成功后留下的标记。
func ReadOnlineMarker ¶
func ReadOnlineMarker(dataDir string) (OnlineMarker, bool)
ReadOnlineMarker 读取上线标记;不存在或损坏时返回 false。
type Options ¶
type Options struct {
Server ServerTarget
Trust TrustOptions
Identity *Identity
// Version 自报的 Agent 版本;空则使用包级 Version。
Version string
// Rev 自报的 Agent 侧代码指纹;空则使用包级 Rev(仍为空表示非发布构建)。
Rev string
Limits Limits
Logf func(format string, args ...any)
// OnEvent 在状态变化时被同步调用,必须快速返回。
OnEvent func(Event)
// Holder 决定会话由谁持有,零值为内嵌(见 HolderMode)。
Holder HolderMode
// HolderSocket 是外置守护进程的本地套接字路径(external / auto 必填)。
HolderSocket string
// Record 是终端记录(终端上显示什么就记录什么,只写在本机)的配置。Record.Dir 为空则不提供记录与历史读取。
// 内嵌模式下由 Agent 自己写入该目录;外置模式下由守护进程写入,Agent 只读。
// Record.Disabled 是本机的一票否决(--no-record)。
Record record.Options
// Exec 是模型执行(非交互命令运行)的配置。Exec.DenyExec 是本机的一票否决(--deny-model-exec):
// 内嵌模式下由 Agent 自己执行;外置模式下命令由守护进程执行,但 Agent 同样会拦下被否决的请求,
// 所以无论在哪一侧设置,否决都生效。Exec.Dir 为空表示本机不能执行模型命令。
Exec holder.ExecOptions
// Files 是文件能力(模型经 MCP 查看 / 拉取 / 写入文件)的本机选项。文件能力同样受 Exec.DenyExec 一票否决。
Files FileOptions
// SSH 非 nil 表示本机开启了 SSH 网关(--ssh-gateway)。内嵌模式下由 Agent 自己的会话宿主承担;
// 外置模式下是守护进程(holder run --ssh-gateway)去连接 SSH 目标,Agent 只转发帧,这里的值不起作用。
SSH *holder.SSHOptions
// SelfUninstall 非 nil 表示这个 Agent 是以常驻服务运行、并且知道如何卸载自己:
// 管理员删除主机并勾选「同时卸载设备端」时,Hub 会发来 uninstall 帧,Agent 调用它在本机另起一个与自身进程树无关的卸载进程
// (purge 对应 --purge)。返回 nil 表示卸载进程已成功启动(卸载本身随后异步完成,会停止本 Agent);
// 返回错误则什么都没有发生,Agent 继续正常运行。前台运行 / 临时身份 / 暂不支持的系统保持 nil。
SelfUninstall func(purge bool) error
// SelfUpgrade 非 nil 表示这个 Agent 是以常驻服务运行、知道如何把升级交给一个与自身进程树无关的升级进程:
// 握手时声明「Web 升级」能力(所有者在本机允许了才是 on),收到 Hub 的 upgrade 帧后下载、校验并交接。
// 前台运行 / 临时身份 / 暂不支持的系统保持 nil,不声明能力。见 webupgrade.go。
SelfUpgrade *SelfUpgrade
// GuiWake 非 nil 表示这个 Agent 可以按本机同意文件的授权,替 Hub 唤醒本机的 Cursor 客户端(#295;见 gui_wake.go)。
// 握手里声明 GUI 唤醒的状态(所有者在本机开启了才是 on)。临时身份即使给了也忽略。
GuiWake *GuiWakeOptions
// 以下字段供测试注入。
Spawner ptyhost.Spawner
Shell ShellFunc
// 重试节奏(零值取默认):网络类错误指数退避 MinBackoff→MaxBackoff;
// 握手无效 / 总闸关闭 / 发现关闭等取 SlowRetry;被停用取 DisabledRetry。
MinBackoff time.Duration
MaxBackoff time.Duration
SlowRetry time.Duration
DisabledRetry time.Duration
// Jitter 给等待时间加抖动;默认 ±20%。
Jitter func(time.Duration) time.Duration
}
Options 是 Agent 的运行参数。
type SelfUpgrade ¶
type SelfUpgrade struct {
// Allowed 报告主机所有者是否允许从 Web 升级(每次现读,不缓存)。
Allowed func() bool
// StageDir 是下载新版本的目录;不存在会被创建(0700)。
StageDir string
// Handoff 把已校验的新程序交给一个与 Agent 进程树无关的升级进程,由它替换程序并重启服务。
// 返回 nil 表示升级进程已经启动,Agent 随后会被重启;返回错误表示什么都没有发生。
Handoff func(ctx context.Context, newBinary, version string) error
// Note 返回上一次升级留下的结果,握手时带给 Hub;可为 nil。
Note func() *termproto.UpgradeNote
// Connected 在每次与 Hub 握手成功时调用,参数是本进程的版本号;可为 nil。
// 升级进程靠它留下的「上线标记」判断新版本是否真的连上了 Hub。
Connected func(version string)
// AutoMode 报告主机所有者在本机为「自动升级」选的模式(termproto.AutoUpgradeOff / Notify / Silent),每次现读;
// nil 表示这个 Agent 不提供自动升级,握手里不声明。
AutoMode func() string
// AutoChecked 在每次自动升级检查得出结论时调用,把结果交给本机保存(供 `auto-upgrade status` 展示);可为 nil。
AutoChecked func(AutoCheckNote)
// AutoSettings 现读主机所有者对自动升级的完整设置(模式、时间段、钉住的公钥);第二个返回值为 false 表示没有同意。
// nil 表示这个 Agent 读不到设置:静默模式不会安装任何东西(只做提示)。
AutoSettings func() (AutoSettings, bool)
// AutoAttempts 返回本机记录的静默升级尝试;AutoAttempted 记一次「对这个版本开始静默升级」(要在下载之前写好)。
// 任何一个为 nil 都意味着无法记录尝试:静默模式不会安装任何东西。
AutoAttempts func() AutoAttempts
AutoAttempted func(version string) error
// 以下供测试注入,零值取默认。
HTTPClient func() (*http.Client, error) // 默认:按 Agent 的信任配置构造
Platform func() (goos, goarch string) // 默认:runtime.GOOS / GOARCH
Verify func(ctx context.Context, file string) (string, error) // 默认:运行 `<file> version` 取版本号
MaxBytes int64 // 默认 256 MiB
DownloadTimeout time.Duration // 默认 5 分钟
Now func() time.Time // 默认 time.Now
}
SelfUpgrade 是 Agent 响应 Hub 的 upgrade 帧所需的本机能力与策略。nil 表示这个 Agent 不支持(不声明能力)。
type ServerTarget ¶
type ServerTarget struct {
URL string // 完整的 ws:// 或 wss:// 地址(含入口路径)
Host string // host:port,TOFU 记录的键
Secure bool // wss
}
ServerTarget 是规范化之后的服务端地址。
func ParseServer ¶
func ParseServer(raw string) (ServerTarget, error)
ParseServer 把用户给的服务端地址规范化:
- 允许省略协议(默认 https);http/https 会转换为 ws/wss;
- 自动补全入口路径;不接受内嵌账号密码,丢弃查询串与片段。
func (ServerTarget) HTTPBase ¶
func (t ServerTarget) HTTPBase() (string, error)
HTTPBase 返回同一台服务端的 HTTP(S) 基地址(不含末尾斜杠,保留部署在子路径下时的路径前缀)。 Agent 用它拼出升级文件的下载地址:地址只由 Agent 自己配置的服务端推出,不接受 Hub 在帧里指定。
type ShellFunc ¶
Limits 与 ShellFunc 的实现在 holder 包里(会话由守护进程持有);这里保留别名, 让命令行与测试沿用 agent.Limits / agent.DefaultLimits 这些名字。
type TrustOptions ¶
type TrustOptions struct {
// Pins 是允许的服务端叶子证书 SHA-256 指纹("sha256:<hex>"),可配置多个以便证书轮换。
Pins []string
// Insecure 允许明文 ws://。
Insecure bool
// KnownServersPath 非空时启用 TOFU 记录;与 Prompt 配合使用。
KnownServersPath string
// Prompt 在 TOFU 首次遇到未知指纹时询问人类是否信任;为 nil 则不做 TOFU。
Prompt func(host, fingerprint string) bool
}
TrustOptions 是连接服务端的信任配置。
func (TrustOptions) HTTPClient ¶
func (o TrustOptions) HTTPClient(t ServerTarget) (*http.Client, error)
HTTPClient 构造用于 WebSocket 升级请求的 HTTP 客户端(HTTP/1.1,支持代理环境变量)。
func (TrustOptions) Validate ¶
func (o TrustOptions) Validate(t ServerTarget) error
Validate 检查配置与目标是否相容(明文地址必须显式 --insecure;指纹必须合法)。
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package cli 是终端 Agent 的命令行:独立二进制 relaymesh-agent 与主程序的 `relaymesh agent` 子命令共用同一份实现。
|
Package cli 是终端 Agent 的命令行:独立二进制 relaymesh-agent 与主程序的 `relaymesh agent` 子命令共用同一份实现。 |
|
Package files 是 Agent 侧的文件能力:stat / hash / 分块读取(拉取)/ 经网址写入(push_url)。
|
Package files 是 Agent 侧的文件能力:stat / hash / 分块读取(拉取)/ 经网址写入(push_url)。 |
|
Package guiwake 是 Agent 里的「GUI 唤醒」执行器:通过 Cursor 客户端的本机调试端口(CDP), 在它的「Agents」窗口里新建会话,或在旧会话的输入框里输入文字并发送。
|
Package guiwake 是 Agent 里的「GUI 唤醒」执行器:通过 Cursor 客户端的本机调试端口(CDP), 在它的「Agents」窗口里新建会话,或在旧会话的输入框里输入文字并发送。 |
|
Package ptyhost 把「伪终端 + 子进程」的平台细节隔离在一个窄接口之后。
|
Package ptyhost 把「伪终端 + 子进程」的平台细节隔离在一个窄接口之后。 |
|
Package record 实现终端会话的**客户端侧**记录:终端上显示什么就记录什么。
|
Package record 实现终端会话的**客户端侧**记录:终端上显示什么就记录什么。 |
|
Package runlog 保存模型运行(非 PTY 的一次性命令)的完整输出。
|
Package runlog 保存模型运行(非 PTY 的一次性命令)的完整输出。 |
|
Package sshcred 是 SSH 网关在本机保存「它代为连接的 SSH 主机的登录凭据」的密封库。
|
Package sshcred 是 SSH 网关在本机保存「它代为连接的 SSH 主机的登录凭据」的密封库。 |