Scar's Blog

MySQL Server MCP 真好用

Sat, 07 Mar 2026 15:36:47 +0800

MySQL Server MCP 真好用

TRAE 的 spec 模式

Sat, 07 Mar 2026 15:29:40 +0800

用 spec 模式，附带详细的接口说明（任务交接文档），能显著提升 AI IDE 的长程任务能力。

现在 TRAE 支持根据 Task 自动创建 Sub Coding Agent 了，总体来说还是比较好用的，偶尔会出现子任务卡死的情况。

/spec 请采用 Java 开发最佳实践，完成这个任务 d:\rightnow-core\docs\rightnow-core-接口设计交接文档.md d:\rightnow-core\docs\rightnow-core-后端接口开发指南.md

Agent Framework Philosophy: The Unbitter Lesson

Sat, 07 Feb 2026 21:22:03 +0800

Agent Framework Philosophy: The Unbitter Lesson

1. Introduction: The Burden of Abstraction

The history of software is a history of abstraction. We build layers to hide complexity, creating frameworks, patterns, and objects that promise to make our lives easier. Yet, in the nascent field of agentic AI, this instinct has led us astray. Early attempts at agent frameworks are replete with complex class hierarchies, managers for every conceivable concept (Memory, Task, Tool), and intricate state machines. They are monuments to premature abstraction.

As Gregor Zunic (Cofounder & CEO of Browser Use) puts it, these frameworks fight the very nature of the intelligence they seek to orchestrate [1]. They fail not because the underlying Large Language Models (LLMs) are weak, but because their rigid structures impose a human-centric view of reasoning onto a non-human intelligence. They encode assumptions that are immediately invalidated by the next model breakthrough.

This document outlines a different philosophy, one derived from first principles and validated by the hard-won lessons of industry pioneers like Anthropic, Manus, and OpenAI [2][3][4]. It is a philosophy of radical simplicity, where we seek not to build an agent, but to unleash one.

2. The First Principle: An Agent is a Loop

If we strip away all the noise, what is an agent? It is a process that perceives, thinks, and acts, in a cycle, to achieve a goal. In the context of LLMs, this translates to an almost trivial implementation:

An agent is just a for-loop of messages. The only state an agent should have is: keep going until the model stops calling tools. You don’t need an agent framework. You don’t need anything else. It’s just a for-loop of tool calls. [1]

This loop is the universal constant of agentic systems. It is the engine. Everything else is just fuel and scenery.

# The irreducible core of an agent
while True:
    response = llm.invoke(context, tools)
    if not response.tool_calls:
        break
    for tool_call in response.tool_calls:
        result = execute(tool_call)
        context.append(result)

Our entire architectural philosophy is built upon the foundation of protecting and empowering this simple loop. We must resist the urge to complicate it.

flowchart TD
    Sandbox -->|provide| Context
    Context --> Agent
    Agent -->|act| Tool
    Tool -->|feedback| Agent
    Agent <-->|handoff by Sandbox| Agent-2

3. The Three Pillars of Simplicity

Our design is guided by three core tenets that emerge from observing what works in practice.

Pillar I: The Sandbox is the World

Instead of creating a multitude of objects to represent the agent’s world (Project, Task, Memory, Files), we unify them into a single, holistic concept: the Sandbox. The Sandbox is an isolated execution environment, typically a virtual machine or container, complete with a file system and the ability to run processes.

This is the most profound simplification. The Sandbox is the state.

Memory is the File System: An agent’s memory is not an abstract class; it is the collection of files within its sandbox. This provides an unlimited, persistent, and directly operable memory that the agent can structure and manage itself, a technique proven effective by Manus [3]. The agent learns to write notes, create logs, and manage data just as a human would.
Context is the Sandbox’s History: The context passed to the LLM is simply the append-only log of what has happened inside the sandbox—a stream of actions and observations.
Projects and Tasks are Implicit: A project is not a database entity; it is a directory in the sandbox. A task is not an object to be managed; it is the initial prompt that kicks off the agent loop.

By unifying the agent’s world into the sandbox, we eliminate dozens of unnecessary classes and the complex interactions between them. The agent interacts with its world not through abstract methods, but through concrete tools like shell and file.

Pillar II: An Agent is a Configuration, Not a Class

Traditional frameworks encourage a deep inheritance model: BaseAgent gives rise to ConcreteAgent, which is then subclassed into SoftwareAgent, ResearchAgent, and so on. This is a fallacy. It conflates an agent’s identity and capabilities with its implementation.

In our philosophy, an Agent is merely a configuration. It is a plain-text or JSON object that defines two things:

Instructions: The system prompt that tells the LLM its role, personality, and objectives.
Tools: A list of capabilities it is allowed to use.

The AgentRunner—the engine that executes the core loop—is stateless. On each iteration, it loads the current agent’s configuration, invokes the LLM, and executes the resulting tool calls. An agent is not an object; it is a mode of operation for the runner.

This approach has powerful implications:

Simplicity: There is no Agent class to maintain. Adding a new agent is as simple as writing a new configuration file.
Flexibility: Agents can be composed, modified, and switched dynamically. Multi-agent collaboration becomes trivial: it is simply one agent using a handoff tool to tell the runner to load a different agent’s configuration on the next loop iteration [4].
Transparency: The agent’s entire
definition is explicit and human-readable, making it easy to debug and understand.

Pillar III: Start with Maximum Capability, Then Restrict

Many frameworks begin by offering a small, “safe” set of tools, forcing the developer to add capabilities one by one. This leads to what has been termed the “incomplete action space” problem [1]. The agent is limited not by the model’s intelligence, but by the developer’s foresight.

We invert this. We start from the assumption that the agent should be able to do anything a human can do within the sandbox. We provide powerful, general-purpose tools from the outset: shell, file, browser. The agent has maximal freedom.

Restrictions are then applied as a layer of safety and guidance, not as a foundational constraint. This is the principle of “Mask, Don’t Remove” articulated by Manus [3]. We don’t take tools away; we temporarily make them unavailable based on the agent’s current state or task, guiding the LLM’s attention without crippling its potential. This ensures the action space remains complete and the KV-cache remains intact, preserving performance and adaptability.

4. Conclusion: The Unbitter Lesson

The bitter lesson of AI research is that general methods that leverage computation ultimately outperform systems based on hand-crafted human knowledge. Agent frameworks are at risk of repeating this mistake by encoding too many assumptions into their design.

By embracing radical simplicity, we learn the unbitter lesson: the most powerful agent framework is the one that gets out of the way. It is a minimal, stateless loop engine operating within a unified sandbox. It treats agents as simple configurations and trusts the LLM to be the intelligent, reasoning core.

This philosophy is not about building less; it is about building right. It is about creating a foundation that is not brittle but resilient, not complex but elegant, and that scales not in spite of, but because of, the relentless advance of AI.

References

[1] Zunic, G. (2026, January 16). The Bitter Lesson of Agent Frameworks. Browser Use Blog. Retrieved from https://browser-use.com/posts/bitter-lesson-agent-frameworks

[2] Schluntz, E., & Zhang, B. (2024, December 19). Building effective agents. Anthropic. Retrieved from https://www.anthropic.com/research/building-effective-agents

[3] Ji, Y. (2025, July 18). Context Engineering for AI Agents: Lessons from Building Manus. Manus Blog. Retrieved from https://manus.im/blog/Context-Engineering-for-AI-Agents-Lessons-from-Building-Manus

[4] OpenAI. (2024). Orchestrating Agents: Routines and Handoffs. OpenAI Cookbook. Retrieved from https://developers.openai.com/cookbook/examples/orchestrating_agents/

Spring AI Extractor 提取器（结构化输出）

Fri, 16 May 2025 13:52:23 +0800

Spring 官方的叫法是结构化输出，不过我更喜欢沿用 LangChain 的叫法“提取器（Extractor）”。

官方文档（Structured Output Converter）

https://docs.spring.io/spring-ai/reference/1.0/api/structured-output-converter.html

package net.heimeng.web.test;

import lombok.Data;
import lombok.extern.slf4j.Slf4j;
import net.heimeng.common.ai.extractor.ExtractorUtils;
import net.heimeng.web.Agent4jWebApplication;
import org.junit.jupiter.api.Assertions;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
import org.springframework.ai.chat.client.ChatClient;
import org.springframework.ai.chat.model.ChatModel;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.beans.factory.annotation.Qualifier;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.core.ParameterizedTypeReference;

import java.util.List;

@Slf4j
@SpringBootTest(classes = Agent4jWebApplication.class)
@DisplayName("AI 单元测试")
public class AiUnitTest {

    @Autowired
    private ChatModel model;

    @DisplayName("AI 配置项测试")
    @Test
    void propertiesTest() {
        // Given
        ChatClient client = ChatClient.builder(model).build();

        // Ensure the client is able to use
        log.debug(client.prompt().user("你好").call().content());

        // Result: 你好👋！我是人工智能助手智谱清言，可以叫我小智🤖，很高兴见到你，欢迎问我任何问题。
    }

    @DisplayName("Extractor 提取器测试")
    @Test
    void extractorTest() {
        // Given
        String textAboutPersons = "蔡徐坤（KUN），1998年8月2日出生于浙江省温州市，" +
                "户籍湖南省吉首市，中国内地男歌手、演员、原创音乐制作人、MV导演。" +
                "朱明春的长子朱立科浙农大毕业三年后，针对温州风俗——家逢喜事分红蛋的习惯，研发出了一鸣利市红蛋，" +
                "深受广大市民的喜爱，成为温州市民办喜事的必需品。之后，朱立科倡导的新型奶吧，" +
                "改变了部分温州人糯米饭加紫菜汤的早餐习惯。该模式一经推出大受温州人欢迎。" +
                "2002年在市区横渎开出第一家一鸣真鲜奶吧直营店，如今，一鸣真鲜奶吧直营店、加盟连锁店在温州地区已发展至近400家。";

        String textAboutActors = "Generate the filmography of 5 movies for Tom Hanks and Bill Murray.";

        List<Person> persons = ExtractorUtils.extract(textAboutPersons, new ParameterizedTypeReference<>() {});
        log.debug(String.valueOf(persons));
        Assertions.assertNotNull(persons);

        Person person = ExtractorUtils.extract(textAboutPersons, Person.class);
        log.debug(person.toString());
        Assertions.assertNotNull(person);

        record ActorFilms(String actor, List<String> movies) {}
        List<ActorFilms> actorFilms = ExtractorUtils.extract(textAboutActors, new ParameterizedTypeReference<>() {});
        log.debug(actorFilms.toString());
        Assertions.assertNotNull(actorFilms);
    }

    @Data
    private static class Person {
        // 私有属性
        private String name;
        private int age;
        private String address;
        private List<String> occupations;
    }
}

package net.heimeng.common.ai.extractor;

import net.heimeng.common.ai.model.WithDescription;
import net.heimeng.common.core.util.SpringUtils;
import org.springframework.ai.chat.client.ChatClient;
import org.springframework.core.ParameterizedTypeReference;

import java.lang.reflect.InvocationTargetException;
import java.util.Map;

/**
 * 提取器工具类
 *
 * @author InwardFlow
 */
public class ExtractorUtils {

    private static final ChatClient CLIENT = SpringUtils.getBean(ChatClient.class);
    public static <T extends WithDescription> T extractWithDescription(String text, Class<T> clazz) {
        try {
            T instance = clazz.getDeclaredConstructor().newInstance();
            return CLIENT.prompt()
                    .user(u -> u.text("""
                                    Extract information from:
                                     {text}
                                     ---
                                     Here is the description:
                                     {description}
                                """)
                            .params(Map.of("text", text, "description", instance.getDescription())))
                    .call()
                    .entity(new ParameterizedTypeReference<>() {});
        } catch (InstantiationException | IllegalAccessException | InvocationTargetException | NoSuchMethodException e) {
            throw new RuntimeException("Unable to create an instance of " + clazz.getName(), e);
        }
    }

    public static <T> T extract(String text, Class<T> clazz) {
        String className = clazz.getSimpleName();
        return CLIENT.prompt()
                .user(u -> u.text("""
                                    Extract information about {className} from {text}
                                """)
                        .params(Map.of("className", className, "text", text)))
                .call()
                .entity(clazz);
    }

    public static <T> T extract(String text, ParameterizedTypeReference<T> typeReference) {
        return CLIENT.prompt()
                .user(u -> u.text("Extract information from: " + text))
                .call()
                .entity(typeReference);
    }

}

Ubuntu 安装 Genius 数学工具

Fri, 25 Apr 2025 08:49:59 +0800

https://www.jirka.org/genius.html

Genius 是一个通用目的的计算器程序。它既可以用作简单的计算器，也可以用作研究或教育工具。语法非常直观，旨在模仿通常的数学书写方式。

GEL 是它的扩展语言名称，它代表 Genius 扩展语言，真聪明，不是吗？事实上，许多标准的 genius 函数本身就是用 GEL 编写的。

使用 cat /etc/issue 可以查看版本号

1. 确保系统已启用 `universe` 仓库

Ubuntu 22.04+ 后，universe 仓库默认已启用。若确认未启用（或旧版本升级后），执行：

apt update  # 刷新软件源
apt install genius -y

2. 旧版本看这里

# apt update && sudo apt install software-properties-common
add-apt-repository universe
apt update
apt install genius

维吉尼亚 Vigenère 密码

Thu, 24 Apr 2025 18:44:12 +0800

工作原理

本质上，Vigenère 密码是几个凯撒密码，其移位值取决于密钥。它可以通过使用Vigenère 表格简单地手动计算。在代码中，可以使用模算术来实现。

编码
编码时，我们首先将每个字母转换为0到25之间的数字，其中A是0，Z是25。如果密钥比消息短，就将其重复直到它们长度相同，例如，如果消息是cryptography，密钥是secretkey：

msg = cryptography
key = secretkeysec
输出O的第i个字符可以使用以下公式从消息M和密钥K计算得出：

O[i] = (M[i] + K[i]) mod 26
解码
将输出O解码为消息M，已知密钥K，同样简单：

M[i] = (O[i] - K[i]) mod 26

准确率、精确率、召回率

Thu, 17 Apr 2025 10:23:57 +0800

准确率是指分类正确的样本数占总样本数的比例。

精确率是针对预测结果而言的，表示预测为正例的样本中有多少是真正的正例。

召回率是针对原来的样本而言的，表示样本中的正例有多少被预测正确了。

总体准确率(overall accuracy)、平均准确率(average accuracy) 是什么

Mon, 03 Mar 2025 14:43:37 +0800

除了视觉对比外，表四还提供了各种方法在图像上的定量结果，其中采用了三个指标，即总体准确率（OA）、平均准确率（AA）和卡帕系数，以评估分类性能。表四中报告的所有分类准确率值均为十次实验的平均结果。

总体准确率（Overall Accuracy, OA）

定义：总体准确率是最直观的分类性能评估指标，它表示所有被正确分类的样本数占总样本数的比例。
计算公式 ：\text{OA}=\frac{\text{正确分类的样本数}}{\text{总样本数}}
举例：假设有一个图像分类任务，总共有 100 个样本，其中 70 个样本被正确分类，那么总体准确率 OA = 70/100 = 0.7，即 70%。
优点：计算简单，易于理解，能够直接反映分类模型在整体样本上的正确分类程度。
缺点：当各类样本数量不平衡时，总体准确率可能会产生误导。例如，如果一个数据集中有 99% 的样本属于类别 A，1% 的样本属于类别 B，一个简单的 “懒惰” 分类器将所有样本都预测为类别 A，就可以得到 99% 的总体准确率，但实际上它对类别 B 的识别能力为 0。

平均准确率（Average Accuracy, AA）

定义：平均准确率是对每个类别分别计算准确率，然后取这些准确率的平均值。它考虑了每个类别的分类准确情况，能够更好地反映分类模型对各个类别的分类性能。
计算公式 ：假设共有 n 个类别，每个类别 i 的准确率为 \text{Accuracy}_i，则平均准确率 AA 为：\text{AA}=\frac{1}{n}\sum_{i=1}^{n}\text{Accuracy}_i
举例：在一个三分类问题中，类别 A、B、C 的样本数量分别为 50、60、40。分类模型对类别 A 的准确率为 0.8，类别 B 的准确率为 0.7，类别 C 的准确率为 0.9。那么平均准确率 AA = (0.8 + 0.7 + 0.9)/3 ≈ 0.8。
优点：相比总体准确率，它在一定程度上能够更好地应对类别不平衡的问题，不会因为某个或某些类别样本数量多而掩盖其他类别分类性能差的情况。
缺点：计算相对复杂一些，而且如果某些类别的样本数量极少，其准确率的计算可能会受到偶然因素的影响较大，从而影响平均准确率的稳定性。

卡帕系数（Kappa Coefficient）

定义：卡帕系数是一种考虑了随机分类因素的分类性能评估指标，它能够更准确地反映分类模型的实际分类能力，避免了因数据分布不平衡而导致的分类性能高估或低估的情况。
计算公式 ：卡帕系数的计算公式为：\kappa =\frac{\text{OA}-\text{PE}}{1-\text{PE}}，其中，PE 为随机分类的期望准确率，计算公式为：\text{PE}=\sum_{i=1}^{n}\left(p_{i+}p_{+i}\right)，p_{i+} 表示第 i 类样本在总体中的比例，p_{+i} 表示第 i 类样本被预测为该类的比例。
举例：假设有一个二分类问题，类别 A 和类别 B 的样本数量分别为 60 和 40。分类模型的预测结果如下表所示：

	类别 A	类别 B	总计
类别 A	40	10	50
类别 B	10	30	40
总计	50	40	90

则 OA = (40 + 30)/90 ≈ 0.778，PE = (50/90)×(50/90) + (40/90)×(40/90) ≈ 0.494，\kappa =\frac{0.778-0.494}{1-0.494}≈0.564。

优点：卡帕系数考虑了随机分类的影响，能够更准确地反映分类模型的实际分类性能，尤其在类别不平衡的情况下，比总体准确率和平均准确率更具可靠性。
缺点：计算相对复杂，需要知道每个类别的样本数量和预测数量，以及总体样本数量等信息，且其结果的解释可能不如总体准确率和平均准确率直观。

Maven 本地项目依赖跑到在线仓库去找，并提示 revision 版本不存在，pom:${revision} (absent)

Wed, 22 Jan 2025 14:08:50 +0800

解决方案：直接添加一个 maven flatten 插件即可。

然后将这个插件添加到构建部分。

<properties>
    <flatten-maven-plugin.version>1.3.0</flatten-maven-plugin.version>
</properties>

<!-- 统一版本号管理 -->
            <plugin>
                <groupId>org.codehaus.mojo</groupId>
                <artifactId>flatten-maven-plugin</artifactId>
                <version>${flatten-maven-plugin.version}</version>
                <configuration>
                    <updatePomFile>true</updatePomFile>
                    <flattenMode>resolveCiFriendliesOnly</flattenMode>
                </configuration>
                <executions>
                    <execution>
                        <id>flatten</id>
                        <phase>process-resources</phase>
                        <goals>
                            <goal>flatten</goal>
                        </goals>
                    </execution>
                    <execution>
                        <id>flatten.clean</id>
                        <phase>clean</phase>
                        <goals>
                            <goal>clean</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>

未命名

Mon, 30 Dec 2024 08:48:58 +0800

转载自角刀牛Java

我曾七次鄙视自己的灵魂：

第一次，当它本可进取时，却故作谦卑；

第二次，当它在空虚时，用爱欲来填充；

第三次，在困难和容易之间，它选择了容易；

第四次，它犯了错，却借由别人也会犯错来宽慰自己；

第五次，它自由软弱，却把它认为是生命的坚韧；

第六次，当它鄙夷一张丑恶的嘴脸时，却不知那正是自己面具中的一副；

第七次，它侧身于生活的污泥中，虽不甘心，却又畏首畏尾。

Scar's Blog

MySQL Server MCP 真好用

TRAE 的 spec 模式

Agent Framework Philosophy: The Unbitter Lesson

Agent Framework Philosophy: The Unbitter Lesson

1. Introduction: The Burden of Abstraction

2. The First Principle: An Agent is a Loop

3. The Three Pillars of Simplicity

Pillar I: The Sandbox is the World

Pillar II: An Agent is a Configuration, Not a Class

Pillar III: Start with Maximum Capability, Then Restrict

4. Conclusion: The Unbitter Lesson

References

Spring AI Extractor 提取器（结构化输出）

Ubuntu 安装 Genius 数学工具

1. 确保系统已启用 universe 仓库

2. 旧版本看这里

维吉尼亚 Vigenère 密码

准确率、精确率、召回率

总体准确率(overall accuracy)、平均准确率(average accuracy) 是什么

总体准确率（Overall Accuracy, OA）

平均准确率（Average Accuracy, AA）

卡帕系数（Kappa Coefficient）

Maven 本地项目依赖跑到在线仓库去找，并提示 revision 版本不存在，pom:${revision} (absent)

未命名

1. 确保系统已启用 `universe` 仓库