Atlas-X-AI/hermes-kanban-watch

Hermes Kanban 监控

在 Claude Code 中展示 Hermes 工人而不占用它们的卡片。正在运行的卡片获得实时行，排队的卡片共享等待行，停止的卡片获得“需要你”的行。被监控卡片的已归档新子卡片将自动加入，除非设置 follow_new: false。

安装与检查

使用 claude --plugin-dir /path/to/hermes-kanban-watch/plugin 启动 Claude Code。调用者解析此技能的插件根目录；使用同级目录下的 scripts/doctor.py。 首先运行 python3 <plugin-root>/scripts/doctor.py --board default。它是只读的。 --fix 会创建一个缺失的默认看板（使用 hermes kanban --board default init）或一个缺失的命名看板（使用 hermes kanban boards create <slug>），还会创建用户路由和一个 hermes-kanban-live 垫片（shim），而不覆盖现有文件。将 ~/.local/bin 添加到 PATH 并重新运行 doctor。 Doctor 要求 hermes-kanban-live --version 精确打印 hermes-kanban-watch 0.3.0。外部的/过时的命令将被标记为 FAIL 并显示其解析路径；在重新运行 --fix 之前移动它或更正 PATH（--fix 永远不会覆盖它）。 --probe 使用 PONG 显式测试每个路由模型，并可能消耗容量。

要求：Python 3.11+、PATH 上的 Hermes、支持工作流的 Claude Code 以及现有的 Hermes 配置文件。模型和密钥属于每个 Hermes 配置文件：API 密钥、订阅登录或本地模型，通过 Hermes 配置，而非此插件。 插件不提供账户或复制凭据。Claude 观察者模型的用量与 Hermes 工人的提供商用量分开。

正常提交卡片

首先使用 hermes kanban boards create demo 创建一个命名看板，然后使用 hermes kanban --board demo create "Build the feature" --assignee builder。 使用 hermes kanban swarm --help 选择上游 swarm 标志。提交不会启动调度器。通过 Hermes 分开启动/委任工人。 后 Bash 钩子在 create/swarm 后建议 /kanban-watch；它本身从不启动或调度任何内容。避免在同一个波次上重复监控。

提交一个路由的、固定的卡片

仅在明确的提交请求时：python3 <plugin-root>/scripts/file_card.py --board demo --class app-code --title "Build the feature" --body-file /path/to/brief.txt --routes /path/to/routes.yaml --worktree /absolute/path/to/worktree。 --routes 和 --worktree 是可选的。该命令通过 route.py 解析一个工人/不同家族的验证器，创建一个固定的工人，运行 set-model，验证 show --json，然后打印其 ID 和精确的 /kanban-watch 参数。它不创建验证器、调度器、工作流或工作树，也不打开任何配置文件或凭据。绝不要将此编写命令授予观察者。 --dry-run 验证文件/路由/看板并打印命令而不运行 Hermes；简报会被打印，所以请将机密信息排除在外。缺少看板/无效路由将被拒绝。部分失败后检查返回的 ID，切勿盲目重新提交。有关详细信息，请参见 完整提交细节；仅在请求时才启动监控。

在 PONG 检查后建议路由

仅当获得明确的容量批准时，运行 python3 <plugin-root>/scripts/doctor.py --board demo --routes /path/to/routes.yaml --probe --suggest-routes /path/to/routes-checked.yaml。它需要 --probe，拒绝已存在的目标（包括目录/符号链接），并且永远不会更改源路由或激活提案。在选择之前审查配置文件/提供商/成本更改。 两条通道必须通过本次运行的 PONG，并且具有不同的声明家族，而不仅仅是不同的主机。通过的工人/验证器被保留；替代品使用字典顺序的通道顺序。没有配对的类将被省略并附带诊断注释；没有配对意味着路由不可用。原始失败仍然退出 1。PONG 不是适用性或持久容量。请参见 选择和审计细节。

启动

将 $ARGUMENTS 视为一个 JSON 参数对象。解析已安装插件的 workflows/kanban-watch.js，然后调用 Workflow({scriptPath: "<plugin-root>/workflows/kanban-watch.js", args: <args>})。 如果 Workflow 不可用，报告该限制并直接运行 hermes-kanban-live 的只读命令，绝不要假装创建了实时工作流行。

参数示例：

• {"board":"default","tasks":["t_1234abcd"]}
• {"board":"demo","phases":[{"title":"Build","tasks":["t_1234abcd"]},{"title":"Verify","tasks":["t_11111111"]}]}
• {"board":"demo","follow_new":false,"stale_days":7,"max_hours":12}

裸看板监控包括排队的/正在运行的卡片，跳过空闲时间超过 stale_days（默认为 7）的排队卡片。stale_days: 0 禁用过滤；显式 ID 始终保留。使用 verbose: true 获取旧版工人文本和工具结果。 读取器是 PATH 上的 hermes-kanban-live；live_cmd 可以用一个安全命令覆盖它，例如 python3 ~/plugins/hermes-kanban-watch/plugin/scripts/kanban_live.py。仅接受字母、数字、空格、/、.、_、-、~。不允许使用 shell 运算符。 每一行默认使用插件的 hermes-kanban-watch:kanban-watcher 智能体；不需要私有用户智能体。agent_type 可以命名另一个可用的智能体，使用 ASCII 字母、数字、-、_ 以及一个可选的 : 分隔非空名称。

读取结果

DONE 是观察到的卡片结果，而不是集成或用户验收。检查实际模型、回退、警告、总结和可交付物。BLOCKED/REVIEW 获得“需要你”的行，并可能在恢复时重新激活。NOT_STARTING 表示已就绪但调度器未启动。UNKNOWN 表示读取失败，而不是卡片消失。超时仅重试退出 3；270 秒的唤醒使等待低于提示缓存 TTL。观察者从不操作工人的文本、更改卡片、修复任何内容或绕过权限。

当工人消息不可用时，每个运行/观察者跟随一次报告并使用卡片日志；心跳从不计数。 不断增长/更改的日志防止可能的卡住警告。只有两次连续相同的运行中调用且日志无变化才可能被标记；首次观察、运行更改和不可读信号不计算在内。有消息时，两次安静调用标记。

使用 python3 <plugin-root>/scripts/route.py --class app-code 检查可选的路由表。它返回工人和不同家族验证器的 JSON；它从不提交或调度卡片。编辑用户路由以命名您自己的配置文件和模型家族。

人间询问约定

对于 hermes-kanban-live needs，以 ASK OPERATOR: 开头一行注释，后跟问题。散文中提到的“尚无 ASK OPERATOR”不算询问。阻塞或依赖等待原因必须说 waiting on operator、waiting for operator 或 needs operator 才能匹配当前的人类等待。这些是显式文本约定，不是自然语言意图检测。“需要你”的工作流行分别标记阻塞/审核结果以及已就绪但未启动的卡片。

报告波次的实际运行和经过时间

运行 hermes-kanban-live report --board demo，可选重复 --task T 或添加 --since EPOCH。在没有任务 ID 的情况下，这包括所有状态，包括已完成/归档的。--since 选择卡片创建时间；它与任务选择相交，并且不剪切单个运行。JSON 在 cards 中每个卡片一个对象，外加 totals、read_status、now 和 missing。每个卡片包含 id/title/status、assignee、实际最后一次运行的 model_used、provider_used、fallback_from、runs、retried、duration_s 和最后一次运行的警告计数。未知的运行数据保持 null。

totals.by_status 统计卡片的数量；run_seconds 汇总所选卡片所有已知运行持续时间（正在运行的运行在 now 时测量）的总和；fell_back 统计在任何尝试中回退的卡片数量；retried 统计具有保守重试保护（多次运行或重试/阻塞历史事件）的卡片数量。这些是经过的秒数，不是计费的代币/货币成本。添加 --format text 以获取对齐的纯文本列和总计，不带 Markdown。退出 4 表示缺少显式 ID；退出 5 表示无法读取看板。仅因 --since 被排除的卡片不算缺失。

检查实际工人/验证器家族独立性

运行 hermes-kanban-live verify-pair --board demo --worker T --verifier V，可选 --families FILE。它使用每个卡片最新完成的运行（非 null 的 ended_at，最新的运行 ID），而不是模型固定或更新的未完成尝试。JSON 包括每个实际的 model_used、provider_used、run_id、映射的 family 和 different_families。运行的实际提供商通过路由文件中的 providers 映射到其模型家族。保持同家族的主机映射一致；多家族主机需要家族特定的标识符。这不从模型前缀推断家族，也不证明审查工作已发生。

查找顺序匹配 route.py：显式的 --families、KANBAN_WATCH_ROUTES、~/.config/hermes-kanban-watch/routes.yaml、附带模板。仅需要有效、非空的 providers 映射。退出 0 表示不同家族，1 表示同家族或无效/未知分类，3 表示任一 ID 没有完成的运行，5 表示无法读取看板。分类错误将 different_families 设置为 null 并包含 error；永远不要将 UNKNOWN 转换为成功的检查。 对于直接的 Claude Code 调用，仅请求 Bash(hermes-kanban-live report:*) 和 Bash(hermes-kanban-live verify-pair:*)，而不是不受限制的 Bash 权限。

在超时期间保持父问题监控有效

运行 hermes-kanban-live needs --board demo --loop --created-by PARENT --cursor-key WAVE 一次，而不是在每次退出 3 后重建命令。在循环模式下 --since 是可选的，在启动时捕获一次（如果不存在），并且永远不会在超时窗口期间前进。它的第一次轮询包括仍然有效的预先存在的等待，包括创建者的旧父问题。已回答/已恢复/已替代的旧等待保持排除，现有的看见游标去重仍然适用。

循环模式在 --interval 处休眠，并且仅重试正常超时，没有超时 JSON 混乱。它在第一次非空 items 结果时退出 0，或者在出错时失败而不重试。--max-seconds 限定每个窗口，而不是命令的生存期；取消调用者以停止静默监控。没有 --loop 时，必需的 --since、退出 3 超时和输出行为保持不变。这仍然是读取器，绝不允许回答、调度或突变卡片。

功能指南

• 波次时间和实际运行报告：实际运行、重试和经过的秒数，而不是计费成本。
• 验证实际运行的家族：已完成运行的家族证据，而非模型固定。
• 使用自身的超时循环一次性装备 needs：跨超时只读的父问题等待。
• 打印头部固定的 PR 合并收据：独立验证器、精确头部、CI 和合并状态检查；从不合并。
• 观察者代币成本：仅计数的 Claude 观察者用量，与工人时间分开。
• 存在于父卡片上的重复工人和问题：观察进程警告和父等待；从不修复它们。
• 提交修复并重新验证先前的判定：仅限显式编写；重用验证器固定、可选的父注释、不调度。
• 工作流拥有的等待轮次：一个截止日期下的健康只读等待。
• 建议常备答案而不发布：为授权审查打印提案，从不发布。