|
|
@@ -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 不支持）
|
fanghanjun