Metadata-Version: 2.4
Name: scripttrace
Version: 0.1.0
Summary: Local screenplay labeling: upload Markdown/Word, side-by-side edit with change traces, export JSON.
Author: yundong Wu
License: MIT
Project-URL: Homepage, https://github.com/example/scripttrace
Keywords: screenplay,annotation,diff,sft,labeling
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: End Users/Desktop
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi>=0.110
Requires-Dist: uvicorn[standard]>=0.27
Requires-Dist: python-docx>=1.1
Requires-Dist: python-multipart>=0.0.9
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Dynamic: license-file

# scripttrace

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

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

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

## 安装

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

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

```bash
pip install scripttrace
```

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

升级到新版本：

```bash
pip install -U scripttrace
```

### 方式二：从 Git 仓库安装

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

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

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

```bash
git clone <本仓库地址>
cd scripttrace
```

Windows（venv）：

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

macOS / Linux：

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

已有 Conda：

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

## 启动

```bash
scripttrace serve
```

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

[http://127.0.0.1:8765](http://127.0.0.1:8765)

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

```bash
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` 允许局域网访问；请只在信任的网络使用。

查看全部参数：

```bash
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`](samples/demo.md)。

## 剧本怎么写更容易识别

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

```markdown
# 剧名

## 第3集

场景：地下车库 夜

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

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

△ 车灯扫过水泥柱。
```

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

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

## 导出格式

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

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

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

```json
{
  "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`。

## 开发

```bash
pip install -e ".[dev]"
pytest
```

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

## 发布到 PyPI（维护者）

`pip install scripttrace` 能成功，前提是把包上传到 [PyPI](https://pypi.org/)。包名目前是 `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/](https://pypi.org/account/register/)（建议先在 [TestPyPI](https://test.pypi.org/account/register/) 练一次）。
2. 登录后打开 **Account settings → API tokens**，新建 token，权限选 Entire account（第一次发包）或只给 `scripttrace`。
3. token 只显示一次，复制保存。用户名填 `__token__`，密码填整段 `pypi-...`。

### 3. 打包并上传

在项目根目录：

```bash
pip install -U build twine
python -m build
```

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

```bash
twine upload --repository testpypi dist/*
```

测试安装：

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

没问题再发正式源：

```bash
twine upload dist/*
```

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

```bash
pip install scripttrace
scripttrace serve
```

项目页： [https://pypi.org/project/scripttrace/](https://pypi.org/project/scripttrace/)

### 注意

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

## 许可证

[MIT](LICENSE)
