stratagate-dsh 0.3.15 → 0.3.17

package/docs/DSH.md

@@ -237,9 +237,13 @@ For diagnostics, the five most recent successful memory-model responses are reta
 
 ## Compatibility and permissions
 
-Installation peers and startup checks support the complete DSH `0.2.0` version family: all Alpha, Beta, RC, and stable releases (`>=0.2.0-0 <0.2.1-0`), without enumerating individual prereleases. Previously supported DSH `0.1.2-rc.1`, CLI `0.1.5-rc.1` (internal packages `0.1.5-rc.2`), `0.1.6-alpha.1`, and the `0.1.7` family from rc.1 through stable remain supported. Startup still requires one coherent internal DSH version and compatible Cordis `4.0.x` patches from `4.0.4` and Schemastery `3.18.x` patches from `3.18.4`; older hosts retain their original dependency families. DSH `0.1.8`, `0.2.1`, and their prereleases remain excluded.
+DSH `0.2.1-rc.1` reads the unified host declaration `engines.dsh: "0.1.2-rc.1 || >=0.1.5-rc.1 <0.3.0-0"`; older hosts use the peer declarations. CLI `0.1.5-rc.1` shipped internal packages at `0.1.5-rc.2`, explaining the different lower bounds.
 
-Development dependencies are pinned to DSH `0.2.0-rc.2` for reproducible checks. The release-gate matrix is configured to verify the previously listed older hosts plus `0.2.0-rc.1` and `0.2.0-rc.2` on Node `24`, Linux, and Windows. `dshWorkshop.compatibility.dshVersions` records concrete verification hosts; installation compatibility comes from the full peer ranges, so that test list does not restrict future `0.2.0` updates.
+Installation peers use continuous compatibility ranges: `0.1.2-rc.1 || >=0.1.5-rc.2 <0.3.0-0` for general DSH interfaces and `>=0.1.5-rc.2 <0.3.0-0` for Session Format interfaces. Existing legacy adapters remain available. Hosts such as `0.2.1-rc.1` and later `0.2.x` updates need no individual whitelist entries or patch-version upper bounds. DSH `0.3.0`, including every prerelease, remains outside the support boundary until its key interfaces are verified. DSH checks these ranges with `includePrerelease`, accepting alpha, beta, RC, and stable versions within the boundary; ordinary npm range matching does not guarantee acceptance of later prereleases.
+
+Startup still requires one coherent internal DSH version. From the `0.2.0` prereleases onward, Session Format packages must also match the core version. Modern hosts require Cordis `4.0.x` patches from `4.0.4` and Schemastery `3.18.x` patches from `3.18.4`; older hosts retain their original dependency families. Before migration or database access, startup checks tool registration, system prompt, model streaming, and default model selection interfaces. The migration loader also validates codec, migration-stage, and restoration entry points before proceeding. Missing interfaces stop the operation with a specific diagnostic. Method presence alone does not prove behavioral compatibility: strict artifact validation, immutable source generations, and recovery receipts remain in place. A continuous range does not mean every version within it has been tested.
+
+Development dependencies remain pinned to DSH `0.2.0-rc.2` for reproducible checks. `dshWorkshop.compatibility.dshVersions` records concrete regression hosts rather than an installation whitelist. Use `DSH_VERSION=<version> node scripts/run-dsh-compatibility.mjs` to check a new host within the peer ranges. Current repository policy skips GitHub CI and Roadmap synchronization while retaining local verification.
 
 On DSH `0.2.0`, the host-owned `dsh-session-format`, `dsh-session-format-catalog`, and `dsh-session-format-v0-to-v1` packages must also match the core DSH version. Mixed or missing Session Format packages stop startup before legacy migration; earlier hosts retain their existing compatibility rules.
 

package/docs/DSH.zh-CN.md

@@ -214,11 +214,13 @@ Topic Projection 优先将全部本批 Event 完整分配到章节和小节。
 
 ## 兼容性与权限
 
-安装声明与启动检查支持整个 DSH `0.2.0` 版本族：全部 Alpha、Beta、RC 和正式版（`>=0.2.0-0 <0.2.1-0`），无需逐个列出预发布版本。此前支持的 DSH `0.1.2-rc.1`、CLI `0.1.5-rc.1`（内部包 `0.1.5-rc.2`）、`0.1.6-alpha.1`，以及从 rc.1 到正式版的 `0.1.7` 仍受支持。启动时仍要求核心 DSH 包来自同一个版本，并限制 Cordis 为 `4.0.x`（从 `4.0.4` 起）、Schemastery 为 `3.18.x`（从 `3.18.4` 起）；早期宿主保留其原有依赖族。`0.1.8`、`0.2.1` 及其预发布版本均不在支持范围内。
+新版 DSH（从 `0.2.1-rc.1` 起）直接读取统一宿主声明 `engines.dsh: "0.1.2-rc.1 || >=0.1.5-rc.1 <0.3.0-0"`；旧版宿主继续使用 peer 声明。CLI `0.1.5-rc.1` 对应内部包 `0.1.5-rc.2`，两者下限不同是历史发布差异。
 
-开发依赖固定为 DSH `0.2.0-rc.2`，保证检查可复现。发布门禁配置在 Node `24`、Linux 和 Windows 上验证此前列出的旧宿主，以及 `0.2.0-rc.1` 和 `0.2.0-rc.2`。`dshWorkshop.compatibility.dshVersions` 记录用于验证的具体宿主；安装兼容性由完整的 peer 版本范围声明，测试版本列表不会限制新的 `0.2.0` 更新。
+安装声明使用连续兼容范围：普通 DSH 接口为 `0.1.2-rc.1 || >=0.1.5-rc.2 <0.3.0-0`，Session Format 接口为 `>=0.1.5-rc.2 <0.3.0-0`。保留已有旧版适配，取消每次宿主升级都追加白名单和设置补丁版本上限的做法；`0.2.1-rc.1` 及后续 `0.2.x` 更新无需逐版追加。`0.3.0` 及其全部预发布版暂不接纳，待关键接口验证后再调整边界。DSH 的兼容检查启用了 `includePrerelease`，范围内的 Alpha、Beta、RC 和正式版均可匹配；普通 npm 的默认范围匹配不保证接纳后续预发布版。
 
-在 DSH `0.2.0` 上，由宿主提供的 `dsh-session-format`、`dsh-session-format-catalog` 和 `dsh-session-format-v0-to-v1` 也必须与核心 DSH 包版本一致。Session Format 包混装或缺失时，插件会在旧会话迁移前拒绝启动；早期宿主保留原有兼容规则。
+运行时仍要求核心 DSH 包来自同一个版本；从 `0.2.0` 预发布版起，也要求 Session Format 包与核心版本一致。新版宿主的 Cordis 保持 `4.0.x`（从 `4.0.4` 起）、Schemastery 保持 `3.18.x`（从 `3.18.4` 起），早期宿主保留其原有依赖族。启动时先检查工具注册、系统提示词、模型调用和默认模型选择接口，再迁移会话或打开数据库；迁移模块加载后，先验证编解码器、迁移阶段和恢复校验入口。接口缺失时给出具体名称并停止操作。方法存在不保证行为完全兼容，迁移仍保留严格内容校验、原始代际不变与恢复收据；连续版本范围也不代表已实测其中每个版本。
+
+开发依赖固定为 DSH `0.2.0-rc.2`，保证检查可复现。`dshWorkshop.compatibility.dshVersions` 记录用于回归验证的具体宿主，不是安装白名单；安装兼容性由 peer 版本范围声明。可通过 `DSH_VERSION=目标版本 node scripts/run-dsh-compatibility.mjs` 验证范围内的新宿主。按当前仓库约定跳过 GitHub CI 与 Roadmap 同步，保留本地验证。
 
 DSH 核心包现在都是由宿主提供的可选 peer。若某个 profile 曾在本地安装这些 peer，升级后、启动前运行 `dsh plugin --profile <名称> exec stratagate-dsh-repair`。该命令只会把已知 DSH 运行时包移动到 profile 内的 `.stratagate-runtime-backups` 并写入恢复收据，不会删除包或触碰会话数据。启动时 bootstrap 还会把 StrataGate 自身的 DSH 导入定向到宿主维护的共享模块回退目录，再检查实际解析出的 DSH 核心族；未知宿主会立即给出明确错误并停止，而不是让正文区域空白。对于受支持的 DSH `0.1.5`、`0.1.6`、`0.1.7` 和 `0.2.0`，含已废弃 `stratagate/memory-citations` 事件的 v0 会话会先复制成经过校验的 v1 代际，再由宿主继续其迁移链；原始 v0 日志不会被修改，并写入 `stratagate-legacy-citations-v1.json` 记录源/目标哈希和恢复说明。
 

package/docs/feedback.md

@@ -0,0 +1,50 @@
+# StrataGate 邮件反馈与本地运行诊断
+
+反馈针对 StrataGate 插件的故障、使用疑问和改进建议。默认流程：用户要求或接受整理反馈 → Agent 写草稿 → 程序附加本地诊断快照 → 用户在插件内检查完整报告 → 复制到自己的邮箱发送。收件地址为 `jiahongcheng61@gmail.com`。
+
+## Agent 信息与交互
+
+- 常驻策略只说明作用域、主动建议门槛和诊断入口。工具说明包含填写依据与更新语义；详细运行数据按需返回。
+- 当前 DSH 默认 native 模式在组装模型请求时提供可见工具的名称、说明与参数；这两个工具采用该方式。PTC 模式由宿主生成工具 SDK 声明。渐进披露用于运行摘要、分页异常与诊断详情：常驻保留短入口，调用后再读取数据，生成草稿时由程序直接附加完整本地快照。
+- `feedback_prepare` 自动整理本地诊断摘要，返回草稿链接与尚未发送状态。新问题用 `new_draft=true`，修改时省略字段保留原值，空字符串或空数组清空字段。用户编辑过的自定义 Markdown 内容会保留。
+- `stratagate_diagnostics` 默认读取当前记忆空间摘要，使用返回的 `id` 获取脱敏详情，使用 `nextOffset` 分页。诊断属于运行数据，不走语义记忆检索与强化。
+- 已填好的 AI 草稿直接进入检查页；修改、完整预览、复制、邮箱和下载位于同一流程。报告预览固定后，复制与下载使用同一快照；用户修改后重新检查。
+- 对话里的同源反馈链接由插件接管点击，阻止宿主 Markdown 将其再次交给侧边浏览器。DSH 0.2.0 通过 `sidebar.settings` 中共享的设置面板 store 打开插件页，反馈空间和目标页由插件传递；关闭重开和已打开面板内切换空间均保留目标草稿。
+- 桌面主界面使用 `dsh-app://app/`；插件通过桌面预加载桥接 `dshDesktopBoot.ready()` 的 `streamBaseUrl` 确认当前 HTTP 后端，仅接管该后端根路径下的有效反馈链接。启动信息未返回时保留首次点击，确认归属后进入设置；其他实例或读取失败则交回宿主原有链接行为。桌面草稿导航沿用主界面的认证代理，直接在当前面板切换。
+- 明确、持续影响当前任务的插件问题才适合主动建议，先处理问题，每个会话最多建议一次，接受后准备草稿。普通后台重试只记本地诊断，保持聊天安静。后台诊断不自动注入模型上下文。
+- 页面提供可复制的 AI 请求提示词，用户回到相关会话发送。直接请求已经授权创建草稿。
+
+## 数据范围与统计口径
+
+运行数据保存在本地数据库的 `stratagate_dsh_diagnostic_*` 表，与核心记忆快照分开。调用结束、操作完成/失败、检索与工具结果等事件只入有界缓冲，最长约五秒批量落盘；正常关闭时尽力刷盘。最多缓冲 256 条，超出丢弃最旧记录并报告丢弃数。数据库忙时立即放弃本次写入并保留缓冲，统计失败不使聊天或记忆任务失败。
+
+原始诊断最多保留七天、全库最多 2000 条；按 UTC 日、记忆空间、模块、模型和插件版本的汇总最多保留九十天、全库最多 10000 行。报告覆盖最近七个 UTC 日（含今天）；最多读取 2000 行汇总、展示 40 组模型/版本明细和一页 20 条异常，截断与下一页位置均明确返回。尚未落盘的缓冲在异常退出时可能丢失；写入失败和缓冲丢弃计数属于当前进程，报告保留采集开始时间与缺失说明。
+
+- `modelCalls`：实际经过采集器的流式请求尝试，包括失败、取消、截断、内部重试。
+- `modelCancelled`：流式 aborted 结束、直接抛出的 AbortError/ABORT_ERR 或消费方提前结束；取消与 `modelFailed` 分开计数，已返回 usage 仍保留。
+- `operations`：一次记忆模型操作，包含其内部内容修正及路由回退请求。它与持久化后台任务的整个生命周期不同。一次失败后由后台再次执行，会形成另一条操作记录。
+- `validationFailures`：请求返回后，内容格式或语义校验失败。请求传输成功并不保证内容合格。
+- `operationsRecovered`：同一操作经历多个请求后完成；包括兼容回退。首次成功率、操作失败率、恢复率均提供操作样本数，耗时为均值。
+- `pipeline`：生成报告时现存摘要、Event 提取、图谱、主题和导入任务的状态。历史重试详情受原始记录保留范围限制；`oldestPendingUpdatedAt` 是最早的待处理任务最后更新时间。
+- Token 使用适配器报告值。DSH 的未缓存输入、缓存读取、缓存写入互斥；reasoning 为输出子集，单列展示，不再次相加。缺失 usage 与缺失 total 分别保留，未知值不填零。
+- `observedBackgroundTokenShare`：当前空间完整已观测请求中，后台请求 Token 占比。任何请求缺少总用量或汇总不完整时为 null；该数值不包含主聊天内所有记忆输入成本，也不等于账单费用占比。
+- `memoryInputEstimate`：对已组装的记忆常驻规则、工具定义、画像、目录和自动上下文做文本 Token 估算，逐个观测聊天请求累计。历史工具结果、分层对话及多模态等归因尚不完整。
+- 数据库共享画像维护或暂时无法归属的调用列入 `sharedOrUnattributed`，不伪造工作区分摊。
+- 收益提供检索充分性、空结果、采用回执与分层内容体积估算。分层估算使用最近最多 64 个存储块，代表内容大小比较，不等于实际账单节省或答案质量。
+- 主聊天采集覆盖能关联到本插件会话且经过宿主 `llm/stream` 钩子的请求；费用比例、净收益及未观测请求保持未知。旧版本历史不回填。
+
+## 反馈内容与隐私
+
+默认报告含用户检查的问题描述、基础诊断、近期模块统计和异常分类、阶段、时间。前端最近错误和后台任务错误原文仅在用户勾选详细错误日志后加入；默认报告还会剔除旧诊断快照中的 detail 字段。持续采集不存模型输入、输出正文或工具参数；错误只取有界 message，并在本地落盘前去除常见凭据、URL、Windows 路径和邮箱。默认摘要省略详细错误文本；按诊断 ID 读取详情时提供脱敏文本。前端生成报告时另对凭据、邮箱、URL、Windows/UNC/Unix 路径脱敏。
+
+详细错误日志、记忆正文由用户选择加入。自动脱敏有边界，检查页展示完整待复制内容供人工确认。统计以本地存储为限，发送邮件由用户完成；复制和下载只表示本地操作成功，实际发送与作者收件需邮件侧证据。
+
+## 验证
+
+使用隔离 SQLite 数据库验证重启保留、命名空间隔离、失败写入不阻塞、原始记录上限与汇总保留、Token 去重计数及缺失标记；模型测试覆盖无效输出重试的额外消耗和后台空间归属；反馈测试覆盖 AI 草稿直达检查、完整快照、用户编辑和剪贴板失败回退。
+
+`scripts/test-feedback-navigation-browser.mjs` 使用已安装 DSH 的真实 Markdown 链接、设置面板和共享 store，以及插件真实组件，在无头 Chrome 中检查点击传播、草稿定位和普通外链。API 使用合成数据，不读取真实用户配置。需要 React/React DOM、宿主 UI 构建依赖和 Chrome；可用 `STRATAGATE_BROWSER_NODE_MODULES` 指定独立依赖目录、`STRATAGATE_BROWSER_CHROME` 指定浏览器。可选 `STRATAGATE_NAVIGATION_BASELINE_SOURCE` 提供旧版 client.js 做原样复现对照，`STRATAGATE_NAVIGATION_EVIDENCE` 保存结果。
+
+设置 `STRATAGATE_NAVIGATION_SURFACE=desktop` 时，测试以独立 Electron 44、临时用户目录、真实注册的 `dsh-app` 协议和隔离 IPC 启动信息运行；桌面主界面与 HTTP 草稿链接使用不同来源。测试经过插件实际 `apply` 注册、真实 `MarkdownText`、`SlotCore` 和设置面板，不调用付费模型。`STRATAGATE_BROWSER_ELECTRON` 指定测试二进制；`STRATAGATE_NAVIGATION_CLIENT_SOURCE` 可指向安装包内的 dist/client.js 验证确切产物；`STRATAGATE_NAVIGATION_SCREENSHOT` 可保存合成场景截图。该测试验证隔离桌面壳中的链路，真实用户 DSH 配置仍需人工验收。
+
+宿主界面的真实邮件发送仍由用户完成。页面截图采用合成数据，仅用于布局检查；具体测试与性能证据见 `docs/validation/feedback-observability-20261016/`。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stratagate-dsh",
-  "version": "0.3.15",
+  "version": "0.3.17",
   "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",
@@ -151,21 +151,22 @@
     "access": "public"
   },
   "engines": {
+    "dsh": "0.1.2-rc.1 || >=0.1.5-rc.1 <0.3.0-0",
     "node": "^22.19.0 || >=24.0.0"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "4.0.2 || ~4.0.4",
-    "@deepseek-ai/dsh-agent-default-model": "0.1.2-rc.1 || 0.1.5-rc.2 || 0.1.6-alpha.1 || >=0.1.7-rc.1 <0.1.8-0 || >=0.2.0-0 <0.2.1-0",
-    "@deepseek-ai/dsh-client-ui-conversation": "0.1.2-rc.1 || 0.1.5-rc.2 || 0.1.6-alpha.1 || >=0.1.7-rc.1 <0.1.8-0 || >=0.2.0-0 <0.2.1-0",
-    "@deepseek-ai/dsh-llm": "0.1.2-rc.1 || 0.1.5-rc.2 || 0.1.6-alpha.1 || >=0.1.7-rc.1 <0.1.8-0 || >=0.2.0-0 <0.2.1-0",
-    "@deepseek-ai/dsh-native-command": "0.1.2-rc.1 || 0.1.5-rc.2 || 0.1.6-alpha.1 || >=0.1.7-rc.1 <0.1.8-0 || >=0.2.0-0 <0.2.1-0",
-    "@deepseek-ai/dsh-session": "0.1.2-rc.1 || 0.1.5-rc.2 || 0.1.6-alpha.1 || >=0.1.7-rc.1 <0.1.8-0 || >=0.2.0-0 <0.2.1-0",
-    "@deepseek-ai/dsh-session-format": "0.1.5-rc.2 || 0.1.6-alpha.1 || >=0.1.7-rc.1 <0.1.8-0 || >=0.2.0-0 <0.2.1-0",
-    "@deepseek-ai/dsh-session-format-catalog": "0.1.5-rc.2 || 0.1.6-alpha.1 || >=0.1.7-rc.1 <0.1.8-0 || >=0.2.0-0 <0.2.1-0",
-    "@deepseek-ai/dsh-session-format-v0-to-v1": "0.1.5-rc.2 || 0.1.6-alpha.1 || >=0.1.7-rc.1 <0.1.8-0 || >=0.2.0-0 <0.2.1-0",
-    "@deepseek-ai/dsh-settings": "0.1.2-rc.1 || 0.1.5-rc.2 || 0.1.6-alpha.1 || >=0.1.7-rc.1 <0.1.8-0 || >=0.2.0-0 <0.2.1-0",
-    "@deepseek-ai/dsh-system-prompt": "0.1.2-rc.1 || 0.1.5-rc.2 || 0.1.6-alpha.1 || >=0.1.7-rc.1 <0.1.8-0 || >=0.2.0-0 <0.2.1-0",
-    "@deepseek-ai/dsh-tools": "0.1.2-rc.1 || 0.1.5-rc.2 || 0.1.6-alpha.1 || >=0.1.7-rc.1 <0.1.8-0 || >=0.2.0-0 <0.2.1-0",
+    "@deepseek-ai/dsh-agent-default-model": "0.1.2-rc.1 || >=0.1.5-rc.2 <0.3.0-0",
+    "@deepseek-ai/dsh-client-ui-conversation": "0.1.2-rc.1 || >=0.1.5-rc.2 <0.3.0-0",
+    "@deepseek-ai/dsh-llm": "0.1.2-rc.1 || >=0.1.5-rc.2 <0.3.0-0",
+    "@deepseek-ai/dsh-native-command": "0.1.2-rc.1 || >=0.1.5-rc.2 <0.3.0-0",
+    "@deepseek-ai/dsh-session": "0.1.2-rc.1 || >=0.1.5-rc.2 <0.3.0-0",
+    "@deepseek-ai/dsh-session-format": ">=0.1.5-rc.2 <0.3.0-0",
+    "@deepseek-ai/dsh-session-format-catalog": ">=0.1.5-rc.2 <0.3.0-0",
+    "@deepseek-ai/dsh-session-format-v0-to-v1": ">=0.1.5-rc.2 <0.3.0-0",
+    "@deepseek-ai/dsh-settings": "0.1.2-rc.1 || >=0.1.5-rc.2 <0.3.0-0",
+    "@deepseek-ai/dsh-system-prompt": "0.1.2-rc.1 || >=0.1.5-rc.2 <0.3.0-0",
+    "@deepseek-ai/dsh-tools": "0.1.2-rc.1 || >=0.1.5-rc.2 <0.3.0-0",
     "@deepseek-ai/schemastery": "3.18.2 || ~3.18.4"
   },
   "peerDependenciesMeta": {
@@ -226,6 +227,7 @@
     "@deepseek-ai/dsh-tools": "0.2.0-rc.2",
     "@deepseek-ai/schemastery": "3.18.4",
     "@types/node": "^22.0.0",
+    "@types/semver": "^7.8.0",
     "cytoscape": "^3.34.1",
     "cytoscape-fcose": "^2.2.0",
     "esbuild": "^0.28.2",
@@ -236,7 +238,8 @@
   },
   "dependencies": {
     "ngraph.graph": "^20.1.2",
-    "ngraph.leiden": "^0.3.0"
+    "ngraph.leiden": "^0.3.0",
+    "semver": "^7.8.5"
   },
   "directories": {
     "doc": "docs",