# @civilization/dsh-git-workbench 中文文档

规范地址：https://npmcn.com/package/%40civilization/dsh-git-workbench/

版本：0\.4\.8
npm 元数据更新时间：2026-10-26T13:16:01.069Z
中文译文更新时间：2026-11-09T22:49:27.659Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40civilization/dsh-git-workbench
原文对照：https://npmcn.com/package/%40civilization/dsh-git-workbench/?lang=original
项目主页：https://github.com/civilization-os/dsh-git-workbench#readme
源码仓库：https://github.com/civilization-os/dsh-git-workbench

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：637 kB，24 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=20\.0\.0
- 运行依赖：1 个
- peer 依赖：react \>=18\.0\.0，react-dom \>=18\.0\.0，@deepseek-ai/cordis \>=4\.0\.0，@deepseek-ai/dsh-tools \>=0\.1\.2-rc\.1，@deepseek-ai/dsh-host-webserver \>=0\.1\.2-rc\.1
- 首次发布：2026-10-21T16:58:37.720Z
- 最新版本发布：2026-10-26T13:16:00.585Z
- 近 30 天下载量：1751（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：10（近 12 个月 10 个）

## 中文简介

IntelliJ IDEA 级别的 Git 版本控制工作台；DAG 拓扑提交图谱、多分支合并轨道可视化、状态栏底部分支切换胶囊与全量变动管理。

## 安装

```sh
npm install @civilization/dsh-git-workbench
```

也可以使用：`pnpm add @civilization/dsh-git-workbench`、`yarn add @civilization/dsh-git-workbench`、`bun add @civilization/dsh-git-workbench`

## README

# @civilization/dsh-git-workbench

**IntelliJ IDEA 级别的专业 Git 版本控制工作台插件，专为 DeepSeek Harness (DSH) 打造。**

本插件为 DeepSeek Harness 提供了媲美 IntelliJ IDEA / VS Code 的全套 Git 工程化版本控制能力，包括 **DAG 拓扑提交图谱**、**多分支合并轨道渲染**、**工作区变动检查与暂存提交**、**底部分支快速切换胶囊**、**全量标签管理与 DAG 视图定位**、**彩色代码差异对比**，以及供 AI Agent 自主调用的 **Git 原生模型工具集**。

> **说明**：本插件已实现完全独立化拆分，**严格仅依赖官方公开 API 组件**（`@deepseek-ai/cordis`, `@deepseek-ai/schemastery`, `@deepseek-ai/dsh-tools` 及 React 18），**没有任何私有组件库或单体仓库内部包的依赖**，可在官方纯净版 DeepSeek Harness 环境中直接安装使用。

* * *

## 🌟 核心特性

### 1\. 🌲 IntelliJ IDEA 级 DAG 提交拓扑树与轨道图

-   **多泳道动态压缩算法**：根据提交历史（`git log --parents`）精确计算并排分支泳道，支持主线、特性分支、热修复分支与合并分支。
-   **平滑贝塞尔曲线连线**：基于 SVG 实时渲染分支分叉与合并连接线，采用 IntelliJ 调色板渲染多彩轨道。
-   **提交引用徽章**：直接在提交节点旁渲染带颜色与边框的 `HEAD`、当前分支（高亮绿）、本地分支（蓝）、远程分支（紫）与发布标签（橙）。
-   **Conventional Commits 智能解析**：自动解析 `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore` 等类型前缀，渲染高对比度彩色胶囊。
-   **主线筛选与全文过滤**：支持「全部 / 仅主线」切换，并提供按 Commit Hash、提交信息、作者名字的即时高亮检索。

### 2\. 🗂️ 工作区代码改动（Changes）与快捷提交控制台

-   **三态工作区树形/扁平分类**：
    -   **已暂存改动 (Staged Changes)**
    -   **未暂存改动 (Changes)**
    -   **未追踪文件 (Untracked Files)**
-   **快速动作支持**：单文件/批量一键 Stage、Unstage、丢弃更改（Discard）、全选暂存。
-   **快捷提交控制台 (Commit Console)**：
    -   内置提交说明输入框，支持 `Ctrl+Enter` 快速提交；
    -   顶部集成常见 Conventional Commits 前缀快捷插入芯片（`feat:`, `fix:`, `docs:`, `refactor:`, `chore:`）。
-   **实时同步工具栏**：支持一键 `Fetch`、`Pull`、`Push` 与 `Refresh`。

### 3\. 🏷️ 全量标签管理器（Tags）与 DAG 拓扑精确定位

-   **现代 Release 卡片布局**：采用 GitHub / JetBrains 风格的两行式紧凑卡片，彻底移除了原生操作系统杂色 Emoji，全量采用矢量 SVG 图标与 DSH 官方设计变量（`--dsw-alias-*`）；
-   **Conventional Commits 智能解析**：标签附注与提交说明自动解析 `feat`, `fix`, `chore` 等前缀并高亮展示规范徽章；
-   **作者头像与相对时间**：采用确定性调色盘渲染作者首字母圆形头像，清晰直观；
-   **标签创建与删除**：支持创建轻量标签（Lightweight）或带说明的附注标签（Annotated），支持为指定 Commit 打标；
-   **一键精确定位与视口居中**：在标签列表中点击「在拓扑树中定位」图标，自动平滑切换到提交图谱视图，精确定位至对应 Commit 节点并带有呼吸光晕高亮与平滑滚动居中。

### 4\. 🔀 分支管理与底部分支切换胶囊（Composer Dock Pill）

-   **顶栏交互联动**：点击顶栏分支徽章直接平滑跳转至分支管理视图；
-   **分支管理视图**：提供即时搜索过滤栏、一键新建并检出分支、本地与远程分支矢量状态标识及「当前检出」高亮徽章；
-   **注入 Composer Dock 状态栏**：注入官方对话框底部的 Composer Dock 状态栏（顺序优先）；
-   **实时分支与领先/落后状态**：实时展示当前所在分支与远程追踪状态（`↑ahead` 本地领先 / `↓behind` 落后远程）；
-   **微弹簧触感反馈**：严格遵循 UI Motion 规范（`cubic-bezier(0.16, 1, 0.3, 1)`），提供灵敏丝滑的悬浮与点击反馈。

### 5\. 🔍 彩色代码差异对比查看器（Unified Diff）

-   点击工作区任意改动文件或 DAG 拓扑图中的任意提交，右侧立即展开对应代码差异；
-   增删行彩色对比高亮（绿色背景新增、红色背景删除、淡紫色块头范围定位）。

### 6\. 🤖 AI Agent 原生感知与控制模型工具集

插件自动向模型注入以下标准 Tools：

-   `git_view`：自主查询状态、提交图谱、分支列表、差异内容与标签列表。
-   `git_checkout`：自主切换分支或创建检出新分支。
-   `git_tag`：自主创建版本标签或清理临时标签。

* * *

## 🏗️ 架构与技术实现

-   **独立双端输出**：
    -   **Host Node 端** (`lib/index.js`)：采用标准 Cordis ESM 插件规范，注册 `/git` 安全 RPC 拦截器与 Agent 工具。
    -   **Client Browser 端** (`lib/client.js`)：打包为自包含的浏览器端模块，遵循 `window.__ModuleLoader__.load({ id: '@civilization/dsh-git-workbench', factory: ... })` 协议。
    -   **自包含样式编译**：利用 `lightningcss` 在构建期将 CSS Modules 直接转译并内联在 Client bundle 中，载入时自动注入 `<style data-plugin="@civilization/dsh-git-workbench">`，无需宿主额外加载外部 CSS。
-   **公共依赖**：
    -   `@deepseek-ai/cordis`: `^4.0.0`
    -   `@deepseek-ai/dsh-tools`: `^0.2.0`
    -   `@deepseek-ai/schemastery`: `^3.18.5`
    -   `react`: `^18.0.0`

* * *

## 📥 安装与使用指南

### 1\. 安装依赖

在官方 DeepSeek Harness 运行时环境或项目中安装：

```bash
pnpm add @civilization/dsh-git-workbench
```

### 2\. 在 `cordis.yml` 中启用插件

编辑运行配置文件 `cordis.yml`（或通过 `cordis.patch.yml`）：

```yaml
plugins:
  - name: "@civilization/dsh-git-workbench"
```

启动 DeepSeek Harness 后，右侧栏将出现专属的 **Git** 图标标签页，底部状态栏将展示实时的分支胶囊。

* * *

## ⌨️ 快捷键

-   `Ctrl + Shift + G`（Windows / Linux）或 `Cmd + Shift + G`（macOS）：一键呼出并聚焦右侧 Git 工作台。
-   `Ctrl + Enter`：在提交信息框中一键触发提交。

* * *

## 🛠️ 本地开发与测试

```bash
# 进入插件目录
cd D:\project\dsh-plugins\dsh-git-workbench

# 安装依赖
pnpm install

# 静态类型检查
pnpm run typecheck

# 单元测试（基于 Vitest）
pnpm run test

# 生产环境打包构建
pnpm run build
```

* * *

## 📄 开源许可证

本项目基于 [Apache-2.0](https://npmcn.com/package/%40civilization/dsh-git-workbench/LICENSE) 协议开源。

## 常见问题

### @civilization/dsh-git-workbench 是什么？

IntelliJ IDEA 级别的 Git 版本控制工作台；DAG 拓扑提交图谱、多分支合并轨道可视化、状态栏底部分支切换胶囊与全量变动管理。

### 如何安装 @civilization/dsh-git-workbench？

在项目目录运行 npm install @civilization/dsh-git-workbench，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\>=18\.0\.0）、react-dom（\>=18\.0\.0）、@deepseek-ai/cordis（\>=4\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @civilization/dsh-git-workbench 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/civilization\_\_dsh-git-workbench 是否存在。

### @civilization/dsh-git-workbench 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @civilization/dsh-git-workbench 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @civilization/dsh-git-workbench 可以商用吗？

@civilization/dsh-git-workbench 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @civilization/dsh-git-workbench 的下载量有多少？

根据 npm 官方下载统计，@civilization/dsh-git-workbench 在 2026/10/10 – 2026/11/08 这 30 天内被下载 1,751 次，日均约 58 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @civilization/dsh-git-workbench 还在维护吗？

最新版本 0\.4\.8 发布于 2026/10/26（14 天前）；至今共发布 10 个版本，其中过去 12 个月发布了 10 个；首次发布于 2026/10/22。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。