diff --git a/docs/AI_INTELLIGENCE_MODULE_SOT.md b/docs/AI_INTELLIGENCE_MODULE_SOT.md index 526d982..ce2e4b3 100644 --- a/docs/AI_INTELLIGENCE_MODULE_SOT.md +++ b/docs/AI_INTELLIGENCE_MODULE_SOT.md @@ -98,6 +98,7 @@ - 2026-07-02 起 P4 source / deployment governance 必須提供 machine-readable report：`scripts/ops/report_source_deploy_runtime_truth.py` 會分層輸出 Gitea / origin / local HEAD source truth、部署檔案 SHA256 readback、正式 `/health` runtime truth、optional container readback 與 GitHub freeze / `momo-db` protected / no DB write / no secret read 安全紅線。此 report 是推 Gitea 與正式部署後的 P4 收斂證據，不得把 source-control success 直接等同 deployment success 或 production runtime success。 - 2026-07-02 起 `/ai_intelligence` 與 `/observability/overview` 必須同樣套用 AI automation benchmark golden signals：首屏需有 `AI 自動化狀態` 區塊，直接顯示「已自動落地、已驗證、異動狀態、下一步」。`/ai_intelligence` 需以 `/api/ai/pchome-growth/ai-automation-surface-summary` 只讀更新首屏，該 endpoint 由 `/api/ai/pchome-growth/ai-automation-readiness` 聚合 safe lanes 後輸出 `golden_signals`、`safe_automation_lanes`、`surface_contract`、`primary_human_gate_count=0`、`writes_database_count=0` 與 `next_machine_action`；`/observability/overview` 需用正式觀測資料分層呈現風險與下一步。raw endpoint、artifact、DB table、manual/human gate 文字不得進首屏訊號。 - 2026-07-02 起 `/ai_automation_smoke` 也必須採密集 AI 巡檢工作台：首屏使用 `data-density-guardrail="compact-smoke-workbench"`，以「AI 巡檢、風險優先、推播摘要」短標籤保留狀態模式；重複說明、趨勢教學與診斷細節提示必須退到 hidden contract，畫面第一層只保留狀態、數字、趨勢、每日摘要與檢查項目 summary。 +- 2026-07-02 起 `/observability/agent_orchestration` 必須採密集 AI Agent 工作台：首屏使用 `data-density-guardrail="compact-agent-workbench"`，以「AI 分工、成本守門、知識命中」短標籤承接分工狀態；hero 說明、KPI 小註、列內描述、卡片描述與頁尾重複標題不得佔用第一層視覺，畫面先保留呼叫總量、主力路徑占比、付費成本、知識命中率、分工矩陣與工具協作表。 - 2026-07-02 起 `/ai_intelligence` 商品明細與單品作戰詳情的四格價格證據必須可測：PChome 價格、MOMO 參考價、差距、可信度需以 `data-evidence` 固定，並以 `aria-label="價格證據"` 對應可掃描區塊；候選待確認或缺資料只能顯示「候選待確認 / 待補」，不得捏造價格或讓使用者打開 raw payload 才知道判斷依據。 - 2026-07-02 起 `/ai_intelligence` 必須是密集 AI 工作台，不得退回大段文字說明頁：首屏與明細可見內容只保留短狀態、數字、四格證據與下一步按鈕；KPI note、benchmark detail、alert 副句、策略說明、decision copy、來源長句與單品 reason list 不得佔用第一層視覺。`tests/test_ai_intelligence_text_density_guardrails.py` 必須鎖住 `data-density-guardrail="compact-ai-workbench"`、短任務文案、detail meta 與 hidden explanatory copy。 - 2026-07-02 起 `/observability/overview` 也必須採密集 AI 觀測工作台：首屏以 `data-density-guardrail="compact-observability-workbench"`、`AI 觀測 / 風險優先 / 下一步` 與 golden signals 先呈現狀態、數字與操作入口；hero lede、signal note、route desc、host meta 與資料來源長句不得佔用第一層視覺。`tests/test_observability_text_density_guardrails.py` 必須鎖住 compact marker 與 hidden explanatory copy。 diff --git a/docs/guides/external_professional_benchmark.md b/docs/guides/external_professional_benchmark.md index c0ec74b..8f4d399 100644 --- a/docs/guides/external_professional_benchmark.md +++ b/docs/guides/external_professional_benchmark.md @@ -72,6 +72,7 @@ Baymard 的商品頁與比較 UX 研究強調：使用者需要清楚的 product - Golden signals: AI automation 第一視窗至少要有四個核心訊號：已自動落地、已驗證、異動狀態、下一步。 - Dashboard-as-code: benchmark 結論必須進 tests；`tests/test_pchome_dashboard_benchmark_guardrails.py` 是 PChome AI dashboard benchmark guard。 - Surface rollout: `/ai_intelligence` 與 `/observability/overview` 已套用相同 golden-signal guardrails；`tests/test_ai_surface_benchmark_guardrails.py` 鎖住兩頁首屏的狀態分層、下一步優先與 evidence-on-demand 語言。 +- AI Agent surface rollout: `/observability/agent_orchestration` 已套用 compact Agent workbench guardrails；`tests/test_agent_orchestration_text_density_guardrails.py` 鎖住首屏短標籤、核心訊號與 hidden explanatory copy。 ## 下一步 TODO 候選 @@ -82,6 +83,7 @@ Baymard 的商品頁與比較 UX 研究強調：使用者需要清楚的 product 5. 將 PChome AI automation benchmark guardrails 套到後續 AI Agent surfaces 與每條 safe automation lane 的 first-viewport summary。 - 已完成: `/api/ai/pchome-growth/ai-automation-surface-summary` 以 `golden_signals` 固化「已自動落地、已驗證、異動狀態、下一步」。 - 已完成: `/ai_intelligence` 首屏直接消費 surface summary，raw receipt / hash / DB table / endpoint 細節留在 evidence-on-demand 層。 + - 已完成: `/observability/agent_orchestration` 首屏以「AI 分工 / 成本守門 / 知識命中」短標籤與四個核心數字呈現 Agent 編排狀態。 ## 參考來源 diff --git a/docs/guides/pchome_ai_automation_priority_backlog.md b/docs/guides/pchome_ai_automation_priority_backlog.md index 97291d8..6b9793e 100644 --- a/docs/guides/pchome_ai_automation_priority_backlog.md +++ b/docs/guides/pchome_ai_automation_priority_backlog.md @@ -101,7 +101,7 @@ ## P1 - Product Visibility And Professional Website Experience -狀態: 進行中，本輪已完成 `/ai_intelligence`、`/observability/overview` 與 `/ai_automation_smoke` 密集 AI 工作台文字密度守門。 +狀態: 進行中，本輪已完成 `/ai_intelligence`、`/observability/overview`、`/ai_automation_smoke` 與 `/observability/agent_orchestration` 密集 AI 工作台文字密度守門。 目的: 讓 AI 自動化在產品裡可見，成為專業營運工作流，而不是只藏在後端。 @@ -132,6 +132,10 @@ - 首屏改成 `data-density-guardrail="compact-smoke-workbench"`，以「AI 巡檢 / 風險優先 / 推播摘要」短標籤承接 AI 健康檢查。 - hero lede、趨勢說明、每日摘要說明與診斷細節提示從可見 UI 退場，保留狀態、數字、趨勢、每日摘要與檢查項目 summary。 - `tests/test_ai_automation_smoke_text_density_guardrails.py` 已鎖住 compact marker、第一層狀態數字與 explanatory copy hidden contract。 +- `/observability/agent_orchestration` 密集 AI Agent 工作台文字密度 guard 已完成: + - 首屏改成 `data-density-guardrail="compact-agent-workbench"`，以「AI 分工 / 成本守門 / 知識命中」短標籤承接 Agent 編排狀態。 + - hero 說明、KPI 小註、列內描述、卡片描述與頁尾重複標題從可見 UI 退場，保留呼叫總量、主力路徑、付費成本、知識命中、分工矩陣與工具協作表。 + - `tests/test_agent_orchestration_text_density_guardrails.py` 已鎖住 compact marker、第一層狀態數字與 explanatory copy hidden contract。 已完成 / 下一步，必須照順序: @@ -254,6 +258,7 @@ | P1.4 | AI intelligence compact workbench text-density guardrails | 已完成 | `/ai_intelligence` first viewport and drilldown hide explanatory copy; focused density guard test | P2.2 benchmark guardrails and future AI surfaces | | P1.5 | Observability compact workbench text-density guardrails | 已完成 | `/observability/overview` first viewport hides explanatory copy; focused density guard test | Apply density guard to remaining high-visibility AI surfaces | | P1.6 | AI automation smoke compact workbench text-density guardrails | 已完成 | `/ai_automation_smoke` first viewport hides explanatory copy; focused density guard test | Apply density guard to remaining high-visibility AI surfaces | +| P1.7 | Agent orchestration compact workbench text-density guardrails | 已完成 | `/observability/agent_orchestration` first viewport hides explanatory copy; focused density guard test | Apply density guard to remaining high-visibility AI surfaces | | P2.1 | External benchmark encoded into requirements | 已完成 | benchmark guide + focused guard test + first-viewport status | P3.1 safe lane expansion | | P3.1 | Extend receipt / replay / drift pattern to more lanes | 已完成 | direct mapping candidate decision lane closeout route + focused tests | P3.2 scheduled automation health summaries | | P3.2 | Scheduled automation health summaries | 已完成 | `/api/ai-automation/scheduled-health-summary` + smoke service focused tests | P3.3 rollback evidence packages | diff --git a/templates/admin/agent_orchestration.html b/templates/admin/agent_orchestration.html index af7cbe5..3492c99 100644 --- a/templates/admin/agent_orchestration.html +++ b/templates/admin/agent_orchestration.html @@ -5,26 +5,26 @@ {% block ewooo_content %} {% import "admin/_observability_labels.html" as obs_label %}
-
AI 分工指揮台 · {{ hours }} 小時視窗

AI 分工指揮台

確認 AI 分工、建議路徑、知識命中與工具編排是否支撐業績決策。

{% if overall %}
呼叫總量
{{ "{:,}".format(overall.total_calls) }}{{ "{:,}".format(overall.total_tokens) }} 用量
主力路徑占比
{{ "%.0f"|format(overall.local_pct) }}%{{ "{:,}".format(overall.local_calls) }} 次主力呼叫
付費成本
${{ "%.2f"|format(overall.total_cost) }}{{ "{:,}".format(overall.paid_calls) }} 次付費呼叫
知識命中率
{{ "%.0f"|format(overall.rag_rate) }}%{{ "{:,}".format(overall.rag_hits) }} 次命中
{% endif %}
+
AI 分工指揮台 · {{ hours }} 小時視窗

AI 分工指揮台

AI 分工成本守門知識命中

確認 AI 分工、建議路徑、知識命中與工具編排是否支撐業績決策。

{% if overall %}
呼叫總量
{{ "{:,}".format(overall.total_calls) }}{{ "{:,}".format(overall.total_tokens) }} 用量
主力路徑占比
{{ "%.0f"|format(overall.local_pct) }}%{{ "{:,}".format(overall.local_calls) }} 次主力呼叫
付費成本
${{ "%.2f"|format(overall.total_cost) }}{{ "{:,}".format(overall.paid_calls) }} 次付費呼叫
知識命中率
{{ "%.0f"|format(overall.rag_rate) }}%{{ "{:,}".format(overall.rag_hits) }} 次命中
{% endif %}
{% if error %}
{{ error }}
{% endif %}
-
AI 分工矩陣

建議路徑、工具與知識命中矩陣

{% for ag in agent_matrix %}{% endfor %}
分工呼叫成本主力路徑付費工具知識錯誤耗時
{{ ag.label }}{{ ag.desc }}{% if ag.calls > 0 %}{{ "{:,}".format(ag.calls) }}{{ "{:,}".format(ag.tokens) }} 用量{% else %}—{% endif %}{% if ag.calls > 0 %}${{ "%.2f"|format(ag.cost) }}{% else %}—{% endif %}{% if ag.calls > 0 %}{{ "%.0f"|format(ag.ollama_pct) }}%主力 {{ ag.ollama_gcp_a }} · 備援 {{ ag.ollama_gcp_b }} · 第三 {{ ag.ollama_111 }}{% else %}—{% endif %}{% if ag.calls > 0 %}{{ "%.0f"|format(ag.paid_pct) }}%雲端備援 {{ ag.gemini }}{% if ag.other_paid %} · 其他 {{ ag.other_paid }}{% endif %}{% else %}—{% endif %}{% if ag.calls > 0 %}{{ "%.1f"|format(ag.mcp_rate) }}%{{ ag.mcp_calls }}{% else %}—{% endif %}{% if ag.calls > 0 %}{{ "%.1f"|format(ag.rag_rate) }}%{{ ag.rag_hits }}{% else %}—{% endif %}{% if ag.calls > 0 %}{{ "%.1f"|format(ag.error_rate) }}%{{ ag.errors }}{% else %}—{% endif %}{% if ag.calls > 0 %}{{ ag.avg_ms }} ms{% else %}—{% endif %}
+
AI 分工矩陣

建議路徑、工具與知識命中矩陣

{% for ag in agent_matrix %}{% endfor %}
分工呼叫成本主力路徑付費工具知識錯誤耗時
{{ ag.label }}{{ ag.desc }}{% if ag.calls > 0 %}{{ "{:,}".format(ag.calls) }}{{ "{:,}".format(ag.tokens) }} 用量{% else %}—{% endif %}{% if ag.calls > 0 %}${{ "%.2f"|format(ag.cost) }}{% else %}—{% endif %}{% if ag.calls > 0 %}{{ "%.0f"|format(ag.ollama_pct) }}%主力 {{ ag.ollama_gcp_a }} · 備援 {{ ag.ollama_gcp_b }} · 第三 {{ ag.ollama_111 }}{% else %}—{% endif %}{% if ag.calls > 0 %}{{ "%.0f"|format(ag.paid_pct) }}%雲端備援 {{ ag.gemini }}{% if ag.other_paid %} · 其他 {{ ag.other_paid }}{% endif %}{% else %}—{% endif %}{% if ag.calls > 0 %}{{ "%.1f"|format(ag.mcp_rate) }}%{{ ag.mcp_calls }}{% else %}—{% endif %}{% if ag.calls > 0 %}{{ "%.1f"|format(ag.rag_rate) }}%{{ ag.rag_hits }}{% else %}—{% endif %}{% if ag.calls > 0 %}{{ "%.1f"|format(ag.error_rate) }}%{{ ag.errors }}{% else %}—{% endif %}{% if ag.calls > 0 %}{{ ag.avg_ms }} ms{% else %}—{% endif %}
{% if recommendations %}
策略規則

編排策略自動建議

{% for r in recommendations %}
{{ r.severity|upper }}{{ r.agent }}
發現：{{ r.finding }}
建議：{{ r.suggestion }}
{% endfor %}
{% endif %} {% if mcp_matrix %}
工具協作明細

工具協作 × 使用情境

{% for m in mcp_matrix %}{% endfor %}
工具服務使用情境工具協作快取快取率成本
服務元件{{ obs_label.caller(m.caller) }}{{ "{:,}".format(m.calls) }}{{ m.cache_hits }}{{ "%.0f"|format(m.cache_rate) }}%${{ "%.4f"|format(m.cost) }}
{% endif %} -

AI 分工指揮台

+

AI 分工指揮台

{% endblock %} diff --git a/tests/test_agent_orchestration_text_density_guardrails.py b/tests/test_agent_orchestration_text_density_guardrails.py new file mode 100644 index 0000000..82e5b70 --- /dev/null +++ b/tests/test_agent_orchestration_text_density_guardrails.py @@ -0,0 +1,38 @@ +from pathlib import Path + + +ROOT = Path(__file__).resolve().parents[1] + + +def test_agent_orchestration_uses_compact_agent_workbench_contract(): + template = (ROOT / "templates/admin/agent_orchestration.html").read_text(encoding="utf-8") + + assert 'data-density-guardrail="compact-agent-workbench"' in template + assert 'aria-label="AI 分工狀態模式"' in template + assert "AI 分工" in template + assert "成本守門" in template + assert "知識命中" in template + + +def test_agent_orchestration_keeps_first_layer_metrics_without_explanatory_copy(): + template = (ROOT / "templates/admin/agent_orchestration.html").read_text(encoding="utf-8") + + for marker in ["呼叫總量", "主力路徑占比", "付費成本", "知識命中率"]: + assert marker in template + + assert ".agent-subtitle,.agent-signal-note,.agent-row-desc,.agent-card-desc,.agent-footer-copy{display:none}" in template + assert 'class="agent-subtitle"' in template + assert 'class="text-muted agent-signal-note"' in template + assert 'class="d-block text-muted agent-row-desc"' in template + assert 'class="d-block text-muted agent-card-desc"' in template + assert 'agent-footer-copy' in template + + +def test_agent_orchestration_preserves_workbench_tables_and_non_raw_wording(): + template = (ROOT / "templates/admin/agent_orchestration.html").read_text(encoding="utf-8") + + for marker in ["建議路徑、工具與知識命中矩陣", "工具協作明細", "工具協作 × 使用情境"]: + assert marker in template + + for forbidden in ["Agent 指揮矩陣", "四 Agent 矩陣", "LLM × MCP × RAG 編排矩陣", "權杖"]: + assert forbidden not in template