tabctl

标签控制

使用 tabctl 安全地检查和分析标签页，并且仅在收到请求时执行有针对性的 GraphQL 变更。

公共浏览器 API

浏览器状态现在仅通过 GraphQL 提供：

• tabctl query '<GRAPHQL>'
• tabctl schema
• tabctl ping
• tabctl history

不要使用已移除的旧版浏览器子命令，例如 list、open、close、inspect、report、screenshot、archive 或 undo。

探索

tabctl schema
tabctl help
tabctl help query

读取示例

# Windows, tabs, and groups
 tabctl query '{ windows { windowId focused groups { groupId title } tabs { tabId title url groupTitle } } }'

# Paginated tabs
 tabctl query '{ tabs(limit: 20, offset: 0) { total hasMore items { tabId title url } } }'

# Analyze duplicate/stale tabs
 tabctl query '{ analyze(windowId: 123, staleDays: 30) { totalTabs duplicateTabs staleTabs } }'

# Inspect page metadata
 tabctl query 'query { inspectTabs(tabIds: [456], signals: ["page-meta"]) { entries { tabId signals { name valueJson } } } }'

# Inspect selectors with typed attrs and filters
 tabctl query 'query { inspectTabs(windowId: 123, selectors: [{ name: "prices", selector: ".price", attr: "text", all: true, text: "$", textMode: "contains" }, { name: "submit_visible", selector: "#submit", attr: "visible" }, { name: "submit_style", selector: "#submit", attr: "styles", styleProps: ["color", "background-color"] }, { name: "item_count", selector: ".item", attr: "count" }, { name: "email_value", selector: "input[type=email]", attr: "value" }, { name: "tos_checked", selector: "input[name=terms]", attr: "checked" }]) { entries { tabId url signals { name valueJson } } } }'

# Read page content as Markdown
 tabctl query 'query { readTabs(windowId: 123, extract: true, maxChars: 30000) { entries { tabId title url markdown chars truncated extracted cached status emptyReason diagnostics { source sourceHtmlChars sourceTextChars documentReadyState truncatedHtml cachedAt cacheAgeMs } error } } }'

# Build reports
 tabctl query '{ reportTabs(windowId: 123) { entries { tabId title url description } } }'

# Capture screenshots
 tabctl query 'query { captureScreenshots(tabIds: [456], mode: "viewport") { entries { tabId tiles { index width height } } } }'

只读提取说明

• readTabs 使用 Kreuzberg 预处理将主框架 HTML 转换为 Markdown。请检查每个标签页的 status、emptyReason、diagnostics 和 error；缓存回退使用有界的配置文件本地打开标签页缓存，该缓存会在读取成功、活动标签页切换以及活动页面静止时刷新，并在诊断信息中报告 status: CACHED、cached: true 和缓存来源。
• readTabs v1 不会遍历跨域 iframe 或 shadow DOM；对于不可脚本化的 URL，会返回 status: UNSUPPORTED_URL。
• inspectTabs 的选择器属性现在包括 html、value、count、box、styles、visible、enabled 和 checked。
• visible 表示元素已渲染，且不是 display:none、visibility:hidden 或 opacity:0。
• enabled 表示元素未被禁用，且 aria-disabled != "true"。
• 对于表单控件，checked 使用 input.checked；否则使用 aria-checked == "true"。

变更示例

# Open tabs in a new grouped window
 tabctl query 'mutation { openTabs(urls: ["https://example.com"], group: "Research", newWindow: true) { windowId groupId tabs { tabId url } } }'

# Group and window changes
 tabctl query 'mutation { updateGroup(groupId: 99, title: "Inbox", color: "blue") { groupId title color } }'
 tabctl query 'mutation { assignToGroup(tabIds: [456], groupTitle: "Inbox") { groupId title } }'
 tabctl query 'mutation { ungroupTabs(tabIds: [456]) { tabId groupId } }'
 tabctl query 'mutation { moveGroup(groupId: 99, newWindow: true) { movedToWindowId movedTabs } }'
 tabctl query 'mutation { mergeWindows(fromWindowId: 200, toWindowId: 123, closeSource: true, confirm: true) { movedTabs sourceClosed } }'

# Tab changes
 tabctl query 'mutation { focusTab(tabId: 456) { success } }'
 tabctl query 'mutation { refreshTabs(tabIds: [456]) { refreshedTabs } }'
 tabctl query 'mutation { moveTab(tabIds: [456], windowId: 123, index: 0) { movedTabs } }'

# Destructive actions with undo support
 tabctl query 'mutation { closeTabs(tabIds: [456], confirm: true) { txid closedTabs } }'
 tabctl query 'mutation { archiveTabs(windowId: 123) { txid archivedTabs } }'
 tabctl query 'mutation { deduplicateTabs(windowId: 123, confirm: true) { txid closedTabs } }'
 tabctl query 'mutation { undoAction(latest: true) { txid summary } }'

# Extension reload
 tabctl query 'mutation { reloadExtension { reloading } }'

安全

• 除非用户明确要求进行更改，否则优先使用只读 GraphQL 查询。
• 限定变更范围并确保可撤销；如有 txid 值，请一并提供。
• 未经明确指定目标或确认，绝不要对用户的整个浏览会话运行破坏性工作流。
• 遵守策略：受保护的标签页不会包含在查询和变更结果中。
• 仅在需要视觉上下文时使用截图。

便捷命令

tabctl ping
tabctl history --limit 10

使用 ping 检查连接和版本状态，并使用 history 查找撤销事务。

故障排除

• tabctl ping --json 是标准的运行时健康检查。
• tabctl doctor --fix 可修复本地配置文件连接和同步偏差。
• TABCTL_AUTO_SYNC_MODE=release-like tabctl query '{ tabs { total } }' 会在类似本地发布的测试期间强制执行运行时同步行为。