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/testerSunshine/12306 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

• 9 active contributors
• MIT licensed
• Tests present
• ⚠ Stale — last commit 3y ago
• ⚠ Concentrated ownership — top contributor handles 54% of recent commits
• ⚠ 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 testerSunshine/12306 repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/testerSunshine/12306.

What it runs against: a local clone of testerSunshine/12306 — 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 testerSunshine/12306 | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | 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 ≤ 1161 days ago | Catches sudden abandonment since generation |

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

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

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT 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 "run.py" \\
  && ok "run.py" \\
  || miss "missing critical file: run.py"
test -f "TickerConfig.py" \\
  && ok "TickerConfig.py" \\
  || miss "missing critical file: TickerConfig.py"
test -f "init/login.py" \\
  && ok "init/login.py" \\
  || miss "missing critical file: init/login.py"
test -f "inter/Query.py" \\
  && ok "inter/Query.py" \\
  || miss "missing critical file: inter/Query.py"
test -f "verify/mlearn_for_image.py" \\
  && ok "verify/mlearn_for_image.py" \\
  || miss "missing critical file: verify/mlearn_for_image.py"

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

An intelligent Chinese railway (12306) ticket booking automation tool that performs OCR-based CAPTCHA solving, automated login, real-time ticket sniping at presale times, and intelligent waitlist management with email and ServerChan push notifications. It combines Keras/TensorFlow deep learning for captcha recognition with Selenium browser automation and asynchronous request handling to beat bot detection. Monolithic single-repo structure: init/ orchestrates main login and ticket selection flow; inter/ contains ~25 request handler modules for each 12306 API endpoint (GetPassengerDTOs.py, ConfirmSingleForQueue.py, etc.); config/ centralizes settings (urlConf.py, emailConf.py, serverchanConf.py); agency/ manages proxy rotation and CDN filtering; verify/ holds CAPTCHA ML code; myUrllib/ wraps HTTP requests with anti-detection headers.

Chinese railway ticket buyers who want to automate the tedious 12306 booking process; travel agents or resellers managing bulk bookings; developers interested in learning web scraping, CAPTCHA ML recognition, and anti-bot evasion techniques applied to a real high-traffic service.

Actively maintained but showing signs of age (Python 3.6-3.7 support, TensorFlow 1.14.0 from 2019). Project has 7 full Discord groups (indicating significant adoption), includes Docker support, unit tests (UnitTest/TestAll.py), and clear setup documentation. However, no visible CI/CD pipeline in the file structure and dependencies like TensorFlow 1.x are deprecated. Verdict: production-viable for active hobbyists, not enterprise-grade.

Heavy reliance on outdated ML stack (TensorFlow 1.14, Keras 2.2.4) with known compatibility issues on modern Python environments—the README explicitly warns about version mismatches. Single-maintainer project (testerSunshine) with 12306 being a moving target that actively fights automation. Model file (12306.image.model.h5) is external and must be manually downloaded; its availability is a hard dependency. Request library version (2.18.4 from 2018) is also legacy.

README mentions update log (Update.md) and ongoing group support suggests active issue resolution, but no explicit commit dates in provided data. Docker support (Dockerfile, docker-compose.yml, docker_install_centos.sh) is well-developed, implying recent DevOps investment. The presence of multiple group IDs (some marked full) suggests active community but no visible GitHub Actions or PR pipeline.

git clone https://github.com/testerSunshine/12306.git
cd 12306
# Download model: https://pan.baidu.com/s/1rS155VjweWVWIJogakechA (密码:bmlm) → 12306.image.model.h5
pip3 install -i https://pypi.tuna.tsinghua.edu.cn/simple -r requirements.txt
python3 run.py c  # Filter CDN first (critical step)
python3 run.py t  # Test email/ServerChan config
python3 run.py r  # Start booking
# OR with Docker: docker-compose up --build -d

Daily commands: For ticket booking: python3 run.py r (requires TickerConfig.py configured, CDN filtered via python3 run.py c, and model downloaded). For testing: python3 run.py t (validates email/ServerChan). For Docker: docker-compose up --build -d after modifying TickerConfig.py (set AUTO_CODE_TYPE=3, HOST='captcha:80'). View logs: docker logs --follow ticket.

• run.py — Main entry point that orchestrates the ticket booking workflow; all users must understand the execution flow starting here
• TickerConfig.py — Central configuration file where all booking parameters, credentials, and notification settings are defined; must be customized before any run
• init/login.py — Handles authentication with 12306 servers and session management; critical for understanding security and user validation flow
• inter/Query.py — Core query engine that polls train availability and ticket status; the most frequently executed module in the booking loop
• verify/mlearn_for_image.py — ML-based CAPTCHA solver using Keras/TensorFlow models; essential for understanding the automated verification mechanism
• inter/SubmitOrderRequest.py — Handles final order submission to 12306; critical path where bookings are finalized
• config/urlConf.py — Centralized URL endpoints for all 12306 API calls; must be maintained as endpoints change

Add a new notification channel

1. Create a new notification configuration module following the pattern in config/emailConf.py or config/serverchanConf.py (config/)
2. Implement a send notification method that accepts booking status and passenger details (config/[newChannelName]Conf.py)
3. Import and instantiate the new notifier in run.py after order confirmation (run.py)
4. Add configuration parameters to TickerConfig.py for the new channel credentials (TickerConfig.py)

Add support for a new verification service

1. Create a new module in verify/ that wraps the external service API (verify/[newServiceName].py)
2. Implement a solve_captcha(image_path) method returning the answer code (verify/[newServiceName].py)
3. Add the new service as a fallback option in verify/localVerifyCode.py with try-except chaining (verify/localVerifyCode.py)
4. Update configuration keys in config/configCommon.py for service credentials (config/configCommon.py)

Add a new 12306 API endpoint interaction

1. Add the new endpoint URL to config/urlConf.py as a class constant (config/urlConf.py)
2. Create a new module in inter/ named after the API endpoint (e.g., inter/GetNewData.py) (inter/[NewApiName].py)
3. Implement request building and response parsing, following patterns from inter/Query.py or inter/SubmitOrderRequest.py (inter/[NewApiName].py)
4. Integrate the new API call into the appropriate workflow location in run.py or an existing inter module (run.py)
5. Add any new response enums or status codes to config/TicketEnmu.py (config/TicketEnmu.py)

Implement a new booking strategy or filter

1. Create filter logic as a new function or class in init/select_ticket_info.py (init/select_ticket_info.py)
2. Add strategy parameters to TickerConfig.py (e.g., preferred_seat_type, min_departure_time) (TickerConfig.py)
3. Call the new filter function after querying available tickets in the main polling loop in run.py (run.py)
4. Log filter results using config/logger.py for debugging filter effectiveness (config/logger.py)

• Keras + TensorFlow 1.14.0 — Local CAPTCHA image classification without external API calls, reducing latency and dependency on cloud services; model-based approach tolerates slight variations in verification images
• Selenium 3.11.0 — Some 12306 interactions require browser automation with JavaScript rendering; Selenium provides reliable DOM manipulation and cookie handling
• BeautifulSoup4 + requests — Standard HTTP-based parsing for most API responses; lightweight and battle-tested for web scraping Chinese railway system endpoints
• ntplib — Network Time Protocol synchronization ensures ticket request timestamps match server time exactly, preventing rejection due to clock skew
• OpenCV (cv2) — Image preprocessing (contrast enhancement, noise reduction) before ML inference improves CAPTCHA recognition accuracy

• Python 3.6+ only (no Python 2.7 support)

  • Why: TensorFlow 1.14+ requires Python 3.x; async/await syntax for concurrent polling
  • Consequence: Cannot run on legacy systems; users must maintain modern Python environment

• Local ML-based CAPTCHA solving vs. always-on cloud OCR service

  • Why: Reduces external dependencies and API costs; preserves privacy of bookings
  • Consequence: Requires 300MB+ model download and GPU/CPU overhead; fallback to cloud services

Critical: CDN filtering (python3 run.py c) must run before each session or request will hang—this is non-obvious and mentioned in README but easy to skip. Model dependency: 12306.image.model.h5 must be in project root; no fallback exists. Time sensitivity: ntplib auto-syncs system clock (config/AutoSynchroTime.py) because 12306 rejects requests with skewed timestamps—if NTP fails silently, all requests fail. TensorFlow hell: TensorFlow 1.14.0 on Python 3.8+ requires workarounds (README hints at version compatibility issues); installing may fail without lowering/raising TensorFlow version. Async gotcha: inter/ConfirmSingleForQueueAsys.py runs async but shares global session state—race conditions possible if multiple routes booked concurrently. 12306 detection: User-Agent rotation and proxy chains are mandatory or requests get 403'd immediately; no request goes out unrotated. Server-side model: config/getCookie.py and LoginConf.py handle session cookies that expire fast—timeouts not parameterized, may timeout on slow networks.

• Optical Character Recognition (OCR) with Deep Learning — The entire CAPTCHA solving subsystem in verify/ relies on training a Keras CNN to classify captcha images; understanding CNN architecture, overfitting, and train/test splits is critical to maintaining this component.
• Session Management & Cookie Persistence — 12306 uses stateful sessions with short-lived cookies; config/getCookie.py and inter modules must preserve session state across multiple API calls or login fails silently.
• Proxy Chain Rotation for Anti-Detection — agency/cdn_utils.py rotates proxy IPs to avoid 12306's rate limiting and IP-based blocking; understanding proxy protocols (HTTP vs SOCKS5) and failover is essential for reliability.
• NTP (Network Time Protocol) Synchronization — config/AutoSynchroTime.py uses ntplib to sync system clock because 12306 APIs reject requests with timestamp skew >1 second; clock drift causes silent 401/403 failures.
• Asynchronous Request Handling with Event Loops — inter/ConfirmSingleForQueueAsys.py and inter/GetQueueCountAsync.py use async patterns to handle parallel booking attempts; race conditions in shared state are a silent failure mode.
• Bot Detection Evasion (User-Agent, Headers, Timing) — 12306 employs multiple anti-bot measures; fake-useragent rotation, custom request headers in myUrllib/, and request timing jitter are necessary or requests fail immediately with 403.
• Presale Queue Management & Race Conditions — Tickets are released at exact times (e.g., 14:00 daily); GetQueueCount.py polls for availability and ConfirmSingleForQueue.py must submit before stock depletes. Order of execution and timing precision matter more than logic correctness.

• zhaipro/easy12306 — Predecessor and source of CAPTCHA model logic; this repo is built on top of its ML components for captcha recognition.
• YinAoXiong/12306_code_server — Companion microservice for cloud-based CAPTCHA solving as alternative to local TensorFlow model; TickerConfig.py references AUTO_CODE_TYPE=3 for this integration.
• testerSunshine/12306model — Separate repo hosting just the Keras model file (12306.image.model.h5) distribution; git clone alternative to Baidu download for the critical model dependency.
• requests/requests — Core HTTP library powering all API calls; understanding requests session handling and retry logic is essential for debugging network issues in this repo.
• kennethreitz/fake-useragent — Dependency for rotating User-Agent headers to evade 12306 bot detection; studying how it's integrated in myUrllib/ helps understand anti-detection architecture.

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 inter/ API modules

The UnitTest/ directory only contains TestAll.py with minimal test coverage. The inter/ directory has 20+ critical API modules (Query.py, SubmitOrderRequest.py, ConfirmSingleForQueue.py, etc.) that handle ticket booking logic but lack dedicated unit tests. This is a high-risk area where bugs cause real user issues. Adding focused tests would catch regressions and improve reliability.

• [ ] Create test files for core modules: inter/Query.py, inter/SubmitOrderRequest.py, inter/GetPassengerDTOs.py, inter/GetQueueCount.py
• [ ] Mock HTTP responses using responses or unittest.mock to avoid external dependencies
• [ ] Test edge cases: network failures, malformed JSON responses, timeout scenarios
• [ ] Add tests to UnitTest/ directory following existing structure and document in Update.md

Refactor myUrllib/httpUtils.py into modular HTTP client with retry logic

The httpUtils.py file likely contains mixed concerns (HTTP requests, retries, error handling, proxies) given the agency/proxy_list and CDN utilities exist separately. This monolithic approach makes testing difficult and error-prone. Splitting into focused modules (core client, retry strategy, proxy rotation, error handling) with explicit interfaces would improve maintainability and allow contributors to extend functionality more safely.

• [ ] Extract retry logic from myUrllib/httpUtils.py into myUrllib/retry_strategy.py with configurable backoff
• [ ] Create myUrllib/proxy_client.py to integrate agency/proxy_list management
• [ ] Create myUrllib/session_manager.py for cookie/session lifecycle and User-Agent rotation
• [ ] Update inter/ modules to use new client interfaces and document changes in Update.md

Add GitHub Actions CI/CD workflow for Python 3.6-3.7 compatibility testing

The repo targets Python 3.6-3.7 per README but has no automated testing on those versions. Dependencies like tensorflow==1.14.0, keras==2.2.4, and opencv-python have version constraints that may break on different Python versions. Without CI, contributors cannot verify their changes work on supported versions, leading to compatibility regressions after merges.

• [ ] Create .github/workflows/test.yml with matrix testing for Python 3.6, 3.7, and 3.8 (for forward compatibility)
• [ ] Test requirements.txt installation and run UnitTest/TestAll.py on each Python version
• [ ] Add separate workflow .github/workflows/docker-build.yml to validate Dockerfile and Dockerfile37 builds
• [ ] Document CI expectations in CONTRIBUTING.md or Update.md for future contributors

• Add unit tests for inter/ modules: Only UnitTest/TestAll.py exists but is empty/minimal (no test cases visible for individual request handlers). Start by writing tests for inter/GetPassengerDTOs.py and inter/CheckUser.py to catch refactoring breakage early.
• Document the CAPTCHA model training pipeline: README mentions the model comes from zhaipro/easy12306 but verify/ directory structure is absent. Add a TRAINING.md with dataset preparation, Keras model definition, and retraining steps so contributors can update the model when 12306 changes their CAPTCHA format.
• Add retry-with-backoff logic to inter/ request modules: Currently no visible exponential backoff in inter/ files (only direct execute() calls). Implement a decorator (e.g., @retry_on_rate_limit) across GetQueueCount.py, ConfirmSingleForQueue.py that handles 429/503 responses gracefully instead of crashing.

• Critical · Severely Outdated Python Version — Dockerfile. The primary Dockerfile uses Python 2.7.15, which reached end-of-life on January 1, 2020. Python 2.7 no longer receives security updates, making the application vulnerable to all known and future Python 2.7 vulnerabilities. All dependencies compiled against Python 2.7 are also unsupported. Fix: Migrate to Python 3.9+ immediately. Update all dependencies to versions compatible with modern Python. Remove the legacy Dockerfile and standardize on Dockerfile37 which uses Python 3.7.
• Critical · Severely Outdated Dependencies with Known Vulnerabilities — requirements.txt, requirements-docker37.txt. Multiple critical dependencies have unpatched vulnerabilities: requests==2.18.4 (released Sept 2017), tensorflow==1.14.0 (released April 2019), keras==2.2.4 (released Sept 2018), Pillow (unversioned), selenium==3.11.0 (released March 2018). These versions contain known CVEs including arbitrary code execution, privilege escalation, and data exfiltration vulnerabilities. Fix: Update all dependencies to latest stable versions: requests>=2.28.0, tensorflow>=2.13.0 or use tensorflow 2.x, keras>=3.0.0, Pillow>=10.0.0, selenium>=4.15.0. Run pip audit to identify remaining CVEs.
• Critical · Credentials and Sensitive Configuration Exposure — config/emailConf.py, config/pushbearConf.py, config/serverchanConf.py, TickerConfig.py. Configuration files contain hardcoded credentials and sensitive data: emailConf.py, pushbearConf.py, serverchanConf.py likely contain API keys, email credentials, and tokens. TickerConfig.py may contain user credentials. These files could expose authentication tokens, email passwords, and third-party API keys if repository is compromised. Fix: Move all credentials to environment variables or a secure secrets management system. Use .env files (added to .gitignore) or container secrets. Never commit credentials to version control. Implement secret scanning in CI/CD pipeline.
• High · Insecure Network Configuration in Docker Compose — docker-compose.yml. The docker-compose.yml exposes services on default bridge network without explicit network isolation. The external CAPTCHA service dependency (yinaoxiong/12306_code_server) is pulled from an untrusted third-party registry without version pinning or digest verification, creating supply chain risk. Fix: Pin CAPTCHA image to specific digest: image: yinaoxiong/12306_code_server:amd64@sha256:.... Implement network policies to restrict inter-service communication. Consider running CAPTCHA service in isolated environment or use official services only.
• High · Use of Deprecated and Vulnerable TensorFlow Version — requirements.txt, requirements-docker37.txt. tensorflow==1.14.0 is from 2019 and no longer receives security updates. TensorFlow 1.x has multiple known vulnerabilities in protobuf parsing, arbitrary code execution in tf.raw_ops, and unsafe pickle deserialization. Fix: Migrate to TensorFlow 2.13+ or latest LTS version. Review TensorFlow security advisories at tensorflow.org/security. Consider using pre-trained model serving infrastructure instead of embedding TensorFlow in application.
• High · Machine Learning Model Files Not Verified — 12306.image.model.h5, model.v2.0.h5, verify/mlearn_for_image.py. Model files (12306.image.model.h5, model.v2.0.h5) are included without integrity checks or code signing. These binary files could contain malicious payloads (trojanized models) and are loaded by Keras/TensorFlow without validation. Fix: Implement model integrity verification using cryptographic hashes (SHA-256) or digital signatures. Verify model checksum on startup before loading. Document model provenance and maintain audit trail. Consider downloading from secure, verified sources only.
• High · HTTP-Only Communication with No TLS/HTTPS Verification — undefined. The application interacts with 12306 services (inter/ modules) and external APIs ( 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.