The Pivot of Agent Orchestration
Open-source Java Agent Engine for JDK 8+ · Spring Boot SPI · ReAct Loop · 8 Pluggable Slots
灵枢(líng shū,意为"针灸的关键枢轴")是 LingShu 引擎的核心仓库 —— 一个为 JDK 8+ 企业 Java 栈设计的、生产级 ReAct Loop Agent Engine。
名字的由来:Agent 的本质是一个循环(ReAct),而循环需要一个枢轴才能转得稳。 我们把这个"枢轴"叫做 LingShu。
🟢 We're an Engine, not an OS. OryxOS 等项目定位是"Distributed Agent OS"——单 JAR 部署、跨节点协调、Java 21 + virtual threads。 LingShu 不跟他们抢这条赛道:LingShu 是一个嵌进你 Spring Boot 进程的 Engine, 不需要为 Agent 单独搭集群、不需要把 JDK 升到 21、不需要新运维模型。 如果你的团队还在 JDK 8 LTS 上、并且你的服务已经跑在 Spring Boot 里 —— LingShu 是默认选项。
- 🚀 JDK 8 优先 — 不用
var/ sealed / records /List.of/ pattern-switch,主流 JDK 8 LTS 系统直接跑 - 🧩 8 个 SPI 槽位 — PromptBuilder / LlmProvider / ToolExecutor / PermissionPolicy / RuntimeSandbox / SessionStore / Compactor / FlowEngine —— 全部一行 SPI 替换
- 🔁 ReAct Loop 一等公民 — 默认
LinearTurnEngine,显式 step 计数 + ReasoningStarted / ObservationAppended / MaxStepsExceeded 三类事件 - 🔌 MCP 客户端内置 — 通过
McpToolAdapter把任意 MCP server 当 Tool 源 - 📜 Skill = Tool 标记接口 —
SKILL.md解析 → 自动注册为 Tool,classpath + 目录双源 - 🛡️ 双层沙箱 —
PermissionPolicy(模型层)+RuntimeSandbox(系统层,chroot/seccomp/sysbox) - 🔄 FlowEngine 可替换 —
LinearTurnEngine默认,GoogleAdkFlowEngine/AlibabaGraphFlowEngine/ 自研 DAG 可平替 - 🪶 Lombok 友好 —
@Value不可变风格,拒绝过度抽象 - 🌐 A2A-ready (roadmap) — Agent-to-Agent 协议对齐 v0.5,跟 OryxOS 的"三件套"对齐
<dependency>
<groupId>ai.lingshu</groupId>
<artifactId>lingshu-core</artifactId>
<version>0.1.0-alpha</version>
</dependency>import ai.lingshu.core.*;
import ai.lingshu.core.engine.*;
import ai.lingshu.core.provider.anthropic.*;
@SpringBootApplication
public class MyFirstAgent {
public static void main(String[] args) {
SpringApplication.run(MyFirstAgent.class, args);
}
@Bean
CommandLineRunner run(AgentFactory factory) {
return args -> {
Agent agent = factory.create(AgentConfig.builder()
.flowEngine("linear")
.llm(LlmConfig.builder()
.provider("anthropic")
.model("claude-sonnet-4-5")
.build())
.skills(SkillSources.of(
ClasspathSource.of("classpath:skills/agent-builtin/"),
DirectorySource.of("./skills/")
))
.build());
RunResult r = agent.runBlocking("用 Java 写一个 Fibonacci 函数");
System.out.println(r.getFinalText());
};
}
}agent:
flow-engine: linear # linear | google-adk | alibaba-graph | dag
llm:
provider: anthropic # anthropic | openai | gemini | ollama
model: claude-sonnet-4-5
api-key: ${ANTHROPIC_API_KEY}
sandbox:
policy: strict # strict | permissive
runtime: chroot # chroot | sysbox | seccomp | none
max-steps: 25
skills:
sources:
- { type: classpath, location: classpath:skills/agent-builtin/ }
- { type: directory, location: ./skills/ }
- { type: git, location: https://github.com/lingshu-ai-agent/lingshu-skill-market } ┌──────────────────────────────────┐
│ FlowEngine (SPI) │
│ LinearTurnEngine | Google ADK | … │
└─────────┬──────────────┬───────────┘
│ drives │ emits events
┌─────────────────────────▼────┐ ┌───────▼───────────┐
│ PromptBuilder (SPI) │ │ AgentEvent bus │
│ LlmProvider (SPI) │ │ (Reactive Streams)│
└──────────────────────────────┘ └─────────────────────┘
│
┌───────────────────────────▼──────────────────────┐
│ Tool / Skill Pool │
│ Tool SPI → McpToolAdapter → SkillTool adapter │
│ Spring AI @AgentTool annotation → SkillTool │
└────────────┬───────────────────┬──────────────────┘
│ permission │ runtime
┌──────▼─────────┐ ┌──────▼──────────┐
│ PermissionPolicy│ │ RuntimeSandbox │
│ (SPI, model) │ │ (SPI, system) │
└────────────────┘ └─────────────────┘
┌────────────────────────────────────────────────────┐
│ SessionStore (SPI) + Compactor (SPI) │
│ 持久化历史 / 滑动窗口 / 摘要压缩 │
└────────────────────────────────────────────────────┘
// 1. 替换 FlowEngine:接入 Google ADK
@AutoService(FlowEngineProvider.class)
public class GoogleAdkFlowEngineProvider implements FlowEngineProvider {
@Override public String name() { return "google-adk"; }
@Override public int priority() { return 100; }
@Override public FlowEngine create(EngineContext ctx) { return new GoogleAdkFlowEngine(ctx); }
}
// 2. 替换 LlmProvider:接入 OpenAI
@AutoService(LlmProviderFactory.class)
public class OpenAiLlmFactory implements LlmProviderFactory {
@Override public String name() { return "openai"; }
@Override public LlmProvider create(LlmConfig cfg) { return new OpenAiLlmProvider(cfg); }
}
// 3. 加自定义 Tool
@AgentTool(name = "db_query", description = "Execute read-only SQL")
public List<Map<String, Object>> dbQuery(String sql) {
// 你的实现
}只要把以上类打进 jar,放到 classpath,引擎自动加载,零配置。
lingshu/
├── lingshu-core/ ← 核心 API + ReAct 引擎
│ ├── engine/ ← LinearTurnEngine
│ ├── loop/ ← ReAct step state machine
│ ├── prompt/ ← PromptBuilder
│ ├── llm/ ← LlmProvider SPI
│ ├── tool/ ← Tool SPI + McpToolAdapter
│ ├── skill/ ← Skill SPI + SkillTool adapter
│ ├── sandbox/ ← PermissionPolicy + RuntimeSandbox
│ ├── session/ ← SessionStore + Compactor
│ ├── event/ ← AgentEvent types
│ └── flow/ ← FlowEngine SPI
├── lingshu-boot-starter/ ← Spring Boot 启动器
├── lingshu-providers/
│ ├── lingshu-anthropic/ ← Anthropic Claude
│ ├── lingshu-openai/ ← OpenAI / GPT
│ ├── lingshu-ollama/ ← 本地 Ollama
│ └── lingshu-mcp-client/ ← MCP server 适配
├── lingshu-adapters/
│ ├── lingshu-google-adk/ ← 接入 Google ADK 作为 FlowEngine
│ └── lingshu-alibaba-graph/ ← 接入 Alibaba Graph 作为 FlowEngine
└── lingshu-bom/ ← Maven BOM
git clone https://github.com/lingshu-ai-agent/lingshu.git
cd lingshu
mvn -pl lingshu-examples/demo-fibonacci -am exec:java \
-Dexec.mainClass=ai.lingshu.examples.fibonacci.DemoFibonacciApp看到 Final: public static long fib(int n) {...} 即成功。
完整文档见 lingshu-ai-agent/lingshu-docs:
- 📘 30s 入门
- 🧠 ReAct Loop 概念
- 🔌 SPI 扩展指南
- 🛡️ Sandbox 与安全
- 🏭 生产部署
设计文档:dsh_agent_design.md(v1.5.3)
- 🐛 提交 Issue
- 💡 提特性建议
- 🔧 Pull Request 流程
- 🛡️ 安全漏洞上报
Apache 2.0 — see LICENSE.
Built with 🪷 by the LingShu community · Apache 2.0 · JDK 8+