stratagate-dsh 0.3.1 → 0.3.3

package/docs/MEMORY_TOPICS.zh-CN.md

@@ -7,8 +7,10 @@
 - 用户画像继续单独常驻。目录说明记过哪些主题，并提供稳定的主题编号。
 - 目录只用于导航；主题概览把已有事件整理为背景、进展、决定、变化和待确认问题，每段保留事件来源。
 - 一个 Topic 对应长期的大章节，例如“StrataGate”“求职与职业发展”。节是能持续容纳同类事件的长期类别，例如“缺陷排查与修复”“版本发布与安装”“架构与配置决策”；单个 bug、版本、日期、任务和处理状态留在节内总览与原事件，不独立成节。已有类别能容纳时复用原标题，同类不同状态或不同版本不再拆节。分类随章的实际内容归纳，不套全局固定表，不设硬节数上限；归类不改变任何事件事实。
-- 同一章内同名总览段落归为一个稳定的节，与段落类型无关。标题按全半角、大小写及空白规范化匹配；没有标题时使用类型名称归组。节的 `.0 总览` 按各段最早来源在章节中的位置排序并原样展示内容；同位置按最晚来源位置及稳定内容排序，各段来源仍独立保存在原始派生数据中；`.1~N` 展示这些来源的去重并集，按事件在章节成员列表中的位置分页。增加段落不新增同名节，不改写旧总览，不增加模型调用或数据库迁移。
-- 小节按其来源在章内成员列表中的最早位置排序，不跟随模型输出段落的先后顺序；同位置用稳定节编号排序。已有成员在前、新事件追加在后，因此新事件形成的新节置后，旧节不会因为新总览前置而改号。更新后的目录视图版本使旧编号及分页缓存失效。
+- 小节归属单独保存在 `sections` 的标题与事件编号中；总览只概括内容并保留各段自己的证据引用。同一章内同名小节及总览按全半角、大小写和空白规范化匹配，与段落类型无关。新总览的展示标题必须匹配本轮声明或继承的小节；省略标题时，其类型对应的默认名称也必须匹配，模型解析和显式 `sections` 写入共用同一校验。总览不能自行建立无事件的小节；旧快照及无 `sections` 的旧 SDK 调用仍按来源和类型名称恢复，有效旧总览可原样保留。节的 `.0 总览` 按各段最早来源在章节中的位置排序并原样展示内容，同位置按最晚来源位置及稳定内容排序；`.1~N` 分页展示归入该节的事件，不要求总览引用每条事件。没有总览的小节仍展示事件，界面不显示空的 `.0 总览`。
+- 新模型结果必须为每条本批章节成员分配至少一个小节；总览可为空，旧小节归属和有效概要由存储层继承。只有本批事件可按显式新归属重新分类；非本批旧事件确认某条关系时，保留其其他小节归属。存储层先确定最终小节，再处理总览：重分类使旧小节没有事件时，丢弃对应旧总览，包括本轮原样回传的旧段；新总览指向已消失的小节则拒绝整次写入。小节仍有成员时继续保留有效旧总览，不为保存总览恢复已移走的事件归属。界面“待归类事件”只包含本章尚无小节归属的事件，与未被概括的事件数量分别计算。旧快照按已有总览来源恢复确定的小节归属；0.3.3 首次 writer 打开时，为已完成整理但仍缺少小节关系的旧事件排队一次定向补归类，包括此前已持久化 `sections` 的候选数据。补归类按原章分批，只更新该章的小节成员关系，保留章 ID、章名、描述、成员顺序、已知归属和有效总览，不重新提取事件。某事件属于多个章时逐章补齐；没有总览也必须写入真实归属。迁移标记及剩余关系持久化，重启不反复排队；只读访问不启动补归类。旧 SDK 调用缺少 `sections` 时仍兼容普通整理，补归类任务必须提供显式 `sections`。
+- 旧事件补归类复用历史整理后台，全库每 10 分钟最多 2 个历史任务，不重置已有额度；新增或修改的事件仍走优先增量路径。模型不可用或额度耗尽时暂留待归类，后台恢复后继续。工作单位是“章节、事件、来源版本”的关系：一个章节等待重试或耗尽重试不会阻止其他章节补齐同一事件。每个任务最多 3 次尝试，失败可通过现有“重新整理”入口发起新的有限周期；重启不会自动清零重试。目录保留未完成关系数及失败关系数，不把多个章节的关系压成一个事件来判断结算；仍有其他关系待处理时显示处理中，只剩终态失败关系时返回 `failed` 并显示未完成和重新整理入口，不报全部完成，也不保持正在处理的轮询状态。遗忘、归档或来源修改会撤销旧版本的补归类关系及过期结果。为控制输入，补归类候选省略旧总览，最多显示 120 个且合计不超过 4,000 字符的完整小节标题，明确提供省略数量；原章必须在实际模型输入中，不能静默裁掉或改分到其他章。
+- 小节按其成员在章内成员列表中的最早位置排序，不跟随模型输出段落的先后顺序；同位置用稳定节编号排序。已有成员在前、新事件追加在后，因此新事件形成的新节置后，旧节不会因为新总览前置而改号。更新后的目录视图版本使旧编号及分页缓存失效。
 - 主模型按需打开主题，再通过现有事件、图谱或原文工具取证，继续使用现有证据检查与采用流程。
 - 现有自动召回继续工作，目录与概览不能成为唯一检索入口。
 
@@ -28,7 +30,7 @@
 - 每章每次模型响应最多 8 段概要；这限制单次输出，不是累计段数或节数上限。有效旧段自动保留，不被新段挤掉；同名段仍聚合成一个节。章节累计内容与全量 JSON 存储的增量化另行跟踪。
 - 每批模型输入及输出有固定上限，调用有超时、有限重试和重启恢复；主模型上下文组装只读取目录。
 - 尚未整理和暂时失败的事件仍提供可验证的简略入口，不阻塞普通检索。
-- 每批最多整理 12 个事件，候选旧主题最多 12 个，模型输入含结构约束不超过约 20,000 词元。每段概览注明来源；主题展开限制约 2,400 词元，并说明省略范围。
+- 每批最多整理 12 个事件，候选旧主题最多 12 个，模型输入含结构约束不超过约 20,000 词元。每段概览注明来源；主题展开限制约 2,400 词元。展开结果优先保留轻量 `sections` 索引（标题和 `sourceEventCount`），包括无总览的小节，并用 `totalSections`、`omittedSections` 说明省略范围；索引、概要、省略计数和外层响应共用预算。全量小节成员关系只在服务端分页，不加入模型展开结果。
 - 主题目录按偏好与要求、决定与计划、工作与结果、交流与协作、其他经历分类；分类仅用于浏览，不改变主题内容和编号。完整目录每页最多 20 项。
 - 正式主题按创建时间从早到晚排列，新增主题追加；同一时刻仅以不可变的主题编号排序，改名不改变章序。注入目录、主题工具与界面共用这一顺序，待整理入口置后，展示章号不写入数据库。
 - Dashboard 只返回主题、节、总览段落及事件数量，不返回事件成员编号、全量标题或摘要；Bootstrap 失败详情也只传数量。完整成员关系保留在服务端。节编号由规范化标题派生，界面与分页共用同一聚合规则。展开节、待整理或失败详情时，用只读接口每页最多读取 9 条事件；数据版本变化时丢弃旧页。同类型但不同标题仍是不同节，同名段落合为一个节。

package/docs/event-extractor.md

@@ -0,0 +1,32 @@
+# Event Extractor v2
+
+新版规则只用于升级后正常提取的新 Event。不会重放旧 L5、改写旧标题、拆分或合并旧 Event，也不会回填分类提示或版本号。已有待处理任务仍按正常重试规则处理。
+
+## 提取判断
+
+判断独立含义及遗忘成本，而不是以重要性、criticality 或消息角色作为统一门槛。用户事实、评价、审美反馈、明确要求、纠正、改变决定和可复用指导采用较低提取门槛；普通 Agent / Tool 执行步骤采用较高门槛。已确认根因、平台限制、失败条件、可复用经验和重要结果仍可独立保留。Summarizer 的高召回预筛同步提示这些候选。
+
+保守使用现有 scope：单次答复要求保留 session 范围；项目要求使用 project；明确长期指导才可使用 user。重复纠正可以成为经验的证据，但不能把一次局部反馈扩大成永久人格或审美。两个能独立变化、被检索、冲突或替代的事实仍分开；原子化不等于记录每次工具调用。标题保留明确对象、稳定锚点和一个主要变化，详细原因留在 summary。
+Extractor 结构化输出必须明确返回合法 scope。工具调用及文本 fallback 都先进行同一 schema 验证；遗漏或非法值触发现有有界重试，重试仍失败时不写入 Event，不再默认扩大为 project。核心旧 Event、手工输入及自定义 Extractor 的兼容类型不变。
+
+## 重复与关系
+
+同一 Block 内的同义表达由模型识别为一条事实，保留直接支持它的目标消息 ID。适配层额外合并同一次输出中 title、summary、scope、criticality 和 temporal 完全相同的卡片，比较截断前的完整模型文本，合并目标来源及检索标签；不同事实、范围或关系不合并。
+精确重复卡的 catalogHints 保留第一张卡的归一化结果，包括第一张缺省时继续缺省；不合并或追加后续卡的类别。
+
+纯重复且没有新增长期信息可不提取；明确强化或延续用 sameEventId，替代/纠正用 supersedesEventIds，无法确认替代的矛盾用 conflictsWithEventIds。历史卡保留。相同项目、关键词近似不能单独建立关系。现有 timeline 仍最多提供 8 条相关及 4 条最近 Event，增加每条最多 400 字符的摘要、范围和历史状态以辅助识别；字段对自定义 Extractor 保持可选。timeline / neighbor 只供理解和关系匹配，不能为新事实提供来源。
+
+## 可选字段与兼容
+
+| 字段 | 语义 | 边界 |
+| --- | --- | --- |
+| `catalogHints?: string[]` | 长期类别的自由短语，仅供导航 | 最多 2 个，每个最多 64 个 Unicode 字符；可以缺省或为空；不设 enum 或 other/其他兜底，不指定目录 ID/路径，不改写标题来充当类别 |
+| `extractorVersion?: number` | 对话提取规则版本 | DSH Extractor 在代码中标记为 `2`，不让模型决定；旧卡、手工卡及其他 Extractor 缺省合法 |
+
+运行时限制提示数量，移除空白、重复、非法类型、明显兜底和目录 ID/路径；类别是否有来源、是否只是标题改写等语义约束由 prompt 负责。Topic Projector 可见 catalogHints 用于路由，但不能据此生成事实或决定章/节。Element 和 Graph 都用字段白名单构造 Event 模型输入，物理排除提示和版本号；Element 保留事实正文、引用、目标来源、时间、范围、criticality 和历史关系。检索的事实字段、provenance、时间、criticality 和 admission 机制不变。
+
+SQLite 用新增的可选 `event_metadata` 附表保存这两个字段，支持 passive / agent 两个 Event 池，随原有事务保存和清理。只为已有字段的卡写元数据行；不 ALTER 旧 Event 表或重建历史数据，存储 schema 仍为 12。旧库没有附表也可以只读打开；普通写入器打开时创建空表。旧 Event 的 API 字段形状保持原样，新字段存在时才输出。
+
+## 验证边界
+
+确定性测试验证 prompt/schema 合约、模型输出归一化、同 Block 精确去重、目标来源边界、relation 写入、SQLite 往返、旧库只读/升级、无历史重提取/回填，以及旧卡的检索、Topic、Graph、API 和 UI 路径。测试里的模型响应是 mock，并非真实模型语义准确率测量；同义识别、提取敏感度及泛化质量仍取决于实际模型。未新增模型调用、依赖、全局 consolidation 或目录算法。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stratagate-dsh",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "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",