字数工作台

本页只展示工具说明。运行工具时，请打开本地小说工作区的 tools 文件夹；网页不提供启动脚本下载。

需要同时更新网站时，Windows 双击更新网站.cmd，Mac 使用更新网站.command。网站入口会先执行本工具的更新与核对，再同步小说、生成作品首页、构建网站并打开预览，无需先单独点“更新字数”。网站需要已有的 Node.js 环境；下面的独立字数工具仍只使用系统自带能力。

保存正文后，Windows 双击更新字数.cmd，Mac 双击更新字数.command。每次更新一次，核对完保留结果，按键后结束。无需安装 Python、Node、PowerShell 7 或其他软件，也不依赖 Obsidian。

日常使用

用任意编辑器修改并保存 Markdown，再运行对应入口。窗口按“项目统计 → 文件明细 → 完成核对 → 本次总览”显示：

蓝青色用于标题与阶段，白色用于项目名称，灰色用于路径和辅助说明。
金色标记已更新、待处理的统计；增量为绿色、减量为金色，不把删减文字当作错误。
绿色表示核对完成，红色用于真正的执行错误。
每个项目显示“一致”或“已更新”；列出变动文件、旧字数、新字数与增减量，并说明新增、改名、移出统计、格式修复和只读保护恢复。
没有变化时明确显示“本次无变化，未改写文件”，不会反复刷新文件修改时间。

窗口随系统终端宽度自然换行，不强制改字体、窗口大小或系统主题。颜色使用终端的基础调色板；设置 NO_COLOR=1 可关闭脚本配色。Mac 是否自动关闭终端窗口取决于终端设置。

这些是统计和生成文件的变化，不保存正文版本历史。两种计数都不变的改写不会被报告为字数变化。

工具只读写本地文件，不联网、不上传、不监听文件、不在后台运行。执行窗口等待按键期间不会继续统计；未保存的编辑不计入。后续改稿需要再次执行。

系统要求与 Mac 首次使用

Windows 使用系统自带的 Windows PowerShell 5.1；Mac 使用系统自带的 /usr/bin/osascript、JavaScript for Automation 和 Foundation。两端遵守相同口径、配置和报告格式，不需要额外运行环境。

把完整工作区复制到 Mac，保留 tools 和各项目之间的位置关系。若复制后双击提示没有执行权限，在工作区根目录的终端运行一次：

chmod u+x tools/更新字数.command

也可直接运行，无需设置执行权限：

bash tools/更新字数.command

Windows 入口只为本次脚本进程设置执行策略，不修改机器的永久设置；若组织策略禁用系统脚本，窗口会保留系统提示。

系统能力参考：Microsoft：随 Windows 提供的 PowerShell、Apple：JavaScript for Automation、Apple：脚本执行权限。

统计内容与保护

仅扫描项目指定目录中的 Markdown。正文须有完整属性区及 类型: 正文；缺失属性区、无效或重复章序会报错，不静默漏计。
主口径 han_ascii_characters：汉字、英文字母、数字各计一字，英文按字母而非单词计数。辅助口径为正文去空白后的可见字符，扩展汉字与 emoji 按 Unicode 字符计数。
排除属性、标题、HTML/Obsidian 注释、图片、嵌入与格式符号；链接计显示文字。正文代码内容仍计数，代码围栏不计。
作者笔记优先另存；正文中的备注可用  与  成对包围，不支持嵌套。
只回写 正文字数，保留其他属性、正文、UTF-8 BOM 与原换行。统计期间检测到文件被改动时停止该项目并提示重试；运行时应先保存并暂时停笔。
生成统计表和可选章节清单设为只读。正文仍可编辑，字数属性被误改时下次执行恢复为实测值。只读保护不是不可绕过的权限边界。
同一工作区同时执行多个入口时，后启动的一份会提示等待；结束或中断后系统自动释放锁，不留后台进程。

新项目接入

无需添加书名名单。工作区直接子目录中的项目有标准 08_正文/ 即可自动识别，首次成功执行后补充以下配置。check 只检查，不创建配置或改写项目文件。

{
  "source": "08_正文",
  "report": "90_项目管理/正文字数统计.md",
  "count_mode": "han_ascii_characters"
}

已有 90_项目管理/字数统计配置.json 优先。非标准目录通过配置指定，所有路径均相对于项目根目录，不能越界或经过符号链接，输出不能放入正文目录。无效配置会报错，不回退默认值。

可增加 chapter_index 指向项目内的 JSON 清单；该文件由工具完整生成，不应混入手写资料。首次自动接入遇到同名手写统计表时，会提示另选输出位置，避免覆盖。

非交互执行与维护

以下命令均在工作区根目录执行，不等待按键。sync 更新一次，check 只检查，update 更新后立即核对。正常退出为 0，过时统计或项目错误为 1，启动失败为 2。

Windows：

powershell.exe -NoProfile -ExecutionPolicy Bypass -File tools/wordcount.ps1 -Mode sync
powershell.exe -NoProfile -ExecutionPolicy Bypass -File tools/wordcount.ps1 -Mode check

Mac：

osascript -l JavaScript tools/wordcount-mac.js sync "$PWD" "$PWD/tools" --plain
osascript -l JavaScript tools/wordcount-mac.js check "$PWD" "$PWD/tools" --plain

实现：Windows 原生程序（本地文件：wordcount.ps1）、Mac 系统接口（本地文件：wordcount-mac.js）、Mac 统计核心（本地文件：wordcount-core.js）。两端共用报告格式（本地文件：wordcount-format.json）与口径测试样例（本地文件：wordcount-cases.json）。调整计数规则时必须同步两端并运行回归检查，不可仅改一端。

powershell.exe -NoProfile -ExecutionPolicy Bypass -File tools/test_wordcount.ps1

osascript -l JavaScript tools/test_wordcount-mac.js "$PWD/tools"

验证范围：Windows 的实际文件读写、只读保护、并发检测和入口已实测；Mac 统计核心已验证样例和当前项目输出一致，系统文件接口仍需在 Mac 真机运行验证。

小说资料库

探索

README