zigmini 0.8.0-beta.2 → 0.8.0-beta.4

package/README.ko.md

@@ -0,0 +1,267 @@
+[English](README.md) | 한국어
+
+# zigmini
+
+zigmini는 맥에서 도는 개인 AI 에이전트 게이트웨이입니다. 맥의 웹 화면과 Android 앱에서 에이전트(OMO)와 대화하고, 작업을 맡기고, 알림을 받습니다. 게이트웨이와 브리지는 macOS 로그인 때 launchd가 자동으로 띄웁니다. Docker는 필요하지 않습니다.
+
+## 요구 사항
+
+- Apple Silicon(M칩) 맥과 macOS. Intel 맥, Linux, Windows는 지원하지 않습니다.
+- [Bun](https://bun.sh) 1.4.0 이상. 설치에는 Bun만 필요합니다. Node.js와 npm은 필요하지 않습니다.
+- 에이전트가 쓸 모델 계정(예: Claude, ChatGPT 구독). 설치 뒤 로그인합니다.
+- (선택) Android 폰. 앱은 게이트웨이가 직접 제공합니다.
+- (선택) 폰을 밖에서 쓰려면 Tailscale 또는 HTTPS 리버스 프록시가 있는 자기 도메인.
+
+## 권한 안내
+
+zigmini는 에이전트를 권한 프리셋 `full-access`로 실행합니다. 에이전트는 도구를 쓸 때마다 승인을 받지 않습니다. 셸 명령은 샌드박스 없이 이 macOS 사용자 계정의 권한으로 실행됩니다. 등록한 폰 앱이 보낸 요청도 같은 권한으로 실행됩니다.
+
+`zigmini setup`은 설치 전에 권한 안내문 전체를 보여 줍니다. `동의`를 정확히 입력해야만 설치합니다. 다른 입력이나 Enter는 동의 안 함이고, 그러면 아무것도 설치하지 않습니다. 동의를 건너뛰는 옵션은 없습니다. 안내문이 바뀌면 다시 동의할 때까지 게이트웨이가 시작하지 않습니다. 이때는 맥 터미널에서 `zigmini consent`를 실행합니다.
+
+## 설치
+
+1. Bun 버전을 확인합니다. zigmini에는 Bun `1.4.0` 이상이 필요합니다.
+   ```sh
+   bun --version
+   ```
+   - 결과가 `1.4.0` 이상(예: `1.4.2`)이면 8번으로 갑니다.
+   - 결과가 `1.4.0`보다 낮으면(예: `1.3.5`) 2번으로 갑니다.
+   - 결과가 `zsh: command not found: bun`이면 4번으로 갑니다.
+2. Bun의 설치 위치를 확인합니다.
+   ```sh
+   which bun
+   ```
+   - 결과가 `/opt/homebrew/bin/bun`이면 Homebrew로 설치한 Bun입니다. `brew upgrade bun`을 실행합니다. 그다음 3번으로 갑니다.
+   - 결과가 `/.bun/bin/bun`으로 끝나면 공식 설치 스크립트로 설치한 Bun입니다. `bun upgrade`를 실행합니다. 그다음 3번으로 갑니다.
+   - 결과가 위 두 경로가 아니면 4번으로 갑니다. 4번은 공식 스크립트로 `~/.bun/bin`에 새 Bun을 설치하고, 6번은 그 폴더를 PATH의 앞에 둡니다.
+3. 1번 명령을 다시 실행합니다.
+   - 결과가 `1.4.0` 이상이면 8번으로 갑니다.
+   - 결과가 여전히 `1.4.0`보다 낮으면 4번으로 갑니다.
+4. (1번 결과가 `zsh: command not found: bun`이거나 2번·3번에서 이리로 왔을 때만) Bun을 공식 설치 스크립트로 설치합니다.
+   ```sh
+   curl -fsSL https://bun.sh/install | bash
+   ```
+   - 이 스크립트는 Bun을 `~/.bun/bin/bun`에 설치합니다.
+   - `~/.zshrc` 파일이 있으면 스크립트는 그 파일 끝에 PATH 설정 줄을 추가하고 `Added "~/.bun/bin" to $PATH in "~/.zshrc"`를 출력합니다.
+   - `~/.zshrc` 파일이 없으면 스크립트는 아무 파일도 바꾸지 않고 `Manually add the directory to ~/.zshrc (or similar):`를 출력합니다. 이때는 새 터미널 창에서도 `bun`을 찾지 못합니다.
+5. `~/.zshrc` 파일이 있는지 확인합니다.
+   ```sh
+   ls ~/.zshrc
+   ```
+   - 결과가 `/.zshrc`로 끝나는 경로 한 줄이면 4번의 스크립트가 PATH 설정 줄을 추가했습니다. 6번으로 갑니다.
+   - 결과가 `No such file or directory`로 끝나면 이 명령으로 PATH 설정 줄을 씁니다. 이 명령은 `~/.zshrc`를 만들고, 스크립트가 쓰는 것과 같은 줄을 씁니다. 이후 새로 여는 터미널 창은 `bun`을 찾습니다. 그다음 6번으로 갑니다.
+     ```sh
+     printf '\n# bun\nexport BUN_INSTALL="$HOME/.bun"\nexport PATH="$BUN_INSTALL/bin:$PATH"\n' >> ~/.zshrc
+     ```
+6. 지금 터미널 창에서 Bun 폴더를 PATH에 넣습니다. 이 명령은 지금 터미널 창에만 적용되고 파일을 바꾸지 않습니다.
+   ```sh
+   export PATH="$HOME/.bun/bin:$PATH"
+   ```
+7. 1번 명령을 다시 실행합니다.
+   - 결과가 `1.4.0` 이상이면 8번으로 갑니다.
+   - 결과가 오류이면 설치를 멈춥니다. 4번 스크립트의 출력에서 `error:`로 시작하는 줄을 확인합니다.
+8. zigmini를 설치합니다. 설치 스크립트(postinstall)는 없습니다. 이 단계는 파일만 받습니다.
+   ```sh
+   bun add -g zigmini
+   ```
+   - `zigmini setup`(15번)을 마칠 때까지 다른 명령은 오류 출력에 `` 아직 설치를 마치지 않았습니다. 먼저 `zigmini setup`을 실행하세요. ``를 보여 줍니다. `--version`, `--help`, `setup`, `consent`, `migrate`, `migrate-run`은 이 줄을 보여 주지 않습니다. `zigmini --help`도 먼저 setup을 실행하라고 안내합니다.
+9. `zigmini` 명령을 찾는지 확인합니다.
+   ```sh
+   zigmini --version
+   ```
+   - 결과가 숫자로 시작하는 버전 한 줄(예: `0.8.0-beta.3`)이면 15번으로 갑니다.
+   - 결과가 `zsh: command not found: zigmini`이면 Bun 전역 명령 폴더가 PATH에 없습니다. 10번으로 갑니다.
+10. 지금 터미널 창에서 Bun 전역 명령 폴더를 PATH에 넣습니다. 이 명령은 지금 터미널 창에만 적용되고 파일을 바꾸지 않습니다.
+    ```sh
+    export PATH="$(bun pm bin -g):$PATH"
+    ```
+11. `~/.zshrc` 파일이 있는지 확인합니다.
+    ```sh
+    ls ~/.zshrc
+    ```
+    - 결과가 `/.zshrc`로 끝나는 경로 한 줄이면 12번으로 갑니다.
+    - 결과가 `No such file or directory`로 끝나면 13번으로 갑니다.
+12. `~/.zshrc`에 Bun 전역 명령 폴더가 이미 있는지 확인합니다.
+    ```sh
+    grep -cF "$(bun pm bin -g)" ~/.zshrc
+    ```
+    - 결과가 `0`이면 13번으로 갑니다.
+    - 결과가 `1` 이상이면 이 폴더는 이미 `~/.zshrc`에 있습니다. 새로 여는 터미널 창은 이 폴더를 찾습니다. 14번으로 갑니다.
+13. `~/.zshrc` 끝에 Bun 전역 명령 폴더를 PATH에 넣는 줄을 씁니다. 파일이 없으면 이 명령이 파일을 만듭니다. 줄에는 `bun pm bin -g`가 출력한 폴더 경로가 들어갑니다. 이후 새로 여는 터미널 창은 이 폴더를 찾습니다.
+    ```sh
+    printf '\nexport PATH="%s:$PATH"\n' "$(bun pm bin -g)" >> ~/.zshrc
+    ```
+14. 9번 명령을 다시 실행합니다.
+    - 결과가 숫자로 시작하는 버전 한 줄이면 15번으로 갑니다.
+    - 결과가 여전히 `zsh: command not found: zigmini`이면 설치를 멈춥니다. `ls "$(bun pm bin -g)"`를 실행합니다. 결과에 `zigmini`가 없으면 8번의 `bun add -g zigmini` 출력에서 `error:`로 시작하는 줄을 확인합니다.
+15. 설치를 마칩니다.
+   ```sh
+   zigmini setup
+   ```
+
+`zigmini setup`은 아래 순서로 진행합니다. 다시 실행해도 됩니다. 이미 끝난 단계는 그대로 둡니다.
+
+1. 권한 안내를 보여 주고 동의를 받습니다.
+2. 홈 폴더 `~/.zigmini`를 만듭니다. 이 설치의 규칙 파일(`~/.zigmini/rules.md`)이 없으면 빈 파일을 만듭니다. 아래 "에이전트 규칙"을 보세요.
+3. 에이전트 엔진(OMO, omo-ai)의 고정 버전을 내려받아 해시를 확인하고 패치합니다. 버전은 패키지가 정합니다(`src/engine/compat.json`, 이 문서를 쓸 때 OMO 5.1.35). 엔진 라이선스 요약을 보여 주고 동의(`y`)를 받습니다.
+4. 에이전트 폴더와 모델 계정 로그인 상태를 확인합니다. 기본 에이전트 폴더는 `~/.omo/agent`이고, 같은 폴더를 쓰는 다른 OMO와 로그인 정보를 같이 씁니다. 로그인하지 않았으면 로그인 명령을 출력합니다. 그 명령을 실행한 뒤 `/login`을 입력합니다.
+5. Notion 토큰을 묻습니다(선택). 비우면 일정 기능이 꺼집니다.
+6. 외부 접속 방식을 묻습니다. 아래 "외부 접속"을 보세요.
+7. 서비스 설정(`~/.zigmini/config.env`, 권한 프리셋 `full-access`)을 쓰고 음성은 꺼 둡니다.
+8. 게이트웨이와 브리지를 launchd에 등록하고 시작합니다. 게이트웨이가 준비될 때까지 기다립니다(최대 600초).
+9. 자기 도메인을 골랐으면 그 도메인이 앱 포트에 닿는지 확인합니다.
+10. 앱 내려받기 QR과 폰 등록 QR을 터미널에 그립니다.
+
+설치가 끝나면 맥의 브라우저에서 http://127.0.0.1:8700 을 엽니다.
+
+묻지 않고 설치하려면 옵션을 씁니다. 권한 동의는 이때도 입력해야 합니다.
+```sh
+zigmini setup --non-interactive --accept-license --access lan
+```
+
+| 옵션 | 뜻 |
+|---|---|
+| `--non-interactive` | 묻지 않습니다 |
+| `--accept-license` | 엔진 라이선스에 동의합니다 |
+| `--agent-dir <경로>` | 공유 `~/.omo/agent` 대신 쓸 전용 에이전트 폴더 |
+| `--notion-token-file <경로>` | Notion 토큰 파일 |
+| `--access <tailscale\|lan\|domain>`, `--domain <https://주소>` | 외부 접속 방식 |
+| `--engine-only` | 엔진 설치 단계만 실행합니다 |
+
+## 외부 접속
+
+웹 화면은 맥 안(`127.0.0.1`)에서만 열립니다. 폰 앱은 별도의 앱 포트(기본 8701)로 접속합니다. 앱 포트로 가는 길은 세 가지 중 하나를 고릅니다. 고른 주소가 폰 등록 QR에 들어갑니다.
+
+| 방식 | 옵션 | 폰이 쓸 수 있는 곳 | 준비 |
+|---|---|---|---|
+| Tailscale | `--access tailscale` | 어디서나 | 맥과 폰에 Tailscale을 설치하고 같은 계정으로 로그인합니다. Tailscale 관리 화면에서 MagicDNS를 켭니다 |
+| 집 Wi-Fi | `--access lan` | 맥과 같은 네트워크 | 없습니다. 맥의 사설 IP 주소를 씁니다 |
+| 자기 도메인 | `--access domain --domain https://<도메인>` | 어디서나 | 앱 포트로 전달하는 HTTPS 리버스 프록시. `https://` 주소만 받습니다 |
+
+나중에 바꾸려면 `zigmini setup --access <방식>`을 다시 실행하거나, 웹 화면 설정의 "외부 접속"에서 바꿉니다. 고르지 않으면 폰은 접속할 수 없습니다.
+
+## 폰 등록
+
+1. 폰에서 앱 내려받기 QR을 찍어 APK를 받고 설치합니다. 설치할 때 Android가 "출처를 알 수 없는 앱" 허용을 물으면 허용합니다.
+2. 앱 첫 화면에서 "QR로 등록"을 눌러 폰 등록 QR을 찍습니다.
+
+앱 첫 화면에는 카메라 없이 등록하는 "게이트웨이 주소"와 "등록 토큰 붙여 넣기" 칸도 있습니다. 토큰 칸에는 등록 QR이 담은 `zigmini://enroll?...` 글 전체를 붙여 넣을 수 있습니다. 이때는 그 글의 주소를 씁니다. 토큰은 한 번만, 유효 시간 안에서만 쓸 수 있습니다.
+
+두 QR은 `zigmini setup`의 마지막에 나옵니다. 다시 만들려면 아래 명령이나 웹 화면 설정의 "기기 등록"·"앱 내려받기"를 씁니다. 게이트웨이가 실행 중이어야 합니다.
+```sh
+zigmini pair --apk   # 앱 내려받기 QR (유효 10분)
+zigmini pair         # 폰 등록 QR (유효 10분, 한 번 사용)
+```
+
+앱 하나로 게이트웨이 여러 개를 등록할 수 있습니다. 게이트웨이마다 주소와 인증 값을 따로 저장하고, 모든 게이트웨이의 알림을 받습니다. 알림을 누르면 그 게이트웨이로 바뀝니다. 등록한 기기는 웹 화면 설정의 "등록된 기기"에서 확인합니다.
+
+## 앱 서명 지문
+
+zigmini 패키지에 들어 있는 Android 앱(APK)은 아래 인증서 하나로만 서명되어 있습니다. 받은 APK가 진짜인지 확인하려면 APK 파일에서 서명 인증서의 SHA-256 지문을 읽어 아래 값과 비교합니다. 예: Android SDK의 `apksigner verify --print-certs zigmini.apk` 출력의 `certificate SHA-256 digest`(콜론 없이 소문자로 나옵니다) 또는 JDK의 `keytool -printcert -jarfile zigmini.apk` 출력의 `SHA256`. 인증서가 둘 이상이거나 값이 다르면 설치하지 마세요.
+
+```text
+F0:AB:B3:B2:DC:70:1A:45:19:85:69:7D:58:68:F5:FB:4F:AC:33:4F:D8:6A:68:DD:04:5C:53:B2:5C:94:77:8C
+```
+
+## 사용자 매뉴얼
+
+사용자 매뉴얼([한국어](docs/manual.ko.md), [English](docs/manual.md))은 웹 설정 창 위쪽의 "매뉴얼" 버튼과, 앱 헤더의 상태 태그를 짧게 눌러 여는 연결 화면의 "매뉴얼" 버튼으로 봅니다.
+
+## 음성
+
+새 설치에서 음성은 꺼져 있습니다. 음성 인식과 음성 합성을 쓰려면 맥의 웹 화면 위쪽의 "음성 설치" 버튼을 누릅니다. 버튼에 내려받을 크기가 보입니다. 게이트웨이가 uv, Python 환경, 음성 모델(약 8GB)을 `~/.zigmini/voice`에 내려받습니다. 진행률은 채팅에 나옵니다. 실패하면 같은 버튼으로 실패한 단계부터 다시 시작합니다. 설치가 끝나면 "음성 꺼짐"을 눌러 켭니다. 음성 설치와 켜기·끄기는 맥의 웹 화면에서 합니다. 앱은 음성 상태만 보여 줍니다. 웹 화면 위쪽에서 "호출어", "박수 감지"(박수 두 번), "음성 답변"도 켭니다.
+
+## 업데이트
+
+새 버전이 나오면 웹 화면 위쪽에 새 버전 줄이 나오고, 앱에도 버전 알림이 나옵니다. 업데이트는 웹 화면 설정의 "업데이트" 버튼("지금 확인"은 새 버전을 확인합니다), 앱 버전 알림의 "업데이트" 버튼, 또는 아래 명령으로 합니다.
+```sh
+zigmini update            # latest로 업데이트
+zigmini update <버전>     # 지정한 버전으로 업데이트
+```
+
+업데이트는 DB를 백업하고, 새 버전을 설치하고, 다시 시작한 뒤 상태를 확인합니다. 확인에 실패하면 이전 버전으로 자동으로 되돌립니다. 권한 안내문이 바뀐 업데이트는 맥에서 새 안내문에 동의한 뒤 진행합니다. 앱에서는 새 안내문에 동의할 수 없습니다.
+
+확인함에 답을 기다리는 질문(main과 작업)이 있으면 업데이트를 시작하지 않습니다. 확인함에서 질문에 먼저 답하거나 질문을 지우세요. `--force`로도 넘길 수 없습니다.
+
+새 앱 버전이 있으면 앱에 "새 앱 버전"과 "내려받기" 버튼이 나옵니다. 버튼은 게이트웨이에서 APK를 내려받습니다. Android가 출처를 알 수 없는 앱 설치 허가를 묻습니다.
+
+새 버전이 무중단 전환을 지원하면(0.8.0-beta.1 다음 버전부터) 진행 중인 턴을 끊지 않습니다.
+
+1. 새 브리지와 OMO(새 실행 세대)가 다른 포트에서 먼저 뜨고 확인을 받습니다. 확인에 실패하면 실행 중인 것은 그대로 두고 설치만 되돌립니다.
+2. 게이트웨이만 다시 시작합니다. 웹과 폰은 수 초 뒤 다시 연결됩니다.
+3. 새 세션은 새 세대에서 열립니다. 이전 세대의 세션은 각자 턴이 끝나면 새 세대로 옮겨집니다.
+4. 이전 세대는 세션이 모두 옮겨지면 끝납니다. 메모리가 충분하면 최대 6시간, 아니면 최대 1시간을 기다립니다. 그때까지 끝나지 않은 턴은 끊깁니다. 마무리되면 main 채팅에 한 줄 알림이 옵니다.
+5. 이전 세대를 정리하는 동안에는 다음 업데이트를 받지 않습니다.
+
+무중단 전환을 지원하지 않는 버전으로 가는 업데이트(0.8.0-beta.1로 가는 업데이트 포함)는 지금처럼 브리지와 게이트웨이를 함께 다시 시작합니다. 이때는 진행 중인 턴이 있으면 업데이트를 시작하지 않습니다. 턴이 끊겨도 되면 `--force`를 붙입니다.
+
+## 명령
+
+| 명령 | 하는 일 |
+|---|---|
+| `zigmini setup` | 설치합니다 |
+| `zigmini start` | 게이트웨이와 브리지를 launchd에 등록하고 시작합니다 |
+| `zigmini stop` | 게이트웨이와 브리지를 멈춥니다 |
+| `zigmini restart [gateway\|bridge]` | 다시 시작합니다 |
+| `zigmini status` | launchd 상태, health, 권한 동의 상태를 보여 줍니다 |
+| `zigmini doctor [--json] [--fix]` | 전체 상태를 점검합니다 |
+| `zigmini pair [--apk]` | 폰 등록 QR 또는 앱 내려받기 QR을 그립니다 |
+| `zigmini consent` | 권한 안내를 보이고 동의를 기록합니다 |
+| `zigmini update [버전] [--force]` | 업데이트합니다 |
+| `zigmini migrate` | 옛 Docker 설치(`~/.zigmini-gateway`)를 새 구조로 복사합니다. 옛 폴더는 바꾸지 않습니다 |
+| `zigmini migrate-run` | 유휴를 기다리고, 옛 실행을 멈추고, 백업하고, migrate와 setup을 실행한 뒤 확인합니다. 실패하면 옛 실행으로 되돌립니다 |
+| `zigmini --version` | 설치된 버전을 출력합니다 |
+| `zigmini --help` | 도움말을 출력합니다 |
+
+채팅에서 `/usage`를 보내면 게이트웨이가 로그인한 모델 계정의 사용량을 바로 답합니다.
+
+## 에이전트 규칙
+
+브리지는 에이전트 세션마다 지시문 뒤에 규칙 파일 두 개를 붙입니다.
+
+- 패키지의 `assets/agent/gateway-rules.md`: 모든 설치에 공통인 규칙입니다. 업데이트가 바꿉니다.
+- `~/.zigmini/rules.md`: 이 설치에만 쓰는 규칙(예: 호칭, 언어, 계정)입니다. 사용자가 직접 고칩니다. 두 파일이 부딪치면 이 파일이 이깁니다.
+
+바꾼 뒤에 열리는 세션부터 새 내용을 씁니다. 바로 적용하려면 쉬는 때 `zigmini restart bridge`를 실행합니다.
+
+## 문제 해결
+
+1. 상태를 봅니다.
+   ```sh
+   zigmini status
+   ```
+2. 전체를 점검합니다. 이상 항목과 할 일이 나옵니다.
+   ```sh
+   zigmini doctor
+   ```
+3. 멈춘 에이전트가 있으면 다시 띄웁니다. `--fix`는 이상 있는 launchd 에이전트만 다시 띄웁니다.
+   ```sh
+   zigmini doctor --fix
+   ```
+4. 그래도 안 되면 로그 폴더 `~/.zigmini/logs`를 확인합니다.
+
+- 게이트웨이가 시작하지 않고 권한 동의가 없다고 나오면 `zigmini consent`를 실행합니다.
+- 오래된 DB 백업, 쓰지 않는 엔진 버전, 업데이트에서 남은 파일은 웹 화면 설정의 "정리"에서 확인하고, 고른 항목만 지웁니다.
+
+## 제거
+
+1. 게이트웨이와 브리지를 멈추고 launchd 등록을 지웁니다.
+   ```sh
+   zigmini stop --uninstall
+   ```
+2. 패키지를 지웁니다.
+   ```sh
+   bun remove -g zigmini
+   ```
+3. 데이터를 지웁니다. 대화 기록, 설정, 엔진, 음성 모델이 모두 지워집니다.
+   ```sh
+   rm -rf ~/.zigmini
+   ```
+
+공유 에이전트 폴더 `~/.omo/agent`는 다른 OMO도 쓰므로 지우지 않습니다.
+
+## 라이선스
+
+zigmini는 [Sustainable Use License 1.0](LICENSE.md)으로 배포합니다. 개인적이거나 비상업적인 용도, 회사 내부 업무 용도로 쓸 수 있습니다. 판매하거나 유료 서비스로 제공할 수 없습니다. 정확한 조건은 `LICENSE.md`를 보세요.
+
+설치 때 받는 엔진 omo-ai와 함께 들어 있는 라이브러리의 라이선스는 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)에 있습니다. zigmini는 omo-ai를 패치해 씁니다. 패치한 사본은 수정본입니다.