From 72bd8e1e5407a14a414dd17c76e6988cd292de0a Mon Sep 17 00:00:00 2001 From: ogt Date: Thu, 2 Jul 2026 12:58:55 +0800 Subject: [PATCH] =?UTF-8?q?=E6=95=B4=E7=90=86=20PChome=20AI=20=E8=87=AA?= =?UTF-8?q?=E5=8B=95=E5=8C=96=E5=84=AA=E5=85=88=E5=B7=A5=E4=BD=9C=E6=B8=85?= =?UTF-8?q?=E5=96=AE?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 1 + docs/AI_INTELLIGENCE_MODULE_SOT.md | 1 + .../pchome_ai_automation_priority_backlog.md | 214 ++++++++++++++++++ 3 files changed, 216 insertions(+) create mode 100644 docs/guides/pchome_ai_automation_priority_backlog.md diff --git a/AGENTS.md b/AGENTS.md index 6595fcc..2dc76d3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -142,6 +142,7 @@ - Browse.sh 爬蟲診斷手冊: `docs/guides/browse_sh_crawler_playbook.md` - Webcrumbs 共用 UI Runtime: `docs/guides/webcrumbs_shared_runtime.md` - PChome 業績成長 UI/UX 守門: `docs/guides/pchome_growth_ui_ux_guardrails.md` +- PChome AI 自動化優先工作清單: `docs/guides/pchome_ai_automation_priority_backlog.md` - 外部專業 Benchmark: `docs/guides/external_professional_benchmark.md` - AI 競價情報 SOT: `docs/AI_INTELLIGENCE_MODULE_SOT.md` - Agent 角色矩陣: `docs/guides/codex_agent_roles.md` diff --git a/docs/AI_INTELLIGENCE_MODULE_SOT.md b/docs/AI_INTELLIGENCE_MODULE_SOT.md index ee125d3..96ab07e 100644 --- a/docs/AI_INTELLIGENCE_MODULE_SOT.md +++ b/docs/AI_INTELLIGENCE_MODULE_SOT.md @@ -83,6 +83,7 @@ - V10.642 起 `/ai_intelligence` 的摘要卡與商品處理數字不可只跳到大區塊；點擊後必須開啟商品明細面板，列出商品名稱、分類、近 7 天業績、業績變化、MOMO 比價狀態與下一步按鈕。明細需至少支援全部、價格壓力、價格優勢、待確認、缺比價與有外部價切換；外部價格風險分佈也必須能一鍵篩選下方表格。 - V10.643 起 `/ai_intelligence` 的商品明細上方必須提供「商品策略分流」視覺摘要，至少包含價格壓力、價格優勢、待確認、缺比價四類；每一類需顯示件數、近 7 天業績與比例條，且可點擊切換明細。舊 KPI 卡也不得是靜態數字，需可導向全部商品、可處理商品、高風險比價或處理紀錄。 - V10.725 source-ready 起 PChome growth 必須提供 `/api/ai/pchome-growth/ai-automation-readiness` 與 Dashboard「AI 主流程」狀態列；同一摘要要聚合缺口偵測、同款搜尋包、候選決策包、證據收據與受控落地，並明確輸出 `primary_human_gate_count=0`、`automation_policy.primary_flow=ai_controlled`。PChome mapping 不得把 AI 例外決策當主流程；所有例外都要進 AI machine-verifiable auto-resolution，產生 failure reasons、下一個機器動作與 rollback/readback 路徑。 +- 2026-07-02 起 PChome AI 自動化主線工作順序以 `docs/guides/pchome_ai_automation_priority_backlog.md` 為可執行 backlog；使用者中途插入的 production truth、版本不得錯、GitHub freeze、推版到 Gitea/正式環境、AI 自動化取代人工主流程、外部專業 benchmark、主流專業產品網站、實作結果與完整優先順序要求，都必須列入 backlog 並依 P0/P1/P2/P3/P4 推進。未在 backlog 的支線不得蓋過 P0 runtime truth / controlled apply closure。 - V10.644 起 `/ai_intelligence` 的商品明細列不得只用句子描述比價；每列必須顯示 PChome 價格、MOMO 參考價、差距、可信度四格價格證據，並保留下一步按鈕。單位價候選需顯示單位價與單位，候選待確認或缺資料則以「待補 / 候選待確認」呈現，不得捏造價格。 - V10.645 起 `/ai_intelligence` 的商品明細分流切換後，必須顯示「這類商品怎麼處理」的行動摘要，包含件數、近 7 天業績、平均可信度、最大價差、代表商品與主按鈕；使用者不得只能看到商品列表而不知道下一步。 - V10.646 起 `/ai_intelligence` 的商品明細必須提供搜尋與排序；搜尋至少涵蓋商品、分類、商品編號與 MOMO 候選資訊，排序至少支援優先級、近 7 天業績、價差、下滑幅度與可信度。搜尋/排序後的行動摘要與明細列表必須使用同一批結果。 diff --git a/docs/guides/pchome_ai_automation_priority_backlog.md b/docs/guides/pchome_ai_automation_priority_backlog.md new file mode 100644 index 0000000..6275792 --- /dev/null +++ b/docs/guides/pchome_ai_automation_priority_backlog.md @@ -0,0 +1,214 @@ +# PChome AI 自動化優先工作清單 + +> 最後更新: 2026-07-02 Asia/Taipei +> 範圍: PChome growth / MOMO mapping AI 自動化主線 +> 真相來源: Gitea `dev` / `main`、正式環境 `/health`、正式 DB readback、machine-verifiable artifacts + +## 不可遺漏的插入需求 + +以下是使用者在主線推進期間插入、且必須保留在完整工作項目裡的要求。後續不得再把這些需求漏掉或變成口頭提醒。 + +1. 正式環境才是最新版本真相；不得用本機檔案、舊筆記、舊分支蓋過 production truth。 +2. 版本不得搞錯；目前正式環境 `/health` 版本維持 `V10.725`，除非有明確版本 bump、部署與 readback。 +3. GitHub 全面 freeze；不得使用 GitHub、`gh`、GitHub API、GitHub Actions、PR、issue、mirror 或 read-only GitHub 流程。 +4. 實作結果必須推到 Gitea `dev` 與 `main`；若改到 runtime 行為，還必須部署到正式環境並回讀。 +5. 主方向是 AI 自動化，不是人工審核；人工欄位只能當 evidence / ledger / UI truth，不得阻擋低爆炸半徑、可驗證、可回滾的 controlled apply。 +6. 每條主線都要產生實作結果；不能只交計畫、UI 卡片、文件或口頭盤點。 +7. 中途插入的所有需求都必須進入本 backlog，且標明優先順序與狀態。 +8. 所有工作必須照優先順序推進；除非高優先 blocker 要求，否則不得開支線偏離。 +9. 產品體驗要往主流、專業產品網站前進：AI 狀態可見、下一步清楚、繁中介面、營運儀表板密度足夠、一般產品頁不暴露 raw engineering terms。 +10. 必須參考外部主流專業網站 / SaaS / observability dashboard 做法：狀態分層、下一步優先、收據可追蹤、drift 監控、automation health visibility。 +11. AI 技術自動化要升級為可見能力：agent status、controlled apply、artifact receipts、drift verifier、rollback / re-apply evidence，不能把隱藏人工 gate 當主流程。 +12. 每次宣稱完成都必須列出 source truth、runtime truth、測試、production readback、artifact / blocker 狀態。 +13. 不把工作丟回給使用者；Codex 收到「批准 / 繼續」後，必須主動補齊 target selector、dry-run / check-mode、rollback、post-apply verifier 與回讀證據。 +14. 需要同時看清楚所有工作狀態：已完成、進行中、未開始；不能只報正在做的一小段。 + +## 優先順序總表 + +| Priority | 主線 | 狀態 | 為什麼排這裡 | +|---|---|---|---| +| P0 | Runtime truth + AI controlled apply closure | 進行中，核心閉環已完成多段 | 先證明 AI 真的在正式環境可執行、可回讀、可驗證、可回滾 | +| P1 | 產品可視化 + 專業網站體驗 | 進行中 | 使用者要看得到實作結果，AI 自動化不能只藏在 artifact / log | +| P2 | 外部主流 benchmark 落成 guardrails | 未開始 | 把主流專業做法變成可測規則，不只是參考口號 | +| P3 | 擴大 AI 自動化覆蓋面 | 未開始 | 把目前 PChome retry lane 的閉環模式複製到更多安全場景 | +| P4 | Source / deployment governance | 持續進行 | 保證版本、Gitea、正式環境、DB 安全紅線不再混亂 | + +## P0 - Runtime Truth And AI Controlled Apply Closure + +狀態: 進行中，核心閉環已完成多段。 + +目的: 先讓 PChome mapping automation 在正式環境真的 execute、verify、stay correct。 + +已完成: + +- 正式環境版本真相 guard：`/health` 是最高真相，目前維持 `V10.725`。 +- Gitea `dev` / `main` source truth 對齊。 +- Retry exception controlled apply executor 已落地，目標表為 `pchome_product_matches`。 +- 正式 DB 已 controlled apply 4 個 selectors: + - `14560744 -> DDBH21-A900I79YR-002` + - `8932783 -> DDBH21-A900I79YR-002` + - `15132753 -> DDBH21-A900I79YR-002` + - `14941743 -> DDBH21-A900I79YR-002` +- Executor receipt 已 materialize。 +- Receipt replay closeout 已用 artifacts 與 DB readback 補齊。 +- AI automation readiness 已可回報: + - `AI_AUTOMATION_CONTROLLED_APPLY_CLOSEOUT_VERIFIED` + - controlled apply lane completed + - receipt replay lane completed +- Drift verifier 已完成: + - production readback `4/4` + - `drift_count=0` + - drift lane completed +- Drift verifier artifact receipt 已完成: + - materialized artifact count `1` + - hash match count `1` +- AI debt scanner 顯示產品面清空: + - `PRODUCT_SURFACE_CLEAR` + - `finding_count=0` + - `primary_human_gate_count=0` + +進行中 / 下一步，必須照順序: + +1. 建立 automated drift-verifier monitor / smoke path，讓 verifier 不是只可手動呼叫，而是能被例行檢查。 +2. 建立 drift rollback / re-apply recommendation package，未來出現 drift 時可自動給出修復方案與回滾證據。 +3. 建立正式環境 compact readback endpoint，回傳最新 apply / replay / drift receipts。 +4. 建立 PChome controlled-apply artifacts retention policy，讓 evidence 可追蹤但不無限制膨脹。 + +完成標準: + +- Gitea `dev` / `main` 已 push。 +- runtime code change 已部署正式環境。 +- `/health` healthy 且 production version truth PASS。 +- 正式 DB readback 與 artifact hash readback 都有證據。 +- focused PChome automation 與 AI debt tests 通過。 + +## P1 - Product Visibility And Professional Website Experience + +狀態: 進行中。 + +目的: 讓 AI 自動化在產品裡可見，成為專業營運工作流，而不是只藏在後端。 + +已完成: + +- AI readiness 已聚合主要 automation lanes。 +- Controlled apply、receipt replay、drift verifier 已進 readiness。 +- 產品層 automation result 已輸出 zero primary human gates。 + +未開始 / 下一步，必須照順序: + +1. 把 PChome AI automation lanes 放進實際 product dashboard 第一視窗。 +2. 用繁體中文營運語言呈現 lane label、狀態與下一個機器動作。 +3. 正常產品畫面隱藏 raw endpoint、commit ID、DB table name、JSON payload。 +4. 增加專業的「今日 AI 自動化狀態」摘要: + - 已自動落地什麼 + - 已驗證什麼 + - drift 狀態 + - 下一個機器動作 +5. 增加 UI tests 或 route readback，避免產品頁退回 raw engineering wording。 + +完成標準: + +- 使用者不用讀 log / artifact，就能在第一畫面看到 AI 自動化狀態。 +- 頁面能回答「發生什麼、是否安全、下一步機器會做什麼」。 +- UI 是專業 dashboard pattern，不是裝飾卡片或空泛 marketing copy。 + +## P2 - External Benchmark And Mainstream Product Practice + +狀態: 未開始。 + +目的: 把外部主流專業產品網站 / SaaS / observability dashboard 的做法落到規則與測試。 + +必須採用的 benchmark 原則: + +- 狀態分層清楚: healthy、warning、blocked、completed。 +- 下一步優先: next machine action 必須比細節更早被看見。 +- Evidence-on-demand: receipts、hashes、raw payload 放詳細層，不壓在主畫面。 +- Manual review 是例外處理，不是 primary flow。 +- 產品面不顯示 raw stack traces、provider internals、database naming。 + +未開始 / 下一步，必須照順序: + +1. 對照目前 AI automation command center 與主流 observability / workflow dashboard pattern。 +2. 把 benchmark 結論轉成 UI guardrails 與 tests。 +3. 為 controlled apply、receipt replay、drift verifier 寫入正式產品文案。 + +完成標準: + +- benchmark-derived requirements 已被 tests 或 guardrails 固化。 +- desktop / mobile 都維持可操作、專業、可掃描。 + +## P3 - Broader AI Automation Expansion + +狀態: 未開始。 + +目的: 把目前 PChome retry mapping lane 的 controlled apply 閉環模式擴展到更多安全場景。 + +未開始 / 下一步，必須照順序: + +1. 對其他 safe mapping backlog lanes 套用 receipt / replay / drift verifier 模式。 +2. 增加 scheduled automation health summaries。 +3. 為每一類 controlled apply 自動產生 rollback evidence package。 +4. 把 AI automation metrics 整合進既有 observability surfaces。 + +完成標準: + +- 每個 automation family 都有 preflight、executor、receipt、replay、drift verifier、product readiness。 +- 每條 lane 都有 machine-verifiable evidence，且沒有隱藏人工-primary blocker。 + +## P4 - Source / Deployment Governance + +狀態: 持續進行。 + +目的: 保持 source control、部署、正式環境真相一致，避免版本與環境再次混亂。 + +持續規則: + +- Gitea 是 source-control truth。 +- GitHub 維持 freeze。 +- 不從未驗證分支部署。 +- 不意外 bump version。 +- 不 recreate / destroy / prune `momo-db`。 +- source-control success、deployment success、production runtime readback 必須分開回報。 + +完成標準: + +- 每次 push / deploy 都回報 Gitea head、production health、version truth、相關 readback。 + +## Current Work Queue + +| Priority | Work item | Status | Latest evidence | Next action | +|---|---|---|---|---| +| P0.1 | Controlled apply executor | 已完成 | `DIRECT_MAPPING_RETRY_EXCEPTION_CONTROLLED_APPLY_EXECUTED`, 4 DB rows | 納入 drift verifier 監控 | +| P0.2 | Executor receipt | 已完成 | executor receipt artifact generated | 進 compact summary | +| P0.3 | Receipt replay closeout | 已完成 | `DIRECT_MAPPING_RETRY_EXCEPTION_CONTROLLED_APPLY_RECEIPT_REPLAYED`, readback `4/4` | 作為 baseline | +| P0.4 | Product readiness visibility | 已完成 | `AI_AUTOMATION_CONTROLLED_APPLY_CLOSEOUT_VERIFIED` | 接到 UI first viewport | +| P0.5 | Drift verifier | 已完成 | `DRIFT_VERIFIED`, `drift_count=0`, readback `4/4` | 建立 monitor / smoke | +| P0.6 | Drift verifier artifact | 已完成 | drift artifact hash match `1` | 增加 latest compact readback | +| P0.7 | Automated drift monitor | 未開始 | none | 下一個實作 | +| P0.8 | Drift rollback / re-apply package | 未開始 | none | P0.7 後實作 | +| P1.1 | Dashboard AI automation first-viewport surface | 未開始 | API readiness exists | P0 monitor 後實作 | +| P1.2 | UI wording guard for no raw engineering terms | 未開始 | existing guardrails only | 為新 automation surface 補 tests | +| P2.1 | External benchmark encoded into requirements | 未開始 | benchmark guide exists | 更新 guardrails / tests | +| P3.1 | Extend receipt / replay / drift pattern to more lanes | 未開始 | current retry lane complete | P1 後選下一條 safe lane | + +## 後續回報格式 + +每次 continuation 必須回報: + +```text +current_priority: +- item: ... +- reason: ... + +implemented: +- ... + +verification: +- tests: ... +- gitea: ... +- production: ... +- artifacts: ... + +next_priority: +- ... +```