dsh-compass 已发布,右侧文件夹面板和只读 git tree

[Happy2Git]

这个面板写了两天,今天刚发布到 GitHub。仓库在 Happy2Git/dsh-compass,先给这里的社区看一眼。

dsh-compass 是一个单包插件,装进 web profile 以后,对话区右侧多出一块固定面板,和左侧边栏对称。面板里有三个标签。

文件夹标签是一棵惰性目录树。列目录时目录排前面,文件排后面,两组各自按名字排序,指向目录的符号链接算目录。点击文件行直接在中部弹出预览,支持 Markdown 渲染和普通文本,256 KiB 以上的文件截断显示。每行都能复制路径,也能用系统默认应用打开。

Git 标签画只读提交图,参照了 vibe-ide 的 GitGraph。泳道按分支排,合并回到主干,HEAD 和标签都有徽章。点击提交懒加载改动文件,新增、修改、删除三种状态,行数变化也一起显示。

上下文标签列出本次会话注入的上下文文档,指令文件和运行时注入分开标记,支持往前翻更早的页面。面板头部还有会话日志下载,导出一个 ZIP。

安装走官方插件通道,一条命令。git 安装会触发包的 prepare 构建,首次需要按提示放行一次。

dsh plugin --profile web add github:Happy2Git/dsh-compass#v0.1.0

有一点要说清楚。面板依赖槽位系统,这套系统已经在当前 master 里,但最后一次 npm 发布早于它。所以在下一个版本发布以前,只能装到从 master 构建的 dsh 上,或者装到我们维护的 fork 上。fork 的默认 web profile 已经内置了这套面板,想用插件版本的话,把内置四行在 profile 补丁里禁用即可,README 里有完整说明。

我们把面板和它依赖的能力面一起开源了,git 能力、目录路由、面板本体都写在包内,不碰核心网关。欢迎试用,有什么想法直接在仓库提 issue。

[zoahdev]

Right-side context file panel is a solid gap - the conversation column gets claustrophobic without a files/git sidecar.

Added dsh-compass to the dsh-subscribe registry (554 plugins) for discovery: github:Happy2Git/dsh-compass.

Two quick suggestions from the UI-plugin side:

1. Persist the panel state (width, active tab, collapse) per profile so a reload doesn't reset it - same lesson as dsh-web-shell's fold-vs-close separation.
2. If the git tab reads the profile's git state, make sure it uses the same isGitRepository probe as the workspace registry (canonical path), so it doesn't hit the "not a git repository" false negative seen in [BUG] Git panel shows 'not a git repository' even when .git exists #1938.

Happy to cross-link from the ecosystem map once you have a release tag.

[Happy2Git]

Thanks for the registry add and the review!

1. Shipped in v0.1.1. The panel store now persists width, active tab, and collapse to localStorage per browser origin, and a rehydrated centered preview is cleared on load so a reload never reopens it.

2. On the git probe, dsh-compass runs git -C <cwd> directly against the session's cwd and lets git's own discovery walk up the parent directories, so it never compares paths itself. I could not find [BUG] Git panel shows 'not a git repository' even when .git exists #1938 in the public repos; could you link it and the isGitRepository probe you mean? If it is a real false negative (symlink, worktree, or canonical-path mismatch), I am happy to align.

[Happy2Git]

On cross-linking, dsh-compass now has release tags v0.1.0 and v0.1.1, so it is ready for the ecosystem map whenever you are.

If you get a chance to try it, the whole thing is one package and one loader row. The directory browser and the git backend ship inside the package, and the panel only needs a dsh build whose web composition has the slot system. Feedback is welcome, and if your registry wants a short description or a specific install path, I am glad to add it.

[Happy2Git]

这个面板第一天是在官方仓库里直接改的,其实很顺手。dsh 的架构本身就是插件式,每块功能都是独立的包,当时觉得"一切皆插件"嘛,发布的时候拆出去还不简单。结果今天真到发布,发现完全不是那么回事,光解耦就花了一整天。

难在哪。面板待在仓库内部的时候,读目录借的是仓库里的目录服务,读文件借的是仓库里的读取接口,类型、构建、测试全都长在大仓库身上。想把它单独发出去,这些依赖要么自己带,要么砍掉,每一个都要动手。

今天做的事就是拆。目录读取改由包自己读文件系统,不再依赖仓库内部的目录服务;git 后端、面板本体合成一个包;构建改成纯转译,clone 下来就能编译;再一个个验证安装、路由、界面,拆完才敢发。

所以经验就一条,在仓库里是插件,和能独立发出去,是两回事。新功能从第一天起就要按独立可发布的标准写,别等发布那天再解耦。

还有个开发体验上的感受。写插件的热插拔不算丝滑,改完代码经常要重新构建、重启服务、刷新页面才看得到效果,后端侧的改动每次都要重启服务。开发这两天,不少时间花在这来回上。

上面这段是我自己的经历。下面几条技术经验,是这次写代码的 agent 根据对话记录自己总结的,贴在这里给做同类插件的人参考。

第一,插件的能力要自带传输。面板的目录和 git 都走插件自己的路由,不碰核心 API 网关。网关是 web、终端、SDK 所有入口共用的,一个界面的私有功能不该长在里面。

第二,宿主路由能读任意本地路径,安全上我们凑了六件事。只许本机访问,只收类型正确的 JSON,请求体限 64 KiB,路径必须写全,git 输出按字节截断,客户端断开就停掉子进程。

第三,发布前多翻上游 master。槽位系统、会话接口大部分都在上游,fork 独有的只有 readText 这类小原语。把缺的能力写进包内,面板就能装到任何带槽位系统的构建上,上游下一次发布以后直接装主线。

第四,git 安装装的是源码,包的 prepare 脚本必须纯转译自包含,不碰类型检查,也不依赖开发仓库的结构。pnpm 10 以上首次还要放行一次构建脚本。

第五,发布走 GitHub-only 的 git spec,一条命令装完,不用上 npm,也不占 @deepseek-ai 的命名空间。

[Happy2Git]

Git 功能这块单独贴一张图,顺便说下它是怎么做的。

Git 标签画的是只读提交图。每个分支一条泳道,合并回到主干,HEAD 和标签名都有徽章,点击提交展开这次改动过的文件。

后端没有用 git 库,直接跑系统的 git 命令,两条就够。列表一条,git log --all --topo-order --date-order --skip=N --max-count=N+1 --pretty=format:%H%x00%P%x00%D%x00%s%x00%aN%x00%aI%x1e,字段用 %x00 分隔、记录用 %x1e 分隔,多取一条用来判断还有没有下一页。详情一条,git show -m --first-parent --no-renames,元信息和文件名状态合在一次调用里,行数变化再单独取一次,按路径合并。

两个参数值得说。-m --first-parent 让三种提交都 diff 得明明白白,普通提交比第一父提交,合并提交比第一父提交,根提交比空树,不会出现 git show 默认那个空空的合并 diff。--no-renames 把重命名摊成删除加新增,文件路径就成了稳定的合并键,状态只有新增、修改、删除三种。

边界也做了。提交页最多 100 条,单个提交的文件最多 500 个,git 输出按 256 KiB 截断,截断了就直接报错,不返回半截解析结果。路由是插件自己的,只允许本机访问。

[Electricitysheep]

右侧文件夹面板 + 只读 git tree——两天写出来效率可以，文件树 + git 状态一屏看完很实用。

已收录进手册生态章节：https://github.com/Electricitysheep/dsh-handbook/blob/main/docs/07-ecosystem.md

[Happy2Git]

dsh-compass 发布之后又走了十几个版本，现在停在 v0.11.3。挑几件和这个帖子主题直接相关的新东西记在这里。

文件树现在带 git 状态徽章，未跟踪、已修改、被忽略的文件一眼能分开。文件行可以拖进对话，视觉模型直接把图片内容附加进消息，其他模型收到路径说明，由 agent 用自己的工具处理，不在工作区复制任何文件。git 板块加了和工作区区块同款的外框与标题，工作区里的文件行点开就是该文件的 diff，提交内文件同样可点。diff 预览按行着色，只染文字不染底色。

上下文标签改动最大。它跟着会话事件流实时更新，新注入的文档自己出现，并且能拿到完整历史。宿主侧新增了 /dir/injected-docs 路由，在服务端把持久化日志过滤一遍，只把注入文档相关的事件发给浏览器。这个改动来自一次实测，在 18 万事件的会话上，历史 RPC 一页 50 条消息的响应有 6 到 7 MB，旧方案一次激活要解码约 120 MB，过滤后一次请求只有 KB 级。文档流也做了签名门控，面板只在文档真正变化时重渲染，不再跟着每个流式批次抖动。

过程里踩过两个坑,一并记下。中间有一版自动遍历直接翻共享的会话窗口，把聊天视图自己的「加载更早」消耗掉了，还干扰了滚动锚点，后来改成面板走自己的路由取数据，不碰共享窗口。另外，插件新增宿主侧路由之后要重启 dsh web，只刷新页面换不到新路由。

范围仍然克制，面板只读，提交、暂存、推送这些写操作继续留给 agent。全部版本的发布记录在 https://github.com/Happy2Git/dsh-compass/releases 。

[leenkcool]

#1728 可以自己提PR收录 。记得互相赞赏。

你这个挺好的。

[Happy2Git]

README 和截图都刷新过了，对应当前 v0.12.0。六张图由仓库里的截图脚本在真实封闭脚手架中自动生成，功能再变重跑一条命令就能重新生成，发布记录见 https://github.com/Happy2Git/dsh-compass/releases/tag/v0.12.0 。

Git 板块，工作区区块与提交树都带外框，工作区文件行点开就是 diff，diff 只染文字色。

上下文板块，当前有效与历史流水都按时间倒序，历史流水自动拿到完整历史。

文件夹板块带 git 状态徽章，文件行可拖进对话，视觉模型直接收图。

README 新增了安全与性能两节。安全上，所有宿主路由仅限回环，请求体 64 KiB 上限，路径必须完全限定，读取失败即关闭，git 只读，图片从不复制进工作区。性能上，文档流做了签名门控，面板只在文档真正变化时重渲染；完整历史走 /dir/injected-docs 在服务端过滤，在 18 万事件的会话上把每次激活约 120 MB 的历史页 JSON 换成单次 KB 级响应。

[Happy2Git]

@zoahdev @Electricitysheep @leenkcool @lz425-code 上面两条评论把发布后的更新整理了一遍，六张新截图和安全、性能的实测数据都在里面。

顺带把你们几位之前提到的事回一下。zoahdev 说的面板状态持久化已经做了，面板宽度、展开收起、激活标签页都会跨刷新保留，这条修好之后还顺手改了持久化重放的合并方式，旧版本地存储升级时面板不会再消失。Electricitysheep 收录的手册条目如果方便，可以用新截图换掉旧的。leenkcool 指的那个收录入口我们看到了，后面单独整理提交。

lz425-code 你在 issue #1938 里提的问题，如果有和面板相关的部分，欢迎把链接贴过来继续说。

[Happy2Git]

v0.13.0 发布，这次更新只为一件事：官方主线打通。从官方仓库 master 源码构建的 dsh，现在可以直接装 compass，面板可用，不再需要 fork。

实测路径：上游 master（钉 47f9438）干净构建，dsh plugin --profile web add github:Happy2Git/dsh-compass#8b0aaa4，面板三个标签、/dir 与 /git 路由、会话日志导出全部正常。npm 发布版仍然不行——它老于槽位系统，这一条要等下一次上游发版，README 的口径已从「官方 dsh 不可用」改为「npm 太旧 / master 源码构建可用」。

期间修了三个实际问题，都值得记下来：

1. /export 撞名。 上游 master 的 dsh-web-app 自带 session-log-download 行，它的 /export 命令与包里的撞名，boot 直接失败。修法是包自己的 bundle patch 禁用该行——插件层排在官方 bundle 之后必胜，无该行的旧构建上是空操作。ZIP 端点 /api/session.export 属于 apiproxy，不受影响。顺带 fork 侧的「禁用内置四行」减为三行。

2. 导出一直是半成品，现在补齐了。 抽包时 session-export 的浏览器半（下载控制器、对话框、面板头按钮）带出来了但没有接线，/export 此前只回一句提示、不真下载——fork 上同样如此。已按原版补齐，现在按钮、对话框、真下载在两种宿主一致。

3. 拖拽在上游宿主降级可用。 上游 composer 不认 application/x-dsh-path 拖拽 MIME，包里新增了整窗接收器：未被宿主认领的拖放把路径句追加进草稿，agent 用自己的工具处理；宿主自己认领（fork）时接收器完全让位，两种宿主都只有一条接收链路。图片直接附内容仍需 fork 的 composer 或上游采纳该 MIME。

一条安装提示：pnpm ≥10 的 allowBuilds 键要用它打印的完整 40 位 commit sha，短 sha 会被再次拦下。全部变更见 https://github.com/Happy2Git/dsh-compass/releases/tag/v0.13.0 。

@leenkcool 1728 那边的收录指引看到了，这就向 Blue-Whale-Harness 提 PR，谢谢整理。

[Happy2Git]

跟进一下 v0.13 之后的更新，两个版本加一个修复，都已在官方 master 源码构建上实测。

v0.14 —— 上下文标签从被动面板变成事件驱动入口。 标签头新增占用条：按实测 UTF-8 字节分「当前有效 / 已压缩」两行，按来源五类着色（指令文件 / 技能注入 / 插件注入 / 跨会话召回 / 运行时注入），不做 token 估算冒充真值。每篇文档带来源标注与实测大小，历史流水头部注明最近一次压缩移出的篇数与体量（12 小时会话实测：当前有效 5 篇 · 46.6 KiB，已压缩 27 篇 · 367.2 KiB）。不在上下文标签时，新注入和压缩边界移动会在「上下文」标签页上挂未读计数徽标，打开即清零，面板折叠时显示圆点——注入、压缩这些事件本身成为入口，不用等用户巡检面板。

v0.15 —— 文件夹标签的目录行有了 git 状态。 之前只有文件行带字母徽章（A/M/D/U/!），目录行只有整目录被忽略时才显示 !。现在目录行聚合其下最强的状态：src 里改了一个文件就显示描边的 M（目录内含修改），含未跟踪显示 U，含删除显示 D，聚合优先级 M > A > D > U > !。同一份 porcelain 输出折叠出聚合，零额外 git 调用。顺带修了一个让徽章整体消失的边界 bug：status --ignored 会把 node_modules 里每个文件都列出来（fork 仓库根目录实测 14 MB，超过 256 KiB 上限直接报错、根目录一个徽章都没有），改为 ls-files --directory 折叠列出后同一根目录只要约 18 KB，截断时只丢忽略项、M/A/D/U 永远完整。

一个修复 —— 对话区随面板宽度联动。 抽包时丢了一段关键 CSS：变量发布了但没人消费，上游宿主上面板只是悬浮盖在对话区右侧，拖宽面板中间不动。已补回（针对对话列根节点的稳定 data-phase 属性 + [data-shell-overlay] 门控），实测面板 280→380 px 时对话列内边距同步 280→380 px。

另外，@leenkcool 1728 收录帖那边的 PR（Happy2Git/Blue-Whale-Harness#35）还在审查中，等收录。

全部代码都在 https://github.com/Happy2Git/dsh-compass （main 最新 = 5c47b11），安装方式不变。

[zoahdev]

状态持久化做得干净——宽度/折叠/激活标签跨刷新保留，比当初提的 fold-vs-close 分离更进一步。/dir、/git 路由在 master 源码构建下打通官方主线，这条对后来者很有参考价值（槽位系统之前 npm 包不可用的坑也写清楚了）。

注册表这边已收录：dsh-subscribe registry（554 插件）里可以直接搜到 dsh-compass。如果需要发布前体检，dsh-plugin-doctor 可以跑 manifest / build / pack / profile-shadow 全套，JSON 输出和退出码都是机器可读的——插件作者之间互相把关，生态才稳。

[Happy2Git]

一条理念向的分享：dsh-compass 的上下文标签，本质是给 Agent 的"思维透明"加了一个观测窗口——你的模型每一步实际收到了什么，现在可以亲眼看到。

轨迹板块展示的是"Agent 做了什么"（行为投影）；上下文标签展示的是"Agent 此刻知道什么"（状态投影）。两者读的是同一份持久日志，一个事件日志、两个投影——行为有出处，知识也该有出处。对长会话排障（"它怎么忘了 X"）来说，后者往往更直接。

具体能看到的：

• 注入清单即真相：每一条进入模型上下文的文档都列出来——指令文件（AGENTS.md 这类）、技能注入、插件注入、跨会话召回、运行时注入，五类来源带颜色区分，旁边标注实测大小。点击任意一行直接看原文，无需猜。
• 占用一目了然：标签头有按字节实测的占用条，分"当前有效 / 已压缩"两段，谁占了多少、压缩把什么移出了窗口，一眼看清。实测一个 12 小时会话：当前有效 5 篇 · 46.6 KiB，已压缩 27 篇 · 367.2 KiB。
• 压缩不再黑箱：历史流水头部直接写明"最近一次压缩将 N 篇（X KiB）移出了模型有效窗口，仍保留在持久日志中"——压缩发生时你知道代价，而不是事后困惑。
• 事件驱动入口：不在上下文标签时，新注入和压缩边界移动会在标签页上挂未读计数，打开即清零——注入、压缩这些事件本身成为入口，不用等用户巡检面板。

安装与用法不变：dsh plugin --profile web add github:Happy2Git/dsh-compass#<commit>，全部代码在 https://github.com/Happy2Git/dsh-compass 。欢迎试用，透明化到什么程度合适、还缺什么视图，都值得聊。

[Happy2Git]

接着上一条透明化，补一个角度：上下文注入的透明化，本身就是安全能力。

注入是 Agent 的"隐形输入"——模型被什么影响，通常只有日志知道。compass 把每一份注入文档的来源、路径、大小、时间摊开之后：

• 提示注入面可审计：指令文件、技能注入、插件注入、跨会话召回各有标签，用户能核对"模型实际被喂了什么"，而不是信任黑盒。跨会话召回尤其值得留意——它把另一个会话的材料带进当前上下文，透明化让这类越界输入一眼可见。
• 压缩透明 = 信任不塌方：看到"最近一次压缩将 27 篇 · 367.2 KiB 移出有效窗口"，意味着你清楚模型视野的边界在哪，不会误以为"它应该记得"——这比事后困惑更安全。
• 只观测、不触碰：面板全程只读，从不修改上下文；目录与 git 读取走插件自有路由，仅回环、路径必须完全限定、输出有界，安全基线和功能是同一套代码写死的。

一句话：看不见的输入才危险，看得见的输入可以审计。