선배교사 김선생
교사를 위한 AI 업무 파트너. 가정통신문·기안·품의 초안, 수업 자료, 생활기록부 문구, 업무 상담을
교직 8~10년 차 선배 교사의 감각으로 도와주는 웹앱입니다.
특징
- 메신저형 대화 화면 — 아이메시지·인스타 DM 감각의 말풍선, 타이핑 인디케이터, 날짜 구분선, 시간 표시
- 표정이 바뀌는 프로필 사진 — 김선생이 답변마다 감정을 표기하면 프로필 얼굴이 5종(차분/자신감/고민/걱정/활짝) 중 하나로 바뀝니다. 헤더 아바타와 각 답변 옆 아바타가 함께 반응합니다.
- 모드 선택 없음 — 상담인지 공문인지 수업 자료인지 김선생이 대화를 읽고 스스로 판단합니다. 사용자는 그냥 말만 걸면 됩니다.
- 구글 로그인 + 기기 간 동기화 (선택) — 로그인하면 대화·업무·설정이 계정에 따라옵니다. API 키와 MCP 토큰은 동기화하지 않고 각 브라우저에만 남습니다. 환경변수가 없으면 로그인 기능 자체가 표시되지 않고 지금처럼 로컬로만 동작합니다.
- 친밀도 3단계 — 정중한 멘토 / 담백한 직속 선배 / 든든한 찐친 선배. 이름을 넣으면 호칭이 바뀝니다. 말투만 달라지고 문서 완성도는 동일합니다.
- AI 사업자 4곳 지원 — Claude · ChatGPT · Gemini · Grok. 교사가 가진 키를 골라 씁니다.
- 인터랙티브 결과물 — 문서는 복사·인쇄 가능한 카드로, 준비 일정은 D-day 체크리스트 위젯으로 나옵니다.
- 업무 체크리스트 — 대화에서 나온 준비 일정을 사이드바에 담아 D-day로 관리하고,
.ics로 내보내 구글·아웃룩 캘린더에 넣습니다.
- 즐겨찾는 양식 퀵버튼 — 가정통신문, 품의, 기안, 생기부, 지도안 등 12종 프리셋
- 생활기록부 기재요령 반영 — 명사형 종결, 기재 금지 항목 회피, 글자수 표기
- 사용자 API 키 방식 — 키는 브라우저 localStorage에만 저장되며 서버에 기록되지 않습니다.
API 라우트는 요청 헤더로 받은 키를 그대로 각 사업자에게 전달하고, 서로 다른 SSE 형식을 하나로 정규화하는 프록시 역할만 합니다.
- 대화·업무 기록 로컬 저장 — 서버 DB가 없습니다.
- 파일 첨부 — 엑셀·CSV·PDF·이미지·한글 파일을 붙이면 김선생이 실제 값을 열어보고 답합니다. (Claude 전용, 파일당 4MB)
- 파일 만들기 — 명렬표·집계표·안내문·차트를 실제 .xlsx / .docx / .png 파일로 만들어 줍니다. 대화 안에서 바로 내려받거나 연결한 폴더에 저장합니다. (Claude 전용)
- 웹 페이지 읽기 — 교육청 공지 링크를 주면 직접 열어 읽고 요약합니다. 웹 검색은 요금이 따로 붙어 넣지 않았습니다. (Claude 전용)
- 내 PC 폴더 연결 — 업무 폴더를 연결하면 파일을 골라 바로 첨부하고, 만들어진 파일을 그 폴더에 저장합니다. 크롬·엣지 데스크톱 전용이며, 서버는 폴더 안을 볼 수 없습니다.
- 외부 도구(MCP) 연결 — 구글 캘린더·드라이브 등 원격 MCP 서버를 여러 개 등록하고 켜고 끕니다. (Claude 전용, 토큰은 직접 발급)
- 스트리밍 응답, 마크다운·표 렌더링, 복사 / txt / 인쇄, 다크 모드, 모바일 대응
개인정보
이 앱은 서버에 어떤 데이터도 저장하지 않습니다(로그인 시 동기화 데이터 제외). 다만 입력한 내용과
첨부한 파일은 사용자의 키로 AI 사업자에게 전송되므로, 학생·학부모의 실명이나 연락처 등 개인정보는
입력하지 않도록 안내하고 있습니다. 첨부 파일은 Anthropic Files API에 올라가고 이 앱의 서버에는
사본이 남지 않습니다.
도구 버전에 대한 메모
web_fetch와 code_execution은 세대를 맞춰야 합니다. 2026년판 web_fetch를 쓰려면
code_execution도 2026년판이어야 합니다. 지금은 검증된 2025년 조합(web_fetch_20250910 +
code_execution_20250825)을 함께 쓰고 있습니다. 이 도구들과 Files API는 정식 기능이라
anthropic-beta 헤더가 필요 없습니다. 없어진 베타 이름을 보내면 400이 납니다.
헤더가 남아 있는 곳은 MCP 커넥터(mcp-client-2025-11-20) 하나뿐입니다.
기술 스택
Next.js 16 (App Router) · React 19 · TypeScript · Tailwind CSS v4
개발
npm install
npm run dev
http://localhost:3000 접속 후 설정에서 Anthropic API 키를 입력하면 바로 사용할 수 있습니다.
서버 환경변수는 필요하지 않습니다.
환경변수 (전부 선택 사항)
없으면 로그인·동기화 기능이 숨겨지고 나머지는 그대로 동작합니다.
| 변수 | 용도 |
|---|
AUTH_SECRET | 세션 쿠키 서명용 임의 문자열 (32자 이상) |
AUTH_GOOGLE_ID / AUTH_GOOGLE_SECRET | Google OAuth 클라이언트 |
UPSTASH_REDIS_REST_URL / UPSTASH_REDIS_REST_TOKEN | 계정별 동기화 저장소. Vercel의 Upstash 연동을 쓰면 KV_REST_API_URL / KV_REST_API_TOKEN 이름으로 들어오는데, 둘 다 인식합니다 |
구글 OAuth 리디렉션 URI: https://<도메인>/api/auth/callback/google
배포
Vercel에 그대로 배포됩니다. 환경변수 설정 없이 동작합니다.
npx vercel --prod
구조
src/
app/
page.tsx 메인 화면 (대화·업무·첨부·폴더 상태 관리)
api/chat/route.ts 4개 사업자 스트리밍 프록시 + SSE 정규화 + 도구 이벤트 + pause_turn 이어받기
api/files/ 첨부 업로드 중계 · 생성 파일 내려받기 프록시
components/
ChatHeader 프로필 사진·상태·일정·설정
Avatar 표정 5종 크로스페이드
Sidebar 업무 체크리스트 · 즐겨찾는 양식 · 대화 목록
MessageBubble 마크다운 + 특수 블록 분기
DocCard 복사·txt·인쇄 가능한 문서 카드
TaskWidget D-day 체크리스트 위젯
FolderBar 내 PC 폴더 연결 상태
FolderPicker 연결된 폴더에서 파일 고르기
Composer, Welcome, SettingsModal
lib/
agent.ts 김선생 페르소나 + 모드별 프롬프트 ← 문구 수정은 주로 여기
providers.ts 사업자별 엔드포인트·모델·델타 추출 ← 모델 추가는 여기
blocks.ts kt-doc / kt-tasks 블록 파싱
mood.ts 표정 5종 정의 · 감정 태그 파싱 · 휴리스틱 폴백
forms.ts 즐겨찾는 양식 프리셋
ics.ts 캘린더(.ics) 생성
stream.ts 정규화된 SSE 파싱
tools.ts Claude 서버 도구 정의 · MCP 서버 조립 ← 도구 추가는 여기
files.ts 첨부 업로드 · 결과 파일 내려받기
folder.ts File System Access API (폴더 연결·저장)
session.ts 구글 OAuth · 서명 세션 쿠키 (의존성 없음)
account.ts 세션 조회 · 동기화 병합 로직
kv.ts Upstash Redis REST
storage.ts localStorage 저장/불러오기
표정 시스템
김선생은 모든 답변을 [감정:calm] 같은 한 줄로 시작합니다. 이 줄은 화면에 보이지 않고 프로필 사진을 바꾸는 데만 쓰입니다.
값은 calm / confident / thinking / concerned / cheerful 다섯 개이며, 모델이 태그를 빠뜨리면 guessMood()가 본문을 보고 추정합니다.
얼굴 이미지는 public/avatars/*.webp에 있습니다.
특수 블록 규약
김선생은 결과물을 두 종류의 코드펜스로 감싸 출력하고, 앱이 이를 위젯으로 바꿉니다.
```kt-doc
제목: 문서 제목
---
본문
```
```kt-tasks
업무: 가을 현장체험학습
기준일: 2026-10-15
D-30 | 학교운영위원회 심의 자료 제출
2026-10-01 | 전세버스 계약 확인
```
