写在前面:这是一篇"第一次"的记录。第一次写 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
{
"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"
]
}
}
}
- bundle patch 层:
cordis.patch.yml把 host 模块插进 DSH 的 Cordis 依赖注入容器。
yaml
- insert:
- id: wagq-dsh-git
name: '@wagq/dsh-git'
这里踩过一个小坑:name 填的是包名,不是相对路径。DSH 会通过 profile 的 node_modules(或安装回退目录)去解析它,写成本地路径会加载失败。
- host 端:
inject = ['webServer'],等 Web 服务就绪后注册一整套路由。 - client 端:
inject = ['slots'],往会话标题栏的 utilities 插槽里注册 Git 按钮。
四、host 端:把 Git 包成一套 HTTP API
4.1 执行 git:永远用参数数组,不拼 shell 字符串
这是我在 host 端立下的第一条规矩。所有 git 操作都走 execFile,参数是数组:
ts
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
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
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
// 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
const baseOptions = { messages, system: SYSTEM_PROMPT, maxTokens: MAX_TOKENS }
七、构建与调试
用 esbuild 打包,package.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
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 里写代码时,不用再为了提交这件事离开对话窗口。