From 6d7a42607ab2e753812933842e9a89e71985c6dc Mon Sep 17 00:00:00 2001 From: vcaesar Date: Fri, 17 Apr 2026 14:21:33 -0700 Subject: [PATCH] Add: add agents.md for code Agent --- AGENTS.md | 101 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 2 +- 2 files changed, 102 insertions(+), 1 deletion(-) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..acaa61b --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,101 @@ +# RobotGo + +Go native cross-platform desktop automation: mouse, keyboard, screen, bitmap, process, window handle, clipboard, and global event listener. Supports macOS, Windows, Linux (X11); amd64 and arm64. + +Module: `github.com/go-vgo/robotgo` — Go 1.24 (CI pins Go 1.25 / 1.26). + +## Build/Test/Lint Commands + +Prerequisites: `GCC` must be installed. `CGO_ENABLED=1` (default). On macOS, Xcode Command Line Tools + Accessibility/Screen Recording permissions. On Linux, X11 + XTest (`libx11-dev xorg-dev libxtst-dev`). + +- **Build**: `go build -v .` +- **Build all subpackages**: `go build -v ./...` +- **Fetch deps**: `go get -v -t -d ./...` +- **Test (CI minimal — no display required)**: `go test -v robot_info_test.go` +- **Test (full)**: `go test -v ./...` (Linux CI wraps with `xvfb-run` — see `.circleci/config.yml`) +- **Single test**: `go test -v -run TestGetScreenSize .` +- **Format**: `gofmt -w .` (code uses tab indentation, standard `gofmt` style) +- **Vet**: `go vet ./...` +- **Run an example**: `cd examples/mouse && go run main.go` + +There is no Makefile / Taskfile / linter config. CI is `.github/workflows/go.yml` (macOS + Windows: `go test -v robot_info_test.go` only), `.circleci/config.yml` (Linux full tests under xvfb), `appveyor.yml` (Windows MinGW). + +## Architecture + +Single Go package `robotgo` at repo root (flat layout) with platform-specific files and C-binding subpackages. Most features are Cgo wrappers over C headers vendored in subdirectories; build tags split platform implementations. + +``` +robotgo/ +├── robotgo.go # main API + Cgo preamble (darwin/linux/windows LDFLAGS) +├── robotgo_mac.go # //go:build darwin +├── robotgo_mac_unix.go # //go:build darwin || linux +├── robotgo_mac_win.go # //go:build darwin || windows +├── robotgo_win.go # //go:build windows +├── robotgo_x11.go # //go:build linux (X11) +├── robotgo_android.go, robotgo_adb.go +├── wayland_n.go, windows_n.go +├── key.go, keycode.go, screen.go, img.go, ps.go +├── robotgo_fn_v1.go # deprecated v1 aliases (kept for compat) +├── robot_info_test.go # only portable test (used by CI) +├── robotgo_test.go # full interactive tests +├── base/ # C helpers (MMBitmap, rgb, microsleep, types, xdisplay) +├── mouse/ # Go pkg + C (mouse.h, mouse_c.h) with *_darwin.go/_windows.go/_x11.go +├── key/ # Go pkg + C (keycode.h, keypress_c.h) +├── screen/ # Go pkg + C (goScreen.h, screengrab_c.h) +├── window/ # Go pkg + C (goWindow.h, window.h, alert_c.h, win_sys.h, pub.h) +├── clipboard/ # Go pkg (darwin/unix/windows variants) + cmd/gocopy, cmd/gopaste +├── event/ # C headers for android / ios +├── cv/ # OpenCV helper (gocv.go) +├── examples/ # mouse, key, screen, window, scale — runnable main.go +├── docs/ # install.md, keys.md, CHANGELOG.md +└── .github/workflows/go.yml, .circleci/config.yml, appveyor.yml +``` + +Key subpackage relationships: the root `robotgo` package pulls C code from `screen/goScreen.h`, `mouse/mouse_c.h`, `window/goWindow.h`. The `key/` and `clipboard/` directories are importable Go packages; `base/` is header-only C support. + +## Code Style + +- **Copyright header**: every Go and C file starts with the 10-line `Copyright (c) 2016-2025 AtomAI...` block (see `CONTRIBUTING.md`). Preserve it verbatim when editing; add a second header only if authorship changes. +- **Indentation**: tabs (Go default). Run `gofmt` before committing. +- **Build tags**: use both forms together — `//go:build darwin` plus legacy `// +build darwin` — matching existing files. +- **Cgo**: `import "C"` immediately follows a `/* ... */` comment block containing `#cgo` directives and `#include`s. Keep LDFLAGS per-OS (`#cgo darwin LDFLAGS`, `#cgo linux LDFLAGS`, `#cgo windows LDFLAGS`). +- **Naming**: exported `CamelCase`; key constants prefixed `Key` (e.g. `KeyA`, `KeyEnter`); C-type aliases prefixed `C` (`CBitmap`, `CHex`). Mirror existing patterns. +- **Imports**: stdlib first, blank line, then third-party (`github.com/...`). Internal subpackage imported as `github.com/go-vgo/robotgo/clipboard` (full module path, not relative). +- **Comments**: godoc-style `// FuncName does X` on every exported symbol. Package doc lives in `doc.go` / top of `robotgo.go`. +- **Error handling**: return `error` as last result; use `errors.New` / `fmt.Errorf`. `Try(fn, handler)` helper wraps panics via `recover`. Do not swallow errors. +- **Types**: existing code uses `interface{}` (pre-generics) — match local style when editing that file, but prefer `any` in new code. Do not mass-rewrite; gopls emits hints, not errors. + +## Testing + +- Framework: stdlib `testing` + `github.com/vcaesar/tt` (`tt.Expect(t, want, got)`). +- Test files: `*_test.go` beside sources. Package declared as `robotgo_test` (external) for API-surface tests, or `robotgo` for internal. +- **Portable tests** live in `robot_info_test.go` — the only file exercised by GitHub Actions. Keep new tests here if they must run headless on macOS/Windows CI. +- **Interactive / display-required tests** go in `robotgo_test.go` and run only under CircleCI's `xvfb-run go test -v ./...`. +- Run one test: `go test -v -run TestGetScreenSize .` +- No fixtures, snapshots, or golden files in use. Screenshots produced by examples are `.gitignore`d. + +## Key Patterns + +- **Cgo + platform split is mandatory**. Any new OS-specific function must be gated by `//go:build` tags and have implementations (even stub) for darwin, linux, windows — examine `mouse/mouse_darwin.go`, `mouse_windows.go`, `mouse_x11.go` as the template. +- **Free C-allocated bitmaps**: every `CaptureScreen`, `ToCBitmap`, etc. must be paired with `defer robotgo.FreeBitmap(bit)` or `robotgo.FreeBitmapArr(...)`. Leaking is a memory bug on all platforms. +- **Global tunables** are package-level vars, not config structs: `MouseSleep`, `KeySleep`, `DisplayID`, `NotPid`, `Scale`. Callers mutate them directly (see README examples). Do not hide them behind getters. +- **`robotgo_fn_v1.go`** contains deprecated v1 aliases — do not add new APIs there, but do not delete existing ones (backwards compatibility). +- **Version string** lives in `robotgo.go` as `const Version = "v1.00.0.1189, MT. Baker!"`. Bump it when releasing; `TestGetVer` asserts it matches `GetVersion()`. +- **Windows pid vs hwnd**: set `robotgo.NotPid = true` to pass window handles instead of pids into the window/key APIs on Windows. +- **macOS permissions**: most screen/input APIs silently fail without Accessibility + Screen Recording grants. When reproducing bugs on darwin, verify System Settings → Privacy & Security first. +- **Do not vendor**: `vendor/` is in `.gitignore`; also avoid `go mod vendor` (upstream note in README references golang/go#26366). +- **C artifacts** (`*.cgo1.go`, `*.cgo2.c`, `_cgo_*`, `*.o`, `*.a` except whitelisted `cdeps/...` libpng archives) are git-ignored — do not commit them. +- **Commit sign-off** is expected (see `CONTRIBUTING.md`); PRs require ≥2 maintainer review (LGTM). + +## Dependencies + +- `github.com/jezek/xgb`, `github.com/jezek/xgbutil` — X11 protocol on Linux. +- `github.com/tailscale/win`, `github.com/dblohm7/wingoes`, `github.com/yusufpapurcu/wmi`, `github.com/go-ole/go-ole` — Windows system APIs. +- `github.com/vcaesar/keycode` — cross-platform keycode mapping (used by `key/`). +- `github.com/vcaesar/imgo`, `golang.org/x/image` — image encode/decode (PNG/JPEG save). +- `github.com/vcaesar/screenshot` — screenshot backend. +- `github.com/vcaesar/gops`, `github.com/shirou/gopsutil/v4` — process enumeration (`FindIds`, `PidExists`, `Kill`). +- `github.com/vcaesar/tt` — testing assertions. +- `github.com/otiai10/gosseract/v2` — OCR (used by `robotgo_ocr.go`; needs `libtesseract`). +- `github.com/godbus/dbus/v5` — used on Linux for Wayland/desktop ops. +- Companion repos (not in `go.mod`, referenced in README/examples): `github.com/vcaesar/bitmap`, `github.com/vcaesar/gcv` (OpenCV), `github.com/jezek/gohook` (global event hook). diff --git a/README.md b/README.md index 2bb3a2b..3d8d14d 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,7 @@ RobotGo supports Mac, Windows, and Linux (X11); and robotgo supports arm64 and x86-amd64. -I build [Codg](https://github.com/vcaesar/codg) now, Easy code and work AI agent system: auto, asynchronous, concurrency, efficiently +I build [Codg](https://github.com/vcaesar/codg) now, Easy code and work AI agent system: auto, asynchronous, concurrency, efficiently and High accuracy