yuelinghuashu/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 模式** — 文件变更自动重建
---
🚀 快速开始
💡 推荐使用 Makefile 工作流（更高效）
Windows 用户也可使用 story init 生成的 story.ps1（PowerShell 版工作流）：.\story.ps1 init / .\story.ps1 new -Title '我的故事' / .\story.ps1 build。
---
🌱 不止于故事
**通用内容治理** — 任何能被"规范化"的文字资产都可以用同一套工作流：
| 模板模式 | 内容类型 | 典型场景 |
| :------------------------- | :------------------------- | :----------------- |
| --template=story（默认） | 小说 / 故事 | 原创、二创 |
| --template=knowledge | 论文 / 访谈 / 博客 / 笔记 | 知识库、研究库 |
| --template=tech | 教程 / API 文档 / 变更日志 | 技术博客、项目文档 |
---
🤖 让 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 工具 | 说明 |
| ------- | ------------------------------------ | ---------------------------------------------------------- |
| 📖 浏览 | scan_stories / read_chapter | 列出故事库、读取章节（支持按需加载与末尾截断，节省 Token） |
| ✍️ 写作 | write_chapter / create_story | 创建新故事、原子写入正文（可选写后合规校验） |
| ✅ 治理 | edit_config / build / validate | 直接改元数据字段、执行 README 重建、校验配置合法性 |
| 📊 统计 | stats | 获取总字数 / 章节数 / 系列进度 / 健康度 |
> 💡 详细配置与示例见 docs/mcp.md。**MCP Server 会读写当前工作目录下的所有文件，请仅在信任的仓库中运行。**
🎯 微调数据准备（SFT / Embedding）
故事库的结构化输出天然适合作为大模型训练数据源——config.json 自带分类标签，export json 按章节精准切片，export embeddings 输出纯文本块。配合 --stdout + Unix 工具链，**一行管道即可转为标准微调格式**：
> 💡 story-cli 已确保 UTF-8 编码（GBK 自动检测告警）、章节级切片（避免语义截断）、元数据完整（type/series/summary 天然可用作分类标签）。无需二次清洗脚本。
---
🛠️ 常用命令
| 命令 | 描述 |
| --------------------------------------------------------------------------- | ------------------------------------------ |
| story init [--template=story\|knowledge\|tech] | 初始化仓库（默认故事/知识库/技术文档模式） |
| story new "标题" [--type] [--lang] [--author] [--creator] | 创建新条目 |
| story build [--validate-only] [--save-counts] [--watch] | 构建 README |
| story epub "标题" [--all] [--split-by-volume] [--output=dir] [--css=path] | 导出 EPUB |
| story export html / txt / json / md / embeddings [--stdout] | 导出多种格式（embeddings 为文本块 JSONL） |
| story import json --file=xxx.json | 从 JSON 批量导入 |
| story stats [--json] | 创作统计 |