story-cli 是一个零部署、Git 原生的 Markdown 内容管理 CLI，用简单的目录约定管理故事、论文、笔记、教程等内容，自动生成 README，导出 EPUB，支持中英双语。
用途 story-cli 面向以 Markdown 写作、并以 Git 仓库管理文字资产的场景。它把内容组织为文件夹：每个条目目录采用 NN-名称/ 形式，包含 config.json 与 text.md。通过这套约定，工具可以统一处理故事、论文、访谈、笔记、教程、API 文档等多种文字内容，形成通用内容中台。
主要能力
- 简单目录约定：内容就是文件夹，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 模式：文件变更自动重建。
使用方式 Windows 用户也可使用 story init 生成的 story.ps1（PowerShell 版工作流）：.\story.ps1 init / .\story.ps1 new -Title '我的故事' / .\story.ps1 build。
MCP Server story-cli 内置 MCP Server，AI 客户端（Claude Desktop / Cursor / VSCode Copilot Chat）可直接读写内容库。AI 能独立完成「创建 → 写作 → 构建 → 统计」的完整闭环，无需在终端手动执行命令。MCP 工具从设计之初就以节省 AI 调用成本为核心原则：scan_stories 默认精简输出（目录浏览节省 ~80-95%）、read_chapter 支持按需截断（续写场景节省 ~95%+）、stats 一次调用拿全数据（~99%）。详细配置与示例见 docs/mcp.md。MCP Server 会读写当前工作目录下的所有文件，请仅在信任的仓库中运行。
微调数据准备（SFT / Embedding） 故事库的结构化输出天然适合作为大模型训练数据源——config.json 自带分类标签，export json 按章节精准切片，export embeddings 输出纯文本块。配合 --stdout + Unix 工具链，一行管道即可转为标准微调格式。story-cli 已确保 UTF-8 编码（GBK 自动检测告警）、章节级切片（避免语义截断）、元数据完整（type/series/summary 天然可用作分类标签），无需二次清洗脚本。
适用场景
- 故事/小说创作与系列管理
- 论文、访谈、笔记等知识库整理
- 教程、API 等技术文档维护
- 通过 MCP 让 AI 客户端直接读写内容库
- 通过 GitHub Action 实现内容自动构建与发布
- 为 SFT / Embedding 准备结构化训练数据
限制与注意事项
- 所有文件必须使用 UTF-8 编码。检测到 GBK/GB2312 时会警告但不阻断构建。
- MCP Server 会读写当前工作目录下的所有文件，请仅在信任的仓库中运行。
- 自定义故事类型/状态及本地化标签时，内置枚举已内置标签，无需重复配置；删除文件即回退默认。
- 全部命令的别名、子命令、参数、分类说明见 docs/commands.md（中英双语）。
- 项目包含 550+ 项测试，覆盖扫描器、系列分组、校验、模板渲染、字数统计、国际化、README 生成、EPUB 导出、CLI 端到端（冒烟测试覆盖全部命令）、.storyignore、MCP 协议、JSON 导入、GitHub Action 结构、合规检查、关联建议、增量构建缓存、embeddings 导出等。
- 欢迎提交 Issue（bug 反馈 / 功能建议，有表单模板）；有意贡献代码请阅读 CONTRIBUTING.md，并在 ROADMAP.md 了解项目定位。
