dsh-companion

使用说明

配置 DeepSeek API Key（模块 C 前置）

1. 打开插件设置页的「开发者模式」总开关。
2. 在「API Key 管理」输入框粘贴你的 DeepSeek API Key 并保存。
   • Key 通过 AES-256-GCM 加密后存入 Harness 插件沙箱的 companion 存储域；
   • 任何接口响应、日志、事件中均不会出现 Key 明文（/cost/state 仅返回 apiKeyConfigured 布尔）。
3. 可选：点击「测试连接」验证 Key 有效性（对应 /cost/test-call）。

模块 A：导出对话

• 单次导出：对话界面头部操作区点击「导出」，或命令面板执行 export。选择格式（Markdown / PDF / JSON / PNG 长图），勾选是否保留时间戳（默认开启）、是否隐私脱敏，确认后文件经浏览器下载到本地。
• 回合级选择（吸收自 dsh-conv-export）：导出对话框内逐回合勾选——角色徽章（用户蓝 / 助手绿）+ 两行内容预览 + 时间，全选/全不选与已选计数实时更新；仅导出选中回合（如剔除失败的尝试或跑题的段落），默认全选。批量导出模式不参与回合选择。
• 导出进度与中止：光栅化导出进行中按钮实时显示「done/total」分片进度；「取消」按钮变为「中止导出」，中止信号贯穿 API 请求与逐片光栅全过程；导出进行中 Esc 不再关闭对话框（以中止按钮为唯一出口）。
• PNG 长图：整篇对话经客户端 canvas 光栅化（SVG foreignObject，2x 视网膜）为一张纵向长图直接下载；仅客户端界面可用（命令面板无 canvas），不参与批量 ZIP。
• 批量导出：导出对话框勾选「批量导出」进入可视化多选界面——全选/全不选工具栏、已选计数（n/N）、按标题或会话 ID 实时筛选（全选作用于当前筛选结果并与已有选择取并集）、勾选行高亮与未勾选行淡化；确认后自动打包为 ZIP 下载（单次最多 100 个会话，自动去重；命令 export-batch 仍可直接按 ID 列表导出）。
• PDF 说明：纯 Latin-1 内容直接生成结构化 PDF 文件；含中文等非 Latin-1 字符时由客户端光栅化为免打印多页 PDF（A4 分页、JPEG 编码、零依赖 PDF 组装），全程无 window.print() 对话框——该路径在部分平台（尤其 Windows Chrome）会冻结整个浏览器；无光栅能力的环境（命令面板）退回打印视图由浏览器另存为 PDF。

模块 B：交接摘要

• 生成：对话头部点击「交接摘要」按钮（或命令 handoff），对话框顶部的会话选择面板默认选中当前会话（带「当前」徽章）并自动生成摘要；也可按标题 / 会话 ID 筛选后选择任意历史会话生成（选中即自动重新生成，切换会取消在途请求并重置编辑状态）。插件调用 DeepSeek API 按固定四段式 Prompt 生成摘要：核心结论 / 已解决的问题 / 关键背景信息 / 待办事项与未解决问题（≤500 字）。
• map-reduce 分层摘要（上下文工程 2.0）：超长会话超出单次摘要字符预算时自动分块——map 阶段逐段要点摘要（段级缓存，未变更的分块不重复调用），reduce 阶段递归归并为最终摘要；统计信息展示分块数与缓存命中数。
• 查询聚焦：摘要对话框输入聚焦主题（如"部署流程"、"性能优化"）后重新生成，Prompt 将定向保留与主题相关的内容，无关细节被压缩——同样的预算，更相关的上下文。
• 上下文血缘图谱：摘要对话框底部展示该会话的血缘——内容从哪些会话流入（来源链）以及摘要流向了哪些会话（后代链），每条记录带深度与内容摘录，跨会话的上下文传播一目了然。
• 上下文压力监测（GET /handoff/context-health）：摘要对话框顶部的压力仪表实时展示选中会话的 token 占用——估算 token 数与占用百分比进度条、按近 N 回合平均增速外推的"还可聊多少回合"耗尽预测、四级健康分级（healthy / watch / advice / critical）与对应交接建议；帮助用户判断"现在交接是否已经太迟"。
• 编辑与复用：摘要在可编辑弹窗中展示，支持「复制到剪贴板」与「保存为模板」；模板可后续查看、删除，生成摘要时也可指定已有模板作为指令文本（缺省回退固定契约 Prompt）。
• 导入继承：新建对话时通过输入区 dock 的「导入历史摘要」入口（或命令 handoff-import）粘贴摘要。插件将其武装给下一个新对话，自动作为 system 角色第一条消息注入，实现跨对话上下文继承。

模块 C：成本优化

• 官方动态计价：计价引擎每小时抓取 DeepSeek 官方定价页（含峰谷分时计划）与智谱/百度文心/字节豆包/Kimi 等国产厂商定价页，自动发现带价模型并导入；官方价格内容变化时持久化新快照，重启后沿用；抓取失败静默降级为内置刊例价快照，不影响实时计价。用户可按模型 id 自定义单价覆盖（最长前缀匹配）。
• 峰谷分时计价：官方定价页声明的高峰时段（缺省北京时间 9:00–12:00、14:00–18:00）按高峰价计费，空闲时段按空闲价；缓存命中的输入按折扣价计费。
• 峰谷自动调度：开启后，任务可标记「紧急 / 普通」。「普通」任务在高峰时段进入延迟队列（容量上限 100），自动等到空闲时段再发起 API 调用；高峰窗口优先取计价引擎对官方定价页的实时解析，异常时回退内置缺省窗口；预算暂停期间排队任务会在执行前被复检拦截；交互式操作（如生成交接摘要）按「紧急」处理，不参与延迟。
• 模型智能路由：开启后按任务类型自动选模 —— 翻译、摘要等简单任务走 deepseek-chat，代码生成、推理等复杂任务走 deepseek-coder；支持自定义路由规则覆盖默认策略。
• 日/月双档预算：分别设置日预算与月预算上限（CNY，0=不限）。任一档消耗达 80% 时通过 Harness 通知系统提醒；达 100% 时再次提醒并自动暂停非必要 API 调用（必要调用仍放行但持续告警）。
• 成本报表：独立视图页提供详尽可视化面板——汇总卡片（调用数 / Token 总量 / 费用 / 节省金额 / 延迟执行数 / 缓存命中率 / 日均费用 / 峰值日）、日/月预算进度条（80% 黄、100% 红）与在途调用预授权展示、每日 Token 图（输入/输出堆叠）、每日费用与节省对比图、模型费用排行（水平占比条 + 调用数与费用占比）、缓存命中结构条（命中折扣价 / 未命中全价）、峰谷 24 小时时间轴（高峰段高亮）、多厂商定价概览（厂商 + 模型数 + 实时/快照/自定义来源徽章）、定价来源与抓取时间，支持手动触发官方定价刷新。命令 usage 可在面板内快速查看本月文本报告。
• 预测性成本智能（HTTP API，供报表视图与外部集成消费）：
  • GET /cost/forecast：支出预测——OLS 线性回归拟合「日费用 ~ 时间」趋势并外推未来 N 天，返回趋势斜率、拟合优度 R²、日均费用、逐日预测点与月末费用投影（已花费 + 未来预测到月底）；历史不足 5 天时返回 sufficient: false。
  • GET /cost/anomalies：异常检测——中位数 + MAD（绝对中位差）鲁棒 z 分数定位费用异常日，对离群值免疫（均值/标准差会被异常值本身污染）；按严重度分级（mild / high / critical）并返回期望值与偏离倍数。
  • POST /cost/what-if：场景沙盘——在历史基线上叠加调用量倍数、目标缓存命中率、模型迁移（from → to 比例）三种算子的任意组合，返回基线 vs 投影的日费用、30 天投影与按模型分解。
  • GET /cost/attribution：变化归因——对比最近 N 天与前 N 天两个等长窗口，按模型分解费用变化贡献份额（降序），回答"这个月多花的钱去哪了"。

模块 D：全局检索与对话内搜索

• 历史对话列表顶部注入全局搜索框（或命令 search）：
  • 关键词：模糊匹配全部历史对话内容；
  • 时间：日期选择器按范围过滤；
  • 标签：命令 tag 或结果页为会话增删自定义标签，支持按标签筛选。
• 搜索结果以列表呈现，附命中片段，点击直达对应对话。
• 对话内搜索（吸收自 dsh-conv-search）：对话头部点击「对话内搜索」或按 Ctrl/Cmd+F 打开浮动查找栏：
  • Enter / Shift+Enter、F3 / Ctrl+G：下一个 / 上一个命中（环绕）；Esc 关闭；↑ / ↓ 浏览查询历史；
  • Aa / ab 开关：区分大小写 / 全词匹配；
  • 高亮经 CSS Custom Highlight API 以覆盖层绘制，不触碰 React 管理的转录 DOM；模型流式输出或加载更早消息时经 MutationObserver 自动重同步，激活命中按「文本节点 + 偏移」身份保持，不跳动读者的滚动位置；
  • 匹配只扫描对话滚动视口，自动排除输入区草稿与搜索栏自身，无幻影命中。

模块 E：本地语义检索（检索智能）

• 检索视图页顶部的模式 Pill 一键切换语义检索（混合排序）与关键词检索（FTS）。
• 混合排序：每条命中附词法排名与语义排名徽章及 RRF 融合分——BM25 捕捉精确词法匹配，字符 trigram 哈希向量捕捉"字符组成相似但用词不同"的近义表达（中英混排、拼写变体），RRF 倒数排名融合两路结果，对单路失效鲁棒。
• 查询智能（轴线 8）：检索前对查询自动做两级扩展，扩展词只追加不替换——
  • 拼写纠错：查询词不在语料词表时，用 trigram 余弦在词表里找最近邻（≥ 0.55 且该词真实出现 ≥ 2 次才采纳）——"perfomance" 自动救回 "performance"，纠错候选必然可在你的对话里命中，不猜通用词典；
  • 共现扩展：对语料中真实出现的查询词，经倒排表直达包含它的文档，统计同文档共现词的 salience（共现文档数 × IDF）取最强者——从你自己的语料学到术语关联（中文提问 ↔ 英文术语、缩写 ↔ 全称），随对话积累自进化；
  • 扩展溯源随响应返回（expansion.notes），检索视图页的智能提示栏以 Pill 展示"auth←鉴权（共现）"，扩展行为完全可解释。
• 时序感知排序（轴线 9）：融合分乘性新近度加成 1 + 0.25 × 2^(-年龄/30天)——排名语义不变，仅把同等相关性向近期轻推（最新文档最多 +25%，相关性仍占主导）。
• 质量诊断（轴线 10）：每次检索返回四级判定（strong/fair/weak/empty）+ 相关度强度（头部融合分 / 理论满分）+ 双通道覆盖率 + 区分度 + 可执行建议；空结果区分"索引未建立"与"查询写法问题"；智能提示栏一行人话把黑盒分数翻译成"这次检索可信吗"。
• 在线学习排序（轴线 28，FTRL-Proximal）：点击即训练——你点开的会话为正例，呈现序中排在它之上的未点击会话为 skip-above 负例（降权 0.25），逻辑回归经 FTRL-Proximal 在线优化（逐坐标自适应学习率 + L1 稀疏 + L2 平滑）；特征 = 词法名次 / 语义名次 / 新近度 / 反馈画像 / 标题匹配 / 偏置。学到的乘数 1 + 0.3 × (2p−1) × warmup 温和上浮你更可能点击的会话（±30% 封顶，warmup 随训练量渐进防小样本过调），只调序不颠覆排序语义；模型持久化到存储域，重启不丢。GET /retrieval/status 附 ranker 诊断（训练量 / 点击数 / warmup / 逐特征权重方向——模型学到了什么完全透明）。
• 检索盲区分析（轴线 19，GET /retrieval/blindspots / 命令 blindspots）：零命中（且救援也失败）的查询自动写入日志——"反复想找但历史里没有"是最真实的知识缺口信号。分析时按词元聚合（多主题长查询同时给每个主题锚记一次敲击），盲区评分 = 搜索次数 × log(1 + 首末停留天数) × 新近度（90 天半衰），孤例失败不推送；每个盲区附查询原形与一句话行动建议。
• 主动脉搏（轴线 18，GET /retrieval/insights / 命令 pulse）：主动洞察引擎——信号提供者注入式架构聚合盲区缺口（轴线 19）、反馈学习画像（轴线 11）、索引健康（覆盖率/最近同步）三类信号源为洞察卡片；按严重度（critical/watch/info）排序、封顶 6 条、单一信号源失败静默隔离；检索视图页「主动脉搏」按钮即开即合成。
• 零外部依赖：全部计算本地完成，无嵌入模型、无网络请求，隐私红线——不上传任何第三方。
• 惰性增量索引 + 增量语料统计：每次检索前对账会话列表（updatedAt 漂移检测，5 秒节流），仅重读变更会话；termDf/gramDf/平均长度/词元倒排表随 put/delete 增量维护，无过滤查询直读缓存（免全语料扫描，实测提速 37 倍）；索引持久化到存储域，重启不丢。POST /retrieval/reindex 可手动全量重建。
• 命令面板执行 find 同样走混合检索，输出附查询扩展溯源与质量摘要行。

模块 F：对话知识资产

• 全局实体图谱：检索视图页底部的知识面板展示覆盖会话数最多的头部实体（命令 / 路径 / 技术 / 代码 / 术语 / 版本六类徽章）；点击任一实体直接以实体名发起检索——知识图谱变成检索入口。
• 单会话洞察：检索结果行点击「知识」按钮，面板展开该会话的洞察：
  • 实体列表：按显著性（freq × 类型权重 × IDF）降序，附频次与全局覆盖数；
  • 建议标签：头部实体推荐为标签，一键应用到该会话（复用模块 D 标签系统；只建议不自动写入，尊重用户判断）；
  • 关联会话：基于实体重叠推荐相关历史对话（IDF 加权——共享稀有实体比共享常见实体更能说明"在谈同一件事"；余弦式归一避免长会话偏向），附共享实体与相似度，点击直达。
• 实体抽取为纯本地规则：行首命令动词表、路径模式、技术专名（缩写 / 驼峰 / 高频首字母大写）、代码标识符（驼峰 / snake_case / 反引号 / 点号链）、中文引号术语、版本号——零 LLM 调用、零成本、零隐私外泄。
• 主题趋势演化（GET /knowledge/trends）：知识面板顶部展示实体动量榜——对比近 N 天与上一 N 天两个等长窗口的实体频次，计算动量（变化率）并判定 rising / falling / stable 三向；每行附迷你周级柱状图（最近 8 周逐周覆盖会话数），点击趋势行直接以实体名发起检索；动量排序优先 |momentum| × log(总频次)，避免"3→6 次"的小样本噪声压过真正的长期趋势。
• 前瞻记忆引擎（轴线 20，GET /knowledge/cognition / /knowledge/intentions / 命令 todo）：对话里说过要做的事（"明天试试这个方案"、"下周再优化"、"回头重构"）自动提取为前瞻意图——时间标记（明天/后天/周末/下周/下个月，模糊标记取 7 天缺省视界）× 意图动词共现判定，问句排除（"怎么修复？"是求助不是承诺）；到期后主动浮现（超期越久越靠前，≥14 天升级为 critical 洞察）——"5 天前你说要试试 X，做了吗？"兑现或放下，都好过遗忘。
• 间隔重复巩固（轴线 21，POST /knowledge/review/grade / 命令 review）：从对话中提取"问题 → 解法"片段作为知识卡片（问题行 × 窗口内解法行配对），SM2 精简版间隔调度（1/3/7/14/30/60 天阶梯）——到期提醒复习，检索式练习（先看问题回忆解法，再翻开核对），"记得"升档、"忘了"归零次日重来；新片段先沉一晚次日首复习，对抗遗忘曲线。
• 类比检索（轴线 22，GET /knowledge/analogy?q= / 命令 analogy）：把问题抽象为结构形状（约束类别 × 解法类别：网络/性能/版本/依赖/并发…），跨全部历史经验做形状级匹配——相似度 = 0.7 × 约束重叠系数 + 0.3 × 解法重叠系数；主题词元重叠低而形状分高判定为跨域类比（领域不同而结构相同，如 docker 网络隔离 ↔ k8s service 互通——主题检索永远找不到的先例），单独标注优先展示。
• 遗忘预测引擎（轴线 23，GET /knowledge/forecast / 命令 forecast）：为每一条知识片段给出连续的记忆画像——艾宾浩斯指数衰减模型 R(t) = exp(-t/S) 计算当前保持率（含从未进入复习循环的旧片段），稳定性 = 档位间隔 × 个体节律 × 标定因子（标定保证「到期时刻的预测保持率恰等于阈值」，与轴线 21 调度数学自洽）；三档分区：≥70% 稳定 / 30–70% 滑落区（最佳巩固窗口，救得回来）/ 40）不作桥证据，病态稠密图预算熔断。暗连接是研究建议而非事实——它们回答"下一场对话值得把谁和谁放到一起"，暗物质清单 = 知识宇宙里最值得点亮的暗区。与轴线 27 的分工：星图沿已有边扩散引力（已知连接的深挖），暗物质预测缺失边（未知连接的发现）。
• 认知面板：检索视图页「认知面板」按钮（CognitionPanel）一屏整合六轴——到期意图列表（超期徽章 + 即将到来预告）、遗忘预测区（保持率进度条 + 分区徽章 + 距跌破阈值倒计时，滑落区优先展示）、复习卡片（负荷分诊结论 + 回忆 → 核对 → 自评闭环 + 节律系数标记）、类比检索框；洪峰时复习区顶部显示顺延徽章与负荷摘要；「主动脉搏」同时聚合认知脉搏（到期意图 / 复习 / 片段资产 / 遗忘预测 / 节律 / 负荷 / 主题漂移 / 记忆固化八类信号），认知信号与检索信号统一推送。
• 命令面板执行 insight（全局图谱）或 insight （单会话洞察）。

模块 G：跨会话知识合成（Deep Research）

• 入口：检索视图页搜索框旁的「深度研究」按钮（输入问题后点击），或命令面板 research （如 research 我之前对性能优化得出过哪些结论？）。
• 块级检索：候选会话（FTS 关键词召回 + 近期会话兜底，封顶 32 个）按回合分块（1800 字符/块，回合不跨块），每块经词法命中率 + trigram 余弦双通道打分（各占 50%），复用模块 E 的同源分词器但粒度到块——检索的是"证据片段"而非"会话"。
• 次模证据选择（轴线 29）：设施选址次模目标——块相关分 + 问题方面覆盖（方面 = 问题词元，权重 = 稀有度：包含该词元的候选块越少越重要，长尾词是问题的真指纹）。次模性让"第二块讲同样内容"的证据边际增益自动归零（冗余被目标函数惩罚），三块各讲一半的互补证据反而胜出——分数降序看不见这一点；惰性贪婪（CELF）按边际增益/成本比维护优先队列，评估次数远小于朴素贪婪，逼近 (1−1/e) ≈ 63.2% 最优。三重约束：至多 10 块、单会话封顶 3 块、总预算 26000 字符（尾部块按剩余预算截断而非丢弃）。
• 契约式合成：合成 Prompt 强制三条纪律——只使用证据中出现的信息（不足时明确回答"证据不足"）、每个关键论断带 [编号] 引用标注、先给直接结论再列依据且矛盾明示；回答即带引用的"迷你研究报告"。
• 结果展示：回答下方列出全部证据来源（会话标题 + 日期 + 摘录），点击直达原会话；统计行显示检索会话数 / 命中块数 / 采用证据数 / 合成模型 / 证据方面覆盖率（选择质量一眼可见）。
• 知识演化追踪（轴线 17）：合成后对证据块做纯本地信念比较——提取主题锚（技术专名）+ 版本号/数值声明，同锚不同值即演化事件（旧值 → 新值 + 双方时间戳与会话）；语义化版本比较（v2.10 > v2.9）判定升级/回退，事件按时间升序排成信念时间线。研究面板的「知识演化」区块展示——"这个结论后来被推翻/升级过"一目了然，零 LLM 开销。
• HTTP API：POST /synthesis/answer（body: { question }）、POST /synthesis/preview（零 LLM 证据预演）→ { answer, model, sources[], evolution, stats }，供外部集成消费。

---

配置 DeepSeek API Key（模块 C 前置）

1. 打开插件设置页的「开发者模式」总开关。
2. 在「API Key 管理」输入框粘贴你的 DeepSeek API Key 并保存。
   • Key 通过 AES-256-GCM 加密后存入 Harness 插件沙箱的 companion 存储域；
   • 任何接口响应、日志、事件中均不会出现 Key 明文（/cost/state 仅返回 apiKeyConfigured 布尔）。
3. 可选：点击「测试连接」验证 Key 有效性（对应 /cost/test-call）。

配置参考

根配置（cordis.patch.yml 可覆盖任意字段）：

字段	类型	默认值	说明
enableExport	boolean	true	启用模块 A
enableHandoff	boolean	true	启用模块 B
enableCost	boolean	true	启用模块 C
enableSearch	boolean	true	启用模块 D
enableRetrieval	boolean	true	启用模块 E（本地语义检索）
enableKnowledge	boolean	true	启用模块 F（对话知识资产）
enableSynthesis	boolean	true	启用模块 G（跨会话知识合成）
apiBaseUrl	string	https://api.deepseek.com	DeepSeek API 基址（manifest 已放行该域名）
apiTimeoutMs	number	60000	单次 API 调用超时（毫秒）

停用单个模块：将对应开关置为 false（配置层），或在 manifest.json 的模块声明中关闭。模块之间零耦合，停用一个不影响其余模块。

---