使用 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 中执行相同的验证器。