AgentCraft-Claw

# AgentCraft-Claw <p align="center"> <img src="https://img.shields.io/badge/Spring%20Boot-3.4.13-6DB33F?logo=spring-boot" /> <img src="https://img.shields.io/badge/Vue%203-3.5.29-4FC08D?logo=vue.js" /> <img src="https://img.shields.io/badge/Spring%20AI-1.1.4-6DB33F?logo=spring" /> <img src="https://img.shields.io/badge/Milvus-2.3.4-00A3E0?logo=apache" /> <img src="https://img.shields.io/badge/Java-17-007396?logo=java" /> <img src="https://img.shields.io/badge/Node-20%2B-339933?logo=node.js" /> </p> <p align="center"> <b>AgentCraft-Claw</b> — Next-generation Agentic Intelligent Knowledge System. With goal-driven Craft Engine as the core, integrating multi-Agent collaboration, seven-step RAG retrieval chain, multimodal understanding, private model deployment, MCP tool ecosystem, and TechBlogHub automatic knowledge base, to build an AI intelligent body platform with autonomous work ability. </p> --- ## Core Capabilities AgentCraft-Claw breaks through the traditional "document Q&A" boundary and constructs an intelligent body system with autonomous planning, execution, and delivery capabilities: - **Intelligent Q&A (Chat)** — Based on the seven-step retrieval chain (Vector + BM25 + RRF + Rerank + Compression) for precise RAG; the new `CraftEngine` flow generation adopts a fully asynchronous `.subscribe()` without blocking Tomcat threads, while the old `RagPipeline` still retains `.blockLast()` synchronous path, supporting SSE flow output, source traceability, and answer sentence-level traceability - **Answer Sentence-Level Traceability (Provenance)** — `ProvenanceService` splits the answer into sentences, matches each sentence with the most relevant recall slice, and generates `{sentenceIndex, sentence, references[]}` structured traceability; `SourcePayloadFactory` uniformly encapsulates chunkId, source document, page number, chapter, knowledge base ID, and webpage URL - **Intelligent Document Slicing** — `TextChunker` reads `rag.chunk_size` / `rag.chunk_overlap` from the AI configuration center, retains PDF page numbers and chapter metadata, supports FAQ/code/title-aware slicing strategies, and provides high-quality fragments for retrieval and traceability - **Task Workshop (Craft)** — Goal-driven task execution engine, supporting three execution modes: simple query, complex task (OTAC cycle + Swarm multi-Agent collaboration), and human-computer collaboration (checkpoint pause confirmation) - **RAG Evaluation Platform (Administrator)** — Builds evaluation datasets, batch imports standard questions and expected hit slices, asynchronously executes RAG pipelines, and calculates Recall@K / MRR / Context Precision / Answer Relevance / Faithfulness, supporting CSV/JSON result export - **Unified Audit Center (Administrator)** — Queries `qa_message` by time, user, session, feedback, and fallback status, with content preview automatically desensitizing phone numbers and emails, supporting CSV/JSON export - **Trace Tracking and Visualization (Administrator)** — Views single message Agent Trace, MCP call, Reflection Log, Provenance, and Craft execution trajectory, tool usage, and time consumption - **Knowledge Base Management** — Supports PDF/DOCX/MD/TXT multi-format upload, asynchronous parsing, intelligent slicing, and vectorized indexing based on independent thread pools, with concurrent deduplication and failure retry capabilities; introduces `KbDocumentVersion` version table and file content hash, realizing incremental updates (addition, deletion, and modification diff), avoiding full deletion and rebuilding - **Knowledge Base Version Management (Frontend)** — Version list, release, rollback, Diff comparison page (`KbVersionView.vue`), row-level Diff highlighting based on LCS algorithm, visual display of addition, deletion, and modification, with iOS 26 Liquid Glass design - **Internet Retrieval** — Integrates Tavily real-time webpage search, cross-verifies knowledge base and internet dual-source, ensuring information timeliness - **WebBridge Browser Automation** — Based on Playwright's real Chromium driver, supports webpage browsing, content extraction, screenshot, click, fill, scroll, and internet search; exposes `BrowserClaw` as an MCP tool to Agent and external clients, with URL whitelist and HarnessEngine double interception - **A/B Experiment Platform** — Administrators can create multi-type experiments and variants, with stable hash distribution by user ID; `AiConfigHolder` caches independent `ChatModel` by variant, realizing online experiments of models and parameters; frontend `/ab-experiments` management backend displays experiment indicators in real-time - **Voice Input** — Real-time WebSocket voice-to-text (DashScope Paraformer), supporting natural voice interaction - **Multimodal RAG** — Supports images, PDF screenshots as problem input, OCR text extraction (Tesseract / Ollama multimodal), multimodal Embedding (image + text joint vector), text retrieval and visual retrieval parallel fusion (RRF), Milvus dual Collection (text + image) - **Private Model One-Stop Machine** — Supports vLLM / Ollama / TGI local large model deployment, unified access through OpenAI-compatible API; `AiConfigHolder` extends `providerType` (CLOUD / VLLM / OLLAMA / LOCAL), dual-layer cache (variantModelCache + localModelCache); TEI (Text Embeddings Inference) private Embedding service; Spring Boot Actuator health check (`LocalModelHealthIndicator`) - **Self-Evolving Planner** — Automatically optimizes Planner Prompt and tool selection strategy based on historical task success rate; `PlannerMetricsCollector` collects plan generation time consumption, step success rate, and tool success rate matrix; `PlannerEvolutionScheduler` evolves regularly (daily at 3:17) and automatically triggers threshold (success rate < 70%); evolution log version management supports A/B comparison and rollback; strategy writes to Procedural Memory (global strategy template) - **Agent Collaboration Protocol** — Interoperates with external Agent platforms like CrewAI, AutoGen, and Dify; `AgentRegistryService` realizes external Agent registration/discovery/capability matching (Redis storage + heartbeat detection); `AgentTaskDelegator` supports task delegation (synchronous polling + asynchronous callback), with HarnessEngine security check before delegation; platform adapters: CrewAIAdapter, AutoGenAdapter, DifyAdapter; callback signature adopts HMAC-SHA256 anti-counterfeiting - **Enterprise-Level RBAC and SSO** — Resource-level permission control: role hierarchy inheritance, permission tree, data permission (ALL / OWN / DEPT / TEAM); custom annotation `@RequirePermission` + AOP interception; SSO supports LDAP/AD, OAuth2/OIDC; automatic user synchronization (SSO login automatically creates local account) - **MCP Tool Chain** — Exposes tool capabilities to external AI clients and automation processes through MCP protocol; `OpenClawController` provides external task submission entrance - **AI Configuration Center** — Dynamically updates parameters through database-driven API Key, model selection, internet switch, etc., without restarting services - **Data Dashboard** — `StatsServiceImpl` uniformly aggregates real `qa_message` / `kb_knowledge_base` / `mcp_tool_registry` / `tech_blog_article` data, with Controller only doing parameter verification and result packaging; backend built-in Micrometer observable indicators - **iOS 26 Liquid Glass** — Frontend adopts liquid glass design language, dynamic fluid gradient, multi-layer refraction highlight, and Spring dynamic effect - **Tech Blog Hub** — One-sentence instruction-driven, automatically captures Anthropic / OpenAI / Google DeepMind / Meta AI and other AI factory technical blogs, after translation, summary, tagging, Reviewer scoring, vectorization, generates offline browsable static knowledge base site --- ## Architecture Design ``` +------------------------------------------------------------------+ | Access Layer | | +--------+ +--------+ +-------------+ +------------------+ | | | REST | | SSE | | WebSocket | | MCP / OpenClaw | | | | API | | Stream | | Speech | | Protocol | | | +--------+ +--------+ +-------------+ +------------------+ | | +-------------------+ +------------------------------------+ | | | Multimodal Input | | Agent Interop Gateway | | | | (Image / PDF) | | (CrewAI / AutoGen / Dify) | | | +-------------------+ +------------------------------------+ | +------------------------------------------------------------------+ | Orchestration Layer | | +--------------+ +------------------+ +---------------------+ | | | CraftEngine | | SelfEvolvingPlanner| | SwarmOrchestrator | | | | (OTAC cycle) | | (Self-Evolving) | | (Multi-Agent Collaboration) | | | +--------------+ +------------------+ +---------------------+ | | +--------------+ +--------------+ +---------------------+ | | | LoopEngine | | HarnessEngine| | OpenClawGateway | | | | (Execution Loop) | | (Constraint Governance) | | (External Tool Protocol) | | | +--------------+ +--------------+ +---------------------+ | +------------------------------------------------------------------+ | Agent Layer | | Planner | Researcher | Analyst | Writer | Coder | Reviewer | | | | Browser | | +------------------------------------------------------------------+ | Claw Tools Layer | | +--------------+ +------------+ +----------+ +------------+| | | KnowledgeClaw| | ResearchClaw| | CodeClaw | | BrowserClaw|| | | (Seven-Step Retrieval) | | (Multi-Source Research) | | (Code) | | (Browser) || | +--------------+ +------------+ +----------+ +------------+| | +-------------------+ +-------------------------------------+| | | MultimodalClaw | | TechBlogHub (RSS/Sitemap/API discovery | | | (OCR+Visual Retrieval) | | → crawling → translation → summary → tagging → indexing | | +-------------------+ | → offline site export） | | +-------------------------------------+| +------------------------------------------------------------------+ | Memory Layer | | +----------+ +----------+ +----------+ +-----------------+ | | | Working | | Semantic | | Episodic | | Procedural | | | | Memory | | Memory | | Memory | | Memory | | | | (Redis) | | (MySQL) | | (MySQL) | | (MySQL) | | | +----------+ +----------+ +----------+ +-----------------+ | +------------------------------------------------------------------+ | Infrastructure Layer | | Spring Boot | Spring AI | MyBatis Plus | MySQL | Redis | Milvus | | | | MinIO | Prometheus | Grafana | Loki | Alertmanager | | | | vLLM / Ollama / TGI / TEI (Local LLM) | | +------------------------------------------------------------------+ ``` ### Three Execution Modes | Mode | Trigger Condition | Execution Process | Applicable Scenario | | ----------------- | ------------------------------------ | ------------------------------------------------------------ | ------------------------------------ | | **SIMPLE** | Short questions, interrogative words | Directly calls ReAct Agent engine -> Knowledge base retrieval -> Immediate response | "What is RAG?" | | **COMPLEX** | Contains complex verbs like analysis/generation/report | AutoPlanner -> Swarm orchestration -> Multi-Agent collaboration -> LoopEngine iteration -> Result synthesis | "Generate an AI industry research report" | | **COLLABORATIVE** | Contains "help me confirm" or "show me first" | Plan -> Checkpoint pause -> Human confirmation -> Continue execution | "Help me confirm if this plan is feasible" | ### Swarm Deep Execution Complex tasks (COMPLEX mode) are driven by `SwarmOrchestrator` for multi-Agent collaboration, with core mechanisms including: - **DAG Topology Parallelism**: `AutoPlanner`-generated step lists are layered by `DagScheduler` using Kahn algorithm, with dependency-free steps executed in parallel on the same layer ( `CompletableFuture` + fixed thread pool), and dependent steps waiting serially by layer. - **Reviewer Deep Verification**: Checkpoint steps trigger Reviewer Agent, outputting structured scoring and improvement suggestions in four dimensions: **factuality / completeness / security / format**; if not passed, can pause and wait for human intervention (COLLABORATIVE mode) or skip non-critical steps. - **Long-Term Memory Recall**: Before each step execution, `MemoryRecallService` recalls from **Working (current Craft context), Semantic (facts/preferences/constraints, MySQL persistence), Episodic (historical step experience, MySQL persistence), Procedural (global strategy template, MySQL persistence)** four-layer memory, fusing with RRF and writing to working context; after execution, automatically precipitates semantic facts and episodic experience. ``` +-----------+ +-----------+ +-----------+ | Step A |---->| Step C |---->| Step E | +-----------+ +-----------+ +-----------+ | ^ v | +-----------+ +-----------+ | Step B |---->| Step D | +-----------+ +-----------+ Layer 1: A, B parallel Layer 2: C, D parallel (dependent on A/B) Layer 3: E serial (dependent on C/D) ``` ### Execution Loop and Constraint Governance # LoopEngine（Execution Loop） Complex tasks are continuously monitored by `LoopEngine` during execution to prevent infinite loops and budget overruns: - **Otac Loop**: Advances tasks through a four-step cycle of Observe-Think-Act-Check, checking execution results after each Act to see if exit conditions are met. - **Reviewer Loop**: The Reviewer Agent scores key outputs on factuality, completeness, safety, and format; if not passed, it generates improvement suggestions and re-executes. - **Budget Loop**: Tracks budget across three dimensions: Token quantity, number of steps, and time spent. If thresholds are exceeded, it triggers degradation or suspension. - **Reflection Loop**: A self-correction loop that runs up to 2 rounds, assessing answer confidence each round; if not passed, it supplements retrieval or rewrites the question. Loop priority: `OtacLoop` > `ReviewerLoop` > `ReflectionLoop` > `BudgetLoop`. #### HarnessEngine（Constraint Governance） `HarnessEngine` checks constraints at input entry, output sending, and key execution nodes: - **PRE_INPUT**: Sensitive word filtering, Prompt injection detection, permission verification, input length and format constraints. - **PRE_EXECUTION**: Plan/URL pre-check, budget and quota pre-verification. - **PER_STEP**: Step-level budget, output, and URL whitelist checks. - **POST_OUTPUT**: Factual consistency verification, safety bottom line, output format check, and secondary filtering of taboo words. - If any stage triggers a constraint, it returns a structured `HarnessDecision`, and the upper layer decides whether to allow, alert, or intercept based on `BLOCK` / `HUMAN` / `DEGRADE` / `WARN` / `ALLOW`. #### Benefits of Loop / Harness to the System | Dimension | Benefits | Typical Scenarios | | ------------ | ------------------------------------------------------------ | ------------------------------------------------------------ | | **Reliability** | LoopEngine prevents tasks from falling into dead loops, Reviewer and Reflection ensure output quality lower bound | Automatic retry of low-quality steps during complex report generation | | **Controllability** | BudgetTracker limits by Token/step/time dimensions, avoiding single request consuming all resources | User submits tasks like "analyze the entire site log" that may produce super long chains | | **Safety** | HarnessEngine adds two layers of control before and after LLM, intercepting Prompt injection and harmful output | Users try to jailbreak or ask prohibited content | | **Observability** | Each Loop cycle and Harness decision are tracked via Micrometer, allowing tracing on the dashboard | Observing indicators like `craft.loop.round`, `harness.decision.total` in Grafana | | **Auditability** | Harness decisions and Loop logs are written to `qa_message`'s `agent_trace` / `reflection_log` | Post-event review of why a certain answer was intercepted or retried | #### Association with Other Components ``` ┌─────────────────────────────────────────────────────────────────┐ │ User / External Client │ └─────────────┬───────────────────────────────────────────────────┘ │ Request ▼ ┌─────────────────────────┐ PRE_INPUT ┌─────────────────────┐ │ CraftChatController │ ───────────────> │ HarnessEngine │ │ /api/v2/chat/stream │ │ Input constraint governance │ └─────────────┬───────────┘ └──────────┬──────────┘ │ │ Pass/Intercept ▼ ▼ ┌─────────────────────────┐ ┌─────────────┐ │ CraftEngine │ <────── Drive OTAC ────> │ LoopEngine │ │ (SIMPLE/COMPLEX/COLLAB)│ Reviewer/Budget │ Execution loop │ └─────────────┬───────────┘ └─────────────┘ │ ▼ ┌─────────────────────────┐ POST_OUTPUT ┌─────────────────────┐ │ SwarmOrchestrator │ ──────────────────> │ HarnessEngine │ │ (Multi-Agent DAG parallel) │ │ Output constraint governance │ └─────────────────────────┘ └──────────┬──────────┘ │ Pass/Intercept ▼ ┌─────────────────────────┐ Tool Invocation ┌─────────────────────┐ │ McpToolRegistry │ <──────────────── │ OpenClaw/MCP │ │ (@Tool annotation registration) │ │ External protocol layer │ └─────────────────────────┘ └─────────────────────┘ ``` - **With CraftEngine**: `CraftEngine` calls `LoopEngine.run()` in SIMPLE/COMPLEX/COLLABORATIVE modes, and Loop decides to continue, retry, or pause; meanwhile, it submits user input and final output to `HarnessEngine` for verification. - **With SwarmOrchestrator**: Complex tasks entering Swarm undergo Harness checks before and after each DAG layer execution and ReviewerLoop review; Harness interception terminates the current layer and returns a decision to `CraftEngine`. - **With SafetyGuard / GuardRailService**: Harness's PRE_INPUT / POST_OUTPUT constraints reuse `SafetyGuard`'s emergency word detection and `GuardRailService`'s semantic fence, forming a three-layer protection of "rules + semantics + strategies". - **With MCP / OpenClaw**: External tool requests via OpenClaw undergo Harness input checks and output checks before returning; non-compliant calls are recorded in audit logs. - **With MetricsService / Grafana**: `LoopEngine` reports `craft.loop.round`, `craft.reviewer.retry`; `HarnessEngine` reports `harness.decision.total` (by `level`, `decision` tags), displayed on the same dashboard as RAG, LLM, and TechBlogHub metrics. - **With Memory**: Loop's Reviewer results and Reflection logs are written to `SharedMemoryBus`'s current Craft context and persisted to `qa_message`, supporting long-term experience replay. ### LLM Call Resilience Governance Large model calls are the core dependency of the system and are prone to issues like sudden latency spikes, quota exhaustion, or service unavailability. The system uniformly packages `ChatModel` with `ResilientChatModel`, integrating multiple layers of protection from Resilience4j: - **CircuitBreaker**: Automatically opens a circuit breaker based on failure rate/slow call rate, avoiding fault spread; returns a structured degraded response upon triggering. - **RateLimiter**: Limits the number of LLM requests within a unit time based on configuration; returns a friendly prompt when exceeded. - **Bulkhead**: Limits concurrent LLM call numbers, preventing single-point dependency from consuming all thread resources. - **TimeLimiter**: Sets a configurable timeout for synchronous `call()`, triggering degradation upon timeout. - **Fallback**: Upon circuit breaker/rate limiter/bulkhead/time limiter triggering, uniformly returns a `ChatResponse` with a prompt, without throwing exceptions that cause SSE disconnection. `ResilientChatModel` covers both synchronous `call(Prompt)` and streaming `stream(Prompt)` paths: the synchronous path uses a `Callable` decorator chain; the streaming path applies rate limiting, isolation, and circuit breaking on Flux using Resilience4j Reactor Operator. `LlmResilienceConfig` exposes four named instances: `llmCircuitBreaker`, `llmRateLimiter`, `llmBulkhead`, `llmTimeLimiter`, with all thresholds externalized to `application.yml` via `llm.resilience.*` configuration items, supporting runtime adjustments without code changes. ### Multimodal RAG The system supports directly using images or PDF screenshots as problem inputs, enabling "visual question-answering" capabilities: - **OCR Text Extraction**: Supports Tesseract local OCR and Ollama multimodal models (like LLaVA) for extracting text content from images, switchable via the `MULTIMODAL_OCR_ENGINE` environment variable. - **Multimodal Embedding**: Images are processed by a multimodal embedding service (image + text joint vector) to generate vectors, aligning with text vectors in the same semantic space. - **Dual Collection Storage**: Milvus maintains independent text collections (`kb_text_collection`) and image collections (`kb_image_collection`), with image records including `image_vector`, `ocr_text`, `source_doc_id`, and `page_number`. - **Parallel Retrieval Fusion**: Text retrieval (Vector + BM25) and visual retrieval (image vector similarity) are executed in parallel and fused via RRF, then sent to reranking and context compression. - **Interface**: `POST /api/v2/multimodal/chat` SSE streaming output, supporting `image` (Base64 or URL) and `message` combination in the request body. ### Private Model Access The system supports deploying large models locally or in private clouds using frameworks like vLLM, Ollama, or TGI, reducing dependency on external cloud APIs: - **Unified OpenAI-compatible API**: Local models are exposed through an OpenAI-compatible API, uniformly encapsulated as `ChatModel` by `AiConfigHolder`, transparent to upper layers. - **ProviderType Extension**: `AiConfigHolder` adds a `providerType` enum (CLOUD / VLLM / OLLAMA / LOCAL), supporting simultaneous access to cloud and multiple local models. - **Dual-layer Cache**: `variantModelCache` (variant level) + `localModelCache` (local model instance level) avoids repeated `ChatModel` construction; automatically invalidates and reloads upon configuration changes. - **TEI Private Embedding**: Private deployment of Embedding models through HuggingFace Text Embeddings Inference (TEI) service, replacing cloud Embedding APIs. - **Health Check**: `LocalModelHealthIndicator` implements Spring Boot Actuator's `HealthIndicator`, periodically detecting local model connectivity and automatically removing unhealthy models from the routing pool. - **Admin Interface**: Local model CRUD (`POST /api/admin/local-models`, etc.) + connectivity testing (`POST /api/admin/local-models/{id}/test`) ### Self-Evolving Planner `SelfEvolvingPlanner` enables the task planning capability to self-evolve during system operation, continuously optimizing Planner Prompt and tool selection strategies: - **Metric Collection**: `PlannerMetricsCollector` gathers metrics on plan generation time, step success rate, tool success rate matrix, and overall task success rate. - **Scheduled Evolution**: `PlannerEvolutionScheduler` executes an evolution task daily at 3:17 AM, automatically analyzing recent metrics and generating optimized Prompt templates and tool selection weights. - **Threshold-triggered Evolution**: Automatically triggers urgent evolution if the overall success rate falls below 70%, without waiting for the scheduled window. - **Version Management**: `PlannerEvolutionLog` records strategy changes, metric comparisons, and effective times, supporting A/B comparison and one-click rollback. - **Strategy Precipitation**: Evolved strategies are written to Procedural Memory (global strategy templates) and shared across all subsequent Craft tasks. - **Safety Boundary**: The evolution process is constrained by HarnessEngine, with new strategies requiring Reviewer verification before taking effect, preventing strategy degradation. ### Agent Collaboration Protocol The system interacts with external Agent platforms like CrewAI, AutoGen, and Dify through `AgentInteropGateway`, building an open Agent ecosystem: - **Registration and Discovery**: `AgentRegistryService` provides external Agent registration, discovery, and capability matching; registration information is stored in Redis with TTL heartbeats, and expired Agents are automatically offline. - **Capability Matching**: Tasks are delegated to the most suitable external Agent based on capability tags (`capabilityTags`) and trust scores. - **Task Delegation**: `AgentTaskDelegator` supports synchronous polling (blocking wait for results) and asynchronous callbacks (receiving results via callback). - **Platform Adapters**: `CrewAIAdapter`, `AutoGenAdapter`, and `DifyAdapter` encapsulate platform-specific invocation protocols and authentication methods, with unified calls through `AgentInteropGateway`. - **Callback Security**: Asynchronous callbacks include HMAC-SHA256 signatures (`X-Interop-Signature`) for authentication and anti-tampering. - **External Endpoints**: - `POST /api/openclaw/agents/delegate` — Submit cross-platform delegated tasks - `POST /api/openclaw/agents/callback` — Receive external Agent callback results ### RBAC Permission Model The system implements an enterprise-level resource-level permission control, meeting multi-tenancy and organizational structure requirements: - **Role Hierarchy Inheritance**: Roles support parent-child inheritance (`parent_role_id`), with child roles automatically inheriting parent roles' permissions. - **Permission Tree**: Permissions are organized in a tree structure (`permission_tree` table), supporting four levels of granularity: menu, button, API, and data. - **Data Permissions**: On top of role-permission, add data scope (`data_scope`): ALL (all), OWN (self), DEPT (department), TEAM (team), linked with organizational structure. - **Annotation-driven**: `@RequirePermission` custom annotation + AOP interception directly on Controller methods, declaratively controlling access permissions; supports `logical = AND / OR` combining multiple permissions. - **Dynamic Authorization**: Permission changes trigger real-time refresh of node caches via Redis publish-subscribe, without service restart. - **Admin Interface**: Role management, permission tree management, user role assignment, data permission configuration. ### SSO Single Sign-On The system supports integration with the enterprise's existing identity system for seamless login: - **LDAP/AD Authentication**: Supports standard LDAP / Active Directory protocols, configurable via `LDAP_URL`, `LDAP_BASE_DN`, `LDAP_BIND_CREDENTIAL`, etc. - **OAuth2/OIDC**: Supports standard OAuth2 authorization code mode and OIDC identity token, compatible with enterprise WeChat, DingTalk, Feishu, and Keycloak. - **Automatic User Sync**: Upon SSO login, the system automatically queries user information and creates/updates accounts (`sys_user`) locally; assigns default roles on the first login. - **Configurable**: SSO switches and provider parameters are configured via `.env` environment variables, allowing code-free switching of identity sources. - **Admin Interface**: SSO configuration viewing and connectivity testing (`POST /api/admin/sso/test`) ### OpenClaw Protocol OpenClaw is an open protocol exposing tool capabilities, compatible with MCP (Model Context Protocol) specifications: - **Tool Registration**: Backend registers capabilities to `McpToolRegistry` via `@Tool` annotation, automatically discovered at runtime; TechBlogHub tools are also uniformly registered. - **Tool Discovery**: External clients can retrieve tool metadata, parameter schema, and examples via `GET /api/mcp/tools`. - **Tool Invocation**: `POST /api/mcp/tools/{id}/test` supports online testing; `/api/mcp/invoke` allows authorized clients to call in JSON-RPC style. - **External Task Submission**: `POST /api/openclaw/tasks` allows external Agents to submit tasks, forwarded to `CraftEngine` execution and event pushback via callbackUrl. - **Security Boundary**: All external calls require JWT authentication, with sensitive tools additionally verifying role permissions; call results are written to audit logs. ## Technology Stack ### Backend (Spring Boot 3.4) | Layer | Technology | Description | | ---------------- | -------------------------------------------------------- | ------------------------------------------------------------ | | Framework | Spring Boot 3.4.13 + Spring AI 1.1.4 | AI-native development framework | | Security | Spring Security + JWT (jjwt 0.12.5) + RBAC/SSO | Stateless authentication, BCrypt encryption, HttpOnly Cookie, SSE one-time ticket, LDAP/AD/OAuth2/OIDC | | ORM | MyBatis Plus 3.5.7 | Efficient CRUD + conditional constructor | | Vector Database | Milvus 2.3.4 | 1024-dimensional vector retrieval, dual Collection (text + image) | | Cache | Redis 7 + Lettuce | Frequency cache + session memory + SSE ticket + Agent registry | | Object Storage | MinIO 8.5.7 | Document file storage | | Document Parsing | Apache PDFBox 3.0 + POI 5.2 | PDF/DOCX extraction | | Keyword Search | Lucene 8.11 + smartcn tokenizer | Chinese BM25 retrieval | | OCR Engine | Tesseract 5.x / Ollama multimodal | Image/PDF screenshot text extraction | | Multimodal Embedding | Ollama multimodal / compatible service | Image + text joint vector | | Local Large Model | vLLM / Ollama / TGI | OpenAI-compatible API private deployment | | Local Embedding | TEI (Text Embeddings Inference) | HuggingFace private Embedding service | | Resilience Governance | Resilience4j 2.1.0 | LLM / search / tool call circuit breaker, current limiting, isolation, timeout, and downgrade | | Speech Recognition | DashScope Paraformer | Real-time streaming ASR | | Internet Search | Tavily API | Real-time web search | | AI Configuration | AiConfigHolder + AiConfigInitializer | Database-driven hot update, atomic replacement model instance, support CLOUD/VLLM/OLLAMA/LOCAL multi-provider | | Blog Ecosystem | ROME 2.1.0 / jsoup 1.17.2 / flexmark 0.64.8 / Playwright 1.44.0 | RSS/Sitemap/content capture/translation/summary | | Observability | Micrometer Prometheus + Loki Logback Appender 1.5.2 | Metrics and logs | ### Frontend (Vue 3 + Vite) | Layer | Technology | Description | | --------- | ------------------------------------------- | ------------------------------------------------------------ | | Framework | Vue 3.5.29 + Vite 7.3 | Composition API | | UI Library | Element Plus 2.13.5 | On-demand automatic import of components (unplugin-vue-components), reducing packaging volume | | State Management | Pinia 3.0.4 | Type-safe Store | | Router | Vue Router 5.0.3 | Dynamic routing + administrator guard | | Design System | iOS 26 Liquid Glass | Liquid glass, dynamic gradient, colored halo | | Charts | ECharts 6.0 | Data visualization | | Markdown | marked 17.0 + highlight.js + DOMPurify | Rich text rendering + XSS filtering | | Tool Library | VueUse 14.2 | Composition API tools | ### Infrastructure (Docker Compose) | Service | Container Port | Host Port | Description | | ------------------- | ---------------- | ---------- | -------------------------------------------- | | MySQL | 3306 | 3307 | Business database | | Redis | 6379 | 6380 | Cache + session + SSE ticket + Agent registry | | Milvus | 19530 | 19530 | Vector database | | MinIO API | 9000 | 9002 | Object storage API | | MinIO Console | 9001 | 9003 | Object storage console | | Backend | 8080 | 8080 | REST + SSE API | | Frontend | 80 | 80 | Main entrance | | Prometheus | 9090 | 9090 | Metrics scraping and querying | | Grafana | 3000 | 3000 | Observability dashboard | | Loki | 3100 | 3100 | Log receiver | | Alertmanager | 9093 | 9093 | Prometheus alert notification management | | etcd | 2379 | — | Milvus metadata dependency | | vLLM / Ollama / TGI | 8000 / 11434 / 8080 | On-demand mapping | Private large model service (optional) | | TEI | 8080 | On-demand mapping | Private Embedding service (optional) | ## Project Structure ``` AgentCraft-Claw/ | |-- backend/ # Backend (Spring Boot) | |-- pom.xml | |-- Dockerfile # Backend container image (multi-stage build) | |-- Dockerfile.debug # Backend debug image | |-- docker-compose.dev.yml # Infrastructure only (MySQL/Redis/MinIO/Milvus/etcd) | |-- src/main/java/com/simon/agentcraft/ | | |-- AgentCraftApplication.java | | |-- abtest/ # A/B testing platform (traffic routing, experiment management, event tracking, metric aggregation) | | |-- agent/ # ReAct Agent core (single-turn conversation chat flow) | | |-- claw/ # Claw unified tool abstraction and registry center | | |-- common/ # Result encapsulation, exceptions, constants, JWT | | |-- config/ # Configuration center (AI hot update, MCP, Milvus, MinIO, Redis, RestTemplate) | | |-- controller/ # REST + SSE + MCP controller | | |-- craft/ # Craft Engine (OTAC task workshop) + AutoPlanner + SelfEvolvingPlanner | | | |-- planner/ # Adaptive planning (PlannerMetricsCollector / PlannerEvolutionScheduler) | | |-- entity/ # Entity + DTO + VO | | |-- harness/ # HarnessEngine (PRE_INPUT/PRE_EXECUTION/PER_STEP/POST_OUTPUT constraint governance) | | |-- llm/ # LLM access and resilience governance | | | |-- local/ # Private model management (LocalModelService / LocalModelHealthIndicator) | | | |-- resilience/ # Resilience4j wrapped resilience ChatModel | | |-- loop/ # LoopEngine (Otac/Reviewer/Budget/Reflection) | | |-- mapper/ # MyBatis Plus Mapper | | |-- mcp/ # MCP tool (@Tool annotation exposure) | | |-- memory/ # Four-level memory (Working/Semantic/Episodic/Procedural) | | |-- metrics/ # Micrometer metric encapsulation | | |-- multimodal/ # Multimodal RAG (OCR / multimodal embedding / visual retrieval fusion) | | |-- openclaw/ # OpenClaw protocol (exposing task submission capability) | | | |-- interop/ # Agent collaboration protocol (AgentRegistryService / AgentTaskDelegator / platform adapter) | | |-- reflection/ # CheckpointService (human-computer collaboration checkpoint) | | |-- safety/ # GuardRailService (multi-dimensional inspection) | | |-- security/ # JWT authentication + Spring Security + RBAC + SSO | | | |-- rbac/ # RBAC permission (role inheritance, permission tree, data permission, @RequirePermission) | | | |-- sso/ # SSO single sign-on (LDAP/AD / OAuth2/OIDC) | | |-- service/ # Business service layer | | | |-- alert/ # Alert channel SPI and implementation | | | |-- code/ # Code generation/review | | | |-- impl/ # Service implementation | | | |-- knowledge/ # Document processing + Milvus + MinIO | | | |-- rag/ # RAG seven-step retrieval chain | | |-- swarm/ # SwarmOrchestrator (multi-role collaboration) | | |-- techblog/ # TechBlogHub module (crawling/translation/summary/tag/indexing/exporting) | |-- src/main/resources/ | | |-- application.yml # Main configuration (LLM/DB/Redis/Milvus/MinIO/TechBlogHub/multimodal/local model) | | |-- logback-spring.xml # Loki log push configuration | | |-- prompts/ # Safety review, query rewriting, knowledge Q&A, TechBlogHub, Planner evolution prompts | |-- src/test/ # Unit test + integration test | | |-- java/com/simon/agentcraft/ | | |-- resources/application-test.yml | | |-- resources/schema.sql # H2 test database table structure | |-- frontend/ # Frontend (Vue 3) | |-- package.json | |-- vite.config.ts # Development proxy, code splitting | |-- Dockerfile # Frontend container image (Node 22 -> nginx) | |-- nginx.conf # Reverse proxy /api, SSE no buffering, history mode | |-- src/ | | |-- api/ # Axios API encapsulation (chat/craft/knowledge/mcp/techBlog etc.) | | |-- components/ # Components (including Liquid Glass) | | |-- layout/ # Main layout | | |-- router/ # Routing configuration (including admin guard) | | |-- stores/ # Pinia state (user/theme) | | |-- styles/ # Global styles | | |-- utils/ # Utility functions | | |-- views/ # Page views | | | |-- admin/ # AI configuration, alert center, local model management, SSO configuration, RBAC management | | | |-- auth/ # Login/register/reset password/SSO login | | | |-- chat/ # Intelligent Q&A (including multimodal input) | | | |-- command/ # Task command center | | | |-- dashboard/ # Data dashboard | | | |-- knowledge/ # Knowledge base management + version management (KbVersionView.vue) | | | |-- mcp/ # MCP console | | | |-- tech-blog/ # TechBlogHub management backend | | | |-- user/ # Personal center | |-- docs/ | |-- agentcraft.sql # Complete database script (including sys_ai_config, tech_blog_*, planner_evolution_log, agent_registry etc.) | |-- operations-runbook.md # Production operations runbook |-- infra/ # Observability and alerting configuration | |-- prometheus/ | | |-- prometheus.yml # Prometheus scraping and alerting manager configuration | | |-- alerts.yml # Prometheus alerting rules | |-- grafana/ # Grafana data source, dashboard, and plugin pre-configuration | | |-- provisioning/ | | |-- dashboards/agentcraft-claw.json | |-- alertmanager/ | | |-- alertmanager.yml # Alertmanager routing and webhook receiver |-- docker-compose.yml # One-click deployment for the entire stack |-- .env.example # Environment variable example |-- meta-mcp-config.json # MCP tool configuration example |-- README.md # This document ``` --- ## Quick Start ### Requirements - Java 17+ (local development) - Node.js 20+ (local development) - Docker & Docker Compose (recommended, one-click deployment) > Dependencies such as database, cache, and vector retrieval can be automatically started via Docker Compose, without needing separate installation. --- ### Method 1: One-Click Deployment with Docker (Recommended) Only Docker is required to start the complete system, without needing local installation of Java/Node.js. ```bash # 1. Clone the project and enter the directory cd AgentCraft-Claw # 2. Copy the environment variable template and fill in real values (BAILIAN_API_KEY and JWT_SECRET are required) cp .env.example .env # Edit .env: BAILIAN_API_KEY, JWT_SECRET, MYSQL_ROOT_PASSWORD etc. # 3. One-click start (first build may take 3-5 minutes) docker compose up -d --build # 4. View backend logs and wait for startup completion docker compose logs -f backend ``` **Port Mapping (avoid conflicts with local services)**: | Service | Container Port | Host Port | Description | | ------------ | -------- | ---------- | ----------------------- | | Frontend | 80 | 80 | Main entry | | Backend API | 8080 | 8080 | REST + SSE API | | MySQL | 3306 | 3307 | Business database | | Redis | 6379 | 6380 | Cache + session | | MinIO API | 9000 | 9002 | Object storage API | | MinIO Console | 9001 | 9003 | Object storage console | | Milvus | 19530 | 19530 | Vector database | | Prometheus | 9090 | 9090 | Metric scraping and query | | Grafana | 3000 | 3000 | Observability dashboard | | Loki | 3100 | 3100 | Log receiver | | Alertmanager | 9093 | 9093 | Prometheus alert notification management | **Access Addresses**: | Service | Address | Description | | ------------ | ------------------------------------ | ------------------------------------------------ | | Frontend | http://localhost | Main entry | | Backend API | http://localhost/api | REST API | | Health Check | http://localhost/api/actuator/health | No authentication required | | Prometheus | http://localhost:9090 | Metric scraping and query（建议生产环境限制访问） | | Grafana | http://localhost:3000 | Observability dashboard（默认 admin / admin，生产必须修改） | | Loki | http://localhost:3100 | Log receiver（建议生产环境限制访问） | | Alertmanager | http://localhost:9093 | Prometheus alert routing and silencing management | | MinIO Console | http://localhost:9003 | Default account in .env，生产必须修改 | **First Deployment Notes**: 1. **MySQL Initialization**: First startup will automatically execute `docs/agentcraft.sql` to initialize the database, including all table structures and initial data (including `sys_ai_config` default configuration and TechBlogHub vendor source) 2. **Environment Variables**: Must set `BAILIAN_API_KEY` (LLM/Embedding/Rerank) and `JWT_SECRET` (length ≥ 32 bytes), otherwise backend cannot start 3. **Port Conflicts**: If local MySQL/Redis etc. are already running, map to ports like 3307/6380 to avoid conflicts 4. **Docker Network**: Infrastructure runs in `agentcraft_default` network, backend connects both `agentcraft_default` and `agentcraft-claw_default`, ensure DNS resolution between containers is normal ```bash # Common commands # Stop and clean data (including database volume) docker compose down -v # Start infrastructure only (without frontend and backend) docker compose -f backend/docker-compose.dev.yml up -d # Rebuild frontend (after code changes) docker compose up -d --build frontend # Rebuild backend (after code changes) docker compose up -d --build backend # View all service status docker compose ps # View specific service logs docker compose logs -f backend docker compose logs -f frontend ``` --- ## Verification After Deployment After Docker Compose starts, confirm system health with the following checklist: ### 1. Service Status ```bash docker compose ps # Expected: backend / frontend / mysql / redis / minio / milvus / prometheus / grafana / loki / alertmanager / etcd are all healthy ``` ### 2. Backend Health Check ```bash curl http://localhost/api/actuator/health ``` ### 3. Prometheus Targets Access http://localhost:9090/targets, confirm `agentcraft-backend` status is **UP**. ### 4. Grafana Data Source Access http://localhost:3000 (default admin/admin), navigate to **Connections -> Data sources**, and confirm that Prometheus and Loki have been tested successfully. ### 5. Alertmanager Status ```bash curl http://localhost:9093/api/v2/status ``` ### 6. End-to-End Alert Verification Push a simulated Alertmanager payload to the backend webhook: ```bash curl -X POST http://localhost/api/internal/alerts/webhook \ -H "Content-Type: application/json" \ -d '{ "version": "4", "status": "firing", "alerts": [{ "status": "firing", "labels": {"alertname": "AgentCraftTestAlert", "severity": "warning"}, "annotations": {"summary": "Test Alert", "description": "For verifying alert channel"}, "startsAt": "2024-01-01T00:00:00Z" }] }' ``` After logging in as an administrator, visit `/alerts` to see the test alert that was just pushed. ### 7. Real Notification Channel Verification After configuring credentials for DingTalk, Feishu, email, etc. in `.env`, reload Alertmanager and push another test alert with `severity: critical`. Confirm that each channel receives the notification. > See the complete operations runbook in `docs/operations-runbook.md`. --- ### Method 2: Local Development #### 1. Start Infrastructure ```bash cd backend docker compose -f docker-compose.dev.yml up -d ``` #### 2. Initialize Database ```bash mysql -u root -p -h localhost -P 3307 < ../docs/agentcraft.sql ``` #### 3. Configure Backend Environment Variables ```bash export BAILIAN_API_KEY=sk-your-api-key export JWT_SECRET=$(openssl rand -base64 32) export MYSQL_ROOT_PASSWORD=root # Optional export TAVILY_API_KEY=tvly-your-key export CORS_ALLOWED_ORIGINS=http://localhost:5173 ``` > You can also write the above variables to `backend/.env` for IDE automatic loading. #### 4. Start Backend ```bash cd backend mvn clean spring-boot:run # or mvn clean package -DskipTests java -jar target/AgentCraft-Claw-0.0.1-SNAPSHOT.jar ``` #### 5. Start Frontend ```bash cd frontend npm install npm run dev # Default access http://localhost:5173 ``` --- ## Environment Variable Description Copy `.env.example` to `.env` and fill in as needed. All default passwords must be changed in production. | Variable | Required | Description | | ------------------------------------------------- | -------- | ------------------------------------------------------------ | | `BAILIAN_API_KEY` | Yes | Alibaba Cloud Bailian API Key for LLM / Embedding / Rerank | | `JWT_SECRET` | Yes | JWT signature key, length ≥ 32 bytes | | `MYSQL_ROOT_PASSWORD` | Recommended | MySQL root password | | `MINIO_ROOT_PASSWORD` | Recommended | MinIO root password | | `GRAFANA_ADMIN_USER` / `GRAFANA_ADMIN_PASSWORD` | Recommended | Grafana admin account, must be changed in production | | `REDIS_PASSWORD` | No | Redis password (leave blank for no password) | | `CORS_ALLOWED_ORIGINS` | No | Frontend access domain, separated by commas | | `OPENCLAW_API_KEY` | No | OpenClaw external task interface API Key, returns 401 if not configured | | `DOCMIND_WEB_SEARCH_ENABLED` | No | Web search switch, default `false` | | `TAVILY_API_KEY` | No | Tavily API Key, required when enabling web search | | `MINIO_ROOT_USER` | No | MinIO root username, default `minioadmin` | | `MINIO_ROOT_PASSWORD` | Recommended | MinIO root password | | `ALERT_EMAIL_ENABLED` | No | Email alert switch, default `false` | | `DINGTALK_ALERT_ENABLED` | No | DingTalk alert switch, default `false` | | `WECHAT_WORK_ALERT_ENABLED` | No | WeChat Work alert switch, default `false` | | `FEISHU_ALERT_ENABLED` | No | Feishu alert switch, default `false` | | `SMS_ALERT_ENABLED` | No | SMS alert switch, default `false` | | `TECH_BLOG_MINIO_BUCKET` | No | TechBlogHub offline site MinIO bucket, default `tech-blog-sites` | | `TECH_BLOG_REQUEST_INTERVAL_MS` | No | Blog crawl request interval (anti-scraping), default `3000` | | `TECH_BLOG_MAX_RETRIES` | No | Blog crawl maximum retries, default `3` | | `TECH_BLOG_PLAYWRIGHT_ENABLED` | No | Whether to enable Playwright dynamic rendering, default `false` | | `TECH_BLOG_REVIEWER_THRESHOLD` | No | TechBlogHub Reviewer score threshold, default `0.85` | | `APP_LOG_LEVEL` | No | Application log level, default `INFO` | | `SECURITY_LOG_LEVEL` | No | Spring Security log level, default `INFO` | | `LOKI_URL` | No | Loki log push address, default `http://localhost:3100/loki/api/v1/push` | | `ALERT_EMAIL_*` | No | Email alert SMTP configuration | | `DINGTALK_WEBHOOK_URL` | No | DingTalk group robot Webhook | | `WECHAT_WORK_WEBHOOK_URL` | No | WeChat Work group robot Webhook | | `FEISHU_WEBHOOK_URL` | No | Feishu group robot Webhook | | `SMS_WEBHOOK_URL` / `SMS_API_KEY` / `SMS_TO_LIST` | No | SMS gateway configuration | | `MULTIMODAL_OCR_ENGINE` | No | Multimodal OCR engine selection: `tesseract` / `ollama`, default `tesseract` | | `MULTIMODAL_EMBEDDING_URL` | No | Multimodal Embedding service address (Ollama or compatible service) | | `LOCAL_MODEL_BASE_URL` | No | Local model OpenAI-compatible API base URL | | `TEI_BASE_URL` | No | TEI (Text Embeddings Inference) service address | | `SSO_ENABLED` | No | SSO single sign-on switch, default `false` | | `SSO_PROVIDER_TYPE` | No | SSO provider type: `ldap` / `oauth2` / `oidc`, default `oauth2` | | `LDAP_URL` | No | LDAP server address, such as `ldap://localhost:389` | | `LDAP_BASE_DN` | No | LDAP base DN, such as `dc=example,dc=com` | | `LDAP_BIND_DN` | No | LDAP bind account DN | | `LDAP_BIND_CREDENTIAL` | No | LDAP bind account password | | `OAUTH2_CLIENT_ID` | No | OAuth2 Client ID | | `OAUTH2_CLIENT_SECRET` | No | OAuth2 Client Secret | | `OAUTH2_AUTHORIZATION_URI` | No | OAuth2 authorization endpoint | | `OAUTH2_TOKEN_URI` | No | OAuth2 token endpoint | | `OAUTH2_USER_INFO_URI` | No | OAuth2 user information endpoint | | `OIDC_ISSUER_URI` | No | OIDC Issuer URI | | `AGENT_INTEROP_CALLBACK_SECRET` | No | Agent collaboration callback HMAC signature key | ### AI Parameter Configuration (Dynamic Hot Update) The system supports dynamic adjustment of parameters through the `sys_ai_config` table without restarting the service. At startup, `AiConfigInitializer` loads the configuration into the `AiConfigHolder` memory snapshot. After configuration changes, the `ChatModel` instance is atomically replaced. Ongoing SSE requests hold the old reference and complete naturally, while new requests automatically use the new configuration. | Parameter | Default Value | Description | | --- | --- | --- | | `llm.api_key` | — | LLM API Key (overrides environment variable) | | `llm.base_url` | `https://dashscope.aliyuncs.com/compatible-mode` | LLM Base URL | | `llm.model` | `qwen-plus` | Chat Model | | `llm.chat_temperature` | `0.7` | Chat Temperature | | `llm.timeout_seconds` | `60` | Request Timeout (seconds) | | `llm.provider_type` | `CLOUD` | Model Provider: CLOUD / VLLM / OLLAMA / LOCAL | | `rag.vector_top_k` | `20` | Vector Retrieval Top-K | | `rag.bm25_top_k` | `20` | BM25 Retrieval Top-K | | `rag.rrf_top_n` | `25` | RRF Fusion Top-N | | `rag.rerank_top_k` | `5` | Re-ranking Top-K | | `reranker.remote.enabled` | `true` | Enable DashScope Remote Re-ranking | | `reranker.model` | `gte-rerank` | Remote Re-ranking Model | | `reranker.local.enabled` | `true` | Enable Local Semantic Re-ranking Fallback | | `reranker.local.keyword_weight` | `0.35` | Local Re-ranking Keyword Weight | | `web_search.enabled` | `false` | Web Search Switch | | `web_search.tavily_api_key` | — | Tavily API Key | | `cache.freq_threshold` | `3` | Cache Frequency Threshold | | `safety.confidence_threshold` | `0.3` | Safety Confidence Threshold | | `guardrail.semantic.enabled` | `true` | Enable Semantic Guardrail | | `guardrail.semantic.threshold` | `0.82` | Semantic Similarity Threshold (0~1) | | `async.document.core-pool-size` | `4` | Document Processing Async Thread Pool Core Size | | `async.document.max-pool-size` | `10` | Document Processing Async Thread Pool Max Size | | `async.document.queue-capacity` | `100` | Document Processing Async Thread Pool Queue Capacity | | `tech_blog.request_interval_ms` | `3000` | TechBlogHub Request Interval | | `tech_blog.max_retries` | `3` | TechBlogHub Max Retries | | `tech_blog.playwright.enabled` | `false` | Enable Playwright Dynamic Rendering | | `tech_blog.reviewer.threshold` | `0.85` | TechBlogHub Reviewer Threshold | | `multimodal.ocr_engine` | `tesseract` | Multimodal OCR Engine: tesseract / ollama | | `multimodal.embedding_url` | — | Multimodal Embedding Service URL | | `local_model.base_url` | — | Local Model OpenAI-compatible API URL | | `local_model.model` | — | Local Model Name | | `tei.base_url` | — | TEI Private Embedding Service URL | | `planner.evolution.enabled` | `true` | Adaptive Planning Evolution Switch | | `planner.evolution.threshold` | `0.7` | Auto Evolution Trigger Success Rate Threshold | | `planner.evolution.cron` | `0 17 3 * * ?` | Scheduled Evolution Cron Expression (default daily 3:17) | | `agent.interop.enabled` | `true` | Agent Interop Protocol Switch | | `agent.interop.callback_secret` | — | Callback HMAC Signature Key | ## RAG 7-Step Retrieval Chain ``` User Query | v [1] QueryRewriter -- Query Rewriting (Expansion, Disambiguation, Intent Enhancement) | v [2] VectorRetriever -- Milvus Semantic Retrieval | v [3] BM25Retriever -- Lucene Keyword Retrieval (smartcn Tokenization) | v [4] RRFFusion -- Reciprocal Rank Fusion (RRF K=60) | v [5] CrossEncoderReranker -- gte-rerank Cross-Encoder Re-ranking, Remote Failure Automatically Downgrades to LocalReranker (Local Embedding Semantic Re-ranking + Keyword Coverage) | v [6] ContextCompressor -- Context Compression (Truncation by Token Budget) | v [7] PromptAssembler -- Assemble Final Prompt (Context + History + Memory + System Instructions) | v LLM Generation | v SelfReflection -- Self-Inspection (Hallucination, Relevance, Completeness, up to 2 rounds) | v Source Annotation (Document Name, Section, Page Number, Relevance Score) ``` ### Smart Document Slicing Document slicing quality directly determines the RAG recall upper limit. The system no longer uses fixed-length slicing but introduces a structure-aware slicing engine: - **Structured Parsing**: `StructuredDocumentParser` identifies semantic blocks such as headings, tables, code blocks, FAQ question-answer pairs, lists, and definitions/terms. - **Differentiated Strategy**: - Headings are separate blocks, establishing chapter indexes. - Tables/code blocks/FAQs are kept intact to avoid disrupting row relationships or syntax structures. - Ordinary paragraphs are merged according to the target size, and long paragraphs are split by sentences while retaining overlapping windows. - **Dynamic Parameters**: Slicing size and overlap length are read in real-time from `AiConfigHolder` (`rag.chunk_size`, `rag.chunk_overlap`), supporting hot updates in the AI configuration center. - **Metadata Enhancement**: Each slice automatically carries `contentType` (heading/table/code/faq/list/definition/general), `chapter`, and `pageNumber` for BM25 filtering and answer tracing. ### Sentence-Level Answer Tracing To improve answer credibility, the system establishes a mapping between each answer sentence and retrieval segments after generation: - The backend `ProvenanceService` splits the answer by English and Chinese punctuation, calculates the token coverage of sentences and chunks, and returns a `sentence → references` list. - Each reference contains `chunkId`, `source` (knowledge_base/web), `documentName`, `score`, and `snippet`. - SSE `done` events and `qa_message.provenance` fields carry complete tracing JSON. - The frontend Chat page adds an "Answer Tracing" panel: - Lists all referenced sentences. - Each sentence shows Top-3 source badges (including similarity). - Clicking on source badges automatically scrolls to the corresponding reference source card and highlights it. - Source cards have new `chunkId` anchors for bidirectional positioning. ## Knowledge Base Versioning and Incremental Updates To support large document iterations and rollbacks, the knowledge base introduces versioning design: - **Version Records**: Each upload generates a `KbDocumentVersion` record, storing `version_no`, `file_hash`, `file_size`, `file_url`, `status`, `change_summary`, and the operator; `kb_knowledge_base.current_version_id` points to the current effective version. - **Incremental Diff**: `DocumentProcessTask` processes by `versionId`, extracts new slices, and compares them with old version slices by content hash. Only add, modify, or delete slices are executed for Milvus writing or deletion, preserving unchanged slices. - **Fine-Grained Vector Deletion**: `MilvusService.insertVectors` returns generated `vector_id` lists and fills them into `kb_chunk.vector_id`; `deleteByVectorIds` supports precise deletion by ID lists, avoiding full library clearance. - **Failure Retry and Reprocessing**: Upload or processing failures can re-create versions and asynchronously process through `/api/v2/kb/{id}/reprocess`; deleting knowledge bases cleans DB, MinIO objects, and Milvus vectors synchronously. ### Frontend Version Management The frontend provides a complete version management page (`KbVersionView.vue`), allowing administrators to: - View version lists (version number, file size, change summary, status, operator, time). - Release new versions, roll back to historical versions. - **Row-Level Diff Comparison**: Based on the LCS (Longest Common Subsequence) algorithm, adjacent version slices are compared row-by-row, with additions, deletions, and modifications highlighted in different colors for intuitive change presentation. - UI adopts iOS 26 Liquid Glass design, consistent with the system style. ## RAG Evaluation Platform To quantify optimization effects, the system has a built-in RAG Evaluation Platform: - **Evaluation Set Management**: Administrators can create evaluation sets and import standard questions in batches (including expected answers, expected chunk IDs, and related kbIds). - **Automatic Running**: Execute complete RAG chain (rewriting → vector/BM25 → RRF → re-ranking → generation) for each problem in the evaluation set. - **Core Metrics**: - `Recall@5`: The proportion of expected chunks hit in the top 5 retrieval results. - `MRR`: The average reciprocal rank of the first relevant chunk. - `Context Precision`: The relevance density of retrieval results. - `Answer Relevance`: LLM evaluators score generated answers for relevance (0-5). - `Faithfulness`: LLM evaluators score answers for faithfulness (0-5). - **Comparison and Export**: Supports viewing historical results, exporting CSV/JSON reports. Administrator entry: `/rag-eval` ## Unified Audit Center All question-and-answer behaviors are unified into the audit center to meet enterprise compliance requirements: - **Query Dimension**: By time range, user ID, session ID, fallback, user feedback, and keyword retrieval `qa_message`. - **Desensitization Export**: Supports exporting CSV/JSON, automatically masking sensitive information like phone numbers and emails with `***`. - **Field Coverage**: Message content, source count, fallback status, feedback, response time, Agent reasoning chain, MCP calls, reflection logs. Administrator entry: `/audit` ## Trace Visualization To help users and administrators understand "why AI answers this way," the system provides message-level trace tracking: - `GET /api/v2/chat/trace/{messageId}` aggregates `qa_message` with `agentTrace`, `mcpCalls`, `reflectionLog`, `provenance`, and `sources`. - `GET /api/craft/{craftId}/trace` queries task workshop execution records. - Frontend Trace page displays in a timeline: - Agent thinking → action → observation. - MCP tool calls and time consumption. - Reviewer/reflection examination results. - Answer tracing sentence cards. Entry: `/trace` ## API Overview Intelligent Q&A ```http GET /api/v2/chat/stream?message=What%20is%20RAG&conversationId=&kbIds=1,2 Accept: text/event-stream Cookie: access_token={jwt} ``` > SSE interface relies on HttpOnly Cookie `access_token` or `Authorization: Bearer` Header for JWT authentication. EventSource will automatically carry the same domain Cookie. SSE Response Events: ``` event: start event: intent Intent recognition result event: rewrite # Query rewriting result event: retrieval # Retrieval result summary event: rerank # Re-ranking result event: token # Streaming generated Token event: reflection # Self-inspection result event: done ``` ### Multimodal Q&A ```http POST /api/v2/multimodal/chat Content-Type: application/json Cookie: access_token={jwt} { "message": "What's in this image?", "image": "data:image/png;base64,iVBORw0KGgo...", "conversationId": "", "kbIds": [1, 2] } ``` > Supports `image` (Base64) or `imageUrl` (public URL) for image transmission; SSE streaming output, event types consistent with `/api/v2/chat/stream`. ### Task Workshop ```http GET /api/craft/stream?goal=Generate%20AI%20Research%20Report&kbIds=1,2 Accept: text/event-stream Cookie: access_token={jwt} ``` SSE Response: ``` event: plan # Execution plan event: step # Step status update event: agent # Agent status event: message # Intermediate message event: checkpoint # Checkpoint (pause and wait for human input) event: result # Final result ``` Resume Execution: ```http POST /api/craft/resume/{craftId} Content-Type: application/json { "response": "Confirm to continue" } ``` ### MCP Toolchain ```http GET /api/mcp/tools # Tool list GET /api/mcp/tools/{id} # Tool details GET /api/mcp/stats # Call statistics POST /api/mcp/tools/{id}/test # Tool testing PUT /api/mcp/tools/{id}/status # Enable/disable tool ``` ### OpenClaw External Tasks ```http POST/openclaw/tasks Content-Type: application/json X: {openclaw_api_key} { "callerId": "external-agent-001", "correlationId": "20240627-001 "goal": "Generate research report", "kbIds": [1, 2], "constraints": {"maxRounds": 5}, "callbackUrl": "https://example.com/callback" } ``` > OpenClaw authenticates via `X-API-Key` Header; API Key is configured through environment variable `OPENCLAW_API_KEY`; `callbackUrl` receives HTTP POST callbacks on events. ### Agent ```http # external Agent platforms api/openclaw/agents/delegate Content-Type: application/json X-API-Key: {openclaw_api_key} { "targetPlatform": "crewai", "capabilityTags": ["research", "analysis"], "task": { "goal": "Analyze competitor pricing strategy", "context": "Target company is a SaaS enterprise", "maxSteps": 5 }, "callbackUrl": "https://example.com/callback", "timeout 300 } # Receive external Agent callback results POST /api/openclaw/agents/callback Content-Type: application/json X-Interop-Signature: {hmac_sha256_signature} { "delegationId": "dlg-001", "status": "completed", "result": { "summary": "..." } } ``` ### Speech Recognition ```websocket wss://host/api/speech/ws // Binary PCM audio stream -> Real-time text ``` ### Tech Blog Hub ```http # Trigger blog crawling task POST /api/v2/tech-blog/crawl { "query": "Fetch 10 recent articles from Anthropic", "sources": ["anthropic"], "maxArticles": 10, "autoTranslate": true } # SSE progress stream GET /api/v2/tech-blog/crawl/{taskId}/stream Accept: text/event-stream # Article list / search / filtering GET /api/v2/tech-blog/articles?sourceId=1&tags=Agent&tags=RAG&sortField=publishDate&sortOrder=desc&page=1&size=20 # Generate offline site POST /api/v2/tech-blog/export { "name": "Anthropic-Agent-topic", "filters": { "sources": ["anthropic"], "tags": ["Agent"] } } # Download offline site ZIP GET /api/v2/tech-blog/export/{exportId}/download # Tag statistics GET /api/v2/tech-blog/stats/tags ``` ### Data Dashboard ```http GET /api/v2/stats/overview?timeRange=week ``` ### RAG Evaluation Platform (Admin) ```http # Dataset management GET /api/admin/rag-eval/datasets POST /api/admin/rag-eval/datasets GET /api/admin/rag-eval/datasets/{datasetId} POST /api/admin/rag-eval/datasets/{datasetId}/questions # Evaluation runs GET /api/admin/rag-eval/runs POST /api/admin/rag-eval/rGET /api/admin/rag-eval/runs/{runId} GET /api/admin/rag-eval/runs/{runId}/results?page=1&size=20 GET /api/admin/rag-eval/runs/{runId}/export?csv ``` - Runs are executed asynchronously by an independent thread pool after launch, with real-time status updates: `running -> completed/failed` - Metrics: Recall@1/3/5, MRR, Context Precision, Answer Relevance (0-5), Faithfulness (0-5), average latency - Evaluation process reusesAG retrieval components directly, without going through SSE and conversation persistence, and has no side effects. ### Unified Audit Center (Admin) ```http GET /api/admin/audit/messages?userId=&conversationId=&feedback=&fallbackOnly=&keyword=&page=1&size=20 POST /api/admin/audit/export { "format": "csv", "filters": { "userId": 1, "feedback": 1 } } ``` - Query conditions support time range, user ID, conversation ID, feedback status, fallback only, and content keywords. - Exported content automatically sanitizes phone numbers and emails. ### Trace Tracking ```http GET /api/v2/chat/trace/{messageId} # Message-level: Agent Trace / MCP Calls / Reflection / Provenance GET /api/craft/{craftId}/trace # Craft-level: execution trajectory / Agent / Tools / time consumption ``` - Message Trace verifies if the current user is the conversation owner. - Craft Trace verifies if the current user is the task owner. ### A/B Experimentation Platform (Admin) ```http # Experiment list / creation / details / update / deletion GET /api/admin/ab-experiments POST /api/admin/ab-experiments GET /api/admin/ab-experiments/{id} PUT /api/admin/ab-experiments/{id} DELETE /api/admin/ab-experiments/{id} # Experiment lifecycle POST /api/admin/ab-experiments/{id}/start POST /api/admin/ab-experiments/{id}/pause POST /api/admin/ab-experiments/{id}/complete # Experiment metrics GET /api/admin/ab-experiments/{id}/metrics ``` - Only `ADMIN` role can access; experiments support `CHAT_MODEL` / `TEMPERATURE` and other types, with traffic percentage and variant weight sharding. - `ExperimentRouter` uses stable hashing (MurmurHash3 simplified implementation) to ensure that the same user requests fall into the same variant multiple times. AiConfigHolder` caches independent `ChatModel` for variant combination, with automatic invalidation and reloading on configuration changes. - Experiment events are recorded through `ab_experiment_event metrics interface statistics exposure/hit/conversion. Admin `/ab-experiments### Alert Center (Admin) ```http # View recent alerts GET /api/admin/alerts/recent?limit=20 # Acknowledge (remove) single alert POST /api/admin/alerts/{fingerprint}/acknowledge # Alertmanager webhook (internal call, no authentication required) POST/internal/alerts ``` --- ### Management (Admin) ```http # Local model CRUD GET /api/admin/local-models POST /api/admin/local-models GET /api/admin/local-models/{id} PUT /api/admin/local-models/{id} DELETE /api/admin/local-models/{id} # Connectivity test POST /api/admin/local-models/{id}/test # Health status GET /api/admin/local-models/{id}/health ``` - Supports vLLM / Ollama / TGI three local model providers configuration. - Connectivity test sends a probe request to verify if the model is available. - Health status is periodically detected by `LocalModelHealthIndicator`. ### RBAC Permission Management (Admin) ```http # Role management GET /api/admin/rbac/roles POST /api/admin/rbac/roles PUT /api/admin/rbac/roles/{id} DELETE /api/admin/rbac/roles/{id} # Permission tree GET /api/admin/rbac/permissions/tree # User role assignment POST /api/admin/rbac/users/{userId}/roles GET /api/admin/rbac/users/{userId}/roles # Data permission configuration PUT /api/admin/rbac/roles/{roleId}/data-scope ``` - Roles support hierarchical inheritance; deleting a parent role automatically checks for child role references. - Permission tree supports menu / button / API / data four-level granularity. - Data permission scope: ALL / OWN / DEPT / TEAM ### SSO Configuration Management (Admin) ```http # Get current SSO configuration GET /api/admin/sso/config # Update SSO configuration PUT /api/admin/sso/config # Connectivity test POST /api/admin/sso/test ``` - Supports LDAP/AD and OAuth2/OIDC two modes configuration. - Connectivity test actually initiates an authentication request to verify configuration correctness. --- ## Security Features - **JWT stateless authentication**: 24h access token + 7d refresh token - **BCrypt password hashing**: strength 10 bcrypt encryption - **Role-based access control**: `ROLE_ADMIN` / `ROLE_USER`, admin route front-end guard + back-end `@PreAuthorize` / `@RequirePermission` dual verification - **Resource-level permissions**: RBAC role hierarchical inheritance, permission tree, data permissions (ALL / OWN / DEPT / TEAM), annotation-driven AOP interception - **SSO security**: LDAP/AD and OAuth2/OIDC single sign-on, SSO login automatically synchronizes users, without exposing enterprise internal passwords - **Input security review**: GuardRailService rules + semantic double-layer security inspection (jailbreak, injection, sensitive information, violence, hatred, illegality, privacy), supports Embedding vector similarity interception synonymous/rewriting bypass - **Output security review**: rules + semantic double-layer harmful content interception, fact-checking, hallucination detection, confidence threshold - **SSE security authentication**: One-time ticket (` mechanism, 60, can only be used once - Automatically carries HttpOnly Cookie in same-domain scenarios - Thoroughly avoids exposing long-term JWT in URL query parameters - **CORS cross-domain configuration**: configures whitelist through `CORS_ALLOWED_ORIGINS` environment variable, prohibits `*` + `AllowCredentials` combination in production environment - **JWT key verification**: verifies `JWT_SECRET` length ≥ 32 bytes at startup, preventing weak key usage **Actuator security**: `/actuator/health/**actuator/info `/actuator/prometheus` are exposed for Prometheus; production environment recommends limiting `/actuator/prometheus` through reverse proxy or IP- **XSS protection**: front-end Markdown rendering uses DOMPurify filtering to prevent `v-html` injection - **TechBlogHub SSRF protection**: `UrlWhitelistHarness` only allows predefined domain list (`anthropic.com`, `openai.com`, `deepmind.google`, `ai.meta.com`, etc.), and intercepts illegal URLs through HarnessEngine PRE_EXECUTION; `BlogDiscoveryTool` supports RSS / Sitemap / official API and Tavily downgrade discovery - **WebBridge URL whitelist**: browser automation only allows public technical domains (`anthropic.com`, `openai.com`, `deepmind.google`, `ai.meta.com`, `wikipedia.org`, `github.com`, `stackoverflow.com`, `docs.spring.io`, etc.), and illegal URLs are intercepted by HarnessEngine at the PRE_EXECUTION stage to prevent SSRF and malicious jumps - **Agent collaboration callback security**: cross-platform callbacks use HMAC-SHA256 signature (`X-Interop-Signature`), and the receiving end verifies the signature to prevent forgery - **Multimodal input security**: uploaded images/PDFs undergo file type verification, size limitation, and content scanning to prevent malicious file uploads --- ## Front-end Design System ### iOS 26 Liquid Glass Design Language The front-end adopts Apple's iOS 26 Liquid Glass design philosophy: - **Liquid glass material**: `backdrop-filter: blur(30-60px) saturate(160-200%)` + multi-layer refraction highlights - **Dynamic fluid background**: 4 colored gradient balls + CSS drift animation + noise texture - **Capsule button**: `border-radius: 9999px` + gradient fill + halo shadow - **Glass card**: 24px rounded corners + top highlight layer + hover - **Color system**: iOS native colors (#0A84FF blue, #BF5AF2 purple, #30D158 green, #FF453A red) - **Typography**: SF Pro Display + larger font sizes, lighter and heavier font weights - **Animations**: Spring easing curve + entrance blur fade-out + breathing halo --- ## Testing ### Running Modes ```bash # Back-end unit testing + integration testing cd backend mvn test # Run integration tests only mvnDtest='Test' # Back-end full build (including tests) mvn clean package # Front-end type checking cd frontend npm run type-check ``` ### Test Coverage | Type | Description | | ------------ | ------------------------------------------------------------ | | Unit Tests | `AlertNotificationServiceTest`, `DocumentProcessTaskTest`, `CrossEncoderRerankerTest`, `LocalRerankerTest`, `ProvenanceServiceTest`, `MetricsServiceTest`, `GuardRailServiceTest`, `AlertMessageFormatterTest`, `DingTalkAlertChannelTest`, `StatsServiceImplTest`, `ResilientChatModelTest`, `LoopEngineTest`, `ReviewerLoopTest`, `HarnessEngineTest`, `InputHarnessTest`, `UrlWhitelistHarnessTest`, `TranslationToolTest`, `TaggingToolTest`, `JwtUtilsTest` (JWT generation/expiration/abnormal parsing), `OpenClawControllerTest` (API Key authentication), `OpenClawGatewayTest` (real HTTP callback), `CraftControllerTest` (asynchronous task/restore/feedback persistence), `PlannerEvolutionSchedulerTest` (timed evolution and threshold trigger), `PlannerMetricsCollectorTest` (indicator collection and matrix generation), `LocalModelHealthIndicatorTest` (health check and status change), `AgentRegistryServiceTest` (registration/discovery/heartbeat), `AgentTaskDelegatorTest` (synchronous delegation and asynchronous callback), `RbacServiceTest` (role inheritance and permission tree), `SsoConfigServiceTest` (SSO configuration and connectivity) | | Integration Tests | `JwtAuthenticationIntegrationTest` (JWT issuance/authentication/expiration), `ControllerIntegrationTest` (public endpoint/administrator permission/parameter verification), `RagPipelineIntegrationTest` (RAG seven-step link call sequence), `TechBlogControllerIntegrationTest` (TechBlogHub end-to-end, including tag filtering and sorting), `StaticSiteGeneratorToolTest` (offline site ZIP structure and search index), `AbExperimentControllerIntegrationTest` (A/B experiment CRUD and lifecycle), `AuditControllerIntegrationTest` (audit query and export), `MultimodalChatIntegrationTest` (image upload/OCR/visual retrieval fusion), `LocalModelControllerIntegrationTest` (local model CRUD/connectivity test), `AgentInteropControllerIntegrationTest` (delegation/callback/HMAC signature) | | Component Tests | `DagSchedulerTest` (DAG topology stratification and ring detection), `SwarmOrchestratorTest` (parallel execution/memory recall/Reviewer) | | Knowledge Base Tests | `StructuredDocumentParserTest` (list/title/FAQ semantic block parsing), `TextChunkerTest` (chapter metadata and short paragraph retention), `DocumentProcessTaskTest` (incremental processing/failure retry/ready status skip) | | Version Management Tests | `KbVersionViewTest` (version list/release/rollback/Diff highlighting) | > Integration tests use the `test` profile + H2 memory database + `@MockitoBean` (Spring Boot 3.4 has deprecated `@MockBean`) to simulate external dependencies, and can be run without Docker. ## Observability Deployed automatically including Prometheus + Grafana + Loki + Alertmanager stack: | Service | Address | Description | | ------------ | --------------------- | ----------------------------------------------- | | Prometheus | http://localhost:9090 | Capture backend `/actuator/prometheus` | | Grafana | http://localhost:3000 | Default admin / admin, AgentCraft-Claw dashboard preset | | Loki | http://localhost:3100 | Receive backend pushed logs | | Alertmanager | http://localhost:9093 | Prometheus alert routing, default push to backend webhook | ### Preset Metrics The backend uses Micrometer to埋点, key metrics include: - `rag.retrieval.duration` — RAG retrieval time-consuming (distinguished by `mode` tag) - `llm.generation.duration` — LLM complete generation time-consuming - `llm.first_token.latency` — LLM first token delay - `rag.reflection.total` — Self-reflection review times (distinguished by `round`, `passed` tags) - `document.process.duration` — Document processing time-consuming (distinguished by `status` tag) - `craft.step.duration` / `craft.execution.duration` — Craft task execution time-consuming - `harness.decision.total` — Harness decision times (distinguished by `level`, `decision` tags) - `craft.loop.round` — Loop iteration rounds - `techblog.crawl.duration` / `techblog.article.count` / `techblog.review.score` — TechBlogHub metrics - `multimodal.ocr.duration` / `multimodal.vision.retrieve.duration` — Multimodal RAG metrics - `local_model.health.status` — Local model health status (0=DOWN, 1=UP) - `planner.evolution.duration` / `planner.evolution.success_rate` — Adaptive planning metrics - `agent.interop.delegate.duration` / `agent.interop.callback.total` — Agent collaboration metrics ### Log Aggregation The backend pushes logs to Loki via `loki-logback-appender`: - Default push address: `http://localhost:3100/loki/api/v1/push` - Automatically set to `http://loki:3100` in Docker Compose - Can be overridden by environment variable `LOKI_URL` - Disabled in `test` profile to avoid unit tests generating network requests Grafana has preset Loki data source, can directly search logs in Explore by `app=agentcraft-claw`, `level`, `thread` and other tags. ### Alert Rules Prometheus has loaded `infra/prometheus/alerts.yml`, preset the following alerts: | Alert Name | Trigger Condition | Level | | --------------------------------------- | ------------------------------------------------------------ | -------- | | `AgentCraftHighRetrievalLatency` | RAG average retrieval time-consuming > 2s in the last 5 minutes, lasting 2 minutes | warning | | `AgentCraftHighFirstTokenLatency` | LLM average first token delay > 5s in the last 5 minutes, lasting 2 minutes | warning | | `AgentCraftHighLlmGenerationLatency` | LLM average complete generation time-consuming > 30s in the last 5 minutes, lasting 2 minutes | warning | | `AgentCraftDocumentProcessingFailing` | Document processing failure rate > 0 in the last 1 minute | critical | | `AgentCraftReflectionFailing` | Self-reflection failure rate > 0.1 times/second in the last 5 minutes, lasting 2 minutes | warning | | `AgentCraftHighJvmHeapUsage` | JVM heap memory usage > 85%, lasting 2 minutes | critical | | `AgentCraftTechBlogCrawlFailing` | TechBlogHub crawl failure rate > 0 in the last 5 minutes, lasting 2 minutes | warning | | `AgentCraftTechBlogExportSlow` | TechBlogHub site generation average time-consuming > 120s in the last 5 minutes, lasting 2 minutes | warning | | `AgentCraftLocalModelDown` | Local model health check failed 3 times consecutively | critical | | `AgentCraftPlannerEvolutionFailing` | Adaptive planning evolution task failed 2 times consecutively | warning | | `AgentCraftAgentInteropCallbackFailing` | Agent collaboration callback failure rate > 0.1, lasting 5 minutes | warning | ### Alert Notification Configuration The system has integrated **Alertmanager**, Prometheus triggers alerts and distributes them to the backend webhook and real notification channels: | Function | Path | | ----------------- | ------------------------------------------------------------ | | Alertmanager Configuration | `infra/alertmanager/alertmanager.yml` | | Backend unified receiving endpoint | `POST /api/internal/alerts/webhook`（internal whitelist, no external authentication） | | Backend channel forwarding endpoint | `POST /api/internal/alerts/notify/{channel}`（channel: dingtalk / wechat_work / feishu / sms） | | Management console view | `GET /api/admin/alerts/recent?limit=20`（need `ADMIN` role） | | Alert confirmation | `POST /api/admin/alerts/{fingerprint}/acknowledge`（need `ADMIN` role） | #### Default Routing Policy | Alert Level | Notification Channel | | ---------- | --------------------------------- | | `critical` | Backend webhook + SMS + DingTalk + Email | | `warning` | Backend webhook + Feishu + Email | | Default | Backend webhook | #### Minimum Available Configuration 1. Copy environment variable template and fill in real credentials: ```bash cp .env.example .env ``` 2. Cancel the corresponding line comment in `.env` and replace: ```env # Email alert ALERT_EMAIL_ENABLED=true ALERT_EMAIL_SMTP_HOST=smtp.example.com ALERT_EMAIL_SMTP_PORT=587 ALERT_EMAIL_FROM=alertmanager@example.com ALERT_EMAIL_USERNAME=alertmanager@example.com ALERT_EMAIL_PASSWORD=your-email-password ALERT_EMAIL_TO=oncall@example.com # DingTalk robot DINGTALK_ALERT_ENABLED=true DINGTALK_WEBHOOK_URL=https://oapi.dingtalk.com/robot/send?access_token=your-token DINGTALK_AT_MOBILES=13800138000 # WeChat robot WECHAT_WORK_ALERT_ENABLED=true WECHAT_WORK_WEBHOOK_URL=https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=your-key # Feishu robot FEISHU_ALERT_ENABLED=true FEISHU_WEBHOOK_URL=https://open.feishu.cn/open-apis/bot/v2/hook/your-token # SMS gateway SMS_ALERT_ENABLED=true SMS_WEBHOOK_URL=https://sms-gateway.example.com/api/v1/send SMS_API_KEY=your-sms-api-key SMS_TEMPLATE_CODE=your-template-code SMS_TO_LIST=13800138000,13900139000 ``` 3. Restart Alertmanager: ```bash docker compose restart alertmanager # or reload online curl -X POST http://localhost:9093/-/reload ``` > Email channel is sent directly by Alertmanager's native `email_configs`; DingTalk/WeChat/Feishu/SMS are pushed to the backend `/api/internal/alerts/notify/{channel}` by Alertmanager's `webhook_configs`, and forwarded by the backend to the required message format for each platform. This allows centralized maintenance of templates, signatures, and current limiting logic without modifying Alertmanager behavior. ### Dashboard Panel `infra/grafana/dashboards/agentcraft-claw.json` presets the following panels: - RAG retrieval time-consuming (by mode) - LLM average generation time-consuming - LLM average first token delay - Document processing time-consuming (by status) - Self-reflection review rate - Harness decision distribution - Loop iteration rounds - TechBlogHub crawl/export metrics - Multimodal OCR / visual retrieval time-consuming - Local model health status - Adaptive planning evolution success rate - Agent collaboration delegation and callback metrics --- ## FAQ and Troubleshooting ### Backend Build #### `mvn test` fails on Windows or JAVA_HOME is incorrect If there are multiple JDKs on Windows or Maven cannot find the correct Java path, it is recommended to use the Docker test image provided by the project: ```bash cd backend MSYS_NO_PATHCONV=1 docker run --rm -v "$(pwd -W)":/app -w /app agentcraft-backend:builder mvn test -Dspring.profiles.active=test ``` > This image has a fixed Java 17 and Maven version, mount the current `backend` directory to `/app` and execute the test, avoiding local environment differences. #### Integration test reports `Table "xxx" not found` The test uses the H2 memory database, and the table structure is initialized by `src/test/resources/schema.sql`. If a new business table is added, the file needs to be updated synchronously, otherwise, the integration test involving the new table will fail. #### Test reports `ResponseBodyEmitter` not triggering `onCompletion` `SseEmitter.complete()` is only triggered when there is an HTTP handler; in unit tests, please use `spy(emitter)` and assert the process ends by `verify(emitter).complete()`, rather than waiting for the callback. ### Frontend Build #### `npm run type-check` reports `any` type warning The project has configured ESLint + Prettier (see `frontend/eslint.config.js`). Try to reduce `any` usage during development, and prefer to declare interfaces for API responses and component states. #### SSE connection interrupted or received duplicate error events Check if `sse.onerror` and `sse.addEventListener('error', ...)` are registered at the same time. The two forms of EventSource will trigger simultaneously, resulting in repeated cleaning. Keep one of them and ensure that the URL parameter is encoded using `URLSearchParams.toString()`. ### TechBlogHub Crawl Failure #### Target website returns 403 / anti-crawl interception 1. Check if `TECH_BLOG_REQUEST_INTERVAL_MS` in `.env` is ≥ 3000 ms 2. Confirm that the target URL is in the `tech-blog.url-whitelist` list in `application.yml` 3. Enable Playwright dynamic rendering: `TECH_BLOG_PLAYWRIGHT_ENABLED=true` (ensure that the browser binary is installed on the container/host) 4. View the degradation path of `ContentFetchTool` and the failed label of `TechBlogMetrics` in the backend log #### Reviewer Score Continuously Failing 1. Check if the `tech_blog.reviewer.threshold` configuration is too high (default 0.85) 2. View the `fail_reason` and Reviewer four-dimensional score for a single article in the management backend 3. Adjust the translation/summary prompt word template `backend/src/main/resources/prompts/` ### Multimodal RAG Common Issues #### Low OCR Recognition Rate 1. Check `MULTIMODAL_OCR_ENGINE` settings: Tesseract is suitable for printed text, Ollama multimodal is suitable for complex graphics and text mixed arrangement 2. Confirm the image resolution ≥ 300 DPI, low resolution will lead to text blur 3. View the recognition time and confidence level of `OcrService` in the backend log #### Inaccurate Visual Retrieval Results 1. Confirm that the multimodal embedding service pointed to by `MULTIMODAL_EMBEDDING_URL` is available 2. Check if the Milvus image Collection has been indexed ( `kb_image_collection` ) 3. Adjust `rag.vector_top_k` and `rag.rrf_top_n` in the AI configuration center ### Local Model Deployment Common Issues #### Local Model Cannot Connect 1. Confirm that `LOCAL_MODEL_BASE_URL` correctly points to the OpenAI-compatible API endpoint of vLLM/Ollama/TGI 2. Send a probe request using the administrator interface `POST /api/admin/local-models/{id}/test` to view detailed errors 3. Check if the local model service is started normally: `curl http://localhost:8000/v1/models` 4. Confirm that the firewall/network policy allows the backend container to access the local model service #### TEI Embedding Service Exception 1. Confirm that `TEI_BASE_URL` points to the TEI service address, such as `http://localhost:8080` 2. Check the model loading status in the TEI service log 3. Verify that the embedding dimension is consistent with the Milvus Collection (default 1024) ### Adaptive Planning Common Issues #### Planner Evolution Effect Deterioration 1. View the A/B comparison of `PlannerEvolutionLog` in the administrator backend to confirm the index changes before and after evolution 2. Use the rollback function to restore to the previous version strategy 3. Check if `planner.evolution.threshold` is set too high or too low #### Evolution Task Not Triggered 1. Confirm `planner.evolution.enabled=true` 2. Check if the Cron expression `planner.evolution.cron` is correct (default `0 17 3 * * ?`, every day at 3:17) 3. View the execution record of `PlannerEvolutionScheduler` in the backend log ### Agent Collaboration Common Issues #### External Agent Callback Failure 1. Confirm that `AGENT_INTEROP_CALLBACK_SECRET` is consistent with the external platform configuration 2. Check if the `X-Interop-Signature` HMAC signature in the callback request is correctly generated 3. View the delegation and callback processing records of `AgentTaskDelegator` in the backend log #### External Agent Registration Failure 1. Confirm that Redis is available, and `AgentRegistryService` relies on Redis to store registration information 2. Check if the external Agent's heartbeat is sent on time (default TTL 30 seconds) 3. View the registered Agent list returned by `GET /api/openclaw/agents/registry` --- ## Frontend Build Optimization - **Element Plus Automatic Import on Demand**: Use `unplugin-auto-import` + `unplugin-vue-components` + `ElementPlusResolver` to pack only the components actually used, avoiding full import. - **Manual Code Splitting**: Configure `manualChunks` in `vite.config.ts` to split `vue-vendor`, `echarts`, `markdown`, etc. into independent chunks. - **Build Results**: `npm run build` passes without warnings of JS chunks larger than 1MB, and the first screen loads faster. - **Code Specification**: The project has built-in ESLint + Prettier, run `npm run lint` to check, `npm run lint:fix` to automatically fix, and `npm run format` to format. --- ## Recent Evolution The following features are based on the **2026-06-27 evolution suggestions** and have been fully implemented: | Feature | Status | Description | | --- | --- | --- | | **Multimodal RAG** | ✅ Online | Supports images/PDF as input, OCR + multimodal embedding + visual retrieval fusion, Milvus dual Collection | | **Private Model All-in-One Machine** | ✅ Online | vLLM/Ollama/TGI local deployment, OpenAI-compatible API unified access, TEI private embedding, double-layer cache, Actuator health check | | **Adaptive Planning** | ✅ Online | Planner automatically evolves Prompt and tool strategy based on historical success rate, timed evolution + threshold trigger, version management and rollback | | **Agent Collaboration Protocol** | ✅ Online | Interoperability with CrewAI/AutoGen/Dify, registry + task delegation + asynchronous callback, HMAC-SHA256 signature anti-counterfeiting | | **Enterprise RBAC and SSO** | ✅ Online | Role level inheritance, permission tree, data permission (ALL/OWN/DEPT/TEAM), LDAP/AD/OAuth2/OIDC single sign-on | | **Knowledge Base Front-end Version Management** | ✅ Online | Version list/release/rollback/Diff comparison, LCS line-level highlighting, iOS 26 Liquid Glass UI | --- ## Phase 1 Performance Optimization (Online) Based on the **2026-06-28 evolution suggestions**, Phase 1 performance optimization has been fully implemented, focusing on solving the most urgent performance bottlenecks and cost control issues: | Feature | Status | Description | | --- | --- | --- | | **Multi-level Cache System** | ✅ Online | L1 Caffeine (local) + L2 Redis (distributed) + L3 DB (persistent), Cache-Aside mode, Bloom filter anti-penetration, distributed lock to ensure consistency, expected to reduce 60% database queries and 30% response delay | | **Query Intent Cache** | ✅ Online | Based on embedding cosine similarity (>0.95) high-frequency query intent cache, cache hit directly returns historical retrieval results, high-frequency query response from 2s to 200ms; knowledge base version update automatically invalidates associated cache | | **RAG Link Pruning** | ✅ Online | Query complexity analyzer automatically judges simple queries (≤5 characters / ≤3 words) to skip Query Rewriter; knowledge base query clear skip network search; vector retrieval empty skip BM25; reordering score <0.5 skip context compression, expected to reduce 30% Token consumption | | **Connection Pool Optimization** | ✅ Online | Milvus connection pool based on Apache Commons Pool2 (maxTotal=20); LLM HTTP connection pool based on Apache HttpClient (maxTotal=200 / maxPerRoute=50); HikariCP connection pool from 10 to 50 (maximum-pool-size), reducing connection establishment overhead and improving concurrency capability | | **Front-end PWA** | ✅ Online | Vite PWA Plugin + Service Worker + Workbox runtime cache, supports offline access, automatic update, network request retry and exponential backoff; manifest configuration supports mobile terminal standalone installation | | **LLM Cost Tracking** | ✅ Online | Records Token consumption by user/session/model dimension ( `llm_usage_log` ), accurately calculates cost based on model unit price ( `llm.cost` configuration), supports monthly budget quota ( `llm_budget` ) and budget warning (80% usage alert), Prometheus indicator exposure | | **Data Desensitization Engine** | ✅ Online | Custom Jackson serializer + `@SensitiveField` annotation, automatically desensitizes at runtime (mobile number, ID card, email, bank card, password), supports FULL / PARTIAL / HASH / REPLACE / AES five strategies, role-level classification (ADMIN no desensitization / USER full mask), log layer automatically desensitizes through `MaskingLogAppender` | --- ## License MIT License (c) 2025 AgentCraft-Claw Team --- ## Acknowledgements - **Spring AI** — AI native application framework - **Milvus** — High-performance vector database - **Element Plus** — Vue 3 component library - **Tavily** — Real-time web search API - **DashScope** — Tongyi Qianwen large model platform - **vLLM / Ollama / TGI** — High-performance local large model inference framework - **TEI** — HuggingFace Text Embeddings Inference - **Apple iOS Design** — Liquid Glass visual inspiration