中文长剧本工坊 mudden2380078550-creator/write-chinese-long-screenplay

Narrative Harness 0.4.0

面向中文小说与剧本的本地创作控制工具。AI 负责理解与创作，本程序保存作品状态、构建上下文、检查候选，并共同提交正文与状态。保留 write-chinese-long-screenplay 作为 Codex Skill 入口。

工具源码、安装副本和作品目录彼此独立。本项目不会自动调用模型、同步云端或发布作品。

使用

本项目自 v0.4.0 起采用本布局，main 即当前版本；旧版布局以 legacy/ 形式保留在仓库内，历史 Release 与 tag 不受影响。下载请使用 v0.4.0 Release，或直接克隆 main：

git clone https://github.com/mudden2380078550-creator/write-chinese-long-screenplay.git narrative-harness
cd narrative-harness

需要 Python 3.10+。源码直接运行，无第三方运行依赖：

python scripts/harness.py project new --root ../my-book --title 我的小说 --format novel
python scripts/harness.py import stage --project ../my-book --source ../资料包.md

之后让 AI 读取归档资料，填写 proposals/.json 中的实体、政策和章节大纲，再执行 import apply。用户不必手填 JSON；格式由宿主 AI 处理。程序只做可靠归档，不假装能独立理解自由文本。

安装为命令：

python -m pip install .
harness --help

安装到 Codex（destination 使用你自己的 Skill 目录）：

python scripts/install_skill.py --destination <skills目录>/write-chinese-long-screenplay --backup-root <备份目录>

安装器先验证独立启动器，再备份已有目录，复制修订后的兼容脚本、Skill 及核心运行包。备份路径在输出 JSON 里。安装副本能移动到另一台有 Python 的设备，不引用本机源码路径。

不要再把整个工具仓库直接复制到 skills 目录。 请运行上面的安装器。安装后可以对 AI 说：“使用 write-chinese-long-screenplay，新建一本系统流小说，项目放在工具目录之外；这是资料包，请整理人物、技能、作者控制和大纲，列出仍需我确认的问题。” AI 负责填提案，未解决的关键问题仍需审定，不能保证任意宿主都会正确执行。

升级前备份作品和旧 Skill。v2 作品使用 project migrate --help 查看复制迁移入口，审定迁移报告后再续写，不直接覆盖旧作品。内部开发版 0.3.0 的锁文件与 0.4.0 不同，保留原工具处理旧开发项目；不要手工修改版本锁绕过检查。

工具 Git 仓库只管理工具；每本作品单独建目录、单独选择私有仓库或其他同步方式。本项目没有自动同步功能，同一本作品不要在多个设备同时写入。

完整输入示例见 工作流协议。示范资料见 examples/package.json。

主要命令

| 命令 | 用途 |
| project new/configure/doctor/recover | 创建、作者配置、完整性检查、恢复中断事务 |
| import stage/apply | 原资料归档、接受审定后的结构化资料 |
| unit prepare/submit/check/accept | 准备上下文、提交候选、检查、接受正文与状态 |
| unit revalidate | 按新政策核对既有章节，不重扣资源 |
| state show --before-unit | 查询某章写前状态 |
| revision impact/fork | 影响范围、从写前状态创建独立修订作品 |
| project migrate | 复制迁移旧 v2 项目，保留原始文件与历史未知标记 |
| export | 只导出已接受且无需重新审查的正文 |

每个命令可加 --help。--budget 以字符为单位，不冒充准确 token 数。业务输出为 JSON；0 成功，1 待审/阻断，2 参数/环境错误，3 冲突，4 需恢复。

作品格式与控制

- project.json 是项目清单，harness.lock.json 锁定工具/数据版本。
- canon/entities/ 保存技能、资源、物品、人物等正式实体；canon/policies/ 独立保存作者规则。
- outline/ 保存独立章节任务书，manuscript/ 保存已接受正文。
- canon/history/ 保存初始状态、接受事件及对应候选和检查报告，可重放核对当前状态。
- runs/ 保存本轮上下文、候选与报告，sources/ 保留原件，proposals/ 保存导入提案。
- .harness/ 是本机锁和中断恢复日志，exports/ 是可再生输出。

Skill 不替代程序控制：未审候选、资源不足、过期修订、篡改的报告和未完成事务均不能按正常命令直接接受。普通候选不能修改作者政策。能力消耗由已声明的 uses 应用；物品是否消耗通过明确 state_changes 表达。

历史、迁移与边界

新稿可以查询历史写前状态。最新章可修订而不重复消耗；有后续已接受章节时采用 revision fork，保留原作品。如果历史视图不能满足当前章纲/政策引用，fork 明确拒绝，需先审定修订基础。

旧 v2 迁移保留原件字节并抽取正文。旧 harness 条目先列为未审定，不能将当前数据伪装成旧章节的写前状态。迁移属于有报告的转换，不是自动补全历史。

确定性验证由标准库中的显式字段与领域校验实现；交换协议 Schema 位于 src/narrative_harness/schemas/。不支持任意 JSON Schema 执行。语义检查由宿主 AI 或作者提供有依据的审查记录，程序并不能证明小说的全部语义和文学质量。
第一版支持本地单写者。Windows 用文件字节锁，POSIX 用 flock；中断靠日志恢复。它不提供跨设备分布式锁，也不声称多文件 replace 天然原子。同步前确保 doctor 通过，同步后再检查一次；本轮只在 Windows 实测，跨平台 CI 已配置，但要等仓库跑起来才能说通过。

开发与验证

python -B -m unittest discover -s tests -v
python -B -m unittest discover -s legacy/tests -v

测试覆盖真实命令行、独立安装、状态消耗、政策、上下文预算、历史修订、手改检测、锁、逐文件故障恢复和资料保真。测试里的正文是固定验证样本，不代表模型生成质量评估。

原剧本模板、方法与修订后的 v2 脚本在 legacy/，v2 与 v3 入口不能混用。原 dsh 的根目录插件布局不再是本版本入口，未验证的宿主不能当成即装即用。版本变化见 CHANGELOG.md。项目延续 GPL-3.0-only，完整文本见 LICENSE，来源及修改记录见 NOTICE.md。英文概览见 README_EN.md。