# AutoHano Works — AI 가 읽는 설치·연결 안내

이 문서는 사람의 PC 에서 도는 AI 도구(Claude Code, Codex CLI 등)가 AutoHano Works를 설치하고 자기 도구로 연결할 때 따르는 순서다. 사람이 해야 하는 단계는 **[사람]** 으로 표시했다. Windows 10/11 (64비트) 전용.

## 0. 준비물

- 기본(이력·비교·주소 찾기·래더 보기·리포트·AI 연결): Windows 10/11 64비트 PC, 인터넷, 구글·네이버·카카오 계정 하나. 따로 깔 런타임·관리자 권한은 필요 없다(Works 는 `127.0.0.1` 에만 열린다). XG5000 이 없는 PC 에서도 된다.
- xgwx 생성(내 PC 엔진, 4장): XG5000 — 이 PC 에 깔려 있으면 그대로 복사해 쓰고, 없으면 LS ELECTRIC 홈페이지의 XG5000 설치 파일로 설치한다. 디스크 여유 8GB. 새 PC 는 처음 한 번 **[사람]** 관리자 승인과 다시 시작이 필요할 수 있다. 만든 파일을 `open=true` 로 바로 여는 것은 이 PC 의 XG5000 을 쓴다.
- 회사 PC: 보안 프로그램이 처음 보는 exe 를 막거나 `works.autohano.com`(로그인)·엔진 설치 중 내려받는 곳이 막혀 있으면 **[사람]** 전산 담당자에게 허용을 부탁한다. 막힌 주소는 `GET /api/engine/status` 의 `hint` 에 나온다.

## Works 가 무엇인가

LS ELECTRIC PLC 파일(XG5000 .xgwx, XP-Builder .xpd)의 버전 이력·비교·주소 검색 도구이자, AI 가 쓴 프로그램을 진짜 XG5000 이 프로젝트로 만들고 검사한 .xgwx 로 돌려주는 생성 엔진이다(CPU 35종: XGI·XGR ST, XGB(IEC) IL, XGK·XGB 래더). 설치형은 원본 파일을 PC 에 저장하지만, 요청한 소스와 분석 결과는 연결한 AI 로 전달한다. 원격 MCP 는 계정 서버를 경유한다. LS ELECTRIC 공식 소프트웨어가 아니다.

## 1. 내려받기 [사람]

1. 브라우저에서 https://works.autohano.com/download 를 열고 구글·네이버·카카오로 로그인하면 `AutoHanoWorks.zip` 이 내려온다. 로그인 없이 받는 길은 없다.
2. zip 을 아무 폴더(예: `C:\AutoHano`)에 풀고, AI 에게 그 폴더 경로를 알려 준다.

## 2. 실행 (AI 가 해도 된다)

- 폴더 안 `AutoHanoWorks.exe` 를 실행한다. 설치 프로그램이 아니다 — 실행이 곧 설치이며, 트레이에 남고 작은 창(런처)이 뜬다. 처음 한 번 Windows SmartScreen 이 "Windows의 PC 보호" 를 띄우면 **[사람]** [추가 정보] → [실행].
- 화면 주소는 `http://127.0.0.1:4011` 이다(환경변수 `WORKBENCH_PORT` 로 바꿨으면 그 포트). 트레이 아이콘 메뉴의 [Works 열기] 로도 열린다. 켜져 있는지는 `GET /api/health`.
- 처음 켜면 작은 창의 로그인 줄이 펼쳐져 있다. **[사람]** 구글·네이버·카카오 중 하나를 눌러 브라우저에서 로그인하고, [Works 열기] 에서 약관에 동의한다. 계정은 한 번에 PC 한 대에서만 쓴다.

## 3. AI 도구에 연결

두 길이 있다. 같은 도구 목록이다. 손님 PC 에서는 exe 를 누르면 뜨는 **런처 창의 [AI 에 연결]** 이 이 PC 의 Claude 데스크톱·Claude Code·Cursor·Codex 에 단추 하나로 붙여 준다 — 아래는 AI 가 직접 설정할 때의 안내다.

**A. 인터넷 커넥터 (Claude 웹·앱, ChatGPT, Claude Code 어디서나)** — 주소 하나: `https://works.autohano.com/mcp`
- Claude Code(다른 PC 에서): `claude mcp add --transport http autohano-works https://works.autohano.com/mcp` 를 실행한 뒤, 처음 쓸 때 열리는 로그인 화면에서 **[사람]** Works 와 같은 계정으로 로그인한다. Works 와 같은 PC 의 Claude Code·Codex 는 아래 B 가 기본이다.
- Claude(웹·앱)·ChatGPT: **[사람]** 설정 → 커넥터 → 사용자 지정 커넥터 추가 → 위 주소 → 로그인. 각 회사의 유료 플랜에서 열리는 경우가 많다.
- 도구는 이 PC 의 Works 가 실행한다. Works 가 꺼져 있으면 도구가 "Works 를 켜 주세요" 를 돌려준다.

**B. 이 PC 안에서 직접 (서버 없이, Claude Code·Codex·Cursor) — 같은 PC 면 이쪽이 빠르고 로그인 창이 없다**

`<풀린 폴더>` 는 지금 켜져 있는 Works 의 폴더다 — `GET http://127.0.0.1:4011/api/mcp/info` 의 `command`(…\runtime\node.exe)가 있는 곳.
1. 확인: `claude mcp get autohano-workbench` · `codex mcp get autohano-workbench`. Command 가 `<풀린 폴더>\runtime\node.exe` 면 이미 연결돼 있다("Connected" 만으로는 맞는 폴더인지 모른다 — 경로를 본다).
2. 다른 폴더를 가리키면 지운다: `claude mcp remove autohano-workbench -s user` · `codex mcp remove autohano-workbench`.
3. 넣는다:
   - Claude Code: `claude mcp add autohano-workbench -s user -e WORKBENCH_API=http://127.0.0.1:4011 -- "<풀린 폴더>\runtime\node.exe" "<풀린 폴더>\app\mcp.mjs"`
   - Codex: `codex mcp add autohano-workbench --env WORKBENCH_API=http://127.0.0.1:4011 -- "<풀린 폴더>\runtime\node.exe" "<풀린 폴더>\app\mcp.mjs"`
   - 이 PC 경로가 들어간 같은 명령: `/api/mcp/info` 의 `snippets.claude` · `snippets.codexCli`, Works 화면 [설정 → AI 연결] 의 복사 버튼, 풀린 폴더의 `CLAUDE.md`·`AGENTS.md`.
4. AI 도구를 새로 시작해야 도구가 보인다. 이름이 다른 기존 MCP 는 건드리지 않는다.

## 4. 무제한 요금제 기능: 내 PC 생성 엔진 (선택)

xgwx 생성을 제한 없이 이 PC 에서 하려면 엔진을 설치한다(무제한·체험). 작은 창의 [내 PC 엔진 설치 → 내 PC 에 설치], 화면 [설정 → 내 PC 생성 엔진 → 내 PC 에 설치], 또는 API `POST /api/engine/install`. 처음 한 번 약 10분, 내려받기 약 1GB, 디스크 여유 8GB. 진행 상태는 `GET /api/engine/status` — `installing` 이 false 가 되면 `phase` 를 본다. 멈추면 `hint` 가 그 자리에서 할 일을 사람 말로 준다.

| `phase` | 할 일 |
|---|---|
| `reboot` + `wsl: "missing"` | `POST /api/engine/wsl-install` — Windows 관리자 승인 창이 뜬다. **[사람]** "예". 끝나면 **[사람]** PC 다시 시작 → Works 다시 실행 → `POST /api/engine/install` |
| `reboot` (준비 끝) | **[사람]** PC 다시 시작 → Works 다시 실행 → `POST /api/engine/install` |
| `bios` | 먼저 **[사람]** 다시 시작 후 `POST /api/engine/install`. 그래도 `bios` 면 **[사람]** BIOS 에서 가상화(Intel VT-x / AMD SVM) 켜기 — 프로그램이 대신할 수 없다 |
| `need-xg5000` | **[사람]** LS ELECTRIC 홈페이지에서 XG5000 설치 파일을 받는다(이름이 `XG5000` 으로 시작하는 .exe 또는 받은 .zip 그대로). `POST /api/engine/installer` — 헤더 `x-file-name: <URL 인코딩한 파일 이름>`, 본문 = 파일 바이트 그대로(예: `curl --data-binary @<파일> -H "x-file-name: <이름>" http://127.0.0.1:4011/api/engine/installer`) → `POST /api/engine/install` |
| `error` | `hint` 대로 `POST /api/engine/install` 로 다시 시도. 같은 자리에서 또 멈추면 상태의 `error`·`log` 를 사람에게 보여 주고 support@autohano.com |
| `ready` + `ready: true` | 끝. `generate_xgwx`·`edit_program`·`change_program`·`check_xgwx` 가 이 PC 에서 돈다 |

## 5. 처음 해 볼 것

연결이 되면 AI 는 먼저 `workbench_status` 를 부른다.

- **"이 파일(폴더) 분석해 줘"**: `add_file(path=전체 경로)` → 받은 versionId 로 `project_summary`(프로그램 이름) → `list_variables`(변수·디바이스 표: 설명·읽기/쓰기·쓰인 렁) → `program_ladder`(렁마다 "조건 → 출력" — OR 가지·병렬 출력까지 파일 그대로, 괄호 안은 디바이스 설명) · `st_source`. 작화(.xpd)는 `screen_objects`.
- **"서보(○○) 시퀀스 확인해 줘"**: `list_variables(query="서보")`·`원점`·`알람`·`APM`·`XPM` 등으로 신호와 쓰인 렁을 찾고 → `program_ladder(query=디바이스)` 로 그 렁들을 순서대로 읽어 순서·조건·인터록을 설명한다. 파일에 없는 것은 "확인 필요".
- **"변수 정리해 줘"**: `list_variables` 전체 + `only=unused`(안 쓰임)·`no-comment`(설명 없음)·`multi-write`(쓰기 여러 곳 — SET/RST 짝도 세므로 이중 코일인지는 렁으로 확인)·`io`(입출력). 정리안은 제안으로 주고, 적용은 사람이 XG5000 에서 한다.
- **"통신 설정 정리해 줘"**: `comm_settings` — 온라인 접속(PC→PLC)·CPU 내장 이더넷·Cnet 채널(RS-485·속도·국번·동작 모드)·FEnet IP·모드버스 서버 주소표·P2P 블록("0x40100 → D00100" 처럼 어디서 어디로)·고속 링크. 인버터·계량기·HMI 와 무엇을 주고받는지 한 번에 본다.

생성 전에는 `generate_profiles`(CPU 목록·입력 형식·거절 규칙·예시)를 부른다. 생성은 `generate_xgwx`(register=true 로 바로 이력 등록, compile=true 면 시뮬레이터로 실제 컴파일·실행까지 확인), 나중 등록은 `register_xgwx`(작업 id). 예: "펌프장 예시를 XGK-CPUA 래더로 만들어 XG5000 으로 열어 줘" → `generate_profiles(sample=pump-station)` → `generate_xgwx(cpu=XGK-CPUA, program=…, open=true)`.

기존 프로젝트 고치기(내 PC 엔진): 먼저 `dryRun=true` 로 어떻게 바뀌는지 보고, 그다음 실제로 고친다(엔진 한 번에 2~4분).

- **프로그램 글 고치기** `edit_program`: ST·IL 은 `st_source` 로 지금 글을 받아 고친 전체 글(`source`) 또는 고칠 곳만(`replace`). 래더(XGK·XGB·XGI)는 `program_ladder(format=il)` 의 렁 번호로 `rungs` 에 렁 단위 — 바꾸기 `{rung, il}` · 지우기 `{rung, remove}` · 끼워 넣기 `{after, il}`. 새 변수는 `variables` 로 같이.
- **프로그램 더하기·이름 바꾸기·지우기** `change_program`. 여러 번 이어서 할 때는 `versionId` 대신 앞 작업 id 를 `fromJob` 으로 주고 마지막에만 `register=true` — 중간 버전이 이력에 쌓이지 않는다.
- **검사만** `check_xgwx`: 고치지 않고 XG5000 프로그램 검사(오류·경고·이중 코일 자리).
- 결과의 「증명」 은 Works 가 고친 파일을 원본과 견준 것이다(바란 곳만 바뀌었는지, 나머지 프로그램·변수·설정이 그대로인지). 증명 통과와 검사 오류 0 일 때 `register=true` 로 같은 프로젝트의 새 버전이 된다.

## 원칙

- Works 는 원본 파일을 고치지 않는다 — 고치기는 사본을 이 PC 의 XG5000 이 고치고 검사한 뒤 새 버전으로 넣는다. AI 가 낸 결론·초안·고친 버전은 실제 설비에 넣기 전에 사람이 XG5000 에서 확인한다.
- 내 PC 엔진은 프로그램 생성·고치기·검사를 PC 에서 실행한다. 원격 MCP 로 요청하면 프로그램 입력과 결과가 계정 서버를 경유한다. 생성 서버를 이용하면 프로그램 입력을 서버로 보낸다.
- 문의: support@autohano.com