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

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\nbash\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\nbash\n# 查看当前状态\nassembly status repo-health-digest\n\n# 从特定阶段重试\nassembly retry repo-health-digest --from score\n\n\n因为状态保存在普通 JSON 文件中，不存在"锁定"或"隐藏状态"的问题。\n\n## 实际使用示例\n\n### 启动守护进程\n\nbash\n# 复制环境配置\ncp .env.example .env\n# 编辑 .env 设置 ANTHROPIC_API_KEY\n\n# 启动守护进程\nassembly daemon start\n\n\n### 提交任务\n\nbash\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\nbash\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\nrepo-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 提供了一个值得尝试的轻量级替代方案。

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\n1. 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\n2. Station（阶段）\n\n一个包含 AGENT.md（前置信息+系统提示）的文件夹。可选包含 EVAL.md 或 script.ts。\n\n- 确定性阶段：使用 .ts 脚本，完全可预测\n- LLM 阶段：仅使用 AGENT.md，由大模型处理\n- 评估门控：使用 EVAL.md 决定是否继续或重试\n\n3. Workpiece（工件）\n\n一个 JSON 文件，在阶段间传递时累积结果。它记录了每个阶段的输出，形成完整的工作轨迹。\n\n4. Envelope（信封）\n\n每个阶段返回的标准格式：{ summary, content, data }。这种统一接口使得阶段之间可以无缝协作。\n\n设计哲学：文件即真相\n\nAssembly 的核心设计理念是"文件即真相"（files as source of truth）：\n\n可审计性\n\nbash\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\nbash\n查看当前状态\nassembly status repo-health-digest\n\n从特定阶段重试\nassembly retry repo-health-digest --from score\n\n\n因为状态保存在普通 JSON 文件中，不存在"锁定"或"隐藏状态"的问题。\n\n实际使用示例\n\n启动守护进程\n\nbash\n复制环境配置\ncp .env.example .env\n编辑 .env 设置 ANTHROPIC_API_KEY\n\n启动守护进程\nassembly daemon start\n\n\n提交任务\n\nbash\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\nbash\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\nrepo-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 提供了一个值得尝试的轻量级替代方案。