docs(04): capture phase context
This commit is contained in:
@@ -0,0 +1,126 @@
|
||||
# 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*
|
||||
Reference in New Issue
Block a user