Documentation
¶
Overview ¶
Package termproto 定义终端功能中「Hub(服务端)」与「Agent(主机端)」共用的线协议、机器码派生与字段净化。
它只依赖标准库,刻意不引用项目内任何其他包:协议是两端的契约,改动必须同时被两端的测试看见。 金标准向量(identity_test.go)固化了机器码与签名的派生方式,任何不兼容的改动都会让它们失败。
Index ¶
- Constants
- Variables
- func CanonGuiOps(s string) string
- func ClampIdle(sec int) int
- func ClampSize(rows, cols uint16) (uint16, uint16)
- func CompareAgentRev(a, b string) (same, known bool)
- func DecodeAck(frame []byte) (ch uint32, offset uint64, err error)
- func DecodeBrowserInput(frame []byte) (payload []byte, err error)
- func DecodeBrowserOutput(frame []byte) (offset uint64, payload []byte, err error)
- func DecodeInput(frame []byte) (ch uint32, payload []byte, err error)
- func DecodeKey(s string, want int) ([]byte, error)
- func DecodeOutput(frame []byte) (ch uint32, offset uint64, payload []byte, err error)
- func DecodeRunOut(frame []byte) (id string, stream byte, offset uint64, payload []byte, err error)
- func EncodeAck(ch uint32, offset uint64) []byte
- func EncodeBrowserInput(payload []byte) []byte
- func EncodeBrowserOutput(offset uint64, payload []byte) []byte
- func EncodeFileData(c FileChunk) []byte
- func EncodeInput(ch uint32, payload []byte) []byte
- func EncodeKey(b []byte) string
- func EncodeOutput(ch uint32, offset uint64, payload []byte) []byte
- func EncodeRecord(c RecordChunk) []byte
- func EncodeRunData(c RunChunk) []byte
- func EncodeRunOut(id string, stream byte, offset uint64, payload []byte) []byte
- func FrameType(frame []byte) (byte, error)
- func GuiRepoProblem(s string) string
- func GuiTextProblem(s string) string
- func MachineCode(pub ed25519.PublicKey) string
- func Marshal(v any) ([]byte, error)
- func NewNonce() ([]byte, error)
- func NormalizeMachineCode(input string) (string, error)
- func ParseStream(name string) (byte, bool)
- func ParseType(data []byte) (string, error)
- func RandomMachineCode() (string, error)
- func RootProblem(p string) string
- func SSHLabel(user, addr string) string
- func SanitizeAgentRev(s string) string
- func SanitizePlatform(s string) string
- func SanitizeSSHCode(code string) string
- func SanitizeText(s string, maxRunes int) string
- func SignChallenge(priv ed25519.PrivateKey, nonce []byte) []byte
- func StreamName(s byte) string
- func ValidAgentRev(s string) bool
- func ValidAgentVersion(s string) bool
- func ValidAutoUpgradeMode(s string) bool
- func ValidAutoWindow(s string) bool
- func ValidFileHandle(s string) bool
- func ValidFileOp(op string) bool
- func ValidGuiConv(s string) bool
- func ValidGuiErr(code string) bool
- func ValidGuiIdem(s string) bool
- func ValidGuiOp(op string) bool
- func ValidMachineCode(s string) bool
- func ValidRunID(s string) bool
- func ValidRunState(s string) bool
- func ValidSHA256Hex(s string) bool
- func ValidSessionID(s string) bool
- func ValidUpgradeID(id string) bool
- func VerifyChallenge(pub ed25519.PublicKey, nonce, sig []byte) bool
- type Approved
- type Attach
- type AttachFailed
- type Attached
- type AutoUpgradeCheck
- type AutoUpgradeGrant
- type AutoUpgradeOffer
- type AutoUpgradeRequest
- type BrowserAck
- type BrowserClosed
- type BrowserExit
- type BrowserLag
- type BrowserReady
- type BrowserResize
- type Bye
- type Challenge
- type Detach
- type Detached
- type Envelope
- type ExecInfo
- type Exit
- type FileChunk
- type FileReq
- type FileRes
- type FileStat
- type GuiCheck
- type GuiProbe
- type GuiProbeComposer
- type GuiProbeRepo
- type GuiProbeRow
- type GuiReq
- type GuiRes
- type Hello
- type Holder
- type Kill
- type LostSession
- type Meta
- type Open
- type OpenFailed
- type Opened
- type Policy
- type PolicyMsg
- type RecordChunk
- type RecordFail
- type RecordInfo
- type RecordRead
- type RecordStat
- type Rejected
- type Rename
- type Resize
- type Run
- type RunAck
- type RunBrief
- type RunCancel
- type RunChunk
- type RunEnd
- type RunFailed
- type RunRead
- type RunReadFail
- type RunStarted
- type Runs
- type RunsSync
- type SSHOp
- type SSHResult
- type SSHTarget
- type Screen
- type SessionInfo
- type Sessions
- type SetLifecycle
- type Uninstall
- type Upgrade
- type UpgradeNote
- type UpgradeStatus
- type VersionRelation
- type Welcome
Constants ¶
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 带下载凭据与发布签名 )
文本控制帧类型。
const ( AutoUpgradeOff = "off" // 支持,但主机所有者没有开启 AutoUpgradeNotify = "notify" // 只提示:发现新版本只记录与显示,不下载、不安装 AutoUpgradeSilent = "silent" // 静默:发现新版本后自己下载、验签、升级(要求发布产物带独立签名) )
Meta.AutoUpgrade 的取值。空串表示这个 Agent 不提供自动升级(旧版本、前台运行、临时身份、暂不支持的系统)。
const ( AutoOfferDisabled = "disabled" // Hub 的总闸是关的:不提供任何自动升级 AutoOfferNotAllowed = "not_allowed" // 这台主机没有声明开启(模式 off / 没有声明) AutoOfferUpToDate = "up_to_date" // 没有比当前更新的版本 AutoOfferAvailable = "available" // 有更新的版本,Version 是它 AutoOfferTooSoon = "too_soon" // 检查得太频繁,这次不回答实质内容 )
AutoUpgradeOffer.Status 的取值。
const ( AutoGrantGranted = "granted" // 批准:帧里有下载凭据、SHA-256 与发布签名 AutoGrantDisabled = "disabled" // Hub 的总闸是关的 AutoGrantNotAllowed = "not_allowed" // 这台主机没有声明静默模式(或是临时身份) AutoGrantUpToDate = "up_to_date" // 没有比当前更新的版本(或无法证明更新) AutoGrantStale = "stale" // Hub 上最新的版本已经不是请求的那个:请重新检查 AutoGrantUnsigned = "unsigned" // 这个发布版本没有发布签名:静默模式不会升级到它 AutoGrantBusy = "busy" // 已经有一次升级在进行,或这台主机上有会损失的运行中会话:稍后再来 AutoGrantTooSoon = "too_soon" // 请求得太频繁 )
AutoUpgradeGrant.Status 的取值。
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 )
协议标识与版本。
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 为应用自定义范围)。
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 )
预认证与握手限额。
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 )
已认证阶段的帧与会话限额。
const ( MinIdleSec = 60 MaxIdleSec = 400 * 24 * 3600 )
空闲回收(生命周期)的取值范围,单位秒。0 表示永久保持;其余取值必须落在 [MinIdleSec, MaxIdleSec] 内。
const ( PingInterval = 15 * time.Second PongTimeout = 45 * time.Second )
心跳:WS ping 间隔与「无 pong 判定断链」的期限(两端对称)。
const ( MaxHostnameRunes = 64 MaxOSRunes = 64 MaxArchRunes = 32 MaxVersionRunes = 32 )
自报字段长度上限(rune 数)。
const ( HostStatusEnabled = "enabled" HostStatusDisabled = "disabled" HostStatusBlocked = "blocked" )
主机状态(持久化在 terminal_hosts.status)。
const ( PrivRoot = "root" PrivAdmin = "admin" PrivUser = "user" )
Agent 特权等级(hello.meta.priv,自报,仅用于界面徽标与提示)。
const ( KindPersistent = "persistent" KindTemporary = "temporary" )
Agent 形态(hello.meta.kind,自报):temporary 表示仅内存的临时身份,服务端不持久化其启用状态。
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 直接下载。
const ( FileOpStat = "stat" // 取元数据(不存在不算错误) FileOpHash = "hash" // 计算 sha256 FileOpOpen = "open" // 打开一个文件准备分块读取(拉取用),返回句柄 FileOpRead = "read" // 读取句柄的一个区间 FileOpClose = "close" // 释放句柄 FileOpPushURL = "push_url" // 由 Agent 下载网址内容并原子写入目标路径 )
文件请求的操作。
const ( FileFlagEOF byte = 1 << 0 // 已读到文件末尾 FileFlagLast byte = 1 << 1 // 本次 read 请求的最后一帧 )
FrameFileData 的标志位。
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)。
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 处理的大小上限 )
文件相关的尺寸限制。
const ( FileTypeFile = "file" FileTypeDir = "dir" FileTypeSymlink = "symlink" FileTypeOther = "other" )
文件类型取值(FileStat.Type)。
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" 字段。
const ( WelcomeEnabled = "enabled" WelcomePending = "pending" )
主机状态在 welcome.status 中的取值。
const ( SessionRunning = "running" SessionExited = "exited" )
会话状态。
const ( BrowserOutput byte = 0x01 // [0x01][偏移 u64][输出](Hub→浏览器) BrowserInput byte = 0x02 // [0x02][输入](浏览器→Hub) )
浏览器 WS 二进制帧类型:[类型 1B][…]。
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][…]。
const ( HolderReady = "ready" // 守护进程可用,Agent 已与它建立控制连接 )
会话守护进程(holder)的状态,取自 holder 帧的 state 字段。
const ( HolderReasonConnecting = "connecting" // 正在连接 HolderReasonSuperseded = "superseded" // 另一个 Agent 实例取代了本实例的控制连接 HolderReasonVersion = "version" // 本地协议主版本不一致 HolderReasonUnreachable = "unreachable" // 连不上(守护进程没启动、被停止或崩溃) )
守护进程不可用的原因码(holder.reason)。
const ( LostHostReboot = "host_reboot" LostHolderExit = "holder_exit" LostHolderStopped = "holder_stopped" LostUnknown = "unknown" )
会话丢失原因(LostSession.Reason)。
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)成功。
const ( GuiOpProbe = "probe" // 只读:端点可达性、页面候选、选择器自检、侧栏会话行与输入框摘要 GuiOpResume = "resume" // 旧会话:选中它、输入唤醒词、发送 GuiOpNew = "new" // 新会话:在指定仓库分组里点 New Agent、输入唤醒词、发送 )
GUI 动作。
const ( GuiWakeOff = "off" // 支持,但主机所有者没有在本机开启 GuiWakeOn = "on" // 支持,且主机所有者已在本机开启 )
Meta.GuiWake 的取值。空串表示这个 Agent 不支持(旧版本、非 Windows 构建之外的暂不支持情形)。
const ( GuiOutcomeSent = "sent" GuiOutcomeNotSent = "not_sent" GuiOutcomeUnknown = "unknown" GuiOutcomeRead = "read" )
GuiRes.Outcome 的取值(语义见文件头)。
const ( GuiStateRunning = "running" GuiStateStopped = "stopped" GuiStateUnknown = "unknown" )
GuiRes.State 的取值:目标会话此刻在窗口里的状态。unknown 不等于已停止——读不到就是读不到。
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)。
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 动作的尺寸限制。
const ( // NonceSize 是服务端挑战随机数的字节数。 NonceSize = 32 // MachineCodePrefix 是机器码前缀。 MachineCodePrefix = "RM-" )
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)。
const ( RecFlagEOF byte = 1 << 0 // 已读到记录末尾(会话仍在运行时之后可能还有新内容) RecFlagSkipped byte = 1 << 1 // 请求的起点已被清理,数据从最早保留的分段开头开始 RecFlagLast byte = 1 << 2 // 本次请求的最后一帧 )
记录帧标志位。
const ( MaxRecordFrameData = 48 << 10 // 单帧事件字节上限(须小于 MaxControlFrame) MaxRecordRead = 1 << 20 // 单次请求返回的字节上限 DefaultRecordRead = 256 << 10 MaxRecordInfoJSON = 56 << 10 )
记录读取的尺寸上限。
const ( RecOn = "on" // 正在录制 RecPaused = "paused" // 暂停(磁盘不足或服务端策略临时关闭) RecError = "error" // 写盘失败,重试中 RecOff = "off" // 服务端策略关闭了录制 RecVeto = "veto" // 本机一票否决(--no-record) RecIncognito = "incognito" // 无痕会话 )
录制状态(SessionInfo.Rec)。
const ( RecReasonNotFound = "not_found" // 没有该会话的记录(无痕、已过期或已被清理) RecReasonBusy = "busy" // Agent 正忙于其他读取 RecReasonBad = "bad_request" RecReasonError = "error" )
记录请求失败原因(RecordFail.Reason)。
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 重连后补报。
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 的编号)。
const ( StreamStdout byte = 1 StreamStderr byte = 2 )
输出流编号。
const ( RunExited = "exited" // 进程自行结束(含非 0 退出码) RunSignaled = "signaled" // 被信号终止(不是本机取消或超时造成的) RunTimeout = "timeout" // 超过 timeout_sec,被终止 RunCancelled = "cancelled" // 收到取消请求,被终止 RunLost = "lost" // 守护进程重启后发现进程已不存在,结果未知 )
运行的结束状态(RunEnd.State,守护进程上报)。
const ( RunFailDenied = "denied_by_host" // 本机一票否决(--deny-model-exec) RunFailBusy = "busy" // 本机同时运行数达到保护上限 RunFailBad = "bad_request" // 参数无效 RunFailCwd = "bad_cwd" // 工作目录不存在或不是目录 RunFailNoShell = "no_shell" // 找不到可用的 shell RunFailSpawn = "spawn_failed" // 进程启动失败 RunFailDuplicate = "duplicate" // 同一运行 ID 已存在 RunFailHolder = "holder_unavailable" RunFailDraining = "shutting_down" )
运行没能启动的原因(RunFailed.Reason)。
const ( RunReadNotFound = "not_found" RunReadBusy = "busy" RunReadBad = "bad_request" RunReadError = "error" RunReadHolder = "holder_unavailable" )
运行输出读取失败的原因(RunReadFail.Reason)。
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 )
运行相关的尺寸限制。
const ( RunFlagEOF byte = 1 << 0 // 已读到这一路输出的末尾,且运行已经结束 RunFlagGap byte = 1 << 1 // 请求的起点落在被丢弃的中间部分,已从下一段可用内容开始 RunFlagLast byte = 1 << 2 // 本次请求的最后一帧 RunFlagRunning byte = 1 << 3 // 运行仍在进行(之后可能还有新的输出) )
应答帧标志位(FrameRunData)。
const ( TSSHOp = "ssh_op" // Hub → 网关:一次性的 SSH 操作(探测 / 检查 / 代为执行 / 凭据维护) TSSHResult = "ssh_result" // 网关 → Hub:ssh_op 的结果 )
帧类型。
const ( SSHOpProbe = "probe" // 只做密钥交换取回主机公钥,不发送任何认证信息 SSHOpCheck = "check" // 用固定的主机公钥与凭据真实登录一次,并读取远端环境信息;persist 时成功后保存凭据 SSHOpExec = "exec" // 在目标上运行一段脚本并回传输出(Hub 的 SSH 执行层经网关使用,目标须 stored) SSHOpCredDel = "cred_del" // 删除网关上保存的某台 SSH 主机的凭据 SSHOpCredSync = "cred_sync" // 只保留名单内的凭据(回收其余),并回报仍持有哪些 )
ssh_op 的操作类型。
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)。
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)。
const ( TUpgrade = "upgrade" // Hub → Agent:请 Agent 自己下载新版本并升级(仅在 Meta.WebUpgrade == "on" 时发送) TUpgradeStatus = "upgrade_status" // Agent → Hub:升级进展 / 拒绝 / 失败 )
文本控制帧类型。
const ( WebUpgradeOff = "off" // 支持,但主机所有者没有允许 WebUpgradeOn = "on" // 支持,且主机所有者已允许 )
Meta.WebUpgrade 的取值。空串表示这个 Agent 不支持(旧版本、前台运行、临时身份、暂不支持的系统)。
const ( UpgradeStageDownloading = "downloading" // 已接受请求,正在下载并校验 UpgradeStageHandoff = "handoff" // 已校验通过,交给与 Agent 进程树无关的升级进程;Agent 随后会被重启 UpgradeStageRefused = "refused" // 没有开始(本地开关、版本关系、正在进行等) UpgradeStageFailed = "failed" // 开始了但没有完成(下载、校验、交接失败);已安装的程序没有被改动 )
UpgradeStatus.Stage 的取值。
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 时给出)。
const ( UpgradeOutcomeOK = "ok" // 升级完成,新版本已连上服务端 UpgradeOutcomeRolledBack = "rolled_back" // 新版本没有连上服务端,已还原为旧版本 UpgradeOutcomeFailed = "failed" // 升级进程没能完成(例如替换或重启失败) )
UpgradeNote.Outcome 的取值。
const ( // MaxUpgradeDetailRunes 限制自报的升级说明长度。 MaxUpgradeDetailRunes = 240 // MaxUpgradeVersionRunes 与分发目录 VERSION 文件允许的版本号长度一致。 MaxUpgradeVersionRunes = 64 )
const FileRootAll = "*"
FileRootAll 是 FileReq.Roots 里的哨兵条目:令牌被明确授予「整个文件系统」(model.TerminalLimits.AllowWholeFS)。 Agent 见到它就不再把路径限制在某个目录里(路径仍须是规范的绝对路径;Windows 上是任一盘符)。 它不是合法的目录写法(RootProblem 拒绝),所以没有任何人工输入的允许目录能构造出它——只有 Hub 在令牌打开了开关时才会放进去。 旧版 Agent 不认识它,会把它当作无法解析的条目丢弃,于是一切路径都被拒绝(失败时更保守,而不是更宽松)。
const FrameFileData byte = 0x07
FrameFileData 是 read 请求的应答:[0x07][req u32][标志 u8][起点 u64][文件总大小 u64][净荷](Agent→Hub)。
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 | 净荷)。
const HolderCapRecLines = "rec_lines"
HolderCapRecLines 声明记录引擎支持「按行数限高」(Policy.RecMaxLines / --record-session-lines)。 升级只替换 Agent、不会重启会话守护进程,而记录引擎在守护进程里,所以 Hub 靠这个能力位判断一台主机上的设置是否已经生效。
const HolderCapSSH = "ssh"
HolderCapSSH 是会话守护进程在 holder 帧 caps 里声明的能力:本机开启了 SSH 网关。
const HolderCapSSHStore = "ssh_store"
HolderCapSSHStore 声明网关的凭据库可用,并支持 stored 目标与 exec / cred_del / cred_sync: 缺少它的网关(旧版本,或凭据库打不开)Hub 一律视为未就绪,不会向它发送任何 SSH 目标。
const MaxLostSessions = 64
MaxLostSessions 是一次 holder 帧里接受的「已丢失会话」条数上限。
const MaxRunsPerFrame = 256
MaxRunsPerFrame 是一个 runs 帧最多接受的条数。
const MaxSignatureTextLen = 128
MaxSignatureTextLen 是帧里发布签名文本的长度上限(与 relsign.MaxSignatureLen 相同;termproto 不依赖 relsign, 所以只在这里限字符集与长度,真正的验证在 Agent 里)。
Variables ¶
var ( ErrShortFrame = errors.New("frame too short") ErrWrongFrame = errors.New("unexpected frame type") ErrPayloadTooBig = errors.New("frame payload too large") )
二进制帧解码错误。
var ErrBadMachineCode = errors.New("invalid machine code")
ErrBadMachineCode 表示字符串不是合法的机器码。
var ErrUnsupportedVersion = errors.New("unsupported protocol version")
ErrUnsupportedVersion 表示协议版本不兼容。
var GuiOps = []string{GuiOpProbe, GuiOpResume, GuiOpNew}
GuiOps 是全部动作,按规范顺序排列(Meta.GuiWakeOps 与同意文件的 allow 都按这个顺序写)。
Functions ¶
func CanonGuiOps ¶ added in v2.2.0
CanonGuiOps 把逗号分隔的动作清单规整为规范形式:只留已知动作、去重、按 GuiOps 的顺序;没有任何已知动作返回空串。
func ClampIdle ¶
ClampIdle 把空闲回收秒数规整到合法范围:不大于 0 的一律视为永久保持(0),过小抬到 MinIdleSec,过大压到 MaxIdleSec。 守护进程用它兜住任何来源(策略、Open、SetLifecycle)的取值,避免一个异常数字让会话被立刻回收。
func CompareAgentRev ¶
CompareAgentRev 比较两个指纹。known 为 false 表示至少一边没有声明或不合法,调用方必须回退到版本号比较; known 为 true 时 same 说明两边的 Agent 代码是否一致。
func DecodeBrowserInput ¶
DecodeBrowserInput 解码浏览器→Hub 的输入帧,净荷不得超过 MaxInputFrame。
func DecodeBrowserOutput ¶
DecodeBrowserOutput 解码浏览器侧输出帧(供测试与 Go 客户端使用)。
func DecodeInput ¶
DecodeInput 解码输入帧。
func DecodeOutput ¶
DecodeOutput 解码输出帧;返回的 payload 与 frame 共享底层数组。
func DecodeRunOut ¶
DecodeRunOut 解码实时输出片段;返回的 payload 与 frame 共享底层数组。
func EncodeBrowserInput ¶
EncodeBrowserInput 编码浏览器→Hub 的输入帧(供测试与 Go 客户端使用)。
func EncodeBrowserOutput ¶
EncodeBrowserOutput 编码 Hub→浏览器的输出帧。
func EncodeInput ¶
EncodeInput 编码 Hub→Agent 的输入帧。
func EncodeOutput ¶
EncodeOutput 编码 Agent→Hub 的输出帧。
func EncodeRunOut ¶
EncodeRunOut 编码实时输出片段;id 必须是合法的运行 ID(否则返回 nil)。
func GuiRepoProblem ¶ added in v2.2.0
GuiRepoProblem 检查仓库标识(Cursor 侧栏分组的 data-agent-drop-section-id,形如 repo:github.com/owner/name)的写法;空串表示合法。 只看字符串:必须以 repo: 开头且后面有内容,不超过 MaxGuiRepoBytes,没有空白、控制字符与格式字符。
func GuiTextProblem ¶ added in v2.2.0
GuiTextProblem 检查要输入的唤醒词;空串表示合法:非空白、不超过 MaxGuiText 个字符、合法 UTF-8, 没有控制字符(含换行、制表)、格式字符(双向控制符、零宽字符)与行 / 段分隔符。唤醒词由 Hub 渲染现有模板(可信来源), 这里是第二道关:Agent 不信任任何来自网络的文字。
func MachineCode ¶
MachineCode 由 Ed25519 公钥派生机器码: "RM-" + SHA-256("relaymesh-machine-code-v1\0" ‖ 公钥) 前 80 位的 Crockford Base32,4-4-4-4 分组。
机器码是公钥指纹而非随机数或系统 machine-id:码本身可以公开出现在界面与日志里, 而冒用它需要对应私钥,因此「看到机器码」不等于「能冒充该主机」。
func NormalizeMachineCode ¶
NormalizeMachineCode 把用户输入规整为规范形式并校验: 大小写不敏感,忽略空白与连字符,按 Crockford 规则把易混字符映射(O→0,I/L→1),前缀 RM 可省略。
func RandomMachineCode ¶
RandomMachineCode 生成一个随机的机器码(同样的 RM- 格式,因而令牌白名单、校验与界面都能直接复用)。 它用于没有 Agent、也就没有密钥对可以派生机器码的主机(SSH 主机);唯一性由调用方在落库时保证。
func RootProblem ¶
RootProblem 检查令牌「允许目录」条目的写法,返回问题描述;空串表示合法。只看字符串,不访问文件系统。
合法写法:`~` 或 `~/…`(Agent 所在账户的家目录)、`/…` 绝对路径、`C:\…` 或 `C:/…` 盘符路径。 文件系统根(`/`、`C:\`)、UNC / 设备路径、相对路径、`~用户名`、含 `..` 片段、含控制字符的写法一律不接受: 把根目录当作允许目录等于不设防,`..` 则会让条目的真实含义与写法对不上。
func SanitizeAgentRev ¶
SanitizeAgentRev 返回合法的指纹,否则返回空串。空串表示对端没有声明(旧版本 / 非发布构建),调用方回退到版本号比较。
func SanitizePlatform ¶
SanitizePlatform 校验 Agent 自报的平台标识(GOOS-GOARCH,如 linux-amd64):写法不合规一律当作没有声明。 它只用来在分发目录里找对应的二进制,所以只接受小写字母与数字组成的两段,绝不放行路径或空白。
func SanitizeSSHCode ¶
SanitizeSSHCode 把来自对端的错误码规整成已知的稳定取值。
func SanitizeText ¶
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 ValidAgentRev ¶
ValidAgentRev 判断 s 是否是合法的 Agent 侧代码指纹(计算方式见 internal/agentrev)。
版本号跟着整个仓库的构建走,服务端每热更一次就变一次;指纹只在 Agent 二进制依赖的代码真的变了时才变。 所以「要不要升级」「守护进程是否落后」先比指纹:指纹一致,两边跑的就是同一份 Agent 代码,版本号不同只是构建号不同。
func ValidAgentVersion ¶
ValidAgentVersion 判断 s 是否是可以出现在升级请求里的版本号(与分发目录 VERSION 文件的规则一致)。
func ValidAutoUpgradeMode ¶
ValidAutoUpgradeMode 判断 s 是否是「主机所有者可以选的开启模式」(不含 off:关闭是删除同意,不是一种模式)。
func ValidAutoWindow ¶
ValidAutoWindow 判断 s 是否是合规的时间段写法(不含空串)。起止相同的写法(如 03:00-03:00)含义含糊,不合规。
func ValidGuiConv ¶ added in v2.2.0
ValidGuiConv 判断是否为小写 UUID(Cursor 的对话编号写法)。
func ValidGuiIdem ¶ added in v2.2.0
ValidGuiIdem 判断幂等键是否为 16–64 位 [A-Za-z0-9_-]。
func ValidMachineCode ¶
ValidMachineCode 判断 s 是否已经是规范形式的机器码(不做任何宽松规整)。
func ValidUpgradeID ¶
ValidUpgradeID 判断 id 是否是合规的升级标识(Hub 生成时按它自检)。
Types ¶
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 ¶
AutoUpgradeCheck 是 Agent 的一次检查。帧里只有标识:版本与平台以握手时声明的为准(Hub 本来就有), 这样 Agent 无法借检查帧让 Hub 去查任意版本或任意平台。
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 把这次请求登记为一次升级)。
type BrowserAck ¶
BrowserAck 是浏览器确认已渲染到某偏移(驱动流控窗口)。
type BrowserClosed ¶
BrowserClosed 在服务端主动断开附着前给出原因。
type BrowserExit ¶
type BrowserExit struct {
T string `json:"t"`
Code *int `json:"code,omitempty"`
Signal string `json:"signal,omitempty"`
}
BrowserExit 通知浏览器会话已结束。
type BrowserLag ¶
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 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 ¶
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 上完成。
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 有意义。
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 上完成。
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
SafeToFallback 报告这次结果是否允许 Hub 回退到 CLI 唤醒:只有「点发送之前就失败」才可以。 点过发送的 sent / unknown、只读的 read,以及同键正在处理中的 duplicate(Outcome 为 unknown)都不回退。 只对 Sanitized 之后的值有意义。
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) 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 进程结束,界面据此标注「重启会中断」。
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。
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 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 ¶
RecordStat 请求读取会话记录的索引信息。
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 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 ¶
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 报告运行结束。
type RunFailed ¶
type RunFailed struct {
T string `json:"t"`
ID string `json:"id"`
Reason string `json:"reason"`
Detail string `json:"detail,omitempty"`
}
RunFailed 报告运行没能启动。
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 ¶
Runs 是控制端接上守护进程时收到的运行清单:仍在运行的运行。 尚未被确认的结束事件会紧接着以独立的 run_end 帧补报(每个事件可能带有较大的内联输出,不适合塞进同一帧)。
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 操作。
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。
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 → 网关方向),且永远不应被打印。
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 去访问任意地址。
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。任何一边为空都按「无需升级」处理。