Metadata-Version: 2.4
Name: snow-agent
Version: 0.1.0
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

Cross-device command execution and agent orchestration CLI.

snow-agent 把目标设备（host）与可复用命令（command）作为确定性资源管理：先注册可通过 SSH 访问的目标设备，再在本地或目标机上执行命令，直接复用目标机用户的登录态与业务凭据，不复制私钥或业务令牌。跨 Agent 任务委派（delegate/task/daemon）把开发方案交给执行设备上的原生编码 Agent（Codex / OpenCode / Claude Code / Antigravity CLI / ZCode）持久执行：同项目任务 FIFO 串行，Snow 独立验证并受控提交。定时调度（job）、配置管理（config）、环境检查（doctor）、MCP 接入与 Snow 自有 Agent Loop 在 [docs](docs/) 中规划，随迭代交付。

## 安装

需要 Python >= 3.10，无第三方运行时依赖：

```bash
uvx snow-agent --version       # 免安装直接运行（uv）
pipx install snow-agent        # 独立环境常规安装
pip install snow-agent         # 装入当前环境
```

开发安装：克隆仓库后 `pip install -e .`。

安装后获得 `snow-agent` 命令入口；`uvx snow-agent` 无需安装即可使用全部子命令。

## 当前可用命令

完整调用说明（参数、工作流、JSON 字段与错误恢复）见 [docs/cli-usage.md](docs/cli-usage.md)；本节只列命令速览。

```text
snow-agent help [COMMAND...]        # 分层帮助；--format json 输出同源的结构化能力描述
snow-agent init                     # 初始化用户级配置
snow-agent host add|list|show|test|remove          # 目标设备注册与 SSH 连通性检查
snow-agent command add|list|show|check|run|remove  # 可复用命令注册、检查与执行
snow-agent exec [--host HOST] [--cwd PATH] [--timeout DURATION] -- COMMAND [ARGS...]
snow-agent delegate submit|targets  # 把开发方案提交给原生编码 Agent 持久执行
snow-agent task list|show|cancel|resume|report     # 委派任务的查询、取消、恢复与阶段上报
snow-agent daemon start|stop|status # 任务调度守护进程（单实例）
```

无参数调用 `snow-agent` 预留给未来的交互式 TUI，当前降级为输出根帮助。

`job`、`config`、`doctor`、`mcp`、`agent` 已在命令树中声明但尚未实现，调用返回结构化 `not_available` 错误。`_rpc` 是委派传输经 SSH 调用的内部入口，不面向日常调用。

根级支持 `snow-agent --version`：文本模式输出一行 `snow-agent 0.1.0`；`--json` 输出 `{"schema_version":1,"kind":"version","version":"0.1.0"}`。该选项仅在根级可用。

退出码：确认的业务退出码原样保留；Snow 自身失败为 1；超时或中断等结果不确定的情况为 2。

文本模式（无 `--json`）下，远端执行的输出剥离 snow-agent 控制记录后逐块实时转发到本进程 stdout/stderr，不等待命令结束；`--json` 时 stdout 只有一个结果对象，字段契约见 `snow-agent exec --help`。

配置存储在 `~/.snow-agent/`（目录 0700、文件 0600、原子写入），用环境变量 `SNOW_AGENT_CONFIG_DIR` 可指定其他位置。

## 快速上手

本地执行，无需任何配置：

```bash
snow-agent exec -- git status
```

跨设备执行（备用机调用主力机上已登录的业务 CLI）：

```bash
snow-agent host add main --ssh user@192.168.1.10   # 注册目标设备，认证沿用标准 SSH 配置
snow-agent host test main                          # 检查连接、认证与目标执行环境
snow-agent exec --host main -- meishi unread       # 在目标机上执行一次
```

对需要反复调用的 CLI，注册为可复用命令：

```bash
snow-agent command add meishi --host main --bin /opt/homebrew/bin/meishi
snow-agent command check meishi
snow-agent command run meishi -- unread
```

跨设备委派在项目所在设备执行（`--host` 指定，默认 local）；方案文件在调用端读取，以不可变快照传输。执行设备需先启动调度进程：

```bash
snow-agent daemon start                                             # 在执行设备上启动任务调度
snow-agent delegate targets                                         # 查看当前设备可用的委派目标（codex / opencode / claude-code / antigravity / zcode）
snow-agent delegate submit --cwd /workspace/repo --agent codex --file ./plans/B.md
snow-agent task show <task_id>                                      # 轮询阶段、验证结论与提交哈希
```

`submit` 立即返回任务 ID；执行设备上的队列、Agent 轮次、独立验证与受控提交在调用方离线后继续。同项目任务按提交顺序串行，失败或状态不明的任务阻塞后续任务，处理后用 `task resume` 恢复。跨设备查询与提交经 SSH 短请求转发到执行设备，方案文件在调用端读取后以不可变快照传输。

取消、恢复、崩溃续接与各阶段上报语义，以及全部命令的参数、JSON 字段和错误处理，见 [docs/cli-usage.md](docs/cli-usage.md)。

每个命令都有分层 `--help`；外部 Agent 无需预置专属 Skill，仅凭逐级帮助与结构化结果即可完成配置、检查、执行和错误恢复。
