Freelance：为AI编码智能体构建结构化工作流与持久化记忆图谱

Freelance是面向AI编码智能体的开源框架，旨在解决当前智能体面临的流程控制缺失和上下文记忆脆弱两大核心挑战。该框架通过三大核心能力实现突破：一是基于YAML定义结构化工作流图，确保执行路径可控；二是通过MCP协议在工具调用边界强制执行工作流规则，实现状态持久化；三是构建随查询增长的持久化知识图谱，具备源文件变更感知能力，让智能体真正实现上下文感知。

随着大语言模型在代码生成领域的应用普及，AI编码智能体成为热点，但存在两大痛点：

流程控制缺失：智能体行为自由发散，缺乏结构化执行路径，复杂任务中效率低、易遗漏关键步骤。

上下文记忆脆弱：记忆受限于模型上下文窗口，早期信息易遗忘，且缺乏源文件变更感知能力，无法区分知识有效性。

Freelance项目正是针对这些痛点设计的解决方案。

Freelance通过三个子系统协作，提供控制力和记忆力：

基于YAML的工作流图定义

工作流为有向图，YAML声明式定义，具备可视化可维护性、严格类型系统（action/decision/gate等节点类型）、子图组合能力（上下文与返回值映射）。

MCP边界强制执行

MCP是智能体与工具交互的标准接口，Freelance在调用边界强制执行工作流规则：智能体需通过freelance_start/freelance_advance推进流程，gate节点阻塞直到条件满足；状态存储在服务端，与智能体会话解耦，解决失忆问题。

持久化知识图谱

内置SQLite知识图谱，支持：编译知识为原子命题、来源追溯（文件/哈希/修改时间）、有效性验证（哈希匹配判断是否过期）、增量学习（仅编译差距避免重复）。

Freelance工作流执行机制细节：

启动与遍历：智能体调用freelance_start启动，系统创建服务端持久化的遍历状态，与会话解耦。

节点处理：每个节点接收描述和指令，action节点执行工作，gate节点验证条件表达式阻止前进。

边条件评估：转移边附加条件表达式（如context.taskDone == true），运行时求值决定下一步。

钩子机制：节点可声明onEnter钩子，进入前自动执行内置功能或本地脚本，实现上下文准备。

Freelance记忆系统的核心特征：

命题化知识表示：知识为自然语言命题，独立自洽，适合人机处理。

内容哈希去重：相同内容命题自动去重，避免知识库膨胀。

Git分支感知：基于文件哈希判断知识有效性，切换分支时自动适配（匹配则有效，否则过期），合并分支后知识收敛。

集合组织：命题分组到命名集合，支持按项目/模块管理，同一命题可在多集合中。

工具生态系统

分为工作流控制工具（freelance_list/freelance_start等）和记忆工具（memory_emit/memory_search等），写操作需活跃工作流遍历许可，读操作随时可用。

配置与部署

双层配置：config.yml（团队共享，版本控制）和config.local.yml（机器特定，git忽略）；优先级：CLI参数 > 环境变量 > config.local.yml > config.yml > 默认值。

Freelance适合的场景：

结构化代码审查：定义多阶段审查流程，确保PR经过必要检查点。

复杂重构任务：分解大型重构为可管理步骤，智能体按流程执行不遗漏。

知识密集型项目：构建项目知识图谱，让智能体真正理解代码库。

长期运行智能体：状态持久化，跨会话持续工作，适合数小时/天的复杂任务。

价值主张：提供可靠的结构化流程和持久记忆，解决智能体无序性和失忆问题。

Freelance代表新的AI智能体设计范式——“有约束的智能”，比无约束智能更具实际应用价值。

未来展望：更多内置工作流模板、更强记忆查询能力、与更多开发工具集成。对于追求可靠性和可控性的AI辅助开发团队，Freelance是值得探索的框架。