lingshu-cli · 灵枢命令行

Terminal-first Agent Runner

一行命令跑起 ReAct Agent · 与 lingshu 引擎同 API · 复用 ~/.lingshu/ 全局配置

---

⚠️ 此仓库已归档(2026-09-04)

lingshu-cli 已并入 lingshu/lingshu-cli/ Maven 模块, 作为核心引擎 lingshu 仓的子模块统一维护,跟随引擎版本号同步发版。

• 🚫 本仓库不再接受新 PR,请到 lingshu/lingshu-cli/ 提交
• 🚫 本仓库不再发版,所有 release 见 lingshu/releases
• ✅ 本仓库保留仅供历史 commit 检索与 star 留存

迁移原因与方案说明见 设计文档 §10.3。

---

为什么需要 CLI

引擎适合 Spring Boot 应用内嵌,但日常调试、写脚本、给非 Java 同事演示**,需要一个零配置的入口** —— lingshu run "..."。

lingshu-cli 提供:

• 🖥️ 终端交互 REPL — lingshu repl,流式打印 Reasoning / Tool call / Observation
• 🚀 单次执行 — lingshu run "用 Java 写 Fibonacci" 拿到 stdout
• 📂 项目级 Skill — ./skills/ 自动加载
• 🔌 stdio 协议 — lingshu serve --stdio 可被 Claude Desktop / Cursor / VS Code 之类的 MCP Host 调用
• 🌍 全局配置 — ~/.lingshu/config.yaml 一次配置多项目复用

---

📦 安装

Homebrew(macOS / Linux)

brew install lingshu-ai-agent/tap/lingshu

SDKMAN(JDK 用户)

sdk install lingshu

直接下载二进制

Releases 提供:

• lingshu-cli-macos-arm64.tar.gz
• lingshu-cli-macos-x64.tar.gz
• lingshu-cli-linux-x64.tar.gz
• lingshu-cli-windows-x64.zip

从源码(需要 JDK 8+)

git clone https://github.com/lingshu-ai-agent/lingshu-cli.git
cd lingshu-cli
mvn package -DskipTests
tar -xzf target/lingshu-cli-*.tar.gz
export PATH=$PWD/lingshu-cli-*/bin:$PATH

---

⚡ 命令

lingshu run

$ lingshu run "用 Java 写一个并发安全的 LRU 缓存,带单元测试"

[step 1] ReasoningStarted  : 用户要的是并发安全 LRU,我应该先写数据结构
[step 1] Tool call         : file_write(path=src/main/java/LruCache.java, content=...)
[step 1] ObservationAppended: 写入成功
[step 2] ReasoningStarted  : 现在加单元测试
[step 2] Tool call         : file_write(path=src/test/java/LruCacheTest.java, content=...)
[step 2] ObservationAppended: 写入成功
[step 3] ReasoningStarted  : 跑测试
[step 3] Tool call         : shell_exec(cmd=mvn test)
[step 3] ObservationAppended: Tests run: 5, Failures: 0
[step 3] ReasoningFinished : ✅ 完成

Final:
  - src/main/java/LruCache.java
  - src/test/java/LruCacheTest.java
  - 全部测试通过

lingshu repl

$ lingshu repl --config ./lingshu.yaml

🦊 LingShu REPL · type '/exit' to quit
🦊 /skills to list, /reload to reload
🦊 /reset to clear session

you> 帮我看看当前目录有什么文件
[step 1] shell_exec(ls -la) → ...
🦊 done.

you> /skills
📦 Built-in skills:
   - file_read / file_edit / file_write
   - shell_exec / shell_kill
   - web_search / web_fetch
   - http_request

you>

lingshu serve --stdio

启动一个 MCP server,任何兼容 MCP Host 都能连接:

lingshu serve --stdio --port 0

lingshu doctor

诊断当前环境:

$ lingshu doctor

✅ JDK 17.0.10 detected
✅ ~/.lingshu/ writable
✅ Anthropic API key valid
⚠️  MCP config: ~/lingshu-mcp.json not found (optional)
✅ Skills directory: ./skills/ has 3 SKILL.md
✅ Default FlowEngine: linear (LinearTurnEngine v1.5.3)

其他

命令	用途
lingshu skill install <url>	安装远程 SKILL.md
lingshu skill list	列出当前所有 Skill
lingshu skill new <name>	模板化新建一个 Skill
lingshu config init	初始化 ~/.lingshu/config.yaml
lingshu trace <run-id>	打印某次运行的 trace
lingshu version	打印版本

---

🛠️ 配置

全局:~/.lingshu/config.yaml

llm:
  provider: anthropic
  model: claude-sonnet-4-5
  api-key: sk-ant-...

sandbox:
  policy: strict
  runtime: chroot

skills:
  sources:
    - { type: classpath, location: classpath:skills/agent-builtin/ }
    - { type: directory, location: ~/.lingshu/skills/ }

max-steps: 25
stream: true

项目级:./lingshu.yaml

项目级配置会 覆盖 全局配置,字段不变。

环境变量

Var	作用
LINGSHU_LLM_API_KEY	覆盖 LLM API key
LINGSHU_MAX_STEPS	覆盖 max-steps
LINGSHU_LOG	debug / info / warn / error
LINGSHU_NO_COLOR	关闭 ANSI 颜色

---

🎯 设计目标

• 零依赖本地运行 — 二进制单文件,解压即用
• 与 lingshu-core 同步发布 — major.minor.patch 完全对齐
• stdio-first — 可被任何 MCP Host 调起
• CJK 友好 — 默认 UTF-8 + 宽字符对齐,终端不会乱

---

📚 相关

• 核心引擎:lingshu-ai-agent/lingshu
• 设计文档:见主仓库 dsh_agent_design.md
• Skill 市场:lingshu-ai-agent/lingshu-skill-market

---

📜 License

Apache 2.0 — see LICENSE.