stratagate-dsh 0.3.15 → 0.3.16

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.16",
   "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",