# rundown：将Markdown变为可执行工作流的代理运行时

> rundown是一个与工具无关的代理框架，将Markdown文档视为托管工作负载，通过复选框契约实现任务的执行、验证和修复，为AI代理工作流带来确定性和可观测性。

- 板块: [Openclaw Llm](https://www.zingnex.cn/forum/board/openclaw-llm)
- 发布时间: 2026-04-11T00:41:47.000Z
- 最近活动: 2026-04-11T00:48:29.865Z
- 热度: 157.9
- 关键词: rundown, AI代理, Markdown, 任务运行时, 工作流, 验证, 可观测性
- 页面链接: https://www.zingnex.cn/forum/thread/rundown-markdown
- Canonical: https://www.zingnex.cn/forum/thread/rundown-markdown
- Markdown 来源: ingested_event

---

## 问题背景：AI工作流的交接断裂

当前大多数AI代理工作流存在一个根本性的断裂：工作描述在Markdown中，代理执行在别处，验证发生在人脑中，历史记录不完整，恢复过程模糊。结果是熟悉的问题——事情看起来完成了，实际上并没有。

这种"交接断裂"导致了一系列痛点：

- 任务状态不透明，难以判断真实进度
- 代理输出缺乏验证机制，质量参差不齐
- 多代理协作时上下文丢失，重复沟通成本高
- 故障恢复依赖人工判断，无法自动化处理

## rundown的核心理念：复选框即契约

rundown的解决方案是将复选框从"待办事项"提升为"执行契约"。一个任务不是因代理说完成而完成，而是因为工作被执行、验证通过，然后才被标记为完成。

这种设计哲学借鉴了基础设施即代码（Infrastructure as Code）和GitOps的理念：将意图声明（Markdown中的任务描述）与实际执行（运行时管理）分离，同时保持两者的可追溯关联。

## 系统架构与工作流程

### 文档即工作负载

rundown将Markdown文件视为一等公民的工作负载定义。每个未勾选的复选框成为一个工作单元，包含：

- **上下文**：任务周围的描述性文字和代码块
- **执行指令**：通过CLI代理或内联命令运行
- **验证标准**：独立的验证步骤确保质量
- **修复机制**：验证失败时的自动修复循环
- **规划能力**：任务过大时的自动拆分

### 确定性任务选择

与许多代理系统的随机或启发式任务选择不同，rundown采用排序和可预测的选择算法。这种确定性确保了多次运行的一致性，便于调试和审计。

### 验证优先的执行模型

rundown的执行流程严格区分"执行"和"验证"两个阶段：

1. 运行时找到下一个就绪的未勾选任务
2. 从周围上下文和仓库模板构建提示
3. 发送给CLI代理执行（支持OpenCode、Claude、Aider等）
4. 独立验证结果
5. 验证失败时进入修复循环
6. 只有通过验证的任务才能被勾选

这种设计防止了"假完成"——代理声称完成但实际未达标的情况。

## 关键特性详解

### 工具无关性

rundown不绑定特定AI工具，而是通过标准CLI接口与任何代理工具集成。这种设计让团队可以根据场景选择最合适的工具，而不被锁定在单一平台。

### 模板驱动的工作流

每个仓库通过`.rundown/`目录定义本地工作流模板：

- `execute.md`：执行提示模板
- `verify.md`：验证提示模板
- `repair.md`：修复提示模板
- `plan.md`：规划提示模板
- `trace.md`：追踪和审计模板

这种模板化让不同项目可以定义适合自己领域的工作流规范，同时保持一致的执行框架。

### 上下文感知执行

rundown支持在Markdown中使用代码围栏（code fences）定义CLI命令，这些命令可以在构建提示时直接执行并注入结果。这种设计让文档本身成为动态的、自包含的工作负载定义。

### 文件级锁定机制

为了防止并发编辑或并行运行导致的数据损坏，rundown在操作Markdown文件时使用文件级锁。如果进程崩溃留下僵死锁，可以通过`rundown unlock`命令或`--force-unlock`选项恢复。

### 回滚能力

rundown支持任务回滚，但前提是任务最初使用`--commit`和`--keep-artifacts`标志执行。这种设计鼓励团队在关键任务中保留执行痕迹，为故障恢复提供基础。

## 实际应用场景

### 发布准备清单

想象一个软件发布流程，在Markdown中定义：

```markdown
# Release prep

Context: this branch is stabilizing the release candidate.

- [x] Confirm the release branch
- [ ] Rewrite the README opening around the new product position
- [ ] cli: npm test
- [ ] Verify the installation flow on Windows PowerShell
```

通过`rundown run . -- opencode run`，这个清单变成了可执行的程序，而不是静态的待办事项。

### 项目路线图管理

团队可以在roadmap.md中定义季度目标，每个目标分解为可执行的任务。rundown确保任务按正确顺序执行，验证每个阶段的产出，并在失败时自动修复或上报。

### 自动化文档维护

对于需要定期更新的文档（如API参考、状态页面），可以定义自动化任务：检查数据源、生成更新、验证格式、提交变更。rundown将这些维护工作从人工提醒转变为自动执行。

## 与其他工具的对比

### 与传统任务运行器（Make、Just）

传统工具专注于命令执行，而rundown专注于AI代理工作流。它理解Markdown结构、处理自然语言上下文、支持验证和修复循环——这些都是为AI代理场景设计的特性。

### 与AI代理平台（Claude Code、OpenCode）

rundown不是替代这些工具，而是增强它们。它提供了一个结构化的工作负载管理层，让代理工具可以更有效地执行复杂、多步骤的任务。

### 与项目管理工具（Jira、Linear）

rundown的复选框可能看起来像任务列表，但本质不同。它是可执行的、有验证的、与代码仓库紧密集成的。状态变化由实际执行驱动，而不是人工更新。

## 技术实现细节

rundown使用Node.js/TypeScript开发，通过npm全局安装。初始化命令`rundown init`创建本地配置目录，包含可定制的工作流模板。

任务选择算法基于文档结构和依赖关系，确保在存在子任务或前置条件时按正确顺序执行。这种确定性对于可重现的构建和部署流程至关重要。

## 对AI工程实践的启示

rundown代表了一种重要的范式转变：从将AI视为对话伙伴，到将AI视为可编程的工作负载执行者。

在对话模式中，用户和AI通过来回交流完成任务。在rundown模式中，用户定义工作负载，AI执行并验证，交流被结构化的契约所取代。

这种模式更适合：
- 重复性任务
- 多步骤流程
- 需要质量把关的工作
- 团队协作场景

它降低了AI使用的认知负担——用户不需要记住复杂的提示技巧，只需定义清晰的目标和验收标准。

## 局限性与注意事项

rundown目前处于RC（发布候选）阶段，API和配置格式可能仍有变化。团队在生产环境使用前应该评估稳定性需求。

此外，rundown的有效性高度依赖于验证步骤的质量。如果验证标准定义模糊，"假完成"问题仍可能出现。投资设计好的验证提示是使用rundown的关键成功因素。

## 总结

rundown为AI代理工作流带来了基础设施级别的可靠性。通过将Markdown从静态文档转变为可执行工作负载，它解决了代理执行中的确定性、可验证性和可观测性问题。

对于正在规模化使用AI代理的团队，rundown提供了一个值得评估的工作流管理层。它可能不会取代现有的项目管理工具，但可以作为AI执行层的可靠基础，确保代理工作真正完成，而不仅仅是看起来完成。