claude-bot/EJClaw
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: prepare 0.2.0 release notes

Browse Source
This commit is contained in:
ejclaw
2026-04-11 21:00:10 +09:00
parent c984d972e1
commit 0185b5e6b6
5 changed files with 354 additions and 290 deletions
Download Patch File Download Diff File Expand all files Collapse all files

169
docs/architecture.md
View File

@@ -1,107 +1,118 @@
# Architecture
# 아키텍처
## Service Stack
## 서비스 구성
Single unified service (`ejclaw`) manages all three Discord bots in one process:
EJClaw는 단일 `ejclaw` 서비스가 세 Discord 봇과 paired runtime을 함께 운영하는 구조입니다.
- `ejclaw.service` — Single unified process
- Discord bots: `DISCORD_OWNER_BOT_TOKEN` (owner), `DISCORD_REVIEWER_BOT_TOKEN` (reviewer), `DISCORD_ARBITER_BOT_TOKEN` (arbiter)
- Paired review: owner ↔ reviewer (agent types configurable per role)
- Reviewer fallback: Claude exhaustion → codex-review auto-handoff
- Shared dirs: `store/`, `groups/`, `data/`
- SQLite WAL mode + `busy_timeout=5000` for concurrent access
- `ejclaw.service`: 단일 unified process
- Discord 봇:
- `DISCORD_OWNER_BOT_TOKEN`
- `DISCORD_REVIEWER_BOT_TOKEN`
- `DISCORD_ARBITER_BOT_TOKEN`
- 저장소:
- `store/`: SQLite DB
- `groups/`: room별 로그 / 메모리 / 설정
- `data/`: 세션, worktree, 런타임 보조 데이터
- SQLite는 WAL + `busy_timeout=5000` 기준으로 동작
## Data Flow
## 핵심 데이터 모델
```
| 구성 요소 | 역할 |
| --- | --- |
| `room_settings` | room-level SSOT |
| `room_role_overrides` | 역할별 agent type / agentConfig override |
| `paired_projects` | canonical project root (`canonical_work_dir`) |
| `paired_tasks` | paired runtime의 상태 머신 |
| `paired_workspaces` | owner / reviewer의 실제 실행 workspace 경로 |
| `registered_groups` | compatibility / materialized read-model 성격의 잔존 레이어 |
현재 기준에서 중요한 점:
- room 설정의 기준은 `room_settings`
- reviewer / arbiter는 room의 공개 진입점이 아니라 내부 역할
- `registered_groups`는 제거 진행 대상이지만 아직 완전히 사라진 것은 아님
## 실행 흐름
```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 → owner finalize
│ ├─ feedback → owner loop
│ └─ BLOCKED → arbiter / user
│
├──► Arbiter (on-demand, fresh session each time)
├──► Arbiter (on-demand)
│ │
│ ┌───┴─── MoA (if enabled) ───┐
│ │ Ref model A ──► opinion │
│ │ Ref model B ──► opinion │
│ │ → injected into prompt │
│ └────────────────────────────┘
│ │
│ PROCEED/REVISE/RESET/ESCALATE
│ ┌───┴─── MoA ───┐
│ │ Kimi / GLM │
│ │ 의견 수집 │
│ └───────────────┘
│
IPC polling ◄── follow-up messages
IPC polling / host tools
│
┌────────── Router ──────────┐
▼ ▼
paired_turn_outputs Discord (display only)
(agent ↔ agent data) (user observation, @mention)
paired_turn_outputs Discord display
```
## Room Assignment Model
## Tribunal 역할 분리
Per-room routing uses an explicit assignment model:
| 역할 | 기본 선택 | 설명 |
| --- | --- | --- |
| owner | room별 `owner_agent_type` (기본 Codex) | 사용자 요청 처리, 코드 작성, 최종 응답 |
| reviewer | 전역 `REVIEWER_AGENT_TYPE` (기본 Claude Code) | owner 결과 검토, 회귀 검증 |
| arbiter | 전역 `ARBITER_AGENT_TYPE` (옵션) | owner / reviewer 교착 시 판정 |
- `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`
- `registered_groups` is a legacy projection being removed from setup/verify/runtime read paths
- Refactor target and migration sequence live in `docs/legacy-compat-removal-spec.md`
역할별 model / effort는 전역 env(`OWNER_*`, `REVIEWER_*`, `ARBITER_*`)로 정하고, room-level `agentConfig`는 provider별(`claudeModel`, `codexModel`) override만 제공합니다.
Operationally:
## Reviewer / Arbiter runtime
- `single` → one owner bot
- `tribunal` → per-room owner + globally configured reviewer + optional arbiter
- reviewer는 owner의 현재 workspace를 direct mount로 읽습니다
- snapshot copy는 현재 기본 실행 경로가 아닙니다
- reviewer workspace 레코드가 오래된 경로를 가리키면 실행 직전에 owner 현재 workspace로 재동기화합니다
- arbiter는 reviewer와 같은 read-only workspace를 쓰되, 세션 디렉토리는 매 호출마다 fresh하게 준비합니다
Tribunal is no longer inferred from "two bots registered on one room"; it is an explicit room setting.
즉 reviewer가 보는 실행 경로는:
## Tribunal 3-Agent System
1. `paired_projects.canonical_work_dir` 같은 canonical root와 별개로
2. `paired_workspaces.workspace_dir`에 저장된 실제 owner worktree
```
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
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
```
입니다.
## Verification Execution
## 세션 / 프롬프트 구성
Reviewer and arbiter now run as host processes with role-scoped read-only
guards and sandbox settings. Verification profiles run directly on the host with
restricted environment variables and snapshot checks:
- owner는 stable worktree + stable session을 사용
- reviewer / arbiter는 read-only 세션 디렉토리를 매 실행 전에 다시 준비
- `prepareReadonlySessionEnvironment()`가 `CLAUDE.md`, `.codex/AGENTS.md`, 설정 파일을 매번 재생성
- 그래서 reviewer 관련 프롬프트 / workspace 변경은 기존 실행 중 프로세스에는 즉시 적용되지 않지만, **다음 reviewer 턴부터는 자동 반영**됩니다
- Fixed-profile direct execution (`test`, `typecheck`, `build`)
- Snapshot comparison before/after execution
- Root-level runtime/build directories excluded from verification snapshot
- Role-scoped reviewer safeguards remain independent of verification execution
## 검증 / 운영 경로
## Key Files
- 검증 명령은 `bun run check` 하나로 묶여 있음
- format
- typecheck
- test
- build
- reviewer / arbiter가 직접 로컬 빌드를 못 돌려도, host verification 경로로 `typecheck`, `test`, `build`를 수행할 수 있음
- startup precondition은 전용 오류로 올리고, `RestartPreventExitStatus=78`로 crash loop를 막음
- deploy는 `migrate-room-registrations`를 선행한 뒤 service restart를 수행
| File | Purpose |
| ------------------------- | ---------------------------------------------------------- |
| `src/index.ts` | Orchestrator: state, message loop, agent invocation |
| `src/agent-runner.ts` | Spawns agent processes, manages env/sessions/skills |
| `src/verification.ts` | Fixed-profile verification execution with snapshot checks |
| `src/channels/discord.ts` | Discord channel (8s typing refresh, Whisper transcription) |
| `src/ipc.ts` | IPC watcher and task processing |
| `src/router.ts` | Message formatting and outbound routing |
| `src/config.ts` | Trigger pattern, paths, intervals |
| `src/task-scheduler.ts` | Runs scheduled tasks |
| `src/db.ts` | SQLite operations |
| `runners/agent-runner/` | Claude Code runner (Agent SDK) |
| `runners/codex-runner/` | Codex runner (SDK, `codex exec` wrapper) |
| `groups/{name}/CLAUDE.md` | Per-group memory (isolated) |
## 주요 파일
| 파일 | 역할 |
| --- | --- |
| `src/index.ts` | 전체 오케스트레이션 진입점 |
| `src/message-runtime.ts` | 메시지 루프, paired flow 연결 |
| `src/message-turn-controller.ts` | progress / final delivery 제어 |
| `src/paired-execution-context.ts` | owner / reviewer / arbiter 실행 준비 |
| `src/paired-workspace-manager.ts` | owner / reviewer workspace 관리 |
| `src/agent-runner.ts` | host process spawn, env/session wiring |
| `src/db.ts` | 런타임 DB facade |
| `src/db/` | canonical room / paired state / migration 로직 |
| `runners/agent-runner/` | Claude Code runner |
| `runners/codex-runner/` | Codex runner |
| `setup/` | setup / verify / service rendering |

154
docs/configuration.md
View File

@@ -1,83 +1,145 @@
# Configuration
# 설정
All configuration in a single `.env` file.
EJClaw의 설정 기준은 `.env` 하나입니다.
프로젝트 루트의 [`../.env.example`](../.env.example)를 기본 예시로 보고, 이 문서는 현재 런타임에서 의미가 있는 키만 추려 설명합니다.
## Discord Bots
## 기본 원칙
- Discord 토큰은 role-fixed canonical 키만 사용합니다
- reviewer 기본 provider는 `claude-code`
- owner 기본 provider는 `codex`
- room-level override는 provider 단위(`claudeModel`, `codexModel`)만 지원합니다
- `CLAUDE_CODE_OAUTH_TOKENS`가 canonical이고, `CLAUDE_CODE_OAUTH_TOKEN`은 legacy fallback입니다
## Discord 봇
```bash
DISCORD_OWNER_BOT_TOKEN= # Owner bot
DISCORD_REVIEWER_BOT_TOKEN= # Reviewer bot
DISCORD_ARBITER_BOT_TOKEN= # Arbiter bot
DISCORD_OWNER_BOT_TOKEN=
DISCORD_REVIEWER_BOT_TOKEN=
DISCORD_ARBITER_BOT_TOKEN=
```
## Agent Types & Models
예전 service-based alias는 더 이상 허용되지 않습니다.
## 역할 / 모델 설정
```bash
# Agent types per role
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)
# 역할별 provider
OWNER_AGENT_TYPE=codex
REVIEWER_AGENT_TYPE=claude-code
# ARBITER_AGENT_TYPE=claude-code
# Per-role model overrides
# provider 기본 모델
CLAUDE_MODEL=claude-opus-4-6
CLAUDE_EFFORT=high
CLAUDE_THINKING=adaptive
CODEX_MODEL=gpt-5.4
CODEX_EFFORT=xhigh
# 역할별 override
OWNER_MODEL=gpt-5.4
REVIEWER_MODEL=claude-opus-4-6
ARBITER_MODEL=gpt-5.4
# Per-role effort level
OWNER_EFFORT=xhigh
OWNER_FALLBACK_ENABLED=true
REVIEWER_MODEL=claude-opus-4-6
REVIEWER_EFFORT=high
ARBITER_EFFORT=xhigh
REVIEWER_FALLBACK_ENABLED=true
# Per-role fallback toggle
REVIEWER_FALLBACK_ENABLED=true # Auto-handoff to codex when Claude exhausted
ARBITER_FALLBACK_ENABLED=false
# Response language
AGENT_LANGUAGE=Korean # Injected into all agent prompts
ARBITER_MODEL=claude-sonnet-4-6
ARBITER_EFFORT=high
ARBITER_FALLBACK_ENABLED=true
```
## Authentication
설명:
- reviewer / arbiter provider 선택은 **전역 설정**
- 특정 방에서만 reviewer를 Codex로 고르는 기능은 없음
- room-level `agentConfig`의 `claudeModel`, `codexModel`은 역할별이 아니라 provider별 override
- `ARBITER_AGENT_TYPE`은 옵션이며, 설정하지 않으면 arbiter는 비활성 상태입니다
## 인증
```bash
CLAUDE_CODE_OAUTH_TOKEN= # Claude Code OAuth token
CLAUDE_CODE_OAUTH_TOKENS= # Comma-separated for multi-account rotation
OPENAI_API_KEY= # Codex API key (if not using OAuth)
# Claude Code OAuth
CLAUDE_CODE_OAUTH_TOKENS=
CLAUDE_CODE_OAUTH_TOKEN=
# Claude host env (선택)
ANTHROPIC_API_KEY=
ANTHROPIC_AUTH_TOKEN=
ANTHROPIC_BASE_URL=
```
## Voice Transcription
설명:
- `CLAUDE_CODE_OAUTH_TOKENS`: canonical, 쉼표 구분
- `CLAUDE_CODE_OAUTH_TOKEN`: 단일 토큰 legacy fallback
- 실제 runner에는 현재 선택된 Claude 토큰 하나만 주입됩니다
Codex 쪽은 현재 **OAuth 세션 파일** 기준으로 동작합니다. `OPENAI_API_KEY`를 Codex child process에 넘겨서 빌링하는 구조는 사용하지 않습니다.
## 음성 전사
```bash
GROQ_API_KEY= # Groq whisper-large-v3-turbo (primary)
OPENAI_API_KEY= # OpenAI whisper-1 (fallback)
GROQ_API_KEY=
```
## Mixture of Agents (MoA)
- 기본은 Groq Whisper
- 필요 시 OpenAI Whisper fallback을 별도 확장할 수 있지만, 현재 README / 문서 기준 최소 키는 `GROQ_API_KEY`입니다
## MoA
```bash
MOA_ENABLED=true
MOA_REF_MODELS=kimi,glm # Configurable reference model list
MOA_REF_MODELS=kimi,glm
# Per-model config (pattern: MOA_{NAME}_{SETTING})
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_MODEL=glm-4-plus
MOA_GLM_BASE_URL=https://open.bigmodel.cn/api/paas/v4
MOA_GLM_API_KEY=xxx
MOA_GLM_API_FORMAT=anthropic
```
## Debugging Paths
MoA는 arbiter 판정 전에 외부 모델 의견을 수집해 prompt에 주입합니다.
`API_FORMAT` 같은 항목은 `.env.example`의 최소 예시에 없는 운영 확장 키입니다.
| Item | Path |
|------|------|
| **DB** | `store/messages.db` (shared, WAL mode) |
| Service log | `journalctl --user -u ejclaw -f` or `logs/ejclaw.log` |
| Per-group logs | `groups/{name}/logs/` |
| Claude sessions | `data/sessions/{name}/.claude/` |
| Codex sessions | `data/sessions/{name}/.codex/` |
| Claude platform rules | `prompts/claude-platform.md` |
| Codex platform rules | `prompts/codex-platform.md` |
| Global memory | `groups/global/CLAUDE.md` |
## 운영 / 배포 관련 설정
```bash
ASSISTANT_NAME=claude
STATUS_CHANNEL_ID=
SESSION_COMMAND_ALLOWED_SENDERS=
MAX_CONCURRENT_AGENTS=5
```
- `ASSISTANT_NAME`은 owner trigger 기본 이름을 만듭니다
- paired room에서도 사용자 진입점은 owner가 기준입니다
- status dashboard와 session command는 선택 설정입니다
## 디버깅 경로
| 항목 | 경로 / 명령 |
| --- | --- |
| DB | `store/messages.db` |
| 서비스 로그 | `journalctl --user -u ejclaw -f` |
| room 로그 | `groups/{folder}/logs/` |
| owner/reviewer 세션 | `data/sessions/{folder}*` |
| owner worktree | `data/workspaces/{folder}/owner` |
| Claude 플랫폼 프롬프트 | `prompts/claude-platform.md` |
| reviewer 프롬프트 | `prompts/claude-paired-room.md` |
| arbiter 프롬프트 | `prompts/arbiter-paired-room.md` |
| Codex 플랫폼 프롬프트 | `prompts/codex-platform.md` |
| 글로벌 메모리 | `groups/global/CLAUDE.md` |
## 문서와 실제 코드의 우선순위
문서보다 실제 동작이 우선입니다. 동작 기준을 확인할 때는 아래를 먼저 봅니다.
1. `.env.example`
2. `src/config/load-config.ts`
3. `src/agent-runner-environment.ts`
4. `src/paired-execution-context.ts`