dsh-tool-writing
面向 DeepSeek Harness 的「写文引擎」插件：让 harness 具备长篇网络小说的创作能力，并用一把独立的 DeepSeek key 承担「子线程 / 分流 / 多线并行」的生成与检索任务。
设计定位
- 主 Agent（harness 自身模型）：总调度，负责主线叙事、结构、设定、以及「新奇的、出其不意的想法」的决策。
- 本插件（独立 key）：把重活分流出去——并发生成多章草稿、批量出点子、批量扩写细纲，以及资料检索与一致性筛查。
- 饲料区（书库）：导入并管理多本小说，建立全文索引，供考据、风格参考与设定借鉴。
工具集
创作核心
| 工具 | 作用 |
|---|
| `novel_init` | 初始化小说项目（元信息 + 目录骨架） |
| `novel_outline` | 生成/展开主线、分卷、章节细纲（可并行） |
| `novel_lore` | 人物/世界观/时间线/伏笔的增删改查 |
| `novel_brainstorm` | 并发生成 N 个新奇点子 |
| `novel_draft` | 起草一章正文（综合设定+大纲+前文，支持分卷） |
| `novel_continue` | 从最近章节自动续写下一章 |
| `novel_batch` | 并发生成多章草稿（分流/多线） |
| `novel_polish` | 润色/改写 |
| `novel_review` | 一致性审校（检索前文+设定，筛查矛盾） |
| `novel_research` | 资料检索/考据，归纳成笔记 |
| `novel_status` | 查看项目进度（分卷/章节/字数） |
| `novel_export` | 导出全书为单个 Markdown/TXT |
| `novel_summarize` | 生成章节情节摘要，写入可检索的情节日志 |
| `novel_setting_extract` | 从正文自动抽取人物/世界观/伏笔到 lore/ |
| `novel_foreshadow` | 伏笔回收追踪（登记/回收/查未回收） |
| `novel_brief` | 模糊需求一键开书（一句话 → 完整方案） |
| `novel_distill` | 蒸馏文本为精华 + 保留校验（项目/书库，含全书语义召回） |
| `novel_handbook` | 生成给人读的导航手册（含语义召回名场面） |
| `novel_simulate` | 深度推演引擎（心理/因果/交汇/反常识意外） |
| `novel_semantic` | 混合语义检索（向量召回+字面召回+LLM 重排，按含义而非字面） |
| `novel_vsearch` | 纯向量语义检索（cosine 相似度，免 LLM，快速看命中） |
| `novel_embed` | 构建/补全语义向量索引（增量、断点续传、内容变更自动重嵌） |
| `novel_evolution` | 设定/人物演化追踪（auto 检测 + 手动 + 历史 + 版本 diff 陈旧检测） |
| `novel_threads` | 多线叙事与线索图谱（登记/交汇/图谱/停滞提醒） |
| `novel_style` | 风格指纹（剖析文风、多风格档案、自动注入所有生成） |
| `novel_decision` | 人机共创决断点（选项+利弊，人做美学决断） |
| `novel_sync` | 章末自动编排（摘要+抽取+演化+伏笔提醒 一键） |
novel_usage | 用量总账：调用次数、token 与估算费用（落盘 $DSH_HOME/writing-usage.json，自动裁剪） |
novel_proofread | 机械校对：只找硬伤（错别字/标点/的地得/重复词/数字格式），不改文风 |
novel_plan | 连载计划：完本目标/每日产出/存稿余量/排期登记（本地 plan.json，不对接平台） |
饲料区 + 扩展检索
| 工具 | 作用 |
|---|
| `novel_library_import` | 导入小说（.txt/.md/.epub，自动识别编码 + 自动分章） |
| `novel_library_list` | 列出书库所有小说 |
| `novel_library_read` | 读某本小说的某一章 |
| `novel_library_delete` | 删除已导入的小说 |
| `novel_library_search` | 书库全文检索（SQLite FTS5 trigram + LIKE 混合） |
| `novel_search` | 扩展检索：项目 + 书库 联合全文检索 |
语义向量检索使用百炼 `text-embedding-v3`（1024 维，复用 DASHSCOPE_API_KEY，零新增成本）：`novel_embed` 建索引（增量可续传，内容变更自动作废重嵌），`novel_semantic` 混合召回，`novel_vsearch` 纯向量；无 key 时自动退化为字面检索。
思考档位路由（V4 三档）
- 引擎
generate() 支持 effort: low | high | max：low/默认走主模型（deepseek-v4-flash）并显式关闭思考模式（V4 官方默认开思考，会吃掉输出额度且不支持 temperature）；high/max 走 deepModel（deepseek-v4-pro）并开启思考 + 对应档位
- 工具路由：草稿/续写/批量/润色/校对/检索重排 → low；一致性审校/设定抽取/蒸馏校验/演化检测/剧情决断/书库拆解/章末编排 → high；
novel_simulate 深度推演 → max
- 兼容旧调用：
deep: true 等价 high（不上 wire 参数，行为不变）
缓存前缀布局（批量省钱）
- 批量生成（
novel_batch）每个请求的 system 与共享上下文（作品信息+设定卡片+大纲+最近章节）逐字节一致，章节差异只出现在提示尾部；generateMany 默认先串行首任务预热缓存，其余并发时自动命中
- DeepSeek 前缀缓存自动命中：v4-flash 命中价 $0.0028/M、v4-pro $0.003625/M（约为未命中价的 1/50~1/120），批量 10 章的费用大头只在首次请求
- 有回归测试锁死该布局（
smoke-cache.mjs）：共享前缀在前、章差异在尾，防止未来改动破坏缓存友好性
用量记账与连载计划
novel_usage：查看独立 key 的调用总账（次数/输入输出 token/缓存命中/估算费用，按模型与最近 7 天汇总）。明细落盘 $DSH_HOME/writing-usage.json（上限 2000 条自动裁剪），单价可按需覆盖。novel_proofread：机械校对某一章，输出「片段 | 问题类型 | 建议改为」清单，绝不改写文风、不重写句子。novel_plan：项目根 plan.json 的本地连载计划——set-goal 设定章数/字数/完本日期后自动算每日产出；schedule/mark-done 登记排期；存稿余量按 manifest 实际章节联动。不做平台发布对接，发布由作者自行粘贴。
语义检索的两种后端
- 百炼稠密向量（
DASHSCOPE_API_KEY 可用时）：text-embedding-v3 1024 维余弦检索
- DeepSeek 概念索引（无百炼 key 或调用失败时自动降级）：用
deepseek-v4-flash 为每个文档抽取概念词（带权重），构成稀疏语义向量空间；查询时以「词表锚定」把检索意图翻译成文档概念词，按 cosine + idf 排序。纯自家 key，零第三方依赖，命中可解释（能显示命中概念）
- 降级自动发生：
novel_embed 建索引、novel_vsearch/novel_semantic 检索都会在稠密路径不可用时无缝切换
项目目录约定
```
novel.json # 作品元信息 + 分卷/章节进度
lore/ # characters/ world/ timeline/ foreshadowing/ other/
outline/ # 主线与分卷/章节细纲
chapters/ # 正文（可按分卷建子目录）
research/ # 考据与审校笔记
.writing-index.sqlite # 项目全文检索索引（SQLite，自动维护）
```
书库默认位于 `$DSH_HOME/writing-library/`（可配 `libraryRoot`）。
配置
| 字段 | 默认值 | 含义 |
|---|
| `apiKeyEnv` | `DSH_WRITING_API_KEY` | 独立 key 的环境变量名/凭证引用 |
| `apiKey` | `""` | 内联 key（不建议，避免泄露） |
| `baseURL` | `https://api.deepseek.com\` | DeepSeek 端点 |
| `model` | `deepseek-v4-flash` | 分流用的模型（可用 deepseek-reasoner） |
deepModel | deepseek-v4-pro | 深度思考任务（归纳/拆解/蒸馏）用的模型 |
| `maxConcurrency` | `4` | 并发上限 |
| `maxTokens` | `4096` | 单次生成最大 token |
| `temperature` | `0.8` | 采样温度 |
embedBaseURL | "" | 自定义 embedding 端点（默认百炼 text-embedding-v3） |
embedModel | "" | embedding 模型名（默认 text-embedding-v3） |
embedApiKey | "" | embedding 密钥（默认复用 DASHSCOPE_API_KEY） |
| `projectRoot` | `.` | 小说项目根目录（默认当前工作区） |
| `libraryRoot` | `$DSH_HOME/writing-library` | 书库根目录 |
密钥安全
密钥绝不硬编码。优先级：凭证存储（`$DSH_HOME/.credentials.yaml` 的 `DSH_WRITING_API_KEY`）→ 环境变量 → 内联 config。
安装（profile）
```
dsh plugin --profile web add file:<本目录>
也可以直接从 npm 安装：dsh plugin --profile web add dsh-tool-writing。
```
然后在写作预设的 `agent.cordis.yml` 中挂载：
```yaml
- id: tool-writing
name: 'dsh-tool-writing'
config:
apiKeyEnv: DSH_WRITING_API_KEY
model: deepseek-v4-flash
maxConcurrency: 4
```
