logan-suu/Agora

🏛️ Agora

一个由人类主导的群聊工作空间，AI 智能体在其中共同规划、编码、测试和审查。

目录

- 当前产品
- 产品演示
- 什么是 Agora？
- 证据与局限
- 架构
- 快速开始（macOS）
- 技术栈
- 仓库布局
- 路线图
- 设计文档
- 项目状态与范围

当前范围：本地使用。 在你自己的电脑上运行 Agora，并在浏览器中打开其本地地址。后端、Docker 沙箱和 Git 工作树都在该机器上运行，应用数据存储在本地。云托管不在当前产品范围内。模型请求会发送到你选择的在线 API 或本地模型服务；本地运行并不意味着离线运行。产品安装和启动命令目前支持 macOS。Linux 产品启动器和自动凭据设置不在该任务的当前范围内；现有的 Linux 沙箱支持是另一回事。

计划发布的版本。 第 10 阶段已完成。第 11–13 阶段将引入 Electron、托管工具链和原生 Mac 开发，并淘汰 Agora 的 Docker 后端，且不迁移旧任务。第 11 和第 12 阶段为有限预览；第 13 阶段接受完整的原生工作流。这些功能是计划中的，在当前源代码构建中尚不可用。以下说明适用于现有的基于 Docker 的实现。有关更小的发布里程碑，请参阅路线图。

macOS 上的凭据设置。 本地启动器在首次使用时会在你的 macOS 钥匙串中创建一个随机加密密钥，并在重启后复用该密钥。在模型设置对话框中，输入你的服务的 Base URL、API 密钥和模型名称，可以针对单个 Agent 或整个团队。访问钥匙串可能需要 macOS 授权。当无法访问原始密钥时，现有的加密连接将保持不可用；应用程序会显示恢复说明，并且绝不会静默替换它。

Agora 的名字来源于古希腊的 agorá：人们聚集在一起交流想法并做出决定的公共集会场所。本项目将这一理念带入软件开发——专业化的 AI 智能体在一个共享、可见的空间中工作，而人类 Leader 始终在场并做出最终决定。

TypeScript
Node.js
Next.js
MCP
Status

当前产品

Agora 在你的 Mac 上运行一个六角色编码团队。独立的 Coder 工作者可以在各自的 Git worktree 和 Docker 容器中并发执行。团队在评审前验证累积的工作成果；由人类 Leader 批准最终完成。

- 指挥工作： 在普通聊天中描述需求变更，查看前后对比提案，然后点击 Confirm changes。模糊的请求可以要求澄清；提案绝不会自行应用。现有的决策命令仍可通过同一聊天入口使用。
- 阅读讨论： 消息支持 Markdown 标题、列表、引用、链接、代码块和表格。需求和评审以可读的章节形式呈现，其原始 JSON 可按需查看。
- 检查执行： 查看持久化的进度和会话时间线，包括并发工作者和恢复的会话谱系。
- 保留权限： 普通测试失败会返回修复；阻塞性异议和最终完成需要 Leader 批准。
- 选择模型： 为整个团队或单个角色配置兼容 OpenAI 的服务。新验证的 DeepSeek V4 连接默认使用 1M 上下文窗口和 384K 最大输出，并自动进行 Harness 历史压缩；自定义限制仍可独立编辑。
- 保留产物： 执行资源释放后，已完成的代码和测试仍然可用。

从 快速开始 开始。参见 最终基准报告、工程面试笔记 和 当前产品演示。Phase 10 最终验收已完成；其 验收证据 与演示和冻结基准分开。

产品演示

https://github.com/user-attachments/assets/d24f4192-8353-43b8-b164-0cbcf700abc2

一个真实任务：描述目标，用通俗英语更改票价，查看并确认提案，修复验证中发现的问题，然后批准完成并保留产物。英文录制包含真实的返工，并剪掉了等待时间。返工和最终批准使用现有的 gate 命令；聊天中不会粘贴 JSON。参见 录制证据、编辑说明和可下载产物。归档输出通过了 18 个项目测试以及 8 个独立检查。

什么是 Agora？

Agora 是一个有明确主张的多智能体编码产品，而不是通用的智能体聊天 SDK。它将软件交付呈现为六个角色之间的群组对话：

- Coordinator 负责路由工作并跟踪进度。
- PM 在任务需要时澄清需求。
- Architect 产出实现边界和决策。
- Coder 在隔离的工作区中更改代码。
- 测试员运行验收检查并报告证据。
- 审查员建议完成或要求返工；由 Leader 做出最终决定。
- Leader（你）可以观察、重定向、批准或否决团队。

可见的聊天是一个控制界面，而不是智能体的原始上下文。每个角色都会收到共享状态的结构化投影，其中仅包含它所需的事实、决策、文件引用和本地频道上下文。这可以防止长对话变成每个智能体共享的不断增长的提示词。

Agora 的核心设计规则是：

- 一个协作界面：通信在群聊 UI 中以频道形式呈现。
- 一个最终权威：智能体可以提出异议，但由人类 Leader 决定；智能体不会通过投票自行达成共识。
- 按角色投影的上下文：显示消息和模型载荷是分开的，原始聊天日志绝不会被整体注入。
- 统一 Harness 智能体：每个角色都使用 Agora 自有的、基于 DeepSeek Harness 构建的智能体实现。Harness 提供智能体循环、会话持久化和压缩；Agora 实现角色投影和协作控制。外部编码智能体执行器不在产品范围内。
- 真实执行证据：编码任务通过沙箱、MCP、Git、测试、持久化和恢复路径运行，而不是仅做 UI 模拟。

证据与局限

最终评估使用固定的四项 Aider Polyglot JavaScript 子集和两项内部协作任务，每项任务和变体进行三次独立尝试。这些是小规模探索性比较，而不是完整的基准排名。

| 冻结组 | 变体 | 总体通过 / 尝试次数 |
| --- | --- | --- |
| Public v11 | 单一 Harness 智能体 | 12 / 12 |
| Public v11 | 多角色，单一模型 | 11 / 12 |
| Public v11 | 多角色，混合模型 | 10 / 12 |
| Internal v14 | 同一 DAG 的串行执行 | 6 / 6 |
| Internal v14 | 并行执行 | 4 / 6 |
| Internal v14 | 稀疏结构化频道上下文 | 4 / 6 |

Public v11 和 internal v14 使用不同的冻结源版本，并分别报告。所有非混合变体都通过 OpenCode Go 使用 deepseek-v4-flash；混合变体对 PM、Architect 和 Reviewer 使用 deepseek-flash。提供商模型别名并不保证固定权重。

在串行和并行运行均通过的四个内部配对中，平均速度比为 1.38 ± 0.20 样本标准差。并行通过了 4/6 次尝试，而串行为 6/6；所选的成功配对并不能确立普遍的速度或可靠性优势。在公共子集上，多角色在 11 个成功配对中平均增加了 176.12 秒。多智能体协调具有可测量的开销。
失败包括审查中断、请求/时间预算耗尽以及流式连接断开。从未进入独立评分的尝试并不能证明代码不正确。Worker Fork 和 history compaction 在这些最终分组中未被触发；单独的功能检查覆盖了这些机制。未知用量仍然未知；订阅配额估算和保守的预算预留并非现金计费总额。

完整报告包含配置、失败、机制覆盖和历史尝试。公开指标和内部指标提供各项结果、样本量和方差。这些冻结的测量结果并非对之后每个源代码修订版本的全新评估。

当前边界：

- macOS 产品安装；Linux 启动器和自动凭据设置已推迟。
- 本地、单用户、单后端运行；模型 API 可以在线。
- 通过所配置的兼容提供商使用 Chat Completions、SSE 和函数工具；不声称兼容仅支持 Responses 和仅支持 OAuth 的服务。
- 自定义角色可以在支持的地方注册并显式分配。任意自定义角色的自主路由已推迟；并行计划会拒绝缺少所需 wave/subtask 绑定的分配。
- 意外的进程退出不承诺自动继续所有未完成的工作。
- 角色投影和沙箱控制会强制执行特定边界；它们不保证无限的上下文、完美的模型决策或对一切攻击的免疫力。

有关证据和权衡，请参阅推迟项和工程笔记。框架调研是一份有时效性的设计输入，而不是对其他框架当前功能的排名。

架构

flowchart TB
Leader[Human Leader]  Web[Local group chat]
Web -->|Task lifecycle and message POST| App[Application services and orchestration]
App --> Scheduler[Global worker leases]
Scheduler --> Workers[Independent Harness workers]
Workers --> Projection[Current role and assignment projection]
Projection --> Loop[Official Harness loop and history]
Loop --> MCP[MCP tools]
MCP --> Worktrees[Task-owned Git worktrees and Docker containers]
Worktrees --> Validation[Integration and cumulative test validation]
Validation --> Review[Reviewer completion candidate]
Review --> Gate[Leader completion gate]
Leader -->|Approve or request changes| Gate
Gate -->|Approved evidence| Artifacts[Archived code and tests]
App --> Commit[Serialized task commit via applyMutations]
Workers --> Commit
Commit --> State[Atomic JSON task state]
State -->|Committed display messages| Bus[MessageBus and SSE]
Bus --> Web
Loop --> Sessions[Official Harness JSONL sessions]
Sessions -->|有界安全 Trace 快照| Web

模型调用和工具调用可以重叠；共享任务提交是串行化的。每个 worker 持有全局调度器租约，并且只接收其角色/分配切片。独立代码按波次集成，Tester 证据绑定已验证的累积提交。Reviewer 批准会创建一个候选；只有 Leader 的批准才能将其最终确定。

非阻塞指令在安全点更新结构化状态，并重新投影现有 worker 上下文。阻塞门会持久化检查点、释放可执行资源，随后在具有已验证会话谱系的全新 Harness 上下文中恢复暂停的 worker。Trace 派生自官方会话日志；它不会暴露原始提示、推理或工具参数/结果。

快速开始（macOS）

第一次为开发设置 Mac？ 请先遵循新 Mac 安装指南。它会引导你安装每个工具、检查版本、修复缺失的依赖项，并首次打开 Agora。必须安装并运行 Docker Desktop；Agora 不会捆绑它。

先决条件

- macOS，带有 Node.js 24 和 pnpm 9.15.9（package.json 中固定的版本）
- Git 和 Xcode Command Line Tools（clang）
- Docker Desktop 及其守护进程正在运行
- 一个兼容的 Chat Completions 服务，支持 SSE 和函数工具，可在线或本地运行

新的产品启动器目前在 Linux 上报告不支持的平台。现有 POSIX 沙箱的 Linux 支持是独立的；Linux 产品设置被推迟为 DEF-017。

在克隆之前，在终端中检查你的工具：
bash
node --version
pnpm --version
git --version
/usr/bin/clang --version
docker --version
docker info --format '{{.ServerVersion}}'

Node 必须报告 v24.x.x，pnpm 必须报告 9.15.9，其余命令必须成功。安装链接和修复步骤在指南中。

安装、检查并启动
bash
git clone https://github.com/logan-suu/Agora.git
cd Agora
pnpm install --frozen-lockfile
pnpm run setup
pnpm run doctor
pnpm start

请明确使用 pnpm run setup：pnpm setup 是 pnpm 自己的 shell 配置命令。Agora 的 setup 会检查依赖项、构建受信任的沙箱和 Keychain 辅助程序，并创建 Next.js 生产构建。它不会为你安装系统依赖项或启动 Docker Desktop。更新源代码后请再次运行 setup。

如果 setup 或 doctor 失败，请遵循其针对具体依赖项的修复步骤和故障排除指南。一旦 Node 和检出可用，即使 pnpm 不可用，node apps/web/scripts/local.mjs doctor 也会运行诊断。诊断会一并报告缺失的工具和版本不匹配，并区分不可用的 Docker CLI 和无法访问的引擎。
打开 http://127.0.0.1:3000。如果该端口已被占用，请使用 pnpm start --port 3100，并打开启动器打印的地址。服务器仅绑定到回环接口，并拒绝跨站写入。同一数据目录的重复启动器会被拒绝。

1. 选择 Set model for all Agents，或某个 Agent 的 Model 按钮。
2. 输入 Base URL 和模型名称。输入 API key，或为本地服务明确选择无身份验证。
3. 保存。保存不会调用模型；Test connection 会发送一个简短的模型请求。
4. 输入任务 ID 和目标，然后启动任务。
5. 在主/子频道和 Trace 中跟踪团队。完成任何必需的 Leader gate；Reviewer 批准会生成一个完成候选，随后由你进行最终批准。

设置更改会应用于新任务。现有任务和已暂停的会话保留其原始模型绑定。多个任务共享现有的全局 worker 限制；这不会改变单用户、单后端实例的边界。

停止和重启

在启动终端中按 Ctrl+C，或在此 checkout 中的另一个终端运行 pnpm stop。如果你使用自定义的 AGORA_DATA_ROOT，停止时请提供相同的值。

停止会关闭新工作的准入，并等待活动的模型请求和任务完成或到达现有的人工 gate。这可能需要一些时间；请留意终端的 draining 消息。没有超时会强制终止进行中的模型。如果资源清理失败，请保持进程打开并重试停止。数据、暂停的 worktree、会话、artifacts 和 Keychain 项都会保留。pnpm start 会重新打开相同的数据和凭据。

意外进程退出会保留现有的恢复规则：持久化的人工 gate 可以通过其持久化的 receipt 恢复；其他未完成的工作会显示为已中断，不承诺自动继续。崩溃后，可能会残留一个陈旧的本地控制 socket。启动错误会打印其确切路径。在移除该 socket 之前，请确认旧的 Agora 进程已退出；不要在实例处于活动状态时移除它。

配置和恢复

| 设置 | 用途 |
| --- | --- |
| Model settings dialog | 按 Agent 或团队范围的 Base URL、API key、模型名称以及可选的 token 限制 |
| AGORA_DATA_ROOT | 可选的数据目录；默认是此 checkout 的 .data |
| AGORA_MODEL | 可选的旧版默认模型，在未选择已保存连接时使用 |
| DEEPSEEK_API_KEY | 可选的旧版默认提供商凭据；仓库的实时 DeepSeek 测试需要它 |
| AGORA_CREDENTIALS_KEY | 高级兼容性覆盖：一个规范的 base64 编码的 32 字节密钥，仅用于该进程 |
正常启动不需要 master-key 环境变量或编辑 .env。macOS Keychain 身份为服务 com.agora.local.credentials，账户等于当前 macOS 用户名，保留先前的本地设置。显式提供的覆盖项优先；空或无效的覆盖项会失败，而不是回退。覆盖项不会自动替换 Keychain 项或重新加密历史记录。

对于现有的高级环境设置，pnpm credentials:adopt 会在检查所有已保存的加密连接后，将该同一密钥显式导入 Keychain。它只会创建缺失的项或复用完全相同的项；冲突的 Keychain 密钥会被拒绝。之后请从启动环境中移除该覆盖项。此操作绝不会打印密钥。

如果 Keychain 已锁定，请解锁并重启。如果访问被拒绝，请在 macOS 中允许受信任的 Agora 辅助程序并重启。缺失或不匹配的历史密钥需要恢复原始密钥，而不是生成替代密钥。损坏的配置需要有效的备份。当加密凭据不可用时，其他路径（包括无认证的模型连接）仍然可用。

使用受保护的备份设施同时备份 .data 和原始 macOS Keychain。仅复制 .data 会保留 API 密钥密文，但不包含其解密密钥。停止或更新 Agora 不会删除二者中的任何一个。请将两份备份都保密；切勿提交 API 密钥或环境文件。

验证仓库
bash
pnpm build:sandbox-native
pnpm build:keychain-native
pnpm typecheck
pnpm lint
pnpm test
pnpm --filter @agora/web build

macOS 测试套件包含一个一次性的、受密码保护的 Keychain，并保留用户的登录 Keychain。Docker 和已配置的实时模型测试必须运行；缺失的权限/依赖项会被报告为验证不完整，而不是跳过通过。显式任务 10.4 启动器和实时模型 G5 命令及结果记录在本地启动证据中。

技术栈

| 层级 | 技术 |
| --- | --- |
| 语言/运行时 | TypeScript 5.9+、Node.js 24 |
| Web UI | Next.js 15、React 19 |
| 单智能体内核 | DeepSeek Harness/Cordis 生态系统 |
| 协调 | 自研轻量级四节点编排器 |
| 工具协议 | MCP TypeScript SDK |
| 沙箱 | 每个工作树使用 Docker，并保留 LocalTemp 适配器用于低阶段测试 |
| 源码隔离 | 通过 simple-git 管理的 Git 工作树 |
| 持久化 | 原子 JSON 快照、官方 Harness JSONL 会话以及 .data/ 下归档的任务产物 |
| 实时传输 | 接收使用 SSE，发送使用 HTTP POST |
| 测试/质量 | Vitest 3、TypeScript、Biome 2 |
| 工作区 | pnpm 9 monorepo |

仓库布局
text
Agora/
├── apps/web/                       # Next.js 群聊 UI 和本地服务器组合
├── packages/
│   ├── core/
│   │   ├── domain/                 # 状态、变更、角色和纯领域逻辑
│   │   ├── orchestration/          # 协调器路由和四节点循环
│   │   └── preemption/             # 协作式抢占领域原语
│   ├── runtime/
│   │   ├── executor/               # Harness 执行器和角色投影
│   │   ├── sandbox/                # Docker 和本地临时沙箱适配器
│   │   └── state/                  # TaskStateStore 端口和 JSON 适配器
│   ├── comm/{bus,channels}/        # MessageBus 和通道/收件箱逻辑
│   ├── roles/definitions/          # 数据驱动的角色规范
│   ├── tools/{bridge,fs,git,lint,sandbox,test}/
│   └── shared/
├── tests/integration/              # 阶段和跨阶段验收套件
├── docs/                           # 蓝图、详细设计、计划、决策、状态
├── .agents/skills/                 # Codex 的项目工作流技能
└── README.md

路线图

| 阶段 | 成果 | 状态 |
| --- | --- | --- |
| 0 | 状态/归约器骨架、Harness 工作器、本地沙箱 | ✅ 已完成 |
| 1 | Docker 沙箱和 MCP 执行工具 | ✅ 已完成 |
| 2 | 六角色编码、测试、审查和反馈循环 | ✅ 已完成 |
| 3 | 角色投影、结构化交接和决策台账 | ✅ 已完成 |
| 4 | 自适应 Tier 0/1/2 编排 | ✅ 已完成 |
| 5 | 可恢复的群聊 MVP 和真实浏览器触发的循环 | ✅ 已完成 |
| 6 | 动态通道、参与者、线程和服务端授权 | ✅ 已完成 |
| 7 | 角色招募、热插拔和强制交接 | ✅ 已完成 |
| 8 | HumanGate、阻塞/建议性异议和仲裁 UI | ✅ 已完成 |
| 9 | 真正的并行工作器和协作式抢占 | ✅ 已完成 |
| 10 | 统一 Harness 代理、macOS 设置和启动、加固、最终基准测试和作品集演示 | ✅ 已完成 |
| 11–13 | Electron/工具链预览 → 受保护的原生执行预览 → 完整的原生工作流和 Docker 退役 | 已计划 |
| 14–20 | 项目/会话 → 招募 → 调度/预算 → 协作 → 附件/概览 → 恢复 → 编排 | 已计划 |
| 21–24 | 知识/图书管理员 → 知识有效性/复用 → 技能/MCP → 自定义角色 | 已计划 |
| 25–30 | 证据/地图 → 接口/报告 → 实验/撤回 → 增量验证 → 虚拟办公室 → 插件/完整验收 | 已计划 |
开发计划包含 20 个阶段（11–30）的 110 项计划任务，每个阶段有 3–7 项任务。所有 94 项原始任务均被保留，并新增了 16 个集成出口。每个阶段以集成测试和发布验收结束；下一阶段依赖于该出口。发布候选版本包括安装程序检查和证据；发布遵循人工审核的 dev-to-main PR 以及单独授权的 tag/GitHub Release。未解决的细节有对应的设计任务，功能到任务的映射保持了覆盖。当前状态和依赖关系仅存在于 docs/task-status.json 中；先运行 node scripts/task-status.mjs summary，然后根据需要查询 task  或 phase 。完整的执行证据保存在每个任务的历史文件中。规划并不声称某个功能已被实现或验收。

设计文档

- 项目蓝图 — 产品定位、架构、路线图和已批准决策
- 详细设计 — 状态模式、角色契约、编排、执行、投影和验证
- 系统架构 — 分层、依赖方向、一致性、韧性和部署
- 技术决策 — 锁定的技术栈、被否决的替代方案、沙箱、SSE 和持久化
- 开发计划 — 阶段 0–30 的任务分解、依赖关系、退出标准和未来功能覆盖
- 框架研究 — 带日期的 AutoGen/AgentScope 源码研究和产品对比证据

项目状态与范围

Agora 是一个面向 2027 届毕业生招聘季的个人作品集项目。它以小型、有证据支持的阶段进行开发：每个阶段必须产出可演示的成果，然后才能开始下一阶段。

当前产品面向可信的单用户本地运行。公开托管、云沙箱和多实例扩展不在当前范围内。未来对该范围的任何变更都需要单独的架构和安全审查。

欢迎反馈和架构讨论。自动 PR 合并有意不作为项目工作流的一部分：变更由人工审核和合并。