# 草苔 StoryMoss 用户指南

> 面向普通用户的产品使用说明。本文档基于当前版本界面截图整理，后续功能更新将持续追加。
> 版本：v0.30.48 | 最后更新：2026-07-31

---

> 💡 **v0.30.46-48 更新提示**：修复了一批影响创作流程的问题——①新建小说后正文有时没有保存、重启后空白、角色/世界观/伏笔等资产缺失的问题已修复；②新建向导在选择世界观后"角色谱生成"可能无提示地退回上一步的问题已修复（此前模型返回格式不兼容时静默失败，现在会记录日志并正确提示）；③向导第一步长时间显示"策略加载失败"其实是仍在加载，现在会显示加载动画；④拆书上传失败时不再显示 `[object Object]`，会显示真实原因（如"需要 Pro 订阅"）；⑤没填故事简介就点"快速创作"时会先弹出说明再执行。
>
> 💡 **v0.30.45 更新提示**：修复了文思活跃模式续写时返回 AI 思考过程（思维链）而非小说正文的问题（提示词泄露）。根因是当使用推理类模型时，模型把全部生成预算花在了内部"思考"上，导致正文为空，而系统错误地把这段思考过程当作正文返回给你。现已修复：不再把思考过程当正文兜底返回；生成预算提升给正文留足空间；新增对裸思维链的检测与剥离；写作提示词明确禁止输出推理过程。界面无变化。
>
> 💡 **v0.30.44 更新提示**：修复了开启文思活跃模式后续写报"生成过程异常结束，未收到有效内容"的问题。根因是生成完成后、内容写入编辑器前的短暂窗口内，一个内部标志被过早清除，导致后台活动检测误判生成已异常结束并弹出错误诊断；同时活跃模式下续写内容本应直接追加到正文，却错误地走了逐字打字机动画。现已修复：内部标志在内容实际交付后才清除，活跃模式续写直接追加到编辑器正文。界面无变化。
>
> 💡 **v0.30.43 更新提示**：修复了续写/编辑后关闭应用或切换章节时，最后输入的内容可能丢失的问题。根因是保存函数读取了滞后的内容快照（编辑器有 200ms 防抖延迟）而非编辑器实际内容，以及后台自动提交时用旧内容覆写编辑器但不更新快照。现已修复：保存时直接读取编辑器实际内容，后台更新时保护未保存的输入。
>
> v0.30.42：修复了创建新小说时"世界观生成失败，请重试"的问题。此前 LLM 成功返回了世界观内容，但模型把 JSON 包裹在 markdown 代码块（```json ... ```）中、或在字符串里直接换行/使用裸双引号，导致程序解析 JSON 时静默失败（没有任何错误日志）。同时发现提示词要求输出"concepts"数组但代码读取"world_buildings"，字段名不一致。现已通过健壮的 JSON 提取（自动剥离代码块围栏、修复未转义换行）、修正字段名、并在提示词中明确禁止代码块包裹来修复。界面无变化。
>
> 💡 **v0.30.41 更新提示**：修复了续写内容被假阳性去重静默丢弃的问题。某些模型（如 deepseek-v4）会在生成内容开头回显用户输入的写作指令（如"续写"），导致打字机动画首帧被误判为与已有正文重复而静默丢弃，用户看到"生成过程异常结束，未收到有效内容"。现已通过最小长度守卫（短文本不做去重检查）和指令回显剥离（自动去除生成内容开头的指令回显）修复。界面无变化。
>

> 💡 **v0.30.40 更新提示**：修复了幕后"代理工作室"页面不显示代理活动记录数据的问题。此前只有在创世或续写进行时打开代理工作室才能看到实时活动，如果在运行结束后才打开页面，则会一直显示"暂无活动"。现在打开页面时会自动从数据库加载最近运行的代理活动记录（黑板条目、运行状态、时间线），并可通过下拉框切换浏览历史运行。
>

> 💡 **v0.30.39 更新提示**：修复了续写内容不按故事大纲推进剧情的问题。此前续写时虽然系统知道故事大纲，但缺少"已推进进度"指针，无法判断当前剧情推进到了故事大纲的哪个节点，导致续写内容偏离大纲、原地踏步或仅复述设定。现在续写时会确定性注入"已推进进度"（最近 3 章的章节大纲）+ 故事大纲硬约束 + 显式调和指令，确保续写严格围绕故事大纲推进到下一节点。界面无变化。
>

> 💡 **v0.30.38 更新提示**：修复了续写时偶尔输出"编辑器元评论"而非小说正文的问题。此前在某些情况下（通常是多次续写后），续写产出的内容会在正文后紧接一段 AI 文学编辑的元评论（如"好的，作为一名专业的文学编辑，我将根据您提供的问题列表和总体评分，对您的文本进行深度重塑…"），而非正常的小说续写内容。根因是意图分类的提示词示例遗漏了一个字段，导致系统误判续写请求不需要正文输出，从而跳过了安全净化步骤。现已从分类源头、提示词示例和安全门控三层修复。界面无变化。
>

> 💡 **v0.30.37 更新提示**：修复了创作或生成失败时，错误提示显示 `[object Object]` 而非可读错误信息的问题。此前当智能创作、生成草稿/大纲、幕后快速创作/AI 向导、文思生成、修稿/审稿/定稿等操作失败时，弹出的提示框只显示一串 `[object Object]`，看不出具体原因。现在这些错误提示会正确显示后端返回的错误信息（如"模型响应超时""写作前检查未通过"等），方便你定位问题。界面无变化。
>

> 💡 **v0.30.36 更新提示**：修复了首次创建新小说时，输入框的创世指令不会被保存到历史记录的问题。此前当你第一次写新小说（无已有作品）时，你输入的创世指令不会被记住，之后按 `↑` 方向键也无法调取。现在创世成功后，你的创世指令会自动保存到新故事的历史记录中，随时可以按 `↑` 召回。界面无变化。
>

> 💡 **v0.30.35 更新提示**：优化了创世（写新小说）的响应速度。此前创世可能卡满 10 分钟超时且看不到首章--根因是「编辑审计质检」在首章生成后**同步阻塞**，被总超时砍掉导致无产出。现在主创写完首章后会**立即显示到编辑器**（约 5-6 分钟可见），编辑审计质检改为**后台异步进行**（独立 300 秒，不影响总流程）。质检完成后会弹出一个 **toast 通知**告知结果：通过（绿色）/ 降级放行（橙色，质检超时或失败但首章已保留）/ 不合格（橙色，列出具体问题并建议重新创世）。后台质检期间你可以继续写作，不合格时也不会自动重写，由你手动决定是否重新创世。界面无变化，创世不再卡死。
>

> 💡 **v0.30.34 更新提示**：进一步修复了续写内容丢失问题。上次修复（v0.30.33）后仍有丢失，根因是多次续写时保存操作并发执行导致「较早的内容覆写较晚的内容」（数据库被静默回退，编辑器看起来正常但重启后丢失）。现已将所有保存操作**串行化**（排队执行，最后一次保存总是最新内容）。同时修复了 AI 修稿后内容未同步保存的问题，并将关闭等待时间从 3 秒提升到 6 秒（确保数据库写完再退出）。界面无变化，续写内容不再丢失。
>
> 💡 **v0.30.33 更新提示**：修复了多次续写后关闭应用再重启时续写内容丢失的问题。此前 AI 追加的续写内容仅在 2 秒防抖后保存，文思活跃连续续写时防抖会被反复重置导致「永不出火」，关闭应用时后端直接退出不给保存机会。现已修复：①关闭应用前会先保存未写入的内容再退出；②AI 每次追加续写后立即保存（不再等 2 秒）；③切换章节前也会先保存当前内容。界面无变化，续写内容不再丢失。
>
> 💡 **v0.30.31 更新提示**：续写内容现严格围绕世界观设定、故事大纲与场景大纲展开，并保持剧情推进方向。修复了此前续写「偏离大纲、世界观不体现、剧情原地踏步」的根因：幕前续写的故事大纲、场景大纲与世界观设定现在会**确定性注入**到写作提示中（不再依赖中间合成步骤是否保留），同时会读取最近 3 章已推进进度作为方向指针，要求每章推进到故事大纲的下一节点而非复述前文。你在「世界构建」面板填写的概念、历史、规则与文化也会真正进入续写。界面无变化，续写质量提升。
>
> 💡 **v0.30.26 更新提示**：幕前输入简单创世指令（如"写一部现代间谍的长篇小说"）时，增强版 logline 不再以输入栏下方独立建议条形式出现，而是以内联幽灵文本紧跟在你已输入的内容之后。按 `→` 即可将灰色后缀追加到当前输入，再按 Enter 即提交“原输入 + 增强后缀”的组合文本。同时修复了偶发因意图分类误走续写路径导致的“分时模式预检未通过（缺少角色）”错误：系统会在无角色时自动创建占位主角，并基于输入文本兜底判断创世意图。
>
> 💡 **v0.30.23 更新提示**：修复了输入"写一部X小说"等创世指令时偶发被误分类为续写、弹出"请先选择作品"错误的问题。AI 意图分类提示词已去偏（不再受"是否已有故事"上下文影响），并新增正例引导；LLM 分类失败时的兜底也改为上下文感知（无故事时自动创世）。
> 💡 **v0.30.22 更新提示**：幕前输入简单指令（如"写一部科幻小说"）创世时，系统现基于 Erik Bork 的 PROBLEM 七元素框架自动生成强力 Logline（谁 + 催化事件 + 核心不可能的任务 + 失败后果），替换原始简单指令作为故事生成前提，故事大纲受 PROBLEM 七元素引导；Logline 持久化到故事并注入续写上下文。设置 -> 提示词 新增可编辑资产 `agency_problem_logline`（Logline 生成）与 `agency_problem_outline`（故事大纲增强）。
> 💡 **v0.30.12 更新提示**：修复续写时偶发返回内容审查报告而非正文的问题。
> 💡 **v0.30.11 更新提示**：AI 对你输入指令的理解更准了--幕前底部输入栏的意图识别由关键词匹配升级为 AI 意图分类（单次 LLM 调用判定是否新建小说/续写/润色等，并自动探测题材），减少「续写被误判成新建小说」之类的路由错误。界面无变化，体验透明。
> 💡 **v0.30.4 更新提示**：幕前底部输入栏的已发送指令现按故事隔离持久保存（最近 20 条），关闭窗口或重启应用后不丢失。按 ↑/↓ 浏览历史指令，按 -> 确认填充，与编码工具的命令历史一致。
> 💡 **v0.26.55 更新提示**：模型管理列表可直接「开启/关闭」模型。关闭后不再调用与探测；若关闭的是当前创作/活跃模型，会自动回退到其他已启用模型。

> 💡 **v0.26.54 更新提示**：设为「创作」的模型在偶发失败后仍会优先用于续写/正文生成；若暂时不可达，会短暂探测后自动回退其他可用模型，不会长期忽略你的创作模型设置。

> 💡 **v0.26.52 更新提示**：在设置中新增模型或设为「创作」默认模型后，幕前底部连接状态与后续 AI 生成会立即使用新配置，无需重启应用。

> 💡 **v0.26.50 更新提示**：在正文编辑器打字时，底部输入栏不应再自动进入「后台运行」；若生成卡住超过设置的前端超时，会弹出诊断卡片（可取消后重试）。知识图谱后台分析会在停笔约 30 秒后进行，不再与续写抢模型。

> 💡 **v0.26.49 更新提示**：续写会强制从当前正文末句接着写，不再另起无关开篇（例如章末在「找线索」，下一段却突然换场景重开）。

> 💡 **v0.26.59 更新提示**：完成 StoryForge → StoryMoss 品牌重命名，官网落地页 `https://ai.91z.net` 已上线；安装包文件名也已统一为 StoryMoss。应用内功能无变更，若此前因旧名导致下载或更新链接异常，请升级到本版本。
>
> 💡 **v0.26.57 更新提示**：后台「工作室设置 → 通用」新增「划分章节方式」，可选择按字数（留空默认 3000 字/章）或按情节自动划分；保存场景内容空闲约 30 秒后，仅对当前故事最新一章自动切分。故事管理页与当前故事指示条均支持「导出」，导出结果会弹出系统保存对话框让你选择本地目录，支持 txt、md、pdf、epub、html、json。后台「提示词注册表」新增「打开目录」按钮，可直接在文件管理器中查看本地 prompts 资源目录。
>
> 💡 **v0.26.48 更新提示**：应用内「检查更新」现从 GitHub 正式版 Release 下载（`latest.json`）。设置 → 关于 可手动检查；有新版本时右上角弹出更新卡片，下载完成后自动重启安装。

> 💡 **v0.26.46 更新提示**：创世时选中的创作方法论（雪花/高密度世界构建等）会真正注入世界观、大纲、角色、场景与伏笔的后台生成，不再静默失效。若题材目录无匹配画像，系统会自动生成并入库供后续复用。拆书分析会保存故事线摘要、作者与伏笔线索，长篇分块分析更稳定（12 小时上限与并发控制）。
>
> 💡 **v0.26.43 更新提示**：修复底部状态栏「准备上下文」等提示前图标显示为方框的问题，现已改为清晰的矢量图标。

> 💡 **v0.26.42 更新提示**：修复「续写下一段」后只出现 Tab 接受提示、看不到灰色幽灵正文、确认后也不追加的问题。接受上一段后立刻再续写现已正常显示待确认内容。

> 💡 **v0.26.41 更新提示**：场景管线「定稿」会写回**当前编辑的场景**（不再按章节号猜第一场）。故事合同「记忆」Tab 可同时看到知识图谱实体与记忆条目（统一读面）。
>
> **v0.26.40**：侧栏项带「热/温/冷/配」徽章；「诊断」组默认折叠；MCP 在 **设置 → 扩展**；知识图谱摘要进默认续写；生成链路可看资产覆盖率。
>
> **v0.26.39**：导航五组；数据洞察合并；设置多 Tab；拆书并发在拆书页；账号菜单进账号设置。

> 💡 **v0.26.45 更新提示**：创世首章会强制落地「开篇人物卡」——正文须出现具体主角姓名，并让读者开篇就明白主角要什么、阻力是什么（不增加创世等待时间）。
>
> 💡 **v0.26.44 更新提示**：创世（「新写一部XX小说」）会先铺设开篇骨架（主角目标与场景戏剧卡），再写第一章正文；目标约 30–90 秒返回。概念提示已加厚（冲突/主角/世界锚点），策略选择中文化，末世类优先匹配末世画像。
>
> 💡 **v0.26.38 更新提示**：后台「工作室配置 → 提示词」全面修复：展开条目可立即编辑（不再卡在 Loading）；「打开目录」用系统文件管理器可靠打开；「导出」支持「已覆盖」与「完整包」两种，并弹出保存对话框。页面新增「场景组合预览」，可查看续写/创世/审稿路径会用到哪些提示词并一键跳转编辑。Call 1 选出的方法论与条件注入器会自动进入生成路径，提升正文质量。

> 💡 **v0.26.34 更新提示**：修复后台「工作室配置 → 提示词」页面批量导入提示词覆盖失效的问题；新增「打开目录」按钮，可直接在系统文件管理器中打开当前使用的提示词资源目录；新增「刷新」按钮重新加载提示词列表。导出/导入按钮已移至页面标题栏。

> 💡 **v0.26.37 更新提示**：修复幕前顶部「保存中...」常亮与字数不随正文增长的问题。自动保存现已正确写入场景；AI 续写/追加后字数会即时更新。

> 💡 **v0.26.24 更新提示**：修复多次续写时正文重复、截断与质量退化。续写结果会自动清理模型自身的循环重复、剔除与已有正文重叠的复述段落，并裁掉超时截断留下的不完整短句。若续写内容仍与当前正文高度相似，系统会提示无需添加。

> 💡 **v0.26.19 更新提示**：创世流程（智能创作-创世）审计与优化。本章新增「创世流程可观测性」：后台世界观/大纲/角色/场景/知识图谱/合同等资产的生成失败不再被静默吞掉，而是累计记录到仪表盘「Genesis 运行记录」并在完成后通过状态栏提示「部分资产生成失败」。同时修复创世第一章与角色生成的若干架构问题（角色提示词此前拿不到世界观上下文），并加固框架级 mutex 中毒锁恢复。创世第一章正文仍由 AI 生成后**自动接受**进编辑器（无需按 Tab），用户可立即开始写作。

> 💡 **v0.26.18 更新提示**：进一步修复新写小说时第一章内容重复的问题。本版本加固三个残留竞态缺口：ChapterSwitch 事件内容为空时不再从数据库加载正文（避免与 AI 生成结果叠加）；Genesis 投递状态机不再因空内容误锁；selectChapter 咽喉点新增 delivered 守卫防止覆盖已投递正文。

> 💡 **v0.26.17 更新提示**：进一步修复 Windows 启动闪退（Issue #4）。v0.26.16 已避免 `init_db` 失败时的 panic；本版本将 SQL 数据库迁移文件打入安装包，并在数据库初始化失败时输出更详细的日志，便于定位权限或路径问题。若启动后功能不可用，请查看 `%APPDATA%\com.storymoss.app\logs\` 下的日志并通过 GitHub Issues 反馈。

> 💡 **v0.26.16 更新提示**：进一步根治新写小说时第一章内容重复的问题。本版本从生成侧与前端的两个独立根因进行结构性修复：生成侧检测模型输出自重复并在必要时重试；前端将 Genesis 自动接受流程改为三态状态机，避免多路径并发导致的内容叠加。同时修复了部分用户遇到的启动闪退问题（当应用数据目录不可写时不再 panic）。

> 💡 **v0.26.14 更新提示**：继续修复新写小说时第一章内容重复的问题。v0.26.13 已确认数据层与渲染层均未重复写入，但部分模型仍会生成「开头段落与结尾段落相同」的循环正文。本版本在正文进入编辑器前增加自重复清理：若检测到模型输出自身重复，会自动裁剪后半段/末段，避免用户看到重复内容。同时减少了幕前诊断日志量，缓解长时间写作后页面卡顿或崩溃。

> 💡 **v0.26.13 更新提示**：进一步修复新写小说时第一章内容「前一段分行、后一段挤成一大段」的虚假重复。日志确认数据层只写入一次，本次修复针对渲染层：生成状态结束时会立即卸载幽灵文本容器，避免空容器残留或复用旧内容导致「正文 + 幽灵文本」同框。若仍遇到异常，请通过「设置 → 反馈」或 GitHub Issues 提供截图/日志。

> 💡 **v0.26.12 更新提示**：修复了打开已有故事或新写小说后，幕前界面偶尔白屏崩溃的问题（角色数据未加载完成时的兼容性修复）；同时加固了订阅状态接口异常时的容错。创世流程与第一章重复问题在 v0.26.9–v0.26.11 已多次修复，本版本进一步提升稳定性。

## 一、产品概览

**草苔 StoryMoss** 是一款 AI 辅助小说创作桌面应用。它将创作流程分为两大空间：

| 空间                   | 作用                                  | 适合场景                 |
| ---------------------- | ------------------------------------- | ------------------------ |
| **幕后（Backstage）**  | 管理故事、角色、场景、世界观、AI 配置 | 规划、整理素材、配置模型 |
| **幕前（Frontstage）** | 沉浸式写作界面，专注正文创作          | 码字、与 AI 对话续写     |

核心思路：幕后把创作要素（人、事、地、世界观）结构化管好，幕前让你专注写字，AI 在需要时介入，不打断心流。

> 💡 **v0.23.63 更新提示**：本版本修复了推理模型（如 MN-Oblivion-26B-UNCENSORED）创世时报 `missing field 'title'` 的问题——推理模型在正文前输出的思考链里的花括号会被误当成 JSON 对象，现已先剥离思考链再提取。v0.23.63 修复了 JSON 尾部多余文本导致的 `trailing characters` 解析错误。v0.23.63 调用模型前先 5s 实时探测连接，自动跳过已失效的死模型，不再浪费 30-300s 等待超时。v0.23.63 根治了创世正文返回后前端页面崩溃与"准备上下文"活动卡死；AI 状态提示栏现在显示模型名称而非模型 ID。v0.23.63 根治了创建新小说 600 秒超时问题。v0.23.63 修复了 macOS 启动崩溃。

---

## 二、全局导航与共用界面

### 2.1 左侧导航栏

无论你在哪一页，左侧边栏始终可见，是应用的主要入口。

![仪表盘](product-screenshots/01_dashboard.png)

从上到下按分组依次是：

| 分组 | 按钮 | 作用 |
| ---- | ---- | ---- |
| — | **打开幕前写作** | 打开「幕前写作」窗口，进入沉浸式码字界面 |
| **创作** | 仪表盘、故事、代理工作室 | 首页总览、故事库与三代理协作实时视图 |
| **故事资产** | 场景、角色、世界构建、伏笔、知识图谱、故事合同 | 当前故事的结构化资产与合同 |
| **创作工具** | 技能、拆书 | AI 技能、参考书分析（MCP 扩展在设置） |
| **诊断** | 叙事分析、数据洞察、创作评估、学习中心、意图诊断、生成链路、日志、任务 | 分析、统计与诊断（默认折叠） |
| **系统** | 设置 | 模型 / Agent / 写作 / 提示词 / 外观 / 关于 / 账号 |

「数据洞察」内含用量、写作、功能使用三个子页（原「用量统计」「写作统计」与设置内数据统计已合并）。

点击任意导航项，右侧主区域会切换为对应页面；当前所在页面会以金色高亮显示。

### 2.2 底部状态区

- **当前编辑**：若已选择故事，底部会显示当前故事名、分类、章节数，点击可快速跳到「场景」页。
- **登录**：未登录时显示，点击弹出登录/账号面板。

### 2.3 顶部通知

- **连接状态**：若应用未能连接本地服务，顶部会出现红色提示条，点击「重试」可重新连接。
- **版本更新**：有新版本时，右上角会弹出更新提示，可选择「安装」或「忽略」。

---

## 三、幕后页面详解

### 3.1 仪表盘 — 创作工作室首页

![仪表盘](product-screenshots/01_dashboard.png)

这是你打开应用后看到的第一个页面。它承担"指挥中枢"的角色。

#### 界面元素

- **欢迎语**："欢迎回到创作工作室" + 每日随机创作格言。
- **快捷创建**：
  - **AI 创建故事**：让 AI 根据你的简单描述生成一个完整故事框架（含角色、场景、世界观）。
  - **手动创建**：从零开始，自己填写标题、简介、类型。
- **统计卡片**（v0.26.25 Phase 1 后已可点击）：
  - **故事**：当前共有多少个故事；点击跳转到「故事」页。
  - **角色**：所有故事中的角色总数；点击跳转到「角色」页。
  - **场景**：所有故事中的场景总数；点击跳转到「场景」页。
- **GENESIS 运行记录**：
  - 显示 AI 自动生成/拆解任务的运行历史。
  - v0.26.19 起，每条记录携带状态（pending/quick_done/completed/failed）、当前步骤、累计的非致命错误（如世界观规则写入失败、角色关系创建失败、知识图谱关系缺失、合同播种失败等）。若创世完成但部分资产未完整生成，状态栏会提示「部分资产生成失败，可在仪表盘查看详情」。
  - 若从未运行过，会显示"暂无 Genesis 运行记录"。
- **开始创作引导**：
  - 当还没有故事时，页面下方会出现"开始你的创作之旅"引导区。
  - 提供"AI 创建第一个故事"和"手动创建"两个入口。

#### 典型操作路径

1. 打开应用 → 看到仪表盘。
2. 点击 **AI 创建故事** → 输入一句话创意 → AI 生成故事框架。
3. 或点击 **手动创建** → 填写故事信息 → 进入「故事」页继续完善。

---

### 3.2 故事 — 管理你的所有作品

![故事页](product-screenshots/02_stories.png)

"故事"是所有创作的顶层容器。一本小说、一个短篇、一个剧本，都是一个"故事"。

#### 首次使用时的空状态

若还没有故事，页面主体为空白，提示你开始创建。创建方式有两种：

- 回到仪表盘，点击 **AI 创建故事**。
- 在「故事」页点击新建按钮，手动填写。

#### 有数据时的预期界面

- **故事卡片/列表**：展示每个故事的封面、标题、类型、进度、最近编辑时间。
- **操作按钮**：
  - **打开**：进入该故事的详细管理。
  - **编辑**：修改标题、简介、类型。
  - **删除**：移除故事（会二次确认）。
  - **导出**：将故事内容导出为文档。

#### 为什么有用

把作品集中管理，避免散在各种文件里。点击任意故事后，左侧底部"当前编辑"会显示该故事，角色、场景、世界观等页面会自动切换到这个故事的数据。

---

### 3.3 角色 — 人物资料库

![角色页](product-screenshots/03_characters.png)

小说是由人推动的。这个页面帮你把每个角色的关键信息系统化管理。

#### 首次使用时的空状态

未创建角色时，页面主体为空。需要先选择一个故事，再添加角色。

#### 有数据时的预期界面

- **角色列表**：头像/姓名卡片。
- **角色详情面板**：
  - **基本信息**：姓名、性别、年龄、外貌。
  - **性格**：性格标签、核心驱动力。
  - **背景**：出身、经历、目标。
  - **关系**：与其他角色的关系（朋友、敌对、亲人等）。
- **操作按钮**：
  - **新增角色**：打开表单填写。
  - **编辑**：修改已有资料。
  - **向导 / Genesis 预生成角色**：通过「AI 创建故事」或幕前「新写 XX 小说」触发创世后，角色会作为预生成资产进入本页；你可在幕后直接编辑、补全人设。
  - **关联场景**：查看该角色在哪些场景中出场。

#### 为什么有用

防止"写到后面忘记角色设定"，也方便 AI 在续写时严格遵循人设不出戏。

---

### 3.4 场景 — 情节单元管理

![场景页](product-screenshots/04_scenes.png)

"场景"是故事的最小情节单位，类似于"一场戏"。一个章节通常包含多个场景。

#### 首次使用时的空状态

未创建场景时，页面提示你开始创作之旅。

#### 有数据时的预期界面

- **场景列表/时间线**：按章节或时间顺序排列。
- **场景卡片**：包含场景标题、所属章节、出场角色、地点、状态（已完成/待写）。
- **操作按钮**：
  - **新增场景**：填写标题、地点、出场角色、场景目标。
  - **编辑场景**：修改内容或元信息。
  - **AI 扩写/润色**：选中场景后让 AI 帮你写或改。
  - **排序/拖拽**：调整场景先后顺序。

#### 为什么有用

把"写一章"拆成"写几场戏"，降低心理压力；同时让 AI 明白每场戏该谁出场、在哪里、要达成什么目标。

---

### 3.5 世界构建 — 设定资料库

![世界构建页](product-screenshots/05_world_building.png)

奇幻、科幻、架空历史作品必备。用来存放世界观、势力、地理、规则等背景设定。

#### 功能预期

- **分类浏览**：按「地理」「势力」「规则」「历史」「文化」等分类查看。
- **设定条目**：每个条目包含名称、描述、关联故事、关联场景。
- **操作按钮**：
  - **新增设定**：填写类型、名称、详细描述。
  - **向导 / Genesis 预生成世界观**：通过「AI 创建故事」或幕前创世触发后，世界观、核心规则、势力等会作为预生成资产进入本页；你可在幕后继续编辑、补充细节。
  - **关联角色/场景**：把设定和具体角色、场景绑定。

#### 为什么有用

保证设定不自相矛盾，也让 AI 在续写时不会"吃书"。

---

### 3.6 知识图谱 — 关系可视化

![知识图谱页](product-screenshots/06_knowledge-graph.png)

把故事中的角色、地点、事件、势力变成一张可交互的网络图。

#### 功能预期

- **节点**：角色（圆点）、地点（方块）、事件（菱形）等。
- **连线**：表示关系，如"朋友""敌对""出生于""发生在"。
- **交互**：
  - 拖拽节点调整布局。
  - 点击节点查看详情。
  - 缩放、平移画布。
  - 筛选显示某类节点（只看角色、只看事件）。

#### 为什么有用

直观发现"这个角色是不是太久没出场""某条线索是不是忘了回收"。

---

### 3.7 技能 — AI 创作技能工坊

![技能页](product-screenshots/07_skills.png)

"技能"是可复用的 AI 辅助 Prompt 模板。系统预置了一些，你也可以自己添加。

#### 界面元素

- **导入技能**：从文件导入别人分享的技能配置。
- **分类筛选标签**：
  - **全部**：显示所有技能。
  - **写作**：续写、改写、润色、扩写。
  - **分析**：情节分析、人设一致性检查。
  - **角色**：生成角色、角色心理描写。
  - **情节**：生成大纲、拆章、节奏分析。
  - **风格**：模仿某作家风格、调整语气。
  - **世界观**：生成地理、势力、规则。
  - **导出**：格式化输出技能。
  - **集成**：与外部工具集成的技能。
  - **自定义**：你自己创建的技能。
- **技能卡片**：名称、描述、适用场景、启用开关。

#### 典型操作

1. 点击 **写作** 分类 → 找到「续写」技能。
2. 在幕前写作时选中文字 → 调用该技能 → AI 按设定风格续写。

---

### 3.8 MCP — 外部工具连接（设置 → 扩展）

![MCP 页](product-screenshots/08_mcp.png)

MCP（Model Context Protocol）让草苔能调用外部模型或数据源。自 v0.26.40 起入口在 **设置 → 扩展**，**不进入默认续写热路径**，仅供高级联调。

#### 功能预期

- **连接列表**：已连接的外部服务。
- **添加连接**：输入地址、密钥、权限范围。
- **工具/资源管理**：查看每个连接提供的工具和资源。

#### 为什么有用

比如连接一个专门的"古文润色"模型，或连接你的私有知识库，让 AI 在创作时参考。

---

### 3.9 拆书 — 学习经典结构

![拆书页](product-screenshots/09_book-deconstruction.png)

把你喜欢的小说上传，AI 帮你提取结构要素，供自己创作参考；绑定参考书后，续写时可注入相关场景片段。

#### 当前能力

- **上传书籍**：支持 txt、epub、pdf 等格式。
- **分析结果**：
  - 书目元信息（标题、作者、题材、简介）
  - 故事线摘要（主线 / 支线 / 转折与高潮要点）
  - 角色与场景列表（含 LitSeg 叙事强度等字段）
  - 伏笔线索（写入伏笔追踪，转故事后可继续使用）
- **转故事**：一键把拆书结果转为可写的新故事草稿。
- **进度**：分析进度按当前书籍过滤，不会与其他任务串扰。

#### 规划中（尚未交付）

- 角色出场频率图表、完整高潮曲线可视化等统计图表。

#### 为什么有用

把「凭感觉写」变成「有参照地写」：结构摘要与场景片段可回流到续写上下文。

---

### 3.10 任务 — 后台作业队列

![任务页](product-screenshots/10_tasks.png)

当 AI 在执行批量操作（如批量生成场景、整书润色）时，会在这里显示进度。

#### 界面元素

- **新建任务**：手动发起一个后台 AI 任务。
- **状态筛选标签**：
  - **全部**
  - **执行中**
  - **等待中**
  - **已完成**
  - **失败**
- **任务列表**：显示任务名称、进度条、预估剩余时间、结果入口。

#### 典型场景

你让 AI "把前 10 章全部润色一遍"，这是一个长任务，会进入队列。你可以关闭电脑去做别的事，回来在任务页查看结果。

---

### 3.11 伏笔看板 — 线索回收追踪

![伏笔看板](product-screenshots/11_foreshadowing.png)

专门用来管理"前面埋下的线索后面有没有回收"。

#### 功能预期

- **列表 + 统计视图**：三列 Kanban（未回收 / 已回收 / 已放弃），展开行可编辑 Payoff Ledger 目标回收窗口（v0.26.35）。
- **创建伏笔**：填写描述、预期回收章节、重要性；`setup_scene_id` 支持从当前故事的场景下拉选择（v0.26.27 起），无需手填 ID。
- **高级回收计划**：可展开高级区编辑 `target_start_scene` / `target_end_scene` 等回收窗口。
- **关联场景**：把伏笔绑定到具体场景。
- **Payoff Ledger**：展示每条伏笔的回收进度、逾期提醒与推荐回收时机。

#### 为什么有用

避免"开头精彩、结尾烂尾"，确保每条线索都有交代。

---

### 3.12 叙事分析 — 结构诊断

![叙事分析页](product-screenshots/12_narrative-analysis.png)

用 AI 分析当前故事的叙事健康度。

#### 功能预期

- **节奏强度条**：以条形图展示每章 / 每个叙事单元的紧张度、冲突密度等强度指标，便于快速定位节奏平缓或过于密集的区间。
- **角色戏份**：各角色出场频率与台词 / 动作占比的文本/条形摘要。
- **情节密度**：对话、动作、描写的比例分析。
- **AI 诊断建议**：指出可能的问题，如"中期节奏过平""某角色出场过少"。

#### 为什么有用

像给小说做体检，发现结构性问题再针对性修改。

---

### 3.13 Story System — 高级契约系统

![Story System](product-screenshots/13_story-system.png)

高级功能页，用于管理故事级 AI 契约、版本提交、运行时规则。

#### 功能预期

- **契约树**：定义 AI 必须遵守的创作规则（如"主角不能死""保持第三人称"）。
- **版本记录**：类似 Git 的提交历史，可回溯到之前的故事版本。
- **运行时规则**：控制 AI 生成时的行为边界。

#### 为什么有用

让 AI 在长篇幅创作中保持高度一致性，避免"越写越偏"。

---

### 3.14 用量统计 — AI 资源消耗

![用量统计](product-screenshots/14_usage-stats.png)

查看你与 AI 交互产生的 Token、调用次数、预估费用。

#### 功能预期

- **按 operation 分组筛选**（v0.26.27 起）：
  - **全部**：展示所有 LLM 调用。
  - **bootstrap**：创世 / 向导流程的调用。
  - **smart_execute**：幕前续写、智能执行的调用。
  - **其他**：审校、洞察、任务等后台调用。
- **按模型统计**：不同模型的调用次数与 Token 消耗对比。
- **总览卡片**：展示当前选中分组的总调用次数、总 Token 数与预估费用。

#### 为什么有用

如果你是按量付费的 API 用户，可以清楚知道钱花在哪。

---

### 3.15 写作统计 — 你的创作数据

![写作统计](product-screenshots/15_writing-stats.png)

记录你自己的写作习惯，帮你建立稳定的输出节奏。

#### 功能预期

- **字数趋势**：每日/每周字数折线图。
- **活跃时段**：你一天中最高产的时段。
- **连续创作天数**：打卡式激励。
- **平均速度**：每小时产出字数。

---

### 3.16 设置 — 模型与偏好配置

![设置页](product-screenshots/16_settings.png)

配置 AI 模型、账号、界面偏好。

#### 界面元素

- **导出设置 / 导入设置**：备份或迁移配置。
- **顶部标签页**：
  - **模型管理**：添加、删除、测试 LLM 连接。
  - **Agent 配置**：配置不同 AI Agent 使用的模型。
  - **创作方法论**：选择创作框架（三幕式、英雄之旅等）。
  - **工作流**：配置自动化流程。
  - **提示词**：查看与编辑全部内置 AI 提示词；v0.30.22 新增 `agency_problem_logline`（Logline 生成）与 `agency_problem_outline`（故事大纲增强），控制 PROBLEM 七元素框架的 Logline 生成与大纲引导，修改即时生效。
  - **通用设置**：主题、语言、自动保存间隔、字号、行高；超时与生成模式等改动保存后即时热重载（v0.26.36：幕前无需重启即可使用新超时/字体/色调）。模型新增与「创作」角色默认模型变更亦即时同步到幕前连接状态与生成路由（v0.26.52）；偶发失败后的粘性降级不会长期绕过创作模型（v0.26.54）；模型列表可开启/关闭（v0.26.55）。
  - **数据统计**：查看本地数据统计。
  - **账号与登录**：管理账号、订阅状态。
- **模型管理页面（默认显示）**：
  - **分类筛选**：全部 / 聊天模型 / 嵌入模型 / 多模态 / 图像生成。
  - **模型卡片**：名称、提供商、模型 ID、延迟、能力标签。
  - **添加模型按钮**：按类型添加新的模型配置。

#### 典型操作

1. 第一次使用先进入 **模型管理** → **添加聊天模型**。
2. 填写 API 地址、模型名、API Key → 点击测试连接。
3. 连接成功后，该模型会在幕前写作和其他 AI 功能中可用。

---

### 3.17 生成链路 — 追踪每次 AI 生成

进入 **生成链路** 页，可查看每次 AI 生成请求的完整调用链路（v0.26.27 起）。

#### 功能预期

- **链路列表**：按时间倒序展示最近的生成链路，包含 trace_id、操作类型、调用时间、耗时与状态。
- **链路详情**：点击某条链路可展开详情，查看：
  - 调用的模型、提示词长度、返回 Token 数。
  - 路由决策（为何选择该模型）。
  - 各阶段耗时与错误信息。
- **与 Genesis 互链**：链路详情中可点击「对应 Genesis 运行」直接跳回仪表盘的 Genesis 运行记录；Genesis 运行记录中也可点击「查看生成链路」进入本页并自动按 `trace_id` / `session_id` 过滤。

#### 为什么有用

当 AI 生成结果不符合预期、某次调用特别慢或失败时，可以在这里精确还原「模型 → 提示词 → 返回」的全过程，便于排查问题。

---

### 3.18 意图图诊断 — 看懂 AI 的规划过程

进入 **意图图** 页，可查看当前故事在 AI 规划阶段的意图图诊断信息（v0.26.27 起）。

#### 功能预期

- **意图节点**：展示 AI 识别出的用户意图节点（如「推进情节」「补充世界观」「润色文笔」等）。
- **PPR 分层**：按 PPR（Primary / Precondition / Resource）分层展示意图依赖关系。
- **执行轨迹**：展示意图图在 PlanExecutor 中的实际执行路径与状态。
- **诊断建议**：当意图识别置信度低或执行路径异常时，给出提示。

#### 为什么有用

AI 不是黑盒：你可以看到它如何理解你的指令、为什么选择某条执行路径，从而更有针对性地调整提示或创作方向。

---

### 3.19 日志查看 — 排查系统与创作问题

进入 **日志** 页，可查看后台工作流日志与系统日志（v0.26.27 起）。

#### 功能预期

- **日志列表**：按时间倒序展示工作流日志，包含时间戳、级别、模块、消息。
- **搜索过滤**：支持按关键字搜索；当从 Genesis 失败运行跳转过来时，会自动填入对应的 `session_id` 过滤。
- **与 Genesis 互链**：Genesis 运行记录中，失败的运行会显示「查看日志」链接，点击后跳转到本页并预填 `session_id`，快速定位该次运行的全部日志。

#### 为什么有用

当创世或续写出现异常、模型长时间无响应、数据未正确写入时，日志是最直接的排查入口。

---

### 3.20 代理工作室 — 实时观看三代理协作

进入 **代理工作室** 页（侧栏「创作」组，v0.30.0 起），可实时查看 Agency 多代理创作框架的运行过程。

#### 功能预期

- **三角色状态卡**：主创 / 管理 / 编辑审计三个代理的实时状态与当前动作。
- **黑板视图**：三代理共享的黑板内容分区展示（事件驱动自动刷新）。
- **活动时间线**：本次 run 的协作事件按时间排列，谁在什么时候做了什么一目了然。

#### 为什么有用

AI 创作不再是黑盒：触发创世或续写后，你可以全程看到三个代理如何分工、质量门如何把关。

---

### 3.21 学习中心 — 管理 AI 学到的创作模式

进入 **学习中心** 页（侧栏「诊断」组，v0.30.0 起），可查看与管理 AI 从你的创作中学到的模式。

#### 功能预期

- **模式列表与置信度**：系统从创作事件中提炼的 instinct（触发条件 → 动作）及其置信度。
- **晋升提案**：置信度足够高且跨故事复现的模式会生成晋升提案，由你确认后物化为可复用技能；也可拒绝。
- **观察流与手动分析**：查看原始观察记录，或手动触发一次「立即分析」。

#### 为什么有用

持续学习的每一步都由你把关——AI 越写越懂你，但学什么、不学什么，最终决定权在你。

---

### 3.22 创作评估 — 质量门与检查点仪表盘

进入 **创作评估** 页（侧栏「诊断」组，v0.29.0 起），可查看 Agency 创作质量的量化趋势。

#### 功能预期

- **质量门评分趋势**：Gate v2 加权评分（四级 grader）随章节的变化曲线与通过率。
- **检查点对比**：里程碑检查点的指标快照（章节数 / 字数 / 评分 / token / 耗时），支持"现在 vs 当时"对比。
- **token 用量**：按角色（主创 / 管理 / 编辑）聚合的 token 消耗。

#### 为什么有用

用数据回答"AI 写得怎么样、有没有越写越好"，而不是凭感觉。

---

## 四、幕前写作界面

### 4.1 界面总览

![幕前写作](product-screenshots/00_frontstage.png)

幕前是一个极简、全屏的写作环境，目的只有一个：让你专注码字。

### 4.2 顶部状态栏

| 元素            | 作用                                 |
| --------------- | ------------------------------------ |
| **草苔 / 故事名** | **双击**改名（有故事时）。空编辑器显示「草苔」；粘贴正文后显示「未命名」并自动创建故事。回幕后请点右上角 **设置** |
| **章节名**      | 顶栏与编辑器上方标题一致；空标题显示「第N章」；**双击**可改名（Enter/失焦保存，Esc 取消） |
| **0 字 / 0 字** | 当前章节字数 / 总字数                |
| **18px**        | 当前字号，点击可调整                 |
| **色调选择**    | 四种配色方案：暖赭、冷青、琥珀、靛紫 |
| **设置**        | 打开设置 / 返回幕后工作室 |
| **温**          | 文思模式切换：控制 AI 提示的主动程度 |

### 4.3 中间编辑区

- 点击"开始写作…"即可输入。
- 支持富文本格式（加粗、斜体、标题等）。
- 内容会自动保存；无故事时首次输入/粘贴正文会自动创建「未命名」故事。
- 编辑器上方的章节标题可双击改名。
- 在编辑器内右键，可调出统一风格的快捷菜单：剪切、复制、粘贴、全选。

### 4.4 底部 AI 输入栏

- **输入任意指令…**：在这里输入对 AI 的指令，例如：
  - "帮我续写下一段"
  - "把这段改得更紧张"
  - "加入一个意外转折"
- 按回车或点击右侧纸飞机发送。

### 4.5 文思模式

点击右上角 **温** 可切换 AI 介入的主动程度：

- **被动**：只有在你主动发指令时 AI 才响应。
- **主动**：AI 会适时给出萤火提示（如下一句建议、情节提醒）。

### 4.6 操作路径示例

1. 在幕后仪表盘点击 **开幕前写作** → 打开幕前界面。
2. 选择喜欢的色调 → 开始打字。
3. 写到卡壳时 → 在底部输入 "接下来怎么发展？" → AI 给出建议。
4. 写完后 → 点击顶部 **设置** 返回幕后，继续管理角色或场景。

---

## 五、常见状态与通知

### 5.1 连接状态提示

若看到顶部红色提示条"无法连接到本地服务"，表示前端未能连上 Rust 后端服务。常见原因：

- 应用尚未完全启动（多等几秒，点击"重试"）。
- 本地服务进程意外退出（重启应用）。
- 防火墙或端口冲突（检查 5173/其他配置端口）。

### 5.2 登录状态

- 未登录时，左下角显示"登录"。
- 点击后弹出登录面板，支持邮箱/第三方账号。
- 登录后可同步订阅状态、跨设备数据。

### 5.3 更新通知

有新版本时，右上角会弹出更新卡片（下载源为 GitHub 正式版 Release）：

- **安装**：从 GitHub 下载签名更新包并重启应用。
- **忽略**：关闭本次提醒（约 7 天内不再提示同一版本）。
- **检查更新**：手动触发版本检查（设置 → 关于 也可）。

若提示无法读取 `latest.json`，请确认官网 `https://storymoss.top/releases/latest.json` 已包含最新版本，或手动前往 [GitHub Releases](https://github.com/91zgaoge/StoryMoss/releases/latest) 下载。

---

## 六、快速上手流程

如果你是第一次使用草苔，建议按以下顺序探索：

1. **打开应用** → 看到仪表盘。
2. **点击 AI 创建故事** → 输入你的创意一句话 → 等待 AI 生成框架。
3. **进入「故事」页** → 确认新建的故事 → 点击打开。
4. **进入「角色」页** → 为故事添加 2-3 个核心角色。
5. **进入「场景」页** → 创建第一章的几个关键场景。
6. **点击左侧「开幕前写作」** → 在幕前界面写第一章。
   - 若通过「AI 创建故事」或幕前输入「新写一部XX小说」触发创世，AI 会先铺设开篇骨架（主角目标与场景戏剧卡），再在约 30–90 秒内生成第一章正文并**自动接受**进编辑器（无需按 Tab），你可立即开始写作；后台继续完善世界观/角色/场景/合同，不阻塞输入。
   - 注：v0.27.0 起，上述 Genesis 快速/后台两阶段流程已被 Agency 多代理框架（创世 2.0）取代——管理备资产、主创作首章、编辑审计把关，中途可定点取消；实时过程可在侧栏「代理工作室」观看。
   - 注：v0.30.22 起，输入简单指令创世时系统会先用 PROBLEM 七元素框架（Punishing/Relatable/Original/Believable/Life-Altering/Entertaining/Meaningful）自动生成强力 Logline（谁 + 催化事件 + 核心不可能的任务 + 失败后果），再以此驱动故事大纲与首章生成，无需手写完整故事构想。
7. **卡壳时用底部 AI 输入栏求助** → 让 AI 续写或润色。
8. **返回幕后「叙事分析」** → 看看 AI 对结构的诊断建议。

---

## 七、更新日志区（持续追加）

> 以下按时间倒序记录功能更新，方便老用户快速了解新增能力。

### 2026-06-08 当前版本

- 仪表盘：支持 AI/手动创建故事，展示故事/角色/场景统计。
- 故事/角色/场景/世界构建：基础 CRUD + AI 生成辅助。
- 技能工坊：分类管理 AI 技能，支持导入导出。
- 任务队列：后台 AI 任务可视化。
- 知识图谱：关系网络可视化。
- 伏笔看板：线索埋设与回收追踪。
- 叙事分析：节奏、戏份、密度分析。
- Story System：契约与版本管理。
- 用量/写作统计：资源消耗与创作习惯双维度数据。
- 设置：多模型配置、Agent 映射、创作方法论、工作流。
- 幕前写作：沉浸式编辑器 + AI 指令栏 + 文思模式 + 四种色调 + 统一风格右键菜单。

---

## 八、附录：截图清单

本文档配图来自 `docs/product-screenshots/`，由 CDP 自动截取并归档：

| 文件名                       | 对应页面     |
| ---------------------------- | ------------ |
| `00_frontstage.png`          | 幕前写作界面 |
| `01_dashboard.png`           | 仪表盘       |
| `02_stories.png`             | 故事管理     |
| `03_characters.png`          | 角色管理     |
| `04_scenes.png`              | 场景管理     |
| `05_world_building.png`      | 世界构建     |
| `06_knowledge-graph.png`     | 知识图谱     |
| `07_skills.png`              | 技能工坊     |
| `08_mcp.png`                 | MCP 连接     |
| `09_book-deconstruction.png` | 拆书分析     |
| `10_tasks.png`               | 任务队列     |
| `11_foreshadowing.png`       | 伏笔看板     |
| `12_narrative-analysis.png`  | 叙事分析     |
| `13_story-system.png`        | Story System |
| `14_usage-stats.png`         | 用量统计     |
| `15_writing-stats.png`       | 写作统计     |
| `16_settings.png`            | 设置         |

每个 `.png` 都配有同名的 `.json` 文件，记录该页面当时的交互元素、坐标和文本内容，便于后续自动化更新文档。