📚 story-cli

제로 배포, Git 네이티브 Markdown 콘텐츠 관리 CLI. 간단한 디렉터리 규칙으로 스토리/논문/노트/튜토리얼을 관리하고, README를 자동 생성하며, EPUB을 내보내고, 중영 이중 언어를 지원합니다.

✨ 기능

• 간단한 디렉터리 규칙 — 콘텐츠는 폴더입니다: NN-이름/ 에 config.json + text.md 포함

• README 자동 생성 — 각 항목과 루트 인덱스가 자동 생성됩니다 (템플릿 기반, 사용자 정의 가능)

• 시리즈 그룹 정렬 — series / seriesOrder 로 표시 순서를 제어하며, 임의 삽입 시 재정렬 불필요

• 런타임 검증 — 빌드 전에 구성 검사 (필수 필드, 열거형, 형식)

• 규정 준수 검사 — story validate 가 Story-Repo 규격에 따라 검증 (디렉터리 이름 / UTF-8 / 중복 번호 / schema)

• 연관 스토리 — story link 로 약한 연관 관리; story build 가 같은 시리즈 후보 연관 자동 제안

• 이중 언어 지원 — 중영 콘텐츠 + 현지화된 README 자동 생성

• 챕터 + 단어 수 — 챕터 제목과 언어 인식 단어 수 자동 추출

• 다중 형식 내보내기 — EPUB (표지 렌더링/레이아웃 스타일/시리즈 메타데이터) / HTML / TXT / JSON / Markdown / embeddings, --stdout 파이프 지원

• 범용 콘텐츠 플랫폼 — 지식 베이스 모드 (논문/인터뷰/노트), 기술 문서 모드 (튜토리얼/API)

• MCP Server — AI 클라이언트 (Claude / Cursor) 가 콘텐츠 라이브러리를 직접 읽고 쓸 수 있음

• GitHub Action — 제로 구성 CI 진입점 (yuelinghuashu/story-cli@v1), 원클릭으로 「Push → Build → 배포」 구현

• Watch 모드 — 파일 변경 시 자동 재빌드

Related MCP server: obsidian-kb

🚀 빠른 시작

# 安装（需要 Node.js >= 22）
npm install -g @yuelinghuashu/story-cli

# 创建示例仓库并查看效果
story demo

# 初始化仓库
story init

# 创建内容并编写
story new "我的新故事"

# 构建所有 README
story build

# 导出 EPUB / 统计
story epub --all
story stats

make init                 # 初始化
make new TITLE="我的故事"  # 新建并自动构建
make commit               # 构建 + 提交
make push                 # 构建 + 提交 + 推送
make stats                # 查看创作统计
make analyze              # 写作质量分析（重复短语 / 字数过期 / 章节趋势，需 jq）

Windows 사용자는 story init 으로 생성된 story.ps1 (PowerShell 버전 워크플로우) 도 사용할 수 있습니다: .\story.ps1 init / .\story.ps1 new -Title '我的故事' / .\story.ps1 build.

🌱 이야기 그 이상

범용 콘텐츠 관리 — '정규화'할 수 있는 모든 텍스트 자산은 동일한 워크플로우를 사용할 수 있습니다:

story init --template=knowledge
story init --template=tech

🤖 AI가 콘텐츠 라이브러리를 관리하게 하세요

story-cli에는 MCP Server 가 내장되어 있습니다. AI 클라이언트 (Claude Desktop / Cursor / VSCode Copilot Chat) 가 콘텐츠 라이브러리를 직접 읽고 쓸 수 있습니다. AI는 '생성 → 작성 → 빌드 → 통계'의 완전한 루프를 독립적으로 수행할 수 있으며, 터미널에서 수동으로 명령을 실행할 필요가 없습니다.

💡 토큰 경제성: MCP 도구는 설계 초기부터 AI 호출 비용 절감을 핵심 원칙으로 삼았습니다. scan_stories 는 기본적으로 간결한 출력 (디렉터리 탐색 시 ~80-95% 절약), read_chapter 는 필요에 따라 잘라내기 지원 (이어쓰기 시나리오에서 ~95%+ 절약), stats 는 한 번의 호출로 모든 데이터 확보 (~99%) — 모든 세부 사항이 AI 워크플로우의 토큰 소비를 줄입니다.

# 启动 MCP Server（需在故事仓库根目录；--root 可从任意目录指定仓库）
story mcp-server

💡 자세한 구성과 예시는 docs/mcp.md 를 참조하세요. MCP Server 는 현재 작업 디렉터리의 모든 파일을 읽고 씁니다. 신뢰할 수 있는 저장소에서만 실행하세요.

🎯 미세 조정 데이터 준비 (SFT / Embedding)

스토리 라이브러리의 구조화된 출력은 대규모 언어 모델 훈련 데이터 소스로 자연스럽게 적합합니다. config.json 에는 분류 태그가 포함되어 있고, export json 은 챕터별로 정확하게 슬라이스하며, export embeddings 는 순수 텍스트 블록을 출력합니다. --stdout + Unix 도구 체인과 함께 사용하면 한 줄의 파이프로 표준 미세 조정 형식으로 변환할 수 있습니다:

# 导出为指令微调 JSONL（summary → instruction，正文 → output）
story export json --stdout | jq -c '.stories[] | {messages: [{role: "user", content: .summary}, {role: "assistant", content: .content}]}' > sft_data.jsonl

# 导出为 Embedding 训练格式
story export embeddings --stdout | jq -c '{text: .content, metadata: {title: .title, series: .series}}' > embedding_data.jsonl

# 快速分析数据配比（总字数/章节分布/重复短语）
story stats --json | jq '{words: .totalWords, chapters: .totalChapters, repeated: .analysis.repeated}'

💡 story-cli 는 UTF-8 인코딩 (GBK 자동 감지 경고), 챕터 수준 슬라이스 (의미론적 잘림 방지), 메타데이터 완전성 (type/series/summary 는 자연스럽게 분류 태그로 사용 가능) 을 보장합니다. 추가 정리 스크립트가 필요 없습니다.

🛠️ 주요 명령

모든 명령의 별칭, 하위 명령, 매개변수, 분류 설명은 docs/commands.md (중영 이중 언어) 를 참조하세요.

사용자 정의 스토리 유형/상태 및 현지화 태그:

{
  "types": ["original", "fanfic", "translation"],
  "statuses": ["completed", "ongoing", "planned"],
  "typeLabels": { "translation": { "zh": "翻译", "en": "Translation" } }
}

내장 열거형에는 이미 태그가 내장되어 있어 중복 구성이 필요 없습니다. 파일을 삭제하면 기본값으로 돌아갑니다.

📚 문서

⚠️ 인코딩 요구 사항

모든 파일은 UTF-8 인코딩을 사용해야 합니다. GBK/GB2312 가 감지되면 경고하지만 빌드를 차단하지는 않습니다.

🧪 테스트

make test         # 或 pnpm test

550개 이상의 테스트가 모두 통과했습니다. 포함: 스캐너, 시리즈 그룹화, 검증, 템플릿 렌더링, 단어 수 계산, 국제화, README 생성, EPUB 내보내기, CLI 엔드투엔드 (스모크 테스트가 모든 명령을 포함), .storyignore, MCP 프로토콜, JSON 가져오기, GitHub Action 구조, 규정 준수 검사, 연관 제안, 증분 빌드 캐시, embeddings 내보내기 등.

☕ 후원 지원

⚖️ License

MIT

🤝 기여

Issue 제출을 환영합니다 (버그 피드백 / 기능 제안, 양식 템플릿 있음). 코드 기여를 원하시면 CONTRIBUTING.md 를 읽고, ROADMAP.md 에서 프로젝트 방향을 확인하세요.