@whybebabo/dsh-code-nav

dsh plugin --profile web add @whybebabo/dsh-code-nav

@whybebabo/dsh-code-nav

<div align="center">🌏 <a href="./README_EN.md"><b>English</b></a> · 中文</div>

这是 AnakinCao/dsh-code-nav 的 fork。

上游目前未发布到 npm，本 fork 补上了「选中文字 → 添加到对话」（v0.1.2 起）、

常见配置文件支持（v0.2.0 起）、Protocol Buffers 支持（v0.3.0 起）与

可点击的引用 chip（v0.4.0 起），并以

@whybebabo/dsh-code-nav

发布到 npm（当前版本 0.4.0；本版发布前 registry 上的最新版仍是 0.3.0）。

差异见下方[Fork 说明](#fork-说明)；v0.1.2 的改动已作为 PR

AnakinCao/dsh-code-nav#1 提交上游。

DSH（DeepSeek Harness）Web 插件 —— dsh-better-sidebar 代码预览导航扩展。

在侧边栏打开代码文件时，自动按文件类型识别语言并接管预览，提供：

• 🎨 按类型语法高亮 —— 扩展名 → 语言识别，轻量自研分词器（注释 / 字符串 / 关键字 / 类型 / 数字 / 函数），深浅色主题自动跟随
• 🧭 符号大纲切换 —— 解析 class / interface / struct / enum / impl、方法 / 函数、变量 / 字段 / 常量；按「全部 / 类 / 方法 / 变量」筛选，下拉符号列表一键跳转定位（行闪烁，符号行可用 Tab 聚焦 + Enter / Space 触发）；单次最多列出 500 个符号，到达上限时在代码区上方提示「符号过多，仅列出前 500 个」
• 🔍 文件内查找 —— 高亮全部匹配、当前匹配强调、n/m 计数、↑/↓ 或 Enter / Shift+Enter 上下跳转、区分大小写开关；按字面子串匹配（. * ( 等正则元字符就是它自己），最多 2000 条匹配，超出时计数显示为 2000+
• 🖱️ 选中文字 → 添加到对话 —— 在预览里划选任意代码，选区上方浮出「添加到对话」按钮，点击即把选区落成一枚可点击的 引用 chip（引用 文件 L起-止，与 better-sidebar 0.30 的 quote chip 同形）：输入框里只占一枚 chip，发送时展开为 相对路径:起止行 围栏代码块（超过 500 字的选区只留路径行）；点击 chip 跳回源文件并闪烁被引行段。宿主没有 chip 通道 / 记录写不进存储时按 better-sidebar 的降级链回退：内置 reference chip → 直接插入围栏块
• 🗂️ 常见配置文件支持 —— JSON / YAML / TOML / XML / INI / properties / dotenv 等配置格式同样有高亮与大纲：键、段头、XML 元素与属性分别上色，段头归「类」、键与属性归「变量」，嵌套层级在符号列表里显示为 键 — 所属段

前置

• DSH dsh web 可正常运行
• 已安装 dsh-better-sidebar（含聚合包 @linxin666/dsh-web-ui-all 带入的场景）；引用 chip 的点击落地需要 0.30.0+（更旧版本仍能落 chip 并正确展开，只是点击不定位行）

安装

dsh plugin --profile web add @whybebabo/dsh-code-nav

装完重启 dsh web（新增 bundle 需 host 侧重载），再硬刷新浏览器（Cmd/Ctrl+Shift+R）。

提示：better-sidebar 设置页「侧边卡片」中可看到本插件的预览器开关（代码预览导航 / Code Preview Navigator），关闭即回退到内置 CodeMirror 编辑器。

⚠️ 不要与上游 dsh-code-nav 同时安装 —— 两者注册同一个预览器 id（dsh-code-nav:outline），会互相冲突。

升级到新版本

已经装过本插件时，请指定精确版本，不要只依赖 ^ 范围（版本号见上方「当前版本」或 npm view @whybebabo/dsh-code-nav version）：

@whybebabo/dsh-code-nav@0.4.0

原因：pnpm 11 的供应链防护默认值 minimumReleaseAge: 1440 表示"发布满 24 小时的版本才优先安装"。由于这是内置默认值（非显式配置），minimumReleaseAgeStrict 默认为 false —— pnpm 不会报错，而是退回安装一个"够老"的版本。于是已装 0.1.1 的人再执行 ^0.1.1，pnpm 会认为 0.1.1 够老、新版本太新，命令显示成功、版本却停在原地。

写成精确版本后，范围内只剩一个候选，pnpm 会安装它并把该版本记入 minimumReleaseAgeExclude。或者等新版本发布满 24 小时后再用 ^ 升级。

从 0.1.x 升到 0.2.0 是纯新增：只多了配置格式的识别与上色，代码文件的既有行为不变。

0.2.1 是修复版：样式标签改用完整包名标记（data-plugin），

修掉卸载 / 热替换后 <style> 残留导致的界面串味 —— 详见下方 Fork 说明表的最后两行。

0.2.2 是修复 + 加固版（不加新功能，主要是把「看着对、实际错」的坑堵掉，另外把原本静默生效的限制说清楚）：

Vue / Svelte 的多个 <script> 块（<script> + <script setup>）现在都会被解析且行号正确；

大小写不敏感查找的行列坐标不再错位（含 İ 这类 toLowerCase() 后长度变化的字符）；

JSON 大纲的键会还原 \n \" \uXXXX 转义；查找 / 大纲的静默上限（2000 条匹配、500 个符号）

现在会在界面上说明；符号行改为键盘可达；构建内联改用函数形式替换，修掉源码里的 $&

被当成替换模式而静默改写产物的问题。详见[开发](#开发)与[已知限制](#已知限制)。

0.3.0 是新增语言版：支持 Protocol Buffers（.proto，proto2 / proto3）——

message / enum / oneof / service / extend 连同嵌套层级进大纲，rpc 成方法、

字段（含 optional / repeated / required 标签与 map<...>）与枚举值成变量；

proto2 的 group 组体挂在组名下；.foo.Bar 这类全限定名也识别。

详见下方[支持的语言](#支持的语言)。

0.4.0 是引用 chip 版：「添加到对话」不再把整段围栏块塞进输入框，而是落成

一枚与 better-sidebar 0.30 同形的引用 chip（引用 文件 L起-止）——输入框保持

紧凑，发送时才展开成同一段围栏块（载荷逐字节不变）；点击 chip 跳回源文件并

闪烁被引行段。引用数据直接存在 chip 自己的 ref 里（cnq1: + JSON），不写 storage，

刷新 / 换标签页 / 清空站点数据都不会把 chip 变死；宿主没有 chip 通道（旧版 DSH /

没有 inputTriggers）时回退到本插件自带的纯文本 chip，再回退为直接插入围栏块，

能力不丢失。

Fork 说明

来源：AnakinCao/dsh-code-nav（上游，MIT），fork 基线 commit 0d34d27。本 fork 仓库：whybebabo/dsh-code-nav。

为什么 fork：上游以 priority: 10 注册预览器，.ts 等扩展名被它接管后，内置 TextEditor 不再挂载 —— 而 better-sidebar 的「选中文字 → 添加到对话」浮层只实现在 TextEditor 内部，betterSidebar 服务面也没有任何选区 / 浮层 / 草稿 API，导致这些文件直接失去该能力。上游暂无此功能，且有本地使用需求。

相对上游的差异（v0.1.2 的改动即 PR #1 的内容；v0.2.0 追加配置文件支持；v0.2.1 修样式归属；v0.2.2 修正确性并加固构建/发布链路；v0.3.0 新增 Protocol Buffers；v0.4.0 引用 chip 可点击）：

项 · 上游 dsh-code-nav@0.1.0 · 本 fork @whybebabo/dsh-code-nav@0.4.0

选中文字 → 添加到对话 · ❌ 无（接管后该能力消失） · ✅ 选区上方浮层按钮 → 会话输入框里落成一枚引用 chip

草稿形态 · — · 与 better-sidebar 0.30 同形：引用 文件 L起-止 的紧凑 chip；点击跳回源文件并闪烁被引行段

插入载荷 · — · 发送时由 codec 展开为 相对路径:起止行 围栏块（与内置查看器逐字节相同）；>500 字只留路径行

行号精度 · — · 取自行容器 + 逐行代码列，user-select:none 的行号槽不会混入；终点落在下一行行首时区间自动收窄

插入实现 · — · 自有 @ input-trigger source（codeNavQuote）+ codec + insertReference()；宿主没有 chip 通道 / ref 解析失败时回退本插件自带的纯文本 chip（codeNavQuoteText），再回退官方 insertText()，旧版宿主回退 setDraft

浮层关闭 · — · 沿用 better-sidebar 的关闭契约：外部点击 / Esc / 页面隐藏 / 失焦 / 滚动 / 面板离开视口

配置文件支持 · ❌ 无（json / yaml / toml / xml 等落到内置查看器，无高亮与大纲） · ✅ JSON / YAML / TOML / XML / INI / properties / dotenv 的高亮 + 结构大纲

新增语言 · ❌ 无 .proto · ✅ Protocol Buffers（.proto）高亮 + 大纲：message / enum / oneof / 字段 / service / rpc / extend

大纲 / 查找的正确性 · — · Vue / Svelte 多个 <script> 块都解析且行号回加原文坐标；大小写不敏感匹配的行列位置用原文坐标（toLowerCase() 后长度变化的字符不再错位）；JSON 键还原 \uXXXX 等转义；上限（500 KB 内容截断 / 2000 条匹配 / 500 个符号）在界面上说明

包名 · dsh-code-nav · @whybebabo/dsh-code-nav（避免占用上游名称）

版本 · 0.1.0（未发布 npm） · 0.4.x（发布到 npm；版本号以 package.json 为准）

构建产物 id · 硬编码 dsh-code-nav · 由 scripts/build.mjs 从 package.json 注入，改名不再漂移；构建期校验顶层重名 / 残留 import / 导出面 / 产物逐行等于源码

<style> 归属标记 · — · 以完整包名标记 data-plugin（v0.2.1 修）：client-modules 卸载 / 热替换时按包名回收样式，短名会让 <style> 残留、界面串味

其余（高亮 / 大纲 / 查找） · 同上 · 无差异，与上游一致

支持的语言

家族 · 扩展名

JavaScript / TypeScri

…(truncated)