# 鲸灵工坊能做什么

[English](./features.md) | **简体中文**

工坊的每一项能力，一部分一部分地讲。简短的版本在 [README](../README.zh.md)；带截图一步步走的在[新手教程](./tutorial.zh.md)；为什么这样设计，见 [design.zh.md](./design.zh.md)。

- [你会得到什么](#你会得到什么)
- [它怎样融入 Harness](#它怎样融入-harness)
- [设置一览](#设置一览)
- [一本书在磁盘上的样子](#一本书在磁盘上的样子)

## 你会得到什么

**一本书一个正史。** 一个项目就是一个普通目录：凡是人写的东西都是 Markdown（人物卡、世界观条目、文风、章节），结构与机器记忆是 JSON。在工坊里改、用你自己的编辑器改、让 Agent 改，三者看到的是同一批文件，也适合用 git 管理。

**有"人"的设定集。** 人物卡不只是小传：还有结构化的人格（带强度的特质、按优先级排列的价值观、说话习惯、绝不会做的事、压力下的反应）、人物关系、生命周期状态、绘图用的外貌描述和配音设置。世界观条目分级——核心设定始终随上下文提供，细节按相关性取用。

**群像调度。** 人物卡上没有"活跃 / 已死亡"这样的标签——一本书不是一条直线，一个词说不完一个人。每个人有一份**履历**：哪一章登场、哪几章在场、哪里离开或死去；它是从各章的收录里读出来的，沿着一条剧情线读，换一条线就是另一份（这条线上死了的人，在更早分出去的那条线上还活着）。"人物"页把和人有关的都放在一处——每个人的人物卡（大幅立绘在左，身份、性格、关系、配音在右），所有人的履历排成的一张表（在场 / 登场 / 离开 / 死亡 / 计划出场 / 计划了却没出场）和关系图——并会提醒：谁消失太久了、哪份章纲还在安排已死之人、哪个主要人物还没有弧光（提醒可以收成一行，也可以隐藏）。

**随篇幅增长的记忆。** 每写完一章，分析模型提取摘要、硬事实、每个人物在章末的状态、新出现的实体以及线索的推进；每十章汇总成一段"篇章摘要"。之后每次调用都会现场打包上下文，方式是**前情梗概 + 窗口里塞原文**：离这一章最近的若干整章一字不差地给（预算默认是模型上下文窗口的一半，按整章取），更早的每章一行梗概，再加上检索到的相关旧段落（关键词检索，可选向量检索混合排序）；稿子装得下时就是全文。重写中间的章节时，**它后面已经写好的章节也一并给**，这一章必须接得上。整个请求的排列为模型服务端的前缀缓存而设计：写下一章时，几十万 token 的前文里只有末尾多出一章，其余命中缓存——命中了多少记在用量里。

**文风是一等公民。** 文风档案包含视角、时态、基调、用词、节奏、意象、对白习惯、必须遵守的规则、禁用清单和范文。可以从你喜欢的文字里提炼，可以先试写一段听听笔触，也可以每本书换一套。

**五种改书的方式**——对应作者心里的几种"模式"：

| 你想…… | 在工坊里 | 通过总编 |
|---|---|---|
| 推演接下来发生什么（大纲推演） | 大纲 → 推演（后续章节、节拍、假设分支）；可以从任何一章之后推演，并选择接着往后、**替换**其后的大纲，或**另开一条剧情线** | `novel_derive` |
| 改一小段（局部修改） | 写作页选中文字 → 润色 / 扩写 / 精简 / 按你的要求改 | `novel_revise scope=passage` |
| 重做一章 | 写作页 → 按要求修改整章 | `novel_revise scope=chapter` |
| 改贯穿全书的东西（全文修改） | 审校 → 审校和修订：写一句要求，点“修订” | `novel_revise scope=lead`（或 `scope=book`） |
| 改世界观或人物，并同步到正文（世界观修改 / 人物修改） | 审校 → "同步一条世界观变更 / 一次人物变更" | `novel_bible` + `novel_revise scope=book` |

修订以**提案**的形式出现，带差异对比，由你采纳或放弃。每次生效的改动都会先给旧稿存一份快照，任何历史版本都可以对比与恢复。

**剧情图：故事可以不止一条路。** 大纲的分卷是**主线**；主线之外可以有别的剧情线——策划推演出的另一种走向、幕间里演出来的一段、大纲被重写之前的旧安排。一条线从某一章之后分出（带着一句"分叉处的抉择"），可以再汇入另一条线，于是剧情是一张图，"大纲 → 剧情图"把它画出来：主线带星标，点任何一站、任何一条线就能操作——改名、汇入、搁置、删除，或者**设为主线**（原来那一段自动变成一条线，不丢稿）。写下一章时可以选走哪条线；阅读页读到分叉处，下面给出的是几条路。线上发生的事留在线上：在支线里死掉的人，在书里并没有死。

**一键与批量。** 凡是"对很多章做同样的事"都是一个任务：**演出 → 一键制作**把选中的章节从脚本、配音、声音、分镜、画面一路做到成片；**写作 → 批量写作**一章接一章地写（缺节拍的先推演，写完一章收录一章）；**插图 → 批量绘制**先画人设图和场景设定图，再照着画立绘、插图和封面。只补缺的，所以中断或部分失败后再点一次就是续做；一步失败只影响依赖它的步骤；每章每步的进度在一张表里。同时发出多少请求由四道全局闸门决定（语音、图片、声音、文字，默认 8，最多 256），服务限流时自己降速、重发、再升回来，并且明说。

**篇幅可以给预算，也可以不给。** 一章可以填一个建议字数，一本书可以填一个默认值；都不填，就由写手根据章纲和这本书已有章节的长短自己判断——工坊不替你编一个数。

**从已有稿件一键导入。** 给它一份已有的稿子（`.txt` / `.md`，UTF-8 或 GBK）：一位编辑 agent 先去读原文、弄清标题的写法、清掉网页留下的杂质，找出它真正的章节；然后逐章收录、把人物归并成人物卡、整理世界观条目、理清它们之间的关系（哪个地方在哪个地方里面、谁住在哪、属于哪一家，地点在故事里的建成与衰败）、重建大纲与线索、提炼文风，并定下这本书的画风。

**读，也可以听——同一页。** 认真排版的阅读器：内嵌插图、主题、字号，以及选中文字后的工具条——"去修改"、"配图"、"和总编讨论"。顶上的开关在**看**和**听**之间切换：听的时候正文不变，正在念的那一句在文中亮起，点任何一句就从那里开始播，一章听完接下一章。作者在同一页上方还有有声版的制作台。

**人物和世界，也是拿来看的。** "观看"里除了正文还有两半：**人物**——所有人按戏份排开，主角大幅，点进去是一个人的整页：大立绘（立绘 / 人设图 / 各套造型可切换，点开看原图）、外貌、性格、来历、这一路（哪一章登场、经历了什么、在哪里离开），和他属于哪一家、住在哪、手里有什么；**世界**——从一座城、一户人家点进去，里面有什么、谁在那里，每一处有它的设定图和写下的文字；有设定图的地方，图就是一个可以点的**场景**：园子里的各处院落、住在这里的人直接标在画面上，点一下就进去（作者可以把这些按钮拖到画里对应的位置钉住）；拉动时间轴，看故事进行到某一章时的样子。每一页右上角的"编辑"一步到这样东西的编辑页，编辑页上的"观看"一步回来。手机上、发布出去的网站上看到的是同一套页面——只带读者该看到的（正文已经写到的人和地方；动机、秘密、备注这些留在作者这边）。

**在手机上读。** 阅读页里点一下手机图标，这本书就开放给同一个 Wi-Fi 下的手机和平板：扫码或输入地址，看和听两种模式都在。默认关闭、逐本开启、只读，地址里带一段可以随时更换的随机口令；模型、密钥和没分享的书都碰不到。

**演出。**

- *插图*——选中一段文字，配一张图，直接嵌在这段之后。全书保持同一种样子，而且没有任何一处是藏起来的：每本书一份**画风**（写在 `novel.json` 里，画图的地方就看得到、改得了）；一份**"不要出现"清单**，写这个世界里没有的东西；每个人物一段**外貌**——写手照它写，每张图也照它画；以及一张**人设图**——正面、侧面、背面三视图——之后每一张有此人的图都把它当参考图一起交给模型。多套服饰各有从主人设图衍生出来的人设图，常去的地点有场景设定图；每张图都记着自己的提示词是由哪几部分拼成的。
- *有声剧*（就是阅读页的"听"）——导演把一章切成旁白、对白和心声，标出每句是谁说的、带什么情绪，并标注场景环境音。**声音表**让每个说话的人——有人物卡的，和没有卡的路人——全书、跨章、连幕间都用同一个声音。每一句合成后都会被**听检**：没念完、没声音，或者明显不像这个人的声音，就自动重念，留下最好的一次；所有句子统一音量。环境音（雨、酒馆、夜、紧张……共 18 种）由浏览器实时合成。语音服务可插拔：Qwen Omni 实时接口（WebSocket）、阿里云百炼 Qwen-TTS（HTTP，支持声线设计）、任意 OpenAI 兼容的 `/audio/speech`。
- *有声漫*——与有声脚本绑定的分镜，人物形象前后一致，配合缓慢的镜头运动和语音播放。分镜切多细由你定：精简、适中、细密，或交给分镜导演自己判断，还可以给一个格数上限；长段旁白中途也会换画面。
- *成片*——把一章做成一个视频文件，由**后期 agent** 来剪：这一章已经做好的配音、音效和分镜画面只是素材，工坊把它们排在一条时间线上交给它，它用命令行（ffmpeg）自己写脚本、剪、检查，再把 MP4 交回来——过了验收才收（有画面、有声音、时长对得上、没有大段黑屏）。它做不好时可以叫外援（Claude Code / Codex）。你可以用自己的话提要求：节奏、字幕、片头。
- *幕间*——下场扮演故事里的某个人物（或只当导演），其他人物由导演模型实时演出：背景、立绘、配音、环境音、选项——一部现场生成的视觉小说（Galgame）。幕间不会影响正史，除非你让写手把它写成一章；否则可以留作番外，或直接作废。

**声音设计。** 有声脚本除了台词，还安排每个场景听得到什么：环境底声、音效、配乐。它们作为注释显示在正文旁边（读的时候也看得到，给读者气氛），也可以由声音模型逐处生成、垫在人声下面——语音用百炼的音频生成模型时不需要另配模型。旁白不再一段一录：相邻的旁白合成一口气念的大段，夹在对白之间的"他说"默认不念。

**看得见模型在想什么。** 写作和其他任务进行时，模型的思维链（开源模型）或思维链摘要（闭源模型）可以边想边看。

**加得上去的，就删得下来。** 章节可以在写作页直接删（正文先存一份版本）；有声脚本的一句、一整份脚本，分镜的一格、一整份分镜，一章的审校意见，一章的成片，都有自己的删除——对话里让总编做也一样。

**写到哪，推演到哪。** 写作页里就能让策划推演后续章节（看过方案再加入大纲）和本章节拍，不用绕去大纲页。

**总编有自己的手，但只有一条路。** 作者口述的一句话、一个名字、一处事实，总编用 `novel_edit` 原样改，不绕写手；该"写"的仍然交给写手。任何改动都留版本、重新收录记忆、记进总览页的"改动记录"，改过正文的可以一键撤销。总编想绕过工坊直接改书的文件会被拦下并指到正确的工具；工坊之外对文件的改动也会被发现、记录、补收录。

**群像里的小人物。** 正文里有名字但没立卡的人（路人甲、店员、"那位太太"）汇总在"人物 · 龙套"里：值得跟踪的立卡，其实是某个人物别名的并过去，其余不管。人物列表默认显示定妆照，也可以切成极简。

**在手机上不只是读。** 分享给手机的书可以设成"仅阅读"或"可编辑"：可编辑时能在手机上改正文、玩幕间；有声漫也能在手机上看。

**加密。** 一本书可以整本加密：正文、设定、记忆、图片、音频在磁盘上只剩密文，连文件名也加密。**新建的时候就可以加密**——起草和导入的内容从第一个文件起就直接写成密文。用密码或这台电脑的系统解锁（触控 ID / 电脑密码）打开；锁着的时候连总编也看不到。手机第一次读要输密码。**关于这本书的对话也随书上锁**：和总编聊这本书的对话、各个角色为它跑的记录，在书上锁时从 DSH 的会话库里拿走并加密，解锁时原样放回、可以接着聊。

**导出**为 Markdown、纯文本、HTML 或 EPUB。

## 它怎样融入 Harness

写小说在这里就是和总编对话，书摊开在对话旁边。

- 一个 **Agent 预设**"小说家 Novelist"：选择它的会话获得总编人格、26 个 `novel_*` 工具、随对话携带的项目摘要、`/novel` 指令和 5 份工作流技能。其他会话不受任何影响。
- **班底是这场对话的子智能体。** 场记、策划、导演、后期的每一次运行都通过 DSH 官方的委派接缝（`ctx.subagents`）挂在发起它的对话之下：继承这场对话的工具、skill 和权限模式，登记在对话标题栏的子智能体目录里，全过程可查。没有专门工具的活，总编用 `novel_crew` 用话交给某个角色（"让策划查查民国上海的邮政，给第四章想两个桥段"）。
- **外援用的是 DSH 自己的子智能体。** 装上 `@deepseek-ai/dsh-subagent-claude-code` 或 `@deepseek-ai/dsh-subagent-codex`，后期剪视频时就能把自己做不好的活交给 Claude Code / Codex——预设里已经挂好了官方的 `@deepseek-ai/dsh-tool-subagent`，没装时什么也不发生。
- **对话就是操作界面**：工坊里每个页面能做的事，都可以直接在对话里说——"把这本 epub 导进来接着写"、"第三章的敲门声改成电话铃"、"给沈蘅画张立绘"、"打开大纲给我看"、"用百炼把配音配好"。总编会自己调用对应的工具，需要你看的时候把那个页面打开给你。
- 会话右侧栏的**"鲸灵工坊"标签页**：书就在对话旁边，总编一开工它就自己打开。总编做的事实时可见（写手写的章节会流式出现在编辑器里），你选中的任何内容都能一键带进对话。想专心读写时点**全屏**（工坊顶栏最右，或侧栏自带的全屏键），再点一下回到对话旁边。
- 各个页面——人物、设定、大纲、写作、观看（正文：文字 / 脚本 / 看，底下一个播放条；人物；世界）、审校、演出、设置——留给你**亲手细调和审阅**：模型做了什么，都能在这里看到、改掉、退回。凡是要等一会儿的事，按下去的按钮会写着它正在做什么，页面底部有一条"进行中"，列出这本书正在跑的每一件事和停止键。
- 左侧栏的**"鲸灵工坊"页面**：书架、设置和任何一本书，不需要开对话。
- 对话记录里的**工具行**：写明"让哪个模型做了什么"，并能一键跳到工坊里对应的位置。
- **一场对话，一本当前的书。** 对话同一时间只在一本书上，旁边的工坊显示的也是这一本。在工坊里换书，对话跟着换——总编会被明确告知现在是哪本、之前谈的是哪本；让总编换书，工坊也跟着换。只想碰一下另一本书时，任何工具都可以带上 `book` 点名。
- **文字模型就是 DSH 的模型**——在 DSH 的"设置 → 模型"里填过 key 的，或者用登录接入的（比如 ChatGPT 订阅：DSH 自带登录，工坊引导页的卡片替它点开）；想用哪家就去那里接，工坊里只管给每个角色选。工坊自己配的只有它特有的：画图的、配音的、做检索的模型，密钥存进 DSH 的凭据库。
- **用量与成本。** 工坊每调用一次模型都会记账——各个角色的 token、图片张数、语音分钟数——按模型、作品和日期汇总；填上你实际付的单价，就能看到钱花在哪。

适用于 Web 界面（`dsh web`）和桌面版。

## 设置一览

每个字段的完整说明见 [configuration.md](./configuration.md)。

**逐项自定义**：

- **模型**——开始只有两行：写手模型，和班底（场记、策划、导演、后期）共用的一个编排模型；每一行可以跟随对话模型，或选用 DSH 里配好的任何一个模型。打开右上角的"高级选项"才是逐个角色：模型、思考强度、温度、输出上限，以及班底角色是作为 agent 干活还是一问一答的普通调用、能用哪些工具（自己的 / DSH 的全部）、一次最多几步，都在这个角色自己的那一块里。外援（Claude Code / Codex）和 ffmpeg 装没装也显示在这里。
- **跟这本书，还是全局**——模型和班底的工作方式可以对所有的书生效，也可以只跟着当前这本书（写进它自己的 `novel.json`，书到哪里跟到哪里）。
- **推荐配置**——各家服务用哪个模型不写在代码里，而是随每个版本发布的 `recommended.json`。原先就是推荐值的设置会跟着新一版走（工坊会说明换了什么，可以改回去）；不想跟随，关掉开关即可。
- **上下文**——`自动`（前情梗概 + 窗口里的原文，装得下就是全文）、`只用检索` 或 `用满窗口`；原文预算（不填 = 模型窗口的一半）；续写时原样携带多少前文。页面上直接显示每个角色的模型窗口多大、会带多少原文。
- **并发**——语音、图片、声音、文字各自同时发出多少个请求：默认 8，最多 256，全局一处。
- **图像**（可选）——OpenRouter 的 `/images`（GPT Image、Gemini、Grok、Seedream、FLUX…）、OpenAI 兼容的 `/images/generations`、阿里云百炼（Qwen-Image、万相、Z-Image），或者 ChatGPT 订阅。
- **语音**（可选）——百炼音频生成 `qwen-audio-3.1-tts-next`（用文字描述音色，为每个人物生成并沿用一段参考音）、Qwen Omni 实时接口、百炼 Qwen-TTS（可设计声线）、OpenRouter 的 `/audio/speech`，或 OpenAI 兼容的 `/audio/speech`。
- **语义检索**（可选）——任意 OpenAI 兼容的 `/embeddings` 接口，与关键词检索混合排序。

**密钥**直接填在设置页里，和其他设置一起保存。它存进 Harness 的凭据库（按接口域名一条记录），不会写进设置文件，也不会回传到页面；同一个服务的各项能力共用一个密钥，填一次就够。习惯用环境变量的话，`DASHSCOPE_API_KEY`、`OPENROUTER_API_KEY`、`OPENAI_API_KEY` 会被自动识别，也可以给某一项指定别的变量名。

**ChatGPT 订阅**——一键接上：引导页的“ChatGPT 订阅（Plus / Pro）”卡片用 **DSH 自己的 ChatGPT 登录**（它的模型适配器给 `openai-codex` 这条路由带的登录，DSH 的页面里没有入口，工坊替它点开），登录一次，就把这条路由加进 DSH 的模型设置、写手和班底配上 GPT 模型（默认都是 GPT-6.1 Sol；DSH 的目录里还没有它的，一键配置把它加进这条路由）、插图用订阅里的 GPT Image，第一次配置时 DSH 新对话的默认模型也换成它（可以不勾）。登录由 DSH 保存和续期，工坊不另存；卡片上可以换账号、退出登录。装了 [Codex Connect](https://github.com/franksong2702/dsh-codex-connect) 插件的，用它自己的登录（同一条路由，二选一）；本机的 Codex CLI 用 ChatGPT 登录过的，插图也能走它。订阅里没有向量接口和语音合成接口，这两项请用上面的服务。一步步的说明见[用 ChatGPT 订阅](./chatgpt.zh.md)。

## 一本书在磁盘上的样子

```
my-novel/
├── novel.json                 书名、故事核、语言、目标字数、当前文风
├── outline.json               分卷 → 章节 → 节拍，线索与伏笔，以及主线之外的剧情线
├── bible/
│   ├── characters/<名字>.md   front matter（人格、履历、外貌、声音）+ 备注
│   ├── world/<名字>.md        分级的世界观条目
│   └── styles/<名字>.md       文风档案
├── manuscript/ch001.md …      正文，一章一个文件
├── assets/                    图片与音频
├── export/                    导出的成书
└── .novel/                    机器记忆：章节收录、历史版本、提案、审校结果、
                               有声脚本、分镜、幕间记录、检索索引
```

详见 [docs/project-format.md](./project-format.md)。