문제 신고: 보고서에 들어 있는 것

aipager에 버그가 생기면 한 번 눌러서 aipager 개발자에게 문제 신고 보고서를 보낼 수 있어요. 무엇이든 보내기 전에 보고서 전체를 볼 수 있고, 내가 동의하기 전에는 아무것도 내 컴퓨터를 떠나지 않고, 보고서에는 채팅, 메시지, 이름, 경로, token이 절대 들어가지 않아요. 보고서는 정해진 필드 목록으로만 만들어져요. 버전, 횟수, 날짜, 예/아니오 답, 정해진 목록에서 고른 선택지, aipager 자체 코드 안의 위치와 그 버그의 ap1- 이름, 그리고 (내가 썼을 때만) 짧은 메모예요.

보내는 방법#

Telegram에서 보고서를 보낼 수 있는 사람은 aipager 설치의 소유자뿐이에요. 이 설치 자체의 개인 채팅에서 봇과 대화하는 사람(봇 소유자)이에요. 그런 개인 채팅이 여러 개이고 소유자가 한 명으로 정해지지 않으면 “문제 신고” 버튼도 자동 제안도 없지만, 터미널의 aipager report는 그대로 쓸 수 있어요. Mini App에는 자체 신고 페이지가 있고, Telegram에서 들어가는 다른 모든 길은 봇과의 내 개인 채팅에서 같은 미리 보기 카드를 열어요:

• /help: 소유자가 보내면 도움말에 “🐞 문제 신고” 버튼이 함께 와요. 그룹에서는 소유자가 누를 때만 작동하고, 미리 보기는 그룹이 아니라 소유자의 개인 채팅에서 열려요.
• Mini App: 설정 탭에서 “문제 신고”(앱이 내 개인 채팅에서 열렸을 때)는 앱 안에서 페이지를 열어요. 맨 위에 내 메모가 있어요(선택 사항, 최대 500자, 글자 수 표시). 그 아래에는 보고서의 짧은 요약이 있어요. 버전, 설정, 오류(오류를 누르면 코드 안의 위치가 보여요), 그리고 자세히 보기예요. 보고서 원문 보기는 보낼 정확한 글을 내 메모까지 포함해서 보여 주고, 입력하는 대로 바뀌어요. 보고서 보내기(아래쪽 Telegram 버튼)는 정확히 그 내용을 딱 한 번 보내고, 그다음 페이지에 참조 번호와 복사 버튼이 나와요. 뒤로 가면 아무것도 보내지 않아요. aipager가 내 메모를 정리했다면(앞뒤 공백, 보이지 않는 문자, 500자를 넘는 부분) 페이지에 정리된 메모를 보여 주고, “보고서 보내기”를 다시 누를 때까지 아무것도 보내지 않아요.
• 메모리 한도 알림: aipager의 hook이 메모리를 다 쓰면 채팅에 오는 알림에 “🐞 이 문제 신고” 버튼이 있어요.
• 자동 제안: aipager가 가끔 알아챈 버그에 대한 보고서를 보내자고 제안해요(aipager가 보고서를 제안하는 때 참고).
• 터미널에서: aipager report는 보고서를 출력하고 Send this report? [y/N]을 물어요. 같은 종류의 필드가 들어 있지만 실행 중인 aipager에 대한 정보는 더 적어요(모드, 채팅, 기능, 실행 시간, 세션, Claude Code 세부 정보가 비어 있거나 알 수 없음으로 나와요). aipager report --note "what you were doing"은 메모를 더해요. 터미널이 없으면(스크립트, 파이프, Claude Code 세션의 shell) 보고서를 출력만 하고 절대 보내지 않아요.

미리 보기 카드는 보고서를 보내질 모습 그대로 보여 줘요. 펼칠 수 있는 접힌 블록 안의 JSON이거나, 메시지 하나에 다 들어가지 않으면 이 카드에 답장으로 오는 report.json 파일이에요. 버튼은:

• 📤 보내기: 정확히 이 보고서를 딱 한 번 보내요. 그 뒤 카드에 보냈어요. 참조 번호: ap1-...가 나와요.
• ✏️ 메모 추가: 10분 안에 이 채팅에 보내는 다음 메시지가 보고서의 메모가 되고(500자에서 잘려요), 카드는 보내기 전에 그 메모가 들어간 보고서를 다시 보여 줘요. 내가 먼저 다른 일을 하면(명령, 다른 버튼, 사진, Mini App에서의 작업) 메모 질문은 닫히고 메모는 추가되지 않아요. 10분이 지나면 다음 메시지는 평소처럼 Claude에게 가요. 이 질문에는 ‹ 뒤로(메모 없는 미리 보기로 돌아가기)와 취소가 있어요.
• ✖️ 취소: 아무것도 보내지 않아요.

미리 보기는 24시간 동안 열려 있고, 가장 최근 5개가 열려 있어요(6번째를 열면 가장 오래된 것이 닫혀요). aipager가 재시작한 뒤에는 예전 카드로 더 이상 보낼 수 없어요. “문제 신고”를 다시 열어서 새 카드를 받으세요. Mini App에서 연 보고서는 24시간 동안 보낼 수 있어요(가장 최근 3개). 재시작 뒤에는 페이지가 새 보고서를 불러와요.

보고서에 들어 있는 것#

쉬운 말로 항목별로 설명할게요. 미리 보기를 보여 주기 전에 한 번, 보내기 전에 한 번, 모든 값을 허용된 값 목록과 대조해요. 맞지 않는 값은 <invalid>로 바뀌거나 빠지고, 절대 그대로 보내지 않아요.

보고서에 대해

• schema: 보고서 형식(aipager-report/1).
• trigger: manual(내가 직접 열었음) 또는 auto(자동 제안).
• day: 날짜, UTC(정확한 시각은 없어요).
• note: 메모를 추가했을 때만: 미리 보기에 나온 그대로의 내 글(최대 500자, 보이지 않는 문자 없음).

aipager와 컴퓨터

• aipager: 버전, 설치 방식(pipx, uv, brew, pip, editable, nix, snap, docker, system, foreign, unknown), 출처(패키지 저장소, 로컬 폴더, git 사본), aipager update가 업그레이드할 수 있는지.
• python: Python 버전, 그리고 CPython인지 PyPy인지.
• os: 시스템(linux, darwin, windows, freebsd), 프로세서 종류, 정해진 목록에서 고른 Linux 배포판과 그 버전 번호, 커널의 major.minor 버전, 컨테이너 종류(있다면: docker, lxc, wsl, podman), aipager가 systemd나 launchd 서비스로 설정되어 있는지.
• deps: aipager가 쓰는 라이브러리의 버전(python-telegram-bot, httpx, aiohttp, PyYAML, rich, questionary, dtach-bin).
• claude_code: Claude Code 버전, 찾은 Claude Code 설치 수, 로그인 방식(env, file, keychain, 또는 알 수 없는 이유). 로그인 정보 자체는 절대 들어가지 않아요.

내 설정, 개수로만

• config: 모드(personal, team, scope), 설정된 개인 채팅과 그룹의 수, 사용자 정의 역할의 수(이름은 없어요), 켜져 있는 기능(Mini App과 그 터널 종류, 음성 메시지, 변경 사항 미리 보기, 풍부한 요약).
• runtime: aipager가 얼마나 오래 실행됐는지를 구간으로(<10m, 10m-1h, 1-24h, 1-7d, >7d), 실행 중인 세션과 작업 중인 세션의 수, 지난 7일 동안 aipager가 예기치 않게 멈춘 횟수와 마지막이 어떻게 끝났는지(clean, crash, reboot).
• doctor: 정해진 상태 검사 목록의 결과(ok, warn, fail), 검사를 다시 실행하지 않고 얻을 수 있을 때(봇과 터미널의 보고서에서는 비어 있어요).
• flood: 모든 채팅을 합친 Telegram 속도 제한 상태. 지난 7일 동안의 차단 횟수, 지금 보내기가 멈춘 채팅이나 최소 모드인 채팅이나 느려진 채팅이 있는지, 가장 바쁜 채팅이 시간당 한도를 얼마나 썼는지를 구간으로. 채팅 ID는 없어요.

무엇이 잘못됐는지

• counters_24h: 정해진 목록의 일마다 지난 24시간 동안 몇 번 일어났는지(예: 작업 카드 감시 재시작, 특정 종류의 Telegram 오류, hook의 메모리 한도 도달, 네트워크나 디스크 오류). 횟수만 있어요.
• log_digest_24h: 지난 24시간 동안 경고나 오류 로그를 가장 많이 쓴 aipager 코드 안의 위치 15곳, 위치(aipager/state.py:1234), 수준, 횟수. 로그 글은 절대 없어요.
• errors: aipager가 기록한 오류 최대 10개, 각각:
  • fingerprint: 그 버그의 ap1- 이름(오류 유형과 aipager 코드 안의 위치 최대 8곳의 이름을 해시한 것이고, 글이나 데이터는 절대 해시하지 않아요).
  • 어디서 일어났는지(aipager, hook, 상태 줄, 명령, Mini App), 어떻게 잡혔는지, 버그인지 아니면 그저 드문 상황인지(tier).
  • aipager가 로그에 쓴 오류라면 logger 이름(aipager 모듈, asyncio, 또는 telegram.ext의 일부).
  • 예외의 유형 이름(예: builtins.KeyError, 또는 정해진 패키지 목록 밖의 예외는 <other>), 원인 유형 최대 3개, ENOSPC 같은 오류 번호 이름.
  • hook 오류라면 hook 이벤트와 도구(기본 도구는 이름으로, 모든 MCP 도구는 mcp로).
  • 몇 번, 어느 날들, 어느 aipager 버전에서 일어났는지.
  • 거쳐 간 aipager 자체 코드 안의 위치 최대 12곳(파일, 줄, 함수 이름)과, 거쳐 간 정해진 목록의 외부 패키지 이름 최대 8개.

절대 들어가지 않는 것: 내 채팅, 메시지, Claude의 답변, 세션 이름, 폴더나 파일 경로, token이나 키, 채팅이나 사용자 ID, 사용자 이름, 컴퓨터 이름, 어떤 오류 메시지의 글, 로그 줄. 위의 필드에는 이런 것들이 들어갈 자리가 없고, 보고서는 보여 주기 전과 보내기 전에 이 목록과 대조돼요.

보고서가 가는 곳#

보고서는 내 이름 없이 Sentry에 있는 aipager 개발자의 비공개 오류 수신함으로 가요. 계정도 없고 설치 ID도 없어요. 다른 웹 요청과 마찬가지로 내 컴퓨터의 인터넷 주소에서 오고, GitHub와 Sentry는 그 주소를 볼 수 있어요. 수신함은 그 주소를 저장하지 않도록 설정되어 있어요(Sentry의 “Prevent Storing of IP Addresses” 옵션). aipager는 HTTPS 요청 하나로 보고서를 직접 보내요(훨씬 더 많은 것을 모으는 Sentry 자체 라이브러리는 쓰지 않아요). 내가 본 보고서는 report.json 첨부 파일로 가고, 분류용 짧은 요약이 함께 가요(버전, 설치 방식과 개발용 설치인지, 시스템, Python과 Claude Code 버전, trigger, 그리고 첫 오류의 지문, 유형, 코드 위치). 요청에는 aipager/<version>만 적혀 있어요.

보낸 뒤에는 카드(또는 터미널)에 참조 번호가 나와요. 첫 오류의 ap1- 지문이거나, 오류가 없는 보고서라면 32자 이벤트 ID예요. GitHub에 이슈도 연다면 개발자가 내 보고서를 찾을 수 있게 참조 번호를 함께 적어 주세요. 로그나 aipager doctor 출력은 이슈에 붙여 넣지 마세요. 거기에는 내 채팅 ID, 홈 폴더 경로, 메시지 앞부분이 들어 있어요.

보내기 직전에 aipager는 어디로 보낼지 알려고 GitHub의 aipager 저장소에서 report-endpoint.json을 읽어요(실행 중인 aipager는 쓸 수 있는 사본을 하루 동안 보관해요. 읽기에 실패하면 다음 보내기 때 다시 시도하고, aipager report는 매번 다시 읽어요). 덕분에 개발자는 새 버전을 내지 않고도 Sentry 키를 바꾸거나, 모두에게 신고를 끄거나, 어떤 버전 번호보다 낮은 버전이 보내지 못하게 할 수 있어요(자기 버전을 알 수 없는 빌드는 그보다 낮다고 봐요). GitHub에 연결할 수 없거나 파일이 aipager가 이해하는 형식이 아니면, aipager는 이 버전에 들어 있는 키를 써요. 읽을 수 있고 꺼져 있다고 적힌 파일은 항상 따라요.

한도#

• 한 컴퓨터에서 하루(UTC)에 최대 5번까지 보내기를 시도할 수 있고, 수동과 자동을 합쳐서 세며 실패한 시도도 세어요. 그다음 시도에는 한 컴퓨터에서 하루에 보고서를 5개까지만 보낼 수 있어요. 내일 다시 시도해 주세요.가 나와요.
• 백그라운드에서 다시 시도하지 않아요. 보내기에 실패하면 카드에 지금은 보낼 수 없어요. 잃어버린 건 없으니 나중에 다시 시도해 주세요.가 나오고 보내기 버튼은 남아 있어요.

aipager가 보고서를 제안하는 때#

aipager는 자기 버그를 알아채고, 가끔 내 개인 채팅에서 그에 대한 보고서를 보내자고 제안해요. aipager에서 내부 오류가 N번 생겼어요 (작업 카드의 TypeError). 보고서가 있으면 문제를 더 빨리 고칠 수 있어요. ...와 함께 보고서 미리 보기, 나중에, 다시 묻지 않기가 있어요. “보고서 미리 보기”는 그 오류들만 담긴 미리 보기 카드를 열어요. 거기서 “보내기”를 누를 때까지 아무것도 보내지 않아요.

제안은 다음이 모두 맞을 때만 나와요:

• aipager의 진짜 버그예요. aipager 자체 코드의 오류가 10분 이상 간격을 두고 두 번 이상 일어났거나, 서비스로 실행 중인 aipager가 비정상 종료하면 바로 세어요(포그라운드에서 실행한 aipager start가 죽은 경우, 예를 들어 터미널을 닫아서라면 횟수만 세어요). hook, 상태 줄 프로그램, 명령이 aipager에 알린 오류(hook의 메모리 부족 포함)는 하루 이상에 걸쳐 일어나야 해서, 그런 오류 한 번으로는 절대 제안하지 않아요. 그런 오류는 알림의 “이 문제 신고” 버튼이 맡아요. aipager의 잘못이 아닌 일(Telegram 제한, 네트워크, 디스크 가득 참)은 절대 제안하지 않아요. 내가 직접 보내는 보고서를 위해 횟수만 세어요.
• 3일에 최대 한 번이고, 그사이 기다리는 것은 모두 이 한 번의 제안에 합쳐요.
• aipager가 이 컴퓨터에서 처음 시작한 뒤 48시간 안에는 제안하지 않고(업데이트로 이 시간이 다시 시작되지 않아요), aipager가 재시작한 뒤 첫 한 시간 동안도 제안하지 않아요.
• 2분 동안 아무것도 실행 중이거나 보낼 차례를 기다리지 않고, 지난 30분 안에 봇과의 개인 채팅을 쓴 적이 있을 때만이에요. 그룹에서는 절대 하지 않고, Telegram이 그 채팅을 제한하는 중에도 하지 않아요.
• 버그마다 aipager 버전 하나에서 한 번만 제안해요. 어떻게 답하든 그 버전에서는 다시 제안하지 않아요. 업데이트한 뒤에 다시 일어나야만 돌아올 수 있어요.
• 나중에와 다시 묻지 않기는 둘 다 “아니요”로 세고, 하루 동안 답하지 않은 제안도 그래요. 보고서 미리 보기는 그 횟수를 0으로 되돌려요. 나중에 취소하더라도요. “아니요”가 연달아 두 번이면 자동 제안이 꺼져요. 두 번째가 누름이었다면 한 줄로 알려 주고, 어느 경우든 /settings에서 볼 수 있어요.
• 개발용 설치(로컬 폴더, git 사본에서 설치했거나 editable 모드로 설치한 aipager)에는 절대 제안하지 않아요.

자동 제안을 끄려면 내 개인 채팅에서 /settings를 쓰세요: 문제 신고: 끄기. “아니요” 두 번으로 꺼졌다면 같은 페이지에 제안 다시 켜기가 있어요. 있지만 읽을 수 없는 reports.json도 자동 제안을 꺼요(aipager가 이전 답을 더 이상 알 수 없으니까요). 제안 다시 켜기는 이 상태도 지워요. 물어볼 채팅이 없는 컴퓨터라면 aipager 환경에 AIPAGER_REPORT_PROMPTS=0을 설정하세요. 이 설정과 상관없이 “문제 신고”와 aipager report는 항상 쓸 수 있어요.

내 컴퓨터에 남는 것#

• ~/.local/state/aipager/reports.json: aipager가 기록한 오류(위와 같은 형태: 유형 이름, 버전, 코드 위치, 최대 50개), 8일 동안의 시간별 횟수, 2일 동안의 로그 요약, 최근 몇 번의 멈춤이 어떻게 끝났는지, 제안 상태(마지막 제안 시각, 연속 “아니요” 횟수, 어느 버그를 어느 버전에서 제안했는지). 나만 읽을 수 있어요.
• ~/.local/state/aipager/report-sends.json: 오늘 보냈거나 보내려고 시도한 보고서 수.
• ~/.local/share/aipager/install.json: aipager가 이 컴퓨터에서 처음 시작한 때(위의 48시간에 쓰여요).
• ~/.local/share/aipager/running.json: aipager가 실행되는 동안 쓰여요(프로세스 번호, 시작 시각, 서비스로 실행 중인지, 이번 부팅의 ID). 비정상 종료와 정상 종료를 구별하는 데 써요.

어느 것에도 채팅, 메시지, 이름, 경로, token은 없어요. aipager uninstall은 이 파일들을 aipager의 다른 데이터와 함께 남겨 두어서 다시 설치하면 이어서 쓸 수 있어요. 무엇을 남겼는지 보여 주고, 지우는 명령을 출력해요(aipager uninstall 참고). 이것들만 지우려면 이 네 파일을 지우세요. ~/.local/state/aipager 폴더를 통째로 지우면 앞의 두 개가 지워지지만(언어 상태 languages.json도 함께), install.json과 running.json은 이름으로 지워야 해요(~/.local/share/aipager는 지우지 마세요. aipager의 세션 폴더도 거기 있어요).

함께 보기#

• 문제 해결: 흔한 문제와 해결 방법.
• 보안 모델: aipager가 무엇을 건드리고, 무엇이 네트워크로 나가는지.
• 봇 명령: /help, /settings, 명령줄.