38 lines
5.8 KiB
Markdown
38 lines
5.8 KiB
Markdown
# Ariweb Suite 개발 지시 — 작성자: Oz · v0.3.2
|
|
|
|
**작성자:** Oz
|
|
**작성일:** 2026-10-29
|
|
**이전 버전:** v0.3.1(서버 설치 CLI 자동 탐색, Oz) · v0.3.0(HAL AI 채팅룸, Oz) · v0.2.1 · v0.2.0 · v0.1.4 · v0.1.1
|
|
**이번 개정:** HAL AI 연동의 **편의성**(OAuth 화면 자동, CLI 로그인용 텍스트 셸, 사전 안내, 기본 공급자 4종 + 기타)과 **도구 기본 설정·인증/승인 요청**. HAL 0.3.1 → **0.3.2**. HAL 에만 적용하며 이전 지시의 모든 기준은 그대로다.
|
|
|
|
## 개정 이력
|
|
- **v0.3.0 · Oz · 2026-10-29:** AI 채팅룸(통합·개별), 연결(로그인·OAuth·API 키), 스킬·도구·MCP.
|
|
- **v0.3.1 · Oz · 2026-10-29:** 서버 설치 CLI 자동 탐색·연결 가능화.
|
|
- **v0.3.2 · Oz · 2026-10-29:** 연동 편의성(OAuth 자동 화면·텍스트 셸·사전 안내·공급자 프리셋) + 도구 기본 설정·승인 요청.
|
|
|
|
## 1. 사용자 요구(Oz 원문, 약화 금지)
|
|
1. **AI 연동 기능 편의성 추가.** OAuth 연동 시 필요한 연동 화면을 자동으로 띄우도록 해야 한다. CLI 로그인을 사용하는 경우라면 text shell 화면을 제공하여 화면에서 필요한 작업을 수행하게 해야 한다. 이 작업들이 자동으로 진행되어야 하며, 사전에 필요한 작업 내용을 안내하도록 만든다. API 연동의 경우 Claude, ChatGPT, Gemini, OpenRouter 는 기본 서비스 업체로 선택할 수 있게 하고 그 외 API 서비스 업체를 통한 연동도 지원할 수 있도록 개선한다. 이상과 같이 HAL 에 AI 를 연동하는 작업을 진행하고, 작업 결과를 소스에 반영한 후 `https://hal21.ariweb.net` 에 배포한다.
|
|
2. **LLM 과 도구 연결에 대한 기본 설정 제공 및 인증 기능 제공.** HAL 의 운영과 관리를 위해 생성된 각종 도구와 스킬은 LLM 연동 시 즉시 활용 가능하도록 미리 설정을 준비하고 제공한다. 이 도구들 중에서 인증이나 승인이 필요한 경우 필요한 인증/승인을 요청할 수 있게 하는 기능도 함께 준비한다.
|
|
|
|
## 2. 필수 동작(계약)
|
|
1. **공급자 프리셋**: Claude(Anthropic) · ChatGPT(OpenAI) · Gemini(Google, 자체 API) · OpenRouter(OpenAI 호환, 기본 주소 고정) 를 기본 선택지로, "기타 API 서비스(OpenAI 호환)" 는 기본 주소를 필수로 받아 연동한다. 공급자·인증 방식마다 **사전 준비 안내**(키 발급 주소, OAuth 리디렉션 URI 와 HAL 콜백 주소, CLI 로그인 절차)를 화면에 보인다.
|
|
2. **OAuth 자동**: OAuth 연결을 저장하면 공급자 로그인 창(팝업)을 자동으로 열고, 승인 뒤 완료 페이지가 스스로 닫히며 부모 창이 모델 확인까지 잇는다. Gemini 는 Google 끝점·scope 프리셋(client id/secret 만), OpenRouter 는 PKCE 프리셋(설정값 없음, 승인 뒤 키 자동 발급·Vault 저장). 실패도 완료 페이지로 알린다.
|
|
3. **텍스트 셸**: 로컬 CLI(claude·codex)의 login·logout·상태·버전만 PTY 로 실행해 화면에서 출력을 보고 입력(코드)을 보낸다. 로컬 CLI 연결을 저장·확인했을 때 로그인이 안 되어 있으면 login 셸을 **자동으로 연다**. 시작은 재인증 필요, 임의 명령·다른 실행 파일 금지, 입력 미저장.
|
|
4. **도구 기본 설정**: 연결마다 도구 정책(`all`·`read_write`·`read_only`·`custom`·`none`)이 있고 기본은 전부 켜짐. 엔진은 켜진 도구만 선언한다. 로컬 CLI 연결에는 HAL MCP 서버 설정이 자동으로 붙어 CLI 가 HAL 도구를 바로 쓴다. 외부 클라이언트용 MCP 설정 스니펫을 제공한다.
|
|
5. **승인 요청**: MCP 경로의 쓰기·고위험 도구 호출은 실행하지 않고 통합 방에 승인 요청(제안 카드)으로 올라가며 `actionId` 를 돌려준다. `hal_action_status`·`hal_actions_pending` 으로 상태를 본다. 승인은 기존 규칙(재인증, 고위험 3단계)으로만 가능하다.
|
|
|
|
## 3. 보안 불변조건
|
|
- 텍스트 셸은 (CLI 종류, 명령 이름)만 받고 허용표의 인자 배열을 탐색된 절대 경로로 실행한다. HAL 환경 변수를 넘기지 않는다. 입력은 저장·감사하지 않고, 출력은 메모리에만 둔다.
|
|
- OAuth 완료 페이지는 외부 스크립트 없이 같은 출처로만 `postMessage` 한다. 토큰·키는 Vault 에만. state 는 해시·1회용·10분, 시작 운영자 = 콜백 운영자.
|
|
- 승인 요청은 제안일 뿐 실행이 아니다. 승인 라우트·재인증·3단계 확인·CSRF·Agent 경계는 0.3.0 그대로. 도구 정책으로 꺼진 도구는 선언도 실행도 하지 않는다.
|
|
|
|
## 4. TDD·검증
|
|
- `test/hal-ai-032.test.mjs` 를 먼저 쓰고 RED 를 확인한 뒤 구현: 프리셋·안내·OpenRouter 주소·기타 주소 필수·Gemini 모델 목록·도구 왕복 / OAuth 생성 → next · 완료 페이지 · Gemini 프리셋 · OpenRouter PKCE / 텍스트 셸(재인증·허용 명령·PTY 출력·입력·종료·강제 종료·목록) / 도구 정책(프리셋·custom 검증·선언 필터)·CLI MCP 주입·MCP 설정 API / MCP 승인 요청(제안·상태 도구·콘솔 승인·3단계·거부) / 화면·버전·문서.
|
|
- 기존 `test/hal-ai.test.mjs`(12) 유지. targeted 뒤 전체 Suite. 배포 뒤 bear read-back.
|
|
|
|
## 5. 버전·배포
|
|
- HAL 0.3.2: package.json·README·VERSION_HISTORY 0.3.2 절·docs/HAL-AI.md §7. 커밋 → push → main 병합 → 깨끗한 main 빌드·verify → bear HAL 만 배포(백업·stage·register-release --approve·bootstrap-release·전환·재시작) → `/api/health`·화면·MCP 설정 read-back. 다른 모듈은 배포하지 않는다.
|
|
|
|
## 6. 완료 조건
|
|
변경 파일, RED/GREEN·전체 테스트, 커밋·병합 커밋, artifact sha256, 배포 read-back, 운영자 조치(claude login 등), 알려진 제한을 보고한다.
|