Metadata-Version: 2.4
Name: omnion
Version: 0.4.0
Summary: Omnion（万象永恒）· 永恒全能，编码与操作。免费优先的 AI Agent 命令行工具，支持云端 API 与本地模型、Skill 扩展与 Computer Use。
Author: Omnion Contributors
Maintainer: Omnion Contributors
License-Expression: MIT
Project-URL: Homepage, https://github.com/rain16370/omnion
Project-URL: Repository, https://github.com/rain16370/omnion
Project-URL: Issues, https://github.com/rain16370/omnion/issues
Keywords: ai,agent,cli,llm,coding,computer-use,skills,automation,qwen,ollama
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Code Generators
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: openai>=1.40
Requires-Dist: typer>=0.12
Requires-Dist: rich>=13.0
Requires-Dist: python-dotenv>=1.0
Requires-Dist: pyautogui>=0.9.54
Requires-Dist: Pillow>=10.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Dynamic: license-file

# 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 技能系统](#skill-技能系统)
- [Computer Use 与安全](#computer-use-与安全)
- [项目结构](#项目结构)
- [从源码开发](#从源码开发)
- [打包与发布](#打包与发布)
- [路线图](#路线图)
- [许可证](#许可证)

---

## 特性

| 能力 | 说明 |
|------|------|
| 双模式推理 | 云端 API（Qwen3-Coder / DeepSeek / GPT / Gemini 等 OpenAI 兼容接口）+ 本地 Ollama |
| 免费优先 | 默认推荐有免费额度的 Qwen3-Coder，或完全离线的 `qwen2.5-coder:7b` |
| Agent 循环 | 系统提示词 + 工具调用 + 结果回填 + 最大循环次数 + 全链路异常兜底 |
| 优雅降级 | 仅使用原生 function calling，不做任何文本协议降级，工具照样能用 |
| 编码能力 | 读文件、写文件、精确补丁、全文搜索、执行命令、跑测试、看 diff |
| Computer Use | 截图、点击、拖拽、输入、按键、组合键、滚轮、剪贴板 |
| 首次配置向导 | 装完即用：选供应商（GLM / Qwen / DeepSeek / Ollama / 自定义…）→ 选模型 → 填 Key → 选主题 |
| 主题系统 | 8 套终端主题，终端配色 + 代码高亮配色可分别切换 |
| 沙箱模式 | `--dry-run` 拦截全部写操作；`--audit` 记录危险操作审计日志 |
| 调试日志 | `--debug` 输出详细日志到 `~/.omnion/logs/`，密钥自动脱敏 |
| 技能按需加载 | 系统提示词只放技能索引，任务相关时才注入全文，避免污染普通任务 |
| Skill 系统 | `SKILL.md`（YAML frontmatter + Markdown）注入系统提示词，支持内置/项目/用户三级 |
| 终端体验 | Typer + Rich，Markdown 渲染、流式输出、彩色表格、斜杠命令 REPL |
| 安全可控 | 危险命令与键鼠操作需确认；`--yes` 可跳过；路径越界拦截；密钥只从 `.env` 读 |

---

## 首次运行配置向导（开箱即用）

在**任何一台新电脑**上装好 Omnion 后，第一次输入 `omnion` 会自动进入配置向导
（参照 openclaw 的首次引导），四步搞定，之后直接 `omnion` 就能用：

```
┌───────────────── ● Omnion 首次配置 ─────────────────┐
│ 1 选择供应商   本地 Ollama / 智谱 GLM / 阿里云百炼 Qwen │
│                DeepSeek / Kimi / 硅基流动 / OpenAI      │
│                Gemini / OpenRouter / Groq / 自定义     │
│ 2 选择模型     预设列表可直接选，也可手动输入模型 ID    │
│ 3 填写 API Key 本地 Ollama 跳过；云端输入时不会回显    │
│ 4 选择主题     8 套终端主题，带代码配色实时预览        │
│ + 工作区       默认当前目录                           │
│ + 高级参数     输出上限 / 循环次数 / 工具提示（可跳过）│
└──────────────────────────────────────────────────────┘
```

配置写入用户级文件 `~/.omnion/config.json`，**不污染项目目录、不需要手动建 .env**。

| 需求 | 命令 |
|------|------|
| 首次配置 | `omnion`（自动进入向导） |
| 随时重新配置 | `omnion --setup` |
| 交互模式内重配 | `/setup` |
| 只换主题 | `/theme` 或 `/theme dracula` |
| 查看可用主题 | `/theme` |

### 支持的供应商

| 类型 | 供应商 | 说明 |
|------|--------|------|
| 本地 | **Ollama** | 完全免费、离线；无需 API Key |
| 国内 | **智谱 GLM** | glm-4.6 / 4.5 / 4.5-air，原生 function calling |
| 国内 | **阿里云百炼 Qwen** | qwen3-coder-plus / flash，新用户有免费额度（默认推荐） |
| 国内 | DeepSeek | deepseek-chat / reasoner |
| 国内 | 月之暗面 Kimi | kimi-k2-turbo-preview |
| 国内 | 硅基流动 | 聚合平台，模型多 |
| 海外 | OpenAI | gpt-4.1 / 4o |
| 海外 | Google Gemini | 视觉强，可做截图分析 |
| 海外 | OpenRouter | 一个 Key 用全站模型 |
| 海外 | Groq | 免费额度、速度极快 |
| 自定义 | **任何 OpenAI 兼容接口** | 自建 vLLM / OneAPI / NewAPI / 网关，填 Base URL 即可 |

### 主题

`Omnion 经典`（默认）/ `VS Code Dark+` / `Dracula` / `Nord` / `Gruvbox Dark` /
`Solarized Dark` / `GitHub 浅色` / `极简黑白`—— 每套主题同时包含**终端品牌色**与
**代码块配色**（Monokai / vs / dracula / nord / gruvbox-dark / solarized-dark / friendly / bw）。

### 配置优先级

```
显式命令行参数 > 环境变量 > 项目 .env > ~/.omnion/config.json（向导写入） > 内置默认值
```

---

## 安装

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

```bash
pip install omnion
```

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

```bash
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` 中）。

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

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

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

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

```dotenv
# 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：本地模型，完全免费离线

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

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

### 临时覆盖配置

```bash
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` | 模型请求超时（秒） |

---

## 快速开始

### 交互模式

```bash
omnion
```

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

### 一次性执行

```bash
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` | 流式输出 |
| `--debug` | 输出调试日志（含模型请求摘要） |
| `--dry-run` | 只读沙箱：拦截写文件 / 命令 / 键鼠操作 |
| `--max-tokens` | 单次回复最大输出 token |
| `--tool-schema` | 工具提示详细度 `auto/full/compact/none` |
| `--setup` | 运行配置向导后退出 |
| `--tools` | 列出全部工具后退出 |
| `--skills` | 列出全部技能后退出 |
| `-v, --version` | 版本信息 |

---

## 斜杠命令

| 命令 | 说明 |
|------|------|
| `/help` | 显示帮助与可用命令 |
| `/exit` | 退出（`/quit`、`exit`、`quit` 同样有效） |
| `/clear` | 清空当前会话上下文 |
| `/model [名称]` | 查看或切换模型 |
| `/skills` | 查看技能列表（标注本次已加载） |
| `/skill <名称>` | 显式加载技能完整流程（`/skill off` 卸载） |
| `/debug` | 查看模型、接口、日志路径、沙箱状态 |
| `/audit` | 查看最近的危险操作审计记录 |
| `/tools` | 查看已注册的工具 |
| `/history` | 查看最近的会话记录 |
| `/version` | 版本信息 |
| `/setup` | 重新运行配置向导（换供应商/模型/主题） |
| `/theme [名称]` | 查看或切换终端主题 |

---

## 内置工具

| 分类 | 工具 | 说明 |
|------|------|------|
| 文件 | `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 由后者覆盖前者。

### 格式

```markdown
---
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` 摸清改动范围，再按**正确性 → 安全 → 性能 → 可维护性**四层检查，
最后按 🔴 阻断 / 🟡 重要 / 🔵 建议 / ⚪ 疑问 四级输出结论，每条都带文件行号与可直接落地的修改建议。

试一下：

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

---

## 调试与沙箱

```bash
omnion --debug                 # DEBUG 日志（~/.omnion/logs/omnion.log，1MB×3 轮转）
omnion --dry-run               # 只读沙箱：拦截写文件 / 命令 / 键鼠，打印将执行的动作
omnion --dry-run -p "重构这个文件" # 先看它打算怎么做，再决定是否放开
```

| 能力 | 说明 |
|------|------|
| 日志脱敏 | 日志与审计里的 `sk-*` / `pypi-*` / `ghp_*` 及 api_key/token 字段自动打码 |
| 审计日志 | 危险命令、键鼠操作、覆盖写入都会记入 `~/.omnion/logs/audit.log` |
| `/audit` | 在 REPL 里查看最近 20 条审计记录 |
| `/debug` | 查看当前模型、接口、工作区、日志路径、沙箱状态 |
| `--dry-run` | 13 类写操作（写文件/补丁/命令/点击/输入…）全部拦截，读取类工具照常 |

---

## 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` 的截图工具只返回图片路径，不做视觉理解；但结构上已经打通：

```python
from omnion.llm import LLMClient

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

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

---

## 项目结构

```text
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）
```

---

## 从源码开发

```bash
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 参数与斜杠命令。
**所有测试都不触网**，用假模型客户端驱动。

---

## 打包与发布

```bash
# 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]` 为真实仓库地址。

---

## 路线图

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

---

## 参与贡献

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

贡献前请确保：

```bash
python -m pytest      # 全部通过
```

## 许可证

[MIT](LICENSE) © 2026 Omnion（万象永恒）Contributors

> 永恒全能，编码与操作。
