# 安装 Team Work 插件

本文写给 **人和 AI 都能照着做**。如果你是 AI 助手（Claude Code、Codex 等），请按顺序执行，每一步都要实际验证，不要在没验证时告诉用户「已成功」。

> 适用对象：电脑上已经装了官方 **Paseo Desktop**，想加装 Team Work 插件（无限伙伴）的同事。还没装 Paseo 的话，推荐等待或使用 [Infinity Buddy 客户端](https://buddy.infist.cn/docs/install-client.md)（Team Work 已内置）。

## 给 AI 的规则

- 只从本文给出的官方地址下载：发布清单 <https://buddy.infist.cn/downloads/releases.json>。不要下载来源不明的同名软件。
- 下载后必须校验 SHA-256，不一致就停止并告诉用户。
- 不要修改安装包里的后台地址、更新通道或插件代码；不需要管理员密码，也不要用 `sudo`。
- 飞书登录必须由用户本人完成，AI 只负责提示。
- 出错时保留完整的原始报错，按「排错」一节处理；处理不了就按「收集日志」整理给用户。
- 结束时按「完成后的汇报」格式回复用户。

## 第 1 步：确认系统和前提

| 系统 | 判断方式 | 平台标识 |
|---|---|---|
| macOS · Apple 芯片 | `uname -m` 输出 `arm64` | `darwin-arm64` |
| macOS · Intel | `uname -m` 输出 `x86_64` | `darwin-x86_64` |
| Windows 10/11 64 位 | PowerShell 中 `[Environment]::Is64BitOperatingSystem` 为 `True` | `win32-x64` |

确认 Paseo Desktop 已安装并且**至少打开过一次**：

- macOS：存在 `/Applications/Paseo.app` 或 `~/Applications/Paseo.app`。
- Windows：存在 `%LOCALAPPDATA%\Programs\Paseo\Paseo.exe`（或开始菜单里能找到 Paseo）。

如果没有 Paseo，停止安装并告诉用户：先安装官方 Paseo Desktop 并打开一次，或者使用 Infinity Buddy 客户端。不要同时运行官方 Paseo 和 Infinity Buddy。

## 第 2 步：从发布清单取最新安装器

发布清单是 JSON：`releases` 数组按新到旧排列。取**第一个**在 `artifacts.<平台标识>` 下有图形安装器（`kind` 为 `graphical-installer`，文件是 `.dmg` 或 `.exe`）的版本，记下 `version`、`url`、`fileName`、`sha256`。如果某个平台没有条目，说明暂未提供该平台的安装器，停止并告诉用户。

macOS（系统自带工具即可，无需 Python / Node）：

```bash
TARGET=darwin-arm64   # Intel Mac 改成 darwin-x86_64
eval "$(curl -fsSL https://buddy.infist.cn/downloads/releases.json | TARGET="$TARGET" osascript -l JavaScript -e '
  ObjC.import("Foundation");
  const raw = $.NSString.alloc.initWithDataEncoding($.NSFileHandle.fileHandleWithStandardInput.readDataToEndOfFile, 4).js;
  const target = $.NSProcessInfo.processInfo.environment.objectForKey("TARGET").js;
  const pick = (r) => { const a = r.artifacts && r.artifacts[target]; return a && (a.installer || ((a.kind === "graphical-installer" || /\.(dmg|exe)$/i.test(a.fileName || "")) ? a : null)); };
  const rel = JSON.parse(raw).releases.find(pick);
  if (!rel) throw new Error("没有适合 " + target + " 的安装器");
  const a = pick(rel);
  const q = (s) => "\x27" + String(s).replace(/\x27/g, "\x27\\\x27\x27") + "\x27";
  ["VERSION=" + q(rel.version), "URL=" + q(a.url), "FILE=" + q(a.fileName), "SHA256=" + q(a.sha256)].join("\n");
')"
echo "版本 $VERSION  文件 $FILE  SHA-256 $SHA256"
```

Windows（PowerShell）：

```powershell
$target = "win32-x64"
$catalog = Invoke-RestMethod -UseBasicParsing "https://buddy.infist.cn/downloads/releases.json"
$release = $catalog.releases | Where-Object { $_.artifacts.$target } | Select-Object -First 1
if (-not $release) { throw "没有适合 $target 的安装器" }
$artifact = $release.artifacts.$target
if ($artifact.installer) { $artifact = $artifact.installer }
"版本 $($release.version)  文件 $($artifact.fileName)  SHA-256 $($artifact.sha256)"
```

## 第 3 步：下载并校验

macOS：

```bash
curl -fL --retry 3 -o ~/Downloads/"$FILE" "$URL"
echo "$SHA256  $HOME/Downloads/$FILE" | shasum -a 256 -c -   # 必须输出 OK
```

Windows（PowerShell）：

```powershell
$exe = Join-Path $HOME "Downloads\$($artifact.fileName)"
Invoke-WebRequest -UseBasicParsing -Uri $artifact.url -OutFile $exe
$actual = (Get-FileHash -Algorithm SHA256 $exe).Hash.ToLower()
if ($actual -ne $artifact.sha256) { throw "SHA-256 不一致：$actual" } else { "校验通过" }
```

## 第 4 步：运行安装器

安装器只写入当前用户目录，**不需要管理员密码**；Paseo 开着也可以装，安装器会自动启动或重启 Paseo 后台服务（daemon），不会关掉 Paseo 窗口。

### macOS

```bash
hdiutil attach -nobrowse -readonly -mountpoint /tmp/team-work-installer ~/Downloads/"$FILE"
open "/tmp/team-work-installer/安装 Team Work.app"
```

在弹出的「安装 Team Work」窗口点击 **安装**，等到显示安装完成（AI 不能操作界面时，请用户点击）。完成后可以点「打开 Paseo」，再卸载镜像：

```bash
hdiutil detach /tmp/team-work-installer
```

- 用 `curl` 下载的文件通常不会触发 Gatekeeper。若用户用浏览器下载后提示「无法验证开发者」：在「系统设置 → 隐私与安全性」点击「仍要打开」。
- 提示「安装器与这台 Mac 不匹配」：芯片选错了，回到第 2 步换平台标识。

无界面的备选方式（仅当无法操作图形界面时使用，效果与点击「安装」相同）：

```bash
APP="/tmp/team-work-installer/安装 Team Work.app/Contents/Resources/payload"
WORK="$(mktemp -d)"
(cd "$APP" && shasum -a 256 -c payload.tar.gz.sha256)   # 必须输出 OK
tar -xzf "$APP/payload.tar.gz" -C "$WORK"
sh "$WORK"/team-work-plugin-*/install.sh install
```

### Windows

```powershell
Start-Process -FilePath $exe
```

在安装窗口里按提示完成即可，无需解压。如果弹出 SmartScreen「已保护你的电脑」：点击「更多信息 → 仍要运行」（安装器未做代码签名，前面已经用 SHA-256 确认来源）。安装器没有静默模式，AI 不能操作界面时请用户点击。

## 第 5 步：验证插件在运行

执行 Paseo 自带的 CLI：

macOS：

```bash
PASEO=/Applications/Paseo.app/Contents/Resources/bin/paseo
[ -x "$PASEO" ] || PASEO="$HOME/Applications/Paseo.app/Contents/Resources/bin/paseo"
"$PASEO" plugin ls --json
```

Windows（PowerShell）：

```powershell
& "$env:LOCALAPPDATA\Programs\Paseo\resources\bin\paseo.cmd" plugin ls --json
```

结果里 `team-work` 这一项必须 `enabled` 为 `true`、`status` 为 `running`。如果不是，等 30 秒再查一次；仍不是就进入「排错」。

macOS 还可以看安装器自带的状态命令（输出里应有「运行状态: running」）：

```bash
~/.paseo/plugin-data/team-work-installer/bin/team-work-installer status
```

## 第 6 步：飞书登录与首次检查（用户操作）

1. 打开 Paseo，左侧点击 **Team Work**。
2. 在「登录 Team」页面点击 **使用飞书继续**，在浏览器里完成飞书授权。
3. 回到 Paseo，Team Work 会自动运行 **完成首次使用检查**（飞书与组织身份、个人公司 Key、开发工具自动安装、Codex 线路配置、首次模型任务）。全部通过后显示「工作环境已就绪」；有失败项可点「重新检查」。

## 排错

| 现象 | 处理 |
|---|---|
| 安装器提示「这台 Mac 还没有 Paseo」/ 找不到 Paseo CLI | 先安装官方 Paseo Desktop 并打开一次，再重新运行安装器 |
| 「Paseo.app 不符合批准的 Developer ID 签名」 | 当前 Paseo 不是官方版本，请从官方渠道重新安装 Paseo |
| 「安装包校验失败」 | 删除下载的文件，回到第 3 步重新下载 |
| 「另一个 Team Work 安装正在进行」 | 等当前安装结束，或关掉其它安装窗口后重试 |
| 「Paseo daemon 启动超时」 | 打开一次 Paseo，等 1 分钟后重新运行安装器 |
| 首次加载失败 | 安装器会自动重启 Paseo daemon 并重试一次；仍失败请收集日志 |
| `plugin ls` 中 team-work 不是 `running` | 打开 Paseo 等 30 秒再查；仍不行重新运行安装器（失败时会保留旧版本，可以放心重试） |
| 飞书按钮不出现 / 登录后一直转圈 | 截图给管理员，并附上「收集日志」中的内容 |

插件要求 Paseo 0.8.0 或更新版本。

## 收集日志

安装失败时请把以下内容整理给用户（再由用户发到飞书反馈群）。**发送前删掉 token、key、cookie 等敏感内容**，不要发送整个 `.paseo` 目录。

1. 安装窗口里的日志：失败时点击 **拷贝日志**，粘贴出来。
2. 系统与芯片、安装器文件名（含版本号）、上面第 5 步命令的完整输出。
3. 日志文件最后 200 行：

macOS：

```bash
tail -n 200 ~/.paseo/daemon.log
tail -n 200 ~/.paseo/plugin-data/team-work/collaboration-agent.log
cat ~/.paseo/plugin-data/team-work/install-state.json
```

Windows（PowerShell，文件不存在可跳过）：

```powershell
Get-Content -Tail 200 "$HOME\.paseo\daemon.log"
Get-Content -Tail 200 "$HOME\.paseo\plugin-data\team-work\collaboration-agent.log"
Get-Content "$HOME\.paseo\plugin-data\team-work-installer\install-state.windows.json"
```

## 完成后的汇报

请用三行告诉用户：

1. 安装的版本号和 SHA-256 校验结果；
2. `paseo plugin ls --json` 中 team-work 的 `enabled` / `status`；
3. 用户接下来要做的事（打开 Paseo → Team Work → 使用飞书继续）。

更多问题见 [常见问题](https://buddy.infist.cn/docs/faq.md)。