# Skill Git：AI 安装与使用说明

服务器：https://agenthub.wannian.fun　版本：2.0.0-rc.12

你正在帮助用户把 Skill Git 接入当前的 AI 应用。按下面的步骤执行，每一步都检查「成功标志」，失败时按「如果失败」处理，不要跳步。

## 安全规则（必须遵守）

- 不要在对话中向用户索取密码、密钥或令牌；登录通过浏览器确认页或本机密码窗口完成。
- 只从本服务器下载客户端，下载后必须校验 sha256。
- 发布、审核通过、下架、删除、修改角色等操作会先返回预览：把预览原样展示给用户，用户明确确认后再带确认令牌重试。

## 第 1 步：下载客户端

1. 读取 `https://agenthub.wannian.fun/bootstrap/client/manifest.json`，在 `platforms` 中按 `<系统>-<架构>`（例如 `windows-amd64`、`darwin-arm64`、`linux-amd64`）找到条目，使用其中的 `url`、`size`、`sha256`。
2. 下载到：
   - Windows：`%LOCALAPPDATA%\SkillGit\skillgit.exe`
   - macOS / Linux：`~/.local/bin/skillgit`（并执行 `chmod +x`）
3. 计算文件 sha256，与 manifest 中的值比对。

成功标志：`skillgit --version` 输出版本号。
如果失败：告诉用户哪一步失败及原始错误信息；sha256 不一致时删除文件并停止。

## 第 2 步：了解用途

问用户：「这个 AI 主要用来做什么？」根据回答确定一个简短的名称（例如「写作助手」）和使用空间（例如「写作」）。不清楚时使用默认值，不要反复追问。

## 第 3 步：接入当前 AI 应用

WorkBuddy：

```
skillgit setup workbuddy --server https://agenthub.wannian.fun --name "<名称>" --spaces "<空间>"
```

成功标志：输出中包含 `client_reload=required`。
然后告诉用户：在 WorkBuddy 中重新加载 MCP 配置（命令输出中有具体的操作步骤，原样转述给用户），完成后回复你。

其他支持远程 MCP 的 AI 应用：让用户在网页「连接与密钥」中创建密钥，然后在应用中添加远程 MCP 服务器 `https://agenthub.wannian.fun/mcp`，认证方式为 Bearer 密钥。密钥由用户自己粘贴到应用的配置中，不要经过对话。

## 第 4 步：登录

调用 `login_start`。如果用户要使用指定账号，传入 `expected_login`（登录名，不是密码）。把链接和确认码交给用户，请他们在已登录正确账号的浏览器窗口手动打开链接，核对页面上的账号和确认码后点「批准」。原样发出包含 `?code=` 值的完整链接。如果打开后只看见输入框，让用户填本次的 8 位码，再在下一页点「批准」。网页明确显示「已批准」后，使用发起申请时的同一个配置按返回间隔调用 `login_status`。如果已重载，保持同一个配置即可继续，不要重新申请。必须用 CLI 排查时，执行同一 EXE 的 `skillgit doctor --profile <配置名>`，看 `device_login_status`，不要只看本机是否已有凭据。

如果用户不方便使用浏览器：执行 `skillgit login --window`，让用户在本机终端输入账号和密码（Windows 会另开一个控制台窗口；密码不经过对话）。已有密钥时也可以执行 `skillgit login --with-key`，把密钥从标准输入交给客户端，密钥不要出现在对话中。

成功标志：`login_status` 确认已连接，`me_get` 返回正确的用户和连接名称。已连接但没有看到 `me_get` 等工具时，重载 WorkBuddy 的 Skill Git MCP，再试一次，不要重新申请。

## 第 5 步：开始使用

先用 `extension_list` 搜索当前账号可见的仓库，再向用户推荐候选（名称、空间、版本）。搜索和查看详情只读目录，不拉取文件。登录不会安装任何拓展，系统 Skill 也不例外。不要执行批量同步。

- 只有用户明确指定一个拓展后才拉取：只下载用本地 `download`（保存 ZIP，不安装）或远端 `extension_download`（返回短时下载地址）；明确要求安装才用本地 `install`。三者均需传 `id`、`version`、`confirm: true`，不要擅自确认。
- 投稿本地目录：`submit_local`。用户未明确指定投稿空间时，先用 `me_get` 的 `capabilities.submit_spaces` 与 `spaces` 对照，只询问有投稿权限的空间。只有个人空间可投稿时，就问是否投到个人空间。用户明确选择后再上传文件。
- 查看待审核：`proposal_list`（参数 `review: true`）；审核：`proposal_review`
- 不确定能做什么时，调用 `me_get` 查看能力列表（capabilities）

所有操作也可以在网页 https://agenthub.wannian.fun/app/ 中完成。

## 投稿 MCP 前的审核与备注

先确定要支持的操作系统、架构和宿主，再用 `submission_digest` 生成待上传 ZIP 并取得 `archive_path` 和 SHA-256。每轮把 ZIP 路径、摘要和目标环境交给一个新开的独立子代理。子代理先核对 ZIP 的 SHA-256，再解包到独立空白环境验证，只使用 ZIP 内文件和已声明的环境依赖。

- **可用性**要从干净目录按包内配置安装启动，实测 MCP 握手、工具列表及一个代表性工具。只靠手改本机配置才能运行时，先修包。
- **兼容性**逐项写明目标系统、架构、宿主和运行时，以及「实测通过」「不支持」「未验证」。明确宣称支持的环境出现启动或功能问题时，先修复，或与用户确认缩小支持范围。

审核失败由主代理修改，再生成 ZIP 和摘要并另开子代理复审。最多三轮，含首次。空回执、超时或缺少明确结论都计入一轮，下一轮另开独立子代理复核同一份 ZIP；没有审核结论时不得提交。第三轮仍有阻塞，或宿主不能开子代理时，暂停投稿并说明。通过后，在 `submit_local` 中把审核通过的摘要作为 `reviewed_sha256` 提交。内容变化会被客户端拒绝，请重审。

Skill 和 MCP 都可把平台限制写进「说明」，并在版本 README 补充依赖和已知限制。例如「仅 Windows x64，已在 WorkBuddy 实测。Linux 不支持，macOS 未验证」。

## 检查和更新客户端

在 WorkBuddy 里说「检查 Skill Git 更新」，调用 `check_update`，回报实际运行的版本、路径和本站已发布的版本。正常使用 Skill Git 工具时，本地客户端每天首次使用会检查一次，默认仅提示；不在后台轮询。

用户说「更新 Skill Git」时，先检查版本，告知目标并征得明确确认，再调用 `update_client`。用户明确要求开启或关闭自动安装时，调用 `set_auto_update`。开启后，本地客户端每天首次使用会检查并尝试安装校验通过的新版，不安装业务拓展。安装后提示用户重载 WorkBuddy MCP，再用 `check_update` 确认新进程的运行版本。若 Windows 报文件占用或旧 MCP 不提供更新工具，请让用户退出旧进程后用原 EXE 先运行 `skillgit update --check`，核对目标版本，再运行 `skillgit update --version <目标版本> --confirm`，或按第 1 步下载替换。不得自动关闭宿主或改动其信任设置。

## 命令行命令

在对话中需要执行命令时使用下面这些命令，参数以本机实际情况为准：

| 命令 | 作用 |
| --- | --- |
| `skillgit setup workbuddy --server https://agenthub.wannian.fun --name "<名称>" --spaces "<空间>" --project "<项目路径>"` | 写入 WorkBuddy 的 MCP 配置（先备份），输出 `client_reload=required` |
| `skillgit login` | 设备确认登录；打印确认链接并轮询 |
| `skillgit login --window` | 在本机终端输入账号和密码（密码不经过对话）；Windows 会另开一个控制台窗口 |
| `skillgit login --with-key` | 从标准输入读取已有密钥（不回显） |
| `skillgit whoami` / `skillgit status` | 查看当前身份与连接 |
| `skillgit search "<关键词>"` | 搜索可见的拓展 |
| `skillgit download <拓展 ID> <版本>` | 只下载一个 ZIP 并核对摘要，不安装 |
| `skillgit install <拓展 ID> <版本>` | 只安装用户指定的拓展版本，不自动改用最新版 |
| `skillgit list` | 列出已安装的拓展 |
| `skillgit uninstall <拓展 ID> <版本>` | 卸载拓展 |
| `skillgit submit "<目录>" --space <空间 ID> --kind skill --name "<名称>" --version 1.0.0 --summary "<说明>"` | 把本地目录打包投稿；只接受目录，ZIP 请先解压 |
| `skillgit discover --scope user\|project` | 查找本地的 Skill 目录 |
| `skillgit key create --label "<名称>"` | 创建 API 密钥并写入本地文件；文件路径以命令返回的 `path` 为准（Windows 在 `%LOCALAPPDATA%\SkillGit\keys\`） |
| `skillgit doctor --profile <配置名>` | 检查连通性、凭据和宿主配置；如有待确认申请，查询并领取已批准的凭据 |
| `skillgit update --check` | 仅查看实际运行版本、路径和已发布版本，不安装 |
| `skillgit update --auto on` / `--auto off` | 开关每天首次使用时的自动安装 |
| `skillgit update --version <目标版本> --confirm` | 下载并校验新版本后替换自身 |

每条命令都支持 `--json`，输出可供解析的 JSON。
