Skip to content
Back to search

muse-guardian

SkillWorks with Claude CodeGitHub

"在全新沙盒/新账号上从零部署一套「CF Server Monitor 探针 + 三层保活 + Hermes 微信机器人 + MuseAutoApprove(muse.ai 外联审批自动批准)」:Cloudflare Worker 后台、cf-probe 探针、持久化脚本布局、离线包缓存、Hermes 安装与模型 API 配置、微信扫码绑定、沙盒内看门狗、平台 hook 探针(检测/恢复拆分)、平台开机钩子、端到端验证。开工先问「全部安装 / 逐模块」(默认逐模块);全文按 5 个模块 + 收尾组织,同一模块内连续执行,只在用户必须输入/扫码/平台点击时打断;每步五段式(命令 / 话术 / 用户手动动作 / 做完的标志 / 排错表格),全部脚本完整代码直接内嵌,复制即可用。触发词:部署保活、给新账号也来一套、装探针、微信机器人、沙盒重建恢复、保活脚本、自动审批、审批卡片、MuseAutoApprove。"

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked yesterday
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/bytehola--muse-guardian/badge.svg)](/listings/bytehola--muse-guardian)

HTML

<a href="/listings/bytehola--muse-guardian"><img src="/api/listings/bytehola--muse-guardian/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 3,110 lines
  1. ---
  2. name: muse-guardian
  3. description: "在全新沙盒/新账号上从零部署一套「CF Server Monitor 探针 + 三层保活 + Hermes 微信机器人 + MuseAutoApprove(muse.ai 外联审批自动批准)」:Cloudflare Worker 后台、cf-probe 探针、持久化脚本布局、离线包缓存、Hermes 安装与模型 API 配置、微信扫码绑定、沙盒内看门狗、平台 hook 探针(检测/恢复拆分)、平台开机钩子、端到端验证。开工先问「全部安装 / 逐模块」(默认逐模块);全文按 5 个模块 + 收尾组织,同一模块内连续执行,只在用户必须输入/扫码/平台点击时打断;每步五段式(命令 / 话术 / 用户手动动作 / 做完的标志 / 排错表格),全部脚本完整代码直接内嵌,复制即可用。触发词:部署保活、给新账号也来一套、装探针、微信机器人、沙盒重建恢复、保活脚本、自动审批、审批卡片、MuseAutoApprove。"
  4. version: 2.6.0
  5. license: MIT
  6. metadata:
  7. hermes:
  8. tags:
  9. [
  10. sandbox,
  11. keepalive,
  12. disaster-recovery,
  13. cloudflare,
  14. probe,
  15. hermes,
  16. weixin,
  17. deployment,
  18. muse-auto-approve,
  19. ]
  20. related_skills: [weixin-instant-ack, sandbox-environment-recon]
  21. ---
  22. # 沙盒保活 + Hermes 微信机器人:一键部署手册
  23. ## 一、这套东西是什么
  24. 平台(Muse / hatch 沙盒)会不定期**重建**沙盒:整机从外部删掉重装,沙盒内的一切——
  25. 进程、systemd、cron、/tmp——全部消失,只有 `$HOME`(`/home/hatch`)会保留。
  26. 本手册部署的是一套**三层保活 + 微信机器人**:
  27. | 层 | 组件 | 对付的故障 | 恢复时间 |
  28. | ---------- | ---------------------------------------------------------------------------- | ---------------------------------------- | --------------------------- |
  29. | 探针 | `cf-probe`(systemd 服务)→ CF Server Monitor 后台 | 你想知道机器到底活着还是挂了 | 60 秒上报一次 |
  30. | Layer 1 | `watchdog.sh`(沙盒内 cron,每分钟) | 机器活着,但某个进程挂了 / 微信连接卡死 | 1 分钟内 |
  31. | Layer 2a | 平台 hook 探针(每 10 秒 bash 轮询,跑在沙盒外;健康零 token,连续异常才唤醒 agent 恢复) | 整机被重建,沙盒内 cron 全灭 | 10 秒级发现,约 2 分钟恢复 |
  32. | Layer 2b | 平台原生开机钩子(每次启动跑一次) | 同上,但更快(开机即恢复) | 开机后约 100 秒 |
  33. | Layer 3 | `restore-all.sh`(幂等一键恢复) | 被 1、2a、2b 调用 | 约 2 分钟 |
  34. | 审批自动化 | `MuseAutoApprove`(沙盒内 node 常驻;步骤 1–4 安装启动、第 15 步起接入保活) | 沙盒访问新域名时平台弹审批卡片、外联卡住 | 默认每 10 秒一轮询 |
  35. 平台重建无法阻止,本手册只保证「重建后自动恢复」。
  36. ## 二、怎么用这本手册(AI 必须遵守的行事规则)
  37. 1. **开工先问执行方式;默认逐模块。** 动手之前先问用户选哪种(话术见第三章开头):
  38. - **A. 全部安装**:一口气把 5 个模块 + 收尾全做完,只在下面 8 个介入点停。
  39. - **B. 逐模块(默认)**:每做完一个模块汇报一次,等用户说"继续"再做下一个。用户没明确选就按 B。
  40. - **同一模块内的步骤连着做完**,不要逐步确认;纯沙盒内的动作(跑脚本、装服务、写 cron、改文件)全部自己做完。
  41. - **只在用户必须到场时停**:需要用户输入(账号、密钥、策略)、扫码、或在平台/网页端点击时,才停下把话术发出去,等用户回复再往下。这些点见「必须用户介入的环节」。
  42. 2. **正文按五段式书写——这是文档结构,不是执行节奏。** 每个步骤五段固定顺序,便于排障与查证;**执行时同一模块内的步骤连着做完,不必逐步确认**,只在 ② 出现、或 ④ 判据不过时才打断用户:
  43. - **① 🤖 AI 执行**:你(AI)要跑的命令,精确到可以直接复制。不要写"类似这样",要写实际的命令。
  44. - **② 💬 对用户说**:可以**原样发给用户**的话术(可微调语气,不要改意思)。用户是技术型、直接、要求客观,话术要短、要具体、要说清"要他做什么"。
  45. - **③ 🙋 用户手动做**:用户必须在网页/手机/平台端点的动作。
  46. - **④ ✅ 做完的标志**:可验证的判据(命令 + 期望输出)。**做不到就不要往下走**,先解决问题。
  47. - **⑤ 🛠️ 常见失败与处理**:表格,现象 → 原因 → 处理。
  48. 3. **每条命令都要真跑过。** 报告结果时说清楚「跑了什么、看到什么」。跑不了就直说跑不了,不要编造输出。
  49. 4. **密钥纪律(四条铁律,违反必出事)**:
  50. - 真实 SECRET / API Key / Worker 域名 / API 地址**绝不写进任何文档、Skill、日志、记忆**——本手册里全用占位符:`<PROBE_ID>`、`<API_SECRET>`、`<WORKER_URL>`、`<API_BASE_URL>`、`<MODEL_NAME>`。
  51. - 密钥优先**让用户自己生成**,通过**安全页面**发给你;只有用户明确同意时才由 AI 生成并在聊天里**一次性**显示。(例外:MuseAutoApprove 的 muse.ai 账号密码——沙盒里没有可用安全入口,按用户要求**走聊天框明文**,见第六章。)
  52. - **先脱敏再打印**,不是"先打印再脱敏"。需要确认密钥存在,就只输出计数/长度/路径/布尔值,不输出值本身。
  53. - 含密钥的文件(`install-cf-probe.sh`、`~/.hermes/.env`)权限一律 600,且**不要用文件读取工具打开**(内容会进会话历史)。
  54. 5. **谁做什么**(重要,别硬揽):
  55. - 沙盒内的一切(跑脚本、装服务、写 cron、改文件)→ 任何有 shell 的 Agent 都能做。
  56. - **Layer 2a(平台 hook 探针)和 Layer 2b(平台开机钩子)跑在沙盒外面**:只有**平台侧 Agent**(Muse)或**用户在平台端**才能创建。如果你是在沙盒里跑的 Agent,这两步要**请求用户/平台侧 Agent 执行**,并把现成的 hook 脚本、hook 定义与恢复提示词交给他们(本手册第 13、14 步给了全文)。
  57. - 涉及 root 权限的操作(装包、写 systemd、启动 sshd、给 `init.sh` 加执行位)→ 沙盒里通常是 root,直接做,但要在报告里说明改了哪些系统路径。
  58. ### 模块地图(执行顺序)
  59. 整条流程分成 **5 个模块 + 收尾**,**顺序不可乱**(MAA 最先装:部署全程要出网,先让审批能自动批;保活补丁必须在脚本落盘〔步骤 7〕与看门狗 cron〔步骤 11〕之后)。**按 A/B 模式连着做,只在介入点停**:
  60. | 模块 | 干什么 | 步骤 | 章节 | 要用户做什么 |
  61. | -------------------- | --------------------------------------------------- | ----- | ----------- | ------------------------------------------------- |
  62. | **A|自动审批底座** | 装 MuseAutoApprove 并常驻,外联审批自动批 | 1–4 | 四~七 | 选策略 + 发 muse.ai 账号密码 + 首次装包点一次卡片 |
  63. | **B|监控与探针** | CF 监控后台 + cf-probe 探针 | 5–6 | 八~九 | 给 CF Token(或网页部署)+ 后台拿安装命令 |
  64. | **C|保活底座** | 保活脚本落盘 + 离线包缓存 | 7–8 | 十~十一 | 无(全自动) |
  65. | **D|微信机器人** | 装 Hermes + 接模型 API + 微信扫码绑定与配对 | 9–10 | 十二~十三 | 模型 API 地址/Key + 微信扫码 + 转配对码 |
  66. | **E|三层保活接入** | Layer 1 看门狗、平台授权、Layer 2a/2b、MAA 保活补丁 | 11–15 | 十四~十八 | 平台端点 3 项授权 |
  67. | **收尾|验收与运维** | MAA 验证/排障/交互/升级、最终验证 | 16–20 | 十九~二十三 | 微信发消息测试 + 决定是否做重建演练 |
  68. ### 必须用户介入的环节(只有这 8 处要停)
  69. 除下列各处,其余全程自动。到这些点才发话术、等用户回复:
  70. 1. **开工询问 + 平台设置**:先问执行方式(A 全部安装 / B 逐模块,默认 B);再在网页把「直接网络协议」全开、「连接器 → 浏览器」(除上传文件)全改为允许(第三章)。
  71. 2. **MAA 策略与账号**:选 A(永久允许)/ B(每次只批一次);把 muse.ai 邮箱密码发在聊天框(步骤 1、3)。
  72. 3. **首次装包卡片**:`git clone` / `npm install` 弹审批卡片时,用户手动点一次「允许」(步骤 2)。
  73. 4. **CF 后台**:给 Cloudflare API Token(或自己在网页部署);后台「添加服务器」把安装命令贴回来;定 `API_SECRET`(步骤 5)。
  74. 5. **模型 API**:接口地址 + API Key + 模型名(步骤 9)。
  75. 6. **微信扫码**:手机扫码 + 确认登录;之后把机器人回的**配对码**转给 AI(步骤 10)。
  76. 7. **平台授权**:平台端确认「保活探针 hook / 开机钩子 / root 执行」3 项(步骤 12)。
  77. 8. **最终验证**:微信给机器人发消息测试;决定是否做重建演练(步骤 20)。
  78. ## 三、开工前的询问与设置 + 两次探测
  79. ### 开工第一件事:问执行方式 + 两处平台设置(一条消息问完)
  80. 这是整条流程的**第一个动作**。在跑任何命令之前先发下面这条,一次把「执行方式」和「两处设置」都问掉,拿到答复再往下。两处设置在平台网页端,沙盒里**无法直接验证**,以用户确认为准。
  81. 💬 对用户说(可原样发送):
  82. > 开始部署前,先确认两件事:
  83. >
  84. > **一、执行方式**,你选一个:
  85. >
  86. > - **A. 全部安装(一次做完,推荐)**:我一口气把 5 个模块 + 收尾全做完,只在需要你输入、扫码或点平台时才来找你。
  87. > - **B. 逐模块(默认)**:每做完一个模块我汇报一次,你说"继续"我再做下一个。
  88. >
  89. > **二、两处平台设置**,在 Muse.AI 网页上做:
  90. >
  91. > **1. 设置 → 权限 → 直接网络协议**:把里面的开关**全部打开**。一个已知 Bug:点开关时滑块看起来没反应,**其实已经打开了**——每个开关点一次就行,不用管滑块动没动,也不要反复点。
  92. >
  93. > **2. 设置 → 权限 → 连接器 → 浏览器**:把里面的选项**全部改成「允许」**,但**「上传文件」不可更改**。
  94. >
  95. > 回复格式随意,比如"**A,都设好了**"或"**B**"。执行方式不回就按 **B(逐模块)**走。
  96. 做完的标志:用户回复执行方式(缺失则按 B)+ 确认两处设置已做。**探测 2 如果全是 000,第一怀疑对象是「直接网络协议」没开全。**
  97. ### 两次探测(不是前置条件,是事实确认)
  98. 这两条命令是给自己看的,**不要**把它们包装成"前置条件清单"去问用户:
  99. ```bash
  100. # 探测 1:我是谁、在哪、有没有 systemd / root
  101. whoami; echo "HOME=$HOME"; id -u; ls -d "$HOME/workspace" 2>/dev/null || echo "no workspace dir"
  102. systemctl --version 2>/dev/null | head -1 || echo "no systemd"
  103. # 探测 2:能不能出去(GitHub / Cloudflare / 模型 API 端点)
  104. curl -sS -m 8 -o /dev/null -w 'github %{http_code}\n' https://raw.githubusercontent.com/huilang-me/cfsm-agent/main/install.sh
  105. curl -sS -m 8 -o /dev/null -w 'cf %{http_code}\n' https://api.cloudflare.com/client/v4
  106. ```
  107. 期望:`whoami` 是 root 或可用 sudo 的用户;`HOME` 指向可持久化的家目录;systemd 存在;两个 HTTP 码不是 000(000 = 连不上)。若 GitHub 不通,第 8 步的离线缓存就是**必需**的,不是可选项。**探测 2 两个都是 000 时,先回头确认上面的「直接网络协议」已全部打开,再谈别的。**
  108. # 模块 A|自动审批底座(MuseAutoApprove,步骤 1–4)
  109. 先装这一模块并常驻:**后续全程出网(拉代码、装依赖、调模型)都不再卡审批卡片**。本模块要用户配合三次:定策略、发 muse.ai 账号密码、首次装包点一次卡片。
  110. ## 四、步骤 1:MuseAutoApprove 是什么(先定策略)
  111. **目标**:说清机制与副作用,让用户定决策策略。
  112. > 沙盒外联未被规则覆盖的域名会弹审批卡片(HITL)。本组件用 muse.ai 账号连 hatch 网关加密 RPC(`wss://hatch.metaaivm.com`)自动决策,默认 `allow_always + destination_domain` 落库永久规则。纯 Node 无浏览器,只与 muse.ai / hatch 通信;`data/` 含账号密码、会话、token,`log/` 含邮箱与审批记录,均在 `$HOME` 下(700/600),不外发不提交。
  113. | 事项 | 说明 |
  114. | -------- | ------------------------------------------------------------------------- |
  115. | 登录 | 邮箱+密码;服务端会发一封验证码邮件,**本工具不读邮件** |
  116. | 会话 | `hatch_sess` 30 天,每 5 分钟 token touch 滚动续期——30 天内跑过一次即永续 |
  117. | 轮询 | 默认 10 秒一轮 |
  118. | 默认决策 | `allow_always + destination_domain`;失败回退 `allow_once` |
  119. | 保守决策 | `--decision allow_once`:只批本次,不落永久规则 |
  120. | 生效范围 | 仅本账号、所连 VM 的审批流 |
  121. ### ① 🤖 AI 执行(命令)
  122. **开工检查**:用户还没确认第三章的两处平台设置——「设置 → 权限 → 直接网络协议」全部打开、「设置 → 权限 → 连接器 → 浏览器」除「上传文件」外全部改为允许——的,先回去做完再进本步骤。
  123. ```bash
  124. ls "$HOME/workspace/muse-guardian/MuseAutoApprove/muse-daemon.cjs" 2>/dev/null \
  125. && echo "已安装(升级见第二十二章)" || echo "尚未安装"
  126. ```
  127. 确认尚未安装后,按 ② 与用户确认策略,再进下一步。用户没明确表态就不要动。
  128. ### ② 💬 对用户说(可原样发送)
  129. > 🚦 装一个"自动点同意"的组件(MuseAutoApprove)。沙盒每次访问新域名,平台会弹卡片等你点"允许",不点就卡住;这个组件用你的 muse.ai 账号把这一步自动做掉。
  130. >
  131. > 要你定一个策略:
  132. >
  133. > - **A. 永久允许**(推荐):同域名批一次永久放行,之后基本不再看到卡片;
  134. > - **B. 每次只批一次**(保守):域名不被永久记住。
  135. >
  136. > 另外它需要你的 muse.ai 账号密码——下一步**直接在聊天框发我**即可。装的过程会弹一两次卡片(GitHub、npm),那两次请手动点允许。
  137. > 回"A"或"B",我就继续。
  138. ### ③ 🙋 用户手动做
  139. - 选策略 A 或 B。
  140. ### ④ ✅ 做完的标志
  141. - 用户明确回复 A 或 B(没回复不要往下走)。
  142. ### ⑤ 🛠️ 常见失败与处理
  143. | 现象 | 处理 |
  144. | ------------------------ | -------------------------------------------------------------------- |
  145. | 用户担心"自动同意"不安全 | 改 B(每次只批一次);或先不装 |
  146. | 用户不想把密码给 AI | MAA 只能明文聊天给(其他入口走不通);介意可落盘后自行改密,或先不装 |
  147. | 用户想只放行指定域名 | 本工具没有白名单:要么 B,要么继续手工点卡片 |
  148. ---
  149. ## 五、步骤 2:安装(Node + git clone + 依赖)
  150. **目标**:Node ≥ 20.18 就位、代码 clone 到 `~/workspace/muse-guardian`、依赖装齐、语法自检全过。
  151. > 全部装在 `$HOME` 下:代码、`node_modules`、Node 运行时、凭据、会话——重建后都在。
  152. ### ① 🤖 AI 执行(命令)
  153. ```bash
  154. # 1) Node ≥ 20.18:有就跳过;没有/过旧 → 装 $HOME/.local(重建不丢)
  155. command -v node && node -v || echo "no node"
  156. ```
  157. ```bash
  158. # 无 Node 或版本低时(示例版本,按需换 22.x 最新补丁号):
  159. case "$(uname -m)" in x86_64|amd64) A=x64;; aarch64|arm64) A=arm64;; *) echo "未知架构 $(uname -m)"; exit 1;; esac
  160. V=v22.16.0
  161. mkdir -p "$HOME/.local" /tmp/ni
  162. curl -fL -o /tmp/ni/node.tar.gz "https://nodejs.org/dist/$V/node-$V-linux-$A.tar.gz"
  163. tar -xzf /tmp/ni/node.tar.gz -C "$HOME/.local" --strip-components=1 --exclude='CHANGELOG.md' --exclude='LICENSE' --exclude='README.md'
  164. export PATH="$HOME/.local/bin:$PATH"; node -v && npm -v
  165. ```
  166. ```bash
  167. # 2) 克隆仓库(更新 = git pull),app 在仓库的 MuseAutoApprove/ 子目录
  168. cd ~/workspace
  169. [ -d muse-guardian/.git ] && git -C muse-guardian pull --ff-only \
  170. || git clone https://github.com/bytehola/muse-guardian.git
  171. ls muse-guardian/MuseAutoApprove/muse-daemon.cjs
  172. # 3) 装依赖 + 双自检
  173. cd muse-guardian/MuseAutoApprove
  174. npm install --no-audit --no-fund
  175. node -e "require('undici');require('ws');require('https-proxy-agent');require('sodium-native');console.log('deps OK')"
  176. for f in muse-daemon.cjs work/*.cjs; do node --check "$f" || echo "FAIL $f"; done; echo "语法检查完成"
  177. # 4) 目录与权限
  178. mkdir -p data log && chmod 700 data
  179. ```
  180. > **首次安装的鸡生蛋**:`git clone` / `npm install` 自己也要出网,可能弹审批卡片(`github.com`、`registry.npmjs.org`、`nodejs.org`)——此时自动审批还没起来,需要用户手动点一次"允许"。点过之后,同类请求就永久放行了。
  181. **装完后读一遍 `~/workspace/muse-guardian/MuseAutoApprove/README.md`**——里面有这个工具的目录结构、CLI 命令、环境变量和日志字段说明。后续排障和回答用户追问时用得上,不要只照本 SKILL.md 的模板复述。
  182. ### ② 💬 对用户说(可原样发送)
  183. > 📦 开始装。过程可能弹一两次审批卡片(GitHub、npm),**请手动点允许**——就这一次,之后同类请求自动审批组件会替你处理。
  184. > 装完我把自检结果给你看。
  185. ### ③ 🙋 用户手动做
  186. - 平台弹卡片时手动点允许。
  187. ### ④ ✅ 做完的标志
  188. ```bash
  189. cd ~/workspace/muse-guardian/MuseAutoApprove
  190. node -v # ≥ v20.18
  191. ls muse-daemon.cjs package.json work/*.cjs | wc -l # 期望 9
  192. node -e "require('undici');require('ws');require('https-proxy-agent');require('sodium-native');console.log('deps OK')"
  193. for f in muse-daemon.cjs work/*.cjs; do node --check "$f" || echo "FAIL $f"; done; echo "语法检查完成"
  194. ```
  195. ### ⑤ 🛠️ 常见失败与处理
  196. | 现象 | 处理 |
  197. | -------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
  198. | `git clone` 超时/被拦 | 让用户放行 `github.com`;或本机打包 `MuseAutoApprove/` 整目录传进沙盒(走整包拷贝,别手抄单文件) |
  199. | `npm install` 超时/被拦 | 放行 `registry.npmjs.org`;或换镜像 `npm config set registry https://registry.npmmirror.com`;或用离线 `node_modules` 包 |
  200. | `sodium-native` 编译失败 | `apt-get install -y build-essential python3` 后重装;或用同架构的离线 `node_modules` |
  201. | `node --check` 某文件 FAIL | 文件截断/损坏:`git -C ~/workspace/muse-guardian checkout -- MuseAutoApprove/<file>` |
  202. | bash 报 `$'\r'` | 从文档复制时带上了 CRLF:`sed -i 's/\r$//' <文件>` |
  203. ---
  204. ## 六、步骤 3:凭据与自动登录
  205. **目标**:凭据落盘(文件方式,长期必须)、验证登录链路。
  206. > **凭据查找顺序**:环境变量 `MUSE_USER`/`MUSE_PASSWORD` > 文件 `data/credentials.json`。
  207. > **长期运行必须用文件**:cron、重建恢复拉起的进程读不到 shell 环境变量。**"会话过期后能否自动重登"完全取决于这个文件**。
  208. > **登录流程**:restart → send-otp(服务端会发一封验证码邮件,**工具不读它**)→ confirm-password(密码信封)→ `hatch_sess` 30 天。
  209. > **会话永续**:守护进程每 5 分钟 token touch 滚动续期——30 天内跑过一次就永续。
  210. > **自愈**:会话丢失/过期 → 下次连接自动重登(日志 `connect_retry ENOENT` → `auto_login_ok` 是正常路径)。
  211. ### ① 🤖 AI 执行(命令)
  212. **唯一方式:用户把账号密码直接发在聊天框,AI 落盘(不复述、不回显)**
  213. > MAA 的 muse.ai 账号是纯密码登录,沙盒里没有可用的安全入口——用户自己写文件、或走别的"安全"通道实测都走不通。**用户直接把邮箱和密码发在聊天框里,这是唯一可行的给法。**
  214. ```bash
  215. APP=~/workspace/muse-guardian/MuseAutoApprove; cd "$APP"
  216. mkdir -p data && chmod 700 data
  217. # 账号密码来自用户聊天框里的明文;值只经环境变量传入,不进 shell 历史、不写命令行参数
  218. MUSE_EM="<用户在聊天框给的邮箱>" MUSE_PW="<用户在聊天框给的密码>" node -e '
  219. require("fs").writeFileSync("data/credentials.json",
  220. JSON.stringify({email:process.env.MUSE_EM,password:process.env.MUSE_PW},null,2),{mode:0o600});
  221. console.log("written");
  222. '
  223. chmod 600 data/credentials.json
  224. ```
  225. > ⚠️ 落盘后**不要**复述、不 echo、不写进任何文档;密码只存在于 `data/credentials.json`(600)。用户介意聊天记录的话,可自行改一次 muse.ai 密码并更新这个文件。
  226. **验证(两步)**:
  227. ```bash
  228. cd "$APP"
  229. node muse-daemon.cjs --check # 离线体检:凭据来源 + 会话状态(不出网)
  230. node muse-daemon.cjs --smoke # 真登录一次:会发一封验证码邮件(无需读码)→ SMOKE OK
  231. ```
  232. ### ② 💬 对用户说(可原样发送)
  233. > 🔑 需要你的 muse.ai 账号密码——**直接在聊天框里发我就行**(邮箱 + 密码,一条消息发来即可)。
  234. >
  235. > 说明:MAA 登录是纯密码,沙盒里没有别的可用入口,**明文聊天是唯一走得通的给法**。我会把它写进沙盒里 600 权限的凭据文件,之后不回显、不复述、不写进任何文档。你要是介意,落盘后可以自行改一次 muse.ai 密码。
  236. >
  237. > 另外两点:登录时 muse.ai 会往你邮箱**发一封验证码邮件,不用读**(流程必需,工具不读码);会话 30 天滚动续期,**只要 30 天内跑过一次就永续**,平时不用重复登录。
  238. ### ③ 🙋 用户手动做
  239. - 在聊天框里直接把 muse.ai 邮箱和密码发给我。
  240. ### ④ ✅ 做完的标志
  241. ```bash
  242. cd ~/workspace/muse-guardian/MuseAutoApprove
  243. node muse-daemon.cjs --check; echo "rc=$?" # 期望:凭据 OK(来源 data/credentials.json),rc=0
  244. node muse-daemon.cjs --smoke; echo "rc=$?" # 期望 0 + SMOKE OK
  245. stat -c '%a %n' data data/credentials.json # 期望 700 / 600
  246. ```
  247. ### ⑤ 🛠️ 常见失败与处理
  248. | 现象 | 处理 |
  249. | ---------------------------------------------- | -------------------------------------------------------------------------- |
  250. | `凭据: 缺失 (无环境变量且无 credentials.json)` | 路径/文件名核对(不是 `.example`);用 `node -e 'JSON.parse(...)'` 验 JSON |
  251. | `来源: 环境变量+文件混合(可能不完整)` | 只留一处完整的 |
  252. | `--smoke` 在 `confirm-password` 失败 | 密码错或账号有额外验证(见"已知边界");让用户浏览器登录确认账号可用 |
  253. | `token 403` | cookie 陈旧:删 `data/cookies.json` 重跑 `--smoke`;或出网没放行 `muse.ai` |
  254. | `sodium-native 未安装` | 回步骤 2 装依赖 |
  255. | 权限不是 600/700 | `chmod 700 data && chmod 600 data/credentials.json` |
  256. ---
  257. ## 七、步骤 4:启动、停止
  258. **目标**:从演练到常驻,掌握停止/重启。
  259. > **顺序**:`--smoke`(真登录)→ `--once --dry`(连网关、只看不批)→ `--once`(真批一轮)→ 常驻(nohup)。
  260. > **默认参数**:不带参数就是 10 秒轮询 + `allow_always` + 失败回退 `allow_once`。策略 B 用 `--decision allow_once`。
  261. > **停止**:优雅停 `touch data/muse-daemon.stop`(≤10 秒退出,**保活不会拉起它**——维护模式);前台 Ctrl+C;强杀 `kill "$(cat data/muse-daemon.pid)"`。
  262. > **防重复**:已在跑时再启动会打印 `another muse-daemon is already running: pid X -> exit` 并退出 0(设计,不是故障)。
  263. ### ① 🤖 AI 执行(命令)
  264. ```bash
  265. APP=~/workspace/muse-guardian/MuseAutoApprove; cd "$APP"
  266. export PATH="$HOME/.local/bin:$PATH"
  267. # 1) 演练:连网关、拉列表、只看不批
  268. node muse-daemon.cjs --once --dry; echo "rc=$?"
  269. tail -n 10 log/daemon-log.ndjson
  270. # 2) 常驻(后台)
  271. mkdir -p log
  272. nohup node muse-daemon.cjs --loop 10000 --always --fallback-once >> log/muse-console.log 2>&1 &
  273. echo "pid=$!"; sleep 8
  274. pgrep -f "[m]use-daemon.cjs" >/dev/null && echo "在跑"
  275. tail -n 5 log/daemon-log.ndjson
  276. ```
  277. 期望日志依次出现 `daemon_start`(含 decision/scope/proxy)→ `connected` → `heartbeat`(每 10 秒一条,`pending` 为当前待批数)。`pending:0` 是常态,不是失败。
  278. **日常操作**:
  279. ```bash
  280. pgrep -f "[m]use-daemon.cjs" # 查进程
  281. tail -f log/daemon-log.ndjson # 实时日志
  282. touch data/muse-daemon.stop # 优雅停(维护模式)
  283. rm data/muse-daemon.stop # 恢复
  284. kill "$(cat data/muse-daemon.pid)" # 强停(接入保活后 1 分钟内拉回)
  285. cd "$APP" && node work/muse-rpc.cjs list # 审批列表
  286. node work/muse-rpc.cjs detail '<id>' # 单条详情
  287. ```
  288. ### ② 💬 对用户说(可原样发送)
  289. > ▶️ 启动分两步:先真登录验证一次(邮箱会收到一封验证码邮件,**不用管**),再做一次"只看不批"的演练;都过了我才挂后台。
  290. > 之后想停就跟我说(我放停止标记,保活也不会拉起它)。
  291. ### ③ 🙋 用户手动做
  292. - 无。
  293. ### ④ ✅ 做完的标志
  294. ```bash
  295. cd ~/workspace/muse-guardian/MuseAutoApprove
  296. pgrep -f "[m]use-daemon.cjs" >/dev/null && echo "在跑"
  297. tail -n 20 log/daemon-log.ndjson # 期望 daemon_start → connected → heartbeat
  298. ```
  299. ### ⑤ 🛠️ 常见失败与处理
  300. | 现象 | 处理 |
  301. | ------------------------------------------------------------------ | ------------------------------------------------------------------- |
  302. | `connect_retry ... ENOENT ... cookies.json` 后紧跟 `auto_login_ok` | 正常自愈(首次无会话),不用管 |
  303. | `token 403` 反复 | 出网没放行 `muse.ai`,或 cookie 陈旧(删 `data/cookies.json` 重登) |
  304. | `fetch failed` / 连不上 | 出网没放行或网络不通;需代理才设 `MUSE_PROXY`(默认直连) |
  305. | 退出码 2 + 中文提示 | 无凭据无会话,回步骤 3 |
  306. | `another muse-daemon is already running` | 已有实例(pid 守卫);重启先停 |
  307. | `DAEMON FATAL` | 看 console 日志里的具体错误;依赖缺失回步骤 2 |
  308. | 启动后没有 heartbeat | 看进程在不在;不在就回上一行 |
  309. ---
  310. # 模块 B|监控与探针(CF 后台 + cf-probe,步骤 5–6)
  311. 先把 Cloudflare 上的监控后台跑起来,再给沙盒装上探针每分钟上报心跳——**这是后面「重建后自动恢复」能不能被外部看见的前提**。后台部署可以 AI 全自动(要 CF Token),也可以用户自己在网页点。
  312. ## 八、步骤 5:部署 CF Server Monitor 后台(Cloudflare Workers)
  313. **目标**:把监控后台跑起来,拿到 Worker 域名。
  314. > 构建命令 `npm run build:frontend`,部署命令 `npx wrangler deploy`。
  315. > Worker 需要 **`API_SECRET`**(Variables and Secrets),它同时是「Agent 上报密钥」与「后台初始登录密码」。
  316. > `wrangler.toml` 已声明 D1 绑定 `DB`(库名 `server-monitor-db`)与 DO `MetricsBroadcaster`(首次部署自动创建)。
  317. ### ① 🤖 AI 执行(命令)
  318. **先问用户走哪条路**(话术见 ②):路径 A 你全自动做,路径 B 用户在网页上点几下。
  319. **路径 A:AI 用 wrangler 全自动部署(需要用户的 Cloudflare API Token)**
  320. ```bash
  321. # 1. Token 只放环境变量,绝不写文件(用户通过安全页面给你)
  322. export CLOUDFLARE_API_TOKEN='<用户提供的 Token>'
  323. export PROBE_API_SECRET='<用户生成的 API_SECRET>' # 用户生成后经安全页面给你;探针上报与后台初始密码都用它
  324. npx wrangler --version || npm i -g wrangler # 没有 wrangler 就装
  325. # 2. 取代码
  326. git clone https://github.com/huilang-me/CF-Server-Monitor /tmp/cf-server-monitor
  327. cd /tmp/cf-server-monitor
  328. # 3. 看 D1 库是否存在;不存在就建(wrangler.toml 里绑定名是 DB、库名是 server-monitor-db)
  329. npx wrangler d1 list || true
  330. npx wrangler d1 create server-monitor-db || true # 已存在会报 already exists,忽略
  331. # 4. 构建前端 + 部署(缺了 build:frontend 会部署出一个没有前端的 Worker)
  332. npm run build:frontend
  333. npx wrangler deploy
  334. # 5. 设置 Worker 密钥(Agent 上报密钥 = 后台初始密码);值从环境变量读,不进 shell 历史
  335. printf '%s' "$PROBE_API_SECRET" | npx wrangler secret put API_SECRET
  336. # 6. 立刻清理 Token
  337. unset CLOUDFLARE_API_TOKEN PROBE_API_SECRET
  338. ```
  339. **路径 B:用户在网页上部署(更省事,推荐给不想把 Token 交出来的用户)**
  340. - 一键部署:打开 `https://deploy.workers.cloudflare.com/?url=https://github.com/huilang-me/CF-Server-Monitor`,确认 Build command 是 `npm run build:frontend`,把 `API_SECRET` 改成随机强密码(不要用默认值);
  341. - 或:Fork 仓库 → Cloudflare Dashboard → Workers & Pages → 从 GitHub 仓库导入 → 构建命令 `npm run build:frontend`、部署命令 `npx wrangler deploy`;
  342. - 部署后在 Worker 的 **Settings → Variables and Secrets** 添加 `API_SECRET`(类型选 Secret),保存并等重新部署完成。
  343. ### ② 💬 对用户说(可原样发送)
  344. > ☁️ 第一步先把监控后台部署起来。它跑在 Cloudflare Workers 上,你账号的免费额度就够。
  345. >
  346. > 有两条路,你挑一条:
  347. >
  348. > **A. 我来部署**:需要一个 Cloudflare API Token,用一次就丢,不写任何文件。拿 Token:
  349. >
  350. > 1. 打开 https://dash.cloudflare.com/profile/api-tokens
  351. > 2. Create Token → 选 **Edit Cloudflare Workers** 模板
  352. > 3. Account Resources 选你的账号 → Continue → Create Token
  353. > 4. **通过安全页面发给我**(不要直接贴在聊天里)
  354. >
  355. > **B. 你在网页上点**:打开这个一键部署链接(我把链接发你),构建命令保持 `npm run build:frontend`,`API_SECRET` 换成随机强密码,部署完在 Worker 的 Variables and Secrets 里确认 `API_SECRET` 已保存。
  356. >
  357. > 另外要先定 **API_SECRET** 这个值(探针上报密钥,也是后台初始登录密码)。两种做法:
  358. >
  359. > - **推荐**:你自己用密码管理器生成一串 32 位随机串(只含字母数字),通过安全页面给我;
  360. > - 或者我生成、在聊天里只显示一次——但这样它会进聊天记录,你介意就别选这个。
  361. >
  362. > 部署成功后 wrangler / 网页会给出 Worker 域名(形如 `https://cf-server-monitor.<你的子域>.workers.dev`),把它告诉我。
  363. ### ③ 🙋 用户手动做
  364. - 选路径 A:创建 Token → 走安全页面发给你;选路径 B:在 Cloudflare 网页完成部署。
  365. - 自己生成或接收 `API_SECRET`。
  366. - 把 Worker 域名告诉你。
  367. ### ④ ✅ 做完的标志
  368. ```bash
  369. export WORKER_URL='https://cf-server-monitor.<你的子域>.workers.dev' # 真实值只放环境变量
  370. curl -sS -m 10 -o /dev/null -w 'HTTP %{http_code}\n' "$WORKER_URL/" # 期望 200(不是 404 / 1101)
  371. curl -sS -m 10 -o /dev/null -w 'admin HTTP %{http_code}\n' "$WORKER_URL/admin" # 期望 200
  372. ```
  373. 另外要用户确认:浏览器打开 `$WORKER_URL/admin#/admin`,用 **用户名 `admin` + 密码 = `API_SECRET`** 能登录进后台。
  374. 登录成功即视为这一步完成。**顺手提醒用户**:登录后立刻在后台把管理员用户名/密码改掉(后台密码可以和 `API_SECRET` 分离,但探针上报必须继续用 `API_SECRET`)。
  375. ### ⑤ 🛠️ 常见失败与处理
  376. | 现象 | 原因 | 处理 |
  377. | --------------------------------- | --------------------------------------------- | ----------------------------------------------------------------------------------- |
  378. | `Authentication error` / `10000` | Token 权限不对或已撤销 | 让用户按上面的模板重建一个;确认账户资源选的是目标账号 |
  379. | 部署成功但页面 404 | 没跑 `npm run build:frontend`,`dist/` 不存在 | 补跑构建再 `npx wrangler deploy` |
  380. | 接口返回 `API_SECRET is required` | Worker 没读到环境变量 | 在 Variables and Secrets 里删掉旧值重新添加 `API_SECRET`,保存后等重新部署 |
  381. | `D1 database already exists` | 以前部署过 | 正常,复用即可(`npx wrangler d1 list` 确认库名是 `server-monitor-db`) |
  382. | 部署卡住不动 | 网络问题 | Ctrl+C 重试一次;仍失败让用户看 Cloudflare 账号状态 |
  383. | `wrangler` 报 DO namespace 未创建 | 首次部署 | 重新 `npx wrangler deploy` 一次(`wrangler.toml` 的 `[[migrations]]` 会在部署时建) |
  384. ---
  385. ## 九、步骤 6:装 cf-probe 探针
  386. **目标**:让沙盒每 60 秒向 CF 后台报一次心跳,后台能看到这台机器在线。
  387. > 安装器 `install.sh`,服务名固定 `cf-probe`;root 路径:二进制 `/usr/local/bin/cf-probe`、配置 `/etc/config/cf-probe/config.conf`、日志 `journalctl -u cf-probe -f`。
  388. > 必填 `-id`(服务器 ID)、`-secret`(= Worker 的 `API_SECRET`)、`-url`(Worker 上报地址)。
  389. > **后台「添加服务器」可生成带全套参数的安装命令,直接用它的。**
  390. ### ① 🤖 AI 执行(命令)
  391. ```bash
  392. # 0. 先建目录(探针脚本要落在这里,$HOME 下才不会被重建带走)
  393. mkdir -p ~/workspace/setup/logs
  394. # 1. 让用户在 CF 后台「添加服务器」,把生成的安装命令发你。它会带齐 -id / -secret / -url 等参数。
  395. # 形如: cf-probe install -id=<服务器ID> -secret=<API_SECRET> -url=https://<worker>/update -interval=60 ...
  396. # 2. 落盘安装脚本(代码见下,三个占位符替换成真实值),权限 600
  397. # 写完后先自检:不能有残留占位符
  398. grep -q '<PROBE_ID>\|<API_SECRET>\|<WORKER_URL>' ~/workspace/setup/install-cf-probe.sh \
  399. && echo "ERROR: 占位符未替换" || echo "占位符已替换干净"
  400. chmod 600 ~/workspace/setup/install-cf-probe.sh
  401. # 3. 落盘启动器(完整代码见本节末尾「代码 2/13」;把那段代码原样写进文件,然后:)
  402. chmod +x ~/workspace/setup/run-probe-install.sh
  403. # 4. 用启动器安装(不要直接跑 install-cf-probe.sh)
  404. bash ~/workspace/setup/run-probe-install.sh; echo "rc=$?"
  405. tail -20 ~/workspace/setup/logs/probe-install.log
  406. # 5. 立刻缓存一份二进制(完整代码见本节末尾「代码 3/13」;写进文件后执行)
  407. chmod +x ~/workspace/setup/cache-cf-probe-bin.sh
  408. bash ~/workspace/setup/cache-cf-probe-bin.sh
  409. ```
  410. **为什么必须走 `run-probe-install.sh`**:cf-probe 的 Go 安装器在安装时会按 cmdline 关键字清理旧进程,直接调用 `install-cf-probe.sh` 会导致**调用者自己的 shell 被误杀**(因为你的命令行里出现了那个关键字)。启动器的对策是:把安装脚本复制到**不含关键字的临时路径**、用 `setsid` 放进**独立会话**再跑。
  411. ### ② 💬 对用户说(可原样发送)
  412. > 📡 现在装探针——它是整套系统的"眼睛",每 60 秒给 CF 后台上报一次这台机器的状态。
  413. >
  414. > 请做两件事:
  415. >
  416. > 1. 打开后台 `https://<worker域名>/admin#/admin`(用户名 `admin`,密码是你刚设的 `API_SECRET`),
  417. > 在「服务器管理」里**添加服务器**,名称可以填 `sandbox-main` 或你习惯的名字;
  418. > 2. 点「复制」拿安装命令(选对系统和版本),**整条命令贴给我**。
  419. >
  420. > 那条命令里会带 `-id=`、`-secret=`、`-url=` 这些参数,我把它写成安装脚本落到沙盒里。
  421. > 提示:这条命令里含你的密钥,贴给我的时候没关系(我会写进 600 权限的文件,不会写进任何文档或记忆)。
  422. ### ③ 🙋 用户手动做
  423. - 在 CF 后台添加服务器,把生成的安装命令贴给你。
  424. - 等 60–90 秒后,回后台看这台服务器是否**在线**、有没有数据上报。
  425. ### ④ ✅ 做完的标志
  426. ```bash
  427. systemctl is-active cf-probe # 期望 active
  428. systemctl status cf-probe --no-pager | head -5
  429. journalctl -u cf-probe -n 5 --no-pager -o cat # 期望看到 started / WSS connected
  430. ls -l /etc/config/cf-probe/config.conf # 期望存在(root 安装路径)
  431. ```
  432. 判据:`active` + 日志里有连接成功行 + **用户确认后台里这台机器在线**(三个都满足才往下走)。
  433. 注意日志里的域名属于用户资产,**不要**把它复制进任何文档。
  434. ### ⑤ 🛠️ 常见失败与处理
  435. | 现象 | 原因 | 处理 |
  436. | ---------------------------------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
  437. | 后台看不到服务器 | `-secret` 与 Worker 的 `API_SECRET` 不一致 | 让用户核对两处值是否完全相同(大小写、有无引号) |
  438. | 安装脚本报"占位符未替换" | 三个占位符有残留 | 重新替换后用 `grep -q '<PROBE_ID>\|…'` 自检 |
  439. | 安装成功但服务不 active | 系统没有 systemd 或权限不足 | `systemctl --version` 确认;非 root 环境用 `systemctl --user`(非 root 安装时二进制在 `~/.cf-probe/`) |
  440. | 安装过程中调用者 shell 被杀 | 直接跑了 `install-cf-probe.sh` | 改用 `bash ~/workspace/setup/run-probe-install.sh` |
  441. | 下载 install.sh 失败 | GitHub 不通 | 有本地缓存 `cf-probe-install.saved.sh` 会自动兜底;没有缓存就先在能上网的机器上抓一份带过去 |
  442. | 探针报了但一直离线 | `-url` 少了 `/update` 或域名错 | 对照后台生成的命令核对 `-url=` |
  443. | 绑定/上报都正常,但流量/CPU 是空的 | 采集间隔为 0(`-collect_interval=0` 表示不额外采样) | 这是默认值,需要更细数据再在后台改参数(探针会自动拉取) |
  444. ### 代码 1/13:`install-cf-probe.sh`(含密钥,权限 600,模板含 3 个占位符)
  445. **目标路径**:`~/workspace/setup/install-cf-probe.sh`
  446. ```bash
  447. #!/usr/bin/env bash
  448. # install-cf-probe.sh — 安装/重装 cf-probe 探针(幂等,可反复执行)。
  449. #
  450. # 【本文件含真实密钥,权限必须 600】
  451. # - 不要提交到任何仓库、不要贴进聊天、不要复制到别处。
  452. # - 部署时把三个占位符换成真实值:<PROBE_ID>、<API_SECRET>、<WORKER_URL>。
  453. # 换完必须自检一次:grep 不到占位符才算换干净。
  454. # - 密钥只在这里(+ Cloudflare Worker 的 API_SECRET)落盘,不要再另存副本。
  455. #
  456. # 结构对照上游(huilang-me/cfsm-agent install.sh,2026-09-26 核对):
  457. # 1. 优先下载最新安装器,失败时用本地缓存 cf-probe-install.saved.sh,
  458. # 下载成功顺手更新缓存——重建时网络不可靠,本地兜底是必须的。
  459. # 2. 安装命令走 `install -id=… -secret=… -url=<worker>/update …`(参数名与上游一致)。
  460. # 3. 额外加固(本 SKILL 增加,已实测可用):
  461. # a. SETUP_DIR 支持 CF_PROBE_SETUP_DIR 覆盖 —— 因为探针安装必须经
  462. # run-probe-install.sh 启动器,而启动器会把脚本复制到 /tmp 运行,
  463. # 此时 dirname "$0" 会变成 /tmp,本地缓存就找错地方了。
  464. # b. 安装器与本地二进制缓存双兜底:无网时可直接跑缓存的 cf-probe 二进制
  465. # (releases/latest/download/cf-probe-linux-amd64,与安装器下载的同一个文件,
  466. # 已验证字节一致;该二进制支持 `install` 子命令)。
  467. set -euo pipefail
  468. SETUP_DIR="${CF_PROBE_SETUP_DIR:-$(cd "$(dirname "$0")" && pwd)}"
  469. SAVED="$SETUP_DIR/cf-probe-install.saved.sh"
  470. LATEST="$SETUP_DIR/cf-probe-install.latest.sh"
  471. INSTALL_SRC='https://raw.githubusercontent.com/huilang-me/cfsm-agent/main/install.sh'
  472. # ===== 部署时替换这三行 =====
  473. PROBE_ID='<PROBE_ID>'
  474. API_SECRET='<API_SECRET>'
  475. WORKER_URL='<WORKER_URL>'
  476. # ==========================
  477. # 可选:自定义网络质量测试节点(留空=用 agent 内置节点)。
  478. # CF 后台「添加服务器」生成的安装命令里会带这组参数,原样抄过来即可。
  479. CT_NODE=''
  480. CU_NODE=''
  481. CM_NODE=''
  482. # 本地二进制缓存(由 cache-cf-probe-bin.sh 生成;按当前架构命名)
  483. case "$(uname -m)" in
  484. x86_64|amd64) BIN_ARCH=amd64 ;;
  485. aarch64|arm64) BIN_ARCH=arm64 ;;
  486. armv7*|armv8l) BIN_ARCH=armv7 ;;
  487. *) BIN_ARCH=unsupported ;;
  488. esac
  489. BIN_CACHE="$SETUP_DIR/cf-probe-linux-${BIN_ARCH}"
  490. ARGS=(install "-id=${PROBE_ID}" "-secret=${API_SECRET}" "-url=${WORKER_URL}/update"
  491. -collect_interval=0 -interval=60 -connection_mode=auto -ping_mode=tcp
  492. -reset_day=1 -auto_update=0)
  493. [ -n "$CT_NODE" ] && ARGS+=("-ct=${CT_NODE}")
  494. [ -n "$CU_NODE" ] && ARGS+=("-cu=${CU_NODE}")
  495. [ -n "$CM_NODE" ] && ARGS+=("-cm=${CM_NODE}")
  496. # 占位符自检:没换干净就别装,免得装出个连不上后台的探针
  497. for v in "$PROBE_ID" "$API_SECRET" "$WORKER_URL"; do
  498. case "$v" in
  499. *'<'*'>'*)
  500. echo "[error] 占位符未替换:$v" >&2
  501. exit 1 ;;
  502. esac
  503. done
  504. installer=""
  505. if curl -fsSL "$INSTALL_SRC" -o "$LATEST" 2>/dev/null && [ -s "$LATEST" ]; then
  506. chmod 600 "$LATEST"
  507. cp -f "$LATEST" "$SAVED"
  508. chmod 600 "$SAVED"
  509. installer="$LATEST"
  510. echo "[info] 已下载上游安装器,并更新本地缓存 $SAVED"
  511. elif [ -f "$SAVED" ]; then
  512. installer="$SAVED"
  513. echo "[warn] 上游下载失败,使用本地缓存安装器 $SAVED" >&2
  514. else
  515. echo "[warn] 上游下载失败且本地无缓存安装器,尝试二进制缓存" >&2
  516. fi
  517. if [ -n "$installer" ]; then
  518. if sh "$installer" "${ARGS[@]}"; then
  519. echo "OK: cf-probe 安装完成(安装器路径)"
  520. exit 0
  521. fi
  522. echo "[warn] 安装器执行失败,回退到本地二进制缓存" >&2
  523. fi
  524. if [ -x "$BIN_CACHE" ]; then
  525. if "$BIN_CACHE" "${ARGS[@]}"; then
  526. echo "OK: cf-probe 安装完成(本地二进制缓存 $BIN_CACHE)"
  527. exit 0
  528. fi
  529. echo "[error] 本地二进制缓存安装失败" >&2
  530. exit 1
  531. fi
  532. echo "[error] 无法安装 cf-probe:网络不可达,且没有安装器/二进制缓存。" >&2
  533. echo "[error] 处理:联网后重跑本脚本,或先跑 cache-cf-probe-bin.sh 缓存二进制(该缓存每次部署都建议做一份)。" >&2
  534. exit 1
  535. ```
  536. ### 代码 2/13:`run-probe-install.sh`(安全启动器)
  537. **目标路径**:`~/workspace/setup/run-probe-install.sh` **权限**:`chmod +x`
  538. ```bash
  539. #!/usr/bin/env bash
  540. # run-probe-install.sh — 探针安装器的安全启动器。
  541. # 背景:cf-probe 的 Go 安装器在安装时会按 cmdline 关键字清理旧进程,
  542. # 直接跑 install-cf-probe.sh 会导致调用者自己的 shell 被误杀(cmdline 含 cf-probe)。
  543. # 对策:复制到无关键字临时路径 + setsid 独立会话运行,隔离两种误伤。
  544. #
  545. # 另一处坑(2026-09-26 复核发现并修掉):install-cf-probe.sh 内部用
  546. # `dirname "$0"` 定位 setup 目录。脚本被复制到 /tmp 后 $0 是 /tmp 里的临时文件,
  547. # dirname 会变成 /tmp —— 本地缓存路径(cf-probe-install.saved.sh)就指错了地方,
  548. # 离线兜底会失败、缓存也永远更新不到真目录。所以这里显式把真目录传下去:
  549. # 启动器 export CF_PROBE_SETUP_DIR,安装脚本优先读它。
  550. set -uo pipefail
  551. SETUP_DIR="${CF_PROBE_SETUP_DIR:-$(cd "$(dirname "$0")" && pwd)}"
  552. SRC="$SETUP_DIR/install-cf-probe.sh"
  553. LOG="$SETUP_DIR/logs/probe-install.log"
  554. mkdir -p "$SETUP_DIR/logs"
  555. TMP_RUN="$(mktemp /tmp/.sysinit-XXXXXXXX.sh)"
  556. cp "$SRC" "$TMP_RUN"
  557. chmod 600 "$TMP_RUN"
  558. # 独立会话(新进程组),安装器即使杀进程组也伤不到调用者
  559. export CF_PROBE_SETUP_DIR="$SETUP_DIR"
  560. setsid bash "$TMP_RUN" >"$LOG" 2>&1 < /dev/null &
  561. pid=$!
  562. if wait "$pid"; then
  563. rc=0
  564. else
  565. rc=$?
  566. fi
  567. rm -f "$TMP_RUN"
  568. exit "$rc"
  569. ```
  570. ### 代码 3/13:`cache-cf-probe-bin.sh`(二进制离线缓存)
  571. **目标路径**:`~/workspace/setup/cache-cf-probe-bin.sh` **权限**:`chmod +x`
  572. ```bash
  573. #!/usr/bin/env bash
  574. # cache-cf-probe-bin.sh — 把 cf-probe 二进制缓存到本地,供重建后无网时离线安装。
  575. #
  576. # 为什么需要它:install-cf-probe.sh 只缓存了「安装脚本」,而安装脚本本身还要去
  577. # GitHub releases 下载 8MB 左右的二进制。网络不可达时(国内沙盒常见)这一步会失败,
  578. # 探针就装不上。把二进制也缓存一份到 $HOME(沙盒重建不丢),恢复时零下载。
  579. #
  580. # 已验证(2026-09-26):该 URL 下回来的二进制与安装器装到 /usr/local/bin/cf-probe
  581. # 的文件字节完全一致(sha256 相同),且 `--help` 里能看到 `cf-probe install` 子命令。
  582. set -uo pipefail
  583. SETUP_DIR="${CF_PROBE_SETUP_DIR:-$(cd "$(dirname "$0")" && pwd)}"
  584. case "$(uname -m)" in
  585. x86_64|amd64) ARCH=amd64 ;;
  586. aarch64|arm64) ARCH=arm64 ;;
  587. armv7*|armv8l) ARCH=armv7 ;;
  588. *) echo "[error] 不支持的架构 $(uname -m)" >&2; exit 1 ;;
  589. esac
  590. URL="https://github.com/huilang-me/cfsm-agent/releases/latest/download/cf-probe-linux-${ARCH}"
  591. OUT="$SETUP_DIR/cf-probe-linux-${ARCH}"
  592. TMP="$OUT.tmp.$$"
  593. echo "[info] 下载 $URL"
  594. if ! curl -fL --connect-timeout 10 -m 300 -o "$TMP" "$URL"; then
  595. rm -f "$TMP"
  596. echo "[error] 下载失败,二进制缓存未更新" >&2
  597. exit 1
  598. fi
  599. chmod 755 "$TMP"
  600. # 自检:能识别 install 子命令才算是个能用的探针二进制
  601. if ! timeout 10 "$TMP" --help 2>&1 | grep -q 'cf-probe install'; then
  602. rm -f "$TMP"
  603. echo "[error] 下载的文件不像 cf-probe 二进制(自检失败),已丢弃" >&2
  604. exit 1
  605. fi
  606. mv -f "$TMP" "$OUT"
  607. sha256sum "$OUT" | awk '{print $1}' > "$OUT.sha256"
  608. echo "OK: 已缓存 $OUT ($(stat -c %s "$OUT") 字节)"
  609. echo " sha256=$(cat "$OUT.sha256")"
  610. ```
  611. ---
  612. # 模块 C|保活底座(脚本落盘 + 离线包,步骤 7–8)
  613. 把全部保活脚本落盘到 `$HOME`,再把 `cron`/`openssh` 依赖闭包和探针二进制缓存到本地——**重建后不依赖网络也能把系统组件装回来**。这一模块**全自动,不需要用户做任何事**。
  614. ## 十、步骤 7:持久化布局(把保活脚本全部落盘)
  615. **目标**:把 7 个保活脚本放到 `$HOME/workspace/setup/`,全部可执行、全部语法检查通过。
  616. > **重建后 `$HOME` 保留,系统目录全丢**。在:`~/workspace/`、`~/.hermes/`(程序与数据)、`~/.local/bin/`。不在:`/usr/local/bin/cf-probe`、`/etc/systemd/system/cf-probe.service`、`/etc/config/cf-probe/`、`/usr/sbin/sshd`、root crontab、`/tmp`。恢复脚本就是把这些按需重装。
  617. ### ① 🤖 AI 执行(命令)
  618. ```bash
  619. mkdir -p ~/workspace/setup/deb-cache ~/workspace/setup/logs
  620. mkdir -p ~/workspace/backups/hermes-home ~/workspace/tools ~/.hermes/memories
  621. # 把本节末尾的 7 个脚本按路径落盘,然后统一设置权限 + 语法检查
  622. chmod +x ~/workspace/setup/*.sh
  623. for f in ~/workspace/setup/*.sh; do bash -n "$f" && echo "OK $f" || echo "FAIL $f"; done
  624. ls -l ~/workspace/setup/*.sh
  625. ```
  626. ### ② 💬 对用户说(可原样发送)
  627. > 🧱 接下来装保活脚本。先跟你说清"什么会丢、什么不会丢",以后沙盒被重建你就知道发生了什么:
  628. >
  629. > - **重建后还在**:`~/workspace/` 里的脚本和离线包、`~/.hermes/` 里的 Hermes 程序和数据、备份。
  630. > - **重建后会丢**:探针二进制、systemd 服务、ssh/cron 这些系统组件、root 的定时任务、`/tmp` 里的东西。
  631. >
  632. > 丢掉的那些不需要你操心——恢复脚本会把它们重新装回来。你什么都不用做,我继续。
  633. ### ③ 🙋 用户手动做
  634. 无(这一步全自动)。
  635. ### ④ ✅ 做完的标志
  636. ```bash
  637. for f in watchdog.sh health-check.sh restore-all.sh lib-pkgs.sh \
  638. restore-hermes.sh backup-hermes.sh run-probe-install.sh; do
  639. [ -x "$HOME/workspace/setup/$f" ] && echo "OK $f" || echo "MISSING/NOT-EXEC $f"
  640. done
  641. bash -n ~/workspace/setup/restore-all.sh && echo "restore-all.sh 语法 OK"
  642. ```
  643. 判据:7 个脚本全部 `OK`,没有 `MISSING/NOT-EXEC`,语法检查无 FAIL。
  644. ### ⑤ 🛠️ 常见失败与处理
  645. | 现象 | 原因 | 处理 |
  646. | ------------------------------ | ----------------------------------------- | --------------------------------------------------------------------------------------- |
  647. | `bash -n` 报 `missing ']'` | 脚本被复制时丢了空格(如 `[ -f "$deb"]`) | 重新从本手册复制;本手册的代码是校验过语法的 |
  648. | 脚本落盘后权限不对 | 用了 `cp` 但源文件不可执行 | `chmod +x ~/workspace/setup/*.sh` |
  649. | `logs/` 不存在导致看门狗报错 | 没建目录 | 看门狗自己会 `mkdir -p`,但仍建议先建好 |
  650. | Hermes 在 `$HOME=/root` 下运行 | 平台注入的 HOME 异常 | 三个脚本都有 HOME 加固(HOME 下找不到 setup 但 `/home/hatch` 有就纠正),保持这段不要删 |
  651. ### 代码 4/13:`lib-pkgs.sh`(离线 deb 安装公共函数)
  652. **目标路径**:`~/workspace/setup/lib-pkgs.sh` **权限**:`chmod +x`
  653. ```bash
  654. #!/usr/bin/env bash
  655. # lib-pkgs.sh — 离线 deb 安装公共函数(被 watchdog.sh / restore-all.sh source)。
  656. # 策略:只安装缺失的包(避免降级镜像自带的新版本);
  657. # dpkg 跑两遍,第二遍解决 pre-depends 顺序问题(如 cron 依赖 cron-daemon-common 先 configure)。
  658. # 等待 dpkg/apt 锁释放。重建刚完成时平台自己的包 reconciliation 可能占着锁,
  659. # 直接 dpkg 会失败;最多等 10 分钟,每 15 秒检查一次(见 skill 避坑)。
  660. wait_for_dpkg_lock() {
  661. local waited=0
  662. while fuser /var/lib/dpkg/lock-frontend >/dev/null 2>&1 \
  663. || fuser /var/lib/dpkg/lock >/dev/null 2>&1; do
  664. if [ "$waited" -ge 600 ]; then
  665. return 1
  666. fi
  667. sleep 15
  668. waited=$((waited + 15))
  669. done
  670. return 0
  671. }
  672. # install_offline_debs <deb-cache-dir> [log-file]
  673. # 返回 0 表示成功(或无需安装),非 0 表示失败。
  674. install_offline_debs() {
  675. local cache_dir="$1" log_file="${2:-/dev/null}"
  676. local missing="" deb pkg
  677. for deb in "$cache_dir"/*.deb; do
  678. [ -f "$deb" ] || continue
  679. pkg="$(dpkg-deb -f "$deb" Package 2>/dev/null)"
  680. if [ -n "$pkg" ] && ! dpkg -l "$pkg" 2>/dev/null | grep -q "^ii"; then
  681. missing="$missing $deb"
  682. fi
  683. done
  684. if [ -z "$missing" ]; then
  685. return 0
  686. fi
  687. if ! wait_for_dpkg_lock; then
  688. echo "dpkg 锁等待超时" >>"$log_file"
  689. return 1
  690. fi
  691. # shellcheck disable=SC2086
  692. if DEBIAN_FRONTEND=noninteractive dpkg --force-confdef --force-confold -i $missing >>"$log_file" 2>&1; then
  693. return 0
  694. fi
  695. # 第一遍可能因 pre-depends 顺序失败:configure 已解包的包,再装一遍
  696. dpkg --configure -a >>"$log_file" 2>&1 || true
  697. # shellcheck disable=SC2086
  698. if DEBIAN_FRONTEND=noninteractive dpkg --force-confdef --force-confold -i $missing >>"$log_file" 2>&1; then
  699. dpkg --configure -a >>"$log_file" 2>&1 || true
  700. return 0
  701. fi
  702. dpkg --configure -a >>"$log_file" 2>&1 || true
  703. return 1
  704. }
  705. ```
  706. ### 代码 5/13:`watchdog.sh`(Layer 1 沙盒内看门狗)
  707. **目标路径**:`~/workspace/setup/watchdog.sh` **权限**:`chmod +x`
  708. ```bash
  709. #!/usr/bin/env bash
  710. # watchdog.sh — 每 1 分钟巡检:cf-probe 探针 / hermes 微信网关 / sshd。
  711. # 挂了就地修复;修不好写日志。设计遵循 awesome-skills/muse-reverse-ssh:
  712. # 原子 mkdir 单实例锁(不用 flock,避免 fd 被子进程继承导致锁死)、
  713. # pgrep 中括号技巧(避免匹配到检查进程自身)、/proc cmdline 校验。
  714. set -uo pipefail
  715. # HOME 加固:若当前 HOME 下找不到 setup 目录但 /home/hatch 下有,
  716. # 说明运行环境异常(如 HOME=/root),纠正后再继续(见 skill 避坑)
  717. if [ ! -d "$HOME/workspace/setup" ] && [ -d /home/hatch/workspace/setup ]; then
  718. export HOME=/home/hatch
  719. fi
  720. SETUP_DIR="$HOME/workspace/setup"
  721. LOG="$SETUP_DIR/logs/watchdog.log"
  722. LOCKDIR="$SETUP_DIR/.watchdog.lock"
  723. LOG_MAX_BYTES=$((10 * 1024 * 1024)) # 任何日志文件的上限:10MB
  724. # shellcheck disable=SC1091
  725. . "$SETUP_DIR/lib-pkgs.sh" 2>/dev/null || true
  726. export PATH="$HOME/.local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
  727. log() { echo "[$(date '+%F %T')] $*" >> "$LOG"; }
  728. # --- 日志裁剪:任何日志文件超过 10MB,只保留末尾 10MB ---
  729. # 覆盖本体系所有日志:脚本日志、MAA 日志、Hermes 网关日志、hook 探针日志。
  730. # 用 tail -c 取字节并 sed 丢掉首行(避免留下半行)。
  731. trim_log_file() {
  732. local f="$1" sz tmp
  733. [ -f "$f" ] || return 0
  734. sz="$(stat -c %s "$f" 2>/dev/null || echo 0)"
  735. [ "$sz" -gt "$LOG_MAX_BYTES" ] || return 0
  736. tmp="${f}.trim.$$"
  737. if tail -c "$LOG_MAX_BYTES" "$f" | sed '1d' > "$tmp" 2>/dev/null; then
  738. mv -f "$tmp" "$f"
  739. log "日志已裁剪至 10MB:$f"
  740. else
  741. rm -f "$tmp"
  742. fi
  743. }
  744. # --- 单实例锁(原子 mkdir;目录不会被子进程继承) ---
  745. if ! mkdir "$LOCKDIR" 2>/dev/null; then
  746. if [ -f "$LOCKDIR/pid" ]; then
  747. oldpid=$(cat "$LOCKDIR/pid" 2>/dev/null || true)
  748. if [ -n "$oldpid" ] && [ -f "/proc/$oldpid/cmdline" ] \
  749. && tr '\0' ' ' < "/proc/$oldpid/cmdline" 2>/dev/null | grep -q "[/]watchdog.sh"; then
  750. exit 0 # 另一个实例还活着,静默退出
  751. fi
  752. fi
  753. rm -rf "$LOCKDIR"
  754. mkdir "$LOCKDIR" 2>/dev/null || exit 0 # 抢锁失败就退出
  755. fi
  756. echo $$ > "$LOCKDIR/pid"
  757. trap 'rm -rf "$LOCKDIR"' EXIT
  758. mkdir -p "$SETUP_DIR/logs"
  759. # --- 1. cf-probe 探针 ---
  760. if [ -f /etc/systemd/system/cf-probe.service ]; then
  761. if ! systemctl is-active -q cf-probe 2>/dev/null; then
  762. log "cf-probe 未运行,尝试 systemctl restart"
  763. if systemctl restart cf-probe >>"$LOG" 2>&1; then
  764. log "cf-probe 重启成功"
  765. else
  766. log "cf-probe 重启失败"
  767. fi
  768. fi
  769. else
  770. log "cf-probe 服务文件丢失,执行重装"
  771. if bash "$SETUP_DIR/run-probe-install.sh" >>"$LOG" 2>&1; then
  772. log "cf-probe 重装成功"
  773. else
  774. log "cf-probe 重装失败"
  775. fi
  776. fi
  777. # --- 2a. hermes 微信网关:进程活着但连接卡死 ---
  778. # 对应 skill 的 "A live tunnel process does not mean a live tunnel":
  779. # 只查进程查不出微信 poll 卡死,看日志里 poll error 是否持续超过 5 分钟。
  780. WXLOG="$HOME/.hermes/logs/weixin-gateway.log"
  781. WX_RESTART_TS="$SETUP_DIR/.wx-wedged-restart-ts"
  782. if pgrep -f "hermes-agent.*[g]ateway" >/dev/null 2>&1 && [ -f "$WXLOG" ]; then
  783. since="$(date -d '10 minutes ago' '+%F %T')"
  784. mapfile -t wxerrs < <(awk -v since="$since" \
  785. 'index($0,"poll error")>0 && substr($0,1,19)>=since {print substr($0,1,19)}' "$WXLOG" 2>/dev/null)
  786. if [ "${#wxerrs[@]}" -ge 3 ]; then
  787. first_ts="${wxerrs[0]}"; last_ts="${wxerrs[$((${#wxerrs[@]}-1))]}"
  788. if [ "$(date -d "$last_ts" +%s)" -gt "$(( $(date -d "$first_ts" +%s) + 300 ))" ]; then
  789. # 15 分钟内只因卡死重启一次,避免全网故障时反复重启
  790. now="$(date +%s)"; last_restart=0
  791. [ -f "$WX_RESTART_TS" ] && last_restart="$(cat "$WX_RESTART_TS" 2>/dev/null || echo 0)"
  792. if [ "$((now - last_restart))" -ge 900 ]; then
  793. log "微信 poll 持续报错超过 5 分钟($first_ts ~ $last_ts),判定连接卡死,重启网关"
  794. # 精确 kill:优先 gateway.pid。注意该文件是 JSON({"pid":123,"kind":"hermes-gateway",...}),
  795. # 不能直接 cat 当数字用;解析出 pid 后还要校验 /proc/<pid>/cmdline 命中网关进程模式(hermes-agent.*[g]ateway)。
  796. # 拿不到有效 pid 才枚举 pgrep 命中进程,并排除自身与父进程——
  797. # 不用 `pkill -f`:一行命令里出现过网关关键字(比如包装它的 bash -c)也会被误杀。
  798. killed=0
  799. gpid=""
  800. if [ -f "$HOME/.hermes/gateway.pid" ]; then
  801. if command -v jq >/dev/null 2>&1; then
  802. gpid="$(jq -r '.pid // empty' "$HOME/.hermes/gateway.pid" 2>/dev/null || true)"
  803. fi
  804. if [ -z "$gpid" ]; then
  805. gpid="$(python3 -c 'import json,sys;print(json.load(open(sys.argv[1])).get("pid",""))' \
  806. "$HOME/.hermes/gateway.pid" 2>/dev/null || true)"
  807. fi
  808. if [ -n "$gpid" ] && [ -f "/proc/$gpid/cmdline" ] \
  809. && tr '\0' ' ' < "/proc/$gpid/cmdline" 2>/dev/null | grep -q "hermes-agent.*[g]ateway"; then
  810. kill -TERM "$gpid" 2>/dev/null && killed=1
  811. for _ in 1 2 3 4 5 6 7 8 9 10; do
  812. kill -0 "$gpid" 2>/dev/null || break
  813. sleep 1
  814. done
  815. if kill -0 "$gpid" 2>/dev/null; then
  816. kill -KILL "$gpid" 2>/dev/null || true
  817. sleep 1
  818. fi
  819. fi
  820. fi
  821. if [ "$killed" = 0 ]; then
  822. for p in $(pgrep -f "hermes-agent.*[g]ateway" 2>/dev/null); do
  823. [ "$p" = "$$" ] && continue
  824. [ "$p" = "$PPID" ] && continue
  825. kill -TERM "$p" 2>/dev/null || true
  826. done
  827. fi
  828. echo "$now" > "$WX_RESTART_TS"
  829. sleep 3
  830. else
  831. log "微信 poll 持续报错,但 15 分钟内已重启过,跳过"
  832. fi
  833. fi
  834. fi
  835. unset wxerrs
  836. fi
  837. # --- 2b. hermes 微信网关:进程缺失则重启 ---
  838. # 进程行有新老两种形态:`hermes gateway run` 与 `python3 -I -c` 包装(cmdline 里是 hermes-agent 路径)。统一用 hermes-agent.*[g]ateway 检测,两种都能命中;[g] 避免自匹配。
  839. if ! pgrep -f "hermes-agent.*[g]ateway" >/dev/null 2>&1; then
  840. log "hermes gateway 进程丢失,尝试重启"
  841. if compgen -G "$HOME/.hermes/weixin/accounts/*.json" > /dev/null 2>&1; then
  842. mkdir -p "$HOME/.hermes/logs"
  843. nohup hermes gateway run >> "$HOME/.hermes/logs/weixin-gateway.log" 2>&1 &
  844. sleep 3
  845. if pgrep -f "hermes-agent.*[g]ateway" >/dev/null 2>&1; then
  846. log "hermes gateway 重启成功"
  847. else
  848. log "hermes gateway 重启后仍无进程"
  849. fi
  850. else
  851. log "无微信账号凭据,跳过网关重启"
  852. fi
  853. fi
  854. # --- 3. sshd ---
  855. if [ ! -x /usr/sbin/sshd ]; then
  856. log "sshd 二进制丢失,尝试从离线缓存重装"
  857. if install_offline_debs "$SETUP_DIR/deb-cache" "$LOG" && [ -x /usr/sbin/sshd ]; then
  858. log "openssh-server 离线重装成功"
  859. else
  860. log "离线重装失败,回退到 apt"
  861. apt-get install -y openssh-server >>"$LOG" 2>&1 || log "openssh-server 安装失败"
  862. fi
  863. fi
  864. if [ -x /usr/sbin/sshd ]; then
  865. mkdir -p /run/sshd
  866. chown root:root /run/sshd; chmod 755 /run/sshd
  867. [ -f /etc/ssh/ssh_host_rsa_key ] || ssh-keygen -A >>"$LOG" 2>&1
  868. if ! pgrep -f "[/]usr/sbin/sshd" >/dev/null 2>&1; then
  869. log "sshd 未运行,尝试启动"
  870. if /usr/sbin/sshd >>"$LOG" 2>&1; then
  871. # 刚启动完立即检查在负载高时可能误判,重试 3 次 × 2 秒(见 skill 避坑)
  872. ok=0
  873. for i in 1 2 3; do
  874. sleep 2
  875. if pgrep -f "[/]usr/sbin/sshd" >/dev/null 2>&1; then ok=1; break; fi
  876. done
  877. [ "$ok" = 1 ] && log "sshd 启动成功" || log "sshd 启动后仍无进程(3 次重试)"
  878. else
  879. log "sshd 启动失败"
  880. fi
  881. fi
  882. else
  883. log "sshd 二进制仍缺失,本次跳过"
  884. fi
  885. # --- 4. 日志裁剪:把所有日志压回 10MB 以内 ---
  886. for f in "$LOG" \
  887. "$HOME/.hermes/logs/weixin-gateway.log" \
  888. "$HOME/workspace/muse-guardian/MuseAutoApprove"/log/*.ndjson \
  889. "$HOME/workspace/muse-guardian/MuseAutoApprove"/log/muse-console.log \
  890. "$HOME/hooks/logs"/*.jsonl \
  891. "$SETUP_DIR/logs"/*.log; do
  892. trim_log_file "$f"
  893. done
  894. log "巡检完成"
  895. ```
  896. ### 代码 6/13:`health-check.sh`(健康检查,0=健康 / 1=需恢复)
  897. **目标路径**:`~/workspace/setup/health-check.sh` **权限**:`chmod +x`
  898. ```bash
  899. #!/usr/bin/env bash
  900. # health-check.sh — 沙盒健康检查,供平台 hook 探针(keepalive-tripwire)与看门狗调用。
  901. # 退出码:0=健康;1=需要恢复(疑似重建或关键服务全挂)。实现只返回 0/1;
  902. # 调用方(hook 探针):rc=1 立即唤醒恢复;非 0/1 累计连续 3 次才唤醒。
  903. #
  904. # 检查项(与 watchdog.sh / restore-all.sh 保持一致):
  905. # 1. cf-probe systemd 服务 active
  906. # 2. hermes 微信网关进程存活
  907. # 3. sshd 进程存活
  908. # 4. cron 进程存活 且 crontab 里有看门狗
  909. # HOME 加固:若当前 HOME 下找不到 setup 目录但 /home/hatch 下有,
  910. # 说明运行环境异常(如 HOME=/root),纠正后再继续(见 skill 避坑)
  911. if [ ! -d "$HOME/workspace/setup" ] && [ -d /home/hatch/workspace/setup ]; then
  912. export HOME=/home/hatch
  913. fi
  914. SETUP_DIR="$HOME/workspace/setup"
  915. failures=""
  916. if [ "$(systemctl is-active cf-probe 2>/dev/null)" != "active" ]; then
  917. failures="$failures cf-probe"
  918. fi
  919. if ! pgrep -f "hermes-agent.*[g]ateway" >/dev/null 2>&1; then
  920. failures="$failures hermes-gateway"
  921. fi
  922. if ! pgrep -f "[/]usr/sbin/sshd" >/dev/null 2>&1; then
  923. failures="$failures sshd"
  924. fi
  925. if ! pgrep -f "[/]usr/sbin/cron" >/dev/null 2>&1; then
  926. failures="$failures cron-daemon"
  927. fi
  928. if ! crontab -l 2>/dev/null | grep -q "watchdog.sh"; then
  929. failures="$failures cron-entry"
  930. fi
  931. if [ -z "$failures" ]; then
  932. echo "OK: all services healthy"
  933. exit 0
  934. fi
  935. # 区分"重建"还是"普通故障":/usr 关键二进制都没了 => 重建
  936. if [ ! -x /usr/bin/crontab ] || [ ! -x /usr/sbin/sshd ] || [ ! -f /usr/local/bin/cf-probe ]; then
  937. echo "REBUILD_DETECTED: missing base binaries; failed:$failures"
  938. exit 1
  939. fi
  940. echo "DEGRADED: failed:$failures"
  941. exit 1
  942. ```
  943. ### 代码 7/13:`restore-all.sh`(Layer 3 一键恢复,幂等)
  944. **目标路径**:`~/workspace/setup/restore-all.sh` **权限**:`chmod +x`
  945. ```bash
  946. #!/usr/bin/env bash
  947. # restore-all.sh — 沙盒重建后一键恢复(幂等,可重复执行):
  948. # 基础包(cron/openssh, 优先离线缓存) → hermes → cf-probe → cron定时任务 → sshd → 看门狗
  949. # 锁:脚本内部原子 mkdir(不用外层 flock,避免 fd 被拉起的守护进程继承导致后续恢复被跳过)。
  950. set -uo pipefail
  951. # HOME 加固:若当前 HOME 下找不到 setup 目录但 /home/hatch 下有,
  952. # 说明运行环境异常(如 HOME=/root),纠正后再继续(见 skill 避坑)
  953. if [ ! -d "$HOME/workspace/setup" ] && [ -d /home/hatch/workspace/setup ]; then
  954. export HOME=/home/hatch
  955. fi
  956. SETUP_DIR="$HOME/workspace/setup"
  957. LOG="$SETUP_DIR/logs/restore.log"
  958. LOCKDIR="$SETUP_DIR/.restore.lock"
  959. MAX_RESTORE_SEC=1200 # 20 分钟:超时视为 stale 锁
  960. # shellcheck disable=SC1091
  961. . "$SETUP_DIR/lib-pkgs.sh"
  962. export PATH="$HOME/.local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
  963. export DEBIAN_FRONTEND=noninteractive
  964. mkdir -p "$SETUP_DIR/logs"
  965. log() { echo "[$(date '+%F %T')] $*" | tee -a "$LOG"; }
  966. # --- 单实例锁(带超时的 stale 回收;恢复是限时操作,年龄规则可用) ---
  967. if ! mkdir "$LOCKDIR" 2>/dev/null; then
  968. if [ -f "$LOCKDIR/pid" ] && [ -f "$LOCKDIR/started" ]; then
  969. oldpid=$(cat "$LOCKDIR/pid" 2>/dev/null || true)
  970. started=$(cat "$LOCKDIR/started" 2>/dev/null || echo 0)
  971. now=$(date +%s)
  972. alive=0
  973. if [ -n "$oldpid" ] && [ -f "/proc/$oldpid/cmdline" ] \
  974. && tr '\0' ' ' < "/proc/$oldpid/cmdline" 2>/dev/null | grep -q "[/]restore-all.sh"; then
  975. alive=1
  976. fi
  977. if [ "$alive" = 1 ] && [ $((now - started)) -lt "$MAX_RESTORE_SEC" ]; then
  978. log "已有恢复在进行中,本次退出"
  979. exit 0
  980. fi
  981. log "检测到 stale 锁(pid=$oldpid),回收后继续"
  982. fi
  983. rm -rf "$LOCKDIR"
  984. mkdir "$LOCKDIR" 2>/dev/null || { log "抢锁失败,退出"; exit 0; }
  985. fi
  986. echo $$ > "$LOCKDIR/pid"
  987. date +%s > "$LOCKDIR/started"
  988. trap 'rm -rf "$LOCKDIR"' EXIT
  989. log "===== 开始恢复 ====="
  990. # --- 0. 等 apt/dpkg 锁(重建后平台可能在做包 reconciling,最多等 10 分钟) ---
  991. for i in $(seq 1 20); do
  992. if ! fuser /var/lib/dpkg/lock-frontend >/dev/null 2>&1 \
  993. && ! fuser /var/lib/apt/lists/lock >/dev/null 2>&1; then
  994. break
  995. fi
  996. log "apt/dpkg 锁被占用,等待 30s ($i/20)"
  997. sleep 30
  998. done
  999. # --- 1. 基础包:cron(定时任务)、openssh-server(sshd) ---
  1000. need_pkgs=0
  1001. [ -x /usr/bin/crontab ] || need_pkgs=1
  1002. [ -x /usr/sbin/sshd ] || need_pkgs=1
  1003. if [ "$need_pkgs" = 1 ]; then
  1004. log "安装基础包(优先离线缓存)"
  1005. if install_offline_debs "$SETUP_DIR/deb-cache" "$LOG" \
  1006. && [ -x /usr/bin/crontab ] && [ -x /usr/sbin/sshd ]; then
  1007. log "离线缓存安装成功"
  1008. else
  1009. log "离线缓存不可用/不完整,回退 apt(可能较慢)"
  1010. apt-get update -qq >>"$LOG" 2>&1
  1011. apt-get install -y -o Dpkg::Options::="--force-confdef" -o Dpkg::Options::="--force-confold" \
  1012. cron openssh-server >>"$LOG" 2>&1 || log "WARN: apt 安装基础包失败"
  1013. fi
  1014. else
  1015. log "基础包已存在,跳过"
  1016. fi
  1017. # --- 2. hermes(现有脚本,幂等:重装 + 恢复用户数据 + 重启网关) ---
  1018. log "恢复 hermes"
  1019. bash "$SETUP_DIR/restore-hermes.sh" >>"$LOG" 2>&1 && log "hermes 恢复完成" || log "WARN: hermes 恢复失败"
  1020. # --- 3. cf-probe 探针(安装脚本幂等) ---
  1021. log "安装 cf-probe"
  1022. bash "$SETUP_DIR/run-probe-install.sh" >>"$LOG" 2>&1 && log "cf-probe 安装完成" || log "WARN: cf-probe 安装失败"
  1023. # --- 4. cron 定时任务:看门狗每 1 分钟(仓库推荐 1 分钟一轮询) ---
  1024. if [ -x /usr/bin/crontab ]; then
  1025. (crontab -l 2>/dev/null | grep -v "watchdog.sh"; echo "* * * * * $SETUP_DIR/watchdog.sh") | crontab -
  1026. log "cron 定时任务已写入"
  1027. # 确保 cron 守护进程在跑
  1028. if ! pgrep -f "[/]usr/sbin/cron" >/dev/null 2>&1; then
  1029. (service cron start >>"$LOG" 2>&1 || /usr/sbin/cron >>"$LOG" 2>&1) && log "cron 守护进程已启动" || log "WARN: cron 守护进程启动失败"
  1030. fi
  1031. else
  1032. log "WARN: crontab 不可用,定时任务未写入"
  1033. fi
  1034. # --- 5. sshd ---
  1035. if [ -x /usr/sbin/sshd ]; then
  1036. mkdir -p /run/sshd
  1037. chown root:root /run/sshd; chmod 755 /run/sshd
  1038. [ -f /etc/ssh/ssh_host_rsa_key ] || ssh-keygen -A >>"$LOG" 2>&1
  1039. if ! pgrep -f "[/]usr/sbin/sshd" >/dev/null 2>&1; then
  1040. /usr/sbin/sshd >>"$LOG" 2>&1 && log "sshd 已启动" || log "WARN: sshd 启动失败"
  1041. else
  1042. log "sshd 已在运行"
  1043. fi
  1044. else
  1045. log "WARN: sshd 二进制缺失"
  1046. fi
  1047. # --- 6. 立刻跑一次看门狗做最终校验 ---
  1048. log "运行看门狗做最终校验"
  1049. bash "$SETUP_DIR/watchdog.sh" >>"$LOG" 2>&1
  1050. log "===== 恢复结束 ====="
  1051. echo "OK: 恢复流程结束,详见 $LOG"
  1052. ```
  1053. ### 代码 8/13:`restore-hermes.sh`(Hermes 恢复:健康就什么都不做)
  1054. **目标路径**:`~/workspace/setup/restore-hermes.sh` **权限**:`chmod +x`
  1055. ```bash
  1056. #!/usr/bin/env bash
  1057. # restore-hermes.sh — 沙盒重建后恢复 Hermes Agent(幂等,可反复跑)。
  1058. #
  1059. # 原理:Hermes 的一切都在 $HOME 下(~/.hermes 程序+数据、~/.local/bin 启动器),
  1060. # 沙盒重建只丢系统目录,所以通常只需重跑一次安装脚本即可恢复。
  1061. #
  1062. # 三条硬规则(2026-09-26 实测踩过,违反必然导致微信全链路静默失败):
  1063. # 1. 健康时【完全跳过 installer】。installer 的 post-build maintenance 会动
  1064. # ~/.hermes/state.db;网关正在运行、句柄在 state.db 上时被换掉文件,
  1065. # 网关会抛 StateDbReplacedError 并拒绝一切写入(=所有微信回复失败)。
  1066. # 所以:hermes 可用 且 数据完好 → 什么都不做,只确保网关在跑。
  1067. # 2. 真正要动东西(缺 hermes / 缺数据)时,先【安全停网关】再动手,做完重新启动。
  1068. # 停网关优先用 gateway.pid 里的 pid(该文件是 JSON,不是裸数字),
  1069. # 校验 /proc/<pid>/cmdline 命中网关进程模式(hermes-agent.*[g]ateway)才 kill;拿不到就枚举
  1070. # pgrep 命中的进程(排除自身与父进程),绝不用 `pkill -f` 一把梭。
  1071. # 3. 账号判断必须用 `compgen -G`:`[ -f dir/*.json ]` 在匹配到多个文件时
  1072. # 报 "too many arguments" 恒为假,症状就是"重建后网关起不来"。
  1073. #
  1074. # 退出码:0=一切就绪;1=有步骤失败(日志里能看到是哪一步)。
  1075. set -uo pipefail
  1076. # 允许测试夹具覆盖(生产不设此变量,走 $HOME/workspace/setup)
  1077. SETUP_DIR="${HERMES_SETUP_DIR:-$HOME/workspace/setup}"
  1078. SAVED="$SETUP_DIR/hermes-install.sh"
  1079. LATEST="$SETUP_DIR/hermes-install.latest.sh"
  1080. BACKUP="$HOME/workspace/backups/hermes-home"
  1081. INSTALL_URL="https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh"
  1082. GWLOG="$HOME/.hermes/logs/weixin-gateway.log"
  1083. export PATH="$HOME/.local/bin:$PATH"
  1084. log() { echo "[restore-hermes] $*"; }
  1085. rc=0
  1086. # --- 读 gateway.pid(JSON 格式:{"pid": 12345, "kind": "hermes-gateway", ...}) ---
  1087. gateway_pid() {
  1088. local f="$HOME/.hermes/gateway.pid" p=""
  1089. [ -f "$f" ] || return 0
  1090. if command -v jq >/dev/null 2>&1; then
  1091. p="$(jq -r '.pid // empty' "$f" 2>/dev/null || true)"
  1092. fi
  1093. if [ -z "$p" ]; then
  1094. p="$(python3 -c 'import json,sys;print(json.load(open(sys.argv[1])).get("pid",""))' "$f" 2>/dev/null || true)"
  1095. fi
  1096. [ -n "$p" ] && printf '%s' "$p"
  1097. return 0
  1098. }
  1099. # --- 停网关:只杀真的是网关的进程 ---
  1100. stop_gateway() {
  1101. local pid mypid ppid_ pids p waited ok
  1102. mypid=$$
  1103. ppid_="$PPID"
  1104. pid="$(gateway_pid)"
  1105. if [ -n "$pid" ] && [ -f "/proc/$pid/cmdline" ] \
  1106. && tr '\0' ' ' < "/proc/$pid/cmdline" 2>/dev/null | grep -q "hermes-agent.*[g]ateway"; then
  1107. log "按 gateway.pid 精确停网关 pid=$pid"
  1108. kill -TERM "$pid" 2>/dev/null || true
  1109. waited=0
  1110. while [ "$waited" -lt 30 ]; do
  1111. kill -0 "$pid" 2>/dev/null || break
  1112. sleep 1; waited=$((waited + 1))
  1113. done
  1114. if kill -0 "$pid" 2>/dev/null; then
  1115. log "WARN 网关 ${waited}s 未退出,SIGKILL pid=$pid"
  1116. kill -KILL "$pid" 2>/dev/null || true
  1117. sleep 2
  1118. fi
  1119. kill -0 "$pid" 2>/dev/null && { log "ERROR 网关仍在运行"; return 1; }
  1120. log "网关已停止"
  1121. return 0
  1122. fi
  1123. # pidfile 不可用:枚举命中进程(排除自身和父进程,避免误杀调用者)
  1124. pids=""
  1125. for p in $(pgrep -f "hermes-agent.*[g]ateway" 2>/dev/null || true); do
  1126. [ "$p" = "$mypid" ] && continue
  1127. [ "$p" = "$ppid_" ] && continue
  1128. pids="$pids $p"
  1129. done
  1130. [ -n "$pids" ] || { log "网关未在运行,无需停"; return 0; }
  1131. log "pidfile 不可用,按 pgrep 命中停止:$pids"
  1132. # shellcheck disable=SC2086
  1133. kill -TERM $pids 2>/dev/null || true
  1134. waited=0; ok=0
  1135. while [ "$waited" -lt 30 ]; do
  1136. ok=1
  1137. for p in $pids; do
  1138. kill -0 "$p" 2>/dev/null && ok=0
  1139. done
  1140. [ "$ok" = 1 ] && break
  1141. sleep 1; waited=$((waited + 1))
  1142. done
  1143. if [ "$ok" = 0 ]; then
  1144. log "WARN 仍有网关进程未退出,SIGKILL 剩余进程"
  1145. for p in $pids; do kill -0 "$p" 2>/dev/null && kill -KILL "$p" 2>/dev/null || true; done
  1146. sleep 2
  1147. fi
  1148. for p in $pids; do
  1149. kill -0 "$p" 2>/dev/null && { log "ERROR 网关进程 $p 仍在运行"; return 1; }
  1150. done
  1151. log "网关已停止"
  1152. return 0
  1153. }
  1154. # --- 启动网关:没在跑才启动(避免双实例) ---
  1155. start_gateway_if_needed() {
  1156. if pgrep -f "hermes-agent.*[g]ateway" >/dev/null 2>&1; then
  1157. log "微信网关已在运行,无需启动"
  1158. return 0
  1159. fi
  1160. if compgen -G "$HOME/.hermes/weixin/accounts/*.json" > /dev/null 2>&1; then
  1161. mkdir -p "$HOME/.hermes/logs"
  1162. nohup hermes gateway run >> "$GWLOG" 2>&1 &
  1163. sleep 3
  1164. if pgrep -f "hermes-agent.*[g]ateway" >/dev/null 2>&1; then
  1165. log "微信网关已启动"
  1166. return 0
  1167. fi
  1168. log "ERROR 网关启动后仍无进程,看 $GWLOG"
  1169. return 1
  1170. fi
  1171. log "无微信账号凭据,跳过网关启动"
  1172. return 0
  1173. }
  1174. # --- 安装/升级 hermes(只在真的需要时调用) ---
  1175. install_hermes() {
  1176. local install_sh=""
  1177. if curl -fsSL "$INSTALL_URL" -o "$LATEST" 2>/dev/null; then
  1178. install_sh="$LATEST"
  1179. cp "$LATEST" "$SAVED"
  1180. log "使用最新官方安装脚本(已更新本地缓存 $SAVED)"
  1181. elif [ -f "$SAVED" ]; then
  1182. install_sh="$SAVED"
  1183. log "WARN 无法下载最新安装脚本,使用本地缓存 $SAVED"
  1184. else
  1185. log "ERROR 安装脚本不可用(无网且无本地缓存),无法安装 hermes"
  1186. return 1
  1187. fi
  1188. if bash "$install_sh" --non-interactive --skip-browser; then
  1189. export PATH="$HOME/.local/bin:$PATH"
  1190. hermes --version || log "WARN hermes --version 返回非 0"
  1191. log "hermes 安装/升级完成"
  1192. return 0
  1193. fi
  1194. log "ERROR 安装脚本执行失败"
  1195. return 1
  1196. }
  1197. # --- 从备份恢复用户数据(只在数据缺失时调用;调用方必须已停网关) ---
  1198. restore_user_data() {
  1199. if [ ! -d "$BACKUP" ]; then
  1200. log "ERROR ~/.hermes 数据缺失,且没有备份目录 $BACKUP"
  1201. return 1
  1202. fi
  1203. if command -v rsync >/dev/null 2>&1; then
  1204. rsync -a "$BACKUP/" "$HOME/.hermes/"
  1205. else
  1206. cp -a "$BACKUP/." "$HOME/.hermes/"
  1207. fi
  1208. chmod 600 "$HOME/.hermes/.env" 2>/dev/null || true
  1209. log "用户数据已从备份恢复"
  1210. return 0
  1211. }
  1212. # ============================ 主流程 ============================
  1213. hermes_ok=0
  1214. if command -v hermes >/dev/null 2>&1 && hermes --version >/dev/null 2>&1; then
  1215. hermes_ok=1
  1216. fi
  1217. data_ok=0
  1218. if [ -f "$HOME/.hermes/config.yaml" ] && [ -f "$HOME/.hermes/state.db" ]; then
  1219. data_ok=1
  1220. fi
  1221. gw_running=0
  1222. pgrep -f "hermes-agent.*[g]ateway" >/dev/null 2>&1 && gw_running=1
  1223. log "检查:hermes_ok=$hermes_ok data_ok=$data_ok gateway_running=$gw_running"
  1224. if [ "$hermes_ok" = 1 ] && [ "$data_ok" = 1 ]; then
  1225. log "hermes 与用户数据都完好:跳过 installer 与数据恢复(不动 state.db)"
  1226. else
  1227. # 有活要干:先确认网关停干净
  1228. if [ "$gw_running" = 1 ]; then
  1229. stop_gateway || { log "ERROR 网关未能停干净,为避免 state.db 被换掉,本次中止"; exit 1; }
  1230. fi
  1231. if [ "$hermes_ok" = 0 ]; then
  1232. install_hermes || rc=1
  1233. fi
  1234. if [ "$data_ok" = 0 ]; then
  1235. restore_user_data || rc=1
  1236. fi
  1237. fi
  1238. start_gateway_if_needed || rc=1
  1239. if [ "$rc" = 0 ]; then
  1240. echo "OK: hermes 已就绪"
  1241. else
  1242. echo "FAIL: hermes 恢复未完成,详见上面的 [restore-hermes] 日志" >&2
  1243. fi
  1244. exit "$rc"
  1245. ```
  1246. ### 代码 9/13:`backup-hermes.sh`(手动备份,fail closed)
  1247. **目标路径**:`~/workspace/setup/backup-hermes.sh` **权限**:`chmod +x`
  1248. **重要**:这是**手动**脚本,**不要**加进 cron——它每次都会读三个活库,和恢复流程抢 IO 没有意义。
  1249. ```bash
  1250. #!/usr/bin/env bash
  1251. # backup-hermes.sh — 把 ~/.hermes 里不可再生的用户数据备份到 workspace。
  1252. #
  1253. # 备份内容:config.yaml、.env(含 API Key)、memories/、skills/、sessions/、hooks/ 等
  1254. # 排除内容:hermes-agent/(git 仓库可重下)、tools/(可重装)、cache/、installs/、logs/
  1255. #
  1256. # 安全规则(2026-09-26 复核后收紧为 fail closed):
  1257. # ~/.hermes 里有三个 WAL 模式的活跃数据库(state.db / kanban.db / shared-state.db)。
  1258. # 网关运行时用 rsync/cp 直接复制 db+WAL+SHM 会得到跨时刻的撕裂快照——
  1259. # 压测实测单轮最多静默丢 38000 行,而且 `PRAGMA integrity_check` 对撕裂备份
  1260. # 照样返回 ok,也就是说"拷完跑个 integrity_check"根本验证不出这个 bug。
  1261. # 所以:三个库一律 `sqlite3 .backup` 在线热备;
  1262. # **任何一步失败就地停手(exit 1),绝不回退到裸 cp**——
  1263. # 回退裸 cp 会把一份可能撕裂的库盖到上一份好备份上,等于用坏备份换掉好备份。
  1264. # 失败时保留上一份好备份,并打印明确错误让人来处理。
  1265. #
  1266. # 实现要点(都是实测踩出来的):
  1267. # - 热备产物写到 DST 之外的 stage 目录。不能放在 DST 里:rsync --delete 会把
  1268. # 源目录里不存在的文件删掉,临时文件正好会被它顺手清理掉(实测 mv 时文件已消失)。
  1269. # - 全部成功后才把三个库 mv 进 DST(同文件系统 rename,原子);失败整次作废,
  1270. # 三个库都保持上一份好备份。
  1271. # - .last-success 只在整次成功时写,并被 rsync 排除,用来回答"到底哪次成功过"。
  1272. # 退出码:0=全部成功;1=至少一个库失败(旧备份保持不变)。
  1273. set -euo pipefail
  1274. SRC="$HOME/.hermes"
  1275. DST="$HOME/workspace/backups/hermes-home"
  1276. STAGE="$HOME/workspace/backups/.hermes-db-stage"
  1277. SQLITE_DBS="state.db kanban.db shared-state.db"
  1278. failed=0
  1279. err() { echo "[error] $*" >&2; failed=1; }
  1280. mkdir -p "$DST"
  1281. rm -rf "$STAGE"
  1282. mkdir -p "$STAGE"
  1283. # --- 0. 前置检查:有活库就必须有 sqlite3;没有就 fail closed,不做任何降级复制 ---
  1284. need_sqlite=0
  1285. for db in $SQLITE_DBS; do
  1286. [ -f "$SRC/$db" ] && need_sqlite=1
  1287. done
  1288. if [ "$need_sqlite" = 1 ] && ! command -v sqlite3 >/dev/null 2>&1; then
  1289. err "本机没有 sqlite3,无法为 3 个 WAL 活库做一致备份。请先装(apt-get install -y sqlite3)后重跑;本次未改动备份目录。"
  1290. exit 1
  1291. fi
  1292. # --- 1. 数据库:在线热备到 stage(完全不碰 DST 里的旧备份) ---
  1293. declare -A TMP_DB=()
  1294. for db in $SQLITE_DBS; do
  1295. [ -f "$SRC/$db" ] || { echo "[info] $SRC/$db 不存在,跳过"; continue; }
  1296. tmp="$STAGE/$db"
  1297. rm -f "$tmp"
  1298. if ! sqlite3 "$SRC/$db" ".backup '$tmp'" 2>/dev/null; then
  1299. rm -f "$tmp"
  1300. err "$db 在线热备失败(sqlite3 .backup 返回非 0)。旧备份已保留,未做任何覆盖。"
  1301. continue
  1302. fi
  1303. # 备份产物自身的可读性检查(注意:这发现不了"撕裂",撕裂是靠 .backup 本身避免的)
  1304. if ! sqlite3 "$tmp" "PRAGMA quick_check;" 2>/dev/null | grep -q '^ok$'; then
  1305. rm -f "$tmp"
  1306. err "$db 热备产物 quick_check 未返回 ok。旧备份已保留。"
  1307. continue
  1308. fi
  1309. TMP_DB["$db"]="$tmp"
  1310. echo "[info] $db 在线热备完成(stage)"
  1311. done
  1312. # --- 2. 其它文件(排除三个库及其 WAL/SHM,它们走上面的热备路径) ---
  1313. if command -v rsync >/dev/null 2>&1; then
  1314. rsync -a --delete \
  1315. --exclude 'hermes-agent/' \
  1316. --exclude 'tools/' \
  1317. --exclude 'cache/' \
  1318. --exclude 'installs/' \
  1319. --exclude 'logs/' \
  1320. --exclude '.last-success' \
  1321. --exclude 'state.db' --exclude 'state.db-wal' --exclude 'state.db-shm' \
  1322. --exclude 'kanban.db' --exclude 'kanban.db-wal' --exclude 'kanban.db-shm' \
  1323. --exclude 'shared-state.db' --exclude 'shared-state.db-wal' --exclude 'shared-state.db-shm' \
  1324. "$SRC/" "$DST/" || err "rsync 复制非数据库文件失败"
  1325. else
  1326. # 无 rsync 时的降级方案:tar 管道到临时目录再合并
  1327. rm -rf "$DST.new"
  1328. mkdir -p "$DST.new"
  1329. tar --exclude='hermes-agent' --exclude='tools' --exclude='cache' \
  1330. --exclude='installs' --exclude='logs' \
  1331. --exclude='state.db' --exclude='state.db-wal' --exclude='state.db-shm' \
  1332. --exclude='kanban.db' --exclude='kanban.db-wal' --exclude='kanban.db-shm' \
  1333. --exclude='shared-state.db' --exclude='shared-state.db-wal' --exclude='shared-state.db-shm' \
  1334. -cf - -C "$HOME" .hermes | tar -xf - -C "$DST.new" --strip-components=1 \
  1335. || err "tar 复制非数据库文件失败"
  1336. (cd "$DST.new" && tar -cf - .) | (cd "$DST" && tar -xf -) || err "合并非数据库文件失败"
  1337. rm -rf "$DST.new"
  1338. fi
  1339. # --- 3. 只有全部成功才把热备产物顶上去,并清理残留 WAL/SHM ---
  1340. if [ "$failed" = 0 ]; then
  1341. for db in $SQLITE_DBS; do
  1342. [ -n "${TMP_DB[$db]:-}" ] || continue
  1343. mv -f "${TMP_DB[$db]}" "$DST/$db"
  1344. rm -f "$DST/$db-wal" "$DST/$db-shm"
  1345. echo "[info] $db 已就位(原子替换)"
  1346. done
  1347. rm -rf "$STAGE"
  1348. date -Is > "$DST/.last-success"
  1349. echo "backup -> $DST"
  1350. du -sh "$DST"
  1351. exit 0
  1352. fi
  1353. # 失败:整次作废,明确保留上一份好备份
  1354. rm -rf "$STAGE"
  1355. echo "[error] 备份未完成:上一份好备份仍原样保留在 $DST(上次成功时间见 $DST/.last-success)" >&2
  1356. exit 1
  1357. ```
  1358. ## 十一、步骤 8:离线包缓存(deb + 探针二进制)
  1359. **目标**:把 `cron`、`openssh-server` 依赖闭包和 cf-probe 二进制都缓存到 `$HOME`,重建后**不依赖网络**也能装回系统组件。
  1360. > 只缓存安装脚本不够:`install.sh` 还要去 GitHub releases 拉二进制,断网时照样装不上。
  1361. > `releases/latest/download/cf-probe-linux-amd64` 与安装器装出的 `/usr/local/bin/cf-probe` sha256 一致,自带 `install` 子命令,可直接当安装器。
  1362. ### ① 🤖 AI 执行(命令)
  1363. **A. deb 依赖闭包(完整、可复现;不要只 `apt-get download cron openssh-server`)**
  1364. ```bash
  1365. cd ~/workspace/setup/deb-cache
  1366. # 1) 算依赖闭包:从 cron + openssh 出发递归展开,去掉 recommends/suggests/conflicts 等分支
  1367. apt-get update -qq
  1368. apt-cache depends --recurse --no-recommends --no-suggests --no-conflicts \
  1369. --no-breaks --no-replaces --no-enhances \
  1370. cron openssh-server openssh-client openssh-sftp-server 2>/dev/null \
  1371. | grep '^[a-z0-9]' | sort -u > /tmp/closure.txt
  1372. # 2) 只保留"当前镜像里真实安装着"的包:
  1373. # 闭包里会出现 systemd-standalone-sysusers / opensysusers / cdebconf 这类【互斥替代品】,
  1374. # 而 lib-pkgs.sh 是"把缓存里缺的包一次性 dpkg -i",互相冲突的包会直接装失败。
  1375. while read -r p; do dpkg -l "$p" 2>/dev/null | grep -q '^ii' && echo "$p"; done \
  1376. < /tmp/closure.txt > /tmp/closure.installed.txt
  1377. grep -vxE 'systemd-standalone-sysusers|opensysusers|cdebconf|libdebian-installer4|libtextwrap1' \
  1378. /tmp/closure.installed.txt > /tmp/closure.final.txt
  1379. # 3) 下载(注意用 apt-get download:它对"已安装"的包也照样下,不用先卸载;
  1380. # 用 install --download-only 会因为"已是最新"而一个都不下)
  1381. cd ~/workspace/setup/deb-cache
  1382. xargs -a /tmp/closure.final.txt apt-get download
  1383. # 4) 验证:数量、关键包、可解析
  1384. ls *.deb | wc -l # 期望 ≥ 70(参考实现 74 个,约 21MB)
  1385. for p in cron cron-daemon-common openssh-server openssh-client openssh-sftp-server; do
  1386. ls ${p}_*.deb >/dev/null 2>&1 && echo "OK $p" || echo "MISSING $p"
  1387. done
  1388. for d in *.deb; do dpkg-deb -f "$d" Package >/dev/null 2>&1 || echo "BAD $d"; done; echo "全部 .deb 可解析"
  1389. du -sh . # 期望 ~21M
  1390. ```
  1391. **B. 探针二进制缓存**
  1392. ```bash
  1393. bash ~/workspace/setup/cache-cf-probe-bin.sh
  1394. ls -l ~/workspace/setup/cf-probe-linux-amd64 ~/workspace/setup/cf-probe-linux-amd64.sha256
  1395. ```
  1396. **C.(建议)Hermes 安装脚本缓存**:`restore-hermes.sh` 会在下载失败时用 `~/workspace/setup/hermes-install.sh`。首次装完 Hermes 后,确认它存在:
  1397. ```bash
  1398. ls -l ~/workspace/setup/hermes-install.sh # 不存在就见步骤 9,restore-hermes.sh 会自动落一份
  1399. ```
  1400. ### ② 💬 对用户说(可原样发送)
  1401. > 💾 现在把"重建后要用的安装包"提前缓存到本地。这样沙盒被重建、网络又不好的时候,系统组件也能装回来:
  1402. >
  1403. > - `cron` + `openssh` 及其依赖(约 21MB,70 多个 .deb)
  1404. > - 探针二进制(约 7.5MB)
  1405. >
  1406. > 你什么都不用做,我看完数量继续。
  1407. ### ③ 🙋 用户手动做
  1408. 无。
  1409. ### ④ ✅ 做完的标志
  1410. ```bash
  1411. ls ~/workspace/setup/deb-cache/*.deb | wc -l # ≥ 70
  1412. ls ~/workspace/setup/cf-probe-linux-amd64 >/dev/null && echo "二进制缓存 OK"
  1413. cat ~/workspace/setup/cf-probe-linux-amd64.sha256 # 有值即可(这是校验和,不是密钥)
  1414. ```
  1415. 判据:deb 数量 ≥ 70、关键包五个都在、二进制缓存存在且带 sha256。
  1416. ### ⑤ 🛠️ 常见失败与处理
  1417. | 现象 | 原因 | 处理 |
  1418. | ------------------------------------------------ | -------------------------------------------------------- | ------------------------------------------------------------- |
  1419. | `apt-get download` 报 `Unable to locate package` | apt 列表为空 / 源不可达 | 先 `apt-get update`;仍失败就换源或从能上网的机器拷 .deb 过来 |
  1420. | 一个 .deb 都没下下来 | 用了 `install --download-only`(已安装的包不会重复下载) | 改用 `apt-get download`(本手册的写法) |
  1421. | 数量只有 5、6 个 | 只下了显式列出的包,没算闭包 | 用第 1 步的 `apt-cache depends --recurse` 生成完整列表 |
  1422. | 装的时候 `dpkg` 报冲突 | 缓存里混进了互斥替代品(systemd-standalone-sysusers 等) | 用第 2 步的过滤规则重建列表 |
  1423. | 二进制缓存自检失败 | 下载到的是错误页面(代理/网关拦截) | 删掉重下;确认 `curl -I` 拿到的是 `application/octet-stream` |
  1424. | deb-cache 占空间大 | 闭包包含已装的运行时库(libc6、systemd 等) | 正常,约 21MB;不要为了省空间删依赖 |
  1425. ---
  1426. # 模块 D|微信机器人(Hermes + 模型 API + 扫码,步骤 9–10)
  1427. 装 Hermes、接上用户自己的模型接口,再用手机扫码把微信绑到网关,最后过一遍首次私聊的配对。**用户介入**:给模型 API 地址与 Key、微信扫码并确认、把机器人回的配对码转给 AI。
  1428. ## 十二、步骤 9:安装 Hermes + 配置模型 API
  1429. **目标**:Hermes 装好、能跑,接上用户自己的 OpenAI 兼容模型接口。
  1430. ### ① 🤖 AI 执行(命令)
  1431. ```bash
  1432. # 1. 安装/恢复 Hermes(幂等;健康时会自动跳过 installer,见脚本注释)
  1433. bash ~/workspace/setup/restore-hermes.sh
  1434. # 2. 确认可用
  1435. export PATH="$HOME/.local/bin:$PATH"
  1436. hermes --version
  1437. # 3. 写模型配置(真实地址只写进 config.yaml,不进任何文档)
  1438. # 幂等:已存在 my-api provider 就不重复追加(重跑不会写出第二份 model:/providers: 块)
  1439. if ! grep -q 'my-api' ~/.hermes/config.yaml 2>/dev/null; then
  1440. cat >> ~/.hermes/config.yaml <<'YAML_EOF'
  1441. model:
  1442. default: "<MODEL_NAME>"
  1443. provider: "my-api"
  1444. providers:
  1445. my-api:
  1446. base_url: "<API_BASE_URL>"
  1447. key_env: "MY_API_KEY"
  1448. YAML_EOF
  1449. echo "模型配置已写入"
  1450. else
  1451. echo "模型配置已存在,跳过(要改地址/模型请手动编辑 ~/.hermes/config.yaml)"
  1452. fi
  1453. # 4. Key 写进 .env(600),值从环境变量来,不进 shell 历史
  1454. # USER_MODEL_KEY 由用户经安全页面提供(值只经环境变量传入)
  1455. # 幂等:已存在 MY_API_KEY= 就不重复追加(否则下面的 grep -c 期望 1 会失败)
  1456. if ! grep -q '^MY_API_KEY=' ~/.hermes/.env 2>/dev/null; then
  1457. printf 'MY_API_KEY=%s\n' "$USER_MODEL_KEY" >> ~/.hermes/.env
  1458. echo "MY_API_KEY 已写入"
  1459. else
  1460. echo "MY_API_KEY 已存在,跳过(要换 Key 请先删掉该行再重跑)"
  1461. fi
  1462. chmod 600 ~/.hermes/.env
  1463. unset USER_MODEL_KEY
  1464. # 5. 自检:模型配置读得到、Key 存在(只打印布尔值和长度,不打印值)
  1465. grep -q 'my-api' ~/.hermes/config.yaml && echo "provider 配置已写入"
  1466. grep -c '^MY_API_KEY=' ~/.hermes/.env # 期望 1
  1467. awk -F= '/^MY_API_KEY=/{print "MY_API_KEY 长度: " length($2)}' ~/.hermes/.env
  1468. ```
  1469. **连通性自检**(推荐做,避免"装好了但一问就报错"):
  1470. ```bash
  1471. hermes --non-interactive "只回复两个字:在线" 2>&1 | tail -5
  1472. ```
  1473. ### ② 💬 对用户说(可原样发送)
  1474. > 🧠 现在装 Hermes(微信机器人的大脑)并接你的模型 API。需要你提供两样:
  1475. >
  1476. > 1. **接口地址**:形如 `http://<主机>:<端口>/v1`(OpenAI 兼容);
  1477. > 2. **API Key**:**走安全页面**发我,别贴在聊天里。
  1478. > 3. **模型名**:你那个接口上要用的模型标识(比如 `deepseek-v4.1-flash` 这类)。
  1479. >
  1480. > - 我写到 `~/.hermes/.env`(600 权限,只有本机能读);
  1481. ### ③ 🙋 用户手动做
  1482. - 通过安全页面提供 API 地址与 Key;提供模型名。
  1483. ### ④ ✅ 做完的标志
  1484. ```bash
  1485. export PATH="$HOME/.local/bin:$PATH"
  1486. hermes --version # 期望打印版本号
  1487. grep -q 'my-api' ~/.hermes/config.yaml && echo "配置 OK"
  1488. ls -l ~/.hermes/.env # 期望 -rw-------(600)
  1489. hermes --non-interactive "只回复两个字:在线" 2>&1 | tail -3 # 期望有正常回复,不是鉴权/连接错误
  1490. ```
  1491. 判据:版本号能打印 + 配置里有 provider + `.env` 权限 600 + 一次真实调用成功。
  1492. ### ⑤ 🛠️ 常见失败与处理
  1493. | 现象 | 原因 | 处理 |
  1494. | ------------------------------ | ------------------------------- | ------------------------------------------------------------------------------------------- |
  1495. | `hermes: command not found` | `~/.local/bin` 不在 PATH | `export PATH="$HOME/.local/bin:$PATH"`;网关用 `nohup hermes gateway run` 启动时会自带 PATH |
  1496. | 调用报 401/403 | Key 错、过期或没写进 `.env` | `grep -c '^MY_API_KEY=' ~/.hermes/.env`;值不要带引号 |
  1497. | 调用超时 | 地址端口不通 | 让用户确认地址可从沙盒访问(`curl -m 8 <API_BASE_URL>/models`);国内机房注意出网策略 |
  1498. | installer 反复重装、把网关搞挂 | installer 无条件跑会动 state.db | 用本手册的 `restore-hermes.sh`:健康时跳过 installer,需要时才停网关 |
  1499. | `.env` 权限变成 644 | 复制/编辑时改了权限 | `chmod 600 ~/.hermes/.env`(里面是所有密钥) |
  1500. ## 十三、步骤 10:绑定微信(扫码登录)
  1501. **目标**:微信账号绑定到 Hermes 网关,用户能在微信里跟机器人对话。
  1502. > iLink 机器人登录:取二维码 → 用户扫码确认 → 凭据落 `~/.hermes/weixin/accounts/<account_id>.json`(网关读它)。**限制**:私聊可用,普通群消息可能收不到(非故障)。**首次私聊需配对**:机器人先回 8 位配对码而非内容,`hermes pairing approve weixin <配对码>` 批准后再发一次才有回复。
  1503. ### ① 🤖 AI 执行(命令)
  1504. ```bash
  1505. # 0. 依赖:二维码渲染需要 qrcode(含 PIL)
  1506. python3 -c 'import qrcode' 2>/dev/null || python3 -m pip install "qrcode[pil]"
  1507. # 1. 落盘两个辅助脚本(代码见下)到 ~/workspace/setup/
  1508. # weixin-qr-fetch.py / weixin-qr-confirm.py
  1509. # 2. 取二维码(生成 PNG)
  1510. python3 ~/workspace/setup/weixin-qr-fetch.py # 输出:QR saved: <...>/weixin-login-qr.png
  1511. # 3. 把 PNG 发给用户扫:在会话里用 MEDIA: 标记;如果需要在回合外发,用
  1512. hermes send --to weixin:<chat_id> "MEDIA:$HOME/workspace/your_files/weixin-login-qr.png"
  1513. # 4. 立刻开始轮询确认(180 秒内有效)
  1514. python3 ~/workspace/setup/weixin-qr-confirm.py; echo "rc=$?"
  1515. # 5. 确认成功后,把网关需要的两项写进 .env(值取自账号 json,不要打印出来)
  1516. python3 - <<'PY'
  1517. import json, glob, os, re
  1518. p = glob.glob(os.path.expanduser("~/.hermes/weixin/accounts/*@im.bot.json"))[0]
  1519. d = json.load(open(p))
  1520. acct = os.path.basename(p).replace(".json", "")
  1521. env = os.path.expanduser("~/.hermes/.env")
  1522. text = open(env).read() if os.path.exists(env) else ""
  1523. add = []
  1524. if "WEIXIN_ACCOUNT_ID=" not in text:
  1525. add.append(f"WEIXIN_ACCOUNT_ID={acct}")
  1526. if "WEIXIN_TOKEN=" not in text:
  1527. add.append(f"WEIXIN_TOKEN={d['token']}")
  1528. if add:
  1529. with open(env, "a") as f:
  1530. f.write("\n" + "\n".join(add) + "\n")
  1531. print("已写入 .env 的项:", [a.split('=')[0] for a in add], "(值不打印)")
  1532. PY
  1533. chmod 600 ~/.hermes/.env
  1534. # 6. 启动网关(后台常驻)
  1535. mkdir -p ~/.hermes/logs
  1536. nohup hermes gateway run >> ~/.hermes/logs/weixin-gateway.log 2>&1 &
  1537. sleep 3; pgrep -f "hermes-agent.*[g]ateway" >/dev/null && echo "网关已启动"
  1538. # 7. 批准配对(关键一步,别漏):让用户先在微信里给机器人发一条消息,
  1539. # 机器人回一个 8 位配对码(形如 3TNTE7PR)而不是内容——这是 Hermes 的 DM 配对安全机制。
  1540. # 拿到码后批准(把 <配对码> 换成用户发来的那串):
  1541. export PATH="$HOME/.local/bin:$PATH"
  1542. hermes pairing list # 看待批准/已批准的人
  1543. hermes pairing approve weixin <配对码> # 批准后该用户永久可用
  1544. # 批准是幂等的,再确认一次:已批准列表里有他,就算配对完成。
  1545. hermes pairing list
  1546. # 备注:weixin 适配器的 DM 策略由 WEIXIN_DM_POLICY 控制(open / allowlist / disabled / pairing)。
  1547. # 默认行为就是「配对」;我们不改它,只走一次性的 approve(比 open 更安全,比 allowlist 省事)。
  1548. # 若日后想彻底免配对(不建议,等同放开所有人),可设 WEIXIN_DM_POLICY=open 后重启网关。
  1549. ```
  1550. ### ② 💬 对用户说(可原样发送)
  1551. > 💬 Hermes 装好了,现在绑定微信。我马上把**二维码**发给你,请:
  1552. >
  1553. > 1. 用**手机微信扫码**;2. 手机上点**确认登录**;3. 扫完跟我说一声。
  1554. >
  1555. > 两点说明:
  1556. >
  1557. > - 二维码有效期约 3 分钟,过期我重新生成一张;
  1558. > - 绑好后**私聊**可用;**普通微信群消息可能收不到**(iLink 的限制,不是故障)。
  1559. >
  1560. > 绑定完成后,请你**在微信里先给机器人发一条消息**。注意:第一次它**不会回内容**,只会回一个**8 位配对码**(比如 `3TNTE7PR`)——这是它的安全机制,不是坏了。
  1561. >
  1562. > 请把这个**配对码发给我**,我批准一下;批准后再给它发一次消息,这次就有正常回复了。
  1563. ### ③ 🙋 用户手动做
  1564. - 扫码 + 手机确认登录。
  1565. - 在微信里给机器人发一条消息,把收到的 **8 位配对码**发给 AI。
  1566. - 等 AI 批准后,再发一次消息确认有回复。
  1567. ### ④ ✅ 做完的标志
  1568. ```bash
  1569. compgen -G "$HOME/.hermes/weixin/accounts/*.json" >/dev/null && echo "账号已绑定"
  1570. python3 -c "import glob,os;print([os.path.basename(p) for p in glob.glob(os.path.expanduser('~/.hermes/weixin/accounts/*.json'))])"
  1571. pgrep -f "hermes-agent.*[g]ateway" >/dev/null && echo "网关运行中"
  1572. grep -c '^WEIXIN_TOKEN=' ~/.hermes/.env # 期望 1(只数条数,不看值)
  1573. hermes pairing list # 期望:用户已在「已批准」列表里
  1574. ```
  1575. 判据:账号 json 存在 + 网关进程在 + `.env` 里有 `WEIXIN_TOKEN` + **用户已在 pairing 已批准列表** + **用户确认收到机器人正常回复**(不是配对码)。
  1576. ### ⑤ 🛠️ 常见失败与处理
  1577. | 现象 | 原因 | 处理 |
  1578. | ------------------------------------- | ------------------------------------------- | -------------------------------------------------------------------------------------------------- |
  1579. | `ModuleNotFoundError: qrcode` | 没装依赖 | `python3 -m pip install "qrcode[pil]"` |
  1580. | 二维码过期 | 用户扫得太慢 | 重跑 `weixin-qr-fetch.py` 生成新码(`confirm` 脚本会返回 2=expired) |
  1581. | 扫码后无反应 | 网络问题 | 看 `~/.hermes/logs/weixin-gateway.log` 尾部;确认沙盒能访问 iLink 域名 |
  1582. | 能收不能回 / 回复全失败 | `state.db` 被换过(`StateDbReplacedError`) | 停网关 → 让恢复脚本用本手册版本重跑 → 重新起网关(**不要在网关运行时覆盖 `~/.hermes/` 里的数据**) |
  1583. | 机器人只回配对码、不回内容 | 首次私聊未配对(Hermes 默认配对) | 让用户把配对码发来,`hermes pairing approve weixin <配对码>`;批准后再发消息即可 |
  1584. | `hermes pairing list` 为空 | 用户还没发过消息 / 网关没连上 | 让用户先给机器人发一条消息,等它回配对码;确认网关在跑 |
  1585. | 群里收不到消息 | iLink 机器人限制 | 如实说明:私聊可用,群聊可能收不到,不是配置问题 |
  1586. | `hermes send` 报 Weixin token missing | `.env` 里缺 `WEIXIN_TOKEN` | 按 ① 的第 5 步补写(网关自身读的是账号 json,所以机器人能收消息但 `hermes send` 会失败) |
  1587. ### 代码 10/13:`weixin-qr-fetch.py`(取二维码)
  1588. **目标路径**:`~/workspace/setup/weixin-qr-fetch.py`
  1589. ```python
  1590. #!/usr/bin/env python3
  1591. """取微信(iLink)登录二维码并渲染成 PNG,供用户扫码。
  1592. 用法:
  1593. python3 weixin-qr-fetch.py
  1594. 产物:
  1595. $HOME/workspace/your_files/weixin-login-qr.png ← 把这个 PNG 发给用户扫
  1596. $HOME/workspace/setup/weixin-qr-state.json ← 供 weixin-qr-confirm.py 续用
  1597. 依赖:python3 + qrcode(含 PIL)
  1598. 没有的话先装:python3 -m pip install "qrcode[pil]"
  1599. 或:uv pip install --python "$(command -v python3)" "qrcode[pil]"
  1600. """
  1601. import json
  1602. import os
  1603. import subprocess
  1604. import sys
  1605. try:
  1606. import qrcode
  1607. except ImportError: # 给出可执行的提示,别只抛 ModuleNotFoundError
  1608. print('缺少 qrcode 模块。请先执行: python3 -m pip install "qrcode[pil]"', file=sys.stderr)
  1609. sys.exit(4)
  1610. HOME = os.path.expanduser("~")
  1611. BASE_URL = "https://ilinkai.weixin.qq.com"
  1612. APP_ID = "bot"
  1613. CLIENT_VERSION = str((2 << 16) | (2 << 8) | 0)
  1614. STATE_PATH = os.path.join(HOME, "workspace", "setup", "weixin-qr-state.json")
  1615. PNG_PATH = os.path.join(HOME, "workspace", "your_files", "weixin-login-qr.png")
  1616. def api_get(endpoint: str) -> dict:
  1617. out = subprocess.run(
  1618. [
  1619. "curl", "-s", "-m", "30",
  1620. "-H", f"iLink-App-Id: {APP_ID}",
  1621. "-H", f"iLink-App-ClientVersion: {CLIENT_VERSION}",
  1622. f"{BASE_URL}/{endpoint}",
  1623. ],
  1624. capture_output=True, text=True, check=True,
  1625. )
  1626. return json.loads(out.stdout)
  1627. def main() -> int:
  1628. data = api_get("ilink/bot/get_bot_qrcode?bot_type=3")
  1629. qrcode_value = str(data.get("qrcode") or "")
  1630. qrcode_url = str(data.get("qrcode_img_content") or "")
  1631. if not qrcode_value:
  1632. print(f"QR response missing qrcode: {data}", file=sys.stderr)
  1633. return 1
  1634. scan_target = qrcode_url or qrcode_value
  1635. os.makedirs(os.path.dirname(PNG_PATH), exist_ok=True)
  1636. os.makedirs(os.path.dirname(STATE_PATH), exist_ok=True)
  1637. qr = qrcode.QRCode(box_size=10, border=4)
  1638. qr.add_data(scan_target)
  1639. qr.make(fit=True)
  1640. qr.make_image(fill_color="black", back_color="white").save(PNG_PATH)
  1641. with open(STATE_PATH, "w") as f:
  1642. json.dump({"qrcode": qrcode_value, "qrcode_url": qrcode_url}, f)
  1643. os.chmod(STATE_PATH, 0o600)
  1644. print(f"QR saved: {PNG_PATH}")
  1645. print("下一步:把这个 PNG 发给用户扫,然后跑 weixin-qr-confirm.py 等确认(180 秒内)")
  1646. return 0
  1647. if __name__ == "__main__":

Lines 2,001–3,110 are not shown. The link to the file on GitHub has every line.

README.md · README · 32 lines
  1. # muse-guardian
  2. 给 Muse.ai 沙盒装上探针、Hermes、保活和重建脚本,以及 **MuseAutoApprove**(自动允许审批)的 SKILL。
  3. ## 使用
  4. ```
  5. 帮我安装 `https://raw.githubusercontent.com/bytehola/muse-guardian/refs/heads/main/SKILL.md`并开始执行。
  6. ```
  7. 如遇拦截,打开侧边栏点击新旁路会话发送。
  8. ---
  9. 安装后 Agent 会按手册步骤部署以下组件:
  10. | 组件 | 作用 |
  11. |---|---|
  12. | cf-probe 探针 | 向 CF 后台上报沙盒状态 |
  13. | Hermes | 操控沙盒里的 AI Agent |
  14. | 三层保活 | 看门狗 + 平台 hook 探针 + 开机钩子,重建后自动恢复 |
  15. | **MuseAutoApprove** | 自动允许批准沙盒的外联审批卡片,访问新域名不再等人点"允许" |
  16. ## 效果
  17. <img width="843" height="636" alt="66695ffdbcaa3b97b3f7138644d2aead" src="https://github.com/user-attachments/assets/193a0521-b6d7-47b3-8ee3-2715f337dd60" />
  18. # 友好社区
  19. [LinuxDo](https://linux.do/)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.