dsh-tool-writing

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 ```