Kiro：从零建置 Fab SPC Drift Synchronization Portal

仅供教育工程用途。本内容是软件架构演练，不属于工艺放行建议。

步骤 7 — Render 入口网站

Kiro 提示词

Create src/ui/render.ts and src/main.ts to render a dark engineering portal. Include summary cards, search, sort buttons, a risk board, FDC health-link cards, dynamic matching notes, yield triage notes, and runbook steps. Use assessFleet from the domain layer.

代码示例 — src/main.ts

import { cdSemTools, fdcHealthLinks, runbookSteps } from "./data/sampleData";
import { assessFleet } from "./domain/risk";
import { renderApp } from "./ui/render";
import "./styles.css";

const root = document.querySelector<HTMLDivElement>("#app");

if (!root) {
  throw new Error("Missing #app root element");
}

renderApp(root, {
  tools: cdSemTools,
  assessments: assessFleet(cdSemTools),
  fdcHealthLinks,
  runbookSteps
});

说明

商业逻辑： 应用程序从已知的 CD-SEM 记录开始，计算风险评估，并将所有可供显示的数据传递给 render 层。

代码逻辑： main.ts 刻意保持精减。它汇入数据、呼叫领域引擎、检查 DOM 根元素，并将 UI 构建委派给 renderApp。

预期结果： 执行 npm run dev 会显示入口网站。如果缺少 #app，应用程序会以清楚的错误快速失败。

系统设计决策

• 进入点只负责协调。 它不应包含业务规则或复杂的 HTML。这让产生的代码更容易审查，也让应用程序的启动路径清楚。
• 快速失败的根元素验证可避免无声的空白画面。 如果 HTML shell 损坏，开发人员会取得明确错误，而不是除错空白页面。这能改善工作坊的疑难排解。
• 先计算评估，再进行 render。 UI 收到的已是解读过的领域数据。这种分离让风险规则能独立于视觉版面与互动程序代码演进。

步骤 8 — 测试

Kiro 提示词

Create tests/risk.test.ts using Vitest. Test Release, ApcGuard, HoldReview for slope, HoldReview for fleet deviation, RunGoldenWafer for residual noise, and Watch for stale blind-window conditions.

代码示例 — tests/risk.test.ts

import { describe, expect, it } from "vitest";
import { assessTool } from "../src/domain/risk";
import type { CdSemTool } from "../src/domain/types";

function tool(overrides: Partial<CdSemTool> = {}): CdSemTool {
  return {
    id: "CDSEM-T",
    layer: "Gate ADI",
    symptom: "baseline",
    blindWindowHours: 1,
    tmgNm: 0.1,
    mandelSlope: 1,
    fleetDeviationSigma: 0.5,
    residualThreeSigmaNm: 0.08,
    deltaMeanSeries: [0.01, 0.02],
    ...overrides
  };
}

describe("assessTool", () => {
  it("releases a healthy tool", () => {
    expect(assessTool(tool()).action).toBe("Release");
  });

  it("guards APC when TMG exceeds limit", () => {
    expect(assessTool(tool({ tmgNm: 0.25 })).action).toBe("ApcGuard");
  });

  it("requires hold review when Mandel Slope is out of range", () => {
    expect(assessTool(tool({ mandelSlope: 1.031 })).action).toBe("HoldReview");
  });

  it("requires hold review when Fleet deviation exceeds 3 sigma", () => {
    expect(assessTool(tool({ fleetDeviationSigma: 3.2 })).action).toBe("HoldReview");
  });

  it("runs golden wafer when residual noise exceeds limit", () => {
    expect(assessTool(tool({ residualThreeSigmaNm: 0.21 })).action).toBe("RunGoldenWafer");
  });

  it("watches a stale blind window", () => {
    expect(assessTool(tool({ blindWindowHours: 8 })).action).toBe("Watch");
  });
});

说明

商业逻辑： 测试将每种测量条件预期得到的建议结果编码下来。

代码逻辑： Fixture factory 建立健康的默认机台，并在每个测试中覆盖一个字段。每个断言验证一项特定规则。

预期结果： 当风险引擎遵循 spec 时，npm test 会通过。未来若规则变更而破坏建议行为，测试会失败。

系统设计决策

• 每个测试只变更一个字段。 这能隔离因果关系，让失败容易理解。除非明确测试优先顺序行为，否则 Kiro 产生的测试应避免混合许多无关的风险因素。
• Fixture factory 减少重复。 开发人员可以快速新增测试，不必复制完整的机台对象。这能改善可维护性并鼓励涵盖更多边界案例。
• 测试断言动作，而不是实作细节。 业务结果比精确的评分算术更重要。这让内部评分能持续演进，同时保留操作行为。

步骤 9 — Hooks

Kiro 提示词

Create .kiro/hooks/test-domain-on-save.json. Run npm test when files under src/domain or tests are saved. Also create a documentation agent hook that updates docs/decision-log.md after spec task execution.

代码示例 — .kiro/hooks/test-domain-on-save.json

{
  "version": "v1",
  "hooks": [
    {
      "name": "test-domain-on-save",
      "description": "Run the deterministic risk tests when domain or test files are saved.",
      "trigger": "PostFileSave",
      "matcher": "^(src/domain/.*\\.ts|tests/.*\\.ts)$",
      "action": {
        "type": "command",
        "command": "npm test"
      },
      "timeout": 60,
      "enabled": true
    }
  ]
}

说明

商业逻辑： 如果风险逻辑或测试变更，项目会立即检查建议行为是否仍然有效。

代码逻辑： JSON hook 监听符合领域或测试 TypeScript 档的档储存事件，并执行 npm test。

预期结果： 储存 src/domain/risk.ts 会触发测试套件，快速显示回归问题。

系统设计决策

• Hook 只锁定高价值档案。 每次 CSS 编辑都执行测试会浪费时间。只比对领域与测试档，能让自动化保持相关且快速。
• 动作具备决定性。 npm test 有可预期的成功或失败输出，因此比可能意外修改档案的广泛 agent action 更安全。
• 逾时保护开发循环。 Hook 不应卡住 IDE。60 秒足以执行工作坊套件，也能教导参与者为自动化设定界限。

步骤 10 — Kiro 最终审查

Kiro 提示词

Review the implementation against the fab-spc-portal spec. Check domain correctness, safety language, test coverage, accessibility, project structure, and hook safety. Produce a prioritized review report without modifying files.

预期的审查主题

• 建议动作是否安全且非自主？
• 阈值是否集中管理？
• 风险原因是否可解释？
• 每项关键规则是否都有测试？
• 新开发人员能否从 steering 与 spec 档理解项目？
• Hooks 的范围是否够窄？

系统设计决策

• 最终审查让 Kiro 成为工程伙伴，而不是未经检查的代码产生器。 开发人员要求结构化批评，再决定接受哪些发现。这能强化专业责任。
• 不修改档的审查可避免意外变更。 目标是在继续编辑前检查覆盖范围与风险。这类似 pull request 审查，将分析与实作分开。
• 审查会完成 spec 循环。 工作坊从意图开始，最后以比较代码与意图结束。这正是专业团队应透过 Kiro 建立的核心习惯。

# 扩充 Lab：使用 Kiro 从 HTML Demo 撰写代码

此扩充 Lab 保留原始建置指南，并加入来自 HTML Demo 的更多实作细节。目标是训练开发人员使用 Kiro，将可运作的单档 prototype 转换为可维护的 TypeScript，同时尽可能保留 Demo 行为。

步骤 11 — 要求 Kiro 分析单体式 HTML Demo

Kiro 提示词

Analyze the uploaded Fab SPC Drift Synchronization HTML demo. Identify all major UI sections, JavaScript data structures, functions, event handlers, CSS design tokens, and state transitions. Return a module extraction plan for a TypeScript/Vite implementation. Do not modify files yet.

预期的 Kiro 分析输出

Kiro 应辨识出以下 Demo 元件：

• Header 与 hero 区段。
• 摘要统计卡片。
• 使用 .tab 按钮与 .portal 面板的分页导览。
• 包含 CD-SEM 记录的 tools 阵列。
• 包含 FDC health-link 记录的 fdc 阵列。
• 包含专案实作步骤的 runbook 阵列。
• 用于 FDC 卡片、runbook 步骤与 market 卡片的 renderStatic()。
• 用于风险看板数据列的 render()。
• 用于可展开机台详细信息证据面板的 panel()。
• 用于 inline SVG 视觉化的 path()、spark() 与 fleetSvg()。
• 用于实时时间显示的 clock()。
• 会变更盲窗与风险值的 setInterval() 模拟。

系统设计决策

• 在重写之前先做分析。 专业开发人员应要求 Kiro 先解释并分类 prototype，才允许它产生替代代码。这能避免遗失原始 JavaScript 中隐藏的重要行为。
• 输出会成为迁移检查清单。 每个已辨识的函数都会对应到目标模块与测试策略。这能清楚说明哪些 Demo 行为已保留，哪些行为被刻意重新设计。
• 将模拟与 production 逻辑分离。 Demo 使用 setInterval() 变更值。在专业实作中，模拟应属于 Demo adapter，而不是领域模型。Kiro 应将它隔离，让测试保持决定性。

步骤 12 — 将 Demo 数据擷取为具类型记录

Kiro 提示词

Convert the demo's tools, fdc, and runbook arrays into typed TypeScript fixture modules. Preserve the values and labels from the HTML demo, but use camelCase fields and explicit interfaces. Put tools in src/data/tools.ts, FDC links in src/data/fdc.ts, and runbook steps in src/data/runbook.ts.

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

import type { CdSemTool } from "../domain/types";

export const cdSemTools: CdSemTool[] = [
  {
    id: "CDSEM-01",
    layer: "Gate ADI",
    symptom: "Stable master, production anchor",
    risk: 18,
    blindWindowHours: 1.2,
    tmgNm: 0.12,
    mandelSlope: 1.0,
    fleetDeviationSigma: 0.4,
    residualThreeSigmaNm: 0.08,
    action: "Release",
    deltaMeanSeries: [0.02, 0.01, 0.03, 0.01, 0.02, 0.0, 0.01, 0.02, 0.01, 0.02]
  },
  {
    id: "CDSEM-03",
    layer: "Fin dense CD",
    symptom: "Deflector DAC wobble, slope mismatch",
    risk: 91,
    blindWindowHours: 7.4,
    tmgNm: 0.23,
    mandelSlope: 1.031,
    fleetDeviationSigma: 3.2,
    residualThreeSigmaNm: 0.16,
    action: "HoldReview",
    deltaMeanSeries: [0.02, 0.03, 0.06, 0.05, 0.08, 0.12, 0.16, 0.2, 0.22, 0.24]
  },
  {
    id: "CDSEM-05",
    layer: "Contact/Via",
    symptom: "Vacuum slow degradation, residual rising",
    risk: 76,
    blindWindowHours: 6.9,
    tmgNm: 0.19,
    mandelSlope: 1.006,
    fleetDeviationSigma: 2.4,
    residualThreeSigmaNm: 0.21,
    action: "RunGoldenWafer",
    deltaMeanSeries: [0.02, 0.01, 0.04, 0.06, 0.08, 0.1, 0.12, 0.13, 0.16, 0.18]
  }
];

说明

商业逻辑： 这些记录保留 Demo 中近似生产环境的案例：健康的母机、斜率不匹配、真空退化、残差杂讯、Fleet 偏差与盲窗老化。

代码逻辑： 单体式 Demo 使用 blind、tmg、slope、fleet 与 resid 等短字段名称。TypeScript 版本改用 blindWindowHours、tmgNm、mandelSlope 与 residualThreeSigmaNm 等明确名称。

预期结果： 应用程序可以 render 与 HTML Demo 相同的情境，同时让 TypeScript 验证每条记录的形状。

系统设计决策

• 明确字段名称降低认知负担。 原始 Demo 为了简洁使用紧凑字段名称。在 production-style 程序代码中，领域名称应能自我说明，因为多位开发人员与审查者都会接触它。
• Fixture 数据保持接近 prototype。 保留原始值，让开发人员能比较 TypeScript 应用程序与 HTML Demo。这使视觉与行为 parity 更容易验证。