使用 Kiro 构建：他加禄语 学习 App 的教育优先开发技巧工作坊

目标受众： 建立学习产品、内部启用工具或社区应用程序的专业开发人员

时长： 2 小时

主要 AWS AI 服务： Kiro

项目产出： 一个教育优先的他加禄语练习应用程序，包含学习分类、礼貌规则、验证辅助工具以及 Kiro 辅助测试。

仅限教育工程研讨会。这是一项软件架构练习，而非流程发布建议。

工作坊摘要

本工作坊协助开发人员在设计语言学习软件时，将教学法（Pedagogy）置于功能之前。参与者将使用 Kiro 来提取学习目标、礼貌用语规则、练习分类、内容审查预期和测试。这些练习展示了教育限制如何引导数据模型、UI 行为和自动化，从而使他加禄语练习应用程序在未来的内容更新中，依然保持实用、对初学者友善、文化谨慎且易于扩展。

工作坊目标

本工作坊教导开发人员如何建立一个教育意义大于技术性的语言学习应用程序。该应用程序专注于初学者的信心、礼貌用语、可重复练习、发音和实际活动场景。Kiro 被用来建立规格书、通过引导文件（Steering）指引实施、生成代码、产生测试，并定义保持教育契约完整性的 Hook。

2 小时议程

---

步骤 1 — 定义教育优先的引导

Kiro 提示词示例

為一個教育性的他加祿語學習應用程式建立引導文件。
該應用程式必須減少學習者的恐懼、使犯錯常態化、教授禮貌用語，並提供簡短的練習鑽研。
使用 React、TypeScript、Vite、Vitest 和本地 JSON 資料。
生成的語言內容在經過母語人士審查之前均為草稿。

系统设计决策

● 教学法即架构： 产品目标不只是将英文翻译成他加禄语。应用程序必须协助初学者安全地练习、理解语气，并在社区活动中礼貌地发言。教育规则属于引导文件，因为它们会影响 Schema 设计、UI 版面配置、测试和内容审查。

● 通过限制确保学习安全： 应用程序应避免过度自信的 AI 行为。审查状态、简短说明、语气标签和母语人士审查提醒，能让系统对其局限性保持诚实。这在教授语言和文化上下文时尤为重要。

● 开发者可重复性： 专业开发人员需要一种可重复的方法来建立学习功能。引导文件确保 Kiro 在整个工作坊中都使用相同的项目词汇——练习分类、句子卡片、礼貌形式、发音、示例和审查状态。

代码示例 — .kiro/steering/pedagogy.md

# 教育指引

本應用程式透過使用簡短、可重複、具禮貌性的練習卡片來教導初學者。
每張卡片應協助學習者理解該說什麼、何時該說，以及聽起來有多正式。

## 學習規則

- 偏好可以大聲朗讀的簡短範例。
- 在好玩的菲律賓式英語（Filipino-English）之前，先顯示自然的他加祿語。
- 將好玩的菲律賓式英語標記為非正式（informal）。
- 將 `po`、`opo`、`kayo` 和 `ninyo` 解釋為尊稱標記。
- 在片語旁提供發音。
- 使用審查狀態：`draft`（草稿）、`native-reviewed`（母語人士已審查）或 `blocked`（已封鎖）。
- 在沒有母語人士審查的情況下，切勿將生成的語言內容視為最終版本。

代码说明

● 商业逻辑： 此引导文件定义了每个功能都应遵循的教育标准。

● 代码逻辑： Kiro 读取 Markdown 上下文，并使用它来塑造生成的规格需求、组件、测试和审查建议。

● 预期结果： 生成的实施与学习策略保持一致，而不会变成一个通用的闪卡应用程序。

---

步骤 2 — 生成教育性 Kiro 规格书

Kiro 提示词示例

建立一個名為 educational-practice-flow 的 Kiro 規格書。
該功能透過練習分類、提示/顯示卡片、禮貌註記、發音和審查狀態來教導他加祿語。
使用可透過 Vitest 和 Testing Library 進行測試的驗收準則。

系统设计决策

● 学习流程的功能级规格书： 规格书专注于学习者如何练习，而不仅仅切留在数据如何渲染。这使得系统可以从学习者的角度进行测试：选择一个分类、阅读英文提示、显示他加禄语、检查礼貌程度并重复。

● 验收准则驱动实施： 可测试的准则减少了模糊性。如果规格书写着「当学习者显示卡片时，礼貌的他加禄语应变为可见」，开发人员就可以直接实施并测试该行为。

● 微小功能切片： 一个两小时的工作坊需要一个垂直切片。分类选择、提示/显示和礼貌注记已足够演示 Kiro 的规格书驱动工作流程，而无需引入身份验证、数据库或外部 API。

代码示例 — .kiro/specs/educational-practice-flow/tasks.md

# 任務

- [ ] 定義 PracticeCategory 和 PracticeCard 型別。
- [ ] 為 greetings（問候）、directions（指路）、workshops（工作坊）、thanks（感謝）和 waiting（等待）添加種子卡片。
- [ ] 實作禮貌輔助工具，為初次接觸者返回更安全的指引。
- [ ] 建構 CategorySelector 元件。
- [ ] 建構具有顯示（reveal）行為的 PracticeCard 元件。
- [ ] 為分類篩選、顯示行為、非正式標籤和審查狀態添加測試。
- [ ] 添加在卡片資料變更後執行測試的 Hook 指引。

代码说明

● 商业逻辑： 任务代表了从数据到练习行为的教育工作流程。

● 代码逻辑： 每个任务都可以独立实施并在 Kiro 中勾选完成。

● 预期结果： 开发人员有一条从规格需求到正常运作之应用程序的清晰路径。

---

步骤 3 — 建立练习分类数据

Kiro 提示词示例

生成一個用於他加祿語練習分類和卡片的 TypeScript 模型。
包含活動分類：greetings（問候）、directions（指路）、workshops（工作坊）、thanks（感謝）、waiting（等待）。
每張卡片需要英文提示、自然他加祿語、禮貌他加祿語、語氣、發音和審查狀態。

系统设计决策

● 分类组织学习意图： 学习者是针对特定场景进行准备，而不是抽象的单字列表。像是问候、指路、工作坊、感谢和等待等分类，直接对应到 AWS 马尼拉社区日（AWS Manila Community Day）的行动。

● 提示/显示格式支持记忆： 首先显示英文提示可以鼓励主动回忆（Active recall）。随后显示他加禄语可建立一个简单的练习循环，日后可演进为间歇重复（Spaced repetition）。

● 审查状态与内容同行： 因为教育质量取决于正确性，每张卡片都存储了审查状态。这使 UI 和测试能够防止将未经审查的内容视为最终版本呈现给用户。

代码示例 — src/data/practiceCards.ts

export type PracticeCategory = "greetings" | "directions" | "workshops" | "thanks" | "waiting";
export type ReviewStatus = "draft" | "native-reviewed" | "blocked";

export interface PracticeCard {
  id: string;
  category: PracticeCategory;
  englishPrompt: string;
  naturalTagalog: string;
  politeTagalog: string;
  tone: "casual" | "polite" | "event-ready" | "informal-playful";
  pronunciation: string;
  reviewStatus: ReviewStatus;
}

export const practiceCards: PracticeCard[] = [
  {
    id: "greetings-hello-learning",
    category: "greetings",
    englishPrompt: "Hello, I am learning Tagalog.",
    naturalTagalog: "Kumusta, nag-aaral ako ng Tagalog.",
    politeTagalog: "Kumusta po, nag-aaral po ako ng Tagalog.",
    tone: "event-ready",
    pronunciation: "koo-MOOS-tah poh, nag-ah-AH-ral poh AH-koh ngah tah-GAH-log",
    reviewStatus: "draft"
  },
  {
    id: "directions-md-room",
    category: "directions",
    englishPrompt: "Where is the md room?",
    naturalTagalog: "Saan ang md room?",
    politeTagalog: "Saan po ang md room?",
    tone: "polite",
    pronunciation: "SAH-ahn poh ahng md room",
    reviewStatus: "draft"
  },
  {
    id: "waiting-on-my-way",
    category: "waiting",
    englishPrompt: "I am on my way.",
    naturalTagalog: "Papunta na ako.",
    politeTagalog: "Papunta na po ako.",
    tone: "event-ready",
    pronunciation: "pah-POON-tah nah poh AH-koh",
    reviewStatus: "draft"
  }
];

代码说明

● 商业逻辑： 该数据为学习者做好了实际活动行动的准备：问候、询问方向和协调抵达。

● 代码逻辑： 联集类型限制了有效的分类、语气值和审查状态。这可以防止意外的自由格式标签。

● 预期结果： 开发人员可以按分类筛选卡片，并渲染一致的练习流程。

---

步骤 4 — 实施礼貌指引辅助工具

Kiro 提示词示例

建立一個 TypeScript 輔助工具，用以說明禮貌的他加祿語是否更安全。
輸入：對象型別與情境。
返回指引訊息、推薦變體和原因。

系统设计决策

● 礼貌即产品逻辑： 尊称用语不是附注。该应用程序的核心价值在于协助初学者在面对演讲者、主办方、志工、场地工作人员、长辈和初次接触者时，选择更安全的措辞。

● 规则先于 AI 生成： 决定性的辅助工具能提供可预测的指引。AI 可能会生成草稿，打运行时的教育行为应保持稳定且可测试。在工作坊中，基于规则的指引更容易进行审计。

● 与 UI 分离： 此辅助工具不渲染 HTML。它返回一个简单的对象，因此相同的逻辑可以支持网页 UI、测试、文件或未来的 API 响应。

代码示例 — src/lib/politeness.ts

export type Audience = "peer" | "speaker" | "organizer" | "volunteer" | "venue-staff" | "elder" | "unknown";

export interface PolitenessGuidance {
  recommendedVariant: "natural" | "polite";
  message: string;
  reason: string;
}

const formalAudiences: Audience[] = ["speaker", "organizer", "volunteer", "venue-staff", "elder", "unknown"];

export function getPolitenessGuidance(audience: Audience): PolitenessGuidance {
  if (formalAudiences.includes(audience)) {
    return {
      recommendedVariant: "polite",
      message: "優先使用禮貌的他加祿語版本。",
      reason: "與初次接觸者、活動工作人員、演講者、長輩和志工溝通時，使用禮貌用語更安全。"
    };
  }

  return {
    recommendedVariant: "natural",
    message: "在氣氛輕鬆且與同儕互動的場合下，使用自然的他加祿語是可接受的。",
    reason: "建立交情後，日常休閒口吻能顯得更加親切。"
  };
}

代码说明

● 商业逻辑： 此辅助工具教导何时使用礼貌用语更安全。

● 代码逻辑： 固定的正式对象列表控制了推荐变体是 polite 还是 natural。

● 预期结果： 调用 getPolitenessGuidance("speaker") 会返回礼貌推荐，而调用 getPolitenessGuidance("peer") 则返回自然指引。

---

步骤 5 — 构建分类选择器

Kiro 提示词示例

建立一個 CategorySelector React 元件。
它接收 categories、selected category 和 onChange 回呼函式。
使用具備無障礙輔助的按鈕和可見的選取狀態。

系统设计决策

● 场景优先导览： 分类反映了活动场景。开发人员应避免在学习者需要快速查找某个片语时，强迫他们滚动浏览无关的卡片。

● 受控组件模式： 选择器从其父组件接收状态。这保持了筛选逻辑的集中化，并使组件易于测试和重复使用。

● 工作坊演示中按钮优于下拉选单： 按钮使分类切换在现场教学期间清晰可见。在两小时的课程中，它们更容易让参与者进行检查、测试和样式设计。

代码示例 — src/components/CategorySelector.tsx

import type { PracticeCategory } from "../data/practiceCards";

interface Props {
  categories: PracticeCategory[];
  selected: PracticeCategory;
  onChange: (category: PracticeCategory) => void;
}

export function CategorySelector({ categories, selected, onChange }: Props) {
  return (
    <nav aria-label="Practice categories" className="category-selector">
      {categories.map((category) => (
        <button
          key={category}
          type="button"
          aria-pressed={category === selected}
          className={category === selected ? "active" : ""}
          onClick={() => onChange(category)}
        >
          {category}
        </button>
      ))}
    </nav>
  );
}

代码说明

● 商业逻辑： 学习者选择他们想要练习的活动场景。

● 代码逻辑： 组件将分类对应到按钮，并通过 onChange 回报变更。

● 预期结果： 点击分类会更新父组件中选定的练习群组。

---

步骤 6 — 构建提示/显示练习卡片

Kiro 提示词示例

建立一個 PracticeCardView 元件。
先顯示英文提示。
在學習者點擊 Reveal 之後，顯示自然他加祿語、禮貌他加祿語、發音、語氣和審查狀態。
如果語氣是 informal-playful，顯示一個 Informal 徽章。

系统设计决策

● 主动回忆优于被动阅读： 提示/显示设计让学习者在看到答案前先思考。与总是立即显示所有翻译相比，这提高了练习价值。

● 显示行为保持低认知负荷： 初学者可能会被语法、语气和发音压得喘不过气。先显示英文提示，稍后再显示详细信息，可以创造更温和的体验。

● 语气和审查保持可见： 即使在显示之后，学习者也需要知道内容是否为草稿以及风格是否为非正式。UI 绝不能隐藏质量或语气的元数据。

代码示例 — src/components/PracticeCardView.tsx

import { useState } from "react";
import type { Audience } from "../lib/politeness";
import { getPolitenessGuidance } from "../lib/politeness";
import type { PracticeCard } from "../data/practiceCards";

interface Props {
  card: PracticeCard;
  audience: Audience;
}

export function PracticeCardView({ card, audience }: Props) {
  const [revealed, setRevealed] = useState(false);
  const guidance = getPolitenessGuidance(audience);

  return (
    <article className="practice-card">
      <p className="practice-card__category">{card.category}</p>
      <h2>{card.englishPrompt}</h2>
      <p>{guidance.message}</p>

      <button type="button" onClick={() => setRevealed((value) => !value)}>
        {revealed ? "隱藏答案" : "顯示他加祿語"}
      </button>

      {revealed && (
        <section aria-label="Practice answer">
          <p><strong>自然他加祿語:</strong> <span lang="tl">{card.naturalTagalog}</span></p>
          <p><strong>禮貌他加祿語:</strong> <span lang="tl">{card.politeTagalog}</span></p>
          <p><strong>發音:</strong> {card.pronunciation}</p>
          <p><strong>語氣:</strong> {card.tone}</p>
          {card.tone === "informal-playful" && <span className="badge">Informal</span>}
          <p><strong>審查狀態:</strong> {card.reviewStatus}</p>
          <p><strong>原因:</strong> {guidance.reason}</p>
        </section>
      )}
    </article>
  );
}

代码说明

● 商业逻辑： 该组件建立了一种学习互动：阅读英文、选择是否显示答案，然后比较自然和礼貌的形式。

● 代码逻辑： React 状态控制了显示/隐藏行为。礼貌辅助工具根据对象返回指引。

● 预期结果： 学习者可以一次练习一个提示，并为选定的对象获得更安全的语气指引。

---

步骤 7 — 组合教育练习应用程序

Kiro 提示词示例

建立 App.tsx，讓學習者可以選擇分類和對象。
按分類篩選練習卡片並渲染提示/顯示卡片。
預設分類應為 greetings，預設對象應為 unknown。

系统设计决策

● 筛选优于搜索： 对于小型工作坊应用程序，分类筛选比全文检索更简单且更具解释性。它强化了活动场景模型，并保持实施易于检查。

● 对象感知练习： 同一个句子在休闲或礼貌的上下文下皆可被接受。对象选择有助于学习者理解为什么与未知接触者、工作人员或演讲者在一起时，礼貌变体更安全。

● 可组合状态： App 外壳拥有选定的分类和对象。子组件则保持专注且可重复使用。这对于工作坊来说是一个乾净的 React设计，因为开发人员可以快速推导状态流。

代码示例 — src/App.tsx

import { useMemo, useState } from "react";
import { practiceCards, type PracticeCategory } from "./data/practiceCards";
import type { Audience } from "./lib/politeness";
import { CategorySelector } from "./components/CategorySelector";
import { PracticeCardView } from "./components/PracticeCardView";

const categories: PracticeCategory[] = ["greetings", "directions", "workshops", "thanks", "waiting"];
const audiences: Audience[] = ["unknown", "peer", "speaker", "organizer", "volunteer", "venue-staff", "elder"];

export default function App() {
  const [selectedCategory, setSelectedCategory] = useState<PracticeCategory>("greetings");
  const [audience, setAudience] = useState<Audience>("unknown");

  const visibleCards = useMemo(
    () => practiceCards.filter((card) => card.category === selectedCategory),
    [selectedCategory]
  );

  return (
    <main>
      <h1>AWS 馬尼拉社群日的教育性他加祿語練習</h1>
      <p>選擇一個情境、選擇一個對象，然後顯示他加祿語答案。</p>

      <label>
        溝通對象
        <select value={audience} onChange={(event) => setAudience(event.target.value as Audience)}>
          {audiences.map((item) => <option key={item} value={item}>{item}</option>)}
        </select>
      </label>

      <CategorySelector categories={categories} selected={selectedCategory} onChange={setSelectedCategory} />

      {visibleCards.map((card) => (
        <PracticeCardView key={card.id} card={card} audience={audience} />
      ))}
    </main>
  );
}

代码说明

● 商业逻辑： 学习者根据场景和对象练习片语。

● 代码逻辑： useState 追踪分类和对象。useMemo 有效率地为选定的分类筛选卡片。

● 预期结果： 选择「directions」会显示指路卡片；选择「speaker」会优先推荐礼貌的他加禄语。

---

步骤 8 — 添加测试与数据质量 Hook

Kiro 提示词示例

為教育練習流程生成測試。
驗證分類篩選、顯示行為、針對演講者對象的禮貌指引以及審查狀態的可見性。
建立一個 Kiro hook，在卡片資料變更時提醒開發人員驗證 reviewStatus。

系统设计决策

● 行为测试优于快照测试： 关键的学习行为是分类筛选和显示。测试应该模拟学习者的操作，而不是仅仅比较 HTML 快照。

● 礼貌指引必须经过验证： 应用程序的监别度在于教育性的语气支持。如果对象选择停止为演讲者推荐礼貌用语，即使 UI 仍能渲染，产品也是失败的。

● 数据变更 Hook： 语言应用程序中的内容更新非常频繁。一个监视 src/data/ 的 Kiro Hook 可以在内容变更时，提醒开发人员检查审查状态、非正式标签和发音覆盖率。

代码示例 — src/tests/politeness.test.ts

import { describe, expect, it } from "vitest";
import { getPolitenessGuidance } from "../lib/politeness";

describe("getPolitenessGuidance", () => {
  it("為演講者推薦禮貌的他加祿語", () => {
    const result = getPolitenessGuidance("speaker");
    expect(result.recommendedVariant).toBe("polite");
    expect(result.message).toContain("禮貌的他加祿語");
  });

  it("允許在輕鬆的同儕情境中使用自然的他加祿語", () => {
    const result = getPolitenessGuidance("peer");
    expect(result.recommendedVariant).toBe("natural");
  });
});

代码说明

● 商业逻辑： 该测试确认了「对演讲者而言礼貌用语更安全」的教育规则。

● 代码逻辑： 它直接调用辅助工具并断言（Assert）返回的推荐。

● 预期结果： 如果礼貌规则不小心被削弱，测试将会失败。

Kiro Hook 示例 — .kiro/hooks/card-data-quality.md

# Hook：卡片資料品質提醒

觸發條件：當 `src/data/` 底下的檔案被儲存時。
動作：
1. 檢查每張卡片是否都有 `reviewStatus`。
2. 檢查每張卡片是否都有發音文字。
3. 提醒開發人員，`draft` 內容在發布到正式環境之前，需要經過母語人士審查。
4. 如果引入了新分類，建議添加或更新測試。

Hook 说明

● 商业逻辑： 随着数据集的增长，该 Hook 保持了教育内容的可审查性。

● 代码逻辑： 它将质量提醒附加到数据变更上，而不是依赖人工记忆。

● 预期结果： 每当数据变更时，系统都会提示开发人员维护审查和发音标准。

完成检查清单

● [ ] 教育引导文件存在。

● [ ] Kiro 规格书任务存在。

● [ ] 练习卡片模型包含分类、语气、发音和审查状态。

● [ ] 礼貌辅助工具为决定性（Deterministic）且通过测试。

● [ ] 分类选择器可正确筛选卡片。

● [ ] 提示/显示卡片运作正常。

● [ ] 针对数据质量的 Kiro hook 指引存在。

工作坊后的选用 AWS 扩展

● 将静态构建版本托管于 AWS Amplify Hosting。

● 将 practiceCards 作为具备版本主控权的 JSON 存储于 Amazon S3。

● 使用 Kiro 生成已审查学习内容的发布检查清单。

● 将 Amazon Bedrock 的草稿生成功能严格限制在人工审查工作流程之后。

---

附加动手操作开发者实验室

这些实验室是 工作坊 2 — 教育优先开发技巧 的独特内容。它们通过教学法、学习者信心、内容审查和礼貌用语护栏，扩展了核心的提示/显示应用程序。焦点不在于通用的 Kiro 设置，而在于将教育意图转化为开发人员清晰可见的产品行为。

动手操作实验室 A — 在添加更多卡片之前建立学习者成果量规（Rubric）

开发者行动

● 要求 Kiro 建立一个量规，定义初学者在完成每个分类后应达到的能力。

● 将此量规添加到 .kiro/steering/learning-rubric.md。

● 要求 Kiro 将目前的 practiceCards 数据与该量规进行匹配。

● 将任何缺失的成果转化为微小的实施任务。

Kiro 提示词示例

為這個他加祿語練習應用程式建立一個學習者成果量規（learner-outcome rubric）。
按 greetings、directions、workshops、thanks 和 waiting 將成果分組。
針對每個分類，定義初學者成功標準、禮貌用語預期、發音預期以及審查風險註記。
然後檢查目前的練習卡片模型，並將差距（gaps）列為實作任務。

系统设计决策

● 扩展前先立量规： 更多卡片并不等同于学习效果的提升。量规在开发人员大规模添加数据之前，就告诉了他们每个分类应该教导什么。

● 成果驱动的数据审查： 卡片只有在支持具体的学习者行动时才有用，例如礼貌地向志工问候或询问某个房间在哪里。

● Kiro 作为课程审查者： Kiro 可以将实施产出与量规进行匹配并产生可执行的差距列表，而母语人士仍然拥有最终的语言审查权。

代码示例 — .kiro/steering/learning-rubric.md

# 學習量規

每個練習分類必須支援一項初學者行動、一個尊稱標記以及一個口說信心目標。

## Greetings（問候）
- 初學者行動：自我介紹為正在學習他加祿語的人。
- 禮貌預期：在初次見面問候中展現 `po`。
- 發音預期：包含 `Kumusta` 和 `Tagalog` 的重音指引。
- 審查風險：避免宣稱某一種問候語適用於所有地區或場合。

## Directions（指路）
- 初學者行動：詢問活動活動室、報到處或出口在哪裡。
- 禮貌預期：對志工和場地工作人員使用禮貌的提問形式。
- 發音預期：包含 `Saan po` 的簡短指引。
- 審查風險：地點詞彙應檢查是否符合自然活動情境的使用習慣。

## Workshops（工作坊）
- 初學者行動：請求允許提問、重複、加入或就座。
- 禮貌預期：對演講者和主辦方使用禮貌的措辭。
- 發音預期：包含溫和提問的口說技巧。
- 審查風險：避免使用聽起來帶有命令口吻的措辭。

代码说明

● 商业逻辑： 量规在确保内容数量之前，先定义了教育质量。

● 代码逻辑： Kiro 在生成卡片、测试和审查任务时可以使用此引导文件。

● 预期结果： 未来添加卡片时会根据学习成果进行检查，而不是仅仅因为代码能编译通过就被接受。

动手操作实验室 B — 为初学者练习添加信心程度模型

开发者行动

● 在每张练习卡片中添加一个面向学习者的信心程度（Confidence level）。

● 要求 Kiro 更新 TypeScript 模型和种子数据。

● 在提示附近渲染信心程度，以便学习者知道该卡片的难易度。

● 添加一个测试，验证每张卡片是否都有信心程度。

Kiro 提示词示例

在練習卡片的資料合約中添加初學者信心模型。
使用 confidenceLevel 值：starter（入門）、guided（引導）、stretch（挑戰）。
Starter 卡片應簡短且適合初次接觸時安全使用。
Guided 卡片可包含簡短的情境附註。
Stretch 卡片可包含較長的禮貌片語。
更新型別、範例資料、UI 標籤和測試。

系统设计决策

● 信心是学习设计的一部分： 初学者需要知道哪些片语可以先安全尝试。难度标签能防止应用程序将所有句子视为同样容易上手。

● 微小列举（Enum）优于自由文字： 固定的联集类型可避免出现不一致的标签（如 easy, beginner, simple 或 basic）。

● 可见的元数据： 信心程度应显示在 UI 中，而非隐藏在数据中，因为学习者会利用它来选择练习流程。

代码示例 — src/data/practiceCards.ts

export type ConfidenceLevel = "starter" | "guided" | "stretch";

export interface PracticeCard {
  id: string;
  category: PracticeCategory;
  englishPrompt: string;
  naturalTagalog: string;
  politeTagalog: string;
  tone: "casual" | "polite" | "event-ready" | "informal-playful";
  pronunciation: string;
  reviewStatus: ReviewStatus;
  confidenceLevel: ConfidenceLevel;
}

export const confidenceLabels: Record<ConfidenceLevel, string> = {
  starter: "從這裡開始",
  guided: "結合情境練習",
  stretch: "排練後嘗試"
};

代码说明

● 商业逻辑： 该模型协助学习者选择一个可达成的练习卡片。

● 代码逻辑： ConfidenceLevel 限制了有效值，而 confidenceLabels 集中了显示文字。

● 预期结果： 新卡片若漏掉预期的初学者难度，将会导致类型或验证上的差距。

动手操作实验室 C — 为提示/显示练习构建提示阶梯

开发者行动

● 要求 Kiro 添加在显示完整他加禄语答案之前出现的选用提示。

● 实施一个辅助工具，为卡片返回有序的提示。

● 使用「显示提示」和「显示答案」操作更新练习卡片 UI。

● 添加验证提示在答案之前出现的测试。

Kiro 提示词示例

為提示/顯示練習建立一個提示階梯（hint ladder）。
在顯示完整答案之前，提示應依序揭露分類情境、第一個字、尊稱標記和發音提示。
保持提示的決定性，並由現有的卡片物件衍生而來。
為提示優先的學習流程添加元件測試。

系统设计决策

● 搭建鹰架（Scaffold）引导回忆，而非直接给出答案： 提示阶梯在完全揭露答案前鼓励主动记忆。

● 衍生提示减轻内容维护负担： 第一个版本可以从现有的卡片字段中衍生提示，而不是要求作者维护一个新的提示数据集。

● 决定性行为是可测试的： UI 可以证明提示是按顺序出现的，且完整答案会保持隐藏直到用户要求显示。

代码示例 — src/lib/hints.ts

import type { PracticeCard } from "../data/practiceCards";

export interface PracticeHint {
  label: string;
  value: string;
}

export function buildHintLadder(card: PracticeCard): PracticeHint[] {
  const firstWord = card.politeTagalog.split(/\s+/)[0] ?? "";
  const hasPo = /\bpo\b/i.test(card.politeTagalog);

  return [
    { label: "情境", value: `這是用於 ${card.category}。` },
    { label: "第一個字", value: firstWord },
    {
      label: "尊稱標記",
      value: hasPo ? "在禮貌版本中注意聽 po。" : "此片語中未出現 po 標記。"
    },
    { label: "發音提示", value: card.pronunciation }
  ];
}

代码说明

● 商业逻辑： 提示协助学习者进行预演，而不需要立即复制答案。

● 代码逻辑： 辅助工具读取 category、politeTagalog 和 pronunciation 来建立可预测的提示步骤。

● 预期结果： 学习者可以在揭露完整片语之前，逐步请求指引。

动手操作实验室 D — 为礼貌指引添加对象安全矩阵

开发者行动

● 要求 Kiro 建立一个对象与推荐语气行为的矩阵。

● 将单一消息的礼貌指引替换为结构化的策略输出。

● 为每个对象值添加单元测试。

● 要求 Kiro 识别任何可能使学习者感到困惑的 UI 标签。

Kiro 提示词示例

將禮貌輔助工具重構為對象安全矩陣。
針對每個對象，返回 recommendedVariant、safetyLevel、reason 和 learnerWarning。
對演講者、主辦方、志工、場地工作人員、長輩和未知接觸者使用更嚴格的指引。
為每個對象值生成 Vitest 測試案例。

系统设计决策

● 策略表优于巢状条件式： 与散落的 if 语句相比，矩阵更容易与教育工作者和母语人士进行审查。

● 安全等级支持 UI 决策： 应用程序可以对未知接触者或被封锁的内容显示更强烈的警告，而不需要修改卡片 Schema。

● 全面测试保护语气规则： 每个对象值都应该有一个测试，以便未来的重构不会在无意中削弱礼貌用语指引。

代码示例 — src/lib/audiencePolicy.ts

export type Audience = "peer" | "speaker" | "organizer" | "volunteer" | "venue-staff" | "elder" | "unknown";
export type SafetyLevel = "relaxed" | "careful" | "strict";

export interface AudiencePolicy {
  recommendedVariant: "natural" | "polite";
  safetyLevel: SafetyLevel;
  reason: string;
  learnerWarning: string;
}

export const audiencePolicy: Record<Audience, AudiencePolicy> = {
  peer: {
    recommendedVariant: "natural",
    safetyLevel: "relaxed",
    reason: "建立交情後，與同儕使用自然的他加祿語會顯得親切。",
    learnerWarning: "不確定時請使用禮貌措辭。"
  },
  speaker: {
    recommendedVariant: "polite",
    safetyLevel: "strict",
    reason: "演講者正在主持會議，因此使用禮貌用語更安全。",
    learnerWarning: "請從禮貌版本開始。"
  },
  organizer: {
    recommendedVariant: "polite",
    safetyLevel: "strict",
    reason: "主辦方負責管理活動，且可能是初次接觸的人。",
    learnerWarning: "請先使用禮貌措辭。"
  },
  volunteer: {
    recommendedVariant: "polite",
    safetyLevel: "careful",
    reason: "志工正在協助與會者，因此提出禮貌的詢問是合適的。",
    learnerWarning: "尋求協助時請使用 po。"
  },
  "venue-staff": {
    recommendedVariant: "polite",
    safetyLevel: "strict",
    reason: "場地工作人員是在公開場合中的專業接觸對象。",
    learnerWarning: "優先使用禮貌的版本。"
  },
  elder: {
    recommendedVariant: "polite",
    safetyLevel: "strict",
    reason: "面對長輩時，使用禮貌用語更為安全。",
    learnerWarning: "除非另有建議，否則請使用禮貌標記。"
  },
  unknown: {
    recommendedVariant: "polite",
    safetyLevel: "strict",
    reason: "未知的接觸對象需要最安全的預設選擇。",
    learnerWarning: "在情境明確變為休閒之前，請選擇禮貌的他加祿語。"
  }
};

代码说明

● 商业逻辑： 该策略教导更具对象感知能力且安全的言语选择。

● 代码逻辑： Record<Audience, AudiencePolicy> 让缺失的对象项目对 TypeScript 来说清晰可见。

● 预期结果： UI 和测试可以为所有的语气指引使用同一个清晰的策略对象。

动手操作实验室 E — 为母语人士反馈建立内容审查队列

开发者行动

● 要求 Kiro 从草稿卡片中生成审查队列（Review queue）。

● 添加一个按分类和审查状态对卡片进行分组的函数。

● 在应用程序中渲染一个仅限开发人员查看的审查摘要，或输出控制台报告。

● 添加一个测试，确保被封锁（Blocked）的卡片绝不会出现在学习者的默认练习列表中。

Kiro 提示词示例

為他加祿語練習卡片建立一個內容審查佇列。
按 reviewStatus 和 category 將卡片分組。
草稿卡片應顯示審查者的問題。
已封鎖的卡片應從預設的學習者練習中排除。
添加一個小型可測試的輔助工具和一個面向開發人員的摘要元件。

系统设计决策

● 审查工作流程是一项功能： 由于语言内容需要母语人士审查，开发人员需要一种方法来查看哪些内容尚未被审查。

● 区分学习者查看与审查者查看： 学习者不应该收到被封锁的内容作为推荐练习，但审查者仍然需要对其进行检查。

● 按分类分组： 审查者可以在场景中评估片语，而不是扫描一个扁平的列表。

代码示例 — src/lib/reviewQueue.ts

import type { PracticeCard, PracticeCategory, ReviewStatus } from "../data/practiceCards";

export type ReviewQueue = Record<ReviewStatus, Partial<Record<PracticeCategory, PracticeCard[]>>>;

export function buildReviewQueue(cards: PracticeCard[]): ReviewQueue {
  return cards.reduce<ReviewQueue>((queue, card) => {
    queue[card.reviewStatus] ??= {};
    queue[card.reviewStatus][card.category] ??= [];
    queue[card.reviewStatus][card.category]!.push(card);
    return queue;
  }, { draft: {}, "native-reviewed": {}, blocked: {} });
}

export function learnerPracticeCards(cards: PracticeCard[]) {
  return cards.filter((card) => card.reviewStatus !== "blocked");
}

代码说明

● 商业逻辑： 辅助工具将审查管理与学习者练习区分开来。

● 代码逻辑： buildReviewQueue 按状态 and 分类对卡片进行分组，而 learnerPracticeCards 则筛选掉不安全的内容。

● 预期结果： 开发人员可以清楚看到哪些需要审查，且被封锁的内容不会被推送给学习者。

动手操作实验室 F — 添加讲师课后小检核（Exit-ticket）与学习分析事件模型

开发者行动

● 要求 Kiro 为工作坊学习成果定义仅限本地的分析事件。

● 为选取的分类、查看的提示、显示的答案和选取的信心程度添加事件类型。

● 在工作坊期间将事件保存在内存或控制台中；不要在外部发送遥测数据。

● 根据事件名生成一个讲师课后小检核（Exit-ticket）范本。

Kiro 提示词示例

為此工作坊應用程式定義一個僅限本地的學習事件模型。
追蹤 category_selected、hint_viewed、answer_revealed 和 confidence_marked。
請勿添加外部遙測或網路呼叫。
建立一個簡短的講師課後小檢核範本，詢問學習者練習了什麼以及他們在哪裡仍需要協助。

系统设计决策

● 无外部复杂度的学习分析： 本地事件模型可协助讲师讨论行为，同时保持工作坊的隐私友善性与免设置性。

● 事件对应到教学法： 这些事件对应到学习行动，而非行销指标。

● 课后小检核形成闭环： 开发人员可以看见产品检测（Instrumentation）如何支持教学质量的提升。

代码示例 — src/lib/learningEvents.ts

export type LearningEventName =
  | "category_selected"
  | "hint_viewed"
  | "answer_revealed"
  | "confidence_marked";

export interface LearningEvent {
  name: LearningEventName;
  cardId?: string;
  category?: string;
  value?: string;
  occurredAt: string;
}

const events: LearningEvent[] = [];

export function recordLearningEvent(event: Omit<LearningEvent, "occurredAt">) {
  events.push({ ...event, occurredAt: new Date().toISOString() });
}

export function readLearningEvents() {
  return [...events];
}

代码说明

● 商业逻辑： 该模型提取了可以为未来教学设计提供实证支持的学习者行动。

● 代码逻辑： 事件存储在工作坊应用程序的内存中，可以在不添加额外服务的情况下进行检查。

● 预期结果： 参与者可以讨论教育产品如何负责任地衡量练习行为。

---

参考架构说明

● 本工作坊强调的 Kiro 功能：教学法引导、学习者成果审查、受控的 TypeScript 重构、基于规则的礼貌原则、源自教育验收准则的测试，以及具备审查感知的开发。

● 产品范畴：针对活动准备、对初学者友善的他加禄语练习。语言内容在经过母语人士审查之前均保持为草稿。

● 运行时范畴：优先采用本地 React 应用程序。在建立审查工作流程后，可选用 AWS Amplify Hosting 或 Amazon S3 进行部署。