From 0ff17297938be22fd08385925c2794de8a52a412 Mon Sep 17 00:00:00 2001 From: admin Date: Mon, 18 May 2026 11:45:01 +0800 Subject: [PATCH] Initial release: airdbg --- .claude-plugin/plugin.json | 52 ++++++ commands/airdbg.md | 100 +++++++++++ scripts/airdbg_mode.py | 275 +++++++++++++++++++++++++++++++ scripts/install_airdbg_plugin.py | 88 ++++++++++ skills/airdbg/SKILL.md | 245 +++++++++++++++++++++++++++ skills/airdbg/agents/openai.yaml | 3 + 6 files changed, 763 insertions(+) create mode 100644 .claude-plugin/plugin.json create mode 100644 commands/airdbg.md create mode 100644 scripts/airdbg_mode.py create mode 100644 scripts/install_airdbg_plugin.py create mode 100644 skills/airdbg/SKILL.md create mode 100644 skills/airdbg/agents/openai.yaml diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..3bd0a50 --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,52 @@ +{ + "name": "airdbg", + "version": "0.1.4", + "description": "Debug-first repair workflow for reproducing defects, requiring GUI evidence for local or remote GUI validation, using local or remote AirNDB for packet-capture evidence, and using local or remote AirSDB for static-analysis evidence when needed, while finding root causes, applying focused fixes, verifying behavior, and maintaining AGENTS.md, ADR, and C4 module context.", + "author": { + "name": "14816", + "email": "noreply@example.com", + "url": "https://airlongdian.fun/plugins/airdbg" + }, + "homepage": "https://airlongdian.fun/plugins/airdbg", + "repository": "http://git.airlongdian.fun/admin/airdbg.git", + "license": "MIT", + "keywords": [ + "airdbg", + "debug", + "bugfix", + "root-cause", + "adr", + "c4", + "airxdb", + "airndb", + "gui-debug", + "screenshot", + "packet-capture", + "pcap", + "airsdb", + "cppcheck", + "static-analysis" + ], + "skills": "./skills/", + "interface": { + "displayName": "AirDbg", + "shortDescription": "Debug-first repair with graphical, packet, and static-analysis evidence", + "longDescription": "AirDbg guides Codex through reproducible debugging: load project context, initialize missing AGENTS.md/ADR/C4 docs, discuss symptoms with the user, require AirXDB or equivalent GUI or screen evidence for every GUI validation instead of trusting process liveness, call local or remote AirNDB for tcpdump or WinDump packet capture, remote tcpdump or dumpcap capture, pcap summaries, BPF filters, DNS, TCP, UDP, TLS, HTTP connectivity and network evidence when needed, call local or remote AirSDB for cppcheck static analysis, staticanalysis.md summaries, and static-analysis documentation when needed, isolate root cause, apply focused fixes, verify behavior, and keep architecture context current.", + "developerName": "14816", + "category": "Productivity", + "capabilities": [ + "Interactive", + "Write" + ], + "websiteURL": "https://airlongdian.fun/plugins/airdbg", + "privacyPolicyURL": "https://openai.com/policies/row-privacy-policy/", + "termsOfServiceURL": "https://openai.com/policies/row-terms-of-use/", + "defaultPrompt": [ + "Use AirDbg to reproduce the current bug, isolate the root cause, and apply the smallest safe fix.", + "Use AirDbg to repair a failing test and keep AGENTS.md, ADR, and C4 context in sync.", + "Use AirDbg to investigate a GUI, network, or C/C++ quality issue and collect the right evidence before changing code." + ], + "brandColor": "#D97706", + "screenshots": [] + } +} diff --git a/commands/airdbg.md b/commands/airdbg.md new file mode 100644 index 0000000..572f211 --- /dev/null +++ b/commands/airdbg.md @@ -0,0 +1,100 @@ +--- +description: Enter, exit, or inspect AirDbg mode for debugging and repair, with mandatory GUI evidence plus AirNDB and AirSDB evidence handoff +argument-hint: [enter|exit|status] +allowed-tools: [Read, Glob, Grep, Bash, Write, Edit] +--- + +# /airdbg + +控制当前工作区的 AirDbg 调试修复模式。 + +用户传入参数：`$ARGUMENTS` + +- `enter` 或空参数：进入 AirDbg 模式并初始化调试上下文。 +- `status`：检查 AirDbg 状态和关键文件是否存在。 +- `exit`：退出 AirDbg 模式。 + +## 执行步骤 + +1. 解析 `$ARGUMENTS`，默认动作为 `enter`。 +2. 在当前项目根目录运行： + +```bash +python "$HOME/plugins/airdbg/scripts/airdbg_mode.py" --mode --project . +``` + +如果 `python` 不存在，尝试 `py` 或 `python3`。 + +3. `enter` 后开始调试对话： + - 确认错误症状、期望行为、实际行为。 + - 确认复现步骤、环境、最近变更和修复限制。 + - 读取或初始化 `AGENTS.md`、ADR 和 C4 module。 + - 复现、定位根因、最小修复、验证。 + +4. 调试中遇到图形相关需求时，必须调用 `airxdb` 或补充等效 GUI/屏幕证据： + - 图形对比、截图取证、视觉回归、布局错位、弹窗、焦点、Canvas、浏览器/桌面 GUI：用 AirXDB 获取截图或报告。 + - 如果目标 GUI 在远程设备、测试机、服务器、VM 或 SSH 主机上，使用 AirXDB 远程设备路径： + +```bash +python "$HOME/plugins/airxdb/scripts/airxdb_remote_device.py" --project . --action setup +python "$HOME/plugins/airxdb/scripts/airxdb_remote_device.py" --project . --action screenshot +``` + + - 远程 helper 缺少 `AIRXDB_REMOTE_SSH_TARGET` 时，先让用户提供 SSH 目标；有目标后它会自动探测远端截图工具，缺失时自动尝试配置。 + - 需要确认用户界面操作是否可用：用 AirXDB 执行最小 GUI 操作验证。 + - 本地或远程 GUI 测试/验证不得只以进程存在、窗口拉起、命令退出成功或日志无异常视为通过。 + - 如果是嵌入式屏幕、显示链路等截图无诊断价值的场景，可不强制截图，但必须补充等效的 GUI/屏幕状态证据和操作验证，并在 debug log 记录原因。 + - AirDbg 继续负责根因分析、修复和最终验证，并把 AirXDB 证据写入 debug log。 + +5. 调试中遇到抓包或网络层证据需求时，可调用 `airndb`： + - DNS、TCP、UDP、TLS、HTTP 连接、端口、代理、防火墙、丢包、重传、RST、延迟：用 AirNDB 设计 BPF 并抓取/读取 pcap。 + - 需要判断请求是否发出、响应是否回来或失败发生在哪个网络阶段：用 AirNDB 生成 pcap、summary 和 JSON 报告。 + - 如果目标流量在远程设备、测试机、服务器、VM、容器宿主机或 SSH 主机上，使用 AirNDB 远程设备路径： + +```bash +python "$HOME/plugins/airndb/scripts/airndb_remote_device.py" --project . --action setup +python "$HOME/plugins/airndb/scripts/airndb_remote_device.py" --project . --action interfaces +python "$HOME/plugins/airndb/scripts/airndb_remote_device.py" --project . --action capture --iface --filter "" --count 200 --timeout 30 +``` + + - 远程 helper 缺少 `AIRNDB_REMOTE_SSH_TARGET` 时，先让用户提供 SSH 目标；有目标后它会自动探测远端 `tcpdump` / `dumpcap`，缺失时自动尝试配置。 + - AirDbg 继续负责代码层根因分析、修复和最终验证，并把 AirNDB 证据写入 debug log。 + +6. 调试中遇到 C/C++ 静态分析或 cppcheck 证据需求时，可调用 `airsdb`： +- 未初始化变量、空指针、越界、资源释放、危险转换、CWE、代码质量或安全性初筛：用 AirSDB 运行 cppcheck 并维护 `AirPlan/docs/staticanalysis.md`。 +- 当检验、测试或调试判断需要静态分析能力时，用 AirSDB 获取 `AirPlan/docs/staticanalysis.md`、XML/JSON 报告等静态分析信息和文档辅助调试。 + - 如果目标代码在远程设备、测试机、服务器、VM、容器宿主机或 SSH 主机上，使用 AirSDB 远程设备路径： + +```bash +python "$HOME/plugins/airsdb/scripts/airsdb_remote_device.py" --project . --action setup +python "$HOME/plugins/airsdb/scripts/airsdb_remote_device.py" --project . --action scan +``` + + - AirDbg 继续负责代码层根因分析、修复和最终验证，并把 AirSDB 证据写入 debug log。 + +7. 修复过程中必须维护： + - `AGENTS.md` + - `docs/architecture/adr/` + - `docs/architecture/c4/module.md` + - `docs/debug/debug-log.md` + +## 输出文案 + +进入模式： + +```text +AirDbg 模式已开启：已初始化或检查 AGENTS.md、ADR、C4 module 和 debug log。请描述错误症状、复现步骤、期望行为和实际行为；如果涉及本机或远程 GUI 测试/验证，必须使用 AirXDB 或等效 GUI/屏幕证据做复验，不能只看进程是否存活；如果涉及抓包或网络层分析，可调用 AirNDB 获取本机或远程 pcap/summary 证据；如果涉及 C/C++ 静态分析或检验需要静态分析能力，可调用 AirSDB 获取本机或远程 cppcheck/staticanalysis 证据。 +``` + +退出模式： + +```text +AirDbg 模式已退出：已返回标准 Codex 流程。 +``` + +状态检查： + +```text +AirDbg 状态： +关键文件：逐项列出 ok/missing。 +``` diff --git a/scripts/airdbg_mode.py b/scripts/airdbg_mode.py new file mode 100644 index 0000000..63612df --- /dev/null +++ b/scripts/airdbg_mode.py @@ -0,0 +1,275 @@ +#!/usr/bin/env python3 +"""Bootstrap AirDbg debugging context files.""" + +from __future__ import annotations + +import argparse +import json +from datetime import datetime, timezone +from pathlib import Path +from typing import Dict, Tuple + +MARKER_BEGIN = "" +MARKER_END = "" + + +def now_iso() -> str: + return datetime.now(timezone.utc).isoformat() + + +def airdbg_agents_block() -> str: + return f"""{MARKER_BEGIN} +## AirDbg Debug Workflow + +1. Use AirDbg for `/airdbg` debugging and repair sessions. +2. Before fixing, load project context: + - `AirPlan/AGENTS.md` + - `AirPlan/docs/architecture/adr/` + - `AirPlan/docs/architecture/c4/module.md` + - `AirPlan/docs/debug/debug-log.md` +3. Reproduce the issue before changing code whenever feasible. +4. Identify root cause, then apply the smallest verifiable fix. +5. Record reproduction, root cause, fix, validation, and residual risk in `AirPlan/docs/debug/debug-log.md`. +6. When debugging needs graphical comparison, screenshots, GUI operation, browser/desktop UI, canvas, layout, focus, popup, or visual evidence, call AirXDB for screenshots, GUI exploration, or operation validation. +7. For every local or remote GUI test or validation, do not treat process liveness, window launch, command success, or clean logs as a pass; require image/GUI evidence plus at least one GUI operation or state check. If screenshots are not diagnostically useful, such as many embedded-screen or display-pipeline scenarios, record equivalent screen evidence instead. +8. If the GUI target is a remote device, test machine, VM, server, or SSH host, call the AirXDB remote device helper before local Computer MCP; it should probe SSH, auto-configure missing remote screenshot tools when possible, and save evidence under `AirPlan/docs/debug/airxdb-artifacts/`. +9. When debugging needs packet capture, pcap reading, BPF filters, DNS/TCP/UDP/TLS/HTTP connectivity, ports, proxy, firewall, packet loss, retransmits, resets, or latency evidence, call AirNDB. +10. If the network target is a remote device, test machine, VM, container host, server, or SSH host, call the AirNDB remote device helper before local capture; it should probe SSH, auto-configure missing remote tcpdump/dumpcap when possible, and save evidence under `AirPlan/docs/network/airndb-captures/`. +11. When debugging needs C/C++ static analysis, cppcheck, code quality, security-relevant findings, CWE, null pointer, bounds, resource, conversion, uninitialized-variable evidence, or static-analysis capability to support validation, call AirSDB and read `AirPlan/docs/staticanalysis.md` plus XML/JSON artifacts when helpful. +12. If the static-analysis target is a remote device, test machine, VM, container host, server, or SSH host, call the AirSDB remote device helper before local cppcheck; it should probe SSH, auto-configure missing remote cppcheck when possible, and maintain `staticanalysis.md`. +13. Record AirXDB, AirNDB, and AirSDB commands, remote target when applicable, screenshot/pcap/staticanalysis/report paths, observations, and how they relate to root cause in `AirPlan/docs/debug/debug-log.md`. +14. Update ADR records when a fix changes long-term behavior, contracts, dependencies, data ownership, error handling, GUI automation boundaries, remote-device boundaries, network boundaries, static-analysis boundaries, or architecture decisions. +15. Update C4 module docs when module boundaries, dependencies, public interfaces, data ownership, GUI automation, local/remote screenshot evidence, local/remote packet capture, static-analysis evidence, network observability, or visual validation boundaries change. +16. Keep ADRs concise because they are AI context records. +{MARKER_END} +""" + + +def c4_module_template() -> str: + return """# C4 Module + +## System Context +- TODO: Describe the system, users, and important external systems. + +## Containers +- TODO: Describe deployable/runtime units. + +## Modules + +| Module | Responsibility | Public Interfaces | Dependencies | Data Ownership | Debug-Relevant Notes | +| --- | --- | --- | --- | --- | --- | +| TODO | TODO | TODO | TODO | TODO | TODO | + +## Error and Observability Flow +- TODO: Describe where errors are raised, logged, retried, surfaced, or recovered. + +## GUI / Visual Debug Boundaries +- AirXDB screenshot evidence, GUI operation checks, graphical comparison, or visual validation used in debugging: TODO +- AirXDB remote device evidence, SSH target, remote screenshot tool, or remote display constraints used in debugging: TODO +- Browser bridge, desktop control, canvas, focus, popup, layout, or multi-display constraints relevant to defects: TODO + +## Network / Packet Debug Boundaries +- AirNDB pcap evidence, tcpdump/WinDump commands, BPF filters, packet summaries, or network validation used in debugging: TODO +- AirNDB remote device evidence, SSH target, remote tcpdump/dumpcap tool, or remote capture permissions used in debugging: TODO +- DNS, TCP, UDP, TLS, HTTP, proxy, firewall, port, NAT, WSL/container/VM/host network constraints relevant to defects: TODO + +## Static Analysis Boundaries +- AirSDB cppcheck evidence, staticanalysis.md entries, XML/JSON reports, suppressions, or quality gates used in debugging: TODO +- AirSDB remote device evidence, SSH target, remote cppcheck tool, or remote static-analysis permissions used in debugging: TODO + +## Change Log +- TODO: Record module-boundary changes caused by fixes. +""" + + +def adr_template() -> str: + return """# ADR-0001: AirDbg Debug Context Governance + +- Status: Accepted +- Date: TODO + +## Context +Debugging sessions need durable AI-readable context so future fixes can understand prior decisions. + +## Decision +Use AirDbg to maintain `AirPlan/AGENTS.md`, `AirPlan/docs/architecture/c4/module.md`, `AirPlan/docs/architecture/adr/`, and `AirPlan/docs/debug/debug-log.md` during repair work. +When debugging requires graphical comparison, screenshots, GUI operations, or visual evidence, use AirXDB for evidence gathering and operation validation, then return to AirDbg for root-cause analysis and focused repair. If the GUI target is remote, use AirXDB's remote device helper before local Computer MCP so SSH and remote screenshot tooling are checked or auto-configured. +Do not treat process liveness, window launch, command success, or clean logs as sufficient proof for a GUI pass. Require image/GUI evidence and a GUI operation or state check for every local or remote GUI validation. If screenshots are not diagnostically useful, such as many embedded-screen or display-pipeline scenarios, record equivalent screen evidence and why screenshots were skipped. +When debugging requires packet capture, pcap analysis, DNS/TCP/UDP/TLS/HTTP connectivity evidence, ports, proxy, firewall, retransmits, resets, or latency analysis, use AirNDB for bounded network evidence, then return to AirDbg for root-cause analysis and focused repair. If the network target is remote, use AirNDB's remote device helper before local capture so SSH and remote tcpdump/dumpcap are checked or auto-configured. +When debugging requires C/C++ static analysis, cppcheck, code quality, security-relevant findings, CWE evidence, or static-analysis capability to support validation, use AirSDB for local or remote static-analysis evidence and `staticanalysis.md` context, then return to AirDbg for root-cause analysis and focused repair. + +## Consequences +- Fixes carry reproducible context across sessions. +- Architecture-impacting repairs must update ADR and C4 module docs. +- ADRs stay concise and focused on decisions. +- GUI evidence and graphical operation results are linked to root cause and validation records. +- Embedded-screen or display-pipeline cases that skip screenshots still record equivalent screen evidence and the reason screenshots were not useful. +- Network packet evidence and pcap summaries are linked to root cause and validation records. +- Static-analysis evidence and staticanalysis.md summaries are linked to root cause and validation records. +- Remote-device SSH targets, auto-configuration outcomes, and permission limits are recorded when they affect debugging. + +## Alternatives +- Chat-only debugging notes: rejected because context is easy to lose. +""" + + +def debug_log_template() -> str: + return """# Debug Log + +Append entries for AirDbg sessions. + +## Entry Template + +### YYYY-MM-DD: short problem title + +- Symptom: TODO +- Expected: TODO +- Actual: TODO +- Reproduction: TODO +- Root cause: TODO +- AirXDB local/remote evidence: TODO +- AirNDB local/remote evidence: TODO +- AirSDB local/remote static-analysis evidence: TODO +- Fix: TODO +- Validation: TODO +- ADR/C4 updates: TODO +- Residual risk: TODO +""" + + +def write_if_missing(path: Path, content: str) -> bool: + if path.exists(): + return False + path.parent.mkdir(parents=True, exist_ok=True) + path.write_text(content, encoding="utf-8", newline="\n") + return True + + +def upsert_agents_md(path: Path) -> str: + block = airdbg_agents_block().rstrip() + "\n" + + if path.exists(): + original = path.read_text(encoding="utf-8") + existed = True + else: + original = "# AGENTS.md\n\n" + existed = False + + begin = original.find(MARKER_BEGIN) + end = original.find(MARKER_END) + + if begin >= 0 and end > begin: + end += len(MARKER_END) + updated = original[:begin].rstrip() + "\n\n" + block + original[end:].lstrip() + status = "updated" + else: + updated = original.rstrip() + "\n\n" + block + status = "updated" if existed else "created" + + path.parent.mkdir(parents=True, exist_ok=True) + path.write_text(updated, encoding="utf-8", newline="\n") + return status + + +def artifact_map(project_root: Path) -> Dict[str, Path]: + return { + "AGENTS.md": project_root / "AirPlan" / "AGENTS.md", + "c4_module": project_root / "AirPlan" / "docs" / "architecture" / "c4" / "module.md", + "adr_dir": project_root / "AirPlan" / "docs" / "architecture" / "adr", + "adr_0001": project_root / "AirPlan" / "docs" / "architecture" / "adr" / "ADR-0001-airdbg-debug-context-governance.md", + "debug_log": project_root / "AirPlan" / "docs" / "debug" / "debug-log.md", + "state": project_root / "AirPlan" / "state" / "airdbg" / "state.json", + } + + +def write_state(path: Path, enabled: bool, project_root: Path) -> None: + artifacts = artifact_map(project_root) + health = { + name: artifacts[name].exists() + for name in [ + "AGENTS.md", + "c4_module", + "adr_dir", + "adr_0001", + "debug_log", + ] + } + + payload = { + "enabled": enabled, + "updatedAt": now_iso(), + "projectRoot": str(project_root), + "artifactHealth": health, + } + + path.parent.mkdir(parents=True, exist_ok=True) + path.write_text(json.dumps(payload, indent=2) + "\n", encoding="utf-8") + + +def enter_mode(project_root: Path) -> Tuple[str, Dict[str, str]]: + artifacts = artifact_map(project_root) + results: Dict[str, str] = {} + + results["AGENTS.md"] = upsert_agents_md(artifacts["AGENTS.md"]) + results["c4_module"] = "created" if write_if_missing(artifacts["c4_module"], c4_module_template()) else "exists" + artifacts["adr_dir"].mkdir(parents=True, exist_ok=True) + results["adr_dir"] = "exists" + results["adr_0001"] = "created" if write_if_missing(artifacts["adr_0001"], adr_template()) else "exists" + results["debug_log"] = "created" if write_if_missing(artifacts["debug_log"], debug_log_template()) else "exists" + + write_state(artifacts["state"], True, project_root) + return "enabled", results + + +def exit_mode(project_root: Path) -> Tuple[str, Dict[str, str]]: + artifacts = artifact_map(project_root) + write_state(artifacts["state"], False, project_root) + return "disabled", {} + + +def status_mode(project_root: Path) -> Tuple[str, Dict[str, str]]: + artifacts = artifact_map(project_root) + state_file = artifacts["state"] + + enabled = False + if state_file.exists(): + try: + payload = json.loads(state_file.read_text(encoding="utf-8")) + enabled = bool(payload.get("enabled")) + except json.JSONDecodeError: + enabled = False + + results = { + name: ("ok" if path.exists() else "missing") + for name, path in artifacts.items() + if name != "state" + } + return ("enabled" if enabled else "disabled"), results + + +def parse_args() -> argparse.Namespace: + parser = argparse.ArgumentParser(description="Manage AirDbg project artifacts.") + parser.add_argument("--mode", choices=["enter", "exit", "status"], default="enter") + parser.add_argument("--project", default=".") + return parser.parse_args() + + +def main() -> None: + args = parse_args() + project_root = Path(args.project).expanduser().resolve() + + if args.mode == "enter": + mode_state, result = enter_mode(project_root) + elif args.mode == "exit": + mode_state, result = exit_mode(project_root) + else: + mode_state, result = status_mode(project_root) + + print(f"airdbg_mode={mode_state}") + print(f"project_root={project_root}") + for key, value in result.items(): + print(f"{key}={value}") + + +if __name__ == "__main__": + main() diff --git a/scripts/install_airdbg_plugin.py b/scripts/install_airdbg_plugin.py new file mode 100644 index 0000000..c0e5d41 --- /dev/null +++ b/scripts/install_airdbg_plugin.py @@ -0,0 +1,88 @@ +#!/usr/bin/env python3 +"""Install the AirDbg plugin into the current user's home-local plugin directory.""" + +from __future__ import annotations + +import argparse +import json +import shutil +from pathlib import Path +from typing import Any, Dict + +PLUGIN_NAME = "airdbg" + + +def copy_plugin(source: Path, target: Path) -> None: + if source.resolve() == target.resolve(): + return + if target.exists(): + shutil.rmtree(target) + ignore = shutil.ignore_patterns("__pycache__", "*.pyc", ".DS_Store", ".git") + shutil.copytree(source, target, ignore=ignore) + + +def marketplace_payload() -> Dict[str, Any]: + return { + "name": "local-airdbg", + "interface": {"displayName": "Local AirDbg Plugins"}, + "plugins": [], + } + + +def update_marketplace(path: Path) -> None: + if path.exists(): + payload = json.loads(path.read_text(encoding="utf-8")) + else: + payload = marketplace_payload() + + payload.setdefault("name", "local-airdbg") + payload.setdefault("interface", {}).setdefault("displayName", "Local AirDbg Plugins") + plugins = payload.setdefault("plugins", []) + + entry = { + "name": PLUGIN_NAME, + "source": { + "source": "local", + "path": f"./plugins/{PLUGIN_NAME}", + }, + "policy": { + "installation": "INSTALLED_BY_DEFAULT", + "authentication": "ON_INSTALL", + }, + "category": "Productivity", + } + + for index, existing in enumerate(plugins): + if existing.get("name") == PLUGIN_NAME: + plugins[index] = entry + break + else: + plugins.append(entry) + + path.parent.mkdir(parents=True, exist_ok=True) + path.write_text(json.dumps(payload, indent=2) + "\n", encoding="utf-8") + + +def parse_args() -> argparse.Namespace: + parser = argparse.ArgumentParser(description="Install AirDbg as a home-local Codex plugin.") + parser.add_argument("--source", default=str(Path(__file__).resolve().parents[1])) + parser.add_argument("--home", default=str(Path.home())) + return parser.parse_args() + + +def main() -> None: + args = parse_args() + source = Path(args.source).expanduser().resolve() + home = Path(args.home).expanduser().resolve() + target = home / "plugins" / PLUGIN_NAME + marketplace = home / ".agents" / "plugins" / "marketplace.json" + + copy_plugin(source, target) + update_marketplace(marketplace) + + print(f"installed_plugin={target}") + print(f"marketplace={marketplace}") + + +if __name__ == "__main__": + main() diff --git a/skills/airdbg/SKILL.md b/skills/airdbg/SKILL.md new file mode 100644 index 0000000..19dfaf2 --- /dev/null +++ b/skills/airdbg/SKILL.md @@ -0,0 +1,245 @@ +--- +name: airdbg +description: Debug-first repair workflow. Use when the user invokes /airdbg or explicitly asks for AirDbg mode to debug, reproduce, diagnose, or fix software errors, including GUI, visual, screenshot, browser UI, desktop UI, remote GUI/device debugging, canvas, layout, focus, popup, graphical operation, network, packet capture, remote packet capture, pcap, DNS, TCP, UDP, TLS, HTTP connectivity, proxy, firewall, port, retransmit, reset, latency, cppcheck, static analysis, code quality, or security-relevant C/C++ defects. Load or initialize AirPlan/AGENTS.md, AirPlan/docs/architecture/adr/ decision records, and AirPlan/docs/architecture/c4/module.md; discuss symptoms and constraints with the user; reproduce the issue; require AirXDB local or remote device helpers or equivalent GUI/screen evidence for every local or remote GUI validation instead of treating process liveness as success; call AirNDB local or remote device helpers when tcpdump/WinDump packet capture, pcap analysis, BPF filters, or network-layer evidence is needed; call AirSDB local or remote device helpers when static-analysis capability, cppcheck evidence, or AirPlan/docs/staticanalysis.md documentation is needed; identify root cause; apply a focused fix; verify with tests or equivalent checks; and update AirPlan/AGENTS.md, ADR, and C4 module docs when project behavior, module boundaries, dependencies, GUI automation boundaries, network boundaries, static-analysis boundaries, remote-device boundaries, or architecture decisions change. +--- + +# AirDbg + +## 核心约束 + +- 全程使用中文与用户交流，代码、命令、日志、路径、异常名保持原文。 +- `/airdbg` 是主要触发入口。用户进入 AirDbg 后，围绕调试和修复错误推进。 +- 先加载项目上下文，再修复：`AirPlan/AGENTS.md`、`AirPlan/docs/architecture/adr/`、`AirPlan/docs/architecture/c4/module.md`。 +- 如果这些文件不存在，先分析当前项目并初始化它们；C4 module 要记录真实模块边界，不只放空模板。 +- 与用户交流症状、复现步骤、期望行为、实际行为、影响范围和修复约束。 +- 默认做最小可验证修复，避免顺手重构。 +- 每个修复都要验证。优先自动化测试，其次是可重复命令或明确的手工验证步骤。 +- 只要验证或复现涉及本地或远程 GUI，就不能只以进程存在、窗口拉起、命令退出成功、端口监听或日志无异常判定通过；必须辅以图像/GUI 检验和测试。 +- 调试中遇到图形对比、截图取证、GUI 操作、浏览器/桌面界面、Canvas、弹窗、焦点、布局、视觉回归或其他图形功能时，必须调用 `airxdb` 获取截图、探索界面、执行操作验证或收集视觉证据；如果是嵌入式屏幕、显示链路等截图无诊断价值的场景，可不强制截图，但必须补充等效的 GUI/屏幕状态证据和操作验证，并记录原因。 +- 如果 GUI 问题发生在远程设备、测试机、VM、服务器或 SSH 主机上，调用 AirXDB remote device helper，而不是默认使用本机 Computer MCP。 +- 调试中遇到抓包分析、pcap、tcpdump/WinDump、BPF、DNS、TCP、UDP、TLS、HTTP 连接、端口、代理、防火墙、丢包、重传、RST 或延迟问题时，可以调用 `airndb` 获取网络层调试证据。 +- 如果网络问题发生在远程设备、测试机、VM、容器宿主机、服务器或 SSH 主机上，调用 AirNDB remote device helper，而不是默认使用本机抓包工具。 +- 调试中遇到需要静态分析能力的检验、测试或定位场景，以及 C/C++ 静态分析、cppcheck、代码质量、安全性初筛、未初始化变量、空指针、越界、资源释放、危险转换或 CWE 线索需求时，可以调用 `airsdb` 获取 `AirPlan/docs/staticanalysis.md`、XML/JSON 报告等静态分析证据和辅助调试文档。 +- 如果静态分析目标在远程设备、测试机、VM、容器宿主机、服务器或 SSH 主机上，调用 AirSDB remote device helper，而不是默认使用本机 cppcheck。 +- 一定要根据项目变化维护 `AirPlan/AGENTS.md`、ADR 和 C4 module。 +- ADR 是给 AI 作为上下文的决策记录，短、准、可检索即可，不写冗长修饰。 + +## 启动与初始化 + +进入 `/airdbg` 时运行： + +```bash +python "$HOME/plugins/airdbg/scripts/airdbg_mode.py" --mode enter --project . +``` + +如果当前环境没有 `python`，尝试 `py` 或 `python3`。脚本不可用时，手动确保以下结构存在： + +- `AirPlan/AGENTS.md` +- `AirPlan/docs/architecture/adr/` +- `AirPlan/docs/architecture/c4/module.md` +- `AirPlan/docs/debug/debug-log.md` +- `AirPlan/state/airdbg/state.json` + +初始化后读取已有内容作为上下文。不要覆盖用户已有正文；只补齐缺失结构或更新 AirDbg 标记块。 + +## 图形调试与 AirXDB 协作 + +AirDbg 负责根因分析、代码层修复和验证收尾；AirXDB 负责图形界面的取证和操作层复现。遇到以下情况时，必须调用 AirXDB 或补充等效 GUI/屏幕证据： + +- 需要截图或图形对比来理解错误现场、视觉回归、布局错位、颜色/尺寸/遮挡差异。 +- 需要操作浏览器 UI、桌面 UI、Electron/Qt/WPF 等应用、Canvas、菜单、弹窗、托盘、任务栏或多显示器界面。 +- 需要 `/airxdb screenshot` 保存错误现场，再把截图交给 AirDbg 做代码层诊断。 +- 目标 GUI 在远程设备、测试机、VM、服务器或 SSH 主机上，需要 `/airxdb remote-screenshot` 或 `airxdb_remote_device.py` 保存远程错误现场。 +- 需要用 AirXDB 执行最小 GUI 操作，确认按钮、表单、导航、窗口切换、焦点或图形流程是否真的失败。 +- 需要把 GUI 证据沉淀到 `AirPlan/docs/debug/gui-debug-log.md`、`AirPlan/docs/debug/airxdb-artifacts/` 或 AirDbg 的 `AirPlan/docs/debug/debug-log.md`。 + +协作规则： + +- 先用 AirXDB 收集最小必要证据，再回到 AirDbg 分析代码根因；不要把视觉症状直接当作根因。 +- 任何本地或远程 GUI 测试/验证都不能仅以进程存活、窗口创建成功、命令返回成功或日志无异常视为通过；默认至少保留 1 份截图/图像证据，并完成 1 次关键 GUI 操作或状态检查。 +- 如果是嵌入式屏幕、显示控制器、外接面板链路等截图无诊断价值的场景，可改用外部采集视频、framebuffer dump、串口/日志配合按键或触控操作记录、状态灯/OSD 观察记录等等效证据，但必须在 `debug-log.md` 记录为什么不截图以及替代证据是什么。 +- 截图模式可在没有 Midscene 语义模型配置时使用；语义视觉动作按 AirXDB 规则先检查模型配置。 +- 本机 GUI 证据使用 `/airxdb screenshot` 或 `airxdb_computer_mcp_smoke.py`；远程 GUI 证据使用 `airxdb_remote_device.py --action setup|screenshot`，由它探测 SSH、远端截图工具并在缺失时自动尝试配置。 +- 远程 helper 缺少 `AIRXDB_REMOTE_SSH_TARGET` 时，先让用户提供 SSH 目标；需要交互式 sudo、管理员确认或无支持包管理器时停止并说明。 +- AirDbg 的 `debug-log.md` 必须记录 AirXDB 命令、截图/报告路径、关键观察、与根因的关系、复验结果和剩余风险。 +- 如果 GUI 自动化、截图取证、视觉验收、浏览器桥接或桌面控制成为长期调试/测试边界，更新 C4 module 并创建或修订 ADR。 +- 如果发现稳定可复用的 GUI 调试命令、截图方式、远程设备配置或视觉验收步骤，更新 `AGENTS.md`。 +- 截图可能包含账号、密钥、客户数据或聊天内容时，先提醒用户脱敏，再外部分享或长期保留。 + +## 抓包调试与 AirNDB 协作 + +AirDbg 负责把网络证据和代码行为联系起来，定位根因并修复；AirNDB 负责 tcpdump/WinDump 抓包、pcap 摘要、BPF 过滤器和网络层证据。遇到以下情况时，调用 AirNDB： + +- 需要抓包判断请求是否发出、响应是否回来、连接是否被 RST/ICMP/防火墙/代理中断。 +- 需要分析 DNS 查询、TCP 三次握手、TLS 握手、HTTP 连接、UDP 流量、端口可达性、重传、丢包或延迟。 +- 需要读取已有 `.pcap` 或生成新的短时有界 pcap 给调试使用。 +- 需要确定问题在应用代码、系统网络栈、容器/WSL/VM/宿主机边界、代理、防火墙还是远端服务。 +- 目标流量发生在远程设备、测试机、VM、容器宿主机、服务器或 SSH 主机上，需要 `/airndb remote-interfaces`、`/airndb remote-capture` 或 `airndb_remote_device.py` 获取远程网络证据。 + +协作规则： + +- 先让 AirNDB 明确授权范围、接口、BPF 过滤器、抓包窗口和 pcap 输出路径；不要进行无界抓包。 +- 本机网络证据使用 `airndb_capture.py`；远程网络证据使用 `airndb_remote_device.py --action setup|interfaces|command|capture`，由它探测 SSH、远端 `tcpdump` / `dumpcap` 并在缺失时自动尝试配置。 +- 远程 helper 缺少 `AIRNDB_REMOTE_SSH_TARGET` 时，先让用户提供 SSH 目标；需要交互式 sudo、管理员确认或无支持包管理器时停止并说明。 +- AirDbg 的 `debug-log.md` 必须记录 AirNDB 命令、pcap/summary/report 路径、关键包或时间线观察、与根因的关系、复验结果和剩余风险。 +- 如果抓包发现新的长期网络边界、端口、协议、DNS、代理、TLS、容器/WSL/VM/宿主机约束或观测方式，更新 C4 module 并创建或修订 ADR。 +- 如果发现稳定可复用的抓包命令、接口选择规则、BPF、远程设备配置或 pcap 读取方式，更新 `AGENTS.md`。 +- pcap 可能包含 token、cookie、payload、内网地址、主机名或个人信息；对外分享前必须提醒用户脱敏。 + +## 静态分析与 AirSDB 协作 + +AirDbg 负责把静态分析线索和代码根因联系起来；AirSDB 负责 cppcheck 检测/安装、本机或远程扫描、XML/JSON 产物和 `AirPlan/docs/staticanalysis.md` 简短报告。遇到以下情况时，可以调用 AirSDB： + +- 需要用 cppcheck 辅助定位 C/C++ bug、内存/资源/越界/空指针/未初始化变量/危险转换/CWE 线索。 +- 需要在修复前后比较静态分析结果。 +- 需要给 AirDbg 的根因分析提供短报告而不是长 XML。 +- 检验、测试或调试判断需要静态分析能力、质量门信息或可引用文档时，需要读取 `AirPlan/docs/staticanalysis.md` 或 AirSDB XML/JSON 报告辅助分析。 +- 目标代码在远程设备、测试机、VM、容器宿主机、服务器或 SSH 主机上，需要 `/airsdb remote-scan` 或 `airsdb_remote_device.py` 获取远端静态分析证据。 + +协作规则： + +- 本机静态分析使用 `airsdb_cppcheck.py --action scan`；远程静态分析使用 `airsdb_remote_device.py --action setup|scan`，由它探测 SSH、远端 cppcheck 并在缺失时自动尝试配置。 +- AirDbg 的 `AirPlan/docs/debug/debug-log.md` 必须记录 AirSDB 命令、`AirPlan/docs/staticanalysis.md`、XML/JSON 报告路径、关键 findings、与根因的关系、复验结果和剩余风险。 +- 如果静态分析发现新的长期质量门槛、suppressions、远程设备配置或 cppcheck 命令，更新 `AGENTS.md`。 +- 如果静态分析成为长期测试/调试边界，更新 C4 module 并创建或修订 ADR。 + +## 调试流程 + +1. 确认问题边界： + - 用户看到的错误是什么。 + - 期望行为和实际行为是什么。 + - 复现步骤、输入数据、环境、版本、最近变更是什么。 + - 有哪些不能破坏的兼容性或性能要求。 +2. 加载上下文： + - 读取 `AGENTS.md`。 + - 读取 ADR 列表和相关 ADR。 + - 读取 `docs/architecture/c4/module.md`。 + - 查看测试、入口、依赖、配置和最近相关文件。 +3. 复现问题： + - 优先运行已有失败测试或用户给出的命令。 + - 没有复现命令时，先构造最小复现或定位性测试。 + - 如果复现依赖 GUI、截图或图形操作，必须调用 AirXDB 获取截图、执行最小界面操作或保存 GUI 报告；远程目标走 AirXDB remote device helper；嵌入式截图无效时改用等效 GUI/屏幕证据并记录原因。 + - 如果复现依赖网络路径或抓包证据，调用 AirNDB 获取短时 pcap、摘要或网络层时间线；远程目标走 AirNDB remote device helper。 +- 如果复现或定位需要 C/C++ 静态分析，或当前检验需要静态分析能力辅助判断，调用 AirSDB 运行本机或远程 cppcheck，并读取 `AirPlan/docs/staticanalysis.md`。 + - 记录复现命令和关键输出到 `docs/debug/debug-log.md`。 +4. 定位根因： + - 从错误栈、日志、测试断言、数据流和模块边界推断。 + - 对 GUI 问题，结合 AirXDB 本机或远程截图/报告判断视觉症状、交互失败和代码根因之间的关系。 + - 对网络问题，结合 AirNDB 本机或远程 pcap/摘要判断请求是否出站、响应是否入站、失败发生在 DNS/TCP/TLS/应用层哪一段。 + - 对静态分析问题，结合 AirSDB findings 判断哪些是当前 bug 线索、哪些是既有质量债或误报。 + - 必要时加临时日志或小范围探针，完成后清理。 + - 区分根因、诱因和表面症状。 +5. 修复： + - 优先选择影响面小、能解释根因的修复。 + - 不做无关格式化、批量重构或架构迁移。 + - 如果修复会改变模块边界、依赖、接口、数据所有权或关键行为，先更新 C4/ADR。 +6. 验证： + - 运行失败用例、相关单元测试、集成测试、lint/typecheck。 + - 如果修复涉及 GUI 或视觉行为，必须调用 AirXDB 截图、图形对比或操作验证关键路径；远程目标用远程 helper 复验；嵌入式截图无效时改用等效 GUI/屏幕证据并记录原因。 + - 如果修复涉及网络行为，调用 AirNDB 复验关键网络路径或读取 pcap 摘要；远程目标用远程 helper 复验。 +- 如果修复涉及 C/C++ 风险、静态分析 findings，或验证需要静态分析能力辅助判断，调用 AirSDB 复跑 cppcheck 并更新 `AirPlan/docs/staticanalysis.md`。 + - 如果不能运行，说明原因，并给出可复验的替代验证。 + - 记录验证证据到 debug log。 +7. 收尾： + - 更新 `AGENTS.md` 中与调试、测试、运行方式相关的项目上下文。 + - 更新或新增 ADR。 + - 更新 C4 module。 + - 向用户汇报根因、改动、验证结果、剩余风险。 + +## AGENTS.md 维护 + +在以下情况更新 `AGENTS.md`： + +- 发现新的运行、测试、构建、调试命令。 +- 发现新的 AirXDB 截图、GUI 操作验证、图形对比、远程设备配置或视觉验收命令。 +- 发现新的 AirNDB 抓包命令、BPF 过滤器、接口选择规则、远程设备配置、pcap 读取方式或网络复验步骤。 +- 发现新的 AirSDB cppcheck 命令、suppressions、质量门槛、远程设备配置或静态分析复验步骤。 +- 发现影响后续 AI 会话的重要项目约束。 +- 修复改变了模块职责、关键流程或错误处理策略。 +- 发现常见坑、环境要求或验证方式。 + +保持内容可执行、可复用，不写调试过程流水账。 + +## ADR 维护 + +目录：`docs/architecture/adr/`。 + +需要 ADR 的情况： + +- 修复选择了一个会影响长期架构或行为兼容性的方案。 +- 改变错误处理、重试、事务、缓存、一致性、安全边界。 +- 改变模块依赖、数据所有权、接口契约。 +- 将 GUI 自动化、截图取证、远程设备 GUI 取证、视觉验收或图形调试流程纳入长期测试/调试边界。 +- 将抓包、远程设备抓包、pcap 分析、网络观测、端口、协议、DNS、代理、TLS 或网络拓扑纳入长期调试/测试边界。 +- 将 cppcheck、staticanalysis.md、静态分析质量门槛或远程静态分析纳入长期调试/测试边界。 +- 拒绝了明显可选方案，需要给后续 AI 留下原因。 + +ADR 模板： + +```markdown +# ADR-000X: short-title + +- Status: Accepted +- Date: YYYY-MM-DD + +## Context +简述错误、约束和为什么需要决策。 + +## Decision +简述采用的修复或架构选择。 + +## Consequences +- 正面影响 +- 代价或风险 + +## Alternatives +- 方案 A：放弃原因 +``` + +## C4 Module 维护 + +文件：`docs/architecture/c4/module.md`。 + +必须记录： + +- 模块名。 +- 职责。 +- 对外接口。 +- 依赖。 +- 数据所有权。 +- 与本次错误或修复相关的质量属性。 + +新增模块、拆分模块、改变依赖、改变接口、改变数据边界、改变错误处理流时必须更新。 + +引入或改变 GUI 自动化、浏览器桥接、桌面控制、截图取证、远程设备 GUI 取证、视觉验收或图形调试基础设施时，也必须更新。 + +引入或改变 tcpdump/WinDump 抓包、远程设备抓包、pcap 分析、网络观测、端口、协议、DNS、代理、TLS、容器/WSL/VM/宿主机网络边界时，也必须更新。 + +引入或改变 cppcheck、staticanalysis.md、静态分析质量门槛、suppressions 或远程静态分析边界时，也必须更新。 + +## debug-log 维护 + +文件：`docs/debug/debug-log.md`。 + +每次 AirDbg 修复至少追加： + +- 问题摘要。 +- 复现命令或复现步骤。 +- 根因。 +- 修复摘要。 +- 验证命令和结果。 +- AirXDB 本机或远程截图/报告/操作验证证据及其结论（如适用）。 +- AirNDB 本机或远程 pcap/summary/report/抓包分析证据及其结论（如适用）。 +- AirSDB 本机或远程 staticanalysis.md/XML/JSON 静态分析证据及其结论（如适用）。 +- 相关 ADR/C4 更新。 +- 剩余风险。 + +## 输出格式 + +调试完成后用中文简洁汇报： + +- 根因。 +- 修复了什么。 +- 更新了哪些 `AGENTS.md` / ADR / C4 / debug log 上下文。 +- 运行了哪些验证；是否调用 AirXDB/AirNDB/AirSDB，截图、pcap、staticanalysis、报告或操作证据在哪里。 +- 仍然存在的风险或未验证项。 diff --git a/skills/airdbg/agents/openai.yaml b/skills/airdbg/agents/openai.yaml new file mode 100644 index 0000000..95da337 --- /dev/null +++ b/skills/airdbg/agents/openai.yaml @@ -0,0 +1,3 @@ +name: airdbg +short_description: Debug-first repair with local/remote AirXDB, AirNDB, and AirSDB evidence +default_prompt: "使用 AirDbg 调试并修复当前项目错误；GUI 测试或验证必须保留 GUI 复验证据，嵌入式截图无效时改用等效屏幕证据；网络证据调用 AirNDB，需要静态分析能力时调用 AirSDB。"