Kilacraft-AI v2.1.3 Player Real-Time State Awareness、Knowledge-Base Retrieval Quality Boost

v2.1.3 - Player Real-Time State Awareness, Greeting System Update Reminders, Version Info Query Skill, Knowledge-Base Retrieval Quality Boost, AI Request Resource Optimization & Security/Stability Hardening

✨ New Features

• Built-in CLAUDE.md Reference: Starting with v2.1.3, the repository root includes a CLAUDE.md file for developers using AI coding tools for secondary development. Designed for Claude Code by default (auto-loaded every session), it covers the project architecture, i18n conventions, code conventions, key design constraints, and modification triggers. For other AI code tools (Cline, Cursor, Copilot Chat, etc.), copy the content into that tool's global rules or context file configuration equivalent
• AI Real-Time Player State Awareness: The AI can now automatically sense the player's current state — coordinates, health and hunger, held items and worn armor, current world, weather, and time of day — without the player having to explain repeatedly or trigger extra skill queries. For state-dependent requests like "take me back", "can this mine diamonds?", or "is there a desert nearby?", the AI responds with context-aware answers and advice. Enabled by default for all players — fully automatic, zero-config, and stores no data
• AI Login Greeting Proactively Notifies of New Versions: Long-running servers that are never restarted can still learn about plugin updates in time. When an admin with the kilacraft.admin.info permission logs in, the AI proactively mentions in the greeting whether a new version is available, stating the exact version number and download URL. Each version is announced to each admin only once — no repeated nagging. Network-check failures are handled silently without disrupting the normal greeting
• Version Info Query Skill: Admins can now ask the AI about plugin version info in natural language — "is there a new version", "what did the latest version update", "what is the download URL", "what features does v2.1.0 have". The AI fetches version info from Gitee/GitHub in real time and answers with the version number, release date, download URL, and full changelog. Requires the kilacraft.admin.info permission (default OP)

🔧 Improvements

• More Accurate Knowledge-Base Retrieval (highlight of this release): The BM25 algorithm now includes the IDF (Inverse Document Frequency) weight — rare, specialized keywords that appear in only a few docs rank higher, while ubiquitous generic words like "player" and "command" no longer dilute results. Recall accuracy of the default BM25 mode (used by the vast majority of servers) improves overall
• More Reliable Knowledge-Base Hot Reload: After switching the server language or toggling Embedding semantic retrieval, /kila reload now automatically rebuilds the knowledge-base chunks, statistics, and vector cache — preventing cache/content mismatches that cause retrieval anomalies or slow responses
• AI Request Resource Optimization: AI requests still in progress are automatically cancelled when a player goes offline, no longer continuing to drain API quota and server threads
• Embedding Cache Concurrency: Concurrent queries from multiple players no longer serialize and wait on each other (more noticeable on large servers with Embedding enabled)
• More Precise AI Error Hints: On a 404 error, the hint now distinguishes "model name may be incorrect" from "API URL may be incorrect", so server owners don't troubleshoot in the wrong direction
• Faster Security Cache Cleanup on Huge Servers: Cleanup of the recent-active-player cache no longer slows down noticeably as the player count grows
• More Traceable AFK Task Callbacks: When a callback can't be delivered because the player is offline, a console log is now recorded to help diagnose "the task didn't seem to fire"
• Auditable Command-Type Skill Operations: Command-type skills executed as OP (e.g. /tpa <target>) keep their cross-player capability while now also logging an audit trail
• More Reliable Server Anomaly Alert Notifications: Server performance anomaly alerts are now delivered to every authorized admin via the login greeting, instead of only the first one who comes online. Each alert is announced to each admin only once — no repeated nagging

🐛 Bug Fixes

• Corrected the comment direction for the retrieval relative threshold (relative_threshold) in knowledge.yml — the old comment wrongly labeled "raise = stricter" as "raise = more lenient", which could lead server owners to tune in the wrong direction; default value unchanged
• Hardened a defensive path that could cause a no-response hang when the secondary analysis hit an extreme exception before calling the AI
• Fixed hot-reloading the output config occasionally causing individual replies to briefly land on the wrong display channel
• Hardened the concurrency safety of AFK-task creation

⚠️ Compatibility

Upgrading from v2.1.2

1. Stop server, replace JAR, start; no database migration needed
2. Removed the deprecated console AI-chat entry: Chatting with the AI directly from the console via /kila <message> (an early debugging feature that became unusable as Agent capabilities grew — the console can't use most skills) has been fully removed. The console still keeps /kila plugins (third-party plugin integration), /kila doctor, /kila reload, /kila knowledge reload, and other management commands; the player side is completely unaffected
3. This is a quality release: no new config entries, no permission changes, no database changes — fully backward compatible
4. If you customized the knowledge.yml comments, you may regenerate it to get the corrected threshold notes (comment-only correction, no new config entries)

Kilacraft-AI v2.1.2 Knowledge Base Retrieval Reconstruction and Optimization; In-Game Query and Diagnostic Commands

v2.1.2 - New In-Game Query & Diagnostic Commands (usage / history / memory / skills / run / doctor / about), Knowledge-Base Retrieval Refactor & AI Error Handling

✨ New Features

• Corpus Seeding Dictionary: On startup, automatically scans the knowledge base for command names (e.g. /back → back) and compound identifiers (e.g. mob-farm, ender-dragon) and adds them to the HanLP tokenizer dictionary. No manual dictionary maintenance — the knowledge base content server owners write is itself the best tokenization reference
• Knowledge Base Writing Guide: The official Wiki provides ready-to-use knowledge-base writing templates (Chinese & English) — 7 writing rules + a complete usable sample; filling in per the template yields the best recall
• BM25 Document Length Auto-Statistics: On startup, automatically computes the actual average length of knowledge-base chunks so BM25 scores long and short docs more fairly. Advanced users may set a fixed avg_doc_length (default 0 = auto)
• In-Game Query & Diagnostic Commands: A set of commands for server owners and players to track AI usage and troubleshoot
  • /kila usage [player|all] [range]: AI usage stats (conversation turns, skill-call count & success rate, top skills, active players); supports self / specific player / server-wide views
  • /kila history [player] [page]: paginated conversation history
  • /kila memory [player]: view a player's profile (login stats + AI-analyzed 8-dimension profile)
  • /kila skills [page]: list currently available skills
• Force-Execute a Skill: /kila run <skill> <prompt> skips intent recognition and directly executes the named skill; supports multi-step tasks and gracefully falls back to normal chat if the intent can't be parsed
• Configuration Self-Diagnostic: /kila doctor runs 17 config checks (database / LLM connectivity / Spark / AI capability switches, etc.) to quickly locate misconfiguration; prints a redacted full-config dump to the console
• Version & Update Check: /kila about shows current version, latest version, and download URL

🔧 Improvements

• Retrieval Filter Refactor (hard threshold → soft/adaptive threshold): The old min_relevance_score (single hard threshold 30) is replaced by two-stage filtering
  • Noise floor: hard cutoff — anything below is dropped (default 25)
  • Relative threshold: soft cutoff — dropped if below top score × ratio (default 0.3)
  • Final threshold = max(noise floor, top score × relative threshold); mathematically guarantees at least 1 relevant result is returned — no more "relevant content exists but nothing comes back"
  • Tunable: lower both → more results (weakly related questions also answered); raise both → stricter (stay silent when unsure)
• BM25 Parameter Tuning: chunk overlap 30 → 50 chars (longer-doc context more coherent after segmentation); min chunk 25 → 20 chars (fewer short-but-useful paragraphs wrongly dropped); short-doc protection — chunks under 50 chars are exempt from the length penalty (old command-style docs were severely under-scored for being too short)
• Embedding Switches to Fusion Mode: No longer replaces BM25 with Embedding alone; instead BM25 + Embedding run in parallel and fuse via RRF (Reciprocal Rank Fusion) by rank. Chunks appearing in both paths rank higher, single-path chunks still participate — balancing exact keyword match and semantic understanding
• Custom Dictionary Auto-Syncs with Corpus: Hot-reloading the knowledge base re-scans the corpus and rebuilds the tokenizer dictionary; new command names / identifiers take effect immediately
• Project Stability: Fixed several NPE crashes from extreme inputs; hardened defenses against unknown user-authored docs
• AI Error Categorized Hints (highlight of this release): When an AI call fails, players now see an actionable, cause-locating hint (e.g. "The model name may be incorrect. Please check the 'model' setting in llm.yml", "API Key is invalid or lacks permission"); the raw error detail is also logged to console WARN for quick troubleshooting. Covers all AI call scenarios: normal chat, skills, tasks, login greeting, AFK notifications, server broadcast
• AI Timeout Friendly Hint: On response timeout, shows "AI response timed out. Please try again later" instead of exposing technical exception class names to the player
• AFK Task Callback Degradation Hint: When an AFK task's callback config fails to parse, clearly states the task will run in "notify-only" mode (callback action cannot execute), with the raw content logged for troubleshooting
• Code Standard Cleanup: Unified utility-class constructor style, removed fully-qualified class names, consolidated redundant method overloads (internal cleanup, no functional impact)
• Complete English Support: All command output and prompts now fully support Chinese/English bilingual; the English-environment experience is complete
• Permission-Aware Help Menu: /kila help shows only the commands the current player has permission to use
• Granular Query Permissions: Viewing self / others / server-wide are authorized separately (kilacraft.query.self, kilacraft.usage.other, etc.)

🐛 Bug Fixes

• Fixed NPE from missing null defenses in BM25Scorer.countOccurrences / EmbeddingCache.getVector / putVector / getNorm
• Fixed players getting stuck on "Thinking..." with no error message when an AI call failed due to config errors (wrong model name / Key / URL, rate limiting, server-side failure, etc.)
• Fixed AI error hints being mistakenly written into conversation history and polluting subsequent chat context (normal chat, login greeting, plugin-command paths)
• Fixed profile analysis writing dirty data and bumping the version number when the AI returned an abnormal structure (added an 8-field whitelist + length cap)
• Fixed occasional no-response hang when the AI secondary analysis failed during skill / task execution

⚠️ Compatibility

Upgrading from v2.1.1

1. Stop server, replace JAR, start
2. Recommended (for the full retrieval optimization): delete knowledge.yml and restart to let the plugin regenerate the latest version with the new config entries, then tweak as needed
3. Works without deleting knowledge.yml: the old min_relevance_score is ignored (no longer used), and retrieval filtering auto-applies the default soft thresholds (noise_floor=25, relative_threshold=0.3)
4. If you previously hand-maintained command names / identifiers in custom_dictionary.words, consider trimming them after upgrade — the new corpus-seeding dictionary auto-extracts these from knowledge-base content
5. Recommended to delete the language config files (language.yml / language_en.yml): the help-menu format was restructured and many command messages were added this build; keeping the old file leaves new command prompts missing and the help menu outdated. Delete and restart to regenerate the latest version, then re-apply your custom text
6. Server owners using English (en) mode should delete i18n/messages_en.yml: player-facing command text was migrated to the language.yml system this build, and the corresponding old keys were removed from messages_en.yml; deleting and restarting avoids leftover redundancy

Kilacraft-AI v2.1.1 Token consumption can be reduced by up to ~93%

v2.1.1 - Two-Phase Intent Recognition Architecture, Skill SPI Structured Response (needInfo Secondary Confirmation), Prompt System Restructuring, LLM Thinking Mode Governance

✨ New Features

• Two-Phase Intent Recognition Architecture (Core of this release): Splits the original "single full skill list to LLM" into two phases, significantly reducing Token consumption
  • Phase 1 (Coarse Selection): Sends only one line of name + description per skill; LLM determines which skill categories are needed; pure small talk returns null directly, skipping Phase 2 for normal AI conversation
  • Phase 2 (Precise Selection): Sends full details (actions + hints) only for skills selected in Phase 1, completing action selection and parameter extraction; validates skill_name against whitelist, invalid names rejected
  • Quantified benefits:
    • Pre-refactor baseline (single-phase, per recognition): main rules ~26K + all skills full ~80K (incl. BukkitAPI 77 actions ~38K) ≈ 106K chars
    • Pure small talk: only Phase 1 (returns null, no Phase 2) ≈ 8K chars, ↓ ~92% vs baseline
    • Normal skill (1 built-in skill hit, median full size ~3.1K): Phase 1 + Phase 2 ≈ 38K chars, ↓ ~65%
    • Complex skill (hit incl. BukkitAPI 77 actions): Phase 1 + Phase 2 ≈ 73K chars, ↓ ~32%
    • Token conversion (Chinese-mixed content ~0.6 token/char): baseline ≈ 64K → three scenarios ≈ 4.8K / 22.6K / 43.5K
  • Response speed: two-phase adds one ultra-lightweight Phase 1 call, but each recognition no longer carries the full skill list; net latency depends on model and network
• Skill SPI Structured Response Architecture (new needInfo secondary confirmation): Skill response semantics upgraded from "message-string prefixes" to typed status
  • New SkillResult.needInfo(message) factory: the official contract for third-party Skills to implement "needs info / secondary confirmation" (missing-param prompts, large-transfer confirmation, etc.); the framework emits a [NEED_INFO] marker and intent recognition drives the confirmation flow
  • SkillResult adds a typed SkillStatus enum (SUCCESS/FAILURE/NEED_INFO) + getStatus(); a new normalization layer SkillResultFormatter uniformly tags output to the LLM as [SUCCESS]/[FAILURE]/[NEED_INFO] — Skills write plain text, eliminating the inconsistency and double-tagging caused by hand-written prefixes
  • SPI Jar adds the SkillStatus class (6th class)
• Intent Recognition Prompt System Restructuring (Chinese/English synced): Added "Three Inviolable Rules" top-priority rule (default to multi-step when uncertain); single-intent/multi-step decision refactored to three-condition check (required param provided by user + completable in one action + no dependency on other actions' return values); arithmetic placeholders unified for amount/quantity/price/threshold; parameter missing enforced "query-then-act" (null required params prohibited); Phase 1 coarse-selection positioning strengthened (favor recall over precision)
• LLM Thinking Mode Governance: Normal conversation path auto-disables thinking for models with thinking on by default (MiMo, DeepSeek V4+, GLM 4.5+, Kimi K2+, Qwen3, Grok 4, Doubao thinking, MiniMax-M3, etc.); admin reasoning path injects enable params per model family; adapted OpenAI o-series / Doubao thinking max_completion_tokens. Resolves thinking tokens sharing max_tokens budget with output tokens causing empty output in MC scenarios (small quota)
• Placeholder Arithmetic Evaluation Utility (ArithmeticUtil): Evaluation logic extracted to a public utility class; application scope expanded from multi-step task scalar params (amount/quantity/price) to CUSTOM task threshold, supporting relative thresholds like "5 below current health" ({step_0.health}-5). Single binary operation only (+ - * /), pure regex, no injection risk
• JSON Auto-Repair Utility (JsonSafeGetUtil): Three-phase repair (filter excess closing → complete missing closing → remove trailing commas), abandons on cross-nesting, unified replacement of multiple duplicate implementations
• Startup Version Update Detection: Async GitHub latest release check, colored console box notification on new version, silent on failure

🔧 Improvements

• Diagnostic Model Fallback Mechanism: When admin.yml has no reasoning model configured, auto-falls back to llm.yml base chat model (reuses url/key/model only, max_tokens/timeout still use diagnostic-specific values to avoid report truncation), lowering the barrier for health monitoring
• Health Monitoring Unavailable Layered Diagnostics: Checks prerequisites one by one (model / guardian switch / Spark installed), gives precise hints; diagnostic report header adds a "Diagnostic Model" row marking the actual generation model
• DB History Load Count Tuning: loadFromDB limit changed from maxHistory×2 to maxHistory (default 20), reducing redundant loading
• AFK Task String Condition Value Display Optimization: EvaluationResult adds actualValueStr; string conditions (e.g., block types) display real values instead of 0/1 placeholders
• LLM Empty Response Friendly Hint: Returns "AI temporarily unavailable" to the player when streaming response is empty instead of an empty message (also logs SSE chunk count and recent raw data for troubleshooting)
• JSON Scenarios Disable max_tokens: Intent recognition, profile analysis, etc. no longer set max_tokens, preventing complex JSON truncation; GenericBukkitAPI description enhanced to improve Phase 1 classification accuracy
• Concurrency & Thread Safety: ConversationManager history queue upgraded to ConcurrentLinkedDeque + auto trim (MAX_HISTORY_SIZE=100); AFKTaskManager atomic registration prevents overflow; ProfileManager.flushAllProfiles single-connection batch update prevents cascade failure
• Code Cleanup & Observability: LLMProvider interface simplified, ThinkingModelCapable upgraded to functional interface; SkillIntentRecognizer exception catching with full stack trace; GreetingPromptBuilder event summary merge eliminates ~140 lines of duplication; unified history access; cleaned up redundant i18n wrappers and translation dead keys
• Configuration Hot-Reload Hardening: PersonalitiesConfigManager switched to snapshot replacement pattern, LLMConfigManager fields fully volatile
• Embedding Retrieval Optimization: chunk vector norm precomputed and cached, cosine similarity computation reduced by 2/3
• reconcileOnlineProfiles Single-Connection Batch: aligned with flushAllProfiles pattern
• Profile Analysis Prompt Temporal Optimization (Chinese/English synced): No longer extracts volatile transient data like balance, coordinates, and inventory counts; retains only long-term stable traits to avoid stale wrong info lingering in the profile; existing profiles are auto-cleaned on the next analysis
• Built-in Skills fully migrated to structured output: MarketActionSkill / CMISkill / MarketQuerySkill / CommandSkill stripped hand-written [FAILURE]/[NEED_INFO] prefixes (~80 sites), uniformly tagged by the framework normalization layer; TaskExecutor multi-step internal skip status switched to a typed enum, removing the old Chinese-prefix sniffing (fixes a latent classification mismatch under English locale)
• Secondary confirmation & prompt governance (Chinese/English synced): intent recognition prompts add a "confirmation-flow" rule (reads the concrete value from history when the player confirms a prior action); llm.yml system prompt uniformly documents marker semantics; messages_en.yml strips marker prefixes embedded in keys/values and fixes a duplicate key; Skill-SPI-Integration-Guide.md (zh+en) fully rewritten

🐛 Bug Fixes

• Fixed BM25Scorer.countOccurrences infinite loop on empty keyword causing mvn test to hang forever
• Fixed KnowledgeRetriever.splitByFixedSize off-by-one where content exactly at MAX_CHUNK_SIZE was split into an extra trailing chunk by the overlap rollback logic
• Fixed ConversationPersistenceService.mergeLoadedHistory clearing itself when loadedHistory and playerHistory are the same object via clear(), causing history loss (triggered when a player sends a message for the second time or later with valid in-memory history, via /ai command or chat listener path)
• Fixed thinking/reasoning models producing empty output in normal conversation (covered by thinking mode governance)
• Fixed profile analysis JSON parsing occasional failure (auto-repair then re-parse), CUSTOM task condition_plan null NPE, shutdown flushAllProfiles connection exception cascade failure, ConversationManager non-thread-safe ArrayDeque concurrent data loss
• Security & Stability Hardening: Fixed multiple stability and security boundary issues; added recent active player cache to strengthen data isolation

⚠️ Compatibility

Upgrading from v2.1.0

1. Stop server, replace JAR, start
2. MUST remove intent_prompts.yml / intent_prompts_en.yml: the two-phase architecture + prompt system restructuring changed this file's structure significantly (new phase1 section, full rewrite into 9 sections, new "Three Inviolable Rules", etc.). Old file contents override the code's built-in new defaults, so the two-phase architecture and this prompt refactor will not take effect — you must delete and restart to let the plugin regenerate it
3. Recommended (for full skill / model config optimization effects): the following config files are recommended to be deleted and regenerated (works without deletion, just missing some optimizations):
   • skills/afktask/AFKTaskSkill.yml / AFKTaskSkill_en.yml, skills/globalmarketplus/MarketActionSkill.yml / MarketActionSkill_en.yml, skills/bukkit/apis.yml / apis_en.yml
   • llm.yml (thinking mode governan...

Kilacraft-AI v2.1.0

v2.1.0 - Server Admin Management (Health Monitoring, Player Analysis, Audit Log), Code Architecture Restructuring

✨ New Features

• Server Health Monitoring System: AI-powered intelligent server monitoring and diagnostics system, solving the problems of difficult-to-locate server lag and time-consuming performance troubleshooting
  • Zero-Configuration Auto-Monitoring: Guardian thread runs 24/7 in the background, checking TPS, MSPT, CPU and other metrics every 10 seconds, automatically triggering diagnostics on anomaly detection
  • AI-Powered Diagnostics: Uses reasoning models (e.g. DeepSeek R1) for deep performance analysis, automatically generating Markdown diagnostic reports with precise bottleneck identification
  • Server Activity Metrics Collection: Captures chunk load changes and player distribution across worlds during the sampling window, compensating for Profiler's blind spot for non-CPU activities (I/O, disk, network)
  • Method-Level Hotspot Identification: Based on Spark Profiler's call stack analysis, pinpointing issues at the code level and identifying specific plugin performance impacts. Auto mode uses full-duration sampling, consistent with manual mode
  • On-Demand Precision Analysis: Supports /kilacraft profile start [duration] command for admins to analyze specific time periods as needed, solving intermittent performance issues
  • Intelligent Debouncing: Alert cooldown, sliding window frequency limits prevent resource exhaustion and ensure system stability
  • External Notification: When auto-triggered diagnostic analysis completes, push alert notifications to Discord or DingTalk group bots so admins are informed even when offline. Discord supports Embed card messages; DingTalk supports Markdown text + optional HMAC-SHA256 signature security. Push content only includes alert triggers, real-time snapshot metrics, and AI diagnosis summary — no full report file attachments to prevent sensitive information leakage
  • Independent Configuration Management: New admin.yml config file for centralized management of monitoring thresholds, reasoning model settings, external notification channels, and diagnostic prompts
• Server Health Alert Query (ServerHealthSkill): Query historical health alert records via natural language
• Player Behavior Analysis (PlayerAnalysisSkill): Online player trends, active player rankings, new player inflow, profile analysis coverage, social graph insights, specific player social relations query
• Audit Log Query (AuditLogSkill): View AI skill execution records, usage statistics, and failure logs
• New admin permission nodes: kilacraft.admin.health, kilacraft.admin.player, kilacraft.admin.audit (OP only by default)
• Spark plugin added as a soft dependency; admin features auto-disable when Spark is absent without affecting other functionality. Paper 1.21+/Folia/Purpur/Leaf/Pufferfish bundles Spark built-in — no separate installation needed
• New /kilacraft notify test command to test Discord/DingTalk notification channel configuration
• Diagnostic report file output (Markdown format, auto-saved to plugins/Kilacraft-AI/reports/)

🔧 Improvements

• Profile Analysis Prompt Temporal Optimization: First-time analysis excludes temporary transient states; incremental analysis actively cleans up outdated temporary content, preventing short-lived activities from persisting across multiple versions
• Self-Monitoring Text Logic Reuse: Extracted DiagnosticReportGenerator.appendSelfMonitoring() as a public static method, ServerHealthGuardian delegates to it, eliminating duplicate code
• Admin Skill Query Output Comprehensive Formatting: All admin Skills (PlayerAnalysisSkill 6 actions, AuditLogSkill 3 actions) message output fully optimized — timestamp humanization (epoch→yyyy-MM-dd HH:mm), UUID→player name resolution (online cache + DB query two-level strategy), event type translation (PLAYER_LOGIN→Login), relationship strength leveling (numeric→Stranger/Acquaintance/Friend/Good Friend/Close Friend), improving AI secondary analysis input readability
• AI Prompt Tone Unification: Normal conversation and secondary analysis prompts unified to concise and plain style, consistent with greeting system. Removed "enthusiastic" / "like chatting with a friend" wording, synchronized config files and hardcoded default values
• MySQL Connection Failure Auto-Fallback to H2: Automatically falls back to H2 embedded database when MySQL is unavailable during startup and hot-reload, ensuring persistence functionality remains available
• Audit Log Query Supports Querying Other Players: audit_log.query_logs added to security whitelist, admins can query a specific player's skill usage logs
• Hot-Reload Database Switch Resource Release Order: Adjusted to close old Provider before creating new Provider, avoiding H2 TCP port conflicts
• Hot-Reload DAO tablePrefix Refresh Consistency: All modules holding DAOs rebuild them during hot-reload to reflect the latest table prefix
• AI Greeting System Prompt & Injected Content Comprehensive Optimization: Three-layer structured health alert output (abnormal metrics / involved plugins / hotspot methods + trigger paths), injected content perspective correction (AI perspective uses player name instead of "you"), last location world prefix, prompt rules comprehensive strengthening (rule #3 milestone generalization & vague description prevention), and full i18n audit governance

🐛 Bug Fixes

• Fixed player profile version reset after hot-reload database switch (V8→V1): reconcileOnlineProfiles() did not reload profile from new database into memory cache, causing runtime state to overwrite new database's historical profile data
• Fixed NPE in initializeAdminSystem / syncGuardianState when databaseManager is not initialized

⚠️ Compatibility

Upgrading from v2.0.2

1. Stop server, replace JAR, start — no database migration needed
2. admin.yml config file is auto-generated on first startup
3. Spark plugin and a configured reasoning model API key in admin.yml are required for server health monitoring features
4. Admin management features default to OP-only access, no additional permission configuration needed
5. database.yml profile analysis prompts updated (new rule #5 for temporal relevance). To get the full prompt optimization effect:
   • Back up your custom config values in database.yml
   • Delete database.yml and restart the server to let the plugin regenerate the latest version
   • Manually merge your custom config values back into the new file
6. greeting.yml greeting prompts optimized (prompt rules comprehensively strengthened, injected content perspective corrected, health alerts structured). To get the full optimization effect:
   • Back up your custom config values in greeting.yml (and greeting_en.yml if using English mode)
   • Delete greeting.yml (and greeting_en.yml) and restart the server to let the plugin regenerate the latest version
   • Manually merge your custom config values back into the new file

New Permission Nodes

• kilacraft.admin.health (server health management, default OP)
• kilacraft.admin.player (player behavior analysis, default OP)
• kilacraft.admin.audit (audit log query, default OP)
• kilacraft.admin.* (all admin features, default OP)

Kilacraft-AI v2.0.2 (more stable, more secure, lower Token consumption)

v2.0.2 - Group Server Data Isolation, Skill Permission Pre-Filter, Incremental Profile Analysis, Profile Historical Snapshots, Placeholder Arithmetic, JSON Auto-Repair

✨ New Features

• Incremental Profile Analysis: Profile analysis upgraded from "generate fresh each time" to "old profile + new conversations fusion update", long-term player traits are not overridden by short-term fluctuations
  • Prompts support Chinese/English bilingual configuration (first analysis / incremental analysis configured separately), supports hot-reload
• Profile Historical Snapshots: New kca_profile_snapshot table, automatically saves a profile snapshot after each analysis, supports tracing any version's profile content and analysis time range, permanently retained
• Group Server Data Isolation: Supports BungeeCord/Velocity cross-server data sharing and isolation
  • database.yml adds group.server_id config, requires deleting old config file to regenerate
  • Conversation history, server events, skill audit logs isolated by server_id; player profiles & social relations are inherently cross-server shared (no server_id field, not configurable)
  • Schema upgraded to v2, auto-creates server_id indexes (H2 / MySQL compatible)
  • Supports group config hot-reload
• Skill Permission Pre-Filter: Dynamically filters available skills by player permissions during intent recognition; unauthorized skills excluded from LLM candidates
  • Skill interface adds getRequiredPermission(), all built-in Skills implement permission declaration
  • PluginPermissionEnum adds 8 Skill-level permission enums
• Placeholder Arithmetic Expressions: Multi-step tasks support {step_x.field + 10} style arithmetic
• LLM JSON Auto-Repair: Auto-completes missing closing braces in AFK task callback JSON

🐛 Bug Fixes

• Fixed API_KEY unconfigured prompt pointing to wrong config file (config.yml → llm.yml)
• Fixed getBoolean() silently returning default for "shared"/"isolated" string values (Critical)
• Fixed DatabaseManager.reload() not updating currentConfig on hot-reload
• Fixed enchanted golden apple event name exceeding length limit
• Fixed SQL syntax incompatibility in expired conversation/event/audit log cleanup using derived table syntax
• Fixed ProfileManager not rebuilding DAO on hot-reload, causing table_prefix changes to not take effect
• Fixed update() overwriting profile analysis fields with cached stale values: profile_data / profile_analyzed_at now exclusively written by updateProfileData(), runtime state updates no longer overwrite AI analysis results
• Fixed /ai clear not preventing DB history reload on next conversation: introduced one-time cleared marker to skip DB loading in loadHistoryIfNeeded
• Fixed AI greeting writing to memory history causing loadHistoryIfNeeded to skip DB load: empty check now excludes assistant-only history
• Fixed AI request errors being silently swallowed without console output
• Unified AI call timeout settings, fixed profile analysis timeout inconsistency with other AI calls

🔧 Improvements

• Distributed scheduled task race safety: watermark markers + SELECT FOR UPDATE row locks for distributed mutual exclusion
• database.yml group config section moved up + unified comment style
• Removed DataCleanupService.serverId dead code
• Improved key field length documentation comments
• Removed unused parameter from social relation interaction type enum
• ConditionPlan operator descriptions migrated to I18nService.tr() system
• Profile injection extended to all player-facing LLM output paths (secondary analysis, stage notifications, broadcast) with unified ProfileManager.injectProfileSummary() API
• Player profile dimensions expanded from 5 to 8 (added interests/boundaries/communication/spatial/facts), profile injection wording changed to "reference context" to avoid interfering with AI conversation judgment, incremental analysis auto-migrates legacy fields
• Incremental profile analysis now filters out version/analyzed_at metadata fields when injecting old profile, preventing LLM misinterpretation
• SPI integration guide, database config guide, and player profile & social relations system guide updated in both Chinese and English (corrected table field descriptions to match actual DDL, added incremental analysis workflow and snapshot mechanism)
• Intent recognition prompt global optimization: strengthened skill semantic matching standard, clarified "data retrieved could help answer" ≠ "skill matches user intent", constrained question decomposition to user's explicitly stated information needs
• BukkitStatsSkill prompt narrowed: limited to Minecraft vanilla statistics only, prohibited guessing or fabricating enum names
• CommandSkill prompt optimization: clarified matching boundary between "executable action" and "information query", removed examples unsuitable for survival players
• LLM secondary analysis prompt enhanced with boundary constraints, reducing hallucination and unreasonable inference
• Third-party Skill registration adds compatibility pre-check mechanism, registration failure does not affect main process

⚠️ Compatibility

Upgrading from v2.0.1

1. Stop server, replace JAR, start — defaults to standalone mode, no config changes needed
2. Database Schema auto-upgrades to v2 (adds profile_snapshot table + 3 server_id indexes), no manual migration needed
3. All new config entries have code-level default values — the plugin works correctly even without deleting any config files
4. Recommended (to get the full v2.0.2 prompt optimization effects): delete the following config files and restart the server to let the plugin regenerate the latest versions:
   • intent_prompts.yml / intent_prompts_en.yml (intent recognition prompts strengthened with semantic matching standards)
   • skills/bukkit/BukkitStatsSkill.yml / BukkitStatsSkill_en.yml (narrowed stats query matching scope)
   • skills/command/CommandSkill.yml / CommandSkill_en.yml (optimized command matching boundary)
   • llm.yml (strengthened prohibition on exposing statistics, old version has similar rules but weaker wording, optional)
   • database.yml (new group server config section + incremental profile prompts + profile dimensions upgraded to 8 + profile timeout adjustment, can manually add or delete to regenerate)
5. For group server mode, add group.server_id config to database.yml (leave empty for single-server)
6. v2.0.2 adds profile.incremental_system_prompt / incremental_system_prompt_en config entries (incremental analysis prompt when existing profile is present), leave empty to use built-in defaults

Upgrading from v2.0.0

1. Follow the "Upgrading from v2.0.1" steps above first
2. v2.0.1 added configurable profile analysis prompts (profile.analysis_system_prompt etc. in database.yml), delete database.yml to regenerate if you want to customize prompts
3. If using English mode (language: en), a greeting_en.yml English greeting config file will be auto-generated on first startup

Upgrading from versions before v2.0.0

1. You must read the v2.0.0 compatibility section first — that version introduced database persistence, config architecture refactoring, and other major changes
2. Upgrade steps:
   • Stop server and backup the entire plugins/Kilacraft-AI/ directory
   • Replace Kilacraft-AI.jar with the new version
   • On first startup, the plugin will auto-create new config files and database tables (Schema auto-upgrades to v2); old config files will not be deleted
   • Follow log prompts to manually migrate custom settings from the old config.yml to new config files (llm: → llm.yml, agent: → llm.yml, output: → output.yml, knowledge: → knowledge.yml)
   • If using MySQL, create the database in advance and configure database.yml
   • Strongly recommended to delete intent_prompts.yml / intent_prompts_en.yml and Skill config files under skills/ directory to let the plugin regenerate the latest versions
3. Conversation history in versions <2.0.0 was stored in memory only — there is no historical data to migrate, data accumulation starts fresh after upgrade

New Permission Nodes

• kilacraft.afk.task / kilacraft.bukkit_fx / kilacraft.bukkit_stats / kilacraft.bukkit_api (default true)
• kilacraft.cmi / kilacraft.command.execute / kilacraft.market.action (default OP)
• kilacraft.market.query / kilacraft.utility (default true)

Version Recommendation

Versions prior to v2.0.2 (including all v1.x releases) are no longer available for direct download. All users are recommended to upgrade to v2.0.2 for better system stability, security, and lower token consumption.