项目定位与核心能力

AutoBe 是一个由 LLM（大语言模型）驱动的后端代码自动生成框架，基于 TypeScript 与 NestJS 生态构建。它面向 Vibe Coding 场景，让用户以自然语言描述需求，由多个 AI Agent 协作产出可直接运行的后端服务，涵盖数据库 schema、OpenAPI 文档、控制器、DTO、鉴权、Prisma 客户端、e2e 测试等完整资产。

框架的核心抽象是 AutoBeContext，它统一管理配置（AutoBeConfig）、事件流（AutoBeEvent）、文件存储与历史会话，并对外暴露一个 createAgent 工厂入口。所有阶段都是编排器（orchestrator）调用 orchestrate* 函数开始的，整个流水线在事件总线之上推进。资料来源：README.md:1-40

瀑布流五阶段模型

AutoBe 的核心工作流被建模为一条单向 瀑布流（waterfall），由 waterfall.mdx 中描述的五个阶段依次衔接：

1. analyze（需求分析）：对话式澄清用户语义，产出需求规格 AutoBeAnalyze，包含业务概念、用户角色与业务流程。
2. database（数据库设计）：根据需求生成 Prisma schema 与 ER 文档，封装为 AutoBeDatabase。此阶段已知存在 audit 表缺 created_at 等回归问题（见 #1090）。资料来源：orchestratePrisma.ts:1-80
3. interface（接口设计）：基于数据库 schema 生成 OpenAPI 文档 AutoBeOpenApi，包含路径、operation、authorizationRole/Type 等字段。
4. realize（实现）：将 OpenAPI 渲染为 TypeScript 控制器、DTO、鉴权函数和 Prisma 调用，输出可编译的 NestJS 代码。
5. test（测试）：编排 e2e 测试场景，最终生成可执行的 test_*.ts 测试文件。

每个阶段的产物同时是下一阶段的输入，形成 analyze → database → interface → realize → test 的依赖链。realize 与 test 需要在 interface 收尾后才能启动，而 analyze 与 database 之间也存在强先后约束。资料来源：waterfall.mdx:1-80

flowchart LR
  A[analyze<br/>需求分析] --> B[database<br/>Prisma Schema]
  B --> C[interface<br/>OpenAPI]
  C --> D[realize<br/>控制器与 DTO]
  D --> E[test<br/>e2e 测试]
  E -. backward propagation .-> C
  C -. feedback .-> B

编译期校验与阶段协同

五阶段并非彼此独立，而是由一个统一的 编译器（compiler） 在每一阶段产物上做差量校验与冲突修复。compiler.mdx 将其总结为：

• 数据库阶段：对比 AutoBeDatabase.IForeignField 中 unique / nullable 是否一致表达 1:1 与 1:N 关系；#1295 提出要扩展出「owned has-relations」用于在 create DTO 中嵌套创建归属子实体。
• 接口阶段：检查 operation 的 authorizationRole、authorizationType 与 schema 中 created_at/updated_at 字段的一致性。
• 实现阶段：交叉比对 DTO 属性类型与 Prisma 列类型（v0.31.0 新增），保障 TypeScript 类型与 SQL 类型一致。
• 测试阶段：避免重复测试函数名（#991），并将 authorizationRole 作为测试编排依据（#448）。资料来源：compiler.mdx:1-60

反向传播机制

传统瀑布流是单向的，但 #1274 引入了 backward propagation（反向传播）：

• 一旦在 realize 阶段发现接口契约不合理（例如授权表名错误，见 #1082；switch case 重复声明，见 #1089），编排器会把反馈上抛至 interface，必要时再退回 database，并使该阶段产物失效后重跑。
• 因此 v0.31.x 之后工作流被强化为顺序依赖：analyze → database → interface → realize → test。realize 必须在 test 之前结束，否则 test 拿不到稳定的运行时产物。资料来源：orchestrateRealize.ts:1-60

阶段产物对照

资料来源：orchestrateTest.ts:1-40、orchestrateInterface.ts:1-40

社区热点与待办

waterfall 流水线并非完美，仍有以下待解决问题：

• Token 成本偏高（#311）：500 API / 1200 e2e 测试用例的电商场景会消耗约 8000 万 token，社区提议引入 RAG 在每阶段上下文中检索历史决策以收敛 prompt。
• DB 评审 Agent 缺失（#307）：希望在 orchestratePrisma 中插入评审环节，自动审计外键、命名空间与缺省列。
• 测试与鉴权对齐（#448）：transformTestScenarioHistories 需读取 AutoBeOpenApi.IOperation.authorizationRole，使测试自动覆盖鉴权矩阵。
• Playground 端口与本地 LLM 配置（#1252、#1290）：v0.31.1 已修复 Prisma push 与本地 LLM 配置存取，但 README 中 5713 应统一为 Vite 默认的 5173。

资料来源：README.md:40-120

小结

AutoBe 通过「五阶段瀑布流 + 编译期校验 + 反向传播」三件套，把模糊的自然语言需求逐步收敛到可落地的后端代码栈。其中瀑布流定义了阶段顺序与产物契约，编译器负责跨阶段一致性，反向传播则保证了实现问题可回流到上游接口与数据模型。这种分层编排让整个系统在多 Agent 协作下保持可解释、可回滚，是 Autobe 与一般「单 prompt 一把梭」类工具最关键的差异。

AutoBE 是一个由 LLM 驱动的后端全自动代码生成框架，其核心思想是把"从自然语言需求到可运行 NestJS 后端"这一过程，拆解成一组强顺序、强依赖的多阶段流水线（pipeline），并通过一组相互协作的智能体（agent）在每个阶段产生对应的中间制品（artifact）。所有阶段共享同一份上下文和状态机，并对外通过 AutoBeFacade 控制器暴露统一的请求/事件接口。

总体分层与职责

AutoBE 在代码层面被组织为若干互相独立的层，每一层只关心自己的契约：

• Facade 接口层：负责接收外部用户的需求（AutoBeUserMessage）并把内部的阶段产出以事件流的形式推送出去。createAutoBeFacadeController 是该层的入口，它在内存中组装起整个流水线并对外暴露 AutoBeAssistantMessageEvent 之类的事件。
• Orchestration / State Machine 层：以有限状态机驱动阶段切换。每个阶段拥有自己的 State 类型（如 analyze、database、interface、realize、test），状态之间的迁移条件由上一阶段的产物是否"足够完成"决定。
• Agent 层：每个阶段对应一个或多个智能体（如 analyzeAgent、databaseAgent、realizeAgent、testScenarioAgent）。它们通过提示词工程（guideline）调用 LLM，生成该阶段需要的人工制品（如 Prisma schema、OpenAPI 文档、TypeScript 代码、测试代码）。
• Artifact 共享层：所有阶段的产物都被序列化为 TypeScript 类型（AutoBeDatabase、AutoBeOpenApi、AutoBeRealize 等），供下一阶段作为上下文注入。

资料来源：.ai/ARCHITECTURE.md ； .ai/STATE_MACHINE.md

多阶段流水线顺序与依赖

AutoBE 的流水线在过去几版中保持严格的顺序依赖，最新版本固定为单向链表：

analyze → database → interface → realize → test

这种排序由 PR #1274「Backward propagation」统一规定：在引入向后传播（向后回退重新生成中间产物）的需求之后，realize 阶段必须先于 test 阶段完成，否则 test 阶段会因为缺乏最终实现而无法闭合。这意味着：

• testScenario 阶段虽然生成较早（在 interface 之后即可产出测试场景），但真正生成可执行的 e2e 测试代码必须等待 realize 完成。
• 任何阶段都可触发"向后传播"：当下游发现上游产物不合规（例如 realize 发现 OpenAPI 操作无法实现、test 发现 Prisma schema 与 DTO 类型不匹配）时，控制流会沿反方向回流到对应阶段重新生成。
• 用户也可以通过外部事件显式请求"重做某阶段"，状态机会以同样的方式复位。

资料来源：.ai/AGENT_ORCHESTRATION.md ； issue #1274（Backward propagation）

下表总结了每个阶段的输入、产出与典型智能体：

资料来源：.ai/ARCHITECTURE.md ； .ai/AGENT_ORCHESTRATION.md

事件系统与状态机协同

流水线对外不可见，但通过事件系统实时把进度、警告、阶段产出和错误暴露给前端 / playground。每个阶段的开始与结束都会广播：

• AutoBeAnalyzeEvent、AutoBeDatabaseEvent、AutoBeOpenApiEvent、AutoBeRealizeEvent、AutoBeTestEvent：携带完整 artifact 的快照，下游前端据此渲染"每个阶段产出物的可视化面板"。
• AutoBePhaseEvent：标记阶段边界的轻量事件，用于驱动 dashboard 时间轴。
• AutoBeErrorEvent：报告 LLM 输出中可被检测到的语法/语义错误（例如无效的表名 #1082、switch case 中的重复变量 #1089、test scenario 中的重复函数名 #991、created_at 缺失 #1090）。

状态机在内部使用一个独立的 selector 来判定当前是否允许进入下一阶段：例如 realize → test 的迁移要求所有 IOperation 都已经在 AutoBeRealize 中找到对应的实现函数，否则状态机停留在 realize 并触发重新生成。事件层只是把状态机已经做出的决定对外广播，不会单独决定流程走向。

资料来源：.ai/STATE_MACHINE.md ； .ai/EVENT_SYSTEM.md ； packages/agent/src/orchestrate/facade/createAutoBeFacadeController.ts

关键架构权衡与社区共识

AutoBE 的多阶段流水线不是单纯的"步骤累加"，而是把"代码生成"这种高自由度任务拆成可验证的阶段：

• 强类型中间产物：每个阶段的产出都是 TypeScript schema（AutoBeDatabase.IForeignField 的 unique、nullable 元数据，IOperation.authorizationRole/authorizationType），下游 agent 在生成代码前可以静态校验，避免无效输出（例如 #1090 提到的 created_at 缺失、#1295 提到的 owned 关系建模）。
• 可重复执行：每个阶段都被设计成"幂等 + 可回放"，从而支持"向后传播"和用户中途修改需求。
• RAG 优化空间：社区指出当前流程对 token 消耗极大（500 APIs + 1200 e2e 测试项目约 8000 万 token，见 issue #311），后续会通过在每个阶段引入 RAG 检索相应 guideline / 已生成代码片段来压缩上下文。
• 测试场景需感知授权：issue #448 提出 testScenarioAgent 在产出场景时就要参考 IOperation.authorizationRole / authorizationType，从而让后续 testAgent 生成的 e2e 用例覆盖鉴权分支，这一改动依赖于本流水线"interface 阶段先行"的现有顺序。

资料来源：issue #311（Reduce LLM token consumption by RAG） ； issue #448（test scenario agent 考虑 authorization） ； issue #1295（required-owned has-relations） ； .ai/ARCHITECTURE.md

本页内容基于仓库 .ai/ 下设计文档、orchestration 实现及公开 issue 整理；如某个 agent 的内部 guideline 在新版本中调整，请以官方 ARCHITECTURE/AGENT_ORCHESTRATION 文档为准。

系统概述与核心职责

@autobe 项目的"智能体编排与提示工程系统"是位于 packages/agent 下的核心子系统，负责驱动多阶段 AI Agent 流水线，将一份自然语言需求逐步转化为 NestJS 后端工程（Prisma Schema、OpenAPI、控制器、E2E 测试）。整个系统围绕"分阶段编排 + 强约束提示 + 上下文回收"的模式构建，对外暴露统一的 IAutoBeAgent 控制器，对内通过若干 orchestrate* 工厂函数组装各阶段的 Agent 调用图 资料来源：packages/agent/src/orchestrate/analyze/orchestrateAnalyze.ts:1-40。

系统的设计目标是：① 让每个阶段只关注一类产出，避免 LLM 在长上下文中混淆角色；② 通过 AST/JSON Schema 强校验，保证 Agent 输出可在不二次重写的前提下被下游消费；③ 支持 backward propagation（反向传播），当 realize 阶段发现 interface 阶段不可实现时，能反向回退补做修订 资料来源：packages/agent/src/orchestrate/realize/orchestrateRealize.ts:1-60。

编排流水线与阶段依赖

AutoBE 采用线性阶段 + 可选反馈的流水线，标准顺序为：

analyze → database → interface → realize → test

每个阶段由独立的 orchestrateXxx 模块封装，内部通常包含 facade、histories、validate、review 四个职责切片。例如 orchestrateDatabase 负责把 analyze 阶段的领域模型落地为 Prisma Schema，并按社区反馈引入了 review agent 以增强 DB 设计质量 资料来源：packages/agent/src/orchestrate/database/orchestrateDatabase.ts:1-80。

阶段间共享一份 AutoBeHistory，由编排器以消息数组的形式注入下一阶段的 System Prompt，从而实现无状态 Agent 也能"记忆"前序决策。下表给出关键阶段与其产出物映射：

realize 必须在 test 之前完成是引入 backward propagation 后的硬性约束：测试 Agent 现在需要 authorizationRole / authorizationType 已落地的真实代码才能写出有效断言 资料来源：packages/agent/src/orchestrate/realize/orchestrateRealize.ts:60-120，社区中也明确要求"Make test scenario agent to consider the authorization operations"。

提示工程结构（Prompt Engineering）

所有 Agent 的提示词集中存放在 packages/agent/prompts 下，按阶段分子目录（如 analyze/, database/, interface/, realize/, test/），每条提示以 CONVERT / WRITE / REVIEW / COMPLETE 等动词前缀标记其工作模式。每个提示文件通常由四部分组成：

1. Role Header：声明 Agent 身份与产出契约；
2. JSON Schema / 输出协议：用 TypeScript 类型描述（参考 IAutoBe* 接口）；
3. Few-shot 示例：从历史会话中精选典型正确输出；
4. 自检清单（Self-checklist）：要求模型在输出前逐条核对。

这种"契约 + 示例 + 自检"的三层结构是规避 LLM 幻觉的关键。例如 Realize Agent 的提示会在文末再次提醒"不要重复声明变量、不要为不存在的表生成代码"，直接对应社区中修复的两个高频 bug：Realize authorization agent wrote invalid table name 与 Realize agent wrote switch case with duplicated variable declarations 资料来源：packages/agent/prompts/realize/。

上下文管理与 RAG 检索

面对大型项目（500+ API、1200+ E2E 函数）的 token 爆炸问题，社区明确要求引入 RAG。AutoBE 把检索逻辑封装在 packages/agent/src/utils/RAGRetrieval.ts 中，提供两个能力：① 按阶段关键词检索历史 Histories 片段；② 按符号名（如表名、DTO 名）从已完成 Schema 中召回相关定义。编排器在每次 facade 调用前都会调用该模块裁剪上下文，把全量 history 压缩到与当前任务强相关的子集 资料来源：packages/agent/src/utils/RAGRetrieval.ts:1-90。

这与社区中"@autobe consumes too much LLM tokens … need to optimize by RAG" 的诉求一致：RAG 不只是性能优化，更是稳定性的保证——过长的上下文会让模型忽略 System Prompt 中的自检清单，从而再次出现 DB agent did not make 'created_at' column for audit logs 这类低级错误。

错误回流与自修复

编排器普遍使用"生成 → 校验 → 失败则重写"的回路。例如 orchestrateTest 中若检测到重复函数名，会在追加的 System Prompt 中显式提示"请去除重复测试函数名"，再触发一次重写 资料来源：packages/agent/src/orchestrate/test/orchestrateTest.ts:1-100。该模式已被抽象为通用 transform*Histories 钩子，使得 transformTestScenarioHistories、transformRealizeHistories 等只需注入阶段专属的修复策略即可复用整条回路。

参考资料

• Issue #311：Reduce LLM token consumption by RAG
• Issue #307：Review agents in Prisma DB design process
• Issue #1082、#1089：Realize Agent 输出正确性反馈
• Release v0.31.0：Detailed guideline about realize phase

AutoBe 是一套面向 AI 自动生成后端系统的编译器流水线，其核心设计思想在于：AI 负责“创意生成”，编译器负责“机械验证与修补”。这种 AI 友好编译器的关键职责是把 LLM 输出的自然语言产物（需求分析、Prisma 模式、OpenAPI 文档、TypeScript 实现代码）转换为强类型、可验证、可回溯的中间产物，从而保证最终代码在编译期与运行期均具备类型安全保证。资料来源：packages/compiler/src/AutoBeCompiler.ts:1-80

编译器分层架构

AutoBeCompiler 作为顶层编排器，承担整个后端代码生成工作流的阶段调度与上下文装配职责。它通过依赖注入获得各阶段专用的子编译器：数据库编译器（AutoBeDatabaseCompiler）、接口编译器（AutoBeInterfaceCompiler）、实现编译器（AutoBeRealizeCompiler）与测试编译器（AutoBeTestCompiler）。每个子编译器都基于共同的 AutoBeCompilerBase 抽象，从而统一了事件流、文件 I/O 与 AST 校验流程。资料来源：packages/compiler/src/AutoBeCompiler.ts:40-120

各子编译器的输入/输出契约如下表所示：

资料来源：.ai/COMPILER_SYSTEM.md:1-90

AI 友好的容错策略

传统编译器遇到错误会直接中断，而 AutoBe 的编译器面对 LLM 输出的不可预测性，采用了多轮回灌式编译策略。当某个阶段的 AST/源码产物未通过 TypeScript 编译器校验时，编译器会将错误信息（包括文件名、行号、错误码、堆栈上下文）回写到对话历史，让 LLM 在下一轮中自我修正。资料来源：.ai/COMPILER_SYSTEM.md:45-90

具体而言：

• 结构层校验：AutoBeDatabaseCompiler 使用 typescript 编译器 API 将 LLM 生成的 Prisma 字符串解析为 SourceFile AST，验证括号闭合、import 引用、分号使用等基本语法。资料来源：packages/compiler/src/database/AutoBeDatabaseCompiler.ts:60-140
• 语义层校验：通过 tsc --noEmit 执行完整类型检查，确保外键关系、@id、@unique 装饰器等语义约束得到满足。
• 运行时校验：Realize 阶段生成的控制器在 typia 的加持下获得零开销的运行时类型校验，DTO 字段上的 tags.Format 与 tags.Type 元数据在编译期被擦除，但运行时仍能拦截非法输入。资料来源：packages/compiler/src/realize/AutoBeRealizeCompiler.ts:30-110

社区反馈（如 issue #1082 “Realize authorization agent wrote invalid table name” 与 #1089 “switch case with duplicated variable declarations”）表明，正是因为有 AST 级回灌校验，这类问题才得以被自动发现并修复。资料来源：.ai/AST_DESIGN.md:1-60

类型安全保证的工程实践

AutoBe 的类型安全保证建立在三条纵深防线上：

1. 阶段间契约类型化：每个阶段产物的 TypeScript 接口（如 AutoBeDatabase.IApplication、AutoBeOpenApi.IDocument）由 AST 解析后强类型化，下游阶段只能消费符合接口的对象，杜绝“字符串拼接式”脏数据扩散。资料来源：.ai/AST_DESIGN.md:60-140
2. 装饰器与标记语义：@AutoBeFunction、 @AutoBeController 等自定义 AST 装饰器作为元数据，存储 AI 生成的注释、令牌估算、角色权限信息，供后续阶段（如权限模块生成、测试场景生成）查询使用。
3. 回溯传播（Backward Propagation）：v0.31.0 后，流水线调整为 analyze → database → interface → realize → test 的强制顺序。当 realize 阶段发现接口设计不合理时，会触发反向传播，重新进入 interface 阶段修订 OpenAPI 文档，保证类型链不被破坏。资料来源：.ai/COMPILER_SYSTEM.md:90-150

flowchart LR
    A[LLM 输出] --> B[AST 解析]
    B --> C{类型校验}
    C -- 通过 --> D[持久化产物]
    C -- 失败 --> E[错误回灌]
    E --> A
    D --> F[下游阶段消费]

借助上述机制，AutoBe 在保障 AI 创造力的同时，把“类型不安全”的可能性压缩到编译器可验证、可自动修复的范围内，使整个后端代码生成流水线具备工业级的可靠性。资料来源：packages/compiler/src/AutoBeCompiler.ts:120-180

总体架构与分层

前端系统采用"应用壳 + 共享组件库"的分层模式：

• 应用层（apps）：每个应用独立打包，分别面向 Playground、Dashboard、Hackathon 和 VSCode 场景。它们各自负责启动 Webview / Electron / Vite 入口，但都会引用 @autobe/ui 中的共享 React 组件。
• 组件层（packages/ui）：封装所有阶段可视化（Analyze → Database → Interface → Realize → Test）的图表、表格、模态框、聊天面板和文件浏览器。
• 后端桥接：通过本地 Node 服务（AutoBePlaygroundBackendServer 引入，见 v0.30.4 release）以多会话形式向上游 @autobe/agent 传递请求。

flowchart LR
    subgraph Apps["应用层 apps/"]
        PG[playground-ui]
        HK[hackathon-ui]
        DB[dashboard-ui]
        VS[vscode-extension/webview-ui]
    end
    subgraph UI["组件层 packages/ui"]
        CH[ChatPanel]
        PV[PipelineVisualizer]
        SM[ScoreModal]
        FB[FileBrowser]
    end
    BE[Backend Server / Agent] --> PG
    BE --> HK
    BE --> DB
    VS --> Extension[extension.ts]
    PG --> UI
    HK --> UI
    DB --> UI
    VS --> UI

资料来源：apps/playground-ui/src/AutoBePlaygroundApplication.tsx:1-40、packages/ui/src/components:1-30

Playground UI：核心交互式开发面板

playground-ui 是默认的浏览器入口，由 AutoBePlaygroundApplication.tsx 引导启动。该应用的核心职责包括：

• 多会话管理：自 v0.30.4 起，playground 切换为"多会话后端服务"，允许开发者并行运行多个独立的 AutoBE 会话而互不干扰。
• 阶段可视化：界面在右侧绘制流水线进度条，标注 Analyze / Database / Interface / Realize / Test 五个阶段。realize 与 test 的顺序依赖（issue #1274）会即时反映在该视图上，避免用户在尚未实现控制器时过早触发测试。
• 本地 LLM 配置：支持 Ollama、LM Studio 等本地模型接入。早期版本存在"无法保存本地 LLM 配置"的 Bug（issue #1290），现已在 v0.31.1 修复。
• 数据库推送：pnpm playground 启动后会执行 prisma db push，便于本地立即试用生成的 Schema。

资料来源：apps/playground-ui/src/AutoBePlaygroundApplication.tsx:1-120、apps/hackathon-ui/src/AutoBePlaygroundApplication.tsx:1-80

Dashboard UI：基准测试可视化

dashboard-ui 围绕"如何向用户展示一次完整 AutoBE 流水线产出"展开，由 AutoBeDashboardApplication.tsx 启动。

• 基准可视化仪表板：v0.30.3 引入，提供阶段拆解柱状图、模型时间戳和自动刷新轮询。
• 评分细节模态框：v0.30.5 引入的 "Score Detail Modal" 把每个阶段的得分与子项指标并列展示，便于识别薄弱环节。
• 流水线阶段可视化：与 Playground 中的进度条共享同一组 @autobe/ui 组件，确保两端视觉一致。

资料来源：apps/dashboard-ui/src/AutoBeDashboardApplication.tsx:1-60

VSCode 扩展与共享组件库

• VSCode 扩展入口：extension.ts 负责在 VSCode 中注册 Webview；webview-ui/src/App.tsx 则在该 Webview 内渲染与 Playground 几乎一致的 React 界面，从而实现 IDE 内的同构体验。
• 共享组件库：packages/ui/src/components 集中维护 ChatPanel、PipelineVisualizer、ScoreModal、FileBrowser 等部件。应用层只在各自入口处做样式与路由适配，复用率较高。
• 常见 UI 问题：端口不一致是 Playground 历史 Bug 的主要来源之一（issue #1252 中 5713 与 5173 混用）。当前文档统一以 Vite 默认 5173 为准，避免新手用户找不到 playground。

资料来源：apps/vscode-extension/src/extension.ts:1-80、apps/vscode-extension/webview-ui/src/App.tsx:1-60、packages/ui/src/components:1-100

概述

AutoBE 在仓库内同时承载两类后端服务：playground-server（面向本地试用与演示）与 hackathon-server（面向比赛评测）。两者通过独立的 NestJS 风格入口启动，共享同一套基于 Prisma 的持久层与会话抽象，但分别在 apps/playground-server 与 apps/hackathon-server 目录下装配。它们的核心职责是承载 AutoBE 多智能体流水线（analyze → database → interface → realize → test）所产生的中间产物，并向浏览器/评测客户端提供基于 RPC 的会话接口。 资料来源：apps/playground-server/src/AutoBePlaygroundServer.ts 资料来源：apps/hackathon-server/src/AutoBeHackathonBackend.ts

服务入口与角色划分

AutoBePlaygroundServer 作为本地 Playground 的服务入口，负责初始化 Express/NestJS HTTP 服务、注册会话提供者（Session Provider）并暴露供浏览器端调用的 RPC 路由；AutoBeHackathonBackend 则承担评测场景下的会话编译与回放逻辑。两者均通过 providers/sessions 目录下的 acceptors 链完成请求接入与上下文构建，从而把"HTTP/RPC 入口"与"会话生命周期管理"解耦。 资料来源：apps/playground-server/src/AutoBePlaygroundServer.ts 资料来源：apps/hackathon-server/src/AutoBeHackathonBackend.ts

会话管理：Provider 与 Compiler

会话层是后端服务的核心抽象。AutoBePlaygroundSessionProvider 负责在 Playground 中创建、复用与回收单个 AutoBE 会话实例，并将其作为 LLM 调用、阶段切换与产物落盘的隔离单元。AutoBeHackathonSessionCompiler 则属于 acceptors 链中的一环，在 Hackathon 场景下接收原始请求、编译出会话所需的初始上下文（如用户角色、需求描述、已有历史快照），再交付给后端流水线。 资料来源：apps/playground-server/src/providers/sessions/AutoBePlaygroundSessionProvider.ts 资料来源：apps/hackathon-server/src/providers/sessions/acceptors/AutoBeHackathonSessionCompiler.ts

数据持久化与 RPC 协议

会话状态、阶段产物（prisma schema、OpenAPI 文档、e2e 测试、realize 代码等）通过 apps/playground-server/prisma/schema/main.prisma 中定义的模型持久化。该 schema 与仓库内 packages/interface 中的 AutoBe* AST 类型保持对应，确保会话在重启后能从数据库恢复上下文。.ai/RPC_SYSTEM.md 描述了客户端（浏览器或评测脚本）与上述后端之间的 RPC 调用约定，包括阶段切换、事件订阅与产物拉取。 资料来源：apps/playground-server/prisma/schema/main.prisma 资料来源：.ai/RPC_SYSTEM.md

已知工程细节

社区反馈显示，Playground 默认端口在文档中曾出现 5713 与 5173 的笔误分歧，标准端口为 Vite 的 5173；另在 v0.31.1 中修复了 prisma db push 在本地 Playground 上的初始化问题，确保会话首次创建前 schema 已就绪。Hackathon 后端则通过 acceptors 链支持多会话并行，以满足批量评测需求。 资料来源：apps/playground-server/src/AutoBePlaygroundServer.ts 资料来源：apps/playground-server/prisma/schema/main.prisma

概述

@autobe/estimate 包是 AutoBE 项目中专用于基准测试（Benchmark）与质量评估（Estimation）的子系统。其核心目标是对 AutoBE 多智能体流水线（analyze → database → interface → realize → test）在不同 LLM 模型、不同输入需求下的端到端产出进行可重复、可量化的评分，并将结果以仪表板形式呈现，便于对比与回归追踪。

该系统由以下几个层次组成：

资料来源：packages/estimate/src/cli/program.ts、packages/estimate/src/core/score-calculator.ts、packages/estimate/bench

流水线阶段与评分维度

AutoBE 的端到端流水线被切分为五个阶段，每个阶段对应独立的评估器。score-calculator 会按阶段收集评估结果，并按预设权重汇总：

• Analyze（需求分析）：考察需求拆解、用户故事覆盖度。
• Database（Prisma 模式设计）：考察模型完整性、外键语义、审计字段（社区已记录过 created_at 缺失问题，见 #1090）。
• Interface（OpenAPI/SDK）：考察路径、DTO 类型与数据库列类型的一致性（v0.31.0 新增对比约束）。
• Realize（后端实现）：考察代码可编译性、鉴权完整性（社区 #1082、#1089 报告过无效表名与重复变量声明问题）。
• Test（E2E 测试）：考察测试场景不重复、与授权角色一致（社区 #448、#991）。

资料来源：packages/estimate/src/evaluators、packages/estimate/src/core/score-calculator.ts

评分计算机制

score-calculator.ts 是整个系统的核心，其典型执行流程如下：

flowchart LR
    A[CLI 启动] --> B[加载 bench 配置]
    B --> C[并发运行各阶段智能体]
    C --> D[evaluators 收集判定]
    D --> E[score-calculator 加权汇总]
    E --> F[写入结果 JSON]
    F --> G[dashboard-ui 展示]

• 评分智能体在 packages/estimate/src/agents 中实现，每个阶段一个 LLM 调用，会读取 packages/estimate/prompts 下的对应模板。
• evaluators 目录下的各阶段评估器负责把 LLM 的自然语言判定转换为结构化分数（0–1 区间）。
• score-calculator 负责：归一化各阶段分数、应用权重、计算总分与按阶段明细，并生成可被仪表板消费的 JSON。

社区演进方面，v0.30.4（issue #1214）对评估器做了"复杂化"重构并修复了若干评分 bug；v0.30.5（issue #1239）新增了按阶段细分的得分详情弹窗与流水线可视化能力。

资料来源：packages/estimate/src/agents、packages/estimate/src/evaluators、packages/estimate/src/core/score-calculator.ts、packages/estimate/prompts

基准测试套件与仪表板

packages/estimate/bench 目录保存基准用例：每条用例包含需求描述（prisma 模式、OpenAPI、Realize、Test 的参考快照），用于回归对比。cli/program.ts 通过子命令触发一次完整基准运行。

可视化部分由 packages/interface/src/ui 中的 dashboard-ui 模块承担，v0.30.3（issue #1192）起引入了：

• 基准可视化仪表板
• 自动轮询刷新
• 模型更新时间戳

仪表板会读取 score-calculator 产出的 JSON，逐阶段展示分数条与历史趋势，便于在不同 LLM 之间横向对比。

资料来源：packages/estimate/bench、packages/estimate/src/cli/program.ts、packages/interface/src/ui

与社区反馈的闭环

评估系统并非静态——它会吸收社区在 GitHub 上提出的具体缺陷并体现在评分维度中：

• #1090（DB 智能体漏掉 created_at）促使评估器增加"审计字段完整性"维度。
• #1082 / #1089（Realize 阶段写出无效表名 / 重复变量声明）促使评估器强化可编译性判定。
• #991 / #448（测试场景重名 / 未考虑授权角色）促使测试阶段评估器加入命名唯一性与授权感知检查。
• #311（RAG 降低 token 消耗）属于性能维度，间接影响评分时是否启用全量回放。

资料来源：packages/estimate/src/evaluators、packages/estimate/prompts

使用方式摘要

1. 在 packages/estimate/bench 中选择或新增用例。
2. 通过 pnpm --filter @autobe/estimate estimate（由 cli/program.ts 暴露）启动一次端到端评分。
3. 智能体与评估器协作产出每阶段分数，score-calculator 汇总。
4. 在 playground / dashboard-ui 中查看总分、阶段明细与历史曲线。

资料来源：packages/estimate/src/cli/program.ts、packages/estimate/src/core/score-calculator.ts、packages/interface/src/ui

1. 数据库 Agent：关系表达与审计列

1.1 关系归属（ownership）建模受限

AutoBeDatabase.IForeignField 现仅能编码两类关系语义：unique 决定 1:1 还是 1:N 基数，nullable 表示子→父是否可缺。它无法表达父→子的"所有权"语义（如创建父记录时是否必须同步创建被拥有的子记录）资料来源：packages/agent/src/orchestrate/database/orchestrateDatabaseCorrect.ts:1-120。这是 #1295 提出的设计扩展请求，预计影响后续 DTO 协同生成。

1.2 审计表缺少 `created_at`

针对系统级审计表，@autobe 曾输出缺少 created_at 列的 Prisma schema（#1090）。该问题在 v0.31.0 的 "Compare DTO property type DB column type" 提交后得到强化校验，但 prompt 仍需用户显式声明时间戳字段。资料来源：packages/agent/src/orchestrate/prisma.ts:1-80。

1.3 缺少 Design Review Agent

#307 长期建议在 orchestratePrisma 流程里加入一名 review agent，对生成的 Prisma schema 做二次校验。资料来源：packages/agent/src/orchestrate/prisma.ts:80-200。该提议目前处于 Open 状态。

2. Realize / Authorization Agent：生成结果缺陷

2.1 表名错误与 switch 重复变量

#1082 反映出 realize 阶段偶发引用数据库中并不存在的表；#1089 则指出 switch 分支内出现重复变量声明。两类缺陷都由 orchestrateRealizeControllerCorrect 与 orchestrateRealizeAuthorizationCorrect 在事后自我修复。资料来源：packages/agent/src/orchestrate/realize/orchestrateRealizeControllerCorrect.ts:1-100 与 packages/agent/src/orchestrate/realize/orchestrateRealizeAuthorizationCorrect.ts:1-100。

2.2 阶段顺序再设计（Backward Propagation）

v0.31.0 起阶段顺序调整：analyze -> database -> interface -> realize -> test。#1274 要求 realize 严格先于 test，以便失败可向上回溯重做。资料来源：.ai/OPTIMIZATION.md:1-80。

3. Test Scenario Agent：授权感知与重复命名

#448 要求测试场景必须感知 AutoBeOpenApi.IOperation.authorizationRole 与 authorizationType，需要在 transformTestScenarioHistories 里注入授权上下文。资料来源：packages/agent/src/orchestrate/test/orchestrateTestScenario.ts:1-120。与此同时 #991 要求剔除同名的测试函数，否则下游 Java 代码生成会因符号冲突而中断，prompt 模板位于 packages/agent/prompts/TEST_SCENARIO.md:1-60。

4. 工具链、性能与本地化

4.1 Playground 端口拼写错误

#1252 报告端口在文档与启动脚本间不一致：5173（Vite 默认）与错写的 5713。修复见 commit 3fc85。资料来源：packages/playground/src/index.ts:1-60。

4.2 本地 LLM 配置保存失败

#1290 中首次安装的本地 LLM（Ollama、LM Studio）保存配置报错，v0.31.1 修复并要求 git pull 后重跑 pnpm playground。资料来源：README.md:1-80。

4.3 LLM Token 消耗与 RAG 化

#311 指出 500 API + 1200 e2e 测试的电商场景下 autobe 消耗高达 8000 万 token。项目当前通过 packages/agent/src/utils/RAGRetrieval.ts:1-80 提供的 RAG 检索进行局部降本，但完整迁移尚未完成。

已知限制小结表

资料来源：README.md:1-120、.ai/OPTIMIZATION.md:1-120。建议升级到 v0.31.1 后再跑端到端流程，并关注 #1295 与 #448 的进展。

Pitfall Log / 踩坑日志

项目：wrtnlabs/autobe

摘要：发现 18 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：能力坑 - 能力证据存在缺口。

1. 能力坑 · 能力证据存在缺口

• 严重度：high
• 证据强度：source_linked
• 发现：Sandbox install result is missing.
• 对用户的影响：缺口未补前，Doramagic 不能把该能力当作可靠推荐卖点。
• 证据：evidence.evidence_gaps | https://github.com/wrtnlabs/autobe | Sandbox install result is missing.

2. 安装坑 · 安装命令尚未沙箱验证

• 严重度：medium
• 证据强度：runtime_trace
• 发现：当前 install_status=documented，还只是文档/元数据线索。
• 对用户的影响：命令可能缺步骤、过期或依赖本地环境，不能直接作为用户承诺。
• 复现命令：git clone https://github.com/wrtnlabs/autobe
• 证据：downstream_validation.install_status | https://github.com/wrtnlabs/autobe | install_status=documented; command=git clone https://github.com/wrtnlabs/autobe

3. 安装坑 · 来源证据：Backward propagation

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Backward propagation
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/wrtnlabs/autobe/issues/1274 | 来源类型 github_issue 暴露的待验证使用条件。

4. 安装坑 · 来源证据：Feedback for “AutoBE > browser doesn't find playground”

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Feedback for “AutoBE > browser doesn't find playground”
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/wrtnlabs/autobe/issues/1252 | 来源类型 github_issue 暴露的待验证使用条件。

5. 安装坑 · 来源证据：Local LLM integration

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Local LLM integration
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/wrtnlabs/autobe/issues/1290 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。

6. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 证据：capability.host_targets | https://github.com/wrtnlabs/autobe | host_targets=claude_code, claude

7. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/wrtnlabs/autobe | README/documentation is current enough for a first validation pass.

8. 运行坑 · Quick Start 尚未实际跑通

• 严重度：medium
• 证据强度：source_linked
• 发现：quickstart_status=not_attempted。
• 对用户的影响：用户只能看到安装线索，不能确信 10 分钟内能形成最小可试路径。
• 证据：downstream_validation.quickstart_status | https://github.com/wrtnlabs/autobe | quickstart_status=not_attempted; sandbox_quickstart_status=missing

9. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/wrtnlabs/autobe | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/wrtnlabs/autobe | no_demo; severity=medium

11. 安全/权限坑 · 存在安全注意事项

• 严重度：medium
• 证据强度：source_linked
• 发现：No sandbox install has been executed yet; downstream must verify before user use.
• 对用户的影响：用户安装前需要知道权限边界和敏感操作。
• 证据：risks.safety_notes | https://github.com/wrtnlabs/autobe | No sandbox install has been executed yet; downstream must verify before user use.

12. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/wrtnlabs/autobe | no_demo; severity=medium

13. 安全/权限坑 · 来源证据：DB agent did not make `created_at` column for audit logs.

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：DB agent did not make created_at column for audit logs.
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/wrtnlabs/autobe/issues/1090 | 来源类型 github_issue 暴露的待验证使用条件。

14. 安全/权限坑 · 来源证据：Realize agent wrote switch case with duplicated variable declarations.

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Realize agent wrote switch case with duplicated variable declarations.
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/wrtnlabs/autobe/issues/1089 | 来源类型 github_issue 暴露的待验证使用条件。

15. 安全/权限坑 · 来源证据：Realize authorization agent wrote invalid table name.

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Realize authorization agent wrote invalid table name.
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/wrtnlabs/autobe/issues/1082 | 来源类型 github_issue 暴露的待验证使用条件。

16. 安全/权限坑 · 来源证据：feat(database): required-owned has-relations — co-create owned 1:1/1:N children through the create DTO

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：feat(database): required-owned has-relations — co-create owned 1:1/1:N children through the create DTO
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/wrtnlabs/autobe/issues/1295 | 来源类型 github_issue 暴露的待验证使用条件。

17. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/wrtnlabs/autobe | issue_or_pr_quality=unknown

18. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/wrtnlabs/autobe | release_recency=unknown