docs(cleanup): remove redundant root-level bug report and synchronize project documentation to v4.1.3
This commit is contained in:
Godopu committed
1 parent
8154d9a12b
commit
cfa15eadee
9 files changed
+56
-105
No files matched your search
@@ -18,7 +18,7 @@
|
||||
- **모호성 제거**: 사용자의 요구사항에 모호한 부분이 있다면 작업을 추측하여 진행하지 말고, 즉시 사용자에게 질문하여 명확히 해야 합니다 (`/grill-me` 슬래시 명령어 권장).
|
||||
|
||||
### 👥 Team Leaders (팀장)
|
||||
새롭게 생성되는 에이전트(`antigravity`, `claude`, `cline`, `hermes` 등)는 각 팀의 **팀장** 역할을 수행합니다. 총괄 매니저로부터 작업을 위임받아 개발 또는 리뷰 워크플로우를 주도합니다.
|
||||
새롭게 생성되는 에이전트(`antigravity`, `claude`, `hermes`, `grok`, `opencode` 등)는 각 팀의 **팀장** 역할을 수행합니다. 총괄 매니저로부터 작업을 위임받아 개발 또는 리뷰 워크플로우를 주도합니다.
|
||||
- **Developer Team Leader (개발 팀장)**:
|
||||
- 총괄 매니저로부터 작업을 위임받습니다.
|
||||
- **작업 분석 및 계획**: 주어진 작업을 철저히 분석하고, 작은 단위로 문제를 나누어 세부 계획을 수립합니다.
|
||||
|
||||
@@ -18,7 +18,7 @@ We clearly separate responsibilities and permissions between roles to reduce bot
|
||||
- **Ambiguity Resolution**: If a user's requirements contain ambiguous details, do not guess. Immediately ask the user for clarification (we recommend using the `/grill-me` slash command).
|
||||
|
||||
### 👥 Team Leaders (팀장)
|
||||
Newly spawned agents (e.g., `antigravity`, `claude`, `cline`, `hermes`) act as **Team Leaders** of their respective groups. They receive delegated tasks from the General Manager and manage implementation or review workflows.
|
||||
Newly spawned agents (e.g., `antigravity`, `claude`, `hermes`, `grok`, `opencode`) act as **Team Leaders** of their respective groups. They receive delegated tasks from the General Manager and manage implementation or review workflows.
|
||||
- **Developer Team Leader (개발 팀장)**:
|
||||
- Receives tasks from the General Manager.
|
||||
- **Task Breakdown & Planning**: Thoroughly analyzes the task, breaks it down into small units, and creates a plan.
|
||||
|
||||
@@ -69,9 +69,15 @@ UUID=$(bash .agents/skills/multi-agent-mux-resume/scripts/resolve_session_id.sh
|
||||
--workspace "$WORKSPACE" --agent "$AGENT" --session "$SESSION_NAME")
|
||||
|
||||
if [ -z "$UUID" ]; then
|
||||
# For Class A, resume_session.sh handles fresh-spawn fallback automatically.
|
||||
echo "No saved session for $WORKSPACE ($AGENT). Class B agents must use multi-agent-mux-create first."
|
||||
exit 1
|
||||
case "$AGENT" in
|
||||
agy|hermes|opencode)
|
||||
: # resume_session.sh handles fresh-spawn fallback automatically (FRESH_SPAWN=1)
|
||||
;;
|
||||
*)
|
||||
echo "ERROR: No saved session for $WORKSPACE ($AGENT). Use multi-agent-mux-create first." >&2
|
||||
exit 1
|
||||
;;
|
||||
esac
|
||||
fi
|
||||
|
||||
export HERDR_SESSION_NAME="$(resolve_herdr_session "$SESSION_NAME" "$WORKSPACE")"
|
||||
@@ -86,10 +92,11 @@ fi
|
||||
# 3. Determine CMD_FULL
|
||||
# For claude: if assigned UUID transcript .jsonl is unmaterialized on disk, use --session-id <uuid>; otherwise use -r <uuid>
|
||||
case "$AGENT" in
|
||||
claude) CMD_FULL="claude --dangerously-skip-permissions $CLAUDE_ID_FLAG $UUID" ;;
|
||||
agy) CMD_FULL="agy --dangerously-skip-permissions --conversation $UUID" ;;
|
||||
hermes) CMD_FULL="hermes --resume $UUID --no-restore-cwd --yolo --accept-hooks" ;;
|
||||
grok) CMD_FULL="grok --resume $UUID --permission-mode bypassPermissions" ;;
|
||||
claude) CMD_FULL="claude --dangerously-skip-permissions $CLAUDE_ID_FLAG $UUID" ;;
|
||||
agy) CMD_FULL="agy --dangerously-skip-permissions --conversation $UUID" ;;
|
||||
hermes) CMD_FULL="hermes --resume $UUID --no-restore-cwd --yolo --accept-hooks" ;;
|
||||
grok) CMD_FULL="grok --resume $UUID --permission-mode bypassPermissions" ;;
|
||||
opencode) CMD_FULL="opencode --session $UUID --auto --agent build" ;;
|
||||
esac
|
||||
|
||||
# 4. Spawn new herdr session + run agent with the saved id
|
||||
@@ -100,7 +107,7 @@ case "$AGENT" in
|
||||
# auto-handle trust / bypass dialogs
|
||||
handle_startup_dialogs "$SESSION_NAME" 20
|
||||
;;
|
||||
agy|hermes|grok)
|
||||
agy|hermes|grok|opencode)
|
||||
eval "herdr new-session -d -s \"$SESSION_NAME\" -x 140 -y 40 -c \"$WORKSPACE\" \"$CMD_FULL\""
|
||||
;;
|
||||
esac
|
||||
|
||||
+5
-1
@@ -2,6 +2,8 @@
|
||||
|
||||
본 문서는 `herdr_agent_orchestration` 오케스트레이션 및 메시징 백플레인 워크플로우를 새로운 프로젝트에 도입하여 이식하고, 새로운 개발자/에이전트가 초기 가동을 시작할 때 수행해야 하는 환경 설정 및 구축 절차를 안내합니다.
|
||||
|
||||
[](VERSIONS.md)
|
||||
|
||||
새로운 에이전트는 이 안내서에 기술된 절차를 순차적으로 실행하여 초기 환경을 안정적으로 설정할 수 있습니다.
|
||||
|
||||
---
|
||||
@@ -27,6 +29,8 @@
|
||||
* `job_subscriber.py`: 백그라운드 이벤트 구독기 및 오디팅 로그 생성기
|
||||
* `publish_event.py`: 실행 상태 및 에러 트랩 시 이벤트 퍼블리셔
|
||||
* `mqtt_common.py`: 공통 MQTT 브로커 연결 유틸리티
|
||||
* `multi-agent-mux-loop/`: 자율적인 계획-실행-교차검증 반복 순환 루프 오케스트레이터
|
||||
* `multi-agent-mux-orc-onboard/`: 오케스트레이터 세션 UUID 온보딩 및 서브에이전트 격리 헬퍼
|
||||
* `MESSAGING.md`: 에이전트 간 주고받는 MQTT 메시지 와이어 스킴 가이드라인
|
||||
|
||||
---
|
||||
@@ -189,6 +193,6 @@ rm -f ".mam/jobs/$JID.json" ".mam/jobs/$JID.lock"
|
||||
|
||||
## 7. 에이전트 온보딩 가이드 (New Agent Onboarding)
|
||||
|
||||
본 환경 구축을 무사히 마쳤다면, 협업하는 에이전트는 즉시 .agents/ 디렉터리에 있는 **[MULTI_AGENT_RULES.ko.md](.agents/MULTI_AGENT_RULES.ko.md)** 문서를 읽어야 합니다.
|
||||
본 환경 구축을 무사히 마쳤다면, 협업하는 에이전트(`claude`, `agy`, `hermes`, `grok`, `opencode`)는 즉시 .agents/ 디렉터리에 있는 **[MULTI_AGENT_RULES.ko.md](.agents/MULTI_AGENT_RULES.ko.md)** 문서를 읽어야 합니다.
|
||||
|
||||
해당 문서에는 에이전트가 각 역할(PM, Worker, Reviewer)로 구동될 때 지켜야 할 **수술적 변경 규칙, 교차 검증 통과 규약, Herdr 뷰포트 유실 방지를 위한 스냅샷 패턴** 등이 서술되어 있어 안정적인 멀티 에이전트 워크플로우에 즉시 기여할 수 있도록 돕습니다.
|
||||
+5
-1
@@ -2,6 +2,8 @@
|
||||
|
||||
This document guides you through the setup and initialization procedures required to adopt the `herdr_agent_orchestration` orchestration and messaging backplane workflow in a new project, enabling a new developer or agent to get up and running quickly.
|
||||
|
||||
[](VERSIONS.md)
|
||||
|
||||
A new agent can follow the steps in this guide sequentially to establish a stable and reliable initial environment.
|
||||
|
||||
---
|
||||
@@ -27,6 +29,8 @@ Before cloning this project into a new environment, you must first understand th
|
||||
* `job_subscriber.py`: Background event subscriber and audit log generator.
|
||||
* `publish_event.py`: Event publisher for runtime states and error traps.
|
||||
* `mqtt_common.py`: Common utility for connecting to the MQTT broker.
|
||||
* `multi-agent-mux-loop/`: Autonomous planning-execution-review loop orchestrator.
|
||||
* `multi-agent-mux-orc-onboard/`: Orchestrator session UUID onboarding and sub-agent isolation helper.
|
||||
* `MESSAGING.md`: Messaging scheme and wire protocol guidelines for MQTT communication between agents.
|
||||
|
||||
---
|
||||
@@ -190,6 +194,6 @@ rm -f ".mam/jobs/$JID.json" ".mam/jobs/$JID.lock"
|
||||
|
||||
## 7. Onboarding Collaborating Agents (New Agent Onboarding)
|
||||
|
||||
Once the setup is verified, onboarding agents should immediately read the **[MULTI_AGENT_RULES.md](.agents/MULTI_AGENT_RULES.md)** guidelines in the .agents/ directory.
|
||||
Once the setup is verified, onboarding agents (`claude`, `agy`, `hermes`, `grok`, `opencode`) should immediately read the **[MULTI_AGENT_RULES.md](.agents/MULTI_AGENT_RULES.md)** guidelines in the .agents/ directory.
|
||||
|
||||
The guidelines describe essential workflows—such as **surgical change constraints, cross-verification review loops, and pane snapshotting to prevent viewport truncation**—allowing new agents to quickly and safely integrate with the multi-agent workflow.
|
||||
+14
-8
@@ -1,6 +1,8 @@
|
||||
# herdr-agent-orchestration (다중 에이전트 Herdr 오케스트레이션 및 메시징 백플레인)
|
||||
|
||||
Herdr와 MQTT 브로커를 기반으로 구축된 고신뢰성 **다중 에이전트 오케스트레이션 및 메시징 백플레인** 프레임워크입니다. Claude, Hermes 등 다중 LLM 백엔드 에이전트 전반에 걸쳐 장시간 수행되는 작업(코드 생성, 리팩토링, 보안 검토 등)을 조정, 격리 및 감사할 수 있도록 설계되었습니다.
|
||||
Herdr와 MQTT 브로커를 기반으로 구축된 고신뢰성 **다중 에이전트 오케스트레이션 및 메시징 백플레인** 프레임워크입니다. `claude`, `agy`, `hermes`, `grok`, `opencode` 등 다중 LLM 백엔드 에이전트 전반에 걸쳐 장시간 수행되는 작업(코드 생성, 리팩토링, 보안 검토 등)을 조정, 격리 및 감사할 수 있도록 설계되었습니다.
|
||||
|
||||
[](VERSIONS.md)
|
||||
|
||||
---
|
||||
|
||||
@@ -9,10 +11,10 @@ Herdr와 MQTT 브로커를 기반으로 구축된 고신뢰성 **다중 에이
|
||||
최근의 에이전트 워크플로우는 세션 타임아웃, 프로세스 격리 부재, 터미널 뷰포트 잘림(스크롤백 한계로 인한 디버그 로그 유실), 복잡한 동시성 경쟁 등의 문제를 자주 겪습니다.
|
||||
|
||||
**herdr-agent-orchestration**은 다음과 같은 솔루션을 통해 이를 해결합니다:
|
||||
1. **Herdr 기반 프로세스 격리:** 개별적으로 격리된 herdr 환경 내부에 에이전트 CLI 세션을 띄워, 백그라운드에서 끊김 없이 장시간 작업이 영속되도록 보장합니다.
|
||||
1. **Herdr 기반 프로세스 격리:** 개별적으로 격리된 herdr 환경 내부에 에이전트 CLI 세션을 띄워, 백그라운드에서 끊김 없이 장시간 작업이 영속되도록 보장합니다. 백그라운드 데몬 서버는 독립된 OS 세션/프로세스 그룹(`start_new_session=True`)으로 분리되어 부모 셸의 시그널 브로드캐스트로부터 안전하게 격리됩니다.
|
||||
2. **비동기 이벤트 기반 아키텍처:** MQTT 브로커를 메시징 백플레인으로 활용하여, 에이전트 간 상태 전이 단계(`started`, `progress`, `completed`, `error`)를 긴밀하게 제어 및 조정합니다.
|
||||
3. **Multi-Agent Mux (MAM):** 파일 기반의 어드바이저리 락(`fcntl`) 및 SQLite WAL 데이터베이스(`.mam/agent-sessions.db`)를 결합하여, 동시성 작업 선점 경쟁을 방지하고 에이전트 세션의 라이프사이클을 드리프트 없이 관리합니다.
|
||||
4. **리뷰어 기반 고신뢰 검증 루프:** Worker 에이전트가 구현한 코드 변경 사항에 대해 상이한 강점을 지닌 전문 검증 에이전트(예: 논리 흐름을 정밀 검토하는 Claude, 셸 문법 및 안전성을 빠르게 확인하는 Hermes)들로부터 최종 `PASS` 판정을 획득한 뒤 머지하도록 교차 검증 루프를 자동화합니다.
|
||||
4. **리뷰어 기반 고신뢰 검증 루프:** Worker 에이전트가 구현한 코드 변경 사항에 대해 상이한 강점을 지닌 전문 검증 에이전트(Claude, Hermes, Grok, OpenCode 등)들로부터 최종 `PASS` 판정을 획득한 뒤 머지하도록 교차 검증 루프를 자동화합니다.
|
||||
|
||||
---
|
||||
|
||||
@@ -22,7 +24,7 @@ Herdr와 MQTT 브로커를 기반으로 구축된 고신뢰성 **다중 에이
|
||||
|
||||
* **`multi-agent-mux-create`**: 격리된 herdr 세션을 생성하고 특정 에이전트 CLI를 백그라운드에서 구동합니다. 프로세스 PID 캡처, 메타데이터 레지스트리 업데이트 및 에이전트 인증 검증을 처리합니다.
|
||||
* **`multi-agent-mux-stop`**: 에이전트 CLI 세션을 정상 종료 키 입력(`/exit` 또는 `Exit`)을 통해 안전하게 닫고, 격리된 대화 히스토리 및 데이터베이스 로그를 삭제(purge)하는 클린업 작업을 수행합니다.
|
||||
* **`multi-agent-mux-resume`**: 디스크 또는 캐시에서 특정 워크스페이스의 세션 UUID를 조회하여 기존 대화 상태(`claude -r <uuid>` 또는 `hermes --resume <uuid>`) 그대로 세션을 복구하고 재개합니다.
|
||||
* **`multi-agent-mux-resume`**: 디스크 또는 캐시에서 특정 워크스페이스의 세션 UUID를 조회하여 기존 대화 상태(`claude -r <uuid>`, `agy --conversation <uuid>`, `hermes --resume <uuid>`, `grok --resume <uuid>`, `opencode --session <uuid>`) 그대로 세션을 복구하고 재개합니다.
|
||||
* **`multi-agent-mux-status`**: 활성화된 모든 세션의 실시간 작동 상태를 쿼리하여 PID 정합성, 실행 명령 포맷, herdr 실제 상태와 데이터베이스 간의 동기화 드리프트를 감지합니다.
|
||||
* **`multi-agent-mux-monitor`**: 백그라운드 Reconcile 프로세스로 실행되어, 실시간 herdr 세션 변화를 모니터링하고 `.mam/agent-sessions.yaml` 메타데이터 파일에 상태를 동기화합니다.
|
||||
* **`multi-agent-mux-delegate-job`**: 태스크를 비동기식 독립 잡으로 위임 및 관리하는 핵심 모듈입니다:
|
||||
@@ -30,6 +32,8 @@ Herdr와 MQTT 브로커를 기반으로 구축된 고신뢰성 **다중 에이
|
||||
* `job_subscriber.py`: MQTT 백플레인 채널을 구독하여 실시간 상태 이벤트를 수집하고 이를 감사 로그(audit trail)에 기록합니다.
|
||||
* `publish_event.py`: 실행 상태 전환 및 세부 에러 내용을 워크스페이스 스크립트에서 백플레인으로 발행합니다.
|
||||
* `mqtt_common.py`: 브로커 접속 규칙, 크레덴셜 인증 및 HMAC 서명 기능을 공통 관리합니다.
|
||||
* **`multi-agent-mux-loop`**: Planner, Creator, Reviewer 3자 간의 자율적인 계획-실행-교차검증 반복 순환 루프를 구동합니다.
|
||||
* **`multi-agent-mux-orc-onboard`**: 오케스트레이터 UUID를 레지스트리에 격리 등록하여 서브 에이전트 자동 탐색 오염을 방지합니다.
|
||||
|
||||
---
|
||||
|
||||
@@ -111,7 +115,7 @@ sequenceDiagram
|
||||
Note over W: 코드 변경 및 자체 검증 수행
|
||||
W->>M: 'completed' (또는 'error') 발행
|
||||
PM->>R: 병렬 리뷰 요청 (Diff 제공)
|
||||
Note over R: 에이전트 교차 검증 (Claude, Hermes)
|
||||
Note over R: 에이전트 교차 검증 (Claude, Hermes, Grok, OpenCode)
|
||||
alt 리뷰 피드백 (NOT PASS)
|
||||
R->>PM: NOT PASS (대안 코드 블록과 함께 피드백 전달)
|
||||
Note over PM: PM 직접 수정 또는 다시 위임 결정
|
||||
@@ -147,9 +151,11 @@ sequenceDiagram
|
||||
│ ├── multi-agent-mux-resume/
|
||||
│ ├── multi-agent-mux-status/
|
||||
│ ├── multi-agent-mux-monitor/
|
||||
│ └── multi-agent-mux-delegate-job/
|
||||
│ ├── requirements.txt # 파이썬 의존성 패키지 선언
|
||||
│ └── scripts/ # 파이썬 기반 백플레인 구현체
|
||||
│ ├── multi-agent-mux-delegate-job/
|
||||
│ │ ├── requirements.txt # 파이썬 의존성 패키지 선언
|
||||
│ │ └── scripts/ # 파이썬 기반 백플레인 구현체
|
||||
│ ├── multi-agent-mux-loop/
|
||||
│ └── multi-agent-mux-orc-onboard/
|
||||
├── .mam/ # Multi-Agent Mux 메타데이터 (git-ignored)
|
||||
│ ├── agent-sessions.db # SQLite WAL 세션 데이터베이스
|
||||
│ ├── agent-sessions.yaml # 텍스트 형식의 세션 레지스트리 스냅샷
|
||||
|
||||
@@ -1,6 +1,8 @@
|
||||
# herdr-agent-orchestration
|
||||
|
||||
An advanced, high-reliability **Multi-Agent Orchestration & Messaging Backplane** framework built on Herdr and MQTT. It is designed to coordinate, isolate, and audit long-running agent tasks (such as code generation, refactoring, and security reviews) across multiple LLM backend clients (e.g., Claude, Hermes).
|
||||
An advanced, high-reliability **Multi-Agent Orchestration & Messaging Backplane** framework built on Herdr and MQTT. It is designed to coordinate, isolate, and audit long-running agent tasks (such as code generation, refactoring, and security reviews) across multiple LLM backend clients (`claude`, `agy`, `hermes`, `grok`, `opencode`).
|
||||
|
||||
[](VERSIONS.md)
|
||||
|
||||
---
|
||||
|
||||
@@ -9,10 +11,10 @@ An advanced, high-reliability **Multi-Agent Orchestration & Messaging Backplane*
|
||||
Modern agentic workflows often suffer from session timeout, lack of process isolation, terminal viewport truncation (scrollback limits), and complex concurrency issues.
|
||||
|
||||
**herdr-agent-orchestration** addresses these problems by providing:
|
||||
1. **Herdr-based Process Isolation:** Spawning LLM client sessions inside dedicated, isolated herdr environments to support persistent background runs.
|
||||
1. **Herdr-based Process Isolation:** Spawning LLM client sessions inside dedicated, isolated herdr environments to support persistent background runs. Background daemon servers detach into their own OS session/process group (`start_new_session=True`), ensuring they survive signal broadcasts to the parent shell.
|
||||
2. **Asynchronous Event-Driven Architecture:** Leveraging an MQTT broker as a message backplane to coordinate state transitions (`started`, `progress`, `completed`, `error`) between collaborating agents.
|
||||
3. **Multi-Agent Mux (MAM):** Combining local file-based locks (fcntl) and an ACID-compliant SQLite WAL database (`.mam/agent-sessions.db`) to manage concurrent job claims and track running agent sessions without drift.
|
||||
4. **Automated Review & Quality Loop:** Implementing parallel reviewer loops where worker agents must receive a `PASS` rating from various specialized verification agents (e.g., Claude for high-level logic, Hermes for shell syntax/safety) before merging code.
|
||||
4. **Automated Review & Quality Loop:** Implementing parallel reviewer loops where worker agents must receive a `PASS` rating from various specialized verification agents (e.g., Claude, Hermes, Grok, OpenCode) before merging code.
|
||||
|
||||
|
||||
---
|
||||
@@ -40,7 +42,7 @@ All orchestration functionalities are structured under the `.agents/skills/` dir
|
||||
|
||||
* **`multi-agent-mux-create`**: Spawns isolated herdr sessions running specified agent CLI wrappers. It captures system processes, updates metadata registries, and enforces authentication checks.
|
||||
* **`multi-agent-mux-stop`**: Gracefully terminates agent CLI sessions (using key macros like `/exit` or `Exit`) and handles disk purge operations (removing conversation JSON files and SQLite logs for deleted workspaces).
|
||||
* **`multi-agent-mux-resume`**: Restores stopped sessions by resolving workspace UUIDs from disk or cache, and invokes the underlying agent using session-resume parameters (e.g., `claude -r <uuid>` or `hermes --resume <uuid>`).
|
||||
* **`multi-agent-mux-resume`**: Restores stopped sessions by resolving workspace UUIDs from disk or cache, and invokes the underlying agent using session-resume parameters (e.g., `claude -r <uuid>`, `agy --conversation <uuid>`, `hermes --resume <uuid>`, `grok --resume <uuid>`, or `opencode --session <uuid>`).
|
||||
* **`multi-agent-mux-status`**: Queries the running states of all active sessions, detecting PID mismatches, command signatures, and drifts between actual herdr instances and the registry database.
|
||||
* **`multi-agent-mux-monitor`**: A long-running reconcile worker that dynamically monitors herdr sessions and synchronizes states to `.mam/agent-sessions.yaml`.
|
||||
* **`multi-agent-mux-delegate-job`**: The core asynchronous task distribution module containing:
|
||||
@@ -48,6 +50,8 @@ All orchestration functionalities are structured under the `.agents/skills/` dir
|
||||
* `job_subscriber.py`: Connects to the MQTT backplane, captures live events, and appends them to audit trails.
|
||||
* `publish_event.py`: Emits execution status transitions and error details from workspace scripts.
|
||||
* `mqtt_common.py`: Manages connection policies, authentication, and HMAC signing.
|
||||
* **`multi-agent-mux-loop`**: Autonomous planning-execution-review orchestration loop across Planner, Creator, and Reviewers until unanimous consensus.
|
||||
* **`multi-agent-mux-orc-onboard`**: Helper to register and isolate orchestrator session UUIDs to prevent sub-agent discovery capture.
|
||||
|
||||
---
|
||||
|
||||
@@ -129,7 +133,7 @@ sequenceDiagram
|
||||
Note over W: Implement & verify code
|
||||
W->>M: Publish 'completed' (or 'error')
|
||||
PM->>R: Request parallel reviews (Provide Diff)
|
||||
Note over R: Parallel analysis (Claude, Hermes)
|
||||
Note over R: Parallel analysis (Claude, Hermes, Grok, OpenCode)
|
||||
alt Review Feedback (NOT PASS)
|
||||
R->>PM: NOT PASS (Feedback with code blocks)
|
||||
Note over PM: Apply fixes or re-delegate
|
||||
@@ -165,9 +169,11 @@ To ensure communication integrity across public MQTT brokers, the backplane inte
|
||||
│ ├── multi-agent-mux-resume/
|
||||
│ ├── multi-agent-mux-status/
|
||||
│ ├── multi-agent-mux-monitor/
|
||||
│ └── multi-agent-mux-delegate-job/
|
||||
│ ├── requirements.txt # Python dependency declaration
|
||||
│ └── scripts/ # Core backplane implementation (Python)
|
||||
│ ├── multi-agent-mux-delegate-job/
|
||||
│ │ ├── requirements.txt # Python dependency declaration
|
||||
│ │ └── scripts/ # Core backplane implementation (Python)
|
||||
│ ├── multi-agent-mux-loop/
|
||||
│ └── multi-agent-mux-orc-onboard/
|
||||
├── .mam/ # Multi-Agent Mux metadata (git-ignored)
|
||||
│ ├── agent-sessions.db # SQLite WAL session database
|
||||
│ ├── agent-sessions.yaml # Human-readable session registry
|
||||
|
||||
+1
-1
@@ -1,6 +1,6 @@
|
||||
# 🛠️ Multi-Agent Mux (MAM) 설치 및 적용 가이드
|
||||
|
||||
MAM은 단일 워크스페이스 상에서 복수의 에이전트(Claude, Agy, Hermes, Grok 등)들이 서로의 상태를 오염시키지 않고 협업할 수 있도록 프로세스 격리 및 라이프사이클 관리를 제공하는 프레임워크입니다.
|
||||
MAM은 단일 워크스페이스 상에서 복수의 에이전트(Claude, Agy, Hermes, Grok, OpenCode 등)들이 서로의 상태를 오염시키지 않고 협업할 수 있도록 프로세스 격리 및 라이프사이클 관리를 제공하는 프레임워크입니다.
|
||||
|
||||
이 가이드는 기존의 다른 프로젝트/레포지토리에 MAM을 신속하게 도입하고 적용하는 절차를 설명합니다.
|
||||
|
||||
|
||||
@@ -1,76 +0,0 @@
|
||||
# Multi-Agent Mux (MAM) 에이전트 생성 이슈 분석 및 수정 보고서
|
||||
|
||||
## 1. 개요 (Overview)
|
||||
|
||||
MAM(Multi-Agent Mux) 오케스트레이션 환경에서 `opencode` 리뷰어 에이전트(`reviewer-opencode-01`) 생성 과정에서 발생했던 TUI 준비 감지 대기 문제와 `lib.sh` 런타임 제어 보완 사항에 대한 기술 분석 및 수정 내역입니다.
|
||||
|
||||
---
|
||||
|
||||
## 2. 세부 문제 원인 및 수정 내역
|
||||
|
||||
### 2.1. OpenCode TUI 감지 토큰 불일치 (핵심 원인)
|
||||
|
||||
- **대상 파일:** [`.agents/skills/lib_py/agents/adapters/opencode.py`](.agents/skills/lib_py/agents/adapters/opencode.py#L22-L26)
|
||||
- **원인 분석:**
|
||||
- OpenCode CLI가 실행되면 터미널 상단 로고가 일반 텍스트가 아닌 **ASCII 특수문자 블록(`█▀▀█...`)**으로 렌더링됩니다.
|
||||
- 기존 어댑터의 `ready_tokens` 설정값이 단순히 `'OpenCode|Chat'`으로만 지정되어 있어, 프로세스가 정상적으로 기동되었음에도 `wait_for_tui_ready` 함수가 화면 텍스트를 감지하지 못하고 30초 대기(타임아웃)에 빠졌습니다.
|
||||
|
||||
#### 🔧 코드 변경 사항 (Diff)
|
||||
```python
|
||||
# 수정 전 (opencode.py)
|
||||
@property
|
||||
def ready_tokens(self) -> str:
|
||||
return 'OpenCode|Chat'
|
||||
|
||||
# 수정 후 (opencode.py)
|
||||
@property
|
||||
def ready_tokens(self) -> str:
|
||||
return 'OpenCode|Chat|Ask anything|tab agents|ctrl\\+p|Build auto|commands'
|
||||
```
|
||||
|
||||
- **개선 효과:**
|
||||
- 실제 OpenCode CLI의 화면 요소인 프롬프트 문구(`Ask anything...`), 모드 표시(`Build auto`), 단축키 힌트(`tab agents`, `ctrl+p`, `commands`)를 즉시 감지하여 1초 이내에 정상 준비 완료로 판정합니다.
|
||||
|
||||
---
|
||||
|
||||
### 2.2. Herdr 런타임 심(Shim) 및 세션 제어 보완 (`lib.sh`)
|
||||
|
||||
MAM 스킬 업데이트 후 발생할 수 있는 Herdr 통신 및 모듈 임포트 문제를 함께 보완했습니다.
|
||||
|
||||
#### ① Shim 래퍼 내 `PYTHONPATH` 누락 보완
|
||||
- **대상 파일:** [`.agents/skills/lib.sh`](.agents/skills/lib.sh#L154-L160)
|
||||
- **원인:** Herdr translation shim(`.mam/shim/herdr`) 내부에서 `python3 -m lib_py.layout` 또는 `lib_py.agents`를 호출할 때 `PYTHONPATH`가 지정되지 않아 `ModuleNotFoundError: No module named 'lib_py'`가 발생할 수 있던 문제.
|
||||
- **수정 내용:** Shim 템플릿 헤더에 `export PYTHONPATH="$_SKILL_DIR:${PYTHONPATH:-}"` 자동 주입 추가.
|
||||
|
||||
```bash
|
||||
# lib.sh 헤더 주입 코드
|
||||
_SHIM_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
||||
_SKILL_DIR="$(cd "$_SHIM_DIR/../../.agents/skills" 2>/dev/null && pwd || true)"
|
||||
[ -n "$_SKILL_DIR" ] && export PYTHONPATH="$_SKILL_DIR:${PYTHONPATH:-}"
|
||||
```
|
||||
|
||||
#### ② `herdr agent start` 타임아웃 및 실행 폴백 추가
|
||||
- **대상 파일:** [`.agents/skills/lib.sh`](.agents/skills/lib.sh#L807-L822)
|
||||
- **원인:** TUI 렌더링에 1~2초 지연이 발생하여 Herdr CLI가 `timed out waiting for agent startup`을 반환할 경우, 이를 실패로 간주하고 생성 중이던 페인을 강제 파괴하던 문제.
|
||||
- **수정 내용:** 타임아웃 발생 시에도 프로세스가 살아있으면 성공으로 처리하고, 미기동 시 `pane send-text`로 에이전트 실행 명령을 전송하는 폴백 로직 추가.
|
||||
|
||||
#### ③ 페인 ID 직접 전달 및 워크스페이스 라벨 매칭 지원
|
||||
- **대상 파일:** [`.agents/skills/lib.sh`](.agents/skills/lib.sh#L343-L375)
|
||||
- **원인:** Herdr 내부 워크스페이스 ID(`wF`)와 사용자가 지정한 라벨(`mam-agents`) 간의 매칭이 어긋날 경우 페인 검색에 실패하는 문제.
|
||||
- **수정 내용:** 대상이 이미 페인 ID 형식(`wN:pM`)인 경우 즉시 반환하고, `workspace_id` 외에 `label` 및 `workspace_label`도 함께 매칭하도록 확장.
|
||||
|
||||
---
|
||||
|
||||
## 3. 최종 검증 결과
|
||||
|
||||
수정 사항 적용 후 `reviewer-opencode-01` 세션 생성이 1초 이내에 정상 완료되었으며, graceful stop 시 고유 세션 ID까지 안전하게 보존되었습니다.
|
||||
|
||||
| 세션명 | 에이전트 | 할당 역할 | 캡처된 고유 대화 ID (UUID) | 복원 가능 상태 |
|
||||
| :--- | :---: | :---: | :--- | :---: |
|
||||
| **`planner-reviewer-claude-01`** | `claude` | `planner, reviewer` | `43c3110e-7bdd-4d3c-b36e-cfba94cd1f04` | ✅ `resumable` |
|
||||
| **`reviewer-creator-grok-01`** | `grok` | `reviewer, creator` | `18f3e028-c8fe-40c6-ae4f-20d513582e93` | ✅ `resumable` |
|
||||
| **`creator-agy-01`** | `agy` | `creator` | `f9744f88-2e1f-489f-a621-1679a4018fdd` | ✅ `resumable` |
|
||||
| **`reviewer-opencode-01`** | `opencode` | `reviewer` | `ses_fb2098b87ffenhiEntaW2HMtp7` | ✅ `resumable` |
|
||||
|
||||
---
|
||||
*작성 일시: 2026-08-29 (UTC)*
|
||||
Reference in new issue
Block a user