novelcli-df 0.1.0

基于 dark-fantasy-engine 工作流的全功能 AI 玄幻小说创作 CLI

novelcli

基于 dark-fantasy-engine 工作流（Claude Code skill）的全功能 AI 玄幻小说创作 CLI。脱离会话环境，用任意 OpenAI 兼容模型进行工业化逐章创作：章节对齐 → 上下文组装 → 正文生成 → 字数验证 → 六维审查 → 三账回填，全程原子写入、失败零污染。

安装

# PyPI 安装（推荐，需先安装 pipx）
pipx install novelcli-df

# 或从 GitHub 直装
pipx install git+https://github.com/rowani1/novelcli.git@v0.1.0

# 或源码可编辑安装（开发）
git clone https://github.com/rowani1/novelcli.git && cd novelcli
pip install -e .

# 验证
novelcli --version

注：PyPI 包名为 novelcli-df（novelcli 与既有项目 novel-cli 命名过近，被 PyPI 相似度检测保留）， 命令行入口不受影响——安装后敲的始终是 novelcli。 pipx 安装方式：python -m pip install --user pipx && python -m pipx ensurepath

要求 Python ≥ 3.10，Windows / macOS / Linux 均可（全程 UTF-8，兼容中文路径）。

配置

novelcli config init    # 生成 ~/.novelcli/config.toml 带注释模板
novelcli config check   # 对 write / review 两角色做连通性测试
novelcli config show    # 查看配置（API key 掩码显示）

配置示例（~/.novelcli/config.toml）：

[profiles.writer]
base_url = "https://api.deepseek.com"
model = "deepseek-reasoner"
api_key_env = "DEEPSEEK_API_KEY"   # 推荐环境变量；明文 api_key 可用但会警告
temperature = 0.8

[profiles.reviewer]
base_url = "https://open.bigmodel.cn/api/paas/v4"
model = "glm-4.7"
api_key_env = "GLM_API_KEY"
temperature = 0.2                  # 审查低温，可跨模型交叉审查

[roles]
write = "writer"
review = "reviewer"

[defaults]
context_chapters = 5               # 上下文携带最近 N 章
context_budget_chars = 60000       # 上下文字符预算（超预算丢最旧章）
expand_max_rounds = 2              # 字数不足自动扩写上限
critical_max_rounds = 3            # 审查 Critical 修正循环上限

多供应商支持

llm 层只走 OpenAI Chat Completions 协议（model / messages / temperature / max_tokens / stream），任何 OpenAI 兼容端点均可直用——包括 DeepSeek、GLM、Kimi、OpenRouter 及各类聚合网关。Claude 与 Gemini 通过官方兼容层同样支持：

# Claude：Anthropic 官方 OpenAI SDK 兼容层
[profiles.claude]
base_url = "https://api.anthropic.com/v1/"
model = "claude-sonnet-4-6"            # 或 claude-opus-4-7
api_key_env = "ANTHROPIC_API_KEY"
temperature = 0.8

# Gemini：Google 官方 OpenAI 兼容端点
[profiles.gemini]
base_url = "https://generativelanguage.googleapis.com/v1beta/openai/"
model = "gemini-2.5-pro"               # 具体型号以官方文档为准
api_key_env = "GEMINI_API_KEY"
temperature = 0.2

[roles]
write = "claude"      # Claude 写作
review = "gemini"     # Gemini 审查（跨模型交叉审查）

填好后运行 novelcli config check：对 write / review 两角色各发一次最小请求， 失败原因按 认证 / 模型名 / 网络 分类报告。

六命令

命令	用途
novelcli init	新书初始化：交互向导生成 skill 兼容书目录（配置/进度/状态卡/伏笔池/账本/卷纲占位）
novelcli write [N] [-n COUNT] [--yes]	逐章创作：生成 → 实测字数 → 审查 → 三账回填；-n 严格串行连写；--yes 挂机（失败即停，绝不静默降级）
novelcli review <N>	单章重审：只审不改，报告归档 reviews/（vN 递增，禁止覆盖历史）
novelcli status	状态总览 + 三账漂移快检（正文 / 状态卡 / 进度一致性）
novelcli count <N|path>	字数验证：汉字数为唯一口径，与 skill 原脚本逐值一致
novelcli config	全局配置管理（init / show / check）

所有书目录命令支持 --root <路径>，缺省为当前工作目录。

典型流程：

mkdir 雾泽噬渊 && cd 雾泽噬渊
novelcli init                # 向导：书名/字数/账本/风格
# 补全 小说设定.md、状态卡「待填写」项、设定圣经/卷纲总表.md
novelcli write               # 交互创作第 1 章（预览门/采纳门/风险门）
novelcli write -n 5 --yes    # 挂机连写 5 章
novelcli status              # 健康检查

与 dark-fantasy-engine skill 共管

novelcli 的书目录格式与 Claude Code 的 dark-fantasy-engine skill 完全互通：

• init 生成的文件族即 skill 模板结构（project_config / task_progress / 99_当前状态卡 / pending_hooks / particle_ledger / 小说设定 / 设定圣经）；
• 任何时候可以切回 Claude Code + skill 工作流继续同一本书，反之亦然；
• markdown 定点回填：机器只动机器管理的区块，人工手写内容一律保留；
• 三账纪律与 skill 铁律一致：一次创作 = 一个章节号、低于字数下限禁止提交、审查历史禁止覆盖、废稿落 正文/_draft/ 不静默删除。

可靠性设计

• 原子写入：临时文件 + os.replace，任何中断不留半成品正式文件；
• 协议容错：LLM 输出违反协议 → 补齐重发一次 → 仍失败存 _draft/ 报错，三账零变更；
• 防自报成绩：字数一律 CLI 实测，状态卡回填前校验章号；
• 提交原子顺序：正文 → 状态卡 → 伏笔池 → 账本 → 进度（完成标志）→ 快照 → 日志轮转，中断输出已写/未写清单，孤儿章下次启动自动检测。

开发

pip install -e . && pip install pytest
python -m pytest tests/ -q     # 86 个测试：单元 + mock LLM 集成 + CLI e2e

License

Apache-2.0