Repository navigation
Issue 7
- 类型：新功能。
- 状态：产品实现已通过 PR #180 合并到 development；本机 / SSH / Worktree 真实 PTY 与三平台原生包专项 CI 通过，剩余现场验收见下方记录。
- Issue：https://github.com/ShaoClean/Alune/issues/7
- PR：https://github.com/ShaoClean/Alune/pull/180（已合并；合并提交
c322bbbb062493267fe23bfd207dbf38adf2f78f，尚未发布）。 - 实现验收：Issue-7-Validation。历史 UI 原型与下方设计稿仍为模拟数据，不代表产品验收。
- 最近更新：2026-10-02。
- 代码基线：
v0.6.1 / development@ebe8b15。本次核对时 Release tag 与 development 指向同一提交。 - 规范：Alune UI 规范、弹窗系统、共享 UI 组件。规范中的历史实现差异不作为当前发布状态。
下载独立 HTML 交互稿（下载后用浏览器打开；字体、图标、样式和脚本已内嵌，无需安装依赖）。顶部“场景”可切换运行中、连接中、断开、退出、失败、空会话、未选仓库、切换中、数量上限和长路径，主题按钮切换深浅色。
所有终端输出、测试结果、主机、路径和会话均为示例。 HTML 不连接服务器、不运行 shell、不执行 Git、不访问真实仓库。现有 Git 控件作为背景展示，终端和仓库切换是本次可交互范围。设计稿不是已发布功能截图。
保留 48px 仓库标签栏、仓库工具栏、左侧导航、右侧改动与提交区、32px 状态栏。终端只占中间内容区下方，不挤压提交表单的高度。默认 340px，可拖动或键盘调整；最小 220px，最大为中间内容高度减去 150px。最大化只占中间内容区，保留两侧与仓库上下文。全屏 Diff 时暂时隐藏终端，退出后恢复面板尺寸和会话。
工作区外围和终端使用 Moonlight token；背景中的 Diff 使用应用既有 Catppuccin Mocha 默认。终端主题与代码语法主题分别处理，不能将 VS Code 的语法 token 当成完整 ANSI 终端调色板。
本机与 SSH 入口一致；会话展示真实运行环境。关联 Worktree 使用独立 repositoryId 和实际路径，不能退回主工作区。小于 900px 时沿用工作区折叠两侧面板的方向，优先保留仓库标签、终端入口、会话身份与当前内容。原型中的 Git 面板切换仅作背景；产品仍须保留原有抽屉入口。
断线后停止输入、保留断线前输出，明确远端进程状态未知。“新建会话”建立新的 sessionId，不显示“恢复原终端”，不重放输入。启动目录不存在或无权限时不打开备用目录。退出保留退出码和输出；非零退出需与正常退出区别显示。
连接中只显示真实状态，不造进度百分比，并提供取消；取消必须销毁正在创建的会话，不能在取消后悄悄出现 shell。无仓库、工作区切换中禁用新建并就地说明原因。Git 状态刷新中不等于仓库身份未知，不应阻止终端创建。
运行中或进程状态未知时，关闭是 L2：默认焦点“取消”，勾选后才启用“关闭会话”，Enter 不执行确认，Escape 取消。说明会话不可恢复、文件改动不回滚、远端脱离会话的进程可能继续运行；不能承诺清理所有远端子进程。已退出、创建失败或传输已销毁的断线记录可直接关闭。小于等于 560px 的确认框使用底部面板、纵向 44px 操作按钮。
| 旧 Issue 描述 | 2026-10-02 核对结果 |
|---|---|
| 发布版 v0.3.2，开发分支 c4a2f13，主题尚未发布 | 最新公开稳定版是 v0.6.1，tag 和 development 均为 ebe8b15；浅深主题、共享 UI 和减少动态效果均已在代码基线中。 |
| 产品通过 SSH 管理仓库，本机仓库 #82 尚未交付 |
#82 已于 2026-09-27 关闭；当前 Repository 已支持 source: local | ssh，本地 Git 操作和 Worktree 已存在。 |
| 面板位置与本机是否纳入仍未设计 | 本稿选择中间内容区底部；本机与 SSH 使用统一设计，首版目标同时覆盖，平台 PTY 依赖仍需 PoC。 |
| execCommandStream 的 cwd 直接拼接需要审查 | 当前代码已使用 quotePosixArgument(cwd)；仍是命令执行通道，不是交互式 PTY，也不能直接复用为 shell 会话。 |
| 尚无交互终端、PTY 会话与入口 | 本次在发布提交中仍未找到终端模块、xterm、node-pty 或 SSH PTY shell / resize 封装；此项仍待开发。 |
基线来自远端 Release、tag、development 和提交内容的核对；设计背景由该提交的隔离生产构建及仓库内 HTTP fixture 取得，未将主工作区的未提交改动计入已发布状态。原始基线截图。
在所选仓库的运行环境中，以登记目录为初始 cwd 创建可交互 PTY。首版设计覆盖本机、SSH 和关联 Worktree、多会话、复制粘贴、中断、resize、退出、明确失败及资源释放。会话生命周期不依赖仓库页面挂载。
图标与字体许可随附件保留。
首版不包含跨应用重启恢复、tmux/screen 托管、终端拆分网格、自定义 shell profile 管理、终端插件/主题市场、AI 自动执行命令。#8 的 AI CLI 能否复用基础传输单独设计，不把用户终端自动交给 AI。
“本机”指运行 Alune 服务进程的主机；桌面版通常就是当前电脑。网页访问异机部署的服务时，不能把服务端 shell 标成“此浏览器所在电脑”。部署版在明确权限和服务主机展示前不得默认开放本机任意 shell。
| 部位 | 本稿决定 |
|---|---|
| 仓库工具栏“终端” | 显示/收起面板；有会话时恢复该仓库最后所选会话，首次打开呈现空态，不自动运行命令。 |
| “新建终端” | 在当前明确的仓库环境与登记路径创建。连接过程禁用该创建请求，防重复；同仓库允许再次显式新建。 |
| 会话 Tabs | 当前仓库分组，bash 01 / zsh 01；关闭按钮单独聚焦，不与选择动作混用。退出/断开用文字标记；数量超宽时局部滚动。 |
| 身份条 | 始终显示本机或 SSH 连接名、仓库、运行状态；与用户 shell 提示符相互独立，不信任提示符作为身份来源。 |
| 启动目录 | 用等宽字体显示 initialPath；长路径省略，悬停可读、按钮复制全文。明确叫“启动目录”，用户 cd 后不假装它是实时 cwd。 |
| 全部会话 | 面板列表按钮、底栏“终端 N”均可访问；按运行环境和仓库标识，选择后进入对应仓库及其会话。 |
| 切换仓库 | 切换可见会话与身份条，保存各仓库最后选择；旧会话继续在原主机运行，不改 cwd、不重新创建进程。 |
| 收起与最大化 | 仅改变布局；不发送 exit / kill，不销毁缓存。最大化后可还原；不与系统窗口全屏混用。 |
| 关闭仓库标签 | 只关闭仓库视图，所属会话保留；通过全部会话重新打开。 |
| 删除登记/连接、关闭窗口/退出应用 | 汇总受影响的活动会话，L2 确认后关闭归属会话；取消则保持原状态。退出后的输出与进程不承诺恢复。 |
| 主题与反馈 | 主题切换保持会话、输入、滚动与尺寸；创建、切换、收起成功直接从界面体现，不新增常规成功弹窗；失败就地显示。 |
继承 tokens.css：常驻面使用 surface，输出区使用 code，分隔线 line，状态采用 green/orange/red/cyan 配文字。工作区不增加光晕、渐变背景或多层卡片。
- 标题/操作 13px；路径、输出等宽约 12.5px/20px；辅助状态 11–12px。终端字体接入时须考虑用户已配置的代码字体和字号；ANSI 调色板需单独完成可读性验证。
- 标题栏 42px，会话栏 38px；紧凑控件高 30px、图标操作 30×30px；间距使用 4/8/12/16px。
- <=560px 的终端操作命中区 44px；会话标签可横向滚动，代码滚动限制在内容区，页面没有整体横向溢出。
- 新基础控件复用
@alune/uiButton、Tooltip、StatusBadge、AluneModal/确认 hook；图标延续 Ant Design。HTML 演示借用真实组件的渲染结果与样式，生产接入不能照搬静态 DOM。 - 焦点环 2px blue + 2px offset；减少动态效果下立即切换，不对终端输出逐行做动画。状态提示使用克制的 live region，不逐行播报输出。
Ctrl+反引号 显示/收起终端，显式打开后进入输入区，收起后回到入口。会话 Tabs 支持左右/Home/End；分隔线支持上下键，Shift 加速，Home/End 到边界。使用 xterm 的键盘和屏幕阅读能力，中文输入不被应用全局快捷键截断；Ctrl+C 始终按终端中断处理。macOS 使用 Cmd+C/V 复制粘贴；Windows/Linux 的 Ctrl+Shift+C/V 与多行粘贴确认需在真实桌面 PoC 核验。需要将 Tab 传给 shell，同时提供可发现的离开终端焦点方式，避免键盘陷阱。
| 状态 | 用户看到的内容 | 输入与可用动作 |
|---|---|---|
| 空会话 | 仓库环境、启动路径、“此仓库还没有终端” | 新建；未选仓库时解释原因 |
| 创建/连接中 | 正在连接主机，或正在启动本机 shell | 禁止输入；取消当前创建 |
| 运行中 | 来源、路径、输出、光标 | 输入、复制粘贴、resize、中断、收起、关闭；该状态表示通道可交互，不表示 shell 空闲 |
| 已断开 | 橙色提示、保留历史、远端进程状态未知 | 禁止输入；显式新建、复制输出、关闭记录 |
| 已退出 | 退出码/信号与历史；非零结果单独提示 | 新建、复制输出、关闭记录 |
| 创建失败 | 主机/目录/权限等具体错误，不回退 cwd | 重新检查并新建、复制诊断、关闭记录 |
会话在创建时冻结 sessionId + ownerWindow/client + repositoryId + source + connectionId? + initialPath。路径与连接由服务端从 repositoryId 解析，客户端不可指定任意命令或越权主机。来源相同、仓库名相同或分支相同均不能合并 session。每个窗口只可输入、resize、接收和销毁自己的会话。
建议初始上限为每窗口 8 个会话、每会话 10,000 行且 2 MiB 的可见历史，两者先到先裁剪，并明确“较早输出已截断”。值属于方案参数，须通过高吞吐 PoC 验证后落地。传输另设有界字节队列与背压，不能只限制前端滚动历史。超限禁止继续创建并保留现有会话；不能无提示丢弃未送达字节。PTY 隐藏期间继续受控接收输出，不逐帧触发 Git 全量刷新。
Socket 临时断开后，首版不承诺恢复原 PTY；销毁该传输和本地资源，停止接收旧输入，保留客户端已有输出。SSH 池的自动重连不能将旧 channel 标为恢复。对远端进程只报告已知事实，主动关闭 channel 不等于杀死所有后代进程。
当前实现与实际验证见 验收记录；本节保留实现前的候选落点。
| 层 | 接入方向与当前差异 |
|---|---|
| 前端 | 评估 @xterm/xterm + fit 插件；仓库级终端 store 保存会话视图，Shell/Layout 常驻管理面板。React 页面卸载不能销毁正在运行的会话。 |
| 会话服务 | 独立 TerminalModule / TerminalService；创建、输入、resize、退出、取消、销毁均检查所有者和状态；终端命名空间或 rooms 单播，不复用全局 command 广播。 |
| SSH | 基于 ssh2 的 PTY shell/channel 增加尺寸、信号和销毁封装；启动前验证 cwd 和 shell，确保路径按数据引用。已有 execCommandStream 不能代替 PTY。 |
| 本机 | 评估 node-pty/ConPTY；以 cwd 参数启动本机 shell，处理 Electron ABI/native rebuild、平台分发与进程树清理。现有 LocalConnection 仅执行 Git，不是通用 shell 入口。 |
| 安全与身份 | 复用桌面本地服务的访问边界并增加 socket 握手身份校验、窗口所有权、会话路由；远程部署不得仅因 cors 配置宽松就开放 shell。 |
| 文件状态同步 | 终端执行外部命令后通过已有刷新/受控文件观察更新 Git 状态，不通过猜测输入中的 git 命令来判断结果，也不让每行输出触发刷新。 |
源码永久链接：
- Repository 来源、路径与 Worktree 类型
- SSH 命令与通道封装
- 本地 Git transport
- EventsGateway 全局广播
- ConnectionService 连接池
- 工作区布局与仓库标签
- 仓库登记与路径解析
已完成的自动验证、支持矩阵与未验证项见 验收记录。以下完整现场清单不因部分测试通过而整项勾选。
- 本机仓库、两个不同 SSH 连接分别新建终端，以 hostname/用户名及 pwd 确认环境和 cwd；Web 服务主机文案无歧义。
- 同仓库多开、不同仓库、同名仓库、主/关联 Worktree、同分支不同路径保持 session 和输出隔离；切换标签不迁移进程。
- 输入、中文 IME、持续/大量输出、颜色、复制粘贴、Ctrl+C、交互式 TUI、resize、退出码和再次新建正常。
- 无仓库、切换中、无效目录、权限不足、SSH 失败和 shell 不存在均有匹配反馈；Git 刷新不额外阻断；无隐式 cwd 回退。
- 空格、中文、引号、换行及 shell 特殊字符路径安全定位；旧会话不能越权或接收其他窗口输入。
- 关闭/取消与创建竞态不泄漏；关闭一个 channel 不断其他终端或 Git；断线不重放输入、不虚假恢复；退出与删除清理全部归属资源。
- 8 会话、历史上限、传输背压、隐藏面板和输出截断提示通过压力测试；不因输出刷新抖动或卡死。
- 深浅主题、用户代码字体/字号、44px 窄屏目标、200% 缩放、减少动态效果、完整键盘与焦点恢复通过实际产品验收。
- macOS、Windows、Linux 真实桌面包测试；记录 OS/架构、shell、PTY/ConPTY、远端系统与依赖版本。不能只以网页原型通过代替。
环境：macOS 上的 Codex 内置 Chromium 浏览器；日期 2026-10-02。HTML 模拟交互，基线构建来自 ebe8b15。
- 基线隔离构建通过 Vite production build；只有既有大 bundle 提示。静态核对 Release、tag、development、本地 Git transport、PTY 缺口与广播方式。
- 已检查浅色/深色、1440/1024/768/560/390/320 CSS px 布局；各宽度页面无整体横向溢出。代码和会话列表允许局部滚动。
- 已检查本机/SSH/Worktree 切换、新建、断线后新建、模拟 pwd、会话切换、关闭确认取消、收起/恢复、最大化/还原、分隔线键盘调整。运行中关闭默认焦点取消，确认初始禁用。
- 设计验证发现并修正深色 Diff 主题、窄屏栅格列、画板顶部被滚动隐藏、异常提示被输出挤出可见区的问题。
- 已将相同 1440×900 应用画布并排核对：基线与设计对照。左/右分区与控件密度继承基线，新增终端只缩短中间内容区；仓库标签在演示中替换为三个可切换示例。
- 主体截图使用 1440×956，其中顶部 56px 是设计工具栏，应用画布为 1440×900；768px 稿使用 768×956；390px 稿使用 390×844。不把原型外部“场景”工具栏当成产品功能。
- 设计稿的关键文字色对比度测量与附件校验见 附件清单。仅声明所列颜色组合，未进行全产品无障碍认证。
- 未验证：真实 PTY/SSH、跨平台 shell/原生打包、屏幕阅读器、系统级 200% 缩放、真实高吞吐与进程清理。减少动态效果已写入设计 CSS，系统开关实测留待实现验收。示例中的“7 passed”只是终端假数据，不是测试结果。
当前参数已在代码中落定，三平台专项 CI 已通过；具体 shell 范围和仍待现场检查的项目以 验收记录 为准。代码回退应撤回 PR #180 的实现，Wiki 修改则单独回退。
产品方向、面板位置和 UI 状态已有本稿；macOS/zsh、Linux/bash、Windows/PowerShell 与 ConPTY 的实际支持矩阵需要 PoC 决定。POSIX 远端为首轮验证对象，Windows SSH shell 的 cwd 与信号语义单列验证；失败时明确告知不支持，不回退错误环境。会话/缓存上限、背压阈值仍是待验证参数。任何缩减首版平台支持的决定均须回写本页和 Issue。
本次只有 Wiki 与 Issue 文档更新。回退使用 Wiki 独立提交的 revert 和 Issue 编辑历史，不涉及主仓库应用代码或用户当前未提交工作。
关联：已交付的本地仓库 #82、Worktree #29、工作区布局 #6、状态栏导航 #73、主题 #86、共享 UI #153；AI CLI #8 独立跟踪。