From 9c122a4a37166f0f4e3b334de1271ff9879c744d Mon Sep 17 00:00:00 2001 From: Your Name Date: Tue, 19 May 2026 23:16:45 +0800 Subject: [PATCH] docs(governance): record hermes km healthcheck rollout [skip ci] --- docs/LOGBOOK.md | 108 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 108 insertions(+) diff --git a/docs/LOGBOOK.md b/docs/LOGBOOK.md index 56b90f52a..e0d5cc1dd 100644 --- a/docs/LOGBOOK.md +++ b/docs/LOGBOOK.md @@ -1,3 +1,111 @@ +## 2026-05-19｜T90 Hermes KB healthcheck worker 與 owner review 閉環 + +**觸發**： + +- T88/T89 已把 `knowledge_degradation` 事件接到 `governance_remediation_dispatch`，並讓事件詳情 / 歷史可看到 dispatch ids。 +- 但 `hermes_kb_growth_healthcheck` 仍停在 pending；Operator 只能知道「已派工」，看不到 Hermes 是否真的建立 KM 草稿、是否已進 owner review、或是否需要人工介入。 + +**修正**： + +- 新增 `src.jobs.hermes_kb_growth_worker`： + - 消費 `executor_type=hermes_kb_growth_healthcheck` 的 pending dispatch。 + - 依狀態機推進 `pending → dispatched → executing → succeeded`。 + - 建立 `auto_runbook / review / ai_extracted` 的 KM 草稿，停在 owner review。 + - 寫回 `decision_context.worker_result`、`workflow.kb_draft_entry_id`、`workflow.current_stage=waiting_owner_review`。 + - 明確保留安全邊界：`writes_km_without_approval=false`，不自動批准、不自動發布正式 KM。 +- `main.py` 啟動 Hermes KB growth loop，每 5 分鐘消費 backlog。 +- `governance_remediation_dispatch_repo` 新增 `list_pending_by_executor()` 與 `update_decision_context()`，避免 job 直接散落 SQL。 +- production smoke 抓到 `knowledge_entries.tags` 實際是 JSON 欄位，不支援 `json @> text`；修正 `KnowledgeDBRepository.list_entries(tags=...)` 改用 JSON/JSONB 皆相容的 quoted tag filter。 +- production smoke 又抓到 `succeeded / waiting_owner_review` 後 dispatcher 仍會因事件 unresolved 重複 requeue；補上 `GovernanceDispatcher._has_kb_growth_review_draft()`，同一 event 已有 Hermes review draft 後不再補 pending。 +- worker 冪等 key 改以 `governance_event:{event_id}` 優先，避免一個 governance event 因 retry/requeue 產生多份 KM 草稿。 + +**Local verification**： + +```text +python -m py_compile apps/api/src/jobs/hermes_kb_growth_worker.py apps/api/src/repositories/governance_remediation_dispatch_repo.py apps/api/src/repositories/knowledge_repository.py apps/api/src/services/governance_dispatcher.py apps/api/src/main.py + -> ok +pytest apps/api/tests/test_hermes_kb_growth_worker.py -q + -> 3 passed（第一版） +pytest apps/api/tests/test_hermes_kb_growth_worker.py apps/api/tests/test_km_writer.py apps/api/tests/test_km_writer_idempotent.py -q + -> 28 passed +pytest apps/api/tests/test_hermes_kb_growth_worker.py apps/api/tests/test_governance_dispatcher.py -q + -> 23 passed +pytest apps/api/tests/test_governance_agent.py apps/api/tests/test_governance_dispatcher.py apps/api/tests/test_ai_governance_endpoints.py apps/api/tests/test_hermes_kb_growth_worker.py -q + -> 74 passed +pytest apps/api/tests/test_governance_remediation_dispatch.py -q + -> 29 passed +ruff F/E9 selected files + -> All checks passed +git diff --check + -> pass +``` + +**Production deploy / smoke（完成）**： + +```text +Code commits: + edf97ad8 feat(governance): process hermes km healthchecks + de6dbe07 fix(knowledge): query tags on json columns + 8342cfa4 fix(governance): stop km healthcheck requeue + +Deploy markers: + 53f87375 chore(cd): deploy edf97ad [skip ci] + ac0d2329 chore(cd): deploy de6dbe0 [skip ci] + 07744bf8 chore(cd): deploy 8342cfa [skip ci] + +Gitea Actions: + 1873 Code Review -> success + 1872 CD -> success + 1875 Code Review -> success + 1874 CD -> success + 1877 Code Review -> success + 1876 CD -> success + +K8s image: + awoooi-api / awoooi-web -> 192.168.0.110:5000/awoooi/*:8342cfa46078dd6d0f092beb93eedb64b43b42ab + +GET https://awoooi.wooo.work/api/v1/health + -> healthy, prod, mock_mode=false + +Worker evidence: + -> hermes_kb_growth_loop_started + -> hermes_kb_growth_once_completed scanned=14 processed=14 failed=0 + -> hermes_kb_growth_once_completed scanned=11 processed=11 failed=0 + -> hermes_kb_growth_review_draft_ready emitted with workflow_stage=waiting_owner_review + -> no UndefinedFunctionError after JSON tag hotfix + +GET /api/v1/knowledge?entry_type=auto_runbook&status=review&q=KM%20healthcheck&limit=40 + -> total=85 + -> newest items created_by=hermes_kb_growth_worker + -> status=review, title=KM healthcheck review draft - + +GET /api/v1/ai/governance/queue?dispatch_status=pending&event_type=knowledge_degradation&size=50 + -> first sample pending_total=0 + -> second sample after 90s pending_total=0 + +GET /api/v1/ai/governance/queue?dispatch_status=succeeded&event_type=knowledge_degradation&size=50 + -> succeeded_total=113 + -> workflow_stage=waiting_owner_review + -> next_action=owner_review_km_draft +``` + +**已知技術債**： + +- 第一版 worker 在 production JSON tag 查詢錯誤下造成 failed dispatch rows，後續 hotfix 已停止錯誤並把新 work item 推進到 `waiting_owner_review`；舊 failed rows 保留作為 audit trail，不回寫刪除。 +- 在 requeue hotfix 部署前已產生部分重複 KM review draft；目前新 worker 以 governance event tag 冪等，後續不再為同一 event 產生多份草稿。下一段應補前端去重/治理清理視圖，讓 owner 看到 canonical draft。 +- `AiGovernanceEvent.resolved` 仍未自動關閉，這是刻意保留：`waiting_owner_review` 代表 Hermes 已完成草稿，不代表 KM stale ratio 已恢復到 20% 以下。 + +**目前整體進度**： + +- AwoooP 告警可觀測鏈：約 99%。 +- 低風險自動修復閉環：約 95%。 +- 前端 AI 自動化管理介面同步：約 95.5%。 +- 治理告警可讀性 / 可處置性：約 96.5%。 +- AI Agent ownership 可追溯性：約 95%。 +- KM healthcheck 派工可追蹤性：約 98%。 +- Hermes KB growth 草稿 / owner review 閉環：約 93%。 +- 完整 AI 自動化管理產品化：約 93.8%。 + ## 2026-05-19｜T89 Governance events detail/history dispatch ids 接線 **觸發**：