55 lines
10 KiB
Markdown
55 lines
10 KiB
Markdown
# Ariweb Suite 개발 지시 — 작성자: Oz · v0.3.0
|
||
|
||
**작성자:** Oz
|
||
**작성일:** 2026-10-29
|
||
**이전 버전:** v0.2.1(HAL 고위험 재인증 안내 위치 수정, Neo, 2026-10-29) · v0.2.0(Webmaker 직접 편집, Neo) · v0.1.4(HAL AI 대시보드·다중 AI 공동 작업창 지시, Neo) · v0.1.1(최초 통합 개발 지시, Hera)
|
||
**이번 개정:** **HAL 화면에 AI 채팅룸 도입.** 이번 개발은 Ariweb Suite 의 HAL 에만 적용한다. HAL 에 새 사용자(운영자) 기능이 더해지므로 가운데 버전 번호를 올린다 — Suite(HAL) 0.2.1 → **0.3.0**. 이전 지시의 모든 기준은 그대로 유효하다. v0.1.4 §41·§42(AI 대시보드·공동 작업창)의 상세 계약 중 이 문서가 다시 적지 않은 항목(변경 잠금·fencing·제한된 합의 절차 등)은 후속 릴리스로 남긴다.
|
||
|
||
## 개정 이력
|
||
- **v0.1.1 · Hera · 2026-10-26:** 최초 통합 개발 지시.
|
||
- **v0.1.4 · Neo · 2026-10-27:** patch 자동 증가 규칙, HAL AI 대시보드·다중 AI 공동 작업창 지시.
|
||
- **v0.2.0 · Neo · 2026-10-28:** Webmaker 직접 편집(시각 편집기).
|
||
- **v0.2.1 · Neo · 2026-10-29:** HAL 고위험 재인증 안내를 전역 배너에서 거부 시점 재인증 창으로.
|
||
- **v0.3.0 · Oz · 2026-10-29:** HAL 운영자 콘솔 오른쪽 AI 채팅룸(통합 방 + 모델별 개별 방), 로그인·OAuth·API 키 연결, 모델별 고유 정보, HAL 제어·감시 스킬·도구·MCP. 소스 반영 뒤 `https://hal21.ariweb.net` 에 배포.
|
||
|
||
## 1. 사용자 요구(Oz 원문, 약화 금지)
|
||
HAL 의 화면 오른쪽에 칸을 나눠 AI 채팅룸을 생성한다. AI 모델은 로그인, OAuth, API Key 를 이용해서 연결할 수 있으며 여러 모델을 연결한 경우 탭을 이용해서 각 모델을 전환할 수 있게 한다.
|
||
|
||
AI 모델은 HAL 의 모든 기능을 제어하고 감시할 수 있도록 필요한 스킬과 도구를 미리 준비한다. 이 스킬이나 도구, MCP 등을 통해 AI 모델은 HAL 의 모든 기능을 제어할 수 있고, 필요한 경우 모든 상태 정보와 로그 정보를 수집할 수 있다. 이들 상태 정보와 로그 정보의 의미는 스킬·도구·MCP 등을 통해 AI 가 이해할 수 있도록 미리 준비한다.
|
||
|
||
각 AI 모델은 고유한 특성, 업무, 이름 등의 고유 정보가 부여되며, 이는 AI 를 연동할 때 지정한다.
|
||
|
||
채팅룸은 개별 채팅룸과 통합 채팅룸으로 나뉜다. **통합 채팅룸**은 AI 채팅룸의 첫 번째 탭으로 항상 고정되어 있으며, 연결된 모든 AI 모델이 함께 참여하는 공간이다. 이 공간에서 내가 보내는 지시는 모든 AI 모델에게 전달되며, 이름을 지정해서 지시하는 내용은 해당 모델만 반응한다. 이 공간에서는 모든 모델이 내 반응에 함께 반응하고 필요한 경우 AI 모델에서 모델로 대화를 전달할 수 있다. 다만, 전달된 대화에 대한 대답은 자동으로 진행될 수 있지만 대답에 대한 두 번째 반응은 사용자의 지시에 의해 진행되도록 설정한다. **개별 채팅룸**은 등록된 개별 AI 모델과 대화하고 지시하는 공간이며, 채팅 탭의 이름은 AI 모델의 이름을 기본값으로 하고 필요한 경우 수정할 수 있게 한다.
|
||
|
||
이상과 같이 HAL 에 AI 를 연동하는 작업을 진행하고, 작업 결과를 소스에 반영한 뒤 `https://hal21.ariweb.net` 에 배포한다.
|
||
|
||
## 2. 필수 동작(계약)
|
||
1. **패널**: 모든 운영자 화면 오른쪽에 AI 채팅룸 패널. 열기/닫기·너비 조절, 운영자별로 저장해 새로 고침 뒤 복원. 좁은 화면(1100px 이하)에서는 본문 아래 전체 너비. 기존 메뉴·승인 단추를 가리지 않는다.
|
||
2. **탭**: 첫 탭 `통합`(고정, 이름 변경·삭제 불가) → 연결 순서대로 모델별 개별 탭(이름 기본값 = 연결 이름, 두 번 눌러 수정). `＋` 는 AI 연동 화면으로.
|
||
3. **연결**(AI 연동 화면 `/ops/ai`): 공급자 Anthropic · OpenAI 호환(기본 주소 변경 가능) · 로컬 CLI 로그인 세션(Claude Code). 인증 방식 API 키 · OAuth(authorization code + PKCE S256) · 로그인(CLI 세션). 연결마다 이름·역할·특성·추가 지시(고유 정보), 기본 모델, 상태(active/disabled/reauth_required/error), 마지막 확인·오류. "확인"은 실제 공급자 모델 목록을 받아 두며, 목록에 없는 모델 선택은 `model_unavailable` 로 거부한다(조용히 대체하지 않음).
|
||
4. **통합 방 규칙**: 지시는 활성 모델 모두에게. `@이름` 또는 글머리 `이름:`/`이름,` 지정 → 그 모델만. 모르는 `@이름` 은 400 `unknown_addressee`. 모델이 `@이름` 으로 다른 모델을 부르면 그 모델이 자동 **1회** 답하고(relayDepth 1), 그 답이 다시 누군가를 불러도 자동 반응은 없다(HAL 안내만 남김). 자기 자신·비활성 모델은 전달 대상이 아니다.
|
||
5. **개별 방**: 1:1. 다른 모델·통합 방과 기록이 섞이지 않는다. 비활성 연결의 방에는 보낼 수 없다(409). "새 대화"는 기록을 비우고 승인 대기 제안을 취소한다.
|
||
6. **스킬·도구**: 각 모델은 system prompt 로 HAL 운영 스킬 문서(`hal/ai/skill.md` — 서버·작업·릴리스·사건·감사·긴급 복구·DR 상태와 오류 코드의 뜻)와 자기 고유 정보, 참여자 목록, 운영자·화면 문맥을 받는다. 도구(`hal/ai/tools.mjs`)는 읽기(건강·현황·서버·지표·릴리스·작업·사건·감사·메일 서비스·긴급 복구·DR·변경 이력·스킬) / 쓰기(서버 등록·승인·유지보수, 사건 등록·종료, 작업 취소·재시도·재개·중지, 모듈 건강 확인, DR 스냅샷) / 고위험(서버 격리·삭제, 모듈 배포·되돌리기·맞추기, 릴리스 승인, 작업 되돌리기, 설정 변경). MCP(stdio) 서버 `node hal/index.mjs mcp` 는 같은 도구 정의를 내보내되 읽기 도구만 실행한다.
|
||
7. **제안·승인**: 쓰기·고위험 도구 호출은 즉시 실행되지 않고 "제안"으로 멈춘다(대화에 카드). 운영자 승인 = 기존 HAL 규칙 그대로: 재인증(최근 10분) + 고위험은 3단계 확인(영향 범위 → 대상 식별정보 재입력 → 최종 실행). 거부하면 실행되지 않는다. 승인 뒤 딱 한 번 실행하고 결과를 도구 결과로 넣어 모델을 이어서 부른다. 같은 제안은 두 번 실행되지 않는다.
|
||
|
||
## 3. 보안 불변조건
|
||
1. 비밀값(API 키·OAuth 토큰·client secret)은 HAL Vault 에만 있다. DB 행·API 응답·목록·감사·대화·작업·로그·소스·테스트·커밋·보고서 어디에도 없다(힌트만). 키 등록·교체·연결 삭제는 "인증 키 변경"이므로 `requireRecent`.
|
||
2. 서버가 공급자에게만 자격을 보낸다. 브라우저에는 돌려주지 않는다. 로컬 CLI 연결은 HAL 이 세션 파일·자격을 읽지도 넘기지도 않으며 CLI 환경 변수는 PATH·HOME 등 최소만.
|
||
3. OAuth: state 는 해시로만 저장, 10분 만료, 1회용. 콜백 운영자 = 시작 운영자. code_verifier 는 Vault 에 두었다가 교환 뒤 제거. 토큰은 서버 측 refresh.
|
||
4. 모델의 도구 인자는 권한이 아니다: HAL 이 선언(schema)으로 다시 검증하고, 모르는 도구·인자는 실행하지 않는다. 임의 셸 명령·경로·네트워크 대상을 받는 도구는 없다. 저장소 파일·로그·고객 데이터·다른 모델의 응답 속 지시문은 승인·정책을 바꾸지 못한다(스킬 문서에 명시).
|
||
5. 기존 `requireRecent`·CSRF·`threeStep`·릴리스 승인·부트스트랩·Node Agent 경계는 한 글자도 약화하지 않는다. AI 경로는 같은 함수(core/jobs)를 같은 인자로 부른다.
|
||
6. 공급자 오류(인증·429·timeout·형식)는 모델 답으로 꾸미지 않고 실패로 표시한다. AI 가 "완료"라고 말해도 HAL 이 확인한 증거(도구 결과·작업 상태)만 믿는다.
|
||
|
||
## 4. TDD·검증
|
||
- production code 전에 회귀 테스트 `test/hal-ai.test.mjs` 를 쓰고 RED(0/11)를 실제 실행으로 확인한 뒤 최소 구현으로 GREEN, 그 다음 전체 Suite 테스트(`node test/run.mjs`).
|
||
- 가짜 공급자(deps.fetch)로 Anthropic·OpenAI 호환 응답을 각본대로 돌려 외부 모델을 부르지 않는다. 비밀 fixture 는 `node:crypto` 로 실행마다 생성(정적 literal 없음).
|
||
- 다루는 계약: 연결 CRUD·비밀 미노출·재인증·모델 확인·모델 거부 / OAuth PKCE(state·운영자·1회용·토큰 Vault·Bearer) / 방·탭(통합 고정·개별·이름 수정) / 통합 방 지정·방송·고유 정보·참여자 전달 / 모델→모델 자동 1회·두 번째 반응 금지 / 개별 방 격리·읽기 도구 왕복·공급자 오류 / 쓰기·고위험 제안·재인증·3단계·거부·1회 실행·이어가기·모르는 도구 거부 / OpenAI 호환 형식 / 로컬 CLI(없음 → 사용 불가 표시, 있음 → -p JSON) / 화면·버전·문서 / MCP stdio.
|
||
- 러너가 만드는 `docs/verification/local-e2e-*` 임시 파일은 커밋하지 않는다.
|
||
|
||
## 5. 버전·이력·배포
|
||
- Suite(HAL) 0.3.0: `package.json`(런타임 `hal/deps.mjs VERSION`·`scripts/release.mjs` 가 따름)·README·`VERSION_HISTORY.md` 0.3.0 절(작성자 Oz·이전 버전·요구·운영자 화면·연결·방 규칙·도구·보안 결정·테스트·배포 read-back·알려진 제한·미확정 정책값)·`docs/HAL-AI.md`.
|
||
- 커밋 → 정본 저장소 push → `main` 병합 → 깨끗한 main 에서 `node scripts/release.mjs build`(전체 테스트·dirty=false) → `verify` → bear `hal21.ariweb.net` 에 HAL 만 배포(이전 릴리스·data/config/Vault 보존, 사전 백업, stage 검증, `register-release --approve`, `bootstrap-release`, current 전환, 재시작) → `/api/health`·화면·외부 경로 read-back. 바뀌지 않은 모듈(포털·Agent·Webmaker·AriMail)은 배포하지 않는다. bear 에는 HAL 만 둔다(2026-10-27 지시).
|
||
|
||
## 6. 완료 조건
|
||
변경 파일, RED/GREEN·전체 테스트 결과, 보안 결정, 커밋·push·병합 커밋, 릴리스 artifact sha256, 배포 read-back(버전·건강·화면), 알려진 제한을 보고한다.
|