@chorus-aidlc/chorus 0.16.1 → 0.16.2

package/README.zh.md

@@ -2,15 +2,15 @@
   <img src="packages/landing/public/images/chorus-slug.png" alt="Chorus" width="240" />
 </p>
 
-<p align="center"><strong>面向 AI 与人类协作的 Agent Harness</strong></p>
+<p align="center"><strong>你的编程 Agent 之上的 Harness：Agent 提议，人类把关，软件交付。</strong></p>
 
 <p align="center"><a href="README.md">English</a> · <strong>中文</strong> · <a href="README.ko.md">한국어</a> · <a href="README.ja.md">日本語</a></p>
 
-<p align="center"><a href="https://doc.chorus-ai.dev"><strong>📖 文档</strong></a></p>
+<p align="center"><a href="https://doc.chorus-ai.dev/zh/"><strong>📖 文档</strong></a></p>
 
-Chorus 是一个 Agent Harness——包裹在 LLM 外面的基础设施层，负责管理会话生命周期、任务状态、子 Agent 编排、可观测性和故障恢复。它让多个具备细粒度权限配置的 AI Agent 和人类在同一平台上协作，完成从需求到交付的全流程。
+Chorus 是你的编程 Agent 之上的 Harness。编程 Agent 是把模型 harness 起来写代码的那层；Chorus 高它们一层，把多个这样的 Agent 和你收进同一条流水线：Agent 提议，你来验收，想法最终交付成软件，而不只是写代码。在底层，它把这套多 Agent、真人把关的协作稳稳跑起来所需的一切都处理好：会话生命周期、任务状态、子 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（AI-Driven Development Lifecycle）](https://aws.amazon.com/blogs/devops/ai-driven-development-life-cycle/)** 方法论启发。核心理念：**Reversed Conversation**：AI 提议，人类验证。
 
 ---
 
@@ -23,7 +23,7 @@ Idea ──> Proposal ──> [Document + Task DAG] ──> Execute ──> Veri
 提出      + 需求澄清     + 起草 PRD/任务         + 报告进度   + 验收     + 关闭
 ```
 
-每个阶段下方标的是「执行该阶段所需的权限」，可以由人类、Agent（预设或 Custom）或两者持有。没有固定角色，5 × 3 权限矩阵的任意组合都合法，详见 [`docs/PERMISSIONS.md`](docs/PERMISSIONS.md)（英文）。
+每个阶段下方标的是「执行该阶段所需的权限」，可以授予人类、Agent 或两者。没有固定角色，5 × 3 权限矩阵的任意组合都合法。→ [Agent 权限](https://doc.chorus-ai.dev/zh/guides/manage-agents/)
 
 ---
 
@@ -45,248 +45,58 @@ Idea ──> Proposal ──> [Document + Task DAG] ──> Execute ──> Veri
 
 ## 快速开始
 
-两条命令在本地运行 Chorus——无需数据库、无需 Docker、无需配置文件。
+两条命令即可，无需数据库、无需 Docker、无需配置文件。
 
 ```bash
 npm install -g @chorus-aidlc/chorus
 chorus
 ```
 
-Chorus 会自动启动内嵌 PostgreSQL (PGlite)、执行数据库迁移，然后在 **http://localhost:8637** 提供服务。
+Chorus 会自动启动内嵌 PostgreSQL (PGlite)、执行数据库迁移，然后在 **http://localhost:8637** 提供服务。默认登录账号：`admin@chorus.local` / `chorus`。
 
-> **提示：** PGlite 是嵌入式单进程 PostgreSQL，本地单人使用完全没问题，但并发能力有限。如果需要多人或多 Agent 同时使用，建议通过 `DATABASE_URL=postgresql://...` 连接外部 PostgreSQL，或使用完整的 [Docker Compose](#docker-一键启动推荐) 部署。
+> 需要运行多个 agent，或部署到生产环境？可使用外部 PostgreSQL、Docker 或 AWS → **[部署与自托管](https://doc.chorus-ai.dev/zh/guides/deployment-overview/)**。
 
-默认登录账号：`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) |
-
-### `chorus daemon` — 作为 Agent 运行时连接
-
-`chorus daemon` 将你的本地机器作为 Agent 运行时连接到远程 Chorus 服务器并执行 Chorus 分配的任务。
-
-> **Agent 后端：** 支持 **Claude Code**（默认）和 **Codex**，用 `--agent codex`（或 `CHORUS_AGENT=codex`）切换。对其他 Agent CLI（Copilot 等）的支持计划在未来版本中实现。
-
-```bash
-chorus login                     # 认证（打开浏览器）
-chorus daemon                    # 前台启动 daemon
-chorus daemon -d                 # 后台启动 daemon（分离模式）
-chorus daemon install            # 安装为开机自启服务（Linux）—— 推荐
-chorus daemon uninstall          # 卸载已安装的服务
-chorus daemon stop               # 停止 daemon（已安装服务时委派给 systemd）
-chorus daemon stop --force       # pid 卡死时强制清理 pidfile
-chorus daemon status             # 查看 daemon 状态
-chorus daemon restart            # 重启 daemon
-chorus daemon logs               # 查看 daemon 日志
-```
-
-**主要特性：**
-
-- **Claude Code 与 Codex 后端** — 自动检测 PATH 中的 `claude`（或 `codex`）CLI；用 `--agent codex` 选择
-- **后台模式** — 使用 `-d` 标志后台运行；用 `stop/restart/logs` 管理
-- **开机自启服务** — `chorus daemon install` 生成正确的 `systemd --user` unit 并启动（见下文）；此后 `status/stop/restart/logs` 会自动委派给 systemd
-- **权限模式** — 默认完全访问（yolo）；使用 `--chorus-only` 限制为仅 Chorus MCP 工具
-- **多路径** — 用可重复的 `--cwd` 让单个 daemon 同时服务多个工作目录（见下文）
-- **交互式设置** — 首次启动时如未配置凭证会提示输入
-
-daemon 需要先认证。首次使用请先运行 `chorus login`，或者 daemon 会在首次启动时交互式提示输入凭证（如果在终端中运行）。
-
-#### 开机 / 登录时自启 —— `chorus daemon install`
-
-```bash
-chorus daemon install --cwd ~/work/repo-a --cwd ~/work/repo-b   # 立即安装并启动，登录时自启
-chorus daemon uninstall                                         # 停用并移除该服务
-```
-
-在 Linux 上，`install` 会生成一个 `systemd --user` unit，让 daemon 以**前台**方式运行（`Type=simple`，不带 `-d`），从而由 systemd 直接接管进程，然后 `daemon-reload` + `enable --now`。它会捕获你传入的 `--cwd`/`--agent`/`--chorus-only` 参数。**不要**手写 `Type=forking` + `chorus daemon -d` 的 unit —— daemon 会自我 daemon 化，systemd 追踪不到，重启时会陷入死循环；交给 `install` 写正确的 unit。在 macOS/Windows 上，`install` 会打印一份可手动安装的正确模板。请先运行 `chorus login`，让 unit 能读到凭证。详见 [docs/DAEMON.md](docs/DAEMON.md)。
-
-#### 服务多个工作目录
-
-一个 daemon 可以同时服务多个本地工作目录——每个声明的路径会注册为一条独立连接（各自拥有会话与唤起循环），归属同一个 Agent。路径**仅仅**是 daemon 服务的目录，不携带任何项目绑定。
-
-```bash
-chorus daemon --cwd ~/work/repo-a --cwd ~/work/repo-b   # 可重复传入
-CHORUS_DAEMON_CWDS="~/work/repo-a:~/work/repo-b" chorus daemon   # 或用环境变量（`:` 或 `,` 分隔）
-```
-
-不传 `--cwd` 时，daemon 只服务它的启动目录这一个路径。
-
-#### 配置文件 —— `~/.chorus/daemon.json`
-
-`chorus login` 会把凭证写入此文件（权限 `0600`）。你也可以把 daemon 的调优项写进**同一个**文件。所有字段都是可选的；命令行参数和环境变量的优先级始终高于文件。
-
-```json
-{
-  "url": "https://chorus.example.com",
-  "apiKey": "cho_xxxxxxxxxxxxxxxxxxxxxxxx",
-  "agentUuid": "00000000-0000-0000-0000-000000000000",
-  "agentName": "My Daemon Agent",
-  "cwds": ["~/work/repo-a", "~/work/repo-b"],
-  "sigintTimeoutMs": 10000
-}
-```
-
-| 字段 | 类型 | 写入方 / 用途 | 优先级（从高到低） |
-|------|------|---------------|--------------------|
-| `url` | string | 远程 Chorus 服务器 URL | `--url` 参数 → `CHORUS_URL` → 文件 |
-| `apiKey` | string | Agent API Key（`cho_…`） | `--api-key` 参数 → `CHORUS_API_KEY` → 文件 |
-| `agentUuid` / `agentName` | string | 认证身份（登录时记录） | 由 `chorus login` 写入 |
-| `cwds` | string[] | daemon 服务的工作目录（多路径） | `--cwd` 参数 → `CHORUS_DAEMON_CWDS` → 文件 → 启动目录 |
-| `sigintTimeoutMs` | number | SIGINT 后强制结束前的宽限窗口（毫秒，默认 `10000`） | `--sigint-timeout` 参数 → `CHORUS_DAEMON_SIGINT_TIMEOUT` → 文件 → `10000` |
-| `yoloAckAt` | string | 内部字段——TTY 下 yolo 确认的时间戳（自动管理） | — |
-
-daemon 启动时的横幅会打印它**实际读取的 `daemon.json` 路径**（以及该文件是否存在），让你随时清楚该编辑哪个文件。
+想把本地机器变成领取任务的 agent 运行时，运行 `chorus daemon` → **[Daemon 运维](https://doc.chorus-ai.dev/zh/guides/daemon-operations/)** · **[远程控制](https://doc.chorus-ai.dev/zh/guides/remote-control/)**。
 
 ---
 
 ## 界面预览
 
-### 远程唤醒 Agent——派活到指定目录，实时看它跑
+### 远程唤醒 Agent：派活到指定目录，实时看它跑
 
 ![远程唤醒 Agent](packages/landing/public/images/agent-daemon-wake.gif)
 
 把一条想法派给远程 Agent 的某个目录，打开对话窗口，就能实时看到本地的 Claude Code 接活、开跑，全程不用碰终端，也不用手动 resume。
 
-### 项目资源图谱——整个项目一张实时思维导图
+### 项目资源图谱：整个项目一张实时思维导图
 
 ![项目资源图谱](packages/landing/public/images/mind-map.png)
 
-Chorus 自动把整个项目整理成一张思维导图——想法、提案、文档、任务连成一棵树，还能实时反映 Agent 的动作，每张卡片的状态随着工作推进自动更新。
+想法、提案、文档、任务连成一棵树，每张卡片的状态随着 Agent 工作实时更新。
 
-### Proposal——AI Agent 实时生成计划
+### Proposal：AI Agent 实时生成计划
 
 ![Proposal Presence](packages/landing/public/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：任务状态实时流转
 
 ![Kanban Presence](packages/landing/public/images/kanban-presence.gif)
 
 Kanban 看板随 Agent 工作进度自动更新，任务卡片在 To Do → In Progress → To Verify 之间实时流转。Presence 指示器高亮显示正在被操作的资源。
 
-### 看板 & 任务 DAG
-
-![Kanban & Task DAG](packages/landing/public/images/kanban-dag.png)
-
-看板追踪任务状态，DAG 展示依赖关系和并行路径，一目了然。
-
-### Idea & 需求细化
-
-![Idea & Elaboration](packages/landing/public/images/idea-elaborate.png)
-
-PM Agent 在创建 Proposal 前，通过结构化问答轮次澄清需求。面板展示 Idea 详情及已完成的细化轮次。
-
-### 提案审阅
-
-![Proposal Review](packages/landing/public/images/proposal.png)
-
-PM Agent 生成的 Proposal 包含文档草稿和任务 DAG 草稿，Admin 在此面板审阅并决定批准或驳回。
-
-### 验收标准——双路验证
-
-![Acceptance Criteria](packages/landing/public/images/task-ac.png)
-
-Dev Agent 自检 + Admin 独立审核，每条验收标准都有结构化的通过/失败证据。
-
-### Universal Search——Cmd+K 全局搜索
-
-![Universal Search](packages/landing/public/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)）
----
+## 连接 Agent
 
-## 架构
+最快的方式是应用内的 setup 向导：打开 **Settings → Setup Guide**。它会创建 API Key，并给出适配你所用客户端的完整命令，无论是 Claude Code、Codex、Kiro、OpenCode、OpenClaw、Pi，还是任何兼容 MCP 的 agent。
 
-```
-┌──────────────────────────────────────────────────────────────────┐
-│                 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 事件分发   │
-                                    └─────────────────────┘
-```
+按客户端分的完整接入指南 → **[Agent 接入平台](https://doc.chorus-ai.dev/zh/reference/agents/)**。
 
-### 子包
+在 **Settings → Agents → Create API Key** 创建 API Key。Key 以 `cho_` 开头，仅在创建时显示一次。
 
-| 包 | 说明 |
-|---|------|
-| [`packages/openclaw-plugin`](packages/openclaw-plugin) | **OpenClaw 插件** — 通过 SSE 长连接 + MCP 工具桥接 [OpenClaw](https://openclaw.ai) 与 Chorus。 |
-| [`packages/chorus-cdk`](packages/chorus-cdk) | **AWS CDK** — Chorus 的 AWS 基础设施即代码。 |
+---
 
 ## 技术栈
 
@@ -294,132 +104,25 @@ Cmd+K 命令面板，支持跨 6 种实体类型搜索。支持范围筛选（
 |------|------|
 | 框架 | 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) |
+| 前端 | React 19, Tailwind CSS 4, shadcn/ui |
+| 数据 | PostgreSQL 16 + Prisma 7, Redis 7（可选） |
+| Agent 集成 | MCP SDK (HTTP Streamable Transport) |
 | 认证 | OIDC + PKCE / API Key / SuperAdmin |
 | i18n | next-intl (en, zh, ko, ja) |
-| 部署 | [Docker Hub](https://hub.docker.com/r/chorusaidlc/chorus-app) / 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、Kiro、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) |
-| Pi coding agent | [CONNECT_PI.md](docs/CONNECT_PI.md) |
-| Kiro CLI | [CONNECT_KIRO.md](docs/CONNECT_KIRO.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](packages/landing/public/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 插件，移植版技能（`$` 前缀斜杠命令）|
-| **Package 内嵌（Pi）** | `packages/chorus-pi/skills/` | Pi + Chorus package，Session 自动化与生命周期 hook |
-| **独立分发** | `public/skill/`（`/skill/` 路径静态托管）| 其他 MCP 客户端（Cursor / Continue / 自研），手动 Session 管理 |
+| 部署 | npm / Docker / AWS CDK |
 
 ---
 
 ## 文档
 
-| 文档 | 说明 |
-|------|------|
-| [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) | 项目开发规范 |
+**📖 完整文档：[doc.chorus-ai.dev](https://doc.chorus-ai.dev/zh/)**
+
+- [快速上手](https://doc.chorus-ai.dev/zh/guides/getting-started/)
+- [连接 agent](https://doc.chorus-ai.dev/zh/reference/agents/)
+- [AI-DLC 工作流](https://doc.chorus-ai.dev/zh/guides/ai-dlc-workflow/)
+- [插件与命令](https://doc.chorus-ai.dev/zh/guides/plugin-commands/)
+- [MCP 工具参考](https://doc.chorus-ai.dev/zh/reference/mcp-tools/)
+- [部署与自托管](https://doc.chorus-ai.dev/zh/guides/deployment-overview/)
 
 ---
 

package/cli/control-handler.mjs

@@ -38,7 +38,8 @@ const NOOP_LOGGER = { info() {}, warn() {}, error() {} };
  *                                            (null until the SSE handshake reports it).
  *   killer?: (child: any, opts: any) => Promise<any>,  Injectable; defaults to killProcessTree.
  *   sigintTimeoutMs?: number,                           Layered-resolved escalation window.
- *   redispatchResume?: (entityType: string, entityUuid: string, resumeReason?: string) => void,
+ *   redispatchResume?: (entityType: string, entityUuid: string, resumeReason?: string,
+ *                       runtimeCwd?: string, orchestrator?: object|null) => void,
  *                                            Re-run a wake for a resumed entity (子3); injected
  *                                            by the daemon. `resumeReason` ("user" | "crash",
  *                                            add-crash-execution-resume) is the row's prior
@@ -180,8 +181,17 @@ export function createControlHandler(deps) {
             `)`
         );
         try {
-          if (typeof event.runtimeCwd === "string" && event.runtimeCwd) {
-            redispatchResume?.(entityType, entityUuid, resumeReason, event.runtimeCwd);
+          if (
+            (typeof event.runtimeCwd === "string" && event.runtimeCwd) ||
+            event.orchestrator != null
+          ) {
+            redispatchResume?.(
+              entityType,
+              entityUuid,
+              resumeReason,
+              typeof event.runtimeCwd === "string" ? event.runtimeCwd : undefined,
+              event.orchestrator ?? null,
+            );
           } else {
             redispatchResume?.(entityType, entityUuid, resumeReason);
           }

package/cli/daemon-rest-client.mjs

@@ -7,7 +7,8 @@
 // The five operations and their EXACT server payload shapes (verified against
 // src/app/api/daemon/*/route.ts — the server is NOT changed by this work):
 //   turnAdvance      → POST /api/daemon/turn-advance
-//                      { connectionUuid, sessionId, status, entityType?, entityUuid? }
+//                      { connectionUuid, sessionId, status, entityType?, entityUuid?,
+//                        coalescedCount? }
 //   transcript       → POST /api/daemon/transcript
 //                      { sessionId, messages: [{ role, text }] }
 //   executionState   → POST /api/daemon/execution-state
@@ -70,7 +71,7 @@ const NOOP_LOGGER = { info() {}, warn() {}, error() {} };
  *   logger?: { info(m:string):void, warn(m:string):void, error(m:string):void },
  * }} opts
  * @returns {{
- *   turnAdvance: (p: { sessionId: string, backendSessionId?: string|null, status: string, entityType?: string|null, entityUuid?: string|null }) => Promise<DaemonRestResult>,
+ *   turnAdvance: (p: { sessionId: string, backendSessionId?: string|null, status: string, entityType?: string|null, entityUuid?: string|null, coalescedCount?: number }) => Promise<DaemonRestResult>,
  *   transcript: (p: { sessionId: string, messages: Array<{ role: string, text: string }> }) => Promise<DaemonRestResult>,
  *   executionState: (p: { executions: Array<Record<string, unknown>> }) => Promise<DaemonRestResult>,
  *   reportInterrupt: (p: { entityType: string, entityUuid: string, reason: string }) => Promise<DaemonRestResult>,
@@ -147,7 +148,7 @@ export function createDaemonRestClient(opts) {
      * the turn's usage. Both ride the terminal edge only. Requires the connectionUuid (the
      * server addresses the turn against a connection the agent owns).
      */
-    async turnAdvance({ sessionId, status, entityType, entityUuid, interruptedReason, transcriptRelayError, usage, backendSessionId }) {
+    async turnAdvance({ sessionId, status, entityType, entityUuid, interruptedReason, transcriptRelayError, usage, backendSessionId, coalescedCount }) {
       const connectionUuid = getConnectionUuid();
       if (!connectionUuid) {
         const error = `cannot advance turn for session ${sessionId} → ${status} — no connection uuid yet`;
@@ -173,6 +174,13 @@ export function createDaemonRestClient(opts) {
         // The whole normalized TokenUsage object, nested under `usage`, only on a terminal edge.
         ...(usage && isTerminal ? { usage } : {}),
         ...(backendSessionId && isTerminal ? { backendSessionId } : {}),
+        // Coalesced-wake count (add-daemon-wake-coalescing): meaningful ONLY on the → running
+        // edge, where the server settles the next (count − 1) same-session pending turns to
+        // `merged`. Sent only when a real batch coalesced (> 1); a single wake (default 1)
+        // omits it so the wire — and every existing turn-advance test — stays byte-identical.
+        ...(status === "running" && typeof coalescedCount === "number" && coalescedCount > 1
+          ? { coalescedCount }
+          : {}),
       };
       return post(
         "turn-advance",

package/cli/daemon.mjs

@@ -8,6 +8,12 @@
 // so a human can `claude --resume <idea-uuid>`); new-vs-resume is decided by
 // probing the on-disk transcript — there is no persisted session-id map.
 //
+// Wake coalescing (add-daemon-wake-coalescing): the WakeQueue is PER-CONNECTION
+// and serializes per DIRECT idea (= per session). Wakes that pile up on the same
+// key while a turn runs are drained together and delivered as ONE batch — a
+// single runBatch → waker.wakeBatch → one `claude --resume` turn — so N
+// same-session queued wakes coalesce into one turn, never N sequential turns.
+//
 // Connection / session / transcript reporting to the server is intentionally
 // NOT done here — the no-op UploadHooks reserve those seams for the derived
 // observability idea.
@@ -147,10 +153,7 @@ export function buildDaemon(creds, deps = {}) {
   // passed through so the Codex backend can export the daemon key into the woken
   // process env (the Claude backend ignores creds — it gets its key via --mcp-config).
   const spawner = deps.spawner ?? selectSpawner(agentType, { logger, permissionMode, creds });
-  // The WakeQueue serializes per DIRECT idea (keyFor's key). It is shared across all
-  // path-connections: serialization-per-idea still holds, and maxConcurrency caps the
-  // whole process's in-flight wakes rather than per-cwd — the right global budget.
-  const queue = new WakeQueue({ maxConcurrency: deps.maxConcurrency ?? 4, logger });
+  const maxConcurrency = deps.maxConcurrency ?? 4;
 
   // ===== Multi-path: the SET of cwds this daemon serves (T3 — FR-5) =====
   // Each declared path becomes one INDEPENDENT connection (own SSE self-report + own
@@ -338,6 +341,11 @@ export function buildDaemon(creds, deps = {}) {
         selectWaker(notification).markQueued(notification, key, attribution),
       wake: (notification, key, attribution) =>
         selectWaker(notification).wake(notification, key, attribution),
+      // Coalesced batch (add-daemon-wake-coalescing): every item shares the key → the same
+      // session → the same cwd (a session's cwd is pinned), so route the whole batch to the
+      // waker selected by the first item's runtimeCwd.
+      wakeBatch: (notifications, key, attribution) =>
+        selectWaker(notifications[0]).wakeBatch(notifications, key, attribution),
       markInterrupting(entityType, entityUuid) {
         for (const candidate of runtimeWakers.values()) {
           if (candidate.executions.has(`${entityType}:${entityUuid}`)) {
@@ -351,6 +359,19 @@ export function buildDaemon(creds, deps = {}) {
       buildExecutionSnapshot: () =>
         [...runtimeWakers.values()].flatMap((candidate) => candidate.buildExecutionSnapshot()),
     };
+    // The WakeQueue serializes per DIRECT idea (keyFor's key) and coalesces same-key pending
+    // wakes into one batch (add-daemon-wake-coalescing §C1/§C4). It is PER-CONNECTION so the
+    // batch runs on THIS connection's own waker facade — the runBatch drains the per-key data
+    // items { notification, attribution } and hands the whole batch to waker.wakeBatch (all
+    // items on one key share the session anchor, so items[0].attribution is the batch
+    // attribution). maxConcurrency caps this connection's in-flight batches.
+    const queue = new WakeQueue({
+      maxConcurrency,
+      logger,
+      runBatch: (key, items) =>
+        waker.wakeBatch(items.map((i) => i.notification), key, items[0].attribution),
+    });
+
     // The router reads THIS connection's own uuid lazily (same source the control handler
     // uses) to suppress a DIRECTED (pinned) wake stamped for a different connection
     // (fix-pinned-wake-directed-delivery, T2). Null until the SSE handshake assigns it — a
@@ -370,8 +391,20 @@ export function buildDaemon(creds, deps = {}) {
     // all scoped to THIS connection's uuid/router/backfill (see the original wiring
     // comments retained on the shared helpers). The control handler verifies a control
     // event against this connection's own connectionUuid before acting.
-    const redispatchResume = (entityType, entityUuid, resumeReason, runtimeCwd) => {
-      router.dispatchResume?.({ entityType, entityUuid, resumeReason, runtimeCwd });
+    const redispatchResume = (
+      entityType,
+      entityUuid,
+      resumeReason,
+      runtimeCwd,
+      orchestrator,
+    ) => {
+      router.dispatchResume?.({
+        entityType,
+        entityUuid,
+        resumeReason,
+        runtimeCwd,
+        orchestrator,
+      });
     };
     const deliverTurn = (turnUuid) => backfill?.pendingTurnsOnly?.(turnUuid);
     const onControl = createControlHandler({
@@ -483,6 +516,7 @@ export function buildDaemon(creds, deps = {}) {
       connectionState,
       waker,
       runtimeWakers,
+      queue,
       router,
       backfill,
       sseListener,
@@ -501,9 +535,11 @@ export function buildDaemon(creds, deps = {}) {
     mcpClient,
     lineage,
     spawner,
-    queue,
     // Back-compat single-connection aliases (the common single-path case). The full
-    // set is exposed as `connections` for multi-path inspection/tests.
+    // set is exposed as `connections` for multi-path inspection/tests. The WakeQueue is
+    // now per-connection (add-daemon-wake-coalescing) so its runBatch can run on the right
+    // connection's waker facade; the primary connection's queue is aliased here.
+    queue: primary.queue,
     waker: primary.waker,
     router: primary.router,
     sseListener: primary.sseListener,
@@ -526,8 +562,10 @@ export function buildDaemon(creds, deps = {}) {
       //    and latch the queue (queued-but-unstarted wakes never spawn).
       for (const c of connections) {
         c.sseListener.disconnect?.();
+        // Latch each connection's OWN queue (queues are per-connection now — add-daemon-
+        // wake-coalescing) so queued-but-unstarted wakes never spawn.
+        c.queue?.stop?.();
       }
-      queue.stop();
       // 2. Interrupt every in-flight wake subprocess via the shared kill escalation.
       //    Each wake's exit path — seeing shuttingDown — reports its turn
       //    interrupted(shutdown) and suppresses the execution crash report.
@@ -538,7 +576,11 @@ export function buildDaemon(creds, deps = {}) {
       //    the kill escalation window plus a hard 5s cap for the exit path's REST
       //    reports. A wake that outlives this does NOT hang the shutdown — its
       //    orphaned turn is the server-side offline reconcile's job (the backstop).
-      const drained = await queue.drain(sigintTimeoutMs + 5_000);
+      //    Drain every connection's queue in parallel; `drained` is true only if all did.
+      const drainResults = await Promise.all(
+        connections.map((c) => c.queue?.drain?.(sigintTimeoutMs + 5_000) ?? true),
+      );
+      const drained = drainResults.every(Boolean);
       if (!drained) {
         logger.warn(
           "[Chorus] shutdown: in-flight wake(s) did not finish within the bound — exiting anyway (server reconcile will finalize their turns)",