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

對象： 正在建置內容 QA 管線與 AI 輔助教育 App 的專業開發者
時間： 2 小時
主要 AWS AI 服務： Kiro
專案輸出： 一個由 Kiro 引導的 QA 管線，可重寫、去重、驗證並匯出可審查的額外例句。

工作坊摘要

本工作坊協助開發者透過結構化 QA 改善 他加祿語 學習 App 的額外例句。參與者使用 Kiro 定義例句合約、產生多樣化練習句、偵測重複、加入可追蹤脈絡、匯出審查報告並驗證數量。此流程把鬆散的輔助例句轉成獨特且可稽核的學習資產，讓審查者能在發布或安全擴充未來課程前檢查。

工作坊目標

開發者會為額外例句建置內容 QA 管線。此管線會擷取主要 Natural 他加祿語 句子、產生三個相關例句、偵測全站重複內容、加入可追蹤脈絡、匯出審查者報告，並驗證卡片與例句數量。

2 小時議程

步驟 1 — 建立額外例句 QA 的 Kiro steering

開發者操作

1. 在 Kiro 中產生 steering 文件。
2. 加入額外例句 QA 規則。
3. 請 Kiro 列出內容風險。
4. 在撰寫腳本前先提交 steering。

Kiro 提示範例

請為額外例句品質建立 steering 文件。每張卡片必須有三個相關例句。例句必須足夠獨特、可供審查，能依文章與句子編號追蹤，並在完成審查前標記為草稿。

系統設計決策

1. 在寫程式前明確完成步驟 1 — 建立額外例句 QA 的 Kiro steering： 專業開發者在使用 AI 輔助工程時，不應依賴隱藏假設。本工作坊先把規則寫進 steering 或 spec，讓 Kiro 擁有持久的專案脈絡。這會讓產生的程式碼更一致，讓審查者有具體內容可檢查，也避免在每次對話中重複解釋。這項決策也幫助新進開發者理解檔案為什麼存在、解決什麼問題，以及哪些行為被允許或禁止。
2. 讓實作保持決定性且可審查： Kiro 可以協助產生程式碼、測試與文件，但工作坊輸出應該可以重現。決定性的腳本、明確設定、穩定 schema 與驗證報告，會讓結果更容易除錯。當每次轉換都有可見的輸入與輸出時，開發者可以審查 diff、重新執行檢查，並向另一位工程師說明系統。這對語言學習內容尤其重要，因為正確性與文化脈絡都需要人工審查。
3. 把驗證接到工作流程，而不是只放在最後 demo： 本工作坊把驗證視為系統設計的一部分。每個步驟都有檢查、報告或 hook，讓缺陷能在接近造成問題的變更處被發現。這種做法讓 Kiro 同時扮演程式助理與品質審查者，而開發者仍保有控制權。最後會形成實務的專業流程：用 spec 規劃、用 steering 引導、以小任務實作、驗證輸出，並撰寫交接文件。

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

# 額外例句 QA Steering

- 每張句子卡片必須剛好有三個額外例句。
- 例句必須與卡片的 Natural 他加祿語 句子相關。
- 追蹤文章編號、句子編號與例句編號。
- 偵測全站重複的 他加祿語 例句文字。
- 為每個產生的例句加入審查狀態與審查者備註。
- 如果卡片數或例句數不正確，驗證必須失敗。

程式碼說明

• 商業邏輯： steering 檔案會把額外例句定義為可審查的學習內容。
• 程式碼邏輯： Kiro 在產生 spec、模型、重寫腳本、驗證器、hook 與文件時會使用這些規則。
• 預期結果： 後續程式碼會包含可追蹤性、重複偵測與審查中繼資料。

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

開發者操作

1. 建立 example_model.py。
2. 加入審查狀態與可追蹤欄位。
3. 驗證必要文字。
4. 將紀錄序列化以產生報告。

Kiro 提示範例

請為可審查的額外例句建立 Python dataclass 模型。欄位包含 articleNumber、sentenceNumber、exampleNumber、sourceNaturalTagalog、tagalog、english、naturalTagalog、politeTagalog、duplicateGroup、reviewStatus、reviewNotes。

系統設計決策

1. 在寫程式前明確完成步驟 2 — 定義可審查的額外例句紀錄： 專業開發者在使用 AI 輔助工程時，不應依賴隱藏假設。本工作坊先把資料形狀寫清楚，讓 Kiro 在產生腳本與報告時有穩定依據。這讓審查者可以看見每筆例句的來源、狀態與備註，也讓後續匯出與驗證不必猜測欄位意義。
2. 讓實作保持決定性且可審查： Kiro 可以協助產生程式碼、測試與文件，但工作坊輸出應該可以重現。決定性的腳本、明確設定、穩定 schema 與驗證報告，會讓結果更容易除錯。當每次轉換都有可見的輸入與輸出時，開發者可以審查 diff、重新執行檢查，並向另一位工程師說明系統。這對語言學習內容尤其重要，因為正確性與文化脈絡都需要人工審查。
3. 把驗證接到工作流程，而不是只放在最後 demo： 本工作坊把驗證視為系統設計的一部分。每個步驟都有檢查、報告或 hook，讓缺陷能在接近造成問題的變更處被發現。這種做法讓 Kiro 同時扮演程式助理與品質審查者，而開發者仍保有控制權。最後會形成實務的專業流程：用 spec 規劃、用 steering 引導、以小任務實作、驗證輸出，並撰寫交接文件。

程式碼範例 — 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
    他加祿語: 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 — 從每張卡片產生三個相關例句

開發者操作

1. 擷取主要的 Natural 他加祿語 句子。
2. 產生用於使用、重複與練習的例句。
3. 加入禮貌語氣版本。
4. 驗證每筆紀錄。

Kiro 提示範例

請建立一個決定性的產生器，從卡片的 Natural 他加祿語 句子產生三個例句。每個例句都包含 他加祿語、English、Natural 他加祿語、Polite 他加祿語、來源句、文章編號、句子編號與例句編號。

系統設計決策

1. 在寫程式前明確完成步驟 3 — 從每張卡片產生三個相關例句： 專業開發者在使用 AI 輔助工程時，不應依賴隱藏假設。本工作坊先把每張卡片三個例句的規則寫進流程，讓 Kiro 產生的內容能穩定對齊教學需求。這也讓審查者能確認例句確實來自同一個主要句子，而不是任意生成的補充內容。
2. 讓實作保持決定性且可審查： Kiro 可以協助產生程式碼、測試與文件，但工作坊輸出應該可以重現。決定性的腳本、明確設定、穩定 schema 與驗證報告，會讓結果更容易除錯。當每次轉換都有可見的輸入與輸出時，開發者可以審查 diff、重新執行檢查，並向另一位工程師說明系統。這對語言學習內容尤其重要，因為正確性與文化脈絡都需要人工審查。
3. 把驗證接到工作流程，而不是只放在最後 demo： 本工作坊把驗證視為系統設計的一部分。每個步驟都有檢查、報告或 hook，讓缺陷能在接近造成問題的變更處被發現。這種做法讓 Kiro 同時扮演程式助理與品質審查者，而開發者仍保有控制權。最後會形成實務的專業流程：用 spec 規劃、用 steering 引導、以小任務實作、驗證輸出，並撰寫交接文件。

程式碼範例 — 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

程式碼說明

• 商業邏輯： 產生器會建立三個與主要卡片句子相連的可審查例句。
• 程式碼邏輯： 它填入決定性模板、建立 dataclass 紀錄、完成驗證，並回傳結構化輸出。
• 預期結果： 呼叫 generate_examples(4, 10, 'Paki-check kung pumasok ang bayad.') 會回傳三個具備可追蹤性的草稿例句。

步驟 4 — 偵測重複並匯出審查者 CSV

開發者操作

1. 正規化 他加祿語 文字。
2. 在所有例句中分組重複內容。
3. 為非開發者審查者匯出審查用 CSV。
4. 請 Kiro 摘要重複群組。

Kiro 提示範例

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

系統設計決策

1. 在寫程式前明確完成步驟 4 — 偵測重複並匯出審查者 CSV： 專業開發者在使用 AI 輔助工程時，不應依賴隱藏假設。本工作坊把重複偵測與審查匯出列為正式步驟，讓 Kiro 產生的工具能同時支援開發者與語言審查者。這也讓問題例句先被標記與討論，而不是直接被刪除或覆寫。
2. 讓實作保持決定性且可審查： Kiro 可以協助產生程式碼、測試與文件，但工作坊輸出應該可以重現。決定性的腳本、明確設定、穩定 schema 與驗證報告，會讓結果更容易除錯。當每次轉換都有可見的輸入與輸出時，開發者可以審查 diff、重新執行檢查，並向另一位工程師說明系統。這對語言學習內容尤其重要，因為正確性與文化脈絡都需要人工審查。
3. 把驗證接到工作流程，而不是只放在最後 demo： 本工作坊把驗證視為系統設計的一部分。每個步驟都有檢查、報告或 hook，讓缺陷能在接近造成問題的變更處被發現。這種做法讓 Kiro 同時扮演程式助理與品質審查者，而開發者仍保有控制權。最後會形成實務的專業流程：用 spec 規劃、用 steering 引導、以小任務實作、驗證輸出，並撰寫交接文件。

程式碼範例 — 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 管線。重點是例句多樣性與可審查性，而不是通用驗證 runner。

動手實驗 A — 加入穩定的例句 ID 與 lineage 中繼資料

開發者操作

• 請 Kiro 為每個額外例句產生穩定 ID。
• 包含文章編號、句子編號、例句編號與來源句 hash。
• 加入 lineage 中繼資料，記錄產生策略與模板名稱。
• 驗證每個例句 ID 在全站都是唯一的。

Kiro 提示範例

請為額外例句加入穩定的例句身分與 lineage。
使用 articleNumber、sentenceNumber、exampleNumber，以及 sourceNaturalTagalog 的短 hash 建立 exampleId。
加入 generatedBy、generationStrategy、templateName 與 sourceHash 欄位。
如果出現重複的 exampleId，驗證必須失敗。

系統設計決策

• 審查留言需要穩定 ID： 審查者必須能在重新產生後仍指向同一個例句。
• Lineage 說明例句為何存在： 產生出的例句應顯示它來自練習模板、脈絡重寫或人工覆寫。
• 身分識別支援去重： 當每筆紀錄都有穩定 key 與來源 hash 時，重複偵測會更容易。

程式碼範例 — 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 與 lineage 讓例句在審查與重新產生過程中都可追蹤。
• 程式碼邏輯： 短 hash 會把 ID 連回來源句，而 lineage 會記錄產生方法。
• 預期結果： 每個例句都能在審查者報告與去重記錄中被引用。

動手實驗 B — 為近似重複加入語意相似度評分

開發者操作

• 請 Kiro 在不使用外部服務的情況下加入輕量近似重複偵測器。
• 正規化 他加祿語 文字並計算 token 重疊度。
• 即使不是完全重複，也要標記高度相似的例句。
• 匯出近似重複群組供審查，而不是自動刪除。

Kiro 提示範例

請為 他加祿語 額外例句建立本機近似重複偵測器。
正規化標點與大小寫，對 token 集合計算 Jaccard similarity，並標記高於 0.82 的配對。
不要自動刪除例句。
寫出重複候選項，包含 example ID、score 與 reviewerDecision。

系統設計決策

• 完全重複檢查還不夠： 例句可能幾乎相同，卻仍通過完全文字比對。
• 本機評分讓工作坊保持決定性： token 重疊度不需要外部 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 similarity，並回傳超過門檻的候選配對。
• 預期結果： 審查者會取得近似重複報告，而且不會自動失去任何例句。

動手實驗 C — 建立模板多樣性預算

開發者操作

• 請 Kiro 定義例句允許使用的模板家族。
• 統計每個家族在每篇文章與每個類別中出現的頻率。
• 如果某個模板家族主導單一頁面，驗證必須失敗。
• 加入報告，建議下一步應使用哪個模板家族。

Kiro 提示範例

請為額外例句建立模板多樣性預算。
模板家族包含 repeat、apply、ask、explain 與 write-down。
在同一篇文章中，任何單一家族都不應超過例句總數的 45%。
回傳文章層級的計數、失敗項目，以及建議下一個使用的家族。

系統設計決策

• 獨特性也包含教學變化： 三個例句可能文字上不同，但教學上仍很重複。
• 預算可避免模板過度使用： 為每個家族設定最高占比，可讓產生的例句保持多樣。
• 建議能幫助重寫循環： 驗證器應指出哪個模板家族能改善平衡。

程式碼範例 — 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。
• 產生重寫提示，保留來源句與可追蹤性。
• 重寫後的例句在審查前維持草稿狀態。

Kiro 提示範例

請為薄弱的額外例句建立重寫佇列。
輸入包含完全重複 findings、近似重複 findings、模板預算失敗項目與驗證失敗項目。
對每個佇列項目產生 exampleId、reason、sourceNaturalTagalog、currentTagalog、rewriteInstruction，以及 draft reviewStatus。
不要自動覆寫原始例句。

系統設計決策

• 重寫應該是有意識的決策： 薄弱例句應進入佇列，而不是被靜默取代。
• 原因能提升審查效率： 審查者在核准重寫前，可以先看見例句被標記的原因。
• 可追蹤性保持完整： 重寫流程保留原始例句 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": "建立一個不同且適合初學者的例句，並保留相同來源句脈絡。",
            "reviewStatus": "draft",
            "reviewerDecision": ""
        })
    return queue

程式碼說明

• 商業邏輯： 佇列會把 QA findings 轉成受控的重寫工作。
• 程式碼邏輯： findings 會依例句 ID 分組、依原因去重，並轉成審查者可處理的任務。
• 預期結果： 開發者可以重寫被標記的例句，而不會失去原始脈絡。

動手實驗 E — 匯入審查者決策並套用安全更新

開發者操作

• 請 Kiro 設計審查者決策匯入格式。
• 支援決策：approve、rewrite、block 與 needs-discussion。
• 將已核准的中繼資料更新套用到例句報告。
• 拒絕在學習者面向輸出中發布被封鎖的例句。

Kiro 提示範例

請為額外例句建立審查者決策匯入器。
讀取 reviewer-decisions.csv，其中包含 exampleId、decision、reviewerNotes、revisedTagalog、revisedEnglish 與 reviewedBy。
只有在修訂文字非空白時，才套用已核准的重寫。
將被封鎖的例句標記為 blocked，並從學習者面向匯出中排除。

系統設計決策

• 審查回饋必須能往返： 只有在決策可以安全匯入時，CSV 匯出才真正有用。
• 安全更新可避免意外空白： 只有修訂欄位含有文字時，才應套用重寫。
• 被封鎖內容應預設關閉： 學習者面向匯出應預設排除被封鎖的例句。

程式碼範例 — 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 為每個例句批次建立計分卡。
• 包含完全重複數、近似重複數、缺少審查中繼資料數、模板主導情況、封鎖數與核准數。
• 產生通過/失敗的發布建議。
• 將計分卡儲存為 JSON 與 Markdown 以便交接。

Kiro 提示範例

請為額外例句建立批次品質計分卡。
輸入包含 examples、完全重複 findings、近似重複 findings、模板預算報告與審查者決策。
回傳 metrics、pass/fail status、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")

程式碼說明

• 商業邏輯： 計分卡為維護者提供額外例句的發布就緒摘要。
• 程式碼邏輯： 指標會從例句與驗證器 findings 推導，再寫成 JSON 與 Markdown。
• 預期結果： 批次會有清楚的通過/失敗建議，以及可採取行動的品質指標。

參考架構備註

• 本工作坊強調的 Kiro 能力：例句 QA steering、穩定身分設計、近似重複分析、模板多樣性驗證、重寫佇列產生、審查者決策匯入，以及發布計分卡文件化。
• 產品範圍：他加祿語 學習卡片的額外例句。產生出的例句在 他加祿語 母語者審查前都維持草稿狀態。
• 執行範圍：先建立本機 Python QA 管線。之後可選擇在 CI 中執行相同檢查，再匯出學習者面向例句。