前言¶
在 DeepSeek Harness（DSH）中，对话会话通常按时间顺序记录。当一段讨论较长且主题分散时，直接导出会话文本往往缺乏结构，不利于阅读和交付。本插件通过两轮 LLM 调用，把会话文本按主题聚类、生成大纲与目录，再逐节填充正文，输出一份自包含的结构化 Markdown 文档。
插件定位与维护者¶
dsh-session-to-doc 是一个 DSH 插件，由维护者 Dongze502 开发。它把当前会话中的对话记录重新组织为带大纲、章节层级和目录的结构化 Markdown 文档，而不是按时间顺序原样导出。插件提供三种入口：模型工具、界面按钮、HTTP 端点，三者共用同一套编排代码。
核心功能¶
三种触发方式¶
- 模型工具
session_to_doc：用户说“整理成文档”或“把这段讨论整理成文档”时，模型根据工具描述判断调用该工具，参数可选detailLevel等。 - 界面按钮：输入框下方常驻的「整理成文档」按钮，点击后直接调用
POST /session-to-doc/generate，使用默认参数（standard+ 带 TOC）生成并在弹层展示，可一键复制 Markdown。 - HTTP 端点：上述按钮背后的接口，也可被脚本调用。
三条路径最终都落到 generateDocument(ctx, input)，同一会话在两种入口下产出相同的文档结构。
工作流程¶
- 提取会话文本：通过
ctx.sessions解析当前会话，优先使用exec.agent.session；若无 agent 则使用ctx.sessions.list()中seq最大的会话。只纳入 user 与 assistant 消息里的 text block，超长会话（超过 60000 字）保留头 65% + 尾 30%，并在notes中标注裁剪字数。 - 第一轮：按主题聚类，生成 outline（标题、层级、字数预算），层级最多三级，标题为可交付的陈述性描述，不使用“用户询问了……”“助手回答了……”等元描述。
- 第二轮：按大纲逐节填充正文，不跨章借用，信息不足时标注。
- 生成 TOC：确定性生成 GitHub 风格目录，跳过代码块、去重锚点。
- 组装返回：将 TOC、outline、正文、notes 组装成 canonical 对象返回。
工具定义¶
参数¶
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
detailLevel |
'concise' \| 'standard' \| 'detailed' |
'standard' |
章节填充的详细程度。concise 压低预算，detailed 放宽预算，standard 按信息密度分配。 |
includeToc |
boolean |
true |
是否在文档开头嵌入目录。 |
maxSectionBudget |
number（可选） |
— | 单章节最大字数上限。不传则由 AI 在规划阶段自行分配（内部上限 2000 字，超过 maxSectionBudget 的预算会被压缩并记录到 notes）。 |
返回值¶
| 字段 | 类型 | 说明 |
|---|---|---|
markdown |
string |
最终完整文档；includeToc 为真时目录已插到正文开头。 |
outline |
Array<{ title: string, level: number, budget: number }> |
第一轮规划出的大纲，可直接用于 UI 卡片预览“准备怎么组织”。 |
toc |
string |
单独返回的目录字符串，始终生成（即使 includeToc 为 false），方便用户复制。 |
notes |
string[]（可选） |
仅在出现业务上的非理想结果时才返回，例如某章节信息不足、预算被压缩、会话被裁剪、大纲规划失败降级、大纲外多出小节。无提示时该字段不出现。 |
输出渲染¶
output.render 只投影纯文本：
render(_args, value) {
return [{ type: 'text', text: value.markdown }]
}
模型看到 Markdown，调用方拿到的仍是完整 canonical 对象。
HTTP 端点¶
请求¶
- 方法：
POST - 路径：
/session-to-doc/generate - 请求体：
{ sessionId?: string, detailLevel?, includeToc?, maxSectionBudget? } - 限制：只接受 POST，body 上限 64 KiB，非法 JSON 返回 400
- 安全：Host 必须是回环权威（
127.0.0.1/localhost/[::1]），Sec-Fetch-Site: cross-site/cross-origin一律 403，带Origin时必须与Host同源
响应¶
- 成功：
200 { ok: true, markdown, outline, toc, notes? } - 失败：
{ ok: false, error }
安装与启用¶
本插件以 npm 包形式发布，需要通过 DSH 的包管理机制安装。请根据 DSH 环境的包管理器执行安装命令（具体命令需参考 DSH 文档或本地 profile 配置）。安装后，插件会自动注册模型工具、界面按钮和 HTTP 端点。
典型用法¶
用户在 DSH 中与模型进行一段讨论后，可以点击输入框下方的「整理成文档」按钮，或让模型自然语言调用 session_to_doc 工具。插件会先提取当前会话文本，然后生成大纲和目录，再逐节填充正文，最终返回一份结构化的 Markdown 文档。
适用场景与注意¶
- 适合需要将长对话整理成可交付文档的场景，如技术讨论总结、会议记录、学习笔记等。
- 插件以当前 DSH 进程权限运行，安装前应检查源码与许可证（MIT）。
- 插件依赖 DSH 版本
0.2.0-rc.2及以上，安装前请核对依赖版本。
结语¶
dsh-session-to-doc 把会话整理为结构化文档，减少人工梳理成本，适合 DSH 用户在需要交付结构化内容时使用。更多详情可访问插件目录页或 GitHub 仓库。
