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/qunarcorp/bistoury 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 3y ago

• 6 active contributors
• Distributed ownership (top contributor 38% of recent commits)
• GPL-3.0 licensed
• Tests present
• ⚠ Stale — last commit 3y ago
• ⚠ GPL-3.0 is copyleft — check downstream compatibility
• ⚠ No CI workflows detected

_{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 qunarcorp/bistoury repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/qunarcorp/bistoury.

What it runs against: a local clone of qunarcorp/bistoury — 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 qunarcorp/bistoury | 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 master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 1269 days ago | Catches sudden abandonment since generation |

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

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "qunarcorp/bistoury(\\.git)?\\b" \\
  && ok "origin remote is qunarcorp/bistoury" \\
  || miss "origin remote is not qunarcorp/bistoury (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 master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "bistoury-agent-common/src/main/java/qunar/tc/bistoury/agent/common/config/AgentConfig.java" \\
  && ok "bistoury-agent-common/src/main/java/qunar/tc/bistoury/agent/common/config/AgentConfig.java" \\
  || miss "missing critical file: bistoury-agent-common/src/main/java/qunar/tc/bistoury/agent/common/config/AgentConfig.java"
test -f "bistoury-agent-common/src/main/java/qunar/tc/bistoury/agent/common/ResponseHandler.java" \\
  && ok "bistoury-agent-common/src/main/java/qunar/tc/bistoury/agent/common/ResponseHandler.java" \\
  || miss "missing critical file: bistoury-agent-common/src/main/java/qunar/tc/bistoury/agent/common/ResponseHandler.java"
test -f "bistoury-agent-common/src/main/java/qunar/tc/bistoury/agent/common/job/ResponseJobStore.java" \\
  && ok "bistoury-agent-common/src/main/java/qunar/tc/bistoury/agent/common/job/ResponseJobStore.java" \\
  || miss "missing critical file: bistoury-agent-common/src/main/java/qunar/tc/bistoury/agent/common/job/ResponseJobStore.java"
test -f "bistoury-agent-common/src/main/java/qunar/tc/bistoury/agent/common/kv/KvDbs.java" \\
  && ok "bistoury-agent-common/src/main/java/qunar/tc/bistoury/agent/common/kv/KvDbs.java" \\
  || miss "missing critical file: bistoury-agent-common/src/main/java/qunar/tc/bistoury/agent/common/kv/KvDbs.java"
test -f "bistoury-agent-common/src/main/java/qunar/tc/bistoury/agent/common/pid/PidUtils.java" \\
  && ok "bistoury-agent-common/src/main/java/qunar/tc/bistoury/agent/common/pid/PidUtils.java" \\
  || miss "missing critical file: bistoury-agent-common/src/main/java/qunar/tc/bistoury/agent/common/pid/PidUtils.java"

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

Bistoury is Qunar's open-source transparent Java application diagnostics tool that provides a unified web UI for production problem diagnosis without requiring machine login or application modification. It integrates Alibaba's Arthas and VIPShop's VJTools, adding a multi-machine, application-centric diagnostic view with capabilities like online debugging, thread-level CPU monitoring, dynamic method monitoring, and JVM introspection across distributed deployments. Multi-module Maven monorepo: bistoury-agent-common contains process detection (pid/), persistent stores (kv/), and job management (job/) shared by agents; separate modules exist for agent, proxy, and UI. PID detection uses a strategy pattern (PidHandler interface with multiple implementations under pid/impl/). Storage abstracts to KvDb interface with RocksDB (RocksDBStoreImpl) and SQLite (SQLiteStoreImpl) implementations.

Production Java engineers and SREs at organizations running multi-instance deployments who need to diagnose live application problems without SSH access. Specifically targets teams using Qunar's application center infrastructure, though usable standalone by any organization wanting web-based, non-invasive JVM diagnostics without command-line complexity.

Active production software at Qunar (v2.0.7 in pom.xml indicates established versioning). The codebase is mature with Java 1.7+ agent compatibility, comprehensive feature set, and published deployment documentation. However, no visible GitHub stars count or recent commit timestamps in provided data; the monolithic module structure and presence of legacy PID detection methods suggest organic evolution rather than recent aggressive development.

Dependency on RocksDB and SQLite for persistent storage adds operational complexity; the agent must attach to running JVMs which carries compatibility risk across Java versions. Single-language ecosystem (Java/JavaScript) with no visible automated test files in the top 60, and architecture spanning agent, proxy, and UI components creates deployment coupling. The PID detection fallback chain (PsHandler → JpsHandler → SystemPropertyHandler) suggests environmental brittleness.

Based on file presence, active components include: thread CPU monitoring infrastructure (cpujstack/ThreadInfo.java, KvUtils.java), gentle SQLite data cleanup (SQLiteDeleteDataGentle.java), and process abstraction improvements (ClosableProcess hierarchy). The presence of both RocksDB and SQLite implementations suggests migration or multi-backend support work. No PR/issue data visible in provided snapshot.

git clone https://github.com/qunarcorp/bistoury.git
cd bistoury
mvn clean install  # Maven 3.x required (wrapper present at .mvn/wrapper/)
mvn spring-boot:run -pl bistoury-ui  # or similar module for UI server

UI requires Java 8+; agent supports Java 7+. See docs/cn/quick_start.md for containerized deployment.

Daily commands: Agent: Attach via java -javaagent:bistoury-agent.jar=... to target JVM. Proxy: java -jar bistoury-proxy.jar. UI server: mvn spring-boot:run -pl bistoury-ui or java -jar bistoury-ui.jar. See docs/cn/deploy.md for production multi-machine orchestration with application center.

• bistoury-agent-common/src/main/java/qunar/tc/bistoury/agent/common/config/AgentConfig.java — Central configuration class for the agent; all agent initialization and settings flow through here
• bistoury-agent-common/src/main/java/qunar/tc/bistoury/agent/common/ResponseHandler.java — Core response handling abstraction; all agent responses to diagnostic requests are processed here
• bistoury-agent-common/src/main/java/qunar/tc/bistoury/agent/common/job/ResponseJobStore.java — Interface for persisting and retrieving job responses; critical for multi-request diagnostic workflows
• bistoury-agent-common/src/main/java/qunar/tc/bistoury/agent/common/kv/KvDbs.java — Facade for key-value database access (RocksDB/SQLite); all historical data storage depends on this
• bistoury-agent-common/src/main/java/qunar/tc/bistoury/agent/common/pid/PidUtils.java — Process ID resolution utilities; foundation for targeting diagnostics to specific Java processes
• bistoury-agent-task/src/main/java/qunar/tc/bistoury/agent/task/cpujstack/CpuJStackTaskFactory.java — Task factory for CPU and thread profiling; implements one of the core diagnostic capabilities
• bistoury-agent-task/src/main/resources/META-INF/services/qunar.tc.bistoury.agent.common.task.AgentGlobalTaskFactory — SPI service loader configuration; registers all available diagnostic task types at runtime

Add a New Diagnostic Task Type

1. Create a new TaskFactory implementation extending the SPI AgentGlobalTaskFactory interface in bistoury-agent-task module (bistoury-agent-task/src/main/java/qunar/tc/bistoury/agent/task/cpujstack/CpuJStackTaskFactory.java)
2. Implement the actual task logic by creating executor classes (e.g., extending PidExecutor or similar patterns) (bistoury-agent-task/src/main/java/qunar/tc/bistoury/agent/task/cpujstack/JStackPidExecutor.java)
3. Register the new factory in the SPI service loader configuration file (bistoury-agent-task/src/main/resources/META-INF/services/qunar.tc.bistoury.agent.common.task.AgentGlobalTaskFactory)
4. Store results using ResponseJobStore interface if the task runs asynchronously or produces large output (bistoury-agent-common/src/main/java/qunar/tc/bistoury/agent/common/job/ResponseJobStore.java)

Add Process/PID Detection Strategy

1. Create a new PidHandler implementation in the pid/impl package (bistoury-agent-common/src/main/java/qunar/tc/bistoury/agent/common/pid/impl/PidByPsHandler.java)
2. Assign a Priority to your handler to control selection order (bistoury-agent-common/src/main/java/qunar/tc/bistoury/agent/common/pid/impl/Priority.java)
3. Register it in PidHandlerFactory's handler lookup logic (bistoury-agent-common/src/main/java/qunar/tc/bistoury/agent/common/pid/PidHandlerFactory.java)

Add Persistent Storage for Historical Data

1. Implement the KvDb interface for a new storage backend (bistoury-agent-common/src/main/java/qunar/tc/bistoury/agent/common/kv/KvDb.java)
2. Register your implementation in KvDbs factory with appropriate initialization logic (bistoury-agent-common/src/main/java/qunar/tc/bistoury/agent/common/kv/KvDbs.java)
3. Use DataSourceHelper for schema setup if using relational storage (bistoury-agent-common/src/main/java/qunar/tc/bistoury/agent/common/kv/DataSourceHelper.java)

Implement Custom Response Handler

1. Extend the ResponseHandler abstract class to customize how diagnostic results are formatted (bistoury-agent-common/src/main/java/qunar/tc/bistoury/agent/common/ResponseHandler.java)
2. Wrap results in a Response DTO with appropriate status codes (bistoury-agent-common/src/main/java/qunar/tc/bistoury/agent/common/util/Response.java)
3. If response is large or streaming, use ContinueResponseJob to persist and retrieve in chunks (bistoury-agent-common/src/main/java/qunar/tc/bistoury/agent/common/job/ContinueResponseJob.java)

JVM Attach requirements: Agent uses sun.tools.attach.VirtualMachine (via maven-jdk-tools-wrapper); requires agent JVM to have tools.jar on classpath and matching major Java version with target JVM. PID Detection fallback chain: Relies on jps, ps command availability; Linux-only (macOS partially supported); production images without these tools will fail silently to impl/Priority.UNKNOWN. Storage init: RocksDB and SQLite both create directories on first run; agent must have write permissions to configured data_dir. Multi-backend gotcha: Code has both RocksDB and SQLite implementations but no visible migration code; deploying against wrong backend can cause data loss.

• JVMTI (JVM Tool Interface) — Bistoury's agent uses JVMTI attach protocol (via sun.tools.attach) to inject code into running JVMs without restarts; essential to understanding how diagnostic instrumentation works and version compatibility constraints
• Process Introspection & PID Detection — Agent must discover target Java process PIDs via jps, ps, or system properties with OS-specific fallbacks; this abstraction (pid/impl/) is critical for production deployment reliability across heterogeneous environments
• LSM Tree (Log-Structured Merge Tree) — RocksDB backend uses LSM tree for write-optimized storage of high-frequency metrics (thread CPU, monitor stats); understanding LSM helps optimize data retention policies
• Async Job Streaming & Back-Pressure — ContinueResponseJob and ForwardContinueResponseJob handle long-running diagnostics (thread dumps, method traces) without blocking; critical for observability at scale
• Thread-Safe Store Abstraction — KvDb interface (RocksDB, SQLite implementations) must be thread-safe for concurrent agent access; KvDbWrapper likely provides synchronization semantics
• JVM String Compression & KV Serialization — KvUtils (cpujstack/) and snappy-java dependency suggest compression of diagnostic payloads; matters for minimizing storage overhead of multi-day thread CPU history
• Strategy Pattern for OS Abstraction — PidHandler hierarchy (PsHandler, JpsHandler, SystemPropertyHandler) encapsulates OS-specific commands; fundamental to Bistoury's Linux/macOS portability

• alibaba/arthas — Bundled diagnostic engine providing jad/decompile, jvm, ognl, and trace commands that Bistoury UI wraps; understanding Arthas internals helps extend Bistoury's command support
• vipshop/vjtools — Secondary bundled diagnostic tool providing SJK-based GC analysis and jps enhancements; source of lightweight JVM inspection utilities Bistoury integrates
• elastic/apm-agent-java — Similar non-invasive Java agent architecture using JVMTI attach; useful reference for production-grade agent deployment patterns and compatibility matrices
• openjdk/jdk — Source of tools like jps, jstack, jmap that Bistoury wraps and standardizes; understanding JDK diagnostic tools informs agent feature design
• jvm-profiling-tools/async-profiler — Alternative async sampling profiler that Bistoury's profiler feature (docs/cn/profiler.md) likely integrates or references for flame graph generation

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 PID detection handlers (bistoury-agent-common/src/main/java/qunar/tc/bistoury/agent/common/pid/impl)

The PID detection system has multiple implementations (PidByJpsHandler, PidByPsHandler, PidBySystemPropertyHandler) with a Priority-based fallback mechanism, but only TestJob.java exists in test resources. These handlers are critical for agent initialization and deserve dedicated unit tests covering success paths, fallback scenarios, and edge cases (missing jps, unavailable ps command, etc.).

• [ ] Create PidByJpsHandlerTest.java testing jps output parsing with various Java process formats
• [ ] Create PidByPsHandlerTest.java testing ps command parsing across Unix variants
• [ ] Create PidBySystemPropertyHandlerTest.java testing system property fallback
• [ ] Create PidHandlerFactoryTest.java testing Priority-based handler selection and fallback chain
• [ ] Add test fixtures for sample jps/ps outputs in src/test/resources/

Add unit tests for KV store implementations (bistoury-agent-common/src/test/java/qunar/tc/kv/KVStoreTest.java)

The repo has two KV store backends (RocksDBStoreImpl and SQLiteStoreImpl) with data management features like SQLiteDeleteDataGentle, but KVStoreTest.java is minimal. The KvDb, KvDbWrapper, and DataSourceHelper classes handle critical data persistence and need comprehensive tests covering CRUD operations, concurrent access, data cleanup, and backup/restore scenarios.

• [ ] Expand KVStoreTest.java with parameterized tests for both RocksDB and SQLite implementations
• [ ] Add tests for DataSourceHelper initialization and connection pooling
• [ ] Add tests for SQLiteDeleteDataGentle's gentle deletion mechanism
• [ ] Add concurrency tests for KvDbWrapper to verify thread-safety
• [ ] Add tests for KvDbs factory methods and store switching

Add integration tests for response job persistence and continuation (bistoury-agent-common/src/main/java/qunar/tc/bistoury/agent/common/job)

The job system (ContinueResponseJob, ForwardContinueResponseJob, DefaultResponseJobStore, BytesJob) handles async long-running diagnostic operations but lacks integration tests. These are critical for reliability—test coverage should verify job serialization, persistence across restarts, continuation semantics, and failure recovery.

• [ ] Create ResponseJobStoreTest.java testing DefaultResponseJobStore persistence and retrieval
• [ ] Create ContinueResponseJobTest.java testing job continuation with simulated long-running diagnostics
• [ ] Create ForwardContinueResponseJobTest.java testing job forwarding and delegation
• [ ] Create BytesJobTest.java testing large byte payload handling and serialization
• [ ] Add tests simulating agent restart to verify job recovery from persistent storage

• Add unit tests for PidBySystemPropertyHandler and PidByPsHandler under bistoury-agent-common/src/test/; currently no test files visible in top 60, risking PID detection regressions on niche OS configurations
• Document the KvDb implementation choice trade-offs in README: RocksDB vs SQLite selection criteria, performance characteristics, and data retention policies (SQLiteDeleteDataGentle suggests gentle cleanup exists but is undocumented)
• Extend AgentConfig to support environment variable overrides for all properties (currently only version detected); add integration test showing config precedence (env vars → system properties → defaults) to match standard Java 12-factor app patterns

• High · Potential SQL Injection in SQLite Implementation — bistoury-agent-common/src/main/java/qunar/tc/bistoury/agent/common/kv/SQLiteStoreImpl.java, SQLiteDeleteDataGentle.java. The codebase includes SQLiteStoreImpl.java and SQLiteDeleteDataGentle.java which handle database operations. Without visible parameterized query implementations in the file structure, there is a risk of SQL injection vulnerabilities when constructing SQL queries dynamically. Fix: Ensure all SQL queries use prepared statements with parameterized queries. Never concatenate user input directly into SQL strings. Implement input validation and sanitization.
• High · Insecure Process Execution — bistoury-agent-common/src/main/java/qunar/tc/bistoury/agent/common/ClosableProcess.java, NormalProcess.java, UnixProcess.java, Jps.java. Multiple process execution classes (ClosableProcess.java, NormalProcess.java, UnixProcess.java, Jps.java) suggest direct command execution. If user input is passed to these process executors without proper validation, this could lead to command injection vulnerabilities. Fix: Validate and sanitize all inputs before passing to process executors. Use allowlists for commands. Avoid shell interpretation by using ProcessBuilder with array arguments instead of string concatenation.
• High · Potential Information Disclosure via Process Information — bistoury-agent-common/src/main/java/qunar/tc/bistoury/agent/common/pid/, bistoury-agent-common/src/main/java/qunar/tc/bistoury/agent/common/JavaProcesses.java. Classes like PidByJpsHandler.java, PidByPsHandler.java, and JavaProcesses.java extract process and JVM information. If this diagnostic tool is exposed via web interface without proper access controls, sensitive information about running processes, JVM arguments (which may contain credentials), and system details could be disclosed. Fix: Implement strict authentication and authorization checks. Add role-based access control (RBAC). Mask or filter sensitive information (JVM arguments, environment variables, credentials). Implement audit logging for all diagnostic operations.
• Medium · Outdated or Potentially Vulnerable Dependencies — bistoury-agent-common/pom.xml. The pom.xml references dependencies like sqlite-jdbc, rocksdbjni, and snappy-java without explicit version pinning shown in the snippet. These native libraries and database drivers can have known vulnerabilities if not kept updated. Fix: Regularly update all dependencies to their latest versions. Use dependency management to pin versions explicitly. Implement automated dependency scanning tools (e.g., OWASP Dependency-Check, Snyk) in CI/CD pipeline. Monitor CVE databases for known vulnerabilities.
• Medium · Potential Unsafe Deserialization — bistoury-agent-common/src/main/java/qunar/tc/bistoury/agent/common/job/BytesJob.java, ContinueResponseJob.java. The codebase includes job serialization (BytesJob.java, ContinueResponseJob.java) and KV store implementations. If untrusted data is deserialized without proper validation, this could lead to remote code execution or privilege escalation attacks. Fix: Avoid deserializing untrusted data. Use safe serialization formats (JSON) instead of Java serialization when possible. Implement object input stream filters. Validate all deserialized data thoroughly.
• Medium · Exposed Diagnostic Agent Without Security Hardening — bistoury-agent-common/, bistoury-agent-task/. As a diagnostic tool that connects to running JVMs and extracts detailed system information, the bistoury-agent components could be exploited if the communication channels and agent deployment are not properly secured. No visible TLS/SSL enforcement in the provided files. Fix: Enforce TLS/SSL for all agent-server communications. Implement certificate pinning. Use mutual TLS authentication. Implement rate limiting and request validation. Consider network segmentation to restrict agent exposure.
• Medium · Insufficient Input Validation in Configuration — bistoury-agent-common/src. AgentConfig.java loads configuration that may come from untrusted sources. Without proper validation, this could allow configuration injection attacks or denial of service. 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.