宜博 / lemongraph

SKILL.md 6.82 KB

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 官方单次入口：

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 的可执行方案。