不能光吹牛，不动手实践！那样是不对的。
一、架构核心理念
1.1 设计目标
Javis 采用双路径架构（Dual-Path Architecture），核心目标是将 AI 交互成本与业务逻辑执行完全解耦。这种设计允许系统在需要 AI 能力时调用 LLM，而在执行传统业务操作时完全不消耗 AI 资源。
1.2 核心原则
Agent-Service 分离: AI 交互成本与业务逻辑执行解耦
端到端类型安全: 通过类型系统消除运行时错误
业务语义对齐: 架构实体严格映射到 PRD 定义
规范驱动一致性: Agent 行为受 Contract Docs 约束
人机协作循环: 三轮迭代反馈机制，然后进入手动编辑模式
二、双路径架构概览
2.1 架构层次图
ounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(line用户界面层 (Next.js) │ ├─── Agent Path (无状态路径) │ │ │ ├── 特点: 无状态、成本优化、快速响应 │ ├── 功能: LLM 调用、提示工程、规范注入 │ └── 输出: 临时响应，不持久化 │ └─── Service Path (有状态路径) │ ├── 特点: 有状态、已验证、工作流驱动 ├── 功能: CRUD 操作、验证、工作流编排、持久化 └── 输出: 数据库持久化、活动日志2.2 路径交互关系
两个路径通过上下文交换进行协作：
Agent Path 从 Service Path 获取上下文（如 Contract Docs、Issue 信息）
Service Path 接收 Agent Path 生成的内容并持久化
两者通过明确的接口边界分离，避免混合执行
三、Agent Path（AI 交互层）
3.1 核心定位
Agent Path专门处理所有 LLM 交互，目标是最小化 token 消耗，最大化响应速度。
3.2 关键特征
无状态设计
不执行数据库写入操作
上下文是临时的、短暂的
每次调用都是独立的，不依赖之前的调用状态
成本优化策略
响应缓存: 相同请求的响应缓存 5 分钟，避免重复调用
流式响应: 使用流式传输，用户可立即看到部分结果
提示压缩: 移除冗余上下文，减少 token 消耗
规范嵌入: 使用向量数据库查找相关 Contract Docs，而非全量注入
高性能设计
并行 API 调用，同时处理多个请求
早期返回机制，一旦有结果立即返回
避免阻塞操作，保持响应速度
规范注入机制
所有 Agent 调用自动注入项目规范（Contract Docs）
通过中间件统一处理，确保一致性
规范内容从缓存或数据库获取，优化性能
3.3 主要职责
Agent Path 负责以下功能需求：
FR-03: 从需求文档（Demand Doc）中探索生成问题（Issues）
FR-04: 从问题（Issue）生成用户故事（User Stories）和测试用例（Test Cases）
FR-06: Figma MCP 集成，处理设计资产
迭代反馈: 根据用户反馈重新生成 Issues 或 Stories
3.4 技术实现
实现方式: Next.js API Routes（独立于 tRPC）
外部集成: BMAD Agent API、Figma MCP、Cursor API
缓存层: Redis 用于响应缓存和规范缓存
四、Service Path（业务逻辑层）
4.1 核心定位
Service Path处理所有业务逻辑、验证、持久化和工作流编排，完全不消耗 AI token。
4.2 关键特征
有状态设计
所有操作都涉及数据库事务
保证 ACID 特性（原子性、一致性、隔离性、持久性）
维护完整的业务状态
严格验证
Schema 验证：确保数据符合数据库模型
业务规则验证：执行业务逻辑约束
Contract Doc 验证：确保生成内容符合项目规范
工作流驱动
使用状态机管理业务流程
事件驱动架构，响应状态变更
消息队列（BullMQ）处理异步工作流
可审计性
完整的活动日志记录
版本控制支持
所有操作可追溯
可追踪性
所有者跟踪（responsibleUserId）
时间戳记录（创建时间、更新时间）
操作历史完整保留
4.3 主要职责
Service Path 负责以下史诗（Epics）：
Epic 1: 项目与资产基线管理（GitLab 集成）
Epic 2: 文档管理（需求文档 vs 规约文档）
Epic 3: 问题管理（CRUD、状态、类型）
Epic 4: 用户故事与测试用例管理
Epic 5: 规约文档版本控制
Epic 6: 代码交付与 CI/CD
4.4 工作流编排
Service Path 使用消息队列编排复杂工作流：
问题探索队列: 处理从需求文档生成问题的任务
故事分解队列: 处理从问题生成用户故事的任务
状态同步: 自动同步迭代状态与问题状态
事件触发: 状态变更触发后续工作流步骤
4.5 技术实现
实现方式: tRPC Procedures（类型安全的 RPC）
数据库: PostgreSQL（通过 Prisma ORM）
消息队列: BullMQ（异步任务处理）
五、双路径交互模式
5.1 模式一：生成-审查-持久化
流程描述:
Agent Path 从需求文档生成内容（轻量级、可缓存）
用户界面展示生成结果供审查（无成本）
用户批准后，Service Path 持久化到数据库
适用场景:
从需求文档探索问题
从问题生成用户故事
任何需要人工审查的 AI 生成内容
成本特点:
Agent Path 调用产生 AI 成本
审查和持久化不产生 AI 成本
5.2 模式二：获取上下文-处理-存储结果
流程描述:
Service Path 获取完整上下文（问题信息、规约文档等）
Agent Path 处理上下文并生成结果（产生 AI 成本）
Service Path 存储生成结果到数据库（无 AI 成本）
适用场景:
问题分解为用户故事
基于现有内容生成新内容
需要完整上下文的复杂生成任务
成本特点:
上下文获取不产生 AI 成本
仅 Agent Path 处理产生 AI 成本
结果存储不产生 AI 成本
5.3 模式三：三轮迭代反馈
流程描述:
Agent Path 生成初始内容
用户提供反馈
Agent Path 根据反馈重新生成（最多 3 轮）
如果 3 轮后仍不满意，Service Path 切换到手动编辑模式
迭代限制:
最多执行 3 轮 AI 重新生成
每轮迭代记录在数据库中
超过限制后自动切换到手动模式
成本控制:
限制迭代次数避免无限成本
手动模式完全无 AI 成本
5.4 模式四：状态同步机制
流程描述: 当迭代（Iteration）状态变更时，自动同步关联问题（Issue）的状态，确保数据一致性。
状态映射规则:
迭代状态变更 | 问题状态同步 | 业务含义 |
|---|---|---|
Planning → InProgress | Open → InProgress | 迭代开始，问题进入开发状态 |
InProgress → Completed | InProgress → Closed | 迭代完成，问题关闭 |
InProgress → Cancelled | InProgress → Open | 迭代取消，问题回退到开放状态 |
Completed → Released | 无变更 | 发布不影响问题状态 |
实现特点:
自动批量更新符合条件的关联问题
只更新状态匹配的问题（避免误更新）
完全在 Service Path 执行，无 AI 成本
六、架构优势分析
6.1 成本优化
显著优势:
AI 成本仅发生在真正需要生成内容时
审查、持久化、查询等操作完全不消耗 token
缓存机制减少重复调用
流式响应提升用户体验同时控制成本
成本对比:
传统混合架构：每次操作都可能调用 AI
双路径架构：只有 Agent Path 产生 AI 成本
6.2 清晰分离
架构清晰度:
Agent Path 和 Service Path 职责明确
开发者容易理解哪个路径负责什么
代码组织更清晰，维护更容易
边界明确:
无状态 vs 有状态
临时响应 vs 持久化存储
AI 处理 vs 业务逻辑
6.3 独立扩展
扩展能力:
Agent Path 可根据 LLM 需求独立扩展
Service Path 可根据业务流量独立扩展
两者互不影响，优化更灵活
性能优化:
Agent Path 优化响应速度和成本
Service Path 优化数据库查询和事务处理
各自使用最适合的技术栈
6.4 规范驱动
一致性保证:
所有 Agent 调用自动注入项目规范
通过中间件统一处理，无法绕过
确保生成内容符合架构、设计、测试标准
可维护性:
规范集中管理（Contract Docs）
修改规范自动影响所有 Agent 调用
减少重复代码和配置
七、架构决策记录（ADR-001）
7.1 决策背景
Javis 需要同时支持：
LLM 交互（成本高、无状态）
传统 CRUD 操作（无成本、有状态）
混合执行会导致成本效率低下和架构复杂性。
7.2 决策内容
将 Agent Path（AI 交互）与 Service Path（业务逻辑）分离，以优化成本并保持清晰的边界。
7.3 决策后果
正面影响:
✅ 成本优化：只为生成内容付费
✅ 清晰分离：Agent Path 无状态，Service Path 有状态
✅ 独立扩展：可根据不同需求分别扩展
需要权衡:
⚠️ 复杂度：开发者需要理解两个执行路径
⚠️ 协调：需要明确两个路径的交互模式
八、实施建议
8.1 开发原则
明确路径选择: 每个功能明确属于 Agent Path 还是 Service Path
避免混合: 不要在 Service Path 中调用 LLM，不要在 Agent Path 中持久化
规范注入: 所有 Agent 调用必须通过中间件注入规范
成本意识: 优先使用 Service Path，仅在需要生成内容时使用 Agent Path
8.2 最佳实践
缓存优先: Agent Path 响应优先使用缓存
批量处理: 尽可能批量处理以减少调用次数
流式响应: 使用流式传输提升用户体验
迭代限制: 严格执行三轮迭代限制
状态同步: 利用自动状态同步机制保持数据一致性
8.3 监控指标
Agent Path 监控:
AI API 调用次数和成本
缓存命中率
响应时间分布
错误率和重试次数
Service Path 监控:
数据库查询性能
事务处理时间
工作流执行状态
活动日志生成量
九、总结
Javis 的双路径架构设计通过明确分离 AI 交互与业务逻辑，实现了：
成本优化: 只在需要时消耗 AI 资源
架构清晰: 职责分明，易于理解和维护
性能提升: 各自优化，互不干扰
规范驱动: 确保生成内容符合项目标准
人机协作: 三轮迭代机制平衡自动化与人工控制
这种架构设计特别适合需要频繁使用 AI 生成内容，同时需要严格业务逻辑管理的企业级应用场景。
AI时代企业生存指南：CEO必须警惕的五大致命内因
2025-12-11
颠覆传统，极致闭环：探索AI赋能下的“三人行”开发组织新模式。
2025-12-10
AI时代，要么Builder，要么Loser，你会怎么选？
2025-12-08
Claude Skills工具简直太爽了！动手实践写了个AI自动代码检查，让AI提升代码质量！
2025-12-07
【AI谈】Elevo，是我对AI认知与思考的具象化表达
2025-09-29
运维老王：创业第十年，我用Elevo找回内心翻腾的梦想
2025-09-12
