前言¶
在 DeepSeek Harness（DSH）里跑智能体时，模型经常要查本地仓库里的代码和文档。若只靠对话上下文或临时 grep，要么上下文装不下整库，要么得自己拼子进程和索引状态。SAG Wiki 上游已经提供本机索引与检索 CLI；要在 Harness 里稳定、结构化地调用它，需要一层宿主侧插件把能力注册进 tools 服务。
下面介绍社区插件 dsh-sag-wiki（维护者 clear0，分类：记忆）：把 SAG Wiki 的本地检索接到 DSH，由本机已安装的 sag 可执行文件完成索引与查询，插件本身不建索引、不联网、不缓存正文。
这是什么¶
dsh-sag-wiki 是纯宿主侧 Cordis 插件（无浏览器半侧），向 DSH 的 tools 服务注册 4 个 sag_* 工具。调用链大致为：模型 → 插件工具 → 本机 sag → SAG 后台服务与本地索引；索引的增删由 sag add / sag remove（或插件的索引管理工具）完成。
- 目录页：https://www.skillhub.cn/plugins/clear0/dsh-sag-wiki
- 源码与说明：https://github.com/clear0/dsh-sag-wiki
- 包版本（资料）：
0.1.0，许可证 MIT
核心功能¶
插件对外提供四个工具，返回结构化 JSON，并渲染成紧凑中文说明：
| 工具 | 作用 |
|---|---|
sag_search |
语义检索（自然语言问句）；需 JEV 模型配置，未配置时会给出可操作提示 |
sag_grep |
精确或正则检索；不依赖嵌入模型 |
sag_index_status |
检查单目录或列出全部已索引目录的状态 |
sag_index_update |
对目录执行索引 add / remove |
依赖关系（摘自 README）：
- 必需：DeepSeek Harness（含 Cordis，需
tools/subprocess/workingDirectory）、Node.js ≥ 20、本机 PATH 中的 SAG CLI、已建索引且后台服务可用的目录。 - 可选：JEV 模型配置，仅
sag_search需要；可改用sag_grep做字面量或正则查找。
安装前准备：SAG CLI 与索引¶
插件不在安装包里附带 CLI，只在 PATH 中查找 sag / sag.exe。任选其一安装通道：
- 桌面版 SAG Wiki（随安装器附带 CLI，常见位置如 Windows
%USERPROFILE%\.local\bin\sag.exe、macOS~/.local/bin/sag）。 - 独立 CLI：
npm install -g @zleap-ai/sag
sag --version
在要检索的项目目录内建立索引（首次 sag add 会拉起常驻后台服务）：
cd /path/to/project
sag check . --json
sag add . --json
可用 sag add . --types md,txt,js,ts,py,json,yaml --json 限制类型；大体积二进制建议在目录根用 .sagignore 排除。
安装与启用插件¶
资料说明：本机 PATH 里没有 dsh 命令时，安装一律通过 Harness 插件管理器完成，不要凭插件名拼接 dsh plugin add github:...。
- 将仓库放到本机任意目录（记下该目录的绝对路径）。
- 在插件管理器中执行
install_bundle，target设为上述绝对路径。
安装后会：在 profile 的 package.json 写入 "dsh-sag-wiki": "link:<路径>"；把包名加入 dsh.profile.bundles；通过 cordis.patch.yml 把 dsh-sag-wiki 插入 boot graph。
验证：
- 工具列表中出现上述四个
sag_*工具。 - 调用
sag_index_status（可不传参），应能看到当前工作目录的覆盖与索引状态；对已sag add的目录应出现status=ready。
改源码后以 link: 方式安装时，需用 profile 登记的 entry id（形如 include:dsh-sag-wiki）重载插件后改动才生效。
权限与审阅：插件以当前 DSH 进程权限执行子进程并访问本机索引；安装前请阅读源码与 MIT 许可证，确认 PATH 与索引目录符合你的安全策略。
典型用法¶
README 中的推荐顺序：
- 查概念或不熟悉的实现：先确认目录已索引，再用
sag_search（query写完整问句，directory指向已索引路径，maxResults默认 5）。 - 查已知符号、错误串、配置键：用
sag_grep，mode=fixed最快；需要正则时用mode=regex。 - 结果太散：缩小
directory或降低maxResults。 - 搜不到：先
sag_index_status，区分未建索引、不在覆盖范围、索引未就绪。 - 新目录：
sag_index_status→ 必要时sag_index_update(action=add)→ 再检索。
一页速览中的验证步骤：
sag --version
cd /path/to/project && sag add . --json
# 安装 bundle 后调用 sag_index_status，应看到该目录 status=ready
未配置 JEV 时，语义检索会提示配置方式；精确检索可一直使用 sag_grep。
适用场景与注意¶
适合：已在用或愿意用 SAG Wiki 做本机代码/文档索引的 DSH 开发者；需要在对话里让模型直接调用索引状态、增删索引、语义或正则检索，而不在 Harness 里重复实现 CLI 封装。
注意：
- Windows x64、macOS arm64 在资料中标记为完整支持；macOS x64 / Linux 取决于上游 SAG 是否提供对应平台构建。
- 宿主 GUI 启动时 PATH 可能与终端不一致，出现「未找到 sag 可执行文件」时可重载插件或重启 Harness。
- 索引规模越大检索越慢，优先收窄
directory而非单纯加大maxResults。 - 仓库内还提供不依赖宿主的自测脚本
node test/smoke.mjs、node test/bench.mjs，用于本地验证参数拼装与延迟（默认不写索引，需--write才会执行sag_index_update(add)）。
结尾¶
dsh-sag-wiki 把 SAG Wiki 的本机检索能力以四个 tools 形式接到 DeepSeek Harness：索引与检索仍由本机 sag 与后台服务承担，插件只做 Cordis 侧注册与 CLI 调用。社区插件目录见 SkillHub 条目；细节、故障排查表与工具参数见 GitHub 仓库 README。
