@sidequest-007/dsh-atlas

dsh plugin --profile web add @sidequest-007/dsh-atlas

dsh-ATLAS

[English](README.md) · 简体中文

在内置 @ 之上：行区间如 @src/a.ts:12-40、Skill、插件与任意 git 仓库作为可选来源，并在发送前显示每条引用要花多少 token。

本项目属于 Side Quest（支线任务） 工作室（Side Quest Labs）—— npm 范围 @sidequest-007/*，仓库 jameswatt139240-crypto/dsh-ATLAS；**DSH 插件 id 沿用生态惯例的无 scope 形式 dsh-***。

<img src="assets/diagrams/atlas-overview.svg" alt="dsh-ATLAS：一个 @ 触发位、五个内置类别加内置的 git 类别，以及任何插件都能注册的自己的类别" width="880">

AT Last, All Sources.

一 @ 即达。

任何插件都能注册自己的类别，其余交给 Atlas；它画出的每个引用都是可点的链接（主题链接色，暗色下即蓝），会话链接点一下直接跳过去。

DeepSeek Harness Web 界面的统一 @ 提及插件：在输入框输入 @，即可引用工作区文件与文件夹、可发现的 Skill、过去的聊天记录、已安装插件，以及工作区的 git 改动 —— 而且任何其它插件都能把自己的类别加进同一个菜单。点一下会话引用，输入框就切到那个会话。

• 一个 @，所有来源：五个内置类别 + 内置的 @git provider（本部署里共 6 个资源族）+ 所有已注册的数据源，同一个列表；输入字母即跨类别一起搜。
• 是平台，不是取词器：第三方插件通过 ctx.atlas seam 注册自己的 @ 类别。菜单每次打开都从实时注册表重建，所以本包永远不需要为某个 provider 改代码 —— 见 [自己接一个 @ 数据源](#自己接一个--数据源)。
• 只给来源，不给内容：提交的引用只注入标记（<workspace-reference>、<skill-reference>、<atlas-reference> …）。插件只读目录项元数据；文件内容由 agent 在需要时自己去读。
• 治理写在代码里：scopes 与 testedOn 必填、id 重复直接抛错、版本不匹配注册为 verified: false、provider 正文有预算（单条 16 KiB、单步 48 KiB）。
• @git 既是范例，也是一个真实来源：它像其它类别一样列出工作区的改动（路径 + 增删行数），并且完全按第三方的方式实现，两个半边加起来约 200 行。

<p align="center"><img src="assets/diagrams/atlas-seam.svg" alt="@ 数据源 seam：浏览器半边在菜单打开时列候选，Host 半边在发送时解析一次，注册表负责门禁" width="880"></p>

它基于 dsh-at-file（MIT）扩展而来：保留原有的工作区路径索引、文件过滤规则与粘贴保护，并新增四个类别、类别菜单与快捷键、混合结果、分组折叠，以及三个模型侧查询工具。

从 dsh-at-file 过来？ 它最后一次提交是 2026-09-01，在当前的 Harness 上已经起不来：ctx.settings.register 不再是函数，插件加载时即抛错、条目被静默丢弃（上游 #45，2026-09-25 至今未关；修复 PR #47 从 2026-10-19 躺到现在）。dsh-atlas 就是同一套文件索引搬到当前 API 上——工作区路径索引、过滤规则、粘贴保护都还在，再加上前面那些类别。二者占用同一个触发位，装一个。

安装

前置：装好 DSH（dsh 在 PATH 上）并有一个 web profile。

# 从 GitHub 装（本仓库；lib/ 已随仓库提交，安装时不会触发构建）
dsh plugin --profile web add github:jameswatt139240-crypto/dsh-ATLAS

# 本地克隆（开发）
git clone https://github.com/jameswatt139240-crypto/dsh-ATLAS
dsh plugin --profile web add link:/path/to/dsh-ATLAS

# npm 包（已发布；`latest` 即当前版本）
dsh plugin --profile web add @sidequest-007/dsh-atlas

安装或更新后重启 dsh web，确保 Host 与浏览器客户端都加载同一版本。然后在输入框打 @。

类别

输入 @ 后，菜单顶部是五个常驻类别行；也可以直接输入关键字跨类别混合搜索。

类别 · 菜单前缀 · 快捷键 · 候选来源 · 选中后写入草稿

文件 · file: · F · 当前会话工作区索引 · @src/index.ts

文件夹 · folder: · D · 同上 · @src/client/

Skill · skill: · S · ctx.skills 技能注册表 · @skill:blender-modeling

过去的聊天 · chat: · C · 官方 session-reference 解析器 · @[标题](dsh-session:<id>)

插件 · plugin: · P · 官方 plugin inventory · @plugin:dsh-atlas

单个快捷键字母是"意图"而不是"查询"：输入它只显示类别行——五个内置类别 + 内置的 @git——以及一行「Tab 补全 → 类别:」提示，且这行提示在最下面（高亮也已经落在它上面），按 <kbd>Tab</kbd> 或 <kbd>Enter</kbd> 即进入对应的 类别: 前缀。注册的数据源也能有快捷键字母：取 provider id 的首字母（@git → <kbd>G</kbd>），只有在该字母没被内置类别或更早注册的 provider 占用时才生效（@<id>: 前缀永远可用）。过滤从更具体的东西开始：不是快捷键的首字母，或第二个字符（fi/fo/sk/ch/pl 这类前缀本来就是两个字符）。点击类别行或「返回类别」行同样进入/返回，且菜单保持打开（这是本插件的两处覆写：正常 pick 路径会关闭菜单）。

第六行起是"已注册数据源"。 @git 已内置（工作区的变更文件，引用内容就是该文件的 diff），任何插件都能用同样的方式加自己的类别——见[自己接一个 @ 数据源](#自己接一个--数据源)。它们排在内置类别之后、按注册顺序出现，注册它们的插件被销毁时一起消失。插件自身的分组以正的 order 注册，因此它是菜单里的最后一个分组：底部那条工作带归本插件，框架自带 dsh-client-ui-reference 数据源的文件列表留在它上面。

交互

• 直接输入字母：跨类别混合搜索，结果按「最近引用」与「全部匹配」两段展示，每行带类别标签；类别行（五个内置 + 内置的 @git）始终在最下面的工作带里可点选。
• 文件夹：@folder: 类别列出目录，选中后写入 @路径/（末尾的 / 才是「目录」的标记，插件依然只读目录项元数据）；在斜杠后继续输入即可在该目录内收窄搜索。过滤时结果分两档排序：先按名称命中的文件夹（工作区内的在前，工作区外的在后），再是只有路径命中的那些，收进它们自己的 路径匹配 组。那一组默认展开、装得下就显示，折叠与否是你的手势。
• 先写的文件夹会成为后面文件列表的作用域：@e:/work/docs/ @file: 会先列出该文件夹自己的文件（一层，走的是文件夹 tab 同一套目录列表），组标题写明它来自哪个文件夹、并标明在工作区之外，然后才是工作区里的命中项。作用域是位置决定的——当前 token 之前最近的那个文件夹引用——所以不需要连接词；草稿里没有文件夹引用时行为与以前完全一致。
• 分组折叠：Skill 按管理层级（系统 / 用户 / 项目 / 自定义 / 插件）再按领域分组，插件按 npm scope（@deepseek-ai/… 或「其他」）分组，过去的聊天按工作区分组、子会话缩进在父会话下；组标题点击即可折叠/展开；当高亮行正是该组标题时按 <kbd>Enter</kbd> 同样折叠/展开。<kbd>Tab</kbd> 补全、<kbd>↑</kbd><kbd>↓</kbd>、<kbd>Esc</kbd> 全部由框架自己的 keymap 提供。除此之外插件只加三个键：高亮组标题上的 <kbd>Enter</kbd> 折叠、类别行/返回行选中后保持菜单打开、以及 <kbd>PageUp</kbd>/<kbd>PageDown</kbd> 按实测一屏翻页——翻页移动的是高亮（高亮属于别的数据源时就只滚列表），所以"看得见的那一行"永远是你正在操作的那一行。
• 列表长了就滚动，不再靠隐藏行数：单个类别最多 MAX_CANDIDATES（20）行，装不下就由菜单滚动——<kbd>PageUp</kbd>/<kbd>PageDown</kbd> 一屏一屏走，且内容变化时（作用域目录列表后到、某组被折叠）插件会把焦点行重新拉回可视区。也就是说不会为了菜单短一点而丢行；谁排在前面由上面的分档决定。
• 相对时间：历史会话与工作区行显示「刚刚 / 5分钟 / 3小时 / 2天」等相对时间。
• 初始视图：@file: 先列出最近引用过的文件（最近的在前，按工作区持久化），其后按字母序。
• 引用成本与失效提示：引用栏里的每个文件引用会显示约 token 成本（如 ≈1.2k tokens；超过 8000 token 时高亮）；若引用的路径在工作区内已不存在，会标出「已失效」。成本取自文件大小（约 4 字节 / token），插件只读目录项元数据，不读取文件内容。
• 错字容错：文件名的轻微拼写错误（如 veiw → view.ts、clinet → client/…）仍能命中。精确匹配优先——只要精确排序有结果，就不会混入模糊结果；长度小于 3 或含 / 的查询保持精确。
• 行范围引用：直接手打 @src/a.ts:12-40 即可引用该文件的第 12–40 行（单行写 @src/a.ts:7；倒序 40-12 会自动归一为 12-40）。目录不接受行范围。Host 只校验语法与路径类型，不会打开文件，因此行号是否越界由 agent 读取时判断。
• 引用栏：输入框上方按顺序显示当前草稿里的每个引用；文件、文件夹与 provider 行可点击打开，每行的 <kbd>×</kbd> 移除对应 token。
• 草稿里任何能打开的 @路径 都是链接：判断依据是插件自己——token 能解码成引用、并且宿主确认该目标存在——而不是框架有没有把它装饰成引用。所以手打的 @AGENTS.md 和框架认出来的 token 一样：整条变蓝、点任意位置都打开、鼠标变手型。上色用 CSS Custom Highlight API 逐段绘制（Lexical 的文本 span 只允许一个文本子节点，包裹尾巴会破坏输入），颜色取框架给引用用的同一个变量。目标已不存在的 token 也不会被当成普通文本，而是按引用栏那套「已失效」语言画成暗色 + 删除线——它是引用，只是打不开。判定时机：只有写完的 token 才会被判失效（后面跟着空白，或后面还有下一行＝按过回车）；正在输入的 token 不下结论——@N 这种中间态必然"不存在"，边打边画删除线等于替用户还没写完的词下判决。能打开的 token 则在名字写成的那一刻就变蓝（与框架自己的引用装饰一样即时）。引用栏还没回答、provider 没声明 open、或名字放不下的 token 什么都不说、保持普通文本。浏览器不支持 highlight API 时什么都不绘制，此时只有框架自己上过色的那部分可点（没画成链接就不表现得像链接）。
• 草稿里由其它数据源插入的 chip 也能点：右侧栏的文件树就是往草稿里插一条原子 chip，这个客户端把它画成框架自己的 chip 蓝、并且不接任何点击。点它即打开它命名的文件，随后 chip 会带上插件的链接语言。那个数据源给 chip 的标签是文件名（完整相对路径只存在于草稿文本里），所以裸文件名按两步还原：①在插件索引里找同名 basename，唯一命中即用；②索引里就有歧义（例如 index.ts 在工作区里有两处）时回退到**草

…(truncated)