36 lines
4.9 KiB
Markdown
36 lines
4.9 KiB
Markdown
|
# Ariweb Suite 개발 지시 — 작성자: Oz · v0.3.1
|
||
|
|
|
||
|
|
**작성자:** Oz
|
||
|
|
**작성일:** 2026-10-29
|
||
|
|
**이전 버전:** v0.3.0(HAL AI 채팅룸, Oz, 2026-10-29) · v0.2.1(HAL 고위험 재인증 안내 위치, Neo) · v0.2.0(Webmaker 직접 편집, Neo) · v0.1.4 · v0.1.1
|
||
|
|
**이번 개정:** HAL 0.3.0 의 로컬 CLI 연결이 bear(HAL 운영 서버)에 **이미 설치된 CLI 를 찾지 못하는 결함 수정**. 결함 수정이므로 끝 버전 번호만 올린다 — HAL 0.3.0 → **0.3.1**. HAL 에만 적용하며 이전 지시의 모든 기준은 그대로다.
|
||
|
|
|
||
|
|
## 개정 이력
|
||
|
|
- **v0.3.0 · Oz · 2026-10-29:** HAL 운영자 콘솔 AI 채팅룸(통합 방 + 개별 방), 모델 연결(로그인·OAuth·API 키), 스킬·도구·MCP.
|
||
|
|
- **v0.3.1 · Oz · 2026-10-29:** 서버 설치 CLI 자동 탐색·연결 가능화(Claude Code·Codex), 로그인 상태 표시.
|
||
|
|
|
||
|
|
## 1. 사용자 요구(Oz 원문, 약화 금지)
|
||
|
|
bear 서버(HAL 운영 서버)에 이미 CLI 가 설치되어 있는데 설치된 것을 확인하지 못하고 있습니다. 서버의 설치 상황을 점검해서 이미 설치된 것은 찾아서 연결 가능하게 수정하세요.
|
||
|
|
|
||
|
|
## 2. 점검(구현 전 실제 확인)
|
||
|
|
- 설치 위치: `~/.local/bin/claude`(Claude Code 2.1.312), `~/.local/bin/codex`(Codex 0.162.1). HAL 실행 계정의 로그인 셸 PATH 에는 있으나 **systemd 서비스 PATH 에는 `~/.local/bin` 이 없다** → 0.3.0 의 "PATH 의 claude" 탐색이 실패한 원인.
|
||
|
|
- 로그인: codex 는 ChatGPT 로 로그인됨(기본 모델 gpt-6.1-sol). claude 는 OAuth 세션 만료(`claude auth status` loggedIn=false) — 서버에서 `claude login` 필요.
|
||
|
|
- 유닛 샌드박스(ProtectSystem=strict)와 같은 조건에서 두 CLI 모두 실행 가능 → 유닛·권한 변경 없이 코드 수정으로 해결.
|
||
|
|
|
||
|
|
## 3. 필수 동작(계약)
|
||
|
|
1. HAL 이 서버에 설치된 CLI(claude·codex)를 **서비스 PATH 와 무관하게** 자동 탐색한다: 환경 변수(CLAUDE_BIN·CODEX_BIN) → HAL_CLI_DIRS → HOME 의 알려진 설치 위치(`~/.local/bin`, `~/.npm-global/bin`, `~/.claude/local`, `~/.codex/packages/standalone/current/bin`, `~/node_modules/.bin`) → `/usr/local/bin`·`/usr/bin` → PATH. 심볼릭 링크도 인정.
|
||
|
|
2. `GET /ops/api/ai/cli` 와 AI 연동 화면 "서버에서 찾은 CLI" 카드가 실행 파일·실제 경로·버전·로그인 상태(claude `auth status`, codex `login status`)·기본 모델·모델 목록(codex `~/.codex/models_cache.json`, 숨김 제외)과 탐색 위치를 보인다. "이 CLI 로 연결 추가"는 양식을 미리 채운다.
|
||
|
|
3. 연결은 `cli.tool`(claude|codex)만으로 만들 수 있고(경로 생략 → 탐색 결과), 모델을 비우면 CLI 기본 모델. "확인"은 탐색된 경로·버전·로그인 상태를 연결에 남기고, 로그인 안 됨이면 `cli_not_logged_in`(상태 `reauth_required`)과 "서버에서 `claude login`/`codex login`" 안내를 낸다. 실행 파일이 없으면 `cli_unavailable` 과 탐색 위치를 낸다. 확인 실패 응답은 메시지가 보이도록 5xx 가 아닌 424.
|
||
|
|
4. Codex 는 `codex exec --json -s read-only --skip-git-repo-check --ephemeral -C <임시 폴더> -m <모델> <프롬프트>` 로 실행하고 `item.completed(agent_message)` 를 답, `turn.completed.usage` 를 사용량으로 쓴다. Claude 는 기존 `-p --output-format json`. 인증 오류 결과는 모델 답으로 꾸미지 않는다.
|
||
|
|
5. HAL 은 CLI 의 세션 파일·자격을 읽지도 넘기지도 않는다. CLI 환경 변수는 HOME·PATH·LANG 등 최소. 절대 경로 실행 파일만, `cli.tool` 은 claude|codex 만.
|
||
|
|
|
||
|
|
## 4. TDD·검증
|
||
|
|
- `test/hal-ai.test.mjs` 에 자동 탐색 테스트를 먼저 추가해 RED 를 확인한다(가짜 HOME/.local/bin 의 claude(로그인 만료)·codex(로그인됨) 스크립트, HAL_CLI_HOME·HAL_CLI_DIRS 로 탐색 위치 고정): 탐색 API 결과, codex 연결(tool 만) → 확인 active → 대화 "OK from codex" 와 exec 인자, claude 연결 → 확인 424 cli_not_logged_in → reauth_required, 모르는 tool 거부, 빈 HOME 에서 cli_unavailable.
|
||
|
|
- GREEN 뒤 targeted(HAL UI·재인증·HAL) 와 전체 Suite 테스트. 배포 뒤 bear 에서 배포 코드의 탐색 결과(실제 claude·codex)를 read-back 한다.
|
||
|
|
|
||
|
|
## 5. 버전·배포
|
||
|
|
- HAL 0.3.1: package.json·README·VERSION_HISTORY 0.3.1 절·docs/HAL-AI.md. 커밋 → push → main 병합 → 깨끗한 main 에서 릴리스 빌드·verify → bear 에 HAL 만 배포(사전 백업·stage 검증·register-release --approve·bootstrap-release·current 전환·재시작) → `/api/health`·`/ops/api/ai/cli` read-back. 다른 모듈은 바뀌지 않았으므로 배포하지 않는다.
|
||
|
|
|
||
|
|
## 6. 완료 조건
|
||
|
|
점검 결과(설치 경로·버전·로그인 상태·원인), 변경 파일, RED/GREEN·전체 테스트, 커밋·병합 커밋, artifact sha256, 배포 read-back(탐색 결과 포함), 운영자가 해야 할 남은 조치(claude login)를 보고한다.
|