第一次写 DSH 插件:跟着自己的喜好实现个简单的代码管理插件

写在前面:这是一篇"第一次"的记录。第一次写 DeepSeek Harness(下文简称 DSH)插件,第一次去摸它的插件注入机制,也是第一次把一个完整的 Git 图形面板搬进一个 AI 对话工具里。文中如有理解偏差,欢迎在评论区拍砖。

一、为什么又双叒自己造轮子

我此前写过一阵 VSCode 插件,对那套 extension.ts + activate() + 各种 Contribution Point 的路子还算熟。最近在重度使用 DSH,用着用着,有个地方越来越别扭:Git 代码管理界面不太符合我的胃口。

dsh目前占用我的工作时长是最高的,但是还是会有一些去使用与操作git的场景让我不得不打开vscode,我太喜欢vscode当前这套界面了,但是这也导致了我在同一个工作目录下,却要开着两个应用并进行切换,这体验很割裂。

于是我先去找了找现成的插件。有能用的并且实现的非常完善了,但都不太对我的胃口。

想了想,与其一直将就,不如自己动手------正好也搞清楚 DSH 插件到底是怎么运作的。于是就有了 @wagq/dsh-git:一个给 DSH 会话标题栏加一枚 Git 图标,点开就是一整套源代码管理面板的插件。

先看成品:

二、DSH 插件和 VSCode 插件,到底哪里不一样

带着 VSCode 的惯性思维上手,我发现 DSH 插件的核心差异是它分两半:

VSCode 插件 DSH 插件
运行环境 一个 Extension Host 进程 host 端 (Node.js)+ client 端(浏览器 React)两套代码
UI 入口 Contribution Point 声明命令/视图 slots.inject 往对话界面预留的"插槽"里塞组件
后端能力 直接在 Extension Host 里跑 Node API host 端注册 HTTP 路由,浏览器端 fetch 调用

这个"双端"结构是理解一切的前提:

  • host 端 跑在 DSH 的 Node 进程里,能访问文件系统、能执行 git 命令、能拿到会话服务。但它不能直接操作浏览器 DOM。
  • client 端是一段注入到浏览器里的 React 代码,能渲染界面、响应点击,但碰不到文件系统。
  • 两端之间靠一套本地 HTTP API 通信------我在 host 端注册 /wagq-git/api/* 路由,client 端用 fetch 调。

有点像自己写了个前后端分离的小应用,只不过"后端"是被 DSH 加载进来的插件模块,"前端"是被注入到对话界面的组件。

三、整体架构:三层拼起来

整个插件由三块拼成,对应 package.json 里的几个关键字段:

json

perl 复制代码
{
  "main": "./dist/index.js",              // host 端入口
  "exports": {
    ".": "./dist/index.js",               // host 端
    "./client": "./dist/client.js"        // client 端
  },
  "dsh": {
    "bundle": { "patch": "./cordis.patch.yml" },
    "client": {
      "platform": "web",
      "inject": [
        "@deepseek-ai/dsh-client-ui-layout",
        "@deepseek-ai/dsh-client-ui-conversation"
      ]
    }
  }
}
  1. bundle patch 层 :cordis.patch.yml 把 host 模块插进 DSH 的 Cordis 依赖注入容器。

yaml

markdown 复制代码
- insert:
    - id: wagq-dsh-git
      name: '@wagq/dsh-git'

这里踩过一个小坑:name 填的是包名 ,不是相对路径。DSH 会通过 profile 的 node_modules(或安装回退目录)去解析它,写成本地路径会加载失败。

  1. host 端 :inject = ['webServer'],等 Web 服务就绪后注册一整套路由。
  2. client 端 :inject = ['slots'],往会话标题栏的 utilities 插槽里注册 Git 按钮。

四、host 端:把 Git 包成一套 HTTP API

4.1 执行 git:永远用参数数组,不拼 shell 字符串

这是我在 host 端立下的第一条规矩。所有 git 操作都走 execFile,参数是数组:

ts

php 复制代码
export function git(cwd: string, args: string[]): Promise<GitResult> {
  return run('git', gitArgs(cwd, args), {
    cwd,
    windowsHide: true,
    timeout: GIT_TIMEOUT_MS,
    maxBuffer: MAX_BUFFER,
    encoding: 'utf8',
    env: {
      ...process.env,
      GIT_TERMINAL_PROMPT: '0',   // 非交互环境绝不弹密码框
      GIT_OPTIONAL_LOCKS: '0',
      GIT_PAGER: 'cat',           // 禁掉分页器,否则卡在没有 TTY 的地方
      LC_ALL: 'C.UTF-8',
      LANG: 'C.UTF-8',
    },
  })
}

function gitArgs(cwd: string, args: string[]): string[] {
  // core.quotepath=false 让中文路径正常显示,而不是 \350\257... 这种八进制转义
  return ['-C', cwd, '--no-pager', '-c', 'core.quotepath=false', ...args]
}

为什么要这么较真?因为文件名、分支名里可能出现空格、引号甚至 &。一旦拼成 shell 字符串,这些字符就可能改变命令本身。用参数数组,git 收到的永远是你意图中的那几个参数。

唯一的例外是终端页签 ------用户在那儿手搓命令行,本来就要支持管道、重定向和 &&,所以那一路由特意走 shell。这是设计上的取舍,不是疏漏。

另外 maxBuffer 我调到了 64MB。git log --all 在大仓库里轻松输出好几 MB,用默认值会直接撑爆。

4.2 提交图:自己算了泳道布局

「图表」页签那张分泳道的提交图,是仿 VSCode Git Graph 做的。host 端只负责吐出扁平的 commit 节点(含 parents),真正的泳道排布在 client 端算。算法用的是经典的"第一个空闲泳道"策略,关键点是泳道不压缩------一条分支线在整个窗口里保持自己的列,不会因为别的分支结束就横向跳动:

ts

typescript 复制代码
export function layoutGraph(commits: CommitNode[]): GraphRow[] {
  const lanes: Array<{ sha: string | null; color: string }> = []
  for (const commit of commits) {
    // 优先认领"正在等自己"的泳道,否则找第一个空的
    let lane = lanes.findIndex((entry) => entry.sha === commit.sha)
    const fromTop = lane !== -1
    if (lane === -1) {
      lane = lanes.findIndex((entry) => entry.sha === null)
      if (lane === -1) { lane = lanes.length; lanes.push({ sha: null, color: laneColor(lane) }) }
      lanes[lane].color = laneColor(lane)
    }
    // ... 第一个 parent 继承本泳道,额外的 parent(merge)另开泳道
  }
}

每一行的线段(上半段/下半段/merge 曲线)都显式输出,第一行不会在节点上方画一条凭空来的线。

4.3 路由层的安全栅栏

host 端所有路由都挂在 /wagq-git 前缀下,并做了两道校验:

  • isLoopbackHost:只接受 localhost 请求,挡住 DNS rebinding。
  • isTrustedRequest:改状态的 POST 请求额外检查 Origin / Sec-Fetch-Site,拒绝跨站。

路径类的 API(文件浏览、读文件内容)全部先 realpath 再校验"必须仍在仓库根目录内",防止构造 .. 越权读到仓库外的文件。

五、client 端:一个 React 弹窗

5.1 注入按钮

client 端做的事很克制------往标题栏 utilities 插槽注册一个按钮:

ts

less 复制代码
ctx.slots.inject('conversation.session.header.utilities', () =>
  ctx.slots.register(
    { name: SLOT, id: 'wagq-dsh-git', order: 30,
      inject: ((sessionId?: string) => ({ sessionId })) as ... },
    (props) => GitHeaderButton({ sessionId: props?.sessionId }),
  ),
)

拿到 sessionId 后,再调 /api/sessions 换算出这个会话的工作目录。这样即使插槽没直接给 cwd,弹窗也能落到正确的仓库上。

5.2 弹窗的三个页签

  • 更改 :分组列出改动,点文件看 diff,鼠标悬停出现暂存/取消暂存/放弃的快捷按钮,Ctrl+Enter 提交,可勾选 amend。
  • 图表:提交图 + 提交详情,右键可复制哈希、revert、reset、rebase(破坏性操作先弹确认框)。
  • 终端:挂在仓库目录下的命令行,显示输出、退出码和耗时。

5.3 并排 diff

diff 我做了并排和行内两种视图,默认并排------左边旧、右边新。这是我从 VSCode 搬过来的最核心的体验点:

解析 patch 时我按 hunk 拆成行,再按 +/- 配对成左右两栏。未跟踪文件 git diff 看不到,我用 git diff --no-index 对空文件比一下,就能拿到同样形状的 hunk。patch 超过 60 万字符会截断并标记 tooLarge,避免把浏览器卡死。

六、亮点功能:用当前会话的模型生成提交消息

这是我最满意的一个功能。提交框下面有个 ✦ 生成提交消息,点一下,插件会把当前暂存区的 diff 发给这个会话正在使用的模型,让它写一条 commit message 自动填进去。

为什么强调"当前会话的模型"?因为我希望生成的消息风格和这段对话保持一致------你正在用一个模型聊中文需求,那提交消息也该是中文的。解析模型时有个优先级:

ts

csharp 复制代码
// 1. 会话当前 agent 的模型
const agent = agents?.get?.(sessionId)
const route = agent?.model?.current?.()
// 2. 部署默认模型
const fallback = ctx.get('agentDefaultModel')?.currentSelection?.()
// 3. 都没有就报清晰的错

只把 diff 发过去,patch 上限 12000 字符,不外传任何文件全文。模型没配密钥、被限流,按钮下方会直接说明原因,而不是让用户对着一个空白框发懵。

踩坑记录 :我最初把 system 消息塞进了 messages 数组,结果模型死活不吐文本。查了半天才发现这个适配器的 system 是顶层 option,放进 messages 会被直接丢掉。改过来就好了:

ts

ini 复制代码
const baseOptions = { messages, system: SYSTEM_PROMPT, maxTokens: MAX_TOKENS }

七、构建与调试

用 esbuild 打包,package.json 里挂了几个脚本:

json

json 复制代码
{
  "build": "node scripts/build.mjs",
  "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.client.json --noEmit",
  "smoke": "node scripts/smoke.mjs",
  "preview": "node scripts/preview.mjs"
}

开发时用 link 模式挂载本地目录,改完源码跑一次 build,刷新页面就能看到效果:

sh

csharp 复制代码
dsh plugin --profile web add "link:D:/code/dsh plugin/dsh-wa-git"

host 和 client 分别有独立的 tsconfig 做类型检查------因为两端能拿到的 Cordis context 完全不一样,我没有去 augment @deepseek-ai/cordis 的类型,而是各自定义了一份本地结构类型(host-context.ts / client/context.ts),够用且干净。

八、写在最后

从"嫌弃现有工具"到"自己撸一个",这一路下来,最大的收获其实不是那个面板本身,而是把 DSH 插件的这套双端 + 插槽注入 + 本地 HTTP API的机制彻底摸清了。回头看,它和 VSCode 插件在思想上有很多共通之处------都是往宿主的扩展点里塞东西------只是 DSH 把前后端拆得更彻底。

现在这个插件已经能覆盖我日常的绝大部分 Git 操作:看改动、写提交(还能让 AI 帮写)、看提交图、管分支远程、解冲突、敲命令。它让我在 DSH 里写代码时,不用再为了提交这件事离开对话窗口。

相关推荐
掘金酱25 分钟前
AI 带来的新生意|稀土掘金 X-Lab 年度大会招募开启
前端·后端·vibecoding
某哈压力大26 分钟前
移动端 rem 适配
前端·vue.js·面试
泯泷1 小时前
Vercel AI SDK 6 完整教程系列 - 第一部分:基础入门篇
前端·javascript
lcy_241 小时前
10 万条数据滚动不卡?聊聊我写的虚拟列表组件 vue-virtualize
前端
zhanlang02171 小时前
HTML 零基础入门到企业实战【第七章 7.5】表单验证基础属性:required、maxlength、placeholder
前端·html
涛涛ing1 小时前
为了快 30 倍,我把构建工具换成了 Rust,结果团队差点连班都加不了
前端
parade岁月2 小时前
SolidJS 2.0 正式发布:异步成为响应式的一部分
前端
lcy_242 小时前
防抖节流、并发控制、指数退避重试——我把它收进了一个库 async-concurrency-kit
前端
程序员大阳2 小时前
副队长Vue3教程(5)--事件绑定 v-on
前端·javascript·vue.js·vue3·事件绑定·v-on