Webnovel Writer hooks 机制解析session_start 与 guard_runtime_write 如何守护运行面【免费下载链接】webnovel-writer基于 Claude Code 的长篇网文辅助创作系统解决 AI 写作中的「遗忘」和「幻觉」问题支持 200 万字量级 连载创作。项目地址: https://gitcode.com/GitHub_Trending/we/webnovel-writerWebnovel Writer 是基于 Claude Code 的长篇网文辅助创作系统其 hooks 机制由两个轻量脚本组成session_start在每次会话开始时自动播报项目状态guard_runtime_write在写文件前拦截对 Story System 主链数据的危险写入为 200 万字量级连载兜底护航。为什么要给 AI 写作系统加 hooks长篇连载最大的敌人是「遗忘」和「幻觉」AI 会话一刷新就忘了小说写到了第几章更危险的是它可能绕过统一的 runtime 命令直接改写投影数据库和提交文件导致主链数据不一致。Webnovel Writer 的答案是在 Claude Code 的插件运行时上挂两个「门卫」——这就是 hooks 机制hook 是轻量守卫不是业务状态机真正的强保证在 runtime 的 gate 与 commit 入口里实现hook 只负责「开局播报」和「危险动作兜底阻断」。hooks 的注册中心hooks.json所有 hook 都在 hooks.json 中声明结构一目了然触发时机匹配器执行脚本超时SessionStart*所有会话session_start.py5 秒PreToolUseWrite\|Edit\|MultiEditguard_runtime_write.py5 秒PreToolUseBashguard_runtime_write.py5 秒两个注意点体现了工程细节命令统一使用${CLAUDE_PLUGIN_ROOT}占位符定位插件根目录而不是硬编码绝对路径保证插件在任何机器上都能跑每个 hook 都带 5 秒超时——门卫必须快绝不能拖慢正常创作流程。session_start新会话开始先告诉你「写到哪了」session_start.py 解决的是「上下文失忆」问题。它的逻辑非常克制调用webnovel.py project-status --format summary拿到当前项目的短状态阶段、下一步动作把输出裁剪到最多 8 行、1000 字符以内再打印给 Claude任何异常Python 缺失、脚本超时都静默返回 0绝不阻断会话。也就是说每次新开对话、resume 或 compact 之后Claude 会先「看一眼」这本书写到了哪里、下一步该干什么再开始干活。对于动辄上百章的连载这相当于一张自动注入的「剧情进度卡」。guard_runtime_write拦在写入之前的最后一道门guard_runtime_write.py 挂在PreToolUse时机上在 AI 真正执行 Write / Edit / Bash 之前收到一条 JSON 载荷工具名 入参判断是否需要拦截。受保护的路径清单以下运行面文件被硬性保护直接编辑会触发permissionDecision: deny退出码 2.story-system/commits/下的章节 commit 文件.webnovel/index.db关系型索引库.webnovel/vectors.db向量库.webnovel/memory_scratchpad.json.webnovel/projection_log.jsonl拦截后 AI 会收到明确提示请改用webnovel.py的write-gate、chapter-commit或projections retry/replay命令让 commit 与 projection 的不变量保持一致。连 Bash 命令都盯住了光拦文件编辑还不够——AI 完全可能用 shell 重定向写库。因此 guard 对 Bash 命令做了二次识别命令里出现受保护路径 写操作特征、set-content、copy-item等→ 拦截命令里出现chapter_commit.py但没有走webnovel.py入口绕过统一 runtime 的旁路调用→ 拦截但webnovel.py ... projections retry/replay这类官方 runtime 命令会被放行。一个刻意的「不保护」state.json源码里有一条很说明问题的注释state.json 被有意排除在保护清单之外因为审计修复经常需要批量、直接地修正state.json而它本身有独立的备份与重建路径对应 issue #113。这个取舍展示了 hooks 设计的原则守卫为工作流服务而不是反过来卡死工作流。两个「不添乱」的设计哲学通读两个脚本能提炼出贯穿始终的原则原则落地方式Fail-open脚本自身出任何错都返回 0hook 永远不成为创作阻塞点轻量状态播报限制在 8 行 / 1000 字符4 秒内跑完只读、不写文件、不启动服务可关闭两个环境变量随时关掉详见 operations.md 的「Hook 开关」best-effort文档明确声明 Bash 字符串解析不能作为唯一可靠保证强保证仍在 runtime gate 内临时关闭 hook 只需设置环境变量WEBNOVEL_DISABLE_SESSION_STATUS_HOOK1 # 关闭会话状态播报 WEBNOVEL_DISABLE_RUNTIME_GUARD_HOOK1 # 关闭写入守卫如何验证 hook 的行为项目自带一组子进程级测试 test_hooks.py用真实 JSON 载荷驱动 guard 脚本覆盖了关键契约直接写 commit 文件 → 被拦截退出码 2直接写state.json→ 放行跑projections retryruntime 命令 → 放行绕过webnovel.py直接调chapter_commit.py→ 被拦截设计意图的完整背景可延伸阅读 多智能体适配规范 §2.5「当前 Hook」 与 插件运行时加固规范。小结Webnovel Writer 的 hooks 机制用不到 300 行 Python 完成了两件事开局让 AI「记住进度」落笔前让 AI「不敢越权」。它不追求万能而是以 fail-open、限时、可关闭的姿态做长连载运行时最经济的一道护栏。相关文件清单注册配置webnovel-writer/hooks/hooks.json会话状态 hookwebnovel-writer/hooks/session_start.py写入守卫 hookwebnovel-writer/hooks/guard_runtime_write.py行为契约测试webnovel-writer/scripts/tests/test_hooks.py运维手册Hook 开关docs/operations/operations.md【免费下载链接】webnovel-writer基于 Claude Code 的长篇网文辅助创作系统解决 AI 写作中的「遗忘」和「幻觉」问题支持 200 万字量级 连载创作。项目地址: https://gitcode.com/GitHub_Trending/we/webnovel-writer创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考