223 lines
5.3 KiB
Markdown
223 lines
5.3 KiB
Markdown
# u-tabs 架构设计
|
||
|
||
> 最后更新：2026-05-15 | 基于 u-tabs v0.3.0
|
||
|
||
## 1. 项目概述
|
||
|
||
u-tabs 是一个 TUI 工作空间启动器，用 Bubble Tea v2 实现。管理多个工作空间（YAML 配置驱动），通过 Windows Terminal + Claude Code 标签页启动。
|
||
|
||
**技术栈**: Go 1.26 / BubbleTea v2 / LipGloss v2
|
||
|
||
## 2. 架构
|
||
|
||
```
|
||
main.go → Model (app.go)
|
||
├── 分组 Tab 栏
|
||
├── 左侧项目列表
|
||
├── 右侧详情面板
|
||
└── Enter → wt.exe → claude
|
||
```
|
||
|
||
## 3. 配置系统
|
||
|
||
### 3.1 加载优先级
|
||
|
||
```
|
||
~/.u-tabs/config.yaml → exe同目录/config.yaml → 内置默认值 (workspace.go)
|
||
```
|
||
|
||
### 3.2 YAML 结构
|
||
|
||
```yaml
|
||
groups:
|
||
- label: CORE # 分组标签，决定编号基数
|
||
desc: 核心业务
|
||
items:
|
||
- title: flux # 短名
|
||
prompt: 描述 # AI prompt
|
||
tech: 技术栈 # 精确到版本
|
||
deploy: 部署 # 服务器/端口/域名
|
||
dir: 目录路径 # 启动目录
|
||
```
|
||
|
||
### 3.3 编号规则
|
||
|
||
由 `GroupConfig.Base` 字段决定，若未设置默认从 0 开始。
|
||
|
||
### 3.4 数据转换
|
||
|
||
`Config.ToInternal()` 将 YAML 配置转为运行时结构，自动生成：
|
||
- `Index`: 全局索引 (0, 1, 2...)
|
||
- `N`: 编号 (base + item索引)
|
||
- `Group`: 继承父级 label
|
||
- `Dir`: `~` 展开为用户主目录
|
||
|
||
## 4. 数据模型
|
||
|
||
### 4.1 Workspace
|
||
|
||
```go
|
||
type Workspace struct {
|
||
Index int // 全局索引
|
||
N int // 编号
|
||
Title string // 短名
|
||
Prompt string // 描述
|
||
Tech string // 技术栈
|
||
Deploy string // 部署情况
|
||
Dir string // 目录路径
|
||
Group string // 分组标签
|
||
}
|
||
```
|
||
|
||
### 4.2 Group
|
||
|
||
```go
|
||
type Group struct {
|
||
Label string
|
||
Desc string
|
||
}
|
||
```
|
||
|
||
### 4.3 运行时索引
|
||
|
||
| 变量 | 类型 | 用途 |
|
||
|------|------|------|
|
||
| `Groups` | `[]Group` | 分组定义 |
|
||
| `AllWorkspaces` | `[]Workspace` | 全部工作空间 |
|
||
| `wsByNum` | `map[int]*Workspace` | 编号→Workspace O(1) 索引 |
|
||
|
||
## 5. 主模型 (app.go)
|
||
|
||
### 5.1 Model
|
||
|
||
```go
|
||
type Model struct {
|
||
activeGroup int // 当前分组索引
|
||
cursor int // 分组内光标
|
||
selected map[int]bool // 多选标记
|
||
inputBuf string // 数字快捷输入缓冲
|
||
width, height int
|
||
launched string // 启动提示
|
||
}
|
||
```
|
||
|
||
### 5.2 Update 消息路由
|
||
|
||
```
|
||
KeyPressMsg
|
||
├── q, ctrl+c → tea.Quit
|
||
├── tab, right, l → activeGroup++ → cursor=0
|
||
├── shift+tab, left, h → activeGroup--
|
||
├── 1, 2, 3, 4 → 跳转分组
|
||
├── up, k → cursor--
|
||
├── down, j → cursor++
|
||
├── Space → toggleMultiSelect
|
||
├── enter → inputBuf非空? launchByInput() : launchSelected()
|
||
├── c → copyCommand()
|
||
└── [0-9] → 追加到 inputBuf
|
||
```
|
||
|
||
### 5.3 View 渲染
|
||
|
||
```
|
||
View()
|
||
└── 启动器模式:
|
||
├─ 第1行: "u-tabs"标题 + 分组 Tab 栏
|
||
├─ 分隔线
|
||
├─ 左右布局 (JoinHorizontal):
|
||
│ ├── 左侧列表: 编号 + 标题 + 描述 (CJK安全截断)
|
||
│ └── 右侧详情: 目录/编号/描述/技术/部署/命令预览
|
||
├─ 输入缓冲提示
|
||
├─ 启动成功提示
|
||
└─ 帮助栏 (快捷键高亮)
|
||
```
|
||
|
||
### 5.4 CJK 安全截断
|
||
|
||
`truncateByWidth()` 按 rune 显示宽度截断，中文=2宽，英文=1宽，不会切断多字节字符：
|
||
|
||
```go
|
||
func truncateByWidth(s string, maxW int) string {
|
||
w := 0
|
||
for i := 0; i < len(s); {
|
||
_, size := utf8.DecodeRuneInString(s[i:])
|
||
rw := runeWidth(rune(s[i]))
|
||
if w+rw > maxW { return s[:i] }
|
||
w += rw
|
||
i += size
|
||
}
|
||
return s
|
||
}
|
||
```
|
||
|
||
## 6. 启动逻辑
|
||
|
||
### 6.1 流程
|
||
|
||
```
|
||
用户按 Enter
|
||
↓
|
||
buildLaunchScript(ws) → PS 脚本
|
||
↓
|
||
encodePSCommand(script) → UTF-16LE → Base64
|
||
↓
|
||
exec.Command("wt.exe", "-w", "0",
|
||
"-d", ws.Dir,
|
||
"--tabColor", randomColor,
|
||
"pwsh", "-NoExit", "-EncodedCommand", encoded).Start()
|
||
↓
|
||
Windows Terminal 新标签页 → claude 交互模式
|
||
```
|
||
|
||
### 6.2 PS 脚本模板
|
||
|
||
```powershell
|
||
$Host.UI.RawUI.WindowTitle = "{Title}"
|
||
Write-Host "=== {Title} ===" -ForegroundColor Cyan
|
||
Write-Host "Prompt: {Prompt}" -ForegroundColor Yellow
|
||
cd "{Dir}"
|
||
claude --name "{Title}" --permission-mode bypassPermissions
|
||
```
|
||
|
||
### 6.3 UTF-16LE 编码
|
||
|
||
```go
|
||
func encodePSCommand(script string) string {
|
||
u16 := utf16.Encode([]rune(script))
|
||
b := make([]byte, len(u16)*2)
|
||
for i, r := range u16 {
|
||
b[i*2] = byte(r)
|
||
b[i*2+1] = byte(r >> 8)
|
||
}
|
||
return base64.StdEncoding.EncodeToString(b)
|
||
}
|
||
```
|
||
|
||
## 7. 样式系统 (Tokyo Night 主题)
|
||
|
||
### 7.1 色板
|
||
|
||
| 常量 | Hex | 用途 |
|
||
|------|-----|------|
|
||
| BgDark | #1a1b26 | 深底色 |
|
||
| BgPanel | #292e42 | 面板/边框/分隔线 |
|
||
| Dim | #565f89 | 次要文字 |
|
||
| Fg | #a9b1d6 | 正文 |
|
||
| Bright | #c0caf5 | 高亮文字 |
|
||
| Accent | #7aa2f7 | 主强调 (蓝色) |
|
||
| Success | #9ece6a | 绿色 (部署/标记) |
|
||
| Warning | #e0af68 | 黄色 (输入提示) |
|
||
| Cyan | #7dcfff | 青色 (编号/详情) |
|
||
| Purple | #bb9af7 | 紫色 (选中行) |
|
||
| Red | #f7768e | 红色 (CORE分组) |
|
||
|
||
### 7.2 分组颜色
|
||
|
||
| 分组 | Hex |
|
||
|------|-----|
|
||
| CORE | #f7768e |
|
||
| LAB | #9ece6a |
|
||
| TOOLS | #e0af68 |
|
||
| ME | #bb9af7 |
|
||
| TEMP | #7dcfff |
|