Communitygithub.com

sethjuarez/auditaur

名称:auditaur-debug。首次诊断 Tauri 应用调试的辅助技能,提供机器可读的 JSON 输出与系统化的工作流。

auditaur 是什么?

Auditaur 是一个专门用于 Tauri 应用调试的 AI 代理技能。它作为观察层(Observability Layer),在保留应用正常启动命令的前提下,附着或包装应用进程以收集就绪状态、遥测数据、驱动命令和人类审批门。该技能支持多种平台(包括 Windows PowerShell),并提供丰富的工作流:意图映射可将用户短语转换为标准 CLI 序列(`auditaur start`、`auditaur drill`、`auditaur inspect`、`auditaur stop`);就绪状态检查区分应用发现、心跳、SQLite 数据库、会话、窗口、前后端遥测、驱动桥和 CDP 端点等阶段;WebView 驱动通过 Tauri 原生桥实现,支持 `click`、`type`、`fill`、`snapshot` 等动作;人类审批门允许在 OAuth 审批、OS 权限提示等场景中暂停代理,等待真实用户操作。它会话管理严格,自动清理进程树和会话文件,避免后续命令定位失效会话。该技能最适合在开发者本地调试、CI 冒烟测试或代理端到端验证时作为可复现的诊断工具使用。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add sethjuarez/auditaur

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

Auditaur 调试工作流

将 Auditaur 作为 Tauri 应用调试的首次诊断界面。在作为代理运行时,优先使用机器可读的 JSON 格式。规范的心智模型为:Auditaur 观察应用,它不替代应用的正常开发命令。

意图映射

将常见的用户短语转换为相应的 Auditaur 工作流:

用户短语代理解释
"观察应用"附着到已经运行的应用并观察就绪状态。
"使用 Auditaur 启动" / "Auditaur 启动应用"当 .auditaur/config.json 存在时运行 auditaur start;否则在 Auditaur 观察下使用 debug run -- <正常命令> 启动正常的应用命令。
"使用 Auditaur 调试应用"先检查就绪状态,然后检查日志/时间线/追踪/IPC。
"驱动应用" / "在应用中点击"需要 Tauri 原生驱动桥,然后使用 auditaur drive。
"运行钻探" / "对应用进行冒烟测试"运行 auditaur drill 以使用配置的默认钻探,或运行 auditaur drill <名称> 以使用指定名称的钻探。
"手动审批" / "人类门" / "OAuth 授权"使用钻探脚本门,使得在人类操作完成时应用会话保持固定。

保留应用的正常启动命令。优先使用简单的仓库配置流程(如果可用):

auditaur start
auditaur drill
auditaur inspect
auditaur stop

这些命令默认读取 .auditaur/config.json 并共享 .auditaur/session.json,因此代理不需要自定义包装来实现就绪轮询、会话 ID、数据库路径或进程清理。

当代理需要机器可读的启动输出时使用 auditaur start --json。它会输出一个最终的 JSON 对象,包含准确的应用会话、进程、选择器、会话文件路径以及任何已生成的命名端口。auditaur stop 会停止记录的进程树并在清理后删除会话文件,使得后续命令不会针对已失效的会话。

先就绪再操作

在读取日志或驱动 UI 之前,先确定哪些部分已就绪:

auditaur debug --app <应用名称> --json status

对于正在运行的应用,等待核心遥测就绪:

auditaur debug --app <应用名称> --active --json watch --until-ready --timeout-seconds 120

如果任务需要前端遥测,添加 --require-frontend。如果任务需要 WebView 选择器动作,使用 Auditaur 应用内驱动桥:在恰好一个调试/测试 WebView 中启用 initAuditaur({ driveBridge: true })(每个 Auditaur 会话一个)并向就绪观察添加 --require-drive-bridge。

npm run tauri dev
auditaur debug --app <应用名称> --active --require-frontend --json watch --until-ready --timeout-seconds 120

在 Windows PowerShell 上:

npm run tauri dev
auditaur debug --app <应用名称> --active --require-frontend --json watch --until-ready --timeout-seconds 120

Auditaur drive 使用 Tauri 原生应用内驱动桥。应用必须在恰好一个调试/测试 WebView 中显式启用 initAuditaur({ driveBridge: true })(每个 Auditaur 会话一个),然后 auditaur drive 通过该桥发送有界请求。

启动应用

默认情况下优先使用附着模式:让开发者、IDE、Tauri 开发服务器或现有终端拥有应用启动权,然后使用 auditaur debug watch 观察就绪状态。这样可以保留用户的正常环境、调试器、热重载和终端输出。

仅当代理或冒烟脚本需要拥有可重复运行的控制权时使用包装模式。包装模式仍应通过应用的正常命令启动应用;Auditaur 观察该进程,而不是替换应用的启动系统。

场景首选模式
人类本地调试附着到已运行的应用
IDE/调试器/Tauri 开发工作流已在运行附着
代理需要端到端验证运行包装
自用或类似 CI 的本地冒烟测试包装

如果代理应该启动应用,包装现有命令:

auditaur start

auditaur start 使用 .auditaur/config.json,报告就绪状态,写入 .auditaur/session.json,并在就绪后有意保持应用运行。如果配置声明了命名端口,start 会预留随机本地端口,扩展命令中的 {{port:name}} 占位符,设置已配置的端口环境变量,并在会话文件和 JSON 输出中记录所选端口。如果配置尚不存在,使用较低级的形式:

auditaur debug --app <应用名称> --require-frontend --json run --timeout-seconds 180 --write-session .auditaur/session.json -- npm run tauri dev

debug run 报告就绪状态并在就绪后有意保持应用运行。当提供了 --app 时,它会忽略生成之前存在的匹配发现记录,等待新的 Auditaur 会话,并将就绪状态固定到该确切的会话/数据库/PID。为代理拥有的启动使用 --write-session <路径>,以便后续命令可以读取 sessionId、instanceId、pid、databasePath 和生成的选择器参数数组,而不是猜测使用 --active 或 --latest。验证完成后使用 auditaur stop 清理生成的应用进程。

解释就绪状态

检查 stages 数组:

  • app_discovery:Auditaur 发现文件存在。
  • heartbeat:应用心跳是新鲜的。
  • telemetry_database:SQLite 数据库存在且架构验证通过。
  • session:可以查询到会话行。
  • window:Tauri 窗口遥测存在。
  • backend_telemetry:后端/插件日志、跨度或窗口行存在。
  • frontend_telemetry:前端日志/错误/IPC/事件存在;仅当使用 --require-frontend 时需要。
  • drive_bridge:Tauri 原生应用内驱动桥状态存在且具有新鲜心跳;仅当使用 --require-drive-bridge 时需要。
  • cdp_endpoint:传统浏览器调试端点就绪;仅当显式请求时检查。

如果就绪状态为 false,则遵循阶段消息和 hints,而不是从终端输出中猜测。

驱动 WebView

在修改应用之前检查 Tauri 原生驱动桥:

auditaur drive --app <应用名称> --active --json inspect

如果需要目标选择,使用桥目标:

auditaur drive --app <应用名称> --active --json click --target auditaur-bridge --selector '<css>'

尽可能先使用只读操作:

auditaur drive --app <应用名称> --active --json exists --selector '<css>'
auditaur drive --app <应用名称> --active --json text --selector '<css>'
auditaur drive --app <应用名称> --active --json snapshot --selector body --output failure.json
auditaur drive --app <应用名称> --active --json screenshot --selector body --output failure.png --snapshot-output failure.json

在分享快照产物之前请先审查;它们可能包含 DOM 文本、URL 或其他敏感内容。

对于文本输入,当直接设置 DOM 值并触发 input/change 事件就足够时,使用 fill。当框架控制的输入或文本区域需要聚焦文本插入时,使用 type:

auditaur drive --app <应用名称> --active --json type --selector 'textarea' --value 'hello' --visible-only

在验证模态框、焦点覆盖或全屏外壳(这些可能留下重复的隐藏 DOM)时,选择器操作(wait、exists、text、click、fill、type、hover、select、check 和 uncheck)优先使用 --visible-only(或 --visible)。

如果 drive inspect 报告 bridge.status 为 inactive,在前端启用 driveBridge。一旦激活,可以通过 Tauri 原生桥使用 wait、exists、text、click、fill、type、press、hover、select、check、uncheck、evaluate、snapshot 和 screenshot。桥截图首先尝试使用原生 WebView 捕获(screenshotBackend=tauri_native_webview_snapshot)以获得无遮挡的 WebView 像素;选择器截图会裁剪该 WebView 图像并报告 screenshotScope=selector 和 selectorRect。如果 WebView 捕获失败,Auditaur 会回退到原生窗口捕获(screenshotBackend=tauri_native_window_xcap),然后进一步回退到 DOM 文本摘要 PNG(screenshotBackend=bridge_dom_summary_canvas)并附加错误元数据。evaluate 在 WebView 中运行任意 JavaScript,因此请将桥限制在开发/测试会话中使用。如果桥处于非活动状态,使用 Auditaur 遥测(timeline、ipc、traces、explain)获取真相,并仅在必须模拟手动 UI 输入时配对使用辅助功能自动化。

旧版兼容性:--cdp-port 可能出现在旧命令中,但 auditaur drive 会忽略它。驱动命令请使用正面措辞:说明它们使用了 Tauri 原生驱动桥。

检查遥测

就绪后,使用结构化读取命令:

auditaur apps --json
auditaur sessions --json
auditaur logs --json
auditaur errors --json
auditaur ipc --json
auditaur events --json
auditaur traces --json
auditaur timeline --json
auditaur explain --json

当存在过期或多个会话时,优先使用 --session <id>、--db <路径>、--active、--latest、--pid 或 --instance-id。

钻探中的人类门

在需要真实人类操作但保留相同固定应用会话的工作流中使用钻探人类门:OAuth/设备代码审批、OS 权限提示、安装程序提权、外部浏览器交接、摄像头/麦克风权限、硬件安全密钥,或任何代理应暂停而不是模拟信任敏感输入的流程。

在钻探脚本中添加门,并使用 --script <路径> 运行钻探:

{
  "gates": [
    {
      "name": "批准 GitHub 登录",
      "instructions": "请在应用或浏览器中完成 GitHub 设备代码审批,然后返回此处。",
      "selector": "#status-card",
      "expectText": "已登录",
      "manualContinue": true,
      "timeoutMs": 300000,
      "choices": [
        { "id": "done", "label": "完成", "outcome": "continue" },
        { "id": "blocked", "label": "受阻", "outcome": "fail" }
      ]
    }
  ]
}

人类门在 Auditaur 已生成并固定新的应用会话并达到就绪状态后运行,但在选择器/文本/错误/IPC/解释证据收集之前。在门期间不要重启应用或切换到其他会话;关键是保持门之前和门之后的证据关联到同一会话/数据库/PID。门可以是仅选择器的监控等待、手动继续、带有 continue/retry/skip/fail/abort 结果的选项、输入和剪贴板提示。默认情况下,钻探报告中的敏感输入和剪贴板值会被编辑,但本地临时的门响应 JSON 可能会短暂包含原始输入值,直到钻探消耗并移除它。

当门需要手动响应时,Auditaur 还会在固定会话数据库旁边发布一个会话本地请求。代理可以通过 MCP 列出和回答这些请求:

auditaur mcp

使用 list_pending_human_gates 查找等待中的门,使用 respond_human_gate 并附带 requestId、可选的 choiceId、可选的 inputs 和清晰的 responder 值。使用与钻探相同的 Auditaur 数据目录运行 MCP 服务器,以便它可以查看会话本地请求文件。如果已安装携带 auditaur init extension 的 Copilot canvas 扩展程序,为等待中的门打开 auditaur-human-gate canvas,以便用户获得操作卡片并可以点击响应。当没有 MCP 或 canvas 客户端可用时,终端 ENTER/选项输入作为回退。

常见失败模式

  • 无发现文件:应用仍在编译、尚未启动,或未注册 Auditaur 插件。
  • 数据库无法读取/架构无效:应用初始化不完全或数据目录错误。
  • 无前端遥测:前端 API 未初始化、前端动作尚未触发,或 UI 中导出失败。
  • 驱动桥非活动:在恰好一个调试/测试 WebView 中启用 initAuditaur({ driveBridge: true }),否则使用遥测加辅助功能回退。
  • 等待中的人类门:不要用合成的应用状态绕过它。将门指令呈现给用户,通过 canvas/MCP/终端路径响应,然后继续在同一固定会话上收集证据。
  • 目标歧义:使用 --target auditaur-bridge;如果匹配多个会话,使用 --session-id、--instance-id、--pid、--latest 或 --active 消除歧义。
  • JSON 输出污染:从当前的 Auditaur CLI 使用 debug run --json;子启动输出不应出现在 JSON 行中。

验证循环

对于高置信度的更改:

  1. 运行相关的测试/构建。
  2. 使用 auditaur debug 启动或附着。
  3. 运行配置的 auditaur drill;如果它发布了人类门,通过 canvas/MCP/终端响应路径将其呈现给用户,而不是替代手动操作。
  4. 当需要 UI 覆盖时,通过 Tauri 原生桥驱动代表性的 UI 路径。
  5. 当前端遥测至关重要时,重新检查 debug status --require-frontend。
  6. 检查 timeline 和 explain。
  7. 清理生成的应用进程和临时遥测目录。

相关技能