omnion 0.1.0__tar.gz

omnion-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Omnion（万象永恒）Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

omnion-0.1.0/PKG-INFO

@@ -0,0 +1,453 @@
+Metadata-Version: 2.4
+Name: omnion
+Version: 0.1.0
+Summary: Omnion（万象永恒）· 永恒全能，编码与操作。免费优先的 AI Agent 命令行工具，支持云端 API 与本地模型、Skill 扩展与 Computer Use。
+Author: Omnion Contributors
+Maintainer: Omnion Contributors
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/omnion/omnion
+Project-URL: Repository, https://github.com/omnion/omnion
+Project-URL: Issues, https://github.com/omnion/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 | 截图、点击、拖拽、输入、按键、组合键、滚轮、剪贴板 |
+| Skill 系统 | `SKILL.md`（YAML frontmatter + Markdown）注入系统提示词，支持内置/项目/用户三级 |
+| 终端体验 | Typer + Rich，Markdown 渲染、流式输出、彩色表格、斜杠命令 REPL |
+| 安全可控 | 危险命令与键鼠操作需确认；`--yes` 可跳过；路径越界拦截；密钥只从 `.env` 读 |
+
+---
+
+## 安装
+
+### 方式一：从 PyPI 安装（发布后）
+
+```bash
+pip install omnion
+```
+
+### 方式二：从源码安装（开发推荐）
+
+```bash
+git clone <omnion-repo-url>
+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` | 流式输出 |
+| `--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 由后者覆盖前者。
+
+### 格式
+
+```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 改动"
+```
+
+---
+
+## 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 --repository pypi dist/*
+# 或用环境变量避免 Token 出现在命令历史里：
+#   $env:PYPI_API_TOKEN = "pypi-xxxxxxxx"   （PowerShell）
+#   python -m twine upload dist/*
+
+# 4. GitHub
+git remote add origin <你的仓库地址>
+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
+
+> 永恒全能，编码与操作。