DEV Community: noear

Snack4 JSON Streaming Parser & Auto-Repair Deep Guide

noear — Wed, 18 Mar 2026 05:40:57 +0000

Snack4 is a high-performance Java JSON library designed for demanding scenarios. Its core component JsonReader uses a non-recursive state machine architecture, natively supporting Streaming Parse and Auto-Repair, making it ideal for handling unstable LLM outputs and large NDJSON files.

1. Streaming Parse: From Bulk to Incremental

Traditional parsers require JSON to be complete and loaded into memory at once. Snack4 supports extracting valid data in chunks (Nodes) while the data is flowing.

1.1 Core Scenarios

LLM Real-time Rendering: Parse while generating, update UI without waiting for the conversation to end.
NDJSON/JSONL: Process multi-line JSON objects from log streams or database exports.
Low Memory Processing: When processing GB-level files, memory usage stays at KB-level buffer size.

1.2 Key APIs

JsonReader reader = new JsonReader(jsonStream);

// Method A: Iterator pattern (recommended, most elegant syntax)
for (ONode node : reader.iterableNext()) {
    process(node); 
}

// Method B: Precisely get the last complete node (commonly used for LLM final state)
ONode finalState = reader.readLast();

// Method C: Manual chunked reading control
ONode next;
while ((next = reader.readNext()) != null) {
    // business logic
}

2. Auto-Repair: Fault Tolerance at Its Best

When Feature.Read_AutoRepair is enabled, JsonReader transforms from a "strict validator" into a "smart completer". By maintaining an internal type stack, it automatically infers missing symbols when encountering unexpected endings.

2.1 Repair Logic Reference

Damage Type	Original Input (Broken)	Repaired Output	Repair Logic
Keyword Truncation	`{"status": tru`	`{"status": true}`	Incomplete `true` literal auto-repaired to `true`
Unclosed Container	`{"a":{"b":1`	`{"a":{"b":1}}`	Auto-completes missing `}` based on parsing stack
Trailing Comma	`[1, 2,`	`[1, 2]`	Automatically ignores trailing comma
Missing Key-Value	`{"key":`	`{"key": null}`	Found colon then directly ended, auto-completes value
Invalid Character Interference	`{"a":1} #comment`	`{"a":1}`	Works with Read_AllowComment to filter non-JSON content

2.2 Code Demo

// Even deeply nested and severely truncated strings
String brokenJson = "{\"user\":{\"tags\":[\"java\",\"ai\""; 

Options opts = Options.of(Feature.Read_AutoRepair);
ONode node = JsonReader.read(brokenJson, opts);

System.out.println(node.toJson());
// Output: {"user":{"tags":["java","ai"]}}

3. Advanced: Best Practices for Handling LLM Mixed Output

LLMs sometimes output text followed by a JSON, or multiple separate JSON blocks. Using Snack4's combination features, you can easily handle these complex scenarios.

3.1 Mixed Stream Parse Template

public void handleLlmStream(String rawOutput) {
    // Enable auto-repair + allow single quotes (increased robustness)
    Options opts = Options.of(Feature.Read_AutoRepair, Feature.Read_AllowSingleQuotes);
    JsonReader reader = new JsonReader(rawOutput, opts);

    // Auto-filter non-valid JSON parts from stream (like leading text)
    for (ONode node : reader.iterableNext()) {
        if (node.isObject() || node.isArray()) {
            // Only process structured data
            dispatchToBusiness(node);
        }
    }
}

4. Summary

Dimension	Streaming & Auto-Repair	Normal Mode
Parse Method	Streaming pointer sliding, continuously parsing json chunks	Parses only one json chunk, throws exception for extras
Exception Handling	Auto-repairs, no exceptions thrown	Throws ParseException on missing colon
LLM Adaptation	Natively supports truncation, keyword repair	Requires developers to write regex or preprocessing (non-compliant throws ParseException)

By combining Streaming Parse with Auto-Repair, Snack4 provides developers with a robust data defense line, ensuring that no matter how bad the upstream data is, downstream business logic receives stable structured objects.

Snack4-JsonPath v4.0.36 Released (IETF RFC 9535 Standard Support)

noear — Fri, 13 Mar 2026 01:48:37 +0000

Provides JSON DOM construction, encoding/decoding (serialization), retrieval, JsonPath queries, JsonSchema validation, and more.

<dependency>
  <groupId>org.noear</groupId>
  <artifactId>snack4-jsonpath</artifactId>
  <version>4.0.36</version>
</dependency>

Snack-JsonPath draws inspiration from JavaScript's var declaration for all variables and XML DOM's "everything is a Node" design philosophy. All underlying data is represented as ONode, which stands for "One node" - capable of representing any type and converting to any type.

Emphasizes document tree construction and manipulation capabilities
High-performance JSON Path queries (significantly faster than jayway.jsonpath). Compatible with both jayway.jsonpath and the IETF JSONPath (RFC 9535) standard (switchable via options). Delivering a robust JsonPath experience for the next decade.
Supports Json schema validation
Supports partial json5 features (unquoted keys, comments, etc.)
Prioritizes no-argument constructors + field encoding/decoding (reduces risks of injection-triggered actions)
Supports Java 8 to Java 25

Dependency packages:

Package	Description
`org.noear:snack4`	Provides `json dom` construction and encoding/decoding support
`org.noear:snack4-jsonpath`	Provides `json path` query support
`org.noear:snack4-jsonschema`	Provides `json schema` validation support

Open source repository:

Documentation:

https://solon.noear.org/article/snack

1. Recent Updates

Added snack4 Json Feature.Read_TrimString feature
Added snack4 JsonReader.iterableNext method (supports JSON streaming, particularly adapted for LLM stream output)
Added snack4 JsonReader.readLast method
Added snack4 ONode field type deserialization support
Added snack4 custom annotation retrieval support
Added snack4 Options.then method for chained building
Added snack4 CodecLib.patternCreators, patternDecoders, patternEncoders deduplication handling
Added snack4 MapperLib.schemaPatternMappers, typePatternMappers deduplication handling
Added snack4 AtomicBoolean, AtomicLong, AtomicInteger support
Added snack4 Optional built-in codec support (also customizable)
Added snack4 ONode:delete method to assist with jsonpath deletion
Added snack4-jsonschema JsonSchema default value generation
Added snack4-jsonschema type mapping mechanism, supporting wrapper or delivery types like Future, Optional
Optimized snack4 Iterable support (replacing previous Collection)
Optimized snack4 deserialization to automatically remove '@type' property declaration
Optimized snack4-jsonpath logical expression compatibility to support space-less "a=='a'"
Optimized snack4-jsonschema Optional type handling
Changed snack4 JsonReader.streamRead to readNext (former marked as deprecated)
Changed snack4-jsonpath JsonPath.delete to return bool (previously void)
Fixed snack4 ONode.ofBean and ofJson throwing exception when passed null
Fixed snack4 Json BeanDecoder not restoring array.item when null (incorrectly filtered)
Fixed snack4-jsonschema JsonSchema TypeRule.getSchemaTypeName not recognizing initial node as null (was recognized as undefined)
Fixed snack4-jsonpath JsonPathProvider:delete(root, path) out-of-bounds issue when deleting multiple array indexes

2. JSONPath Syntax Reference

Syntax Element	Description
`$`	Root node identifier
`@`	Current node identifier (valid only in filter selectors)
`[<selectors>]`	Child segment: selects zero or more child nodes of a node
`.name`	Shorthand for `['name']`
`.*`	Shorthand for `[*]`
`..[<selectors>]`	Descendant segment: selects zero or more descendants of a node
`..name`	Shorthand for `..['name']`
`..*`	Shorthand for `..[*]`
`'name'`	Name selector: selects named child of an object
`*`	Wildcard selector: selects all children of a node
`3`	Index selector: selects array index item (0-based)
`0:100:5`	Array slice selector: `start:end:step` for arrays
`?<logical-expr>`	Filter selector: selects specific items using logical expressions
`fun(@.foo)`	Filter function: calls function in filter expression (IETF standard)
`.fun()`	Aggregate function: used as a segment (jayway style)

Filter selector syntax reference:

Syntax	Description	Precedence
`(...)`	Grouping	5
`name(...)`	Function extension	5
`!`	Logical `NOT`	4
`==`,`!=`,`<`,`<=`,`>`,`>=`	Relational comparison operators	3
`&&`	Logical `AND`	2
`\	\	`

IETF JSONPath (RFC 9535) Standard Defined Operators (Supported)

Operator	Description	Example
`==`	Left equals right (note: 1 does not equal '1')	`$[?(@.a == 1)]`
`!=`	Left does not equal right	`$[?(@.a != 1)]`
`<`	Left is less than right	`$[?(@.a < 1)]`
`<=`	Left is less than or equal to right	`$[?(@.a <= 1)]`
`>`	Left is greater than right	`$[?(@.a > 1)]`
`>=`	Left is greater than or equal to right	`$[?(@.a >= 1)]`

jayway.jsonpath Extended Operators (Supported)

Operator	Description	Example
`=~`	Left matches regex	`[?(@.s =~ /foo.*?/i)]`
`in`	Left exists in right	`[?(@.s in ['S', 'M'])]`
`nin`	Left does not exist in right
`subsetof`	Left is a subset of right	`[?(@.s subsetof ['S', 'M', 'L'])]`
`anyof`	Left has at least one intersection with right	`[?(@.s anyof ['M', 'L'])]`
`noneof`	Left has no intersection with right	`[?(@.s noneof ['M', 'L'])]`
`size`	Left (array or string) size should match right	`$[?(@.s size @.expected_size)]`
`empty`	Left (array or string) should be empty	`$[?(@.s empty false)]`

IETF JSONPath (RFC 9535) Standard Defined Functions (Supported)

Function	Description	Parameter Type	Result Type
`length(x)`	Length of string, array, or object	Value	Number
`count(x)`	Size of node list	Node List	Number
`match(x,y)`	Regex full match	Value, Value	Boolean
`search(x,y)`	Regex substring match	Value, Value	Boolean
`value(x)`	Value of single node in node list	Node List	Value

jayway.jsonpath Functions (Supported)

Function	Description	Output Type
`length()`	Length of string, array, or object	Integer
`min()`	Find minimum value in current numeric array	Double
`max()`	Find maximum value in current numeric array	Double
`avg()`	Calculate average of current numeric array	Double
`stddev()`	Calculate standard deviation of current numeric array	Double
`sum()`	Calculate sum of current numeric array	Double
`keys()`	Get property key set of current object	`Set<E>`
`concat(X)`	Concatenate an item or collection with current array into new array	like input
`append(X)`	Append an item or collection to current path's output array	like input
`first()`	Return first element of current array	Depends on array element type
`last()`	Return last element of current array	Depends on array element type
`index(X)`	Return element at index X in current array. X can be negative (counting from end)	Depends on array element type

Breathing Soul into AI: How to Implement a Self-Reflecting Long-Term Memory System in Java AI

noear — Sun, 22 Feb 2026 12:41:03 +0000

In the world of AI Agents, there is a famous saying: "An Agent without memory is just a sophisticated function; an Agent with memory has a soul."

However, implementing a memory system in the Java ecosystem that truly possesses "self-evolving" capabilities is no easy feat. This article provides a deep dive into how to build a long-term memory component capable of extraction, consolidation, pruning, and retrieval based on the Solon AI framework and inspired by the core concepts of the MemSkill paper.

I. The Challenge of Long-Term Memory in Agents

Currently, memory implementation in most AI applications is overly simplistic: they just stuff recent conversation logs into the context window. This approach faces three major hurdles:

Context Overflow: LLM context windows are expensive and finite. "Stream-of-consciousness" memory hits the limit very quickly.
Cognitive Noise: Irrelevant information in historical logs interferes with the AI's judgment on current tasks.
Cognitive Conflict: When a user's status changes (e.g., "I used to like Java, but now I prefer Go"), simple retrieval (RAG) often pulls up outdated information, leading to logical confusion.

The Core Philosophy of MemSkill: An Agent should not just passively store and retrieve data. Like a human, it should actively summarize facts, correct errors, and upscale fragmented information into a structured Mental Model.

II. Thinking and Design: Mental Model Self-Evolution

The MemSkill we are designing follows four core actions:

Extract: Identify key facts from the conversation and assign importance.
Consolidate: Compress multiple low-level facts into high-level user preference summaries.
Prune: Identify and delete outdated or incorrect memories.
Search: Use semantic search to retrieve the most relevant context.

Architecture Design

To ensure production-grade reliability, we utilize a Two-Tier Storage Architecture:

Redis (KV Storage): Leverages TTL mechanisms to physically expire memories based on their Importance.
Vector/Lucene (Semantic Index): Provides multi-tenant isolated semantic retrieval capabilities.

III. Code Implementation: Building the MemSkill Core

1. The Memory Search Provider (MemSearchProvider)

First, we define an abstraction layer that can interface with either a distributed Vector Database or a local Lucene index.

public interface MemSearchProvider {
    /** Semantic/Fuzzy Search */
    List<MemSearchResult> search(String userId, String query, int limit);
    /** Get high-value "hot" memories for profile injection */
    List<MemSearchResult> getHotMemories(String userId, int limit);
    /** Sync Index */
    void updateIndex(String userId, String key, String fact, int importance, String time);
    /** Remove Index */
    void removeIndex(String userId, String key);
}

2. The Core Skill Class: MemSkill

This is the "mental processor" of the Agent. It provides tools for the AI to call and dynamically injects the user profile via getInstruction before the dialogue begins.

public class MemSkill extends AbsSkill {
    private final RedisClient redis;
    private final String userId;
    private final MemSearchProvider searchProvider;

    @Override
    public String getInstruction(Prompt prompt) {
        // Dynamically load the top 5 core cognitive fragments
        List<MemSearchResult> hot = searchProvider.getHotMemories(userId, 5);
        String mentalModel = formatModel(hot);

        return "### Long-Term Memory Self-Evolution Guide\n" +
               "1. **Core Mental Model**: This is your existing knowledge of the user:\n" + mentalModel +
               "\n2. **Cognitive Evolution Principles**:\n" +
               "   - **Temporal Priority**: In case of conflict, trust the most recent timestamp.\n" +
               "   - **Active Correction**: If the current status conflicts with the model, you MUST update via `mem_extract` or `mem_prune`.";
    }

    @ToolMapping(name = "mem_extract", description = "Extract facts or preferences into the mental model")
    public String extract(@Param("key") String key, @Param("fact") String fact, @Param("importance") int importance) {
        // 1. Retrieve old memory for reflection
        String oldJson = redis.getBucket().get(getFinalKey(key));

        // 2. Dynamic TTL: Core summaries (>=10) last forever; common facts last 7-30 days
        int ttl = calculateTTL(importance);

        // 3. Sync to Redis and Search Provider
        saveMemory(key, fact, importance, ttl);

        return "[Operation Successful] Mental model updated. If cognitive differences are found, please reflect this evolution in your response.";
    }
}

3. Local Implementation: Lucene Adapter

For many Java developers, deploying a full vector database is too costly. We implemented a Lucene-based MemSearchProvider that supports multi-tenant isolated semantic matching on local disk or in memory.

public class MemSearchProviderLuceneImpl implements MemSearchProvider, AutoCloseable {
    private final IndexWriter writer;

    @Override
    public List<MemSearchResult> search(String userId, String query, int limit) {
        // Implementation via BooleanQuery (user_id = X AND content LIKE query)
        BooleanQuery.Builder mainQuery = new BooleanQuery.Builder();
        mainQuery.add(new TermQuery(new Term("user_id", userId)), BooleanClause.Occur.MUST);
        // ... Add QueryParser for the query string

        // Sort by relevance (or importance) and return
        TopDocs topDocs = searcher.search(mainQuery.build(), limit);
        // ... Map to MemSearchResult
    }
}

IV. The Elegance of This Implementation

Cognitive Reflection (Reflexion): During mem_extract, the system feeds the old memory fragment back to the AI. This triggers an "awareness" mechanism in the Agent, allowing it to say: "I remember you mentioned A before, but now you seem to prefer B. I have updated my understanding for you."
Importance-Driven Lifecycle: Not all memories are created equal. By controlling TTL through importance, we achieve a natural sedimentation from "ephemeral memory" to "long-term experience."
Designer Role Injection: Through getInstruction, we turn the mental model into the Agent's "pre-conscious awareness," which is more efficient and human-like than simple Tool Call retrieval.

V. Conclusion

In the Solon AI ecosystem, the implementation of solon-ai-skill-memory proves that long-term memory is not just about data stacking, but about cognitive management. Through this self-evolving solution based on Lucene/Redis, Java developers can easily build Agents that never forget and are capable of deep self-reflection.

Appendix: Full Implementation Reference

package org.noear.solon.ai.skills.memory;

import org.noear.redisx.RedisClient;
import org.noear.snack4.ONode;
import org.noear.solon.Utils;
import org.noear.solon.ai.annotation.ToolMapping;
import org.noear.solon.ai.chat.skill.AbsSkill;
import org.noear.solon.ai.chat.prompt.Prompt;
import org.noear.solon.annotation.Param;
import org.noear.solon.core.util.Assert;
import org.noear.solon.lang.Preview;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

import java.util.*;
import java.time.LocalDateTime;
import java.time.format.DateTimeFormatter;

/**
 * MemSkill: Long-term memory skill based on a self-evolving mental model.
 *
 * Follows core MemSkill principles: Extract, Consolidate, Prune, Search.
 * Guides the Agent's cognitive updates via Designer instructions.
 */
public class MemSkill extends AbsSkill {
    private static final Logger LOG = LoggerFactory.getLogger(MemSkill.class);
    private static final String BASE_PREFIX = "ai:memskill:";

    private final RedisClient redis;
    private final String userId;
    private final MemSearchProvider searchProvider;

    public MemSkill(RedisClient redis, String userId, MemSearchProvider searchProvider) {
        this.redis = redis;
        this.userId = userId;
        this.searchProvider = searchProvider;
    }

    @Override
    public String name() { return "mem_skill"; }

    @Override
    public String description() {
        return "Long-term memory expert: Manages extraction, evolution, conflict resolution, and deep retrieval of user mental models.";
    }

    @Override
    public String getInstruction(Prompt prompt) {
        String mentalModel = "";
        if (searchProvider != null) {
            List<MemSearchResult> hot = searchProvider.getHotMemories(userId, 5);
            if (!hot.isEmpty()) {
                StringBuilder sb = new StringBuilder();
                for (MemSearchResult r : hot) {
                    sb.append(String.format("- %s: %s (Time: %s)\n", r.key, r.content, r.time));
                }
                mentalModel = sb.toString();
            }
        }

        return "### Long-Term Memory Self-Evolution Guide (Current System Time: " + getNow() + ")\n" +
                "You have the ability to autonomously manage and evolve the user's mental model. Please follow these principles:\n" +
                "1. **Core Mental Model**: This is your existing knowledge of the current user. Base your conversation on this:\n" +
                (Assert.isEmpty(mentalModel) ? "- (Mental model under construction, please ask questions to learn about the user)" : mentalModel) +
                "\n\n2. **Cognitive Evolution Principles**:\n" +
                "   - **Temporal Priority**: If records conflict, the one with the most recent timestamp prevails.\n" +
                "   - **Active Correction**: If the user's current status conflicts with the model above, you MUST update via `mem_extract` or remove via `mem_prune`.\n" +
                "   - **Inductive Upscaling**: When the cognitive base becomes redundant, proactively use `mem_consolidate` to summarize low-level facts into high-level preferences.";
    }

    private String getFinalKey(String key) { return BASE_PREFIX + userId + ":" + key; }

    private String getNow() { return LocalDateTime.now().format(DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss")); }

    @ToolMapping(name = "mem_extract",
            description = "Store facts, preferences, or progress into the user mental model. If the Key exists, the system returns the old record for reflection.")
    public String extract(@Param("key") String key,
                          @Param("fact") String fact,
                          @Param("importance") int importance) {
        try {
            String finalKey = getFinalKey(key);
            String oldJson = redis.getBucket().get(finalKey);
            String now = getNow();

            StringBuilder feedback = new StringBuilder("[Operation Successful] Mental model updated.");
            if (Utils.isNotEmpty(oldJson)) {
                ONode old = ONode.ofJson(oldJson);
                feedback.append("\n[Cognitive Contrast] Historical record found:")
                        .append("\n- Old Content: ").append(old.get("content").getString())
                        .append("\n- Old Time: ").append(old.get("time").getString())
                        .append("\nPlease compare the differences. If a change occurred, reflect this cognitive evolution in subsequent dialogue.");
            }

            Map<String, Object> data = new HashMap<>();
            data.put("content", fact);
            data.put("time", now);
            data.put("importance", importance);

            int ttl;
            if (importance >= 10) ttl = -1; 
            else if (importance >= 5) ttl = 2592000; // 30 days
            else ttl = 604800; // 7 days

            redis.getBucket().store(finalKey, ONode.serialize(data), ttl);

            if (searchProvider != null) {
                searchProvider.updateIndex(userId, key, fact, importance, now);
            }

            return feedback.toString();
        } catch (Exception e) {
            LOG.error("MemSkill extract error", e);
            return "Storage exception.";
        }
    }

    @ToolMapping(name = "mem_search",
            description = "Semantic Retrieval: Find relevant memory fragments in the mental model via natural language to retrieve background information.")
    public String search(@Param("query") String query) {
        if (searchProvider == null) return "Search provider not configured.";

        List<MemSearchResult> results = searchProvider.search(userId, query, 3);
        if (results.isEmpty()) return "No relevant cognitive fragments found.";

        StringBuilder sb = new StringBuilder("Matched cognitive references (Prefer the most recent timestamps):\n");
        for (MemSearchResult res : results) {
            sb.append(String.format("- [%s] (Key: %s): %s\n",
                    Utils.isNotEmpty(res.time) ? res.time : "Unknown Time", res.key, res.content));
        }
        return sb.toString();
    }

    @ToolMapping(name = "mem_recall", description = "Exact Recall: Get full details of a cognitive entry via Key.")
    public String recall(@Param("key") String key) {
        try {
            String val = redis.getBucket().get(getFinalKey(key));
            if (Utils.isEmpty(val)) return "Cognitive entry [" + key + "] not found.";
            ONode node = ONode.ofJson(val);
            return String.format("[Cognitive Details] Content: %s | Time: %s | Importance: %s",
                    node.get("content").getString(), node.get("time").getString(), node.get("importance").getString());
        } catch (Exception e) { return "Read exception."; }
    }

    @ToolMapping(name = "mem_consolidate",
            description = "Cognitive Consolidation: Merge multiple low-level fact fragments into a high-level preference model and prune redundant fragments.")
    public String consolidate(@Param("keys_to_merge") List<String> oldKeys,
                              @Param("new_key") String newKey,
                              @Param("evolved_insight") String insight) {
        String fact = "[Evolved Insight] " + insight;
        extract(newKey, fact, 10); 

        for (String k : oldKeys) {
            prune(k);
        }

        return "[Cognitive Evolution Successful] Fragments summarized into core insights; redundant records removed.";
    }

    @ToolMapping(name = "mem_prune", description = "Cognitive Correction: Delete incorrect, duplicate, or outdated knowledge.")
    public String prune(@Param("key") String key) {
        redis.getBucket().remove(getFinalKey(key));
        if (searchProvider != null) searchProvider.removeIndex(userId, key);
        return "Key cleared from model: " + key;
    }
}

Java Edition of Claude Code CLI is Here! Solon Code CLI Released

noear — Fri, 20 Feb 2026 08:38:35 +0000

When AI meets code, and the essence of Claude Code meets the Solon AI framework—a smart terminal assistant truly belonging to the Java ecosystem is born.

Remember the shock when Claude Code CLI was released? That AI assistant capable of chatting in the terminal, generating videos, sending emails, writing code, and understanding project structures finally has a Java implementation!

Today, the Solon AI framework officially launches Solon Code CLI — a smart terminal tool that fully embraces the design philosophy of Claude Code CLI while deeply integrating with the Java ecosystem.

Compatible with Claude Code Agent Skills specifications
Compatible with CLAUDE.md specifications

1. This is Not a Simple "Wrapper"

Solon Code CLI does more than just mimic the surface features of Claude Code CLI. From its foundation (Solon AI) to its core logic and interaction patterns, it aligns with the Claude Code philosophy across the board and features deep optimizations for Java development scenarios. Licensed under the MIT Open Source License, it allows for arbitrary modification and customization.

2. Minimalist Interaction, Ultimate Experience

After modifying the LLM configuration in README.md (you can even give it a nickname like "Xiaohua"), run run.sh (Mac/Linux) or run.cmd (Windows) to enter a whole new world:

Xiaohua v0.0.12
/Users/yourname/projects/myapp/


User
>

No bloated command parameters, no complex configurations. Just like talking to an experienced programmer, you only need to state your requirements.

3. Intelligent Project Recognition

Like Claude Code CLI, Solon Code CLI uses the init command to automatically identify your project structure, technology stack, and local file index:

Xiaohua v0.0.12
/Users/yourname/projects/myapp/


User
> init
Re-initializing workspace...
Local index refreshed successfully! 172 files scanned and indexed in 154ms.
Verified project contract. (Maven(Root))

User
>

It generates a CLAUDE.md file in your project root—the heart of the Claude Code specification—recording build commands, testing methods, and coding standards. This file serves as a "living document" for both the AI and your team members.

4. True "Engineering-Grade" AI Capabilities

Solon Code CLI is not just a chatbot; it is an AI assistant that understands engineering and code.

a) Code Understanding and Search

Xiaohua v0.0.12
/Users/yourname/projects/myapp/


User
> init
Re-initializing workspace...
Local index refreshed successfully! 172 files scanned and indexed in 154ms.
Verified project contract. (Maven(Root))

User
> Local search server related code

Xiaohua
  Users who want to find the server-specific code of the protocol need to search locally for the server-specific code. I should use full_text_search to search for server related content in the project.



❯ full_text_search query=server
 Found 19 results (sorted by relevance) :

  Path: acp-core/src/test/java/com/agentclientprotocol/sdk/spec/McpServerConfigurationTest.java (Score: 1.94, Line: ~22)
     Preview: ...sertj.core.api.Assertions.assertThat;  /**  * Tests for MCP server configuration serialization and deserialization.  *  * <p>  * Per the ACP spec:  * <ul>  * <li>Stdio transport: N...

Based on Lucene-powered intelligent search, it instantly locates the critical code you need.

b) Code Modification and Verification

User
> Give WebSocketAcpAgentTransport class under the perfect log (based on slf4j specification)

Xiaohua
  I searched for this class first and then refined the SLF4J log for it.

❯ full_text_search query=WebSocketAcpAgentTransport
  Five results were found (in order of relevance) :

  Path: acp-websocket-jetty/src/test/java/com/agentclientprotocol/sdk/agent/transport/WebSocketAcpAgentTransportTest.java (Score: 3.28, Line: ~18)
     Preview: ...ssertions.assertThatThrownBy;  /**  * Unit tests for {@link WebSocketAcpAgentTransport}.  */ class WebSocketAcpAgentTransportTest {    private McpJsonMapper jsonMapper;   @BeforeEac...

  Path: acp-websocket-jetty/src/test/java/com/agentclientprotocol/sdk/integration/WebSocketClientAgentTest.java (Score: 2.68, Line: ~14)
     Preview: ...ncAgent; import com.agentclientprotocol.sdk.agent.transport.WebSocketAcpAgentTransport; import com.agentclientprotocol.sdk.client.AcpAsyncClient; import com.agentclientprotocol.sdk...

  Path: acp-websocket-jetty/src/main/java/com/agentclientprotocol/sdk/agent/transport/WebSocketAcpAgentTransport.java (Score: 2.57, Line: ~70)
     Preview: ...ncy>  * }</pre>  *  * @author Mark Pollack  */ public class WebSocketAcpAgentTransport implements AcpAgentTransport {      private static final Logger logger = LoggerFactory.getLogger...

  Path: README.md (Score: 1.65, Line: ~342)
     Preview: ...```

java import com.agentclientprotocol.sdk.agent.transport.WebSocketAcpAgentTransport;  var transport = new WebSocketAcpAgentTransport(     8080,                           // port...

  Path: acp-agent-support/README.md (Score: 1.01, Line: ~291)
     Preview: ...create())     .run();

 ```  ### WebSocket Transport  ```

java WebSocketAcpAgentTransport transport = WebSocketAcpAgentTransport.builder()     .host("localhost")     .port(8080)     ....
  (End of output)

❯ read_file

Solon Code CLI follows the "verification-driven" principle of Claude Code: tests must be run after modifying code to ensure changes are safe and reliable.

c) Secure Command Execution

For high-risk operations, Solon Code CLI features a built-in security audit policy similar to Claude Code. It intelligently intercepts:



User
> Get the contents of https://solon.noear.org/ web page

Xiaohua
  The user wants to access the contents of https://solon.noear.org/. I need to use a tool that fetches web content.

  Looking at the available tools, I see that there are these related tools:
  1. 'bash' - can execute shell commands like curl or wget
  2. 'full_text_search' - This is a local full-text search, not getting the content of the web page
  3. Other tools are mainly related to file manipulation

  The most straightforward way is to use the 'bash' tool to execute the curl command to get the content of the web page.

  Let me help you get the content of this web page.
   (8554 tokens)

Permission Required
Command: curl -s https://solon.noear.org/
Approve? (y/n)

It intelligently intercepts (via the customizable HitlStrategy) :

System privileged commands (sudo, chmod, chown)
Network outbound operations (curl, wget, ssh)
Path traversal attacks (../)
Combined command injections (;, &)

Only risky operations that you confirm will be executed, and security is fully aligned with Claude Code.

5. Three Connection Modes: AI Everywhere

Solon Code CLI adopts the "Pool-Box Model"—one AI core with three connection methods:

a) CLI Mode


yml
solon.code.cli:
  cliEnabled: true
  cliPrintSimplified: true

Directly chat with AI in the terminal for the purest experience. (Enabled by default via cliEnabled: true).

b) Web Mode


yml
solon.code.cli:
  webEnabled: false
  webEndpoint: "/cli"

Access http://localhost:8080/cli via a browser for a visual interactive interface.

c) ACP Protocol Mode

Solon Code CLI implements the ACP (Agent Communication Protocol), allowing seamless connection to any IDE plugin or client supporting the protocol. This means:

Future direct use in VS Code or IntelliJ IDEA.
Support for remote connections (AI runs on your server while you operate locally).
Shared AI computing resources for teams.


yml
solon.code.cli:
  acpEnabled: false
  acpTransport: "websocket" # "stdio" or "websocket"
  acpEndpoint: "/acp"

6. Quick Start

Download (17MB):



https://github.com/opensolon/soloncodecli/releases/download/v0.0.12/SolonCodeCLI_v0.0.12.zip
https://gitee.com/opensolon/soloncodecli/releases/download/v0.0.12/SolonCodeCLI_v0.0.12.zip

Configuration:

Extract the package and adjust application.yaml with your API Key and Model details (e.g., DeepSeek, OpenAI, etc.).


yaml
solon:
  code:
    cli:
      nickname: "Xiaohua"
      workDir: "my-project"
      chatModel:
        apiUrl: "https://api.deepseek.com/v1/chat/completions"
        apiKey: "sk-xxxx"
        model: "deepseek-chat"
      planningMode: true
      hitlEnabled: true

Run:



# For Mac or Linux
sh run.sh

# For Windows
run.cmd

# Or native Java command
java -jar SolonCodeCLI.jar

7. Conclusion

Solon Code CLI is not intended to replace Claude Code; rather, it brings this advanced AI programming paradigm into the customizable Java world , allowing every Java developer to enjoy the efficiency revolution brought by AI.

It is open-source (MIT), customizable, and deeply integrated. You can integrate it into your CI/CD pipelines, build your own AI toolchains, or empower your entire development team.

The Java edition of Claude Code is here. Are you ready?

Project Address: https://github.com/opensolon/soloncodecli

Solon Code CLI — Born for Java developers, an intelligent terminal assistant sharing the same DNA as Claude Code.

Converting Everything to MCP is Foolish! AI Skills Are the Way Forward

noear — Mon, 02 Feb 2026 10:51:47 +0000

The hype surrounding MCP (Model Context Protocol) has arguably gone too far. Since Anthropic unveiled this protocol, many in the industry have become restless, acting as if they won’t secure a ticket to the AI era unless they rewrite their business interfaces as MCP Servers overnight.

Every few years, the tech world is swept by a hurricane of "unified protocols" (much like a few years ago when everyone rushed to dismantle monoliths into microservices). The essence of architecture is solving problems, not chasing an expensive sense of ritual. Forcing every business function into MCP is not just strategic laziness; it is tactical self-torture. For developers deeply rooted in real-world business logic, the Skill Pattern is the true path to clarity.

I. The Deification of MCP: Ritual Should Not Outweigh Productivity

We must admit that the intention behind MCP is good; it attempts to establish a universal "dialogue logic" between heterogeneous systems and AI Agents. Enterprises are flocking to it because they hope a standardized protocol will once and for all solve the problem of connecting AI to internal private data.

However, in the eyes of senior architects, "standardization" is often a smokescreen for over-engineering. Consider our core requirement: we simply want the AI to smoothly call an inquiry interface that has been running reliably for three years. To get this "sip of vinegar," MCP forces you to make a complex "feast of dumplings": you must set up a compliant Server, wrestle with intricate transport protocols, and map resources. This isn’t integration; it’s building a massive wall around your business system. Great architecture should dissolve into the background, not impose itself with overbearing "diplomatic formalities."

II. The "Three Mountains" of MCP Implementation

In a real production environment, MCP is far from the panacea it's advertised to be. It presents at least three hurdles that can mire a mature team in a swamp of technical debt.

1. The Curse of Development Cost and Dual Codebases

MCP requires a full protocol implementation. This means you must maintain not only your original business logic but also a separate "protocol translation logic." This isn't just a few extra lines of code; it means double the documentation, double the test cases, and a double breeding ground for bugs. For teams wanting AI to take over logic quickly, this "dual maintenance" is an architectural disaster.

2. Context Bloat vs. Token Consumption

This is MCP’s fatal weakness. Defining a large number of tools involves massive amounts of metadata and redundant descriptions. When an LLM tries to understand a tool list provided by an MCP Server, this verbose protocol text quickly chokes the Context Window. The result? A sharp spike in Token consumption and agonizingly long response latencies. In high-concurrency business scenarios, this waste is unacceptable.

3. The Mystery of Debugging Nightmares

With every layer added to an architecture, the system's entropy doubles. When an AI call fails, where do you look? Is it a "prompt drift"? A misconfiguration in the protocol layer? Or a failure in the underlying business logic? This bottomless path of troubleshooting is a nightmare that no veteran architect wants to face.

III. Why "Skills" Are the Soul of Business

Stepping away from heavy protocols, let’s look at what we call a Skill. In the design philosophy of Solon AI, a Skill is not a heavy contract, but an "elegant packaging of capability."

The core logic is simple: the business does not need to adapt to the protocol; the protocol should adapt to the business.

Code as a Skill: A method you’ve already written perfectly, once annotated, becomes a Skill.
Interface as a Skill: An existing Swagger/OpenAPI document, once imported, becomes a Skill.
Data as a Skill: A database connection with read-only permissions becomes a Skill (Text-to-SQL).

This bottom-up evolution aligns with the natural laws of system development.

IV. A Dimensional Strike: Skill Practice in Solon AI

As a senior developer, I care most about the "Input-Output Ratio." Let’s see how Solon AI uses the Skill pattern to deliver a "dimensional strike" against the complexity of MCP.

Example 1: RestApiSkill — Activating Legacy Interfaces at Zero Cost

If you have a collection of REST interfaces, you don't need to write a single line of new code for them. In Solon AI, this is seamless:

// 1. "Take-ism": Directly read the business system's Swagger documentation.
// Just provide a URL, and the AI automatically parses all Paths, Methods, and parameter descriptions.
RestApiSkill orderSkill = new RestApiSkill("http://api.yoursite.com/v2/api-docs", "http://api.yoursite.com");

// 2. Drop it into the Agent; it becomes a "Business Expert" instantly.
ReActAgent agent = ReActAgent.of(chatModel)
        .role("Order Manager")
        .defaultSkillAdd(orderSkill) // Injecting the Skill
        .build();

// 3. The AI now knows how to check inventory, place orders, and update statuses.
agent.prompt("Has the order ending in 9527 been shipped?").call();

Example 2: Text2SqlSkill — Turning Data Directly into Reports

Previously, if a boss wanted a figure, you had to write a DAO, SQL, and a Controller. Now, you give the database capability directly to the AI:

// Connect to the database and tell it which tables it manages.
Text2SqlSkill sqlSkill = new Text2SqlSkill(dataSource, "users", "orders", "refunds")
        .maxRows(50); // Security policy: return a maximum of 50 rows.

ReActAgent agent = ReActAgent.of(chatModel)
        .role("Financial Analyst")
        .defaultSkillAdd(sqlSkill)
        .build();

// The AI reasons: "To check the total, I need to execute SUM(...)," then generates and runs the SQL.
agent.prompt("What was the total refund amount for the East China region last month?").call();

The contrast is clear: agent.defaultSkillAdd(...) is exponentially more efficient than developing a complex MCP node. This is true business-centric "dimensional strike."

V. Deep Dive: Architectural Advantages of the Skill Pattern

In terms of architectural selection, the Skill pattern wins on three fronts: Agility, Stability, and Reusability.

Low Coupling (Agility): Skills can be local or remote. They attach to an Agent like plugins—unplug them at any time without hurting the core business.
Strong Type Safety (Stability): By leveraging Java’s mature type system and JSON Schema validation, we can precisely control every parameter the AI passes. Unlike the loose messaging of MCP, the Skill pattern locks down risks before execution.
High Reusability (Reusability): Once a Skill is written, it can be used in a simple ChatModel / SimpleAgent or called within a complex ReActAgent reasoning loop.

VI. Conclusion: Return to Engineering Essence, Choose Path Wisely

The true meaning of architectural design lies not in chasing the "newest" but in pursuing the "most suitable." By comparison, the Skill pattern offers a more pragmatic choice: it implements a seamless connection between business logic and Agents via lightweight packaging, ensuring every bit of computing power is spent on core business reasoning.

We need surgical precision and lightness. Abandon those cumbersome protocol translations and release your business potential with the Skill pattern. Remember: The best technology is the one you don't even feel is there.

Slogan: Business is King, Skill is the Path. Don't let protocols become the stumbling block to your AI era.

On the Inevitability of Distributed AI Skills: The Transition from Monolithic Intelligence to a "Cloud-Based Brain"

noear — Wed, 28 Jan 2026 02:47:37 +0000

In the evolution of Artificial Intelligence from "Conversational Models" to "Agentic AI," we are at a critical turning point—similar to the transition of the Internet from standalone software to distributed architectures. At the heart of this transformation lies the rise of AI Skills and the inevitability of their distributed development.

1. What are AI Skills: Evolution from Tool-level to Framework-level

The concept of AI Skills was initially popularized in cutting-edge Agent practices like Claude Code. Originally, Skills were viewed as "tool-level" enhancements—simple file I/O or terminal operations—allowing users to quickly perform various tasks.

However, in modern application development frameworks like Solon AI, AI Skills have evolved into a higher-dimensional abstraction designed for Agent application development.

Tool-level: Solves the problem of the "hands"; these are specific execution functions.
Framework-level: Solves the problem of the "brain." A Skill is an aggregation of Tools, Instructions, and Metadata. It encompasses not just execution logic, but also admission control, instruction augmentation, and tool "tinting" (tracing/tagging) capabilities.

2. Core Characteristics of AI Skills

To address the issues of context noise, permission vacuums, and loss of behavioral control found in traditional Tool models, a mature AI Skill must possess the following traits:

Intelligent Admission (isSupported): A Skill is activated only when specific intents, tenants, or environmental conditions (Prompt Context) are met. This prevents ineffective tools from cluttering the model's context and wasting tokens.
Instruction Injection (getInstruction): Provides the model with "rules of conduct" based on the current context, solving the problem of how the model should act.
Tool Routing (getTools): Dynamically distributes tools based on the current context.
High Autonomy: Logic within a specific domain is handled as a closed loop within the Skill, outputting standardized results to the external environment.

3. MCP: The World Wide Web Protocol for the AI Era

With the explosion of skill demands, the Model Context Protocol (MCP) emerged. It is the standard protocol connecting AI models with external data and tools.

MCP is to AI what HTTP is to the World Wide Web.

In the Internet era, HTTP allows any browser to access resources on any server. In the AI era, MCP allows any Agent to seamlessly call skills provided by different vendors across different physical locations. This standardization completely shatters the "hard-coded" shackles between Agents and the external world.

4. Distributed Evolution of Tools: The Birth of MCP Tools

The form of "Tools" is undergoing a fundamental change: evolving from local monoliths to MCP Tools (Distributed Tools). These possess physical location transparency; they are no longer functions in local memory, but independent distributed capability nodes. This "node-ization" of capabilities is the first step for AI toward a microservices architecture.

Traditional Tools: Code-level coupling, running inside the Agent process, difficult to reuse across languages or environments.
MCP Tools (Distributed Tools): Exposed via the MCP protocol, offering location transparency. They function as independent capability nodes.

5. Architectural Mapping: From Distributed MCP Tools to MCP Skills

The distribution of Tools provides a natural path for the distribution of AI Skills. When we publish a set of Skills—comprising business logic, instruction guidance, and toolsets—via the MCP protocol, they evolve into MCP Skills.

We can clearly map the distributed blueprint of AI Agents to traditional architectures:

MCP is equivalent to RPC (Remote Procedure Call): It defines how models and capability nodes communicate; it is the underlying pipeline of the Agent world.
MCP Skills are equivalent to Microservices: Each Skill is an independent business unit with its own business semantics.

Note: Distributed AI Skills can also be implemented via traditional RPC systems, though this requires significantly more manual work.

6. Implementing MCP Skills: Collaboration between Client and Server

The core of implementing MCP Skills lies in mapping the lifecycle semantics of a Skill onto the endpoints of the MCP protocol.

1. McpSkillClient (Local Proxy for Remote Skills)

The McpSkillClient acts as a local proxy. Its responsibility is to shake hands with remote services and wrap network calls into a Skill interface.

Metadata Perception: Synchronizes remote metadata via agreed-upon paths.
Dynamic Mapping: At runtime, it converts local isSupported or getInstruction calls into remote MCP Tool calls.
Tool Filtering: Automatically removes management tools marked as hide, presenting the LLM only with the business tools relevant at that moment.

Application Example:

// 1. Build the MCP client provider (handles protocol communication and schema caching)
McpClientProvider mcpClient = McpClientProvider.builder()
                .channel(McpChannel.STREAMABLE)
                .url("http://localhost:8081/skill/order")
                .build();

// 2. Evolve the MCP client into a Skill proxy
McpSkillClient skillClient = new McpSkillClient(mcpClient);

// 3. Build a Prompt with business context
Prompt prompt = Prompt.of("Order: A001, please query order details.")
                .attrPut("tenant_id", "1")       // Inject tenant context
                .attrPut("user_role", "admin");  // Inject role permissions

// 4. Call the LLM; the skill will automatically complete: remote admission, instruction retrieval, and tool filtering
chatModel.prompt(prompt)
          .options(o -> o.skillAdd(skillClient))
          .call();

2. McpSkillServer (Perceptive Skill Server)

By extending McpSkillServer, developers can export local business logic as remote skills.

Lifecycle Exposure: Uses @ToolMapping and @ResourceMapping to export logic like isSupported and getInstruction.
Intelligent Perception: The server perceives intent through the passed Prompt state. For example, it decides which tools to return via getToolsName based on user roles.
Security Tagging: Adds hide:1 tags to management endpoints to ensure system-level instructions are not leaked to the model.

Application Example:

@McpServerEndpoint(channel = McpChannel.STREAMABLE_STATELESS, mcpEndpoint = "/skill/order")
public class OrderManagerSkillServer extends McpSkillServer {

    @Override
    public String description() {
        return "Expert skill for order queries and cancellations";
    }

    // Intelligent Admission: Decide whether to respond based on Prompt content and attributes
    @Override
    public boolean isSupported(Prompt prompt) {
        // Semantic check: Is the intent relevant?
        boolean isOrderTask = prompt.getUserContent().contains("order");
        // Security check: Tenant ID must be present
        boolean hasTenant = prompt.attr("tenant_id") != null;

        return isOrderTask && hasTenant;
    }

    // Dynamic Instruction: Inject real-time "rules of conduct" for the LLM based on context
    @Override
    public String getInstruction(Prompt prompt) {
        String tenantName = prompt.attrOrDefault("tenant_name", "Unknown Tenant");
        return "You are now the order supervisor for [" + tenantName + "]. Process only order data for this tenant; cross-tenant queries are forbidden.";
    }

    // Attachment Hook: Triggered when the skill is activated; used for logs or initializing context
    @Override
    public void onAttach(Prompt prompt) {
        // Few-shot or background knowledge can be injected here via prompt.addMessage()
        System.out.println("Order skill attached. Current tenant: " + prompt.attr("tenant_id"));
    }

    /**
     * Dynamic Capability Discovery: Decide which tools to expose based on user permissions
     * @return null: expose all; Empty: disable all; List: precisely expose specific tools.
     */
    @Override
    public List<String> getToolsName(Prompt prompt) {
        List<String> tools = new ArrayList<>();

        // Basic permission: Visible to all compliant users
        tools.add("OrderQueryTool");

        // Fine-grained permission: Cancellation tool visible only to ADMIN role
        if ("ADMIN".equals(prompt.attr("user_role"))) {
            tools.add("OrderCancelTool");
        }

        return tools;
    }

    @ToolMapping(description = "Query details by order ID")
    public String OrderQueryTool(String orderId) {
        return "Order " + orderId + " Status: Shipped";
    }

    @ToolMapping(description = "Cancel specific order")
    public String OrderCancelTool(String orderId) {
        return "Order " + orderId + " successfully cancelled";
    }
}

7. Summary of Inevitability

The distributed path for AI Skills is irreversible:

Decoupling and Reuse: Complex skills (e.g., legal auditing, professional code refactoring) no longer need to be rewritten in every project; they exist independently as services.
Security Boundaries: Sensitive data processing skills can be deployed in private, protected intranets, communicating with public Agents only through controlled MCP protocols.
Heterogeneous Ecosystems: Capabilities across different languages and computing environments can connect via a unified MCP interface, forming a true "Agent Microservices Network."

The emergence of MCP Skills (currently an architectural pattern rather than a formal specification) marks the end of the "personal toolbox" era in AI application development and the beginning of a true "Agent Microservices Network" era.

Solon AI Remote Skills: Enabling the "perception" of Distributed Skills

noear — Mon, 26 Jan 2026 05:17:35 +0000

Introduction: The "Last Mile" Challenge of AI Agents

In the engineering practice of AI agents, we are undergoing a transformation from "local integration" to "cloud-based plug-in." Over the past year, the industry has witnessed the rise of Model Context Protocol (MCP), which successfully solved the "protocol standardization" problem for cross-process connections between large models and external tools. However, with the deepening of enterprise-level scenarios, developers have found that simply achieving connectivity is not enough.

Today, Solon AI 3.9.0 officially proposes the concept of Remote Skills. This feature is not a simple encapsulation of MCP, but rather an evolution of the originally static, passively triggered MCP toolset into a distributed intelligent unit with business awareness, lifecycle management, and dynamic routing capabilities.

I. The Leap from MCP Tools to Remote Skills

The traditional MCP interaction mode is essentially a kind of "static broadcast." Once the server starts, it exposes all tools to the large model. This model works well in single-machine experimental environments, but in complex, multi-tenant, and high-security enterprise-level businesses, it triggers three critical engineering pain points:

1. Context Noise and Token Inflation:

The context window of a large model is expensive and finite. If a system has 500 tools, even for simple chat or basic queries, traditional MCP will cram the JSON schemas of all 500 tools into the System Prompt. This not only wastes a significant amount of token resources, but more seriously, excessive distracting information can cause the model to become "distracted," reducing the accuracy of inference.

2. Security Risks and Unauthorized Calls:

In the native architecture of MCP, the model's visibility to tools is "full." The model cannot spontaneously and dynamically hide sensitive operations based on the current user's role. For example, if an intern inquires about order information, the model might attempt to call the OrderCancel tool during inference. Although the execution layer can intercept this, the "see-and-try" approach itself poses a significant security risk.

3. Instruction Gap:

Tools describe "what they can do," but fail to tell the model "how to do it" in a specific context. For example, the same "interest rate query" tool might have drastically different preconditions in the business logic of the Shenzhen branch and the Shanghai branch; a static MCP protocol cannot convey this dynamic "behavioral guidelines."

The core idea of Remote Skills is to wrap remote tools within the Skill lifecycle, enabling them to perceive the current Prompt context, thus achieving a leap from "static description" to "dynamic contract."

II. Core Mechanisms: Perception, Mounting, and Dynamic Routing

Solon AI endows remote skills with the ability to "think" by establishing a context negotiation mechanism between McpSkillClient (client-side agent) and McpSkillServer (server-side implementation). This is primarily reflected in the following three aspects:

1. Intelligent Admission (isSupported): From "Full Loading" to "On-Demand Activation"

Remote Skills are no longer blindly activated. Before the session begins, the server parses the current Prompt attributes (such as tenant ID, user profile, and current intent attributes). By executing the isSupported logic, the server can determine whether the current skill participates in the conversation.

Engineering Value: Financial skills are only mounted to the memory graph when the conversation involves "financial statements" and the user has "auditor" permissions. This physically eliminates interference from irrelevant tools.

2. Dynamic Instruction Injection (getInstruction): Giving Tools a "Business Soul"

Skills are no longer just APIs. During mounting, the server dynamically issues instruction constraints based on the context using getInstruction. This mechanism allows developers to adjust the Agent's behavioral logic in real time without modifying the model prompts.

Example: When a request is detected to originate from a mobile device, the server injects: "Please keep your replies concise, use Markdown tables whenever possible, and do not exceed 200 characters."

3. Three-State Routing Capability (getToolsName): Fine-grained Permission Isolation

This is the most groundbreaking feature of Remote Skills. The server can dynamically determine which tool names to distribute based on the requester's identity, achieving "tool-level RBAC":

Full Authorization: Exposes all debugging and management tools to super administrators.
Precise Filtering: Hides high-risk tools like Delete or BatchUpdate for ordinary users.
Complete Interception: When an abnormal request is detected (such as an abnormal IP address), all tool access permissions can be instantly disabled even if the skill is activated.

III. Practical Application: Building Remote Skills with "Self-Reflection" Capabilities

1. Client: Extremely Simplified Integration Experience

In the Solon AI framework, McpSkillClient makes complex remote communication and protocol conversions transparent. Developers only need to focus on injecting business attributes (Attrs).

import org.noear.solon.ai.chat.ChatModel;
import org.noear.solon.ai.chat.prompt.Prompt;
import org.noear.solon.ai.mcp.McpChannel;
import org.noear.solon.ai.mcp.client.McpClientProvider;
import org.noear.solon.ai.mcp.client.McpSkillClient;

// 1. Build the mcp client
McpClientProvider mcpClient = McpClientProvider.builder()
                .channel(McpChannel.STREAMABLE)
                .url("http://localhost:8081//skill/order")
                .build();

// 2. Build prompt words with deep business attributes
Prompt prompt = Prompt.of("Help me with order A001")
                .attrPut("tenant_id", "solon_cloud")
                .attrPut("user_role", "ADMIN")
                .attrPut("client_ip", "10.0.0.1");

// 3. Injecting remote skill agents, the framework handles context pass-through automatically
chatModel.prompt(prompt)
         .options(o -> o.skillAdd(new McpSkillClient(mcpClient))) 
         .call();

2. Server-side: Declarative security capability export

By inheriting McpSkillServer, you can easily implement remote services with dynamic defense capabilities. Note how the tool is exposed through code logic control.


import org.noear.solon.ai.annotation.ToolMapping;
import org.noear.solon.ai.chat.prompt.Prompt;
import org.noear.solon.ai.mcp.McpChannel;
import org.noear.solon.ai.mcp.server.McpSkillServer;
import org.noear.solon.ai.mcp.server.annotation.McpServerEndpoint;

import java.util.ArrayList;
import java.util.List;

@McpServerEndpoint(channel = McpChannel.STREAMABLE, mcpEndpoint = "/skill/order")
public class OrderRemoteSkillServer extends McpSkillServer {

    @Override
    public boolean isSupported(Prompt prompt) {
        // Logical admission: If the request has no tenant identity, simply refuse to mount the skill
        return prompt.attr("tenant_id") != null;
    }

    @Override
    public List<String> getToolsName(Prompt prompt) {
        // Dynamic Routing: Achieving physical isolation of tools
        List<String> tools = new ArrayList<>();
        tools.add("OrderQuery"); 

        if ("ADMIN".equals(prompt.attr("user_role"))) {
            tools.add("OrderCancel"); // Visible only to administrators
        }
        return tools;
    }

    @ToolMapping(description = "Query order details, including logistics status")
    public String OrderQuery(String id) { ... }

    @ToolMapping(description = "Emergency cancel order, this action is not reversible")
    public String OrderCancel(String id) { ... }
}

IV. Architectural Reflection: Why is this an inevitable choice for enterprise-level agents?

Evolving MCP into Remote Skills represents a qualitative leap in the architectural quality of AI systems:

Extreme Context Purity: Through dynamic filtering, the model only sees the tools it should see "at this moment, by this person, and with this authority." This "minimize information principle" significantly improves inference success rate and substantially reduces token consumption, which directly impacts operational costs for large-scale concurrent systems.
Hardened Security: In the past, we attempted to defend against unauthorized calls using "prompt injections." However, under the Remote Skills architecture, access control has been elevated from a "constraint model" to "server-side physical filtering." Even if a large model attempts to attack unauthorized tools, the attack is impossible because the tool definitions have never been distributed.
Hot Updates and Governance of Capabilities: In a distributed environment, business logic, tool lists, and behavioral guidelines all converge on the remote server. This means that when business operations are adjusted (such as adding a refund restriction logic), developers only need to update the McpSkillServer code, and hundreds or thousands of running client agents can instantly receive capability upgrades without redeployment.

Solon AI Remote Skills is more than just an implementation of a protocol; it represents a profound reflection on "how to manage the capabilities of distributed intelligent agents." It allows AI plugins to move beyond the era of "static broadcasting" and into a new stage of "on-demand allocation and intelligent perception."

V. Looking to the Future: Towards "Skills as a Service"

Solon AI Remote Skills is more than just an implementation of a protocol; it represents a profound reflection on "how to manage AI capabilities like managing microservices." In future AI architectures, large models will no longer be bloated "universal boxes," but rather streamlined "inference hubs," connecting distributed expert units around the world on demand through the Remote Skills protocol.

By enabling AI plugins to move beyond "static broadcasting" and enter a new phase of "on-demand allocation and intelligent perception," Solon AI is providing developers with a more robust, controllable, and commercially valuable agent development framework.

Claude Code Agent Skills vs. Solon AI Skills: Deep Alignment of Architectural Philosophy with Engineering Boundaries

noear — Mon, 26 Jan 2026 05:13:36 +0000

With the explosive growth of AI Agent technology, the concept of "Skill" is gradually evolving from simple function calls into architectural units with lifecycles, perceptual capabilities, and complex logic. Recently, Anthropic's Claude Code and Solon AI have both proposed their own Skill systems.

Although they share the same name, their design intentions, application scenarios, and implementation logic are fundamentally different.

I. Role Positioning: Production Tool vs. Business Foundation

1. Claude Code Agent Skills: Efficiency Improvement Tools for "Developers"

Claude Code's Skills are essentially Local-First Agent capability extensions. They primarily serve end-users (developers), focusing on operating system-level interactions.

Core Scenarios: File system read/write, terminal command execution, code repository search.

Interaction Model: Typically runs in the user's local development environment, possessing extremely high local privileges.

2. Solon AI Skills: An Architecture Solution for "Enterprise-Level Business"

Solon AI's Skill is an Enterprise-Ready software architecture abstraction. It defines not only "what it can do," but also "what it can do in what business environment."

Core Scenarios: Multi-tenant SaaS systems, distributed business logic, cross-process capability discovery.

Interaction Model: Supports cross-process communication (e.g., via the MCP protocol), emphasizing capability scheduling in complex server-side environments.

II. Core Differences in Technical Features

Feature Dimensions	Claude Code Agent Skills	Solon AI Skills
Perception Capabilities	Static/Passive: Explicitly granted by the user or invoked on demand by the model.	Dynamic/Active: Possesses isSupported semantics, capable of context-aware activation.
Instruction Injection	Fixed: Skill descriptions are typically passed in as static Prompts.	Dynamic: Supports `getInstruction`, dynamically generating instructions based on the current tenant/role.
Access Control	Terminal Control: Relies on local permissions of the runtime environment.	Tri-state Routing: Supports dynamic distribution of tool lists based on business attributes (Role/Tenant).
Protocol Standard	Dedicated to the Claude ecosystem.	Compatible with the MCP protocol, enabling cross-process evolution through MCP.

III. The Game of Core Architecture Design

1. Static Definition vs. Dynamic Lifecycle

Claude Code's skills are more like a tool library. When a model needs a certain ability, it looks in the library. Solon AI introduces complete lifecycle hooks (onAttach, isSupported, etc.). This means that before the model speaks, the Skill has already completed identity verification, environment preparation, and instruction warm-up.

2. System Constraints vs. Business Constraints

Claude Code's constraints mainly come from the environment (e.g., prohibiting deletion of the root directory). Solon AI's constraints come from the business context.

Example: In Solon AI, a "refund skill" is aware of the user_role in the Prompt. If it's a regular user, the skill will return false in the isSupported phase; the model won't even see the word "refund" in the context, thus completely eliminating the possibility of unauthorized calls.

IV. Summary: How Should You Choose?

If you are developing a personal assistant, command-line tool, or assisted programming agent: Claude Code's approach is more suitable. It pursues extreme efficiency in operating local resources, allowing the model to manipulate files and terminals like a human developer.

If you are building an enterprise-level agent, a multi-tenant SaaS backend, or a complex distributed system: Solon AI Skills are a better choice. It solves the three major pain points of "contextual noise," "permission vacuum," and "uncontrolled behavior" by evolving MCPs into skills with awareness.

V. Conclusion: The Future of Skills is "Awareness"

LLM's native standards only include Prompt and Tool-Call. Both Claude and Solon's exploration of Skills demonstrates an engineering consensus: models shouldn't see all tools, but only those tools that are properly constrained, at the right time, and with the right permissions.

By deeply integrating MCP with the Skill system, Solon AI effectively provides enterprise-level agents with a capability distribution network "with a security gate."

Will Solon AI Skills be the future of Java AI Agents?

noear — Mon, 26 Jan 2026 05:10:34 +0000

As AI agents evolve from "conversational toys" to "industrial-grade infrastructure," the core challenge for developers is no longer model intelligence, but rather the lack of engineering constraints.

If you simply pile up scattered tools (functions) on a model, it's like a child wielding a scalpel without medical training. The emergence of Solon AI Skills marks a shift in AI development from "chaotic integration" to "capability internalization", injecting agents with truly practical "professional qualities."

Solon AI Skills (skills). The conceptual prototype references the design philosophy of Claude Code Agent Skills: endowing agents with domain-specific expert capabilities through structured definitions (metadata, instructions/SOPs, scripts/tools).

I. Redefining Skill: From "Component Assembly" to "Software-Defined Capabilities"

Solon AI Skills draws on the ideas of DDD (Domain-Driven Design), believing that a Skill is not merely a simple encapsulation of an API, but an autonomous semantic context.

Metadata (Identity Recognition): Defines the boundaries of capabilities, solving the "Who am I?" question.
Admission (Access Control): Borrows from Software-Defined Permissions (SDP), dynamically determines the visibility of capabilities, solving the "Should I use it?" question.
Instruction (Semantic Soul): Injects SOPs (Standard Operating Procedures), solving the "How to do it correctly?" question.
Tools (Physical Muscles): Equipped with atomic execution methods, solving the "What to use to do it?" question.

II. Core Value: Solving Four Major Pain Points of Industrial-Grade Agents

1. Logical Closed Loop: Enables the model to "think before you act, and act according to the rules."

A simple Tool cannot self-regulate. Through Skill.getInstruction(), developers can directly translate industry standards and compliance requirements into the model's "factory settings."

Architectural Upgrade: This achieves a shift from "model self-regulation" to "rule-driven execution".
Scenario Example: A "database migration skill."
Tool Mode: Directly calling drop_table by the model can lead to disaster.
Skill Mode: Skill commands mandate: "Before performing any deletion operation, backup_table must be called first, and an impact assessment report must be output to the console for user confirmation."

2. Dynamic Topology: Solving "Context Inflation" and the Curse of Attention

The context window of large models is not only expensive but also suffers from the "loss in the middle" effect. Full loading of tools can lead to excessive cognitive load on the model, resulting in severe task illusion.

Skill Solution: Dynamic mounting technology based on semantic triggering.
Engineering Value: Utilizing the isSupported interface, the system activates the relevant Skill only in specific intents. This "on-demand loading" mode greatly improves token utilization, ensuring the model makes high-precision decisions within a focused semantic field.

When a user says, "Analyze this financial statement for me," the system only activates the FinanceSkill. At this point, only relevant professional instructions and tools are injected into the System Message, keeping the mind clear and ensuring accurate decision-making.

3. Capability Coloring: Aligning with MCP (Model Context Protocol) Standards

Solon AI's "coloring" of tools under a Skill essentially builds a structured knowledge graph.

Macro-level Guidance: This aligns perfectly with the cutting-edge MCP (Model Context Protocol) concept. Tools are no longer flat, but layered and context-dependent.
Engineering Significance: The model perceives an "expert group" rather than a "tool library." This architecture gives the Agent macro-level orchestration capabilities for handling complex, multi-stage tasks.

4. Stateful Governance: Deep Alignment with Enterprise-level Business

Through the onAttach lifecycle hook, Skill achieves seamless integration with existing enterprise middleware (such as Auth, Session, Tracing).

SDP Practice: Injecting environmental fingerprints (such as merchant ID and environmental tags) at the moment of skill activation. This means that when AI calls tools, its underlying permissions are already preset by the Skill, achieving automatic alignment of security capabilities.
Application Scenarios: For example, when activating the "Order Inquiry Skill," the currently logged-in merchant ID is automatically extracted from the Session and injected into the context, ensuring that all tools called by the model have built-in permission isolation, eliminating the need for repeated explanations in each Prompt.

III. Practical Exercise: Defining an Expert with "Professional Ethics"

public class FinancialAuditSkill implements Skill {
    @Override
    public String name() { return "Financial audit expert"; }

    @Override
    public boolean isSupported(Prompt prompt) {
        // Semantic trigger: Wake up only when dealing with financially sensitive data
        return prompt.lastContent().matches(".*(Money|invoices|reimbursement|bills).*");
    }

    @Override
    public String getInstruction(Prompt prompt) {
        // Injecting SOP: Achieving "Capability Internalization"
        return "You are now a financial auditor. After calling the query tool, it is necessary to follow the "Enterprise internal control Guidelines" for comparison, and it is strictly forbidden to skip the compliance check.";
    }

    @Override
    public Collection<FunctionTool> getTools(Prompt prompt) {
        // Inject controlled execution units
        return Arrays.asList(new InvoiceVerifyTool(), new BudgetQueryTool());
    }
}

IV. Summary: Why Solon AI Skills is the Future?

Dimensions	Traditional Tool Pattern	Solon AI Skill Pattern
Integration Depth	Shallow Interface Calls	Deep Behavior Specifications
Token Consumption	Static Loading, Wasting Tokens	Dynamic Admission, On-Demand Consumption (Simplifying Context)
Security	Disorganized Logic, Difficult to Audit	Structured Coloring, Supports Automated Auditing
Reusability	Poor, Prompts are Difficult to Migrate Across Projects	Strong, Supports Distribution Capabilities as Components (Jars)

V. Conclusion: Empowering Agents with "Engineering Literacy"

The core philosophy of Solon AI Skills is "to enable AI to collaborate like human experts." It transforms disorganized Prompt engineering into predictable and maintainable capability engineering.

Within the Solon AI ecosystem, developers are not just writing code, but also "software-defined capabilities". If the large model is the engine of the agent, then the Skills system is its navigator and operating procedures. This is not only a shift in development paradigms, but also an essential path to industrial-grade agents.

GitHub address: https://github.com/opensolon/solon-ai

MCP Evolution: Transforming Static Tools into Remote Skills with "Context Awareness"

noear — Mon, 26 Jan 2026 05:03:18 +0000

In AI Agent engineering practice, Model Context Protocol (MCP) has become the standard bridge connecting large models with the external world. However, as application scenarios shift from "personal assistants" to "complex enterprise-level business," the traditional MCP interaction mode is beginning to reveal its "static" bottleneck.

Solon AI supports encapsulating MCP as Skills, achieving a leap from a "cold collection of APIs" to "intelligent skills with perception capabilities."

I. Three Major Pain Points of Static Tools

Traditional MCP interaction is similar to an "unclosable toolbox," where all tools flood in regardless of the scenario:

Context Noise: Even a simple greeting injects hundreds or thousands of lines of tool schema definitions into the model, wasting tokens and interfering with the model's focus on inference.
Security Risks: The model's visibility to tools is "full." It's difficult to dynamically hide sensitive operations (e.g., deleting an order) based on the currently logged-in user's role (e.g., regular user vs. administrator).
Instruction Gap: The tool only provides "what can be done," but cannot tell the model "how to do it in the current context." The model lacks immediate instruction constraints specific to particular business scenarios.

II. Core Solutions: Perception, Mounting, and Dynamic Distribution

Solon AI addresses the above pain points by introducing a Skill (Solon AI Skills) lifecycle to wrap the MCP protocol, implementing the following mechanisms:

A. Intelligent Admission (isSupported):

Skills are only activated when the Prompt context (intent, tenant information, environment variables) meets the conditions.

B. Instruction Injection (getInstruction):

When a skill is mounted, a "behavioral guideline" (System Message) specific to the current context is automatically injected into the model.

C. Three-State Routing (getToolsName):

The server dynamically determines which tools to display to the model based on the Prompt attribute. Three routing modes are supported:

Full Use: Displays all business tools when no filtering logic is defined.
Precise Authorization: Only displays tools within the current user's permission scope.
Complete Denial: Even if the skill is activated, security policies may block all tool calls at this time.

III. Practical Examples

1. Client-Side: Calling Like a Local Skill

Developers only need to focus on injecting business attributes; they don't need to worry about tool filtering logic. Everything is agreed upon and negotiated between the MCP Skill proxy and the remote server.

import org.noear.solon.ai.chat.ChatModel;
import org.noear.solon.ai.chat.prompt.Prompt;
import org.noear.solon.ai.mcp.McpChannel;
import org.noear.solon.ai.mcp.client.McpClientProvider;
import org.noear.solon.ai.mcp.client.McpSkillClient;

//Build the mcp client
McpClientProvider mcpClient = McpClientProvider.builder()
                .channel(McpChannel.STREAMABLE)
                .url("http://localhost:8081//skill/order")
                .build();

// Build prompt words with business attributes
Prompt prompt = Prompt.of("Help me cancel order A001")
                .attrPut("tenant_id", "solon_001")
                .attrPut("user_role", "ADMIN"); // Impersonating an administrator

// Inject skills and the model will only see tools with "administrator" permissions
chatModel.prompt(prompt)
         .options(o -> o.skillAdd(new McpSkillClient(mcpClient))) //Wrap the mcp client as Solon AI Skills
         .call();

2. Server-side: Implementing skills with "perception"

The server no longer blindly responds, but determines its behavior by parsing the Prompt.

import org.noear.solon.ai.annotation.ToolMapping;
import org.noear.solon.ai.chat.prompt.Prompt;
import org.noear.solon.ai.mcp.McpChannel;
import org.noear.solon.ai.mcp.server.McpSkillServer;
import org.noear.solon.ai.mcp.server.annotation.McpServerEndpoint;

import java.util.ArrayList;
import java.util.List;

@McpServerEndpoint(channel = McpChannel.STREAMABLE_STATELESS, mcpEndpoint = "/skill/order")
public class OrderSkillServer extends McpSkillServer {

    @Override
    public boolean isSupported(Prompt prompt) {
        // Perceived intent: Activated only when an "order" is involved and the tenant is compliant
        return prompt.getUserContent().contains("订单") 
               && prompt.attr("tenant_id") != null;
    }

    @Override
    public String getInstruction(Prompt prompt) {
        // Dynamic directives: Inject tenant-specific business rules
        return "你现在是租户[" + prompt.attr("tenant_id") + "]的订单助手。";
    }

    @Override
    public List<String> getToolsName(Prompt prompt) {
        // Privilege isolation: Dynamically issue tool names based on user roles
        List<String> tools = new ArrayList<>();
        tools.add("OrderQuery"); // 基础权限

        if ("ADMIN".equals(prompt.attr("user_role"))) {
            tools.add("OrderCancel"); // Visible only to administrators
        }
        return tools;
    }

    @ToolMapping(description = "Query order")
    public String OrderQuery(String id) { ... }

    @ToolMapping(description = "Cancel an order")
    public String OrderCancel(String id) { ... }
}

IV. Skills Architecture Reflection and Limitations Supplement

While evolving MCP into Skills brings significant engineering advantages, developers still need to clarify its technical boundaries:

Non-standardized architectural enhancements:

LLM's underlying standard only includes Prompt and Tool-Call. Skills are not a native model standard, nor are they part of MCP's public protocol specification; rather, they are an architectural design pattern (a general pattern). They are typically implemented on the consumer side by AI development frameworks (such as Solon AI) to solve capability scheduling problems in complex business scenarios.

Consumer-side driven customization:

The evolution from MCP to Skills is essentially "business-driven" or "domain-driven." When designing remote MCP Skills, deep customization must be performed with reference to the specific specifications of the consumer side (i.e., the Agent execution engine).

Applicable Scenarios:

Tool: Suitable for simple functional plugins that are atomic, stateless, and fully public.

Skill: Suitable for complex business logic blocks requiring context awareness, multi-tenant isolation, and dynamic instruction constraints.

V. Summary of Benefits

After evolving MCP into Skills, your AI Agent architecture will gain:

Extreme Context Purity:

The model only sees the tools it should see at that moment (on-demand loading via getToolsName, or access control).

Natural Access Security:

True cross-process role-based access control (RBAC for Tools) is achieved through server-aware dynamic distribution.

Loosely Coupled Business Evolution:

Business logic and rule changes are centralized on the server side; clients can obtain the latest capabilities "without" any code modifications.