Jcchen2026/feishu-doc-publish

飞书文档发布（Feishu Doc Publisher）

Agent 총칙 (필독)

1. 飞书 게시 작업 발생 → 먼저 이 스킬을 읽고 CLI 실행; 사용자에게 직접 명령어를 실행하라고만 알리지 마세요.
2. OAuth 만료 / 토큰 없음 → Agent가 자동 복구 (§OAuth 만료 자동 복구 참조); 사용자는 브라우저에서「승인」만 클릭하면 됩니다.
3. 자격 증명 검색 순서 (config.py에 이미 구현되어 있으므로 Agent가 중복 복사 금지):
   • tools/feishu_doc_publisher/.env + feishu_tokens.json (프로젝트 내부, 기본값)
   • 없으면 → ~/.cursor/tools/feishu_doc_publisher/ 또는 ~/.claude/tools/feishu_doc_publisher/ (로컬 덮어쓰기)
4. Registry: tools/feishu_doc_publisher/clusters/registry.json (선택 사항; registry가 없으면 docs/modules/<cluster>-module-map.md 규칙에 따라 추론)

최초 설치 (대상 프로젝트)

# 한 줄 설치 (공개 저장소)
curl -fsSL https://raw.githubusercontent.com/Jcchen2026/feishu-doc-publish/main/install.sh | bash -s -- /path/to/your-repo

# 또는 clone 후 설치
git clone https://github.com/Jcchen2026/feishu-doc-publish.git
/path/to/feishu-doc-publish/install.sh /path/to/your-repo

설치 후 .env를 구성하고 OAuth를 한 번 수행하세요. 자세한 내용은 tools/feishu_doc_publisher/README.md를 참조하세요.

표준 게시 (단일 Markdown)

cd tools/feishu_doc_publisher
python3 cli.py publish \
  --markdown ../../docs/guides/<file>.md \
  --title "<Feishu 문서 제목>" \
  --state-file feishu_doc_state_<slug>.json

표준 게시 (module-map)

tools/feishu_doc_publisher/sync_module_map.sh --dry-run --cluster <cluster>
tools/feishu_doc_publisher/sync_module_map.sh --cluster <cluster>

사용자가「飞书 게시 / sync module-map」이라고 말하면 → Agent가 직접 위 명령어를 실행하고 feishu_url을 반환합니다.

---

Publish Safety Gate (P0)

배경: PUBLISH_INCIDENTS.md · 관련 없는 Feishu 문서 덮어쓰기 사고.

조건을 하나라도 충족하지 않으면 → 중단, 게시 금지.

게시 전 체크리스트 (Agent 자가 점검)

• 클러스터 모드인 경우 반드시 feishu_doc_state_<cluster>.json을 사용해야 함
• module-map 게시 대상으로 feishu_doc_state.json을 묵시적으로 사용하는 것 금지
• module-map.md에서 feishu.cn/docx/<id>를 추출하여 state 내의 document_id와 반드시 일치해야 함
• 먼저 --dry-run을 실행하여 출력에 publish_target: OK가 포함되어 있는지 확인
• 게시 성공 후: module-map / README의 Feishu URL을 자동으로 수정하는 것 금지 (사용자가 새 문서 바인딩을 명시적으로 요청하지 않은 경우)
• 사람이 확인할 수 있도록 출력: state_file · doc_id · module-map doc_id

금지 사항

• ❌ 클러스터 게시 시 feishu_doc_state.json을 대상으로 사용하는 것
• ❌ 게시 출력 URL이 module-map과 다르다고 해서 module-map Feishu 링크를 자동으로 수정하는 것
• ❌ --dry-run으로 publish_target을 검증하지 않고 바로 공식 게시하는 것

---

OAuth 만료 자동 복구 (P0 · Agent 필수 실행)

트리거 시점

오류 키워드	의미
No user_access_token found	토큰 없음
Authentication token expired / 99991677	access_token 만료
invalid_grant / refresh token has been revoked	refresh_token 무효화

Agent 표준 절차

cd tools/feishu_doc_publisher
python3 cli.py oauth serve --timeout 600

Agent는 반드시:

1. 직접 oauth serve를 실행해야 함 (background + 'OAuth complete'까지 폴링 가능).
2. 사용자에게 알림: 「브라우저에서 Feishu 승인 페이지가 열렸습니다. 한 번만 승인을 클릭해 주세요.」
3. 승인 성공 후 즉시 원래 작업을 재시도.
4. 팀이 토큰을 공유하는 경우 새 feishu_tokens.json을 커밋 (App Secret은 제출 금지).

금지 사항

• ❌ "oauth start / finish를 먼저 실행하세요"만 출력하고 사용자가 직접 터미널에서 작업하도록 하는 것
• ❌ OAuth 복구 후 로컬의 이전 토큰으로 프로젝트 내의 feishu_tokens.json을 덮어쓰는 것

---

문서 분류

• 규칙: tools/feishu_doc_publisher/CLASSIFY.md
• 설정: feishu_categories.json (feishu_categories.json.example에서 복사)
• 상태 정렬: python3 cli.py reconcile-states
• 새 카테고리 생성: python3 setup_category.py <category> --drive-name "..." --wiki-name "..." --wiki-root-node <token>

BugFix 수정 설명

항목	값
category	bugfix (또는 프로젝트 사용자 정의)
작성 규칙	tools/feishu_doc_publisher/BUGFIX_DOC_WRITING.md
Cursor rule	.cursor/rules/feishu-bugfix-doc-writing.mdc

---

Mermaid

• Git에서 ```mermaid 소스 코드 유지
• 기본값 FEISHU_MERMAID_MODE=addons: ```mermaid → Feishu add_ons「텍스트 다이어그램」 네이티브 플로우차트로 변환
• 실패 시 대체 PNG 이미지: docs/assets/<cluster>/

범위

• 수정 허용: tools/feishu_doc_publisher/**、docs/**、.cursor/skills/feishu-doc-publish/**
• 커밋 금지: .env (Secret 포함)、feishu_tokens.json (팀 정책에 따라 자체 결정)、feishu_folders.json、feishu_wiki.json (로컬 캐시)