docs: prepare 0.2.0 release notes

2026-04-11 21:00:10 +09:00
parent c984d972e1
commit 0185b5e6b6
5 changed files with 354 additions and 290 deletions
--- a/README.md
+++ b/README.md
@@ -1,220 +1,180 @@
 # EJClaw

-![Version](https://img.shields.io/badge/version-0.1.0-blue)
+![Version](https://img.shields.io/badge/version-0.2.0-blue)
 ![Claude Agent SDK](https://img.shields.io/badge/Claude_Agent_SDK-0.2.87-blueviolet)
 ![Codex SDK](https://img.shields.io/badge/Codex_SDK-0.117.0-green)
 ![Bun](https://img.shields.io/badge/Bun-1.3+-f9f1e1?logo=bun&logoColor=black)
-![Discord](https://img.shields.io/badge/Discord-Bot-5865F2?logo=discord&logoColor=white)
+![Discord](https://img.shields.io/badge/Discord-Tribunal-5865F2?logo=discord&logoColor=white)

-Tribunal multi-agent AI assistant (Owner + Reviewer + Arbiter) over Discord with autonomous paired review and Mixture of Agents.
+EJClaw는 Discord 위에서 동작하는 Tribunal 멀티에이전트 개발 보조 시스템입니다.
+사용자 요청은 owner가 받고, reviewer가 자동 리뷰를 수행하며, 필요할 때 arbiter가 교착을 정리합니다.

-Originally derived from [qwibitai/nanoclaw](https://github.com/qwibitai/nanoclaw), now independently maintained as EJClaw.
-Prompt design inspired by [Q00/ouroboros](https://github.com/Q00/ouroboros) and [garrytan/gstack](https://github.com/garrytan/gstack), adapted for EJClaw's Discord and dual-service workflow.
-Tribunal arbiter system inspired by multi-agent consensus architectures.
+원본은 [qwibitai/nanoclaw](https://github.com/qwibitai/nanoclaw)에서 출발했지만, 현재는 EJClaw의 Discord/paired-runtime 구조에 맞게 독립적으로 유지되고 있습니다.

-## Overview
+## 개요

-A single unified service (`ejclaw`) runs a **Tribunal** of three roles while
-managing three Discord bots in one process:
+- 단일 `ejclaw` 서비스가 owner / reviewer / arbiter 세 역할과 세 Discord 봇을 함께 관리합니다.
+- 사용자 진입점은 owner 하나이며, reviewer와 arbiter는 내부 역할로 동작합니다.
+- room-level 설정은 `room_settings`를 기준으로 하며, `assign_room`이 공개 assignment 인터페이스입니다.
+- reviewer는 owner의 현재 worktree를 direct mount로 읽고, role-scoped read-only 보호를 적용받습니다.
+- paired runtime은 SQLite(WAL), stable owner worktree, turn/lease 추적, host verification으로 구성됩니다.

-| Role | Purpose |
-|------|---------|
-| **Owner** | Handles user requests, writes code |
-| **Reviewer** | Critically reviews owner's work, verifies design direction |
-| **Arbiter** | On-demand deadlock breaker between owner and reviewer |
+## 핵심 기능

-The identity layer is role-fixed:
+- Tribunal 3-에이전트 루프: owner / reviewer / arbiter
+- Mixture of Agents(MoA): 외부 모델 의견을 arbiter 판단에 주입
+- 역할별 agent type / model / effort 설정
+- role-fixed Discord 봇 3개 체계
+- reviewer host runtime + read-only guard
+- 승인 후 변경 감지와 재리뷰
+- Claude 장애 시 Codex로 넘기는 global failover
+- Claude OAuth 멀티 토큰 로테이션
+- `assign_room` 기반 명시적 room assignment
+- Bun + SQLite 기반 빠른 런타임

- **Owner bot** — Handles the owner turn output slot.
- **Reviewer bot** — Handles the reviewer turn output slot.
- **Arbiter bot** — Handles the arbiter turn output slot.
+## Tribunal 시스템

-Each role's agent type and model are independently configurable via `.env`
-(`OWNER_AGENT_TYPE`, `REVIEWER_AGENT_TYPE`, `ARBITER_AGENT_TYPE`, `*_MODEL`).
-Three Discord bots provide the identity layer — which bot speaks is determined
-by the active role, not hardcoded.
+| 역할 | 현재 기본값 | 설명 |
+| --- | --- | --- |
+| Owner | room별 `owner_agent_type` (기본 Codex) | 사용자 요청 처리, 코드 작성, 최종 응답 |
+| Reviewer | 전역 `REVIEWER_AGENT_TYPE` (기본 Claude Code) | owner 결과 비판적 리뷰, 회귀 검증 |
+| Arbiter | 전역 `ARBITER_AGENT_TYPE` (옵션) | owner/reviewer 교착 시 판정 |

-## Room Assignment Model
-
-Per-room routing now uses an explicit assignment model:
-
- `room_settings` is the room-level source of truth (SSOT)
- Each room stores:
-  - `room_mode`: `single` or `tribunal`
-  - `owner_agent_type`: `codex` or `claude-code`
- Public room assignment uses `assign_room`
- Legacy `register_group` public interfaces were removed
- `registered_groups` remains as a materialized capability/read-model layer and legacy fallback, not the authoritative room configuration
-
-Operationally:
-
- `single` → one owner bot
- `tribunal` → per-room owner + globally configured reviewer + optional arbiter
-
-This means tribunal is no longer inferred from “two bots registered on one room”; it is an explicit room setting.
-
-## Tribunal Flow
-
-```
-User message
-  → Owner responds (implementation, answer, etc.)
-    → Reviewer auto-triggered (critical review, design check)
-      → Verdict:
-          DONE              → Owner finalizes → Task completed → @user ✅
-          DONE_WITH_CONCERNS → Owner addresses feedback → loop
+```text
+사용자 메시지
+  → Owner 응답
+    → Reviewer 자동 실행
+      → verdict:
+          DONE               → Owner finalize → 완료
+          DONE_WITH_CONCERNS → Owner 수정 → 재리뷰 루프
          BLOCKED/NEEDS_CONTEXT
-            ├─ Arbiter enabled → Arbiter judges → PROCEED/REVISE/RESET/ESCALATE
-            └─ Arbiter disabled → Escalate to user → @user ⚠️
-      → Owner BLOCKED/NEEDS_CONTEXT → Arbiter (same path as reviewer)
-      → Deadlock (2+ round trips without progress)
-          → Arbiter summoned → binding verdict → loop resumes
+            ├─ Arbiter enabled  → Arbiter 판정
+            └─ Arbiter disabled → 사용자로 에스컬레이션
+      → 왕복이 누적되면 arbiter 자동 요청 가능
 ```

-### Mixture of Agents (MoA)
+### MoA

-When enabled, the arbiter collects opinions from external models (Kimi, GLM, etc.) before rendering its verdict:
+MoA가 켜져 있으면 arbiter가 판정하기 전에 Kimi, GLM 같은 외부 모델 의견을 병렬 수집하고, 그 결과를 arbiter 프롬프트에 주입합니다. 최종 판정은 여전히 EJClaw arbiter가 내립니다.

-```
-Deadlock detected → MoA reference queries (Kimi + GLM, parallel)
-  → Opinions injected into arbiter's prompt
-    → SDK arbiter (subscription-based) aggregates all perspectives
-      → Final verdict: PROCEED / REVISE / RESET / ESCALATE
-```
+## 방 설정 모델

-No extra SDK processes. External references use lightweight API calls (Anthropic-compatible).
+현재 room 설정의 기준은 다음과 같습니다.

-## Features
+- `room_settings`: room-level SSOT
+- `room_role_overrides`: owner / reviewer / arbiter 역할별 override
+- `paired_projects`: canonical project root
+- `paired_workspaces`: 실제 owner / reviewer 실행 workspace
+- `registered_groups`: 완전히 제거되지는 않았지만, canonical source가 아니라 compatibility/read-model 성격으로 남아 있는 레이어

- **Tribunal 3-agent system** — Owner/reviewer/arbiter with on-demand deadlock resolution
- **Discord-independent communication** — Agent-to-agent data flows directly via DB, Discord is display-only
- **Mixture of Agents** — External model opinions (Kimi, GLM) enrich arbiter verdicts
- **Per-role model selection** — `OWNER_MODEL`, `REVIEWER_MODEL`, `ARBITER_MODEL` + effort + fallback toggle
- **Host reviewer with read-only guards** — Reviewer runs on host with role-scoped sandbox and guard policy
- **Global failover** — Account-level Claude failure → all channels switch to codex, auto-recovers
- **Post-approval change detection** — Re-triggers review if owner modifies code after approval
- **Auto user notification** — @mention on task completion (✅ done, ⚠️ escalated)
- **Loop protection** — Deadlock threshold, merge_ready oscillation guard, arbiter re-invocation limit
- **Voice transcription** — Groq Whisper (primary) / OpenAI Whisper (fallback)
- **Token rotation** — Multi-account Claude/Codex rotation on rate limits
- **Kimi usage dashboard** — Coding plan 5h/7d usage displayed alongside Claude/Codex
- **MCP integration** — Memento (persistent memory) + EJClaw host tools
- **Session persistence** — Separate sessions per role (owner/reviewer/arbiter)
- **Scheduled tasks** — Cron/interval/once via MCP tool
- **Mid-turn steering** — Inject follow-up messages while agent is working
- **Bun runtime** — Native SQLite (bun:sqlite), fast startup, no native addon builds
+운영적으로는:

-## Architecture
+- `single` → owner만 실행
+- `tribunal` → owner + reviewer + optional arbiter

-```
+중요한 점:
+
+- reviewer는 더 이상 snapshot copy를 기본 실행 경로로 쓰지 않습니다.
+- reviewer는 owner의 현재 workspace를 direct mount로 읽습니다.
+- stale reviewer workspace 레코드가 남아 있어도 실행 직전 owner 현재 경로로 재동기화됩니다.
+
+## 아키텍처
+
+```text
 Discord ──► SQLite (WAL) ──► GroupQueue ──┬──► Owner (host process)
                                          │       │
-                                          │       ▼ (auto-trigger)
-                                          ├──► Reviewer (host process, read-only guarded)
+                                          │       ▼
+                                          ├──► Reviewer (host process, read-only)
                                          │       │
-                                          │   Verdict routing
-                                          │       ├─ DONE → change detection → finalize or re-review
-                                          │       ├─ BLOCKED → Arbiter (if enabled) or User
-                                          │       └─ Feedback → Owner (loop)
+                                          │   verdict routing
+                                          │       ├─ DONE → finalize
+                                          │       ├─ feedback → owner loop
+                                          │       └─ BLOCKED → arbiter / user
                                          │
-                                          ├──► Arbiter (on-demand, fresh session each time)
+                                          ├──► Arbiter (on-demand, fresh session)
                                          │       │
-                                          │   ┌───┴─── MoA (if enabled) ───┐
-                                          │   │ Kimi API ──► opinion       │
-                                          │   │ GLM API  ──► opinion       │
-                                          │   │ → injected into prompt     │
-                                          │   └────────────────────────────┘
-                                          │       │
-                                          │   PROCEED/REVISE/RESET/ESCALATE
+                                          │   ┌───┴─── MoA ───┐
+                                          │   │ Kimi / GLM    │
+                                          │   │ 의견 수집      │
+                                          │   └───────────────┘
                                          │
-                                     IPC polling ◄── follow-up messages
+                                     IPC follow-up / host tools
                                          │
                              ┌────────── Router ──────────┐
                              ▼                            ▼
-                   paired_turn_outputs           Discord (display only)
-                   (agent ↔ agent data)      (user observation, @mention)
+                    paired_turn_outputs            Discord display
 ```

-## Setup
+## 시작하기

-### Prerequisites
+### 요구사항

- Linux (Ubuntu 22.04+) or macOS
+- Linux(Ubuntu 22.04+) 또는 macOS
 - [Bun](https://bun.sh/) 1.3+
- [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code)
- [Codex CLI](https://github.com/openai/codex) (`npm install -g @openai/codex`)
- Discord bot tokens (3: owner, reviewer, arbiter)
+- Claude Code CLI
+- Codex CLI
+- Discord 봇 토큰 3개(owner / reviewer / arbiter)

-### Install
+### 설치

 ```bash
 git clone https://github.com/phj1081/EJClaw.git
 cd EJClaw
 bun install
-bun run build:runners
-bun run build
+bun run build:all
 ```

-## Documentation
+### 환경 설정

- [Architecture](docs/architecture.md) — Data flow, room model, verification execution, key files
- [Configuration](docs/configuration.md) — Full `.env` reference, debugging paths
-
-### Environment
-
-All configuration in a single `.env` file:
+- `.env.example`를 기준으로 `.env`를 작성합니다.
+- 전체 키 설명은 [docs/configuration.md](docs/configuration.md)를 봅니다.
+- 최소한 아래는 먼저 채워야 합니다.

 ```bash
-# Discord bots (canonical role-fixed names)
-DISCORD_OWNER_BOT_TOKEN=         # Owner bot
-DISCORD_REVIEWER_BOT_TOKEN=      # Reviewer bot
-DISCORD_ARBITER_BOT_TOKEN=       # Arbiter bot
-
-# Old service-based token names are no longer accepted.
-# Rename existing values to the canonical role-based keys above.
-
-# Agent types
-OWNER_AGENT_TYPE=codex            # codex | claude-code
-REVIEWER_AGENT_TYPE=claude-code   # claude-code | codex
-ARBITER_AGENT_TYPE=codex          # codex | claude-code (optional, enables 3rd agent)
-
-# Per-role model overrides
-OWNER_MODEL=gpt-5.4
-REVIEWER_MODEL=claude-opus-4-6
-ARBITER_MODEL=gpt-5.4
-
-# API keys
-CLAUDE_CODE_OAUTH_TOKEN=          # Claude Code OAuth token
-CLAUDE_CODE_OAUTH_TOKENS=         # Comma-separated for multi-account rotation
-GROQ_API_KEY=                     # Voice transcription (Groq Whisper)
-
-# Mixture of Agents (MoA)
-MOA_ENABLED=true
-MOA_REF_MODELS=kimi,glm
-MOA_KIMI_MODEL=kimi-k2.5
-MOA_KIMI_BASE_URL=https://api.kimi.com/coding
-MOA_KIMI_API_KEY=sk-kimi-xxx
-MOA_KIMI_API_FORMAT=anthropic
-MOA_GLM_MODEL=glm-5.1
-MOA_GLM_BASE_URL=https://open.bigmodel.cn/api/anthropic
-MOA_GLM_API_KEY=xxx
-MOA_GLM_API_FORMAT=anthropic
+DISCORD_OWNER_BOT_TOKEN=
+DISCORD_REVIEWER_BOT_TOKEN=
+DISCORD_ARBITER_BOT_TOKEN=
+CLAUDE_CODE_OAUTH_TOKENS=
+OWNER_AGENT_TYPE=codex
+REVIEWER_AGENT_TYPE=claude-code
 ```

-### Deploy
+### 실행
+
+```bash
+bun run dev
+```
+
+### 배포

 ```bash
 bun run deploy
 ```

-## Development
+이 스크립트는 다음을 순서대로 수행합니다.
+
+1. 최신 커밋 fast-forward pull
+2. 전체 build
+3. `migrate-room-registrations` 실행
+4. `systemctl --user restart ejclaw`
+
+## 개발

 ```bash
-bun run build                # Build main project
-bun run build:runners        # Install + build both runners
-bun run dev                  # Dev mode with hot reload
-bun test                     # Run tests
+bun run build
+bun run build:runners
+bun run test
+bun run typecheck
+bun run check
 ```

-## License
+## 문서

-MIT — Originally derived from [qwibitai/nanoclaw](https://github.com/qwibitai/nanoclaw)
+- [docs/architecture.md](docs/architecture.md) — 데이터 모델, 실행 흐름, 주요 파일
+- [docs/configuration.md](docs/configuration.md) — `.env` 키와 디버깅 경로
+- [docs/legacy-compat-removal-spec.md](docs/legacy-compat-removal-spec.md) — 남아 있는 레거시 제거 계획
+- [CHANGELOG.md](CHANGELOG.md) — 릴리즈 이력
+
+## 라이선스
+
+MIT