# Phase 4: GSD Integration - Context

**Gathered:** 2026-03-11
**Status:** Ready for planning

<domain>
## Phase Boundary

完成 GSD 命令全覆盖 — 确保所有 34 个 GSD slash 命令都能通过桥接正常工作，实现 BRDG-06 要求。这个阶段填补编排层（Phase 3）与 100% 命令覆盖之间的差距，同时完善项目上下文追踪和工作流连续性支持。

</domain>

<decisions>
## Implementation Decisions

### 命令清单处理策略
- **处理模式**: 关键命令特殊处理，其余泛型透传
- **关键命令定义**: `/gsd:new-project` 和 `/gsd:use` 需要 orchestrator 特殊逻辑
- **泛型命令**: 其他 32 个命令统一通过 tmux 透传 + 卡片格式化

### 关键命令特殊处理

#### `/gsd:new-project`
- **预创建会话**: orchestrator 检测命令后，先调用 TmuxSessionManager 创建会话和工作空间
- **命令透传**: 会话创建后，透传命令到 tmux 让 GSD 初始化项目结构
- **工作空间路径**: `~/gsd-workspaces/{project}/`

#### `/gsd:use`
- **上下文追踪**: OpenClaw 在用户级别追踪当前项目（存入独立用户状态文件）
- **后续命令路由**: 后续命令根据追踪的上下文选择目标 tmux 会话
- **项目不存在处理**: 检查项目是否存在，不存在则返回错误卡片 + 「创建新项目」按钮

### 项目上下文追踪

#### 存储设计
- **位置**: `~/gsd-workspaces/.users/{user_id}/context.json`
- **格式**: JSON，原子写入（与 Phase 1 state.json 一致）

#### 追踪数据
- **当前项目**: 用户当前正在操作的项目名
- **最近项目列表**: 最近使用的项目（保留最近 5 个）
- **最后活跃时间**: 用户上次活动时间戳
- **用户偏好**: 可选的个性化设置（默认超时、输出格式等）

#### 多用户场景
- **隔离策略**: 完全隔离 — 每个用户独立的 tmux 会话和工作空间
- **用户识别**: 通过 OpenClaw 的 user_id 区分

### 频道支持
- **Phase 4 范围**: 仅飞书
- **其他频道**: 微信、Telegram、Discord 延后到 v2

### 工作流连续性

#### 上下文保持
- **机制**: tmux 持久会话
- **Claude CLI 上下文**: 自然保持在 tmux 会话中
- **用户重连**: 直接重连到现有 tmux 会话

#### 中途掉线恢复
- **责任归属**: GSD 处理恢复（通过 STATE.md 追踪）
- **OpenClaw 角色**: 只负责重新连接到 tmux 会话

#### 长命令超时
- **普通命令**: 60 秒超时（Phase 3 已定义）
- **长命令**: 无超时，依赖 GSD 自己的完成信号
- **长命令列表**: `execute-phase`, `plan-phase`, `discuss-phase`, `new-project`
- **进度更新**: 使用 Phase 3 的 ProgressMonitor 机制

### Claude's Discretion
- 用户偏好的具体字段名和默认值
- 长命令检测的具体逻辑（命令名匹配 vs 运行时检测）
- 最近项目列表的保留数量（建议 5 个）

</decisions>

<specifics>
## Specific Ideas

- 用户状态文件路径与 Phase 1 的 state.json 保持一致的原子写入模式
- 「创建新项目」按钮样式与 Phase 2 的卡片按钮一致
- 长命令识别通过命令名前缀匹配（execute-, plan-, discuss-, new-project）

</specifics>

<code_context>
## Existing Code Insights

### Reusable Assets
- **Phase 1 TmuxSessionManager**: 会话创建、恢复、销毁 — `/gsd:new-project` 预创建会话的基础
- **Phase 1 StateManager**: JSON 状态管理模式 — 用户上下文存储可直接复用原子写入模式
- **Phase 1 WorkspaceManager**: 工作空间目录创建 — `/gsd:new-project` 需要调用
- **Phase 2 FeishuResponseFormatter**: 卡片格式化 — format_success/format_error/format_info
- **Phase 3 Orchestrator**: 命令路由框架 — 需要扩展添加特殊命令处理分支
- **Phase 3 ApprovalHandler**: 按钮回调处理 — 「创建新项目」按钮可复用此机制
- **Phase 3 ProgressMonitor**: 进度更新 — 长命令的进度反馈

### Established Patterns
- **状态持久化**: JSON 格式，原子写入（tempfile + rename）
- **错误处理**: 中文错误消息 + 异常类
- **卡片布局**: 三区结构（标题区 + 内容区 + 操作区）
- **命名规范**: gsd- 前缀统一

### Integration Points
- `UserContextManager` (新增): 用户上下文追踪，被 Orchestrator 调用
- `Orchestrator.handle_message()`: 需要扩展特殊命令处理逻辑
- `Orchestrator.parse_command()`: 已有的命令解析可复用
- Phase 4 完成后，BRDG-06 需求将满足

</code_context>

<deferred>
## Deferred Ideas

- 微信频道支持 — v2 特性
- Telegram/Discord 频道支持 — v2 特性
- 多语言支持（中文/英文切换）
- 项目共享（多用户协作同一项目）
- 命令历史记录和搜索

</deferred>

---

*Phase: 04-gsd-integration*
*Context gathered: 2026-03-11*