🧱 第五课：从 YAML 到 TypeScript — 迈向 Sandcastle 架构

预计完成时间：35 分钟  |  难度：中级  |  类型：重构 + 实践

本课目标

将第 4 课的 内联 claude -p 重构为 TypeScript 脚本编排模式：

• Prompt 从 YAML heredoc 中迁出 → 独立 .md 文件
• AI 调用逻辑从 YAML 中迁出 → TypeScript 脚本（npx tsx 执行）
• YAML 回归本职：只做编排（触发、环境准备、结果发布、标签收尾）

这是从"第 4 课简化版"迈向 sandcastle 真实架构的第一步。功能不变，结构升级。

为什么要重构？第 4 课的问题

第 4 课的 agent-analyze.yml 把所有逻辑塞进了一个 YAML 文件：

# 第 4 课做法：prompt 内联在 YAML 的 heredoc 里
- name: Run AI analysis
  run: |
    claude -p "$(cat <<'PROMPT'
    你是一个软件架构分析助手...
    1. **需求理解**：用 2-3 句话...
    2. **技术方案**：提出 1-2 个...
    ...
    PROMPT
    )" --output-format text --allowedTools Read,Grep,Glob \
    > "$RUNNER_TEMP/analysis.md"

能跑，但有三个问题会随着扩展而放大：

sandcastle 和 course-video-manager 的做法完全不同。它们引入了一层TypeScript 编排脚本，把关注点拆成三层：

YAML 只剩下一行调用：

npx tsx .sandcastle/analyze/analyze.ts

新概念：三层架构

sandcastle 不直接调用 claude -p，而是严格遵循三层分离：

第一步：创建 prompt 文件

把第 4 课的 prompt 从 YAML heredoc 中提取出来，存为独立文件。

在仓库根目录创建 .sandcastle/analyze/prompt.md：

你是一个软件架构分析助手。下面是一个 GitHub Issue 的 JSON 数据，
存储在 {{CONTEXT_FILE}} 中。

请阅读这个 Issue 并用中文做以下分析：

1. **需求理解**：用 2-3 句话总结 Issue 想解决的问题
2. **技术方案**：提出 1-2 个可行的技术实现思路
3. **潜在风险**：指出实现中需要注意的 1-3 个风险点
4. **建议的下一步**：给出具体的行动建议

直接输出分析结果，不要做其他操作。

第二步：写 TypeScript 编排脚本

创建 .sandcastle/analyze/analyze.ts。这个脚本做四件事：

1. 读取环境变量（YAML 传入的 Issue 编号、标题等）
2. 加载 prompt 文件，替换其中的模板变量
3. 调用 claude CLI，传入 prompt 和权限参数
4. 验证输出，写入结果文件

// .sandcastle/analyze/analyze.ts
import { execSync } from "node:child_process";
import { readFileSync, writeFileSync, existsSync } from "node:fs";
import { join } from "node:path";

// ── 1. 读取 YAML 传来的环境变量 ──
const issueNumber = process.env.ISSUE_NUMBER;
const issueTitle = process.env.ISSUE_TITLE;
const contextFile = process.env.CONTEXT_FILE;
const outputDir = process.env.OUTPUT_DIR || process.env.RUNNER_TEMP || "/tmp";

if (!issueNumber || !contextFile) {
  console.error("❌ 缺少必要的环境变量: ISSUE_NUMBER 或 CONTEXT_FILE");
  process.exit(1);
}

console.log(`🔍 正在分析 Issue #${issueNumber}: ${issueTitle}`);

// ── 2. 加载 prompt 模板，替换变量 ──
const promptTemplate = readFileSync(
  join(import.meta.dirname, "prompt.md"),
  "utf-8"
);
const prompt = promptTemplate.replace("{{CONTEXT_FILE}}", contextFile);

// ── 3. 调用 claude CLI ──
const outputFile = join(outputDir, "analysis.md");

try {
  const result = execSync("claude", {
    input: prompt,
    env: {
      ...process.env,
      CLAUDE_CODE_OAUTH_TOKEN: process.env.CLAUDE_CODE_OAUTH_TOKEN!,
    },
    timeout: 5 * 60 * 1000, // 5 分钟超时
    maxBuffer: 1024 * 1024,  // 1MB 输出上限
  });

  // ── 4. 写入输出文件 ──
  writeFileSync(outputFile, result.stdout, "utf-8");
  console.log(`✅ 分析完成，输出已写入 ${outputFile}`);
  console.log(`📊 分析长度: ${result.stdout.length} 字符`);

} catch (error) {
  // ── 失败处理：写 failure_reason.txt ──
  const reason = error instanceof Error ? error.message : String(error);
  writeFileSync(join(outputDir, "failure_reason.txt"), reason, "utf-8");
  console.error(`❌ AI 分析失败: ${reason}`);
  process.exit(1);
}

逐行解释

第三步：简化 YAML

重构后的 .github/workflows/agent-analyze.yml 第 4 阶段大幅简化：

# ── 阶段 3: 获取上下文（不变）──
- name: Fetch issue body
  run: |
    gh issue view "$ISSUE_NUMBER" --json title,body,labels \
      > "$RUNNER_TEMP/issue-context.json"

# ── 阶段 4: AI 分析（重构后）──
- name: Run AI analysis
  id: analyze
  env:
    CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
    CONTEXT_FILE: ${{ runner.temp }}/issue-context.json
    OUTPUT_DIR: ${{ runner.temp }}
  run: |
    npx tsx .sandcastle/analyze/analyze.ts \
      > "$RUNNER_TEMP/analysis.md"

原来 ~20 行的 heredoc + claude 参数 + 重定向，现在变成了 1 行 npx tsx 调用。prompt 内容、claude 参数、错误处理全部搬到了 TypeScript 脚本里。

第四步：补全依赖安装

现在工作流需要 tsx 来执行 TypeScript 脚本。在环境准备阶段加一行安装：

# ── 阶段 2: 环境准备 ──
- uses: actions/checkout@v4
  with:
    fetch-depth: 1

- uses: actions/setup-node@v4
  with:
    node-version: 22

- name: Install tsx
  run: npm install -g tsx

- name: Install Claude Code
  run: npm install -g @anthropic-ai/claude-code

完整对照：重构前 vs 重构后

✏️ 诊断性测验

🎯 总结：你学到了什么

推荐进一步阅读

• 主阅读材料：sandcastle/.sandcastle/agent-workflows/ — 看真实的 review.ts、implement.ts 是怎么写的。对比你刚写的 analyze.ts，找出相同模式和扩展之处
• @ai-hero/sandcastle npm 包 — 了解 sandcastle.claudeCode() 和 runWithExtraction() 的 API
• 参考文档：Agent-Runner 契约速查表 — 回顾输入/输出规范、可靠性模式、权限控制
• Node.js 文档：execSync — input、timeout、maxBuffer 等选项的官方说明