看板阻塞恢复守护 andrepontesmelo/hkrc

Hermes 看板恢复控制器（HKRC）

CI
Version
local gate

HKRC banner

一个 sidecar 守护进程，用于补充 Hermes 看板工作流：它观察任务执行，保持实例健康，并每天反思编排层本身如何改进。

它为什么存在

Hermes 看板非常适合任务分解和编排——但并非完美。
存在一些边界情况，任务会卡住，或者编排工作流本身需要改进。HKRC 的存在是为了让看板上观察到的问题和低效之处被编目并永不重复，而不是靠人工重新发现。

最终目标是明确的：理想情况下，Hermes 看板根本不需要 sidecar。修复和改进应该进入 Hermes 源码，使 sidecar 变得不再必要——但即便如此，回顾和反思始终能带来价值。哪个已编目的边界情况对应哪个上游 Hermes 修复，以及每个看门狗退役前必须满足什么条件，都记录在 docs/upstream-mapping.md 中。

它做什么

HKRC 是一个确定性的状态机——绝不是自主的 LLM 代理。它有两部分：

日常运行——确定性看门狗。 一个守护进程加上由 cron 驱动的看门狗观察看板执行，并自动处理已编目的边界情况，目前包括：

- 带有缺陷载荷的评审阻塞 → 自动创建修复卡片（每次评审、每个阻塞事件一张；已去重）。
- 修复已验证合并 → 取代循环关闭：被缺陷阻塞的评审以已验证证据完成（git merge-base --is-ancestor——版本声明会说谎，合并状态不会），并且受门控的子任务被提升。
- 选取门控自动推进：任务完成后，优先级最高的已停放 needs_input 卡片被解除阻塞——但当存在任何能力阻塞的卡片、该卡片或其父任务处于暂停状态，或最近的评论说 hold 时，绝不推进。
- 可提升阻塞防护：一个以 blocked 创建但没有阻塞事件的任务会被调度器静默自动提升；监视器会写入缺失的事件。
- 需要评审的死锁归档：一个被阻塞的父任务，其原因已经带有完成证据，会永远搁置其评审子任务；监视器会归档该父任务——仅在具备证据、仅在有评审子任务时，绝不其他情况（故障关闭）。

除了监视器之外，确定性看门狗会在任务等待你的输入时（needs-input-watcher）、当调度器死亡留下静默阻塞时（stale-block-watch）、当已完成卡片缺少其评审配对时（review-gap），以及当决策停滞时（watcher）。受保护引用的 Git 准入强制执行以 Outcome Guard 形式交付——由操作员注册的契约加上一个 Git 钩子，拒绝未受保护的规范引用更新。

每日反思——一次 LLM 调用。 每天（时间由你选择），HKRC 确定性地收集前一日执行的指标，并发出单次 LLM 请求，提出对编排工作流的改进建议。目标不是直接修复任务——而是扩展已编目的边界情况层，使已发生的错误不再重演。

一张图涵盖两半部分：日常 watcher 滴答（观察 → 决策 → 行动），以及生成每日反思报告的夜间 harness 循环：

Watcher 滴答（观察、决策、行动）与每日反思报告

配置只有两行：用于 LLM 反思的模型，以及它运行的时间。仅此而已。

何时使用它

- 你运行 Hermes 并配有 Kanban 看板，而卡住的任务积累速度超过你手动解除阻塞的速度。
- 你希望编排层中观察到的失败和低效被编目并预防，而不是被重新发现。
- 你希望有一个每日自审循环，审计编排层并将已接受的发现路由到 HKRC 看板。
- 你希望对受保护引用实施 Git 准入强制执行。

不要用它来打开或编辑原生 Hermes 源代码、配置或任务数据库——该安全边界是绝对的。

安装

需要 Python 3.11+ 和 uv。零运行时第三方依赖。

git clone https://github.com/andrepontesmelo/hkrc
cd hkrc
uv sync --dev
uv run pytest # full suite green

在使用该检出之前，验证门禁为绿色。github: 安装会在安装时解析默认分支——为可复现性固定一个标签。

[!WARNING]
守护进程会观察 Kanban 看板，并对已编目的边界情况采取自动恢复操作：创建修复卡、在验证合并后完成评审、推进选取门禁、缺失事件防护、有证据支撑的死锁归档。在部署不是你编写的配置之前，请审计控制器配置。配置面是用于每日 LLM 反思的模型加上每日反思时间——精确限定该范围，并且每个 watchdog 都以 --dry-run 启动。

安装后可用的命令：

uv run pytest # full suite
hkrc --help # every command (init/status/discover/run/daemon/…/flag)

python3 scripts/hkrc_release.py install --instance-root
hkrc init # writes controller config + state DB

发布过程从不安装、启用或启动服务——那始终是操作员的动作。完整的新机器演练（systemd 选择加入、cron 协调、升级/回滚）见 README 的 Install on a fresh machine 部分。

要求
- Python 3.11+、uv；一个正在运行的 Hermes 实例，带有 Kanban 看板。
- 用于看门狗节奏的 Cron；systemd 可选，始终需显式启用。

决策延迟监视器（watcher）

watcher 命令消除了日常运营中测量到的四种决策延迟停滞：等待修复卡片的缺陷阻塞评审、取代记账、一次一个的挑选门控，以及创建时即被阻塞的任务。它根据评审者的缺陷阻塞自动创建修复卡片（按评审 + 阻塞事件幂等），并且当修复被验证已合并到规范分支时（git merge-base --is-ancestor，绝不使用声称的 SHA），完成原始评审并提升任何被门控的子项。

该 tick 本身是 What it does 下图中上层通道的一趟流程：观察每个看板的事件积压和当前状态，根据已编目的边界情况做出决策，然后行动——或者跳过，故障关闭。

会话摩擦标记（friction-flag 技能）

当会话遇到摩擦时——同一件事被阻塞两次、重复追问、错过的技能触发、静默失败、ADHD 契约未命中——智能体自行追加一个标记，使用故障关闭的单行命令（如果 hkrc 二进制文件不存在则无操作）：

HKRC="$HOME/.hermes/hkrc/bin/hkrc"; [ -x "$HKRC" ] && "$HKRC" flag --severity --kind --note "" || true

没有检测机制：由智能体添加标记；没有任何东西扫描会话或提出发现。每日 harness 学习循环将新标记作为报告行和仅统计数据重新审视——完全相同的重复项折叠为 xN。该技能随每个版本发布到 /skills/friction-flag/。

Harness 学习循环（harness-loop）

对实例自身会话进行的每夜 7 天自我审查，提炼为分类缺陷和分级改进摘要。hkrc harness-loop run --config （移植了旧版 f69651252ba1 cron 作业）。从 --dry-run 开始：该循环会写入其计划和升级，直到你开启它才会派发。逐字提示词位于 references/harness-loop-prompt.md。该趟流程是同一图表的下层通道——它渲染的报告就是每日反思，通过 cron（Telegram）投递，没有新内容时保持静默。

深入阅读

- 文档索引 — 从这里开始：架构、开发、结果守卫、角色矩阵运行手册。

- 决策延迟监视器（watcher） — 为什么停滞的决策会被升级，以及看门狗节奏是如何计算的。
- Harness 学习循环（harness-loop） — 每夜自我审查循环提示词和升级规则。
- 角色矩阵（persona_matrix） 及其操作 运行手册 — 角色/人格漂移检测和证据。

贡献欢迎提交 PR——工作流程和本地门禁请参见 CONTRIBUTING.md。
安全问题：SECURITY.md（请勿公开提交 issue）。

测试

uv run pytest # 完整测试套件

许可证

MIT——请参见 LICENSE。