@p-dsh-market/conversation-knowledge-map

Readme

# @p-dsh-market/conversation-knowledge-map

DSH 的“知识视图”插件，把同一工作路径下用户明确选择的多个历史对话整理成：

- 有阶段性段落的思维导图；
- 只读、可筛选、可回溯来源的静态知识图谱。

首版通过 `sessionQuery.filterSessions()`、`readTitleSnapshots()` 和 `readSurface()` 读取会话，不扫描 `$DSH_HOME/sessions`。结果保存到当前工作路径的 `.g-dsh-market-knowledge/`，只保存图数据、来源事件序号和生成参数，不复制完整聊天正文。

生成流程必须经过菜单栏配置和应用内确认。Host 会再次校验锚点 Session、`cwd`、选中 Session、revision 和固定保存目录；模型输出先通过图数据 Schema 校验，失败或取消不会替换旧结果。

配置面板会列出运行时可用的 Provider / Model，并默认带入 DSH 默认模型；本次选择会绑定到确认令牌、Agent 调用和 `manifest.json`，不会因为默认模型变化而被静默替换。提交任务后配置对话框立即关闭，失败原因会显示在知识视图页的任务条中。

“提取范围”同时作用于思维导图和知识图谱：默认的“完整对话正文”读取用户问题与助手回答；“仅助手回答正文”排除用户消息，并在摘要阶段进一步忽略检查步骤、搜索/工具过程、重试过程和状态播报。两种模式都始终过滤 `reasoning` / `thinking` 块、`<think>` 文本、工具结果和流式过程块。提取范围会绑定到确认令牌并保存到 `manifest.json`，生成后的来源栏会显示本次使用的范围。

摘要阶段按对话并行处理，并发上限固定为 3；每个对话按约 5000 字、优先在完整段落边界分段，只有单段本身超长时才按句末或硬边界拆分。同一对话的分段保持顺序处理。思维导图使用合并后的会话摘要；知识图谱直接使用保留来源的分段摘要，避免长对话在二次压缩后丢失实体。知识图谱按证据分段多次生成，最多 2 批并行；单批限制在 10–18 个实体、最多 24 条关系，若达到输出 Token 上限则只降低并重试当前批次。所有成功批次由 Host 按实体类型与名称、关系起点/终点/类型确定性去重并合并来源，最终结果再根据已读取文本量和有效分段数裁剪为 30–100 个实体、最多 200 条关系。单个批次连续失败只跳过该批，不会推翻其他成功批次。结构化输出失败时会完全重置并最多重试 3 次；单个对话摘要连续失败后只跳过该对话，不阻断其他对话和最终报告。“同时生成”模式下，一个最终视图失败也不会阻断另一个视图保存。进度区域和最终知识视图都会按时间线显示读取、摘要、具体失败原因、重试、跳过、合并、生成及保存过程；知识图谱时间线还会显示批次数、模型返回数量和合并去重后的保留数量。模型可以保留 thinking，但结果提取只读取最终文本并过滤 reasoning 内容；摘要和每次图谱调用分别预留 12000 与 24000 个输出 Token。最终模型若返回未选择的 Session 引用，会过滤该引用；严格模式下无有效来源的内容项会被跳过，最终页面列出实际总结的对话、失败对话和过滤数量。

生成过程时间线支持折叠和展开：进行中的任务默认展开，已完成结果中的历史时间线默认折叠。仅生成一种视图时会保留工作区中已有的另一种视图，不再用 `null` 覆盖其存储。思维导图使用递归树形布局并绘制父子连接线；严格来源过滤后少于 2 个有效节点的退化结果不会再作为成功视图保存，而会进入重试。知识图谱按关联度使用中心节点与自动扩展的多层环形布局，节点卡片内显示类型和最多两行名称，关系以带方向箭头的弱化曲线呈现，并通过描边区分推测或冲突内容；图谱置于固定且裁剪溢出内容的视口中，首次打开自动居中，可在空白区域通过不受边界限制的位移自由拖动，图谱能够部分或完全移出可视框。画布另提供 50%–200% 缩放、独立的 80%–220% 节点间距以及选中实体的一跳局部视图。

节点“继续对话”只形成一个可编辑的后续问题。确认导航后，插件使用公开的 Session 导航入口；如果当前 Runtime 没有向该槽位暴露草稿镜像，则提供“打开并复制问题”的安全降级，不自动发送消息。

## 生成失败诊断

Host 和生成编排器会输出带 `[conversation-knowledge-map]` 前缀的诊断日志。日志包含路由、Provider / Model、Agent Session、实时事件类型、surface/session 读取次数、提取文本长度、输出形状和错误原因，不记录 Prompt 或原始对话正文。为诊断结构化输出失败，当前还会记录模型实际返回文本：不超过 32000 字符时完整记录，超过时保留首尾各 16000 字符；该内容可能包含模型整理出的对话信息，排障完成后应按运行环境的日志策略清理。解析失败日志会额外列出 Markdown JSON 围栏、首末大括号位置以及每个候选对象属于未闭合、JSON 语法错误、合法但结构不符或合法目标结构。优先查看 DSH Web Runtime 的终端日志；若 Runtime 提供 logger 服务，则同时写入该 logger。重点关注 `agent output content`、`agent output parse failed`、`agent event`、`agent idle`、`agent turn failure`、`agent surface read` 和 `agent session read`。Runtime 在 `turn/end.reason.kind = error` 时会优先显示其 `code/message`；只有未发现 turn 错误且确实没有助手输出时，才会报告“模型没有返回 JSON 对象”。

## 本地验证

```powershell
node --test tests/conversation-knowledge-map.test.mjs
node --check market/conversation-knowledge-map/lib/index.js
node --check market/conversation-knowledge-map/lib/client.js
```

仓库测试通过后可同步到 DSH Web Profile；真实 DSH Web 视觉回放仍需重启 Runtime 后验证。