# Heimdal 설치 안내 (에이전트용)

이 문서는 초대받은 사람의 코딩 에이전트가 읽고 그대로 실행하는 설치 절차입니다.
설치되는 것은 웹 클라이언트 **saya** 와, saya 가 보여 줄 메신저 연결들입니다. 모두 이 기계 안에서만 돌고,
`127.0.0.1` 에만 열립니다.

## 에이전트가 지킬 것

- **초대코드와 토큰을 출력·기록·커밋하지 않는다.** 초대코드는 `HEIMDAL_CODE` 환경 변수로만 넘기고, 명령 인자나 파일에 쓰지 않는다.
- **메신저에 로그인하거나 메시지를 보내지 않는다.** 로그인·권한 부여는 아래 "사람이 할 일"을 사람에게 그대로 전한다.
- `sudo`, 시스템 설정 변경은 사람에게 먼저 묻는다.
- 설치가 `SHA-256 does not match` 로 멈추면 **다시 시도하지 말고** 멈춰서 알린다.
- 결과는 설치 스크립트가 마지막에 출력하는 JSON 으로 판단한다.

## 1. 사람에게 물을 것

1. 초대코드 (`HMD-` 로 시작)
2. 무엇을 설치할지

| 구성요소 | 무엇 | Windows | macOS | Linux |
|---|---|---|---|---|
| `saya` | 웹 화면 (브라우저로 엶) | ✓ | ✓ | ✓ |
| `kanao` | PC 카카오톡 연결 | ✓ | | |
| `kamado` | Mac 카카오톡 연결 | | ✓ | |
| `chatplus-core` | 채팅+ 연결 | ✓ | ✓ | |
| `tsuba` | 텔레그램·디스코드·슬랙 연결 (어댑터를 골라야 함) | ✓ | ✓ | ✓ |

tsuba 를 고르면 어댑터도 묻습니다: `telegram`, `discord`(봇), `slack`, `discord-user`(개인 계정, Discord 약관 위반 위험이 있음을 알릴 것).

**kanao·kamado(카카오톡)를 고르면 설치 전에 반드시 알릴 것:** 카카오 공식 기능이 아니며(저장된 대화를 직접 읽고, 창을 대신 눌러 보냄)
카카오 이용약관상 계정이 일시 또는 영구 제한될 수 있다. 사람이 이해하고 동의한 뒤에만 설치한다.

## 2. 설치

### Windows (PowerShell)

```powershell
$env:HEIMDAL_CODE = "<초대코드>"
& ([scriptblock]::Create((irm https://heimdal.sanguneo.com/install.ps1))) -Components saya,kanao,chatplus-core,tsuba -Tsuba telegram
```

### macOS / Linux

```sh
export HEIMDAL_CODE='<초대코드>'
curl -fsSL https://heimdal.sanguneo.com/install.sh | bash -s -- --components saya,kamado,chatplus-core,tsuba --tsuba telegram
```

설치 위치: Windows `%LOCALAPPDATA%\Heimdal`, macOS `~/Library/Application Support/Heimdal`, Linux `~/.local/share/heimdal`.
로그인할 때 자동으로 시작합니다(Windows 작업 스케줄러, macOS LaunchAgent, Linux `systemd --user`).

## 3. 결과 읽기

마지막 출력에서:

- `services` / `healthy`: 각 구성요소가 응답하는지. 하나라도 `false` 면 종료 코드 3. 로그는 `logs` 폴더의 `<이름>.log`.
- `sayaLists`: saya 에 등록된 연결(`kakao` 는 카카오톡). 사람이 고른 것이 다 보이면 끝입니다.
- `saya`: 브라우저로 열 주소 (기본 `http://127.0.0.1:8080/`).
- `needsHuman` / `needs_human`: 아래 "사람이 할 일". 그대로 사람에게 전하고, 했다고 하면 **같은 설치 명령을 다시 실행**합니다.

## 4. 사람이 할 일

| 상황 | 할 일 |
|---|---|
| kanao | PC 카카오톡을 켜 두고 로그인 상태 유지. 카카오톡은 PC 한 곳에서만 로그인되므로 Mac 의 kamado 와 동시에 쓰지 않음 |
| kamado (macOS) | 시스템 설정 › 개인정보 보호 및 보안 › **전체 디스크 접근 권한**과 **손쉬운 사용**에 안내된 `kamado` 파일을 추가하고 켜기. 카카오톡 로그인 유지 |
| chatplus-core | 채팅+ 를 켜 두고 로그인 유지. macOS 는 kamado 와 같은 두 권한을 `chatplus-core` 파일에 |
| tsuba telegram | https://my.telegram.org 에서 API ID/HASH 를 **본인 것으로** 발급해 안내된 `tsuba-telegram.user.env` 에 적기 → 설치 명령 다시 실행 → 안내된 `run … tsuba-telegram login` 으로 전화번호·코드 입력 → 설치 명령 다시 실행 |
| tsuba discord | Discord 개발자 포털에서 봇을 만들고 Message Content Intent 를 켠 뒤 봇 토큰을 `tsuba-discord.user.env` 에 |
| tsuba slack | 본인 워크스페이스에 Slack 앱을 만들고(사용자 토큰 `xoxp-`, Socket Mode 앱 토큰 `xapp-`) `tsuba-slack.user.env` 에 |
| tsuba discord-user | 본인 계정 토큰을 `tsuba-discord-user.user.env` 에. Discord 약관상 계정 제재 위험이 있음 |
| Linux | 로그아웃 뒤에도 돌게 하려면 `sudo loginctl enable-linger $USER` |

`.user.env` 파일은 사용자만 읽을 수 있게 만들어집니다. 값을 채울 때 화면에 출력하지 마세요.

## 5. 업데이트·상태·제거

- 업데이트: 같은 설치 명령을 다시 실행 (초대코드는 처음 한 번 저장되므로 `HEIMDAL_CODE` 없이도 됨). 이전 버전 하나는 남겨 둡니다.
- 상태: Windows `-Action status`, macOS/Linux `--status`.
- 제거: Windows `-Action uninstall` (`-Purge` 면 설정·세션까지), macOS/Linux `--uninstall` (`--purge`).

## 6. saya 를 다른 기계에 둘 때 (선택)

saya 와 연결들을 서로 다른 기계에 두려면 두 기계가 같은 Tailscale tailnet 에 있어야 합니다.

1. saya 기계: 평소대로 `saya` 를 설치하고, 사람에게 `tailscale serve --bg --https=8798 http://127.0.0.1:8798` 을 부탁합니다.
   등록 토큰은 설정 폴더 `config/state`(macOS/Linux) 또는 `config\state.json`(Windows)의 `saya-register` 값입니다. **화면에 출력하지 말고** 파일째 옮깁니다.
2. 연결을 돌릴 기계: 그 토큰을 `config/saya-register-token` 파일로 두고,
   `HEIMDAL_REGISTER_URL=https://<saya 기계>.<tailnet>.ts.net:8798`, `HEIMDAL_ADVERTISE_HOST=https://<이 기계>.<tailnet>.ts.net` 을 주고 설치합니다.
   각 연결 포트마다 사람에게 `tailscale serve --bg --https=<포트> http://127.0.0.1:<포트>` 를 부탁합니다.

## 문제가 생기면

- `the invite code was not accepted (401)`: 코드가 틀렸거나 폐기됨. 초대한 사람에게 문의.
- `<구성요소> has no <플랫폼> build`: 그 기계용 빌드가 아직 없음.
- `healthy: false`: `logs/<이름>.log` 의 마지막 줄을 사람에게 보여 줌(토큰이 없는지 확인 후).
- saya 에 카카오톡이 안 보임: 카카오톡이 꺼져 있거나 로그아웃 상태. 등록 문제가 아님.