📚 story-cli

Gestor de contenido Markdown nativo de Git, con cero despliegue. Gestiona historias/artículos/notas/tutoriales con una convención de directorios simple, genera README automáticamente, exporta EPUB, bilingüe chino-inglés.

✨ Características

• Convención de directorios simple — El contenido son carpetas: NN-nombre/ contiene config.json + text.md

• Generación automática de README — Cada entrada y el índice raíz se generan automáticamente (basado en plantillas, personalizable)

• Agrupación y ordenación por series — series / seriesOrder controlan la visualización, inserción sin necesidad de renumerar

• Validación en tiempo de ejecución — Verifica la configuración antes de compilar (campos obligatorios, enumeraciones, formato)

• Verificación de cumplimiento — story validate valida según la especificación Story-Repo (nombres de directorio / UTF-8 / números de serie duplicados / schema)

• Historias relacionadas — story link gestiona relaciones débiles; story build sugiere automáticamente candidatos de la misma serie

• Soporte bilingüe — Contenido chino-inglés + generación automática de README localizado

• Capítulos + recuento de palabras — Extracción automática de títulos de capítulos y recuento de palabras con detección de idioma

• Exportación multi-formato — EPUB (portada renderizada / estilos de maquetación / metadatos de serie) / HTML / TXT / JSON / Markdown / embeddings, con soporte de pipe --stdout

• Plataforma de contenido general — Modo base de conocimiento (artículos/entrevistas/notas), modo documentación técnica (tutoriales/API)

• MCP Server — Los clientes de IA (Claude / Cursor) pueden leer y escribir directamente en la biblioteca de contenido

• GitHub Action — Entrada de CI con cero configuración (yuelinghuashu/story-cli@v1), un clic para «Push → Build → Publicar»

• Modo Watch — Reconstrucción automática ante cambios de archivos

Related MCP server: obsidian-kb

🚀 Inicio rápido

# 安装（需要 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）

Los usuarios de Windows también pueden usar story.ps1 generado por story init (flujo de trabajo en PowerShell): .\story.ps1 init / .\story.ps1 new -Title 'Mi historia' / .\story.ps1 build.

🌱 Más que historias

Gobernanza de contenido general — Cualquier activo de texto que pueda "normalizarse" puede usar el mismo flujo de trabajo:

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

🤖 Deja que la IA gestione tu biblioteca de contenido

story-cli incluye un MCP Server integrado: los clientes de IA (Claude Desktop / Cursor / VSCode Copilot Chat) pueden leer y escribir directamente en tu biblioteca de contenido. La IA puede completar de forma autónoma el ciclo completo de «Crear → Escribir → Compilar → Estadísticas» sin necesidad de ejecutar comandos manualmente en la terminal.

💡 Economía de tokens: las herramientas MCP se diseñaron desde el principio con el ahorro de costes de llamadas de IA como principio central. scan_stories genera salida simplificada por defecto (ahorro de ~80-95 % en navegación de directorios), read_chapter admite truncamiento bajo demanda (ahorro de ~95 %+ en escenarios de continuación de escritura), stats obtiene todos los datos en una sola llamada (~99 %): cada detalle está pensado para reducir el consumo de tokens en tu flujo de trabajo con IA.

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

💡 Para configuración detallada y ejemplos, consulta docs/mcp.md. El MCP Server lee y escribe todos los archivos del directorio de trabajo actual; ejecútalo solo en repositorios de confianza.

🎯 Preparación de datos para fine-tuning (SFT / Embeddings)

La salida estructurada de la biblioteca de historias es naturalmente adecuada como fuente de datos para el entrenamiento de modelos grandes: config.json incluye etiquetas de categoría integradas, export json segmenta con precisión por capítulos, export embeddings genera bloques de texto plano. Combinado con --stdout + herramientas Unix, una sola línea de pipe convierte los datos al formato estándar de fine-tuning:

# 导出为指令微调 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 garantiza codificación UTF-8 (detección automática de advertencia para GBK), segmentación a nivel de capítulo (evita ruptura semántica), metadatos completos (type/series/summary utilizables directamente como etiquetas de categoría). Sin necesidad de scripts de limpieza adicionales.

🛠️ Comandos comunes

Alias, subcomandos, parámetros y clasificación de todos los comandos, consulta docs/commands.md (bilingüe chino-inglés).

Personaliza tipos/estados de historias y etiquetas localizadas:

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

Las enumeraciones integradas ya incluyen etiquetas; no es necesario repetir la configuración. Eliminar el archivo restaura los valores predeterminados.

📚 Documentación

⚠️ Requisitos de codificación

Todos los archivos deben usar codificación UTF-8. Si se detecta GBK/GB2312, se emitirá una advertencia pero no se bloqueará la compilación.

🧪 Pruebas

make test         # 或 pnpm test

Más de 550 pruebas, todas superadas. Cobertura: escáner, agrupación por series, validación, renderizado de plantillas, recuento de palabras, internacionalización, generación de README, exportación EPUB, pruebas end-to-end de CLI (pruebas de humo que cubren todos los comandos), .storyignore, protocolo MCP, importación JSON, estructura de GitHub Action, verificación de cumplimiento, sugerencias de relaciones, caché de compilación incremental, exportación de embeddings, etc.

☕ Patrocinio

⚖️ Licencia

MIT

🤝 Contribuciones

Las Issues son bienvenidas (informes de errores / sugerencias de funciones, con plantillas de formulario); si deseas contribuir con código, lee CONTRIBUTING.md y consulta ROADMAP.md para conocer el enfoque del proyecto.