# Phase 3: Orchestration - Context

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

<domain>
## Phase Boundary

命令路由和双向桥接 — 用户通过聊天发送 GSD slash 命令，系统捕获 tmux 输出并返回，支持审批流程、进度更新和错误处理。这是 gsd-openclaw 技能的"大脑"层，连接 Phase 1 的会话管理、Phase 2 的响应格式化与实际的 GSD 命令执行。

</domain>

<decisions>
## Implementation Decisions

### 命令路由策略
- **命令解析**: 直接解析（正则或字符串分割），由 orchestrator.py 验证命令有效性
- **会话需求**: 所有命令需要 tmux 会话（统一流程，简化实现）
- **执行超时**: 60 秒（大多数 GSD 命令在合理时间内完成）
- **无会话处理**: 自动创建会话并执行命令（参考 Phase 2 CONTEXT.md 的设计）

### 审批流程集成
- **审批检测**: 解析 Claude 工具调用标记（如 AskUserQuestion、ExitPlanMode）
- **回调处理**: 使用飞书 Card 按钮回调（value 字段存储上下文）
- **审批超时**: 无超时限制（等待用户响应或会话结束）

### 进度更新机制
- **进度检测**: 输出模式匹配（监控百分比、阶段名等进度相关字符串）
- **更新频率**: 每 1 分钟发送一次进度更新
- **完成检测**: tmux 提示符出现（Claude CLI 输出完成，会话返回到提示符）

### 错误处理策略
- **错误检测**: 关键词匹配（监控输出中的 error、failed、exception 等）
- **错误呈现**: 直接展示原始错误（使用 Phase 2 的 format_error() 方法）
- **会话丢失处理**: 自动恢复会话并重试命令（CLI 已支持会话恢复）

### Claude's Discretion
- 进度匹配的具体正则模式
- 错误关键词的完整列表
- 审批按钮的具体文案和样式
- 进度更新的卡片格式

</decisions>

<specifics>
## Specific Ideas

- 进度更新使用简洁格式（如"正在执行... [2/5 任务]"）
- 审批按钮保持简洁（2-4 个中文字符，与 Phase 2 一致）
- 错误卡片使用红色主题（Phase 2 已定义）

</specifics>

<code_context>
## Existing Code Insights

### Reusable Assets
- **Phase 1 TmuxSessionManager**: 会话创建、恢复、销毁 — 所有命令执行的基础
- **Phase 1 StateManager**: 状态持久化 — 存储当前项目上下文
- **Phase 1 CLI (cli.py)**: 命令解析模式可参考（argparse 结构）
- **Phase 2 FeishuResponseFormatter**: 卡片格式化 — format_success/format_error/format_info
- **Phase 2 Prompt Templates**: context_recovery.md、command_mapping.md、error_recovery.md
- **Phase 2 SKILL.md**: 已定义 /gsd:* 触发模式

### Established Patterns
- **会话管理**: gsd-{project} 命名前缀，状态持久化到 ~/gsd-workspaces/
- **错误处理**: 中文错误消息 + 异常类（TmuxSessionError）
- **卡片布局**: 三区结构（标题区 + 内容区 + 操作区）
- **按钮交互**: CardButton dataclass，value 字段存储回调数据

### Integration Points
- orchestrator.py 是本 phase 的核心产出，将调用：
  - TmuxSessionManager（会话管理）
  - FeishuResponseFormatter（响应格式化）
  - StateManager（状态持久化）
- OpenClaw 通过 SKILL.md 加载技能，调用 orchestrator.py
- 本 phase 产出将被 Phase 4 的完整 GSD 命令支持使用

</code_context>

<deferred>
## Deferred Ideas

- 微信/Telegram/Discord 频道支持（Phase 2 已 defer，本 phase 仍仅飞书）
- 多语言支持（中文/英文切换）
- 命令历史记录和搜索
- 批量命令执行

</deferred>

---

*Phase: 03-orchestration*
*Context gathered: 2026-03-11*