KEEL · 龙骨 · A CURRICULUM FOR THE AI ERA

当 Agent 真的开始“动手”：从动作提议到可恢复的现实执行 — keel 龙骨

Real-world Execution 的参考信息：当 Agent 真的开始“动手”：从动作提议到可恢复的现实执行

值班人员要求 Agent 把 payment-service 在 staging 环境的数据库连接池从 20 调到 40，然后通知值班群。模型很快给出了两个动作：修改配置、发送通知。

真正困难的部分现在才开始：

配置接口收到请求并返回超时，配置到底改了没有？
Harness 重启后，是否会把同一个动作再执行一次？
配置已经修改，通知却失败，整次运行算成功还是失败？
用户批准的是“改到 40”，执行前参数被模型改成 80，旧批准还能不能用？
浏览器、文件系统、Shell 和设备控制拥有不同副作用，能否共用一个执行器？

这些不是 prompt 技巧，而是分布式系统、工作流和安全工程共同面对的执行语义。

先看清完整链路

flowchart LR
    U[用户目标] --> H[Harness 创建 Run]
    H --> M[模型提出 ActionProposal]
    M --> C[程序构造 ActionCommand]
    C --> P[预检与安全授权]
    P --> G[Execution Gateway]
    G --> A[领域 Adapter]
    A --> W[外部系统]
    W --> R[Receipt / Job / Unknown]
    R --> E[事件、对账与恢复]
    E --> H

模型负责理解意图和提出候选动作。程序负责生成可信标识、固定参数、检查策略、执行动作并解释结果。外部系统的返回值不是聊天文本，而是后续恢复所依赖的事实。

这条学习线解决什么

读完并完成实验后，你应能准确解释：

Tool Call、Action、Command、Attempt、Receipt 和 Effect 的区别；
为什么模型输出只能是动作提议，不能直接成为 Shell、SQL 或 HTTP 请求；
dry-run、preview 和 preflight 分别能发现什么，不能保证什么；
幂等怎样保护业务效果，以及它为什么不等于“只执行一次”；
timeout、failure 和 outcome unknown 为什么需要不同恢复动作；
长任务怎样使用 operation ID、轮询、回调、租约和 deadline；
跨系统动作为什么常用 Saga 与补偿，而不是假设全局事务；
文件、浏览器、命令和设备适配器怎样进入隔离边界；
审批怎样绑定动作摘要、参数、审批人、有效期和执行时刻；
怎样用事件日志和对账把中断的 Run 恢复到可解释状态。

章节顺序

章节	当前要解决的问题	代码落点
01. 模型说“做完了”，现实真的改变了吗？	划清推理、工具与现实副作用	执行边界图
02. 一个动作需要哪些不会含糊的字段？	建立 Proposal、Command、Attempt、Receipt	`contracts.py`
03. 让 Ollama 只负责提出动作	接入真实模型并隔离不可信输出	`ollama_planner.py`
04. 执行前，先让变化变得可见	建立 preview、fingerprint 和 Gateway	`gateway.py`
05. 重试为什么可能把一次事故变成两次？	建立业务幂等与冲突检测	`idempotency.py`
06. 一个动作五分钟后才完成怎么办？	管理异步 Job、轮询和 deadline	`jobs.py`
07. 超时以后，最重要的是承认“不知道”	区分失败与未知结果并对账	`reconciliation.py`
08. 不能回滚的世界，怎样收拾部分成功？	设计补偿、顺序和人工接管	`saga.py`
09. 浏览器、文件、命令和设备不是普通函数	理解执行适配器与隔离	Adapter 契约
10. 人工批准的必须是将要执行的那个动作	处理审批绑定与 TOCTOU	安全课程接口
11. 进程重启后，Run 如何接着走？	建立事件、恢复和因果轨迹	`events.py`
12. 完成一次可恢复的配置变更	连起完整执行闭环	`change_run.py`

遇到陌生术语时查阅现实执行术语地图。资料来源和课程取舍记录在调研与课程设计依据中。

先验证协议，再连接真实模型

python -m pip install -r courses/advanced/real-world-execution/course/project/requirements.txt
python courses/advanced/real-world-execution/course/project/examples/01_action_contract.py
python courses/advanced/real-world-execution/course/project/examples/03_preview_and_execute.py
python -m unittest discover -s courses/advanced/real-world-execution/course/project/tests -v

确定性的执行语义通过后，再让本地 Ollama 生成动作提议：

ollama serve
ollama pull qwen3:8b
$env:OLLAMA_MODEL = "qwen3:8b"
python courses/advanced/real-world-execution/course/project/examples/02_ollama_plan.py

从第 01 章开始。先确认“模型输出”和“现实事实”之间隔着哪些系统责任。

进入 keel 阅读