macOS 适合验证流程，不作为首选生产环境
项目脚本以 Linux 为标准，macOS 需要通过 Docker Desktop 的 Linux VM 运行，并确认共享目录和容器内 UID/GID 行为。
它解决的不是聊天，而是运维入口碎片化
不用每天 SSH 进服务器
常见状态、用户创建、二维码绑定、模型查看、文件管理，都通过母体走受控命令完成。
多人使用不互相污染
子实例只能看到自己的工作区和文件区，不管理宿主机、母体、Docker 或其他用户。
模型和媒体能力分开
聊天、图片、视频模型独立配置，避免一次切换把媒体能力覆盖。
成品文件直接送达微信
Word、Excel、PPT、PDF、图片、视频通过 MEDIA 路径回传给对应用户。
系统分层像一条清晰的控制轨道
微信负责入口，母体负责控制，Docker 负责隔离，子实例负责用户任务，Skill 和文件区负责交付。
微信网关
管理员和普通用户都从微信进入；网关只负责收发消息和二维码绑定。
母体 manager
拥有高权限，但通过 policy 和 chatopsctl 把自然语言落到可审计命令。
Docker Compose
统一管理 hermes_manager 和 bot_<user_id> 子实例，日志和健康状态可查。
子实例
每个用户独立 workspace、files、memory，只能操作自己的目录。
Skill / Files
公共 Skill、私有 Skill、MEDIA 文件和生成结果按作用域交付。
运行边界与接入保障
二维码交付
母体绑定管理员和接入子实例时必须拿到二维码链接，保存图片，并通过 MEDIA 路径直接推送给微信管理员。
DM open
普通用户扫码接入默认选择 Allow all direct messages；只有实际出现 pending pairing 时才走审批兜底。
Office 成品
Word、Excel、PPT、PDF 等任务必须产出真实文件，写入子实例 files 目录，再由网关上传给用户。
运行保障不靠口头承诺：二维码、容器状态、DM open、文件成品和权限边界都要能被脚本验证。
macOS Docker Desktop 路径
解包后将部署目录放到 Docker Desktop 可共享路径，再按脚本准备 .env、权限、模型和微信绑定。
解压并校验发布包
先解 zip，再解 hermes-deployment.tar，校验必要部署文件的 sha256。
unzip hermes-chatops-release.zip
tar -xf hermes-deployment.tar
cd hermes-deployment
sha256sum -c ../DEPLOYMENT_CHECKSUMS.sha256把母体、子实例、Skill 和密钥页拆成四个清楚入口
母体不要东找西找。自然语言先映射到固定入口，入口解决不了再请求管理员确认宿主机操作。
母体先找规范入口，不先乱试命令
母体提示词和 policy 要把自然语言映射到 chatopsctl、scripts、validate.sh 这些明确入口。
- 状态、用户、模型、密钥、Skill、文件都要有固定命令路径。
- 入口无法覆盖时，母体应说明原因并请求管理员确认宿主机命令。
- 返回结果必须包含影响范围、是否成功和下一步验证。
/opt/hermes-deployment/toolmanager/bin/chatopsctl用户扫码后直接进入子实例对话
子实例绑定微信时应选择 Allow all direct messages；如果配置成 Use DM pairing approval，就一定会弹 pairing code。
- 扫码后容器保持运行，不能因为绑定进程退出导致主服务退出。
- bind_driver.py 要能拿到二维码 URL 并保存图片。
- 未开启 DM open 时才走 pending pairing 审批。
global_tools/bind_driver.pymodeAllow all direct messagesSkill 按公共和私有边界拆开
公共技能面向子实例同步，母体高权限能力只留在 manager，减少用户越界操作。
- 公共 Skill 改完后同步并重启需要加载的实例。
- 子实例不得拥有 Docker、宿主机和其他用户目录管理能力。
- 英文系统提示可以中文解释，但命令和文件名不翻译。
global_skills/managerglobal_plugins/chatops-policyAgnes 模型和 key 单独管理
文本、图像、视频都走 Agnes 免费模型，key 通过脚本或密钥页录入，部署包只保留模板。
- 不要把 key 写入 README、网页、聊天记录或发布包。
- SECRET_PORTAL_PUBLIC_URL 可使用 auto。
- 初始化后用 show-model 和最小调用验证。
agnes-2.0-flashportalone-time secret page母体执行运维时先走 chatopsctl 和 scripts 里的规范入口，入口无法覆盖时再请求管理员确认宿主机命令。
- 日常入口是
chatopsctl status、doctor --strict、user list、manager show-model。 - 删除、覆盖、重启、改权限和清理文件都要说明影响范围，并使用带确认参数的入口。
- 策略拦截器不应只说“无法执行”，要提示正确入口或需要管理员授权的宿主机命令。
cd /opt/hermes-deployment
sudo docker exec -u hermes hermes_manager chatopsctl status
sudo docker exec -u hermes hermes_manager chatopsctl doctor --strict
sudo docker exec -u hermes hermes_manager chatopsctl user list
sudo docker exec -u hermes hermes_manager chatopsctl manager show-model日常运维像看仪表盘一样清楚
- 管理员说“接入新用户”时，母体应调用
chatopsctl user create和user bind，生成二维码并提醒选择 Allow all direct messages。 - 管理员说“用户已扫码”时，母体先查容器和 pairing 状态；DM open 已生效时直接验证对话，不再要求 pairing approve。
- 用户生成文件时，子实例把成品放进自己的 files 目录，并用 MEDIA 路径推回微信。
- 遇到英文网关提示时，实例用中文解释错误含义，命令、文件名、错误码保留英文原文。
macOS 验证重点是二维码、MEDIA 文件保存和容器生命周期；生产问题仍应回到 Ubuntu 复验。
Agnes API 是文本、图像、视频能力入口
项目默认按 Agnes 免费模型准备，复现文档会说明 key 获取、模型填写、最小调用和排障。
获取 key
- 访问 Agnes 官方控制台，注册或登录账号。
- 进入 API Key / Token 管理页，创建新的 key。
- 只在初始化脚本或密钥页录入 key，不要发到微信群或普通聊天窗口。
模型填写
- 文本、图片、视频模型分开填写。
- 文档中默认示例使用免费 Agnes 模型，占位值可替换。
- 部署包不内置真实 key，打包发布前必须保持空模板。
验证方式
- 先用
chatopsctl manager show-model看配置。 - 再用文本、图片、视频各跑一次最小调用。
- 失败时保留英文错误码，同时用中文解释给用户。
每次发布都要能被重新校验
- 校验部署文件完整性：
DEPLOYMENT_CHECKSUMS.sha256 - 校验脚本语法和执行位：
bash -n scripts/*.sh - 校验 Docker 配置：
docker compose --env-file .env config --quiet - 校验母体入口：
chatopsctl doctor --strict - 校验微信链路：管理员二维码、普通用户二维码、扫码后容器状态。
校验文件
校验文件只覆盖必要部署文件，不包含 README、documents、page 和 release 产物。
sha256sum -c DEPLOYMENT_CHECKSUMS.sha256扫码后 exit、二维码缺失和 pairing code 的判断顺序
- 管理员绑定无二维码且报
invalid choice: hermes，优先检查scripts/bind-manager-weixin.sh中docker compose run参数顺序。 - 普通用户扫码后子实例 exit，先看
docker logs bot_<user_id>，再查 entrypoint、绑定命令是否覆盖主进程。 - 弹出
Hi~ I do not recognize you yet和 pairing code，说明直聊授权不是 Allow all direct messages 或配置没有生效。 - bind_driver.py 拿不到二维码时，检查网关输出格式、二维码 URL 抓取逻辑、MEDIA 保存目录权限。