# UndoAI 本地 Agent 安装协议

官方安装页：https://publish.undoai.cn/skills/publish-self-hosted-content

稳定版清单：https://publish.undoai.cn/.well-known/undoai-skills/publish-self-hosted-content/stable.json

## 已有安装

先读取 `~/.undoai/installations/publish-self-hosted-content.json`，使用回执管理的 CLI，而不是随意选 PATH 中的同名程序。运行 `--json skill status`，再按需执行 `--json skill update`。不要先把下载的二进制覆盖到正在使用的受管 CLI。Windows 的更新可能返回等待重启状态，必须完成替换后再验收。

## 首次安装的签名引导

1. 从上述官方 HTTPS 安装页的 `undoai-skill-signing-key` 与 `undoai-skill-signing-fingerprint` 元数据取得信任锚。公钥 Base64 解码为 32 字节；指纹为这些字节的 SHA-256 小写十六进制。仅信任清单内自带公钥不构成验证。
2. 读取 JSON 清单，要求 schema_version 为 `1`、name 为 `publish-self-hosted-content`、channel 为 `stable`。不得接受未知结构并猜测签名算法。
3. 签名内容是 Go `Manifest.SignableBytes` 的紧凑 UTF-8 JSON，不是对格式化 JSON 原文签名，也不是将所有键按字母排序。顶层字段顺序为：`schema_version,name,channel,version,released_at,changelog_url,capabilities,skill,cli,host_targets,signing`。`capabilities` 数组按字符串升序排序，其余数组保持原序。
4. 子对象字段顺序：skill=`url,sha256,size`；cli=`version,min_version,assets`；每个 CLI asset=`os,arch,url,sha256,size`；每个 host_target=`host,install_path`；signing=`algorithm,key_id,public_key,fingerprint,signature`。若存在非空 `secondary_signatures` 数组，将其置于 signing 最后；数组内每项沿用 signing 前五字段顺序。所有 `signature` 字段置为空字符串，但保留字段。
5. 使用标准 JSON 双引号与转义、无额外空白或尾换行；字符串中的 `<`、`>`、`&`、U+2028、U+2029 使用 Go JSON 的 `\u` 转义。released_at 使用清单中的标准 RFC3339 UTC 时间。签名是原清单 signature 的 Base64 解码值；以可信公钥对上述字节执行 Ed25519 验证。使用平台已有的可信加密实现；不能验证时报告阻塞，不跳过。
6. 只选择实际 OS/CPU 的 CLI。URL 必须匹配 `https://publish.undoai.cn/releases/cli/<cli.version>/<os>/<arch>/publishctl`（Windows 为 publishctl.exe）。下载后核对字节数和 SHA-256；Skill ZIP 同样核对。所有重定向也必须保持官方 HTTPS 源。
7. 将已校验的 CLI 放入用户级 `~/.undoai/bin/publishctl`，Windows 为 `%USERPROFILE%\.undoai\bin\publishctl.exe`，不写系统目录。macOS/Linux 设置用户可执行权限，然后用完整路径执行 `--json skill install`。CLI 会再次验证并原子安装完整 Skill。

## 宿主配置

- Kimi Code、本地 Codex、本地 Cursor：优先使用已托管的 `~/.agents/skills/publish-self-hosted-content`，在实际运行环境确认技能识别。
- Claude Code：用户级目录为 `~/.claude/skills/`；可将对应技能链接到托管目录以共享更新。不得覆盖已有目录。不能建立链接时，说明独立副本需要随更新同步。
- WorkBuddy：先检查通用目录识别；否则在「技能 → 添加技能 → 上传技能」导入完整已校验 ZIP 并启用。导入副本需要随更新重新导入。不要使用不存在的 `--host workbuddy` 或 `--host kimi` 参数。
- 如需使用 CLI 的宿主专用安装，只支持当前清单列出的 host；先检查既有回执的路径约束，不得用第二次 install 伪装成多宿主同步。

## 验收

分别报告 CLI 版本、Skill 版本、受管路径、宿主发现结果、独立导入副本的更新方式。实际调用 `--version`、`--json skill status`，打开新会话确认能读取 SKILL.md 及引用资源。没有真实宿主识别证据就标记未完成。安装不需要用户登录，也不需要发布测试站点。首次实际发布才走浏览器授权。保留用户账号配置、项目和非托管技能。