# AI Agent 工具採用批准包工作報告

> 日期：2026-06-11（台北時間）
> 狀態：P2-402C 已完成；P2-402D / P2-402E / P2-402F / P2-402G 已接續完成；整體 AI Agent 主動營運與版本生命週期完成度 100%。
> 邊界：本文件與對應 API 只提供批准包，不安裝工具、不改 CI、不查外部 registry、不下載漏洞 DB、不建立 PR、不 auto merge、不發 Telegram、不改 production route。

## 1. 本波完成項目

| 項目 | 狀態 | 產出 |
|---|---|---|
| 工具採用 schema | 完成 | `docs/schemas/ai_agent_tool_adoption_approval_package_v1.schema.json` |
| 工具採用 snapshot | 完成 | `docs/evaluations/ai_agent_tool_adoption_approval_package_2026-06-11.json` |
| API loader | 完成 | `apps/api/src/services/ai_agent_tool_adoption_approval_package.py` |
| 只讀 API | 完成 | `GET /api/v1/agents/agent-tool-adoption-approval-package` |
| 測試 | 完成 | loader / API / safety boundary / rollup mismatch / unknown source ref |
| 主契約同步 | 完成 | `ai_agent_proactive_operations_contract_v1` 完成度 100%，current `P2-402G`，next `P2-403A` |

## 2. 官方來源與工具角色

| 工具 | 官方來源 | 主責 Agent | 專業角色 | 採用前必過關卡 |
|---|---|---|---|---|
| Renovate for Gitea | <https://docs.renovatebot.com/modules/platform/gitea/> | Hermes | 依賴更新 PR 草案、grouping、automerge=false、reviewer policy | Gitea bot token、workflow、branch policy、PR storm rollback |
| OSV-Scanner | <https://google.github.io/osv-scanner/usage/> | OpenClaw | 依賴漏洞 advisory lookup 候選 | 外部查詢、cache TTL、false-positive、severity mapping |
| Trivy | <https://trivy.dev/> | OpenClaw | container / filesystem / IaC / SBOM / Kubernetes scanner 候選 | DB cache、runner cost、registry credential、image/build 邊界 |
| Syft | <https://anchore.com/opensource/> | Hermes | SBOM 產生候選 | SBOM schema、artifact retention、redaction、storage path |
| Grype | <https://anchore.com/opensource/> | OpenClaw | Syft SBOM / image vulnerability cross-check 候選 | vulnerability DB cache、suppression、duplicate handling、Telegram gate |

## 3. Agent 分工

| Agent | 本波可做 | 本波不可做 |
|---|---|---|
| Hermes | 彙整官方來源、工具欄位、Gitea PR lane 草案、SBOM artifact policy 草案 | 建立 bot token、寫 workflow、產 SBOM、建立 PR |
| OpenClaw | 仲裁 secret / CI / 費用 / false-positive / blast-radius，要求 HITL approval | 自行批准工具啟用、改 CI runner、改 Alertmanager / Telegram route、auto merge |
| NemoTron | 建立離線 replay 欄位，評估 scanner output 如何影響 AI Agent / prompt / tool-call 品質 | 新增 SDK、呼叫付費模型、開 shadow/canary、改 provider route |

## 4. 後續代辦與優先順序

| 優先 | ID | 工作 | 完成標準 | 目前狀態 |
|---:|---|---|---|---|
| 1 | P2-402D | Telegram action-required digest policy | 定義 critical / action-required / failure-only，禁止成功洗版，接 Telegram Gateway E2E gate | 完成 |
| 2 | P2-402E | Gitea PR 草案 lane | Renovate grouping、automerge=false、測試要求、rollback、owner response | 完成 |
| 3 | P2-402F | host OS / K3s / stateful services 版本只讀盤點 | 主機、K3s、PostgreSQL、Redis、MinIO、Harbor、Gitea 只讀版本矩陣 | 完成 |
| 4 | P2-402G | Governance UI 顯示可委派能力 | 前端顯示 autonomy level、gate、owner、Telegram policy，無執行按鈕 | 完成 |
| 5 | P2-403A | Runtime gate planning | 排程、工具、PR 草案、host probe 與 Telegram queue write 的逐項批准包 | 待辦 |
| 6 | 候選池 | SBOM artifact policy | Syft / Trivy artifact 格式、保存、redaction、消費者規則 | 未排正式編號 |
| 7 | 候選池 | Scanner false-positive policy | OSV / Trivy / Grype 差異、suppression、severity mapping、owner SLA | 未排正式編號 |
| 8 | 候選池 | Version history / RAG 回寫 | 每次版本觀測、批准、失敗、rollback 回寫 `version_history` / `upgrade_outcomes` | 未排正式編號 |

## 5. 現在仍維持 false 的邊界

- `tool_install_allowed=false`
- `ci_workflow_change_allowed=false`
- `external_registry_lookup_allowed=false`
- `vulnerability_database_download_allowed=false`
- `package_upgrade_allowed=false`
- `lockfile_write_allowed=false`
- `docker_build_allowed=false`
- `image_pull_allowed=false`
- `gitea_pr_creation_allowed=false`
- `auto_merge_allowed=false`
- `telegram_direct_send_allowed=false`
- `paid_service_enabled=false`
- `production_route_change_allowed=false`
- `secret_plaintext_allowed=false`

## 6. 進度同步方式

每推進一個正式 task，必須同步更新四個地方：

1. `docs/evaluations/ai_agent_proactive_operations_contract_2026-06-11.json` 的完成度、current task、next task。
2. `docs/ai/AI_AGENT_AUTOMATION_WORKLIST_2026-06-04.md` 的狀態、百分比、關卡。
3. `docs/superpowers/specs/2026-04-15-MASTER-ai-autonomous-flywheel-v2.md` 的 §3.2.1c 與 changelog。
4. `docs/LOGBOOK.md` 的正式工作紀錄、驗證結果與 deployment evidence。
