docs: add sub_agent params alignment design spec

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-09-01 15:08:51 +08:00 · 2026-04-15 21:47:06 -07:00
parent 17d1f9b967
commit 62f48a14e3
1 changed files with 132 additions and 0 deletions
@@ -0,0 +1,132 @@
+# sub_agent 工具参数对齐设计
+
+## 目标
+
+让 sub_agent 的 5 个子智能体（architect/writer/auditor/reviser/exporter）的参数与 pipeline runner 方法对齐，消除硬编码和参数丢弃。
+
+## Scope
+
+**A 层：参数暴露**。只对齐已暴露的 5 个 agent，不新增 pipeline 方法的暴露（writeDraft、planChapter、repairChapterState 等留后续）。
+
+## 方案
+
+**方案 3：扁平扩展 + description 约束**。在现有 `SubAgentParams` 上新增字段，每个字段的 TypeBox `description` 标注适用的 agent，模型通过 tool schema 的 description 知道约束。
+
+## SubAgentParams schema 变更
+
+现有字段：
+- `agent` — 子智能体类型（不变）
+- `instruction` — 自然语言指令（不变，行为改变见下）
+- `bookId` — 书籍 ID（不变）
+- `chapterNumber` — 目标章节号（已有，auditor/reviser 适用）
+
+新增字段（全部 `Type.Optional`）：
+
+| 字段 | 类型 | description | 适用 agent |
+|------|------|-------------|-----------|
+| `title` | `String` | architect only: 书名 | architect |
+| `genre` | `String` | architect only: 题材 (xuanhuan, urban, mystery, romance, scifi, fantasy, wuxia, general 等) | architect |
+| `platform` | `String` | architect only: 目标平台 (tomato, qidian, feilu, other) | architect |
+| `language` | `String` | architect only: 写作语言 (zh/en)，默认 zh | architect |
+| `targetChapters` | `Number` | architect only: 目标总章数，默认 200 | architect |
+| `chapterWordCount` | `Number` | architect/writer: 每章目标字数，默认 3000 | architect, writer |
+| `mode` | `String` | reviser only: 修订模式 (spot-fix/polish/rewrite/rework/anti-detect)，默认 spot-fix | reviser |
+| `format` | `String` | exporter only: 导出格式 (txt/md/epub)，默认 txt | exporter |
+| `approvedOnly` | `Boolean` | exporter only: 仅导出已审核通过的章节 | exporter |
+
+## 各 agent 行为变更
+
+### 1. architect
+
+**现状**：`pipeline.initBook({ id, genre: "general", title: "", language: "zh" } as any, { externalContext: instruction })`
+
+**改为**：
+```ts
+const now = new Date().toISOString();
+await pipeline.initBook({
+  id,
+  title: title ?? "",
+  genre: genre ?? "general",
+  platform: (platform as any) ?? "other",
+  language: (language as any) ?? "zh",
+  status: "outlining",
+  targetChapters: targetChapters ?? 200,
+  chapterWordCount: chapterWordCount ?? 3000,
+  createdAt: now,
+  updatedAt: now,
+}, { externalContext: instruction });
+```
+- 去掉 `as any`，构建完整 BookConfig
+- `instruction` 继续作为 `externalContext` 传递
+- 建书后从 story_bible.md 回填 title（已有逻辑保留）
+
+### 2. writer
+
+**现状**：`pipeline.writeNextChapter(bookId)` — wordCount 丢弃，instruction 丢弃
+
+**改为**：
+```ts
+const result = await pipeline.writeNextChapter(bookId, chapterWordCount);
+```
+- `chapterWordCount` 透传为 `wordCount` 参数
+- `instruction` 透传为 pipeline config 的 `externalContext`（需要在 writeNextChapter 调用前设置）
+- `chapterNumber` 不适用于 writer（writeNextChapter 总是写下一章），schema description 已标注
+
+### 3. auditor
+
+**现状**：参数齐了，返回值只有 issueCount
+
+**改为**：
+```ts
+const audit = await pipeline.auditDraft(bookId, chapterNumber);
+const issueLines = audit.issues
+  .map(i => `[${i.severity}] ${i.description}`)
+  .join("\n");
+return textResult(
+  `Audit chapter ${audit.chapterNumber}: ${audit.passed ? "PASSED" : "FAILED"}, ${audit.issues.length} issue(s).\n${issueLines}`
+);
+```
+- 返回完整 issues 列表（severity + description），让 agent 能判断下一步操作
+
+### 4. reviser
+
+**现状**：mode 靠正则从 instruction 提取，anti-detect 不可达，instruction 丢弃
+
+**改为**：
+```ts
+const resolvedMode: ReviseMode = mode ?? "spot-fix";
+await pipeline.reviseDraft(bookId, chapterNumber, resolvedMode);
+```
+- `mode` 直接从 schema 字段读取，去掉正则逻辑
+- `instruction` 透传为 `externalContext`（等同 CLI 的 `--brief`）
+
+### 5. exporter
+
+**现状**：纯 stub "Coming soon"
+
+**改为**：使用 `project-tools.ts` 中已有的 `exportBookToPath` 逻辑：
+```ts
+const exportFormat = format ?? "txt";
+const onlyApproved = approvedOnly ?? false;
+// 调用 StateManager 的导出逻辑
+```
+- 支持 txt/md/epub 三种格式
+- 支持 approvedOnly 过滤
+- 返回导出文件路径
+
+## 系统提示词更新
+
+更新中英文系统提示词，说明每个 agent 的可用参数：
+- architect: title, genre, platform, language, targetChapters, chapterWordCount
+- writer: chapterWordCount（wordCount 覆盖）
+- auditor: chapterNumber
+- reviser: chapterNumber, mode
+- exporter: format, approvedOnly
+
+## 不在 scope 内
+
+- 新增 sub_agent 类型（planner、repairer、syncer 等）
+- writeDraft / planChapter / composeChapter 等方法暴露
+- fanfic / import 流程
+- temperatureOverride（CLI 也没暴露）
+- writer 指定章节号（writeNextChapter 不支持）