<p align="center">
  <img src="docs/images/chorus-slug.png" alt="Chorus" width="240" />
</p>

<p align="center"><strong>面向 AI 与人类协作的 Agent Harness</strong></p>

<p align="center"><a href="README.md">English</a></p>

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

受 **[AI-DLC（AI-Driven Development Lifecycle）](https://aws.amazon.com/blogs/devops/ai-driven-development-life-cycle/)** 方法论启发。核心理念：**Reversed Conversation**——AI 提议，人类验证。

---

## AI-DLC 工作流

```
Idea ──> Proposal ──> [Document + Task DAG] ──> Execute ──> Verify ──> Done
  ^          ^               ^                     ^          ^         ^
人类      idea:write     proposal:write         task:write   *:admin    *:admin
提出      + 需求澄清     + 起草 PRD/任务         + 报告进度   + 验收     + 关闭
```

每个阶段下方标的是「执行该阶段所需的权限」，可以由人类、Agent（预设或 Custom）或两者持有。没有固定角色，5 × 3 权限矩阵的任意组合都合法，详见 [`docs/PERMISSIONS.md`](docs/PERMISSIONS.md)（英文）。

---

## 最近更新

**[v0.9.0](https://chorus-ai.dev/zh/blog/chorus-v0.9.0-release/)** — 头脑风暴 skill 帮你把模糊的想法聊出形状（在结构化多选题前先开放式对话），想法落地后自动生成总结报告（Summary / Decisions / Follow-ups 三段式，挂在想法概览页）。

**[v0.8.0](https://chorus-ai.dev/zh/blog/chorus-v0.8.0-release/)** — OpenSpec-aware 模式（仅 Claude Code）：当仓库下同时存在 `openspec/` 目录和 `openspec` CLI 时自动启用，新增 `/opsx/{explore,propose,apply,archive}` 与 task verify 后的 archive-trigger 钩子。

**[v0.7.0](https://chorus-ai.dev/zh/blog/chorus-v0.7.0-release/)** — 细粒度 Agent 权限：5 类资源 × 3 个动作组成的网格，取代 PM / Developer / Admin 三选一。保留原有预设，新增 Custom 选项自由组合。

**[v0.6.7](https://chorus-ai.dev/zh/blog/chorus-v0.6.7-release/)** — Codex CLI 版 Chorus 插件（一条命令装完）、同一邮箱属于多个 Company 时的工作区选择器、每种客户端的接入文档。

**[v0.6.6](https://chorus-ai.dev/zh/blog/chorus-v0.6.6-release/)** — npm 一键安装（`npx @chorus-aidlc/chorus`）、文档导出（MD/PDF/Word）、Proposal 撤回、优化 Agent Checkin 快速获取工作状态。

**[v0.6.2](https://chorus-ai.dev/zh/blog/chorus-v0.6.2-release/)** — 嵌入式 PGlite 模式（零依赖部署）、Pino 结构化日志、无状态 MCP 支持水平扩展、默认端口改为 8637。

**[v0.6.1](https://chorus-ai.dev/zh/blog/chorus-v0.6.1-release/)** — `/yolo` 技能：全自动 AI-DLC 流水线（Idea → Proposal → Execute → Verify），支持 Agent Team 并行执行。

**[v0.6.0](https://chorus-ai.dev/zh/blog/chorus-v0.6.0-release/)** — IdeaTracker 面板、独立审阅 Agent（proposal-reviewer + task-reviewer）、实时 Agent Presence 指示器、跨列 Kanban 动画。

> 完整更新日志：[CHANGELOG.md](CHANGELOG.md)

---

## 快速开始

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

```bash
npm install -g @chorus-aidlc/chorus
chorus
```

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

> **提示：** PGlite 是嵌入式单进程 PostgreSQL，本地单人使用完全没问题，但并发能力有限。如果需要多人或多 Agent 同时使用，建议通过 `DATABASE_URL=postgresql://...` 连接外部 PostgreSQL，或使用完整的 [Docker Compose](#docker-一键启动推荐) 部署。

默认登录账号：`admin@chorus.local` / `chorus`

### 参数选项

```bash
# 自定义端口
chorus --port 3000

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

# 自定义登录账号
DEFAULT_USER=me@example.com 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（完整版）** | [`docker compose up`](#docker-一键启动推荐)（PostgreSQL + Redis + Chorus） |
| **AWS CDK** | [部署到 AWS](#部署到-aws) |

---

## 界面预览

### Proposal——AI Agent 实时生成计划

![Proposal Presence](docs/images/proposal-presence.gif)

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

### Pixel Workspace——Agent 实时工作状态

![Pixel Workspace](docs/images/pixcel-workspace-new.gif)

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

### Kanban——任务状态实时流转

![Kanban Presence](docs/images/kanban-presence.gif)

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

### 看板 & 任务 DAG

![Kanban & Task DAG](docs/images/kanan-dag.png)

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

### Idea & 需求细化

![Idea & Elaboration](docs/images/idea-elaborate.png)

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

### 提案审阅

![Proposal Review](docs/images/proposal.png)

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

### 验收标准——双路验证

![Acceptance Criteria](docs/images/task-ac.png)

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

### Universal Search——Cmd+K 全局搜索

![Universal Search](docs/images/universal-search.png)

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) 并行执行
- **细粒度 Agent 权限** — 5 类资源 × 3 个动作组成的权限网格，支持预设 + 自定义组合（[详细说明](docs/PERMISSIONS.md) · 英文）
- **Chorus Plugin** — 生命周期钩子自动管理 Session 创建/关闭、心跳、上下文注入
- **需求澄清** — Proposal 创建前的结构化问答轮次
- **Proposal 审批流** — PM 起草，Admin 审批，草稿物化为正式实体
- **通知系统** — 应用内 + SSE 推送 + Redis Pub/Sub，支持个人偏好设置（[设计文档](src/app/api/notifications/README.md)）
- **@Mention** — Tiptap 自动补全、权限隔离搜索、mention 通知（[设计文档](src/app/api/mentionables/README.md)）
- **活动流** — 全操作审计 + Session 归因
- **全局搜索** — Cmd+K 跨 6 种实体类型、3 级范围筛选、片段生成（[设计文档](docs/SEARCH.md)）
---

## 架构

```
┌──────────────────────────────────────────────────────────────────┐
│                 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 Streaming (50+ tools, permission-gated)  │   │
│  │  /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      │   │
│  └───────────────────────────────────────────────────────────┘   │
└──────────────────────────────────────────────────────────────────┘
     ↑              ↑              ↑              ↑
  Agent w/      Agent w/       Agent w/         人类
  idea+proposal  task:write    *:admin perms   （浏览器）
   :write perms    perms      （代理人类审批）
   (LLM)          (LLM)         (LLM)
                     │
          ┌──────────▼──────────┐   ┌─────────────────────┐
          │  PostgreSQL + Prisma │   │  Redis（可选）       │
          └─────────────────────┘   │  Pub/Sub 事件分发   │
                                    └─────────────────────┘
```

### 子包

| 包 | 说明 |
|---|------|
| [`packages/openclaw-plugin`](packages/openclaw-plugin) | **OpenClaw 插件** — 通过 SSE 长连接 + MCP 工具桥接 [OpenClaw](https://openclaw.ai) 与 Chorus。 |
| [`packages/chorus-cdk`](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](https://hub.docker.com/repository/docker/chorusaidlc/chorus-app/general) / Docker Compose / AWS CDK |

---

## 快速开始

### Docker 一键启动（推荐）

无需构建工具或外部数据库。镜像内置 [PGlite](https://pglite.dev)（嵌入式 PostgreSQL）：

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

DEFAULT_USER=admin@example.com DEFAULT_PASSWORD=changeme \
  docker compose -f docker-compose.local.yml up -d
```

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

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

#### 生产部署（PostgreSQL + Redis）

多副本生产环境：

```bash
DEFAULT_USER=admin@example.com DEFAULT_PASSWORD=changeme \
  docker compose up -d
```

> 完整环境变量和配置选项见 [Docker 文档](docs/DOCKER.md)。

---

### 本地开发

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

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

### 本地开发（无需 Docker）

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

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

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

### 部署到 AWS

```bash
./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、OpenCode、OpenClaw 或其他 agent）。向导会帮你创建 API Key、展示完整命令，并引导你验证连接。

如果偏好文档：

| 客户端 | 接入文档 |
|--------|---------|
| Claude Code | [CONNECT_CLAUDE_CODE.zh.md](docs/CONNECT_CLAUDE_CODE.zh.md) |
| Codex CLI | [CONNECT_CODEX.zh.md](docs/CONNECT_CODEX.zh.md) |
| OpenCode † | [CONNECT_OPENCODE.zh.md](docs/CONNECT_OPENCODE.zh.md) |
| 其他 MCP agent（Cursor / Continue / 自研等） | [CONNECT_OTHER_AGENTS.zh.md](docs/CONNECT_OTHER_AGENTS.zh.md) |

† OpenCode 的接入由社区维护的 [`opencode-chorus`](https://github.com/etnperlong/opencode-chorus) 插件提供（npm: [`opencode-chorus`](https://www.npmjs.com/package/opencode-chorus)），作者 [@etnperlong](https://github.com/etnperlong)，特此感谢！

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

![Create API Key](docs/images/create-key.png)

---

## Skill 文档

| 方式 | 位置 | 适用场景 |
|------|------|---------|
| **Plugin 内嵌（Claude Code）** | `public/chorus-plugin/skills/` | Claude Code + Chorus 插件，Session 自动化与生命周期 hook |
| **Plugin 内嵌（Codex CLI）** | `plugins/chorus/skills/` | Codex CLI + Chorus 插件，移植版技能（`$` 前缀斜杠命令）|
| **独立分发** | `public/skill/`（`/skill/` 路径静态托管）| 其他 MCP 客户端（Cursor / Continue / 自研），手动 Session 管理 |

---

## 文档

| 文档 | 说明 |
|------|------|
| [PRD](docs/PRD_Chorus.md) | 产品需求文档 |
| [Architecture](docs/ARCHITECTURE.md) | 技术架构文档 |
| [MCP Tools](docs/MCP_TOOLS.md) | MCP 工具参考 |
| [Permissions](docs/PERMISSIONS.md) | Agent 权限模型（5 × 3 矩阵 + 预设 + Custom） |
| [Chorus Plugin](docs/chorus-plugin.md) | 插件设计与 Hook 说明 |
| [OpenSpec Mode](docs/OPENSPEC_MODE.md) | OpenSpec 模式（Plugin 0.8.1+，opt-in） |
| [Search](docs/SEARCH.md) | 全局搜索技术设计 |
| [AI-DLC Gap Analysis](docs/AIDLC_GAP_ANALYSIS.md) | AI-DLC 方法论差距分析 |
| [AIG Implementation Plan](docs/CHORUS_AIG_PLAN.md) | Agent 透明度路线图 |
| [Presence Design](docs/PRESENCE_DESIGN.md) | 实时 Agent Presence 系统 |
| [Docker](docs/DOCKER.md) | Docker 镜像使用与部署 |
| [Logging](docs/LOGGING.md) | 结构化日志架构 |
| [CLAUDE.md](CLAUDE.md) | 项目开发规范 |

---

## License

AGPL-3.0 — see [LICENSE.txt](LICENSE.txt)
