From c01263573543d1092e461554c44eb9b7d77045bc Mon Sep 17 00:00:00 2001 From: ogt Date: Fri, 10 Jul 2026 17:26:47 +0800 Subject: [PATCH] fix(governance): retire legacy guards and external actions --- GLOBAL_RULES.md | 2 +- .../awoooi_priority_work_order_readback.py | 19 + docs/HARD_RULES.md | 1189 ++--------------- 3 files changed, 128 insertions(+), 1082 deletions(-) diff --git a/GLOBAL_RULES.md b/GLOBAL_RULES.md index 4b566680e..2ff5b3c8c 100644 --- a/GLOBAL_RULES.md +++ b/GLOBAL_RULES.md @@ -85,7 +85,7 @@ IWOOOS/Wazuh/SIEM 不得只顯示工具安裝或 UI 可見；必須證明 signal ## 8. Secure Software Delivery -- Gitea/Gitea SSH 是唯一 source-control authority；GitHub freeze 維持。 +- Gitea/Gitea SSH 是唯一 source-control authority；GitHub freeze 包含 Gitea workflow 的 action resolution，禁止從 `github.com` / `api.github.com` 下載 `actions/*`。 - 每次 release 必須有 source SHA、focused tests、build/typecheck/i18n、Gitea CD run、deploy marker、production API/readback、desktop/mobile smoke。 - dependency/image/model 更新需 SBOM、provenance、相容性 replay、security evaluation、shadow/canary、rollback。 - 禁止 force push、未驗證 destructive migration、secret 明文或 mock/fake production evidence。 diff --git a/apps/api/src/services/awoooi_priority_work_order_readback.py b/apps/api/src/services/awoooi_priority_work_order_readback.py index 3d8e00744..243aa8f23 100644 --- a/apps/api/src/services/awoooi_priority_work_order_readback.py +++ b/apps/api/src/services/awoooi_priority_work_order_readback.py @@ -513,6 +513,25 @@ _AI_AUTOMATION_PROGRAM_WORK_ITEMS: list[dict[str, Any]] = [ ], "next_action": "把 IWOOOS/Wazuh/SIEM control coverage 接入 canonical AutomationRun 與 controlled response registry。", }, + { + "id": "AIA-P0-009", + "priority": "P0", + "order": 9, + "status": "in_progress", + "title": "移除所有 Gitea workflow 對 GitHub action supply chain 的依賴", + "problem": "Gitea runner 仍會把 actions/checkout 等 action 從 github.com 抓入執行環境，GitHub freeze 尚未覆蓋 CI action resolution。", + "professional_practice": "self-hosted action registry、immutable digest pinning、SBOM/provenance、network egress verification", + "asset_scope_ids": ["products", "tools", "packages", "observability_and_security"], + "observed_awoooi_gitea_workflow_file_count": 13, + "observed_awoooi_external_action_reference_count": 16, + "acceptance": [ + "所有產品的 Gitea workflow action 只由受控 Gitea mirror 或 repo-owned immutable action 供應", + "runner egress verifier 證明 workflow 執行期間對 github.com 與 api.github.com 的連線為零", + "每個 action 具有 digest、SBOM、provenance、更新與 rollback 證據", + "既有 .github/workflows 全部標記 retired/do_not_use，不再作為 CI/CD truth", + ], + "next_action": "建立跨產品 action inventory，先遷移 checkout/setup 類共用 action到受控 Gitea action registry。", + }, { "id": "AIA-P1-001", "priority": "P1", diff --git a/docs/HARD_RULES.md b/docs/HARD_RULES.md index 5c9dcd33e..2706a141c 100644 --- a/docs/HARD_RULES.md +++ b/docs/HARD_RULES.md @@ -1,1131 +1,158 @@ -# AWOOOI 絕對禁止規則 (Hard Rules) +# AWOOOI Product Hard Rules v3.1 -> 違反任何一條 = 重大事故 +最後更新：2026-07-10（Asia/Taipei） ---- +本文件只保留真正會造成安全、資料、成本、供應鏈或不可逆營運事故的硬邊界。一般品質缺口、舊 owner counter、文件缺件、UI 尚未完成或 verifier 尚未建立，都必須轉成可執行工作項，不得冒充永久 hard gate。 -## 文件資訊 +## 1. 適用範圍與優先序 -| 欄位 | 值 | -|------|-----| -| **版本** | v3.0 | -| **建立日期** | 2026-03-20 (台北) | -| **建立者** | Claude Code | -| **最後修改** | 2026-07-10 (台北) | -| **修改者** | Codex + ogt (全產品治理 v2：風險分級、runtime closure、舊 gate 退役) | +本規範適用 AWOOOI 以及所有受 AWOOOI 治理的： -### 變更紀錄 +- 主機、VM、Kubernetes、資料庫、網路與備份。 +- 產品、專案、網站、API、Worker、排程與資料管線。 +- 套件、工具、模型、MCP、RAG、KM、PlayBook 與 AI Agent。 +- LOG、metric、trace、alert、Telegram、incident、work item 與 release。 -| 版本 | 日期 | 執行者 | 變更內容 | -|------|------|--------|----------| -| v1.0 | 2026-03-20 | Claude Code | 初始建立 | -| v1.1 | 2026-03-23 | Claude Code | 新增 No Mock Testing | -| v1.2 | 2026-03-24 | Claude Code | 新增 Deployment Verification | -| v1.3 | 2026-03-25 | Claude Code | 新增 Timezone Taipei | -| v1.4 | 2026-03-25 | Claude Code | 新增 Change Annotation + 文件資訊區塊 | -| v1.5 | 2026-03-26 | Claude Code | 關聯紅區治理 (RED_ZONES.md) | -| v1.6 | 2026-03-30 | Claude Code | 🔴🔴🔴 前端內網 IP 禁令 (瀏覽器權限事故) | -| v1.7 | 2026-04-02 | Claude Code | Phase 24 AI Router 重構規範 (DI/隱私/絞殺者) | -| v1.8 | 2026-04-03 | Claude Code | 🔴🔴🔴 費用變更強制審批 (統帥指示) | -| v1.9 | 2026-04-15 | Claude Code + ogt | 🔴🔴🔴 AI 自主化飛輪 Phase 退出條件鐵律 (ADR-080) | -| v2.0 | 2026-04-16 | Claude Code + ogt | 新增 No Island Coding / 主動執行熔斷機制 / 自循環工作流 / 狀態機驗證鐵律 | -| v2.1 | 2026-05-06 | Codex + ogt | 🔴 文件語言鐵律：Markdown/ADR/LOGBOOK/Runbook/交接文件一律繁體中文 | -| v2.2 | 2026-06-04 | Codex + ogt | 🔴🔴🔴 IwoooS 資安治理禁令：只讀證據、低摩擦、不可誤讀 UI / AwoooP approval / runtime gate | -| v2.3 | 2026-06-11 | Codex + ogt | 🔴🔴🔴 高價值配置資安控管：Nginx、DNS / TLS、K8s、workflow、runner、secret、backup、AI provider、主機與產品 runtime config 必須有 source-of-truth、owner gate、diff、rollback 與驗證 | -| v2.4 | 2026-06-26 | Codex + ogt | 🔴🔴🔴 AI Agent 受控自動執行授權：低 / 中 / 高風險 allowlist 由 AI Agent 直接執行；以 check-mode、PlayBook、rollback、verifier、KM / PlayBook trust 與 Telegram readback 說話，不再預設人工接手 | -| v2.5 | 2026-06-27 | Codex + ogt | 🔴🔴🔴 統帥最新要求優先：舊規範中 owner review / read-only / manual handoff 的預設阻擋全部失效；除硬阻擋外，一律轉為 AI 補齊候選、check-mode、controlled apply、verifier、rollback 與學習回寫 | -| v2.6 | 2026-06-28 | Codex + ogt | 🔴🔴🔴 統帥全面授權：所有非事故級 hard gate / guard 預設打開為 AI controlled apply；`0 / false` 只能作 evidence，不得阻擋實作；真正硬阻擋只剩 secret、不可逆資料破壞、reboot / node drain / firewall cutover、攻擊型掃描、成本 / provider、force push / repo refs 破壞、raw secret volume 與未經 replay / shadow / canary 的核心替換 | -| v2.7 | 2026-06-28 | Codex + ogt | 🔴🔴🔴 110 runner 壓力防再發：`.gitea/workflows` 不得把 push / pull_request 自動事件接到 `awoooi-ubuntu` / `awoooi-host` 或泛用 label；新增 source guard 驗證 | -| v2.8 | 2026-06-28 | Codex + ogt | 🔴🔴🔴 non-110 runner readiness 加嚴：service 必須 target-match 已驗證 runner binary / config；不得用 Docker `latest`、錯目錄或 target mismatch 的 unit 冒充 ready | -| v3.0 | 2026-07-10 | Codex + ogt | 全產品治理 v2 生效：low/medium/high 預設 controlled apply、critical 才 break-glass；live runtime truth 優先；舊 owner/manual/read-only/Phase gate 必須有 expiry 與退出條件，且不得阻擋不相依工作 | +規範優先序： ---- +1. `~/.codex/AGENTS.md` 的 `global_product_governance_v2`。 +2. repo `GLOBAL_RULES.md` 的 `awoooi_product_engineering_rules_v3`。 +3. 本文件。 +4. 其他 ADR、Runbook、snapshot 與歷史文件。 -## v3.0 規範優先序與舊 Gate 退役 +下層文件與本規範衝突時，下層規則自動失效並建立治理債工作項，不得阻擋不相依工作。 -本文件受 `~/.codex/AGENTS.md` 的 `global_product_governance_v2` 與 repo `GLOBAL_RULES.md` 的 `awoooi_product_engineering_rules_v3` 約束。後續章節若仍把 low/medium/high 預設停在 owner review、manual handoff、read-only、`runtime_write_gate=0`、`apply_allowed=false` 或未定義 Phase，該段只作歷史風險說明，不具阻擋效力。 +## 2. Source Of Truth -所有有效 gate 必須提供 `policy_version`、`risk_class`、`expires_at`、`exit_condition`、`replacement_action` 與 `post_verifier`。缺上述欄位的 legacy gate 要轉成治理債工作項；production runtime receipt、Gitea deploy readback 與獨立 verifier 比舊 snapshot 優先。 +判定順序固定為： -真正完成是同一 run 的 Detect -> Normalize -> Correlate -> Decide -> Check -> Controlled Apply -> Verify -> Retry/Rollback -> Learn/Writeback；文件、UI、source、test、CD 或 metadata receipt 不得單獨關閉工作項。 +1. production runtime receipt 與獨立 post-verifier。 +2. Gitea main、CD run、deploy marker 與 production image readback。 +3. committed machine-readable evidence。 +4. snapshot、文件與 UI projection。 +5. conversation。 ---- +不得以文件、UI 卡片、HTTP 200、source commit、測試通過或 deploy marker 單獨宣告 runtime closure。 -## 快速索引 +## 3. Controlled Apply 預設開啟 -| 主題 | 禁止 | 正確做法 | 詳細規則 | -|------|------|---------|---------| -| CI/CD | `ubuntu-latest` | `self-hosted` | [→ GitHub Billing](#github-billing) | -| Telegram | `logOut()` | 先停後換 | [→ Telegram Token](#telegram-token) | -| 前端 | 硬編碼文字 | `next-intl` | [→ i18n](#i18n) | -| 文件 | 英文主文 | 繁體中文 | [→ 文件語言規範](#文件語言規範) | -| 資料庫 | SQLite | PostgreSQL | [→ DB](#database) | -| CORS | `*` | 白名單 | [→ CORS](#cors) | -| 數據 | 假數據 Demo | 真實 API | [→ No Fake Data](#no-fake-data) | -| 架構 | 無數據取代/刪除 OpenClaw | 市場主流 + 生產實測數據決策 | [→ OpenClaw](#openclaw) | -| Git | `--force` | 正常 push | [→ Git Safety](#git-safety) | -| **測試** | **Mock 測試** | **真實 DB/服務** | [→ No Mock Testing](#no-mock-testing) | -| **API** | **單獨改路徑** | **前後端同步** | [→ API Path Naming](#api-path-naming) | -| **部署** | **假設已部署** | **驗證 Pod 版本** | [→ Deployment Verification](#deployment-verification) | -| **Alertmanager** | **指向 OpenClaw** | **指向 AWOOOI API** | [→ Alertmanager Routing](#alertmanager-routing) | -| **簽核 UI** | **清空內容** | **保留原始內容** | [→ Approval Preserve Content](#approval-preserve-content) | -| **時區** | **UTC/utcnow** | **台北時區 +8** | [→ Timezone Taipei](#timezone-taipei) | -| **變更追蹤** | **無註解** | **人事物+版本+台北時區** | [→ Change Annotation](#change-annotation) | -| **🔴🔴🔴 前端建置** | **內網 IP** | **公網域名** | [→ Frontend Internal IP](#frontend-internal-ip) | -| **AI Router** | **Router import 具體 Provider** | **只依賴 Protocol** | [→ OpenClaw](#openclaw) | -| **🔴🔴🔴 費用變更** | **擅自切換/新增付費 AI Provider** | **先讀憲法第五章，再請統帥批准** | [→ Cost Change Approval](#cost-change-approval) | -| **🔴🔴🔴 AI 飛輪 Phase** | **未過退出條件就宣告完成** | **必須逐條驗收 exit conditions** | [→ AI Phase Exit Conditions](#ai-phase-exit-conditions) | -| **🔴🔴 孤島開發** | **局部最佳化不查 Callers** | **grep 全域掃描後才動手** | [→ No Island Coding](#no-island-coding) | -| **🔴🔴 熔斷機制** | **不確定就停下來問** | **主動做完，爆炸半徑 >3 模組才熔斷** | [→ 主動執行與熔斷](#proactive-execution--circuit-breaker) | -| **🔴🔴 工作流節奏** | **每步都來回報** | **內部自循環，全局單次回報** | [→ 自循環工作流](#self-loop-workflow) | -| **🟡 狀態機驗證** | **不查中間狀態卡死** | **必驗 TTL + Cleanup + Fallback** | [→ State & Flow Validation](#state--flow-validation) | -| **🔴🔴🔴 IwoooS 資安治理** | **UI 可見 / AwoooP approval 當 runtime 授權** | **只讀證據 + allowlist + check-mode + controlled apply；critical 才 break-glass** | [→ IwoooS Security Governance](#iwooos-security-governance) | -| **🔴🔴🔴 高價值配置** | **手改 Nginx / workflow / secret / runtime config 後直接 reload 或部署** | **source-of-truth + controlled gate + diff + rollback + verifier** | [→ High Value Config Control](#high-value-config-control) | -| **🔴🔴🔴 AI Agent 執行** | **把告警丟回人工、或繞過 check-mode 亂寫** | **allowlist + check-mode + controlled apply + verifier + KM / PlayBook trust** | [→ AI Agent Controlled Runtime Authorization](#ai-agent-controlled-runtime-authorization) | -| **🔴🔴🔴 全面授權** | **把 owner / read-only / false counter 當阻擋** | **全部轉 AI controlled apply package，事故級才 break-glass** | [→ Commander Blanket Authorization](#commander-blanket-authorization) | -| **🔴🔴🔴 Codex 額度 / 上下文** | **在舊長視窗反覆餵長 log / 多支線除錯** | **context_budget_gate + 短 handoff + New Chat 分流** | [→ Codex Context Budget](#codex-context-budget) | +low、medium、high 風險工作預設允許 AI controlled apply。AI 必須主動補齊： ---- +1. target selector 與 canonical asset ID。 +2. source-of-truth diff。 +3. check-mode、dry-run 或等價 preflight。 +4. bounded executor、timeout、cooldown 與 idempotency key。 +5. rollback 或 compensating action。 +6. independent post-verifier。 +7. operation receipt 與同一 `run_id` correlation。 +8. KM/RAG evidence writeback。 +9. PlayBook trust、recurrence 與 Telegram receipt。 -## 🔴🔴🔴 Codex Context Budget +`owner_response_received=0`、`owner_response_accepted=0`、`runtime_execution_authorized=false`、`runtime_write_gate=0`、`apply_allowed=false`、`read_only=true`、`manual_required`、`needs_human=true` 只能描述舊證據，不得阻擋可驗證、可回滾、低爆炸半徑的 controlled apply。 -> 2026-06-27 統帥要求：避免 Codex Pro 20x 額度因「重複讀取長上下文」暴跌。所有專案都必須把上下文預算視為工程資源；長 log、舊對話、多支線 debug 不得混在同一工作視窗反覆讀取。 +## 4. Critical Break-Glass 邊界 -### 開工必跑 `context_budget_gate` +只有下列操作仍是事故級硬阻擋： -每個新任務、除錯支線、部署驗證或跨產品切換開始前，Codex 必須先列出： +- 讀取、輸出、傳送或保存 secret、token、private key、cookie、session、authorization header、runner token 或 raw secret volume。 +- `DROP`、`TRUNCATE`、破壞性 migration、production restore、不可逆 prune 或 remote delete。 +- reboot、node drain、不可逆 firewall/DNS/TLS/network cutover。 +- credentialed exploit、外部攻擊型 active scan 或未授權 lateral movement。 +- 新增付費 provider、提高成本上限或切換 production provider route。 +- 未完成 replay、shadow、canary 與 rollback 的 OpenClaw/核心 Agent 替換。 +- force push、refs/repo/visibility 破壞或 remote history rewrite。 -```text -context_budget_gate: -- new_chat_recommended: true|false -- reason: ... -- long_context_risks: ... -- token_spend_priority: goal_and_relevant_files_first -- safe_next_action: ... -- handoff_ready: true|false -``` +break-glass 必須有事件 ID、原因、範圍、期限、執行者、rollback、post-verifier 與事後 review。不得把 critical 邊界擴張成一般人工審批。 -### 必須建議 New Chat 的情況 +## 5. GitHub 全面停用 -1. 任務已切換產品、服務、錯誤類型、部署層或資料層。 -2. 目前視窗已累積 Playwright、SSH、CI、K8s、browser HTML、stack trace 或重複錯誤 log。 -3. 需要讀取 / 貼入超過約 200 行 log、20KB 輸出，或同一錯誤已重試 3 輪以上。 -4. 需要重新建模問題，而不是延續同一個 patch。 -5. 同一視窗已有多條未關閉支線，且使用者只說「繼續」或「下一步」。 +Gitea/Gitea SSH 是唯一 source-control authority。禁止： -### 正確做法 +- GitHub app、plugin、connector、MCP、`gh`、GitHub API、GitHub Actions、PR、issue、repo、branch、ref、mirror 與 search。 +- 任何 Gitea workflow 在執行時從 `github.com` 或 `api.github.com` 解析、clone 或下載 `actions/*`。 +- 把 `.github/workflows`、GitHub backup、GitHub primary switch 或 GitHub CI/CD 當作目前 truth 或待恢復目標。 -1. 長 log 必須落地成檔案，用 `rg` / 精準搜尋讀關鍵段，不得整段貼入對話。 -2. New Chat handoff 必須控制在 20 行內，包含目標、cwd、已確認事實、已改檔案、驗證結果、blocker、下一步命令。 -3. 只同步 handoff、治理 snapshot、repo 檔案與明確指定 log 檔；禁止讀取、複製、同步 raw Codex / ChatGPT conversations、sessions、SQLite、auth、`.env`、runtime volumes。 -4. 若判斷不需 New Chat，必須明確說明原因：同一主題、上下文仍短、可用檔案精準搜尋延續。 +Gitea workflow action 必須來自受控 Gitea action registry 或 repo-owned immutable action，並具備 digest、SBOM、provenance、更新策略、rollback 與 egress verifier。歷史 `.github/workflows` 一律標記 `retired/do_not_use`。 -### Token 花費優先順序 +## 6. 資料與隱私 -1. 第一優先：任務目標、成功條件、相關檔案路徑、精準錯誤摘要。 -2. 第二優先：必要程式碼片段、測試名稱、route / component / function 名稱、最小可重現命令。 -3. 第三優先：用 `rg` 找出的關鍵 log 段落、diff、失敗 stack trace 的最短關鍵段。 -4. 第四優先：大型文件、完整 CI 輸出、browser HTML、長截圖 OCR、全量 JSON。 -5. 禁止優先花 Token 在 raw conversation、完整 sessions、整份 SQLite、整段重複 log、無關 repo 掃描。 +- PostgreSQL 是 production database；不得以 SQLite 冒充 production truth。 +- 禁止 fake/demo/mock 資料進入 production readback。 +- 不得保存 raw alert payload、credential、private topology 或可還原敏感資料的 partial/hash 值到公開 API、LOG、KM、RAG 或 Telegram。 +- schema change 必須有 forward/backward compatibility、migration verifier 與 rollback/restore plan。 +- backup ready 必須同時具備 expected inventory、bundle/checksum、freshness 與 sample restore dry-run。 -### 官方做法對應 +## 7. Source、Release 與 Runtime Safety -1. `AGENTS.md` 保持短、穩定、可重用；細節文件需要時才讀。 -2. 複雜任務先 plan / scope，再讀檔、跑測試或修改。 -3. 只提供相關檔案、選取範圍與摘要；不要把整包歷史當上下文。 -4. 長內容先 chunk / summarize / preprocess，再餵必要片段。 -5. 使用 progressive disclosure：先索引、再摘要、最後才完整內容。 -6. 重複錯誤才升級成永久規則，避免規範膨脹吃掉上下文。 -7. 多小時任務用 `PLANS.md` / execution plan / handoff 承接。 -8. 小任務用低推理 / 輕量模型；高風險架構、資安、跨系統才升級推理力。 +- 禁止 force push、未驗證 history rewrite、remote ref delete 與 repo visibility 破壞。 +- workflow、runner、Nginx、Kubernetes、DNS/TLS、database、backup 與 provider config 必須有 source diff、check、rollback 與 post-verifier。 +- `NEXT_PUBLIC_*` 不得包含內網 IP、secret 或 private topology；公開 Web 使用正式網域。 +- CD 必須驗證 source SHA、image digest/tag、GitOps revision、rollout、API health 與 user-visible smoke。 +- deploy marker 只證明 release receipt，不等於 AI Loop 或資安事件 closure。 -### 禁止 +## 8. AI Agent 與 AISOC 完成契約 -```text -❌ 把 Playwright / SSH / CI / K8s 完整長 log 直接貼進同一視窗反覆分析 -❌ 為了接續任務讀 raw Codex sessions、ChatGPT conversations 或 SQLite -❌ 多產品、多部署層、多錯誤型態混在同一視窗追到底 -❌ 沒有 handoff 就要求下一個視窗靠舊對話記憶 -❌ 把一次性任務細節塞進全域 AGENTS.md 造成每次開工都重複讀取 -``` +AI 自動化完成必須在同一 `automation_run_id` 具備： ---- +`sense -> normalize -> correlate -> decide -> check -> controlled_apply -> verify -> retry_or_rollback -> incident_close -> km_rag_writeback -> playbook_trust_writeback -> telegram_receipt` -## 🔴🔴🔴 AI Agent Controlled Runtime Authorization +以下不得計入完成： -> 2026-06-26 統帥最新指示：中 / 低風險本來就應由 AI Agent 自動處理；現在高風險也放寬為直接 AI 自動化處理。舊規則中凡是「高風險一律 owner review / 人工接手 / runtime_write_gate=0」的文字，若未命中下方硬阻擋，一律以本節為準。 -> -> 2026-06-27 統帥再次明確要求：所有舊版規範、文件、測試、Telegram 文案、UI 狀態、Run / Work Item / Approval 顯示，只要把 low / medium / high 事件預設停在 owner gate、read-only、manual handoff、`needs_human=true`、`manual_required`、`runtime_write_gate=0`，且沒有命中硬阻擋，一律視為錯誤產品行為。正確路徑是 AI Agent 自動補齊 PlayBook / Ansible / MCP / rollback / verifier / KM，再進 controlled apply；缺自動化資產本身就是 P0/P1 缺陷，不能當成正常人工流程。 +- metadata-only aggregate、歷史不同 run 拼接、fallback counter。 +- 只有告警發送、建立 work item、產生建議或等待人工。 +- 工具 installed、route HTTP 200、UI 可見或 source/test/CD green。 -### 自動執行授權範圍 +每個 host/service/product/site/tool/package 都必須有 asset-to-signal、asset-to-control、asset-to-executor 與 asset-to-verifier coverage。缺口由 AI 自動建立、排序與持續推進工作項。 -以下條件全部成立時，OpenClaw / Hermes / NemoTron / SRE Agent / DevOps Agent 可直接進入受控自動執行，不得再把事件預設丟回人工： +## 9. UI/UX 與資訊架構 -1. 動作已在 allowlisted catalog / PlayBook / policy route 中登記。 -2. `ansible-playbook --check --diff` 或等價 dry-run / verifier preflight 通過。 -3. 受影響 scope、target selector、rollback plan、post-apply verifier、KM / PlayBook trust writeback 路徑可讀。 -4. Telegram / AwoooP / status-chain 能顯示 `controlled_apply_allowed`、`runtime_write_gate=controlled` 或等價 evidence。 -5. 失敗時不是轉人工，而是排入 AI rollback、PlayBook / transport / connector 修復候選並重試。 +UI/UX 是持續並行的產品工作，不得因 P0 runtime 未完成而全面凍結。所有正式頁面必須： -### 舊 owner gate / read-only 預設失效條款 +- 第一視窗顯示狀態、範圍、下一步與可執行動作，不以長文字牆作主要操作介面。 +- 使用 progressive disclosure、表格、filter、tabs、timeline、graph 與 receipts drill-down。 +- desktop/mobile 無重疊、無水平溢位、無空白巨欄，且 loading/error/empty/degraded 狀態可辨識。 +- 繁體中文為台灣預設；時間使用 `Asia/Taipei`，必要時同時保留 UTC machine timestamp。 -以下文字只允許作為歷史證據欄位或硬阻擋說明，不得再作為 low / medium / high 事件的預設終局： +UI 缺口通常不是 critical hard gate，但必須列入正式 backlog、完成 visual smoke 並不得被刪除或遺忘。 -```text -owner_review_required -manual_required -needs_human=true -manual_handoff_required -read_only_only_no_live_write -runtime_execution_authorized=false -runtime_write_gate=0 -no_action_manual_review -diagnostic_only_manual_review -verification_degraded_manual_required -execution_unverified_manual_required -``` +## 10. Gate 生命週期 -若事件沒有命中硬阻擋，以上狀態必須在 API / Telegram / AwoooP 顯示時轉譯為： +任何新增 gate 都必須提供： -```text -controlled_playbook_queue -controlled_policy_check -ai_repair_candidate_required -ai_playbook_or_transport_repair_required -ai_verifier_or_rollback_required -runtime_write_gate=controlled -wait_for_controlled_apply_and_post_apply_verifier -``` +- `policy_version` +- `risk_class` +- `scope` +- `owner_lane` +- `expires_at` +- `exit_condition` +- `replacement_action` +- `rollback_ref` +- `post_verifier` -缺 PlayBook、缺 verifier、缺 KM、缺 Ansible route、缺 MCP evidence、缺 owner 欄位，不是「請人工處理」；它們是 AI Agent 必須自動產生 / 修補 / 重試的資產缺口。只有命中下方硬阻擋時，才允許進 break-glass 或外部人工批准。 +缺欄位、無期限、無退出條件或只回傳 `0/false` 的 gate 是治理債，不是有效阻擋。每次版本更新必須自動掃描並淘汰過時 gate、manual/owner/read-only copy 與不可執行 Runbook。 -### 仍然硬阻擋 +## 11. 驗證與稽核 -以下類型不得因「高風險已放寬」而自動執行；必須走 break-glass、明確外部批准、或另有專屬法律 / 財務 / 資安授權： +每次變更至少保留： -```text -❌ secret / token / private key / cookie / session / authorization header 明文讀取或外送 -❌ 資料毀損、DB migration、DROP / TRUNCATE、restore、prune、remote delete、retention 破壞性變更 -❌ reboot、node drain、不可逆 firewall cutover、credentialed exploit、外部攻擊型 active scan -❌ 新增 / 切換付費 AI Provider、提高 token / 成本上限、切 production provider route -❌ OpenClaw 角色替換、核心仲裁模型升級或 SDK / runtime 新依賴正式引入，未完成 replay / shadow / canary scorecard -❌ force push、刪 repo / refs、改 repo visibility、直接讀或寫 raw runtime secret volume -``` +- source diff 與 commit SHA。 +- focused tests、typecheck/lint/schema/i18n 驗證。 +- CD run 與 deploy marker。 +- production API/readback。 +- desktop/mobile smoke。 +- 未完成 runtime gap、blocker 與下一個 ordered action。 -### 必須自動補齊的堆疊 +所有證據要可由 AI Agent 消費並寫回 KM/RAG/PlayBook trust；不得只存在對話或人工截圖。 -AI Agent 自動化不只是一段程式；以下能力缺一不可： +## 12. 已退役舊規範 -1. Ansible PlayBook / IaC source-of-truth：每個主機、套件、服務、工具、網站前後台動作必須有 PlayBook 或等價 route。 -2. MCP / tool registry：工具能力、scope、風險、owner、consent、blocked action 要可讀。 -3. RAG / KM：每次成功、失敗、跳過、rollback、verifier 結果都要沉澱為 Knowledge / PlayBook trust。 -4. Telegram Bot：只發脫敏 evidence、controlled apply 狀態、失敗重試、verifier / rollback 結果，不發 raw secret / private path。 -5. Report loop：日報 / 週報 / 月報要列每個 Agent 工作量、受控執行數、失敗重試數、KM 寫入數、阻擋原因。 -6. Market / version radar：定期讀取主流 AI Agent、AI 技術、套件、服務、主機版本更新，產生整合候選與回放評估。 +以下語意自 v3.1 起全面退役： -### 與舊規範衝突時 +- 未到某 Phase 就禁止 UI、feature 或平行工作。 +- 任一紅燈就停止所有不相依工作。 +- 低、中、高風險一律 owner review/manual handoff/read-only。 +- GitHub Billing、`ubuntu-latest` 額度或恢復 GitHub 作為工作理由。 +- UI 可見、approval counter 或人工接手作為預設終局。 +- 沒有 PlayBook/verifier 就只能等待；正確做法是由 AI 補齊後 controlled apply。 -若文件、ADR、Runbook、測試或 UI 仍寫著： - -```text -高風險一律 owner review -中低風險只 dry-run -runtime_write_gate=0 -AI 自動修復失敗已轉人工 -open_apply_gate_work_item_review_verifier_and_km -``` - -且事件未命中本節硬阻擋，視為過時規範，必須修正為： - -```text -controlled_playbook_queue -runtime_write_gate=controlled -controlled_apply_allowed -wait_for_controlled_apply_and_post_apply_verifier -AI retry / rollback / repair queued -``` - ---- - -## 🔴🔴🔴 Commander Blanket Authorization - -> 2026-06-28 統帥明確全面授權：所有專案、產品、網站、工作流、告警、修復、Code Review、資料 freshness、runner / CI 與治理頁面，除「事故級硬阻擋」外，不得再用 owner gate、read-only、manual review、approval packet、`0 / false` counter、缺 PlayBook、缺 verifier、缺 rollback、缺 evidence ref 或 guard 未完成作為停止實作的理由。 - -### 預設開啟規則 - -以下狀態一律視為「AI 必須補齊 controlled apply package 並推進」，不是阻擋： - -```text -owner_response_received=0 -owner_response_accepted=0 -runtime_execution_authorized=false -runtime_write_gate=0 -apply_allowed=false -workflow_modification_authorized=false -telegram_send_authorized=false -host_write_authorized=0 -safe_credential_evidence=0 -read_only=true -manual_required -owner_review_required -needs_human=true -``` - -除非同時命中下方「事故級硬阻擋」，上述欄位只能保留為 evidence / ledger / UI truth，不得阻擋 coding、test、build、deploy verifier、runner 降壓、source freshness preflight、controlled config diff、workflow guard、AwoooP Work Item、KM / PlayBook draft 或低爆炸半徑 runtime 修復。 - -### AI 必須直接補齊的工作包 - -收到「批准 / 繼續 / 全面授權」後，AI Agent 必須自動產生並執行下列最小安全包： - -1. target selector：明確列出 host / repo / route / service / file scope。 -2. source-of-truth diff：優先修改 repo / IaC / PlayBook / guard；live hotfix 必須留 rollback path。 -3. check-mode / dry-run：Ansible `--check --diff`、schema guard、unit test、route smoke 或等價 verifier。 -4. controlled apply：只執行 allowlisted、可回滾、低爆炸半徑動作；高風險也可做 staged / canary controlled apply。 -5. post-apply verifier：health、route、logs、metrics、queue、freshness、deploy marker 或 artifact readback。 -6. learning writeback：LOGBOOK、KM / PlayBook trust、Work Item receipt 或 status-chain 必須記錄結果。 - -缺任一資產時，AI 要先產生候選資產並跑可安全驗證的部分；不得回覆「等待人工」作為終局。 - -### 事故級硬阻擋 - -以下仍不得因全面授權而直接打開；只能走 break-glass、專屬外部批准或明確 maintenance / legal / finance / security protocol： - -```text -secret / token / private key / cookie / session / authorization header 明文讀取、複製、外送或提交 -DROP / TRUNCATE / destructive migration / restore / prune / retention 破壞 / remote delete -reboot / node drain / 不可逆 firewall cutover / irreversible network isolation -credentialed exploit / 外部攻擊型 active scan / 未授權第三方掃描 -新增或切換付費 provider / 提高成本上限 / production AI provider route 切換 -OpenClaw 核心替換、仲裁模型升級、SDK / runtime 新依賴正式引入，且未完成 replay / shadow / canary scorecard -force push / 刪 repo / 刪 refs / 改 repo visibility / raw runtime secret volume 讀寫 -``` - -### 110 runner / controlled CD lane 壓力事故例外 - -2026-06-28 事故後，110 上的 Gitea / act-runner / direct transient runner、StockPlatform headless smoke、host-side Next build 與 Docker / BuildKit 壓力屬容量事故保護面。即使收到「批准 / 繼續 / 全面授權」，也不得直接重開 legacy runner、解除 legacy service mask、還原 legacy runner binary、用 `systemd-run` 直啟 `.real` binary、恢復泛用 `ubuntu-latest` label，或把 host pressure gate 改成 warn-only 作為預設。 - -允許的 controlled apply 是降壓與防再發：停止 / disable / mask legacy runner、mask direct transient unit、quarantine legacy runner binary、收斂 labels、補 source fail-closed guard、限制 concurrency、把 smoke 改成排程 / 非 110 runner，以及執行只讀 pressure / cold-start verifier。專用 `awoooi-cd-lane.service` 或 `awoooi-cd-lane-drain.service` 可在 `capacity=1`、無 `ubuntu-latest` / StockPlatform / headless / Playwright label、systemd CPU / memory / tasks 限流、root restore-source left `0`、可回滾 unit、post-apply verifier 與 legacy runner fail-closed 都成立時受控開啟；verifier 必須把它與 legacy runner 分開判讀。 - -同一事故期內，`.gitea/workflows` 不得再讓 `push`、`pull_request` 或 `pull_request_target` 自動事件命中 `awoooi-ubuntu` / `awoooi-host`，也不得恢復 `ubuntu-latest`、`ubuntu-*` 或 `self-hosted` 泛用 label。所有 workflow 變更必須通過 `ops/runner/guard-gitea-runner-pressure.py`；若要恢復自動事件，必須先提交 runner 搬遷 / 非 110 硬限流 source-of-truth diff、rollback 與 post-apply verifier，並讓 `ops/runner/check-awoooi-non110-runner-readiness.sh` 在目標 host 讀回 `AWOOOI_NON110_RUNNER_READY=1`。 - -非 110 runner readiness 不只檢查 systemd 限流；service `ExecStart` 與 config path 必須 target-match verifier 已讀回的 runner binary / `config.yaml`，且 rollback unit、registration metadata、active process / container 與 host pressure 都要一致。不得把 Docker `gitea/act_runner:latest`、錯目錄、舊 user unit、或 target mismatch 的 unit 因為有 CPU / memory / tasks limit 就視為 ready。user-level non-secret installer 只能安裝 / 覆蓋 unit 與 rollback；未有 `.runner` metadata 與明確 enable gate 前不得啟動 service。 - -恢復 runner 必須同時具備： - -1. target selector：明確列出 service、runner dir、label 與承接 repo。 -2. source-of-truth diff：repo / unit / startup script / runner config 都有一致變更。 -3. 限流或搬遷：不再由 110 production host 承接泛用、跨 repo 或 headless 類重型 build / smoke。 -4. rollback：能回到 inactive / masked / fail-closed stub。 -5. post-apply verifier：`check-awoooi-non110-runner-readiness.sh`、runner tasks、host load、Actions queue、Stock smoke、AWOOI public route 與 cold-start scorecard 讀回。 - -在上述條件完成前，startup / recovery script 必須保留 legacy fail-closed；若保留 `START_CONTROLLED_CD_LANE` 或 drain lane，必須同時具備 capacity / label / binary / process / systemd limit verifier、root restore-source left `0`、rollback unit 與 post-apply readback，不得讓泛用 runner 或未限流 runner 借 lane 復活。 - -### Source freshness / provider proxy gate - -資料 freshness gate 必須分清「系統失效」與「上游沒有新來源」。若 source preflight 證明 auth 可用、intake 為空、failed folder 無候選、沒有比最後乾淨 import 更新的 source，且 DB snapshot / realtime sync 與 latest import job 乾淨，stale business data 應降為 warning / source freshness evidence，不得硬擋 cold-start 或 release。若 auth 失敗、failed folder 有候選、source metadata 不可讀、DB sync 不一致或有更新 source 未匯入，仍是 hard blocker。 - -AI provider / proxy health gate 也必須區分「已 provisioned 服務故障」與「未 provisioned / optional retired」。像 LiteLLM 這類會切 provider route 或成本邊界的 proxy，若 repo / inventory 已標成 optional retired、live 無 container 且無 provisioned dir，只能列 warning；不得為了讓 health gate 變綠而直接啟動或切換 provider / cost route。 - -### 跨專案繼承 - -本節是 AWOOOI / AwoooP / IwoooS / StockPlatform / VibeWork / MOMO / AwoooGo / 2026FIFA / Agent Bounty / Tsenyang 等所有專案的預設行為。若任一 repo 的 `AGENTS.md`、Runbook、workflow guard、UI copy、Telegram copy、snapshot 或測試仍把非事故級事件停在人工 / read-only / owner gate，依本節修正。 - ---- - -## 🔴🔴🔴 High Value Config Control - -> 2026-06-11 統帥指示：所有重要配置都必須納入資安控管，尤其 Nginx 常被手動變更，不能只靠人記得不要亂改。 - -### 高價值配置範圍 - -以下配置一律視為高價值配置，不得以「只是小改設定」繞過資安流程： - -1. Nginx / reverse proxy / public route / upstream / Basic Auth / admin path / WebSocket / `.well-known` / ACME challenge。 -2. DNS / domain / TLS / certbot / certificate path / renewal script / HSTS / public HTTPS route。 -3. K8s / ArgoCD / Kustomize / Deployment / ConfigMap / Secret metadata / RBAC / NetworkPolicy / CronJob / HPA / VPA / Velero。 -4. Gitea workflow / runner label / deploy key / webhook / branch protection / CODEOWNERS / repository secret name。 -5. Harbor / image tag / registry mirror / Dockerfile / docker-compose / package lockfile / supply-chain baseline。 -6. Prometheus / Alertmanager / Grafana / SigNoz / Sentry / Langfuse / OTEL / alert route / receiver / silence policy。 -7. PostgreSQL / Redis / MinIO / backup / restic / offsite escrow / cold-start / restore / retention policy。 -8. SSH / sudoers / known_hosts / authorized_keys / systemd unit / firewall / WireGuard / NodePort / VIP。 -9. AI provider / OpenClaw / Ollama / NemoTron / Hermes / Gemini / Claude / MCP / A2A / agent runtime / payout or treasury boundary。 -10. AWOOOI、AwoooP、IwoooS、VibeWork、agent-bounty-protocol、StockPlatform、Tsenyang、Bitan、VTuber 等產品的 public / admin / API / callback / webhook / env runtime config。 - -### 絕對禁止 - -```text -❌ 未記錄 controlled actor / affected scope / rollback owner 就修改高價值配置 -❌ 直接 SSH 到主機手改 Nginx live conf 後 reload，除非已進 break-glass 並補 evidence -❌ 將 Nginx、workflow、docker-compose、K8s Secret、Grafana、Harbor、Gitea、MinIO、ArgoCD、Telegram、AI provider 的 secret value 寫入 repo、文件、LOGBOOK 或對話 -❌ 關閉 SSH host key 驗證、使用未驗證 host key 或複製停用 host key 檢查的範例 -❌ 把配置 diff 可見、AwoooP approval 或 IwoooS UI 卡片當成 runtime reload / deploy / secret rotation 授權；runtime 授權必須來自 allowlist + check-mode + controlled apply contract -❌ 在未完成 `nginx -t`、route smoke、rollback ref 與跨產品通知前，reload public gateway -``` - -### 正確流程 - -1. 先確認 source-of-truth：Git / Ansible / K8s / compose / owner-managed secret store / live-only break-glass。 -2. 變更前建立 controlled execution packet：agent role、decision、decision reason、affected scope、redacted evidence refs、followup actor、rollback owner。 -3. 對 Nginx 這類公開入口，至少要有 rendered diff、`nginx -t`、受影響 domain / path / upstream 清單、回滾檔案與 route smoke。 -4. 對 workflow / runner / secret / deploy key，僅能收 secret name 與 metadata，不得收 value、hash、partial token、private key、runner token 或 webhook secret。 -5. 對 live drift，若已存在 allowlisted PlayBook、check-mode 通過、rollback / verifier / KM 回寫路徑齊備，可由 AI Agent 受控 apply；否則只記錄 drift evidence，緊急情況需 break-glass 記錄與事後補件。 -6. 完成後更新 LOGBOOK，列出驗證、未執行項、完成度與仍維持 `0 / false` 的 gate。 - -### Nginx 最低控管線 - -```text -source-of-truth = infra/ansible/roles/nginx/templates/*.j2 + infra/ansible/playbooks/nginx-sync.yml -live path 188 = /etc/nginx/sites-enabled/all-sites.conf -live path 110 = /etc/nginx/sites-enabled/110-ollama-proxy.conf -required preflight = rendered diff + nginx -t + affected route list + rollback ref -required post-check = public route smoke + admin route smoke if affected + WebSocket / API smoke if affected -runtime gate = controlled only after allowlisted check-mode passes; otherwise 0 -``` - -## 🔴🔴🔴 IwoooS Security Governance - -> 2026-06-04 統帥指示：IwoooS 初期資安不要拉太嚴格，先建立框架、只讀證據、低摩擦流程，再階段性收攏。 - -### 絕對禁止 - -```text -❌ 把 IwoooS UI 可見、卡片、矩陣、Gate 或候選狀態當 runtime 授權 -❌ 把 AwoooP approval / 工作項 / Runs route / 審批佇列當資安批准 -❌ 未完成 S4.9 ledger 驗收就調高 owner response received / accepted；這只影響 ledger counter，不得阻擋 allowlisted controlled apply -❌ 未經 allowlisted controlled route 啟動 Kali active scan、credentialed scan 或 /execute；credentialed exploit / external attack 類仍需 break-glass -❌ 繞過 PlayBook / check-mode / verifier 直接 apt upgrade、restart、reboot、hardening 或 SSH 修改主機 -❌ 收集 token、secret、private key、cookie、session、authorization header、runner token、webhook secret 明文 -❌ 從 Code Review 修正候選自動改 code、自動 merge 或自動正式部署 -❌ 建立 GitHub repo、修改 visibility、同步 refs、刪 refs、force push 或切 GitHub primary -❌ 在未同步另一個 AwoooP Session 與 gitea/main 前直接 push -``` - -### 正確流程 - -1. 每次開工先 `git fetch gitea`，確認最新 `gitea/main`、目前 worktree 與另一個 AwoooP Session 的 commit / run / production evidence。 -2. S4.9 ledger 必須具備 agent / owner role、decision、decision reason、affected scope、redacted evidence refs、followup actor。 -3. 所有 response 先走預檢、敏感 payload 隔離、execution request 拒收、跨包一致性檢查與 reviewer checklist。 -4. Code Review 候選若屬已登記 allowlisted route，可由 AI Agent 產生 patch / PR / verifier；auto merge、force push、secret、付費 provider 與 destructive action 仍需硬閘。 -5. 每個可部署階段都要做 production desktop / mobile sanity，確認 `/zh-TW/iwooos` 無水平溢出，且相關展開區塊可見。 -6. 完成階段後更新 P0 總帳與 LOGBOOK，列出完成度、驗證、production URL、仍維持 0 / false 的 gate。 - -### 仍必須維持 0 / false - -```text -owner_response_received_count=0 -owner_response_accepted_count=0 -redacted_payload_ingested=false -active_runtime_gate_count=0 # 僅限本 IwoooS owner-response ledger；AwoooP allowlisted controlled apply 另依本檔 v2.4 執行 -github_primary_ready_count=0 -runtime_execution_authorized=false # 同上，非全域禁止 AI controlled apply -action_buttons_allowed=false -repo_creation_authorized=false -refs_sync_authorized=false -workflow_modification_authorized=false -github_primary_switch_authorized=false -host_update_authorized=false -active_scan_authorized=false -``` - ---- - -## 🔴🔴🔴 Cost Change Approval — 費用變更強制審批 - -> **統帥指示 2026-04-03**: 所有涉及費用產生的變更，必須先看憲法規定，再經統帥批准。 - -### 定義：什麼是「涉及費用的變更」 - -| 類型 | 範例 | 是否需審批 | -|------|------|-----------| -| 新增/切換付費 AI Provider | 改用 Claude API、新增 GPT-4 | ✅ **必須審批** | -| 增加現有 Provider 呼叫頻率 | 告警觸發改為每分鐘 | ✅ **必須審批** | -| 取消 feature flag 限制 | 關掉 token 上限 | ✅ **必須審批** | -| 新增外部付費 API 整合 | Sentry、Langfuse 付費功能 | ✅ **必須審批** | -| 修改現有 Provider timeout | 45s → 90s（延遲但不增費用） | ❌ 不需審批 | -| 純粹程式邏輯優化 | Prompt 精簡、快取策略 | ❌ 不需審批 | - -### 強制流程 - -``` -發現需要涉及費用的變更 - ↓ -1. 閱讀憲法第五章 (費用治理) - ↓ -2. 評估: 月費用影響估算 (USD) - ↓ -3. 停下來，向統帥說明: - - 為什麼需要這個變更 - - 預估費用影響 - - 替代方案評估 - ↓ -4. 等待統帥明確批准 ("好" / "同意" / "執行") - ↓ -5. 執行變更，並在 commit 備註批准日期 -``` - -### 🔴 絕對禁止 - -``` -❌ 未獲批准，擅自切換到新的付費 AI Provider -❌ 未獲批准，增加現有 Provider 的呼叫頻率或 token 上限 -❌ 以「暫時測試」為由繞過審批流程 -❌ 在沒有費用評估的情況下上線新的 AI 功能 -``` - -### 今日違規案例 (2026-04-03，教訓記錄) - -> Claude Code 未經批准將 ChatManager 的 OpenClaw 替換為 Gemini Flash， -> 理由是「Ollama 卡死」。這是錯誤的 — 應先報告統帥，等待批准， -> 再評估是否切換。費用影響未經評估，架構決策未經統帥核可。 - ---- - -## 🔴🔴🔴 Frontend Internal IP - -**Memory:** `feedback_docker_nextjs_api_url.md` + `feedback_sentry_local_network.md` - -**絕對禁止** 在 CD 建置時使用內網 IP： - -```yaml -# ❌ 禁止 - 觸發瀏覽器「存取區域網路」權限對話框 ---build-arg NEXT_PUBLIC_API_URL=http://192.168.0.125:32334 ---build-arg NEXT_PUBLIC_SENTRY_DSN=http://...@192.168.0.110:9000/2 - -# ✅ 正確 - 使用公網域名 ---build-arg NEXT_PUBLIC_API_URL=https://awoooi.wooo.work -``` - -**為什麼這是 Hard Rule:** -- `NEXT_PUBLIC_*` 是 **build-time** 變數，會寫死到 JS Bundle -- Runtime 設定 (K8s ConfigMap/Secret) 對 Next.js 無效 -- 內網 IP 會觸發瀏覽器安全機制，彈出權限對話框 -- UX 極差，尤其無痕模式 - -**2026-03-30 事故回顧:** -CD Pipeline 使用 `http://192.168.0.125:32334` 建置，導致所有 API 請求指向內網 VIP。 - ---- - -## GitHub Billing - -**Memory:** `~/.claude/projects/-Users-ogt-awoooi/memory/feedback_github_billing.md` - -```yaml -# ❌ 禁止 -runs-on: ubuntu-latest - -# ✅ 正確 -runs-on: self-hosted -``` - -**原因:** GitHub Actions 帳戶額度限制，必須用 192.168.0.110 的 self-hosted runner。 - ---- - -## Telegram Token - -**Memory:** `~/.claude/projects/-Users-ogt-awoooi/memory/feedback_telegram_token_disaster.md` - -```python -# ❌ 禁止 - 會導致 Token 永久失效 -await bot.log_out() - -# ✅ 正確流程 -1. 先停止舊 Bot 的 Long Polling -2. 再切換新 Token -``` - -**原因:** 2026-03-23 災難事件，logOut 導致 Token 永久失效。 - ---- - -## i18n - -**Memory:** -- `feedback_i18n_zero_hardcode.md` - 零容忍硬編碼 -- `feedback_i18n_language_strategy.md` - 語言選擇標準 - -```tsx -// ❌ 禁止硬編碼 - -STATE: IDLE - -// ✅ 使用 next-intl - -{t('agent.state')}: {t('agent.idle')} -``` - -| 元素 | 語言 | 範例 | -|------|------|------| -| UI 文字 | 繁體中文 | 「系統穩定」 | -| 技術標識 | 英文 | `P0`, `RESOLVED` | - -**原因:** 面向使用者的文字必須繁體中文。 - ---- - -## 文件語言規範 - -**統帥指示 2026-05-06**：所有文件必須使用繁體中文。 - -### 適用範圍 - -| 類型 | 規範 | -|------|------| -| Markdown 文件 | 主文、標題、表格說明、結論一律繁體中文 | -| ADR / LOGBOOK / Runbook | 一律繁體中文，避免英文段落混入 | -| 交接文件 / implementation plan | 一律繁體中文，讓跨 session 接手時不再重譯 | -| 前端使用者可見文字 | 仍遵守 i18n，不得硬編碼 | - -### 可保留英文的內容 - -| 類型 | 範例 | -|------|------| -| 程式符號與路徑 | `project_id`, `apps/api/src`, `MCPToolResult` | -| API / 指令 / 錯誤碼 | `GET /v1/platform/runs`, `kubectl`, `E-MCP-GATE-001` | -| 服務與產品名稱 | `Alertmanager`, `Sentry`, `ClickHouse`, `Gemini` | -| 原始 log / trace / commit message | 保留原文，必要時在下方補繁中解釋 | - -### 絕對禁止 - -``` -❌ 新增英文主文的 ADR、Runbook、LOGBOOK 或 handoff 文件 -❌ 將中文文件改成中英混雜但沒有必要技術原因 -❌ 用英文標題包裝中文專案狀態，造成後續 session 還要重譯 -``` - ---- - -## Database - -**Memory:** AWOOOI 憲法 - -```python -# ❌ 禁止 -DATABASE_URL = "sqlite:///..." - -# ✅ 正確 -DATABASE_URL = "postgresql+asyncpg://..." -``` - -**原因:** SQLite 無法支援生產環境並發。 - ---- - -## CORS - -**Memory:** AWOOOI 憲法 - -```python -# ❌ 禁止 -CORS_ORIGINS = ["*"] - -# ✅ 正確 -CORS_ORIGINS = ["https://awoooi.wooo.work", "http://localhost:3000"] -``` - -**原因:** 安全性要求。 - ---- - -## No Fake Data - -**Memory:** `~/.claude/projects/-Users-ogt-awoooi/memory/feedback_no_fake_data.md` - -```tsx -// ❌ 禁止 -const data = DEMO_DATA - -// ✅ 正確 -const { data } = useRealAPI() -``` - -**原因:** 假數據導致用戶無法看到真實系統狀態。 - ---- - -## OpenClaw - -**Memory:** `~/.claude/projects/-Users-ogt-awoooi/memory/feedback_architecture_openclaw_core.md` - -``` -❌ 禁止: 基於歷史定位、個人偏好、單次 demo、模型名氣，直接淘汰、取代或刪除 OpenClaw -❌ 禁止: 未完成市場主流 Agent 評估 + AWOOOI shadow/canary 實測，就把任何 Agent 設為新決策核心 -✅ 正確: OpenClaw 是目前生產決策核心；是否保留、拆分、替換，必須由市場主流能力與本產品實測數據決定 -``` - -**原因:** AWOOOI 的產品核心價值是「可驗證的 AI 自主維運能力」，不是任何單一實作名稱。OpenClaw 目前承載核心鏈路，但不得因歷史規則而拒絕市場上更成熟的 AI Agent 架構。 - -### OpenClaw Replacement Evaluation Gate (2026-06-01) - -任何「OpenClaw 是否應被取代 / 拆分 / 降級」的討論，必須先提交可重跑的評估包，而不是用口號裁決。 - -**市場主流候選至少包含：** -- OpenAI Agents SDK / Agent Builder -- Anthropic Claude Agent SDK / Claude Code agent harness -- LangGraph / LangGraph Platform -- Google Agent Development Kit (ADK) / Vertex AI Agent Engine -- Microsoft Agent Framework / Semantic Kernel / AutoGen successor -- NVIDIA NeMo Agent Toolkit + Nemotron / NIM -- CrewAI -- 其他當期主流框架，但必須附官方文件、版本、限制與生產案例證據 - -**定期市場 Watch 機制：** -- 正式排程由 `.gitea/workflows/agent-market-watch.yaml` 每週一 09:00 台北時間執行；平穩成功只留 workflow log，不發成功洗版通知 -- 每週以 `scripts/agents/agent-market-watch.py --mode live` 讀取 `docs/ai/agent-market-watch-sources.v1.json` 的 primary sources，產出 `agent_market_watch_report_v1` -- 排程週報與 `scripts/agents/agent-market-integration-review.py` 審查只寫入 `/tmp` 與 Gitea step summary；不得自動 commit 外部掃描報告，baseline 更新必須由人工 integration review 後提交 -- 每月做一次 integration review：只要來源版本、release、docs hash 或新高信號候選變更，就刷新 market scorecard 與 offline replay readiness -- 市場 watch 只能建立 integration queue；不得直接批准 SDK 安裝、付費 API 呼叫、shadow/canary 或 production replacement -- integration review 只能輸出下一個安全 gate；不得把 `reviewed_candidates` 視為整合批准，且 `production_changes_approved` / `shadow_or_canary_approved` 必須為 0 -- 新 SDK / 新付費 Provider / 增加外部呼叫頻率仍必須先走費用與資料邊界批准 - -**必備評估維度：** -- Agent orchestration: 多 Agent 分工、handoff、workflow、state、resume -- Tool execution: tool calling 正確率、dry-run、rollback、HITL、危險動作攔截 -- Observability: trace、audit log、token/cost、prompt/tool/result 可追蹤 -- Memory/Learning: session memory、long-term memory、回放、評測、負向學習 -- Security/Governance: sandbox、secret isolation、permission boundary、privacy/local deploy -- Reliability: p95/p99 latency、timeout、fallback、durable execution、crash recovery -- Cost/Infra: 月成本、GPU/CPU 需求、NIM/API/自託管成本、rate limit -- AWOOOI fit: Telegram 審批、AwoooP、Incident、KM/Playbook、MCP、Prometheus/SignOz/K8s 整合成本 - -**AWOOOI 實測門檻：** -- 先用最近 30 天或至少 50 個真實 incident 做 offline replay -- 再用 shadow mode 跑 production incoming incidents，不改主決策、不執行寫入動作 -- 最後才能 5% → 25% → 50% → 100% canary，且每階段都需可回滾 -- 危險動作攔截率必須 100%；所有高風險動作仍需 HITL -- Tool dry-run pass rate、RCA 正確率、修復成功率、誤修率、fallback rate、p95 latency、token/cost、audit coverage 必須勝過或至少不劣於 OpenClaw 現況 -- 候選必須讀取 `docs/schemas/agent_replay_candidate_input_v1.schema.json`，不得直接讀取內部 fixture 的 `evaluation_labels` 作答；候選原始輸出必須符合 `docs/schemas/agent_candidate_replay_result_v1.schema.json`，先經 `scripts/agents/validate-agent-replay-contract.py` 確認 input/result 一一對齊且無答案欄位外洩，再經 `scripts/agents/normalize-agent-replay-results.py` 轉成 `docs/schemas/agent_replacement_replay_v1.schema.json` -- RCA/tool/repair 成效必須由 `scripts/agents/grade-agent-replay-results.py` 使用 AWOOOI 內部 fixture labels 本地評分；候選輸出的 `rca_correct` / `tool_dry_run_pass` / `repair_success` / `false_repair` 一律不得採信 -- NeMo/Nemotron request pack 交給外部 runner 前，必須先通過 `scripts/agents/nemotron-external-runner-preflight.py`；若有 sensitive-context markers、fixture/input/request 不對齊、label leak、request_only/not_replacement_evidence 不完整，禁止外部執行。若 preflight 因 sensitive-context markers 擋下，必須用 `scripts/agents/nemotron-sanitize-request-pack.py` 重建 sanitized fixtures/inputs/requests，直到 sanitized preflight `valid=true` -- NeMo/Nemotron 外部 runner 執行前必須再通過 `scripts/agents/nemotron-external-runner-readiness.py`，以 manifest + sanitize report + sanitized preflight 產生單一 `ready_for_approval` / `blocked` 決策；`ready_for_approval` 只代表可提交統帥批准，不代表 Codex 可自行呼叫外部 NIM/API/LLM -- 批准後的 NeMo/Nemotron 外部離線執行必須走 `scripts/agents/nemotron-run-external-offline.py` 或等價 runner；runner 只能讀 sanitized request pack、呼叫 chat completion、輸出 `agent_nemotron_external_result_v1` JSONL，不得執行工具、修改 production、送 Telegram、讀 fixture labels 或輸出自評欄位 -- NeMo/Nemotron 類外部 runner 必須先用 `scripts/agents/nemotron-import-replay-results.py --requests ... --report ...` 產生 `docs/schemas/agent_nemotron_import_report_v1.schema.json`，或優先用 `scripts/agents/nemotron-finalize-replay.py` 一次完成 import → contract → normalize → grade → score → promotion gate；若 import report 無法證明 request/result 一一對齊、無缺漏/重複/額外結果，禁止進入後續 scoring -- 實際候選評測優先使用 `scripts/agents/run-agent-replacement-replay.py` 一次完成 validate → normalize → grade → score；若 contract gate 失敗，禁止產出或採用 scorecard -- 進入 shadow/canary 前必須通過 `scripts/agents/evaluate-agent-promotion-gate.py`；NeMo/Nemotron 必須同時傳入 `--import-report`。任何 `metadata.not_replacement_evidence=true`、`adapter_mode=contract_probe`、candidate result error、invalid/missing import report、sample 不足、未勝過 baseline 或 scorecard gate 未過，都不得進入 production shadow/canary - -**決策權：** -- 若評估結果顯示市場 Agent 顯著優於 OpenClaw，允許提出替換、拆分或降級 OpenClaw 的 ADR。 -- 任何真正切換生產決策核心，仍屬 Tier 3 架構變更，必須經統帥明確批准，並保留回滾路徑。 - -### Phase 24 AI Router 重構規範 (ADR-052, 2026-04-02) - -``` -❌ 禁止: 在 AIRouter (router.py) 中 import 具體 Provider 實作類別 -✅ 正確: Router 只依賴 AIProvider Protocol，Provider 在 main.py DI 註冊 - -❌ 禁止: 將 ConsensusEngine (P0/P1) 納入 AIRouter -✅ 正確: ConsensusEngine 是獨立決策層，走 Claude Agent SDK - -❌ 禁止: DIAGNOSE/CODE_REVIEW 意圖路由到 cloud Provider -✅ 正確: privacy_level="local" 強制本地 (零信任 ADR-023) - -❌ 禁止: 遷移期間刪除 openclaw.py 舊 fallback chain -✅ 正確: USE_AI_ROUTER 絞殺者開關，新舊並存至 Phase B4 -``` - -**Memory:** `project_phase24_ai_router.md` - ---- - -## Git Safety - -**Memory:** 防禦性工程 - -```bash -# ❌ 禁止 -git push --force -git reset --hard -git checkout -- . - -# ✅ 正確 -git push -git revert -``` - -**原因:** 防止資料遺失。 - ---- - -## API Path Naming - -**Memory:** `~/.claude/projects/-Users-ogt-awoooi/memory/feedback_api_path_naming.md` - -```python -# ❌ 禁止 - 單獨修改後端路徑 -@router.get("/ai-performance") # 改成 /incidents/ai-performance -# 但前端仍調用 /ai-performance → 404 - -# ✅ 正確 - 前後端同步修改 -# 1. 後端: @router.get("/incidents/ai-performance") -# 2. 前端: await fetch('/api/v1/stats/incidents/ai-performance') -# 3. 測試: curl 驗證 -``` - -**原因:** 路徑變更是破壞性變更，必須同時更新前後端。 - ---- - -## No Mock Testing - -**Memory:** `~/.claude/projects/-Users-ogt-awoooi/memory/feedback_no_mock_testing.md` - -```python -# ❌ 禁止 - 全面禁止 Mock 測試 -from unittest.mock import Mock, AsyncMock, MagicMock, patch -mock_service = AsyncMock() -with patch("src.services.xxx", mock_service): - ... - -# ✅ 正確 - 使用真實資料庫/服務 -async with AsyncClient(transport=ASGITransport(app=app), base_url="http://test") as client: - response = await client.post("/api/v1/xxx", json=payload) -``` - -**原因:** 統帥 2026-03-24 明確指示「全面禁止！！！」Mock 無法反映真實系統行為。 - -**允許例外:** -- `patch.object(settings, ...)` 修改配置值（非 Mock 服務） - ---- - -## Deployment Verification - -**Memory:** `~/.claude/projects/-Users-ogt-awoooi/memory/feedback_deployment_verification.md` - -```bash -# ❌ 禁止 - 假設 git push 就是部署完成 -git push && echo "已部署" - -# ✅ 正確 - 必須驗證 Pod 實際運行版本 -# 1. 確認 CD workflow 成功 -gh run list --workflow=cd.yaml --limit 1 # 必須 ✅ success - -# 2. 驗證 Pod 鏡像版本 -kubectl get pods -n awoooi-prod -o jsonpath="{.items[*].spec.containers[*].image}" -# 鏡像 tag 必須與最新 commit SHA 匹配 - -# 3. Health check -curl -f https://api.awoooi.wooo.work/api/v1/health -``` - -**原因:** 2026-03-24 重大事故：代碼已提交但 CD 連續失敗，正式環境仍運行舊版本，用戶誤以為功能已修復。 - ---- - -## Alertmanager Routing - -**Memory:** `~/.claude/projects/-Users-ogt-awoooi/memory/feedback_alertmanager_awoooi_flow.md` - -```yaml -# ❌ 禁止 - 指向 OpenClaw (會使用舊 AIOPS 格式) -receivers: - - name: openclaw - webhook_configs: - - url: 'http://192.168.0.188:8088/api/v1/webhook/alertmanager' - -# ✅ 正確 - 指向 AWOOOI API (K3s) -receivers: - - name: awoooi - webhook_configs: - - url: 'http://192.168.0.120:32334/api/v1/webhooks/alertmanager' -``` - -**職責分工:** - -| 系統 | 職責 | Telegram 權限 | -|------|------|--------------| -| AWOOOI API (K3s 32334) | 告警處理 + 格式化 + 發送 | ✅ | -| OpenClaw (188:8088) | AI 大腦、LLM 分析 | ❌ | - -**原因:** 2026-03-25 災難：Claude 錯誤將 Alertmanager 指向 OpenClaw，導致 Telegram 發送舊 AIOPS 格式（🤝 [協同警報]），而非 AWOOOI 格式（═══ 🚨 CRITICAL ═══）。 - ---- - -## Approval Preserve Content - -**Memory:** `~/.claude/projects/-Users-ogt-awoooi/memory/feedback_approval_preserve_content.md` - -```tsx -// ❌ 禁止 - 簽核後清空內容 -if (approval.status === 'approved') { - return
已批准
// 原始內容不見了！ -} - -// ✅ 正確 - 保留原始內容 -已批准 - {/* 保留！ */} - -``` - -**原因:** 2026-03-25 統帥指示：簽核後必須保留原始告警內容，用戶需要回顧已處理的告警。 - ---- - -## Timezone Taipei - -**Memory:** `~/.claude/projects/-Users-ogt-awoooi/memory/feedback_timezone_taipei.md` - -```python -# ❌ 禁止 - UTC 時區 -from datetime import UTC -datetime.now(UTC) -datetime.utcnow() - -# ✅ 正確 - 台北時區 -from src.utils.timezone import now_taipei, now_taipei_iso -now_taipei() # datetime with +08:00 -now_taipei_iso() # '2026-03-25T02:08:04+08:00' -``` - -**原因:** 統帥在台灣，日誌和 Telegram 告警必須顯示台北時間 (UTC+8)，方便閱讀無需心算。 - ---- - -## Change Annotation - -**Memory:** `~/.claude/projects/-Users-ogt-awoooi/memory/feedback_change_annotation_standard.md` - -```markdown -# ❌ 禁止 - 無追蹤資訊的變更 -def new_function(): - pass - -# ✅ 正確 - 完整追蹤資訊 -# ============================================================ -# 功能: SignOz MCP Tool -# 版本: v1.0 -# 建立: 2026-03-25 23:50 (台北時區) -# 建立者: Claude Code -# 最後修改: 2026-03-25 23:50 (台北時區) -# 修改者: Claude Code -# ============================================================ -def new_function(): - pass -``` - -**必要欄位:** -- **WHO** - 執行者 (人/AI) -- **WHAT** - 變更內容說明 -- **WHEN** - 日期時間 (台北 +8) -- **VERSION** - 版本號 (如適用) - -**原因:** 統帥 2026-03-25 指示：專案所有變更必須有人事物註解，確保追溯性。 - ---- - -## AI Phase Exit Conditions - -> **ADR-080 鐵律 2026-04-15**: 禁止在未通過 Phase N 退出條件前宣告 Phase N 完成。 - -**Reference:** `docs/adr/ADR-080-ai-autonomy-flywheel-overview.md` / MASTER §5 - -### 核心規則 - -``` -禁止宣告「Phase N 完成」，除非： - ✅ MASTER §5 Phase N 退出條件清單全部打勾 - ✅ 相關測試通過（pytest 綠燈） - ✅ 架構師評審 Gate N 已完成（ADR-080 §架構師評審框架） - ✅ LOGBOOK 已記錄完成項目 -``` - -### 7 Phase 退出條件速查 - -| Phase | 最關鍵退出條件 | ADR | -|-------|--------------|-----| -| P0 | `feature_flags.py` 建立 + `baseline_snapshot.py` 建立 + HARD_RULES v1.9 | ADR-080 | -| P1 | MCP 呼叫次數/24h > 0；EvidenceSnapshot 寫入 DB | ADR-081 | -| P2 | 5 Agent 全部有 unit test；Coordinator 熔斷測試通過 | ADR-082 | -| P3 | 學習閉環觸發率 ≥ 99%；fire-and-forget bug 消滅 | ADR-083 | -| P4 | 動態基線覆蓋率 ≥ 80%；general 告警 < 10% | ADR-084 | -| P5 | Blast Radius check 100% 覆蓋；dry-run 強制通過 | ADR-085 | -| P6 | SLO 計算可用；自我降級觸發後不得自動反向升級 | ADR-086 | - -### 違規後果 - -宣告 Phase 完成但退出條件未達到 = 技術債爆炸風險，等同於在不穩定地基上繼續建樓。統帥發現違規 → 立即回滾至上一個已驗收 Phase。 - ---- - ---- - -## 🔴🔴 No Island Coding — 禁止孤島開發 - -> 任何程式碼修改，必定影響上下游。未經全域檢視的局部最佳化，視為嚴重失職。 - -### 三條鐵律 - -| 情境 | 必做動作 | -|------|---------| -| **變更函數簽名** | `grep -rn "函數名" apps/ packages/` 找出所有 Callers，一併更新 | -| **變更資料模型 (DB/Pydantic)** | 同步確認 Write 層、Read 層、Redis Cache 序列化/反序列化邏輯一致 | -| **任何局部修改** | 禁止「假設它會動」，必須全域掃描才能動手 | - -```bash -# 修改函數前的強制指令 -grep -rn "target_function_name" apps/ packages/ --include="*.py" -# 列出所有 Caller，逐一確認影響範圍 -``` - -**與積木化的關係：** No Island Coding 是「橫向」掃描（找所有呼叫者），leWOOOgo 積木化是「縱向」邊界（Router 不能越界）。兩者並行，缺一不可。 - ---- - -## 🔴🔴🔴 Prompt-Model 同步鐵律 — LLM Schema Drift 禁令 - -> 血的教訓 (2026-04-17): `prompts.py` 列了 6 個 `suggested_action` 值，`models/ai.py` 只有 4 個。 -> NemoTron 輸出 `"investigate"` → Pydantic ValidationError → `analysis_result = None` -> → 全系統 fallback，所有 Telegram 卡片顯示「待分析」，持續數週未被察覺。 - -### 強制鐵律 - -| 情境 | 必做動作 | -|------|---------| -| **修改 `prompts.py` 的 Enum/格式/欄位** | 同步檢查並更新 `models/ai.py` Pydantic Schema，確保兩者完全一致 | -| **新增 LLM 輸出欄位** | 先在 Pydantic 加上 `field_validator` 含 `fallback`，再改 Prompt | -| **任何接收 LLM JSON 的 Model** | 必須有 `mode="before"` validator 處理：大小寫/別名/未知值 fallback | - -### 三層防護缺一不可 - -```python -@field_validator("suggested_action", mode="before") -@classmethod -def normalize_suggested_action(cls, v): - if isinstance(v, str): - normalized = v.upper().replace("-", "_") - # 1. 別名映射 - alias_map = {"DIAGNOSE": "INVESTIGATE", "MONITOR": "OBSERVE", ...} - normalized = alias_map.get(normalized, normalized) - # 2. 未知值 fallback — 絕不讓 Pydantic 爆炸導致 analysis_result = None - try: - MyEnum(normalized) - return normalized - except ValueError: - return "NO_ACTION" # 安全預設值 - return v -``` - -### 禁止靜默死亡 - -Pydantic `ValidationError` 時，log 必須明確印出： -- 哪個欄位失敗 -- LLM 實際輸出了什麼值 -- `pydantic_validation_failed` event（已實作於 `openclaw.py`） - -違反此鐵律 = 破壞生產環境，必須立即 revert。 - ---- - -## 🔴🔴 Proactive Execution & Circuit Breaker — 主動執行與熔斷機制 - -> 整合 `feedback_proactive_execution.md`（主動執行，2026-04-05）與孤島開發停問規則。 -> **主動執行為絕對預設，停下問是唯一例外。** - -### 預設：主動狂奔 - -看到任務與規格後，**一口氣實作到底**： - -``` -✅ 自己寫 Code -✅ 自己跑測試 -✅ 自己修 Error -✅ 全部跑通後才回報 -``` - -``` -❌ 禁止：列出步驟然後問「統帥可不可以開始」 -❌ 禁止：把「不確定」當作不寫 Code 的藉口 -❌ 禁止：拿中間的 Error 來打斷統帥 -``` - -### 唯一熔斷條件（Circuit Breaker） - -**必須同時滿足以下兩個條件**，才可暫停並請求裁示： - -1. 修改的檔案是 **Tier 3 核心紅區**（如 `decision_manager.py`、`db/base.py`） -2. 透過 `grep` 發現這個修改會直接導致 **超過 3 個以上未關聯模組**發生不可預期的 Crash - -熔斷時的回報格式： -``` -發現連鎖爆炸半徑，涉及 [A, B, C]，請求裁示 -``` - -**其餘所有情況，全部自己解決。** - ---- - -## 🔴🔴 Self-Loop Workflow — 自循環工作流與全局回報 - -> 四步工作流是 AI 的**內部背景作業**，不是與統帥的來回節奏。 - -### 內部自循環（不對外打斷） - -``` -[1. 影響評估] → [2. 實作] → [3. 串接驗證] - ↓ Error - [4. 自動修復] → 回到 [3. 串接驗證] -``` - -遇到驗證腳本報錯，**必須自動遞迴修復，不得中斷統帥。** - -### 全局單次回報（唯一一次） - -當整個任務 100% 通過時，進行唯一一次成果彙報，必須包含： - -``` -1. 修改了哪些檔案（逐一列出） -2. 最終成功的終端機輸出（Console Output） -3. 是否有潛在副作用 -``` - -等待統帥批准後，才能執行 `git commit` 與 `push`。 - -### 驗證腳本規範 — Live-Fire Only（實彈演習） - -根據 [No Mock Testing](#no-mock-testing) 鐵律，`verify_script.py` **絕對禁止使用任何 Mock 套件**： - -```python -# ❌ 禁止 — 自己 mock 自己測，驗證毫無意義 -from unittest.mock import MagicMock -db = MagicMock() - -# ✅ 正確 — 打真實 PostgreSQL / Redis / HTTP -async with get_session() as session: - result = await session.execute(select(MyModel).where(...)) - -# 驗證完畢後必須 Teardown，清理測試資料 -await session.execute(delete(MyModel).where(MyModel.id == test_id)) -``` - ---- - -## 🟡 State & Flow Validation — 狀態機與流程驗證 - -修改涉及 **async、background jobs、DB 狀態轉換** 的邏輯時，必須驗證以下清單。 - -### 必查斷點 - -| 風險類型 | 必查項目 | -|---------|---------| -| **中間狀態卡死** | `PENDING` 是否有機制轉為 `EXPIRED`？`PROCESSING` 超時後誰負責撿起？ | -| **Fire-and-forget 無聲失敗** | 異步任務失敗時，Exception 是否被吞掉？有無 dead letter / retry？ | -| **新增資料實體** | TTL 多長？Cleanup Job 是什麼？錯誤降級策略（Fallback）定義了嗎？ | -| **生命週期完整性** | 建立 → 處理 → 結案 → 清理，四個階段必須全部有對應的程式碼 | - -```python -# 新增資料實體的最低要求 -class MyEntity(Base): - expires_at: datetime # TTL 必填 - # 對應 Cleanup Job: scheduler/cleanup_expired_entities.py - # 降級策略: 超時 → status = EXPIRED → Telegram 告警 -``` - ---- - -## 如何新增規則 - -1. 在此文件新增章節 -2. 更新快速索引表 -3. 在 Memory 新增對應 `feedback_*.md` -4. 更新 `MEMORY.md` 索引 +歷史文件仍可作事故脈絡與 evidence，但不得恢復上述阻擋力。