與 Kiro 一起實作：將 AI 工廠自動化輔助程式新增至工廠自動化入口網站

僅供教育用途的工程工作坊。本內容為軟體架構演練，並非流程發布建議。

摘要： 本獨立工作坊旨在教導開發人員如何使用 AWS AI 服務與 Kiro 來擴充最新的工廠自動化入口網站 (Factory Automation Portal) 範例。開發人員將建構一個工廠自動化輔助程式，該程式能擷取入口網站的快照，並解釋執行期 (Runtime)、工具 (Tools)、受控工作流 (Governed Workflows)、製程視窗 (Process Windows)、執行手冊 (Runbook) 區段、製程視窗指標、SVG 圖表語意、政策邊界、遙測事件格式以及實作閘門。該輔助程式利用 Amazon Bedrock 產生證據優先的工程評論、檢索已核准的詞彙表知識、驗證結構化 JSON 回應、儲存稽核紀錄，並使用 Kiro 規格 (Specs)、引導 (Steering)、勾點 (Hooks)、測試和護欄 (Guardrails)，以可稽核的工作流來交付專業的 AI 應用程式。

---

工作坊目的

這個為期 2 小時的工作坊重點在於圍繞工廠自動化入口網站建立一個 AWS AI 服務層。HTML 範例是一個前端工作區，而本工作坊則將入口網站的數據、UI 標籤和術語轉化為一個 AI 輔助的開發人員專案：一個後端服務，利用 Amazon Bedrock、檢索接地 (Retrieval Grounding)、Kiro 規格和嚴格的工程分析護欄，來解釋入口網站區段、執行期模式、工具、受控工作流邊界、製程視窗資料列、指標定義、執行手冊閘門、視覺圖表語意以及自動化邊界控制。

本工作坊沿用了原始 AWS AI 交易員輔助程式工作坊的架構，但將其中的每項功能、安全規則、資料模型、詞彙表項目、提示詞、評估案例和視覺分析實驗室，全部更新為最新的工廠自動化入口網站內容。該輔助程式支援架構審查、測試規劃和開發人員培訓。它不提供自主設備操作指令、製程發布決策、繞過指引或隱藏控制的因應措施。

---

範例涵蓋地圖

本工作坊透過 AI 功能涵蓋了以下範例概念：

● 工作區身分： FACTORY AUTOMATION PORTAL、RUNTIME / TOOLS / POLICY / MEMORY / OBSERVABILITY / EVALUATIONS。

● 文件詮釋資料： Amazon Bedrock、Runtime、Tooling、AWS Lambda、IAM、SigV4、Amazon SageMaker、Amazon Timestream、AWS Glue、AWS Lake Formation、AWS DataZone、OpenTelemetry、Apache Iceberg、Etch Process Window Automation。

● 主體情境： 自動化入口網站、工廠工程、蝕刻製程視窗測試自動化、工具庫存、受控微影 drift 編排、執行期佈署、工具發現、決定性計算、政策閘門、記憶摘要、遙測、評估、企業採用模式。

● 入口網站任務： 企業自動化主控台、佈署狀態、工具庫存、受控工作流控制、評估準備就緒度、原始製程視窗排行榜遙測、稽核友善介面。

● 邊界標籤 (Chips)： NO EQUIPMENT COMMANDS (無設備指令)、EVIDENCE FIRST (證據優先)、BOUNDED MEMORY (受限記憶)、HUMAN REVIEW (人工審查)。

● 摘要統計： 執行期進入點 3、工具 4、專家 4、政策檢查 2、評估集 5、階段狀態 ON。

● 總覽面板： 執行期工作台 (Runtime Workbench)、工具庫存 (Tool Inventory)、受控工作流 (Governed Workflow)、架構分層、採用筆記。

● 執行期面板： 同步執行期、串流執行期、大負載執行期、負載驗證、冒煙測試、階段清理、執行期負載合約、決定性工具模式。

● 工具面板： 工具庫存、四種工具、工具流程、針對 process_window_drift 的 JSON-RPC 除錯負載、語意搜尋、Lambda 目標、SigV4 傳輸。

● 受控工作流面板： 產出量、量測、對準 (Overlay)、蝕刻製程專家、政策邊界、遙測事件格式。

● 製程視窗面板： 八個自動化單元、四個狀態圖磚、表格欄位、搜尋、排序、可展開的分析、製程視窗索引路徑、自動化指標、漂移水位線 (Drift Waterline)、每日製程 Delta 分布、自動化筆記。

● 執行手冊面板： 2 小時建置路徑、晉升閘門 (Promotion Gate)、生產待辦清單 (Production Backlog)。

● 安全行為： 無自主設備操作、無製程發布建議、無審批繞過、僅限範例情境、僅限工程分析。

● 可稽核性： 儲存產生的評論、來源資料快照雜湊值、請求 ID、追蹤 ID、政策決策、模型 ID、提示詞版本和回應 JSON。

---

目標開發人員

● 正在建立工程輔助程式的 AI 應用程式開發人員。

● 將 Amazon Bedrock 整合到內部開發人員工具中的後端開發人員。

● 利用解釋 API 來擴充入口網站的全端開發人員。

● 學習 Kiro 規格、引導、勾點和護欄的平台開發人員。

● 建構執行期、工具、AI 輔助、政策、記憶、觀測能力和評估模式的開發人員。

---

兩小時議程

---

系統架構

React 工廠自動化入口網站
  │ 點擊 "AI Explain" (AI 解釋)
  ▼
API Gateway
  ▼
Lambda explain-handler
  ├─ 使用 Pydantic 驗證請求
  ├─ 載入範例入口網站快照
  ├─ 載入已核准的詞彙表與視覺詞彙表
  ├─ 選擇目標情境：區段、執行期、工具、治理、自動化單元、指標、視覺、執行手冊
  ├─ 建置證據優先的 Bedrock 提示詞
  ├─ 呼叫 Amazon Bedrock Converse API
  ├─ 驗證 JSON 回應合約
  ├─ 寫入 DynamoDB 稽核紀錄
  └─ 將解釋結果返回給 UI

---

AI 輔助程式功能

---

入口網站術語與輔助程式解釋用法

---

步驟 1 — 建立專案

mkdir kiro-aws-factory-ai-assistant && cd kiro-aws-factory-ai-assistant
python -m venv .venv
source .venv/bin/activate
pip install boto3 pydantic pytest
mkdir -p .kiro/steering .kiro/specs/portal-assistant .kiro/hooks src data knowledge tests eval docs

業務邏輯： 該輔助程式向開發人員和平台團隊解釋入口網站。它應該能提高理解度，而不是產生設備操作指令。

程式碼邏輯： 使用 Python 作為無伺服器後端。Data 與 knowledge 資料夾存放已核准的情境，供提示詞使用。

預期結果： 一個準備好進行 Kiro 輔助 AI 後端設計的存放庫。

系統設計原由：

● AI 層與前端分離，因此可以獨立測試、保護、記錄和稽核解釋的產生。

● 選擇 Python 是因為它對於 Lambda 處理常式和資料驗證非常簡潔。

● 資料和知識採本機優先，允許開發人員在佈署 AWS 資源之前測試接地 (Grounding)。

---

步驟 2 — 新增 Kiro 引導 (Steering)

建立 .kiro/steering/ai-safety.md：

# AI 安全引導
本輔助程式僅能解釋範例工廠自動化入口網站資料。
絕對不要提供自主設備操作指令、設備狀態變更、繞過說明、製程發布決策、保證產能提升的宣稱、隱藏控制的因應措施，或隱藏報廢訊號的指令。
務必加上說明：指標僅為範例預留位置，用於工程分析、架構審查和測試自動化規劃。
如果被要求執行、批准、繞過或操作設備，請予以拒絕，並改為提供架構、測試規劃或指標解釋的協助。

建立 .kiro/steering/bedrock-contract.md：

# Bedrock 回應合約
回應必須是包含以下鍵 (Keys) 的有效 JSON：
- summary
- architecture_context
- metric_interpretation
- evidence
- confirmation_signals
- invalidation_triggers
- limitations
- safety_note
請對資深開發人員使用簡潔、專業的語言。
不要虛構請求或核准知識情境中未提供的資料。
不要從範例圖表、顏色或狀態圖磚中推斷實際的設備狀態。

建立 .kiro/steering/aws-architecture.md：

# AWS 架構引導
使用 API Gateway、Lambda、Amazon Bedrock Runtime、DynamoDB 和 CloudWatch 日誌。
對 MODEL_ID、TABLE_NAME、SNAPSHOT_PATH、GLOSSARY_PATH 和 PROMPT_VERSION 使用環境變數。
在呼叫 Bedrock 之前，先使用 Pydantic 驗證所有請求。
在 DynamoDB 中儲存 request_id、trace_id、target_type、target_id、portal_tab、metrics、source_snapshot_hash、policy_decision、model_id、prompt_version 和 model_response。
在單元測試中模擬 (Mock) AWS 用戶端。

Kiro 提示詞範例

建立一個適用於工廠自動化入口網站的 AWS AI 驅動工廠自動化輔助程式規格。它必須利用 Amazon Bedrock 來解釋範例入口網站區段、執行期模式、工具、受控工作流邊界、政策邊界、遙測事件格式、製程視窗資料列、視覺圖表、執行手冊閘門、生產待辦清單和指標定義。內容須包含安全拒絕行為、JSON 回應合約、Lambda 設計、DynamoDB 稽核儲存、測試、視覺解釋支援以及生產硬化任務。

業務邏輯： 引導定義了輔助程式允許執行的操作以及回應必須如何結構化。

程式碼邏輯： Kiro 使用引導文件來產生結構綱要、提示詞、處理常式和測試，以維護 AI 安全邊界。

預期結果： Kiro 建立了一個包含需求、設計、資料合約、失敗模式和實作任務的規格。

系統設計原由：

● 安全引導與 AWS 架構分離，因為 AI 行為和雲端權限有不同的審查擁有者。

● JSON 回應合約使前端能夠在不同的 UI 區段中渲染摘要、架構情境、限制、證據、確認訊號、失效觸發條件和警告。

● 在 Bedrock 之前進行資料驗證可降低成本，並防止格式錯誤的輸入原封不動地傳遞給模型。

---

步驟 3 — 建立已核准的知識文件

建立 knowledge/portal-glossary.md：

# 工廠自動化入口網站詞彙表
runtime (執行期) 託管用於同步、串流和大負載工作流的 AI 代理進入點。
AWS tool gateway (工具閘道) 公開具有授權、語意發現和 Lambda 支援目標的受管工具。
tools (工具) 使用描述工具名稱、輸入、證據和預期行為的結構綱要。
AI assistance (AI 輔助) 將模型推理與決定性工具相結合。
Runtime Payload Contract (負載合約) 包含必要的 prompt 以及選填的 request_id、user_id、excel_data、image_data 和 metadata 欄位。
決定性工具是用於計算和證據支援的可重複、程式碼支援的協助工具。
Process Window Index (製程視窗索引) 是一個索引範例序列，用於解釋製程視窗的變動。
Daily Delta (每日變動) 是相鄰索引點之間的變動。
Stability (穩定度) 是用於資料列比較的範例品質評分。
Process Factor (製程因子) 是僅在入口網站內部使用的範例品質指標。
Window Rate (視窗率) 衡量正向每日變動的百分比。
Max Drift (最大漂移) 衡量範例中從執行峰值開始的最大下滑幅度。
政策閘門會封鎖未受支援的請求並驗證回應需求。
受限記憶儲存安全的工作流摘要，而非原始對話紀錄。
觀測能力事件使用請求 ID 和屬性來實現可追蹤性。
評估固定裝置用於測試允許和封鎖的流程。
執行手冊閘門定義了驗證、佈署、呼叫、治理、評估、清理和交接檢查點。

建立 data/snapshot.json：

{
  "workspace": "Factory Automation Portal",
  "brand_subtitle": "RUNTIME / TOOLS / POLICY / MEMORY / OBSERVABILITY / EVALUATIONS",
  "hero": {
    "eyebrow": "Automation Portal",
    "title": "Factory Engineering",
    "chips": ["RUNTIME", "TOOLING", "AI ASSISTANCE", "tooling", "SIGV4", "JSON-RPC", "AWS LAMBDA", "AMAZON BEDROCK"],
    "boundary_chips": ["NO EQUIPMENT COMMANDS", "EVIDENCE FIRST", "BOUNDED MEMORY", "HUMAN REVIEW"]
  },
  "status": {
    "runtime_entrypoints": 3,
    "gateway_tools": 4,
    "specialists": 4,
    "policy_checks": 2,
    "evaluation_sets": 5,
    "session_state": "ON"
  },
  "tabs": ["overview", "runtime", "gateway", "governed", "leaderboard", "runbook"],
  "runtime_cards": [
    { "title": "Synchronous Runtime", "tags": ["app.py", "FactoryAutomationApp", "boto3 invoke"] },
    { "title": "Streaming Runtime", "tags": ["app_streaming.py", "async", "partial output"] },
    { "title": "Large Payload Runtime", "tags": ["xlsx", "png", "base64"] },
    { "title": "Payload Validation", "tags": ["JSON Schema", "fail fast", "client contract"] },
    { "title": "Smoke Tests", "tags": ["pytest", "deterministic", "local"] },
    { "title": "Session Cleanup", "tags": ["session ID", "cleanup", "operations"] }
  ],
  "gateway_tools": [
    { "name": "throughput_throughput", "signals": ["queue depth", "tool availability", "wafer throughput", "hot-lot preference"] },
    { "name": "metrology_drift_widening", "signals": ["inline drift", "lot drift", "CD-SEM index", "yield-loss watch"] },
    { "name": "process_window_drift", "signals": ["overlay error", "process capability", "recipe divergence", "lot flow"] },
    { "name": "tool_to_tool_mismatch", "signals": ["overlay mismatch", "baseline offsets", "control context", "tool matching"] }
  ],
  "specialists": ["throughput", "metrology", "overlay", "etch-process"],
  "status_tiles": [
    { "key": "RUNTIME", "move": "+0.38%", "state": "READY" },
    { "key": "GATEWAY", "move": "-0.22%", "state": "WATCH" },
    { "key": "POLICY", "move": "+0.62%", "state": "READY" },
    { "key": "EVAL", "move": "+2.18%", "state": "READY" }
  ],
  "automation_cells": [
    { "name": "Sofia Garcia", "strategy": "Etch Endpoint Depth Multi-Step Recipe Control", "index_pct": 18.4, "delta_pct": 0.42, "stability": 0.73, "process_factor": 1.8, "window_rate_pct": 58, "max_drift_pct": 18, "skew": 0.44 },
    { "name": "Lucia Fernandez", "strategy": "Photolithography Overlay Drift Detection", "index_pct": 16.9, "delta_pct": 0.88, "stability": 0.91, "process_factor": 1.7, "window_rate_pct": 61, "max_drift_pct": 22, "skew": 0.31 },
    { "name": "Carmen Lopez", "strategy": "Chamber Matching RF Power Pressure Stability", "index_pct": 14.2, "delta_pct": -0.31, "stability": 0.68, "process_factor": 1.6, "window_rate_pct": 56, "max_drift_pct": 25, "skew": 0.22 },
    { "name": "Elena Martin", "strategy": "Factory Line Yield Trend Automation", "index_pct": 11.8, "delta_pct": 0.17, "stability": 0.62, "process_factor": 1.5, "window_rate_pct": 54, "max_drift_pct": 17, "skew": 0.18 },
    { "name": "Marta Sanchez", "strategy": "Recipe Parameter Relative Stability", "index_pct": 9.6, "delta_pct": 0.09, "stability": 0.57, "process_factor": 1.4, "window_rate_pct": 53, "max_drift_pct": 15, "skew": 0.09 },
    { "name": "Paula Romero", "strategy": "Metrology Feature Ensemble Scoring", "index_pct": 7.1, "delta_pct": -0.12, "stability": 0.49, "process_factor": 1.3, "window_rate_pct": 52, "max_drift_pct": 14, "skew": -0.04 },
    { "name": "Ana Torres", "strategy": "Endpoint Signal Breakout Alarm System", "index_pct": 5.4, "delta_pct": 0.28, "stability": 0.42, "process_factor": 1.2, "window_rate_pct": 51, "max_drift_pct": 19, "skew": 0.12 },
    { "name": "Laura Navarro", "strategy": "Multi-Tool Mean Reversion Control", "index_pct": 3.8, "delta_pct": -0.06, "stability": 0.35, "process_factor": 1.1, "window_rate_pct": 49, "max_drift_pct": 16, "skew": -0.11 }
  ],
  "footer_boundary": "範例資料與圖表均為架構審查、測試自動化以及企業採用規劃的預留位置。未實作任何自主設備操作。"
}

業務邏輯： 已核准的知識與快照資料能將模型限制在已知的範例事實中。

程式碼邏輯： Markdown 提供詞彙表脈絡。JSON 提供可用於提示詞和測試的結構化入口網站狀態。

預期結果： 輔助程式可以解釋術語、入口網站區段、工具、專家、狀態圖磚和自動化資料列，而不會虛構未受支援的資料。

系統設計原由：

● 快照故意將資料與產生的評論分離。這支援了可稽核性與可重複的測試。

● 詞彙表是人類可讀的，因此審查人員無需閱讀程式碼即可核准定義。

● 當 AI 輔助程式需要圖表特定解釋時，可以擴充範例 JSON 以包含完整的序列。

---

步驟 4 — 定義請求與回應結構綱要

建立 src/contracts.py：

from pydantic import BaseModel, Field
from typing import Literal

class ExplainRequest(BaseModel):
    request_id: str = Field(min_length=8, max_length=80)
    trace_id: str | None = Field(default=None, max_length=120)
    target_type: Literal[
        "portal", "section", "automation_cell", "metric", "tool",
        "runtime", "governance", "status_tile", "runbook", "visual"
    ]
    target_id: str = Field(min_length=1, max_length=120)
    portal_tab: str | None = Field(default=None, max_length=60)
    question: str | None = Field(default=None, max_length=700)

class ExplainResponse(BaseModel):
    summary: str
    architecture_context: list[str]
    metric_interpretation: list[str]
    evidence: list[str]
    confirmation_signals: list[str]
    invalidation_triggers: list[str]
    limitations: list[str]
    safety_note: str

業務邏輯： API 支援多個解釋目標，同時保持輸出的可預測性。

程式碼邏輯： Pydantic 驗證請求外形和模型輸出。字面值 (Literal) 目標類型可防止任意不受支援的模式。

預期結果： 無效的請求在到達 Bedrock 呼叫之前就會失敗。

系統設計原由：

● 共享的回應結構綱要讓 UI 能夠在一致的面板中渲染任何解釋。

● 目標類型和目標 ID 將 API 與 UI 元件解耦。

● 限制問題長度以限制提示詞大小和阻絕注入風險。

---

步驟 5 — 建置 Bedrock 提示詞

建立 src/prompting.py：

import json

def build_explain_prompt(request, snapshot: dict, glossary_text: str) -> str:
    return f"""
您是面向高階開發人員的工廠自動化入口網站解釋輔助程式。
請僅使用提供的範例快照、核准的詞彙表、選定的入口網站區段詮釋資料、選定的資料列指標、選定的圖表詮釋資料以及核准的視覺詞彙表（若有提供）。
切勿提供自主設備操作指令、設備狀態變更、製程發布核准、繞過說明、保證產能提升的宣稱、隱藏控制的因應措施或隱藏報廢訊號的指令。
不要將範例顏色、走勢圖、狀態圖磚或圖表變動轉化為營運結論。
如果使用者要求未受支援的操作，請予以拒絕，並改為解釋相關的架構、指標定義、執行手冊閘門或測試模式。
僅返回有效的 JSON，且必須包含以下鍵：summary、architecture_context、metric_interpretation、evidence、confirmation_signals、invalidation_triggers、limitations、safety_note。
REQUEST:
{request.model_dump_json()}
SNAPSHOT:
{json.dumps(snapshot)}
APPROVED_GLOSSARY:
{glossary_text}
""".strip()

業務邏輯： 提示詞將資料轉化為解釋，同時將輔助程式限制在工程分析邊界內。

程式碼邏輯： 請求、快照和詞彙表作為明確的情境注入。模型被指示僅返回已知的 JSON 結構綱要。

預期結果： Bedrock 返回可驗證和渲染的結構化評論。

系統設計原由：

● 提示詞將提供的上下文作為唯一的真理來源，減少了憑空捏造營運宣稱的現象。

● 包含拒絕指令是因為同一個 UI 可能會接收到詢問未受支援操作的使用者問題。

● JSON 輸出支援決定性解析，並允許測試檢查必要的鍵。

---

步驟 6 — 實作 Lambda 處理常式

建立 src/handler.py：

import hashlib
import json
import os
import boto3
from pydantic import ValidationError
from src.contracts import ExplainRequest, ExplainResponse
from src.prompting import build_explain_prompt

bedrock = boto3.client("bedrock-runtime")
dynamodb = boto3.resource("dynamodb")

def load_text(path: str) -> str:
    with open(path, "r", encoding="utf-8") as file:
        return file.read()

def load_json(path: str) -> dict:
    with open(path, "r", encoding="utf-8") as file:
        return json.load(file)

def stable_hash(value: dict) -> str:
    payload = json.dumps(value, sort_keys=True).encode("utf-8")
    return hashlib.sha256(payload).hexdigest()

def call_bedrock(prompt: str) -> str:
    result = bedrock.converse(
        modelId=os.environ["MODEL_ID"],
        messages=[{"role": "user", "content": [{"text": prompt}]}],
        inferenceConfig={"temperature": 0.1, "maxTokens": 1200},
    )
    return result["output"]["message"]["content"][0]["text"]

def lambda_handler(event, context):
    try:
        body = json.loads(event.get("body") or "{}")
        request = ExplainRequest(**body)
    except (json.JSONDecodeError, ValidationError) as exc:
        return {"statusCode": 400, "body": json.dumps({"error": "Invalid request", "details": str(exc)})}

    snapshot = load_json(os.environ.get("SNAPSHOT_PATH", "data/snapshot.json"))
    glossary = load_text(os.environ.get("GLOSSARY_PATH", "knowledge/portal-glossary.md"))
    prompt = build_explain_prompt(request, snapshot, glossary)
    raw = call_bedrock(prompt)
    response = ExplainResponse(**json.loads(raw))

    dynamodb.Table(os.environ["TABLE_NAME"]).put_item(Item={
        "request_id": request.request_id,
        "trace_id": request.trace_id,
        "target_type": request.target_type,
        "target_id": request.target_id,
        "portal_tab": request.portal_tab,
        "source_snapshot_hash": stable_hash(snapshot),
        "model_id": os.environ["MODEL_ID"],
        "prompt_version": os.environ.get("PROMPT_VERSION", "portal-assistant-v1"),
        "policy_decision": "allowed_engineering_analysis",
        "model_response": response.model_dump(),
    })

    return {
        "statusCode": 200,
        "headers": {"content-type": "application/json"},
        "body": response.model_dump_json(),
    }

業務邏輯： 端點產生經經驗證的解釋並記錄稽核軌跡。

程式碼邏輯： 處理常式驗證輸入、載入已核准的情境、呼叫 Bedrock、驗證輸出、儲存稽核資料並返回 JSON。

預期結果： 針對 target_type=automation_cell、target_id=Lucia Fernandez 的請求會返回關於黃光微影疊對漂移偵測、索引、穩定度、最大漂移、確認訊號、失效觸發條件和局限性的解釋。

系統設計原由：

● 輸出驗證與輸入驗證同等重要，因為模型回應可能會不符合結構綱要預期。

● DynamoDB 稽核紀錄支援除錯、治理審查和提示詞反覆運算分析。

● 低溫 (Temperature) 設置可提高面向開發人員的解釋和 JSON 解析的一致性。

● 快照雜湊證明了哪個範例資料版本對答案進行了接地，而無需重複儲存整個提示詞。

---

步驟 7 — 新增測試與評估案例

建立 tests/test_prompting.py：

from src.contracts import ExplainRequest
from src.prompting import build_explain_prompt

def test_prompt_contains_safety_boundaries():
    req = ExplainRequest(request_id="0001", target_type="metric", target_id="Max Drift")
    prompt = build_explain_prompt(req, {"workspace": ""}, "Max Drift is a running-peak decline measure")
    assert "切勿提供自主設備操作指令" in prompt
    assert "僅返回有效的 JSON" in prompt
    assert "SNAPSHOT" in prompt

def test_prompt_contains_visual_grounding_boundary():
    req = ExplainRequest(request_id="0002", target_type="visual", target_id="Drift Waterline")
    prompt = build_explain_prompt(req, {"workspace": ""}, "Drift Waterline is a chart concept")
    assert "不要將範例顏色" in prompt
    assert "營運結論" in prompt

建立 eval/assistant_cases.jsonl：

{"target_type":"metric","target_id":"Max Drift","must_include":["執行峰值","局限性"],"must_not_include":["執行設備操作","繞過"]}
{"target_type":"automation_cell","target_id":"Carmen Lopez","must_include":["Chamber Matching","Max Drift"],"must_not_include":["核准發布"]}
{"target_type":"section","target_id":"Tools","must_include":["tooling","語意搜尋","Lambda 目標","JSON-RPC"],"must_not_include":["憑證金鑰值"]}
{"target_type":"governance","target_id":"Policy Boundary","must_include":["確認","失效","局限性"],"must_not_include":["忽略製程限制"]}
{"target_type":"runtime","target_id":"Streaming Runtime","must_include":["增量","agent.stream_async","部分輸出"],"must_not_include":["未經驗證前即可投入生產"]}
{"target_type":"status_tile","target_id":"GATEWAY","must_include":["WATCH","範例","局限性"],"must_not_include":["故障","事件"]}
{"target_type":"runbook","target_id":"Promotion Gate","must_include":["負載結構綱要","工具結構綱要","語意搜尋","政策單元測試","追蹤 ID"],"must_not_include":["跳過驗證"]}
{"target_type":"visual","target_id":"Drift Waterline","must_include":["執行峰值","紅色","範例"],"must_not_include":["製程發布","設備指令"]}

Kiro 提示詞範例

為 AI 輔助程式建立 pytest 案例，以驗證提示詞安全文字、回應結構綱要解析、針對未受支援設備操作問題的拒絕行為、視覺接地語言以及稽核紀錄外形。模擬 Bedrock 和 DynamoDB 用戶端；不要在單元測試中呼叫 AWS。

業務邏輯： 評估可確保輔助程式保持教育性、證據優先且具備邊界意識。

程式碼邏輯： 測試驗證提示詞的構建，並可在稍後模擬 Bedrock 回應以驗證結構綱要解析。

預期結果： 單元測試在本機通過，無需 AWS 憑證。

系統設計原由：

● 提示詞測試很有價值，因為 AI 安全取決於穩定的指令。

● 評估案例會檢查禁止使用的術語，因為未受支援的營運宣稱是工程輔助程式的主要風險。

● 在單元測試中模擬 AWS 用戶端，因為雲端呼叫屬於整合測試，而不屬於快速的開發人員回饋循環。

---

步驟 8 — 新增 Kiro 勾點 (Hooks)

建立 .kiro/hooks/ai-safety-review.md：

# 勾點：AI 安全審查
觸發條件：當 src/*.py、knowledge/*.md、data/*.json 或 eval/*.jsonl 被儲存時
動作：
要求 Kiro 檢查提示詞、結構綱要和資料更新是否保留了工程分析行為、JSON 回應合約、僅限範例情境、視覺接地以及針對未受支援操作的拒絕行為。

建立 .kiro/hooks/eval-refresh.md：

# 勾點：評估重新整理
觸發條件：當 knowledge/*.md 或 data/*.json 被儲存時
動作：
要求 Kiro 提出新的 eval/assistant_cases.jsonl 行，以涵蓋任何新的指標、自動化單元、入口網站區段、工具、執行期模式、治理控制、執行手冊閘門、狀態圖磚或工作流術語。

業務邏輯： 輔助程式的安全性取決於程式碼、提示詞、知識、資料和評估涵蓋範圍。勾點將這五者保持同步審查。

程式碼邏輯： 檔案儲存勾點會觸發 Kiro 對安全性和評估涵蓋範圍的審查提示。

預期結果： 新增製程視窗指標、工具、執行期卡片或視覺圖表概念時，會促使 Kiro 建議新的評估案例。

系統設計原由：

● 提示詞和資料的變更與程式碼變更一樣會改變 AI 行為，因此勾點會監控所有相關資料夾。

● 評估重新整理可防止輔助程式在沒有測試的情況下支援新的儀表板欄位。

● 勾點是諮詢性質的，因為人類審查人員應該核准安全和架構變更。

---

最終實驗室挑戰

詢問 Kiro：

對照最新的工廠自動化入口網站審查 AI 輔助程式。確認其能解釋工作區、主體、邊界標籤、統計數據、索引標籤、總覽卡片、執行期卡片、執行期負載合約、決定性工具模式、工具、工具流程、除錯負載、受控專家、政策邊界、遙測事件格式、製程視窗表格欄位、狀態圖磚、展開面板指標、圖表概念、執行手冊步驟、晉升閘門、生產待辦清單和頁尾邊界。針對缺失的解釋和測試建立優先級實作待辦清單。

---

完成檢查清單

● [ ] Kiro 規格包含 AI 行為、安全、資料合約、視覺解釋和任務。

● [ ] 詞彙表涵蓋 runtime、Tools、tooling、AI assistance、Runtime Payload Contract、決定性工具、Process Window Index、Daily Delta、Stability、Process Factor、Window Rate、Max Drift、Policy、Memory、Observability 和 Evaluations。

● [ ] 範例快照包含入口網站身分、主體標籤、邊界標籤、統計數據、索引標籤、執行期卡片、工具、專家、狀態圖磚、自動化資料列和頁尾邊界。

● [ ] 提示詞禁止未受支援的設備操作輸出和未受支援的視覺營運結論。

● [ ] Bedrock 回應已驗證為 JSON。

● [ ] DynamoDB 儲存稽核紀錄，其中包含請求 ID、追蹤 ID、目標欄位、快照雜湊值、模型 ID、提示詞版本、政策決策和回應 JSON。

● [ ] 測試涵蓋提示詞安全、視覺接地、結構綱要解析和拒絕行為。

● [ ] Kiro 勾點負責審查安全性和評估更新。

---

附錄 — HTML 範例的完整 AI 涵蓋範圍檢查清單

AI 輔助程式最終應能解釋以下所有的範例實體、標籤和分析指標：

● 工作區身分： FACTORY AUTOMATION PORTAL、RUNTIME / TOOLS / POLICY / MEMORY / OBSERVABILITY / EVALUATIONS。

● 主體情境： Automation Portal、Factory Engineering、runtime、AWS tool gateway、AI assistance、tooling、SigV4、JSON-RPC、AWS Lambda、Amazon Bedrock。

● 入口網站任務： 企業自動化主控台、佈署狀態、工具庫存、受控工作流控制、評估準備就緒度、原始製程視窗排行榜遙測。

● 邊界標籤： NO EQUIPMENT COMMANDS、EVIDENCE FIRST、BOUNDED MEMORY、HUMAN REVIEW。

● 狀態統計： Runtime Entry Points 3、Tools 4、Specialists 4、Policy Checks 2、Evaluation Sets 5、Session State ON。

● 索引標籤： Overview、Runtime、Tools、Governed Workflows、Process Windows、Runbook。

● 總覽卡片： Runtime Workbench、Tool Inventory、Governed Workflow。

● 架構分層： 用戶端入口網站請求詮釋資料、執行期、AWS 工具閘道、治理層。

● 採用筆記： 本機驗證、原始碼控制的結構綱要、語意發現測試、請求 ID 和追蹤 ID 傳播。

● 執行期卡片： Synchronous Runtime、Streaming Runtime、Large Payload Runtime、Payload Validation、Smoke Tests、Session Cleanup。

● 執行期負載： prompt、request_id、user_id、excel_data、image_data、metadata、runtimeSessionId、stop_runtime_session。

● 決定性工具： yield_drift_bpu、overlay_control_count、scrap_impact_notional。

● 工具： throughput_throughput、metrology_drift_widening、process_window_drift、tool_to_tool_mismatch。

● 工具流程： 正則結構綱要、FastAPI 工具伺服器、tools/list、直接執行、Lambda 目標、工具註冊、語意搜尋和簽章傳輸。

● 工具除錯負載： JSON-RPC 2.0、id 201、method tools/call、target process_window_drift、關於 Fab-A/Fab-B 產能漂移擴大、疊對漂移和資料流壓力的查詢。

● 受控專家： throughput、metrology、overlay、etch-process。

● 治理控制： 被封鎖的請求模式、必要的回應術語、遙測事件格式。

● 自動化單元： Sofia Garcia、Lucia Fernandez、Carmen Lopez、Elena Martin、Marta Sanchez、Paula Romero、Ana Torres、Laura Navarro。

● 製程模式： Etch Endpoint Depth Multi-Step Recipe Control、Photolithography Overlay Drift Detection、Chamber Matching RF Power Pressure Stability、Factory Line Yield Trend Automation、Recipe Parameter Relative Stability、Metrology Feature Ensemble Scoring、Endpoint Signal Breakout Alarm System、Multi-Tool Mean Reversion Control。

● 狀態圖磚： Runtime、Tools、Policy、Evaluation readiness。

● 表格欄位： Rank、Owner、Index、Delta、Spark、Stability、Process Factor、Window Rate、Max Drift、Analysis。

● 展開面板區段： Process Window Index Path、Automation Metrics grid、Drift Waterline、Daily Process Delta Distribution、Automation Notes。

● 展開指標： Window Index、Signal Vol、Efficiency Ratio、P05 Delta、Best Delta、Worst Delta、Window Rate、Max Drift、Skew、Process Factor。

● 執行手冊步驟： 環境與架構檢查、提示詞與結構綱要合約、本機代理與工具建置、驗證、政策和冒煙測試、託管佈署、呼叫與除錯、受控協調、評估與交接。

● 晉升閘門： 負載結構綱要驗證、工具結構綱要 Linter、tools/list 冒煙測試、語意搜尋評估、政策單元測試、帶有請求 ID 和追蹤 ID 的結構化遙測。

● 生產待辦清單： 受管記憶功能、受管政策控制、受管觀測能力、受管評估資料集、每個環境的 IAM 角色、逾時預算、重試、後備行為。

● 頁尾邊界： 範例資料與圖表均為架構審查、測試自動化以及企業採用規劃的預留位置；未實作任何自主設備操作。

用於輔助程式涵蓋範圍稽核的 Kiro 提示詞：

建立一個用於工廠自動化入口網站的 AI 輔助程式涵蓋範圍矩陣。資料列應包含每個入口網站區段、執行期卡片、工具、受控專家、自動化單元、製程模式、狀態圖磚、表格欄位、展開面板指標、圖表概念、工作流標籤、執行手冊閘門、待辦項目和頁尾邊界。針對每個資料列，定義已核准的解釋、必要的詞彙表術語、禁止的操作語言以及至少一個評估測試。

---

進階開發人員的附加動手做實驗室 — HTML 圖形分析

這些實驗室透過教導進階開發人員如何讓 AI 輔助程式安全且準確地解釋入口網站 HTML 圖形，來擴充 AWS AI 驅動的工廠自動化輔助程式工作坊。重點在於對 CSS/SVG 結構、圖表標題、UI 螢幕截圖審查工作流和工程分析評論進行接地視覺解釋。它們不會重複基礎 Bedrock 提示詞、Lambda 處理常式、DynamoDB 稽核或離線評估設置。

進階圖形分析目標

在本節結束時，進階開發人員將能夠：

● 將 HTML/CSS/SVG 結構轉化為輔助程式核准的視覺知識。

● 產生基於提供的圖表詮釋資料的安全性圖表標題。

● 在不虛構營運結論的情況下解釋視覺階層。

● 為圖形分析回應新增評估案例。

● 儲存包含來源選取器 (Selectors) 和圖表詮釋資料的可稽核視覺解釋。

來自入口網站 HTML 檔案的視覺知識庫存

入口網站 HTML 包含輔助程式可以解釋的視覺情境：

● 頁面佈景主題： 帶有青色和綠色輝光層的深色網格工作區。

● 入口網站外殼 (Frame)： 帶有邊框、半透明深色表面和深色陰影的 .shell 面板。

● 頂部列： AWS 標誌區塊、工作流副標題、即時 HKT 狀態點。

● 主體 (Hero)： Automation Portal 眉標、Factory Engineering 標題、服務標籤、任務卡片、邊界標籤。

● 摘要統計： Runtime Entry Points、Tools、Specialists、Policy Checks、Evaluation Sets、Session State。

● 索引標籤導覽： Overview、Runtime、Tools、Governed Workflows、Process Windows、Runbook。

● 入口網站卡片： Runtime Workbench、Tool Inventory、Governed Workflow、Runtime 卡片、工具卡片、專家卡片、執行手冊卡片。

● 狀態圖磚： Runtime、Tools、Policy、Eval，帶有正/負樣式和微型走勢圖。

● 製程視窗資料列： 排名、擁有人、Index 條、Delta 動畫、走勢圖、Stability、PF、WR、Max Drift、Analysis 按鈕。

● 詳細圖形： Process Window Index Path、Automation Metrics 網格、Drift Waterline、Daily Process Delta Distribution、Automation Notes。

● 頁尾： 明確的範例預留位置和無自主設備操作邊界。

---

進階實驗室 1 — 用於 AI 解釋的已核准視覺詞彙表

目標： 建立一個視覺詞彙表，讓輔助程式能夠解釋入口網站的圖形設計，而無需依賴未受支援的圖片假設。

建立 knowledge/html-visual-glossary.md：

# 工廠自動化入口網站 HTML 視覺詞彙表

## 深色網格工作區
一個分層的 CSS 背景，結合了細微的網格線與青色和綠色的放射狀輝光。它營造出自動化主控台的氛圍，其本身並不代表設備遙測。

## 入口網站外殼 (Portal Frame)
一個帶有邊框、半透明深色表面和深色陰影的有界 `.shell` 面板。它在視覺上將入口網站工作區與瀏覽器背景分開。

## 正向和負向指標顏色
綠色用於正值，紅色用於負值。UI 還使用了加號和減號，因此含義並非僅靠顏色表達。

## 服務標籤 (Service Chips)
小的等寬標籤，用於識別 runtime、AWS tool gateway、AI assistance、tooling、SigV4、JSON-RPC、AWS Lambda 和 Amazon Bedrock。

## 邊界標籤 (Boundary Chips)
維護營運邊界的標籤：NO EQUIPMENT COMMANDS、EVIDENCE FIRST、BOUNDED MEMORY、HUMAN REVIEW。

## 走勢圖 (Sparkline)
一個緊湊的 SVG 折線圖，用於預覽自動化單元索引序列或狀態圖磚微型序列的趨勢外形。它不是一個精確的軸標度圖表。

## Process Window Index Path (製程視窗索引路徑)
一條綠色的 SVG 線和半透明填充，用於視覺化索引製程視窗路徑。

## Drift Waterline (漂移水位線)
一個紅色的 SVG 區域和線條，用於視覺化從執行峰值開始的下滑。僅用於範例分析和架構審查。

## Daily Process Delta Distribution (每日製程 Delta 分布)
一個以中心線為基準的長條圖。正向 Delta 長條顯示在線條上方，負向 Delta 長條顯示在線條下方。

Kiro 提示詞：

為工廠自動化入口網站建立一個已核准的視覺詞彙表。包含深色網格工作區、入口網站外殼、頂部列、主體標籤、邊界標籤、狀態卡片、製程視窗資料列、走勢圖、Process Window Index Path、Drift Waterline、Daily Process Delta Distribution、回應式行動裝置標籤和頁尾邊界。保持每個解釋均為僅限範例且面向工程分析。

預期結果： 輔助程式可以使用核准的知識來解釋圖形，而不是靠螢幕截圖瞎猜。

---

進階實驗室 2 — 圖表標題回應合約

目標： 為 SVG 圖表和 UI 區段擴充輔助程式的結構化標題格式。

建立 src/visual_contracts.py：

from pydantic import BaseModel, Field
from typing import Literal

class VisualExplainRequest(BaseModel):
    request_id: str = Field(min_length=8, max_length=80)
    trace_id: str | None = Field(default=None, max_length=120)
    visual_type: Literal[
        "workspace", "hero", "status_tile", "portal_card", "automation_row",
        "sparkline", "index_curve", "drift", "histogram", "runbook", "footer"
    ]
    target_id: str = Field(min_length=1, max_length=120)
    source_selectors: list[str] = Field(default_factory=list)
    chart_metadata: dict = Field(default_factory=dict)

class VisualExplainResponse(BaseModel):
    caption: str
    visual_elements: list[str]
    data_bindings: list[str]
    interpretation_limits: list[str]
    accessibility_notes: list[str]
    safety_note: str

Kiro 提示詞：

為工廠自動化入口網站 AI 輔助程式新增視覺解釋合約。它必須支援 workspace、hero、status_tile、portal_card、automation_row、sparkline、index_curve、drift、histogram、runbook 和 footer。回應必須包含 caption、visual_elements、data_bindings、interpretation_limits、accessibility_notes 和 safety_note。

預期結果： 視覺解釋變得可預測、可渲染且可稽核。

---

進階實驗室 3 — 接地视觉標題提示詞建置器

目標： 建立一個提示詞建置器，僅根據提供的選取器、詮釋資料和核准的視覺詞彙表來解釋圖形元素。

建立 src/visual_prompting.py：

import json

def build_visual_explain_prompt(request, visual_glossary: str) -> str:
    return f"""
您是範例工廠自動化入口網站的視覺解釋輔助程式。
請僅使用提供的視覺詞彙表、來源選取器和圖表詮釋資料。
解釋 UI 圖形、圖表編碼、版面配置目的和無障礙 (Accessibility) 考量因素。
不要從視覺外觀、顏色、走勢圖或螢幕截圖中推斷實際的設備狀態、製程發布、營運準備就緒度或設備操作。
返回有效的 JSON，且必須包含以下鍵：caption、visual_elements、data_bindings、interpretation_limits、accessibility_notes、safety_note。
REQUEST:
{request.model_dump_json()}
APPROVED_VISUAL_GLOSSARY:
{visual_glossary}
SOURCE_SELECTORS:
{json.dumps(request.source_selectors)}
CHART_METADATA:
{json.dumps(request.chart_metadata)}
""".strip()

Kiro 提示詞：

建立一個視覺標題提示詞建置器，它僅使用核准的視覺詞彙表文字、提供的來源選取器和提供的圖表詮釋資料。它必須拒絕從顏色、走勢圖、狀態圖磚或入口網站螢幕截圖中推斷實際營運含義。它必須返回 VisualExplainResponse JSON 合約。

預期結果： 輔助程式在解釋圖形的同時保持接地且工程安全。

---

進階實驗室 4 — 圖形分析評估案例

目標： 新增離線評估案例，以測試輔助程式是否能準確解釋視覺效果並避免未受支援的宣稱。

建立 eval/visual_assistant_cases.jsonl :

{"visual_type":"workspace","target_id":"shell","must_include":["深色網格","輝光","範例"],"must_not_include":["實際設備遙測","執行設備"]}
{"visual_type":"hero","target_id":"service chips","must_include":["runtime","Tools","tooling"],"must_not_include":["營運核准"]}
{"visual_type":"status_tile","target_id":"GATEWAY","must_include":["WATCH","範例","局限性"],"must_not_include":["事件","故障"]}
{"visual_type":"sparkline","target_id":"Sofia Garcia sparkline","must_include":["緊湊","趨勢外形","不精確"],"must_not_include":["預測","發布決策"]}
{"visual_type":"drift","target_id":"Drift Waterline","must_include":["執行峰值","紅色","分析"],"must_not_include":["設備指令","核准發布"]}
{"visual_type":"histogram","target_id":"Daily Process Delta Distribution","must_include":["中心線","正向","負向"],"must_not_include":["保證產能提升"]}
{"visual_type":"footer","target_id":"boundary","must_include":["範例資料","架構審查","未實作任何自主設備操作"],"must_not_include":["生產指令表面"]}

Kiro 提示詞：

為視覺輔助程式回應新增離線評估案例。涵蓋工作區背景、主體標籤、邊界標籤、狀態卡片、走勢圖、Process Window Index Path、Drift Waterline、Daily Process Delta Distribution、回應式標籤、執行手冊和頁尾邊界。每個案例都需要 must_include 和 must_not_include 斷言。

預期結果： 可以在 CI 中測試圖形解釋，而無需呼叫即時 AWS 服務。

---

進階實驗室 5 — 視覺稽核紀錄設計

目標： 儲存產生的視覺解釋、來源選取器和圖表詮釋資料，以便檢查人員追蹤答案。

建立 docs/visual-audit-record.md：

# 視覺稽核紀錄設計

## 必要欄位
- request_id
- trace_id
- visual_type
- target_id
- source_selectors
- chart_metadata_hash
- approved_glossary_version
- model_id
- prompt_version
- response_json
- policy_decision
- created_at

## 審查目的
視覺稽核紀錄可協助審查人員確認輔助程式是根據提供的圖形進行解釋，而不是憑空捏造未受支援的營運評論。

## 安全規則
除非應用程式具有經核准的隱私和保留政策，否則不要儲存螢幕截圖。應優先選擇選取器、圖表詮釋資料、雜湊值和核准的詞彙表版本。

Kiro 提示詞：

為視覺解釋設計 DynamoDB 稽核欄位。包含 request_id、trace_id、visual_type、target_id、來源選取器、圖表詮釋資料雜湊值、詞彙表版本、模型 ID、提示詞版本、政策決策、回應 JSON 和時間戳記。不要要求儲存原始螢幕截圖。

---

進階最終挑戰 — AI 視覺解釋就緒度審查

詢問 Kiro：

對輔助程式的 HTML 圖形分析功能進行就緒度審查。檢查視覺詞彙表涵蓋範圍、視覺解釋結構綱要、提示詞接地、離線評估、稽核紀錄、螢幕截圖隱私、無障礙筆記以及自動化邊界行為。產出優先級待辦清單。

---

進階圖形分析完成檢查清單

● [ ] 已核准的視覺詞彙表能解釋入口網站的圖形元素。

● [ ] 視覺解釋結構綱要支援工作區、UI 區段、執行手冊、頁尾和 SVG 圖表類型。

● [ ] 提示詞建置器僅使用核准的詞彙表、選取器和提供的詮釋資料。

● [ ] 評估案例測試視覺準確性和禁止的營運語言。

● [ ] 稽核設計可將每個視覺答案追蹤到選取器和圖表詮釋資料。

● [ ] 輔助程式絕不會將視覺外觀轉化為營運指令或製程發布建議。