# https://github.com/wrtnlabs/autobe 项目说明书

生成时间：2026-07-26 06:48:27 UTC

## 目录

- [项目概览与瀑布流模型](#page-overview)
- [系统架构与多阶段流水线](#page-architecture)
- [智能体编排与提示工程系统](#page-orchestration)
- [AI 友好编译器与类型安全保证](#page-compiler)
- [前端应用与用户界面](#page-frontend)
- [后端服务与会话管理](#page-backend)
- [基准测试与质量评估系统](#page-estimate)
- [社区热点问题与已知限制](#page-issues)

<a id='page-overview'></a>

## 项目概览与瀑布流模型

### 相关页面

相关主题：[系统架构与多阶段流水线](#page-architecture), [AI 友好编译器与类型安全保证](#page-compiler)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/wrtnlabs/autobe/blob/main/README.md)
- [website/src/content/docs/concepts/waterfall.mdx](https://github.com/wrtnlabs/autobe/blob/main/website/src/content/docs/concepts/waterfall.mdx)
- [website/src/content/docs/concepts/compiler.mdx](https://github.com/wrtnlabs/autobe/blob/main/website/src/content/docs/concepts/compiler.mdx)
- [packages/agent/src/orchestrate/orchestrateAnalyze.ts](https://github.com/wrtnlabs/autobe/blob/main/packages/agent/src/orchestrate/orchestrateAnalyze.ts)
- [packages/agent/src/orchestrate/orchestratePrisma.ts](https://github.com/wrtnlabs/autobe/blob/main/packages/agent/src/orchestrate/orchestratePrisma.ts)
- [packages/agent/src/orchestrate/orchestrateInterface.ts](https://github.com/wrtnlabs/autobe/blob/main/packages/agent/src/orchestrate/orchestrateInterface.ts)
- [packages/agent/src/orchestrate/orchestrateRealize.ts](https://github.com/wrtnlabs/autobe/blob/main/packages/agent/src/orchestrate/orchestrateRealize.ts)
- [packages/agent/src/orchestrate/orchestrateTest.ts](https://github.com/wrtnlabs/autobe/blob/main/packages/agent/src/orchestrate/orchestrateTest.ts)
</details>

# 项目概览与瀑布流模型

## 项目定位与核心能力

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

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

## 瀑布流五阶段模型

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

1. **analyze（需求分析）**：对话式澄清用户语义，产出需求规格 `AutoBeAnalyze`，包含业务概念、用户角色与业务流程。
2. **database（数据库设计）**：根据需求生成 Prisma schema 与 ER 文档，封装为 `AutoBeDatabase`。此阶段已知存在 audit 表缺 `created_at` 等回归问题（见 #1090）。资料来源：[orchestratePrisma.ts:1-80](https://github.com/wrtnlabs/autobe/blob/main/packages/agent/src/orchestrate/orchestratePrisma.ts)
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](https://github.com/wrtnlabs/autobe/blob/main/website/src/content/docs/concepts/waterfall.mdx)

```mermaid
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](https://github.com/wrtnlabs/autobe/blob/main/website/src/content/docs/concepts/compiler.mdx)

## 反向传播机制

传统瀑布流是单向的，但 #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](https://github.com/wrtnlabs/autobe/blob/main/packages/agent/src/orchestrate/orchestrateRealize.ts)

## 阶段产物对照

| 阶段 | 入口编排器 | 输出产物类型 | 典型文件来源 |
| --- | --- | --- | --- |
| analyze | `orchestrateAnalyze.ts` | `AutoBeAnalyze` | 需求对话上下文 |
| database | `orchestratePrisma.ts` | `AutoBeDatabase`（Prisma schema） | `*.prisma` |
| interface | `orchestrateInterface.ts` | `AutoBeOpenApi` | `openapi.json` |
| realize | `orchestrateRealize.ts` | `AutoBeRealize`（控制器 + DTO） | `*.controller.ts` |
| test | `orchestrateTest.ts` | `AutoBeTest` | `test_api_*.ts` |

资料来源：[orchestrateTest.ts:1-40](https://github.com/wrtnlabs/autobe/blob/main/packages/agent/src/orchestrate/orchestrateTest.ts)、[orchestrateInterface.ts:1-40](https://github.com/wrtnlabs/autobe/blob/main/packages/agent/src/orchestrate/orchestrateInterface.ts)

## 社区热点与待办

`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](https://github.com/wrtnlabs/autobe/blob/main/README.md)

## 小结

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

---

<a id='page-architecture'></a>

## 系统架构与多阶段流水线

### 相关页面

相关主题：[智能体编排与提示工程系统](#page-orchestration), [项目概览与瀑布流模型](#page-overview)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [.ai/ARCHITECTURE.md](https://github.com/wrtnlabs/autobe/blob/main/.ai/ARCHITECTURE.md)
- [.ai/AGENT_ORCHESTRATION.md](https://github.com/wrtnlabs/autobe/blob/main/.ai/AGENT_ORCHESTRATION.md)
- [.ai/STATE_MACHINE.md](https://github.com/wrtnlabs/autobe/blob/main/.ai/STATE_MACHINE.md)
- [.ai/EVENT_SYSTEM.md](https://github.com/wrtnlabs/autobe/blob/main/.ai/EVENT_SYSTEM.md)
- [packages/agent/src/orchestrate/facade/createAutoBeFacadeController.ts](https://github.com/wrtnlabs/autobe/blob/main/packages/agent/src/orchestrate/facade/createAutoBeFacadeController.ts)
</details>

# 系统架构与多阶段流水线

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](https://github.com/wrtnlabs/autobe/blob/main/.ai/ARCHITECTURE.md) ； [.ai/STATE_MACHINE.md](https://github.com/wrtnlabs/autobe/blob/main/.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](https://github.com/wrtnlabs/autobe/blob/main/.ai/AGENT_ORCHESTRATION.md) ； [issue #1274（Backward propagation）](https://github.com/wrtnlabs/autobe/issues/1274)

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

| 阶段 | 输入 | 产出（Artifact） | 主要 Agent |
| --- | --- | --- | --- |
| `analyze` | 用户需求 `AutoBeUserMessage` | `AutoBeAnalyze` 需求文档 | `analyzeAgent` |
| `database` | `AutoBeAnalyze` | `AutoBeDatabase`（Prisma 风格 schema + 关系元数据） | `databaseAgent` + 可能的 review sub-agent |
| `interface` | `AutoBeAnalyze` + `AutoBeDatabase` | `AutoBeOpenApi`（包含 `authorizationRole`、`authorizationType` 的 IOperation） | `interfaceAgent` |
| `realize` | `AutoBeOpenApi` + `AutoBeDatabase` | `AutoBeRealize`（NestJS 控制器代码 + DTO + Prisma 客户端调用） | `realizeAgent` |
| `test` | `AutoBeRealize` + `AutoBeOpenApi` | `AutoBeTest`（e2e 测试函数集合，去重后生成） | `testScenarioAgent` + `testAgent` |

资料来源：[.ai/ARCHITECTURE.md](https://github.com/wrtnlabs/autobe/blob/main/.ai/ARCHITECTURE.md) ； [.ai/AGENT_ORCHESTRATION.md](https://github.com/wrtnlabs/autobe/blob/main/.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](https://github.com/wrtnlabs/autobe/blob/main/.ai/STATE_MACHINE.md) ； [.ai/EVENT_SYSTEM.md](https://github.com/wrtnlabs/autobe/blob/main/.ai/EVENT_SYSTEM.md) ； [packages/agent/src/orchestrate/facade/createAutoBeFacadeController.ts](https://github.com/wrtnlabs/autobe/blob/main/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）](https://github.com/wrtnlabs/autobe/issues/311) ； [issue #448（test scenario agent 考虑 authorization）](https://github.com/wrtnlabs/autobe/issues/448) ； [issue #1295（required-owned has-relations）](https://github.com/wrtnlabs/autobe/issues/1295) ； [.ai/ARCHITECTURE.md](https://github.com/wrtnlabs/autobe/blob/main/.ai/ARCHITECTURE.md)

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

---

<a id='page-orchestration'></a>

## 智能体编排与提示工程系统

### 相关页面

相关主题：[系统架构与多阶段流水线](#page-architecture), [AI 友好编译器与类型安全保证](#page-compiler)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [packages/agent/src/orchestrate/analyze/orchestrateAnalyze.ts](https://github.com/wrtnlabs/autobe/blob/main/packages/agent/src/orchestrate/analyze/orchestrateAnalyze.ts)
- [packages/agent/src/orchestrate/database/orchestrateDatabase.ts](https://github.com/wrtnlabs/autobe/blob/main/packages/agent/src/orchestrate/database/orchestrateDatabase.ts)
- [packages/agent/src/orchestrate/interface/orchestrateInterface.ts](https://github.com/wrtnlabs/autobe/blob/main/packages/agent/src/orchestrate/interface/orchestrateInterface.ts)
- [packages/agent/src/orchestrate/realize/orchestrateRealize.ts](https://github.com/wrtnlabs/autobe/blob/main/packages/agent/src/orchestrate/realize/orchestrateRealize.ts)
- [packages/agent/src/orchestrate/test/orchestrateTest.ts](https://github.com/wrtnlabs/autobe/blob/main/packages/agent/src/orchestrate/test/orchestrateTest.ts)
- [packages/agent/src/utils/RAGRetrieval.ts](https://github.com/wrtnlabs/autobe/blob/main/packages/agent/src/utils/RAGRetrieval.ts)
- [packages/agent/prompts](https://github.com/wrtnlabs/autobe/tree/main/packages/agent/prompts)
</details>

# 智能体编排与提示工程系统

## 系统概述与核心职责

`@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 也能"记忆"前序决策。下表给出关键阶段与其产出物映射：

| 阶段 | 入口文件 | 主要产出 | 下游消费者 |
| --- | --- | --- | --- |
| analyze | orchestrateAnalyze.ts | 需求条目 / 角色 / 用户故事 | database |
| database | orchestrateDatabase.ts | Prisma Schema + 评审报告 | interface |
| interface | orchestrateInterface.ts | OpenAPI `IOperation`、DTO、授权标注 | realize, test |
| realize | orchestrateRealize.ts | NestJS 控制器 / Provider | test |
| test | orchestrateTest.ts | E2E 测试场景与函数 | 编译/运行 |

`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/](https://github.com/wrtnlabs/autobe/tree/main/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

---

<a id='page-compiler'></a>

## AI 友好编译器与类型安全保证

### 相关页面

相关主题：[系统架构与多阶段流水线](#page-architecture), [智能体编排与提示工程系统](#page-orchestration)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [packages/compiler/src/AutoBeCompiler.ts](https://github.com/wrtnlabs/autobe/blob/main/packages/compiler/src/AutoBeCompiler.ts)
- [packages/compiler/src/database/AutoBeDatabaseCompiler.ts](https://github.com/wrtnlabs/autobe/blob/main/packages/compiler/src/database/AutoBeDatabaseCompiler.ts)
- [packages/compiler/src/interface/AutoBeInterfaceCompiler.ts](https://github.com/wrtnlabs/autobe/blob/main/packages/compiler/src/interface/AutoBeInterfaceCompiler.ts)
- [packages/compiler/src/realize/AutoBeRealizeCompiler.ts](https://github.com/wrtnlabs/autobe/blob/main/packages/compiler/src/realize/AutoBeRealizeCompiler.ts)
- [.ai/AST_DESIGN.md](https://github.com/wrtnlabs/autobe/blob/main/.ai/AST_DESIGN.md)
- [.ai/COMPILER_SYSTEM.md](https://github.com/wrtnlabs/autobe/blob/main/.ai/COMPILER_SYSTEM.md)
</details>

# AI 友好编译器与类型安全保证

`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]()

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

| 阶段 | 编译器 | 输入 | 输出 | 类型校验手段 |
|------|--------|------|------|--------------|
| Analyze | AutoBeAnalyzeCompiler | 用户对话历史 | AutoBeAnalyzeHistory | JSON Schema + AST 校验 |
| Database | AutoBeDatabaseCompiler | 分析报告 | Prisma Schema (AST) | tsc + Prisma parse |
| Interface | AutoBeInterfaceCompiler | 数据模型 | OpenAPI IOperation | TypeScript AST |
| Realize | AutoBeRealizeCompiler | OpenAPI 文档 | NestJS Controller 代码 | tsc + typia 运行时校验 |
| Test | AutoBeTestCompiler | 接口 + 实现 | E2E 测试函数 | tsc + typia |

资料来源：[.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]()

```mermaid
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]()

---

<a id='page-frontend'></a>

## 前端应用与用户界面

### 相关页面

相关主题：[后端服务与会话管理](#page-backend)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [apps/playground-ui/src/AutoBePlaygroundApplication.tsx](https://github.com/wrtnlabs/autobe/blob/main/apps/playground-ui/src/AutoBePlaygroundApplication.tsx)
- [apps/hackathon-ui/src/AutoBePlaygroundApplication.tsx](https://github.com/wrtnlabs/autobe/blob/main/apps/hackathon-ui/src/AutoBePlaygroundApplication.tsx)
- [apps/dashboard-ui/src/AutoBeDashboardApplication.tsx](https://github.com/wrtnlabs/autobe/blob/main/apps/dashboard-ui/src/AutoBeDashboardApplication.tsx)
- [apps/vscode-extension/src/extension.ts](https://github.com/wrtnlabs/autobe/blob/main/apps/vscode-extension/src/extension.ts)
- [apps/vscode-extension/webview-ui/src/App.tsx](https://github.com/wrtnlabs/autobe/blob/main/apps/vscode-extension/webview-ui/src/App.tsx)
- [packages/ui/src/components](https://github.com/wrtnlabs/autobe/blob/main/packages/ui/src/components)
</details>

# 前端应用与用户界面

AutoBE 项目在 `apps/` 目录下并行维护了多套面向不同场景的前端入口，并在 `packages/ui` 中沉淀了共享的可视化组件。该架构既能让普通用户在浏览器中交互式运行完整的 Vibe Coding 流水线，又能为基准测试、研讨会和 IDE 集成提供差异化入口。

## 总体架构与分层

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

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

```mermaid
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](https://github.com/wrtnlabs/autobe/blob/main/apps/playground-ui/src/AutoBePlaygroundApplication.tsx) 引导启动。该应用的核心职责包括：

- **多会话管理**：自 [v0.30.4](https://github.com/wrtnlabs/autobe/releases/tag/v0.30.4) 起，playground 切换为"多会话后端服务"，允许开发者并行运行多个独立的 AutoBE 会话而互不干扰。
- **阶段可视化**：界面在右侧绘制流水线进度条，标注 Analyze / Database / Interface / Realize / Test 五个阶段。`realize` 与 `test` 的顺序依赖（[issue #1274](https://github.com/wrtnlabs/autobe/issues/1274)）会即时反映在该视图上，避免用户在尚未实现控制器时过早触发测试。
- **本地 LLM 配置**：支持 Ollama、LM Studio 等本地模型接入。早期版本存在"无法保存本地 LLM 配置"的 Bug（[issue #1290](https://github.com/wrtnlabs/autobe/issues/1290)），现已在 [v0.31.1](https://github.com/wrtnlabs/autobe/releases/tag/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](https://github.com/wrtnlabs/autobe/blob/main/apps/dashboard-ui/src/AutoBeDashboardApplication.tsx) 启动。

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

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

## VSCode 扩展与共享组件库

- **VSCode 扩展入口**：[extension.ts](https://github.com/wrtnlabs/autobe/blob/main/apps/vscode-extension/src/extension.ts) 负责在 VSCode 中注册 Webview；[webview-ui/src/App.tsx](https://github.com/wrtnlabs/autobe/blob/main/apps/vscode-extension/webview-ui/src/App.tsx) 则在该 Webview 内渲染与 Playground 几乎一致的 React 界面，从而实现 IDE 内的同构体验。
- **共享组件库**：`packages/ui/src/components` 集中维护 `ChatPanel`、`PipelineVisualizer`、`ScoreModal`、`FileBrowser` 等部件。应用层只在各自入口处做样式与路由适配，复用率较高。
- **常见 UI 问题**：端口不一致是 Playground 历史 Bug 的主要来源之一（[issue #1252](https://github.com/wrtnlabs/autobe/issues/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]()

---

<a id='page-backend'></a>

## 后端服务与会话管理

### 相关页面

相关主题：[前端应用与用户界面](#page-frontend), [系统架构与多阶段流水线](#page-architecture)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [apps/playground-server/src/AutoBePlaygroundServer.ts](https://github.com/wrtnlabs/autobe/blob/main/apps/playground-server/src/AutoBePlaygroundServer.ts)
- [apps/hackathon-server/src/AutoBeHackathonBackend.ts](https://github.com/wrtnlabs/autobe/blob/main/apps/hackathon-server/src/AutoBeHackathonBackend.ts)
- [apps/playground-server/src/providers/sessions/AutoBePlaygroundSessionProvider.ts](https://github.com/wrtnlabs/autobe/blob/main/apps/playground-server/src/providers/sessions/AutoBePlaygroundSessionProvider.ts)
- [apps/hackathon-server/src/providers/sessions/acceptors/AutoBeHackathonSessionCompiler.ts](https://github.com/wrtnlabs/autobe/blob/main/apps/hackathon-server/src/providers/sessions/acceptors/AutoBeHackathonSessionCompiler.ts)
- [apps/playground-server/prisma/schema/main.prisma](https://github.com/wrtnlabs/autobe/blob/main/apps/playground-server/prisma/schema/main.prisma)
- [.ai/RPC_SYSTEM.md](https://github.com/wrtnlabs/autobe/blob/main/.ai/RPC_SYSTEM.md)
</details>

# 后端服务与会话管理

## 概述

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]()

| 组件 | 作用范围 | 主要职责 |
|------|---------|---------|
| AutoBePlaygroundServer | 本地 Playground | 启动 HTTP/RPC、注册会话提供者 |
| AutoBeHackathonBackend | 评测后端 | 装配 acceptor 链、托管编译结果 |
| AutoBePlaygroundSessionProvider | Playground 会话 | 创建/复用/回收会话实例 |
| AutoBeHackathonSessionCompiler | Hackathon acceptor | 编译请求上下文并下发会话 |

## 数据持久化与 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]()

---

<a id='page-estimate'></a>

## 基准测试与质量评估系统

### 相关页面

相关主题：[社区热点问题与已知限制](#page-issues)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [packages/estimate/src/cli/program.ts](https://github.com/wrtnlabs/autobe/blob/main/packages/estimate/src/cli/program.ts)
- [packages/estimate/src/agents](https://github.com/wrtnlabs/autobe/blob/main/packages/estimate/src/agents)
- [packages/estimate/src/evaluators](https://github.com/wrtnlabs/autobe/blob/main/packages/estimate/src/evaluators)
- [packages/estimate/src/core/score-calculator.ts](https://github.com/wrtnlabs/autobe/blob/main/packages/estimate/src/core/score-calculator.ts)
- [packages/estimate/prompts](https://github.com/wrtnlabs/autobe/blob/main/packages/estimate/prompts)
- [packages/estimate/bench](https://github.com/wrtnlabs/autobe/blob/main/packages/estimate/bench)
- [packages/benchmark](https://github.com/wrtnlabs/autobe/blob/main/packages/benchmark)
- [packages/interface/src/ui](https://github.com/wrtnlabs/autobe/blob/main/packages/interface/src/ui)
</details>

# 基准测试与质量评估系统

## 概述

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

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

| 层级 | 路径 | 职责 |
|------|------|------|
| 命令行入口 | `packages/estimate/src/cli/program.ts` | 注册子命令、读取配置、调度智能体与评估器 |
| 评分智能体 | `packages/estimate/src/agents` | 通过 LLM 对每个阶段的产出做定性判定 |
| 评估器 | `packages/estimate/src/evaluators` | 按阶段定义评分维度（功能性、完整性、编译性等） |
| 分数计算器 | `packages/estimate/src/core/score-calculator.ts` | 汇总各阶段分数、计算加权总分与置信度 |
| 提示词模板 | `packages/estimate/prompts` | 评分智能体的 system/用户提示词 |
| 基准数据集 | `packages/estimate/bench` | 预置的需求描述与期望产出快照 |

资料来源：[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` 是整个系统的核心，其典型执行流程如下：

```mermaid
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]()

---

<a id='page-issues'></a>

## 社区热点问题与已知限制

### 相关页面

相关主题：[智能体编排与提示工程系统](#page-orchestration), [基准测试与质量评估系统](#page-estimate)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [.ai/OPTIMIZATION.md](https://github.com/wrtnlabs/autobe/blob/main/.ai/OPTIMIZATION.md)
- [README.md](https://github.com/wrtnlabs/autobe/blob/main/README.md)
- [packages/agent/src/orchestrate/database/orchestrateDatabaseCorrect.ts](https://github.com/wrtnlabs/autobe/blob/main/packages/agent/src/orchestrate/database/orchestrateDatabaseCorrect.ts)
- [packages/agent/src/orchestrate/prisma.ts](https://github.com/wrtnlabs/autobe/blob/main/packages/agent/src/orchestrate/prisma.ts)
- [packages/agent/src/orchestrate/realize/orchestrateRealizeAuthorizationCorrect.ts](https://github.com/wrtnlabs/autobe/blob/main/packages/agent/src/orchestrate/realize/orchestrateRealizeAuthorizationCorrect.ts)
- [packages/agent/src/orchestrate/realize/orchestrateRealizeControllerCorrect.ts](https://github.com/wrtnlabs/autobe/blob/main/packages/agent/src/orchestrate/realize/orchestrateRealizeControllerCorrect.ts)
- [packages/agent/src/orchestrate/test/orchestrateTestScenario.ts](https://github.com/wrtnlabs/autobe/blob/main/packages/agent/src/orchestrate/test/orchestrateTestScenario.ts)
- [packages/agent/src/utils/RAGRetrieval.ts](https://github.com/wrtnlabs/autobe/blob/main/packages/agent/src/utils/RAGRetrieval.ts)
- [packages/agent/prompts/TEST_SCENARIO.md](https://github.com/wrtnlabs/autobe/blob/main/packages/agent/prompts/TEST_SCENARIO.md)
- [packages/playground/src/index.ts](https://github.com/wrtnlabs/autobe/blob/main/packages/playground/src/index.ts)
</details>

# 社区热点问题与已知限制

本页整理 AutoBe 用户在实际使用中频繁反馈的问题及其对应的源码定位，帮助开发者理解当前各 Agent 的能力边界与已落地/未落地的修复。所有条目均与社区工单及源码模块一一对应。

## 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 检索进行局部降本，但完整迁移尚未完成。

## 已知限制小结表

| 阶段 | 已知问题 | 主要受影响文件 | 状态 |
|---|---|---|---|
| database | 缺少 ownership 语义 (#1295) | `orchestrateDatabaseCorrect.ts` | Open |
| database | 审计表缺 `created_at` (#1090) | `orchestratePrisma.ts` | Partial（v0.31.0） |
| realize | 非法表名 / switch 重复 (#1082, #1089) | `orchestrateRealizeControllerCorrect.ts` | Correct 阶段修复 |
| test | 未感知授权、命名重复 (#448, #991) | `orchestrateTestScenario.ts`、`TEST_SCENARIO.md` | Open |
| 工具链 | 端口错字、本地 LLM (#1252, #1290) | `playground/src/index.ts`、README | Fixed in v0.31.1 |
| 全局 | Token 过高、RAG 不完整 (#311) | `utils/RAGRetrieval.ts` | In Progress |

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

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：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

<!-- canonical_name: wrtnlabs/autobe; human_manual_source: deepwiki_human_wiki -->