# Lingshu

**Repository Path**: vue-node/lingshu

## Basic Information

- **Project Name**: Lingshu
- **Description**: 灵枢 (Lingshu) 是一个轻量级、可扩展的智能体框架，旨在从零复现 OpenClaw 的核心设计，并更加贴合国人使用习惯。我们以学习为目的，通过渐进式开发，逐步实现技能动态加载、函数调用、MCP 协议集成、向量记忆等特性，打造更懂中文用户的开源智能体系统。项目名称取自《黄帝内经》，寓意智慧枢纽。无论你是 AI 初学者还是资深开发者，欢迎加入我们，一起拆解、重构、创新，共同书写属于国人的智能体
- **Primary Language**: TypeScript
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-03-19
- **Last Updated**: 2026-03-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Lingshu

## 🔥 项目倡议：从零复现“小龙虾”——打造属于我们自己的智能体框架

### 缘起：为什么我们要做这件事？

最近，**OpenClaw**（我们亲切地称它为“小龙虾”）在 AI 智能体领域掀起了一阵热潮。它提出的“技能即插即用”、“MCP 协议”、“元数据驱动”等设计理念，让我们看到了智能体框架的未来形态。但当我们沉浸于使用它的强大功能时，是否曾好奇过：**这些酷炫的能力背后，到底是如何实现的？**

我们发起这个开源项目，**不是为了简单地复刻一只“小龙虾”**，而是要以学习者的姿态，深入拆解它的每一根“触须”，理解其设计思想，然后在这个过程中**不断发现可以优化的细节，设计更巧妙的实现方式，甚至拓展出“小龙虾”本身没有的新功能**。我们要让它更接地气，更符合国人的使用习惯，最终成长为一个真正由国内开发者主导的、自主可控的、更加完善的智能体系统。

**与其做一个单纯的用户，不如亲手拆解、重构、创造！** 我们希望通过一步步复现其核心思想，深入理解智能体框架的底层逻辑，同时融入我们自己的思考和创意，让这只智慧的“灵兽”在中华文化的沃土上生根发芽。

### 🎯 项目目标

**打造一个轻量级、可扩展、更懂中文用户的智能体框架雏形，并随着学习不断进化。**  
我们将采用**渐进式开发**策略，从最简单的原型开始，逐步加入函数调用、MCP 协议支持、动态技能加载、向量记忆等特性，最终形成一个功能完备、易于二次开发的智能体基础框架。在这个过程中，我们不仅要做“搬运工”，更要做“设计师”——遇到原设计中不够优雅或不符合国人习惯的地方，我们大胆改进；发现可以创新的机会，我们勇于尝试。

- **核心原则**：代码简洁、模块清晰、文档同步、易于参与、**自主创新**。
- **最终形态**：支持通过自然语言调用本地技能，可连接 MCP 服务器，具备对话记忆和动态技能筛选能力，**并内置对中文语境、国内常见服务（如微信、钉钉、邮件、天气、快递查询、国内云平台等）的友好支持。**
- **学习价值**：覆盖大模型 API 集成、函数调用、进程通信、向量数据库、插件系统等多个技术领域，**并培养我们发现问题、解决问题的能力**。

### 🧰 技术栈规划（灵活可讨论）

- **主语言**：Node.js / TypeScript（便于快速开发和跨平台）
- **大模型接口**：DeepSeek / OpenAI API（函数调用、工具调用），**优先适配国内大模型（如智谱、千问、文心）**
- **技能脚本**：支持多语言（Python、Shell、JS 等），通过子进程调用
- **MCP 协议**：参考 Model Context Protocol 规范，实现客户端，**同时探索更适合国内环境的轻量级替代方案**
- **向量检索**：Chroma / LanceDB 本地嵌入，用于记忆和技能筛选
- **元数据解析**：gray-matter 解析 YAML Front Matter
- **社区协作**：GitHub / Gitee / GitCode 同步，Discord 或微信群交流

### 🗺️ 渐进式开发路线图

我们将项目分为多个里程碑，每个阶段完成一个核心功能，并确保可运行。欢迎任何阶段的参与者！

#### 🚩 阶段一：最简原型（MVP）

**目标**：跑通“用户输入 → 调用大模型 → 解析指令 → 执行本地命令”的基础流程。  

- 实现技能目录扫描
- 解析技能 README.md 中的 YAML 元数据（名称、描述、命令）
- 将技能描述转换为大模型可理解的 tools 格式
- 支持通过子进程执行脚本并返回结果
- 提供命令行交互界面
- **探索点**：如何让技能描述更简洁？如何设计中文友好的参数命名？

#### 🚩 阶段二：函数调用与动态参数

**目标**：支持复杂的参数传递和函数调用规范。  

- 完善技能参数定义（类型、必需、枚举等）
- 实现参数校验与类型转换
- 支持多轮对话中的技能复用
- 添加简单的对话历史管理
- **探索点**：能否让模型自动生成参数校验规则？如何优化中文参数的理解？

#### 🚩 阶段三：MCP 协议集成

**目标**：让框架能够连接任意 MCP 服务器，调用远程工具。  

- 实现 MCP 客户端，支持工具发现和调用
- 将 MCP 工具动态注册为“内置技能”
- 支持混合调用（本地脚本 + MCP 工具）
- **探索点**：MCP 协议在国内的适用性如何？是否需要简化或扩展？

#### 🚩 阶段四：记忆与智能筛选

**目标**：解决长对话和技能数量爆炸的问题。  

- 引入向量数据库，对对话历史进行向量化存储
- 实现基于用户输入的历史片段召回
- 对技能描述进行向量化，动态筛选最相关技能
- 控制 token 消耗，优化上下文
- **探索点**：能否利用国产向量数据库（如 Milvus）？如何提高中文语境下的召回准确率？

#### 🚩 阶段五：技能市场与生态

**目标**：打造可分享的技能生态，特别鼓励开发针对国内用户场景的技能。  

- 设计技能包格式（.claw 或文件夹）
- 实现技能安装、更新、卸载命令
- 建立公共技能仓库（可选），**优先收录处理国内常用服务（如微信机器人、邮件、钉钉通知、天气、快递查询等）的技能**
- 提供技能开发模板和文档
- **探索点**：如何降低非技术用户创建技能的门槛？能否让用户通过自然语言定义技能？

### 🤝 如何参与？

我们欢迎一切形式的贡献：**代码、文档、测试、想法、答疑、宣传**。无论你是 AI 初学者还是资深工程师，都能在这里找到适合自己的位置。

- **项目仓库**（三站同步，任选其一）：
  - GitHub: [https://github.com/vue-node/lingshu](https://github.com/vue-node/lingshu)（待创建）
  - Gitee：[Gitee](https://gitee.com/vue-node/lingshu)
  - Gitcode：[Gitcode](https://gitcode.com/VueNode/lingshu)
- **官网地址**：[lingshu.vuenode.com](https://lingshu.vuenode.com)
- **交流渠道**：
  - 微信群：添加助手微信  拉群（待建）
  - Discord：[邀请链接]（待建）
  - 项目 Issues：任何问题、建议欢迎提交
- **快速开始**：查看仓库中的 `CONTRIBUTING.md` 和 `docs/` 目录

### 📖 项目名称由来（征集意见）

我们暂定项目中文名为 **“灵枢”**（**Lingshu** – A Lightweight Agent Framework Inspired by Chinese Wisdom），取自《黄帝内经》中的《灵枢经》，意为生命的关键枢纽、核心机理。以此命名，寓意本项目是智能体的核心框架，掌管着技能与思维的运转，同时也寄托了我们对中医智慧与现代科技融合的敬意。当然，如果你有更好的想法（例如“天工”、“开物”、“知微”等），欢迎在 Issue 中提出，我们一起投票决定！

### 🧠 写在最后

复现一个优秀框架的过程，本身就是最好的学习。我们将一起面对各种技术挑战：如何让大模型准确理解技能描述？如何设计安全高效的脚本执行机制？如何平衡灵活性与性能？**每一个难题被攻克的过程，都是我们成长的印记。** 而在这个过程中，我们还将留下属于自己的印记——那些改进、优化和创新，最终汇聚成一个真正由我们亲手打造的、富有中华文化底蕴的智能体框架。

如果你也对智能体技术充满好奇，如果你享受从零构建的乐趣，如果你渴望与一群热爱技术的人同行，那么请加入我们！让我们从一行代码开始，共同书写属于我们的“灵枢”故事。

**现在就开始吧！Star & Fork，然后一起动手！** 🚀