# WriterSkill

**Repository Path**: adetion/writer-skill

## Basic Information

- **Project Name**: WriterSkill
- **Description**: 写手Skill（长篇小说创作助手，自带知识库学习）。支持分块生成、知识库安全检索、状态机持久化、全自动创作流程，支持自动解析Word(docx)/Excel(xlsx)/PDF/TXT/MD格式文件转换为【结构化YAML知识库】。使用场景：当用户需要创作长篇小说、生成大量文本内容、管理连载写作进度、避免大文本对话导致token超限错误、需要导入多格式文件转换为YAML知识库时激活。
- **Primary Language**: Python
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: https://wop.cc
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 1
- **Created**: 2026-04-10
- **Last Updated**: 2026-05-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

---
name: writer
description: 【零token超限400错误保证的】【长篇文本/小说】创作助手，支持分块生成、知识库安全检索、状态机持久化、全自动创作流程，支持自动解析Word(docx)/Excel(xlsx)/PDF/TXT/MD格式文件转换为【结构化YAML知识库】。使用场景：当用户需要创作长篇小说、生成大量文本内容、管理连载写作进度、避免大文本对话导致token超限错误、需要导入多格式文件转换为YAML知识库时激活。
---

# 烦请尊重作者辛苦，随意打赏~~~英文版请移步https://github.com/adetion/Writer.Skill

【QQ群：611951252 】

# 【Writer（写手）Skill技能】

## 概述
本技能专为长篇内容创作设计，核心目标是**零400 token超限错误保证**，所有大文本通过文件交换，对话仅返回状态和进度信息，确保即使每日创作8万字的极端场景下，所有API调用安全可控，用户无需关心底层token限制。

![输入图片说明](%E6%88%AA%E5%B1%8F2026-04-11%2000.38.41.png)

## 核心设计原则（零400错误保证）
1.  任何与LLM的交互，输入token + 输出token严格控制在当前模型限制的80%以内，自动适配模型上下文窗口大小（32k/128k等）
2.  采用「分片生成、外部存储、渐进式构建」策略，所有大文本不进入对话上下文
3.  内部使用状态机驱动，每一步仅处理小段内容，避免单次请求超限
4.  若请求预估会超限，自动降级（压缩上下文、拆分输出、分步执行）并通知用户

## 知识库使用规则（安全检索不超限）
1.  知识库以结构化文件（JSON/YAML）存储在OpenClaw工作区，默认路径为`./novel_knowledge/`，支持向量/关键词索引
2.  **多格式自动解析**：支持直接导入docx、xlsx、pdf、txt、md格式文件，自动解析转换为结构化YAML知识库条目，无需手动整理格式
3.  每次生成内容时，仅提取与当前情节最相关的设定片段，拼接后总token不超过8k（可配置）
4.  知识库条目过大时自动截断或生成摘要后再注入上下文，不加载全量内容
5.  知识库更新采用增量修改，不重新加载全量数据

> 知识库配置参考：[references/knowledge_config.md](references/knowledge_config.md)
> 文件解析脚本：[scripts/file_parser.py](scripts/file_parser.py)
> 依赖安装：运行 `pip install -r requirements.txt` 安装所有解析依赖

### 知识库导入使用方法
1. **自动导入**：直接上传任意支持格式的文件（docx/xlsx/pdf/txt/md），技能自动触发解析，转换为结构化YAML条目存入知识库
2. **手动解析**：执行命令 `python scripts/file_parser.py <文件路径>` 可手动解析指定文件
3. **自动打标签**：解析过程自动识别内容类型，自动添加「人物」「世界观」「剧情」等标签，自动设置优先级
4. **文件备份**：原始文件自动备份到知识库目录，不会丢失

支持的文件格式：
| 格式 | 说明 |
|------|------|
| .docx | Word文档，自动按段落/标题拆分条目 |
| .xlsx | Excel表格，自动按行转换为条目，第一行作为表头 |
| .pdf | PDF文档，自动提取文本拆分条目 |
| .txt/.md | 纯文本/Markdown文档，自动按标题/空行拆分条目 |

## 章节生成规则（分步拼接，单次输出短小）
### 章节拆分生成
1.  单章8000字拆分为4~8个场景块（每块1000~2000字），逐块生成
2.  每生成一个场景块立即写入外部文件，不返回完整章节到对话
3.  下一场景块生成时仅读取最近1~2个已生成块作为上下文，避免加载全章历史，同时保留必要的人物/情节状态
4.  场景块之间的连贯性由技能自动保证，写入文件时无缝拼接

### 单次API调用控制
1.  每次调用前自动统计当前输入（系统指令 + 检索知识库片段 + 最近场景块 + 生成提示）的token数，超过安全阈值（默认24k）时自动压缩（减少历史块数量、缩短知识库片段）
2.  单次输出限制为不超过2k tokens（约1500~2000字），可根据模型能力上调，但总token不得超过模型限制的80%

> 生成脚本：[scripts/generate_chunk.py](scripts/generate_chunk.py)

## 对话交互规则（极简消息，无大内容返回）
1.  所有对话回复仅包含状态、进度、文件路径、少量预览，单条回复不超过500字
2.  超过500字的内容（大纲、章节正文、检查报告）全部写入外部文件，对话中仅提供文件路径或简短摘要
3.  收到用户创作命令后立即回复「任务已启动，进度将实时更新」，通过多条短消息逐步反馈进度（每生成一个场景块/一章发送一条短消息）
4.  支持异步后台运行，完成时发送汇总通知

## 状态机与持久化规则
1.  维护`novel_state.json`状态文件，记录：
    - 当前总进度（已生成章节、场景块数量）
    - 待生成大纲
    - 每章/每场景块的文件路径
    - 知识库检索缓存（最近使用的设定）
    - 下一步动作（生成大纲、生成下一场景块、合规检查等）
2.  每次调用技能先读取状态文件决定执行步骤，执行后更新状态再退出
3.  支持断点续传，对话中断或token限制触发后可从断点继续，不丢失进度

> 状态管理脚本：[scripts/state_manager.py](scripts/state_manager.py)

## 每日创作全流程（全自动无超限风险）
1.  **生成大纲**：不一次性生成全量大纲，分批次生成1~3章大纲（每章1~3句话），写入大纲文件，每次仅返回进度提示
2.  **逐章生成**：根据大纲和状态逐章、逐场景块生成，每生成一个块立即写入文件并更新状态，每章完成后执行轻量级自检，自检报告写入文件
3.  **章节衔接**：生成新章第一个场景块时自动加载上一章最后两个场景块作为上下文，保证情节连贯
4.  **每日终检**：所有章节生成后，后台异步执行全量合规检查，生成报告文件，最终发送汇总消息：「今日创作完成，共X章，合规检查通过，结果存于[文件路径]」

## 反馈与修改规则（安全更新）
1.  用户提出修改某章节时，仅加载该章节文件 + 必要知识库内容，分场景块生成修改后的版本，覆盖原文件并更新状态
2.  后续章节生成自动识别修改内容，保持情节一致性
3.  若用户一次性粘贴大量素材，自动提示「素材过大，请分批提供或直接上传文件」，避免单次输入超限

## 错误处理与降级规则
1.  若API调用因token超限失败，自动捕获后压缩输入（减少历史、缩短知识库片段）重试，最多重试3次
2.  重试仍失败则暂停任务，发送错误报告文件并等待用户指令
3.  所有错误日志写入`./logs/writer_error.log`文件，便于排查

## 可配置参数
所有参数可通过[references/config.yaml](references/config.yaml)修改：
| 参数名 | 说明 | 默认值 |
|--------|------|--------|
| max_input_tokens | 单次请求输入token上限（留空自动适配当前模型） | 24k |
| max_output_tokens | 单次请求输出token上限（留空自动适配当前模型） | 2k |
| safety_threshold | 总token安全阈值（不超过模型限制的百分比） | 0.8 |
| context_chunks | 保留最近场景块数量 | 2 |
| knowledge_chunk_size | 知识库检索片段最大token | 4k |
| work_dir | 创作内容存储目录 | ./novel_workspace/ |
| min_chapter_words | 单章最小字数 | 8000 |
| max_retry_count | token超限失败重试次数 | 3 |

## 资源说明
### scripts/
- `generate_chunk.py`：场景块生成脚本，负责token统计、内容生成、文件写入
- `state_manager.py`：状态文件读写、断点续传管理
- `knowledge_retriever.py`：知识库检索、片段提取、摘要生成
- `validator.py`：token超限检查、内容合规检查
- `file_parser.py`：多格式文件解析脚本，支持docx/xlsx/pdf/txt/md自动转换为结构化YAML知识库

### references/
- `config.yaml`：技能参数配置文件
- `knowledge_config.md`：知识库结构、索引配置说明
-