TL;DR

feishu-cli는 Markdown과 飞书 문서를 양방향 무손실 변환하는 CLI 도구이며 AI Agent 통합용 9개 Skill을 제공한다. 변환 파이프라인은 순차 블록 생성 → diagram/table/image 병렬 worker → 역순 폴백 처리의 세 단계로 동작하여 대용량 문서(10,000+ 行 / 127 个图表 / 170+ 个表格)를 처리한 사례가 제시되어 있다. 설치는 curl 한 줄이나 go install, 소스 빌드를 지원하며 Device Flow 기반 OAuth로 사용자 권한을 관리하는 구조다.

주요 기능

• Markdown ↔ 飞书 문서 무손실 변환을 지원한다. 40+ 블록 타입과 코드·표·수식 등 문법을 보존하는 매핑 테이블을 구현했다. 변환 과정에서 Mermaid와 PlantUML을画板으로 변환해 편집 가능한 벡터로 업로드하는 처리 루틴을 포함함이 확인됐다.
• 대규모 문서 병렬 파이프라인을 내장했다. 세 단계(순차 블록 생성 → 다중 worker 병렬 처리(도표/표) → 역순 폴백 처리)로 구성해 처리량을 극대화하며 10,000+ 行 / 127 个图表 / 170+ 个表格 같은 대용량 임포트를 실험적으로 지원한 것으로 나타났다. 실패 항목은 자동으로 코드블록으로 강등해 전체 작업 중단을 방지한다.
• AI Agent 통합용 9개 Skill을 제공한다. Claude Code 같은 에이전트가 문서 생성·메시지 전송·권한관리 등을 직접 호출할 수 있도록 Skill manifest와 참조 워크플로를 포함한다. AI 기반 워크플로에서 즉시 사용 가능한 도구 체인이 제공되는 것으로 나타났다.
• 강력한 스크립트 친화성 및 안전 장치를 갖추었다. 오타나 잘못된 플래그에 대해 스펠링 제안을 하고 쓰기 작업은 --dry-run 옵션으로 미리보기할 수 있으며 idempotency 키로 중복 전송을 방지하는 구현이다. 출력은 --jq/--format로 구조화되어 자동화 파이프라인에 바로 연결 가능함이 확인됐다.

어떻게 동작하는가

feishu-cli는 Markdown 파서를 통해 문서의 블록을 추출한 뒤 블록 시퀀스를 순차 생성하여 문서 뼈대를 만든다. 생성 단계에서 Mermaid/PlantUML 같은 다이어그램 블록은 별도의 diagram worker 풀로 전달되어 SVG/画板 엔진으로 변환하고 변환 결과를 문서에 삽입하는 병렬 처리 파이프라인을 사용한다. 대형 표는 초기 9행을 create_block로 만들고 이후 insert_table_row API를 사용해 같은 블록에 행을 추가하는 방식으로 단일 테이블 연속성을 보존하는 구현이다.

해결 문제

로컬 Markdown을 飞书 문서로 옮길 때 발생하는 구조 손실과 이미지·도표 취급 문제를 해소한다. 변환 파이프라인은 블록별 매핑과 도표의 벡터 변환, 표의 행 추가 전략으로 원본 정보가 소실되지 않도록 설계되었다. 또한 AI Agent가 직접 飞书 리소스를 조작할 수 있도록 Skill 인터페이스를 제공해 에이전트 자동화와 휴먼 운영 간 갭을 줄인다는 문제를 해결했다.

지금 주목받는 이유

AI Agent 연동용 9개 Skill을 통해 Claude Code 등 에이전트가 飞书 리소스를 직접 조작하도록 설계되어 에이전트 자동화 사례에 곧바로 적용 가능하다. 또한 Markdown↔飞书 무손실 변환과画板 벡터 변환 같은 실무용 기능이 충실하여 개발자·도구 통합 수요와 맞아떨어진 것으로 보인다. GitHub Stars 1317과 Releases에 대한 자동 설치 경험 제공이 확산 요인으로 작용한 것으로 나타났다.

차별점

• 무손실 양방향 변환을 목표로 한 블록 매핑 테이블을 제공한다. 제목, 리스트, Callout, 표, 수식 등 40+ 블록 타입을 대응시키며 원문 복원을 고려한 round-trip 지원 로직을 포함한다. 변환 중 도표 실패 시 원문 보존과 폴백 처리를 자동으로 수행하는 점이 차별화 포인트다.
• Mermaid·PlantUML을 editable vector로 변환하여画板에 업로드하는 처리 경로를 제공한다. 단순 이미지 스냅샷이 아니라 편집 가능한 노드와 벡터로 업로드함으로써 이후 飞书에서 직접 수정이 가능하다. 대규모 임포트 실험에서 >90% 성공률을 보고했고 실패 시 자동 강등 로직으로 전환하는 안정성 장치가 있다.
• 대용량 처리에 최적화된 세 단계 병렬 파이프라인을 채택했다. 1단계 순차 블록 생성 → 2단계 diagram/table/image worker 병렬 처리 → 3단계 역순 폴백 처리 구조로 처리량을 확보하며 실제로 10,000+ 行 / 127 个图表 / 170+ 个表格 임포트를 지원한 사례가 제시되어 있다. 병렬 worker 수, 업로드 옵션, 이미지/diagram workers를 플래그로 조정할 수 있는 점도 운영상 유리하다.

사용 사례

• 기술문서·보고서의 로컬 → 飞书 일괄 마이그레이션을 자동화하는 용도에 적합하다. 로컬 Markdown 저장소를 문서 라이브러리로 전환할 때 블록 보존성과 도표 편집 가능성을 유지하는 워크플로를 제공한다. 대용량 문서 처리 파라미터를 조정해 수천 줄 단위 임포트를 배치로 실행할 수 있다.
• AI Agent가 조직 문서·메시지·권한을 제어하도록 하는 자동화 파이프라인에 통합할 수 있다. README에 명시된 9개 Skill을 Agent 플랫폼에 로드하면 문서 생성·메시지 전송·권한 변경 등을 에이전트가 직접 수행할 수 있다. 대화형 에이전트와 결합한 자동 문서 생성·검토·배포 시나리오에 바로 적용 가능함이 확인됐다.
• 운영 스크립트와 CI 파이프라인에서飞书 API를 직접 호출하는 대신 단일 CLI로 통합 관리하는 용도로 효율적이다. api透传 기능과 profile·token 관리·doctor 체크를 통해 권한·토큰·엔드포인트 상태를 자동 검증하는 흐름을 제공한다. --dry-run, idempotency-key, --jq 출력 같은 자동화 친화적 옵션이 존재한다.

시작하기

설치와 인증은 세 단계로 끝난다. 첫째, curl로 제공된 install.sh를 실행하면 플랫폼을 자동 인식해 바이너리를 설치하거나 업데이트한다. 둘째, feishu-cli config create-app --save로 앱을 자동 생성하여 App ID/Secret을 ~/.feishu-cli/config.yaml에 저장하고 셋째, 필요 시 feishu-cli auth login으로 Device Flow 기반 OAuth 인증을 완료하면 즉시 명령을 실행할 수 있다.

요구사항

• Go 1.21+ 환경에서 go install을 통한 빌드가 가능하다. 또한 리포는 사전 빌드된 바이너리를 Releases로 제공하므로 Go 환경이 없는 사용자는 curl 설치 스크립트로도 배포물을 얻을 수 있다. 운영 체제는 Linux/x64, Linux ARM64, macOS(amd64/arm64), Windows x64를 공식적으로 패키지로 지원함이 확인됐다.
• OAuth 권한 설정을 위해 飞书 Open Platform에서 scope를 앱에 부여할 권한이 필요하다. README는 tenant·user scope를 포함하는 JSON을 한 번에 import하도록 권장하며 테넌트 관리자 승인 절차가 필요하다고 명시되어 있다. Device Flow를 통해 User Access Token과 Refresh Token을 ~/.feishu-cli/token.json에 저장하고 자동 갱신을 수행하는 동작 흐름이다.
• 대량 문서 임포트 시 네트워크 대역폭과 API QPS 제한을 고려해야 한다. feishu-cli는 문서 수준에서 병렬 worker 수(diagram-workers/table-workers/image-workers)를 조정하고 문서 단위로 3 QPS 같은 내부 세율을 적용하는 설계를 채택했다. 대형 파일 업로드는 분할 업로드와 Range 다운로드로 대용량 전송을 보조하는 구현이 포함되어 있다.