← DSPy From First Principles

构建自我改进的工程程序

把本书的机制组装成一个仓库修复程序,带上契约、工具、上下文策略、验证、优化、晋升与生产证据。

现在,我们可以把整本书组装起来了。

前面的每一章都加入了一个机制,因为排在它前面的系统暴露出了一个具体的局限:一份 契约(第 3 章)、一个被测量的基线(第 8 章)、一个被攻击过的指标(第 9 章)、 三个优化器与一次目标替换(第 11–14 章)、工具与有边界的环境访问(第 15 章)、 证据选择(第 16 章)、推理路径搜索(第 17 章)、一道实验防火墙(第 18 章),以 及一条带回滚的晋升边界(第 19 章)。本章不再引入新机制。它要问的是:我们已有的 这些机制能否组成一个单一的循环,其中没有任何一个阶段悄悄晋升自己的产出。

收官实验执行的是完整的仓库修复循环,而不是让语言模型阶段停留在假设层面。一个由 本地 Qwen3 支撑的程序检视了一个有边界的仓库,诊断出一个具体缺陷,提出了一处修 复,通过了确定性的开发验证,通过了一次独立的隐藏评估,并抵达了一个独立的 PROMOTE 决定。

这个结果之所以重要,是因为每一个阶段都仍然可以被独立检视。

目标不是一个重写自己、再部署结果的自主系统。那是自我改进的弱含义。

更强的含义是:

系统造出一个产生证据的循环,在其中,程序行为可以在显式的实验边界与晋升边界 之下被经验性地改进。

收官任务是仓库修复。

输入:

仓库
问题或请求的工程变更
约束

输出:

诊断
证据
提出的干预
候选补丁
验证结果
置信度 / 不确定性

真正的成功判据来自外部:

这个改动是否解决了引发它的问题,
同时没有造成不可接受的回归?

1. 不够用的基线

最小的 DSPy 版本很诱人:

import dspy

repair = dspy.Predict("issue, repository_context -> diagnosis, patch")

它失败的原因,本书已经揭示过了:

契约太模糊
上下文太大
没有工具边界
没有验证循环
没有划分纪律
没有晋升边界
把补丁的相似度当成了成功

于是我们用零件造出真正的程序。

在被测量的实验夹具(fixture)里,基线 invoice_total 实现忽略了数量。公开测试 失败,独立的隐藏评估给这个坏掉的基线打了 0.5。一个已知的确定性对照补丁同时通 过了公开与隐藏验证,表明这套评测框架在 LM 路径被评估之前就能识别出预期的修复。


2. 收官之作的架构

    flowchart TD
    I[问题] --> N[规范化请求]
    N --> RE[仓库探索器]
    RE --> SC[搜索代码]
    RE --> RF[读取文件]
    RE --> IT[检视测试]
    SC --> EP[证据包]
    RF --> EP
    IT --> EP
    EP --> DG[诊断]
    DG --> CI[选择干预]
    CI --> GP[生成补丁]
    GP --> IA[隔离应用]
    IA --> VA{验证}
    VA -->|通过| FC[最终候选]
    VA -->|失败| RV[解释并修订,至多一次]
    RV --> IA
  

这就是实际运行的那条循环。最终候选左边的一切都是 LM 加工具的路径;从验证往 右的一切都是确定性的。失败这条分支是有边界的——只修订一次,之后候选是什么就是 什么。

LM 的职责:

解读问题
选择要检视的证据
诊断可能的原因
提出干预
生成补丁
解释验证失败

确定性的职责:

仓库修订
文件访问
作用域检查
补丁应用
工作树隔离
测试执行
schema 校验
哈希
产物持久化
比较
晋升状态

CoCoder 当前的候选生成程序就体现了这种分离。它的程序定义指定了输入 schema、输 出 schema、约束、运行时策略、验证契约、优化面,以及一个直接的运行时。评估适配 器准备一个隔离的工作区,构建仓库分析上下文,物化候选生成,运行作用域与验证,分 析候选,计算工程差值,并定稿报告。

收官之作遵循同样的分工。LM 只拿到三个只读工具——仓库搜索、有边界的文件读取和符 号检视。它没有改动、shell、网络或隐藏验证方面的能力。它做了三次诊断工具调用, 并把service.py 认定为牵涉其中的文件。


3. 程序契约

class DiagnoseIssue(dspy.Signature):
    """Diagnose a repository issue from bounded evidence."""

    issue: str = dspy.InputField()
    repository_evidence: str = dspy.InputField()
    constraints: str = dspy.InputField()

    diagnosis: str = dspy.OutputField()
    suspected_files: list[str] = dspy.OutputField()
    missing_evidence: str = dspy.OutputField()
    confidence: float = dspy.OutputField()

class GeneratePatch(dspy.Signature):
    """Generate a bounded unified diff for a diagnosed issue."""

    issue: str = dspy.InputField()
    diagnosis: str = dspy.InputField()
    repository_evidence: str = dspy.InputField()
    constraints: str = dspy.InputField()

    patch: str = dspy.OutputField(desc="Unified diff or explicit rejection")
    rationale: str = dspy.OutputField()
    expected_behavior_change: str = dspy.OutputField()

class InterpretValidationFailure(dspy.Signature):
    """Explain a failed patch validation and propose the next revision strategy."""

    issue: str = dspy.InputField()
    diagnosis: str = dspy.InputField()
    patch: str = dspy.InputField()
    validation_output: str = dspy.InputField()

    failure_analysis: str = dspy.OutputField()
    revision_strategy: str = dspy.OutputField()

契约不包含 promotion_decision、历史验证结果或黄金补丁。那些属于评估与治理。


4. 验证循环

第 2 节里的验证节点展开成一个固定的序列:在隔离的工作树里应用候选补丁;在相 关处进行解析、编译与静态检查;先跑聚焦的测试,再跑更广的测试;然后是作用域与回 归检查。任何一步失败都会直接给出结果——一个能应用却改错了文件的补丁不会拿到部分 分数。

一个 LM 评审器(LM judge)可以帮助解释令人困惑的失败。它不能替代测试。补丁仍然 必须能被应用。目标行为仍然必须被检查。作用域仍然必须被控制。

在被测量的那次运行中,第一个生成的修复成功应用、作为 Python 通过了解析、只修改 了service.py,并通过了公开的开发测试。因为开发验证通过了,所以既不允许也不需 要修订。

然后独立的隐藏评估才运行。候选通过了全部隐藏用例,聚合分数为 1.0。那个隐藏结 果从未被反馈进补丁生成。

CoCoder 记录的维度包括解析/schema 状态、作用域状态、验证状态、动因关切的状态、 实质性回归的数量,以及局限。这就是值得效仿的形态。


5. 优化数据集

一个仓库修复案例应当记录:

case_id
仓库修订
问题
允许的证据
约束
基线程序版本
候选补丁
执行状态
验证状态
作用域状态
关切是否已解决
回归
如有则记录人的决定
划分

只有决策时刻的字段会进入程序输入。结果字段支撑指标与晋升。

收官之作在操作层面强制执行这条规则。公开开发测试的输出最多只能引导一次修复修订。 独立隐藏评估的结果对诊断与补丁生成不可见,只有在最终候选通过开发验证之后才会变 得可见。

这就造出了一条单向的证据边界:

诊断 / 修复
    ↓
开发验证
    ↓
可选的有边界修订
    ↓
最终候选
    ↓
独立评估
    ↓
比较 / 晋升

最终候选边界之下的证据不能向上流入修复。

指标应当偏好结果:

补丁有效
作用域可接受
验证通过
动因关切已解决
没有实质性回归

与黄金 diff 的相似度可以是一个小小的诊断信号。它不是成功判据,除非任务本身就是 “复现这个补丁”。


6. 按失败情形选择优化器

不要为了装饰去堆叠优化器。

失败情形 合理的优化器
只有少量可信的修复示例 BootstrapFewShot
指令系统性地偏弱 MIPROv2
失败带有丰富的诊断信息 GEPA
大上下文选择失败 先改进检索/工具,再做提示词优化

对一个仓库修复程序来说,当验证失败能够产出可操作的反馈时,GEPA 就变得有吸引力:

补丁编辑了目标文件,但没有更新那个仍在传入旧参数的调用方。

这样的反馈能比一个标量的零更好地引导指令变异。


7. 冻结的实验与晋升

清单:

程序版本
仓库案例修订
数据集指纹
训练/开发/保留集 ID
运行时版本
provider/模型配置
工具面版本
检索/索引版本
验证契约
指标版本
优化器版本/配置
DSPy 版本
种子
预算
源码修订

协议:

冻结
  ↓
基线评估
  ↓
在允许的证据上优化
  ↓
候选持久化
  ↓
完整性审计
  ↓
保留集评估
  ↓
比较
  ↓
晋升建议

激活:

生效基线 v1
       ↓
候选 v2
       ↓
保留集评估
       ↓
比较策略
       ↓
PROMOTE / REJECT / INSUFFICIENT
       ↓
操作者决定
       ↓
激活

回滚仍然可用。

在收官运行里,候选产物与晋升决定是两个各自持久化的对象,带着不同的指纹。候选产 物的指纹是 2840b5d5...b4c85;晋升决定的指纹是 60df345c...eedc5。

决定是 PROMOTE,因为最终候选通过了开发验证、在独立评估上拿了 1.0,并且没有 引入硬回归。激活被刻意地没有自动执行。

这保住了第 19 章的不变量:晋升证据可以为激活提供理由,而它本身并不是激活。


8. 一个可执行的小型清单守卫

收官之作需要在实验边界周围写普通的测试。

def validate_experiment_manifest(manifest: dict) -> None:
    required = {
        "program_version",
        "dataset_fingerprint",
        "train_ids",
        "dev_ids",
        "holdout_ids",
        "runtime_version",
        "provider_config",
        "tool_surface_version",
        "validation_contract",
        "metric_version",
        "optimizer_config",
        "dspy_version",
        "seed",
        "budget",
    }
    missing = sorted(required - set(manifest))
    if missing:
        raise ValueError(f"manifest missing: {', '.join(missing)}")

    visible = set(manifest["train_ids"]) | set(manifest["dev_ids"])
    leaked = visible & set(manifest["holdout_ids"])
    if leaked:
        raise ValueError(f"holdout ids optimizer-visible: {', '.join(sorted(leaked))}")

这不是 CoCoder 完整实验服务的替代品。它是同一份契约的最小版本:清单不完整,或 者保留集边界被打破,候选就无法被解释。

被测量的收官清单通过了它那道可执行守卫,没有缺失字段,也没有本不该出现的字段。 它记录了 provider、工具面、开发验证契约、独立评估协议、候选产物、晋升决定、 DSPy 版本、修复预算和源码修订。

因此,这份清单解释的不只是曾经存在过哪个候选,还包括它是在怎样的证据与治理边界 之下产生的。


9. 生产证据循环

完成后的循环:

    flowchart LR
    AP[生效程序] --> RT[真实任务]
    RT --> RE[运行证据]
    RE --> VA[验证]
    VA --> HD[人的决定 / 结果]
    HD --> AD[经审计的数据集]
    AD --> NE[下一次实验]
    NE --> CP[候选程序]
    CP --> IE[独立评估]
    IE --> PD[晋升决定]
    PD -->|当 PROMOTE 时| AP
  

生产活动只有在成熟起来并通过泄漏策略之后,才会成为下一次实验的证据。这是本书最 后一个乐章:

提示工程
        ↓
语言模型程序设计
        ↓
经验性程序工程

通常会出什么错

症状 可能原因 如何诊断 改什么
补丁语法有效但关切依旧存在 指标只检查能否应用/解析 检视动因关切的状态 加入面向行为的验证
测试通过但作用域变了 缺少作用域验证 比较改动的文件与工程差值 加上作用域闸门
优化器分数提高但候选被拒 治理维度抓住了回归 阅读比较中的损失 修程序,而不是改策略
程序使用了历史答案 记忆/工具泄漏 检视证据包 按划分/修订强制执行防火墙
生效行为无法解释 缺少清单/运行记录 追溯生效版本的血缘 持久化程序、模型、工具与晋升证据

位于 experiments/dspy-from-first-principles/ch18_repository_repair 的收官实 验夹具从一个具体缺陷开始:发票总额忽略了数量。

被测量的执行走完了完整路径。这次运行的身份列在下面,好让整个实验可以在同一处被 检视:

身份 值
运行 repair-run-20260901-013940 (experiments/dspy-from-first-principles/ch18_repository_repair)
模型 ollama_chat/qwen3:latest — Qwen3 8.2B, Q4_K_M, temperature=0, native_thinking=false, DSPy 3.3.1
实验夹具 invoice_total 忽略数量;夹具指纹 85b9f606…a2ff8f
工具面 仓库搜索、有边界的文件读取、符号检视(无改动、shell、网络或隐藏验证)
候选产物指纹 2840b5d5…3b4c85
晋升决定指纹 60df345c…6eedc5
评估协议指纹 bee8ace4…800843
实验指纹 3d4483a6…242884
阶段 结果
坏基线的公开验证 失败
坏基线的隐藏分数 0.5
已知对照补丁 通过公开 + 隐藏
诊断 完成
只读诊断工具调用 3
第一个 LM 补丁被应用 是
语法闸门 通过
作用域闸门 通过
公开开发验证 通过
修订 不需要
独立隐藏评估 通过
隐藏分数 1.0
晋升决定 PROMOTE
自动激活 否
LM 历史记录条目总数 6
LM token 总数 7,065
清单守卫 通过

第一次修复成功是有用的,但它并不是这个实验的主要证明。即使 LM 失败,同一套评测 框架依然成立,因为修复质量被刻意地没有做成一个不变量。决定这个结果是否可解释的, 是确定性对照、有边界的工具面、验证边界、独立评估、清单守卫和晋升记录。

Compounding Engineering 与 Arachne 提供了有用的对照:二者分别是跨工作保留下来 的学习,以及图执行与自愈。来源: Strategic-Automation/dspy-compounding-engineering、 Strategic-Automation/arachne。

本章小结

我们没有造一个提示词优化器。我们造的是围绕语言模型程序的架构。

收官之作随后演练了这套架构。一个语言模型诊断出一个真实的实验夹具缺陷,并在第一 次尝试就提出了一个有效的修复。但这个模型从不被允许宣布自己成功。是普通软件应用 了补丁、检查了语法与作用域、运行了开发验证、把独立评估扣住直到候选被冻结、比较 了由此产生的证据、审计了清单,并记录了一个独立的晋升决定。

完成后的系统拥有契约、执行策略、工具、上下文策略、示例、指标、优化器、实验清单、 候选产物、独立证据、晋升策略、生产遥测和回滚。

在整本书里,进步的单位发生了变化:

提示词措辞
    ↓
程序结构
    ↓
被测量的行为
    ↓
受控的优化
    ↓
独立证据
    ↓
受治理的部署
    ↓
新的经审计证据

这就是自我改进的更强含义。系统不会悄悄重写自己再宣布成功。它反复地制造候选,而 这些候选的行为,可以被产生它们的那个机制之外的证据挑战。

最后的论点很简单:

一个语言模型应用,当它的行为可以被规定、执行、观察、评估、诊断、优化、版本 化、比较、晋升,并在证据之下再次得到改进时,就变得可以被工程化了。