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
- Variables
- func AuditPath(dataDir string) string
- func ConsentPath(dataDir string) string
- func ParseEndpoint(s string) (int, error)
- func RecentAudit(dataDir string, n int) []string
- func RemoveConsent(dataDir string) error
- func Status(dataDir string) (mode, ops string)
- func WriteConsent(dataDir string, c Consent) error
- type Consent
- type ConsentError
- type Executor
- type Options
- type PageSpec
- type Resolved
- type Selectors
- type Target
- type Timing
Constants ¶
const ( DefaultPageTitle = "Cursor Agents" DefaultPageURLPattern = `(?i)^vscode-file://vscode-app/.*/cursor/resources/app/` )
DefaultPageTitle 与 DefaultPageURLPattern 是「Cursor Agents」窗口的识别规则:标题恰好等于它,且地址是 Cursor 安装目录里的 workbench 页面。
const ConsentFileName = "gui-wake.json"
ConsentFileName 是主机所有者的同意文件,放在 Agent 的数据目录里。它是 GUI 唤醒唯一的开关与唯一的配置入口: Hub、网页、任何远程调用方都不能写它——只有在这台主机上能写。每次请求都重读(改了立刻生效,删了立刻失效)。
const SelectorsVersion = "cursor-agents/3.27-2026-10-30"
SelectorsVersion 是内置选择器表的版本标识:Cursor 改版、我们调整默认值时递增,probe 会把它带回 Hub,便于对照。
Variables ¶
var ( // ErrConsentMissing:文件不存在 —— GUI 唤醒没有开启。 ErrConsentMissing = errors.New("gui-wake.json 不存在:这台主机没有开启 GUI 唤醒") // ErrConsentDisabled:文件里 enabled=false。 ErrConsentDisabled = errors.New("gui-wake.json 里 enabled=false:GUI 唤醒已关闭") )
同意文件读取的几类结果。
Functions ¶
func RecentAudit ¶
RecentAudit 返回审计日志(gui-wake.log)的最后 n 行,供 `gui-wake status` 展示给主机所有者。 文件不存在、不是普通文件或读不了都返回空:这只是一个看日志的便利,不影响任何动作。 只读文件末尾至多 recentAuditTail 字节;每一行去掉控制字符并截断(日志是我们自己写的,但展示前不信任它)。
func RemoveConsent ¶
RemoveConsent 删除同意文件(关闭 GUI 唤醒)。文件本来就不存在不算错。
func WriteConsent ¶
WriteConsent 原子地写入同意文件(供 `relaymesh-agent gui-wake enable` 使用)。先校验再写,写不进无效内容。
Types ¶
type Consent ¶
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 ¶
ReadConsent 读取同意文件的原始内容:严格解析(未知字段、尾随内容、超大文件、符号链接都是无效), 但不要求 enabled、也不展开校验。供命令行在重新开启时保留已有的选择器覆盖,以及 `status` 如实展示。 错误与 LoadConsent 一致:ErrConsentMissing(文件不存在)或 *ConsentError(存在但无效)。
type ConsentError ¶
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)。
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 ¶
LoadConsent 读取并校验同意文件。返回值要么是可用的配置,要么是下面几类错误之一: ErrConsentMissing / ErrConsentDisabled(正常的「没开」),*ConsentError(文件存在但无效)。
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 字面量传进页面里的固定函数——页面里执行的脚本是源码里的常量,选择器只是数据。
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 是各个等待的时限。零值字段取默认;测试里缩短。