welsonjs

WelsonJS 빠른 시작

English version

이 문서는 WelsonJS 0.2.7.62 기준이다. WelsonJS를 설치하고, AI 도구가 있는 코드 편집기를 쓰고, 첫 번째 스크립트를 실행하기까지의 과정을 설명한다. 소스 코드로 작업하려는 개발자는 개발자용 안내로 바로 가면 된다.

요구 사항

1. 설치

  1. Releases 페이지에서 welsonjs_0.2.7.62_setup.exe를 내려받는다. SignPath Foundation이 서명한 파일이다.
  2. 실행하고 변경 허용을 묻는 창에서 허용한다(관리자 권한이 필요하다).
  3. Customer Information(선택): 비워 두어도 된다. 내용을 입력하고 동의란에 표시했을 때만 Catswords Research로 전송된다.
  4. 구성 요소를 고르고(아래 참고) 설치가 끝날 때까지 기다린다.

파일 복사가 끝나면 PowerShell 창에서 설치 후 스크립트가 실행된다. 이 스크립트가 WelsonJS 바이너리와 선택한 구성 요소를 내려받는데, AI 모델은 시간이 걸릴 수 있다. 이 창을 닫지 않는다. 스크립트가 끝나면 WelsonJS Launcher가 실행된다.

WelsonJS는 C:\Program Files (x86)\WelsonJS에 설치된다. llama.cpp와 AI 모델을 비롯해 내려받은 구성 요소는 %APPDATA%\WelsonJS에 들어간다.

구성 요소 고르기

기본 선택인 Full에는 다음이 들어 있다.

구성 요소 하는 일
Associate .js files to run with WelsonJS .js 파일을 더블클릭하면 Windows Script Host 대신 WelsonJS로 실행한다. Windows 기본 동작을 유지하려면 해제한다.
Register the welsonjs:// URI scheme welsonjs:// 링크로 WelsonJS를 실행할 수 있게 한다. 어떤 웹 페이지에서나 이 링크를 열 수 있으므로, 필요하지 않으면 해제한다.
WelsonJS Launcher and Windows Service 런처와 코드 편집기, WelsonJS Windows 서비스.
Configure WelsonJS MCP server for supported AI CLIs 설치된 AI 명령줄 도구(예: Claude Code)에 WelsonJS를 MCP 서버로 등록한다.
Python, cURL, websocat 일부 WelsonJS 모듈이 쓰는 도구.
Local AI 모델(Llama.cpp 아래) 편집기의 AI 도구가 내 PC에서 실행하는 모델. llama.cpp도 함께 설치된다.

Local AI 모델은 모두 합쳐 약 4.9 GB다.

모델 다운로드 크기 용도
Hy-MT2 1.8B 1.25-bit (Tencent) 462 MB 번역, 기본 Local AI 모델
FrogNano 4B 2609 2.8 GB 코딩 질문과 코드 작성
BitNet b1.58 2B-4T (Microsoft) 1.2 GB 1.58비트 모델로 하는 일반 질문
Qwen3Guard-Gen-0.6B (Qwen) 484 MB 프롬프트의 위험한 내용 검사(LLM 가드)

어떤 로컬 모델을 골라야 할지 고민이라면, 하려는 일에 맞는 모델을 활성화한다.

용량을 줄이려면 Custom을 고르고 필요한 것만 표시한다. 예를 들어 번역만 한다면 Hy-MT2 하나로 충분하다. 나중에 설치 프로그램을 다시 실행해 구성 요소를 추가할 수 있다.

2. 런처와 편집기 실행

런처는 자기 전용 브라우저 프로필을 쓰므로, 여기서 웹 서비스에 로그인해도 평소 쓰는 브라우저에는 영향이 없다. 이전 버전에서 업그레이드했다면 이전 런처가 띄운 브라우저 창을 먼저 닫는다.

3. 스크립트 작성과 실행

편집기에는 예제 스크립트가 들어 있다. WelsonJS 스크립트는 main 함수를 내보낸다.

// hello.js
function main() {
    console.log("Hello World");
}

exports.main = main;

스크립트는 Windows Script Host의 JScript 엔진(ES3 기반)에서 실행된다. var와 function을 쓰고, let, const, 화살표 함수, 클래스 같은 ES6+ 문법은 쓸 수 없다. lib 폴더의 모듈은 var HTTP = require("lib/http");처럼 require로 불러온다.

4. AI 도구 사용

리본의 Inference (AI) 그룹에는 지금 쓰는 AI 서비스 이름이 적힌 버튼이 있다. 누를 때마다 다음 서비스로 바뀐다.

편집기에서 텍스트를 선택하고 마우스 오른쪽 버튼을 누르면 다음 메뉴를 쓸 수 있다.

메뉴 하는 일
Send Selection 선택한 텍스트를 보낸다.
Explain Selection 선택한 코드나 텍스트를 설명한다.
Find Problems in Selection 선택한 코드에서 버그를 찾는다.
Translate Selection into … 시스템 언어나 영어로 번역한다. Local AI는 번역을 항상 Hy-MT2로 한다.
Write Code 설명한 내용대로 WelsonJS에서 실행되는 JavaScript 코드를 작성한다.
Ask… 직접 입력한 질문을 한다.

답은 편집기에 주석으로 들어간다. 서비스를 바꾸면 쌓인 대화가 지워진다.

Local AI

웹 채팅 서비스

5. 네트워크 도구

리본의 Network Tools 그룹에서 호스트 정보를 조회한다.

6. 설정 바꾸기

런처 설정은 C:\Program Files (x86)\WelsonJS\bin\x86\WelsonJS.Launcher.exe.config에 있다. 관리자 권한으로 파일을 고친 뒤 런처를 다시 시작한다.

설정 용도
IpQueryApiKey IP 도구에 쓰는 Criminal IP API 키
IpQueryApiKey2 IP 도구에 쓰는 AbuseIPDB API 키
DnsServerAddress DNS 도구가 쓰는 DNS 서버(쉼표로 구분, 기본값 1.1.1.1,8.8.8.8)
ResourceServerApiKey 런처의 OpenAI 호환 API를 쓰는 다른 프로그램을 위한 API 키

업그레이드하면 설치 프로그램이 이 파일을 새 파일로 바꾼다. 바꾼 값은 적어 두었다가 업그레이드 후 다시 설정한다.

7. 다른 프로그램에서 AI 쓰기(선택)

런처에는 OpenAI 호환 API가 있어서, OpenAI를 지원하는 프로그램이 Local AI 모델과 웹 채팅 서비스를 쓸 수 있다.

런처가 실행 중이면 이 PC의 프로그램이 쓸 수 있다. 브라우저 엔진으로 만든 앱처럼 API 키가 필요한 프로그램도 있다. 이때는 ResourceServerApiKey를 공개된 예시 값에서 16자 이상의 내 키로 바꾼다. 자세한 내용은 openai-compatible-api.md를 참고한다.

8. 문제 해결


개발자용 안내

설치 프로그램 없이 소스 코드로도 WelsonJS를 쓸 수 있다. 스크립트는 Windows에 내장된 Windows Script Host의 JScript 엔진에서 실행되므로, 기본 실행에는 별도 소프트웨어가 필요하지 않다. WelsonJS는 Windows XP SP3 이상에서 동작한다(Windows 11 24H2까지 확인).

소스 받기

git clone https://github.com/gnh1201/welsonjs.git
cd welsonjs

PowerShell 한 줄로 내려받아 실행할 수도 있다. master 브랜치를 %TEMP%에 내려받아 bootstrap.bat을 실행한다.

irm https://catswords.blob.core.windows.net/welsonjs/bootstrap.ps1 | iex

(선택) 초기 설정

bootstrap.bat

bootstrap.bat은 두 가지 일을 한다.

레지스트리와 COM 등록을 바꾸므로 관리자 권한이 필요할 수 있다. 순수 JScript 모듈만 쓴다면 건너뛰어도 된다.

스크립트 실행

cscript app.js helloworld

app.js는 첫 번째 인자로 받은 이름의 모듈을 불러와(확장자를 생략하면 .js가 붙는다) main(args)를 호출한다. 추가 인자는 배열로 전달되고, main이 숫자를 반환하면 그 값이 종료 코드가 된다.

모듈과 진입점은 다음과 같이 만든다.

// lib/sayhello.js
function say() {
    console.log("hello");
}

exports.say = say;
// sayhello.js
var SayHello = require("lib/sayhello");

function main(args) {
    SayHello.say();
}

exports.main = main;
cscript app.js sayhello

더 알아보기

다음 단계