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/MatsuriDayo/nekoray 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.

WAIT — Stale — last commit 1y ago

• 20 active contributors
• Distributed ownership (top contributor 49% of recent commits)
• GPL-3.0 licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 1y ago
• ⚠ GPL-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 MatsuriDayo/nekoray repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/MatsuriDayo/nekoray.

What it runs against: a local clone of MatsuriDayo/nekoray — 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 MatsuriDayo/nekoray | Confirms the artifact applies here, not a fork | | 2 | License is still GPL-3.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 543 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of MatsuriDayo/nekoray. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/MatsuriDayo/nekoray.git
#   cd nekoray
#
# 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 MatsuriDayo/nekoray and re-run."
  exit 2
fi

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

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

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

# 4. Critical files exist
test -f "CMakeLists.txt" \\
  && ok "CMakeLists.txt" \\
  || miss "missing critical file: CMakeLists.txt"
test -f "db/Database.hpp" \\
  && ok "db/Database.hpp" \\
  || miss "missing critical file: db/Database.hpp"
test -f "fmt/AbstractBean.hpp" \\
  && ok "fmt/AbstractBean.hpp" \\
  || miss "missing critical file: fmt/AbstractBean.hpp"
test -f "go/cmd/nekobox_core/main.go" \\
  && ok "go/cmd/nekobox_core/main.go" \\
  || miss "missing critical file: go/cmd/nekobox_core/main.go"
test -f "db/ConfigBuilder.hpp" \\
  && ok "db/ConfigBuilder.hpp" \\
  || miss "missing critical file: db/ConfigBuilder.hpp"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 543 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~513d)"
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/MatsuriDayo/nekoray"
  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).

Nekoray is a Qt-based cross-platform GUI proxy configuration manager that wraps sing-box as its backend, allowing users to configure and manage proxy connections (SOCKS, HTTP, Shadowsocks, VMess, VLESS, Trojan, TUIC, etc.) across Windows and Linux with a single unified interface. It supports subscription management, custom outbounds, and custom cores with configuration in JSON format. Hybrid C++/Go monorepo: core GUI built in Qt/C++ (src/main likely, using CMake build system), backend logic delegates to sing-box (Go module in nekobox_core/), gRPC services (grpc_server module) bridge them, and 3rdparty/ contains vendored dependencies from Qv2ray and utility libraries (QJsonModel, QThreadCreateThread, base64, QR code gen). Configuration is JSON-based, parsed via protobuf where needed.

End users and network administrators on Windows/Linux who need a desktop GUI to manage multiple proxy protocols and subscriptions without command-line configuration; also relevant to developers familiar with Qt and Go who want to contribute to proxy tooling.

Abandoned/Unmaintained — the README explicitly states '不再维护，自寻替代品' (no longer maintained, find alternatives). While it has GitHub workflows for CI/CD builds and appears to have had active development (436KB of C++), there are no recent commits visible in the provided metadata, making it unsuitable for new production deployments.

Critical risk: the project is explicitly unmaintained and the maintainer recommends finding alternatives. The dependency chain is complex (sing-box ecosystem with gRPC, protobuf, and numerous Go packages), and the codebase mixes three languages (C++, Go, CMake), increasing maintenance burden. Single-maintainer risk (MatsuriDayo) with no visible fork adoption or community takeover.

Active development appears halted — the repository is explicitly marked as unmaintained. Historical CI pipelines (build-nekoray-cmake.yml, update-pkgbuild.yml) exist but no recent activity is evident from the file listing. Last known supported version shipped with sing-box backend and Xray-core integration.

git clone https://github.com/MatsuriDayo/nekoray.git
cd nekoray
git submodule update --init --recursive
mkdir build && cd build
cmake ..
make -j$(nproc)

Requires: Qt 5/6 SDK, CMake 3.16+, Go 1.19+, and C++ compiler. See docs/Compile_*.md for platform-specific steps.

Daily commands: After building with CMake: ./nekoray (or ./nekoray --options per docs/RunFlags.md). The binary expects sing-box core and config files in standard locations (~/.config/nekoray/ on Linux, %APPDATA%/nekoray/ on Windows).

• CMakeLists.txt — Root build configuration; defines all project targets, dependencies, platform-specific builds, and compiler settings for Qt/C++ and Go components.
• db/Database.hpp — Core database abstraction managing profiles, groups, and configuration state; all UI and backend operations depend on this schema.
• fmt/AbstractBean.hpp — Base class for all proxy protocol beans (SOCKS, Trojan, VMess, etc.); essential for serialization and protocol handling across the app.
• go/cmd/nekobox_core/main.go — Entry point for the sing-box backend; bridges gRPC calls from Qt frontend to the proxy engine.
• db/ConfigBuilder.hpp — Converts bean objects to sing-box JSON config; critical path from UI model to actual proxy startup.
• fmt/Link2Bean.cpp — Parses proxy share links (ss://, trojan://, etc.) into internal bean representation; handles all inbound protocol deserialization.
• .github/workflows/build-nekoray-cmake.yml — CI/CD pipeline for cross-platform binary builds; defines how releases are packaged for Windows and Linux.

Add Support for a New Proxy Protocol

1. Create a new bean struct in fmt/ (e.g., fmt/MyProxyBean.hpp) that inherits from AbstractBean, define all protocol-specific fields. (fmt/AbstractBean.hpp)
2. Add parsing logic in Link2Bean.cpp to recognize and deserialize your protocol's share link format (e.g., myproto://). (fmt/Link2Bean.cpp)
3. Add serialization in Bean2CoreObj_box.cpp to convert your bean to sing-box JSON config schema. (fmt/Bean2CoreObj_box.cpp)
4. Update Database.hpp if needed to store protocol-specific metadata; rebuild and test link imports. (db/Database.hpp)

Add a New Configuration Setting to the UI

1. Add the new field to the appropriate bean class (e.g., TrojanVLESSBean) in fmt/ (fmt/TrojanVLESSBean.hpp)
2. Update ConfigBuilder.hpp and Bean2CoreObj_box.cpp to serialize the setting into sing-box JSON. (db/ConfigBuilder.hpp)
3. Create or modify a Qt UI file in the GUI layer to expose the setting in the profile editor. (3rdparty/qv2ray/v2/ui/widgets/editors/w_JsonEditor.ui)

Add a New gRPC RPC Method for Backend Control

1. Define the new gRPC service method in the proto schema (review go/cmd/nekobox_core/ structure or grpc_server for IDL). (go/cmd/nekobox_core/grpc_box.go)
2. Implement the handler in grpc_box.go, integrating with core_box.go for sing-box lifecycle management. (go/cmd/nekobox_core/core_box.go)
3. Call the new RPC from the Qt frontend wherever the feature is triggered (add gRPC client call in UI logic). (go/cmd/nekobox_core/main.go)

Customize sing-box Routing or DNS Rules

1. Extend the ConfigBuilder or add new bean fields to expose routing/DNS options in the domain/IP rule format. (db/ConfigBuilder.hpp)
2. Update Bean2CoreObj_box.cpp to map UI inputs into sing-box's routing and dns_servers JSON structure. (fmt/Bean2CoreObj_box.cpp)
3. Test by exporting the config JSON and verifying it against sing-box documentation. (fmt/Bean2External.cpp)

• Qt 6 / C++ — Cross-platform GUI that compiles natively on Windows and Linux with minimal platform-specific code; mature ecosystem for desktop apps.
• sing-box (Go backend) — Modern, lightweight proxy engine with extensive protocol support; decouples UI from proxy logic and allows headless operation.
• gRPC + Protobuf — Type-safe, language-agnostic IPC between Qt (C++) and Go backend; efficient binary serialization.
• CMake — Unified build system for Qt, C++, and Go components across Windows and Linux without platform-specific makefiles.

• Separate Qt frontend from Go backend via gRPC instead of embedding sing-box in C++

  • Why: Go ecosystem is richer for proxy logic; Go is easier to cross-compile and update independently.
  • Consequence: Adds inter-process communication overhead (~1–5ms per RPC), but gains modularity and cleaner separation of concerns.

• Store all profiles, groups, and configs in memory (Database.hpp) rather than a persistent SQL database

  • Why: Simpler data model for this use case; profiles are typically small JSON objects.
  • Consequence: Config is lost on app exit unless explicitly exported; no concurrent multi-process access, but acceptable for a single-user GUI app.

• Reuse

  • Why: undefined
  • Consequence: undefined

Unmaintained status: no active support; breakage with newer sing-box versions likely. Submodule hell: .gitmodules references multiple qv2ray submodules (v2/ and v3/ coexist); git submodule update --init --recursive mandatory. gRPC bridging: GUI↔backend communication via localhost gRPC; requires sing-box binary in PATH or configured location, or startup will fail silently. Protobuf regeneration: changes to config .proto require manual CMake reconfiguration (cmake/myproto.cmake); ninja/make alone won't pick up changes. Platform-specific builds: Windows requires VC++ redistributable (linked in README); Linux requires libgl1-mesa-dev and Qt runtime libraries.

• gRPC + Protocol Buffers — Nekoray uses gRPC to bridge Qt GUI (C++) and sing-box backend (Go) via localhost services; understanding this IPC mechanism is essential for modifying proxy protocol handling or adding new configuration options
• Proxy Protocol Stack (SOCKS/HTTP/Shadowsocks/VMess/VLESS/Trojan) — The entire app exists to configure these protocols; contributors must understand tunneling basics, authentication schemes, and config serialization per protocol
• Qt Signal/Slot Mechanism — The entire GUI is built on Qt's asynchronous event model; modifying UI logic requires knowledge of signal propagation, slot connections, and thread safety in Qt
• Subscription Format Parsing (Shadowsocks/Clash/v2rayN) — Nekoray's subscription feature decodes multiple incompatible formats into unified config; the parsing logic in 3rdparty/ is fragile and format-specific
• JSON Schema for Proxy Config — sing-box uses JSON for all configuration; understanding nested structure (inbounds/outbounds/route/dns) is critical for adding new proxy types or routing rules
• CMake Cross-Platform Build Orchestration — The build must generate platform-specific binaries (Windows .exe, Linux ELF) and integrate Go modules; CMake logic in cmake/linux/ and root CMakeLists.txt handles this complexity
• Geolocation/Domain Routing (GeoSite/GeoIP) — Advanced routing requires binary geolocation databases (parsed in GeositeReader.cpp); this underpins rule-based proxy selection by destination

• SagerNet/sing-box — The active backend proxy engine used by nekoray; essential dependency for understanding config schema and protocol support
• Qv2ray/Qv2ray — Predecessor project (vendored in 3rdparty/); nekoray reused its Qt UI components and architecture patterns
• 2dust/v2rayN — Windows-focused alternative proxy manager; uses similar protocol stack (VMess, VLESS, Trojan) and provides comparison for UI/UX patterns
• MatsuriDayo/Matsuri — Earlier Android-based proxy manager by same author; shared codebase philosophy and sing-box integration approach
• sagernet/sing-box-extra — Extended sing-box plugins and custom protocols; directly integrated into nekoray for protocol extensibility

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 unit tests for db/ConfigBuilder and db/Database core classes

The repo has critical database and configuration building logic in db/ConfigBuilder.cpp and db/Database.cpp with no visible test files. These are core components handling proxy configuration persistence and profile management. Adding unit tests would improve reliability of config serialization/deserialization and catch regressions in profile filtering (db/ProfileFilter.cpp) and traffic data handling (db/traffic/).

• [ ] Create tests/ directory with CMake test configuration
• [ ] Add unit tests for ConfigBuilder::Build() and configuration validation in db/ConfigBuilder.cpp
• [ ] Add unit tests for Database load/save operations and Group management in db/Database.cpp
• [ ] Add unit tests for ProxyEntity parsing and ProfileFilter matching logic
• [ ] Integrate tests into CMakeLists.txt with CTest and GitHub Actions workflow

Add GitHub Actions workflow for cross-platform binary testing and validation

Currently .github/workflows/ has build-nekoray-cmake.yml and update-pkgbuild.yml, but no validation workflow that tests compiled binaries on Windows/Linux. Given the GUI nature and platform-specific code in cmake/windows/ and cmake/linux/, a post-build validation workflow would catch platform-specific regressions early. This is critical since the project no longer has active maintenance.

• [ ] Create .github/workflows/test-binaries.yml that runs after build-nekoray-cmake.yml completes
• [ ] Add steps to verify Windows binary (exe) exists and can execute --version on Windows runner
• [ ] Add steps to verify Linux binary functionality and basic GUI initialization on Linux runner
• [ ] Test configuration file loading from db/ with sample proxy profiles
• [ ] Add artifact downloads and basic smoke tests for portable releases

Create integration tests for sing-box backend communication via gRPC

The project depends on grpc_server v1.0.0 (go.mod) and github.com/sagernet/sing-box for backend proxy operations, but there are no visible integration tests verifying the C++/gRPC interface. With no active maintenance, having tests that validate the message passing between Qt frontend and sing-box backend would document expected behavior and prevent silent failures.

• [ ] Add integration test directory structure alongside existing 3rdparty/ utilities
• [ ] Create tests validating gRPC server startup and configuration protocol in nekobox_core module
• [ ] Add tests for ProxyEntity to sing-box config conversion (verify db/ConfigBuilder output)
• [ ] Add tests for traffic data collection via TrafficLooper (db/traffic/TrafficLooper.cpp)
• [ ] Document gRPC API contract in tests for future maintainers

• Add unit tests for 3rdparty/qv2ray/v3/components/GeositeReader/GeositeReader.cpp — currently untested, could cover malformed protobuf parsing and edge cases in domain list loading
• Document gRPC service protocol in docs/ — no specification of nekobox_core service definitions visible; add autogenerated .proto docs or handwritten API reference for contributors
• Refactor 3rdparty/ vendored code into git submodules — qv2ray/v2/ and v3/ are duplicated copies; migrate to proper submodule pinning to reduce maintenance burden and sync upstream fixes

• High · Outdated Go Dependencies with Known Vulnerabilities — go.mod, go.sum dependencies. The go.mod file specifies Go 1.19, which is an older version. Multiple transitive dependencies have known CVEs, including: github.com/klauspost/compress (CVE-2024-4899), github.com/miekg/dns (CVE-2023-26752), and potentially others. The sing-box backend and its dependencies may contain unpatched security issues. Fix: Update Go to version 1.21 or later. Run 'go get -u ./...' to update all dependencies. Audit critical dependencies like sing-box for known CVEs using tools like nancy or trivy.
• High · Replaced Dependencies Without Version Pinning — go.mod (replaced directives). The go.mod file uses 'replaced' directives for critical components (libneko, sing-box, grpc_server) without explicit version constraints. This allows arbitrary local versions to be used during builds, potentially introducing untested or malicious code. Fix: Either pin replaced dependencies to specific versions or document the replacement strategy. Use checksums in go.mod to ensure integrity. If using local replacements during development, ensure CI/CD uses proper versioned dependencies for releases.
• High · No Security Policy or Vulnerability Disclosure Process — Repository root, GitHub settings. The repository does not appear to have a SECURITY.md file or clear vulnerability disclosure policy. The project is also marked as unmaintained ('不再维护'), creating a significant risk for security issues being unaddressed. Fix: If the project is unmaintained, clearly indicate this in the README with migration guidance. Otherwise, establish a SECURITY.md file with responsible disclosure guidelines and create a security contact mechanism.
• Medium · Proxy Configuration Manager with Network Exposure — db/ConfigBuilder.cpp, db/Database.cpp, fmt/Bean2CoreObj_box.cpp. The application is a proxy configuration manager interfacing with sing-box backend. Improper validation of proxy configurations could lead to MITM attacks, credential leakage, or malicious proxy injection. The grpc_server dependency suggests network-exposed functionality. Fix: Implement strict validation of all proxy configurations. Sanitize URL parsing and credential handling. Use TLS for gRPC communications. Implement input validation for configuration files and user inputs.
• Medium · Base64 Encoding Implementation — 3rdparty/base64.cpp, 3rdparty/base64.h. Custom base64 implementation found in 3rdparty/base64.cpp. Custom cryptographic or encoding implementations are prone to implementation errors and should be avoided. Fix: Replace with standard library implementations (e.g., Qt's built-in base64 utilities or OpenSSL). Audit the current implementation for encoding/decoding edge cases.
• Medium · QR Code Generation Library — 3rdparty/qrcodegen.cpp, 3rdparty/qrcodegen.hpp. The qrcodegen library (3rdparty/qrcodegen.cpp) is bundled. While generally safe, QR codes could potentially encode malicious content if user input is not properly validated before QR generation. Fix: Validate all data before QR code generation. Ensure QR codes are only generated from trusted configuration sources. Implement size limits on encoded data.
• Medium · Windows-Specific Code with Potential Privilege Issues — 3rdparty/WinCommander.cpp, 3rdparty/WinCommander.hpp. WinCommander.cpp suggests Windows-specific command execution. Without careful sandboxing, this could be vulnerable to privilege escalation or command injection. Fix: Review Windows command execution for injection vulnerabilities. Ensure proper quoting of arguments. Avoid running with elevated privileges unless absolutely necessary. Use Windows API directly instead of shell execution where possible.
• Low · Third-party Qv2ray Code Integration — 3rdparty/qv2ray/. Code from Qv2ray project (3rdparty/qv2ray/) is integrated directly. Ensure this code is regularly audited and updated, as it includes JSON parsing and proxy configuration logic. Fix: Keep Qv2ray components updated to the latest version.

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.