If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/Mrs4s/go-cqhttp shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 5w ago
• 30+ active contributors
• Distributed ownership (top contributor 32% of recent commits)
• AGPL-3.0 licensed
• CI configured
• Tests present
• ⚠ AGPL-3.0 is copyleft — check downstream compatibility

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live Mrs4s/go-cqhttp repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/Mrs4s/go-cqhttp.

What it runs against: a local clone of Mrs4s/go-cqhttp — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in Mrs4s/go-cqhttp | Confirms the artifact applies here, not a fork | | 2 | License is still AGPL-3.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 68 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of Mrs4s/go-cqhttp. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/Mrs4s/go-cqhttp.git
#   cd go-cqhttp
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of Mrs4s/go-cqhttp and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "Mrs4s/go-cqhttp(\\.git)?\\b" \\
  && ok "origin remote is Mrs4s/go-cqhttp" \\
  || miss "origin remote is not Mrs4s/go-cqhttp (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(AGPL-3\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"AGPL-3\\.0\"" package.json 2>/dev/null) \\
  && ok "license is AGPL-3.0" \\
  || miss "license drift — was AGPL-3.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "main.go" \\
  && ok "main.go" \\
  || miss "missing critical file: main.go"
test -f "cmd/gocq/main.go" \\
  && ok "cmd/gocq/main.go" \\
  || miss "missing critical file: cmd/gocq/main.go"
test -f "coolq/bot.go" \\
  && ok "coolq/bot.go" \\
  || miss "missing critical file: coolq/bot.go"
test -f "modules/api/api.go" \\
  && ok "modules/api/api.go" \\
  || miss "missing critical file: modules/api/api.go"
test -f "modules/config/config.go" \\
  && ok "modules/config/config.go" \\
  || miss "missing critical file: modules/config/config.go"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 68 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~38d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/Mrs4s/go-cqhttp"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

go-cqhttp is a native Go implementation of the OneBot-v11 protocol for QQ bot development, built on MiraiGo library. It provides HTTP API, WebSocket (forward/reverse), and reverse HTTP POST interfaces to interact with QQ programmatically without needing the official QQ client, supporting CQ code parsing, message handling, and group management. Monolithic Go binary structure: cmd/gocq/ contains the main entry point and login logic; coolq/ is the core API handler (api.go, api_v12.go, bot.go, converter.go); db/ provides abstraction over LevelDB, MongoDB, and SQLite3 backends; db/leveldb/ implements the primary persistent storage layer. Message handling flows through CQCode parsing in cqcode.go and routed via HTTP/WebSocket transports.

QQ bot developers and automation engineers who want to build chat bots and automated tools for QQ (the Chinese messaging platform) using Go, without dealing with QQ's proprietary binary protocol directly—they use go-cqhttp as a middleware bridge to QQ's network.

Project is actively abandoned as of late 2023. The repo has commits through August 2023 (MiraiGo dependency pinned to that date), CI/CD workflows are configured (GitHub Actions for release, lint, Docker builds), but the README explicitly states 'Due to QQ official's continuous encryption updates, we are no longer able to maintain this project' and recommends migration to NTQQ. High test coverage suggests maturity at sunset, but protocol incompatibility now makes it non-functional.

Critical risk: The project is unmaintained and explicitly non-functional against current QQ protocol versions due to ongoing encryption changes by Tencent. Dependency on MiraiGo (a separate protocol library also facing similar pressure) creates cascading obsolescence. Single maintainer (Mrs4s) with no active succession planning. Using this in production would require forking and maintaining protocol implementation—a significant undertaking given QQ's adversarial approach to bot libraries.

Project is in maintenance-mode limbo: last meaningful commits are from August 2023 (dependency updates). Open issues likely include protocol breakage reports. GitHub Workflows exist for automated releases and Docker image builds but no active development. The pinned recommendation to migrate to go-cqhttp/issues/2471 (NTQQ-based successor) indicates community shift.

git clone https://github.com/Mrs4s/go-cqhttp.git
cd go-cqhttp
go mod download
go build -o go-cqhttp ./cmd/gocq
./go-cqhttp

(Requires Go 1.20+; will prompt for QQ credentials and generate config.yml on first run.)

Daily commands:

go build -o go-cqhttp ./cmd/gocq
./go-cqhttp

First run creates config.yml with QQ login, HTTP/WebSocket listener config, and database backend selection. Daemon mode can be enabled via config. No dev server—it runs as a standalone bot bridge daemon.

• main.go — Application entry point that initializes the QQ bot framework and orchestrates startup
• cmd/gocq/main.go — CLI entry point for the go-cqhttp executable; handles login, configuration, and daemon initialization
• coolq/bot.go — Core bot abstraction wrapping MiraiGo; manages QQ session, event handlers, and message routing
• modules/api/api.go — OneBot API server implementation; exposes HTTP/WebSocket endpoints for third-party integrations
• modules/config/config.go — Configuration management; defines and loads settings for bot behavior, API servers, and database backends
• coolq/event.go — Event parsing and marshaling; converts QQ protocol events into OneBot-compliant JSON structures
• internal/msg/parse.go — CQ code parser; converts between OneBot message format and native QQ message elements

Add a new OneBot API endpoint

1. Define the API method signature in coolq/api.go (coolq/api.go)
2. Implement business logic using MiraiGo client methods (coolq/api.go)
3. Register the method in modules/api/caller.go's dispatch switch (modules/api/caller.go)
4. Test via HTTP POST to /api/{method_name} with JSON body (modules/api/api.go)

Add support for a new message element type

1. Define the element struct in internal/msg/element.go (internal/msg/element.go)
2. Add CQ code parsing/encoding in internal/msg/parse.go (internal/msg/parse.go)
3. Add MiraiGo conversion in coolq/converter.go (coolq/converter.go)
4. Write parser test in internal/msg/parse_test.go (internal/msg/parse_test.go)

Add a new configuration option

1. Add field to Config struct in modules/config/config.go (modules/config/config.go)
2. Add YAML example to modules/config/default_config.yml (modules/config/default_config.yml)
3. Use config.XXX in relevant handler (api.go, bot.go, etc.) (modules/config/config.go)
4. Document in docs/config.md (docs/config.md)

Add a new database backend

1. Implement db.Database interface methods in new db/mydb/mydb.go (db/database.go)
2. Register backend in db/multidb.go NewDatabase switch (db/multidb.go)
3. Add config option in modules/config/config.go (modules/config/config.go)
4. Update default_config.yml with backend example (modules/config/default_config.yml)

• MiraiGo (Go QQ protocol library) — Provides native QQ protocol implementation without CoolQ (unsupported) dependency; enables lightweight cross-platform deployment
• OneBot v11 API standard — Achieves plugin/bot framework interoperability; allows code reuse from CoolQ ecosystem
• LevelDB, SQLite3, MongoDB (pluggable) — Supports embedded deployments (LevelDB/SQLite) and distributed setups (MongoDB); abstracts storage via interface
• Logrus + log rotation — Structured logging with configurable output; file rotation prevents unbounded disk growth in 24/7 deployments
• WebSocket + HTTP dual-mode API — HTTP for stateless request-response; WebSocket for event push and real-time state; supports both client patterns

• MiraiGo as single QQ protocol implementation (no CoolQ fallback)

  • Why: Eliminates heavyweight Windows runtime dependency; simplifies deployment and reduces attack surface
  • Consequence: Breaks for users on unsupported device types; protocol changes require MiraiGo updates not owned by this project

• Pluggable database backends instead of single embedded DB

  • Why: Supports both lightweight single-instance (LevelDB) and clustered deployments (MongoDB)
  • Consequence: Adds abstraction complexity and test burden; each backend must implement full interface

• Message-level caching in memory (cache.go) rather than persistent cache layer

  • Why: Reduces operational complexity; sufficient for majority of bots that handle <100k messages/day
  • Consequence: Loses cache on restart; does not scale for high-throughput aggregators

• CQ code string encoding as wire format (not binary protobuf)

  • Why: Human-readable for debugging; compatible with CoolQ ecosystem tools and documentation
  • Consequence: String parsing overhead (~2–3% CPU); larger payloads vs. binary encoding

• Does not implement QQ client GUI; headless bot framework only
• Does not support QQ voice calls or video streams (protocol limitation in MiraiGo)

Critical: The project is non-functional on current QQ servers due to encryption protocol changes. Device lock: First login may require QR code scan or security verification; device.json is persisted to avoid repeated locks. Database default: LevelDB is default; switching to MongoDB/SQLite3 requires manual config changes in config.yml (db section). CQ code escaping: CQ codes must be properly escaped in JSON; raw ampersands will break parsing. No hot-reload: Changes to config.yml require daemon restart. HTTP API concurrency: The HTTP API handler is synchronous per endpoint—high request volume may block. MiraiGo dependency: Core protocol logic is in the MiraiGo package (imported, not in this repo); any protocol fix requires forking MiraiGo.

• OneBot Protocol (v11) — go-cqhttp's entire API surface and event schema are defined by OneBot v11 spec; understanding this standard is essential to know what endpoints exist and how events are structured
• CQ Code (CQHTTP Markup Language) — Messages in go-cqhttp are transmitted as CQ code (e.g., [CQ:image,file=...] [CQ:face,id=123])—parsing and generating CQ codes correctly is critical for image, mention, and reply features
• Reverse Proxy / Reverse WebSocket — go-cqhttp can push events to your bot server (reverse HTTP POST, reverse WS) rather than only accepting pull requests—this is the recommended pattern for low-latency bots and avoids polling
• QQ Protocol Encryption & Device Lock — go-cqhttp must authenticate with QQ's proprietary, constantly-evolving encryption protocol; device.json and token caching prevent re-authentication, but protocol updates break compatibility—this is why the project is unmaintained
• LevelDB Sorted Key-Value Store — go-cqhttp uses LevelDB by default for message history and user cache; it's an embedded database (not client-server), making deployment simple but limiting horizontal scaling
• WebSocket Multiplexing (Forward & Reverse) — go-cqhttp supports both forward (bot polls via WS) and reverse (go-cqhttp pushes via WS) WebSocket modes; multiplexing events to multiple subscribers is handled in the transport layer
• Message Receipt Deduplication — QQ may deliver the same message multiple times due to retries; go-cqhttp must deduplicate via message ID to avoid duplicate bot responses, handled in the event processing layer

• Mrs4s/MiraiGo — The underlying QQ protocol client library that go-cqhttp wraps; any protocol-level bug fixes or features must be contributed here first
• howmanybots/onebot-11 — The OneBot v11 standard specification that go-cqhttp implements; defines the API contract and event schema
• botuniverse/onebot — Umbrella organization for OneBot standard; hosts v12+ spec and ecosystem tools; go-cqhttp is v11-only
• mamoe/mirai — Original Java Mirai project that inspired MiraiGo and go-cqhttp; provides context on the broader QQ bot ecosystem and protocol understanding
• nonebot/nonebot2 — Popular Python OneBot framework; many bot developers use go-cqhttp as the backend for NoneBot2-based bots

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for coolq/cqcode.go CQCode parser

The cqcode.go file handles parsing of CQ codes (special message format used in QQ), which is critical functionality. Currently, global/all_test.go exists but there's no dedicated test file for the CQCode parsing logic. This should include edge cases like nested codes, malformed input, and various CQ code types (image, at, share, etc.) mentioned in coolq/api.go

• [ ] Create coolq/cqcode_test.go with tests for CQCode parsing functions
• [ ] Add test cases for each CQ code type (image, at, share, contact, etc.)
• [ ] Include edge cases: empty codes, nested codes, special characters, malformed input
• [ ] Verify roundtrip conversion (CQCode → string → CQCode) preserves data
• [ ] Run coverage analysis to ensure >80% coverage of cqcode.go

Add database abstraction layer tests for db/multidb.go

The repo supports multiple database backends (SQLite3, MongoDB, LevelDB) via db/multidb.go, but there are no tests verifying that all backends implement consistent behavior. This is critical for users switching between database types, as bugs in one backend could go unnoticed.

• [ ] Create db/multidb_test.go with interface compliance tests
• [ ] Add test suite that runs identical test cases against all three backend implementations (sqlite3, mongodb, leveldb)
• [ ] Test critical operations: save message, query message, delete record, transaction handling
• [ ] Verify error handling consistency across backends
• [ ] Add integration tests with actual database instances using Docker containers

Add GitHub Actions workflow for cross-platform binary compatibility testing

The repo claims native cross-platform support (Linux, Windows, macOS) but the ci.yml workflow only shows basic Go tests. There's no verification that binaries actually build and run on each platform. Given the platform-specific code in global/signal_*.go and global/terminal/quick_edit_windows.go, this is essential.

• [ ] Review existing .github/workflows/ci.yml and .github/workflows/release.yml
• [ ] Create .github/workflows/cross-platform-test.yml that builds binaries on ubuntu-latest, windows-latest, and macos-latest
• [ ] Add smoke tests in cmd/gocq/main.go that verify platform-specific functionality (signal handling, terminal detection)
• [ ] Test with go build for all three platforms to catch platform-specific compilation errors early
• [ ] Document results in docs/CONTRIBUTING.md or similar

• Add unit tests for coolq/cqcode.go parsing edge cases (nested brackets, special characters, escaped ampersands)—currently minimal test coverage and users report CQ code parsing bugs
• Implement reverse HTTP client retry logic with exponential backoff in the HTTP POST transport (cmd/gocq or main transport layer)—currently missing, causing event loss if webhook is temporarily unavailable
• Document the database migration path in docs/config.md for switching from LevelDB to SQLite3 or MongoDB with data preservation steps—currently undocumented, users lose message history on backend switch

• High · Outdated Go Version in Docker Build — Dockerfile, line 1. The Dockerfile uses Go 1.20 which is outdated. Go 1.20 reached end-of-life on August 8, 2024. Using outdated Go versions exposes the application to known security vulnerabilities in the Go runtime and standard library that will not receive patches. Fix: Update to the latest stable Go version (1.22 or later). Modify 'FROM golang:1.20-alpine AS builder' to 'FROM golang:1.22-alpine AS builder' and update go.mod to 'go 1.22'.
• High · Missing Input Validation in CQCode Parser — coolq/cqcode.go. The file 'coolq/cqcode.go' likely processes CQ codes which are user-controlled input. Without visible input validation patterns in the file structure, there is a risk of injection attacks through specially crafted CQ code payloads that could lead to unintended behavior or command execution. Fix: Implement strict input validation and sanitization for all CQ code parsing. Use whitelisting approach for allowed CQ code types and parameters. Validate parameter values against expected formats and ranges.
• High · Potential SQL Injection in Database Layers — db/sqlite3/, db/leveldb/, db/mongodb/. Multiple database implementations are present (SQLite3, MongoDB, LevelDB) without visible parameterized query enforcement in the file structure. The 'db/sqlite3/sqlite3.go' and 'db/leveldb/writer.go' files handle data persistence and may be vulnerable to SQL injection if query construction is not parameterized. Fix: Ensure all database queries use parameterized statements or prepared statements. Implement ORM or query builder patterns that prevent SQL injection. Never concatenate user input into query strings.
• High · Insecure Credential Handling in Login Module — cmd/gocq/login.go. The file 'cmd/gocq/login.go' likely handles authentication credentials. Without visible encryption or secure credential storage patterns, login credentials may be stored in plaintext or logged insecurely, exposing sensitive authentication information. Fix: Implement secure credential storage using encryption at rest. Use Go's crypto packages for sensitive data. Never log credentials or authentication tokens. Implement secure memory handling to prevent credential exposure through memory dumps.
• Medium · Missing HTTPS Enforcement in WebSocket Communication — global/net.go, coolq/bot.go. The codebase uses 'RomiChan/websocket' dependency for communication but there is no visible enforcement of secure WebSocket (WSS) connections. This could allow man-in-the-middle attacks on the communication channel. Fix: Enforce WSS (WebSocket Secure) for all WebSocket connections. Implement certificate validation and HTTPS enforcement in network communication. Document security requirements for deployment.
• Medium · Insufficient Access Control in Docker Container — Dockerfile, docker-entrypoint.sh. The Dockerfile creates a non-root user 'abc' but runs the entrypoint script as root initially. The 'su-exec' usage in 'docker-entrypoint.sh' may have privilege escalation risks if not properly configured. The UID/GID environment variables could be bypassed. Fix: Run the container as non-root from the start. Use 'USER abc' directive in Dockerfile. Validate and sanitize UID/GID environment variables in the entrypoint script. Remove su-exec if possible in favor of direct unprivileged execution.
• Medium · Outdated Alpine Base Image — Dockerfile, line 11. The Dockerfile uses 'alpine:latest' which is a moving target and may pull images with unpatched vulnerabilities. Using 'latest' tag makes builds non-reproducible and unpredictable from a security standpoint. Fix: Pin the Alpine version to a specific stable version (e.g., 'alpine:3.19'). Regularly update to latest patch versions. Use specific version tags instead of 'latest' for reproducible builds.
• Medium · Potential YAML Deserialization Vulnerability — undefined. The codebase uses 'gopkg.in/yaml.v3' for configuration parsing. If YAML files are processed Fix: undefined

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.