Hunter 启动器 0.1.12

[0.1.12] - 2026-09-23

迭代轮 I12。一句话：装好了就记住它。

起因还是用户自己的 Mac（2026-09-22 23:10）：Hunter 六个服务 6/6 健康跑着、
网页 127.0.0.1:3100 返回 200，重新打开启动器看到的却是
「欢迎使用 Hunter 启动器」。根子在判据上 —— 那时候启动器只看
~/.hunter/launcher.toml 里的一行标记，而那一行只在安装流程自己成功走完时才写；
那一次安装在启动器看来是失败的，最后是在外面修好的，没有人回来把标记补上。

变更

打开启动器先查一次现状，不再闪欢迎页。 窗口一出来是一张「正在检查 Hunter 状态」，
不到一秒就跳走。判据改成现状优先：六个容器在就是装过，标记写的是什么都不影响 ——
而且启动器会顺手把标记补上，面板顶上说一句「检测到 Hunter 已在运行，已记录为已安装」。
容器没了、上一次的数据卷还在时，会先进一页「检测到上次的数据」。

配置里那条安装记录也记全了：哪一版启动器装的、装的哪一版 Hunter、用的哪套运行时、
上一次真的看到 6/6 健康是什么时候。运行面板右侧多了「安装于」「上次正常运行」两行。
（[launcher] version 那个从 0.1.7 起就没更新过的字段，现在并进 [install] launcher_version，
每次启动都写成当前版本。）

运行面板上半部多了三层资源。 这台电脑（CPU / 内存 / 内存压力 / 系统盘）、
Hunter 运行环境（虚拟机分配与实际用量）、数据（数据库 / 数据卷合计 / 镜像），
外加一行每个服务的 CPU 与内存。

分三层是有理由的：在 macOS 上 Hunter 跑在一台只服务它的虚拟机里，
「这台 Mac 内存 92%」和「那台虚拟机内存 92%」是两件不同的事。每张卡都写着数字从哪问来的。
窗口看不见时全部停止采集（这几条命令要起子进程，没人看的时候采它只是费电）；
拿不到的每一项都显示 —，鼠标停上去能看到原因。

停止 / 启动 / 重启补全了。

• 停止：先问一句。用内置运行时的机器上多一个默认勾上的选项
  「顺便把 Hunter 的运行环境也停了（释放约 4 GB 内存）」—— 不勾的话那台虚拟机还占着内存；
• 启动：运行环境没起的话先把它起起来（顺带检查一次虚拟机的 DNS），再起容器等健康；
• 重启：可以六个一起，也可以只重启一个（容器不换，端口映射与数据卷都不动）。

操作过程中按钮置灰，下面一条条显示刚做过的事。托盘上那三项走同一条路。

电脑或运行环境重启之后，容器会自己回来。 覆盖文件给六个服务都写了
restart: unless-stopped；万一还是没回来（比如内置运行时的虚拟机停过一次），
打开启动器就会自动拉起，不需要点任何按钮。
你自己点过「停止」的那一次不算 —— 启动器记着那是你的决定。

重装之前先看一眼有没有旧数据。 安装流程在写配置之前多了一步（只读）：
问一遍 docker 有哪些数据卷、读一下数据库的大版本、看一眼 JWT_SECRET 还在不在。

数据库 + 密钥卷 + JWT_SECRET 都在、版本不比要装的这一版新时，直接沿用 ——
不删卷、不重建库、不重新生成密钥，也不会掉登录。
唯一会停下来的一种情况是你的数据比要装的这一版新（新错误码 E_DATA_DOWNGRADE）：
硬装会把数据弄坏而且没法撤销，所以停在动手之前。

命令行新增三条只读命令：--boot-state（打开启动器时那一次判定）、
--monitor（三层资源）、--data-check [--deep]（有没有上一次的数据）。

---

下载

平台	文件	说明
Windows 10/11 x64	hunter-launcher_0.1.12_x64-setup.exe（推荐）/ hunter-launcher_0.1.12_x64_en-US.msi	NSIS 安装包 / MSI
macOS 12+	hunter-launcher_0.1.12_universal.dmg	通用二进制（Intel + Apple Silicon）
Ubuntu 22.04+ / Debian 12+ x64	hunter-launcher_0.1.12_amd64.deb（推荐）/ hunter-launcher_0.1.12_amd64.AppImage	deb 约 3.8 MiB；AppImage 约 78 MiB（自带整套 WebKitGTK，这是格式的固有代价）

国内下载（腾讯云香港，不用翻墙）：
https://hunter-dl-hk-1253756459.cos.ap-hongkong.myqcloud.com/launcher/0.1.12/

GitHub 下载：https://github.com/agentpit-io/HunterLauncher/releases/tag/launcher-v0.1.12

Linux 上装 deb：

sudo apt install -y ./hunter-launcher_0.1.12_amd64.deb
hunter-launcher            # 有桌面就开界面
hunter-launcher --headless # 纯 SSH 的机器走这条

⚠ 这些包没有代码签名

Windows 代码签名证书（100–500 美元/年）与 Apple 开发者账号（99 美元/年）都要花钱，
本项目目前没有购买，所以：

• Windows：SmartScreen 会拦一下。点「更多信息」→「仍要运行」。
• macOS：会说「无法打开，因为它来自身份不明的开发者」或「已损坏」。
  右键点 .app →「打开」→ 再点一次「打开」；仍然不行就在终端里跑
  xattr -dr com.apple.quarantine "/Applications/Hunter Launcher.app"（路径里有空格，引号别漏）。
• Linux：不受影响，deb / AppImage 本来就不强制签名。

因此这个 Release 标为 prerelease（预发布）。要不要买证书、转正式版由用户决定。
详细的图文步骤在 docs/常见问题.md。

自更新的清单是签名的：updater 用的 minisign 密钥是本项目自己生成的，公钥编译在程序里，
签名验不过的更新包不会被安装。这一条与上面的代码签名是两件事。

已知问题

• AppImage 有 78 MiB，远超设计目标里写的 40 MB —— 它要自带整套 WebKitGTK，压不下去。
  介意体积就用 deb。
• .deb 装的启动器不能就地自更新（换 /usr 下的文件要 root）。点「更新」时启动器会把
  新包下到 ~/.hunter/updates/ 并给出一条 sudo apt install 命令，最后一步由你来。
  AppImage / Windows / macOS 是全自动的。
• 运行面板上「今日对话」「晨报」两张卡显示 —：hunter-community 的 api 没有对应的
  免登录接口（逐条实测过），按「拿不到就不编」的原则空着。上游接口清单在面板上可以点开看。
• Windows / macOS 只在 CI 里编译与打包通过，没有在真机上跑过。

社区反馈回应

这是启动器的第一个公开版本，还没有收到社区反馈。用得不顺手请开 issue：
https://github.com/agentpit-io/HunterLauncher/issues/new —— 启动器里「反馈」按钮能一键生成预填好的 issue，
并附一份脱敏过的诊断包（不含 key）。

Hunter 启动器 0.1.9

[0.1.9] - 2026-09-22

迭代轮 I9。这一版只有一条主线：「上次没装成功」不该让这次更糟。

起因是 0.1.8 在用户自己的 Mac 上第一次真机运行。那台机器上留着 0.1.7 装了一半的
残骸（~/.hunter/runtime 里的 docker 与 colima 都在，虚拟机从没起来过），
0.1.8 把自己上一次留下的东西认成了「你装的 Docker / Colima」，于是：

• 「没有 Docker → 装一套内置运行时」这条主线一步都没走到；
• 它执行了一条不带 profile、不带 COLIMA_HOME 的 colima start，
  在用户家目录里建出了一台和 Hunter 毫无关系的虚拟机（占 1.4 GB）；
• AI 后来把虚拟机起起来了、docker 也能用了，安装却没有接着往下走，
  界面停在「没能自动装好」；
• 那段时间里所有端口检查都问错了 Docker，端口冲突检测整条被跳过。

变更

上次装剩的东西，这次认得出来了。 启动器现在先问「~/.hunter/runtime 里那一套
是什么状态」，再问「你自己的 Docker 在不在」。文件缺几个就补齐缺的那几个
（已经下好并核过校验和的一个字节都不重下），虚拟机没起来就起它，起不来就
清掉那台虚拟机重建一次再起。新的错误码 E_BUILTIN_DOWN 专门指这件事，
不再和「你的 Docker 没开」混为一谈。

不会再碰你的 ~/.colima。 启动器发出的每一条 colima 命令都必须带指向
~/.hunter/runtime 的 COLIMA_HOME 和 --profile hunter；缺一样就在真正执行之前
被拒掉并记进审计日志。你自己装的 colima 只会被「启动它原本就有的 profile」，
绝不会替你新建虚拟机。

修好之后会自己接着装。 诊断助手（规则层或 AI）任何一步让 Docker 变得可用，
安装就自动从写配置继续往下走，不再停在失败卡片上。

全自动档下不再让你点确认。 你在授权页上选的是全自动，那么出问题之后
那些安全动作（换端口、重试、启动运行时……）由启动器自己执行 ——
把关的门一道没少，只是不再让你去按那个按钮。做了什么依然看得见：
界面上多了一块「启动器已经替你做了这几步」，一条条列出来。

端口检查问的是正确的那个 Docker。 用内置运行时时，所有 docker ps
都指向它自己的 socket；一次检查只采一遍现场（原来是五个端口各采一遍）。

修复

• 我们的残骸会把你一套好好的 Docker 弄坏：DOCKER_CONFIG 原先只要
  ~/.hunter/runtime 里有东西就指过去，于是残骸里那个坏掉的 compose 插件被用上，
  安装在「写配置」那一步失败。现在谁生效就用谁的配置。
• 自动修复时「这个办法没成」被当成了「没有别的办法」，第二条路一次都没机会跑。
• 一个计划的头一条动作失败过之后，后面那条「等它生效」会被单独拎出来干等到超时，
  而界面上说的还是头一条要做的事。
• 命令行上打出过 E_UNKNOWN: Hunter 自己那台虚拟机没起来 这种自相矛盾的话
  （错误码清单抄了三份，加新码时漏改一份）。
• E_DAEMON_DOWN / E_WSL_MISSING 两条错误提示里还写着让你去敲命令，已改写。

已知限制

• macOS 未真机验证（本项目只有 Linux 测试机）。mac 分支的代码路径已逐行审阅，
  CI 在 macOS 上跑单测并打 dmg。
• 0.1.8 如果已经在你的 ~/.colima 里建出过一台叫 default 的虚拟机，
  启动器不会替你停、也不会替你删（那是你家目录里的东西）。
  常见问题里「之前装过没成功，再装会怎样」一节写了它是什么、占多少。

---

下载

平台	文件	说明
Windows 10/11 x64	hunter-launcher_0.1.9_x64-setup.exe（推荐）/ hunter-launcher_0.1.9_x64_en-US.msi	NSIS 安装包 / MSI
macOS 12+	hunter-launcher_0.1.9_universal.dmg	通用二进制（Intel + Apple Silicon）
Ubuntu 22.04+ / Debian 12+ x64	hunter-launcher_0.1.9_amd64.deb（推荐）/ hunter-launcher_0.1.9_amd64.AppImage	deb 约 3.8 MiB；AppImage 约 78 MiB（自带整套 WebKitGTK，这是格式的固有代价）

国内下载（腾讯云香港，不用翻墙）：
https://hunter-dl-hk-1253756459.cos.ap-hongkong.myqcloud.com/launcher/0.1.9/

GitHub 下载：https://github.com/agentpit-io/HunterLauncher/releases/tag/launcher-v0.1.9

Linux 上装 deb：

sudo apt install -y ./hunter-launcher_0.1.9_amd64.deb
hunter-launcher            # 有桌面就开界面
hunter-launcher --headless # 纯 SSH 的机器走这条

⚠ 这些包没有代码签名

Windows 代码签名证书（100–500 美元/年）与 Apple 开发者账号（99 美元/年）都要花钱，
本项目目前没有购买，所以：

• Windows：SmartScreen 会拦一下。点「更多信息」→「仍要运行」。
• macOS：会说「无法打开，因为它来自身份不明的开发者」或「已损坏」。
  右键点 .app →「打开」→ 再点一次「打开」；仍然不行就在终端里跑
  xattr -dr com.apple.quarantine "/Applications/Hunter Launcher.app"（路径里有空格，引号别漏）。
• Linux：不受影响，deb / AppImage 本来就不强制签名。

因此这个 Release 标为 prerelease（预发布）。要不要买证书、转正式版由用户决定。
详细的图文步骤在 docs/常见问题.md。

自更新的清单是签名的：updater 用的 minisign 密钥是本项目自己生成的，公钥编译在程序里，
签名验不过的更新包不会被安装。这一条与上面的代码签名是两件事。

已知问题

• AppImage 有 78 MiB，远超设计目标里写的 40 MB —— 它要自带整套 WebKitGTK，压不下去。
  介意体积就用 deb。
• .deb 装的启动器不能就地自更新（换 /usr 下的文件要 root）。点「更新」时启动器会把
  新包下到 ~/.hunter/updates/ 并给出一条 sudo apt install 命令，最后一步由你来。
  AppImage / Windows / macOS 是全自动的。
• 运行面板上「今日对话」「晨报」两张卡显示 —：hunter-community 的 api 没有对应的
  免登录接口（逐条实测过），按「拿不到就不编」的原则空着。上游接口清单在面板上可以点开看。
• Windows / macOS 只在 CI 里编译与打包通过，没有在真机上跑过。

社区反馈回应

这是启动器的第一个公开版本，还没有收到社区反馈。用得不顺手请开 issue：
https://github.com/agentpit-io/HunterLauncher/issues/new —— 启动器里「反馈」按钮能一键生成预填好的 issue，
并附一份脱敏过的诊断包（不含 key）。

Hunter 启动器 0.1.11

[0.1.11] - 2026-09-23

迭代轮 I11。一句话：已经装好了就别再装。

起因还是 0.1.9 在用户自己的 Mac 上。21:39 报了「启动超时」进错误页；
22:05 根因在外部被修好，六个服务全绿、网页返回 200 —— 而界面一直到 22:50
还挂着 21:39 那张失败卡片。用户在那张卡片上唯一能点的是「重试」，
点下去的结果是：重新取 compose、重写 .env、开始重新下载 849 MB。

变更

错误页现在会自己看现状。 进了错误页之后，启动器每 20 秒只读地问一次
「Hunter 到底在不在跑」（docker compose ps + 一次本机网页请求）。
一旦六个服务全就绪、网页也打得开，界面自己回到运行面板，
并用一句人话说明刚才发生了什么。AI 或固定规则每跑完一个动作也会立刻重查一次。

「重试」先看一眼，再决定要不要装。 点重试的第一步是只读探测，然后分三种走法：

• 那一套已经在正常跑 → 什么都不做，直接告诉你「Hunter 已经在运行」；
• 只有个别服务不正常 → 只动那几个（起它 / 重启它），
  不重新取配置、不重新下载镜像、健康的容器一个都不重建；
• 这台机器上确实没有一套能用的 → 才走完整安装。

启动器自己上一次装的那一套，永远是复用或修好，不会再并出第二套占你的盘和内存。
（「本机已有另一套 Hunter 就并存换端口」那条规矩只对你自己另外装的那些成立。）

错误页多了一个「关闭」。 它只是把窗口收回托盘：不退出、不停容器、不动任何服务。
复查说没异常的时候，它就是那一页的主按钮 —— 那种情形下「重试」本来就是错的那个选择。

端口那一栏不再骗人。 诊断信息里的端口现在分三类显示：空闲 / 被 Hunter 自己占用 /
被其他程序占用。0.1.9 那份用户导出的诊断里，五个正被 Hunter 自己占着的端口
全印着「空闲」—— 送给模型的前提一错，后面的推理全是白做的。

手工敲 docker compose 也不会把端口开到局域网上。 ~/.hunter/app/.env 里
现在写着 COMPOSE_PROJECT_NAME 与 COMPOSE_FILE，在那个目录直接
docker compose up -d 会自动带上启动器的覆盖文件（端口只绑 127.0.0.1）。
启动器每次启动还会对一遍：跑着的容器绑在哪，和配置说的一不一样 ——
不一样就按配置把那几个容器收回本机。

（背景：2026-09-22 22:01 有人在这台 Mac 上手工跑了一次 docker compose -p hunter up -d，
漏了覆盖文件，五个端口在局域网里可达了约 50 分钟。）

---

下载

平台	文件	说明
Windows 10/11 x64	hunter-launcher_0.1.11_x64-setup.exe（推荐）/ hunter-launcher_0.1.11_x64_en-US.msi	NSIS 安装包 / MSI
macOS 12+	hunter-launcher_0.1.11_universal.dmg	通用二进制（Intel + Apple Silicon）
Ubuntu 22.04+ / Debian 12+ x64	hunter-launcher_0.1.11_amd64.deb（推荐）/ hunter-launcher_0.1.11_amd64.AppImage	deb 约 3.8 MiB；AppImage 约 78 MiB（自带整套 WebKitGTK，这是格式的固有代价）

国内下载（腾讯云香港，不用翻墙）：
https://hunter-dl-hk-1253756459.cos.ap-hongkong.myqcloud.com/launcher/0.1.11/

GitHub 下载：https://github.com/agentpit-io/HunterLauncher/releases/tag/launcher-v0.1.11

Linux 上装 deb：

sudo apt install -y ./hunter-launcher_0.1.11_amd64.deb
hunter-launcher            # 有桌面就开界面
hunter-launcher --headless # 纯 SSH 的机器走这条

⚠ 这些包没有代码签名

Windows 代码签名证书（100–500 美元/年）与 Apple 开发者账号（99 美元/年）都要花钱，
本项目目前没有购买，所以：

• Windows：SmartScreen 会拦一下。点「更多信息」→「仍要运行」。
• macOS：会说「无法打开，因为它来自身份不明的开发者」或「已损坏」。
  右键点 .app →「打开」→ 再点一次「打开」；仍然不行就在终端里跑
  xattr -dr com.apple.quarantine "/Applications/Hunter Launcher.app"（路径里有空格，引号别漏）。
• Linux：不受影响，deb / AppImage 本来就不强制签名。

因此这个 Release 标为 prerelease（预发布）。要不要买证书、转正式版由用户决定。
详细的图文步骤在 docs/常见问题.md。

自更新的清单是签名的：updater 用的 minisign 密钥是本项目自己生成的，公钥编译在程序里，
签名验不过的更新包不会被安装。这一条与上面的代码签名是两件事。

已知问题

• AppImage 有 78 MiB，远超设计目标里写的 40 MB —— 它要自带整套 WebKitGTK，压不下去。
  介意体积就用 deb。
• .deb 装的启动器不能就地自更新（换 /usr 下的文件要 root）。点「更新」时启动器会把
  新包下到 ~/.hunter/updates/ 并给出一条 sudo apt install 命令，最后一步由你来。
  AppImage / Windows / macOS 是全自动的。
• 运行面板上「今日对话」「晨报」两张卡显示 —：hunter-community 的 api 没有对应的
  免登录接口（逐条实测过），按「拿不到就不编」的原则空着。上游接口清单在面板上可以点开看。
• Windows / macOS 只在 CI 里编译与打包通过，没有在真机上跑过。

社区反馈回应

这是启动器的第一个公开版本，还没有收到社区反馈。用得不顺手请开 issue：
https://github.com/agentpit-io/HunterLauncher/issues/new —— 启动器里「反馈」按钮能一键生成预填好的 issue，
并附一份脱敏过的诊断包（不含 key）。

Hunter 启动器 0.1.10

[0.1.10] - 2026-09-22

迭代轮 I10。这一版只有一条主线：Hunter 自己那台虚拟机从出生起就没有 DNS。

起因是 0.1.9 在用户自己的 Mac 上真机运行。该做的都做对了 ——
认出上次装剩的东西、走你自己配的代理取到 compose、从腾讯云香港拉下 849 MB、
起容器成功、全程一次点击都不用。然后卡在最后一米：opencode 十三分钟不健康，
报了一句「启动超时」，而确定性规则认不出来。

真正的原因用日志永远看不出来：启动器自带的那份虚拟机系统镜像里没有
systemd-resolved（Ubuntu 24.04 把它拆成了单独的包，minimal 镜像不装），
而镜像里那条 /etc/resolv.conf 符号链接照旧指向它 —— 链接在，被链接的人不在。
于是那台虚拟机、以及它里面的每一个容器，解析不了任何域名。

比健康检查更要紧的是：容器连不上模型网关 —— 就算六个服务全绿，你也一句话都问不出来。

变更

虚拟机现在一定有 DNS。 启动器会在它自己那台虚拟机里把 /etc/resolv.conf
写好（lima 的网关 + 两个国内可直连的公共 DNS，数值都是实测挑的），
并装一个开机重写它的服务，所以虚拟机重启、宿主机重启之后仍然有效。
每次启动器启动、每次安装走到「检查 Docker」那一步，都会重新解析一次域名来复查 ——
不假设上一次修好了。

「容器能不能上网」成了一项必检。 镜像拉完之后，启动器会用刚拉下来的那个镜像
起一个一次性容器（用完即删、不带你的 key），从容器里真的连一次模型网关。
连不上就不算装完 —— 因为一个起得来却问不出话的 Hunter，对你没有意义。
过程流里能看见这张卡片和它的真实耗时。

已经装好的机器会自己痊愈。 0.1.10 一起来就会检查那台虚拟机的 DNS：
已经好的什么都不动（包括你自己手工改过的），还坏着的自动修好、
让已经在跑的容器重新拿一份 DNS，然后把没装完的安装接着往下走。

两个新错误码：E_RUNTIME_NO_DNS（虚拟机没有可用的 DNS）、
E_CONTAINER_OFFLINE（容器连不上模型网关）。两个都有对应的确定性规则，
认出来是零额度消耗的；跑在你自己装的 Docker 上而我们确实修不了的那一类，
会如实说清楚往哪儿查，而不是给一个没用的按钮。

命令行新增 --check-net：一条命令查完「虚拟机有没有 DNS」和
「容器连不连得上模型网关」，两项都通才返回 0。

边界没有变

启动器不会改你电脑的 DNS、hosts、代理或防火墙设置。
这一版新增的写文件动作只作用于 Hunter 自己那台虚拟机（colima-hunter），
而且只认一张逐字写死的命令表 —— 这是写在程序里的，不是一句承诺。

---

下载

平台	文件	说明
Windows 10/11 x64	hunter-launcher_0.1.10_x64-setup.exe（推荐）/ hunter-launcher_0.1.10_x64_en-US.msi	NSIS 安装包 / MSI
macOS 12+	hunter-launcher_0.1.10_universal.dmg	通用二进制（Intel + Apple Silicon）
Ubuntu 22.04+ / Debian 12+ x64	hunter-launcher_0.1.10_amd64.deb（推荐）/ hunter-launcher_0.1.10_amd64.AppImage	deb 约 3.8 MiB；AppImage 约 78 MiB（自带整套 WebKitGTK，这是格式的固有代价）

国内下载（腾讯云香港，不用翻墙）：
https://hunter-dl-hk-1253756459.cos.ap-hongkong.myqcloud.com/launcher/0.1.10/

GitHub 下载：https://github.com/agentpit-io/HunterLauncher/releases/tag/launcher-v0.1.10

Linux 上装 deb：

sudo apt install -y ./hunter-launcher_0.1.10_amd64.deb
hunter-launcher            # 有桌面就开界面
hunter-launcher --headless # 纯 SSH 的机器走这条

⚠ 这些包没有代码签名

Windows 代码签名证书（100–500 美元/年）与 Apple 开发者账号（99 美元/年）都要花钱，
本项目目前没有购买，所以：

• Windows：SmartScreen 会拦一下。点「更多信息」→「仍要运行」。
• macOS：会说「无法打开，因为它来自身份不明的开发者」或「已损坏」。
  右键点 .app →「打开」→ 再点一次「打开」；仍然不行就在终端里跑
  xattr -dr com.apple.quarantine "/Applications/Hunter Launcher.app"（路径里有空格，引号别漏）。
• Linux：不受影响，deb / AppImage 本来就不强制签名。

因此这个 Release 标为 prerelease（预发布）。要不要买证书、转正式版由用户决定。
详细的图文步骤在 docs/常见问题.md。

自更新的清单是签名的：updater 用的 minisign 密钥是本项目自己生成的，公钥编译在程序里，
签名验不过的更新包不会被安装。这一条与上面的代码签名是两件事。

已知问题

• AppImage 有 78 MiB，远超设计目标里写的 40 MB —— 它要自带整套 WebKitGTK，压不下去。
  介意体积就用 deb。
• .deb 装的启动器不能就地自更新（换 /usr 下的文件要 root）。点「更新」时启动器会把
  新包下到 ~/.hunter/updates/ 并给出一条 sudo apt install 命令，最后一步由你来。
  AppImage / Windows / macOS 是全自动的。
• 运行面板上「今日对话」「晨报」两张卡显示 —：hunter-community 的 api 没有对应的
  免登录接口（逐条实测过），按「拿不到就不编」的原则空着。上游接口清单在面板上可以点开看。
• Windows / macOS 只在 CI 里编译与打包通过，没有在真机上跑过。

社区反馈回应

这是启动器的第一个公开版本，还没有收到社区反馈。用得不顺手请开 issue：
https://github.com/agentpit-io/HunterLauncher/issues/new —— 启动器里「反馈」按钮能一键生成预填好的 issue，
并附一份脱敏过的诊断包（不含 key）。

Hunter 启动器 0.1.8

[0.1.8] - 2026-09-21

迭代轮 I8。这一版只有一条主线：把「让你自己动手」的地方全部删掉。

起因是 0.1.7 在用户自己的 Mac 上第一次真机运行 —— 四个组件从腾讯云香港装好了，
虚拟机起不来，最后停在一张卡片上：

请在终端里执行：brew install --cask orbstack（或者去 orbstack.dev 下载）
　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　［我执行完了，继续］

用户的原话是：「很多用户连这个都不明白」。于是这一版把这类出口从代码里清掉了。

变更

安装过程中你一次都不用点。 输 key → 授权页点一次「开始安装」，到六个服务健康为止
界面上不再出现任何需要你决定的按钮（「停止安装」那个入口留着）。原先会停下来问你的
三件事，现在启动器自己按最佳方案办，并在过程流里用一句人话说明做了什么决定、为什么：

• 要装新软件 → 按「最不打扰你」的顺序依次试（见下）；
• 这台电脑上已经有另一套 Hunter → 自动「两套并存、换一组端口」，你原来那套一点都不动
  （想改成直接用已有那套，设置页里切换）；
• 这次的额度用完了 → 不问你，改成只按固定规则继续；真装不上就自动生成脱敏诊断包。

「每一步都问我」那一档还在，挪到了设置页 → AI 助手，默认不再是它。

没有 Docker 时三条路自动依次走完，每一条都是启动器自己执行：

1. 内置运行时（装在 ~/.hunter/runtime，不用密码）
2. OrbStack 官方安装包（下 dmg → 验苹果签名与公证 → 装 → 打开 → 等 docker 就绪）
3. Homebrew —— 这台电脑上没有 brew 就先替你把 brew 装上，再 brew install --cask orbstack

排序原则是「同样能解决问题时，优先不需要任何交互的那条」，所以要密码的路线排在最后。

需要管理员权限时弹的是系统自带的密码框。 之前的承诺是「绝不使用管理员密码」，
代价是撞上要 root 的事只能把活儿丢回给你。现在改成：需要时由 macOS / polkit / UAC
自己弹授权框，弹之前界面先用一句人话说清「要做什么、为什么要密码」。
启动器不自绘密码框、不保存密码、不把密码写进日志。其余禁止项一条没放松：
不删你的文件、不改你的网络与安全设置（代理 / DNS / hosts / VPN / 防火墙 / Gatekeeper / SIP）、
不动别的项目的容器与数据、不执行模型自己编的命令。

Linux 上的启动器自更新跟着改了：.deb 以前是「包下好了，这条命令你自己去敲」，
现在是下好包 → 弹 polkit 的原生授权框 → 启动器自己 dpkg -i。

开源协议改为 Apache License 2.0（原为 MIT）。新增 NOTICE 与
THIRD_PARTY_NOTICES.md；启动器运行时下载的那些第三方程序
（Colima MIT、Lima Apache-2.0、docker CLI 与 compose Apache-2.0、Homebrew BSD-2-Clause、
OrbStack 专有）不随安装包分发，各自保留各自的许可证，不因本项目换协议而改动。

修复

虚拟机系统镜像现在由启动器自己下。 这是 0.1.7 在用户 Mac 上卡住的直接原因：
colima start 会自己直连 GitHub 去取 colima-core 的
ubuntu-24.04-minimal-cloudimg-*-docker.raw.gz（341 MB / 316 MB），那一次下载不受我们控制，
用户那台机器上直连 GitHub 十秒超时。现在这两个文件进了内置运行时的清单：
GitHub 与腾讯云香港并列择优、版本与 sha512 写死、校验不符拒绝用、下载有真实进度，
下好之后用 colima start --disk-image <本地文件> 交给 colima，它一个字节都不用自己下。

沿用你自己配好的网络代理。 用户那台 Mac 的系统设置里配着 127.0.0.1:7897，
直连 github.com 十秒超时、走代理两秒就通 —— 路是铺好的，是我们没走。现在启动器在
直连失败时会只读地读出这台机器上的代理（macOS scutil --proxy、Windows 注册表的
Internet Settings、Linux 环境变量），用它重试，并把 HTTP_PROXY / HTTPS_PROXY /
ALL_PROXY / NO_PROXY 传给 colima、limactl、docker，以及（用 colima start --env）
虚拟机里的 docker。界面上会说一句「检测到你设置了网络代理，已沿用」。
只读取，绝不修改你的网络设置。

「已自动解决 N 个问题」现在如实计数：自动换下载源、自动改走代理、自动换兜底路线，
每一次都算一个，并各自在过程流里留一行说明。

内部

• 新增一条流水线检查 scripts/check-wording.py：扫界面文案、规则层文案、动作表描述，
  出现「请在终端里执行」「复制这条命令」「我执行完了」「请你选择」「点一下继续」这类
  要用户自己动手或替我们做决定的字样，CI 直接红。它自带 9 条反例 + 8 条正当文案的自测，
  证明规则本身不是空跑。这条原则靠代码守，不靠提示词。

---

下载

平台	文件	说明
Windows 10/11 x64	hunter-launcher_0.1.8_x64-setup.exe（推荐）/ hunter-launcher_0.1.8_x64_en-US.msi	NSIS 安装包 / MSI
macOS 12+	hunter-launcher_0.1.8_universal.dmg	通用二进制（Intel + Apple Silicon）
Ubuntu 22.04+ / Debian 12+ x64	hunter-launcher_0.1.8_amd64.deb（推荐）/ hunter-launcher_0.1.8_amd64.AppImage	deb 约 3.8 MiB；AppImage 约 78 MiB（自带整套 WebKitGTK，这是格式的固有代价）

国内下载（腾讯云香港，不用翻墙）：
https://hunter-dl-hk-1253756459.cos.ap-hongkong.myqcloud.com/launcher/0.1.8/

GitHub 下载：https://github.com/agentpit-io/HunterLauncher/releases/tag/launcher-v0.1.8

Linux 上装 deb：

sudo apt install -y ./hunter-launcher_0.1.8_amd64.deb
hunter-launcher            # 有桌面就开界面
hunter-launcher --headless # 纯 SSH 的机器走这条

⚠ 这些包没有代码签名

Windows 代码签名证书（100–500 美元/年）与 Apple 开发者账号（99 美元/年）都要花钱，
本项目目前没有购买，所以：

• Windows：SmartScreen 会拦一下。点「更多信息」→「仍要运行」。
• macOS：会说「无法打开，因为它来自身份不明的开发者」或「已损坏」。
  右键点 .app →「打开」→ 再点一次「打开」；仍然不行就在终端里跑
  xattr -dr com.apple.quarantine "/Applications/Hunter Launcher.app"（路径里有空格，引号别漏）。
• Linux：不受影响，deb / AppImage 本来就不强制签名。

因此这个 Release 标为 prerelease（预发布）。要不要买证书、转正式版由用户决定。
详细的图文步骤在 docs/常见问题.md。

自更新的清单是签名的：updater 用的 minisign 密钥是本项目自己生成的，公钥编译在程序里，
签名验不过的更新包不会被安装。这一条与上面的代码签名是两件事。

已知问题

• AppImage 有 78 MiB，远超设计目标里写的 40 MB —— 它要自带整套 WebKitGTK，压不下去。
  介意体积就用 deb。
• .deb 装的启动器不能就地自更新（换 /usr 下的文件要 root）。点「更新」时启动器会把
  新包下到 ~/.hunter/updates/ 并给出一条 sudo apt install 命令，最后一步由你来。
  AppImage / Windows / macOS 是全自动的。
• 运行面板上「今日对话」「晨报」两张卡显示 —：hunter-community 的 api 没有对应的
  免登录接口（逐条实测过），按「拿不到就不编」的原则空着。上游接口清单在面板上可以点开看。
• Windows / macOS 只在 CI 里编译与打包通过，没有在真机上跑过。

社区反馈回应

这是启动器的第一个公开版本，还没有收到社区反馈。用得不顺手请开 issue：
https://github.com/agentpit-io/HunterLauncher/issues/new —— 启动器里「反馈」按钮能一键生成预填好的 issue，
并附一份脱敏过的诊断包（不含 key）。

Hunter 启动器 0.1.7

[0.1.7] - 2026-09-21

迭代轮 I7。设计文档 §十分期里原定 I6 的四项 —— 上一轮被 macOS 的 P0 抢占，本轮补齐。

新增

没有 Docker 也能零点击装完（macOS） —— 以前「这台电脑没装 Docker」要你自己去下载、
拖进应用程序、点开、过欢迎页。现在授权页上多了一项默认勾着的勾：

如果电脑上没有 Docker，允许 AI 为你安装（装在 ~/.hunter/runtime 里，不改系统，可一键卸载）

勾着的话启动器装一套完全用户态的运行时到 ~/.hunter/runtime：
Colima v0.10.3 + Lima v2.2.0 + docker 客户端 29.8.1 + compose v5.5.1。

• 版本与 sha256 写死在程序里，下完逐个核对，对不上就删掉不用 —— 不跟 latest 漂移；
• 两个下载源并列测速：GitHub / docker.com 与腾讯云香港；
• 不要管理员密码、不改系统任何地方：不写 /usr/local、不改 shell 配置、不碰你的 ~/.docker。
  虚拟机、socket、配置全在 ~/.hunter/runtime 里；
• 本机已经有 OrbStack / Docker Desktop / Colima 的话一个字节都不下（在跑就直接用，
  装了没跑就先把它点起来）；
• 设置页 →「容器运行时」→「卸载内置运行时」一键清干净，Hunter 自己的数据卷不受影响。

设置里另有一条备选路线「OrbStack 官方安装包」（下 dmg + 验苹果签名与公证 + Team ID）。
它装得更快，但首次打开 OrbStack 时 macOS 与它自己会弹欢迎页、可能要管理员密码 ——
那是系统与 OrbStack 的交互，启动器不会替你点，所以它不是默认。
（OrbStack 个人使用免费，商用需另外授权。）

Windows 装 WSL / Docker Desktop 要管理员权限，Linux 装 Docker Engine 要 sudo ——
这两条路启动器不替你提权，只把要敲的命令原样写给你，你执行完点一下就接着装。

直接用你已经装好的那一套 Hunter —— 发现本机已有别的 Hunter 时，过程流里的卡片
给两个按钮：「和它并存（推荐，不动它）」与「直接用它，不再装一套」。
这张卡片不拦着安装（并存本来就是默认），点了才改道。

选「直接用它」之后运行面板变成「正在管理你原有的 Hunter」：看容器状态、看日志、打开网页。
停止 / 启动 / 重启每一次都要你再确认一遍；启动器不会改它的配置，
任何情况下都不删它的数据卷（动作表里根本没有对它 down / -v 的路）。
读不到它的 compose 文件时如实降级成只读监控。

复核员 —— 计划里出现「需要你同意」级别的动作时，启动器会再问一次模型：
换一段完全独立的提示词、不带上一轮的对话历史、不给它任何工具，只判两件事 ——
「会不会伤到你已有的数据 / 网络 / 其他项目」「说的话对不对得上现场证据」。
过程流里单独一张「复核」卡片。否决就退回去重想（带着否决理由）。

复核通过不等于可以执行。 守卫（程序里那道硬校验）与你的确认这两道照样要过。
多一个模型把关，不是让代码那道门松一松的理由。

发送诊断给开发者 —— 修不好时的最终页新增一个按钮：在你自己的机器上生成脱敏诊断包 →
把将要贴出去的 issue 标题与正文原样摆给你看 → 你点了才打开浏览器（内容已预填）。
诊断包不会自动上传，本地路径一并给出。出口闸这一版连用户名与主机名都扫，
扫到就不给「打开 GitHub」那个按钮。

变更（会影响现在的用法，请先看这一条）

Hunter 的网页现在只有装它的那台电脑能打开。

六个服务的端口全部绑在 127.0.0.1 上（以前只有 api / opencode / postgres / redis 是，
网页端口绑的是所有网卡）。手机、平板、同一网络里的另一台电脑都打不开了。

为什么改：Hunter 的聊天界面不需要任何口令。以前只要能连到你这台机器，
打开 http://<你的 IP>:<端口> 就能直接用，烧的是你的额度 ——
这件事从 0.1.0 起就是这样，我们在 0.1.2 把开关做了出来，但默认值一直没动。

局域网访问（让同一网络的其他设备也能打开）是付费版功能，免费版里没有这个开关：
设置页「谁能打开 Hunter」那一栏现在是一行只读说明，
launcher.toml 里手写 web_bind = "all" 或 "0.0.0.0" 也不会生效 ——
覆盖文件照样按 127.0.0.1 生成，并在日志里记一条说明它被忽略了。

从旧版本升上来的机器不受影响：升级不会悄悄改动你已有的配置
（不然「昨天手机上还能开」会在你不知道的情况下突然失效）。
运行面板顶上会出现一条提示，想收紧就点「只允许本机访问」。
收紧是单向的，收完不能再放开。

改进

• 预检阶段自动换端口现在算「已自动解决 1 个问题」。0.1.6 在 Mac 上换掉了 5 个被占的
  端口、装成功了，总览那一行却写「已自动解决 0 个」—— 用户看见它发现问题、处理掉了，
  那就该算数。
• 事件流按次归档，保留最近 5 份（~/.hunter/logs/assist-events-<时间戳>.jsonl）。
  以前一开新的就把上一次覆盖掉，而排查「上一版装到哪一步失败的」要的正是那一份。
• 「找不到 Docker」时规则层先自己按已知位置硬找一遍，找到就直接写进设置。
  0.1.5 实测这一步交给模型花了 8,632 token，而且它第一轮还要求再探一次我们刚探过的东西。
• 命令行下的「逐步确认」档第一次真的能用了：stdin 是终端就把问题打出来等你输 y/n；
  是管道 / CI 就照旧按「不」处理并在开头说清楚。
• 命令行新增 --takeover list|use|status|logs|stop|start|restart|release、--feedback、
  --review。--takeover 的改动类子命令要 -y——那是二次确认在命令行下的形态。

下载

平台	文件	说明
Windows 10/11 x64	hunter-launcher_0.1.7_x64-setup.exe（推荐）/ hunter-launcher_0.1.7_x64_en-US.msi	NSIS 安装包 / MSI
macOS 12+	hunter-launcher_0.1.7_universal.dmg	通用二进制（Intel + Apple Silicon）
Ubuntu 22.04+ / Debian 12+ x64	hunter-launcher_0.1.7_amd64.deb（推荐）/ hunter-launcher_0.1.7_amd64.AppImage	deb 约 3.8 MiB；AppImage 约 78 MiB（自带整套 WebKitGTK，这是格式的固有代价）

国内下载（腾讯云香港，不用翻墙）：
https://hunter-dl-hk-1253756459.cos.ap-hongkong.myqcloud.com/launcher/0.1.7/

GitHub 下载：https://github.com/agentpit-io/HunterLauncher/releases/tag/launcher-v0.1.7

Linux 上装 deb：

sudo apt install -y ./hunter-launcher_0.1.7_amd64.deb
hunter-launcher            # 有桌面就开界面
hunter-launcher --headless # 纯 SSH 的机器走这条

⚠ 这些包没有代码签名

Windows 代码签名证书（100–500 美元/年）与 Apple 开发者账号（99 美元/年）都要花钱，
本项目目前没有购买，所以：

• Windows：SmartScreen 会拦一下。点「更多信息」→「仍要运行」。
• macOS：会说「无法打开，因为它来自身份不明的开发者」或「已损坏」。
  右键点 .app →「打开」→ 再点一次「打开」；仍然不行就在终端里跑
  xattr -dr com.apple.quarantine "/Applications/Hunter Launcher.app"（路径里有空格，引号别漏）。
• Linux：不受影响，deb / AppImage 本来就不强制签名。

因此这个 Release 标为 prerelease（预发布）。要不要买证书、转正式版由用户决定。
详细的图文步骤在 docs/常见问题.md。

自更新的清单是签名的：updater 用的 minisign 密钥是本项目自己生成的，公钥编译在程序里，
签名验不过的更新包不会被安装。这一条与上面的代码签名是两件事。

已知问题

• AppImage 有 78 MiB，远超设计目标里写的 40 MB —— 它要自带整套 WebKitGTK，压不下去。
  介意体积就用 deb。
• .deb 装的启动器不能就地自更新（换 /usr 下的文件要 root）。点「更新」时启动器会把
  新包下到 ~/.hunter/updates/ 并给出一条 sudo apt install 命令，最后一步由你来。
  AppImage / Windows / macOS 是全自动的。
• 运行面板上「今日对话」「晨报」两张卡显示 —：hunter-community 的 api 没有对应的
  免登录接口（逐条实测过），按「拿不到就不编」的原则空着。上游接口清单在面板上可以点开看。
• Windows / macOS 只在 CI 里编译与打包通过，没有在真机上跑过。

社区反馈回应

这是启动器的第一个公开版本，还没有收到社区反馈。用得不顺手请开 issue：
https://github.com/agentpit-io/HunterLauncher/issues/new —— 启动器里「反馈」按钮能一键生成预填好的 issue，
并附一份脱敏过的诊断包（不含 key）。

Hunter 启动器 0.1.6

[0.1.6] - 2026-09-21

迭代轮 I6。0.1.5 在用户 Mac 上真机验收，端口那一条修好了，却卡在下一步：
docker compose pull 一个镜像都拉不下来，而且界面上那句「原话：」后面是空的。
本轮是一次热修，原定 I6 的内容（复核员、install_runtime 等）顺延到 I7。

修复

Docker 找不到它自己的凭据助手（P0） —— 从访达 / 程序坞双击起来的启动器，
PATH 只有 /usr/bin:/bin:/usr/sbin:/sbin。I4 已经让启动器按已知位置找到了 docker，
但 docker 自己去 $PATH 上找 docker-credential-osxkeychain 时，
拿到的还是那份受限 PATH：

error getting credentials - err: exec: "docker-credential-osxkeychain":
  executable file not found in $PATH, out: ``

（用户的 ~/.docker/config.json 里有 "credsStore": "osxkeychain"，
是 OrbStack / Docker Desktop 装的时候自己写的；助手在 /usr/local/bin。）

现在所有 docker / compose 子进程都用同一套环境：
PATH = 原 PATH + docker 所在目录 + 它软链指向的目录 + 平台已知位置
（和找 docker 用的是同一份清单，去重、保序、只加真实存在的目录），
日志里记一行「补了哪些目录」。Linux 与 Windows 同样适用。

补全之后仍然找不到助手时，启动器在 ~/.hunter/docker-config/ 里另起一份
不带 credsStore 的配置给自己用（Hunter 的六个镜像都是公开的，本来就不需要登录）。
你的 ~/.docker/config.json 一个字节都不会被改 —— 这不是承诺，是路径守卫拦得住。

「原话」不再是空的 —— compose v5 把顶层错误写成
{"error":true,"message":"…"}，而 0.1.5 的解析只认另外两种形状，
于是失败原因整段丢掉了，用户和 AI 都只看到「退出码 1。原话：」。
现在三种 JSON 形状都认，stdout 与 stderr 都收；真的一个字都没输出时，
也如实说「一个字的错误都没有」，而不是留半截话。

不再在两个镜像源之间来回兜圈 —— 新错误码 E_CRED_HELPER：
本机凭据助手缺失是本机配置的问题，与下载源无关，换源永远修不好。
0.1.5 在用户机器上为此换了三次源、花了 268 秒、一个问题都没解决。
另外加了一条通用闸门：同一条失败原话只换一次源；换完原话一个字都没变，
就判定「与源无关」，把现场连同原话交给诊断员，而不是接着换。

测试

测试机上用真的 0.1.5 二进制复现了这次失败（受限 PATH + 一个找不到的 credsStore），
再用新版跑同一个现场：

现场	0.1.5	0.1.6
助手在已知位置（/usr/local/bin）	失败 · 4 回合 · 换了 3 次源 · 「原话」是空的	零点击到 6 / 6，0 个修复回合，69 秒
助手在任何已知位置之外	同上	零点击到 6 / 6，1 个修复回合，0 token，51 秒（自动另起一份配置）

两次跑完，用户已有的那套 Hunter 六个容器 ID 未变、数据卷清单与创建时间未变、
~/.docker 未被改动。

---

下载

平台	文件	说明
Windows 10/11 x64	hunter-launcher_0.1.6_x64-setup.exe（推荐）/ hunter-launcher_0.1.6_x64_en-US.msi	NSIS 安装包 / MSI
macOS 12+	hunter-launcher_0.1.6_universal.dmg	通用二进制（Intel + Apple Silicon）
Ubuntu 22.04+ / Debian 12+ x64	hunter-launcher_0.1.6_amd64.deb（推荐）/ hunter-launcher_0.1.6_amd64.AppImage	deb 约 3.8 MiB；AppImage 约 78 MiB（自带整套 WebKitGTK，这是格式的固有代价）

国内下载（腾讯云香港，不用翻墙）：
https://hunter-dl-hk-1253756459.cos.ap-hongkong.myqcloud.com/launcher/0.1.6/

GitHub 下载：https://github.com/agentpit-io/HunterLauncher/releases/tag/launcher-v0.1.6

Linux 上装 deb：

sudo apt install -y ./hunter-launcher_0.1.6_amd64.deb
hunter-launcher            # 有桌面就开界面
hunter-launcher --headless # 纯 SSH 的机器走这条

⚠ 这些包没有代码签名

Windows 代码签名证书（100–500 美元/年）与 Apple 开发者账号（99 美元/年）都要花钱，
本项目目前没有购买，所以：

• Windows：SmartScreen 会拦一下。点「更多信息」→「仍要运行」。
• macOS：会说「无法打开，因为它来自身份不明的开发者」或「已损坏」。
  右键点 .app →「打开」→ 再点一次「打开」；仍然不行就在终端里跑
  xattr -dr com.apple.quarantine "/Applications/Hunter Launcher.app"（路径里有空格，引号别漏）。
• Linux：不受影响，deb / AppImage 本来就不强制签名。

因此这个 Release 标为 prerelease（预发布）。要不要买证书、转正式版由用户决定。
详细的图文步骤在 docs/常见问题.md。

自更新的清单是签名的：updater 用的 minisign 密钥是本项目自己生成的，公钥编译在程序里，
签名验不过的更新包不会被安装。这一条与上面的代码签名是两件事。

已知问题

• AppImage 有 78 MiB，远超设计目标里写的 40 MB —— 它要自带整套 WebKitGTK，压不下去。
  介意体积就用 deb。
• .deb 装的启动器不能就地自更新（换 /usr 下的文件要 root）。点「更新」时启动器会把
  新包下到 ~/.hunter/updates/ 并给出一条 sudo apt install 命令，最后一步由你来。
  AppImage / Windows / macOS 是全自动的。
• 运行面板上「今日对话」「晨报」两张卡显示 —：hunter-community 的 api 没有对应的
  免登录接口（逐条实测过），按「拿不到就不编」的原则空着。上游接口清单在面板上可以点开看。
• Windows / macOS 只在 CI 里编译与打包通过，没有在真机上跑过。

社区反馈回应

这是启动器的第一个公开版本，还没有收到社区反馈。用得不顺手请开 issue：
https://github.com/agentpit-io/HunterLauncher/issues/new —— 启动器里「反馈」按钮能一键生成预填好的 issue，
并附一份脱敏过的诊断包（不含 key）。

Hunter 启动器 0.1.5

[0.1.5] - 2026-09-21

迭代轮 I5。用户在自己的 Mac 上装 0.1.4，启动那一步报「端口已被占用」——
根因是端口探测在 macOS 上把被占死的端口判成了空闲。本轮先把这个确定性缺陷修掉，
再把整个安装改成「一次授权，AI 自动干完，过程实时给你看」。

修复

macOS 上把被占用的端口判成空闲（P0） —— 用户电脑上早有一套 Hunter 占着
3100 / 8100 / 3921 / 5442 / 6479，启动器只把 web 3100 改成了 3101，其余四个照原样用，
docker compose up 随后报 Bind for 0.0.0.0:8100 failed: port is already allocated。

根因：std::net::TcpListener::bind 在 Unix 上默认给监听套接字开 SO_REUSEADDR，
macOS 的 BSD 语义下这个选项会让「绑 127.0.0.1:P」在「*:P 已被别人占着」时照样成功。
web 探的是 0.0.0.0 所以查对了，其余四个探的是 127.0.0.1 所以全错。
Linux 内核的行为不同，所以 I4 在测试机上四个场景全过、一上真机就炸。

现在端口探测走三重确认，任何一路说「占用」就算占用，并记下占用者是谁：

1. 用 socket2 显式构造套接字、不设 SO_REUSEADDR，0.0.0.0 / [::] / 127.0.0.1 各绑一次
   （127.0.0.1 那一条是给 Windows 的：那边的 SO_REUSEADDR 允许抢占，通配绑定不会因为「别人占着回环」而失败）；
2. docker ps 的全部已发布端口 + 所属 compose 项目名（Docker 是端口这件事的最终裁判）；
3. lsof -nP -iTCP -sTCP:LISTEN（Windows 用 netstat -ano）补充占用进程名。

起容器前的预检闸门 —— docker compose up 之前拿合并后的端口表再对一遍现场，
有冲突就先换端口，不等 Docker 报错。

端口冲突有了自己的错误码 E_PORT_CONFLICT —— 0.1.4 把
port is already allocated 归成了「启动超时」，于是规则层认不出来、AI 拿到的前提就是错的。
顺带补齐了 no space left / pull access denied / TLS handshake timeout / i/o timeout
的归类。

认得出你电脑上已有的其他 Hunter —— 镜像名含 hunter-community- 的其他 compose 项目
会被报出来（连同它用官方镜像的 postgres / redis），默认并存换端口，
界面上写清楚「启动器不会停它、不会删它」。

重试前清掉本项目的 Created 残留容器 —— 不带 -v，删之前逐个核对 compose 项目标签。

新增

一次授权 + AI 自动驾驶安装 —— 向导变成
「欢迎 → 输入 key → 一次授权 → 自动安装 → 完成」。
授权那一下之后不需要再点任何按钮（测试机实测 54–94 秒到 6 / 6 健康），
除非撞上三种必问情况：要装新软件、要动你已有的 Hunter、要超本次额度上限。

三档授权（设置页随时可改）：auto 自动驾驶（推荐）/ confirm 逐步确认 / off 关闭。

实时过程流 —— 每一件事一张卡片，写人话；右侧「详情」里是命令、原始输出、耗时、token。
顶上一行常驻：现在在干什么、自动解决了几个问题、花了多少 token、第几个修复回合。

AI 绝不会做的事，写在代码里 —— 路径 canonicalize 之后必须落在 ~/.hunter/ 内、
删除只限启动器自己生成的文件、docker 操作强制 --project-name hunter 并在执行前核对
容器的 compose 项目标签、没有任何需要 sudo 的动作、volume rm / prune / down -v /
改代理 DNS hosts 防火墙 / 任意 shell 一律不在动作表里。
每一次动作（包括被拒绝的）都写 ~/.hunter/logs/assist-audit.log，设置页里能直接看。

要管理员权限的事会请你出手 —— Linux 上 systemctl start docker 需要 root 时，
界面给一张卡片写明「请在终端里执行 sudo systemctl start docker」，
不替你提权、也不假装做过了。

其他

• hunter-launcher --auto [--assist-mode auto|confirm|off]：命令行下跑同一套自动安装，
  事件流同时落到 ~/.hunter/logs/assist-events.jsonl。
• 慢机器上健康检查的等待上限可以调长（[hunter] start_timeout_secs，180–900 秒）。
• 下载那一步现在区分「真的下载了多少」与「本机已有多少」——
  镜像已在本机时如实写「这次一个字节都没下载」，不再拿 manifest 大小冒充下载量。

---

下载

平台	文件	说明
Windows 10/11 x64	hunter-launcher_0.1.5_x64-setup.exe（推荐）/ hunter-launcher_0.1.5_x64_en-US.msi	NSIS 安装包 / MSI
macOS 12+	hunter-launcher_0.1.5_universal.dmg	通用二进制（Intel + Apple Silicon）
Ubuntu 22.04+ / Debian 12+ x64	hunter-launcher_0.1.5_amd64.deb（推荐）/ hunter-launcher_0.1.5_amd64.AppImage	deb 约 3.8 MiB；AppImage 约 78 MiB（自带整套 WebKitGTK，这是格式的固有代价）

国内下载（腾讯云香港，不用翻墙）：
https://hunter-dl-hk-1253756459.cos.ap-hongkong.myqcloud.com/launcher/0.1.5/

GitHub 下载：https://github.com/agentpit-io/HunterLauncher/releases/tag/launcher-v0.1.5

Linux 上装 deb：

sudo apt install -y ./hunter-launcher_0.1.5_amd64.deb
hunter-launcher            # 有桌面就开界面
hunter-launcher --headless # 纯 SSH 的机器走这条

⚠ 这些包没有代码签名

Windows 代码签名证书（100–500 美元/年）与 Apple 开发者账号（99 美元/年）都要花钱，
本项目目前没有购买，所以：

• Windows：SmartScreen 会拦一下。点「更多信息」→「仍要运行」。
• macOS：会说「无法打开，因为它来自身份不明的开发者」或「已损坏」。
  右键点 .app →「打开」→ 再点一次「打开」；仍然不行就在终端里跑
  xattr -dr com.apple.quarantine "/Applications/Hunter Launcher.app"（路径里有空格，引号别漏）。
• Linux：不受影响，deb / AppImage 本来就不强制签名。

因此这个 Release 标为 prerelease（预发布）。要不要买证书、转正式版由用户决定。
详细的图文步骤在 docs/常见问题.md。

自更新的清单是签名的：updater 用的 minisign 密钥是本项目自己生成的，公钥编译在程序里，
签名验不过的更新包不会被安装。这一条与上面的代码签名是两件事。

已知问题

• AppImage 有 78 MiB，远超设计目标里写的 40 MB —— 它要自带整套 WebKitGTK，压不下去。
  介意体积就用 deb。
• .deb 装的启动器不能就地自更新（换 /usr 下的文件要 root）。点「更新」时启动器会把
  新包下到 ~/.hunter/updates/ 并给出一条 sudo apt install 命令，最后一步由你来。
  AppImage / Windows / macOS 是全自动的。
• 运行面板上「今日对话」「晨报」两张卡显示 —：hunter-community 的 api 没有对应的
  免登录接口（逐条实测过），按「拿不到就不编」的原则空着。上游接口清单在面板上可以点开看。
• Windows / macOS 只在 CI 里编译与打包通过，没有在真机上跑过。

社区反馈回应

这是启动器的第一个公开版本，还没有收到社区反馈。用得不顺手请开 issue：
https://github.com/agentpit-io/HunterLauncher/issues/new —— 启动器里「反馈」按钮能一键生成预填好的 issue，
并附一份脱敏过的诊断包（不含 key）。

Hunter 启动器 0.1.4 · macOS 真机首测修复 + AI 诊断助手

[0.1.4] - 2026-09-20

迭代轮 I4。用户在自己的 Mac 上第一次真机跑 0.1.3，当场撞出一个 P0；
本轮修掉它，顺带把安装排障做成了两层的诊断助手。

修复

macOS 上装着 Docker 却报「没有找到 Docker」（P0） —— 用户的 OrbStack 好好装着、
终端里 docker version 能返回 Server 29.4.0，启动器却停在
E_DOCKER_MISSING · 命令行里找不到 docker。

根因和「装没装」毫无关系，是 macOS GUI 程序的固有行为：从访达或程序坞启动的程序，
拿到的 PATH 只有 /usr/bin:/bin:/usr/sbin:/sbin（launchctl getenv PATH 是空的 →
走系统默认），不含 /usr/local/bin —— 而 docker 恰恰就在那里
（一个指向 /Applications/OrbStack.app/Contents/MacOS/xbin/docker 的软链）。
终端里能跑，是因为 shell 读过 /etc/paths 与 ~/.zshrc，GUI 程序读不到那些。

现在不再只看 PATH：按「配置指定 → PATH → 平台已知位置」的顺序挨个探，
找到第一个能执行的就用。Docker 检测页上直接写出实际用的是哪一条路径、从哪找到的
（是软链还会写出它指向哪里）；一个都没找到时，把探过的每一个位置和结果整份列出来。
mac 上探的位置包括 /usr/local/bin、/opt/homebrew/bin、~/.orbstack/bin、
~/.docker/bin、Docker.app 与 OrbStack.app 的 app 内目录、~/.colima/bin、~/.rd/bin 等；
Linux 与 Windows 各有自己的一份。装在清单之外的，可以在
~/.hunter/launcher.toml 的 [runtime] docker_path 里指一次。

docker compose 也一样：先试 CLI 插件，没有再找独立的 docker-compose。
之后所有调用 docker 的地方都走这条解析出来的绝对路径，不再有「有的地方用 PATH、
有的地方用绝对路径」这种事。

变化

向导顺序调整：欢迎 → 输入 key → Docker → 选模型 → 拉镜像 → 启动。
key 挪到了 Docker 前面。Docker 那一步是整个流程里最容易卡住的，而新加的 AI 诊断助手
要用这把 key 调网关；填 key 本来就只需要联网、不依赖 Docker，挪到前面没有代价。
命令行 --headless 的步骤号同步调整。

新增

AI 诊断助手。分两层，顺序不能反。

第一层是确定性规则，一直在跑，零延迟、零 token、不联网：多路径探测、
「装了但没起来」（OrbStack / Docker Desktop / Colima / systemd 分别判「装没装」与
「进程起没起」，直接给一个「启动它」的按钮）、端口占用、磁盘不足、拉取失败。
规则认出来的情况到此为止，一个字都不会发出去。

第二层是 AI 兜底，只有规则认不出来、或者你主动点了「让 AI 帮我看看」才会调。
它走 Hunter 网关（hunter-chat），用的就是你自己那把 key。几条边界：

• 送上去的是一份结构化诊断，你可以逐字展开看、整份复制走。里面没有 key、
  没有 Bearer 头，路径里的用户名一律换成 <用户目录>；发之前还有一道闸，
  整份再扫一遍 key 的形状，命中就干脆不发。
• 模型不能让启动器跑任意命令 —— 它只能从一张写死的动作表里挑，表外的一律拒绝
  并在日志里记一条（界面上也会显示「模型提了什么、为什么没执行」）。
  只读动作自动执行；会改动你机器的必须先把完整命令原样给你看，点确认才跑。
• 来回最多 3 轮，之后明说搞不定并给手工步骤。
• 没填 key、离线、网关不可用、额度用尽（402）、限流（429）、超时 ——
  任何一条都退回第一层，并在界面上写清是哪一条挡住了。
• 设置页有开关，默认开；关掉之后只剩第一层。

命令行也有：hunter-launcher --diagnose 只跑规则层（零 token），
加 --ai 才会真去问模型（显式开关，因为 --diagnose 常被写进脚本，
不能在你没要求的时候悄悄花掉额度）。

诊断包与日志里的路径不再带用户名 —— /Users/zhangsan/.hunter/app/.env 会写成
<用户目录>/.hunter/app/.env，后半截留着（排查还得靠它）。诊断包是要贴进 GitHub issue 的。

---

下载

平台	文件	说明
Windows 10/11 x64	hunter-launcher_0.1.4_x64-setup.exe（推荐）/ hunter-launcher_0.1.4_x64_en-US.msi	NSIS 安装包 / MSI
macOS 12+	hunter-launcher_0.1.4_universal.dmg	通用二进制（Intel + Apple Silicon）
Ubuntu 22.04+ / Debian 12+ x64	hunter-launcher_0.1.4_amd64.deb（推荐）/ hunter-launcher_0.1.4_amd64.AppImage	deb 约 3.8 MiB；AppImage 约 78 MiB（自带整套 WebKitGTK，这是格式的固有代价）

国内下载（腾讯云香港，不用翻墙）：
https://hunter-dl-hk-1253756459.cos.ap-hongkong.myqcloud.com/launcher/0.1.4/

GitHub 下载：https://github.com/agentpit-io/HunterLauncher/releases/tag/launcher-v0.1.4

Linux 上装 deb：

sudo apt install -y ./hunter-launcher_0.1.4_amd64.deb
hunter-launcher            # 有桌面就开界面
hunter-launcher --headless # 纯 SSH 的机器走这条

⚠ 这些包没有代码签名

Windows 代码签名证书（100–500 美元/年）与 Apple 开发者账号（99 美元/年）都要花钱，
本项目目前没有购买，所以：

• Windows：SmartScreen 会拦一下。点「更多信息」→「仍要运行」。
• macOS：会说「无法打开，因为它来自身份不明的开发者」或「已损坏」。
  右键点 .app →「打开」→ 再点一次「打开」；仍然不行就在终端里跑
  xattr -dr com.apple.quarantine "/Applications/Hunter Launcher.app"（路径里有空格，引号别漏）。
• Linux：不受影响，deb / AppImage 本来就不强制签名。

因此这个 Release 标为 prerelease（预发布）。要不要买证书、转正式版由用户决定。
详细的图文步骤在 docs/常见问题.md。

自更新的清单是签名的：updater 用的 minisign 密钥是本项目自己生成的，公钥编译在程序里，
签名验不过的更新包不会被安装。这一条与上面的代码签名是两件事。

已知问题

• AppImage 有 78 MiB，远超设计目标里写的 40 MB —— 它要自带整套 WebKitGTK，压不下去。
  介意体积就用 deb。
• .deb 装的启动器不能就地自更新（换 /usr 下的文件要 root）。点「更新」时启动器会把
  新包下到 ~/.hunter/updates/ 并给出一条 sudo apt install 命令，最后一步由你来。
  AppImage / Windows / macOS 是全自动的。
• 运行面板上「今日对话」「晨报」两张卡显示 —：hunter-community 的 api 没有对应的
  免登录接口（逐条实测过），按「拿不到就不编」的原则空着。上游接口清单在面板上可以点开看。
• Windows / macOS 只在 CI 里编译与打包通过，没有在真机上跑过。

社区反馈回应

这是启动器的第一个公开版本，还没有收到社区反馈。用得不顺手请开 issue：
https://github.com/agentpit-io/HunterLauncher/issues/new —— 启动器里「反馈」按钮能一键生成预填好的 issue，
并附一份脱敏过的诊断包（不含 key）。

Hunter 启动器 0.1.3

[0.1.3] - 2026-09-20

迭代轮 I3 的补丁版。又做了一次全量回归（清空 ~/.hunter、用 0.1.2 的 deb
从零装、命令行与界面各一次、真实对话跑通），修掉本轮自审与回归撞出来的几条。

修复

额度用完了，运行面板上一个字都没提 —— 这是本轮回归当场撞上的：测试 key 的
今日额度在回归途中真的用完了（网关 remaining 为 0），Hunter 里的对话被挡住，
而启动器的运行面板只摆着「304,144 / 300,000」两个数字，进度条还是正常的琥珀金。
输入 key 那一页白纸黑字写着「额度用尽会明确提示，不会静默降级」—— 装完之后那句话
其实没有兑现。现在额度用完时面板上会有一条明确的提示（用了多少、什么时候重置、
想现在就用该怎么办），额度卡的副行写「已用完 · 明天 00:00（上海）重置」，
进度条转成警示色；hunter-launcher --status 也一样。

Podman 被误判成「Docker 装了但服务没起」 —— 本轮在测试机上真装了一次
podman 4.9.3 验这件事。它的 docker version --format json 是合法的 Docker 形状
JSON（只有 Client 没有 Server），而且整段里一个 podman 字样都没有，
所以原来那条「输出不是 JSON 才认 podman」的判断永远轮不到 —— 用户明明装着能用的
podman，看到的却是「连不上 Docker 后台服务」加一整页装 Docker 的指引。
现在认得出来了，并且明说自己没验过：Podman 仍是实验支持，整套安装从来没有在
它上面跑通过，docker compose 在 Podman 上要另外装 compose provider。

更新页的卡片标题自己打自己 —— 标题写着「启动器有新版本」，正下方写着
「启动器已经是最新版」。标题现在跟着状态走。

更新页的发布时间原样显示成 2026-09-19T09:47:29Z —— 现在换算成上海时间
「2026-09-19 17:47（上海）」，和界面上别处一致。

--tray-menu 打错一个字母会「成功」 —— hunter-launcher --tray-menu stopp
之前会照常开一个界面、退出码 0，脚本里看起来像是做成了，实际什么都没发生。
现在退出码 2，并列出可用的菜单项。

--key-file 指的文件权限太松时不再闷声不响 —— 帮助里写着「建议 600」，
但之前只写不查。现在文件对同机其他用户可读时会提醒一句（只提醒，不中断）。

变化

.env 写完会读回来逐项对账 —— 写之前查值里有没有换行（0.1.2 加的）拦的是
已知形状；现在写完再把文件按 .env 的语法解析回来，逐项比对本来要写的值，
并检查有没有同名键写了两遍。任何形式的注入或写坏都会当场报错，而不是装到一半才发现。
对账的报错只说键名不说值，key 与口令一个字都不会进日志。

~/.hunter/app/VERSION 收成 600 —— 至此 ~/.hunter 下由启动器写出来的文件
全部是 600、目录全部是 700，口径统一了（这个文件里只有一个版本号，不是安全问题）。

内部

• 镜像源候选的字段换成 Cow，自定义镜像源不再往 'static 里泄漏字符串
  （设置页每保存一次泄一点，一个进程以 KB 计）；代码库里 Box::leak 清零。
• CI 里给安装包改名那一步不再把版本号拼进源文件名，改成和发布流水线一样按前缀替换。
• 截图脚本多一页（额度用尽的运行面板）；GUI 回归脚本每点一下都会断言界面真的变了。

---

下载

平台	文件	说明
Windows 10/11 x64	hunter-launcher_0.1.3_x64-setup.exe（推荐）/ hunter-launcher_0.1.3_x64_en-US.msi	NSIS 安装包 / MSI
macOS 12+	hunter-launcher_0.1.3_universal.dmg	通用二进制（Intel + Apple Silicon）
Ubuntu 22.04+ / Debian 12+ x64	hunter-launcher_0.1.3_amd64.deb（推荐）/ hunter-launcher_0.1.3_amd64.AppImage	deb 约 3.8 MiB；AppImage 约 78 MiB（自带整套 WebKitGTK，这是格式的固有代价）

国内下载（腾讯云香港，不用翻墙）：
https://hunter-dl-hk-1253756459.cos.ap-hongkong.myqcloud.com/launcher/0.1.3/

GitHub 下载：https://github.com/agentpit-io/HunterLauncher/releases/tag/launcher-v0.1.3

Linux 上装 deb：

sudo apt install -y ./hunter-launcher_0.1.3_amd64.deb
hunter-launcher            # 有桌面就开界面
hunter-launcher --headless # 纯 SSH 的机器走这条

⚠ 这些包没有代码签名

Windows 代码签名证书（100–500 美元/年）与 Apple 开发者账号（99 美元/年）都要花钱，
本项目目前没有购买，所以：

• Windows：SmartScreen 会拦一下。点「更多信息」→「仍要运行」。
• macOS：会说「无法打开，因为它来自身份不明的开发者」或「已损坏」。
  右键点 .app →「打开」→ 再点一次「打开」；仍然不行就在终端里跑
  xattr -dr com.apple.quarantine "/Applications/Hunter Launcher.app"（路径里有空格，引号别漏）。
• Linux：不受影响，deb / AppImage 本来就不强制签名。

因此这个 Release 标为 prerelease（预发布）。要不要买证书、转正式版由用户决定。
详细的图文步骤在 docs/常见问题.md。

自更新的清单是签名的：updater 用的 minisign 密钥是本项目自己生成的，公钥编译在程序里，
签名验不过的更新包不会被安装。这一条与上面的代码签名是两件事。

已知问题

• AppImage 有 78 MiB，远超设计目标里写的 40 MB —— 它要自带整套 WebKitGTK，压不下去。
  介意体积就用 deb。
• .deb 装的启动器不能就地自更新（换 /usr 下的文件要 root）。点「更新」时启动器会把
  新包下到 ~/.hunter/updates/ 并给出一条 sudo apt install 命令，最后一步由你来。
  AppImage / Windows / macOS 是全自动的。
• 运行面板上「今日对话」「晨报」两张卡显示 —：hunter-community 的 api 没有对应的
  免登录接口（逐条实测过），按「拿不到就不编」的原则空着。上游接口清单在面板上可以点开看。
• Windows / macOS 只在 CI 里编译与打包通过，没有在真机上跑过。

社区反馈回应

这是启动器的第一个公开版本，还没有收到社区反馈。用得不顺手请开 issue：
https://github.com/agentpit-io/HunterLauncher/issues/new —— 启动器里「反馈」按钮能一键生成预填好的 issue，
并附一份脱敏过的诊断包（不含 key）。