Metadata-Version: 2.4
Name: snow-agent
Version: 0.2.1
Summary: Cross-device command execution and agent orchestration CLI.
Author: XiaodongTong
License-Expression: MIT
Project-URL: Homepage, https://github.com/XiaodongTong/snow-agent
Project-URL: Repository, https://github.com/XiaodongTong/snow-agent
Project-URL: Issues, https://github.com/XiaodongTong/snow-agent/issues
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
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
Classifier: Topic :: System :: Distributed Computing
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=7.4; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Dynamic: license-file

# snow-agent

> 不用在各个 Agent 窗口之间来回切换，更不用守在屏幕前当“接力棒”。在同一个终端里一次性派完所有方案：同项目绝对串行排队、无冲突独立验证、自动受控提交，把人从琐碎的盯哨中彻底解放出来。

用 AI 编码 Agent 辅助开发，现实中往往被两件事折磨：
- **在各个 Agent 窗口之间来回横跳**：电脑里装了 Codex、Claude Code、OpenCode 等各种工具，做不同需求要在不同终端或应用窗口之间反复切换、各自盯进度，注意力被撕得稀碎。
- **人肉当调度器与防冲突接力棒**：手里有方案 A、B、C，并发派给多个 Agent 立刻引发代码冲突与覆盖；为了避免冲突，只能自己守在屏幕前，等一个跑完、确认后再手动派下一个，人被死死拴在 Human-in-the-loop 的低效循环里。

`snow-agent` 针对这两层痛点重构工作流：
- **单窗口统筹分发**：无需在不同客户端间来回切，同一个终端内直接把任务派给任意原生 Agent；
- **同项目绝对串行排队**：方案明确后一口气把所有任务全部提交。后台严格单任务推进，前序任务独立验证通过并自动提交 Git 后，后续任务才在干净的最新代码上启动，彻底消除代码合并冲突与人肉盯哨成本。

---

## 核心能力

- **跨 Agent 统一委派（告别窗口横跳与会话中断）**
  通过 `delegate submit --agent <name>`，在一个终端内把开发方案交给任意原生编码 Agent。
  - **一个入口统筹**：无需打开多个 Agent 客户端或终端分屏，统一提交、统一查进度；
  - **同项目绝对串行**：同项目任务 FIFO 串行排队推进，避免代码覆盖与合并冲突；
  - **离线持久运行**：提交后立即返回任务 ID，后台守护进程接管执行，终端关闭或人离开不影响任务进行；
  - **独立核验与受控提交**：Agent 实现后由 Snow 独立执行验证命令，验证通过才执行 Git 提交，不凭 Agent 凭空汇报；
  - **AI Native**：任何外部 Agent 无需预装专属 Prompt 或 Skill，仅凭 `--help` 分层帮助即可自主感知能力与排错。

- **辅助能力：设备连接与常用命令**
  - **跨设备命令执行**：通过 `host` 注册设备，经 SSH 调用远端命令（`exec --host`），直接复用远端当前用户的登录态与权限；
  - **常用命令托管**：通过 `command` 将常用 CLI 注册为命名命令并自动检查可执行性，日常使用 `command run` 快速调用。

---

## 已支持的 Agent

运行 `snow-agent delegate targets` 可一键检测本机已安装且可用的 Agent：

| 标识 (`--agent`) | 对应工具 | 特点与运行环境 |
| --- | --- | --- |
| `codex` | Codex CLI | 沙盒隔离执行，任务目录按需授权 |
| `claude-code` | Claude Code CLI | 复用本机登录态，无人值守执行 |
| `opencode` | OpenCode CLI | 自动识别凭据与模型，需配置放行权限 |
| `antigravity` | Antigravity CLI (`agy`) | 全放行模式执行，建议独立沙盒仓库 |
| `zcode` | ZCode Desktop | 经桌面端内置 bundle 无头执行 |
| `cursor` | Cursor Agent CLI (`cursor-agent`) | 官方 headless print 模式，需 `agent login` 登录态或 `CURSOR_API_KEY` |

---

## 安装

已发布至 [PyPI](https://pypi.org/project/snow-agent/0.2.1/)，要求 Python >= 3.10，零第三方运行时依赖：

```bash
pip install snow-agent         # PyPI 安装
uvx snow-agent --version       # 免安装直接运行（推荐尝鲜）
pipx install snow-agent        # 独立环境安装
```

---

## 快速开始

### 1. 委派任务给原生编码 Agent（本机主线）

初始化配置并启动后台调度器：
```bash
snow-agent init
snow-agent daemon start
snow-agent delegate targets                        # 查看本机可用的 Agent
```

提交开发方案给编码 Agent（以 Codex 为例）：
```bash
snow-agent delegate submit --cwd /path/to/repo --agent codex --file ./plans/feat.md
snow-agent task show <task_id>                     # 查询执行阶段、验证结果与提交状态
```
提交后即可关闭终端，后台守护进程接管排队与执行；任务完成且验证通过后自动受控提交 Git。使用 `snow-agent task list/cancel/resume` 可随时查看和管理任务。

### 2. 辅助能力：跨设备调用与常用命令

如需跨机调用或管理常用命令：
```bash
snow-agent host add main --ssh user@192.168.1.10   # 注册设备
snow-agent exec --host main -- meishi unread       # 跨机执行远端命令
snow-agent command add meishi --host main --bin /opt/homebrew/bin/meishi
snow-agent command run meishi -- unread            # 作为命名命令快速复用
```

---

## 当前边界

以下能力仍在规划中，尚未交付：定时调度（`job`）、配置管理（`config`）、环境检查（`doctor`）、MCP 接入与内置 Agent Loop。此外，跨设备命令执行与跨设备委派转发仍属早期功能，持续完善中。

---

## 深入了解

全部命令参数、跨设备委派完整工作流、状态机与错误处理规范，请查阅完整文档：
- [CLI 使用指南](docs/cli-usage.md)
