📚 story-cli

CLI для управления Markdown-контентом с нулевым развертыванием и нативным Git. Управляйте историями/статьями/заметками/уроками с помощью простых соглашений о каталогах, автоматически генерируйте 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.ps1 (рабочий процесс PowerShell), сгенерированный story init: .\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 и т.д.

☕ Поддержка

⚖️ Лицензия

MIT

🤝 Участие в разработке

Приветствуются Issue (отчеты об ошибках / предложения функций, есть шаблоны форм); желающие внести вклад в код, пожалуйста, прочитайте CONTRIBUTING.md и ознакомьтесь с позиционированием проекта в ROADMAP.md.