#!/bin/sh
# Claude Code Skill 설치 스크립트
# 생성: 2026-08-13 · Skill 1개 · 파일 1개
#
#   ./install-skills.sh            ~/.claude/skills/ 에 설치 (모든 프로젝트에서 사용)
#   ./install-skills.sh ./myrepo   ./myrepo/.claude/skills/ 에 설치 (그 저장소 전용)
set -e

DEST="${1:+$1/.claude/skills}"
DEST="${DEST:-$HOME/.claude/skills}"
mkdir -p "$DEST"
echo "설치 위치: $DEST"


mkdir -p "$DEST/author-disambiguate"
cat > "$DEST/author-disambiguate/SKILL.md" <<'SKILL_PAYLOAD_EOF'
---
name: author-disambiguate
description: 서지 데이터에서 같은 사람의 여러 표기를 하나로 묶고 동명이인은 나눈다. 한글 로마자 음절 이표기(SEONG≡SUNG), 이니셜 축약(DONG W ≡ DONG WAN), 구두점 정규화(J-H/J.H./JH), 과분할과 과병합의 맞교환. TRIGGER - "저자 동일인", "동명이인", "저자명 통일", "author disambiguation", "같은 사람이 여러 명으로 세어짐", 저자 단위로 집계해야 하는데 표기가 흩어져 있을 때.
---

# 저자 동일인 판정

## 왜 어려운가

한 사람이 논문마다 다르게 적힌다. `Kim, Jae Heon` · `Kim JH` · `Kim J-H` · `Kim J.H.` — 그리고 진짜 다른 사람도 `Kim JH` 다. **너무 좁게 묶으면 한 사람이 여러 명이 되고, 너무 넓게 묶으면 여러 명이 한 사람이 된다.** 둘 다 저자 단위 집계를 망친다.

정본 코드에 두 방향의 실패가 모두 실측으로 적혀 있다.

| 방식 | 결과 |
|---|---|
| 구두점 정규화 없이 문자열 그대로 키 | **같은 사람이 332개 그룹으로 쪼개짐**(과분할) |
| 성 + 이니셜로만 묶기 | **`KIM JH` 하나에 71명이 뭉침**(과병합) |

## 정본 코드

```
~/Documents/혜연/BTC_KOL_PoC/analyze_kol.py
  same_name()        음절 동치 판정
  author_key()       저자 식별 키 생성
  build_alias_map()  표기 묶음 만들기 (234줄)
```

`--selfcheck` 로 로직 자체를 검증한다.

## 기본 전략 — 풀네임 키 + 구두점 정규화

```
fullname (기본)
    성 + 이름 전체.  'Kim, Jae Heon' → 'KIM JAE HEON'
    구두점만 정규화: 'J-H' 'J.H.' 'JH' 'J H' → 모두 'J H'
```

이 정규화 하나가 332개 과분할을 없앤다. **서로 다른 사람이 섞이지 않는 게 우선**이고, 이니셜 표기 레코드와 풀네임 레코드가 갈리는 과분할은 다음 단계(alias map)에서 잡는다.

### 이니셜인지 이름인지는 소문자 유무로 판정한다

```python
# 소문자 유무로 판정해야 한다 — 대문자로 바꾼 뒤 보면 'Shin'도 이니셜로 오인된다.
if fore and " " not in fore and len(fore) <= 4 and not re.search(r"[a-z]", raw):
    fore = " ".join(fore)
```

`Shin` 은 네 글자 이름이고 `SHIN` 으로 바꾸면 이니셜 4개처럼 보인다. **정규화 전 원문의 대소문자를 봐야 구분된다.** 대문자 변환을 먼저 하면 이 정보가 사라진다.

## 표기 동치 — 두 규칙

`same_name()` 이 성을 뺀 이름 토큰들을 비교한다.

```
① 음절 수가 같고 각 음절이 동치      'SEONG KOO' ≡ 'SUNG KOO'
② 마지막 음절이 한 글자인 축약 표기   'DONG W'    ≡ 'DONG WAN'
```

①은 **한글 로마자 표기 흔들림**이다. 성구 → Seong Koo / Sung Koo / Seong Gu. 음절 동치표(`_SYL`)를 두고 매핑한다.
②는 이름 뒷부분만 이니셜로 적은 경우다. 앞 음절이 모두 같고 마지막만 한 글자면 접두어인지 확인한다.

**둘 다 음절 수가 같을 것을 요구한다.** 길이가 다르면 다른 사람으로 본다 — 안 그러면 `Kim J` 가 모든 김씨와 묶인다.

## 과분할과 과병합 중 하나를 골라야 한다

동시에 없앨 수 없다. 어느 쪽 오류가 덜 나쁜지 정하고 그 방향으로 기울인다.

- **KOL·업적 분석** → 과병합이 치명적이다(남의 논문이 내 실적이 됨). 풀네임 기본 + alias 로 보수적으로 묶는다.
- **네트워크·규모 추정** → 과분할이 더 아프다. 이니셜 키를 쓰되 결과를 그렇게 읽는다.

정본은 `KEY_MODE = "fullname"` 을 기본으로 두고 `initials` 를 비교용으로 남겨 뒀다. **두 방식을 모두 돌려 차이를 보는 것 자체가 진단**이다.

## 함정

- 묶은 결과를 반드시 사람이 본다. `build_alias_map` 은 `trace` 인자로 어떤 표기가 왜 묶였는지 남긴다.
- 수동 교정은 코드가 아니라 데이터로 둔다(`load_merge_block()` — 묶으면 안 되는 쌍 목록).
- 애매한 건은 `ambig_df` 로 따로 뽑아 검토 대상으로 출력한다.
- ORCID 가 있으면 그것이 최우선이다. 이름 매칭은 ORCID 가 없을 때의 차선책이다.

## 연관 skill

`[[kol-profile]]`(이 판정 위에서 동작), `[[corresponding-author-verify]]`, `[[institution-resolve]]`(같은 종류의 정규화 문제)
SKILL_PAYLOAD_EOF

echo ""
echo "완료 — Skill 1개를 설치했습니다."
echo "Claude Code를 다시 시작하면 인식됩니다."