前言¶

在 DSH 里让模型理解一个本地仓库，常见做法是反复读目录、搜文件名或手动贴路径。仓库一大，上下文容易被无关文件占满，模型也不一定能从散落的 package.json 和入口文件名推断出结构。dsh-compass 是 LIghtJUNction 维护的 DSH 客户端插件（npm 包名 @lightjunction/dsh-compass），面向 DSH 0.2.1-rc.2，在宿主机本地工作区扫描文件并暴露两个工具：codebase_map 汇总文件列表、包信息与候选入口；code_tour 按路径关键词抽取声明行，便于在已有地图版本上做一次轻量「导览」。它不是 AST 索引、引用搜索或 import 图，也不替代 Git 或 IDE 的全局导航。

这是什么¶

一句话：为 DeepSeek Harness 提供 Repository code maps and navigation——即仓库级代码地图与基于路径的导览能力。

维护者与来源：GitHub 仓库 LIghtJUNction/dsh-compass，社区目录页 SkillHub 条目（独立社区站点，与 DeepSeek / 幻方无官方从属关系）。许可证 MIT（见仓库 NOTICE 中对上游的说明）。开发要求 Node >=24；README 写明本地用 Node 26 / TypeScript 5.9.3 开发与测试，Release CI 配置为 Node 24。

核心功能¶

插件通过 Cordis bundle 注册工具，每次调用在 宿主机本地 重新扫描（无持久缓存、无自动 prompt 注入）。

codebase_map¶

• 调用 codebase_map({}) 返回：files、packages（JSON 编码的包摘要）、候选 entryPoints、revision、规范 root、以及是否 truncated。
• 调用 codebase_map({ expectedRevision: "<previous revision>" }) 若地图已过期则拒绝，避免在陈旧快照上继续操作。

包元数据会报告 Node 包名、scripts、依赖名；不会执行 scripts。候选入口包括常见的 index/main/app/server 类文件，以及 Cargo.toml、pyproject.toml、go.mod 等——均为启发式，不保证是可执行入口。

code_tour¶

• 调用 code_tour({ topic: "auth", expectedRevision: "<map revision>" })：在受支持的源文件中，路径 字面包含 auth（忽略大小写）的文件里抽取声明行；结果含路径、行号及地图 revision。
• 导览读完文件后会再次校验地图；若已变化会要求重试。最多访问 20 个匹配文件，每文件最多 15 条声明行（每行 240 字符），超出会标记截断。

扫描与 revision 的含义¶

跳过隐藏项、符号链接、node_modules、dist、build、target、coverage、vendor 等目录；不是 Git-ignore 解析器。扫描在达到 1000 个文件、4000 次访问条目或目录深度 8 时停止并报告截断。畸形或不可读的 package.json 会使操作失败，而不是静默编造包数据。单文件读取上限 256 KiB。

revision 由文件路径、大小、mtime/ctime 及 package.json 文本指纹而成，不是全仓库内容哈希，也不是原子文件系统快照。

声明行启发式覆盖常见 JS/TS、Python、Rust、Go、Java 及 C 系扩展；不支持语义化架构推断或框架自动识别。

安装与启用¶

官方说明从 GitHub Release 安装已构建的 tgz（README 给出的 URL 为 v0.1.0 资源位置，是否已发布需以 Release 页为准；安装时使用同一次 Release 附带的归档与 SHA256SUMS）。

dsh plugin --profile headless add https://github.com/LIghtJUNction/dsh-compass/releases/download/v0.1.0/lightjunction-dsh-compass-0.1.0.tgz
dsh headless --dump-config

包内含 DSH bundle patch 与编译后的 JavaScript，不需要 Pi 依赖。安装后需 重启 DSH。若不用 headless profile，将命令中的 profile 名换成你实际使用的即可。

配置 root¶

默认 bundle 配置为 {}：各工具使用 调用方智能体的工作目录。若无智能体的 host 调用，必须在配置里显式指定 root。若要把工作区固定到本机某路径，在 profile 的 cordis.patch.yml 中增加：

- id: dsh-compass
  config:
    root: /absolute/local/project

root 必须已存在，在 DSH 宿主机 上通过 Node 文件系统 API 解析。远程 DSH world 或 sandbox 不会 重定向这些操作：仅适合 宿主机本地项目 启用；这不是远程 world 适配器，也不是安全沙箱。

典型用法¶

README 建议的可复现对话示例：向 DSH 提问——「Map this repository, then show a tour of files under src.」

对应工具链大致为：

1. 先调用 codebase_map({}) 拿到 revision 与结构摘要。
2. 再用 code_tour({ topic: "src", expectedRevision: "<上一步 revision>" })（或你关心的路径片段作为 topic）查看匹配路径下的声明行。

若两步之间文件系统发生变化，应重新 codebase_map 并更新 expectedRevision。

适用场景与注意¶

适合谁：在 DSH 智能体循环里，需要快速给模型一份 受控规模 的仓库鸟瞰（文件列表、包脚本与依赖名、候选入口），并在不建索引的前提下按路径关键词看一批声明行时，可在 可信的本地工作区 启用本插件。

务必知晓：

• 插件以 当前 DSH 进程权限 读取本地文件；安装前应自行审阅源码与 MIT 许可证，确认路径边界策略符合你的安全预期。README 说明对普通符号链接重定向、no-follow 打开常规文件等有检查，但 不能 抵御恶意进程并发替换祖先目录；应在可信本地环境使用。目标语义为 Linux/macOS 风格文件系统，Windows 未验证。
• 无 Pi TUI onboarding 菜单、无框架/约定自动检测、无语义化 tour 生成；并发读支持，dispose 时会中止/排空工作并注销工具。
• 维护者仓库开发自检可运行 npm run check（TypeScript、行为测试与构建；使用真实 Cordis、DSH ToolRuntime 等，无需 live 模型凭证——见 README）。

结尾¶

dsh-compass 把「先画一张本地仓库地图、再按路径关键词做有限导览」收成两个 DSH 工具，适合在 agent 工作目录或显式 root 下做结构化摸底，而不是做全仓库语义搜索。

• 社区目录：https://www.skillhub.cn/plugins/LIghtJUNction/dsh-compass
• 源码与 README：https://github.com/LIghtJUNction/dsh-compass