# Phase 1: Core Infrastructure - Context

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

<domain>
## Phase Boundary

创建、列表、销毁、恢复 tmux 会话，带持久化状态，支持多用户隔离的会话管理基础设施。这是整个 gsd-openclaw 技能的底层核心，后续所有命令桥接和 GSD 集成都依赖于此。

</domain>

<decisions>
## Implementation Decisions

### Session Naming
- **命名格式**: 仅项目名（单用户场景，如 `gsd-project-alpha`）
- **同名冲突**: 自动添加时间戳后缀（如 `-20260311-001`）
- **显示名**: 支持用户自定义友好名称，存储映射：显示名 → tmux 名
- **会话限制**: 每用户可配置最大会话数（默认值由 planner 决定）

### State Storage
- **位置**: 每项目独立目录 `~/gsd-workspaces/{project}/.gsd/`
- **检查点频率**: 每 30 秒自动保存
- **状态内容**:
  - 会话元数据（ID、项目名、创建时间）
  - tmux 引用（会话名、窗格 ID）
  - 活动统计（最后活跃时间、命令计数）
  - 最后输出快照
- **原子写入**: 是（先写临时文件再 rename）
- **备份策略**: 保留 1 个备份（`.gsd/state.json.bak`）

### Workspace Structure
- **根目录**: `~/gsd-workspaces/{project}/`
- **目录布局**:
  ```
  ~/gsd-workspaces/{project}/
  ├── .gsd/
  │   ├── state.json          # 会话状态
  │   ├── state.json.bak      # 状态备份
  │   └── session-dump/       # 会话转储
  ├── code/                   # 项目代码（可选）
  └── io-logs/
      └── {session-id}.log    # I/O 日志
  ```
- **I/O 日志保留**: 7 天
- **会话结束处理**: 销毁会话时删除工作空间

### Recovery Strategy
- **崩溃恢复**: 启动时自动检测状态文件，提示用户是否恢复
- **孤儿会话处理**: 自动清理没有状态文件的 tmux 会话
- **状态验证**: 恢复前验证状态文件完整性和版本兼容性
- **备份使用**: 主状态文件损坏时自动尝试备份

### Claude's Discretion
- 检查点的精确触发时机（命令后 vs 定时器）
- 状态文件 schema 版本号设计
- 日志文件命名格式
- 错误消息的具体措辞

</decisions>

<specifics>
## Specific Ideas

- 工作空间结构参考 dev-workflow 的 `.planning/` 模式
- 状态文件使用 JSON 格式，与 dev-workflow 的 state.json 一致
- tmux 会话名前缀统一使用 `gsd-` 避免与其他 tmux 用途冲突

</specifics>

<code_context>
## Existing Code Insights

### Reusable Assets
- **dev-workflow/state_manager.py**: JSON 状态管理模式可直接复用
  - `load_state()`, `save_state()`, `init_state()` 函数签名
  - 原子写入模式（temp file + rename）
  - ISO 时间戳格式
- **dev-workflow/orchestrator.py**: 命令行参数解析模式
  - argparse 结构
  - 阶段管理逻辑

### Established Patterns
- **状态路径查找**: 从当前目录向上查找 `.planning/` 定位项目根
- **目录创建**: `mkdir(parents=True, exist_ok=True)` 模式
- **错误处理**: 中文错误消息 + sys.exit(1)

### Integration Points
- 本 phase 产出的 `state_manager.py` 将被 Phase 3 的 `orchestrator.py` 调用
- `tmux_session_manager.py` 将被 Phase 3 的命令桥接调用
- 工作空间目录结构将被 Phase 4 的 GSD 集成使用

</code_context>

<deferred>
## Deferred Ideas

- 多用户前缀（当前为单用户场景，如需多用户隔离可后续添加）
- 会话池化和 LRU 淘汰（v2 特性）
- 会话分支和克隆（v2 特性）
- 实时状态同步到 OpenClaw 控制面板（Phase 5）

</deferred>

---

*Phase: 01-core-infrastructure*
*Context gathered: 2026-03-11*