使用 Kiro 建置：他加祿語 學習 App 中可審查的獨特額外例句工作坊

目標受眾： 負責建置內容 QA 管線與 AI 輔助教育應用程式的專業開發人員

時長： 2 小時

主要 AWS AI 服務： Kiro

專案產出： 一個由 Kiro 引導的 QA 管線，用於重寫、去重、驗證並匯出可審查的額外範例。

僅限教育工程研討會。這是一項軟體架構練習，而非流程發佈建議。

工作坊摘要

本工作坊旨在協助開發人員透過結構化的 QA，改善他加祿語（Tagalog）學習 App 中的額外範例。參與者將使用 Kiro 定義範例合約、生成多樣化的練習句子、偵測重複項目、加入可追溯的背景資訊、匯出審查員報告並驗證數量。此工作流程可將鬆散的輔助範例轉化為獨特、可稽核的學習資產，讓審查員能在發布或安全擴展至未來課程前進行檢查。

工作坊目標

開發人員將建置一個用於額外範例的內容 QA 管線。該管線將擷取主要的原生他加祿語（Natural Tagalog）句子、生成三個相關範例、偵測整個網站中的重複項目、加入可追溯的背景資訊、匯出審查員報告，並驗證卡片與範例的數量。

2 小時議程

---

步驟 1 — 建立用於額外範例 QA 的 Kiro 導向設定

開發人員任務

● 在 Kiro 中生成導向文件（steering docs）。

● 加入額外範例的 QA 規則。

● 要求 Kiro 列出內容風險。

● 在撰寫腳本前提交（commit）導向設定。

Kiro 提示詞範例

建立一個用於額外範例品質的導向文件。每張卡片必須包含三個相關範例。範例必須具備足夠的獨特性以供審查，並能透過文章與句子編號進行追溯，且在審查完成前須標記為草稿（draft）。

系統設計決策

● 在編碼前使「步驟 1 — 建立用於額外範例 QA 的 Kiro 導向設定」保持顯性： 專業開發人員在使用 AI 輔助工程時不應依賴隱含的假設。工作坊首先將規則寫入導向設定或規格書中，使 Kiro 具備持久的專案背景資訊。這能讓生成的程式碼更具一致性，為審查員提供具體的檢查依據，並避免在每次對話中重複解釋。此決策也有助於新進開發人員理解檔案存在的原因、解決了什麼問題，以及哪些行為是被允許或禁止的。

● 保持實作具備確定性（deterministic）且可審查： 雖然 Kiro 可以協助生成程式碼、測試與文件，但工作坊的產出應具備可重複性。具備確定性的腳本、明確的組態、穩定的綱要（schemas）與驗證報告能讓結果更容易除錯。當每項轉換都有可見的輸入與輸出時，開發人員就能審查差異（diffs）、重新執行檢查，並向其他工程師解釋該系統。這對於語言學習內容尤為重要，因為正確性與文化背景需要人工審查。

● 將驗證附加至工作流程，而非僅限於最終的展示： 工作坊將驗證視為系統設計的一部分。每個步驟都包含檢查、報告或 Hook，以便在造成變更的當下就能發現缺陷。這種方法讓 Kiro 能夠同時擔任編碼助理與品質審查員，同時讓開發人員保持主導權。這是一個實用的專業工作流程：用規格書計劃、用導向設定引導、以小型任務實作、驗證輸出並記錄交付檔案。

程式碼範例 — .kiro/steering/extra-example-qa.md

# 額外範例 QA 導向設定

- 每個句子卡片必須恰好包含三個額外範例。
- 範例必須與該卡片的原生他加祿語（Natural Tagalog）句子相關。
- 追溯文章編號、句子編號與範例編號。
- 偵測整個網站中重複的他加祿語範例文字。
- 為每個生成的範例加入審查狀態與審查員筆記。
- 若卡片數量或範例數量錯誤，則驗證失敗。

程式碼說明

● 業務邏輯： 導向設定檔案將額外範例定義為可審查的學習內容。

● 程式碼邏輯： Kiro 在生成規格書、模型、重寫腳本、驗證器、Hook 與文件時會使用這些規則。

● 預期結果： 未來的程式碼將包含可追溯性、重複偵測與審查中繼資料。

---

步驟 2 — 定義可審查的額外範例紀錄

開發人員任務

● 建立 example_model.py。

● 加入審查狀態與可追溯性欄位。

● 驗證必填文字。

● 序列化紀錄以用於報告。

Kiro 提示詞範例

建立一個用於可審查額外範例的 Python dataclass 模型。欄位包括：articleNumber, sentenceNumber, exampleNumber, sourceNaturalTagalog, tagalog, english, naturalTagalog, politeTagalog, duplicateGroup, reviewStatus, reviewNotes。

系統設計決策

● 在編碼前使「步驟 2 — 定義可審查的額外範例紀錄」保持顯性： 專業開發人員在使用 AI 輔助工程時不應依賴隱含的假設。工作坊首先將規則寫入導向設定或規格書中，使 Kiro 具備持久的專案背景資訊。這能讓生成的程式碼更具一致性，為審查員提供具體的檢查依據，並避免在每次對話中重複解釋。此決策也有助於新進開發人員理解檔案存在的原因、解決了什麼問題，以及哪些行為是被允許或禁止的。

● 保持實作具備確定性且可審查： 雖然 Kiro 可以協助生成程式碼、測試與文件，但工作坊的產出應具備可重複性。具備確定性的腳本、明確的組態、穩定的綱要與驗證報告能讓結果更容易除錯。當每項轉換都有可見的輸入與輸出時，開發人員就能審查差異、重新執行檢查，並向其他工程師解釋該系統。這對於語言學習內容尤為重要，因為正確性與文化背景需要人工審查。

● 將驗證附加至工作流程，而非僅限於最終的展示： 工作坊將驗證視為系統設計的一部分。每個步驟都包含檢查、報告或 Hook，以便在造成變更的當下就能發現缺陷。這種方法讓 Kiro 能夠同時擔任編碼助理與品質審查員，同時讓開發人員保持主導權。這是一個實用的專業工作流程：用規格書計劃、用導向設定引導、以小型任務實作、驗證輸出並記錄交付檔案。

程式碼範例 — example_model.py

from dataclasses import dataclass, asdict

ALLOWED_REVIEW_STATUS = {"draft", "native-reviewed", "blocked"}

@dataclass
class ExtraExample:
    articleNumber: int
    sentenceNumber: int
    exampleNumber: int
    sourceNaturalTagalog: str
    tagalog: str
    english: str
    naturalTagalog: str
    politeTagalog: str
    duplicateGroup: str | None = None
    reviewStatus: str = "draft"
    reviewNotes: str = "Needs native-speaker review."

    def validate(self):
        if self.reviewStatus not in ALLOWED_REVIEW_STATUS:
            raise ValueError(f"Invalid reviewStatus: {self.reviewStatus}")
        required = [self.sourceNaturalTagalog, self.tagalog, self.english, self.naturalTagalog, self.politeTagalog]
        if any(not value.strip() for value in required):
            raise ValueError("ExtraExample has empty required text")

    def to_dict(self):
        self.validate()
        return asdict(self)

程式碼說明

● 業務邏輯： 資料類別（dataclass）使每個額外範例皆可追溯與審查。

● 程式碼邏輯： 它會驗證必填文字、控制審查狀態，並將其序列化為字典，以便用於 JSON 報告。

● 預期結果： 呼叫 to_dict() 將回傳經過驗證的紀錄，或擲出明確的驗證錯誤。

---

步驟 3 — 從每個卡片生成三個相關範例

開發人員任務

● 擷取主要的原生他加祿語句子。

● 生成用於使用、重複與練習的範例。

● 加入客氣/禮貌（polite）變體。

● 驗證每筆紀錄。

Kiro 提示詞範例

建立一個具備確定性的生成器，從卡片的原生他加祿語句子產生三個範例。每個範例皆須包含他加祿語、英語、原生他加祿語、禮貌他加祿語、來源句子、文章編號、句子編號與範例編號。

系統設計決策

● 在編碼前使「步驟 3 — 從每個卡片生成三個相關範例」保持顯性： 專業開發人員在使用 AI 輔助工程時不應依賴隱含的假設。工作坊首先將規則寫入導向設定或規格書中，使 Kiro 具備持久的專案背景資訊。這能讓生成的程式碼更具一致性，為審查員提供具體的檢查依據，並避免在每次對話中重複解釋。此決策也有助於新進開發人員理解檔案存在的原因、解決了什麼問題，以及哪些行為是被允許或禁止的。

● 保持實作具備確定性且可審查： 雖然 Kiro 可以協助生成程式碼、測試與文件，但工作坊的產出應具備可重複性。具備確定性的腳本、明確的組態、穩定的綱要與驗證報告能讓結果更容易除錯。當每項轉換都有可見的輸入與輸出時，開發人員就能審查差異、重新執行檢查，並向其他工程師解釋該系統。這對於語言學習內容尤為重要，因為正確性與文化背景需要人工審查。

● 將驗證附加至工作流程，而非僅限於最終的展示： 工作坊將驗證視為系統設計的一部分。每個步驟都包含檢查、報告或 Hook，以便在造成變更的當下就能發現缺陷。這種方法讓 Kiro 能夠同時擔任編碼助理與品質審查員，同時讓開發人員保持主導權。這是一個實用的專業工作流程：用規格書計劃、用導向設定引導、以小型任務實作、驗證輸出並記錄交付檔案。

程式碼範例 — generate_examples.py

from example_model import ExtraExample

def generate_examples(article_number, sentence_number, natural_tagalog):
    templates = [
        (f'Gagamitin ko rin ang linyang "{natural_tagalog}" mamaya.', f'I will also use the line "{natural_tagalog}" later.', f'Uulitin ko ang linyang "{natural_tagalog}" nang dahan-dahan.', f'Pakisuyo, uulitin ko po ang linyang "{natural_tagalog}" nang dahan-dahan.'),
        (f'Sasabihin ko ang linyang "{natural_tagalog}" sa kausap ko.', f'I will say the line "{natural_tagalog}" to the person I am talking to.', f'Ipapaliwanag ko ang linyang "{natural_tagalog}" sa simpleng paraan.', f'Pakisuyo, ipapaliwanag ko po ang linyang "{natural_tagalog}" sa simpleng paraan.'),
        (f'Magsanay tayo gamit ang linyang "{natural_tagalog}" ngayon.', f'Let us practice using the line "{natural_tagalog}" now.', f'Isusulat ko ang linyang "{natural_tagalog}" sa notes ko.', f'Pakisuyo, isusulat ko po ang linyang "{natural_tagalog}" sa notes ko.')
    ]
    output = []
    for i, (tagalog, english, natural, polite) in enumerate(templates, start=1):
        example = ExtraExample(article_number, sentence_number, i, natural_tagalog, tagalog, english, natural, polite)
        example.validate()
        output.append(example)
    return output

程式碼說明

● 業務邏輯： 生成器會建立三個與主卡片句子綁定的可審查範例。

● 程式碼邏輯： 它會填入具備確定性的範本、建立資料類別紀錄、對其進行驗證並回傳結構化輸出。

● 預期結果： 呼叫 generate_examples(4, 10, 'Paki-check kung pumasok ang bayad.') 會回傳三個帶有可追溯性的草稿範例。

---

步驟 4 — 偵測重複項目並匯出審查員 CSV

開發人員任務

● 正規化（Normalize）他加祿語文字。

● 對所有範例中的重複項目進行分組。

● 為非開發人員審查員匯出審查用 CSV。

● 要求 Kiro 摘要重複分組。

Kiro 提示詞範例

建立重複偵測功能與 CSV 匯出器。正規化他加祿語文字、將重複項目分組、指派 duplicateGroup ID，並輸出 articleNumber, sentenceNumber, sourceNaturalTagalog, tagalog, english, politeTagalog, duplicateGroup, reviewStatus 與 reviewNotes。

系統設計決策

● 在編碼前使「步驟 4 — 偵測重複項目並匯出審查員 CSV」保持顯性： 專業開發人員在使用 AI 輔助工程時不應依賴隱含的假設。工作坊首先將規則寫入導向設定或規格書中，使 Kiro 具備持久的專案背景資訊。這能讓生成的程式碼更具一致性，為審查員提供具體的檢查依據，並避免在每次對話中重複解釋。此決策也有助於新進開發人員理解檔案存在的原因、解決了什麼問題，以及哪些行為是被允許或禁止的。

● 保持實作具備確定性且可審查： 雖然 Kiro 可以協助生成程式碼、測試與文件，但工作坊的產出應具備可重複性。具備確定性的腳本、明確的組態、穩定的綱要與驗證報告能讓結果更容易除錯。當每項轉換都有可見的輸入與輸出時，開發人員就能審查差異、重新執行檢查，並向其他工程師解釋該系統。這對於語言學習內容尤為重要，因為正確性與文化背景需要人工審查。

● 將驗證附加至工作流程，而非僅限於最終的展示： 工作坊將驗證視為系統設計的一部分。每個步驟都包含檢查、報告或 Hook，以便在造成變更的當下就能發現缺陷。這種方法讓 Kiro 能夠同時擔任編碼助理與品質審查員，同時讓開發人員保持主導權。這是一個實用的專業工作流程：用規格書計劃、用導向設定引導、以小型任務實作、驗證輸出並記錄交付檔案。

程式碼範例 — export_review_csv.py

import csv
import json
from pathlib import Path

COLUMNS = ["articleNumber", "sentenceNumber", "exampleNumber", "sourceNaturalTagalog", "tagalog", "english", "politeTagalog", "duplicateGroup", "reviewStatus", "reviewNotes"]

def export_csv(json_path="example-review-report.json", csv_path="example-review-report.csv"):
    payload = json.loads(Path(json_path).read_text(encoding="utf-8"))
    with open(csv_path, "w", newline="", encoding="utf-8") as file:
        writer = csv.DictWriter(file, fieldnames=COLUMNS)
        writer.writeheader()
        for example in payload["examples"]:
            writer.writerow({column: example.get(column, "") for column in COLUMNS})
    return csv_path

if __name__ == "__main__":
    print(export_csv())

程式碼說明

● 業務邏輯： 匯出器透過與試算表相容的 CSV，讓非開發人員審查員也能輕鬆進行範例審查。

● 程式碼邏輯： 它會讀取 JSON 報告、以穩定的順序寫入指定的欄位，並回傳 CSV 路徑。

● 預期結果： 執行 python export_review_csv.py 會建立 example-review-report.csv 以供語言審查使用。

---

附加實作開發實驗室

這些實驗室是 工作坊 6 — 獨特且可審查額外範例 所特有的。它們透過語意獨特性檢查、可追溯的範例身分、重寫佇列、審查員匯入以及批次級別的品質報告，來擴展額外範例的 QA 管線。其核心重點在於範例的多樣性與可審查性，而非泛用的驗證執行器。

實作實驗室 A — 加入穩定的範例 ID 與歷程中繼資料

開發人員任務

● 要求 Kiro 為每個額外範例生成穩定的 ID。

● 包含文章編號、句子編號、範例編號以及來源句子的雜湊值（hash）。

● 加入歷程中繼資料（lineage metadata），以記錄生成策略與範本名稱。

● 驗證整個網站中每個範例 ID 的唯一性。

Kiro 提示詞範例

為額外範例加入穩定的範例身分識別與歷程資訊（lineage）。
從 articleNumber, sentenceNumber, exampleNumber 與 sourceNaturalTagalog 的短雜湊值建立 exampleId。
加入 generatedBy, generationStrategy, templateName 與 sourceHash 欄位。
若有重複的 exampleId 數值，則驗證失敗。

系統設計決策

● 審查意見需要穩定的 ID： 審查員必須能夠在重新生成後，依然指向同一個範例。

● 歷程資訊解釋了範例存在的原因： 生成的範例應顯示其來自練習範本、情境重寫還是手動覆蓋。

● 身分識別支援去重機制： 當每筆紀錄都有穩定的鍵值與來源雜湊時，重複偵測會變得更容易。

程式碼範例 — example_identity.py

import hashlib


def short_hash(value: str) -> str:
    return hashlib.sha1(value.encode("utf-8")).hexdigest()[:8]


def example_id(article_number: int, sentence_number: int, example_number: int, source_natural_tagalog: str) -> str:
    return f"a{article_number:03d}-s{sentence_number:03d}-e{example_number:02d}-{short_hash(source_natural_tagalog)}"


def lineage(template_name: str, strategy: str = "deterministic-template") -> dict:
    return {
        "generatedBy": "workshop-6-extra-example-pipeline",
        "generationStrategy": strategy,
        "templateName": template_name
    }

程式碼說明

● 業務邏輯： 穩定的 ID 與歷程資訊讓範例在審查與重新生成過程中皆可追溯。

● 程式碼邏輯： 短雜湊將 ID 與來源句子綁定，而歷程資訊則記錄了生成方法。

● 預期結果： 每個範例都可以在審查員報告與去重記錄中被引用。

實作實驗室 B — 為近乎重複的項目加入語意相似度評分

開發人員任務

● 要求 Kiro 加入一個輕量級的近乎重複（near-duplicate）偵測器，且不依賴外部服務。

● 正規化他加祿語文字並計算詞記（token）重疊度。

● 標記具有高相似度的範例，即使它們不是完全相同的重複項目。

● 匯出近乎重複的候選名單以供審查，而非自動刪除。

Kiro 提示詞範例

為他加祿語額外範例建立一個本地的近乎重複偵測器。
正規化標點符號與大小寫，計算詞記（token）集合的 Jaccard 相似度，並標記分數超過 0.82 的配對。
請勿自動刪除範例。
將重複候選項目連同範例 ID、分數與審查員決策（reviewerDecision）一併寫出。

系統設計決策

● 僅靠精確重複檢查是不夠的： 範例可能近乎相同，但仍能通過精確的文字比對。

● 本地評分可保持工作坊的確定性： 詞記重疊度是可解釋且可重複驗證的，不需要外部 API。

● 審查員決策仍由人工主導： 偵測器負責標記候選項目；由審查員決定保留、重寫還是封鎖。

程式碼範例 — near_duplicates.py

import re
from itertools import combinations


def tokens(text: str) -> set[str]:
    normalized = re.sub(r"[^\w\sñÑ]", " ", text.lower())
    return {part for part in normalized.split() if part}


def jaccard(left: str, right: str) -> float:
    a = tokens(left)
    b = tokens(right)
    if not a and not b:
        return 1.0
    return len(a & b) / len(a | b)


def near_duplicate_pairs(examples: list[dict], threshold: float = 0.82) -> list[dict]:
    findings = []
    for left, right in combinations(examples, 2):
        score = jaccard(left["tagalog"], right["tagalog"])
        if score >= threshold:
            findings.append({
                "leftExampleId": left["exampleId"],
                "rightExampleId": right["exampleId"],
                "score": round(score, 3),
                "reviewerDecision": ""
            })
    return findings

程式碼說明

● 業務邏輯： 偵測器會找出可能讓學習者感到重複乏味的範例。

● 程式碼邏輯： 它會正規化文字、計算 Jaccard 相似度，並回傳高於閾值的候選配對。

● 預期結果： 審查員會收到一份近乎重複的報告，且不會自動遺失任何範例。

實作實驗室 C — 建立範本多樣性預算

開發人員任務

● 要求 Kiro 定義範例允許的範本家族（template families）。

● 計算每個範本家族在每篇文章與每個類別中出現的頻率。

● 若單一範本家族在頁面中佔比過高，則驗證失敗。

● 加入一份報告，建議接下來應該使用哪個範本家族。

Kiro 提示詞範例

為額外範例建立一個範本多樣性預算。
範本家族包括：repeat（重複）、apply（應用）、ask（提問）、explain（解釋）與 write-down（寫下）。
在單一文章中，任一範本家族的佔比皆不得超過額外範例的 45%。
回傳文章級別的計次、失敗項目以及建議的下一個家族。

系統設計決策

● 獨特性應包含教學法上的多樣性： 三個範例在文字上可能是獨特的，但在教學法上卻可能流於重複。

● 預算可防止範本被過度使用： 限制每個家族的最大份額，能保持生成範例的多樣性。

● 建議有助於重寫迴圈（rewrite loops）： 驗證器應指出哪個範本家族可以改善平衡。

程式碼範例 — template_budget.py

from collections import Counter, defaultdict

MAX_SHARE = 0.45
FAMILIES = ["repeat", "apply", "ask", "explain", "write-down"]


def article_template_report(examples: list[dict]) -> dict:
    grouped = defaultdict(list)
    for example in examples:
        grouped[example["articleNumber"]].append(example)

    reports = {}
    for article, rows in grouped.items():
        counts = Counter(row["templateFamily"] for row in rows)
        total = sum(counts.values()) or 1
        failures = [
            {"templateFamily": family, "share": count / total}
            for family, count in counts.items()
            if count / total > MAX_SHARE
        ]
        suggested = min(FAMILIES, key=lambda family: counts.get(family, 0))
        reports[article] = {"total": total, "counts": dict(counts), "failures": failures, "suggestedNextFamily": suggested}
    return reports

程式碼說明

● 業務邏輯： 該報告使額外範例在不同的練習風格中保持多樣化。

● 程式碼邏輯： 它按文章將範例分組、計算範本家族數量、標記佔比過高的家族，並推薦未被充分使用的家族。

● 預期結果： 開發人員可以根據具體的多樣性回饋，重寫重複的批次。

實作實驗室 D — 為重複或薄弱的範例建立重寫佇列

開發人員任務

● 要求 Kiro 建立一個需要重寫的範例佇列。

● 加入原因標籤，例如 exact-duplicate（完全重複）、near-duplicate（近乎重複）、template-overused（範本過度使用）與 missing-politeness（遺漏禮貌變体）。

● 產生保留來源句子與可追溯性的重寫提示詞。

● 在審查完成前，將重寫的範例保持在草稿（draft）狀態。

Kiro 提示詞範例

為薄弱的額外範例建立一個重寫佇列。
輸入來源包括完全重複發現、近乎重複發現、範本預算失敗以及驗證失敗。
為佇列中的每個項目產生 exampleId, reason, sourceNaturalTagalog, currentTagalog, rewriteInstruction，並將 reviewStatus 設為 draft。
請勿自動覆寫原始範例。

系統設計決策

● 重寫應是審慎且深思熟慮的： 薄弱的範例應進入佇列，而非被默默替換。

● 原因標籤能提升審查效率： 審查員可以在核准重寫前，看到該範例被標記的原因。

● 保持可追溯性完好無損： 重寫會保留原始的範例 ID 與來源句子以供比對。

程式碼範例 — rewrite_queue.py

from collections import defaultdict


def build_rewrite_queue(examples_by_id: dict[str, dict], findings: list[dict]) -> list[dict]:
    grouped_reasons = defaultdict(list)
    for finding in findings:
        grouped_reasons[finding["exampleId"]].append(finding["reason"])

    queue = []
    for example_id, reasons in grouped_reasons.items():
        example = examples_by_id[example_id]
        queue.append({
            "exampleId": example_id,
            "reason": sorted(set(reasons)),
            "sourceNaturalTagalog": example["sourceNaturalTagalog"],
            "currentTagalog": example["tagalog"],
            "rewriteInstruction": "Create a distinct beginner-friendly example that keeps the same source sentence context.",
            "reviewStatus": "draft",
            "reviewerDecision": ""
        })
    return queue

程式碼說明

● 業務邏輯： 該佇列將 QA 發現轉化為受控的重寫工作。

● 程式碼邏輯： 發現項目依範例 ID 分組、按原因去重，並轉換為可供審查員處理的任務。

● 預期結果： 開發人員可以重寫被標記的範例，而不會遺失原始背景資訊。

實作實驗室 E — 匯入審查員決策並套用安全更新

開發人員任務

● 要求 Kiro 設計審查員決策的匯入格式。

● 支援以下決策：approve（核准）、rewrite（重寫）、block（封鎖）與 needs-discussion（需要討論）。

● 將核准的中繼資料更新套用至範例報告。

● 拒絕在面向學習者的最終輸出中發布被封鎖的範例。

Kiro 提示詞範例

為額外範例建立一個審查員決策匯入器。
讀取包含 exampleId, decision, reviewerNotes, revisedTagalog, revisedEnglish 與 reviewedBy 的 `reviewer-decisions.csv` 檔案。
僅在修改後欄位不為空時，才套用核准的重寫內容。
將被封鎖的範例標記為 blocked，並在匯出面向學習者的內容時將其排除。

系統設計決策

● 審查員回饋必須支援雙向來回（round-trip）： 唯有在決策能被安全匯入時，CSV 匯出才真正有用。

● 安全更新可避免意外的空白： 除非修改後的欄位包含文字，否則不應套用重寫。

● 被封鎖的內容應採用安全失敗（fail-closed）原則： 面向學習者的匯出內容在預設情況下應排除被封鎖的範例。

程式碼範例 — import_reviewer_decisions.py

import csv

ALLOWED_DECISIONS = {"approve", "rewrite", "block", "needs-discussion"}


def apply_decisions(examples_by_id: dict[str, dict], csv_path: str) -> dict[str, dict]:
    with open(csv_path, newline="", encoding="utf-8") as file:
        for row in csv.DictReader(file):
            example_id = row["exampleId"]
            decision = row["decision"]
            if decision not in ALLOWED_DECISIONS or example_id not in examples_by_id:
                continue
            example = examples_by_id[example_id]
            example["reviewerDecision"] = decision
            example["reviewNotes"] = row.get("reviewerNotes", "")
            example["reviewedBy"] = row.get("reviewedBy", "")
            if decision == "block":
                example["reviewStatus"] = "blocked"
            if decision == "approve":
                example["reviewStatus"] = "native-reviewed"
            if decision == "rewrite" and row.get("revisedTagalog") and row.get("revisedEnglish"):
                example["tagalog"] = row["revisedTagalog"]
                example["english"] = row["revisedEnglish"]
                example["reviewStatus"] = "draft"
    return examples_by_id


def learner_examples(examples: list[dict]) -> list[dict]:
    return [example for example in examples if example.get("reviewStatus") != "blocked"]

程式碼說明

● 業務邏輯： 審查員的決策成為內容 QA 生命週期的一部分。

● 程式碼邏輯： 匯入器會更新狀態、筆記、審查員身分與安全重寫，同時過濾掉被封鎖的輸出。

● 預期結果： 審查回饋可以直接套用，無須手動編輯龐大的 JSON 檔案。

實作實驗室 F — 產生批次品質計分卡

開發人員任務

● 要求 Kiro 為每個範例批次建立計分卡（scorecard）。

● 包含完全重複計次、近乎重複計次、遺漏審查中繼資料、範本主導性、封鎖計次與核准計次。

● 產生通過/失敗（pass/fail）的發布建議。

● 將計分卡儲存為 JSON 與 Markdown 以供交付使用。

Kiro 提示詞範例

為額外範例建立一個批次品質計分卡。
輸入來源包括範例、完全重複發現、近乎重複發現、範本預算報告與審查員決策。
回傳指標、通過/失敗狀態、發布建議（releaseRecommendation）與後續行動（nextActions）。
寫出 `example-quality-scorecard.json` 與 `example-quality-scorecard.md`。

系統設計決策

● 品質需要發布視角的視圖： 個別驗證器雖然有用，但維護者需要一個最終的摘要。

● 計分卡讓進度可視化： 團隊可以追蹤重複計次是否在減少，以及核准的範例是否在增加。

● Markdown 支援人工交付： 易讀的報告有助於審查員與工作坊參與者理解還剩下哪些工作。

程式碼範例 — scorecard.py

import json
from pathlib import Path


def quality_scorecard(examples: list[dict], exact_duplicates: list[dict], near_duplicates: list[dict], template_failures: list[dict]) -> dict:
    blocked = sum(1 for example in examples if example.get("reviewStatus") == "blocked")
    approved = sum(1 for example in examples if example.get("reviewStatus") == "native-reviewed")
    missing_review = sum(1 for example in examples if not example.get("reviewStatus"))
    passed = not exact_duplicates and len(near_duplicates) <= 5 and not template_failures and missing_review == 0
    return {
        "totalExamples": len(examples),
        "approvedExamples": approved,
        "blockedExamples": blocked,
        "exactDuplicateCount": len(exact_duplicates),
        "nearDuplicateCount": len(near_duplicates),
        "templateFailureCount": len(template_failures),
        "missingReviewMetadata": missing_review,
        "status": "passed" if passed else "needs-work",
        "releaseRecommendation": "Ready for learner-facing export." if passed else "Resolve QA findings before release."
    }


def write_scorecard(scorecard: dict, json_path="example-quality-scorecard.json", md_path="example-quality-scorecard.md") -> None:
    Path(json_path).write_text(json.dumps(scorecard, indent=2), encoding="utf-8")
    lines = ["# 範例品質計分卡", ""]
    for key, value in scorecard.items():
        lines.append(f"- **{key}:** {value}")
    Path(md_path).write_text("\n".join(lines) + "\n", encoding="utf-8")

程式碼說明

● 業務邏輯： 計分卡為維護者提供額外範例的發布就緒摘要。

● 程式碼邏輯： 指標衍生自範例與驗證器的發現，然後寫入成 JSON 與 Markdown。

● 預期結果： 該批次具備明確的通過/失敗建議與具體可執行的品質指標。

---

參考架構說明

● 本工作坊強調的 Kiro 能力： 範例 QA 導向、穩定身分設計、近乎重複分析、範本多樣性驗證、重寫佇列生成、審查員決策匯入以及發布計分卡文件化。

● 產品範疇： 用於他加祿語學習卡片的額外範例。生成的範例在由他加祿語母語人士審查前，皆保持為草稿（draft）狀態。

● 執行環境範疇： 首先在本地執行 Python QA 管線。後續可選擇自動化配置，在 CI 中執行相同的檢查，然後才匯出面向學習者的範例。