wechat-selkies/AGENTS.md

PROJECT KNOWLEDGE BASE

Generated: 2026-03-23 Commit: e18821f Branch: master

OVERVIEW

Docker 容器化微信/QQ Linux 客户端，基于 LinuxServer Selkies WebRTC 基础镜像，通过浏览器远程访问桌面应用。支持 AMD64/ARM64 双架构。

STRUCTURE

wechat-selkies/
├── Dockerfile              # 单阶段构建，基于 selkies:ubuntunoble
├── docker-compose.yml      # 单服务编排
├── root/                   # COPY /root / → 容器内脚本和配置
│   ├── defaults/
│   │   ├── autostart           # 容器启动入口，仅一行: /scripts/start.sh
│   │   └── menu.xml            # Openbox 右键菜单模板（静态基础项）
│   └── scripts/
│       ├── start.sh            # 主启动脚本：openbox配置 → 菜单刷新 → 监听桌面 → 启动应用
│       ├── refresh-menu.sh     # 合并 menu.xml + ~/Desktop/*.desktop → 生成最终菜单
│       ├── window_switcher.py  # ⚠️ 已废弃，仅保留
│       ├── wechat/             # wechat-start.sh / wechat-restart.sh / wechat-unminimize.sh
│       └── qq/                 # qq-restart.sh
├── .github/workflows/      # CI: 多架构构建 + Issue 自动化
├── docs/images/            # README 截图
└── config/                 # ⚠️ gitignored 运行时数据挂载点

WHERE TO LOOK

任务	位置	备注
添加新应用	Dockerfile (安装) + root/defaults/menu.xml (菜单)	参考 QQ 安装段落的 case 模式
修改启动行为	root/scripts/start.sh	入口脚本，由 root/defaults/autostart 触发
修改右键菜单	root/defaults/menu.xml + root/scripts/refresh-menu.sh	menu.xml 是模板，refresh-menu.sh 动态合并 ~/Desktop/*.desktop
修改菜单动态生成逻辑	root/scripts/refresh-menu.sh	解析 .desktop 文件的 Name/Exec/Icon 字段，处理图标搜索
添加新应用启动/重启脚本	root/scripts/<app>/	遵循 wechat/ 目录模式: start.sh + restart.sh
修改环境变量	Dockerfile (ENV) + docker-compose.yml (environment)	两处需同步
CI/CD	.github/workflows/docker.yml	tag v* 触发，多架构 buildx，可选推送 Docker Hub
Issue 自动化	.github/workflows/issue-validation.yml + cleanup-issues.yml	标题/描述校验 + 7天自动关闭

CONVENTIONS

• 语言: 脚本用 Bash (#!/bin/bash)，窗口切换器用 Python3 + Xlib + tkinter
• 容器路径约定: COPY /root / 将 root/ 目录内容映射到容器根 /，因此 root/scripts/start.sh → 容器内 /scripts/start.sh
• 自启动机制: Selkies 基础镜像读取 /defaults/autostart 文件执行启动脚本
• 菜单刷新: inotifywait 监听 ~/Desktop/ 变更自动刷新 Openbox 菜单
• 进程管理: 应用通过 nohup ... & 后台启动，restart 脚本先 pkill -9 再启动
• restart 脚本模式: pkill -9 -f /usr/bin/<app> → nohup /usr/bin/<app> >/dev/null 2>&1 &（QQ 需额外 --no-sandbox）
• 菜单模板 vs 运行时: root/defaults/menu.xml 是源码模板，/config/.config/openbox/menu.xml 是运行时生成的，不要混淆
• refresh-menu.sh: 仅在内容变更时才写入 + reconfigure，避免无意义刷新
• 图标搜索优先级: proot-apps icons (256→512→128→64→48→scalable) → system icons → fallback xterm icon
• 多架构: Dockerfile 使用 $TARGETPLATFORM 条件分支安装不同架构 deb 包

ANTI-PATTERNS (THIS PROJECT)

• 不要直接修改 config/ 目录下的文件 — 这是运行时挂载数据，gitignored
• 不要修改 config/.config/openbox/ 下文件作为"源码" — 这些由 root/defaults/ 模板生成
• 不要在 root/ 下放非容器必需文件 — COPY /root / 会将所有内容复制到容器根目录
• 不要在 menu.xml 中添加 .desktop 动态条目 — 由 refresh-menu.sh 自动处理
• 不要在 start.sh 中用 exec 替代 nohup ... & — 需要多进程并行运行
• 升级后功能缺失 → 清空 ./config/.config/openbox/ 目录（已知 gotcha，见 README）
• window_switcher.py 已废弃 — start.sh 中已注释掉，但文件保留，不要删除

COMMANDS

# 本地构建并启动
docker-compose up -d --build

# 仅启动（使用已有镜像）
docker-compose up -d

# 查看日志
docker-compose logs -f wechat-selkies

# 进入容器调试
docker exec -it wechat-selkies bash

# 清理升级问题
rm -rf ./config/.config/openbox

NOTES

• 端口 3000=HTTP, 3001=HTTPS（推荐 HTTPS）
• shm_size: "1gb" 影响 WebRTC 性能，建议保留
• /dev/dri 映射为可选 GPU 加速
• AUTO_START_WECHAT / AUTO_START_QQ 控制容器启动时是否自动拉起应用
• 第三方应用通过 proot-apps 安装，快捷方式自动出现在右键菜单
• Docker Hub 推送需在 GitHub 仓库 Environment 中配置 ENABLE_DOCKERHUB=true