使用 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 中执行相同的检查，然后才导出面向学习者的示例。