前言¶
在 DeepSeek Harness（DSH）里写长篇剧本或分支剧情时，人物、设定、待定问题、章节和情节往往散在很多小 Markdown 文件里，跨多次会话也很难一眼看清全貌。常见做法是自己在编辑器里来回翻目录，结构（画布坐标、连线、章节归属）要么记在脑子里，要么另开一份 JSON，和卡片正文容易脱节。
dsh-script-cards 是维护者 tokai-teiodh 发布的客户端插件：在项目目录下用「方片网格」管存档类卡片，用「两级分支画布」管章节与情节，在浏览器里改完直接写回卡片文件；画布结构落在 分支.json，与正文一样能进 git。下面介绍它做什么、怎么装、目录与卡片约定，以及可选的 cards.py 辅助工具。
这是什么¶
插件全名 dsh-script-cards（npm 包名同 GitHub 仓库名），当前资料中的版本为 0.2.1（MIT 许可证）。它面向 DSH 的 Web 客户端：装好后会话头会出现「剧本档案」按钮，右侧栏多一个可停靠页（与对话并排），左侧栏也有一页全屏入口。
一句话定位：两个视图、两族卡片——方片视图收存档族卡片，分支视图收分支族卡片，互不混用；编辑结果写回磁盘上的 Markdown 与 JSON，而不是只存在浏览器里。
| 视图 | 卡片 type（资料原文） |
|---|---|
| 方片 | project character setting scene beat dialogue open decision reference |
| 分支 | chapter node condition result |
社区目录页：skillhub.cn 插件页。源码与说明：GitHub tokai-teiodh/dsh-script-cards。DSH 生态是「一切皆插件」；SkillHub 等目录站与 DeepSeek / 幻方无官方从属关系，安装前请自行查看源码与许可证。
核心功能¶
方片页：全貌与存档¶
方片页是自适应圆角方片网格，按类型分组；标签单行横滑（按住标签条左右拖，左侧卡片区不便拖选文字，右侧详情正文可选）。支持星标收藏与置顶，点开看正文。人物卡可右键设「角色色」，写入卡片 frontmatter 的 color，文档里该人物台词名会跟着变色。
分支页：章节 → 情节，两级画布¶
上级排章节，下级排该章节里的情节；配浏览器式导航（后退 / 前进 / 回到上级 / 刷新 + 面包屑）。双击章节卡片进入下级。
画布交互（资料中的要点）：
- 缩放与平移：滚轮以指针为中心走固定档位（25%～200%）；空白处左键拖动画布；中键、
Alt+左键也可平移。 - 连线：从卡片边缘圆点拖出贝塞尔线，松手连接；拖动卡片时连线实时跟随。线可点击命名，右键可重命名或删除。
- 框选与批量：画布上右键拖虚线框多选；
Delete移出画布，Ctrl+A全选本层；可编组、染色、自动排列（竖排 / 横排）等。 - 引用卡：从「存档卡」抽屉拖入画布的是引用，不复制文件，位置记在
分支.json的refs；虚线边、只读详情，改内容回方片页。 - 文本框与矩形：独立对象，记在
分支.json的objects；不参与连线与自动排列对卡片的同一套文件语义。 - 展开卡片：默认浮动窗口（可图钉、可全屏）；章节 / 节点另有「字段 | 文档」页签，文档是
<档案目录>/文档/<与卡片同名>.md的独立文件。
文档页：长文与台词录入¶
仅在章节、节点类卡片上，文档与卡片正文的 ## 角色 等字段分离。文档输入框支持 Ctrl+S 保存，空文档不落盘。在文档里右键可调人物菜单（来自方片页 type: character 的标题规则）录台词 / 旁白，带 Enter / Shift+Enter 等行首标记规则。未保存草稿暂存在本机浏览器（不写进项目目录）；写盘失败时输入框只读并说明原因。
更细的操作说明在仓库内 操作指南.md（README 中链接）。
安装与启用¶
该包未发布到 npm，需以源码形式放进 DSH profile 的 node_modules，并在 profile 的 bundle 列表里登记。改 bundle 后必须重启 DSH——客户端名单与 Typert 清单在 boot 时组装，不重启不生效。
资料原文安装步骤如下（Windows PowerShell 示例路径，Linux/macOS 请将 $env:DSH_HOME 换为对应环境变量）：
# 1) 克隆进 profile 的 node_modules
git clone https://github.com/tokai-teiodh/dsh-script-cards "$env:DSH_HOME\profiles\desktop\node_modules\dsh-script-cards"
# 2) 把包名加进该 profile 的 dsh.profile.bundles（见 profiles/<profile>/package.json）
# "dsh": { "profile": { "bundles": [ ..., "dsh-script-cards" ] } }
# 3) 重启 DSH
运行环境：package.json 要求 Node >= 20；peer 依赖含 @deepseek-ai/cordis ^4.0.2。
目录约定与卡片格式¶
默认目录在项目根下（名称可在面板「设置」里按项目改，存在浏览器本地）：
<项目根>/
剧本档案/
卡片/*.md ← 一张卡片一个文件
归档/*.md ← 会话总结
文档/*.md ← 章节 / 节点卡片的独立文档（与卡片文件同名）
分支.json ← 章节归属、画布坐标、连线、染色、引用位置等
正文在卡片 .md 里，结构在 分支.json 里；文档是第三份独立文件。frontmatter 字段白名单（与 cards.py 一致）：id / type / title / code / chapter / mode / when / order / summary / tags / color / created / updated / source。
节点示例（资料原文）：
---
id: node-n1
type: node
title: 神社训练
when: 第4天
order: 10
summary: 一行简介（面板卡片最下面那行）
tags: 日常, 支线
---
## 角色
- 甲
## 场景
- 某地
## 内容
- 发生了什么
code：章节序号，如G1.1。chapter：所属章节卡片键，形如card/<文件名去掉 .md>。mode: branch：画成分歧节点（带选项列与多出口）。
典型用法：cards.py（可选）¶
仓库附带零依赖 Python 工具 cards.py，用于初始化档案、增删卡片、归档会话、重建索引等。在项目根执行，例如：
python cards.py init --root .
python cards.py add --spec card.json --root . # 新增卡片（--force 覆盖）
python cards.py archive --spec summary.json --root . # 归档一次会话
python cards.py index --root . # 重建索引
日常编辑以面板为主；CLI 适合批量建卡或与自动化脚本衔接。具体子命令与 JSON spec 以仓库 README 与脚本帮助为准。
适用场景与注意¶
适合谁：在 DSH 里长期维护游戏剧本、互动小说、带分支的情节设计，且希望「文件即真相、git 可 diff」的团队或个人。
权限与安全：插件随当前 DSH 进程运行，能读写你打开的项目目录；安装前应阅读源码与 MIT 许可证，确认 bundle 来源可信。不要在未审查的第三方 profile 里盲目加入 bundle。
依赖与平台：分类为客户端（Web）；未 npm 发布意味着升级需自行拉取仓库或替换 node_modules 目录并重启。
结尾¶
dsh-script-cards 把「散落的 Markdown 卡片」和「分支结构」收进同一套 DSH 面板：方片看设定与素材，画布理章节与连线，改完写回文件。若你在 Harness 里做分支叙事，可按上文步骤装入 profile 并约定好 剧本档案 目录。
- 目录页：https://www.skillhub.cn/plugins/tokai-teiodh/dsh-script-cards
- GitHub：https://github.com/tokai-teiodh/dsh-script-cards
