---
name: unattended-agent-operations
description: 配置、审计和验证无人值守 Agent 的身份文件、工作区规则、技能绑定、Cron、Gateway 与操作系统调度器。适用于多 profile、定时任务注册但不执行、消息 Gateway 冲突、macOS LaunchAgent/systemd 部署及端到端运行证据核验。
version: 1.0.0
metadata:
  hermes:
    tags: [agent-operations, cron, profiles, gateway, launchd, unattended, verification]
---

# 无人值守 Agent 运行保障

## 何时使用

当任务涉及以下任一情况时使用：

- 建立或审计专用 Agent profile；
- 检查 `SOUL.md`、`AGENTS.md`、技能和 Cron 是否形成闭环；
- 定时任务存在但没有自动执行；
- 多 profile Gateway、消息平台或 app_id 冲突；
- 使用 launchd、systemd 或其他外部调度器运行 Hermes Cron；
- 需要证明“实际自动运行”，而不仅是“配置看起来正确”。

Hermes CLI、配置键和当前特性以官方文档与受保护的 `hermes-agent` skill 为准；本技能负责运行架构、验证顺序和常见误判。

## 五层运行契约

无人值守 Agent 至少有五层，每层只承担一种责任：

1. **SOUL**：身份、使命、不可妥协原则和决策责任。
2. **Profile AGENTS**：事实源、状态机、工作区、工具身份、安全边界和停止条件。
3. **Class Skill**：跨项目可复用的方法、检查表、证据模板和故障处置。
4. **Project AGENTS**：目录关系、项目命令、环境和本地边界。
5. **Cron Prompt**：自足的单轮任务、优先级、唯一事实源、无工作行为和禁止事项。

不要把整套方法复制到每个 Cron prompt；prompt 应加载 class skill，只固定自动运行契约。层间冲突时先修正源文件，不能靠 prompt 重复堆叠掩盖。

## 配置审计

### 身份与工作区

- profile 有明确 `SOUL.md`；身份与项目目录规则一致；
- profile 与项目均有适用的 `AGENTS.md`，或明确为什么只需要一处；
- workdir 会加载正确角色规则，不会误载 Planning/Code 等其他身份；
- profile 的技能目录可见，Cron 显式绑定必要技能；
- 不把所有已安装技能都加载进 Cron，上下文只保留任务需要的最小集合。

### Cron

创建后重新读取并确认：

- Job ID、名称；
- schedule 的真实解析结果；
- `repeat=forever` 或预期次数；
- enabled/state；
- skills、model/provider、toolsets；
- workdir；
- delivery 目标；
- next/last run 与 last status。

周期表达式使用显式语义，例如 `every 10m`。不能假定 `10m` 一定表示循环；若返回 `once`，删除错误任务并重新创建，避免残留一次性 repeat。

## 调度器选择

优先使用 profile Gateway 内置调度器。但必须先检查：

- Gateway 是否实际运行，而不是只安装了服务定义；
- 最新启动日志是否成功；
- 消息平台是否允许同机多实例；
- 是否会影响正在服务的其他 profile。

若 profile 不需要接收消息，且第二个 Gateway 会与现有消息客户端冲突，可使用 Hermes 官方单次入口：

```bash
hermes -p <profile> cron tick
```

由 launchd/systemd 周期调用。tick 每次检查后退出属于预期行为；此模式的健康指标是调度次数增长、最新退出码为 0、Cron run history 正常，而不是常驻 PID。

## 日志优先排障

出现“安装成功但未运行”时：

1. 查看 service status、PID、LastExitStatus；
2. 读取本次启动对应的最新日志段，不先猜配置；
3. 区分历史噪音与当前启动错误；
4. 找到根因后选择不影响其他 profile 的最小修复；
5. 清理旧日志或建立时间边界，再次触发获得干净证据。

不要因为 service 文件存在、`enabled=true` 或 next_run 有值就宣布自动化已生效。

## 外部调度器验证

无论是 launchd 还是 systemd，至少验证：

1. 配置语法有效；
2. 服务已加载；
3. 手动 kick/start 后退出码正确；
4. stdout/stderr 没有当前错误；
5. 调度计数随时间增长；
6. Hermes Cron history 出现一次完成记录；
7. 读取持久化输出，确认 Agent 真的执行了任务逻辑；
8. 等待一次自然周期，确认不是只支持手动触发；
9. 在出现真实工作对象时验证完整业务链路。

手动运行返回 `success=true` 仍不足；必须读取输出或 run history。空队列的 `[SILENT]` 只能证明调度、技能加载和空路径，不能证明业务代码访问、真实测试和写回链路。

## macOS 注意事项

- LaunchAgent 对 `Documents`、Desktop 等受 TCC 保护目录的访问可能不同于交互式终端；具体排障步骤见 `references/macos-profile-cron-runner.md` 中「macOS TCC Documents 目录后台访问」。
- 当 GUI 授权不可行时，最可靠的工程方案是把项目整体移出 Documents，并在原地保留符号链接；完整操作见 `references/macos-documents-tcc-project-move-recipe.md`。
- 迁移后不能只做 `mv`：必须同步更新 cron `workdir`、prompt 中的旧路径、checkpoint 中缓存的 `workdir`，以及 profile / 项目 `AGENTS.md` 中的共享入口。
- 调度器自身的 WorkingDirectory 优先放在 profile 目录；任务再按需访问项目路径。
- 若后台 Agent 无法访问业务目录，不得用交互式成功替代后台证据，应报告未完成链路并处理权限或调整部署。
- 一次性 tick 显示 `state = not running` 可以是正常的；同时核对 `runs` 和 `last exit code`。
- 路径变更或异常运行后，cron job 可能被系统自动置为 `paused`；验证前先检查 `enabled` 与 `state`，必要时 `cron resume`。

## 安全边界

- 不为启动新 profile 而停止未知用途的现有 Gateway；先查清 PID、profile 和平台占用。
- 不复制、输出或硬编码凭证；不同 profile 应有明确凭证与平台隔离策略。
- 无人值守 prompt 不得递归创建 Cron。
- Cron 的 toolsets、网络、文件和写权限按最小权限配置。
- 自动任务的副作用必须受单任务认领、幂等或锁保护。

## 完成门

只有以下均满足才能报告“无人值守 Agent 已可用”：

- 身份、规则、技能和 prompt 无冲突；
- 周期与 repeat 配置正确；
- 调度器真实运行；
- 至少一次 Cron 执行完成并有持久化证据；
- 空队列路径正确且无副作用；
- 有真实对象时，完整业务路径已验证；若尚无对象，必须明确此项仍未覆盖；
- 不影响其他 profile 或正在运行的消息 Gateway。

## 参考

- `references/macos-profile-cron-runner.md`：macOS、多 profile Feishu 冲突与独立 `cron tick` LaunchAgent 的实战配置及验证要点。
- `references/macos-documents-tcc-project-move-recipe.md`：当 GUI 无法授权 Full Disk Access 时，把项目移出 Documents 并同步更新 cron、prompt 与 checkpoint 的可执行方案。