Skip to content
BranchesTags

Repository files navigation

Oh My Sage

米家自动化极客版 AI Agent - 用自然语言创建复杂的米家极客版自动化规则

Next.jsTypeScriptVercel AI SDKMCP

Oh My Sage 是一个工具驱动的 AI Agent，通过自然语言对话帮助你创建和管理小米米家自动化极客版规则。

✨ 核心特性

  • 🤖 Agent 循环 - 持续运行的思考-行动循环，非一次性响应
  • 🛠️ 工具驱动 - 所有能力通过工具实现，灵活可扩展
  • 💭 思考可见 - 输出思考过程，让你了解 Agent 在做什么
  • 💡 多方案建议 - 为你提供多种实现方案供选择
  • ✅ 确认后执行 - 重要操作前获取你的确认
  • 🔄 流式输出 - 实时显示处理过程
  • 📐 自动布局 - 规则节点自动排版，清晰展示流程
  • 🔌 MCP 支持 - 通过 Model Context Protocol 集成到 AI 编程助手

🚀 快速开始

两种使用方式，任选其一：

方式适用场景特点
🔌 MCP Server开发场景集成到 AI 编程助手，作为工具直接调用
🌐 Web 界面日常使用浏览器交互，可视化界面

MCP 方式（一行命令安装）

# 克隆、构建并链接到系统 PATH
git clone https://github.com/allocnode/oh-my-sage.git &&cd oh-my-sage && npm install && npm run build:mcp && npm link

配置 MCP Server（在支持 MCP 的 AI 助手中）：

{
"mcpServers": {
"oh-my-sage-mcp": {
"command": ["oh-my-sage-mcp"],
"environment": { "GATEWAY_URL": "http://192.168.0.4" }
}
}
}

然后直接对话使用：

  • "帮我查看米家设备"
  • "创建一个每天晚上8点关闭客厅灯的自动化规则"

⚠️关于 Skill：创建/更新自动化规则需要安装 mijia-automation Skill。安装后 AI 助手会自动激活，无需手动操作。

Web 方式（一行命令启动）

# 克隆并安装
git clone https://github.com/allocnode/oh-my-sage.git &&cd oh-my-sage && npm install
# 配置环境变量
cp .env.example .env
# 编辑 .env 填入 LLM API 和网关地址# 启动
npm run dev

访问 http://localhost:3000 即可使用。

📖 详细文档

🔌 MCP Server（推荐开发场景）

通过 Model Context Protocol 将 oh-my-sage 集成到 AI 编程助手。

完整安装步骤

Step 1: 构建并安装 MCP Server

cd oh-my-sage
npm install
npm run build:mcp
npm link

构建完成后，oh-my-sage-mcp 命令会被链接到系统 PATH。

Step 2: 配置 MCP Server

在 MCP Host 配置文件中添加：

{
"mcpServers": {
"oh-my-sage-mcp": {
"command": ["oh-my-sage-mcp"],
"environment": {
"GATEWAY_URL": "http://192.168.0.4"
}
}
}
}

Step 3: 安装 Skill（创建/更新规则必需）

关于 Skill 的自动激活：

  • 如果涉及到创建规则或更新规则，你需要先安装 mijia-automation Skill
  • 一旦安装了 Skill，AI 助手会在需要时自动激活，无需手动操作
  • 如果你没有安装 Skill，AI 助手会提示你需要先安装

安装方式：

Skill 位于 .agents/skills/mijia-automation/ 目录下：

  • OpenCode: 复制到 ~/.config/opencode/skills/
  • Claude/Cursor: 将 SKILL.md 内容添加到 AGENTS.md 或对话中

Step 4: 连接并使用

在 OpenCode 中直接对话：

  1. 连接网关：

    帮我连接米家网关，登录码是 123456

  2. 查看设备：

    查看我有哪些米家设备

  3. 创建自动化规则：

    帮我创建一个自动化规则：每天晚上8点关闭客厅灯

MCP 工具列表

工具描述
mijia_auth连接米家网关（必须先调用）
mijia_disconnect断开网关连接
mijia_status检查连接状态
mijia_get_devices获取设备列表
mijia_get_device获取设备详情+MIOT Spec能力
mijia_get_graphs获取自动化规则列表
mijia_get_graph获取规则详情
mijia_create_graph创建规则（⚠️需 Skill 支持）
mijia_update_graph更新规则（⚠️更新 nodes 需 Skill）
mijia_delete_graph删除规则
mijia_toggle_graph启用/禁用规则
mijia_validate_graph校验规则完整性
mijia_get_variables获取变量列表
mijia_set_variable设置变量值

⚠️ 关于创建/更新规则：

mijia_create_graph 和 mijia_update_graph 需要 mijia-automation Skill 的支持。

  • 如果已安装 Skill，AI 助手会自动激活，无需手动操作
  • 如果 AI 助手提示需要安装 Skill，请参考上面的 "Step 3" 进行安装

Skill 提供的内容：

  • 完整的节点类型模板（deviceInput, deviceOutput, condition, timeRange, delay 等）
  • 节点连接规则（outputs 格式、state/event 节点区别）
  • 关键校验规则（节点ID格式、inputs/outputs 要求）
  • dtype 映射规则（bool/int/float/string）

🌐 Web 界面（适合日常使用）

适合喜欢浏览器交互的用户，提供可视化界面。

安装步骤

让 AI 帮你安装（推荐）：

如果你在使用 OpenCode、Claude Code、Cursor 等 AI 编程助手，直接告诉它：

帮我安装 oh-my-sage: https://github.com/allocnode/oh-my-sage
我需要：
1. LLM API 地址：https://api.openai.com/v1（或其他 OpenAI 兼容接口）
2. API Key：你的key
3. 模型名称：gpt-4o（或其他模型）
4. 米家网关地址：http://192.168.0.5（改成你的）

手动安装：

# 克隆并安装
git clone https://github.com/allocnode/oh-my-sage.git &&cd oh-my-sage && npm install
# 配置环境变量
cp .env.example .env

编辑 .env 文件：

# OpenAI 兼容接口配置LLM_BASE_URL=https://api.openai.com/v1LLM_API_KEY=your_api_key_hereLLM_MODEL=gpt-4o# 米家网关地址GATEWAY_URL=http://192.168.0.5

启动服务：

npm run dev

访问 http://localhost:3000，输入网关登录码即可使用。

💡 使用示例

MCP 方式示例

用户: 帮我查看米家设备
Agent: 我来帮你查看米家设备。首先连接到网关。
[mijia_auth] passcode: 960622, gateway_url: http://192.168.0.4
→ 连接成功
[mijia_get_devices] → 获取到 82 台设备，包括：
- 小米智能中控屏 (在线)
- 客厅灯 (在线)
- 智能窗帘 (在线)
你的智能家居共有 82 台设备，大部分都在线运行良好！

Web 方式示例

用户: 每天晚上8点关闭客厅灯
Agent: [思考中...] 我来帮你设置这个自动化。
[正在获取设备列表...]
我看到你有这些灯：
- 客厅灯 (在线)
- 卧室灯 (在线)
[正在生成建议方案...]
我为你准备了几个方案：
⭐ 方案1: 简单方案
- 每天 20:00 准时关闭客厅灯
- 优点: 简单直接
方案2: 智能方案 - 每天 20:00，如果灯开着就关闭
- 优点: 避免无效操作
你选择哪个方案？

🤖 支持的模型

支持任何 OpenAI 兼容接口的模型：

服务商Base URL模型示例
OpenAIhttps://api.openai.com/v1gpt-4o
通义千问https://dashscope.aliyuncs.com/compatible-mode/v1qwen-max
DeepSeekhttps://api.deepseek.com/v1deepseek-chat
Kimihttps://api.moonshot.cn/v1moonshot-v1-128k
本地 Ollamahttp://localhost:11434/v1qwen2:72b

📁 项目结构

oh-my-sage/
├── .agents/
│ └── skills/
│ └── mijia-automation/ # 米家自动化 Skill（MCP创建规则必需）
├── src/
│ ├── app/ # Next.js Web 界面
│ ├── components/ # React 组件
│ ├── server/ # Web 后端
│ ├── core/ # Core 库（MCP 和 Web 共用）
│ │ ├── gateway/ # 网关客户端
│ │ ├── tools/ # 工具实现
│ │ └── types/ # 类型定义
│ └── mcp/ # MCP Server
│ ├── index.ts # 入口
│ ├── config.ts # 配置
│ ├── utils.ts # 工具函数
│ └── tools/ # MCP 工具
├── dist/mcp/ # MCP 构建输出
├── ref/ # 参考文档
└── docs/ # 设计文档

📚 参考文档

🔧 Agent Skills

Oh My Sage 支持可扩展的 Agent Skills 系统。

渐进式披露

层级内容Token 成本触发时机
Catalogname + description~50-100/Skill系统初始化
Instructions完整 SKILL.md<5000 tokens自动/手动激活
Resourcesreferences/ 等按需加载read_skill_file

🤝 Contributing

欢迎贡献！请遵循以下步骤：

  1. Fork 本仓库
  2. 创建特性分支 (git checkout -b feature/amazing-feature)
  3. 提交更改 (git commit -m 'Add amazing feature')
  4. 推送到分支 (git push origin feature/amazing-feature)
  5. 开启 Pull Request

📄 License

MIT License - 详见 LICENSE 文件

🙏 致谢

About

🛠️ 米家自动化极客版 AI Agent (SKILL & MCP)- 用自然语言创建复杂自动化规则

Resources

Readme
MIT license
Activity

Stars

76 stars

Watchers

0 watching

Forks

14 forks
Report repository

Releases

Packages

Contributors

Languages