guiwake

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

Documentation

Overview

Package guiwake 是 Agent 里的「GUI 唤醒」执行器:通过 Cursor 客户端的本机调试端口(CDP), 在它的「Agents」窗口里新建会话,或在旧会话的输入框里输入文字并发送。

安全边界(设计稿 §4,D-445):

  • 只连同意文件里写明的 127.0.0.1:<端口>;同意文件在本机、由主机所有者写,Hub 改不了;
  • Hub 只能发「动作 + 目标 + 文字」,页面里执行的脚本全是本包的常量;
  • 每次动作前后都有明确的判据:发之前 not_sent 才能回退到 CLI 唤醒,点了发送之后只有 sent / unknown;
  • 同一个幂等键最多动手一次;每次请求都写本机审计日志(只记长度与指纹)。

Index

Constants

View Source
const (
	DefaultPageTitle      = "Cursor Agents"
	DefaultPageURLPattern = `(?i)^vscode-file://vscode-app/.*/cursor/resources/app/`
)

DefaultPageTitle 与 DefaultPageURLPattern 是「Cursor Agents」窗口的识别规则:标题恰好等于它,且地址是 Cursor 安装目录里的 workbench 页面。

View Source
const ConsentFileName = "gui-wake.json"

ConsentFileName 是主机所有者的同意文件,放在 Agent 的数据目录里。它是 GUI 唤醒唯一的开关与唯一的配置入口: Hub、网页、任何远程调用方都不能写它——只有在这台主机上能写。每次请求都重读(改了立刻生效,删了立刻失效)。

View Source
const SelectorsVersion = "cursor-agents/3.27-2026-10-30"

SelectorsVersion 是内置选择器表的版本标识:Cursor 改版、我们调整默认值时递增,probe 会把它带回 Hub,便于对照。

Variables

View Source
var (
	// ErrConsentMissing:文件不存在 —— GUI 唤醒没有开启。
	ErrConsentMissing = errors.New("gui-wake.json 不存在:这台主机没有开启 GUI 唤醒")
	// ErrConsentDisabled:文件里 enabled=false。
	ErrConsentDisabled = errors.New("gui-wake.json 里 enabled=false:GUI 唤醒已关闭")
)

同意文件读取的几类结果。

Functions

func AuditPath

func AuditPath(dataDir string) string

AuditPath 是审计日志的路径(供命令行告诉所有者去哪里看)。

func ConsentPath

func ConsentPath(dataDir string) string

ConsentPath 是同意文件的路径。

func ParseEndpoint

func ParseEndpoint(s string) (int, error)

ParseEndpoint 校验端点写法并返回端口。

func RecentAudit

func RecentAudit(dataDir string, n int) []string

RecentAudit 返回审计日志(gui-wake.log)的最后 n 行,供 `gui-wake status` 展示给主机所有者。 文件不存在、不是普通文件或读不了都返回空:这只是一个看日志的便利,不影响任何动作。 只读文件末尾至多 recentAuditTail 字节;每一行去掉控制字符并截断(日志是我们自己写的,但展示前不信任它)。

func RemoveConsent

func RemoveConsent(dataDir string) error

RemoveConsent 删除同意文件(关闭 GUI 唤醒)。文件本来就不存在不算错。

func Status

func Status(dataDir string) (mode, ops string)

Status 返回 hello 里要自报的内容:同意文件有效且启用时是 on + 允许的动作;否则 off。

func WriteConsent

func WriteConsent(dataDir string, c Consent) error

WriteConsent 原子地写入同意文件(供 `relaymesh-agent gui-wake enable` 使用)。先校验再写,写不进无效内容。

Types

type Consent struct {
	Enabled bool `json:"enabled"`
	// Endpoint 必须是 http://127.0.0.1:<端口>(不接受 localhost、IPv6、主机名、https、路径)。
	Endpoint string `json:"endpoint"`
	// Allow 是允许的动作;缺省只允许 probe(只读)。要让 Hub 能真的唤醒,所有者必须显式写上 resume / new。
	Allow []string `json:"allow,omitempty"`
	// Selectors 逐项覆盖选择器与界面文案(键见 Selectors 的 JSON 字段名)。
	Selectors map[string]string `json:"selectors,omitempty"`
	Page      *PageSpec         `json:"page,omitempty"`
	// RestoreAfterResume:续聊发送完后,把用户原来选中的会话选回来(默认 true)。
	RestoreAfterResume *bool `json:"restore_after_resume,omitempty"`
	// RestoreAfterNew:新建发送完后,把用户原来选中的会话选回来(默认 false:新会话留在眼前更符合预期)。
	RestoreAfterNew *bool `json:"restore_after_new,omitempty"`
}

Consent 是同意文件的内容。**严格解析**:未知字段、尾随内容、超大文件、符号链接一律视为无效(GUI 唤醒关闭), 这样一个写错的键不会悄悄变成更宽松的授权。

func ReadConsent

func ReadConsent(dataDir string) (Consent, error)

ReadConsent 读取同意文件的原始内容:严格解析(未知字段、尾随内容、超大文件、符号链接都是无效), 但不要求 enabled、也不展开校验。供命令行在重新开启时保留已有的选择器覆盖,以及 `status` 如实展示。 错误与 LoadConsent 一致:ErrConsentMissing(文件不存在)或 *ConsentError(存在但无效)。

func (Consent) Resolve

func (c Consent) Resolve() (*Resolved, error)

Resolve 校验并展开配置。

type ConsentError

type ConsentError struct {
	Code string
	Msg  string
}

ConsentError 表示同意文件存在但无效;Code 是要回给 Hub 的稳定错误码。

func (*ConsentError) Error

func (e *ConsentError) Error() string

type Executor

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

Executor 执行 GUI 唤醒请求。同一时刻只做一件事(第二个请求得到 busy_host)。

func New

func New(o Options) *Executor

New 构造执行器。

func (*Executor) Do

func (e *Executor) Do(ctx context.Context, req termproto.GuiReq) (res termproto.GuiRes)

Do 处理一个请求。它不会 panic、不会返回未净化的结果;每次调用都写一行审计日志。

type Options

type Options struct {
	DataDir string // Agent 数据目录:同意文件、幂等表、审计日志都放这里
	Timing  Timing
	Now     func() time.Time
}

Options 是构造执行器的参数。

type PageSpec

type PageSpec struct {
	Title      string `json:"title,omitempty"`
	URLPattern string `json:"url_regexp,omitempty"`
}

PageSpec 覆盖窗口识别规则(主机所有者的本机配置;测试里用它指向本机的假页面)。

type Resolved

type Resolved struct {
	Port      int
	Endpoint  string
	Allow     map[string]bool
	Selectors Selectors
	Title     string
	URLRegexp *regexp.Regexp

	RestoreAfterResume bool
	RestoreAfterNew    bool
}

Resolved 是校验过、可直接使用的配置。

func LoadConsent

func LoadConsent(dataDir string) (*Resolved, error)

LoadConsent 读取并校验同意文件。返回值要么是可用的配置,要么是下面几类错误之一: ErrConsentMissing / ErrConsentDisabled(正常的「没开」),*ConsentError(文件存在但无效)。

func (*Resolved) AllowList

func (r *Resolved) AllowList() string

AllowList 返回规范顺序的允许动作(逗号分隔),用于 hello 自报。

func (*Resolved) Allows

func (r *Resolved) Allows(op string) bool

Allows 报告同意文件是否允许这个动作。

type Selectors

type Selectors struct {
	Version string `json:"version"`

	Sidebar    string `json:"sidebar"`    // 侧栏容器:必须恰好 1 个
	Row        string `json:"row"`        // 侧栏里的一个会话行
	RowIDAttr  string `json:"rowIdAttr"`  // 会话行上的对话编号属性
	RepoGroup  string `json:"repoGroup"`  // 仓库分组容器
	RepoAttr   string `json:"repoAttr"`   // 仓库分组上的仓库标识属性
	RowTrigger string `json:"rowTrigger"` // 行里可点击的触发元素(选中状态也读它)

	SelectedAttr  string `json:"selectedAttr"`  // 选中时触发元素上的属性名
	SelectedValue string `json:"selectedValue"` // 选中时的属性值
	RowState      string `json:"rowState"`      // 行里的状态图标(读它的 aria-label)
	StateRunning  string `json:"stateRunning"`  // 运行中的状态文案
	StateDone     string `json:"stateDone"`     // 已完成的状态文案

	Shell       string `json:"shell"`       // 会话面板
	ShellIDAttr string `json:"shellIdAttr"` // 会话面板上的对话编号属性
	Editor      string `json:"editor"`      // 提示词输入框(contenteditable)
	// EditorIDAttr 是输入框上的对话编号属性;新建会话的输入框上它可能为空或不存在。
	EditorIDAttr string `json:"editorIdAttr"`
	Composer     string `json:"composer"`     // 输入区容器(找不到时向上找含提交按钮的祖先)
	Submit       string `json:"submit"`       // 提交按钮
	SubmitSend   string `json:"submitSend"`   // 提交按钮 aria-label:有文字、可发送
	SubmitStop   string `json:"submitStop"`   // 提交按钮 aria-label:运行中、停止
	SubmitActive string `json:"submitActive"` // 提交按钮 data-state:可用

	NewAgent string `json:"newAgent"` // 仓库分组里的 New Agent 按钮
	Bubble   string `json:"bubble"`   // 会话面板里的一条消息
	Blockers string `json:"blockers"` // 阻断元素(对话框 / 确认 / 错误提示);只数「可见」的
}

Selectors 是「Cursor Agents」窗口里各个元素的选择器与界面文案。

默认值来自 2026-10-30 对 Cursor 3.27.x(Chrome 148)窗口的只读观察与用户的 cursor-ui-cdp skill;这些属性不是公开稳定的接口, Cursor 升级后可能变,所以整张表可以被主机所有者在本机的同意文件里逐项覆盖(见 Consent.Selectors),而不是写死在代码里。 它整体以 JSON 字面量传进页面里的固定函数——页面里执行的脚本是源码里的常量,选择器只是数据。

func DefaultSelectors

func DefaultSelectors() Selectors

DefaultSelectors 返回内置默认。

func (Selectors) WithOverrides

func (s Selectors) WithOverrides(o map[string]string) (Selectors, error)

WithOverrides 返回应用覆盖之后的副本。覆盖只接受已知的键、非空的字符串、不超过 maxSelectorBytes、 合法 UTF-8 且没有控制字符;其余一律报错(宁可整体失败,也不静默忽略一个写错的键)。 CSS 选择器本身的语法在页面里校验(selector_invalid)。

type Target

type Target struct {
	ID                   string `json:"id"`
	Type                 string `json:"type"`
	Title                string `json:"title"`
	URL                  string `json:"url"`
	WebSocketDebuggerURL string `json:"webSocketDebuggerUrl"`
}

Target 是 /json/list 里的一项。

type Timing

type Timing struct {
	Total       time.Duration // 一次请求的总时限
	Call        time.Duration // 单次 CDP 调用
	Select      time.Duration // 点击会话行之后等面板挂载
	Poll        time.Duration // 轮询间隔
	Input       time.Duration // 文字出现在输入框里
	SendReady   time.Duration // 提交按钮变成「可发送」
	Evidence    time.Duration // 点发送之后等证据
	NewComposer time.Duration // 点 New Agent 之后等新输入框
	NewRow      time.Duration // 点发送之后等新会话行出现
	Settle      time.Duration // 看到新行之后再观察一小会儿,确认没有第二行
}

Timing 是各个等待的时限。零值字段取默认;测试里缩短。

func DefaultTiming

func DefaultTiming() Timing

DefaultTiming 是设计稿 §5.4 的取值。

Jump to

Keyboard shortcuts

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