termproto

package
v2.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 4, 2026 License: Apache-2.0 Imports: 15 Imported by: 0

Documentation

Overview

Package termproto 定义终端功能中「Hub(服务端)」与「Agent(主机端)」共用的线协议、机器码派生与字段净化。

它只依赖标准库,刻意不引用项目内任何其他包:协议是两端的契约,改动必须同时被两端的测试看见。 金标准向量(identity_test.go)固化了机器码与签名的派生方式,任何不兼容的改动都会让它们失败。

Index

Constants

View Source
const (
	TAutoUpgradeCheck   = "auto_upgrade_check"   // Agent → Hub:问「有没有比我新的版本」
	TAutoUpgradeOffer   = "auto_upgrade_offer"   // Hub → Agent:对一次检查的回答
	TAutoUpgradeRequest = "auto_upgrade_request" // Agent → Hub:静默模式下,「我现在就要升级到这个版本,请给我下载凭据」
	TAutoUpgradeGrant   = "auto_upgrade_grant"   // Hub → Agent:对一次请求的裁决;只有 granted 带下载凭据与发布签名
)

文本控制帧类型。

View Source
const (
	AutoUpgradeOff    = "off"    // 支持,但主机所有者没有开启
	AutoUpgradeNotify = "notify" // 只提示:发现新版本只记录与显示,不下载、不安装
	AutoUpgradeSilent = "silent" // 静默:发现新版本后自己下载、验签、升级(要求发布产物带独立签名)
)

Meta.AutoUpgrade 的取值。空串表示这个 Agent 不提供自动升级(旧版本、前台运行、临时身份、暂不支持的系统)。

View Source
const (
	AutoOfferDisabled    = "disabled"    // Hub 的总闸是关的:不提供任何自动升级
	AutoOfferNotAllowed  = "not_allowed" // 这台主机没有声明开启(模式 off / 没有声明)
	AutoOfferUpToDate    = "up_to_date"  // 没有比当前更新的版本
	AutoOfferAvailable   = "available"   // 有更新的版本,Version 是它
	AutoOfferUnavailable = "unavailable" // Hub 这边没有适用于这台主机的构建,或没有版本清单
	AutoOfferTooSoon     = "too_soon"    // 检查得太频繁,这次不回答实质内容
)

AutoUpgradeOffer.Status 的取值。

View Source
const (
	AutoGrantGranted     = "granted"     // 批准:帧里有下载凭据、SHA-256 与发布签名
	AutoGrantDisabled    = "disabled"    // Hub 的总闸是关的
	AutoGrantNotAllowed  = "not_allowed" // 这台主机没有声明静默模式(或是临时身份)
	AutoGrantUpToDate    = "up_to_date"  // 没有比当前更新的版本(或无法证明更新)
	AutoGrantStale       = "stale"       // Hub 上最新的版本已经不是请求的那个:请重新检查
	AutoGrantUnavailable = "unavailable" // Hub 没有适用于这台主机的构建,或没有版本清单
	AutoGrantUnsigned    = "unsigned"    // 这个发布版本没有发布签名:静默模式不会升级到它
	AutoGrantBusy        = "busy"        // 已经有一次升级在进行,或这台主机上有会损失的运行中会话:稍后再来
	AutoGrantTooSoon     = "too_soon"    // 请求得太频繁
)

AutoUpgradeGrant.Status 的取值。

View Source
const (
	// SubprotocolAgent 是 Agent↔Hub WebSocket 的子协议名(版本化,便于日后其他实现接入)。
	SubprotocolAgent = "relaymesh.agent.v1"
	// SubprotocolBrowser 是浏览器↔Hub 终端 WebSocket 的子协议名。
	SubprotocolBrowser = "relaymesh.term.v1"
	// TicketSubprotocolPrefix 用于在 Sec-WebSocket-Protocol 中携带一次性票据:
	// 浏览器 WebSocket 无法自定义请求头,放进 URL 会进入访问日志,因此放进子协议头(服务端在升级前读取、不记录)。
	TicketSubprotocolPrefix = "tk."
	// ProtocolVersion 是 challenge / hello 中的协议版本号。
	ProtocolVersion = 1
)

协议标识与版本。

View Source
const (
	CloseInvalidHandshake = 4401 // 握手或签名无效(多为版本不兼容),Agent 60 秒后重试
	CloseGateClosed       = 4403 // 终端总闸关闭(含免密私有直连模式)
	CloseNotFound         = 4404 // 目标主机不在线或会话不存在(浏览器侧)
	CloseUnknownMachine   = 4405 // 未知机器码且发现模式关闭
	CloseDisabled         = 4409 // 主机被停用 / 忽略
	CloseSessionEnded     = 4410 // 会话已结束(浏览器侧)
	CloseStalled          = 4412 // 附着方长时间不确认,被服务端断开(浏览器侧)
	CloseSuperseded       = 4413 // 同一机器码的新连接取代了旧连接
	CloseLagging          = 4414 // 附着方持续跟不上输出(会话有记录时):断开并要求重新附着,跳到最新输出(浏览器侧)
	CloseRateLimited      = 4429 // 限流或名额已满
)

WebSocket 应用层关闭码(4000~4999 为应用自定义范围)。

View Source
const (
	// MaxPreAuthFrame 是 online 之前(未启用或未完成握手)单帧的字节上限。
	MaxPreAuthFrame = 8 << 10
	// HandshakeTimeout 是 Hello 必须完成的期限。
	HandshakeTimeout = 10 * time.Second
	// MaxPreAuthConns / MaxPreAuthPerIP 是预认证阶段并发连接的全局 / 单 IP 上限。
	MaxPreAuthConns = 16
	MaxPreAuthPerIP = 4
	// MaxPending 是待启用列表的条数上限;PendingOfflineTTL 是离线条目保留时长。
	MaxPending        = 32
	PendingOfflineTTL = 10 * time.Minute
)

预认证与握手限额。

View Source
const (
	// MaxControlFrame 是 online 之后 JSON 控制帧的字节上限(hello 携带会话清单,需要比预认证更宽)。
	MaxControlFrame = 64 << 10
	// MaxDataPayload 是单个输出 / 输入二进制帧的净荷上限。
	MaxDataPayload = 32 << 10
	// MaxInputFrame 是浏览器单次输入帧上限,粘贴大文本由前端分块。
	MaxInputFrame = 16 << 10
	// AttachWindow 是附着后每通道在途(已发送未确认)字节窗口。
	AttachWindow = 256 << 10
	// StallTimeout 是窗口耗尽后附着方仍不确认则断开该附着的期限。
	StallTimeout = 10 * time.Second
	// LagUnacked / LagClear 是「附着方跟不上输出」的判据(迟滞):在途未确认量达到 LagUnacked 算饱和,降到 LagClear 以下才算恢复。
	// 链路带宽小于程序的输出速度时,窗口会一直停在接近满的位置;普通输出、快链路下窗口很快排空,不会触发。
	LagUnacked = AttachWindow * 3 / 4
	LagClear   = AttachWindow / 2
	// LagWarnAfter 是持续饱和多久后告诉浏览器「正在追赶」(浏览器据此盖上遮罩);LagEjectAfter 是持续多久后断开并要求重新附着。
	// 只对会话记录正常的附着生效:被跳过的中间输出得能从记录里读到,没有记录的会话保持无损背压。
	// 提醒在输出到来时第一时间发;撤回与断开每 250 毫秒检查一次(见 attach.go 的 attachTick),所以断开最多晚 250 毫秒。
	LagWarnAfter  = 500 * time.Millisecond
	LagEjectAfter = 1200 * time.Millisecond
	// LagInputGrace:浏览器刚送来键盘输入的这段时间里不断开——用户多半正在处理眼前的输出(最常见的是用 Ctrl+C 打断刷屏),
	// 断开重连的几秒里这些按键赶不上。提醒(遮罩)照常,只推迟断开;输入一停、过了这个时间还跟不上,才断开。
	LagInputGrace = 2 * time.Second
	// RingSize 是每会话回放缓冲的默认大小。
	RingSize = 1 << 20
	// CompactRingSize 是「精简会话」(会话守护预设启动的 Cursor CLI 会话)的回放缓冲大小:32 KiB 约为 100 行左右的可见输出。
	// CLI 自己的对话日志在 Cursor 里保存,终端里留一大截历史没有意义,还会让缓冲与回放持续膨胀(追加 #80)。
	CompactRingSize = 32 << 10
	// CompactMaxCols 是精简会话的终端宽度上限:再宽只会让每行更长、同样的缓冲装得更少。
	CompactMaxCols = 120
	// MaxTailLines 是浏览器请求「只回放末尾若干行」时接受的行数上限(超过按此截断)。
	MaxTailLines = 5000
	// TailMinBytes 是启用「只回放末尾若干行」的缓冲量门槛:缓冲里不足这么多字节的会话本来就回放得很快,
	// 整体回放还能保住完整的终端状态,没必要裁剪。
	TailMinBytes = 256 << 10
	// MaxSessionsPerHost 是每主机会话数上限。
	MaxSessionsPerHost = 16
	// DetachedTTL 是旧版本固定的「断开 7 天回收」。自 H1 起生命周期由 Policy.IdleSec 与会话设置决定(默认永久保持),
	// 这个常量只作为兼容旧 Hub 的参考值保留,不再是默认行为。
	DetachedTTL = 7 * 24 * time.Hour
	// MaxSessionNameRunes 是会话名上限;MaxRemarkRunes 是主机备注上限。
	MaxSessionNameRunes = 64
	MaxRemarkRunes      = 64
	// MaxCwdRunes 是「在原目录重建会话」所带目录路径的上限。
	MaxCwdRunes = 1024
)

已认证阶段的帧与会话限额。

View Source
const (
	MinIdleSec = 60
	MaxIdleSec = 400 * 24 * 3600
)

空闲回收(生命周期)的取值范围,单位秒。0 表示永久保持;其余取值必须落在 [MinIdleSec, MaxIdleSec] 内。

View Source
const (
	PingInterval = 15 * time.Second
	PongTimeout  = 45 * time.Second
)

心跳:WS ping 间隔与「无 pong 判定断链」的期限(两端对称)。

View Source
const (
	MaxHostnameRunes = 64
	MaxOSRunes       = 64
	MaxArchRunes     = 32
	MaxVersionRunes  = 32
)

自报字段长度上限(rune 数)。

View Source
const (
	HostStatusEnabled  = "enabled"
	HostStatusDisabled = "disabled"
	HostStatusBlocked  = "blocked"
)

主机状态(持久化在 terminal_hosts.status)。

View Source
const (
	PrivRoot  = "root"
	PrivAdmin = "admin"
	PrivUser  = "user"
)

Agent 特权等级(hello.meta.priv,自报,仅用于界面徽标与提示)。

View Source
const (
	KindPersistent = "persistent"
	KindTemporary  = "temporary"
)

Agent 形态(hello.meta.kind,自报):temporary 表示仅内存的临时身份,服务端不持久化其启用状态。

View Source
const (
	TFileReq = "file_req" // Hub→Agent:文件请求
	TFileRes = "file_res" // Agent→Hub:文件应答(成功与失败;read 成功时用 FrameFileData)
)

文件能力(P2)协议:Hub 经 Agent 在主机上做 stat / hash / 拉取 / 经 URL 推送。

授权分两层:Hub 判定令牌能不能碰这台主机(权限位、主机白名单、闸门、模式),随请求下发令牌允许的目录(roots); Agent 在本机做权威检查——路径必须落在 roots 之内,符号链接也不能逃出去(os.Root),推送的网址不得指向回环 / 私网 / 链路本地。 文件内容不经过 Hub 的数据库与审计:拉取时 Hub 只做内存里的中继,推送由 Agent 直接下载。

View Source
const (
	FileOpStat    = "stat"     // 取元数据(不存在不算错误)
	FileOpHash    = "hash"     // 计算 sha256
	FileOpOpen    = "open"     // 打开一个文件准备分块读取(拉取用),返回句柄
	FileOpRead    = "read"     // 读取句柄的一个区间
	FileOpClose   = "close"    // 释放句柄
	FileOpPushURL = "push_url" // 由 Agent 下载网址内容并原子写入目标路径
)

文件请求的操作。

View Source
const (
	FileFlagEOF  byte = 1 << 0 // 已读到文件末尾
	FileFlagLast byte = 1 << 1 // 本次 read 请求的最后一帧
)

FrameFileData 的标志位。

View Source
const (
	FileErrBadRequest   = "bad_request"      // 参数无效
	FileErrBadPath      = "bad_path"         // 路径不是绝对路径 / 含非法字符 / 格式不支持
	FileErrNotAllowed   = "path_not_allowed" // 路径不在允许的目录内(含通过符号链接逃出)
	FileErrNotFound     = "not_found"        // 文件或父目录不存在
	FileErrNotFile      = "not_a_file"       // 目标不是普通文件
	FileErrIsDir        = "is_directory"     // 目标是目录
	FileErrIsSymlink    = "is_symlink"       // 目标是符号链接(拒绝覆盖)
	FileErrExists       = "exists"           // 目标已存在且没有允许覆盖
	FileErrTooLarge     = "too_large"        // 超过大小上限
	FileErrPermission   = "permission_denied"
	FileErrIO           = "io_error"
	FileErrURLBlocked   = "url_blocked"     // 网址不被允许(协议、凭据、指向非公网地址等)
	FileErrDownload     = "download_failed" // 下载失败(连接 / 状态码 / 中断)
	FileErrHashMismatch = "hash_mismatch"   // 下载内容的 sha256 与给定值不一致
	FileErrTimeout      = "timeout"
	FileErrBusy         = "busy"           // 本机同时进行的文件操作过多
	FileErrDenied       = "denied_by_host" // 本机一票否决(--deny-model-exec)
	FileErrBadHandle    = "bad_handle"     // 句柄不存在或已过期
)

文件操作的稳定错误码(FileRes.Code)。

View Source
const (
	MaxFileRoots     = 20      // 一次请求最多带多少个允许目录
	MaxFilePathBytes = 1024    // 单个路径(含允许目录)的字节上限
	MaxFileURLBytes  = 2048    // 网址的字节上限
	MaxFileRead      = 1 << 20 // 一次 read 请求最多返回的字节数
	// MaxFileDataFrame 是单个 FrameFileData 的净荷上限(与运行输出帧一致)。
	MaxFileDataFrame = 32 << 10
	MaxFilePull      = 1 << 30   // 单次拉取的大小上限
	MaxFilePush      = 256 << 20 // 单次 URL 推送的大小上限
	MaxFileHash      = 4 << 30   // 单次 hash 处理的大小上限
)

文件相关的尺寸限制。

View Source
const (
	FileTypeFile    = "file"
	FileTypeDir     = "dir"
	FileTypeSymlink = "symlink"
	FileTypeOther   = "other"
)

文件类型取值(FileStat.Type)。

View Source
const (
	// Agent ↔ Hub
	TChallenge    = "challenge"
	THello        = "hello"
	TWelcome      = "welcome"
	TApproved     = "approved"
	TRejected     = "rejected"
	TPolicy       = "policy"
	TUninstall    = "uninstall" // Hub → Agent:卸载本机的 Agent 常驻服务(删除主机时可选;仅在 Meta.Uninstall 声明支持时发送)
	TOpen         = "open"
	TOpened       = "opened"
	TOpenFailed   = "open_failed"
	TAttach       = "attach"
	TAttached     = "attached"
	TAttachFailed = "attach_failed"
	TDetach       = "detach"
	TDetached     = "detached"
	TResize       = "resize"
	TKill         = "kill"
	TRename       = "rename"
	TLifecycle    = "lifecycle"
	TExit         = "exit"
	TSessions     = "sessions"
	TBye          = "bye"
	THolder       = "holder"

	// Hub ↔ 浏览器
	TReady  = "ready"
	TAck    = "ack"
	TPing   = "ping"
	TPong   = "pong"
	TClosed = "closed"
	// TLag 通知浏览器「你跟不上输出了 / 追上了」(见 BrowserLag)。旧浏览器忽略不认识的控制帧。
	TLag = "lag"
)

文本(JSON)控制帧的类型标识,存放在每条消息的 "t" 字段。

View Source
const (
	WelcomeEnabled = "enabled"
	WelcomePending = "pending"
)

主机状态在 welcome.status 中的取值。

View Source
const (
	SessionRunning = "running"
	SessionExited  = "exited"
)

会话状态。

View Source
const (
	BrowserOutput byte = 0x01 // [0x01][偏移 u64][输出](Hub→浏览器)
	BrowserInput  byte = 0x02 // [0x02][输入](浏览器→Hub)
)

浏览器 WS 二进制帧类型:[类型 1B][…]。

View Source
const (
	FrameOutput byte = 0x01 // [0x01][通道 u32][偏移 u64][输出](Agent→Hub)
	FrameInput  byte = 0x02 // [0x02][通道 u32][输入](Hub→Agent)
	FrameAck    byte = 0x03 // [0x03][通道 u32][已确认偏移 u64](Hub→Agent)
)

Agent↔Hub 二进制帧类型:[类型 1B][通道 u32][…]。

View Source
const (
	HolderReady       = "ready"       // 守护进程可用,Agent 已与它建立控制连接
	HolderUnavailable = "unavailable" // 守护进程暂不可达:新建 / 附着会话会失败,现有会话是否存活未知
)

会话守护进程(holder)的状态,取自 holder 帧的 state 字段。

View Source
const (
	HolderReasonConnecting  = "connecting"  // 正在连接
	HolderReasonSuperseded  = "superseded"  // 另一个 Agent 实例取代了本实例的控制连接
	HolderReasonVersion     = "version"     // 本地协议主版本不一致
	HolderReasonUnreachable = "unreachable" // 连不上(守护进程没启动、被停止或崩溃)
)

守护进程不可用的原因码(holder.reason)。

View Source
const (
	LostHostReboot    = "host_reboot"
	LostHolderExit    = "holder_exit"
	LostHolderStopped = "holder_stopped"
	LostUnknown       = "unknown"
)

会话丢失原因(LostSession.Reason)。

View Source
const (
	TGuiReq = "gui_req" // Hub→Agent:GUI 动作请求
	TGuiRes = "gui_res" // Agent→Hub:GUI 动作应答(成功与失败)
)

GUI 唤醒(#295)协议:Hub 经 Agent 在装着 Cursor 客户端的 Windows 主机上,通过本机回环的 Chromium 调试接口(CDP) 操作「Cursor Agents」窗口,做三件固定的事——只读探测(probe)、在旧会话里输入唤醒词并发送(resume)、新建会话并发送(new)。 设计稿:.cursor/planning/2026-10-30-295-gui-wake-design.md(文档库 design/gui-wake-295.md)。

信任边界:

  • 是否允许 GUI 动作、连哪个本机端口、允许哪些动作,由主机所有者在主机本地决定(数据目录里的 gui-wake.json),Hub 无法替他选; Agent 在握手里声明这个开关的状态(Meta.GuiWake),每次请求仍重读同意文件,声明只是提示。
  • Hub 只下发「动作 + 目标 + 文本」,**没有任何字段能带脚本**;页面里执行的全是 Agent 源码里的固定函数,要输入的文字走 Input.insertText。
  • 应答来自 Agent,全部字段都不可信:Hub 只用 Sanitized 之后的值。

结果语义(Outcome)是整个协议最重要的一条:它决定 Hub 能不能「回退到 CLI 唤醒」。

  • sent 点了发送,并且取到了发送证据;
  • not_sent 点发送**之前**就失败,窗口里没有留下我们输入的草稿——只有这一种可以安全回退,否则同一个会话可能被叫醒两次;
  • unknown 点了发送但没有取到证据(或应答本身不可信):Hub 与 Agent 都不重试、不回退,交给人到窗口里核对;
  • read 只读动作(probe)成功。
View Source
const (
	GuiOpProbe  = "probe"  // 只读:端点可达性、页面候选、选择器自检、侧栏会话行与输入框摘要
	GuiOpResume = "resume" // 旧会话:选中它、输入唤醒词、发送
	GuiOpNew    = "new"    // 新会话:在指定仓库分组里点 New Agent、输入唤醒词、发送
)

GUI 动作。

View Source
const (
	GuiWakeOff = "off" // 支持,但主机所有者没有在本机开启
	GuiWakeOn  = "on"  // 支持,且主机所有者已在本机开启
)

Meta.GuiWake 的取值。空串表示这个 Agent 不支持(旧版本、非 Windows 构建之外的暂不支持情形)。

View Source
const (
	GuiOutcomeSent    = "sent"
	GuiOutcomeNotSent = "not_sent"
	GuiOutcomeUnknown = "unknown"
	GuiOutcomeRead    = "read"
)

GuiRes.Outcome 的取值(语义见文件头)。

View Source
const (
	GuiStateRunning = "running"
	GuiStateStopped = "stopped"
	GuiStateUnknown = "unknown"
)

GuiRes.State 的取值:目标会话此刻在窗口里的状态。unknown 不等于已停止——读不到就是读不到。

View Source
const (
	GuiErrBadRequest    = "bad_request"    // 请求的形状不合规
	GuiErrDisabled      = "gui_disabled"   // 本机没有开启 GUI 唤醒(同意文件不存在 / enabled=false / 损坏)
	GuiErrOpNotAllowed  = "op_not_allowed" // 同意文件没有允许这个动作
	GuiErrDenied        = "denied_by_host" // 本机一票否决(--deny-model-exec)
	GuiErrBusy          = "busy_host"      // 本机已有一个 GUI 动作在进行
	GuiErrBadEndpoint   = "bad_endpoint"   // 同意文件里的端点不是 http://127.0.0.1:<端口>,或页面的调试地址不在同一回环端口
	GuiErrNoEndpoint    = "no_endpoint"    // 端点连不上(Cursor 没有用调试端口启动)
	GuiErrNoPage        = "no_page"        // 端点上没有「Cursor Agents」页面
	GuiErrAmbiguousPage = "ambiguous_page" // 有多个「Cursor Agents」页面,不挑第一个

	GuiErrSelectorInvalid   = "selector_invalid"   // 选择器覆盖的写法不对
	GuiErrSelectorMissing   = "selector_missing"   // 必需的元素没有匹配到
	GuiErrSelectorAmbiguous = "selector_ambiguous" // 应该唯一的元素匹配到多个(不挑第一个)

	GuiErrNoSuchConversation = "no_such_conversation" // 侧栏里没有这个会话编号
	GuiErrRepoMismatch       = "repo_mismatch"        // 会话所在的仓库分组与请求不一致
	GuiErrRepoNotFound       = "repo_not_found"       // 侧栏里没有这个仓库分组
	GuiErrNotSelected        = "not_selected"         // 点了行但没有变成选中
	GuiErrShellNotMounted    = "shell_not_mounted"    // 选中后会话面板(或输入框)没有在时限内挂载

	GuiErrConversationBusy         = "conversation_busy"          // 会话在运行
	GuiErrConversationStateUnknown = "conversation_state_unknown" // 读不到会话状态(不当作已停止)
	GuiErrDraftPresent             = "draft_present"              // 目标会话的输入框已有草稿
	GuiErrForegroundDraft          = "foreground_draft"           // 当前正在看的另一个会话的输入框有草稿(人可能正在打字)
	GuiErrBlockedDialog            = "blocked_dialog"             // 窗口里有未关闭的对话框 / 确认 / 错误提示

	GuiErrFocusFailed  = "focus_failed"  // 输入框没能获得焦点
	GuiErrInputFailed  = "input_failed"  // 输入的文字与期望不一致
	GuiErrSendDisabled = "send_disabled" // 提交按钮没有变成「可发送」

	GuiErrNewAgentMissing    = "new_agent_missing"    // 仓库分组里没有 New Agent 按钮
	GuiErrNewAgentAmbiguous  = "new_agent_ambiguous"  // 仓库分组里有多个 New Agent 按钮
	GuiErrNewAgentDisabled   = "new_agent_disabled"   // New Agent 按钮不可用
	GuiErrNewComposerMissing = "new_composer_missing" // 点了 New Agent 但没有出现新的输入框
	GuiErrNewIDUnresolved    = "new_id_unresolved"    // 发送了,但没有出现新的会话行(Outcome=unknown)
	GuiErrNewIDAmbiguous     = "new_id_ambiguous"     // 发送了,但新会话行不止一个,不按列表顺序猜(Outcome=sent,Conv 为空)

	GuiErrLocalIO = "local_io" // 本机文件读写失败(幂等表写不进去时宁可不动手)

	GuiErrOutcomeUnknown = "outcome_unknown" // 点了发送,但没有取到发送证据
	GuiErrDuplicate      = "duplicate"       // 同一幂等键的请求正在处理中(Outcome 固定为 unknown,不回退)
	GuiErrTimeout        = "timeout"         // 动作总时限到了
	GuiErrCDP            = "cdp_error"       // CDP 通道出错(连接 / 协议 / 页面脚本异常)
)

GUI 动作的稳定错误码(GuiRes.Code)。

View Source
const (
	MaxGuiText      = 4000 // 唤醒词的字符数上限(rune)
	MaxGuiRepoBytes = 200  // 仓库标识的字节上限
	GuiIdemMin      = 16   // 幂等键长度下限
	GuiIdemMax      = 64   // 幂等键长度上限

	MaxGuiProbeRows      = 100 // probe 最多返回多少个会话行
	MaxGuiProbeRepos     = 20  // probe 最多返回多少个仓库分组
	MaxGuiProbeChecks    = 40  // probe 最多返回多少条选择器自检
	MaxGuiProbeComposers = 20  // probe 最多返回多少个输入框摘要
	MaxGuiEvidence       = 16  // 一次应答最多带多少条证据
	MaxGuiMsgRunes       = 300 // 应答 Msg 的字符数上限
	MaxGuiEvidenceRunes  = 160 // 单条证据的字符数上限

	// MaxGuiResBytes 是一条 GuiRes 序列化后的字节上限,留出余量低于 MaxControlFrame(64 KiB):Hub 的读取端对超限的帧直接断开连接,
	// 所以诚实的 Agent 必须在发送前保证不超限——Sanitized 的最后一步(fit)会按「行 → 输入框摘要 → 仓库分组 → 自检 → 证据 → 快照」的顺序削减。
	MaxGuiResBytes = 48 << 10
)

GUI 动作的尺寸限制。

View Source
const (

	// NonceSize 是服务端挑战随机数的字节数。
	NonceSize = 32

	// MachineCodePrefix 是机器码前缀。
	MachineCodePrefix = "RM-"
)
View Source
const (
	TRecordRead = "record_read" // Hub→Agent:读取一段记录内容
	TRecordStat = "record_stat" // Hub→Agent:读取记录索引
	TRecordInfo = "record_info" // Agent→Hub:索引应答
	TRecordFail = "record_fail" // Agent→Hub:请求失败
)

终端记录(客户端侧)读取协议:Hub 向 Agent 请求某个会话已记录的终端显示内容。 内容只在人类读取时按页经 Agent→Hub 流出,Hub 不落盘(INV-M4)。

View Source
const (
	RecFlagEOF     byte = 1 << 0 // 已读到记录末尾(会话仍在运行时之后可能还有新内容)
	RecFlagSkipped byte = 1 << 1 // 请求的起点已被清理,数据从最早保留的分段开头开始
	RecFlagLast    byte = 1 << 2 // 本次请求的最后一帧
)

记录帧标志位。

View Source
const (
	MaxRecordFrameData = 48 << 10 // 单帧事件字节上限(须小于 MaxControlFrame)
	MaxRecordRead      = 1 << 20  // 单次请求返回的字节上限
	DefaultRecordRead  = 256 << 10
	MaxRecordInfoJSON  = 56 << 10
)

记录读取的尺寸上限。

View Source
const (
	RecOn        = "on"        // 正在录制
	RecPaused    = "paused"    // 暂停(磁盘不足或服务端策略临时关闭)
	RecError     = "error"     // 写盘失败,重试中
	RecOff       = "off"       // 服务端策略关闭了录制
	RecVeto      = "veto"      // 本机一票否决(--no-record)
	RecIncognito = "incognito" // 无痕会话
)

录制状态(SessionInfo.Rec)。

View Source
const (
	RecReasonNotFound = "not_found" // 没有该会话的记录(无痕、已过期或已被清理)
	RecReasonBusy     = "busy"      // Agent 正忙于其他读取
	RecReasonBad      = "bad_request"
	RecReasonError    = "error"
)

记录请求失败原因(RecordFail.Reason)。

View Source
const (
	TRun         = "run"           // Hub→Agent→守护进程:启动一次运行
	TRunStarted  = "run_started"   // 守护进程→Agent→Hub:进程已启动
	TRunFailed   = "run_failed"    // 守护进程→Agent→Hub:没能启动(含本机一票否决)
	TRunEnd      = "run_end"       // 守护进程→Agent→Hub:运行结束
	TRunCancel   = "run_cancel"    // Hub→Agent→守护进程:取消运行
	TRunAck      = "run_ack"       // Hub→Agent→守护进程:结束事件已处理,可停止补报
	TRuns        = "runs"          // 守护进程→Agent→Hub:控制端接上时的运行清单(用于对账)
	TRunsSync    = "runs_sync"     // Hub→Agent→守护进程:请求重发运行清单与尚未确认的结束事件
	TRunRead     = "run_read"      // Hub→Agent→守护进程:读取已保存的输出
	TRunReadFail = "run_read_fail" // 守护进程→Agent→Hub:读取失败
)

模型执行(非 PTY 的「一次调用 = 一次运行」)协议。

与人工终端的 PTY 会话并存、互不干扰:运行没有 TTY、stdin 关闭,输出分 stdout / stderr 两路, 完整输出只落在主机本地文件里(头 + 尾截断),Hub 只收到实时片段(仅用于给人看)、 结束时的结果摘要与短预览,从不存输出(INV-M4)。运行进程由主机上的守护进程持有, Agent 重启不影响运行,结束事件在 Agent 重连后补报。

View Source
const (
	// FrameRunOut 是实时输出片段:[0x05][运行 ID 16B][流 u8][偏移 u64][净荷](守护进程→Hub)。
	// 偏移是该流的累计字节位置;实时流可能因限速而跳过一段,跳过的部分仍完整记录在主机文件里。
	FrameRunOut byte = 0x05
	// FrameRunData 是 run_read 的应答:[0x06][req u32][标志 u8][流 u8][起点 u64][下一偏移 u64][总量 u64][净荷]。
	FrameRunData byte = 0x06
)

二进制帧类型(延续 FrameOutput..FrameRecord 的编号)。

View Source
const (
	StreamStdout byte = 1
	StreamStderr byte = 2
)

输出流编号。

View Source
const (
	RunExited    = "exited"    // 进程自行结束(含非 0 退出码)
	RunSignaled  = "signaled"  // 被信号终止(不是本机取消或超时造成的)
	RunTimeout   = "timeout"   // 超过 timeout_sec,被终止
	RunCancelled = "cancelled" // 收到取消请求,被终止
	RunLost      = "lost"      // 守护进程重启后发现进程已不存在,结果未知
)

运行的结束状态(RunEnd.State,守护进程上报)。

View Source
const (
	RunFailDenied      = "denied_by_host"   // 本机一票否决(--deny-model-exec)
	RunFailBusy        = "busy"             // 本机同时运行数达到保护上限
	RunFailBad         = "bad_request"      // 参数无效
	RunFailCwd         = "bad_cwd"          // 工作目录不存在或不是目录
	RunFailNoShell     = "no_shell"         // 找不到可用的 shell
	RunFailSpawn       = "spawn_failed"     // 进程启动失败
	RunFailUnavailable = "exec_unavailable" // 本机没有可用于保存运行输出的目录
	RunFailDuplicate   = "duplicate"        // 同一运行 ID 已存在
	RunFailHolder      = "holder_unavailable"
	RunFailDraining    = "shutting_down"
)

运行没能启动的原因(RunFailed.Reason)。

View Source
const (
	RunReadNotFound = "not_found"
	RunReadBusy     = "busy"
	RunReadBad      = "bad_request"
	RunReadError    = "error"
	RunReadHolder   = "holder_unavailable"
)

运行输出读取失败的原因(RunReadFail.Reason)。

View Source
const (
	// MaxRunCommandBytes 限制命令文本长度:run 帧要能放进 64 KiB 的控制帧(含 JSON 转义膨胀),所以远低于 64 KiB。
	MaxRunCommandBytes   = 24 << 10
	MaxRunCwdRunes       = 1024
	DefaultRunTimeoutSec = 120
	MaxRunTimeoutSec     = 7 * 24 * 3600

	// RunPreviewHead / RunPreviewTail 是结束时随 run_end 上报、Hub 落库的预览大小(合并 stdout / stderr,按到达顺序)。
	RunPreviewHead = 4 << 10
	RunPreviewTail = 2 << 10
	// RunInlineMax 是 run_end 里直接带上的单路输出的上限:小输出不需要再走一次读取往返。
	RunInlineMax = 8 << 10

	// DefaultRunRead / MaxRunRead 是一次 run_read 的默认 / 最大字节数;MaxRunDataFrame 是单个应答帧的净荷上限。
	DefaultRunRead  = 64 << 10
	MaxRunRead      = 256 << 10
	MaxRunDataFrame = 32 << 10
)

运行相关的尺寸限制。

View Source
const (
	RunFlagEOF     byte = 1 << 0 // 已读到这一路输出的末尾,且运行已经结束
	RunFlagGap     byte = 1 << 1 // 请求的起点落在被丢弃的中间部分,已从下一段可用内容开始
	RunFlagLast    byte = 1 << 2 // 本次请求的最后一帧
	RunFlagRunning byte = 1 << 3 // 运行仍在进行(之后可能还有新的输出)
)

应答帧标志位(FrameRunData)。

View Source
const (
	TSSHOp     = "ssh_op"     // Hub → 网关:一次性的 SSH 操作(探测 / 检查 / 代为执行 / 凭据维护)
	TSSHResult = "ssh_result" // 网关 → Hub:ssh_op 的结果
)

帧类型。

View Source
const (
	SSHOpProbe    = "probe"     // 只做密钥交换取回主机公钥,不发送任何认证信息
	SSHOpCheck    = "check"     // 用固定的主机公钥与凭据真实登录一次,并读取远端环境信息;persist 时成功后保存凭据
	SSHOpExec     = "exec"      // 在目标上运行一段脚本并回传输出(Hub 的 SSH 执行层经网关使用,目标须 stored)
	SSHOpCredDel  = "cred_del"  // 删除网关上保存的某台 SSH 主机的凭据
	SSHOpCredSync = "cred_sync" // 只保留名单内的凭据(回收其余),并回报仍持有哪些
)

ssh_op 的操作类型。

View Source
const (
	MaxSSHExecOut = 40 << 10 // 一次 exec 应答里 stdout 与 stderr 合计的上限
	MaxSSHKeep    = 512      // cred_sync 名单 / 回报的条数上限(远多于 SSH 主机数量上限)
)

ssh_op / ssh_result 的尺寸约束。Hub ↔ Agent 的控制帧不超过 MaxControlFrame(64 KiB),超限的帧会让对端关闭连接; 输出字节经 JSON 字节数组编码(base64,膨胀 4/3),所以一次 exec 应答里**两路输出合计**只放 40 KiB(编码后约 54 KiB)。

View Source
const (
	SSHCodeDisabled    = "gateway_disabled"    // 这台主机没有开启 SSH 网关能力
	SSHCodeDenied      = "target_denied"       // 目标不在网关本机的允许名单内
	SSHCodeBadRequest  = "bad_request"         // 目标信息无效
	SSHCodeUnreachable = "unreachable"         // 连不上目标 / 连接中断 / 超时
	SSHCodeAuth        = "auth_failed"         // 认证失败
	SSHCodeHostKey     = "host_key_mismatch"   // 主机密钥与已固定的不一致
	SSHCodeNoHostKey   = "no_host_key"         // 没有固定的主机密钥,拒绝连接
	SSHCodePassphrase  = "passphrase_required" // 私钥已加密,需要口令
	SSHCodeUnsupported = "unsupported"         // 目标不是受支持的 POSIX 环境
	SSHCodeBusy        = "busy"                // 网关正在处理太多 SSH 操作
	SSHCodeNoCred      = "no_credential"       // 网关上没有这台 SSH 主机的凭据(换了数据卷 / 重建了容器 / 还没登记)
	SSHCodeExecDenied  = "exec_denied"         // 网关本机用 --deny-model-exec 禁止了模型执行
	SSHCodeStore       = "cred_store"          // 网关无法读写自己的凭据库
	SSHCodeInternal    = "internal"
)

稳定的错误码(ssh_result.code 与 open_failed.code)。

View Source
const (
	TUpgrade       = "upgrade"        // Hub → Agent:请 Agent 自己下载新版本并升级(仅在 Meta.WebUpgrade == "on" 时发送)
	TUpgradeStatus = "upgrade_status" // Agent → Hub:升级进展 / 拒绝 / 失败
)

文本控制帧类型。

View Source
const (
	WebUpgradeOff = "off" // 支持,但主机所有者没有允许
	WebUpgradeOn  = "on"  // 支持,且主机所有者已允许
)

Meta.WebUpgrade 的取值。空串表示这个 Agent 不支持(旧版本、前台运行、临时身份、暂不支持的系统)。

View Source
const (
	UpgradeStageDownloading = "downloading" // 已接受请求,正在下载并校验
	UpgradeStageHandoff     = "handoff"     // 已校验通过,交给与 Agent 进程树无关的升级进程;Agent 随后会被重启
	UpgradeStageRefused     = "refused"     // 没有开始(本地开关、版本关系、正在进行等)
	UpgradeStageFailed      = "failed"      // 开始了但没有完成(下载、校验、交接失败);已安装的程序没有被改动
)

UpgradeStatus.Stage 的取值。

View Source
const (
	UpgradeCodeNotSupported = "not_supported" // 这个 Agent 不是以可升级的常驻服务运行
	UpgradeCodeNotAllowed   = "not_allowed"   // 主机所有者没有允许从 Web 升级
	UpgradeCodeUpToDate     = "up_to_date"    // 目标版本不比当前新
	UpgradeCodeBusy         = "busy"          // 已经有一次升级在进行
	UpgradeCodeBadRequest   = "bad_request"   // 请求的字段不合规
	UpgradeCodeDownload     = "download"      // 下载失败
	UpgradeCodeChecksum     = "checksum"      // 下载内容与 Hub 给出的 SHA-256 不一致
	UpgradeCodeSignature    = "signature"     // 下载内容没有通过发布签名验证(静默自动升级才要求)
	UpgradeCodeRecord       = "record"        // 无法在本机记录这次升级尝试(静默自动升级先记尝试再下载)
	UpgradeCodeVerify       = "verify"        // 新程序无法运行,或报出的版本不是期望的版本
	UpgradeCodeHandoff      = "handoff"       // 无法启动升级进程
	UpgradeCodeApply        = "apply"         // 升级进程已启动,但没能完成替换或重启(Agent 因此一直活着)
)

UpgradeStatus.Code 的取值(Stage 为 refused / failed 时给出)。

View Source
const (
	UpgradeOutcomeOK         = "ok"          // 升级完成,新版本已连上服务端
	UpgradeOutcomeRolledBack = "rolled_back" // 新版本没有连上服务端,已还原为旧版本
	UpgradeOutcomeFailed     = "failed"      // 升级进程没能完成(例如替换或重启失败)
)

UpgradeNote.Outcome 的取值。

View Source
const (
	// MaxUpgradeDetailRunes 限制自报的升级说明长度。
	MaxUpgradeDetailRunes = 240
	// MaxUpgradeVersionRunes 与分发目录 VERSION 文件允许的版本号长度一致。
	MaxUpgradeVersionRunes = 64
)
View Source
const FileRootAll = "*"

FileRootAll 是 FileReq.Roots 里的哨兵条目:令牌被明确授予「整个文件系统」(model.TerminalLimits.AllowWholeFS)。 Agent 见到它就不再把路径限制在某个目录里(路径仍须是规范的绝对路径;Windows 上是任一盘符)。 它不是合法的目录写法(RootProblem 拒绝),所以没有任何人工输入的允许目录能构造出它——只有 Hub 在令牌打开了开关时才会放进去。 旧版 Agent 不认识它,会把它当作无法解析的条目丢弃,于是一切路径都被拒绝(失败时更保守,而不是更宽松)。

View Source
const FrameFileData byte = 0x07

FrameFileData 是 read 请求的应答:[0x07][req u32][标志 u8][起点 u64][文件总大小 u64][净荷](Agent→Hub)。

View Source
const FrameRecord byte = 0x04

FrameRecord 是 Agent→Hub 的记录内容帧(一次 record_read 应答由一到多帧组成): [0x04][req u32][flags u8][seg u32][off u32][next_seg u32][next_off u32][事件字节] 事件字节与主机上分段文件里的编码完全一致(kind | dt uvarint | len uvarint | 净荷)。

View Source
const HolderCapRecLines = "rec_lines"

HolderCapRecLines 声明记录引擎支持「按行数限高」(Policy.RecMaxLines / --record-session-lines)。 升级只替换 Agent、不会重启会话守护进程,而记录引擎在守护进程里,所以 Hub 靠这个能力位判断一台主机上的设置是否已经生效。

View Source
const HolderCapSSH = "ssh"

HolderCapSSH 是会话守护进程在 holder 帧 caps 里声明的能力:本机开启了 SSH 网关。

View Source
const HolderCapSSHStore = "ssh_store"

HolderCapSSHStore 声明网关的凭据库可用,并支持 stored 目标与 exec / cred_del / cred_sync: 缺少它的网关(旧版本,或凭据库打不开)Hub 一律视为未就绪,不会向它发送任何 SSH 目标。

View Source
const MaxLostSessions = 64

MaxLostSessions 是一次 holder 帧里接受的「已丢失会话」条数上限。

View Source
const MaxRunsPerFrame = 256

MaxRunsPerFrame 是一个 runs 帧最多接受的条数。

View Source
const MaxSignatureTextLen = 128

MaxSignatureTextLen 是帧里发布签名文本的长度上限(与 relsign.MaxSignatureLen 相同;termproto 不依赖 relsign, 所以只在这里限字符集与长度,真正的验证在 Agent 里)。

Variables

View Source
var (
	ErrShortFrame    = errors.New("frame too short")
	ErrWrongFrame    = errors.New("unexpected frame type")
	ErrPayloadTooBig = errors.New("frame payload too large")
)

二进制帧解码错误。

View Source
var ErrBadMachineCode = errors.New("invalid machine code")

ErrBadMachineCode 表示字符串不是合法的机器码。

View Source
var ErrUnsupportedVersion = errors.New("unsupported protocol version")

ErrUnsupportedVersion 表示协议版本不兼容。

GuiOps 是全部动作,按规范顺序排列(Meta.GuiWakeOps 与同意文件的 allow 都按这个顺序写)。

Functions

func CanonGuiOps added in v2.2.0

func CanonGuiOps(s string) string

CanonGuiOps 把逗号分隔的动作清单规整为规范形式:只留已知动作、去重、按 GuiOps 的顺序;没有任何已知动作返回空串。

func ClampIdle

func ClampIdle(sec int) int

ClampIdle 把空闲回收秒数规整到合法范围:不大于 0 的一律视为永久保持(0),过小抬到 MinIdleSec,过大压到 MaxIdleSec。 守护进程用它兜住任何来源(策略、Open、SetLifecycle)的取值,避免一个异常数字让会话被立刻回收。

func ClampSize

func ClampSize(rows, cols uint16) (uint16, uint16)

ClampSize 把终端尺寸限制在 [1, 1000];0 视为未指定并回落到 24×80。

func CompareAgentRev

func CompareAgentRev(a, b string) (same, known bool)

CompareAgentRev 比较两个指纹。known 为 false 表示至少一边没有声明或不合法,调用方必须回退到版本号比较; known 为 true 时 same 说明两边的 Agent 代码是否一致。

func DecodeAck

func DecodeAck(frame []byte) (ch uint32, offset uint64, err error)

DecodeAck 解码确认帧;长度必须精确。

func DecodeBrowserInput

func DecodeBrowserInput(frame []byte) (payload []byte, err error)

DecodeBrowserInput 解码浏览器→Hub 的输入帧,净荷不得超过 MaxInputFrame。

func DecodeBrowserOutput

func DecodeBrowserOutput(frame []byte) (offset uint64, payload []byte, err error)

DecodeBrowserOutput 解码浏览器侧输出帧(供测试与 Go 客户端使用)。

func DecodeInput

func DecodeInput(frame []byte) (ch uint32, payload []byte, err error)

DecodeInput 解码输入帧。

func DecodeKey

func DecodeKey(s string, want int) ([]byte, error)

DecodeKey 解码 base64url;要求 want 字节长度精确匹配,防止截断或超长输入。

func DecodeOutput

func DecodeOutput(frame []byte) (ch uint32, offset uint64, payload []byte, err error)

DecodeOutput 解码输出帧;返回的 payload 与 frame 共享底层数组。

func DecodeRunOut

func DecodeRunOut(frame []byte) (id string, stream byte, offset uint64, payload []byte, err error)

DecodeRunOut 解码实时输出片段;返回的 payload 与 frame 共享底层数组。

func EncodeAck

func EncodeAck(ch uint32, offset uint64) []byte

EncodeAck 编码 Hub→Agent 的确认帧。

func EncodeBrowserInput

func EncodeBrowserInput(payload []byte) []byte

EncodeBrowserInput 编码浏览器→Hub 的输入帧(供测试与 Go 客户端使用)。

func EncodeBrowserOutput

func EncodeBrowserOutput(offset uint64, payload []byte) []byte

EncodeBrowserOutput 编码 Hub→浏览器的输出帧。

func EncodeFileData

func EncodeFileData(c FileChunk) []byte

EncodeFileData 编码 read 的应答帧。

func EncodeInput

func EncodeInput(ch uint32, payload []byte) []byte

EncodeInput 编码 Hub→Agent 的输入帧。

func EncodeKey

func EncodeKey(b []byte) string

EncodeKey / DecodeKey 用 base64url(无填充)在 JSON 与库中表示公钥、签名与 nonce。

func EncodeOutput

func EncodeOutput(ch uint32, offset uint64, payload []byte) []byte

EncodeOutput 编码 Agent→Hub 的输出帧。

func EncodeRecord

func EncodeRecord(c RecordChunk) []byte

EncodeRecord 编码记录内容帧。

func EncodeRunData

func EncodeRunData(c RunChunk) []byte

EncodeRunData 编码 run_read 的应答帧。

func EncodeRunOut

func EncodeRunOut(id string, stream byte, offset uint64, payload []byte) []byte

EncodeRunOut 编码实时输出片段;id 必须是合法的运行 ID(否则返回 nil)。

func FrameType

func FrameType(frame []byte) (byte, error)

FrameType 返回二进制帧的类型字节;空帧返回 ErrShortFrame。

func GuiRepoProblem added in v2.2.0

func GuiRepoProblem(s string) string

GuiRepoProblem 检查仓库标识(Cursor 侧栏分组的 data-agent-drop-section-id,形如 repo:github.com/owner/name)的写法;空串表示合法。 只看字符串:必须以 repo: 开头且后面有内容,不超过 MaxGuiRepoBytes,没有空白、控制字符与格式字符。

func GuiTextProblem added in v2.2.0

func GuiTextProblem(s string) string

GuiTextProblem 检查要输入的唤醒词;空串表示合法:非空白、不超过 MaxGuiText 个字符、合法 UTF-8, 没有控制字符(含换行、制表)、格式字符(双向控制符、零宽字符)与行 / 段分隔符。唤醒词由 Hub 渲染现有模板(可信来源), 这里是第二道关:Agent 不信任任何来自网络的文字。

func MachineCode

func MachineCode(pub ed25519.PublicKey) string

MachineCode 由 Ed25519 公钥派生机器码: "RM-" + SHA-256("relaymesh-machine-code-v1\0" ‖ 公钥) 前 80 位的 Crockford Base32,4-4-4-4 分组。

机器码是公钥指纹而非随机数或系统 machine-id:码本身可以公开出现在界面与日志里, 而冒用它需要对应私钥,因此「看到机器码」不等于「能冒充该主机」。

func Marshal

func Marshal(v any) ([]byte, error)

Marshal 把控制帧编码为 JSON;编码失败属于程序错误,返回 error 供调用方处理。

func NewNonce

func NewNonce() ([]byte, error)

NewNonce 生成服务端挑战用的随机数。

func NormalizeMachineCode

func NormalizeMachineCode(input string) (string, error)

NormalizeMachineCode 把用户输入规整为规范形式并校验: 大小写不敏感,忽略空白与连字符,按 Crockford 规则把易混字符映射(O→0,I/L→1),前缀 RM 可省略。

func ParseStream

func ParseStream(name string) (byte, bool)

ParseStream 把流名称解析成编号。

func ParseType

func ParseType(data []byte) (string, error)

ParseType 读取 JSON 控制帧的类型字段。

func RandomMachineCode

func RandomMachineCode() (string, error)

RandomMachineCode 生成一个随机的机器码(同样的 RM- 格式,因而令牌白名单、校验与界面都能直接复用)。 它用于没有 Agent、也就没有密钥对可以派生机器码的主机(SSH 主机);唯一性由调用方在落库时保证。

func RootProblem

func RootProblem(p string) string

RootProblem 检查令牌「允许目录」条目的写法,返回问题描述;空串表示合法。只看字符串,不访问文件系统。

合法写法:`~` 或 `~/…`(Agent 所在账户的家目录)、`/…` 绝对路径、`C:\…` 或 `C:/…` 盘符路径。 文件系统根(`/`、`C:\`)、UNC / 设备路径、相对路径、`~用户名`、含 `..` 片段、含控制字符的写法一律不接受: 把根目录当作允许目录等于不设防,`..` 则会让条目的真实含义与写法对不上。

func SSHLabel

func SSHLabel(user, addr string) string

SSHLabel 生成会话标签里展示的目标描述(不含凭据)。

func SanitizeAgentRev

func SanitizeAgentRev(s string) string

SanitizeAgentRev 返回合法的指纹,否则返回空串。空串表示对端没有声明(旧版本 / 非发布构建),调用方回退到版本号比较。

func SanitizePlatform

func SanitizePlatform(s string) string

SanitizePlatform 校验 Agent 自报的平台标识(GOOS-GOARCH,如 linux-amd64):写法不合规一律当作没有声明。 它只用来在分发目录里找对应的二进制,所以只接受小写字母与数字组成的两段,绝不放行路径或空白。

func SanitizeSSHCode

func SanitizeSSHCode(code string) string

SanitizeSSHCode 把来自对端的错误码规整成已知的稳定取值。

func SanitizeText

func SanitizeText(s string, maxRunes int) string

SanitizeText 把不可信文本(主机名、系统名、备注、会话名等)规整为可安全展示的纯文本:

  • 非法 UTF-8 整体丢弃对应字节;
  • 只保留「可显示」字符(字母、组合记号、数字、标点、符号与普通空格); 控制字符(含换行、制表、ESC)、格式字符(双向控制符、零宽字符、BOM)、行 / 段分隔符、 私用区与未分配码位全部去除;其他各类空白统一映射为普通空格并折叠;
  • 连续组合记号最多保留 maxConsecutiveMarks 个;
  • 首尾空白去除,并按 rune 数截断到 maxRunes。

界面与日志只应按纯文本输出其结果(绝不使用 v-html)。maxRunes<=0 表示不限长,仅用于内部测试。

func SignChallenge

func SignChallenge(priv ed25519.PrivateKey, nonce []byte) []byte

SignChallenge 用私钥对「域前缀 ‖ nonce」签名。

func StreamName

func StreamName(s byte) string

StreamName 返回流的名称;未知编号返回空串。

func ValidAgentRev

func ValidAgentRev(s string) bool

ValidAgentRev 判断 s 是否是合法的 Agent 侧代码指纹(计算方式见 internal/agentrev)。

版本号跟着整个仓库的构建走,服务端每热更一次就变一次;指纹只在 Agent 二进制依赖的代码真的变了时才变。 所以「要不要升级」「守护进程是否落后」先比指纹:指纹一致,两边跑的就是同一份 Agent 代码,版本号不同只是构建号不同。

func ValidAgentVersion

func ValidAgentVersion(s string) bool

ValidAgentVersion 判断 s 是否是可以出现在升级请求里的版本号(与分发目录 VERSION 文件的规则一致)。

func ValidAutoUpgradeMode

func ValidAutoUpgradeMode(s string) bool

ValidAutoUpgradeMode 判断 s 是否是「主机所有者可以选的开启模式」(不含 off:关闭是删除同意,不是一种模式)。

func ValidAutoWindow

func ValidAutoWindow(s string) bool

ValidAutoWindow 判断 s 是否是合规的时间段写法(不含空串)。起止相同的写法(如 03:00-03:00)含义含糊,不合规。

func ValidFileHandle

func ValidFileHandle(s string) bool

ValidFileHandle 判断句柄是否为 128 位小写十六进制。

func ValidFileOp

func ValidFileOp(op string) bool

ValidFileOp 判断操作名是否为已知值。

func ValidGuiConv added in v2.2.0

func ValidGuiConv(s string) bool

ValidGuiConv 判断是否为小写 UUID(Cursor 的对话编号写法)。

func ValidGuiErr added in v2.2.0

func ValidGuiErr(code string) bool

ValidGuiErr 判断错误码是否为已知值。

func ValidGuiIdem added in v2.2.0

func ValidGuiIdem(s string) bool

ValidGuiIdem 判断幂等键是否为 16–64 位 [A-Za-z0-9_-]。

func ValidGuiOp added in v2.2.0

func ValidGuiOp(op string) bool

ValidGuiOp 判断动作名是否为已知值。

func ValidMachineCode

func ValidMachineCode(s string) bool

ValidMachineCode 判断 s 是否已经是规范形式的机器码(不做任何宽松规整)。

func ValidRunID

func ValidRunID(s string) bool

ValidRunID 判断运行 ID 是否为 128 位小写十六进制。

func ValidRunState

func ValidRunState(s string) bool

ValidRunState 判断结束状态是否为已知值。

func ValidSHA256Hex

func ValidSHA256Hex(s string) bool

ValidSHA256Hex 判断是否为 64 位小写十六进制摘要。

func ValidSessionID

func ValidSessionID(s string) bool

ValidSessionID 判断会话 ID 是否为 128 位小写十六进制。

func ValidUpgradeID

func ValidUpgradeID(id string) bool

ValidUpgradeID 判断 id 是否是合规的升级标识(Hub 生成时按它自检)。

func VerifyChallenge

func VerifyChallenge(pub ed25519.PublicKey, nonce, sig []byte) bool

VerifyChallenge 校验签名。pub 与 sig 的长度必须严格符合 Ed25519,否则直接判定失败(不 panic)。

Types

type Approved

type Approved struct {
	T      string `json:"t"`
	Policy Policy `json:"policy"`
}

Approved 在待启用的主机被管理员启用后,于同一连接推送。

type Attach

type Attach struct {
	T     string `json:"t"`
	Ch    uint32 `json:"ch"`
	SID   string `json:"sid"`
	Since uint64 `json:"since"`
	Rows  uint16 `json:"rows,omitempty"`
	Cols  uint16 `json:"cols,omitempty"`
	// TailLines 只对全新附着(since = 0)有意义:缓冲量足够大、会话记录又在正常录制时,只回放主屏末尾这么多行,
	// 更早的内容由浏览器按需读取记录。0 = 整体回放(旧行为)。
	// 不认识这个字段的旧版本 Agent / 守护进程会忽略它,照常整体回放,所以无需同步升级。
	TailLines uint16 `json:"tail_lines,omitempty"`
}

Attach 请求把一条数据通道附着到会话;通道号由 Hub 分配(每条 Agent 连接内唯一)。

type AttachFailed

type AttachFailed struct {
	T      string `json:"t"`
	Ch     uint32 `json:"ch"`
	SID    string `json:"sid"`
	Reason string `json:"reason"`
}

AttachFailed 是 Attach 的失败应答。

type Attached

type Attached struct {
	T         string `json:"t"`
	Ch        uint32 `json:"ch"`
	SID       string `json:"sid"`
	Base      uint64 `json:"base"`
	End       uint64 `json:"end"`
	From      uint64 `json:"from"`                // 实际回放起点(首个数据帧的偏移)
	Truncated bool   `json:"truncated,omitempty"` // 请求的起点已被缓冲覆盖
	Prefix    string `json:"prefix,omitempty"`    // base64:应先写入终端的模式恢复序列(不占用偏移)
	Rows      uint16 `json:"rows"`
	Cols      uint16 `json:"cols"`
	State     string `json:"state"`
	ExitCode  *int   `json:"exit_code,omitempty"`
}

Attached 是 Attach 的成功应答,随后开始按偏移输出数据帧。

type AutoUpgradeCheck

type AutoUpgradeCheck struct {
	T  string `json:"t"`
	ID string `json:"id"`
}

AutoUpgradeCheck 是 Agent 的一次检查。帧里只有标识:版本与平台以握手时声明的为准(Hub 本来就有), 这样 Agent 无法借检查帧让 Hub 去查任意版本或任意平台。

func (AutoUpgradeCheck) Validate

func (c AutoUpgradeCheck) Validate() error

Validate 检查字段格式。

type AutoUpgradeGrant

type AutoUpgradeGrant struct {
	T      string `json:"t"`
	ID     string `json:"id"`
	Status string `json:"status"`
	// 以下只在 Status 为 granted 时有:目标版本(与请求一致)、这台主机的升级窗口票据、
	// 目标平台程序的 SHA-256,以及发布流程给这个(版本、平台、SHA-256)签的名(rmsig1:…)。
	Version string `json:"version,omitempty"`
	Ticket  string `json:"ticket,omitempty"`
	SHA256  string `json:"sha256,omitempty"`
	Sig     string `json:"sig,omitempty"`
}

AutoUpgradeGrant 是 Hub 对静默升级请求的裁决。Agent 收到后必须先过 Sanitized:它来自对端,不可信。 与 AutoUpgradeOffer 不同,granted 的裁决带有下载凭据——所以它只在 Agent 自己发出请求之后才会被采纳。

func (AutoUpgradeGrant) Sanitized

func (g AutoUpgradeGrant) Sanitized() (AutoUpgradeGrant, bool)

Sanitized 返回净化后的副本;标识或状态不认识、或 granted 缺少合规的凭据时返回 false。 不是 granted 的裁决里夹带的凭据一律丢弃。

func (AutoUpgradeGrant) ToUpgrade

func (g AutoUpgradeGrant) ToUpgrade() Upgrade

ToUpgrade 把已净化的 granted 裁决转成 upgrade 帧的形状:Agent 复用 Web 一键升级的下载 / 校验 / 交接链路, 以及它对各字段的 Validate。

type AutoUpgradeOffer

type AutoUpgradeOffer struct {
	T      string `json:"t"`
	ID     string `json:"id"`
	Status string `json:"status"`
	// Version 是 Hub 上最新的 Agent 版本;Status 为 available / up_to_date 时给出。
	Version string `json:"version,omitempty"`
}

AutoUpgradeOffer 是 Hub 对检查的回答。Agent 收到后必须先过 Sanitized:它来自对端,不可信。

func (AutoUpgradeOffer) Sanitized

func (o AutoUpgradeOffer) Sanitized() (AutoUpgradeOffer, bool)

Sanitized 返回净化后的副本;标识或状态不认识时返回 false。

type AutoUpgradeRequest

type AutoUpgradeRequest struct {
	T       string `json:"t"`
	ID      string `json:"id"`
	Version string `json:"version"`
}

AutoUpgradeRequest 是静默模式的 Agent 在「决定现在就升级」时发出的请求:只有标识与它想升级到的版本。 版本、平台、模式仍以握手时声明的为准——Agent 无法借请求让 Hub 去签发别的平台、别的主机的东西。 ID 同时是之后 upgrade_status 进展报告里的升级标识(Hub 把这次请求登记为一次升级)。

func (AutoUpgradeRequest) Validate

func (r AutoUpgradeRequest) Validate() error

Validate 检查字段格式。

type BrowserAck

type BrowserAck struct {
	T      string `json:"t"`
	Offset uint64 `json:"offset"`
}

BrowserAck 是浏览器确认已渲染到某偏移(驱动流控窗口)。

type BrowserClosed

type BrowserClosed struct {
	T      string `json:"t"`
	Reason string `json:"reason"`
}

BrowserClosed 在服务端主动断开附着前给出原因。

type BrowserExit

type BrowserExit struct {
	T      string `json:"t"`
	Code   *int   `json:"code,omitempty"`
	Signal string `json:"signal,omitempty"`
}

BrowserExit 通知浏览器会话已结束。

type BrowserLag

type BrowserLag struct {
	T  string `json:"t"`
	On bool   `json:"on"`
}

BrowserLag 告诉浏览器它跟不上会话输出的状态变化:On 为真表示持续饱和(浏览器应盖上「正在追赶」遮罩, 若饱和持续下去服务端会以 CloseLagging 断开并要求重新附着),为假表示已经追上。

type BrowserReady

type BrowserReady struct {
	T         string `json:"t"`
	SID       string `json:"sid"`
	Base      uint64 `json:"base"`
	End       uint64 `json:"end"`
	From      uint64 `json:"from"`
	Truncated bool   `json:"truncated,omitempty"`
	Prefix    string `json:"prefix,omitempty"`
	Rows      uint16 `json:"rows"`
	Cols      uint16 `json:"cols"`
	State     string `json:"state"`
	ExitCode  *int   `json:"exit_code,omitempty"`
}

BrowserReady 在浏览器附着成功后下发。

type BrowserResize

type BrowserResize struct {
	T    string `json:"t"`
	Rows uint16 `json:"rows"`
	Cols uint16 `json:"cols"`
}

BrowserResize 是浏览器上报的终端尺寸。

type Bye

type Bye struct {
	T      string `json:"t"`
	Reason string `json:"reason,omitempty"`
}

Bye 通知对端即将关闭(附带原因,便于日志与界面提示)。

type Challenge

type Challenge struct {
	T     string `json:"t"`
	V     int    `json:"v"`
	Nonce string `json:"nonce"`
}

Challenge 是服务端发出的一次性挑战。

type Detach

type Detach struct {
	T  string `json:"t"`
	Ch uint32 `json:"ch"`
}

Detach 请求释放数据通道(Hub→Agent)。

type Detached

type Detached struct {
	T      string `json:"t"`
	Ch     uint32 `json:"ch"`
	Reason string `json:"reason"`
}

Detached 是 Agent 主动释放通道的通知(会话结束、停滞等)。

type Envelope

type Envelope struct {
	T string `json:"t"`
}

Envelope 仅用于先嗅探消息类型。

type ExecInfo

type ExecInfo struct {
	Shell string `json:"shell,omitempty"` // 默认 shell 的名称(bash / sh / pwsh / powershell / cmd …)
	Home  string `json:"home,omitempty"`  // 默认工作目录(账户家目录)
	Sep   string `json:"sep,omitempty"`   // 路径分隔符
}

ExecInfo 描述主机上模型运行使用的执行环境,用于 terminal_targets 让模型知道该写什么语法的命令。

type Exit

type Exit struct {
	T      string `json:"t"`
	SID    string `json:"sid"`
	Code   *int   `json:"code,omitempty"`
	Signal string `json:"signal,omitempty"`
}

Exit 通知会话中的进程已退出。

type FileChunk

type FileChunk struct {
	Req   uint32
	Flags byte
	Off   uint64 // 本帧第一个字节在文件中的位置
	Total uint64 // 打开时(或读取时)观察到的文件总大小
	Data  []byte
}

FileChunk 是 FrameFileData 解码后的内容。

func DecodeFileData

func DecodeFileData(frame []byte) (FileChunk, error)

DecodeFileData 解码 read 的应答帧;返回的 Data 与 frame 共享底层数组。

type FileReq

type FileReq struct {
	T     string   `json:"t"`
	Req   uint32   `json:"req"`
	Op    string   `json:"op"`
	Roots []string `json:"roots,omitempty"`
	Path  string   `json:"path,omitempty"`
	// Max 是 hash / open / push_url 允许处理的最大字节数;0 表示取协议上限。
	Max int64 `json:"max,omitempty"`

	// read / close
	Handle string `json:"h,omitempty"`
	Off    uint64 `json:"off,omitempty"`
	Len    int    `json:"len,omitempty"`

	// push_url
	URL       string `json:"url,omitempty"`
	Overwrite bool   `json:"overwrite,omitempty"`
	SHA256    string `json:"sha256,omitempty"` // 期望的内容摘要(小写十六进制),可选
}

FileReq 是 Hub→Agent 的文件请求。Roots 是令牌允许的目录;权威检查在 Agent 上完成。

func (FileReq) Problem

func (r FileReq) Problem() string

Problem 检查请求的结构是否合法,返回问题描述;合法返回空串。它只管形状(长度、字符、数量),不做路径授权。

type FileRes

type FileRes struct {
	T    string `json:"t"`
	Req  uint32 `json:"req"`
	OK   bool   `json:"ok"`
	Code string `json:"code,omitempty"`
	Msg  string `json:"msg,omitempty"`

	Stat   *FileStat `json:"stat,omitempty"`   // stat
	SHA256 string    `json:"sha256,omitempty"` // hash / push_url
	Size   int64     `json:"size,omitempty"`   // hash / open / push_url
	Handle string    `json:"h,omitempty"`      // open

	Status    int    `json:"status,omitempty"`    // push_url:最终响应的 HTTP 状态码
	Source    string `json:"source,omitempty"`    // push_url:最终来源(协议://主机[:端口],不含路径与查询串)
	Redirects int    `json:"redirects,omitempty"` // push_url:经过的重定向次数
}

FileRes 是 Agent→Hub 的文件应答。OK=false 时只有 Code / Msg 有意义。

func (FileRes) Sanitized

func (r FileRes) Sanitized() FileRes

Sanitized 返回净化后的副本:应答来自 Agent,全部字段都不可信。

type FileStat

type FileStat struct {
	Exists bool   `json:"exists"`
	Type   string `json:"type,omitempty"` // file | dir | symlink | other
	Size   int64  `json:"size,omitempty"`
	Mode   string `json:"mode,omitempty"`  // 八进制权限位(Windows 为空)
	MTime  int64  `json:"mtime,omitempty"` // Unix 秒
}

FileStat 是 stat 的结果。

type GuiCheck added in v2.2.0

type GuiCheck struct {
	Name string `json:"name"`
	Want string `json:"want"` // 期望的写法:=1、>=0 …
	Got  int    `json:"got"`
	OK   bool   `json:"ok"`
}

GuiCheck 是选择器自检的一项:这一类元素在页面里匹配到几个,期望是什么。偏离一眼能看出来,便于在 Cursor 改版后校准。

type GuiProbe added in v2.2.0

type GuiProbe struct {
	Reachable bool   `json:"reachable"`           // 端点可达
	Browser   string `json:"browser,omitempty"`   // /json/version 的 Browser(如 Chrome/148.0.7778.280)
	Pages     int    `json:"pages"`               // 符合条件的「Cursor Agents」页面个数(应为 1)
	Selectors string `json:"selectors,omitempty"` // 选择器表的版本标识
	Selected  string `json:"selected,omitempty"`  // 当前选中行的会话编号
	Blockers  int    `json:"blockers,omitempty"`  // 窗口里可见的对话框个数

	Checks    []GuiCheck         `json:"checks,omitempty"`
	RowsTotal int                `json:"rows_total,omitempty"` // 侧栏里的会话行总数(Rows 可能被截断到 MaxGuiProbeRows)
	Rows      []GuiProbeRow      `json:"rows,omitempty"`
	Repos     []GuiProbeRepo     `json:"repos,omitempty"`
	Composers []GuiProbeComposer `json:"composers,omitempty"`
}

GuiProbe 是 probe 的只读快照。**不含标题与聊天内容。**

type GuiProbeComposer added in v2.2.0

type GuiProbeComposer struct {
	Conv        string `json:"conv,omitempty"`
	Draft       bool   `json:"draft,omitempty"`
	Submit      string `json:"submit,omitempty"`       // 提交按钮的 aria-label(如 Send message / Stop generation / Start voice chat)
	SubmitState string `json:"submit_state,omitempty"` // 提交按钮的 data-state(如 active / stop)
}

GuiProbeComposer 是一个已挂载会话的输入框摘要:只有「有没有草稿」与提交按钮的文案 / 状态,不含草稿内容。

type GuiProbeRepo added in v2.2.0

type GuiProbeRepo struct {
	Repo      string `json:"repo"`
	Rows      int    `json:"rows"`
	NewAgents int    `json:"new_agents"` // 分组里 New Agent 按钮的个数
}

GuiProbeRepo 是侧栏里的一个仓库分组。

type GuiProbeRow added in v2.2.0

type GuiProbeRow struct {
	ID       string `json:"id"`
	Repo     string `json:"repo,omitempty"`
	State    string `json:"state,omitempty"` // 行上的状态文案原样(如 In progress / Completed),已净化
	Selected bool   `json:"selected,omitempty"`
	Mounted  bool   `json:"mounted,omitempty"` // 这个会话的面板是否常驻 DOM
}

GuiProbeRow 是侧栏里的一个会话行。不含标题与聊天内容:标题是用户的私人信息,唤醒用不着。

type GuiReq added in v2.2.0

type GuiReq struct {
	T   string `json:"t"`
	Req uint32 `json:"req"`
	Op  string `json:"op"`
	// Idem 是幂等键:同一个键最多动手一次(Agent 把近 30 分钟的结果持久化)。resume / new 必填;probe 可空。
	Idem string `json:"idem,omitempty"`
	// Conv 是目标会话的编号:resume 必填;probe 可选(限定到一行);new 必须为空。
	Conv string `json:"conv,omitempty"`
	// Repo 是仓库分组标识:new 必填;resume 可选(给了就核对行所在的分组);probe 必须为空。
	Repo string `json:"repo,omitempty"`
	// Text 是要输入的唤醒词:resume / new 必填;probe 必须为空。
	Text string `json:"text,omitempty"`
}

GuiReq 是 Hub→Agent 的 GUI 动作请求。字段含义见各动作;授权与界面检查全在 Agent 上完成。

func (GuiReq) Problem added in v2.2.0

func (r GuiReq) Problem() string

Problem 检查请求的结构是否合法,返回问题描述;合法返回空串。它只管形状(长度、字符、必填与互斥),不做授权与界面检查。

type GuiRes added in v2.2.0

type GuiRes struct {
	T       string `json:"t"`
	Req     uint32 `json:"req"`
	OK      bool   `json:"ok"`
	Outcome string `json:"outcome"`
	Code    string `json:"code,omitempty"`
	Msg     string `json:"msg,omitempty"`

	Conv     string    `json:"conv,omitempty"`     // new 成功时的新会话编号;resume 时回显目标
	State    string    `json:"state,omitempty"`    // 目标会话此刻的状态
	Evidence []string  `json:"evidence,omitempty"` // 发送证据与观察到的情况(短词,不含文字内容)
	Probe    *GuiProbe `json:"probe,omitempty"`    // probe 的快照;失败的动作也可以带一份(用于校准)
	Ms       int64     `json:"ms,omitempty"`       // Agent 侧的动作耗时(毫秒)
}

GuiRes 是 Agent→Hub 的 GUI 动作应答。Outcome 是权威字段,OK 只是它的派生(sent / read 为真)。

func (GuiRes) SafeToFallback added in v2.2.0

func (r GuiRes) SafeToFallback() bool

SafeToFallback 报告这次结果是否允许 Hub 回退到 CLI 唤醒:只有「点发送之前就失败」才可以。 点过发送的 sent / unknown、只读的 read,以及同键正在处理中的 duplicate(Outcome 为 unknown)都不回退。 只对 Sanitized 之后的值有意义。

func (GuiRes) Sanitized added in v2.2.0

func (r GuiRes) Sanitized() GuiRes

Sanitized 返回净化后的副本:应答来自 Agent,全部字段都不可信。

保守规则:Outcome 不是已知值时按 unknown 处理(绝不当作 not_sent——那会让 Hub 回退到 CLI、把同一个会话叫醒两次); OK 由 Outcome 推出,不信 Agent 自报的值;not_sent 带未知错误码时仍是 not_sent(回退只取决于 Outcome),错误码落到 cdp_error; sent 只允许带 new_id_ambiguous 一个提示码;read 不带错误码。

type Hello

type Hello struct {
	T        string        `json:"t"`
	V        int           `json:"v"`
	Pub      string        `json:"pub"`
	Sig      string        `json:"sig"`
	Meta     Meta          `json:"meta"`
	Sessions []SessionInfo `json:"sessions,omitempty"`
}

Hello 是 Agent 对挑战的应答。

func (Hello) Decode

func (h Hello) Decode() (ed25519.PublicKey, []byte, error)

Decode 解出并校验公钥与签名的编码、长度与版本;不做验签(验签需要本连接的 nonce)。

func (Hello) SanitizedSessions

func (h Hello) SanitizedSessions() []SessionInfo

SanitizedSessions 净化会话清单:丢弃非法项与超出上限的多余项。

type Holder

type Holder struct {
	T          string `json:"t"`
	State      string `json:"state"`
	Persistent bool   `json:"persistent"`
	Version    string `json:"version,omitempty"`
	// Rev 是守护进程自己的「Agent 侧代码指纹」:与 Agent 的 Meta.Rev 一致说明两者跑的是同一份代码,不需要重启守护进程。
	// 旧版本的守护进程没有这一项(服务端回退到能力位判断)。
	Rev     string        `json:"rev,omitempty"`
	BootID  string        `json:"boot_id,omitempty"`
	Started int64         `json:"started,omitempty"`
	Caps    []string      `json:"caps,omitempty"`
	Reason  string        `json:"reason,omitempty"`
	Lost    []LostSession `json:"lost,omitempty"`

	// DenyExec 是本机策略(G4)的摘要:为 true 表示这台主机用 --deny-model-exec 拒绝了一切模型运行(人工终端不受影响)。
	DenyExec bool `json:"deny_exec,omitempty"`
	// Exec 描述模型运行的执行环境(默认 shell、家目录、路径分隔符);不支持模型运行的守护进程不带这一项。
	Exec *ExecInfo `json:"exec,omitempty"`
}

Holder 是 Agent 向 Hub 报告的会话守护进程状态(Agent→Hub)。 内嵌模式下 Persistent=false:会话随 Agent 进程结束,界面据此标注「重启会中断」。

func (Holder) Sanitized

func (h Holder) Sanitized() Holder

Sanitized 返回净化后的副本:全部字段都来自对端,界面与日志只按纯文本渲染。

type Kill

type Kill struct {
	T   string `json:"t"`
	SID string `json:"sid"`
}

Kill 终止会话。

type LostSession

type LostSession struct {
	SID     string `json:"sid"`
	Name    string `json:"name,omitempty"`
	Cwd     string `json:"cwd,omitempty"`
	Created int64  `json:"created,omitempty"`
	Reason  string `json:"reason"`
	At      int64  `json:"at,omitempty"`
}

LostSession 描述一个已经不存在的会话以及它消失的原因,由守护进程在重启后上报。

type Meta

type Meta struct {
	Host string `json:"host"`
	OS   string `json:"os"`
	Arch string `json:"arch"`
	Ver  string `json:"ver"`
	// Rev 是这个 Agent 二进制的「Agent 侧代码指纹」(见 agentversion.go)。版本号跟着整个仓库的构建走,代码没变也会变;
	// 指纹只在 Agent 依赖的代码变了才变,服务端据此判断「可升级」。旧版本与非发布构建没有这一项,服务端回退到版本号比较。
	Rev  string `json:"rev,omitempty"`
	Priv string `json:"priv"`
	Kind string `json:"kind"`
	// Files 声明这个 Agent 能处理文件请求(file_req)。旧版本没有这一项,服务端据此判断「主机不支持」。
	Files bool `json:"files,omitempty"`
	// FilesAll 声明这个 Agent 认识 FileRootAll 哨兵(令牌被明确授予「整个文件系统」)。没有它的旧版 Agent 会拒绝一切路径,
	// 服务端据此在发请求之前就给出「请先升级 Agent」的明确说明,而不是让模型看到莫名其妙的越界错误。
	FilesAll bool `json:"files_all,omitempty"`
	// Uninstall 声明这个 Agent 是以常驻服务运行、并且知道如何卸载自己(收到 uninstall 帧时)。
	// 前台运行 / 临时身份 / 暂不支持的系统都不声明;旧版本没有这一项,服务端据此不提供「同时卸载设备端」。
	Uninstall bool `json:"uninstall,omitempty"`
	// Plat 是这个 Agent 的平台标识(运行时的 GOOS-GOARCH,如 linux-amd64),与分发目录里 Agent 二进制的平台后缀同一写法。
	// OS 字段是给人看的系统描述(如「Debian GNU/Linux 12」),无法据此挑出对应的二进制,所以单独声明:
	// 服务端在发出升级请求之前就能确认「分发目录里有适用于这台主机的二进制」,并取到它的校验值。
	Plat string `json:"plat,omitempty"`
	// WebUpgrade 声明这个 Agent 能响应 Hub 的 upgrade 帧自己升级:WebUpgradeOn 表示主机所有者已在本机允许,
	// WebUpgradeOff 表示支持但没有允许;空串是不支持(旧版本 / 前台运行 / 临时身份 / 暂不支持的系统)。见 upgrade.go。
	WebUpgrade string `json:"web_upgrade,omitempty"`
	// LastUpgrade 是 Agent 本地保存的上一次升级的结果(升级成功 / 已回滚 / 失败);没有则为空。
	LastUpgrade *UpgradeNote `json:"last_upgrade,omitempty"`
	// AutoUpgrade 声明主机所有者在本机为「自动升级」选的模式:AutoUpgradeNotify / AutoUpgradeSilent 表示已开启,
	// AutoUpgradeOff 表示支持但没有开启;空串是不支持(与 WebUpgrade 同样的条件,另加「旧版本」)。见 autoupgrade.go。
	AutoUpgrade string `json:"auto_upgrade,omitempty"`
	// AutoWindow 是主机所有者给静默自动升级限定的时间段(主机本地时间,HH:MM-HH:MM);空表示不限。
	// 只用于展示:是否在时间段内由 Agent 自己判断,Hub 不据此做任何决定。
	AutoWindow string `json:"auto_window,omitempty"`
	// GuiWake 声明这个 Agent 能处理 GUI 唤醒请求(gui_req,#295):GuiWakeOn 表示主机所有者已在本机开启,
	// GuiWakeOff 表示支持但没有开启;空串是不支持(旧版本)。它只是提示——每次请求 Agent 仍重读本机的同意文件。见 gui.go。
	GuiWake string `json:"gui_wake,omitempty"`
	// GuiWakeOps 是主机所有者在本机允许的 GUI 动作(逗号分隔,probe / resume / new 的子集,规范顺序);只在 GuiWake 非空时有意义,用于提前给出提示。
	GuiWakeOps string `json:"gui_wake_ops,omitempty"`
}

Meta 是 Agent 自报的元数据。**全部不可信**:使用前必须经过 Sanitized。

func (Meta) Sanitized

func (m Meta) Sanitized() Meta

Sanitized 返回净化并限长后的副本:控制字符、双向控制符、零宽字符、非法 UTF-8 一律去除; 枚举字段回落到安全默认值。界面与日志只按纯文本渲染这些字段。

type Open

type Open struct {
	T         string `json:"t"`
	Req       string `json:"req"`
	Name      string `json:"name,omitempty"`
	Rows      uint16 `json:"rows"`
	Cols      uint16 `json:"cols"`
	Incognito bool   `json:"incognito,omitempty"` // 无痕会话:不录制,主机上不留任何记录
	// Compact 为 true 时是「精简会话」:回放缓冲只有 CompactRingSize、终端宽度不超过 CompactMaxCols(会话守护预设用)。旧版 Agent 会忽略它。
	Compact bool `json:"compact,omitempty"`

	// IdleSec 为本会话单独设置的空闲回收秒数(0 = 永久保持);nil 表示沿用主机默认。
	IdleSec *int `json:"idle_sec,omitempty"`
	// Cwd 是希望新会话启动时所在的目录(「在原目录重建会话」);必须是主机上存在的绝对路径,否则回落到默认目录。
	Cwd string `json:"cwd,omitempty"`
	// SSH 非空表示这是一个经 SSH 网关的会话:不启动本机 shell,而是由本机的会话守护进程去连接这个目标。
	// 只在本机开启了 SSH 网关时才会被接受;open 只接受引用网关上已保存凭据的目标(Stored=true),帧里不带任何凭据;
	// 目标本身仍不应被随意打印(SSHTarget 自带脱敏)。
	SSH *SSHTarget `json:"ssh,omitempty"`
}

Open 请求在 Agent 上新建会话。

type OpenFailed

type OpenFailed struct {
	T      string `json:"t"`
	Req    string `json:"req"`
	Reason string `json:"reason"`
	// Code 是 SSH 会话失败时的稳定错误码(SSHCode*),普通会话为空。
	Code string `json:"code,omitempty"`
}

OpenFailed 是 Open 的失败应答。

type Opened

type Opened struct {
	T       string      `json:"t"`
	Req     string      `json:"req"`
	Session SessionInfo `json:"session"`
}

Opened 是 Open 的成功应答,sid 由 Agent 生成。

type Policy

type Policy struct {
	Terminal       bool   `json:"terminal"`
	MaxSessions    int    `json:"max_sessions,omitempty"`
	DetachedTTLSec int    `json:"detached_ttl_sec,omitempty"`
	Reason         string `json:"reason,omitempty"` // terminal=false 时的总闸原因码

	// IdleSec 是主机默认的生命周期:连续这么多秒没有交互(没人附着、也没有输入)才回收会话;0 表示永久保持。
	// 会话可以单独覆盖(Open.IdleSec / SetLifecycle)。强制执行者是守护进程,Hub 或 Agent 离线时照常计时。
	IdleSec int `json:"idle_sec,omitempty"`

	// 录制策略:只能比 Agent 本机配置更严格(关闭 / 缩短保留 / 降低配额),不能强制开启或放宽。
	RecOff           bool `json:"rec_off,omitempty"`
	RecRetentionDays int  `json:"rec_retention_days,omitempty"`
	RecSessionMB     int  `json:"rec_session_mb,omitempty"`
	RecHostMB        int  `json:"rec_host_mb,omitempty"`
	// RecMaxLines 是单个会话记录保留的输出行数上限(按换行符计,超出后滚动丢弃最旧的分段);0 表示不限制。
	// 同样只能比 Agent 本机配置更严格。旧版 Agent 不认识这个字段,会照旧只按字节上限滚动。
	RecMaxLines int `json:"rec_max_lines,omitempty"`
}

Policy 是服务端下发的策略;Agent 取「本地默认」与「策略」中更严的一方。

type PolicyMsg

type PolicyMsg struct {
	T      string `json:"t"`
	Policy Policy `json:"policy"`
}

PolicyMsg 是运行期策略变更(如总闸翻转)。

type RecordChunk

type RecordChunk struct {
	Req     uint32
	Flags   byte
	Seg     uint32
	Off     uint32
	NextSeg uint32
	NextOff uint32
	Data    []byte
}

RecordChunk 是 FrameRecord 解码后的内容。

func DecodeRecord

func DecodeRecord(frame []byte) (RecordChunk, error)

DecodeRecord 解码记录内容帧;返回的 Data 与 frame 共享底层数组。

type RecordFail

type RecordFail struct {
	T      string `json:"t"`
	Req    uint32 `json:"req"`
	Reason string `json:"reason"`
}

RecordFail 是记录请求的失败应答。

type RecordInfo

type RecordInfo struct {
	T    string          `json:"t"`
	Req  uint32          `json:"req"`
	SID  string          `json:"sid"`
	Info json.RawMessage `json:"info"`
}

RecordInfo 是索引应答;Info 是主机端 record.Info 的 JSON(不含任何终端内容)。

type RecordRead

type RecordRead struct {
	T   string `json:"t"`
	Req uint32 `json:"req"`
	SID string `json:"sid"`
	Seg uint32 `json:"seg,omitempty"`
	Off uint32 `json:"off,omitempty"`
	Max int    `json:"max,omitempty"`
}

RecordRead 请求读取一段记录内容:从 (Seg, Off) 起至多 Max 字节;Seg 为 0 表示从最早保留的分段开始。

type RecordStat

type RecordStat struct {
	T   string `json:"t"`
	Req uint32 `json:"req"`
	SID string `json:"sid"`
}

RecordStat 请求读取会话记录的索引信息。

type Rejected

type Rejected struct {
	T      string `json:"t"`
	Reason string `json:"reason,omitempty"`
}

Rejected 在待启用的主机被忽略时推送,随后以 CloseDisabled 关闭。

type Rename

type Rename struct {
	T    string `json:"t"`
	SID  string `json:"sid"`
	Name string `json:"name"`
}

Rename 修改会话名。

type Resize

type Resize struct {
	T    string `json:"t"`
	SID  string `json:"sid"`
	Rows uint16 `json:"rows"`
	Cols uint16 `json:"cols"`
}

Resize 调整会话 PTY 尺寸(以最近一次为准)。

type Run

type Run struct {
	T   string `json:"t"`
	ID  string `json:"id"`
	Cmd string `json:"cmd"`
	// Shell 为空表示自动选择(Unix:bash,其次 sh;Windows:pwsh、powershell、cmd);
	// 其余取值限定为 bash / sh / zsh / pwsh / powershell / cmd。
	Shell string `json:"shell,omitempty"`
	// Cwd 为空表示该账户的家目录。
	Cwd string `json:"cwd,omitempty"`
	// TimeoutSec 为 0 时取 DefaultRunTimeoutSec;上限 MaxRunTimeoutSec。
	TimeoutSec int `json:"timeout_sec,omitempty"`
}

Run 请求在主机上执行一条命令(Hub→Agent→守护进程)。

没有 env 字段是刻意的:模型不能给进程注入环境变量(LD_PRELOAD 一类的风险)。

type RunAck

type RunAck struct {
	T  string `json:"t"`
	ID string `json:"id"`
}

RunAck 表示 Hub 已处理该运行的结束事件,守护进程不必再补报。

type RunBrief

type RunBrief struct {
	ID      string `json:"id"`
	PID     int    `json:"pid,omitempty"`
	Started int64  `json:"started"`
}

RunBrief 是运行清单里的一项(仍在运行的)。

type RunCancel

type RunCancel struct {
	T  string `json:"t"`
	ID string `json:"id"`
	// Reason 是取消来源:user | model | pause | revoked | gate_closed | host_removed | token_changed | unknown_run(旧版本只有 system)。
	// 守护进程原样回报在 RunEnd.Reason 里(最长 32 个字符),Hub 把它存成运行记录的 deny_reason,界面据此解释「为什么被取消」。
	Reason string `json:"reason,omitempty"`
}

RunCancel 请求取消运行(先 TERM,宽限后 KILL,作用于整个进程组)。

type RunChunk

type RunChunk struct {
	Req    uint32
	Flags  byte
	Stream byte
	Off    uint64 // 本帧第一个字节在该路输出中的位置
	Next   uint64 // 继续读取应使用的偏移(跳过被丢弃部分后可能大于 Off+len(Data))
	Total  uint64 // 该路输出到目前为止产生的总字节数
	Data   []byte
}

RunChunk 是 FrameRunData 解码后的内容。

func DecodeRunData

func DecodeRunData(frame []byte) (RunChunk, error)

DecodeRunData 解码 run_read 的应答帧;返回的 Data 与 frame 共享底层数组。

type RunEnd

type RunEnd struct {
	T      string `json:"t"`
	ID     string `json:"id"`
	State  string `json:"state"`
	Code   *int   `json:"code,omitempty"`
	Signal string `json:"signal,omitempty"`
	// DurMS 是运行耗时(毫秒);OutBytes / ErrBytes 是两路输出产生的总字节数。
	DurMS    int64 `json:"dur_ms"`
	OutBytes int64 `json:"out_bytes"`
	ErrBytes int64 `json:"err_bytes"`
	// OutDropped / ErrDropped 是因「头 + 尾」截断而没有保留的中间字节数。
	OutDropped int64 `json:"out_dropped,omitempty"`
	ErrDropped int64 `json:"err_dropped,omitempty"`
	// Out / Err 在对应输出不超过 RunInlineMax 时直接给出全文;否则为空,需要用 run_read 读取。
	Out []byte `json:"out,omitempty"`
	Err []byte `json:"err,omitempty"`
	// PrevHead / PrevTail 是合并两路输出(按到达顺序)后的开头与结尾预览,仅用于列表与卡片。
	PrevHead []byte `json:"prev_head,omitempty"`
	PrevTail []byte `json:"prev_tail,omitempty"`
	Reason   string `json:"reason,omitempty"` // 补充说明(如 lost 时的原因)
}

RunEnd 报告运行结束。

func (RunEnd) Sanitized

func (e RunEnd) Sanitized() (RunEnd, bool)

Sanitized 返回净化并限长后的副本;ID 非法时 ok=false。

type RunFailed

type RunFailed struct {
	T      string `json:"t"`
	ID     string `json:"id"`
	Reason string `json:"reason"`
	Detail string `json:"detail,omitempty"`
}

RunFailed 报告运行没能启动。

func (RunFailed) Sanitized

func (f RunFailed) Sanitized() (RunFailed, bool)

Sanitized 返回净化后的副本;ID 非法时 ok=false。

type RunRead

type RunRead struct {
	T      string `json:"t"`
	Req    uint32 `json:"req"`
	ID     string `json:"id"`
	Stream string `json:"stream"` // stdout | stderr
	Off    uint64 `json:"off,omitempty"`
	Max    int    `json:"max,omitempty"`
}

RunRead 请求读取运行已保存的输出:从某一路的 Off 起至多 Max 字节。

type RunReadFail

type RunReadFail struct {
	T      string `json:"t"`
	Req    uint32 `json:"req"`
	Reason string `json:"reason"`
}

RunReadFail 是 run_read 的失败应答。

type RunStarted

type RunStarted struct {
	T       string `json:"t"`
	ID      string `json:"id"`
	PID     int    `json:"pid,omitempty"`
	Shell   string `json:"shell,omitempty"` // 实际使用的 shell(名称,不含路径)
	Cwd     string `json:"cwd,omitempty"`   // 实际工作目录
	Started int64  `json:"started"`         // 启动时间(Unix 毫秒,主机时钟)
}

RunStarted 报告进程已启动。

func (RunStarted) Sanitized

func (s RunStarted) Sanitized() (RunStarted, bool)

Sanitized 返回净化后的副本;ID 非法时 ok=false。

type Runs

type Runs struct {
	T       string     `json:"t"`
	Running []RunBrief `json:"running"`
}

Runs 是控制端接上守护进程时收到的运行清单:仍在运行的运行。 尚未被确认的结束事件会紧接着以独立的 run_end 帧补报(每个事件可能带有较大的内联输出,不适合塞进同一帧)。

func (Runs) Sanitized

func (r Runs) Sanitized() Runs

Sanitized 返回净化后的清单:丢弃非法项与超出上限的多余项。

type RunsSync

type RunsSync struct {
	T string `json:"t"`
}

RunsSync 请求守护进程重发运行清单(runs)与尚未被确认的结束事件(run_end)。 Agent 与 Hub 之间的链路断开期间产生的结束事件无处可投,重连后靠它补回;重发是幂等的。

type SSHOp

type SSHOp struct {
	T      string    `json:"t"`
	Req    string    `json:"req"`
	Op     string    `json:"op"`
	Target SSHTarget `json:"target"`

	// Persist(check):真实登录成功之后,把这份凭据保存到网关本机(键是 Target.ID);失败不留任何痕迹。
	Persist bool `json:"persist,omitempty"`

	// exec:交给远端的命令行与标准输入(Hub 生成的任务脚本,命令文本已在脚本里 base64,不会拼进命令行),
	// 以及两路输出合计的上限(<=0 取 MaxSSHExecOut,且不会超过它)。
	Cmd    string `json:"cmd,omitempty"`
	Stdin  []byte `json:"stdin,omitempty"`
	MaxOut int    `json:"max_out,omitempty"`

	// cred_sync:应当保留的 SSH 主机机器码;网关删除名单之外的凭据。
	Keep []string `json:"keep,omitempty"`
}

SSHOp 是 Hub 向网关发起的一次性 SSH 操作。

func (SSHOp) GoString

func (o SSHOp) GoString() string

GoString 脱敏描述(%#v)。

func (SSHOp) String

func (o SSHOp) String() string

String 脱敏描述(不含命令、标准输入与凭据)。

type SSHResult

type SSHResult struct {
	T    string `json:"t"`
	Req  string `json:"req"`
	OK   bool   `json:"ok"`
	Code string `json:"code,omitempty"`
	Msg  string `json:"msg,omitempty"`

	// probe:规整后的地址与探测到的主机公钥。
	Addr        string `json:"addr,omitempty"`
	KeyType     string `json:"key_type,omitempty"`
	HostKey     string `json:"host_key,omitempty"`
	Fingerprint string `json:"fingerprint,omitempty"`

	// check:远端环境信息与耗时。Posix 表示环境信息探测成功——目标是受支持的 POSIX 环境,可以被模型执行;
	// 探测失败(Windows OpenSSH、网络设备、受限 shell)仍然可以开人工终端。
	Host      string `json:"host,omitempty"`
	OS        string `json:"os,omitempty"`
	Arch      string `json:"arch,omitempty"`
	User      string `json:"user,omitempty"`
	Home      string `json:"home,omitempty"`
	LatencyMS int64  `json:"latency_ms,omitempty"`
	Posix     bool   `json:"posix,omitempty"`

	// exec:脚本的标准输出 / 标准错误与退出码(两路合计不超过 MaxSSHExecOut)。
	Stdout []byte `json:"stdout,omitempty"`
	Stderr []byte `json:"stderr,omitempty"`
	Exit   int    `json:"exit,omitempty"`

	// cred_sync:网关此刻仍持有凭据的主机码(名单内的部分)与被回收的凭据数。
	Have    []string `json:"have,omitempty"`
	Dropped int      `json:"dropped,omitempty"`
}

SSHResult 是 ssh_op 的结果。全部字段来自对端:Hub 使用前必须经过 Sanitized。

func (SSHResult) Sanitized

func (r SSHResult) Sanitized() SSHResult

Sanitized 返回净化并限长后的副本;未知的错误码一律归为 internal。

type SSHTarget

type SSHTarget struct {
	// ID 是 Hub 侧这台 SSH 主机的机器码:标注会话归属,同时是网关凭据库里这份凭据的键(不是秘密)。
	ID   string `json:"id,omitempty"`
	Addr string `json:"addr"`
	User string `json:"user"`
	// Auth 为 password 或 key;probe 不需要认证信息。
	Auth string `json:"auth,omitempty"`
	// Stored 为 true 表示凭据已保存在网关本机:帧里不带任何凭据,网关按 ID 取用(open / exec / check 复测都这样用)。
	Stored     bool   `json:"stored,omitempty"`
	Password   string `json:"password,omitempty"`
	PrivateKey string `json:"private_key,omitempty"`
	Passphrase string `json:"passphrase,omitempty"`
	// HostKey 是已固定的主机公钥(标准 base64 的 SSH 公钥线格式);probe 不需要,其余操作必须有。
	HostKey string `json:"host_key,omitempty"`
}

SSHTarget 描述网关要连接的目标。只有 check 帧会携带凭据(Hub → 网关方向),且永远不应被打印。

func (SSHTarget) GoString

func (t SSHTarget) GoString() string

GoString 同样脱敏(%#v)。

func (SSHTarget) String

func (t SSHTarget) String() string

String 只描述连到哪里,不含任何凭据(%v / %s / %+v 都会走到这里)。

type Screen

type Screen struct {
	Word      string  `json:"word,omitempty"`      // 状态行动词(Thinking / Working / Globbing ...),仅「现在还在动画」时有值
	Tokens    int     `json:"tokens"`              // 状态行里的实时 token 数;-1 = 没读到
	CtxPct    float64 `json:"ctx_pct"`             // 页脚的上下文占用百分比;-1 = 没读到
	Approval  bool    `json:"approval,omitempty"`  // 屏幕停在「Waiting for approval...」
	Cancelled bool    `json:"cancelled,omitempty"` // 最近一屏是「Cancelled • 15s」
	Animating bool    `json:"animating,omitempty"` // 最近 2 秒仍有输出字节
	BPS       float64 `json:"bps"`                 // 最近 5 秒的平均字节速率
	Quiet     int     `json:"quiet"`               // 距最后一次输出的秒数;-1 = 从未有输出
}

Screen 是一次屏幕扫描的线上格式。不含任何屏幕文字,只有状态词(取自白名单字符)、计数与标志。

type SessionInfo

type SessionInfo struct {
	SID      string `json:"sid"`
	Name     string `json:"name,omitempty"`
	Rows     uint16 `json:"rows"`
	Cols     uint16 `json:"cols"`
	Base     uint64 `json:"base"` // 环形缓冲中最旧字节的累计偏移
	End      uint64 `json:"end"`  // 已产生输出的累计字节数
	State    string `json:"state"`
	ExitCode *int   `json:"exit_code,omitempty"`
	Created  int64  `json:"created,omitempty"` // Agent 时钟的 Unix 秒,仅供展示(服务端不据此做任何 TTL 判定)
	Attached int    `json:"attached"`
	Shell    string `json:"shell,omitempty"`
	PID      int    `json:"pid,omitempty"`
	Alt      bool   `json:"alt,omitempty"` // 当前处于备用屏(全屏程序如 vim)
	// Target 非空表示这是经 SSH 网关的会话:值是 Hub 侧那台 SSH 主机的机器码(新建时由 Hub 指定,守护进程原样保存)。
	Target string `json:"target,omitempty"`

	// 生命周期(H1):Idle 是生效的「无交互多久后回收」秒数,0 表示永久保持;IdleOwn 表示这个会话单独设置过,
	// 否则沿用主机默认。Active 是最后一次交互(有输入,或附着数降为 0)的 Unix 秒;有人附着时即为「现在」。
	Idle    int   `json:"idle,omitempty"`
	IdleOwn bool  `json:"idle_own,omitempty"`
	Active  int64 `json:"active,omitempty"`

	// 录制状态(终端上显示什么就记录什么,内容只存在主机本地,这里只有索引)。
	Rec      string `json:"rec,omitempty"`       // on | paused | error | off | veto | incognito
	RecBytes int64  `json:"rec_bytes,omitempty"` // 主机上当前保留的记录字节数
	RecFirst int64  `json:"rec_first,omitempty"` // 最早保留内容的时间(Unix 秒)
	RecLast  int64  `json:"rec_last,omitempty"`  // 最近写入的时间(Unix 秒)
	RecGap   bool   `json:"rec_gap,omitempty"`   // 记录不完整(开头被清理或中途有缺口)

	// Screen 是屏幕扫描器(#113 M3.1)对 cursor-agent TUI 的识别结果;认不出任何东西时为空。
	// 只有 Agent 守护进程 / Hub 本地会话在「识别出变化」或定时刷新时才会更新它;旧版 Agent 没有这个字段。
	Screen *Screen `json:"screen,omitempty"`
}

SessionInfo 描述 Agent 上的一个终端会话。

func (SessionInfo) Sanitized

func (s SessionInfo) Sanitized() (SessionInfo, bool)

Sanitized 返回净化后的会话信息;SID 非法时 ok=false,调用方应丢弃该条目。

type Sessions

type Sessions struct {
	T        string        `json:"t"`
	Sessions []SessionInfo `json:"sessions"`
}

Sessions 是 Agent 上会话清单的全量更新。

type SetLifecycle

type SetLifecycle struct {
	T       string `json:"t"`
	SID     string `json:"sid"`
	IdleSec *int   `json:"idle_sec,omitempty"`
}

SetLifecycle 修改一个已有会话的生命周期:IdleSec 为 nil 表示改回沿用主机默认,0 表示永久保持。

type Uninstall

type Uninstall struct {
	T string `json:"t"`
	// Purge 同时删除身份文件与已信任服务器记录(等同 --purge);终端录像与命令输出始终保留在本机,由主机所有者自行处理。
	Purge bool `json:"purge,omitempty"`
}

Uninstall 请求 Agent 卸载自己的常驻服务,效果等同于管理员在主机上手动执行 `relaymesh-agent uninstall`。 只会在管理员(已登录且已解锁)删除主机并勾选「同时卸载设备端」时发送,并且先于随后的关闭帧。 Agent 在本机另起一个与自身进程树无关的卸载进程来完成(卸载会停止 Agent 自己,所以不能在自己的进程树里做)。

type Upgrade

type Upgrade struct {
	T string `json:"t"`
	// ID 是这次升级的标识,Agent 在 upgrade_status 里原样带回。
	ID string `json:"id"`
	// Version 是目标版本(Hub 自带的 Agent 版本)。
	Version string `json:"version"`
	// Ticket 是这台主机的升级窗口票据(/i/<票据>/<文件名>)。
	Ticket string `json:"ticket"`
	// SHA256 是目标平台的 Agent 二进制的 SHA-256(小写十六进制)。
	SHA256 string `json:"sha256"`
}

Upgrade 请求 Agent 自己下载新版本并升级。只会在管理员(已登录且已解锁)点了「一键升级」、 并且这台主机的 Agent 声明了 Meta.WebUpgrade == "on" 时发送。

帧里**没有 URL 也没有文件名**:Agent 用自己配置的服务端地址与自己的 GOOS/GOARCH 推出下载地址, 所以 Hub(或冒充 Hub 的人)无法借它让 Agent 去访问任意地址。

func (Upgrade) Validate

func (u Upgrade) Validate() error

Validate 检查字段格式。Agent 收到后必须先过它,不合规的一律拒绝。

type UpgradeNote

type UpgradeNote struct {
	Outcome string `json:"outcome"`
	From    string `json:"from,omitempty"`
	To      string `json:"to,omitempty"`
	// At 是结果产生的 Unix 秒(主机时钟)。
	At     int64  `json:"at,omitempty"`
	Detail string `json:"detail,omitempty"`
}

UpgradeNote 是 Agent 本地保存的「上一次升级的结果」,握手时随 Meta 带给 Hub。 升级进程把它写进数据目录;新 Agent 上线(升级成功)或旧 Agent 被还原后重新上线(回滚)都会把它报出来, 这样即使 Agent 在升级中途被重启,管理员也能在 Web 上看到结果与原因,而不必去翻主机的日志。

func (UpgradeNote) Sanitized

func (n UpgradeNote) Sanitized() *UpgradeNote

Sanitized 返回净化后的副本;结果类型不认识时返回 nil。

type UpgradeStatus

type UpgradeStatus struct {
	T      string `json:"t"`
	ID     string `json:"id"`
	Stage  string `json:"stage"`
	Code   string `json:"code,omitempty"`
	Detail string `json:"detail,omitempty"`
}

UpgradeStatus 是 Agent 对升级请求的进展报告。

func (UpgradeStatus) Sanitized

func (s UpgradeStatus) Sanitized() (UpgradeStatus, bool)

Sanitized 返回净化后的副本(全部字段来自对端);阶段不认识时返回 false。

type VersionRelation

type VersionRelation int

VersionRelation 描述当前版本相对目标版本的关系。

const (
	// VersionCurrent:一致,或当前版本更新(例如服务端回退过)——都不需要升级。
	VersionCurrent VersionRelation = iota
	// VersionOlder:能确定当前版本更旧。
	VersionOlder
	// VersionDiffers:与目标版本不同,但无法比较新旧(短哈希之类)。
	VersionDiffers
)

func RelateAgentVersion

func RelateAgentVersion(cur, latest string) VersionRelation

RelateAgentVersion 比较当前版本 cur 与目标版本 latest。任何一边为空都按「无需升级」处理。

type Welcome

type Welcome struct {
	T           string `json:"t"`
	Status      string `json:"status"`
	MachineCode string `json:"machine_code"`
	Policy      Policy `json:"policy"`
}

Welcome 是握手通过后的应答。

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL