cb9b16e5a8
包含： - 核心配置文件（AGENTS.md, SOUL.md, USER.md等） - 记忆系统（memory/文件夹） - 技能库（skills/文件夹） - 小说内容（novel/文件夹） - .gitignore配置
385 lines
8.9 KiB
Markdown
385 lines
8.9 KiB
Markdown
# Fanfic Writer v2.0 - 安装指南 / Installation Guide
|
||
|
||
自动化小说写作助手 v2.0 - 基于证据的状态管理、多视角QC、原子I/O
|
||
|
||
---
|
||
|
||
## 📦 安装要求 / Installation Requirements
|
||
|
||
### 环境要求 / Environment Requirements
|
||
|
||
- **OpenClaw**: 最新版本
|
||
- **模型**: 由 OpenClaw 自动提供（skill 不硬编码模型）
|
||
|
||
### 重要说明
|
||
|
||
这个 skill **不包含任何模型配置**。当 OpenClaw 调用此 skill 时，自动使用 OpenClaw 当前配置的模型。
|
||
|
||
---
|
||
|
||
## 📥 安装步骤 / Installation Steps
|
||
|
||
### 方式一：通过 ClawHub 安装 / Install via ClawHub (Recommended)
|
||
|
||
```bash
|
||
# 搜索 fanfic-writer 技能
|
||
clawhub search fanfic-writer
|
||
|
||
# 安装
|
||
clawhub install fanfic-writer
|
||
```
|
||
|
||
### 方式二：手动安装 / Manual Installation
|
||
|
||
**步骤1: 复制技能文件到 OpenClaw 目录**
|
||
|
||
**Windows:**
|
||
```powershell
|
||
# 复制整个 fanfic-writer 目录到
|
||
C:\Users\<用户名>\.openclaw\skills\
|
||
# 或
|
||
C:\Users\<用户名>\clawd\skills\
|
||
```
|
||
|
||
**Linux/macOS:**
|
||
```bash
|
||
# 复制整个 fanfic-writer 目录到
|
||
~/.openclaw/skills/
|
||
# 或
|
||
~/.clawd/skills/
|
||
```
|
||
|
||
**步骤2: 确保目录结构完整**
|
||
|
||
```
|
||
fanfic-writer/
|
||
├── SKILL.md # 技能说明 (本文件)
|
||
├── INSTALL_GUIDE.md # 安装指南
|
||
├── prompts/
|
||
│ ├── v1/ # 核心模板 (Auto模式必需)
|
||
│ │ ├── chapter_outline.md
|
||
│ │ ├── chapter_draft_first.md
|
||
│ │ ├── chapter_draft_continue.md
|
||
│ │ ├── chapter_plan.md
|
||
│ │ ├── main_outline.md
|
||
│ │ └── world_building.md
|
||
│ └── v2_addons/ # 扩展模板
|
||
│ ├── critic_editor.md
|
||
│ ├── critic_logic.md
|
||
│ ├── critic_continuity.md
|
||
│ ├── reader_feedback.md
|
||
│ ├── qc_evaluate.md
|
||
│ ├── backpatch_plan.md
|
||
│ └── sanitizer.md
|
||
├── scripts/
|
||
│ ├── v2/ # v2.0 核心代码
|
||
│ │ ├── __init__.py
|
||
│ │ ├── utils.py
|
||
│ │ ├── atomic_io.py
|
||
│ │ ├── workspace.py
|
||
│ │ ├── config_manager.py
|
||
│ │ ├── state_manager.py
|
||
│ │ ├── prompt_registry.py
|
||
│ │ ├── prompt_assembly.py
|
||
│ │ ├── price_table.py
|
||
│ │ ├── resume_manager.py
|
||
│ │ ├── phase_runner.py
|
||
│ │ ├── writing_loop.py
|
||
│ │ ├── safety_mechanisms.py
|
||
│ │ ├── cli.py
|
||
│ │ └── test_v2.py
|
||
│ ├── v1/ # v1.0 兼容代码 (可选)
|
||
│ └── test_v2.py
|
||
└── requirements.txt # Python依赖 (如需要)
|
||
```
|
||
|
||
**步骤3: 安装 Python 依赖 (如需要)**
|
||
|
||
```bash
|
||
# 进入技能目录
|
||
cd fanfic-writer
|
||
|
||
# 安装依赖 (v2.0 主要使用标准库，通常无需额外安装)
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
**步骤4: 重启 OpenClaw**
|
||
|
||
安装完成后重启 OpenClaw，技能会自动加载。
|
||
|
||
```bash
|
||
# 重启 OpenClaw
|
||
openclaw restart
|
||
# 或
|
||
openclaw gateway restart
|
||
```
|
||
|
||
---
|
||
|
||
## 🚀 快速开始 / Quick Start
|
||
|
||
### 1. 初始化新书 / Initialize a New Book
|
||
|
||
```bash
|
||
# 使用 CLI
|
||
python -m scripts.v2.cli init --title "我的小说" --genre "都市灵异" --words 100000
|
||
|
||
# 或通过 OpenClaw 对话
|
||
写一本都市灵异小说
|
||
```
|
||
|
||
### 2. 运行写作 / Run Writing
|
||
|
||
```bash
|
||
# 自动模式写作 (推荐)
|
||
python -m scripts.v2.cli write --run-dir <path> --mode auto --chapters 1-10
|
||
|
||
# 手动模式 (每步需确认)
|
||
python -m scripts.v2.cli write --run-dir <path> --mode manual
|
||
```
|
||
|
||
### 3. 断点续写 / Resume Writing
|
||
|
||
```bash
|
||
# 自动检测并续写
|
||
python -m scripts.v2.cli write --run-dir <path> --resume auto
|
||
|
||
# 强制恢复
|
||
python -m scripts.v2.cli write --run-dir <path> --resume force
|
||
```
|
||
|
||
### 4. 完成写作 / Finalize
|
||
|
||
```bash
|
||
# 合并章节并生成最终报告
|
||
python -m scripts.v2.cli finalize --run-dir <path>
|
||
```
|
||
|
||
---
|
||
|
||
## 📋 CLI 命令参考 / CLI Command Reference
|
||
|
||
| 命令 Command | 说明 Description | 示例 Example |
|
||
|------------|-----------------|--------------|
|
||
| `init` | 初始化新书 | `init --title "书名" --genre "类型"` |
|
||
| `setup` | 运行阶段1-5 | `setup --run-dir <path>` |
|
||
| `write` | 写作 (阶段6) | `write --run-dir <path> --mode auto` |
|
||
| `backpatch` | 回补修复 | `backpatch --run-dir <path>` |
|
||
| `finalize` | 最终化 (阶段8-9) | `finalize --run-dir <path>` |
|
||
| `status` | 查看状态 | `status --run-dir <path>` |
|
||
| `test` | 自测 | `test` |
|
||
|
||
### 常用参数 / Common Options
|
||
|
||
| 参数 Option | 说明 Description | 默认值 Default |
|
||
|------------|-----------------|----------------|
|
||
| `--run-dir, -r` | 运行目录 | 必需 |
|
||
| `--mode` | 模式: auto/manual | manual |
|
||
| `--chapters` | 章节范围 | 全部 |
|
||
| `--resume` | 恢复: off/auto/force | off |
|
||
| `--budget` | 成本预算 (元) | 无限制 |
|
||
| `--max-words` | 最大字数 | 500000 |
|
||
|
||
---
|
||
|
||
## ⚙️ 配置说明 / Configuration
|
||
|
||
### 0-book-config.json
|
||
|
||
在初始化时会自动生成，核心字段：
|
||
|
||
```json
|
||
{
|
||
"version": "2.0.0",
|
||
"book": {
|
||
"title": "书名",
|
||
"title_slug": "shu_ming",
|
||
"book_uid": "a1b2c3d4",
|
||
"genre": "都市灵异",
|
||
"target_word_count": 100000,
|
||
"chapter_target_words": 2500
|
||
},
|
||
"generation": {
|
||
"model": "nvidia/moonshotai/kimi-k2.5",
|
||
"mode": "auto",
|
||
"max_attempts": 3,
|
||
"auto_threshold": 85,
|
||
"auto_rescue_enabled": true,
|
||
"auto_rescue_max_rounds": 3
|
||
},
|
||
"qc": {
|
||
"pass_threshold": 85,
|
||
"warning_threshold": 75,
|
||
"weights": {...}
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 💰 成本管理 / Cost Management
|
||
|
||
### 费率表 / Price Table
|
||
|
||
v2.0 内置费率表，支持多平台：
|
||
|
||
```bash
|
||
# 查看当前费率
|
||
cat 0-config/price-table.json
|
||
|
||
# 更新费率 (运行时)
|
||
# 编辑 price-table.json 后自动热更新
|
||
```
|
||
|
||
### 成本报告 / Cost Report
|
||
|
||
```bash
|
||
# 查看成本日志
|
||
cat logs/cost-report.jsonl
|
||
|
||
# 成本统计
|
||
# 在 final/quality-report.md 中查看
|
||
```
|
||
|
||
---
|
||
|
||
## 🔧 高级功能 / Advanced Features
|
||
|
||
### 1. 状态面板 / State Panels
|
||
|
||
v2.0 使用7个状态面板追踪写作进度：
|
||
|
||
- `4-writing-state.json` - 核心状态
|
||
- `characters.json` - 角色状态
|
||
- `plot_threads.json` - 剧情线索
|
||
- `timeline.json` - 时间线
|
||
- `inventory.json` - 道具
|
||
- `locations_factions.json` - 地点/势力
|
||
- `session_memory.json` - 滚动记忆
|
||
|
||
### 2. 证据链 / Evidence Chain
|
||
|
||
所有状态变更需要证据：
|
||
|
||
```json
|
||
{
|
||
"value": "...",
|
||
"evidence_chapter": "第015章",
|
||
"evidence_snippet": "张大胆说：...",
|
||
"confidence": 0.85
|
||
}
|
||
```
|
||
|
||
### 3. 安全机制 / Safety Mechanisms
|
||
|
||
- **Auto-Rescue**: 自动尝试恢复可恢复错误
|
||
- **Auto-Abort**: 检测卡死循环并暂停
|
||
- **Backpatch**: FORCED章节的回补修复
|
||
- **Forced Streak**: 连续FORCED触发熔断
|
||
|
||
---
|
||
|
||
## 🐛 故障排查 / Troubleshooting
|
||
|
||
### 技能未加载 / Skill Not Loading
|
||
|
||
```bash
|
||
# 检查目录结构
|
||
ls -la ~/.openclaw/skills/fanfic-writer/
|
||
|
||
# 重启 OpenClaw
|
||
openclaw restart
|
||
```
|
||
|
||
### 模型调用失败 / Model Call Failed
|
||
|
||
```bash
|
||
# 检查 API 配置
|
||
openclaw config get
|
||
|
||
# 确认模型可用
|
||
# 查看错误日志
|
||
cat <run-dir>/logs/errors.jsonl
|
||
```
|
||
|
||
### 断点续写失败 / Resume Failed
|
||
|
||
```bash
|
||
# 检查状态文件
|
||
cat <run-dir>/4-state/4-writing-state.json
|
||
|
||
# 强制恢复
|
||
python -m scripts.v2.cli write --run-dir <path> --resume force
|
||
```
|
||
|
||
---
|
||
|
||
## 📊 性能优化 / Performance Optimization
|
||
|
||
### 减少Token消耗
|
||
|
||
1. **使用高效模型**: 推荐 `moonshot/kimi-k2.5`
|
||
2. **调整上下文窗口**: 在配置中设置 `context_bucket`
|
||
3. **批量处理**: 使用 `--chapters 1-10` 批量写作
|
||
|
||
### 成本控制
|
||
|
||
1. **设置预算**: `--budget 100` (100元)
|
||
2. **监控成本**: 查看 `logs/cost-report.jsonl`
|
||
3. **使用缓存**: 启用 `cache_mode`
|
||
|
||
---
|
||
|
||
## 📄 文件结构 / File Structure
|
||
|
||
```
|
||
novels/
|
||
└── {book_title_slug}__{book_uid}/
|
||
└── runs/
|
||
└── {run_id}/
|
||
├── 0-config/ # 配置
|
||
├── 1-outline/ # 大纲
|
||
├── 2-planning/ # 规划
|
||
├── 3-world/ # 世界观
|
||
├── 4-state/ # 运行时状态 (7面板)
|
||
├── drafts/ # 草稿
|
||
├── chapters/ # 正式章节
|
||
├── anchors/ # 锚点
|
||
├── logs/ # 日志 (token/cost/事件)
|
||
├── archive/ # 归档 (快照/回滚)
|
||
└── final/ # 最终输出
|
||
```
|
||
|
||
---
|
||
|
||
## 🔄 从 v1.0 迁移 / Migration from v1.0
|
||
|
||
v2.0 保持向后兼容：
|
||
|
||
```bash
|
||
# v1.0 书籍可用 v2.0 继续写作
|
||
python -m scripts.v2.cli write --run-dir <v1_book_path> --resume auto
|
||
```
|
||
|
||
注意: v1.0 目录结构不同，需要复制到新的 `runs/{run_id}/` 结构中。
|
||
|
||
---
|
||
|
||
## 📞 支持 / Support
|
||
|
||
- **文档**: 参见 `SKILL.md`
|
||
- **问题反馈**: GitHub Issues
|
||
- **社区**: OpenClaw Discord
|
||
|
||
---
|
||
|
||
## 📄 许可证 / License
|
||
|
||
MIT License - 可自由使用、修改、分发。
|
||
|
||
---
|
||
|
||
**Happy Writing! 🎉**
|
||
|
||
**创作愉快! 🎉**
|