stratagate-dsh 0.2.97 → 0.3.0

package/docs/DSH.zh-CN.md

@@ -102,7 +102,10 @@ DSH_HOME/stratagate/memory.db
 
 插件注册以下工具：
 
+记忆目录默认提供约 400 词元的导航。`memory_list_topics` 可分类分页或查询主题，`memory_expand_topic` 展开有来源的概览；这两个工具不生成证据批次，也不强化记忆。概览中的事实需用 `memory_search_events` 的 `topic_id` 参数查证，再走证据评估和采用流程。后台从已有事件小批量整理，失败或尚未整理时仍保留事件入口。详见[记忆目录与主题整合](MEMORY_TOPICS.zh-CN.md)。
+
 ```text
+memory_list_topics    memory_expand_topic
 memory_search_events   memory_expand_event
 memory_search_graph    memory_expand_graph_node
 memory_search_raw      memory_get_blocks

package/docs/MEMORY_TOPICS.zh-CN.md

@@ -0,0 +1,49 @@
+# 记忆目录与主题整合
+
+本次实现两项能力：默认可见的记忆目录，以及按需展开的跨事件主题概览。经验提炼不在本次范围内。
+
+## 使用方式
+
+- 用户画像继续单独常驻。目录说明记过哪些主题，并提供稳定的主题编号。
+- 目录只用于导航；主题概览把已有事件整理为背景、进展、决定、变化和待确认问题，每段保留事件来源。
+- 一个 Topic 对应长期的大章节，例如“StrataGate”“求职与职业发展”。节是能持续容纳同类事件的长期类别，例如“缺陷排查与修复”“版本发布与安装”“架构与配置决策”；单个 bug、版本、日期、任务和处理状态留在节内总览与原事件，不独立成节。已有类别能容纳时复用原标题，同类不同状态或不同版本不再拆节。分类随章的实际内容归纳，不套全局固定表，不设硬节数上限；归类不改变任何事件事实。
+- 同一章内同名总览段落归为一个稳定的节，与段落类型无关。标题按全半角、大小写及空白规范化匹配；没有标题时使用类型名称归组。节的 `.0 总览` 按各段最早来源在章节中的位置排序并原样展示内容；同位置按最晚来源位置及稳定内容排序，各段来源仍独立保存在原始派生数据中；`.1~N` 展示这些来源的去重并集，按事件在章节成员列表中的位置分页。增加段落不新增同名节，不改写旧总览，不增加模型调用或数据库迁移。
+- 小节按其来源在章内成员列表中的最早位置排序，不跟随模型输出段落的先后顺序；同位置用稳定节编号排序。已有成员在前、新事件追加在后，因此新事件形成的新节置后，旧节不会因为新总览前置而改号。更新后的目录视图版本使旧编号及分页缓存失效。
+- 主模型按需打开主题，再通过现有事件、图谱或原文工具取证，继续使用现有证据检查与采用流程。
+- 现有自动召回继续工作，目录与概览不能成为唯一检索入口。
+
+工具按需要选择：`memory_list_topics` 浏览或查询目录；需要主题脉络时用 `memory_expand_topic` 查看概览，需要事实证据时可直接用 `memory_search_events(query, topic_id)` 核实事件，再进入既有证据评估与采用流程。前两个工具不生成证据批次。空查询可浏览主题事件，使用返回的 `nextOffset` 继续分页；`temporalIntent` 可选择最早或最新记录。
+
+## 范围与维护
+
+- 目录覆盖当前命名空间内可见的对话事件和主动记忆，含没有图谱节点的事件。
+- 图谱展示聚类只是可选分组线索，不能将不相连节点的展示拼组当作语义主题。
+- 后台用已有事件分批整理历史，后续只处理内容、状态或关联变化。检索时间、采用次数和衰减不触发重新生成。
+- 首次写连接打开命名空间时，固定已有历史事件的版本清单，持久记录“待处理 → 处理中 → 已完成”；新命名空间冻结空集合并直接完成，随后新增事件都按增量处理。关闭或重启后接着处理未完成批次，已成功批次和主题编号保留；整理器版本升级时才开启新的回填清单。并发打开沿用先成功保存的清单，只读访问不初始化、不迁移。
+- 整个数据库的历史回填每 10 分钟最多启动 2 批，每批最多 12 条事件。额度在调用前持久预扣，各命名空间共用，重启不重置，失败重试也占额度；达到上限后保留简略入口，下一窗口继续。这个上限约束后台整理任务，模型桥内部的格式重试和适配器降级仍分别有固定上限，并不承诺固定金额。新增或语义变化的事件优先整理，不占历史额度。旧章因某条来源或背景依赖变化而整章失效时，其余未变化成员的重建必须共用这份历史额度，不能变成无限制增量任务。重建版本单独持久记录，不改写首次打开冻结的历史清单；旧测试版已失效的积压也保守归入历史额度。
+- 每轮最多尝试 3 次，失败等待至少 30 / 60 秒，历史额度不足时等待更久。用尽次数后停止自动重试。用户可在历史整理的失败详情中选择“重新整理这 N 条”：仅将该批当前有效来源排队为新一轮，仍占共享历史额度；成功批次不重做。来源变化、遗忘、过期目录及重复提交均不能强行复用旧失败；新任务编号拒绝旧结果。排队和进度持久保存，重启不重置预算。“已完成”表示本轮任务已结算，不代表所有批次成功。
+- 本次主题整理器升级到第 3 代。首次写连接打开第 2 代目录时，保留来源及依赖仍有效的章 ID、章名、成员顺序和创建时间，清空旧细节小节与旧派生任务/进度，冻结当时可见事件按新规则重新分批整理；节及节内编号会因本次重新分组更新。第 1 代碎章及混合/未知代目录仍整体退休，依赖已变化或隐藏的旧章语言不沿用。全程不修改事件、原文、图谱或采用记录，也不重置全库历史额度；新增及发生变化的事件继续优先。只读访问仅在内存预览：保留有效第 2 代章的导航，隐藏旧小节并保留事件入口；不启动历史整理、不写库。第 1 代旧目录仍隐藏。第 3 代成功进度和编号在重启后保留，不反复重建。
+- 旧章候选仍最多 12 个，排序结合全部已有节标题以及少量成员标题和标签。每个已展示候选提供全部轻量节标题、最多 4 段正文；节标题不授予未展示事件的引用权限。提示要求可容纳新事项时逐字复用已有节标题，不近义改名。同名章在已展示候选中唯一匹配时复用编号；全局已有同名正式章但未展示时拒绝结果，不静默创建重复章，显式改名也不能撞上另一章；不同项目仍独立归类，不引入永久跨章合并机制。
+- 失效只标记一次。模型遗漏主题编号时，存储层为明确的成员延续复用编号；无法唯一对应的旧失效主题，在所有仍可见成员成功处理后移除。分批成功进度不会被旧主题再次清零，过期模型结果仍拒绝。
+- 每章每次模型响应最多 8 段概要；这限制单次输出，不是累计段数或节数上限。有效旧段自动保留，不被新段挤掉；同名段仍聚合成一个节。章节累计内容与全量 JSON 存储的增量化另行跟踪。
+- 每批模型输入及输出有固定上限，调用有超时、有限重试和重启恢复；主模型上下文组装只读取目录。
+- 尚未整理和暂时失败的事件仍提供可验证的简略入口，不阻塞普通检索。
+- 每批最多整理 12 个事件，候选旧主题最多 12 个，模型输入含结构约束不超过约 20,000 词元。每段概览注明来源；主题展开限制约 2,400 词元，并说明省略范围。
+- 主题目录按偏好与要求、决定与计划、工作与结果、交流与协作、其他经历分类；分类仅用于浏览，不改变主题内容和编号。完整目录每页最多 20 项。
+- 正式主题按创建时间从早到晚排列，新增主题追加；同一时刻仅以不可变的主题编号排序，改名不改变章序。注入目录、主题工具与界面共用这一顺序，待整理入口置后，展示章号不写入数据库。
+- Dashboard 只返回主题、节、总览段落及事件数量，不返回事件成员编号、全量标题或摘要；Bootstrap 失败详情也只传数量。完整成员关系保留在服务端。节编号由规范化标题派生，界面与分页共用同一聚合规则。展开节、待整理或失败详情时，用只读接口每页最多读取 9 条事件；数据版本变化时丢弃旧页。同类型但不同标题仍是不同节，同名段落合为一个节。
+- 目录默认预算约 400 词元，原相关记忆预算为 900 词元。超过目录预算时提供可展开的分类和分页入口，不能静默隐藏剩余主题。
+
+## 必须始终成立
+
+1. 事件和原文是证据底座，目录与概览不写回为新事件，不登记采用证据，不强化记忆。
+2. 主题编号独立于展示聚类成员；每条可见目录文字和概览都有可验证的来源依赖。
+3. 来源被遗忘、归档、撤销或修改后，旧派生文字先停止曝光，后台再重建。不能通过原始对话重新总结来复活已隐藏的事件。
+4. 模型结果提交前重新核对读取时的来源版本；过期任务不能覆盖新版主题。
+5. 主题只在当前命名空间可见；安装级画像不自动并入项目主题。
+6. 历史、计划、取消、争议和当前事实不能在整合时混为一谈；缺少信息保留为待确认问题。
+7. 升级、失败和重启不会修改或删除已有事件、图谱和原始对话；目录可独立重建。
+
+## 验收
+
+验证模糊查询发现主题、无图谱事件覆盖、按主题取证、增量整合与稳定编号、隐藏来源即时失效、过期提交拒绝、零采用强化、命名空间隔离、旧库升级、重启恢复、有限重试、输入和目录预算，以及后台失败时原搜索继续可用。测试只使用临时数据库与模拟模型。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stratagate-dsh",
-  "version": "0.2.97",
+  "version": "0.3.0",
   "description": "Recent conversations stay vivid. Older ones fade into summaries, not oblivion. StrataGate gives DeepSeek Harness six-layer, time-decaying memory, while lasting events and relationships settle into a knowledge graph. Bring your memories from other AIs with you—no need to start over.",
   "type": "module",
   "main": "./dist/index.js",