Documentation
¶
Overview ¶
Package termstate 是终端会话「输出流状态」的共享实现:按累计偏移寻址的环形缓冲(Ring)与 DEC 私有模式跟踪器(ModeTracker)。
它们原本属于 Agent 侧的会话守护进程;Hub 为「直连的 SSH 主机」提供人工终端(Hub 本地会话,见 internal/terminal/localterm.go)时 需要完全相同的重连续传与备用屏恢复行为,所以抽成这个不依赖任何 PTY / 网络的小包,两条路径共用同一份实现与测试。
Index ¶
- Variables
- func StripANSI(b []byte) string
- func TUIVersionVerified(cursorVersion string) bool
- type ModeTracker
- type Ring
- func (r *Ring) AlignForReplay(from uint64) uint64
- func (r *Ring) Base() uint64
- func (r *Ring) End() uint64
- func (r *Ring) Read(off uint64, dst []byte) (int, error)
- func (r *Ring) ReplayStart(from uint64, tail int, minBytes uint64) (start uint64, trimmed bool)
- func (r *Ring) TailStart(lines int) uint64
- func (r *Ring) Write(p []byte)
- type Scanner
- type ScreenInfo
Constants ¶
This section is empty.
Variables ¶
var ErrOverwritten = errors.New("ring: offset overwritten")
ErrOverwritten 表示请求的偏移已经被环形缓冲覆盖。
Functions ¶
func StripANSI ¶
StripANSI 去掉 CSI / OSC / 其它两字节转义序列和控制字符(保留换行与制表),返回 UTF-8 文字。 输入开头可能是被截断的转义序列的残片,这里宽容处理:认不出的 ESC 直接丢掉它和后面一个字节。
func TUIVersionVerified ¶
TUIVersionVerified 判断一个 cursor 版本号是否在「已用实验验证过屏幕写法」的清单里。 未知版本返回 false:使用方应把该会话标为 tui:unrecognized 并降级为纯 hook,不产生任何告警(设计稿 04 §2.6)。
Types ¶
type ModeTracker ¶
type ModeTracker struct {
// contains filtered or unexported fields
}
ModeTracker 解析终端输出流,跟踪那些「重新连接后必须恢复」的 DEC 私有模式。
为什么需要它:浏览器重新附着一个正在运行 vim / tmux / htop 的会话时,新建的 xterm 并不知道 进程此前已经切到备用屏、开启了鼠标上报或括号粘贴。若只回放字节,画面与输入行为都会错乱。 Agent 在输出流上维护这些模式的当前值,附着时先发一段「模式恢复序列」再回放数据。
解析器是一个极小的状态机,只识别 CSI ? … h/l、ESC = / ESC >、RIS 与 DECSTR,并正确跳过 OSC / DCS 等字符串序列(窗口标题里的文字不会被误当成模式切换)。它能跨数据块边界工作。
func (*ModeTracker) Alt ¶
func (m *ModeTracker) Alt() (bool, uint64)
Alt 返回当前是否处于备用屏,以及进入备用屏那条序列结束之后的偏移。
func (*ModeTracker) Feed ¶
func (m *ModeTracker) Feed(start uint64, data []byte)
Feed 消费一段输出。start 是 data[0] 的累计偏移,用来记录「进入备用屏」的位置。
func (*ModeTracker) Prefix ¶
func (m *ModeTracker) Prefix(includeAlt bool) []byte
Prefix 生成「模式恢复序列」:把新终端带到与当前输出流一致的模式状态。 includeAlt 为 true 时先切换到备用屏(调用方随后应当从进入备用屏之后的偏移开始回放)。 只输出与默认值不同的模式,全部为默认时返回 nil。
type Ring ¶
type Ring struct {
// contains filtered or unexported fields
}
Ring 是按「累计字节偏移」寻址的环形缓冲:偏移为 o 的字节存放在 buf[o % size]。
偏移从 0 开始单调递增,永不回绕(uint64 足够),这让「断线重连从某偏移续传」「缺口显式标记」 都成为简单的整数比较。Ring 本身不是并发安全的,调用方(Session)用自己的锁保护它。
func (*Ring) AlignForReplay ¶
AlignForReplay 返回一个不小于 from 的回放起点,避免从转义序列或 UTF-8 字符中间开始。
只有在 from 恰好是环形缓冲的头(缓冲已经回绕过)时才需要对齐:此时头部字节很可能落在某个 序列的中间。优先对齐到下一个换行之后;扫描范围内没有换行就只跳过 UTF-8 续字节。
func (*Ring) Read ¶
Read 从偏移 off 读取至多 len(dst) 字节,返回实际读取的字节数。 off 早于 Base 时返回 ErrOverwritten;off 不小于 End 时返回 0。
func (*Ring) ReplayStart ¶
ReplayStart 给出全新附着在主屏上的回放起点:在 AlignForReplay 之上叠加「只回放末尾若干行」。
tail > 0、缓冲里的字节数不少于 minBytes、并且缓冲里的行数多于 tail 时,起点取末尾 tail 行的开头(trimmed = true); 这是有意跳过的内容(浏览器可以从记录里按需读到它),不算「被覆盖」。其余情况等同于 AlignForReplay(from)。 缓冲还很小的会话照旧整体回放:回放本来就快,也保住完整的终端状态。
type Scanner ¶
type Scanner struct {
// contains filtered or unexported fields
}
Scanner 累积输出并按需给出 ScreenInfo。非并发安全:调用方自己加锁(Feed 与 Info 通常在同一把会话锁下)。
type ScreenInfo ¶
type ScreenInfo struct {
// Recognized 为 true 说明至少认出了状态行、审批提示或页脚之一。
Recognized bool `json:"recognized"`
// Word 是状态行的动词(Thinking / Working / Globbing / Running ...),没有状态行时为空。
Word string `json:"word,omitempty"`
// Tokens 是状态行里的实时 token 数;-1 表示没读到(状态行不带计数,或写法没见过)。
Tokens int `json:"tokens"`
// CtxPct 是页脚里的上下文占用百分比(0~100,保留一位小数);-1 表示没读到。
CtxPct float64 `json:"ctx_pct"`
// Approval 为 true 表示屏幕正停在「Waiting for approval...」上。
Approval bool `json:"approval,omitempty"`
// Cancelled 为 true 表示最近一次画面是「Cancelled • 15s」(被人中断)。
Cancelled bool `json:"cancelled,omitempty"`
// Animating 为 true 表示最近 2 秒还有输出字节(旋转动画仍在动)。
Animating bool `json:"animating,omitempty"`
// BytesPerSec 是最近 scanRateBuckets 秒内的平均字节速率。
BytesPerSec float64 `json:"bytes_per_sec"`
// QuietFor 是距离最后一次输出过去了多久;从未有过输出为 -1。
QuietFor time.Duration `json:"quiet_for"`
}
ScreenInfo 是一次扫描的结果。零值表示「没有认出任何东西」。