ivo

align="center"> <img src="docs/images/avatar.png" alt="IVO avatar" width="220" /> </p> <h1 align="center">IVO</h1> <p align="center"> 一款与 GitHub Copilot 或免费 Ollama 配合使用的轻量级 Telegram 编程助手。 </p> IVO 将 [GitHub Copilot CLI](https://github.com/features/copilot/cli) 转化为一个个人助理，您可以从 Telegram 使用它。 您发送文本或语音消息，它可以在真实的工作空间中工作：检查代码、编辑文件、运行 shell 命令、使用、调用 MCP 服务器，并通过机器人回复。 您可以在两种模式下运行它： - 搭配 **GitHub Copilot** [免费/订阅](https://github.com/features/copilot/plans) - 搭配 **Ollama**，由于其 [**Copilot 集成**](https://docs.ollama.com/integrations/copilot-cli) 推荐的路径是 Ollama在免费层也是如此。 目标不是构建另一个庞大的。 目标是保持在 CLI 之上的层尽可能于理解和有用。 - 小型核心，易于- 由 GitHub Copilot CLI 在原始工作区模式下提供支持 - 以 Telegram 为首选，支持语音输入- 技能和代理以纯 Markdown 定义 - 每个代理或用户具有持久内存 - 与 GitHub Copilot 或免费 Ollama 模型配合使用 - 推荐使用 作为最简单的免费设置 仓库：<https.com/albertleal/ivo> ## 为什么 IVO 该领域的大多数项目都朝着两个方向发展： - 它们成为具有自己的运行时、编排堆栈、插件系统和抽象的大型框架。 - 它们保持很小，但最终只是一个聊天中继，没有真正的执行能力。 IVO 处于两者之间。 它保持很小，但仍然是一个真正的工作助手，因为繁重的工作留在了 GitHub Copilot CLI 中，它已经提供了、权限、工作区访问、浏览器自动化、MCP 支持和模型集成。 IVO 只添加了 Copilot CLI 已经为您提供的功能： - Telegram 接口 - 语音笔记语回复 - 轻量级内存 - 基于 Markdown 的技能和代理 - 用于通知和集成的小さHTTP API 如果 Copilot CLI 变得更好，IVO 也会自动变得更好。 ## IVO 的功能 从 Telegram，您可以要求它： - 审计存储库以查找秘密、死代码或明显的问题 - 运行测试并解释失败原因 - 重写文档或代码注释 - 检查日志和本地进程 Playwright 通过 Copilot 工具浏览网页 - 调用 MCP 服务器，如浏览器、Firecrawl 或 Home Assistant -杠命令切换模型 - 以文本或语音回复 这是核心思想：真正的代码代理能力，但可以从您的手机访问。 ## IVO 的使用体验 两个快速演示：> <tr> td align="center"50%"> <img src="docs/videos/ivo_flow.gif" alt="IVO Telegram 工作流：选择适配器和模型、说话并获取 width="320" /> 首次使用工作流：选择适配器和模型，与 IVO 交谈 Telegram 获取回复。 </td> <td align="center" width="50%"> <img src="docs/videos/ivo_creates_own" alt="IVO 创建自己的工具：在被要求获取图片 width="320" /><br /> 真实的代理当缺少能力时，IVO 可以在工作区中小工具并在下次使用它。 </td> </tr> </table> 您可以发送的提示示例： - “审核此存储查找明显的秘密并修补 gitignore” - “运行失败的测试，解释根本修复最小的安全问题” - “找到一种方法连接到我的 Home Assistant 网络并关闭厨房灯” IVO 将请求转发给 Copilot CLI，协调工作区代理、技能和 MCP 集成，然后将回复流式返回到 Telegram。 它也可以更广泛的工作区，例如您的主目录，以便它可以跨多个本地文件作为个人代理移动。 ## - 保持核心最小 - 重用 Cop 而不是重建其工具 - 优先使用纯文件而不是自定义系统 - 使移动体验成为一流的 - 保持所有内容易于检查和自定义 ## 功能 - 用于您的编码助手的 Telegram 接口 - Copilot CLI 作为主要引擎 - 使用 Whisper 进行语音输入 - 使用 Kokoro 进行语音- 为具有 Copilot 订阅的用户提供 GitHub Copilot 支持 - 支持本地或云模型的 Ollama，包括免费路径 - 技能和代理存储为 `.github/skills/` 和 `.github/agents/` 文件 - 持久内存存储为简单的 Markdown 文件 用于出站通知和自动化钩子的 HTTP API - 当您将 IVO 指向存储库时，按工作 - 动态斜杠命令用于已发现的模型别名 -堆栈相比，Python 代码库非常小 ## 选择您的后端 ### GitHub Copilot 路径 已经拥有 GitHub Cop订阅，并希望使用原生 工作流，请选项。 ### 免费 Ollama 路径 如果您想支付 Copilot 费用的情况下运行 IVO选项。 推荐Ollama Cloud，即使层也是如此。 这是无需管理大型本地模型即可方式，IVO可以通过相同的 Telegram 接口公开这些## 为什么它不同 IVO 并不试图取代。 它的目标是让 Copilot CLI 在通常地方可用：Telegram和轻量级个人自动化赋予了它不同的形态： | 方法核心引擎 | 主要界面 | 复杂度 | 最适合 | --- | --- | --- | --- | | 单 Copilot CLIilot CLI | 终端 | 经常使用笔记本电脑的用户 | | 典型的机器人 | 自定义器 | Telegram | 低问答聊天 | | 大型代理框架 | 自定义运行时 | 网页、桌面、终端 | 高 | 需要一体化团队 | | IVO | Copilot CLI | Telegram + 语音 | | 想要一个功能助手而无需额外框架重量的人 | 如果您已经使用并信任 Copilot CLI，对其的远程控制，而不是另一个需要维护的堆栈。 ## 快速开始 在开始之前，请选择一个后端： - 如果您已经支付了 GitHub Copilot 费用，请选择 Copilot - 如果您想要免费路径，请选择 Ollama - 如果您想要推荐的免费路径，且设置摩擦最小，请 Cloud ###. 克隆并安装 ```bash git clone https://github.com/albert/ivo.git cd ivo make install 创建虚拟环境，项，搭建本地需要时复制配置文件模板。 ### 2. 创建一个 Telegram 机器人 - 在 Telegram 中打开 BotFather - 创建一个新机器人 复制机器人令牌 向您要授权的 Telegram 账户发送至少一条- 将令牌和 放入 `.env） ###. 配置密钥和设置 编辑 `.env`: ```TELEGRAM_BOT_TOKEN:abc TELEGRAM_CHAT_ID=12345678 ``` 编辑 `config.yaml`： 如果您想ama 和 Copilot 订阅之间进行选择 telegram: ${TELEGRAM_B} admin_chat ${TELEGRAMadapters: : enabled: ollama: enabled: true defaults: : copilot ``` 如果您只想使用免费ama 路径，请切换适配器： ```yamlapters: copilot: enabled: false #关闭 ollama: true defaults: : ollama同样适用于仅限 ```yaml ad copilot: enabled: true ollama: enabled: false #关闭 defaults: adapter: ollama ``` ### 4. 运行它 ```bash make run ``` 或： ```bash python -m ivo config.yaml ``` 或2 监督用于无人值守运行）： ```bash pm ecosystem.config.js save pm2 logs ivo ``` ### 日志 日志使用单个 stderr 处理程序，格式为 `< [logger] LEVEL:。 - 级别：config.yaml` 中的 `logging.level` 控制，可通过 `LOG_LEVEL` 环境变量覆盖（`ERROR`、`WARNING`、`INFO`、`DEBUG`）。pm2 `ecosystem.config.js` 配备了 `LOG_LEVEL=ERROR`，因此稳态输出保持安静 — 切换到 `INFO`/`DEBUG` 和 `pm2 restart --update-env`，当您需要跟踪请求时。 - 嘈杂的库（`httpx`、`httpcore`、`telegram`、`uvicorn.access`）被锁定为 `WARNING`，因此 ivo 自己的记录保持可读。 - 文件（仅限 pm`~/Library/ivo/ivo.{out,err}.log`（macOS），`~/.local/state/ivo/log/...`（其他位置）。轮换由 `pm2-logrotate` 处理： ```bash pm2 install pm2-logrotate pm2 set pm2-logrotate:max_size 10M pm2 set pm2-logrotate:retain 7 pm2 set pm2:compress true ``` ## 先决条件 - Python 3.11+ - 如果使用 Copilot 路径，则需要安装并认证 GitHub Copilot CLI 如果您想要语音转文本，则需要在 `PATH` 上安装 `whisper-cli` - 如果您想要文本转语音，则需要 Kokoro - 如果ama 路径，则需要安装 Ollama 您不想要运行本地模型，则推荐使用 Ollama Cloud 作为免费选项 ## 常见用例 ### 移动编码助手 -离电脑时检查存储库 - 从 Telegram 触发小型修复、审计或文档重写 - 使用斜杠命令快速切换模型 ### 语音驱动的工作流程 - 发送语音笔记而不是输入长提示 -方便输入文本时语回复 ### 个人自动化 - 通过 HTTP API推送到 Telegram 日志、监视机器或运行维护任务 MCP 服务器以实现家庭自动化和其他工具 架构 IVO 简单。 ```text Telegram -> 机器人处理程序度器 -> 适配器 -> 引擎 ->回复 | | | | +-- Copilot CLI | | | +-- Copilot 适配器 +-- Ollama 适配器 +-- 技能 +-- 内存 +-- 子代理 +-- 会话存储 ``` 重要的分割是： - 适配器选择 IVO 如何与后端通信 - 引擎实际上执行工具启用代理工作流 实际上，Copilot 和 Ollama 是适配器选择，而 Copilot CLI 仍然是工具功能流背后的引擎 项目布局 ```text .github/ ├── agents/ Markdown 代理定义 └── skills/ Markdown 技能和元配置 .ivo/ └── 基于文件的内存存储/ ├── app.py异步应用程序 ├── YAML + 环境加载 ├── orchestr├── agents.py skills.py ├── ├── adapters/ / ├── bot/ ├── session/ └── utils/ ``` ## 配置 大多数配置位于 `config.yaml`。有关完整注释版本，请参见.example.yaml`部分： -`：机器人令牌、管理聊天、轮询- `api`：HTTP API 主机、端口、IP 允许列表 adapters`： 和 Ollama 后端 `defaults`：初始适配器选择 - `session`：sqlite、json 或内存会话存储 - `skills`：技能目录和自动加载规则 - `memory`：、截断、每用户模式 - `代理目录、工作区门代理、 - `work：命名的工作区根目录、活动工作区 cwd 同步 ## 内置命令 -` 显示状态和- `/models` 列出可用模型 <alias>` - `/agents出已注册的代理 - `/voice`回复 - `/stop` 中断当前- `/clear` 清除聊天历史记录 - `/workspace` 列出/切换命名工作区 w<name键切换工作区（例如 `/wivo`） 其他都被视为正常提示。 ## 技能、内存和代理 ### 技能 技能是纯 Markdown 文件定义了助手的行为，无需自定义代码。 ### 内存 内存基于简单。调度器将最近的内存注入，并将新的记忆事实追加到磁盘上。 代理 子代理前置信息的 Markdown 文件允许主助手任务，而无需引入重型框架。 示例： ```markdown --- name: sql-helper description:英语翻译成 SQL。 adapter: copilot: claude-sonnet-4.6 system_prompt_inline: | 您返回一个 SQL 语句来满足用户的请求。 tools: [] --- ``` ## 工作区模式 在 `workspaces.paths` 中配置命名工作区，选择启动工作区，并使用 `/workspace` 实时切换。 `/workspace` 现在为每个配置的工作区打印可快速命令（例如 `/wroot`、`/wivo`weltomatic`），无需输入名称即可切换。 当工作区激活IVO 会从该 `.github/ag 加载代理，并将叠在捆之上。 当.use_workspace: true` 也启用时，内存到该工作区状态按工作切换回来在那里使用的最后一个适配器/模型/代理。 API IVO 公开了一个小型 FastAPI 服务器用于集成和出站通知。 - `GET /health` - `GET /models` - `POST /send` 当启用 API 时，Swagger UI、ReDoc 和 OpenAPI 可用。静态模式也已提交到 `docs/openapi.json`。 默认情况下，只有环回客户端可以调用 API。您可以使用 `config.yaml` 中的 `api.allowed` 扩大访问## IVO 的比较 权衡是故意的。 - 如果您想要一个具有许多内部抽象的大型代理平台，IVO 可能太小。 - 如果一个仅作为聊天 Telegram 机器人，IVO 可能比必要更具能力。 - 如果您已经使用 Copilot CLI，并希望从手机上获得该 是狭窄的最佳选择。 ## 路线图 - 更好的首次运行设置流程 - 更多的捆绑技能和代理模板 - 更强大的多会话和专用代理工作流 - 更多的开箱即用 MCP 集成 - 更好的长时间运行任务的可观察性 ## 贡献 参见 [`CONTRIBUTING.md`](CONTRIBUTING.md)。 ## 许可证 MIT。参见 [`LICENSE`](LICENSE)。