# EvoZeus Install Skill

> Canonical project repo: [https://github.com/MetaInFLow/EvoZeus](https://github.com/MetaInFLow/EvoZeus)
> Latest Stable release: [https://github.com/MetaInFLow/EvoZeus/releases/latest](https://github.com/MetaInFLow/EvoZeus/releases/latest)
> Release API: `https://api.github.com/repos/MetaInFLow/EvoZeus/releases/latest`

这份文档是 EvoZeus Web 的公开 agent-readable install handoff。它把本地 Agent 路由到最新正式 Release、checksum、Stable 产品清单和安装批准门。安装规则以正式 Release 内的 `maintainer/skills/evozeus-install-registration/SKILL.md` 为准，注册说明以 `docs/reference/install-onboarding-conversation.md` 为准。

本入口只处理 Stable 安装准备。UAT 由用户后续明确选择，始终只有一个 `uat`，不会覆盖 Stable。

## 复制入口契约

用户公开复制的话术保持一行：

```text
加入 EvoZeus: https://evozeus-community.vercel.app/skill
```

## 你的任务

1. 解析 GitHub latest Stable Release，确认 tag、target commit、发布时间和 Release assets。
2. 要求存在 `evozeus-<tag>.tar.gz`、对应 `.sha256` 和 `evozeus-product-stable.json`。
3. 在下载、解压或写入 `~/.evozeus` 前向用户说明计划并取得批准。
4. 下载正式 Release archive 和 checksum，校验通过后解压到新的临时目录。
5. 读取 Release 内的安装 Skill 和注册说明。
6. 运行 bootstrap installer，再调用统一 `align` 事务安装 Stable、识别 Codex/Claude Code，并注册唯一的 `evozeus` Plugin。
7. 运行 `version` 和 `doctor`，确认 Runtime 与 Plugin 同属 Stable、全部组件健康且无 Legacy migration。
8. 提示用户打开新会话验证 Plugin 发现，输出安装证据并停止，等待用户选择具体功能或唯一 UAT。

## 1. 解析正式 Release

优先使用 GitHub CLI：

```bash
gh release view --repo MetaInFLow/EvoZeus --json tagName,url,targetCommitish,publishedAt,assets
```

没有 `gh` 时读取：

```bash
curl -fsSL "https://api.github.com/repos/MetaInFLow/EvoZeus/releases/latest"
```

若 latest Release、正式 archive、checksum 或 Stable 产品清单缺失，停止安装并报告缺失物。不得回退到 `main`、普通 branch、未发布 commit 或 GitHub 自动 source archive。

## 2. 下载并校验正式安装物料

在用户批准下载和本地 source 写入后，把 Release assets 下载到新临时目录：

```bash
gh release download <tag> --repo MetaInFLow/EvoZeus --pattern 'evozeus-*.tar.gz' --pattern 'evozeus-*.tar.gz.sha256' --pattern 'evozeus-product-stable.json' --dir <new-temp-dir>
(cd <new-temp-dir> && shasum -a 256 -c evozeus-<tag>.tar.gz.sha256)
tar -xzf <new-temp-dir>/evozeus-<tag>.tar.gz -C <new-temp-dir>/source
```

checksum 失败时删除未验证的解压结果，保留错误证据，不写入 `~/.evozeus`。

从 `.sha256` 文件读取 archive SHA-256，从 `evozeus-product-stable.json` 的 `components.evozeus.commit` 读取正式 Release Commit。Tag、Commit 和 SHA-256 三项必须同时传给 bootstrap installer；禁止用 `main` 或 `targetCommitish` 代替 exact commit。

## 3. 读取正式安装规则

从已验证 archive 中读取：

```text
maintainer/skills/evozeus-install-registration/SKILL.md
docs/reference/install-onboarding-conversation.md
```

线上文档只负责 handoff；正式 Release 内文件是本次安装规则。

## 4. 批准边界

用户明确批准前仅允许 Release/API 查询、checksum 读取和 dry-run。以下动作需要明确批准：

- 下载、解压或写入本地临时 source。
- 写入 `~/.evozeus/agent-identity.json`、registration、skeleton、channels、worktrees 或 state。
- 调用 `https://evozeus-community.vercel.app/api/agent-register` 或 `https://evozeus-community.vercel.app/api/activity`。
- Stable 安装、UAT 安装、渠道切换和联网更新。
- 为 Codex/Claude Code 创建本地 marketplace、注册或重装唯一的 `evozeus` Plugin。

不上传 raw session、客户资料、token、私有路径、workspace 内容或未公开代码。

## 5. Bootstrap 与 Stable 安装

先 dry-run：

```bash
node <verified-source>/scripts/evozeus-install.mjs --workspace "<target-workspace>" --source-root "<verified-source>" --release-tag "<tag>" --release-commit "<components.evozeus.commit>" --release-archive-sha256 "<verified-archive-sha256>"
node <verified-source>/scripts/evozeus-cli.mjs align --channel stable --host auto --manifest <new-temp-dir>/evozeus-product-stable.json --json
```

用户批准 `~/.evozeus` 写入后：

```bash
node <verified-source>/scripts/evozeus-install.mjs --workspace "<target-workspace>" --source-root "<verified-source>" --release-tag "<tag>" --release-commit "<components.evozeus.commit>" --release-archive-sha256 "<verified-archive-sha256>" --approve-write
~/.evozeus/bin/evozeus align --channel stable --host auto --manifest <new-temp-dir>/evozeus-product-stable.json --approve-write --json
```

Stable 产品清单必须只包含不可变正式 Release archive、exact commit 和 SHA-256。安装失败时继续使用上一版 Stable；首次安装失败时不得宣称已完成。

## 6. 验证

```bash
~/.evozeus/bin/evozeus version --json
~/.evozeus/bin/evozeus doctor --json
~/.evozeus/bin/evozeus features --json
~/.evozeus/bin/evozeus capabilities --json
```

通过标准：

- `active_channel` 是 `stable`。
- product version、manifest digest、四个组件的 version/commit/source/health 完整。
- Codex/Claude 中只有一个 Plugin id `evozeus`，Plugin 与 Runtime 的 channel、version、Commit 一致。
- Doctor 为 `ready` 或 `ready_after_new_session`，无 mixed channel、临时 CoEvolve source 或旧 Wrapper 地址。
- install report 的 `install_material` 是 `release_archive`，Tag、Commit 和 archive SHA-256 与正式资产一致。
- Stable 运行内不会自动写入更新。

若 Doctor 返回 `ready_after_new_session`，要求用户开启新 Agent 会话再验证，不得宣称当前会话已经热加载 Codex Plugin。

## 7. 唯一 UAT（仅在用户主动选择后）

```bash
~/.evozeus/bin/evozeus align --channel uat --host auto --json
~/.evozeus/bin/evozeus align --channel uat --host auto --approve-write --auto-refresh --json
```

UAT 使用隔离 worktree 和 `~/.evozeus/state/uat`。Bug 修复覆盖同一个 `uat/current`；不得创建 uat2、uat-fix、uat-new 或第二个用户入口。切回正式版：

```bash
~/.evozeus/bin/evozeus align --channel stable --host auto --approve-write --json
```

## 输出证据

```json
{
  "release": {"tag": "vX.Y.Z", "commit": "40-char SHA", "archive_sha256": "sha256:..."},
  "install": {"status": "dry_run | installed | reconciled | blocked", "active_channel": "stable"},
  "product_manifest": {"version": "vX.Y.Z", "digest": "sha256:..."},
  "plugin": {"id": "evozeus", "hosts": ["codex | claude"], "status": "ready | ready_after_new_session | blocked"},
  "doctor": {"verdict": "ready | ready_after_new_session | migration_required | align_required | repair_required"},
  "next_action": {"requires_user_choice": true, "allowed": ["use feature", "install single uat", "pause"]}
}
```

完成证据输出后停止。不要自动扫描 Session、运行 Factor、创建 Issue/PR、切换 UAT 或发布内容。