📚 story-cli

Zero-deployment, Git-native Markdown content management CLI. Manage stories/papers/notes/tutorials with a simple directory convention, auto-generate README, export EPUB, Chinese-English bilingual.

✨ Features

• Simple directory convention — content is a folder: NN-名称/ containing config.json + text.md

• Auto-generated README — per-entry and root index are generated automatically (template-driven, customizable)

• Series grouping & ordering — series / seriesOrder control display order; insert anywhere without reshuffling

• Runtime validation — checks configuration before building (required fields, enums, formats)

• Compliance checks — story validate validates against the Story-Repo spec (directory naming / UTF-8 / duplicate sequence numbers / schema)

• Story linking — story link manages weak links; story build automatically suggests candidate links from the same series

• Bilingual support — Chinese/English content + auto-generated localized README

• Chapters + word count — auto-extracts chapter titles and language-aware word counts

• Multi-format export — EPUB (cover rendering / typesetting styles / series metadata) / HTML / TXT / JSON / Markdown / embeddings, with --stdout piping

• General-purpose content platform — knowledge base mode (papers / interviews / notes), tech documentation mode (tutorials / API)

• MCP Server — AI clients (Claude / Cursor) can read and write the content library directly

• GitHub Action — zero-config CI entry point (yuelinghuashu/story-cli@v1), one-click "Push → Build → Publish"

• Watch mode — auto-rebuilds on file changes

Related MCP server: obsidian-kb

🚀 Quick Start

# 安装（需要 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 users can also use the story.ps1 (PowerShell workflow) generated by story init: .\story.ps1 init / .\story.ps1 new -Title '我的故事' / .\story.ps1 build.

🌱 More Than Just Stories

General-purpose content governance — any written asset that can be "normalized" can use the same workflow:

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

🤖 Let AI Manage Your Content Library

story-cli has a built-in MCP Server — AI clients (Claude Desktop / Cursor / VSCode Copilot Chat) can directly read and write your content library. AI can independently complete the full loop of "create → write → build → stats" without manually executing commands in the terminal.

💡 Token efficiency: MCP tools were designed from day one with saving AI invocation costs as the core principle. scan_stories outputs tersely by default (saves ~80-95% for directory browsing), read_chapter supports on-demand truncation (saves ~95%+ for continuation scenarios), stats gets all data in one call (~99%) — every detail is reducing Token consumption for your AI workflow.

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

💡 See docs/mcp.md for detailed configuration and examples. The MCP Server reads and writes all files in the current working directory; only run it in repositories you trust.

🎯 Fine-Tuning Data Preparation (SFT / Embedding)

The structured output of a story library is naturally suited as an LLM training data source — config.json comes with classification tags, export json slices precisely by chapter, export embeddings outputs plain-text chunks. Combined with --stdout + Unix toolchain, a one-line pipeline converts to the standard fine-tuning format:

# 导出为指令微调 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 already ensures UTF-8 encoding (auto-detects GBK with a warning), chapter-level slicing (avoids semantic truncation), and complete metadata (type/series/summary natively usable as classification labels). No secondary cleaning script is needed.

🛠️ Common Commands

See docs/commands.md (bilingual) for aliases, subcommands, arguments, and category descriptions of all commands.

Customize story types/statuses and localized labels:

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

Built-in enums already include labels, so no repeated configuration is needed. Deleting the file falls back to defaults.

📚 Documentation

⚠️ Encoding Requirements

All files must use UTF-8 encoding. A warning is raised when GBK/GB2312 is detected, but the build is not blocked.

🧪 Testing

make test         # 或 pnpm test

All 550+ tests pass. Coverage: scanner, series grouping, validation, template rendering, word counting, internationalization, README generation, EPUB export, CLI end-to-end (smoke tests cover all commands), .storyignore, MCP protocol, JSON import, GitHub Action structure, compliance checks, link suggestions, incremental build cache, embeddings export, and more.

☕ Sponsorship

⚖️ License

MIT

🤝 Contributing

Issues are welcome (bug reports / feature suggestions, form templates available); if you'd like to contribute code, please read CONTRIBUTING.md and learn about the project's positioning in ROADMAP.md.