前言¶
DeepSeek Harness (DSH) 的智能体在会话之间往往面临上下文丢失的问题，尤其是当工作流涉及大量文件、工具配置或历史记录时，重复检索本地资源效率低下。mega-index-map 作为一个跨工作区库，旨在解决这一问题。它允许智能体将遇到的文件、工具、环境配置、知识库条目和工作记录统一记录并索引到本地，从而在任何对话中都能快速复用这些信息。
插件定位¶
mega-index-map 是一个由 Nesarf 维护的跨工作区互操作库。其核心价值在于提供一个本地的、自扩展的文件格式库，用于记录、索引和搜索跨工作区的数据。所有数据存储在 $DSH_HOME/library 目录下，插件运行时无网络 I/O，不执行任何上传操作，确保了数据的安全性和隔离性。
核心功能¶
插件提供了一系列以 library_ 为前缀的工具命令，覆盖了从数据记录到检索的全流程。
-
library_record
记录对象。系统具备变更检测机制，通过verify/confirm路由决定是否更新。对于不可变类的变更，系统会拒绝并等待用户确认，随后记录reason并标记为record-confirm。 -
library_index
对索引执行重建、审核、索引和修剪操作：op=rebuild（默认）：去重、排序并报告冲突。op=audit dir=<path>：只读 reconciling 目录与索引，处理磁盘上存在但未记录的条目，以及索引中路径不再存在的记录。op=index dir=<path> confirm=true：注册缺失条目，受深度和条目上限限制，同时应用敏感内容规则。op=prune confirm=true：删除不再符合条件（如格式签名出现次数不足）的派生行。
-
library_query
按关键字、类型或标签搜索，支持光标分页。多词查询会逐词匹配并基于覆盖率进行排名，单个词则作为子串搜索。 -
library_detect
扫描并注册本机的工具和环境。内置种子基于PATH解析命令名，并记录工具位置（如%ProgramFiles%、%GOROOT%等）。支持add（添加到候选包）和propose（从目录建议条目）。 -
library_sniff
通过头部字节（支持 108 种签名）识别文件类型，独立于文件扩展名。 -
library_format
扩展本机的格式库，支持list、scan、learn、add、remove、deps、draft、report、deliver和unseal等操作。 -
library_decrypt
在请求时读取隔离的敏感对象。 -
library_export
将数据导出为 JSON 或 NDJSON 格式。 -
library_encoding
报告主机编码及切换到 UTF-8 的方法。 -
library_adb
通过 ADB 执行 Android 设备操作。 -
library_sessions
读取 DSH 会话及其导出的历史记录 ZIP。支持op=list、op=read、op=tail、op=search、op=record、op=bootstrap和op=status。数据以 zstd 帧存储，支持只读访问和损坏尾部的处理。
安装与启用¶
安装插件需要使用官方的包管理命令。
# 安装插件
dsh plugin --profile web add github:Nesarf/mega-index-map
# 升级已安装的版本
dsh plugin --profile web update mega-index-map
在首次启动时，插件会自动执行引导流程，读取会话历史并挖掘可索引的事实。
典型用法¶
- 查询索引
library_query term by term ranking
- 索引操作
# 重建索引
library_index op=rebuild
# 审核目录
library_index op=audit dir=/path/to/dir
# 索引目录并强制确认
library_index op=index dir=/path/to/dir confirm=true
# 修剪索引
library_index op=prune confirm=true
- 会话管理
# 列出会话
library_sessions op=list
# 读取会话摘要
library_sessions op=read
# 搜索会话历史中的短语
library_sessions op=search phrase
# 引导配置
# blocking: 默认，完成后注册工具
# gate: 后台运行，通过 status 查看状态
# off: 仅显式调用 bootstrap
# bootstrapBudgetMs: 默认 300000ms，控制最大运行时间
library_sessions op=bootstrap blocking bootstrapBudgetMs=300000
- 工具检测
# 添加候选工具
library_detect add tool_name
# 从目录建议条目
library_detect propose /path/to/dir
适用场景与注意¶
该插件适合需要在多轮对话中保持状态、检索本地工具配置或文件信息的场景。
- 性能数据：在当前规模下（约 11,649 个对象，6.0 MB 索引），查询耗时约 51ms，记录耗时约 156ms，重建耗时约 124ms。
- 并发与隔离：写入操作通过锁文件串行化。插件对跨 Harness 是只读的，仅向
$DSH_HOME、临时目录或调用者路径写入。 - 不变量：输出强制为 ASCII，确保跨平台可移植性，并正确处理 UTF-8 文本。
- 安全提示：该插件以当前 DSH 进程权限运行。安装前请检查源码与许可证。
总结¶
mega-index-map 为 DSH 提供了一个本地化的知识管理和检索层。通过将文件、工具和环境记录进索引，智能体可以更高效地复用上下文，减少对磁盘的直接检索依赖。对于需要长期维护工作上下文的项目，这是一个实用的工具。更多详情可查看插件目录或 GitHub 仓库。
