1. 项目概述从“智能生成”到“工程化流程”的探索最近几个月我一直在折腾一个在AI编程领域反复出现的老问题模型能力日新月异但围绕它们构建的工程化工作流却依然脆弱不堪。相信很多尝试过GitHub Copilot、Cursor或者各类AI Agent的朋友都有同感——这些工具在“生成代码片段”这件事上确实惊艳能快速带来开发上的“动量”。但当你真的想把一个从零开始的想法变成一个可运行、可测试、可协作的完整软件项目时整个流程就开始变得摇摇欲坠。你会发现从项目初始化、任务拆解、角色分工到代码审查、测试验证乃至流程卡住时的恢复和整体可观测性这些“脏活累活”往往还是得靠人工来缝缝补补。这正是我着手开发Fabrica的初衷。它不是一个宣称要“取代开发团队”的魔法黑盒而是一个为OpenClaw设计的开源插件核心目标是探索如何为AI驱动的编码工作流套上一层更结构化、可审计、可预测且易于运维的工程外壳。简单说它的价值不在于让AI写更多代码而在于让AI写代码的整个过程变得像我们熟悉的软件工程实践一样有章可循、有迹可查、出了问题知道怎么修。2. 核心理念与架构设计为何选择确定性状态机2.1 从“散装提示词”到“装配线式工作流”当前大多数AI编码代理的工作模式可以比喻成一位技艺高超但随心所欲的工匠。你给他一个需求提示词他可能给你雕出一朵花也可能给你造出一艘船过程不透明结果难预测一旦出错你很难定位是需求理解偏差、工具使用不当还是中间某一步计算出了问题。这种“黑盒生成”模式在单次任务中或许高效但在需要多次迭代、多人协作、具备明确质量门禁的软件项目中就显得力不从心了。Fabrica的设计哲学是试图将这位“自由工匠”纳入一条现代化的“软件装配线”。这条装配线有明确的工序Intake, Spec, Development, Review, Test, Merge每个工序由专门的“工人”AI Agent负责工序之间有标准的交接件如需求规格书、GitHub Issue、Pull Request整个流水线由一个确定性的“调度系统”有限状态机来驱动和监控。这样做的核心好处有三个可观测性 (Observability)每个环节的输入、输出和状态都是明确的。你可以清楚地看到项目当前在哪个阶段卡在了哪里上一次Agent执行的具体任务和结果是什么。可干预性 (Intervention)因为流程是结构化的所以当流程偏离预期或陷入循环时系统可以执行预设的“修复策略”Repair Pass或者更容易地引入人工判断点Human-in-the-loop。可复用与可测试 (Reusability Testability)每个环节如“代码审查Agent”都可以被单独测试、评估和优化。整个工作流也可以像代码一样进行版本管理和迭代。2.2 核心架构基于有限状态机的智能体编排Fabrica的核心是一个确定性有限状态机 (Deterministic Finite State Machine)。这个选择并非偶然而是基于对“稳定性”和“可调试性”的优先考虑。为什么是状态机而不是更“智能”的LLM Orchestrator市面上有些方案倾向于用一个“超级大脑”LLM来动态决定下一步做什么。这听起来很灵活但引入了巨大的不确定性同一个输入模型可能因为微小的随机性做出不同的路由决策导致流程不可复现调试时如同大海捞针。状态机虽然看似“笨拙”但它提供了绝对的确定性和可预测性。在Fabrica中流程的每一步转移都基于明确的条件如“PR是否已创建”、“审查是否通过”这些条件大多来自GitHub API的确定状态或CI/CD流水线的确定结果而非LLM的随机输出。这为整个系统奠定了可靠性的基石。这个状态机驱动着以下几个核心角色Agent的协作产品经理/需求分析师 (Intake Spec Agent)负责将用户模糊的自然语言描述通过多轮对话Interview澄清转化为结构化的软件需求规格说明。开发工程师 (Developer Agent)根据规格说明和拆解后的任务GitHub Issue进行实际的代码编写、模块实现并提交Pull Request。代码审查员 (Reviewer Agent)对提交的PR进行代码审查检查代码风格、逻辑错误、潜在风险并提出修改意见或批准合并。测试工程师 (Tester Agent)在代码合并前或合并后执行自动化测试或根据测试计划进行验证并提交测试结果作为证据。运维监控 (Doctor Metrics Agent)这是一个后台角色持续监控整个工作流的心跳默认60秒一次执行修复操作如重试失败的任务、重置僵尸状态并收集系统运行指标。整个系统的数据流和状态转移都通过GitHub的Issue、PR、Commit、Check Run等原生能力进行承载和同步这使得Fabrica能够无缝集成到现有的开发实践中所有产出物都是开发团队熟悉的形式。3. Fabrica工作流全链路拆解与实操3.1 阶段一需求摄入与规格化 (Intake Specification)一切始于一个想法。用户可以通过Telegram机器人或CLI命令行向Fabrica发送一段自然语言描述例如“帮我创建一个简单的待办事项Web应用使用Next.js 14和Prisma需要用户认证和基本的CRUD操作。”1. 分类与澄清访谈 (Classify Interview)Fabrica的Intake Agent首先会尝试对输入进行粗粒度分类如“Web全栈项目”、“数据脚本”、“API服务”。然后它会启动一个多轮澄清对话。这一步至关重要是避免后续开发方向性错误的关键。Agent会像一位经验丰富的产品经理一样提出一系列问题来补全信息缺口“您期望的部署方式是什么Vercel、Docker还是其他”“对于用户认证有偏好的方案吗比如NextAuth.js、Clerk”“待办事项需要哪些字段除了标题需要截止日期、优先级、分类标签吗”“前端UI有特定的组件库偏好吗比如Shadcn/ui, MUI”这个过程会持续到Agent认为它已经获得了足够编写一份初步需求规格说明的信息。所有问答历史都会被记录下来作为需求追溯的依据。2. 生成结构化规格说明 (Generate Spec)基于访谈结果Spec Agent会生成一份结构化的Markdown文档。这份文档远不止是用户输入的复述它会包含项目概述项目目标、核心用户、价值主张。技术栈选型明确的前端、后端、数据库、部署平台等。功能清单 (Feature List)拆解为Epic或用户故事。非功能需求如性能、安全性、可访问性考虑。初步的架构草图例如描述数据流、主要的组件和服务。验收标准 (Acceptance Criteria)为每个主要功能点定义明确的完成标准。这份规格说明会作为GitHub Wiki页面或项目根目录下的SPEC.md文件被创建并成为后续所有开发活动的“宪法”。实操心得让AI学会“提问”比让它“回答”更难在设计Intake Agent时最大的挑战不是生成答案而是设计出有效的提问逻辑。我们通过Few-shot Prompting为Agent提供了大量“优秀产品需求访谈”的示例教会它识别模糊词汇如“好用”、“快速”并将其转化为可追问的具体问题“您指的‘快速’是页面加载时间低于1秒还是操作响应时间低于100毫秒”。同时我们为访谈设置了轮次上限例如5轮防止陷入无休止的细节追问在信息足够和效率之间取得平衡。3.2 阶段二任务分解与项目初始化 (Issue Decomposition Bootstrap)有了清晰的规格说明下一步就是将宏大的目标转化为可执行的小任务。1. 创建GitHub项目与仓库Fabrica会自动在关联的GitHub组织或个人账户下创建一个新的仓库。仓库的命名、描述、.gitignore模板、开源许可证如MIT都会根据项目类型自动设置。它还会初始化一个基本的GitHub Project板用于可视化跟踪任务状态。2. 智能任务拆解 (Issue Creation)这是体现工程化思维的关键一步。Developer Agent此时扮演架构师角色会阅读SPEC.md并按照“自上而下、逐步求精”的原则创建一系列GitHub Issues。拆解逻辑通常遵循以下模式Epic级Issue如“实现用户认证系统”。Feature级Issue隶属于Epic如“设置NextAuth.js提供商”、“设计用户登录/注册UI组件”、“实现受保护的路由中间件”。Task级Issue更具体的开发任务如“创建lib/auth.ts文件配置NextAuth.js选项”、“在app/api/auth/[...nextauth]/route.ts中实现Credential Provider”、“创建components/auth/login-form.tsx组件”。每个Issue都会包含清晰的描述、关联的规格说明章节、以及实现该任务可能需要修改或创建的文件列表。这些Issue会被自动分配到GitHub Project的“待办”列。3. 项目脚手架生成在拆解任务的同时Fabrica会并行执行项目脚手架生成。它根据选定的技术栈如Next.js Prisma Tailwind CSS运行标准的CLI命令如npx create-next-applatest并集成必要的依赖和基础配置。这确保了开发环境的一致性让Developer Agent可以从一个“正确”的起点开始编码而不是从零开始处理繁琐的配置。3.3 阶段三开发、审查、测试的自动化循环这是工作流的核心执行阶段三个角色Agent在状态机的调度下循环协作。1. 开发阶段 (Developer Agent)状态机监测到有处于“待开发”状态的Issue。Developer Agent被唤醒它的工作流程是获取上下文读取Issue描述、关联的代码文件、整个仓库的当前状态。规划实现在内部Agent会先“思考”一个实现计划我们通过Chain-of-Thought prompting来让这个过程可见于日志列出将要修改的文件和大致改动。执行编码Agent在本地或隔离的沙盒环境中执行代码修改。它不仅仅生成代码片段还会执行必要的终端命令如安装新包 (npm install)、运行数据库迁移 (npx prisma migrate dev)。提交与推送完成编码后Agent会创建Git Commit并推送到一个新的分支分支名通常与Issue号关联如feature/auth-1。创建Pull Request最后Agent会自动创建一个PR将更改关联到原Issue并填写PR描述概述所做的更改。完成后它将Issue和PR的状态标记为“等待审查”。2. 审查阶段 (Reviewer Agent)当PR被创建后状态机触发Reviewer Agent。它的审查不是形式化的而是基于一系列预设的、可配置的规则和LLM的深度分析代码风格检查是否遵循项目约定的规范通过集成ESLint、Prettier规则进行提示。逻辑与安全审查LLM会分析代码变更寻找潜在的bug、安全漏洞如SQL注入风险、性能问题或不符合需求规格的地方。生成审查意见Reviewer Agent会在PR中留下详细的评论可能包括“建议将这段逻辑提取为独立函数以提高可读性”或“此处缺少对空值的处理可能导致运行时错误”。决策如果审查通过Agent会批准PR如果发现问题它会“请求更改”并将状态打回给Developer Agent。3. 测试阶段 (Tester Agent)当PR获得批准后或根据配置在合并前Tester Agent开始工作。它的任务不是编写测试用例那属于开发阶段而是执行验证运行自动化测试触发项目的测试套件如Jest, Playwright。执行端到端流程验证对于Web应用它可能启动一个预览环境并模拟用户执行关键路径如注册、登录、创建待办项。提交证据将测试结果通过/失败、测试日志、甚至屏幕截图作为评论附在PR中。如果测试失败它会自动将状态置为“失败”并通知相关Agent。4. 合并与收尾 (Merge)当所有关卡审查批准、测试通过都满足后状态机自动执行PR合并操作并关闭关联的GitHub Issue。整个功能点的开发流程就此完成。注意事项避免“过度自动化”的陷阱在这个循环中我们设置了明确的“人工介入点”。例如可以配置规则任何涉及数据库模式变更或核心依赖升级的PR必须等待人工最终批准。Fabrica的仪表板会高亮显示这些等待人工决策的项目。完全无人值守的自动化在复杂项目中风险极高我们的目标是“自动化一切可自动化的但清晰地暴露和控制那些必须由人决策的点”。3.4 阶段四修复、监控与可观测性这是Fabrica区别于许多“一次性演示”项目的关键——它为自己配备了“维修工”和“仪表盘”。1. 修复通道 (Repair Pass)系统以60秒为心跳周期进行自检。在每个周期它会执行一个修复扫描处理以下典型问题僵尸状态某个Issue或PR长时间如30分钟无状态更新可能因为网络超时或Agent意外崩溃。修复通道会重置其状态并触发重试。环境不一致检测到本地开发环境与预期不符如缺少某个关键环境变量尝试根据项目规范进行修复或发出明确告警。循环检测如果同一个Issue在“开发-审查-请求更改”之间循环超过一定次数如3次系统会将其标记为“需要人工介入”并通知维护者防止无限循环消耗资源。2. 医生诊断与指标 (Doctor Metrics)Fabrica内置了一个诊断模块持续收集系统指标Agent性能指标每个Agent任务的平均执行时间、成功率、失败原因分布。工作流效率指标从Issue创建到关闭的平均周期时间、各阶段开发、审查、测试的耗时占比。资源消耗API调用次数特别是昂贵模型API、计算资源使用情况。 这些指标通过简单的仪表板或日志输出帮助维护者了解系统健康度定位瓶颈例如是否总是在“代码审查”阶段耗时过长。3. 可观测性输出所有Agent的思考过程、执行命令、API调用和决策日志都以结构化的方式如JSONL格式输出到指定位置。这意味着当流程出现意外结果时你可以像查看分布式系统的追踪日志一样回溯整个决策链精确定位是哪个Agent、在哪个步骤、基于什么信息做出了错误判断。这为调试和迭代工作流本身提供了可能。4. 实战部署、问题排查与调优指南4.1 环境准备与快速启动Fabrica的设计目标是易于部署和集成。目前它主要作为OpenClaw的插件运行。1. 前提条件OpenClaw环境一个已经安装并配置好的OpenClaw实例。OpenClaw提供了AI Agent执行的基础运行时。GitHub账户与Token你需要一个GitHub账号并生成一个具有足够权限的Personal Access Token需要repo,workflow,project等作用域用于Fabrica自动化操作仓库、项目和PR。AI模型API密钥Fabrica的各个Agent需要大语言模型驱动。你需要准备OpenAI GPT-4/3.5-Turbo、Anthropic Claude或类似模型的API密钥。建议使用性能更强的模型如GPT-4用于复杂的规划和审查任务以提升整体效果。2. 安装与配置# 1. 克隆Fabrica仓库到你的OpenClaw插件目录 git clone https://github.com/MestreY0d4-Uninter/fabrica.git /path/to/openclaw/plugins/ # 2. 安装Python依赖Fabrica通常是一个Python插件 cd /path/to/openclaw/plugins/fabrica pip install -r requirements.txt # 3. 配置环境变量 # 在你的OpenClaw环境或Fabrica配置文件中设置以下关键变量 export GITHUB_TOKENyour_github_personal_access_token export OPENAI_API_KEYyour_openai_api_key # 可选配置其他模型、日志路径、心跳间隔等 export FABRICA_HEARTBEAT_INTERVAL60 export FABRICA_LOG_LEVELINFO3. 启动与触发配置完成后在OpenClaw中启用Fabrica插件。触发工作流有两种主要方式Telegram机器人向绑定的Bot发送消息/startproject 项目描述...。CLI命令在OpenClaw的CLI中执行fabrica start --description 项目描述...。启动后你就可以在GitHub上看到自动创建的仓库、项目板和第一个Issue整个流水线开始运转。4.2 常见问题与故障排查实录在实际使用和测试中我们遇到了不少典型问题。以下是排查思路和解决方案的速查表。问题现象可能原因排查步骤与解决方案Intake Agent陷入无限问答循环用户需求过于模糊或开放Agent无法形成有效判断。Prompt中缺少终止访谈的明确条件。1. 检查日志看Agent反复询问的问题是否类似。2. 优化Intake Agent的Prompt加入更明确的终止规则例如“如果连续两轮问答都未获取到关于[技术栈/核心功能/部署目标]的新信息则结束访谈基于已有信息生成规格。”3. 在UI/CLI中为用户提供“强制结束访谈并继续”的选项。Developer Agent生成的代码无法通过基础编译Agent使用的上下文可能不完整如未包含package.json或对项目框架的理解有偏差。1. 检查Agent执行任务时的“工作目录”和“上下文文件列表”。确保它能看到所有必要的配置文件。2. 在项目脚手架阶段生成一个更详细、包含常见问题解答的README_DEV.md给Agent参考。3. 引入一个轻量级的“编译检查”步骤在Agent提交代码前自动运行npm run build或tsc --noEmit如果失败则让Agent根据错误信息自行修复。Reviewer Agent批准了明显有错误的代码审查Prompt不够严格或使用的模型能力不足如用了GPT-3.5-Turbo审查复杂逻辑。1. 升级Reviewer Agent使用的模型为GPT-4或Claude-3 Opus。2. 细化审查规则Prompt要求其必须检查具体的错误模式例如“请检查1. 异步函数是否正确处理了错误2. API路由是否校验了用户输入3. 数据库查询是否避免了N1问题”3. 将自动化静态分析工具如SonarQube扫描结果作为上下文提供给Reviewer Agent让其结合分析报告进行审查。整个流程在某个Issue上卡住状态无更新心跳线程崩溃Agent任务因超时或异常而静默失败遇到了需要人工干预但未配置通知的情况。1.首先查看Doctor日志这是第一现场。日志会记录最后一次心跳活动、各个Agent任务的状态和可能的错误信息。2.检查GitHub API速率限制过多的API调用可能导致临时封禁。查看日志中是否有429错误。解决方案是增加请求间隔或使用GitHub App安装方式以获得更高限额。3.手动执行修复Fabrica CLI通常提供fabrica doctor --fix命令尝试自动修复僵尸状态。如果不行通过fabrica issue --retry issue_number手动重试特定任务。Tester Agent无法成功运行端到端测试测试环境如浏览器、数据库未正确配置或启动测试用例本身依赖未准备好的数据。1. 确保项目脚手架中包含了可靠的测试环境配置如docker-compose.test.yml。2. 让Tester Agent在运行测试前先执行环境准备脚本。3. 对于E2E测试提供更详细的“测试准备指南”给Agent或考虑在初期先只运行单元测试E2E测试由人工触发。生成的代码风格与团队规范不符缺乏统一的代码风格定义和检查工具集成。1. 在项目初始化时必须集成ESLint和Prettier并提交配置文件.eslintrc.js,.prettierrc。2. 在Developer Agent的Prompt中明确强调“所有代码必须通过项目ESLint和Prettier检查”。3. 在GitHub Actions中配置CI在PR创建时自动运行linting如果失败则阻塞合并让Agent必须修复。4.3 性能调优与成本控制建议运行一个全自动化的AI工作流性能和成本是无法回避的问题。1. 模型策略优化分层使用模型不要所有任务都用最贵的模型。将任务分类高创造性、高复杂度的任务如架构设计、复杂逻辑审查使用GPT-4中等任务如代码生成、简单审查使用Claude-3 Sonnet或GPT-3.5-Turbo低复杂度任务如格式化、简单命令执行使用廉价的小模型或规则引擎。上下文长度管理LLM API收费通常与输入输出的token数相关。优化Prompt去除冗余信息。对于长上下文如整个代码库优先使用RAG技术检索相关片段而不是全量喂入。缓存与复用对于相似的Issue或任务如“创建另一个CRUD API”Agent的解决方案可能类似。可以引入简单的缓存机制存储“问题-解决方案”对在遇到高度相似的新问题时优先尝试复用减少API调用。2. 流程效率优化并行化可行任务如果项目中有多个独立的Feature Issue如“开发登录页面”和“设计数据库Schema”可以配置Fabrica尝试并行开发由不同的Developer Agent实例处理前提是它们之间没有依赖关系。设置超时与重试策略为每个Agent任务设置合理的超时时间如10分钟。超时后自动重试最多2-3次如果仍然失败则升级为需要人工处理的故障。精简“修复通道”扫描范围随着项目规模变大每次心跳都全量扫描所有Issue/PR可能低效。可以改为只扫描“进行中”状态的项目或者增量扫描自上次心跳后有变更的项目。3. 成本监控详细日志记录确保每一次LLM API调用的模型、输入输出token数都被记录。设置预算告警利用云服务商的监控功能或自己编写脚本当日/周/月的API调用费用超过阈值时发送告警并暂停非核心任务。评估ROI定期回顾对比Fabrica自动化完成的任务所花费的API成本与工程师手动完成同等任务的时间成本。这有助于判断自动化在哪些场景下是经济高效的。5. 设计反思、局限性与未来演进方向构建Fabrica的过程是一个不断在“自动化理想”与“工程现实”之间寻找平衡点的过程。它目前远非完美更像一个功能齐备但需要精心调校的“原型车间”。1. 当前的主要局限性对复杂、模糊需求的驾驭能力有限虽然Intake Agent能进行多轮澄清但对于极其抽象或充满内在矛盾的需求这在真实业务中很常见它仍然可能生成有偏差的规格导致后续开发全盘跑偏。人类的早期深度介入仍然不可替代。“理解”而非“真正理解”Agent们基于模式匹配和概率生成来“理解”代码和需求。它们能出色地处理模式化的任务创建标准CRUD API、实现常见UI组件但对于需要深刻领域知识、复杂业务逻辑或创造性算法设计的任务其输出质量不稳定需要大量人工复审和修正。调试与纠错成本不低当工作流出错时尽管有日志但调试一个由多个AI Agent和状态机组成的分布式系统其心智负担有时甚至高于直接手动编写代码。你需要理解每个Agent的决策上下文、Prompt的意图以及状态机的转移逻辑。初始配置与调优门槛让Fabrica在一个新团队或新项目类型中良好运行需要不少前期工作编写适合团队文化的Prompt模板、配置代码审查规则、设置测试环境等。它不是一个“开箱即用万物皆可自动”的解决方案。2. 设计中的关键权衡确定性与灵活性的权衡我们选择了确定性状态机牺牲了动态工作流生成的灵活性换来了可预测性和可调试性。这对于追求稳定性的工程场景是值得的。自动化程度与人工控制的权衡我们刻意避免了“全自动”的噱头而是设计了明确的人工介入点。这看起来不够“智能”但大大提高了系统的实用性和安全性。真正的“智能”是知道何时该自动何时该交给人。通用性与专用性的权衡Fabrica试图提供一个通用的软件工程工作流框架。但实践中为特定类型项目如前端React应用、数据ETL管道定制专属的Agent技能和流程模板效果会好得多。未来的方向可能是提供一个核心引擎可插拔的“领域适配器”。3. 我期待的反馈与演进方向如果你对这类工具感兴趣我特别希望听到以下几方面的反馈架构层面状态机的设计是否过于僵化是否有更优雅的编排模式如基于事件的驱动在保持确定性的同时提供更多灵活性用户体验对于想要尝试的开发者当前的安装、配置和启动流程是否足够清晰哪里让你感到困惑故障处理在实际运行中你遇到的最棘手的故障是什么现有的“修复通道”和“医生”诊断是否帮你解决了问题价值判断在使用了这类工具后你觉得它带来的结构化和自动化收益是否抵得上学习、配置和调试它所付出的成本在什么类型的项目或团队中它的性价比最高Fabrica的代码仓库完全公开它不是一个完美的产品而是一个诚实的实验。它的价值不在于展示了多炫酷的AI能力而在于认真对待了“将AI融入工程实践”时所必须面对的、琐碎却至关重要的工程问题。欢迎你来试用、批评、拆解或者告诉我对于你日常的软件开发工作流来说什么样的自动化辅助才是真正有用而非过度设计的。
Fabrica：基于确定性状态机的AI编程工程化工作流实践
1. 项目概述从“智能生成”到“工程化流程”的探索最近几个月我一直在折腾一个在AI编程领域反复出现的老问题模型能力日新月异但围绕它们构建的工程化工作流却依然脆弱不堪。相信很多尝试过GitHub Copilot、Cursor或者各类AI Agent的朋友都有同感——这些工具在“生成代码片段”这件事上确实惊艳能快速带来开发上的“动量”。但当你真的想把一个从零开始的想法变成一个可运行、可测试、可协作的完整软件项目时整个流程就开始变得摇摇欲坠。你会发现从项目初始化、任务拆解、角色分工到代码审查、测试验证乃至流程卡住时的恢复和整体可观测性这些“脏活累活”往往还是得靠人工来缝缝补补。这正是我着手开发Fabrica的初衷。它不是一个宣称要“取代开发团队”的魔法黑盒而是一个为OpenClaw设计的开源插件核心目标是探索如何为AI驱动的编码工作流套上一层更结构化、可审计、可预测且易于运维的工程外壳。简单说它的价值不在于让AI写更多代码而在于让AI写代码的整个过程变得像我们熟悉的软件工程实践一样有章可循、有迹可查、出了问题知道怎么修。2. 核心理念与架构设计为何选择确定性状态机2.1 从“散装提示词”到“装配线式工作流”当前大多数AI编码代理的工作模式可以比喻成一位技艺高超但随心所欲的工匠。你给他一个需求提示词他可能给你雕出一朵花也可能给你造出一艘船过程不透明结果难预测一旦出错你很难定位是需求理解偏差、工具使用不当还是中间某一步计算出了问题。这种“黑盒生成”模式在单次任务中或许高效但在需要多次迭代、多人协作、具备明确质量门禁的软件项目中就显得力不从心了。Fabrica的设计哲学是试图将这位“自由工匠”纳入一条现代化的“软件装配线”。这条装配线有明确的工序Intake, Spec, Development, Review, Test, Merge每个工序由专门的“工人”AI Agent负责工序之间有标准的交接件如需求规格书、GitHub Issue、Pull Request整个流水线由一个确定性的“调度系统”有限状态机来驱动和监控。这样做的核心好处有三个可观测性 (Observability)每个环节的输入、输出和状态都是明确的。你可以清楚地看到项目当前在哪个阶段卡在了哪里上一次Agent执行的具体任务和结果是什么。可干预性 (Intervention)因为流程是结构化的所以当流程偏离预期或陷入循环时系统可以执行预设的“修复策略”Repair Pass或者更容易地引入人工判断点Human-in-the-loop。可复用与可测试 (Reusability Testability)每个环节如“代码审查Agent”都可以被单独测试、评估和优化。整个工作流也可以像代码一样进行版本管理和迭代。2.2 核心架构基于有限状态机的智能体编排Fabrica的核心是一个确定性有限状态机 (Deterministic Finite State Machine)。这个选择并非偶然而是基于对“稳定性”和“可调试性”的优先考虑。为什么是状态机而不是更“智能”的LLM Orchestrator市面上有些方案倾向于用一个“超级大脑”LLM来动态决定下一步做什么。这听起来很灵活但引入了巨大的不确定性同一个输入模型可能因为微小的随机性做出不同的路由决策导致流程不可复现调试时如同大海捞针。状态机虽然看似“笨拙”但它提供了绝对的确定性和可预测性。在Fabrica中流程的每一步转移都基于明确的条件如“PR是否已创建”、“审查是否通过”这些条件大多来自GitHub API的确定状态或CI/CD流水线的确定结果而非LLM的随机输出。这为整个系统奠定了可靠性的基石。这个状态机驱动着以下几个核心角色Agent的协作产品经理/需求分析师 (Intake Spec Agent)负责将用户模糊的自然语言描述通过多轮对话Interview澄清转化为结构化的软件需求规格说明。开发工程师 (Developer Agent)根据规格说明和拆解后的任务GitHub Issue进行实际的代码编写、模块实现并提交Pull Request。代码审查员 (Reviewer Agent)对提交的PR进行代码审查检查代码风格、逻辑错误、潜在风险并提出修改意见或批准合并。测试工程师 (Tester Agent)在代码合并前或合并后执行自动化测试或根据测试计划进行验证并提交测试结果作为证据。运维监控 (Doctor Metrics Agent)这是一个后台角色持续监控整个工作流的心跳默认60秒一次执行修复操作如重试失败的任务、重置僵尸状态并收集系统运行指标。整个系统的数据流和状态转移都通过GitHub的Issue、PR、Commit、Check Run等原生能力进行承载和同步这使得Fabrica能够无缝集成到现有的开发实践中所有产出物都是开发团队熟悉的形式。3. Fabrica工作流全链路拆解与实操3.1 阶段一需求摄入与规格化 (Intake Specification)一切始于一个想法。用户可以通过Telegram机器人或CLI命令行向Fabrica发送一段自然语言描述例如“帮我创建一个简单的待办事项Web应用使用Next.js 14和Prisma需要用户认证和基本的CRUD操作。”1. 分类与澄清访谈 (Classify Interview)Fabrica的Intake Agent首先会尝试对输入进行粗粒度分类如“Web全栈项目”、“数据脚本”、“API服务”。然后它会启动一个多轮澄清对话。这一步至关重要是避免后续开发方向性错误的关键。Agent会像一位经验丰富的产品经理一样提出一系列问题来补全信息缺口“您期望的部署方式是什么Vercel、Docker还是其他”“对于用户认证有偏好的方案吗比如NextAuth.js、Clerk”“待办事项需要哪些字段除了标题需要截止日期、优先级、分类标签吗”“前端UI有特定的组件库偏好吗比如Shadcn/ui, MUI”这个过程会持续到Agent认为它已经获得了足够编写一份初步需求规格说明的信息。所有问答历史都会被记录下来作为需求追溯的依据。2. 生成结构化规格说明 (Generate Spec)基于访谈结果Spec Agent会生成一份结构化的Markdown文档。这份文档远不止是用户输入的复述它会包含项目概述项目目标、核心用户、价值主张。技术栈选型明确的前端、后端、数据库、部署平台等。功能清单 (Feature List)拆解为Epic或用户故事。非功能需求如性能、安全性、可访问性考虑。初步的架构草图例如描述数据流、主要的组件和服务。验收标准 (Acceptance Criteria)为每个主要功能点定义明确的完成标准。这份规格说明会作为GitHub Wiki页面或项目根目录下的SPEC.md文件被创建并成为后续所有开发活动的“宪法”。实操心得让AI学会“提问”比让它“回答”更难在设计Intake Agent时最大的挑战不是生成答案而是设计出有效的提问逻辑。我们通过Few-shot Prompting为Agent提供了大量“优秀产品需求访谈”的示例教会它识别模糊词汇如“好用”、“快速”并将其转化为可追问的具体问题“您指的‘快速’是页面加载时间低于1秒还是操作响应时间低于100毫秒”。同时我们为访谈设置了轮次上限例如5轮防止陷入无休止的细节追问在信息足够和效率之间取得平衡。3.2 阶段二任务分解与项目初始化 (Issue Decomposition Bootstrap)有了清晰的规格说明下一步就是将宏大的目标转化为可执行的小任务。1. 创建GitHub项目与仓库Fabrica会自动在关联的GitHub组织或个人账户下创建一个新的仓库。仓库的命名、描述、.gitignore模板、开源许可证如MIT都会根据项目类型自动设置。它还会初始化一个基本的GitHub Project板用于可视化跟踪任务状态。2. 智能任务拆解 (Issue Creation)这是体现工程化思维的关键一步。Developer Agent此时扮演架构师角色会阅读SPEC.md并按照“自上而下、逐步求精”的原则创建一系列GitHub Issues。拆解逻辑通常遵循以下模式Epic级Issue如“实现用户认证系统”。Feature级Issue隶属于Epic如“设置NextAuth.js提供商”、“设计用户登录/注册UI组件”、“实现受保护的路由中间件”。Task级Issue更具体的开发任务如“创建lib/auth.ts文件配置NextAuth.js选项”、“在app/api/auth/[...nextauth]/route.ts中实现Credential Provider”、“创建components/auth/login-form.tsx组件”。每个Issue都会包含清晰的描述、关联的规格说明章节、以及实现该任务可能需要修改或创建的文件列表。这些Issue会被自动分配到GitHub Project的“待办”列。3. 项目脚手架生成在拆解任务的同时Fabrica会并行执行项目脚手架生成。它根据选定的技术栈如Next.js Prisma Tailwind CSS运行标准的CLI命令如npx create-next-applatest并集成必要的依赖和基础配置。这确保了开发环境的一致性让Developer Agent可以从一个“正确”的起点开始编码而不是从零开始处理繁琐的配置。3.3 阶段三开发、审查、测试的自动化循环这是工作流的核心执行阶段三个角色Agent在状态机的调度下循环协作。1. 开发阶段 (Developer Agent)状态机监测到有处于“待开发”状态的Issue。Developer Agent被唤醒它的工作流程是获取上下文读取Issue描述、关联的代码文件、整个仓库的当前状态。规划实现在内部Agent会先“思考”一个实现计划我们通过Chain-of-Thought prompting来让这个过程可见于日志列出将要修改的文件和大致改动。执行编码Agent在本地或隔离的沙盒环境中执行代码修改。它不仅仅生成代码片段还会执行必要的终端命令如安装新包 (npm install)、运行数据库迁移 (npx prisma migrate dev)。提交与推送完成编码后Agent会创建Git Commit并推送到一个新的分支分支名通常与Issue号关联如feature/auth-1。创建Pull Request最后Agent会自动创建一个PR将更改关联到原Issue并填写PR描述概述所做的更改。完成后它将Issue和PR的状态标记为“等待审查”。2. 审查阶段 (Reviewer Agent)当PR被创建后状态机触发Reviewer Agent。它的审查不是形式化的而是基于一系列预设的、可配置的规则和LLM的深度分析代码风格检查是否遵循项目约定的规范通过集成ESLint、Prettier规则进行提示。逻辑与安全审查LLM会分析代码变更寻找潜在的bug、安全漏洞如SQL注入风险、性能问题或不符合需求规格的地方。生成审查意见Reviewer Agent会在PR中留下详细的评论可能包括“建议将这段逻辑提取为独立函数以提高可读性”或“此处缺少对空值的处理可能导致运行时错误”。决策如果审查通过Agent会批准PR如果发现问题它会“请求更改”并将状态打回给Developer Agent。3. 测试阶段 (Tester Agent)当PR获得批准后或根据配置在合并前Tester Agent开始工作。它的任务不是编写测试用例那属于开发阶段而是执行验证运行自动化测试触发项目的测试套件如Jest, Playwright。执行端到端流程验证对于Web应用它可能启动一个预览环境并模拟用户执行关键路径如注册、登录、创建待办项。提交证据将测试结果通过/失败、测试日志、甚至屏幕截图作为评论附在PR中。如果测试失败它会自动将状态置为“失败”并通知相关Agent。4. 合并与收尾 (Merge)当所有关卡审查批准、测试通过都满足后状态机自动执行PR合并操作并关闭关联的GitHub Issue。整个功能点的开发流程就此完成。注意事项避免“过度自动化”的陷阱在这个循环中我们设置了明确的“人工介入点”。例如可以配置规则任何涉及数据库模式变更或核心依赖升级的PR必须等待人工最终批准。Fabrica的仪表板会高亮显示这些等待人工决策的项目。完全无人值守的自动化在复杂项目中风险极高我们的目标是“自动化一切可自动化的但清晰地暴露和控制那些必须由人决策的点”。3.4 阶段四修复、监控与可观测性这是Fabrica区别于许多“一次性演示”项目的关键——它为自己配备了“维修工”和“仪表盘”。1. 修复通道 (Repair Pass)系统以60秒为心跳周期进行自检。在每个周期它会执行一个修复扫描处理以下典型问题僵尸状态某个Issue或PR长时间如30分钟无状态更新可能因为网络超时或Agent意外崩溃。修复通道会重置其状态并触发重试。环境不一致检测到本地开发环境与预期不符如缺少某个关键环境变量尝试根据项目规范进行修复或发出明确告警。循环检测如果同一个Issue在“开发-审查-请求更改”之间循环超过一定次数如3次系统会将其标记为“需要人工介入”并通知维护者防止无限循环消耗资源。2. 医生诊断与指标 (Doctor Metrics)Fabrica内置了一个诊断模块持续收集系统指标Agent性能指标每个Agent任务的平均执行时间、成功率、失败原因分布。工作流效率指标从Issue创建到关闭的平均周期时间、各阶段开发、审查、测试的耗时占比。资源消耗API调用次数特别是昂贵模型API、计算资源使用情况。 这些指标通过简单的仪表板或日志输出帮助维护者了解系统健康度定位瓶颈例如是否总是在“代码审查”阶段耗时过长。3. 可观测性输出所有Agent的思考过程、执行命令、API调用和决策日志都以结构化的方式如JSONL格式输出到指定位置。这意味着当流程出现意外结果时你可以像查看分布式系统的追踪日志一样回溯整个决策链精确定位是哪个Agent、在哪个步骤、基于什么信息做出了错误判断。这为调试和迭代工作流本身提供了可能。4. 实战部署、问题排查与调优指南4.1 环境准备与快速启动Fabrica的设计目标是易于部署和集成。目前它主要作为OpenClaw的插件运行。1. 前提条件OpenClaw环境一个已经安装并配置好的OpenClaw实例。OpenClaw提供了AI Agent执行的基础运行时。GitHub账户与Token你需要一个GitHub账号并生成一个具有足够权限的Personal Access Token需要repo,workflow,project等作用域用于Fabrica自动化操作仓库、项目和PR。AI模型API密钥Fabrica的各个Agent需要大语言模型驱动。你需要准备OpenAI GPT-4/3.5-Turbo、Anthropic Claude或类似模型的API密钥。建议使用性能更强的模型如GPT-4用于复杂的规划和审查任务以提升整体效果。2. 安装与配置# 1. 克隆Fabrica仓库到你的OpenClaw插件目录 git clone https://github.com/MestreY0d4-Uninter/fabrica.git /path/to/openclaw/plugins/ # 2. 安装Python依赖Fabrica通常是一个Python插件 cd /path/to/openclaw/plugins/fabrica pip install -r requirements.txt # 3. 配置环境变量 # 在你的OpenClaw环境或Fabrica配置文件中设置以下关键变量 export GITHUB_TOKENyour_github_personal_access_token export OPENAI_API_KEYyour_openai_api_key # 可选配置其他模型、日志路径、心跳间隔等 export FABRICA_HEARTBEAT_INTERVAL60 export FABRICA_LOG_LEVELINFO3. 启动与触发配置完成后在OpenClaw中启用Fabrica插件。触发工作流有两种主要方式Telegram机器人向绑定的Bot发送消息/startproject 项目描述...。CLI命令在OpenClaw的CLI中执行fabrica start --description 项目描述...。启动后你就可以在GitHub上看到自动创建的仓库、项目板和第一个Issue整个流水线开始运转。4.2 常见问题与故障排查实录在实际使用和测试中我们遇到了不少典型问题。以下是排查思路和解决方案的速查表。问题现象可能原因排查步骤与解决方案Intake Agent陷入无限问答循环用户需求过于模糊或开放Agent无法形成有效判断。Prompt中缺少终止访谈的明确条件。1. 检查日志看Agent反复询问的问题是否类似。2. 优化Intake Agent的Prompt加入更明确的终止规则例如“如果连续两轮问答都未获取到关于[技术栈/核心功能/部署目标]的新信息则结束访谈基于已有信息生成规格。”3. 在UI/CLI中为用户提供“强制结束访谈并继续”的选项。Developer Agent生成的代码无法通过基础编译Agent使用的上下文可能不完整如未包含package.json或对项目框架的理解有偏差。1. 检查Agent执行任务时的“工作目录”和“上下文文件列表”。确保它能看到所有必要的配置文件。2. 在项目脚手架阶段生成一个更详细、包含常见问题解答的README_DEV.md给Agent参考。3. 引入一个轻量级的“编译检查”步骤在Agent提交代码前自动运行npm run build或tsc --noEmit如果失败则让Agent根据错误信息自行修复。Reviewer Agent批准了明显有错误的代码审查Prompt不够严格或使用的模型能力不足如用了GPT-3.5-Turbo审查复杂逻辑。1. 升级Reviewer Agent使用的模型为GPT-4或Claude-3 Opus。2. 细化审查规则Prompt要求其必须检查具体的错误模式例如“请检查1. 异步函数是否正确处理了错误2. API路由是否校验了用户输入3. 数据库查询是否避免了N1问题”3. 将自动化静态分析工具如SonarQube扫描结果作为上下文提供给Reviewer Agent让其结合分析报告进行审查。整个流程在某个Issue上卡住状态无更新心跳线程崩溃Agent任务因超时或异常而静默失败遇到了需要人工干预但未配置通知的情况。1.首先查看Doctor日志这是第一现场。日志会记录最后一次心跳活动、各个Agent任务的状态和可能的错误信息。2.检查GitHub API速率限制过多的API调用可能导致临时封禁。查看日志中是否有429错误。解决方案是增加请求间隔或使用GitHub App安装方式以获得更高限额。3.手动执行修复Fabrica CLI通常提供fabrica doctor --fix命令尝试自动修复僵尸状态。如果不行通过fabrica issue --retry issue_number手动重试特定任务。Tester Agent无法成功运行端到端测试测试环境如浏览器、数据库未正确配置或启动测试用例本身依赖未准备好的数据。1. 确保项目脚手架中包含了可靠的测试环境配置如docker-compose.test.yml。2. 让Tester Agent在运行测试前先执行环境准备脚本。3. 对于E2E测试提供更详细的“测试准备指南”给Agent或考虑在初期先只运行单元测试E2E测试由人工触发。生成的代码风格与团队规范不符缺乏统一的代码风格定义和检查工具集成。1. 在项目初始化时必须集成ESLint和Prettier并提交配置文件.eslintrc.js,.prettierrc。2. 在Developer Agent的Prompt中明确强调“所有代码必须通过项目ESLint和Prettier检查”。3. 在GitHub Actions中配置CI在PR创建时自动运行linting如果失败则阻塞合并让Agent必须修复。4.3 性能调优与成本控制建议运行一个全自动化的AI工作流性能和成本是无法回避的问题。1. 模型策略优化分层使用模型不要所有任务都用最贵的模型。将任务分类高创造性、高复杂度的任务如架构设计、复杂逻辑审查使用GPT-4中等任务如代码生成、简单审查使用Claude-3 Sonnet或GPT-3.5-Turbo低复杂度任务如格式化、简单命令执行使用廉价的小模型或规则引擎。上下文长度管理LLM API收费通常与输入输出的token数相关。优化Prompt去除冗余信息。对于长上下文如整个代码库优先使用RAG技术检索相关片段而不是全量喂入。缓存与复用对于相似的Issue或任务如“创建另一个CRUD API”Agent的解决方案可能类似。可以引入简单的缓存机制存储“问题-解决方案”对在遇到高度相似的新问题时优先尝试复用减少API调用。2. 流程效率优化并行化可行任务如果项目中有多个独立的Feature Issue如“开发登录页面”和“设计数据库Schema”可以配置Fabrica尝试并行开发由不同的Developer Agent实例处理前提是它们之间没有依赖关系。设置超时与重试策略为每个Agent任务设置合理的超时时间如10分钟。超时后自动重试最多2-3次如果仍然失败则升级为需要人工处理的故障。精简“修复通道”扫描范围随着项目规模变大每次心跳都全量扫描所有Issue/PR可能低效。可以改为只扫描“进行中”状态的项目或者增量扫描自上次心跳后有变更的项目。3. 成本监控详细日志记录确保每一次LLM API调用的模型、输入输出token数都被记录。设置预算告警利用云服务商的监控功能或自己编写脚本当日/周/月的API调用费用超过阈值时发送告警并暂停非核心任务。评估ROI定期回顾对比Fabrica自动化完成的任务所花费的API成本与工程师手动完成同等任务的时间成本。这有助于判断自动化在哪些场景下是经济高效的。5. 设计反思、局限性与未来演进方向构建Fabrica的过程是一个不断在“自动化理想”与“工程现实”之间寻找平衡点的过程。它目前远非完美更像一个功能齐备但需要精心调校的“原型车间”。1. 当前的主要局限性对复杂、模糊需求的驾驭能力有限虽然Intake Agent能进行多轮澄清但对于极其抽象或充满内在矛盾的需求这在真实业务中很常见它仍然可能生成有偏差的规格导致后续开发全盘跑偏。人类的早期深度介入仍然不可替代。“理解”而非“真正理解”Agent们基于模式匹配和概率生成来“理解”代码和需求。它们能出色地处理模式化的任务创建标准CRUD API、实现常见UI组件但对于需要深刻领域知识、复杂业务逻辑或创造性算法设计的任务其输出质量不稳定需要大量人工复审和修正。调试与纠错成本不低当工作流出错时尽管有日志但调试一个由多个AI Agent和状态机组成的分布式系统其心智负担有时甚至高于直接手动编写代码。你需要理解每个Agent的决策上下文、Prompt的意图以及状态机的转移逻辑。初始配置与调优门槛让Fabrica在一个新团队或新项目类型中良好运行需要不少前期工作编写适合团队文化的Prompt模板、配置代码审查规则、设置测试环境等。它不是一个“开箱即用万物皆可自动”的解决方案。2. 设计中的关键权衡确定性与灵活性的权衡我们选择了确定性状态机牺牲了动态工作流生成的灵活性换来了可预测性和可调试性。这对于追求稳定性的工程场景是值得的。自动化程度与人工控制的权衡我们刻意避免了“全自动”的噱头而是设计了明确的人工介入点。这看起来不够“智能”但大大提高了系统的实用性和安全性。真正的“智能”是知道何时该自动何时该交给人。通用性与专用性的权衡Fabrica试图提供一个通用的软件工程工作流框架。但实践中为特定类型项目如前端React应用、数据ETL管道定制专属的Agent技能和流程模板效果会好得多。未来的方向可能是提供一个核心引擎可插拔的“领域适配器”。3. 我期待的反馈与演进方向如果你对这类工具感兴趣我特别希望听到以下几方面的反馈架构层面状态机的设计是否过于僵化是否有更优雅的编排模式如基于事件的驱动在保持确定性的同时提供更多灵活性用户体验对于想要尝试的开发者当前的安装、配置和启动流程是否足够清晰哪里让你感到困惑故障处理在实际运行中你遇到的最棘手的故障是什么现有的“修复通道”和“医生”诊断是否帮你解决了问题价值判断在使用了这类工具后你觉得它带来的结构化和自动化收益是否抵得上学习、配置和调试它所付出的成本在什么类型的项目或团队中它的性价比最高Fabrica的代码仓库完全公开它不是一个完美的产品而是一个诚实的实验。它的价值不在于展示了多炫酷的AI能力而在于认真对待了“将AI融入工程实践”时所必须面对的、琐碎却至关重要的工程问题。欢迎你来试用、批评、拆解或者告诉我对于你日常的软件开发工作流来说什么样的自动化辅助才是真正有用而非过度设计的。
