{"id":50925510,"url":"https://github.com/zhao5271/agent-watchdog","last_synced_at":"2026-06-16T22:31:05.900Z","repository":{"id":350200957,"uuid":"1205573469","full_name":"zhao5271/agent-watchdog","owner":"zhao5271","description":"配合 tmux 监听 agent 执行任务的状态","archived":false,"fork":false,"pushed_at":"2026-04-09T09:06:34.000Z","size":125,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-09T11:11:25.151Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zhao5271.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-09T04:51:47.000Z","updated_at":"2026-04-09T09:06:45.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/zhao5271/agent-watchdog","commit_stats":null,"previous_names":["zhao5271/agent-watchdog"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/zhao5271/agent-watchdog","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zhao5271%2Fagent-watchdog","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zhao5271%2Fagent-watchdog/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zhao5271%2Fagent-watchdog/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zhao5271%2Fagent-watchdog/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zhao5271","download_url":"https://codeload.github.com/zhao5271/agent-watchdog/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zhao5271%2Fagent-watchdog/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34426738,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-16T02:00:06.860Z","response_time":126,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-16T22:31:01.043Z","updated_at":"2026-06-16T22:31:05.896Z","avatar_url":"https://github.com/zhao5271.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Agent Watchdog\n\n一个放在本地后台运行的任务监听器，用于：\n\n- 监听单个任务是否仍在运行\n- 通过日志推断任务阶段\n- 识别任务是否变慢、疑似卡住、意外停止\n- 在终端中以 HUD 风格展示状态\n- 提示你是否需要手动重启任务\n\n## 当前能力\n\n- 单任务监听\n- `tmux` 托管任务\n- 保留失败现场后自动拉起 replacement session\n- 状态文件 `runtime/status.json`\n- 启动元数据 `runtime/launch.json`\n- 事件日志 `runtime/events.log`\n- 终端 HUD 展示\n- 手动重启命令\n\n## 目录\n\n```text\nagent-watchdog/\n├── README.md\n├── config/\n│   ├── stage-rules.json\n│   └── tasks.example.json\n├── docs/\n│   └── 状态字段说明.md\n├── runtime/\n│   ├── events.log\n│   ├── status.json\n│   └── watchdog.pid\n└── scripts/\n    ├── restart.sh\n    ├── status.py\n    └── watchdog.py\n```\n\n## 快速开始\n\n### 1. 最简启动\n\n```bash\naww \"python3 /path/to/task.py\"\n```\n\n如果你希望启动后立刻进入交互 session，用：\n\n```bash\nawx\n```\n\n说明：\n\n- 启动前会先停掉这个仓库里的旧 watchdog，避免多个进程同时覆盖状态文件\n- 任务会进入新的 `tmux session`\n- 输出会写入新的运行日志文件\n- `watchdog` 会读取 `runtime/launch.json`，跟踪当前活跃 session/pane\n- 如果任务 `failed / stopped / stalled`，会先把旧 session 重命名成 `*-failed-时间戳`，再拉起新的 replacement session\n- 默认参数：\n  - `soft_timeout=300`\n  - `hard_timeout=900`\n  - `poll_interval=1`\n  - `max_restarts=3`\n\n### 2. 可选环境变量\n\n```bash\nAWW_TASK_NAME=\"首页重构\" AWW_MAX_RESTARTS=5 aww \"python3 /path/to/task.py\"\n```\n\n支持：\n\n- `AWW_TASK_NAME`\n- `AWW_SOFT_TIMEOUT`\n- `AWW_HARD_TIMEOUT`\n- `AWW_POLL_INTERVAL`\n- `AWW_MAX_RESTARTS`\n\n### 3. 三个入口的区别\n\n- `aww \"命令\"`\n  启动托管任务，但不自动进入 session\n- `awx [命令]`\n  启动托管任务后，立刻 `tmux attach`，并把 HUD 放进 `tmux status-right`\n\n当前推荐：\n\n- `aww` 适合只启动，不立刻 attach\n- `awx` 适合 attach 后用 `tmux status-right` 看状态；不传命令时默认执行 `codex`\n- `awx` 绑定当前终端生命周期：直接关闭终端或 Warp 标签页后，tmux session 和任务会一起结束，不会继续在后台挂着\n- `awxbar` 仅保留为兼容别名，后续不再继续维护\n\n`awx` 的状态栏默认展示：\n\n- 命令摘要\n- 当前状态\n- 当前阶段\n- 运行时长与未响应时长\n- 重启次数\n- 不展示通用任务名，例如 `Agent 任务`\n- 不展示“当前任务细节”多行区块\n- `awxbar \"codex\"` 等价于 `awx \"codex\"`，但会提示已废弃\n\n### 4. 高级用法\n\n如果你要手动指定 `task-id`、`session-prefix` 或更底层参数，再直接调用：\n\n```bash\nbash /Users/zhang/Desktop/agent-watchdog/scripts/tmux_launch.sh \\\n  --task-id home-redesign \\\n  --task-name \"首页结果工作台重构\" \\\n  --command \"python3 /path/to/task.py\"\n```\n\n### 5. 查看状态\n\n```bash\npython3 /Users/zhang/Desktop/agent-watchdog/scripts/status.py\n```\n\n持续刷新：\n\n```bash\npython3 /Users/zhang/Desktop/agent-watchdog/scripts/status.py --watch\n```\n\n### 6. 停止监听\n\n```bash\nbash /Users/zhang/Desktop/agent-watchdog/scripts/stop_watchdog.sh\n```\n\n### 7. 手动执行重启\n\n```bash\nbash /Users/zhang/Desktop/agent-watchdog/scripts/restart.sh\n```\n\n它会读取 `runtime/launch.json`，保留当前失败现场后再新建一个 session。\n\n说明：\n\n- 自动重启仍然由 `watchdog` 在 `failed / stopped / stalled` 等可恢复状态下触发\n- `restart.sh` 只是给你手动触发同一条重启链路\n\n## 关键运行文件\n\n- `runtime/status.json`\n  HUD 和其他脚本读取的主状态\n- `runtime/launch.json`\n  当前被托管的 `tmux session / pane / command / log_path`\n- `runtime/events.log`\n  `watchdog_started / stage_changed / task_restarted / restart_failed`\n\n## 设计原则\n\n### 对 `tmux` 现场友好\n\n自动恢复时会：\n\n- 保留旧 session\n- 把旧 session 重命名成 `*-failed-时间戳`\n- 让你可以随时 `tmux attach -t \u003c旧session\u003e` 回看现场\n\n### 自动重启有上限\n\n默认最多自动恢复 3 次，避免错误配置导致无限重启。\n\n### `graphModel` 一类数据无关\n\n这个工具不绑定某个具体项目的数据结构。\n它只关心：\n\n- 进程\n- `tmux session / pane`\n- 日志\n- 阶段\n- 超时\n\n## 下一步可以扩展的能力\n\n- 多任务面板\n- HTML 状态页\n- 系统服务化运行\n- 通知渠道（Telegram / 飞书 / 邮件）\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzhao5271%2Fagent-watchdog","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzhao5271%2Fagent-watchdog","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzhao5271%2Fagent-watchdog/lists"}