docs(phase-04): research GSD integration phase domain

2026-03-11 18:26:56 +08:00
parent d7696a3742
commit e001f5b04a
1 changed files with 540 additions and 0 deletions
@@ -0,0 +1,540 @@
 # Phase 4: GSD Integration - Research
 **Researched:** 2026-03-11
 **Domain:** GSD command bridging, user context tracking, special command handling
 **Confidence:** HIGH
 ## Summary
 Phase 4 completes the GSD command coverage by implementing special handling for key commands (`/gsd:new-project` and `/gsd:use`) while ensuring all 34 GSD slash commands work through pass-through mode. The primary technical challenges are:
 1. **Special Command Handling**: `/gsd:new-project` requires pre-creating the tmux session and workspace before passing the command to GSD. `/gsd:use` requires tracking user context across sessions.
 2. **User Context Tracking**: A new `UserContextManager` class is needed to track which project each user is currently working on, stored in independent user state files.
 3. **Long Command Support**: Certain commands (execute-phase, plan-phase, discuss-phase, new-project) have no timeout and rely on GSD's completion signal with progress updates.
 **Primary recommendation:** Extend the existing `Orchestrator` class with special command detection logic, add a new `UserContextManager` class following Phase 1's atomic write patterns, and leverage existing Phase 3 components (ProgressMonitor, ApprovalHandler) for long-running operations.
 <user_constraints>
 ## User Constraints (from CONTEXT.md)
 ### Locked 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 个）
 ### Deferred Ideas (OUT OF SCOPE)
 - 微信频道支持 — v2 特性
 - Telegram/Discord 频道支持 — v2 特性
 - 多语言支持（中文/英文切换）
 - 项目共享（多用户协作同一项目）
 - 命令历史记录和搜索
 </user_constraints>
 <phase_requirements>
 ## Phase Requirements
 | ID | Description | Research Support |
 |----|-------------|-----------------|
 | BRDG-06 | All GSD slash commands are supported (no command left behind) | GSD has 34 commands across 5 categories (Core Workflow, Navigation, Brownfield, Phase Management, Session, Utilities). Current Orchestrator supports generic pass-through via regex parsing. Special handling needed for `new-project` and `use`. |
 </phase_requirements>
 ## Standard Stack
 ### Core
 | Library | Version | Purpose | Why Standard |
 |---------|---------|---------|--------------|
 | libtmux | 0.37.0+ | tmux session management | Already used in Phase 1 TmuxSessionManager |
 | Python dataclasses | 3.12+ | Data structures | Established pattern in existing codebase |
 | json (stdlib) | 3.12+ | State persistence | Already used in Phase 1 StateManager |
 | tempfile (stdlib) | 3.12+ | Atomic writes | Established pattern from Phase 1 |
 | re (stdlib) | 3.12+ | Command parsing | Already used in Orchestrator |
 ### Supporting
 | Library | Version | Purpose | When to Use |
 |---------|---------|---------|-------------|
 | pytest | 8.0+ | Testing | All new components |
 | unittest.mock | 3.12+ | Mocking tmux | Unit tests for UserContextManager |
 ### Alternatives Considered
 | Instead of | Could Use | Tradeoff |
 |------------|-----------|----------|
 | Custom UserContextManager | SQLite for user state | SQLite adds complexity; JSON is simpler and matches Phase 1 pattern |
 | Command name prefix matching | Runtime detection of long commands | Prefix matching is simpler and more predictable; runtime detection would require analyzing output patterns |
 **Installation:**
 ```bash
 # No new dependencies required - all existing stack
 ```
 ## Architecture Patterns
 ### Recommended Project Structure
 ```
 src/gsd_openclaw/
 ├── user_context.py        # NEW: UserContextManager class
 ├── orchestrator.py        # EXTEND: Add special command handling
 ├── tmux_session.py        # REUSE: Session creation for new-project
 ├── command_executor.py    # EXTEND: Add long command detection
 ├── progress_monitor.py    # REUSE: Progress updates for long commands
 ├── approval_handler.py    # REUSE: Button callbacks for "create project"
 ├── response_formatter.py  # REUSE: Card formatting
 └── state_manager.py       # REUSE: Atomic write pattern reference
 tests/
 ├── test_user_context.py   # NEW: UserContextManager tests
 ├── test_orchestrator.py   # EXTEND: Add special command tests
 └── conftest.py            # EXTEND: Add user context fixtures
 ```
 ### Pattern 1: UserContextManager Class
 **What:** Manages per-user project context with atomic persistence
 **When to use:** Tracking which project a user is working on
 **Example:**
 ```python
 # Source: Based on Phase 1 StateManager pattern
 from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Optional, List
 import json
 import tempfile
 import os
@dataclass
 class UserContext:
    """User's project context state."""
    schema_version: str = "1.0"
    user_id: str = ""
    current_project: str = ""
    recent_projects: List[str] = field(default_factory=list)
    last_active_at: str = ""
    preferences: dict = field(default_factory=dict)
 class UserContextManager:
    """Manages user context with atomic persistence."""
    USERS_ROOT = Path.home() / "gsd-workspaces" / ".users"
    def __init__(self, user_id: str, users_root: Optional[Path] = None):
        self.user_id = user_id
        self.users_root = Path(users_root) if users_root else self.USERS_ROOT
        self.context_path = self.users_root / user_id / "context.json"
    def load(self) -> Optional[UserContext]:
        """Load user context with backup fallback."""
        # Same pattern as StateManager.load()
        ...
    def save(self, context: UserContext) -> None:
        """Save user context atomically with backup rotation."""
        # Same pattern as StateManager.save_state()
        # 1. Create parent dirs
        # 2. Rotate backup
        # 3. Write to temp file
        # 4. Atomic replace
        ...
 ```
 ### Pattern 2: Special Command Detection in Orchestrator
 **What:** Route specific commands to special handlers, pass others through
 **When to use:** Processing incoming /gsd:* commands
 **Example:**
 ```python
 # Source: Extension of existing Orchestrator.handle_message()
 class Orchestrator:
    # Long commands that need no timeout
    LONG_COMMANDS = {'execute-phase', 'plan-phase', 'discuss-phase', 'new-project'}
    def handle_message(self, user_id: str, message: str, channel: str, context: Dict) -> Dict:
        parsed = self.parse_command(message)
        if parsed is None:
            return self.formatter.format_info(title="无效命令", content="...")
        command, args = parsed
        # Special handling for new-project
        if command == 'new-project':
            return self._handle_new_project(user_id, args)
        # Special handling for use
        if command == 'use':
            return self._handle_use_project(user_id, args)
        # Generic pass-through for all other commands
        return self._handle_generic_command(user_id, command, args)
    def _handle_new_project(self, user_id: str, project_name: str) -> Dict:
        """Pre-create session then pass command to GSD."""
        # 1. Create tmux session via TmuxSessionManager
        session = self.tmux_manager.create_session(project_name)
        # 2. Execute /gsd:new-project in the session
        result = self.executor.execute(session, f"/gsd:new-project {project_name}", timeout=None)
        # 3. Update user context
        self.user_context_manager.set_current_project(user_id, project_name)
        # 4. Return formatted result
        ...
    def _handle_use_project(self, user_id: str, project_name: str) -> Dict:
        """Switch user's current project context."""
        # 1. Check if project exists
        session = self.tmux_manager.get_session(project_name)
        if session is None:
            # Return error card with "Create New Project" button
            return self.formatter.format_error(
                title="项目不存在",
                content=f"项目 '{project_name}' 不存在",
                buttons=[CardButton(text="创建新项目", value={"action": "new-project", "name": project_name})]
            )
        # 2. Update user context
        self.user_context_manager.set_current_project(user_id, project_name)
        # 3. Return success
        ...
    def _is_long_command(self, command: str) -> bool:
        """Check if command requires no timeout."""
        return command in self.LONG_COMMANDS
 ```
 ### Pattern 3: Long Command Execution
 **What:** Execute commands without timeout, use progress monitoring
 **When to use:** Commands that take minutes to complete
 **Example:**
 ```python
 # Source: Extension of CommandExecutor.execute()
 def execute_with_progress(
    self,
    session,
    command: str,
    progress_callback: Callable[[ProgressInfo], None],
    poll_interval: float = 5.0  # Check every 5 seconds for long commands
 ) -> CommandResult:
    """Execute long command with progress updates."""
    # 1. Send command
    self.send_command(session.tmux_session.active_pane, command)
    # 2. Poll for output and progress
    while True:
        time.sleep(poll_interval)
        output = self._capture_current_output(session.tmux_session.active_pane)
        # Check for progress indicators
        progress = self.progress_monitor.extract_progress(output)
        if progress and self.progress_monitor.should_send_update():
            progress_callback(progress)
        # Check for completion (prompt or stabilization)
        if self._is_complete(output):
            return CommandResult(output=output, completed=True, ...)
 ```
 ### Anti-Patterns to Avoid
 - **Don't block on long commands:** Use async polling, not synchronous waits
 - **Don't mix user contexts:** Each user has isolated context, never share between users
 - **Don't timeout long commands:** execute-phase, plan-phase, discuss-phase, new-project have no timeout
 - **Don't duplicate state logic:** Reuse Phase 1's atomic write pattern for UserContextManager
 ## Don't Hand-Roll
 | Problem | Don't Build | Use Instead | Why |
 |---------|-------------|-------------|-----|
 | User state persistence | Custom file locking | StateManager atomic write pattern | Crash-safe, tested pattern from Phase 1 |
 | Progress detection | Custom regex | ProgressMonitor.extract_progress() | Already handles percentage, fraction, phase patterns |
 | Approval cards | New button format | ApprovalHandler.create_approval_card() | Existing pattern for interactive buttons |
 | Session creation | Manual tmux commands | TmuxSessionManager.create_session() | Handles collision resolution, state persistence |
 **Key insight:** Phase 4 is primarily about extending existing patterns, not creating new ones. The UserContextManager follows StateManager patterns exactly, special commands extend Orchestrator's routing, and long commands extend CommandExecutor.
 ## Common Pitfalls
 ### Pitfall 1: Race Condition in Session Creation
 **What goes wrong:** Two users try to create project with same name simultaneously
 **Why it happens:** No locking on session creation
 **How to avoid:** TmuxSessionManager._resolve_collision() already handles this with timestamp suffix
 **Warning signs:** Session names with unexpected suffixes, duplicate state files
 ### Pitfall 2: User Context File Corruption
 **What goes wrong:** Server crash during write leaves corrupted context.json
 **Why it happens:** Not using atomic writes
 **How to avoid:** Follow StateManager pattern exactly: tempfile + os.replace
 **Warning signs:** JSONDecodeError when loading context, missing user preferences
 ### Pitfall 3: Long Command Timeout
 **What goes wrong:** execute-phase times out after 60 seconds
 **Why it happens:** Using default timeout for all commands
 **How to avoid:** Check command name against LONG_COMMANDS set, pass timeout=None
 **Warning signs:** Commands return "timeout" status, incomplete phases
 ### Pitfall 4: Missing User Context on First Use
 **What goes wrong:** New user sends command without context
 **Why it happens:** UserContextManager.load() returns None for new users
 **How to avoid:** Create default context on first access, use "default" project
 **Warning signs:** KeyError on user_id, missing project routing
 ## Code Examples
 Verified patterns from existing codebase:
 ### Atomic Write Pattern (from state_manager.py)
 ```python
 # Source: /home/starmen1265/work/kb-skills/gsd-openclaw/src/gsd_openclaw/state_manager.py
 def save_state(state: SessionState, state_path: Path) -> None:
    """Save session state to file atomically with backup rotation."""
    state_path = Path(state_path)
    backup_path = state_path.with_suffix('.json.bak')
    # 1. Create parent directories if missing
    state_path.parent.mkdir(parents=True, exist_ok=True)
    # 2. Rotate backup
    if state_path.exists():
        if backup_path.exists():
            backup_path.unlink()
        state_path.rename(backup_path)
    # 3. Write to temp file in same directory
    fd, temp_path = tempfile.mkstemp(dir=state_path.parent, suffix='.tmp')
    try:
        with os.fdopen(fd, 'w', encoding='utf-8') as f:
            json.dump(state.to_dict(), f, indent=2, ensure_ascii=False)
        # 4. Atomic replace
        os.replace(temp_path, state_path)
    except Exception:
        if os.path.exists(temp_path):
            os.unlink(temp_path)
        raise
 ```
 ### Command Parsing Pattern (from orchestrator.py)
 ```python
 # Source: /home/starmen1265/work/kb-skills/gsd-openclaw/src/gsd_openclaw/orchestrator.py
 class Orchestrator:
    COMMAND_PATTERN = re.compile(r'^/gsd:(\S+)\s*(.*)$')
    def parse_command(self, message: str) -> Optional[Tuple[str, str]]:
        """Parse a message for /gsd:* command pattern."""
        match = self.COMMAND_PATTERN.match(message.strip())
        if match:
            command = match.group(1)
            args = match.group(2).strip()
            return (command, args)
        return None
 ```
 ### Progress Detection Pattern (from progress_monitor.py)
 ```python
 # Source: /home/starmen1265/work/kb-skills/gsd-openclaw/src/gsd_openclaw/progress_monitor.py
 class ProgressMonitor:
    PROGRESS_PATTERNS = [
        (re.compile(r'(\d+)%'), 'percentage'),
        (re.compile(r'\[(\d+)/(\d+)(?:[^\]]*)\]'), 'fraction'),
        (re.compile(r'Phase\s+(\d+)', re.IGNORECASE), 'phase'),
        (re.compile(r'完成|completed|done', re.IGNORECASE), 'completion'),
    ]
    def extract_progress(self, output: str) -> Optional[ProgressInfo]:
        """Extract progress information from output text."""
        for pattern, progress_type in self.PROGRESS_PATTERNS:
            match = pattern.search(output)
            if match:
                # Return ProgressInfo based on type
                ...
 ```
 ## State of the Art
 | Old Approach | Current Approach | When Changed | Impact |
 |--------------|------------------|--------------|--------|
 | Per-session context | Per-user context (Phase 4) | This phase | Users can switch projects without losing context |
 | Fixed 60s timeout | Adaptive timeout based on command | This phase | Long commands no longer timeout prematurely |
 | Generic command handling | Special handling for key commands | This phase | new-project pre-creates session, use tracks context |
 **Deprecated/outdated:**
 - None in this phase (building on existing patterns)
 ## GSD Command Categories (34 Total)
 Based on official GSD documentation (https://github.com/gsd-build/get-shit-done):
 ### Core Workflow (8 commands)
 | Command | Description | Special Handling |
 |---------|-------------|------------------|
 | `/gsd:new-project` | Initialize project with questions, research, requirements, roadmap | YES - Pre-create session |
 | `/gsd:discuss-phase` | Capture implementation decisions | Long command |
 | `/gsd:plan-phase` | Research + plan + verify | Long command |
 | `/gsd:execute-phase` | Execute plans in parallel waves | Long command |
 | `/gsd:verify-work` | Manual user acceptance testing | Pass-through |
 | `/gsd:audit-milestone` | Verify milestone completion | Pass-through |
 | `/gsd:complete-milestone` | Archive milestone, tag release | Pass-through |
 | `/gsd:new-milestone` | Start next version | Pass-through |
 ### Navigation (4 commands)
 | Command | Description | Special Handling |
 |---------|-------------|------------------|
 | `/gsd:progress` | Show current position | Pass-through |
 | `/gsd:help` | Show all commands | Pass-through |
 | `/gsd:update` | Update GSD | Pass-through |
 | `/gsd:join-discord` | Join community | Pass-through |
 ### Brownfield (1 command)
 | Command | Description | Special Handling |
 |---------|-------------|------------------|
 | `/gsd:map-codebase` | Analyze existing codebase | Pass-through |
 ### Phase Management (5 commands)
 | Command | Description | Special Handling |
 |---------|-------------|------------------|
 | `/gsd:add-phase` | Append phase to roadmap | Pass-through |
 | `/gsd:insert-phase` | Insert urgent work | Pass-through |
 | `/gsd:remove-phase` | Remove future phase | Pass-through |
 | `/gsd:list-phase-assumptions` | See Claude's approach | Pass-through |
 | `/gsd:plan-milestone-gaps` | Create phases for gaps | Pass-through |
 ### Session (2 commands)
 | Command | Description | Special Handling |
 |---------|-------------|------------------|
 | `/gsd:pause-work` | Create handoff | Pass-through |
 | `/gsd:resume-work` | Restore from session | Pass-through |
 ### Utilities (9 commands)
 | Command | Description | Special Handling |
 |---------|-------------|------------------|
 | `/gsd:use` | Switch project context | YES - Track user context |
 | `/gsd:settings` | Configure GSD | Pass-through |
 | `/gsd:set-profile` | Switch model profile | Pass-through |
 | `/gsd:add-todo` | Capture idea | Pass-through |
 | `/gsd:check-todos` | List pending todos | Pass-through |
 | `/gsd:debug` | Systematic debugging | Pass-through |
 | `/gsd:quick` | Execute ad-hoc task | Pass-through |
 | `/gsd:health` | Validate .planning/ | Pass-through |
 **Note:** 2 commands need special handling (new-project, use), 4 are long commands (new-project, execute-phase, plan-phase, discuss-phase), all others pass through generically.
 ## Open Questions
 1. **User Preferences Schema**
   - What we know: CONTEXT.md mentions preferences field (default timeout, output format)
   - What's unclear: Exact field names and default values
   - Recommendation: Start minimal with empty dict, add fields as needed
 2. **Long Command Detection Implementation**
   - What we know: Command name matching is the approach (from CONTEXT.md)
   - What's unclear: Whether to also detect long-running at runtime
   - Recommendation: Start with command name matching, add runtime detection if needed
 3. **Recent Projects List Size**
   - What we know: CONTEXT.md suggests 5 items
   - What's unclear: Whether this should be configurable
   - Recommendation: Hardcode 5, make configurable later if requested
 ## Validation Architecture
 ### Test Framework
 | Property | Value |
 |----------|-------|
 | Framework | pytest 8.0+ |
 | Config file | pyproject.toml (existing) |
 | Quick run command | `pytest tests/test_user_context.py tests/test_orchestrator.py -x -v` |
 | Full suite command | `pytest -x` |
 ### Phase Requirements → Test Map
 | Req ID | Behavior | Test Type | Automated Command | File Exists? |
 |--------|----------|-----------|-------------------|-------------|
 | BRDG-06 | All 34 GSD commands supported | unit | `pytest tests/test_orchestrator.py::TestGsdCommands -x -v` | Wave 0 (new) |
 | BRDG-06 | new-project pre-creates session | unit | `pytest tests/test_orchestrator.py::TestSpecialCommands::test_new_project_creates_session -v` | Wave 0 (new) |
 | BRDG-06 | use tracks user context | unit | `pytest tests/test_user_context.py::TestUserContextManager::test_set_current_project -v` | Wave 0 (new) |
 | BRDG-06 | use shows error for non-existent project | unit | `pytest tests/test_orchestrator.py::TestSpecialCommands::test_use_nonexistent_project -v` | Wave 0 (new) |
 | BRDG-06 | long commands have no timeout | unit | `pytest tests/test_command_executor.py::TestLongCommands -v` | Wave 0 (extend) |
 | BRDG-06 | user context persists atomically | unit | `pytest tests/test_user_context.py::TestAtomicWrites -v` | Wave 0 (new) |
 | BRDG-06 | user context isolated between users | unit | `pytest tests/test_user_context.py::TestMultiUser -v` | Wave 0 (new) |
 ### Sampling Rate
 - **Per task commit:** `pytest tests/test_user_context.py tests/test_orchestrator.py -x -v`
 - **Per wave merge:** `pytest -x`
 - **Phase gate:** Full suite green before `/gsd:verify-work`
 ### Wave 0 Gaps
 - [ ] `tests/test_user_context.py` — new file for UserContextManager tests
 - [ ] `tests/test_orchestrator.py` — extend with TestSpecialCommands class
 - [ ] `tests/conftest.py` — add user_context fixture
 - [ ] Extend `tests/test_command_executor.py` — add long command tests
 ## Sources
 ### Primary (HIGH confidence)
 - GSD Official Repository: https://github.com/gsd-build/get-shit-done - Complete command list and documentation
 - Existing codebase: `/home/starmen1265/work/kb-skills/gsd-openclaw/src/gsd_openclaw/` - Established patterns for state management, command execution, response formatting
 ### Secondary (MEDIUM confidence)
 - Phase 1 research: `.planning/phases/01-core-infrastructure/01-RESEARCH.md` - StateManager atomic write pattern
 - Phase 3 research: `.planning/phases/03-orchestration/03-RESEARCH.md` - Orchestrator command routing
 ### Tertiary (LOW confidence)
 - None - all findings verified against codebase or official docs
 ## Metadata
 **Confidence breakdown:**
 - Standard stack: HIGH - All libraries already in use
 - Architecture: HIGH - Patterns established in Phases 1-3
 - Pitfalls: HIGH - Based on analysis of existing code patterns
 **Research date:** 2026-03-11
 **Valid until:** 30 days - stable patterns, unlikely to change significantly