首页 / 文章 / 《实用笔记》：基于Claude Code的量产级文本转SQL代理

agents sql data claude-code naturallanguageprocessing langchain

《实用笔记》：基于Claude Code的量产级文本转SQL代理

《实用笔记》操作指南：基于Claude Code的量产级文本转SQL代理——适用于采用该模式的团队的合同、检查项及可直接插入的代码模块。

4157 词

可将此内容视为《基于 Claude Code、LangGraph、Langfuse、FastAPI 和 Qdrant 的生产级文本转 SQL 工具》中理念面向操作员的简化版本：清晰的阶段划分、有序的代码模块，以及能在交接过程中保留的恢复说明。

仓库

将仓库视为可度量的对象使用效果最佳。在扩大范围之前，先记录一份理想的运行日志、一个故障案例以及回滚说明。同时文档化正常流程与恢复流程。重试机制、人工审核环节以及死信处理都是产品本身的组成部分，而非后续需要补充的内容。保持图结构的状态简洁且具有类型定义；嵌套的 blob 会掩盖哪个节点编写了哪个字段的信息，还会在流程中断后导致无法继续执行。

技术栈

将技术栈视为可度量的对象来管理效果最佳。在扩大范围之前，先记录一份优秀的测试用例、一个故障案例以及回滚说明。优先选择小型且可测试的单元，而非庞大的脚本。当某个步骤出错时，故障应能指向具体的责任模块，而非复杂的流程链。保持图结构的状态简洁且具有类型定义。嵌套的数据块会掩盖哪个节点修改了哪个字段的信息，还会在流程中断后导致无法继续执行。

LLM与智能体

将大语言模型与智能体视为可度量的系统时，其效果最佳。在扩大应用范围之前，先记录一个成功的案例、一个失败案例以及回滚说明。将此阶段视为输入与经过验证的输出之间的契约。为相关成果命名，明确成功标准，绝不允许出现无声无息的半完成状态。需为每轮对话及每次会话设定token预算。智能体工具往往会大量消耗上下文资源，设置上限可避免演示过程变成意外的费用账单。

嵌入向量与向量搜索

将嵌入模型与向量搜索视为可度量的实体时，其效果最佳。在扩大应用范围之前，先记录一个成功的案例、一个失败案例以及回滚说明。在功能结果旁还需记录处理时间以及令牌或查询成本。提前了解这些成本，就能避免在从演示环境过渡到共享环境时出现意外费用。应将分块策略与检索策略分开，当质量指标发生变化时，修改其中一项无需强制重写另一项。

API与后端

将 API 和后端视为可度量的系统结构时，其运行效果最佳。在扩大范围之前，需记录一份理想的操作日志、一个故障案例以及回滚说明。配置应与应用程序代码分开存放。环境文件、密钥存储和功能开关应集中于一处，以便操作人员无需查看整个系统结构即可进行审计。保持系统状态的扁平化与类型化。嵌套的数据结构会掩盖具体是哪个节点修改了哪个字段，还会导致中断后无法继续执行。将 API 和后端视为可度量的系统结构时，其运行效果最佳。在扩大范围之前，需记录一份理想的操作日志、一个故障案例以及回滚说明。相比复杂的脚本，应优先使用小型且可测试的单元。当某个步骤出现故障时，故障原因应能明确指向某个具体的功能模块，而非整个复杂的流程。

前端

在修改前端代码之前，需先明确输入参数、该步骤的负责人以及结束标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。应将此阶段视为输入与已验证输出之间的契约。为相关成果命名，定义成功判定标准，杜绝默许的半完成状态。对于涉及资金支出或修改生产数据的操作，必须经过人工审批。编译时的连接方式并不等同于业务上的完整性。

可观测性与追踪

在涉及可观测性与追踪功能时，应在修改代码之前明确输入参数、各步骤的负责人以及结束标准。操作人员应能够从已知的检查点重新运行相应步骤，而无需猜测隐藏状态。除了功能结果外，还需记录执行时间以及令牌或查询成本。提前了解这些成本信息，可避免在流程从演示环境转向共享环境时出现意外费用。对于那些会产生费用或修改生产数据的操作，必须经过人工审批。仅靠编译时的配置并不足以确保业务的完整性。

评估

在修改代码之前，为评估目的需明确输入参数、该步骤的负责人以及终止标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。配置信息应置于应用程序代码之外。环境文件、密钥存储以及功能开关应集中存放于一个位置，以便操作人员无需查看整个流程即可进行审计。对于涉及资金支出或修改生产数据的操作，必须经过人工审批。编译时的连接方式并不等同于业务功能的完整性。在修改代码之前，为评估目的需明确输入参数、该步骤的负责人以及终止标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。相较于庞大的脚本，应优先使用小型且可测试的单元。当某个步骤出现故障时，故障原因应能明确指向某个具体的责任模块，而非整个复杂的流程。

基础设施与配置

在处理基础设施与配置时，首先需明确相关约定：所需的输入参数、成功标志，以及部分失败时的处理方式。这样的清单能确保后续的代码修改始终符合约定。将此阶段视为输入与验证后输出之间的契约。为相关产物命名，定义成功检测标准，杜绝无声的半完成状态。在成本较高的操作之后设置检查点。当操作员重新尝试后续节点时，恢复流程不应再次调用相同的大型语言模型。

MCP服务器

在开发MCP Server时，首先需明确接口规范：所需的输入参数、成功信号以及部分失败时的处理方式。这样的清单能确保后续的代码修改始终符合预期。在功能结果旁记录执行时间以及令牌或查询成本。提前了解成本情况，可避免从演示环境过渡到共享环境时出现意外的费用支出。需为每次调用记录工具名称、参数哈希值、延迟时间以及最终结果。没有这些记录，调试循环问题将会耗费大量时间。

测试

在编写测试时，首先明确接口规范：所需的输入参数、成功标志以及部分失败时的处理方式。这样的清单能确保后续的代码修改保持一致性。将配置信息与应用程序代码分开存放。环境文件、密钥存储以及功能开关应集中管理，以便操作人员无需查看整个系统结构即可进行审计。在耗时较高的步骤之后设置检查点。当操作人员重新执行后续节点时，恢复流程不应再次调用相同的大型语言模型。在编写测试时，首先明确接口规范：所需的输入参数、成功标志以及部分失败时的处理方式。这样的清单能确保后续的代码修改保持一致性。优先选择小型、可测试的单元，而非庞大的脚本。当某个步骤失败时，故障应能指向具体的责任模块，而非整个复杂的流程。

开发者工具

将开发者工具视为可度量的对象使用效果最佳。在扩大范围之前，先记录一份理想的测试用例、一个故障案例以及回滚说明。把这一阶段视为输入与经过验证的输出之间的契约，为相关成果命名，明确成功标准，绝不允许出现悄无声息的半完成状态。工具应具备严格的架构规范和明确的副作用标识，这样托管方才能在自动批准之前知道哪些调用会改变系统状态。

为何要从零开始构建文本转SQL的智能体

将自研的文本转SQL智能体视为可度量的对象来分析，是理解其设计优缺点的最佳方式。在扩大应用范围之前，先记录一份理想的运行案例、一个失败案例以及回滚说明。在功能结果之外，还需记录执行时间以及令牌或查询成本。提前了解这些成本信息，就能避免在从演示环境过渡到共享环境时出现意外费用。要保持图结构的状态简洁且类型明确，嵌套的数据块会掩盖具体是哪个节点修改了哪一字段，还会在进程中断后导致无法继续运行。

1. UDogRetail数据集——构建真实的测试环境

UDogRetail数据集——在设计真实的测试环境时，将其视为可测量的对象最为有效。在扩大范围之前，先记录一份标准流程、一个故障案例以及回滚说明。将配置信息置于应用程序代码之外。环境文件、密钥存储和功能标志应集中存放于一处，以便操作人员无需查看整个架构即可进行审计。保持架构状态的简洁性与类型化。嵌套的数据结构会掩盖哪个节点修改了哪个字段的信息，还会在中断后导致流程无法继续。
UDogRetail数据集——在设计真实的测试环境时，将其视为可测量的对象最为有效。在扩大范围之前，先记录一份标准流程、一个故障案例以及回滚说明。优先选择小型且可测试的单元，而非庞大的脚本。当某个步骤出现故障时，故障原因应能明确指向某个具体的功能模块，而非复杂的流程链。

2. 架构概览——各组件如何协同工作

在“2. 架构概览——各组件如何协同工作”部分，应在修改代码之前明确输入内容、该步骤的负责人以及结束标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。将此阶段视为输入与已验证输出之间的契约。为相关成果命名，定义成功检测标准，并拒绝默许的半完成状态。对于涉及资金支出或修改生产数据的操作，必须经过人工审批。编译时的连接并不等同于业务上的完整性。

您选择的技术栈及其原因：

关于您选择的技术栈及其原因：在修改代码之前，需明确输入参数、该步骤的负责人以及完成标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。应在功能结果旁记录执行时间以及令牌或查询成本。提前了解成本情况，可避免在从演示环境过渡到共享环境时出现意外费用。对于会产生支出或修改生产数据的操作，必须经过人工审批。编译时的配置并不等同于业务功能的完整性。

3. 构建RAG流程——架构设计与文档检索

对于3.构建RAG流程——架构设计+文档检索，应在修改代码之前明确输入参数、该步骤的负责人以及终止标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测其中的隐藏状态。配置信息应置于应用程序代码之外。环境文件、密钥存储以及功能开关应集中存放于一个位置，以便操作人员无需查看整个系统结构即可进行审计。需注明实际用于支撑答案的段落。如果没有引用，操作人员就无法区分是幻觉内容还是索引缺失导致的错误。对于3.构建RAG流程——架构设计+文档检索，应在修改代码之前明确输入参数、该步骤的负责人以及终止标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测其中的隐藏状态。相比庞大的脚本，更应优先使用小型且可测试的单元。当某个步骤失败时，故障原因应当一目了然。

单一职责，而非复杂的流程链。

模式索引

在处理模式索引时，首先明确契约内容：所需输入、成功信号以及部分失败时的处理方式。这样的清单能确保后续的代码修改保持一致性。将此阶段视为输入与验证后输出之间的契约。为相关成果命名，定义成功检查标准，并杜绝无声的半完成状态。在耗时步骤之后设置检查点。当操作员重新尝试后续节点时，恢复流程不应再次调用相同的大型语言模型。

知识库索引

在处理知识库索引时，首先写下相关规范：所需输入、成功标志以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改保持一致性。在功能结果旁记录执行时间以及令牌或查询成本。提前了解成本情况，可避免在从演示环境过渡到共享环境时出现意外费用。在耗时的步骤之后设置检查点。当操作员重新尝试后续节点时，恢复流程不应再次收取相同的LLM调用费用。

检索

在处理检索功能时，首先需明确相关规范：所需输入、成功信号以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改保持一致性。应将配置信息与应用程序代码分开存放。环境文件、密钥存储以及功能开关应集中管理，以便操作人员无需查看整个系统结构即可进行审计。在调整提示词之前，先使用固定的问题集来衡量召回率。仅仅更换提示词往往无法解决检索效果不佳的问题。在处理检索功能时，首先需明确相关规范：所需输入、成功信号以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改保持一致性。相比庞大的脚本，更应优先使用小型且可测试的单元。当某个步骤出现故障时，故障点应能指向单一的责任模块，而非复杂的流程链。

4. LangGraph智能体——节点、状态与自我修正

LangGraph智能体——其节点、状态及自我修正功能在被视为可度量对象时表现最佳。在扩大应用范围之前，先记录一份理想的处理结果、一个失败案例以及回滚说明。将此阶段视为输入与经过验证的输出之间的契约。为相关成果命名，明确成功标准，绝不允许出现无声的、不完整的处理结果。保持图结构的层次简单且类型明确。嵌套的数据块会掩盖哪个节点编写了哪个字段的信息，且在中断后会导致处理无法继续。

class AgentState(TypedDict):
  question: str
  session_id: str
  retrieved_schema: list[str]
  retrieved_docs: list[str]
  generated_sql: Optional[str]
  sql_reasoning: Optional[str]
  sql_assumptions: list[str]
  sql_confidence: float
  validation_error: Optional[str]
  execution_result: Optional[ExecutionResult]
  execution_error: Optional[str]
  retry_count: int
  correction_history: list[CorrectionRecord]
  needs_clarification: bool
  clarification_message: Optional[str]
  final_explanation: Optional[str]
  langfuse_trace_id: Optional[str]

生成

将GENERATE视为可测量的界面使用效果最佳。在扩大范围之前，先记录一个成功的案例、一个失败案例以及回滚说明。在功能结果旁同时记录执行时间以及令牌或查询成本。提前了解成本情况，可避免在从演示环境过渡到共享环境时出现意外费用。需保持图表状态简洁且具有明确类型；嵌套的数据块会掩盖哪个节点修改了哪个字段的信息，且在中断后还会导致流程无法继续。

验证 → 执行

将“验证 → 执行”视为可度量的流程体系时，其效果最佳。在扩大范围之前，需记录一份理想的执行日志、一个故障案例以及回滚说明。配置应与应用程序代码分开存放。环境文件、密钥存储和功能开关应集中于一处，以便操作人员无需查看整个流程图即可进行审计。保持流程图的状态结构化且具有明确类型。嵌套的数据块会掩盖具体是哪个节点修改了哪个字段，还会导致中断后无法继续执行。将“验证 → 执行”视为可度量的流程体系时，其效果最佳。在扩大范围之前，需记录一份理想的执行日志、一个故障案例以及回滚说明。相较于庞大的脚本，应优先使用小型且可测试的单元。当某一步骤失败时，故障应指向单一的责任模块，而非复杂的流程链。

FORBIDDEN_KEYWORDS = frozenset({
"INSERT", "UPDATE", "DELETE", "DROP",
"TRUNCATE", "ALTER", "CREATE", "GRANT", "REVOKE"
})

自我修正循环

对于自我修正循环，应在修改代码之前明确输入参数、该步骤的负责人以及退出条件。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。将此阶段视为输入与已验证输出之间的契约。为相关成果命名，定义成功标准，杜绝默许的半完成状态。对于涉及资金支出或修改生产数据的操作，必须经过人工审批。编译时的配置并不等同于业务上的完整性。

def route_after_execute(state: AgentState) -> str:
  if state["execution_error"] is None:
    return "explain"
  if state["retry_count"] >= settings.max_retries:
    return "clarify"
    return "correct"

5. 使其具备生产环境就绪条件 — FastAPI、Docker、Terraform

第五点：使其具备生产环境就绪条件——使用FastAPI、Docker和Terraform，在修改代码之前明确输入参数、该步骤的负责人以及终止标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏的状态。除了功能结果外，还需记录执行时间以及令牌或查询成本。提前了解成本情况可以避免在从演示环境过渡到共享环境时出现意外账单。对于会产生费用或修改生产数据的操作，必须经过人工审批。编译时的配置并不等同于业务功能的完整性。

API

对于 API，修改代码之前需明确输入参数、该步骤的负责人以及终止条件。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。配置信息应置于应用程序代码之外。环境文件、密钥存储以及功能开关应集中存放，以便操作人员无需查看整个流程即可进行审计。对于涉及资金支出或修改生产数据的操作，需经过人工审批。编译时的连接方式并不等同于业务功能的完整性。对于 API，修改代码之前需明确输入参数、该步骤的负责人以及终止条件。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。相比庞大的脚本，更应采用小型且可测试的单元。当某个步骤失败时，故障原因应能明确指向某个具体功能，而非整个复杂的流程。

Docker

在处理 Docker 相关工作时，首先需明确约定：所需的输入参数、成功标志以及部分失败时的处理方式。这样的清单能确保后续的代码修改保持一致性。将此阶段视为输入与验证后输出之间的契约。为相关成果命名，定义成功判定标准，并杜绝无声的半完成状态。在耗时较高的步骤之后设置检查点。当操作员重新尝试后续节点时，恢复流程不应再次调用相同的大型语言模型。

#!/bin/bash
# backend/start.sh
set -e
echo "==> Running Alembic migrations…"
cd /app/backend && alembic upgrade head
echo "==> Starting uvicorn…"
exec uvicorn app.main:app - host 0.0.0.0 - port 8000

配置

在处理配置时，首先写下相关约定：所需的输入参数、成功信号以及部分失败时的处理方式。这样的清单能确保后续的代码修改保持一致性。在功能结果旁记录执行时间以及令牌或查询成本。提前了解成本情况，可避免在从演示环境过渡到共享环境时出现意外费用。在耗时的步骤之后设置检查点。当操作员重新尝试后续节点时，恢复流程不应再次收取相同的LLM调用费用。

class Settings(BaseSettings):
  anthropic_api_key: SecretStr
  voyage_api_key: SecretStr
  postgres_password: SecretStr
  langfuse_secret_key: SecretStr

6. Langfuse的可观测性——追踪每次智能体运行

在学习 Langfuse 的可观测性功能——即追踪每次智能体运行时，首先需明确相关规范：所需输入、成功信号以及部分失败时的处理方式。这样的清单能确保后续的代码修改透明可溯。将配置信息置于应用程序代码之外。环境文件、密钥存储以及功能开关应集中存放于一个位置，以便操作员无需查看整个流程即可进行审计。在耗时较高的步骤之后设置检查点。当操作员重新执行后续节点时，恢复流程不应再次计费相同的 LLM 调用。在学习 Langfuse 的可观测性功能——即追踪每次智能体运行时，首先需明确相关规范：所需输入、成功信号以及部分失败时的处理方式。这样的清单能确保后续的代码修改透明可溯。优先选择小型且易于测试的单元，而非结构复杂的脚本。当某个步骤失败时，故障应指向单一责任模块，而非错综复杂的流程。

。

@observe(name="generate", as_type="generation")
def generate(state: AgentState) -> AgentState:
# Claude call happens here
# Langfuse auto-captures input, output, latency

lf = get_lf_client()
lf.update_current_observation(
model="claude-sonnet-4–6",
usage={"input": input_tokens, "output": output_tokens},
)

7. 测试——单元测试与集成测试

在将单元测试和集成测试视为可度量的指标时，其效果最佳。在扩大测试范围之前，需记录一份理想的测试用例、一个失败案例以及回滚说明。应将此阶段视为输入与经过验证的输出之间的契约。为相关文档命名，明确成功标准，杜绝默许的半完成状态。需保持图结构的扁平化与类型化。嵌套的数据结构会掩盖哪个节点修改了哪个字段的信息，且在中断后会导致测试无法继续。

单元测试

将单元测试视为可度量的对象时，其效果最佳。在扩大测试范围之前，先记录一份理想的测试用例、一个失败案例以及回滚说明。在功能结果旁同时记录执行时间以及令牌或查询成本。提前了解这些成本，就能避免在测试环境从演示模式切换到共享环境时出现意外费用。要保持图表状态的结构清晰且类型明确，嵌套的数据块会掩盖具体是哪个节点修改了哪个字段，还会在测试中断后导致无法继续执行。

@pytest.mark.parametrize("keyword", sorted(FORBIDDEN_KEYWORDS))
def test_forbidden_keyword_rejected(keyword: str) -> None:
  sql = f"{keyword} INTO orders VALUES ('x')"
  result = validate_sql(sql)
  assert not result.is_valid
  assert keyword in result.error_message
  def test_forbidden_keyword_in_cte_still_rejected() -> None:
  sql = "WITH x AS (DELETE FROM orders RETURNING id) SELECT * FROM x"
  result = validate_sql(sql)
  assert not result.is_valid

pytest tests/unit/ -v

集成测试

将集成测试视为可度量的对象时，其效果最佳。在扩大测试范围之前，需记录一份标准测试用例、一个失败案例以及回滚说明。应将配置与应用程序代码分开。环境文件、密钥存储和功能开关应集中存放，以便操作人员无需查看整个系统结构即可进行审计。要保持系统状态的简洁性与类型化。嵌套的数据结构会掩盖具体是哪个节点修改了哪个字段，还会导致在出现中断后无法继续执行。将集成测试视为可度量的对象时，其效果最佳。在扩大测试范围之前，需记录一份标准测试用例、一个失败案例以及回滚说明。相比复杂的脚本，更应优先使用小型且易于测试的单元。当某个步骤失败时，故障应能指向具体的责任模块，而非整个错综复杂的流程。

pytest tests/integration/ -v

8. 使用GEval评估代理

第8点：使用GEval评估智能体时，应在修改代码之前明确输入参数、各步骤的负责人以及终止标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。应将此阶段视为输入与验证后输出之间的契约：为相关成果命名，定义成功判定标准，杜绝默许的半完成状态。对于涉及资金支出或修改生产数据的操作，必须经过人工审批——编译时的连接方式并不等同于业务上的完整性。

prompt = f"""
Score from 0.0 to 1.0 whether this explanation is faithful to the results.
Results: {json.dumps(rows[:5])}
Explanation: {explanation}
Return only JSON: {{"score": float, "reasoning": str}}
"""

python -m evaluation.harness --complexity simple
python -m evaluation.harness --limit 10

9. MCP服务器——让它成为Claude Code的一部分

对于第9点：MCP服务器——要使其成为Claude Code的组成部分，需在修改代码之前明确输入参数、该步骤的负责人以及终止条件。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。除了功能结果外，还需记录执行时间以及令牌或查询成本。提前了解成本情况可以避免在从演示环境切换到共享环境时出现意外账单。

mcp = FastMCP(name="udogretail-text2sql")
@mcp.tool()
def query_tool(question: str, session_id: str = "") -> str:
"""Run a natural-language question through the Text-to-SQL agent."""
…
@mcp.tool()
def schema_tool(keyword: str) -> str:
"""Look up tables and columns matching a keyword."""
…
@mcp.tool()
def history_tool(limit: int = 5) -> str:
"""Fetch the last N query runs from agent history."""
…

{
"mcpServers": {
  "udogretail-text2sql": {
    "type": "stdio",
    "command": ".venv/bin/python",
    "args": ["mcp_server/server.py"],
    "env": {"API_BASE_URL": "http://localhost:8000"}
    }
  }
}

10. 结果、经验教训以及未来的改进措施

关于10.结果、经验教训以及未来会做的改进：在修改代码之前，需明确输入参数、该步骤的负责人以及终止标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。配置信息应置于应用程序代码之外。环境文件、密钥存储和功能标志应集中存放于一个位置，以便操作人员无需查看整个流程即可进行审计。对于涉及资金支出或修改生产数据的操作，需经过人工审批。编译时的连接方式并不等同于业务流程的完整性。关于10.结果、经验教训以及未来会做的改进：在修改代码之前，需明确输入参数、该步骤的负责人以及终止标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。相比庞大的脚本，更应优先使用小型且可测试的单元。当某个步骤失败时，故障原因应能明确指向具体的修复点。

责任明确而非流程混乱。

你会做出的不同调整：

在思考“会做出哪些不同调整”时，首先写下契约：所需输入、成功信号以及部分失败时的处理方式。这样的清单能确保后续的代码修改保持透明。将此阶段视为输入与验证后输出之间的契约。为相关成果命名，定义成功检查标准，并拒绝默许部分完成的情况。在成本较高的步骤之后设置检查点。当操作员重新尝试后续节点时，恢复流程不应再次调用相同的大型语言模型。

让我感到惊讶的是：

在处理“让我惊讶的是什么？”这部分时，首先需写下相关规范：所需输入、成功标志以及部分失败时的处理方式。这样的清单能确保后续的代码修改保持一致性。

操作检查清单

在制定操作检查清单时，同样要首先明确规范：所需输入、成功标志以及部分失败时的处理方式。这样的清单能确保后续的代码修改保持一致性。

需同时记录正常流程和故障恢复流程。重试机制、人工审核环节以及错误处理方式都是产品本身的组成部分，而非后续需要补充的内容。

在成本较高的步骤之后设置检查点。当操作员重新尝试后续节点时，恢复流程不应再次计费相同的LLM调用。

锁定依赖版本，并记录用于运行演示的镜像摘要。可重复性比经验知识更重要。

优先选择小型、可测试的单元，而非庞大的脚本。当某个步骤失败时，故障应能指向单一责任点，而非复杂的流程链。

在成本较高的步骤之后设置检查点。当操作员重新尝试后续节点时，恢复流程不应再次计费相同的LLM调用。

在升级技术栈之前，先冻结版本，为关键路径保存标准记录，并确认回滚步骤。共享环境需要设置速率限制、租户检查机制，以及明确的密钥轮换负责人。与其追求花哨的一次性演示，不如注重扎实的可靠性。

关于 91a3d7beec49 的批处理说明：不要将提供者密钥放入代码仓库，为每个会话设置令牌上限，并将转录内容存储在评估测试用例的旁边，以便后续更换模型时仍能保持可比性。

全部文章发送简报