Metadata-Version: 2.4
Name: omnion
Version: 0.5.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: tomli>=2.0; python_version < "3.11"
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"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Provides-Extra: browser
Requires-Dist: playwright>=1.44; extra == "browser"
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 | 截图、点击、拖拽、输入、按键、组合键、滚轮、剪贴板 |
| 浏览器自动化 | Playwright **DOM 级**操作（按选择器点击/填表/读正文），替代盲点坐标；可选依赖 |
| **项目记忆** | `OMNION.md`（类 `CLAUDE.md`）自动注入系统提示词；`@文件` 一键引内容 |
| **自动验证闭环** | 改完自动跑语法检查 + 测试，**失败把真实报错喂回让模型自修**，不许"改崩了还汇报完成" |
| **Plan Mode** | 只读 → 计划 → 批准 → 执行：计划阶段写操作被硬锁，批准后才解锁 |
| 首次配置向导 | 装完即用：选供应商 → 选模型 → 填 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 / 硅基流动 / 火山方舟    │
│                百度千帆 / 腾讯混元 / MiniMax / 阶跃 / 零一│
│                OpenAI / Gemini / OpenRouter / Groq      │
│                xAI / Mistral / Together / Perplexity     │
│                Azure / Fireworks / 自定义（共 23 家）    │
│ 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 |
| 国内 | 硅基流动 | 聚合平台，模型多 |
| 国内 | **火山引擎方舟 Doubao** | doubao-seed-1.6 等，有免费额度 |
| 国内 | **百度千帆 ERNIE** | ernie-4.5 / x1 系列 |
| 国内 | **腾讯混元 Hunyuan** | hunyuan-turbos / large |
| 国内 | **MiniMax** | MiniMax-Text-01 / abab 系列 |
| 国内 | **阶跃星辰 Step** | step-2 / step-1.5 系列 |
| 国内 | **零一万物 Yi** | yi-lightning / yi-large |
| 海外 | OpenAI | gpt-4.1 / 4o |
| 海外 | Google Gemini | 视觉强，可做截图分析 |
| 海外 | OpenRouter | 一个 Key 用全站模型 |
| 海外 | Groq | 免费额度、速度极快 |
| 海外 | **xAI Grok** | grok-4 / grok-3 系列 |
| 海外 | **Mistral AI** | mistral-large / codestral |
| 海外 | **Together AI** | 开源模型聚合（Llama / DeepSeek / Qwen） |
| 海外 | **Perplexity** | 联网搜索模型（sonar 系列） |
| 海外 | **Azure OpenAI** | 企业合规，部署名即模型 ID |
| 海外 | **Fireworks AI** | 速度快，模型多 |
| 自定义 | **任何 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 的用户请看这一节**，不需要卸载重装。

### 最常用：一条命令升级

```bash
pip install --upgrade omnion      # 简写：pip install -U omnion
omnion --version                 # 确认版本号
```

`pip install omnion` 在已安装的情况下**不会自动升级**，必须加 `--upgrade`（或 `-U`），
这是最常见的"装完还是旧版本"原因。

### 按安装方式对照

| 你当初的安装方式 | 升级命令 |
|------------------|----------|
| `pip install omnion` | `pip install --upgrade omnion` |
| `pipx install omnion` | `pipx upgrade omnion` |
| `pip install -e ".[dev]"`（源码开发） | `git pull && pip install -e ".[dev]"` |
| Docker | `docker build -t omnion .`（重新构建镜像） |
| PyInstaller 单文件 | `git pull && python build_exe.py`（重新出包） |

### 升级会不会丢配置？

不会。你的配置在 `~/.omnion/config.json`、密钥在 `.env`，升级只替换程序代码，**不会覆盖或删除**。
想换供应商 / 模型 / 主题，升级后执行 `omnion --setup` 重新走一遍向导即可。

### 从 0.4.x 升级到 0.5.0 的注意事项

- **首次配置向导不再替你预设默认项**：供应商、模型、主题都需要手动选择（避免误用不合适的默认模型）。
  已经配置好的用户**不受影响**，直接 `omnion` 即可。
- 新增启动欢迎界面与吉祥物；脚本场景加 `--no-banner` 关闭。
- 如果升级后命令行为异常，先确认装的是新版：
  ```bash
  omnion --version            # 应显示 0.5.0
  python -m omnion.cli --version   # 绕过 PATH，定位实际生效的版本
  pip show omnion             # 查看 pip 记录的安装位置与版本
  ```
  若 `pip show omnion` 显示 0.5.0 但 `omnion --version` 不是，多半是**同时存在多个 Python 环境**，
  请用与你安装时相同的那个解释器执行 `pip install --upgrade omnion`。

---

## 配置模型

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

启动后会显示欢迎面板：左侧是原创吉祥物「星核之灵」，右侧是项目信息（版本随
`pyproject.toml` 动态读取）、工作区、模型、工具与技能数、快捷命令，以及一句随机台词：

```
┌─ Omnion 欢迎 ────────────────────────────────┐
│ 万象永恒 · Omnion（万象永恒）  v0.5.0          │
│ 永恒全能，编码与操作。                         │
│ 模型   qwen3-coder-plus                       │
│ 工作区 D:\omnion                              │
│ 工具   42 个已注册  · 技能 5 个               │
│ 快捷   /help /model /skills /tools /exit      │
└ 终端命令：omnion ─────────────────────────────┘
（面板左侧还有吉祥物「星核之灵」~ 随机说一句台词；--no-banner 可关闭）
```
> 脚本 / 截图场景下可用 `omnion --no-banner` 跳过欢迎界面直接进入交互或执行任务。

### 一次性执行

```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` | 运行配置向导后退出 |
| `--no-banner` | 关闭启动欢迎界面（便于脚本调用 / 截图） |
| `--tools` | 列出全部工具后退出 |
| `--skills` | 列出全部技能后退出 |
| `-v, --version` | 版本信息 |

---

## 斜杠命令

| 命令 | 说明 |
|------|------|
| `/help` | 显示帮助与可用命令 |
| `/exit` | 退出（`/quit`、`exit`、`quit` 同样有效） |
| `/clear` | 清空当前会话上下文 |
| `/model [名称]` | 查看或切换模型 |
| `/skills` | 查看技能列表（标注本次已加载） |
| `/skill <名称>` | 显式加载技能完整流程（`/skill off` 卸载） |
| `/debug` | 查看模型、接口、日志路径、沙箱状态 |
| `/audit` | 查看最近的危险操作审计记录 |
| `/tools` | 查看已注册的工具 |
| `/history` | 查看最近的会话记录 |
| `/version` | 版本信息 |
| `/setup` | 重新运行配置向导（换供应商/模型/主题） |
| `/theme [名称]` | 查看或切换终端主题 |
| `/plan` | **Plan Mode**：只读计划模式（`/plan <任务>` / `/plan approve` / `/plan off`） |
| `/verify on\|off` | 改完代码是否自动跑验证并自修（默认 on） |
| `/memory` | 查看 / 重新加载项目记忆文件 `OMNION.md` |
| `/auto on\|off` | 复杂任务是否自动先规划（默认 off） |
| `/subagent <任务>` | 拆成并行子任务执行并汇总 |
| `/mcp` | 查看 MCP Server 连接状态 |

---

## 工作流能力

这一层是 Omnion 与「只会聊天 + 调工具」的分水岭：**让 Agent 越用越懂你的项目，
并且不许它把代码改崩还不自知**。

### 项目记忆 `OMNION.md`（类 `CLAUDE.md`）

在项目根目录放一份 `OMNION.md`，启动时自动读取并注入系统提示词——
项目约定、技术栈、禁区、输出风格不必每次重复交代。

```markdown
# OMNION.md · 项目记忆

## 铁律
1. 改完必须跑测试，不要为了"看起来通过"而绕过
2. 不要改 tests/
3. 新增工具必须三处同步登记：tool_policy 分类、dangerous 标记、schema 与签名一致
```

- 从工作区**逐级向上查找**（最多 4 层父目录），也兼容 `AGENTS.md` / `CLAUDE.md`
- `/memory` 改完随时重新加载，不用重启
- 优先级**高于**内置的通用工作方式说明

### `@文件` 引用

```text
omnion › 帮我看看 @src/llm.py 的重试逻辑有没有问题
```

该文件内容会随本轮消息一起送给模型，省去"先 read_file 再回答"的来回。
只展开**工作区内、非敏感**（`.env` / `*.pem` / `id_rsa` 等）的文件，
单文件超 8K 字符截断，一轮最多 5 个。

### 改完自动验证闭环

以前 Agent 改完代码直接汇报，它并不知道自己写的是不是语法错误。
现在每次写操作后自动跑一层验证，把**真实失败输出**喂回对话让它自修：

1. **语法检查**：对改动的 `.py` 做 `ast.parse`（进程内、零副作用、微秒级）
2. **跑测试**：语法过了且项目有 `tests/` 时跑 `pytest -q -x`（子进程、180s 超时）

```text
[自动验证失败] 语法检查未通过（1/1 个文件有语法错误）
src/a.py:3: SyntaxError —— expected ':'
请依据下面的真实报错修正后重新验证，不要在未验证通过的情况下宣称任务完成。
```

`/verify off` 可关闭；`--dry-run` 沙箱下自动跳过。

### Plan Mode：只读 → 计划 → 批准 → 执行

```text
omnion › /plan 给登录接口加上限流
  → 进入 Plan Mode：写操作被锁，只能 read_file / search_files / git diff
  → 模型调研现状后输出计划（改哪些文件、风险、怎么验证）

omnion › /plan approve
  → 解锁写操作，把计划交给模型执行（含自动验证闭环）

omnion › /plan off        # 不批准，直接退出
```

实现上在**两处**同时收窄：暴露给模型的工具 schema 只保留只读工具，
且 `execute_tool` 对写工具硬拦截——即使模型"想"写也写不了。

### 浏览器自动化（Playwright，DOM 级）

Computer Use 的「截图 → 猜坐标 → 点」是盲点操作。Playwright 直接操作 DOM：

| 需求 | 工具 |
|------|------|
| 打开网页 | `browser_open` |
| 看看页面上有什么可点的 | `browser_snapshot` |
| 读正文 | `browser_read` |
| 点按钮 / 填表单 / 按键 | `browser_click` / `browser_type` / `browser_press` |
| DOM 搞不定时兜底 | `browser_screenshot` + 坐标点击 |

浏览器实例是**进程内单例**（不会每个工具重启一次浏览器），`browser_close` 释放。
所有改变页面的操作都需确认，并已在 `--dry-run` 与 Plan Mode 下正确拦截。

### 工具读写分类：单一真相来源

`--dry-run` 拦截、并行/串行分流、Plan Mode 白名单、子 Agent 工具收窄，
全部依赖同一份分类表 `src/omnion/tool_policy.py`：

```python
READ_ONLY_TOOLS  # 只读，Plan Mode 可用
MUTATING_TOOLS   # 写操作，--dry-run 与 Plan Mode 拦截
SERIAL_TOOLS     # 必须串行（写操作 + 资源释放）
```

新增工具只需改这一处，不会再出现"加了写工具但忘了登记，`--dry-run` 拦不住"
（例如 `git_commit` / `run_tests` 曾长期缺失于拦截名单）。

---

## 内置工具

| 分类 | 工具 | 说明 |
|------|------|------|
| 文件 | `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` | 等待若干秒 |
| 浏览器 | `browser_open` | 用 Chromium 打开网址，返回标题与正文摘要 |
| 浏览器 | `browser_snapshot` | 列出页面可交互元素（链接/按钮/输入框）及选择器 |
| 浏览器 | `browser_read` | 读取指定 CSS 选择器的文本内容 |
| 浏览器 | `browser_click` / `browser_type` / `browser_press` | 按选择器点击 / 填表 / 按键（需确认） |
| 浏览器 | `browser_evaluate` / `browser_upload` | 执行页面 JS / 上传文件（需确认） |
| 浏览器 | `browser_screenshot` / `browser_tabs` / `browser_close` | 网页截图 / 标签页管理 / 关闭浏览器 |

共 **42 个工具**。随时用 `omnion --tools` 查看带 JSON Schema 的完整列表。

> **浏览器自动化**是可选依赖，不装也能用其它工具（会明确提示未安装）：
> ```bash
> pip install "omnion[browser]" && playwright install chromium
> ```
> DOM 能定位就用 DOM，DOM 搞不定（Canvas、远程桌面、原生控件）再退回
> `browser_screenshot` + 坐标点击，两者互补而非替代。

> Git 工具刻意保持**克制**：`git_commit` 只提交明确列出的文件（禁止 `git add -A`），
> 且在 `--dry-run` 沙箱与 Plan Mode 下会被拦截。

---

## Skill 技能系统

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

### 目录优先级

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

同名 Skill 由后者覆盖前者。

### 格式

```markdown
---
name: deploy
description: 项目的标准发布流程
version: 0.5.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` 中

### 接入多模态

`omnion` 的截图工具返回图片路径，结构上已为多模态视觉回路打通：

```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 / 默认值）
│   ├── providers.py          # 23 家供应商预设（云端 + 本地）
│   ├── memory.py             # 会话记忆与上下文裁剪
│   ├── permissions.py        # 危险操作识别与确认机制
│   ├── planner.py            # 任务规划（子步骤拆解）
│   ├── subagent.py           # 子 Agent / 任务委派
│   ├── sessions.py           # 会话持久化与项目级记忆
│   ├── parallel.py           # 工具并行执行与结果聚合
│   ├── mcp.py                # MCP（Model Context Protocol）客户端接入
│   ├── computer_use.py       # Computer Use 调度（节流 / 紧急中止）
│   ├── banner.py             # 启动欢迎界面与吉祥物「星核之灵」
│   ├── tool_policy.py        # 工具读写分类的唯一真相来源
│   ├── project_memory.py     # OMNION.md 项目记忆 + @文件引用展开
│   ├── verifier.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
│   │   ├── browser_tools.py  # browser_*（Playwright DOM 级自动化）
│   │   └── computer_tools.py # screenshot / click / type_text / press_key / scroll ...
│   └── skills/
│       └── code-review/SKILL.md
├── docs/                     # 架构 / 安装 / 配置 / 使用 / FAQ / Computer Use / Skill
└── 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
```

---

## 路线图

- [x] v0.5.0：Agent 核心循环、23 家供应商、文件/Shell/Git 工具、Skill 系统、Computer Use、启动欢迎界面与吉祥物「星核之灵」、安全审计与 CI/CD
- [x] 子 Agent / 任务委派（`subagent.py`，并行执行多个子任务）
- [x] 会话持久化与项目级记忆（`sessions.py` / `memory.json`）
- [x] MCP（Model Context Protocol）客户端接入（`mcp.py`）
- [x] 多模态视觉回路（`llm.chat_vision`：截图 → 视觉模型 → 决策）
- [x] 工具并行执行与结果聚合（`parallel.py`）
- [ ] 可选的网页搜索 / 浏览器自动化工具

---

## 参与贡献

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

贡献前请确保：

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

## 许可证

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

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