Windows 上的 Collie

如何在 Windows 11 上安装 Collie、在手机上打开它，以及排查可能出现的问题。请先阅读 安全性：按照设计，Collie 会提供对你计算机的远程 shell 访问权限。

在 Linux 和 macOS 上，collie start 可以通过 Tailscale Serve 为你将 Collie 发布到手机。Tailscale 是一项将你自己的设备连接到专用网络（称为 tailnet）的服务。

在 Windows 上，Collie 不会自动发布。Tailscale Serve 会在你的 tailnet 上为 Collie 提供一个 HTTPS 地址，在 Windows 上你需要手动运行该步骤。通过手机访问 展示了具体方法。

实验性功能。 实验性意味着维护者负责并测试 Windows 代码，但下述部分尚未全部验证。以下是完整状态： 已测试 - 在 Windows 11 虚拟机上针对发布文件的本地副本进行了包含 25 个步骤的安装、更新和回滚演练。 - 在 Windows 11 虚拟机上从公开的 v1.16.0 版本进行真实安装：install.ps1 找到了发布版本，sha256 匹配，且 collie.exe 成功运行。随后 collie start、collie status、collie doctor 和 collie stop 均正常工作。 - 在 Headscale tailnet 上通过 Tailscale Serve 经由 HTTP 访问手机：Host 检查、collie url、配对和写入控制门均正常。 尚未测试 - Windows 上两个真实版本之间的更新。 - Windows 上的 HTTPS 形式 Tailscale Serve，以及随之支持的主屏幕安装、Web Push 和麦克风。 - Windows 10、Windows Server、Windows on ARM 以及 未测试的内容 中的其他项目。 从现在开始，发布检查要求必须提供 Windows zip。只有维护者可以在发布 Linux 热修复（详情）时覆盖此项规则。

你将获得的功能

Collie 会在手机上显示终端中的 agent，以便你查看哪个 agent 需要你并进行回复。

这些 agent 运行在 Herdr 窗格中。窗格是 Herdr 内部的一个终端窗口。Herdr 是一个终端复用器，用于保持 agent 在窗格中持续运行。在 Windows 上，Herdr 是唯一受支持的复用器。

Collie 可以读取诸如 Claude Code、Codex、OpenCode、pi 和 omp 等 agent。agent 本身必须在 Windows 上运行。具体哪些 agent 支持取决于 agent 本身，与 Collie 无关。

开始之前

你需要准备：

• —
  x64 架构的 Windows 11。 此处的 Windows 不包括 WSL。在 WSL 内部，请遵循 安装 中的 Linux 安装说明。
• —
  PowerShell。 Windows 11 自带的 Windows PowerShell 5.1 即可满足要求。
• —
  适用于 Windows 的 Herdr 0.9.3 或更高版本。 下方的步骤 1 会安装它。Herdr 项目提供其 Windows 构建版本，Collie 依赖于它。
• —
  一部手机 配备浏览器、iPhone 或 Android 手机。
• —
  一个免费的 Tailscale 账号。 首次登录 Tailscale 应用时创建。PC 和手机必须登录到同一个账号。手机通过它连接 PC，步骤 6 将进行相关设置。

检查智能应用控制是否开启，因为它可能会阻止 collie.exe。打开 Windows 安全中心，依次进入 应用和浏览器控制 和 智能应用控制设置。它有三种状态：

如果处于开启状态，请先阅读 未签名的二进制文件。其中列出了可选方案。

从零到手机访问

按顺序执行以下步骤。列表后说明了每一步执行后应看到的内容。若要在运行安装脚本前查看其内容，请参阅 安装。

1. 01
   使用 Herdr 自带的安装程序安装 Herdr，然后检查版本：

   irm https://herdr.dev/install.ps1 | iex
   herdr --version

1. 01
   使用 Collie 的安装程序安装 Collie：

   irm https://colliepwa.dev/install.ps1 | iex

1. 01
   打开一个新终端并在其中启动 Herdr，保持该终端处于打开状态：

   herdr

1. 01
   打开第二个终端或一个新的 Herdr 窗格，然后启动 Collie 并输出其地址：

   collie start
   collie url

1. 01
   在 Herdr 窗格中启动您的 agent，例如 Claude Code：

   claude

1. 01
   使用 通过手机访问 为手机提供访问入口，该项目在 Windows 上仅通过 HTTP 运行。在执行其 tailscale serve 命令之前，只有这台 PC 可以访问 Collie；执行之后，tailnet 上的每台设备都可以访问，直到完成配对。

1. 01
   在手机浏览器中输入该地址，或者发给自己，然后将 Collie 添加到主屏幕，如 在手机上打开 所示。

1. 01
   在 PC 上运行以下命令配对手机：

   collie pair

每一步后应看到的内容：

1. 01
   Herdr 输出其安装程序日志。herdr --version 输出 0.9.3 或更新版本。本页面不提供 Herdr 专属命令，因为安装程序由 Herdr 项目维护。如果此处安装失败，请打开 herdr.dev 并按照其 Windows 步骤操作。
2. 02
   脚本会输出每个步骤。结尾处有一行以 OK Collie 开头的内容以及后续步骤列表，列表依次为 Next steps. This script does not take them for you:、1. Open a NEW terminal window. 和 3. Start Collie, then print its address:。若要先查看脚本内容，请参阅 安装。

   不会启动任何服务，也没有进程常驻后台。脚本仅运行一次 collie.exe version 以检查 Windows 是否允许其运行，仅此而已。

3. 03
   Herdr 启动并接管该终端。需要新终端是因为 Windows 仅向安装完成后新打开的窗口应用新的 PATH。
4. 04
   需要第二个终端是因为 Herdr 占用了第一个终端。collie start 会输出 Collie 正在运行 横幅，并提示 Collie 在此处未发布入口。入口是指位于 Collie 前端、供手机打开的 HTTPS 地址。Windows 上出现该提示属正常现象：步骤 6 会手动完成这一部分。在安装 Tailscale 之前，它还会在 stderr 输出此行：error: 'tailscale status' named no host for this node。此时出现该行是正常的，步骤 6 之后便不再出现。
5. 05
   Agent 在窗格中启动。Collie 会在控制面板中显示它。
6. 06
   tailscale serve status 显示您的 tailnet 地址，collie url 会将其输出。在此步骤之前，collie url 可能会输出本地环回地址（127.0.0.1），该地址仅本台 PC 可打开。您可以在本台 PC 的浏览器中打开它以查看控制面板。
7. 07
   手机显示 Collie 控制面板。等待您操作的窗格排在最前。
8. 08
   collie pair 输出一个 8 字符代码，接着输出类似 single-use · expires <time> (10 minutes) 的一行内容，然后输出一个二维码。在手机的主屏幕打开 Collie 应用，输入该代码。随后手机即完成配对。

安装

install.ps1 执行的操作，以及可更改的配置。

irm https://colliepwa.dev/install.ps1 | iex

若想在运行前查看脚本，请将其保存为文件，打开查看后再运行：

Invoke-WebRequest -OutFile install.ps1 https://colliepwa.dev/install.ps1
notepad install.ps1
powershell -ExecutionPolicy Bypass -File .\install.ps1

install.ps1 不需要 Bun、Git，也不需要 bash。它会检查最新的 5 个版本，选取第一个包含 Windows zip 的版本，校验其 sha256 并在不匹配时停止。sha256 是该文件的指纹。脚本会打印每一步操作，且绝不请求管理员权限。如果没有版本包含该 zip，它会以 下文有说明 状态停止。

默认执行策略 Restricted 是 Windows 用来限制哪些脚本可运行的规则，它会拒绝运行下载的脚本文件。“先查看脚本”变体的最后一行会为该次运行设置 Bypass。Unblock-File .\install.ps1 是另一种方式。irm ... | iex 形式直接运行脚本内容，不需要进行此设置。

脚本会将发布版本放入 %LOCALAPPDATA%\collie\versions\<version>，将 current 联接指向它，并将 current\bin 添加到用户的 PATH。联接是 Windows 的文件夹链接，current 始终指向当前运行的版本。脚本会运行一次 collie.exe version，以确认 Windows 允许其运行。它不会启动任何其他内容。再次运行不会更改任何内容，并指向 collie update。

zip 文件也位于 GitHub 的每个发布页面中，放在其 .sha256 文件旁。请使用脚本安装，不要手动安装 zip。

collie start 会注册名为 herdr.collie 的任务计划程序任务。任务计划程序是 Windows 用于在指定时间或事件运行作业的程序。该任务会在你登录时以受限令牌启动 Collie，即不具有管理员权限。

该任务会运行一个 launcher。launcher 是一个小型程序，如果 bridge 异常退出，它会重新启动 bridge。bridge 是运行在 PC 上并向手机提供网页服务的 Collie 程序。

通过手机访问

“从零到手机”的第 6 步完整说明。这些步骤与 Linux 和 macOS 上的手动操作步骤相同。本项目曾通过 HTTP 在 Headscale tailnet（Headscale 是自建的 Tailscale 服务器）上，使用调至手机尺寸的桌面浏览器在 Windows 上运行过一次。下文中的 HTTPS 形式未曾运行过，也未曾使用真实的手机或 agent。如果某一步骤失败，请提交报告（其中）。

注意。 从执行 tailscale serve 命令（下文第 3 步）开始，直到完成设备配对，Collie 对 tailnet 上的所有设备开放，它们可以查看并在你的窗格中输入内容。在该命令之前，只有这台 PC 可以访问 Collie。请在之后立即执行手机端步骤和 collie pair。如果其他人共享你的 tailnet，请立即配对，并阅读 安全性 了解如何限制可访问 Collie 的人员。

1. 01
   在 PC 和手机上安装 Tailscale，并在两端登录同一个账号：tailscale.com/download。

1. 01
   在 Tailscale admin console 中，打开 DNS，启用 MagicDNS，然后选择 启用 HTTPS。

1. 01
   在 PC 上的新终端中，在 tailnet 上发布 Collie 的本地端口（默认为 8787）：

   tailscale serve --bg --set-path=/ 8787

1. 01
   如果 Collie 配置文件夹不存在，请创建它，然后打开其 .env 文件：

   New-Item -ItemType Directory -Force "$env:APPDATA\herdr\plugins\config\herdr.collie"
   notepad "$env:APPDATA\herdr\plugins\config\herdr.collie\.env"

1. 01
   在文件末尾添加以下两行（替换为你自己在第 3 步中获得的名称），然后保存：

   COLLIE_PUBLIC_HOSTS=myhost.tail1234.ts.net
   COLLIE_PUBLIC_URL=https://myhost.tail1234.ts.net

1. 01
   重启 bridge，然后输出地址：

   collie restart
   collie url

Collie 仅在这台 PC 上监听，使用只有这台 PC 可以访问的环回地址。在 Linux 和 macOS 上，collie start 会替你运行 Tailscale Serve。这就是“托管前门”的含义：Collie 会自行发布地址。在 Windows 上，collie start 不会执行此操作，因此你需要自行运行 Tailscale Serve。

在第 3 步中，Tailscale 会输出一行带有类似 https://myhost.tail1234.ts.net 地址的信息。名称是 https:// 之后的部分。复制该名称。tailscale serve status 显示相同的地址：

https://myhost.tail1234.ts.net (tailnet only)
|-- / proxy http://127.0.0.1:8787

该命令与 Linux 和 macOS 上 collie start 为你运行的命令相同。--set-path=/ 会替换这台 PC 在 tailnet 上已于 / 提供的所有服务。

注意。 在 Headscale tailnet 上，第 3 步中的 HTTPS 命令会失败并显示 error enabling https feature: error 501 Not Implemented，因为 Headscale 不签发 HTTPS 证书。在发布之前，collie doctor 会在其 front-door 行显示警告：this tailnet has no HTTPS certificates, so an https front door cannot be published。此时请通过 HTTP 发布，这也是本项目在 Windows 上运行的形式：tailscale serve --bg --http=80 --set-path=/ 8787。它在 tailnet 端口 80 上发布，因此地址为 http://<name>，不带端口。在 COLLIE_PUBLIC_URL 中使用该 http:// 地址。执行该命令后，front-door 行通过。在 1.16.0 中它会保留该警告。此处可以使用普通 HTTP，因为 Tailscale 会加密 tailnet 设备之间的通信 (WireGuard)，且 HTTP 跃点保留在 tailnet 内部。切勿使用 tailscale funnel。通过 HTTP 时，添加到主屏幕、Web Push 和麦克风功能保持停用。在 Linux 和 macOS 上，Collie 自身的 HTTP 模式会改为在 bridge 端口上发布 (COLLIE_SERVE_MODE)。Collie 在 Windows 上不运行 Serve，因此该变量在此处不会改变发布行为。

在启用了 HTTPS 的 tailnet 上，Tailscale 会为该地址提供手机信任的证书。在 Headscale 上，请参见上文的“注意”。添加到主屏幕、Web Push（发送到手机的通知）以及麦克风功能都需要 HTTPS。通过普通 HTTP 时，它们保持停用状态（语音输入与 Web Push）。

在第 4 步中，如果文件不存在，记事本会询问是否创建该文件。点击 是。该文件夹是 herdr.collie 的 Herdr 插件配置文件夹，默认为 %APPDATA%\herdr\plugins\config\herdr.collie。Collie 会向 Herdr 索取该路径，因此 herdr plugin config-dir herdr.collie 会将其输出。

COLLIE_PUBLIC_HOSTS 是 Host 检查：Collie 会读取每个请求中的网站名称，并拒绝不在该列表中的任何名称，以防止网页通过 DNS 重绑定访问它。COLLIE_PUBLIC_URL 是 collie url 和 collie pair 的二维码输出的地址。请使用全名打开 Collie：Host 检查会拒绝 tailnet IP 地址和短名称。Collie 在启动时也会尝试自行查找 tailnet 名称。这两行配置可以确保无误。

Collie 在 Windows 上不管理此映射。collie stop 和 collie uninstall 会保留该映射。tailscale serve status 会显示它，而 tailscale serve reset 会清除 PC 上的所有 Serve 映射。切勿使用 tailscale funnel：Funnel 会将 Collie 暴露在公网上。

如果你更倾向于使用反向代理（转发 Web 请求到 Collie 的程序）或其他隧道，部署 介绍了各种变体。即使用 变体 C，并将 COLLIE_PUBLIC_HOSTS 设置为你手机访问的名称。第一次执行 collie start 不会弹出防火墙提示，因为 Collie 仅在这台机器上监听。

在手机上打开

1. 01
   将 collie url 中的地址获取到手机上：手动输入或发送给自己。在 iPhone 上使用 Safari 打开。在 Android 手机上使用 Chrome 打开。手机上需要安装 Tailscale 应用并登录到你的 tailnet。
2. 02
   将 Collie 添加到主屏幕，以便像应用一样全屏打开：- iPhone： 在 Safari 中，轻点 分享，轻点 添加到主屏幕，然后轻点 添加。- Android： 在 Chrome 中，打开 Collie 设置，轻点顶部卡片上的 安装。
3. 03
   通过新图标打开 Collie。
4. 04
   在应用中，打开 设置，然后打开 系统，再打开 已配对的设备。
5. 05
   在 PC 上运行 collie pair，输入配对码和一个名称，然后点击 配对该设备。

在通过图标打开的应用中输入配对码。不要扫描 collie pair 输出的二维码：相机应用会在浏览器标签页中打开它，而在 iPhone 上，添加到主屏幕的应用拥有独立于 Safari 的自身存储，因此在标签页中完成的配对不会同步过去。

配对码有效期为 10 分钟且只能使用一次。如果配对码过期，请重新运行 collie pair。完成配对后，上述“注意”中提到的开放访问状态（配对设备）即告结束。

常用命令

在任意终端中运行这些命令。各命令的行为与在 Linux 和 macOS 上一致，只有下方列出的 Windows 注意事项除外。

更新

从终端或手机进行更新，操作与 Linux 和 macOS 相同：

collie update

更新流程会拉取发布版本、替换 collie.exe、重启 bridge 并检查其是否有响应。如果无响应，Collie 会在约一分十五秒内回退到之前可用的版本。手机上的 Update 按钮执行相同的流程。

若要手动回退，请运行此命令。它不需要网络。它将 current 指向磁盘上仍保留的最新历史版本，并重启 bridge。如果该版本未能正常启动，Collie 会恢复到原版本且不作任何更改：

collie update --rollback

旧版本文件夹可能会保留在 versions\ 中，直到启动器重启，因为 Windows 不会删除正在运行的程序占用的文件夹。下一次更新会将其删除。

注意。 源码检出目录在 Windows 上从不自行更新：collie update 和手机上的按钮会输出一句话说明这一点，且不作任何更改。在首个 zip 包发布之前完成的所有 Windows 安装均为源码检出。迁移到 zip 安装是一次性手动操作：运行 collie uninstall 删除旧任务，然后运行 install.ps1。完成之后，collie update 即可正常工作。

Collie 在每台 Windows 机器上只允许一个安装实例，且 collie start 会拒绝运行另一个实例的任务，这也是必须先删除旧任务的原因。你也可以保留源码检出并手动更新：拉取更新的 tag，运行 bun run build，然后运行 collie restart。构建需要 Git for Windows 的 bash。

低于及等于 v1.15.0 的版本无法替换正在运行的 collie.exe，并会失败报错 EPERM。该修复（PR 309）最初在 v1.15.1 中发布。后续的 Windows 更新工作（例如 Windows 上的手机端 Update 按钮）最初在 v1.16.0 中发布。

卸载

collie uninstall

collie uninstall 会停止 bridge 并删除任务计划程序任务。它会保留安装文件夹、你的 .env 以及用户 PATH 条目，正如所有安装都会保留其文件一样。随后它会输出另外两行供 PowerShell 执行的命令。第一行删除安装文件夹。第二行通过注册表仅从你的用户 PATH 中删除 current\bin。Collie 输出的两行各占一行，其中包含你的实际文件夹路径。它们如下所示（此处换行以供排版）：

cmd /c rmdir /s /q "<install folder>"
$k = [Microsoft.Win32.Registry]::CurrentUser.OpenSubKey('Environment', $true)
$k.SetValue('Path', (($k.GetValue('Path', '', 'DoNotExpandEnvironmentNames') -split ';' |
  Where-Object { $_.TrimEnd('\') -ne '<install folder>\current\bin' }) -join ';'),
  $k.GetValueKind('Path'))
$k.Close()

尽量直接复制 Collie 自身输出的命令行。Collie 不会删除你手动创建的 tailscale serve 映射（通过手机访问）。

故障排查

先运行 collie doctor，然后在下方找到你的问题。

collie doctor 会检查安装情况，并为发现的每个问题输出修复建议。然后阅读下方与你所见现象相符的小节。如果都不相符，请查看 日志 中说明的日志。

若要报告问题，请在 github.com/AltanS/collie/issues 提交 issue。说明你使用的是 Windows，提供通过 collie version 获取的 Collie 版本，并粘贴 collie doctor 的输出及日志的最后几行。提交前请先删除所有私密内容。日志中可能包含窗格文本。

未签名的二进制文件：SmartScreen 和 Smart App Control

collie.exe 未签名，因此 Windows 无法识别其发布者。运行安装程序前请先阅读本说明。

有两项 Windows 功能可能会阻止未签名的程序：

• —
  SmartScreen 会在运行来自互联网的程序前发出提示。对于在浏览器中下载的文件，请依次点击“更多信息”和“仍要运行”。
• —
  Smart App Control 不支持基于单个文件的放行。如果它处于开启状态并拦截了 Collie，你无法仅放行那一个文件。install.ps1 在运行 collie.exe version 时会显示拦截信息，且不会输出成功提示行。

如果 Smart App Control 拦截了 Collie，你可以按以下顺序选择：

1. 01
   检查它是否开启：打开“Windows 安全中心”，然后打开 应用和浏览器控制，再打开 智能应用控制设置。
2. 02
   从源码构建（从源码构建），这会在你自己的机器上生成 collie.exe。未在开启 Smart App Control 的机器上测试过此操作。
3. 03
   请使用关闭了 Smart App Control 的 PC，或者在 issue 中反馈该拦截问题。
4. 04
   最后，关闭 Smart App Control。此操作较难撤回：Microsoft 文档曾说明重新开启可能需要重置 Windows，因此请先阅读 Microsoft 当前的页面说明。

install.ps1 中的 sha256 校验能够发现文件损坏或下载文件被替换的问题。它无法证明文件的发布者是谁，因为哈希值就存放在 zip 文件旁，能够替换其中一个的人同样可以替换另一个。为二进制文件签名是后续可能推进的步骤，目前暂无明确时间表。

长路径

表现形式： 窗格未打开，且 Herdr 提示 The directory name is invalid (os error 267)。collie doctor 会先发出警告：LongPathsEnabled is 0 on this machine。

除非启用 Windows 长路径，否则 Herdr 无法在路径长于 260 个字符的文件夹中启动窗格。当安装文件夹本身过长时，collie doctor 也会发出警告。

在以管理员身份运行的 PowerShell 中执行：

Set-ItemProperty -Path 'HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem' `
  -Name LongPathsEnabled -Value 1

Windows 可能需要重启才能让已经在运行的程序检测到该更改。无论如何，请尽量保持工作文件夹路径简短。

任务计划程序拒绝标准用户

表现形式： collie start 失败并报错 error: schtasks /Create /TN herdr.collie failed，Windows 报告 0x80070569，Collie 提示该帐户缺少“作为批处理作业登录”的权限。

这会影响从未拥有该权限的标准用户帐户。管理员帐户通常拥有该权限。

管理员授予该权限的步骤：

1. 01
   运行 secpol.msc。
2. 02
   打开“本地策略”，然后打开“用户权限分配”。
3. 03
   打开 作为批处理作业登录，并添加该帐户。
4. 04
   重新运行 collie start。

Windows Home 不自带 secpol.msc。

机密文件

表现形式： collie doctor 会打印一行 secrets-private（例如 can be read by other accounts）并附带修复方法。

Collie 会限制谁可以读取其机密文件：仅限你的账户、SYSTEM 和 Administrators。Windows 没有 0600 模式，因此 Collie 会设置其状态和配置文件夹的访问控制列表 (ACL)。

collie doctor

secrets-private 行有三种结果：

网络共享、FAT 或 exFAT 卷上的文件夹属于“not checked”，因为没有可读取的列表。请将状态和配置文件夹保留在本机的 NTFS 驱动器上。

bridge 启动时会修复权限宽松的文件夹，但仅限 Collie 刚刚创建的文件夹、用户配置文件中的默认文件夹，或者为空/仅包含 Collie 自身文件的文件夹。对于任何其他文件夹，仅会检查并发出警告，并提供修复该问题的 icacls 命令。collie doctor 和其他命令不会做出任何更改。

若要撤消修复：在修复前，bridge 会将旧列表保存在状态文件夹中的 acl-backups 里并打印撤消命令。在以管理员身份运行的终端中执行它：

icacls <folder> /restore <backup file>

COLLIE_NO_ACL_REPAIR=1 会关闭所有更改。Collie 仍会进行检查并发出警告。有关规则的完整说明见 Windows 上的机密文件。

日志

bridge 日志为插件配置文件夹中的 collie.log（默认为 %APPDATA%\herdr\plugins\config\herdr.collie\collie.log）。collie logs 会打印其末尾几行。Collie 仅对其执行追加写入且从不轮转，因此只要 bridge 处于运行状态，文件就会持续增长。若要清空它，请运行 collie stop，删除该文件，然后运行 collie start。

从源码构建

Release zip 文件不需要工具链。从源码构建仍需要 Bun、Git 以及位于 PATH 中的 Git for Windows 的 bash，因为 bun run build 会调用 bash。不依赖 bash 的构建方案已在计划中，但尚未完成。

受支持的环境

单台主机：运行于 x64 上的 Windows 11，使用 Herdr 作为多路复用器。

crew 是指多台各自运行 Collie 的机器，全部展示在同一个 URL（Crew）之后。

以下限制同样有效：

• —
  Collie 允许每台 Windows 机器安装一个实例。任务名称始终为 herdr.collie。
• —
  Collie 不会轮转 collie.log（日志）。
• —
  herdr plugin install 不是 Windows 安装路径。请使用 install.ps1，然后使用 collie start。
• —
  Herdr 的操作按钮在 Windows 上不存在，因为它们需要 bash。
• —
  Herdr 的 Windows 版本由 Herdr 项目构建。Collie 依赖它，但无法控制它。

Crew

此版本中 Windows 机器无法加入 crew。collie crew invite、crew join、crew add、crew deputy、crew approve-promote 和 collie promote 在 Windows 上均拒绝执行，输出单句提示且不更改任何内容。单台 Windows 机器上的 Collie 独立工作。

从社区脚本迁移

如果运行了社区脚本会有哪些变化，以及哪些内容不会保留。

在此版本之前，Windows 运行在社区编写的脚本 contrib/windows/collie-ctl.ps1 下。现在 Collie 自行运行该任务，并且该脚本的每个动词都对应一个同名的 collie 动词。更新后，请运行一次 collie restart。如果脚本之前运行的任务名为 herdr.collie，Collie 会以相同名称接管它。在重启之前，collie status 和 collie doctor 会提示任务仍在运行旧脚本。

有两点不会继承：

• —
  自定义任务名称。 脚本允许你设置 COLLIE_TASK_NAME。Collie 不会读取它，并且任务名称始终为 herdr.collie。你以其他名称注册的任务会保留在原处，Collie 不会停止或移除它。在运行 collie start 之前请将其删除，否则会有两个监管进程启动 bridge。在 PowerShell 中运行：schtasks /Delete /TN "<your task name>" /F。
• —
  崩溃日志副本。 脚本在 bridge 失败时会保留一份日志副本。Collie 不会保留。旧副本会一直留在磁盘上，直到你将其删除。

测试方式，以及何时结束 experimental 状态

Collie 标为 experimental 的原因，供需要证据的读者参考。使用 Collie 并不需要阅读此内容。

本页面中的两个词具有固定含义：

• —
  受支持 表示维护者负责 Windows 代码并进行测试：每次推送触发 CI 运行，并在每个发布 tag 之前在 Windows 11 虚拟机上进行演练（ADR 0075）。CI 是 GitHub 上的自动化测试运行。ADR 是仓库中保存的简短决策记录。
• —
  实验性功能 表示两个正式版本之间的更新以及 HTTPS 手机访问路径尚未得到验证。

支持所基于的基础：

• —
  windows.yml 工作流属于 CI 工作流，针对每次拉取请求以及推送到 main 的每次提交，在 windows-latest 上运行 bridge、cli 和 scripts 测试。它目前尚不是必需检查项。维护者计划在连续大约十次绿灯运行后将其设为必需项。
• —
  每个版本都会使用 .sha256 文件构建 collie-<version>-windows-x64.zip。
• —
  在每个发布 tag 之前，维护者会运行一次演练（make win-rehearse）。该演练会在全新的 Windows 11 虚拟机上安装版本，从终端和手机端点执行更新，强制触发一次失败的健康检查并检验回滚。更新过程使用发布文件的本地副本。如果虚拟机不可用，则推迟打 tag。
• —
  除 CI 之外，Windows 11 是第二项基准环境，因为 CI runner 使用的是 Windows Server。
• —
  在 Windows 11 虚拟机上运行了来自公开 v1.16.0 版本的实际安装。install.ps1 找到了该版本，下载了 zip，sha256 匹配，且 collie.exe 作为 1.16.0 成功运行。collie start 注册了任务并启动了 bridge。collie status 显示运行中，collie doctor 返回状态码 0，collie stop 停止了该任务。位于 https://colliepwa.dev/install.ps1 的脚本可用，且与 v1.16.0 版本中的脚本按字节完全一致。
• —
  在 Headscale tailnet 上的 Windows 11 虚拟机中，通过 HTTP 运行了手机访问测试。tailscale serve --bg --http=80 --set-path=/ <port> 发布了 Collie。两行 .env 和 collie restart 让 collie url 和 collie start 横幅打印出 tailnet 名称。从另一台 tailnet 机器访问时，页面、/api/health 和 /api/snapshot 均按全名正常响应，而通过 tailnet IP 地址或短名发起的请求被拒绝。手机界面中的配对正常工作，配对完成后，无凭据的写入操作收到 403 "device not paired"。测试中以手机尺寸缩放的桌面浏览器替代了实体手机。
• —
  测试虚拟机上的 Smart App Control 处于评估模式，Smart App Control 和 SmartScreen 均未在此处拦截 Collie。本页面描述的是 Windows 文档中记录的内容，而非实际遇到的拦截情况。

仅当下列条件全部同时满足时，才会移除 experimental 字样：

1. 01
   发布包含 Windows zip 文件，install.ps1 上线 colliepwa.dev，并且针对正式版本完成了一次安装和一次更新。前三项已完成：v1.16.0 包含该 zip，地址可用，且安装已运行。两个正式版本之间的更新尚未完成，因为这需要第二个带有该 zip 的版本。
2. 02
   Windows 检查是分支保护中的一项必需检查。分支保护是 GitHub 的一项设置，在指定的检查通过之前会阻止合并。
3. 03
   发布门禁会读取 Windows 工作流。门禁是发布工作流的第一步，在发布之前等待测试完成。
4. 04
   对缺少 Windows zip 的容忍已关闭。正如接下来的章节所述，现在它处于关闭状态。

不包含 Windows zip 的发布版本

从现在起，发布检查要求必须有 Windows zip。仅维护者可针对 Linux 热修复覆盖此要求。发布任务在 scripts/windows-asset.ts 中检查此项。它会寻找包含该 zip 的早期稳定版本（非草稿、非预发布），v1.16.0 便是其中之一。从 2026-11-15 起，无论如何该 zip 都是强制要求的；当 GitHub 的发布列表无响应时，它也是强制要求的。唯一的例外是维护者在 Windows 构建损坏时针对 Linux 热修复设置的开关，即仓库变量 COLLIE_WINDOWS_ASSET_OVERRIDE。在该开关下创建的发布版本不包含 Windows zip。

v1.16.0 之前的发布版本没有 Windows zip。当最新发布版本没有该文件时，你会看到以下内容：

• —
  install.ps1 会查看最新的五个发布版本。对于每一个版本，它会打印 <tag> has no Windows build. Trying the next older release.。然后打印 collie install: none of the newest 5 releases of AltanS/collie carries a Windows build yet. Nothing was installed.，最后输出 Install failed. 以及一行提示你固定某个包含该文件的版本的说明。它不会更改你机器上的任何内容。要固定某个版本，请设置 COLLIE_TAG。
• —
  在 Windows 安装上运行 collie update 会显示 error: release <version> has no Windows build; try again after the next release. Nothing was changed.

若要检查，请打开 GitHub 上的 release 页面并查找名为 collie-<version>-windows-x64.zip 的文件。

未测试的内容

以下为单纯的列举，不构成任何保证：

• —
  Windows 上两个正式发布版本之间的更新。演练使用了发布文件的本地副本。
• —
  Windows 上 Tailscale Serve 的 HTTPS 形式（Headscale 返回了 501 Not Implemented），随附主屏幕安装、Web Push 和麦克风。还有一部真机手机、一个在 Herdr 窗格中运行的 agent，以及一个反向代理，用于替代 Tailscale Serve。
• —
  在 Windows 上手动执行 collie update --rollback。演练了更新失败后的自动回滚。
• —
  从源码检出切换到 zip 安装，以及手动更新源码检出。
• —
  手动安装 zip，不使用 install.ps1。
• —
  Windows 10、Windows Server、Windows on ARM，以及 Windows 上的 tmux、zellij 和 tuios。
• —
  真实的 Smart App Control 拦截，以及用于 install.ps1 的 PowerShell 7。
• —
  在启用了 Smart App Control 的机器上从源码构建。
• —
  Windows Home 上的任务计划程序（Task Scheduler）修复。此路径通过一个用户名包含空格和非 ASCII 字符的标准用户进行了验证。
• —
  真实硬件上的 FAT 卷。“未检查”这一结果已由单元测试覆盖。
• —
  第二个 Collie 任务被拒绝的情况，仅由单元测试覆盖。
• —
  资源管理器（Explorer）是否无需注销即可识别新的 PATH，以及标准用户修改 PATH 的情况。
• —
  接入真实引擎的 local-cli 语音提供商。其清理逻辑使用测试命令进行了测试：Collie 会终止该命令的进程树，但由已退出的辅助程序启动的进程可能会比它存活更久（语音输入与 Web Push）。