WAIT — Single-maintainer risk — review before adopting

• Last commit today
• 2 active contributors
• MIT licensed
• CI configured
• ⚠ Small team — 2 contributors active in recent commits
• ⚠ Single-maintainer risk — top contributor 96% of recent commits
• ⚠ No test directory detected

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

mihomo is a Python Pydantic-based type-safe wrapper around the Honkai: Star Rail Mihomo API (https://api.mihomo.me/sr_info_parsed/{UID}), providing fully-typed models for player profiles, characters, equipment, and combat stats with IDE autocompletion. It supports two API versions (V1 and V2) with built-in utilities for icon URL resolution, duplicate character removal, and character data merging. Dual-model architecture: mihomo/models/ contains V2 models (base.py, character.py, combat.py, equipment.py, player.py, stat.py) while mihomo/models/v1/ mirrors the structure for V1 API contracts. Core client logic in mihomo/client.py, utilities in mihomo/tools.py, with examples/ providing runnable V1/V2 usage patterns.

Python developers building Honkai: Star Rail companion apps, stat trackers, or bot integrations who need strongly-typed access to player data without manual JSON parsing or schema validation.

Actively maintained with structured CI/CD via GitHub Actions (build.yml, Delete.yml workflows), comprehensive model definitions across 30+ files, and example scripts demonstrating both API versions. Clear production-ready state with v1 and v2 API stability.

Single-language Python package with no visible test directory (no tests/ folder in top 60 files), making regression detection unclear. Dependency on Mihomo API stability (external service), no SemVer versioning visible in pyproject.toml snippet. Appears actively maintained but single-maintainer risk common in game API wrappers.

No recent commit data visible in file listing, but the dual-version support (V1 and V2 coexistence) and tools like remove_duplicate_character() and merge character data suggest active feature maintenance. GitHub Actions workflows indicate CI is configured but current build status unknown.

git clone https://github.com/KT-Yeh/mihomo.git && cd mihomo && pip install -e . (installs from pyproject.toml); then run examples: python examples/basic.py

Daily commands: No traditional 'dev server' (library, not app). To use: pip install -U git+https://github.com/KT-Yeh/mihomo.git, then python examples/basic.py or import from mihomo import MihomoAPI in your own script.

• mihomo/__init__.py — Main package entry point exposing MihomoAPI client and core models; every user starts here
• mihomo/client.py — HTTP client for Mihomo API; handles all network requests to fetch user data for both V1 and V2 formats
• mihomo/models/__init__.py — Exports primary V2 data models (StarrailInfoParsed); defines the shape of parsed Honkai data that consumers depend on
• mihomo/models/base.py — Base Pydantic model classes and shared validation logic; foundation for all V2 models
• mihomo/models/v1/__init__.py — Exports V1 data models (StarrailInfoParsedV1); maintains backward compatibility with legacy API format
• pyproject.toml — Build configuration and dependency manifest; defines Python version, Pydantic requirement, and package metadata

• MihomoAPI Client — Orchestrates HTTP requests to Mihomo API endpoints and delegates parsing to Pydantic models; manages language preference and

Add a new data model field to V2 Player data

1. Identify the API response JSON structure by inspecting the Mihomo API output and determine which category it belongs to (player, character, equipment, etc.) (N/A (external API reference))
2. Add the new field with proper type hints to the appropriate model class in mihomo/models/ (e.g., PlayerInfo in player.py) (mihomo/models/player.py)
3. If the field requires custom validation or transformation, add a Pydantic validator using @field_validator or @model_validator (mihomo/models/base.py)
4. Update the init.py export if creating a new top-level model class (mihomo/models/__init__.py)
5. Add test example in one of the example files to verify the field is accessible (examples/basic.py)

Support a new API language or region

1. Check if a new Language enum value is needed; add it to the Language enum definition (mihomo/__init__.py)
2. Update the MihomoAPI client to accept the new language parameter in the fetch methods (mihomo/client.py)
3. Verify that Pydantic models handle the new language's response structure; may require adjustments to parsing logic if field names or types differ (mihomo/models/base.py)
4. Test with a live API call to ensure the new language returns valid data (examples/basic.py)

Migrate or add support for a new Mihomo API version

1. Create a new versioned model directory (e.g., mihomo/models/v3/) mirroring the structure of mihomo/models/v1/ (mihomo/models/v1/__init__.py)
2. Define all Pydantic models matching the new API response schema, using a new base class if the structure differs significantly (mihomo/models/v3/base.py)
3. Add a new fetch method to the MihomoAPI client (e.g., fetch_user_v3) that calls the versioned endpoint (mihomo/client.py)
4. Export the new version's models and add them to the main init.py for public use (mihomo/__init__.py)
5. Create an example demonstrating usage of the new API version (examples/basic.py)

Add custom validation or transformation logic for a data model

1. Implement a Pydantic field_validator or model_validator in the target model file (mihomo/models/character.py)
2. If the logic is shared across multiple models, add it to the base model class (mihomo/models/base.py)
3. Test the validator by creating example API responses in an example script (examples/basic.py)

• Pydantic v2 — Provides type hints, runtime validation, and auto-completion for parsed API responses; enables IDE support for accessing nested game data structures
• Python asyncio — Supports async HTTP requests to Mihomo API and concurrent data fetching for better performance in applications that manage multiple player profiles
• httpx (inferred) — Async-native HTTP client for making requests to the Mihomo API; preferred over requests for non-blocking I/O

• Maintain both V1 and V2 API models in separate directories

  • Why: The Mihomo API has evolved; users may depend on either version for backward compatibility
  • Consequence: Increased codebase size and maintenance burden; potential for model duplication, but enables gradual migration paths

• Icon URL transformation via client.get_icon_url() rather than automatic replacement

  • Why: Gives users control over when and how URLs are fetched; avoids blocking calls in the parsing stage
  • Consequence: Users must explicitly opt-in via replace_icon_name_with_url=True; adds extra step but preserves performance for use cases that don't need URLs

• No built-in caching at the client level

  • Why: Caching requirements vary by user (local file, Redis, in-memory); delegating to user code keeps the library lightweight
  • Consequence: Users managing many profiles must implement their own cache; examples show persistence patterns but no automatic TTL

• Real-time data synchronization — library fetches on-demand, not pushing updates
• Authentication — uses public Mihomo API that requires only UID, no login
• Game state modification — read-only access to player data
• Offline support — requires network connectivity to Mihomo API
• Non-English language parsing — data validation is agnostic to language; client only controls API language parameter

1. Two parallel model hierarchies (V1 and V2) must stay in sync manually—schema drift between mihomo/models/ and mihomo/models/v1/ can cause silent failures. 2. icon/preview/portrait fields are name-strings by default; replace_icon_name_with_url=True flag required to auto-convert to full URLs (easy to forget). 3. Mihomo API rate limits and cache refresh times (game updates may not reflect immediately) are not handled by the client. 4. No visible error handling examples for network timeouts or invalid UIDs in examples/.

• Pydantic Data Validation & Serialization — All models inherit from Pydantic BaseModel; understanding field validators, Config classes, and serialization modes is essential to extend/modify schemas without runtime errors
• Async/Await & aiohttp (or httpx) — Client.fetch_user() is async-first; you must understand event loops and await semantics to use this library correctly in production code
• Schema Versioning (V1 vs V2) — This repo deliberately maintains two parallel model trees to support deprecated API endpoints; understanding contract evolution and backward compatibility is critical for avoiding version mismatches
• Data Transfer Objects (DTO) — The entire architecture uses Pydantic models as immutable DTOs; this pattern decouples network contracts from business logic
• Language Enum & Localization — MihomoAPI(language=Language.EN) parameterizes all API calls; understanding how enums drive i18n is needed to add new language support
• Icon URL Resolution & Asset Mapping — get_icon_url() and replace_icon_name_with_url parameter show how asset identifiers are resolved to CDN URLs; critical for UI rendering in consuming apps
• Character Deduplication & Data Merging — tools.remove_duplicate_character() and merge functions handle real-world data quality issues (API caching, user roster changes); understanding stateful transformations is key to building reliable tracking apps

• KT-Yeh/genshin-py — Spiritual predecessor/sibling library; similar Pydantic model wrapper for Genshin Impact API, shares same design patterns and maintainer
• thesadru/genshin — Alternative Genshin Impact API client with similar async/Pydantic architecture; reference for multi-version API handling strategies
• MetaCubeX/meta-rules-dat — Same GitHub org; likely used for network/proxy configuration in mihomo ecosystem tools
• hoyo-py/hoyolab.py — HoYoverse API abstraction library supporting HSR, Genshin, ZZZ; complementary for unified game account queries

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 mihomo/models/ with pytest

The repo lacks test files for the core Pydantic models (character.py, equipment.py, player.py, stat.py, combat.py). Given this is a data parsing library, unit tests validating model initialization, field validation, and deserialization from Mihomo API responses are critical for reliability. This would catch breaking changes when the API updates.

• [ ] Create tests/ directory with init.py
• [ ] Add tests/test_character.py testing Character model parsing with sample API responses
• [ ] Add tests/test_equipment.py testing Equipment model validation and relationships
• [ ] Add tests/test_player.py testing PlayerInfo deserialization
• [ ] Add tests/test_models_v1.py testing v1 API response parsing (StarrailInfoParsedV1)
• [ ] Add pytest configuration to pyproject.toml with coverage thresholds
• [ ] Add test data fixtures with sample JSON responses from Mihomo API

Create GitHub Actions workflow to validate Pydantic model compatibility with API changes

The repo has build.yml and Delete.yml workflows but lacks automated testing against live or mock Mihomo API responses. Adding a scheduled workflow that validates all model definitions against API responses (or a versioned schema) would catch API breaking changes early and ensure models stay in sync with upstream changes.

• [ ] Create .github/workflows/api_validation.yml with scheduled trigger (daily/weekly)
• [ ] Add step to fetch sample responses from https://api.mihomo.me/sr_info_parsed/{test_uid}?lang=en for both v1 and v2
• [ ] Add validation step using pytest to deserialize responses into StarrailInfoParsed and StarrailInfoParsedV1 models
• [ ] Add step to report any deserialization failures or missing fields
• [ ] Add notification on failure (issue creation or workflow failure alert)

Add integration tests in examples/ with data persistence and merge validation

The examples/data_persistence.py and examples/merge_data.py files exist but lack corresponding integration tests. These demonstrate real-world usage patterns (caching, data merging) that should be tested to prevent regressions. This ensures the library's practical use cases remain functional.

• [ ] Create tests/test_integration.py for end-to-end scenarios
• [ ] Add test for data_persistence pattern: fetch user data, serialize to file, deserialize and validate equivalence
• [ ] Add test for merge_data pattern: fetch multiple users, merge datasets, validate no data loss or conflicts
• [ ] Add test for replace_icon_name_with_url feature with mock icon URL generation
• [ ] Add fixtures with mock API responses to avoid live API calls during testing
• [ ] Verify tests pass in build.yml workflow

• Add unit tests for mihomo/models/stat.py and mihomo/models/combat.py (no tests/ directory exists; critical for schema validation regression detection)
• Create a v1-to-v2 migration guide in docs/ or README (users with V1 integrations need concrete examples; currently only 2 separate examples, no comparison)
• Add docstrings and type hints to mihomo/tools.py functions (remove_duplicate_character, merge data); currently lack parameter descriptions and return type examples)

The codebase shows reasonable security posture for a data parsing library, but has moderate concerns around external API consumption without strict validation, dependency management practices, and lack of explicit security documentation. Primary risks are input validation for external API parameters and ensuring Pydantic models validate strictly. The project would benefit from explicit dependency pinning, security documentation, and enhanced input validation for user-supplied parameters passed to the external API.

• High · External API Dependency Without Validation — mihomo/client.py. The codebase fetches data from https://api.mihomo.me/sr_info_parsed/{UID}?lang={LANG} without apparent input validation or rate limiting. User-supplied UIDs and language parameters could be exploited for injection attacks or DoS attacks against the API. Fix: Implement input validation for UID (numeric validation, range checks) and language parameters (whitelist allowed values). Add rate limiting and request timeout configurations.
• Medium · Missing Dependency Pinning in pyproject.toml — pyproject.toml. The dependency file content was not provided. Without explicit version pinning and lock files, the project may be vulnerable to transitive dependency vulnerabilities or supply chain attacks. Fix: Use exact version pinning for all dependencies or implement a lock file (poetry.lock, requirements.lock). Regularly audit dependencies using tools like 'pip-audit' or 'safety'.
• Medium · Unvalidated User Data from External API — mihomo/models. Pydantic models consume data directly from the Mihomo API without apparent schema validation strictness. Malformed or malicious API responses could cause unexpected behavior or model corruption. Fix: Configure Pydantic with strict validation mode. Use explicit validators with ConfigDict(strict=True). Implement response validation and error handling for unexpected API response formats.
• Medium · Potential URL Injection in Icon URL Handling — mihomo/client.py. The README mentions 'client.get_icon_url' and 'replace_icon_name_with_url=True' functionality. If icon names/URLs are not properly sanitized, this could lead to URL injection or SSRF vulnerabilities. Fix: Validate all URLs returned from API before storing or using them. Use URL parsing libraries to ensure they match expected domains. Implement whitelist-based URL validation for API responses.
• Low · No HTTPS Enforcement Documentation — mihomo/client.py, README.md. While the API URL shown uses HTTPS, there's no explicit enforcement or documentation about secure communication requirements for the library. Fix: Document HTTPS-only requirement. Add configuration to prevent HTTP fallback. Consider implementing certificate pinning for enhanced security.
• Low · Missing Security Headers and API Documentation — Repository root. No security policy (SECURITY.md) or vulnerability disclosure guidelines are documented in the repository. Fix: Create SECURITY.md with vulnerability disclosure procedures and security best practices. Add security considerations section to README.
• Low · Insufficient Error Handling — mihomo/errors.py. The mihomo/errors.py file exists but without reviewing the content, error handling practices cannot be fully assessed. Poor error handling could leak sensitive information. Fix: Ensure error messages don't leak API structure, UIDs, or other sensitive information. Implement proper logging with sanitization.

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

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

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/MetaCubeX/mihomo 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.

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

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

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

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

# 4. Critical files exist
test -f "mihomo/__init__.py" \\
  && ok "mihomo/__init__.py" \\
  || miss "missing critical file: mihomo/__init__.py"
test -f "mihomo/client.py" \\
  && ok "mihomo/client.py" \\
  || miss "missing critical file: mihomo/client.py"
test -f "mihomo/models/__init__.py" \\
  && ok "mihomo/models/__init__.py" \\
  || miss "missing critical file: mihomo/models/__init__.py"
test -f "mihomo/models/base.py" \\
  && ok "mihomo/models/base.py" \\
  || miss "missing critical file: mihomo/models/base.py"
test -f "mihomo/models/v1/__init__.py" \\
  && ok "mihomo/models/v1/__init__.py" \\
  || miss "missing critical file: mihomo/models/v1/__init__.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 30 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~0d)"
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/MetaCubeX/mihomo"
  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).

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