오픈 소스 AI 코딩 어시스턴트 — 한 번 배포로 브라우저 전 과정 제어 가능

오픈 소스 AI 코딩 어시스턴트 — 한 번 배포로 브라우저 전 과정 제어

Agent 위임 및 백그라운드 작업 · Docker 자가 호스팅 · 국산 대규모 언어 모델(LLM) 직결 · 심층 보안 아키텍처

빠른 시작 · 핵심 기능 · 사례 전시 · 공개 엔지니어링 사례 · SWE-bench 평가 · CLI 도구 · skill 시스템 · 플러그인 시스템 · 시각화 · 메모리 시스템 · 경쟁 제품 비교 · English

서버에 배포하여 브라우저를 열면 사용 가능하며, 휴대폰에서도 사용 가능합니다.

🏗️

전체 시스템 아키텍처 보기 →

Java Agent Runtime · React 브라우저 조작면 · Python Capability Service · 전경 시각화

🧭

전체 기능 개요 보기 →상호 작용 진입점 · Agent / Run · 권한 보안 · 도구 및 Skill · 검증 산출물 · 관측 복원

역사적 코드 규모 스냅샷 (현재 버전 통계 아님): ea0170c

· 2026-08-09 · Git 추적 제품 소스코드 134,826 라인 / 863 파일 (Java 93,118 / 622개, React 33,642 / 209개, Python 서비스 및 CLI 8,066 / 32개; 로컬 무시 파일 제외)

🔎

실시간 골드 모니터링: ZhikunCode vs Codex 동일 문제 PK →ZhikunCode × Codex · 동일 요구사항에 대한 두 가지 구현으로, 14차원 평가, 과정 스크린샷 및 전체 실행 기록 제공

🚄

12306 예비 전 과정 시각화: 단일 파일 제로 의존성 납품 →ZhikunCode/KimiK3 × Codex/GPT-5.6 Sol · 7차원 비교 평가, 양측 산출물은 온라인에서 직접 체험 가능

🎮

AI가 5시간 만에 플레이 가능한 '왕자 영요' 웹 버전 작성 →Kimi K3 · 연속 개발 5시간 29분 소요 · 순수 정적 Three.js 19개 파일 / 7,979 라인 · 브라우저를 열면 바로 체험 가능

📊

AI 오피스 도구 비교 평가 (Yutai Technology · 2026-08-30 기준) →5가지 도구 × 6개 작업 연속 링크 · 30건의 고정 최종본 증거 재검토 · 동일 보고서 Alibaba Cloud OSS 미러: oss.zhikun.xin

🔍

AI 코딩 코드 리뷰 비교: 17개 보고서 Claude Opus5.5: 순위 분석, 방법 및 증거 →· GPT-6 Astra Ultra: 공정 순위 및 재검토 가능한 증거 →

🔬

8가지 AI 코딩 동일 문제 코드 리뷰 (2026-09-25) →8개 원본 보고서 · 6차원 평가 · 재검토 가능한 증거와 약 1시간 57분 과정 녹화

🏆

SWE-bench Lite 기술 보고서 →

제출 네임스페이스 20260525_zhikuncode

· 공식 harness 평가 Resolve168 / 300 (56.0%) · 패치 생성률 284 / 300 (94.7%)

동일한 실시간 골드 모니터링 요구사항을 ZhikunCode와 Codex에게 각각 처음부터 완성하게 한 후, 요구 이해도, 개발 상호 작용, 데이터 정확성, 아키텍처, 코드 품질, 사용자 경험 등 14개 차원에서 점수를 매겼습니다. 보고서는 양측의 장점과 단점을 동시에 보존합니다.

• ZhikunCode: Kimi K3가 HTTP 429에 직면하자 사용자가 GLM-5.2로 전환하여 동일한 논리 세션에서 계속 진행했습니다.
• Codex: GPT-5.6 Sol, 추론 강도 High.
• 최종 점수 ZhikunCode 68.3, Codex 68.4 — 두 시스템은 거의 동점입니다.

비교 보고서 보기 → ·
원본 데이터 다운로드 → ·
평가 방법 이해하기 →

동일한

• 연속 개발 과정에서 5시간 29분 동안 작업하여, 19개의 자체 파일과 7,979줄의 코드를 산출했습니다.
• 10개의 서브 Agent가 협업하여 역할 분담을 했으며, 플레이 방식, 렌더링, AI 행동 및 레벨 리소스를 포괄합니다.
• 순수 정적(static) 배포로, 백엔드나 외부 네트워크 의존성이 없으며 브라우저에서 직접 실행됩니다.
• 전 과정 기록: 43장의 스크린샷과 5개의 원본 녹화 영상이 있어 보고서를 따라가며 상세히 확인할 수 있습니다.

상세 사례 보기 → ·
온라인 체험 (5명의 영웅 선택) → ·
자동 시연 (경기 바로 시작) → ·
평가 방법 알아보기 →

다섯 가지 AI 오피스 도구(Qwen Office, Qoder, Doubao Office, WorkBuddy 및 ZhikunCode)가 동일한 6가지 연속 명령 세트를 순차적으로 실행했습니다. 이들은 우수기술(宇树科技)을 중심으로 Excel 분석 초안, Word 연구 보고서, PPT부터 인포그래픽 및 인터랙티브 HTML까지의 완벽한 오피스 작업 흐름을 완성했으며, 총 30개의 최종 결과물을 산출하고 각 건별 증거를 재확인했습니다.

공식 순위 두 목록에 모두 등재되었습니다: 6개 임무 동등 가중치 순위에서 ZhikunCode가 93.8점으로 1위(Qwen 93.6점 2위); 균형 투자 연구 실무 순위에서는 Qwen이 93.3점으로 1위, ZhikunCode가 92.7점으로 2위를 차지했습니다. 30개 최종 결과물의 전달 단계 분포는 G0 3건 / G1 20건 / G2 7건입니다. 본 보고서는 단일 고정 샘플 임무 체인 실측이며, 각 도구의 전반적인 능력을 외삽(extrapolate)할 수 없습니다.

전체 보고서 보기 (GitHub Pages) → ·
阿里云 OSS 미러 →

Claude Opus 5.5: 순위 분석 방법, 과정, 증거 및 결론 → ·
GPT-6 Astra Ultra: 공정 순위 및 재검증 가능한 증거 →

여덟 가지 AI 코딩 도구가 동일한 코드 커밋을 검토하며, 유효 발견, 정확성, 귀속(attribution), 증거, 엔지니어링 범위 및 제안된 전달의 6가지 차원에서 최종 보고서를 비교했습니다. 공개적으로 8개의 원본 보고서, 항목별 점수, 독립 재검증 증거, 재계산 스크립트와 약 1시간 57분의 과정 녹화 영상을 제공합니다. 이번은 단일 임무 산출물 평가이며, 제품의 전반적인 능력 순위를 대표하지 않습니다.

평가 홈 → ·
증거 및 재계산 → ·
과정 녹화 영상 및 시간 인덱스 →

위 사례들은 모두 단일 임무 실측 기록이며, 상세 방법과 데이터는 각 사례 보고서 페이지를 참조하십시오.

천문(千问) / DeepSeek / Moonshot / 智谱GLM / MiniMax를 즉시 사용 가능하며, 중국 네트워크에 직접 연결되어 과학 인터넷 접속이 필요하지 않음 |
| 🐳 | Docker 원클릭 배포 |
docker compose up -d 명령으로 기본 Java 백엔드와 내장 정적 프론트엔드가 자동으로 시작됩니다. 이미지는 선택적 관리 Python 서비스가 포함되어 있으며, 데이터는 로컬에 저장됩니다. |
| 📤 | OSS 게시 및 스크린샷 붙여넣기 (선택) |
/publish-oss는 명시적인 명령을 통해서만 검증된 결과물을 게시합니다. 스크린샷 붙여넣기는 두 가지 경로를 지원합니다. OSS가 구성된 경우 백엔드를 통해 빠르게 업로드하고, OSS가 구성되지 않은 경우 Base64로 직접 전송하여 이미지 분석 기능을 사용할 때 추가 설정 없이도 사용 가능합니다. |
| 🌍 | 秒悟(Meoo) 앱 게시 (선택) |
/publish-meoo를 통해 검증된 정적 웹사이트 또는 풀스택 애플리케이션을 독립적인 새 사이트로 게시하고 공유 가능한 웹사이트 링크를 얻을 수 있습니다. 기본적으로 비활성화되어 있으며, 완전 접근 모드 외의 모든 배포는 개별 확인이 필요합니다. |
| 🎙️ | 음성 상호작용 (ASR / TTS) |
대화 입력은 마이크 음성 인식(qwen3-asr-flash)을 지원하며, AI 답변은 원클릭 읽기 기능을 지원합니다(qwen3-tts-flash). 알리바바 클라우드 백련 DashScope에 연결하고 API Key를 설정하면 바로 사용할 수 있으며, 미설정 시 자동으로 숨겨집니다. |
| ⚡ | 지능형 컨텍스트 관리 |
6단계 압축 캐스케이드(Snip / MicroCompact / ContextCollapse / AutoCompact / CollapseDrain / ReactiveCompact) + 증분 폴딩(10라운드마다 자동 압축) + 413 2단계 컨텍스트 압축(CollapseDrain의 공격적 압축 → ReactiveCompact의 반응형 압축) + 정밀 토큰 카운팅(tiktoken 다중 모델 지원) + 자체 교정 루프(SelfCorrectionLoop, 컴파일/테스트 실패 시 자동 진단 및 복구, 최대 3회) + 토큰 3단계 경고 + 이미지 컨텍스트 관리(대형 이미지는 외장화 → 필요시 주입 → 예산 수호 3중 보호)를 통해 초장문 대화를 끊김 없이 처리합니다. 핵심 엔진은 ContextCascade와 QueryEngine입니다. |
| 📷 | 멀티모달 이미지 대화 |
이미지 업로드 입력을 지원하며, 모델이 자동으로 이미지 내용을 인식하고 분석합니다. 지능형 비전 모델 라우팅 기능은 현재 모델이 이미지를 지원하지 않을 경우 동일 제조사의 비전 모델로 자동 전환하여 처리한 후, 원래 모델로 끊김 없이 복귀합니다. DeepSeek V4.1 Flash(deepseek-flash)는 네이티브하게 시각을 지원하며, DeepSeek 시리즈의 이미지 이해 폴백 역할을 합니다. 이미지 예산 수호 기능은 대형 이미지(>50KB)를 자동으로 경량 JSON 참조로 외장화하고, API 호출 전에 필요에 따라 주입합니다. 2단계 토큰 예산 수호는 다중 이미지 대화가 초과하는 것을 방지하며 (단일 이미지 ≤1.5MB, 총합 ≤2MB, 단회 최대 8장 주입 가능). ZenMux 이미지 모델에는 Fable 5.1, GPT-5.6 Sol, GPT-6 Astra, Gemini 3.8 Flash 및 Grok 4.6이 포함되어 있습니다 (각 모델의 수량 제한은 모델 디렉토리를 참조). |
| 🖼️ | 브라우저 시맨틱 스냅샷 |
/snap 명령을 사용하여 웹페이지의 전체 상태(DOM 구조 + 상호작용 요소)를 지능적으로 포착합니다. 풍부한 상호작용 페이지의 의미론적 추출을 지원하여, Agent가 해석하고 재현 검증할 수 있는 구조화된 JSON을 생성합니다. |
| 💬 | 라운드 및 작업 프로세스 보기 |
표시 방식은 세 가지 단계로 제공됩니다: 간소화 모드는 기본적으로 질문과 프로세스/답변을 접어 볼 수 있으며, 각각 개별적으로 펼칠 수 있습니다. 표준 및 전체 프로세스 모드는 완전한 질문과 답변을 유지하며, 해당 모드에 따라 프로세스를 표시합니다. 실행 중에도 동일하게 적용됩니다. 모바일 환경에서는 상시 입력 카드가 첨부 파일, 음성 및 표시 방식 전환 기능을 제공하며, 홈 페이지 템플릿에는 초안을 직접 채워 넣을 수 있습니다.

📊 실시간 활동 추적 및 승인
Activity Panel은 AI 도구 실행의 전 과정을 실시간으로 기록하며, L1/L2/L3 세 단계로 표시됩니다. Signal 스마트 태그(auto_approve/review_recommended/needs_review)를 통해 한 번에 대량 승인 결정을 내릴 수 있으며, SQLite 백엔드에 데이터를 영구 저장하고 세션 복원을 지원합니다.

🧪 런타임 검증 프레임워크 (Runtime Verification)
VerifierFactory는 세 가지 모드로 배포됩니다(browser/http_api/auto). 여기에 8가지 HTTP action handler와 JSONPath 단언, 증거 사슬 SQLite 저장, Feature Flag 이중 게이트, 그리고 프론트엔드 실시간 진행 패널을 갖추고 있습니다.

🔍 RV-4 증거 패키지 시각화
검증 산출물 7가지 유형의 증거(screenshot / command / console / test / video / har / diff)가 탭으로 분할되어 표시됩니다. 모바일 환경에서는 STOMP verify_attention 알림을 구독하여 한 번에 승인/반려 처리가 가능하며, REST API /api/evidence/*를 통해 조회 및 Blob 다운로드가 제공됩니다.

🏆 SWE-bench Lite 과거 실측 (2026-05)
과거 평가 모델 qwen3.7-max(원 기록 유지)와 6가지 도구 클로즈셋(Read/Edit/Write/Bash/Grep/Glob)을 사용합니다. 네트워크 연결이나 sub-agent 없이 진행됩니다. 공식 harness 평가는 Resolve 56.0% (168/300), Patch 생성률 94.7% (284/300)를 기록했습니다. 기술 보고서 →

🚀 극한의 성능
REST API p50 1.5ms · WS STOMP 핸드셰이크 2.22ms · 490회 실제 요청 샘플 검증, 핵심 엔진은 외부 의존성이 없는 순수 Java로 구현되었습니다.

🏭 런타임 신뢰성
Run 상태 CAS 원자 관리 · 전체 세션 스냅샷, Run 이벤트 시퀀스 및 처리 대기 영구 상호작용 재현 · 프로세스 하드 타임아웃 + 기울기 종료(gradient termination) · 범위 부여(Scope Grant)와 자식 Agent의 통제된 상속 · Artifact declare→seal→hash 검증 및 명시적 배포 · 구조화된 도구 결과 생성, 도구 카드 및 권위 다운로드 링크 제공 · sid/rid/prid/agent/turn/tool/llm 로그 연관 · BestEffortObservabilityRecorder를 통한 이벤트 실패 격리 보충 · Provider 로컬 예산 가드

다크 모드, 라이트 모드, 액체 유리(liquid glass), 성함(Starship), 화과천(Huaguo Chen), 영소야(Lingxiaoye), 그리고 젤리(Jelly)의 총 7가지 테마를 지원합니다. 데스크톱 환경에서는 상단 바의 '외관 설정'에서, 모바일 레이아웃은 입력창의 '더 보기' 내 '외관'에서 전환할 수 있습니다. 설정은 즉시 적용되며 로컬에 저장됩니다.

젤리(Jelly)는 진한/절제 스타일과 전체, 간결, 닫기 세 가지 단계의 애니메이션을 제공하며 시스템의 '동적 효과 줄이기' 기본 설정을 따릅니다.

화과천(Huaguo Chen)과 영소야(Lingxiaoye)는 대나오천궁(大鬧天宮)의 화려한 극화 스타일을 채택하여, 각각 따뜻한 색감의 비단지와 어두운 밤 풍경 배색을 제공합니다. 전용 강조색을 사용하며, 강조색 사전 설정 전환은 지원하지 않습니다. 두 테마 모두 다음 기능을 제공합니다:

진한/절제: '진한 모드'를 켜면 금박 무늬, 현판 및 실색 메시지 말풍선이 표시되며, 끄면 절제된 스타일을 사용합니다. 애니메이션은 독립적으로 전체, 간결 또는 닫기로 선택할 수 있습니다. 폐관(閉關): 장식 레이어를 숨기고 글쓰기에 집중합니다. 장식 공유: 대화 제목과 편집 가능한 주석을 축, 수묵지, 또는 책자 형식의 단일 PNG 이미지로 제작하여 내보낼 수 있습니다.

새로운 대화는 기본적으로 개발 작업대(Development Workbench), 표준 표시 방식을 사용하며, 간결/개발 작업대 공유 대화에서는 표시 방식을 간결, 표준, 전체 과정 중 선택할 수 있습니다. 어시스턴트 답변 끝의 '이번 라운드 수정'을 펼치면 파일 목록을 확인하고, 이번 라운드의 원본 Edit 또는 Write에 대한 순차적인 수정 내역(성공했고 경로를 확인할 수 있는 작업만 포함)을 볼 수 있습니다.

대화 목록에서 2~5개의 실행이 중지된 유휴 대화를 선택하여 새로운 대화로 병합할 수 있으며, 이때 주 대화, 새 제목, 모델을 확인해야 합니다. 새 대화는 인계 요약, 과정 텍스트 및 출처가 명확한 임시 산출물 사본을 받으며, 엔지니어링 코드는 자동으로 병합되지 않습니다. 병합 기간 동안 원본 대화는 볼 수 있지만 실행하거나 삭제할 수는 없습니다. 새 대화는 '완전 접근 권한'(AUTO_APPROVE) 모드를 사용하며, 생성 후 다음 지시를 기다립니다.

음성 인식은 LLM_PROVIDER_DASHSCOPE_API_KEY (Token Plan Key 불가)를 설정해야 하며, 신조어 교정은 루트 디렉토리 .env에 ASR_CORRECTIONS를 설정한 후 백엔드를 재시작해야 적용됩니다. 형식은 표준 표기:변형1,변형2;표준 표기2:변형3와 같습니다. 예시로 zhikuncode:zhi kun code,zkun code,智坤code;PostgreSQL:post gre sql가 있습니다. 설정 항목은 .env.example을 참조하십시오.

본 프로젝트는 LLM(대규모 언어 모델) API Key가 있어야 실행할 수 있습니다. 기본적으로 **Alibaba Cloud Qwen (DashScope)**를 사용하며, 국내 네트워크에 직접 연결됩니다.

천문(千问) API 키 확보 방법:

• 알리클라우드 바이롄(阿里云百炼) 플랫폼 API Key 관리 페이지 접속
• 알리클라우드 계정 등록 또는 로그인
• API Key 생성 후, 전체 키를 복사합니다 (접두사는 sk-로 시작).

천문은 개인 개발에 충분한 무료 크레딧을 제공합니다. DeepSeek, Moonshot/Kimi 등 다른 국내 서비스 공급자도 사용할 수 있으며, 자세한 내용은 아래 '지원하는 LLM 서비스 공급자'를 참조하세요.

단 3단계만 거치면 제로 상태에서 사용 가능합니다:

# 1. 저장소 클론
git clone https://github.com/zhikunqingtao/zhikuncode.git
cd zhikuncode
...

최초 빌드 설명: 처음 실행할 때는 Docker 이미지를 자동으로 빌드해야 하므로, 의존성 다운로드 및 컴파일 과정이 필요하며, 예상 소요 시간은 15~30분입니다 (네트워크 속도에 따라 다름). 이후 재시작 시에는 몇 초 만에 가능합니다. docker compose logs -f를 통해 빌드 진행 상황을 확인할 수 있습니다.

시작 완료 후, 브라우저에서 **http://localhost:8080**으로 접속하면 바로 사용할 수 있습니다.

기본 설정 (Basic)

docker-compose.yml

기본적으로 Java 백엔드만 실행됩니다 (백엔드가 내장된 정적 프런트엔드를 제공). Docker 이미지는 Python 런타임과 서비스 코드를 포함하고 있지만, 기본적으로는 시작되지 않습니다. 만약 컨테이너 내부의 Python 서비스를 사용해야 한다면, 자신의 Compose 오버라이드(override)를 통해 다음 환경 변수를 명시적으로 전달해야 합니다:

PYTHON_SERVICE_AUTO_START=true<br>PYTHON_SERVICE_PATH=/app/python-service<br>PYTHON_SERVICE_EXECUTABLE=/app/python-service/.venv/bin/python<br>WORKSPACE_ROOT=/app/workspace<br><br>그리고 두 개의 Compose 파일을 사용하여 컨테이너를 재구성해야 합니다. 만약 브라우저가 직결된 Python의 인터페이스 기능을 사용하도록 하려면, 오버라이드에서 반드시 Python을 컨테이너 인터페이스에 바인딩하고 호스트 머신의 루프백(loopback) 주소로만 매핑하며 필요한 정확한 라우트를 역방향 프록시를 통해 열어야 합니다. 8000 포트를 공용 인터넷에 직접 노출해서는 안 됩니다.

시스템 요구 사항: Docker 20.10+ 및 Docker Compose V2, 메모리 4GB 이상 권장.

선행 조건 (Prerequisites): JDK 21, Node.js 22+, Python 3.11~3.12 (3.13+는 지원하지 않음)

git clone https://github.com/zhikunqingtao/zhikuncode.git
cd zhikuncode
# 환경 변수 설정
...

세 가지 서비스가 동시에 시작됩니다:

./start.sh

기본적으로 저장소의 루트 디렉토리를 작업 공간(workspace)으로 설정합니다. allowed roots와 로컬 피커 스위치 모두 비어있지 않은 경우에만, 자동으로 본래 기기 디렉토리 탐색 기능이 활성화됩니다.

• 처음 사용할 때는 기본적으로 **개발 작업대 (开发工作台)**가 사용되며, 세션이 선택되지 않았을 경우 환영 페이지가 표시됩니다. 페이지 상단에서 언제든지 **간결한 작업대 (简洁工作台)**로 전환할 수 있습니다.
• 간결한 작업대는 결과 중심이며, 현재 Root Run에 해당하는 요구사항, 최종 답변, 주요 성과, 처리 대기 항목, 최근 활동 및 승인 상태를 보여주며, 이전 실행 결과를 이번 전달 내용에 섞지 않습니다.
• 개발 작업대는 전체 대화 기록, 도구 호출, 파일, Diff, Git, 터미널, 브라우저, Agent 및 증거 보기(evidence view) 기능을 보존합니다.
• 보기 선택은 현재 브라우저에 저장되며 세션별로 기억하는 것이 가능합니다. 뷰를 전환해도 작업이 중단되거나 실행 상태가 변경되지 않습니다.
• PDF, 이미지, 텍스트, Markdown 등 다양한 형식의 파일은 작업대 내에서 안전하게 미리 볼 수 있습니다. 다른 파일들은 개발 작업대의 파일 영역으로 전환하여 처리할 수 있습니다.

권한 데이터 설명: 현재 권한 아키텍처는 V015 영구 상호작용(persistent interaction)과 V019 제한적 부여(constrained Grant)를 데이터베이스 권위로 사용하며, 이전 권한 테이블은 읽지 않습니다. 개발 환경을 업그레이드할 때는 프로젝트 데이터베이스를 직접 재구축하고 새 버전에서 다시 권한을 부여합니다.

ZhikunCode는 내장된 /publish-oss Skill을 제공하여, 동일한 영구 루트 세션(persistent root Session) 내의 루트 Run 또는 parent_run_id를 통해 생성된 후대 Run 중 하나에서 검증된 산출물 항목을 선택하여 OSS 영구 공개 링크로 게시할 수 있습니다. 기본 OSS 게시 기능은 기본적으로 비활성화되어 있으며 절대 자동으로 업로드되지 않으므로, 별도로 구성하여 활성화해야 합니다. Skill 관리 페이지의 스위치는 배포 구성을 대체하지 않습니다. 파일을 생성하거나, Run을 완료하거나, 미리 보거나, 파일을 여는 행위로는 업로드가 트리거되지 않습니다. 모든 게시 작업은 사용자로부터 명시적인 요청이 있어야 하며, 한 번의 고위험 권한 확인을 거쳐야 합니다.

동일한 OSS 구성을 활성화하면, 브라우저가 다른 애플리케이션에서 복사하여 붙여넣은 PNG/JPEG/WebP 스크린샷(단일 이미지 최대 5 MiB)도 감지할 수 있으며, 이를 고정된 백엔드 채널을 통해 즉시 업로드하고 서버 측에서 검증된 OSS 이미지 주소를 시각 모델에 직접 전달합니다. 이 경로는 /publish-oss Skill을 호출하지 않으며 LLM을 추가로 호출하지 않습니다. OSS가 구성되지 않은 경우 Base64 직전송으로 자동 하향 조정되어, 별도의 설정 없이도 이미지 분석 기능을 사용할 수 있습니다.

'로컬 파일 참조(引用本地文件)'는 실제 접근 능력에 따라 경로를 선택합니다. 직접 루프백(loopback)하고 프록시 포워딩이 없으며 네이티브 선택기 보안 게이트가 모두 충족될 때만 정규화된(canonical) 경로만 전송됩니다. ECS, 원격 및 프록시 액세스의 경우 브라우저 파일 선택기를 사용하며, 파일을 선택하면 즉시 ${ZHIKUN_OSS_PREFIX}/local-files/에 업로드하고 파일 이름과 OSS 주소를 프롬프트에 추가합니다. 원격 파일은 기본적으로 ZHIKUN_OSS_MAX_FILE_BYTES (100 MiB) 상한선을 따릅니다. OSS가 구성되지 않은 경우 이 경로는 사용할 수 없으며 Base64로 하향 조정되지 않습니다. 이 채널은 모든 파일 유형을 허용하며, 민감한 파일 이름이나 내용 스캔을 수행하지 않습니다. 객체는 영구적인 public-read로 게시되며, 태그 제거, 세션 전환 또는 메시지 포기만으로는 삭제되지 않으므로 사용 전에 파일이 공개될 수 있는지 확인해야 합니다.

자격 증명 모드(Credential Mode)는 기본값으로 auto입니다. 로컬에 완전한 표준 ALIBABA_CLOUD_ACCESS_KEY_ID/ALIBABA_CLOUD_ACCESS_KEY_SECRET가 존재하는 경우 Alibaba Cloud의 기본 자격 증명 체인을 우선 사용합니다. 그렇지 않은 경우, ZHIKUN_OSS_ECS_ROLE_NAME이 구성된 경우 ECS RAM Role + IMDSv2를 사용하며, 둘 다 없는 경우 여전히 기본 자격 증명 체인(예: Alibaba Cloud CLI의 기본 Profile)을 시도합니다. 따라서 동일한 비키 설정으로 로컬 원클릭 시작과 ECS 모두를 지원할 수 있습니다. 모든 배포자는 반드시 자신의 버킷과 최소 권한 신원을 사용해야 하며, 저장소에는 유지 관리자의 OSS 자격 증명이 포함되어 있지 않습니다.

.env에 다음과 같이 구성합니다:

ZHIKUN_OSS_ENABLED=true
ZHIKUN_OSS_ENDPOINT=https://oss-cn-your-region.aliyuncs.com
ZHIKUN_OSS_REGION=cn-your-region
...

선택적 사용자 정의 도메인 및 미리 보기: 먼저 목표 버킷의 도메인 바인딩, DNS 및 HTTPS 구성을 직접 완료한 후, ZHIKUN_OSS_PUBLIC_BASE_URL을 자신의 HTTPS 도메인 루트 주소(예: https://files.example.com, 포트, 경로 접두사, 쿼리 매개변수 또는 단편 없이)로 설정합니다. 산출물 게시, 스크린샷 붙여넣기 및 원격 파일 참조는 모두 이 도메인을 사용하며, 업로드 엔드포인트는 변경되지 않습니다. ZHIKUN_OSS_PREVIEW_ENABLED=true를 설정한 후에는 새로 업로드되는 HTML, 순수 텍스트, PDF, PNG/JPEG/GIF/WebP만 inline으로 사용하고, 다른 유형은 여전히 첨부 파일로 처리됩니다. 미리 보기를 활성화하려면 사용자 정의 도메인 구성이 필수이며 OSS 기본 도메인을 사용할 수 없습니다. 기본값은 비워두고 닫으면 원래의 다운로드 동작을 유지합니다.

OSS가 비활성화된 경우, 유효하지 않은 사용자 정의 도메인/미리 보기 설정은 경고를 발생시키고 CSP에서 제외되지만 시작을 차단하지는 않습니다. 활성화된 경우 여전히 시작을 차단합니다. 합법적인 사용자 정의 도메인은 OSS가 비활성화되어도 역사적 이미지를 지원하기 위해 CSP에 유지됩니다. 게시 진입점은 항상 엄격한 구성 검증을 유지합니다. 클립보드 API는 HEAD 반환의 구체적인 이미지 MIME(대소문자 통일, 매개변수 제거)를 표준화하고 유효한 CDN 변환 유형을 유지하며, 다른 유형은 파일 바이트 감지 결과로 폴백됩니다. 클라이언트가 선언하는 이미지 유형은 여전히 업로드 내용과 일치해야 합니다.

로컬 배포의 경우 Alibaba Cloud CLI 기본 Profile을 먼저 구성할 수 있으며, 제한된 RAM 사용자 또는 임시 STS의 ALIBABA_CLOUD_ACCESS_KEY_ID와 ALIBABA_CLOUD_ACCESS_KEY_SECRET, 그리고 선택적 ALIBABA_CLOUD_SECURITY_TOKEN을 로컬 .env에 작성할 수도 있습니다.

⚠️ [IMG:N] 형식 토큰은 이미지 placeholder 입니다. 번역하지 말고 원래 위치에 그대로 유지하세요.

(이전 청크의 내용과 일관된 톤으로 이어집니다.)

진짜 값은 제출해서는 안 됩니다. 구식 OSS_ACCESS_KEY_ID,
OSS_ACCESS_KEY_SECRET,
OSS_SESSION_TOKEN

은 거부됩니다.

신분은 목표 버킷/접두사(Bucket/Prefix)가 필요로 하는 최소한의 권한만 가져야 합니다:
PutObject,
GetObject/HeadObject,
PutObjectAcl
그리고 실패 시 정리할 DeleteObject 권한입니다. 또한, 버킷은 목표 객체에 public-read 설정이 허용되어야 하며, 그렇지 않으면 업로드가 실패하고 개인(private) 객체를 정리하려고 시도합니다.

사용 흐름:

• 현재 영구 세션(persistent root Session)에서 산출물을 생성합니다. Manifest가 declare → seal/hash → verify를 완료하면 상태는 verified일 수도 있고, 목표의 검증된 항목을 포함하는 partial일 수도 있습니다.
• 명시적으로 /publish-oss <파일 경로>를 입력하거나 “방금 생성한 산출물을 OSS에 업로드”라고 설명합니다.
• 확인 카드(confirmation card)에서 파일 이름, 크기, 공개 범위 및 “영구 공개” 경고를 검토한 후 이번 작업을 승인합니다.
• 업로드가 성공하면 게시 성공 카드(publish success card)를 사용하여 미리 보기 또는 다운로드를 열어봅니다. 브라우저의 실제 응답을 기준으로 하며, 모델이 링크를 재구성하지 않도록 합니다.

보안 경계 및 현재 제한:

• 동일한 영구 루트 세션 내에서 루트 Run 또는 권한 부여된 하위 Run이 선언하고, 목표 항목이 검증되었으며 Manifest 해시와 여전히 일치하는 워크스페이스 내의 단일 일반 파일만 허용되며, 기본적으로 100 MiB를 초과할 수 없습니다.
• 디렉토리, 배치 업로드, 심볼릭 링크, 워크스페이스 외부 경로, .env,
  개인 키(private key), 데이터베이스, 자격 증명 구성 및 민감한 내용이 감지된 파일은 거부됩니다.
• 객체는 먼저 개인적으로 업로드되고, 원거리 검증에 성공한 후에야 public-read로 전환됩니다. 실패할 경우 이번에 새로 생성된 개인 객체를 정리합니다.
• 반환 주소는 영구 공개 링크입니다. 카드는 공개 주소의 응답을 기반으로 미리 보기 또는 다운로드를 판단하며, 검사 실패 시 보수적으로 “다운로드”를 표시하고 이미 성공한 게시를 취소하지 않습니다. OSS 기본 도메인은 일반적으로 HTML을 다운로드합니다.
• 이전 객체의 내용, 메타데이터 및 히스토리 메시지 링크는 마이그레이션되지 않습니다. 이전 객체를 반복적으로 게시할 경우 현재 구성된 도메인을 반환할 수 있지만, 원본 첨부 파일은 여전히 다운로드될 수 있습니다. 미리 보기를 닫아도 이미 업로드된 객체의 메타데이터가 복구되지는 않습니다.
• HTML 미리 보기 시 페이지 스크립트가 실행됩니다. 공유 영역(sharing domain)에서는 애플리케이션 로그인 쿠키를 공유하거나 애플리케이션 인증 인터페이스의 크로스 도메인 화이트리스트에 추가할 수 없습니다. 동일 사이트 하위 도메인이 완전한 보안 격리를 의미하지는 않습니다. HTTPS 인증서 갱신에 주의해야 하며, 모든 브라우저에서 모든 형식을 미리 볼 수 있다고 보장하지 않습니다.
• 현재 간소화된 버전은 배치 게시, 게시 기록 또는 취소 진입점을 제공하지 않습니다. 공개 객체를 삭제하려면 운영 인력(operations personnel)이 OSS 측에서 명시적으로 실행해야 합니다.
• 로컬과 ECS 모두 실제 업로드를 지원합니다. 로컬에서는 기본 자격 증명 체인(credential chain)을 사용하고, ECS에서는 자동 순환되는 RAM Role 임시 자격 증명을 사용하는 것이 좋습니다.
• 원거리 파일 참조는 원본 요청 본문 스트리밍 업로드(streaming upload)를 사용하여 Spring의 전역 multipart 제한을 확대하지 않습니다. 만약 ECS 앞에 리버스 프록시가 있다면, 프록시의 요청 본문 상한선도 ZHIKUN_OSS_MAX_FILE_BYTES보다 낮지 않아야 합니다.