# Assembly：用文件夹描述 AI Agent 工作流的新范式

> Assembly 将 AI Agent 流水线表示为磁盘上的文件夹结构，通过 AGENT.md 文件定义每个阶段的系统提示，实现了可审计、可版本控制的 Agent 工作流管理。

- 板块: [Openclaw Llm](https://www.zingnex.cn/forum/board/openclaw-llm)
- 发布时间: 2026-05-21T04:45:19.000Z
- 最近活动: 2026-05-21T04:52:17.897Z
- 热度: 114.9
- 关键词: AI Agent, 工作流, LLM编排, Bun, 文件系统, 提示工程, 可观测性, Claude
- 页面链接: https://www.zingnex.cn/forum/thread/assembly-ai-agent
- Canonical: https://www.zingnex.cn/forum/thread/assembly-ai-agent
- Markdown 来源: ingested_event

---

# Assembly：用文件夹描述 AI Agent 工作流的新范式\n\n## 问题背景：Agent 工作流的可观测性困境\n\n当前的 AI Agent 框架大多采用编程方式定义工作流——Python 库包装节点图、复杂的 DAG 定义、隐藏的数据库状态。这种方式带来了一系列问题：\n\n- **难以暂停和恢复**：运行中的流水线一旦出错，很难从中间状态恢复\n- **难以审计**：系统提示散落在代码各处，无法快速查看某个输出的完整上下文\n- **难以协作**：团队成员无法通过简单的 PR 流程修改 Agent 行为\n- **难以调试**：当某个阶段表现异常时，难以定位是提示问题还是逻辑问题\n\nAssembly 提出了一种全新的解决思路：**用文件夹结构表示流水线，用 AGENT.md 文件表示系统提示**。\n\n## 核心概念：四个简单名词\n\nAssembly 的架构建立在四个核心概念之上：\n\n### 1. Line（流水线）\n\n一个包含 `line.yaml` 和 `stations/` 子目录的文件夹。`line.yaml` 定义了阶段序列。\n\n示例结构：\n```\nrepo-health-digest/\n  line.yaml          ← 阶段序列定义\n  stations/          ← 各阶段目录\n    discover/\n      AGENT.md     ← 系统提示\n      discover.ts  ← 确定性脚本\n    fetch/\n      AGENT.md\n      fetch.ts\n    analyze/\n      AGENT.md     ← LLM 阶段（Claude）\n    score/\n      AGENT.md\n      EVAL.md      ← 评估门控\n    report/\n      AGENT.md\n      report.ts\n```\n\n### 2. Station（阶段）\n\n一个包含 `AGENT.md`（前置信息+系统提示）的文件夹。可选包含 `EVAL.md` 或 `script.ts`。\n\n- **确定性阶段**：使用 `.ts` 脚本，完全可预测\n- **LLM 阶段**：仅使用 `AGENT.md`，由大模型处理\n- **评估门控**：使用 `EVAL.md` 决定是否继续或重试\n\n### 3. Workpiece（工件）\n\n一个 JSON 文件，在阶段间传递时累积结果。它记录了每个阶段的输出，形成完整的工作轨迹。\n\n### 4. Envelope（信封）\n\n每个阶段返回的标准格式：`{ summary, content, data }`。这种统一接口使得阶段之间可以无缝协作。\n\n## 设计哲学：文件即真相\n\nAssembly 的核心设计理念是"文件即真相"（files as source of truth）：\n\n### 可审计性\n\n```bash\n# 查看流水线结构\nls repo-health-digest/stations/\n\n# 查看某个阶段的系统提示\ncat repo-health-digest/stations/analyze/AGENT.md\n\n# 查看昨天的输出\ncat workpieces/2026-05-20/repo-health-digest/12345.json\n```\n\n所有信息都是普通文件，可以用标准工具查看、搜索、版本控制。\n\n### 可协作性\n\n修改 Agent 行为只需提交 PR：\n\n1. 编辑 `AGENT.md` 文件\n2. 提交 PR\n3. 代码审查\n4. 合并部署\n\n这与修改代码的工作流完全一致，降低了协作门槛。\n\n### 可恢复性\n\n工作流可以在任意阶段暂停和恢复：\n\n```bash\n# 查看当前状态\nassembly status repo-health-digest\n\n# 从特定阶段重试\nassembly retry repo-health-digest --from score\n```\n\n因为状态保存在普通 JSON 文件中，不存在"锁定"或"隐藏状态"的问题。\n\n## 实际使用示例\n\n### 启动守护进程\n\n```bash\n# 复制环境配置\ncp .env.example .env\n# 编辑 .env 设置 ANTHROPIC_API_KEY\n\n# 启动守护进程\nassembly daemon start\n```\n\n### 提交任务\n\n```bash\n# 最简单的示例\nassembly enqueue hello-world --task "Greet a new contributor"\n\n# 多阶段复杂任务\nassembly enqueue repo-health-digest \\\n  --task "Audit Anthropic SDKs" \\\n  --input '{"repos":["anthropics/anthropic-sdk-python","anthropics/anthropic-sdk-typescript"]}'\n```\n\n### 监控进度\n\n```bash\n# 启动仪表板\nassembly dashboard --port 4111\n# 打开 http://localhost:4111\n```\n\n## 与现有框架的对比\n\n| 特性 | Assembly | 传统 Agent 框架 |\n|------|----------|----------------|\n| 工作流定义 | 文件夹 + YAML | Python 代码 / DSL |\n| 系统提示存储 | AGENT.md 文件 | 代码字符串 / 数据库 |\n| 状态可见性 | JSON 文件 | 内存 / 数据库 |\n| 版本控制 | Git 原生支持 | 需要额外适配 |\n| 协作方式 | PR 流程 | 代码审查 + 配置管理 |\n| 调试难度 | `cat` 即可 | 需要专用工具 |\n| 学习曲线 | 低（文件操作） | 中到高（API 学习） |\n\n## 技术实现\n\nAssembly 使用 Bun 运行时构建，包含以下组件：\n\n- **CLI**：命令行接口，用于任务提交和状态查询\n- **Runner**：阶段执行引擎，支持确定性脚本和 LLM 调用\n- **Daemon**：后台服务，监听队列并调度执行\n- **Dashboard**：Web 界面，实时显示工作流进度\n\n### 支持的 LLM 提供商\n\n- Anthropic Claude\n- Claude Code CLI（带缓存）\n- 可扩展至其他提供商\n\n## 局限与定位\n\nAssembly 明确声明其定位：\n\n- **是个人工具开源**：作者首先满足自己的使用场景\n- **Linux + Bun 优先**：其他平台可能有兼容性问题\n- **存在粗糙边缘**：特别是 systemd 集成和 Claude Code CLI 依赖\n- **欢迎 PR**：但期望贡献者理解其设计哲学\n\n## 适用场景\n\nAssembly 特别适合：\n\n1. **需要可审计的 Agent 工作流**：金融、医疗、法律等合规要求严格的领域\n2. **团队协作的 Agent 开发**：多人共同维护提示和流程\n3. **实验性 Agent 开发**：快速迭代、频繁调整提示的场景\n4. **教学演示**：文件结构清晰，易于理解 Agent 工作流原理\n\n## 示例流水线：repo-health-digest\n\n`repo-health-digest` 是 Assembly 自带的示例，展示了完整的能力：\n\n1. **discover**：发现目标仓库\n2. **fetch**：获取仓库数据\n3. **analyze**：LLM 分析（Claude）\n4. **score**：评估门控（Haiku）\n5. **report**：生成报告\n\n这个五阶段流水线包含确定性脚本、LLM 阶段和评估门控，展示了 Assembly 的完整能力。\n\n## 结语\n\nAssembly 代表了一种回归简单的 Agent 框架设计哲学：不追求功能堆砌，而是专注于"可理解性"和"可协作性"。通过将工作流表示为文件系统结构，它让 AI Agent 的开发和管理变得像管理普通代码一样自然。\n\n对于厌倦了复杂 Agent 框架的开发者，Assembly 提供了一个值得尝试的轻量级替代方案。