dsh-reference-anything 0.5.0 → 0.5.2

package/cordis.patch.yml

@@ -1,134 +1,136 @@
-# dsh-reference-anything — the layer this bundle contributes.
-#
-# A patch REPLACES a row's whole `config` rather than merging keys, so when you
-# override one of these in your profile's cordis.patch.yml, restate every key
-# the row needs.
-- id: ui-reference
-  # Reference Anything re-registers Files and DSH sessions as two independent
-  # sources over the same official Remotes.  Disabling only this Client source
-  # keeps the official file/session services. RA also owns the native
-  # "reference" codec and the newer Host's file/folder message renderers.
-  disabled: true
-
-- insert:
-    - id: reference-chat-import-runtime
-      name: 'dsh-reference-anything/chat-import-runtime'
-
-    # The registry every source registers into.
-    - id: references
-      name: 'dsh-reference-anything'
-      config:
-        listLimit: 20
-
-    # Local Agent mentions receive bounded body previews before the model runs.
-    # Other external sources retain deferred reading. Native file and
-    # `dsh-session:` references stay with DSH's official services.
-    - id: reference-mention
-      name: 'dsh-reference-anything/reference'
-      config:
-        maxReferences: 3
-
-    # Lets the model go looking on its own, and page backwards through a
-    # conversation it has only seen the end of.
-    - id: reference-tool
-      name: 'dsh-reference-anything/tool'
-      config:
-        listLimit: 20
-        maxOutputBytes: 65536
-        readTurns: 10
-        maxReadTurns: 50
-        timeoutMs: 30000
-
-    # Durable, local-only mirror of ChatGPT/Claude/Gemini/DeepSeek/Grok.
-    # Browser requests happen during an explicit sync, or — only when the user
-    # opts in via the Conversations settings panel — on a background interval.
-    - id: reference-web-chat
-      name: 'dsh-reference-anything/web-chat'
-      config:
-        timeoutMs: 60000
-        maxStdoutBytes: 33554432
-
-    # Host-only OpenList lifecycle, credentials, and administration. This must
-    # start before the cloud-drive source and Remote that consume it.
-    - id: reference-openlist
-      name: 'dsh-reference-anything/openlist'
-
-    # Host Remote used by the Web @Conversation source and settings panel.
-    - id: reference-anything-web
-      name: 'dsh-reference-anything/web'
-
-    # Exported conversations on disk. Inert until the directory exists, so the
-    # default is safe; point `roots` wherever you keep your exports.
-    - id: reference-file
-      name: 'dsh-reference-anything/file'
-      config:
-        # External plugin overlays intentionally cannot evaluate !!js. This
-        # portable relative root stays inert unless the launched workspace has
-        # a references/ directory; users may override it with absolute roots.
-        roots: ['references']
-        extensions: ['.json']
-
-    # Text files in the user's own cloud drives, listed by name and read a
-    # window at a time. Reading one needs a per-task grant: these are personal
-    # remote files, so the model may only open what its user named. Inert
-    # without a credential — a drive that has never been logged into simply
-    # reports unavailable, so the default is safe.
-    - id: reference-cloud-drive
-      name: 'dsh-reference-anything/cloud-drive'
-      config:
-        # OpenList is inert until a connection is configured in the Cloud
-        # drives settings section; no account secret is stored in this patch.
-        drives: ['openlist']
-        # Where OpenList listing starts when `roots` has no explicit entry.
-        # Keep it empty to show the OpenList root.
-        root: ''
-        # Optional OpenList root, for example {openlist: '/notes'}.
-        roots: {}
-        listTtlMs: 30000
-        # 64 KiB at 4000 characters a block is at most 17 blocks, which fits
-        # inside maxReadTurns — so an ordinary text file is returned whole,
-        # from its beginning. Raising this buys reach at the cost of a first
-        # page that lands at the end of the file.
-        maxReadBytes: 65536
-        maxReadTurns: 20
-        blockChars: 4000
-
-    # Local transcripts are read only from enabled sources and allowed roots;
-    # no per-task grant. Every read rechecks the current source policy.
-    - id: reference-local-agent
-      name: 'dsh-reference-anything/local-agent'
-      config:
-        # Every format this package reads, at each agent's own default location
-        # under $HOME. An agent that is not installed simply has no directory,
-        # which is not an error. Ordered by how well the format is validated:
-        # the first two were built against real corpora, the rest from format
-        # documentation and synthetic fixtures. Drop the unvalidated ones from
-        # this list to run on the two that were measured.
-        agents: ['claude-code', 'codex', 'cursor', 'qoder', 'reasonix', 'openclaw',
-                 'kimi', 'grokbuild', 'hermes', 'gemini-cli', 'pi',
-                 'opencode', 'mimocode', 'zcode']
-        extraRoots: []
-        # The @ menu is a cross-project history picker; the per-Agent enable
-        # switches remain the explicit visibility boundary.
-        scope: 'all'
-        maxTranscripts: 200
-        maxReadTurns: 20
-        maxScanBytes: 33554432
-        headLines: 40
-        tailLines: 20
-        maxProbeBytes: 2097152
-        maxLineBytes: 1048576
-        directoryTtlMs: 5000
-        includeThinking: false
-        toolCalls: 'full'
-        includeSidechains: false
-        stripEnvironmentPreamble: true
-        # The last three formats keep every conversation in one SQLite database
-        # rather than a file apiece, so reading them needs `node:sqlite`. Set
-        # this to false and the driver is never imported at all: no root of
-        # those kinds is resolved, so no database is ever opened.
-        sqlite: true
-        # Most message rows to materialize from one database-backed session,
-        # counted from the newest. A database cannot be streamed the way a JSONL
-        # file can, so this is what bounds the memory a read costs.
-        maxSessionRecords: 2000
+# dsh-reference-anything — the layer this bundle contributes.
+#
+# A patch REPLACES a row's whole `config` rather than merging keys, so when you
+# override one of these in your profile's cordis.patch.yml, restate every key
+# the row needs.
+- id: ui-reference
+  # Reference Anything re-registers Files and DSH sessions as two independent
+  # sources over the same official Remotes.  Disabling only this Client source
+  # keeps the official file/session services. RA also owns the native
+  # "reference" codec and the newer Host's file/folder message renderers.
+  # If a profile explicitly enables ui-reference, RA defers those registrations
+  # and hides its duplicate file/session candidates (saved RA chips still work).
+  disabled: true
+
+- insert:
+    - id: reference-chat-import-runtime
+      name: 'dsh-reference-anything/chat-import-runtime'
+
+    # The registry every source registers into.
+    - id: references
+      name: 'dsh-reference-anything'
+      config:
+        listLimit: 20
+
+    # Local Agent mentions receive bounded body previews before the model runs.
+    # Other external sources retain deferred reading. Native file and
+    # `dsh-session:` references stay with DSH's official services.
+    - id: reference-mention
+      name: 'dsh-reference-anything/reference'
+      config:
+        maxReferences: 3
+
+    # Lets the model go looking on its own, and page backwards through a
+    # conversation it has only seen the end of.
+    - id: reference-tool
+      name: 'dsh-reference-anything/tool'
+      config:
+        listLimit: 20
+        maxOutputBytes: 65536
+        readTurns: 10
+        maxReadTurns: 50
+        timeoutMs: 30000
+
+    # Durable, local-only mirror of ChatGPT/Claude/Gemini/DeepSeek/Grok.
+    # Browser requests happen during an explicit sync, or — only when the user
+    # opts in via the Conversations settings panel — on a background interval.
+    - id: reference-web-chat
+      name: 'dsh-reference-anything/web-chat'
+      config:
+        timeoutMs: 60000
+        maxStdoutBytes: 33554432
+
+    # Host-only OpenList lifecycle, credentials, and administration. This must
+    # start before the cloud-drive source and Remote that consume it.
+    - id: reference-openlist
+      name: 'dsh-reference-anything/openlist'
+
+    # Host Remote used by the Web @Conversation source and settings panel.
+    - id: reference-anything-web
+      name: 'dsh-reference-anything/web'
+
+    # Exported conversations on disk. Inert until the directory exists, so the
+    # default is safe; point `roots` wherever you keep your exports.
+    - id: reference-file
+      name: 'dsh-reference-anything/file'
+      config:
+        # External plugin overlays intentionally cannot evaluate !!js. This
+        # portable relative root stays inert unless the launched workspace has
+        # a references/ directory; users may override it with absolute roots.
+        roots: ['references']
+        extensions: ['.json']
+
+    # Text files in the user's own cloud drives, listed by name and read a
+    # window at a time. Reading one needs a per-task grant: these are personal
+    # remote files, so the model may only open what its user named. Inert
+    # without a credential — a drive that has never been logged into simply
+    # reports unavailable, so the default is safe.
+    - id: reference-cloud-drive
+      name: 'dsh-reference-anything/cloud-drive'
+      config:
+        # OpenList is inert until a connection is configured in the Cloud
+        # drives settings section; no account secret is stored in this patch.
+        drives: ['openlist']
+        # Where OpenList listing starts when `roots` has no explicit entry.
+        # Keep it empty to show the OpenList root.
+        root: ''
+        # Optional OpenList root, for example {openlist: '/notes'}.
+        roots: {}
+        listTtlMs: 30000
+        # 64 KiB at 4000 characters a block is at most 17 blocks, which fits
+        # inside maxReadTurns — so an ordinary text file is returned whole,
+        # from its beginning. Raising this buys reach at the cost of a first
+        # page that lands at the end of the file.
+        maxReadBytes: 65536
+        maxReadTurns: 20
+        blockChars: 4000
+
+    # Local transcripts are read only from enabled sources and allowed roots;
+    # no per-task grant. Every read rechecks the current source policy.
+    - id: reference-local-agent
+      name: 'dsh-reference-anything/local-agent'
+      config:
+        # Every format this package reads, at each agent's own default location
+        # under $HOME. An agent that is not installed simply has no directory,
+        # which is not an error. Ordered by how well the format is validated:
+        # the first two were built against real corpora, the rest from format
+        # documentation and synthetic fixtures. Drop the unvalidated ones from
+        # this list to run on the two that were measured.
+        agents: ['claude-code', 'codex', 'cursor', 'qoder', 'reasonix', 'openclaw',
+                 'kimi', 'grokbuild', 'hermes', 'gemini-cli', 'pi',
+                 'opencode', 'mimocode', 'zcode']
+        extraRoots: []
+        # The @ menu is a cross-project history picker; the per-Agent enable
+        # switches remain the explicit visibility boundary.
+        scope: 'all'
+        maxTranscripts: 200
+        maxReadTurns: 20
+        maxScanBytes: 33554432
+        headLines: 40
+        tailLines: 20
+        maxProbeBytes: 2097152
+        maxLineBytes: 1048576
+        directoryTtlMs: 5000
+        includeThinking: false
+        toolCalls: 'full'
+        includeSidechains: false
+        stripEnvironmentPreamble: true
+        # The last three formats keep every conversation in one SQLite database
+        # rather than a file apiece, so reading them needs `node:sqlite`. Set
+        # this to false and the driver is never imported at all: no root of
+        # those kinds is resolved, so no database is ever opened.
+        sqlite: true
+        # Most message rows to materialize from one database-backed session,
+        # counted from the newest. A database cannot be streamed the way a JSONL
+        # file can, so this is what bounds the memory a read costs.
+        maxSessionRecords: 2000

package/docs/release/0.4.4/README.md

@@ -0,0 +1,75 @@
+# v0.4.4 — Local Plugins and Configurable Picker Shortcuts
+
+## English
+
+### Discover and reference local plugins
+
+Before v0.4.4, the `@` menu could expose files, sessions, agents, and web chats, but it could not show which local DSH plugins were installed or running. Finding a plugin meant leaving the task and checking the host or profile configuration, and plugin packages were difficult to distinguish from ordinary dependencies.
+
+v0.4.4 adds **All local plugins** as an `@` source. It reads the active loader entries, profile bundles, and installed packages that carry DSH bundle/client metadata, while filtering out ordinary dependencies. Each result reports whether the plugin is running, disabled, or not running. When its package directory can be resolved, selecting it also inserts a native reference to that directory so the agent can inspect it with the existing file tools.
+
+Use `@plugin:` to search. Settings can hide the group, show only running plugins, or hide official DeepSeek plugins.
+
+### Use one shortcut for the source you mean
+
+Previously, source prefixes were fixed and several useful words could be claimed by only one group. A provider name such as `claude` or an Agent name such as `codex` could be ambiguous, and users had to remember different built-in spellings for groups and platforms. Users also could not choose vocabulary that matched their own workflow.
+
+v0.4.4 lets users define their own shortcuts for source groups, web providers, local agents, and cloud-drive mounts. Shared shortcuts can route to more than one source, while provider and Agent shortcuts still select the concrete provider or Agent kind. For example, a user can configure `work` for web conversations and then use `@work:meeting`, or configure `history` for local agents and use `@history:cache`. Multiple shortcuts can be entered with commas in Settings.
+
+The routing also accepts full-width colons and keeps ordinary keywords searchable when they are not being used as a scoped prefix.
+
+### Make folders and references behave like their type
+
+Previously, choosing a directory from the file source could either enter the directory or insert it without a clear distinction, and the resulting reference could still look like a file. This made folder navigation and folder references easy to confuse, especially when using the keyboard.
+
+v0.4.4 gives directory candidates two explicit keyboard actions: press **`Tab`** to drill into the directory and continue browsing its contents; press **`Enter`** to settle the selection and insert a folder reference with folder appearance and the correct trailing path. Picker and Composer icons now distinguish commands, files, folders, sessions, local agents, web providers, cloud drives, and local plugins, including native icon projection updates.
+
+### Keep the command source complete
+
+Some hosts do not return a `model` command even though the command is available to the user. v0.4.4 adds the `model` entry when it is missing, with localized labels and the matching command icon, so the command picker remains complete across host versions.
+
+### Validation
+
+- TypeScript typecheck passed.
+- Production build passed.
+- Client source tests passed in isolation.
+- The full test run passed: 46 test files, 805 tests passed, and 8 tests were skipped.
+
+---
+
+## 中文
+
+### 发现并引用本地插件
+
+在 v0.4.3 之前，`@` 菜单可以展示文件、会话、本地 Agent 和网页端对话，但不能直接告诉用户本机安装了哪些 DSH 插件、哪些插件正在运行。查找插件通常需要离开当前任务去检查宿主或 Profile 配置，而且插件包容易和普通依赖混在一起。
+
+v0.4.4 在 `@` 菜单中新增“本地所有的插件”来源。它会读取当前 Loader 条目、Profile 声明的 Bundle，以及带有 DSH bundle/client 元数据的已安装包，同时排除普通依赖。每个结果会显示“运行中”“已停用”或“未运行”状态。如果能解析出插件目录，选中后还会插入指向真实本地目录的原生引用，Agent 可以继续使用现有文件工具查看该目录。
+
+可以使用 `@plugin:` 搜索。设置中可以隐藏整个插件分组、只显示运行中的插件，或隐藏 DeepSeek 官方插件。
+
+### 用快捷词直接定位目标来源
+
+之前的来源前缀是固定的，而且一些常用词只能归属于一个分组。比如 `claude`、`codex` 既可能指网页端 Provider，也可能指本地 Agent，用户容易遇到歧义，还需要记住不同来源的内置写法。用户也无法把快捷词改成符合自己工作习惯的名称。
+
+v0.4.4 允许用户自定义来源分组、网页 Provider、本地 Agent 和网盘挂载的快捷词。共享快捷词可以同时路由到多个来源；Provider 和 Agent 快捷词则可以进一步定位到具体平台或 Agent 类型。例如可以把网页对话配置为 `work`，然后使用 `@work:会议`；也可以把本地 Agent 配置为 `history`，然后使用 `@history:缓存`。设置输入框支持用逗号填写多个快捷词。
+
+路由同时兼容全角冒号；没有被配置为分组前缀的普通关键词仍然会作为普通搜索词保留。
+
+### 让文件夹和引用行为符合实际类型
+
+之前从文件来源选择目录时，进入目录和插入目录引用的行为不够清晰，插入后的外观也可能仍然像普通文件；使用键盘时尤其容易混淆“浏览文件夹”和“引用文件夹”。
+
+v0.4.4 为目录候选增加了明确的键盘操作：按 **`Tab`** 进入目录并继续浏览其内容；按 **`Enter`** 确认当前选择并插入带文件夹外观和正确尾部路径的目录引用。Picker 和 Composer 中的图标也进行了更新，现在可以区分命令、文件、文件夹、会话、本地 Agent、网页 Provider、网盘和本地插件，并同步处理原生菜单的图标投影。
+
+### 补齐命令来源
+
+部分宿主版本不会返回 `model` 命令，但用户仍然可以使用该命令。这会导致命令 Picker 在不同宿主版本中内容不一致。
+
+v0.4.4 会在宿主未提供时补充 `model` 入口，并提供本地化名称和对应图标，让命令列表保持一致。
+
+### 验证
+
+- TypeScript 类型检查通过。
+- 生产构建通过。
+- 客户端来源测试单独运行通过。
+- 完整测试通过：46 个测试文件，805 个用例通过，8 个用例跳过。

package/{release-notes → docs/release}/0.4.4/features.json

@@ -33,4 +33,4 @@
     "title": "未来更新预告",
     "description": "未来计划带来：\n\n1. 不依赖 OpenCLI 的静默网页端对话同步\n2. 更强大的会话搜索\n3. 更实用的 @云盘权限\n4. @电脑窗口功能\n\n这个插件靠用爱发电持续维护。如果它对你有帮助，欢迎到 GitHub 点一颗 Star 支持！也欢迎有时间、有能力的朋友提交 Issue，反馈问题和建议，或通过 PR 一起完善插件。感谢每一份支持。\n\n[前往 GitHub · Star / Issue / PR](https://github.com/Chael-Chael/dsh-reference-anything)"
   }
-]
+]

package/docs/release/0.5.0/README.md

@@ -0,0 +1,148 @@
+[中文](#cn-050) | [English](#en-050)
+
+> 审稿草案 / Editorial draft：尚未发布，最终文字待审核，技术验收仍为 BLOCKED。
+
+本版本是一次围绕本地 Agent 历史引用与接续工作流程的重大更新，汇总自 `v0.4.4` 以来的变更：来源目录从 14 类扩展到 29 类，升级本地引用工具协议，并新增正文预览、搜索、图片读取、会话导入和实验性交接摘要。
+
+<h3 id="cn-050">新增功能</h3>
+
+- 来源目录扩展至 29 类，新增 Antigravity、Kilo Code、ChatGPT 导出、WorkBuddy、Qwen Code、Continue、Cline、Goose、DSH4、Zed、Crush、TeleAgent、Trae Work、Mistral Vibe 和 DSH。
+- 内置来自 Chat Import 0.26.1 的只读扫描与解析能力，统一发现更多格式的历史。无需安装独立 Chat Import 即可搜索和引用；导入与交接摘要才使用独立插件。
+- 本地引用在发送时自动附上正文预览，让模型开始回答前就能看到历史上下文；正文、工具记录、图片目录分开展示。
+- 重做本地会话工具协议：reference_list 专门发现本地会话；reference_read 通过 ref 定位，使用 part=messages/tools/images 选择内容，以 from/maxItems 分页，返回统一的 revision/items/next。
+- 新增 reference_search，支持在本地会话正文或工具文本中按区分大小写的字面关键词搜索，每条记录返回首个匹配片段；命中位置可直接交给 reference_read 继续读取。
+- 新增 reference_image，按图片 ID 取回原生图片内容，模型可以直接看图；每次一张、最大 10 MiB，需要可恢复的图片数据及视觉模型。
+- 多条本地引用按预处理批次共享文本预算，默认 16 KiB，剩余上下文可进一步降低它；预览保留最近连续尾段，长消息提供可继续读取的前缀。每次本地工具文本结果另受默认 16 KiB 上限限制。
+- 新增可读的 dsh-local 定位与完整引用块，支持同机重启后续读和跨会话复制。每次读取检查当前来源开关、允许目录及会话身份，不再要求逐会话引用授权；关闭来源后旧引用也不能新读取，已注入的历史不会自动撤回。
+- Enter 引用，Tab 进入会话操作：通过 Chat Import 导入完整历史并打开目标会话，显示导入状态；操作失败在菜单中保留原因并支持重试。
+- Claude Code 与 Codex 新增实验性交接摘要，将历史工作的摘要放入当前输入框，便于接着做；默认关闭，不自动发送。
+- 新增“会话导入与交接”设置：导入入口、摘要入口及操作确认可分别配置，默认显示导入、关闭摘要并保留确认。
+- 新增 Chat Import 状态检查与显式安装/升级入口，兼容已有独立版本；保留用户禁用决定，升级失败可重试，停用引用插件不移除独立 Chat Import。
+- 新增离线可看的版本功能卡与 GIF 演示、上一页/下一页导航，以及首次进入该版本插件设置时的介绍；关闭介绍与隐藏菜单入口分别记录。
+
+### 体验优化
+
+- 本地长记录使用明确的 next 接续位置，可跨消息内部继续读取；工具、图片列表可按所属消息过滤，列表版本与正文版本分开校验。
+- 每条用户消息后的多份本地引用合并为一个背景区块；固定工具说明不再逐页重复，显示元数据与正文分离。
+- 功能介绍卡片随界面语言显示中文或英文，未提供英文的卡片回退到原文。
+
+- DSH 会话候选区分当前任务的子 Agent 会话并优先展示，补齐冷会话标题信息、过滤已确认的空会话，改进时间与名称展示。
+- 文件浏览新增面包屑返回导航；下钻目录时隔离其他来源结果；文件引用支持通过宿主资源面板打开，目录继续保持 Tab 浏览、Enter 引用。
+- 完善多个逗号分隔快捷词和跨来源共享快捷词的匹配，保留 codex 等具体来源别名的定向筛选。
+- 后台检查会话正文可用性，隐藏已确认无正文的记录；未知结构、读取异常和超出检查预算的条目继续保留，文件变化后重新检查。
+- 扫描改为独立子进程并增加短期缓存、请求合并和来源级警告，设置中可查看检测到的路径与会话数量。
+- 插件启动后进行轻量连接检查；网页菜单在同步操作旁显示检查中、可用或异常状态，具体列出 OpenCLI、Bridge、适配器及扩展问题，未就绪时阻止无效同步。
+- OpenCLI 2.0.0 随插件作为固定依赖安装，更新统一随插件交付；适配 JSON 管理输出、扩展兼容状态与新版 Bridge 生命周期，网页适配器更新至 0.2.3。
+- 补齐扩展来源图标，调整本地来源卡片与扫描状态展示；当前版本说明与远端最新版本说明分开获取，避免更新信息错位。
+
+### 问题修复
+
+- 修正 @ 菜单首次打开时的异步选中顺序，等待排在前面的来源完成；用户开始键鼠操作后不再自动改动选择。
+- 修正下钻操作与普通搜索缓存混用、重复点击导入/摘要以及菜单刷新影响操作状态的问题，保留错误和重试入口。
+- 完善 Codex 附件包装中的正文与图片、Codex/Claude 压缩检查点、Trae 消息分段，以及 Antigravity 类型化工具结果和异步结果的解析关联。
+- 精简本地工具返回，正文只保留一份结构化数据，直接调用和 run_code 使用一致内容；长文本按 Unicode 码点偏移续读，不把截断当作读完。保留宿主拒绝/替换策略，来源变化时拒绝旧位置并提示刷新。
+- 加强真实路径、来源开关、允许目录与会话身份校验；导入/摘要仍只接受扫描选择并保留确认流程。来源关闭、原始记录缺失、版本变化及参数错误分别返回明确错误，不放宽 DSH 沙箱。
+
+### 其他变更
+
+- 网页/云盘等非本地来源的列表和读取工具改名为 external_reference_list 与 external_reference_read，仍使用其 URI 协议；reference_attachment_read 保持原名。
+- Chat Import 安装/升级只接受 npm 0.26.1 或更高版本，移除旧 GitHub 源码包回退；按需显式安装，不随启动自动安装。
+
+- 建立演示、亲测、Desktop、Agent 浏览器测试四环境分工，以及真实来源验收、官方 Session Log 诊断、tgz 安装矩阵、累计报告与文案审稿流程。
+
+#### 本地 Agent 工具协议迁移
+
+本次重做的是历史读取接口，不是调用另一个 Agent 执行任务。旧参数不再兼容。
+
+| 项目 | 远端 0.4.4 | 当前 0.5.0 |
+| --- | --- | --- |
+| 本地发现 | 通用 reference_list | 本地专用 reference_list，条目提供 ref |
+| 本地读取 | uri / cursor / before / detail | ref / revision / part / from / maxItems |
+| 正文结果 | 旧消息窗口 | revision、items、next；正文只出现一次 |
+| 接续 | 旧 cursor | 原样将 next 放入同类操作的 from；null 表示当前范围结束 |
+| 搜索 | 无专用本地搜索 | reference_search，正文与工具记录均可搜索 |
+| 非本地来源 | reference_list/read | external_reference_list/read，继续使用 URI |
+
+首次读取示意（ref 必须取自真实列表或引用；占位符不能直接执行）：
+
+```json
+{"ref":{"source":"codex","path":"<原始绝对路径>","sessionId":"<实际 ID>"},"part":"messages","maxItems":20}
+```
+
+初次从头读取 messages 时省略 revision 和 from；后续使用返回的正文 revision，并完整复制 next 到 from。part=tools/images 分别返回工具记录或图片目录；查看像素另用 reference_image，并携带数字 imageId。reference_search 的 part 可为 messages/tools，query 为区分大小写的字面子串。
+
+上一开发草稿中的顶层 source/path/sessionId、start/limit/mode 也已删除。旧本地引用需重新选择；内容版本变化时从头刷新，不复用旧位置。列表 revision 只用于列表翻页，不能作为正文 revision。长文本 textOffset 按 Unicode 码点计数，建议复制返回位置，不自行计算。
+
+#### 演示与已知限制
+
+![真实 Web 中插入 Codex 与 Claude Code 的虚构历史引用；未发送模型请求。](./demos/local-references.gif)
+
+![Enter 引用、Tab 打开确认并模拟导入虚构历史。](./demos/agent-import.gif)
+
+来源目录覆盖不等于全部来源均通过真实账号验收；交接摘要为实验功能。预算是保守估计，大记录解析仍可能消耗较多内存；不保存本地正文快照，后续读取依赖原文件。GIF 使用隔离演示数据，不是服务验收证据。
+
+<h3 id="en-050">New Features</h3>
+
+This major update covers changes since `v0.4.4`, focusing on local Agent history and continuing previous work. It expands the source catalog from 14 to 29 formats, upgrades the local reference tool protocol, and adds body previews, search, image retrieval, session imports and experimental handoff summaries.
+
+- Expand the local-source catalog from 14 to 29 formats, adding Antigravity, Kilo Code, ChatGPT exports, WorkBuddy, Qwen Code, Continue, Cline, Goose, DSH4, Zed, Crush, TeleAgent, Trae Work, Mistral Vibe and DSH.
+- Bundle read-only scanners and parsers derived from Chat Import 0.26.1. Search and reference local history without installing the independent Chat Import plugin; imports and handoff summaries use that plugin separately.
+- Attach a body preview when a local reference is sent, so the model receives historical context before answering. Present body messages, tool records and image indexes separately.
+- Redesign local tools: reference_list discovers local sessions; reference_read takes a ref, selects messages/tools/images with part, paginates with from/maxItems and returns revision/items/next.
+- Add reference_search for case-sensitive literal search in local messages or tool text. Return the first match per record and positions that can be passed directly to reference_read.
+- Add reference_image to retrieve actual historical images by ID: one image per call, up to 10 MiB, with recoverable source bytes and a vision-capable model required.
+- Share a default 16 KiB text budget across local previews in a pre-step batch, reduced further by remaining context. Keep a contiguous recent tail and a resumable prefix for long messages. Local tool text results have a separate default 16 KiB cap.
+- Introduce readable dsh-local locators and complete reference blocks for reuse after restarts and across conversations on the same machine. Every read checks enabled sources, allowed roots and session identity; local references no longer require per-session grants. Disabling a source prevents new reads through old references but does not retract previously injected content.
+- Use Enter to reference and Tab to open conversation actions: import history through Chat Import, open the destination session and display import status. Keep actionable errors in the menu for retry.
+- Add experimental handoff summaries for Claude Code and Codex, placing the summary in the current composer. Disabled by default, with no automatic send.
+- Add separate settings for import actions, handoff summaries and confirmation. Defaults show imports, disable summaries and keep confirmation enabled.
+- Add Chat Import status checks and explicit install/upgrade actions, reuse compatible independent installations, respect disabled states, allow retry after failure and retain Chat Import when Reference Anything is disabled.
+- Add offline feature cards and GIF demonstrations, previous/next navigation and an introduction on the first visit to the installed version’s settings. Closing the dialog and dismissing its menu entry are separate actions.
+
+### Improvements
+
+- Resume long records using explicit next positions, including offsets inside a message. Filter tool/image listings by owning message and validate list revisions separately from content revisions.
+- Aggregate local references into one background block after each user message, avoid repeating stable tool instructions on every page and separate display metadata from body text.
+- Show feature cards in Chinese or English according to the interface language, with fallback to the original text when an English translation is absent.
+
+- Prioritize and label subagent sessions belonging to the current task, refresh cold-session metadata, omit confirmed blank sessions and improve titles and timestamps.
+- Add breadcrumb navigation to file browsing, isolate folder drill-down results from other sources and open file references through the host resource panel. Keep Tab for browsing and Enter for referencing folders.
+- Improve matching for comma-separated shortcuts and shared shortcuts across sources while preserving provider-specific filters such as codex.
+- Check transcript availability in the background and hide confirmed bodyless records. Keep unknown formats, read failures and over-budget records visible, and recheck changed files.
+- Run discovery in a separate process with short-lived caching, request coalescing and source-specific warnings. Show discovered paths and session counts in settings.
+- Run a lightweight connection check on startup. Show checking, ready or failure status beside Web sync actions, identify OpenCLI, Bridge, adapter and extension issues, and block sync when prerequisites are not ready.
+- Ship pinned OpenCLI 2.0.0 with the plugin and update it through plugin releases. Support JSON management output, extension compatibility and Bridge lifecycle changes; update the Web adapter to 0.2.3.
+- Extend source icons and refine local-source cards and scan status. Fetch installed-version notes separately from latest-version notes to avoid showing the wrong release.
+
+### Bug Fixes
+
+- Fix initial selection races between asynchronous @ groups; wait for earlier groups and stop automatic selection once the user interacts.
+- Separate drill-down actions from ordinary search caches, prevent duplicate import/summary requests and preserve action state and retry errors across menu refreshes.
+- Preserve Codex wrapper text and images, Codex/Claude compaction checkpoints and Trae message parts; correctly associate typed and asynchronous Antigravity tool results.
+- Keep one structured copy of local result text for direct tools and run_code. Resume long records by Unicode code-point offset instead of treating truncation as completion. Respect host denial/replacement policies and reject stale positions after source changes.
+- Strengthen enabled-source, canonical-path, allowed-root and session-identity checks. Imports/summaries still use scanned selections and confirmation. Report disabled sources, missing records, changed revisions and invalid parameters distinctly without relaxing the DSH sandbox.
+
+### Chores
+
+- Rename non-local listing/reading tools to external_reference_list and external_reference_read while retaining their URI protocol; reference_attachment_read keeps its name.
+- Install/upgrade Chat Import from npm 0.26.1 or later only, removing the old GitHub source-package fallback. Installation remains explicit, not automatic at startup.
+
+- Establish separate demo, user-test, Desktop and Agent-browser environments, plus real-source acceptance, official Session Log diagnosis, tgz installation checks, cumulative reporting and editorial review.
+
+#### Local Agent tool protocol migration
+
+This redesign reads history; it does not launch another Agent. Old arguments are not supported. Local reference_list now returns refs; reference_read accepts ref/revision/part/from/maxItems and returns revision/items/next. Non-local listing/reading moves to external_reference_list/read with its URI protocol intact.
+
+```json
+{"ref":{"source":"codex","path":"<absolute source path>","sessionId":"<actual ID>"},"part":"messages","maxItems":20}
+```
+
+Copy ref from actual results. Omit revision/from only for the initial messages read. Continue with the content revision and copy the entire next into from for the same operation; null ends that scope, not necessarily all earlier history. Read tools or image listings with part=tools/images; reference_image retrieves pixels using a numeric imageId. reference_search supports messages/tools and case-sensitive literal queries.
+
+The previous development draft’s top-level source/path/sessionId and start/limit/mode are also removed. Reselect old local references. Restart from the beginning after content changes; list revisions cannot substitute for content revisions. textOffset counts Unicode code points; copy returned positions rather than calculating them.
+
+#### Demos and known limitations
+
+The GIFs above use fictional data in the real Web UI, including a simulated import; they are not live-service acceptance evidence. Catalog coverage does not mean every source has passed real-account testing. Handoff summaries are experimental. Context budgeting is conservative, large sources can still consume substantial memory, and later reads require the original files because body snapshots are not saved.
+
+Full Changelog: [v0.4.4…1b8cf3e](https://github.com/Chael-Chael/dsh-reference-anything/compare/v0.4.4...1b8cf3e1dc09b5dbf9801c6ceb1c0f85618c45ed). 远端基线已核对；本轮文案未提交，最终发布前更新为审核通过的最终提交或标签。 Remote baseline verified; this editorial revision is uncommitted. Update the comparison to the approved final commit or tag before publication.

package/docs/release/0.5.1/README.md

@@ -0,0 +1,33 @@
+[中文](#cn-051) | [English](#en-051)
+
+<h3 id="cn-051">v0.5.1</h3>
+
+本版本基于 v0.5.0，修复引用兼容与菜单体验问题。
+
+### 问题修复
+
+- 修复与官方 `ui-reference` 同时启用时的引用注册冲突。官方开启时保留其引用与缓存机制，并隐藏 RA 的重复文件、会话来源；此前插入的 RA 引用仍可使用。
+- 本地 Agent 查询仅对匹配且去重后的来源查询导入状态，避免无匹配时重复扫描造成等待。
+
+### 体验优化
+
+- 官方文件、会话来源接入显示开关、独立排序与展开/收起，支持方向键、Enter 和 Tab 操作。
+- Tab 进入文件目录或进入本地 Agent 的操作、导入确认页后，仅显示当前来源；返回根级列表后恢复其他来源。
+- 展开/收起操作采用灰色文字。新功能介绍卡片与演示沿用 v0.5.0。
+
+<h3 id="en-051">v0.5.1</h3>
+
+This patch is based on v0.5.0 and improves reference compatibility and menu behavior.
+
+### Bug Fixes
+
+- Fix conflicting reference registrations when the official `ui-reference` plugin is enabled. Official references and caching remain in use, duplicate RA file/session sources are hidden, and previously inserted RA references remain supported.
+- Query local Agent import status only for sources contributing matched, deduplicated results, avoiding repeated scans for queries with no matches.
+
+### Improvements
+
+- Apply visibility toggles, independent ordering, and expand/collapse controls to official file and session sources, with arrow-key, Enter, and Tab navigation.
+- Show only the active source after entering a file directory with Tab or opening a local Agent action/import confirmation page. Restore other sources on return to the root list.
+- Use gray text for expand/collapse actions. Reuse the v0.5.0 feature cards and demos.
+
+Full Changelog: [v0.5.0...v0.5.1](https://github.com/Chael-Chael/dsh-reference-anything/compare/v0.5.0...v0.5.1)

package/docs/release/0.5.2/README.md

@@ -0,0 +1,51 @@
+[中文](#cn-052) | [English](#en-052)
+
+<h3 id="cn-052">新增功能</h3>
+
+本版本基于 v0.5.1，扩展本地会话来源，修复功能卡 GIF 加载开销和官方引用前缀兼容问题。
+
+- 新增 oh-my-pi、Copilot VS Code、Copilot CLI、豆包桌面版的扫描和只读引用，内置来源增至 33 种。输入 `@omp:`、`@copilot-vscode:`、`@copilot-cli:` 或 `@doubao:` 搜索并按 Enter 插入引用；扫描和引用无需安装 Chat Import。
+- 豆包仅支持本地已缓存正文的对话；缺少的对话可先在豆包中打开后刷新，不会自动下载云端历史。
+
+![四种新增来源的只读引用；使用虚构演示数据](demos/new-local-sources.gif)
+
+### 体验优化
+
+- 功能卡 GIF 改为打开当前卡片时按需访问远程地址，不再内联到客户端 JavaScript 或随 npm 包重复分发。首次观看需要网络；下载失败时可重试，网络不可达时不保证离线展示。
+
+### 问题修复
+
+- 下载附件清理增加文件创建时间核对，避免文件系统复用 inode 后将同名替换文件误认作临时附件。
+
+- 官方 `ui-reference` 启用时，`@file:`、`@session:` 及对应自定义别名仍可限定搜索类别，并调用官方搜索接口；普通 `@` 查询继续由官方来源处理。
+
+### 其他变更
+
+- 内置扫描器与解析器更新至 Chat Import 0.26.3。导入功能需要安装并启用 0.26.3 或更新兼容版本，旧版会显示升级提示。
+- 发布说明、功能卡与演示素材统一归档到 `docs/release/`。
+
+<h3 id="en-052">New Features</h3>
+
+Based on v0.5.1, this release adds local conversation sources and fixes feature-card GIF overhead and official reference prefix compatibility.
+
+- Add scanning and read-only references for oh-my-pi, Copilot VS Code, Copilot CLI and Doubao Desktop, bringing the bundled catalog to 33 formats. Search with `@omp:`, `@copilot-vscode:`, `@copilot-cli:` or `@doubao:`, then press Enter to insert a reference. Scanning and references do not require Chat Import.
+- Doubao supports only conversations with locally cached bodies. Open a missing conversation in Doubao and refresh; cloud history is not downloaded automatically.
+
+![Read-only references from four new sources; synthetic demo data](demos/new-local-sources.gif)
+
+### Improvements
+
+- Load feature-card GIFs from remote URLs only when their card is opened, instead of embedding them in client JavaScript or duplicating them in the npm package. First viewing requires a network connection. Failed downloads can be retried; offline display is not guaranteed.
+
+### Bug Fixes
+
+- Check file creation time during attachment cleanup to avoid mistaking a replacement file for a temporary attachment when the filesystem reuses its inode.
+
+- Keep `@file:`, `@session:` and their custom aliases working when the official `ui-reference` plugin is enabled, using official search APIs. Unscoped `@` queries remain handled by the official sources.
+
+### Chores
+
+- Update bundled scanners and parsers to Chat Import 0.26.3. Importing requires an installed and enabled 0.26.3 or compatible newer version; older installations show an upgrade prompt.
+- Consolidate release notes, feature cards and demo assets under `docs/release/`.
+
+Full Changelog: [v0.5.1...v0.5.2](https://github.com/Chael-Chael/dsh-reference-anything/compare/v0.5.1...v0.5.2)