分形生成实验（二）：API 合约驱动的轻量化强类型协作框架

在上一篇《分形生成实验：在有限上下文中构建可组合的强类型单元》中，我们提出了以强类型系统为基石的AI协作框架。近期通过一个真实简历分析项目的实践，我对该方法论进行了轻量化改造------用API合约驱动替代显式模块拓扑 ，并初步探索了前端样式约束的集成。本文将分享这一演进过程的核心洞察。

一、为何需要轻量化？从复杂拓扑到API-first

原实验中的shared/dataflow/模块拓扑设计，本质是显式声明模块间的调用链路（如"用户模块→订单模块"）。这在金融级复杂系统中确有必要，但对于多数中小型项目却显得冗余。

在本次简历分析项目中，我观察到：API端点天然定义了模块边界与交互协议。例如：

GET /api/v1/status 返回用户状态（含token配额、试用资格等）
POST /api/v1/startAnalyze 接收JD与简历，返回多轮对话的初始问题

这两个端点不仅定义了数据类型 （如UserStatusResponse），更隐含了业务流顺序（必须先获取状态再提交分析）。AI在生成前端调用逻辑时，只需严格遵循API文档中的类型定义与调用时序，即可自动满足模块间契约------无需额外维护拓扑图。

关键转变 ：将dataflow/的"模块拓扑"转化为API文档的"端点关系"，使契约定义与开发流程天然对齐。

二、强类型扩展：从代码到样式的双约束

原实验的强类型仅覆盖数据层，但前端UI的一致性同样依赖约束。本次实践中，我通过全局CSS变量建立了基础样式规范：

css 复制代码

:root {
  /* 颜色体系 */
  --primary-color: #409eff;
  --success-color: #67c23a;
  /* 响应式断点 */
  --breakpoint-md: 768px;
}

当要求AI生成组件时，明确指令："使用var(--primary-color)作为主按钮背景色，并在max-width: var(--breakpoint-md)下切换为垂直布局"。这使得生成的按钮、表单等组件在不同页面保持视觉统一，且天然适配移动端。

尽管尚未实现Design Tokens的完整体系（如语义化命名、多主题支持），但CSS变量已验证了样式约束的可行性------未来可通过工具链将Tokens编译为CSS变量，进一步强化AI的样式生成纪律。

三、轻量化框架的核心优势

降低认知负荷

开发者只需维护API文档与CSS变量，无需设计复杂的模块拓扑图。AI的生成上下文从"理解系统架构"简化为"遵守API契约"。
天然前后端对齐

API类型定义（如StartAnalyzeRequest）可直接用于生成前端请求体与后端校验逻辑，避免类型不一致导致的联调问题。
渐进式扩展能力

当项目复杂度提升时，可逐步引入：
- OpenAPI规范自动化生成类型
- Design Tokens管理设计系统
- 端到端测试验证API调用链

四、未来展望：向Design Tokens演进

当前CSS变量方案存在局限：颜色值与业务语义弱关联（如--primary-color未说明用途）。下一步计划实践Design Tokens：

定义语义化令牌（如--color-button-primary）
通过工具链同步至CSS/JS/设计稿
要求AI生成组件时引用令牌而非具体值

这将使样式约束从"技术实现"升级为"设计语言"，进一步缩小AI生成内容与产品意图的偏差。

结语

分形生成实验的本质，是在AI的"局部视野"与系统的"全局一致性"之间架设桥梁。通过API合约驱动的轻量化框架，我们证明了：强类型约束不必复杂，只需精准锚定协作边界。无论是数据流还是样式规范，只要提供清晰的公共契约，AI便能成为可靠的"分形单元"制造者。

📩 交流与合作 ：欢迎通过CSDN私信或cli_assistant仓库探讨智能体开发实践与更深层次合作！