scripttrace

本地剧本对照标注工具。把 Markdown / 纯文本 / Word 剧本导入后，左边看原文、右边改台词，删除划红、新增划绿；每句可写「为什么要改」并打 1–5 分，再导出 JSON 或 SFT 训练数据。

全程跑在你自己的电脑上，不上传云端、不连业务数据库。数据默认写在用户目录 ~/.scripttrace/projects/。

需要 Python 3.10+ 和现代浏览器（Chrome / Edge / Firefox）。

安装

需要 Python 3.10+。任选一种方式。

方式一：PyPI（发布后，给别人用这个）

pip install scripttrace

装好后执行 scripttrace serve，浏览器打开终端里打印的地址（默认 http://127.0.0.1:8765）。

升级到新版本：

pip install -U scripttrace

方式二：从 Git 仓库安装

把下面的地址换成你的 GitHub / Gitee 仓库：

pip install git+https://github.com/<你的用户名>/scripttrace.git

方式三：克隆源码（自己改代码时用）

git clone <本仓库地址>
cd scripttrace

Windows（venv）：

python -m venv .venv
.venv\Scripts\activate
pip install -e ".[dev]"

macOS / Linux：

python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

已有 Conda：

conda create -n scripttrace python=3.11 -y
conda activate scripttrace
pip install -e ".[dev]"

启动

scripttrace serve

终端会打印监听地址，默认：

http://127.0.0.1:8765

用浏览器打开即可。换端口或改数据目录：

scripttrace serve --port 9000
scripttrace serve -p 9000 --data-dir D:\labels
scripttrace serve --host 0.0.0.0 --port 9000

--host 0.0.0.0 允许局域网访问；请只在信任的网络使用。

查看全部参数：

scripttrace --help
scripttrace serve --help

参数	环境变量	默认	说明
--host	SCRIPTTRACE_HOST	127.0.0.1	监听地址
-p / --port	SCRIPTTRACE_PORT	8765	端口，范围 1–65535
--data-dir	SCRIPTTRACE_HOME	~/.scripttrace/projects	项目数据目录

怎么用

1. 在左侧「导入」拖入或点击上传剧本（.md / .txt / .docx，也可试 .fountain）。项目名默认取文件名，可在列表里重命名或删除。
2. 中间三栏对照：
   • 原剧本：只读，永远不会被改写。删除的字划红。
   • 修改后：点这里改台词。新增的字划绿。
   • 批注 / 打分：填写为什么要改；星星 1–5 分，再点一次可清空。
3. 工具栏可搜索、筛选「全部 / 已修改 / 未修改」、只看已批注，并用「上一条 / 下一条」跳转。
4. 修改会自动保存（约 1 秒）；也可点「保存」或 Ctrl+S。
5. 点 预览 / 导出 查看统计和数据样例，再下载需要的格式。

侧边栏可折叠（‹ / ☰），折叠状态会记住。

快捷键：

按键	作用
Ctrl+S（macOS：⌘S）	立即保存
Ctrl+↓ / Ctrl+↑	下一条 / 上一条已修改
Esc	关闭预览窗口

仓库里有一份短示例：samples/demo.md。

剧本怎么写更容易识别

解析器会尽量拆成「集 / 场 / 对白 / 动作」等段落。下面这种写法识别最稳：

# 剧名

## 第3集

场景：地下车库 夜

**林深**
此事我已知晓，你不必再解释。

苏晚：我只是希望你能理解我的难处。

△ 车灯扫过水泥柱。

• 集数：第3集 或 EPISODE 3
• 场次：场景：… / 場次 / SCENE，或 INT. / EXT. / 内景 / 外景
• 对白：单独一行角色名（可加粗），下一行台词；或 角色名：台词
• 动作：以 △ 开头的行

文本文件按 UTF-8（带或不带 BOM）或 GB18030 读取。单个文件不超过 20MB。

导出格式

在「预览 / 导出」里可切换三种格式。预览只展示前若干条，下载才是完整文件。

1. 完整 JSON（*.scripttrace.json）

schema: scripttrace.v1。含全部段落、字级 ops、以及改过的对白 SFT 数组。适合存档或二次处理。

{
  "schema": "scripttrace.v1",
  "title": "示例短剧",
  "blocks": [
    {
      "id": "b0007",
      "kind": "dialogue",
      "speaker": "林深",
      "episode": "3",
      "original": "此事我已知晓，你不必再解释。",
      "revised": "我知道了。别解释。",
      "changed": true,
      "note": "太文言，改口语",
      "score": 4,
      "ops": [
        {"op": "delete", "text": "此事我已知晓，你不必再解释。"},
        {"op": "insert", "text": "我知道了。别解释。"}
      ]
    }
  ],
  "sft": [
    {
      "instruction": "把下面这场戏的台词改得更像人说的话。…",
      "input": "第3集 场次 地下车库 角色 林深\n【原文台词】\n此事我已知晓，你不必再解释。",
      "output": "我知道了。别解释。",
      "note": "太文言，改口语",
      "score": 4
    }
  ]
}

ops 为字符级痕迹：equal / delete / insert。

2. 修改轨迹（*.trace.json）

schema: scripttrace.trace.v1。只含改过的句子：deleted / inserted / ops，以及 note、score。适合看「改了什么」。

3. SFT JSONL（*.sft.jsonl）

只含改过的对白，每行一条训练样本：instruction / input / output，并带 note、score。适合拿去微调模型。

原文从未被修改的段落不会进入轨迹或 SFT。

数据存在哪

每个项目是数据目录下的一个文件夹，内含 project.json 和导入时的原始文件副本。原文在服务端视为不可变：保存时只会写入改稿、批注和分数。

Windows 默认路径类似：

C:\Users\<你的用户名>\.scripttrace\projects\

备份或换电脑时，拷贝整个数据目录即可。用 --data-dir 可以指定到网盘或共享盘。

常见问题

页面打不开 / 端口被占用
换一个端口：scripttrace serve -p 9000。

改了代码界面没变化
Python 改动需要重启 scripttrace serve。静态页面请 Ctrl+F5 强制刷新，避免缓存旧的 JS/CSS。

点「预览 / 导出」没反应
先确认终端里的服务还在跑，然后 Ctrl+F5。若刚更新过程序，需要重启服务。

中文文件名下载报错 / 乱码
当前版本已按 RFC 5987 处理下载文件名。请使用本仓库较新的代码，不要用很旧的安装包。

导入的 Word 版式乱了
.docx 只抽取段落文字，复杂表格、文本框可能丢失。重要剧本建议另存为 .md 或 .txt。

开发

pip install -e ".[dev]"
pytest

源码在 src/scripttrace/，页面在 src/scripttrace/static/。可编辑安装后改 Python 即可生效，但仍需重启服务。

发布到 PyPI（维护者）

pip install scripttrace 能成功，前提是把包上传到 PyPI。包名目前是 scripttrace，版本写在 pyproject.toml 的 version 里。

1. 改元数据

打开 pyproject.toml，把占位信息换成真实的：

• authors：你的名字和邮箱
• Homepage：GitHub / Gitee 仓库地址

同一版本号只能上传一次，以后改代码要先把 version 改成 0.1.1、0.2.0 等。

2. 注册账号并做 API token

1. 注册 https://pypi.org/account/register/（建议先在 TestPyPI 练一次）。
2. 登录后打开 Account settings → API tokens，新建 token，权限选 Entire account（第一次发包）或只给 scripttrace。
3. token 只显示一次，复制保存。用户名填 __token__，密码填整段 pypi-...。

3. 打包并上传

在项目根目录：

pip install -U build twine
python -m build

会生成 dist/scripttrace-0.1.0.tar.gz 和 .whl。先发到测试源（可选）：

twine upload --repository testpypi dist/*

测试安装：

pip install -i https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple scripttrace

没问题再发正式源：

twine upload dist/*

上传成功后，别人就可以：

pip install scripttrace
scripttrace serve

项目页： https://pypi.org/project/scripttrace/

注意

• 不要把 token 写进仓库。可用环境变量 TWINE_USERNAME=__token__ 和 TWINE_PASSWORD=pypi-...，或本机 %USERPROFILE%\.pypirc。
• dist/ 已在 .gitignore 里，不要提交构建产物。
• 若提示包名已被占用，改 pyproject.toml 里的 name（例如 yowo-scripttrace），命令行入口 scripttrace 可以保持不变。

许可证

MIT