Skip to content

README.ko.md

Latest commit

 

History

History
368 lines (274 loc) · 13.4 KB

README.ko.md

File metadata and controls

368 lines (274 loc) · 13.4 KB

opensession

English CI crates.io License: MIT

OpenSession은 AI 세션 로그를 로컬 우선(local-first)으로 기록/등록/공유/검토하는 워크플로입니다.

웹: opensession.io
문서: opensession.io/docs
한국어 제품 문서: docs.ko.md

문서 맵

DX 리셋 v1

CLI/Web/API 계약은 3가지 동작으로 정리되었습니다.

  • register: canonical HAIL JSONL을 로컬 저장소에 등록 (네트워크 부작용 없음)
  • share: Source URI를 공유 가능한 출력으로 변환
  • handoff: 불변(immutable) 아티팩트를 생성하고 alias를 관리

레거시 표면은 제거되었습니다.

  • opensession publish ... 제거
  • opensession session handoff ... 제거
  • 레거시 단축 라우트(/git, /gh/*, /resolve/*)는 더 이상 제공되지 않으며 의도적으로 404를 반환
  • /api/ingest/preview 제거 (/api/parse/preview 사용)

URI 모델

  • os://src/local/<sha256>
  • os://src/gh/<owner>/<repo>/ref/<ref_enc>/path/<path...>
  • os://src/gl/<project_b64>/ref/<ref_enc>/path/<path...>
  • os://src/git/<remote_b64>/ref/<ref_enc>/path/<path...>
  • os://artifact/<sha256>

인코딩 규칙:

  • ref_enc: RFC3986 percent-encoding
  • project_b64, remote_b64: base64url(no padding)

설치

cargo install opensession

사용자 표면은 opensession CLI입니다. 자동 세션 수집(auto-capture)을 쓰려면 daemon 프로세스가 추가로 실행 중이어야 합니다.

CLI 로컬 전용 경로(backup/summary/handoff):

opensession doctor
opensession doctor --fix --profile local

데스크톱 앱 경로(app + CLI + app-first 기본값):

opensession doctor --fix --profile app --open-target app

개발 툴체인 (레포 작업 필수)

로컬 환경 편차를 줄이기 위해 레포 훅/검증은 mise 관리 툴체인을 필수로 사용합니다.

mise install
mise exec -- node --version
mise exec -- cargo --version

로컬 게이트(./.githooks/pre-commit, ./.githooks/pre-push)는 mise exec 경로로 실행됩니다.

Install-and-Forget 설정

# 1) CLI 설치
cargo install opensession

# 2) 로컬 설정 진단 (flutter doctor 스타일)
opensession doctor

# 3) 권장 설치값 적용 (변경 전 동의 프롬프트)
opensession doctor --fix --profile local

# 선택: fanout 모드를 명시적으로 지정
opensession doctor --fix --profile local --fanout-mode hidden_ref

# 선택: view/review 오프너를 명시적으로 지정
opensession doctor --fix --profile app --open-target app

# 자동화/비대화형(non-TTY)
opensession doctor --fix --yes --profile local --fanout-mode hidden_ref --open-target web

doctor는 내부적으로 기존 setup 파이프라인을 재사용합니다. doctor --fix는 적용 전 setup 계획을 출력하고 동의를 받은 뒤 훅/shim/fanout 변경을 수행합니다. 첫 interactive 적용 시 fanout 저장 모드(hidden_ref 또는 git_notes)를 선택하며, 선택값은 로컬 git 설정(.git/config)의 opensession.fanout-mode에 저장됩니다. 같은 설정 흐름에서 opensession view/review 오프너(app 또는 web)도 선택하며 opensession.open-target으로 저장됩니다. 비대화형 환경에서는 --fix에 --yes가 필요하고, 저장된 fanout 모드가 없으면 --fanout-mode를 명시해야 합니다. --open-target은 선택사항이며 기본값이 profile을 따릅니다(local -> web, app -> app).

자동 수집을 위한 daemon 실행:

# opensession-daemon 바이너리가 있는 경우
opensession-daemon run

# 소스 체크아웃에서 실행하는 경우
cargo run -p opensession-daemon -- run

daemon이 없으면 parse/register/share는 수동으로 사용할 수 있지만 백그라운드 자동 수집은 동작하지 않습니다.

데스크톱 프리뷰 (Tauri)

기존 Svelte UI를 재사용하는 데스크톱 프리뷰 셸은 desktop/에 있습니다.

cd desktop
npm install
npm run dev

위 명령은 로컬 데스크톱 런타임으로 Tauri 데스크톱 창을 실행합니다. opensession-server는 필요하지 않습니다.

데스크톱 릴리즈는 GitHub Actions Release 워크플로에서 수동 실행하며, 이제 crates 릴리즈와 macOS 데스크톱 아티팩트 업로드를 같은 버전 태그로 처리합니다. 릴리즈 정책은 macOS universal(x86_64 + arm64) 단일이며, CI/Release에서 lipo 검증을 수행합니다.

데스크톱 런타임 Summary 설정(v3)

데스크톱 로컬 런타임은 typed runtime 설정 구조를 사용합니다.

  • summary.provider.id|endpoint|model
  • summary.prompt.template
  • summary.response.style|shape
  • summary.storage.trigger|backend
  • summary.source_mode
  • vector_search.enabled|provider|model|endpoint|granularity|chunk_size_lines|chunk_overlap_lines|top_k_chunks|top_k_sessions

데스크톱 정책:

  • runtime capabilities에서 auth_enabled=false이면 account/auth UI를 숨깁니다.
  • 데스크톱 로컬 런타임의 source mode는 session_only로 잠금됩니다.
  • session_or_git_changes는 CI/CLI 같은 비-desktop 경로에서만 유지됩니다.
  • 기본 저장 backend는 hidden_ref(Git-native summary 원장)입니다.
  • hidden_ref를 쓰더라도 빠른 필터/검색을 위해 목록 메타데이터와 벡터 인덱스 메타데이터는 로컬 SQLite(local.db)에 계속 인덱싱됩니다.
  • settings의 response preview는 결정론적 로컬 샘플 렌더링이며 LLM/네트워크 호출을 하지 않습니다.

데스크톱 검색 옵션:

  • 키워드 검색: 일반 검색어
  • 시맨틱 벡터 검색은 세션 단일 문자열이 아니라 이벤트/라인 청크 인덱싱으로 동작합니다.
  • 벡터 검색은 기본 비활성화이며 Settings에서 임베딩 모델 설치를 명시적으로 완료해야 활성화할 수 있습니다.
  • 기본 임베딩 모델은 로컬 Ollama의 bge-m3 (http://127.0.0.1:11434)입니다.
  • Settings에서 모델 설치/인덱싱 상태(NotInstalled/Installing/Ready/Failed, Idle/Running/Complete/Failed)와 Rebuild index를 제공합니다.

데스크톱 빌드 안정성 정책:

  • CI에서 Linux 데스크톱 번들 빌드 검증(desktop-bundle-verify)을 필수로 수행합니다.
  • macOS 번들 빌드는 universal-apple-darwin으로 강제되고 아키텍처 검증을 통과해야 합니다.
  • 정기/수동 Desktop Dry Run 워크플로가 no-sign 번들 빌드를 점검하고 진단 아티팩트를 업로드합니다.

빠른 시작

# 첫 사용자용 명령 흐름 출력
opensession docs quickstart

# agent-native 로그 -> canonical HAIL JSONL
opensession parse --profile codex ./raw-session.jsonl > ./session.hail.jsonl

# 로컬 object store 등록
opensession register ./session.hail.jsonl
# -> os://src/local/<sha256>

# 원본 바이트 확인
opensession cat os://src/local/<sha256>

# 요약 메타데이터 확인
opensession inspect os://src/local/<sha256>

공유(share)

# 원클릭 git 공유 (첫 push만 한 번 확인, 이후 quick 모드에서 자동 push)
opensession share os://src/local/<sha256> --quick

# 선택적 네트워크 변경
opensession share os://src/local/<sha256> --git --remote origin --push

# OpenSession pre-push 훅 설치/업데이트
opensession doctor
opensession doctor --fix --profile local
# 선택: fanout 실패 시 push 자체를 실패시키고 싶다면
OPENSESSION_STRICT=1 git push

# remote-resolvable URI -> 웹 URL
opensession config init --base-url https://opensession.io
opensession share os://src/git/<remote_b64>/ref/<ref_enc>/path/<path...> --web

share --web는 .opensession/config.toml이 반드시 필요합니다. Git-native write는 이제 hidden ledger ref(refs/opensession/branches/<branch_b64url>)를 사용하며, 새 write에 레거시 고정 ref는 쓰지 않습니다. opensession doctor --fix는 훅 안정성을 위해 ~/.local/share/opensession/bin/opensession shim도 설치합니다.

Cleanup 자동화

GitHub/GitLab/Generic 원격에서 hidden ref와 artifact 정리를 자동화할 수 있습니다.

# cleanup 설정 + 템플릿 초기화
opensession cleanup init --provider auto

# 비대화형 설정
opensession cleanup init --provider auto --yes

# cleanup 상태 + janitor 미리보기
opensession cleanup status

# 기본은 dry-run
opensession cleanup run

# 실제 삭제 적용
opensession cleanup run --apply

기본값:

  • hidden ref TTL: 30일
  • artifact branch TTL: 30일
  • GitHub/GitLab 설정 시 PR/MR 갱신마다 session artifact branch를 갱신하고 리뷰 코멘트를 남기는 session-review 자동화 템플릿도 함께 생성됩니다.
  • 기본값은 ephemeral PR/MR artifact branch이며 리뷰가 닫히면 삭제됩니다. --session-archive-branch <branch>를 설정하면 pr/sessions 같은 전용 archive branch에 immutable snapshot을 계속 보관합니다.
  • session-review 코멘트에는 Reviewer Quick Digest 블록이 포함되며, 모바일 친화적인 Q&A 줄글 요약, 수정 파일, 추가/수정 테스트가 함께 표시됩니다.

민감한 저장소는 즉시 정리 모드를 권장합니다.

opensession cleanup init --provider auto --hidden-ttl-days 0 --artifact-ttl-days 0 --yes

# 전용 브랜치에 리뷰 스냅샷 영구 보관
opensession cleanup init --provider auto --session-archive-branch pr/sessions --yes

handoff

# 불변 artifact 생성
opensession handoff build --from os://src/local/<sha256> --pin latest
# -> os://artifact/<sha256>

# 출력 표현 선택
opensession handoff artifacts get os://artifact/<sha256> --format canonical --encode jsonl

# 해시/내용 검증
opensession handoff artifacts verify os://artifact/<sha256>

# alias 관리
opensession handoff artifacts pin latest os://artifact/<sha256>
opensession handoff artifacts unpin latest

# 삭제 정책: unpinned만 삭제 가능
opensession handoff artifacts rm os://artifact/<sha256>

Canonical 웹 라우트

  • /src/gh/<owner>/<repo>/ref/<ref_enc>/path/<path...>
  • /src/gl/<project_b64>/ref/<ref_enc>/path/<path...>
  • /src/git/<remote_b64>/ref/<ref_enc>/path/<path...>

API 표면(v1)

  • GET /api/health
  • GET /api/capabilities
  • POST /api/parse/preview
  • GET /api/sessions
  • GET /api/sessions/{id}
  • GET /api/sessions/{id}/raw
  • DELETE /api/admin/sessions/{id} (X-OpenSession-Admin-Key 필요)

실패 복구 가이드

자주 발생하는 실패 시그니처와 즉시 복구 명령:

  1. local URI로 share --web 실행:
opensession share os://src/local/<sha256> --git --remote origin
opensession share os://src/git/<remote_b64>/ref/<ref_enc>/path/<path...> --web
  1. share --git에서 remote 누락:
opensession share os://src/local/<sha256> --quick
  1. git 저장소 밖에서 share --git 실행:
cd <your-repo>
opensession share os://src/local/<sha256> --quick
  1. .opensession/config.toml 없이 share --web 실행:
opensession config init --base-url https://opensession.io
opensession config show
  1. 비정규 입력으로 register 실행:
opensession parse --profile codex ./raw-session.jsonl --out ./session.hail.jsonl
opensession register ./session.hail.jsonl
  1. parser/input 불일치로 parse 실패:
opensession parse --help
opensession parse --profile codex ./raw-session.jsonl --preview
  1. view 타겟 해석 실패:
opensession view os://src/... --no-open
opensession view ./session.hail.jsonl --no-open
opensession view HEAD
  1. cleanup 설정 전에 cleanup run 실행:
opensession cleanup init --provider auto
opensession cleanup run

처음 사용자 5분 복귀 경로:

opensession doctor
opensession doctor --fix --profile local
opensession parse --profile codex ./raw-session.jsonl --out ./session.hail.jsonl
opensession register ./session.hail.jsonl
opensession share os://src/local/<sha256> --quick

로컬 개발 검증

# 필수 훅 게이트
./.githooks/pre-commit
./.githooks/pre-push

PR CI는 의도적으로 가볍게 유지합니다. .github/workflows/ci.yml에는 빠른 기본 게이트만 남기고, 무거운 GitHub-hosted E2E/desktop 검증은 .github/workflows/ci-deep.yml로 분리해 로컬에서 먼저 검증하는 흐름을 기준으로 둡니다.

# 웹 런타임 검증 (wrangler + opensession-server 기동 이후)
cd web
OPENSESSION_E2E_WORKER_BASE_URL=http://127.0.0.1:8788 \
OPENSESSION_E2E_SERVER_BASE_URL=http://127.0.0.1:3000 \
OPENSESSION_E2E_ALLOW_REMOTE=0 \
CI=1 \
npm run test:e2e:live -- --reporter=list

훅/CI 동등 검증 절차(API E2E, Desktop E2E, artifact 정책 포함): docs/development-validation-flow.md