📚 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 は「作成 → 執筆 → ビルド → 統計」の完全なサイクルを単独で完了でき、ターミナルで手動コマンドを実行する必要はありません。

💡 Token 経済性：MCP ツールは設計当初から AI 呼び出しコストの削減を中核原則としています。scan_stories はデフォルトで簡潔な出力（ディレクトリ閲覧で ~80-95% 削減）、read_chapter はオンデマンドの切り詰めに対応（続き書きのシナリオで ~95%+ 削減）、stats は一度の呼び出しで全データを取得（~99%）——あらゆる細部が AI ワークフローの Token 消費を抑えます。

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

💡 詳細な設定と例は docs/mcp.md を参照してください。MCP Server は現在の作業ディレクトリ内のすべてのファイルを読み書きします。信頼できるリポジトリでのみ実行してください。

🎯 ファインチューニング用データ準備（SFT / Embedding）

ストーリーライブラリの構造化出力は大規模言語モデルのトレーニングデータソースとして自然に適しています——config.json には分類ラベルが組み込まれ、export json は章単位で正確にスライスし、export embeddings はプレーンテキストブロックを出力します。--stdout + Unix ツールチェーンと組み合わせれば、1行のパイプで標準的なファインチューニング形式に変換できます：

# 导出为指令微调 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 でプロジェクトの位置づけをご確認ください。