v1.2.1：运行时契约修复与数据投影支持

更新摘要

本版本聚焦运行时契约、审查结果可信度、导出质量，以及章节提交后的数据投影。

修复

• review-pipeline 正确读取 --review-results 指向的 JSON 文件；文件缺失、损坏或 reviewer 标记为 incomplete 时保持 unverified。
• doctor 在发现问题或找不到项目时返回非零退出码，JSON 输出可直接用于 CI。
• init-contract 变为幂等；只有底本内容发生变化时才递增版本号。
• export 去除常见 Markdown 展示标记，避免标题、列表和链接语法进入纯文本导出。

新增

• chapter-commit --data-artifacts 记录 data-agent 提供的三份 JSON artifact。
• projections status|retry|replay --chapter N 重建摘要投影并写入 projection_log.jsonl；未实现的宿主专属投影明确标记为 skipped。
• fiction-review 内置 review schema、通用 rubric、爽点/多线检查和阻断覆盖规则，并支持 reviewer 不可用时的 solo fallback。
• 扫榜文档明确 browser-cdp 为外部可选依赖，并要求标记非实时数据来源。

验证

• 32 个 Python 测试通过。
• 15 个 skill 的格式检查通过。
• 编码检查：117 个文件通过，0 个异常。
• fiction-scan 的 8 个 JavaScript 文件语法检查通过。

升级

git pull origin main

也可以固定使用本版本：

git checkout v1.2.1

v1.2.0: P2/P3 完善 — 测试套件 + LICENSE + CHANGELOG + pre-commit + 文件拆分

v1.2.0: P2/P3 完善 — 测试套件 + LICENSE + CHANGELOG + pre-commit + 文件拆分

🆕 新增

1. pytest 测试套件

新增 tests/test_fiction.py，15 个测试用例覆盖核心功能：

• test_init_creates_state_with_schema_version — init 写入 schema_version
• test_where_finds_project / test_where_exits_nonzero_when_no_project — where 命令
• test_migrate_state_old_format / test_migrate_state_idempotent — schema 迁移
• test_load_state_auto_migrates_and_persists — 自动迁移+持久化
• test_doctor_reports_missing_files — doctor 体检
• test_export_txt / test_export_fanqie_format — 导出
• test_chapter_commit — 章节提交
• test_review_pipeline_writes_report — 审查报告
• test_memory_add_and_list / test_memory_dedup / test_memory_search_and_delete — project-memory
• test_cli_help_registered — CLI 参数注册

运行方式：

# 用 pytest
python -m pytest tests/ -v

# 或内置 runner（无需安装 pytest）
python tests/test_fiction.py --run

防止再次出现"参数没注册"这种低级问题。

2. LICENSE 文件

补齐 MIT LICENSE（README 早已声明 MIT 但仓库根缺失）：

• 版权年份 2024-2026
• 版权人 qingyabailu-git

3. CHANGELOG.md

参考 Keep a Changelog 格式，记录 v1.0.0 到 v1.1.0 的主要变更，方便用户了解升级影响。

4. pre-commit hook（编码保护）

从源头杜绝乱码文件被提交，两种安装方式：

方式一：Git 原生 hook

cp scripts/pre-commit-hook.sh .git/hooks/pre-commit
chmod +x .git/hooks/pre-commit

方式二：pre-commit 框架（需 pip install pre-commit）

pre-commit install

hook 会检查暂存的 .md/.py/.json/.yaml/.yml 文件是否为干净 UTF-8（无 BOM、无乱码特征），不合格则阻止提交。

🔧 重构

5. 拆分 fiction-write/SKILL.md

章节修改模式（Re-craft/Rewrite）的详细六步流程拆分到独立文件：

• skills/fiction-write/references/revise-modes.md（100 行，含完整流程）
• skills/fiction-write/SKILL.md 从 429 行减到 340 行，保留速查表和引用链接

主 SKILL.md 加载更轻量，进入修改模式时才加载详细流程。

6. agents 编排描述对齐

Deep 模式增量章节明确标注 context-agent / data-agent / reviewer / projection / postcommit gate 均由主线 LLM 直接执行，scripts/fiction.py 仅提供 chapter-commit 和 review-pipeline 辅助脚本支持。消除"描述与实现脱节"的疑虑。

7. cmd_memory 扩展子命令

project-memory 命令新增三个子命令：

子命令	功能
list-patterns	列出所有已存模式
search-pattern	按关键词或类型搜索
delete-pattern	按索引或类型删除

add-pattern 同时增加去重逻辑（pattern_type + description 完全相同则跳过）。

8. Windows 兼容性说明

README 新增"Windows 用户注意"段落，明确说明 SKILL.md 使用 bash 语法，Windows 用户需 Git Bash / WSL / MSYS2 / Cygwin，PowerShell 和 CMD 无法直接运行。

📊 变更统计

• 9 文件变更
• +712 行 / -106 行
• 新增 6 文件（LICENSE, CHANGELOG.md, .pre-commit-config.yaml, scripts/pre-commit-hook.sh, skills/fiction-write/references/revise-modes.md, tests/test_fiction.py）

✅ 验证

# 1. 测试套件
python tests/test_fiction.py --run
# 期望: 15 passed, 0 failed

# 2. 编码检测
python scripts/check_encoding.py .
# 期望: 110+ OK, 0 BAD

# 3. CLI 新子命令
python scripts/fiction.py project-memory --help
# 应显示 add-pattern / list-patterns / search-pattern / delete-pattern

⬆️ 升级方法

git pull origin main
# 或指定版本
git checkout v1.2.0

从 v1.1.0 升级无破坏性变更，所有功能向后兼容。

📝 后续

P0/P1/P2/P3 全部完成。本项目当前状态：

阶段	内容	状态
P0	紧急修复（乱码+参数+退出码）	✅ v1.0.3
P1	schema 版本化+环境变量兼容+致谢规范化	✅ v1.1.0
P2	文件拆分+agents对齐+cmd_memory扩展+LICENSE+Windows说明	✅ v1.2.0
P3	测试套件+pre-commit hook+CHANGELOG	✅ v1.2.0

后续如有新需求可继续迭代。

---

完整变更: v1.1.0...v1.2.0

v1.1.0: P1 完善 — schema 版本化 + 环境变量兼容 + 致谢规范化

v1.1.0: P1 完善 — schema 版本化 + 环境变量兼容 + 致谢规范化

🆕 新功能

1. state.json schema 版本化与自动迁移
   旧项目打开时自动迁移到新 schema，无需手动处理：

新增 SCHEMA_VERSION = 1 常量和 migrate_state() 函数
init_project 写入 schema_version: 1 字段
load_state 自动检测旧版（project_info 字段）迁移到 project，并持久化迁移结果
migrate_state 返回 (state, changed) 元组，幂等可重复调用
cmd_status / cmd_contract 不再依赖 project_info fallback
迁移示例：

2. 环境变量双前缀兼容（CODEX_ + CLAUDE_）
   本工具现在同时兼容 Codex 和 Claude Code 两种环境：

8 个 SKILL.md: $PWD → ${CLAUDE_PROJECT_DIR:-$PWD}
fiction-doctor: CLAUDE_PLUGIN_ROOT → CODEX_PLUGIN_ROOT 优先 fallback 到 CLAUDE_PLUGIN_ROOT
README 新增"环境变量兼容性"说明段落
用户无需任何额外配置，无论用 Codex 还是 Claude Code 都能正常工作。

🔧 重构
3. metadata.openclaw.sources 迁移到致谢章节
14 个 SKILL.md 从 frontmatter 移除非标准 metadata.openclaw.sources 字段（Codex/WorkBuddy skill 不识别此字段），改为在每个文件末尾添加 ## 致谢 章节列出来源仓库：

markdown

致谢

本 skill 的开发参考了以下开源项目的思路与实现：

• lingfengQAQ/webnovel-writer
• worldwonderer/oh-story-claudecode
  符合 Codex/WorkBuddy skill 标准字段规范，frontmatter 只保留 name 和 description。

4. yaml 描述与 SKILL.md 同步
   fiction-write/agents/openai.yaml: 描述更新为含修改模式（"写作 Normal/Deep 双模式 + 修改 Re-craft/Rewrite 双模式"）
   fiction-start/SKILL.md: 旧 fiction-revise 引用改为 fiction-write 内建变更传播流程
   fiction-write/SKILL.md: 移除旧的 fiction-revise 变更传播引用
   📊 变更统计
   17 文件变更
   +201 行 / -104 行
   涉及 14 个 SKILL.md + 1 个 yaml + fiction.py + README.md
   ⬆️ 升级方法
   bash
   git pull origin main

或指定版本

git checkout v1.1.0
从 v1.0.3 升级无破坏性变更：

旧 state.json 会自动迁移（幂等，可重复打开）
环境变量原 CLAUDE_* 仍可用，新增 CODEX_* 优先级更高
所有 skill 行为保持兼容
🔍 验证方法
bash

1. 编码检测

python scripts/check_encoding.py .

期望: 105+ OK, 0 BAD

2. CLI 参数

python scripts/fiction.py doctor --help # 应显示 --chapter/--deep
python scripts/fiction.py export --help # 应显示 --format/--output

3. schema 迁移测试（新建项目检查 schema_version）

python scripts/fiction.py init --title test --author me --genre urban /tmp/test
cat /tmp/test/.novel/state.json # 应含 "schema_version": 1
📝 后续待办（P2/P3，非阻塞）
fiction-write/SKILL.md 拆分（当前 16KB 偏大）
agents 编排描述（reviewer/context/data-agent）与脚本实现对齐
cmd_memory 加 list/search/delete 子命令
LICENSE 文件
pytest 测试用例
pre-commit hook
CHANGELOG
完整变更: v1.0.3...v1.1.0

v1.0.3: 紧急修复 — 全部 SKILL.md/yaml 乱码 + fiction.py P0 问题 + 编码保护

v1.0.3: 紧急修复 — 全部 SKILL.md/yaml 乱码 + fiction.py P0 问题 + 编码保护

⚠️ 紧急修复版本

v1.0.2 标榜修复 UTF-8 编码，但实际未修干净——所有 15 个 SKILL.md 和 15 个 agents/openai.yaml 仍是 GBK 污染乱码，导致 AI 加载后无法理解能力边界，skill 实际不可用。本版本彻底修复。

🔧 修复内容

1. 乱码修复（P0）

从最早干净的 commit 4ef33fa 恢复所有中文内容：

• ✅ 15 个 SKILL.md 恢复干净 UTF-8（fiction、fiction-write、fiction-analyze 等）
• ✅ 15 个 agents/openai.yaml 恢复干净 UTF-8
• ✅ scripts/reference_search.py 去除 UTF-8 BOM
• ✅ 全项目 105 个文本文件编码检测通过

2. fiction.py P0 脚本问题修复

问题 | 修复前 | 修复后 -- | -- | -- cmd_where 失败退出码 | 0（错误被掩盖） | 1（错误走 stderr） cmd_export 参数 | 缺 --format/--output | 支持 --format {txt,docx,fanqie} --output（含番茄平台格式化） cmd_doctor 参数 | 缺 --chapter/--deep | 支持 --chapter N --deep cmd_review list 类型 | 不处理 | 完整支持

3. fiction-revise 路由同步

• fiction/SKILL.md 路由表：fiction-revise → fiction-write（内建修改模式）
• fiction-write/SKILL.md 新增"章节修改模式（内建）"章节
  • Re-craft 模式：大改，自动传播影响范围
  • Rewrite 模式：重写，全链路刷新
  • Polish 模式：转交 fiction-polish

4. README 同步

• 完整写作流程图：revise → write（修改模式）
• 三种修改强度表增加"调用方式"列
• fiction-write 描述补充修改职责
• 快速上手增加"修改第5章"示例

v1.0.2-修复问题

重构

• 将 fiction-revise（章节修改）合并到 fiction-write（正文写作），作为内置的三种修改模式：Polish（润色微调）/ Re-craft（重铸段落）/ Rewrite（重写章节），不再作为独立 skill 存在

增强

• 为 7 个 skill 新增"写作视角""工作流清晰度""跨 skill 协作"说明段落，覆盖：fiction-analyze fiction-conceive fiction-export fiction-learn fiction-query fiction-review fiction-scan

修复

• 修复审查报告指出的多项问题：UTF-8 编码规范、fiction-doctor 体检逻辑、fiction-review 审查集成、恢复 fiction-polish 润色路由、安装引导文案优化
• 为 fiction-learn 和 fiction-export 补充写作视角说明

v1.0.1-修复与优化

web-fiction v1.0.1 — 修复与优化

用 AI 帮你写网文的工具包，从构思到完本一条龙。

技能列表

技能	它能干什么
fiction	主入口，自动找到对应功能
fiction-conceive	和 AI 一起琢磨故事点子、设计角色
fiction-setup	自动建好项目文件夹
fiction-start	开写前检查准备，锁定故事设定
fiction-scan	看平台上什么类型最火
fiction-analyze	拆解爆款，学人家的结构和写法
fiction-plan	规划每卷节奏和每章大纲
fiction-write	写正文（自动判断用普通还是深度模式）
fiction-revise	三档修改：小改文字 / 大改剧情 / 全部重写
fiction-review	帮你看写得怎么样
fiction-polish	让文字更自然，去掉 AI 味
fiction-query	查角色叫什么、设定是什么、伏笔在哪
fiction-learn	把好写法存下来以后继续用
fiction-doctor	检查项目文件有没有缺失
fiction-export	写完导出全文
fiction-import	把以前写的小说导入进来

安装

下载项目后对 Codex 说：「请把我项目里 skills/ 目录下的技能安装到 Codex」

我不懂编程，这个 skill 是用 Codex 接入 DeepSeek 写的。

v1.0.1 更新内容

• 全篇阅读体验优化：去术语化，零基础也能看懂
• 修复 root() 函数跨项目污染
• 修复 Polish 模式职责重叠
• 修复 README 中的虚假声明
• 新增 reference_search.py 参考库搜索脚本
• 修了些问题

v1.0.0 — 初始发布

web-fiction v1.0.0

用 AI 帮你写网文的工具包，从构思到完本一条龙。

面向番茄小说等免费阅读平台。核心思路：先想好每章要让读者有什么感受，再动笔写。

技能列表

技能	它能干什么
fiction	主入口，自动帮你找到对应的功能
fiction-conceive	和 AI 一起琢磨故事点子、设计角色、确定文风
fiction-setup	自动建好写小说需要的文件夹结构
fiction-start	正式开写前检查准备是否充分，锁定故事设定
fiction-scan	看看平台上现在什么类型最火
fiction-analyze	分析热门小说是怎么写的，学人家的结构和技巧
fiction-plan	规划每一卷的节奏、时间线和每章的大纲
fiction-write	写正文（系统自动判断用普通写还是深度写）
fiction-revise	修改章节（小改文字/大改剧情/全部重写）
fiction-review	帮你看写得怎么样（可以看一章、多章或整卷）
fiction-polish	让文字更自然，去掉 AI 味
fiction-query	问系统角色叫什么、设定是什么、前面埋了什么伏笔
fiction-learn	把写得好的写法存下来，以后继续用
fiction-doctor	检查项目有没有文件缺失、设定是否完整
fiction-export	写完后导出全文，归档保存
fiction-import	把以前写的小说导入到这套工具里

安装

把这个项目下载到电脑上，然后对 Codex 说：

「请把我项目里 skills/ 目录下的技能安装到 Codex」

AI 会自动完成安装。