基于对抗式 Agent 的智能化软件工厂（Agora）

Agora 是一款 Electron 桌面应用，可以把自然语言形式的软件需求转换为一条可执行、可检查、可追踪的五阶段开发流水线。每个阶段由 Executor Agent 负责生成和修订产物，由 Critic Agent 独立检查问题；开发者还可以在阶段结束后提交人工意见，让 Agent 针对真实运行问题继续修改。

Agora 目前只允许连接 DeepSeek 官方 API。API Key 仅保存在当前进程的内存中，写入本地设置前会被删除。

代码仓库：GitLink · GitHub

Agora 工作台：首页显示已完成的 snake-game 项目和五阶段流水线

Agora 可以完成什么

默认流水线由五个按顺序执行的 Skills 组成：

自然语言需求
    │
    ▼
1. 需求分析 ──► 2. 架构设计 ──► 3. 代码编程
                                      │
                                      ▼
5. 文档生成 ◄────────────────── 4. 测试手册

每个阶段都会保存 Executor Agent 初稿、Critic Agent 评审意见、Executor Agent 修订稿、最终结果和可选的人工修订记录。代码编程和文档生成阶段还会解析模型输出中的 ### FILE: 文件块，将其写成可以直接检查和运行的多文件工程。

主要功能包括：

五个内置 Skills：需求分析、架构设计、代码编程、测试手册和文档生成。
Executor Agent 与 Critic Agent 分工协作，每个阶段可以单独设置评审迭代次数。
可选的人工确认环节，支持根据产品实际运行结果定向修改。
在项目页统一查看流水线进度、阶段记录、Agent 对话和产物文件。
使用 SQLite 保存项目历史，同时在独立 workspace 中保存可读文件。
写入文件前检查路径，拒绝绝对路径和越级目录。
从共享类型、主进程、IPC 到自动化测试共同限制为 DeepSeek 官方 API。
基于 Electron、React、TypeScript、Vite、pnpm workspace 和 better-sqlite3 构建。

环境要求

工具	支持版本	说明
Node.js	20 LTS 或 22 LTS	当前 `better-sqlite3` 依赖不建议使用 Node.js 24。
pnpm	9 或更高版本	Agora 使用 pnpm workspace，不要改用 npm 或 Yarn 安装依赖。
Git	当前稳定版本	用于克隆和管理代码。

检查本机环境：

node --version
pnpm --version
git --version

如果尚未安装 pnpm：

npm install --global pnpm

安装并启动项目

在 Windows PowerShell 中依次执行：

git clone https://gitlink.org.cn/junliz/agora.git
cd agora

pnpm install --frozen-lockfile
pnpm rebuild:native
pnpm dev

pnpm dev 会自动完成以下工作：

编译 shared 共享包。
启动 shared 和 Electron 主进程的 TypeScript 监听编译。
在 http://127.0.0.1:5173 启动 Vite 前端服务。
等待前端和主进程准备完成，然后打开 Electron 主窗口。

首次启动需要先生成主进程文件，窗口可能在命令执行数秒后才出现。

窗口没有自动打开

不要关闭正在运行的 pnpm dev。先检查终端是否满足以下两个条件：

Vite 已显示地址 http://127.0.0.1:5173。
已生成 packages/main/dist/index.js 和 packages/main/dist/preload.cjs。

如果两个条件都满足，可以在仓库目录中新开一个 PowerShell 窗口运行：

pnpm start

如果终端提示 better-sqlite3 与 Electron 版本不兼容，执行：

pnpm rebuild:native
pnpm dev

如果提示 5173 端口被占用，需要先结束之前遗留的 Vite 或 Agora 进程，再重新执行 pnpm dev。

首次配置 DeepSeek

启动后进入左侧的设置页面，依次配置两个模型槽位：

在模型 1 中填写有效的 DeepSeek API Key，然后点击“测试连接”。
从官方接口返回的模型列表中选择模型，并设置推理强度。
使用相同步骤配置模型 2。
将一个模型槽位设为 Executor Agent，另一个设为 Critic Agent。
如果希望每个阶段都由人工检查，打开“人工参与”。
点击“保存设置”。

固定配置如下：

配置项	取值
Provider	DeepSeek
Base URL	`https://api.deepseek.com`
Agent 角色	一个 Executor Agent、一个 Critic Agent
API Key 保存方式	仅保存在内存中，Agora 重启后自动清除

两个模型槽位都完成连接测试并选定模型后，才能启动开发流水线。

创建第一条流水线

进入 工作台，点击“新建任务”。
填写项目名称和清楚、具体的软件需求。
可以选择目标目录；如果留空，Agora 会在 workspaces/ 下自动创建项目目录。
点击“选择标准流水线”，启用全部五个 Skills。
在右侧预览区设置每个阶段的迭代次数。
点击“启动”。
在项目页查看 Run Trace、实时状态、阶段信息和产物列表。
如果启用了人工参与，在阶段完成后确认结果或提交需要修改的具体问题。

测试阶段生成的是 Markdown 格式的人工试用测试手册。开发者需要按照测试手册运行生成的软件；发现产品问题后，可以回到代码编程阶段提交反馈，由 Executor Agent 进行一次针对性修订。

系统架构

Agora 将用户界面、桌面端高权限操作、流水线编排和产物存储分为不同层次：

┌──────────────────────────────────────────────────────────────────────┐
│ Renderer 渲染进程 — React 界面                                     │
│ 工作台 · 项目页 · 技能库 · 设置页                                  │
└───────────────────────────────┬──────────────────────────────────────┘
                                │ 有类型约束、白名单限制的 IPC
                                ▼
┌──────────────────────────────────────────────────────────────────────┐
│ Preload 安全桥接                                                    │
│ 只向 Renderer 暴露界面实际需要的 IPC 方法                          │
└───────────────────────────────┬──────────────────────────────────────┘
                                ▼
┌──────────────────────────────────────────────────────────────────────┐
│ Electron 主进程                                                     │
│ 项目/设置 IPC · Pipeline Orchestrator · Skill Registry             │
├───────────────────────┬───────────────────────┬──────────────────────┤
│ DeepSeek 驱动        │ SQLite 数据库         │ Workspace 文件写入  │
│ Executor + Critic    │ 项目/对话/产物索引    │ 安全相对路径        │
└───────────────────────┴───────────────────────┴──────────────────────┘

每个阶段如何执行

Pipeline Orchestrator 对每个选中的 Skill 执行同一套受控流程：

读取前序阶段产物并组装输入
            │
            ▼
Executor Agent 生成阶段初稿
            │
            ▼
Critic Agent 检查遗漏、矛盾和风险
            │
            ▼
Executor Agent 输出完整修订稿
            │
            ├── 按本阶段设置的次数继续评审和修订
            ▼
最终结果写入 SQLite 和项目 workspace
            │
            ├── 可选人工反馈 → Executor Agent 定向修订一次
            ▼
进入下一个阶段

主进程通过单向 Pipeline 事件把运行进度发送给 Renderer。Renderer 不会直接访问模型、数据库或文件系统。

阶段之间的数据关系

阶段	主要输入	主要输出
需求分析	原始需求和补充上下文	用户故事、验收标准和约束
架构设计	需求分析结果	架构文档和接口约定
代码编程	需求与架构产物	`code/` 下的可运行文件和修改记录
测试手册	用户故事和生成代码	人工验收测试手册
文档生成	需求、架构、代码和测试结果	README 和配套文档

仓库结构

agora/
├── packages/
│   ├── shared/       # 共享类型、IPC 常量和设置迁移
│   ├── main/         # Electron 主进程、Pipeline、DeepSeek、SQLite、IPC
│   └── renderer/     # React 页面和流水线交互界面
├── skills/           # 内置 Skill 配置与提示模板
├── workspaces/       # 自动生成的软件项目和阶段记录
├── examples/         # 示例需求和 CLI 演示输入
├── scripts/          # 开发及演示脚本
├── docs/             # 架构、Skill 格式和设计文档
├── agora.db           # 本地项目历史数据库
└── package.json       # workspace 命令入口

自动生成的项目目录

每个软件产品都有独立的 workspace。阶段文件夹名称是当前程序真实使用的输出格式：

workspaces/<项目名称>/
├── 1-需求分析/
│   ├── 执行者-初稿.md
│   ├── 评审者-第1轮评审.md
│   ├── 执行者-第1轮修订.md
│   └── 最终输出.md
├── 2-架构设计/
├── 3-代码编程/
│   └── 执行者-人工修订1.md    # 提交人工意见后才会生成
├── 4-测试/
├── 5-文档/
└── code/                         # 可运行源代码和产品文档

SQLite 保存项目元数据、Agent 对话、人工干预和产物索引；workspace 保存可以直接阅读的 Markdown 过程文件及软件源代码。两种存储共同实现界面查询和文件级追踪。

常用开发命令

命令	作用
`pnpm dev`	编译 shared、启动监听和 Vite，然后打开 Electron。
`pnpm build`	构建 shared、main 和 renderer 三个包。
`pnpm test`	执行全部 Vitest 测试。
`pnpm lint`	检查 TypeScript 和 TSX 源代码。
`pnpm rebuild:native`	按 Electron 33 重新编译 `better-sqlite3`。
`pnpm pack`	构建并打包桌面应用。
`pnpm demo`	不启动 Electron，直接运行 CLI 演示。