已经可以写了，考虑以后再完善。
私仓：zkcoi/novelmaster - novelmaster - Gitea: Git with a cup of tea
最近有个概念非常火， Harness Engineering，于是开始尝试使用ClaudeCode开始一个项目，来验证尝试如何能更好的Harness智能体。
实际上整体看下来，没有什么好的应用方向，于是看了一些项目，最终确定了以长篇小说为例，来构建一个基于Claude Code 的长篇网络小说创作系统，核心是希望使用工程化的方式来解决遗忘和幻觉的两个问题，最终写出一部百万字的爽文小说。
最终的效果感觉非常不错，而且关键在于设定集。记录下整个过程，感觉还是比较有意思，最终报告由ClaudeCode via MiniMax-M2.7整理，因为懒得写了。
# NovelMaster (Noma) 演进报告：从简单 Agent 到 Harness Engineering
> 一个 AI 辅助写作系统的架构演进历程
---
## 摘要
本文记录 **NovelMaster (Noma)** 项目从最初简单原型到当前复杂系统的演进过程。通过分析这个演进轨迹，我们可以理解 **Harness Engineering**（约束工程化）方法论是如何在创意 AI 领域落地实践的，以及为什么"更复杂的架构"并不总是意味着"更好的效果"。
---
## 1. 项目起源：解决 AI 写作的两大痛点
### 1.1 背景
2026 年初，我们开始探索用 AI 辅助长篇网络小说创作。在实践中发现了两个核心问题：
| 问题 | 表现 | 根因分析 |
|------|------|----------|
| **遗忘** | AI 写到第 50 章时忘记第 3 章的设定 | 上下文窗口限制 |
| **幻觉** | AI 写出的情节与已有大纲冲突 | 缺乏约束机制 |
### 1.2 初始洞察
> **与其让 AI 自由发挥，不如给它套上一层"马具"——让它在约束范围内发挥创造力。**
这就是 Harness Engineering 的核心思想。
---
## 2. 演进阶段一览
```
┌────────────────────────────────────────────────────────────────────────────┐
│ NovelMaster 演进时间线 │
├────────────────────────────────────────────────────────────────────────────┤
│ │
│ v1.0 (2026-01) v2.0 (2026-04) v5.0 (当前) │
│ ──────────────── ──────────────── ────────────── │
│ 简单双 Agent 10 子系统增强 分层架构 + 复杂状态 │
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │
│ │Context Agent│ │Context Agent│ │ Skill Layer │ │
│ │(上下文构建) │ │ + 欲望演化 │ │ noma-init/plan/ │ │
│ └─────────────┘ │ + RAG 强制 │ │ write/review/... │ │
│ ↓ └─────────────┘ └──────────┬──────────┘ │
│ ┌─────────────┐ ↓ │ │
│ │Data Agent │ ┌─────────────┐ ↓ │
│ │(数据回写) │ │六维审查矩阵 │ ┌─────────────────────┐ │
│ └─────────────┘ └─────────────┘ │ Agent Matrix │ │
│ │ Context/Data/Checker │ │
│ └──────────┬──────────┘ │
│ │ │
│ ┌──────────▼──────────┐ │
│ │ Core Engine │ │
│ │ state_manager/ │ │
│ │ memory_rag/validators│ │
│ └─────────────────────┘ │
└────────────────────────────────────────────────────────────────────────────┘
```
---
## 3. v1.0：最小可用原型
### 3.1 架构
```
┌─────────────────────────────────────────────────────┐
│ 最初的 noma 结构 │
├─────────────────────────────────────────────────────┤
│ │
│ Context Agent Data Agent │
│ ───────────── ────────── │
│ • 读大纲 • 提取实体 │
│ • 读前几章 • 更新 state.json │
│ • 构建上下文 • 写摘要 │
│ │
│ [整个系统只有 2 个 Agent，约 500 行代码] │
│ │
└─────────────────────────────────────────────────────┘
```
### 3.2 核心代码示例
```python
# v1.0 的 Context Agent (伪代码)
def build_context(chapter_num):
# 读取前 3 章
recent_chapters = read_chapters(chapter_num - 3, chapter_num)
# 读取大纲
outline = read_outline()
# 构建上下文
return {
"objectives": extract_objectives(outline, chapter_num),
"characters": extract_characters(recent_chapters),
"setting": extract_setting(recent_chapters)
}
# v1.0 的 Data Agent (伪代码)
def save_chapter(chapter_num, content):
# 提取实体
entities = extract_entities(content)
# 更新状态
state = read_state()
state["entities"].update(entities)
state["progress"] = chapter_num
write_state(state)
# 写摘要
summary = summarize(content)
write_summary(chapter_num, summary)
```
### 3.3 v1.0 的问题
| 问题 | 表现 | 严重程度 |
|------|------|----------|
| 上下文太少 | 写到 20 章就出现设定矛盾 | 🔴 严重 |
| 无质量审查 | 写完就丢，不知道质量如何 | 🟡 中等 |
| 状态分散 | entity/relationship/state 混在一起 | 🟢 轻微 |
---
## 4. v2.0：长篇稳定性增强
### 4.1 为什么需要 v2.0
当创作超过 **500 章、500 万字** 时，v1.0 的问题开始暴雷：
- 前 50 章的设定到后期完全失效
- 战力系统通货膨胀失控
- 伏笔埋了 30 章忘记回收
- 因果链断裂，出现"突然"发展的情节
### 4.2 新增的 10 个子系统
根据 FIXES.md (v2.0 长篇稳定性修复)，新增了：
| # | 子系统 | 解决什么问题 | 文件位置 |
|---|--------|-------------|----------|
| 1 | **欲望演化引擎** | 角色动机单调 | `ledger.py` |
| 2 | **数值平衡系统** | 战力通胀失控 | `ledger.py` |
| 3 | **Hook 债务机制** | 伏笔回收率低 | `ledger.py` |
| 4 | **奇观演化系统** | 审美疲劳 | `genesis_contract.json` |
| 5 | **角色后台演化** | 休眠角色状态丢失 | `handoff.py` |
| 6 | **设定原样引用** | 设定概括失真 | `context-agent.md` |
| 7 | **因果链推导** | 情节跳跃断裂 | `context-agent.md` |
| 8 | **RAG 强制绑定** | RAG 结果被忽略 | `context-agent.md` |
| 9 | **逻辑一致性审查器** | 逻辑漏洞 | `logic_consistency_checker.py` |
| 10 | **章节预规划器** | 缺乏事前规划 | `noma-preplan/` |
### 4.3 核心增强示例
**欲望演化引擎** (ledger.py):
```python
class DesirePhase(Enum):
EMBRYONIC = "萌芽期" # 0-15%
GROWING = "成长期" # 15-35%
PEAK = "高峰期" # 35-65%
TRANSFORMATION = "转变期" # 65-85%
SUBLIMATION = "升华期" # 85-100%
def evolve_desire_phase(current_phase, chapter_progress):
"""根据章节进度计算欲望演化阶段"""
# 自动根据进度触发演化
pass
def detect_motivation_drift():
"""检测动机漂移，防止角色行为不一致"""
pass
```
**Hook 债务机制** (ledger.py):
```python
@dataclass
class HookDebtWarning:
hook_id: str
introduced_chapter: int
overdue_chapters: int
interest_rate: float # 超期利息
def force_hook_audit():
"""强制扫描未回收 Hook"""
# 默认回收期限: 50 章
# 超期利息: 每 50 章 +5%
pass
```
### 4.4 v2.0 的代价
新增 10 个子系统后，代码量从 ~500 行增长到 ~3000 行。
**新问题开始浮现**：
| 问题 | 表现 | 根因 |
|------|------|------|
| 上下文构建变慢 | Step 1 从 5 秒变成 30 秒 | 增强功能太多 |
| 审查结果难以汇总 | 6 个 Checker 返回格式不一 | 缺乏统一抽象 |
| 状态文件膨胀 | state.json 超过 100KB | 过度设计 |
---
## 5. v5.0：分层架构与复杂状态管理
### 5.1 当前架构
```
┌─────────────────────────────────────────────────────────────────┐
│ Skill Layer │
│ noma-init │ noma-plan │ noma-write │ noma-review │ noma-resume│
├─────────────────────────────────────────────────────────────────┤
│ Agent Matrix │
│ ┌─────────────┐ ┌─────────────┐ ┌────────────────────────┐ │
│ │Context Agent│ │ Data Agent │ │ Six Checkers │ │
│ │ │ │ │ │ consistency │ │
│ │ v2.0 增强版 │ │ 9 步 A-I │ │ continuity │ │
│ │ │ │ │ │ ooc │ │
│ │ │ │ │ │ reader-pull │ │
│ │ │ │ │ │ high-point │ │
│ │ │ │ │ │ pacing │ │
│ └─────────────┘ └─────────────┘ └────────────────────────┘ │
├─────────────────────────────────────────────────────────────────┤
│ Core Engine │
│ ┌────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ state_manager │ │ memory_rag │ │ validators │ │
│ │ │ │ │ │ │ │
│ │ handoff.py │ │ context_cache │ │ fourth_wall │ │
│ │ LOD/Tick/帧交接│ │ vectorstore │ │ 元叙事开关 │ │
│ │ │ │ │ │ │ │
│ │ ledger.py │ └─────────────────┘ └─────────────────┘ │
│ │ 资产/负债账本 │ │
│ │ │ │
│ │ retcon_manager │ │
│ │ 热补丁意图漂移 │ │
│ └────────────────┘ │
├─────────────────────────────────────────────────────────────────┤
│ Data Layer │
│ state.json │ index.db │ vectors.db │ ledger.json │ summaries/ │
└─────────────────────────────────────────────────────────────────┘
```
### 5.2 复杂状态管理
**handoff.py (帧交接协议)**:
```python
@dataclass
class HandoffFrame:
tick: int # 全局时钟
timestamp: float # 时间戳
active_characters: List[Character] # 在场角色 (LOD)
suspended_characters: List[Character] # 休眠角色
imminent_actions: List[ImminentAction] # 悬置动作
world_state: WorldState # 世界状态
metadata: HandoffMetadata # 章节元数据
```
**ledger.py (资产/负债账本)**:
```python
@dataclass
class Asset: # 爽感积累 (正面资产)
id: str
type: str # "arc_resolution", "character_growth"
value: float
@dataclass
class Liability: # 钩子债务 (负面资产)
id: str
type: str # "unresolved_hook", "promised_payoff"
interest_rate: float # 债务利息
```
### 5.3 当前代码规模
| 模块 | 文件数 | 代码行数 (估算) |
|------|--------|----------------|
| agents/ | 15+ | ~5,000 |
| core_engine/ | 10+ | ~8,000 |
| scripts/ | 30+ | ~15,000 |
| **总计** | **55+** | **~28,000** |
相比 v1.0 的 ~500 行，增长了 **56 倍**。
---
## 6. 演进过程中的关键设计决策
### 6.1 决策 1：Context Agent 的膨胀
**v1.0**: Context Agent 输出 ~500 字的上下文摘要
**v5.0**: Context Agent 需要输出：
- 7 板块任务书
- Context Contract (10+ 字段)
- 欲望演化状态
- 设定原样引用表
- 因果链推导
- RAG 强制绑定声明
**反思**: 一个 Agent 承担了太多责任，导致输出臃肿且难以维护。
### 6.2 决策 2：审查器的演进
**v1.0**: 无审查器
**v2.0**: 3 个核心审查器
**v5.0**: 6 个审查器 + 1 个 scene-depth-checker
| 审查器 | 检查内容 | 复杂度 |
|--------|---------|--------|
| consistency | 战力/地点/时间线 | O(n) |
| continuity | 场景连贯性 | O(n) |
| ooc | 角色行为 | O(n) |
| reader-pull | 钩子强度 | O(n²) |
| high-point | 爽点密度 | O(n²) |
| pacing | 节奏配比 | O(n) |
**反思**: 审查器数量增长，但它们的输出格式不统一，汇总决策变得困难。
### 6.3 决策 3：Data Agent 的 9 步链路
```
A. 加载上下文
↓
B. AI 实体提取
↓
C. 实体消歧
↓
D. 写入 state/index
↓
E. 章节摘要
↓
F. AI 场景切片
↓
G. RAG 向量索引
↓
H. 风格样本评估
↓
I. 债务利息
```
**反思**: 链路过长导致调试困难，而且某些步骤（如 RAG 索引）对最终质量的影响难以量化。
---
## 7. 演进教训：什么做对了，什么做错了
### 7.1 做对的事情 ✅
| 决策 | 效果 |
|------|------|
| **防幻觉三定律** | 有效减少了设定冲突 |
| **RAG 向量检索** | 解决了长篇上下文召回问题 |
| **模型档位系统** | 资源调配更灵活 |
| **最小回滚策略** | 失败处理更优雅 |
### 7.2 做错的事情 ❌
| 决策 | 问题 | 教训 |
|------|------|------|
| 引入游戏引擎概念 (LOD/Tick) | 过度工程化，叙事不是游戏 | 避免跨领域概念迁移 |
| Hook 债务利息 | 用户不理解，金融隐喻失败 | 概念需要可理解 |
| 6 个并行审查器 | 汇总决策困难 | 简化优于复杂 |
| 9 步 Data Agent | 链路太长，难以调试 | 最小可用优于完整 |
| Schema 强制填写 | 用户负担大 | 渐进式优于强制 |
### 7.3 核心问题诊断
```
┌─────────────────────────────────────────────────────────────────┐
│ 当前系统的核心矛盾 │
├─────────────────────────────────────────────────────────────────┤
│ │
│ 设计目标 vs 实际效果 │
│ ───────── ───────────── │
│ 解决"遗忘" 上下文召回确实有效 │
│ 解决"幻觉" 但系统本身变得"遗忘" │
│ （没人记得为什么这么设计） │
│ │
│ 全面覆盖 60+ 文件，28,000+ 行 │
│ 严格审查 6 个 Checker，输出难以汇总 │
│ 可追溯 状态文件膨胀，难以维护 │
│ │
└─────────────────────────────────────────────────────────────────┘
```
---
## 8. Harness Engineering 的实践总结
### 8.1 什么是 Harness Engineering
**Harness** = 马具。给一匹野马套上马具，让它能为人所用。
```
传统方式: AI 自由发挥 → 遗忘 + 幻觉
Harness: AI + 约束框架 → 结构化产出
核心思想: 不是限制 AI 的能力，而是引导它
```
### 8.2 本项目的 Harness 设计
| Harness 类型 | 实现 | 效果 |
|-------------|------|------|
| **大纲 Harness** | 大纲即法律 | 防止擅自发挥 |
| **设定 Harness** | 设定即物理 | 防止矛盾 |
| **实体 Harness** | 发明需识别 | 防止凭空创造 |
| **审查 Harness** | 六维矩阵 | 防止质量下滑 |
### 8.3 过度 Harness 的风险
```
┌────────────────────────────────────────────────────────────────┐
│ Harness 的临界点 │
├────────────────────────────────────────────────────────────────┤
│ │
│ 约束不足 ──────────────────────────────→ 约束过度 │
│ (AI 自由发挥，遗忘/幻觉) (系统复杂，难以使用) │
│ │
│ ▲ │
│ │ │
│ 当前平衡点 │
│ (可能偏右) │
│ │
│ 最佳点应该在: 最小可用约束 + 最大创意空间 │
│ │
└────────────────────────────────────────────────────────────────┘
```
---
## 9. 给同路人的建议
### 9.1 从简单开始
> **"First make it work, then make it complex."**
v1.0 的双 Agent 架构虽然简单，但它是**可用的**。后续的复杂化应该在验证了基础假设之后进行。
### 9.2 警惕过度工程化
| 信号 | 说明 |
|------|------|
| 新概念需要 500 字解释 | 可能过度复杂 |
| 状态文件超过 10 个 | 可能过度拆分 |
| 新增功能需要修改 5+ 文件 | 可能架构耦合 |
### 9.3 保持概念可理解
**好的概念**: 大纲即法律、设定即物理
**坏的概念**: LOD/Tick 帧交接、债务利息
金融隐喻在工程领域是好的，但在创意领域可能让用户困惑。
### 9.4 渐进式演进而非大爆炸
| 演进方式 | 风险 |
|---------|------|
| 渐进式 | 低风险，可能路径不优 |
| 大爆炸 | 高风险，可能推翻重来 |
---
## 10. 结语
NovelMaster 项目是一个**有价值的实验**——它探索了如何用工程化方法解决 AI 创意写作的问题。在演进过程中，我们学到了：
1. **Harness Engineering 的核心是约束，而非复杂**
2. **从简单开始，保持可理解性**
3. **渐进式演进优于大爆炸重构**
4. **概念隐喻需要与用户领域匹配**
当前系统的复杂度过高，但它的核心思想——**用约束引导 AI 创意**——是正确的。未来的改进方向应该是**简化架构、保留核心思想**，而不是继续增加复杂度。
---
## 参考资料
- `NOVELMASTER_ENGINEERING_REPORT.md` - 完整工程架构文档
- `noma/FIXES.md` - 修复记录 (v5.5.5, v2.0)
- `noma/docs/architecture.md` - 架构说明
- `noma/docs/core_engine.md` - 核心引擎说明
---
*文档版本: 1.0*
*撰写日期: 2026-04-02*
*项目版本: NovelMaster (Noma) 5.0*
本文作者：ZKCOI
文章名称：ClaudeCode下Harness Engineering，工程化尝试长篇网络小说创作
文章链接：https://www.zkcoi.com/365up/ai-agent/4518.html
本站资源仅供个人学习和交流，如若转载，请注明出处，详见《免责声明》。
微信扫一扫 
支付宝扫一扫 
