openclaw/skills/gsd-openclaw/.planning/phases/01-core-infrastructure/01-CONTEXT.md

Phase 1: Core Infrastructure - Context

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

## Phase Boundary

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

## 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 版本号设计
• 日志文件命名格式
• 错误消息的具体措辞

## Specific Ideas

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

<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 Ideas

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

---

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