dsh-novel-generator 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 XiaoOu2024
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,87 @@
-# Temporary Holding Version
+# 小说工坊 · dsh-novel-generator
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+DSH 的常驻插件：在时间线上写小说。每个作品绑定一个普通会话，章节正文与世界快照都由那个会话里自己的 Agent 生成。
+
+## 安装
+
+```sh
+dsh plugin --profile web add dsh-novel-generator
+# 或直接装这个仓库：dsh plugin --profile web add https://github.com/XiaoOu2024/dsh-novel-generator
+```
+
+或在 DSH 的 **设置 → 插件** 里安装（本包声明了 `dsh.bundle`）。装好后刷新页面，界面左下角出现「小说工坊」按钮。
+
+> npm 包名 `dsh-novel-generator` 与 GitHub 仓库 `XiaoOu2024/dsh-novel-generator` 同名。
+
+需要 **DeepSeek Harness 0.2.1-rc.2 或更新的 0.2.x**：宿主侧调用 `sessionController`（create / selectModel / prompt / resolveAgent）、`workspaceRegistry`（create / resolveByPath / attachSession）与 `agentPresets`，这些在 0.2.1 之前不存在或不稳定。`package.json` 里以 `peerDependencies: { "@deepseek-ai/dsh": "^0.2.1-rc.2" }`（optional）声明，安装环境与本机验证版本一致。
+
+## 打开方式
+
+界面左下角（设置按钮旁）的 **小说工坊** 按钮，点开就是项目管理界面；右上角「关闭」退出。
+
+## 界面流程
+
+1. **作品列表**：创建 / 删除 / 打开作品。**删除作品会同时删掉工作目录下以作品名命名的那个文件夹（正文、梗概、快照），二次确认里会说明；作品绑定的会话保留。**创建时选工作目录、模型、预设——**工作目录只能通过「选择」调目录选择器挑选，不能手填**；创建动作本身会调用 `sessionController.create` 为作品开一个会话，会话照常出现在左侧列表里，可以直接进去对话。**每行都显示当前模型，并有「模型」按钮：改完会同时切换作品绑定的会话模型**（走 `sessionController.selectModel`）。**会话会被放进左侧对应的分组：作品目录已经是工作区就并进去，否则为该目录新建一个名为「小说工坊」的工作区**，不再是「未分组」。打开工作室时会对老作品补做这一步。
+2. **时间长河**（作品主界面）：最上方是时间线，左端是第 0 天，右端是**最新世界快照的时间**（故事已经写到快照之后时，右端延伸到故事当前的时间）。拖动时下方世界观、角色列表、势力列表、关系（`甲 乙 关系`）切换到该时间点之前最新的那份快照。右上角「快照间隔」是一个可编辑的选择框：候选值 **7 / 15 / 30 / 90 / 180 / 365 天**，也可以直接输入别的天数——这个值同时是「多少天结算一份世界快照」的阈值和自动触发点。**当拖到下一个快照点（上一份快照时间 + 一个间隔）时，页面顶部出现「生成世界快照 · 第 N 天」按钮，点击会先问「是否为当前时间生成世界快照」，确认后才生成。**「进入故事」进入离选中时间最近的章节。界面最底部是一条**每章天数统计图**：横轴为第几章（每章居中占一格），纵轴就是「今天数」——每章自己跨了多少天，柱高即该章天数，折线连接各章天数，鼠标悬停可看到该章在故事里的起止天数；标题栏的「隐藏统计图 / 显示统计图」按钮可以收起或展开它。
+3. **章节故事**：左上「← 时间长河」回时间线界面，右上「章节大纲 →」把故事页向左收起、翻开大纲页。中间用「← 上一章 / 下一章 →」左右切换；**到了最后一章，右侧的「下一章 →」变成「＋ 新建章节」**。正文可直接改，底部「保存」，保存成功用右上角的提示条告知（不是页面上的一行小字）。**正文有未保存的修改时，任何离开动作（回时间线、翻章、进大纲、新建章节、返回作品列表、关闭工作室）都会先弹出确认，可选「不保存离开」或「保存并离开」。**
+4. **新建章节**（弹窗）：章节名称（可留空）、章节最低字数、章节最多字数、故事时间长度（天），后三项必填。填好后可以「创建空章节」，或点「自动推演」一次拿到本章梗概、章节名称与完整正文。**作品的第一章没有世界快照、也没有上一章可依据，所以这一章的自动推演是禁用的（新建弹窗与章节大纲页都是），先创建空章节、自己写梗概再生成。**
+5. **章节大纲**：左上「← 章节故事」。可改标题、时间长度、字数上下限、梗概最低字数与梗概；梗概达到最低字数且其他项填完才能「保存」，保存成功用提示条告知，保存后「生成章节故事」才可点。右上「自动推演」点下去会先提示「将覆盖现有内容」，确认后按当前字数与时间长度重新生成**故事梗概 + 章节名称 + 整章正文**并直接保存；「生成章节故事」点下去会先问「是否以当前故事梗概生成故事」，确认后才重写正文。**大纲有未保存的修改时，离开同样会先弹确认（不保存离开 / 保存并离开）；大纲不完整时「保存并离开」会拒绝并提示。**
+
+## 世界快照怎么来
+
+- 时间线以「天」计（0 = 创建作品那天），整条线的右端永远等于最新快照的时间。
+- **每次生成章节后**都会检查：本章结束时间距离上一份快照是否已满一个时间线单位（30 / 90 / 365 天，由你选）。
+- 满了就取**上一份世界快照 + 这段时间内各章的梗概**，让作品会话产出新快照（世界观 / 角色 / 势力 / 关系），时间线随之向前多出一段到新快照时间。
+- 第一份快照同样按这个规则：故事时间走过一个单位后才写入。
+
+## 数据与接口
+
+- **索引文件**：`<DSH_HOME>/novel-studio/projects/<项目id>/project.json`（`DSH_HOME` 缺省为 `~/.dsh`，本机即 `C:\Users\Admin\.dsh\novel-studio`）。时间线、大纲、快照字段都记在这里；`dataDir` 配置可改这块的位置。
+- **正文、梗概、快照全部写到工作目录下、以作品名称命名的文件夹里**：
+
+  ```
+  <工作目录>/<作品名称>/
+  ├── 作品信息.md                    作品参数总览 + 章节一览表
+  ├── 第01章 章节名.md                章节正文（纯正文）
+  ├── 章节大纲/
+  │   └── 第01章 章节名.md            该章梗概 + 时间跨度 + 字数上下限 + 实际字数
+  └── 世界快照/
+      └── 第030天.md                 世界观 / 角色 / 势力 / 关系 / 阶段变化
+  ```
+
+  - 每次保存正文、生成章节、保存大纲（改标题）、结算快照都会同步刷新这些文件；改标题会顺手删掉旧文件名。
+  - 若你在编辑器里直接改章节正文 `.md` 且比插件记录的更新时间更晚，下次打开作品会以文件内容为准（梗概与快照目前是单向导出）。
+- **作品名称就是文件夹名，所以受文件名规则限制**：不能为空、最多 60 字、不能以空格或点开头结尾、不能含 `\ / : * ? " < > |` 与控制字符、不能用 `CON`/`NUL`/`COM1` 等系统保留名。创建界面会即时校验并禁用「创建」按钮。
+- HTTP 接口前缀：`/dsh-novel-generator/api`，只接受本机页面同源请求。
+- 生成、推演、快照都是异步任务：`POST /generate`、`POST /compose`、`POST /deduce`、`POST /snapshot/refresh` 返回 `jobId`，再由 `GET /job?id=` 轮询。
+- `timeline.cursor` 现在以「天」为单位；旧数据（按格计数）在首次读取时自动换算一次并标记 `cursorUnit: "day"`。
+
+## 自检脚本（开发用，不随包发布）
+
+```bash
+node selfcheck.mjs <临时工作目录>          # 创建/时间线/章节/大纲/保存/删除
+node selfcheck-generate.mjs <临时工作目录> # 真实调用模型生成一章
+node selfcheck-snapshot.mjs <临时工作目录> # 真实调用模型产出一份世界快照
+node selfcheck-compose.mjs <临时工作目录>  # 自动推演整章，并验证快照阈值触发
+```
+
+脚本默认访问 `http://127.0.0.1:3080`，仅用于本机验证。
+
+## 市场投稿条目
+
+`awesome-dsh-plugin` 的条目（`data/plugins/XiaoOu2024__dsh-novel-generator.yml`）：
+
+```yaml
+url: https://github.com/XiaoOu2024/dsh-novel-generator
+name: XiaoOu2024/dsh-novel-generator
+category: ui
+description:
+  en: 'Novel generator: builds a world snapshot along a story timeline and, from the latest snapshot and the most recent chapters, deduces the next chapter.'
+  zh: '小说生成器：按时间线生成世界快照，通过世界快照和最近章节自动推演新章节。'
+```
+
+投稿前需要：仓库已推送、创建满 1 天、仓库设置了 `dsh-plugin` topic。
+
+## 多语言
+
+界面语言跟随 DSH **设置 → 通用 → 语言**：客户端已接上 `ctx.locale`，并提供了 `useTranslator()`（`t('中文', 'English')`）。目前完成切换的是侧栏入口、工作室标题栏与载入提示；其余界面文案仍是中文，翻译工作是逐条的机械改造（约 500 处），留待后续一轮完成。