Releases: modoojunko/awesome-novel-agent
Release list
v4.12.3
v4.12.3 版本说明
关键词： Python 版本门槛、安装阶段 fail-fast、3.9 兼容
一句话
Python 版本问题从"执行时报错"提前到"安装时报错"：新增 tools/check-python.py 版本门槛，install.sh / install.ps1 在创建/删除任何文件前先检查解释器版本；同时修复 sync-project.py 在 Python 3.9 下 import 即 TypeError 的意外依赖（补 from __future__ import annotations），3.9 用户无需升级即可运行。
这版做了什么
| 改动 | 说明 |
|---|---|
版本门槛脚本（tools/check-python.py） |
新增独立检查脚本（默认要求 Python 3.9+，--min 供测试覆盖），版本不满足时输出明确的升级提示 |
安装 fail-fast（install.sh / install.ps1） |
两个安装脚本在任何目录创建/删除前先运行版本检查，不满足立即中止；install.sh 支持 NOVEL_PYTHON 指定解释器（如 Homebrew 的 python3.12） |
3.9 兼容修复（tools/sync-project.py） |
补上与 platforms.py 一致的 from __future__ import annotations，str | None 注解在 Python 3.9 下不再 import 即抛 TypeError |
| 文档（README / README-en） | 前置要求补充 "Python 3.9+（推荐 3.11+）"，说明安装脚本会先检查版本 |
| 回归测试 | test_platforms.py 新增版本门槛单元用例与"版本不满足时 install.sh 不创建任何目录"负向 E2E |
兼容性
无平台行为变化（claude / opencode / reasonix / codex 产物不变）。macOS 系统自带 Python 3.9.6 已验证 init / sync / --check 全通过；安装门槛仅对 <3.9 的解释器生效。已安装旧版 skill 的用户需要重跑 install.sh（tools/ 不参与项目级同步）才能拿到修复后的脚本。
验证方法
- Python 3.9.6：
init.py/sync-project.py/sync-project.py --check全通过（修复前 import 即 TypeError） python tools/test_platforms.py：100/100 通过install.sh用系统 Python 3.9.6 安装成功；NOVEL_PYTHON=/bin/false模拟版本不满足时在创建目标目录前中止
v4.12.2
v4.12.2 版本说明
关键词： Codex 调度安全、子 agent 越权防护、递归自派拦截
一句话
修复 Codex 平台多 agent 调度的失控问题：子 agent 不再能越权推进流水线或递归派生自己。所有子 agent 的 Codex TOML 注入「调度权限硬约束」（禁止 spawn_agent、禁止写非本 order 文件、禁止写 phase 字段），项目 AGENTS.md 声明 novel-agent 为唯一调度者。
这版做了什么
| 改动 | 说明 |
|---|---|
调度硬约束注入（tools/platforms.py） |
convert_to_codex 为所有子 agent 在 developer_instructions 顶部注入「调度权限硬约束」：禁止 spawn_agent（含同名递归派生）、禁止写 .agent/task/ 非本 order 文件、禁止写 status.md 的 phase / current_step / last_volume_completed；工具范围声明改为提示性文本（Codex TOML 无工具白名单字段，文本级防线） |
| 源 agent 边界 | volume-planner 源文件 OOS 补「不调度其他 agent，不派生子 agent」；updater OOS 补「不写 status.md 的 phase 等字段」 |
顶层调度规则（templates/AGENTS.codex.md） |
新项目 AGENTS.md 增加「调度边界（最高优先级）」：novel-agent 是唯一调度者，子 agent 禁止再派生（含同名递归） |
| 回归测试 | test_platforms.py 新增 3 个红绿用例（子 agent 注入硬约束、novel-agent 不注入、AGENTS.md 唯一调度者规则） |
兼容性
仅影响 Codex 平台生成的 agent 指令与项目 AGENTS.md 模板；claude / opencode / reasonix 平台产物无行为变化（源文件 OOS 增补为纯文本强化）。已有 Codex 项目执行 sync-project.py --platform codex 后 TOML 生效；AGENTS.md 调度边界段需重新 init 或手动补充。
验证方法
python tools/test_platforms.py：94/94 通过python -m py_compile tools/*.py、check-agents.py、check-conflicts.py通过- 四平台重新 init：Codex 产物含硬约束，claude / opencode / reasonix 无 spawn_agent / 调度边界泄漏
v4.12.1 — agent 驱动安装 + /awesome-novel 统一入口
v4.12.1 版本说明
关键词： 安装体验、agent 驱动安装、/awesome-novel 统一入口
一句话
安装不再让用户复制粘贴命令：对 AI 说「帮我安装 awesome-novel-skill」，AI 自己运行 install.sh <平台> 安装本体；之后在小说目录输入 /awesome-novel（Codex 用 /use awesome-novel）即可在本地初始化小说工作空间。
这版做了什么
| 改动 | 说明 |
|---|---|
| agent 驱动安装 | README（中/英）、landing page、tutorial 的安装方式从「用户复制粘贴」改为「对 AI 说一句话，AI 自动运行 ./install.sh <平台> / install.ps1 <平台>」 |
| 统一入口命令 | 安装完成后在小说目录输入 /awesome-novel 自动初始化（Codex 为 /use awesome-novel）；SKILL.md 检测流程与 init.py / sync-project.py 调用改为 skill 安装目录绝对路径 |
| 文档一致性修复 | Reasonix 入口统一为 @novel-agent（项目级部署的入口 skill 名为 novel-agent）；README-en / tutorial agent 数量统一为 8（含 anti-ai）；tutorial 平台表补齐 OpenCode / Codex / Reasonix，并补 Windows install.ps1 与 install.sh 兼容平台脚注 |
| 版本信息对齐 | tutorial 手册版本对齐 v4.12.0+ |
兼容性
纯文档改动，无代码行为变化；四平台安装 / 初始化流程不变。
验证方法
- 纯文档 / HTML 改动，无 Python 逻辑变更
- CI：lint（py_compile、check-agents、check-conflicts、test_platforms）通过
- Markdown 代码块围栏配对、HTML 标签目检通过
v4.12.0 — Codex 平台支持
v4.12.0 版本说明
关键词： Codex 平台支持、四平台适配、安装/检视修复、landing page
一句话
新增 Codex 平台支持，与 Claude Code / OpenCode / Reasonix 并列成为第四平台：skill 用户级安装到 ~/.codex/skills/awesome-novel/，初始化时把 8 个自定义 agent 以 Codex 官方 TOML 部署到项目 .codex/agents/，novel-agent 用 spawn_agent 调度子 agent。
这版做了什么
| 改动 | 说明 |
|---|---|
平台适配层（tools/platforms.py） |
新增 codex 平台条目；convert_to_codex() 把 8 个 Claude agent frontmatter 转换为 Codex 官方 TOML（name/description/developer_instructions），SOP 内联、Agent→spawn_agent、.claude/ 引用改写；ensure_yaml() 依赖预检 |
| 初始化/同步 | init.py --platform codex 项目级部署 .codex/agents/*.toml + .codex/skills/（memory-recording、roleplay-sandbox）+ knowledge/memory；生成 Codex 版 AGENTS.md；sync-project.py 按源指纹重新生成派生产物 |
| 安装 | install.sh codex / install.ps1 codex 装到用户级 ~/.codex/skills/awesome-novel/；修复全新 HOME 首次安装被安全校验误拒（F1） |
| 检视修复 | rewrite_refs 清除部署产物裸 .claude/ 残留（F2）；memory-format-spec.md 改平台无关表述（F3）；CI 增加平台测试步骤（F4）；缺 pyyaml 时明确报错而非静默产出损坏 TOML（F5）；install.sh 先校验后建目录、codex 检测改 .codex 路径段匹配 |
| 文档与 landing page | README（中/英）、SKILL.md、ARCHITECTURE.md、skill.json、根 AGENTS.md、平台适配 spec 同步；index.html 补充 Codex/OpenCode/Reasonix 安装说明 |
| CI | test_platforms.py 纳入检查；pull_request 触发；Pages 部署仅限 main 推送 |
验证方法
tools/test_platforms.py：90/90 通过（四平台回归 + codex 单元/E2E/负向用例 + F1/P2/P3 回归）py_compile、check-agents.py、check-conflicts.py、bash -n install.sh全过- Codex 实测 demo：init → 设定 → 卷纲 → 章纲 → 提示词 → 正文 → 去 AI 味 → 归档，第一章完成
兼容性保证
- 新增平台不改变既有三平台行为；四平台共享同一套写作流程与知识库
opencode/reasonix/codex的 agent 转换需要 pyyaml（tools/requirements.txt已声明，CI 自动安装；缺失时 init/sync 明确报错）
v4.11.1 — README 更新（QQ 交流群 + 三平台文档对齐）
v4.11.1 版本说明
关键词： README 更新、QQ 交流群、三平台文档对齐
一句话
README 对外口径与 v4.11.0 的平台适配层对齐：文档不再只写 Claude Code / OpenCode，补上 Reasonix 的安装和集成说明；顶部新增 QQ 交流群入口。
这版做了什么
v4.11.0 代码里已经支持 Claude Code / OpenCode / Reasonix 三平台纯原生部署，但 README 还停留在「Claude Code / OpenCode」两个平台的口径，Reasonix 用户照文档装不起来。这版纯文档改动，把 README 对齐到实际能力。
| 改动 | 说明 |
|---|---|
| QQ 交流群入口 | README 顶部徽章 + 开篇「加入交流群」区块，群号 1006050538（2群） |
| 三平台文档对齐 | 标题、徽章、你需要什么、安装、项目结构树、FAQ 全部补齐 Reasonix；新增「Reasonix 集成」章节（项目级 .reasonix/skills/ 部署、init.py --platform reasonix、reasonix code 开始写作、sync 升级） |
| 项目结构说明 | 结构树改为 .claude/ / .opencode/ / .reasonix/ 三选一并列，注明实际只生成一套 |
| README-en.md 同步 | 英文版平台部分（标题、徽章、What You Need、Installation）同步补 OpenCode 和 Reasonix |
兼容性
纯文档改动，无代码行为变化。
验证方法
tools/test_platforms.py：52 项断言全部通过（平台适配层回归）
v4.11.0 — 平台适配层：三平台纯原生部署
v4.11.0 版本说明
关键词： 平台适配层、三平台纯原生部署、Reasonix 完善
一句话
把部署层做成平台感知：Claude Code / OpenCode / Reasonix 三个 coding agent 各有自己的 agent/skill/knowledge/memory 目录约定，init.py 和 sync-project.py 现在按平台部署，非 Claude 平台不再产生 .claude/。 Reasonix 项目从"skills 在 .reasonix、知识却割裂在 .claude"的状态，变成全部落在 .reasonix/ 下。
这版做了什么
上一版加入了 Reasonix（DeepSeek 前缀缓存优化）支持，但只把 10 个 SKILL.md 部署到 .reasonix/skills/，knowledge/memory/agents 仍硬编码进 .claude/——Reasonix 用户初始化后看到一半框架在 .reasonix/、一半在 .claude/，像部署错了地方。根因是：不同 coding agent 对 agent/skill/knowledge/memory 的目录约定不同，部署脚本没有做平台适配。
这版引入共享平台适配层 tools/platforms.py，把部署全部改成平台感知。
具体改了什么
| 改动 | 说明 |
|---|---|
平台适配层 tools/platforms.py |
新共享模块：平台配置表（claude→.claude/、opencode→.opencode/、reasonix→.reasonix/）+ 平台检测 + 引用改写 + reasonix skill 生成。加新平台只加一行配置 |
| init.py 纯原生部署 | 新增 --platform claude|opencode|reasonix（NOVEL_PLATFORM 环境变量 / SKILL_HOME 路径识别兜底）；reasonix/opencode 初始化不再产生 .claude/；reasonix 不部署 agents（10 个 SKILL.md 即 agents） |
| sync-project.py 平台感知 | 同步目标目录按平台走；reasonix 的 10 个 SKILL.md 是转换产物，同步时重新生成而非字节拷贝（变更检测靠源指纹） |
| 引用改写 | 部署内容里的 .claude/knowledge/、.claude/memory/ 引用按平台改写（如 reasonix → .reasonix/knowledge/）；项目模板 CLAUDE.md/AGENTS.md、永久记忆占位一并改写 |
| opencode 一致性 | opencode agent 的 frontmatter 转换（tools: → permission:）收进共享模块，init 和 sync 行为一致，sync 不再把转换结果回退成 Claude 格式 |
回归验证 tools/test_platforms.py |
52 项断言：三平台布局、引用改写、reasonix 10 个 skill、sync 一致性、claude 字节保真 |
验证方法
平台适配是部署逻辑重构，最大的风险是改坏 Claude Code 的现有输出。验证刻意覆盖了三层：
- 三平台 E2E——
test_platforms.py分别 init claude/opencode/reasonix 到临时目录，断言目录布局（该有的有、不该有的没有）+ 引用改写正确 - claude 字节保真——claude 平台 init 产物与改动前逐字节 diff 一致（唯一区别：不再生成多余的
.reasonix/） - 静态回归——check-agents / check-conflicts 通过；
--platform非法值/缺值友好报错而非裸 traceback
兼容性保证
- ✅ 全新项目：
python tools/init.py <path> --genre <N> --platform <claude|opencode|reasonix>，平台不指定也能靠 SKILL_HOME 路径识别兜底（默认 claude） - ✅ 既有 Claude Code 项目：升级后行为不变（默认 claude 平台，输出逐字节一致）
⚠️ 已有 Reasonix 项目（v4.10 初始化）：knowledge/memory 仍留在旧.claude/，需重跑新 init（--platform reasonix）补.reasonix/knowledge|memory，手动删.claude/即完成纯原生迁移
适合视频呈现的亮点
-
"部署层抽象"的工程范式 — 三平台目录约定抽象成配置表 + 检测 + 引用改写，加平台只加一行；"部署时转换、源文件保持 Claude Code 格式不动"的取舍贯穿始终。
-
纯原生 vs 兼容的取舍 — 明确选择"非 Claude 平台不再产生
.claude/"，换取目录干净；为此入口检查（"确认平台部署目录已生成"）、项目模板、永久记忆全部平台化。 -
回归先行的纪律 — 先写 52 项断言的验证脚本（红），再实现（绿）；三平台每个都验"该有的有、不该有的没有"，claude 逐字节保真。
v4.10.0 — #81 用户反馈全案修复 + Reasonix 支持
v4.10.0
围绕 GitHub issue #81 的真实用户反馈（8 条按严重性排列），系统性修复"写了很多设计但没起作用"的痛点。
核心改动
反AI规则源头治理 — 破折号改用法判定（few-shot 正反例）；统一 5 组跨文件冲突阈值；职责声明烙进文件；新增 check-conflicts.py CI 拦截
Prompt 门禁 — prompt-audit 新增维度 H（规则去重）+ I（优先级重排），FAIL 打回
断点续跑 — 写新章节 7 步全支持；章节状态当断点源（省 token）；writer partial 草稿续写不重头
章节回滚 — 重写某章时撤销该章归档追加（timeline/foreshadowing/角色状态）；作者说"重写第X章"即触发
记忆闭环 — 作者偏好注入 prompt；updater diff 提取改始终执行
知识部署断链修复 — sync-project.py 平铺 format-specs，写作基底等 7 个核心文件恢复加载
附带能力
Reasonix 支持 — init.py 项目级部署 .reasonix/skills/（10 个 SKILL.md），DeepSeek 前缀缓存优化（治成本痛点）
工程方法
每轮修复都经提示词工程师验证→修复→再验证（断点续跑三轮、反AI规则两轮），真实项目数据副本演练回滚。
版本说明：docs/releasenote-4.10.0.md
v4.9.0 — 多 agent 架构修复
一句话
这版把"文档里架构完整、机制里一半没落地"的问题一次性补齐了——多 agent 协作从"靠模型自觉"变成"靠机制保证"。
核心改动
| 改动 | 说明 |
|---|---|
| 完成信号机制化 | order 文件从"删除 = 完成"改为"标记 status: DONE = 完成"，调度死锁根除 |
| 权限白名单落地 | 8 个 agent 加 tools: 白名单，权限变机制；check-agents.py CI 校验 |
| 归档重写 | 定稿改 Write 生成 + 中间稿保留；归档全程幂等（查重 + checkpoint），重派不重复 |
| 状态机补全 | 卷完成判定归 novel-agent（数字裁决）；新增 finished 完本终态 |
| 数据生命周期 | foreshadowing 台账全生命周期、reader 评审沉淀、设定变更通知消费闭环 |
修复过程
三轮审计闭环：架构师审计（S1-S6 + M1-M5）→ 工作流梳理（G1-G14）→ 两轮 code review（+NG1-NG7 + review 修复）。每批配真实测试：静态检查 + 沙盒模拟归档 + 权限矩阵验证。
兼容性
- ✅ 全新项目 init.py 自动带出全部新机制
- ✅ 既有项目 sync-project.py 同步 + 台账缺失兜底创建
⚠️ 历史项目的旧格式 order 文件与新协议不兼容，升级前建议清理.agent/task/残留
完整版本说明见 docs/releasenote-4.9.0.md。
v4.8.4 — OpenCode 平台支持
✨ OpenCode 平台支持
本版本新增对 OpenCode（第三方开源 AI 编码 CLI）的支持。
变更清单
- tools/init.py — 根据 SKILL_HOME 路径自动检测平台，agent 定义部署到对应目录（
.opencode/agents/或.claude/agents/） - tools/sync-project.py — 同步路径随平台自动切换
- templates/AGENTS.md — 新增 OpenCode 项目模板
- SKILL.md / README.md — 新增 OpenCode 集成说明
- install.ps1 / install.sh — 新增
opencode平台安装选项
使用方式
安装到: /c/Users/modoo/.config/opencode/skills/awesome-novel
已更新 NOVEL_SKILL_HOME=/c/Users/modoo/.config/opencode/skills/awesome-novel 到 /c/Users/modoo/.profile
已更新 NOVEL_SKILL_HOME=/c/Users/modoo/.config/opencode/skills/awesome-novel 到 /c/Users/modoo/.bashrc
错误：安装目标路径异常 (/c/Users/modoo/.config/opencode/skills/awesome-novel)，中止。
兼容性
- ✅ Claude Code 用户不受影响，
.claude/agents/路径不变 - ✅ OpenCode 与 Claude Code 是「或」关系——装哪个平台就用哪个路径
- ✅ 两种平台共享同一套写作流程和知识库
完整改动： #78