@chorus-aidlc/chorus

v0.6.8

Published

2 days ago

The Agent Harness for AI-Human Collaboration — session lifecycle, task state, sub-agent orchestration, observability, and failure recovery

Downloads

958

0High
0Medium
0Low

felix-chan

agent-harness ai-dlc mcp agent-orchestration session-lifecycle task-dag

Chorus 是一个 Agent Harness——包裹在 LLM 外面的基础设施层，负责管理会话生命周期、任务状态、子 Agent 编排、可观测性和故障恢复。它让多个 AI Agent（PM、Developer、Admin）和人类在同一平台上协作，完成从需求到交付的全流程。

受 AI-DLC（AI-Driven Development Lifecycle） 方法论启发。核心理念：Reversed Conversation——AI 提议，人类验证。

AI-DLC 工作流

Idea ──> Proposal ──> [Document + Task DAG] ──> Execute ──> Verify ──> Done
  ^          ^               ^                     ^          ^         ^
Human     PM Agent       PM Agent              Dev Agent    Admin     Admin
creates   analyzes       drafts PRD            codes &      reviews   closes
          & plans        & tasks               reports      & verifies

快速开始

两条命令在本地运行 Chorus——无需数据库、无需 Docker、无需配置文件。

npm install -g @chorus-aidlc/chorus
chorus

Chorus 会自动启动内嵌 PostgreSQL (PGlite)、执行数据库迁移，然后在 http://localhost:8637 提供服务。

提示： PGlite 是嵌入式单进程 PostgreSQL，本地单人使用完全没问题，但并发能力有限。如果需要多人或多 Agent 同时使用，建议通过 DATABASE_URL=postgresql://... 连接外部 PostgreSQL，或使用完整的 Docker Compose 部署。

默认登录账号：[email protected] / chorus

参数选项

# 自定义端口
chorus --port 3000

# 自定义数据目录（默认：~/.chorus-data）
chorus --data-dir /path/to/data

# 自定义登录账号
[email protected] DEFAULT_PASSWORD=secret chorus

# 使用外部 PostgreSQL（跳过内嵌 PGlite）
DATABASE_URL=postgresql://user:pass@host:5432/chorus chorus

其他部署方式

| 方式 | 命令 | |------|------| | npm（最简单） | npm i -g @chorus-aidlc/chorus && chorus | | Docker（单镜像） | docker compose -f docker-compose.local.yml up | | Docker（完整版） | docker compose up（PostgreSQL + Redis + Chorus） | | AWS CDK | 部署到 AWS |

界面预览

Proposal——AI Agent 实时生成计划

Proposal Presence

PM Agent 分析需求并实时生成包含 PRD 和任务 DAG 的提案，Presence 指示器实时显示 Agent 活动状态。

Pixel Workspace——Agent 实时工作状态

Pixel Workspace

左侧为像素工作室，用像素小人代表每个 Agent 的实时工作状态；右侧为 Agent 终端实时输出。

Kanban——任务状态实时流转

Kanban Presence

Kanban 看板随 Agent 工作进度自动更新，任务卡片在 To Do → In Progress → To Verify 之间实时流转。Presence 指示器高亮显示正在被操作的资源。

看板 & 任务 DAG

Kanban & Task DAG

看板追踪任务状态，DAG 展示依赖关系和并行路径，一目了然。

Idea & 需求细化

Idea & Elaboration

PM Agent 在创建 Proposal 前，通过结构化问答轮次澄清需求。面板展示 Idea 详情及已完成的细化轮次。

提案审阅

Proposal Review

PM Agent 生成的 Proposal 包含文档草稿和任务 DAG 草稿，Admin 在此面板审阅并决定批准或驳回。

验收标准——双路验证

Acceptance Criteria

Dev Agent 自检 + Admin 独立审核，每条验收标准都有结构化的通过/失败证据。

Universal Search——Cmd+K 全局搜索

Cmd+K 命令面板，支持跨 6 种实体类型搜索。支持范围筛选（全局/项目组/单项目）、按类型切换 Tab、键盘导航。Web UI 和 AI Agent（通过 chorus_search MCP 工具）共享同一搜索后端。

功能特性

会话生命周期 — 持久化 Session，心跳检测，自动过期与故障恢复
任务 DAG — 依赖建模、环检测、交互式可视化
Kanban — 实时任务流转，Worker 徽标与 Agent Presence
Multi-Agent 协作 — Claude Code Agent Teams (Swarm Mode) 并行执行
Chorus Plugin — 生命周期钩子自动管理 Session 创建/关闭、心跳、上下文注入
需求澄清 — Proposal 创建前的结构化问答轮次
Proposal 审批流 — PM 起草，Admin 审批，草稿物化为正式实体
通知系统 — 应用内 + SSE 推送 + Redis Pub/Sub，支持个人偏好设置（设计文档）
@Mention — Tiptap 自动补全、权限隔离搜索、mention 通知（设计文档）
活动流 — 全操作审计 + Session 归因
全局搜索 — Cmd+K 跨 6 种实体类型、3 级范围筛选、片段生成（设计文档）

架构

┌──────────────────────────────────────────────────────────────────┐
│                 Chorus — Agent Harness (:8637)                    │
│                                                                  │
│  ┌── Harness Capabilities ───────────────────────────────────┐   │
│  │  Session Lifecycle │ Task State Machine │ Context Inject   │   │
│  │  Sub-Agent Orchestration │ Observability │ Failure Recovery│   │
│  └───────────────────────────────────────────────────────────┘   │
│                                                                  │
│  ┌── Chorus Plugin (lifecycle hooks) ────────────────────────┐   │
│  │  SubagentStart/Stop │ Heartbeat │ Skill & Context Inject  │   │
│  └───────────────────────────────────────────────────────────┘   │
│                                                                  │
│  ┌── API Layer ──────────────────────────────────────────────┐   │
│  │  /api/mcp  — MCP HTTP Streamable (50+ tools, role-based)  │   │
│  │  /api/*    — REST API (Web UI + SSE push)                 │   │
│  └───────────────────────────────────────────────────────────┘   │
│                                                                  │
│  ┌── Service Layer ──────────────────────────────────────────┐   │
│  │  AI-DLC Workflow │ UUID-first │ Multi-tenant              │   │
│  └───────────────────────────────────────────────────────────┘   │
│                                                                  │
│  ┌── Web UI (React 19 + Tailwind + shadcn/ui) ──────────────┐   │
│  │  Kanban │ Task DAG │ Proposals │ Activity │ Sessions      │   │
│  └───────────────────────────────────────────────────────────┘   │
└──────────────────────────────────────────────────────────────────┘
     ↑              ↑              ↑              ↑
  PM Agent    Developer Agent  Admin Agent      Human
   (LLM)         (LLM)          (LLM)        (Browser)
                     │
          ┌──────────▼──────────┐   ┌─────────────────────┐
          │  PostgreSQL + Prisma │   │  Redis（可选）       │
          └─────────────────────┘   │  Pub/Sub 事件分发   │
                                    └─────────────────────┘

子包

| 包 | 说明 | |---|------| | packages/openclaw-plugin | OpenClaw 插件 — 通过 SSE 长连接 + MCP 工具桥接 OpenClaw 与 Chorus。 | | packages/chorus-cdk | AWS CDK — Chorus 的 AWS 基础设施即代码。 |

技术栈

| 组件 | 技术 | |------|------| | 框架 | Next.js 15 (App Router, Turbopack) | | 语言 | TypeScript 5 (strict mode) | | 前端 | React 19, Tailwind CSS 4, shadcn/ui (Radix UI) | | ORM | Prisma 7 | | 数据库 | PostgreSQL 16 | | 缓存/消息 | Redis 7 (ioredis) — 可选 | | Agent 集成 | MCP SDK 1.26 (HTTP Streamable Transport) | | 认证 | OIDC + PKCE / API Key / SuperAdmin | | i18n | next-intl (en, zh) | | 部署 | Docker Hub / Docker Compose / AWS CDK |

快速开始

Docker 一键启动（推荐）

无需构建工具或外部数据库。镜像内置 PGlite（嵌入式 PostgreSQL）：

git clone https://github.com/Chorus-AIDLC/chorus.git
cd chorus

[email protected] DEFAULT_PASSWORD=changeme \
  docker compose -f docker-compose.local.yml up -d

访问 http://localhost:8637，用上面设置的账号登录。

数据持久化在 Docker 卷中。嵌入模式仅支持单实例（无 Redis）。

生产部署（PostgreSQL + Redis）

多副本生产环境：

[email protected] DEFAULT_PASSWORD=changeme \
  docker compose up -d

完整环境变量和配置选项见 Docker 文档。

本地开发

前置条件：Node.js 22+、pnpm 9+、Docker（用于 PostgreSQL/Redis）

cp .env.example .env
pnpm docker:db
pnpm install
pnpm db:migrate:dev
pnpm dev
# 访问 http://localhost:8637

本地开发（无需 Docker）

前置条件：Node.js 22+、pnpm 9+

cp .env.example .env
pnpm install
pnpm dev:local        # 开发服务器 http://localhost:8637

PGlite 在端口 5433 运行嵌入式 PostgreSQL。数据存储在 .pglite/，删除即可重置。

部署到 AWS

./install.sh

交互式安装器自动创建 VPC、Aurora Serverless v2、ElastiCache Serverless、ECS Fargate 和 ALB（HTTPS）。配置保存到 default_deploy.sh 供后续重新部署。

连接 AI Agent

最快的方式是用应用内的 setup 向导：打开 Web UI，进入 Settings → Setup Guide → 打开设置向导，按照向导给出的分步指引接入自己的客户端（Claude Code、Codex、OpenClaw 或其他 agent）。向导会帮你创建 API Key、展示完整命令，并引导你验证连接。

如果偏好文档：

| 客户端 | 接入文档 | |--------|---------| | Claude Code | CONNECT_CLAUDE_CODE.zh.md | | Codex CLI | CONNECT_CODEX.zh.md | | 其他 MCP agent（Cursor / Continue / 自研等） | CONNECT_OTHER_AGENTS.zh.md |

在 Web UI 的 Settings → Agents → Create API Key 创建 API Key。Key 以 cho_ 开头，仅在创建时显示一次。

Create API Key

Skill 文档

| 方式 | 位置 | 适用场景 | |------|------|---------| | Plugin 内嵌 | public/chorus-plugin/skills/chorus/ | Claude Code + Plugin，Session 自动化 | | 独立分发 | public/skill/（/skill/ 路径静态托管）| 任何 Agent，手动 Session 管理 |

文档

| 文档 | 说明 | |------|------| | PRD | 产品需求文档 | | Architecture | 技术架构文档 | | MCP Tools | MCP 工具参考 | | Chorus Plugin | 插件设计与 Hook 说明 | | Search | 全局搜索技术设计 | | AI-DLC Gap Analysis | AI-DLC 方法论差距分析 | | AIG Implementation Plan | Agent 透明度路线图 | | Presence Design | 实时 Agent Presence 系统 | | Docker | Docker 镜像使用与部署 | | Logging | 结构化日志架构 | | CLAUDE.md | 项目开发规范 |

License

AGPL-3.0 — see LICENSE.txt

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

AI-DLC 工作流

最近更新

快速开始

参数选项

其他部署方式

界面预览

Proposal——AI Agent 实时生成计划

Pixel Workspace——Agent 实时工作状态

Kanban——任务状态实时流转

看板 & 任务 DAG

Idea & 需求细化

提案审阅

验收标准——双路验证

Universal Search——Cmd+K 全局搜索

功能特性

架构

子包

技术栈

快速开始

Docker 一键启动（推荐）

生产部署（PostgreSQL + Redis）

本地开发

本地开发（无需 Docker）

部署到 AWS

连接 AI Agent

Skill 文档

文档

License