Omnion（万象永恒）

永恒全能，编码与操作。

Omnion 是一个免费优先、开源可扩展的终端 AI Agent。它把大模型接进你的命令行， 既能像 Claude Code 一样读写代码、执行命令、跑测试，也能通过 Computer Use 真实操作电脑。

• 终端命令：omnion　PyPI 包名：omnion　协议：MIT
• 支持云端 OpenAI 兼容 API与本地 Ollama 模型，默认配置免费优先
• 内置文件 / Shell / Git / Computer Use 工具，全部带 JSON Schema
• Skill 技能系统：一个 SKILL.md 就能教会 Agent 你的专属工作流
• 危险操作默认需要确认，可选沙箱运行，绝不静默作恶

---

目录

• 特性
• 安装
• 配置模型
• 快速开始
• 斜杠命令
• 内置工具
• Skill 技能系统
• Computer Use 与安全
• 项目结构
• 从源码开发
• 打包与发布
• 路线图
• 许可证

---

特性

能力	说明
双模式推理	云端 API（Qwen3-Coder / DeepSeek / GPT / Gemini 等 OpenAI 兼容接口）+ 本地 Ollama
免费优先	默认推荐有免费额度的 Qwen3-Coder，或完全离线的 qwen2.5-coder:7b
Agent 循环	系统提示词 + 工具调用 + 结果回填 + 最大循环次数 + 全链路异常兜底
优雅降级	仅使用原生 function calling，不做任何文本协议降级，工具照样能用
编码能力	读文件、写文件、精确补丁、全文搜索、执行命令、跑测试、看 diff
Computer Use	截图、点击、拖拽、输入、按键、组合键、滚轮、剪贴板
Skill 系统	SKILL.md（YAML frontmatter + Markdown）注入系统提示词，支持内置/项目/用户三级
终端体验	Typer + Rich，Markdown 渲染、流式输出、彩色表格、斜杠命令 REPL
安全可控	危险命令与键鼠操作需确认；--yes 可跳过；路径越界拦截；密钥只从 .env 读

---

安装

方式一：从 PyPI 安装（发布后）

pip install omnion

方式二：从源码安装（开发推荐）

git clone https://github.com/rain16370/omnion.git
cd omnion

python -m venv .venv
# Windows PowerShell
.\.venv\Scripts\Activate.ps1
# macOS / Linux
source .venv/bin/activate

pip install -e ".[dev]"
omnion --version

要求：Python ≥ 3.10。

---

配置模型

Omnion 从 .env 或环境变量读取配置（永远不要把密钥提交到 Git，.env 已在 .gitignore 中）。

cp .env.example .env      # Windows PowerShell: Copy-Item .env.example .env

方案 A（推荐）：云端免费额度 —— Qwen3-Coder

API_KEY=sk-你的百炼APIKey
BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
MODEL=qwen3-coder-plus

其他 OpenAI 兼容服务只需替换三项：

# DeepSeek
API_KEY=sk-...
BASE_URL=https://api.deepseek.com/v1
MODEL=deepseek-chat

# OpenAI 官方
API_KEY=sk-...
BASE_URL=https://api.openai.com/v1
MODEL=gpt-4o-mini

# Google Gemini（OpenAI 兼容端点）
API_KEY=...
BASE_URL=https://generativelanguage.googleapis.com/v1beta/openai/
MODEL=gemini-2.0-flash

方案 B：本地模型，完全免费离线

# 1) 安装 Ollama：https://ollama.com/download
ollama pull qwen2.5-coder:7b
ollama serve

API_KEY=ollama                 # Ollama 不校验，填任意非空值即可
BASE_URL=http://localhost:11434/v1
MODEL=qwen2.5-coder:7b

临时覆盖配置

omnion --model qwen3-coder-plus --base-url https://... --api-key sk-...
omnion /model qwen2.5-coder:14b      # 交互模式内热切换

可选环境变量

变量	默认值	说明
OMNION_MAX_ITERATIONS	30	单次任务最大工具循环次数
OMNION_TEMPERATURE	0.2	采样温度（编码场景建议偏低）
OMNION_MAX_HISTORY	100	上下文保留的最大消息条数
OMNION_WORKSPACE	.	工作区根目录
OMNION_SCREENSHOT_PATH	screen.png	截图默认保存路径
OMNION_AUTO_APPROVE	false	是否跳过危险操作确认
OMNION_STREAM	false	是否默认开启流式输出
OMNION_TIMEOUT	180	模型请求超时（秒）

---

快速开始

交互模式

omnion

┌─────────────────────────────── ● Omnion 欢迎 ───────────────────────────────┐
│ 万象永恒  Omnion（万象永恒）v0.1.0                                          │
│ Slogan    永恒全能，编码与操作。                                            │
│ 模型      qwen3-coder-plus                                                  │
│ 工作区    D:\omnion                                                         │
│ 工具      22 个已注册  · 技能 1 个  · 流式 关                               │
└───────────────────────────── 终端命令：omnion ─────────────────────────────┘
万象永恒 Omnion 已启动。永恒全能，编码与操作。
omnion ›

一次性执行

omnion -p "写一个快速排序"
omnion -p "读一下 src/omnion/agent.py，用 5 句话讲清楚它的主循环"
omnion --yes -p "把 tests 全部跑一遍并总结失败原因"   # 跳过确认（谨慎）
omnion --stream -p "解释这个仓库的目录结构"          # 流式输出

常用命令行参数

参数	说明
-p, --prompt TEXT	一次性执行的任务描述（不提供则进入交互模式）
-m, --model TEXT	模型名
--base-url TEXT	OpenAI 兼容接口地址
--api-key TEXT	API Key（建议改用 .env）
-w, --workspace PATH	工作区目录
-y, --yes	跳过危险操作确认
--stream	流式输出
--tools	列出全部工具后退出
--skills	列出全部技能后退出
-v, --version	版本信息

---

斜杠命令

命令	说明
/help	显示帮助与可用命令
/exit	退出（/quit、exit、quit 同样有效）
/clear	清空当前会话上下文
/model [名称]	查看或切换模型
/skills	查看已加载的技能
/tools	查看已注册的工具
/history	查看最近的会话记录
/version	版本信息

---

内置工具

分类	工具	说明
文件	read_file	读取文件（支持 start_line / end_line 片段读取）
文件	write_file	写入/覆盖文件
文件	list_files	列目录，支持通配符与递归
文件	search_files	关键词全文搜索，返回文件 + 行号 + 片段
文件	apply_patch	精确文本替换（old_str → new_str）或整文件写入/追加
Shell	run_shell	执行命令（Windows 默认 PowerShell），高危命令需确认
Shell	run_python	执行一段 Python 代码并返回输出
Git	git_status	查看分支与工作区状态
Git	git_diff	查看 diff（支持 staged / ref / path）
Git	git_log	查看最近提交
电脑	screenshot	截图保存为 PNG 并返回路径
电脑	mouse_position	当前鼠标坐标与屏幕分辨率
电脑	click / move_to / drag_to	鼠标点击 / 移动 / 拖拽
电脑	type_text / press_key / hotkey	键盘输入 / 单键 / 组合键
电脑	scroll	滚轮滚动
电脑	read_clipboard / write_to_clipboard	剪贴板读写
电脑	wait	等待若干秒

随时用 omnion --tools 查看带 JSON Schema 的完整列表。

Git 工具刻意保持只读：提交、推送这类决定权永远留给人类。

---

Skill 技能系统

Skill 是 Omnion 的扩展机制：一个目录 + 一个 SKILL.md，内容会在启动时注入系统提示词。

目录优先级

1. 内置：omnion/skills/（随包发布）
2. 项目级：<工作区>/.omnion/skills/
3. 用户级：~/.omnion/skills/（对所有项目生效）

同名 Skill 由后者覆盖前者。

格式

---
name: deploy
description: 项目的标准发布流程
version: 1.0.0
tags: [devops, release]
---

# 技能：deploy

## 执行流程

1. 先跑 `pytest`
2. 再 `python -m build`
3. 用 `twine check dist/*` 校验

## 输出格式

- 一份发布检查清单

放进 ~/.omnion/skills/deploy/SKILL.md，重启 omnion 后用 /skills 即可看到。

内置示例：code-review

src/omnion/skills/code-review/SKILL.md 是一份完整的代码审查技能： 先用 git_status / git_diff 摸清改动范围，再按正确性 → 安全 → 性能 → 可维护性四层检查， 最后按 🔴 阻断 / 🟡 重要 / 🔵 建议 / ⚪ 疑问 四级输出结论，每条都带文件行号与可直接落地的修改建议。

试一下：

omnion -p "用 code-review 技能审查我当前的 git 改动"

---

Computer Use 与安全

⚠️ 安全警告 Computer Use 能真实地点击、输入、删除文件与数据。 请务必在虚拟机 / 沙箱 / 测试账号中运行。 强烈不建议在存有敏感数据的主力机上开启 --yes。

Omnion 的默认防线：

• 键鼠操作、剪贴板写入逐次询问确认（--yes 可跳过，请谨慎）
• 危险 Shell 命令（rm -rf、format、curl | bash、git push --force、git reset --hard 等）自动拦截并确认
• 直接执行 Python 代码时，命中删除文件、调用子进程、动态执行等模式会额外确认
• 写入工作区之外的路径需要确认
• PyAutoGUI 的 FAILSAFE 处于开启状态：鼠标猛移到屏幕左上角可紧急中止
• 截图默认写入 screen.png，已在 .gitignore 中

接入多模态

v0.1.0 的截图工具只返回图片路径，不做视觉理解；但结构上已经打通：

from omnion.llm import LLMClient

client = LLMClient(model="qwen-vl-max")        # 任意支持视觉的模型
answer = client.chat_vision("这个截图里有什么？", ["screen.png"])

把这段逻辑接进 Agent 循环，即可实现"看屏幕 → 决定下一步"的完整 Computer Use。

---

项目结构

omnion/
├── pyproject.toml            # 打包与依赖（[project.scripts] omnion = "omnion.cli:main"）
├── README.md
├── LICENSE                   # MIT
├── .env.example              # 配置模板（不含任何真实密钥）
├── .gitignore
├── src/omnion/
│   ├── __init__.py           # 项目元信息：Omnion / 万象永恒 / omnion
│   ├── cli.py                # Typer + Rich 入口，REPL 与斜杠命令
│   ├── agent.py              # OmnionAgent 核心循环
│   ├── llm.py                # OpenAI 兼容模型接入层（云端 + 本地）
│   ├── config.py             # 统一配置（env / .env / 默认值）
│   ├── memory.py             # 会话记忆与上下文裁剪
│   ├── permissions.py        # 危险操作识别与确认机制
│   ├── tools/
│   │   ├── __init__.py       # Tool / ToolRegistry 与 Schema 转换
│   │   ├── context.py        # 工具运行上下文（工作区 + 权限）
│   │   ├── file_tools.py     # read/write/list/search/apply_patch
│   │   ├── shell_tools.py    # run_shell / run_python
│   │   ├── git_tools.py      # git_status / git_diff / git_log
│   │   └── computer_tools.py # screenshot / click / type_text / press_key / scroll ...
│   └── skills/
│       └── code-review/SKILL.md
└── tests/                    # pytest 测试（工具、Skill、Agent 循环、CLI）

---

从源码开发

pip install -e ".[dev]"

python -m pytest              # 全部测试（不需要任何 API Key，全部用假模型）
python -m pytest -v           # 查看每个用例
python -m pytest tests/test_agent.py -k skill   # 只跑匹配用例

测试覆盖：配置解析、危险命令识别、会话记忆裁剪、五类工具、Skill 加载与注入、 Agent 循环（含工具调用、异常兜底、循环上限、降级协议）、CLI 参数与斜杠命令。 所有测试都不触网，用假模型客户端驱动。

---

打包与发布

# 1. 构建
python -m build                      # 产物在 dist/

# 2. 本地校验
twine check dist/*

# 3. 上传 PyPI（需要你的 PyPI Token，请自行保管，勿写进仓库）
python -m twine upload dist/*
# 注意：twine 7.x 已移除 `twine login`，请用以下任一方式提供凭据
#   方式 A（推荐）：存进系统 keyring，不落盘、不进命令历史
#   python -m keyring set pypi __token__    # 提示 Password 时粘贴 token
#   方式 B：当前终端会话的环境变量
#   $env:TWINE_USERNAME = "__token__"
#   $env:TWINE_PASSWORD = "pypi-xxxxxxxx"
#   方式 C：写入 ~/.pypirc（明文保存，twine 自动读取）

# 4. GitHub
git remote add origin https://github.com/rain16370/omnion.git
git push -u origin main

发布前请更新 pyproject.toml 中的 [project.urls] 为真实仓库地址。

---

路线图

• v0.1.0：Agent 核心循环、文件/Shell/Git 工具、Skill 系统、Computer Use 基础、CLI
• 子 Agent / 任务委派（并行执行多个子任务）
• 会话持久化与项目级记忆（memory.json）
• MCP（Model Context Protocol）客户端接入
• 多模态视觉回路（截图 → 视觉模型 → 决策）
• 工具并行执行与结果聚合
• 可选的网页搜索 / 浏览器自动化工具

---

参与贡献

欢迎提交 Issue 与 PR，尤其是：新 Skill、新工具、更多免费模型适配。

贡献前请确保：

python -m pytest      # 全部通过

许可证

MIT © 2026 Omnion（万象永恒）Contributors

永恒全能，编码与操作。