dsh-gitland

Readme

# dsh-gitland

DeepSeek Harness（DSH）的 Git 面板插件：在 Web GUI 中呈现 GoLand 风格的 Git 工具窗口 ——
提交日志时间线（彩色泳道图）、分支管理、worktree 管理，以及工作区状态摘要，并支持简单的
分支/worktree 操作。

## 功能

- **入口**：侧边栏底部、`设置` 上方两个**纯图标按钮**（悬停显示名称）：上方 commit
  按钮（打开提交弹窗，有待提交改动时显示计数角标）与下方 Git 按钮（打开底部停靠面板，
  GoLand 工具窗口风格，可 Esc 关闭、点击遮罩关闭）。
- **提交弹窗**（commit 按钮）：列出本次改动的文件清单（默认全选，可勾选排除；
  `--untracked-files=all` 展开未跟踪目录），每文件可展开 diff 预览；「✨ AI 生成」由
  **宿主直连一次模型调用**按选中文件的 diff 起草 Conventional Commits 提交信息（无
  Agent 循环、零工具轮次、自动选最低推理档位），结果**自动回填**输入框；底部按钮
  **commit / commit and push**。提交按精确路径执行（`git add` + `git commit --only`）：
  未勾选的其他已暂存文件**不会**被夹带进本次提交；推送失败时提交保留并如实提示。
- **自动刷新**：面板打开期间每 15 秒轮询（状态/同步/当前页数据），窗口聚焦与页面
  可见时立即刷新；操作进行中跳过，提交弹窗打开时暂停。手动刷新按钮保留。
- **Pull 按钮**：始终可点（仅操作进行中禁用）——up-to-date 的 pull 是无害 no-op 且
  顺带刷新跟踪事实；不再依赖「远端是否有新提交」的智能判断（该判断会因陈旧数据误禁用）。
- **仓库选择**：自动发现在 DSH 中注册过的工作区里的 Git 仓库（以工作区为安全边界，面板
  只能访问已注册工作区内的仓库），顶部下拉切换。
- **面板整体高度可调**：面板顶边为拖拽条（row-resize 双向箭头，拖动跟随指针，双击复位，
  200px～86% 视口高）；三栏宽度、详情栏内部上下分栏同样可拖。
- **日志与分支页**（GoLand 三栏布局，同一页内左右并排）：
  - **左栏·分支树**：顶层为可折叠的 **Local / Remote / Tags 根节点**（文件夹图标），其下
    是 feature、hotfix 等命名空间文件夹（文件夹图标+计数），再下是具体分支（**分支图
    标 + 纯文字名**，无圆框）；**当前分支**为金色标签图标 + 加粗品牌色名；**单击仅选中
    行，双击才在右栏打开其 tip 提交**；顶部搜索框按名称模糊过滤；工具栏上下双 V 图标
    一键折叠/展开全部；悬停浮出紧凑图标按钮（检出/删除）。栏宽下限按最长分支名实测，
    名称永不省略。
  - **中栏·提交日志**：彩色泳道提交图、徽章、作者/日期/哈希列，「加载更多」；工具条
    **单行**排布：搜索框 + **Branch / User 下拉 + Date 下拉（最近24小时 / 最近7天 / 按
    时间范围——选范围时展开起止日期行）**，可叠加过滤。
  - **右栏·提交详情**：点击日志行（或双击分支行）显示更改文件；目录树默认（眼睛图标切
    换）；**每个文件前有按扩展名着色的文件图标，文件名颜色表示改动类型**（绿=新增、蓝=
    修改、红=删除、紫=重命名，JetBrains 色板）；文件**单击仅选中，双击才展开 diff**。
    未选中提交时右栏收起。
- **主题适配**：深色模式下主文字调暗柔和（近白 → 混灰），当前分支徽章使用 inverted
  标签色，浅/深两套主题下均保持可读。
- **工作树页**：列出主工作树与全部 linked worktree（分支、HEAD、locked/prunable 状态）；
  支持添加 worktree（新建分支或检出已有分支）、移除 worktree、清理元数据。
- **状态条**：当前分支、领先/落后上游计数、暂存/未暂存/未跟踪计数徽章。
- **工作流 Skills**：源自 w-coding-plugins `git-workflow` 插件的命令适配（见下节），在输入框
  输入 `/` 即可调用。

## 工作流 Skills（git-workflow 适配）

把 Claude Code 格式的 git-workflow 插件（commands + skills）适配为 DSH 的 user-invocable
skill：宿主端启动时解析 `skills/<name>/SKILL.md` 并注册到 `ctx.skills`（runtime 来源）。
Web GUI 中输入 `/git-commit ...` 发送后，host 在 pre-step 边界注入完整 skill 正文，模型按
正文执行——与 Claude 斜杠命令展开为提示词的语义一致。

| Skill | 来源命令 | `/` 菜单 | 说明 |
|-------|---------|----------|------|
| `git-commit` | `/commit` | ✅ | Conventional Commits 提交，可选推送 |
| `git-branch` | `/branch` | ✅ | Git Flow 分支创建 / 删除（仅本地） |
| `git-worktree` | `/worktree` | ✅ | worktree 创建 / 删除 / 批量清理 |
| `git-rules` | `skills/git-rules.md` | ❌ | 规范参考（仅模型调用；被上面三个命令引用加载） |

适配要点：交互确认从 `AskUserQuestion` 改为 `ask_user_question`；命令正文显式引导先加载
`git-rules`（DSH 会话目录只含名称+描述，不自动注入正文）；bash 专属语法（如
`basename $(...)`）改写为平台无关描述；`/git-workflow:xxx` 引用改为 `/git-xxx`。
源插件的 `/changelog` 与 `/help` 未纳入（changelog 交给专业工程化工具）。

用法示例：

```text
/git-commit --push --style=full
/git-commit --issue=#123
/git-branch create feature/user-auth
/git-branch delete feature/old-feature
/git-worktree create feature/payment
/git-worktree clean --dry-run
```

skill 文件是**双用格式**：除由本插件运行时注册外，也可直接把 `skills/<name>/` 目录复制到
任意项目的 `.dsh/skills/`（或用户 skill 根目录），由 DSH 内置的 filesystem provider 以相同
frontmatter 加载。项目层同名 skill 优先级高于本插件的 runtime 注册，可按项目覆盖。

## 安全模型

- 宿主端只在 `ctx.workspaceRegistry` 解析出的注册工作区目录内执行 git（argv 数组、无 shell）。
- 每个请求过与 DSH `/api` 相同的浏览器信任围栏：Host 必须是环回或部署声明的受信主机，
  显式跨站标记拒绝、Origin 必须同源。这不是认证层（与 `/api` 同一模型）。
- worktree 目标路径必须位于仓库外，且不得包含仓库；分支名经 `git check-ref-format --branch`
  校验（拒绝 `--upload-pack=evil` 之类的注入形状）。

## 依赖与构建

本仓库在离线环境开发：`node_modules` 通过 junction 指向本机的 deepseek-harness 检出
（见 `scripts/link-deps.ps1`，默认指向
`F:\Project\code repository\Others\deepseek-harness`）。

```powershell
cd dsh-gitland
powershell -ExecutionPolicy Bypass -File scripts\link-deps.ps1   # 首次
node node_modules\tsdown\dist\run.mjs                            # 构建 lib/index.js + lib/client.js
node node_modules\typescript\lib\tsc.js --noEmit                 # 类型检查
```

## 安装进 dsh web profile

已提供幂等安装脚本（把包 junction 进 profile 的 node_modules，并登记 bundle 层）：

```powershell
powershell -ExecutionPolicy Bypass -File scripts\install.ps1
```

之后正常启动 `dsh web` 即可；卸载用 `scripts\uninstall.ps1`。

## 验证

- `scripts/smoke-fixture.ps1` + `scripts/smoke.ts`：对真实 git 仓库输出做解析器断言
  （status/log/branches/worktrees/泳道图/CJK 文件名——夹具经 cmd 原始字节重定向生成，
  免受控制台代码页干扰）。
- `scripts/commit-it.ts`：对真实临时仓库验证提交弹窗后端方法（`repo.changes` 的逐文件
  diff 与 untracked 展开/截断、`repo.commit` 的精确路径提交不夹带其他已暂存文件、
  `repo.draft` 用假 llm 验证提示组装/围栏剥离/最低推理档位/失败面）。
- `scripts/mutation-test.ps1`：对一个运行中的服务器（默认 `http://127.0.0.1:3090`）做全量
  变更操作测试（建分支/检出/删除/worktree 增删/恶意输入拒绝）。
- `scripts/client-it.ts`：在模拟的模块加载器里执行构建产物，断言双插槽注册、共享
  controller、字典与样式挂载。
- `scripts/skills-check.ts`：静态校验工作流 skill 包（名称、frontmatter、调用策略、
  描述预算、交叉引用、恶意 frontmatter 拒绝）。
- `scripts/skills-it.ts`：加载构建产物 `lib/index.js`，用最小 fake cordis 上下文断言
  四个 skill 的运行时注册（来源、调用策略、resourceBase）。

## 结构

```
dsh-gitland/
├── src/
│   ├── index.ts        宿主端：/git 路由（信任围栏 + workspaceRegistry 边界 + 错误映射）
│   │                   + skills 服务注入（工作流 skill 注册）
│   ├── api.ts          方法实现与 git 输出解析器
│   ├── git.ts          git 子进程层（argv、超时、结构化失败）
│   ├── trust.ts        浏览器信任围栏（镜像 /api 的模型）
│   ├── model.ts        线上模型（宿主/浏览器共享类型）
│   ├── skills.ts       工作流 skill 加载器（frontmatter 解析 + ctx.skills 注册）
│   └── client/
│       ├── index.ts    浏览器端 apply：字典、样式、两个插槽贡献
│       ├── store.ts    PanelController（快照源 + 异步操作 + 提交详情状态）
│       ├── api.ts      fetch 客户端
│       ├── gitgraph.ts 泳道图布局算法
│       ├── GitOverlay.tsx / LogView.tsx / BranchView.tsx / WorktreeView.tsx
│       ├── CommitDetails.tsx  提交详情栏（更改文件：平铺/目录树切换 + diff/提交信息区）
│       ├── filetree.ts  更改文件的目录树构建
│       ├── GitSidebarAction.tsx  侧边栏入口按钮（Git 面板 + 提交弹窗两个纯图标按钮）
│       ├── locales.ts  zh/en 文案
│       └── styles.ts   注入式样式（--dsw-* 语义 token）
├── skills/             工作流 skill（git-commit / git-branch / git-worktree / git-rules）
└── cordis.patch.yml    bundle 层补丁（git-panel 行）
```

## 方法列表（POST /git/&lt;method&gt;）

`repos`、`status`、`log`、`branches`、`worktrees`、`commit.files`、`commit.patch`、
`branch.create`、`branch.switch`、`branch.delete`、`worktree.add`、`worktree.remove`、
`worktree.prune`、`repo.changes`、`repo.commit`、`repo.draft`；统一 `{ok:true,value}` / `{ok:false,error:{code,message}}` 信封。
`commit.files` 的哈希参数严格校验为 4–40 位十六进制（提交号），重命名文件的
`commit.patch` 需同时携带 `path`（新路径）与 `origPath`（旧路径）以配对 diff。
`repo.changes` 以 `--untracked-files=all` 展开未跟踪目录并附带每文件截断 diff
（16 KB，untracked 经 `diff --no-index`，exit 1 视为有差异的正常产出）；
`repo.commit` 携带精确文件列表（`git add` + `git commit --only`）；
`repo.draft` 携带选中文件列表，经宿主 `llm` 服务一次直连模型调用起草提交信息
（默认模型路由 + 最低推理档位，`maxTokens` 512，diff 总预算 48 KB）。