scripttrace 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 yundong Wu
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,323 @@
1
+ Metadata-Version: 2.4
2
+ Name: scripttrace
3
+ Version: 0.1.0
4
+ Summary: Local screenplay labeling: upload Markdown/Word, side-by-side edit with change traces, export JSON.
5
+ Author: yundong Wu
6
+ License: MIT
7
+ Project-URL: Homepage, https://github.com/example/scripttrace
8
+ Keywords: screenplay,annotation,diff,sft,labeling
9
+ Classifier: Programming Language :: Python :: 3
10
+ Classifier: License :: OSI Approved :: MIT License
11
+ Classifier: Environment :: Web Environment
12
+ Classifier: Intended Audience :: End Users/Desktop
13
+ Requires-Python: >=3.10
14
+ Description-Content-Type: text/markdown
15
+ License-File: LICENSE
16
+ Requires-Dist: fastapi>=0.110
17
+ Requires-Dist: uvicorn[standard]>=0.27
18
+ Requires-Dist: python-docx>=1.1
19
+ Requires-Dist: python-multipart>=0.0.9
20
+ Provides-Extra: dev
21
+ Requires-Dist: pytest>=8; extra == "dev"
22
+ Dynamic: license-file
23
+
24
+ # scripttrace
25
+
26
+ 本地剧本对照标注工具。把 Markdown / 纯文本 / Word 剧本导入后,左边看原文、右边改台词,删除划红、新增划绿;每句可写「为什么要改」并打 1–5 分,再导出 JSON 或 SFT 训练数据。
27
+
28
+ 全程跑在你自己的电脑上,**不上传云端、不连业务数据库**。数据默认写在用户目录 `~/.scripttrace/projects/`。
29
+
30
+ 需要 **Python 3.10+** 和现代浏览器(Chrome / Edge / Firefox)。
31
+
32
+ ## 安装
33
+
34
+ 需要 **Python 3.10+**。任选一种方式。
35
+
36
+ ### 方式一:PyPI(发布后,给别人用这个)
37
+
38
+ ```bash
39
+ pip install scripttrace
40
+ ```
41
+
42
+ 装好后执行 `scripttrace serve`,浏览器打开终端里打印的地址(默认 http://127.0.0.1:8765)。
43
+
44
+ 升级到新版本:
45
+
46
+ ```bash
47
+ pip install -U scripttrace
48
+ ```
49
+
50
+ ### 方式二:从 Git 仓库安装
51
+
52
+ 把下面的地址换成你的 GitHub / Gitee 仓库:
53
+
54
+ ```bash
55
+ pip install git+https://github.com/<你的用户名>/scripttrace.git
56
+ ```
57
+
58
+ ### 方式三:克隆源码(自己改代码时用)
59
+
60
+ ```bash
61
+ git clone <本仓库地址>
62
+ cd scripttrace
63
+ ```
64
+
65
+ Windows(venv):
66
+
67
+ ```powershell
68
+ python -m venv .venv
69
+ .venv\Scripts\activate
70
+ pip install -e ".[dev]"
71
+ ```
72
+
73
+ macOS / Linux:
74
+
75
+ ```bash
76
+ python -m venv .venv
77
+ source .venv/bin/activate
78
+ pip install -e ".[dev]"
79
+ ```
80
+
81
+ 已有 Conda:
82
+
83
+ ```bash
84
+ conda create -n scripttrace python=3.11 -y
85
+ conda activate scripttrace
86
+ pip install -e ".[dev]"
87
+ ```
88
+
89
+ ## 启动
90
+
91
+ ```bash
92
+ scripttrace serve
93
+ ```
94
+
95
+ 终端会打印监听地址,默认:
96
+
97
+ [http://127.0.0.1:8765](http://127.0.0.1:8765)
98
+
99
+ 用浏览器打开即可。换端口或改数据目录:
100
+
101
+ ```bash
102
+ scripttrace serve --port 9000
103
+ scripttrace serve -p 9000 --data-dir D:\labels
104
+ scripttrace serve --host 0.0.0.0 --port 9000
105
+ ```
106
+
107
+ `--host 0.0.0.0` 允许局域网访问;请只在信任的网络使用。
108
+
109
+ 查看全部参数:
110
+
111
+ ```bash
112
+ scripttrace --help
113
+ scripttrace serve --help
114
+ ```
115
+
116
+ | 参数 | 环境变量 | 默认 | 说明 |
117
+ |------|----------|------|------|
118
+ | `--host` | `SCRIPTTRACE_HOST` | `127.0.0.1` | 监听地址 |
119
+ | `-p` / `--port` | `SCRIPTTRACE_PORT` | `8765` | 端口,范围 1–65535 |
120
+ | `--data-dir` | `SCRIPTTRACE_HOME` | `~/.scripttrace/projects` | 项目数据目录 |
121
+
122
+ ## 怎么用
123
+
124
+ 1. 在左侧「导入」拖入或点击上传剧本(`.md` / `.txt` / `.docx`,也可试 `.fountain`)。项目名默认取文件名,可在列表里重命名或删除。
125
+ 2. 中间三栏对照:
126
+ - **原剧本**:只读,永远不会被改写。删除的字划红。
127
+ - **修改后**:点这里改台词。新增的字划绿。
128
+ - **批注 / 打分**:填写为什么要改;星星 1–5 分,再点一次可清空。
129
+ 3. 工具栏可搜索、筛选「全部 / 已修改 / 未修改」、只看已批注,并用「上一条 / 下一条」跳转。
130
+ 4. 修改会自动保存(约 1 秒);也可点「保存」或 `Ctrl+S`。
131
+ 5. 点 **预览 / 导出** 查看统计和数据样例,再下载需要的格式。
132
+
133
+ 侧边栏可折叠(‹ / ☰),折叠状态会记住。
134
+
135
+ 快捷键:
136
+
137
+ | 按键 | 作用 |
138
+ |------|------|
139
+ | `Ctrl+S`(macOS:`⌘S`) | 立即保存 |
140
+ | `Ctrl+↓` / `Ctrl+↑` | 下一条 / 上一条已修改 |
141
+ | `Esc` | 关闭预览窗口 |
142
+
143
+ 仓库里有一份短示例:[`samples/demo.md`](samples/demo.md)。
144
+
145
+ ## 剧本怎么写更容易识别
146
+
147
+ 解析器会尽量拆成「集 / 场 / 对白 / 动作」等段落。下面这种写法识别最稳:
148
+
149
+ ```markdown
150
+ # 剧名
151
+
152
+ ## 第3集
153
+
154
+ 场景:地下车库 夜
155
+
156
+ **林深**
157
+ 此事我已知晓,你不必再解释。
158
+
159
+ 苏晚:我只是希望你能理解我的难处。
160
+
161
+ △ 车灯扫过水泥柱。
162
+ ```
163
+
164
+ - 集数:`第3集` 或 `EPISODE 3`
165
+ - 场次:`场景:…` / `場次` / `SCENE`,或 `INT.` / `EXT.` / `内景` / `外景`
166
+ - 对白:单独一行角色名(可加粗),下一行台词;或 `角色名:台词`
167
+ - 动作:以 `△` 开头的行
168
+
169
+ 文本文件按 `UTF-8`(带或不带 BOM)或 `GB18030` 读取。单个文件不超过 20MB。
170
+
171
+ ## 导出格式
172
+
173
+ 在「预览 / 导出」里可切换三种格式。预览只展示前若干条,**下载才是完整文件**。
174
+
175
+ ### 1. 完整 JSON(`*.scripttrace.json`)
176
+
177
+ `schema: scripttrace.v1`。含全部段落、字级 `ops`、以及改过的对白 SFT 数组。适合存档或二次处理。
178
+
179
+ ```json
180
+ {
181
+ "schema": "scripttrace.v1",
182
+ "title": "示例短剧",
183
+ "blocks": [
184
+ {
185
+ "id": "b0007",
186
+ "kind": "dialogue",
187
+ "speaker": "林深",
188
+ "episode": "3",
189
+ "original": "此事我已知晓,你不必再解释。",
190
+ "revised": "我知道了。别解释。",
191
+ "changed": true,
192
+ "note": "太文言,改口语",
193
+ "score": 4,
194
+ "ops": [
195
+ {"op": "delete", "text": "此事我已知晓,你不必再解释。"},
196
+ {"op": "insert", "text": "我知道了。别解释。"}
197
+ ]
198
+ }
199
+ ],
200
+ "sft": [
201
+ {
202
+ "instruction": "把下面这场戏的台词改得更像人说的话。…",
203
+ "input": "第3集 场次 地下车库 角色 林深\n【原文台词】\n此事我已知晓,你不必再解释。",
204
+ "output": "我知道了。别解释。",
205
+ "note": "太文言,改口语",
206
+ "score": 4
207
+ }
208
+ ]
209
+ }
210
+ ```
211
+
212
+ `ops` 为字符级痕迹:`equal` / `delete` / `insert`。
213
+
214
+ ### 2. 修改轨迹(`*.trace.json`)
215
+
216
+ `schema: scripttrace.trace.v1`。**只含改过的句子**:`deleted` / `inserted` / `ops`,以及 `note`、`score`。适合看「改了什么」。
217
+
218
+ ### 3. SFT JSONL(`*.sft.jsonl`)
219
+
220
+ **只含改过的对白**,每行一条训练样本:`instruction` / `input` / `output`,并带 `note`、`score`。适合拿去微调模型。
221
+
222
+ 原文从未被修改的段落不会进入轨迹或 SFT。
223
+
224
+ ## 数据存在哪
225
+
226
+ 每个项目是数据目录下的一个文件夹,内含 `project.json` 和导入时的原始文件副本。原文在服务端视为不可变:保存时只会写入改稿、批注和分数。
227
+
228
+ Windows 默认路径类似:
229
+
230
+ `C:\Users\<你的用户名>\.scripttrace\projects\`
231
+
232
+ 备份或换电脑时,拷贝整个数据目录即可。用 `--data-dir` 可以指定到网盘或共享盘。
233
+
234
+ ## 常见问题
235
+
236
+ **页面打不开 / 端口被占用**
237
+ 换一个端口:`scripttrace serve -p 9000`。
238
+
239
+ **改了代码界面没变化**
240
+ Python 改动需要**重启** `scripttrace serve`。静态页面请 **Ctrl+F5** 强制刷新,避免缓存旧的 JS/CSS。
241
+
242
+ **点「预览 / 导出」没反应**
243
+ 先确认终端里的服务还在跑,然后 Ctrl+F5。若刚更新过程序,需要重启服务。
244
+
245
+ **中文文件名下载报错 / 乱码**
246
+ 当前版本已按 RFC 5987 处理下载文件名。请使用本仓库较新的代码,不要用很旧的安装包。
247
+
248
+ **导入的 Word 版式乱了**
249
+ `.docx` 只抽取段落文字,复杂表格、文本框可能丢失。重要剧本建议另存为 `.md` 或 `.txt`。
250
+
251
+ ## 开发
252
+
253
+ ```bash
254
+ pip install -e ".[dev]"
255
+ pytest
256
+ ```
257
+
258
+ 源码在 `src/scripttrace/`,页面在 `src/scripttrace/static/`。可编辑安装后改 Python 即可生效,但仍需重启服务。
259
+
260
+ ## 发布到 PyPI(维护者)
261
+
262
+ `pip install scripttrace` 能成功,前提是把包上传到 [PyPI](https://pypi.org/)。包名目前是 `scripttrace`,版本写在 `pyproject.toml` 的 `version` 里。
263
+
264
+ ### 1. 改元数据
265
+
266
+ 打开 `pyproject.toml`,把占位信息换成真实的:
267
+
268
+ - `authors`:你的名字和邮箱
269
+ - `Homepage`:GitHub / Gitee 仓库地址
270
+
271
+ 同一版本号只能上传一次,以后改代码要先把 `version` 改成 `0.1.1`、`0.2.0` 等。
272
+
273
+ ### 2. 注册账号并做 API token
274
+
275
+ 1. 注册 [https://pypi.org/account/register/](https://pypi.org/account/register/)(建议先在 [TestPyPI](https://test.pypi.org/account/register/) 练一次)。
276
+ 2. 登录后打开 **Account settings → API tokens**,新建 token,权限选 Entire account(第一次发包)或只给 `scripttrace`。
277
+ 3. token 只显示一次,复制保存。用户名填 `__token__`,密码填整段 `pypi-...`。
278
+
279
+ ### 3. 打包并上传
280
+
281
+ 在项目根目录:
282
+
283
+ ```bash
284
+ pip install -U build twine
285
+ python -m build
286
+ ```
287
+
288
+ 会生成 `dist/scripttrace-0.1.0.tar.gz` 和 `.whl`。先发到测试源(可选):
289
+
290
+ ```bash
291
+ twine upload --repository testpypi dist/*
292
+ ```
293
+
294
+ 测试安装:
295
+
296
+ ```bash
297
+ pip install -i https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple scripttrace
298
+ ```
299
+
300
+ 没问题再发正式源:
301
+
302
+ ```bash
303
+ twine upload dist/*
304
+ ```
305
+
306
+ 上传成功后,别人就可以:
307
+
308
+ ```bash
309
+ pip install scripttrace
310
+ scripttrace serve
311
+ ```
312
+
313
+ 项目页: [https://pypi.org/project/scripttrace/](https://pypi.org/project/scripttrace/)
314
+
315
+ ### 注意
316
+
317
+ - 不要把 token 写进仓库。可用环境变量 `TWINE_USERNAME=__token__` 和 `TWINE_PASSWORD=pypi-...`,或本机 `%USERPROFILE%\.pypirc`。
318
+ - `dist/` 已在 `.gitignore` 里,不要提交构建产物。
319
+ - 若提示包名已被占用,改 `pyproject.toml` 里的 `name`(例如 `yowo-scripttrace`),命令行入口 `scripttrace` 可以保持不变。
320
+
321
+ ## 许可证
322
+
323
+ [MIT](LICENSE)
@@ -0,0 +1,300 @@
1
+ # scripttrace
2
+
3
+ 本地剧本对照标注工具。把 Markdown / 纯文本 / Word 剧本导入后,左边看原文、右边改台词,删除划红、新增划绿;每句可写「为什么要改」并打 1–5 分,再导出 JSON 或 SFT 训练数据。
4
+
5
+ 全程跑在你自己的电脑上,**不上传云端、不连业务数据库**。数据默认写在用户目录 `~/.scripttrace/projects/`。
6
+
7
+ 需要 **Python 3.10+** 和现代浏览器(Chrome / Edge / Firefox)。
8
+
9
+ ## 安装
10
+
11
+ 需要 **Python 3.10+**。任选一种方式。
12
+
13
+ ### 方式一:PyPI(发布后,给别人用这个)
14
+
15
+ ```bash
16
+ pip install scripttrace
17
+ ```
18
+
19
+ 装好后执行 `scripttrace serve`,浏览器打开终端里打印的地址(默认 http://127.0.0.1:8765)。
20
+
21
+ 升级到新版本:
22
+
23
+ ```bash
24
+ pip install -U scripttrace
25
+ ```
26
+
27
+ ### 方式二:从 Git 仓库安装
28
+
29
+ 把下面的地址换成你的 GitHub / Gitee 仓库:
30
+
31
+ ```bash
32
+ pip install git+https://github.com/<你的用户名>/scripttrace.git
33
+ ```
34
+
35
+ ### 方式三:克隆源码(自己改代码时用)
36
+
37
+ ```bash
38
+ git clone <本仓库地址>
39
+ cd scripttrace
40
+ ```
41
+
42
+ Windows(venv):
43
+
44
+ ```powershell
45
+ python -m venv .venv
46
+ .venv\Scripts\activate
47
+ pip install -e ".[dev]"
48
+ ```
49
+
50
+ macOS / Linux:
51
+
52
+ ```bash
53
+ python -m venv .venv
54
+ source .venv/bin/activate
55
+ pip install -e ".[dev]"
56
+ ```
57
+
58
+ 已有 Conda:
59
+
60
+ ```bash
61
+ conda create -n scripttrace python=3.11 -y
62
+ conda activate scripttrace
63
+ pip install -e ".[dev]"
64
+ ```
65
+
66
+ ## 启动
67
+
68
+ ```bash
69
+ scripttrace serve
70
+ ```
71
+
72
+ 终端会打印监听地址,默认:
73
+
74
+ [http://127.0.0.1:8765](http://127.0.0.1:8765)
75
+
76
+ 用浏览器打开即可。换端口或改数据目录:
77
+
78
+ ```bash
79
+ scripttrace serve --port 9000
80
+ scripttrace serve -p 9000 --data-dir D:\labels
81
+ scripttrace serve --host 0.0.0.0 --port 9000
82
+ ```
83
+
84
+ `--host 0.0.0.0` 允许局域网访问;请只在信任的网络使用。
85
+
86
+ 查看全部参数:
87
+
88
+ ```bash
89
+ scripttrace --help
90
+ scripttrace serve --help
91
+ ```
92
+
93
+ | 参数 | 环境变量 | 默认 | 说明 |
94
+ |------|----------|------|------|
95
+ | `--host` | `SCRIPTTRACE_HOST` | `127.0.0.1` | 监听地址 |
96
+ | `-p` / `--port` | `SCRIPTTRACE_PORT` | `8765` | 端口,范围 1–65535 |
97
+ | `--data-dir` | `SCRIPTTRACE_HOME` | `~/.scripttrace/projects` | 项目数据目录 |
98
+
99
+ ## 怎么用
100
+
101
+ 1. 在左侧「导入」拖入或点击上传剧本(`.md` / `.txt` / `.docx`,也可试 `.fountain`)。项目名默认取文件名,可在列表里重命名或删除。
102
+ 2. 中间三栏对照:
103
+ - **原剧本**:只读,永远不会被改写。删除的字划红。
104
+ - **修改后**:点这里改台词。新增的字划绿。
105
+ - **批注 / 打分**:填写为什么要改;星星 1–5 分,再点一次可清空。
106
+ 3. 工具栏可搜索、筛选「全部 / 已修改 / 未修改」、只看已批注,并用「上一条 / 下一条」跳转。
107
+ 4. 修改会自动保存(约 1 秒);也可点「保存」或 `Ctrl+S`。
108
+ 5. 点 **预览 / 导出** 查看统计和数据样例,再下载需要的格式。
109
+
110
+ 侧边栏可折叠(‹ / ☰),折叠状态会记住。
111
+
112
+ 快捷键:
113
+
114
+ | 按键 | 作用 |
115
+ |------|------|
116
+ | `Ctrl+S`(macOS:`⌘S`) | 立即保存 |
117
+ | `Ctrl+↓` / `Ctrl+↑` | 下一条 / 上一条已修改 |
118
+ | `Esc` | 关闭预览窗口 |
119
+
120
+ 仓库里有一份短示例:[`samples/demo.md`](samples/demo.md)。
121
+
122
+ ## 剧本怎么写更容易识别
123
+
124
+ 解析器会尽量拆成「集 / 场 / 对白 / 动作」等段落。下面这种写法识别最稳:
125
+
126
+ ```markdown
127
+ # 剧名
128
+
129
+ ## 第3集
130
+
131
+ 场景:地下车库 夜
132
+
133
+ **林深**
134
+ 此事我已知晓,你不必再解释。
135
+
136
+ 苏晚:我只是希望你能理解我的难处。
137
+
138
+ △ 车灯扫过水泥柱。
139
+ ```
140
+
141
+ - 集数:`第3集` 或 `EPISODE 3`
142
+ - 场次:`场景:…` / `場次` / `SCENE`,或 `INT.` / `EXT.` / `内景` / `外景`
143
+ - 对白:单独一行角色名(可加粗),下一行台词;或 `角色名:台词`
144
+ - 动作:以 `△` 开头的行
145
+
146
+ 文本文件按 `UTF-8`(带或不带 BOM)或 `GB18030` 读取。单个文件不超过 20MB。
147
+
148
+ ## 导出格式
149
+
150
+ 在「预览 / 导出」里可切换三种格式。预览只展示前若干条,**下载才是完整文件**。
151
+
152
+ ### 1. 完整 JSON(`*.scripttrace.json`)
153
+
154
+ `schema: scripttrace.v1`。含全部段落、字级 `ops`、以及改过的对白 SFT 数组。适合存档或二次处理。
155
+
156
+ ```json
157
+ {
158
+ "schema": "scripttrace.v1",
159
+ "title": "示例短剧",
160
+ "blocks": [
161
+ {
162
+ "id": "b0007",
163
+ "kind": "dialogue",
164
+ "speaker": "林深",
165
+ "episode": "3",
166
+ "original": "此事我已知晓,你不必再解释。",
167
+ "revised": "我知道了。别解释。",
168
+ "changed": true,
169
+ "note": "太文言,改口语",
170
+ "score": 4,
171
+ "ops": [
172
+ {"op": "delete", "text": "此事我已知晓,你不必再解释。"},
173
+ {"op": "insert", "text": "我知道了。别解释。"}
174
+ ]
175
+ }
176
+ ],
177
+ "sft": [
178
+ {
179
+ "instruction": "把下面这场戏的台词改得更像人说的话。…",
180
+ "input": "第3集 场次 地下车库 角色 林深\n【原文台词】\n此事我已知晓,你不必再解释。",
181
+ "output": "我知道了。别解释。",
182
+ "note": "太文言,改口语",
183
+ "score": 4
184
+ }
185
+ ]
186
+ }
187
+ ```
188
+
189
+ `ops` 为字符级痕迹:`equal` / `delete` / `insert`。
190
+
191
+ ### 2. 修改轨迹(`*.trace.json`)
192
+
193
+ `schema: scripttrace.trace.v1`。**只含改过的句子**:`deleted` / `inserted` / `ops`,以及 `note`、`score`。适合看「改了什么」。
194
+
195
+ ### 3. SFT JSONL(`*.sft.jsonl`)
196
+
197
+ **只含改过的对白**,每行一条训练样本:`instruction` / `input` / `output`,并带 `note`、`score`。适合拿去微调模型。
198
+
199
+ 原文从未被修改的段落不会进入轨迹或 SFT。
200
+
201
+ ## 数据存在哪
202
+
203
+ 每个项目是数据目录下的一个文件夹,内含 `project.json` 和导入时的原始文件副本。原文在服务端视为不可变:保存时只会写入改稿、批注和分数。
204
+
205
+ Windows 默认路径类似:
206
+
207
+ `C:\Users\<你的用户名>\.scripttrace\projects\`
208
+
209
+ 备份或换电脑时,拷贝整个数据目录即可。用 `--data-dir` 可以指定到网盘或共享盘。
210
+
211
+ ## 常见问题
212
+
213
+ **页面打不开 / 端口被占用**
214
+ 换一个端口:`scripttrace serve -p 9000`。
215
+
216
+ **改了代码界面没变化**
217
+ Python 改动需要**重启** `scripttrace serve`。静态页面请 **Ctrl+F5** 强制刷新,避免缓存旧的 JS/CSS。
218
+
219
+ **点「预览 / 导出」没反应**
220
+ 先确认终端里的服务还在跑,然后 Ctrl+F5。若刚更新过程序,需要重启服务。
221
+
222
+ **中文文件名下载报错 / 乱码**
223
+ 当前版本已按 RFC 5987 处理下载文件名。请使用本仓库较新的代码,不要用很旧的安装包。
224
+
225
+ **导入的 Word 版式乱了**
226
+ `.docx` 只抽取段落文字,复杂表格、文本框可能丢失。重要剧本建议另存为 `.md` 或 `.txt`。
227
+
228
+ ## 开发
229
+
230
+ ```bash
231
+ pip install -e ".[dev]"
232
+ pytest
233
+ ```
234
+
235
+ 源码在 `src/scripttrace/`,页面在 `src/scripttrace/static/`。可编辑安装后改 Python 即可生效,但仍需重启服务。
236
+
237
+ ## 发布到 PyPI(维护者)
238
+
239
+ `pip install scripttrace` 能成功,前提是把包上传到 [PyPI](https://pypi.org/)。包名目前是 `scripttrace`,版本写在 `pyproject.toml` 的 `version` 里。
240
+
241
+ ### 1. 改元数据
242
+
243
+ 打开 `pyproject.toml`,把占位信息换成真实的:
244
+
245
+ - `authors`:你的名字和邮箱
246
+ - `Homepage`:GitHub / Gitee 仓库地址
247
+
248
+ 同一版本号只能上传一次,以后改代码要先把 `version` 改成 `0.1.1`、`0.2.0` 等。
249
+
250
+ ### 2. 注册账号并做 API token
251
+
252
+ 1. 注册 [https://pypi.org/account/register/](https://pypi.org/account/register/)(建议先在 [TestPyPI](https://test.pypi.org/account/register/) 练一次)。
253
+ 2. 登录后打开 **Account settings → API tokens**,新建 token,权限选 Entire account(第一次发包)或只给 `scripttrace`。
254
+ 3. token 只显示一次,复制保存。用户名填 `__token__`,密码填整段 `pypi-...`。
255
+
256
+ ### 3. 打包并上传
257
+
258
+ 在项目根目录:
259
+
260
+ ```bash
261
+ pip install -U build twine
262
+ python -m build
263
+ ```
264
+
265
+ 会生成 `dist/scripttrace-0.1.0.tar.gz` 和 `.whl`。先发到测试源(可选):
266
+
267
+ ```bash
268
+ twine upload --repository testpypi dist/*
269
+ ```
270
+
271
+ 测试安装:
272
+
273
+ ```bash
274
+ pip install -i https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple scripttrace
275
+ ```
276
+
277
+ 没问题再发正式源:
278
+
279
+ ```bash
280
+ twine upload dist/*
281
+ ```
282
+
283
+ 上传成功后,别人就可以:
284
+
285
+ ```bash
286
+ pip install scripttrace
287
+ scripttrace serve
288
+ ```
289
+
290
+ 项目页: [https://pypi.org/project/scripttrace/](https://pypi.org/project/scripttrace/)
291
+
292
+ ### 注意
293
+
294
+ - 不要把 token 写进仓库。可用环境变量 `TWINE_USERNAME=__token__` 和 `TWINE_PASSWORD=pypi-...`,或本机 `%USERPROFILE%\.pypirc`。
295
+ - `dist/` 已在 `.gitignore` 里,不要提交构建产物。
296
+ - 若提示包名已被占用,改 `pyproject.toml` 里的 `name`(例如 `yowo-scripttrace`),命令行入口 `scripttrace` 可以保持不变。
297
+
298
+ ## 许可证
299
+
300
+ [MIT](LICENSE)
@@ -0,0 +1,44 @@
1
+ [build-system]
2
+ requires = ["setuptools>=68", "wheel"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "scripttrace"
7
+ version = "0.1.0"
8
+ description = "Local screenplay labeling: upload Markdown/Word, side-by-side edit with change traces, export JSON."
9
+ readme = "README.md"
10
+ license = { text = "MIT" }
11
+ requires-python = ">=3.10"
12
+ authors = [{ name = "yundong Wu" }]
13
+ keywords = ["screenplay", "annotation", "diff", "sft", "labeling"]
14
+ classifiers = [
15
+ "Programming Language :: Python :: 3",
16
+ "License :: OSI Approved :: MIT License",
17
+ "Environment :: Web Environment",
18
+ "Intended Audience :: End Users/Desktop",
19
+ ]
20
+ dependencies = [
21
+ "fastapi>=0.110",
22
+ "uvicorn[standard]>=0.27",
23
+ "python-docx>=1.1",
24
+ "python-multipart>=0.0.9",
25
+ ]
26
+
27
+ [project.optional-dependencies]
28
+ dev = ["pytest>=8"]
29
+
30
+ [project.scripts]
31
+ scripttrace = "scripttrace.cli:main"
32
+
33
+ [project.urls]
34
+ Homepage = "https://github.com/example/scripttrace"
35
+
36
+ [tool.setuptools.packages.find]
37
+ where = ["src"]
38
+
39
+ [tool.setuptools.package-data]
40
+ scripttrace = ["static/*"]
41
+
42
+ [tool.pytest.ini_options]
43
+ testpaths = ["tests"]
44
+ pythonpath = ["src"]
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1,3 @@
1
+ """Local screenplay labeling with side-by-side change traces."""
2
+
3
+ __version__ = "0.1.0"
@@ -0,0 +1,4 @@
1
+ from scripttrace.cli import main
2
+
3
+ if __name__ == "__main__":
4
+ raise SystemExit(main())