1. 项目概述AI辅助工程框架flowai的设计哲学如果你和我一样日常开发重度依赖Claude Code、Cursor这类AI编程助手那你肯定也经历过这种场景让AI写个功能它噼里啪啦一顿输出代码看着还行但仔细一检查架构跑偏了、依赖搞乱了甚至把核心逻辑都改了。最后还得自己从头捋一遍时间一点没省血压倒是上来了。这就是典型的“AI失控”问题——你把方向盘交给了AI但它可能开上了一条你完全没想走的路。flowai这个框架就是来解决这个核心矛盾的。它不是一个试图取代开发者的全自动AI代理而是一个**“辅助工程”**框架。它的核心理念非常明确开发者永远是架构师和审查者AI只是执行者。在这个模式下你设定任务、审批计划、控制每一次代码变更AI则负责在你划定的边界内高效地完成具体的编码、测试和文档工作。这就像你是一个建筑项目的总工程师AI是你手下最得力的施工队图纸你来画每一步施工方案你来批最终验收也由你把关。我花了几天时间深度体验了flowai它彻底改变了我与AI协作的方式。以前是“我说一句AI干一堆我再收拾烂摊子”现在是“我定方向AI出方案我审批AI执行我验收”的清晰流水线。这种模式不仅大幅提升了代码质量的可控性更重要的是它把AI从“不可预测的黑盒”变成了“可预测、可管理的生产工具”。接下来我就结合自己的实操带你彻底搞懂flowai的安装、配置、核心工作流以及那些官方文档里没写的避坑技巧。2. 核心架构与组件拆解命令、技能与代理要玩转flowai首先得理解它的三个核心概念命令、技能和代理。这三者共同构成了flowai的指令系统决定了AI在项目中能做什么、怎么做。2.1 命令开发者发起的明确工作流命令是由开发者主动触发的、具有明确起点和终点的工作流。在AI IDE里它们通常以斜杠命令的形式出现比如/flowai-commit、/flowai-init。你可以把命令理解为一个个封装好的“宏”或“脚本”专门用来处理那些重复性高、步骤固定的开发任务。flowai内置的核心命令包corepack提供了开发中最常用的一套命令/flowai-init项目初始化。这是你接触flowai的第一个命令。它会扫描你的代码库分析技术栈然后生成一系列基础文件包括最重要的AGENTS.md项目总纲、requirements.md需求文档、design.md设计文档的脚手架以及适配你项目的Deno任务脚本。实操心得运行这个命令前最好确保你的项目根目录已经是一个可运行的状态比如deno task check能通过否则它基于错误上下文生成的文档可能不准。/flowai-commit原子提交。这是flowai工作流的收尾环节。AI会检查当前的所有变更运行项目定义的检查如deno task check进行自我代码审查然后将通过审查的变更打包成一个逻辑完整的原子提交。关键点这个命令生成的提交信息结构非常清晰包含了变更概述、影响分析和自检清单远超手动写的git commit -m “fix bug”。/flowai-review-and-commit先审查后提交。这是/flowai-commit的增强版它把审查和提交拆成了两个明确的阶段。AI会先对变更进行一轮深度质量评估代码风格、潜在bug、架构一致性生成审查报告供你确认只有在你批准后才会进入提交阶段。适合场景当你对AI本次做的修改不太放心或者变更涉及核心模块时用这个命令更稳妥。/flowai-update框架更新。一键更新flowai CLI、同步最新的技能和代理到你的IDE配置中并检测框架模板的变更提示你是否需要迁移本地的AGENTS.md等文件。注意事项更新前建议先提交或暂存你本地的所有修改因为更新过程可能会覆盖某些由flowai管理的配置文件。命令的本质是把开发者的意图翻译成AI能一步步执行的、结构化的操作清单。它确保了每次操作的起点和流程都是一致的避免了因提示词表述模糊导致的AI“自由发挥”。2.2 技能AI可自动调用的能力模块如果说命令是“手动挡”那技能就是“自动挡”。技能是AI在会话中可以根据上下文自动发现并调用的能力模块。当AI在处理一个复杂任务时如果它判断某个内置技能能帮上忙它就会主动加载这个技能的指令并执行。flowai的技能库非常丰富分布在不同的功能包中core包中的核心技能构成了日常开发的基石。flowai-skill-plan任务规划。这是flowai工作流的起点。当你给AI一个模糊需求如“给用户模块加个搜索功能”AI会调用此技能生成一个GODS格式的详细计划。GODS代表Goal目标、Overview概述、Done完成标准、Solution解决方案。你必须仔细审查并批准这个计划这是你掌控架构方向的第一步。flowai-skill-review与flowai-skill-reflect质量保障。前者用于代码审查后者用于会话自我分析。AI在完成一个阶段后可能会自动调用它们来检查自己的工作质量。flowai-skill-investigate深度调查。用于排查复杂Bug。它会引导AI采用“假设-实验-验证”的科学方法而不是盲目地试错。engineering包中的工程技能扩展了AI在非编码任务上的能力。flowai-skill-deep-research深度研究。能指挥子代理进行多源网络调研并汇总报告。flowai-skill-draw-mermaid-diagrams绘制Mermaid图表。让AI直接生成架构图、流程图等。flowai-skill-write-prd/dep编写产品需求文档或开发增强提案。这对于需要AI协助进行前期设计的项目非常有用。devtools包中的开发工具技能用于扩展flowai自身。如果你想为团队定制专属技能或代理这里的flowai-skill-engineer-skill和flowai-skill-engineer-subagent就是你的工具。技能和命令在文件结构上很像都位于framework/pack/下的对应目录。它们最根本的区别在于一个元数据标志disable-model-invocation: true。这个标志由flowai CLI在安装时自动添加到命令文件中告诉AI“这个技能不能由你主动调用只能等用户来触发”。而技能文件没有这个标志AI在合适的时机就会自动拾取。2.3 代理具备特定专长的AI角色代理定义了AI在特定任务中应该扮演的角色和思维方式。你可以把它理解为给AI戴上的“专业帽子”。当激活某个代理时AI会加载该代理的完整指令集使其行为模式更贴近某个领域的专家。flowai内置了几个关键代理flowai-console-expert控制台专家。擅长处理复杂的命令行操作、脚本编写和系统任务。当你需要AI执行一系列终端命令时这个代理能极大减少错误。flowai-diff-specialist差异分析专家。专门用于分析Git差异并准备符合规范的原子提交。它在/flowai-commit工作流中会被自动调用。flowai-skill-adapter与flowai-agent-adapter适配器代理。当flowai框架本身更新后技能或代理的模板可能发生了变化。这两个代理负责将你项目中已安装的旧版技能/代理根据新模板进行适配更新保留你的项目特定配置。工作流程中的角色协同一次典型的/flowai-commit过程可能是这样的你开发者触发命令 - AI加载flowai-diff-specialist代理角色 - 该代理调用flowai-skill-review技能审查代码 - 再调用flowai-skill-reflect技能进行自我总结 - 最后生成提交。整个过程是技能与代理的有机组合。3. 安装、配置与初始化全流程实操理论讲完了我们上手实操。flowai的安装和配置有几个关键决策点选对了后面一路顺畅选错了可能就得重来。我会结合我踩过的坑带你走一遍最稳妥的路径。3.1 环境准备与CLI安装flowai基于Deno运行时所以第一步是安装Deno。官方要求v2.x版本。# 在MacOS上使用Homebrew安装是最简单的方式 brew install deno # 安装完成后验证版本 deno --version # 输出应类似deno 2.x.x接下来安装flowai的CLI工具。这里有个细节jsr:korchasa/flowai是它在JSRJavaScript Registry上的包名。# 全局安装flowai CLI deno install -g -A jsr:korchasa/flowai注意-A参数赋予了脚本所有权限这是因为flowai CLI需要读写文件系统、访问网络来同步技能。如果你对安全性有极高要求可以查阅Deno文档按需授予更细粒度的权限但作为开发工具-A是最省心的选择。安装成功后运行flowai --help应该能看到命令列表。如果提示“command not found”可能是Deno的安装目录如~/.deno/bin没有加入到系统的PATH环境变量中你需要手动添加一下。3.2 全局安装 vs. 项目本地安装关键抉择这是第一个关键选择把flowai的技能安装到哪里flowai提供了两种作用域理解它们的区别至关重要。全局安装--global路径技能会被安装到你的用户目录下如~/.claude/skills/、~/.cursor/skills/等。配置使用全局配置文件~/.flowai.yaml。特点一次安装所有项目共享。你只需要同步一次之后在任何项目中使用AI IDE都能调用这些技能。适用场景个人开发者或者团队中每个成员希望独立管理自己的一套技能。项目本地安装--local路径技能被安装到当前项目的特定目录下如./.claude/skills/、./.cursor/skills/。配置使用项目根目录下的配置文件./.flowai.yaml。特点技能与项目绑定可以提交到Git仓库中。适用场景团队协作项目需要确保所有成员使用完全一致的技能版本和配置或者某个项目需要使用一些自定义的、非标准的技能。如何选择如果你是个人开发者刚开始接触flowai我强烈建议从全局安装开始。它更简单管理起来更方便不会污染你的项目目录。如果你是团队技术负责人需要为某个大型项目统一开发规范那么应该使用项目本地安装。你可以将.flowai.yaml和IDE的技能目录如.cursor/添加到.gitignore的例外中使其纳入版本控制。安装命令示例# 进入你的项目目录 cd /path/to/your/project # 方式一明确指定全局安装推荐个人使用 flowai sync --global # 方式二明确指定项目本地安装 flowai sync --local # 方式三使用自动检测默认行为 flowai sync使用flowai sync不加参数时它会自动检测首先看当前目录下有没有.flowai.yaml文件有则按项目本地处理。如果没有再看用户目录下有没有~/.flowai.yaml有则按全局处理。如果都没有则会交互式询问你选择哪种方式。我的建议对于新项目直接运行flowai sync --global。如果你想为某个特定项目启用本地安装只需要在该项目根目录创建一个空的.flowai.yaml文件或运行flowai sync --local自动创建之后在这个项目里运行flowai sync就会自动识别为本地模式。3.3 项目初始化与AGENTS.md的生成安装好技能后下一步就是在你的项目中初始化flowai。这是通过AI IDE如Cursor来完成的而不是CLI。在你的AI IDE中打开目标项目。在聊天框或命令面板中输入/flowai-initAI会开始工作。它会做以下几件事分析代码库扫描项目结构、识别技术栈是Node.js、Deno、Python还是其他、分析现有的配置文件。生成AGENTS.md这是flowai的“大脑”。AI会根据分析结果在这个文件中写入项目的愿景、技术栈约束、代码风格规则、强制要求等。这个文件你必须仔细审查和修改生成文档脚手架创建documents/目录并在其中生成requirements.md软件需求规格和design.md设计文档的模板。配置开发命令根据项目类型在deno.json或类似配置中添加或更新诸如check、test、fmt等标准化任务。AGENTS.md文件详解与定制AGENTS.md是flowai的灵魂它告诉AI“在这个项目里应该怎么做事”。初始化生成的版本是通用模板你必须根据项目实际情况进行深度定制。一个典型的AGENTS.md包含以下部分# Project Agents Configuration ## Vision [这里定义项目的核心目标和愿景。例如“构建一个高性能、易扩展的内部用户管理系统替代旧的遗留系统。”] ## Tech Stack Constraints - **Runtime**: Deno 2.x - **Language**: TypeScript (strict mode) - **Database**: PostgreSQL (via postgres driver) - **API Style**: RESTful JSON - **禁止项**: - 不允许使用 any 类型。 - 所有异步操作必须处理错误禁止未处理的Promise。 - 新增外部依赖必须经过审核并添加到 deno.json 的 imports 中。 ## Code Style Rules - 使用 2 空格缩进。 - 字符串优先使用单引号 ()。 - 导出函数必须显式声明返回类型。 - 文件命名采用kebab-case例如user-service.ts。 ## Mandatory Workflow 1. 任何功能开发前必须调用 /flowai-skill-plan 生成GODS计划并经我开发者批准。 2. 每次代码修改后**必须**运行 deno task check包括 lint、format、test且必须通过。 3. 提交代码必须使用 /flowai-commit 或 /flowai-review-and-commit生成原子提交。初始化后的检查清单[ ] 打开并仔细阅读生成的AGENTS.md根据项目实际情况修改Vision、Tech Stack和Rules。[ ] 检查documents/目录下的文档模板如果项目已有相关文档可以将其内容迁移过来。[ ] 运行deno task check或你项目对应的检查命令确保初始化过程没有引入语法或风格错误。[ ] 尝试运行/flowai-skill-plan让AI为你手头的一个小任务生成计划测试技能是否加载成功。4. 核心开发工作流实战从需求到提交flowai的价值在完整的开发工作流中体现得淋漓尽致。下面我以一个真实的场景——“为用户列表添加分页查询功能”——来演示flowai如何介入从规划到提交的每一步。4.1 阶段一任务规划与审批当你接到一个新需求时不要直接让AI开始写代码。第一步是规划。触发规划在AI IDE中输入/flowai-skill-plan。描述任务AI会问你任务是什么。你回答“在现有的用户列表API (GET /api/users) 中添加分页查询功能支持page和pageSize参数返回结构需要包含总条数、当前页数据和总页数。”AI生成GODS计划AI会调用flowai-skill-plan技能生成一份结构化的计划## Goal 为 /api/users 端点实现分页查询提升大数据量下的性能与用户体验。 ## Overview 1. 修改路由处理函数解析 page (默认1) 和 pageSize (默认20) 查询参数。 2. 修改数据库查询使用 LIMIT 和 OFFSET。 3. 执行一次额外的查询以获取总用户数。 4. 构造新的响应格式{ total, page, pageSize, totalPages, data }。 5. 更新相关的API文档如OpenAPI/Swagger。 ## Done - [ ] 后端API接受并处理分页参数。 - [ ] 数据库查询正确分页并返回总条数。 - [ ] 前端如果存在能调用新的API并显示分页数据。 - [ ] 所有现有测试通过并新增分页相关测试。 - [ ] deno task check 通过。 ## Solution 这里AI会列出更详细的技术方案比如具体修改哪个文件使用什么SQL语句等。开发者审查与批准这是你行使架构师权力的关键一步。你需要仔细审查这个计划架构正确性用LIMIT/OFFSET在数据量极大时可能有效率问题是否考虑用游标分页AI可能不知道需要你指出。完整性它是否考虑了错误处理如page传入负数是否考虑了pageSize的最大值限制影响面这个修改会不会破坏现有的前端调用是否需要同步更新前端代码 你可以直接让AI修改计划“将LIMIT/OFFSET方案改为基于created_at时间的游标分页并添加对page和pageSize参数的验证逻辑。” AI会更新计划直到你满意为止。最后你明确给出指令“批准该计划开始实施。”4.2 阶段二AI执行与开发者监督AI收到批准指令后就会开始按照计划一步步写代码。这时你的角色从架构师转变为监督者。观察代码变更AI通常会打开相关的文件如user-router.ts、user-service.ts开始修改。你应该在IDE的Git面板或源代码管理视图中实时查看它产生的差异。不要等到它全部写完再看。中途纠偏如果你发现AI的实现偏离了计划或者采用了你不认可的代码模式比如用了any类型而你的AGENTS.md里明确禁止了要立即打断它“停这里不能用any请使用明确的接口类型UserQueryParams。”运行检查在AI完成一个逻辑模块比如修改完路由层后可以手动运行一下deno task check或者让AI自己运行。flowai的核心原则之一是‘单点验证’即deno task check是代码健康的唯一真理源。任何破坏检查的代码都不应进入提交阶段。这个过程中flowai的“技能”在后台默默工作。例如当AI需要写数据库查询时可能会自动加载与数据库操作相关的技能当它需要写测试时flowai-skill-fix-tests技能可能会被触发。4.3 阶段三质量审查与原子提交当AI完成所有编码并通过了deno task check后就进入了最后的审查与提交阶段。触发审查与提交输入命令/flowai-review-and-commit。这个命令比单纯的/flowai-commit多了一个深度审查环节。AI自我审查AI会调用flowai-skill-review技能对自己的变更进行一轮严格的代码审查。它会生成一份报告内容包括代码风格是否符合项目规范。潜在Bug如可能的空值引用、边界条件处理。架构一致性修改是否与整体设计吻合。测试覆盖是否新增或更新了足够的测试。 这份报告会呈现给你。你需要仔细阅读确认AI的审查是否到位。生成原子提交在你确认审查无误后AI会调用flowai-diff-specialist代理准备提交。它会将本次所有相关的变更路由、服务、测试组织在一起。撰写清晰的提交信息通常遵循“类型(范围): 描述”的格式如feat(api): add pagination to user list endpoint。在提交信息中详细说明变更内容、动机和影响。最终它会生成一个Git命令如git commit -m “...”等待你的最终确认。你必须明确同意它才会执行git commit。至此一个完整的、受控的AI辅助开发循环结束。你全程掌控了方向、设计和质量而AI承担了所有繁琐的实现、测试和文档工作。这种模式极大地提升了复杂任务的开发效率和代码质量的可预测性。5. 高级技巧、问题排查与生态扩展掌握了基本工作流后我们来看看一些能让你用得更顺手的高级功能和常见问题的解决办法。5.1 使用CLI进行自动化与集成flowai的CLI不仅是安装工具还提供了强大的自动化能力特别是flowai loop命令。flowai loop非交互式AI执行引擎这个命令允许你在终端或脚本中以非交互方式运行AI任务。它的一个典型应用场景是自动化代码库健康检查。假设你想每天凌晨自动检查项目中有没有新的TODO注释并生成报告# 创建一个脚本 check_todos.sh #!/bin/bash # 使用flowai-console-expert代理以非交互模式(yolo)运行 flowai loop --yolo --agent console-expert 扫描整个代码库找出所有TODO和FIXME注释按文件和优先级整理成Markdown表格输出。 todo_report.md然后你可以用cron定时任务执行这个脚本报告会输出到todo_report.md文件。更复杂的例子定期项目维护你可以创建一个结合了多个技能的维护脚本# 使用维护技能间隔5分钟运行一次最多运行10次迭代用于长时间运行的任务 flowai loop --yolo --interval 5m --max-iterations 10 /flowai-skill-maintenanceflowai-skill-maintenance技能会对项目进行8个维度的健康扫描依赖、配置、测试、文档等并尝试交互式地修复问题。通过loop命令你可以让它自动运行。5.2 常见问题与排查指南在实际使用中你可能会遇到以下问题问题1AI无法识别/flowai-xxx命令。可能原因1技能未正确同步到IDE目录。排查检查~/.cursor/skills/或你使用的IDE对应目录下是否存在flowai-commit等文件夹。解决在项目根目录重新运行flowai sync根据你的作用域选择是否加--global。可能原因2IDE未加载技能。Cursor等IDE有时需要重启或手动触发技能列表重载。解决尝试重启IDE或在命令面板中搜索“Reload Skills”之类的选项。问题2/flowai-init生成的AGENTS.md内容过于泛泛不贴合项目。原因AI在初始化时对项目上下文理解不足。解决不要依赖一次生成的结果。将其作为草稿手动进行深度编辑。特别是Tech Stack Constraints和Mandatory Workflow部分必须根据你项目的实际情况细化。一个具体的、严格的AGENTS.md是flowai高效工作的前提。问题3AI在执行计划时“自作主张”做了计划外的事情。原因可能是当前会话的上下文被污染或者AI模型“幻觉”。预防严格按照“规划-批准-执行-审查”流程。在AI开始执行前再次确认它复述的计划与你批准的一致。纠正立即中断AI明确指出偏离之处并命令它回滚到上一步正确的状态或根据修正后的计划继续。问题4deno task check在本地通过但在CI/CD中失败。原因最常见的是环境差异比如Deno版本、依赖版本或全局配置文件不同。排查确保CI环境与本地开发环境使用完全相同的Deno版本在deno.json中用deno字段指定。使用deno.lock文件锁定依赖。flowai的启示这正是flowai强调“单点验证”的原因。确保CI运行的检查命令与本地deno task check完全一致。可以在AGENTS.md中强制规定“所有代码在提交前必须在本地通过与CI完全相同的检查流水线。”5.3 自定义技能与代理打造团队专属工作流flowai真正的威力在于它的可扩展性。你可以为团队或特定项目创建自定义的技能和代理。创建自定义技能假设你的团队有一个固定的代码审查清单每次提交前都必须检查。你可以创建一个自定义技能规划技能内容在项目根目录下创建一个.claude/skills/my-team-code-review/SKILL.md文件如果是本地安装模式。编写技能指令# 技能my-team-code-review ## 目的 执行我们团队特定的代码审查清单。 ## 审查清单 1. **安全性**检查所有用户输入是否经过验证和清理。 2. **性能**检查循环内是否有重复的数据库查询或API调用。 3. **可维护性**检查函数长度是否超过50行超过则需要重构。 4. **日志**检查关键业务逻辑和错误路径是否有适当的日志记录。 5. **配置化**检查是否有硬编码的魔法数字或字符串应移至配置。 ## 执行步骤 1. 分析当前Git暂存区的变更。 2. 针对每一处变更对照上述清单进行检查。 3. 生成审查报告列出发现的问题和建议。同步技能运行flowai sync这个自定义技能就会被同步到IDE中。使用技能你可以在任何任务中告诉AI“在提交前请调用my-team-code-review技能进行审查。”AI会自动加载并执行它。创建自定义代理如果你团队的后端主要用Go语言你可以创建一个Go专家代理创建代理文件.claude/agents/go-backend-expert/SUBAGENT.md编写代理指令# 代理Go后端专家 ## 角色 你是一个经验丰富的Go后端工程师精通Gin、GORM、Go标准库和云原生开发。 ## 编程规范 - 使用 go fmt 格式化代码。 - 错误处理使用 errors.Wrap 包装错误并提供上下文。 - 日志使用结构化的日志库如 slog 或 zap。 - 测试使用表格驱动测试覆盖率力求达到80%以上。 ## 专长领域 - RESTful API设计 - 数据库建模与优化PostgreSQL/MySQL - 并发模式goroutine, channel - 微服务间通信gRPC, REST之后在开始一个Go相关的任务时你可以指示AI“请以go-backend-expert代理的角色来执行这个任务。”通过自定义技能和代理你可以将团队的最佳实践、技术规范固化到flowai中让AI成为团队文化的忠实执行者从而大幅提升整个团队的代码质量和开发效率的一致性。