agent-xs 0.1.0
CLI tool for novel writing with Claude Code plugin
Requires Python: >=3.11
Keywords: claude, cli, novel, writing

#  中文网文小说写作助手

一个为中文网文创作设计的 Claude Code 插件，提供从主题确定到最终定稿的完整写作流程支持。

## 功能特性

### 五阶段写作流程

1. **主题确定** (`/theme`) - 与 AI 对话确定小说主题、类型、世界观和基调
2. **大纲编写** (`/outline`) - 根据主题编写完整的小说大纲
3. **项目初始化** (`/init`) - 初始化小说项目，创建角色、物品、场景、事件信息文件
4. **草稿编写** (`/draft`) - 逐章编写草稿，每次写一章
5. **章节定稿** (`/finalize`) - 审阅并定稿章节，确保连贯性

### 核心特性

- **知识库管理**: 自动维护角色、物品、场景、事件的结构化信息
- **实时同步**: 草稿阶段即时同步知识库，保持信息最新
- **连贯性保障**: 定稿时参考后续草稿，确保剧情连贯
- **YAML frontmatter**: 结构化元数据方便查询和管理

## 安装

### 方法 1: 本地安装

克隆本仓库到本地：

```bash
git clone <repository-url>
cd agent-xs
```

在 Claude Code 中使用 `--plugin-dir` 加载：

```bash
cc --plugin-dir /path/to/agent-xs
```

### 方法 2: 复制到项目

将插件复制到项目的 `.claude-plugin/` 目录：

```bash
cp -r agent-xs /path/to/your-project/.claude-plugin/
```

## 使用指南

### 1. 确定主题与基调

```bash
/theme
```

Agent 会与你对话，探讨：
- 小说类型（玄幻、仙侠、都市、科幻等）
- 世界观设定
- 主角设定
- 主题与核心冲突
- 写作风格
- 目标读者群

结果保存在 `小说/主题与基调.md`

### 2. 编写大纲

```bash
/outline
```

根据主题与基调，Agent 帮助你编写：
- 整体结构
- 各卷/篇章规划
- 主要情节线
- 角色发展弧

结果保存在 `大纲/整体大纲.md`

### 3. 初始化项目

```bash
/init
```

Agent 根据大纲创建初始信息：
- `现有信息/角色/<角色名>.md` - 主要角色档案
- `现有信息/物品/<物品名>.md` - 关键物品
- `现有信息/场景/<场景名>.md` - 重要场景
- `现有信息/事件/<事件名>.md` - 初始事件

### 4. 编写草稿

```bash
/draft
```

编写一章草稿。Agent 会：
- 参考所有现有信息和大纲
- 包含章节元数据（序号、标题、字数、时间线、出场角色、场景、主要事件、情绪曲线）
- **实时同步知识库更新**

草稿保存在 `草稿/[序号]. <章节名>.md`

### 5. 定稿章节

```bash
/finalize
```

审阅并定稿章节。Agent 会：
- 检查后续草稿状态（推荐有后续草稿以确保连贯性）
- 参考所有现有信息和后续草稿
- 审阅章节内容，修改优化
- 如有修改则同步更新知识库

定稿保存在 `正文/[序号]. <章节名>.md`

## 文件结构

创作过程中会生成以下结构：

```
your-novel/
├── 小说/
│   └── 主题与基调.md
├── 大纲/
│   └── 整体大纲.md
├── 现有信息/              # 核心知识库
│   ├── 角色/
│   │   ├── 张三.md
│   │   └── 李四.md
│   ├── 物品/
│   │   └── 玄天剑.md
│   ├── 场景/
│   │   └── 云霄宗.md
│   └── 事件/
│       └── 宗门大比.md
├── 草稿/
│   ├── 1. 初入仙门.md
│   ├── 2. 首次修炼.md
│   └── 3. 意外奇遇.md
└── 正文/
    └── 1. 初入仙门.md
```

## 信息文件格式

### 角色文件示例

```markdown
---
name: 张三
status: alive
role: 主角
first_appearance: 1
last_updated: 5
age: 25
gender: 男
cultivation_level: 筑基期
faction: 云霄宗
relationships:
  - target: 李四
    type: 师徒
    note: 师父
---

## 外貌特征
[描述]

## 性格特点
[描述]

## 背景故事
[描述]

## 发展轨迹
- 第1章: 初次登场...
```

详细格式请参考插件文档。

## 命令列表

| 命令 | 说明 |
|------|------|
| `/theme` | 确定主题与基调 |
| `/outline` | 编写整体大纲 |
| `/init` | 初始化小说项目 |
| `/draft [章节号]` | 编写一章草稿 |
| `/finalize <章节号>` | 审阅定稿一章 |
| `/edit <类型> [名称]` | 编辑主题/大纲/知识库 |
| `/status` | 查看项目状态 |

## 辅助工具

### 快速查阅知识库

Claude 会自动使用 quick-lookup skill 来查阅知识库。你也可以手动运行脚本：

```bash
# 列出所有知识库内容
uv run ${PLUGIN_PATH}/skills/quick-lookup/scripts/list_info.py --all

# 列出所有角色
uv run ${PLUGIN_PATH}/skills/quick-lookup/scripts/list_info.py 角色

# 查看元数据
uv run ${PLUGIN_PATH}/skills/quick-lookup/scripts/list_info.py 角色 张三 --brief

# 查看完整信息
uv run ${PLUGIN_PATH}/skills/quick-lookup/scripts/list_info.py 角色 张三 --detail

# 搜索关键词
uv run ${PLUGIN_PATH}/skills/quick-lookup/scripts/search_info.py 玄天剑

# 忽略大小写搜索
uv run ${PLUGIN_PATH}/skills/quick-lookup/scripts/search_info.py -i keyword
```

其中 `${PLUGIN_PATH}` 是插件安装路径（如 `.claude-plugin/agent-xs` 或通过 `--plugin-dir` 指定的路径）。

详细说明请参考 `skills/quick-lookup/SKILL.md`

## 工作原理

### 草稿 vs 定稿

**草稿阶段**:
- 快速推进剧情
- **同步更新知识库**，保持信息最新
- 信息更新记录在章节末尾
- 可以大胆尝试各种剧情发展

**定稿阶段**:
- 审阅草稿质量
- 检查连贯性（推荐有后续草稿）
- 修改优化文笔
- 标记为可发布状态

### 推荐工作流

1. 连续编写 3-4 章草稿
2. 回头定稿第 1 章（此时可参考后续草稿检查连贯性）
3. 继续编写新草稿
4. 定稿下一章
5. 循环往复

## 最佳实践

1. **主题阶段**: 花时间充分探讨，主题决定整本书的方向
2. **大纲阶段**: 不必过于详细，留出创作空间
3. **保持节奏**: 至少完成后3章草稿再开始定稿
4. **定期备份**: 知识库是核心资产，定期备份
5. **灵活调整**: 草稿阶段可大胆调整剧情，定稿前都可修改

## 技术细节

- 使用 YAML frontmatter 存储结构化元数据
- Markdown 格式便于阅读和版本控制
- 知识库采用分类文件管理，便于查询和维护
- 章节元数据包含丰富信息，便于分析和调整

## 贡献

欢迎提交 Issue 和 Pull Request！

## 许可证

MIT License

## 更新日志

### 0.2.0
- **流程优化**：草稿阶段现在实时同步知识库，提高创作效率
- **新增命令**：
  - `/edit` 支持编辑主题、大纲和知识库
  - `/status` 查看项目状态和进度
- **命令参数**：`draft` 和 `finalize` 命令支持指定章节号
- **Prompt 精简**：大幅精简命令 prompt，提高响应速度
- **写作技巧**：将网文写作技巧整合到 skill 中按需加载
- **定稿简化**：后3章草稿要求改为推荐而非强制
- **脚本增强**：
  - `list_info.py --all` 一次查看所有知识库内容
  - `search_info.py -i` 支持忽略大小写搜索
- **模板优化**：角色模板 `power_level` 字段适用于所有类型小说

### 0.1.0 (Initial Release)
- 五阶段完整写作流程
- 知识库管理系统
- 草稿-定稿分离机制