storyEditor

本项目是一个基于 Electron + React 的本地 Story DSL Markdown 编辑器。

它现在的核心定位是：

• 在本地文件系统上直接编辑 Story DSL Markdown
• 在编辑 / 预览 / 分屏 / 节点图之间来回切换
• 直接从 Story DSL 导出运行侧需要的 JSON

当前能力

• 文本编辑：直接编辑 .md / .markdown
• 实时预览：Markdown 预览与编辑区联动
• 节点视图：把剧情节点、选项连接、缺失引用可视化出来
• 图上编辑：支持创建和修改普通节点、辅助节点、额外选项、触发器、模板
• 数据管理：集中查看和编辑共享 ==# 区块中的数据项
• 文件夹工作区：可打开单文件，也可打开整个故事目录
• JSON 导出：支持单文件导出、批量导出、无界面 CLI 导出
• 编码兼容：读取文件时会自动识别 UTF-8、UTF-16、GBK/GB18030、Big5、Shift_JIS 等常见编码

Story DSL 约定

数据区使用共享 ==# 形式，条目内部用 kind 区分类型：

==#
- id: hp
  kind: stat
  name: 生命值
  value: 10

- id: has_key
  kind: var
  name: 是否持有钥匙
  value: false

快速开始

要求：

• Node.js
• npm

安装并启动开发版：

npm install
npm start

也可以直接用脚本启动：

.\scripts\RunStoryEditor.ps1

或：

scripts\RunStoryEditor.bat

打开文件或目录

应用支持直接把文件或目录路径作为启动参数传入。

例如：

npm start -- .\examples\extra-options-demo.md
npm start -- .\examples

也可以用项目内脚本直接打开一个故事目录：

.\scripts\OpenStoryProject.ps1 "D:\YourStoryProject"

JSON 导出

1. 命令行导出

单文件导出：

npm run export:json -- --file .\examples\extra-options-demo.md

指定输出位置：

npm run export:json -- --file .\examples\extra-options-demo.md --output .\test-exports\single

批量导出目录：

npm run export:json -- --dir .\examples --output .\test-exports\batch --recursive

查看帮助：

npm run export:json -- --help

2. 通过 Electron 主进程无界面导出

npm start -- --export-json --file .\examples\extra-options-demo.md --output .\test-exports\from-electron

命中 --export-json 时，应用不会创建窗口，而是执行导出后退出。

3. 打包后导出

打包后的 storyEditor.exe 也支持同样的 CLI：

.\storyEditor.exe --export-json --file E:\StoryProject\chapter1.md --output E:\StoryExports
.\storyEditor.exe --export-json --dir E:\StoryProject\chaptersmd --output E:\StoryExports --recursive

打包

开发环境构建渲染层并启动：

npm start

生成 Electron 打包产物：

npm run dist

或直接走 electron-builder：

npm run dist:electron

默认输出目录是 dist/。

打包产物怎么用

打包后主要有两种产物形态。

1. 目录版：dist/win-unpacked/

这是 Electron 的解包目录，可以直接整目录拷走使用。

使用方式：

• 保留整个 win-unpacked 目录结构，不要只拿其中一个 .exe
• 进入 dist/win-unpacked/ 后，双击里面的主程序即可启动
• 也可以给它传文件或目录路径，直接打开目标 Story 工程

示例：

.\dist\win-unpacked\storyEditor.exe
.\dist\win-unpacked\storyEditor.exe "E:\StoryProject"
.\dist\win-unpacked\storyEditor.exe "E:\StoryProject\chapter1.md"

如果你需要分发一个“免安装但不是单文件”的版本，直接发整个 win-unpacked 目录即可。

2. 单文件便携版：dist\storyEditor 2.0.0.exe

执行 npm run dist 时，会在 dist/ 下额外生成一个单文件便携版。

按当前 package.json，文件名会是：

dist\storyEditor 2.0.0.exe

使用方式：

• 直接双击即可启动
• 也可以把文件或目录路径作为参数传入
• 也支持 --export-json 无界面导出

示例：

& ".\dist\storyEditor 2.0.0.exe"
& ".\dist\storyEditor 2.0.0.exe" "E:\StoryProject"
& ".\dist\storyEditor 2.0.0.exe" --export-json --file "E:\StoryProject\chapter1.md" --output "E:\StoryExports"

便携版首次运行时，会先把内置运行时自动解包到：

%LOCALAPPDATA%\com.oneannoyday.storyeditor\portable-runtime\

之后再启动真正的内层应用。这个解包目录由程序自行管理，一般不需要手动处理。

目录说明

• src/：React 前端与编辑器主界面
• main.js / preload.js：Electron 主进程与桥接层
• markdown-engine.js：Markdown / Story DSL 解析相关逻辑
• scripts/：运行、打包、导出、文档同步脚本
• examples/：示例 Story DSL 文件
• skill/ai-story-md-dsl/：本地 Story DSL 文档与 skill 源
• AI_STORY_JSON_FORMAT_ZH.md：导出 JSON 格式说明

Story DSL 文档来源

项目内 Story DSL 文档以本地 skill 目录为准：

• skill\ai-story-md-dsl\SKILL.md
• skill\ai-story-md-dsl\references\zh\common-brief.md
• skill\ai-story-md-dsl\references\en\common-brief.md

需要同步到全局 skill 时运行：

npm run sync:story-dsl-docs