termstate

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: 7 Imported by: 0

Documentation

Overview

Package termstate 是终端会话「输出流状态」的共享实现:按累计偏移寻址的环形缓冲(Ring)与 DEC 私有模式跟踪器(ModeTracker)。

它们原本属于 Agent 侧的会话守护进程;Hub 为「直连的 SSH 主机」提供人工终端(Hub 本地会话,见 internal/terminal/localterm.go)时 需要完全相同的重连续传与备用屏恢复行为,所以抽成这个不依赖任何 PTY / 网络的小包,两条路径共用同一份实现与测试。

Index

Constants

This section is empty.

Variables

View Source
var ErrOverwritten = errors.New("ring: offset overwritten")

ErrOverwritten 表示请求的偏移已经被环形缓冲覆盖。

Functions

func StripANSI

func StripANSI(b []byte) string

StripANSI 去掉 CSI / OSC / 其它两字节转义序列和控制字符(保留换行与制表),返回 UTF-8 文字。 输入开头可能是被截断的转义序列的残片,这里宽容处理:认不出的 ESC 直接丢掉它和后面一个字节。

func TUIVersionVerified

func TUIVersionVerified(cursorVersion string) bool

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 NewModeTracker

func NewModeTracker() *ModeTracker

NewModeTracker 创建处于初始状态的跟踪器。

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 NewRing

func NewRing(size int) *Ring

NewRing 创建容量为 size 字节的环形缓冲(size 至少为 1)。

func (*Ring) AlignForReplay

func (r *Ring) AlignForReplay(from uint64) uint64

AlignForReplay 返回一个不小于 from 的回放起点,避免从转义序列或 UTF-8 字符中间开始。

只有在 from 恰好是环形缓冲的头(缓冲已经回绕过)时才需要对齐:此时头部字节很可能落在某个 序列的中间。优先对齐到下一个换行之后;扫描范围内没有换行就只跳过 UTF-8 续字节。

func (*Ring) Base

func (r *Ring) Base() uint64

Base 返回仍保留在缓冲中的最旧字节的偏移。

func (*Ring) End

func (r *Ring) End() uint64

End 返回累计写入的字节数(下一个字节的偏移)。

func (*Ring) Read

func (r *Ring) Read(off uint64, dst []byte) (int, error)

Read 从偏移 off 读取至多 len(dst) 字节,返回实际读取的字节数。 off 早于 Base 时返回 ErrOverwritten;off 不小于 End 时返回 0。

func (*Ring) ReplayStart

func (r *Ring) ReplayStart(from uint64, tail int, minBytes uint64) (start uint64, trimmed bool)

ReplayStart 给出全新附着在主屏上的回放起点:在 AlignForReplay 之上叠加「只回放末尾若干行」。

tail > 0、缓冲里的字节数不少于 minBytes、并且缓冲里的行数多于 tail 时,起点取末尾 tail 行的开头(trimmed = true); 这是有意跳过的内容(浏览器可以从记录里按需读到它),不算「被覆盖」。其余情况等同于 AlignForReplay(from)。 缓冲还很小的会话照旧整体回放:回放本来就快,也保住完整的终端状态。

func (*Ring) TailStart

func (r *Ring) TailStart(lines int) uint64

TailStart 返回「缓冲末尾 lines 行」的起点偏移:从末尾往回数换行符,第 lines+1 个换行符之后就是 倒数第 lines 行(连同末尾还没结束的那一行,例如提示符)的开头。起点总落在行首,不会切在转义序列或 UTF-8 字符中间 (换行符是 C0 控制字符,不会出现在序列或多字节字符内部)。

缓冲里的换行不够多(整个缓冲不到 lines 行)时返回 Base,由调用方照常整体回放。

func (*Ring) Write

func (r *Ring) Write(p []byte)

Write 追加数据,必要时覆盖最旧的数据。

type Scanner

type Scanner struct {
	// contains filtered or unexported fields
}

Scanner 累积输出并按需给出 ScreenInfo。非并发安全:调用方自己加锁(Feed 与 Info 通常在同一把会话锁下)。

func NewScanner

func NewScanner() *Scanner

NewScanner 返回一个空的扫描器。

func (*Scanner) Feed

func (s *Scanner) Feed(now time.Time, p []byte)

Feed 登记一段输出。p 不会被保留(内部拷贝尾部)。

func (*Scanner) Info

func (s *Scanner) Info(now time.Time) ScreenInfo

Info 扫描当前尾部并返回结果。

func (*Scanner) Wire

func (s *Scanner) Wire(now time.Time) *termproto.Screen

Wire 把当前扫描结果换成线上格式;认不出任何东西(没有状态行 / 审批 / 页脚)时返回 nil。

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 是一次扫描的结果。零值表示「没有认出任何东西」。

Jump to

Keyboard shortcuts

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