前言¶
DeepSeek Harness（DSH）的智能体通常运行在沙盒环境中，无法直接读取宿主机上的文件系统。这导致两个常见问题：一是智能体无法访问团队共享的知识库（如 Antigravity 的 ~/.gemini 目录），在遇到文件权限问题时容易产生“文件不存在”的误判；二是智能体可能误执行破坏性命令，如 git reset --hard 或 rm -rf，导致数据丢失。
dsh-knowledge-bridge 是一个运行在宿主机层面的 Cordis 插件。它使用宿主进程的权限读取文件系统，向智能体提供三个检索工具，并注入一条指令让模型知晓知识库的存在。同时，它内置了防破坏性的 Shell 命令安全机制。
核心功能¶
检索工具¶
插件向智能体暴露以下三个工具：
knowledge_search：基于关键词的搜索。具备明确的权重系统：标题 10，ID 8，别名 8，标签 6，引用 4，摘要 3，工件名 2，正文 1。搜索结果包含 ID、标题、得分、截断的摘要和工件列表，不会直接返回文件内容。knowledge_read：按需读取完整文档或特定工件（如master_guide.md）。knowledge_list：提供知识库的目录大纲，包含 ID、标题、工件数量以及一行预览。
配置与发现¶
- 零配置发现：插件会自动从环境变量
DSH_KNOWLEDGE_PATHS或一系列已知位置查找知识库。默认路径包括~/.gemini/antigravity-ide/knowledge、~/.antigravity-ide/knowledge、~/.dsh/knowledge、~/.codex/knowledge以及当前目录下的./knowledge和./docs/knowledge。 - 规则注入：插件会从工作区发现
AGENTS.md、GEMINI.md或CLAUDE.md并将其注入到系统提示词中。 - 版本与更新信息：
knowledge_info工具会返回当前安装版本、更新命令、重启要求以及版本检查结果。
安全防护¶
- 安全护栏：插件会拦截
bash、pwsh、cmd或terminal调用中匹配禁止模式的命令（如git reset --hard、rm -rf等），防止智能体执行破坏性操作。 - Token 优化：工具摘要会被截断，避免在后续对话中因输出过长导致 Token 溢出。
安装与启用¶
环境要求¶
- Node.js 版本需 >= 20.0.0。
- 插件本身无外部依赖，仅使用 Node.js 内置模块 (
node:fs,node:path,node:os)。
安装步骤¶
在 DeepSeek Harness 的终端中执行以下命令：
dsh plugin --profile <profile> add https://github.com/Babydunx1/dsh-knowledge-bridge
安装完成后，需要重启 DeepSeek Harness 以加载新的 JavaScript 模块。
典型用法¶
安装插件后，可以通过项目自带的脚本验证其功能。这些命令无需 DeepSeek Harness 介入即可运行：
# 运行测试套件
npm test
# 验证构建合约的静态检查
npm run validate
# 演示：索引示例知识库并打印智能体将看到的内容
npm run demo
适用场景与注意¶
- 定位说明：这不是一个将整个知识库（2MB 可能产生约 1M tokens）加载到提示词中的记忆系统，也不是向量数据库。它采用确定性关键词评分，不依赖嵌入服务。
- 权限说明：插件以宿主机权限运行，能访问环境变量指定的路径，但不会自动将整个目录挂载到智能体的上下文中，而是按需检索。
- 环境变量：可以通过设置
DSH_KNOWLEDGE_PATHS环境变量来覆盖默认的发现路径。 - 平台支持：支持 Windows、macOS 和 Linux。
总结¶
dsh-knowledge-bridge 解决了智能体在沙盒环境下无法获取外部知识以及误操作的风险。它通过零配置发现、按需检索和防破坏机制，为 DeepSeek Harness 提供了可靠的知识层支持。
