Repository navigation
Issue 82
- 类型：功能
- 状态：UI 设计稿与产品实现已完成；三平台 CI 通过，待合并
- Issue：https://github.com/ShaoClean/Alune/issues/82
- PR：#106
- 最近更新：2026-09-26
- 代码基线：
development@f6ce4aca3d82a5a4133f5d6d5326531baa0cfca6（v0.3.4） - 交付：12 个关键场景的可点击原型、浅深主题截图、本地 Git 实现、自动化与桌面验收记录
下列截图为 UI 设计稿。原型使用演示数据，仅在页面内模拟操作，不执行 Git，不读取实际文件，不用于证明真实 Git 行为。正式实现截图及真实仓库结果见文末与验收页。
变更前 Repository 必须绑定 connectionId，GitService 经由 ensureConnected 执行远端 Git；首次使用也从 SSH 连接开始。本地仓库无法独立登记或完成提交。目标是允许用户直接打开本机已有 Git 仓库，同时复用现有 Diff、暂存、提交、历史、多标签和可选 AI 提交交互。
设计以当前工作区为基础：左侧仓库导航、中央 Diff、右侧文件与提交区，上方标签和仓库工具栏、底部路径状态栏。沿用 theme.css 的月光浅深主题、系统字体和 Ant Design 图标，不再引入第二套视觉系统。
下载可离线打开的交互原型。下载 HTML 后在浏览器打开；无依赖、无网络请求，重新加载恢复演示数据。顶部“查看场景”跳转到以下 12 个状态，右侧可切换浅深主题。
| 编号 | 场景 | 主要交互 |
|---|---|---|
| 01 | 本地工作区 | 来源标识、Diff、暂存、提交、多标签、分支和同步 |
| 02 | 仓库总览 | 本机 / SSH 筛选、名称 / 路径 / 分支搜索、排序、打开 |
| 03 | 打开本地仓库 | 系统目录选择、手输路径、检测结果、重复仓库定位 |
| 04 | 首次提交 / 无远程 | 无 HEAD 提交、无远程说明、同步按钮禁用原因 |
| 05 | 设置上游并推送 | 选择远程与分支，设置上游后发起首次推送 |
| 06 | Worktree 管理 | 新建、独立标签打开、当前目录不可删除、删除确认 |
| 07 | 丢弃改动确认 | 来源与路径、影响范围、不可撤销说明、显式勾选 |
| 08 | 同步错误 | 拒绝原因、本地提交保留、错误详情、下一步 |
| 09 | 浅克隆历史 | 历史边界说明、获取完整历史入口 |
| 10 | Git 作者配置 | 姓名邮箱、仅当前仓库范围、提交身份说明 |
| 11 | 首次打开 | 打开本地仓库和连接 SSH 两个入口 |
| 12 | 路径 / 权限错误 | 就地错误、保留输入、重新选择、禁止继续 |
侧栏将仓库分为“本机”和“SSH 远程”；远程区继续按连接分组。顶部同名仓库分别标记“本机”和“SSH”。底栏持续显示完整路径与执行位置；危险操作弹窗重复显示目标来源与路径。
来源标签不用颜色单独表达，始终有图标和文字。不要把本地仓库伪装成名为 localhost 的 SSH 连接，也不要让本地操作等待 SSH 状态。
未暂存和已暂存分别展示；提交按钮仅在“存在已暂存文件 + 摘要非空”时可用。同一文件的暂存区版本与之后的工作区改动应分别展示。原型为易读演示只展示简化文件状态，正式实现继续使用现有 FileStatus 和 Diff 语义。
可选 AI 提交入口继续保留；显式发起才会发送已暂存差异，生成结果可编辑且不会自动提交。来源切换不改变 AI 设置的凭据边界。
仓库总览以一组可扫描的行展示名称、路径、来源、分支和状态，避免同名仓库只能依靠卡片位置识别。支持按名称、路径、分支搜索，“全部 / 本机 / SSH 远程”筛选，以及最近打开、名称排序。原有侧栏拖动排序和标签排序保留。
- “打开本地仓库…”进入本地来源；通用“打开仓库”默认本机，并可切换 SSH。
- 桌面使用系统目录选择器；同时允许粘贴绝对路径。取消系统选择器不产生错误、不改动现有标签。
- 规范化路径，识别 Git 根目录、分支、Worktree、作者和状态。选择仓库子目录时明确显示最终根目录。
- 检测过程中显示加载状态且禁止重复打开；检测失败保留输入和详细原因。
- 成功后登记并打开标签。已经登记 / 打开的同一来源与规范路径应直接聚焦，避免重复。
- 打开不会 clone、init、暂存或修改用户文件。非 Git 目录提供重新选择，不自动初始化。
- 打开 → 查看改动 → 暂存 → 填写摘要 / 可选描述 → 提交，提交完成后刷新状态、分支前后计数与历史。
- 保留每个仓库的提交草稿、文件选择和面板布局；同名本地 / SSH 仓库不能串用草稿。
- 无 HEAD 仓库显示“准备好你的第一次提交”；取消暂存使用适用于无 HEAD 的操作；历史显示明确空状态。首次提交前禁止没有意义的同步。
- 缺少作者时保留草稿和暂存内容，引导只为当前仓库配置。全局配置变更不作为默认。
- 新建分支可选创建后切换；验证 Git ref 名称，拒绝重复、无效和被其他 Worktree 占用的分支。
- 切换冲突时保留现场，提供提交 / 储藏路径。原型以保守场景演示“有改动则提示”，正式实现以 Git 是否会覆盖文件为准，允许安全携带改动。
- 删除当前分支或被 Worktree 占用的分支禁用。删除其他分支先执行安全删除；未合并时明确拒绝，不静默升级为强制删除。
- 合并发生冲突时显示冲突文件与 Git 输出，允许用户在编辑器处理后刷新；不把 exit code 非零报告为合并成功。
- 历史复用现有分支图、分页、合并提交与初始提交 Diff。原型历史列表用于展示浅克隆说明，不替代现有分支图组件。
- 无远程：本地提交可用；提示“需要同步时再添加远程”，同步按钮带禁用原因。
- 有远程、无上游：主操作为“发布分支”，先显示远程地址及分支，确认设置上游后推送。
- Fetch / Pull / Push 显示运行状态、操作仓库、目标和可取消入口。操作进度没有准确百分比时使用不定进度，不编造百分比。
- 同一仓库的写操作串行；切换标签后操作归属不变，允许查看其他仓库。
- 取消表示停止后续执行，不能承诺远端已完成步骤回滚。结束后重新读取真实仓库状态。
- 错误保留原始 Git 详情，并提供面向用户的解释。非快进拒绝引导先获取 / 拉取；认证失败说明使用本机还是远端凭据，提示检查 Agent / 凭据助手；网络超时可重试。
- 强制推送从独立入口发起，显示目标分支、覆盖风险和显式确认，使用
--force-with-lease。 - 浅克隆明确标记历史不完整；获取完整历史作为显式网络操作，不在打开时自动下载。
Stash 支持创建、查看、应用、应用并移除、删除；创建时明确是否包含未跟踪文件。应用冲突时保留原储藏及冲突状态，不静默删除。删除另行确认。原型演示创建 / 查看 / 应用 / 删除；正式实现保留现有弹出操作。
| 操作 | 标签与登记 | 磁盘内容 | 确认 |
|---|---|---|---|
| 关闭标签 | 关闭标签，保留仓库登记 | 全部保留 | 不需要破坏性确认 |
| 从列表移除 | 移除登记并关闭对应标签 | 目录、历史、改动保留 | 说明范围并确认 |
| 删除 Worktree | 移除关联 Worktree 登记和标签 | 删除指定目录；保留分支与提交 | 显示完整路径，显式确认 |
创建 Worktree 选择新目录及分支，校验目录非当前仓库、目标为空、分支未被占用。当前、锁定或有未提交改动的 Worktree 禁止直接删除；首期不提供跳过这些限制的强制删除。
丢弃已跟踪文件的工作区改动与删除整个新增文件采用不同文案。前者恢复为暂存区版本，不清除已暂存内容；后者必须明确磁盘文件将被删除。确认后重新验证文件身份、状态与范围，防止确认期间文件发生变化。
Git 未安装、目录不存在、无权限、非 Git 仓库、不受信任的仓库所有权、只读磁盘分别给出说明。不要自动添加 safe.directory=*、提权、修改系统权限或覆盖凭据。长路径与中文 / 空格 / 引号按字面值传给 Git；避免拼接 shell 执行。
“首期”是 #82 最小可发布范围。表中阶段为实施顺序，不代表仅交付阶段 1 就能关闭 Issue。
| 阶段 | 交付范围 | 出口条件 |
|---|---|---|
| 0 · 设计 | 本文、UI 原型、关键状态和验收矩阵 | 可审阅，区分原型与产品功能 |
| 1 · 本地基础闭环 | 目录选择、路径检测、来源模型、列表 / 标签、状态、文本 / 图片 / 二进制 Diff、暂存 / 取消暂存、提交与历史 | 隔离真实仓库完成首次提交和已有仓库提交，SSH 回归通过 |
| 2 · 日常 Git | 分支创建 / 切换 / 重命名 / 删除 / 合并，Fetch / Pull / Push / 上游，Stash，Worktree | 完成打开到同步闭环；无远程、浅克隆、冲突和目录边界覆盖 |
| 3 · 可靠性与交付 | 长操作 / 取消 / 错误、危险操作确认、持久化迁移、跨平台测试、文档和 PR | 全部验收项有可复验记录，明确真机未验证项 |
首期暂不提供：克隆 / 初始化向导、集成终端、凭据保险箱、可视化冲突编辑器、交互式 Rebase、自动修改系统 Git 信任策略、完整 LFS / 子模块管理、后台自动同步、强制删除脏 Worktree。已有 SSH 能力继续可用；这些范围不阻止本地仓库完成 Issue 的闭环。
- Repository 明确
source: local | ssh。本地记录不绑定 Connection；现有数据迁移为 ssh，不更改连接认证字段。目录标识按来源、连接和规范路径去重。 - 本地命令使用 Node 子进程直接传 argv，不启用 shell；SSH 保留现有传输和认证边界。复用状态、日志和 Diff 的解析器与返回结构。
- 本地路径由后端验证；渲染层通过窄 IPC 打开系统目录选择器，不能因此取得任意 shell 能力。
- 本地浏览仅处理登记工作区内的相对路径；符号链接、子模块和过大文件继续执行既有预览限制。Git 图像内容使用字节读取，不能经文本管道破坏。
- 长操作记录 ID、仓库 ID、类型、状态、输出与结束时间；取消信号传递到进程。结果刷新以真实 Git 状态为准。
- UI 复用现有 ChangesView、DiffViewer、HistoryWorkspace、BranchPicker、标签持久化和面板调整机制；原型只表达新信息架构，不要求重写这些成熟组件。
- 新来源不能改变 SSH 的数据边界；本地失败不触发远端重连，远端认证失败不阻塞本地列表和提交。
- 基础窗口：1280 × 720；另检查 1024 × 768 紧凑桌面布局。正式实现保留现有可隐藏与拖动调整面板。
- 基准左栏 236 px、右栏 320 px；中央 Diff 自适应。工具栏六个视图持续可达，小窗口缩为带可访问名称的图标，再按需横向滚动。
- 正文 13–14 px，帮助信息 11–12 px，代码 12–13 px；主要表单控件至少 30 px，主要按钮 32–36 px。
- 颜色来自当前月光 tokens：浅色主色
#415ab0，深色主色#afc6ff；增减色复用绿色 / 红色背景及符号，不只依赖色相。 - 弹窗有标题、焦点约束、Esc 取消和关闭后焦点恢复；破坏性动作初始不聚焦到确认按钮。所有图标操作有名称；清晰保留键盘焦点。
- 运行中、加载失败、空列表是不同状态；禁用控件用明确弱化外观和原因，不以“无结果”掩盖读取失败。
- 遵循系统和应用的减少动态效果设置，不以动画作为进度的唯一表达。
主体实现：69ce79e；最终验证提交：e4b4f23。本地仓库通过独立 transport 执行结构化 Git 参数；既有 SSH 仓库继续使用原连接与认证。共享解析器、Diff、历史、AI 暂存快照和工作区交互。
- 保留正式产品的文件类型图标、Diff 专注 / 全屏、可调整面板、AI 模型入口与历史分支图。设计稿中的简化 Diff 不替换这些能力。
- 本次仓库总览保留现有卡片，新增来源筛选、名称 / 路径排序、搜索和打开本地入口。列表 / 卡片切换由 #66 跟踪；不在本次重复重构。
- 新建分支直接切换；新建 Worktree 创建新分支并在独立标签打开。Git 原生保护未合并、占用和冲突分支。删除脏 Worktree 不提供强制绕过。
- 耗时写操作显示操作类型、耗时与取消入口；取消后刷新真实状态。首次推送的上游分支可与当前本地分支不同。强推使用租约保护。
- 目录选择器 IPC 已在 Electron 中验证选中与取消结果；系统对话框返回值由测试桩提供，尚不等于人工操作系统选择器验收。
- 明确首期范围、暂不支持范围和实施阶段。
- UI 设计稿覆盖本地 / SSH 来源、核心路径及主要边界，附可点击原型与截图。
- 本地仓库完成“打开 → 查看改动 → 暂存 → 提交 → 切换分支 → 同步远程”。
- 正式产品本地与 SSH 复用工作区、Diff、历史和提交交互；路径与来源持续可见。
- 支持多仓库 / 多标签、搜索、排序、快速切换及重启恢复。
- 新仓库无 HEAD、无远程、浅克隆、游离 HEAD 均有正确状态。
- 文本 / 图片 / 二进制、部分暂存、重命名、中文 / 特殊字符路径有测试。
- 分支、Stash 和本地 Worktree 的操作与保护规则通过真实仓库验证。
- 长操作显示状态、可取消、有清晰错误；危险操作需要确认。
- 持久化迁移兼容现有 SSH 记录，认证和路径边界不退化。
- macOS / Windows / Linux 自动化测试与验收记录完备；未验证真机项明确列出。
详见 UI 验证与产品验收计划。分别记录原型、真实 Git 自动化、桌面 UI 和平台边界；PR 合并前保留 Issue 的开放状态。
主要实现风险是跨平台 Git 进程取消、Windows 参数与路径、旧数据库迁移、无 HEAD 取消暂存，以及 Worktree 共享分支约束。按阶段保留回归证据；回退代码不能自动回退独立 Wiki 的变更。