mirror of
https://github.com/go-vgo/robotgo
synced 2026-05-23 09:48:59 +00:00
Add: add agents.md for code Agent
This commit is contained in:
vcaesar
parent
f63a266c5f
commit
6d7a42607a
2 changed files with 102 additions and 1 deletions
101
AGENTS.md
Normal file
101
AGENTS.md
Normal file
|
|
@ -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).
|
||||
|
|
@ -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
|
||||
|
||||
<p align="center">
|
||||
<a href="https://github.com/vcaesar/codg" rel="nofollow">
|
||||
|
|
|
|||
Loading…
Reference in a new issue