# Xw Card Writing Assistant（卡片式写作案板）

A card-based writing board for Obsidian: one card = one scene (INT/EXT + location + day/night, one-line action, +/- emotional shift, > < conflict). Cards can be dragged to swap or insert, batch-selected and moved, acts and columns are adjustable, and everything is written back as plain Markdown — always readable, always portable.

通用的**卡片式写作案板**：一块板分几幕，每幕钉若干张索引卡，一张卡 = 一个场景（内/外景＋地点＋日夜、一句话动作、＋/－ 情绪转变、＞＜ 冲突）。所有内容写回 Markdown 纯文本，文件永远可读、可迁移。

## 功能一览

- **15 张空白节拍卡**：不预设任何固定节奏，用什么节拍由你决定；另可在设置里**自定义节拍模板**（可增删、排序、配释义，如「角色卡」这类模块卡）
- **幕管理**：幕可改名、增删、上下移；「移动」下拉选另一幕后本幕整体移到它正下方；改名撞名时两幕**互换名字**（卡片的「幕」字段跟着对调）
- **幕折叠**：幕头 `˄` 一键把整幕收成**标题一行**（✕↑↓˄ 和「移动」跟随收进行内），再点 `˅` 展开；折叠状态随文件保存，下次打开保持原样
- **列**：每幕 1–4 列可调，每张卡自己记列号——加列不挪卡、可以拖进空列
- **卡片**：内/外景、地点、日夜、一句话「事」、＋/－ 情绪转变、＞＜ 冲突，未填的字段自动隐藏、点选填空；右上角圆点 = 状态灯兼编辑入口（墨绿 = 合规 / 桃红 = 缺项）
- **拖拽**：单卡或批量组，拖到目标卡**中腹 = 互换位置**、**靠边 = 插到前/后**（插入位置用两卡之间的线表示）；拖到空白处落到该列末尾
- **批量多选**：工具栏「批量」按钮进入，点选多张后整组拖走（互换 / 插入与单卡同款语义）
- **幕头备注**：幕名下可加多条备注，右上角悬停出现小手即可**拖动排序**（中腹=互换、靠边=插入）
- **格式刷**：先点一张基准卡，再点/框选其他卡一键统一尺寸；开着时支持拖框批量刷
- **宽/高锁定**：工具栏「锁宽」「锁高」开关——锁定后拖拽把手不能改这一维（锁宽→拖拽只能改高；锁高→只能改宽）；格式刷与弹窗手填不受限
- **汇总导出**：一键把全板「事」按编号汇成一篇；每幕可用开关选择是否参与汇总
- **自检**：一键检查缺项、节拍与幕的归属、行末铰链对位
- **色彩编码**：按人物/线索给卡上色，颜色可增删
- **新建卡尺寸**：跟随**同幕同列最后一张卡**（以案板文件为准，拖拽/弹窗/格式刷/手改文件都自动一致）；空列新卡用默认 300×176
- **统一编号**：卡片编号 = 板面视觉顺序（幕→列→从上到下），挪卡、改列数后编号自动按新位置重排，历史文件顺序不影响；导语类卡固定 00、不占号；汇总导出同一套编号

## 安装

### 方式一：社区插件商城（上架后）

Obsidian → 设置 → 第三方插件 → 浏览 → 搜索「**卡片式写作案板**」→ 安装并启用。

### 方式二：手动安装（当前版本）

1. 把 `Xw-Card-Writing-Assistant` 文件夹（含 `manifest.json`、`main.js`、`styles.css` 三个文件）放进你的库：
   `<你的库>/.obsidian/plugins/Xw-Card-Writing-Assistant/`
2. 重启 Obsidian（或 Ctrl+P 执行「重新加载应用」）
3. 设置 → 第三方插件 → 关闭「安全模式」（如未关）→ 在已安装插件里启用「卡片式写作案板」

## 快速上手

1. 左侧 ribbon 点**案板图标**，或 Ctrl+P 搜「打开案板面板」→ 新建或选择案板文件
2. 也可以把 ```xw-card-board``` 代码块嵌进任意笔记，阅读模式下笔记里直接渲染案板
3. 点「插入 15 张空白节拍卡」快速起板，或点某列末尾的「＋」逐张加卡
4. 点卡面空白处直接写「事」；点圆点补全细节
5. 写完点「汇总」导出全文，点「自检」查缺项

## 特型节拍卡：导语 / 衔接点

本插件**不预设任何节拍体系**，但有两个通用概念只要节拍名对上就会自动生效（设置 →「节拍模板」里自建同名模板即可）：

### 「导语」（开篇引子卡）

- **编号固定 00、不占号**：无论这张卡放在哪个幕、哪一列，编号永远是 00，其余卡跳过它连续排 01、02…
- **汇总导出时自动排全文最前**（编号 0）
- **自检豁免**：导语是引子卡，不参与「一场戏 / 情绪转变 / 冲突」四条硬要求检查，状态灯不会因它缺项报警
- 建议：释义可填「开篇引子：几句话把读者勾进来，垫定全篇的语气」

### 「衔接点」（转场卡）

- 自动带**「转折点」标记**（卡面节拍旁出现标签）
- 建议：释义可填「通用转场卡：标记故事从一个段落进入下一个段落」

> 注：名字必须**一字不差**（「导语」两个字，不要带【】或其他前后缀）。配合「插入 15 张空白节拍卡」起板时，把其中一张的节拍改成「导语」就是引子卡。

## 文件格式说明

案板文件是普通 Markdown。卡片就是标准小节，插件用几行 **HTML 注释**记录板面元信息，都不影响正常阅读：

| 注释行 | 含义 |
|---|---|
| `<!-- stc:acts: ... -->` | 各幕的幕名（顺序即板面顺序） |
| `<!-- stc:cols: ... -->` | 每幕的列数 |
| `<!-- stc:hinge: ... -->` | 每幕**行末铰链**（该行最后一张卡预期的节拍），供「自检」对位用 |
| `<!-- stc:actnotes: ... -->` | 幕头备注 |
| `<!-- stc:summary: ... -->` | 哪些幕不参与汇总（有才写） |

> 注：这些 `stc:` 注释是插件的历史内部标记，不影响使用，也不指向任何第三方作品。

## 常见问题

- **改幕名提示重名？** 幕名是卡片「幕」字段的关联键，不能有两幕同名。改成已存在的名字时会**自动两幕互换名字**——例如「第二幕」移到第三位后改名「第三幕」，原第三幕自动变回「第二幕」。
- **节拍下拉里是什么？** 15 张空白节拍（节拍01–节拍15），不预设任何写作流派的具体节奏；想要自己的节拍体系，在设置的「节拍模板」里添加即可。
- **幕移动后卡号会乱吗？** 不会。挪幕时卡片编号按板面显示顺序即时重排（导语类卡固定 00、不占号）。
- **想要「导语」卡（开篇引子）？** 在设置 →「节拍模板」里自建一个名字精确为「导语」的模板，之后把卡的节拍选成它即可——编号固定 00、不占号、汇总导出自动排全文最前、自检豁免。详见上方「特型节拍卡」一节。

## English

**About.** A card-based writing board for outlining stories. One card = one scene
(INT/EXT + location + day/night, a one-line action, a +/- emotional shift, a > < conflict).
Everything is written back into the note as plain Markdown, so your files stay readable,
diff-able and portable — no proprietary format, no lock-in.

**Features**

- **Cards = scenes**: card face holds the scene header, the one-line action, the emotional shift and the conflict; empty fields hide themselves.
- **Drag & drop**: drag a single card onto another to swap, or to its edge to insert (insertion point is shown as a line between two cards); batch-select several cards and move them as a group.
- **Acts & columns**: rename, add, remove, reorder or collapse acts; 1–4 columns per act; drag-sortable notes under each act name.
- **Beat cards**: 15 blank beat cards — no built-in story system; define your own beat templates in settings. Two special names work automatically: 「导语」 (prologue card, always number 00, exported first) and 「衔接点」 (transition card, marked as a turning point).
- **Format painter, width/height locks**, new cards inherit the size of the last card in the same act/column.
- **Unified numbering** by board order (act → column → top to bottom), renumbered automatically when cards move.
- **Summary export** (all "action" lines in order) and a **self-check** panel for missing fields, hinge alignment and stray cards.
- **Colour coding** per character/thread, editable in settings.
- Mobile supported; light and dark themes; **no network access, no telemetry, no analytics**.

**Install (manual)**

1. Put the `Xw-Card-Writing-Assistant` folder (`manifest.json`, `main.js`, `styles.css`) into `<your vault>/.obsidian/plugins/`.
2. Reload Obsidian, then enable "卡片式写作案板" in Settings → Community plugins.

**Usage**

1. Click the board icon in the ribbon (or run the "打开案板面板" command) and pick a board file, or embed a ```` ```xw-card-board ```` code block in any note.
2. Use "插入 15 张空白节拍卡" to start, or the `＋` at the end of a column to add cards one by one.
3. Click a card to write its action text; click the dot in its top-right corner to edit all fields.
4. Use "汇总" to export the whole board as text and "自检" to check for missing pieces.

## 更新日志

### V1.0.02

- 插件显示名改为 **Xw Card Writing Assistant**（官方要求插件名使用基本拉丁字母，中文名会被商城校验拦下）。
- 许可证确定为 **MIT + Commons Clause**；README 增补英文说明。
- 移除「卡数检查」功能（每行/总卡数目标、黑洞提示）。

### V1.0.01

- 首个公开发布版本。
- 卡片式写作案板：一张卡 = 一个场景，支持拖拽互换/插入（插入位置用线表示）、批量多选整组移动、幕/列数可调、幕折叠、幕头备注拖动排序。
- 格式刷刷尺寸、宽/高锁定、新建卡跟随最近调整的尺寸、卡片统一编号（板面视觉顺序）。
- 15 张空白节拍卡 + 自定义节拍模板；「导语」「衔接点」特型节拍卡。
- 状态灯提示缺项、汇总导出与一键自检；全部写回 Markdown 纯文本。

## 权限与隐私 / Permissions & Privacy

- **完全本地运行**：插件不发起任何网络请求，不收集遥测或统计数据，不向任何服务器发送任何内容。
- **库内文件枚举**：为了让你在「切换案板文件」「导入模板」时挑选文件，插件会列出你库中 Markdown 文件的**路径**（`vault.getMarkdownFiles`）；它**不读取这些文件的内容**。插件只读写**你明确选定 / 当前打开的那一份案板文件**（以及新建案板时创建的那一个），**不会改动任何其他笔记**。
- **剪贴板**：只有当你点击汇总弹窗里的「复制」按钮时，插件才把汇总正文**写入**系统剪贴板；它**从不读取**剪贴板内容。
- **无后台行为**：没有定时任务、没有自动更新机制、不调用任何外部进程或命令行。

Fully local: no network requests, no telemetry or analytics, nothing is ever sent anywhere.
**Vault file enumeration**: to let you pick a board file (or a template to import), the plugin lists
the *paths* of Markdown files in your vault; it does not read their contents. It only reads and
writes the board file you explicitly choose or have open (plus the one it creates when you make a
new board) - no other note is ever modified. **Clipboard**: the plugin *writes* to the system
clipboard only when you click the copy button in the summary dialog; it never reads the clipboard.
No background activity: no timers, no auto-update mechanism, no external processes.

## 许可证 / License

**MIT License + Commons Clause**

- **免费使用**：任何人都可以免费使用、复制、修改本插件，**包括商业公司把它用在日常工作中**——拿来写剧本、写小说、做开发，都不受限制。
- **唯一限制：不得出售**。即不得把本插件（或其修改版）作为付费产品或付费服务提供给第三方，包括以收取托管费、咨询费、支持服务费等方式变相收费。
- 如需超出上述范围的授权，请联系作者：https://github.com/Xiawen-Shyan-Wen
- 条款分两份：MIT 正文见 `LICENSE`，Commons Clause 附加条款见 `LICENSE-COMMONS-CLAUSE.txt`（两份合起来即「MIT + Commons Clause」）。

Licensed under the **MIT License** (see `LICENSE`) **with the Commons Clause**
(see `LICENSE-COMMONS-CLAUSE.txt`). Everyone — including companies, for their own internal or
commercial work — may use, copy and modify this plugin free of charge. The only restriction is
that you may not **Sell** the software: you may not provide it (or a modified version of it)
to third parties as a paid product or service, including via fees for hosting, consulting or
support. For any use outside those terms, please contact the author:
https://github.com/Xiawen-Shyan-Wen