Spur Product Spec

基于当前可交互 Preview（2026-08）冻结的产品说明：各区职责、用户旅程、功能、 Pi 集成方式与技术栈。用于桌面端开工，而不是再讨论「要不要做第二个 Pi」。

product Spur version 0.2 preview frozen UX site spur.kevin.top pi chat not reimplemented

1. 愿景与边界

一句话

Spur 是 Pi 的 worktree 遥控器 / 工作区 OS：管 project 与隔离 worktree，把 Pi 丢进正确的 cwd；不重做 Agent 对话能力。

做

多 project（本地 git 仓库根）侧栏管理
在 project 下创建 / 关闭 linked worktree（自选 base / quick base）
打开 worktree → 自动在该目录启动 / 附着 Pi
上下文展示（path / branch / env）与危险操作确认
账号入口占位（Sign in），后续同步 Pi 配置

不做（明确）

重做 Pi 聊天、Send、流式输出、/login UI、tools UI
完整 IDE / 内嵌代码编辑器 / LSP
第一期多 session 管理器（一 wt 默认一 Pi）
强迫用户为 core 流程注册账号

2. 产品原则

Project first, then worktree — 底部只加 project；worktree 在 project 下管理。
One chain — 创建/选中 worktree ⇒ 右侧即 Pi，且 cwd 已绑定。
Pi is the runtime — Spur 只做编排与生命周期，不抄 Pi 功能。
Chrome folds up — 顶栏合并、少空占位（无 idle/Restart 噪音）。
Safety on destroy — 关 wt / 移 project 时若 Pi 在跑必须确认。
Local-first — 核心循环不依赖云；登录只增强同步。
Speed is a feature — 桌面目标：侧栏与切换体感极致快（Rust + 异步 git）。

3. 用户与场景

主用户

并行开多个 feature / agent 任务
已用或准备用 Pi 写代码
需要 git worktree 隔离，讨厌分支互踩

核心场景

从固定 base（如 origin/main）开隔离区
立刻在隔离区里和 Pi 干活
多仓库同时挂在一个窗口侧栏
收工：关 wt / 移 project

4. 信息架构 / 各区说明

以当前 Preview 布局为准（桌面 GPUI 应对齐同一信息架构）。

┌─ Spur window ──────────────────────────────────────────────────┐ │ ┌─ Left sidebar ──────────┐ ┌─ Right main ───────────────────┐ │ │ │ [logo] Search… │ │ Pi · ctx… [Sign in] │ │ ← 同一顶栏行 │ │ │ │ env chips (仅 Pi running) │ │ │ │ ▾ project │ │ ┌────────────────────────────┐ │ │ │ │ default origin/main │ │ │ │ │ │ │ │ [+] [⋯] │ │ │ Pi surface (placeholder │ │ │ │ │ · worktree rows │ │ │ → real Pi PTY later) │ │ │ │ │ · No worktrees yet │ │ │ │ │ │ │ │ │ │ └────────────────────────────┘ │ │ │ │ [+ Add project] │ │ │ │ │ └─────────────────────────┘ └────────────────────────────────┘ │ └────────────────────────────────────────────────────────────────┘

4.1 左侧 · 顶栏（side-titlebar）

元素	说明
Logo mark	Spur 品牌（锐利 spear/shark 造型）
Search	过滤 project 名 / quick base / worktree 名与分支

4.2 左侧 · 列表

元素	说明
Project 行	折叠 ▾/▸ · 名称 · `default <quickBase>` [+] 在该 project 下新建 worktree [⋯] 菜单：Set default base / New worktree / Remove project
Worktree 行	名称 · 分支（非 main 显示 `branch ← base`）· main 角标点击 = 选中并启动/附着 Pi hover × = 关闭 linked worktree（main 不可关）
空态	project 下无 wt 时显示 `No worktrees yet`（点击同 +）

4.3 左侧 · 底栏（side-footer）

规则	说明
只加 Project	文案：Add project directory / + Add project。禁止在底栏放 New worktree。
提示	空：先加 project 再建 wt；有 project：worktree 在上方各 project 下管理。

4.4 右侧 · 顶栏（main-titlebar，单行折叠）

元素	说明
Pi context（左）	与 Sign in 同一行，不单独占第二行状态条。空：`Pi · waiting` / `Pi · select a worktree` 有 wt：`Pi · name · branch · ← base · path`
Sign in（右）	低调文字按钮占位；登录后为小 chip + Sign out。功能以后再扩。

已否决的 chrome

右侧大 SPUR 字标单独一行；idle 徽章；Restart 按钮；假聊天 Send 输入框。

4.5 右侧 · Env 条

仅当 Pi running 时展示。字段（启动契约）：

SPUR_WORKTREE — 当前隔离目录
SPUR_MAIN_REPO — 主仓库路径
SPUR_BRANCH — 当前分支
SPUR_QUICK_BASE — project 默认 base
PWD — 同 worktree（明示 cwd）

4.6 右侧 · Pi surface

整块 = Pi 本体占位（真产品为嵌入 PTY/TUI）。 Spur 不在此实现对话、Send、流式、/login。 Preview 显示 mock「Pi is running here」+ cd/pi 命令提示。

5. User Journey

J1 · 主路径（必须丝滑）

1. 打开 Spur
2. 底部 Add project → 选择本地 git 根目录 + 设 default base（默认 origin/main）
3. Project 出现在侧栏
4. 点项目行 [+]（或 ⋯ → New worktree）
5. 填 name + base（默认带出 quick base）→ Create & open in Pi
6. 链：create wt → select → boot Pi(cwd=wt)
7. 右侧 Pi surface 进入 running；env 条出现
8. 用户在 Pi 内 /login、写代码、提交（Pi 能力）
9. 收工：worktree 行 × 关闭（若 Pi 在跑则确认）或 ⋯ Remove project

J2 · 继续已有 worktree

1. 侧栏点击已有 worktree
2. 自动 select + boot/attach Pi
3. 右侧显示该 wt 上下文

J3 · 仅浏览 project

1. 点击 project 行折叠/展开
2. 未选 wt 时右侧 Pi 为 waiting / select a worktree
3. 不在「仅 project 选中」时误起 Pi 改主目录

J4 · 账号（占位）

1. 点 Sign in → 预览 mock 登录
2. 显示账号 chip；可 Sign out
3. 后续：同步 Pi auth sources / 偏好（未开工）

6. 功能说明

功能	优先级	Preview	Desktop 目标
Add project（本地目录）	P0	路径输入 + Browse mock	系统目录选择器；校验 git root
Project quick base	P0	⋯ → Set default base	持久化；创建 wt 默认填入
Create worktree from base	P0	mock path + 日志	`git worktree add -b name path base`
List / select worktree	P0	localStorage 列表	`git worktree list --porcelain`
Open wt → auto Pi	P0	bootPi mock + surface	spawn/embed `pi`，cwd=wt
Context env	P0	env chips	真实 process env
Close worktree / remove project safety	P0	confirm if Pi running	停进程 + git worktree remove
Search filter	P0	有	有
Sign in 占位	P1	mock	Google OAuth + 后端（后置）
Sync Pi config	P2	不做深	vault / providers
Embedded Pi PTY	P0 桌面	占位块	portable-pty + 终端渲染
GPUI 原生窗	P0 桌面	HTML mock	唯一生产桌面实现；由 canonical Preview 规划
多 Pi session / wt	P2	不做	默认 1:1

7. 状态与交互规则

选择状态

selection.projectId + selection.worktreeId
仅有 project、无 worktree：不启动 Pi
选中 worktree：必须尝试 boot/attach Pi

Pi 状态（每 worktree）

running | stopped（preview 用 state.pi[wtId]）
创建 wt 的 reason：create | open | restart

删除保护

关闭 linked wt 且 Pi running → 确认「Stop Pi and close」
移除 project 且任一 wt 上 Pi running → 列出 running wt 后确认
main checkout 不可作为 linked wt 关闭；只能 Remove project

快捷键（preview）

键	动作
`a` / `o`	Add project
`n`	New worktree（无 project 时引导先加）
`b`	Default base

8. Pi 集成契约

核心契约

cwd = worktree_abs_path 时执行 pi（或配置的 pi bin）。 Spur 不解析 Pi TUI 协议（P0）；只管理进程与展示表面。

启动

# conceptual
cd $SPUR_WORKTREE
env \
  SPUR_WORKTREE=... \
  SPUR_MAIN_REPO=... \
  SPUR_BRANCH=... \
  SPUR_QUICK_BASE=... \
  pi

Session

默认跟随 Pi 自身 session 目录（按 cwd 组织）
P0 不强制 --session-dir 进 worktree
一 worktree 一 Pi 进程（默认）

生命周期

事件	Spur 行为
select / create wt	start or focus Pi for that cwd
close wt	stop Pi then remove worktree（确认）
remove project	stop all child Pi then drop from store
Pi exit	标记 stopped；表面显示未运行（可再附着）

UI 边界

Spur：侧栏 + 顶栏上下文 + env + Pi surface 容器
Pi：容器内全部交互（对话、登录模型、工具）

9. 账号 / 登录（占位）

右上角 Sign in（低调文字，非大 Google 徽章）
Preview：mock 登录 + Sign out
意图：日后同步 Pi 相关 auth sources / 偏好；不阻塞 local 主路径
真 OAuth / vault：P1+，需后端与隐私说明

10. 技术栈

层	选型	备注
桌面语言	Rust	性能优先
桌面 UI 生产实现	GPUI	唯一构建与发布路径
设计与评审基线	Canonical HTML Preview	与 GPUI 共享 tokens 和场景清单
异步	tokio
Git	git CLI	正确性优先
Agent	Pi CLI	cwd + env
PTY	portable-pty 等	嵌入 Pi
本地状态	JSON → sqlite 可演进	`~/Library/Application Support/spur/`
官网	Vite 静态 + Cloudflare Pages	spur.kevin.top
包装	macOS .app + codesign DMG	Developer ID
仓库	github.com/kevinaimonster/spur	private

11. 架构与 Crate

spur/
├── crates/
│   ├── spur_core      # 模型 · Command · Event · Error
│   ├── spur_git       # worktree / branch / path / default base
│   ├── spur_store     # 持久化 projects / prefs / auth stub
│   ├── spur_agent     # Pi LaunchSpec + env
│   ├── spur_runtime   # 多 repo 编排 · 队列 · 生命周期
│   ├── spur_pty       # PTY 生命周期
│   ├── spur_terminal  # VT 网格（供 UI 绘制）
│   ├── spur_gpui      # 唯一原生桌面入口与生产 UI
│   ├── spur_design_system # tokens / contract / fixtures
│   ├── spur_ui_catalog # native design harness
│   └── spur_cli       # 无头金样
├── apps/web           # 官网 + preview/
├── packaging/macos    # 签名 DMG
├── branding           # logo SVG
└── docs/              # 本 spec 等

依赖方向：UI → runtime → (git | store | agent | pty)；core 不依赖 UI。

12. 数据模型（逻辑）

Project {
  id, name, path,              // git root
  quickBase,                   // e.g. origin/main
  open: bool,                  // sidebar expanded
  worktrees: Worktree[]
}

Worktree {
  id, name, path, branch,
  fromBase?,                   // create base
  isMain: bool
}

Selection { projectId?, worktreeId? }

PiSession {                    // per worktree
  running: bool,
  startedAt?,
  env: { SPUR_* }
}

Auth {                         // placeholder
  signedIn, provider, user?,
  piSync?: { status, lastSyncAt, sources[] }
}

13. 非功能需求

侧栏点击到 UI 反馈 < 100ms；git/Pi 启动异步不堵 UI
macOS arm64 与 Intel 各发一份签名 DMG；签名分发；公证可选但建议
不提交密钥 / .p12；配置走 Keychain 与用户目录
协议：桌面代码 MIT；不引入 Zed GPL 代码

14. MVP 范围 / 分期

已完成（Preview / 基建）

产品规则与 IA 在 HTML Preview 可点通
官网 + Cloudflare Pages + 域名
Rust monorepo 骨架 + CLI worktree 金样
签名 DMG 脚本与品牌 logo

Desktop MVP（开工目标）

GPUI（或阶段性 UI）对齐 Preview 布局
真 git：add project / list / create / remove worktree
真 Pi：select/create wt → spawn pi(cwd) + env
嵌入或先系统级附着 Pi；表面容器对齐占位
关闭/删除安全确认

随后

PTY 内嵌打磨
公证与自动更新
Sign in 真接通 + Pi 配置同步

15. 开工清单

建议第一周

以本 spec + apps/web/public/preview/ 为 UX 源，冻结 IA
spur_git：create/list/remove 与 path 模板对齐 Preview
spur_agent + runtime：selectWorktree → bootPi 真进程
UI：左侧列表 + 底栏 Add project + 顶栏 Pi context + Pi surface 容器
手工验收：走通 J1 全路径

验收标准（J1）

能添加真实 git project
能从 quick base 创建 linked worktree 且磁盘存在
创建后自动在该目录启动 Pi（可见进程 / 嵌入表面）
env 中带 SPUR_*
Pi 运行中删除 wt 有确认且不留僵尸进程

16. 链接与资产

资源	位置
私仓	github.com/kevinaimonster/spur
官网	spur.kevin.top
Preview UX	spur.kevin.top/preview
Preview 源	`apps/web/public/preview/`
本 Spec	`docs/spec.html`
架构备忘	`docs/architecture.md`
Logo	`branding/`
包装	`packaging/macos/`