使用 Kiro 建置：他加祿語 卡片的文法與發音補強管線工作坊

目標受眾： 負責建置內容豐富化管線與教育工具的專業開發人員

時長： 2 小時

主要 AWS AI 服務： Kiro

專案產出： 一個由 Kiro 引導的確定性豐富化管線，用於為他加祿語卡片加入文法拆解與發音指南。

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

工作坊摘要

本工作坊將引導開發人員完成為他加祿語卡片豐富化文法筆記與發音支援的工作。 參與者將使用 Kiro 定義確定性邊界、建置詞彙表、生成輔助文字、修補結構化內容或 HTML，並驗證覆蓋率。 這些練習強調了可審查的語言輔助機制：雖然自動化可以準備解釋內容，但人工審查能確保面向學習者的文法、語音引導與範例在整體上保持清晰、準確、一致且實用。

工作坊目標

開發人員將建置一個管線，用於擷取他加祿語句子、加入文法解釋、生成發音指南、修補 HTML 或結構化卡片資料，並驗證覆蓋率。

2 小時議程

---

步驟 1 — 建立用於豐富化邊界的 Kiro 導向設定

開發人員任務

● 在 Kiro 中生成導向文件。

● 加入豐富化特定規則。

● 要求 Kiro 列出哪些應該是確定性的，哪些需要審查。

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

Kiro 提示詞範例

建立一個用於他加祿語文法與發音豐富化管線的導向文件。使用確定性 Python 輔助程式、主題詞彙表、發音對應表、備用規則、BeautifulSoup 修補、驗證檢查以及母語人士審查提醒。

系統設計決策

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

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

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

程式碼範例 — .kiro/steering/enrichment.md

# 豐富化導向設定

- 保持文法與發音豐富化具備確定性。
- 對已知字詞使用詞彙表字典。
- 對常用字詞使用發音對應表。
- 對未知字詞使用透明的備用規則。
- 請勿在豐富化過程中重寫他加祿語句子。
- 在母語人士審查完成前，將輔助輸出標記為草稿（draft）。
- 在每個批次執行後印出驗證計數。

程式碼說明

● 業務邏輯： 導向設定檔案定義了豐富化的範疇與品質預期。

● 程式碼邏輯： Kiro 在生成腳本、測試、Hook 與文件時，會將該檔案作為持久的背景資訊。

● 預期結果： Kiro 生成的豐富化程式碼應保留他加祿語句子，並加入可審查的輔助區塊。

---

步驟 2 — 建置本地文法詞彙表

開發人員任務

● 建立 glossary.py。

● 加入常用字詞，甚至活動相關的外來語（loanwords）。

● 加入透明的備用行為。

● 要求 Kiro 生成詞彙表測試。

Kiro 提示詞範例

建立一個適合初學者的他加祿語詞彙表模組。包含 po, opo, saan, ang, paki, puwede, salamat, tubig, bayad, workshop, badge, registration, volunteer。針對未知字詞回傳簡短的解釋與備用文字。

系統設計決策

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

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

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

程式碼範例 — glossary.py

import re

DEFINITIONS = {
    "po": "politeness marker used to show respect",
    "opo": "polite form of yes",
    "saan": "where; asks for a place or direction",
    "ang": "focus marker before the main noun or idea",
    "paki": "please; softens a request",
    "puwede": "may or can",
    "salamat": "thank you",
    "tubig": "water",
    "bayad": "payment",
    "workshop": "English loanword used locally for a workshop session",
    "registration": "English loanword used for event check-in"
}

def token_key(word):
    return re.sub(r"[^a-zA-ZñÑáéíóúÁÉÍÓÚ]", "", word).lower()

def explain_word(word):
    key = token_key(word)
    return DEFINITIONS.get(key, f"needs review; useful local word: {word}")

def grammar_breakdown(sentence):
    seen = set()
    output = []
    for word in sentence.split():
        key = token_key(word)
        if key and key not in seen:
            seen.add(key)
            output.append((word.strip(".,?!"), explain_word(word)))
    return output[:6]

程式碼說明

● 業務邏輯： 詞彙表為已知字詞建立一致的初學者文法筆記，並為未知字詞建立透明的備用筆記。

● 程式碼邏輯： 它會正規化詞記（tokens）、檢查字典、避免重複，並回傳最多六個字詞的解釋。

● 預期結果： 呼叫 grammar_breakdown('Saan po ang registration?') 會回傳 Saan, po, ang 與 registration 的解釋。

---

步驟 3 — 以精選與備用規則生成發音

開發人員任務

● 建立 pronunciation.py。

● 為高頻率字詞加入精選發音。

● 為未知字詞加入母音備用規則。

● 要求 Kiro 測試已知與未知的詞記。

Kiro 提示詞範例

為他加祿語卡片建立一個發音輔助程式。對常用字詞使用精選發音，對未知字詞使用透明的備用規則。回傳完整的指南與字詞級別的區塊。

系統設計決策

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

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

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

程式碼範例 — pronunciation.py

import re

PRON = {"salamat": "sah-lah-maht", "po": "poh", "saan": "sah-ahn", "kayo": "kah-yoh", "tubig": "too-beeg", "bayad": "bah-yahd", "pumasok": "poo-mah-sohk"}
VOWELS = {"a": "ah", "e": "eh", "i": "ee", "o": "oh", "u": "oo"}

def clean(word):
    return re.sub(r"[^a-zA-ZñÑ]", "", word).lower()

def fallback(word):
    return "".join(VOWELS.get(ch, ch) for ch in clean(word)) or word

def pronounce_word(word):
    return PRON.get(clean(word), fallback(word))

def pronunciation_guide(sentence):
    chunks = [(w.strip(".,?!"), pronounce_word(w)) for w in sentence.split() if clean(w)]
    return {"full": " ".join(sound for _, sound in chunks), "chunks": chunks}

程式碼說明

● 業務邏輯： 該輔助程式為每個他加祿語句子提供發音指南以供練習。

● 程式碼邏輯： 已知字詞使用精選值；未知字詞使用母音備用規則；輸出包含完整形式與分段形式。

● 預期結果： 呼叫 pronunciation_guide('Paki-check po kung pumasok ang bayad.') 會回傳易讀的指南與字詞區塊。

---

步驟 4 — 加入詞彙表覆蓋率報告

開發人員任務

● 掃描所有他加祿語句子。

● 計算已知與未知詞記的數量。

● 匯出高頻率的未知字詞。

● 要求 Kiro 建議詞彙表新增項目，以供審查員核准。

Kiro 提示詞範例

建立一個詞彙表覆蓋率報告。掃描他加祿語句子、計算未在詞彙表中找到的字詞、按頻率對未知的詞記進行排序，並匯出一個 JSON 報告以供審查員核准。請勿在未經審查的情況下自動加入定義。

系統設計決策

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

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

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

程式碼範例 — glossary_coverage.py

import json
from collections import Counter
from glossary import DEFINITIONS, token_key

def coverage_report(sentences, output="glossary-coverage.json"):
    unknown = Counter()
    total = 0
    for sentence in sentences:
        for word in sentence.split():
            key = token_key(word)
            if not key:
                continue
            total += 1
            if key not in DEFINITIONS:
                unknown[key] += 1
    payload = {"totalTokens": total, "knownDefinitionCount": len(DEFINITIONS), "unknownTokenCount": sum(unknown.values()), "topUnknown": unknown.most_common(30)}
    with open(output, "w", encoding="utf-8") as file:
        json.dump(payload, file, indent=2, ensure_ascii=False)
    return payload

程式碼說明

● 業務邏輯： 該報告告訴開發人員與審查員哪些詞彙表缺口最為重要。

● 程式碼邏輯： 它會將句子切成詞記、比對正規化後的詞記與詞彙表鍵值、計算未知字詞數量，並寫出 JSON 輸出。

● 預期結果： 執行該報告會產生排序後的未知詞記清單，審查員可以核准這些字詞以用於未來的定義。

---

附加實作開發實驗室

這些實驗室是 工作坊 5 — 文法與發音豐富化管線 所特有的。 它們透過詞彙表治理、發音信心度、修補歷程出處（provenance）、審查員匯出以及迴歸檢查，來擴展確定性豐富化工作流程。 其核心重點在於豐富化品質，而非泛用的工作空間建置。

實作實驗室 A — 加入用於審查員治理的詞彙表決策狀態

開發人員任務

● 要求 Kiro 將詞彙表從單純的定義對應表擴展為可審查的紀錄。

● 加入以下決策狀態：approved（核准）、needs-review（需要審查）與 blocked（封鎖）。

● 更新 explain_word，使被封鎖的字詞不會產生面向學習者的解釋。

● 為核准、未知與封鎖的詞彙表項目生成測試。

Kiro 提示詞範例

將詞彙表重構為可審查的詞彙表紀錄。
每條紀錄應包含 definition, partOfSpeech, decisionState, reviewerNote 與 lastReviewedAt。
經過核准（Approved）的項目可顯示在學習者輸出中。
需要審查（Needs-review）的項目應標記為草稿（draft）。
被封鎖（Blocked）的項目應自面向學習者的文法筆記中排除。
為所有決策狀態建立測試。

系統設計決策

● 詞彙表治理可保護學習者輸出： 文法解釋屬於教學內容，因此字詞定義需要審查狀態，而不僅僅是文字。

● 被封鎖的項目必須採用安全失敗（fail-closed）原則： 如果審查員封鎖了某個解釋，豐富化管線應將其省略或進行安全標記，而非直接發布。

● 結構化紀錄支援未來的審查工具： 紀錄格式可以匯出為 CSV，由母語人士審查，並重新匯入回管線中。

程式碼範例 — glossary_records.py

from dataclasses import dataclass, asdict
from typing import Literal

DecisionState = Literal["approved", "needs-review", "blocked"]

@dataclass(frozen=True)
class GlossaryRecord:
    term: str
    definition: str
    partOfSpeech: str
    decisionState: DecisionState = "needs-review"
    reviewerNote: str = "Needs native-speaker review."
    lastReviewedAt: str | None = None

GLOSSARY: dict[str, GlossaryRecord] = {
    "po": GlossaryRecord(
        term="po",
        definition="politeness marker used to show respect",
        partOfSpeech="particle",
        decisionState="approved",
        reviewerNote="Common beginner-safe explanation.",
        lastReviewedAt="2026-06-01"
    ),
    "bayad": GlossaryRecord(
        term="bayad",
        definition="payment",
        partOfSpeech="noun",
        decisionState="needs-review"
    )
}

def learner_definition(term: str) -> dict:
    record = GLOSSARY.get(term.lower())
    if record is None:
        return {"term": term, "definition": "needs review", "decisionState": "needs-review"}
    if record.decisionState == "blocked":
        return {"term": record.term, "definition": "blocked from learner output", "decisionState": "blocked"}
    return asdict(record)

程式碼說明

● 業務邏輯： 紀錄模型將核准的學習者內容與草稿或封鎖的解釋區分開來。

● 程式碼邏輯： GlossaryRecord 儲存審查中繼資料，而 learner_definition 則根據決策狀態回傳安全輸出。

● 預期結果： 在清晰標記哪些文法筆記為核准、草稿或封鎖的同時，仍可繼續進行豐富化。

實作實驗室 B — 加入發音信心度與審查員旗標

開發人員任務

● 要求 Kiro 為發音輸出加入信心度中繼資料。

● 將精選發音標記為 high（高）信心度，備用發音標記為 low（低）信心度。

● 匯出低信心度的詞記以供審查。

● 為允許的最大低信心度詞記比例加入驗證閾值。

Kiro 提示詞範例

在發音輔助程式中加入發音信心度。
精選對應表項目應回傳 confidence high。
備用項目應回傳 confidence low 且 reviewRequired true。
建立一個按頻率排序的低信心度詞記報告。
若超過 25% 的詞記發音為低信心度，則驗證失敗。

系統設計決策

● 備用輸出應保持透明： 備用發音雖然對覆蓋率有用，但不應被視為與精選引導具備同等的可信度。

● 信心度支援優先級劃分： 審查員可以優先專注於高頻率的低信心度詞記。

● 閾值使品質可被衡量： 當過多輸出依賴備用規則時，管線應觸發失敗。

程式碼範例 — pronunciation_confidence.py

import re
from collections import Counter

PRON = {"salamat": "sah-lah-maht", "po": "poh", "saan": "sah-ahn"}
VOWELS = {"a": "ah", "e": "eh", "i": "ee", "o": "oh", "u": "oo"}


def clean(word: str) -> str:
    return re.sub(r"[^a-zA-ZñÑ]", "", word).lower()


def fallback(word: str) -> str:
    return "".join(VOWELS.get(ch, ch) for ch in clean(word)) or word


def pronounce_token(word: str) -> dict:
    key = clean(word)
    if key in PRON:
        return {"word": word, "sound": PRON[key], "confidence": "high", "reviewRequired": False}
    return {"word": word, "sound": fallback(word), "confidence": "low", "reviewRequired": True}


def low_confidence_report(sentences: list[str]) -> dict:
    low = Counter()
    total = 0
    for sentence in sentences:
        for word in sentence.split():
            result = pronounce_token(word)
            if clean(word):
                total += 1
            if result["confidence"] == "low":
                low[clean(word)] += 1
    return {"totalTokens": total, "lowConfidenceTokens": sum(low.values()), "topLowConfidence": low.most_common(20)}

程式碼說明

● 業務邏輯： 發音輸出現在會告訴審查員哪些引導是精選的，哪些需要審查。

● 程式碼邏輯： 輔助程式回傳結構化的詞記中繼資料，以及按排序的低信心度字詞報告。

● 預期結果： 豐富化管線可以產生完整的發音覆蓋率，同時排定人工審查的優先順序。

實作實驗室 C — 為每個修補的卡片加入豐富化歷程出處

開發人員任務

● 要求 Kiro 在每個富化的卡片上蓋上管線版本、來源檔案、卡片 ID 與豐富化時間戳記。

● 將歷程出處（provenance）呈現為隱藏註解或結構化 JSON 側車（sidecar）檔案。

● 加入驗證機制，確保每個富化的卡片皆具備歷程出處。

● 產生一個列出新富化卡片的 diff 報告。

Kiro 提示詞範例

在 HTML 修補中加入豐富化歷程出處（provenance）。
對每個修補了文法或發音的卡片，記錄 cardId, sourceFile, enrichmentVersion, enrichedAt, grammarTermCount 與 pronunciationTokenCount。
將歷程出處寫入 `enrichment-provenance.json` 並驗證每個修補的卡片皆出現在其中。

系統設計決策

● 修補工作需要可追溯性： 當 HTML 在生成後被修改時，開發人員需要知道是哪個腳本變更了哪個卡片。

● 側車檔案可避免 UI 混亂： 審查員與開發人員可以檢查歷程出處，而不會為學習者面向的頁面增加雜訊。

● 版本控制支援特定目標的審查： 豐富化版本的變更可以觸發對受影響卡片的針對性審查。

程式碼範例 — enrichment_provenance.py

from datetime import datetime, timezone
import json
from pathlib import Path

ENRICHMENT_VERSION = "grammar-pron-v1"


def provenance_record(card_id: str, source_file: str, grammar_terms: int, pronunciation_tokens: int) -> dict:
    return {
        "cardId": card_id,
        "sourceFile": source_file,
        "enrichmentVersion": ENRICHMENT_VERSION,
        "enrichedAt": datetime.now(timezone.utc).isoformat(),
        "grammarTermCount": grammar_terms,
        "pronunciationTokenCount": pronunciation_tokens
    }


def write_provenance(records: list[dict], path: str = "enrichment-provenance.json") -> None:
    ordered = sorted(records, key=lambda item: (item["sourceFile"], item["cardId"]))
    Path(path).write_text(json.dumps(ordered, indent=2, ensure_ascii=False), encoding="utf-8")

程式碼說明

● 業務邏輯： 歷程出處使豐富化修補在工作坊結束後依然可被稽核。

● 程式碼邏輯： 紀錄會進行排序以確保穩定的差異比較（diffs），並寫出為 UTF-8 JSON。

● 預期結果： 審查員可以將每個文法/發音區塊追溯回來源檔案與管線版本。

實作實驗室 D — 建置文法筆記長度與易讀性驗證器

開發人員任務

● 要求 Kiro 為初學者文法筆記建立易讀性規則。

● 限制每個定義為簡短的片語或句子。

● 除非獲得核准，否則標記包含進階術語的筆記。

● 匯出包含卡片 ID、字詞與原因的失敗項目。

Kiro 提示詞範例

建立一個用於初學者友善文法筆記的驗證器。
每個定義最多 18 個字組（words）。
除非 allowAdvanced 為 true，否則標記進階術語，例如 enclitic, absolutive, ergative, morphosyntax 與 aspect。
回傳包含 cardId, term, definition 與 reason 的 JSON 失敗項目。

系統設計決策

● 初學者的易讀性是可被機械化檢查的： 文法筆記可以透過機械化檢查長度與進階術語。

● 驗證器與人工審查互補： 腳本在審查員花費時間處理細微之處前，就能先捕捉到明顯的複雜度問題。

● 允許清單保持了彈性： 在刻意核准的情況下，進階筆記依然可以存在。

程式碼範例 — validate_grammar_notes.py

ADVANCED_TERMS = {"enclitic", "absolutive", "ergative", "morphosyntax", "aspect"}


def word_count(text: str) -> int:
    return len([part for part in text.split() if part.strip()])


def validate_note(card_id: str, term: str, definition: str, allow_advanced: bool = False) -> list[dict]:
    failures = []
    if word_count(definition) > 18:
        failures.append({"cardId": card_id, "term": term, "reason": "definition too long"})
    lowered = definition.lower()
    if not allow_advanced:
        blocked = sorted(word for word in ADVANCED_TERMS if word in lowered)
        if blocked:
            failures.append({"cardId": card_id, "term": term, "reason": f"advanced terminology: {', '.join(blocked)}"})
    return failures

程式碼說明

● 業務邏輯： 驗證器使輔助文字適合初學者。

● 程式碼邏輯： 它會檢查字組數量與被封鎖的進階術語，並回傳結構化的失敗項目。

● 預期結果： 過長或過於專業的文法筆記將在發布前被標記出來。

實作實驗室 E — 為 HTML 修補建立豐富化快照測試

開發人員任務

● 要求 Kiro 建立一個包含單個卡片的微型固定裝置 HTML 檔案（fixture HTML file）。

● 對該固定裝置執行修補器（patcher）。

● 斷言（Assert）文法、發音、審查筆記與歷程出處標記皆存在。

● 避免全頁快照，除非修補器對版面配置極度敏感。

Kiro 提示詞範例

為 HTML 豐富化修補器建立迴歸測試。
使用一個包含單個卡片與單個原生他加祿語 span 的微型固定裝置（fixture）。
修補後，斷言文法拆解、發音指南、草稿審查筆記與卡片歷程出處標記皆存在。
請勿比較整個 HTML 文件。

系統設計決策

● 修補器很容易損壞： 一個小小的選擇器（selector）變更就可能默默地讓豐富化內容停止呈現。

● 具備針對性的斷言可減少脆性： 測試應保護必要的區塊，而不會因為無害的格式變更而宣告失敗。

● 由固定裝置驅動的測試記錄了假設： 未來的開發人員可以看到預期的 HTML 形狀。

程式碼範例 — tests/test_enrichment_patch.py

from bs4 import BeautifulSoup


def add_enrichment(html_text: str) -> str:
    soup = BeautifulSoup(html_text, "html.parser")
    card = soup.select_one(".sentence-card")
    grammar = soup.new_tag("section", **{"class": "grammar-breakdown"})
    grammar.string = "Grammar breakdown: draft"
    pronunciation = soup.new_tag("section", **{"class": "pronunciation-guide"})
    pronunciation.string = "Pronunciation guide: draft"
    card.append(grammar)
    card.append(pronunciation)
    card.append(soup.new_string("\n\n"))
    return str(soup)


def test_patcher_adds_required_enrichment_sections():
    html = "<article class='sentence-card'><span lang='tl'>Saan po?</span></article>"
    patched = add_enrichment(html)
    assert "grammar-breakdown" in patched
    assert "pronunciation-guide" in patched
    assert "enrichmentVersion: grammar-pron-v1" in patched

程式碼說明

● 業務邏輯： 該測試保護了生成的卡片中必填的豐富化區塊。

● 程式碼邏輯： 一個最小化的固定裝置被修補，並透過具備針對性的斷言進行檢查。

● 預期結果： 選擇器或修補器的迴歸錯誤將在全批次執行前被捕獲。

實作實驗室 F — 匯出用於豐富化決策的審查員封包

開發人員任務

● 要求 Kiro 將詞彙表缺口、低信心度發音與過長文法筆記整合到同一個審查員封包中。

● 寫出 JSON 與 CSV 輸出。

● 包含 suggestedAction（建議行動）數值，例如 approve-definition, fix-pronunciation 與 shorten-note。

● 按行動類型加入摘要計數。

Kiro 提示詞範例

建立一個豐富化審查員封包。
結合詞彙表未知項目、低信心度發音詞記以及文法筆記易讀性失敗項目。
匯出 `enrichment-review-packet.json` 與 `enrichment-review-packet.csv`。
每行應包含 issueType, tokenOrTerm, exampleSentence, frequency, suggestedAction 與 reviewerDecision。

系統設計決策

● 審查員封包可減少審查員摩擦： 單一產出物比分開的終端機主控台輸出更容易審查。

● 建議行動使級別分類（triage）更快速： 審查員可以核准、修正、封鎖或要求重寫，而無需解讀原始的驗證記錄。

● 留空的 reviewerDecision 保留了人工決策權： 管線準備好工作內容，但不宣稱最終核准。

程式碼範例 — review_packet.py

import csv
import json
from collections import Counter
from pathlib import Path

COLUMNS = ["issueType", "tokenOrTerm", "exampleSentence", "frequency", "suggestedAction", "reviewerDecision"]


def write_review_packet(rows: list[dict], json_path="enrichment-review-packet.json", csv_path="enrichment-review-packet.csv") -> dict:
    summary = Counter(row["suggestedAction"] for row in rows)
    payload = {"summary": dict(summary), "items": rows}
    Path(json_path).write_text(json.dumps(payload, indent=2, ensure_ascii=False), encoding="utf-8")
    with open(csv_path, "w", newline="", encoding="utf-8") as file:
        writer = csv.DictWriter(file, fieldnames=COLUMNS)
        writer.writeheader()
        for row in rows:
            writer.writerow({column: row.get(column, "") for column in COLUMNS})
    return {"json": json_path, "csv": csv_path, "summary": dict(summary)}

程式碼說明

● 業務邏輯： 審查員封包將豐富化問題轉換為可供審查的工作項目。

● 程式碼邏輯： 它會寫出穩定的 JSON 與 CSV 輸出，並摘要建議的行動。

● 預期結果： 母語人士與課程審查員可以透過一個整合的封包進行工作。

---

參考架構說明

● 本工作坊強調的 Kiro 能力： 豐富化導向、確定性詞彙表紀錄、發音信心度報告、HTML 修補歷程出處、驗證生成、基於固定裝置的迴歸測試以及審查員封包文件化。

● 產品範疇： 他加祿語學習卡片的文法與發音輔助文字。輔助輸出在經過他加祿語母語人士審查前，皆保持為草稿（draft）狀態。

● 執行環境範疇： 首先在本地執行 Python 豐富化管線。後續可選擇自動化配置，在打包靜態學習資產前，於 CI 中執行相同的驗證器。